diff --git a/.github/workflows/README.md b/.github/workflows/README.md
index a25fd89f..c2198b8d 100644
--- a/.github/workflows/README.md
+++ b/.github/workflows/README.md
@@ -11,10 +11,12 @@ existing unbounded-tech quality provider plus the integration/* jobs below —
 |----------|-----------------|----------|
 | [`quality.yaml`](./quality.yaml) | yes | **Consumers:** fmt → clippy → build → test + coverage (sticky PR comment) |
 | [`test-all-features.yaml`](./test-all-features.yaml) | yes | **This repo:** workspace `--all-features` |
-| [`integration-*.yaml`](./) | yes | **This repo:** broker / DB / CLI / observability |
+| [`integration-*.yaml`](./) | yes | **This repo:** broker / DB / CLI / observability / GraphQL identity+OIDC |
+| [`integration-e2e-ui.yaml`](./integration-e2e-ui.yaml) | yes | **This repo:** `tests/e2e-ui` offline suite + Playwright browser e2e |
+| [`integration-js.yaml`](./integration-js.yaml) | yes | **This repo:** install, typecheck, test, build, and packed-consumer smoke test for `js/` |
 | [`on-pr-quality.yaml`](./on-pr-quality.yaml) | entry | **This repo** PR gate (not the consumer quality contract) |
 | [`on-push-main-version-and-tag.yaml`](./on-push-main-version-and-tag.yaml) | entry | **This repo** main → **vnext** tag |
-| [`on-v-tag-publish.yaml`](./on-v-tag-publish.yaml) | entry | **This repo** crates.io + `dctl` binary release |
+| [`on-v-tag-publish.yaml`](./on-v-tag-publish.yaml) | entry | **This repo** crates.io + npm + `dctl` binary release |
 
 **Version tagging (anywhere):** `unbounded-tech/workflow-vnext-tag`  
 **GitHub Release only (domain crates):** `unbounded-tech/workflow-simple-release`
@@ -90,12 +92,46 @@ jobs:
 
 **Pinning:** prefer a released tag once cut (`@vX.Y.Z` or git SHA). During development of quality, `@feat/shared-workflows` is fine.
 
+## npm release setup
+
+Version tags publish the package under [`js/`](../../js/) to npm as
+`@hops-ops/distributed`. The tag must have the exact form `vX.Y.Z`; the workflow
+uses `X.Y.Z` for both `js/package.json` and `js/package-lock.json`, runs the same
+package quality gate used on pull requests, and publishes with npm provenance.
+
+Configure an npm **Trusted Publisher** for `@hops-ops/distributed` with these
+exact GitHub Actions coordinates:
+
+- Organization or user: `hops-ops`
+- Repository: `distributed`
+- Workflow filename: `on-v-tag-publish.yaml`
+- Environment: `npm`
+- Allowed action: `npm publish`
+
+Trusted Publisher configuration is available only after the npm package exists.
+One-time bootstrap (already completed for this repo):
+
+1. Publish a throwaway non-release version such as `0.0.0` for
+   `@hops-ops/distributed` on the public npm registry.
+2. Configure the npm Trusted Publisher using the exact coordinates above
+   (`npm trust github @hops-ops/distributed --file on-v-tag-publish.yaml
+   --repo hops-ops/distributed --env npm --allow-publish`).
+3. Create the GitHub `npm` deployment environment (optional protection rules:
+   tag pattern `v*`, required reviewers).
+
+Release preflight validates the tag form and that `@hops-ops/distributed`
+exists on the public registry before any npm or crates.io write starts. Tagged
+npm releases authenticate through GitHub Actions OIDC. The workflow
+intentionally has job-scoped `id-token: write`, uses npm 11.5.1 or newer, and
+does **not** require or accept a long-lived `NPM_TOKEN` repository secret.
+
 ## Why this monorepo doesn’t call `quality.yaml`
 
 The framework workspace needs a different gate: default-features tests via
 unbounded quality (or similar), plus **all-features**, Postgres/NATS/Kafka/…
-integrations, and CLI/observability jobs. Consumer domain crates are single
-packages (or small libs) and only need the reusable quality contract.
+integrations, CLI/observability, and GraphQL identity/OIDC jobs. Consumer
+domain crates are single packages (or small libs) and only need the reusable
+quality contract.
 
 ## Out of scope (for now)
 
diff --git a/.github/workflows/integration-e2e-ui.yaml b/.github/workflows/integration-e2e-ui.yaml
new file mode 100644
index 00000000..5eed91a3
--- /dev/null
+++ b/.github/workflows/integration-e2e-ui.yaml
@@ -0,0 +1,182 @@
+name: e2e-ui fixture (offline + browser)
+
+# Nested Todos template under tests/e2e-ui — not the root workspace.
+# Local parity:
+#   cd tests/e2e-ui && make check-client
+#   cd tests/e2e-ui && make test
+#   cd tests/e2e-ui && make up && make run   # then make test-browser
+on:
+  workflow_call:
+
+env:
+  CARGO_TERM_COLOR: always
+  # Playwright / Auth.js over HTTP on localhost
+  CI: true
+
+jobs:
+  offline:
+    name: e2e-ui offline (domain + suite + UI unit)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: tests/e2e-ui
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          persist-credentials: false
+
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8
+        with:
+          toolchain: stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: tests/e2e-ui -> target
+          shared-key: e2e-ui-offline
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: |
+            js/package-lock.json
+            tests/e2e-ui/ui/package-lock.json
+
+      - name: Verify generated client artifacts
+        run: make check-client
+
+      - name: Offline test suite
+        run: make test
+
+  browser:
+    name: e2e-ui Playwright (live stack)
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    defaults:
+      run:
+        working-directory: tests/e2e-ui
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          persist-credentials: false
+
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8
+        with:
+          toolchain: stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: tests/e2e-ui -> target
+          shared-key: e2e-ui-browser
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: |
+            js/package-lock.json
+            tests/e2e-ui/package-lock.json
+            tests/e2e-ui/ui/package-lock.json
+
+      - name: Install host tools
+        run: sudo apt-get update && sudo apt-get install -y jq openssl curl
+
+      - name: Docker stack + OIDC bootstrap (make up)
+        run: |
+          chmod +x scripts/up.sh
+          make up
+
+      - name: Build e2e-ui API binary
+        run: cargo build -p e2e-runner --bin e2e-ui
+
+      - name: Install UI deps
+        run: make ui-install
+
+      - name: Start API + UI
+        run: |
+          set -euo pipefail
+          set -a
+          # shellcheck disable=SC1091
+          . ./e2e-ui.env
+          set +a
+          export AUTH_URL="${E2E_UI_ORIGIN:-http://localhost:5180}"
+          export AUTH_USE_SECURE_COOKIES=false
+          export AUTH_TRUST_HOST=true
+
+          ./target/debug/e2e-ui > .make-runner.log 2>&1 &
+          echo $! > .make-runner.pid
+
+          ok=0
+          for i in $(seq 1 90); do
+            code=$(curl -s -o /dev/null -w '%{http_code}' -X POST "http://127.0.0.1:8791/graphql" \
+              -H 'content-type: application/json' \
+              -d '{"query":"{ __typename }"}' 2>/dev/null || echo 000)
+            if [ "$code" = "200" ] || [ "$code" = "401" ]; then ok=1; break; fi
+            sleep 0.5
+          done
+          if [ "$ok" != "1" ]; then
+            echo "API failed to become ready"; tail -100 .make-runner.log; exit 1
+          fi
+          echo "API ready (HTTP $code)"
+
+          cd ui
+          npm run dev -- --host localhost --port 5180 > ../.make-ui.log 2>&1 &
+          echo $! > ../.make-ui.pid
+          cd ..
+
+          ok=0
+          for i in $(seq 1 60); do
+            code=$(curl -s -o /dev/null -w '%{http_code}' "http://localhost:5180/" 2>/dev/null || echo 000)
+            # 200 home, or 303 redirect when auth wraps routes — not 000/5xx
+            if [ "$code" = "200" ] || [ "$code" = "303" ] || [ "$code" = "302" ]; then ok=1; break; fi
+            sleep 0.5
+          done
+          if [ "$ok" != "1" ]; then
+            echo "UI failed to become ready (last HTTP $code)"; tail -80 .make-ui.log; exit 1
+          fi
+          echo "UI ready (HTTP $code)"
+
+      - name: Install Playwright + Chromium
+        run: |
+          npm install
+          npx playwright install chromium --with-deps
+
+      - name: Run browser e2e
+        run: npm run test:browser
+        env:
+          E2E_UI_ORIGIN: http://localhost:5180
+          E2E_API_ORIGIN: http://127.0.0.1:8791
+          CI: true
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-ui-playwright-report
+          path: |
+            tests/e2e-ui/playwright-report
+            tests/e2e-ui/test-results
+          if-no-files-found: ignore
+          retention-days: 7
+
+      - name: Dump logs on failure
+        if: failure()
+        run: |
+          echo '=== API log ==='
+          tail -150 .make-runner.log || true
+          echo '=== UI log ==='
+          tail -80 .make-ui.log || true
+          docker compose -f docker/docker-compose.yml ps -a || true
+          docker compose -f docker/docker-compose.yml logs --tail=100 || true
+
+      - name: Stop API/UI
+        if: always()
+        run: |
+          [ -f .make-ui.pid ] && kill "$(cat .make-ui.pid)" 2>/dev/null || true
+          [ -f .make-runner.pid ] && kill "$(cat .make-runner.pid)" 2>/dev/null || true
+          lsof -ti:8791 2>/dev/null | xargs -r kill -9 2>/dev/null || true
+          lsof -ti:5180 2>/dev/null | xargs -r kill -9 2>/dev/null || true
+
+      - name: Tear down Docker
+        if: always()
+        run: docker compose -f docker/docker-compose.yml down -v || true
diff --git a/.github/workflows/integration-graphql.yaml b/.github/workflows/integration-graphql.yaml
new file mode 100644
index 00000000..e231ee02
--- /dev/null
+++ b/.github/workflows/integration-graphql.yaml
@@ -0,0 +1,158 @@
+name: GraphQL Identity / OIDC Integration Tests
+
+# Reusable workflow: wired from on-pr-quality and on-push-main.
+#
+# - identity-always-on: mock JWKS F1–F10 + offline OIDC suite matrix (no IdP)
+# - oidc-zitadel-e2e: live Zitadel compose + JWT-bearer mint
+# - oidc-keycloak-e2e: live Keycloak compose + client_credentials
+# - oidc-authentik-e2e: live Authentik compose + client_credentials
+#
+# Local parity:
+#   ./scripts/oidc-{zitadel,keycloak,authentik}-up.sh
+#   set -a && source graphql-oidc[-keycloak|-authentik].env && set +a
+#   cargo test --test graphql_oidc_<provider> --features graphql,sqlite,metrics
+on:
+  workflow_call:
+
+jobs:
+  identity-always-on:
+    name: GraphQL Identity + offline OIDC matrix
+    runs-on: ubuntu-latest
+    env:
+      CARGO_TERM_COLOR: always
+      # Explicitly clear live gates so matrix cannot accidentally run live paths
+      ZITADEL_E2E: ""
+      KEYCLOAK_E2E: ""
+      AUTHENTIK_E2E: ""
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8
+        with:
+          toolchain: stable
+      - name: Always-on identity suite (no IdP)
+        run: |
+          cargo test --test graphql_identity --features graphql,sqlite,metrics --verbose
+      - name: Offline OIDC provider matrix (all skip cleanly without gates)
+        run: |
+          cargo test \
+            --test graphql_oidc_zitadel \
+            --test graphql_oidc_keycloak \
+            --test graphql_oidc_authentik \
+            --features graphql,sqlite,metrics --verbose
+
+  oidc-zitadel-e2e:
+    name: GraphQL OIDC Zitadel e2e (live)
+    runs-on: ubuntu-latest
+    env:
+      CARGO_TERM_COLOR: always
+      ZITADEL_HOST: http://localhost:8080
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8
+        with:
+          toolchain: stable
+      - name: Install bootstrap tools
+        run: sudo apt-get update && sudo apt-get install -y jq openssl curl
+      - name: Start Zitadel + bootstrap (docker compose)
+        run: |
+          chmod +x scripts/oidc-zitadel-up.sh scripts/ci-bootstrap-graphql-oidc.sh
+          ./scripts/oidc-zitadel-up.sh
+      - name: Run live Zitadel e2e suite
+        run: |
+          set -a
+          # shellcheck disable=SC1091
+          source graphql-oidc.env
+          set +a
+          test -n "${ZITADEL_E2E:-}"
+          test -n "${OIDC_ISSUER:-}"
+          test -n "${GRAPHQL_E2E_CUSTOMER_KEY:-}"
+          echo "ZITADEL_E2E=$ZITADEL_E2E OIDC_ISSUER=$OIDC_ISSUER"
+          cargo test --test graphql_oidc_zitadel --features graphql,sqlite,metrics --verbose -- --nocapture
+      - name: Dump Zitadel logs on failure
+        if: failure()
+        run: |
+          docker compose -f tests/graphql_oidc_zitadel/docker-compose.yml ps -a || true
+          docker compose -f tests/graphql_oidc_zitadel/docker-compose.yml logs --tail=200 || true
+          ls -la tests/graphql_oidc_zitadel/machinekey || true
+      - name: Tear down
+        if: always()
+        run: docker compose -f tests/graphql_oidc_zitadel/docker-compose.yml down -v || true
+
+  oidc-keycloak-e2e:
+    name: GraphQL OIDC Keycloak e2e (live)
+    runs-on: ubuntu-latest
+    env:
+      CARGO_TERM_COLOR: always
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8
+        with:
+          toolchain: stable
+      - name: Install tools
+        run: sudo apt-get update && sudo apt-get install -y curl python3
+      - name: Start Keycloak + bootstrap
+        run: |
+          chmod +x scripts/oidc-keycloak-up.sh
+          ./scripts/oidc-keycloak-up.sh
+      - name: Run live Keycloak e2e suite
+        run: |
+          set -a
+          # shellcheck disable=SC1091
+          source graphql-oidc-keycloak.env
+          set +a
+          test -n "${KEYCLOAK_E2E:-}"
+          test -n "${OIDC_ISSUER:-}"
+          echo "KEYCLOAK_E2E=$KEYCLOAK_E2E OIDC_ISSUER=$OIDC_ISSUER OIDC_AUDIENCE=$OIDC_AUDIENCE"
+          cargo test --test graphql_oidc_keycloak --features graphql,sqlite,metrics --verbose -- --nocapture
+      - name: Dump Keycloak logs on failure
+        if: failure()
+        run: |
+          docker compose -f tests/graphql_oidc_keycloak/docker-compose.yml ps -a || true
+          docker compose -f tests/graphql_oidc_keycloak/docker-compose.yml logs --tail=200 || true
+      - name: Tear down
+        if: always()
+        run: docker compose -f tests/graphql_oidc_keycloak/docker-compose.yml down -v || true
+
+  oidc-authentik-e2e:
+    name: GraphQL OIDC Authentik e2e (live)
+    runs-on: ubuntu-latest
+    env:
+      CARGO_TERM_COLOR: always
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8
+        with:
+          toolchain: stable
+      - name: Install tools
+        run: sudo apt-get update && sudo apt-get install -y curl python3
+      - name: Start Authentik + bootstrap
+        run: |
+          chmod +x scripts/oidc-authentik-up.sh
+          ./scripts/oidc-authentik-up.sh
+      - name: Run live Authentik e2e suite
+        run: |
+          set -a
+          # shellcheck disable=SC1091
+          source graphql-oidc-authentik.env
+          set +a
+          test -n "${AUTHENTIK_E2E:-}"
+          test -n "${OIDC_ISSUER:-}"
+          test -n "${OIDC_JWKS_URI:-}"
+          echo "AUTHENTIK_E2E=$AUTHENTIK_E2E OIDC_ISSUER=$OIDC_ISSUER"
+          cargo test --test graphql_oidc_authentik --features graphql,sqlite,metrics --verbose -- --nocapture
+      - name: Dump Authentik logs on failure
+        if: failure()
+        run: |
+          docker compose -f tests/graphql_oidc_authentik/docker-compose.yml ps -a || true
+          docker compose -f tests/graphql_oidc_authentik/docker-compose.yml logs --tail=200 || true
+      - name: Tear down
+        if: always()
+        run: docker compose -f tests/graphql_oidc_authentik/docker-compose.yml down -v || true
diff --git a/.github/workflows/integration-js.yaml b/.github/workflows/integration-js.yaml
new file mode 100644
index 00000000..c89253d3
--- /dev/null
+++ b/.github/workflows/integration-js.yaml
@@ -0,0 +1,37 @@
+name: Distributed JS client quality
+
+# Reusable workflow for the publishable package under js/.
+# Local parity: cd js && npm ci && npm run quality
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Distributed JS client quality (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: ["20", "24"]
+    defaults:
+      run:
+        working-directory: js
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+          cache-dependency-path: js/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run package quality checks
+        run: npm run quality
diff --git a/.github/workflows/integration-postgres.yaml b/.github/workflows/integration-postgres.yaml
index d05a8c6b..ace6a44a 100644
--- a/.github/workflows/integration-postgres.yaml
+++ b/.github/workflows/integration-postgres.yaml
@@ -40,6 +40,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libcurl4-openssl-dev
       - name: Run Postgres integration tests
         run: |
+          cargo test --lib --features postgres postgres_command_ledger_adapter_conformance_when_database_available --verbose
           cargo test --test postgres_repository --all-features --verbose
           cargo test --test postgres_repository_conformance --all-features --verbose
           cargo test --test postgres_transport --all-features --verbose
diff --git a/.github/workflows/on-pr-quality.yaml b/.github/workflows/on-pr-quality.yaml
index 6554029a..22046ce3 100644
--- a/.github/workflows/on-pr-quality.yaml
+++ b/.github/workflows/on-pr-quality.yaml
@@ -34,3 +34,12 @@ jobs:
 
   observability:
     uses: ./.github/workflows/integration-observability.yaml
+
+  graphql:
+    uses: ./.github/workflows/integration-graphql.yaml
+
+  e2e-ui:
+    uses: ./.github/workflows/integration-e2e-ui.yaml
+
+  js-client:
+    uses: ./.github/workflows/integration-js.yaml
diff --git a/.github/workflows/on-push-main-version-and-tag.yaml b/.github/workflows/on-push-main-version-and-tag.yaml
index eaf40616..80b1ee2e 100644
--- a/.github/workflows/on-push-main-version-and-tag.yaml
+++ b/.github/workflows/on-push-main-version-and-tag.yaml
@@ -40,11 +40,20 @@ jobs:
   observability:
     uses: ./.github/workflows/integration-observability.yaml
 
+  graphql:
+    uses: ./.github/workflows/integration-graphql.yaml
+
+  e2e-ui:
+    uses: ./.github/workflows/integration-e2e-ui.yaml
+
+  js-client:
+    uses: ./.github/workflows/integration-js.yaml
+
   # This uses commit logs and tags from git to determine the next version number and create a tag for the release.
   # Some commits such as chore: will not trigger a version bump and tag; this is by design.
   version-and-tag:
     name: Version and Tag
-    needs: [quality, all-features, postgres, nats, rabbitmq, kafka, distributed-cli, observability]
+    needs: [quality, all-features, postgres, nats, rabbitmq, kafka, distributed-cli, observability, graphql, e2e-ui, js-client]
     uses: unbounded-tech/workflow-vnext-tag/.github/workflows/workflow.yaml@v1.21.5
     secrets:
       DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
diff --git a/.github/workflows/on-v-tag-publish.yaml b/.github/workflows/on-v-tag-publish.yaml
index 409cd963..7be814a0 100644
--- a/.github/workflows/on-v-tag-publish.yaml
+++ b/.github/workflows/on-v-tag-publish.yaml
@@ -1,4 +1,4 @@
-name: On Version Tagged, Publish Crates and CLI Artifacts
+name: On Version Tagged, Publish Packages and CLI Artifacts
 
 on:
   push:
@@ -9,7 +9,30 @@ permissions:
   contents: read
 
 jobs:
+  # Fail closed before crates publish if the public npm package is missing.
+  release-preflight:
+    name: Verify release registries are ready
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate release tag
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          if [[ ! "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Expected a release tag in vX.Y.Z form, got: $RELEASE_TAG" >&2
+            exit 1
+          fi
+
+      - name: Verify npm package exists
+        run: |
+          package_name="$(npm view @hops-ops/distributed name)"
+          if [[ "$package_name" != "@hops-ops/distributed" ]]; then
+            echo "Expected @hops-ops/distributed on npm, got: $package_name" >&2
+            exit 1
+          fi
+
   publish-macros:
+    needs: release-preflight
     uses: unbounded-tech/workflows-rust/.github/workflows/publish.yaml@feat/cargo-publish
     secrets:
       crates_io_token: ${{ secrets.CRATES_IO_TOKEN }}
@@ -20,6 +43,7 @@ jobs:
   # distributed_cli (the `dctl` binary + generation library) has no internal
   # workspace dependencies, so it publishes independently of the macros/core crates.
   publish-cli:
+    needs: release-preflight
     uses: unbounded-tech/workflows-rust/.github/workflows/publish.yaml@feat/cargo-publish
     secrets:
       crates_io_token: ${{ secrets.CRATES_IO_TOKEN }}
@@ -36,10 +60,58 @@ jobs:
       manifest_path: Cargo.toml
       cargo_publish_args: "--locked"
 
-  # `publish` waits for the macros crate, while `publish-cli` is independent.
-  # Gate binary artifacts on both so all three crates publish first.
+  publish-js:
+    name: Publish Distributed JS client to npm
+    needs: release-preflight
+    runs-on: ubuntu-latest
+    environment: npm
+    permissions:
+      contents: read
+      id-token: write
+    defaults:
+      run:
+        working-directory: js
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: https://registry.npmjs.org
+
+      # npm trusted publishing requires npm CLI 11.5.1 or newer.
+      - name: Install npm with trusted publishing support
+        run: npm install --global npm@11.5.1
+
+      - name: Derive package version from release tag
+        id: release
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          if [[ ! "$RELEASE_TAG" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+            echo "Expected a release tag in vX.Y.Z form, got: $RELEASE_TAG" >&2
+            exit 1
+          fi
+          echo "version=${BASH_REMATCH[1]}" >> "$GITHUB_OUTPUT"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Apply release version to package metadata
+        run: npm version "${{ steps.release.outputs.version }}" --no-git-tag-version --allow-same-version
+
+      - name: Run package quality checks
+        run: npm run quality
+
+      - name: Publish package with provenance
+        run: npm publish --provenance --access public
+
+  # `publish` waits for the macros crate; the CLI and JS package are independent.
+  # Gate binary artifacts on every package publication.
   release:
-    needs: [publish, publish-cli]
+    needs: [publish, publish-cli, publish-js]
     permissions:
       contents: write
     uses: unbounded-tech/workflows-rust/.github/workflows/release.yaml@v2.3.0
diff --git a/.gitignore b/.gitignore
index 34b6c47c..3f13a57a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,3 +31,23 @@ target/llvm-cov/
 
 .claude/worktrees
 .dispatch-prefetch
+graphql-oidc.env
+
+# ATC agent local cache (PR review prefetch)
+.dispatch-prefetch/
+
+# Make recipe PID/log files (e2e-ui already ignores under its dir)
+.make-*
+**/.make-*
+
+# OIDC e2e local secrets / generated env (never commit)
+graphql-oidc.env
+graphql-oidc-keycloak.env
+graphql-oidc-authentik.env
+tests/graphql_oidc_zitadel/machinekey/**
+!tests/graphql_oidc_zitadel/machinekey/.gitignore
+tests/workshop-service/ui/node_modules/
+tests/workshop-service/ui/build/
+tests/workshop-service/ui/.svelte-kit/
+tests/workshop-service/**/target/
+tests/workshop-service/*.db
diff --git a/Cargo.toml b/Cargo.toml
index 7c36648c..ef73ccb0 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,5 +1,6 @@
 [workspace]
 members = ["distributed_macros", "distributed_cli"]
+exclude = ["tests/e2e-ui"]
 resolver = "2"
 
 [workspace.package]
@@ -26,48 +27,62 @@ categories = ["data-structures", "database"]
 [lib]
 path = "src/lib.rs"
 
+[[example]]
+name = "graphiql"
+path = "examples/graphiql.rs"
+required-features = ["graphql", "sqlite"]
+
 [features]
 default = []
 emitter = ["dep:event-emitter-rs"]
 metrics = []
 http = ["dep:axum", "dep:reqwest", "dep:tokio"]
 grpc = ["dep:tonic", "dep:tonic-prost", "dep:prost", "dep:tokio"]
-postgres = ["dep:sqlx", "dep:tokio", "sqlx/postgres", "sqlx/migrate", "sqlx/runtime-tokio"]
-sqlite = ["dep:sqlx", "dep:tokio", "sqlx/migrate", "sqlx/runtime-tokio", "sqlx/sqlite"]
+postgres = ["dep:sqlx", "dep:tokio", "sqlx/postgres", "sqlx/migrate", "sqlx/runtime-tokio", "sqlx/json"]
+sqlite = ["dep:sqlx", "dep:tokio", "sqlx/migrate", "sqlx/runtime-tokio", "sqlx/sqlite", "sqlx/json"]
 nats = ["dep:async-nats", "dep:futures", "dep:tokio"]
 rabbitmq = ["dep:lapin", "dep:futures", "dep:tokio"]
 kafka = ["dep:rdkafka", "dep:tokio"]
 otel = ["dep:opentelemetry", "dep:opentelemetry_sdk", "dep:tracing", "dep:tracing-opentelemetry"]
+graphql = ["dep:async-graphql", "dep:async-graphql-axum", "dep:hmac", "dep:jsonwebtoken", "http", "axum?/ws"]
 
 [dependencies]
 async-nats = { version = "0.49", optional = true }
+async-graphql = { version = "7", optional = true }
+async-graphql-axum = { version = "7", optional = true }
 axum = { version = "0.8", optional = true }
 base64 = "0.22.1"
 futures = { version = "0.3", optional = true }
 lapin = { version = "4", optional = true }
 rdkafka = { version = "0.39", features = ["cmake-build", "tokio"], optional = true }
-reqwest = { version = "0.13", default-features = false, optional = true }
+reqwest = { version = "0.13", default-features = false, features = ["rustls"], optional = true }
+jsonwebtoken = { version = "9", optional = true }
 bitcode = { version = "0.6.9", features = ["serde"] }
 event-emitter-rs = { version = "0.1.4", optional = true }
 futures-util = { version = "0.3", default-features = false, features = ["alloc"] }
+hmac = { version = "0.12", optional = true }
 opentelemetry = { version = "0.32", default-features = false, features = ["trace"], optional = true }
 opentelemetry_sdk = { version = "0.32", default-features = false, features = ["trace"], optional = true }
 serde = { version = "1.0.210", features = ["derive"] }
 serde_json = "1.0.128"
+sha2 = "0.10"
 distributed_macros = { workspace = true }
 sqlx = { version = "0.9", default-features = false, optional = true }
 tonic = { version = "0.14", default-features = false, features = ["router", "transport", "codegen"], optional = true }
 tonic-prost = { version = "0.14", optional = true }
 prost = { version = "0.14", optional = true }
-tokio = { version = "1", features = ["rt-multi-thread", "net", "macros", "time"], optional = true }
+tokio = { version = "1", features = ["rt-multi-thread", "net", "macros", "time", "sync"], optional = true }
 tracing = { version = "0.1", optional = true }
 tracing-opentelemetry = { version = "0.33", default-features = false, optional = true }
+uuid = { version = "1", features = ["v7"] }
 
 [build-dependencies]
 tonic-build = { version = "0.14", default-features = false, features = ["transport"] }
 
 [dev-dependencies]
 axum = "0.8"
+tower = { version = "0.5", features = ["util"] }
+http-body-util = "0.1"
 # OTLP export e2e (tests/otel_export): a real SDK pipeline pointed at a
 # collector container, exercising the `otel` feature the way a service binary
 # would. Keep versions in lockstep with the optional `otel` feature deps.
@@ -77,6 +92,9 @@ proptest = "1"
 prost = "0.14"
 reqwest = { version = "0.13", features = ["json"] }
 serde_json = "1.0"
-tokio = { version = "1", features = ["full"] }
+tokio = { version = "1", features = ["full", "test-util"] }
 tokio-stream = "0.1"
+tokio-tungstenite = "0.29"
 tonic = { version = "0.14", default-features = false, features = ["router", "transport", "codegen"] }
+rsa = "0.9"
+rand = "0.8"
diff --git a/README.md b/README.md
index 7ba21be7..6d2bf0bf 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,99 @@
 # Distributed
 
-Distributed is a CQRS and event-sourcing framework for Rust applications that want simple domain models, replayable aggregate history, durable publication, and pluggable infrastructure.
+**Event-sourced Rust backends. Deny-by-default GraphQL with first-class OIDC.
+A causal TypeScript replica for real apps.** One platform from aggregate tests
+to SvelteKit SSR.
 
-It keeps your domain model as a plain struct (Plain Old Rust Struct, or PORS), inspired by POCO/POJO, while giving you append-only aggregate event records, replay, snapshots, read models, an outbox, a multi-transport service bus, and a small async command-handler framework.
+Plain domain structs on the write side. Relational read models on the query
+side. The GraphQL edge validates Bearer tokens (JWKS) and maps claims into
+session roles/RLS — not a bolted-on middleware afterthought. The browser talks
+**one protocol** — GraphQL queries, live subscriptions, and typed command
+mutations — through `@hops-ops/distributed`.
 
-The core idea is explicit boundaries: aggregate event records are the write-side source of truth, read models serve queries, and published domain or integration messages are created deliberately through the outbox.
+---
 
-It is built with stateless vertical and horizontal scaling in cloud-native environments in mind. You can start with a single in-memory service and split it later into partitioned services backed by Postgres and a real broker — without rewriting the domain model.
+## See it run
+
+### e2e-ui — read the code (`tests/e2e-ui`)
+
+A copyable multi-crate product: pure domains, GraphQL-only edge, Zitadel OIDC,
+SvelteKit SSR, generated clients, live WS. Full runbook + deeper map:
+**[`tests/e2e-ui/README.md`](tests/e2e-ui/README.md)**.
+
+```bash
+cd tests/e2e-ui && make up && set -a && source e2e-ui.env && set +a && make run
+# UI :5180 · API :8791/graphql · login alice / Password1!
+```
+
+What makes it feel like a real app is not a second framework — it is a short
+stack of deliberate files. Start here:
+
+| File | Why it is nice |
+|---|---|
+| [`ui/src/routes/todos/+page.graphql`](tests/e2e-ui/ui/src/routes/todos/+page.graphql) | Co-located read. `@load` → SSR seed; no hand-written load function for the list. |
+| [`ui/src/routes/todos/+page.svelte`](tests/e2e-ui/ui/src/routes/todos/+page.svelte) | `Todos.use()` + `useCommands()` — page never invents a cache or optimistic recipe. |
+| [`ui/src/routes/chat/+page.graphql`](tests/e2e-ui/ui/src/routes/chat/+page.graphql) | Same document does SSR **and** live: `@load @live`. No second subscription file. |
+| [`ui/src/routes/blob/[[gameId]]/+page.svelte`](tests/e2e-ui/ui/src/routes/blob/[[gameId]]/+page.svelte) | Arrow keys → `commands.blob.move`; board from `BlobGames.use()` — projected payload hits the replica before the call resolves. |
+| [`ui/src/routes/+layout.server.ts`](tests/e2e-ui/ui/src/routes/+layout.server.ts) | One root loader, generated route registry, session → engine role. No loading flash for declared ops. |
+| [`ui/src/routes/+layout.svelte`](tests/e2e-ui/ui/src/routes/+layout.svelte) | `provideDistributed` + SSR hydration into the causal replica. |
+| [`ui/src/routes/admin/+layout.server.ts`](tests/e2e-ui/ui/src/routes/admin/+layout.server.ts) | Elevated surface is a **second** generated client + role gate — not smuggled into the user bundle. |
+| [`crates/service/src/service.rs`](tests/e2e-ui/crates/service/src/service.rs) | Inventory, RLS (`owner_id = claim(x-user-id)`), dual client surfaces (`e2e-ui` / `e2e-ui-admin`), OIDC claim map. |
+| [`crates/service/src/handlers/commands/blob_move.rs`](tests/e2e-ui/crates/service/src/handlers/commands/blob_move.rs) | `PreparedCommand<Projected<BlobGameView>>` — map/score written with the event, not dual-written later. |
+| [`crates/todo-domain/src/models/todo.rs`](tests/e2e-ui/crates/todo-domain/src/models/todo.rs) | Plain aggregate: `create` / `ensure_owner` / `@sourced` events — no GraphQL in the domain. |
+| [`crates/readmodels/src/models/blob_game_view.rs`](tests/e2e-ui/crates/readmodels/src/models/blob_game_view.rs) | `#[table]` + `belongs_to` owner join — GraphQL shape from the read model. |
+| [`ui/src/auth.ts`](tests/e2e-ui/ui/src/auth.ts) | Real Auth.js + Zitadel scopes/groups → engine roles. |
+
+```text
+  SvelteKit  ──GraphQL HTTP/WS──►  Rust edge (GraphqlEngine + microsvc)
+       │                                │
+       │  @hops-ops/distributed         ├── mutations → aggregates
+       │  causal replica + commands     ├── Projected rows (blob) with events
+       │  dctl-generated ops            └── projector rows (todos, chat)
+```
+
+JS package deep-dive: [`js/README.md`](js/README.md).
+
+### GraphiQL playground (engine only)
+
+```bash
+cargo run --example graphiql --features "graphql,sqlite"
+# → http://127.0.0.1:4000/graphql
+```
+
+### First-class OIDC (Zitadel, Keycloak, Authentik)
+
+GraphQL identity is **built into the engine** (`OidcBearer`: JWKS, iss/aud/exp,
+claim → role/session). Live against three local IdPs — not mocks only:
+
+| Provider | Compose + bootstrap | Live test | Gate |
+|---|---|---|---|
+| **[Zitadel](tests/graphql_oidc_zitadel/)** (reference) | `./scripts/oidc-zitadel-up.sh` | `cargo test --test graphql_oidc_zitadel --features graphql,sqlite` | `ZITADEL_E2E=1` |
+| **[Keycloak](tests/graphql_oidc_keycloak/)** | `./scripts/oidc-keycloak-up.sh` | `cargo test --test graphql_oidc_keycloak --features graphql,sqlite` | `KEYCLOAK_E2E=1` |
+| **[Authentik](tests/graphql_oidc_authentik/)** | `./scripts/oidc-authentik-up.sh` | `cargo test --test graphql_oidc_authentik --features graphql,sqlite` | `AUTHENTIK_E2E=1` |
+
+Shared **E1–E8** in [`tests/graphql_oidc_common/`](tests/graphql_oidc_common/).
+Gated binaries skip cleanly when unset. Offline: `cargo test --test graphql_identity --features graphql,sqlite`.
+
+e2e-ui boots **Zitadel** for the browser path; the three stacks prove the same
+`OidcBearer` edge is not vendor-locked.
+
+---
 
 ## At a Glance
 
 | Capability | What it gives you |
 |---|---|
-| Plain Rust aggregates | Domain state stays in ordinary structs with explicit command methods. |
-| Model-first TDD | Specify the aggregate API in fast, exhaustive unit tests before writing handlers or choosing infrastructure. |
-| Event-sourced persistence | Append-only `EventRecord`s, replay, optimistic commit, and pluggable async repositories. |
-| Typed macros | `#[sourced]`, `#[digest]`, and `aggregate!()` remove boilerplate while keeping replay explicit. |
-| Snapshots | `#[derive(Snapshot)]` and a snapshot cache speed up hydration for long streams. |
-| Outbox | Durable publication records committed atomically with aggregates. |
-| Read models | Query-optimized relational projections, committed atomically or updated eventually. |
-| Service bus facade | `send`/`listen` (point-to-point) and `publish`/`subscribe` (fan-out) over a swappable transport. |
-| Transports | In-memory, SQLite, Postgres, NATS JetStream, RabbitMQ, Kafka, and Knative/CloudEvents — one constructor line apart. |
-| Microservice framework | Convention-based async handlers exposed over HTTP, gRPC, the bus, or direct dispatch. |
-| Service CLI | `dctl` scaffolds service crates, describes manifests, and renders SQL or Atlas schema artifacts. |
-| Pluggable infrastructure | Traits for storage, messaging, read models, snapshots, outbox publishing, and locking. |
+| **Full-stack path** | Rust domains → GraphQL edge → `@hops-ops/distributed` → SvelteKit/React |
+| **First-class OIDC** | Built-in `OidcBearer` (JWKS, claims → roles); live e2e for **Zitadel, Keycloak, Authentik** |
+| Plain Rust aggregates | Domain state in ordinary structs with explicit command methods |
+| Model-first TDD | Exhaustive unit tests before handlers or infrastructure |
+| Event-sourced persistence | Append-only records, replay, optimistic commit, pluggable async repos |
+| Outbox + multi-transport bus | Durable publish; swap in-memory / SQL / NATS / RabbitMQ / Kafka / Knative |
+| Read models | Relational projections — atomic with the command **or** eventual from projectors |
+| GraphQL query service | Filters, order, pagination, relationships, RBAC, live subs, causal mutations |
+| npm JS client | Artifacts, HTTP/WS transport, **causal replica**, diagnostics, SvelteKit/React |
+| microsvc | One handler inventory on HTTP, gRPC, bus, GraphQL, or direct dispatch |
+| `dctl` | Scaffold, SQL/Atlas/SDL, **client-manifest / client** codegen |
 
 ## Use as a Dependency
 
@@ -117,9 +187,10 @@ you are working on the macro crate itself. The `distributed_cli` crate installs
 the `dctl` tooling and is not needed as a runtime dependency unless you are
 embedding the CLI in another command such as `hops service`.
 
-## Quick Start
+## Quick Start (library)
 
-Five steps: specify the model API in tests, implement the model, add a thin
+Want the product demo first? Use [See it run](#see-it-run) above. This section is
+the minimal **in-crate** path: specify the model API in tests, implement the model, add a thin
 command handler, serve it, then swap in production persistence and transports
 without changing the proven domain behavior.
 
@@ -387,6 +458,14 @@ Distributed is inspired by the original [sourced](https://github.com/mateodelnor
 - Keep storage and messaging pluggable and testable behind async traits.
 - Make the transport a wiring choice, not a handler change.
 - Add optional queue-based locking for serialized workflows.
+- Expose a deny-by-default GraphQL edge over relational read models (not ad-hoc
+  handler SQL).
+- Ship **first-class OIDC** on that edge (`OidcBearer` + claim mapping), with
+  optional trusted-proxy modes — not “bring your own JWT middleware.”
+- Keep browser apps on one protocol: typed GraphQL queries, live subscriptions,
+  and causal command mutations with a normalized client replica.
+- Prefer generated client artifacts and explicit projection contracts over
+  hand-written fetch/cache glue.
 
 ## Feature Flags
 
@@ -399,6 +478,7 @@ network servers.
 | `emitter` | No | In-process event emission and `#[enqueue]`. |
 | `http` | No | Axum HTTP transport for `microsvc` + the Knative/CloudEvents ingress router. |
 | `grpc` | No | Tonic gRPC transport for `microsvc`. |
+| `graphql` | No | GraphQL query service over read models (pulls in `http` + WebSocket). Pair with `sqlite` and/or `postgres` for a dialect. |
 | `postgres` | No | `PostgresRepository` and the Postgres outbox/transport (`PostgresBus`). |
 | `sqlite` | No | `SqliteRepository` async SQL adapter and local durable transport (`SqliteBus`). |
 | `nats` | No | `NatsBus` (NATS JetStream source/publisher). |
@@ -423,8 +503,9 @@ network servers.
 - **OutboxMessage**: A durable publication work item for a domain event, integration event, command, or generic transport message. Supports optional `destination` for point-to-point routing and metadata propagation.
 - **OutboxDispatcher**: Drains durable outbox rows and publishes them to a transport, sharing one claim → publish → complete path.
 - **ReadModel**: Query-optimized relational projection state for UI/API reads. Read models may be updated atomically with a command or eventually from published messages.
+- **GraphqlEngine**: Deny-by-default GraphQL surface over registered read-model tables: role-scoped columns/row filters, optional command mutations, live subscriptions via `ChangeHub`, and identity modes (`OidcBearer`, `TrustedProxy`, `Hybrid`, `DevHeaders`).
 - **Bus / BusConsumer**: The service bus facade — `send`/`publish` (produce) and `listen`/`subscribe` (consume), implemented by a per-transport `*Bus` type.
-- **microsvc::Service**: Convention-based async command/event handler framework with pluggable transports (HTTP, gRPC, bus, direct dispatch).
+- **microsvc::Service**: Convention-based async command/event handler framework with pluggable transports (HTTP, gRPC, bus, GraphQL mutations, direct dispatch).
 
 ## Terminology And CQRS Boundaries
 
@@ -887,8 +968,25 @@ SQLite is the no-extra-process local durable path: one SQLite database can back
 repositories, read models, the outbox, locks, and `SqliteBus` for tests, demos,
 and small single-node deployments. Postgres is the low-ops starter for production:
 a single Postgres cluster can back repositories, read models, the outbox, **and**
-the durable transport (`PostgresBus`). See
-[`docs/repositories.md`](docs/repositories.md) for the full guide.
+the durable transport (`PostgresBus`).
+
+### Repository traits (async-only)
+
+Streams are keyed by full **stream identity** `(aggregate_type, aggregate_id)`,
+not bare IDs. Prefer an explicit durable `aggregate_type` in production
+(`impl_aggregate!(..., aggregate_type = "...")` or the sourced/aggregate macros).
+
+| Trait | Role |
+| --- | --- |
+| `GetStream` | Load one or more event streams by identity |
+| `TransactionalCommit` | Commit `CommitBatch` (streams, read-model write plans, snapshots) in one backend transaction |
+| `ReadModelWritePlanStore` / `RelationalReadModelQueryStore` | Relational projection write + PK load surfaces for adapters |
+| `SnapshotStore` | Rebuildable snapshot cache by stream identity |
+| `OutboxStore` | Claim/update durable outbox rows (workers; not aggregate rehydration) |
+
+`InMemoryRepository` (plus in-memory read-model/snapshot stores) is the behavioral
+reference for conformance tests — not a production I/O adapter. SQL adapters
+implement the same traits with `sqlx`.
 
 ## Outbox Pattern
 
@@ -1054,10 +1152,34 @@ bus.listen(
 Retryable failures (e.g. transient `NotFound`) are nacked for redelivery; the runner
 never silently acks a handler error.
 
-See [`docs/transports.md`](docs/transports.md) for the full transport
-layer, the two confirmation thresholds (producer publish vs consumer ack), and the
-low-level `MessageSource` / `MessagePublisher` / `run_source` boundary the
-facade is built on.
+### Transport boundaries (producer vs consumer)
+
+`microsvc` owns registration, guards, typed decoding, and dispatch. **Transport
+adapters** own receive/ack/retry/publish and topic mapping. Shared vocabulary lives
+in `bus` (no concrete broker dependency).
+
+| Type | Purpose |
+| --- | --- |
+| `TransportError` / `TransportErrorKind` | Retryable vs permanent — drives redelivery vs failure policy |
+| `FailurePolicy` / `FailureAction` | Permanent failure: `Retry`, `DeadLetter`, `Park`, `LogAndAck`, `Stop` |
+| `RunOptions` / `ConsumerDeliveryMode` | Idempotent dispatch by default; optional inbox hook |
+| `TransportCapabilities` | Per-transport durability, confirms, retry ownership, ack kind |
+| `MessageSource` + `run_source` | Pull loop: dispatch then settle only after the handler finishes |
+| `MessagePublisher` + `OutboxDispatcher` | Publish threshold for outbox completion; claim → publish → complete |
+
+**Two confirmation thresholds** (do not collapse them):
+
+1. **Producer publish** — when an outbox row may be marked published (SQL commit,
+   broker confirm/ack, Knative 2xx, in-memory accept). Unknown outcomes stay retryable.
+2. **Consumer ack** — only after the handler (and optional inbox receipt) committed.
+   Never silently ack a handler error.
+
+```rust,ignore
+use distributed::bus::{run_source, RunOptions};
+
+// Low-level receive loop (facade buses wrap this)
+run_source(service, source, RunOptions::idempotent()).await?;
+```
 
 ## Microservice Framework (`microsvc`)
 
@@ -1364,7 +1486,295 @@ let loaded = repo
     .await?;
 ```
 
-See [`docs/read-models.md`](docs/read-models.md) for the full guide, including relational metadata, schema bootstrap, relationship includes, distributed idempotency, and non-goals.
+### Relational metadata, includes, and schema
+
+- **Derive:** `#[derive(ReadModel)]` + `#[table("...")]` (or `#[readmodel(table = "...")]`)
+  emit `RelationalReadModel` metadata, row conversion, PKs, indexes, FKs, and an
+  adapter-owned version column. Use `#[id]`, `#[index]` / `#[unique]`,
+  `#[readmodel(jsonb)]`, and relationship attributes (`has_many` / `belongs_to` /
+  `many_to_many` + `foreign_key` / `through`).
+- **Writes:** `ReadModelWritePlan` / workspace `upsert` + `commit` (same transaction
+  as events when staged on `CommitBatch`).
+- **Internal loads:** PK-anchored includes —
+  `store.workspace().load(...).include(...).one()` (one-level, opt-in).
+- **Schema lifecycle:** `ReadModelSchemaRegistry` + adapter for migration artifacts
+  and startup verification; `dctl schema` / `distributed_manifest()` for SQL.
+- **Non-goals:** public query APIs belong on the GraphQL layer below (not the ORM
+  include loader); do not write projections outside the projection path.
+
+## GraphQL query service
+
+Auto-generated GraphQL over relational read models — Hasura-style filtering,
+ordering, pagination, relationships, role-based column allowlists and row
+filters, live subscriptions after write-plan commits, and typed **causal command
+mutations** derived from the executable `Service` (including atomic
+`Projected<T>` and eventual `Fact` + projector paths).
+
+This is the public query/command edge for full-stack apps. The companion
+TypeScript package [`@hops-ops/distributed`](js/) (see
+[`js/README.md`](js/README.md)) supplies transport, a normalized causal replica,
+command runtime, diagnostics, and SvelteKit/React adapters. End-to-end template:
+[`tests/e2e-ui/`](tests/e2e-ui/). Scaffold with `dctl scaffold … --query-api`.
+Example playground: `cargo run --example graphiql --features "graphql,sqlite"`.
+
+### Enable
+
+```toml
+# Query engine + SQLite dialect (local / tests)
+distributed = { version = "0.1", features = ["graphql", "sqlite"] }
+
+# Production-shaped: GraphQL + Postgres repository/bus
+distributed = { version = "0.1", features = ["graphql", "postgres"] }
+```
+
+`graphql` implies `http` (Axum router, including `/graphql/ws`). SDL helpers under
+`distributed::graphql::{naming,sdl}` compile without the feature so
+`dctl schema --format graphql` works in tooling crates.
+
+### Scope
+
+| In | Out |
+|---|---|
+| `SELECT`-only query surface from `TableSchema` / read models | Table mutations / write-to-projection via GraphQL |
+| Role column allowlists + row filters (`claim(...)`) | Full IdP product UI (login pages live in your app / Auth.js) |
+| **First-class OIDC Bearer validation** (JWKS, iss/aud/exp, claim → session) | Assuming raw HTTP microsvc routes authenticate without a proxy or GraphQL edge |
+| SQLite + Postgres dialects | Cross-service federation / remote schemas |
+| Typed causal command mutations (`Service` → GraphQL) | Raw JSON GraphQL command registries |
+| Live list subscriptions via commit-path invalidation | Querying outbox / event-store operational tables |
+
+### Mount on a service
+
+```rust,ignore
+use distributed::graphql::{
+    claim, col, read, typed_command, Fact, GraphqlEngine,
+};
+use distributed::microsvc::{Routes, Service};
+
+let routes = Routes::new()
+    .with_repo(repository.clone().aggregate::<Todo>())
+    .typed_command(
+        typed_command::<CreateTodoInput, Fact<TodoStatusPayload>>("todo.create")
+            .field_name("todos_create")
+            .roles(["user", "admin"])
+            .confirmations(todo_confirmations),
+    )
+    .handle(create_todo)
+    .typed_command(
+        typed_command::<ForceArchiveInput, Fact<TodoStatusPayload>>("todo.force_archive")
+            .field_name("todos_force_archive")
+            .roles(["admin"])
+            .confirmations(todo_confirmations),
+    )
+    .handle(force_archive);
+
+let service = Service::new()
+    .named("todos")
+    .routes(routes)
+    // Optional: keep commands on GraphQL/bus/direct dispatch only.
+    .without_http_command_routes();
+
+let engine = GraphqlEngine::from_manifest(&manifest, &repository)?
+    // This exact executable inventory is the only mutation source.
+    .service(&service)
+    // Stable nonzero deployment secret shared by replicas of this endpoint.
+    .protocol_token_key(protocol_token_key)
+    .roles(&["user", "admin", "anonymous"])
+    .permission::<TodoView>(
+        "user",
+        read()
+            .all_columns()
+            .rows(col("owner_id").eq(claim("x-user-id"))),
+    )
+    .permission::<TodoView>("admin", read().all_columns())
+    .graphiql(true) // local only — see GraphiQL section
+    .build()?;
+
+let service = service.try_with_graphql(engine)?;
+
+// POST /graphql           — queries + command mutations
+// GET  /graphql           — GraphiQL when enabled
+// GET  /graphql/ws        — subscriptions (graphql-transport-ws / graphql-ws)
+```
+
+### Permissions (deny by default)
+
+Three axes — **grant** a role, **columns** they may see, **rows** they may access.
+Unmentioned models/roles fail closed (that is the deny). There is no separate
+`.deny()` list: omit the role, narrow columns, or tighten `.rows(...)`.
+
+```rust,ignore
+use distributed::graphql::{read, col, claim, ModelPermissions};
+
+ModelPermissions::new()
+    .grant(
+        "user",
+        read()
+            .all_columns()
+            .rows(col("owner_id").eq(claim("x-user-id"))),
+    )
+    .grant("admin", read().all_columns()) // all rows
+    .grant("anonymous", read().columns(["id", "status"]));
+```
+
+Row predicates can bind session claims (`claim("x-user-id")`, …) so multi-tenant
+RLS lives in the engine, not ad-hoc handler SQL.
+
+### Identity (first-class OIDC)
+
+Auth is a **built-in GraphQL concern**, not a separate product you wire after the
+fact. The engine validates tokens, maps claims into a `microsvc::Session`, and
+feeds the same claim map into RLS (`claim("x-user-id")`, roles, …). Modes live
+under [`src/graphql/identity/`](src/graphql/identity/):
+
+| Mode | When to use |
+|---|---|
+| **`OidcBearer`** | **Default for public edges:** JWT access tokens (`Authorization: Bearer …`), JWKS (incl. discovery), iss/aud/exp/nbf, alg allowlist (no `alg=none`), claim → engine roles. Configure with `OIDC_ISSUER` / `OIDC_AUDIENCE` (and related). |
+| **`TrustedProxy`** | Mesh/gateway already authenticated; inject trusted headers, strip client spoofing. |
+| **`Hybrid`** | Bearer when present, else trusted proxy headers. |
+| **`DevHeaders`** | Local only: ambient `x-user-id` / `x-role`. **Never** on a public edge. |
+
+Scaffolds prefer **`OidcBearer`** whenever OIDC env is set — not DevHeaders.
+
+**Provider-portable by design.** Live compose + bootstrap + e2e binaries ship for:
+
+- **Zitadel** — `tests/graphql_oidc_zitadel` + `scripts/oidc-zitadel-up.sh` (JWT-bearer mint; also powers e2e-ui login)
+- **Keycloak** — `tests/graphql_oidc_keycloak` + `scripts/oidc-keycloak-up.sh` (client_credentials + realm roles)
+- **Authentik** — `tests/graphql_oidc_authentik` + `scripts/oidc-authentik-up.sh` (client_credentials + groups)
+
+Shared assertions (E1–E8): discovery/JWKS, happy path, role isolation, multi-audience / `azp`, expired and forged tokens, etc. Generic OIDC also works for SaaS IdPs (e.g. Okta) without a dedicated compose stack.
+
+**WebSocket subscriptions:** browsers cannot set `Authorization` on the upgrade.
+Clients send the access token in `connection_init` (`authorization` /
+`accessToken` / nested headers). Do not put long-lived tokens in query strings
+for production. e2e-ui chat demonstrates the OIDC path.
+
+> **Note:** Raw microsvc HTTP/gRPC routes still treat `Session` as opaque unless
+> you terminate auth at a proxy **or** put the public API on GraphQL
+> (`OidcBearer`). The GraphQL edge is where first-class token validation lives.
+
+### Command mutations vs HTTP commands
+
+Command fields on the GraphQL schema are an RPC facade: same guards, same
+handlers, same outbox/projector path as other transports. Prefer a
+**GraphQL-only public API** for browser apps (`.without_http_command_routes()`)
+so the edge is one protocol. Handler guards should require a session user
+(and role where needed); never trust client-supplied owner fields over the
+session principal.
+
+### Live subscriptions
+
+After projectors commit read-model rows, a `ChangeHub` invalidates matching
+subscriptions so clients receive updated lists without polling. Wire projectors
+to the same pool the engine uses; the e2e-ui chat subscription is the reference.
+
+### GraphiQL
+
+```bash
+cargo run --example graphiql --features "graphql,sqlite"
+# open http://127.0.0.1:4000/graphql  (override with GRAPHIQL_ADDR)
+```
+
+GraphiQL is a **developer** tool. Default headers in the playground trust
+`x-role` / `x-user-id` (DevHeaders-style). For real services:
+
+- Prefer **`graphiql(false)`** or env policy (`GRAPHIQL=0`, production
+  `RUST_ENV` / `graphiql_enabled_from_env`) so production never ships the IDE.
+- Treat GraphiQL + DevHeaders as local-only; pair public scaffolds with
+  `OidcBearer`.
+
+### Client surfaces, generated artifacts, and CI
+
+```bash
+# Optional human-readable GraphQL SDL artifact
+dctl schema --format graphql --out schema.graphql
+git diff --exit-code schema.graphql   # drift gate
+```
+
+The Rust `Service` inventory and GraphQL `Surface` IR are the source of truth
+for schema, authorization, commands, optimistic effects, and client artifacts.
+`dctl client-manifest` exports one role or named application surface, and
+`dctl client` compiles that manifest with co-located `.graphql` operations into
+typed query/live/command modules. Common and elevated applications use separate
+manifest entrypoints, document sets, generated directories, virtual modules,
+and request-local replicas; an admin superset is never bundled into the common
+client.
+
+In `tests/e2e-ui`:
+
+```bash
+make gen-client    # Rust Service + ui/distributed.config.js → user/admin clients
+make check-client  # byte/file-set drift gate; never rewrites
+```
+
+See [`js/README.md`](js/README.md) for the package API and
+[`tests/e2e-ui/README.md`](tests/e2e-ui/README.md) for the complete integration
+flow.
+
+### Full-stack template (`tests/e2e-ui`)
+
+Copyable product shape (not a toy workshop): multi-crate domains, GraphQL-only
+edge, real OIDC, SSR, live subscriptions, and a teaching **Blob** aggregate that
+uses atomic `Projected<BlobGameView>` (direct-only — no async blob projector).
+
+| Piece | Role |
+|---|---|
+| Domain crates | Pure aggregates: todos, chat, blob |
+| Read models | Projector-owned rows *and* direct `Projected` rows (blob) — no dual-write from handlers |
+| GraphQL edge | Owner RLS, admin surfaces, joins to `auth_users`, chat live sub, blob commands |
+| Identity | Zitadel + Auth.js (PKCE), optional Zitadel user-scrape → `auth_users` |
+| SvelteKit | `$distributed` / `$distributed/admin`, SSR from co-located `+page.graphql`, hydration, generated live ops + optimistic commands |
+| Suite | GraphQL-only edge, IDOR, OIDC isolation, Playwright (incl. projected-move races) |
+
+```bash
+cd tests/e2e-ui
+make up && set -a && source e2e-ui.env && set +a && make run
+# UI http://127.0.0.1:5180  ·  API GraphQL http://127.0.0.1:8791/graphql
+# /todos  /chat  /blob  /admin  /login
+make test         # domain + behavioral + JS-backed UI build/typecheck/tests
+make check-client # generated user/admin clients are current
+```
+
+### TypeScript client (`js/` → `@hops-ops/distributed`)
+
+| Export | Purpose |
+|---|---|
+| `@hops-ops/distributed` | Typed documents, HTTP GraphQL client, identity helpers |
+| `…/replica` | Normalized causal replica, command runtime, projected fences |
+| `…/sveltekit` | Vite virtual modules, SSR load/hydrate, app shells |
+| `…/react` | Optional React hooks adapter |
+| `…/diagnostics` | Client diagnostics helpers |
+
+Generate app clients from the Rust surface:
+
+```bash
+dctl client-manifest …   # export role/app surface IR
+dctl client …            # compile co-located .graphql → typed modules
+```
+
+See [`js/README.md`](js/README.md) for package API and packaging.
+
+### Tests in this repo
+
+| Suite | Focus |
+|---|---|
+| `tests/graphql_*` | Engine, HTTP, SDL, dialects, harden (authz/DoS/inject), causal transport |
+| `tests/graphql_identity` | Always-on OIDC/JWT matrix (mock JWKS; no Docker) |
+| `tests/graphql_oidc_{zitadel,keycloak,authentik}` | **Live** multi-IdP e2e (compose + real JWKS; gated) |
+| `tests/typed_commands` | Causal command / Projected / Fact registration |
+| `tests/e2e-ui` | Multi-crate product template + SvelteKit + Zitadel UI login + Playwright |
+| `js/tests` | Replica, command runtime, adapters |
+| `examples/graphiql.rs` | Seeded local playground |
+
+```bash
+cargo test --test graphql_engine --features "graphql,sqlite"
+cargo test --test graphql_identity --features "graphql,sqlite"
+cargo test --test graphql_harden --features "graphql,sqlite"
+cd js && npm run quality
+# Live IdPs (optional):
+#   ./scripts/oidc-zitadel-up.sh && set -a && source graphql-oidc.env && set +a
+#   cargo test --test graphql_oidc_zitadel --features graphql,sqlite
+# Full UI matrix: cd tests/e2e-ui && make test
+```
 
 ## Snapshots
 
@@ -1564,8 +1974,15 @@ endpoint and, when paired with `--gitops`, emits Prometheus Operator
 `ServiceMonitor` and `PrometheusRule` templates for HTTP services. The generated
 values keep those CRDs disabled until an environment explicitly enables them.
 Bus-only and worker services can expose the same registry on a side port with
-`distributed::metrics::serve_http`. See [`docs/metrics.md`](docs/metrics.md) for
-metric names, label rules, and GitOps details.
+`distributed::metrics::serve_http("0.0.0.0:9100", Some("orders-worker")).await?`,
+or compose `distributed::metrics::http_router_for_service("orders-worker")` into
+an existing Axum app. Scrape `GET /metrics` (Prometheus text). Keep `/metrics` on
+a **private** listener — unauthenticated by design.
+
+**Label policy (closed set):** `service`, `message_kind`, `message`, `status`,
+`transport`, `outcome`, `failure_class`, `action`, plus GraphQL `root_field` when
+applicable. Do **not** label metrics with `user_id`, `tenant_id`, free-form paths,
+or raw command input (unknown commands bucket as `message=unknown`).
 
 `describe`/`schema` compile your crate and call its `distributed_manifest()`
 entrypoint (override with `--entrypoint`), which registers the [read
@@ -1602,6 +2019,7 @@ src/
   commit_builder/ # Transactional batches for aggregates, outbox, and read models
   emitter/        # In-process event emitter helpers (feature = "emitter")
   entity/         # Entity, event records, metadata, upcasting codecs
+  graphql/        # Query service: engine, permissions, identity, SDL, HTTP/WS (feature = "graphql")
   in_memory_repo/   # In-memory repository (implements every async trait)
   lock/           # Lock + lock manager traits, in-memory locks
   microsvc/       # Command/event handler framework: service, context, session
@@ -1616,12 +2034,8 @@ src/
   lib.rs          # Public exports
 distributed_macros/
   src/            # Proc macros: sourced, digest, aggregate, enqueue, ReadModel, Snapshot
-docs/
-  repositories.md
-  transports.md
-  read-models.md
-  postgres-event-store.md
-  research-and-roadmap.md
+js/               # @hops-ops/distributed JS/TS client, command runtime, and SvelteKit adapter
+tests/e2e-ui/     # Full-stack CQRS + GraphQL + SvelteKit template (nested workspace)
 migrations/       # Explicit SQLite and Postgres migrations
 compose.yaml      # Local postgres / rabbitmq / kafka / nats for integration tests
 ```
@@ -1676,19 +2090,27 @@ CI also publishes `lcov.info` as a workflow artifact and attempts an optional Co
 
 ## Examples
 
-- `tests/sourced/` — `#[sourced]` macro with typed event enum, `TryFrom`, and aggregate hydration
-- `tests/sourced_upcasting/` — `#[sourced]` with upcasters (v1→v2→v3 chains)
-- `tests/sourced_enqueue/` — `#[sourced(entity, enqueue)]` integrated choreography (`--features emitter`)
-- `tests/sourced_snapshot/` — `#[derive(Snapshot)]` with custom ID keys, `serde(skip)` exclusion, and custom entity fields
-- `tests/snapshots/` — snapshot creation, loading, and partial replay
-- `tests/upcasting/` — event versioning with v1→v2→v3 upcasters, chaining, and snapshot integration
-- `tests/read_models/` — relational read-model projections and atomic commits
-- `tests/distributed_read_model/` — multi-service projection over the bus + persistence matrix
-- `tests/microsvc/` — async handlers, dispatch, session, convention, HTTP, gRPC, and bus transports
-- `tests/sagas/` — saga orchestration and choreography with the outbox pattern
-- `tests/sqlite_repository/`, `tests/postgres_repository/` — durable SQL adapters
-- `tests/transport_conformance/`, `tests/{nats,rabbitmq,kafka,postgres,sqlite}_transport/`, `tests/knative_cloudevents/` — transport adapters and the shared conformance harness
+**Start here (product demos):** [See it run](#see-it-run) — e2e-ui (`tests/e2e-ui`),
+Blob game, live chat, GraphiQL.
+
+| Path | What it showcases |
+|---|---|
+| [`tests/e2e-ui/`](tests/e2e-ui/) | Full-stack CQRS + GraphQL + OIDC + SvelteKit (todos, chat, blob) |
+| [`js/`](js/) | `@hops-ops/distributed` — transport, causal replica, SvelteKit/React |
+| [`examples/graphiql.rs`](examples/graphiql.rs) | Seeded GraphQL playground (`--features "graphql,sqlite"`) |
+| `tests/graphql_*` | Engine, HTTP/WS, harden, identity, multi-IdP OIDC |
+| `tests/typed_commands/` | Causal command / `Projected` / `Fact` registration |
+| `tests/microsvc/` | Handlers on HTTP, gRPC, bus, session |
+| `tests/read_models/`, `tests/distributed_read_model/` | Atomic vs eventual projections |
+| `tests/sourced*` / `tests/snapshots/` / `tests/upcasting/` | Macros, snapshots, event versioning |
+| `tests/sagas/` | Orchestration + choreography with the outbox |
+| `tests/*_transport/`, `tests/knative_cloudevents/` | Broker adapters + conformance |
+
+## License
 
 ## License
 
-MIT. See `LICENSE`.
+The Rust workspace metadata declares its crates as MIT licensed, but this
+repository does not currently contain a top-level license file. The npm package
+therefore remains `UNLICENSED` until maintainers explicitly choose and add its
+license.
diff --git a/distributed_cli/Cargo.toml b/distributed_cli/Cargo.toml
index 1217e577..5a6f59ea 100644
--- a/distributed_cli/Cargo.toml
+++ b/distributed_cli/Cargo.toml
@@ -15,6 +15,11 @@ name = "dctl"
 path = "src/main.rs"
 
 [dependencies]
+async-graphql-parser = "7"
+async-graphql-value = "7"
+base64 = "0.22.1"
 clap = { version = "4", features = ["derive"] }
+glob = "0.3"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+sha2 = "0.10"
diff --git a/distributed_cli/README.md b/distributed_cli/README.md
index b9b7f92a..4567fd7d 100644
--- a/distributed_cli/README.md
+++ b/distributed_cli/README.md
@@ -102,6 +102,62 @@ compile the target crate, they need the local `distributed` crate to be
 resolvable — found automatically from the workspace, or pass `--distributed-path`
 / set `DISTRIBUTED_PATH`.
 
+## `dctl client-manifest` — authorized client surface
+
+```bash
+dctl client-manifest > target/distributed-client.json
+```
+
+Compiles the service's `distributed_client_surface` export into the versioned,
+role/application-selected manifest used by the operation compiler. The export
+already contains one concrete role or named application surface; it is not an
+admin catalog that downstream tools filter themselves.
+
+## `dctl client` — typed query, live, and command artifacts
+
+```bash
+dctl client \
+  --manifest target/distributed-client.json \
+  --role user \
+  --documents 'src/**/*.graphql' \
+  --out src/generated/distributed
+
+# CI: parse, validate, and compare without writing
+dctl client \
+  --manifest target/distributed-client.json \
+  --role user \
+  --documents 'src/**/*.graphql' \
+  --out src/generated/distributed \
+  --check
+```
+
+The requested `--role` or `--surface` must exactly match the manifest's
+authorized identity. Generation validates the GraphQL documents, injects only
+authorized wire-only identity metadata, derives an exact live companion for
+`@live`, and emits framework-neutral TypeScript replica artifacts alongside the
+manifest-owned command and protocol operations. Operation IDs hash the exact
+full document sent over GraphQL; they do not imply an APQ/persisted-operation
+registry.
+
+Each operation artifact also contains the closed variable/input codec compiled
+from that selected surface. The runtime applies GraphQL singleton-list coercion,
+canonical scalar encoding, unknown-field rejection, and deterministic deep
+freezing before variables can identify a cache entry or reach the network.
+Manifest v7 and variable codec v2 carry the selected service's exact
+`max_depth`, `max_bool_width`, and `max_in_list` contract. Static literal and
+mixed-variable filters are rejected during generation when their known shape
+exceeds those limits; runtime variables carry per-use `filterBaseDepth` and
+`maxItems` constraints. Reused variables receive the most restrictive
+intersection across every root, relationship selection, and aggregate use.
+The current query surface supports complete and offset-window roots; cursor
+artifacts are not certified and therefore fail closed to revalidation.
+
+`@load` is discovered automatically for `src/routes/**/+page.graphql`. A
+co-located document with a different filename can use the explicit fallback
+`--route OperationName=/route`. Unsupported or unprovable selections fail at
+build time with their source location; the compiler does not emit a partial
+normalization plan.
+
 ## `dctl describe` — manifest as JSON
 
 ```bash
diff --git a/distributed_cli/skills/distributed-graphql/SKILL.md b/distributed_cli/skills/distributed-graphql/SKILL.md
new file mode 100644
index 00000000..9b619ccc
--- /dev/null
+++ b/distributed_cli/skills/distributed-graphql/SKILL.md
@@ -0,0 +1,178 @@
+---
+name: distributed-graphql
+description: Expose generated GraphQL queries and typed causal commands over Distributed services. Use when adding a GraphQL API, roles, model exposure, subscriptions, command mutations, or generated clients.
+---
+
+# GraphQL query service
+
+Enable the framework features and mount one endpoint:
+
+```toml
+distributed = { path = "...", features = ["graphql", "sqlite"] } # or postgres
+```
+
+## Service layout (`src/query/`)
+
+```
+src/query/
+  mod.rs          # build_engine(repository, &service, protocol_key)
+  roles.rs        # role name constants
+  <model>.rs      # one file per exposed model: permissions()
+```
+
+Typed command declarations live beside their executable handlers. There is no
+second GraphQL command registry.
+
+### Add a model exposure
+
+1. Ensure the read model is in `distributed_manifest()`.
+2. Add `src/query/<table>.rs`:
+
+```rust
+use distributed::graphql::{read, col, claim, ModelPermissions};
+use crate::read_models::OrderView;
+
+pub type Model = OrderView;
+
+pub fn permissions() -> ModelPermissions<OrderView> {
+    ModelPermissions::new()
+        .grant("user", read()
+            .all_columns()
+            .rows(col("customer_id").eq(claim("x-user-id"))))
+        .grant("anonymous", read().columns(["order_id", "status"]))
+}
+```
+
+3. Register it in `src/query/mod.rs` via `graphql_models!(builder, order_view)` or
+   `.model::<OrderView>(order_view::permissions())`.
+
+### Roles
+
+Declare the vocabulary with `.roles(&["user", "anonymous"])`. Deny-by-default:
+a role sees nothing until granted via `.model(...)` / `.grant_all(role)` /
+`.permission(...)`.
+
+## Wire the service
+
+```rust
+let service = build_service(repository.clone())
+    // Browser writes go through the OIDC-protected GraphQL command proxy only.
+    .without_http_command_routes();
+let engine = query::build_engine(
+    &repository,
+    &service,
+    protocol_token_key,
+)?;
+let service = service.try_with_graphql(engine)?;
+// POST /graphql  — queries / mutations
+// GET  /graphql  — GraphiQL IDE when `.graphiql(true)`
+```
+
+`without_http_command_routes()` disables only the generic `POST /{command}`
+transport on this GraphQL-facing service. Non-GraphQL services may keep those
+direct command routes when that transport is intentional and independently
+authenticated.
+
+Build the executable `Service` first and pass that exact instance to
+`GraphqlEngineBuilder::service`. For `Projected<M>`, pass the repository handle
+itself as the GraphQL pool source; a separately cloned raw pool cannot prove the
+same transactional storage identity. Configure a stable, nonzero 32-byte
+protocol key on every replica serving the same endpoint.
+
+### GraphiQL (local visual explorer)
+
+```bash
+# Framework playground (seeded orders, no scaffold needed):
+cargo run --example graphiql --features "graphql,sqlite"
+# → http://127.0.0.1:4000/graphql
+
+# Or run your scaffolded service and open GET /graphql
+GRAPHIQL=0 cargo run   # disable IDE in production
+```
+
+Default GraphiQL headers: `x-role: user`, `x-user-id: demo`. Edit in the IDE
+Headers panel. See `README § GraphQL query service`.
+
+### Identity (public GraphQL)
+
+Scaffold **always** wires `public_oidc_identity_from_env()` → **`OidcBearer`** +
+`require_auth=true` (D6). Set `OIDC_ISSUER` + `OIDC_AUDIENCE` (or `OIDC_CLIENT_ID`).
+If unset, placeholder issuer still uses OidcBearer (401 without Bearer) — **never**
+ambient `DevHeaders` on the public scaffold path.
+
+| Mode | Use |
+|---|---|
+| `OidcBearer` | Public API — validate `Authorization: Bearer` JWT (access token) |
+| `Hybrid` | Bearer preferred; else gateway-injected headers |
+| `TrustedProxy` | Mesh — strip client identity denylist at process |
+| `DevHeaders` | Local GraphiQL / unit tests only (explicit opt-in) |
+
+Wire via `.identity(distributed::graphql::public_oidc_identity_from_env())`.
+Never trust raw client `x-user-id` / `x-role` on a public edge.
+
+Pass `change_stream(repo.read_model_changes())` for live subscriptions.
+
+### Typed causal commands
+
+Declare each GraphQL mutation on the executable route:
+
+```rust
+let routes = Routes::new()
+    .with_repo(repository.aggregate::<Order>())
+    .typed_command(
+        typed_command::<CreateOrderInput, Fact<CreateOrderPayload>>("order.create")
+            .roles(["user"])
+            .confirmations(/* finite projector proof */),
+    )
+    .handle(create_order);
+```
+
+Handlers accept `CausalCommandContext`, stage aggregate/outbox/projection work on
+that context, and return `PreparedCommand<Accepted<_>>`,
+`PreparedCommand<Fact<_>>`, or `PreparedCommand<Projected<M>>`. Never commit
+outside the framework-owned causal boundary.
+
+### Command consistency modes
+
+**Command success does not imply projection visibility.**
+
+| Contract | Meaning |
+|----------|---------|
+| `Accepted<T>` | Durable command accepted; no projection visibility is promised. |
+| `Fact<T>` | Durable fact returned with finite registered projector confirmations. |
+| `Projected<M>` | Exact read-model row is staged in the same transaction. |
+
+Rules:
+
+1. Use `Projected<M>` only when the exact row is staged with the command.
+2. Use `Fact<T>` only with finite confirmation topology registered on the same
+   service.
+3. Otherwise use `Accepted<T>`; never invent a projected row.
+
+Surface IR: SDL is built via `build_surface` → `graphql_sdl_from_surface` (shared inventory
+for dialect-honest comparison ops, role grants, typed commands, and generated
+client manifests).
+
+## SDL artifact (CI gate)
+
+```bash
+dctl schema --format graphql --out schema.graphql
+git diff --exit-code schema.graphql
+```
+
+`--dialect` is ignored with `--format graphql` (dialect-independent core surface).
+
+## Scaffold
+
+```bash
+dctl scaffold my-service --query-api --read-models --store sqlite
+```
+
+Emits typed causal handlers, a service-derived GraphQL engine, `src/query/`
+permissions, the `graphql` feature, and repository/token-key wiring.
+
+## Reference
+
+- Framework docs: `README § GraphQL query service` in the Distributed repo
+- Distributed GitKB: `specs/query-layer/v1/client-replica` and
+  `specs/query-layer/v1/causal-command-protocol` (normative)
diff --git a/distributed_cli/skills/distributed-schema/SKILL.md b/distributed_cli/skills/distributed-schema/SKILL.md
index 184682e3..e6f32265 100644
--- a/distributed_cli/skills/distributed-schema/SKILL.md
+++ b/distributed_cli/skills/distributed-schema/SKILL.md
@@ -122,4 +122,4 @@ dctl schema --format atlas --name orders --db-secret orders-db \
 
 Full flag table: `distributed_cli/README.md` in the Distributed repo
 (https://crates.io/crates/distributed_cli). Event-store internals:
-`docs/postgres-event-store.md`; read-model metadata: `docs/read-models.md`.
+`README (Postgres repository section) and migrations/`; read-model metadata: `README § Read Models`.
diff --git a/distributed_cli/skills/distributed-usage/SKILL.md b/distributed_cli/skills/distributed-usage/SKILL.md
index 7a60fbb9..f0947205 100644
--- a/distributed_cli/skills/distributed-usage/SKILL.md
+++ b/distributed_cli/skills/distributed-usage/SKILL.md
@@ -135,6 +135,23 @@ Rules that prevent real bugs:
 
 ## Command handlers
 
+For a browser-facing GraphQL service, use the typed causal command path instead
+of exposing a raw `Context`/`serde_json::Value` handler as the mutation contract:
+
+- declare `.typed_command(typed_command::<Input, Accepted<Payload> | Fact<Payload> | Projected<Model>>(...))`
+  on the executable route;
+- implement the handler with `CausalCommandContext` and return a
+  `PreparedCommand<_>` so the framework owns commit, ledger, outbox, and
+  projection atomicity;
+- bind that exact `Service` through `GraphqlEngineBuilder::service`, configure
+  public OIDC, and call `.without_http_command_routes()` so browser writes use
+  only the GraphQL command proxy;
+- generate the strictly typed client with `dctl client`.
+
+Use the `distributed-graphql` skill for the complete route, consistency,
+authorization, and client-generation contract. The raw handler form below
+remains valid for intentional non-GraphQL transports.
+
 One module per handler, exporting `COMMAND` (or `EVENT`/`EVENTS`), a `guard`,
 and an async `handle`:
 
@@ -228,12 +245,43 @@ Gotchas:
   replica of one deployment. `namespace(..)` scopes broker topology per
   app/environment. Names are validated: portable IDs only (`A-Za-z0-9_-`,
   `.` also allowed in namespaces, max 128 bytes).
-- `microsvc` does **not** authenticate. Deploy behind a trusted proxy that
-  strips client-supplied identity headers and injects authenticated claims
-  (`Session` is an opaque map; `x-user-id` / `x-role` are convenience keys only).
+- Generic `microsvc` command routes do **not** authenticate themselves. Protect
+  intentional non-GraphQL routes at a trusted edge. Public GraphQL scaffolds
+  instead wire `OidcBearer` validation and disable generic command POST routes;
+  never trust client-supplied identity headers.
 - `connect_and_migrate` applies migrations; plain `connect` does not create
   tables.
 
+## Multi-crate single-service layout (and later microservices)
+
+Copy the **e2e-ui** fixture under `tests/e2e-ui/` (README; see `tests/e2e-ui/README.md`):
+
+```text
+crates/
+  todo-domain/     # personal todos (owner-scoped)
+  chat-domain/     # lobby chat (shared room)
+  readmodels/      # projections + distributed_manifest
+  service/         # thin command handlers + event projectors + GraphQL
+  runner/          # store + bus + bind
+  suite/           # HTTP/GraphQL behavioral cases
+ui/                # SvelteKit: todos + chat with GraphQL subscriptions
+```
+
+Rules the fixture demonstrates:
+
+- **Domain unit tests first** (`cargo test -p todo-domain`) — no repository
+- **Owner from session**, never from untrusted create body
+- **Projectors only** write read models (commands commit aggregate + outbox)
+- GraphQL row filter: `owner_id = claim(x-user-id)` for role `user`
+- **Typed causal GraphQL commands** run through the OIDC command proxy; generic
+  direct command POST routes are disabled
+- **Generated client**: `dctl client` produces the typed replica/query/command
+  artifacts consumed by the SvelteKit app
+- **Subscriptions**: wire `SqliteRepository::read_model_changes()` into
+  `GraphqlEngineBuilder::change_stream`; clients use WebSocket `/graphql/ws`
+
+Run the full app: `cd tests/e2e-ui && make`. Suite: `make test`.
+
 ## Manifest entrypoint
 
 Every service should export `distributed_manifest()` registering its read
@@ -251,7 +299,7 @@ Keep it updated when adding read models or tables; see the
 ## References
 
 - Framework guide: the `distributed` crate README (https://crates.io/crates/distributed)
-- Read models: `docs/read-models.md`; transports: `docs/transports.md`;
-  repositories: `docs/repositories.md` in the Distributed repo
+- Read models: `README § Read Models`; transports: `README § Event Bus / transports`;
+  repositories: `README § Repositories` in the Distributed repo
 - CI/GitOps scaffolding: the `distributed-ci` skill
 - Schema and manifest tooling: the `distributed-schema` skill
diff --git a/distributed_cli/src/cli.rs b/distributed_cli/src/cli.rs
index ea8d9c29..6603746c 100644
--- a/distributed_cli/src/cli.rs
+++ b/distributed_cli/src/cli.rs
@@ -7,13 +7,18 @@
 //! `hops` mounts [`ServiceArgs`] under `hops service` and dispatches with [`run`],
 //! re-exporting the commands rather than reimplementing them.
 
-use clap::{Args, Subcommand, ValueEnum};
+use clap::{ArgGroup, Args, Subcommand, ValueEnum};
+use std::collections::{BTreeMap, BTreeSet};
 use std::error::Error;
 use std::ffi::OsString;
 use std::fs;
 use std::path::{Component, Path, PathBuf};
 use std::process::Command;
 
+use crate::client_compiler::{
+    compile_client, ClientCompileInput, ClientDocument, ClientRouteRegistration,
+    ClientSurfaceSelector, GeneratedClientFile, GeneratedClientProject,
+};
 use crate::manifest_harness::{run_manifest_harness, HarnessMode, HarnessOptions};
 use crate::skills::{embedded_skills, generate_skills, SkillsInitSpec, AGENTS_MD_FILE};
 use crate::{
@@ -23,6 +28,7 @@ use crate::{
 };
 
 const DISTRIBUTED_MANIFEST_SCHEMA_VERSION: u64 = 1;
+const DISTRIBUTED_CLIENT_MANIFEST_VERSION: u64 = 1;
 
 #[derive(Args, Debug)]
 pub struct ServiceArgs {
@@ -37,6 +43,10 @@ pub enum ServiceCommands {
     Scaffold(ScaffoldArgs),
     /// Print a service's Distributed project manifest as JSON
     Describe(DescribeArgs),
+    /// Compile role/application-scoped GraphQL operations into client artifacts
+    Client(ClientArgs),
+    /// Compile the service's authorized client Surface manifest as JSON
+    ClientManifest(ClientManifestArgs),
     /// Render schema artifacts (SQL or an Atlas Operator resource) from a manifest
     Schema(SchemaArgs),
     /// Extract the embedded Distributed agent skills into a project
@@ -123,6 +133,9 @@ pub struct ScaffoldArgs {
     /// Generate placeholder read-model modules and register them in distributed_manifest().
     #[arg(long)]
     pub read_models: bool,
+    /// Generate src/query/ GraphQL skeleton, enable the graphql feature, and wire with_graphql.
+    #[arg(long)]
+    pub query_api: bool,
     /// Enable Distributed tracing spans and GitOps OTLP environment values.
     #[arg(long, visible_alias = "otel")]
     pub tracing: bool,
@@ -199,6 +212,63 @@ pub struct DescribeArgs {
     pub distributed_path: Option<PathBuf>,
 }
 
+#[derive(Args, Debug)]
+pub struct ClientManifestArgs {
+    /// Service project directory. Defaults to the current directory.
+    #[arg(long, default_value = ".")]
+    pub path: PathBuf,
+    /// Cargo.toml for the target service. Overrides --path.
+    #[arg(long)]
+    pub manifest_path: Option<PathBuf>,
+    /// Cargo package to inspect when the manifest belongs to a workspace.
+    #[arg(long)]
+    pub package: Option<String>,
+    /// Comma-delimited feature list for the target service.
+    #[arg(long, value_delimiter = ',')]
+    pub features: Vec<String>,
+    /// Disable default features on the target service dependency.
+    #[arg(long)]
+    pub no_default_features: bool,
+    /// Surface export function. Defaults to
+    /// `<crate>::distributed_client_surface`.
+    #[arg(long)]
+    pub entrypoint: Option<String>,
+    /// Path to the local Distributed crate.
+    #[arg(long)]
+    pub distributed_path: Option<PathBuf>,
+}
+
+#[derive(Args, Debug)]
+#[command(group(
+    ArgGroup::new("client_surface")
+        .required(true)
+        .multiple(false)
+        .args(["role", "surface"])
+))]
+pub struct ClientArgs {
+    /// Role/application-selected Distributed client manifest v7.
+    #[arg(long)]
+    pub manifest: PathBuf,
+    /// Verify that the manifest is selected for this concrete role.
+    #[arg(long)]
+    pub role: Option<String>,
+    /// Verify that the manifest is selected for this named application surface.
+    #[arg(long)]
+    pub surface: Option<String>,
+    /// GraphQL document glob. Repeat for multiple source roots.
+    #[arg(long, required = true, value_name = "GLOB")]
+    pub documents: Vec<String>,
+    /// Explicit @load fallback in OPERATION=/route form. Repeat as needed.
+    #[arg(long, value_name = "OPERATION=/route")]
+    pub route: Vec<String>,
+    /// Generated artifact directory.
+    #[arg(long, default_value = "src/generated/distributed")]
+    pub out: PathBuf,
+    /// Verify generated bytes and file set without writing anything.
+    #[arg(long)]
+    pub check: bool,
+}
+
 #[derive(Args, Debug)]
 pub struct SchemaArgs {
     /// Service project directory. Defaults to the current directory.
@@ -313,6 +383,9 @@ pub enum SchemaFormat {
     Sql,
     /// An Atlas Operator `AtlasSchema` resource wrapping the desired-state SQL.
     Atlas,
+    /// Dialect-independent GraphQL SDL (`schema.graphql` artifact).
+    /// When set, `--dialect` is silently ignored (SDL has no dialect).
+    Graphql,
 }
 
 // Map the CLI's clap enums onto the generation spec enums. These exist so
@@ -363,6 +436,8 @@ pub fn run(args: &ServiceArgs) -> Result<(), Box<dyn Error>> {
     match &args.command {
         ServiceCommands::Scaffold(scaffold) => run_scaffold(scaffold),
         ServiceCommands::Describe(describe) => run_describe(describe),
+        ServiceCommands::Client(client) => run_client(client),
+        ServiceCommands::ClientManifest(client) => run_client_manifest(client),
         ServiceCommands::Schema(schema) => run_schema(schema),
         ServiceCommands::Skills(skills) => match &skills.command {
             SkillsCommands::Init(init) => run_skills_init(init),
@@ -634,14 +709,28 @@ fn run_scaffold(args: &ScaffoldArgs) -> Result<(), Box<dyn Error>> {
     let distributed_path = resolve_distributed_path(args.distributed_path.as_deref(), &output_dir)?;
     let distributed_dependency_path = path_for_toml(&relative_path(&output_dir, &distributed_path));
 
+    // GraphQL execution needs a SQL store feature; promote in-memory → sqlite.
+    let store = {
+        let store = args.store.into();
+        if args.query_api && matches!(store, crate::StoreTarget::InMemory) {
+            eprintln!(
+                "warning: --query-api requires a SQL store; promoting --store in-memory to sqlite"
+            );
+            crate::StoreTarget::Sqlite
+        } else {
+            store
+        }
+    };
+
     let spec = ServiceScaffoldSpec {
         name: args.name.clone(),
         transport: transport.into(),
-        store: args.store.into(),
+        store,
         bus: args.bus.map(Into::into),
         metrics: args.metrics.map(Into::into),
         models: args.model.clone(),
-        read_models: args.read_models,
+        read_models: args.read_models || args.query_api,
+        query_api: args.query_api,
         tracing: args.tracing,
         commands: args.command.clone(),
         events: args.event.clone(),
@@ -693,8 +782,553 @@ fn run_describe(args: &DescribeArgs) -> Result<(), Box<dyn Error>> {
     }
 }
 
-fn run_schema(args: &SchemaArgs) -> Result<(), Box<dyn Error>> {
-    let sql = run_manifest_harness(
+const MAX_CLIENT_MANIFEST_BYTES: usize = 16 * 1024 * 1024;
+const MAX_CLIENT_DOCUMENT_BYTES: usize = 1024 * 1024;
+const MAX_GENERATED_CLIENT_ARTIFACT_BYTES: usize = 8 * 1024 * 1024;
+const MAX_GENERATED_CLIENT_FILES: usize = 8_192;
+
+fn run_client(args: &ClientArgs) -> Result<(), Box<dyn Error>> {
+    let manifest_source =
+        read_utf8_bounded(&args.manifest, MAX_CLIENT_MANIFEST_BYTES, "client manifest")?;
+    let manifest: serde_json::Value =
+        serde_json::from_str(&manifest_source).map_err(|error| -> Box<dyn Error> {
+            format!("parse client manifest {}: {error}", args.manifest.display()).into()
+        })?;
+    let selector = match (&args.role, &args.surface) {
+        (Some(role), None) => ClientSurfaceSelector::role(role.clone()),
+        (None, Some(surface)) => ClientSurfaceSelector::application(surface.clone()),
+        _ => {
+            return Err("pass exactly one of --role <name> or --surface <application-name>".into());
+        }
+    };
+    let documents = collect_client_documents(&args.documents)?;
+    let routes = args
+        .route
+        .iter()
+        .map(|registration| parse_client_route_registration(registration))
+        .collect::<Result<Vec<_>, _>>()?;
+    let project = compile_client(
+        ClientCompileInput::new(manifest, selector, documents).with_route_registrations(routes),
+    )?;
+
+    if args.check {
+        check_client_project(&args.out, &project)?;
+        println!(
+            "Distributed client artifacts are current ({} files)",
+            project.files.len()
+        );
+    } else {
+        write_client_project(&args.out, &project)?;
+        println!(
+            "Generated {} Distributed client artifacts at {}",
+            project.files.len(),
+            args.out.display()
+        );
+    }
+    Ok(())
+}
+
+fn read_utf8_bounded(path: &Path, limit: usize, label: &str) -> Result<String, Box<dyn Error>> {
+    let bytes =
+        fs::read(path).map_err(|error| format!("read {label} {}: {error}", path.display()))?;
+    if bytes.len() > limit {
+        return Err(format!(
+            "{label} {} is {} bytes; maximum supported size is {limit}",
+            path.display(),
+            bytes.len()
+        )
+        .into());
+    }
+    String::from_utf8(bytes)
+        .map_err(|error| format!("{label} {} is not UTF-8: {error}", path.display()).into())
+}
+
+fn collect_client_documents(patterns: &[String]) -> Result<Vec<ClientDocument>, Box<dyn Error>> {
+    let project_root = fs::canonicalize(std::env::current_dir()?)?;
+    let mut matched = BTreeMap::<PathBuf, String>::new();
+    for pattern in patterns {
+        if pattern.trim().is_empty() {
+            return Err("--documents glob must not be empty".into());
+        }
+
+        // Exact existing files must not go through glob expansion. Paths can
+        // contain SvelteKit route params such as `[[gameId]]`, which are valid
+        // path characters but glob metacharacters.
+        let direct = PathBuf::from(pattern);
+        if direct.is_file() {
+            insert_client_document_path(&project_root, &mut matched, &direct)?;
+            continue;
+        }
+
+        let mut pattern_matches = 0usize;
+        let entries = glob::glob(pattern)
+            .map_err(|error| format!("invalid --documents glob `{pattern}`: {error}"))?;
+        for entry in entries {
+            let path =
+                entry.map_err(|error| format!("expand --documents glob `{pattern}`: {error}"))?;
+            insert_client_document_path(&project_root, &mut matched, &path)?;
+            pattern_matches += 1;
+        }
+        if pattern_matches == 0 {
+            return Err(format!("--documents glob `{pattern}` matched no files").into());
+        }
+    }
+
+    matched
+        .into_iter()
+        .map(|(path, source_path)| {
+            Ok(ClientDocument::new(
+                source_path,
+                read_utf8_bounded(&path, MAX_CLIENT_DOCUMENT_BYTES, "GraphQL document")?,
+            ))
+        })
+        .collect()
+}
+
+fn insert_client_document_path(
+    project_root: &Path,
+    matched: &mut BTreeMap<PathBuf, String>,
+    path: &Path,
+) -> Result<(), Box<dyn Error>> {
+    let canonical = fs::canonicalize(path)
+        .map_err(|error| format!("resolve GraphQL document {}: {error}", path.display()))?;
+    if !canonical.is_file() {
+        return Err(format!("GraphQL document {} is not a file", path.display()).into());
+    }
+    let relative = canonical.strip_prefix(project_root).map_err(|_| {
+        format!(
+            "GraphQL document {} resolves outside project root {}",
+            path.display(),
+            project_root.display()
+        )
+    })?;
+    let source_path = portable_relative_path(relative)?;
+    matched.entry(canonical).or_insert(source_path);
+    Ok(())
+}
+
+fn parse_client_route_registration(value: &str) -> Result<ClientRouteRegistration, Box<dyn Error>> {
+    let Some((operation, route)) = value.split_once('=') else {
+        return Err(format!("invalid --route `{value}`; expected OPERATION=/route").into());
+    };
+    if operation.trim().is_empty() || route.trim().is_empty() {
+        return Err(
+            format!("invalid --route `{value}`; expected non-empty OPERATION=/route").into(),
+        );
+    }
+    Ok(ClientRouteRegistration::new(operation.trim(), route.trim()))
+}
+
+fn portable_relative_path(path: &Path) -> Result<String, Box<dyn Error>> {
+    let mut parts = Vec::new();
+    for component in path.components() {
+        match component {
+            Component::Normal(value) => parts.push(value.to_string_lossy().into_owned()),
+            Component::CurDir => {}
+            _ => {
+                return Err(
+                    format!("path {} is not a portable relative path", path.display()).into(),
+                )
+            }
+        }
+    }
+    if parts.is_empty() {
+        return Err(format!("path {} has no file name", path.display()).into());
+    }
+    Ok(parts.join("/"))
+}
+
+fn generated_client_path(
+    root: &Path,
+    file: &GeneratedClientFile,
+) -> Result<PathBuf, Box<dyn Error>> {
+    let relative = Path::new(&file.path);
+    if relative.is_absolute()
+        || relative
+            .components()
+            .any(|component| !matches!(component, Component::Normal(_)))
+    {
+        return Err(format!("compiler produced unsafe generated path `{}`", file.path).into());
+    }
+    Ok(root.join(relative))
+}
+
+fn write_client_project(
+    root: &Path,
+    project: &GeneratedClientProject,
+) -> Result<(), Box<dyn Error>> {
+    validate_generated_client_files(&project.files)?;
+    validate_client_write_targets(root, &project.files)?;
+    let stale_files = stale_generated_client_files(root, project)?;
+    validate_client_output_convergence(root, project, &stale_files)?;
+    fs::create_dir_all(root)?;
+
+    for path in stale_files {
+        fs::remove_file(&path).map_err(|error| {
+            format!(
+                "remove stale generated client artifact {}: {error}",
+                path.display()
+            )
+        })?;
+    }
+
+    // Provenance is written last so an interrupted run never advertises a new
+    // complete generation before its operation modules exist.
+    let mut files = project.files.iter().collect::<Vec<_>>();
+    files.sort_by_key(|file| (file.path == "manifest.json", file.path.as_str()));
+    for file in files {
+        let path = generated_client_path(root, file)?;
+        if let Some(parent) = path.parent() {
+            fs::create_dir_all(parent)?;
+        }
+        fs::write(&path, &file.contents)
+            .map_err(|error| format!("write generated artifact {}: {error}", path.display()))?;
+    }
+    Ok(())
+}
+
+fn validate_client_output_convergence(
+    root: &Path,
+    project: &GeneratedClientProject,
+    stale_files: &[PathBuf],
+) -> Result<(), Box<dyn Error>> {
+    let expected = project
+        .files
+        .iter()
+        .map(|file| file.path.clone())
+        .collect::<BTreeSet<_>>();
+    let stale = stale_files
+        .iter()
+        .map(|path| {
+            path.strip_prefix(root)
+                .map_err(|_| {
+                    format!(
+                        "stale generated client path {} escaped output {}",
+                        path.display(),
+                        root.display()
+                    )
+                })
+                .and_then(|relative| {
+                    portable_relative_path(relative).map_err(|error| error.to_string())
+                })
+        })
+        .collect::<Result<BTreeSet<_>, _>>()?;
+    let unexpected = collect_generated_client_paths(root)?
+        .into_iter()
+        .filter(|path| !expected.contains(path) && !stale.contains(path))
+        .collect::<Vec<_>>();
+    if unexpected.is_empty() {
+        return Ok(());
+    }
+    Err(format!(
+        "generated output contains files without current or previous compiler ownership:\n  {}; refusing to write until they are moved or removed",
+        unexpected.join("\n  ")
+    )
+    .into())
+}
+
+fn validate_client_write_targets(
+    root: &Path,
+    files: &[GeneratedClientFile],
+) -> Result<(), Box<dyn Error>> {
+    match fs::symlink_metadata(root) {
+        Ok(metadata) if metadata.file_type().is_symlink() || !metadata.is_dir() => {
+            return Err(format!(
+                "generated output {} must be a real directory, not a symlink or other entry",
+                root.display()
+            )
+            .into())
+        }
+        Ok(_) => {}
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
+        Err(error) => {
+            return Err(format!("inspect generated output {}: {error}", root.display()).into())
+        }
+    }
+
+    for file in files {
+        let relative = Path::new(&file.path);
+        let mut current = root.to_path_buf();
+        let component_count = relative.components().count();
+        for (index, component) in relative.components().enumerate() {
+            let Component::Normal(component) = component else {
+                unreachable!("generated paths were validated before write-target inspection")
+            };
+            current.push(component);
+            let metadata = match fs::symlink_metadata(&current) {
+                Ok(metadata) => metadata,
+                Err(error) if error.kind() == std::io::ErrorKind::NotFound => break,
+                Err(error) => {
+                    return Err(format!(
+                        "inspect generated client path {}: {error}",
+                        current.display()
+                    )
+                    .into())
+                }
+            };
+            let is_target = index + 1 == component_count;
+            let valid = if is_target {
+                metadata.is_file() && !metadata.file_type().is_symlink()
+            } else {
+                metadata.is_dir() && !metadata.file_type().is_symlink()
+            };
+            if !valid {
+                return Err(format!(
+                    "generated client path {} contains a symlink or incompatible entry",
+                    current.display()
+                )
+                .into());
+            }
+        }
+    }
+    Ok(())
+}
+
+fn stale_generated_client_files(
+    root: &Path,
+    project: &GeneratedClientProject,
+) -> Result<Vec<PathBuf>, Box<dyn Error>> {
+    let provenance_path = root.join("manifest.json");
+    let metadata = match fs::symlink_metadata(&provenance_path) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
+        Err(error) => {
+            return Err(format!(
+                "inspect previous generated client manifest {}: {error}",
+                provenance_path.display()
+            )
+            .into())
+        }
+    };
+    if metadata.file_type().is_symlink() || !metadata.is_file() {
+        return Err(format!(
+            "previous generated client manifest {} must be a regular file",
+            provenance_path.display()
+        )
+        .into());
+    }
+
+    let source = read_utf8_bounded(
+        &provenance_path,
+        MAX_CLIENT_MANIFEST_BYTES,
+        "previous generated client manifest",
+    )?;
+    let provenance: serde_json::Value = serde_json::from_str(&source).map_err(|error| {
+        format!(
+            "parse previous generated client manifest {}: {error}; refusing to guess stale-file ownership",
+            provenance_path.display()
+        )
+    })?;
+    if provenance
+        .get("compiler_manifest_version")
+        .and_then(serde_json::Value::as_u64)
+        != Some(1)
+    {
+        return Err(format!(
+            "previous generated client manifest {} has an unsupported compiler_manifest_version; refusing to guess stale-file ownership",
+            provenance_path.display()
+        )
+        .into());
+    }
+    let operations = provenance
+        .get("operations")
+        .and_then(serde_json::Value::as_array)
+        .ok_or_else(|| {
+            format!(
+                "previous generated client manifest {} is missing operations; refusing to guess stale-file ownership",
+                provenance_path.display()
+            )
+        })?;
+    let expected = project
+        .files
+        .iter()
+        .map(|file| file.path.as_str())
+        .collect::<BTreeSet<_>>();
+    let mut stale = BTreeSet::new();
+    for (index, operation) in operations.iter().enumerate() {
+        let module_path = operation
+            .get("module_path")
+            .and_then(serde_json::Value::as_str)
+            .ok_or_else(|| {
+                format!(
+                    "previous generated client manifest {} operations[{index}] is missing module_path; refusing to guess stale-file ownership",
+                    provenance_path.display()
+                )
+            })?;
+        validate_previous_client_module_path(module_path)?;
+        if !expected.contains(module_path) {
+            stale.insert(module_path.to_string());
+        }
+    }
+
+    let mut paths = Vec::with_capacity(stale.len());
+    for relative in stale {
+        let path = root.join(&relative);
+        let metadata = match fs::symlink_metadata(&path) {
+            Ok(metadata) => metadata,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
+            Err(error) => {
+                return Err(format!(
+                    "inspect stale generated client artifact {}: {error}",
+                    path.display()
+                )
+                .into())
+            }
+        };
+        if metadata.file_type().is_symlink() || !metadata.is_file() {
+            return Err(format!(
+                "stale generated client artifact {} must be a regular file",
+                path.display()
+            )
+            .into());
+        }
+        let contents = read_utf8_bounded(
+            &path,
+            MAX_GENERATED_CLIENT_ARTIFACT_BYTES,
+            "stale generated client artifact",
+        )?;
+        if !contents.starts_with("/** GENERATED by dctl client. Do not edit. */") {
+            return Err(format!(
+                "refusing to remove {} because its compiler ownership marker is missing",
+                path.display()
+            )
+            .into());
+        }
+        paths.push(path);
+    }
+    Ok(paths)
+}
+
+fn validate_previous_client_module_path(path: &str) -> Result<(), Box<dyn Error>> {
+    let mut components = Path::new(path).components();
+    let valid = matches!(components.next(), Some(Component::Normal(value)) if value == "operations")
+        && matches!(components.next(), Some(Component::Normal(value)) if Path::new(value).extension().is_some_and(|extension| extension == "ts"))
+        && components.next().is_none();
+    if !valid {
+        return Err(format!(
+            "previous compiler provenance contains unsafe operation module path `{path}`; refusing to remove it"
+        )
+        .into());
+    }
+    Ok(())
+}
+
+fn check_client_project(
+    root: &Path,
+    project: &GeneratedClientProject,
+) -> Result<(), Box<dyn Error>> {
+    validate_generated_client_files(&project.files)?;
+    let expected = project
+        .files
+        .iter()
+        .map(|file| (file.path.clone(), file.contents.as_str()))
+        .collect::<BTreeMap<_, _>>();
+    let actual_paths = collect_generated_client_paths(root)?;
+    let mut drift = Vec::new();
+
+    for (path, contents) in &expected {
+        let full_path = root.join(path);
+        match fs::read_to_string(&full_path) {
+            Ok(actual) if actual == *contents => {}
+            Ok(_) => drift.push(format!("changed {path}")),
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                drift.push(format!("missing {path}"));
+            }
+            Err(error) => {
+                return Err(
+                    format!("read generated artifact {}: {error}", full_path.display()).into(),
+                )
+            }
+        }
+    }
+    for path in actual_paths {
+        if !expected.contains_key(&path) {
+            drift.push(format!("unexpected {path}"));
+        }
+    }
+    if drift.is_empty() {
+        return Ok(());
+    }
+    drift.sort();
+    Err(format!(
+        "generated Distributed client artifacts are stale:\n  {}\nrun `dctl client` without --check to regenerate",
+        drift.join("\n  ")
+    )
+    .into())
+}
+
+fn validate_generated_client_files(files: &[GeneratedClientFile]) -> Result<(), Box<dyn Error>> {
+    if files.is_empty() || files.len() > MAX_GENERATED_CLIENT_FILES {
+        return Err(format!(
+            "compiler produced {} files; expected 1..={MAX_GENERATED_CLIENT_FILES}",
+            files.len()
+        )
+        .into());
+    }
+    let mut paths = BTreeSet::new();
+    for file in files {
+        let _ = generated_client_path(Path::new("."), file)?;
+        if !paths.insert(file.path.as_str()) {
+            return Err(format!("compiler produced duplicate path `{}`", file.path).into());
+        }
+    }
+    Ok(())
+}
+
+fn collect_generated_client_paths(root: &Path) -> Result<BTreeSet<String>, Box<dyn Error>> {
+    let mut files = BTreeSet::new();
+    match fs::symlink_metadata(root) {
+        Ok(metadata) if metadata.file_type().is_symlink() || !metadata.is_dir() => {
+            return Err(format!(
+                "generated output {} must be a real directory, not a symlink or other entry",
+                root.display()
+            )
+            .into())
+        }
+        Ok(_) => {}
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(files),
+        Err(error) => {
+            return Err(format!("inspect generated output {}: {error}", root.display()).into())
+        }
+    }
+    let mut pending = vec![(root.to_path_buf(), PathBuf::new())];
+    while let Some((directory, relative)) = pending.pop() {
+        for entry in fs::read_dir(&directory)? {
+            let entry = entry?;
+            let file_type = entry.file_type()?;
+            let next_relative = relative.join(entry.file_name());
+            if file_type.is_symlink() {
+                return Err(format!(
+                    "generated output contains unsupported symlink {}",
+                    entry.path().display()
+                )
+                .into());
+            }
+            if file_type.is_dir() {
+                pending.push((entry.path(), next_relative));
+            } else if file_type.is_file() {
+                files.insert(portable_relative_path(&next_relative)?);
+                if files.len() > MAX_GENERATED_CLIENT_FILES {
+                    return Err(format!(
+                        "generated output {} exceeds {MAX_GENERATED_CLIENT_FILES} files",
+                        root.display()
+                    )
+                    .into());
+                }
+            } else {
+                return Err(format!(
+                    "generated output contains unsupported entry {}",
+                    entry.path().display()
+                )
+                .into());
+            }
+        }
+    }
+    Ok(files)
+}
+
+fn run_client_manifest(args: &ClientManifestArgs) -> Result<(), Box<dyn Error>> {
+    let json = run_manifest_harness(
         &HarnessOptions {
             path: args.path.clone(),
             manifest_path: args.manifest_path.clone(),
@@ -704,12 +1338,45 @@ fn run_schema(args: &SchemaArgs) -> Result<(), Box<dyn Error>> {
             entrypoint: args.entrypoint.clone(),
             distributed_path: args.distributed_path.clone(),
         },
-        HarnessMode::SchemaSql(args.dialect),
+        HarnessMode::ClientManifest,
     )?;
+    let manifest: serde_json::Value = serde_json::from_str(&json)?;
+    validate_client_manifest_json(&manifest)?;
+    println!("{}", serde_json::to_string_pretty(&manifest)?);
+    Ok(())
+}
+
+fn run_schema(args: &SchemaArgs) -> Result<(), Box<dyn Error>> {
+    let mode = match args.format {
+        SchemaFormat::Graphql => HarnessMode::SchemaGraphql,
+        _ => HarnessMode::SchemaSql(args.dialect),
+    };
+    let rendered = run_manifest_harness(
+        &HarnessOptions {
+            path: args.path.clone(),
+            manifest_path: args.manifest_path.clone(),
+            package: args.package.clone(),
+            features: args.features.clone(),
+            no_default_features: args.no_default_features,
+            entrypoint: args.entrypoint.clone(),
+            distributed_path: args.distributed_path.clone(),
+        },
+        mode,
+    ).map_err(|err| -> Box<dyn Error> {
+        let msg = err.to_string();
+        if msg.contains("graphql_sdl") || msg.contains("no method named `graphql_sdl`") {
+            format!(
+                "target service's distributed version predates graphql schema support — upgrade distributed to a version that provides DistributedProjectManifest::graphql_sdl(): {msg}"
+            ).into()
+        } else {
+            err
+        }
+    })?;
 
     let content = match args.format {
-        SchemaFormat::Sql => sql,
-        SchemaFormat::Atlas => render_atlas_schema(&atlas_spec_from_flags(args, sql)?)?,
+        SchemaFormat::Sql => rendered,
+        SchemaFormat::Atlas => render_atlas_schema(&atlas_spec_from_flags(args, rendered)?)?,
+        SchemaFormat::Graphql => rendered,
     };
 
     if let Some(out) = &args.out {
@@ -922,6 +1589,56 @@ fn validate_manifest_json(envelope: &serde_json::Value) -> Result<(), Box<dyn Er
     Ok(())
 }
 
+fn validate_client_manifest_json(manifest: &serde_json::Value) -> Result<(), Box<dyn Error>> {
+    let Some(version) = manifest
+        .get("manifest_version")
+        .and_then(serde_json::Value::as_u64)
+    else {
+        return Err("client manifest JSON is missing numeric manifest_version".into());
+    };
+    if version != DISTRIBUTED_CLIENT_MANIFEST_VERSION {
+        return Err(format!(
+            "unsupported Distributed client manifest version {version}; expected {DISTRIBUTED_CLIENT_MANIFEST_VERSION}"
+        )
+        .into());
+    }
+    if manifest
+        .get("protocol_version")
+        .and_then(serde_json::Value::as_u64)
+        .is_none()
+    {
+        return Err("client manifest JSON is missing numeric protocol_version".into());
+    }
+    for field in ["service_id", "schema_fingerprint", "protocol_fingerprint"] {
+        if manifest
+            .get(field)
+            .and_then(serde_json::Value::as_str)
+            .is_none()
+        {
+            return Err(format!("client manifest JSON is missing string {field}").into());
+        }
+    }
+    for field in ["surface", "capabilities"] {
+        if manifest
+            .get(field)
+            .and_then(serde_json::Value::as_object)
+            .is_none()
+        {
+            return Err(format!("client manifest JSON is missing object {field}").into());
+        }
+    }
+    for field in ["scalar_codecs", "models", "roots", "commands", "projectors"] {
+        if manifest
+            .get(field)
+            .and_then(serde_json::Value::as_array)
+            .is_none()
+        {
+            return Err(format!("client manifest JSON is missing array {field}").into());
+        }
+    }
+    Ok(())
+}
+
 pub(crate) fn resolve_distributed_path(
     provided: Option<&Path>,
     anchor: &Path,
@@ -1124,6 +1841,33 @@ mod tests {
         );
     }
 
+    #[test]
+    fn client_manifest_validator_accepts_only_current_version() {
+        let manifest = serde_json::json!({
+            "manifest_version": DISTRIBUTED_CLIENT_MANIFEST_VERSION,
+            "protocol_version": 1,
+            "service_id": "orders",
+            "schema_fingerprint": "sha256:schema",
+            "protocol_fingerprint": "sha256:protocol",
+            "surface": {},
+            "capabilities": {},
+            "scalar_codecs": [],
+            "models": [],
+            "roots": [],
+            "commands": [],
+            "projectors": []
+        });
+        validate_client_manifest_json(&manifest).expect("current manifest version");
+
+        let mut stale = manifest;
+        stale["manifest_version"] = serde_json::json!(3);
+        let error = validate_client_manifest_json(&stale)
+            .expect_err("pre-release v3 manifests must be rejected");
+        assert!(error.to_string().contains(&format!(
+            "version 3; expected {DISTRIBUTED_CLIENT_MANIFEST_VERSION}"
+        )));
+    }
+
     #[test]
     fn optional_github_repo_reports_the_flag_on_error() {
         let err = parse_optional_github_repo(Some("missing-repo"), "--github")
diff --git a/distributed_cli/src/client_compiler/command_manifest/confirmations.rs b/distributed_cli/src/client_compiler/command_manifest/confirmations.rs
new file mode 100644
index 00000000..1b93ba6f
--- /dev/null
+++ b/distributed_cli/src/client_compiler/command_manifest/confirmations.rs
@@ -0,0 +1,181 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use crate::client_compiler::manifest::{
+    ManifestCommand, ManifestConfirmationKind, ManifestConsistencyKind, ManifestField,
+    ManifestModel, ManifestProjector,
+};
+use crate::client_compiler::ClientCompileError;
+
+use super::effects::{require_model, validate_expression, validate_key};
+use super::support::{command_error, invalid, nonempty};
+use super::CommandManifestValidation;
+
+// Mirrors `projection_protocol::MAX_PROJECTION_EVIDENCE_BATCH_ITEMS`, which is
+// not exported across the `distributed`/`distributed_cli` package boundary.
+const MAX_CONFIRMATIONS: usize = 128;
+
+pub(super) fn validate_confirmations(
+    command: &ManifestCommand,
+    models: &BTreeMap<String, ManifestModel>,
+    projectors: &BTreeMap<&str, &ManifestProjector>,
+    report: &mut CommandManifestValidation,
+) -> Result<(), ClientCompileError> {
+    let confirmations = command.extensions.confirmations.as_ref();
+    match (command.extensions.consistency.kind, confirmations) {
+        (ManifestConsistencyKind::Fact, None) => {
+            return Err(command_error(
+                command,
+                "client.manifest.command_confirmations",
+                "fact consistency requires confirmations",
+            ));
+        }
+        (ManifestConsistencyKind::Projected, Some(_)) => {
+            return Err(command_error(
+                command,
+                "client.manifest.command_confirmations",
+                "projected consistency cannot declare asynchronous confirmations",
+            ));
+        }
+        _ => {}
+    }
+    let Some(confirmations) = confirmations else {
+        if command.extensions.consistency.kind == ManifestConsistencyKind::Accepted {
+            report
+                .commands_requiring_revalidation
+                .insert(command.name.clone());
+        }
+        return Ok(());
+    };
+    if confirmations.version != 1 {
+        return Err(command_error(
+            command,
+            "client.manifest.command_confirmations",
+            "confirmations.version must be 1",
+        ));
+    }
+    if confirmations.expected.len() > MAX_CONFIRMATIONS {
+        return Err(command_error(
+            command,
+            "client.manifest.command_confirmations",
+            format!(
+                "declares {} projector confirmations; maximum is {MAX_CONFIRMATIONS}",
+                confirmations.expected.len()
+            ),
+        ));
+    }
+    match confirmations.kind {
+        ManifestConfirmationKind::Unavailable => {
+            if !confirmations.expected.is_empty() {
+                return Err(command_error(
+                    command,
+                    "client.manifest.command_confirmations",
+                    "unavailable confirmations must have an empty expected inventory",
+                ));
+            }
+            report
+                .commands_requiring_revalidation
+                .insert(command.name.clone());
+            return Ok(());
+        }
+        ManifestConfirmationKind::Finite if confirmations.expected.is_empty() => {
+            return Err(command_error(
+                command,
+                "client.manifest.command_confirmations",
+                "finite confirmations must contain at least one expected target",
+            ));
+        }
+        ManifestConfirmationKind::Finite => {}
+    }
+
+    let mut seen = BTreeSet::new();
+    for confirmation in &confirmations.expected {
+        let projector = projectors
+            .get(confirmation.projector.as_str())
+            .copied()
+            .ok_or_else(|| {
+                command_error(
+                    command,
+                    "client.manifest.confirmation_projector",
+                    format!(
+                        "confirmation references unknown projector `{}`",
+                        confirmation.projector
+                    ),
+                )
+            })?;
+        if !projector.causal_confirmation
+            || !projector
+                .models
+                .iter()
+                .any(|model| model == &confirmation.model)
+        {
+            return Err(command_error(
+                command,
+                "client.manifest.confirmation_projector",
+                format!(
+                    "projector `{}` is not an authorized causal owner of model `{}`",
+                    projector.name, confirmation.model
+                ),
+            ));
+        }
+        let model = require_model(command, &confirmation.model, models)?;
+        validate_key(command, model, &confirmation.key, true, report)?;
+        if let Some(partition) = &confirmation.partition {
+            let expected = ManifestField {
+                name: "projector partition".into(),
+                scalar: "String".into(),
+                codec: "string".into(),
+                nullable: false,
+            };
+            validate_expression(command, partition, &expected)?;
+        }
+        let identity = serde_json::to_string(confirmation).map_err(|error| {
+            command_error(
+                command,
+                "client.manifest.command_confirmations",
+                format!("could not canonicalize confirmation: {error}"),
+            )
+        })?;
+        if !seen.insert(identity) {
+            return Err(command_error(
+                command,
+                "client.manifest.command_confirmations",
+                "repeats an expected projector confirmation",
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn validate_projector_inventory<'a>(
+    projectors: &'a [ManifestProjector],
+    models: &BTreeMap<String, ManifestModel>,
+) -> Result<BTreeMap<&'a str, &'a ManifestProjector>, ClientCompileError> {
+    let mut result = BTreeMap::new();
+    for projector in projectors {
+        if projector.version != 1 {
+            return Err(invalid(
+                "client.manifest.projector_version",
+                format!("projector `{}` must use version 1", projector.name),
+            ));
+        }
+        nonempty(&projector.name, "projector name")?;
+        for model in &projector.models {
+            if !models.contains_key(model) {
+                return Err(invalid(
+                    "client.manifest.projector_model",
+                    format!(
+                        "projector `{}` references unknown model `{model}`",
+                        projector.name
+                    ),
+                ));
+            }
+        }
+        if result.insert(projector.name.as_str(), projector).is_some() {
+            return Err(invalid(
+                "client.manifest.duplicate_projector",
+                format!("duplicate projector `{}`", projector.name),
+            ));
+        }
+    }
+    Ok(result)
+}
diff --git a/distributed_cli/src/client_compiler/command_manifest/effects.rs b/distributed_cli/src/client_compiler/command_manifest/effects.rs
new file mode 100644
index 00000000..580ffb24
--- /dev/null
+++ b/distributed_cli/src/client_compiler/command_manifest/effects.rs
@@ -0,0 +1,537 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use crate::client_compiler::manifest::{
+    ManifestCommand, ManifestCommandShape, ManifestEffect, ManifestEffectExpression,
+    ManifestEffectField, ManifestEffectKey, ManifestEffectRelationship, ManifestField,
+    ManifestInputDefault, ManifestModel, ManifestNormalization, ManifestTypeField,
+};
+use crate::client_compiler::ClientCompileError;
+
+use super::support::{command_error, constant_matches};
+use super::CommandManifestValidation;
+
+pub(super) fn validate_trusted_preset_inventory(
+    command: &ManifestCommand,
+) -> Result<(), ClientCompileError> {
+    fn expression_names<'a>(expression: &'a ManifestEffectExpression, out: &mut BTreeSet<&'a str>) {
+        if let ManifestEffectExpression::TrustedPreset { name } = expression {
+            out.insert(name);
+        }
+    }
+    fn key_names<'a>(key: &'a ManifestEffectKey, out: &mut BTreeSet<&'a str>) {
+        for field in &key.fields {
+            expression_names(&field.value, out);
+        }
+    }
+
+    let mut referenced = BTreeSet::new();
+    if let Some(effects) = &command.extensions.effects {
+        for effect in &effects.operations {
+            match effect {
+                ManifestEffect::Upsert { key, fields, .. }
+                | ManifestEffect::Patch { key, fields, .. } => {
+                    key_names(key, &mut referenced);
+                    for field in fields {
+                        expression_names(&field.value, &mut referenced);
+                    }
+                }
+                ManifestEffect::Delete { key, .. } => key_names(key, &mut referenced),
+                ManifestEffect::Link { source, target, .. }
+                | ManifestEffect::Unlink { source, target, .. } => {
+                    key_names(source, &mut referenced);
+                    key_names(target, &mut referenced);
+                }
+                ManifestEffect::InvalidateRelationship { source, .. } => {
+                    key_names(source, &mut referenced);
+                }
+                ManifestEffect::InvalidateModel { .. } => {}
+            }
+        }
+    }
+    if let Some(confirmations) = &command.extensions.confirmations {
+        for confirmation in &confirmations.expected {
+            key_names(&confirmation.key, &mut referenced);
+            if let Some(partition) = &confirmation.partition {
+                expression_names(partition, &mut referenced);
+            }
+        }
+    }
+    if let Some(direct) = &command.extensions.direct_projection {
+        if let Some(partition) = &direct.partition {
+            expression_names(partition, &mut referenced);
+        }
+    }
+
+    let declared = command
+        .extensions
+        .trusted_presets
+        .iter()
+        .map(|descriptor| descriptor.name.as_str())
+        .collect::<BTreeSet<_>>();
+    if declared != referenced {
+        return Err(command_error(
+            command,
+            "client.manifest.trusted_preset_inventory",
+            "trusted_presets must exactly describe every trusted preset expression",
+        ));
+    }
+    Ok(())
+}
+
+pub(super) fn validate_defaults(
+    command: &ManifestCommand,
+    version: u32,
+    defaults: &[ManifestInputDefault],
+) -> Result<(), ClientCompileError> {
+    if version != 1 || defaults.is_empty() {
+        return Err(command_error(
+            command,
+            "client.manifest.input_defaults",
+            "input_defaults must be version 1 with at least one entry",
+        ));
+    }
+    let ManifestCommandShape::Object { definition } = &command.input else {
+        return Err(command_error(
+            command,
+            "client.manifest.input_default_path",
+            "generated defaults require a typed object input",
+        ));
+    };
+    let mut paths = BTreeSet::new();
+    for default in defaults {
+        let [field_name] = default.path.as_slice() else {
+            return Err(command_error(
+                command,
+                "client.manifest.input_default_path",
+                "generated default must target exactly one top-level input field",
+            ));
+        };
+        if !paths.insert(field_name.as_str()) {
+            return Err(command_error(
+                command,
+                "client.manifest.input_default_path",
+                format!("repeats generated default path `{field_name}`"),
+            ));
+        }
+        let field = definition
+            .fields
+            .iter()
+            .find(|field| field.name == *field_name)
+            .ok_or_else(|| {
+                command_error(
+                    command,
+                    "client.manifest.input_default_path",
+                    format!("generated default references unknown input field `{field_name}`"),
+                )
+            })?;
+        if field.nullable
+            || field.list
+            || field.nested.is_some()
+            || !matches!(field.type_name.as_str(), "String" | "ID")
+        {
+            return Err(command_error(
+                command,
+                "client.manifest.input_default_path",
+                format!(
+                    "generated default `{field_name}` requires a non-null, non-list String/ID field"
+                ),
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn validate_effect(
+    command: &ManifestCommand,
+    effect: &ManifestEffect,
+    models: &BTreeMap<String, ManifestModel>,
+    report: &mut CommandManifestValidation,
+) -> Result<(), ClientCompileError> {
+    match effect {
+        ManifestEffect::Upsert { model, key, fields }
+        | ManifestEffect::Patch { model, key, fields } => {
+            let model = addressable_model(command, model, models)?;
+            validate_key(command, model, key, false, report)?;
+            validate_effect_fields(command, model, fields)
+        }
+        ManifestEffect::Delete { model, key } => {
+            let model = addressable_model(command, model, models)?;
+            validate_key(command, model, key, false, report)
+        }
+        ManifestEffect::Link {
+            relationship,
+            source,
+            target,
+        }
+        | ManifestEffect::Unlink {
+            relationship,
+            source,
+            target,
+        } => {
+            let (source_model, target_model) =
+                validate_relationship(command, relationship, models)?;
+            require_addressable(command, source_model)?;
+            require_addressable(command, target_model)?;
+            validate_key(command, source_model, source, false, report)?;
+            validate_key(command, target_model, target, false, report)
+        }
+        ManifestEffect::InvalidateModel { model } => {
+            require_model(command, model, models).map(|_| ())
+        }
+        ManifestEffect::InvalidateRelationship {
+            relationship,
+            source,
+        } => {
+            let (source_model, _) = validate_relationship(command, relationship, models)?;
+            require_addressable(command, source_model)?;
+            validate_key(command, source_model, source, false, report)
+        }
+    }
+}
+
+fn validate_effect_fields(
+    command: &ManifestCommand,
+    model: &ManifestModel,
+    fields: &[ManifestEffectField],
+) -> Result<(), ClientCompileError> {
+    let identity = model
+        .identity()
+        .expect("effect model addressability checked before field validation");
+    let mut names = BTreeSet::new();
+    for assignment in fields {
+        if !names.insert(assignment.field.as_str()) {
+            return Err(command_error(
+                command,
+                "client.manifest.effect_field",
+                format!("effect repeats `{}.{}`", model.id, assignment.field),
+            ));
+        }
+        let field = model.field(&assignment.field).ok_or_else(|| {
+            command_error(
+                command,
+                "client.manifest.effect_field",
+                format!(
+                    "effect references unknown field `{}.{}`",
+                    model.id, assignment.field
+                ),
+            )
+        })?;
+        if identity.iter().any(|key| key.name == assignment.field) {
+            return Err(command_error(
+                command,
+                "client.manifest.effect_field",
+                format!(
+                    "effect cannot assign identity field `{}.{}`",
+                    model.id, field.name
+                ),
+            ));
+        }
+        validate_expression(command, &assignment.value, field)?;
+    }
+    Ok(())
+}
+
+fn validate_relationship<'a>(
+    command: &ManifestCommand,
+    relationship: &ManifestEffectRelationship,
+    models: &'a BTreeMap<String, ManifestModel>,
+) -> Result<(&'a ManifestModel, &'a ManifestModel), ClientCompileError> {
+    let source = require_model(command, &relationship.source_model, models)?;
+    let declared = source.relationship(&relationship.field).ok_or_else(|| {
+        command_error(
+            command,
+            "client.manifest.effect_relationship",
+            format!(
+                "effect references unknown relationship `{}.{}`",
+                relationship.source_model, relationship.field
+            ),
+        )
+    })?;
+    if declared.target_model != relationship.target_model {
+        return Err(command_error(
+            command,
+            "client.manifest.effect_relationship",
+            format!(
+                "relationship `{}.{}` targets `{}`, not `{}`",
+                relationship.source_model,
+                relationship.field,
+                declared.target_model,
+                relationship.target_model
+            ),
+        ));
+    }
+    let target = require_model(command, &relationship.target_model, models)?;
+    Ok((source, target))
+}
+
+pub(super) fn validate_key(
+    command: &ManifestCommand,
+    model: &ManifestModel,
+    key: &ManifestEffectKey,
+    allow_embedded: bool,
+    report: &mut CommandManifestValidation,
+) -> Result<(), ClientCompileError> {
+    match &model.normalization {
+        ManifestNormalization::Normalized { fields, .. } => {
+            let actual = key
+                .fields
+                .iter()
+                .map(|field| field.field.as_str())
+                .collect::<Vec<_>>();
+            let expected = fields
+                .iter()
+                .map(|field| field.name.as_str())
+                .collect::<Vec<_>>();
+            if actual != expected {
+                return Err(command_error(
+                    command,
+                    "client.manifest.effect_key",
+                    format!(
+                        "key for `{}` must exactly match ordered identity ({})",
+                        model.id,
+                        expected.join(", ")
+                    ),
+                ));
+            }
+        }
+        ManifestNormalization::Embedded if allow_embedded => {
+            report
+                .commands_requiring_revalidation
+                .insert(command.name.clone());
+            if key.fields.is_empty() {
+                return Err(command_error(
+                    command,
+                    "client.manifest.confirmation_key",
+                    format!(
+                        "embedded confirmation key for `{}` must not be empty",
+                        model.id
+                    ),
+                ));
+            }
+            let mut names = BTreeSet::new();
+            if key
+                .fields
+                .iter()
+                .any(|field| !names.insert(field.field.as_str()))
+            {
+                return Err(command_error(
+                    command,
+                    "client.manifest.confirmation_key",
+                    format!(
+                        "embedded confirmation key for `{}` repeats a field",
+                        model.id
+                    ),
+                ));
+            }
+        }
+        ManifestNormalization::Embedded => {
+            return Err(command_error(
+                command,
+                "client.manifest.effect_identity",
+                format!(
+                    "key-addressed effect cannot target embedded model `{}`",
+                    model.id
+                ),
+            ));
+        }
+    }
+    for key_field in &key.fields {
+        let field = model.field(&key_field.field).ok_or_else(|| {
+            command_error(
+                command,
+                "client.manifest.effect_key",
+                format!(
+                    "key for `{}` references unknown field `{}`",
+                    model.id, key_field.field
+                ),
+            )
+        })?;
+        validate_expression(command, &key_field.value, field)?;
+    }
+    Ok(())
+}
+
+pub(super) fn validate_expression(
+    command: &ManifestCommand,
+    expression: &ManifestEffectExpression,
+    expected: &ManifestField,
+) -> Result<(), ClientCompileError> {
+    match expression {
+        ManifestEffectExpression::Input { path } => {
+            let (field, inherited_nullable) = input_field(command, path)?;
+            let json_container =
+                expected.scalar == "JSON" && (field.list || field.nested.is_some());
+            if !json_container
+                && (field.list || field.nested.is_some() || field.type_name != expected.scalar)
+            {
+                return Err(command_error(
+                    command,
+                    "client.manifest.effect_input_type",
+                    format!(
+                        "input `{}` cannot populate `{}:{}`",
+                        path.join("."),
+                        expected.name,
+                        expected.scalar
+                    ),
+                ));
+            }
+            if (inherited_nullable || field.nullable) && !expected.nullable {
+                return Err(command_error(
+                    command,
+                    "client.manifest.effect_input_nullability",
+                    format!(
+                        "nullable input `{}` cannot populate non-null field `{}`",
+                        path.join("."),
+                        expected.name
+                    ),
+                ));
+            }
+            Ok(())
+        }
+        ManifestEffectExpression::TrustedPreset { name } => {
+            let descriptor = command
+                .extensions
+                .trusted_presets
+                .iter()
+                .find(|descriptor| descriptor.name == *name)
+                .ok_or_else(|| {
+                    command_error(
+                        command,
+                        "client.manifest.effect_trusted_preset",
+                        format!("uses undeclared trusted preset `{name}`"),
+                    )
+                })?;
+            if descriptor.codec != expected.codec {
+                return Err(command_error(
+                    command,
+                    "client.manifest.effect_trusted_preset",
+                    format!(
+                        "trusted preset `{name}` codec `{}` cannot populate `{}:{}` with codec `{}`",
+                        descriptor.codec,
+                        expected.name,
+                        expected.scalar,
+                        expected.codec
+                    ),
+                ));
+            }
+            Ok(())
+        }
+        ManifestEffectExpression::Constant { value } if constant_matches(value, expected) => Ok(()),
+        ManifestEffectExpression::Constant { .. } => Err(command_error(
+            command,
+            "client.manifest.effect_constant",
+            format!(
+                "constant is incompatible with field `{}` (`{}`)",
+                expected.name, expected.scalar
+            ),
+        )),
+        ManifestEffectExpression::Null if expected.nullable => Ok(()),
+        ManifestEffectExpression::Null => Err(command_error(
+            command,
+            "client.manifest.effect_null",
+            format!("null cannot populate non-null field `{}`", expected.name),
+        )),
+    }
+}
+
+fn input_field<'a>(
+    command: &'a ManifestCommand,
+    path: &[String],
+) -> Result<(&'a ManifestTypeField, bool), ClientCompileError> {
+    if path.is_empty() {
+        return Err(command_error(
+            command,
+            "client.manifest.effect_input_path",
+            "effect input path must not be empty",
+        ));
+    }
+    let ManifestCommandShape::Object { definition } = &command.input else {
+        return Err(command_error(
+            command,
+            "client.manifest.effect_input_path",
+            "effect input references require a typed object input",
+        ));
+    };
+    let mut current = definition;
+    let mut inherited_nullable = false;
+    for (index, segment) in path.iter().enumerate() {
+        let field = current
+            .fields
+            .iter()
+            .find(|field| field.name == *segment)
+            .ok_or_else(|| {
+                command_error(
+                    command,
+                    "client.manifest.effect_input_path",
+                    format!("effect references unknown input path `{}`", path.join(".")),
+                )
+            })?;
+        if index + 1 == path.len() {
+            return Ok((field, inherited_nullable));
+        }
+        if field.list {
+            return Err(command_error(
+                command,
+                "client.manifest.effect_input_path",
+                format!(
+                    "effect input path `{}` descends through a list",
+                    path.join(".")
+                ),
+            ));
+        }
+        inherited_nullable |= field.nullable;
+        current = field.nested.as_deref().ok_or_else(|| {
+            command_error(
+                command,
+                "client.manifest.effect_input_path",
+                format!(
+                    "effect input path `{}` descends through a scalar",
+                    path.join(".")
+                ),
+            )
+        })?;
+    }
+    unreachable!("a non-empty path either resolves or returns an error")
+}
+
+fn addressable_model<'a>(
+    command: &ManifestCommand,
+    name: &str,
+    models: &'a BTreeMap<String, ManifestModel>,
+) -> Result<&'a ManifestModel, ClientCompileError> {
+    let model = require_model(command, name, models)?;
+    require_addressable(command, model)?;
+    Ok(model)
+}
+
+fn require_addressable(
+    command: &ManifestCommand,
+    model: &ManifestModel,
+) -> Result<(), ClientCompileError> {
+    if model.identity().is_some_and(|fields| !fields.is_empty()) {
+        Ok(())
+    } else {
+        Err(command_error(
+            command,
+            "client.manifest.effect_identity",
+            format!(
+                "key-addressed effect cannot target embedded model `{}`",
+                model.id
+            ),
+        ))
+    }
+}
+
+pub(super) fn require_model<'a>(
+    command: &ManifestCommand,
+    name: &str,
+    models: &'a BTreeMap<String, ManifestModel>,
+) -> Result<&'a ManifestModel, ClientCompileError> {
+    models.get(name).ok_or_else(|| {
+        command_error(
+            command,
+            "client.manifest.effect_model",
+            format!("references unknown model `{name}`"),
+        )
+    })
+}
diff --git a/distributed_cli/src/client_compiler/command_manifest/mod.rs b/distributed_cli/src/client_compiler/command_manifest/mod.rs
new file mode 100644
index 00000000..4df64405
--- /dev/null
+++ b/distributed_cli/src/client_compiler/command_manifest/mod.rs
@@ -0,0 +1,20 @@
+use std::collections::BTreeSet;
+
+mod confirmations;
+mod effects;
+mod protocol;
+mod shape;
+mod support;
+mod validation;
+
+pub(crate) use validation::validate_command_manifest;
+
+/// Semantic command validation which cannot be expressed by serde alone.
+///
+/// A command is included in `commands_requiring_revalidation` when its
+/// authorized manifest intentionally withholds an exact optimistic effect or
+/// finite confirmation plan.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub(crate) struct CommandManifestValidation {
+    pub(crate) commands_requiring_revalidation: BTreeSet<String>,
+}
diff --git a/distributed_cli/src/client_compiler/command_manifest/protocol.rs b/distributed_cli/src/client_compiler/command_manifest/protocol.rs
new file mode 100644
index 00000000..33c6ff47
--- /dev/null
+++ b/distributed_cli/src/client_compiler/command_manifest/protocol.rs
@@ -0,0 +1,45 @@
+use crate::client_compiler::manifest::{validate_exact_operation_hash, ManifestProtocolOperations};
+use crate::client_compiler::ClientCompileError;
+
+use super::support::invalid;
+
+const COMMAND_STATUS_OPERATION: &str =
+    "query Distributed_CommandStatus($commandId: ID!) { commandStatus(commandId: $commandId) { state } }";
+
+pub(super) fn validate_protocol_operations(
+    operations: &ManifestProtocolOperations,
+    commands_present: bool,
+) -> Result<(), ClientCompileError> {
+    if operations.version != 1 {
+        return Err(invalid(
+            "client.manifest.protocol_operations",
+            "manifest.protocol_operations.version must be 1",
+        ));
+    }
+    match (&operations.command_status, commands_present) {
+        (None, true) => Err(invalid(
+            "client.manifest.command_status",
+            "manifest commands require the framework command-status operation",
+        )),
+        (Some(_), false) => Err(invalid(
+            "client.manifest.command_status",
+            "query-only manifests must not expose a command-status operation",
+        )),
+        (None, false) => Ok(()),
+        (Some(status), true) => {
+            if status.name != "Distributed_CommandStatus"
+                || status.operation != COMMAND_STATUS_OPERATION
+            {
+                return Err(invalid(
+                    "client.manifest.command_status",
+                    "command-status operation does not byte-match the framework contract",
+                ));
+            }
+            validate_exact_operation_hash(
+                &status.operation,
+                &status.operation_hash,
+                "command status",
+            )
+        }
+    }
+}
diff --git a/distributed_cli/src/client_compiler/command_manifest/shape.rs b/distributed_cli/src/client_compiler/command_manifest/shape.rs
new file mode 100644
index 00000000..279904b8
--- /dev/null
+++ b/distributed_cli/src/client_compiler/command_manifest/shape.rs
@@ -0,0 +1,264 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use crate::client_compiler::manifest::{
+    ManifestCommand, ManifestCommandShape, ManifestConsistencyKind, ManifestModel, ManifestRoot,
+    ManifestTypeDef, RootOperation,
+};
+use crate::client_compiler::ClientCompileError;
+
+use super::support::{graphql_name, invalid};
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(super) enum CommandTypeKind {
+    Input,
+    Output,
+}
+
+pub(super) fn projected_output_typename<'a>(
+    command: &ManifestCommand,
+    models: &'a BTreeMap<String, ManifestModel>,
+) -> Option<&'a str> {
+    if let Some(target) = command.extensions.direct_projection.as_ref() {
+        if let Some(model) = models.get(&target.model) {
+            return Some(model.typename.as_str());
+        }
+    }
+    let consistency = &command.extensions.consistency;
+    if consistency.kind != ManifestConsistencyKind::Projected {
+        return None;
+    }
+    let ManifestCommandShape::Object { definition } = &command.output else {
+        return None;
+    };
+    models
+        .values()
+        .find(|model| model.typename == definition.name)
+        .map(|model| model.typename.as_str())
+}
+
+pub(super) fn occupied_surface_types(
+    models: &BTreeMap<String, ManifestModel>,
+    roots: &BTreeMap<(RootOperation, String), ManifestRoot>,
+    scalar_codecs: &BTreeMap<String, String>,
+) -> BTreeSet<String> {
+    let mut occupied = ["Query", "Mutation", "Subscription", "order_by"]
+        .into_iter()
+        .map(str::to_string)
+        .collect::<BTreeSet<_>>();
+    occupied.extend(scalar_codecs.keys().cloned());
+    for model in models.values() {
+        occupied.insert(model.typename.clone());
+        for relationship in &model.relationships {
+            occupied.insert(relationship.target_typename.clone());
+            occupied.extend(
+                relationship
+                    .arguments
+                    .iter()
+                    .map(|argument| argument.type_name.clone()),
+            );
+            if let Some(aggregate) = &relationship.aggregate {
+                occupied.insert(aggregate.semantics.wrapper_typename.clone());
+                occupied.insert(aggregate.semantics.fields_typename.clone());
+                occupied.extend(
+                    aggregate
+                        .arguments
+                        .iter()
+                        .map(|argument| argument.type_name.clone()),
+                );
+            }
+        }
+    }
+    for root in roots.values() {
+        occupied.extend(
+            root.arguments
+                .iter()
+                .map(|argument| argument.type_name.clone()),
+        );
+        if let Some(aggregate) = &root.aggregate {
+            occupied.insert(aggregate.wrapper_typename.clone());
+            occupied.insert(aggregate.fields_typename.clone());
+        }
+    }
+    occupied
+}
+
+pub(super) fn validate_shape(
+    shape: &ManifestCommandShape,
+    kind: CommandTypeKind,
+    scalar_codecs: &BTreeMap<String, String>,
+    label: &str,
+    occupied_types: &BTreeSet<String>,
+    allowed_occupied_type: Option<&str>,
+    definitions: &mut BTreeMap<String, (CommandTypeKind, ManifestTypeDef)>,
+) -> Result<(), ClientCompileError> {
+    match shape {
+        ManifestCommandShape::None => Ok(()),
+        ManifestCommandShape::Object { definition } => validate_type_def(
+            definition,
+            kind,
+            scalar_codecs,
+            label,
+            occupied_types,
+            allowed_occupied_type,
+            definitions,
+        ),
+    }
+}
+
+fn validate_type_def(
+    definition: &ManifestTypeDef,
+    kind: CommandTypeKind,
+    scalar_codecs: &BTreeMap<String, String>,
+    label: &str,
+    occupied_types: &BTreeSet<String>,
+    allowed_occupied_type: Option<&str>,
+    definitions: &mut BTreeMap<String, (CommandTypeKind, ManifestTypeDef)>,
+) -> Result<(), ClientCompileError> {
+    graphql_name(&definition.name, &format!("{label} type"))?;
+    if occupied_types.contains(&definition.name)
+        && allowed_occupied_type != Some(definition.name.as_str())
+    {
+        return Err(invalid(
+            "client.manifest.command_type_namespace",
+            format!(
+                "{label} type `{}` collides with an occupied GraphQL surface type",
+                definition.name
+            ),
+        ));
+    }
+    if let Some((previous_kind, previous)) = definitions.get(&definition.name) {
+        return if *previous_kind == kind && previous == definition {
+            Ok(())
+        } else {
+            Err(invalid(
+                "client.manifest.command_type_reference",
+                format!(
+                    "GraphQL type `{}` has ambiguous input/output or structural definitions",
+                    definition.name
+                ),
+            ))
+        };
+    }
+    definitions.insert(definition.name.clone(), (kind, definition.clone()));
+    if definition.fields.is_empty() {
+        return Err(invalid(
+            "client.manifest.command_type_fields",
+            format!("{label} type `{}` must contain a field", definition.name),
+        ));
+    }
+    let mut names = BTreeSet::new();
+    let mut previous = None;
+    for field in &definition.fields {
+        graphql_name(&field.name, &format!("{label} field"))?;
+        graphql_name(&field.type_name, &format!("{label} field type"))?;
+        if !names.insert(field.name.as_str()) {
+            return Err(invalid(
+                "client.manifest.command_type_field",
+                format!("{label} repeats field `{}`", field.name),
+            ));
+        }
+        if previous.is_some_and(|name| name >= field.name.as_str()) {
+            return Err(invalid(
+                "client.manifest.command_type_field",
+                format!("{label} fields must use canonical name order"),
+            ));
+        }
+        previous = Some(field.name.as_str());
+        if field.item_nullable && !field.list {
+            return Err(invalid(
+                "client.manifest.command_type_nullability",
+                format!(
+                    "{label} field `{}` marks a non-list item nullable",
+                    field.name
+                ),
+            ));
+        }
+        match (&field.codec, &field.nested) {
+            (Some(codec), None) => {
+                validate_codec(&field.type_name, codec, scalar_codecs, label)?;
+            }
+            (None, Some(nested)) if nested.name == field.type_name => {
+                validate_type_def(
+                    nested,
+                    kind,
+                    scalar_codecs,
+                    &format!("{label}.{}", field.name),
+                    occupied_types,
+                    None,
+                    definitions,
+                )?;
+            }
+            (None, Some(_)) => {
+                return Err(invalid(
+                    "client.manifest.command_type_reference",
+                    format!(
+                        "{label} field `{}` type does not match its nested definition",
+                        field.name
+                    ),
+                ));
+            }
+            _ => {
+                return Err(invalid(
+                    "client.manifest.command_type_codec",
+                    format!(
+                        "{label} field `{}` must declare exactly one scalar codec or nested type",
+                        field.name
+                    ),
+                ));
+            }
+        }
+    }
+    Ok(())
+}
+
+fn validate_codec(
+    scalar: &str,
+    codec: &str,
+    scalar_codecs: &BTreeMap<String, String>,
+    label: &str,
+) -> Result<(), ClientCompileError> {
+    match scalar_codecs.get(scalar) {
+        Some(expected) if expected == codec => Ok(()),
+        Some(expected) => Err(invalid(
+            "client.manifest.command_type_codec",
+            format!("{label} codec `{codec}` does not match `{scalar}` codec `{expected}`"),
+        )),
+        None => Err(invalid(
+            "client.manifest.command_type_scalar",
+            format!("{label} references unsupported scalar `{scalar}`"),
+        )),
+    }
+}
+
+pub(super) fn canonical_command_operation(command: &ManifestCommand) -> String {
+    let operation_name = format!("Client_{}", command.mutation_field);
+    let (variables, arguments) = match &command.input {
+        ManifestCommandShape::None => ("($commandId: ID!)".to_string(), "(commandId: $commandId)"),
+        ManifestCommandShape::Object { definition } => (
+            format!("($commandId: ID!, $input: {}!)", definition.name),
+            "(commandId: $commandId, input: $input)",
+        ),
+    };
+    let selection = match &command.output {
+        ManifestCommandShape::Object { definition } => {
+            format!(" {{ {} }}", command_selection(definition))
+        }
+        ManifestCommandShape::None => String::new(),
+    };
+    format!(
+        "mutation {operation_name}{variables} {{ {}{arguments}{selection} }}",
+        command.mutation_field
+    )
+}
+
+fn command_selection(definition: &ManifestTypeDef) -> String {
+    definition
+        .fields
+        .iter()
+        .map(|field| match &field.nested {
+            Some(nested) => format!("{} {{ {} }}", field.name, command_selection(nested)),
+            None => field.name.clone(),
+        })
+        .collect::<Vec<_>>()
+        .join(" ")
+}
diff --git a/distributed_cli/src/client_compiler/command_manifest/support.rs b/distributed_cli/src/client_compiler/command_manifest/support.rs
new file mode 100644
index 00000000..96a88a5c
--- /dev/null
+++ b/distributed_cli/src/client_compiler/command_manifest/support.rs
@@ -0,0 +1,147 @@
+use std::collections::BTreeSet;
+
+use base64::Engine as _;
+use serde_json::Value as JsonValue;
+
+use crate::client_compiler::manifest::{ManifestCommand, ManifestField};
+use crate::client_compiler::ClientCompileError;
+
+pub(super) fn constant_matches(value: &JsonValue, expected: &ManifestField) -> bool {
+    if expected.scalar == "JSON" {
+        return true;
+    }
+    match (expected.scalar.as_str(), value) {
+        ("Boolean", JsonValue::Bool(_)) => true,
+        ("BigInt", JsonValue::Number(number)) => number.is_i64() || number.is_u64(),
+        ("Int", JsonValue::Number(number)) => {
+            number
+                .as_i64()
+                .is_some_and(|value| i32::try_from(value).is_ok())
+                || number
+                    .as_u64()
+                    .is_some_and(|value| i32::try_from(value).is_ok())
+        }
+        ("Float", JsonValue::Number(_)) => true,
+        ("String" | "ID", JsonValue::String(_)) => true,
+        ("Timestamptz", JsonValue::String(value)) => is_rfc3339(value),
+        ("Bytea", JsonValue::String(value)) => base64::engine::general_purpose::STANDARD
+            .decode(value)
+            .is_ok(),
+        _ => false,
+    }
+}
+
+fn is_rfc3339(value: &str) -> bool {
+    let bytes = value.as_bytes();
+    if bytes.len() < 20
+        || bytes.get(4) != Some(&b'-')
+        || bytes.get(7) != Some(&b'-')
+        || !matches!(bytes.get(10), Some(b'T' | b't'))
+        || bytes.get(13) != Some(&b':')
+        || bytes.get(16) != Some(&b':')
+    {
+        return false;
+    }
+    let number = |range: std::ops::Range<usize>| {
+        std::str::from_utf8(bytes.get(range)?)
+            .ok()?
+            .parse::<u32>()
+            .ok()
+    };
+    let (Some(year), Some(month), Some(day), Some(hour), Some(minute), Some(second)) = (
+        number(0..4),
+        number(5..7),
+        number(8..10),
+        number(11..13),
+        number(14..16),
+        number(17..19),
+    ) else {
+        return false;
+    };
+    let leap = year % 4 == 0 && (year % 100 != 0 || year % 400 == 0);
+    let max_day = match month {
+        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
+        4 | 6 | 9 | 11 => 30,
+        2 if leap => 29,
+        2 => 28,
+        _ => return false,
+    };
+    if day == 0 || day > max_day || hour > 23 || minute > 59 || second > 60 {
+        return false;
+    }
+    let mut cursor = 19;
+    if bytes.get(cursor) == Some(&b'.') {
+        cursor += 1;
+        let start = cursor;
+        while bytes.get(cursor).is_some_and(u8::is_ascii_digit) {
+            cursor += 1;
+        }
+        if cursor == start {
+            return false;
+        }
+    }
+    match bytes.get(cursor) {
+        Some(b'Z' | b'z') => cursor + 1 == bytes.len(),
+        Some(b'+' | b'-') if cursor + 6 == bytes.len() && bytes.get(cursor + 3) == Some(&b':') => {
+            matches!(
+                (
+                    number(cursor + 1..cursor + 3),
+                    number(cursor + 4..cursor + 6)
+                ),
+                (Some(0..=23), Some(0..=59))
+            )
+        }
+        _ => false,
+    }
+}
+
+pub(super) fn graphql_name(value: &str, label: &str) -> Result<(), ClientCompileError> {
+    if !crate::client_compiler::is_graphql_name(value) || value.starts_with("__") {
+        Err(invalid(
+            "client.manifest.graphql_name",
+            format!("{label} `{value}` must be a valid GraphQL name"),
+        ))
+    } else {
+        Ok(())
+    }
+}
+
+pub(super) fn unique_nonempty(values: &[String], label: &str) -> Result<(), ClientCompileError> {
+    let mut seen = BTreeSet::new();
+    for value in values {
+        nonempty(value, label)?;
+        if !seen.insert(value) {
+            return Err(invalid(
+                "client.manifest.duplicate_entry",
+                format!("{label} entries must be unique"),
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn nonempty(value: &str, label: &str) -> Result<(), ClientCompileError> {
+    if value.trim().is_empty() {
+        Err(invalid(
+            "client.manifest.empty",
+            format!("{label} must not be empty"),
+        ))
+    } else {
+        Ok(())
+    }
+}
+
+pub(super) fn command_error(
+    command: &ManifestCommand,
+    code: &'static str,
+    message: impl std::fmt::Display,
+) -> ClientCompileError {
+    invalid(
+        code,
+        format!("manifest command `{}` {message}", command.name),
+    )
+}
+
+pub(super) fn invalid(code: &'static str, message: impl Into<String>) -> ClientCompileError {
+    ClientCompileError::manifest(code, message)
+}
diff --git a/distributed_cli/src/client_compiler/command_manifest/validation.rs b/distributed_cli/src/client_compiler/command_manifest/validation.rs
new file mode 100644
index 00000000..293448b4
--- /dev/null
+++ b/distributed_cli/src/client_compiler/command_manifest/validation.rs
@@ -0,0 +1,172 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use crate::client_compiler::manifest::{
+    validate_exact_operation_hash, ManifestCommand, ManifestCommandShape, ManifestModel,
+    ManifestProjector, ManifestProtocolOperations, ManifestRoot, ManifestTypeDef, RootOperation,
+};
+use crate::client_compiler::ClientCompileError;
+
+use super::confirmations::{validate_confirmations, validate_projector_inventory};
+use super::effects::{validate_defaults, validate_effect, validate_trusted_preset_inventory};
+use super::protocol::validate_protocol_operations;
+use super::shape::{
+    canonical_command_operation, occupied_surface_types, projected_output_typename, validate_shape,
+    CommandTypeKind,
+};
+use super::support::{command_error, graphql_name, invalid, nonempty, unique_nonempty};
+use super::CommandManifestValidation;
+
+pub(crate) fn validate_command_manifest(
+    commands: &[ManifestCommand],
+    models: &BTreeMap<String, ManifestModel>,
+    roots: &BTreeMap<(RootOperation, String), ManifestRoot>,
+    scalar_codecs: &BTreeMap<String, String>,
+    projectors: &[ManifestProjector],
+    causal_receipts: bool,
+    protocol_operations: &ManifestProtocolOperations,
+) -> Result<CommandManifestValidation, ClientCompileError> {
+    if causal_receipts != !commands.is_empty() {
+        return Err(invalid(
+            "client.manifest.command_capability",
+            "manifest command inventory and capabilities.causal_receipts must agree",
+        ));
+    }
+    validate_protocol_operations(protocol_operations, !commands.is_empty())?;
+    let projectors = validate_projector_inventory(projectors, models)?;
+    let occupied_types = occupied_surface_types(models, roots, scalar_codecs);
+
+    let mut command_names = BTreeSet::new();
+    let mut mutation_fields = BTreeSet::new();
+    let mut type_definitions = BTreeMap::new();
+    let mut report = CommandManifestValidation::default();
+    for command in commands {
+        validate_command(
+            command,
+            models,
+            scalar_codecs,
+            &projectors,
+            &occupied_types,
+            &mut type_definitions,
+            &mut report,
+        )?;
+        if !command_names.insert(command.name.as_str()) {
+            return Err(invalid(
+                "client.manifest.duplicate_command",
+                format!("duplicate manifest command `{}`", command.name),
+            ));
+        }
+        if !mutation_fields.insert(command.mutation_field.as_str()) {
+            return Err(invalid(
+                "client.manifest.duplicate_command_field",
+                format!(
+                    "duplicate manifest command mutation field `{}`",
+                    command.mutation_field
+                ),
+            ));
+        }
+    }
+    Ok(report)
+}
+
+fn validate_command(
+    command: &ManifestCommand,
+    models: &BTreeMap<String, ManifestModel>,
+    scalar_codecs: &BTreeMap<String, String>,
+    projectors: &BTreeMap<&str, &ManifestProjector>,
+    occupied_types: &BTreeSet<String>,
+    type_definitions: &mut BTreeMap<String, (CommandTypeKind, ManifestTypeDef)>,
+    report: &mut CommandManifestValidation,
+) -> Result<(), ClientCompileError> {
+    if command.version != 1 {
+        return Err(command_error(
+            command,
+            "client.manifest.command_version",
+            "version must be 1",
+        ));
+    }
+    nonempty(&command.name, "command name")?;
+    graphql_name(&command.mutation_field, "command mutation field")?;
+    unique_nonempty(
+        &command.grants,
+        &format!("command `{}` grant", command.name),
+    )?;
+
+    validate_shape(
+        &command.input,
+        CommandTypeKind::Input,
+        scalar_codecs,
+        &format!("command `{}` input", command.name),
+        occupied_types,
+        None,
+        type_definitions,
+    )?;
+    if matches!(command.output, ManifestCommandShape::None) {
+        return Err(command_error(
+            command,
+            "client.manifest.command_output",
+            "cannot declare an empty output",
+        ));
+    }
+    validate_shape(
+        &command.output,
+        CommandTypeKind::Output,
+        scalar_codecs,
+        &format!("command `{}` output", command.name),
+        occupied_types,
+        projected_output_typename(command, models),
+        type_definitions,
+    )?;
+
+    let canonical = canonical_command_operation(command);
+    if command.operation != canonical {
+        return Err(command_error(
+            command,
+            "client.manifest.command_operation",
+            "operation does not byte-match the canonical typed command operation",
+        ));
+    }
+    validate_exact_operation_hash(&command.operation, &command.operation_hash, "command")?;
+
+    let extensions = &command.extensions;
+    if extensions.version != 1 {
+        return Err(command_error(
+            command,
+            "client.manifest.command_extensions",
+            "extensions.version must be 1",
+        ));
+    }
+    let consistency = &extensions.consistency;
+    if consistency.version != 1 {
+        return Err(command_error(
+            command,
+            "client.manifest.command_consistency",
+            "consistency.version must be 1",
+        ));
+    }
+    if let Some(defaults) = &extensions.input_defaults {
+        validate_defaults(command, defaults.version, &defaults.defaults)?;
+    }
+    if let Some(effects) = &extensions.effects {
+        if effects.version != 1 {
+            return Err(command_error(
+                command,
+                "client.manifest.command_effects",
+                "effects.version must be 1",
+            ));
+        }
+        if effects.operations.is_empty() {
+            report
+                .commands_requiring_revalidation
+                .insert(command.name.clone());
+        }
+        for effect in &effects.operations {
+            validate_effect(command, effect, models, report)?;
+        }
+    } else {
+        report
+            .commands_requiring_revalidation
+            .insert(command.name.clone());
+    }
+    validate_confirmations(command, models, projectors, report)?;
+    validate_trusted_preset_inventory(command)
+}
diff --git a/distributed_cli/src/client_compiler/command_manifest_tests.rs b/distributed_cli/src/client_compiler/command_manifest_tests.rs
new file mode 100644
index 00000000..aa832485
--- /dev/null
+++ b/distributed_cli/src/client_compiler/command_manifest_tests.rs
@@ -0,0 +1,515 @@
+use std::collections::BTreeMap;
+
+use serde_json::json;
+
+use super::command_manifest::validate_command_manifest;
+use super::manifest::{
+    hash_bytes, ManifestCommand, ManifestCommandConsistency, ManifestCommandExtensions,
+    ManifestCommandShape, ManifestConfirmation, ManifestConfirmationKind, ManifestConfirmations,
+    ManifestConsistencyKind, ManifestEffect, ManifestEffectExpression, ManifestEffectField,
+    ManifestEffectKey, ManifestEffects, ManifestField, ManifestFilterField, ManifestFilterInput,
+    ManifestInputDefault, ManifestInputDefaultGenerator, ManifestInputDefaults, ManifestKeyField,
+    ManifestModel, ManifestNormalization, ManifestProjector, ManifestProtocolOperation,
+    ManifestProtocolOperations, ManifestRevalidationFallback, ManifestRowPolicy,
+    ManifestTrustedPresetDescriptor, ManifestTypeDef, ManifestTypeField,
+};
+
+fn field(
+    name: &str,
+    type_name: &str,
+    codec: Option<&str>,
+    nested: Option<ManifestTypeDef>,
+) -> ManifestTypeField {
+    ManifestTypeField {
+        name: name.into(),
+        type_name: type_name.into(),
+        nullable: false,
+        list: false,
+        item_nullable: false,
+        codec: codec.map(str::to_string),
+        nested: nested.map(Box::new),
+    }
+}
+
+fn model() -> ManifestModel {
+    ManifestModel {
+        id: "Todo".into(),
+        typename: "Todo".into(),
+        source_table: "todos".into(),
+        dependencies: vec!["todos".into()],
+        normalization: ManifestNormalization::Normalized {
+            fields: vec![ManifestKeyField {
+                name: "id".into(),
+                codec: "string".into(),
+            }],
+            encoding: "length_prefixed_v1".into(),
+        },
+        fields: vec![
+            ManifestField {
+                name: "id".into(),
+                scalar: "ID".into(),
+                codec: "string".into(),
+                nullable: false,
+            },
+            ManifestField {
+                name: "payload".into(),
+                scalar: "Bytea".into(),
+                codec: "base64".into(),
+                nullable: false,
+            },
+            ManifestField {
+                name: "title".into(),
+                scalar: "String".into(),
+                codec: "string".into(),
+                nullable: false,
+            },
+        ],
+        relationships: Vec::new(),
+        filter_input: ManifestFilterInput {
+            type_name: "todos_bool_exp".into(),
+            fields: ["id", "payload", "title"]
+                .into_iter()
+                .map(|name| ManifestFilterField {
+                    name: name.into(),
+                    operators: vec!["_eq".into()],
+                })
+                .collect(),
+            relationships: Vec::new(),
+        },
+        row_policy: ManifestRowPolicy::Unrestricted,
+        record_revisions: true,
+        tombstones: true,
+    }
+}
+
+fn codecs() -> BTreeMap<String, String> {
+    [
+        ("Bytea".into(), "base64".into()),
+        ("ID".into(), "string".into()),
+        ("JSON".into(), "json".into()),
+        ("String".into(), "string".into()),
+    ]
+    .into_iter()
+    .collect()
+}
+
+fn input() -> ManifestTypeDef {
+    ManifestTypeDef {
+        name: "CreateTodoInput".into(),
+        fields: vec![
+            field("id", "ID", Some("string"), None),
+            field(
+                "metadata",
+                "TodoMetadataInput",
+                None,
+                Some(ManifestTypeDef {
+                    name: "TodoMetadataInput".into(),
+                    fields: vec![field("title", "String", Some("string"), None)],
+                }),
+            ),
+        ],
+    }
+}
+
+fn output() -> ManifestTypeDef {
+    ManifestTypeDef {
+        name: "CreateTodoPayload".into(),
+        fields: vec![
+            field("id", "ID", Some("string"), None),
+            field(
+                "todo",
+                "TodoResult",
+                None,
+                Some(ManifestTypeDef {
+                    name: "TodoResult".into(),
+                    fields: vec![
+                        field("id", "ID", Some("string"), None),
+                        field("title", "String", Some("string"), None),
+                    ],
+                }),
+            ),
+        ],
+    }
+}
+
+fn input_expression(path: &[&str]) -> ManifestEffectExpression {
+    ManifestEffectExpression::Input {
+        path: path.iter().map(|segment| (*segment).into()).collect(),
+    }
+}
+
+fn key() -> ManifestEffectKey {
+    ManifestEffectKey {
+        fields: vec![ManifestEffectField {
+            field: "id".into(),
+            value: input_expression(&["id"]),
+        }],
+    }
+}
+
+fn command() -> ManifestCommand {
+    let operation = "mutation Client_createTodo($commandId: ID!, $input: CreateTodoInput!) { createTodo(commandId: $commandId, input: $input) { id todo { id title } } }";
+    ManifestCommand {
+        version: 1,
+        name: "CreateTodo".into(),
+        mutation_field: "createTodo".into(),
+        grants: vec!["user".into()],
+        input: ManifestCommandShape::Object {
+            definition: input(),
+        },
+        output: ManifestCommandShape::Object {
+            definition: output(),
+        },
+        operation: operation.into(),
+        operation_hash: hash_bytes(operation.as_bytes()),
+        extensions: ManifestCommandExtensions {
+            version: 1,
+            consistency: ManifestCommandConsistency {
+                version: 1,
+                kind: ManifestConsistencyKind::Fact,
+            },
+            direct_projection: None,
+            input_defaults: Some(ManifestInputDefaults {
+                version: 1,
+                defaults: vec![ManifestInputDefault {
+                    path: vec!["id".into()],
+                    generator: ManifestInputDefaultGenerator::UuidV7,
+                }],
+            }),
+            effects: Some(ManifestEffects {
+                version: 1,
+                operations: vec![ManifestEffect::Upsert {
+                    model: "Todo".into(),
+                    key: key(),
+                    fields: vec![ManifestEffectField {
+                        field: "title".into(),
+                        value: input_expression(&["metadata", "title"]),
+                    }],
+                }],
+                fallback: ManifestRevalidationFallback::Revalidate,
+            }),
+            confirmations: Some(ManifestConfirmations {
+                version: 1,
+                kind: ManifestConfirmationKind::Finite,
+                expected: vec![ManifestConfirmation {
+                    projector: "todos".into(),
+                    model: "Todo".into(),
+                    key: key(),
+                    partition: None,
+                }],
+                fallback: ManifestRevalidationFallback::Revalidate,
+            }),
+            trusted_presets: Vec::new(),
+        },
+    }
+}
+
+fn projector() -> ManifestProjector {
+    ManifestProjector {
+        version: 1,
+        name: "todos".into(),
+        facts: vec!["TodoCreated".into()],
+        models: vec!["Todo".into()],
+        dependencies: vec!["todos".into()],
+        causal_confirmation: true,
+    }
+}
+
+fn protocol() -> ManifestProtocolOperations {
+    let operation = "query Distributed_CommandStatus($commandId: ID!) { commandStatus(commandId: $commandId) { state } }";
+    ManifestProtocolOperations {
+        version: 1,
+        command_status: Some(ManifestProtocolOperation {
+            name: "Distributed_CommandStatus".into(),
+            operation: operation.into(),
+            operation_hash: hash_bytes(operation.as_bytes()),
+        }),
+    }
+}
+
+fn validate(
+    command: &ManifestCommand,
+) -> Result<super::command_manifest::CommandManifestValidation, super::ClientCompileError> {
+    validate_commands(std::slice::from_ref(command))
+}
+
+fn validate_commands(
+    commands: &[ManifestCommand],
+) -> Result<super::command_manifest::CommandManifestValidation, super::ClientCompileError> {
+    validate_command_manifest(
+        commands,
+        &[("Todo".into(), model())].into_iter().collect(),
+        &BTreeMap::new(),
+        &codecs(),
+        &[projector()],
+        true,
+        &protocol(),
+    )
+}
+
+fn command_with_identity(name: &str, mutation_field: &str) -> ManifestCommand {
+    let mut command = command();
+    command.name = name.into();
+    command.mutation_field = mutation_field.into();
+    command.operation = format!(
+        "mutation Client_{mutation_field}($commandId: ID!, $input: CreateTodoInput!) {{ {mutation_field}(commandId: $commandId, input: $input) {{ id todo {{ id title }} }} }}"
+    );
+    command.operation_hash = hash_bytes(command.operation.as_bytes());
+    command
+}
+
+#[test]
+fn validates_recursive_shapes_effects_and_confirmations() {
+    let report = validate(&command()).expect("valid typed command");
+    assert!(report.commands_requiring_revalidation.is_empty());
+}
+
+#[test]
+fn requires_byte_exact_canonical_operation_and_recursive_codecs() {
+    let mut drifted = command();
+    drifted.operation.push(' ');
+    drifted.operation_hash = hash_bytes(drifted.operation.as_bytes());
+    let error = validate(&drifted).expect_err("whitespace drift must fail");
+    assert_eq!(error.code, "client.manifest.command_operation");
+
+    let mut wrong_codec = command();
+    let ManifestCommandShape::Object { definition } = &mut wrong_codec.input else {
+        unreachable!()
+    };
+    definition.fields[1].nested.as_mut().expect("nested").fields[0].codec = Some("json".into());
+    let error = validate(&wrong_codec).expect_err("recursive codec drift must fail");
+    assert_eq!(error.code, "client.manifest.command_type_codec");
+}
+
+#[test]
+fn trusted_presets_require_an_exact_typed_descriptor() {
+    let mut trusted = command();
+    let Some(effects) = &mut trusted.extensions.effects else {
+        unreachable!()
+    };
+    let ManifestEffect::Upsert { fields, .. } = &mut effects.operations[0] else {
+        unreachable!()
+    };
+    fields[0].value = ManifestEffectExpression::TrustedPreset {
+        name: "subject".into(),
+    };
+    let error = validate(&trusted).expect_err("undeclared trusted preset must fail closed");
+    assert_eq!(error.code, "client.manifest.effect_trusted_preset");
+
+    trusted
+        .extensions
+        .trusted_presets
+        .push(ManifestTrustedPresetDescriptor {
+            name: "subject".into(),
+            codec: "string".into(),
+        });
+    validate(&trusted).expect("matching descriptor binds the trusted preset");
+}
+
+#[test]
+fn missing_effects_and_nonfinite_confirmations_require_revalidation() {
+    let mut missing_effects = command();
+    missing_effects.extensions.effects = None;
+    let report = validate(&missing_effects).expect("effects may be withheld");
+    assert!(report
+        .commands_requiring_revalidation
+        .contains("CreateTodo"));
+
+    let mut accepted_without_confirmations = command();
+    accepted_without_confirmations.extensions.consistency.kind = ManifestConsistencyKind::Accepted;
+    accepted_without_confirmations.extensions.confirmations = None;
+    let report = validate(&accepted_without_confirmations)
+        .expect("accepted effects may omit a finite confirmation contract");
+    assert!(report
+        .commands_requiring_revalidation
+        .contains("CreateTodo"));
+
+    let mut unavailable = command();
+    let confirmations = unavailable
+        .extensions
+        .confirmations
+        .as_mut()
+        .expect("confirmations");
+    confirmations.kind = ManifestConfirmationKind::Unavailable;
+    confirmations.expected.clear();
+    let report = validate(&unavailable).expect("complete topology may be withheld");
+    assert!(report
+        .commands_requiring_revalidation
+        .contains("CreateTodo"));
+
+    unavailable
+        .extensions
+        .confirmations
+        .as_mut()
+        .expect("confirmations")
+        .expected
+        .push(ManifestConfirmation {
+            projector: "hidden".into(),
+            model: "Todo".into(),
+            key: key(),
+            partition: Some(ManifestEffectExpression::Constant {
+                value: json!("tenant"),
+            }),
+        });
+    let error = validate(&unavailable).expect_err("unavailable must be empty");
+    assert_eq!(error.code, "client.manifest.command_confirmations");
+}
+
+#[test]
+fn rejects_empty_outputs_and_ambiguous_command_type_namespaces() {
+    let mut empty = command();
+    empty.output = ManifestCommandShape::None;
+    let error = validate(&empty).expect_err("GraphQL mutation output cannot be empty");
+    assert_eq!(error.code, "client.manifest.command_output");
+
+    let mut overlaps_input = command();
+    overlaps_input.output = ManifestCommandShape::Object {
+        definition: input(),
+    };
+    let error = validate(&overlaps_input).expect_err("input/output type IDs cannot overlap");
+    assert_eq!(error.code, "client.manifest.command_type_reference");
+
+    let first = command();
+    let second = command_with_identity("CreateTodoAgain", "createTodoAgain");
+    validate_commands(&[first.clone(), second.clone()])
+        .expect("identical output definitions may be shared across commands");
+
+    let mut conflicting = second;
+    let ManifestCommandShape::Object { definition } = &mut conflicting.output else {
+        unreachable!()
+    };
+    definition.fields[0].nullable = true;
+    let error = validate_commands(&[first, conflicting])
+        .expect_err("cross-command type definitions must be globally unambiguous");
+    assert_eq!(error.code, "client.manifest.command_type_reference");
+
+    let mut model_collision = command();
+    let ManifestCommandShape::Object { definition } = &mut model_collision.input else {
+        unreachable!()
+    };
+    definition.name = "Todo".into();
+    let error = validate(&model_collision)
+        .expect_err("command input types cannot shadow an authorized model object");
+    assert_eq!(error.code, "client.manifest.command_type_namespace");
+
+    let mut scalar_collision = command();
+    let ManifestCommandShape::Object { definition } = &mut scalar_collision.input else {
+        unreachable!()
+    };
+    definition.name = "String".into();
+    let error = validate(&scalar_collision)
+        .expect_err("command input types cannot shadow built-in scalar types");
+    assert_eq!(error.code, "client.manifest.command_type_namespace");
+
+    let mut non_projected_model_output = command();
+    let ManifestCommandShape::Object { definition } = &mut non_projected_model_output.output else {
+        unreachable!()
+    };
+    definition.name = "Todo".into();
+    let error = validate(&non_projected_model_output)
+        .expect_err("only an exact Projected<T> output may reuse its model object type");
+    assert_eq!(error.code, "client.manifest.command_type_namespace");
+}
+
+#[test]
+fn caps_finite_confirmations_at_the_authoritative_protocol_limit() {
+    let mut excessive = command();
+    let confirmations = excessive
+        .extensions
+        .confirmations
+        .as_mut()
+        .expect("confirmations");
+    confirmations.expected = vec![confirmations.expected[0].clone(); 129];
+
+    let error = validate(&excessive).expect_err("129 confirmations exceed the protocol batch");
+    assert_eq!(error.code, "client.manifest.command_confirmations");
+    assert!(error.message.contains("maximum is 128"));
+}
+
+#[test]
+fn bytea_constants_use_the_authoritative_standard_base64_decoder() {
+    let mut encoded = command();
+    {
+        let Some(effects) = &mut encoded.extensions.effects else {
+            unreachable!()
+        };
+        let ManifestEffect::Upsert { fields, .. } = &mut effects.operations[0] else {
+            unreachable!()
+        };
+        fields.push(ManifestEffectField {
+            field: "payload".into(),
+            value: ManifestEffectExpression::Constant {
+                value: json!("AQ=="),
+            },
+        });
+    }
+    validate(&encoded).expect("canonical standard base64");
+
+    let Some(effects) = &mut encoded.extensions.effects else {
+        unreachable!()
+    };
+    let ManifestEffect::Upsert { fields, .. } = &mut effects.operations[0] else {
+        unreachable!()
+    };
+    fields.last_mut().expect("payload assignment").value = ManifestEffectExpression::Constant {
+        // Syntactically shaped like base64, but the unused trailing bits
+        // are non-zero and the authoritative decoder rejects it.
+        value: json!("AB=="),
+    };
+    let error = validate(&encoded).expect_err("non-canonical trailing bits must fail");
+    assert_eq!(error.code, "client.manifest.effect_constant");
+}
+
+#[test]
+fn accepts_shapes_beyond_removed_compiler_only_size_limits() {
+    let mut deep = command();
+    let mut nested = ManifestTypeDef {
+        name: "Deep40".into(),
+        fields: vec![field("value", "String", Some("string"), None)],
+    };
+    for depth in (0..40).rev() {
+        let type_name = format!("Deep{depth}");
+        let child_name = nested.name.clone();
+        nested = ManifestTypeDef {
+            name: type_name,
+            fields: vec![field("child", &child_name, None, Some(nested))],
+        };
+    }
+    let ManifestCommandShape::Object { definition } = &mut deep.input else {
+        unreachable!()
+    };
+    let nested_name = nested.name.clone();
+    definition
+        .fields
+        .push(field("zdeep", &nested_name, None, Some(nested)));
+    validate(&deep).expect("Surface has no 32-level command type limit");
+
+    let mut wide = command();
+    let ManifestCommandShape::Object { definition } = &mut wide.input else {
+        unreachable!()
+    };
+    let mut fields = (0..4_097)
+        .map(|index| field(&format!("a{index:04}"), "String", Some("string"), None))
+        .collect::<Vec<_>>();
+    fields.append(&mut definition.fields);
+    definition.fields = fields;
+    validate(&wide).expect("Surface has no 4,096-field command type limit");
+}
+
+#[test]
+fn query_only_protocol_has_no_command_status_or_causal_capability() {
+    let report = validate_command_manifest(
+        &[],
+        &BTreeMap::new(),
+        &BTreeMap::new(),
+        &codecs(),
+        &[],
+        false,
+        &ManifestProtocolOperations {
+            version: 1,
+            command_status: None,
+        },
+    )
+    .expect("query-only contract");
+    assert!(report.commands_requiring_revalidation.is_empty());
+}
diff --git a/distributed_cli/src/client_compiler/graphql/arguments.rs b/distributed_cli/src/client_compiler/graphql/arguments.rs
new file mode 100644
index 00000000..9daab786
--- /dev/null
+++ b/distributed_cli/src/client_compiler/graphql/arguments.rs
@@ -0,0 +1,570 @@
+use super::*;
+
+pub(super) fn single_root_field<'a>(
+    mut fields: Vec<MergedField<'a>>,
+    operation: &OperationDefinition,
+    document: &ClientDocument,
+) -> Result<MergedField<'a>, ClientCompileError> {
+    if fields.len() != 1 {
+        return Err(source_error(
+            "client.operation.single_root",
+            format!(
+                "causal protocol v1 requires exactly one query root; found {}",
+                fields.len()
+            ),
+            document,
+            operation.selection_set.pos,
+        ));
+    }
+    Ok(fields.pop().expect("length checked"))
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn compile_arguments(
+    field: &Field,
+    owner: &str,
+    allowed_arguments: &[ManifestArgument],
+    model: &ManifestModel,
+    manifest: &ClientManifest,
+    variables: &[CompiledVariable],
+    used_variables: &mut BTreeSet<String>,
+    document: &ClientDocument,
+) -> Result<BTreeMap<String, CompiledArgument>, ClientCompileError> {
+    let manifest_arguments = allowed_arguments
+        .iter()
+        .map(|argument| (argument.name.as_str(), argument))
+        .collect::<BTreeMap<_, _>>();
+    let variables = variables
+        .iter()
+        .map(|variable| (variable.name.as_str(), variable))
+        .collect::<BTreeMap<_, _>>();
+    let mut result = BTreeMap::new();
+    for (name, value) in &field.arguments {
+        let name_string = name.node.as_str();
+        let Some(manifest_argument) = manifest_arguments.get(name_string) else {
+            return Err(source_error(
+                "client.argument.denied_or_unknown",
+                format!("argument `{name_string}` is absent from selected field `{owner}`",),
+                document,
+                name.pos,
+            ));
+        };
+        if result.contains_key(name_string) {
+            return Err(source_error(
+                "client.argument.duplicate",
+                format!("root argument `{name_string}` appears more than once"),
+                document,
+                name.pos,
+            ));
+        }
+        let compiled = match &value.node {
+            Value::Variable(variable) => {
+                let Some(definition) = variables.get(variable.as_str()) else {
+                    return Err(source_error(
+                        "client.variable.undefined",
+                        format!(
+                            "argument `{name_string}` references undefined variable `${variable}`"
+                        ),
+                        document,
+                        value.pos,
+                    ));
+                };
+                let expected_type =
+                    Type::new(&manifest_argument.graphql_type()).expect("manifest type validated");
+                if !variable_type_compatible(&definition.graphql_type, &expected_type) {
+                    let actual_type = definition.graphql_type.to_string();
+                    let expected_type = expected_type.to_string();
+                    return Err(source_error(
+                        "client.variable.type_mismatch",
+                        format!(
+                            "variable `${variable}` used for `{name_string}` has type `{actual_type}`; selected manifest requires `{expected_type}`"
+                        ),
+                        document,
+                        value.pos,
+                    ));
+                }
+                used_variables.insert(variable.to_string());
+                CompiledArgument::Variable(variable.to_string())
+            }
+            literal => {
+                let literal =
+                    canonicalize_argument_literal(literal, manifest_argument, model, manifest);
+                validate_literal(&literal, manifest_argument, document, value.pos)?;
+                compile_argument_source(
+                    &literal,
+                    name_string,
+                    &variables,
+                    used_variables,
+                    document,
+                    value.pos,
+                )?
+            }
+        };
+        result.insert(name_string.to_string(), compiled);
+    }
+    for argument in allowed_arguments {
+        if !argument.nullable && !result.contains_key(&argument.name) {
+            return Err(source_error(
+                "client.argument.required",
+                format!(
+                    "field `{owner}` requires argument `{}` of type `{}`",
+                    argument.name,
+                    argument.graphql_type()
+                ),
+                document,
+                field.name.pos,
+            ));
+        }
+    }
+    Ok(result)
+}
+
+pub(super) fn validate_used_variables(
+    variables: &[CompiledVariable],
+    used: &BTreeSet<String>,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    if let Some(variable) = variables
+        .iter()
+        .find(|variable| !used.contains(&variable.name))
+    {
+        return Err(source_error(
+            "client.variable.unused",
+            format!(
+                "variable `${}` is defined but is not used by the compiled operation",
+                variable.name,
+            ),
+            document,
+            position,
+        ));
+    }
+    Ok(())
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn reject_directives(
+    directives: &[Positioned<Directive>],
+    owner: &str,
+    document: &ClientDocument,
+) -> Result<(), ClientCompileError> {
+    let Some(directive) = directives.first() else {
+        return Ok(());
+    };
+    let name = directive.node.name.node.as_str();
+    let (code, message) = if matches!(name, "skip" | "include") {
+        (
+            "client.directive.conditional_unsupported",
+            format!(
+                "conditional directive `@{name}` on {owner} requires a field-presence plan and is not supported yet"
+            ),
+        )
+    } else {
+        (
+            "client.directive.unsupported",
+            format!("directive `@{name}` on {owner} is not supported"),
+        )
+    };
+    Err(source_error(code, message, document, directive.pos))
+}
+
+pub(super) fn compile_argument_source(
+    value: &Value,
+    argument: &str,
+    variables: &BTreeMap<&str, &CompiledVariable>,
+    used_variables: &mut BTreeSet<String>,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<CompiledArgument, ClientCompileError> {
+    if !contains_variable(value) {
+        return Ok(CompiledArgument::Literal {
+            value: value_to_json(value, document, position)?,
+            wire: render_value(value, document, position)?,
+        });
+    }
+    match value {
+        Value::Variable(variable) => {
+            if !variables.contains_key(variable.as_str()) {
+                return Err(source_error(
+                    "client.variable.undefined",
+                    format!(
+                        "argument `{argument}` references undefined nested variable `${variable}`"
+                    ),
+                    document,
+                    position,
+                ));
+            }
+            used_variables.insert(variable.to_string());
+            Ok(CompiledArgument::Variable(variable.to_string()))
+        }
+        Value::List(values) => values
+            .iter()
+            .map(|value| {
+                compile_argument_source(
+                    value,
+                    argument,
+                    variables,
+                    used_variables,
+                    document,
+                    position,
+                )
+            })
+            .collect::<Result<Vec<_>, _>>()
+            .map(CompiledArgument::List),
+        Value::Object(values) => values
+            .iter()
+            .map(|(name, value)| {
+                Ok((
+                    name.to_string(),
+                    compile_argument_source(
+                        value,
+                        argument,
+                        variables,
+                        used_variables,
+                        document,
+                        position,
+                    )?,
+                ))
+            })
+            .collect::<Result<BTreeMap<_, _>, ClientCompileError>>()
+            .map(CompiledArgument::Object),
+        _ => unreachable!("non-container value with no variable returned above"),
+    }
+}
+
+pub(super) fn contains_variable(value: &Value) -> bool {
+    match value {
+        Value::Variable(_) => true,
+        Value::List(values) => values.iter().any(contains_variable),
+        Value::Object(values) => values.values().any(contains_variable),
+        _ => false,
+    }
+}
+
+pub(super) fn canonicalize_argument_literal(
+    value: &Value,
+    argument: &ManifestArgument,
+    model: &ManifestModel,
+    manifest: &ClientManifest,
+) -> Value {
+    let value = if argument.kind == ManifestArgumentKind::Filter {
+        canonicalize_filter_literal(value, model, &model.filter_input, manifest)
+    } else {
+        value.clone()
+    };
+    let value =
+        if argument.list && !matches!(&value, Value::List(_) | Value::Null | Value::Variable(_)) {
+            Value::List(vec![value])
+        } else {
+            value
+        };
+    match &argument.codec {
+        Some(codec) if argument.list => match value {
+            Value::List(items) => Value::List(
+                items
+                    .iter()
+                    .map(|item| canonicalize_scalar_literal(item, &argument.type_name, codec))
+                    .collect(),
+            ),
+            value => value,
+        },
+        Some(codec) => canonicalize_scalar_literal(&value, &argument.type_name, codec),
+        None => value,
+    }
+}
+
+pub(super) fn canonicalize_filter_literal(
+    value: &Value,
+    model: &ManifestModel,
+    input: &ManifestFilterInput,
+    manifest: &ClientManifest,
+) -> Value {
+    let Value::Object(fields) = value else {
+        return value.clone();
+    };
+    let mut canonical = fields.clone();
+    for (name, value) in fields {
+        let value = match name.as_str() {
+            "_and" | "_or" => canonicalize_filter_literal_list(value, model, input, manifest),
+            "_not" => canonicalize_filter_literal(value, model, input, manifest),
+            field_name if input.fields.iter().any(|field| field.name == field_name) => model
+                .field(field_name)
+                .map(|field| canonicalize_filter_comparison_literal(value, field))
+                .unwrap_or_else(|| value.clone()),
+            relationship_name
+                if input
+                    .relationships
+                    .iter()
+                    .any(|relationship| relationship.field == relationship_name) =>
+            {
+                model
+                    .relationship(relationship_name)
+                    .and_then(|relationship| manifest.models.get(&relationship.target_model))
+                    .map(|target| {
+                        canonicalize_filter_literal(value, target, &target.filter_input, manifest)
+                    })
+                    .unwrap_or_else(|| value.clone())
+            }
+            _ => value.clone(),
+        };
+        canonical.insert(name.clone(), value);
+    }
+    Value::Object(canonical)
+}
+
+pub(super) fn canonicalize_filter_literal_list(
+    value: &Value,
+    model: &ManifestModel,
+    input: &ManifestFilterInput,
+    manifest: &ClientManifest,
+) -> Value {
+    match value {
+        Value::List(items) => Value::List(
+            items
+                .iter()
+                .map(|item| canonicalize_filter_literal(item, model, input, manifest))
+                .collect(),
+        ),
+        Value::Null | Value::Variable(_) => value.clone(),
+        value => Value::List(vec![canonicalize_filter_literal(
+            value, model, input, manifest,
+        )]),
+    }
+}
+
+pub(super) fn canonicalize_filter_comparison_literal(
+    value: &Value,
+    field: &ManifestField,
+) -> Value {
+    let Value::Object(operators) = value else {
+        return value.clone();
+    };
+    let mut canonical = operators.clone();
+    for (operator, operand) in operators {
+        let operand = match operator.as_str() {
+            "_in" | "_nin" => {
+                let operand =
+                    if matches!(operand, Value::List(_) | Value::Null | Value::Variable(_)) {
+                        operand.clone()
+                    } else {
+                        Value::List(vec![operand.clone()])
+                    };
+                match operand {
+                    Value::List(items) => Value::List(
+                        items
+                            .iter()
+                            .map(|item| {
+                                canonicalize_scalar_literal(item, &field.scalar, &field.codec)
+                            })
+                            .collect(),
+                    ),
+                    operand => operand,
+                }
+            }
+            "_is_null" | "_has_key" => operand.clone(),
+            _ => canonicalize_scalar_literal(operand, &field.scalar, &field.codec),
+        };
+        canonical.insert(operator.clone(), operand);
+    }
+    Value::Object(canonical)
+}
+
+pub(super) fn canonicalize_scalar_literal(value: &Value, scalar: &str, codec: &str) -> Value {
+    match (scalar, codec, value) {
+        ("ID", "string", Value::Number(number)) if json_number_is_negative_zero(number) => {
+            Value::String("0".into())
+        }
+        ("ID", "string", Value::Number(number)) if json_number_is_safe_integer(number) => {
+            Value::String(number.to_string())
+        }
+        ("Bytea", "base64", Value::String(value)) => canonical_standard_base64(value)
+            .map(Value::String)
+            .unwrap_or_else(|| Value::String(value.clone())),
+        ("Float", "float64", Value::Number(number)) => canonicalize_float_number(number)
+            .map(Value::Number)
+            .unwrap_or_else(|| Value::Number(number.clone())),
+        ("Int", "int32", Value::Number(number))
+        | ("BigInt", "json_number_precision_limited", Value::Number(number))
+            if json_number_is_negative_zero(number) =>
+        {
+            Value::Number(serde_json::Number::from(0))
+        }
+        ("JSON", "json", value) => canonicalize_json_literal(value),
+        _ => value.clone(),
+    }
+}
+
+pub(super) fn canonicalize_json_literal(value: &Value) -> Value {
+    match value {
+        Value::Number(number) => canonicalize_json_number(number)
+            .map(Value::Number)
+            .unwrap_or_else(|| Value::Number(number.clone())),
+        Value::List(values) => Value::List(values.iter().map(canonicalize_json_literal).collect()),
+        Value::Object(values) => Value::Object(
+            values
+                .iter()
+                .map(|(name, value)| (name.clone(), canonicalize_json_literal(value)))
+                .collect(),
+        ),
+        _ => value.clone(),
+    }
+}
+
+pub(super) fn canonicalize_json_number(number: &serde_json::Number) -> Option<serde_json::Number> {
+    if json_number_is_negative_zero(number) {
+        return Some(serde_json::Number::from(0));
+    }
+    if number.as_i64().is_some() || number.as_u64().is_some() {
+        return Some(number.clone());
+    }
+    let value = number.as_f64().filter(|value| value.is_finite())?;
+    if value.fract() == 0.0 {
+        if value.abs() > 9_007_199_254_740_991.0 {
+            return None;
+        }
+        return if value.is_sign_negative() {
+            Some(serde_json::Number::from(value as i64))
+        } else {
+            Some(serde_json::Number::from(value as u64))
+        };
+    }
+    serde_json::Number::from_f64(value)
+}
+
+pub(super) fn canonicalize_float_number(number: &serde_json::Number) -> Option<serde_json::Number> {
+    let value = number.as_f64()?;
+    if value == 0.0 {
+        Some(serde_json::Number::from(0))
+    } else {
+        serde_json::Number::from_f64(value)
+    }
+}
+
+pub(super) fn validate_literal(
+    value: &Value,
+    argument: &ManifestArgument,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    if matches!(value, Value::Null) {
+        if argument.nullable {
+            return Ok(());
+        }
+        return Err(source_error(
+            "client.argument.null",
+            format!(
+                "argument `{}` is non-null in the selected manifest",
+                argument.name
+            ),
+            document,
+            position,
+        ));
+    }
+    if argument.list && !matches!(value, Value::List(_)) {
+        return Err(source_error(
+            "client.argument.list_literal",
+            format!(
+                "argument `{}` requires an explicit list literal or a variable of type `{}`",
+                argument.name,
+                argument.graphql_type()
+            ),
+            document,
+            position,
+        ));
+    }
+    if let Some(codec) = &argument.codec {
+        let valid = if argument.list {
+            let Value::List(items) = value else {
+                unreachable!("list shape checked above")
+            };
+            items.iter().all(|item| {
+                value_to_json(item, document, position).is_ok_and(|item| {
+                    scalar_json_literal_matches(&item, &argument.type_name, codec, false)
+                })
+            })
+        } else {
+            value_to_json(value, document, position).is_ok_and(|value| {
+                scalar_json_literal_matches(&value, &argument.type_name, codec, false)
+            })
+        };
+        return if valid {
+            Ok(())
+        } else {
+            Err(source_error(
+                "client.argument.literal_type",
+                format!(
+                    "literal for argument `{}` does not match scalar `{}` / codec `{}`",
+                    argument.name, argument.type_name, codec
+                ),
+                document,
+                position,
+            ))
+        };
+    }
+    if argument.list {
+        return Ok(());
+    }
+    let valid = match argument.type_name.as_str() {
+        "Boolean" => matches!(value, Value::Boolean(_)),
+        "Int" => matches!(value, Value::Number(number) if number.is_i64() || number.is_u64()),
+        "Float" | "BigInt" => matches!(value, Value::Number(_)),
+        "ID" | "String" | "Bytea" | "Timestamptz" => matches!(value, Value::String(_)),
+        "JSON" => !matches!(value, Value::Binary(_) | Value::Variable(_)),
+        _ => matches!(value, Value::Object(_) | Value::Enum(_) | Value::List(_)),
+    };
+    if valid {
+        Ok(())
+    } else {
+        Err(source_error(
+            "client.argument.literal_type",
+            format!(
+                "literal for argument `{}` does not match manifest type `{}`",
+                argument.name,
+                argument.graphql_type()
+            ),
+            document,
+            position,
+        ))
+    }
+}
+
+pub(super) fn value_to_json(
+    value: &Value,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<JsonValue, ClientCompileError> {
+    match value {
+        Value::Variable(variable) => Err(source_error(
+            "client.argument.nested_variable",
+            format!("nested variable `${variable}` is not a literal"),
+            document,
+            position,
+        )),
+        Value::Null => Ok(JsonValue::Null),
+        Value::Number(value) => Ok(JsonValue::Number(value.clone())),
+        Value::String(value) => Ok(JsonValue::String(value.clone())),
+        Value::Boolean(value) => Ok(JsonValue::Bool(*value)),
+        Value::Binary(_) => Err(source_error(
+            "client.literal.binary",
+            "binary GraphQL literals are not portable to the JavaScript replica",
+            document,
+            position,
+        )),
+        Value::Enum(value) => Ok(JsonValue::String(value.to_string())),
+        Value::List(values) => Ok(JsonValue::Array(
+            values
+                .iter()
+                .map(|value| value_to_json(value, document, position))
+                .collect::<Result<_, _>>()?,
+        )),
+        Value::Object(values) => {
+            let mut object = JsonMap::new();
+            let mut values = values.iter().collect::<Vec<_>>();
+            values.sort_by(|left, right| left.0.cmp(right.0));
+            for (name, value) in values {
+                object.insert(name.to_string(), value_to_json(value, document, position)?);
+            }
+            Ok(JsonValue::Object(object))
+        }
+    }
+}
diff --git a/distributed_cli/src/client_compiler/graphql/fragments.rs b/distributed_cli/src/client_compiler/graphql/fragments.rs
new file mode 100644
index 00000000..2ccdf05d
--- /dev/null
+++ b/distributed_cli/src/client_compiler/graphql/fragments.rs
@@ -0,0 +1,384 @@
+use super::*;
+
+pub(super) fn validate_reachable_fragment_graph<'ast>(
+    fragments: &'ast HashMap<Name, Positioned<FragmentDefinition>>,
+    document: &ClientDocument,
+    selection_set: &'ast Positioned<SelectionSet>,
+) -> Result<(), ClientCompileError> {
+    validate_fragment_selection_set(
+        fragments,
+        document,
+        &mut FragmentGraphState::default(),
+        selection_set,
+        1,
+    )
+}
+
+pub(super) fn validate_fragment_selection_set<'ast>(
+    fragments: &'ast HashMap<Name, Positioned<FragmentDefinition>>,
+    document: &ClientDocument,
+    state: &mut FragmentGraphState,
+    selection_set: &'ast Positioned<SelectionSet>,
+    depth: usize,
+) -> Result<(), ClientCompileError> {
+    check_expansion_depth(depth, document, selection_set.pos)?;
+    for selection in &selection_set.node.items {
+        match &selection.node {
+            Selection::Field(field) => {
+                if !field.node.selection_set.node.items.is_empty() {
+                    validate_fragment_selection_set(
+                        fragments,
+                        document,
+                        state,
+                        &field.node.selection_set,
+                        depth + 1,
+                    )?;
+                }
+            }
+            Selection::InlineFragment(fragment) => {
+                validate_fragment_selection_set(
+                    fragments,
+                    document,
+                    state,
+                    &fragment.node.selection_set,
+                    depth + 1,
+                )?;
+            }
+            Selection::FragmentSpread(spread) => {
+                let name = spread.node.fragment_name.node.as_str();
+                let Some(definition) = fragments.get(name) else {
+                    return Err(source_error(
+                        "client.graphql.fragment_undefined",
+                        format!("fragment spread `{name}` has no definition in this document"),
+                        document,
+                        spread.node.fragment_name.pos,
+                    ));
+                };
+                if let Some(cycle_start) = state
+                    .active_fragments
+                    .iter()
+                    .position(|active| active == name)
+                {
+                    let mut cycle = state.active_fragments[cycle_start..].to_vec();
+                    cycle.push(name.to_string());
+                    return Err(source_error(
+                        "client.graphql.fragment_cycle",
+                        format!("fragment expansion cycle: {}", cycle.join(" -> ")),
+                        document,
+                        spread.node.fragment_name.pos,
+                    ));
+                }
+                if state.completed_fragments.contains(name) {
+                    continue;
+                }
+                check_expansion_depth(depth + 1, document, spread.pos)?;
+                state.active_fragments.push(name.to_string());
+                let result = validate_fragment_selection_set(
+                    fragments,
+                    document,
+                    state,
+                    &definition.node.selection_set,
+                    depth + 1,
+                );
+                state.active_fragments.pop();
+                result?;
+                state.completed_fragments.insert(name.to_string());
+            }
+        }
+    }
+    Ok(())
+}
+
+impl<'ast, 'source> FragmentExpander<'ast, 'source> {
+    pub(super) fn new(
+        fragments: &'ast HashMap<Name, Positioned<FragmentDefinition>>,
+        document: &'source ClientDocument,
+    ) -> Self {
+        Self {
+            fragments,
+            document,
+            state: ExpansionState::default(),
+        }
+    }
+
+    pub(super) fn merge_object(
+        &mut self,
+        selection_sets: &[&'ast Positioned<SelectionSet>],
+        typename: &str,
+        depth: usize,
+        field_owner: &str,
+    ) -> Result<Vec<MergedField<'ast>>, ClientCompileError> {
+        let position = selection_sets
+            .first()
+            .map_or_else(Pos::default, |selection_set| selection_set.pos);
+        check_expansion_depth(depth, self.document, position)?;
+        count_expansion_unit(&mut self.state, self.document, position)?;
+
+        let mut fields = Vec::new();
+        let mut response_keys = BTreeMap::new();
+        for selection_set in selection_sets {
+            expand_selection_set(
+                self.fragments,
+                self.document,
+                &mut self.state,
+                selection_set,
+                typename,
+                depth,
+                field_owner,
+                &mut fields,
+                &mut response_keys,
+            )?;
+        }
+        Ok(fields)
+    }
+
+    pub(super) fn reject_unused_fragments(&self) -> Result<(), ClientCompileError> {
+        let unused = self
+            .fragments
+            .iter()
+            .filter(|(name, _)| !self.state.used_fragments.contains(name.as_str()))
+            .min_by(|left, right| {
+                (left.1.pos, left.0.as_str()).cmp(&(right.1.pos, right.0.as_str()))
+            });
+        let Some((name, definition)) = unused else {
+            return Ok(());
+        };
+        Err(source_error(
+            "client.graphql.fragment_unused",
+            format!("fragment `{name}` is not reachable from the document operation"),
+            self.document,
+            definition.pos,
+        ))
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn expand_selection_set<'ast>(
+    fragments: &'ast HashMap<Name, Positioned<FragmentDefinition>>,
+    document: &ClientDocument,
+    state: &mut ExpansionState,
+    selection_set: &'ast Positioned<SelectionSet>,
+    typename: &str,
+    depth: usize,
+    field_owner: &str,
+    fields: &mut Vec<MergedField<'ast>>,
+    response_keys: &mut BTreeMap<String, usize>,
+) -> Result<(), ClientCompileError> {
+    check_expansion_depth(depth, document, selection_set.pos)?;
+    for selection in &selection_set.node.items {
+        count_expansion_unit(state, document, selection.pos)?;
+        match &selection.node {
+            Selection::Field(field) => {
+                merge_field(document, field, field_owner, fields, response_keys)?
+            }
+            Selection::FragmentSpread(spread) => {
+                reject_directives(
+                    &spread.node.directives,
+                    &format!(
+                        "fragment spread `{}`",
+                        spread.node.fragment_name.node.as_str()
+                    ),
+                    document,
+                )?;
+                let name = spread.node.fragment_name.node.as_str();
+                let Some(definition) = fragments.get(name) else {
+                    return Err(source_error(
+                        "client.graphql.fragment_undefined",
+                        format!("fragment spread `{name}` has no definition in this document"),
+                        document,
+                        spread.node.fragment_name.pos,
+                    ));
+                };
+                state.used_fragments.insert(name.to_string());
+                reject_directives(
+                    &definition.node.directives,
+                    &format!("fragment definition `{name}`"),
+                    document,
+                )?;
+                require_fragment_type(
+                    definition.node.type_condition.node.on.node.as_str(),
+                    typename,
+                    name,
+                    document,
+                    definition.node.type_condition.pos,
+                )?;
+                if let Some(cycle_start) = state
+                    .active_fragments
+                    .iter()
+                    .position(|active| active == name)
+                {
+                    let mut cycle = state.active_fragments[cycle_start..].to_vec();
+                    cycle.push(name.to_string());
+                    return Err(source_error(
+                        "client.graphql.fragment_cycle",
+                        format!("fragment expansion cycle: {}", cycle.join(" -> ")),
+                        document,
+                        spread.node.fragment_name.pos,
+                    ));
+                }
+                check_expansion_depth(depth + 1, document, spread.pos)?;
+                state.active_fragments.push(name.to_string());
+                let result = expand_selection_set(
+                    fragments,
+                    document,
+                    state,
+                    &definition.node.selection_set,
+                    typename,
+                    depth + 1,
+                    field_owner,
+                    fields,
+                    response_keys,
+                );
+                state.active_fragments.pop();
+                result?;
+            }
+            Selection::InlineFragment(fragment) => {
+                reject_directives(&fragment.node.directives, "inline fragment", document)?;
+                if let Some(condition) = &fragment.node.type_condition {
+                    require_fragment_type(
+                        condition.node.on.node.as_str(),
+                        typename,
+                        "inline fragment",
+                        document,
+                        condition.pos,
+                    )?;
+                }
+                check_expansion_depth(depth + 1, document, fragment.pos)?;
+                expand_selection_set(
+                    fragments,
+                    document,
+                    state,
+                    &fragment.node.selection_set,
+                    typename,
+                    depth + 1,
+                    field_owner,
+                    fields,
+                    response_keys,
+                )?;
+            }
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn merge_field<'ast>(
+    document: &ClientDocument,
+    field: &'ast Positioned<Field>,
+    field_owner: &str,
+    fields: &mut Vec<MergedField<'ast>>,
+    response_keys: &mut BTreeMap<String, usize>,
+) -> Result<(), ClientCompileError> {
+    reject_directives(&field.node.directives, field_owner, document)?;
+    let response_key = field.node.response_key().node.as_str();
+    let canonical_arguments = canonical_field_arguments(&field.node, document)?;
+    let is_object = !field.node.selection_set.node.items.is_empty();
+
+    if let Some(index) = response_keys.get(response_key).copied() {
+        let first = &mut fields[index];
+        let first_is_object = !first.selection_sets.is_empty();
+        if first.first.node.name.node != field.node.name.node
+            || first.canonical_arguments != canonical_arguments
+            || first_is_object != is_object
+        {
+            let first_position = first.first.node.response_key().pos;
+            return Err(source_error(
+                "client.selection.conflict",
+                format!(
+                    "response key `{response_key}` conflicts with its first selection at {}:{}",
+                    first_position.line.max(1),
+                    first_position.column.max(1)
+                ),
+                document,
+                field.node.response_key().pos,
+            ));
+        }
+        if is_object {
+            first.selection_sets.push(&field.node.selection_set);
+        }
+        return Ok(());
+    }
+
+    response_keys.insert(response_key.to_string(), fields.len());
+    fields.push(MergedField {
+        first: field,
+        selection_sets: is_object
+            .then_some(&field.node.selection_set)
+            .into_iter()
+            .collect(),
+        canonical_arguments,
+    });
+    Ok(())
+}
+
+pub(super) fn canonical_field_arguments(
+    field: &Field,
+    document: &ClientDocument,
+) -> Result<Vec<(String, String)>, ClientCompileError> {
+    let mut arguments = field
+        .arguments
+        .iter()
+        .map(|(name, value)| {
+            Ok((
+                name.node.to_string(),
+                render_value(&value.node, document, value.pos)?,
+            ))
+        })
+        .collect::<Result<Vec<_>, ClientCompileError>>()?;
+    arguments.sort();
+    Ok(arguments)
+}
+
+pub(super) fn require_fragment_type(
+    actual: &str,
+    expected: &str,
+    fragment: &str,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    if actual == expected {
+        return Ok(());
+    }
+    Err(source_error(
+        "client.graphql.fragment_type",
+        format!(
+            "{fragment} has type condition `{actual}` but the current concrete type is `{expected}`"
+        ),
+        document,
+        position,
+    ))
+}
+
+pub(super) fn check_expansion_depth(
+    depth: usize,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    if depth <= MAX_OBJECT_DEPTH {
+        return Ok(());
+    }
+    Err(source_error(
+        "client.selection.depth",
+        format!("selection expansion exceeds the supported {MAX_OBJECT_DEPTH}-level depth"),
+        document,
+        position,
+    ))
+}
+
+pub(super) fn count_expansion_unit(
+    state: &mut ExpansionState,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    if state.expanded_units >= MAX_EXPANDED_SELECTIONS {
+        return Err(source_error(
+            "client.selection.expansion_bound",
+            format!(
+                "expanded selection exceeds the supported {MAX_EXPANDED_SELECTIONS}-unit bound"
+            ),
+            document,
+            position,
+        ));
+    }
+    state.expanded_units += 1;
+    Ok(())
+}
diff --git a/distributed_cli/src/client_compiler/graphql/mod.rs b/distributed_cli/src/client_compiler/graphql/mod.rs
new file mode 100644
index 00000000..8e4b64af
--- /dev/null
+++ b/distributed_cli/src/client_compiler/graphql/mod.rs
@@ -0,0 +1,41 @@
+use std::collections::{BTreeMap, BTreeSet, HashMap};
+
+use async_graphql_parser::types::{
+    BaseType, Directive, DocumentOperations, Field, FragmentDefinition, OperationDefinition,
+    OperationType, Selection, SelectionSet, Type,
+};
+use async_graphql_parser::{parse_query, Pos, Positioned};
+use async_graphql_value::{Name, Value};
+use base64::Engine as _;
+use serde::Serialize;
+use serde_json::{Map as JsonMap, Value as JsonValue};
+
+use super::manifest::{
+    hash_bytes, ClientManifest, ManifestAggregateSemantics, ManifestArgument, ManifestArgumentKind,
+    ManifestComplexityWeights, ManifestExecutionLimits, ManifestField, ManifestFilterExpr,
+    ManifestFilterField, ManifestFilterInput, ManifestFilterSemantics, ManifestModel,
+    ManifestOrderSemantics, ManifestPagination, ManifestRelationship,
+    ManifestRelationshipKeyMapping, ManifestRelationshipKind, ManifestRelationshipMaintenance,
+    ManifestRoot, ManifestRowPolicy, RootKind, RootOperation,
+};
+use super::{ClientCompileError, ClientDocument, ClientRouteDiscovery, GeneratedRoutePlan};
+
+mod arguments;
+mod fragments;
+mod objects;
+mod operation;
+mod query_plan;
+mod types;
+mod validation;
+mod variables;
+
+pub(crate) use operation::{compile_document, typescript_scalar};
+pub(crate) use types::*;
+
+use arguments::*;
+use fragments::*;
+use objects::*;
+use operation::*;
+use query_plan::*;
+use validation::*;
+use variables::*;
diff --git a/distributed_cli/src/client_compiler/graphql/objects.rs b/distributed_cli/src/client_compiler/graphql/objects.rs
new file mode 100644
index 00000000..c2cb512e
--- /dev/null
+++ b/distributed_cli/src/client_compiler/graphql/objects.rs
@@ -0,0 +1,617 @@
+use super::*;
+
+pub(super) fn compile_model_object<'ast>(
+    field: &MergedField<'ast>,
+    model: &ManifestModel,
+    manifest: &ClientManifest,
+    variables: &[CompiledVariable],
+    used_variables: &mut BTreeSet<String>,
+    document: &ClientDocument,
+    expander: &mut FragmentExpander<'ast, '_>,
+    depth: usize,
+) -> Result<CompiledObject, ClientCompileError> {
+    let selected_fields = expander.merge_object(
+        &field.selection_sets,
+        &model.typename,
+        depth,
+        "selected field",
+    )?;
+    if selected_fields.is_empty() {
+        return Err(source_error(
+            "client.selection.empty",
+            format!(
+                "object field `{}` must select at least one field",
+                field.first.node.name.node
+            ),
+            document,
+            field.first.node.selection_set.pos,
+        ));
+    }
+    let mut result = Vec::with_capacity(selected_fields.len());
+    let mut relationship_source_fields = BTreeSet::new();
+    for selected in selected_fields {
+        let response_key = selected.first.node.response_key().node.as_str();
+        let field_name = selected.first.node.name.node.as_str();
+        if let Some(relationship) = model.relationship(field_name) {
+            if selected.selection_sets.is_empty() {
+                return Err(source_error(
+                    "client.selection.object_required",
+                    format!(
+                        "relationship `{}` on model `{}` requires an object selection",
+                        relationship.name, model.id
+                    ),
+                    document,
+                    selected.first.node.selection_set.pos,
+                ));
+            }
+            let target = manifest
+                .models
+                .get(&relationship.target_model)
+                .ok_or_else(|| {
+                    ClientCompileError::manifest(
+                        "client.manifest.relationship_target",
+                        format!(
+                            "relationship `{}.{}` references absent target model `{}`",
+                            model.id, relationship.name, relationship.target_model
+                        ),
+                    )
+                })?;
+            let arguments = compile_arguments(
+                &selected.first.node,
+                &format!("{}.{}", model.id, relationship.name),
+                &relationship.arguments,
+                target,
+                manifest,
+                variables,
+                used_variables,
+                document,
+            )?;
+            let relationship_plan = compiled_relationship_plan(relationship);
+            let (local_keys, remote_keys) = relationship_key_fields(&relationship_plan.key_mapping);
+            relationship_source_fields.extend(local_keys.iter().cloned());
+            let mut selection = compile_model_object(
+                &selected,
+                target,
+                manifest,
+                variables,
+                used_variables,
+                document,
+                expander,
+                depth + 1,
+            )?;
+            let mut dependencies = BTreeSet::new();
+            if relationship.list {
+                dependencies.extend(query_plan_field_dependencies(
+                    target,
+                    relationship.filter.as_ref(),
+                    relationship.order.as_ref(),
+                    &relationship.arguments,
+                    &arguments,
+                ));
+            }
+            dependencies.extend(remote_keys.iter().cloned());
+            if !dependencies.is_empty() {
+                inject_dependency_fields(
+                    &mut selection,
+                    target,
+                    &dependencies,
+                    document,
+                    selected.first.pos,
+                )?;
+            }
+            let cardinality = if relationship.list {
+                Cardinality::Many
+            } else {
+                Cardinality::One
+            };
+            let coverage = compile_coverage(
+                relationship.pagination.as_ref(),
+                &relationship.arguments,
+                &format!("{}.{}", model.id, relationship.name),
+                document,
+                selected.first.pos,
+            )?;
+            let (filter, order, pagination) = compile_query_plans(
+                target,
+                relationship.filter.as_ref(),
+                relationship.order.as_ref(),
+                &relationship.arguments,
+                &arguments,
+                variables,
+                manifest,
+                document,
+                &selected.first.node,
+                coverage.as_ref(),
+                filter_depth_from_selection(depth, 1),
+                relationship.list,
+            )?;
+            result.push(CompiledMember::Branch(Box::new(CompiledBranch {
+                semantic: CompiledBranchSemantic::Relationship,
+                response_key: response_key.to_string(),
+                field: relationship.name.clone(),
+                cardinality,
+                nullable: relationship.nullable,
+                arguments,
+                dependencies: relationship.dependencies.clone(),
+                coverage,
+                filter,
+                order,
+                pagination,
+                relationship: Some(relationship_plan),
+                selection,
+            })));
+            continue;
+        }
+        if let Some((relationship, aggregate)) = model.relationships.iter().find_map(|candidate| {
+            candidate
+                .aggregate
+                .as_ref()
+                .filter(|aggregate| aggregate.name == field_name)
+                .map(|aggregate| (candidate, aggregate))
+        }) {
+            if selected.selection_sets.is_empty() {
+                return Err(source_error(
+                    "client.selection.object_required",
+                    format!(
+                        "relationship aggregate `{}` on model `{}` requires an object selection",
+                        aggregate.name, model.id
+                    ),
+                    document,
+                    selected.first.node.selection_set.pos,
+                ));
+            }
+            let target = manifest
+                .models
+                .get(&relationship.target_model)
+                .ok_or_else(|| {
+                    ClientCompileError::manifest(
+                        "client.manifest.relationship_target",
+                        format!(
+                            "relationship aggregate `{}.{}` references absent target model `{}`",
+                            model.id, aggregate.name, relationship.target_model
+                        ),
+                    )
+                })?;
+            let arguments = compile_arguments(
+                &selected.first.node,
+                &format!("{}.{}", model.id, aggregate.name),
+                &aggregate.arguments,
+                target,
+                manifest,
+                variables,
+                used_variables,
+                document,
+            )?;
+            let selection = compile_aggregate_object(
+                &selected,
+                target,
+                &aggregate.semantics,
+                &aggregate.arguments,
+                &arguments,
+                relationship.filter.as_ref(),
+                relationship.order.as_ref(),
+                &aggregate.dependencies,
+                manifest,
+                variables,
+                used_variables,
+                document,
+                expander,
+                depth + 1,
+            )?;
+            let (filter, order, pagination) = compile_query_plans(
+                target,
+                relationship.filter.as_ref(),
+                relationship.order.as_ref(),
+                &aggregate.arguments,
+                &arguments,
+                variables,
+                manifest,
+                document,
+                &selected.first.node,
+                None,
+                filter_depth_from_selection(depth, 1),
+                false,
+            )?;
+            result.push(CompiledMember::Branch(Box::new(CompiledBranch {
+                semantic: CompiledBranchSemantic::Aggregate,
+                response_key: response_key.to_string(),
+                field: aggregate.name.clone(),
+                cardinality: Cardinality::One,
+                nullable: true,
+                arguments,
+                dependencies: aggregate.dependencies.clone(),
+                coverage: Some(complete_coverage()),
+                filter,
+                order,
+                pagination,
+                relationship: None,
+                selection,
+            })));
+            continue;
+        }
+        let manifest_field = if field_name == "__typename" {
+            None
+        } else {
+            Some(model.field(field_name).ok_or_else(|| {
+                source_error(
+                    "client.selection.denied_or_unknown",
+                    format!(
+                        "field `{field_name}` is absent from selected model `{}`",
+                        model.id
+                    ),
+                    document,
+                    selected.first.node.name.pos,
+                )
+            })?)
+        };
+        if !selected.first.node.arguments.is_empty() {
+            return Err(source_error(
+                "client.selection.field_arguments",
+                format!("scalar field `{field_name}` must not have arguments"),
+                document,
+                selected.first.pos,
+            ));
+        }
+        if !selected.selection_sets.is_empty() {
+            return Err(source_error(
+                "client.selection.scalar_nested",
+                format!("scalar field `{field_name}` cannot have a nested selection"),
+                document,
+                selected.first.node.selection_set.pos,
+            ));
+        }
+        result.push(CompiledMember::Scalar(match manifest_field {
+            Some(field) => compiled_scalar(response_key, field, true),
+            None => CompiledScalar {
+                response_key: response_key.to_string(),
+                field: "__typename".into(),
+                codec: "string".into(),
+                nullable: false,
+                expose: true,
+            },
+        }));
+    }
+    if model.identity().is_some() {
+        inject_wire_fields(&mut result, model, document, field.first.pos)?;
+    }
+    let mut object = CompiledObject {
+        typename: model.typename.clone(),
+        storage: compiled_storage(model),
+        members: result,
+    };
+    inject_dependency_fields(
+        &mut object,
+        model,
+        &relationship_source_fields,
+        document,
+        field.first.pos,
+    )?;
+    Ok(object)
+}
+
+pub(super) fn compiled_storage(model: &ManifestModel) -> CompiledStorage {
+    match model.identity() {
+        Some(identity) => CompiledStorage::Normalized {
+            model_id: model.id.clone(),
+            identity_fields: identity.iter().map(|field| field.name.clone()).collect(),
+        },
+        None => CompiledStorage::Embedded,
+    }
+}
+
+pub(super) fn compiled_relationship_plan(
+    relationship: &ManifestRelationship,
+) -> CompiledRelationshipPlan {
+    let maintenance = match &relationship.key_mapping {
+        ManifestRelationshipKeyMapping::Direct { .. }
+        | ManifestRelationshipKeyMapping::Through { .. } => relationship.maintenance,
+        ManifestRelationshipKeyMapping::ThroughOpaque { .. }
+        | ManifestRelationshipKeyMapping::Embedded => ManifestRelationshipMaintenance::Revalidate,
+    };
+    CompiledRelationshipPlan {
+        field: relationship.name.clone(),
+        target_model: relationship.target_model.clone(),
+        kind: relationship.kind,
+        key_mapping: relationship.key_mapping.clone(),
+        maintenance,
+        dependencies: relationship.dependencies.clone(),
+    }
+}
+
+pub(super) fn relationship_key_fields(
+    mapping: &ManifestRelationshipKeyMapping,
+) -> (&[String], &[String]) {
+    match mapping {
+        ManifestRelationshipKeyMapping::Direct { local, remote }
+        | ManifestRelationshipKeyMapping::Through { local, remote, .. }
+        | ManifestRelationshipKeyMapping::ThroughOpaque { local, remote, .. } => (local, remote),
+        ManifestRelationshipKeyMapping::Embedded => (&[], &[]),
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn compile_aggregate_object<'ast>(
+    field: &MergedField<'ast>,
+    model: &ManifestModel,
+    semantics: &ManifestAggregateSemantics,
+    arguments: &[ManifestArgument],
+    compiled_arguments: &BTreeMap<String, CompiledArgument>,
+    filter_semantics: Option<&ManifestFilterSemantics>,
+    order_semantics: Option<&ManifestOrderSemantics>,
+    dependencies: &[String],
+    manifest: &ClientManifest,
+    variables: &[CompiledVariable],
+    used_variables: &mut BTreeSet<String>,
+    document: &ClientDocument,
+    expander: &mut FragmentExpander<'ast, '_>,
+    depth: usize,
+) -> Result<CompiledObject, ClientCompileError> {
+    let selected_fields = expander.merge_object(
+        &field.selection_sets,
+        &semantics.wrapper_typename,
+        depth,
+        "aggregate field",
+    )?;
+    if selected_fields.is_empty() {
+        return Err(source_error(
+            "client.selection.empty",
+            format!(
+                "aggregate field `{}` must select `aggregate`, `nodes`, or `__typename`",
+                field.first.node.name.node
+            ),
+            document,
+            field.first.node.selection_set.pos,
+        ));
+    }
+    let mut members = Vec::with_capacity(selected_fields.len());
+    for selected in selected_fields {
+        let response_key = selected.first.node.response_key().node.to_string();
+        let field_name = selected.first.node.name.node.as_str();
+        if !selected.first.node.arguments.is_empty() {
+            return Err(source_error(
+                "client.selection.field_arguments",
+                format!("aggregate member `{field_name}` must not have arguments"),
+                document,
+                selected.first.pos,
+            ));
+        }
+        match field_name {
+            "aggregate" if semantics.count => {
+                if selected.selection_sets.is_empty() {
+                    return Err(source_error(
+                        "client.selection.object_required",
+                        "aggregate summary requires an object selection",
+                        document,
+                        selected.first.node.selection_set.pos,
+                    ));
+                }
+                members.push(CompiledMember::Branch(Box::new(CompiledBranch {
+                    semantic: CompiledBranchSemantic::AggregateFields,
+                    response_key,
+                    field: "aggregate".into(),
+                    cardinality: Cardinality::One,
+                    nullable: true,
+                    arguments: BTreeMap::new(),
+                    dependencies: dependencies.to_vec(),
+                    coverage: Some(complete_coverage()),
+                    filter: None,
+                    order: None,
+                    pagination: None,
+                    relationship: None,
+                    selection: compile_aggregate_fields_object(
+                        &selected,
+                        semantics,
+                        document,
+                        expander,
+                        depth + 1,
+                    )?,
+                })));
+            }
+            "nodes" if semantics.nodes => {
+                if selected.selection_sets.is_empty() {
+                    return Err(source_error(
+                        "client.selection.object_required",
+                        "aggregate nodes require an object selection",
+                        document,
+                        selected.first.node.selection_set.pos,
+                    ));
+                }
+                let coverage = compile_coverage(
+                    Some(&semantics.nodes_pagination),
+                    arguments,
+                    &format!("{}.nodes", field.first.node.name.node),
+                    document,
+                    selected.first.pos,
+                )?;
+                let mut selection = compile_model_object(
+                    &selected,
+                    model,
+                    manifest,
+                    variables,
+                    used_variables,
+                    document,
+                    expander,
+                    depth + 1,
+                )?;
+                let dependency_fields = query_plan_field_dependencies(
+                    model,
+                    filter_semantics,
+                    order_semantics,
+                    arguments,
+                    compiled_arguments,
+                );
+                inject_dependency_fields(
+                    &mut selection,
+                    model,
+                    &dependency_fields,
+                    document,
+                    selected.first.pos,
+                )?;
+                let (filter, order, pagination) = compile_query_plans(
+                    model,
+                    filter_semantics,
+                    order_semantics,
+                    arguments,
+                    compiled_arguments,
+                    variables,
+                    manifest,
+                    document,
+                    &field.first.node,
+                    coverage.as_ref(),
+                    filter_depth_from_selection(depth, 2),
+                    true,
+                )?;
+                members.push(CompiledMember::Branch(Box::new(CompiledBranch {
+                    semantic: CompiledBranchSemantic::AggregateNodes,
+                    response_key,
+                    field: "nodes".into(),
+                    cardinality: Cardinality::Many,
+                    nullable: false,
+                    arguments: BTreeMap::new(),
+                    dependencies: dependencies.to_vec(),
+                    coverage,
+                    filter,
+                    order,
+                    pagination,
+                    relationship: None,
+                    selection,
+                })));
+            }
+            "__typename" => {
+                if !selected.selection_sets.is_empty() {
+                    return Err(source_error(
+                        "client.selection.scalar_nested",
+                        "scalar field `__typename` cannot have a nested selection",
+                        document,
+                        selected.first.node.selection_set.pos,
+                    ));
+                }
+                members.push(CompiledMember::Scalar(CompiledScalar {
+                    response_key,
+                    field: "__typename".into(),
+                    codec: "string".into(),
+                    nullable: false,
+                    expose: true,
+                }));
+            }
+            "aggregate" | "nodes" => {
+                return Err(source_error(
+                    "client.selection.aggregate_denied",
+                    format!(
+                        "aggregate member `{field_name}` is absent from the selected manifest semantics"
+                    ),
+                    document,
+                    selected.first.node.name.pos,
+                ));
+            }
+            _ => {
+                return Err(source_error(
+                    "client.selection.denied_or_unknown",
+                    format!(
+                        "field `{field_name}` is absent from aggregate type `{}`",
+                        semantics.wrapper_typename
+                    ),
+                    document,
+                    selected.first.node.name.pos,
+                ));
+            }
+        }
+    }
+    Ok(CompiledObject {
+        typename: semantics.wrapper_typename.clone(),
+        storage: CompiledStorage::Embedded,
+        members,
+    })
+}
+
+pub(super) fn compile_aggregate_fields_object<'ast>(
+    field: &MergedField<'ast>,
+    semantics: &ManifestAggregateSemantics,
+    document: &ClientDocument,
+    expander: &mut FragmentExpander<'ast, '_>,
+    depth: usize,
+) -> Result<CompiledObject, ClientCompileError> {
+    let selected_fields = expander.merge_object(
+        &field.selection_sets,
+        &semantics.fields_typename,
+        depth,
+        "aggregate summary field",
+    )?;
+    if selected_fields.is_empty() {
+        return Err(source_error(
+            "client.selection.empty",
+            "aggregate summary must select at least one field",
+            document,
+            field.first.node.selection_set.pos,
+        ));
+    }
+    let mut members = Vec::with_capacity(selected_fields.len());
+    for selected in selected_fields {
+        let response_key = selected.first.node.response_key().node.to_string();
+        let field_name = selected.first.node.name.node.as_str();
+        if !selected.first.node.arguments.is_empty() || !selected.selection_sets.is_empty() {
+            return Err(source_error(
+                "client.selection.aggregate_metric_shape",
+                format!("aggregate metric `{field_name}` must be a scalar leaf"),
+                document,
+                selected.first.pos,
+            ));
+        }
+        match field_name {
+            "count" if semantics.count => members.push(CompiledMember::Scalar(CompiledScalar {
+                response_key,
+                field: "count".into(),
+                codec: "int32".into(),
+                nullable: false,
+                expose: true,
+            })),
+            "__typename" => members.push(CompiledMember::Scalar(CompiledScalar {
+                response_key,
+                field: "__typename".into(),
+                codec: "string".into(),
+                nullable: false,
+                expose: true,
+            })),
+            "sum" | "avg" | "min" | "max" => {
+                return Err(source_error(
+                    "client.selection.aggregate_metric_unsupported",
+                    format!(
+                        "aggregate metric `{field_name}` needs a typed metric-object contract before it can be compiled"
+                    ),
+                    document,
+                    selected.first.node.name.pos,
+                ));
+            }
+            _ => {
+                return Err(source_error(
+                    "client.selection.denied_or_unknown",
+                    format!(
+                        "field `{field_name}` is absent from aggregate summary type `{}`",
+                        semantics.fields_typename
+                    ),
+                    document,
+                    selected.first.node.name.pos,
+                ));
+            }
+        }
+    }
+    Ok(CompiledObject {
+        typename: semantics.fields_typename.clone(),
+        storage: CompiledStorage::Embedded,
+        members,
+    })
+}
+
+pub(super) fn compiled_scalar(
+    response_key: &str,
+    field: &ManifestField,
+    expose: bool,
+) -> CompiledScalar {
+    CompiledScalar {
+        response_key: response_key.to_string(),
+        field: field.name.clone(),
+        codec: field.codec.clone(),
+        nullable: field.nullable,
+        expose,
+    }
+}
diff --git a/distributed_cli/src/client_compiler/graphql/operation.rs b/distributed_cli/src/client_compiler/graphql/operation.rs
new file mode 100644
index 00000000..e6095d9e
--- /dev/null
+++ b/distributed_cli/src/client_compiler/graphql/operation.rs
@@ -0,0 +1,682 @@
+use super::*;
+
+pub(crate) fn compile_document(
+    document: &ClientDocument,
+    manifest: &ClientManifest,
+    registrations: &BTreeMap<String, String>,
+) -> Result<CompiledOperation, ClientCompileError> {
+    if document.source.len() > MAX_SOURCE_BYTES {
+        return Err(source_error(
+            "client.document.size",
+            format!("GraphQL document exceeds the supported {MAX_SOURCE_BYTES}-byte bound"),
+            document,
+            Pos::default(),
+        ));
+    }
+    let parsed = parse_query(&document.source).map_err(|error| {
+        let pos = error.positions().next().unwrap_or_default();
+        source_error(
+            "client.graphql.parse",
+            format!("invalid GraphQL document: {error}"),
+            document,
+            pos,
+        )
+    })?;
+    let (name, operation) = match &parsed.operations {
+        DocumentOperations::Single(operation) => {
+            return Err(source_error(
+                "client.operation.named_required",
+                "client operations must be explicitly named",
+                document,
+                operation.pos,
+            ));
+        }
+        DocumentOperations::Multiple(operations) if operations.len() == 1 => {
+            let (name, operation) = operations.iter().next().expect("length checked");
+            (name.as_str().to_string(), operation)
+        }
+        DocumentOperations::Multiple(operations) => {
+            let position = operations
+                .values()
+                .map(|operation| operation.pos)
+                .min()
+                .unwrap_or_default();
+            return Err(source_error(
+                "client.operation.one_per_document",
+                format!(
+                    "each client document must contain exactly one named operation; found {}",
+                    operations.len()
+                ),
+                document,
+                position,
+            ));
+        }
+    };
+    if operation.node.ty != OperationType::Query {
+        return Err(source_error(
+            "client.operation.query_required",
+            "application documents must declare a query; commands are generated from the manifest",
+            document,
+            operation.pos,
+        ));
+    }
+    let compiler_directives = compiler_directives(&operation.node, document)?;
+    let variables = compile_variables(&operation.node, document)?;
+    let mut expander = FragmentExpander::new(&parsed.fragments, document);
+    let root_fields =
+        expander.merge_object(&[&operation.node.selection_set], "Query", 1, "root field")?;
+    let root_field = single_root_field(root_fields, &operation.node, document)?;
+
+    let root_name = root_field.first.node.name.node.as_str();
+    let root_manifest = manifest
+        .root(RootOperation::Query, root_name)
+        .ok_or_else(|| {
+            source_error(
+                "client.root.denied_or_unknown",
+                format!("query root `{root_name}` is absent from the selected manifest surface"),
+                document,
+                root_field.first.node.name.pos,
+            )
+        })?;
+    let model = manifest.models.get(&root_manifest.model).ok_or_else(|| {
+        ClientCompileError::manifest(
+            "client.manifest.root_model",
+            format!(
+                "root `{root_name}` references absent model `{}`",
+                root_manifest.model
+            ),
+        )
+    })?;
+    validate_reachable_fragment_graph(&parsed.fragments, document, &operation.node.selection_set)?;
+    let mut used_variables = BTreeSet::new();
+    let compiled_arguments = compile_arguments(
+        &root_field.first.node,
+        &root_manifest.name,
+        &root_manifest.arguments,
+        model,
+        manifest,
+        &variables,
+        &mut used_variables,
+        document,
+    )?;
+    let mut selection = match root_manifest.kind {
+        RootKind::List | RootKind::ByPk => compile_model_object(
+            &root_field,
+            model,
+            manifest,
+            &variables,
+            &mut used_variables,
+            document,
+            &mut expander,
+            2,
+        )?,
+        RootKind::Aggregate => {
+            let semantics = root_manifest.aggregate.as_ref().ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.manifest.aggregate_semantics",
+                    format!("aggregate root `{root_name}` has no aggregate semantics"),
+                )
+            })?;
+            compile_aggregate_object(
+                &root_field,
+                model,
+                semantics,
+                &root_manifest.arguments,
+                &compiled_arguments,
+                root_manifest.filter.as_ref(),
+                root_manifest.order.as_ref(),
+                &root_manifest.dependencies,
+                manifest,
+                &variables,
+                &mut used_variables,
+                document,
+                &mut expander,
+                2,
+            )?
+        }
+    };
+    if root_manifest.kind == RootKind::List {
+        let dependencies = query_plan_field_dependencies(
+            model,
+            root_manifest.filter.as_ref(),
+            root_manifest.order.as_ref(),
+            &root_manifest.arguments,
+            &compiled_arguments,
+        );
+        inject_dependency_fields(
+            &mut selection,
+            model,
+            &dependencies,
+            document,
+            root_field.first.pos,
+        )?;
+    }
+    validate_used_variables(&variables, &used_variables, document, operation.pos)?;
+    expander.reject_unused_fragments()?;
+
+    let cardinality = match root_manifest.kind {
+        RootKind::List => Cardinality::Many,
+        RootKind::ByPk => Cardinality::One,
+        RootKind::Aggregate => Cardinality::One,
+    };
+    let coverage = match root_manifest.kind {
+        RootKind::Aggregate => Some(complete_coverage()),
+        RootKind::List | RootKind::ByPk => compile_coverage(
+            root_manifest.pagination.as_ref(),
+            &root_manifest.arguments,
+            &root_manifest.name,
+            document,
+            root_field.first.pos,
+        )?,
+    };
+    let (filter, order, pagination) = compile_query_plans(
+        model,
+        root_manifest.filter.as_ref(),
+        root_manifest.order.as_ref(),
+        &root_manifest.arguments,
+        &compiled_arguments,
+        &variables,
+        manifest,
+        document,
+        &root_field.first.node,
+        coverage.as_ref(),
+        0,
+        root_manifest.kind == RootKind::List,
+    )?;
+    let root = CompiledRoot {
+        response_key: root_field.first.node.response_key().node.to_string(),
+        field: root_name.to_string(),
+        cardinality,
+        nullable: matches!(root_manifest.kind, RootKind::ByPk | RootKind::Aggregate),
+        arguments: compiled_arguments,
+        dependencies: root_manifest.dependencies.clone(),
+        coverage,
+        filter,
+        order,
+        pagination,
+        selection,
+    };
+    validate_execution_limits(
+        &root,
+        root_manifest.kind,
+        &manifest.execution,
+        document,
+        operation.pos,
+    )?;
+
+    let query_document = render_operation(OperationType::Query, &name, &variables, &root)?;
+    let query_hash = hash_bytes(query_document.as_bytes());
+    let live = if compiler_directives.live {
+        Some(compile_live(
+            &name,
+            &variables,
+            &root,
+            root_manifest,
+            manifest,
+            document,
+            operation.pos,
+        )?)
+    } else {
+        None
+    };
+    let route = compile_route(
+        &name,
+        compiler_directives.load,
+        document,
+        registrations.get(&name),
+        operation.pos,
+    )?;
+    let variable_constraints = operation_variable_constraints(&root);
+    let variable_codec = compile_variable_codec(&variables, manifest, &variable_constraints)?;
+    let module_stem = module_stem(&name);
+    Ok(CompiledOperation {
+        name: name.clone(),
+        source_path: document.path.clone(),
+        source_line: operation.pos.line.max(1),
+        source_column: operation.pos.column.max(1),
+        module_path: format!("operations/{module_stem}.ts"),
+        export_name: format!("Operation_{name}"),
+        query_document,
+        query_hash,
+        live,
+        variables,
+        variable_codec,
+        root,
+        route,
+    })
+}
+
+#[derive(Default)]
+pub(super) struct CompilerDirectives {
+    load: bool,
+    live: bool,
+}
+
+pub(super) fn compiler_directives(
+    operation: &OperationDefinition,
+    document: &ClientDocument,
+) -> Result<CompilerDirectives, ClientCompileError> {
+    let mut result = CompilerDirectives::default();
+    let mut seen = BTreeSet::new();
+    for directive in &operation.directives {
+        let name = directive.node.name.node.as_str();
+        if !seen.insert(name) {
+            return Err(source_error(
+                "client.directive.duplicate",
+                format!("directive `@{name}` appears more than once"),
+                document,
+                directive.pos,
+            ));
+        }
+        if !directive.node.arguments.is_empty() {
+            return Err(source_error(
+                "client.directive.arguments",
+                format!("compiler directive `@{name}` does not accept arguments"),
+                document,
+                directive.pos,
+            ));
+        }
+        match name {
+            "load" => result.load = true,
+            "live" => result.live = true,
+            "skip" | "include" => {
+                return Err(source_error(
+                    "client.directive.conditional_unsupported",
+                    format!(
+                        "conditional directive `@{name}` requires a field-presence plan and is not supported yet"
+                    ),
+                    document,
+                    directive.pos,
+                ));
+            }
+            _ => {
+                return Err(source_error(
+                    "client.directive.unsupported",
+                    format!("operation directive `@{name}` is not supported"),
+                    document,
+                    directive.pos,
+                ));
+            }
+        }
+    }
+    Ok(result)
+}
+
+pub(super) fn compile_live(
+    query_name: &str,
+    variables: &[CompiledVariable],
+    root: &CompiledRoot,
+    query_manifest: &ManifestRoot,
+    manifest: &ClientManifest,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<CompiledLiveOperation, ClientCompileError> {
+    if !manifest.capabilities.live_queries || !query_manifest.live {
+        return Err(source_error(
+            "client.live.unavailable",
+            format!(
+                "`@live` was requested for `{query_name}`, but selected root `{}` is not live-capable",
+                query_manifest.name
+            ),
+            document,
+            position,
+        ));
+    }
+    let subscription = manifest
+        .root(RootOperation::Subscription, &query_manifest.name)
+        .ok_or_else(|| {
+            source_error(
+                "client.live.root_missing",
+                format!(
+                    "`@live` requires subscription root `{}` on the same selected surface",
+                    query_manifest.name
+                ),
+                document,
+                position,
+            )
+        })?;
+    if subscription.model != query_manifest.model
+        || subscription.kind != query_manifest.kind
+        || !arguments_compatible(&subscription.arguments, &query_manifest.arguments)
+        || !subscription.live
+        || subscription.dependencies != query_manifest.dependencies
+        || subscription.pagination != query_manifest.pagination
+    {
+        return Err(source_error(
+            "client.live.root_mismatch",
+            format!(
+                "subscription root `{}` does not exactly match query model, cardinality, arguments, dependencies, pagination, and live contract",
+                subscription.name
+            ),
+            document,
+            position,
+        ));
+    }
+    let live_name = format!("{query_name}_Live");
+    let document = render_operation(OperationType::Subscription, &live_name, variables, root)?;
+    Ok(CompiledLiveOperation {
+        hash: hash_bytes(document.as_bytes()),
+        document,
+    })
+}
+
+pub(super) fn arguments_compatible(left: &[ManifestArgument], right: &[ManifestArgument]) -> bool {
+    let canonical = |arguments: &[ManifestArgument]| {
+        arguments
+            .iter()
+            .map(|argument| {
+                (
+                    argument.name.clone(),
+                    argument.kind,
+                    argument.graphql_type(),
+                )
+            })
+            .collect::<BTreeSet<_>>()
+    };
+    canonical(left) == canonical(right)
+}
+
+pub(super) fn compile_route(
+    operation: &str,
+    load: bool,
+    document: &ClientDocument,
+    registration: Option<&String>,
+    position: Pos,
+) -> Result<Option<GeneratedRoutePlan>, ClientCompileError> {
+    if !load {
+        return Ok(None);
+    }
+    if let Some(route) = infer_route(&document.path) {
+        if registration.is_some() {
+            return Err(source_error(
+                "client.route.redundant_registration",
+                format!(
+                    "`{operation}` is already discovered from `{}`; remove its explicit route registration",
+                    document.path
+                ),
+                document,
+                position,
+            ));
+        }
+        return Ok(Some(GeneratedRoutePlan {
+            operation: operation.to_string(),
+            route,
+            source_path: document.path.clone(),
+            discovery: ClientRouteDiscovery::Convention,
+        }));
+    }
+    let Some(route) = registration else {
+        return Err(source_error(
+            "client.route.registration_required",
+            format!(
+                "`@load` operation `{operation}` is outside `src/routes/**/+page.graphql`; move it there or register `--route {operation}=/route-id`"
+            ),
+            document,
+            position,
+        ));
+    };
+    Ok(Some(GeneratedRoutePlan {
+        operation: operation.to_string(),
+        route: route.clone(),
+        source_path: document.path.clone(),
+        discovery: ClientRouteDiscovery::Explicit,
+    }))
+}
+
+pub(super) fn infer_route(path: &str) -> Option<String> {
+    let marker = "src/routes/";
+    let start = if path.starts_with(marker) {
+        marker.len()
+    } else {
+        path.find(&format!("/{marker}"))? + marker.len() + 1
+    };
+    let rest = path.get(start..)?;
+    if rest == "+page.graphql" {
+        return Some("/".into());
+    }
+    let directory = rest.strip_suffix("/+page.graphql")?;
+    if directory.is_empty() {
+        Some("/".into())
+    } else {
+        Some(format!("/{directory}"))
+    }
+}
+
+pub(super) fn render_operation(
+    operation_type: OperationType,
+    name: &str,
+    variables: &[CompiledVariable],
+    root: &CompiledRoot,
+) -> Result<String, ClientCompileError> {
+    let variable_definitions = if variables.is_empty() {
+        String::new()
+    } else {
+        format!(
+            "({})",
+            variables
+                .iter()
+                .map(render_variable)
+                .collect::<Result<Vec<_>, _>>()?
+                .join(", ")
+        )
+    };
+    let arguments = render_compiled_arguments(&root.arguments);
+    let root_prefix = if root.response_key == root.field {
+        root.field.clone()
+    } else {
+        format!("{}: {}", root.response_key, root.field)
+    };
+    let mut lines = vec![format!("{operation_type} {name}{variable_definitions} {{")];
+    lines.push(format!("  {root_prefix}{arguments} {{"));
+    render_object_selection(&mut lines, &root.selection, 4);
+    lines.push("  }".into());
+    lines.push("}".into());
+    Ok(format!("{}\n", lines.join("\n")))
+}
+
+pub(super) fn render_object_selection(
+    lines: &mut Vec<String>,
+    object: &CompiledObject,
+    indent: usize,
+) {
+    let padding = " ".repeat(indent);
+    for member in &object.members {
+        match member {
+            CompiledMember::Scalar(field) => {
+                let prefix = if field.response_key == field.field {
+                    field.field.clone()
+                } else {
+                    format!("{}: {}", field.response_key, field.field)
+                };
+                lines.push(format!("{padding}{prefix}"));
+            }
+            CompiledMember::Branch(branch) => {
+                let prefix = if branch.response_key == branch.field {
+                    branch.field.clone()
+                } else {
+                    format!("{}: {}", branch.response_key, branch.field)
+                };
+                let arguments = render_compiled_arguments(&branch.arguments);
+                lines.push(format!("{padding}{prefix}{arguments} {{"));
+                render_object_selection(lines, &branch.selection, indent + 2);
+                lines.push(format!("{padding}}}"));
+            }
+        }
+    }
+}
+
+pub(super) fn render_compiled_arguments(arguments: &BTreeMap<String, CompiledArgument>) -> String {
+    if arguments.is_empty() {
+        return String::new();
+    }
+    format!(
+        "({})",
+        arguments
+            .iter()
+            .map(|(name, value)| format!("{name}: {}", render_compiled_argument(value)))
+            .collect::<Vec<_>>()
+            .join(", ")
+    )
+}
+
+pub(super) fn render_compiled_argument(value: &CompiledArgument) -> String {
+    match value {
+        CompiledArgument::Literal { wire, .. } => wire.clone(),
+        CompiledArgument::Variable(variable) => format!("${variable}"),
+        CompiledArgument::List(values) => format!(
+            "[{}]",
+            values
+                .iter()
+                .map(render_compiled_argument)
+                .collect::<Vec<_>>()
+                .join(", ")
+        ),
+        CompiledArgument::Object(values) => format!(
+            "{{{}}}",
+            values
+                .iter()
+                .map(|(name, value)| format!("{name}: {}", render_compiled_argument(value)))
+                .collect::<Vec<_>>()
+                .join(", ")
+        ),
+    }
+}
+
+pub(super) fn render_variable(variable: &CompiledVariable) -> Result<String, ClientCompileError> {
+    Ok(format!("${}: {}", variable.name, variable.graphql_type))
+}
+
+pub(super) fn render_value(
+    value: &Value,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<String, ClientCompileError> {
+    match value {
+        Value::Variable(variable) => Ok(format!("${variable}")),
+        Value::Null => Ok("null".into()),
+        Value::Boolean(value) => Ok(value.to_string()),
+        Value::Number(value) => Ok(value.to_string()),
+        Value::String(value) => Ok(Value::String(value.clone()).to_string()),
+        Value::Binary(_) => Err(source_error(
+            "client.literal.binary",
+            "binary GraphQL literals are not portable to the JavaScript replica",
+            document,
+            position,
+        )),
+        Value::Enum(value) => Ok(value.to_string()),
+        Value::List(values) => Ok(format!(
+            "[{}]",
+            values
+                .iter()
+                .map(|value| render_value(value, document, position))
+                .collect::<Result<Vec<_>, _>>()?
+                .join(", ")
+        )),
+        Value::Object(values) => {
+            let sorted = values.iter().collect::<BTreeMap<_, _>>();
+            Ok(format!(
+                "{{{}}}",
+                sorted
+                    .into_iter()
+                    .map(|(name, value)| {
+                        Ok(format!(
+                            "{name}: {}",
+                            render_value(value, document, position)?
+                        ))
+                    })
+                    .collect::<Result<Vec<_>, ClientCompileError>>()?
+                    .join(", ")
+            ))
+        }
+    }
+}
+
+pub(super) fn variable_type_compatible(variable: &Type, argument: &Type) -> bool {
+    if !argument.nullable && variable.nullable {
+        return false;
+    }
+    match (&variable.base, &argument.base) {
+        (BaseType::Named(variable), BaseType::Named(argument)) => variable == argument,
+        (BaseType::List(variable), BaseType::List(argument)) => {
+            variable_type_compatible(variable, argument)
+        }
+        _ => false,
+    }
+}
+
+pub(crate) fn typescript_scalar(
+    field: &CompiledScalar,
+) -> Result<&'static str, ClientCompileError> {
+    match field.codec.as_str() {
+        "boolean" => Ok("boolean"),
+        "float64" | "int32" | "json_number_precision_limited" => Ok("number"),
+        "string" | "base64" | "string_unvalidated_timestamp" => Ok("string"),
+        "json" => Ok("unknown"),
+        codec => Err(ClientCompileError::manifest(
+            "client.scalar.codec_unsupported",
+            format!(
+                "field `{}` uses unsupported TypeScript codec `{codec}`",
+                field.field
+            ),
+        )),
+    }
+}
+
+pub(super) fn module_stem(name: &str) -> String {
+    let mut result = String::new();
+    for (index, character) in name.chars().enumerate() {
+        if character == '_' {
+            if !result.ends_with('-') {
+                result.push('-');
+            }
+        } else if character.is_ascii_uppercase() {
+            if index > 0 && !result.ends_with('-') {
+                result.push('-');
+            }
+            result.push(character.to_ascii_lowercase());
+        } else {
+            result.push(character.to_ascii_lowercase());
+        }
+    }
+    result
+}
+
+pub(super) fn source_error(
+    code: &'static str,
+    message: impl Into<String>,
+    document: &ClientDocument,
+    position: Pos,
+) -> ClientCompileError {
+    ClientCompileError::source(
+        code,
+        message,
+        &document.path,
+        position.line.max(1),
+        position.column.max(1),
+    )
+}
+
+#[cfg(test)]
+mod local_tests {
+    use super::{infer_route, module_stem};
+
+    #[test]
+    fn route_convention_is_narrow() {
+        assert_eq!(
+            infer_route("src/routes/todos/+page.graphql").as_deref(),
+            Some("/todos")
+        );
+        assert_eq!(
+            infer_route("/tmp/app/src/routes/+page.graphql").as_deref(),
+            Some("/")
+        );
+        assert_eq!(infer_route("src/lib/todos.graphql"), None);
+        assert_eq!(infer_route("src/routes/todos/query.graphql"), None);
+    }
+
+    #[test]
+    fn module_names_are_portable() {
+        assert_eq!(module_stem("TodosForUser"), "todos-for-user");
+        assert_eq!(module_stem("todos_for_user"), "todos-for-user");
+    }
+}
diff --git a/distributed_cli/src/client_compiler/graphql/query_plan.rs b/distributed_cli/src/client_compiler/graphql/query_plan.rs
new file mode 100644
index 00000000..12e4ec37
--- /dev/null
+++ b/distributed_cli/src/client_compiler/graphql/query_plan.rs
@@ -0,0 +1,560 @@
+use super::*;
+
+pub(super) fn inject_wire_fields(
+    members: &mut Vec<CompiledMember>,
+    model: &ManifestModel,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    let identity = model
+        .identity()
+        .expect("embedded model rejected before injection");
+    let mut response_keys = members
+        .iter()
+        .map(|member| match member {
+            CompiledMember::Scalar(scalar) => scalar.response_key.clone(),
+            CompiledMember::Branch(branch) => branch.response_key.clone(),
+        })
+        .collect::<BTreeSet<_>>();
+    for identity_field in identity {
+        if members.iter().any(|member| match member {
+            CompiledMember::Scalar(scalar) => scalar.field == identity_field.name,
+            CompiledMember::Branch(_) => false,
+        }) {
+            continue;
+        }
+        let field = model.field(&identity_field.name).ok_or_else(|| {
+            source_error(
+                "client.selection.identity_denied",
+                format!(
+                    "normalized identity `{}` is not selectable on model `{}`",
+                    identity_field.name, model.id
+                ),
+                document,
+                position,
+            )
+        })?;
+        let response_key = allocate_wire_alias(&identity_field.name, &mut response_keys);
+        members.push(CompiledMember::Scalar(compiled_scalar(
+            &response_key,
+            field,
+            false,
+        )));
+    }
+    if !members.iter().any(|member| match member {
+        CompiledMember::Scalar(scalar) => scalar.field == "__typename",
+        CompiledMember::Branch(_) => false,
+    }) {
+        let response_key = allocate_wire_alias("typename", &mut response_keys);
+        members.push(CompiledMember::Scalar(CompiledScalar {
+            response_key,
+            field: "__typename".into(),
+            codec: "string".into(),
+            nullable: false,
+            expose: false,
+        }));
+    }
+    Ok(())
+}
+
+pub(super) fn query_plan_field_dependencies(
+    model: &ManifestModel,
+    filter: Option<&ManifestFilterSemantics>,
+    order: Option<&ManifestOrderSemantics>,
+    declared_arguments: &[ManifestArgument],
+    compiled_arguments: &BTreeMap<String, CompiledArgument>,
+) -> BTreeSet<String> {
+    let mut fields = BTreeSet::new();
+    let mut relationships = BTreeSet::new();
+    if let Some(filter) = filter {
+        if let ManifestRowPolicy::Predicate { expression } = &filter.row_policy {
+            collect_policy_fields(expression, &mut fields, &mut relationships);
+        }
+        if let Some(argument) = declared_arguments
+            .iter()
+            .find(|argument| argument.kind == ManifestArgumentKind::Filter)
+            .and_then(|argument| compiled_arguments.get(&argument.name))
+        {
+            collect_filter_source_fields(argument, filter, &mut fields, &mut relationships);
+        }
+    }
+    if let Some(order) = order {
+        if let Some(argument) = declared_arguments
+            .iter()
+            .find(|argument| argument.kind == ManifestArgumentKind::Order)
+            .and_then(|argument| compiled_arguments.get(&argument.name))
+        {
+            collect_order_source_fields(argument, order, &mut fields);
+        }
+    }
+    for relationship_name in relationships {
+        if let Some(relationship) = model.relationship(&relationship_name) {
+            let (local, _) = relationship_key_fields(&relationship.key_mapping);
+            fields.extend(local.iter().cloned());
+        }
+    }
+    fields
+}
+
+pub(super) fn collect_filter_source_fields(
+    source: &CompiledArgument,
+    semantics: &ManifestFilterSemantics,
+    fields: &mut BTreeSet<String>,
+    relationships: &mut BTreeSet<String>,
+) {
+    match source {
+        CompiledArgument::Variable(_) => {
+            fields.extend(semantics.fields.iter().map(|field| field.name.clone()));
+            relationships.extend(semantics.relationships.iter().cloned());
+        }
+        CompiledArgument::Literal { value, .. } => {
+            collect_client_filter_fields(value, semantics, fields, relationships);
+        }
+        CompiledArgument::List(items) => {
+            for item in items {
+                collect_filter_source_fields(item, semantics, fields, relationships);
+            }
+        }
+        CompiledArgument::Object(values) => {
+            for (name, value) in values {
+                match name.as_str() {
+                    "_and" | "_or" | "_not" => {
+                        collect_filter_source_fields(value, semantics, fields, relationships);
+                    }
+                    field
+                        if semantics
+                            .fields
+                            .iter()
+                            .any(|candidate| candidate.name == field) =>
+                    {
+                        fields.insert(field.to_string());
+                    }
+                    relationship
+                        if semantics
+                            .relationships
+                            .iter()
+                            .any(|candidate| candidate == relationship) =>
+                    {
+                        relationships.insert(relationship.to_string());
+                    }
+                    _ => {}
+                }
+            }
+        }
+    }
+}
+
+pub(super) fn collect_order_source_fields(
+    source: &CompiledArgument,
+    semantics: &ManifestOrderSemantics,
+    fields: &mut BTreeSet<String>,
+) {
+    match source {
+        CompiledArgument::Variable(_) => fields.extend(semantics.fields.iter().cloned()),
+        CompiledArgument::Literal { value, .. } => {
+            if let Some(entries) = value.as_array() {
+                for entry in entries {
+                    if let Some(object) = entry.as_object() {
+                        fields.extend(object.keys().cloned());
+                    }
+                }
+            }
+        }
+        CompiledArgument::List(items) => {
+            for item in items {
+                collect_order_source_fields(item, semantics, fields);
+            }
+        }
+        CompiledArgument::Object(values) => fields.extend(values.keys().cloned()),
+    }
+}
+
+pub(super) fn collect_policy_fields(
+    expression: &ManifestFilterExpr,
+    fields: &mut BTreeSet<String>,
+    relationships: &mut BTreeSet<String>,
+) {
+    match expression {
+        ManifestFilterExpr::And(expressions) | ManifestFilterExpr::Or(expressions) => {
+            for expression in expressions {
+                collect_policy_fields(expression, fields, relationships);
+            }
+        }
+        ManifestFilterExpr::Not(expression) => {
+            collect_policy_fields(expression, fields, relationships)
+        }
+        ManifestFilterExpr::Cmp { column, .. }
+        | ManifestFilterExpr::In { column, .. }
+        | ManifestFilterExpr::IsNull { column, .. } => {
+            fields.insert(column.clone());
+        }
+        ManifestFilterExpr::Rel { field, .. } => {
+            relationships.insert(field.clone());
+        }
+    }
+}
+
+pub(super) fn collect_client_filter_fields(
+    value: &JsonValue,
+    semantics: &ManifestFilterSemantics,
+    fields: &mut BTreeSet<String>,
+    relationships: &mut BTreeSet<String>,
+) {
+    let Some(object) = value.as_object() else {
+        return;
+    };
+    for (name, value) in object {
+        match name.as_str() {
+            "_and" | "_or" => {
+                if let Some(items) = value.as_array() {
+                    for item in items {
+                        collect_client_filter_fields(item, semantics, fields, relationships);
+                    }
+                }
+            }
+            "_not" => collect_client_filter_fields(value, semantics, fields, relationships),
+            field
+                if semantics
+                    .fields
+                    .iter()
+                    .any(|candidate| candidate.name == field) =>
+            {
+                fields.insert(field.to_string());
+            }
+            relationship
+                if semantics
+                    .relationships
+                    .iter()
+                    .any(|candidate| candidate == relationship) =>
+            {
+                relationships.insert(relationship.to_string());
+            }
+            _ => {}
+        }
+    }
+}
+
+pub(super) fn inject_dependency_fields(
+    selection: &mut CompiledObject,
+    model: &ManifestModel,
+    dependencies: &BTreeSet<String>,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    let mut response_keys = selection
+        .members
+        .iter()
+        .map(|member| match member {
+            CompiledMember::Scalar(scalar) => scalar.response_key.clone(),
+            CompiledMember::Branch(branch) => branch.response_key.clone(),
+        })
+        .collect::<BTreeSet<_>>();
+    for dependency in dependencies {
+        if selection.members.iter().any(|member| match member {
+            CompiledMember::Scalar(scalar) => scalar.field == *dependency,
+            CompiledMember::Branch(_) => false,
+        }) {
+            continue;
+        }
+        let field = model.field(dependency).ok_or_else(|| {
+            source_error(
+                "client.selection.dependency_denied",
+                format!(
+                    "query-index dependency `{dependency}` is not selectable on model `{}`",
+                    model.id
+                ),
+                document,
+                position,
+            )
+        })?;
+        let response_key = allocate_wire_alias(dependency, &mut response_keys);
+        selection
+            .members
+            .push(CompiledMember::Scalar(compiled_scalar(
+                &response_key,
+                field,
+                false,
+            )));
+    }
+    Ok(())
+}
+
+pub(super) fn allocate_wire_alias(field: &str, used: &mut BTreeSet<String>) -> String {
+    let stem = format!("_distributed_{field}");
+    if used.insert(stem.clone()) {
+        return stem;
+    }
+    for suffix in 2_u64.. {
+        let candidate = format!("{stem}_{suffix}");
+        if used.insert(candidate.clone()) {
+            return candidate;
+        }
+    }
+    unreachable!("finite set always admits another suffix")
+}
+
+pub(super) fn compile_coverage(
+    pagination: Option<&ManifestPagination>,
+    arguments: &[ManifestArgument],
+    owner: &str,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<Option<CompiledCoverage>, ClientCompileError> {
+    let Some(pagination) = pagination else {
+        return Ok(Some(complete_coverage()));
+    };
+    if pagination.kind != "offset" || pagination.coverage != "window" {
+        return Err(source_error(
+            "client.pagination.unsupported",
+            format!(
+                "field `{owner}` uses unsupported pagination contract kind=`{}` coverage=`{}`",
+                pagination.kind, pagination.coverage
+            ),
+            document,
+            position,
+        ));
+    }
+    Ok(Some(CompiledCoverage {
+        kind: "offset".into(),
+        offset_argument: arguments
+            .iter()
+            .find(|argument| argument.kind == ManifestArgumentKind::Offset)
+            .map(|argument| argument.name.clone()),
+        limit_argument: arguments
+            .iter()
+            .find(|argument| argument.kind == ManifestArgumentKind::Limit)
+            .map(|argument| argument.name.clone()),
+        default_limit: Some(pagination.default_limit),
+        max_limit: Some(pagination.max_limit),
+    }))
+}
+
+pub(super) fn complete_coverage() -> CompiledCoverage {
+    CompiledCoverage {
+        kind: "complete".into(),
+        offset_argument: None,
+        limit_argument: None,
+        default_limit: None,
+        max_limit: None,
+    }
+}
+
+pub(super) fn compiled_pagination_plan(coverage: &CompiledCoverage) -> CompiledPaginationPlan {
+    match coverage.kind.as_str() {
+        "complete" => CompiledPaginationPlan {
+            kind: "complete".into(),
+            insert: "local".into(),
+            delete: "local".into(),
+            reorder: "local".into(),
+            stable_update: "local".into(),
+        },
+        "offset" => CompiledPaginationPlan {
+            kind: "offset".into(),
+            // Runtime locality is still fail-closed: these operations are
+            // applied only when observed coverage proves a non-full first
+            // page. Full, shifted, or ambiguous windows revalidate.
+            insert: "local".into(),
+            delete: "local".into(),
+            reorder: "local".into(),
+            stable_update: "local".into(),
+        },
+        other => CompiledPaginationPlan {
+            kind: other.into(),
+            insert: "revalidate".into(),
+            delete: "revalidate".into(),
+            reorder: "revalidate".into(),
+            stable_update: "revalidate".into(),
+        },
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn compile_query_plans(
+    model: &ManifestModel,
+    filter: Option<&ManifestFilterSemantics>,
+    order: Option<&ManifestOrderSemantics>,
+    declared_arguments: &[ManifestArgument],
+    compiled_arguments: &BTreeMap<String, CompiledArgument>,
+    variables: &[CompiledVariable],
+    manifest: &ClientManifest,
+    document: &ClientDocument,
+    field: &Field,
+    pagination: Option<&CompiledCoverage>,
+    filter_base_depth: u64,
+    list_index: bool,
+) -> Result<CompiledQueryPlans, ClientCompileError> {
+    let filter_argument = declared_arguments
+        .iter()
+        .find(|argument| argument.kind == ManifestArgumentKind::Filter);
+    let order_argument = declared_arguments
+        .iter()
+        .find(|argument| argument.kind == ManifestArgumentKind::Order);
+
+    let filter_plan = match filter {
+        Some(semantics) => {
+            let mut variable_constraints = BTreeMap::new();
+            let input = filter_argument
+                .and_then(|argument| compiled_arguments.get(&argument.name))
+                .cloned();
+            if let Some(input) = &input {
+                let input_type = filter_argument
+                    .map(ManifestArgument::graphql_type)
+                    .ok_or_else(|| {
+                        ClientCompileError::manifest(
+                            "client.manifest.filter_argument",
+                            format!(
+                                "model `{}` has filter semantics without an argument",
+                                model.id
+                            ),
+                        )
+                    })?;
+                validate_filter_source(
+                    input,
+                    model,
+                    &model.filter_input,
+                    &input_type,
+                    variables,
+                    manifest,
+                    &manifest.execution,
+                    document,
+                    argument_position(field, filter_argument.map(|value| value.name.as_str())),
+                    filter_base_depth,
+                    &mut variable_constraints,
+                )?;
+            }
+            let fields = semantics
+                .fields
+                .iter()
+                .map(|filter_field| {
+                    let field = model.field(&filter_field.name).ok_or_else(|| {
+                        ClientCompileError::manifest(
+                            "client.manifest.filter_field",
+                            format!(
+                                "filter plan for model `{}` references absent field `{}`",
+                                model.id, filter_field.name
+                            ),
+                        )
+                    })?;
+                    Ok(CompiledFilterField {
+                        name: field.name.clone(),
+                        scalar: field.scalar.clone(),
+                        codec: field.codec.clone(),
+                        nullable: field.nullable,
+                        operators: filter_field.operators.clone(),
+                    })
+                })
+                .collect::<Result<Vec<_>, ClientCompileError>>()?;
+            let relationships = semantics
+                .relationships
+                .iter()
+                .map(|name| {
+                    model
+                        .relationship(name)
+                        .map(compiled_relationship_plan)
+                        .ok_or_else(|| {
+                            ClientCompileError::manifest(
+                                "client.manifest.filter_relationship",
+                                format!(
+                                    "filter plan for model `{}` references absent relationship `{name}`",
+                                    model.id
+                                ),
+                            )
+                        })
+                })
+                .collect::<Result<Vec<_>, ClientCompileError>>()?;
+            Some(CompiledFilterPlan {
+                input,
+                fields,
+                relationships,
+                row_policy: semantics.row_policy.clone(),
+                variable_constraints,
+            })
+        }
+        None => None,
+    };
+
+    let order_plan = match order {
+        Some(semantics) => {
+            let input = order_argument
+                .and_then(|argument| compiled_arguments.get(&argument.name))
+                .cloned();
+            if let Some(input) = &input {
+                validate_order_source(
+                    input,
+                    semantics,
+                    order_argument,
+                    variables,
+                    document,
+                    argument_position(field, order_argument.map(|value| value.name.as_str())),
+                )?;
+            }
+            let fields = semantics
+                .fields
+                .iter()
+                .map(|name| compiled_order_field(model, name))
+                .collect::<Result<Vec<_>, _>>()?;
+            let identity = model
+                .identity()
+                .unwrap_or_default()
+                .iter()
+                .map(|identity| compiled_order_field(model, &identity.name))
+                .collect::<Result<Vec<_>, _>>()?;
+            Some(CompiledOrderPlan {
+                input,
+                fields,
+                identity,
+            })
+        }
+        None if list_index => Some(CompiledOrderPlan {
+            input: None,
+            fields: Vec::new(),
+            identity: model
+                .identity()
+                .unwrap_or_default()
+                .iter()
+                .map(|identity| compiled_order_field(model, &identity.name))
+                .collect::<Result<Vec<_>, _>>()?,
+        }),
+        None => None,
+    };
+
+    let pagination_plan = if list_index {
+        pagination.map(compiled_pagination_plan)
+    } else {
+        None
+    };
+
+    Ok((filter_plan, order_plan, pagination_plan))
+}
+
+pub(super) fn compiled_order_field(
+    model: &ManifestModel,
+    name: &str,
+) -> Result<CompiledOrderField, ClientCompileError> {
+    let field = model.field(name).ok_or_else(|| {
+        ClientCompileError::manifest(
+            "client.manifest.order_field",
+            format!(
+                "order plan for model `{}` references absent field `{name}`",
+                model.id
+            ),
+        )
+    })?;
+    Ok(CompiledOrderField {
+        name: field.name.clone(),
+        scalar: field.scalar.clone(),
+        codec: field.codec.clone(),
+        nullable: field.nullable,
+    })
+}
+
+pub(super) fn argument_position(field: &Field, name: Option<&str>) -> Pos {
+    name.and_then(|name| {
+        field
+            .arguments
+            .iter()
+            .find(|(argument, _)| argument.node.as_str() == name)
+            .map(|(_, value)| value.pos)
+    })
+    .unwrap_or(field.name.pos)
+}
diff --git a/distributed_cli/src/client_compiler/graphql/types.rs b/distributed_cli/src/client_compiler/graphql/types.rs
new file mode 100644
index 00000000..78912c5e
--- /dev/null
+++ b/distributed_cli/src/client_compiler/graphql/types.rs
@@ -0,0 +1,344 @@
+use super::*;
+
+pub(super) const MAX_SOURCE_BYTES: usize = 1024 * 1024;
+pub(super) const MAX_VARIABLES: usize = 256;
+pub(super) const MAX_OBJECT_DEPTH: usize = 64;
+pub(super) const MAX_EXPANDED_SELECTIONS: usize = 10_000;
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledOperation {
+    pub(crate) name: String,
+    pub(crate) source_path: String,
+    pub(crate) source_line: usize,
+    pub(crate) source_column: usize,
+    pub(crate) module_path: String,
+    pub(crate) export_name: String,
+    pub(crate) query_document: String,
+    pub(crate) query_hash: String,
+    pub(crate) live: Option<CompiledLiveOperation>,
+    pub(crate) variables: Vec<CompiledVariable>,
+    pub(crate) variable_codec: CompiledVariableCodec,
+    pub(crate) root: CompiledRoot,
+    pub(crate) route: Option<GeneratedRoutePlan>,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledLiveOperation {
+    pub(crate) document: String,
+    pub(crate) hash: String,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledVariable {
+    pub(crate) name: String,
+    pub(crate) graphql_type: Type,
+}
+
+#[derive(Clone, Debug, Serialize)]
+pub(crate) struct CompiledVariableCodec {
+    pub(crate) version: u32,
+    pub(crate) limits: CompiledVariableCodecLimits,
+    pub(crate) variables: BTreeMap<String, CompiledInputType>,
+    pub(crate) inputs: BTreeMap<String, CompiledInputDefinition>,
+}
+
+#[derive(Clone, Debug, Serialize)]
+pub(crate) struct CompiledVariableCodecLimits {
+    #[serde(rename = "maxDepth")]
+    pub(crate) max_depth: u64,
+    #[serde(rename = "maxBoolWidth")]
+    pub(crate) max_bool_width: u64,
+    #[serde(rename = "maxInList")]
+    pub(crate) max_in_list: u64,
+}
+
+#[derive(Clone, Debug, Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub(crate) enum CompiledInputType {
+    Scalar {
+        scalar: String,
+        codec: String,
+        nullable: bool,
+    },
+    Enum {
+        name: String,
+        values: Vec<String>,
+        nullable: bool,
+    },
+    Input {
+        name: String,
+        nullable: bool,
+        #[serde(rename = "filterBaseDepth", skip_serializing_if = "Option::is_none")]
+        filter_base_depth: Option<u64>,
+    },
+    List {
+        nullable: bool,
+        #[serde(rename = "maxItems", skip_serializing_if = "Option::is_none")]
+        max_items: Option<u64>,
+        item: Box<CompiledInputType>,
+    },
+}
+
+#[derive(Clone, Debug, Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub(crate) enum CompiledInputDefinition {
+    Filter {
+        model: String,
+        fields: Vec<CompiledFilterInputField>,
+        relationships: Vec<CompiledFilterInputRelationship>,
+    },
+    Order {
+        model: String,
+        fields: Vec<CompiledOrderInputField>,
+        values: Vec<String>,
+    },
+}
+
+#[derive(Clone, Debug, Serialize)]
+pub(crate) struct CompiledFilterInputField {
+    pub(crate) field: String,
+    pub(crate) scalar: String,
+    pub(crate) codec: String,
+    pub(crate) nullable: bool,
+    pub(crate) operators: Vec<String>,
+}
+
+#[derive(Clone, Debug, Serialize)]
+pub(crate) struct CompiledOrderInputField {
+    pub(crate) field: String,
+    pub(crate) scalar: String,
+    pub(crate) codec: String,
+    pub(crate) nullable: bool,
+}
+
+#[derive(Clone, Debug, Serialize)]
+pub(crate) struct CompiledFilterInputRelationship {
+    pub(crate) field: String,
+    pub(crate) target: CompiledFilterInputTarget,
+}
+
+#[derive(Clone, Debug, Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub(crate) enum CompiledFilterInputTarget {
+    Input { name: String },
+    Opaque,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledRoot {
+    pub(crate) response_key: String,
+    pub(crate) field: String,
+    pub(crate) cardinality: Cardinality,
+    pub(crate) nullable: bool,
+    pub(crate) arguments: BTreeMap<String, CompiledArgument>,
+    pub(crate) dependencies: Vec<String>,
+    pub(crate) coverage: Option<CompiledCoverage>,
+    pub(crate) filter: Option<CompiledFilterPlan>,
+    pub(crate) order: Option<CompiledOrderPlan>,
+    pub(crate) pagination: Option<CompiledPaginationPlan>,
+    pub(crate) selection: CompiledObject,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledObject {
+    pub(crate) typename: String,
+    pub(crate) storage: CompiledStorage,
+    pub(crate) members: Vec<CompiledMember>,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) enum CompiledMember {
+    Scalar(CompiledScalar),
+    Branch(Box<CompiledBranch>),
+}
+
+#[derive(Clone, Debug)]
+pub(crate) enum CompiledStorage {
+    Normalized {
+        model_id: String,
+        identity_fields: Vec<String>,
+    },
+    Embedded,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledBranch {
+    pub(crate) semantic: CompiledBranchSemantic,
+    pub(crate) response_key: String,
+    pub(crate) field: String,
+    pub(crate) cardinality: Cardinality,
+    pub(crate) nullable: bool,
+    pub(crate) arguments: BTreeMap<String, CompiledArgument>,
+    pub(crate) dependencies: Vec<String>,
+    pub(crate) coverage: Option<CompiledCoverage>,
+    pub(crate) filter: Option<CompiledFilterPlan>,
+    pub(crate) order: Option<CompiledOrderPlan>,
+    pub(crate) pagination: Option<CompiledPaginationPlan>,
+    pub(crate) relationship: Option<CompiledRelationshipPlan>,
+    pub(crate) selection: CompiledObject,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum CompiledBranchSemantic {
+    Relationship,
+    Aggregate,
+    AggregateFields,
+    AggregateNodes,
+}
+
+pub(super) struct MergedField<'a> {
+    pub(super) first: &'a Positioned<Field>,
+    pub(super) selection_sets: Vec<&'a Positioned<SelectionSet>>,
+    pub(super) canonical_arguments: Vec<(String, String)>,
+}
+
+pub(super) struct FragmentExpander<'ast, 'source> {
+    pub(super) fragments: &'ast HashMap<Name, Positioned<FragmentDefinition>>,
+    pub(super) document: &'source ClientDocument,
+    pub(super) state: ExpansionState,
+}
+
+#[derive(Default)]
+pub(super) struct ExpansionState {
+    pub(super) used_fragments: BTreeSet<String>,
+    pub(super) active_fragments: Vec<String>,
+    pub(super) expanded_units: usize,
+}
+
+#[derive(Default)]
+pub(super) struct FragmentGraphState {
+    pub(super) active_fragments: Vec<String>,
+    pub(super) completed_fragments: BTreeSet<String>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum Cardinality {
+    One,
+    Many,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) enum CompiledArgument {
+    Literal { value: JsonValue, wire: String },
+    Variable(String),
+    List(Vec<CompiledArgument>),
+    Object(BTreeMap<String, CompiledArgument>),
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledCoverage {
+    pub(crate) kind: String,
+    pub(crate) offset_argument: Option<String>,
+    pub(crate) limit_argument: Option<String>,
+    pub(crate) default_limit: Option<u64>,
+    pub(crate) max_limit: Option<u64>,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledFilterPlan {
+    pub(crate) input: Option<CompiledArgument>,
+    pub(crate) fields: Vec<CompiledFilterField>,
+    pub(crate) relationships: Vec<CompiledRelationshipPlan>,
+    pub(crate) row_policy: ManifestRowPolicy,
+    pub(super) variable_constraints: BTreeMap<String, VariableUseConstraint>,
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub(super) struct VariableUseConstraint {
+    pub(super) filter_base_depth: Option<u64>,
+    pub(super) max_items: Option<u64>,
+    pub(super) item: Option<Box<VariableUseConstraint>>,
+}
+
+impl VariableUseConstraint {
+    pub(super) fn filter(base_depth: u64) -> Self {
+        Self {
+            filter_base_depth: Some(base_depth),
+            ..Self::default()
+        }
+    }
+
+    pub(super) fn list(max_items: u64, item: Option<Self>) -> Self {
+        Self {
+            max_items: Some(max_items),
+            item: item.map(Box::new),
+            ..Self::default()
+        }
+    }
+
+    pub(super) fn intersect(&mut self, other: &Self) {
+        self.filter_base_depth = match (self.filter_base_depth, other.filter_base_depth) {
+            (Some(left), Some(right)) => Some(left.max(right)),
+            (left, right) => left.or(right),
+        };
+        self.max_items = match (self.max_items, other.max_items) {
+            (Some(left), Some(right)) => Some(left.min(right)),
+            (left, right) => left.or(right),
+        };
+        match (&mut self.item, &other.item) {
+            (Some(left), Some(right)) => left.intersect(right),
+            (None, Some(right)) => self.item = Some(right.clone()),
+            _ => {}
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledFilterField {
+    pub(crate) name: String,
+    pub(crate) scalar: String,
+    pub(crate) codec: String,
+    pub(crate) nullable: bool,
+    pub(crate) operators: Vec<String>,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledRelationshipPlan {
+    pub(crate) field: String,
+    pub(crate) target_model: String,
+    pub(crate) kind: ManifestRelationshipKind,
+    pub(crate) key_mapping: ManifestRelationshipKeyMapping,
+    pub(crate) maintenance: ManifestRelationshipMaintenance,
+    pub(crate) dependencies: Vec<String>,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledOrderPlan {
+    pub(crate) input: Option<CompiledArgument>,
+    pub(crate) fields: Vec<CompiledOrderField>,
+    pub(crate) identity: Vec<CompiledOrderField>,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledOrderField {
+    pub(crate) name: String,
+    pub(crate) scalar: String,
+    pub(crate) codec: String,
+    pub(crate) nullable: bool,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledPaginationPlan {
+    pub(crate) kind: String,
+    pub(crate) insert: String,
+    pub(crate) delete: String,
+    pub(crate) reorder: String,
+    pub(crate) stable_update: String,
+}
+
+pub(super) type CompiledQueryPlans = (
+    Option<CompiledFilterPlan>,
+    Option<CompiledOrderPlan>,
+    Option<CompiledPaginationPlan>,
+);
+
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledScalar {
+    pub(crate) response_key: String,
+    pub(crate) field: String,
+    pub(crate) codec: String,
+    pub(crate) nullable: bool,
+    pub(crate) expose: bool,
+}
diff --git a/distributed_cli/src/client_compiler/graphql/validation.rs b/distributed_cli/src/client_compiler/graphql/validation.rs
new file mode 100644
index 00000000..abe7080b
--- /dev/null
+++ b/distributed_cli/src/client_compiler/graphql/validation.rs
@@ -0,0 +1,1214 @@
+use super::*;
+
+pub(super) fn validate_execution_limits(
+    root: &CompiledRoot,
+    kind: RootKind,
+    execution: &ManifestExecutionLimits,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    let depth = compiled_object_depth(&root.selection, 1);
+    if depth > execution.max_depth {
+        return Err(source_error(
+            "client.operation.depth_limit",
+            format!(
+                "compiled operation depth {depth} exceeds the selected service max_depth {}",
+                execution.max_depth
+            ),
+            document,
+            position,
+        ));
+    }
+
+    let weights = &execution.complexity;
+    let child = compiled_object_complexity(&root.selection, weights);
+    let complexity = match kind {
+        RootKind::List => weights
+            .list_root
+            .saturating_add(weights.list_fanout.saturating_mul(child)),
+        RootKind::ByPk => weights.by_pk.saturating_add(child),
+        RootKind::Aggregate => weights.aggregate.saturating_add(child),
+    };
+    if complexity > execution.max_complexity {
+        return Err(source_error(
+            "client.operation.complexity_limit",
+            format!(
+                "compiled operation complexity {complexity} exceeds the selected service max_complexity {}",
+                execution.max_complexity
+            ),
+            document,
+            position,
+        ));
+    }
+    Ok(())
+}
+
+pub(super) fn compiled_object_depth(selection: &CompiledObject, parent_depth: u64) -> u64 {
+    selection
+        .members
+        .iter()
+        .map(|member| {
+            let field_depth = parent_depth.saturating_add(1);
+            match member {
+                CompiledMember::Scalar(_) => field_depth,
+                CompiledMember::Branch(branch) => {
+                    field_depth.max(compiled_object_depth(&branch.selection, field_depth))
+                }
+            }
+        })
+        .max()
+        .unwrap_or(parent_depth)
+}
+
+pub(super) fn compiled_object_complexity(
+    selection: &CompiledObject,
+    weights: &ManifestComplexityWeights,
+) -> u64 {
+    selection.members.iter().fold(0, |total, member| {
+        let cost = match member {
+            CompiledMember::Scalar(_) => weights.scalar,
+            CompiledMember::Branch(branch) => match branch.semantic {
+                CompiledBranchSemantic::Relationship => {
+                    let child = compiled_object_complexity(&branch.selection, weights);
+                    match branch
+                        .relationship
+                        .as_ref()
+                        .expect("relationship branches retain their compiled descriptor")
+                        .kind
+                    {
+                        ManifestRelationshipKind::BelongsTo => {
+                            weights.belongs_to.saturating_add(child)
+                        }
+                        ManifestRelationshipKind::HasMany => weights
+                            .has_many
+                            .saturating_add(weights.list_fanout.saturating_mul(child)),
+                        ManifestRelationshipKind::ManyToMany => weights
+                            .m2m
+                            .saturating_add(weights.list_fanout.saturating_mul(child)),
+                    }
+                }
+                CompiledBranchSemantic::Aggregate => weights
+                    .aggregate
+                    .saturating_add(compiled_object_complexity(&branch.selection, weights)),
+                CompiledBranchSemantic::AggregateFields => weights.scalar,
+                CompiledBranchSemantic::AggregateNodes => weights
+                    .list_fanout
+                    .saturating_mul(compiled_object_complexity(&branch.selection, weights))
+                    .max(weights.scalar),
+            },
+        };
+        total.saturating_add(cost)
+    })
+}
+
+pub(super) fn filter_depth_from_selection(selection_depth: usize, root_offset: usize) -> u64 {
+    u64::try_from(selection_depth.saturating_sub(root_offset))
+        .expect("compiler selection depth fits in u64")
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn validate_filter_source(
+    source: &CompiledArgument,
+    model: &ManifestModel,
+    input: &ManifestFilterInput,
+    expected_type: &str,
+    variables: &[CompiledVariable],
+    manifest: &ClientManifest,
+    execution: &ManifestExecutionLimits,
+    document: &ClientDocument,
+    position: Pos,
+    depth: u64,
+    constraints: &mut BTreeMap<String, VariableUseConstraint>,
+) -> Result<(), ClientCompileError> {
+    validate_filter_depth(model, execution, depth, document, position)?;
+    match source {
+        CompiledArgument::Literal { value, .. } => validate_filter_literal(
+            value, model, input, manifest, execution, document, position, depth,
+        ),
+        CompiledArgument::Variable(name) => {
+            validate_nested_variable(name, expected_type, variables, document, position)?;
+            constrain_variable(constraints, name, VariableUseConstraint::filter(depth));
+            Ok(())
+        }
+        CompiledArgument::List(_) => Err(source_error(
+            "client.filter.object_required",
+            format!("filter for model `{}` must be an object or null", model.id),
+            document,
+            position,
+        )),
+        CompiledArgument::Object(values) => {
+            for (name, value) in values {
+                match name.as_str() {
+                    "_and" | "_or" => match value {
+                        CompiledArgument::List(items) => {
+                            validate_filter_width(
+                                name,
+                                items.len(),
+                                execution.max_bool_width,
+                                document,
+                                position,
+                            )?;
+                            for item in items {
+                                if let CompiledArgument::Variable(variable) = item {
+                                    validate_nested_variable(
+                                        variable,
+                                        &format!("{}!", input.type_name),
+                                        variables,
+                                        document,
+                                        position,
+                                    )?;
+                                    constrain_variable(
+                                        constraints,
+                                        variable,
+                                        VariableUseConstraint::filter(depth.saturating_add(1)),
+                                    );
+                                } else {
+                                    validate_filter_source(
+                                        item,
+                                        model,
+                                        input,
+                                        &input.type_name,
+                                        variables,
+                                        manifest,
+                                        execution,
+                                        document,
+                                        position,
+                                        depth.saturating_add(1),
+                                        constraints,
+                                    )?;
+                                }
+                            }
+                        }
+                        CompiledArgument::Variable(variable) => {
+                            validate_nested_variable(
+                                variable,
+                                &format!("[{}!]", input.type_name),
+                                variables,
+                                document,
+                                position,
+                            )?;
+                            constrain_variable(
+                                constraints,
+                                variable,
+                                VariableUseConstraint::list(
+                                    execution.max_bool_width,
+                                    Some(VariableUseConstraint::filter(depth.saturating_add(1))),
+                                ),
+                            );
+                        }
+                        CompiledArgument::Literal { value, .. } => {
+                            validate_filter_literal(
+                                &json_singleton(name, value.clone()),
+                                model,
+                                input,
+                                manifest,
+                                execution,
+                                document,
+                                position,
+                                depth,
+                            )?;
+                        }
+                        CompiledArgument::Object(_) => {
+                            return Err(source_error(
+                                "client.filter.boolean_list",
+                                format!("filter operator `{name}` must contain a list of objects"),
+                                document,
+                                position,
+                            ));
+                        }
+                    },
+                    "_not" => validate_filter_source(
+                        value,
+                        model,
+                        input,
+                        &input.type_name,
+                        variables,
+                        manifest,
+                        execution,
+                        document,
+                        position,
+                        depth.saturating_add(1),
+                        constraints,
+                    )?,
+                    field_name => {
+                        if let Some(filter_field) =
+                            input.fields.iter().find(|field| field.name == field_name)
+                        {
+                            let field = model.field(field_name).ok_or_else(|| {
+                                ClientCompileError::manifest(
+                                    "client.manifest.filter_field",
+                                    format!(
+                                        "filter plan for model `{}` references absent field `{field_name}`",
+                                        model.id
+                                    ),
+                                )
+                            })?;
+                            validate_filter_comparison_source(
+                                value,
+                                model,
+                                field,
+                                filter_field,
+                                variables,
+                                execution,
+                                document,
+                                position,
+                                constraints,
+                            )?;
+                        } else if let Some(relationship_input) = input
+                            .relationships
+                            .iter()
+                            .find(|relationship| relationship.field == field_name)
+                        {
+                            let relationship = model.relationship(field_name).ok_or_else(|| {
+                                ClientCompileError::manifest(
+                                    "client.manifest.filter_relationship",
+                                    format!(
+                                        "filter plan for model `{}` references absent relationship `{field_name}`",
+                                        model.id
+                                    ),
+                                )
+                            })?;
+                            let target = manifest.models.get(&relationship.target_model).ok_or_else(|| {
+                                ClientCompileError::manifest(
+                                    "client.manifest.filter_relationship",
+                                    format!(
+                                        "filter relationship `{}.{field_name}` has an absent target",
+                                        model.id
+                                    ),
+                                )
+                            })?;
+                            validate_filter_source(
+                                value,
+                                target,
+                                &target.filter_input,
+                                &relationship_input.target_type,
+                                variables,
+                                manifest,
+                                execution,
+                                document,
+                                position,
+                                depth.saturating_add(1),
+                                constraints,
+                            )?;
+                        } else {
+                            return Err(source_error(
+                                "client.filter.field_denied_or_unknown",
+                                format!(
+                                    "filter field `{field_name}` is absent from selected model `{}`",
+                                    model.id
+                                ),
+                                document,
+                                position,
+                            ));
+                        }
+                    }
+                }
+            }
+            Ok(())
+        }
+    }
+}
+
+pub(super) fn validate_filter_depth(
+    model: &ManifestModel,
+    execution: &ManifestExecutionLimits,
+    depth: u64,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    if depth > MAX_OBJECT_DEPTH as u64 {
+        return Err(source_error(
+            "client.filter.safety_depth",
+            format!(
+                "filter for model `{}` exceeds the compiler safety depth {MAX_OBJECT_DEPTH}",
+                model.id
+            ),
+            document,
+            position,
+        ));
+    }
+    if depth > execution.max_depth {
+        return Err(source_error(
+            "client.filter.depth_limit",
+            format!(
+                "filter for model `{}` reaches semantic depth {depth}, exceeding max_depth {}",
+                model.id, execution.max_depth
+            ),
+            document,
+            position,
+        ));
+    }
+    Ok(())
+}
+
+pub(super) fn validate_filter_width(
+    operator: &str,
+    actual: usize,
+    maximum: u64,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    let actual = u64::try_from(actual).unwrap_or(u64::MAX);
+    if actual <= maximum {
+        return Ok(());
+    }
+    Err(source_error(
+        "client.filter.width_limit",
+        format!(
+            "filter operator `{operator}` contains {actual} items, exceeding its limit {maximum}"
+        ),
+        document,
+        position,
+    ))
+}
+
+pub(super) fn constrain_variable(
+    constraints: &mut BTreeMap<String, VariableUseConstraint>,
+    name: &str,
+    constraint: VariableUseConstraint,
+) {
+    constraints
+        .entry(name.to_string())
+        .and_modify(|existing| existing.intersect(&constraint))
+        .or_insert(constraint);
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn validate_filter_comparison_source(
+    source: &CompiledArgument,
+    model: &ManifestModel,
+    field: &ManifestField,
+    semantics: &ManifestFilterField,
+    variables: &[CompiledVariable],
+    execution: &ManifestExecutionLimits,
+    document: &ClientDocument,
+    position: Pos,
+    constraints: &mut BTreeMap<String, VariableUseConstraint>,
+) -> Result<(), ClientCompileError> {
+    if let CompiledArgument::Literal { value, .. } = source {
+        let operators = value.as_object().ok_or_else(|| {
+            source_error(
+                "client.filter.comparison_object",
+                format!(
+                    "filter field `{}.{}` must contain a comparison object",
+                    model.id, field.name
+                ),
+                document,
+                position,
+            )
+        })?;
+        for (operator, operand) in operators {
+            if !semantics
+                .operators
+                .iter()
+                .any(|allowed| allowed == operator)
+            {
+                return Err(source_error(
+                    "client.filter.operator_denied_or_unknown",
+                    format!(
+                        "filter operator `{operator}` is absent from selected field `{}.{}`",
+                        model.id, field.name
+                    ),
+                    document,
+                    position,
+                ));
+            }
+            match operator.as_str() {
+                "_in" | "_nin" => {
+                    let items = operand.as_array().ok_or_else(|| {
+                        source_error(
+                            "client.filter.list_required",
+                            format!("filter operator `{operator}` requires a list"),
+                            document,
+                            position,
+                        )
+                    })?;
+                    validate_filter_width(
+                        operator,
+                        items.len(),
+                        execution.max_in_list,
+                        document,
+                        position,
+                    )?;
+                    for item in items {
+                        validate_filter_scalar_literal(
+                            item, model, field, false, document, position,
+                        )?;
+                    }
+                }
+                "_is_null" if !operand.is_boolean() && !operand.is_null() => {
+                    return Err(source_error(
+                        "client.filter.boolean_required",
+                        "filter operator `_is_null` requires a boolean or null",
+                        document,
+                        position,
+                    ));
+                }
+                "_is_null" => {}
+                "_has_key" => validate_filter_typed_literal(
+                    operand, model, field, "String", "string", true, document, position,
+                )?,
+                _ => {
+                    validate_filter_scalar_literal(operand, model, field, true, document, position)?
+                }
+            }
+        }
+        return Ok(());
+    }
+    let CompiledArgument::Object(operators) = source else {
+        return Err(source_error(
+            "client.filter.comparison_object",
+            format!(
+                "filter field `{}.{}` must contain a comparison object",
+                model.id, field.name
+            ),
+            document,
+            position,
+        ));
+    };
+    for (operator, operand) in operators {
+        if !semantics
+            .operators
+            .iter()
+            .any(|allowed| allowed == operator)
+        {
+            return Err(source_error(
+                "client.filter.operator_denied_or_unknown",
+                format!(
+                    "filter operator `{operator}` is absent from selected field `{}.{}`",
+                    model.id, field.name
+                ),
+                document,
+                position,
+            ));
+        }
+        match (operator.as_str(), operand) {
+            ("_in" | "_nin", CompiledArgument::Variable(variable)) => {
+                validate_nested_variable(
+                    variable,
+                    &format!("[{}!]", field.scalar),
+                    variables,
+                    document,
+                    position,
+                )?;
+                constrain_variable(
+                    constraints,
+                    variable,
+                    VariableUseConstraint::list(execution.max_in_list, None),
+                );
+            }
+            ("_in" | "_nin", CompiledArgument::List(items)) => {
+                validate_filter_width(
+                    operator,
+                    items.len(),
+                    execution.max_in_list,
+                    document,
+                    position,
+                )?;
+                for item in items {
+                    match item {
+                        CompiledArgument::Variable(variable) => validate_nested_variable(
+                            variable,
+                            &format!("{}!", field.scalar),
+                            variables,
+                            document,
+                            position,
+                        )?,
+                        item => validate_compiled_filter_literal(
+                            item, model, field, false, document, position,
+                        )?,
+                    }
+                }
+            }
+            (
+                "_in" | "_nin",
+                CompiledArgument::Literal {
+                    value: JsonValue::Array(items),
+                    ..
+                },
+            ) => {
+                validate_filter_width(
+                    operator,
+                    items.len(),
+                    execution.max_in_list,
+                    document,
+                    position,
+                )?;
+                for item in items {
+                    validate_filter_scalar_literal(item, model, field, false, document, position)?;
+                }
+            }
+            ("_in" | "_nin", _) => {
+                return Err(source_error(
+                    "client.filter.list_required",
+                    format!("filter operator `{operator}` requires a list"),
+                    document,
+                    position,
+                ));
+            }
+            ("_is_null", CompiledArgument::Variable(variable)) => {
+                validate_nested_variable(variable, "Boolean", variables, document, position)?;
+            }
+            (
+                "_is_null",
+                CompiledArgument::Literal {
+                    value: JsonValue::Bool(_) | JsonValue::Null,
+                    ..
+                },
+            ) => {}
+            ("_is_null", _) => {
+                return Err(source_error(
+                    "client.filter.boolean_required",
+                    "filter operator `_is_null` requires a boolean or null",
+                    document,
+                    position,
+                ));
+            }
+            ("_has_key", CompiledArgument::Variable(variable)) => {
+                validate_nested_variable(variable, "String", variables, document, position)?;
+            }
+            ("_has_key", operand) => validate_compiled_filter_typed_literal(
+                operand, model, field, "String", "string", true, document, position,
+            )?,
+            (_, CompiledArgument::Variable(variable)) => {
+                validate_nested_variable(variable, &field.scalar, variables, document, position)?;
+            }
+            (_, operand) => {
+                validate_compiled_filter_literal(operand, model, field, true, document, position)?
+            }
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn validate_compiled_filter_literal(
+    source: &CompiledArgument,
+    model: &ManifestModel,
+    field: &ManifestField,
+    nullable: bool,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    validate_compiled_filter_typed_literal(
+        source,
+        model,
+        field,
+        &field.scalar,
+        &field.codec,
+        nullable,
+        document,
+        position,
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn validate_compiled_filter_typed_literal(
+    source: &CompiledArgument,
+    model: &ManifestModel,
+    field: &ManifestField,
+    scalar: &str,
+    codec: &str,
+    nullable: bool,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    let Some(value) = compiled_literal_json(source) else {
+        return Err(source_error(
+            "client.filter.operand",
+            format!(
+                "filter operand on `{}.{}` cannot contain a nested variable",
+                model.id, field.name
+            ),
+            document,
+            position,
+        ));
+    };
+    validate_filter_typed_literal(
+        &value, model, field, scalar, codec, nullable, document, position,
+    )
+}
+
+pub(super) fn compiled_literal_json(source: &CompiledArgument) -> Option<JsonValue> {
+    match source {
+        CompiledArgument::Literal { value, .. } => Some(value.clone()),
+        CompiledArgument::Variable(_) => None,
+        CompiledArgument::List(items) => items
+            .iter()
+            .map(compiled_literal_json)
+            .collect::<Option<Vec<_>>>()
+            .map(JsonValue::Array),
+        CompiledArgument::Object(fields) => fields
+            .iter()
+            .map(|(name, value)| Some((name.clone(), compiled_literal_json(value)?)))
+            .collect::<Option<JsonMap<String, JsonValue>>>()
+            .map(JsonValue::Object),
+    }
+}
+
+pub(super) fn validate_filter_scalar_literal(
+    value: &JsonValue,
+    model: &ManifestModel,
+    field: &ManifestField,
+    nullable: bool,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    validate_filter_typed_literal(
+        value,
+        model,
+        field,
+        &field.scalar,
+        &field.codec,
+        nullable,
+        document,
+        position,
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn validate_filter_typed_literal(
+    value: &JsonValue,
+    model: &ManifestModel,
+    field: &ManifestField,
+    scalar: &str,
+    codec: &str,
+    nullable: bool,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    if scalar_json_literal_matches(value, scalar, codec, nullable) {
+        return Ok(());
+    }
+    Err(source_error(
+        "client.filter.literal_type",
+        format!(
+            "filter literal for `{}.{}` does not match scalar `{}` / codec `{}`{}",
+            model.id,
+            field.name,
+            scalar,
+            codec,
+            if nullable { " or null" } else { "" }
+        ),
+        document,
+        position,
+    ))
+}
+
+pub(super) fn scalar_json_literal_matches(
+    value: &JsonValue,
+    scalar: &str,
+    codec: &str,
+    nullable: bool,
+) -> bool {
+    match (scalar, codec, value) {
+        (_, _, JsonValue::Null) => nullable,
+        ("ID" | "String", "string", JsonValue::String(_))
+        | ("Timestamptz", "string_unvalidated_timestamp", JsonValue::String(_))
+        | ("Boolean", "boolean", JsonValue::Bool(_)) => true,
+        ("Bytea", "base64", JsonValue::String(value)) => canonical_standard_base64(value).is_some(),
+        ("Int", "int32", JsonValue::Number(number)) => {
+            number
+                .as_i64()
+                .is_some_and(|number| i32::try_from(number).is_ok())
+                || number
+                    .as_u64()
+                    .is_some_and(|number| i32::try_from(number).is_ok())
+        }
+        ("Float", "float64", JsonValue::Number(number)) => {
+            number.as_f64().is_some_and(f64::is_finite)
+        }
+        ("BigInt", "json_number_precision_limited", JsonValue::Number(number)) => {
+            json_number_is_safe_integer(number)
+        }
+        ("JSON", "json", value) => json_value_roundtrips_javascript(value),
+        _ => false,
+    }
+}
+
+pub(super) fn json_value_roundtrips_javascript(value: &JsonValue) -> bool {
+    match value {
+        JsonValue::Number(number) => json_number_roundtrips_javascript(number),
+        JsonValue::Array(values) => values.iter().all(json_value_roundtrips_javascript),
+        JsonValue::Object(values) => values.values().all(json_value_roundtrips_javascript),
+        JsonValue::Null | JsonValue::Bool(_) | JsonValue::String(_) => true,
+    }
+}
+
+pub(super) fn json_number_roundtrips_javascript(number: &serde_json::Number) -> bool {
+    let Some(value) = number.as_f64().filter(|value| value.is_finite()) else {
+        return false;
+    };
+    value.fract() != 0.0 || value.abs() <= 9_007_199_254_740_991.0
+}
+
+pub(super) fn json_number_is_safe_integer(number: &serde_json::Number) -> bool {
+    const JS_MAX_SAFE_INTEGER: u64 = 9_007_199_254_740_991;
+    json_number_is_negative_zero(number)
+        || number
+            .as_i64()
+            .is_some_and(|number| number.unsigned_abs() <= JS_MAX_SAFE_INTEGER)
+        || number
+            .as_u64()
+            .is_some_and(|number| number <= JS_MAX_SAFE_INTEGER)
+}
+
+pub(super) fn json_number_is_negative_zero(number: &serde_json::Number) -> bool {
+    number
+        .as_f64()
+        .is_some_and(|number| number == 0.0 && number.is_sign_negative())
+}
+
+pub(super) fn canonical_standard_base64(value: &str) -> Option<String> {
+    base64::engine::general_purpose::STANDARD
+        .decode(value.as_bytes())
+        .ok()
+        .map(|bytes| base64::engine::general_purpose::STANDARD.encode(bytes))
+}
+
+pub(super) fn validate_nested_variable(
+    name: &str,
+    expected: &str,
+    variables: &[CompiledVariable],
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    let variable = variables
+        .iter()
+        .find(|variable| variable.name == name)
+        .expect("nested variable existence checked while compiling arguments");
+    let expected_type = Type::new(expected).ok_or_else(|| {
+        ClientCompileError::manifest(
+            "client.manifest.argument_type",
+            format!("invalid nested variable target type `{expected}`"),
+        )
+    })?;
+    if variable_type_compatible(&variable.graphql_type, &expected_type) {
+        return Ok(());
+    }
+    Err(source_error(
+        "client.variable.type_mismatch",
+        format!(
+            "nested variable `${name}` has type `{}`; selected filter/order position requires `{expected}`",
+            variable.graphql_type
+        ),
+        document,
+        position,
+    ))
+}
+
+pub(super) fn json_singleton(name: &str, value: JsonValue) -> JsonValue {
+    let mut object = JsonMap::new();
+    object.insert(name.to_string(), value);
+    JsonValue::Object(object)
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn validate_filter_literal(
+    value: &JsonValue,
+    model: &ManifestModel,
+    input: &ManifestFilterInput,
+    manifest: &ClientManifest,
+    execution: &ManifestExecutionLimits,
+    document: &ClientDocument,
+    position: Pos,
+    depth: u64,
+) -> Result<(), ClientCompileError> {
+    validate_filter_depth(model, execution, depth, document, position)?;
+    if value.is_null() {
+        return Ok(());
+    }
+    let object = value.as_object().ok_or_else(|| {
+        source_error(
+            "client.filter.object_required",
+            format!("filter for model `{}` must be an object or null", model.id),
+            document,
+            position,
+        )
+    })?;
+    for (name, value) in object {
+        match name.as_str() {
+            "_and" | "_or" => {
+                if value.is_null() {
+                    continue;
+                }
+                let items = value.as_array().ok_or_else(|| {
+                    source_error(
+                        "client.filter.boolean_list",
+                        format!("filter operator `{name}` must contain a list of objects"),
+                        document,
+                        position,
+                    )
+                })?;
+                validate_filter_width(
+                    name,
+                    items.len(),
+                    execution.max_bool_width,
+                    document,
+                    position,
+                )?;
+                for item in items {
+                    validate_filter_literal(
+                        item,
+                        model,
+                        input,
+                        manifest,
+                        execution,
+                        document,
+                        position,
+                        depth.saturating_add(1),
+                    )?;
+                }
+            }
+            "_not" => validate_filter_literal(
+                value,
+                model,
+                input,
+                manifest,
+                execution,
+                document,
+                position,
+                depth.saturating_add(1),
+            )?,
+            field_name => {
+                if let Some(field) = input.fields.iter().find(|field| field.name == field_name) {
+                    let operators = value.as_object().ok_or_else(|| {
+                        source_error(
+                            "client.filter.comparison_object",
+                            format!(
+                                "filter field `{}.{field_name}` must contain a comparison object",
+                                model.id
+                            ),
+                            document,
+                            position,
+                        )
+                    })?;
+                    for (operator, operand) in operators {
+                        if !field.operators.iter().any(|allowed| allowed == operator) {
+                            return Err(source_error(
+                                "client.filter.operator_denied_or_unknown",
+                                format!(
+                                    "filter operator `{operator}` is absent from selected field `{}.{field_name}`",
+                                    model.id
+                                ),
+                                document,
+                                position,
+                            ));
+                        }
+                        let model_field = model.field(field_name).ok_or_else(|| {
+                            ClientCompileError::manifest(
+                                "client.manifest.filter_field",
+                                format!(
+                                    "filter plan for model `{}` references absent field `{field_name}`",
+                                    model.id
+                                ),
+                            )
+                        })?;
+                        match operator.as_str() {
+                            "_in" | "_nin" => {
+                                let items = operand.as_array().ok_or_else(|| {
+                                    source_error(
+                                        "client.filter.list_required",
+                                        format!("filter operator `{operator}` requires a list"),
+                                        document,
+                                        position,
+                                    )
+                                })?;
+                                validate_filter_width(
+                                    operator,
+                                    items.len(),
+                                    execution.max_in_list,
+                                    document,
+                                    position,
+                                )?;
+                                for item in items {
+                                    validate_filter_scalar_literal(
+                                        item,
+                                        model,
+                                        model_field,
+                                        false,
+                                        document,
+                                        position,
+                                    )?;
+                                }
+                            }
+                            "_is_null" if !operand.is_boolean() && !operand.is_null() => {
+                                return Err(source_error(
+                                    "client.filter.boolean_required",
+                                    "filter operator `_is_null` requires a boolean or null",
+                                    document,
+                                    position,
+                                ));
+                            }
+                            "_is_null" => {}
+                            _ => validate_filter_scalar_literal(
+                                operand,
+                                model,
+                                model_field,
+                                true,
+                                document,
+                                position,
+                            )?,
+                        }
+                    }
+                } else if let Some(relationship_input) = input
+                    .relationships
+                    .iter()
+                    .find(|relationship| relationship.field == field_name)
+                {
+                    let relationship = model.relationship(field_name).ok_or_else(|| {
+                        ClientCompileError::manifest(
+                            "client.manifest.filter_relationship",
+                            format!(
+                                "filter plan for model `{}` references absent relationship `{field_name}`",
+                                model.id
+                            ),
+                        )
+                    })?;
+                    let target =
+                        manifest
+                            .models
+                            .get(&relationship.target_model)
+                            .ok_or_else(|| {
+                                ClientCompileError::manifest(
+                                    "client.manifest.filter_relationship",
+                                    format!(
+                                "filter relationship `{}.{field_name}` has an absent target",
+                                model.id
+                            ),
+                                )
+                            })?;
+                    if relationship_input.target_type != target.filter_input.type_name {
+                        return Err(ClientCompileError::manifest(
+                            "client.manifest.filter_relationship",
+                            format!(
+                                "filter relationship `{}.{field_name}` targets input `{}` but model `{}` declares `{}`",
+                                model.id,
+                                relationship_input.target_type,
+                                target.id,
+                                target.filter_input.type_name
+                            ),
+                        ));
+                    }
+                    validate_filter_literal(
+                        value,
+                        target,
+                        &target.filter_input,
+                        manifest,
+                        execution,
+                        document,
+                        position,
+                        depth.saturating_add(1),
+                    )?;
+                } else {
+                    return Err(source_error(
+                        "client.filter.field_denied_or_unknown",
+                        format!(
+                            "filter field `{field_name}` is absent from selected model `{}`",
+                            model.id
+                        ),
+                        document,
+                        position,
+                    ));
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn validate_order_literal(
+    value: &JsonValue,
+    semantics: &ManifestOrderSemantics,
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    if value.is_null() {
+        return Ok(());
+    }
+    let entries = value.as_array().ok_or_else(|| {
+        source_error(
+            "client.order.list_required",
+            "order_by must be a list or null",
+            document,
+            position,
+        )
+    })?;
+    for entry in entries {
+        let object = entry.as_object().ok_or_else(|| {
+            source_error(
+                "client.order.object_required",
+                "each order_by entry must be an object",
+                document,
+                position,
+            )
+        })?;
+        if object.len() != 1 {
+            return Err(source_error(
+                "client.order.ambiguous",
+                "each order_by entry must contain exactly one field to declare priority",
+                document,
+                position,
+            ));
+        }
+        let (field, direction) = object.iter().next().expect("length checked");
+        if !semantics.fields.iter().any(|allowed| allowed == field) {
+            return Err(source_error(
+                "client.order.field_denied_or_unknown",
+                format!("order_by field `{field}` is absent from the selected model"),
+                document,
+                position,
+            ));
+        }
+        let direction = direction.as_str().ok_or_else(|| {
+            source_error(
+                "client.order.direction",
+                format!("order_by field `{field}` must use a declared direction enum"),
+                document,
+                position,
+            )
+        })?;
+        if !semantics.values.iter().any(|allowed| allowed == direction) {
+            return Err(source_error(
+                "client.order.direction",
+                format!("order_by direction `{direction}` is absent from the selected manifest"),
+                document,
+                position,
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn validate_order_source(
+    source: &CompiledArgument,
+    semantics: &ManifestOrderSemantics,
+    argument: Option<&ManifestArgument>,
+    variables: &[CompiledVariable],
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    match source {
+        CompiledArgument::Literal { value, .. } => {
+            validate_order_literal(value, semantics, document, position)
+        }
+        CompiledArgument::Variable(name) => {
+            let expected = argument
+                .map(ManifestArgument::graphql_type)
+                .ok_or_else(|| {
+                    ClientCompileError::manifest(
+                        "client.manifest.order_argument",
+                        "order semantics exist without an order argument",
+                    )
+                })?;
+            validate_nested_variable(name, &expected, variables, document, position)
+        }
+        CompiledArgument::List(entries) => {
+            for entry in entries {
+                match entry {
+                    CompiledArgument::Variable(name) => {
+                        let item_type = argument
+                            .map(|argument| argument.type_name.as_str())
+                            .ok_or_else(|| {
+                                ClientCompileError::manifest(
+                                    "client.manifest.order_argument",
+                                    "order semantics exist without an order argument",
+                                )
+                            })?;
+                        validate_nested_variable(
+                            name,
+                            &format!("{item_type}!"),
+                            variables,
+                            document,
+                            position,
+                        )?;
+                    }
+                    CompiledArgument::Object(fields) => validate_order_entry_source(
+                        fields, semantics, variables, document, position,
+                    )?,
+                    CompiledArgument::Literal { value, .. } => {
+                        validate_order_literal(
+                            &JsonValue::Array(vec![value.clone()]),
+                            semantics,
+                            document,
+                            position,
+                        )?;
+                    }
+                    CompiledArgument::List(_) => {
+                        return Err(source_error(
+                            "client.order.object_required",
+                            "each order_by entry must be an object",
+                            document,
+                            position,
+                        ));
+                    }
+                }
+            }
+            Ok(())
+        }
+        CompiledArgument::Object(_) => Err(source_error(
+            "client.order.list_required",
+            "order_by must be a list or null",
+            document,
+            position,
+        )),
+    }
+}
+
+pub(super) fn validate_order_entry_source(
+    fields: &BTreeMap<String, CompiledArgument>,
+    semantics: &ManifestOrderSemantics,
+    variables: &[CompiledVariable],
+    document: &ClientDocument,
+    position: Pos,
+) -> Result<(), ClientCompileError> {
+    if fields.len() != 1 {
+        return Err(source_error(
+            "client.order.ambiguous",
+            "each order_by entry must contain exactly one field to declare priority",
+            document,
+            position,
+        ));
+    }
+    let (field, direction) = fields.iter().next().expect("length checked");
+    if !semantics.fields.iter().any(|allowed| allowed == field) {
+        return Err(source_error(
+            "client.order.field_denied_or_unknown",
+            format!("order_by field `{field}` is absent from the selected model"),
+            document,
+            position,
+        ));
+    }
+    match direction {
+        CompiledArgument::Variable(name) => {
+            validate_nested_variable(name, "order_by", variables, document, position)
+        }
+        CompiledArgument::Literal { value, .. } => {
+            let direction = value.as_str().ok_or_else(|| {
+                source_error(
+                    "client.order.direction",
+                    format!("order_by field `{field}` must use a declared direction enum"),
+                    document,
+                    position,
+                )
+            })?;
+            if semantics.values.iter().any(|allowed| allowed == direction) {
+                Ok(())
+            } else {
+                Err(source_error(
+                    "client.order.direction",
+                    format!(
+                        "order_by direction `{direction}` is absent from the selected manifest"
+                    ),
+                    document,
+                    position,
+                ))
+            }
+        }
+        CompiledArgument::List(_) | CompiledArgument::Object(_) => Err(source_error(
+            "client.order.direction",
+            format!("order_by field `{field}` must use a declared direction enum"),
+            document,
+            position,
+        )),
+    }
+}
diff --git a/distributed_cli/src/client_compiler/graphql/variables.rs b/distributed_cli/src/client_compiler/graphql/variables.rs
new file mode 100644
index 00000000..a04fd95a
--- /dev/null
+++ b/distributed_cli/src/client_compiler/graphql/variables.rs
@@ -0,0 +1,501 @@
+use super::*;
+
+pub(super) fn compile_variables(
+    operation: &OperationDefinition,
+    document: &ClientDocument,
+) -> Result<Vec<CompiledVariable>, ClientCompileError> {
+    if operation.variable_definitions.len() > MAX_VARIABLES {
+        return Err(source_error(
+            "client.variables.bound",
+            format!("operation exceeds the supported {MAX_VARIABLES}-variable bound"),
+            document,
+            operation.selection_set.pos,
+        ));
+    }
+    let mut variables = Vec::with_capacity(operation.variable_definitions.len());
+    let mut seen = BTreeSet::new();
+    for variable in &operation.variable_definitions {
+        let definition = &variable.node;
+        let name = definition.name.node.as_str();
+        if !seen.insert(name) {
+            return Err(source_error(
+                "client.variable.duplicate",
+                format!("variable `${name}` is defined more than once"),
+                document,
+                definition.name.pos,
+            ));
+        }
+        reject_directives(&definition.directives, "variable definition", document)?;
+        if definition.default_value.is_some() {
+            return Err(source_error(
+                "client.variable.default_unsupported",
+                format!(
+                    "variable `${name}` declares a default; pass the effective root argument explicitly so cache identity cannot diverge from server coercion"
+                ),
+                document,
+                definition.name.pos,
+            ));
+        }
+        variables.push(CompiledVariable {
+            name: name.to_string(),
+            graphql_type: definition.var_type.node.clone(),
+        });
+    }
+    variables.sort_by(|left, right| left.name.cmp(&right.name));
+    Ok(variables)
+}
+
+#[derive(Clone, Copy)]
+pub(super) struct FilterInputCandidate<'a> {
+    model: &'a ManifestModel,
+    semantics: &'a ManifestFilterInput,
+}
+
+#[derive(Clone, Copy)]
+pub(super) struct OrderInputCandidate<'a> {
+    model: &'a ManifestModel,
+    semantics: &'a ManifestOrderSemantics,
+}
+
+pub(super) fn compile_variable_codec(
+    variables: &[CompiledVariable],
+    manifest: &ClientManifest,
+    constraints: &BTreeMap<String, VariableUseConstraint>,
+) -> Result<CompiledVariableCodec, ClientCompileError> {
+    let mut filters = BTreeMap::<String, FilterInputCandidate<'_>>::new();
+    let mut orders = BTreeMap::<String, OrderInputCandidate<'_>>::new();
+
+    for model in manifest.models.values() {
+        register_filter_input(
+            &model.filter_input.type_name,
+            model,
+            &model.filter_input,
+            &mut filters,
+        )?;
+    }
+
+    for root in manifest.roots.values() {
+        let model = manifest.models.get(&root.model).ok_or_else(|| {
+            ClientCompileError::manifest(
+                "client.manifest.root_model",
+                format!(
+                    "root `{}` references absent model `{}`",
+                    root.name, root.model
+                ),
+            )
+        })?;
+        register_order_input_candidate(&root.arguments, root.order.as_ref(), model, &mut orders)?;
+    }
+
+    for source in manifest.models.values() {
+        for relationship in &source.relationships {
+            let target = manifest
+                .models
+                .get(&relationship.target_model)
+                .ok_or_else(|| {
+                    ClientCompileError::manifest(
+                        "client.manifest.relationship_target",
+                        format!(
+                            "relationship `{}.{}` references absent model `{}`",
+                            source.id, relationship.name, relationship.target_model
+                        ),
+                    )
+                })?;
+            register_order_input_candidate(
+                &relationship.arguments,
+                relationship.order.as_ref(),
+                target,
+                &mut orders,
+            )?;
+            if let Some(aggregate) = &relationship.aggregate {
+                register_order_input_candidate(
+                    &aggregate.arguments,
+                    relationship.order.as_ref(),
+                    target,
+                    &mut orders,
+                )?;
+            }
+        }
+    }
+
+    if let Some(name) = filters.keys().find(|name| orders.contains_key(*name)) {
+        return Err(ClientCompileError::manifest(
+            "client.variable.input_type_conflict",
+            format!(
+                "selected manifest uses input type `{name}` for both filter and order contracts"
+            ),
+        ));
+    }
+
+    let order_values = orders
+        .values()
+        .next()
+        .map(|candidate| candidate.semantics.values.clone())
+        .unwrap_or_default();
+    if orders
+        .values()
+        .any(|candidate| candidate.semantics.values != order_values)
+    {
+        return Err(ClientCompileError::manifest(
+            "client.variable.order_enum_conflict",
+            "selected order input contracts disagree on the direction enum",
+        ));
+    }
+
+    let mut inputs = BTreeMap::new();
+    let mut visiting = BTreeSet::new();
+    let mut compiled_variables = BTreeMap::new();
+    for variable in variables {
+        let input_type = compile_variable_input_type(
+            &variable.graphql_type,
+            manifest,
+            &filters,
+            &orders,
+            &order_values,
+            &mut inputs,
+            &mut visiting,
+            constraints.get(&variable.name),
+        )?;
+        compiled_variables.insert(variable.name.clone(), input_type);
+    }
+    Ok(CompiledVariableCodec {
+        version: 1,
+        limits: CompiledVariableCodecLimits {
+            max_depth: manifest.execution.max_depth,
+            max_bool_width: manifest.execution.max_bool_width,
+            max_in_list: manifest.execution.max_in_list,
+        },
+        variables: compiled_variables,
+        inputs,
+    })
+}
+
+pub(super) fn operation_variable_constraints(
+    root: &CompiledRoot,
+) -> BTreeMap<String, VariableUseConstraint> {
+    let mut constraints = BTreeMap::new();
+    merge_filter_constraints(root.filter.as_ref(), &mut constraints);
+    merge_object_variable_constraints(&root.selection, &mut constraints);
+    constraints
+}
+
+pub(super) fn merge_object_variable_constraints(
+    object: &CompiledObject,
+    constraints: &mut BTreeMap<String, VariableUseConstraint>,
+) {
+    for member in &object.members {
+        let CompiledMember::Branch(branch) = member else {
+            continue;
+        };
+        merge_filter_constraints(branch.filter.as_ref(), constraints);
+        merge_object_variable_constraints(&branch.selection, constraints);
+    }
+}
+
+pub(super) fn merge_filter_constraints(
+    filter: Option<&CompiledFilterPlan>,
+    constraints: &mut BTreeMap<String, VariableUseConstraint>,
+) {
+    let Some(filter) = filter else {
+        return;
+    };
+    for (name, constraint) in &filter.variable_constraints {
+        constraints
+            .entry(name.clone())
+            .and_modify(|existing| existing.intersect(constraint))
+            .or_insert_with(|| constraint.clone());
+    }
+}
+
+pub(super) fn register_order_input_candidate<'a>(
+    arguments: &[ManifestArgument],
+    order: Option<&'a ManifestOrderSemantics>,
+    model: &'a ManifestModel,
+    orders: &mut BTreeMap<String, OrderInputCandidate<'a>>,
+) -> Result<(), ClientCompileError> {
+    if let Some(semantics) = order {
+        if let Some(argument) = arguments
+            .iter()
+            .find(|argument| argument.kind == ManifestArgumentKind::Order)
+        {
+            register_order_input(&argument.type_name, model, semantics, orders)?;
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn register_filter_input<'a>(
+    name: &str,
+    model: &'a ManifestModel,
+    semantics: &'a ManifestFilterInput,
+    candidates: &mut BTreeMap<String, FilterInputCandidate<'a>>,
+) -> Result<(), ClientCompileError> {
+    if let Some(existing) = candidates.get(name) {
+        if existing.model.id != model.id || existing.semantics != semantics {
+            return Err(ClientCompileError::manifest(
+                "client.variable.input_type_conflict",
+                format!("filter input type `{name}` has multiple selected structural contracts"),
+            ));
+        }
+        return Ok(());
+    }
+    candidates.insert(name.to_string(), FilterInputCandidate { model, semantics });
+    Ok(())
+}
+
+pub(super) fn register_order_input<'a>(
+    name: &str,
+    model: &'a ManifestModel,
+    semantics: &'a ManifestOrderSemantics,
+    candidates: &mut BTreeMap<String, OrderInputCandidate<'a>>,
+) -> Result<(), ClientCompileError> {
+    if let Some(existing) = candidates.get(name) {
+        if existing.model.id != model.id || existing.semantics != semantics {
+            return Err(ClientCompileError::manifest(
+                "client.variable.input_type_conflict",
+                format!("order input type `{name}` has multiple selected structural contracts"),
+            ));
+        }
+        return Ok(());
+    }
+    candidates.insert(name.to_string(), OrderInputCandidate { model, semantics });
+    Ok(())
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn compile_variable_input_type(
+    graphql_type: &Type,
+    manifest: &ClientManifest,
+    filters: &BTreeMap<String, FilterInputCandidate<'_>>,
+    orders: &BTreeMap<String, OrderInputCandidate<'_>>,
+    order_values: &[String],
+    inputs: &mut BTreeMap<String, CompiledInputDefinition>,
+    visiting: &mut BTreeSet<String>,
+    constraint: Option<&VariableUseConstraint>,
+) -> Result<CompiledInputType, ClientCompileError> {
+    let nullable = graphql_type.nullable;
+    match &graphql_type.base {
+        BaseType::List(item) => {
+            if constraint.is_some_and(|constraint| constraint.filter_base_depth.is_some()) {
+                return Err(ClientCompileError::manifest(
+                    "client.variable.constraint_type",
+                    "filterBaseDepth cannot apply to a list variable",
+                ));
+            }
+            Ok(CompiledInputType::List {
+                nullable,
+                max_items: constraint.and_then(|constraint| constraint.max_items),
+                item: Box::new(compile_variable_input_type(
+                    item,
+                    manifest,
+                    filters,
+                    orders,
+                    order_values,
+                    inputs,
+                    visiting,
+                    constraint.and_then(|constraint| constraint.item.as_deref()),
+                )?),
+            })
+        }
+        BaseType::Named(name) => {
+            let name = name.as_str();
+            if let Some(codec) = manifest.scalar_codecs.get(name) {
+                require_leaf_constraint(name, constraint)?;
+                return Ok(CompiledInputType::Scalar {
+                    scalar: name.to_string(),
+                    codec: codec.clone(),
+                    nullable,
+                });
+            }
+            if filters.contains_key(name) {
+                if constraint.is_some_and(|constraint| {
+                    constraint.max_items.is_some() || constraint.item.is_some()
+                }) {
+                    return Err(ClientCompileError::manifest(
+                        "client.variable.constraint_type",
+                        format!("filter input `{name}` received list constraints"),
+                    ));
+                }
+                compile_filter_input_definition(name, filters, inputs, visiting)?;
+                return Ok(CompiledInputType::Input {
+                    name: name.to_string(),
+                    nullable,
+                    filter_base_depth: constraint
+                        .and_then(|constraint| constraint.filter_base_depth),
+                });
+            }
+            if orders.contains_key(name) {
+                require_leaf_constraint(name, constraint)?;
+                compile_order_input_definition(name, orders, inputs)?;
+                return Ok(CompiledInputType::Input {
+                    name: name.to_string(),
+                    nullable,
+                    filter_base_depth: None,
+                });
+            }
+            if name == "order_by" && !order_values.is_empty() {
+                require_leaf_constraint(name, constraint)?;
+                return Ok(CompiledInputType::Enum {
+                    name: name.to_string(),
+                    values: order_values.to_vec(),
+                    nullable,
+                });
+            }
+            Err(ClientCompileError::manifest(
+                "client.variable.input_type_unsupported",
+                format!(
+                    "variable input type `{name}` has no compiler-owned scalar, filter, order, or enum contract"
+                ),
+            ))
+        }
+    }
+}
+
+pub(super) fn require_leaf_constraint(
+    name: &str,
+    constraint: Option<&VariableUseConstraint>,
+) -> Result<(), ClientCompileError> {
+    if constraint.is_none_or(|constraint| {
+        constraint.filter_base_depth.is_none()
+            && constraint.max_items.is_none()
+            && constraint.item.is_none()
+    }) {
+        return Ok(());
+    }
+    Err(ClientCompileError::manifest(
+        "client.variable.constraint_type",
+        format!("variable type `{name}` received incompatible input constraints"),
+    ))
+}
+
+pub(super) fn compile_filter_input_definition(
+    name: &str,
+    candidates: &BTreeMap<String, FilterInputCandidate<'_>>,
+    inputs: &mut BTreeMap<String, CompiledInputDefinition>,
+    visiting: &mut BTreeSet<String>,
+) -> Result<(), ClientCompileError> {
+    if inputs.contains_key(name) || !visiting.insert(name.to_string()) {
+        return Ok(());
+    }
+    let candidate = *candidates.get(name).ok_or_else(|| {
+        ClientCompileError::manifest(
+            "client.variable.filter_input",
+            format!("filter input type `{name}` has no selected contract"),
+        )
+    })?;
+    let fields = candidate
+        .semantics
+        .fields
+        .iter()
+        .map(|semantics| {
+            let field = candidate.model.field(&semantics.name).ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.variable.filter_field",
+                    format!(
+                        "filter input `{name}` references absent field `{}.{}`",
+                        candidate.model.id, semantics.name
+                    ),
+                )
+            })?;
+            Ok(CompiledFilterInputField {
+                field: field.name.clone(),
+                scalar: field.scalar.clone(),
+                codec: field.codec.clone(),
+                nullable: field.nullable,
+                operators: semantics.operators.clone(),
+            })
+        })
+        .collect::<Result<Vec<_>, ClientCompileError>>()?;
+
+    let mut relationships = Vec::with_capacity(candidate.semantics.relationships.len());
+    for relationship_input in &candidate.semantics.relationships {
+        candidate
+            .model
+            .relationship(&relationship_input.field)
+            .ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.variable.filter_relationship",
+                    format!(
+                        "filter input `{name}` references absent relationship `{}.{}`",
+                        candidate.model.id, relationship_input.field
+                    ),
+                )
+            })?;
+        let target = candidates
+            .contains_key(&relationship_input.target_type)
+            .then(|| {
+                compile_filter_input_definition(
+                    &relationship_input.target_type,
+                    candidates,
+                    inputs,
+                    visiting,
+                )?;
+                Ok(CompiledFilterInputTarget::Input {
+                    name: relationship_input.target_type.clone(),
+                })
+            })
+            .transpose()?
+            .unwrap_or(CompiledFilterInputTarget::Opaque);
+        relationships.push(CompiledFilterInputRelationship {
+            field: relationship_input.field.clone(),
+            target,
+        });
+    }
+    inputs.insert(
+        name.to_string(),
+        CompiledInputDefinition::Filter {
+            model: candidate.model.id.clone(),
+            fields,
+            relationships,
+        },
+    );
+    visiting.remove(name);
+    Ok(())
+}
+
+pub(super) fn compile_order_input_definition(
+    name: &str,
+    candidates: &BTreeMap<String, OrderInputCandidate<'_>>,
+    inputs: &mut BTreeMap<String, CompiledInputDefinition>,
+) -> Result<(), ClientCompileError> {
+    if inputs.contains_key(name) {
+        return Ok(());
+    }
+    let candidate = *candidates.get(name).ok_or_else(|| {
+        ClientCompileError::manifest(
+            "client.variable.order_input",
+            format!("order input type `{name}` has no selected contract"),
+        )
+    })?;
+    let fields = candidate
+        .semantics
+        .fields
+        .iter()
+        .map(|field_name| {
+            let field = candidate.model.field(field_name).ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.variable.order_field",
+                    format!(
+                        "order input `{name}` references absent field `{}.{field_name}`",
+                        candidate.model.id
+                    ),
+                )
+            })?;
+            Ok(CompiledOrderInputField {
+                field: field.name.clone(),
+                scalar: field.scalar.clone(),
+                codec: field.codec.clone(),
+                nullable: field.nullable,
+            })
+        })
+        .collect::<Result<Vec<_>, ClientCompileError>>()?;
+    inputs.insert(
+        name.to_string(),
+        CompiledInputDefinition::Order {
+            model: candidate.model.id.clone(),
+            fields,
+            values: candidate.semantics.values.clone(),
+        },
+    );
+    Ok(())
+}
diff --git a/distributed_cli/src/client_compiler/manifest/commands.rs b/distributed_cli/src/client_compiler/manifest/commands.rs
new file mode 100644
index 00000000..582163dd
--- /dev/null
+++ b/distributed_cli/src/client_compiler/manifest/commands.rs
@@ -0,0 +1,119 @@
+use super::*;
+
+pub(crate) fn canonicalize_commands(
+    commands: &mut [ManifestCommand],
+) -> Result<(), ClientCompileError> {
+    for command in commands.iter_mut() {
+        canonicalize_string_set(
+            &mut command.grants,
+            &format!("command `{}` grant", command.name),
+        )?;
+        for descriptor in &command.extensions.trusted_presets {
+            validate_nonempty(&descriptor.name, "trusted preset name")?;
+            validate_nonempty(&descriptor.codec, "trusted preset codec")?;
+            if descriptor.name.len() > 128
+                || descriptor.name.trim() != descriptor.name
+                || descriptor.name.chars().any(char::is_control)
+            {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.trusted_preset_name",
+                    format!(
+                        "manifest command `{}` has an invalid trusted preset name",
+                        command.name
+                    ),
+                ));
+            }
+        }
+        command.extensions.trusted_presets.sort();
+        if command
+            .extensions
+            .trusted_presets
+            .windows(2)
+            .any(|pair| pair[0].name == pair[1].name)
+        {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.trusted_preset_inventory",
+                format!(
+                    "manifest command `{}` repeats a trusted preset descriptor",
+                    command.name
+                ),
+            ));
+        }
+        if let Some(defaults) = &mut command.extensions.input_defaults {
+            for default in &mut defaults.defaults {
+                validate_nonempty_strings(
+                    &default.path,
+                    &format!("command `{}` input default path", command.name),
+                )?;
+            }
+            defaults.defaults.sort();
+            if defaults
+                .defaults
+                .windows(2)
+                .any(|pair| pair[0].path == pair[1].path)
+            {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.input_default_path",
+                    format!(
+                        "manifest command `{}` repeats an input default path",
+                        command.name
+                    ),
+                ));
+            }
+        }
+        if let Some(direct) = &mut command.extensions.direct_projection {
+            if let Some(partition) = &mut direct.partition {
+                canonicalize_effect_expression(partition);
+            }
+        }
+        if let Some(effects) = &mut command.extensions.effects {
+            for effect in &mut effects.operations {
+                canonicalize_effect(effect);
+            }
+        }
+        if let Some(confirmations) = &mut command.extensions.confirmations {
+            for confirmation in &mut confirmations.expected {
+                canonicalize_effect_key(&mut confirmation.key);
+                if let Some(partition) = &mut confirmation.partition {
+                    canonicalize_effect_expression(partition);
+                }
+            }
+        }
+    }
+    commands.sort_by(|left, right| left.name.cmp(&right.name));
+    Ok(())
+}
+
+pub(crate) fn canonicalize_effect(effect: &mut ManifestEffect) {
+    match effect {
+        ManifestEffect::Upsert { key, fields, .. } | ManifestEffect::Patch { key, fields, .. } => {
+            canonicalize_effect_key(key);
+            for field in fields.iter_mut() {
+                canonicalize_effect_expression(&mut field.value);
+            }
+            fields.sort_by(|left, right| left.field.cmp(&right.field));
+        }
+        ManifestEffect::Delete { key, .. } => canonicalize_effect_key(key),
+        ManifestEffect::Link { source, target, .. }
+        | ManifestEffect::Unlink { source, target, .. } => {
+            canonicalize_effect_key(source);
+            canonicalize_effect_key(target);
+        }
+        ManifestEffect::InvalidateRelationship { source, .. } => {
+            canonicalize_effect_key(source);
+        }
+        ManifestEffect::InvalidateModel { .. } => {}
+    }
+}
+
+pub(crate) fn canonicalize_effect_key(key: &mut ManifestEffectKey) {
+    for field in &mut key.fields {
+        canonicalize_effect_expression(&mut field.value);
+    }
+}
+
+pub(crate) fn canonicalize_effect_expression(expression: &mut ManifestEffectExpression) {
+    if let ManifestEffectExpression::Constant { value } = expression {
+        *value = canonical_json_value(std::mem::take(value));
+    }
+}
diff --git a/distributed_cli/src/client_compiler/manifest/mod.rs b/distributed_cli/src/client_compiler/manifest/mod.rs
new file mode 100644
index 00000000..b22f675d
--- /dev/null
+++ b/distributed_cli/src/client_compiler/manifest/mod.rs
@@ -0,0 +1,25 @@
+mod commands;
+mod model_validation;
+mod parse;
+mod projectors;
+mod roots;
+mod types;
+mod util;
+
+pub(crate) use super::{is_graphql_name, ClientCompileError, ClientSurfaceSelector};
+pub(crate) use commands::*;
+pub(crate) use model_validation::*;
+pub(crate) use projectors::*;
+pub(crate) use roots::*;
+pub(crate) use util::{validate_hash, validate_nonempty};
+
+const MANIFEST_VERSION: u64 = 1;
+const PROTOCOL_VERSION: u64 = 1;
+const PROTOCOL_FINGERPRINT: &str =
+    "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273";
+
+pub(crate) use types::*;
+pub(crate) use util::{canonical_json_value, hash_bytes, validate_exact_operation_hash};
+
+#[cfg(test)]
+pub(crate) use parse::refresh_schema_fingerprint;
diff --git a/distributed_cli/src/client_compiler/manifest/model_validation.rs b/distributed_cli/src/client_compiler/manifest/model_validation.rs
new file mode 100644
index 00000000..6535e8f2
--- /dev/null
+++ b/distributed_cli/src/client_compiler/manifest/model_validation.rs
@@ -0,0 +1,1546 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use serde_json::Value as JsonValue;
+
+use super::*;
+
+pub(crate) fn validate_input_default_generators_in_json(
+    value: &JsonValue,
+) -> Result<(), ClientCompileError> {
+    let Some(commands) = value.get("commands").and_then(JsonValue::as_array) else {
+        return Ok(());
+    };
+    for (command_index, command) in commands.iter().enumerate() {
+        let command_name = command
+            .get("name")
+            .and_then(JsonValue::as_str)
+            .unwrap_or("<unknown>");
+        let Some(defaults) = command
+            .pointer("/extensions/input_defaults/defaults")
+            .and_then(JsonValue::as_array)
+        else {
+            continue;
+        };
+        for (default_index, default) in defaults.iter().enumerate() {
+            if !matches!(
+                default.get("generator").and_then(JsonValue::as_str),
+                Some("uuid_v7" | "ulid")
+            ) {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.input_default_generator",
+                    format!(
+                        "manifest command `{command_name}` input default {default_index} must use uuid_v7 or ulid (commands[{command_index}])"
+                    ),
+                ));
+            }
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn canonicalize_surface(
+    surface: &mut ManifestSurface,
+) -> Result<(), ClientCompileError> {
+    match surface {
+        ManifestSurface::Role { name } => {
+            validate_nonempty(name, "manifest.surface.name")?;
+        }
+        ManifestSurface::Application { name, roles } => {
+            validate_nonempty(name, "manifest.surface.name")?;
+            if roles.is_empty() {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.surface_roles",
+                    format!("application surface `{name}` must declare at least one role"),
+                ));
+            }
+            canonicalize_string_set(roles, &format!("application surface `{name}` role"))?;
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn canonicalize_string_set(
+    values: &mut [String],
+    label: &str,
+) -> Result<(), ClientCompileError> {
+    validate_nonempty_strings(values, label)?;
+    values.sort();
+    if values.windows(2).any(|pair| pair[0] == pair[1]) {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.duplicate_entry",
+            format!("{label} entries must be unique"),
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_nonempty_strings(
+    values: &[String],
+    label: &str,
+) -> Result<(), ClientCompileError> {
+    for value in values {
+        validate_nonempty(value, label)?;
+    }
+    Ok(())
+}
+
+pub(crate) fn require_dependency(
+    dependencies: &[String],
+    required: &str,
+    owner: &str,
+) -> Result<(), ClientCompileError> {
+    if dependencies.iter().any(|dependency| dependency == required) {
+        return Ok(());
+    }
+    Err(ClientCompileError::manifest(
+        "client.manifest.dependency",
+        format!("{owner} must include invalidation dependency `{required}`"),
+    ))
+}
+
+pub(crate) fn validate_graphql_name(value: &str, label: &str) -> Result<(), ClientCompileError> {
+    if !super::is_graphql_name(value) || value.starts_with("__") {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.graphql_name",
+            format!("{label} `{value}` must be a valid GraphQL name"),
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_surface(
+    actual: &ManifestSurface,
+    expected: &ClientSurfaceSelector,
+) -> Result<(), ClientCompileError> {
+    let matches = match (actual, expected) {
+        (
+            ManifestSurface::Role { name: actual },
+            ClientSurfaceSelector::Role { name: expected },
+        ) => !expected.trim().is_empty() && actual == expected,
+        (
+            ManifestSurface::Application {
+                name: actual,
+                roles,
+            },
+            ClientSurfaceSelector::Application { name: expected },
+        ) => {
+            !expected.trim().is_empty()
+                && actual == expected
+                && !roles.is_empty()
+                && roles.iter().all(|role| !role.trim().is_empty())
+        }
+        _ => false,
+    };
+    if matches {
+        return Ok(());
+    }
+    let actual_label = match actual {
+        ManifestSurface::Role { name } => format!("role `{name}`"),
+        ManifestSurface::Application { name, .. } => format!("application `{name}`"),
+    };
+    let expected_label = match expected {
+        ClientSurfaceSelector::Role { name } => format!("role `{name}`"),
+        ClientSurfaceSelector::Application { name } => format!("application `{name}`"),
+    };
+    Err(ClientCompileError::manifest(
+        "client.manifest.surface_mismatch",
+        format!(
+            "selected manifest surface is {actual_label}; compiler was explicitly requested for {expected_label}"
+        ),
+    ))
+}
+
+pub(crate) fn validate_capabilities(
+    capabilities: &ManifestCapabilities,
+) -> Result<(), ClientCompileError> {
+    if capabilities.query_fallback != "revalidate" {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.query_fallback",
+            format!(
+                "unsupported query fallback `{}`; manifest v7 requires `revalidate`",
+                capabilities.query_fallback
+            ),
+        ));
+    }
+    if capabilities.live_resume && !capabilities.live_queries {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.live_resume",
+            "capabilities.live_resume requires capabilities.live_queries",
+        ));
+    }
+    if capabilities.tombstones && !capabilities.record_revisions {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.tombstone_capability",
+            "capabilities.tombstones requires capabilities.record_revisions",
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_execution_limits(
+    execution: &ManifestExecutionLimits,
+) -> Result<(), ClientCompileError> {
+    const JS_MAX_SAFE_INTEGER: u64 = 9_007_199_254_740_991;
+    for (name, value) in [
+        ("max_depth", execution.max_depth),
+        ("max_bool_width", execution.max_bool_width),
+        ("max_in_list", execution.max_in_list),
+    ] {
+        if value > JS_MAX_SAFE_INTEGER {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.execution_js_integer",
+                format!("execution.{name} `{value}` exceeds JavaScript's exact integer range"),
+            ));
+        }
+    }
+    if execution.complexity.version != 1 {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.complexity_version",
+            format!(
+                "unsupported query complexity contract version {}; dctl requires version 1",
+                execution.complexity.version
+            ),
+        ));
+    }
+    let weights = [
+        ("scalar", execution.complexity.scalar),
+        ("belongs_to", execution.complexity.belongs_to),
+        ("has_many", execution.complexity.has_many),
+        ("m2m", execution.complexity.m2m),
+        ("aggregate", execution.complexity.aggregate),
+        ("list_root", execution.complexity.list_root),
+        ("by_pk", execution.complexity.by_pk),
+        ("list_fanout", execution.complexity.list_fanout),
+    ];
+    if let Some((name, _)) = weights.into_iter().find(|(_, value)| *value == 0) {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.complexity_weight",
+            format!("query complexity weight `{name}` must be greater than zero"),
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_derived_capabilities(
+    capabilities: &ManifestCapabilities,
+    roots: &BTreeMap<(RootOperation, String), ManifestRoot>,
+    commands: &[ManifestCommand],
+) -> Result<(), ClientCompileError> {
+    let has_live_roots = roots
+        .keys()
+        .any(|(operation, _)| *operation == RootOperation::Subscription);
+    if capabilities.live_queries != has_live_roots {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.live_capability",
+            "capabilities.live_queries must exactly describe the subscription-root inventory",
+        ));
+    }
+    let has_commands = !commands.is_empty();
+    if capabilities.causal_receipts != has_commands || !capabilities.cache_scope {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.command_capability",
+            "causal_receipts must agree with command inventory and cache_scope must be enabled for every generated surface",
+        ));
+    }
+    if capabilities.confirmed_persistence {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.persistence_capability",
+            "manifest v7 does not yet support confirmed client persistence",
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_scalar_codecs(
+    codecs: Vec<ManifestScalarCodec>,
+) -> Result<BTreeMap<String, String>, ClientCompileError> {
+    if codecs.is_empty() {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.scalar_codecs",
+            "manifest.scalar_codecs must declare the complete authorized scalar inventory",
+        ));
+    }
+    let supported = [
+        ("BigInt", "json_number_precision_limited"),
+        ("Boolean", "boolean"),
+        ("Bytea", "base64"),
+        ("Float", "float64"),
+        ("ID", "string"),
+        ("Int", "int32"),
+        ("JSON", "json"),
+        ("String", "string"),
+        ("Timestamptz", "string_unvalidated_timestamp"),
+    ]
+    .into_iter()
+    .collect::<BTreeMap<_, _>>();
+    let mut result = BTreeMap::new();
+    for entry in codecs {
+        validate_nonempty(&entry.scalar, "manifest scalar")?;
+        validate_nonempty(&entry.codec, "manifest scalar codec")?;
+        let expected = supported.get(entry.scalar.as_str()).ok_or_else(|| {
+            ClientCompileError::manifest(
+                "client.manifest.scalar_unsupported",
+                format!(
+                    "scalar `{}` has no fail-closed TypeScript codec in this compiler",
+                    entry.scalar
+                ),
+            )
+        })?;
+        if entry.codec != *expected {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.codec_unsupported",
+                format!(
+                    "scalar `{}` declares codec `{}`; compiler requires `{expected}`",
+                    entry.scalar, entry.codec
+                ),
+            ));
+        }
+        if result
+            .insert(entry.scalar.clone(), entry.codec.clone())
+            .is_some()
+        {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.duplicate_scalar",
+                format!("manifest repeats scalar codec `{}`", entry.scalar),
+            ));
+        }
+    }
+    if result.len() != supported.len()
+        || supported.keys().any(|scalar| !result.contains_key(*scalar))
+    {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.scalar_codecs",
+            "manifest.scalar_codecs must contain the exact v4 scalar inventory",
+        ));
+    }
+    Ok(result)
+}
+
+pub(crate) fn canonicalize_model(model: &mut ManifestModel) -> Result<(), ClientCompileError> {
+    canonicalize_string_set(
+        &mut model.dependencies,
+        &format!("model `{}` dependency", model.id),
+    )?;
+    model
+        .fields
+        .sort_by(|left, right| left.name.cmp(&right.name));
+    model
+        .relationships
+        .sort_by(|left, right| left.name.cmp(&right.name));
+    canonicalize_filter_input(&mut model.filter_input)?;
+    canonicalize_row_policy(&mut model.row_policy);
+    for relationship in &mut model.relationships {
+        canonicalize_arguments(
+            &mut relationship.arguments,
+            &format!(
+                "model `{}` relationship `{}` argument",
+                model.id, relationship.name
+            ),
+        )?;
+        canonicalize_string_set(
+            &mut relationship.dependencies,
+            &format!(
+                "model `{}` relationship `{}` dependency",
+                model.id, relationship.name
+            ),
+        )?;
+        if let Some(filter) = &mut relationship.filter {
+            canonicalize_filter_semantics(filter)?;
+        }
+        if let Some(order) = &mut relationship.order {
+            canonicalize_order_semantics(order)?;
+        }
+        if let Some(aggregate) = &mut relationship.aggregate {
+            canonicalize_arguments(
+                &mut aggregate.arguments,
+                &format!(
+                    "model `{}` relationship `{}` aggregate argument",
+                    model.id, relationship.name
+                ),
+            )?;
+            canonicalize_aggregate_semantics(&mut aggregate.semantics)?;
+            canonicalize_string_set(
+                &mut aggregate.dependencies,
+                &format!(
+                    "model `{}` relationship `{}` aggregate dependency",
+                    model.id, relationship.name
+                ),
+            )?;
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn canonicalize_row_policy(policy: &mut ManifestRowPolicy) {
+    if let ManifestRowPolicy::Predicate { expression } = policy {
+        canonicalize_filter_expression(expression);
+    }
+}
+
+pub(crate) fn canonicalize_filter_expression(expression: &mut ManifestFilterExpr) {
+    match expression {
+        ManifestFilterExpr::And(expressions) | ManifestFilterExpr::Or(expressions) => {
+            for expression in expressions {
+                canonicalize_filter_expression(expression);
+            }
+        }
+        ManifestFilterExpr::Not(expression) => canonicalize_filter_expression(expression),
+        ManifestFilterExpr::Cmp { rhs, .. } => canonicalize_operand(rhs),
+        ManifestFilterExpr::In { values, .. } => {
+            for operand in values {
+                canonicalize_operand(operand);
+            }
+        }
+        ManifestFilterExpr::Rel { predicate, .. } => {
+            canonicalize_filter_expression(predicate);
+        }
+        ManifestFilterExpr::IsNull { .. } => {}
+    }
+}
+
+pub(crate) fn canonicalize_operand(operand: &mut ManifestOperand) {
+    if let ManifestOperand::Lit(ManifestLitValue::Json(value)) = operand {
+        *value = canonical_json_value(std::mem::take(value));
+    }
+}
+
+pub(crate) fn canonicalize_filter_semantics(
+    semantics: &mut ManifestFilterSemantics,
+) -> Result<(), ClientCompileError> {
+    canonicalize_filter_fields(&mut semantics.fields)?;
+    canonicalize_string_set(&mut semantics.relationships, "filter relationship")?;
+    canonicalize_row_policy(&mut semantics.row_policy);
+    Ok(())
+}
+
+pub(crate) fn canonicalize_filter_input(
+    input: &mut ManifestFilterInput,
+) -> Result<(), ClientCompileError> {
+    canonicalize_filter_fields(&mut input.fields)?;
+    input
+        .relationships
+        .sort_by(|left, right| left.field.cmp(&right.field));
+    Ok(())
+}
+
+pub(crate) fn canonicalize_filter_fields(
+    fields: &mut [ManifestFilterField],
+) -> Result<(), ClientCompileError> {
+    fields.sort_by(|left, right| left.name.cmp(&right.name));
+    for field in fields {
+        canonicalize_string_set(
+            &mut field.operators,
+            &format!("filter field `{}` operator", field.name),
+        )?;
+    }
+    Ok(())
+}
+
+pub(crate) fn canonicalize_order_semantics(
+    semantics: &mut ManifestOrderSemantics,
+) -> Result<(), ClientCompileError> {
+    canonicalize_string_set(&mut semantics.fields, "order field")?;
+    canonicalize_string_set(&mut semantics.values, "order value")
+}
+
+pub(crate) fn canonicalize_aggregate_semantics(
+    semantics: &mut ManifestAggregateSemantics,
+) -> Result<(), ClientCompileError> {
+    canonicalize_string_set(&mut semantics.sum, "aggregate sum field")?;
+    canonicalize_string_set(&mut semantics.avg, "aggregate avg field")?;
+    canonicalize_string_set(&mut semantics.min, "aggregate min field")?;
+    canonicalize_string_set(&mut semantics.max, "aggregate max field")
+}
+
+pub(crate) fn canonicalize_arguments(
+    arguments: &mut [ManifestArgument],
+    _label: &str,
+) -> Result<(), ClientCompileError> {
+    arguments.sort_by(|left, right| left.name.cmp(&right.name));
+    Ok(())
+}
+
+pub(crate) fn validate_model(
+    model: &ManifestModel,
+    scalar_codecs: &BTreeMap<String, String>,
+) -> Result<(), ClientCompileError> {
+    validate_graphql_name(&model.id, "manifest model id")?;
+    validate_graphql_name(&model.typename, "manifest model typename")?;
+    validate_nonempty(&model.source_table, "manifest model source_table")?;
+    validate_graphql_name(
+        &model.filter_input.type_name,
+        "manifest model filter input type",
+    )?;
+    validate_nonempty_strings(
+        &model.dependencies,
+        &format!("model `{}` dependency", model.id),
+    )?;
+    if !model
+        .dependencies
+        .iter()
+        .any(|dependency| dependency == &model.source_table)
+    {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.model_dependency",
+            format!(
+                "model `{}` dependencies must include source table `{}`",
+                model.id, model.source_table
+            ),
+        ));
+    }
+    if model.tombstones && !model.record_revisions {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.model_tombstones",
+            format!(
+                "model `{}` cannot expose tombstones without record revisions",
+                model.id
+            ),
+        ));
+    }
+    let mut names = BTreeSet::new();
+    for field in &model.fields {
+        validate_graphql_name(&field.name, "manifest model field")?;
+        validate_graphql_name(&field.scalar, "manifest field scalar")?;
+        validate_nonempty(&field.codec, "manifest field codec")?;
+        match scalar_codecs.get(&field.scalar) {
+            Some(codec) if codec == &field.codec => {}
+            Some(codec) => {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.field_codec",
+                    format!(
+                        "model `{}` field `{}` codec `{}` does not match scalar `{}` inventory codec `{codec}`",
+                        model.id, field.name, field.codec, field.scalar
+                    ),
+                ));
+            }
+            None => {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.field_scalar",
+                    format!(
+                        "model `{}` field `{}` uses scalar `{}` absent from manifest.scalar_codecs",
+                        model.id, field.name, field.scalar
+                    ),
+                ));
+            }
+        }
+        if !names.insert(field.name.as_str()) {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.duplicate_field",
+                format!("model `{}` repeats field `{}`", model.id, field.name),
+            ));
+        }
+    }
+    for relationship in &model.relationships {
+        validate_graphql_name(&relationship.name, "manifest relationship")?;
+        if !names.insert(relationship.name.as_str()) {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.duplicate_member",
+                format!(
+                    "model `{}` repeats field/relationship `{}`",
+                    model.id, relationship.name
+                ),
+            ));
+        }
+        validate_graphql_name(
+            &relationship.target_model,
+            "manifest relationship target model",
+        )?;
+        validate_graphql_name(
+            &relationship.target_typename,
+            "manifest relationship target typename",
+        )?;
+        validate_unique_arguments_for(
+            &relationship.arguments,
+            scalar_codecs,
+            &format!("model `{}` relationship `{}`", model.id, relationship.name),
+        )?;
+        validate_nonempty_strings(
+            &relationship.dependencies,
+            &format!(
+                "model `{}` relationship `{}` dependency",
+                model.id, relationship.name
+            ),
+        )?;
+    }
+    match &model.normalization {
+        ManifestNormalization::Embedded => {}
+        ManifestNormalization::Normalized { fields, encoding } => {
+            if encoding != "canonical_json_tuple_v1" {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.identity_encoding",
+                    format!(
+                        "model `{}` uses unsupported identity encoding `{encoding}`",
+                        model.id
+                    ),
+                ));
+            }
+            if fields.is_empty() {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.empty_identity",
+                    format!("normalized model `{}` has no identity fields", model.id),
+                ));
+            }
+            let mut identities = BTreeSet::new();
+            for identity in fields {
+                validate_graphql_name(&identity.name, "manifest identity field")?;
+                validate_nonempty(&identity.codec, "manifest identity codec")?;
+                if !identities.insert(identity.name.as_str()) {
+                    return Err(ClientCompileError::manifest(
+                        "client.manifest.duplicate_identity",
+                        format!(
+                            "model `{}` repeats identity field `{}`",
+                            model.id, identity.name
+                        ),
+                    ));
+                }
+                let Some(field) = model.field(&identity.name) else {
+                    return Err(ClientCompileError::manifest(
+                        "client.manifest.identity_field",
+                        format!(
+                            "model `{}` identity field `{}` is absent from its authorized fields",
+                            model.id, identity.name
+                        ),
+                    ));
+                };
+                if field.nullable || field.codec != identity.codec {
+                    return Err(ClientCompileError::manifest(
+                        "client.manifest.identity_codec",
+                        format!(
+                            "model `{}` identity field `{}` must be non-null and match codec `{}`",
+                            model.id, identity.name, identity.codec
+                        ),
+                    ));
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_model_graph(
+    models: &BTreeMap<String, ManifestModel>,
+    scalar_codecs: &BTreeMap<String, String>,
+) -> Result<(), ClientCompileError> {
+    for model in models.values() {
+        validate_row_policy(&model.row_policy, model, models)?;
+        validate_filter_input(&model.filter_input, model, models)?;
+        for relationship in &model.relationships {
+            let target = models.get(&relationship.target_model).ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.manifest.relationship_target",
+                    format!(
+                        "model `{}` relationship `{}` targets absent model `{}`",
+                        model.id, relationship.name, relationship.target_model
+                    ),
+                )
+            })?;
+            if relationship.target_typename != target.typename {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.relationship_typename",
+                    format!(
+                        "model `{}` relationship `{}` target typename `{}` does not match model `{}` typename `{}`",
+                        model.id,
+                        relationship.name,
+                        relationship.target_typename,
+                        target.id,
+                        target.typename
+                    ),
+                ));
+            }
+            require_dependency(
+                &relationship.dependencies,
+                &model.source_table,
+                &format!("relationship {}.{}", model.id, relationship.name),
+            )?;
+            require_dependency(
+                &relationship.dependencies,
+                &target.source_table,
+                &format!("relationship {}.{}", model.id, relationship.name),
+            )?;
+            if let ManifestRelationshipKeyMapping::Through { table, .. } = &relationship.key_mapping
+            {
+                require_dependency(
+                    &relationship.dependencies,
+                    table,
+                    &format!("relationship {}.{}", model.id, relationship.name),
+                )?;
+            }
+            match relationship.kind {
+                ManifestRelationshipKind::BelongsTo if relationship.list => {
+                    return Err(ClientCompileError::manifest(
+                        "client.manifest.relationship_cardinality",
+                        format!(
+                            "belongs_to relationship `{}.{}` cannot be a list",
+                            model.id, relationship.name
+                        ),
+                    ));
+                }
+                ManifestRelationshipKind::HasMany | ManifestRelationshipKind::ManyToMany
+                    if !relationship.list =>
+                {
+                    return Err(ClientCompileError::manifest(
+                        "client.manifest.relationship_cardinality",
+                        format!(
+                            "{:?} relationship `{}.{}` must be a list",
+                            relationship.kind, model.id, relationship.name
+                        ),
+                    ));
+                }
+                _ => {}
+            }
+            if relationship.list && relationship.nullable {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.relationship_nullability",
+                    format!(
+                        "list relationship `{}.{}` must be a non-null collection",
+                        model.id, relationship.name
+                    ),
+                ));
+            }
+            validate_key_mapping(model, target, relationship)?;
+            validate_relationship_semantics(model, target, relationship, models, scalar_codecs)?;
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_key_mapping(
+    source: &ManifestModel,
+    target: &ManifestModel,
+    relationship: &ManifestRelationship,
+) -> Result<(), ClientCompileError> {
+    let validate_fields = |local: &[String], remote: &[String]| {
+        if local.is_empty() || local.len() != remote.len() {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.relationship_key_mapping",
+                format!(
+                    "relationship `{}.{}` key mapping must contain equally sized non-empty local and remote fields",
+                    source.id, relationship.name
+                ),
+            ));
+        }
+        for field in local {
+            if source.field(field).is_none() {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.relationship_local_key",
+                    format!(
+                        "relationship `{}.{}` references absent local field `{field}`",
+                        source.id, relationship.name
+                    ),
+                ));
+            }
+        }
+        for field in remote {
+            if target.field(field).is_none() {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.relationship_remote_key",
+                    format!(
+                        "relationship `{}.{}` references absent target field `{field}`",
+                        source.id, relationship.name
+                    ),
+                ));
+            }
+        }
+        for (local_field, remote_field) in local.iter().zip(remote) {
+            let local_contract = source
+                .field(local_field)
+                .expect("local relationship field checked above");
+            let remote_contract = target
+                .field(remote_field)
+                .expect("remote relationship field checked above");
+            if local_contract.scalar == "BigInt"
+                || remote_contract.scalar == "BigInt"
+                || local_contract.codec != remote_contract.codec
+            {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.relationship_key_codec",
+                    format!(
+                        "relationship {}.{} local and target keys must use matching portable codecs",
+                        source.id, relationship.name
+                    ),
+                ));
+            }
+        }
+        Ok(())
+    };
+    let local_maintenance = matches!(
+        relationship.key_mapping,
+        ManifestRelationshipKeyMapping::Direct { .. }
+            | ManifestRelationshipKeyMapping::Through { .. }
+    );
+    if local_maintenance
+        != matches!(
+            relationship.maintenance,
+            ManifestRelationshipMaintenance::Local
+        )
+    {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.relationship_maintenance",
+            format!(
+                "relationship `{}.{}` maintenance does not match its key mapping",
+                source.id, relationship.name
+            ),
+        ));
+    }
+    match &relationship.key_mapping {
+        ManifestRelationshipKeyMapping::Direct { local, remote } => validate_fields(local, remote),
+        ManifestRelationshipKeyMapping::Through {
+            local,
+            remote,
+            table,
+            source_foreign_key,
+            target_foreign_key,
+        } => {
+            validate_fields(local, remote)?;
+            validate_nonempty(table, "relationship through table")?;
+            validate_nonempty(
+                source_foreign_key,
+                "relationship through source foreign key",
+            )?;
+            validate_nonempty(
+                target_foreign_key,
+                "relationship through target foreign key",
+            )
+        }
+        ManifestRelationshipKeyMapping::ThroughOpaque {
+            local,
+            remote,
+            dependency,
+        } => {
+            validate_fields(local, remote)?;
+            validate_nonempty(dependency, "opaque relationship dependency")?;
+            if !relationship
+                .dependencies
+                .iter()
+                .any(|candidate| candidate == dependency)
+            {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.relationship_dependency",
+                    format!(
+                        "relationship `{}.{}` opaque dependency `{dependency}` is absent from its dependency set",
+                        source.id, relationship.name
+                    ),
+                ));
+            }
+            Ok(())
+        }
+        ManifestRelationshipKeyMapping::Embedded => Ok(()),
+    }
+}
+
+pub(crate) fn validate_relationship_semantics(
+    source: &ManifestModel,
+    target: &ManifestModel,
+    relationship: &ManifestRelationship,
+    models: &BTreeMap<String, ManifestModel>,
+    scalar_codecs: &BTreeMap<String, String>,
+) -> Result<(), ClientCompileError> {
+    validate_filter_argument_type(
+        &relationship.arguments,
+        target,
+        &format!("relationship `{}.{}`", source.id, relationship.name),
+    )?;
+    let has_filter_argument = relationship
+        .arguments
+        .iter()
+        .any(|argument| argument.kind == ManifestArgumentKind::Filter);
+    let has_order_argument = relationship
+        .arguments
+        .iter()
+        .any(|argument| argument.kind == ManifestArgumentKind::Order);
+    let has_limit_argument = relationship
+        .arguments
+        .iter()
+        .any(|argument| argument.kind == ManifestArgumentKind::Limit);
+    let has_offset_argument = relationship
+        .arguments
+        .iter()
+        .any(|argument| argument.kind == ManifestArgumentKind::Offset);
+    if relationship.filter.is_some() != has_filter_argument
+        || relationship.order.is_some() != has_order_argument
+        || relationship.pagination.is_some() != (has_limit_argument && has_offset_argument)
+    {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.relationship_arguments",
+            format!(
+                "relationship {}.{} arguments do not match its filter/order/pagination semantics",
+                source.id, relationship.name
+            ),
+        ));
+    }
+    if relationship.list {
+        let filter = relationship.filter.as_ref().ok_or_else(|| {
+            ClientCompileError::manifest(
+                "client.manifest.relationship_filter",
+                format!(
+                    "list relationship `{}.{}` requires filter semantics",
+                    source.id, relationship.name
+                ),
+            )
+        })?;
+        validate_filter_semantics(filter, target, models)?;
+        let order = relationship.order.as_ref().ok_or_else(|| {
+            ClientCompileError::manifest(
+                "client.manifest.relationship_order",
+                format!(
+                    "list relationship `{}.{}` requires order semantics",
+                    source.id, relationship.name
+                ),
+            )
+        })?;
+        validate_order_semantics(order, target)?;
+        validate_pagination(
+            relationship.pagination.as_ref().ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.manifest.relationship_pagination",
+                    format!(
+                        "list relationship `{}.{}` requires pagination semantics",
+                        source.id, relationship.name
+                    ),
+                )
+            })?,
+            &format!("relationship `{}.{}`", source.id, relationship.name),
+        )?;
+    } else if relationship.filter.is_some()
+        || relationship.order.is_some()
+        || relationship.pagination.is_some()
+    {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.relationship_list_semantics",
+            format!(
+                "singular relationship `{}.{}` cannot declare filter, order, or pagination semantics",
+                source.id, relationship.name
+            ),
+        ));
+    }
+    if relationship.live && !relationship.list {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.relationship_live",
+            format!(
+                "singular relationship `{}.{}` cannot be marked live",
+                source.id, relationship.name
+            ),
+        ));
+    }
+    if let Some(aggregate) = &relationship.aggregate {
+        if !relationship.list {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.relationship_aggregate",
+                format!(
+                    "singular relationship `{}.{}` cannot expose an aggregate",
+                    source.id, relationship.name
+                ),
+            ));
+        }
+        validate_graphql_name(&aggregate.name, "relationship aggregate name")?;
+        validate_graphql_name(
+            &aggregate.semantics.wrapper_typename,
+            "relationship aggregate wrapper type",
+        )?;
+        validate_graphql_name(
+            &aggregate.semantics.fields_typename,
+            "relationship aggregate fields type",
+        )?;
+        validate_unique_arguments_for(
+            &aggregate.arguments,
+            scalar_codecs,
+            &format!("relationship aggregate {}.{}", source.id, aggregate.name),
+        )?;
+        validate_nonempty_strings(&aggregate.dependencies, "relationship aggregate dependency")?;
+        for dependency in &relationship.dependencies {
+            require_dependency(
+                &aggregate.dependencies,
+                dependency,
+                &format!("relationship aggregate {}.{}", source.id, aggregate.name),
+            )?;
+        }
+        validate_aggregate_semantics(&aggregate.semantics, target)?;
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_filter_input(
+    input: &ManifestFilterInput,
+    model: &ManifestModel,
+    models: &BTreeMap<String, ManifestModel>,
+) -> Result<(), ClientCompileError> {
+    validate_filter_fields(&input.fields, model)?;
+    let expected_relationships = model
+        .relationships
+        .iter()
+        .map(|relationship| relationship.name.as_str())
+        .collect::<BTreeSet<_>>();
+    let actual_relationships = input
+        .relationships
+        .iter()
+        .map(|relationship| relationship.field.as_str())
+        .collect::<BTreeSet<_>>();
+    if actual_relationships != expected_relationships
+        || input.relationships.len() != expected_relationships.len()
+    {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.filter_input_relationships",
+            format!(
+                "model `{}` filter input must describe every authorized relationship exactly once",
+                model.id
+            ),
+        ));
+    }
+    for relationship_input in &input.relationships {
+        validate_graphql_name(
+            &relationship_input.field,
+            "manifest filter input relationship field",
+        )?;
+        validate_graphql_name(
+            &relationship_input.target_type,
+            "manifest filter input relationship target type",
+        )?;
+        let relationship = model
+            .relationship(&relationship_input.field)
+            .expect("filter input relationship inventory checked above");
+        let target = models.get(&relationship.target_model).ok_or_else(|| {
+            ClientCompileError::manifest(
+                "client.manifest.filter_input_target",
+                format!(
+                    "model `{}` filter relationship `{}` targets absent model `{}`",
+                    model.id, relationship.name, relationship.target_model
+                ),
+            )
+        })?;
+        if relationship_input.target_type != target.filter_input.type_name {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.filter_input_target_type",
+                format!(
+                    "model `{}` filter relationship `{}` target type `{}` does not match model `{}` filter input `{}`",
+                    model.id,
+                    relationship.name,
+                    relationship_input.target_type,
+                    target.id,
+                    target.filter_input.type_name
+                ),
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_filter_fields(
+    fields: &[ManifestFilterField],
+    model: &ManifestModel,
+) -> Result<(), ClientCompileError> {
+    let expected_fields = model
+        .fields
+        .iter()
+        .map(|field| field.name.as_str())
+        .collect::<BTreeSet<_>>();
+    let actual_fields = fields
+        .iter()
+        .map(|field| field.name.as_str())
+        .collect::<BTreeSet<_>>();
+    if actual_fields != expected_fields || fields.len() != expected_fields.len() {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.filter_fields",
+            format!(
+                "filter input for model `{}` must describe every authorized scalar field exactly once",
+                model.id
+            ),
+        ));
+    }
+    for field in fields {
+        validate_nonempty_strings(
+            &field.operators,
+            &format!("model `{}` filter operator", model.id),
+        )?;
+        if field.operators.is_empty() {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.filter_operators",
+                format!(
+                    "model `{}` filter field `{}` has no supported operators",
+                    model.id, field.name
+                ),
+            ));
+        }
+        if field.operators.iter().any(|operator| {
+            !matches!(
+                operator.as_str(),
+                "_eq"
+                    | "_neq"
+                    | "_gt"
+                    | "_gte"
+                    | "_lt"
+                    | "_lte"
+                    | "_in"
+                    | "_nin"
+                    | "_is_null"
+                    | "_like"
+                    | "_ilike"
+                    | "_contains"
+                    | "_contained_in"
+                    | "_has_key"
+            )
+        }) {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.filter_operator",
+                format!(
+                    "model `{}` filter field `{}` declares an unknown comparison operator",
+                    model.id, field.name
+                ),
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_filter_semantics(
+    semantics: &ManifestFilterSemantics,
+    model: &ManifestModel,
+    models: &BTreeMap<String, ManifestModel>,
+) -> Result<(), ClientCompileError> {
+    if semantics.fields != model.filter_input.fields {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.filter_contract",
+            format!(
+                "filter semantics for model `{}` do not match its authoritative filter input fields",
+                model.id
+            ),
+        ));
+    }
+    let input_relationships = model
+        .filter_input
+        .relationships
+        .iter()
+        .map(|relationship| relationship.field.as_str())
+        .collect::<Vec<_>>();
+    if semantics
+        .relationships
+        .iter()
+        .map(String::as_str)
+        .ne(input_relationships)
+    {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.filter_contract",
+            format!(
+                "filter semantics for model `{}` do not match its authoritative filter input relationships",
+                model.id
+            ),
+        ));
+    }
+    if semantics.row_policy != model.row_policy {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.filter_row_policy",
+            format!(
+                "filter semantics for model `{}` do not preserve its row policy",
+                model.id
+            ),
+        ));
+    }
+    validate_row_policy(&semantics.row_policy, model, models)
+}
+
+pub(crate) fn validate_filter_argument_type(
+    arguments: &[ManifestArgument],
+    model: &ManifestModel,
+    owner: &str,
+) -> Result<(), ClientCompileError> {
+    let Some(argument) = arguments
+        .iter()
+        .find(|argument| argument.kind == ManifestArgumentKind::Filter)
+    else {
+        return Ok(());
+    };
+    if argument.list || argument.type_name != model.filter_input.type_name {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.filter_argument_type",
+            format!(
+                "{owner} filter argument `{}` must use non-list input `{}`, received `{}`",
+                argument.name, model.filter_input.type_name, argument.type_name
+            ),
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_order_semantics(
+    semantics: &ManifestOrderSemantics,
+    model: &ManifestModel,
+) -> Result<(), ClientCompileError> {
+    let expected_fields = model
+        .fields
+        .iter()
+        .map(|field| field.name.as_str())
+        .collect::<BTreeSet<_>>();
+    let actual_fields = semantics
+        .fields
+        .iter()
+        .map(String::as_str)
+        .collect::<BTreeSet<_>>();
+    if actual_fields != expected_fields || semantics.fields.len() != expected_fields.len() {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.order_fields",
+            format!(
+                "order semantics for model `{}` must describe every authorized scalar field exactly once",
+                model.id
+            ),
+        ));
+    }
+    let expected_values = [
+        "asc",
+        "asc_nulls_first",
+        "asc_nulls_last",
+        "desc",
+        "desc_nulls_first",
+        "desc_nulls_last",
+    ]
+    .into_iter()
+    .collect::<BTreeSet<_>>();
+    let actual_values = semantics
+        .values
+        .iter()
+        .map(String::as_str)
+        .collect::<BTreeSet<_>>();
+    if actual_values != expected_values || semantics.values.len() != expected_values.len() {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.order_values",
+            format!(
+                "order semantics for model `{}` must use the manifest v7 direction set",
+                model.id
+            ),
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_pagination(
+    pagination: &ManifestPagination,
+    owner: &str,
+) -> Result<(), ClientCompileError> {
+    if pagination.kind != "offset" || pagination.coverage != "window" {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.pagination",
+            format!("{owner} pagination must use kind `offset` and coverage `window`"),
+        ));
+    }
+    if pagination.default_limit > pagination.max_limit {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.pagination_limit",
+            format!("{owner} pagination default_limit must not exceed max_limit"),
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_aggregate_semantics(
+    aggregate: &ManifestAggregateSemantics,
+    model: &ManifestModel,
+) -> Result<(), ClientCompileError> {
+    validate_graphql_name(&aggregate.wrapper_typename, "aggregate wrapper typename")?;
+    validate_graphql_name(&aggregate.fields_typename, "aggregate fields typename")?;
+    validate_pagination(
+        &aggregate.nodes_pagination,
+        &format!("aggregate nodes for model `{}`", model.id),
+    )?;
+    if !aggregate.count || !aggregate.nodes {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.aggregate_capability",
+            format!(
+                "aggregate semantics for model `{}` must retain count and nodes",
+                model.id
+            ),
+        ));
+    }
+    for (label, fields) in [
+        ("sum", &aggregate.sum),
+        ("avg", &aggregate.avg),
+        ("min", &aggregate.min),
+        ("max", &aggregate.max),
+    ] {
+        for field in fields {
+            if model.field(field).is_none() {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.aggregate_field",
+                    format!(
+                        "aggregate {label} for model `{}` references absent field `{field}`",
+                        model.id
+                    ),
+                ));
+            }
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_row_policy(
+    policy: &ManifestRowPolicy,
+    model: &ManifestModel,
+    models: &BTreeMap<String, ManifestModel>,
+) -> Result<(), ClientCompileError> {
+    match policy {
+        ManifestRowPolicy::Unrestricted | ManifestRowPolicy::ServerOnly => Ok(()),
+        ManifestRowPolicy::Predicate { expression } => {
+            validate_filter_expression(expression, model, models)
+        }
+    }
+}
+
+pub(crate) fn derive_trusted_preset_descriptors(
+    models: &BTreeMap<String, ManifestModel>,
+    commands: &[ManifestCommand],
+) -> Result<Vec<ManifestTrustedPresetDescriptor>, ClientCompileError> {
+    let mut descriptors = BTreeMap::<String, String>::new();
+    for command in commands {
+        for descriptor in &command.extensions.trusted_presets {
+            insert_trusted_preset_descriptor(
+                &mut descriptors,
+                descriptor,
+                &format!("command `{}`", command.name),
+            )?;
+        }
+    }
+    for model in models.values() {
+        if let ManifestRowPolicy::Predicate { expression } = &model.row_policy {
+            collect_row_policy_trusted_presets(expression, model, models, &mut descriptors)?;
+        }
+    }
+    Ok(descriptors
+        .into_iter()
+        .map(|(name, codec)| ManifestTrustedPresetDescriptor { name, codec })
+        .collect())
+}
+
+pub(crate) fn collect_row_policy_trusted_presets(
+    expression: &ManifestFilterExpr,
+    model: &ManifestModel,
+    models: &BTreeMap<String, ManifestModel>,
+    descriptors: &mut BTreeMap<String, String>,
+) -> Result<(), ClientCompileError> {
+    match expression {
+        ManifestFilterExpr::And(expressions) | ManifestFilterExpr::Or(expressions) => {
+            for expression in expressions {
+                collect_row_policy_trusted_presets(expression, model, models, descriptors)?;
+            }
+        }
+        ManifestFilterExpr::Not(expression) => {
+            collect_row_policy_trusted_presets(expression, model, models, descriptors)?;
+        }
+        ManifestFilterExpr::Cmp {
+            column,
+            rhs: ManifestOperand::Claim(claim),
+            ..
+        } => {
+            insert_row_policy_trusted_preset(model, column, &claim.header, descriptors)?;
+        }
+        ManifestFilterExpr::In { column, values, .. } => {
+            for value in values {
+                if let ManifestOperand::Claim(claim) = value {
+                    insert_row_policy_trusted_preset(model, column, &claim.header, descriptors)?;
+                }
+            }
+        }
+        ManifestFilterExpr::Rel { field, predicate } => {
+            let relationship = model.relationship(field).ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.manifest.row_policy_relationship",
+                    format!(
+                        "model `{}` row policy references absent relationship `{field}`",
+                        model.id
+                    ),
+                )
+            })?;
+            let target = models.get(&relationship.target_model).ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.manifest.row_policy_relationship",
+                    format!(
+                        "model `{}` row policy relationship `{field}` targets absent model `{}`",
+                        model.id, relationship.target_model
+                    ),
+                )
+            })?;
+            collect_row_policy_trusted_presets(predicate, target, models, descriptors)?;
+        }
+        ManifestFilterExpr::Cmp { .. } | ManifestFilterExpr::IsNull { .. } => {}
+    }
+    Ok(())
+}
+
+pub(crate) fn insert_row_policy_trusted_preset(
+    model: &ManifestModel,
+    column: &str,
+    name: &str,
+    descriptors: &mut BTreeMap<String, String>,
+) -> Result<(), ClientCompileError> {
+    let field = model.field(column).ok_or_else(|| {
+        ClientCompileError::manifest(
+            "client.manifest.row_policy_column",
+            format!(
+                "model `{}` row policy references absent field `{column}`",
+                model.id
+            ),
+        )
+    })?;
+    if matches!(field.codec.as_str(), "base64" | "json") {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.row_policy_portability",
+            format!(
+                "model `{}` row-policy claim `{name}` targets `{column}` with non-local codec `{}`",
+                model.id, field.codec
+            ),
+        ));
+    }
+    insert_trusted_preset_descriptor(
+        descriptors,
+        &ManifestTrustedPresetDescriptor {
+            name: name.into(),
+            codec: field.codec.clone(),
+        },
+        &format!("model `{}` row policy field `{column}`", model.id),
+    )
+}
+
+pub(crate) fn insert_trusted_preset_descriptor(
+    descriptors: &mut BTreeMap<String, String>,
+    descriptor: &ManifestTrustedPresetDescriptor,
+    owner: &str,
+) -> Result<(), ClientCompileError> {
+    validate_trusted_preset_name(&descriptor.name, "trusted preset name")?;
+    match descriptors.entry(descriptor.name.clone()) {
+        std::collections::btree_map::Entry::Vacant(entry) => {
+            entry.insert(descriptor.codec.clone());
+        }
+        std::collections::btree_map::Entry::Occupied(entry) if entry.get() == &descriptor.codec => {
+        }
+        std::collections::btree_map::Entry::Occupied(entry) => {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.trusted_preset_inventory",
+                format!(
+                    "trusted preset `{}` uses incompatible codecs `{}` and `{}` across the selected client surface ({owner})",
+                    descriptor.name,
+                    entry.get(),
+                    descriptor.codec
+                ),
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_trusted_preset_name(
+    value: &str,
+    description: &str,
+) -> Result<(), ClientCompileError> {
+    validate_nonempty(value, description)?;
+    if value.len() > 128 || value.trim() != value || value.chars().any(char::is_control) {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.trusted_preset_name",
+            format!("{description} must be 1..=128 bytes with no surrounding whitespace or control characters"),
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_filter_expression(
+    expression: &ManifestFilterExpr,
+    model: &ManifestModel,
+    models: &BTreeMap<String, ManifestModel>,
+) -> Result<(), ClientCompileError> {
+    match expression {
+        ManifestFilterExpr::And(expressions) | ManifestFilterExpr::Or(expressions) => {
+            for expression in expressions {
+                validate_filter_expression(expression, model, models)?;
+            }
+            Ok(())
+        }
+        ManifestFilterExpr::Not(expression) => {
+            validate_filter_expression(expression, model, models)
+        }
+        ManifestFilterExpr::Cmp { column, rhs, .. } => {
+            validate_policy_column(model, column)?;
+            validate_operand(rhs)
+        }
+        ManifestFilterExpr::In { column, values, .. } => {
+            validate_policy_column(model, column)?;
+            for operand in values {
+                validate_operand(operand)?;
+            }
+            Ok(())
+        }
+        ManifestFilterExpr::IsNull { column, .. } => validate_policy_column(model, column),
+        ManifestFilterExpr::Rel { field, predicate } => {
+            let relationship = model.relationship(field).ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.manifest.row_policy_relationship",
+                    format!(
+                        "model `{}` row policy references absent relationship `{field}`",
+                        model.id
+                    ),
+                )
+            })?;
+            let target = models.get(&relationship.target_model).ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.manifest.row_policy_relationship",
+                    format!(
+                        "model `{}` row policy relationship `{field}` has an absent target",
+                        model.id
+                    ),
+                )
+            })?;
+            validate_filter_expression(predicate, target, models)
+        }
+    }
+}
+
+pub(crate) fn validate_policy_column(
+    model: &ManifestModel,
+    column: &str,
+) -> Result<(), ClientCompileError> {
+    if model.field(column).is_none() {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.row_policy_column",
+            format!(
+                "model `{}` row policy references absent field `{column}`",
+                model.id
+            ),
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_operand(operand: &ManifestOperand) -> Result<(), ClientCompileError> {
+    const JS_MAX_SAFE_INTEGER: u64 = 9_007_199_254_740_991;
+
+    fn json_is_portable(value: &JsonValue) -> bool {
+        match value {
+            JsonValue::Null | JsonValue::Bool(_) | JsonValue::String(_) => true,
+            JsonValue::Number(number) => {
+                if let Some(value) = number.as_i64() {
+                    value.unsigned_abs() <= JS_MAX_SAFE_INTEGER
+                } else if let Some(value) = number.as_u64() {
+                    value <= JS_MAX_SAFE_INTEGER
+                } else {
+                    number.as_f64().is_some_and(f64::is_finite)
+                }
+            }
+            JsonValue::Array(values) => values.iter().all(json_is_portable),
+            JsonValue::Object(values) => values.values().all(json_is_portable),
+        }
+    }
+
+    if let ManifestOperand::Claim(claim) = operand {
+        validate_trusted_preset_name(&claim.header, "row policy claim header")?;
+        return Ok(());
+    }
+    let portable = match operand {
+        ManifestOperand::Claim(_) => unreachable!("claim returned above"),
+        ManifestOperand::Lit(ManifestLitValue::I64(value)) => {
+            value.unsigned_abs() <= JS_MAX_SAFE_INTEGER
+        }
+        ManifestOperand::Lit(ManifestLitValue::Json(value)) => json_is_portable(value),
+        ManifestOperand::Lit(_) => true,
+    };
+    if !portable {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.row_policy_portability",
+            "client-visible row policies cannot contain JavaScript-unsafe numbers",
+        ));
+    }
+    Ok(())
+}
diff --git a/distributed_cli/src/client_compiler/manifest/parse.rs b/distributed_cli/src/client_compiler/manifest/parse.rs
new file mode 100644
index 00000000..b5f9a543
--- /dev/null
+++ b/distributed_cli/src/client_compiler/manifest/parse.rs
@@ -0,0 +1,256 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value as JsonValue;
+
+use super::*;
+
+// The compiler treats one manifest version as an exact executable contract.
+// Same-version extensions must bump the pre-release version instead of being
+// silently ignored by an older client compiler.
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct ManifestWire {
+    manifest_version: u64,
+    protocol_version: u64,
+    service_id: String,
+    surface: ManifestSurface,
+    schema_fingerprint: String,
+    protocol_fingerprint: String,
+    execution: ManifestExecutionLimits,
+    capabilities: ManifestCapabilities,
+    scalar_codecs: Vec<ManifestScalarCodec>,
+    models: Vec<ManifestModel>,
+    roots: Vec<ManifestRoot>,
+    commands: Vec<ManifestCommand>,
+    protocol_operations: ManifestProtocolOperations,
+    projectors: Vec<ManifestProjector>,
+}
+
+#[derive(Serialize)]
+struct ManifestSchemaMaterial<'a> {
+    manifest_version: u64,
+    protocol_version: u64,
+    service_id: &'a str,
+    surface: &'a ManifestSurface,
+    execution: &'a ManifestExecutionLimits,
+    capabilities: &'a ManifestCapabilities,
+    scalar_codecs: &'a [ManifestScalarCodec],
+    models: &'a [ManifestModel],
+    roots: &'a [ManifestRoot],
+    commands: &'a [ManifestCommand],
+    protocol_operations: &'a ManifestProtocolOperations,
+    projectors: &'a [ManifestProjector],
+}
+
+impl ClientManifest {
+    pub(crate) fn parse(
+        value: JsonValue,
+        selector: &ClientSurfaceSelector,
+    ) -> Result<Self, ClientCompileError> {
+        validate_input_default_generators_in_json(&value)?;
+        let mut wire: ManifestWire = serde_json::from_value(value).map_err(|error| {
+            ClientCompileError::manifest(
+                "client.manifest.invalid",
+                format!("invalid Distributed client manifest: {error}"),
+            )
+        })?;
+        let computed_schema_fingerprint = schema_fingerprint(&wire)?;
+        if wire.manifest_version != MANIFEST_VERSION {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.version",
+                format!(
+                    "client compiler requires manifest_version {MANIFEST_VERSION}, received {}",
+                    wire.manifest_version
+                ),
+            ));
+        }
+        if wire.protocol_version != PROTOCOL_VERSION {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.protocol_version",
+                format!(
+                    "client compiler requires protocol_version {PROTOCOL_VERSION}, received {}",
+                    wire.protocol_version
+                ),
+            ));
+        }
+        validate_nonempty(&wire.service_id, "manifest.service_id")?;
+        validate_hash(&wire.schema_fingerprint, "manifest.schema_fingerprint")?;
+        validate_hash(&wire.protocol_fingerprint, "manifest.protocol_fingerprint")?;
+        validate_execution_limits(&wire.execution)?;
+        if wire.protocol_fingerprint != PROTOCOL_FINGERPRINT {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.protocol_fingerprint",
+                format!(
+                    "client compiler protocol contract is `{PROTOCOL_FINGERPRINT}`, received `{}`; regenerate the manifest and use a matching dctl version",
+                    wire.protocol_fingerprint
+                ),
+            ));
+        }
+        canonicalize_surface(&mut wire.surface)?;
+        validate_surface(&wire.surface, selector)?;
+        validate_capabilities(&wire.capabilities)?;
+
+        let scalar_codecs = validate_scalar_codecs(wire.scalar_codecs)?;
+        let mut models = BTreeMap::new();
+        let mut typenames = BTreeSet::new();
+        let mut source_tables = BTreeSet::new();
+        let mut filter_input_types = BTreeSet::new();
+        for mut model in wire.models {
+            canonicalize_model(&mut model)?;
+            validate_model(&model, &scalar_codecs)?;
+            if !typenames.insert(model.typename.clone()) {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.duplicate_typename",
+                    format!("duplicate manifest model typename `{}`", model.typename),
+                ));
+            }
+            if !source_tables.insert(model.source_table.clone()) {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.duplicate_source_table",
+                    format!(
+                        "multiple manifest models claim source table `{}`",
+                        model.source_table
+                    ),
+                ));
+            }
+            if !filter_input_types.insert(model.filter_input.type_name.clone()) {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.duplicate_filter_input",
+                    format!(
+                        "multiple manifest models claim filter input type `{}`",
+                        model.filter_input.type_name
+                    ),
+                ));
+            }
+            let id = model.id.clone();
+            if models.insert(id.clone(), model).is_some() {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.duplicate_model",
+                    format!("duplicate manifest model id `{id}`"),
+                ));
+            }
+        }
+        validate_model_graph(&models, &scalar_codecs)?;
+
+        let mut roots = BTreeMap::new();
+        let mut root_ids = BTreeSet::new();
+        for mut root in wire.roots {
+            canonicalize_root(&mut root)?;
+            validate_nonempty(&root.id, "manifest root id")?;
+            validate_nonempty(&root.name, "manifest root name")?;
+            validate_nonempty(&root.model, "manifest root model")?;
+            if !root_ids.insert(root.id.clone()) {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.duplicate_root_id",
+                    format!("duplicate manifest root id `{}`", root.id),
+                ));
+            }
+            if !models.contains_key(&root.model) {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.root_model",
+                    format!(
+                        "manifest root `{}` references missing model `{}`",
+                        root.name, root.model
+                    ),
+                ));
+            }
+            validate_unique_arguments(&root, &scalar_codecs)?;
+            validate_root_contract(&root, &models)?;
+            let key = (root.operation, root.name.clone());
+            if roots.insert(key, root).is_some() {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.duplicate_root",
+                    "duplicate manifest operation root",
+                ));
+            }
+        }
+
+        let mut projectors = wire.projectors;
+        canonicalize_projectors(&mut projectors)?;
+        validate_projectors(&projectors, &models)?;
+        let mut commands = wire.commands;
+        canonicalize_commands(&mut commands)?;
+        let mut command_validation = super::super::command_manifest::validate_command_manifest(
+            &commands,
+            &models,
+            &roots,
+            &scalar_codecs,
+            &projectors,
+            wire.capabilities.causal_receipts,
+            &wire.protocol_operations,
+        )?;
+        command_validation
+            .commands_requiring_revalidation
+            .extend(validate_direct_projections(
+                &commands,
+                &models,
+                &projectors,
+            )?);
+        let trusted_presets = derive_trusted_preset_descriptors(&models, &commands)?;
+        validate_derived_capabilities(&wire.capabilities, &roots, &commands)?;
+        if wire.schema_fingerprint != computed_schema_fingerprint {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.schema_fingerprint",
+                format!(
+                    "manifest schema fingerprint mismatch: declared `{}`, computed `{computed_schema_fingerprint}`; regenerate the selected client manifest",
+                    wire.schema_fingerprint
+                ),
+            ));
+        }
+
+        Ok(Self {
+            service_id: wire.service_id,
+            surface: wire.surface,
+            schema_fingerprint: wire.schema_fingerprint,
+            protocol_fingerprint: wire.protocol_fingerprint,
+            execution: wire.execution,
+            capabilities: wire.capabilities,
+            scalar_codecs,
+            models,
+            roots,
+            commands,
+            trusted_presets,
+            commands_requiring_revalidation: command_validation.commands_requiring_revalidation,
+            protocol_operations: wire.protocol_operations,
+            projectors,
+        })
+    }
+
+    pub(crate) fn root(&self, operation: RootOperation, name: &str) -> Option<&ManifestRoot> {
+        self.roots.get(&(operation, name.to_string()))
+    }
+}
+
+fn schema_fingerprint(wire: &ManifestWire) -> Result<String, ClientCompileError> {
+    let material = ManifestSchemaMaterial {
+        manifest_version: wire.manifest_version,
+        protocol_version: wire.protocol_version,
+        service_id: &wire.service_id,
+        surface: &wire.surface,
+        execution: &wire.execution,
+        capabilities: &wire.capabilities,
+        scalar_codecs: &wire.scalar_codecs,
+        models: &wire.models,
+        roots: &wire.roots,
+        commands: &wire.commands,
+        protocol_operations: &wire.protocol_operations,
+        projectors: &wire.projectors,
+    };
+    serde_json::to_vec(&material)
+        .map(|bytes| hash_bytes(&bytes))
+        .map_err(|error| {
+            ClientCompileError::manifest(
+                "client.manifest.schema_fingerprint",
+                format!("could not recompute manifest schema fingerprint: {error}"),
+            )
+        })
+}
+
+#[cfg(test)]
+pub(crate) fn refresh_schema_fingerprint(value: &mut JsonValue) {
+    let wire: ManifestWire =
+        serde_json::from_value(value.clone()).expect("test manifest must match the v7 wire shape");
+    value["schema_fingerprint"] =
+        JsonValue::String(schema_fingerprint(&wire).expect("test manifest must be serializable"));
+}
diff --git a/distributed_cli/src/client_compiler/manifest/projectors.rs b/distributed_cli/src/client_compiler/manifest/projectors.rs
new file mode 100644
index 00000000..63f2829e
--- /dev/null
+++ b/distributed_cli/src/client_compiler/manifest/projectors.rs
@@ -0,0 +1,424 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use super::*;
+
+pub(crate) fn canonicalize_projectors(
+    projectors: &mut [ManifestProjector],
+) -> Result<(), ClientCompileError> {
+    for projector in projectors.iter_mut() {
+        canonicalize_string_set(
+            &mut projector.facts,
+            &format!("projector `{}` fact", projector.name),
+        )?;
+        canonicalize_string_set(
+            &mut projector.models,
+            &format!("projector `{}` model", projector.name),
+        )?;
+        canonicalize_string_set(
+            &mut projector.dependencies,
+            &format!("projector `{}` dependency", projector.name),
+        )?;
+    }
+    projectors.sort_by(|left, right| left.name.cmp(&right.name));
+    Ok(())
+}
+
+pub(crate) fn validate_projectors(
+    projectors: &[ManifestProjector],
+    models: &BTreeMap<String, ManifestModel>,
+) -> Result<(), ClientCompileError> {
+    let mut names = BTreeSet::new();
+    for projector in projectors {
+        if projector.version != 1 {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.projector_version",
+                format!("projector `{}` must use version 1", projector.name),
+            ));
+        }
+        validate_nonempty(&projector.name, "manifest projector name")?;
+        if !names.insert(projector.name.as_str()) {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.duplicate_projector",
+                format!("duplicate manifest projector `{}`", projector.name),
+            ));
+        }
+        if projector.models.is_empty() {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.projector_inventory",
+                format!(
+                    "projection owner `{}` must declare at least one model",
+                    projector.name
+                ),
+            ));
+        }
+        if projector.facts.is_empty() && projector.causal_confirmation {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.projector_inventory",
+                format!(
+                    "direct-only projection owner `{}` cannot provide asynchronous confirmation",
+                    projector.name
+                ),
+            ));
+        }
+        let mut expected_dependencies = BTreeSet::new();
+        for model in &projector.models {
+            let Some(model_contract) = models.get(model) else {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.projector_model",
+                    format!(
+                        "projector `{}` references absent model `{model}`",
+                        projector.name
+                    ),
+                ));
+            };
+            expected_dependencies.insert(model_contract.source_table.as_str());
+        }
+        let actual_dependencies = projector
+            .dependencies
+            .iter()
+            .map(String::as_str)
+            .collect::<BTreeSet<_>>();
+        if actual_dependencies != expected_dependencies {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.projector_dependency",
+                format!(
+                    "projector `{}` dependencies must exactly cover its model source tables",
+                    projector.name
+                ),
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_direct_projections(
+    commands: &[ManifestCommand],
+    models: &BTreeMap<String, ManifestModel>,
+    projectors: &[ManifestProjector],
+) -> Result<BTreeSet<String>, ClientCompileError> {
+    let mut requiring_revalidation = BTreeSet::new();
+    for command in commands {
+        let consistency = command.extensions.consistency.kind;
+        let direct = command.extensions.direct_projection.as_ref();
+        match (consistency, direct) {
+            (ManifestConsistencyKind::Projected, None) => {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.direct_projection_required",
+                    format!(
+                        "manifest projected command `{}` requires exactly one direct_projection target",
+                        command.name
+                    ),
+                ));
+            }
+            (ManifestConsistencyKind::Projected, Some(direct)) => {
+                if validate_direct_projection(command, direct, models, projectors)? {
+                    requiring_revalidation.insert(command.name.clone());
+                }
+            }
+            (_, Some(_)) => {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.direct_projection_unexpected",
+                    format!(
+                        "manifest non-projected command `{}` cannot declare direct_projection",
+                        command.name
+                    ),
+                ));
+            }
+            (_, None) => {}
+        }
+    }
+    Ok(requiring_revalidation)
+}
+
+pub(crate) fn validate_direct_projection(
+    command: &ManifestCommand,
+    direct: &ManifestDirectProjection,
+    models: &BTreeMap<String, ManifestModel>,
+    projectors: &[ManifestProjector],
+) -> Result<bool, ClientCompileError> {
+    if direct.topology.version != 1 {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.direct_projection_topology",
+            format!(
+                "manifest command `{}` direct projection topology version must be 1",
+                command.name
+            ),
+        ));
+    }
+    validate_projection_name(
+        &direct.topology.name,
+        &format!(
+            "manifest command `{}` direct projection topology name",
+            command.name
+        ),
+    )?;
+    validate_hash(
+        &direct.topology.digest,
+        &format!(
+            "manifest command `{}` direct projection topology digest",
+            command.name
+        ),
+    )?;
+    validate_projection_epoch(
+        &direct.change_epoch,
+        &format!(
+            "manifest command `{}` direct projection change_epoch",
+            command.name
+        ),
+    )?;
+    validate_graphql_name(
+        &direct.model,
+        &format!(
+            "manifest command `{}` direct projection model",
+            command.name
+        ),
+    )?;
+    let model = models.get(&direct.model).ok_or_else(|| {
+        ClientCompileError::manifest(
+            "client.manifest.direct_projection_model",
+            format!(
+                "manifest command `{}` direct projection references absent model `{}`",
+                command.name, direct.model
+            ),
+        )
+    })?;
+    if !matches!(
+        &model.normalization,
+        ManifestNormalization::Normalized { .. }
+    ) {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.direct_projection_model",
+            format!(
+                "manifest command `{}` direct projection model `{}` has no complete authorized normalized identity",
+                command.name, direct.model
+            ),
+        ));
+    }
+    let ManifestCommandShape::Object { definition } = &command.output else {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.direct_projection_output",
+            format!(
+                "manifest projected command `{}` must return its exact model object",
+                command.name
+            ),
+        ));
+    };
+    if definition.name != model.typename || definition.fields.len() != model.fields.len() {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.direct_projection_output",
+            format!(
+                "manifest projected command `{}` output `{}` does not exactly match model `{}` typename `{}`",
+                command.name, definition.name, direct.model, model.typename
+            ),
+        ));
+    }
+    for field in &definition.fields {
+        let matches = model.fields.iter().any(|model_field| {
+            field.name == model_field.name
+                && field.type_name == model_field.scalar
+                && field.nullable == model_field.nullable
+                && !field.list
+                && !field.item_nullable
+                && field.codec.as_deref() == Some(model_field.codec.as_str())
+                && field.nested.is_none()
+        });
+        if !matches {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.direct_projection_output",
+                format!(
+                    "manifest projected command `{}` output field `{}.{}` differs from model `{}`",
+                    command.name, definition.name, field.name, direct.model
+                ),
+            ));
+        }
+    }
+
+    let visible_owners = projectors
+        .iter()
+        .filter(|projector| projector.models.iter().any(|model| model == &direct.model))
+        .collect::<Vec<_>>();
+    match visible_owners.as_slice() {
+        [] => {
+            if projectors
+                .iter()
+                .any(|projector| projector.name == direct.topology.name)
+            {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.direct_projection_owner",
+                    format!(
+                        "manifest command `{}` topology `{}` does not own model `{}`",
+                        command.name, direct.topology.name, direct.model
+                    ),
+                ));
+            }
+            // A role surface may intentionally omit the topology because it
+            // also owns denied models. The exact digest is sufficient and does
+            // not disclose those hidden model/fact/table identities.
+        }
+        [owner] if owner.name == direct.topology.name => {}
+        [owner] => {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.direct_projection_owner",
+                format!(
+                    "manifest command `{}` names topology `{}` but visible projector `{}` owns model `{}`",
+                    command.name, direct.topology.name, owner.name, direct.model
+                ),
+            ));
+        }
+        owners => {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.direct_projection_owner",
+                format!(
+                    "manifest command `{}` model `{}` has ambiguous visible projector ownership: {}",
+                    command.name,
+                    direct.model,
+                    owners
+                        .iter()
+                        .map(|owner| owner.name.as_str())
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                ),
+            ));
+        }
+    }
+
+    direct
+        .partition
+        .as_ref()
+        .map(|partition| validate_direct_projection_partition(command, partition))
+        .transpose()
+        .map(|requires_revalidation| requires_revalidation.unwrap_or(false))
+}
+
+pub(crate) fn validate_projection_name(value: &str, label: &str) -> Result<(), ClientCompileError> {
+    validate_nonempty(value, label)?;
+    if value.len() > 128
+        || value
+            .chars()
+            .any(|character| character.is_control() || character.is_whitespace())
+    {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.direct_projection_topology",
+            format!("{label} must be at most 128 bytes without whitespace or control characters"),
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_projection_epoch(
+    value: &str,
+    label: &str,
+) -> Result<(), ClientCompileError> {
+    validate_nonempty(value, label)?;
+    if value.len() > 128 || value.chars().any(char::is_control) {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.direct_projection_epoch",
+            format!("{label} must be at most 128 bytes without control characters"),
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_direct_projection_partition(
+    command: &ManifestCommand,
+    partition: &ManifestEffectExpression,
+) -> Result<bool, ClientCompileError> {
+    match partition {
+        ManifestEffectExpression::Input { path } => {
+            if path.is_empty() {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.direct_projection_partition",
+                    format!(
+                        "manifest command `{}` direct projection partition input path must not be empty",
+                        command.name
+                    ),
+                ));
+            }
+            validate_nonempty_strings(
+                path,
+                &format!(
+                    "manifest command `{}` direct projection partition input path",
+                    command.name
+                ),
+            )?;
+            let ManifestCommandShape::Object { definition } = &command.input else {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.direct_projection_partition",
+                    format!(
+                        "manifest command `{}` direct projection partition input requires a typed object input",
+                        command.name
+                    ),
+                ));
+            };
+            let mut current = definition;
+            for (index, segment) in path.iter().enumerate() {
+                let field = current
+                    .fields
+                    .iter()
+                    .find(|field| field.name == *segment)
+                    .ok_or_else(|| {
+                        ClientCompileError::manifest(
+                            "client.manifest.direct_projection_partition",
+                            format!(
+                                "manifest command `{}` direct projection references unknown input path `{}`",
+                                command.name,
+                                path.join(".")
+                            ),
+                        )
+                    })?;
+                if index + 1 == path.len() {
+                    if field.list || field.nested.is_some() {
+                        return Err(ClientCompileError::manifest(
+                            "client.manifest.direct_projection_partition",
+                            format!(
+                                "manifest command `{}` direct projection partition path `{}` must resolve to a scalar",
+                                command.name,
+                                path.join(".")
+                            ),
+                        ));
+                    }
+                    return Ok(false);
+                }
+                if field.list {
+                    return Err(ClientCompileError::manifest(
+                        "client.manifest.direct_projection_partition",
+                        format!(
+                            "manifest command `{}` direct projection partition path `{}` descends through a list",
+                            command.name,
+                            path.join(".")
+                        ),
+                    ));
+                }
+                current = field.nested.as_deref().ok_or_else(|| {
+                    ClientCompileError::manifest(
+                        "client.manifest.direct_projection_partition",
+                        format!(
+                            "manifest command `{}` direct projection partition path `{}` descends through a scalar",
+                            command.name,
+                            path.join(".")
+                        ),
+                    )
+                })?;
+            }
+            unreachable!("non-empty direct projection path resolves or returns an error")
+        }
+        ManifestEffectExpression::TrustedPreset { name } => {
+            let declared = command
+                .extensions
+                .trusted_presets
+                .iter()
+                .any(|descriptor| descriptor.name == *name && descriptor.codec == "string");
+            if !declared {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.direct_projection_partition",
+                    format!(
+                        "manifest command `{}` direct projection partition trusted preset `{name}` must declare the string codec",
+                        command.name
+                    ),
+                ));
+            }
+            Ok(false)
+        }
+        ManifestEffectExpression::Constant { .. } | ManifestEffectExpression::Null => Ok(false),
+    }
+}
diff --git a/distributed_cli/src/client_compiler/manifest/roots.rs b/distributed_cli/src/client_compiler/manifest/roots.rs
new file mode 100644
index 00000000..23f4b825
--- /dev/null
+++ b/distributed_cli/src/client_compiler/manifest/roots.rs
@@ -0,0 +1,288 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use super::*;
+
+pub(crate) fn canonicalize_root(root: &mut ManifestRoot) -> Result<(), ClientCompileError> {
+    canonicalize_arguments(
+        &mut root.arguments,
+        &format!("manifest root `{}` argument", root.name),
+    )?;
+    canonicalize_string_set(
+        &mut root.dependencies,
+        &format!("manifest root `{}` dependency", root.name),
+    )?;
+    if let Some(filter) = &mut root.filter {
+        canonicalize_filter_semantics(filter)?;
+    }
+    if let Some(order) = &mut root.order {
+        canonicalize_order_semantics(order)?;
+    }
+    if let Some(aggregate) = &mut root.aggregate {
+        canonicalize_aggregate_semantics(aggregate)?;
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_root_contract(
+    root: &ManifestRoot,
+    models: &BTreeMap<String, ManifestModel>,
+) -> Result<(), ClientCompileError> {
+    let expected_id = format!(
+        "{}:{}",
+        match root.operation {
+            RootOperation::Query => "query",
+            RootOperation::Subscription => "subscription",
+        },
+        root.name
+    );
+    if root.id != expected_id {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.root_id",
+            format!(
+                "root `{}` id must be `{expected_id}`, received `{}`",
+                root.name, root.id
+            ),
+        ));
+    }
+    validate_graphql_name(&root.name, "manifest root name")?;
+    let model = models.get(&root.model).ok_or_else(|| {
+        ClientCompileError::manifest(
+            "client.manifest.root_model",
+            format!(
+                "manifest root `{}` references missing model `{}`",
+                root.name, root.model
+            ),
+        )
+    })?;
+    validate_filter_argument_type(
+        &root.arguments,
+        model,
+        &format!("manifest root `{}`", root.name),
+    )?;
+    validate_nonempty_strings(
+        &root.dependencies,
+        &format!("manifest root `{}` dependency", root.name),
+    )?;
+    require_dependency(
+        &root.dependencies,
+        &model.source_table,
+        &format!("manifest root {}", root.name),
+    )?;
+    if root.operation == RootOperation::Subscription && root.kind != RootKind::List {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.subscription_kind",
+            format!(
+                "subscription root `{}` must use list cardinality in manifest v7",
+                root.name
+            ),
+        ));
+    }
+    if root.operation == RootOperation::Subscription && !root.live {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.subscription_live",
+            format!("subscription root `{}` must be marked live", root.name),
+        ));
+    }
+
+    let has_filter_argument = root
+        .arguments
+        .iter()
+        .any(|argument| argument.kind == ManifestArgumentKind::Filter);
+    let has_order_argument = root
+        .arguments
+        .iter()
+        .any(|argument| argument.kind == ManifestArgumentKind::Order);
+    let has_limit_argument = root
+        .arguments
+        .iter()
+        .any(|argument| argument.kind == ManifestArgumentKind::Limit);
+    let has_offset_argument = root
+        .arguments
+        .iter()
+        .any(|argument| argument.kind == ManifestArgumentKind::Offset);
+    if root.filter.is_some() != has_filter_argument
+        || root.order.is_some() != has_order_argument
+        || root.pagination.is_some() != (has_limit_argument && has_offset_argument)
+    {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.root_arguments",
+            format!(
+                "root `{}` arguments do not match its filter/order/pagination semantics",
+                root.name
+            ),
+        ));
+    }
+    if let Some(filter) = &root.filter {
+        validate_filter_semantics(filter, model, models)?;
+    }
+    if let Some(order) = &root.order {
+        validate_order_semantics(order, model)?;
+    }
+    match root.kind {
+        RootKind::List => {
+            root.filter.as_ref().ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.manifest.root_filter",
+                    format!("list root `{}` requires filter semantics", root.name),
+                )
+            })?;
+            root.order.as_ref().ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.manifest.root_order",
+                    format!("list root `{}` requires order semantics", root.name),
+                )
+            })?;
+            validate_pagination(
+                root.pagination.as_ref().ok_or_else(|| {
+                    ClientCompileError::manifest(
+                        "client.manifest.root_pagination",
+                        format!("list root `{}` requires pagination semantics", root.name),
+                    )
+                })?,
+                &format!("root `{}`", root.name),
+            )?;
+            if root.aggregate.is_some() {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.root_aggregate",
+                    format!(
+                        "list root `{}` cannot declare aggregate semantics",
+                        root.name
+                    ),
+                ));
+            }
+        }
+        RootKind::ByPk => {
+            if root.pagination.is_some()
+                || root.aggregate.is_some()
+                || root.filter.is_some()
+                || root.order.is_some()
+            {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.by_pk_semantics",
+                    format!(
+                        "by-pk root `{}` cannot declare filter, order, pagination, or aggregate semantics",
+                        root.name
+                    ),
+                ));
+            }
+            if root.arguments.iter().any(|argument| {
+                argument.kind != ManifestArgumentKind::PrimaryKey
+                    || argument.nullable
+                    || argument.list
+            }) {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.by_pk_arguments",
+                    format!(
+                        "by-pk root `{}` may contain only non-null scalar primary-key arguments",
+                        root.name
+                    ),
+                ));
+            }
+        }
+        RootKind::Aggregate => {
+            if root.pagination.is_some() || root.order.is_some() {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.aggregate_root_semantics",
+                    format!(
+                        "aggregate root `{}` cannot declare order or pagination semantics",
+                        root.name
+                    ),
+                ));
+            }
+            validate_aggregate_semantics(
+                root.aggregate.as_ref().ok_or_else(|| {
+                    ClientCompileError::manifest(
+                        "client.manifest.aggregate_root",
+                        format!(
+                            "aggregate root `{}` requires aggregate semantics",
+                            root.name
+                        ),
+                    )
+                })?,
+                model,
+            )?;
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_unique_arguments(
+    root: &ManifestRoot,
+    scalar_codecs: &BTreeMap<String, String>,
+) -> Result<(), ClientCompileError> {
+    validate_unique_arguments_for(
+        &root.arguments,
+        scalar_codecs,
+        &format!("manifest root `{}`", root.name),
+    )
+}
+
+pub(crate) fn validate_unique_arguments_for(
+    arguments: &[ManifestArgument],
+    scalar_codecs: &BTreeMap<String, String>,
+    owner: &str,
+) -> Result<(), ClientCompileError> {
+    let mut names = BTreeSet::new();
+    let mut kinds = BTreeSet::new();
+    for argument in arguments {
+        validate_graphql_name(&argument.name, "manifest argument")?;
+        validate_graphql_name(&argument.type_name, "manifest argument type")?;
+        if !names.insert(argument.name.as_str()) {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.duplicate_argument",
+                format!("{owner} repeats argument `{}`", argument.name),
+            ));
+        }
+        if argument.kind != ManifestArgumentKind::PrimaryKey && !kinds.insert(argument.kind) {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.duplicate_argument_kind",
+                format!("{owner} repeats {:?} argument semantics", argument.kind),
+            ));
+        }
+        if matches!(
+            argument.kind,
+            ManifestArgumentKind::Limit | ManifestArgumentKind::Offset
+        ) && (argument.list || argument.type_name != "Int")
+        {
+            return Err(ClientCompileError::manifest(
+                "client.manifest.pagination_argument",
+                format!(
+                    "{owner} pagination argument `{}` must use scalar Int",
+                    argument.name
+                ),
+            ));
+        }
+        match (scalar_codecs.get(&argument.type_name), &argument.codec) {
+            (Some(expected), Some(actual)) if actual == expected => {}
+            (Some(expected), Some(actual)) => {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.argument_codec",
+                    format!(
+                        "{owner} argument `{}` codec `{actual}` does not match scalar `{}` inventory codec `{expected}`",
+                        argument.name, argument.type_name
+                    ),
+                ));
+            }
+            (Some(_), None) => {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.argument_codec",
+                    format!(
+                        "{owner} scalar argument `{}` is missing its codec",
+                        argument.name
+                    ),
+                ));
+            }
+            (None, Some(actual)) => {
+                return Err(ClientCompileError::manifest(
+                    "client.manifest.argument_codec",
+                    format!(
+                        "{owner} argument `{}` declares codec `{actual}` for non-scalar type `{}`",
+                        argument.name, argument.type_name
+                    ),
+                ));
+            }
+            (None, None) => {}
+        }
+    }
+    Ok(())
+}
diff --git a/distributed_cli/src/client_compiler/manifest/types.rs b/distributed_cli/src/client_compiler/manifest/types.rs
new file mode 100644
index 00000000..f8c338b1
--- /dev/null
+++ b/distributed_cli/src/client_compiler/manifest/types.rs
@@ -0,0 +1,791 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value as JsonValue;
+
+use super::canonical_json_value;
+
+#[derive(Clone, Debug)]
+pub(crate) struct ClientManifest {
+    pub(crate) service_id: String,
+    pub(crate) surface: ManifestSurface,
+    pub(crate) schema_fingerprint: String,
+    pub(crate) protocol_fingerprint: String,
+    pub(crate) execution: ManifestExecutionLimits,
+    pub(crate) capabilities: ManifestCapabilities,
+    pub(crate) scalar_codecs: BTreeMap<String, String>,
+    pub(crate) models: BTreeMap<String, ManifestModel>,
+    pub(crate) roots: BTreeMap<(RootOperation, String), ManifestRoot>,
+    pub(crate) commands: Vec<ManifestCommand>,
+    /// Exact scope-wide descriptor inventory derived from command-local
+    /// presets plus every client-visible row-policy claim/column codec.
+    pub(crate) trusted_presets: Vec<ManifestTrustedPresetDescriptor>,
+    pub(crate) commands_requiring_revalidation: BTreeSet<String>,
+    pub(crate) protocol_operations: ManifestProtocolOperations,
+    pub(crate) projectors: Vec<ManifestProjector>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestExecutionLimits {
+    pub(crate) max_depth: u64,
+    pub(crate) max_complexity: u64,
+    pub(crate) max_bool_width: u64,
+    pub(crate) max_in_list: u64,
+    pub(crate) complexity: ManifestComplexityWeights,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestComplexityWeights {
+    pub(crate) version: u32,
+    pub(crate) scalar: u64,
+    pub(crate) belongs_to: u64,
+    pub(crate) has_many: u64,
+    pub(crate) m2m: u64,
+    pub(crate) aggregate: u64,
+    pub(crate) list_root: u64,
+    pub(crate) by_pk: u64,
+    pub(crate) list_fanout: u64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub(crate) enum ManifestSurface {
+    Role { name: String },
+    Application { name: String, roles: Vec<String> },
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestCapabilities {
+    pub(crate) live_queries: bool,
+    pub(crate) record_revisions: bool,
+    pub(crate) tombstones: bool,
+    pub(crate) causal_receipts: bool,
+    pub(crate) live_resume: bool,
+    pub(crate) query_fallback: String,
+    pub(crate) cache_scope: bool,
+    pub(crate) confirmed_persistence: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestScalarCodec {
+    pub(crate) scalar: String,
+    pub(crate) codec: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestModel {
+    pub(crate) id: String,
+    pub(crate) typename: String,
+    pub(crate) source_table: String,
+    pub(crate) dependencies: Vec<String>,
+    pub(crate) normalization: ManifestNormalization,
+    pub(crate) fields: Vec<ManifestField>,
+    pub(crate) relationships: Vec<ManifestRelationship>,
+    pub(crate) filter_input: ManifestFilterInput,
+    pub(crate) row_policy: ManifestRowPolicy,
+    pub(crate) record_revisions: bool,
+    pub(crate) tombstones: bool,
+}
+
+impl ManifestModel {
+    pub(crate) fn field(&self, name: &str) -> Option<&ManifestField> {
+        self.fields.iter().find(|field| field.name == name)
+    }
+
+    pub(crate) fn relationship(&self, name: &str) -> Option<&ManifestRelationship> {
+        self.relationships
+            .iter()
+            .find(|relationship| relationship.name == name)
+    }
+
+    pub(crate) fn identity(&self) -> Option<&[ManifestKeyField]> {
+        match &self.normalization {
+            ManifestNormalization::Normalized { fields, .. } => Some(fields),
+            ManifestNormalization::Embedded => None,
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub(crate) enum ManifestNormalization {
+    Normalized {
+        fields: Vec<ManifestKeyField>,
+        encoding: String,
+    },
+    Embedded,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestKeyField {
+    pub(crate) name: String,
+    pub(crate) codec: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestField {
+    pub(crate) name: String,
+    pub(crate) scalar: String,
+    pub(crate) codec: String,
+    pub(crate) nullable: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestFilterInput {
+    pub(crate) type_name: String,
+    pub(crate) fields: Vec<ManifestFilterField>,
+    pub(crate) relationships: Vec<ManifestFilterInputRelationship>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestFilterInputRelationship {
+    pub(crate) field: String,
+    pub(crate) target_type: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub(crate) enum ManifestRowPolicy {
+    Unrestricted,
+    Predicate { expression: ManifestFilterExpr },
+    ServerOnly,
+}
+
+#[derive(Clone, Debug, PartialEq, Deserialize)]
+#[serde(tag = "kind", content = "value", rename_all = "snake_case")]
+pub(crate) enum ManifestFilterExpr {
+    And(Vec<ManifestFilterExpr>),
+    Or(Vec<ManifestFilterExpr>),
+    Not(Box<ManifestFilterExpr>),
+    Cmp {
+        column: String,
+        op: ManifestCmpOp,
+        rhs: ManifestOperand,
+    },
+    In {
+        column: String,
+        values: Vec<ManifestOperand>,
+        negated: bool,
+    },
+    IsNull {
+        column: String,
+        is_null: bool,
+    },
+    Rel {
+        field: String,
+        predicate: Box<ManifestFilterExpr>,
+    },
+}
+
+impl Serialize for ManifestFilterExpr {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        use serde_json::json;
+
+        fn wire_value(expression: &ManifestFilterExpr) -> JsonValue {
+            match expression {
+                ManifestFilterExpr::And(items) => json!({
+                    "kind": "and",
+                    "value": items.iter().map(wire_value).collect::<Vec<_>>()
+                }),
+                ManifestFilterExpr::Or(items) => json!({
+                    "kind": "or",
+                    "value": items.iter().map(wire_value).collect::<Vec<_>>()
+                }),
+                ManifestFilterExpr::Not(item) => {
+                    json!({"kind": "not", "value": wire_value(item)})
+                }
+                ManifestFilterExpr::Cmp { column, op, rhs } => json!({
+                    "kind": "cmp",
+                    "value": {"column": column, "op": op, "rhs": rhs}
+                }),
+                ManifestFilterExpr::In {
+                    column,
+                    values,
+                    negated,
+                } => json!({
+                    "kind": "in",
+                    "value": {
+                        "column": column,
+                        "values": values,
+                        "negated": negated
+                    }
+                }),
+                ManifestFilterExpr::IsNull { column, is_null } => json!({
+                    "kind": "is_null",
+                    "value": {"column": column, "is_null": is_null}
+                }),
+                ManifestFilterExpr::Rel { field, predicate } => json!({
+                    "kind": "rel",
+                    "value": {"field": field, "predicate": wire_value(predicate)}
+                }),
+            }
+        }
+
+        canonical_json_value(wire_value(self)).serialize(serializer)
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", content = "value", rename_all = "snake_case")]
+pub(crate) enum ManifestOperand {
+    Lit(ManifestLitValue),
+    Claim(ManifestClaimRef),
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", content = "value", rename_all = "snake_case")]
+pub(crate) enum ManifestLitValue {
+    String(String),
+    I64(i64),
+    F64(f64),
+    Bool(bool),
+    Json(JsonValue),
+    Null,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestClaimRef {
+    pub(crate) header: String,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ManifestCmpOp {
+    Eq,
+    Neq,
+    Gt,
+    Gte,
+    Lt,
+    Lte,
+    Like,
+    Ilike,
+    Contains,
+    ContainedIn,
+    HasKey,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestRelationship {
+    pub(crate) name: String,
+    pub(crate) target_model: String,
+    pub(crate) target_typename: String,
+    pub(crate) kind: ManifestRelationshipKind,
+    pub(crate) list: bool,
+    pub(crate) nullable: bool,
+    pub(crate) arguments: Vec<ManifestArgument>,
+    pub(crate) key_mapping: ManifestRelationshipKeyMapping,
+    pub(crate) maintenance: ManifestRelationshipMaintenance,
+    pub(crate) dependencies: Vec<String>,
+    pub(crate) filter: Option<ManifestFilterSemantics>,
+    pub(crate) order: Option<ManifestOrderSemantics>,
+    pub(crate) pagination: Option<ManifestPagination>,
+    pub(crate) aggregate: Option<ManifestRelationshipAggregate>,
+    pub(crate) live: bool,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ManifestRelationshipKind {
+    HasMany,
+    BelongsTo,
+    ManyToMany,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub(crate) enum ManifestRelationshipKeyMapping {
+    Direct {
+        local: Vec<String>,
+        remote: Vec<String>,
+    },
+    Through {
+        local: Vec<String>,
+        remote: Vec<String>,
+        table: String,
+        source_foreign_key: String,
+        target_foreign_key: String,
+    },
+    ThroughOpaque {
+        local: Vec<String>,
+        remote: Vec<String>,
+        dependency: String,
+    },
+    Embedded,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ManifestRelationshipMaintenance {
+    Local,
+    Revalidate,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestRelationshipAggregate {
+    pub(crate) name: String,
+    pub(crate) arguments: Vec<ManifestArgument>,
+    pub(crate) semantics: ManifestAggregateSemantics,
+    pub(crate) dependencies: Vec<String>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum RootOperation {
+    Query,
+    Subscription,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum RootKind {
+    List,
+    ByPk,
+    Aggregate,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestRoot {
+    pub(crate) id: String,
+    pub(crate) operation: RootOperation,
+    pub(crate) name: String,
+    pub(crate) kind: RootKind,
+    pub(crate) model: String,
+    pub(crate) arguments: Vec<ManifestArgument>,
+    pub(crate) filter: Option<ManifestFilterSemantics>,
+    pub(crate) order: Option<ManifestOrderSemantics>,
+    pub(crate) pagination: Option<ManifestPagination>,
+    pub(crate) aggregate: Option<ManifestAggregateSemantics>,
+    pub(crate) dependencies: Vec<String>,
+    pub(crate) live: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestArgument {
+    pub(crate) name: String,
+    pub(crate) kind: ManifestArgumentKind,
+    pub(crate) type_name: String,
+    pub(crate) nullable: bool,
+    pub(crate) list: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) codec: Option<String>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ManifestArgumentKind {
+    Filter,
+    Order,
+    Limit,
+    Offset,
+    PrimaryKey,
+}
+
+impl ManifestArgument {
+    pub(crate) fn graphql_type(&self) -> String {
+        let base = if self.list {
+            format!("[{}!]", self.type_name)
+        } else {
+            self.type_name.clone()
+        };
+        if self.nullable {
+            base
+        } else {
+            format!("{base}!")
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestFilterSemantics {
+    pub(crate) fields: Vec<ManifestFilterField>,
+    pub(crate) relationships: Vec<String>,
+    pub(crate) row_policy: ManifestRowPolicy,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestFilterField {
+    pub(crate) name: String,
+    pub(crate) operators: Vec<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestOrderSemantics {
+    pub(crate) fields: Vec<String>,
+    pub(crate) values: Vec<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestPagination {
+    pub(crate) kind: String,
+    pub(crate) default_limit: u64,
+    pub(crate) max_limit: u64,
+    pub(crate) coverage: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestAggregateSemantics {
+    pub(crate) wrapper_typename: String,
+    pub(crate) fields_typename: String,
+    pub(crate) nodes_pagination: ManifestPagination,
+    pub(crate) count: bool,
+    pub(crate) nodes: bool,
+    pub(crate) sum: Vec<String>,
+    pub(crate) avg: Vec<String>,
+    pub(crate) min: Vec<String>,
+    pub(crate) max: Vec<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestCommand {
+    pub(crate) version: u32,
+    pub(crate) name: String,
+    pub(crate) mutation_field: String,
+    pub(crate) grants: Vec<String>,
+    pub(crate) input: ManifestCommandShape,
+    pub(crate) output: ManifestCommandShape,
+    pub(crate) operation: String,
+    pub(crate) operation_hash: String,
+    pub(crate) extensions: ManifestCommandExtensions,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub(crate) enum ManifestCommandShape {
+    None,
+    Object { definition: ManifestTypeDef },
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestTypeDef {
+    pub(crate) name: String,
+    pub(crate) fields: Vec<ManifestTypeField>,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestTypeField {
+    pub(crate) name: String,
+    pub(crate) type_name: String,
+    pub(crate) nullable: bool,
+    pub(crate) list: bool,
+    pub(crate) item_nullable: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) codec: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) nested: Option<Box<ManifestTypeDef>>,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestCommandExtensions {
+    pub(crate) version: u32,
+    pub(crate) consistency: ManifestCommandConsistency,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) direct_projection: Option<ManifestDirectProjection>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) input_defaults: Option<ManifestInputDefaults>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) effects: Option<ManifestEffects>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) confirmations: Option<ManifestConfirmations>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub(crate) trusted_presets: Vec<ManifestTrustedPresetDescriptor>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestTrustedPresetDescriptor {
+    pub(crate) name: String,
+    pub(crate) codec: String,
+}
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestCommandConsistency {
+    pub(crate) version: u32,
+    pub(crate) kind: ManifestConsistencyKind,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestDirectProjection {
+    pub(crate) topology: ManifestProjectionTopologyIdentity,
+    pub(crate) model: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) partition: Option<ManifestEffectExpression>,
+    pub(crate) change_epoch: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestProjectionTopologyIdentity {
+    pub(crate) version: u32,
+    pub(crate) name: String,
+    pub(crate) digest: String,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ManifestConsistencyKind {
+    Accepted,
+    Fact,
+    Projected,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestInputDefaults {
+    pub(crate) version: u32,
+    pub(crate) defaults: Vec<ManifestInputDefault>,
+}
+
+impl Serialize for ManifestInputDefaults {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        #[derive(Serialize)]
+        struct Wire<'a> {
+            version: u32,
+            defaults: &'a [JsonValue],
+        }
+
+        let defaults = self
+            .defaults
+            .iter()
+            .map(serde_json::to_value)
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(serde::ser::Error::custom)?;
+        Wire {
+            version: self.version,
+            defaults: &defaults,
+        }
+        .serialize(serializer)
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestInputDefault {
+    pub(crate) path: Vec<String>,
+    pub(crate) generator: ManifestInputDefaultGenerator,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ManifestInputDefaultGenerator {
+    UuidV7,
+    Ulid,
+}
+
+#[derive(Clone, Debug, PartialEq, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestEffects {
+    pub(crate) version: u32,
+    pub(crate) operations: Vec<ManifestEffect>,
+    pub(crate) fallback: ManifestRevalidationFallback,
+}
+
+impl Serialize for ManifestEffects {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        #[derive(Serialize)]
+        struct Wire<'a> {
+            version: u32,
+            operations: &'a [JsonValue],
+            fallback: ManifestRevalidationFallback,
+        }
+
+        let operations = self
+            .operations
+            .iter()
+            .map(serde_json::to_value)
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(serde::ser::Error::custom)?;
+        Wire {
+            version: self.version,
+            operations: &operations,
+            fallback: self.fallback,
+        }
+        .serialize(serializer)
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub(crate) enum ManifestEffect {
+    Upsert {
+        model: String,
+        key: ManifestEffectKey,
+        fields: Vec<ManifestEffectField>,
+    },
+    Patch {
+        model: String,
+        key: ManifestEffectKey,
+        fields: Vec<ManifestEffectField>,
+    },
+    Delete {
+        model: String,
+        key: ManifestEffectKey,
+    },
+    Link {
+        relationship: ManifestEffectRelationship,
+        source: ManifestEffectKey,
+        target: ManifestEffectKey,
+    },
+    Unlink {
+        relationship: ManifestEffectRelationship,
+        source: ManifestEffectKey,
+        target: ManifestEffectKey,
+    },
+    InvalidateModel {
+        model: String,
+    },
+    InvalidateRelationship {
+        relationship: ManifestEffectRelationship,
+        source: ManifestEffectKey,
+    },
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestEffectRelationship {
+    pub(crate) source_model: String,
+    pub(crate) field: String,
+    pub(crate) target_model: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestEffectKey {
+    pub(crate) fields: Vec<ManifestEffectField>,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestEffectField {
+    pub(crate) field: String,
+    pub(crate) value: ManifestEffectExpression,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub(crate) enum ManifestEffectExpression {
+    Input { path: Vec<String> },
+    TrustedPreset { name: String },
+    Constant { value: JsonValue },
+    Null,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ManifestRevalidationFallback {
+    Revalidate,
+}
+
+#[derive(Clone, Debug, PartialEq, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestConfirmations {
+    pub(crate) version: u32,
+    pub(crate) kind: ManifestConfirmationKind,
+    pub(crate) expected: Vec<ManifestConfirmation>,
+    pub(crate) fallback: ManifestRevalidationFallback,
+}
+
+impl Serialize for ManifestConfirmations {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        #[derive(Serialize)]
+        struct Wire<'a> {
+            version: u32,
+            kind: ManifestConfirmationKind,
+            expected: &'a [JsonValue],
+            fallback: ManifestRevalidationFallback,
+        }
+
+        let expected = self
+            .expected
+            .iter()
+            .map(serde_json::to_value)
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(serde::ser::Error::custom)?;
+        Wire {
+            version: self.version,
+            kind: self.kind,
+            expected: &expected,
+            fallback: self.fallback,
+        }
+        .serialize(serializer)
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum ManifestConfirmationKind {
+    Finite,
+    Unavailable,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestConfirmation {
+    pub(crate) projector: String,
+    pub(crate) model: String,
+    pub(crate) key: ManifestEffectKey,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) partition: Option<ManifestEffectExpression>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestProtocolOperations {
+    pub(crate) version: u32,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) command_status: Option<ManifestProtocolOperation>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestProtocolOperation {
+    pub(crate) name: String,
+    pub(crate) operation: String,
+    pub(crate) operation_hash: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct ManifestProjector {
+    pub(crate) version: u32,
+    pub(crate) name: String,
+    pub(crate) facts: Vec<String>,
+    pub(crate) models: Vec<String>,
+    pub(crate) dependencies: Vec<String>,
+    pub(crate) causal_confirmation: bool,
+}
diff --git a/distributed_cli/src/client_compiler/manifest/util.rs b/distributed_cli/src/client_compiler/manifest/util.rs
new file mode 100644
index 00000000..feda806b
--- /dev/null
+++ b/distributed_cli/src/client_compiler/manifest/util.rs
@@ -0,0 +1,92 @@
+use std::collections::BTreeMap;
+
+use serde_json::Value as JsonValue;
+use sha2::{Digest, Sha256};
+
+use super::*;
+
+pub(crate) fn validate_exact_operation_hash(
+    operation: &str,
+    expected: &str,
+    label: &str,
+) -> Result<(), ClientCompileError> {
+    validate_hash(expected, &format!("{label} operation hash"))?;
+    let actual = hash_bytes(operation.as_bytes());
+    if actual != expected {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.operation_hash",
+            format!("{label} operation hash mismatch: expected `{expected}`, computed `{actual}`"),
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn hash_bytes(bytes: &[u8]) -> String {
+    let digest = Sha256::digest(bytes);
+    format!("sha256:{digest:x}")
+}
+
+pub(crate) fn validate_hash(value: &str, label: &str) -> Result<(), ClientCompileError> {
+    if value.len() != 71
+        || !value.starts_with("sha256:")
+        || !value[7..]
+            .bytes()
+            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+    {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.hash",
+            format!("{label} must be a lowercase sha256 fingerprint"),
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_nonempty(value: &str, label: &str) -> Result<(), ClientCompileError> {
+    if value.trim().is_empty() {
+        return Err(ClientCompileError::manifest(
+            "client.manifest.empty",
+            format!("{label} must not be empty"),
+        ));
+    }
+    Ok(())
+}
+
+pub(crate) fn canonical_json_value(value: JsonValue) -> JsonValue {
+    match value {
+        JsonValue::Array(values) => {
+            JsonValue::Array(values.into_iter().map(canonical_json_value).collect())
+        }
+        JsonValue::Object(values) => {
+            let sorted = values
+                .into_iter()
+                .map(|(key, value)| (key, canonical_json_value(value)))
+                .collect::<BTreeMap<_, _>>();
+            JsonValue::Object(sorted.into_iter().collect())
+        }
+        scalar => scalar,
+    }
+}
+
+#[cfg(test)]
+mod canonical_wire_tests {
+    use super::super::{ManifestFilterExpr, ManifestLitValue, ManifestOperand};
+
+    #[test]
+    fn filter_expr_serialization_is_canonical_across_map_backends() {
+        let mut value = serde_json::Map::new();
+        value.insert("z".into(), serde_json::json!(2));
+        value.insert("a".into(), serde_json::json!(1));
+        let expression = ManifestFilterExpr::In {
+            column: "metadata".into(),
+            values: vec![ManifestOperand::Lit(ManifestLitValue::Json(
+                serde_json::Value::Object(value),
+            ))],
+            negated: false,
+        };
+
+        assert_eq!(
+            serde_json::to_string(&expression).unwrap(),
+            r#"{"kind":"in","value":{"column":"metadata","negated":false,"values":[{"kind":"lit","value":{"kind":"json","value":{"a":1,"z":2}}}]}}"#
+        );
+    }
+}
diff --git a/distributed_cli/src/client_compiler/mod.rs b/distributed_cli/src/client_compiler/mod.rs
new file mode 100644
index 00000000..1e1bca7a
--- /dev/null
+++ b/distributed_cli/src/client_compiler/mod.rs
@@ -0,0 +1,420 @@
+//! Pure, framework-neutral compiler for Distributed client artifacts.
+//!
+//! This module deliberately owns no filesystem or glob behavior. Callers load
+//! one role/application-selected manifest and the colocated GraphQL documents,
+//! then decide how to write or check the returned files.
+
+mod command_manifest;
+mod graphql;
+mod manifest;
+mod render;
+
+#[cfg(test)]
+mod command_manifest_tests;
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value as JsonValue;
+
+use graphql::{compile_document, CompiledOperation};
+use manifest::ClientManifest;
+use render::render_project;
+
+/// Complete input to one deterministic client compilation.
+#[derive(Clone, Debug)]
+pub struct ClientCompileInput {
+    /// The role/application-selected Distributed client manifest.
+    pub manifest: JsonValue,
+    /// Exact authorization surface expected by the caller.
+    pub selector: ClientSurfaceSelector,
+    /// GraphQL sources. Filesystem traversal and glob expansion stay in the CLI.
+    pub documents: Vec<ClientDocument>,
+    /// Explicit fallback for `@load` documents outside the conventional route
+    /// location. Equivalent CLI syntax is `--route Operation=/route-id`.
+    pub route_registrations: Vec<ClientRouteRegistration>,
+}
+
+impl ClientCompileInput {
+    pub fn new(
+        manifest: JsonValue,
+        selector: ClientSurfaceSelector,
+        documents: Vec<ClientDocument>,
+    ) -> Self {
+        Self {
+            manifest,
+            selector,
+            documents,
+            route_registrations: Vec::new(),
+        }
+    }
+
+    pub fn with_route_registrations(
+        mut self,
+        route_registrations: Vec<ClientRouteRegistration>,
+    ) -> Self {
+        self.route_registrations = route_registrations;
+        self
+    }
+}
+
+/// Explicit client authorization surface. This value only verifies manifest
+/// provenance; it can never relabel a broader manifest.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum ClientSurfaceSelector {
+    Role { name: String },
+    Application { name: String },
+}
+
+impl ClientSurfaceSelector {
+    pub fn role(name: impl Into<String>) -> Self {
+        Self::Role { name: name.into() }
+    }
+
+    pub fn application(name: impl Into<String>) -> Self {
+        Self::Application { name: name.into() }
+    }
+}
+
+/// One already-loaded GraphQL source.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ClientDocument {
+    pub path: String,
+    pub source: String,
+}
+
+impl ClientDocument {
+    pub fn new(path: impl Into<String>, source: impl Into<String>) -> Self {
+        Self {
+            path: path.into(),
+            source: source.into(),
+        }
+    }
+}
+
+/// Explicit `@load` route fallback, keyed by the GraphQL operation name.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ClientRouteRegistration {
+    pub operation: String,
+    pub route: String,
+}
+
+impl ClientRouteRegistration {
+    pub fn new(operation: impl Into<String>, route: impl Into<String>) -> Self {
+        Self {
+            operation: operation.into(),
+            route: route.into(),
+        }
+    }
+}
+
+/// Pure compiler output. `files` is sorted by portable relative path.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GeneratedClientProject {
+    pub files: Vec<GeneratedClientFile>,
+    pub operations: Vec<GeneratedOperationSummary>,
+    pub routes: Vec<GeneratedRoutePlan>,
+    pub schema_fingerprint: String,
+    pub protocol_fingerprint: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GeneratedClientFile {
+    pub path: String,
+    pub contents: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct GeneratedOperationSummary {
+    pub name: String,
+    pub source_path: String,
+    pub module_path: String,
+    pub export_name: String,
+    pub operation_hash: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub live_operation_hash: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct GeneratedRoutePlan {
+    pub operation: String,
+    pub route: String,
+    pub source_path: String,
+    pub discovery: ClientRouteDiscovery,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ClientRouteDiscovery {
+    Convention,
+    Explicit,
+}
+
+/// Stable, source-located error returned for every unsupported or invalid
+/// construct. The first compiler slice never silently weakens an operation.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ClientCompileError {
+    pub code: &'static str,
+    pub message: String,
+    pub source: Option<ClientSourceLocation>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ClientSourceLocation {
+    pub path: String,
+    pub line: usize,
+    pub column: usize,
+}
+
+impl ClientCompileError {
+    pub(crate) fn manifest(code: &'static str, message: impl Into<String>) -> Self {
+        Self {
+            code,
+            message: message.into(),
+            source: None,
+        }
+    }
+
+    pub(crate) fn source(
+        code: &'static str,
+        message: impl Into<String>,
+        path: &str,
+        line: usize,
+        column: usize,
+    ) -> Self {
+        Self {
+            code,
+            message: message.into(),
+            source: Some(ClientSourceLocation {
+                path: path.to_string(),
+                line,
+                column,
+            }),
+        }
+    }
+}
+
+impl fmt::Display for ClientCompileError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        if let Some(source) = &self.source {
+            write!(
+                formatter,
+                "{}:{}:{}: {} [{}]",
+                source.path, source.line, source.column, self.message, self.code
+            )
+        } else {
+            write!(formatter, "{} [{}]", self.message, self.code)
+        }
+    }
+}
+
+impl std::error::Error for ClientCompileError {}
+
+/// Compile one selected manifest and its colocated GraphQL sources.
+pub fn compile_client(
+    mut input: ClientCompileInput,
+) -> Result<GeneratedClientProject, ClientCompileError> {
+    let manifest = ClientManifest::parse(input.manifest, &input.selector)?;
+
+    if input.documents.is_empty() {
+        return Err(ClientCompileError::manifest(
+            "client.documents.empty",
+            "client compilation requires at least one GraphQL document",
+        ));
+    }
+
+    for document in &mut input.documents {
+        document.path = normalize_source_path(&document.path)?;
+    }
+    input.documents.sort_by(|left, right| {
+        left.path
+            .cmp(&right.path)
+            .then_with(|| left.source.cmp(&right.source))
+    });
+    for pair in input.documents.windows(2) {
+        if pair[0].path == pair[1].path {
+            return Err(ClientCompileError::manifest(
+                "client.documents.duplicate_path",
+                format!("duplicate GraphQL document path `{}`", pair[0].path),
+            ));
+        }
+    }
+
+    let registrations = validate_route_registrations(input.route_registrations)?;
+    let mut used_registrations = BTreeSet::new();
+    let mut operations = Vec::with_capacity(input.documents.len());
+    for document in &input.documents {
+        let operation = compile_document(document, &manifest, &registrations)?;
+        if operation.route.as_ref().is_some_and(|route| {
+            route.discovery == ClientRouteDiscovery::Explicit
+                && used_registrations.insert(operation.name.clone())
+        }) {
+            // Insert performed by the predicate.
+        }
+        operations.push(operation);
+    }
+
+    operations.sort_by(|left, right| {
+        left.name
+            .cmp(&right.name)
+            .then_with(|| left.source_path.cmp(&right.source_path))
+    });
+    let mut names = BTreeMap::<&str, &str>::new();
+    let mut modules = BTreeMap::<&str, &str>::new();
+    for operation in &operations {
+        if let Some(previous_path) =
+            names.insert(operation.name.as_str(), operation.source_path.as_str())
+        {
+            return Err(ClientCompileError::manifest(
+                "client.operation.duplicate_name",
+                format!(
+                    "duplicate GraphQL operation `{}` in `{}` and `{}`",
+                    operation.name, previous_path, operation.source_path
+                ),
+            ));
+        }
+        if let Some(previous_name) =
+            modules.insert(operation.module_path.as_str(), operation.name.as_str())
+        {
+            return Err(ClientCompileError::manifest(
+                "client.operation.module_collision",
+                format!(
+                    "operations `{}` and `{}` collide at generated module `{}`",
+                    previous_name, operation.name, operation.module_path
+                ),
+            ));
+        }
+    }
+
+    for operation in registrations.keys() {
+        if !operations
+            .iter()
+            .any(|candidate| &candidate.name == operation)
+        {
+            return Err(ClientCompileError::manifest(
+                "client.route.unknown_registration",
+                format!("explicit route registration names unknown operation `{operation}`"),
+            ));
+        }
+        if !used_registrations.contains(operation) {
+            return Err(ClientCompileError::manifest(
+                "client.route.unused_registration",
+                format!(
+                    "explicit route registration for `{operation}` is unused; registrations are only valid as the `@load` fallback"
+                ),
+            ));
+        }
+    }
+
+    validate_unique_routes(&operations)?;
+    render_project(&manifest, operations)
+}
+
+fn normalize_source_path(path: &str) -> Result<String, ClientCompileError> {
+    let normalized = path.trim().replace('\\', "/");
+    if normalized.is_empty() {
+        return Err(ClientCompileError::manifest(
+            "client.documents.empty_path",
+            "GraphQL document path must not be empty",
+        ));
+    }
+    if normalized.split('/').any(|segment| segment == "..") {
+        return Err(ClientCompileError::manifest(
+            "client.documents.parent_path",
+            format!("GraphQL document path `{path}` must not contain `..`"),
+        ));
+    }
+    Ok(normalized)
+}
+
+fn validate_route_registrations(
+    mut registrations: Vec<ClientRouteRegistration>,
+) -> Result<BTreeMap<String, String>, ClientCompileError> {
+    registrations.sort_by(|left, right| {
+        left.operation
+            .cmp(&right.operation)
+            .then_with(|| left.route.cmp(&right.route))
+    });
+    let mut result = BTreeMap::new();
+    for registration in registrations {
+        if !is_graphql_name(&registration.operation) {
+            return Err(ClientCompileError::manifest(
+                "client.route.invalid_operation",
+                format!(
+                    "route registration operation `{}` is not a GraphQL name",
+                    registration.operation
+                ),
+            ));
+        }
+        let route = normalize_route(&registration.route)?;
+        if result
+            .insert(registration.operation.clone(), route)
+            .is_some()
+        {
+            return Err(ClientCompileError::manifest(
+                "client.route.duplicate_registration",
+                format!(
+                    "duplicate route registration for operation `{}`",
+                    registration.operation
+                ),
+            ));
+        }
+    }
+    Ok(result)
+}
+
+fn normalize_route(route: &str) -> Result<String, ClientCompileError> {
+    let mut normalized = route.trim().replace('\\', "/");
+    if normalized.is_empty() || !normalized.starts_with('/') {
+        return Err(ClientCompileError::manifest(
+            "client.route.invalid",
+            format!("route `{route}` must be non-empty and start with `/`"),
+        ));
+    }
+    if normalized.contains('?')
+        || normalized.contains('#')
+        || normalized.split('/').any(|segment| segment == "..")
+    {
+        return Err(ClientCompileError::manifest(
+            "client.route.invalid",
+            format!("route `{route}` must not contain query, fragment, or parent segments"),
+        ));
+    }
+    while normalized.len() > 1 && normalized.ends_with('/') {
+        normalized.pop();
+    }
+    Ok(normalized)
+}
+
+fn validate_unique_routes(operations: &[CompiledOperation]) -> Result<(), ClientCompileError> {
+    let mut routes = BTreeMap::<&str, &str>::new();
+    for operation in operations {
+        let Some(route) = &operation.route else {
+            continue;
+        };
+        if let Some(previous) = routes.insert(&route.route, &operation.name) {
+            return Err(ClientCompileError::manifest(
+                "client.route.duplicate",
+                format!(
+                    "route `{}` is owned by both `{}` and `{}`",
+                    route.route, previous, operation.name
+                ),
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn is_graphql_name(value: &str) -> bool {
+    let mut chars = value.chars();
+    matches!(chars.next(), Some('_' | 'A'..='Z' | 'a'..='z'))
+        && chars.all(|character| matches!(character, '_' | '0'..='9' | 'A'..='Z' | 'a'..='z'))
+}
+
+#[cfg(test)]
+mod tests;
+
+#[cfg(test)]
+mod runtime_bridge_tests;
diff --git a/distributed_cli/src/client_compiler/render/artifact.rs b/distributed_cli/src/client_compiler/render/artifact.rs
new file mode 100644
index 00000000..98623050
--- /dev/null
+++ b/distributed_cli/src/client_compiler/render/artifact.rs
@@ -0,0 +1,501 @@
+use std::collections::BTreeMap;
+
+use serde::Serialize;
+use serde_json::Value as JsonValue;
+
+use super::super::graphql::{
+    Cardinality, CompiledArgument, CompiledBranch, CompiledBranchSemantic, CompiledFilterField,
+    CompiledFilterPlan, CompiledMember, CompiledObject, CompiledOperation, CompiledOrderField,
+    CompiledOrderPlan, CompiledPaginationPlan, CompiledRelationshipPlan, CompiledStorage,
+    CompiledVariableCodec,
+};
+use super::super::manifest::{
+    ClientManifest, ManifestRelationshipKeyMapping, ManifestRelationshipKind,
+    ManifestRelationshipMaintenance, ManifestRowPolicy, ManifestTrustedPresetDescriptor,
+};
+use super::super::ClientCompileError;
+
+#[derive(Serialize)]
+struct Artifact<'a> {
+    id: &'a str,
+    document: &'a str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    source: Option<ArtifactSource<'a>>,
+    #[serde(rename = "variableCodec")]
+    variable_codec: &'a CompiledVariableCodec,
+    roots: Vec<ArtifactRoot<'a>>,
+    protocol: ArtifactProtocol<'a>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    live: Option<ArtifactLive<'a>>,
+}
+
+#[derive(Serialize)]
+struct ArtifactSource<'a> {
+    path: &'a str,
+    line: usize,
+    column: usize,
+}
+
+#[derive(Serialize)]
+struct ArtifactProtocol<'a> {
+    version: u32,
+    #[serde(rename = "schemaHash")]
+    schema_hash: &'a str,
+    surface: &'a super::super::manifest::ManifestSurface,
+    operation: &'a str,
+    #[serde(rename = "trustedPresets")]
+    trusted_presets: &'a [ManifestTrustedPresetDescriptor],
+}
+
+#[derive(Serialize)]
+struct ArtifactLive<'a> {
+    id: &'a str,
+    document: &'a str,
+}
+
+#[derive(Serialize)]
+struct ArtifactRoot<'a> {
+    #[serde(rename = "responseKey")]
+    response_key: &'a str,
+    field: &'a str,
+    cardinality: &'static str,
+    nullable: bool,
+    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
+    arguments: BTreeMap<&'a str, ArtifactArgument<'a>>,
+    dependencies: &'a [String],
+    #[serde(skip_serializing_if = "Option::is_none")]
+    coverage: Option<ArtifactCoverage<'a>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    filter: Option<ArtifactFilter<'a>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    order: Option<ArtifactOrder<'a>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pagination: Option<ArtifactPagination<'a>>,
+    selection: ArtifactSelection<'a>,
+}
+
+#[derive(Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+enum ArtifactArgument<'a> {
+    Literal {
+        value: &'a JsonValue,
+    },
+    Variable {
+        name: &'a str,
+    },
+    List {
+        items: Vec<ArtifactArgument<'a>>,
+    },
+    Object {
+        fields: BTreeMap<&'a str, ArtifactArgument<'a>>,
+    },
+}
+
+#[derive(Serialize)]
+struct ArtifactCoverage<'a> {
+    kind: &'a str,
+    #[serde(rename = "offsetArgument", skip_serializing_if = "Option::is_none")]
+    offset_argument: Option<&'a str>,
+    #[serde(rename = "limitArgument", skip_serializing_if = "Option::is_none")]
+    limit_argument: Option<&'a str>,
+    #[serde(rename = "defaultLimit", skip_serializing_if = "Option::is_none")]
+    default_limit: Option<u64>,
+    #[serde(rename = "maxLimit", skip_serializing_if = "Option::is_none")]
+    max_limit: Option<u64>,
+}
+
+#[derive(Serialize)]
+struct ArtifactFilter<'a> {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    input: Option<ArtifactArgument<'a>>,
+    fields: Vec<ArtifactFilterField<'a>>,
+    relationships: Vec<ArtifactRelationship<'a>>,
+    #[serde(rename = "rowPolicy")]
+    row_policy: &'a ManifestRowPolicy,
+}
+
+#[derive(Serialize)]
+struct ArtifactFilterField<'a> {
+    field: &'a str,
+    scalar: &'a str,
+    codec: &'a str,
+    nullable: bool,
+    operators: &'a [String],
+}
+
+#[derive(Serialize)]
+struct ArtifactRelationship<'a> {
+    field: &'a str,
+    #[serde(rename = "targetModel")]
+    target_model: &'a str,
+    kind: ManifestRelationshipKind,
+    #[serde(rename = "keyMapping")]
+    key_mapping: ArtifactRelationshipKeyMapping<'a>,
+    maintenance: ManifestRelationshipMaintenance,
+    dependencies: &'a [String],
+}
+
+#[derive(Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+enum ArtifactRelationshipKeyMapping<'a> {
+    Direct {
+        local: &'a [String],
+        remote: &'a [String],
+    },
+    Through {
+        local: &'a [String],
+        remote: &'a [String],
+        table: &'a str,
+        #[serde(rename = "sourceForeignKey")]
+        source_foreign_key: &'a str,
+        #[serde(rename = "targetForeignKey")]
+        target_foreign_key: &'a str,
+    },
+    ThroughOpaque {
+        local: &'a [String],
+        remote: &'a [String],
+        dependency: &'a str,
+    },
+    Embedded,
+}
+
+#[derive(Serialize)]
+struct ArtifactOrder<'a> {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    input: Option<ArtifactArgument<'a>>,
+    fields: Vec<ArtifactOrderField<'a>>,
+    #[serde(rename = "tieBreakers")]
+    tie_breakers: Vec<ArtifactOrderField<'a>>,
+}
+
+#[derive(Serialize)]
+struct ArtifactOrderField<'a> {
+    field: &'a str,
+    scalar: &'a str,
+    codec: &'a str,
+    nullable: bool,
+}
+
+#[derive(Serialize)]
+struct ArtifactPagination<'a> {
+    kind: &'a str,
+    insert: &'a str,
+    delete: &'a str,
+    reorder: &'a str,
+    #[serde(rename = "stableUpdate")]
+    stable_update: &'a str,
+}
+
+#[derive(Serialize)]
+struct ArtifactSelection<'a> {
+    typename: &'a str,
+    storage: ArtifactStorage<'a>,
+    members: Vec<ArtifactMember<'a>>,
+}
+
+#[derive(Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+enum ArtifactStorage<'a> {
+    Normalized {
+        model: &'a str,
+        #[serde(rename = "identityFields")]
+        identity_fields: &'a [String],
+    },
+    Embedded,
+}
+
+#[derive(Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+enum ArtifactMember<'a> {
+    Scalar {
+        #[serde(rename = "responseKey")]
+        response_key: &'a str,
+        field: &'a str,
+        codec: &'a str,
+        nullable: bool,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        expose: Option<bool>,
+    },
+    Branch {
+        semantic: CompiledBranchSemantic,
+        #[serde(rename = "responseKey")]
+        response_key: &'a str,
+        field: &'a str,
+        cardinality: &'static str,
+        nullable: bool,
+        #[serde(skip_serializing_if = "BTreeMap::is_empty")]
+        arguments: BTreeMap<&'a str, ArtifactArgument<'a>>,
+        dependencies: &'a [String],
+        #[serde(skip_serializing_if = "Option::is_none")]
+        coverage: Option<ArtifactCoverage<'a>>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        filter: Option<Box<ArtifactFilter<'a>>>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        order: Option<Box<ArtifactOrder<'a>>>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pagination: Option<Box<ArtifactPagination<'a>>>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        relationship: Option<Box<ArtifactRelationship<'a>>>,
+        selection: Box<ArtifactSelection<'a>>,
+    },
+}
+/// Serialize the exact artifact embedded in the generated TypeScript module.
+///
+/// Keeping this boundary machine-readable lets cross-runtime contract tests
+/// consume Rust output directly instead of recovering JSON from TypeScript.
+pub(super) fn render_operation_artifact_json(
+    operation: &CompiledOperation,
+    manifest: &ClientManifest,
+) -> Result<String, ClientCompileError> {
+    let artifact = Artifact {
+        id: &operation.query_hash,
+        document: &operation.query_document,
+        source: artifact_source(operation),
+        variable_codec: &operation.variable_codec,
+        roots: vec![artifact_root(operation)],
+        protocol: ArtifactProtocol {
+            version: 1,
+            schema_hash: &manifest.schema_fingerprint,
+            surface: &manifest.surface,
+            operation: &operation.query_hash,
+            trusted_presets: &manifest.trusted_presets,
+        },
+        live: operation.live.as_ref().map(|live| ArtifactLive {
+            id: &live.hash,
+            document: &live.document,
+        }),
+    };
+    let artifact_json = serde_json::to_string_pretty(&artifact).map_err(|error| {
+        ClientCompileError::manifest(
+            "client.render.operation",
+            format!("failed to render operation `{}`: {error}", operation.name),
+        )
+    })?;
+    Ok(artifact_json)
+}
+
+fn artifact_source(operation: &CompiledOperation) -> Option<ArtifactSource<'_>> {
+    let path = operation.source_path.as_str();
+    let drive_absolute = path.as_bytes().get(1) == Some(&b':');
+    if path.len() > 4_096
+        || path.chars().any(char::is_control)
+        || path.starts_with('/')
+        || drive_absolute
+        || path.split('/').any(|segment| segment == "..")
+        || !(path.ends_with(".graphql") || path.ends_with(".gql"))
+    {
+        return None;
+    }
+    Some(ArtifactSource {
+        path,
+        line: operation.source_line,
+        column: operation.source_column,
+    })
+}
+
+fn artifact_root(operation: &CompiledOperation) -> ArtifactRoot<'_> {
+    let root = &operation.root;
+    ArtifactRoot {
+        response_key: &root.response_key,
+        field: &root.field,
+        cardinality: match root.cardinality {
+            Cardinality::One => "one",
+            Cardinality::Many => "many",
+        },
+        nullable: root.nullable,
+        arguments: root
+            .arguments
+            .iter()
+            .map(|(name, argument)| (name.as_str(), artifact_argument(argument)))
+            .collect(),
+        dependencies: &root.dependencies,
+        coverage: root.coverage.as_ref().map(|coverage| ArtifactCoverage {
+            kind: &coverage.kind,
+            offset_argument: coverage.offset_argument.as_deref(),
+            limit_argument: coverage.limit_argument.as_deref(),
+            default_limit: coverage.default_limit,
+            max_limit: coverage.max_limit,
+        }),
+        filter: root.filter.as_ref().map(artifact_filter),
+        order: root.order.as_ref().map(artifact_order),
+        pagination: root.pagination.as_ref().map(artifact_pagination),
+        selection: artifact_selection(&root.selection),
+    }
+}
+
+fn artifact_argument(argument: &CompiledArgument) -> ArtifactArgument<'_> {
+    match argument {
+        CompiledArgument::Literal { value, .. } => ArtifactArgument::Literal { value },
+        CompiledArgument::Variable(name) => ArtifactArgument::Variable { name },
+        CompiledArgument::List(items) => ArtifactArgument::List {
+            items: items.iter().map(artifact_argument).collect(),
+        },
+        CompiledArgument::Object(fields) => ArtifactArgument::Object {
+            fields: fields
+                .iter()
+                .map(|(name, value)| (name.as_str(), artifact_argument(value)))
+                .collect(),
+        },
+    }
+}
+
+fn artifact_filter(plan: &CompiledFilterPlan) -> ArtifactFilter<'_> {
+    ArtifactFilter {
+        input: plan.input.as_ref().map(artifact_argument),
+        fields: plan.fields.iter().map(artifact_filter_field).collect(),
+        relationships: plan
+            .relationships
+            .iter()
+            .map(artifact_relationship)
+            .collect(),
+        row_policy: &plan.row_policy,
+    }
+}
+
+fn artifact_filter_field(field: &CompiledFilterField) -> ArtifactFilterField<'_> {
+    ArtifactFilterField {
+        field: &field.name,
+        scalar: &field.scalar,
+        codec: &field.codec,
+        nullable: field.nullable,
+        operators: &field.operators,
+    }
+}
+
+fn artifact_relationship(relationship: &CompiledRelationshipPlan) -> ArtifactRelationship<'_> {
+    ArtifactRelationship {
+        field: &relationship.field,
+        target_model: &relationship.target_model,
+        kind: relationship.kind,
+        key_mapping: match &relationship.key_mapping {
+            ManifestRelationshipKeyMapping::Direct { local, remote } => {
+                ArtifactRelationshipKeyMapping::Direct { local, remote }
+            }
+            ManifestRelationshipKeyMapping::Through {
+                local,
+                remote,
+                table,
+                source_foreign_key,
+                target_foreign_key,
+            } => ArtifactRelationshipKeyMapping::Through {
+                local,
+                remote,
+                table,
+                source_foreign_key,
+                target_foreign_key,
+            },
+            ManifestRelationshipKeyMapping::ThroughOpaque {
+                local,
+                remote,
+                dependency,
+            } => ArtifactRelationshipKeyMapping::ThroughOpaque {
+                local,
+                remote,
+                dependency,
+            },
+            ManifestRelationshipKeyMapping::Embedded => ArtifactRelationshipKeyMapping::Embedded,
+        },
+        maintenance: relationship.maintenance,
+        dependencies: &relationship.dependencies,
+    }
+}
+
+fn artifact_order(plan: &CompiledOrderPlan) -> ArtifactOrder<'_> {
+    ArtifactOrder {
+        input: plan.input.as_ref().map(artifact_argument),
+        fields: plan.fields.iter().map(artifact_order_field).collect(),
+        tie_breakers: plan.identity.iter().map(artifact_order_field).collect(),
+    }
+}
+
+fn artifact_order_field(field: &CompiledOrderField) -> ArtifactOrderField<'_> {
+    ArtifactOrderField {
+        field: &field.name,
+        scalar: &field.scalar,
+        codec: &field.codec,
+        nullable: field.nullable,
+    }
+}
+
+fn artifact_pagination(plan: &CompiledPaginationPlan) -> ArtifactPagination<'_> {
+    ArtifactPagination {
+        kind: &plan.kind,
+        insert: &plan.insert,
+        delete: &plan.delete,
+        reorder: &plan.reorder,
+        stable_update: &plan.stable_update,
+    }
+}
+
+fn artifact_selection(selection: &CompiledObject) -> ArtifactSelection<'_> {
+    ArtifactSelection {
+        typename: &selection.typename,
+        storage: match &selection.storage {
+            CompiledStorage::Normalized {
+                model_id,
+                identity_fields,
+            } => ArtifactStorage::Normalized {
+                model: model_id,
+                identity_fields,
+            },
+            CompiledStorage::Embedded => ArtifactStorage::Embedded,
+        },
+        members: selection
+            .members
+            .iter()
+            .map(|member| match member {
+                CompiledMember::Scalar(scalar) => ArtifactMember::Scalar {
+                    response_key: &scalar.response_key,
+                    field: &scalar.field,
+                    codec: &scalar.codec,
+                    nullable: scalar.nullable,
+                    expose: (!scalar.expose).then_some(false),
+                },
+                CompiledMember::Branch(branch) => artifact_branch(branch),
+            })
+            .collect(),
+    }
+}
+
+fn artifact_branch(branch: &CompiledBranch) -> ArtifactMember<'_> {
+    ArtifactMember::Branch {
+        semantic: branch.semantic,
+        response_key: &branch.response_key,
+        field: &branch.field,
+        cardinality: match branch.cardinality {
+            Cardinality::One => "one",
+            Cardinality::Many => "many",
+        },
+        nullable: branch.nullable,
+        arguments: branch
+            .arguments
+            .iter()
+            .map(|(name, argument)| (name.as_str(), artifact_argument(argument)))
+            .collect(),
+        dependencies: &branch.dependencies,
+        coverage: branch.coverage.as_ref().map(|coverage| ArtifactCoverage {
+            kind: &coverage.kind,
+            offset_argument: coverage.offset_argument.as_deref(),
+            limit_argument: coverage.limit_argument.as_deref(),
+            default_limit: coverage.default_limit,
+            max_limit: coverage.max_limit,
+        }),
+        filter: branch
+            .filter
+            .as_ref()
+            .map(|plan| Box::new(artifact_filter(plan))),
+        order: branch
+            .order
+            .as_ref()
+            .map(|plan| Box::new(artifact_order(plan))),
+        pagination: branch
+            .pagination
+            .as_ref()
+            .map(|plan| Box::new(artifact_pagination(plan))),
+        relationship: branch
+            .relationship
+            .as_ref()
+            .map(|relationship| Box::new(artifact_relationship(relationship))),
+        selection: Box::new(artifact_selection(&branch.selection)),
+    }
+}
diff --git a/distributed_cli/src/client_compiler/render/commands.rs b/distributed_cli/src/client_compiler/render/commands.rs
new file mode 100644
index 00000000..7babcef7
--- /dev/null
+++ b/distributed_cli/src/client_compiler/render/commands.rs
@@ -0,0 +1,671 @@
+use std::collections::BTreeSet;
+
+use serde_json::Value as JsonValue;
+
+use super::super::manifest::{
+    canonical_json_value, ClientManifest, ManifestCommand, ManifestCommandShape,
+    ManifestConfirmation, ManifestConfirmationKind, ManifestConsistencyKind,
+    ManifestDirectProjection, ManifestEffect, ManifestEffectExpression, ManifestEffectField,
+    ManifestEffectKey, ManifestEffectRelationship, ManifestEffects, ManifestRevalidationFallback,
+    ManifestTypeDef, ManifestTypeField,
+};
+use super::super::ClientCompileError;
+use super::common::quoted_property;
+
+pub(super) fn render_commands(manifest: &ClientManifest) -> Result<String, ClientCompileError> {
+    validate_command_namespaces(&manifest.commands)?;
+    let projectors = serde_json::to_string_pretty(&manifest.projectors).map_err(|error| {
+        ClientCompileError::manifest(
+            "client.render.projectors",
+            format!("failed to render projector artifacts: {error}"),
+        )
+    })?;
+    let mut sections = vec!["/** GENERATED by dctl client. Do not edit. */".to_string()];
+    if !manifest.commands.is_empty() {
+        sections.push(
+            "import {\n  createReplicaCommandRuntime,\n  prepareReplicaCommand\n} from '@hops-ops/distributed/replica';"
+                .into(),
+        );
+        sections.push(
+            "import type {\n  DistributedReplica,\n  PrepareReplicaCommandOptions,\n  ReplicaCommandArtifact,\n  ReplicaCommandRuntime,\n  ReplicaCommandRuntimeOptions,\n  ReplicaCommandTransport,\n  ReplicaPreparedCommand,\n  ReplicaValue\n} from '@hops-ops/distributed/replica';"
+                .into(),
+        );
+        sections.push("import { COMMAND_STATUS } from './protocol.js';".into());
+    }
+    for command in &manifest.commands {
+        sections.push(render_command(command, manifest)?);
+    }
+    let artifact_names = manifest
+        .commands
+        .iter()
+        .map(|command| format!("Command_{}", command.mutation_field))
+        .collect::<Vec<_>>()
+        .join(", ");
+    sections.push(format!(
+        "export const COMMAND_ARTIFACTS = [{artifact_names}] as const;"
+    ));
+    let command_entries = manifest
+        .commands
+        .iter()
+        .map(|command| {
+            format!(
+                "  {}: Command_{}",
+                quoted_property(&command.name),
+                command.mutation_field
+            )
+        })
+        .collect::<Vec<_>>()
+        .join(",\n");
+    sections.push(format!(
+        "/** Inspectable command inventory consumed by the generated binding factory. */\nexport const COMMANDS = {{\n{command_entries}\n}} as const;"
+    ));
+    if !manifest.commands.is_empty() {
+        sections.push(
+            [
+                "/** Runtime owning the generated callable command surface and its causal lifecycle. */",
+                "export type GeneratedCommandRuntime = ReplicaCommandRuntime<typeof COMMANDS>;",
+                "",
+                "/** Callable `commands.x(input)` surface exposed by GeneratedCommandRuntime. */",
+                "export type GeneratedCommands = GeneratedCommandRuntime['commands'];",
+                "",
+                "/** Runtime options excluding compiler-owned protocol authority. */",
+                "export type GeneratedCommandRuntimeOptions = Omit<ReplicaCommandRuntimeOptions, 'status'>;",
+                "",
+                "/**",
+                " * Bind this generated command inventory to a replica and transport.",
+                " * Keep the returned runtime when `observeResult` or `dispose` is needed.",
+                " */",
+                "export function createCommands(",
+                "  replica: DistributedReplica,",
+                "  transport: ReplicaCommandTransport,",
+                "  options?: GeneratedCommandRuntimeOptions",
+                "): GeneratedCommandRuntime {",
+                "  return createReplicaCommandRuntime(replica, transport, COMMANDS, {",
+                "    ...options,",
+                "    status: COMMAND_STATUS",
+                "  });",
+                "}",
+            ]
+            .join("\n"),
+        );
+    }
+    sections.push(format!(
+        "/** Projector topology used by command confirmation/effect runtimes. */\nexport const PROJECTOR_ARTIFACTS = {projectors} as const;"
+    ));
+    sections
+        .push("export type GeneratedCommandArtifact = (typeof COMMAND_ARTIFACTS)[number];".into());
+    Ok(format!("{}\n", sections.join("\n\n")))
+}
+
+fn validate_command_namespaces(commands: &[ManifestCommand]) -> Result<(), ClientCompileError> {
+    const RESERVED_SEGMENTS: [&str; 3] = ["__proto__", "constructor", "prototype"];
+
+    let mut paths = Vec::with_capacity(commands.len());
+    for command in commands {
+        let segments = command.name.split('.').collect::<Vec<_>>();
+        if command.name.len() > 512 || segments.len() > 64 {
+            return Err(ClientCompileError::manifest(
+                "client.command.namespace_segment",
+                format!(
+                    "command `{}` cannot generate a safe nested command namespace: paths are limited to 512 bytes and 64 segments",
+                    command.name
+                ),
+            ));
+        }
+        if let Some(segment) = segments.iter().copied().find(|segment| {
+            segment.is_empty()
+                || segment.len() > 128
+                || segment.trim() != *segment
+                || segment.chars().any(char::is_control)
+                || RESERVED_SEGMENTS.contains(segment)
+        }) {
+            return Err(ClientCompileError::manifest(
+                "client.command.namespace_segment",
+                format!(
+                    "command `{}` cannot generate a safe nested command namespace: segment `{segment}` is empty, reserved, oversized, padded, or contains control characters",
+                    command.name
+                ),
+            ));
+        }
+        paths.push((command.name.as_str(), segments));
+    }
+
+    for left_index in 0..paths.len() {
+        for right_index in (left_index + 1)..paths.len() {
+            let (left_name, left) = &paths[left_index];
+            let (right_name, right) = &paths[right_index];
+            let (prefix_name, prefix, descendant_name, descendant) = if left.len() <= right.len() {
+                (left_name, left, right_name, right)
+            } else {
+                (right_name, right, left_name, left)
+            };
+            if descendant.starts_with(prefix) {
+                return Err(ClientCompileError::manifest(
+                    "client.command.namespace_collision",
+                    format!(
+                        "commands `{prefix_name}` and `{descendant_name}` collide in the generated nested command namespace; rename one command so neither dotted path prefixes the other"
+                    ),
+                ));
+            }
+        }
+    }
+    Ok(())
+}
+
+fn render_command(
+    command: &ManifestCommand,
+    manifest: &ClientManifest,
+) -> Result<String, ClientCompileError> {
+    // Domain command names deliberately permit dots and other non-GraphQL
+    // characters. Generated identifiers use the unique, GraphQL-validated
+    // mutation field; the public command map retains the exact domain name.
+    let identifier = &command.mutation_field;
+    let input_name = format!("Command_{identifier}_Input");
+    let output_name = format!("Command_{identifier}_Output");
+    let defaults = command
+        .extensions
+        .input_defaults
+        .as_ref()
+        .map(|defaults| {
+            defaults
+                .defaults
+                .iter()
+                .map(|default| default.path.clone())
+                .collect::<BTreeSet<_>>()
+        })
+        .unwrap_or_default();
+    let input_type = render_command_shape_type(&command.input, true, &defaults)?;
+    let output_type = render_command_shape_type(&command.output, false, &BTreeSet::new())?;
+    // serde_json's map backend can change when Cargo feature unification enables
+    // `preserve_order` elsewhere in the workspace. Canonicalize compiler-owned
+    // JSON so generated bytes never depend on the invoking feature matrix.
+    let artifact = canonical_json_value(command_artifact_json(command, manifest)?);
+    let artifact = serde_json::to_string_pretty(&artifact).map_err(|error| {
+        ClientCompileError::manifest(
+            "client.render.command",
+            format!(
+                "failed to render executable command `{}`: {error}",
+                command.name
+            ),
+        )
+    })?;
+    let prepare = match command.input {
+        ManifestCommandShape::None => format!(
+            "export function prepareCommand_{}(\n  options?: PrepareReplicaCommandOptions\n): ReplicaPreparedCommand<{}, {}> {{\n  return prepareReplicaCommand(Command_{}, undefined, options);\n}}",
+            identifier, input_name, output_name, identifier
+        ),
+        _ => format!(
+            "export function prepareCommand_{}(\n  input: {},\n  options?: PrepareReplicaCommandOptions\n): ReplicaPreparedCommand<{}, {}> {{\n  return prepareReplicaCommand(Command_{}, input, options);\n}}",
+            identifier, input_name, input_name, output_name, identifier
+        ),
+    };
+    Ok(format!(
+        "export type {input_name} = {input_type};\n\n\
+         export type {output_name} = {output_type};\n\n\
+         /** Exact typed causal command descriptor and full mutation bytes. */\n\
+         export const Command_{}: ReplicaCommandArtifact<{}, {}> = {};\n\n\
+         {}",
+        identifier, input_name, output_name, artifact, prepare
+    ))
+}
+
+fn render_command_shape_type(
+    shape: &ManifestCommandShape,
+    input: bool,
+    defaults: &BTreeSet<Vec<String>>,
+) -> Result<String, ClientCompileError> {
+    match shape {
+        ManifestCommandShape::None => Ok("void".into()),
+        ManifestCommandShape::Object { definition } => {
+            render_command_type_definition(definition, input, defaults, &[], 0)
+        }
+    }
+}
+
+fn render_command_type_definition(
+    definition: &ManifestTypeDef,
+    input: bool,
+    defaults: &BTreeSet<Vec<String>>,
+    prefix: &[String],
+    indent: usize,
+) -> Result<String, ClientCompileError> {
+    let member_padding = " ".repeat(indent + 2);
+    let closing_padding = " ".repeat(indent);
+    let mut lines = vec!["{".to_string()];
+    for field in &definition.fields {
+        let mut path = prefix.to_vec();
+        path.push(field.name.clone());
+        let optional = input && (field.nullable || defaults.contains(&path));
+        let mut value = render_command_field_type(field, input, defaults, &path, indent + 2)?;
+        if field.list {
+            if field.item_nullable {
+                value = format!("({value} | null)");
+            }
+            value = format!("readonly {value}[]");
+        }
+        if field.nullable {
+            value = format!("{value} | null");
+        }
+        lines.push(format!(
+            "{member_padding}readonly {}{}: {value};",
+            quoted_property(&field.name),
+            if optional { "?" } else { "" }
+        ));
+    }
+    lines.push(format!("{closing_padding}}}"));
+    Ok(lines.join("\n"))
+}
+
+fn render_command_field_type(
+    field: &ManifestTypeField,
+    input: bool,
+    defaults: &BTreeSet<Vec<String>>,
+    path: &[String],
+    indent: usize,
+) -> Result<String, ClientCompileError> {
+    if let Some(nested) = &field.nested {
+        return render_command_type_definition(nested, input, defaults, path, indent);
+    }
+    match field.codec.as_deref() {
+        Some("boolean") => Ok("boolean".into()),
+        Some("float64" | "int32" | "json_number_precision_limited") => Ok("number".into()),
+        Some("string" | "base64" | "string_unvalidated_timestamp") => Ok("string".into()),
+        Some("json") => Ok("ReplicaValue".into()),
+        Some(codec) => Err(ClientCompileError::manifest(
+            "client.scalar.codec_unsupported",
+            format!(
+                "command field `{}` uses unsupported TypeScript codec `{codec}`",
+                field.name
+            ),
+        )),
+        None => Err(ClientCompileError::manifest(
+            "client.render.command_shape",
+            format!(
+                "command field `{}` has neither a scalar codec nor a nested definition",
+                field.name
+            ),
+        )),
+    }
+}
+
+fn command_artifact_json(
+    command: &ManifestCommand,
+    manifest: &ClientManifest,
+) -> Result<JsonValue, ClientCompileError> {
+    let consistency = &command.extensions.consistency;
+    let mut artifact = serde_json::Map::new();
+    artifact.insert("version".into(), serde_json::json!(command.version));
+    artifact.insert("name".into(), serde_json::json!(command.name));
+    artifact.insert(
+        "mutationField".into(),
+        serde_json::json!(command.mutation_field),
+    );
+    artifact.insert("document".into(), serde_json::json!(command.operation));
+    artifact.insert(
+        "operationHash".into(),
+        serde_json::json!(command.operation_hash),
+    );
+    artifact.insert(
+        "protocol".into(),
+        serde_json::json!({
+            "version": 1,
+            "schemaHash": manifest.schema_fingerprint,
+            "protocolHash": manifest.protocol_fingerprint,
+            "surface": &manifest.surface,
+            "operation": command.operation_hash,
+            "trustedPresets": &manifest.trusted_presets,
+        }),
+    );
+    artifact.insert("input".into(), command_shape_json(&command.input));
+    artifact.insert("output".into(), command_shape_json(&command.output));
+    if let Some(defaults) = &command.extensions.input_defaults {
+        artifact.insert(
+            "inputDefaults".into(),
+            serde_json::json!({
+                "version": defaults.version,
+                "defaults": defaults.defaults,
+            }),
+        );
+    }
+    artifact.insert(
+        "consistency".into(),
+        serde_json::json!(consistency_label(consistency.kind)),
+    );
+    artifact.insert(
+        "effects".into(),
+        effects_json(command.extensions.effects.as_ref()),
+    );
+    if let Some(confirmations) = &command.extensions.confirmations {
+        artifact.insert(
+            "confirmations".into(),
+            serde_json::json!({
+                "version": confirmations.version,
+                "kind": confirmation_kind_label(confirmations.kind),
+                "expected": confirmations.expected.iter().map(confirmation_json).collect::<Vec<_>>(),
+                "fallback": "revalidate",
+            }),
+        );
+    }
+    if let Some(direct) = &command.extensions.direct_projection {
+        artifact.insert(
+            "directProjection".into(),
+            direct_projection_json(direct, manifest)?,
+        );
+    }
+    if !command.extensions.trusted_presets.is_empty() {
+        artifact.insert(
+            "trustedPresets".into(),
+            serde_json::json!(command.extensions.trusted_presets),
+        );
+    }
+    artifact.insert(
+        "revalidation".into(),
+        command_revalidation_json(command, manifest),
+    );
+    Ok(JsonValue::Object(artifact))
+}
+
+fn command_shape_json(shape: &ManifestCommandShape) -> JsonValue {
+    match shape {
+        ManifestCommandShape::None => serde_json::json!({"kind": "none"}),
+        ManifestCommandShape::Object { definition } => serde_json::json!({
+            "kind": "object",
+            "definition": command_type_definition_json(definition),
+        }),
+    }
+}
+
+fn command_type_definition_json(definition: &ManifestTypeDef) -> JsonValue {
+    serde_json::json!({
+        "name": definition.name,
+        "fields": definition.fields.iter().map(command_type_field_json).collect::<Vec<_>>(),
+    })
+}
+
+fn command_type_field_json(field: &ManifestTypeField) -> JsonValue {
+    let mut result = serde_json::Map::new();
+    result.insert("name".into(), serde_json::json!(field.name));
+    result.insert("typeName".into(), serde_json::json!(field.type_name));
+    result.insert("nullable".into(), serde_json::json!(field.nullable));
+    result.insert("list".into(), serde_json::json!(field.list));
+    result.insert(
+        "itemNullable".into(),
+        serde_json::json!(field.item_nullable),
+    );
+    if let Some(codec) = &field.codec {
+        result.insert("codec".into(), serde_json::json!(codec));
+    }
+    if let Some(nested) = &field.nested {
+        result.insert("nested".into(), command_type_definition_json(nested));
+    }
+    JsonValue::Object(result)
+}
+
+fn consistency_label(kind: ManifestConsistencyKind) -> &'static str {
+    match kind {
+        ManifestConsistencyKind::Accepted => "accepted",
+        ManifestConsistencyKind::Fact => "fact",
+        ManifestConsistencyKind::Projected => "projected",
+    }
+}
+
+fn confirmation_kind_label(kind: ManifestConfirmationKind) -> &'static str {
+    match kind {
+        ManifestConfirmationKind::Finite => "finite",
+        ManifestConfirmationKind::Unavailable => "unavailable",
+    }
+}
+
+fn effects_json(effects: Option<&ManifestEffects>) -> JsonValue {
+    match effects {
+        Some(effects) => serde_json::json!({
+            "version": effects.version,
+            "operations": effects.operations.iter().map(effect_json).collect::<Vec<_>>(),
+            "fallback": revalidation_label(effects.fallback),
+        }),
+        None => serde_json::json!({
+            "version": 1,
+            "operations": [],
+            "fallback": "revalidate",
+        }),
+    }
+}
+
+fn revalidation_label(fallback: ManifestRevalidationFallback) -> &'static str {
+    match fallback {
+        ManifestRevalidationFallback::Revalidate => "revalidate",
+    }
+}
+
+fn effect_json(effect: &ManifestEffect) -> JsonValue {
+    match effect {
+        ManifestEffect::Upsert { model, key, fields } => serde_json::json!({
+            "kind": "upsert",
+            "model": model,
+            "key": effect_key_json(key),
+            "fields": fields.iter().map(effect_field_json).collect::<Vec<_>>(),
+        }),
+        ManifestEffect::Patch { model, key, fields } => serde_json::json!({
+            "kind": "patch",
+            "model": model,
+            "key": effect_key_json(key),
+            "fields": fields.iter().map(effect_field_json).collect::<Vec<_>>(),
+        }),
+        ManifestEffect::Delete { model, key } => serde_json::json!({
+            "kind": "delete",
+            "model": model,
+            "key": effect_key_json(key),
+        }),
+        ManifestEffect::Link {
+            relationship,
+            source,
+            target,
+        } => serde_json::json!({
+            "kind": "link",
+            "relationship": effect_relationship_json(relationship),
+            "source": effect_key_json(source),
+            "target": effect_key_json(target),
+        }),
+        ManifestEffect::Unlink {
+            relationship,
+            source,
+            target,
+        } => serde_json::json!({
+            "kind": "unlink",
+            "relationship": effect_relationship_json(relationship),
+            "source": effect_key_json(source),
+            "target": effect_key_json(target),
+        }),
+        ManifestEffect::InvalidateModel { model } => serde_json::json!({
+            "kind": "invalidate_model",
+            "model": model,
+        }),
+        ManifestEffect::InvalidateRelationship {
+            relationship,
+            source,
+        } => serde_json::json!({
+            "kind": "invalidate_relationship",
+            "relationship": effect_relationship_json(relationship),
+            "source": effect_key_json(source),
+        }),
+    }
+}
+
+fn effect_relationship_json(relationship: &ManifestEffectRelationship) -> JsonValue {
+    serde_json::json!({
+        "sourceModel": relationship.source_model,
+        "field": relationship.field,
+        "targetModel": relationship.target_model,
+    })
+}
+
+fn effect_key_json(key: &ManifestEffectKey) -> JsonValue {
+    serde_json::json!({
+        "fields": key.fields.iter().map(effect_field_json).collect::<Vec<_>>(),
+    })
+}
+
+fn effect_field_json(field: &ManifestEffectField) -> JsonValue {
+    serde_json::json!({
+        "field": field.field,
+        "value": effect_expression_json(&field.value),
+    })
+}
+
+fn effect_expression_json(expression: &ManifestEffectExpression) -> JsonValue {
+    match expression {
+        ManifestEffectExpression::Input { path } => {
+            serde_json::json!({"kind": "input", "path": path})
+        }
+        ManifestEffectExpression::TrustedPreset { name } => {
+            serde_json::json!({"kind": "trusted_preset", "name": name})
+        }
+        ManifestEffectExpression::Constant { value } => {
+            serde_json::json!({"kind": "constant", "value": value})
+        }
+        ManifestEffectExpression::Null => serde_json::json!({"kind": "null"}),
+    }
+}
+
+fn confirmation_json(confirmation: &ManifestConfirmation) -> JsonValue {
+    let mut result = serde_json::Map::new();
+    result.insert(
+        "projector".into(),
+        serde_json::json!(confirmation.projector),
+    );
+    result.insert("model".into(), serde_json::json!(confirmation.model));
+    result.insert("key".into(), effect_key_json(&confirmation.key));
+    if let Some(partition) = &confirmation.partition {
+        result.insert("partition".into(), effect_expression_json(partition));
+    }
+    JsonValue::Object(result)
+}
+
+fn direct_projection_json(
+    direct: &ManifestDirectProjection,
+    manifest: &ClientManifest,
+) -> Result<JsonValue, ClientCompileError> {
+    let identity = manifest
+        .models
+        .get(&direct.model)
+        .and_then(|model| model.identity())
+        .filter(|fields| !fields.is_empty())
+        .ok_or_else(|| {
+            ClientCompileError::manifest(
+                "client.render.direct_projection_identity",
+                format!(
+                    "direct projection model `{}` has no complete normalized identity",
+                    direct.model
+                ),
+            )
+        })?;
+    let mut result = serde_json::Map::new();
+    result.insert(
+        "topology".into(),
+        serde_json::json!({
+            "version": direct.topology.version,
+            "name": direct.topology.name,
+            "digest": direct.topology.digest,
+        }),
+    );
+    result.insert("model".into(), serde_json::json!(direct.model));
+    result.insert(
+        "identityFields".into(),
+        serde_json::json!(identity
+            .iter()
+            .map(|field| field.name.as_str())
+            .collect::<Vec<_>>()),
+    );
+    if let Some(partition) = &direct.partition {
+        result.insert("partition".into(), effect_expression_json(partition));
+    }
+    result.insert("changeEpoch".into(), serde_json::json!(direct.change_epoch));
+    Ok(JsonValue::Object(result))
+}
+
+fn command_revalidation_json(command: &ManifestCommand, manifest: &ClientManifest) -> JsonValue {
+    let required = manifest
+        .commands_requiring_revalidation
+        .contains(&command.name);
+    let mut models = BTreeSet::new();
+    let mut relationships = BTreeSet::new();
+    let mut dependencies = BTreeSet::new();
+    if let Some(effects) = &command.extensions.effects {
+        for effect in &effects.operations {
+            collect_effect_scope(effect, &mut models, &mut relationships);
+        }
+    }
+    if let Some(confirmations) = &command.extensions.confirmations {
+        for confirmation in &confirmations.expected {
+            models.insert(confirmation.model.clone());
+            if let Some(projector) = manifest
+                .projectors
+                .iter()
+                .find(|projector| projector.name == confirmation.projector)
+            {
+                dependencies.extend(projector.dependencies.iter().cloned());
+            }
+        }
+    }
+    if let Some(direct) = &command.extensions.direct_projection {
+        models.insert(direct.model.clone());
+        if let Some(projector) = manifest
+            .projectors
+            .iter()
+            .find(|projector| projector.name == direct.topology.name)
+        {
+            dependencies.extend(projector.dependencies.iter().cloned());
+        }
+    }
+    if required && models.is_empty() {
+        models.extend(manifest.models.keys().cloned());
+    }
+    for model in &models {
+        if let Some(model) = manifest.models.get(model) {
+            dependencies.extend(model.dependencies.iter().cloned());
+        }
+    }
+    let relationship_values = relationships
+        .into_iter()
+        .map(|(source_model, field, target_model)| {
+            serde_json::json!({
+                "sourceModel": source_model,
+                "field": field,
+                "targetModel": target_model,
+            })
+        })
+        .collect::<Vec<_>>();
+    serde_json::json!({
+        "version": 1,
+        "required": required,
+        "dependencies": dependencies.into_iter().collect::<Vec<_>>(),
+        "models": models.into_iter().collect::<Vec<_>>(),
+        "relationships": relationship_values,
+    })
+}
+
+fn collect_effect_scope(
+    effect: &ManifestEffect,
+    models: &mut BTreeSet<String>,
+    relationships: &mut BTreeSet<(String, String, String)>,
+) {
+    match effect {
+        ManifestEffect::Upsert { model, .. }
+        | ManifestEffect::Patch { model, .. }
+        | ManifestEffect::Delete { model, .. }
+        | ManifestEffect::InvalidateModel { model } => {
+            models.insert(model.clone());
+        }
+        ManifestEffect::Link { relationship, .. }
+        | ManifestEffect::Unlink { relationship, .. }
+        | ManifestEffect::InvalidateRelationship { relationship, .. } => {
+            models.insert(relationship.source_model.clone());
+            models.insert(relationship.target_model.clone());
+            relationships.insert((
+                relationship.source_model.clone(),
+                relationship.field.clone(),
+                relationship.target_model.clone(),
+            ));
+        }
+    }
+}
diff --git a/distributed_cli/src/client_compiler/render/common.rs b/distributed_cli/src/client_compiler/render/common.rs
new file mode 100644
index 00000000..049f9958
--- /dev/null
+++ b/distributed_cli/src/client_compiler/render/common.rs
@@ -0,0 +1,16 @@
+use super::super::ClientCompileError;
+
+pub(super) fn quoted_property(value: &str) -> String {
+    // GraphQL response keys are valid identifiers, but quoting them prevents
+    // TypeScript keyword collisions without inventing a second public name.
+    serde_json::to_string(value).expect("string serialization cannot fail")
+}
+
+pub(super) fn json_string(value: &str) -> Result<String, ClientCompileError> {
+    serde_json::to_string(value).map_err(|error| {
+        ClientCompileError::manifest(
+            "client.render.string",
+            format!("failed to render generated string literal: {error}"),
+        )
+    })
+}
diff --git a/distributed_cli/src/client_compiler/render/mod.rs b/distributed_cli/src/client_compiler/render/mod.rs
new file mode 100644
index 00000000..598f61b7
--- /dev/null
+++ b/distributed_cli/src/client_compiler/render/mod.rs
@@ -0,0 +1,24 @@
+mod artifact;
+mod commands;
+mod common;
+mod operation;
+mod project;
+mod typescript;
+
+pub(crate) use project::render_project;
+
+#[cfg(test)]
+pub(crate) fn render_operation_artifact_json(
+    operation: &super::graphql::CompiledOperation,
+    manifest: &super::manifest::ClientManifest,
+) -> Result<String, super::ClientCompileError> {
+    artifact::render_operation_artifact_json(operation, manifest)
+}
+
+#[cfg(test)]
+pub(crate) fn render_operation_module(
+    operation: &super::graphql::CompiledOperation,
+    manifest: &super::manifest::ClientManifest,
+) -> Result<String, super::ClientCompileError> {
+    operation::render_operation_module(operation, manifest)
+}
diff --git a/distributed_cli/src/client_compiler/render/operation.rs b/distributed_cli/src/client_compiler/render/operation.rs
new file mode 100644
index 00000000..94facd90
--- /dev/null
+++ b/distributed_cli/src/client_compiler/render/operation.rs
@@ -0,0 +1,68 @@
+use super::super::graphql::{
+    CompiledFilterInputTarget, CompiledInputDefinition, CompiledInputType, CompiledOperation,
+    CompiledVariableCodec,
+};
+use super::super::manifest::ClientManifest;
+use super::super::ClientCompileError;
+use super::artifact::render_operation_artifact_json;
+use super::common::json_string;
+use super::typescript::{render_data_type, render_variables_type};
+
+pub(super) fn render_operation_module(
+    operation: &CompiledOperation,
+    manifest: &ClientManifest,
+) -> Result<String, ClientCompileError> {
+    let variables_name = format!("{}_Variables", operation.export_name);
+    let data_name = format!("{}_Data", operation.export_name);
+    let variables = render_variables_type(operation, &variables_name)?;
+    let data = render_data_type(operation, &data_name)?;
+    let artifact_json = render_operation_artifact_json(operation, manifest)?;
+    let replica_value_import =
+        variable_codec_uses_replica_value(&operation.variable_codec).then_some(", ReplicaValue");
+    Ok(format!(
+        "/** GENERATED by dctl client. Do not edit. */\n\
+         import type {{ ReplicaOperationArtifact{} }} from '@hops-ops/distributed/replica';\n\
+         \n\
+         {variables}\n\
+         \n\
+         {data}\n\
+         \n\
+         /** Exact canonical query bytes sent to the server. */\n\
+         export const {}Document = {};\n\
+         \n\
+         /** Typed normalized-replica operation descriptor. */\n\
+         export const {}: ReplicaOperationArtifact<{}, {}> = {};\n",
+        replica_value_import.unwrap_or_default(),
+        operation.export_name,
+        json_string(&operation.query_document)?,
+        operation.export_name,
+        data_name,
+        variables_name,
+        artifact_json,
+    ))
+}
+
+fn variable_codec_uses_replica_value(codec: &CompiledVariableCodec) -> bool {
+    fn input_type_uses_replica_value(input: &CompiledInputType) -> bool {
+        match input {
+            CompiledInputType::Scalar { codec, .. } => codec == "json",
+            CompiledInputType::List { item, .. } => input_type_uses_replica_value(item),
+            CompiledInputType::Enum { .. } | CompiledInputType::Input { .. } => false,
+        }
+    }
+
+    codec.variables.values().any(input_type_uses_replica_value)
+        || codec.inputs.values().any(|input| match input {
+            CompiledInputDefinition::Filter {
+                fields,
+                relationships,
+                ..
+            } => {
+                fields.iter().any(|field| field.codec == "json")
+                    || relationships.iter().any(|relationship| {
+                        matches!(&relationship.target, CompiledFilterInputTarget::Opaque)
+                    })
+            }
+            CompiledInputDefinition::Order { .. } => false,
+        })
+}
diff --git a/distributed_cli/src/client_compiler/render/project.rs b/distributed_cli/src/client_compiler/render/project.rs
new file mode 100644
index 00000000..feb27111
--- /dev/null
+++ b/distributed_cli/src/client_compiler/render/project.rs
@@ -0,0 +1,512 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use serde::Serialize;
+
+use super::super::graphql::CompiledOperation;
+use super::super::manifest::{canonical_json_value, ClientManifest};
+use super::super::{
+    ClientCompileError, GeneratedClientFile, GeneratedClientProject, GeneratedOperationSummary,
+    GeneratedRoutePlan,
+};
+use super::commands::render_commands;
+use super::common::json_string;
+use super::operation::render_operation_module;
+
+pub(crate) fn render_project(
+    manifest: &ClientManifest,
+    operations: Vec<CompiledOperation>,
+) -> Result<GeneratedClientProject, ClientCompileError> {
+    let mut files = Vec::new();
+    let mut summaries = Vec::with_capacity(operations.len());
+    let mut routes = Vec::new();
+
+    for operation in &operations {
+        files.push(GeneratedClientFile {
+            path: operation.module_path.clone(),
+            contents: render_operation_module(operation, manifest)?,
+        });
+        summaries.push(GeneratedOperationSummary {
+            name: operation.name.clone(),
+            source_path: operation.source_path.clone(),
+            module_path: operation.module_path.clone(),
+            export_name: operation.export_name.clone(),
+            operation_hash: operation.query_hash.clone(),
+            live_operation_hash: operation.live.as_ref().map(|live| live.hash.clone()),
+        });
+        if let Some(route) = &operation.route {
+            routes.push(route.clone());
+        }
+    }
+    routes.sort_by(|left, right| {
+        left.route
+            .cmp(&right.route)
+            .then_with(|| left.operation.cmp(&right.operation))
+    });
+    files.push(GeneratedClientFile {
+        path: "commands.ts".into(),
+        contents: render_commands(manifest)?,
+    });
+    files.push(GeneratedClientFile {
+        path: "protocol.ts".into(),
+        contents: render_protocol(manifest)?,
+    });
+    files.push(GeneratedClientFile {
+        path: "routes.ts".into(),
+        contents: render_routes(&routes, &operations)?,
+    });
+    files.push(GeneratedClientFile {
+        path: "sveltekit.ts".into(),
+        contents: render_sveltekit(manifest, &operations)?,
+    });
+    files.push(GeneratedClientFile {
+        path: "index.ts".into(),
+        contents: render_index(&operations),
+    });
+    files.push(GeneratedClientFile {
+        path: "manifest.json".into(),
+        contents: render_compiler_manifest(manifest, &summaries, &routes)?,
+    });
+    files.sort_by(|left, right| left.path.cmp(&right.path));
+
+    Ok(GeneratedClientProject {
+        files,
+        operations: summaries,
+        routes,
+        schema_fingerprint: manifest.schema_fingerprint.clone(),
+        protocol_fingerprint: manifest.protocol_fingerprint.clone(),
+    })
+}
+fn render_protocol(manifest: &ClientManifest) -> Result<String, ClientCompileError> {
+    let operations =
+        serde_json::to_string_pretty(&manifest.protocol_operations).map_err(|error| {
+            ClientCompileError::manifest(
+                "client.render.protocol",
+                format!("failed to render protocol artifacts: {error}"),
+            )
+        })?;
+    let trusted_presets =
+        serde_json::to_string_pretty(&manifest.trusted_presets).map_err(|error| {
+            ClientCompileError::manifest(
+                "client.render.trusted_presets",
+                format!("failed to render trusted-preset inventory: {error}"),
+            )
+        })?;
+    let mut sections =
+        vec!["/** GENERATED by dctl client. Exact framework-owned operation bytes. */".to_string()];
+    if manifest.protocol_operations.command_status.is_some() {
+        sections.push(
+            "import type { ReplicaCommandStatusArtifact } from '@hops-ops/distributed/replica';"
+                .into(),
+        );
+    }
+    sections.push(format!(
+        "export const CLIENT_PROTOCOL = {{\n\
+         \tversion: 1,\n\
+         \tserviceId: {},\n\
+         \tschemaHash: {},\n\
+         \tprotocolHash: {},\n\
+         \tsurface: {},\n\
+         \ttrustedPresets: {trusted_presets},\n\
+         \toperations: {operations}\n\
+         }} as const;",
+        json_string(&manifest.service_id)?,
+        json_string(&manifest.schema_fingerprint)?,
+        json_string(&manifest.protocol_fingerprint)?,
+        serde_json::to_string(&manifest.surface).map_err(|error| {
+            ClientCompileError::manifest(
+                "client.render.protocol",
+                format!("failed to render client surface selector: {error}"),
+            )
+        })?,
+    ));
+    if let Some(status) = &manifest.protocol_operations.command_status {
+        let artifact = canonical_json_value(serde_json::json!({
+            "name": &status.name,
+            "document": &status.operation,
+            "operationHash": &status.operation_hash,
+            "protocol": {
+                "version": 1,
+                "schemaHash": &manifest.schema_fingerprint,
+                "protocolHash": &manifest.protocol_fingerprint,
+                "surface": &manifest.surface,
+                "operation": &status.operation_hash,
+                "trustedPresets": &manifest.trusted_presets,
+            }
+        }));
+        let artifact = serde_json::to_string_pretty(&artifact).map_err(|error| {
+            ClientCompileError::manifest(
+                "client.render.command_status",
+                format!("failed to render command-status artifact: {error}"),
+            )
+        })?;
+        sections.push(format!(
+            "/** Exact compiler-owned operation used to recover ambiguous command outcomes. */\n\
+             export const COMMAND_STATUS: ReplicaCommandStatusArtifact = {artifact};"
+        ));
+    }
+    Ok(format!("{}\n", sections.join("\n\n")))
+}
+
+#[derive(Serialize)]
+struct CompilerManifest<'a> {
+    compiler_manifest_version: u32,
+    distributed_manifest_version: u32,
+    protocol_version: u32,
+    service_id: &'a str,
+    surface: &'a super::super::manifest::ManifestSurface,
+    schema_fingerprint: &'a str,
+    protocol_fingerprint: &'a str,
+    scalar_codecs: &'a BTreeMap<String, String>,
+    commands_requiring_revalidation: &'a BTreeSet<String>,
+    operations: &'a [GeneratedOperationSummary],
+    routes: &'a [GeneratedRoutePlan],
+}
+
+fn render_compiler_manifest(
+    manifest: &ClientManifest,
+    operations: &[GeneratedOperationSummary],
+    routes: &[GeneratedRoutePlan],
+) -> Result<String, ClientCompileError> {
+    let provenance = CompilerManifest {
+        compiler_manifest_version: 1,
+        distributed_manifest_version: 1,
+        protocol_version: 1,
+        service_id: &manifest.service_id,
+        surface: &manifest.surface,
+        schema_fingerprint: &manifest.schema_fingerprint,
+        protocol_fingerprint: &manifest.protocol_fingerprint,
+        scalar_codecs: &manifest.scalar_codecs,
+        commands_requiring_revalidation: &manifest.commands_requiring_revalidation,
+        operations,
+        routes,
+    };
+    serde_json::to_string_pretty(&provenance)
+        .map(|rendered| format!("{rendered}\n"))
+        .map_err(|error| {
+            ClientCompileError::manifest(
+                "client.render.manifest",
+                format!("failed to render compiler provenance manifest: {error}"),
+            )
+        })
+}
+
+fn render_routes(
+    routes: &[GeneratedRoutePlan],
+    operations: &[CompiledOperation],
+) -> Result<String, ClientCompileError> {
+    let routes_json = serde_json::to_string_pretty(routes).map_err(|error| {
+        ClientCompileError::manifest(
+            "client.render.routes",
+            format!("failed to render route plan: {error}"),
+        )
+    })?;
+    let mut imports = Vec::new();
+    let mut bindings = Vec::new();
+    for (index, route) in routes.iter().enumerate() {
+        let operation = operations
+            .iter()
+            .find(|operation| operation.name == route.operation)
+            .ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.render.routes",
+                    format!(
+                        "route `{}` references missing operation `{}`",
+                        route.route, route.operation
+                    ),
+                )
+            })?;
+        let module = operation
+            .module_path
+            .strip_suffix(".ts")
+            .expect("compiler module paths end in .ts");
+        imports.push(format!(
+            "import {{ {} }} from './{module}.js';",
+            operation.export_name
+        ));
+        bindings.push(format!(
+            "  {{ plan: DISTRIBUTED_ROUTES[{index}], artifact: {} }}",
+            operation.export_name
+        ));
+    }
+    let import_section = if imports.is_empty() {
+        String::new()
+    } else {
+        format!("{}\n\n", imports.join("\n"))
+    };
+    let bindings = if bindings.is_empty() {
+        "[]".to_string()
+    } else {
+        format!("[\n{}\n]", bindings.join(",\n"))
+    };
+    Ok(format!(
+        "{import_section}\
+         /** GENERATED framework-neutral `@load` ownership plan. */\n\
+         export const DISTRIBUTED_ROUTES = {routes_json} as const;\n\
+         \n\
+         /** Static route-to-artifact bindings consumed by framework SSR adapters. */\n\
+         export const DISTRIBUTED_ROUTE_OPERATIONS = {bindings} as const;\n\
+         \n\
+         export type DistributedRoutePlan = (typeof DISTRIBUTED_ROUTES)[number];\n\
+         export type DistributedRouteOperation = (typeof DISTRIBUTED_ROUTE_OPERATIONS)[number];\n"
+    ))
+}
+
+fn render_index(operations: &[CompiledOperation]) -> String {
+    let mut lines = vec![
+        "/** GENERATED public entrypoint. */".to_string(),
+        "export * from './commands.js';".into(),
+        "export * from './protocol.js';".into(),
+        "export * from './routes.js';".into(),
+    ];
+    for operation in operations {
+        let module = operation
+            .module_path
+            .strip_suffix(".ts")
+            .expect("compiler module paths end in .ts");
+        lines.push(format!("export * from './{module}.js';"));
+    }
+    format!("{}\n", lines.join("\n"))
+}
+
+fn render_sveltekit(
+    manifest: &ClientManifest,
+    operations: &[CompiledOperation],
+) -> Result<String, ClientCompileError> {
+    if let Some(operation) = operations
+        .iter()
+        .find(|operation| !typescript_value_binding(&operation.name))
+    {
+        return Err(ClientCompileError::source(
+            "client.operation.sveltekit_identifier",
+            format!(
+                "operation `{}` cannot be exported as a `$distributed` value because it is reserved in JavaScript/TypeScript; rename the operation",
+                operation.name
+            ),
+            &operation.source_path,
+            operation.source_line,
+            operation.source_column,
+        ));
+    }
+
+    let mut value_exports = BTreeSet::from([
+        "COMMAND_ARTIFACTS".to_string(),
+        "COMMANDS".to_string(),
+        "DISTRIBUTED_ROUTES".to_string(),
+        "DISTRIBUTED_ROUTE_OPERATIONS".to_string(),
+        "PROJECTOR_ARTIFACTS".to_string(),
+        "provideDistributed".to_string(),
+        "useCommands".to_string(),
+    ]);
+    if !manifest.commands.is_empty() {
+        value_exports.insert("createCommands".into());
+    }
+    for command in &manifest.commands {
+        value_exports.insert(format!("Command_{}", command.mutation_field));
+        value_exports.insert(format!("prepareCommand_{}", command.mutation_field));
+    }
+    for operation in operations {
+        value_exports.insert(operation.export_name.clone());
+        value_exports.insert(format!("{}Document", operation.export_name));
+    }
+    if let Some(operation) = operations
+        .iter()
+        .find(|operation| value_exports.contains(&operation.name))
+    {
+        return Err(ClientCompileError::source(
+            "client.operation.sveltekit_export_collision",
+            format!(
+                "operation `{}` collides with the generated `$distributed` export namespace; rename the operation",
+                operation.name
+            ),
+            &operation.source_path,
+            operation.source_line,
+            operation.source_column,
+        ));
+    }
+
+    let mut sections = vec![
+        "/** GENERATED by dctl client. Do not edit. */".to_string(),
+        [
+            "import {",
+            "  createDistributedSvelteKit,",
+            "  defineDistributedSvelteKitOperation,",
+            "  provideDistributedSvelteKitClient,",
+            "  useDistributedSvelteKitCommands",
+            "} from '@hops-ops/distributed/sveltekit';",
+            "",
+            "import type {",
+            "  CreateDistributedSvelteKitOptions,",
+            "  DistributedSvelteKitClient",
+            "} from '@hops-ops/distributed/sveltekit';",
+        ]
+        .join("\n"),
+    ];
+
+    if manifest.commands.is_empty() {
+        sections
+            .push("export type GeneratedCommands = Readonly<Record<never, never>>;".to_string());
+    } else {
+        sections.push(
+            [
+                "import { createCommands as createGeneratedCommands } from './commands.js';",
+                "import type { GeneratedCommands as ServiceGeneratedCommands } from './commands.js';",
+                "",
+                "export type GeneratedCommands = ServiceGeneratedCommands;",
+            ]
+            .join("\n"),
+        );
+    }
+
+    for (index, operation) in operations.iter().enumerate() {
+        let module = operation
+            .module_path
+            .strip_suffix(".ts")
+            .expect("compiler module paths end in .ts");
+        sections.push(format!(
+            "import {{ {} as DistributedOperation_{index} }} from './{module}.js';",
+            operation.export_name
+        ));
+    }
+
+    sections.push(
+        [
+            "/** Inspectable framework-neutral artifacts remain available here. */",
+            "export * from './index.js';",
+        ]
+        .join("\n"),
+    );
+
+    for (index, operation) in operations.iter().enumerate() {
+        sections.push(format!(
+            "/** Tree-local Svelte binding for the generated `{}` artifact. */\nexport const {} = defineDistributedSvelteKitOperation(DistributedOperation_{index});",
+            operation.name, operation.name
+        ));
+    }
+
+    let mut bindings = vec![
+        "/**".to_string(),
+        " * Create and install one component-tree/request-local generated client.".to_string(),
+        " * No client or command proxy is retained by this module.".to_string(),
+        " */".to_string(),
+        "export function provideDistributed(".to_string(),
+        "  options: Omit<CreateDistributedSvelteKitOptions<GeneratedCommands>, 'createCommands'>"
+            .to_string(),
+        "): DistributedSvelteKitClient<GeneratedCommands> {".to_string(),
+        "  return provideDistributedSvelteKitClient(".to_string(),
+        "    createDistributedSvelteKit<GeneratedCommands>({".to_string(),
+    ];
+    if manifest.commands.is_empty() {
+        bindings.push("      ...options".to_string());
+    } else {
+        bindings.push("      ...options,".to_string());
+        bindings.push("      createCommands: createGeneratedCommands".to_string());
+    }
+    bindings.extend(
+        [
+            "    })",
+            "  );",
+            "}",
+            "",
+            "/** Resolve the nearest generated command surface during component initialization. */",
+            "export function useCommands(): GeneratedCommands {",
+            "  return useDistributedSvelteKitCommands<GeneratedCommands>();",
+            "}",
+        ]
+        .into_iter()
+        .map(str::to_string),
+    );
+    sections.push(bindings.join("\n"));
+
+    Ok(format!("{}\n", sections.join("\n\n")))
+}
+
+fn typescript_value_binding(name: &str) -> bool {
+    // GraphQL already guarantees the identifier grammar. This list closes the
+    // remaining JavaScript strict-mode and TypeScript keyword/contextual traps.
+    !matches!(
+        name,
+        "abstract"
+            | "any"
+            | "arguments"
+            | "as"
+            | "asserts"
+            | "async"
+            | "await"
+            | "bigint"
+            | "boolean"
+            | "break"
+            | "case"
+            | "catch"
+            | "class"
+            | "const"
+            | "constructor"
+            | "continue"
+            | "debugger"
+            | "declare"
+            | "default"
+            | "delete"
+            | "do"
+            | "else"
+            | "enum"
+            | "eval"
+            | "export"
+            | "extends"
+            | "false"
+            | "finally"
+            | "for"
+            | "from"
+            | "function"
+            | "get"
+            | "global"
+            | "if"
+            | "implements"
+            | "import"
+            | "in"
+            | "infer"
+            | "instanceof"
+            | "interface"
+            | "intrinsic"
+            | "is"
+            | "keyof"
+            | "let"
+            | "module"
+            | "namespace"
+            | "never"
+            | "new"
+            | "null"
+            | "number"
+            | "object"
+            | "of"
+            | "out"
+            | "override"
+            | "package"
+            | "private"
+            | "protected"
+            | "public"
+            | "readonly"
+            | "require"
+            | "return"
+            | "satisfies"
+            | "set"
+            | "static"
+            | "string"
+            | "super"
+            | "switch"
+            | "symbol"
+            | "this"
+            | "throw"
+            | "true"
+            | "try"
+            | "type"
+            | "typeof"
+            | "undefined"
+            | "unique"
+            | "unknown"
+            | "using"
+            | "var"
+            | "void"
+            | "while"
+            | "with"
+            | "yield"
+    )
+}
diff --git a/distributed_cli/src/client_compiler/render/typescript.rs b/distributed_cli/src/client_compiler/render/typescript.rs
new file mode 100644
index 00000000..7b9149b6
--- /dev/null
+++ b/distributed_cli/src/client_compiler/render/typescript.rs
@@ -0,0 +1,287 @@
+use super::super::graphql::{
+    typescript_scalar, Cardinality, CompiledFilterInputField, CompiledFilterInputTarget,
+    CompiledInputDefinition, CompiledInputType, CompiledMember, CompiledObject, CompiledOperation,
+};
+use super::super::ClientCompileError;
+use super::common::{json_string, quoted_property};
+
+pub(super) fn render_variables_type(
+    operation: &CompiledOperation,
+    name: &str,
+) -> Result<String, ClientCompileError> {
+    if operation.variables.is_empty() {
+        return Ok(format!("export type {name} = Record<string, never>;"));
+    }
+    let mut blocks = operation
+        .variable_codec
+        .inputs
+        .iter()
+        .map(|(input_name, definition)| {
+            render_input_definition(&operation.export_name, input_name, definition)
+        })
+        .collect::<Result<Vec<_>, _>>()?;
+
+    let mut lines = vec![format!("export type {name} = {{")];
+    for variable in &operation.variables {
+        let input_type = operation
+            .variable_codec
+            .variables
+            .get(&variable.name)
+            .ok_or_else(|| {
+                ClientCompileError::manifest(
+                    "client.render.variable_codec",
+                    format!(
+                        "operation `{}` has no codec for variable `${}`",
+                        operation.name, variable.name
+                    ),
+                )
+            })?;
+        lines.push(format!(
+            "  readonly {}{}: {};",
+            quoted_property(&variable.name),
+            if variable.graphql_type.nullable {
+                "?"
+            } else {
+                ""
+            },
+            render_input_type(&operation.export_name, input_type)?
+        ));
+    }
+    lines.push("};".into());
+    blocks.push(lines.join("\n"));
+    Ok(blocks.join("\n\n"))
+}
+
+fn render_input_definition(
+    operation: &str,
+    name: &str,
+    definition: &CompiledInputDefinition,
+) -> Result<String, ClientCompileError> {
+    let alias = input_alias(operation, name);
+    match definition {
+        CompiledInputDefinition::Filter {
+            fields,
+            relationships,
+            ..
+        } => {
+            let mut lines = vec![format!("type {alias} = {{")];
+            for operator in ["_and", "_or"] {
+                lines.push(format!(
+                    "  readonly {}?: {alias} | readonly {alias}[] | null;",
+                    quoted_property(operator)
+                ));
+            }
+            lines.push(format!(
+                "  readonly {}?: {alias} | null;",
+                quoted_property("_not")
+            ));
+            for field in fields {
+                lines.push(format!(
+                    "  readonly {}?: {};",
+                    quoted_property(&field.field),
+                    render_filter_comparison(field)?
+                ));
+            }
+            for relationship in relationships {
+                let target = match &relationship.target {
+                    CompiledFilterInputTarget::Input { name } => input_alias(operation, name),
+                    CompiledFilterInputTarget::Opaque => {
+                        "{ readonly [key: string]: ReplicaValue }".into()
+                    }
+                };
+                lines.push(format!(
+                    "  readonly {}?: {target} | null;",
+                    quoted_property(&relationship.field)
+                ));
+            }
+            lines.push("};".into());
+            Ok(lines.join("\n"))
+        }
+        CompiledInputDefinition::Order { fields, values, .. } => {
+            let direction = format!("{alias}_Direction");
+            let direction_type = render_string_union(values)?;
+            let mut lines = vec![format!("type {direction} = {direction_type};")];
+            if fields.is_empty() {
+                lines.push(format!("type {alias} = never;"));
+            } else {
+                lines.push(format!("type {alias} ="));
+                for (index, field) in fields.iter().enumerate() {
+                    lines.push("  | {".into());
+                    for candidate in fields {
+                        let property = quoted_property(&candidate.field);
+                        if candidate.field == field.field {
+                            lines.push(format!("      readonly {property}: {direction};"));
+                        } else {
+                            lines.push(format!("      readonly {property}?: never;"));
+                        }
+                    }
+                    lines.push(if index + 1 == fields.len() {
+                        "    };".into()
+                    } else {
+                        "    }".into()
+                    });
+                }
+            }
+            Ok(lines.join("\n"))
+        }
+    }
+}
+
+fn render_filter_comparison(
+    field: &CompiledFilterInputField,
+) -> Result<String, ClientCompileError> {
+    let scalar = typescript_input_scalar(&field.scalar, &field.codec)?;
+    let mut lines = vec!["{".to_string()];
+    for operator in &field.operators {
+        let value = match operator.as_str() {
+            "_is_null" => "boolean | null".into(),
+            "_in" | "_nin" => format!("{scalar} | readonly {}[]", parenthesize_ts_union(scalar)),
+            "_has_key" => "string | null".into(),
+            _ => format!("{scalar} | null"),
+        };
+        lines.push(format!(
+            "    readonly {}?: {value};",
+            quoted_property(operator)
+        ));
+    }
+    lines.push("  } | null".into());
+    Ok(lines.join("\n"))
+}
+
+fn render_input_type(
+    operation: &str,
+    input_type: &CompiledInputType,
+) -> Result<String, ClientCompileError> {
+    let (base, nullable) = match input_type {
+        CompiledInputType::Scalar {
+            scalar,
+            codec,
+            nullable,
+        } => (
+            typescript_input_scalar(scalar, codec)?.to_string(),
+            *nullable,
+        ),
+        CompiledInputType::Enum {
+            values, nullable, ..
+        } => (render_string_union(values)?, *nullable),
+        CompiledInputType::Input { name, nullable, .. } => {
+            (input_alias(operation, name), *nullable)
+        }
+        CompiledInputType::List { nullable, item, .. } => {
+            let item = render_input_type(operation, item)?;
+            (
+                format!("{item} | readonly {}[]", parenthesize_ts_union(&item)),
+                *nullable,
+            )
+        }
+    };
+    Ok(if nullable {
+        format!("{base} | null")
+    } else {
+        base
+    })
+}
+
+fn typescript_input_scalar(scalar: &str, codec: &str) -> Result<&'static str, ClientCompileError> {
+    match (scalar, codec) {
+        ("ID", "string") => Ok("string | number"),
+        ("String", "string")
+        | ("Bytea", "base64")
+        | ("Timestamptz", "string_unvalidated_timestamp") => Ok("string"),
+        ("Boolean", "boolean") => Ok("boolean"),
+        ("Int", "int32") | ("Float", "float64") | ("BigInt", "json_number_precision_limited") => {
+            Ok("number")
+        }
+        ("JSON", "json") => Ok("ReplicaValue"),
+        _ => Err(ClientCompileError::manifest(
+            "client.scalar.codec_unsupported",
+            format!("scalar `{scalar}` uses unsupported input codec `{codec}`"),
+        )),
+    }
+}
+
+fn render_string_union(values: &[String]) -> Result<String, ClientCompileError> {
+    if values.is_empty() {
+        return Err(ClientCompileError::manifest(
+            "client.render.input_enum",
+            "generated input enum must contain at least one value",
+        ));
+    }
+    values
+        .iter()
+        .map(|value| json_string(value))
+        .collect::<Result<Vec<_>, _>>()
+        .map(|values| values.join(" | "))
+}
+
+fn input_alias(operation: &str, input: &str) -> String {
+    format!("{operation}_Input_{input}")
+}
+
+fn parenthesize_ts_union(value: &str) -> String {
+    if value.contains(" | ") {
+        format!("({value})")
+    } else {
+        value.to_string()
+    }
+}
+
+pub(super) fn render_data_type(
+    operation: &CompiledOperation,
+    name: &str,
+) -> Result<String, ClientCompileError> {
+    let root = &operation.root;
+    let entity = render_object_type(&root.selection, 2)?;
+    let value = match root.cardinality {
+        Cardinality::Many => format!("readonly {entity}[]"),
+        Cardinality::One => {
+            if root.nullable {
+                format!("{entity} | null")
+            } else {
+                entity
+            }
+        }
+    };
+    Ok(format!(
+        "export type {name} = {{\n  readonly {}: {};\n}};",
+        quoted_property(&root.response_key),
+        value
+    ))
+}
+
+fn render_object_type(
+    object: &CompiledObject,
+    indent: usize,
+) -> Result<String, ClientCompileError> {
+    let member_padding = " ".repeat(indent + 2);
+    let closing_padding = " ".repeat(indent);
+    let mut lines = vec!["{".to_string()];
+    for member in &object.members {
+        match member {
+            CompiledMember::Scalar(field) if field.expose => {
+                let scalar = typescript_scalar(field)?;
+                lines.push(format!(
+                    "{member_padding}readonly {}: {}{};",
+                    quoted_property(&field.response_key),
+                    scalar,
+                    if field.nullable { " | null" } else { "" }
+                ));
+            }
+            CompiledMember::Scalar(_) => {}
+            CompiledMember::Branch(branch) => {
+                let object = render_object_type(&branch.selection, indent + 2)?;
+                let value = match branch.cardinality {
+                    Cardinality::Many => format!("readonly {object}[]"),
+                    Cardinality::One if branch.nullable => format!("{object} | null"),
+                    Cardinality::One => object,
+                };
+                lines.push(format!(
+                    "{member_padding}readonly {}: {value};",
+                    quoted_property(&branch.response_key)
+                ));
+            }
+        }
+    }
+    lines.push(format!("{closing_padding}}}"));
+    Ok(lines.join("\n"))
+}
diff --git a/distributed_cli/src/client_compiler/runtime_bridge_tests.rs b/distributed_cli/src/client_compiler/runtime_bridge_tests.rs
new file mode 100644
index 00000000..751dbd5a
--- /dev/null
+++ b/distributed_cli/src/client_compiler/runtime_bridge_tests.rs
@@ -0,0 +1,63 @@
+use std::collections::BTreeMap;
+
+use super::graphql::{compile_document, CompiledOperation};
+use super::manifest::ClientManifest;
+use super::render::{render_operation_artifact_json, render_operation_module};
+use super::tests::manifest;
+use super::{ClientDocument, ClientSurfaceSelector};
+
+const RUNTIME_BRIDGE_QUERY: &str = r#"
+  query RustRuntimeBridge($id: ID!, $tenantId: ID!) {
+    todo(id: $id, tenantId: $tenantId) {
+      id
+      title
+    }
+  }
+"#;
+
+fn compile_runtime_bridge_operation() -> (ClientManifest, CompiledOperation) {
+    let manifest = ClientManifest::parse(manifest(), &ClientSurfaceSelector::role("user"))
+        .expect("runtime bridge manifest");
+    let document = ClientDocument::new(
+        "src/routes/runtime-bridge/+page.graphql",
+        RUNTIME_BRIDGE_QUERY,
+    );
+    let operation = compile_document(&document, &manifest, &BTreeMap::new())
+        .expect("compile runtime bridge operation");
+    (manifest, operation)
+}
+
+fn rust_runtime_bridge_artifact() -> String {
+    let (manifest, operation) = compile_runtime_bridge_operation();
+    let artifact = render_operation_artifact_json(&operation, &manifest)
+        .expect("serialize runtime bridge operation artifact");
+    format!("{artifact}\n")
+}
+
+#[test]
+fn rust_emitted_runtime_bridge_artifact_is_byte_exact() {
+    assert_eq!(
+        rust_runtime_bridge_artifact(),
+        include_str!("../../tests/fixtures/runtime-bridge-operation.json"),
+        "the JavaScript runtime bridge fixture must remain exact Rust compiler output"
+    );
+}
+
+#[test]
+fn scalar_only_operation_module_is_byte_exact_and_needs_no_replica_value_import() {
+    let (manifest, operation) = compile_runtime_bridge_operation();
+    let module = render_operation_module(&operation, &manifest)
+        .expect("render scalar-only operation module");
+assert_eq!(
+        module,
+        include_str!("../../tests/fixtures/generated-scalar-operation.ts"),
+        "the strict TypeScript scalar-only fixture must remain exact Rust compiler output"
+    );
+    assert!(
+        module.contains(
+            "import type { ReplicaOperationArtifact } from '@hops-ops/distributed/replica';"
+        ),
+        "{module}"
+    );
+    assert!(!module.contains("ReplicaValue"), "{module}");
+}
diff --git a/distributed_cli/src/client_compiler/tests.rs b/distributed_cli/src/client_compiler/tests.rs
new file mode 100644
index 00000000..109c99f8
--- /dev/null
+++ b/distributed_cli/src/client_compiler/tests.rs
@@ -0,0 +1,2980 @@
+use serde_json::{json, Value as JsonValue};
+use sha2::{Digest, Sha256};
+
+use super::manifest::{refresh_schema_fingerprint, ClientManifest};
+use super::{
+    compile_client, ClientCompileInput, ClientDocument, ClientRouteDiscovery,
+    ClientRouteRegistration, ClientSurfaceSelector,
+};
+
+fn fingerprint(label: &str) -> String {
+    let digest = Sha256::digest(label.as_bytes());
+    format!("sha256:{digest:x}")
+}
+
+fn scalar_codecs() -> JsonValue {
+    json!([
+        {"scalar": "BigInt", "codec": "json_number_precision_limited"},
+        {"scalar": "Boolean", "codec": "boolean"},
+        {"scalar": "Bytea", "codec": "base64"},
+        {"scalar": "Float", "codec": "float64"},
+        {"scalar": "ID", "codec": "string"},
+        {"scalar": "Int", "codec": "int32"},
+        {"scalar": "JSON", "codec": "json"},
+        {"scalar": "String", "codec": "string"},
+        {"scalar": "Timestamptz", "codec": "string_unvalidated_timestamp"}
+    ])
+}
+
+fn model(id: &str, typename: &str) -> JsonValue {
+    let filter_input_type = format!("{typename}_bool_exp");
+    json!({
+        "id": id,
+        "typename": typename,
+        "source_table": format!("{}_rows", id.to_lowercase()),
+        "dependencies": [format!("{}_rows", id.to_lowercase())],
+        "normalization": {
+            "kind": "normalized",
+            "fields": [
+                {"name": "tenantId", "codec": "string"},
+                {"name": "id", "codec": "string"}
+            ],
+            "encoding": "canonical_json_tuple_v1"
+        },
+        "fields": [
+            {"name": "completed", "scalar": "Boolean", "codec": "boolean", "nullable": false},
+            {"name": "id", "scalar": "ID", "codec": "string", "nullable": false},
+            {"name": "priority", "scalar": "Int", "codec": "int32", "nullable": false},
+            {"name": "tenantId", "scalar": "ID", "codec": "string", "nullable": false},
+            {"name": "title", "scalar": "String", "codec": "string", "nullable": true}
+        ],
+        "relationships": [
+            {
+                "name": "owner",
+                "target_model": id,
+                "target_typename": typename,
+                "kind": "belongs_to",
+                "list": false,
+                "nullable": true,
+                "arguments": [],
+                "key_mapping": {"kind": "embedded"},
+                "maintenance": "revalidate",
+                "dependencies": [format!("{}_rows", id.to_lowercase())],
+                "live": false
+            }
+        ],
+        "filter_input": {
+            "type_name": filter_input_type,
+            "fields": filter_semantics()["fields"].clone(),
+            "relationships": [
+                {"field": "owner", "target_type": filter_input_type}
+            ]
+        },
+        "row_policy": {"kind": "unrestricted"},
+        "record_revisions": true,
+        "tombstones": true
+    })
+}
+
+fn list_arguments() -> JsonValue {
+    json!([
+        {
+            "name": "where",
+            "kind": "filter",
+            "type_name": "todo_bool_exp",
+            "nullable": true,
+            "list": false
+        },
+        {
+            "name": "order_by",
+            "kind": "order",
+            "type_name": "todo_order_by",
+            "nullable": true,
+            "list": true
+        },
+        {
+            "name": "limit",
+            "kind": "limit",
+            "type_name": "Int",
+            "nullable": true,
+            "list": false,
+            "codec": "int32"
+        },
+        {
+            "name": "offset",
+            "kind": "offset",
+            "type_name": "Int",
+            "nullable": true,
+            "list": false,
+            "codec": "int32"
+        }
+    ])
+}
+
+fn filter_semantics() -> JsonValue {
+    json!({
+        "fields": [
+            {"name": "completed", "operators": ["_eq"]},
+            {"name": "id", "operators": ["_eq"]},
+            {"name": "priority", "operators": ["_eq", "_in", "_nin"]},
+            {"name": "tenantId", "operators": ["_eq"]},
+            {"name": "title", "operators": ["_eq"]}
+        ],
+        "relationships": ["owner"],
+        "row_policy": {"kind": "unrestricted"}
+    })
+}
+
+fn order_semantics() -> JsonValue {
+    json!({
+        "fields": ["completed", "id", "priority", "tenantId", "title"],
+        "values": [
+            "asc",
+            "asc_nulls_first",
+            "asc_nulls_last",
+            "desc",
+            "desc_nulls_first",
+            "desc_nulls_last"
+        ]
+    })
+}
+
+fn normalized_list_relationship() -> JsonValue {
+    json!({
+        "name": "owner",
+        "target_model": "Todo",
+        "target_typename": "todo",
+        "kind": "has_many",
+        "list": true,
+        "nullable": false,
+        "arguments": list_arguments(),
+        "key_mapping": {
+            "kind": "direct",
+            "local": ["tenantId", "id"],
+            "remote": ["tenantId", "id"]
+        },
+        "maintenance": "local",
+        "dependencies": ["todo_rows"],
+        "filter": filter_semantics(),
+        "order": order_semantics(),
+        "pagination": {
+            "kind": "offset",
+            "default_limit": 25,
+            "max_limit": 100,
+            "coverage": "window"
+        },
+        "aggregate": null,
+        "live": true
+    })
+}
+
+fn list_root(operation: &str) -> JsonValue {
+    json!({
+        "id": format!("{operation}:todos"),
+        "operation": operation,
+        "name": "todos",
+        "kind": "list",
+        "model": "Todo",
+        "arguments": list_arguments(),
+        "filter": filter_semantics(),
+        "order": order_semantics(),
+        "pagination": {
+            "kind": "offset",
+            "default_limit": 25,
+            "max_limit": 100,
+            "coverage": "window"
+        },
+        "aggregate": null,
+        "dependencies": ["todo_rows"],
+        "live": true
+    })
+}
+
+fn by_pk_root() -> JsonValue {
+    json!({
+        "id": "query:todo",
+        "operation": "query",
+        "name": "todo",
+        "kind": "by_pk",
+        "model": "Todo",
+        "arguments": [
+            {
+                "name": "tenantId",
+                "kind": "primary_key",
+                "type_name": "ID",
+                "nullable": false,
+                "list": false,
+                "codec": "string"
+            },
+            {
+                "name": "id",
+                "kind": "primary_key",
+                "type_name": "ID",
+                "nullable": false,
+                "list": false,
+                "codec": "string"
+            }
+        ],
+        "filter": null,
+        "order": null,
+        "pagination": null,
+        "aggregate": null,
+        "dependencies": ["todo_rows"],
+        "live": false
+    })
+}
+
+fn aggregate_root() -> JsonValue {
+    json!({
+        "id": "query:todos_aggregate",
+        "operation": "query",
+        "name": "todos_aggregate",
+        "kind": "aggregate",
+        "model": "Todo",
+        "arguments": [{
+            "name": "where",
+            "kind": "filter",
+            "type_name": "todo_bool_exp",
+            "nullable": true,
+            "list": false
+        }],
+        "filter": filter_semantics(),
+        "order": null,
+        "pagination": null,
+        "aggregate": {
+            "wrapper_typename": "todo_aggregate",
+            "fields_typename": "todo_aggregate_fields",
+            "nodes_pagination": {
+                "kind": "offset",
+                "default_limit": 25,
+                "max_limit": 100,
+                "coverage": "window"
+            },
+            "count": true,
+            "nodes": true,
+            "sum": [],
+            "avg": [],
+            "min": [],
+            "max": []
+        },
+        "dependencies": ["todo_rows"],
+        "live": false
+    })
+}
+
+pub(super) fn manifest() -> JsonValue {
+    let mut value = json!({
+        "manifest_version": 1,
+        "protocol_version": 1,
+        "service_id": "todos-service",
+        "surface": {"kind": "role", "name": "user"},
+        "schema_fingerprint": fingerprint("schema"),
+        "protocol_fingerprint": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+        "execution": {
+            "max_depth": 8,
+            "max_complexity": 500,
+            "max_bool_width": 256,
+            "max_in_list": 1000,
+            "complexity": {
+                "version": 1,
+                "scalar": 1,
+                "belongs_to": 2,
+                "has_many": 10,
+                "m2m": 12,
+                "aggregate": 8,
+                "list_root": 3,
+                "by_pk": 1,
+                "list_fanout": 5
+            }
+        },
+        "capabilities": {
+            "live_queries": true,
+            "record_revisions": true,
+            "tombstones": true,
+            "causal_receipts": false,
+            "live_resume": true,
+            "query_fallback": "revalidate",
+            "cache_scope": true,
+            "confirmed_persistence": false
+        },
+        "scalar_codecs": scalar_codecs(),
+        "models": [model("Todo", "todo")],
+        "roots": [
+            list_root("query"),
+            list_root("subscription"),
+            by_pk_root(),
+            aggregate_root()
+        ],
+        "commands": [],
+        "protocol_operations": {"version": 1},
+        "projectors": []
+    });
+    refresh_schema_fingerprint(&mut value);
+    value
+}
+
+fn custom_scalar_manifest() -> JsonValue {
+    let mut value = manifest();
+    value["models"][0]["fields"]
+        .as_array_mut()
+        .expect("model fields")
+        .extend([
+            json!({"name": "blob", "scalar": "Bytea", "codec": "base64", "nullable": true}),
+            json!({"name": "payload", "scalar": "JSON", "codec": "json", "nullable": true}),
+            json!({"name": "sequence", "scalar": "BigInt", "codec": "json_number_precision_limited", "nullable": false}),
+            json!({"name": "updatedAt", "scalar": "Timestamptz", "codec": "string_unvalidated_timestamp", "nullable": true}),
+        ]);
+    value["models"][0]["filter_input"]["fields"]
+        .as_array_mut()
+        .expect("model filter input fields")
+        .extend([
+            json!({"name": "blob", "operators": ["_eq"]}),
+            json!({"name": "payload", "operators": ["_eq"]}),
+            json!({"name": "sequence", "operators": ["_eq", "_in"]}),
+            json!({"name": "updatedAt", "operators": ["_eq"]}),
+        ]);
+    for root in value["roots"].as_array_mut().expect("manifest roots") {
+        if let Some(fields) = root
+            .get_mut("filter")
+            .and_then(JsonValue::as_object_mut)
+            .and_then(|filter| filter.get_mut("fields"))
+            .and_then(JsonValue::as_array_mut)
+        {
+            fields.extend([
+                json!({"name": "blob", "operators": ["_eq"]}),
+                json!({"name": "payload", "operators": ["_eq"]}),
+                json!({"name": "sequence", "operators": ["_eq", "_in"]}),
+                json!({"name": "updatedAt", "operators": ["_eq"]}),
+            ]);
+        }
+        if let Some(fields) = root
+            .get_mut("order")
+            .and_then(JsonValue::as_object_mut)
+            .and_then(|order| order.get_mut("fields"))
+            .and_then(JsonValue::as_array_mut)
+        {
+            fields.extend(["blob", "payload", "sequence", "updatedAt"].map(JsonValue::from));
+        }
+    }
+    refresh_schema_fingerprint(&mut value);
+    value
+}
+
+fn literal_scalar_manifest() -> JsonValue {
+    let mut value = custom_scalar_manifest();
+    value["models"][0]["fields"]
+        .as_array_mut()
+        .expect("model fields")
+        .push(json!({
+            "name": "ratio",
+            "scalar": "Float",
+            "codec": "float64",
+            "nullable": false
+        }));
+    value["models"][0]["filter_input"]["fields"]
+        .as_array_mut()
+        .expect("model filter input fields")
+        .push(json!({"name": "ratio", "operators": ["_eq"]}));
+    for root in value["roots"].as_array_mut().expect("manifest roots") {
+        if let Some(fields) = root
+            .get_mut("filter")
+            .and_then(JsonValue::as_object_mut)
+            .and_then(|filter| filter.get_mut("fields"))
+            .and_then(JsonValue::as_array_mut)
+        {
+            fields.push(json!({"name": "ratio", "operators": ["_eq"]}));
+        }
+        if let Some(fields) = root
+            .get_mut("order")
+            .and_then(JsonValue::as_object_mut)
+            .and_then(|order| order.get_mut("fields"))
+            .and_then(JsonValue::as_array_mut)
+        {
+            fields.push(json!("ratio"));
+        }
+    }
+    refresh_schema_fingerprint(&mut value);
+    value
+}
+
+fn projected_manifest() -> JsonValue {
+    let mutation = "mutation Client_projectTodo($commandId: ID!, $input: ProjectTodoInput!) { projectTodo(commandId: $commandId, input: $input) { completed id priority tenantId title } }";
+    let status =
+        "query Distributed_CommandStatus($commandId: ID!) { commandStatus(commandId: $commandId) { state } }";
+    let mut value = manifest();
+    value["capabilities"]["causal_receipts"] = json!(true);
+    value["capabilities"]["cache_scope"] = json!(true);
+    value["commands"] = json!([{
+        "version": 1,
+        "name": "ProjectTodo",
+        "mutation_field": "projectTodo",
+        "grants": ["user"],
+        "input": {
+            "kind": "object",
+            "definition": {
+                "name": "ProjectTodoInput",
+                "fields": [
+                    {
+                        "name": "id",
+                        "type_name": "ID",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "string"
+                    },
+                    {
+                        "name": "tenantId",
+                        "type_name": "ID",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "string"
+                    }
+                ]
+            }
+        },
+        "output": {
+            "kind": "object",
+            "definition": {
+                "name": "todo",
+                "fields": [
+                    {
+                        "name": "completed",
+                        "type_name": "Boolean",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "boolean"
+                    },
+                    {
+                        "name": "id",
+                        "type_name": "ID",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "string"
+                    },
+                    {
+                        "name": "priority",
+                        "type_name": "Int",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "int32"
+                    },
+                    {
+                        "name": "tenantId",
+                        "type_name": "ID",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "string"
+                    },
+                    {
+                        "name": "title",
+                        "type_name": "String",
+                        "nullable": true,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "string"
+                    }
+                ]
+            }
+        },
+        "operation": mutation,
+        "operation_hash": fingerprint(mutation),
+        "extensions": {
+            "version": 1,
+            "consistency": {"version": 1, "kind": "projected"},
+            "direct_projection": {
+                "topology": {
+                    "version": 1,
+                    "name": "todos",
+                    "digest": fingerprint("todos topology")
+                },
+                "model": "Todo",
+                "partition": {"kind": "input", "path": ["tenantId"]},
+                "change_epoch": "todos-v1"
+            }
+        }
+    }]);
+    value["projectors"] = json!([{
+        "version": 1,
+        "name": "todos",
+        "facts": [],
+        "models": ["Todo"],
+        "dependencies": ["todo_rows"],
+        "causal_confirmation": false
+    }]);
+    value["protocol_operations"] = json!({
+        "version": 1,
+        "command_status": {
+            "name": "Distributed_CommandStatus",
+            "operation": status,
+            "operation_hash": fingerprint(status)
+        }
+    });
+    refresh_schema_fingerprint(&mut value);
+    value
+}
+
+fn generated_command_types_manifest() -> JsonValue {
+    let import = "mutation Client_importTodos($commandId: ID!, $input: ImportTodosInput!) { importTodos(commandId: $commandId, input: $input) { result } }";
+    let ping =
+        "mutation Client_pingTodos($commandId: ID!) { pingTodos(commandId: $commandId) { ok } }";
+    let mut value = projected_manifest();
+    value["commands"][0]["name"] = json!("todo.project");
+    value["commands"].as_array_mut().expect("commands").extend([
+        json!({
+            "version": 1,
+            "name": "todo.import",
+            "mutation_field": "importTodos",
+            "grants": ["user"],
+            "input": {
+                "kind": "object",
+                "definition": {
+                    "name": "ImportTodosInput",
+                    "fields": [{
+                        "name": "source",
+                        "type_name": "JSON",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "json"
+                    }]
+                }
+            },
+            "output": {
+                "kind": "object",
+                "definition": {
+                    "name": "ImportTodosPayload",
+                    "fields": [{
+                        "name": "result",
+                        "type_name": "JSON",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "json"
+                    }]
+                }
+            },
+            "operation": import,
+            "operation_hash": fingerprint(import),
+            "extensions": {
+                "version": 1,
+                "consistency": {"version": 1, "kind": "accepted"}
+            }
+        }),
+        json!({
+            "version": 1,
+            "name": "todo.ping",
+            "mutation_field": "pingTodos",
+            "grants": ["user"],
+            "input": {"kind": "none"},
+            "output": {
+                "kind": "object",
+                "definition": {
+                    "name": "PingTodosPayload",
+                    "fields": [{
+                        "name": "ok",
+                        "type_name": "Boolean",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "boolean"
+                    }]
+                }
+            },
+            "operation": ping,
+            "operation_hash": fingerprint(ping),
+            "extensions": {
+                "version": 1,
+                "consistency": {"version": 1, "kind": "accepted"}
+            }
+        }),
+    ]);
+    refresh_schema_fingerprint(&mut value);
+    value
+}
+
+#[test]
+fn rejects_legacy_top_level_json_command_shapes() {
+    for slot in ["input", "output"] {
+        let mut value = projected_manifest();
+        value["commands"][0][slot] = json!({"kind": "json", "codec": "json"});
+
+        let error = ClientManifest::parse(value, &ClientSurfaceSelector::role("user"))
+            .expect_err("top-level JSON command shapes were removed in manifest v7");
+        assert_eq!(error.code, "client.manifest.invalid");
+        assert!(error.message.contains("unknown variant `json`"));
+    }
+}
+
+fn input(source: &str) -> ClientCompileInput {
+    ClientCompileInput::new(
+        manifest(),
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/routes/todos/+page.graphql",
+            source,
+        )],
+    )
+}
+
+fn input_with_manifest(manifest: JsonValue, source: &str) -> ClientCompileInput {
+    ClientCompileInput::new(
+        manifest,
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/routes/todos/+page.graphql",
+            source,
+        )],
+    )
+}
+
+const CUSTOM_SCALAR_QUERY: &str = r#"
+  query ScalarInputs(
+    $where: todo_bool_exp!
+    $order: [todo_order_by!]
+    $id: ID!
+    $big: BigInt!
+    $bytes: Bytea
+    $json: JSON
+    $timestamp: Timestamptz
+  ) {
+    todos(
+      where: {
+        _and: [
+          $where,
+          {
+            id: {_eq: $id},
+            sequence: {_eq: $big},
+            blob: {_eq: $bytes},
+            payload: {_eq: $json},
+            updatedAt: {_eq: $timestamp}
+          }
+        ]
+      },
+      order_by: $order
+    ) { id }
+  }
+"#;
+
+fn custom_scalar_project() -> super::GeneratedClientProject {
+    compile_client(input_with_manifest(
+        custom_scalar_manifest(),
+        CUSTOM_SCALAR_QUERY,
+    ))
+    .expect("compile recursive custom-scalar inputs")
+}
+
+fn row_policy_claim_manifest() -> JsonValue {
+    let mut value = manifest();
+    let policy = json!({
+        "kind": "predicate",
+        "expression": {
+            "kind": "cmp",
+            "value": {
+                "column": "tenantId",
+                "op": "eq",
+                "rhs": {
+                    "kind": "claim",
+                    "value": {"header": "x-tenant-id"}
+                }
+            }
+        }
+    });
+    value["models"][0]["row_policy"] = policy.clone();
+    for root in value["roots"].as_array_mut().expect("manifest roots") {
+        if !root["filter"].is_null() {
+            root["filter"]["row_policy"] = policy.clone();
+        }
+    }
+    refresh_schema_fingerprint(&mut value);
+    value
+}
+
+fn file<'a>(project: &'a super::GeneratedClientProject, path: &str) -> &'a str {
+    project
+        .files
+        .iter()
+        .find(|file| file.path == path)
+        .unwrap_or_else(|| panic!("missing generated file {path}"))
+        .contents
+        .as_str()
+}
+
+fn operation_artifact(project: &super::GeneratedClientProject) -> JsonValue {
+    let operation = &project.operations[0];
+    let generated = file(project, &operation.module_path);
+    let start = generated
+        .rfind(" = {")
+        .expect("generated operation artifact")
+        + 3;
+    let json = generated[start..]
+        .strip_suffix(";\n")
+        .expect("generated operation artifact terminator");
+    serde_json::from_str(json).expect("generated operation artifact JSON")
+}
+
+fn object_member<'a>(selection: &'a JsonValue, field: &str) -> &'a JsonValue {
+    selection["members"]
+        .as_array()
+        .expect("selection members")
+        .iter()
+        .find(|member| member["field"] == field)
+        .unwrap_or_else(|| panic!("missing selection member {field}"))
+}
+
+fn selected_relationship_artifact(relationship: JsonValue) -> JsonValue {
+    let mut value = manifest();
+    value["models"][0]["relationships"][0] = relationship;
+    refresh_schema_fingerprint(&mut value);
+    let project = compile_client(input_with_manifest(
+        value,
+        "query RelationshipPlan { todos { owner { id } } }",
+    ))
+    .expect("compile relationship plan");
+    operation_artifact(&project)
+}
+
+#[test]
+fn compiles_aliases_composite_wire_identity_live_and_load() {
+    let project = compile_client(input(
+        r#"
+          query Todos($limit: Int!) @load @live {
+            rows: todos(limit: $limit) {
+              _distributed_tenantId: title
+              headline: title
+            }
+          }
+        "#,
+    ))
+    .expect("compile");
+    let operation = &project.operations[0];
+    let generated = file(&project, &operation.module_path);
+
+    assert!(generated.contains("query Todos($limit: Int!)"));
+    assert!(generated.contains("_distributed_tenantId_2: tenantId"));
+    assert!(generated.contains("_distributed_id: id"));
+    assert!(generated.contains("_distributed_typename: __typename"));
+    assert!(generated.contains("subscription Todos_Live($limit: Int!)"));
+    assert!(generated.contains("\"expose\": false"));
+    assert!(generated.contains("readonly \"headline\": string | null"));
+    assert!(!generated.contains("readonly \"_distributed_id\""));
+    assert_eq!(
+        operation.operation_hash,
+        fingerprint(
+            "query Todos($limit: Int!) {\n  rows: todos(limit: $limit) {\n    _distributed_tenantId: title\n    headline: title\n    _distributed_tenantId_2: tenantId\n    _distributed_id: id\n    _distributed_typename: __typename\n  }\n}\n"
+        )
+    );
+    assert!(operation.live_operation_hash.is_some());
+    assert_eq!(project.routes[0].route, "/todos");
+    assert_eq!(
+        project.routes[0].discovery,
+        ClientRouteDiscovery::Convention
+    );
+}
+
+#[test]
+fn operation_artifact_carries_normalized_source_provenance() {
+    let project = compile_client(input("query SourceLocated { todos { id } }"))
+        .expect("compile source-located operation");
+    let artifact = operation_artifact(&project);
+
+    assert_eq!(
+        artifact["source"],
+        json!({
+            "path": "src/routes/todos/+page.graphql",
+            "line": 1,
+            "column": 1
+        })
+    );
+}
+
+#[test]
+fn enforces_the_selected_services_exact_depth_and_complexity_limits() {
+    let shallow_source = "query ExactDepth { todos { id } }";
+    let mut exact_depth_manifest = manifest();
+    exact_depth_manifest["execution"]["max_depth"] = json!(2);
+    refresh_schema_fingerprint(&mut exact_depth_manifest);
+    compile_client(input_with_manifest(exact_depth_manifest, shallow_source))
+        .expect("root and leaf fields exactly at max_depth must compile");
+
+    let mut shallow_rejected_manifest = manifest();
+    shallow_rejected_manifest["execution"]["max_depth"] = json!(1);
+    refresh_schema_fingerprint(&mut shallow_rejected_manifest);
+    let error = compile_client(input_with_manifest(
+        shallow_rejected_manifest,
+        shallow_source,
+    ))
+    .expect_err("root plus leaf must count as operation depth two");
+    assert_eq!(error.code, "client.operation.depth_limit");
+    assert!(error.message.contains("operation depth 2"), "{error:?}");
+
+    let mut depth_manifest = manifest();
+    depth_manifest["execution"]["max_depth"] = json!(3);
+    refresh_schema_fingerprint(&mut depth_manifest);
+    let error = compile_client(input_with_manifest(
+        depth_manifest,
+        "query TooDeep { todos { owner { owner { id } } } }",
+    ))
+    .expect_err("depth must fail at build time");
+    assert_eq!(error.code, "client.operation.depth_limit");
+    assert!(error.message.contains("operation depth 4"), "{error:?}");
+
+    let mut exact_deep_manifest = manifest();
+    exact_deep_manifest["execution"]["max_depth"] = json!(4);
+    refresh_schema_fingerprint(&mut exact_deep_manifest);
+    compile_client(input_with_manifest(
+        exact_deep_manifest,
+        "query ExactDeep { todos { owner { owner { id } } } }",
+    ))
+    .expect("the exact recursive service depth boundary must compile");
+
+    let source = "query ExactCost { todos { id } }";
+    let mut accepted_manifest = manifest();
+    accepted_manifest["execution"]["max_complexity"] = json!(18);
+    refresh_schema_fingerprint(&mut accepted_manifest);
+    compile_client(input_with_manifest(accepted_manifest, source))
+        .expect("the exact service complexity boundary must compile");
+
+    let mut rejected_manifest = manifest();
+    rejected_manifest["execution"]["max_complexity"] = json!(17);
+    refresh_schema_fingerprint(&mut rejected_manifest);
+    let error = compile_client(input_with_manifest(rejected_manifest, source))
+        .expect_err("complexity must fail at build time");
+    assert_eq!(error.code, "client.operation.complexity_limit");
+    assert!(
+        error.message.contains("operation complexity 18"),
+        "{error:?}"
+    );
+}
+
+#[test]
+fn compiles_recursive_normalized_relationships_and_nested_fragments() {
+    let project = compile_client(input(
+        r#"
+          query NestedOwner {
+            todos {
+              title
+              owner { ...OwnerFields }
+            }
+          }
+
+          fragment OwnerFields on todo { id }
+        "#,
+    ))
+    .expect("compile normalized relationship");
+    let operation = &project.operations[0];
+    let generated = file(&project, &operation.module_path);
+    let canonical = "query NestedOwner {\n  todos {\n    title\n    owner {\n      id\n      _distributed_tenantId: tenantId\n      _distributed_typename: __typename\n    }\n    _distributed_tenantId: tenantId\n    _distributed_id: id\n    _distributed_typename: __typename\n  }\n}\n";
+
+    assert!(
+        generated.contains(&serde_json::to_string(canonical).unwrap()),
+        "generated:\n{generated}"
+    );
+    assert_eq!(operation.operation_hash, fingerprint(canonical));
+    assert!(generated.contains("readonly \"owner\": {"));
+    assert!(generated.contains("} | null;"));
+    assert!(generated.contains("\"semantic\": \"relationship\""));
+    assert!(generated.contains("\"maintenance\": \"revalidate\""));
+    assert!(generated.contains("\"codec\": \"string\""));
+    assert!(!generated.contains("fragment OwnerFields"));
+}
+
+#[test]
+fn emits_exact_relationship_plans_and_injects_direct_through_and_opaque_keys() {
+    let mut belongs_to = model("Todo", "todo")["relationships"][0].clone();
+    belongs_to["key_mapping"] = json!({
+        "kind": "direct",
+        "local": ["title"],
+        "remote": ["title"]
+    });
+    belongs_to["maintenance"] = json!("local");
+
+    let mut has_many = normalized_list_relationship();
+    has_many["key_mapping"] = json!({
+        "kind": "direct",
+        "local": ["title"],
+        "remote": ["title"]
+    });
+
+    let mut many_to_many = normalized_list_relationship();
+    many_to_many["kind"] = json!("many_to_many");
+    many_to_many["key_mapping"] = json!({
+        "kind": "through",
+        "local": ["title"],
+        "remote": ["title"],
+        "table": "todo_members",
+        "source_foreign_key": "todo_id",
+        "target_foreign_key": "member_id"
+    });
+    many_to_many["dependencies"] = json!(["todo_members", "todo_rows"]);
+
+    let mut opaque = normalized_list_relationship();
+    opaque["kind"] = json!("many_to_many");
+    opaque["key_mapping"] = json!({
+        "kind": "through_opaque",
+        "local": ["title"],
+        "remote": ["title"],
+        "dependency": "todo_members"
+    });
+    opaque["maintenance"] = json!("revalidate");
+    opaque["dependencies"] = json!(["todo_members", "todo_rows"]);
+
+    let cases = [
+        (
+            "belongs_to direct",
+            belongs_to,
+            json!({
+                "field": "owner",
+                "targetModel": "Todo",
+                "kind": "belongs_to",
+                "keyMapping": {
+                    "kind": "direct",
+                    "local": ["title"],
+                    "remote": ["title"]
+                },
+                "maintenance": "local",
+                "dependencies": ["todo_rows"]
+            }),
+            "one",
+        ),
+        (
+            "has_many direct",
+            has_many,
+            json!({
+                "field": "owner",
+                "targetModel": "Todo",
+                "kind": "has_many",
+                "keyMapping": {
+                    "kind": "direct",
+                    "local": ["title"],
+                    "remote": ["title"]
+                },
+                "maintenance": "local",
+                "dependencies": ["todo_rows"]
+            }),
+            "many",
+        ),
+        (
+            "many_to_many through",
+            many_to_many,
+            json!({
+                "field": "owner",
+                "targetModel": "Todo",
+                "kind": "many_to_many",
+                "keyMapping": {
+                    "kind": "through",
+                    "local": ["title"],
+                    "remote": ["title"],
+                    "table": "todo_members",
+                    "sourceForeignKey": "todo_id",
+                    "targetForeignKey": "member_id"
+                },
+                "maintenance": "local",
+                "dependencies": ["todo_members", "todo_rows"]
+            }),
+            "many",
+        ),
+        (
+            "many_to_many opaque",
+            opaque,
+            json!({
+                "field": "owner",
+                "targetModel": "Todo",
+                "kind": "many_to_many",
+                "keyMapping": {
+                    "kind": "through_opaque",
+                    "local": ["title"],
+                    "remote": ["title"],
+                    "dependency": "todo_members"
+                },
+                "maintenance": "revalidate",
+                "dependencies": ["todo_members", "todo_rows"]
+            }),
+            "many",
+        ),
+    ];
+
+    for (label, relationship, expected, cardinality) in cases {
+        let artifact = selected_relationship_artifact(relationship);
+        let root = &artifact["roots"][0];
+        let branch = object_member(&root["selection"], "owner");
+        assert_eq!(branch["relationship"], expected, "{label}");
+        assert_eq!(branch["cardinality"], cardinality, "{label}");
+        assert_eq!(
+            root["filter"]["relationships"][0], expected,
+            "{label} filter catalog"
+        );
+
+        let source_key = object_member(&root["selection"], "title");
+        assert_eq!(source_key["expose"], false, "{label} source key");
+        let target_key = object_member(&branch["selection"], "title");
+        assert_eq!(target_key["expose"], false, "{label} target key");
+    }
+}
+
+#[test]
+fn embedded_relationship_plans_remain_revalidate_without_invented_keys() {
+    let artifact =
+        selected_relationship_artifact(model("Todo", "todo")["relationships"][0].clone());
+    let root = &artifact["roots"][0];
+    let branch = object_member(&root["selection"], "owner");
+    let expected = json!({
+        "field": "owner",
+        "targetModel": "Todo",
+        "kind": "belongs_to",
+        "keyMapping": {"kind": "embedded"},
+        "maintenance": "revalidate",
+        "dependencies": ["todo_rows"]
+    });
+    assert_eq!(branch["relationship"], expected);
+    assert_eq!(root["filter"]["relationships"][0], expected);
+    assert!(
+        root["selection"]["members"]
+            .as_array()
+            .expect("root members")
+            .iter()
+            .all(|member| member["field"] != "title"),
+        "embedded mappings must not invent unavailable relationship keys"
+    );
+}
+
+#[test]
+fn relationship_filter_catalog_injects_its_referenced_source_keys() {
+    let mut value = manifest();
+    let mut relationship = normalized_list_relationship();
+    relationship["key_mapping"] = json!({
+        "kind": "direct",
+        "local": ["title"],
+        "remote": ["title"]
+    });
+    value["models"][0]["relationships"][0] = relationship;
+    refresh_schema_fingerprint(&mut value);
+    let project = compile_client(input_with_manifest(
+        value,
+        r#"query RelationshipFilter {
+            todos(where: {owner: {title: {_eq: "owned"}}}) { id }
+        }"#,
+    ))
+    .expect("compile relationship predicate");
+    let artifact = operation_artifact(&project);
+    let root = &artifact["roots"][0];
+    assert_eq!(
+        root["filter"]["relationships"][0]["keyMapping"],
+        json!({
+            "kind": "direct",
+            "local": ["title"],
+            "remote": ["title"]
+        })
+    );
+    let source_key = object_member(&root["selection"], "title");
+    assert_eq!(source_key["expose"], false);
+}
+
+#[test]
+fn compiles_nested_list_arguments_coverage_and_variable_usage() {
+    let mut value = manifest();
+    value["models"][0]["relationships"][0] = normalized_list_relationship();
+    refresh_schema_fingerprint(&mut value);
+    let project = compile_client(ClientCompileInput::new(
+        value,
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/routes/todos/+page.graphql",
+            "query NestedList($take: Int!) { todos { copies: owner(limit: $take, offset: 0) { headline: title } } }",
+        )],
+    ))
+    .expect("compile normalized list relationship");
+    let operation = &project.operations[0];
+    let generated = file(&project, &operation.module_path);
+    let canonical = "query NestedList($take: Int!) {\n  todos {\n    copies: owner(limit: $take, offset: 0) {\n      headline: title\n      _distributed_tenantId: tenantId\n      _distributed_id: id\n      _distributed_typename: __typename\n    }\n    _distributed_tenantId: tenantId\n    _distributed_id: id\n    _distributed_typename: __typename\n  }\n}\n";
+
+    assert_eq!(operation.operation_hash, fingerprint(canonical));
+    assert!(generated.contains(&serde_json::to_string(canonical).unwrap()));
+    assert!(generated.contains("\"cardinality\": \"many\""));
+    assert!(generated.contains("\"maintenance\": \"local\""));
+    assert!(generated.contains("\"offsetArgument\": \"offset\""));
+    assert!(generated.contains("\"limitArgument\": \"limit\""));
+    assert!(generated.contains("readonly \"copies\": readonly {"));
+}
+
+#[test]
+fn compiles_embedded_objects_without_inventing_wire_identity() {
+    let mut value = manifest();
+    value["models"].as_array_mut().expect("models").push(json!({
+        "id": "TodoDetails",
+        "typename": "todo_details",
+        "source_table": "todo_details_rows",
+        "dependencies": ["todo_details_rows"],
+        "normalization": {"kind": "embedded"},
+        "fields": [{
+            "name": "note",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": true
+        }],
+        "relationships": [],
+        "filter_input": {
+            "type_name": "todo_details_bool_exp",
+            "fields": [
+                {"name": "note", "operators": ["_eq"]}
+            ],
+            "relationships": []
+        },
+        "row_policy": {"kind": "unrestricted"},
+        "record_revisions": false,
+        "tombstones": false
+    }));
+    value["models"][0]["relationships"]
+        .as_array_mut()
+        .expect("relationships")
+        .push(json!({
+            "name": "details",
+            "target_model": "TodoDetails",
+            "target_typename": "todo_details",
+            "kind": "belongs_to",
+            "list": false,
+            "nullable": true,
+            "arguments": [],
+            "key_mapping": {"kind": "embedded"},
+            "maintenance": "revalidate",
+            "dependencies": ["todo_details_rows", "todo_rows"],
+            "live": false
+        }));
+    value["models"][0]["filter_input"]["relationships"]
+        .as_array_mut()
+        .expect("filter input relationships")
+        .push(json!({
+            "field": "details",
+            "target_type": "todo_details_bool_exp"
+        }));
+    value["roots"][0]["filter"]["relationships"] = json!(["details", "owner"]);
+    value["roots"][1]["filter"]["relationships"] = json!(["details", "owner"]);
+    value["roots"][3]["filter"]["relationships"] = json!(["details", "owner"]);
+    refresh_schema_fingerprint(&mut value);
+
+    let project = compile_client(ClientCompileInput::new(
+        value,
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/routes/todos/+page.graphql",
+            "query Embedded { todos { details { note } } }",
+        )],
+    ))
+    .expect("compile embedded relationship");
+    let operation = &project.operations[0];
+    let generated = file(&project, &operation.module_path);
+    let canonical = "query Embedded {\n  todos {\n    details {\n      note\n    }\n    _distributed_tenantId: tenantId\n    _distributed_id: id\n    _distributed_typename: __typename\n  }\n}\n";
+    assert_eq!(operation.operation_hash, fingerprint(canonical));
+    assert!(generated.contains(&serde_json::to_string(canonical).unwrap()));
+    assert!(generated.contains("\"typename\": \"todo_details\""));
+    assert!(generated.contains("\"kind\": \"embedded\""));
+    assert!(generated.contains("readonly \"note\": string | null;"));
+}
+
+#[test]
+fn compiles_aggregate_count_and_nodes_with_exact_typenames_and_window() {
+    let project = compile_client(input(
+        r#"
+          query AggregateTodos($where: todo_bool_exp) {
+            stats: todos_aggregate(where: $where) { ...AggregateParts }
+          }
+
+          fragment AggregateParts on todo_aggregate {
+            summary: aggregate { ...CountFields }
+            items: nodes { ...TodoFields }
+          }
+          fragment CountFields on todo_aggregate_fields { total: count }
+          fragment TodoFields on todo { headline: title }
+        "#,
+    ))
+    .expect("compile aggregate");
+    let operation = &project.operations[0];
+    let generated = file(&project, &operation.module_path);
+    let canonical = "query AggregateTodos($where: todo_bool_exp) {\n  stats: todos_aggregate(where: $where) {\n    summary: aggregate {\n      total: count\n    }\n    items: nodes {\n      headline: title\n      _distributed_tenantId: tenantId\n      _distributed_id: id\n      _distributed_typename: __typename\n      _distributed_completed: completed\n      _distributed_priority: priority\n    }\n  }\n}\n";
+
+    assert!(
+        generated.contains(&serde_json::to_string(canonical).unwrap()),
+        "generated:\n{generated}"
+    );
+    assert_eq!(operation.operation_hash, fingerprint(canonical));
+    assert!(generated.contains("\"typename\": \"todo_aggregate\""));
+    assert!(generated.contains("\"typename\": \"todo_aggregate_fields\""));
+    assert!(generated.contains("\"semantic\": \"aggregate_fields\""));
+    assert!(generated.contains("\"semantic\": \"aggregate_nodes\""));
+    assert!(generated.contains("\"defaultLimit\": 25"));
+    assert!(generated.contains("\"maxLimit\": 100"));
+    assert!(generated.contains("readonly \"stats\": {"));
+    assert!(generated.contains("readonly \"summary\": {"));
+    assert!(generated.contains("readonly \"total\": number;"));
+    assert!(generated.contains("readonly \"items\": readonly {"));
+    assert!(!generated.contains("fragment AggregateParts"));
+}
+
+#[test]
+fn compiles_count_only_without_inventing_nodes_or_record_identity() {
+    let project = compile_client(input(
+        "query CountOnly { summary: todos_aggregate { stats: aggregate { total: count } } }",
+    ))
+    .expect("compile count-only aggregate");
+    let operation = &project.operations[0];
+    let generated = file(&project, &operation.module_path);
+    let canonical = "query CountOnly {\n  summary: todos_aggregate {\n    stats: aggregate {\n      total: count\n    }\n  }\n}\n";
+
+    assert_eq!(operation.operation_hash, fingerprint(canonical));
+    assert!(generated.contains(&serde_json::to_string(canonical).unwrap()));
+    assert!(!generated.contains("\"semantic\": \"aggregate_nodes\""));
+    assert!(!generated.contains("\"model\": \"Todo\""));
+    assert!(generated.contains("readonly \"summary\": {"));
+    assert!(generated.contains("readonly \"stats\": {"));
+    assert!(generated.contains("readonly \"total\": number;"));
+}
+
+#[test]
+fn compiles_nullable_relationship_aggregate_from_declared_typenames() {
+    let mut value = manifest();
+    let mut relationship = normalized_list_relationship();
+    relationship["aggregate"] = json!({
+        "name": "owner_aggregate",
+        "arguments": [],
+        "semantics": {
+            "wrapper_typename": "todo_aggregate",
+            "fields_typename": "todo_aggregate_fields",
+            "nodes_pagination": {
+                "kind": "offset",
+                "default_limit": 25,
+                "max_limit": 100,
+                "coverage": "window"
+            },
+            "count": true,
+            "nodes": true,
+            "sum": [],
+            "avg": [],
+            "min": [],
+            "max": []
+        },
+        "dependencies": ["todo_rows"]
+    });
+    value["models"][0]["relationships"][0] = relationship;
+    refresh_schema_fingerprint(&mut value);
+    let project = compile_client(ClientCompileInput::new(
+        value,
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/routes/todos/+page.graphql",
+            "query RelationshipStats { todos { metrics: owner_aggregate { stats: aggregate { total: count } items: nodes { headline: title } } } }",
+        )],
+    ))
+    .expect("compile relationship aggregate");
+    let operation = &project.operations[0];
+    let generated = file(&project, &operation.module_path);
+    let canonical = "query RelationshipStats {\n  todos {\n    metrics: owner_aggregate {\n      stats: aggregate {\n        total: count\n      }\n      items: nodes {\n        headline: title\n        _distributed_tenantId: tenantId\n        _distributed_id: id\n        _distributed_typename: __typename\n      }\n    }\n    _distributed_tenantId: tenantId\n    _distributed_id: id\n    _distributed_typename: __typename\n  }\n}\n";
+
+    assert_eq!(operation.operation_hash, fingerprint(canonical));
+    assert!(generated.contains(&serde_json::to_string(canonical).unwrap()));
+    assert!(generated.contains("\"semantic\": \"aggregate\""));
+    assert!(generated.contains("\"field\": \"owner_aggregate\""));
+    assert!(generated.contains("\"nullable\": true"));
+    assert!(generated.contains("readonly \"metrics\": {"));
+    assert!(generated.contains("} | null;"));
+}
+
+#[test]
+fn preserves_enum_wire_syntax_and_json_runtime_value() {
+    let project = compile_client(input(
+        r#"
+          query Ordered {
+            todos(order_by: [{priority: asc}]) { id }
+          }
+        "#,
+    ))
+    .expect("compile");
+    let generated = file(&project, &project.operations[0].module_path);
+    assert!(generated.contains("todos(order_by: [{priority: asc}])"));
+    assert!(generated.contains("\"priority\": \"asc\""));
+    assert!(!generated.contains("priority: \\\"asc\\\""));
+}
+
+#[test]
+fn emits_executable_filter_order_and_pagination_plans_with_hidden_dependencies() {
+    let project = compile_client(input(
+        r#"
+          query Planned($where: todo_bool_exp, $order: [todo_order_by!]) {
+            todos(where: $where, order_by: $order, limit: 10) { id }
+          }
+        "#,
+    ))
+    .expect("compile executable index plan");
+    let generated = file(&project, &project.operations[0].module_path);
+
+    assert!(generated.contains("\"filter\": {"));
+    assert!(generated.contains("\"input\": {"));
+    assert!(generated.contains("\"name\": \"where\""));
+    assert!(generated.contains("\"rowPolicy\": {"));
+    assert!(generated.contains("\"kind\": \"unrestricted\""));
+    assert!(generated.contains("\"field\": \"priority\""));
+    assert!(generated.contains("\"codec\": \"int32\""));
+    assert!(generated.contains("\"order\": {"));
+    assert!(generated.contains("\"tieBreakers\": ["));
+    assert!(generated.contains("\"pagination\": {"));
+    assert!(generated.contains("\"insert\": \"local\""));
+    assert!(generated.contains("\"delete\": \"local\""));
+    assert!(generated.contains("\"reorder\": \"local\""));
+    assert!(generated.contains("\"stableUpdate\": \"local\""));
+    assert!(generated.contains("type Operation_Planned_Input_todo_bool_exp = {"));
+    assert!(generated.contains(
+        "readonly \"_and\"?: Operation_Planned_Input_todo_bool_exp | readonly Operation_Planned_Input_todo_bool_exp[] | null;"
+    ));
+    assert!(generated.contains("readonly \"_in\"?: number | readonly number[];"));
+    assert!(generated.contains("type Operation_Planned_Input_todo_order_by_Direction ="));
+    assert!(generated.contains("readonly \"order\"?: Operation_Planned_Input_todo_order_by | readonly Operation_Planned_Input_todo_order_by[] | null;"));
+    assert!(generated.contains("\"variableCodec\": {"));
+    assert!(generated.contains("\"version\": 1"));
+    assert!(generated.contains("\"maxBoolWidth\": 256"));
+    assert!(generated.contains("\"maxInList\": 1000"));
+    let provenance: JsonValue =
+        serde_json::from_str(file(&project, "manifest.json")).expect("compiler manifest JSON");
+    assert_eq!(provenance["distributed_manifest_version"], 1);
+    assert!(generated.contains(
+        "\"target\": {\n              \"kind\": \"input\",\n              \"name\": \"todo_bool_exp\""
+    ));
+    assert!(!generated.contains("Readonly<Record<string, unknown>>"));
+
+    // A whole-object filter/order variable may reference every authorized
+    // field, so the compiler must inject their complete conservative envelope.
+    assert!(generated.contains("_distributed_completed: completed"));
+    assert!(generated.contains("_distributed_priority: priority"));
+    assert!(generated.contains("_distributed_tenantId: tenantId"));
+    assert!(generated.contains("_distributed_title: title"));
+    let public_data = generated
+        .split("export type Operation_Planned_Data =")
+        .nth(1)
+        .expect("generated public data type")
+        .split("/** Exact canonical query bytes")
+        .next()
+        .expect("public data type boundary");
+    assert!(!public_data.contains("readonly \"priority\""));
+    assert!(!public_data.contains("readonly \"title\""));
+}
+
+#[test]
+fn generated_variable_codec_types_recursive_inputs_and_custom_scalars() {
+    let project = custom_scalar_project();
+    let generated = file(&project, &project.operations[0].module_path);
+
+    assert_eq!(
+        generated,
+        include_str!("../../tests/fixtures/generated-operation.ts"),
+        "the checked-in TypeScript consumer fixture must remain byte-exact"
+    );
+    assert!(generated.contains("readonly \"id\": string | number;"));
+    assert!(generated.contains("readonly \"big\": number;"));
+    assert!(generated.contains("readonly \"bytes\"?: string | null;"));
+    assert!(generated.contains("readonly \"json\"?: ReplicaValue | null;"));
+    assert!(generated.contains("readonly \"timestamp\"?: string | null;"));
+    assert!(generated.contains("readonly \"payload\"?: {"));
+    assert!(generated.contains("readonly \"_eq\"?: ReplicaValue | null;"));
+    assert!(generated.contains("readonly \"_in\"?: number | readonly number[];"));
+    assert!(!generated.contains("Readonly<Record<string, unknown>>"));
+
+    let artifact = operation_artifact(&project);
+    assert_eq!(artifact["protocol"]["trustedPresets"], json!([]));
+    assert_eq!(artifact["variableCodec"]["version"], 1);
+    assert_eq!(
+        artifact["variableCodec"]["limits"],
+        json!({
+            "maxDepth": 8,
+            "maxBoolWidth": 256,
+            "maxInList": 1000
+        })
+    );
+    assert_eq!(
+        artifact["variableCodec"]["variables"]["where"]["filterBaseDepth"],
+        1
+    );
+    assert_eq!(
+        artifact["variableCodec"]["variables"]["id"],
+        json!({
+            "kind": "scalar",
+            "scalar": "ID",
+            "codec": "string",
+            "nullable": false
+        })
+    );
+    assert_eq!(
+        artifact["variableCodec"]["variables"]["order"]["kind"],
+        "list"
+    );
+    assert_eq!(
+        artifact["variableCodec"]["variables"]["order"]["item"]["name"],
+        "todo_order_by"
+    );
+    let filter_fields = artifact["variableCodec"]["inputs"]["todo_bool_exp"]["fields"]
+        .as_array()
+        .expect("compiled filter input fields");
+    let sequence = filter_fields
+        .iter()
+        .find(|field| field["field"] == "sequence")
+        .expect("BigInt filter field");
+    assert_eq!(sequence["scalar"], "BigInt");
+    assert_eq!(sequence["codec"], "json_number_precision_limited");
+    assert_eq!(
+        artifact["variableCodec"]["inputs"]["todo_bool_exp"]["relationships"][0]["target"]["kind"],
+        "input"
+    );
+}
+
+#[test]
+fn generated_query_carries_row_policy_claim_contract_without_a_command_runtime() {
+    let project = compile_client(input_with_manifest(
+        row_policy_claim_manifest(),
+        "query Todos { todos { id tenantId } }",
+    ))
+    .expect("compile client-visible row-policy claim");
+    let artifact = operation_artifact(&project);
+    assert_eq!(
+        artifact["protocol"]["trustedPresets"],
+        json!([{"name": "x-tenant-id", "codec": "string"}])
+    );
+    assert_eq!(
+        artifact["roots"][0]["filter"]["rowPolicy"]["expression"]["value"]["rhs"]["value"]
+            ["header"],
+        "x-tenant-id"
+    );
+}
+
+#[test]
+fn model_filter_contract_resolves_belongs_to_and_has_many_cycles() {
+    let mut recursive = manifest();
+    let mut children = normalized_list_relationship();
+    children["name"] = json!("children");
+    children["filter"]["relationships"] = json!(["children", "owner"]);
+    recursive["models"][0]["relationships"]
+        .as_array_mut()
+        .expect("relationships")
+        .push(children);
+    recursive["models"][0]["filter_input"]["relationships"]
+        .as_array_mut()
+        .expect("filter input relationships")
+        .push(json!({
+            "field": "children",
+            "target_type": "todo_bool_exp"
+        }));
+    for root in recursive["roots"].as_array_mut().expect("roots") {
+        if let Some(relationships) = root
+            .get_mut("filter")
+            .and_then(JsonValue::as_object_mut)
+            .and_then(|filter| filter.get_mut("relationships"))
+        {
+            *relationships = json!(["children", "owner"]);
+        }
+    }
+    refresh_schema_fingerprint(&mut recursive);
+    let project = compile_client(input_with_manifest(
+        recursive,
+        "query RecursiveWhere($where: todo_bool_exp) { todos(where: $where) { id } }",
+    ))
+    .expect("compile explicit self-recursive filter contract");
+    let generated = file(&project, &project.operations[0].module_path);
+
+    assert_eq!(
+        generated
+            .matches("type Operation_RecursiveWhere_Input_todo_bool_exp = {")
+            .count(),
+        1,
+        "recursive aliases must be declared once"
+    );
+    assert!(generated
+        .contains("readonly \"children\"?: Operation_RecursiveWhere_Input_todo_bool_exp | null;"));
+    assert!(generated
+        .contains("readonly \"owner\"?: Operation_RecursiveWhere_Input_todo_bool_exp | null;"));
+    let artifact = operation_artifact(&project);
+    let relationships = artifact["variableCodec"]["inputs"]["todo_bool_exp"]["relationships"]
+        .as_array()
+        .expect("compiled filter input relationships");
+    assert_eq!(relationships.len(), 2);
+    for relationship in relationships {
+        assert_eq!(
+            relationship["target"],
+            json!({"kind": "input", "name": "todo_bool_exp"})
+        );
+    }
+}
+
+#[test]
+fn literal_index_plans_inject_only_referenced_fields_and_validate_shape() {
+    let project = compile_client(input(
+        "query LiteralPlan { todos(where: {priority: {_eq: 3}}, order_by: [{priority: desc}]) { id } }",
+    ))
+    .expect("compile literal index plan");
+    let generated = file(&project, &project.operations[0].module_path);
+    assert!(generated.contains("_distributed_priority: priority"));
+    assert!(!generated.contains("_distributed_completed: completed"));
+    assert!(!generated.contains("_distributed_title: title"));
+    assert!(generated.contains("\"kind\": \"literal\""));
+    assert!(generated.contains("\"priority\": {"));
+    assert!(generated.contains("\"_eq\": 3"));
+
+    let error = compile_client(input(
+        "query BadFilterField { todos(where: {missing: {_eq: 3}}) { id } }",
+    ))
+    .expect_err("unknown filter field must fail at build time");
+    assert_eq!(error.code, "client.filter.field_denied_or_unknown");
+
+    let error = compile_client(input(
+        "query BadFilterOperator { todos(where: {priority: {_gt: 3}}) { id } }",
+    ))
+    .expect_err("unselected filter operator must fail at build time");
+    assert_eq!(error.code, "client.filter.operator_denied_or_unknown");
+
+    let error = compile_client(input(
+        "query BadFilterLiteral { todos(where: {priority: {_eq: \"bad\"}}) { id } }",
+    ))
+    .expect_err("filter literals must match the selected scalar codec");
+    assert_eq!(error.code, "client.filter.literal_type");
+
+    let error = compile_client(input(
+        "query BadFilterList { todos(where: {priority: {_in: [1, \"bad\"]}}) { id } }",
+    ))
+    .expect_err("every filter list item must match the selected scalar codec");
+    assert_eq!(error.code, "client.filter.literal_type");
+
+    let error = compile_client(input(
+        "query AmbiguousOrder { todos(order_by: [{priority: asc, id: desc}]) { id } }",
+    ))
+    .expect_err("ambiguous order priority must fail at build time");
+    assert_eq!(error.code, "client.order.ambiguous");
+}
+
+#[test]
+fn scalar_literals_use_the_same_canonical_domains_as_variables() {
+    let project = compile_client(input_with_manifest(
+        literal_scalar_manifest(),
+        r#"
+          query LiteralScalarCodecs {
+            todos(
+              where: {
+                id: {_eq: -0}
+                priority: {_eq: -0}
+                blob: {_eq: "AQI="}
+                payload: {_eq: {z: -0, a: 1, safe: 9007199254740991, decimal: 0.100000000000000005}}
+                ratio: {_eq: -0}
+                sequence: {_eq: -0}
+              }
+            ) { id }
+          }
+        "#,
+    ))
+    .expect("compile canonical scalar literals");
+    let operation = operation_artifact(&project);
+    let value = &operation["roots"][0]["filter"]["input"]["value"];
+    assert_eq!(value["id"]["_eq"], "0");
+    assert_eq!(value["priority"]["_eq"], 0);
+    assert_eq!(value["blob"]["_eq"], "AQI=");
+    assert_eq!(
+        value["payload"]["_eq"],
+        json!({"a": 1, "decimal": 0.1, "safe": 9_007_199_254_740_991_u64, "z": 0})
+    );
+    assert_eq!(value["ratio"]["_eq"], 0);
+    assert_eq!(value["sequence"]["_eq"], 0);
+    let document = operation["document"].as_str().expect("operation document");
+    assert!(document.contains("id: {_eq: \"0\"}"));
+    assert!(document.contains("decimal: 0.1"));
+    assert!(!document.contains("0.100000000000000005"));
+
+    let rounded_float = compile_client(input_with_manifest(
+        literal_scalar_manifest(),
+        "query RoundedFloat { todos(where: {ratio: {_eq: 9007199254740993}}) { id } }",
+    ))
+    .expect("Float literals canonicalize through the JavaScript/server f64 domain");
+    let rounded_float = operation_artifact(&rounded_float);
+    assert_eq!(
+        rounded_float["roots"][0]["filter"]["input"]["value"]["ratio"]["_eq"].as_f64(),
+        Some(9_007_199_254_740_992.0)
+    );
+    let rounded_document = rounded_float["document"]
+        .as_str()
+        .expect("rounded document");
+    assert!(!rounded_document.contains("9007199254740993"));
+
+    let mixed_json = compile_client(input_with_manifest(
+        custom_scalar_manifest(),
+        "query MixedJson($id: ID!) { todos(where: {id: {_eq: $id}, payload: {_eq: {a: 1}}}) { id } }",
+    ))
+    .expect("a JSON scalar literal remains a scalar beside an unrelated variable");
+    let mixed_json = operation_artifact(&mixed_json);
+    assert_eq!(
+        mixed_json["roots"][0]["filter"]["input"]["fields"]["payload"]["value"]["_eq"]["a"],
+        1
+    );
+
+    let by_pk = compile_client(input(
+        "query LiteralIds { todo(id: -0, tenantId: 1) { id } }",
+    ))
+    .expect("GraphQL integer ID literals coerce to canonical strings");
+    let by_pk = operation_artifact(&by_pk);
+    assert_eq!(by_pk["roots"][0]["arguments"]["id"]["value"], "0");
+    assert_eq!(by_pk["roots"][0]["arguments"]["tenantId"]["value"], "1");
+
+    for (source, label) in [
+        (
+            "query UnsafeId { todos(where: {id: {_eq: 9007199254740992}}) { id } }",
+            "unsafe integer ID",
+        ),
+        (
+            "query WideInt { todos(where: {priority: {_eq: 2147483648}}) { id } }",
+            "out-of-range Int",
+        ),
+        (
+            "query FractionalBigInt { todos(where: {sequence: {_eq: 1.5}}) { id } }",
+            "fractional BigInt",
+        ),
+        (
+            "query UnsafeBigInt { todos(where: {sequence: {_eq: 9007199254740992}}) { id } }",
+            "unsafe BigInt",
+        ),
+        (
+            "query NonCanonicalBytea { todos(where: {blob: {_eq: \"AB==\"}}) { id } }",
+            "non-canonical Bytea",
+        ),
+        (
+            "query UnsafeJsonInteger { todos(where: {payload: {_eq: {n: 9007199254740993}}}) { id } }",
+            "JSON integer that cannot round-trip through JavaScript",
+        ),
+        (
+            "query UnsafeJsonStringifyInteger { todos(where: {payload: {_eq: {n: 36028797018963968}}}) { id } }",
+            "JSON integer whose JavaScript decimal serialization changes",
+        ),
+    ] {
+        let error = match compile_client(input_with_manifest(literal_scalar_manifest(), source)) {
+            Ok(_) => panic!("{label} must fail"),
+            Err(error) => error,
+        };
+        assert_eq!(error.code, "client.filter.literal_type", "{label}");
+    }
+
+    let error = compile_client(input("query WideLimit { todos(limit: 2147483648) { id } }"))
+        .expect_err("root Int literals use the same signed 32-bit domain as variables");
+    assert_eq!(error.code, "client.argument.literal_type");
+}
+
+#[test]
+fn canonicalizes_graphql_singletons_at_every_filter_and_order_list_position() {
+    let project = compile_client(input(
+        r#"
+          query SingletonLists {
+            todos(
+              where: {
+                _and: {priority: {_in: 3}}
+                _or: {completed: {_eq: true}}
+              }
+              order_by: {priority: desc}
+            ) { id }
+          }
+        "#,
+    ))
+    .expect("GraphQL singleton input coercion must compile");
+    let generated = file(&project, &project.operations[0].module_path);
+    assert!(generated.contains(
+        "todos(order_by: [{priority: desc}], where: {_and: [{priority: {_in: [3]}}], _or: [{completed: {_eq: true}}]})"
+    ));
+
+    let artifact = operation_artifact(&project);
+    let root = &artifact["roots"][0];
+    let expected_filter = json!({
+        "kind": "literal",
+        "value": {
+            "_and": [{"priority": {"_in": [3]}}],
+            "_or": [{"completed": {"_eq": true}}]
+        }
+    });
+    let expected_order = json!({
+        "kind": "literal",
+        "value": [{"priority": "desc"}]
+    });
+    assert_eq!(root["arguments"]["where"], expected_filter);
+    assert_eq!(root["filter"]["input"], expected_filter);
+    assert_eq!(root["arguments"]["order_by"], expected_order);
+    assert_eq!(root["order"]["input"], expected_order);
+}
+
+#[test]
+fn enforces_filter_depth_and_width_limits_after_graphql_singleton_coercion() {
+    let mut depth_manifest = manifest();
+    depth_manifest["execution"]["max_depth"] = json!(2);
+    refresh_schema_fingerprint(&mut depth_manifest);
+    compile_client(input_with_manifest(
+        depth_manifest.clone(),
+        r#"
+          query ExactFilterDepth {
+            todos(where: {
+              _not: {
+                _not: {
+                  _and: null
+                  _or: []
+                  priority: {_in: [1, 2]}
+                }
+              }
+            }) { id }
+          }
+        "#,
+    ))
+    .expect("semantic filter depth exactly at max_depth must compile");
+
+    for source in [
+        "query TooDeepNot { todos(where: {_not: {_not: {_not: null}}}) { id } }",
+        "query TooDeepRelationship { todos(where: {owner: {owner: {owner: null}}}) { id } }",
+    ] {
+        let error = compile_client(input_with_manifest(depth_manifest.clone(), source))
+            .expect_err("null still enters _not and relationship filter children");
+        assert_eq!(error.code, "client.filter.depth_limit", "{source}");
+    }
+
+    let mut width_manifest = manifest();
+    width_manifest["execution"]["max_bool_width"] = json!(1);
+    width_manifest["execution"]["max_in_list"] = json!(1);
+    refresh_schema_fingerprint(&mut width_manifest);
+    compile_client(input_with_manifest(
+        width_manifest.clone(),
+        r#"
+          query ExactFilterWidths {
+            todos(where: {_and: {priority: {_in: 1}}}) { id }
+          }
+        "#,
+    ))
+    .expect("singleton boolean and IN inputs coerce to their exact width boundary");
+
+    for (source, label) in [
+        (
+            "query WideBool { todos(where: {_and: [{priority: {_eq: 1}}, {priority: {_eq: 2}}]}) { id } }",
+            "literal boolean list",
+        ),
+        (
+            "query WideIn { todos(where: {priority: {_in: [1, 2]}}) { id } }",
+            "literal IN list",
+        ),
+        (
+            "query WideMixedBool($where: todo_bool_exp!) { todos(where: {_and: [$where, {priority: {_eq: 1}}]}) { id } }",
+            "mixed boolean list",
+        ),
+        (
+            "query WideMixedIn($priority: Int!) { todos(where: {priority: {_in: [$priority, 1]}}) { id } }",
+            "mixed IN list",
+        ),
+    ] {
+        let error = compile_client(input_with_manifest(width_manifest.clone(), source))
+            .expect_err("filter width above the exact service boundary must fail");
+        assert_eq!(error.code, "client.filter.width_limit", "{label}");
+    }
+}
+
+#[test]
+fn variable_codec_intersects_filter_depth_and_list_constraints() {
+    let mut value = manifest();
+    value["execution"]["max_bool_width"] = json!(7);
+    value["execution"]["max_in_list"] = json!(11);
+    refresh_schema_fingerprint(&mut value);
+    let project = compile_client(input_with_manifest(
+        value,
+        r#"
+          query VariableConstraints(
+            $where: todo_bool_exp!
+            $clauses: [todo_bool_exp!]
+            $ids: [Int!]
+          ) {
+            todos(where: {
+              _and: [
+                $where
+                {_not: $where}
+                {_and: $clauses}
+                {priority: {_in: $ids}}
+              ]
+            }) { id }
+          }
+        "#,
+    ))
+    .expect("compile variables reused at multiple filter positions");
+    let artifact = operation_artifact(&project);
+    let variables = &artifact["variableCodec"]["variables"];
+    assert_eq!(variables["where"]["filterBaseDepth"], 2);
+    assert_eq!(variables["clauses"]["maxItems"], 7);
+    assert_eq!(variables["clauses"]["item"]["filterBaseDepth"], 2);
+    assert_eq!(variables["ids"]["maxItems"], 11);
+}
+
+#[test]
+fn relationship_selection_and_aggregate_filters_inherit_model_edge_depth() {
+    let mut value = manifest();
+    let mut relationship = normalized_list_relationship();
+    relationship["aggregate"] = json!({
+        "name": "owner_aggregate",
+        "arguments": list_arguments(),
+        "semantics": {
+            "wrapper_typename": "todo_aggregate",
+            "fields_typename": "todo_aggregate_fields",
+            "nodes_pagination": {
+                "kind": "offset",
+                "default_limit": 25,
+                "max_limit": 100,
+                "coverage": "window"
+            },
+            "count": true,
+            "nodes": true,
+            "sum": [],
+            "avg": [],
+            "min": [],
+            "max": []
+        },
+        "dependencies": ["todo_rows"]
+    });
+    value["models"][0]["relationships"][0] = relationship;
+    refresh_schema_fingerprint(&mut value);
+    let project = compile_client(input_with_manifest(
+        value,
+        r#"
+          query EdgeFilterDepth(
+            $selectedWhere: todo_bool_exp
+            $aggregateWhere: todo_bool_exp
+          ) {
+            todos {
+              owner(where: $selectedWhere) { id }
+              owner_aggregate(where: $aggregateWhere) {
+                aggregate { count }
+              }
+            }
+          }
+        "#,
+    ))
+    .expect("compile relationship selection and aggregate filter variables");
+    let artifact = operation_artifact(&project);
+    for variable in ["selectedWhere", "aggregateWhere"] {
+        assert_eq!(
+            artifact["variableCodec"]["variables"][variable]["filterBaseDepth"], 1,
+            "{variable}"
+        );
+    }
+}
+
+#[test]
+fn variable_nullability_is_compatible_but_never_weaker() {
+    compile_client(input(
+        "query Strict($limit: Int!) { todos(limit: $limit) { id } }",
+    ))
+    .expect("non-null variable may satisfy nullable argument");
+
+    let error = compile_client(input(
+        "query Weak($tenantId: ID, $id: ID!) { todo(tenantId: $tenantId, id: $id) { title } }",
+    ))
+    .expect_err("nullable variable may not satisfy non-null argument");
+    assert_eq!(error.code, "client.variable.type_mismatch");
+
+    let error = compile_client(input(
+        "query WeakItem($order: [todo_order_by]) { todos(order_by: $order) { id } }",
+    ))
+    .expect_err("nullable list item may not satisfy non-null item");
+    assert_eq!(error.code, "client.variable.type_mismatch");
+}
+
+#[test]
+fn compiles_nested_filter_and_order_variables_with_recursive_value_sources() {
+    let project = compile_client(input(
+        r#"
+          query Nested($priority: Int!, $direction: order_by!) {
+            todos(
+              where: {priority: {_eq: $priority}}
+              order_by: [{priority: $direction}]
+            ) { id }
+          }
+        "#,
+    ))
+    .expect("compile nested variables");
+    let generated = file(&project, &project.operations[0].module_path);
+    assert!(generated.contains("where: {priority: {_eq: $priority}}"));
+    assert!(generated.contains("order_by: [{priority: $direction}]"));
+    assert!(generated.contains("\"kind\": \"object\""));
+    assert!(generated.contains("\"kind\": \"list\""));
+    assert!(generated.contains("\"name\": \"priority\""));
+    assert!(generated.contains("\"name\": \"direction\""));
+    assert!(generated.contains("_distributed_priority: priority"));
+    assert!(!generated.contains("_distributed_completed: completed"));
+    assert!(generated.contains(
+        "readonly \"direction\": \"asc\" | \"asc_nulls_first\" | \"asc_nulls_last\" | \"desc\" | \"desc_nulls_first\" | \"desc_nulls_last\";"
+    ));
+    assert!(generated.contains("\"kind\": \"enum\""));
+    assert!(!generated.contains("Readonly<Record<string, unknown>>"));
+
+    let error = compile_client(input(
+        "query WrongNested($priority: String!) { todos(where: {priority: {_eq: $priority}}) { id } }",
+    ))
+    .expect_err("nested variable type must match its scalar position");
+    assert_eq!(error.code, "client.variable.type_mismatch");
+
+    let error = compile_client(input(
+        "query MissingNested { todos(where: {priority: {_eq: $missing}}) { id } }",
+    ))
+    .expect_err("nested variable must be defined");
+    assert_eq!(error.code, "client.variable.undefined");
+
+    let error = compile_client(input(
+        "query WrongListItem($priority: String!) { todos(where: {priority: {_in: [$priority]}}) { id } }",
+    ))
+    .expect_err("nested list-item variables must match the non-null scalar item type");
+    assert_eq!(error.code, "client.variable.type_mismatch");
+}
+
+#[test]
+fn rejects_variable_defaults_until_cache_identity_can_apply_them() {
+    let error = compile_client(input(
+        "query Defaulted($limit: Int = 10) { todos(limit: $limit) { id } }",
+    ))
+    .expect_err("defaults would currently diverge from replica argument identity");
+    assert_eq!(error.code, "client.variable.default_unsupported");
+}
+
+#[test]
+fn application_surfaces_are_explicit_and_fingerprint_separate_chunks() {
+    let document = ClientDocument::new(
+        "src/routes/todos/+page.graphql",
+        "query Todos { todos { id } }",
+    );
+    let mut common = manifest();
+    common["surface"] = json!({"kind": "application", "name": "web-common", "roles": ["user"]});
+    refresh_schema_fingerprint(&mut common);
+    let common_fingerprint = common["schema_fingerprint"]
+        .as_str()
+        .expect("common fingerprint")
+        .to_string();
+    let common_project = compile_client(ClientCompileInput::new(
+        common.clone(),
+        ClientSurfaceSelector::application("web-common"),
+        vec![document.clone()],
+    ))
+    .expect("compile exact application surface");
+    assert_eq!(common_project.schema_fingerprint, common_fingerprint);
+
+    let mismatch = compile_client(ClientCompileInput::new(
+        common,
+        ClientSurfaceSelector::role("user"),
+        vec![document.clone()],
+    ))
+    .expect_err("a role selector cannot relabel an application surface");
+    assert_eq!(mismatch.code, "client.manifest.surface_mismatch");
+
+    let mut elevated = manifest();
+    elevated["surface"] = json!({"kind": "application", "name": "web-admin", "roles": ["admin"]});
+    refresh_schema_fingerprint(&mut elevated);
+    let elevated_project = compile_client(ClientCompileInput::new(
+        elevated,
+        ClientSurfaceSelector::application("web-admin"),
+        vec![document],
+    ))
+    .expect("compile separate elevated application surface");
+    assert_ne!(
+        common_project.schema_fingerprint,
+        elevated_project.schema_fingerprint
+    );
+}
+
+#[test]
+fn explicit_load_registration_is_the_documented_fallback() {
+    let input = ClientCompileInput::new(
+        manifest(),
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/features/todos.graphql",
+            "query Todos @load { todos { id } }",
+        )],
+    );
+    let error = compile_client(input.clone()).expect_err("registration required");
+    assert_eq!(error.code, "client.route.registration_required");
+    assert!(error.message.contains("--route Todos=/route-id"));
+
+    let project = compile_client(
+        input.with_route_registrations(vec![ClientRouteRegistration::new("Todos", "/todos")]),
+    )
+    .expect("explicit route");
+    assert_eq!(project.routes[0].route, "/todos");
+    assert_eq!(project.routes[0].discovery, ClientRouteDiscovery::Explicit);
+    let routes = file(&project, "routes.ts");
+    assert!(routes.contains("import { Operation_Todos } from './operations/todos.js';"));
+    assert!(routes.contains("export const DISTRIBUTED_ROUTE_OPERATIONS"));
+    assert!(routes.contains("plan: DISTRIBUTED_ROUTES[0], artifact: Operation_Todos"));
+    let sveltekit = file(&project, "sveltekit.ts");
+    assert!(
+        sveltekit.contains(
+            "export const Todos = defineDistributedSvelteKitOperation(DistributedOperation_0);"
+        ),
+        "{sveltekit}"
+    );
+    assert!(sveltekit.contains("export function provideDistributed("));
+    assert!(sveltekit.contains("export function useCommands(): GeneratedCommands"));
+    assert!(
+        !sveltekit.contains("const client ="),
+        "generated modules must not retain a module-global client: {sveltekit}"
+    );
+}
+
+#[test]
+fn sveltekit_wrapper_names_cannot_shadow_generated_runtime_exports() {
+    let error = compile_client(input(
+        r#"
+          query useCommands {
+            todos { id }
+          }
+        "#,
+    ))
+    .expect_err("reserved generated SvelteKit export");
+    assert_eq!(error.code, "client.operation.sveltekit_export_collision");
+    assert!(error.message.contains("useCommands"));
+}
+
+#[test]
+fn sveltekit_wrapper_names_fail_closed_on_typescript_keywords() {
+    for name in ["default", "await"] {
+        let error = compile_client(input(&format!("query {name} {{ todos {{ id }} }}")))
+            .expect_err("TypeScript keyword must not become a generated value binding");
+        assert_eq!(error.code, "client.operation.sveltekit_identifier");
+        assert!(error.message.contains(name), "{error}");
+        let source = error.source.expect("keyword error is source-located");
+        assert_eq!(source.path, "src/routes/todos/+page.graphql");
+        assert_eq!(source.line, 1);
+    }
+
+    let project = compile_client(input("query awaited { todos { id } }"))
+        .expect("near-keyword operation remains valid");
+    assert!(file(&project, "sveltekit.ts").contains("export const awaited ="));
+}
+
+#[test]
+fn expands_root_named_and_inline_fragments_into_canonical_full_text() {
+    let project = compile_client(input(
+        r#"
+          query Fragmented {
+            ...Root
+          }
+          fragment Root on Query {
+            todos {
+              ...Fields
+              ... { priority }
+              ... on todo { headline: title }
+              ...Fields
+            }
+          }
+          fragment Fields on todo { id }
+        "#,
+    ))
+    .expect("compile fragments");
+    let expected = "query Fragmented {\n  todos {\n    id\n    priority\n    headline: title\n    _distributed_tenantId: tenantId\n    _distributed_typename: __typename\n  }\n}\n";
+
+    assert_eq!(project.operations[0].operation_hash, fingerprint(expected));
+    assert!(!file(&project, &project.operations[0].module_path).contains("fragment Root"));
+}
+
+#[test]
+fn merges_identical_root_objects_and_preserves_first_encounter_order() {
+    let project = compile_client(input(
+        r#"
+          query Merged {
+            ...First
+            ...Second
+          }
+          fragment First on Query {
+            rows: todos(limit: 10, offset: 0) { title }
+          }
+          fragment Second on Query {
+            rows: todos(offset: 0, limit: 10) { id title }
+          }
+        "#,
+    ))
+    .expect("merge compatible root selections");
+    let expected = "query Merged {\n  rows: todos(limit: 10, offset: 0) {\n    title\n    id\n    _distributed_tenantId: tenantId\n    _distributed_typename: __typename\n  }\n}\n";
+
+    assert_eq!(project.operations[0].operation_hash, fingerprint(expected));
+}
+
+#[test]
+fn rejects_fragment_graph_errors_deterministically() {
+    let cases = [
+        (
+            "query Missing { todos { ...Absent } }",
+            "client.graphql.fragment_undefined",
+            "Absent",
+        ),
+        (
+            "query Cyclic { todos { ...A } } fragment A on todo { ...B } fragment B on todo { ...A }",
+            "client.graphql.fragment_cycle",
+            "A -> B -> A",
+        ),
+        (
+            "query WrongType { todos { ...Fields } } fragment Fields on Todo { id }",
+            "client.graphql.fragment_type",
+            "current concrete type is `todo`",
+        ),
+        (
+            "query WrongRoot { ...Root } fragment Root on query { todos { id } }",
+            "client.graphql.fragment_type",
+            "current concrete type is `Query`",
+        ),
+        (
+            "query WrongInline { todos { ... on Todo { id } } }",
+            "client.graphql.fragment_type",
+            "current concrete type is `todo`",
+        ),
+    ];
+    for (source, code, message) in cases {
+        let error = compile_client(input(source)).expect_err(source);
+        assert_eq!(error.code, code, "{source}: {error}");
+        assert!(error.message.contains(message), "{source}: {error}");
+        assert!(error.source.is_some());
+    }
+
+    let error = compile_client(input(
+        r#"
+          query Unused { todos { id } }
+          fragment ZedFirst on todo { id }
+          fragment AlphaLater on todo { title }
+        "#,
+    ))
+    .expect_err("source-first unused fragment");
+    assert_eq!(error.code, "client.graphql.fragment_unused");
+    assert!(error.message.contains("ZedFirst"));
+}
+
+#[test]
+fn prevalidates_fragment_graph_through_nested_fields_before_lowering() {
+    let error = compile_client(input(
+        r#"
+          query NestedCycle {
+            todos { ...Recursive }
+          }
+          fragment Recursive on todo {
+            owner { ...Recursive }
+          }
+        "#,
+    ))
+    .expect_err("fragment cycles remain invalid through relationship fields");
+    assert_eq!(error.code, "client.graphql.fragment_cycle");
+    assert!(error.message.contains("Recursive -> Recursive"));
+    assert_eq!(error.source.as_ref().map(|source| source.line), Some(6));
+
+    let error = compile_client(input(
+        "query NestedMissing { todos { owner { ...Missing } } }",
+    ))
+    .expect_err("undefined nested fragments precede unsupported relationship lowering");
+    assert_eq!(error.code, "client.graphql.fragment_undefined");
+    assert!(error.message.contains("Missing"));
+}
+
+#[test]
+fn fragment_definition_order_does_not_change_generated_output() {
+    let operation = "query Stable { todos { ...First ...Second } }\n";
+    let left = compile_client(input(&format!(
+        "{operation}fragment First on todo {{ id }}\nfragment Second on todo {{ title }}\n"
+    )))
+    .expect("first definition order");
+    let right = compile_client(input(&format!(
+        "{operation}fragment Second on todo {{ title }}\nfragment First on todo {{ id }}\n"
+    )))
+    .expect("second definition order");
+
+    assert_eq!(left, right);
+}
+
+#[test]
+fn rejects_directives_on_every_fragment_surface() {
+    let cases = [
+        (
+            "query SpreadDirective { todos { ...Fields @skip(if: true) } } fragment Fields on todo { id }",
+            "client.directive.conditional_unsupported",
+        ),
+        (
+            "query DefinitionDirective { todos { ...Fields } } fragment Fields on todo @custom { id }",
+            "client.directive.unsupported",
+        ),
+        (
+            "query InlineDirective { todos { ... @custom { id } } }",
+            "client.directive.unsupported",
+        ),
+    ];
+    for (source, code) in cases {
+        let error = compile_client(input(source)).expect_err(source);
+        assert_eq!(error.code, code, "{source}: {error}");
+    }
+}
+
+#[test]
+fn rejects_response_key_conflicts_at_the_later_selection() {
+    let source = r#"
+      query Conflict {
+        todos {
+          same: id
+          same: title
+        }
+      }
+    "#;
+    let error = compile_client(input(source)).expect_err("field-name conflict");
+    assert_eq!(error.code, "client.selection.conflict");
+    assert_eq!(error.source.as_ref().map(|source| source.line), Some(5));
+    assert!(error.message.contains("first selection at 4:"));
+
+    for source in [
+        "query ShapeConflict { todos { same: id same: id { value } } }",
+        "query ArgumentConflict { rows: todos(limit: 1) { id } rows: todos(limit: 2) { id } }",
+    ] {
+        let error = compile_client(input(source)).expect_err(source);
+        assert_eq!(error.code, "client.selection.conflict", "{source}: {error}");
+    }
+}
+
+#[test]
+fn fragment_expansion_is_bounded_by_depth_and_total_work() {
+    let mut deep = String::from("query Deep { todos { ...F0 } }\n");
+    for index in 0..65 {
+        deep.push_str(&format!(
+            "fragment F{index} on todo {{ ...F{} }}\n",
+            index + 1
+        ));
+    }
+    deep.push_str("fragment F65 on todo { id }\n");
+    let error = compile_client(input(&deep)).expect_err("depth bound");
+    assert_eq!(error.code, "client.selection.depth");
+
+    let spreads = "...Fields ".repeat(5_000);
+    let expanded =
+        format!("query Expanded {{ todos {{ {spreads} }} }} fragment Fields on todo {{ id }}");
+    let error = compile_client(input(&expanded)).expect_err("expansion work bound");
+    assert_eq!(error.code, "client.selection.expansion_bound");
+}
+
+#[test]
+fn rejects_conditional_and_multi_root() {
+    let cases = [
+        (
+            "query Conditional($yes: Boolean!) { todos { id @include(if: $yes) } }",
+            "client.directive.conditional_unsupported",
+        ),
+        (
+            "query Multi { todos { id } todo(tenantId: \"t\", id: \"1\") { id } }",
+            "client.operation.single_root",
+        ),
+    ];
+    for (source, code) in cases {
+        let error = compile_client(input(source)).expect_err(source);
+        assert_eq!(error.code, code, "{source}: {error}");
+        assert!(error.source.is_some());
+    }
+}
+
+#[test]
+fn recursive_selection_shapes_fail_closed() {
+    let cases = [
+        (
+            "query MissingObject { todos { owner } }",
+            "client.selection.object_required",
+        ),
+        (
+            "query NestedScalar { todos { title { id } } }",
+            "client.selection.scalar_nested",
+        ),
+        (
+            "query NestedUndefined { todos { owner(limit: $missing) { id } } }",
+            "client.argument.denied_or_unknown",
+        ),
+        (
+            "query Metric { todos_aggregate { aggregate { sum } } }",
+            "client.selection.aggregate_metric_unsupported",
+        ),
+        (
+            "query WrongType { todos_aggregate { ...Wrong } } fragment Wrong on todo { id }",
+            "client.graphql.fragment_type",
+        ),
+    ];
+    for (source, code) in cases {
+        let error = compile_client(input(source)).expect_err(source);
+        assert_eq!(error.code, code, "{source}: {error}");
+        assert!(error.source.is_some());
+    }
+}
+
+#[test]
+fn rejects_unknown_scalar_and_codec_instead_of_emitting_unknown() {
+    let mut invalid = manifest();
+    invalid["scalar_codecs"]
+        .as_array_mut()
+        .expect("array")
+        .push(json!({"scalar": "Money", "codec": "money"}));
+    let error = compile_client(ClientCompileInput::new(
+        invalid,
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/routes/todos/+page.graphql",
+            "query Todos { todos { id } }",
+        )],
+    ))
+    .expect_err("unknown codec");
+    assert_eq!(error.code, "client.manifest.scalar_unsupported");
+}
+
+#[test]
+fn rejects_well_formed_but_incompatible_protocol_fingerprint() {
+    let mut invalid = manifest();
+    invalid["protocol_fingerprint"] = json!(fingerprint("different protocol"));
+    let error = compile_client(ClientCompileInput::new(
+        invalid,
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/routes/todos/+page.graphql",
+            "query Todos { todos { id } }",
+        )],
+    ))
+    .expect_err("protocol drift");
+    assert_eq!(error.code, "client.manifest.protocol_fingerprint");
+    assert!(error.message.contains("matching dctl version"));
+}
+
+#[test]
+fn live_companion_fails_closed_on_dependency_or_pagination_drift() {
+    let mut invalid = manifest();
+    let subscription = invalid["roots"]
+        .as_array_mut()
+        .expect("roots")
+        .iter_mut()
+        .find(|root| root["operation"] == "subscription")
+        .expect("subscription");
+    subscription["pagination"]["default_limit"] = json!(24);
+    refresh_schema_fingerprint(&mut invalid);
+    let error = compile_client(ClientCompileInput::new(
+        invalid,
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/routes/todos/+page.graphql",
+            "query Todos @live { todos { id } }",
+        )],
+    ))
+    .expect_err("live drift");
+    assert_eq!(error.code, "client.live.root_mismatch");
+}
+
+#[test]
+fn command_protocol_and_extensions_are_preserved_exactly() {
+    let mutation = "mutation Client_createTodo($commandId: ID!, $input: CreateTodoInput!) { createTodo(commandId: $commandId, input: $input) { id } }";
+    let status =
+        "query Distributed_CommandStatus($commandId: ID!) { commandStatus(commandId: $commandId) { state } }";
+    let mut value = manifest();
+    value["capabilities"]["causal_receipts"] = json!(true);
+    value["capabilities"]["cache_scope"] = json!(true);
+    value["commands"] = json!([{
+        "version": 1,
+        "name": "todo.create",
+        "mutation_field": "createTodo",
+        "grants": ["user"],
+        "input": {
+            "kind": "object",
+            "definition": {
+                "name": "CreateTodoInput",
+                "fields": [
+                    {
+                        "name": "id",
+                        "type_name": "ID",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "string"
+                    },
+                    {
+                        "name": "tenantId",
+                        "type_name": "ID",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "string"
+                    },
+                    {
+                        "name": "title",
+                        "type_name": "String",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "string"
+                    }
+                ]
+            }
+        },
+        "output": {
+            "kind": "object",
+            "definition": {
+                "name": "CreateTodoPayload",
+                "fields": [{
+                    "name": "id",
+                    "type_name": "ID",
+                    "nullable": false,
+                    "list": false,
+                    "item_nullable": false,
+                    "codec": "string"
+                }]
+            }
+        },
+        "operation": mutation,
+        "operation_hash": fingerprint(mutation),
+        "extensions": {
+            "version": 1,
+            "consistency": {"version": 1, "kind": "fact"},
+            "input_defaults": {
+                "version": 1,
+                "defaults": [{"path": ["id"], "generator": "uuid_v7"}]
+            },
+            "effects": {
+                "version": 1,
+                "operations": [{
+                    "kind": "upsert",
+                    "model": "Todo",
+                    "key": {
+                        "fields": [
+                            {
+                                "field": "tenantId",
+                                "value": {"kind": "input", "path": ["tenantId"]}
+                            },
+                            {
+                                "field": "id",
+                                "value": {"kind": "input", "path": ["id"]}
+                            }
+                        ]
+                    },
+                    "fields": [{
+                        "field": "title",
+                        "value": {"kind": "input", "path": ["title"]}
+                    }]
+                }],
+                "fallback": "revalidate"
+            },
+            "confirmations": {
+                "version": 1,
+                "kind": "finite",
+                "expected": [{
+                    "projector": "todos",
+                    "model": "Todo",
+                    "key": {
+                        "fields": [
+                            {
+                                "field": "tenantId",
+                                "value": {"kind": "input", "path": ["tenantId"]}
+                            },
+                            {
+                                "field": "id",
+                                "value": {"kind": "input", "path": ["id"]}
+                            }
+                        ]
+                    }
+                }],
+                "fallback": "revalidate"
+            }
+        }
+    }]);
+    value["projectors"] = json!([{
+        "version": 1,
+        "name": "todos",
+        "facts": ["TodoCreated"],
+        "models": ["Todo"],
+        "dependencies": ["todo_rows"],
+        "causal_confirmation": true
+    }]);
+    value["protocol_operations"] = json!({
+        "version": 1,
+        "command_status": {
+            "name": "Distributed_CommandStatus",
+            "operation": status,
+            "operation_hash": fingerprint(status)
+        }
+    });
+    refresh_schema_fingerprint(&mut value);
+    let project = compile_client(ClientCompileInput::new(
+        value,
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/routes/todos/+page.graphql",
+            "query Todos { todos { id } }",
+        )],
+    ))
+    .expect("compile commands");
+    let commands = file(&project, "commands.ts");
+    let protocol = file(&project, "protocol.ts");
+    assert!(commands.contains(mutation));
+    assert!(commands.contains("createReplicaCommandRuntime"));
+    assert!(commands.contains("import type {\n  DistributedReplica,"));
+    assert!(commands.contains("export type Command_createTodo_Input"));
+    assert!(commands.contains("readonly \"id\"?: string;"));
+    assert!(commands.contains("readonly \"tenantId\": string;"));
+    assert!(commands.contains("\"mutationField\": \"createTodo\""));
+    assert!(commands.contains("\"inputDefaults\""));
+    assert!(commands.contains("\"effects\""));
+    assert!(commands.contains("\"confirmations\""));
+    assert!(commands.contains("\"consistency\": \"fact\""));
+    assert!(commands.contains("\"revalidation\""));
+    assert!(commands.contains("\"trustedPresets\": []"));
+    assert!(commands.contains("export function prepareCommand_createTodo"));
+    assert!(commands.contains("export const COMMAND_ARTIFACTS = [Command_createTodo] as const;"));
+    assert!(commands.contains("export const COMMANDS = {"));
+    assert!(commands.contains("\"todo.create\": Command_createTodo"));
+    assert!(commands
+        .contains("export type GeneratedCommandRuntime = ReplicaCommandRuntime<typeof COMMANDS>;"));
+    assert!(
+        commands.contains("export type GeneratedCommands = GeneratedCommandRuntime['commands'];")
+    );
+    assert!(commands.contains(
+        "export type GeneratedCommandRuntimeOptions = Omit<ReplicaCommandRuntimeOptions, 'status'>;"
+    ));
+    assert!(commands.contains("export function createCommands("));
+    assert!(commands.contains("import { COMMAND_STATUS } from './protocol.js';"));
+    assert!(commands.contains(
+        "return createReplicaCommandRuntime(replica, transport, COMMANDS, {\n    ...options,\n    status: COMMAND_STATUS\n  });"
+    ));
+    assert!(!commands.contains("export const commands ="));
+    assert!(!commands.contains("{ artifact: Command_createTodo"));
+    assert!(!commands.contains("Command_todo.create"));
+    assert!(!commands.contains("\"extensions\""));
+    assert!(protocol.contains(status));
+    assert!(protocol.contains(&fingerprint(status)));
+    assert!(protocol.contains("import type { ReplicaCommandStatusArtifact }"));
+    assert!(protocol.contains("export const COMMAND_STATUS: ReplicaCommandStatusArtifact"));
+    assert!(protocol.contains("\"document\": \"query Distributed_CommandStatus"));
+    assert!(protocol.contains("\"schemaHash\":"));
+    assert!(protocol.contains("\"protocolHash\":"));
+    assert!(protocol.contains("\"surface\": {"));
+    assert!(protocol.contains("\"trustedPresets\": []"));
+    assert!(protocol.contains("\ttrustedPresets: []"));
+}
+
+#[test]
+fn generated_command_typescript_covers_typed_json_fields_and_no_input_wrappers() {
+    let project = compile_client(ClientCompileInput::new(
+        generated_command_types_manifest(),
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/routes/todos/+page.graphql",
+            "query Todos { todos { id } }",
+        )],
+    ))
+    .expect("compile generated command type fixture");
+    let commands = file(&project, "commands.ts");
+assert_eq!(
+        commands,
+        include_str!("../../tests/fixtures/generated-commands.ts")
+    );
+}
+
+#[test]
+fn generated_command_namespaces_reject_prefix_collisions() {
+    let mut value = generated_command_types_manifest();
+    value["commands"][0]["name"] = json!("todo");
+    value["commands"][1]["name"] = json!("todo.complete");
+    refresh_schema_fingerprint(&mut value);
+
+    let error = compile_client(ClientCompileInput::new(
+        value,
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/routes/todos/+page.graphql",
+            "query Todos { todos { id } }",
+        )],
+    ))
+    .expect_err("a command path cannot also be a namespace");
+    assert_eq!(error.code, "client.command.namespace_collision");
+    assert!(error.message.contains("`todo`"));
+    assert!(error.message.contains("`todo.complete`"));
+    assert!(error.message.contains("prefixes"));
+}
+
+#[test]
+fn projected_command_requires_exact_role_safe_direct_projection() {
+    let value = projected_manifest();
+    let parsed = ClientManifest::parse(value, &ClientSurfaceSelector::role("user"))
+        .expect("valid projected direct target");
+    assert!(parsed.projectors[0].facts.is_empty());
+    assert!(!parsed.projectors[0].causal_confirmation);
+    let direct = parsed.commands[0]
+        .extensions
+        .direct_projection
+        .as_ref()
+        .expect("projected command direct target");
+    assert_eq!(direct.topology.version, 1);
+    assert_eq!(direct.topology.name, "todos");
+    assert_eq!(direct.model, "Todo");
+    assert_eq!(direct.change_epoch, "todos-v1");
+    assert!(matches!(
+        direct.partition,
+        Some(super::manifest::ManifestEffectExpression::Input { ref path })
+            if path.as_slice() == ["tenantId"]
+    ));
+
+    let project = compile_client(input_with_manifest(
+        projected_manifest(),
+        "query Todos { todos { id } }",
+    ))
+    .expect("compile projected command");
+    let commands = file(&project, "commands.ts");
+    assert!(commands.contains("\"identityFields\": [\n      \"tenantId\",\n      \"id\"\n    ]"));
+    assert!(!commands.contains("\"identity_fields\""));
+
+    let mut absent = projected_manifest();
+    absent["commands"][0]["extensions"]
+        .as_object_mut()
+        .expect("extensions")
+        .remove("direct_projection");
+    refresh_schema_fingerprint(&mut absent);
+    let error = ClientManifest::parse(absent, &ClientSurfaceSelector::role("user"))
+        .expect_err("projected direct target is mandatory");
+    assert_eq!(error.code, "client.manifest.direct_projection_required");
+
+    let mut non_projected = projected_manifest();
+    non_projected["commands"][0]["extensions"]["consistency"]["kind"] = json!("accepted");
+    refresh_schema_fingerprint(&mut non_projected);
+    let error = ClientManifest::parse(non_projected, &ClientSurfaceSelector::role("user"))
+        .expect_err("accepted commands cannot carry direct projection metadata");
+    assert_eq!(error.code, "client.manifest.direct_projection_unexpected");
+
+    let mut impossible_confirmation = projected_manifest();
+    impossible_confirmation["projectors"][0]["causal_confirmation"] = json!(true);
+    refresh_schema_fingerprint(&mut impossible_confirmation);
+    let error = ClientManifest::parse(
+        impossible_confirmation,
+        &ClientSurfaceSelector::role("user"),
+    )
+    .expect_err("a direct-only owner cannot confirm asynchronous work");
+    assert_eq!(error.code, "client.manifest.projector_inventory");
+
+    let mut embedded = projected_manifest();
+    embedded["models"][0]["normalization"] = json!({"kind": "embedded"});
+    refresh_schema_fingerprint(&mut embedded);
+    let error = ClientManifest::parse(embedded, &ClientSurfaceSelector::role("user"))
+        .expect_err("direct projection requires a complete normalized identity");
+    assert_eq!(error.code, "client.manifest.direct_projection_model");
+}
+
+#[test]
+fn projected_command_rejects_tampered_topology_and_wrong_owner() {
+    let mut tampered = projected_manifest();
+    tampered["commands"][0]["extensions"]["direct_projection"]["topology"]["digest"] =
+        json!(format!("sha256:{}", "AB".repeat(32)));
+    refresh_schema_fingerprint(&mut tampered);
+    let error = ClientManifest::parse(tampered, &ClientSurfaceSelector::role("user"))
+        .expect_err("topology digest must be canonical lowercase SHA-256");
+    assert_eq!(error.code, "client.manifest.hash");
+
+    let mut wrong_owner = projected_manifest();
+    wrong_owner["commands"][0]["extensions"]["direct_projection"]["topology"]["name"] =
+        json!("other_projector");
+    refresh_schema_fingerprint(&mut wrong_owner);
+    let error = ClientManifest::parse(wrong_owner, &ClientSurfaceSelector::role("user"))
+        .expect_err("direct target must use the visible model owner");
+    assert_eq!(error.code, "client.manifest.direct_projection_owner");
+
+    let mut trusted_preset = projected_manifest();
+    trusted_preset["commands"][0]["extensions"]["direct_projection"]["partition"] =
+        json!({"kind": "trusted_preset", "name": "current_tenant"});
+    trusted_preset["commands"][0]["extensions"]["trusted_presets"] =
+        json!([{"name": "current_tenant", "codec": "string"}]);
+    refresh_schema_fingerprint(&mut trusted_preset);
+    ClientManifest::parse(trusted_preset.clone(), &ClientSurfaceSelector::role("user"))
+        .expect("scope-bound trusted preset may define a direct target");
+    let project = compile_client(input_with_manifest(
+        trusted_preset,
+        "query Todos { todos { id } }",
+    ))
+    .expect("compile trusted-preset client surface");
+    assert_eq!(
+        operation_artifact(&project)["protocol"]["trustedPresets"],
+        json!([{"name": "current_tenant", "codec": "string"}]),
+        "every query artifact carries the exact surface-wide preset contract"
+    );
+}
+
+#[test]
+fn rejects_commands_without_causal_identity_or_normative_input_defaults() {
+    let valid = "mutation Client_createTodo($commandId: ID!, $input: CreateTodoInput!) { createTodo(commandId: $commandId, input: $input) { id } }";
+    let status = "query Distributed_CommandStatus($commandId: ID!) { commandStatus(commandId: $commandId) { state } }";
+    let command = |operation: &str, generator: &str| {
+        json!({
+            "version": 1,
+            "name": "CreateTodo",
+            "mutation_field": "createTodo",
+            "grants": ["user"],
+            "input": {
+                "kind": "object",
+                "definition": {
+                    "name": "CreateTodoInput",
+                    "fields": [{
+                        "name": "id",
+                        "type_name": "ID",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "string"
+                    }]
+                }
+            },
+            "output": {
+                "kind": "object",
+                "definition": {
+                    "name": "CreateTodoPayload",
+                    "fields": [{
+                        "name": "id",
+                        "type_name": "ID",
+                        "nullable": false,
+                        "list": false,
+                        "item_nullable": false,
+                        "codec": "string"
+                    }]
+                }
+            },
+            "operation": operation,
+            "operation_hash": fingerprint(operation),
+            "extensions": {
+                "version": 1,
+                "consistency": {"version": 1, "kind": "projected"},
+                "input_defaults": {
+                    "version": 1,
+                    "defaults": [{"path": ["id"], "generator": generator}]
+                }
+            }
+        })
+    };
+    let compile = |entry: JsonValue| {
+        let mut value = manifest();
+        value["capabilities"]["causal_receipts"] = json!(true);
+        value["capabilities"]["cache_scope"] = json!(true);
+        value["commands"] = json!([entry]);
+        value["protocol_operations"] = json!({
+            "version": 1,
+            "command_status": {
+                "name": "Distributed_CommandStatus",
+                "operation": status,
+                "operation_hash": fingerprint(status)
+            }
+        });
+        compile_client(ClientCompileInput::new(
+            value,
+            ClientSurfaceSelector::role("user"),
+            vec![ClientDocument::new(
+                "src/routes/todos/+page.graphql",
+                "query Todos { todos { id } }",
+            )],
+        ))
+    };
+
+    let without_id =
+        "mutation Client_createTodo($input: CreateTodoInput!) { createTodo(input: $input) { id } }";
+    assert_eq!(
+        compile(command(without_id, "uuid_v7"))
+            .expect_err("missing causal identity")
+            .code,
+        "client.manifest.command_operation"
+    );
+    assert_eq!(
+        compile(command(valid, "uuid_v4"))
+            .expect_err("unsupported generator")
+            .code,
+        "client.manifest.input_default_generator"
+    );
+}
+
+#[test]
+fn output_is_identical_for_shuffled_documents() {
+    let mut left_manifest = manifest();
+    left_manifest["models"]
+        .as_array_mut()
+        .expect("models")
+        .push(model("Unused", "unused"));
+    refresh_schema_fingerprint(&mut left_manifest);
+    let right_manifest = left_manifest.clone();
+    let mut tampered_manifest = left_manifest.clone();
+    for key in ["models", "roots", "scalar_codecs", "projectors", "commands"] {
+        tampered_manifest[key]
+            .as_array_mut()
+            .expect("set-like array")
+            .reverse();
+    }
+    let docs = vec![
+        ClientDocument::new(
+            "src/routes/todos/+page.graphql",
+            "query Todos { todos { id } }",
+        ),
+        ClientDocument::new(
+            "src/routes/todo/+page.graphql",
+            "query Todo { todo(tenantId: \"t\", id: \"1\") { title } }",
+        ),
+    ];
+    let left = compile_client(ClientCompileInput::new(
+        left_manifest,
+        ClientSurfaceSelector::role("user"),
+        docs.clone(),
+    ))
+    .expect("left");
+    let right = compile_client(ClientCompileInput::new(
+        right_manifest,
+        ClientSurfaceSelector::role("user"),
+        docs.into_iter().rev().collect(),
+    ))
+    .expect("right");
+    assert_eq!(left, right);
+
+    let error = compile_client(ClientCompileInput::new(
+        tampered_manifest,
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/routes/todos/+page.graphql",
+            "query Todos { todos { id } }",
+        )],
+    ))
+    .expect_err("manifest order is part of the emitter-owned fingerprint");
+    assert_eq!(error.code, "client.manifest.schema_fingerprint");
+}
+
+#[test]
+fn manifest_parser_accepts_embedded_by_pk_and_zero_sized_windows() {
+    let mut value = manifest();
+    value["models"][0]["normalization"] = json!({"kind": "embedded"});
+    value["roots"]
+        .as_array_mut()
+        .expect("roots")
+        .iter_mut()
+        .find(|root| root["kind"] == "by_pk")
+        .expect("by-pk root")["arguments"] = json!([]);
+    for root in value["roots"].as_array_mut().expect("roots") {
+        if root["kind"] == "list" {
+            root["pagination"]["default_limit"] = json!(0);
+            root["pagination"]["max_limit"] = json!(0);
+        }
+    }
+    refresh_schema_fingerprint(&mut value);
+
+    ClientManifest::parse(value, &ClientSurfaceSelector::role("user"))
+        .expect("embedded models and zero-sized authorized windows are valid v6 contracts");
+}
+
+#[test]
+fn manifest_parser_rejects_execution_limits_outside_javascript_integer_range() {
+    for name in ["max_depth", "max_bool_width", "max_in_list"] {
+        let mut value = manifest();
+        value["execution"][name] = json!(9_007_199_254_740_992_u64);
+        refresh_schema_fingerprint(&mut value);
+        let error = ClientManifest::parse(value, &ClientSurfaceSelector::role("user"))
+            .expect_err("runtime codec limits must remain exact JavaScript integers");
+        assert_eq!(error.code, "client.manifest.execution_js_integer", "{name}");
+    }
+}
+
+#[test]
+fn manifest_parser_rejects_list_roots_without_executable_query_plan_semantics() {
+    let cases = [
+        ("filter", &["filter"][..], "client.manifest.root_filter"),
+        ("order", &["order"][..], "client.manifest.root_order"),
+        (
+            "pagination",
+            &["limit", "offset"][..],
+            "client.manifest.root_pagination",
+        ),
+    ];
+
+    for (semantic, removed_argument_kinds, expected_code) in cases {
+        let mut value = manifest();
+        let root = value["roots"]
+            .as_array_mut()
+            .expect("roots")
+            .iter_mut()
+            .find(|root| root["operation"] == "query" && root["kind"] == "list")
+            .expect("query list root");
+        root[semantic] = JsonValue::Null;
+        root["arguments"]
+            .as_array_mut()
+            .expect("list arguments")
+            .retain(|argument| {
+                let kind = argument["kind"].as_str().expect("argument kind");
+                !removed_argument_kinds.contains(&kind)
+            });
+        refresh_schema_fingerprint(&mut value);
+
+        let error = ClientManifest::parse(value, &ClientSurfaceSelector::role("user"))
+            .expect_err("list roots require the complete executable query-plan contract");
+        assert_eq!(error.code, expected_code, "missing {semantic}");
+    }
+}
+
+#[test]
+fn manifest_parser_rejects_filter_input_target_and_argument_drift() {
+    let mut wrong_target = manifest();
+    wrong_target["models"][0]["filter_input"]["relationships"][0]["target_type"] =
+        json!("other_bool_exp");
+    refresh_schema_fingerprint(&mut wrong_target);
+    let error = ClientManifest::parse(wrong_target, &ClientSurfaceSelector::role("user"))
+        .expect_err("relationship filter targets must resolve to the target model contract");
+    assert_eq!(error.code, "client.manifest.filter_input_target_type");
+
+    let mut wrong_argument = manifest();
+    wrong_argument["roots"][0]["arguments"][0]["type_name"] = json!("other_bool_exp");
+    refresh_schema_fingerprint(&mut wrong_argument);
+    let error = ClientManifest::parse(wrong_argument, &ClientSurfaceSelector::role("user"))
+        .expect_err("root filter arguments must name the model filter contract");
+    assert_eq!(error.code, "client.manifest.filter_argument_type");
+}
+
+#[test]
+fn manifest_parser_accepts_mixed_per_model_revision_evidence() {
+    let mut value = manifest();
+    let mut without_evidence = model("Unowned", "Unowned");
+    without_evidence["record_revisions"] = json!(false);
+    without_evidence["tombstones"] = json!(false);
+    value["models"]
+        .as_array_mut()
+        .expect("models")
+        .push(without_evidence);
+    value["capabilities"]["record_revisions"] = json!(false);
+    value["capabilities"]["tombstones"] = json!(false);
+    refresh_schema_fingerprint(&mut value);
+
+    ClientManifest::parse(value, &ClientSurfaceSelector::role("user"))
+        .expect("global record evidence describes the selected query footprint, not any model");
+}
+
+#[test]
+fn rejects_unknown_and_duplicate_route_registrations() {
+    let error = compile_client(
+        input("query Todos { todos { id } }")
+            .with_route_registrations(vec![ClientRouteRegistration::new("Missing", "/missing")]),
+    )
+    .expect_err("unknown registration");
+    assert_eq!(error.code, "client.route.unknown_registration");
+
+    let error = compile_client(
+        input("query Todos { todos { id } }").with_route_registrations(vec![
+            ClientRouteRegistration::new("Todos", "/one"),
+            ClientRouteRegistration::new("Todos", "/two"),
+        ]),
+    )
+    .expect_err("duplicate registration");
+    assert_eq!(error.code, "client.route.duplicate_registration");
+}
+
+#[test]
+fn source_paths_cannot_inject_generated_typescript() {
+    let project = compile_client(ClientCompileInput::new(
+        manifest(),
+        ClientSurfaceSelector::role("user"),
+        vec![ClientDocument::new(
+            "src/injected*/\nexport const compromised = true;\n/**.graphql",
+            "query Safe { todos { id } }",
+        )],
+    ))
+    .expect("compile adversarial source path");
+    let module = file(&project, &project.operations[0].module_path);
+
+    assert!(module.starts_with("/** GENERATED by dctl client. Do not edit. */\n"));
+    assert!(!module.contains("compromised"));
+    assert!(
+        !module.contains("\"source\""),
+        "unsafe provenance must be omitted from executable artifacts"
+    );
+    assert!(file(&project, "manifest.json").contains("\\nexport const compromised"));
+}
diff --git a/distributed_cli/src/generate/gitops.rs b/distributed_cli/src/generate/gitops.rs
index a54971fc..fe803cfa 100644
--- a/distributed_cli/src/generate/gitops.rs
+++ b/distributed_cli/src/generate/gitops.rs
@@ -136,6 +136,21 @@ impl Scaffold {
         )
     }
 
+    /// Helm env for GraphQL query API: injects `DATABASE_URL` from chart values
+    /// when `--query-api` was set (build_with_graphql reads this at runtime).
+    fn query_api_env_yaml(&self) -> String {
+        if !self.query_api {
+            return String::new();
+        }
+
+        r#"            {{ if and .Values.queryApi.enabled .Values.queryApi.databaseUrl }}
+            - name: DATABASE_URL
+              value: {{ .Values.queryApi.databaseUrl | quote }}
+            {{ end }}
+"#
+        .to_string()
+    }
+
     fn knative_broker_names(&self) -> Vec<String> {
         let mut brokers = BTreeSet::new();
         for model in &self.models {
@@ -223,6 +238,14 @@ prometheusRule:
             ""
         };
         let tracing_enabled = self.tracing;
+        let query_api_values = if self.query_api {
+            r#"queryApi:
+  enabled: true
+  databaseUrl: ""
+"#
+        } else {
+            ""
+        };
         format!(
             r#"image:
   repository: {image_repository}
@@ -233,8 +256,7 @@ observability:
   tracing:
     enabled: {tracing_enabled}
     otlpEndpoint: ""
-{bus}{metrics}
-"#,
+{bus}{metrics}{query_api_values}"#,
             image_repository = self.image_repository(),
         )
     }
@@ -243,6 +265,7 @@ observability:
         let name = k8s_name(&self.names.package_name);
         let bus_env = self.bus_env_yaml();
         let tracing_env = self.tracing_env_yaml();
+        let query_api_env = self.query_api_env_yaml();
         format!(
             r#"apiVersion: apps/v1
 kind: Deployment
@@ -272,8 +295,7 @@ spec:
           env:
             - name: BIND_ADDR
               value: 0.0.0.0:3000
-{bus_env}{tracing_env}
-"#,
+{bus_env}{tracing_env}{query_api_env}"#,
         )
     }
 
@@ -372,6 +394,7 @@ spec:
         let name = k8s_name(&self.names.package_name);
         let bus_env = self.bus_env_yaml();
         let tracing_env = self.tracing_env_yaml();
+        let query_api_env = self.query_api_env_yaml();
         format!(
             r#"apiVersion: serving.knative.dev/v1
 kind: Service
@@ -398,8 +421,7 @@ spec:
           env:
             - name: BIND_ADDR
               value: 0.0.0.0:3000
-{bus_env}{tracing_env}
-"#,
+{bus_env}{tracing_env}{query_api_env}"#,
         )
     }
 
diff --git a/distributed_cli/src/generate/mod.rs b/distributed_cli/src/generate/mod.rs
index 4dda9895..3bbbc219 100644
--- a/distributed_cli/src/generate/mod.rs
+++ b/distributed_cli/src/generate/mod.rs
@@ -50,6 +50,7 @@ pub(crate) struct Scaffold {
     pub(crate) bus: Option<BusTarget>,
     pub(crate) metrics: Option<MetricsTarget>,
     pub(crate) include_read_models: bool,
+    pub(crate) query_api: bool,
     pub(crate) tracing: bool,
     pub(crate) gitops: bool,
     pub(crate) gitops_promote: Option<GitopsPromoteTarget>,
@@ -66,6 +67,13 @@ impl Scaffold {
     fn from_spec(spec: ServiceScaffoldSpec) -> Result<Self, ScaffoldError> {
         let names = ScaffoldNames::new(&spec.name)?;
         let models = model_scaffolds(&spec.models)?;
+        // GraphQL execution is SQL-backed. Keep the public pure generator aligned
+        // with the CLI, which promotes its in-memory default to SQLite.
+        let store = if spec.query_api && spec.store == StoreTarget::InMemory {
+            StoreTarget::Sqlite
+        } else {
+            spec.store
+        };
         let read_models = if spec.read_models {
             if models.is_empty() {
                 vec![ModelScaffold::new(&names.package_name)?]
@@ -91,10 +99,11 @@ impl Scaffold {
             names,
             distributed_dependency_path: spec.distributed_dependency_path,
             transport: spec.transport,
-            store: spec.store,
+            store,
             bus: spec.bus,
             metrics: spec.metrics,
             include_read_models: spec.read_models,
+            query_api: spec.query_api,
             tracing: spec.tracing,
             gitops: spec.gitops,
             gitops_promote: spec.gitops_promote,
@@ -117,7 +126,7 @@ impl Scaffold {
         files.push(file("src/main.rs", self.main_rs()));
         files.push(file("src/manifest.rs", self.manifest_rs()));
         files.push(file("src/service.rs", self.service_rs()));
-        if !self.models.is_empty() {
+        if !self.models.is_empty() || (self.query_api && !self.commands.is_empty()) {
             files.push(file("src/models/mod.rs", self.models_mod_rs()));
             for model in &self.models {
                 files.push(file(
@@ -139,6 +148,16 @@ impl Scaffold {
                 self.event_handler_rs(event),
             ));
         }
+        if self.query_api {
+            files.push(file("src/query/mod.rs", self.query_mod_rs()));
+            files.push(file("src/query/roles.rs", self.query_roles_rs()));
+            for model in &self.read_models {
+                files.push(file(
+                    &format!("src/query/{}.rs", model.module_ident),
+                    self.query_model_rs(model),
+                ));
+            }
+        }
         if self.include_read_models {
             files.push(file("src/read_models/mod.rs", self.read_models_mod_rs()));
         }
@@ -185,6 +204,7 @@ mod tests {
             metrics: None,
             models: Vec::new(),
             read_models: false,
+            query_api: false,
             tracing: false,
             commands: Vec::new(),
             events: Vec::new(),
@@ -427,6 +447,123 @@ mod tests {
         assert!(!values.contains("prometheusRule:"), "values.yaml: {values}");
     }
 
+    #[test]
+    fn query_api_emits_query_modules_and_graphql_feature() {
+        let mut s = spec("orders");
+        s.query_api = true;
+        s.read_models = true;
+        s.store = StoreTarget::Sqlite;
+        s.models = vec!["Order".into()];
+        s.gitops = true;
+        let project = generate_service_scaffold(s).unwrap();
+        let paths = paths(&project);
+        assert!(paths.contains(&"src/query/mod.rs"));
+        assert!(paths.contains(&"src/query/roles.rs"));
+        assert!(!paths.contains(&"src/query/commands.rs"));
+        assert!(
+            paths.iter().any(|p| p.starts_with("src/query/")
+                && *p != "src/query/mod.rs"
+                && *p != "src/query/roles.rs"),
+            "expected per-model query module: {paths:?}"
+        );
+        let cargo = contents(&project, "Cargo.toml");
+        assert!(
+            cargo.contains("graphql"),
+            "Cargo.toml must enable graphql feature: {cargo}"
+        );
+        let service = contents(&project, "src/service.rs");
+        assert!(
+            service.contains("build_with_graphql") && service.contains("try_with_graphql"),
+            "service must wire GraphQL: {service}"
+        );
+        assert!(
+            service.contains(".without_http_command_routes()"),
+            "GraphQL scaffold must not also expose unauthenticated direct command POST routes: {service}"
+        );
+        assert!(
+            service.contains("pub type ServiceRepo = SqliteRepository;"),
+            "query-api service must use the SQL repository type: {service}"
+        );
+        assert!(
+            service.contains("let repo = ServiceRepo::connect_and_migrate(&database_url).await?;"),
+            "build_with_graphql must open the persistent repository: {service}"
+        );
+        assert!(
+            service.contains("crate::query::build_engine(&repo, &service"),
+            "build_with_graphql must bind the exact executable service and preserve the repository's GraphQL storage identity: {service}"
+        );
+        assert!(
+            service.contains("AggregateRepository::<_, crate::models::Order>::new(repo.clone())")
+                && service.contains(".typed_command(handlers::"),
+            "build_with_graphql routes must register typed causal commands over the persistent repository: {service}"
+        );
+        assert!(
+            !service.contains("Routes::new().with_dependencies(InMemoryRepository::new())"),
+            "build_with_graphql must not route commands to an in-memory repository: {service}"
+        );
+        let main = contents(&project, "src/main.rs");
+        assert!(
+            main.contains("build_with_graphql"),
+            "main must call build_with_graphql: {main}"
+        );
+        let query_mod = contents(&project, "src/query/mod.rs");
+        assert!(
+            query_mod.contains(
+                "use distributed::graphql::{GraphqlBuildError, GraphqlEngine, GraphqlPoolSource};"
+            )
+                && query_mod.contains("source: impl Into<GraphqlPoolSource>")
+                && query_mod.contains("service: &Service")
+                && query_mod.contains(".service(service)")
+                && query_mod.contains(".protocol_token_key(protocol_token_key)")
+                && query_mod.contains(".graphiql(")
+                && query_mod.contains("graphiql_enabled_from_env")
+                && query_mod.contains(".identity(")
+                && query_mod.contains("public_oidc_identity_from_env"),
+            "query build_engine must accept a causal pool source and wire GraphiQL + OIDC identity defaults: {query_mod}"
+        );
+        // D6: generated public scaffold must wire library OidcBearer helper (not DevHeaders).
+        assert!(
+            query_mod.contains("public_oidc_identity_from_env()")
+                && !query_mod.contains("IdentityConfig::dev_headers"),
+            "public scaffold must call public_oidc_identity_from_env, not DevHeaders: {query_mod}"
+        );
+
+        // GitOps chart injects DATABASE_URL for query API (mirrors tracing OTEL env).
+        let values = contents(&project, ".gitops/deploy/values.yaml");
+        assert!(
+            values.contains("queryApi:") && values.contains("databaseUrl:"),
+            "values.yaml must declare queryApi.databaseUrl: {values}"
+        );
+        assert!(values.contains("enabled: true"));
+        let deployment = contents(&project, ".gitops/deploy/templates/deployment.yaml");
+        assert!(
+            deployment.contains("DATABASE_URL"),
+            "deployment must inject DATABASE_URL: {deployment}"
+        );
+        assert!(
+            deployment.contains(".Values.queryApi.databaseUrl"),
+            "deployment must bind DATABASE_URL from values: {deployment}"
+        );
+        assert!(deployment.contains("if and .Values.queryApi.enabled .Values.queryApi.databaseUrl"));
+    }
+
+    #[test]
+    fn public_query_api_scaffold_promotes_in_memory_store_to_sqlite() {
+        let mut s = spec("orders");
+        s.query_api = true;
+        s.store = StoreTarget::InMemory;
+        let project = generate_service_scaffold(s).unwrap();
+        let cargo = contents(&project, "Cargo.toml");
+        let service = contents(&project, "src/service.rs");
+
+        assert!(cargo.contains("\"sqlite\""), "Cargo.toml: {cargo}");
+        assert!(
+            service.contains("pub type ServiceRepo = SqliteRepository;"),
+            "query-api scaffold must use its enabled SQL repository: {service}"
+        );
+        assert!(!service.contains("pub type ServiceRepo = InMemoryRepository;"));
+    }
+
     #[test]
     fn tracing_scaffold_enables_otel_feature_and_gitops_env_values() {
         let mut s = spec("orders");
diff --git a/distributed_cli/src/generate/service_crate.rs b/distributed_cli/src/generate/service_crate.rs
index 19725e29..b87c1ba3 100644
--- a/distributed_cli/src/generate/service_crate.rs
+++ b/distributed_cli/src/generate/service_crate.rs
@@ -69,11 +69,14 @@ tokio = {{ version = "1", features = ["macros", "net", "rt-multi-thread"] }}
         if self.tracing {
             features.push("otel");
         }
+        if self.query_api {
+            features.push("graphql");
+        }
         features
     }
 
     pub(super) fn lib_rs(&self) -> String {
-        let models = if !self.models.is_empty() {
+        let models = if !self.models.is_empty() || (self.query_api && !self.commands.is_empty()) {
             "pub mod models;\n"
         } else {
             ""
@@ -83,10 +86,15 @@ tokio = {{ version = "1", features = ["macros", "net", "rt-multi-thread"] }}
         } else {
             ""
         };
+        let query = if self.query_api {
+            "pub mod query;\n"
+        } else {
+            ""
+        };
         format!(
             r#"pub mod handlers;
 pub mod manifest;
-{models}{read_models}pub mod service;
+{models}{read_models}{query}pub mod service;
 
 pub use manifest::distributed_manifest;
 "#
@@ -94,7 +102,7 @@ pub use manifest::distributed_manifest;
     }
 
     pub(super) fn main_rs(&self) -> String {
-        let error_type = if self.tracing {
+        let error_type = if self.tracing || self.query_api {
             "Box<dyn std::error::Error + Send + Sync + 'static>"
         } else {
             "Box<dyn std::error::Error>"
@@ -113,6 +121,17 @@ pub use manifest::distributed_manifest;
             "    result?;\n"
         };
         let tracing_setup = self.tracing_setup_rs(error_type);
+        let service_init = if self.query_api {
+            format!(
+                "    let service = {crate}::service::build_with_graphql().await?;\n",
+                crate = self.names.crate_ident
+            )
+        } else {
+            format!(
+                "    let service = {crate}::service::in_memory();\n",
+                crate = self.names.crate_ident
+            )
+        };
         let serve_block = match self.transport {
             ServiceTransport::Http => {
                 "    let result = distributed::microsvc::serve(service, &addr).await;\n".to_string()
@@ -131,12 +150,10 @@ pub use manifest::distributed_manifest;
             r#"#[tokio::main]
 async fn main() -> Result<(), {error_type}> {{
 {tracing_init}    let addr = std::env::var("BIND_ADDR").unwrap_or_else(|_| "127.0.0.1:3000".to_string());
-    let service = {crate_ident}::service::in_memory();
-{serve_block}{tracing_shutdown}    Ok(())
+{service_init}{serve_block}{tracing_shutdown}    Ok(())
 }}
 
 {tracing_setup}"#,
-            crate_ident = self.names.crate_ident,
         )
     }
 
@@ -206,9 +223,17 @@ pub fn service_manifest() -> ServiceManifest {{
     }
 
     pub(super) fn service_rs(&self) -> String {
+        let repo_import = if self.query_api {
+            match self.store {
+                StoreTarget::Postgres => "PostgresRepository",
+                _ => "SqliteRepository",
+            }
+        } else {
+            "InMemoryRepository"
+        };
         let mut manifest_imports = vec![
             "microsvc::{Routes, Service}",
-            "InMemoryRepository",
+            repo_import,
             "ServiceManifest",
         ];
         if self.metrics == Some(MetricsTarget::Prometheus) {
@@ -217,6 +242,9 @@ pub fn service_manifest() -> ServiceManifest {{
         if self.tracing {
             manifest_imports.push("TracingManifest");
         }
+        if self.query_api && !self.commands.is_empty() {
+            manifest_imports.push("AggregateRepository");
+        }
         let manifest_imports = manifest_imports.join(", ");
         let registrations = self
             .commands
@@ -228,6 +256,41 @@ pub fn service_manifest() -> ServiceManifest {{
                     .map(|handler| format!("        event handlers::{},\n", handler.module_ident)),
             )
             .collect::<String>();
+        let event_registrations = self
+            .events
+            .iter()
+            .map(|handler| format!("        event handlers::{},\n", handler.module_ident))
+            .collect::<String>();
+        let typed_route_attachments = self
+            .commands
+            .iter()
+            .map(|handler| {
+                let model_type = self
+                    .command_model(handler)
+                    .map(|model| model.type_ident.as_str())
+                    .unwrap_or("CommandAggregate");
+                format!(
+                    r#"    let service = service.routes(
+        Routes::new()
+            .with_repo(AggregateRepository::<_, crate::models::{model_type}>::new(repo.clone()))
+            .typed_command(handlers::{module}::command())
+            .handle(handlers::{module}::handle),
+    );
+"#,
+                    module = handler.module_ident,
+                )
+            })
+            .collect::<String>();
+        let event_route_attachment = if self.events.is_empty() {
+            String::new()
+        } else {
+            format!(
+                r#"    let service = service.routes(distributed::routes!(
+        Routes::new().with_dependencies(repo.clone()),
+{event_registrations}    ));
+"#
+            )
+        };
         let manifest_commands = self
             .commands
             .iter()
@@ -263,6 +326,101 @@ pub fn service_manifest() -> ServiceManifest {{
             ""
         };
 
+        if self.query_api {
+            let (repo_ty, connect_default) = match self.store {
+                StoreTarget::Postgres => (
+                    "PostgresRepository",
+                    r#""postgres://postgres:postgres@127.0.0.1:5432/postgres""#,
+                ),
+                _ => ("SqliteRepository", r#""sqlite::memory:""#),
+            };
+            let protocol_key_read = if self.commands.is_empty() {
+                String::new()
+            } else {
+                "    let protocol_token_key = graphql_protocol_token_key()?;\n".into()
+            };
+            let protocol_key_argument = if self.commands.is_empty() {
+                ""
+            } else {
+                ", protocol_token_key"
+            };
+            let protocol_key_helper = if self.commands.is_empty() {
+                String::new()
+            } else {
+                r#"
+fn graphql_protocol_token_key(
+) -> Result<[u8; 32], Box<dyn std::error::Error + Send + Sync>> {
+    use std::io::{Error, ErrorKind};
+
+    let secret = std::env::var("DISTRIBUTED_GRAPHQL_PROTOCOL_TOKEN_KEY").map_err(|_| {
+        Error::new(
+            ErrorKind::NotFound,
+            "DISTRIBUTED_GRAPHQL_PROTOCOL_TOKEN_KEY must be a stable 32-byte deployment secret",
+        )
+    })?;
+    let bytes = secret.into_bytes();
+    let key: [u8; 32] = bytes.try_into().map_err(|_| {
+        Error::new(
+            ErrorKind::InvalidInput,
+            "DISTRIBUTED_GRAPHQL_PROTOCOL_TOKEN_KEY must be exactly 32 UTF-8 bytes",
+        )
+    })?;
+    if key.iter().all(|byte| *byte == 0) {
+        return Err(Error::new(
+            ErrorKind::InvalidInput,
+            "DISTRIBUTED_GRAPHQL_PROTOCOL_TOKEN_KEY must not be all zero",
+        )
+        .into());
+    }
+    Ok(key)
+}
+"#
+                .to_string()
+            };
+            return format!(
+                r#"use std::sync::Arc;
+
+use distributed::{{{manifest_imports}}};
+
+use crate::handlers;
+
+pub type ServiceRepo = {repo_ty};
+
+pub fn build(repo: ServiceRepo) -> Arc<Service> {{
+    Arc::new(build_service(repo))
+}}
+
+fn build_service(repo: ServiceRepo) -> Service {{
+    let service = Service::new()
+        .named({service_name})
+        .without_http_command_routes();
+{typed_route_attachments}{event_route_attachment}    service
+}}
+
+/// Build the service with GraphQL mounted at `POST /graphql`.
+///
+/// Reads `DATABASE_URL` (defaults to {connect_default} for local dev).
+pub async fn build_with_graphql() -> Result<Arc<Service>, Box<dyn std::error::Error + Send + Sync>> {{
+    let database_url =
+        std::env::var("DATABASE_URL").unwrap_or_else(|_| {connect_default}.to_string());
+    let repo = ServiceRepo::connect_and_migrate(&database_url).await?;
+    let service = build_service(repo.clone());
+{protocol_key_read}    let engine = crate::query::build_engine(&repo, &service{protocol_key_argument})?;
+    Ok(Arc::new(service.try_with_graphql(engine)?))
+}}
+
+{protocol_key_helper}
+
+pub fn manifest() -> ServiceManifest {{
+    ServiceManifest::new({service_name})
+{manifest_commands}{manifest_events}{manifest_metrics}{manifest_tracing}        .transport({transport})
+}}
+"#,
+                service_name = rust_string(&self.names.package_name),
+                transport = rust_string(transport),
+            );
+        }
+
         format!(
             r#"use std::sync::Arc;
 
@@ -307,17 +465,63 @@ pub fn manifest() -> ServiceManifest {{
             .collect::<Vec<_>>()
             .join("");
 
-        format!(
-            r#"{modules}
-use serde::{{Deserialize, Serialize}};
+        let fallback_aggregate =
+            if self.query_api && self.models.is_empty() && !self.commands.is_empty() {
+                r#"
+use distributed::{sourced, Entity, Snapshot};
 
+#[derive(Default, Snapshot)]
+pub struct CommandAggregate {
+    pub entity: Entity,
+    pub name: Option<String>,
+    pub status: String,
+}
 
-#[derive(Clone, Debug, Serialize, Deserialize)]
-pub struct CommandInput {{
+#[sourced(entity)]
+impl CommandAggregate {
+    #[event("service.command_recorded")]
+    pub fn record_command(&mut self, command: String, id: String, name: Option<String>) {
+        self.entity.set_id(&id);
+        self.name = name;
+        self.status = command;
+    }
+}
+"#
+            } else {
+                ""
+            };
+
+        let command_types = if self.query_api {
+            r#"#[derive(Clone, Debug, Deserialize, distributed::GraphqlInput)]
+pub struct CommandInput {
+    pub id: String,
+    pub name: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, distributed::GraphqlOutput)]
+pub struct CommandOutput {
+    pub command: String,
+    pub id: String,
+    pub model: String,
+    pub name: Option<String>,
+}
+"#
+        } else {
+            r#"#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct CommandInput {
     pub id: String,
     #[serde(default)]
     pub name: Option<String>,
-}}
+}
+"#
+        };
+
+        format!(
+            r#"{modules}
+use serde::{{Deserialize, Serialize}};
+
+{fallback_aggregate}
+{command_types}
 "#
         )
     }
@@ -360,6 +564,48 @@ impl {model_struct} {{
     }
 
     pub(super) fn command_handler_rs(&self, handler: &MessageHandler) -> String {
+        if self.query_api {
+            let (model_type, model_name) = self
+                .command_model(handler)
+                .map(|model| (model.type_ident.as_str(), model.name.as_str()))
+                .unwrap_or(("CommandAggregate", "CommandAggregate"));
+            return format!(
+                r#"use distributed::graphql::{{typed_command, Accepted, PreparedCommand, TypedCommand}};
+use distributed::microsvc::{{CausalCommandContext, HandlerError}};
+
+use crate::models::{{CommandInput, CommandOutput, {model_type}}};
+
+pub const COMMAND: &str = {message_name};
+pub const MODEL: &str = {model_name};
+
+pub fn command() -> TypedCommand<CommandInput, Accepted<CommandOutput>> {{
+    typed_command::<CommandInput, Accepted<CommandOutput>>(COMMAND).roles(["user"])
+}}
+
+pub async fn handle(
+    ctx: &CausalCommandContext<'_, {model_type}>,
+    input: CommandInput,
+) -> Result<PreparedCommand<Accepted<CommandOutput>>, HandlerError> {{
+    let mut aggregate = match ctx.load(&input.id).await? {{
+        Some(aggregate) => aggregate,
+        None => ctx.create(),
+    }};
+    aggregate.record_command(COMMAND.to_string(), input.id.clone(), input.name.clone())?;
+    ctx.stage(aggregate)?;
+    PreparedCommand::<Accepted<CommandOutput>>::prepare(CommandOutput {{
+        command: COMMAND.to_string(),
+        id: input.id,
+        model: MODEL.to_string(),
+        name: input.name,
+    }})
+    .map_err(|error| HandlerError::Other(Box::new(error)))
+}}
+"#,
+                message_name = rust_string(&handler.message_name),
+                model_name = rust_string(model_name),
+            );
+        }
+
         if let Some(model) = self.command_model(handler) {
             format!(
                 r#"use distributed::{{
@@ -478,4 +724,105 @@ use serde::{{Deserialize, Serialize}};
             .find(|model| model.name == message_model)
             .or_else(|| self.models.first())
     }
+
+    pub(super) fn query_mod_rs(&self) -> String {
+        let mods = self
+            .read_models
+            .iter()
+            .map(|m| format!("pub mod {};\n", m.module_ident))
+            .collect::<String>();
+        let tighten_hint = if self.read_models.is_empty() {
+            String::new()
+        } else {
+            let names = self
+                .read_models
+                .iter()
+                .map(|m| m.module_ident.as_str())
+                .collect::<Vec<_>>()
+                .join(", ");
+            format!(
+                "// Tighten grants by replacing grant_all with:\n//   distributed::graphql_models!(builder, {names})\n// after filling permissions() in each model module.\n"
+            )
+        };
+        let protocol_key_parameter = if self.commands.is_empty() {
+            ""
+        } else {
+            ",\n    protocol_token_key: [u8; 32]"
+        };
+        let protocol_key_builder = if self.commands.is_empty() {
+            ""
+        } else {
+            "\n        .protocol_token_key(protocol_token_key)"
+        };
+        format!(
+            r#"//! GraphQL query exposure (deny-by-default permissions).
+//!
+//! One module per exposed read model. Command mutations are derived from the
+//! executable service's typed causal inventory.
+
+{mods}pub mod roles;
+
+use distributed::graphql::{{GraphqlBuildError, GraphqlEngine, GraphqlPoolSource}};
+use distributed::microsvc::Service;
+
+/// Build the GraphQL engine for this service.
+///
+/// `DATABASE_URL` is used by `service::build_with_graphql`; defaults to an
+/// in-memory SQLite database when unset (dev only).
+pub fn build_engine(
+    source: impl Into<GraphqlPoolSource>,
+    service: &Service{protocol_key_parameter},
+) -> Result<GraphqlEngine, GraphqlBuildError> {{
+{tighten_hint}    // GraphiQL policy lives in `distributed::graphql::graphiql_enabled_from_env`
+    // (GRAPHIQL override; RUST_ENV/ENV/APP_ENV production → off; else on).
+    let graphiql = distributed::graphql::graphiql_enabled_from_env();
+    // Public GraphQL identity (D6/D7): always OidcBearer + require_auth=true.
+    // Set OIDC_ISSUER + OIDC_AUDIENCE (or OIDC_CLIENT_ID). Unset → placeholder
+    // issuer (still OidcBearer; ambient headers never trusted). For local
+    // GraphiQL ambient headers only, pass IdentityMode::DevHeaders explicitly.
+    let identity = distributed::graphql::public_oidc_identity_from_env();
+    GraphqlEngine::from_manifest(&crate::distributed_manifest(), source)?
+        .service(service){protocol_key_builder}
+        .roles(roles::ALL)
+        .grant_all(roles::USER)
+        .graphiql(graphiql)
+        .identity(identity)
+        .build()
+}}
+"#
+        )
+    }
+
+    pub(super) fn query_roles_rs(&self) -> String {
+        r#"//! Role vocabulary for GraphQL permissions.
+
+pub const USER: &str = "user";
+pub const ANONYMOUS: &str = "anonymous";
+
+/// Roles declared on the engine builder.
+pub const ALL: &[&str] = &[USER, ANONYMOUS];
+"#
+        .to_string()
+    }
+
+    pub(super) fn query_model_rs(&self, model: &ModelScaffold) -> String {
+        format!(
+            r#"//! Permissions for `{view}`.
+
+use distributed::graphql::{{read, ModelPermissions}};
+
+use crate::read_models::{view};
+
+pub type Model = {view};
+
+pub fn permissions() -> ModelPermissions<{view}> {{
+    ModelPermissions::new()
+        // Deny-by-default until roles are granted. grant_all(USER) in mod.rs
+        // covers the scaffold default; tighten .columns(...) / .rows(...) for prod.
+        .grant(super::roles::USER, read().all_columns().aggregations())
+}}
+"#,
+            view = model.view_ident,
+        )
+    }
 }
diff --git a/distributed_cli/src/lib.rs b/distributed_cli/src/lib.rs
index e5681b04..b55cd15a 100644
--- a/distributed_cli/src/lib.rs
+++ b/distributed_cli/src/lib.rs
@@ -19,15 +19,21 @@
 
 mod atlas;
 mod cli;
+mod client_compiler;
 mod generate;
 mod manifest_harness;
 mod skills;
 
 pub use atlas::{render_atlas_schema, AtlasDatabaseUrl, AtlasSchemaSpec};
 pub use cli::{
-    run, AgentHarness, Bus, DescribeArgs, Framework, GitopsPromote, ManifestFormat, Metrics,
-    ScaffoldArgs, SchemaArgs, SchemaDialect, SchemaFormat, ServiceArgs, ServiceCommands,
-    SkillsArgs, SkillsCommands, SkillsInitArgs, Store, Transport,
+    run, AgentHarness, Bus, ClientArgs, ClientManifestArgs, DescribeArgs, Framework, GitopsPromote,
+    ManifestFormat, Metrics, ScaffoldArgs, SchemaArgs, SchemaDialect, SchemaFormat, ServiceArgs,
+    ServiceCommands, SkillsArgs, SkillsCommands, SkillsInitArgs, Store, Transport,
+};
+pub use client_compiler::{
+    compile_client, ClientCompileError, ClientCompileInput, ClientDocument, ClientRouteDiscovery,
+    ClientRouteRegistration, ClientSourceLocation, ClientSurfaceSelector, GeneratedClientFile,
+    GeneratedClientProject, GeneratedOperationSummary, GeneratedRoutePlan,
 };
 pub use generate::{generate_service_scaffold, package_name};
 pub use skills::{embedded_skills, generate_skills, EmbeddedFile, EmbeddedSkill, SkillsInitSpec};
@@ -53,6 +59,8 @@ pub struct ServiceScaffoldSpec {
     pub models: Vec<String>,
     /// Generate placeholder read-model modules and register them in the manifest.
     pub read_models: bool,
+    /// Generate `src/query/` GraphQL exposure skeleton + `graphql` feature wiring.
+    pub query_api: bool,
     /// Enable Distributed's optional tracing span feature and GitOps OTLP env metadata.
     pub tracing: bool,
     /// Command handler message names (raw; empty → a default command is derived).
diff --git a/distributed_cli/src/main.rs b/distributed_cli/src/main.rs
index cffb6396..d3ed4e23 100644
--- a/distributed_cli/src/main.rs
+++ b/distributed_cli/src/main.rs
@@ -1,8 +1,8 @@
 use clap::Parser;
 use distributed_cli::ServiceArgs;
 
-/// The `dctl` CLI: scaffold Distributed services, describe their manifest, and
-/// render schema artifacts (SQL or Atlas Operator resources).
+/// The `dctl` CLI: scaffold Distributed services, compile typed client
+/// artifacts, describe manifests, and render schema artifacts.
 #[derive(Parser, Debug)]
 #[command(name = "dctl", version, about, long_about = None)]
 struct Cli {
diff --git a/distributed_cli/src/manifest_harness.rs b/distributed_cli/src/manifest_harness.rs
index 8bdede6f..235e5683 100644
--- a/distributed_cli/src/manifest_harness.rs
+++ b/distributed_cli/src/manifest_harness.rs
@@ -1,8 +1,8 @@
-//! The manifest harness: `describe`/`schema` compile a tiny generated crate
-//! that depends on the target service, calls its `distributed_manifest()`
-//! entrypoint, and prints the manifest JSON or rendered SQL. This module owns
-//! that codegen and the nested `cargo` invocations; the `cli` module maps
-//! command flags onto [`HarnessOptions`]/[`HarnessMode`].
+//! The manifest harness: `describe`/`schema`/`client-manifest` compile a tiny
+//! generated crate that depends on the target service and calls its portable
+//! export entrypoint. This module owns that codegen and the nested `cargo`
+//! invocations; the `cli` module maps flags onto
+//! [`HarnessOptions`]/[`HarnessMode`].
 
 use serde::Deserialize;
 use std::error::Error;
@@ -28,6 +28,8 @@ pub(crate) struct HarnessOptions {
 pub(crate) enum HarnessMode {
     DescribeJson,
     SchemaSql(SchemaDialect),
+    SchemaGraphql,
+    ClientManifest,
 }
 
 impl HarnessMode {
@@ -36,6 +38,17 @@ impl HarnessMode {
             HarnessMode::DescribeJson => "describe-json",
             HarnessMode::SchemaSql(SchemaDialect::Postgres) => "schema-postgres",
             HarnessMode::SchemaSql(SchemaDialect::Sqlite) => "schema-sqlite",
+            HarnessMode::SchemaGraphql => "schema-graphql",
+            HarnessMode::ClientManifest => "client-manifest",
+        }
+    }
+
+    fn default_entrypoint(self) -> &'static str {
+        match self {
+            HarnessMode::ClientManifest => "distributed_client_surface",
+            HarnessMode::DescribeJson | HarnessMode::SchemaSql(_) | HarnessMode::SchemaGraphql => {
+                "distributed_manifest"
+            }
         }
     }
 }
@@ -54,10 +67,17 @@ pub(crate) fn run_manifest_harness(
         .entrypoint
         .clone()
         .map(|entrypoint| qualify_entrypoint(&crate_ident, &entrypoint))
-        .unwrap_or_else(|| Ok(format!("{crate_ident}::distributed_manifest")))?;
+        .unwrap_or_else(|| Ok(format!("{crate_ident}::{}", mode.default_entrypoint())))?;
     validate_rust_path(&entrypoint)?;
 
-    let harness_root = package.directory.join("target/dctl-manifest-harness");
+    // Keep the standalone harness beside workspace packages, never underneath
+    // one. A harness nested below a package that uses `workspace = true`
+    // dependencies becomes that package's nearest workspace ancestor and Cargo
+    // resolves its inherited dependencies against the generated harness.
+    let harness_root = package
+        .target_directory
+        .join("dctl-manifest-harness")
+        .join(&package.name);
     let harness_dir = harness_root.join(mode.cache_key());
     fs::create_dir_all(harness_dir.join("src"))?;
     fs::write(
@@ -166,6 +186,28 @@ fn harness_main_rs(entrypoint: &str, mode: HarnessMode) -> String {
 "#
             )
         }
+        HarnessMode::SchemaGraphql => format!(
+            r#"fn main() {{
+    let manifest = {entrypoint}();
+    let envelope = distributed::DistributedManifestEnvelope::new(manifest);
+    let sdl = envelope
+        .project
+        .graphql_sdl()
+        .expect("manifest GraphQL SDL should render");
+    print!("{{}}", sdl);
+}}
+"#
+        ),
+        HarnessMode::ClientManifest => format!(
+            r#"fn main() {{
+    let export: distributed::graphql::DistributedClientSurfaceExport = {entrypoint}();
+    let manifest = export
+        .manifest()
+        .expect("client Surface should compile into a manifest");
+    println!("{{}}", serde_json::to_string_pretty(&manifest).expect("client manifest should serialize"));
+}}
+"#
+        ),
     }
 }
 
@@ -191,6 +233,7 @@ fn resolve_target_manifest_path(
 struct CargoPackage {
     name: String,
     directory: PathBuf,
+    target_directory: PathBuf,
 }
 
 fn cargo_package(
@@ -213,6 +256,7 @@ fn cargo_package(
     }
 
     let metadata: CargoMetadata = serde_json::from_slice(&output.stdout)?;
+    let target_directory = PathBuf::from(&metadata.target_directory);
     let selected = if let Some(package_name) = package_name {
         metadata
             .packages
@@ -244,12 +288,14 @@ fn cargo_package(
     Ok(CargoPackage {
         name: selected.name,
         directory,
+        target_directory,
     })
 }
 
 #[derive(Debug, Deserialize)]
 struct CargoMetadata {
     packages: Vec<CargoMetadataPackage>,
+    target_directory: String,
 }
 
 #[derive(Debug, Deserialize)]
@@ -330,4 +376,21 @@ mod tests {
             "main.rs: {main_rs}"
         );
     }
+
+    #[test]
+    fn client_harness_uses_the_shared_surface_export_compiler() {
+        assert_eq!(
+            HarnessMode::ClientManifest.default_entrypoint(),
+            "distributed_client_surface"
+        );
+        let main_rs = harness_main_rs(
+            "orders_service::distributed_client_surface",
+            HarnessMode::ClientManifest,
+        );
+        assert!(main_rs.contains(
+            "let export: distributed::graphql::DistributedClientSurfaceExport = orders_service::distributed_client_surface();"
+        ));
+        assert!(main_rs.contains(".manifest()"));
+        assert!(!main_rs.contains("build_surface"));
+    }
 }
diff --git a/distributed_cli/src/skills.rs b/distributed_cli/src/skills.rs
index 0acdfad9..9f5d42e6 100644
--- a/distributed_cli/src/skills.rs
+++ b/distributed_cli/src/skills.rs
@@ -40,7 +40,7 @@ pub struct EmbeddedSkill {
     pub files: &'static [EmbeddedFile],
 }
 
-static SKILLS: [EmbeddedSkill; 3] = [
+static SKILLS: [EmbeddedSkill; 4] = [
     EmbeddedSkill {
         name: "distributed-usage",
         description: "Build Distributed CQRS/event-sourced Rust services where you mostly write models and handlers while the framework and dctl generate persistence, transports, manifests, and deploy wiring. Use model-first TDD to specify plain aggregate behavior with fast unit tests before implementing models and thin handlers. Use when designing, testing, writing, or modifying a Distributed service or domain model.",
@@ -65,6 +65,14 @@ static SKILLS: [EmbeddedSkill; 3] = [
             contents: include_str!("../skills/distributed-schema/SKILL.md"),
         }],
     },
+    EmbeddedSkill {
+        name: "distributed-graphql",
+        description: "Expose generated GraphQL queries and typed causal commands over Distributed services. Use when adding a GraphQL API, roles, model exposure, subscriptions, command mutations, or generated clients.",
+        files: &[EmbeddedFile {
+            relative_path: "SKILL.md",
+            contents: include_str!("../skills/distributed-graphql/SKILL.md"),
+        }],
+    },
 ];
 
 /// The registry of skills embedded in this binary.
diff --git a/distributed_cli/tests/cli_client.rs b/distributed_cli/tests/cli_client.rs
new file mode 100644
index 00000000..bdb6ca58
--- /dev/null
+++ b/distributed_cli/tests/cli_client.rs
@@ -0,0 +1,760 @@
+//! Integration tests for `dctl client`: drive the real binary against a small
+//! manifest-v1 project and verify generation, read-only drift checking,
+//! authorization-surface selection, document discovery, and explicit `@load`
+//! route registration.
+
+use std::collections::BTreeMap;
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::{Command, Output};
+
+const ROLE_MANIFEST: &str = r#"{
+  "manifest_version": 1,
+  "protocol_version": 1,
+  "service_id": "todos",
+  "surface": {
+    "kind": "role",
+    "name": "user"
+  },
+  "schema_fingerprint": "sha256:fc1d0cdb83cb42d07d9dfaf0944b24ea3e95b1dafc63ad320f9e93ffe2e3d9b9",
+  "protocol_fingerprint": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+  "execution": {
+    "max_depth": 8,
+    "max_complexity": 500,
+    "max_bool_width": 256,
+    "max_in_list": 1000,
+    "complexity": {
+      "version": 1,
+      "scalar": 1,
+      "belongs_to": 2,
+      "has_many": 10,
+      "m2m": 12,
+      "aggregate": 8,
+      "list_root": 3,
+      "by_pk": 1,
+      "list_fanout": 5
+    }
+  },
+  "capabilities": {
+    "live_queries": false,
+    "record_revisions": false,
+    "tombstones": false,
+    "causal_receipts": false,
+    "live_resume": false,
+    "query_fallback": "revalidate",
+    "cache_scope": true,
+    "confirmed_persistence": false
+  },
+  "scalar_codecs": [
+    {
+      "scalar": "BigInt",
+      "codec": "json_number_precision_limited"
+    },
+    {
+      "scalar": "Boolean",
+      "codec": "boolean"
+    },
+    {
+      "scalar": "Bytea",
+      "codec": "base64"
+    },
+    {
+      "scalar": "Float",
+      "codec": "float64"
+    },
+    {
+      "scalar": "ID",
+      "codec": "string"
+    },
+    {
+      "scalar": "Int",
+      "codec": "int32"
+    },
+    {
+      "scalar": "JSON",
+      "codec": "json"
+    },
+    {
+      "scalar": "String",
+      "codec": "string"
+    },
+    {
+      "scalar": "Timestamptz",
+      "codec": "string_unvalidated_timestamp"
+    }
+  ],
+  "models": [
+    {
+      "id": "Todo",
+      "typename": "Todo",
+      "source_table": "todos",
+      "dependencies": [
+        "todos"
+      ],
+      "normalization": {
+        "kind": "normalized",
+        "fields": [
+          {
+            "name": "id",
+            "codec": "string"
+          }
+        ],
+        "encoding": "canonical_json_tuple_v1"
+      },
+      "fields": [
+        {
+          "name": "id",
+          "scalar": "ID",
+          "codec": "string",
+          "nullable": false
+        },
+        {
+          "name": "title",
+          "scalar": "String",
+          "codec": "string",
+          "nullable": false
+        }
+      ],
+      "relationships": [],
+      "filter_input": {
+        "type_name": "todos_bool_exp",
+        "fields": [
+          {
+            "name": "id",
+            "operators": [
+              "_eq",
+              "_neq",
+              "_gt",
+              "_gte",
+              "_lt",
+              "_lte",
+              "_in",
+              "_nin",
+              "_is_null"
+            ]
+          },
+          {
+            "name": "title",
+            "operators": [
+              "_eq",
+              "_neq",
+              "_gt",
+              "_gte",
+              "_lt",
+              "_lte",
+              "_in",
+              "_nin",
+              "_is_null",
+              "_like",
+              "_ilike"
+            ]
+          }
+        ],
+        "relationships": []
+      },
+      "row_policy": {
+        "kind": "unrestricted"
+      },
+      "record_revisions": false,
+      "tombstones": false
+    }
+  ],
+  "roots": [
+    {
+      "id": "query:todos",
+      "operation": "query",
+      "name": "todos",
+      "kind": "list",
+      "model": "Todo",
+      "arguments": [
+        {
+          "name": "where",
+          "kind": "filter",
+          "type_name": "todos_bool_exp",
+          "nullable": true,
+          "list": false
+        },
+        {
+          "name": "order_by",
+          "kind": "order",
+          "type_name": "todos_order_by",
+          "nullable": true,
+          "list": true
+        },
+        {
+          "name": "limit",
+          "kind": "limit",
+          "type_name": "Int",
+          "nullable": true,
+          "list": false,
+          "codec": "int32"
+        },
+        {
+          "name": "offset",
+          "kind": "offset",
+          "type_name": "Int",
+          "nullable": true,
+          "list": false,
+          "codec": "int32"
+        }
+      ],
+      "filter": {
+        "fields": [
+          {
+            "name": "id",
+            "operators": [
+              "_eq",
+              "_neq",
+              "_gt",
+              "_gte",
+              "_lt",
+              "_lte",
+              "_in",
+              "_nin",
+              "_is_null"
+            ]
+          },
+          {
+            "name": "title",
+            "operators": [
+              "_eq",
+              "_neq",
+              "_gt",
+              "_gte",
+              "_lt",
+              "_lte",
+              "_in",
+              "_nin",
+              "_is_null",
+              "_like",
+              "_ilike"
+            ]
+          }
+        ],
+        "relationships": [],
+        "row_policy": {
+          "kind": "unrestricted"
+        }
+      },
+      "order": {
+        "fields": [
+          "id",
+          "title"
+        ],
+        "values": [
+          "asc",
+          "asc_nulls_first",
+          "asc_nulls_last",
+          "desc",
+          "desc_nulls_first",
+          "desc_nulls_last"
+        ]
+      },
+      "pagination": {
+        "kind": "offset",
+        "default_limit": 100,
+        "max_limit": 1000,
+        "coverage": "window"
+      },
+      "aggregate": null,
+      "dependencies": [
+        "todos"
+      ],
+      "live": false
+    }
+  ],
+  "commands": [],
+  "protocol_operations": {
+    "version": 1,
+    "command_status": null
+  },
+  "projectors": []
+}"#;
+
+const TODOS_QUERY: &str = r#"query Todos {
+  todos {
+    id
+    title
+  }
+}
+"#;
+
+const LOAD_TODOS_QUERY: &str = r#"query Todos @load {
+  todos {
+    id
+    title
+  }
+}
+"#;
+
+const SECOND_TODOS_QUERY: &str = r#"query SecondTodos {
+  todos {
+    title
+  }
+}
+"#;
+
+fn project_dir(name: &str) -> PathBuf {
+    let project = Path::new(env!("CARGO_TARGET_TMPDIR")).join(name);
+    let _ = fs::remove_dir_all(&project);
+    fs::create_dir_all(&project).expect("create disposable client project");
+    fs::write(project.join("client-manifest.json"), ROLE_MANIFEST).expect("write client manifest");
+    project
+}
+
+fn write_document(project: &Path, relative: &str, source: &str) {
+    let path = project.join(relative);
+    fs::create_dir_all(path.parent().expect("document has a parent"))
+        .expect("create GraphQL document parent");
+    fs::write(path, source).expect("write GraphQL document");
+}
+
+fn dctl_client(project: &Path, args: &[&str]) -> Output {
+    Command::new(env!("CARGO_BIN_EXE_dctl"))
+        .arg("client")
+        .args(args)
+        .current_dir(project)
+        .output()
+        .expect("dctl should run")
+}
+
+fn generate(project: &Path, documents: &str, extra: &[&str]) -> Output {
+    let mut args = vec![
+        "--manifest",
+        "client-manifest.json",
+        "--role",
+        "user",
+        "--documents",
+        documents,
+        "--out",
+        "generated",
+    ];
+    args.extend_from_slice(extra);
+    dctl_client(project, &args)
+}
+
+fn assert_success(output: &Output, context: &str) {
+    assert!(
+        output.status.success(),
+        "{context} failed:\n{}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+}
+
+fn assert_failure_contains(output: &Output, expected: &str, context: &str) {
+    assert!(!output.status.success(), "{context} unexpectedly succeeded");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains(expected),
+        "{context} stderr did not contain {expected:?}:\n{stderr}"
+    );
+}
+
+fn snapshot_tree(root: &Path) -> BTreeMap<String, Vec<u8>> {
+    fn visit(root: &Path, directory: &Path, snapshot: &mut BTreeMap<String, Vec<u8>>) {
+        let mut entries = fs::read_dir(directory)
+            .unwrap_or_else(|error| panic!("read {}: {error}", directory.display()))
+            .map(|entry| entry.expect("read directory entry"))
+            .collect::<Vec<_>>();
+        entries.sort_by_key(|entry| entry.file_name());
+        for entry in entries {
+            let path = entry.path();
+            let file_type = entry.file_type().expect("read entry type");
+            if file_type.is_dir() {
+                visit(root, &path, snapshot);
+            } else if file_type.is_file() {
+                let relative = path
+                    .strip_prefix(root)
+                    .expect("snapshot path remains below root")
+                    .to_string_lossy()
+                    .replace('\\', "/");
+                snapshot.insert(relative, fs::read(&path).expect("read snapshot file"));
+            } else {
+                panic!("unexpected entry in test snapshot: {}", path.display());
+            }
+        }
+    }
+
+    let mut snapshot = BTreeMap::new();
+    visit(root, root, &mut snapshot);
+    snapshot
+}
+
+#[test]
+fn generate_then_check_accepts_the_exact_artifact_tree() {
+    let project = project_dir("client-generate-check");
+    write_document(&project, "queries/todos.graphql", TODOS_QUERY);
+
+    let generated = generate(&project, "queries/*.graphql", &[]);
+    assert_success(&generated, "initial client generation");
+    let generated_stdout = String::from_utf8_lossy(&generated.stdout);
+    assert!(
+        generated_stdout.contains("Generated") && generated_stdout.contains("generated"),
+        "stdout: {generated_stdout}"
+    );
+    for expected in [
+        "commands.ts",
+        "index.ts",
+        "manifest.json",
+        "operations/todos.ts",
+        "protocol.ts",
+        "routes.ts",
+        "sveltekit.ts",
+    ] {
+        assert!(
+            project.join("generated").join(expected).is_file(),
+            "missing generated artifact {expected}"
+        );
+    }
+    let operation = fs::read_to_string(project.join("generated/operations/todos.ts"))
+        .expect("read generated operation");
+    assert!(
+        operation.contains("\"order\": {")
+            && operation.contains("\"tieBreakers\": [")
+            && operation.contains("\"field\": \"id\"")
+            && operation.contains("\"filter\": {")
+            && operation.contains("\"pagination\": {")
+            && operation.contains("\"kind\": \"offset\"")
+            && operation.contains("\"defaultLimit\": 100")
+            && operation.contains("\"maxLimit\": 1000"),
+        "list operations must encode filter, stable identity ordering, and bounded offset-window maintenance"
+    );
+    let commands =
+        fs::read_to_string(project.join("generated/commands.ts")).expect("read command bindings");
+    assert!(
+        commands.contains("export const COMMAND_ARTIFACTS = [] as const;")
+            && commands.contains("export const COMMANDS = {\n\n} as const;"),
+        "a query-only surface must retain inspectable empty inventories"
+    );
+    assert!(
+        !commands.contains("@hops-ops/distributed/replica")
+            && !commands.contains("createCommands")
+            && !commands.contains("COMMAND_STATUS"),
+        "a query-only surface must not emit unusable command runtime imports or factories"
+    );
+    let sveltekit = fs::read_to_string(project.join("generated/sveltekit.ts"))
+        .expect("read SvelteKit bindings");
+    assert!(
+        sveltekit.contains(
+            "export const Todos = defineDistributedSvelteKitOperation(DistributedOperation_0);"
+        ) && sveltekit.contains(
+            "export type GeneratedCommands = Readonly<Record<never, never>>;"
+        ),
+        "the virtual-module target must expose an SSR-safe generated operation wrapper: {sveltekit}"
+    );
+    assert!(
+        !sveltekit.contains("createGeneratedCommands"),
+        "query-only surfaces must not invent a command runtime: {sveltekit}"
+    );
+
+    let checked = generate(&project, "queries/*.graphql", &["--check"]);
+    assert_success(&checked, "client artifact check");
+    assert!(
+        String::from_utf8_lossy(&checked.stdout)
+            .contains("Distributed client artifacts are current"),
+        "stdout: {}",
+        String::from_utf8_lossy(&checked.stdout)
+    );
+}
+
+#[test]
+fn exact_document_path_with_glob_metacharacters_generates_and_checks_portably() {
+    let project = project_dir("client-exact-glob-metacharacters");
+    let document_path = "src/routes/blob/[[gameId]]/+page.graphql";
+    write_document(&project, document_path, TODOS_QUERY);
+
+    let generated = generate(&project, document_path, &[]);
+    assert_success(&generated, "exact metacharacter-path generation");
+    let manifest: serde_json::Value = serde_json::from_str(
+        &fs::read_to_string(project.join("generated/manifest.json"))
+            .expect("read generated manifest"),
+    )
+    .expect("parse generated manifest");
+    let source_paths = manifest["operations"]
+        .as_array()
+        .expect("manifest operations")
+        .iter()
+        .map(|operation| {
+            operation["source_path"]
+                .as_str()
+                .expect("operation source path")
+        })
+        .collect::<Vec<_>>();
+    assert_eq!(source_paths, vec![document_path]);
+
+    let checked = generate(&project, document_path, &["--check"]);
+    assert_success(&checked, "exact metacharacter-path check");
+    assert!(
+        String::from_utf8_lossy(&checked.stdout)
+            .contains("Distributed client artifacts are current"),
+        "stdout: {}",
+        String::from_utf8_lossy(&checked.stdout)
+    );
+}
+
+#[test]
+fn check_reports_tampering_without_rewriting_any_artifact() {
+    let project = project_dir("client-check-tampered");
+    write_document(&project, "queries/todos.graphql", TODOS_QUERY);
+    assert_success(
+        &generate(&project, "queries/*.graphql", &[]),
+        "initial client generation",
+    );
+
+    let generated = project.join("generated");
+    fs::write(generated.join("index.ts"), "user-owned tamper\n")
+        .expect("tamper with generated artifact");
+    let before = snapshot_tree(&generated);
+
+    let checked = generate(&project, "queries/*.graphql", &["--check"]);
+    assert_failure_contains(&checked, "changed index.ts", "tampered client check");
+    assert_eq!(
+        snapshot_tree(&generated),
+        before,
+        "--check must not repair or otherwise write the generated tree"
+    );
+    assert_eq!(
+        fs::read_to_string(generated.join("index.ts")).unwrap(),
+        "user-owned tamper\n"
+    );
+}
+
+#[test]
+fn selected_role_manifest_rejects_role_name_and_application_kind_mismatches() {
+    let project = project_dir("client-surface-mismatch");
+    write_document(&project, "queries/todos.graphql", TODOS_QUERY);
+
+    let wrong_role = dctl_client(
+        &project,
+        &[
+            "--manifest",
+            "client-manifest.json",
+            "--role",
+            "admin",
+            "--documents",
+            "queries/*.graphql",
+            "--out",
+            "generated",
+        ],
+    );
+    assert_failure_contains(
+        &wrong_role,
+        "client.manifest.surface_mismatch",
+        "role-name mismatch",
+    );
+
+    let wrong_kind = dctl_client(
+        &project,
+        &[
+            "--manifest",
+            "client-manifest.json",
+            "--surface",
+            "web",
+            "--documents",
+            "queries/*.graphql",
+            "--out",
+            "generated",
+        ],
+    );
+    assert_failure_contains(
+        &wrong_kind,
+        "client.manifest.surface_mismatch",
+        "role/application selector mismatch",
+    );
+    assert!(
+        !project.join("generated").exists(),
+        "surface mismatch must fail before writing output"
+    );
+}
+
+#[test]
+fn unmatched_document_glob_fails_before_creating_output() {
+    let project = project_dir("client-unmatched-glob");
+
+    let output = generate(&project, "queries/**/*.graphql", &[]);
+    assert_failure_contains(&output, "matched no files", "unmatched document glob");
+    assert!(
+        !project.join("generated").exists(),
+        "an unmatched source glob must not create output"
+    );
+}
+
+#[test]
+fn explicit_route_is_the_load_fallback_outside_route_conventions() {
+    let project = project_dir("client-explicit-route");
+    write_document(&project, "queries/todos.graphql", LOAD_TODOS_QUERY);
+
+    let missing_route = generate(&project, "queries/*.graphql", &[]);
+    assert_failure_contains(
+        &missing_route,
+        "client.route.registration_required",
+        "@load without route ownership",
+    );
+    assert!(
+        !project.join("generated").exists(),
+        "failed route discovery must not create output"
+    );
+
+    let generated = generate(&project, "queries/*.graphql", &["--route", "Todos=/todos"]);
+    assert_success(&generated, "client generation with explicit route");
+    let routes =
+        fs::read_to_string(project.join("generated/routes.ts")).expect("read generated route plan");
+    assert!(
+        routes.contains("\"route\": \"/todos\""),
+        "routes.ts: {routes}"
+    );
+    assert!(
+        routes.contains("\"discovery\": \"explicit\""),
+        "routes.ts: {routes}"
+    );
+    assert!(
+        routes.contains("DISTRIBUTED_ROUTE_OPERATIONS")
+            && routes.contains("artifact: Operation_Todos"),
+        "routes.ts must statically bind discovered ownership to its artifact: {routes}"
+    );
+}
+
+#[test]
+fn check_rejects_an_unexpected_file_without_touching_the_tree() {
+    let project = project_dir("client-check-unexpected");
+    write_document(&project, "queries/todos.graphql", TODOS_QUERY);
+    assert_success(
+        &generate(&project, "queries/*.graphql", &[]),
+        "initial client generation",
+    );
+
+    let generated = project.join("generated");
+    fs::write(generated.join("stale.ts"), "keep me\n").expect("write unexpected artifact");
+    let before = snapshot_tree(&generated);
+
+    let checked = generate(&project, "queries/*.graphql", &["--check"]);
+    assert_failure_contains(&checked, "unexpected stale.ts", "unexpected-file check");
+    assert_eq!(
+        snapshot_tree(&generated),
+        before,
+        "--check must remain read-only when the file set drifts"
+    );
+
+    let regenerated = generate(&project, "queries/*.graphql", &[]);
+    assert_failure_contains(
+        &regenerated,
+        "files without current or previous compiler ownership",
+        "unexpected-file regeneration",
+    );
+    assert_eq!(
+        snapshot_tree(&generated),
+        before,
+        "normal generation must also fail before mutating an unowned file set"
+    );
+}
+
+#[test]
+fn regeneration_removes_only_modules_owned_by_previous_provenance() {
+    let project = project_dir("client-regenerate-converges");
+    write_document(&project, "queries/todos.graphql", TODOS_QUERY);
+    write_document(&project, "queries/second.graphql", SECOND_TODOS_QUERY);
+    assert_success(
+        &generate(&project, "queries/*.graphql", &[]),
+        "initial two-operation generation",
+    );
+
+    let generated = project.join("generated");
+    let stale_module = generated.join("operations/second-todos.ts");
+    assert!(
+        stale_module.is_file(),
+        "second operation should be generated"
+    );
+    fs::remove_file(project.join("queries/second.graphql")).expect("remove obsolete source");
+
+    assert_success(
+        &generate(&project, "queries/*.graphql", &[]),
+        "regeneration after deleting an operation",
+    );
+    assert!(
+        !stale_module.exists(),
+        "a module proven by previous provenance must be removed when its operation disappears"
+    );
+    assert_success(
+        &generate(&project, "queries/*.graphql", &["--check"]),
+        "converged generation check",
+    );
+}
+
+#[test]
+fn regeneration_refuses_to_delete_a_stale_module_without_ownership_marker() {
+    let project = project_dir("client-regenerate-marker");
+    write_document(&project, "queries/todos.graphql", TODOS_QUERY);
+    write_document(&project, "queries/second.graphql", SECOND_TODOS_QUERY);
+    assert_success(
+        &generate(&project, "queries/*.graphql", &[]),
+        "initial two-operation generation",
+    );
+
+    let stale_module = project.join("generated/operations/second-todos.ts");
+    fs::write(&stale_module, "user-owned contents\n").expect("replace ownership marker");
+    fs::remove_file(project.join("queries/second.graphql")).expect("remove obsolete source");
+    let before = snapshot_tree(&project.join("generated"));
+
+    let regenerated = generate(&project, "queries/*.graphql", &[]);
+    assert_failure_contains(
+        &regenerated,
+        "compiler ownership marker is missing",
+        "unowned stale-module regeneration",
+    );
+    assert_eq!(
+        snapshot_tree(&project.join("generated")),
+        before,
+        "failed ownership proof must not mutate generated output"
+    );
+}
+
+#[cfg(unix)]
+#[test]
+fn generation_rejects_symlinked_output_components_without_writing_through_them() {
+    use std::os::unix::fs::symlink;
+
+    let project = project_dir("client-generate-symlink");
+    write_document(&project, "queries/todos.graphql", TODOS_QUERY);
+    let outside = project.join("outside");
+    fs::create_dir_all(&outside).expect("create outside target");
+    fs::create_dir_all(project.join("generated")).expect("create generated root");
+    symlink(&outside, project.join("generated/operations")).expect("link operation directory");
+
+    let generated = generate(&project, "queries/*.graphql", &[]);
+    assert_failure_contains(
+        &generated,
+        "contains a symlink or incompatible entry",
+        "symlinked output generation",
+    );
+    assert_eq!(
+        snapshot_tree(&outside),
+        BTreeMap::new(),
+        "generation must not follow an output-directory symlink"
+    );
+}
+
+#[test]
+fn generation_rejects_an_unproven_old_surface_chunk_without_provenance() {
+    let project = project_dir("client-generate-unproven-surface");
+    write_document(&project, "queries/todos.graphql", TODOS_QUERY);
+    let generated = project.join("generated");
+    fs::create_dir_all(generated.join("operations")).expect("create old output tree");
+    fs::write(
+        generated.join("operations/admin-only.ts"),
+        "/** GENERATED by dctl client. Do not edit. */\nexport const secret = true;\n",
+    )
+    .expect("write unproven elevated chunk");
+    let before = snapshot_tree(&generated);
+
+    let output = generate(&project, "queries/*.graphql", &[]);
+    assert_failure_contains(
+        &output,
+        "files without current or previous compiler ownership",
+        "unproven prior-surface output",
+    );
+    assert_eq!(
+        snapshot_tree(&generated),
+        before,
+        "missing provenance must never authorize deletion or partial overwrite"
+    );
+}
diff --git a/distributed_cli/tests/cli_manifest.rs b/distributed_cli/tests/cli_manifest.rs
index 470fbc7c..aa2a6416 100644
--- a/distributed_cli/tests/cli_manifest.rs
+++ b/distributed_cli/tests/cli_manifest.rs
@@ -44,6 +44,81 @@ fn describe_emits_manifest_json() {
     assert!(json.contains("\"orders\""), "json: {json}");
 }
 
+#[test]
+#[ignore = "compiles the fixture via the manifest harness; run in the integration job"]
+fn client_manifest_uses_service_surface_export() {
+    let json = dctl(&["client-manifest"]);
+    let manifest: serde_json::Value = serde_json::from_str(&json).unwrap();
+    assert_eq!(manifest["manifest_version"], 1);
+    assert_eq!(manifest["protocol_version"], 1);
+    assert_eq!(manifest["service_id"], "orders");
+    assert_eq!(manifest["surface"]["kind"], "role");
+    assert_eq!(manifest["surface"]["name"], "user");
+    assert_eq!(
+        manifest["schema_fingerprint"],
+        "sha256:31a54d18b0104283e3ec26cb7da37bfb2c31a3d8e37e96e8297e83059cf56aa4"
+    );
+    assert_eq!(
+        manifest["protocol_fingerprint"],
+        "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273"
+    );
+    assert_eq!(manifest["models"][0]["id"], "OrderView");
+    assert_eq!(manifest["models"][0]["record_revisions"], true);
+    assert_eq!(manifest["models"][0]["tombstones"], true);
+    assert_eq!(manifest["capabilities"]["record_revisions"], true);
+    assert_eq!(manifest["capabilities"]["tombstones"], true);
+    assert_eq!(manifest["capabilities"]["live_resume"], true);
+    assert_eq!(manifest["capabilities"]["query_fallback"], "revalidate");
+    assert_eq!(
+        manifest["commands"][0]["extensions"]["consistency"]["kind"],
+        "projected"
+    );
+    assert_eq!(
+        manifest["commands"][0]["extensions"]["direct_projection"]["topology"]["version"],
+        1
+    );
+    assert_eq!(
+        manifest["commands"][0]["extensions"]["direct_projection"]["topology"]["name"],
+        "project_orders"
+    );
+    assert_eq!(
+        manifest["commands"][0]["extensions"]["direct_projection"]["topology"]["digest"],
+        "sha256:32e51a5f5c3b7a83d27366f8dc889b87045e65f027f7b598421a6db765efe8a4"
+    );
+    assert_eq!(
+        manifest["commands"][0]["extensions"]["direct_projection"]["model"],
+        "OrderView"
+    );
+    assert_eq!(
+        manifest["commands"][0]["extensions"]["direct_projection"]["change_epoch"],
+        "orders-v1"
+    );
+    assert!(manifest["commands"][0]["extensions"]["direct_projection"]
+        .get("partition")
+        .is_none());
+    assert!(manifest["protocol_operations"]["command_status"].is_object());
+}
+
+#[test]
+#[ignore = "compiles the fixture via the manifest harness; run in the integration job"]
+fn emitted_client_manifest_is_accepted_by_client_compiler() {
+    let json = dctl(&["client-manifest"]);
+    let manifest: serde_json::Value = serde_json::from_str(&json).unwrap();
+    let project = distributed_cli::compile_client(distributed_cli::ClientCompileInput::new(
+        manifest,
+        distributed_cli::ClientSurfaceSelector::role("user"),
+        vec![distributed_cli::ClientDocument::new(
+            "src/routes/orders/+page.graphql",
+            "query Orders { orders { order_id status } }",
+        )],
+    ))
+    .expect("the compiler must consume the exact manifest emitted by the server crate");
+
+    assert_eq!(project.operations.len(), 1);
+    assert_eq!(project.operations[0].name, "Orders");
+    assert_eq!(project.schema_fingerprint.len(), 71);
+}
+
 #[test]
 #[ignore = "compiles the fixture via the manifest harness; run in the integration job"]
 fn schema_renders_postgres_sql() {
diff --git a/distributed_cli/tests/cli_scaffold_compile.rs b/distributed_cli/tests/cli_scaffold_compile.rs
index 92f1909e..f5088d52 100644
--- a/distributed_cli/tests/cli_scaffold_compile.rs
+++ b/distributed_cli/tests/cli_scaffold_compile.rs
@@ -95,6 +95,16 @@ fn scaffolded_http_tracing_service_compiles() {
     cargo_check(&out_dir);
 }
 
+#[test]
+#[ignore = "compiles the scaffolded project via a nested cargo build; run in the integration job"]
+fn scaffolded_query_api_service_compiles() {
+    let out_dir = scaffold(
+        "compile-query-api-sqlite",
+        &["--query-api", "--store", "sqlite", "--model", "order"],
+    );
+    cargo_check(&out_dir);
+}
+
 #[test]
 #[ignore = "compiles the scaffolded project via a nested cargo build; run in the integration job"]
 fn scaffolded_knative_service_compiles() {
diff --git a/distributed_cli/tests/cli_skills_init.rs b/distributed_cli/tests/cli_skills_init.rs
index 229c6b76..8c7305d0 100644
--- a/distributed_cli/tests/cli_skills_init.rs
+++ b/distributed_cli/tests/cli_skills_init.rs
@@ -78,7 +78,7 @@ fn init_bootstraps_a_fresh_project_and_reruns_are_noops() {
     let agents_md = read(&dir, "AGENTS.md");
     assert!(agents_md.contains(BEGIN) && agents_md.contains(END));
     assert!(stdout.contains("created .distributed/skills/distributed-ci/SKILL.md"));
-    assert!(stdout.contains("Initialized 3 skills at .distributed/skills (wired: claude, agents)"));
+    assert!(stdout.contains("Initialized 4 skills at .distributed/skills (wired: claude, agents)"));
 
     // No strays at the harness skill roots (only skill folders).
     for root in [".agents/skills", ".claude/skills"] {
diff --git a/distributed_cli/tests/fixtures/generated-commands-consumer.ts b/distributed_cli/tests/fixtures/generated-commands-consumer.ts
new file mode 100644
index 00000000..606649da
--- /dev/null
+++ b/distributed_cli/tests/fixtures/generated-commands-consumer.ts
@@ -0,0 +1,34 @@
+import {
+	createCommands,
+	type GeneratedCommands,
+	type GeneratedCommandRuntime
+} from './generated-commands.js';
+import type {
+	DistributedReplica,
+	ReplicaCommandTransport
+} from '@hops-ops/distributed/replica';
+
+declare const replica: DistributedReplica;
+declare const transport: ReplicaCommandTransport;
+
+const runtime: GeneratedCommandRuntime = createCommands(replica, transport);
+const commands: GeneratedCommands = runtime.commands;
+
+commands.todo.import({ source: 'fixture' });
+commands.todo.ping();
+commands.todo.project({ id: 'todo-1', tenantId: 'tenant-1' }).then(
+	(receipt) => {
+		const title: string | null = receipt.result.title;
+		return title;
+	}
+);
+
+runtime.observeResult({});
+runtime.dispose();
+
+// @ts-expect-error Generated object inputs remain exact and required.
+commands.todo.project({ id: 'todo-1' });
+// @ts-expect-error A no-input command accepts options, not domain input.
+commands.todo.ping({ id: 'todo-1' });
+// @ts-expect-error Descriptor inventory is not presented as callable commands.
+createCommands(replica, transport).commands.todo.project.artifact;
diff --git a/distributed_cli/tests/fixtures/generated-commands.ts b/distributed_cli/tests/fixtures/generated-commands.ts
new file mode 100644
index 00000000..d027ed02
--- /dev/null
+++ b/distributed_cli/tests/fixtures/generated-commands.ts
@@ -0,0 +1,370 @@
+/** GENERATED by dctl client. Do not edit. */
+
+import {
+  createReplicaCommandRuntime,
+  prepareReplicaCommand
+} from '@hops-ops/distributed/replica';
+
+import type {
+  DistributedReplica,
+  PrepareReplicaCommandOptions,
+  ReplicaCommandArtifact,
+  ReplicaCommandRuntime,
+  ReplicaCommandRuntimeOptions,
+  ReplicaCommandTransport,
+  ReplicaPreparedCommand,
+  ReplicaValue
+} from '@hops-ops/distributed/replica';
+
+import { COMMAND_STATUS } from './protocol.js';
+
+export type Command_importTodos_Input = {
+  readonly "source": ReplicaValue;
+};
+
+export type Command_importTodos_Output = {
+  readonly "result": ReplicaValue;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_importTodos: ReplicaCommandArtifact<Command_importTodos_Input, Command_importTodos_Output> = {
+  "consistency": "accepted",
+  "document": "mutation Client_importTodos($commandId: ID!, $input: ImportTodosInput!) { importTodos(commandId: $commandId, input: $input) { result } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "json",
+          "itemNullable": false,
+          "list": false,
+          "name": "source",
+          "nullable": false,
+          "typeName": "JSON"
+        }
+      ],
+      "name": "ImportTodosInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "importTodos",
+  "name": "todo.import",
+  "operationHash": "sha256:e8e54238fd7618fa94e90ae60b1dfac8833943027d04e71be84cb03702f1cebf",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "json",
+          "itemNullable": false,
+          "list": false,
+          "name": "result",
+          "nullable": false,
+          "typeName": "JSON"
+        }
+      ],
+      "name": "ImportTodosPayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:e8e54238fd7618fa94e90ae60b1dfac8833943027d04e71be84cb03702f1cebf",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:e384dd6cdb8281665ceb58e3d51292e3d3c965972dfd2f70ebd3fbef89dd9c40",
+    "surface": {
+      "kind": "role",
+      "name": "user"
+    },
+    "trustedPresets": [],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todo_rows"
+    ],
+    "models": [
+      "Todo"
+    ],
+    "relationships": [],
+    "required": true,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_importTodos(
+  input: Command_importTodos_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_importTodos_Input, Command_importTodos_Output> {
+  return prepareReplicaCommand(Command_importTodos, input, options);
+}
+
+export type Command_pingTodos_Input = void;
+
+export type Command_pingTodos_Output = {
+  readonly "ok": boolean;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_pingTodos: ReplicaCommandArtifact<Command_pingTodos_Input, Command_pingTodos_Output> = {
+  "consistency": "accepted",
+  "document": "mutation Client_pingTodos($commandId: ID!) { pingTodos(commandId: $commandId) { ok } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [],
+    "version": 1
+  },
+  "input": {
+    "kind": "none"
+  },
+  "mutationField": "pingTodos",
+  "name": "todo.ping",
+  "operationHash": "sha256:3cb3c1e96331b4e98191cc725ab6b01c0e9b04cc7cc0f37f4fa0ef394fee9acf",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "ok",
+          "nullable": false,
+          "typeName": "Boolean"
+        }
+      ],
+      "name": "PingTodosPayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:3cb3c1e96331b4e98191cc725ab6b01c0e9b04cc7cc0f37f4fa0ef394fee9acf",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:e384dd6cdb8281665ceb58e3d51292e3d3c965972dfd2f70ebd3fbef89dd9c40",
+    "surface": {
+      "kind": "role",
+      "name": "user"
+    },
+    "trustedPresets": [],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todo_rows"
+    ],
+    "models": [
+      "Todo"
+    ],
+    "relationships": [],
+    "required": true,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_pingTodos(
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_pingTodos_Input, Command_pingTodos_Output> {
+  return prepareReplicaCommand(Command_pingTodos, undefined, options);
+}
+
+export type Command_projectTodo_Input = {
+  readonly "id": string;
+  readonly "tenantId": string;
+};
+
+export type Command_projectTodo_Output = {
+  readonly "completed": boolean;
+  readonly "id": string;
+  readonly "priority": number;
+  readonly "tenantId": string;
+  readonly "title": string | null;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_projectTodo: ReplicaCommandArtifact<Command_projectTodo_Input, Command_projectTodo_Output> = {
+  "consistency": "projected",
+  "directProjection": {
+    "changeEpoch": "todos-v1",
+    "identityFields": [
+      "tenantId",
+      "id"
+    ],
+    "model": "Todo",
+    "partition": {
+      "kind": "input",
+      "path": [
+        "tenantId"
+      ]
+    },
+    "topology": {
+      "digest": "sha256:b44a23c0c3e5bb3c7f72da0ec21789206f8880508d9cd60145a9a0793113490e",
+      "name": "todos",
+      "version": 1
+    }
+  },
+  "document": "mutation Client_projectTodo($commandId: ID!, $input: ProjectTodoInput!) { projectTodo(commandId: $commandId, input: $input) { completed id priority tenantId title } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "id",
+          "nullable": false,
+          "typeName": "ID"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "tenantId",
+          "nullable": false,
+          "typeName": "ID"
+        }
+      ],
+      "name": "ProjectTodoInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "projectTodo",
+  "name": "todo.project",
+  "operationHash": "sha256:f986d060555cdedfe94621914116306af704d8bb90e75289722a3b7119211d32",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "completed",
+          "nullable": false,
+          "typeName": "Boolean"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "id",
+          "nullable": false,
+          "typeName": "ID"
+        },
+        {
+          "codec": "int32",
+          "itemNullable": false,
+          "list": false,
+          "name": "priority",
+          "nullable": false,
+          "typeName": "Int"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "tenantId",
+          "nullable": false,
+          "typeName": "ID"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "title",
+          "nullable": true,
+          "typeName": "String"
+        }
+      ],
+      "name": "todo"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:f986d060555cdedfe94621914116306af704d8bb90e75289722a3b7119211d32",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:e384dd6cdb8281665ceb58e3d51292e3d3c965972dfd2f70ebd3fbef89dd9c40",
+    "surface": {
+      "kind": "role",
+      "name": "user"
+    },
+    "trustedPresets": [],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todo_rows"
+    ],
+    "models": [
+      "Todo"
+    ],
+    "relationships": [],
+    "required": true,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_projectTodo(
+  input: Command_projectTodo_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_projectTodo_Input, Command_projectTodo_Output> {
+  return prepareReplicaCommand(Command_projectTodo, input, options);
+}
+
+export const COMMAND_ARTIFACTS = [Command_importTodos, Command_pingTodos, Command_projectTodo] as const;
+
+/** Inspectable command inventory consumed by the generated binding factory. */
+export const COMMANDS = {
+  "todo.import": Command_importTodos,
+  "todo.ping": Command_pingTodos,
+  "todo.project": Command_projectTodo
+} as const;
+
+/** Runtime owning the generated callable command surface and its causal lifecycle. */
+export type GeneratedCommandRuntime = ReplicaCommandRuntime<typeof COMMANDS>;
+
+/** Callable `commands.x(input)` surface exposed by GeneratedCommandRuntime. */
+export type GeneratedCommands = GeneratedCommandRuntime['commands'];
+
+/** Runtime options excluding compiler-owned protocol authority. */
+export type GeneratedCommandRuntimeOptions = Omit<ReplicaCommandRuntimeOptions, 'status'>;
+
+/**
+ * Bind this generated command inventory to a replica and transport.
+ * Keep the returned runtime when `observeResult` or `dispose` is needed.
+ */
+export function createCommands(
+  replica: DistributedReplica,
+  transport: ReplicaCommandTransport,
+  options?: GeneratedCommandRuntimeOptions
+): GeneratedCommandRuntime {
+  return createReplicaCommandRuntime(replica, transport, COMMANDS, {
+    ...options,
+    status: COMMAND_STATUS
+  });
+}
+
+/** Projector topology used by command confirmation/effect runtimes. */
+export const PROJECTOR_ARTIFACTS = [
+  {
+    "version": 1,
+    "name": "todos",
+    "facts": [],
+    "models": [
+      "Todo"
+    ],
+    "dependencies": [
+      "todo_rows"
+    ],
+    "causal_confirmation": false
+  }
+] as const;
+
+export type GeneratedCommandArtifact = (typeof COMMAND_ARTIFACTS)[number];
diff --git a/distributed_cli/tests/fixtures/generated-operation.ts b/distributed_cli/tests/fixtures/generated-operation.ts
new file mode 100644
index 00000000..ea973836
--- /dev/null
+++ b/distributed_cli/tests/fixtures/generated-operation.ts
@@ -0,0 +1,837 @@
+/** GENERATED by dctl client. Do not edit. */
+import type { ReplicaOperationArtifact, ReplicaValue } from '@hops-ops/distributed/replica';
+
+type Operation_ScalarInputs_Input_todo_bool_exp = {
+  readonly "_and"?: Operation_ScalarInputs_Input_todo_bool_exp | readonly Operation_ScalarInputs_Input_todo_bool_exp[] | null;
+  readonly "_or"?: Operation_ScalarInputs_Input_todo_bool_exp | readonly Operation_ScalarInputs_Input_todo_bool_exp[] | null;
+  readonly "_not"?: Operation_ScalarInputs_Input_todo_bool_exp | null;
+  readonly "blob"?: {
+    readonly "_eq"?: string | null;
+  } | null;
+  readonly "completed"?: {
+    readonly "_eq"?: boolean | null;
+  } | null;
+  readonly "id"?: {
+    readonly "_eq"?: string | number | null;
+  } | null;
+  readonly "payload"?: {
+    readonly "_eq"?: ReplicaValue | null;
+  } | null;
+  readonly "priority"?: {
+    readonly "_eq"?: number | null;
+    readonly "_in"?: number | readonly number[];
+    readonly "_nin"?: number | readonly number[];
+  } | null;
+  readonly "sequence"?: {
+    readonly "_eq"?: number | null;
+    readonly "_in"?: number | readonly number[];
+  } | null;
+  readonly "tenantId"?: {
+    readonly "_eq"?: string | number | null;
+  } | null;
+  readonly "title"?: {
+    readonly "_eq"?: string | null;
+  } | null;
+  readonly "updatedAt"?: {
+    readonly "_eq"?: string | null;
+  } | null;
+  readonly "owner"?: Operation_ScalarInputs_Input_todo_bool_exp | null;
+};
+
+type Operation_ScalarInputs_Input_todo_order_by_Direction = "asc" | "asc_nulls_first" | "asc_nulls_last" | "desc" | "desc_nulls_first" | "desc_nulls_last";
+type Operation_ScalarInputs_Input_todo_order_by =
+  | {
+      readonly "blob": Operation_ScalarInputs_Input_todo_order_by_Direction;
+      readonly "completed"?: never;
+      readonly "id"?: never;
+      readonly "payload"?: never;
+      readonly "priority"?: never;
+      readonly "sequence"?: never;
+      readonly "tenantId"?: never;
+      readonly "title"?: never;
+      readonly "updatedAt"?: never;
+    }
+  | {
+      readonly "blob"?: never;
+      readonly "completed": Operation_ScalarInputs_Input_todo_order_by_Direction;
+      readonly "id"?: never;
+      readonly "payload"?: never;
+      readonly "priority"?: never;
+      readonly "sequence"?: never;
+      readonly "tenantId"?: never;
+      readonly "title"?: never;
+      readonly "updatedAt"?: never;
+    }
+  | {
+      readonly "blob"?: never;
+      readonly "completed"?: never;
+      readonly "id": Operation_ScalarInputs_Input_todo_order_by_Direction;
+      readonly "payload"?: never;
+      readonly "priority"?: never;
+      readonly "sequence"?: never;
+      readonly "tenantId"?: never;
+      readonly "title"?: never;
+      readonly "updatedAt"?: never;
+    }
+  | {
+      readonly "blob"?: never;
+      readonly "completed"?: never;
+      readonly "id"?: never;
+      readonly "payload": Operation_ScalarInputs_Input_todo_order_by_Direction;
+      readonly "priority"?: never;
+      readonly "sequence"?: never;
+      readonly "tenantId"?: never;
+      readonly "title"?: never;
+      readonly "updatedAt"?: never;
+    }
+  | {
+      readonly "blob"?: never;
+      readonly "completed"?: never;
+      readonly "id"?: never;
+      readonly "payload"?: never;
+      readonly "priority": Operation_ScalarInputs_Input_todo_order_by_Direction;
+      readonly "sequence"?: never;
+      readonly "tenantId"?: never;
+      readonly "title"?: never;
+      readonly "updatedAt"?: never;
+    }
+  | {
+      readonly "blob"?: never;
+      readonly "completed"?: never;
+      readonly "id"?: never;
+      readonly "payload"?: never;
+      readonly "priority"?: never;
+      readonly "sequence": Operation_ScalarInputs_Input_todo_order_by_Direction;
+      readonly "tenantId"?: never;
+      readonly "title"?: never;
+      readonly "updatedAt"?: never;
+    }
+  | {
+      readonly "blob"?: never;
+      readonly "completed"?: never;
+      readonly "id"?: never;
+      readonly "payload"?: never;
+      readonly "priority"?: never;
+      readonly "sequence"?: never;
+      readonly "tenantId": Operation_ScalarInputs_Input_todo_order_by_Direction;
+      readonly "title"?: never;
+      readonly "updatedAt"?: never;
+    }
+  | {
+      readonly "blob"?: never;
+      readonly "completed"?: never;
+      readonly "id"?: never;
+      readonly "payload"?: never;
+      readonly "priority"?: never;
+      readonly "sequence"?: never;
+      readonly "tenantId"?: never;
+      readonly "title": Operation_ScalarInputs_Input_todo_order_by_Direction;
+      readonly "updatedAt"?: never;
+    }
+  | {
+      readonly "blob"?: never;
+      readonly "completed"?: never;
+      readonly "id"?: never;
+      readonly "payload"?: never;
+      readonly "priority"?: never;
+      readonly "sequence"?: never;
+      readonly "tenantId"?: never;
+      readonly "title"?: never;
+      readonly "updatedAt": Operation_ScalarInputs_Input_todo_order_by_Direction;
+    };
+
+export type Operation_ScalarInputs_Variables = {
+  readonly "big": number;
+  readonly "bytes"?: string | null;
+  readonly "id": string | number;
+  readonly "json"?: ReplicaValue | null;
+  readonly "order"?: Operation_ScalarInputs_Input_todo_order_by | readonly Operation_ScalarInputs_Input_todo_order_by[] | null;
+  readonly "timestamp"?: string | null;
+  readonly "where": Operation_ScalarInputs_Input_todo_bool_exp;
+};
+
+export type Operation_ScalarInputs_Data = {
+  readonly "todos": readonly {
+    readonly "id": string;
+  }[];
+};
+
+/** Exact canonical query bytes sent to the server. */
+export const Operation_ScalarInputsDocument = "query ScalarInputs($big: BigInt!, $bytes: Bytea, $id: ID!, $json: JSON, $order: [todo_order_by!], $timestamp: Timestamptz, $where: todo_bool_exp!) {\n  todos(order_by: $order, where: {_and: [$where, {blob: {_eq: $bytes}, id: {_eq: $id}, payload: {_eq: $json}, sequence: {_eq: $big}, updatedAt: {_eq: $timestamp}}]}) {\n    id\n    _distributed_tenantId: tenantId\n    _distributed_typename: __typename\n    _distributed_blob: blob\n    _distributed_completed: completed\n    _distributed_payload: payload\n    _distributed_priority: priority\n    _distributed_sequence: sequence\n    _distributed_title: title\n    _distributed_updatedAt: updatedAt\n  }\n}\n";
+
+/** Typed normalized-replica operation descriptor. */
+export const Operation_ScalarInputs: ReplicaOperationArtifact<Operation_ScalarInputs_Data, Operation_ScalarInputs_Variables> = {
+  "id": "sha256:d9f67afd74da3173c4a3b60d3dc832cc1288424a932a3784e2a8f9de3b379c13",
+  "document": "query ScalarInputs($big: BigInt!, $bytes: Bytea, $id: ID!, $json: JSON, $order: [todo_order_by!], $timestamp: Timestamptz, $where: todo_bool_exp!) {\n  todos(order_by: $order, where: {_and: [$where, {blob: {_eq: $bytes}, id: {_eq: $id}, payload: {_eq: $json}, sequence: {_eq: $big}, updatedAt: {_eq: $timestamp}}]}) {\n    id\n    _distributed_tenantId: tenantId\n    _distributed_typename: __typename\n    _distributed_blob: blob\n    _distributed_completed: completed\n    _distributed_payload: payload\n    _distributed_priority: priority\n    _distributed_sequence: sequence\n    _distributed_title: title\n    _distributed_updatedAt: updatedAt\n  }\n}\n",
+  "source": {
+    "path": "src/routes/todos/+page.graphql",
+    "line": 2,
+    "column": 3
+  },
+  "variableCodec": {
+    "version": 1,
+    "limits": {
+      "maxDepth": 8,
+      "maxBoolWidth": 256,
+      "maxInList": 1000
+    },
+    "variables": {
+      "big": {
+        "kind": "scalar",
+        "scalar": "BigInt",
+        "codec": "json_number_precision_limited",
+        "nullable": false
+      },
+      "bytes": {
+        "kind": "scalar",
+        "scalar": "Bytea",
+        "codec": "base64",
+        "nullable": true
+      },
+      "id": {
+        "kind": "scalar",
+        "scalar": "ID",
+        "codec": "string",
+        "nullable": false
+      },
+      "json": {
+        "kind": "scalar",
+        "scalar": "JSON",
+        "codec": "json",
+        "nullable": true
+      },
+      "order": {
+        "kind": "list",
+        "nullable": true,
+        "item": {
+          "kind": "input",
+          "name": "todo_order_by",
+          "nullable": false
+        }
+      },
+      "timestamp": {
+        "kind": "scalar",
+        "scalar": "Timestamptz",
+        "codec": "string_unvalidated_timestamp",
+        "nullable": true
+      },
+      "where": {
+        "kind": "input",
+        "name": "todo_bool_exp",
+        "nullable": false,
+        "filterBaseDepth": 1
+      }
+    },
+    "inputs": {
+      "todo_bool_exp": {
+        "kind": "filter",
+        "model": "Todo",
+        "fields": [
+          {
+            "field": "blob",
+            "scalar": "Bytea",
+            "codec": "base64",
+            "nullable": true,
+            "operators": [
+              "_eq"
+            ]
+          },
+          {
+            "field": "completed",
+            "scalar": "Boolean",
+            "codec": "boolean",
+            "nullable": false,
+            "operators": [
+              "_eq"
+            ]
+          },
+          {
+            "field": "id",
+            "scalar": "ID",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq"
+            ]
+          },
+          {
+            "field": "payload",
+            "scalar": "JSON",
+            "codec": "json",
+            "nullable": true,
+            "operators": [
+              "_eq"
+            ]
+          },
+          {
+            "field": "priority",
+            "scalar": "Int",
+            "codec": "int32",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_in",
+              "_nin"
+            ]
+          },
+          {
+            "field": "sequence",
+            "scalar": "BigInt",
+            "codec": "json_number_precision_limited",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_in"
+            ]
+          },
+          {
+            "field": "tenantId",
+            "scalar": "ID",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq"
+            ]
+          },
+          {
+            "field": "title",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": true,
+            "operators": [
+              "_eq"
+            ]
+          },
+          {
+            "field": "updatedAt",
+            "scalar": "Timestamptz",
+            "codec": "string_unvalidated_timestamp",
+            "nullable": true,
+            "operators": [
+              "_eq"
+            ]
+          }
+        ],
+        "relationships": [
+          {
+            "field": "owner",
+            "target": {
+              "kind": "input",
+              "name": "todo_bool_exp"
+            }
+          }
+        ]
+      },
+      "todo_order_by": {
+        "kind": "order",
+        "model": "Todo",
+        "fields": [
+          {
+            "field": "blob",
+            "scalar": "Bytea",
+            "codec": "base64",
+            "nullable": true
+          },
+          {
+            "field": "completed",
+            "scalar": "Boolean",
+            "codec": "boolean",
+            "nullable": false
+          },
+          {
+            "field": "id",
+            "scalar": "ID",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "payload",
+            "scalar": "JSON",
+            "codec": "json",
+            "nullable": true
+          },
+          {
+            "field": "priority",
+            "scalar": "Int",
+            "codec": "int32",
+            "nullable": false
+          },
+          {
+            "field": "sequence",
+            "scalar": "BigInt",
+            "codec": "json_number_precision_limited",
+            "nullable": false
+          },
+          {
+            "field": "tenantId",
+            "scalar": "ID",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "title",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": true
+          },
+          {
+            "field": "updatedAt",
+            "scalar": "Timestamptz",
+            "codec": "string_unvalidated_timestamp",
+            "nullable": true
+          }
+        ],
+        "values": [
+          "asc",
+          "asc_nulls_first",
+          "asc_nulls_last",
+          "desc",
+          "desc_nulls_first",
+          "desc_nulls_last"
+        ]
+      }
+    }
+  },
+  "roots": [
+    {
+      "responseKey": "todos",
+      "field": "todos",
+      "cardinality": "many",
+      "nullable": false,
+      "arguments": {
+        "order_by": {
+          "kind": "variable",
+          "name": "order"
+        },
+        "where": {
+          "kind": "object",
+          "fields": {
+            "_and": {
+              "kind": "list",
+              "items": [
+                {
+                  "kind": "variable",
+                  "name": "where"
+                },
+                {
+                  "kind": "object",
+                  "fields": {
+                    "blob": {
+                      "kind": "object",
+                      "fields": {
+                        "_eq": {
+                          "kind": "variable",
+                          "name": "bytes"
+                        }
+                      }
+                    },
+                    "id": {
+                      "kind": "object",
+                      "fields": {
+                        "_eq": {
+                          "kind": "variable",
+                          "name": "id"
+                        }
+                      }
+                    },
+                    "payload": {
+                      "kind": "object",
+                      "fields": {
+                        "_eq": {
+                          "kind": "variable",
+                          "name": "json"
+                        }
+                      }
+                    },
+                    "sequence": {
+                      "kind": "object",
+                      "fields": {
+                        "_eq": {
+                          "kind": "variable",
+                          "name": "big"
+                        }
+                      }
+                    },
+                    "updatedAt": {
+                      "kind": "object",
+                      "fields": {
+                        "_eq": {
+                          "kind": "variable",
+                          "name": "timestamp"
+                        }
+                      }
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        }
+      },
+      "dependencies": [
+        "todo_rows"
+      ],
+      "coverage": {
+        "kind": "offset",
+        "offsetArgument": "offset",
+        "limitArgument": "limit",
+        "defaultLimit": 25,
+        "maxLimit": 100
+      },
+      "filter": {
+        "input": {
+          "kind": "object",
+          "fields": {
+            "_and": {
+              "kind": "list",
+              "items": [
+                {
+                  "kind": "variable",
+                  "name": "where"
+                },
+                {
+                  "kind": "object",
+                  "fields": {
+                    "blob": {
+                      "kind": "object",
+                      "fields": {
+                        "_eq": {
+                          "kind": "variable",
+                          "name": "bytes"
+                        }
+                      }
+                    },
+                    "id": {
+                      "kind": "object",
+                      "fields": {
+                        "_eq": {
+                          "kind": "variable",
+                          "name": "id"
+                        }
+                      }
+                    },
+                    "payload": {
+                      "kind": "object",
+                      "fields": {
+                        "_eq": {
+                          "kind": "variable",
+                          "name": "json"
+                        }
+                      }
+                    },
+                    "sequence": {
+                      "kind": "object",
+                      "fields": {
+                        "_eq": {
+                          "kind": "variable",
+                          "name": "big"
+                        }
+                      }
+                    },
+                    "updatedAt": {
+                      "kind": "object",
+                      "fields": {
+                        "_eq": {
+                          "kind": "variable",
+                          "name": "timestamp"
+                        }
+                      }
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        },
+        "fields": [
+          {
+            "field": "blob",
+            "scalar": "Bytea",
+            "codec": "base64",
+            "nullable": true,
+            "operators": [
+              "_eq"
+            ]
+          },
+          {
+            "field": "completed",
+            "scalar": "Boolean",
+            "codec": "boolean",
+            "nullable": false,
+            "operators": [
+              "_eq"
+            ]
+          },
+          {
+            "field": "id",
+            "scalar": "ID",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq"
+            ]
+          },
+          {
+            "field": "payload",
+            "scalar": "JSON",
+            "codec": "json",
+            "nullable": true,
+            "operators": [
+              "_eq"
+            ]
+          },
+          {
+            "field": "priority",
+            "scalar": "Int",
+            "codec": "int32",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_in",
+              "_nin"
+            ]
+          },
+          {
+            "field": "sequence",
+            "scalar": "BigInt",
+            "codec": "json_number_precision_limited",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_in"
+            ]
+          },
+          {
+            "field": "tenantId",
+            "scalar": "ID",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq"
+            ]
+          },
+          {
+            "field": "title",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": true,
+            "operators": [
+              "_eq"
+            ]
+          },
+          {
+            "field": "updatedAt",
+            "scalar": "Timestamptz",
+            "codec": "string_unvalidated_timestamp",
+            "nullable": true,
+            "operators": [
+              "_eq"
+            ]
+          }
+        ],
+        "relationships": [
+          {
+            "field": "owner",
+            "targetModel": "Todo",
+            "kind": "belongs_to",
+            "keyMapping": {
+              "kind": "embedded"
+            },
+            "maintenance": "revalidate",
+            "dependencies": [
+              "todo_rows"
+            ]
+          }
+        ],
+        "rowPolicy": {
+          "kind": "unrestricted"
+        }
+      },
+      "order": {
+        "input": {
+          "kind": "variable",
+          "name": "order"
+        },
+        "fields": [
+          {
+            "field": "blob",
+            "scalar": "Bytea",
+            "codec": "base64",
+            "nullable": true
+          },
+          {
+            "field": "completed",
+            "scalar": "Boolean",
+            "codec": "boolean",
+            "nullable": false
+          },
+          {
+            "field": "id",
+            "scalar": "ID",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "payload",
+            "scalar": "JSON",
+            "codec": "json",
+            "nullable": true
+          },
+          {
+            "field": "priority",
+            "scalar": "Int",
+            "codec": "int32",
+            "nullable": false
+          },
+          {
+            "field": "sequence",
+            "scalar": "BigInt",
+            "codec": "json_number_precision_limited",
+            "nullable": false
+          },
+          {
+            "field": "tenantId",
+            "scalar": "ID",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "title",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": true
+          },
+          {
+            "field": "updatedAt",
+            "scalar": "Timestamptz",
+            "codec": "string_unvalidated_timestamp",
+            "nullable": true
+          }
+        ],
+        "tieBreakers": [
+          {
+            "field": "tenantId",
+            "scalar": "ID",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "id",
+            "scalar": "ID",
+            "codec": "string",
+            "nullable": false
+          }
+        ]
+      },
+      "pagination": {
+        "kind": "offset",
+        "insert": "local",
+        "delete": "local",
+        "reorder": "local",
+        "stableUpdate": "local"
+      },
+      "selection": {
+        "typename": "todo",
+        "storage": {
+          "kind": "normalized",
+          "model": "Todo",
+          "identityFields": [
+            "tenantId",
+            "id"
+          ]
+        },
+        "members": [
+          {
+            "kind": "scalar",
+            "responseKey": "id",
+            "field": "id",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_tenantId",
+            "field": "tenantId",
+            "codec": "string",
+            "nullable": false,
+            "expose": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_typename",
+            "field": "__typename",
+            "codec": "string",
+            "nullable": false,
+            "expose": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_blob",
+            "field": "blob",
+            "codec": "base64",
+            "nullable": true,
+            "expose": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_completed",
+            "field": "completed",
+            "codec": "boolean",
+            "nullable": false,
+            "expose": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_payload",
+            "field": "payload",
+            "codec": "json",
+            "nullable": true,
+            "expose": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_priority",
+            "field": "priority",
+            "codec": "int32",
+            "nullable": false,
+            "expose": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_sequence",
+            "field": "sequence",
+            "codec": "json_number_precision_limited",
+            "nullable": false,
+            "expose": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_title",
+            "field": "title",
+            "codec": "string",
+            "nullable": true,
+            "expose": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_updatedAt",
+            "field": "updatedAt",
+            "codec": "string_unvalidated_timestamp",
+            "nullable": true,
+            "expose": false
+          }
+        ]
+      }
+    }
+  ],
+  "protocol": {
+    "version": 1,
+    "schemaHash": "sha256:9d0d6ec390c7402779a98490ce3e046de73c59f1e2534928927495e1407547fe",
+    "surface": {
+      "kind": "role",
+      "name": "user"
+    },
+    "operation": "sha256:d9f67afd74da3173c4a3b60d3dc832cc1288424a932a3784e2a8f9de3b379c13",
+    "trustedPresets": []
+  }
+};
diff --git a/distributed_cli/tests/fixtures/generated-scalar-operation.ts b/distributed_cli/tests/fixtures/generated-scalar-operation.ts
new file mode 100644
index 00000000..5a7fdaeb
--- /dev/null
+++ b/distributed_cli/tests/fixtures/generated-scalar-operation.ts
@@ -0,0 +1,128 @@
+/** GENERATED by dctl client. Do not edit. */
+import type { ReplicaOperationArtifact } from '@hops-ops/distributed/replica';
+
+export type Operation_RustRuntimeBridge_Variables = {
+  readonly "id": string | number;
+  readonly "tenantId": string | number;
+};
+
+export type Operation_RustRuntimeBridge_Data = {
+  readonly "todo": {
+    readonly "id": string;
+    readonly "title": string | null;
+  } | null;
+};
+
+/** Exact canonical query bytes sent to the server. */
+export const Operation_RustRuntimeBridgeDocument = "query RustRuntimeBridge($id: ID!, $tenantId: ID!) {\n  todo(id: $id, tenantId: $tenantId) {\n    id\n    title\n    _distributed_tenantId: tenantId\n    _distributed_typename: __typename\n  }\n}\n";
+
+/** Typed normalized-replica operation descriptor. */
+export const Operation_RustRuntimeBridge: ReplicaOperationArtifact<Operation_RustRuntimeBridge_Data, Operation_RustRuntimeBridge_Variables> = {
+  "id": "sha256:8cd0dd25a9328638e46aa285dc34bbc36be7738616a81bfa26e973ad41ab2878",
+  "document": "query RustRuntimeBridge($id: ID!, $tenantId: ID!) {\n  todo(id: $id, tenantId: $tenantId) {\n    id\n    title\n    _distributed_tenantId: tenantId\n    _distributed_typename: __typename\n  }\n}\n",
+  "source": {
+    "path": "src/routes/runtime-bridge/+page.graphql",
+    "line": 2,
+    "column": 3
+  },
+  "variableCodec": {
+    "version": 1,
+    "limits": {
+      "maxDepth": 8,
+      "maxBoolWidth": 256,
+      "maxInList": 1000
+    },
+    "variables": {
+      "id": {
+        "kind": "scalar",
+        "scalar": "ID",
+        "codec": "string",
+        "nullable": false
+      },
+      "tenantId": {
+        "kind": "scalar",
+        "scalar": "ID",
+        "codec": "string",
+        "nullable": false
+      }
+    },
+    "inputs": {}
+  },
+  "roots": [
+    {
+      "responseKey": "todo",
+      "field": "todo",
+      "cardinality": "one",
+      "nullable": true,
+      "arguments": {
+        "id": {
+          "kind": "variable",
+          "name": "id"
+        },
+        "tenantId": {
+          "kind": "variable",
+          "name": "tenantId"
+        }
+      },
+      "dependencies": [
+        "todo_rows"
+      ],
+      "coverage": {
+        "kind": "complete"
+      },
+      "selection": {
+        "typename": "todo",
+        "storage": {
+          "kind": "normalized",
+          "model": "Todo",
+          "identityFields": [
+            "tenantId",
+            "id"
+          ]
+        },
+        "members": [
+          {
+            "kind": "scalar",
+            "responseKey": "id",
+            "field": "id",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "title",
+            "field": "title",
+            "codec": "string",
+            "nullable": true
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_tenantId",
+            "field": "tenantId",
+            "codec": "string",
+            "nullable": false,
+            "expose": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_typename",
+            "field": "__typename",
+            "codec": "string",
+            "nullable": false,
+            "expose": false
+          }
+        ]
+      }
+    }
+  ],
+  "protocol": {
+    "version": 1,
+    "schemaHash": "sha256:7441d46de81cf919ae22ce29884bdbd7ba436d4f7bf56721156e9b1b8cbc3834",
+    "surface": {
+      "kind": "role",
+      "name": "user"
+    },
+    "operation": "sha256:8cd0dd25a9328638e46aa285dc34bbc36be7738616a81bfa26e973ad41ab2878",
+    "trustedPresets": []
+  }
+};
diff --git a/distributed_cli/tests/fixtures/orders-service/src/lib.rs b/distributed_cli/tests/fixtures/orders-service/src/lib.rs
index 75bab4c2..e052cf14 100644
--- a/distributed_cli/tests/fixtures/orders-service/src/lib.rs
+++ b/distributed_cli/tests/fixtures/orders-service/src/lib.rs
@@ -1,7 +1,18 @@
 //! Minimal Distributed service fixture for `dctl` manifest-harness integration
 //! tests: one read model (→ an `orders` table) registered in the project manifest.
 
-use distributed::{DistributedProjectManifest, ReadModel};
+use std::any::TypeId;
+
+use distributed::graphql::{
+    build_surface, surface_for_role, typed_command, DistributedClientSurfaceExport,
+    GraphqlInputType, GraphqlOutputType, GraphqlTypeDef, GraphqlTypeField, PreparedCommand,
+    Projected, RoleGrant, SurfaceOptions, SurfaceProjector,
+};
+use distributed::microsvc::{CausalCommandContext, HandlerError, Routes, Service};
+use distributed::{
+    Aggregate, AggregateRepository, DistributedProjectManifest, Entity, EventRecord,
+    InMemoryRepository, ReadModel,
+};
 use serde::{Deserialize, Serialize};
 
 #[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, ReadModel)]
@@ -12,8 +23,122 @@ pub struct OrderView {
     pub status: String,
 }
 
+impl GraphqlOutputType for OrderView {
+    fn graphql_type() -> GraphqlTypeDef {
+        GraphqlTypeDef::new(
+            "OrderView",
+            vec![
+                GraphqlTypeField {
+                    name: "order_id".into(),
+                    type_name: "String".into(),
+                    nullable: false,
+                    list: false,
+                    item_nullable: false,
+                    nested: None,
+                },
+                GraphqlTypeField {
+                    name: "status".into(),
+                    type_name: "String".into(),
+                    nullable: false,
+                    list: false,
+                    item_nullable: false,
+                    nested: None,
+                },
+            ],
+        )
+        .with_type_id(TypeId::of::<Self>())
+    }
+}
+
+#[derive(Deserialize)]
+struct ProjectOrderInput {
+    order_id: String,
+}
+
+impl GraphqlInputType for ProjectOrderInput {
+    fn graphql_type() -> GraphqlTypeDef {
+        GraphqlTypeDef::new(
+            "ProjectOrderInput",
+            vec![GraphqlTypeField {
+                name: "order_id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            }],
+        )
+        .with_type_id(TypeId::of::<Self>())
+    }
+}
+
+#[derive(Default)]
+struct FixtureAggregate {
+    entity: Entity,
+}
+
+impl Aggregate for FixtureAggregate {
+    type ReplayError = std::convert::Infallible;
+
+    fn entity(&self) -> &Entity {
+        &self.entity
+    }
+
+    fn entity_mut(&mut self) -> &mut Entity {
+        &mut self.entity
+    }
+
+    fn replay_event(&mut self, _event: &EventRecord) -> Result<(), Self::ReplayError> {
+        Ok(())
+    }
+}
+
+async fn project_order(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    _input: ProjectOrderInput,
+) -> Result<PreparedCommand<Projected<OrderView>>, HandlerError> {
+    Err(HandlerError::Rejected(
+        "manifest-only fixture does not execute commands".into(),
+    ))
+}
+
 /// The entrypoint `dctl describe`/`dctl schema` call by default
 /// (`<crate>::distributed_manifest`).
 pub fn distributed_manifest() -> DistributedProjectManifest {
     DistributedProjectManifest::new("orders").read_model::<OrderView>()
 }
+
+/// Pool-free client export used by `dctl client-manifest`. Both the CLI harness
+/// and a runtime engine finish through `DistributedClientSurfaceExport::manifest`.
+pub fn distributed_client_surface() -> DistributedClientSurfaceExport {
+    let project = distributed_manifest();
+    let service = Service::new().named("orders").routes(
+        Routes::new()
+            .with_repo(AggregateRepository::<_, FixtureAggregate>::new(
+                InMemoryRepository::new(),
+            ))
+            .typed_command(
+                typed_command::<ProjectOrderInput, Projected<OrderView>>("order.project")
+                    .field_name("orders_project")
+                    .roles(["user"]),
+            )
+            .handle(project_order),
+    );
+    let full = build_surface(&project.tables, &SurfaceOptions::sqlite())
+        .expect("fixture Surface should build")
+        .with_service(&service)
+        .expect("fixture typed service should bind")
+        .with_projectors([SurfaceProjector::new("project_orders")
+            .facts(["order.projected"])
+            .models(["OrderView"])
+            .change_epoch("orders-v1")])
+        .expect("fixture projector should bind");
+    let grants = std::collections::BTreeMap::from([(
+        "OrderView".to_string(),
+        RoleGrant::all_columns().with_aggregations(),
+    )]);
+    let user =
+        surface_for_role(&full, "user", &grants).expect("fixture role policy should be valid");
+    DistributedClientSurfaceExport::from_project(&project, user)
+        .expect("fixture Surface should be role-selected")
+}
diff --git a/distributed_cli/tests/fixtures/protocol.d.ts b/distributed_cli/tests/fixtures/protocol.d.ts
new file mode 100644
index 00000000..aaaa2fbe
--- /dev/null
+++ b/distributed_cli/tests/fixtures/protocol.d.ts
@@ -0,0 +1,3 @@
+import type { ReplicaCommandStatusArtifact } from '@hops-ops/distributed/replica';
+
+export declare const COMMAND_STATUS: ReplicaCommandStatusArtifact;
diff --git a/distributed_cli/tests/fixtures/runtime-bridge-operation.json b/distributed_cli/tests/fixtures/runtime-bridge-operation.json
new file mode 100644
index 00000000..0054fc32
--- /dev/null
+++ b/distributed_cli/tests/fixtures/runtime-bridge-operation.json
@@ -0,0 +1,109 @@
+{
+  "id": "sha256:8cd0dd25a9328638e46aa285dc34bbc36be7738616a81bfa26e973ad41ab2878",
+  "document": "query RustRuntimeBridge($id: ID!, $tenantId: ID!) {\n  todo(id: $id, tenantId: $tenantId) {\n    id\n    title\n    _distributed_tenantId: tenantId\n    _distributed_typename: __typename\n  }\n}\n",
+  "source": {
+    "path": "src/routes/runtime-bridge/+page.graphql",
+    "line": 2,
+    "column": 3
+  },
+  "variableCodec": {
+    "version": 1,
+    "limits": {
+      "maxDepth": 8,
+      "maxBoolWidth": 256,
+      "maxInList": 1000
+    },
+    "variables": {
+      "id": {
+        "kind": "scalar",
+        "scalar": "ID",
+        "codec": "string",
+        "nullable": false
+      },
+      "tenantId": {
+        "kind": "scalar",
+        "scalar": "ID",
+        "codec": "string",
+        "nullable": false
+      }
+    },
+    "inputs": {}
+  },
+  "roots": [
+    {
+      "responseKey": "todo",
+      "field": "todo",
+      "cardinality": "one",
+      "nullable": true,
+      "arguments": {
+        "id": {
+          "kind": "variable",
+          "name": "id"
+        },
+        "tenantId": {
+          "kind": "variable",
+          "name": "tenantId"
+        }
+      },
+      "dependencies": [
+        "todo_rows"
+      ],
+      "coverage": {
+        "kind": "complete"
+      },
+      "selection": {
+        "typename": "todo",
+        "storage": {
+          "kind": "normalized",
+          "model": "Todo",
+          "identityFields": [
+            "tenantId",
+            "id"
+          ]
+        },
+        "members": [
+          {
+            "kind": "scalar",
+            "responseKey": "id",
+            "field": "id",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "title",
+            "field": "title",
+            "codec": "string",
+            "nullable": true
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_tenantId",
+            "field": "tenantId",
+            "codec": "string",
+            "nullable": false,
+            "expose": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_typename",
+            "field": "__typename",
+            "codec": "string",
+            "nullable": false,
+            "expose": false
+          }
+        ]
+      }
+    }
+  ],
+  "protocol": {
+    "version": 1,
+    "schemaHash": "sha256:7441d46de81cf919ae22ce29884bdbd7ba436d4f7bf56721156e9b1b8cbc3834",
+    "surface": {
+      "kind": "role",
+      "name": "user"
+    },
+    "operation": "sha256:8cd0dd25a9328638e46aa285dc34bbc36be7738616a81bfa26e973ad41ab2878",
+    "trustedPresets": []
+  }
+}
diff --git a/distributed_cli/tests/fixtures/tsconfig.generated-commands.json b/distributed_cli/tests/fixtures/tsconfig.generated-commands.json
new file mode 100644
index 00000000..8098dd26
--- /dev/null
+++ b/distributed_cli/tests/fixtures/tsconfig.generated-commands.json
@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "verbatimModuleSyntax": true,
+    "baseUrl": "../../..",
+    "paths": {
+      "@hops-ops/distributed/replica": ["js/src/replica/index.ts"]
+    }
+  },
+  "files": [
+    "generated-commands.ts",
+    "generated-commands-consumer.ts",
+    "protocol.d.ts"
+  ]
+}
diff --git a/distributed_macros/Cargo.toml b/distributed_macros/Cargo.toml
index 1d2f1d50..a056d2de 100644
--- a/distributed_macros/Cargo.toml
+++ b/distributed_macros/Cargo.toml
@@ -20,3 +20,4 @@ trybuild = "1.0"
 # need the runtime crate to type-check generated `distributed::...` code.
 # Cargo permits dev-dependency cycles.
 distributed = { path = ".." }
+serde = { version = "1.0", features = ["derive"] }
diff --git a/distributed_macros/src/aggregate.rs b/distributed_macros/src/aggregate.rs
new file mode 100644
index 00000000..a3101b14
--- /dev/null
+++ b/distributed_macros/src/aggregate.rs
@@ -0,0 +1,437 @@
+use proc_macro2::TokenStream as TokenStream2;
+use quote::{format_ident, quote};
+use syn::{
+    braced,
+    parse::{Parse, ParseStream},
+    Ident, LitStr, Token,
+};
+
+/// Emit the `impl distributed::Aggregate` block shared by `aggregate!` and
+/// `#[sourced]`.
+///
+/// Both entry points produce a byte-identical impl: same associated
+/// `ReplayError = String`, same `entity`/`entity_mut`/`replay_event` bodies, and
+/// the same optional `aggregate_type` and upcasters methods. Only the replay
+/// match arms differ in how they are built upstream, so this helper takes them
+/// (already rendered) along with the type name and entity field. Keeping one
+/// emitter prevents the replay semantics of the two macros from drifting.
+///
+/// It emits only the `impl` block; callers still place `#upcaster_wrappers`
+/// (the free upcaster fns) where they already do.
+pub(crate) fn aggregate_impl_tokens(
+    type_name: &Ident,
+    entity_field: &Ident,
+    aggregate_type_method: &Option<TokenStream2>,
+    replay_arms: &[TokenStream2],
+    upcasters_method: &TokenStream2,
+) -> TokenStream2 {
+    quote! {
+        impl distributed::Aggregate for #type_name {
+            type ReplayError = String;
+
+            #aggregate_type_method
+
+            fn entity(&self) -> &distributed::Entity {
+                &self.#entity_field
+            }
+
+            fn entity_mut(&mut self) -> &mut distributed::Entity {
+                &mut self.#entity_field
+            }
+
+            fn replay_event(
+                &mut self,
+                event: &distributed::EventRecord,
+            ) -> Result<(), Self::ReplayError> {
+                match event.event_name.as_str() {
+                    #(#replay_arms)*
+                    _ => return Err(format!("Unknown event: {}", event.event_name)),
+                }
+                Ok(())
+            }
+
+            #upcasters_method
+        }
+    }
+}
+
+// ============================================================================
+// aggregate! proc-macro
+// ============================================================================
+fn upcaster_wrapper_prefix(owner: &Ident) -> String {
+    owner
+        .to_string()
+        .trim_start_matches("r#")
+        .to_ascii_lowercase()
+}
+
+pub(crate) fn event_variant_ident(event_name: &LitStr) -> Ident {
+    let value = event_name.value();
+    let segment = value
+        .rsplit('.')
+        .find(|part| !part.is_empty())
+        .unwrap_or(&value);
+    let mut ident = String::new();
+    let mut capitalize_next = true;
+
+    for ch in segment.chars() {
+        if ch.is_ascii_alphanumeric() {
+            if ident.is_empty() && ch.is_ascii_digit() {
+                ident.push_str("Event");
+            }
+
+            if capitalize_next {
+                ident.push(ch.to_ascii_uppercase());
+                capitalize_next = false;
+            } else {
+                ident.push(ch);
+            }
+        } else {
+            capitalize_next = true;
+        }
+    }
+
+    if ident.is_empty() {
+        ident.push_str("Event");
+    }
+
+    format_ident!("{}", ident)
+}
+
+pub(crate) fn generate_upcaster_tokens(
+    owner: &Ident,
+    upcasters: &[UpcasterDef],
+) -> (proc_macro2::TokenStream, proc_macro2::TokenStream) {
+    if upcasters.is_empty() {
+        return (quote! {}, quote! {});
+    }
+
+    let prefix = upcaster_wrapper_prefix(owner);
+    let wrapper_names: Vec<_> = upcasters
+        .iter()
+        .enumerate()
+        .map(|(idx, _)| format_ident!("__sourced_upcast_{}_{}", prefix, idx))
+        .collect();
+
+    let wrapper_defs = upcasters
+        .iter()
+        .zip(wrapper_names.iter())
+        .map(|(u, wrapper)| {
+            let source_type = &u.source_type;
+            let target_type = &u.target_type;
+            let to_version = &u.to_version;
+            let transform_fn = &u.transform_fn;
+            quote! {
+                fn #wrapper(
+                    event: &distributed::EventRecord,
+                ) -> Result<Vec<u8>, distributed::UpcastError> {
+                    distributed::upcast_payload::<#source_type, #target_type>(
+                        event,
+                        #to_version,
+                        #transform_fn,
+                    )
+                }
+            }
+        });
+
+    let upcaster_entries = upcasters
+        .iter()
+        .zip(wrapper_names.iter())
+        .map(|(u, wrapper)| {
+            let event_name = &u.event_name;
+            let from_version = &u.from_version;
+            let to_version = &u.to_version;
+            quote! {
+                distributed::EventUpcaster {
+                    event_type: #event_name,
+                    from_version: #from_version,
+                    to_version: #to_version,
+                    transform: #owner::#wrapper,
+                }
+            }
+        });
+
+    let upcasters_method = quote! {
+        fn upcasters() -> &'static [distributed::EventUpcaster] {
+            static UPCASTERS: &[distributed::EventUpcaster] = &[
+                #(#upcaster_entries),*
+            ];
+            UPCASTERS
+        }
+    };
+
+    (
+        quote! {
+            impl #owner {
+                #(#wrapper_defs)*
+            }
+        },
+        upcasters_method,
+    )
+}
+
+// ============================================================================
+// #[enqueue] attribute macro
+// ============================================================================
+pub(crate) fn expand_aggregate(input: TokenStream2) -> syn::Result<TokenStream2> {
+    let input = syn::parse2::<AggregateInput>(input)?;
+
+    let agg_name = &input.agg_name;
+    let entity_field = &input.entity_field;
+
+    // Generate replay match arms - deserialize and call method directly
+    let replay_arms: Vec<_> = input
+        .events
+        .iter()
+        .map(|evt| {
+            let event_name = &evt.event_name;
+            let method_name = &evt.method_name;
+            let args = &evt.args;
+
+            // Determine what args to pass to the method
+            let call_args: Vec<_> = match &evt.method_args {
+                Some(method_args) => method_args.clone(),
+                None => args.clone(),
+            };
+
+            if args.is_empty() {
+                // No payload
+                quote! {
+                    #event_name => {
+                        self.#method_name().map_err(|e| e.to_string())?;
+                    }
+                }
+            } else if call_args.is_empty() {
+                // Event has payload but method takes no args
+                quote! {
+                    #event_name => {
+                        self.#method_name().map_err(|e| e.to_string())?;
+                    }
+                }
+            } else if args.len() == 1 {
+                // Single-element tuple needs trailing comma: (x,) not (x)
+                let arg = &args[0];
+                let call_arg = &call_args[0];
+                quote! {
+                    #event_name => {
+                        let (#arg,) = event.decode().map_err(|e| e.to_string())?;
+                        self.#method_name(#call_arg).map_err(|e| e.to_string())?;
+                    }
+                }
+            } else {
+                // Multi-element tuple
+                quote! {
+                    #event_name => {
+                        let (#(#args),*) = event.decode().map_err(|e| e.to_string())?;
+                        self.#method_name(#(#call_args),*).map_err(|e| e.to_string())?;
+                    }
+                }
+            }
+        })
+        .collect();
+
+    let (upcaster_wrappers, upcasters_method) =
+        generate_upcaster_tokens(agg_name, &input.upcasters);
+    let aggregate_type_method = input.aggregate_type.as_ref().map(|aggregate_type| {
+        quote! {
+            fn aggregate_type() -> &'static str {
+                #aggregate_type
+            }
+        }
+    });
+
+    // ReplayError stays `String`: replay errors are flattened from
+    // heterogeneous sources (per-event `decode()` errors, user method errors of
+    // arbitrary `E`, and unknown-event messages) via `e.to_string()`. A typed
+    // error would have to be generic over each method's error type or erase
+    // them anyway, so `String` is the smaller, honest representation here.
+    let aggregate_impl = aggregate_impl_tokens(
+        agg_name,
+        entity_field,
+        &aggregate_type_method,
+        &replay_arms,
+        &upcasters_method,
+    );
+    let expanded = quote! {
+        #upcaster_wrappers
+
+        #aggregate_impl
+    };
+
+    Ok(expanded)
+}
+
+pub(crate) struct UpcasterDef {
+    pub(crate) event_name: LitStr,
+    pub(crate) from_version: syn::LitInt,
+    pub(crate) to_version: syn::LitInt,
+    source_type: syn::Type,
+    target_type: syn::Type,
+    transform_fn: syn::Path,
+}
+
+impl Parse for UpcasterDef {
+    /// Parses one upcaster entry:
+    /// `("event.name", from => to, SourceType => TargetType, transform_fn)`.
+    ///
+    /// Shared by `aggregate!` and `#[sourced(..., upcasters(...))]` so the
+    /// upcaster grammar cannot drift between the two entry points.
+    fn parse(input: ParseStream) -> syn::Result<Self> {
+        let inner;
+        syn::parenthesized!(inner in input);
+
+        let event_name: LitStr = inner.parse()?;
+        inner.parse::<Token![,]>()?;
+        let from_version: syn::LitInt = inner.parse()?;
+        inner.parse::<Token![=>]>()?;
+        let to_version: syn::LitInt = inner.parse()?;
+        inner.parse::<Token![,]>()?;
+        let source_type: syn::Type = inner.parse()?;
+        inner.parse::<Token![=>]>()?;
+        let target_type: syn::Type = inner.parse()?;
+        inner.parse::<Token![,]>()?;
+        let transform_fn: syn::Path = inner.parse()?;
+
+        Ok(UpcasterDef {
+            event_name,
+            from_version,
+            to_version,
+            source_type,
+            target_type,
+            transform_fn,
+        })
+    }
+}
+
+/// Parse a sequence of parenthesized upcaster entries with optional trailing
+/// commas, until `content` is exhausted.
+pub(crate) fn parse_upcaster_list(content: ParseStream) -> syn::Result<Vec<UpcasterDef>> {
+    let mut upcasters = Vec::new();
+    while !content.is_empty() {
+        upcasters.push(content.parse::<UpcasterDef>()?);
+        // Optional trailing comma between upcaster entries
+        if content.peek(Token![,]) {
+            content.parse::<Token![,]>()?;
+        }
+    }
+    Ok(upcasters)
+}
+
+struct AggregateInput {
+    agg_name: Ident,
+    entity_field: Ident,
+    aggregate_type: Option<LitStr>,
+    events: Vec<EventDef>,
+    upcasters: Vec<UpcasterDef>,
+}
+
+struct EventDef {
+    event_name: LitStr,
+    args: Vec<Ident>,
+    method_name: Ident,
+    method_args: Option<Vec<Ident>>, // None = use event args, Some([]) = no args, Some([x,y]) = specific args
+}
+
+pub(crate) fn validate_aggregate_type_literal(lit: &LitStr) -> syn::Result<()> {
+    let value = lit.value();
+    if value.trim().is_empty() {
+        return Err(syn::Error::new_spanned(
+            lit,
+            "`aggregate_type` must not be empty or whitespace",
+        ));
+    }
+    if value.contains('\u{1f}') {
+        return Err(syn::Error::new_spanned(
+            lit,
+            "`aggregate_type` must not contain the reserved stream delimiter (U+001F)",
+        ));
+    }
+    Ok(())
+}
+
+impl Parse for AggregateInput {
+    fn parse(input: ParseStream) -> syn::Result<Self> {
+        let agg_name: Ident = input.parse()?;
+        input.parse::<Token![,]>()?;
+        let entity_field: Ident = input.parse()?;
+        let mut aggregate_type = None;
+
+        if input.peek(Token![,]) {
+            input.parse::<Token![,]>()?;
+            let kw: Ident = input.parse()?;
+            if kw != "aggregate_type" {
+                return Err(syn::Error::new(kw.span(), "expected `aggregate_type`"));
+            }
+            input.parse::<Token![=]>()?;
+            let lit = input.parse::<LitStr>()?;
+            validate_aggregate_type_literal(&lit)?;
+            aggregate_type = Some(lit);
+        }
+
+        let content;
+        braced!(content in input);
+
+        let mut events = Vec::new();
+        while !content.is_empty() {
+            let event_name: LitStr = content.parse()?;
+
+            // Parse (arg1, arg2, ...)
+            let args_content;
+            syn::parenthesized!(args_content in content);
+            let args: syn::punctuated::Punctuated<Ident, Token![,]> =
+                args_content.parse_terminated(Ident::parse, Token![,])?;
+            let args: Vec<Ident> = args.into_iter().collect();
+
+            content.parse::<Token![=>]>()?;
+            let method_name: Ident = content.parse()?;
+
+            // Check for optional method args: method() or method(a, b)
+            let method_args = if content.peek(syn::token::Paren) {
+                let method_args_content;
+                syn::parenthesized!(method_args_content in content);
+                let method_args: syn::punctuated::Punctuated<Ident, Token![,]> =
+                    method_args_content.parse_terminated(Ident::parse, Token![,])?;
+                Some(method_args.into_iter().collect())
+            } else {
+                None // Use event args
+            };
+
+            events.push(EventDef {
+                event_name,
+                args,
+                method_name,
+                method_args,
+            });
+
+            // Optional trailing comma
+            if content.peek(Token![,]) {
+                content.parse::<Token![,]>()?;
+            }
+        }
+
+        // Parse optional `upcasters [...]` block
+        let mut upcasters = Vec::new();
+        if input.peek(syn::Ident) {
+            let kw: Ident = input.parse()?;
+            if kw != "upcasters" {
+                return Err(syn::Error::new(kw.span(), "expected `upcasters`"));
+            }
+
+            let upcaster_content;
+            syn::bracketed!(upcaster_content in input);
+            upcasters = parse_upcaster_list(&upcaster_content)?;
+        }
+
+        Ok(AggregateInput {
+            agg_name,
+            entity_field,
+            aggregate_type,
+            events,
+            upcasters,
+        })
+    }
+}
+
+// ============================================================================
+// #[sourced] attribute macro
+// ============================================================================
diff --git a/distributed_macros/src/command_effects.rs b/distributed_macros/src/command_effects.rs
new file mode 100644
index 00000000..c9f81088
--- /dev/null
+++ b/distributed_macros/src/command_effects.rs
@@ -0,0 +1,855 @@
+use proc_macro2::TokenStream;
+use quote::{format_ident, quote};
+use syn::parse::{Parse, ParseStream};
+use syn::{braced, parenthesized, Expr, Ident, Lit, Path, Result, Token};
+
+mod keyword {
+    syn::custom_keyword!(input);
+    syn::custom_keyword!(upsert);
+    syn::custom_keyword!(patch);
+    syn::custom_keyword!(delete);
+    syn::custom_keyword!(link);
+    syn::custom_keyword!(unlink);
+    syn::custom_keyword!(invalidate);
+    syn::custom_keyword!(key);
+    syn::custom_keyword!(set);
+    syn::custom_keyword!(source);
+    syn::custom_keyword!(target);
+    syn::custom_keyword!(confirm);
+    syn::custom_keyword!(partition);
+    syn::custom_keyword!(default);
+}
+
+pub fn expand(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
+    match syn::parse::<CommandEffects>(input) {
+        Ok(effects) => effects.expand().into(),
+        Err(error) => error.to_compile_error().into(),
+    }
+}
+
+pub fn expand_confirmations(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
+    match syn::parse::<CommandConfirmations>(input) {
+        Ok(confirmations) => confirmations.expand().into(),
+        Err(error) => error.to_compile_error().into(),
+    }
+}
+
+pub fn expand_input_defaults(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
+    match syn::parse::<CommandInputDefaults>(input) {
+        Ok(defaults) => defaults.expand().into(),
+        Err(error) => error.to_compile_error().into(),
+    }
+}
+
+struct CommandInputDefaults {
+    input: Path,
+    defaults: Vec<InputDefault>,
+}
+
+impl Parse for CommandInputDefaults {
+    fn parse(stream: ParseStream<'_>) -> Result<Self> {
+        stream.parse::<keyword::input>()?;
+        stream.parse::<Token![:]>()?;
+        let input = stream.parse()?;
+        stream.parse::<Token![;]>()?;
+
+        let mut defaults = Vec::new();
+        let mut fields = std::collections::BTreeSet::new();
+        while !stream.is_empty() {
+            stream.parse::<keyword::default>()?;
+            let default = InputDefault::parse(stream)?;
+            if !fields.insert(default.field.to_string()) {
+                return Err(syn::Error::new(
+                    default.field.span(),
+                    format!("duplicate generated input default `{}`", default.field),
+                ));
+            }
+            defaults.push(default);
+            stream.parse::<Token![;]>()?;
+        }
+        if defaults.is_empty() {
+            return Err(stream.error("command_input_defaults! requires at least one default"));
+        }
+        Ok(Self { input, defaults })
+    }
+}
+
+impl CommandInputDefaults {
+    fn expand(self) -> TokenStream {
+        let input = self.input;
+        let defaults = self
+            .defaults
+            .into_iter()
+            .map(|default| default.expand(&input));
+        quote! {
+            distributed::graphql::__command_input_defaults::<#input>(
+                vec![#(#defaults),*]
+            )
+        }
+    }
+}
+
+enum InputDefaultGenerator {
+    UuidV7,
+    Ulid,
+}
+
+struct InputDefault {
+    field: Ident,
+    generator: InputDefaultGenerator,
+}
+
+impl InputDefault {
+    fn parse(stream: ParseStream<'_>) -> Result<Self> {
+        let input_ident: Ident = stream.parse()?;
+        if input_ident != "input" {
+            return Err(syn::Error::new(
+                input_ident.span(),
+                "generated defaults must target `input.field`",
+            ));
+        }
+        stream.parse::<Token![.]>()?;
+        let field = stream.parse()?;
+        stream.parse::<Token![=]>()?;
+        let generator: Ident = stream.parse()?;
+        let arguments;
+        parenthesized!(arguments in stream);
+        if !arguments.is_empty() {
+            return Err(arguments.error("input-default generators take no arguments"));
+        }
+        let generator = match generator.to_string().as_str() {
+            "uuid_v7" => InputDefaultGenerator::UuidV7,
+            "ulid" => InputDefaultGenerator::Ulid,
+            _ => {
+                return Err(syn::Error::new(
+                    generator.span(),
+                    "unknown input-default generator; expected uuid_v7() or ulid()",
+                ));
+            }
+        };
+        Ok(Self { field, generator })
+    }
+
+    fn expand(self, input: &Path) -> TokenStream {
+        let marker_name = format_ident!(
+            "__Distributed{}EffectInputField_{}",
+            input.segments.last().unwrap().ident,
+            self.field,
+            span = self.field.span()
+        );
+        let marker = marker_path(input, marker_name);
+        match self.generator {
+            InputDefaultGenerator::UuidV7 => quote! {
+                distributed::graphql::__input_default_uuid_v7::<#input, #marker>()
+            },
+            InputDefaultGenerator::Ulid => quote! {
+                distributed::graphql::__input_default_ulid::<#input, #marker>()
+            },
+        }
+    }
+}
+
+struct CommandEffects {
+    input: Path,
+    operations: Vec<Operation>,
+}
+
+impl Parse for CommandEffects {
+    fn parse(stream: ParseStream<'_>) -> Result<Self> {
+        stream.parse::<keyword::input>()?;
+        stream.parse::<Token![:]>()?;
+        let input = stream.parse()?;
+        stream.parse::<Token![;]>()?;
+
+        let mut operations = Vec::new();
+        while !stream.is_empty() {
+            operations.push(Operation::parse(stream)?);
+            stream.parse::<Token![;]>()?;
+        }
+        if operations.is_empty() {
+            return Err(stream.error(
+                "command_effects! requires at least one operation; omit .effects(...) to use explicit revalidation",
+            ));
+        }
+        Ok(Self { input, operations })
+    }
+}
+
+impl CommandEffects {
+    fn expand(self) -> TokenStream {
+        let input = self.input;
+        let operations = self
+            .operations
+            .into_iter()
+            .map(|operation| operation.expand(&input));
+        quote! {
+            distributed::graphql::__command_effects::<#input>(vec![#(#operations),*])
+        }
+    }
+}
+
+struct CommandConfirmations {
+    input: Path,
+    confirmations: Vec<ProjectionConfirmation>,
+}
+
+impl Parse for CommandConfirmations {
+    fn parse(stream: ParseStream<'_>) -> Result<Self> {
+        stream.parse::<keyword::input>()?;
+        stream.parse::<Token![:]>()?;
+        let input = stream.parse()?;
+        stream.parse::<Token![;]>()?;
+
+        let mut confirmations = Vec::new();
+        while !stream.is_empty() {
+            stream.parse::<keyword::confirm>()?;
+            confirmations.push(ProjectionConfirmation::parse(stream)?);
+            stream.parse::<Token![;]>()?;
+        }
+        if confirmations.is_empty() {
+            return Err(stream
+                .error("command_confirmations! requires at least one finite projector target"));
+        }
+        Ok(Self {
+            input,
+            confirmations,
+        })
+    }
+}
+
+impl CommandConfirmations {
+    fn expand(self) -> TokenStream {
+        let input = self.input;
+        let confirmations = self
+            .confirmations
+            .into_iter()
+            .map(|confirmation| confirmation.expand(&input));
+        quote! {
+            distributed::graphql::__command_confirmations::<#input>(
+                vec![#(#confirmations),*]
+            )
+        }
+    }
+}
+
+struct ProjectionConfirmation {
+    projector: Path,
+    model: Path,
+    key: FieldMap,
+    partition: Option<ValueExpression>,
+}
+
+impl ProjectionConfirmation {
+    fn parse(stream: ParseStream<'_>) -> Result<Self> {
+        let projector = stream.parse()?;
+        stream.parse::<Token![->]>()?;
+        let model = stream.parse()?;
+        let content;
+        braced!(content in stream);
+        content.parse::<keyword::key>()?;
+        let key = FieldMap::parse_braced(&content)?;
+        let partition: Option<ValueExpression> = if content.is_empty() {
+            None
+        } else {
+            content.parse::<Token![,]>()?;
+            content.parse::<keyword::partition>()?;
+            content.parse::<Token![:]>()?;
+            Some(content.parse()?)
+        };
+        if !content.is_empty() {
+            return Err(content.error("unexpected tokens after projector confirmation"));
+        }
+        Ok(Self {
+            projector,
+            model,
+            key,
+            partition,
+        })
+    }
+
+    fn expand(self, input: &Path) -> TokenStream {
+        let projector = self.projector;
+        let model = self.model;
+        let key = self.key.expand_key(input, &model);
+        let confirmation = quote! {
+            (#projector).__distributed_confirmation::<#input, #model>(#key)
+        };
+        match self.partition {
+            Some(partition) => {
+                let partition = partition.expand(input);
+                quote! { (#confirmation).partition(#partition) }
+            }
+            None => confirmation,
+        }
+    }
+}
+
+enum Operation {
+    Upsert(ModelWrite),
+    Patch(ModelWrite),
+    Delete(ModelDelete),
+    Link(RelationshipWrite),
+    Unlink(RelationshipWrite),
+    InvalidateModel(Path),
+    InvalidateRelationship(RelationshipInvalidate),
+}
+
+impl Operation {
+    fn parse(stream: ParseStream<'_>) -> Result<Self> {
+        if stream.peek(keyword::upsert) {
+            stream.parse::<keyword::upsert>()?;
+            return Ok(Self::Upsert(ModelWrite::parse(stream)?));
+        }
+        if stream.peek(keyword::patch) {
+            stream.parse::<keyword::patch>()?;
+            return Ok(Self::Patch(ModelWrite::parse(stream)?));
+        }
+        if stream.peek(keyword::delete) {
+            stream.parse::<keyword::delete>()?;
+            return Ok(Self::Delete(ModelDelete::parse(stream)?));
+        }
+        if stream.peek(keyword::link) {
+            stream.parse::<keyword::link>()?;
+            return Ok(Self::Link(RelationshipWrite::parse(stream)?));
+        }
+        if stream.peek(keyword::unlink) {
+            stream.parse::<keyword::unlink>()?;
+            return Ok(Self::Unlink(RelationshipWrite::parse(stream)?));
+        }
+        if stream.peek(keyword::invalidate) {
+            stream.parse::<keyword::invalidate>()?;
+            let model: Path = stream.parse()?;
+            if stream.peek(Token![.]) {
+                stream.parse::<Token![.]>()?;
+                let relationship = stream.parse()?;
+                let content;
+                braced!(content in stream);
+                content.parse::<keyword::source>()?;
+                let source = FieldMap::parse_braced(&content)?;
+                if !content.is_empty() {
+                    return Err(content.error("unexpected tokens after invalidate source key"));
+                }
+                return Ok(Self::InvalidateRelationship(RelationshipInvalidate {
+                    model,
+                    relationship,
+                    source,
+                }));
+            }
+            return Ok(Self::InvalidateModel(model));
+        }
+        Err(stream.error("expected upsert, patch, delete, link, unlink, or invalidate operation"))
+    }
+
+    fn expand(self, input: &Path) -> TokenStream {
+        match self {
+            Self::Upsert(write) => write.expand(input, WriteKind::Upsert),
+            Self::Patch(write) => write.expand(input, WriteKind::Patch),
+            Self::Delete(delete) => delete.expand(input),
+            Self::Link(write) => write.expand(input, RelationshipKind::Link),
+            Self::Unlink(write) => write.expand(input, RelationshipKind::Unlink),
+            Self::InvalidateModel(model) => quote! {
+                distributed::graphql::__effect_invalidate_model::<#model>()
+            },
+            Self::InvalidateRelationship(invalidate) => invalidate.expand(input),
+        }
+    }
+}
+
+struct ModelWrite {
+    model: Path,
+    key: FieldMap,
+    fields: FieldMap,
+}
+
+impl ModelWrite {
+    fn parse(stream: ParseStream<'_>) -> Result<Self> {
+        let model = stream.parse()?;
+        let content;
+        braced!(content in stream);
+        content.parse::<keyword::key>()?;
+        let key = FieldMap::parse_braced(&content)?;
+        content.parse::<Token![,]>()?;
+        content.parse::<keyword::set>()?;
+        let fields = FieldMap::parse_braced(&content)?;
+        for (field, _) in &fields.0 {
+            if key.0.iter().any(|(key_field, _)| key_field == field) {
+                return Err(syn::Error::new(
+                    field.span(),
+                    format!(
+                        "effect set cannot assign key field `{field}`; upsert/patch identity materializes from `key` and rekeying is unsupported"
+                    ),
+                ));
+            }
+        }
+        if !content.is_empty() {
+            return Err(content.error("unexpected tokens after model effect set"));
+        }
+        Ok(Self { model, key, fields })
+    }
+
+    fn expand(self, input: &Path, kind: WriteKind) -> TokenStream {
+        let model = self.model;
+        let key = self.key.expand_key(input, &model);
+        let fields = self.fields.expand_fields(input, &model);
+        match kind {
+            WriteKind::Upsert => quote! {
+                distributed::graphql::__effect_upsert::<#model>(#key, vec![#(#fields),*])
+            },
+            WriteKind::Patch => quote! {
+                distributed::graphql::__effect_patch::<#model>(#key, vec![#(#fields),*])
+            },
+        }
+    }
+}
+
+enum WriteKind {
+    Upsert,
+    Patch,
+}
+
+struct ModelDelete {
+    model: Path,
+    key: FieldMap,
+}
+
+impl ModelDelete {
+    fn parse(stream: ParseStream<'_>) -> Result<Self> {
+        let model = stream.parse()?;
+        let content;
+        braced!(content in stream);
+        content.parse::<keyword::key>()?;
+        let key = FieldMap::parse_braced(&content)?;
+        if !content.is_empty() {
+            return Err(content.error("unexpected tokens after delete key"));
+        }
+        Ok(Self { model, key })
+    }
+
+    fn expand(self, input: &Path) -> TokenStream {
+        let model = self.model;
+        let key = self.key.expand_key(input, &model);
+        quote! { distributed::graphql::__effect_delete::<#model>(#key) }
+    }
+}
+
+struct RelationshipWrite {
+    source_model: Path,
+    relationship: Ident,
+    target_model: Path,
+    source: FieldMap,
+    target: FieldMap,
+}
+
+impl RelationshipWrite {
+    fn parse(stream: ParseStream<'_>) -> Result<Self> {
+        let source_model = stream.parse()?;
+        stream.parse::<Token![.]>()?;
+        let relationship = stream.parse()?;
+        stream.parse::<Token![->]>()?;
+        let target_model = stream.parse()?;
+        let content;
+        braced!(content in stream);
+        content.parse::<keyword::source>()?;
+        let source = FieldMap::parse_braced(&content)?;
+        content.parse::<Token![,]>()?;
+        content.parse::<keyword::target>()?;
+        let target = FieldMap::parse_braced(&content)?;
+        if !content.is_empty() {
+            return Err(content.error("unexpected tokens after relationship effect keys"));
+        }
+        Ok(Self {
+            source_model,
+            relationship,
+            target_model,
+            source,
+            target,
+        })
+    }
+
+    fn expand(self, input: &Path, kind: RelationshipKind) -> TokenStream {
+        let source_model = self.source_model;
+        let target_model = self.target_model;
+        let relationship_method = format_ident!(
+            "__Distributed{}EffectRelationship_{}",
+            source_model.segments.last().unwrap().ident,
+            self.relationship,
+            span = self.relationship.span()
+        );
+        let relationship_marker = marker_path(&source_model, relationship_method);
+        let relationship = quote! {
+            distributed::graphql::__effect_relationship::<#relationship_marker>()
+        };
+        let source = self.source.expand_key(input, &source_model);
+        let target = self.target.expand_key(input, &target_model);
+        match kind {
+            RelationshipKind::Link => quote! {
+                distributed::graphql::__effect_link::<#source_model, #target_model>(
+                    #relationship,
+                    #source,
+                    #target,
+                )
+            },
+            RelationshipKind::Unlink => quote! {
+                distributed::graphql::__effect_unlink::<#source_model, #target_model>(
+                    #relationship,
+                    #source,
+                    #target,
+                )
+            },
+        }
+    }
+}
+
+enum RelationshipKind {
+    Link,
+    Unlink,
+}
+
+struct RelationshipInvalidate {
+    model: Path,
+    relationship: Ident,
+    source: FieldMap,
+}
+
+impl RelationshipInvalidate {
+    fn expand(self, input: &Path) -> TokenStream {
+        let model = self.model;
+        let relationship_method = format_ident!(
+            "__Distributed{}EffectRelationship_{}",
+            model.segments.last().unwrap().ident,
+            self.relationship,
+            span = self.relationship.span()
+        );
+        let relationship_marker = marker_path(&model, relationship_method);
+        let source = self.source.expand_key(input, &model);
+        quote! {
+            distributed::graphql::__effect_invalidate_relationship(
+                distributed::graphql::__effect_relationship::<#relationship_marker>(),
+                #source,
+            )
+        }
+    }
+}
+
+struct FieldMap(Vec<(Ident, ValueExpression)>);
+
+impl FieldMap {
+    fn parse_braced(stream: ParseStream<'_>) -> Result<Self> {
+        let content;
+        braced!(content in stream);
+        let mut fields = Vec::new();
+        let mut names = std::collections::BTreeSet::new();
+        while !content.is_empty() {
+            let field: Ident = content.parse()?;
+            if !names.insert(field.to_string()) {
+                return Err(syn::Error::new(
+                    field.span(),
+                    format!("duplicate command-effect field `{field}`"),
+                ));
+            }
+            content.parse::<Token![:]>()?;
+            let value = content.parse()?;
+            fields.push((field, value));
+            if content.is_empty() {
+                break;
+            }
+            content.parse::<Token![,]>()?;
+        }
+        if fields.is_empty() {
+            return Err(content.error("effect key/set must contain at least one field"));
+        }
+        Ok(Self(fields))
+    }
+
+    fn expand_key(self, input: &Path, model: &Path) -> TokenStream {
+        let mut key_type = model.clone();
+        let last = key_type
+            .segments
+            .last_mut()
+            .expect("syn paths always contain at least one segment");
+        last.ident = format_ident!(
+            "__Distributed{}EffectKey",
+            last.ident,
+            span = last.ident.span()
+        );
+        let fields = self.0.into_iter().map(|(field, expression)| {
+            let marker_name = format_ident!(
+                "__Distributed{}EffectModelField_{}",
+                model.segments.last().unwrap().ident,
+                field,
+                span = field.span()
+            );
+            let marker = marker_path(model, marker_name);
+            let value = expression.expand(input);
+            quote! {
+                #field: distributed::graphql::__effect_key_assignment::<#marker, _>(#value)
+            }
+        });
+        quote! {
+            {
+                let key: distributed::graphql::TypedEffectKey<#model> =
+                    #key_type { #(#fields),* }.into();
+                key
+            }
+        }
+    }
+
+    fn expand_fields(self, input: &Path, model: &Path) -> Vec<TokenStream> {
+        self.0
+            .into_iter()
+            .map(|(field, expression)| {
+                let method = format_ident!(
+                    "__Distributed{}EffectModelField_{}",
+                    model.segments.last().unwrap().ident,
+                    field,
+                    span = field.span()
+                );
+                let marker = marker_path(model, method);
+                let value = expression.expand(input);
+                quote! {
+                    distributed::graphql::__effect_assignment::<#marker, _>(#value)
+                }
+            })
+            .collect()
+    }
+}
+
+enum ValueExpression {
+    Input(Vec<InputPathSegment>),
+    Trusted(syn::LitStr),
+    Null,
+    Constant(Expr),
+    Literal(Lit),
+}
+
+struct InputPathSegment {
+    field: Ident,
+    /// Required on every non-leaf segment so the macro can name the next
+    /// derive-generated marker without runtime reflection.
+    nested_type: Option<Path>,
+}
+
+impl Parse for ValueExpression {
+    fn parse(stream: ParseStream<'_>) -> Result<Self> {
+        if stream.peek(Lit) {
+            return Ok(Self::Literal(stream.parse()?));
+        }
+        let function_or_input: Ident = stream.parse()?;
+        if function_or_input == "input" {
+            return Ok(Self::Input(parse_input_path(stream)?));
+        }
+
+        let arguments;
+        parenthesized!(arguments in stream);
+        match function_or_input.to_string().as_str() {
+            "uuid_v7" => {
+                if !arguments.is_empty() {
+                    return Err(arguments.error("uuid_v7() takes no arguments"));
+                }
+                Err(syn::Error::new(
+                    function_or_input.span(),
+                    "uuid_v7() cannot be used as an anonymous effect value; declare `default input.field = uuid_v7()` with command_input_defaults! and reference `input.field`",
+                ))
+            }
+            "ulid" => {
+                if !arguments.is_empty() {
+                    return Err(arguments.error("ulid() takes no arguments"));
+                }
+                Err(syn::Error::new(
+                    function_or_input.span(),
+                    "ulid() cannot be used as an anonymous effect value; declare `default input.field = ulid()` with command_input_defaults! and reference `input.field`",
+                ))
+            }
+            "null" => {
+                if !arguments.is_empty() {
+                    return Err(arguments.error("null() takes no arguments"));
+                }
+                Ok(Self::Null)
+            }
+            "constant" => {
+                let value: Expr = arguments.parse()?;
+                if !arguments.is_empty() {
+                    return Err(arguments.error("constant() accepts exactly one Rust expression"));
+                }
+                validate_constant_expression(&value)?;
+                Ok(Self::Constant(value))
+            }
+            "trusted" => {
+                let name: syn::LitStr = arguments.parse()?;
+                if !arguments.is_empty() {
+                    return Err(arguments.error("trusted() accepts exactly one string literal"));
+                }
+                let value = name.value();
+                if value.is_empty()
+                    || value.len() > 128
+                    || value.trim() != value
+                    || value.chars().any(char::is_control)
+                {
+                    return Err(syn::Error::new(
+                        name.span(),
+                        "trusted() preset name must be 1..=128 bytes, have no surrounding whitespace, and contain no control characters",
+                    ));
+                }
+                Ok(Self::Trusted(name))
+            }
+            other => Err(syn::Error::new(
+                function_or_input.span(),
+                format!(
+                    "unknown command-effect expression `{other}`; use input.field, a literal, constant(value), or null()"
+                ),
+            )),
+        }
+    }
+}
+
+impl ValueExpression {
+    fn expand(self, input: &Path) -> TokenStream {
+        match self {
+            Self::Input(segments) => {
+                let first = &segments[0].field;
+                let marker_name = format_ident!(
+                    "__Distributed{}EffectInputField_{}",
+                    input.segments.last().unwrap().ident,
+                    first,
+                    span = first.span()
+                );
+                let root_marker = marker_path(input, marker_name);
+                let mut marker = quote! { #root_marker };
+                for pair in segments.windows(2) {
+                    let nested_type = pair[0]
+                        .nested_type
+                        .as_ref()
+                        .expect("parser requires a type on non-leaf input segments");
+                    let field = &pair[1].field;
+                    let marker_name = format_ident!(
+                        "__Distributed{}EffectInputField_{}",
+                        nested_type.segments.last().unwrap().ident,
+                        field,
+                        span = field.span()
+                    );
+                    let nested_marker = marker_path(nested_type, marker_name);
+                    marker = quote! {
+                        distributed::graphql::EffectInputPath<#marker, #nested_marker>
+                    };
+                }
+                quote! { distributed::graphql::__effect_input::<#input, #marker>() }
+            }
+            Self::Trusted(name) => quote! {
+                distributed::graphql::__effect_trusted(#name)
+            },
+            Self::Null => quote! {
+                distributed::graphql::__effect_null()
+            },
+            Self::Constant(Expr::Lit(value)) if matches!(value.lit, Lit::Str(_)) => {
+                let Lit::Str(value) = value.lit else { unreachable!() };
+                quote! {
+                    distributed::graphql::__effect_constant(::std::string::String::from(#value))
+                }
+            }
+            Self::Constant(value @ Expr::Path(_)) => quote! {
+                distributed::graphql::__effect_constant(const { #value })
+            },
+            Self::Constant(value) => quote! {
+                distributed::graphql::__effect_constant(#value)
+            },
+            Self::Literal(Lit::Str(value)) => quote! {
+                distributed::graphql::__effect_constant(::std::string::String::from(#value))
+            },
+            Self::Literal(Lit::Bool(value)) => quote! {
+                distributed::graphql::__effect_constant(#value)
+            },
+            Self::Literal(Lit::Int(value)) => quote! {
+                distributed::graphql::__effect_constant(#value)
+            },
+            Self::Literal(Lit::Float(value)) => quote! {
+                distributed::graphql::__effect_constant(#value)
+            },
+            Self::Literal(other) => syn::Error::new_spanned(
+                other,
+                "only string, boolean, integer, and float literals are supported in command effects",
+            )
+            .to_compile_error(),
+        }
+    }
+}
+
+fn parse_input_path(stream: ParseStream<'_>) -> Result<Vec<InputPathSegment>> {
+    stream.parse::<Token![.]>()?;
+    let mut segments = Vec::new();
+    loop {
+        let field: Ident = stream.parse()?;
+        let nested_type = if stream.peek(Token![<]) {
+            stream.parse::<Token![<]>()?;
+            let nested_type = stream.parse()?;
+            stream.parse::<Token![>]>()?;
+            Some(nested_type)
+        } else {
+            None
+        };
+        let continues = stream.peek(Token![.]);
+        if continues && nested_type.is_none() {
+            return Err(syn::Error::new(
+                field.span(),
+                "nested input paths require the nested Rust type after each parent field, for example `input.profile<ProfileInput>.display_name`",
+            ));
+        }
+        if !continues && nested_type.is_some() {
+            return Err(syn::Error::new(
+                field.span(),
+                "a nested input type annotation must be followed by another field segment",
+            ));
+        }
+        segments.push(InputPathSegment { field, nested_type });
+        if !continues {
+            break;
+        }
+        stream.parse::<Token![.]>()?;
+    }
+    Ok(segments)
+}
+
+fn validate_constant_expression(expression: &Expr) -> Result<()> {
+    match expression {
+        Expr::Path(path)
+            if path.qself.is_none()
+                && path
+                    .path
+                    .segments
+                    .iter()
+                    .all(|segment| segment.arguments.is_empty()) =>
+        {
+            Ok(())
+        }
+        Expr::Lit(literal)
+            if matches!(
+                literal.lit,
+                Lit::Str(_) | Lit::Bool(_) | Lit::Int(_) | Lit::Float(_)
+            ) =>
+        {
+            Ok(())
+        }
+        Expr::Unary(unary)
+            if matches!(unary.op, syn::UnOp::Neg(_))
+                && matches!(
+                    unary.expr.as_ref(),
+                    Expr::Lit(literal)
+                        if matches!(literal.lit, Lit::Int(_) | Lit::Float(_))
+                ) =>
+        {
+            Ok(())
+        }
+        _ => Err(syn::Error::new_spanned(
+            expression,
+            "constant(...) accepts only a primitive literal (including a negative numeric literal) or a const/enum path; calls, macros, blocks, and other operators are not deterministic command-effect IR",
+        )),
+    }
+}
+
+fn marker_path(base: &Path, marker: Ident) -> Path {
+    let mut path = base.clone();
+    path.segments
+        .last_mut()
+        .expect("syn paths always contain at least one segment")
+        .ident = marker;
+    path
+}
diff --git a/distributed_macros/src/digest.rs b/distributed_macros/src/digest.rs
new file mode 100644
index 00000000..523ab731
--- /dev/null
+++ b/distributed_macros/src/digest.rs
@@ -0,0 +1,90 @@
+use proc_macro2::TokenStream as TokenStream2;
+use quote::{format_ident, quote};
+use syn::{parse::Parser, Expr, Ident, ItemFn, LitStr, Token};
+
+use crate::shared::{
+    ensure_sourced_result_signature, extract_params_with_types, generate_digest_call,
+    wrap_result_body_with_guard,
+};
+
+pub(crate) fn expand_digest(attr: TokenStream2, item: TokenStream2) -> syn::Result<TokenStream2> {
+    let args = parse_digest_args.parse2(attr)?;
+    let mut func = syn::parse2::<ItemFn>(item)?;
+
+    let signature_synthesized = ensure_sourced_result_signature(&mut func.sig, "digest")?;
+
+    let params = extract_params_with_types(&func.sig, "digest")?;
+    let param_names: Vec<&Ident> = params.iter().map(|(name, _)| name).collect();
+    let digest_call = generate_digest_call(
+        &args.entity_field,
+        &args.event_name,
+        &param_names,
+        args.version.as_ref(),
+    );
+
+    let new_body = wrap_result_body_with_guard(
+        args.guard.as_ref(),
+        digest_call,
+        &func.block,
+        signature_synthesized,
+    );
+    *func.block = new_body;
+
+    Ok(quote! { #func })
+}
+
+pub(crate) struct DigestArgs {
+    pub(crate) entity_field: syn::Ident,
+    event_name: LitStr,
+    pub(crate) guard: Option<Expr>,
+    pub(crate) version: Option<syn::LitInt>,
+}
+
+pub(crate) fn parse_digest_args(input: syn::parse::ParseStream) -> syn::Result<DigestArgs> {
+    // Check if first token is an identifier (potential entity field) or a string literal (event name)
+    let (entity_field, event_name) = if input.peek(LitStr) {
+        // No entity field specified, use default "entity"
+        let event_name: LitStr = input.parse()?;
+        (format_ident!("entity"), event_name)
+    } else {
+        // First token is an identifier - could be entity field or event name follows
+        let first_ident: syn::Ident = input.parse()?;
+        input.parse::<Token![,]>()?;
+        let event_name: LitStr = input.parse()?;
+        (first_ident, event_name)
+    };
+
+    let mut guard = None;
+    let mut version = None;
+
+    // Parse optional keyword arguments: `when = condition`, `version = N`
+    while input.peek(Token![,]) {
+        input.parse::<Token![,]>()?;
+        // Allow (and ignore) a trailing comma.
+        if input.is_empty() {
+            break;
+        }
+        let ident: syn::Ident = input.parse()?;
+        if ident == "when" {
+            input.parse::<Token![=]>()?;
+            guard = Some(input.parse()?);
+        } else if ident == "version" {
+            input.parse::<Token![=]>()?;
+            version = Some(input.parse()?);
+        } else {
+            return Err(syn::Error::new_spanned(
+                &ident,
+                format!(
+                    "unsupported key `{ident}` in #[digest(...)]; expected `when` or `version`"
+                ),
+            ));
+        }
+    }
+
+    Ok(DigestArgs {
+        entity_field,
+        event_name,
+        guard,
+        version,
+    })
+}
diff --git a/distributed_macros/src/enqueue.rs b/distributed_macros/src/enqueue.rs
new file mode 100644
index 00000000..7ebf88a1
--- /dev/null
+++ b/distributed_macros/src/enqueue.rs
@@ -0,0 +1,114 @@
+use proc_macro2::TokenStream as TokenStream2;
+use quote::{format_ident, quote};
+use syn::{parse::Parser, Expr, Ident, ItemFn, LitStr, Token};
+
+use crate::shared::{
+    ensure_sourced_result_signature, extract_params_with_types, wrap_result_body_with_guard,
+};
+
+pub(crate) fn expand_enqueue(attr: TokenStream2, item: TokenStream2) -> syn::Result<TokenStream2> {
+    let args = parse_enqueue_args.parse2(attr)?;
+    let mut func = syn::parse2::<ItemFn>(item)?;
+
+    let signature_synthesized = ensure_sourced_result_signature(&mut func.sig, "enqueue")?;
+
+    let emitter_field = &args.emitter_field;
+    let event_name = &args.event_name;
+
+    // Use function parameters - serialize as tuple to JSON
+    let params = extract_params_with_types(&func.sig, "enqueue")?;
+    let param_names: Vec<&Ident> = params.iter().map(|(name, _)| name).collect();
+
+    let entity_field = &args.entity_field;
+
+    let enqueue_call = if param_names.is_empty() {
+        quote! {
+            if !self.#entity_field.is_replaying() {
+                self.#emitter_field.enqueue(#event_name, "");
+            };
+        }
+    } else if param_names.len() == 1 {
+        // Single-element tuple needs trailing comma: (x,) not (x)
+        let param = &param_names[0];
+        quote! {
+            if !self.#entity_field.is_replaying() {
+                self.#emitter_field.enqueue_with(#event_name, &(#param.clone(),))?;
+            };
+        }
+    } else {
+        // Multi-element tuple
+        quote! {
+            if !self.#entity_field.is_replaying() {
+                self.#emitter_field.enqueue_with(#event_name, &(#(#param_names.clone()),*))?;
+            };
+        }
+    };
+
+    let new_body = wrap_result_body_with_guard(
+        args.guard.as_ref(),
+        enqueue_call,
+        &func.block,
+        signature_synthesized,
+    );
+    *func.block = new_body;
+
+    Ok(quote! { #func })
+}
+
+pub(crate) struct EnqueueArgs {
+    pub(crate) emitter_field: syn::Ident,
+    pub(crate) entity_field: syn::Ident,
+    event_name: LitStr,
+    guard: Option<Expr>,
+}
+
+pub(crate) fn parse_enqueue_args(input: syn::parse::ParseStream) -> syn::Result<EnqueueArgs> {
+    // Check if first token is an identifier (potential emitter field) or a string literal (event name)
+    let (emitter_field, event_name) = if input.peek(LitStr) {
+        // No emitter field specified, use default "emitter"
+        let event_name: LitStr = input.parse()?;
+        (format_ident!("emitter"), event_name)
+    } else {
+        // First token is an identifier - emitter field name, event name follows
+        let first_ident: syn::Ident = input.parse()?;
+        input.parse::<Token![,]>()?;
+        let event_name: LitStr = input.parse()?;
+        (first_ident, event_name)
+    };
+
+    let mut guard = None;
+    // Defaults to the conventional `entity` field; overridable so a renamed
+    // entity field still produces a correct `is_replaying()` guard.
+    let mut entity_field = format_ident!("entity");
+
+    // Parse optional keyword arguments: `when = condition`, `entity = field`
+    while input.peek(Token![,]) {
+        input.parse::<Token![,]>()?;
+        // Allow (and ignore) a trailing comma.
+        if input.is_empty() {
+            break;
+        }
+        let ident: syn::Ident = input.parse()?;
+        if ident == "when" {
+            input.parse::<Token![=]>()?;
+            guard = Some(input.parse()?);
+        } else if ident == "entity" {
+            input.parse::<Token![=]>()?;
+            entity_field = input.parse()?;
+        } else {
+            return Err(syn::Error::new_spanned(
+                &ident,
+                format!(
+                    "unsupported key `{ident}` in #[enqueue(...)]; expected `when` or `entity`"
+                ),
+            ));
+        }
+    }
+
+    Ok(EnqueueArgs {
+        emitter_field,
+        entity_field,
+        event_name,
+        guard,
+    })
+}
diff --git a/distributed_macros/src/entry_tests.rs b/distributed_macros/src/entry_tests.rs
new file mode 100644
index 00000000..3570aa19
--- /dev/null
+++ b/distributed_macros/src/entry_tests.rs
@@ -0,0 +1,312 @@
+#[cfg(test)]
+mod tests {
+    use crate::{aggregate, digest, enqueue, sourced};
+    use quote::quote;
+    use syn::parse::Parser;
+
+    // ---- digest ----------------------------------------------------------
+
+    #[test]
+    fn expand_digest_inserts_digest_call() {
+        let attr = quote! { "initialized" };
+        let item = quote! {
+            fn initialize(&mut self, id: String) {
+                self.id = id;
+            }
+        };
+        let out = digest::expand_digest(attr, item).unwrap().to_string();
+        assert!(out.contains("digest"), "unexpected output: {out}");
+        assert!(out.contains("\"initialized\""), "unexpected output: {out}");
+    }
+
+    #[test]
+    fn parse_digest_args_rejects_unknown_key() {
+        let attr = quote! { "x", versoin = 2 };
+        let err = digest::parse_digest_args
+            .parse2(attr)
+            .err()
+            .expect("unknown key should error");
+        let msg = err.to_string();
+        assert!(msg.contains("unsupported key `versoin`"), "got: {msg}");
+        assert!(msg.contains("version"), "got: {msg}");
+    }
+
+    #[test]
+    fn parse_digest_args_accepts_version_and_when() {
+        let attr = quote! { entity, "renamed", when = true, version = 2 };
+        let args = digest::parse_digest_args.parse2(attr).unwrap();
+        assert_eq!(args.entity_field, "entity");
+        assert!(args.guard.is_some());
+        assert!(args.version.is_some());
+    }
+
+    // ---- enqueue ---------------------------------------------------------
+
+    #[test]
+    fn parse_enqueue_args_defaults_entity_field() {
+        let attr = quote! { "order.initialized" };
+        let args = enqueue::parse_enqueue_args.parse2(attr).unwrap();
+        assert_eq!(args.emitter_field, "emitter");
+        assert_eq!(args.entity_field, "entity");
+    }
+
+    #[test]
+    fn parse_enqueue_args_overrides_entity_field() {
+        let attr = quote! { "order.initialized", entity = state };
+        let args = enqueue::parse_enqueue_args.parse2(attr).unwrap();
+        assert_eq!(args.entity_field, "state");
+    }
+
+    #[test]
+    fn expand_enqueue_uses_renamed_entity_field_in_guard() {
+        let attr = quote! { "order.initialized", entity = state };
+        let item = quote! {
+            fn create(&mut self, id: String) {
+                self.id = id;
+            }
+        };
+        let out = enqueue::expand_enqueue(attr, item).unwrap().to_string();
+        assert!(
+            out.contains("self . state . is_replaying"),
+            "expected renamed entity guard, got: {out}"
+        );
+    }
+
+    #[test]
+    fn parse_enqueue_args_rejects_unknown_key() {
+        let attr = quote! { "x", wen = true };
+        let err = enqueue::parse_enqueue_args
+            .parse2(attr)
+            .err()
+            .expect("unknown key should error");
+        assert!(
+            err.to_string().contains("unsupported key `wen`"),
+            "got: {err}"
+        );
+    }
+
+    // ---- event (parse) ---------------------------------------------------
+
+    #[test]
+    fn parse_event_args_rejects_unknown_key() {
+        let attr = quote! { "completed", wen = true };
+        let err = sourced::parse_event_args
+            .parse2(attr)
+            .err()
+            .expect("unknown key should error");
+        assert!(
+            err.to_string().contains("unsupported key `wen`"),
+            "got: {err}"
+        );
+    }
+
+    // ---- sourced ---------------------------------------------------------
+
+    #[test]
+    fn parse_sourced_args_requires_entity_field() {
+        let attr = quote! {};
+        let err = sourced::parse_sourced_args
+            .parse2(attr)
+            .err()
+            .expect("missing entity should error");
+        assert!(
+            err.to_string().contains("requires the entity field name"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn parse_sourced_args_rejects_unknown_key() {
+        let attr = quote! { entity, evnts = "Foo" };
+        let err = sourced::parse_sourced_args
+            .parse2(attr)
+            .err()
+            .expect("unknown key should error");
+        assert!(
+            err.to_string().contains("unsupported key `evnts`"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn expand_sourced_generates_enum_and_aggregate() {
+        let attr = quote! { entity };
+        let item = quote! {
+            impl Todo {
+                #[event("initialized")]
+                pub fn initialize(&mut self, id: String) {
+                    self.id = id;
+                }
+            }
+        };
+        let out = sourced::expand_sourced(attr, item).unwrap().to_string();
+        assert!(out.contains("enum TodoEvent"), "got: {out}");
+        assert!(
+            out.contains("impl distributed :: Aggregate for Todo"),
+            "got: {out}"
+        );
+    }
+
+    #[test]
+    fn expand_sourced_rejects_duplicate_event_names() {
+        let attr = quote! { entity };
+        let item = quote! {
+            impl Todo {
+                #[event("done")]
+                pub fn complete(&mut self) {}
+                #[event("done")]
+                pub fn finish(&mut self) {}
+            }
+        };
+        let err = sourced::expand_sourced(attr, item).expect_err("duplicate should error");
+        assert!(
+            err.to_string().contains("duplicate #[event] name `done`"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn expand_sourced_rejects_variant_ident_collisions() {
+        let attr = quote! { entity };
+        let item = quote! {
+            impl Workflow {
+                #[event("user.completed")]
+                pub fn user_completed(&mut self) {}
+                #[event("admin.completed")]
+                pub fn admin_completed(&mut self) {}
+            }
+        };
+        let err = sourced::expand_sourced(attr, item).expect_err("variant collision should error");
+        let msg = err.to_string();
+        assert!(msg.contains("`user.completed`"), "got: {msg}");
+        assert!(msg.contains("`admin.completed`"), "got: {msg}");
+        assert!(msg.contains("`Completed`"), "got: {msg}");
+    }
+
+    #[test]
+    fn expand_sourced_rejects_tuple_parameter_pattern() {
+        let attr = quote! { entity };
+        let item = quote! {
+            impl Point {
+                #[event("moved")]
+                pub fn moved(&mut self, (x, y): (u8, u8)) {
+                    self.x = x;
+                    self.y = y;
+                }
+            }
+        };
+        let err = sourced::expand_sourced(attr, item).expect_err("tuple pattern should error");
+        assert!(
+            err.to_string()
+                .contains("unsupported parameter pattern in #[event] method"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn expand_digest_rejects_wildcard_parameter_pattern() {
+        let attr = quote! { "initialized" };
+        let item = quote! {
+            fn initialize(&mut self, _: String) {}
+        };
+        let err = digest::expand_digest(attr, item).expect_err("wildcard pattern should error");
+        assert!(
+            err.to_string()
+                .contains("unsupported parameter pattern in #[digest] method"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn expand_enqueue_rejects_struct_parameter_pattern() {
+        let attr = quote! { "order.initialized" };
+        let item = quote! {
+            fn create(&mut self, Payload { id }: Payload) {
+                let _ = id;
+            }
+        };
+        let err = enqueue::expand_enqueue(attr, item).expect_err("struct pattern should error");
+        assert!(
+            err.to_string()
+                .contains("unsupported parameter pattern in #[enqueue] method"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn expand_sourced_rejects_event_without_receiver() {
+        let attr = quote! { entity };
+        let item = quote! {
+            impl Todo {
+                #[event("initialized")]
+                pub fn initialize(id: String) {}
+            }
+        };
+        let err = sourced::expand_sourced(attr, item).expect_err("missing receiver should error");
+        assert!(
+            err.to_string().contains("must take a `&mut self` receiver"),
+            "got: {err}"
+        );
+    }
+
+    // ---- upcasters -------------------------------------------------------
+
+    /// Both `aggregate!` and `#[sourced]` route through the same
+    /// `UpcasterDef` parser, so one grammar check covers both entry points.
+    #[test]
+    fn upcaster_def_parses_full_entry() {
+        let input = quote! { ("initialized", 1 => 2, OldPayload => NewPayload, upcast_fn) };
+        let def: aggregate::UpcasterDef = syn::parse2(input).unwrap();
+        assert_eq!(def.event_name.value(), "initialized");
+        assert_eq!(def.from_version.base10_parse::<u64>().unwrap(), 1);
+        assert_eq!(def.to_version.base10_parse::<u64>().unwrap(), 2);
+    }
+
+    #[test]
+    fn upcaster_def_rejects_missing_transform_fn() {
+        let input = quote! { ("initialized", 1 => 2, OldPayload => NewPayload) };
+        assert!(syn::parse2::<aggregate::UpcasterDef>(input).is_err());
+    }
+
+    #[test]
+    fn parse_sourced_args_accepts_upcasters() {
+        let attr = quote! {
+            entity,
+            upcasters(("initialized", 1 => 2, OldPayload => NewPayload, upcast_fn))
+        };
+        let args = sourced::parse_sourced_args.parse2(attr).unwrap();
+        assert_eq!(args.upcasters.len(), 1);
+    }
+
+    #[test]
+    fn expand_aggregate_accepts_upcasters_block() {
+        let input = quote! {
+            Todo, entity {
+                "initialized"(id) => initialize,
+            }
+            upcasters [
+                ("initialized", 1 => 2, OldPayload => NewPayload, upcast_fn),
+            ]
+        };
+        let out = aggregate::expand_aggregate(input).unwrap().to_string();
+        assert!(out.contains("upcasters"), "got: {out}");
+        assert!(out.contains("upcast_fn"), "got: {out}");
+    }
+
+    // ---- aggregate -------------------------------------------------------
+
+    #[test]
+    fn expand_aggregate_generates_impl() {
+        let input = quote! {
+            Todo, entity {
+                "initialized"(id) => initialize,
+            }
+        };
+        let out = aggregate::expand_aggregate(input).unwrap().to_string();
+        assert!(
+            out.contains("impl distributed :: Aggregate for Todo"),
+            "got: {out}"
+        );
+        assert!(out.contains("replay_event"), "got: {out}");
+    }
+}
diff --git a/distributed_macros/src/graphql_types.rs b/distributed_macros/src/graphql_types.rs
new file mode 100644
index 00000000..ce9ef976
--- /dev/null
+++ b/distributed_macros/src/graphql_types.rs
@@ -0,0 +1,676 @@
+//! GraphqlInput / GraphqlOutput derive macros.
+
+use proc_macro2::TokenStream;
+use quote::{format_ident, quote};
+use syn::{
+    punctuated::Punctuated, Attribute, Data, DeriveInput, Expr, Fields, GenericArgument, Lit,
+    LitStr, Meta, PathArguments, Token, Type,
+};
+
+#[derive(Clone, Copy)]
+enum SerdeDirection {
+    Deserialize,
+    Serialize,
+}
+
+impl SerdeDirection {
+    fn attribute_name(self) -> &'static str {
+        match self {
+            Self::Deserialize => "deserialize",
+            Self::Serialize => "serialize",
+        }
+    }
+
+    fn derive_name(self) -> &'static str {
+        match self {
+            Self::Deserialize => "GraphqlInput",
+            Self::Serialize => "GraphqlOutput",
+        }
+    }
+}
+
+#[derive(Clone, Copy)]
+enum RenameRule {
+    LowerCase,
+    UpperCase,
+    PascalCase,
+    CamelCase,
+    SnakeCase,
+    ScreamingSnakeCase,
+}
+
+impl RenameRule {
+    fn parse(value: &LitStr) -> syn::Result<Self> {
+        match value.value().as_str() {
+            "lowercase" => Ok(Self::LowerCase),
+            "UPPERCASE" => Ok(Self::UpperCase),
+            "PascalCase" => Ok(Self::PascalCase),
+            "camelCase" => Ok(Self::CamelCase),
+            "snake_case" => Ok(Self::SnakeCase),
+            "SCREAMING_SNAKE_CASE" => Ok(Self::ScreamingSnakeCase),
+            "kebab-case" | "SCREAMING-KEBAB-CASE" => Err(syn::Error::new_spanned(
+                value,
+                "serde kebab-case field names cannot be represented in GraphQL; use camelCase or snake_case",
+            )),
+            other => Err(syn::Error::new_spanned(
+                value,
+                format!(
+                    "unsupported serde rename_all rule `{other}` for GraphqlInput/GraphqlOutput"
+                ),
+            )),
+        }
+    }
+
+    fn apply(self, field: &str) -> String {
+        match self {
+            Self::LowerCase | Self::SnakeCase => field.to_string(),
+            Self::UpperCase | Self::ScreamingSnakeCase => field.to_ascii_uppercase(),
+            Self::PascalCase => {
+                let mut renamed = String::new();
+                let mut capitalize = true;
+                for ch in field.chars() {
+                    if ch == '_' {
+                        capitalize = true;
+                    } else if capitalize {
+                        renamed.push(ch.to_ascii_uppercase());
+                        capitalize = false;
+                    } else {
+                        renamed.push(ch);
+                    }
+                }
+                renamed
+            }
+            Self::CamelCase => {
+                let pascal = Self::PascalCase.apply(field);
+                let mut chars = pascal.chars();
+                chars
+                    .next()
+                    .map(|first| first.to_ascii_lowercase().to_string() + chars.as_str())
+                    .unwrap_or_default()
+            }
+        }
+    }
+}
+
+pub fn expand_graphql_input(input: DeriveInput) -> syn::Result<TokenStream> {
+    expand(
+        input,
+        quote! { distributed::graphql::GraphqlInputType },
+        quote! { distributed::graphql::GraphqlInputType },
+        SerdeDirection::Deserialize,
+    )
+}
+
+pub fn expand_graphql_output(input: DeriveInput) -> syn::Result<TokenStream> {
+    expand(
+        input,
+        quote! { distributed::graphql::GraphqlOutputType },
+        quote! { distributed::graphql::GraphqlOutputType },
+        SerdeDirection::Serialize,
+    )
+}
+
+fn expand(
+    input: DeriveInput,
+    trait_path: TokenStream,
+    nested_trait: TokenStream,
+    serde_direction: SerdeDirection,
+) -> syn::Result<TokenStream> {
+    let name = &input.ident;
+    let visibility = &input.vis;
+    validate_serde_container_shape(&input.attrs, serde_direction)?;
+    let rename_all = serde_rename_all(&input.attrs, serde_direction)?;
+    let Data::Struct(data) = &input.data else {
+        return Err(syn::Error::new_spanned(
+            &input,
+            "GraphqlInput/GraphqlOutput only support structs with named fields",
+        ));
+    };
+    let Fields::Named(fields) = &data.fields else {
+        return Err(syn::Error::new_spanned(
+            &input,
+            "GraphqlInput/GraphqlOutput require named fields",
+        ));
+    };
+
+    let mut field_tokens = Vec::new();
+    let mut effect_input_markers = Vec::new();
+    for field in &fields.named {
+        validate_serde_field_shape(&field.attrs, serde_direction)?;
+        let field_name = field
+            .ident
+            .as_ref()
+            .ok_or_else(|| syn::Error::new_spanned(field, "field must be named"))?;
+        let rust_field_name = field_name.to_string();
+        let rust_field_name = rust_field_name
+            .strip_prefix("r#")
+            .unwrap_or(&rust_field_name);
+        let field_name_str =
+            serde_field_rename(&field.attrs, serde_direction)?.unwrap_or_else(|| {
+                rename_all
+                    .map(|rule| rule.apply(rust_field_name))
+                    .unwrap_or_else(|| rust_field_name.to_string())
+            });
+        validate_graphql_field_name(&field_name_str, field)?;
+        let (type_name, nullable, list, item_nullable, nested) =
+            map_type(&field.ty, field, &nested_trait)?;
+        let effect_path_kind = if !list && nested.is_some() {
+            quote! { distributed::graphql::EffectInputObjectKind }
+        } else {
+            quote! { distributed::graphql::EffectInputTerminalKind }
+        };
+        let effect_wire = effect_input_wire_tokens(&type_name, list, nested.is_some());
+        let nested_tokens = match nested {
+            Some(tokens) => quote! { Some(::std::boxed::Box::new(#tokens)) },
+            None => quote! { None },
+        };
+        field_tokens.push(quote! {
+            distributed::graphql::GraphqlTypeField {
+                name: #field_name_str.to_string(),
+                type_name: #type_name.to_string(),
+                nullable: #nullable,
+                list: #list,
+                item_nullable: #item_nullable,
+                nested: #nested_tokens,
+            }
+        });
+        if matches!(serde_direction, SerdeDirection::Deserialize) {
+            let marker = format_ident!("__Distributed{}EffectInputField_{}", name, field_name);
+            let field_ty = &field.ty;
+            let nested_ty = effect_nested_type(field_ty);
+            let non_null_ty = effect_non_null_type(field_ty);
+            let nullability = if extract_path_arg(field_ty, "Option").is_some() {
+                quote! { distributed::graphql::EffectNullable }
+            } else {
+                quote! { distributed::graphql::EffectRequired }
+            };
+            effect_input_markers.push(quote! {
+                #[doc(hidden)]
+                #[allow(non_camel_case_types)]
+                #visibility struct #marker;
+
+                impl distributed::graphql::EffectInputFieldMarker for #marker {
+                    type Input = #name;
+                    type Value = #field_ty;
+                    type NonNullValue = #non_null_ty;
+                    type Nullability = #nullability;
+                    type PathKind = #effect_path_kind;
+                    type Wire = #effect_wire;
+                    type Nested = #nested_ty;
+                    fn path() -> ::std::vec::Vec<&'static str> {
+                        vec![#field_name_str]
+                    }
+                }
+            });
+        }
+    }
+
+    let type_name_str = name.to_string();
+    Ok(quote! {
+        impl #trait_path for #name {
+            fn graphql_type() -> distributed::graphql::GraphqlTypeDef {
+                distributed::graphql::GraphqlTypeDef::new(
+                    #type_name_str,
+                    vec![#(#field_tokens),*],
+                ).with_type_id(::std::any::TypeId::of::<#name>())
+            }
+        }
+
+        #(#effect_input_markers)*
+    })
+}
+
+fn effect_input_wire_tokens(type_name: &str, list: bool, nested: bool) -> proc_macro2::TokenStream {
+    if list {
+        return quote! { distributed::graphql::EffectWireList };
+    }
+    if nested {
+        return quote! { distributed::graphql::EffectWireObject };
+    }
+    match type_name {
+        "String" | "ID" => quote! { distributed::graphql::EffectWireString },
+        "Boolean" => quote! { distributed::graphql::EffectWireBoolean },
+        "BigInt" | "Int" => quote! { distributed::graphql::EffectWireBigInt },
+        "Float" => quote! { distributed::graphql::EffectWireFloat },
+        "JSON" => quote! { distributed::graphql::EffectWireJson },
+        "Bytea" => quote! { distributed::graphql::EffectWireBytea },
+        "Timestamptz" => quote! { distributed::graphql::EffectWireTimestamp },
+        _ => quote! { distributed::graphql::EffectWireUnsupported },
+    }
+}
+
+fn effect_non_null_type(mut ty: &Type) -> &Type {
+    while let Some(inner) = extract_path_arg(ty, "Option") {
+        ty = inner;
+    }
+    ty
+}
+
+fn effect_nested_type(mut ty: &Type) -> &Type {
+    while let Some(inner) = extract_path_arg(ty, "Option") {
+        ty = inner;
+    }
+    if let Some(inner) = extract_path_arg(ty, "Vec") {
+        ty = inner;
+        while let Some(inner) = extract_path_arg(ty, "Option") {
+            ty = inner;
+        }
+    }
+    ty
+}
+
+fn map_type(
+    ty: &Type,
+    span: &syn::Field,
+    nested_trait: &TokenStream,
+) -> syn::Result<(String, bool, bool, bool, Option<TokenStream>)> {
+    let mut current = ty;
+    let mut nullable = false;
+    while let Some(inner) = extract_path_arg(current, "Option") {
+        nullable = true;
+        current = inner;
+    }
+
+    let mut list = false;
+    let mut item_nullable = false;
+    if let Some(inner) = extract_path_arg(current, "Vec") {
+        list = true;
+        current = inner;
+        while let Some(inner) = extract_path_arg(current, "Option") {
+            item_nullable = true;
+            current = inner;
+        }
+        if extract_path_arg(current, "Vec").is_some() {
+            return Err(syn::Error::new_spanned(
+                ty,
+                "nested lists are not supported for GraphqlInput/GraphqlOutput fields",
+            ));
+        }
+    }
+
+    let path = match current {
+        Type::Path(p) => p,
+        _ => {
+            return Err(syn::Error::new_spanned(
+                span,
+                "unsupported field type for GraphqlInput/GraphqlOutput",
+            ));
+        }
+    };
+    let last = path
+        .path
+        .segments
+        .last()
+        .ok_or_else(|| syn::Error::new_spanned(span, "empty type path"))?;
+    let ident = last.ident.to_string();
+
+    let scalar = match ident.as_str() {
+        "String" | "str" => Some("String"),
+        "bool" => Some("Boolean"),
+        "i8" | "i16" | "i32" | "i64" | "u8" | "u16" | "u32" | "u64" | "isize" | "usize" => {
+            Some("BigInt")
+        }
+        "f32" | "f64" => Some("Float"),
+        "Value" => Some("JSON"),
+        _ => None,
+    };
+
+    if let Some(s) = scalar {
+        return Ok((s.to_string(), nullable, list, item_nullable, None));
+    }
+
+    let nested = quote! { <#current as #nested_trait>::graphql_type() };
+    Ok((ident, nullable, list, item_nullable, Some(nested)))
+}
+
+fn extract_path_arg<'a>(ty: &'a Type, wrapper: &str) -> Option<&'a Type> {
+    let Type::Path(path) = ty else {
+        return None;
+    };
+    let seg = path.path.segments.last()?;
+    if seg.ident != wrapper {
+        return None;
+    }
+    let PathArguments::AngleBracketed(args) = &seg.arguments else {
+        return None;
+    };
+    args.args.iter().find_map(|arg| match arg {
+        GenericArgument::Type(t) => Some(t),
+        _ => None,
+    })
+}
+
+fn serde_rename_all(
+    attrs: &[Attribute],
+    direction: SerdeDirection,
+) -> syn::Result<Option<RenameRule>> {
+    let value = serde_name_value(attrs, "rename_all", direction)?;
+    value.as_ref().map(RenameRule::parse).transpose()
+}
+
+fn validate_serde_field_shape(attrs: &[Attribute], direction: SerdeDirection) -> syn::Result<()> {
+    for attr in attrs.iter().filter(|attr| attr.path().is_ident("serde")) {
+        let metas = attr.parse_args_with(Punctuated::<Meta, Token![,]>::parse_terminated)?;
+        for meta in metas {
+            let unsupported = match &meta {
+                Meta::Path(path) if path.is_ident("skip") => Some("skip"),
+                Meta::Path(path)
+                    if path.is_ident("skip_deserializing")
+                        && matches!(direction, SerdeDirection::Deserialize) =>
+                {
+                    Some("skip_deserializing")
+                }
+                Meta::Path(path)
+                    if path.is_ident("skip_serializing")
+                        && matches!(direction, SerdeDirection::Serialize) =>
+                {
+                    Some("skip_serializing")
+                }
+                Meta::NameValue(name_value)
+                    if name_value.path.is_ident("skip_serializing_if")
+                        && matches!(direction, SerdeDirection::Serialize) =>
+                {
+                    Some("skip_serializing_if")
+                }
+                Meta::Path(path) if path.is_ident("flatten") => Some("flatten"),
+                Meta::Path(path)
+                    if path.is_ident("default")
+                        && matches!(direction, SerdeDirection::Deserialize) =>
+                {
+                    Some("default")
+                }
+                Meta::NameValue(name_value)
+                    if name_value.path.is_ident("default")
+                        && matches!(direction, SerdeDirection::Deserialize) =>
+                {
+                    Some("default")
+                }
+                Meta::NameValue(name_value) if name_value.path.is_ident("with") => Some("with"),
+                Meta::NameValue(name_value)
+                    if name_value.path.is_ident("deserialize_with")
+                        && matches!(direction, SerdeDirection::Deserialize) =>
+                {
+                    Some("deserialize_with")
+                }
+                Meta::NameValue(name_value)
+                    if name_value.path.is_ident("serialize_with")
+                        && matches!(direction, SerdeDirection::Serialize) =>
+                {
+                    Some("serialize_with")
+                }
+                Meta::NameValue(name_value)
+                    if name_value.path.is_ident("alias")
+                        && matches!(direction, SerdeDirection::Deserialize) =>
+                {
+                    Some("alias")
+                }
+                _ => None,
+            };
+            if let Some(attribute) = unsupported {
+                return Err(syn::Error::new_spanned(
+                    meta,
+                    format!(
+                        "#[serde({attribute})] is not supported by {} because it changes the declared GraphQL field shape; define a separate wire type",
+                        direction.derive_name(),
+                    ),
+                ));
+            }
+        }
+    }
+    Ok(())
+}
+
+fn validate_serde_container_shape(
+    attrs: &[Attribute],
+    direction: SerdeDirection,
+) -> syn::Result<()> {
+    for attr in attrs.iter().filter(|attr| attr.path().is_ident("serde")) {
+        let metas = attr.parse_args_with(Punctuated::<Meta, Token![,]>::parse_terminated)?;
+        for meta in metas {
+            let unsupported = match &meta {
+                Meta::Path(path) if path.is_ident("transparent") => Some("transparent"),
+                Meta::Path(path) if path.is_ident("untagged") => Some("untagged"),
+                Meta::NameValue(name_value)
+                    if name_value.path.is_ident("tag") || name_value.path.is_ident("content") =>
+                {
+                    Some(if name_value.path.is_ident("tag") {
+                        "tag"
+                    } else {
+                        "content"
+                    })
+                }
+                Meta::Path(path)
+                    if path.is_ident("default")
+                        && matches!(direction, SerdeDirection::Deserialize) =>
+                {
+                    Some("default")
+                }
+                Meta::NameValue(name_value)
+                    if name_value.path.is_ident("default")
+                        && matches!(direction, SerdeDirection::Deserialize) =>
+                {
+                    Some("default")
+                }
+                Meta::NameValue(name_value)
+                    if (name_value.path.is_ident("from")
+                        || name_value.path.is_ident("try_from"))
+                        && matches!(direction, SerdeDirection::Deserialize) =>
+                {
+                    Some(if name_value.path.is_ident("from") {
+                        "from"
+                    } else {
+                        "try_from"
+                    })
+                }
+                Meta::NameValue(name_value)
+                    if name_value.path.is_ident("into")
+                        && matches!(direction, SerdeDirection::Serialize) =>
+                {
+                    Some("into")
+                }
+                _ => None,
+            };
+            if let Some(attribute) = unsupported {
+                return Err(syn::Error::new_spanned(
+                    meta,
+                    format!(
+                        "#[serde({attribute})] is not supported by {} because it changes the declared GraphQL object shape; define a separate wire type",
+                        direction.derive_name(),
+                    ),
+                ));
+            }
+        }
+    }
+    Ok(())
+}
+
+fn serde_field_rename(
+    attrs: &[Attribute],
+    direction: SerdeDirection,
+) -> syn::Result<Option<String>> {
+    Ok(serde_name_value(attrs, "rename", direction)?.map(|value| value.value()))
+}
+
+fn serde_name_value(
+    attrs: &[Attribute],
+    key: &str,
+    direction: SerdeDirection,
+) -> syn::Result<Option<LitStr>> {
+    let mut found = None;
+    for attr in attrs.iter().filter(|attr| attr.path().is_ident("serde")) {
+        let metas = attr.parse_args_with(Punctuated::<Meta, Token![,]>::parse_terminated)?;
+        for meta in metas {
+            match meta {
+                Meta::NameValue(name_value) if name_value.path.is_ident(key) => {
+                    set_serde_name(&mut found, string_literal(&name_value.value, key)?, key)?;
+                }
+                Meta::List(list) if list.path.is_ident(key) => {
+                    let directional =
+                        list.parse_args_with(Punctuated::<Meta, Token![,]>::parse_terminated)?;
+                    for meta in directional {
+                        if let Meta::NameValue(name_value) = meta {
+                            if name_value.path.is_ident(direction.attribute_name()) {
+                                set_serde_name(
+                                    &mut found,
+                                    string_literal(&name_value.value, key)?,
+                                    key,
+                                )?;
+                            }
+                        }
+                    }
+                }
+                _ => {}
+            }
+        }
+    }
+    Ok(found)
+}
+
+fn set_serde_name(found: &mut Option<LitStr>, value: LitStr, key: &str) -> syn::Result<()> {
+    if found.is_some() {
+        return Err(syn::Error::new_spanned(
+            value,
+            format!("duplicate serde `{key}` rule for GraphqlInput/GraphqlOutput"),
+        ));
+    }
+    *found = Some(value);
+    Ok(())
+}
+
+fn string_literal(value: &Expr, key: &str) -> syn::Result<LitStr> {
+    match value {
+        Expr::Lit(expr) => match &expr.lit {
+            Lit::Str(value) => Ok(value.clone()),
+            _ => Err(syn::Error::new_spanned(
+                value,
+                format!("serde `{key}` must be a string literal"),
+            )),
+        },
+        _ => Err(syn::Error::new_spanned(
+            value,
+            format!("serde `{key}` must be a string literal"),
+        )),
+    }
+}
+
+fn validate_graphql_field_name(name: &str, span: &syn::Field) -> syn::Result<()> {
+    let mut chars = name.chars();
+    let first_valid = match chars.next() {
+        Some('_') => !name.starts_with("__"),
+        Some(first) => first.is_ascii_alphabetic(),
+        None => false,
+    };
+    if first_valid && chars.all(|ch| ch.is_ascii_alphanumeric() || ch == '_') {
+        return Ok(());
+    }
+    Err(syn::Error::new_spanned(
+        span,
+        format!(
+            "serde field name `{name}` is not a valid GraphQL name; use #[serde(rename = \"valid_name\")]"
+        ),
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn graphql_safe_rename_all_rules_match_serde_field_rules() {
+        let field = "long_field_name";
+        let cases = [
+            ("lowercase", "long_field_name"),
+            ("UPPERCASE", "LONG_FIELD_NAME"),
+            ("PascalCase", "LongFieldName"),
+            ("camelCase", "longFieldName"),
+            ("snake_case", "long_field_name"),
+            ("SCREAMING_SNAKE_CASE", "LONG_FIELD_NAME"),
+        ];
+        for (rule, expected) in cases {
+            let literal = LitStr::new(rule, proc_macro2::Span::call_site());
+            assert_eq!(RenameRule::parse(&literal).unwrap().apply(field), expected);
+        }
+    }
+
+    #[test]
+    fn directional_serde_names_follow_wire_direction() {
+        let input: DeriveInput = syn::parse_quote! {
+            #[serde(rename_all(deserialize = "camelCase", serialize = "SCREAMING_SNAKE_CASE"))]
+            struct CommandInput {
+                regular_field: String,
+                #[serde(rename(deserialize = "inputID", serialize = "OUTPUT_ID"))]
+                custom_id: String,
+            }
+        };
+        let input_tokens = expand_graphql_input(input).unwrap().to_string();
+        assert!(input_tokens.contains("\"regularField\""));
+        assert!(input_tokens.contains("\"inputID\""));
+
+        let output: DeriveInput = syn::parse_quote! {
+            #[serde(rename_all(deserialize = "camelCase", serialize = "SCREAMING_SNAKE_CASE"))]
+            struct CommandOutput {
+                regular_field: String,
+                #[serde(rename(deserialize = "inputID", serialize = "OUTPUT_ID"))]
+                custom_id: String,
+            }
+        };
+        let output_tokens = expand_graphql_output(output).unwrap().to_string();
+        assert!(output_tokens.contains("\"REGULAR_FIELD\""));
+        assert!(output_tokens.contains("\"OUTPUT_ID\""));
+    }
+
+    #[test]
+    fn nested_lists_and_shape_changing_serde_attrs_fail_closed() {
+        let nested: DeriveInput = syn::parse_quote! {
+            struct Nested { values: Option<Vec<Option<Vec<String>>>> }
+        };
+        let error = expand_graphql_input(nested).unwrap_err().to_string();
+        assert!(error.contains("nested lists are not supported"), "{error}");
+
+        let skipped: DeriveInput = syn::parse_quote! {
+            struct Skipped {
+                #[serde(skip_deserializing)]
+                value: String,
+            }
+        };
+        let error = expand_graphql_input(skipped).unwrap_err().to_string();
+        assert!(
+            error.contains("changes the declared GraphQL field shape"),
+            "{error}"
+        );
+
+        let defaulted: DeriveInput = syn::parse_quote! {
+            struct Defaulted {
+                #[serde(default)]
+                value: String,
+            }
+        };
+        let error = expand_graphql_input(defaulted).unwrap_err().to_string();
+        assert!(error.contains("#[serde(default)]"), "{error}");
+
+        let custom: DeriveInput = syn::parse_quote! {
+            struct Custom {
+                #[serde(deserialize_with = "decode_value")]
+                value: String,
+            }
+        };
+        let error = expand_graphql_input(custom).unwrap_err().to_string();
+        assert!(error.contains("#[serde(deserialize_with)]"), "{error}");
+
+        let transparent: DeriveInput = syn::parse_quote! {
+            #[serde(transparent)]
+            struct Transparent { value: String }
+        };
+        let error = expand_graphql_output(transparent).unwrap_err().to_string();
+        assert!(error.contains("#[serde(transparent)]"), "{error}");
+
+        let container_default: DeriveInput = syn::parse_quote! {
+            #[serde(default = "default_input")]
+            struct ContainerDefault { value: String }
+        };
+        let error = expand_graphql_input(container_default)
+            .unwrap_err()
+            .to_string();
+        assert!(error.contains("#[serde(default)]"), "{error}");
+    }
+}
diff --git a/distributed_macros/src/lib.rs b/distributed_macros/src/lib.rs
index 25bf9ce9..11392161 100644
--- a/distributed_macros/src/lib.rs
+++ b/distributed_macros/src/lib.rs
@@ -1,1423 +1,50 @@
+mod aggregate;
+mod command_effects;
+mod digest;
+mod enqueue;
+mod graphql_types;
 mod read_model;
+mod shared;
 mod snapshot;
+mod sourced;
 
 use proc_macro::TokenStream;
-use proc_macro2::TokenStream as TokenStream2;
-use quote::{format_ident, quote};
-use syn::{
-    braced,
-    parse::{Parse, ParseStream, Parser},
-    Expr, FnArg, Ident, ItemFn, ItemImpl, LitStr, Pat, ReturnType, Token, Type,
-};
-
-// ============================================================================
-// Shared helpers
-// ============================================================================
-
-/// Extract parameter names and types from a method signature (excludes `self`).
-///
-/// Every parameter must be a plain identifier: its name is recorded in the
-/// event payload and used to call the method again on replay. A pattern like
-/// `(a, b): (u8, u8)` or `_: String` has no single name, so silently skipping
-/// it would drop the parameter from the payload and make the generated replay
-/// arm call the method with too few arguments — an arity error pointing at
-/// generated code, far from the cause. Reject it here with a spanned error.
-fn extract_params_with_types(
-    sig: &syn::Signature,
-    attr_name: &str,
-) -> syn::Result<Vec<(Ident, syn::Type)>> {
-    sig.inputs
-        .iter()
-        .filter_map(|arg| match arg {
-            FnArg::Typed(pat_type) => Some(pat_type),
-            FnArg::Receiver(_) => None,
-        })
-        .map(|pat_type| match &*pat_type.pat {
-            Pat::Ident(pat_ident) => Ok((pat_ident.ident.clone(), (*pat_type.ty).clone())),
-            other => Err(syn::Error::new_spanned(
-                other,
-                format!(
-                    "unsupported parameter pattern in #[{attr_name}] method — use a plain identifier"
-                ),
-            )),
-        })
-        .collect()
-}
-
-fn returns_result(sig: &syn::Signature) -> bool {
-    match &sig.output {
-        ReturnType::Default => false,
-        ReturnType::Type(_, ty) => match ty.as_ref() {
-            Type::Path(path) => path.path.segments.last().is_some_and(|segment| {
-                segment.ident == "Result" || segment.ident == "SourcedResult"
-            }),
-            _ => false,
-        },
-    }
-}
-
-fn ensure_sourced_result_signature(
-    sig: &mut syn::Signature,
-    attr_name: &str,
-) -> Result<bool, syn::Error> {
-    match &sig.output {
-        ReturnType::Default => {
-            sig.output = syn::parse_quote!(-> distributed::SourcedResult<()>);
-            Ok(true)
-        }
-        ReturnType::Type(_, _) if returns_result(sig) => Ok(false),
-        ReturnType::Type(_, ty) => Err(syn::Error::new_spanned(
-            ty,
-            format!(
-                "#[{}] methods must return Result<(), E>, SourcedResult, or omit the return type",
-                attr_name
-            ),
-        )),
-    }
-}
-
-/// Generate a digest call token stream.
-fn generate_digest_call(
-    entity_field: &Ident,
-    event_name: &LitStr,
-    param_names: &[&Ident],
-    version: Option<&syn::LitInt>,
-) -> proc_macro2::TokenStream {
-    match version {
-        Some(ver) => {
-            if param_names.is_empty() {
-                quote! { self.#entity_field.digest_v(#event_name, #ver, &())?; }
-            } else if param_names.len() == 1 {
-                let param = param_names[0];
-                quote! { self.#entity_field.digest_v(#event_name, #ver, &(#param.clone(),))?; }
-            } else {
-                quote! { self.#entity_field.digest_v(#event_name, #ver, &(#(#param_names.clone()),*))?; }
-            }
-        }
-        None => {
-            if param_names.is_empty() {
-                quote! { self.#entity_field.digest_empty(#event_name)?; }
-            } else if param_names.len() == 1 {
-                let param = param_names[0];
-                quote! { self.#entity_field.digest(#event_name, &(#param.clone(),))?; }
-            } else {
-                quote! { self.#entity_field.digest(#event_name, &(#(#param_names.clone()),*))?; }
-            }
-        }
-    }
-}
-
-/// Wrap a `Result<(), E>` command method with an optional guard and fallible prelude.
-fn wrap_result_body_with_guard(
-    guard: Option<&Expr>,
-    prepend: proc_macro2::TokenStream,
-    original_block: &syn::Block,
-    signature_synthesized: bool,
-) -> syn::Block {
-    match (guard, signature_synthesized) {
-        (Some(guard), true) => {
-            syn::parse_quote! {
-                {
-                    if #guard {
-                        #prepend
-                        #original_block;
-                    }
-                    Ok(())
-                }
-            }
-        }
-        (Some(guard), false) => {
-            syn::parse_quote! {
-                {
-                    if #guard {
-                        #prepend
-                        (|| #original_block)()?;
-                    }
-                    Ok(())
-                }
-            }
-        }
-        (None, true) => {
-            syn::parse_quote! {
-                {
-                    #prepend
-                    #original_block;
-                    Ok(())
-                }
-            }
-        }
-        (None, false) => {
-            syn::parse_quote! {
-                {
-                    #prepend
-                    (|| #original_block)()?;
-                    Ok(())
-                }
-            }
-        }
-    }
-}
-
-/// Generate an enqueue call token stream (for use within `#[sourced]`).
-fn generate_enqueue_call(
-    entity_field: &Ident,
-    emitter_field: &Ident,
-    event_name: &LitStr,
-    param_names: &[&Ident],
-) -> proc_macro2::TokenStream {
-    let enqueue_expr = if param_names.is_empty() {
-        quote! { self.#emitter_field.enqueue(#event_name, ""); }
-    } else if param_names.len() == 1 {
-        let param = param_names[0];
-        quote! { self.#emitter_field.enqueue_with(#event_name, &(#param.clone(),))?; }
-    } else {
-        quote! { self.#emitter_field.enqueue_with(#event_name, &(#(#param_names.clone()),*))?; }
-    };
-    quote! {
-        if !self.#entity_field.is_replaying() {
-            #enqueue_expr
-        };
-    }
-}
-
-fn upcaster_wrapper_prefix(owner: &Ident) -> String {
-    owner
-        .to_string()
-        .trim_start_matches("r#")
-        .to_ascii_lowercase()
-}
-
-fn event_variant_ident(event_name: &LitStr) -> Ident {
-    let value = event_name.value();
-    let segment = value
-        .rsplit('.')
-        .find(|part| !part.is_empty())
-        .unwrap_or(&value);
-    let mut ident = String::new();
-    let mut capitalize_next = true;
-
-    for ch in segment.chars() {
-        if ch.is_ascii_alphanumeric() {
-            if ident.is_empty() && ch.is_ascii_digit() {
-                ident.push_str("Event");
-            }
-
-            if capitalize_next {
-                ident.push(ch.to_ascii_uppercase());
-                capitalize_next = false;
-            } else {
-                ident.push(ch);
-            }
-        } else {
-            capitalize_next = true;
-        }
-    }
-
-    if ident.is_empty() {
-        ident.push_str("Event");
-    }
-
-    format_ident!("{}", ident)
-}
-
-fn generate_upcaster_tokens(
-    owner: &Ident,
-    upcasters: &[UpcasterDef],
-) -> (proc_macro2::TokenStream, proc_macro2::TokenStream) {
-    if upcasters.is_empty() {
-        return (quote! {}, quote! {});
-    }
-
-    let prefix = upcaster_wrapper_prefix(owner);
-    let wrapper_names: Vec<_> = upcasters
-        .iter()
-        .enumerate()
-        .map(|(idx, _)| format_ident!("__sourced_upcast_{}_{}", prefix, idx))
-        .collect();
-
-    let wrapper_defs = upcasters
-        .iter()
-        .zip(wrapper_names.iter())
-        .map(|(u, wrapper)| {
-            let source_type = &u.source_type;
-            let target_type = &u.target_type;
-            let to_version = &u.to_version;
-            let transform_fn = &u.transform_fn;
-            quote! {
-                fn #wrapper(
-                    event: &distributed::EventRecord,
-                ) -> Result<Vec<u8>, distributed::UpcastError> {
-                    distributed::upcast_payload::<#source_type, #target_type>(
-                        event,
-                        #to_version,
-                        #transform_fn,
-                    )
-                }
-            }
-        });
-
-    let upcaster_entries = upcasters
-        .iter()
-        .zip(wrapper_names.iter())
-        .map(|(u, wrapper)| {
-            let event_name = &u.event_name;
-            let from_version = &u.from_version;
-            let to_version = &u.to_version;
-            quote! {
-                distributed::EventUpcaster {
-                    event_type: #event_name,
-                    from_version: #from_version,
-                    to_version: #to_version,
-                    transform: #owner::#wrapper,
-                }
-            }
-        });
-
-    let upcasters_method = quote! {
-        fn upcasters() -> &'static [distributed::EventUpcaster] {
-            static UPCASTERS: &[distributed::EventUpcaster] = &[
-                #(#upcaster_entries),*
-            ];
-            UPCASTERS
-        }
-    };
-
-    (
-        quote! {
-            impl #owner {
-                #(#wrapper_defs)*
-            }
-        },
-        upcasters_method,
-    )
-}
-
-// ============================================================================
-// #[enqueue] attribute macro
-// ============================================================================
+use syn::DeriveInput;
 
 /// Attribute macro that automatically queues a local event for emission.
-///
-/// Similar to `#[digest]`, this macro captures function parameters and
-/// serializes them as the event data (using JSON). Events are queued
-/// during method execution and can be emitted after a successful commit.
-///
-/// **Requires the `emitter` feature to be enabled.**
-///
-/// # Usage
-///
-/// Basic usage with function parameters (automatically captured):
-/// ```ignore
-/// #[enqueue("order.initialized")]
-/// fn create(&mut self, id: String, items: Vec<Item>) {
-///     // enqueue call auto-inserted, params serialized as JSON
-///     // calls self.emitter.enqueue_with(...)
-/// }
-/// ```
-///
-/// With guard condition:
-/// ```ignore
-/// #[enqueue("step.completed", when = self.can_complete())]
-/// fn complete_step(&mut self) {
-///     self.completed = true;
-/// }
-/// ```
-///
-/// With custom emitter field name:
-/// ```ignore
-/// #[enqueue(my_emitter, "todo.initialized")]
-/// fn create(&mut self, name: String) {
-///     // uses self.my_emitter instead of self.emitter
-/// }
-/// ```
-///
-/// With a renamed entity field (used for the replay guard):
-/// ```ignore
-/// #[enqueue("order.initialized", entity = state)]
-/// fn create(&mut self, id: String) {
-///     // uses self.state.is_replaying() instead of self.entity.is_replaying()
-/// }
-/// ```
-///
-/// The macro supports:
-/// - Default emitter field name: `emitter` (can be overridden by specifying field name first)
-/// - `when = condition`: guard that wraps the entire method body
-/// - `entity = field`: entity field used for the `is_replaying()` guard (default: `entity`)
-/// - Methods may omit the return type; the macro expands them to `distributed::SourcedResult<()>`
 #[proc_macro_attribute]
 pub fn enqueue(attr: TokenStream, item: TokenStream) -> TokenStream {
-    expand_enqueue(attr.into(), item.into())
+    enqueue::expand_enqueue(attr.into(), item.into())
         .unwrap_or_else(|e| e.to_compile_error())
         .into()
 }
 
-fn expand_enqueue(attr: TokenStream2, item: TokenStream2) -> syn::Result<TokenStream2> {
-    let args = parse_enqueue_args.parse2(attr)?;
-    let mut func = syn::parse2::<ItemFn>(item)?;
-
-    let signature_synthesized = ensure_sourced_result_signature(&mut func.sig, "enqueue")?;
-
-    let emitter_field = &args.emitter_field;
-    let event_name = &args.event_name;
-
-    // Use function parameters - serialize as tuple to JSON
-    let params = extract_params_with_types(&func.sig, "enqueue")?;
-    let param_names: Vec<&Ident> = params.iter().map(|(name, _)| name).collect();
-
-    let entity_field = &args.entity_field;
-
-    let enqueue_call = if param_names.is_empty() {
-        quote! {
-            if !self.#entity_field.is_replaying() {
-                self.#emitter_field.enqueue(#event_name, "");
-            };
-        }
-    } else if param_names.len() == 1 {
-        // Single-element tuple needs trailing comma: (x,) not (x)
-        let param = &param_names[0];
-        quote! {
-            if !self.#entity_field.is_replaying() {
-                self.#emitter_field.enqueue_with(#event_name, &(#param.clone(),))?;
-            };
-        }
-    } else {
-        // Multi-element tuple
-        quote! {
-            if !self.#entity_field.is_replaying() {
-                self.#emitter_field.enqueue_with(#event_name, &(#(#param_names.clone()),*))?;
-            };
-        }
-    };
-
-    let new_body = wrap_result_body_with_guard(
-        args.guard.as_ref(),
-        enqueue_call,
-        &func.block,
-        signature_synthesized,
-    );
-    *func.block = new_body;
-
-    Ok(quote! { #func })
-}
-
-struct EnqueueArgs {
-    emitter_field: syn::Ident,
-    entity_field: syn::Ident,
-    event_name: LitStr,
-    guard: Option<Expr>,
-}
-
-fn parse_enqueue_args(input: syn::parse::ParseStream) -> syn::Result<EnqueueArgs> {
-    // Check if first token is an identifier (potential emitter field) or a string literal (event name)
-    let (emitter_field, event_name) = if input.peek(LitStr) {
-        // No emitter field specified, use default "emitter"
-        let event_name: LitStr = input.parse()?;
-        (format_ident!("emitter"), event_name)
-    } else {
-        // First token is an identifier - emitter field name, event name follows
-        let first_ident: syn::Ident = input.parse()?;
-        input.parse::<Token![,]>()?;
-        let event_name: LitStr = input.parse()?;
-        (first_ident, event_name)
-    };
-
-    let mut guard = None;
-    // Defaults to the conventional `entity` field; overridable so a renamed
-    // entity field still produces a correct `is_replaying()` guard.
-    let mut entity_field = format_ident!("entity");
-
-    // Parse optional keyword arguments: `when = condition`, `entity = field`
-    while input.peek(Token![,]) {
-        input.parse::<Token![,]>()?;
-        // Allow (and ignore) a trailing comma.
-        if input.is_empty() {
-            break;
-        }
-        let ident: syn::Ident = input.parse()?;
-        if ident == "when" {
-            input.parse::<Token![=]>()?;
-            guard = Some(input.parse()?);
-        } else if ident == "entity" {
-            input.parse::<Token![=]>()?;
-            entity_field = input.parse()?;
-        } else {
-            return Err(syn::Error::new_spanned(
-                &ident,
-                format!(
-                    "unsupported key `{ident}` in #[enqueue(...)]; expected `when` or `entity`"
-                ),
-            ));
-        }
-    }
-
-    Ok(EnqueueArgs {
-        emitter_field,
-        entity_field,
-        event_name,
-        guard,
-    })
-}
-
 /// Attribute macro that automatically inserts a digest call at the beginning of a method.
-///
-/// If the annotated method omits a return type, it expands to
-/// `distributed::SourcedResult<()>`. Methods may also explicitly return
-/// `Result<(), E>` where `E` can be constructed from
-/// `distributed::EventRecordError`; explicit `Result` methods should return
-/// `Ok(())` from the original body.
-///
-/// The generated digest call runs before the original method body. This means
-/// serialization errors are returned before the method mutates state. If the
-/// method can reject a command for domain validation reasons, prefer calling
-/// `self.entity.digest(...)?` explicitly after validation and before mutation.
-///
-/// # Usage
-///
-/// Basic usage with function parameters (automatically captured):
-/// ```ignore
-/// #[digest("initialized")]
-/// fn initialize(&mut self, id: String, user_id: String) {
-///     // digest call auto-inserted, params serialized as tuple
-/// }
-/// ```
-///
-/// With guard condition:
-/// ```ignore
-/// #[digest("completed", when = !self.completed)]
-/// fn complete(&mut self) -> Result<(), distributed::EventRecordError> {
-///     self.completed = true;
-///     Ok(())
-/// }
-/// ```
-/// The guard wraps both the digest call and the method body, so a false guard
-/// records no event and skips the body.
-///
-/// With validation inside the command body, use explicit digesting:
-/// ```ignore
-/// fn rename(&mut self, title: String) -> Result<(), TodoError> {
-///     if title.trim().is_empty() {
-///         return Err(TodoError::EmptyTitle);
-///     }
-///
-///     self.entity.digest("renamed", &(title.clone(),))?;
-///     self.title = title;
-///     Ok(())
-/// }
-/// ```
-///
-/// With custom entity field name:
-/// ```ignore
-/// #[digest(my_entity, "initialized")]
-/// fn create(&mut self, name: String) -> Result<(), distributed::EventRecordError> {
-///     // uses self.my_entity instead of self.entity
-///     Ok(())
-/// }
-/// ```
-///
-/// The macro supports:
-/// - Default entity field name: `entity` (can be overridden by specifying field name first)
-/// - `when = condition`: guard that wraps the entire method body
 #[proc_macro_attribute]
 pub fn digest(attr: TokenStream, item: TokenStream) -> TokenStream {
-    expand_digest(attr.into(), item.into())
+    digest::expand_digest(attr.into(), item.into())
         .unwrap_or_else(|e| e.to_compile_error())
         .into()
 }
 
-fn expand_digest(attr: TokenStream2, item: TokenStream2) -> syn::Result<TokenStream2> {
-    let args = parse_digest_args.parse2(attr)?;
-    let mut func = syn::parse2::<ItemFn>(item)?;
-
-    let signature_synthesized = ensure_sourced_result_signature(&mut func.sig, "digest")?;
-
-    let params = extract_params_with_types(&func.sig, "digest")?;
-    let param_names: Vec<&Ident> = params.iter().map(|(name, _)| name).collect();
-    let digest_call = generate_digest_call(
-        &args.entity_field,
-        &args.event_name,
-        &param_names,
-        args.version.as_ref(),
-    );
-
-    let new_body = wrap_result_body_with_guard(
-        args.guard.as_ref(),
-        digest_call,
-        &func.block,
-        signature_synthesized,
-    );
-    *func.block = new_body;
-
-    Ok(quote! { #func })
-}
-
-struct DigestArgs {
-    entity_field: syn::Ident,
-    event_name: LitStr,
-    guard: Option<Expr>,
-    version: Option<syn::LitInt>,
-}
-
-fn parse_digest_args(input: syn::parse::ParseStream) -> syn::Result<DigestArgs> {
-    // Check if first token is an identifier (potential entity field) or a string literal (event name)
-    let (entity_field, event_name) = if input.peek(LitStr) {
-        // No entity field specified, use default "entity"
-        let event_name: LitStr = input.parse()?;
-        (format_ident!("entity"), event_name)
-    } else {
-        // First token is an identifier - could be entity field or event name follows
-        let first_ident: syn::Ident = input.parse()?;
-        input.parse::<Token![,]>()?;
-        let event_name: LitStr = input.parse()?;
-        (first_ident, event_name)
-    };
-
-    let mut guard = None;
-    let mut version = None;
-
-    // Parse optional keyword arguments: `when = condition`, `version = N`
-    while input.peek(Token![,]) {
-        input.parse::<Token![,]>()?;
-        // Allow (and ignore) a trailing comma.
-        if input.is_empty() {
-            break;
-        }
-        let ident: syn::Ident = input.parse()?;
-        if ident == "when" {
-            input.parse::<Token![=]>()?;
-            guard = Some(input.parse()?);
-        } else if ident == "version" {
-            input.parse::<Token![=]>()?;
-            version = Some(input.parse()?);
-        } else {
-            return Err(syn::Error::new_spanned(
-                &ident,
-                format!(
-                    "unsupported key `{ident}` in #[digest(...)]; expected `when` or `version`"
-                ),
-            ));
-        }
-    }
-
-    Ok(DigestArgs {
-        entity_field,
-        event_name,
-        guard,
-        version,
-    })
-}
-
-/// Emit the `impl distributed::Aggregate` block shared by `aggregate!` and
-/// `#[sourced]`.
-///
-/// Both entry points produce a byte-identical impl: same associated
-/// `ReplayError = String`, same `entity`/`entity_mut`/`replay_event` bodies, and
-/// the same optional `aggregate_type` and upcasters methods. Only the replay
-/// match arms differ in how they are built upstream, so this helper takes them
-/// (already rendered) along with the type name and entity field. Keeping one
-/// emitter prevents the replay semantics of the two macros from drifting.
-///
-/// It emits only the `impl` block; callers still place `#upcaster_wrappers`
-/// (the free upcaster fns) where they already do.
-fn aggregate_impl_tokens(
-    type_name: &Ident,
-    entity_field: &Ident,
-    aggregate_type_method: &Option<TokenStream2>,
-    replay_arms: &[TokenStream2],
-    upcasters_method: &TokenStream2,
-) -> TokenStream2 {
-    quote! {
-        impl distributed::Aggregate for #type_name {
-            type ReplayError = String;
-
-            #aggregate_type_method
-
-            fn entity(&self) -> &distributed::Entity {
-                &self.#entity_field
-            }
-
-            fn entity_mut(&mut self) -> &mut distributed::Entity {
-                &mut self.#entity_field
-            }
-
-            fn replay_event(
-                &mut self,
-                event: &distributed::EventRecord,
-            ) -> Result<(), Self::ReplayError> {
-                match event.event_name.as_str() {
-                    #(#replay_arms)*
-                    _ => return Err(format!("Unknown event: {}", event.event_name)),
-                }
-                Ok(())
-            }
-
-            #upcasters_method
-        }
-    }
-}
-
-// ============================================================================
-// aggregate! proc-macro
-// ============================================================================
-
 /// Generates the Aggregate trait impl with replay logic.
-///
-/// # Usage
-///
-/// ```ignore
-/// distributed::aggregate!(Todo, entity {
-///     "initialized"(id, user_id, task) => initialize,
-///     "completed"() => complete(),
-/// });
-/// ```
-///
-/// This generates the `Aggregate` trait impl that handles replaying events.
-/// Events are stored as serialized payloads and deserialized on replay.
-///
-/// Note: Use `=> method()` (with parens) when the method takes no arguments.
-/// Use `=> method` (no parens) to pass all event args to the method.
 #[proc_macro]
 pub fn aggregate(input: TokenStream) -> TokenStream {
-    expand_aggregate(input.into())
+    aggregate::expand_aggregate(input.into())
         .unwrap_or_else(|e| e.to_compile_error())
         .into()
 }
 
-fn expand_aggregate(input: TokenStream2) -> syn::Result<TokenStream2> {
-    let input = syn::parse2::<AggregateInput>(input)?;
-
-    let agg_name = &input.agg_name;
-    let entity_field = &input.entity_field;
-
-    // Generate replay match arms - deserialize and call method directly
-    let replay_arms: Vec<_> = input
-        .events
-        .iter()
-        .map(|evt| {
-            let event_name = &evt.event_name;
-            let method_name = &evt.method_name;
-            let args = &evt.args;
-
-            // Determine what args to pass to the method
-            let call_args: Vec<_> = match &evt.method_args {
-                Some(method_args) => method_args.clone(),
-                None => args.clone(),
-            };
-
-            if args.is_empty() {
-                // No payload
-                quote! {
-                    #event_name => {
-                        self.#method_name().map_err(|e| e.to_string())?;
-                    }
-                }
-            } else if call_args.is_empty() {
-                // Event has payload but method takes no args
-                quote! {
-                    #event_name => {
-                        self.#method_name().map_err(|e| e.to_string())?;
-                    }
-                }
-            } else if args.len() == 1 {
-                // Single-element tuple needs trailing comma: (x,) not (x)
-                let arg = &args[0];
-                let call_arg = &call_args[0];
-                quote! {
-                    #event_name => {
-                        let (#arg,) = event.decode().map_err(|e| e.to_string())?;
-                        self.#method_name(#call_arg).map_err(|e| e.to_string())?;
-                    }
-                }
-            } else {
-                // Multi-element tuple
-                quote! {
-                    #event_name => {
-                        let (#(#args),*) = event.decode().map_err(|e| e.to_string())?;
-                        self.#method_name(#(#call_args),*).map_err(|e| e.to_string())?;
-                    }
-                }
-            }
-        })
-        .collect();
-
-    let (upcaster_wrappers, upcasters_method) =
-        generate_upcaster_tokens(agg_name, &input.upcasters);
-    let aggregate_type_method = input.aggregate_type.as_ref().map(|aggregate_type| {
-        quote! {
-            fn aggregate_type() -> &'static str {
-                #aggregate_type
-            }
-        }
-    });
-
-    // ReplayError stays `String`: replay errors are flattened from
-    // heterogeneous sources (per-event `decode()` errors, user method errors of
-    // arbitrary `E`, and unknown-event messages) via `e.to_string()`. A typed
-    // error would have to be generic over each method's error type or erase
-    // them anyway, so `String` is the smaller, honest representation here.
-    let aggregate_impl = aggregate_impl_tokens(
-        agg_name,
-        entity_field,
-        &aggregate_type_method,
-        &replay_arms,
-        &upcasters_method,
-    );
-    let expanded = quote! {
-        #upcaster_wrappers
-
-        #aggregate_impl
-    };
-
-    Ok(expanded)
-}
-
-struct UpcasterDef {
-    event_name: LitStr,
-    from_version: syn::LitInt,
-    to_version: syn::LitInt,
-    source_type: syn::Type,
-    target_type: syn::Type,
-    transform_fn: syn::Path,
-}
-
-impl Parse for UpcasterDef {
-    /// Parses one upcaster entry:
-    /// `("event.name", from => to, SourceType => TargetType, transform_fn)`.
-    ///
-    /// Shared by `aggregate!` and `#[sourced(..., upcasters(...))]` so the
-    /// upcaster grammar cannot drift between the two entry points.
-    fn parse(input: ParseStream) -> syn::Result<Self> {
-        let inner;
-        syn::parenthesized!(inner in input);
-
-        let event_name: LitStr = inner.parse()?;
-        inner.parse::<Token![,]>()?;
-        let from_version: syn::LitInt = inner.parse()?;
-        inner.parse::<Token![=>]>()?;
-        let to_version: syn::LitInt = inner.parse()?;
-        inner.parse::<Token![,]>()?;
-        let source_type: syn::Type = inner.parse()?;
-        inner.parse::<Token![=>]>()?;
-        let target_type: syn::Type = inner.parse()?;
-        inner.parse::<Token![,]>()?;
-        let transform_fn: syn::Path = inner.parse()?;
-
-        Ok(UpcasterDef {
-            event_name,
-            from_version,
-            to_version,
-            source_type,
-            target_type,
-            transform_fn,
-        })
-    }
-}
-
-/// Parse a sequence of parenthesized upcaster entries with optional trailing
-/// commas, until `content` is exhausted.
-fn parse_upcaster_list(content: ParseStream) -> syn::Result<Vec<UpcasterDef>> {
-    let mut upcasters = Vec::new();
-    while !content.is_empty() {
-        upcasters.push(content.parse::<UpcasterDef>()?);
-        // Optional trailing comma between upcaster entries
-        if content.peek(Token![,]) {
-            content.parse::<Token![,]>()?;
-        }
-    }
-    Ok(upcasters)
-}
-
-struct AggregateInput {
-    agg_name: Ident,
-    entity_field: Ident,
-    aggregate_type: Option<LitStr>,
-    events: Vec<EventDef>,
-    upcasters: Vec<UpcasterDef>,
-}
-
-struct EventDef {
-    event_name: LitStr,
-    args: Vec<Ident>,
-    method_name: Ident,
-    method_args: Option<Vec<Ident>>, // None = use event args, Some([]) = no args, Some([x,y]) = specific args
-}
-
-fn validate_aggregate_type_literal(lit: &LitStr) -> syn::Result<()> {
-    let value = lit.value();
-    if value.trim().is_empty() {
-        return Err(syn::Error::new_spanned(
-            lit,
-            "`aggregate_type` must not be empty or whitespace",
-        ));
-    }
-    if value.contains('\u{1f}') {
-        return Err(syn::Error::new_spanned(
-            lit,
-            "`aggregate_type` must not contain the reserved stream delimiter (U+001F)",
-        ));
-    }
-    Ok(())
-}
-
-impl Parse for AggregateInput {
-    fn parse(input: ParseStream) -> syn::Result<Self> {
-        let agg_name: Ident = input.parse()?;
-        input.parse::<Token![,]>()?;
-        let entity_field: Ident = input.parse()?;
-        let mut aggregate_type = None;
-
-        if input.peek(Token![,]) {
-            input.parse::<Token![,]>()?;
-            let kw: Ident = input.parse()?;
-            if kw != "aggregate_type" {
-                return Err(syn::Error::new(kw.span(), "expected `aggregate_type`"));
-            }
-            input.parse::<Token![=]>()?;
-            let lit = input.parse::<LitStr>()?;
-            validate_aggregate_type_literal(&lit)?;
-            aggregate_type = Some(lit);
-        }
-
-        let content;
-        braced!(content in input);
-
-        let mut events = Vec::new();
-        while !content.is_empty() {
-            let event_name: LitStr = content.parse()?;
-
-            // Parse (arg1, arg2, ...)
-            let args_content;
-            syn::parenthesized!(args_content in content);
-            let args: syn::punctuated::Punctuated<Ident, Token![,]> =
-                args_content.parse_terminated(Ident::parse, Token![,])?;
-            let args: Vec<Ident> = args.into_iter().collect();
-
-            content.parse::<Token![=>]>()?;
-            let method_name: Ident = content.parse()?;
-
-            // Check for optional method args: method() or method(a, b)
-            let method_args = if content.peek(syn::token::Paren) {
-                let method_args_content;
-                syn::parenthesized!(method_args_content in content);
-                let method_args: syn::punctuated::Punctuated<Ident, Token![,]> =
-                    method_args_content.parse_terminated(Ident::parse, Token![,])?;
-                Some(method_args.into_iter().collect())
-            } else {
-                None // Use event args
-            };
-
-            events.push(EventDef {
-                event_name,
-                args,
-                method_name,
-                method_args,
-            });
-
-            // Optional trailing comma
-            if content.peek(Token![,]) {
-                content.parse::<Token![,]>()?;
-            }
-        }
-
-        // Parse optional `upcasters [...]` block
-        let mut upcasters = Vec::new();
-        if input.peek(syn::Ident) {
-            let kw: Ident = input.parse()?;
-            if kw != "upcasters" {
-                return Err(syn::Error::new(kw.span(), "expected `upcasters`"));
-            }
-
-            let upcaster_content;
-            syn::bracketed!(upcaster_content in input);
-            upcasters = parse_upcaster_list(&upcaster_content)?;
-        }
-
-        Ok(AggregateInput {
-            agg_name,
-            entity_field,
-            aggregate_type,
-            events,
-            upcasters,
-        })
-    }
-}
-
-// ============================================================================
-// #[sourced] attribute macro
-// ============================================================================
-
-struct SourcedArgs {
-    entity_field: Ident,
-    enum_name: Option<LitStr>,
-    aggregate_type: Option<LitStr>,
-    enqueue: Option<Ident>, // Some(emitter_field) if enqueue enabled
-    upcasters: Vec<UpcasterDef>,
-}
-
-fn parse_sourced_args(input: ParseStream) -> syn::Result<SourcedArgs> {
-    if input.is_empty() {
-        return Err(
-            input.error("#[sourced] requires the entity field name, e.g. `#[sourced(entity)]`")
-        );
-    }
-    let entity_field: Ident = input.parse()?;
-    let mut enum_name = None;
-    let mut aggregate_type = None;
-    let mut enqueue = None;
-    let mut upcasters = Vec::new();
-
-    while input.peek(Token![,]) {
-        input.parse::<Token![,]>()?;
-        // Allow (and ignore) a trailing comma.
-        if input.is_empty() {
-            break;
-        }
-        let kw: Ident = input.parse()?;
-        if kw == "events" {
-            input.parse::<Token![=]>()?;
-            enum_name = Some(input.parse::<LitStr>()?);
-        } else if kw == "aggregate_type" {
-            input.parse::<Token![=]>()?;
-            let lit = input.parse::<LitStr>()?;
-            validate_aggregate_type_literal(&lit)?;
-            aggregate_type = Some(lit);
-        } else if kw == "enqueue" {
-            // Optional custom emitter field: enqueue(my_emitter)
-            if input.peek(syn::token::Paren) {
-                let inner;
-                syn::parenthesized!(inner in input);
-                enqueue = Some(inner.parse::<Ident>()?);
-            } else {
-                enqueue = Some(format_ident!("emitter"));
-            }
-        } else if kw == "upcasters" {
-            let upcaster_content;
-            syn::parenthesized!(upcaster_content in input);
-            upcasters = parse_upcaster_list(&upcaster_content)?;
-        } else {
-            return Err(syn::Error::new_spanned(
-                &kw,
-                format!(
-                    "unsupported key `{kw}` in #[sourced(...)]; expected `events`, `aggregate_type`, `enqueue`, or `upcasters`"
-                ),
-            ));
-        }
-    }
-
-    Ok(SourcedArgs {
-        entity_field,
-        enum_name,
-        aggregate_type,
-        enqueue,
-        upcasters,
-    })
-}
-
-struct EventAttr {
-    event_name: LitStr,
-    guard: Option<Expr>,
-    version: Option<syn::LitInt>,
-}
-
-fn parse_event_args(input: ParseStream) -> syn::Result<EventAttr> {
-    let event_name: LitStr = input.parse()?;
-    let mut guard = None;
-    let mut version = None;
-
-    while input.peek(Token![,]) {
-        input.parse::<Token![,]>()?;
-        // Allow (and ignore) a trailing comma.
-        if input.is_empty() {
-            break;
-        }
-        let ident: Ident = input.parse()?;
-        if ident == "when" {
-            input.parse::<Token![=]>()?;
-            guard = Some(input.parse()?);
-        } else if ident == "version" {
-            input.parse::<Token![=]>()?;
-            version = Some(input.parse()?);
-        } else {
-            return Err(syn::Error::new_spanned(
-                &ident,
-                format!("unsupported key `{ident}` in #[event(...)]; expected `when` or `version`"),
-            ));
-        }
-    }
-
-    Ok(EventAttr {
-        event_name,
-        guard,
-        version,
-    })
-}
-
-fn find_and_remove_event_attr(
-    attrs: &mut Vec<syn::Attribute>,
-) -> Result<Option<EventAttr>, syn::Error> {
-    let idx = attrs.iter().position(|a| a.path().is_ident("event"));
-    match idx {
-        Some(idx) => {
-            let attr = attrs.remove(idx);
-            let event_attr = attr.parse_args_with(parse_event_args)?;
-            Ok(Some(event_attr))
-        }
-        None => Ok(None),
-    }
-}
-
-struct EventMethodInfo {
-    event_name: LitStr,
-    method_name: Ident,
-    params: Vec<(Ident, syn::Type)>,
-}
-
 /// Attribute macro that generates a typed event enum, `TryFrom<&EventRecord>`,
 /// and `impl Aggregate` from annotated methods in an impl block.
-///
-/// Each `#[event(...)]` method is rewritten with the same recording order as
-/// `#[digest]`: event recording runs before the original method body, and a
-/// `when = ...` guard wraps both event recording and the body. Use explicit
-/// `self.entity.digest(...)?` calls for commands that need to validate before
-/// deciding whether to record an event.
-///
-/// # Usage
-///
-/// ```ignore
-/// #[sourced(entity)]
-/// impl Todo {
-///     #[event("initialized")]
-///     pub fn initialize(&mut self, id: String, user_id: String, task: String) {
-///         self.entity.set_id(&id);
-///         self.user_id = user_id;
-///         self.task = task;
-///     }
-///
-///     #[event("completed", when = !self.completed)]
-///     pub fn complete(&mut self) {
-///         self.completed = true;
-///     }
-/// }
-/// // Generates: TodoEvent enum, TryFrom<&EventRecord>, impl Aggregate
-/// ```
-///
-/// Options:
-/// - `#[sourced(entity)]` - entity field name
-/// - `#[sourced(entity, events = "CustomName")]` - custom enum name
-/// - `#[sourced(entity, aggregate_type = "todos")]` - stable stream type name
-/// - `#[sourced(entity, upcasters(("initialized", 1 => 2, OldPayload => NewPayload, upcast_fn)))]` - upcasters
 #[proc_macro_attribute]
 pub fn sourced(attr: TokenStream, item: TokenStream) -> TokenStream {
-    expand_sourced(attr.into(), item.into())
+    sourced::expand_sourced(attr.into(), item.into())
         .unwrap_or_else(|e| e.to_compile_error())
         .into()
 }
 
-fn expand_sourced(attr: TokenStream2, item: TokenStream2) -> syn::Result<TokenStream2> {
-    let args = parse_sourced_args.parse2(attr)?;
-    let mut impl_block = syn::parse2::<ItemImpl>(item)?;
-
-    // Extract struct name from self type
-    let struct_name = match &*impl_block.self_ty {
-        syn::Type::Path(type_path) => match type_path.path.segments.last() {
-            Some(segment) => segment.ident.clone(),
-            None => {
-                return Err(syn::Error::new_spanned(
-                    &impl_block.self_ty,
-                    "#[sourced] requires a named type",
-                ));
-            }
-        },
-        _ => {
-            return Err(syn::Error::new_spanned(
-                &impl_block.self_ty,
-                "#[sourced] requires a named type",
-            ));
-        }
-    };
-
-    // Collect event info and modify methods
-    let mut event_methods: Vec<EventMethodInfo> = Vec::new();
-    // Detect duplicate event names so the conflict points at the offending
-    // attribute instead of surfacing as a confusing duplicate match arm later.
-    let mut seen_events: std::collections::HashSet<String> = std::collections::HashSet::new();
-    // Distinct event names can still derive the same enum variant because only
-    // the last `.`-segment is PascalCased (`user.completed` and
-    // `admin.completed` both become `Completed`). Track the derived idents so
-    // the collision is reported here, naming both event strings, instead of as
-    // a duplicate-variant error inside the generated enum.
-    let mut seen_variants: std::collections::HashMap<String, LitStr> =
-        std::collections::HashMap::new();
-
-    for item in &mut impl_block.items {
-        if let syn::ImplItem::Fn(method) = item {
-            match find_and_remove_event_attr(&mut method.attrs) {
-                Ok(Some(event_attr)) => {
-                    // Event methods are replayed as `self.method(...)`, so they
-                    // must take a `self` receiver. Reject free associated
-                    // functions up front with a pointed message.
-                    if !matches!(method.sig.inputs.first(), Some(FnArg::Receiver(_))) {
-                        return Err(syn::Error::new_spanned(
-                            &method.sig,
-                            "#[event] methods must take a `&mut self` receiver",
-                        ));
-                    }
-
-                    let event_key = event_attr.event_name.value();
-                    if !seen_events.insert(event_key.clone()) {
-                        return Err(syn::Error::new_spanned(
-                            &event_attr.event_name,
-                            format!("duplicate #[event] name `{event_key}` in this #[sourced] impl block"),
-                        ));
-                    }
-
-                    let variant = event_variant_ident(&event_attr.event_name);
-                    if let Some(prev) = seen_variants.get(&variant.to_string()) {
-                        return Err(syn::Error::new_spanned(
-                            &event_attr.event_name,
-                            format!(
-                                "#[event] names `{}` and `{event_key}` both derive the enum variant `{variant}`; rename one so the variant names are distinct",
-                                prev.value()
-                            ),
-                        ));
-                    }
-                    seen_variants.insert(variant.to_string(), event_attr.event_name.clone());
-
-                    let signature_synthesized =
-                        ensure_sourced_result_signature(&mut method.sig, "event")?;
-
-                    let params = extract_params_with_types(&method.sig, "event")?;
-                    let param_name_refs: Vec<&Ident> =
-                        params.iter().map(|(name, _)| name).collect();
-
-                    // Build prepend: optional enqueue + digest
-                    let enqueue_call = args.enqueue.as_ref().map(|emitter_field| {
-                        generate_enqueue_call(
-                            &args.entity_field,
-                            emitter_field,
-                            &event_attr.event_name,
-                            &param_name_refs,
-                        )
-                    });
-                    let digest_call = generate_digest_call(
-                        &args.entity_field,
-                        &event_attr.event_name,
-                        &param_name_refs,
-                        event_attr.version.as_ref(),
-                    );
-                    let prepend = quote! {
-                        #enqueue_call
-                        #digest_call
-                    };
-
-                    let new_body = wrap_result_body_with_guard(
-                        event_attr.guard.as_ref(),
-                        prepend,
-                        &method.block,
-                        signature_synthesized,
-                    );
-                    method.block = new_body;
-
-                    event_methods.push(EventMethodInfo {
-                        event_name: event_attr.event_name,
-                        method_name: method.sig.ident.clone(),
-                        params,
-                    });
-                }
-                Ok(None) => { /* not an event method, skip */ }
-                Err(err) => return Err(err),
-            }
-        }
-    }
-
-    // Determine enum name
-    let enum_name = if let Some(ref custom) = args.enum_name {
-        format_ident!("{}", custom.value())
-    } else {
-        format_ident!("{}Event", struct_name)
-    };
-
-    // Generate event enum
-    let enum_variants = event_methods.iter().map(|e| {
-        let variant_name = event_variant_ident(&e.event_name);
-        if e.params.is_empty() {
-            quote! { #variant_name }
-        } else {
-            let fields = e.params.iter().map(|(name, ty)| quote! { #name: #ty });
-            quote! { #variant_name { #(#fields),* } }
-        }
-    });
-
-    let enum_def = quote! {
-        #[allow(clippy::enum_variant_names)]
-        #[derive(Debug, Clone, PartialEq)]
-        pub enum #enum_name {
-            #(#enum_variants),*
-        }
-    };
-
-    // Generate event_name() method on the enum
-    let event_name_arms = event_methods.iter().map(|e| {
-        let variant_name = event_variant_ident(&e.event_name);
-        let name_str = &e.event_name;
-        if e.params.is_empty() {
-            quote! { #enum_name::#variant_name => #name_str }
-        } else {
-            quote! { #enum_name::#variant_name { .. } => #name_str }
-        }
-    });
-
-    let event_name_impl = quote! {
-        impl #enum_name {
-            pub fn event_name(&self) -> &'static str {
-                match self {
-                    #(#event_name_arms),*
-                }
-            }
-        }
-    };
-
-    // Generate TryFrom<&EventRecord>
-    let try_from_arms = event_methods.iter().map(|e| {
-        let variant_name = event_variant_ident(&e.event_name);
-        let event_name_str = &e.event_name;
-        if e.params.is_empty() {
-            quote! {
-                #event_name_str => Ok(#enum_name::#variant_name),
-            }
-        } else if e.params.len() == 1 {
-            let (name, _) = &e.params[0];
-            quote! {
-                #event_name_str => {
-                    let (#name,) = event.decode().map_err(|e| e.to_string())?;
-                    Ok(#enum_name::#variant_name { #name })
-                }
-            }
-        } else {
-            let names: Vec<_> = e.params.iter().map(|(n, _)| n).collect();
-            quote! {
-                #event_name_str => {
-                    let (#(#names),*) = event.decode().map_err(|e| e.to_string())?;
-                    Ok(#enum_name::#variant_name { #(#names),* })
-                }
-            }
-        }
-    });
-
-    let try_from_impl = quote! {
-        impl TryFrom<&distributed::EventRecord> for #enum_name {
-            type Error = String;
-            fn try_from(event: &distributed::EventRecord) -> Result<Self, Self::Error> {
-                match event.event_name.as_str() {
-                    #(#try_from_arms)*
-                    _ => Err(format!("Unknown event: {}", event.event_name)),
-                }
-            }
-        }
-    };
-
-    // Generate impl Aggregate
-    let entity_field = &args.entity_field;
-    let replay_arms: Vec<_> = event_methods
-        .iter()
-        .map(|e| {
-            let event_name_str = &e.event_name;
-            let method_name = &e.method_name;
-            if e.params.is_empty() {
-                quote! {
-                    #event_name_str => {
-                        self.#method_name().map_err(|e| e.to_string())?;
-                    }
-                }
-            } else if e.params.len() == 1 {
-                let (name, _) = &e.params[0];
-                quote! {
-                    #event_name_str => {
-                        let (#name,) = event.decode().map_err(|e| e.to_string())?;
-                        self.#method_name(#name).map_err(|e| e.to_string())?;
-                    }
-                }
-            } else {
-                let names: Vec<_> = e.params.iter().map(|(n, _)| n).collect();
-                quote! {
-                    #event_name_str => {
-                        let (#(#names),*) = event.decode().map_err(|e| e.to_string())?;
-                        self.#method_name(#(#names),*).map_err(|e| e.to_string())?;
-                    }
-                }
-            }
-        })
-        .collect();
-
-    let (upcaster_wrappers, upcasters_method) =
-        generate_upcaster_tokens(&struct_name, &args.upcasters);
-    let aggregate_type_method = args.aggregate_type.as_ref().map(|aggregate_type| {
-        quote! {
-            fn aggregate_type() -> &'static str {
-                #aggregate_type
-            }
-        }
-    });
-
-    // ReplayError stays `String` — see the rationale on `expand_aggregate`.
-    let aggregate_impl = aggregate_impl_tokens(
-        &struct_name,
-        entity_field,
-        &aggregate_type_method,
-        &replay_arms,
-        &upcasters_method,
-    );
-
-    let expanded = quote! {
-        #impl_block
-        #enum_def
-        #event_name_impl
-        #try_from_impl
-        #upcaster_wrappers
-        #aggregate_impl
-    };
-
-    Ok(expanded)
-}
-
-// ============================================================================
-// #[derive(ReadModel)] derive macro
-// ============================================================================
-
 /// Derive macro for the `ReadModel` trait.
-///
-/// # Usage
-///
-/// ```ignore
-/// #[derive(Clone, Serialize, Deserialize, ReadModel)]
-/// #[collection("counter_views")]
-/// struct CounterView {
-///     #[id]
-///     pub id: String,
-///     pub name: String,
-///     pub value: i32,
-/// }
-/// ```
-///
-/// - `#[readmodel(collection = "...")]` or `#[collection("...")]` sets the
-///   collection name.
-///   If omitted, defaults to snake_case struct name + "s".
-/// - `#[readmodel(table = "...")]` or `#[table("...")]` opts into relational
-///   table metadata.
-/// - `#[readmodel(column = "...")]` or `#[column("...")]` sets a relational
-///   column name.
-/// - `#[readmodel(id)]`, `#[id]`, or `#[id("column_name")]` marks the field
-///   used as the unique identifier.
-///   If omitted, defaults to a field named `id`.
-/// - `#[readmodel(index)]`, `#[index]`, or `#[index("index_name")]` declares a
-///   secondary index on a field.
-/// - `#[readmodel(unique)]`, `#[unique]`, or `#[unique("index_name")]`
-///   declares a unique secondary index on a field.
-/// - `#[index(columns = ["field_a", "field_b"])]` or
-///   `#[index(name = "...", columns = ["field_a", "field_b"])]` declares a
-///   compound secondary index on a struct.
-/// - `#[unique(columns = ["field_a", "field_b"])]` or
-///   `#[unique(name = "...", columns = ["field_a", "field_b"])]` declares a
-///   compound unique index on a struct.
 #[proc_macro_derive(
     ReadModel,
     attributes(readmodel, collection, table, column, id, index, unique)
@@ -1426,350 +53,50 @@ pub fn derive_read_model(input: TokenStream) -> TokenStream {
     read_model::derive_read_model(input)
 }
 
-// ============================================================================
-// #[derive(Snapshot)] derive macro
-// ============================================================================
-
 /// Derive macro that generates a snapshot struct, `fn snapshot()`, and
 /// `impl Snapshottable` for an aggregate.
-///
-/// # Usage
-///
-/// ```ignore
-/// #[derive(Default, Snapshot)]
-/// struct Todo {
-///     pub entity: Entity,
-///     user_id: String,
-///     task: String,
-///     completed: bool,
-/// }
-/// ```
-///
-/// Generates `TodoSnapshot` with `id: String` + all non-entity fields,
-/// a `fn snapshot()` method, and `impl Snapshottable`.
-///
-/// Options:
-/// - `#[snapshot(id = "sku")]` — use a struct field as the ID key instead of synthesizing `id`
-/// - `#[snapshot(entity = "my_entity")]` — override the entity field name (default: `entity`)
-/// - `#[snapshot(version = N)]` — set `Snapshottable::SNAPSHOT_VERSION` (default: 1).
-///   Bump this whenever the snapshot layout changes incompatibly; on load a
-///   stored snapshot whose version differs is treated as a cache miss and the
-///   aggregate is rebuilt by replay rather than mis-decoded.
-/// - Fields with `#[serde(skip)]` are automatically excluded
 #[proc_macro_derive(Snapshot, attributes(snapshot))]
 pub fn derive_snapshot(input: TokenStream) -> TokenStream {
     snapshot::derive_snapshot(input)
 }
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use quote::quote;
-    use syn::parse::Parser;
-
-    // ---- digest ----------------------------------------------------------
-
-    #[test]
-    fn expand_digest_inserts_digest_call() {
-        let attr = quote! { "initialized" };
-        let item = quote! {
-            fn initialize(&mut self, id: String) {
-                self.id = id;
-            }
-        };
-        let out = expand_digest(attr, item).unwrap().to_string();
-        assert!(out.contains("digest"), "unexpected output: {out}");
-        assert!(out.contains("\"initialized\""), "unexpected output: {out}");
-    }
-
-    #[test]
-    fn parse_digest_args_rejects_unknown_key() {
-        let attr = quote! { "x", versoin = 2 };
-        let err = parse_digest_args
-            .parse2(attr)
-            .err()
-            .expect("unknown key should error");
-        let msg = err.to_string();
-        assert!(msg.contains("unsupported key `versoin`"), "got: {msg}");
-        assert!(msg.contains("version"), "got: {msg}");
-    }
-
-    #[test]
-    fn parse_digest_args_accepts_version_and_when() {
-        let attr = quote! { entity, "renamed", when = true, version = 2 };
-        let args = parse_digest_args.parse2(attr).unwrap();
-        assert_eq!(args.entity_field, "entity");
-        assert!(args.guard.is_some());
-        assert!(args.version.is_some());
-    }
-
-    // ---- enqueue ---------------------------------------------------------
-
-    #[test]
-    fn parse_enqueue_args_defaults_entity_field() {
-        let attr = quote! { "order.initialized" };
-        let args = parse_enqueue_args.parse2(attr).unwrap();
-        assert_eq!(args.emitter_field, "emitter");
-        assert_eq!(args.entity_field, "entity");
-    }
-
-    #[test]
-    fn parse_enqueue_args_overrides_entity_field() {
-        let attr = quote! { "order.initialized", entity = state };
-        let args = parse_enqueue_args.parse2(attr).unwrap();
-        assert_eq!(args.entity_field, "state");
-    }
-
-    #[test]
-    fn expand_enqueue_uses_renamed_entity_field_in_guard() {
-        let attr = quote! { "order.initialized", entity = state };
-        let item = quote! {
-            fn create(&mut self, id: String) {
-                self.id = id;
-            }
-        };
-        let out = expand_enqueue(attr, item).unwrap().to_string();
-        assert!(
-            out.contains("self . state . is_replaying"),
-            "expected renamed entity guard, got: {out}"
-        );
-    }
-
-    #[test]
-    fn parse_enqueue_args_rejects_unknown_key() {
-        let attr = quote! { "x", wen = true };
-        let err = parse_enqueue_args
-            .parse2(attr)
-            .err()
-            .expect("unknown key should error");
-        assert!(
-            err.to_string().contains("unsupported key `wen`"),
-            "got: {err}"
-        );
-    }
-
-    // ---- event (parse) ---------------------------------------------------
-
-    #[test]
-    fn parse_event_args_rejects_unknown_key() {
-        let attr = quote! { "completed", wen = true };
-        let err = parse_event_args
-            .parse2(attr)
-            .err()
-            .expect("unknown key should error");
-        assert!(
-            err.to_string().contains("unsupported key `wen`"),
-            "got: {err}"
-        );
-    }
-
-    // ---- sourced ---------------------------------------------------------
-
-    #[test]
-    fn parse_sourced_args_requires_entity_field() {
-        let attr = quote! {};
-        let err = parse_sourced_args
-            .parse2(attr)
-            .err()
-            .expect("missing entity should error");
-        assert!(
-            err.to_string().contains("requires the entity field name"),
-            "got: {err}"
-        );
-    }
-
-    #[test]
-    fn parse_sourced_args_rejects_unknown_key() {
-        let attr = quote! { entity, evnts = "Foo" };
-        let err = parse_sourced_args
-            .parse2(attr)
-            .err()
-            .expect("unknown key should error");
-        assert!(
-            err.to_string().contains("unsupported key `evnts`"),
-            "got: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_sourced_generates_enum_and_aggregate() {
-        let attr = quote! { entity };
-        let item = quote! {
-            impl Todo {
-                #[event("initialized")]
-                pub fn initialize(&mut self, id: String) {
-                    self.id = id;
-                }
-            }
-        };
-        let out = expand_sourced(attr, item).unwrap().to_string();
-        assert!(out.contains("enum TodoEvent"), "got: {out}");
-        assert!(
-            out.contains("impl distributed :: Aggregate for Todo"),
-            "got: {out}"
-        );
-    }
-
-    #[test]
-    fn expand_sourced_rejects_duplicate_event_names() {
-        let attr = quote! { entity };
-        let item = quote! {
-            impl Todo {
-                #[event("done")]
-                pub fn complete(&mut self) {}
-                #[event("done")]
-                pub fn finish(&mut self) {}
-            }
-        };
-        let err = expand_sourced(attr, item).expect_err("duplicate should error");
-        assert!(
-            err.to_string().contains("duplicate #[event] name `done`"),
-            "got: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_sourced_rejects_variant_ident_collisions() {
-        let attr = quote! { entity };
-        let item = quote! {
-            impl Workflow {
-                #[event("user.completed")]
-                pub fn user_completed(&mut self) {}
-                #[event("admin.completed")]
-                pub fn admin_completed(&mut self) {}
-            }
-        };
-        let err = expand_sourced(attr, item).expect_err("variant collision should error");
-        let msg = err.to_string();
-        assert!(msg.contains("`user.completed`"), "got: {msg}");
-        assert!(msg.contains("`admin.completed`"), "got: {msg}");
-        assert!(msg.contains("`Completed`"), "got: {msg}");
-    }
-
-    #[test]
-    fn expand_sourced_rejects_tuple_parameter_pattern() {
-        let attr = quote! { entity };
-        let item = quote! {
-            impl Point {
-                #[event("moved")]
-                pub fn moved(&mut self, (x, y): (u8, u8)) {
-                    self.x = x;
-                    self.y = y;
-                }
-            }
-        };
-        let err = expand_sourced(attr, item).expect_err("tuple pattern should error");
-        assert!(
-            err.to_string()
-                .contains("unsupported parameter pattern in #[event] method"),
-            "got: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_digest_rejects_wildcard_parameter_pattern() {
-        let attr = quote! { "initialized" };
-        let item = quote! {
-            fn initialize(&mut self, _: String) {}
-        };
-        let err = expand_digest(attr, item).expect_err("wildcard pattern should error");
-        assert!(
-            err.to_string()
-                .contains("unsupported parameter pattern in #[digest] method"),
-            "got: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_enqueue_rejects_struct_parameter_pattern() {
-        let attr = quote! { "order.initialized" };
-        let item = quote! {
-            fn create(&mut self, Payload { id }: Payload) {
-                let _ = id;
-            }
-        };
-        let err = expand_enqueue(attr, item).expect_err("struct pattern should error");
-        assert!(
-            err.to_string()
-                .contains("unsupported parameter pattern in #[enqueue] method"),
-            "got: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_sourced_rejects_event_without_receiver() {
-        let attr = quote! { entity };
-        let item = quote! {
-            impl Todo {
-                #[event("initialized")]
-                pub fn initialize(id: String) {}
-            }
-        };
-        let err = expand_sourced(attr, item).expect_err("missing receiver should error");
-        assert!(
-            err.to_string().contains("must take a `&mut self` receiver"),
-            "got: {err}"
-        );
-    }
-
-    // ---- upcasters -------------------------------------------------------
-
-    /// Both `aggregate!` and `#[sourced]` route through the same
-    /// `UpcasterDef` parser, so one grammar check covers both entry points.
-    #[test]
-    fn upcaster_def_parses_full_entry() {
-        let input = quote! { ("initialized", 1 => 2, OldPayload => NewPayload, upcast_fn) };
-        let def: UpcasterDef = syn::parse2(input).unwrap();
-        assert_eq!(def.event_name.value(), "initialized");
-        assert_eq!(def.from_version.base10_parse::<u64>().unwrap(), 1);
-        assert_eq!(def.to_version.base10_parse::<u64>().unwrap(), 2);
-    }
+/// Compile a portable, type-checked optimistic command-effect declaration.
+#[proc_macro]
+pub fn command_effects(input: TokenStream) -> TokenStream {
+    command_effects::expand(input)
+}
 
-    #[test]
-    fn upcaster_def_rejects_missing_transform_fn() {
-        let input = quote! { ("initialized", 1 => 2, OldPayload => NewPayload) };
-        assert!(syn::parse2::<UpcasterDef>(input).is_err());
-    }
+/// Compile declaration-owned generators for canonical command input fields.
+#[proc_macro]
+pub fn command_input_defaults(input: TokenStream) -> TokenStream {
+    command_effects::expand_input_defaults(input)
+}
 
-    #[test]
-    fn parse_sourced_args_accepts_upcasters() {
-        let attr = quote! {
-            entity,
-            upcasters(("initialized", 1 => 2, OldPayload => NewPayload, upcast_fn))
-        };
-        let args = parse_sourced_args.parse2(attr).unwrap();
-        assert_eq!(args.upcasters.len(), 1);
-    }
+/// Compile a finite, typed projector confirmation plan for one command input.
+#[proc_macro]
+pub fn command_confirmations(input: TokenStream) -> TokenStream {
+    command_effects::expand_confirmations(input)
+}
 
-    #[test]
-    fn expand_aggregate_accepts_upcasters_block() {
-        let input = quote! {
-            Todo, entity {
-                "initialized"(id) => initialize,
-            }
-            upcasters [
-                ("initialized", 1 => 2, OldPayload => NewPayload, upcast_fn),
-            ]
-        };
-        let out = expand_aggregate(input).unwrap().to_string();
-        assert!(out.contains("upcasters"), "got: {out}");
-        assert!(out.contains("upcast_fn"), "got: {out}");
+/// Derive `GraphqlInputType` for command mutation input structs.
+#[proc_macro_derive(GraphqlInput, attributes(serde))]
+pub fn derive_graphql_input(input: TokenStream) -> TokenStream {
+    let input = syn::parse_macro_input!(input as DeriveInput);
+    match graphql_types::expand_graphql_input(input) {
+        Ok(tokens) => tokens.into(),
+        Err(err) => err.to_compile_error().into(),
     }
+}
 
-    // ---- aggregate -------------------------------------------------------
-
-    #[test]
-    fn expand_aggregate_generates_impl() {
-        let input = quote! {
-            Todo, entity {
-                "initialized"(id) => initialize,
-            }
-        };
-        let out = expand_aggregate(input).unwrap().to_string();
-        assert!(
-            out.contains("impl distributed :: Aggregate for Todo"),
-            "got: {out}"
-        );
-        assert!(out.contains("replay_event"), "got: {out}");
+/// Derive `GraphqlOutputType` for command mutation output structs.
+#[proc_macro_derive(GraphqlOutput, attributes(serde))]
+pub fn derive_graphql_output(input: TokenStream) -> TokenStream {
+    let input = syn::parse_macro_input!(input as DeriveInput);
+    match graphql_types::expand_graphql_output(input) {
+        Ok(tokens) => tokens.into(),
+        Err(err) => err.to_compile_error().into(),
     }
 }
+
+#[cfg(test)]
+mod entry_tests;
diff --git a/distributed_macros/src/read_model.rs b/distributed_macros/src/read_model.rs
deleted file mode 100644
index 5d4059f7..00000000
--- a/distributed_macros/src/read_model.rs
+++ /dev/null
@@ -1,1519 +0,0 @@
-use proc_macro::TokenStream;
-use quote::{quote, ToTokens};
-use syn::{
-    punctuated::Punctuated, Attribute, Data, DeriveInput, Expr, ExprArray, ExprLit, Field, Fields,
-    GenericArgument, Lit, LitStr, Meta, PathArguments, Token, Type,
-};
-
-pub fn derive_read_model(input: TokenStream) -> TokenStream {
-    let input = syn::parse_macro_input!(input as DeriveInput);
-    match expand_read_model(input) {
-        Ok(expanded) => TokenStream::from(expanded),
-        Err(err) => err.to_compile_error().into(),
-    }
-}
-
-fn expand_read_model(input: DeriveInput) -> syn::Result<proc_macro2::TokenStream> {
-    let name = &input.ident;
-    let struct_attrs = StructAttrs::from_input(&input)?;
-    let fields = named_fields(&input)?;
-    let field_attrs = fields
-        .named
-        .iter()
-        .map(FieldAttrs::from_field)
-        .collect::<syn::Result<Vec<_>>>()?;
-    let relational =
-        struct_attrs.is_relational() || field_attrs.iter().any(FieldAttrs::is_relational);
-
-    let id_field = find_id_field(&fields.named, &field_attrs)?;
-    let collection = struct_attrs
-        .collection
-        .clone()
-        .or_else(|| struct_attrs.table.clone())
-        .unwrap_or_else(|| format!("{}s", to_snake_case(&name.to_string())));
-
-    let read_model_impl = if let Some(id_field) = &id_field {
-        Some(quote! {
-            impl distributed::ReadModel for #name {
-                const COLLECTION: &'static str = #collection;
-
-                fn id(&self) -> &str {
-                    &self.#id_field
-                }
-            }
-        })
-    } else if relational {
-        None
-    } else {
-        return Err(syn::Error::new_spanned(
-            input,
-            "ReadModel derive requires a field named `id` or a field marked with #[readmodel(id)]",
-        ));
-    };
-
-    let relational_impl = if relational {
-        Some(expand_relational_read_model(
-            name,
-            &struct_attrs,
-            &fields.named,
-            &field_attrs,
-            id_field.as_ref(),
-        )?)
-    } else {
-        None
-    };
-
-    Ok(quote! {
-        #read_model_impl
-        #relational_impl
-    })
-}
-
-fn named_fields(input: &DeriveInput) -> syn::Result<&FieldsNamed> {
-    let Data::Struct(data_struct) = &input.data else {
-        return Err(syn::Error::new_spanned(
-            input,
-            "ReadModel derive can only be used on structs with named fields",
-        ));
-    };
-
-    let Fields::Named(fields) = &data_struct.fields else {
-        return Err(syn::Error::new_spanned(
-            &data_struct.fields,
-            "ReadModel derive requires named fields",
-        ));
-    };
-
-    Ok(fields)
-}
-
-type FieldsNamed = syn::FieldsNamed;
-
-fn expand_relational_read_model(
-    name: &syn::Ident,
-    struct_attrs: &StructAttrs,
-    fields: &Punctuated<Field, Token![,]>,
-    field_attrs: &[FieldAttrs],
-    id_field: Option<&syn::Ident>,
-) -> syn::Result<proc_macro2::TokenStream> {
-    let model_name = name.to_string();
-    let table_name = struct_attrs
-        .table
-        .clone()
-        .or_else(|| struct_attrs.collection.clone())
-        .unwrap_or_else(|| format!("{}s", to_snake_case(&model_name)));
-
-    let primary_key_fields =
-        relational_primary_key_fields(struct_attrs, fields, field_attrs, id_field);
-    let primary_key_columns = primary_key_fields
-        .iter()
-        .map(|column| quote! { #column.to_string() })
-        .collect::<Vec<_>>();
-
-    let mut column_defs = Vec::new();
-    let mut row_inserts = Vec::new();
-    let mut row_fields = Vec::new();
-    let mut key_inserts = Vec::new();
-    let mut foreign_keys = Vec::new();
-    let mut indexes = Vec::new();
-    let mut relationships = Vec::new();
-    let mut hydrate_include_arms = Vec::new();
-    let mut include_rows_arms = Vec::new();
-    let mut include_schema_arms = Vec::new();
-
-    for (field, attrs) in fields.iter().zip(field_attrs) {
-        let ident = field
-            .ident
-            .as_ref()
-            .ok_or_else(|| syn::Error::new_spanned(field, "ReadModel fields must be named"))?;
-        let field_name = ident.to_string();
-
-        if let Some(relationship) = attrs.relationship_tokens(&field_name)? {
-            relationships.push(relationship);
-            let (hydrate_arm, include_rows_arm, include_schema_arm) =
-                attrs.relationship_include_tokens(field, &field_name)?;
-            hydrate_include_arms.push(hydrate_arm);
-            include_rows_arms.push(include_rows_arm);
-            include_schema_arms.push(include_schema_arm);
-            row_fields.push(quote! { #ident: ::core::default::Default::default() });
-            continue;
-        }
-
-        if attrs.skip_query {
-            row_fields.push(quote! { #ident: ::core::default::Default::default() });
-            continue;
-        }
-
-        let column_name = attrs.column.clone().unwrap_or_else(|| field_name.clone());
-        let primary_key = primary_key_fields
-            .iter()
-            .any(|pk| pk == &field_name || pk == &column_name);
-        let nullable = attrs.nullable || option_inner_type(&field.ty).is_some();
-        let column_type = column_type_tokens(&field.ty, attrs.jsonb);
-        let default_tokens = option_string_tokens(attrs.default.as_deref());
-        let foreign_key_value = attrs.foreign_key.as_ref().map(foreign_key_tokens);
-        let foreign_key = foreign_key_value
-            .as_ref()
-            .map(|foreign_key| quote! { Some(#foreign_key) })
-            .unwrap_or_else(|| quote! { None });
-        if let Some(foreign_key) = &foreign_key_value {
-            foreign_keys.push(foreign_key.clone());
-        }
-        let delegated_from = option_string_tokens(attrs.delegated_from.as_deref());
-        let has_default = attrs.has_default;
-        let jsonb = attrs.jsonb;
-
-        column_defs.push(quote! {
-            distributed::TableColumn {
-                field_name: #field_name.to_string(),
-                column_name: #column_name.to_string(),
-                column_type: #column_type,
-                nullable: #nullable,
-                has_default: #has_default,
-                default: #default_tokens,
-                primary_key: #primary_key,
-                foreign_key: #foreign_key,
-                delegated_from: #delegated_from,
-                jsonb: #jsonb,
-                skipped: false,
-            }
-        });
-
-        if let Some(value) = bytes_row_value_tokens(&field.ty, quote! { self.#ident }) {
-            row_inserts.push(quote! {
-                row.insert(#column_name, #value);
-            });
-        } else {
-            row_inserts.push(quote! {
-                row.insert_serde(#column_name, &self.#ident)?;
-            });
-        }
-        row_fields.push(quote! {
-            #ident: row.get_serde(#column_name)?
-        });
-
-        if primary_key {
-            if let Some(value) = bytes_row_value_tokens(&field.ty, quote! { self.#ident }) {
-                key_inserts.push(quote! {
-                    key.values.insert(#column_name.to_string(), #value);
-                });
-            } else {
-                key_inserts.push(quote! {
-                    key.values.insert(
-                        #column_name.to_string(),
-                        distributed::RowValue::from_serde(&self.#ident)?,
-                    );
-                });
-            }
-        }
-
-        if attrs.indexed || attrs.unique {
-            let index_columns = vec![column_name.clone()];
-            let index_name = attrs
-                .index_name
-                .clone()
-                .unwrap_or_else(|| default_index_name(&table_name, &index_columns, attrs.unique));
-            let unique = attrs.unique;
-            indexes.push(index_def_tokens(index_name, index_columns, unique));
-        }
-    }
-
-    for index in &struct_attrs.indexes {
-        let index_columns = index
-            .columns
-            .iter()
-            .map(|column| resolve_column_reference(column, fields, field_attrs))
-            .collect::<Vec<_>>();
-        let index_name = index
-            .name
-            .clone()
-            .unwrap_or_else(|| default_index_name(&table_name, &index_columns, index.unique));
-        indexes.push(index_def_tokens(index_name, index_columns, index.unique));
-    }
-
-    Ok(quote! {
-        impl distributed::RelationalReadModel for #name {
-            fn schema() -> &'static distributed::TableSchema {
-                static SCHEMA: ::std::sync::LazyLock<distributed::TableSchema> =
-                    ::std::sync::LazyLock::new(|| distributed::TableSchema {
-                        model_name: #model_name.to_string(),
-                        table_name: #table_name.to_string(),
-                        columns: vec![#(#column_defs),*],
-                        primary_key: distributed::PrimaryKey {
-                            columns: vec![#(#primary_key_columns),*],
-                        },
-                        version_column: Some(distributed::DEFAULT_TABLE_VERSION_COLUMN.to_string()),
-                        foreign_keys: vec![#(#foreign_keys),*],
-                        indexes: vec![#(#indexes),*],
-                        relationships: vec![#(#relationships),*],
-                    });
-                &SCHEMA
-            }
-
-            fn primary_key(&self) -> Result<distributed::RowKey, distributed::TableStoreError> {
-                let mut key = distributed::RowKey::default();
-                #(#key_inserts)*
-                Ok(key)
-            }
-
-            fn to_row(&self) -> Result<distributed::RowValues, distributed::TableStoreError> {
-                let mut row = distributed::RowValues::new();
-                #(#row_inserts)*
-                Ok(row)
-            }
-
-            fn from_row(row: distributed::RowValues) -> Result<Self, distributed::TableStoreError> {
-                Ok(Self {
-                    #(#row_fields),*
-                })
-            }
-        }
-
-        impl distributed::RelationalReadModelIncludes for #name {
-            fn hydrate_include(
-                &mut self,
-                include: &str,
-                rows: Vec<distributed::RowValues>,
-            ) -> Result<(), distributed::TableStoreError> {
-                match include {
-                    #(#hydrate_include_arms,)*
-                    _ => Err(distributed::TableStoreError::Metadata(format!(
-                        "read model `{}` has no hydratable relationship `{}`",
-                        #model_name,
-                        include
-                    ))),
-                }
-            }
-
-            fn include_rows(
-                &self,
-                include: &str,
-            ) -> Result<Vec<distributed::RowValues>, distributed::TableStoreError> {
-                match include {
-                    #(#include_rows_arms,)*
-                    _ => Err(distributed::TableStoreError::Metadata(format!(
-                        "read model `{}` has no tracked relationship `{}`",
-                        #model_name,
-                        include
-                    ))),
-                }
-            }
-
-            fn include_target_schema(
-                include: &str,
-            ) -> Result<&'static distributed::TableSchema, distributed::TableStoreError> {
-                match include {
-                    #(#include_schema_arms,)*
-                    _ => Err(distributed::TableStoreError::Metadata(format!(
-                        "read model `{}` has no tracked relationship `{}`",
-                        #model_name,
-                        include
-                    ))),
-                }
-            }
-        }
-    })
-}
-
-fn relational_primary_key_fields(
-    struct_attrs: &StructAttrs,
-    fields: &Punctuated<Field, Token![,]>,
-    field_attrs: &[FieldAttrs],
-    id_field: Option<&syn::Ident>,
-) -> Vec<String> {
-    if !struct_attrs.primary_key.is_empty() {
-        return struct_attrs
-            .primary_key
-            .iter()
-            .map(|key| resolve_column_reference(key, fields, field_attrs))
-            .collect();
-    }
-
-    id_field
-        .map(|id| {
-            let id_name = id.to_string();
-            resolve_column_reference(&id_name, fields, field_attrs)
-        })
-        .into_iter()
-        .collect()
-}
-
-fn resolve_column_reference(
-    reference: &str,
-    fields: &Punctuated<Field, Token![,]>,
-    field_attrs: &[FieldAttrs],
-) -> String {
-    fields
-        .iter()
-        .zip(field_attrs)
-        .find_map(|(field, attrs)| {
-            let field_name = field.ident.as_ref()?.to_string();
-            if field_name == reference {
-                Some(attrs.column.clone().unwrap_or(field_name))
-            } else {
-                None
-            }
-        })
-        .unwrap_or_else(|| reference.to_string())
-}
-
-fn default_index_name(table_name: &str, columns: &[String], unique: bool) -> String {
-    let prefix = if unique { "uq" } else { "idx" };
-    format!("{prefix}_{table_name}_{}", columns.join("_"))
-}
-
-fn index_def_tokens(
-    index_name: String,
-    index_columns: Vec<String>,
-    unique: bool,
-) -> proc_macro2::TokenStream {
-    let columns = index_columns
-        .iter()
-        .map(|column| quote! { #column.to_string() })
-        .collect::<Vec<_>>();
-
-    quote! {
-        distributed::TableIndex {
-            name: Some(#index_name.to_string()),
-            columns: vec![#(#columns),*],
-            unique: #unique,
-        }
-    }
-}
-
-#[derive(Default)]
-struct StructAttrs {
-    collection: Option<String>,
-    table: Option<String>,
-    primary_key: Vec<String>,
-    indexes: Vec<IndexAttr>,
-}
-
-struct IndexAttr {
-    name: Option<String>,
-    columns: Vec<String>,
-    unique: bool,
-}
-
-impl StructAttrs {
-    fn from_input(input: &DeriveInput) -> syn::Result<Self> {
-        let mut attrs = Self::default();
-        for attr in &input.attrs {
-            if attr.path().is_ident("collection") {
-                attrs.collection = Some(parse_direct_string_attr(attr, "collection")?);
-                continue;
-            }
-
-            if attr.path().is_ident("table") {
-                attrs.table = Some(parse_direct_string_attr(attr, "table")?);
-                continue;
-            }
-
-            if attr.path().is_ident("index") {
-                attrs
-                    .indexes
-                    .push(parse_direct_index_attr(attr, "index", false)?);
-                continue;
-            }
-
-            if attr.path().is_ident("unique") {
-                attrs
-                    .indexes
-                    .push(parse_direct_index_attr(attr, "unique", true)?);
-                continue;
-            }
-
-            if !attr.path().is_ident("readmodel") {
-                continue;
-            }
-
-            attr.parse_nested_meta(|meta| {
-                if meta.path.is_ident("collection") {
-                    attrs.collection = Some(meta.value()?.parse::<LitStr>()?.value());
-                } else if meta.path.is_ident("table") {
-                    attrs.table = Some(meta.value()?.parse::<LitStr>()?.value());
-                } else if meta.path.is_ident("primary_key") {
-                    let expr = meta.value()?.parse::<Expr>()?;
-                    attrs.primary_key = parse_string_list(expr)?;
-                } else {
-                    return Err(meta.error("unknown readmodel struct attribute"));
-                }
-                Ok(())
-            })?;
-        }
-        Ok(attrs)
-    }
-
-    fn is_relational(&self) -> bool {
-        self.table.is_some() || !self.primary_key.is_empty() || !self.indexes.is_empty()
-    }
-}
-
-#[derive(Default)]
-struct FieldAttrs {
-    id: bool,
-    column: Option<String>,
-    indexed: bool,
-    index_name: Option<String>,
-    unique: bool,
-    jsonb: bool,
-    skip_query: bool,
-    nullable: bool,
-    has_default: bool,
-    default: Option<String>,
-    foreign_key: Option<ForeignKeyParts>,
-    delegated_from: Option<String>,
-    relationship: Option<RelationshipAttr>,
-}
-
-impl FieldAttrs {
-    fn from_field(field: &Field) -> syn::Result<Self> {
-        let mut attrs = Self::default();
-        let mut pending_foreign_key: Option<String> = None;
-        let mut pending_through: Option<String> = None;
-        for attr in &field.attrs {
-            if attr.path().is_ident("id") {
-                attrs.id = true;
-                if let Some(column) = parse_optional_direct_string_attr(attr)? {
-                    attrs.column = Some(column);
-                }
-                continue;
-            }
-
-            if attr.path().is_ident("column") {
-                attrs.column = Some(parse_direct_string_attr(attr, "column")?);
-                continue;
-            }
-
-            if attr.path().is_ident("index") {
-                attrs.indexed = true;
-                if let Some(index_name) = parse_optional_direct_string_attr(attr)? {
-                    attrs.index_name = Some(index_name);
-                }
-                continue;
-            }
-
-            if attr.path().is_ident("unique") {
-                attrs.unique = true;
-                attrs.indexed = true;
-                if let Some(index_name) = parse_optional_direct_string_attr(attr)? {
-                    attrs.index_name = Some(index_name);
-                }
-                continue;
-            }
-
-            if !attr.path().is_ident("readmodel") {
-                continue;
-            }
-
-            attr.parse_nested_meta(|meta| {
-                if meta.path.is_ident("id") {
-                    attrs.id = true;
-                } else if meta.path.is_ident("column") {
-                    attrs.column = Some(meta.value()?.parse::<LitStr>()?.value());
-                } else if meta.path.is_ident("index") {
-                    attrs.indexed = true;
-                    if meta.input.peek(Token![=]) {
-                        attrs.index_name = Some(meta.value()?.parse::<LitStr>()?.value());
-                    }
-                } else if meta.path.is_ident("unique") {
-                    attrs.unique = true;
-                    attrs.indexed = true;
-                } else if meta.path.is_ident("jsonb") {
-                    attrs.jsonb = true;
-                } else if meta.path.is_ident("skip_query")
-                    || meta.path.is_ident("skip")
-                    || meta.path.is_ident("private")
-                {
-                    attrs.skip_query = true;
-                } else if meta.path.is_ident("nullable") {
-                    attrs.nullable = true;
-                } else if meta.path.is_ident("default") {
-                    attrs.has_default = true;
-                    if meta.input.peek(Token![=]) {
-                        attrs.default = Some(meta.value()?.parse::<LitStr>()?.value());
-                    }
-                } else if meta.path.is_ident("foreign_key") {
-                    let value = meta.value()?.parse::<LitStr>()?.value();
-                    if attrs.relationship.is_some() {
-                        let relationship = relationship_mut(&mut attrs, "foreign_key")?;
-                        if relationship.foreign_key.is_some() {
-                            return Err(
-                                meta.error("relationship foreign_key declared more than once")
-                            );
-                        }
-                        relationship.foreign_key = Some(value);
-                    } else if pending_foreign_key.is_some() {
-                        return Err(meta.error("relationship foreign_key declared more than once"));
-                    } else {
-                        pending_foreign_key = Some(value);
-                    }
-                } else if meta.path.is_ident("delegated_from") {
-                    attrs.delegated_from = Some(meta.value()?.parse::<LitStr>()?.value());
-                } else if meta.path.is_ident("has_many") {
-                    let target = meta.value()?.parse::<LitStr>()?.value();
-                    attrs.relationship = Some(RelationshipAttr {
-                        kind: RelationshipKindAttr::HasMany,
-                        target_model: target,
-                        foreign_key: None,
-                        through: None,
-                    });
-                } else if meta.path.is_ident("belongs_to") {
-                    let target = meta.value()?.parse::<LitStr>()?.value();
-                    attrs.relationship = Some(RelationshipAttr {
-                        kind: RelationshipKindAttr::BelongsTo,
-                        target_model: target,
-                        foreign_key: None,
-                        through: None,
-                    });
-                } else if meta.path.is_ident("many_to_many") {
-                    let target = meta.value()?.parse::<LitStr>()?.value();
-                    attrs.relationship = Some(RelationshipAttr {
-                        kind: RelationshipKindAttr::ManyToMany,
-                        target_model: target,
-                        foreign_key: None,
-                        through: None,
-                    });
-                } else if meta.path.is_ident("through") {
-                    let through = meta.value()?.parse::<LitStr>()?.value();
-                    if attrs.relationship.is_some() {
-                        let relationship = relationship_mut(&mut attrs, "through")?;
-                        if relationship.through.is_some() {
-                            return Err(meta.error("relationship through declared more than once"));
-                        }
-                        relationship.through = Some(through);
-                    } else if pending_through.is_some() {
-                        return Err(meta.error("relationship through declared more than once"));
-                    } else {
-                        pending_through = Some(through);
-                    }
-                } else {
-                    return Err(meta.error("unknown readmodel field attribute"));
-                }
-                Ok(())
-            })?;
-        }
-
-        if let Some(value) = pending_foreign_key {
-            if let Some(relationship) = attrs.relationship.as_mut() {
-                if relationship.foreign_key.is_some() {
-                    return Err(syn::Error::new_spanned(
-                        field,
-                        "relationship foreign_key declared more than once",
-                    ));
-                }
-                relationship.foreign_key = Some(value);
-            } else {
-                attrs.foreign_key = Some(parse_foreign_key(&value)?);
-            }
-        }
-
-        if let Some(through) = pending_through {
-            if let Some(relationship) = attrs.relationship.as_mut() {
-                if relationship.through.is_some() {
-                    return Err(syn::Error::new_spanned(
-                        field,
-                        "relationship through declared more than once",
-                    ));
-                }
-                relationship.through = Some(through);
-            } else {
-                return Err(syn::Error::new_spanned(
-                    field,
-                    "`through` must be declared with a relationship attribute",
-                ));
-            }
-        }
-
-        Ok(attrs)
-    }
-
-    fn is_relational(&self) -> bool {
-        self.column.is_some()
-            || self.indexed
-            || self.unique
-            || self.jsonb
-            || self.skip_query
-            || self.nullable
-            || self.has_default
-            || self.foreign_key.is_some()
-            || self.delegated_from.is_some()
-            || self.relationship.is_some()
-    }
-
-    fn relationship_tokens(
-        &self,
-        field_name: &str,
-    ) -> syn::Result<Option<proc_macro2::TokenStream>> {
-        let Some(relationship) = &self.relationship else {
-            return Ok(None);
-        };
-        let Some(foreign_key) = relationship.foreign_key.as_deref() else {
-            return Err(syn::Error::new(
-                proc_macro2::Span::call_site(),
-                format!("relationship `{field_name}` must declare `foreign_key = \"...\"`"),
-            ));
-        };
-        let target_model = &relationship.target_model;
-        let through = option_string_tokens(relationship.through.as_deref());
-        let kind = match relationship.kind {
-            RelationshipKindAttr::HasMany => quote! { distributed::RelationshipKind::HasMany },
-            RelationshipKindAttr::BelongsTo => quote! { distributed::RelationshipKind::BelongsTo },
-            RelationshipKindAttr::ManyToMany => {
-                quote! { distributed::RelationshipKind::ManyToMany }
-            }
-        };
-        Ok(Some(quote! {
-            distributed::RelationshipDef {
-                field_name: #field_name.to_string(),
-                kind: #kind,
-                target_model: #target_model.to_string(),
-                foreign_key: Some(#foreign_key.to_string()),
-                through: #through,
-            }
-        }))
-    }
-
-    fn relationship_include_tokens(
-        &self,
-        field: &Field,
-        field_name: &str,
-    ) -> syn::Result<(
-        proc_macro2::TokenStream,
-        proc_macro2::TokenStream,
-        proc_macro2::TokenStream,
-    )> {
-        let relationship = self.relationship.as_ref().ok_or_else(|| {
-            syn::Error::new_spanned(field, "field is not a read-model relationship")
-        })?;
-        let ident = field
-            .ident
-            .as_ref()
-            .ok_or_else(|| syn::Error::new_spanned(field, "ReadModel fields must be named"))?;
-
-        match relationship.kind {
-            RelationshipKindAttr::HasMany | RelationshipKindAttr::ManyToMany => {
-                let inner = vec_inner_type(&field.ty).ok_or_else(|| {
-                    syn::Error::new_spanned(
-                        field,
-                        format!("relationship `{field_name}` must be shaped as `Vec<T>`"),
-                    )
-                })?;
-                validate_relationship_target_type(
-                    field,
-                    inner,
-                    &relationship.target_model,
-                    field_name,
-                )?;
-                let hydrate = quote! {
-                    #field_name => {
-                        self.#ident = rows
-                            .into_iter()
-                            .map(<#inner as distributed::RelationalReadModel>::from_row)
-                            .collect::<Result<Vec<_>, distributed::TableStoreError>>()?;
-                        Ok(())
-                    }
-                };
-                let include_rows = quote! {
-                    #field_name => self
-                        .#ident
-                        .iter()
-                        .map(distributed::RelationalReadModel::to_row)
-                        .collect::<Result<Vec<_>, distributed::TableStoreError>>()
-                };
-                let include_schema = quote! {
-                    #field_name => Ok(<#inner as distributed::RelationalReadModel>::schema())
-                };
-                Ok((hydrate, include_rows, include_schema))
-            }
-            RelationshipKindAttr::BelongsTo => {
-                let inner = option_inner_type(&field.ty).ok_or_else(|| {
-                    syn::Error::new_spanned(
-                        field,
-                        format!(
-                            "belongs_to relationship `{field_name}` must be shaped as `Option<T>`"
-                        ),
-                    )
-                })?;
-                validate_relationship_target_type(
-                    field,
-                    inner,
-                    &relationship.target_model,
-                    field_name,
-                )?;
-                let hydrate = quote! {
-                    #field_name => {
-                        let mut rows = rows.into_iter();
-                        self.#ident = match rows.next() {
-                            Some(row) => Some(<#inner as distributed::RelationalReadModel>::from_row(row)?),
-                            None => None,
-                        };
-                        if rows.next().is_some() {
-                            return Err(distributed::TableStoreError::Metadata(format!(
-                                "belongs_to relationship `{}` returned more than one row",
-                                #field_name
-                            )));
-                        }
-                        Ok(())
-                    }
-                };
-                let include_rows = quote! {
-                    #field_name => {
-                        let mut rows = Vec::new();
-                        if let Some(value) = &self.#ident {
-                            rows.push(distributed::RelationalReadModel::to_row(value)?);
-                        }
-                        Ok(rows)
-                    }
-                };
-                let include_schema = quote! {
-                    #field_name => Ok(<#inner as distributed::RelationalReadModel>::schema())
-                };
-                Ok((hydrate, include_rows, include_schema))
-            }
-        }
-    }
-}
-
-fn relationship_mut<'a>(
-    attrs: &'a mut FieldAttrs,
-    name: &str,
-) -> syn::Result<&'a mut RelationshipAttr> {
-    attrs.relationship.as_mut().ok_or_else(|| {
-        syn::Error::new(
-            proc_macro2::Span::call_site(),
-            format!("`{name}` must be declared after a relationship attribute"),
-        )
-    })
-}
-
-#[derive(Clone)]
-struct ForeignKeyParts {
-    table: String,
-    column: String,
-}
-
-#[derive(Clone)]
-struct RelationshipAttr {
-    kind: RelationshipKindAttr,
-    target_model: String,
-    foreign_key: Option<String>,
-    through: Option<String>,
-}
-
-#[derive(Clone, Copy)]
-enum RelationshipKindAttr {
-    HasMany,
-    BelongsTo,
-    ManyToMany,
-}
-
-fn find_id_field(
-    fields: &Punctuated<Field, Token![,]>,
-    field_attrs: &[FieldAttrs],
-) -> syn::Result<Option<syn::Ident>> {
-    let mut explicit_id: Option<syn::Ident> = None;
-    for (field, attrs) in fields.iter().zip(field_attrs) {
-        if attrs.id {
-            let ident = field.ident.clone().ok_or_else(|| {
-                syn::Error::new_spanned(field, "ReadModel id field must be named")
-            })?;
-            if let Some(previous) = &explicit_id {
-                return Err(syn::Error::new_spanned(
-                    field,
-                    format!(
-                        "Multiple #[readmodel(id)] fields found: `{}` and `{}`",
-                        previous, ident
-                    ),
-                ));
-            }
-            explicit_id = Some(ident);
-        }
-    }
-
-    if explicit_id.is_some() {
-        return Ok(explicit_id);
-    }
-
-    Ok(fields
-        .iter()
-        .filter_map(|field| field.ident.clone())
-        .find(|ident| ident == "id"))
-}
-
-fn parse_string_list(expr: Expr) -> syn::Result<Vec<String>> {
-    match expr {
-        Expr::Array(ExprArray { elems, .. }) => elems.into_iter().map(parse_string_expr).collect(),
-        expr => parse_string_expr(expr).map(|value| vec![value]),
-    }
-}
-
-fn parse_string_expr(expr: Expr) -> syn::Result<String> {
-    match expr {
-        Expr::Lit(ExprLit {
-            lit: Lit::Str(value),
-            ..
-        }) => Ok(value.value()),
-        other => Err(syn::Error::new_spanned(
-            other,
-            "expected string literal in readmodel attribute",
-        )),
-    }
-}
-
-fn parse_direct_string_attr(attr: &Attribute, attr_name: &str) -> syn::Result<String> {
-    parse_optional_direct_string_attr(attr)?.ok_or_else(|| {
-        syn::Error::new_spanned(attr, format!("#[{attr_name}] requires a string literal"))
-    })
-}
-
-fn parse_optional_direct_string_attr(attr: &Attribute) -> syn::Result<Option<String>> {
-    match &attr.meta {
-        Meta::List(list) => Ok(Some(list.parse_args::<LitStr>()?.value())),
-        Meta::NameValue(name_value) => parse_string_expr(name_value.value.clone()).map(Some),
-        Meta::Path(_) => Ok(None),
-    }
-}
-
-fn parse_direct_index_attr(
-    attr: &Attribute,
-    attr_name: &str,
-    unique: bool,
-) -> syn::Result<IndexAttr> {
-    let mut name = None;
-    let mut columns = None;
-
-    match &attr.meta {
-        Meta::List(_) => {
-            attr.parse_nested_meta(|meta| {
-                if meta.path.is_ident("name") {
-                    name = Some(meta.value()?.parse::<LitStr>()?.value());
-                } else if meta.path.is_ident("columns") {
-                    let expr = meta.value()?.parse::<Expr>()?;
-                    columns = Some(parse_string_list(expr)?);
-                } else {
-                    return Err(meta.error(format!("unknown {attr_name} attribute")));
-                }
-                Ok(())
-            })?;
-        }
-        Meta::NameValue(name_value) => {
-            columns = Some(parse_string_list(name_value.value.clone())?);
-        }
-        Meta::Path(_) => {}
-    }
-
-    let columns = columns.ok_or_else(|| {
-        syn::Error::new_spanned(attr, format!("#[{attr_name}] requires columns = [\"...\"]"))
-    })?;
-    if columns.is_empty() {
-        return Err(syn::Error::new_spanned(
-            attr,
-            format!("#[{attr_name}] requires at least one column"),
-        ));
-    }
-
-    Ok(IndexAttr {
-        name,
-        columns,
-        unique,
-    })
-}
-
-fn parse_foreign_key(value: &str) -> syn::Result<ForeignKeyParts> {
-    let Some((table, column)) = value.split_once('.') else {
-        return Err(syn::Error::new(
-            proc_macro2::Span::call_site(),
-            "foreign_key must use `table.column` syntax",
-        ));
-    };
-    Ok(ForeignKeyParts {
-        table: table.to_string(),
-        column: column.to_string(),
-    })
-}
-
-fn foreign_key_tokens(foreign_key: &ForeignKeyParts) -> proc_macro2::TokenStream {
-    let table = &foreign_key.table;
-    let column = &foreign_key.column;
-    quote! {
-        distributed::ForeignKey {
-            table: #table.to_string(),
-            column: #column.to_string(),
-        }
-    }
-}
-
-fn option_string_tokens(value: Option<&str>) -> proc_macro2::TokenStream {
-    match value {
-        Some(value) => quote! { Some(#value.to_string()) },
-        None => quote! { None },
-    }
-}
-
-fn column_type_tokens(ty: &Type, jsonb: bool) -> proc_macro2::TokenStream {
-    if jsonb {
-        return quote! { distributed::ColumnType::Json };
-    }
-
-    let ty = option_inner_type(ty).unwrap_or(ty);
-    if let Some(last) = last_type_segment(ty) {
-        let ident = last.ident.to_string();
-        return match ident.as_str() {
-            "String" | "str" => quote! { distributed::ColumnType::Text },
-            "bool" => quote! { distributed::ColumnType::Boolean },
-            "i8" | "i16" | "i32" | "i64" | "isize" => {
-                quote! { distributed::ColumnType::Integer }
-            }
-            "u8" | "u16" | "u32" | "u64" | "usize" => {
-                quote! { distributed::ColumnType::UnsignedInteger }
-            }
-            "f32" | "f64" => quote! { distributed::ColumnType::Float },
-            "Vec" => {
-                if vec_inner_is_u8(last) {
-                    quote! { distributed::ColumnType::Bytes }
-                } else {
-                    quote! { distributed::ColumnType::Json }
-                }
-            }
-            "HashMap" | "BTreeMap" | "Value" => quote! { distributed::ColumnType::Json },
-            _ => {
-                let type_name = ty.to_token_stream().to_string();
-                quote! { distributed::ColumnType::Unsupported(#type_name.to_string()) }
-            }
-        };
-    }
-
-    let type_name = ty.to_token_stream().to_string();
-    quote! { distributed::ColumnType::Unsupported(#type_name.to_string()) }
-}
-
-fn bytes_row_value_tokens(
-    ty: &Type,
-    value: proc_macro2::TokenStream,
-) -> Option<proc_macro2::TokenStream> {
-    let option_inner = option_inner_type(ty);
-    let ty = option_inner.unwrap_or(ty);
-    let segment = last_type_segment(ty)?;
-    if segment.ident != "Vec" || !vec_inner_is_u8(segment) {
-        return None;
-    }
-
-    if option_inner.is_some() {
-        Some(quote! {
-            match &#value {
-                Some(value) => distributed::RowValue::Bytes(value.clone()),
-                None => distributed::RowValue::Null,
-            }
-        })
-    } else {
-        Some(quote! {
-            distributed::RowValue::Bytes(#value.clone())
-        })
-    }
-}
-
-fn option_inner_type(ty: &Type) -> Option<&Type> {
-    let segment = last_type_segment(ty)?;
-    if segment.ident != "Option" {
-        return None;
-    }
-    let PathArguments::AngleBracketed(args) = &segment.arguments else {
-        return None;
-    };
-    args.args.iter().find_map(|arg| match arg {
-        GenericArgument::Type(ty) => Some(ty),
-        _ => None,
-    })
-}
-
-fn vec_inner_type(ty: &Type) -> Option<&Type> {
-    let segment = last_type_segment(ty)?;
-    if segment.ident != "Vec" {
-        return None;
-    }
-    let PathArguments::AngleBracketed(args) = &segment.arguments else {
-        return None;
-    };
-    args.args.iter().find_map(|arg| match arg {
-        GenericArgument::Type(ty) => Some(ty),
-        _ => None,
-    })
-}
-
-fn validate_relationship_target_type(
-    field: &Field,
-    ty: &Type,
-    target_model: &str,
-    field_name: &str,
-) -> syn::Result<()> {
-    let Some(segment) = last_type_segment(ty) else {
-        return Err(syn::Error::new_spanned(
-            field,
-            format!("relationship `{field_name}` target type must be a named read model"),
-        ));
-    };
-    if segment.ident != target_model {
-        return Err(syn::Error::new_spanned(
-            field,
-            format!(
-                "relationship `{field_name}` targets `{target_model}` but the field stores `{}`",
-                segment.ident
-            ),
-        ));
-    }
-    Ok(())
-}
-
-fn last_type_segment(ty: &Type) -> Option<&syn::PathSegment> {
-    match ty {
-        Type::Path(path) => path.path.segments.last(),
-        Type::Reference(reference) => last_type_segment(&reference.elem),
-        _ => None,
-    }
-}
-
-fn vec_inner_is_u8(segment: &syn::PathSegment) -> bool {
-    let PathArguments::AngleBracketed(args) = &segment.arguments else {
-        return false;
-    };
-    args.args.iter().any(|arg| match arg {
-        GenericArgument::Type(Type::Path(path)) => path
-            .path
-            .segments
-            .last()
-            .is_some_and(|segment| segment.ident == "u8"),
-        _ => false,
-    })
-}
-
-fn to_snake_case(s: &str) -> String {
-    let mut result = String::new();
-    for (i, ch) in s.chars().enumerate() {
-        if ch.is_uppercase() {
-            if i > 0 {
-                result.push('_');
-            }
-            result.extend(ch.to_lowercase());
-        } else {
-            result.push(ch);
-        }
-    }
-    result
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn expand_read_model_accepts_named_id_field() {
-        let input: DeriveInput = syn::parse_quote! {
-            struct CounterView {
-                id: String,
-                value: i32,
-            }
-        };
-
-        let expanded = expand_read_model(input).unwrap().to_string();
-
-        assert!(expanded.contains("impl distributed :: ReadModel for CounterView"));
-        assert!(expanded.contains("fn id"));
-    }
-
-    #[test]
-    fn expand_read_model_accepts_explicit_id_attribute() {
-        let input: DeriveInput = syn::parse_quote! {
-            struct CounterView {
-                id: String,
-                #[readmodel(id)]
-                counter_id: String,
-                value: i32,
-            }
-        };
-
-        let expanded = expand_read_model(input).unwrap().to_string();
-
-        assert!(expanded.contains("& self . counter_id"));
-        assert!(!expanded.contains("& self . id"));
-    }
-
-    #[test]
-    fn expand_read_model_accepts_direct_collection_attribute() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[collection("counter_views")]
-            struct CounterView {
-                #[id]
-                counter_id: String,
-                value: i32,
-            }
-        };
-
-        let expanded = expand_read_model(input).unwrap().to_string();
-
-        assert!(expanded.contains("const COLLECTION : & 'static str = \"counter_views\""));
-        assert!(expanded.contains("& self . counter_id"));
-    }
-
-    #[test]
-    fn expand_read_model_accepts_direct_table_and_id_column_attributes() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[table = "counter_views"]
-            struct CounterView {
-                #[id("counter_id")]
-                id: String,
-                value: i32,
-            }
-        };
-
-        let expanded = expand_read_model(input).unwrap().to_string();
-
-        assert!(expanded.contains("table_name : \"counter_views\""));
-        assert!(expanded.contains("column_name : \"counter_id\""));
-    }
-
-    #[test]
-    fn expand_read_model_accepts_direct_column_attribute() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[table("counter_views")]
-            struct CounterView {
-                #[id]
-                id: String,
-                #[column("counter_value")]
-                value: i32,
-            }
-        };
-
-        let expanded = expand_read_model(input).unwrap().to_string();
-
-        assert!(expanded.contains("column_name : \"counter_value\""));
-    }
-
-    #[test]
-    fn expand_read_model_accepts_direct_index_attribute() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[table("counter_views")]
-            struct CounterView {
-                #[id]
-                id: String,
-                #[index("idx_counter_views_value")]
-                value: i32,
-            }
-        };
-
-        let expanded = expand_read_model(input).unwrap().to_string();
-
-        assert!(expanded.contains("name : Some (\"idx_counter_views_value\""));
-        assert!(expanded.contains("columns : vec ! [\"value\""));
-        assert!(expanded.contains("unique : false"));
-    }
-
-    #[test]
-    fn expand_read_model_accepts_direct_unique_attribute() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[table("counter_views")]
-            struct CounterView {
-                #[id]
-                id: String,
-                #[unique("uq_counter_views_slug")]
-                slug: String,
-            }
-        };
-
-        let expanded = expand_read_model(input).unwrap().to_string();
-
-        assert!(expanded.contains("name : Some (\"uq_counter_views_slug\""));
-        assert!(expanded.contains("columns : vec ! [\"slug\""));
-        assert!(expanded.contains("unique : true"));
-    }
-
-    #[test]
-    fn expand_read_model_accepts_struct_compound_index_attribute() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[table("account_summaries")]
-            #[index(name = "idx_account_summaries_owner_created", columns = ["owner", "created_at"])]
-            struct AccountSummary {
-                #[id("account_id")]
-                id: String,
-                owner: String,
-                #[column("created_at_utc")]
-                created_at: String,
-            }
-        };
-
-        let expanded = expand_read_model(input).unwrap().to_string();
-
-        assert!(expanded.contains("name : Some (\"idx_account_summaries_owner_created\""));
-        assert!(expanded.contains("columns : vec ! [\"owner\" . to_string () , \"created_at_utc\""));
-        assert!(expanded.contains("unique : false"));
-    }
-
-    #[test]
-    fn expand_read_model_accepts_struct_compound_unique_attribute() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[table("accounts")]
-            #[unique(columns = ["tenant_id", "slug"])]
-            struct AccountSummary {
-                #[id("account_id")]
-                id: String,
-                tenant_id: String,
-                slug: String,
-            }
-        };
-
-        let expanded = expand_read_model(input).unwrap().to_string();
-
-        assert!(expanded.contains("name : Some (\"uq_accounts_tenant_id_slug\""));
-        assert!(expanded.contains("columns : vec ! [\"tenant_id\""));
-        assert!(expanded.contains("\"slug\""));
-        assert!(expanded.contains("unique : true"));
-    }
-
-    #[test]
-    fn expand_read_model_rejects_struct_index_without_columns() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[table("counter_views")]
-            #[index]
-            struct CounterView {
-                #[id]
-                id: String,
-                value: i32,
-            }
-        };
-
-        let err = expand_read_model(input).expect_err("struct index needs columns");
-
-        assert!(
-            err.to_string().contains("#[index] requires columns"),
-            "unexpected error: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_read_model_rejects_direct_attributes_without_values() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[collection]
-            struct CounterView {
-                id: String,
-                value: i32,
-            }
-        };
-
-        let err = expand_read_model(input).expect_err("direct collection needs a value");
-
-        assert!(
-            err.to_string()
-                .contains("#[collection] requires a string literal"),
-            "unexpected error: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_read_model_rejects_missing_id_field_for_document_models() {
-        let input: DeriveInput = syn::parse_quote! {
-            struct CounterView {
-                value: i32,
-            }
-        };
-
-        let err = expand_read_model(input).expect_err("missing id field should return an error");
-
-        assert!(
-            err.to_string().contains("field named `id`"),
-            "unexpected error: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_read_model_allows_composite_relational_models_without_string_id() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[readmodel(table = "player_weapons", primary_key = ["player_id", "weapon_id"])]
-            struct PlayerWeapon {
-                #[readmodel(foreign_key = "players.player_id", delegated_from = "Player.player_id")]
-                player_id: String,
-                weapon_id: String,
-            }
-        };
-
-        let expanded = expand_read_model(input).unwrap().to_string();
-
-        assert!(expanded.contains("impl distributed :: RelationalReadModel for PlayerWeapon"));
-        assert!(!expanded.contains("impl distributed :: ReadModel for PlayerWeapon"));
-    }
-
-    #[test]
-    fn expand_read_model_rejects_multiple_explicit_id_attributes() {
-        let input: DeriveInput = syn::parse_quote! {
-            struct CounterView {
-                #[readmodel(id)]
-                counter_id: String,
-                #[readmodel(id)]
-                tenant_id: String,
-                value: i32,
-            }
-        };
-
-        let err = expand_read_model(input).expect_err("multiple ids should return an error");
-
-        assert!(
-            err.to_string()
-                .contains("Multiple #[readmodel(id)] fields found"),
-            "unexpected error: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_read_model_rejects_unknown_struct_attributes() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[readmodel(tabel = "counter_views")]
-            struct CounterView {
-                id: String,
-                value: i32,
-            }
-        };
-
-        let err = expand_read_model(input).expect_err("unknown struct attribute should fail");
-
-        assert!(
-            err.to_string()
-                .contains("unknown readmodel struct attribute"),
-            "unexpected error: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_read_model_rejects_unknown_field_attributes() {
-        let input: DeriveInput = syn::parse_quote! {
-            struct CounterView {
-                #[readmodel(ide)]
-                id: String,
-                value: i32,
-            }
-        };
-
-        let err = expand_read_model(input).expect_err("unknown field attribute should fail");
-
-        assert!(
-            err.to_string()
-                .contains("unknown readmodel field attribute"),
-            "unexpected error: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_read_model_accepts_relationship_metadata_before_relationship_kind() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[readmodel(table = "players")]
-            struct Player {
-                #[readmodel(id, column = "player_id")]
-                id: String,
-                #[readmodel(foreign_key = "player_id", has_many = "PlayerWeapon")]
-                weapons: Vec<PlayerWeapon>,
-            }
-        };
-
-        let expanded = expand_read_model(input).unwrap().to_string();
-
-        assert!(expanded.contains("RelationshipKind :: HasMany"));
-        assert!(expanded.contains("foreign_key : Some (\"player_id\""));
-    }
-
-    #[test]
-    fn expand_read_model_accepts_through_before_many_to_many() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[readmodel(table = "players")]
-            struct Player {
-                #[readmodel(id, column = "player_id")]
-                id: String,
-                #[readmodel(through = "player_weapon_links", foreign_key = "player_id", many_to_many = "Weapon")]
-                weapons: Vec<Weapon>,
-            }
-        };
-
-        let expanded = expand_read_model(input).unwrap().to_string();
-
-        assert!(expanded.contains("RelationshipKind :: ManyToMany"));
-        assert!(expanded.contains("through : Some (\"player_weapon_links\""));
-        assert!(expanded.contains("foreign_key : Some (\"player_id\""));
-    }
-
-    #[test]
-    fn expand_read_model_rejects_tuple_structs() {
-        let input: DeriveInput = syn::parse_quote! {
-            struct CounterView(String);
-        };
-
-        let err = expand_read_model(input).expect_err("tuple struct should return an error");
-
-        assert!(
-            err.to_string().contains("requires named fields"),
-            "unexpected error: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_read_model_rejects_relationships_without_foreign_key() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[readmodel(table = "players")]
-            struct Player {
-                #[readmodel(id)]
-                player_id: String,
-                #[readmodel(has_many = "PlayerWeapon")]
-                weapons: Vec<PlayerWeapon>,
-            }
-        };
-
-        let err = expand_read_model(input).expect_err("missing relationship key should fail");
-
-        assert!(
-            err.to_string().contains("foreign_key"),
-            "unexpected error: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_read_model_rejects_duplicate_relationship_foreign_keys() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[readmodel(table = "players")]
-            struct Player {
-                #[readmodel(id)]
-                player_id: String,
-                #[readmodel(has_many = "PlayerWeapon", foreign_key = "player_id", foreign_key = "owner_id")]
-                weapons: Vec<PlayerWeapon>,
-            }
-        };
-
-        let err = expand_read_model(input).expect_err("duplicate relationship foreign key");
-
-        assert!(
-            err.to_string()
-                .contains("foreign_key declared more than once"),
-            "unexpected error: {err}"
-        );
-    }
-
-    #[test]
-    fn expand_read_model_rejects_duplicate_pending_relationship_through_attrs() {
-        let input: DeriveInput = syn::parse_quote! {
-            #[readmodel(table = "players")]
-            struct Player {
-                #[readmodel(id)]
-                player_id: String,
-                #[readmodel(through = "player_weapon_links", through = "weapon_players", many_to_many = "Weapon")]
-                weapons: Vec<Weapon>,
-            }
-        };
-
-        let err = expand_read_model(input).expect_err("duplicate pending relationship through");
-
-        assert!(
-            err.to_string().contains("through declared more than once"),
-            "unexpected error: {err}"
-        );
-    }
-
-    #[test]
-    fn snake_case_preserves_multi_char_lowercase_mapping() {
-        assert_eq!(to_snake_case("İdView"), "i\u{307}d_view");
-    }
-}
diff --git a/distributed_macros/src/read_model/attrs.rs b/distributed_macros/src/read_model/attrs.rs
new file mode 100644
index 00000000..78f28543
--- /dev/null
+++ b/distributed_macros/src/read_model/attrs.rs
@@ -0,0 +1,586 @@
+use quote::quote;
+use syn::{Attribute, DeriveInput, Expr, ExprArray, ExprLit, Field, Lit, LitStr, Meta, Token};
+
+use super::types::{
+    option_inner_type, option_string_tokens, validate_relationship_target_type, vec_inner_type,
+};
+
+#[derive(Default)]
+pub(super) struct StructAttrs {
+    pub(super) collection: Option<String>,
+    pub(super) table: Option<String>,
+    pub(super) primary_key: Vec<String>,
+    pub(super) indexes: Vec<IndexAttr>,
+}
+
+pub(super) struct IndexAttr {
+    pub(super) name: Option<String>,
+    pub(super) columns: Vec<String>,
+    pub(super) unique: bool,
+}
+
+impl StructAttrs {
+    pub(super) fn from_input(input: &DeriveInput) -> syn::Result<Self> {
+        let mut attrs = Self::default();
+        for attr in &input.attrs {
+            if attr.path().is_ident("collection") {
+                attrs.collection = Some(parse_direct_string_attr(attr, "collection")?);
+                continue;
+            }
+
+            if attr.path().is_ident("table") {
+                attrs.table = Some(parse_direct_string_attr(attr, "table")?);
+                continue;
+            }
+
+            if attr.path().is_ident("index") {
+                attrs
+                    .indexes
+                    .push(parse_direct_index_attr(attr, "index", false)?);
+                continue;
+            }
+
+            if attr.path().is_ident("unique") {
+                attrs
+                    .indexes
+                    .push(parse_direct_index_attr(attr, "unique", true)?);
+                continue;
+            }
+
+            if !attr.path().is_ident("readmodel") {
+                continue;
+            }
+
+            attr.parse_nested_meta(|meta| {
+                if meta.path.is_ident("collection") {
+                    attrs.collection = Some(meta.value()?.parse::<LitStr>()?.value());
+                } else if meta.path.is_ident("table") {
+                    attrs.table = Some(meta.value()?.parse::<LitStr>()?.value());
+                } else if meta.path.is_ident("primary_key") {
+                    let expr = meta.value()?.parse::<Expr>()?;
+                    attrs.primary_key = parse_string_list(expr)?;
+                } else {
+                    return Err(meta.error("unknown readmodel struct attribute"));
+                }
+                Ok(())
+            })?;
+        }
+        Ok(attrs)
+    }
+
+    pub(super) fn is_relational(&self) -> bool {
+        self.table.is_some() || !self.primary_key.is_empty() || !self.indexes.is_empty()
+    }
+}
+
+#[derive(Default)]
+pub(super) struct FieldAttrs {
+    pub(super) id: bool,
+    pub(super) column: Option<String>,
+    pub(super) indexed: bool,
+    pub(super) index_name: Option<String>,
+    pub(super) unique: bool,
+    pub(super) jsonb: bool,
+    pub(super) text: bool,
+    pub(super) skip_query: bool,
+    pub(super) nullable: bool,
+    pub(super) has_default: bool,
+    pub(super) default: Option<String>,
+    pub(super) foreign_key: Option<ForeignKeyParts>,
+    pub(super) delegated_from: Option<String>,
+    pub(super) relationship: Option<RelationshipAttr>,
+}
+
+impl FieldAttrs {
+    pub(super) fn from_field(field: &Field) -> syn::Result<Self> {
+        let mut attrs = Self::default();
+        let mut pending_foreign_key: Option<String> = None;
+        let mut pending_through: Option<String> = None;
+        let mut pending_target_foreign_key: Option<String> = None;
+        for attr in &field.attrs {
+            if attr.path().is_ident("id") {
+                attrs.id = true;
+                if let Some(column) = parse_optional_direct_string_attr(attr)? {
+                    attrs.column = Some(column);
+                }
+                continue;
+            }
+
+            if attr.path().is_ident("column") {
+                attrs.column = Some(parse_direct_string_attr(attr, "column")?);
+                continue;
+            }
+
+            if attr.path().is_ident("index") {
+                attrs.indexed = true;
+                if let Some(index_name) = parse_optional_direct_string_attr(attr)? {
+                    attrs.index_name = Some(index_name);
+                }
+                continue;
+            }
+
+            if attr.path().is_ident("unique") {
+                attrs.unique = true;
+                attrs.indexed = true;
+                if let Some(index_name) = parse_optional_direct_string_attr(attr)? {
+                    attrs.index_name = Some(index_name);
+                }
+                continue;
+            }
+
+            if !attr.path().is_ident("readmodel") {
+                continue;
+            }
+
+            attr.parse_nested_meta(|meta| {
+                if meta.path.is_ident("id") {
+                    attrs.id = true;
+                } else if meta.path.is_ident("column") {
+                    attrs.column = Some(meta.value()?.parse::<LitStr>()?.value());
+                } else if meta.path.is_ident("index") {
+                    attrs.indexed = true;
+                    if meta.input.peek(Token![=]) {
+                        attrs.index_name = Some(meta.value()?.parse::<LitStr>()?.value());
+                    }
+                } else if meta.path.is_ident("unique") {
+                    attrs.unique = true;
+                    attrs.indexed = true;
+                } else if meta.path.is_ident("jsonb") {
+                    attrs.jsonb = true;
+                } else if meta.path.is_ident("text") {
+                    attrs.text = true;
+                } else if meta.path.is_ident("skip_query")
+                    || meta.path.is_ident("skip")
+                    || meta.path.is_ident("private")
+                {
+                    attrs.skip_query = true;
+                } else if meta.path.is_ident("nullable") {
+                    attrs.nullable = true;
+                } else if meta.path.is_ident("default") {
+                    attrs.has_default = true;
+                    if meta.input.peek(Token![=]) {
+                        attrs.default = Some(meta.value()?.parse::<LitStr>()?.value());
+                    }
+                } else if meta.path.is_ident("foreign_key") {
+                    let value = meta.value()?.parse::<LitStr>()?.value();
+                    if attrs.relationship.is_some() {
+                        let relationship = relationship_mut(&mut attrs, "foreign_key")?;
+                        if relationship.foreign_key.is_some() {
+                            return Err(
+                                meta.error("relationship foreign_key declared more than once")
+                            );
+                        }
+                        relationship.foreign_key = Some(value);
+                    } else if pending_foreign_key.is_some() {
+                        return Err(meta.error("relationship foreign_key declared more than once"));
+                    } else {
+                        pending_foreign_key = Some(value);
+                    }
+                } else if meta.path.is_ident("delegated_from") {
+                    attrs.delegated_from = Some(meta.value()?.parse::<LitStr>()?.value());
+                } else if meta.path.is_ident("has_many") {
+                    let target = meta.value()?.parse::<LitStr>()?.value();
+                    attrs.relationship = Some(RelationshipAttr {
+                        kind: RelationshipKindAttr::HasMany,
+                        target_model: target,
+                        foreign_key: None,
+                        through: None,
+                        target_foreign_key: None,
+                    });
+                } else if meta.path.is_ident("belongs_to") {
+                    let target = meta.value()?.parse::<LitStr>()?.value();
+                    attrs.relationship = Some(RelationshipAttr {
+                        kind: RelationshipKindAttr::BelongsTo,
+                        target_model: target,
+                        foreign_key: None,
+                        through: None,
+                        target_foreign_key: None,
+                    });
+                } else if meta.path.is_ident("many_to_many") {
+                    let target = meta.value()?.parse::<LitStr>()?.value();
+                    attrs.relationship = Some(RelationshipAttr {
+                        kind: RelationshipKindAttr::ManyToMany,
+                        target_model: target,
+                        foreign_key: None,
+                        through: None,
+                        target_foreign_key: None,
+                    });
+                } else if meta.path.is_ident("through") {
+                    let through = meta.value()?.parse::<LitStr>()?.value();
+                    if attrs.relationship.is_some() {
+                        let relationship = relationship_mut(&mut attrs, "through")?;
+                        if relationship.through.is_some() {
+                            return Err(meta.error("relationship through declared more than once"));
+                        }
+                        relationship.through = Some(through);
+                    } else if pending_through.is_some() {
+                        return Err(meta.error("relationship through declared more than once"));
+                    } else {
+                        pending_through = Some(through);
+                    }
+                } else if meta.path.is_ident("target_foreign_key") {
+                    let value = meta.value()?.parse::<LitStr>()?.value();
+                    if attrs.relationship.is_some() {
+                        let relationship = relationship_mut(&mut attrs, "target_foreign_key")?;
+                        if relationship.target_foreign_key.is_some() {
+                            return Err(meta
+                                .error("relationship target_foreign_key declared more than once"));
+                        }
+                        relationship.target_foreign_key = Some(value);
+                    } else if pending_target_foreign_key.is_some() {
+                        return Err(
+                            meta.error("relationship target_foreign_key declared more than once")
+                        );
+                    } else {
+                        pending_target_foreign_key = Some(value);
+                    }
+                } else {
+                    return Err(meta.error("unknown readmodel field attribute"));
+                }
+                Ok(())
+            })?;
+        }
+
+        if let Some(value) = pending_foreign_key {
+            if let Some(relationship) = attrs.relationship.as_mut() {
+                if relationship.foreign_key.is_some() {
+                    return Err(syn::Error::new_spanned(
+                        field,
+                        "relationship foreign_key declared more than once",
+                    ));
+                }
+                relationship.foreign_key = Some(value);
+            } else {
+                attrs.foreign_key = Some(parse_foreign_key(&value)?);
+            }
+        }
+
+        if let Some(through) = pending_through {
+            if let Some(relationship) = attrs.relationship.as_mut() {
+                if relationship.through.is_some() {
+                    return Err(syn::Error::new_spanned(
+                        field,
+                        "relationship through declared more than once",
+                    ));
+                }
+                relationship.through = Some(through);
+            } else {
+                return Err(syn::Error::new_spanned(
+                    field,
+                    "`through` must be declared with a relationship attribute",
+                ));
+            }
+        }
+
+        if let Some(target_fk) = pending_target_foreign_key {
+            if let Some(relationship) = attrs.relationship.as_mut() {
+                if relationship.target_foreign_key.is_some() {
+                    return Err(syn::Error::new_spanned(
+                        field,
+                        "relationship target_foreign_key declared more than once",
+                    ));
+                }
+                relationship.target_foreign_key = Some(target_fk);
+            } else {
+                return Err(syn::Error::new_spanned(
+                    field,
+                    "`target_foreign_key` must be declared with a relationship attribute",
+                ));
+            }
+        }
+
+        if attrs.jsonb && attrs.text {
+            return Err(syn::Error::new_spanned(
+                field,
+                "readmodel field cannot be both `jsonb` and text-backed",
+            ));
+        }
+
+        Ok(attrs)
+    }
+
+    pub(super) fn is_relational(&self) -> bool {
+        self.column.is_some()
+            || self.indexed
+            || self.unique
+            || self.jsonb
+            || self.text
+            || self.skip_query
+            || self.nullable
+            || self.has_default
+            || self.foreign_key.is_some()
+            || self.delegated_from.is_some()
+            || self.relationship.is_some()
+    }
+
+    pub(super) fn relationship_tokens(
+        &self,
+        field_name: &str,
+    ) -> syn::Result<Option<proc_macro2::TokenStream>> {
+        let Some(relationship) = &self.relationship else {
+            return Ok(None);
+        };
+        let Some(foreign_key) = relationship.foreign_key.as_deref() else {
+            return Err(syn::Error::new(
+                proc_macro2::Span::call_site(),
+                format!("relationship `{field_name}` must declare `foreign_key = \"...\"`"),
+            ));
+        };
+        let target_model = &relationship.target_model;
+        let through = option_string_tokens(relationship.through.as_deref());
+        let target_foreign_key = option_string_tokens(relationship.target_foreign_key.as_deref());
+        let kind = match relationship.kind {
+            RelationshipKindAttr::HasMany => quote! { distributed::RelationshipKind::HasMany },
+            RelationshipKindAttr::BelongsTo => quote! { distributed::RelationshipKind::BelongsTo },
+            RelationshipKindAttr::ManyToMany => {
+                quote! { distributed::RelationshipKind::ManyToMany }
+            }
+        };
+        Ok(Some(quote! {
+            distributed::RelationshipDef {
+                field_name: #field_name.to_string(),
+                kind: #kind,
+                target_model: #target_model.to_string(),
+                foreign_key: Some(#foreign_key.to_string()),
+                through: #through,
+                target_foreign_key: #target_foreign_key,
+            }
+        }))
+    }
+
+    pub(super) fn relationship_include_tokens(
+        &self,
+        field: &Field,
+        field_name: &str,
+    ) -> syn::Result<(
+        proc_macro2::TokenStream,
+        proc_macro2::TokenStream,
+        proc_macro2::TokenStream,
+    )> {
+        let relationship = self.relationship.as_ref().ok_or_else(|| {
+            syn::Error::new_spanned(field, "field is not a read-model relationship")
+        })?;
+        let ident = field
+            .ident
+            .as_ref()
+            .ok_or_else(|| syn::Error::new_spanned(field, "ReadModel fields must be named"))?;
+
+        match relationship.kind {
+            RelationshipKindAttr::HasMany | RelationshipKindAttr::ManyToMany => {
+                let inner = vec_inner_type(&field.ty).ok_or_else(|| {
+                    syn::Error::new_spanned(
+                        field,
+                        format!("relationship `{field_name}` must be shaped as `Vec<T>`"),
+                    )
+                })?;
+                validate_relationship_target_type(
+                    field,
+                    inner,
+                    &relationship.target_model,
+                    field_name,
+                )?;
+                let hydrate = quote! {
+                    #field_name => {
+                        self.#ident = rows
+                            .into_iter()
+                            .map(<#inner as distributed::RelationalReadModel>::from_row)
+                            .collect::<Result<Vec<_>, distributed::TableStoreError>>()?;
+                        Ok(())
+                    }
+                };
+                let include_rows = quote! {
+                    #field_name => self
+                        .#ident
+                        .iter()
+                        .map(distributed::RelationalReadModel::to_row)
+                        .collect::<Result<Vec<_>, distributed::TableStoreError>>()
+                };
+                let include_schema = quote! {
+                    #field_name => Ok(<#inner as distributed::RelationalReadModel>::schema())
+                };
+                Ok((hydrate, include_rows, include_schema))
+            }
+            RelationshipKindAttr::BelongsTo => {
+                let inner = option_inner_type(&field.ty).ok_or_else(|| {
+                    syn::Error::new_spanned(
+                        field,
+                        format!(
+                            "belongs_to relationship `{field_name}` must be shaped as `Option<T>`"
+                        ),
+                    )
+                })?;
+                validate_relationship_target_type(
+                    field,
+                    inner,
+                    &relationship.target_model,
+                    field_name,
+                )?;
+                let hydrate = quote! {
+                    #field_name => {
+                        let mut rows = rows.into_iter();
+                        self.#ident = match rows.next() {
+                            Some(row) => Some(<#inner as distributed::RelationalReadModel>::from_row(row)?),
+                            None => None,
+                        };
+                        if rows.next().is_some() {
+                            return Err(distributed::TableStoreError::Metadata(format!(
+                                "belongs_to relationship `{}` returned more than one row",
+                                #field_name
+                            )));
+                        }
+                        Ok(())
+                    }
+                };
+                let include_rows = quote! {
+                    #field_name => {
+                        let mut rows = Vec::new();
+                        if let Some(value) = &self.#ident {
+                            rows.push(distributed::RelationalReadModel::to_row(value)?);
+                        }
+                        Ok(rows)
+                    }
+                };
+                let include_schema = quote! {
+                    #field_name => Ok(<#inner as distributed::RelationalReadModel>::schema())
+                };
+                Ok((hydrate, include_rows, include_schema))
+            }
+        }
+    }
+}
+
+fn relationship_mut<'a>(
+    attrs: &'a mut FieldAttrs,
+    name: &str,
+) -> syn::Result<&'a mut RelationshipAttr> {
+    attrs.relationship.as_mut().ok_or_else(|| {
+        syn::Error::new(
+            proc_macro2::Span::call_site(),
+            format!("`{name}` must be declared after a relationship attribute"),
+        )
+    })
+}
+
+#[derive(Clone)]
+pub(super) struct ForeignKeyParts {
+    table: String,
+    column: String,
+}
+
+#[derive(Clone)]
+pub(super) struct RelationshipAttr {
+    pub(super) kind: RelationshipKindAttr,
+    pub(super) target_model: String,
+    pub(super) foreign_key: Option<String>,
+    pub(super) through: Option<String>,
+    pub(super) target_foreign_key: Option<String>,
+}
+
+#[derive(Clone, Copy)]
+pub(super) enum RelationshipKindAttr {
+    HasMany,
+    BelongsTo,
+    ManyToMany,
+}
+fn parse_string_list(expr: Expr) -> syn::Result<Vec<String>> {
+    match expr {
+        Expr::Array(ExprArray { elems, .. }) => elems.into_iter().map(parse_string_expr).collect(),
+        expr => parse_string_expr(expr).map(|value| vec![value]),
+    }
+}
+
+fn parse_string_expr(expr: Expr) -> syn::Result<String> {
+    match expr {
+        Expr::Lit(ExprLit {
+            lit: Lit::Str(value),
+            ..
+        }) => Ok(value.value()),
+        other => Err(syn::Error::new_spanned(
+            other,
+            "expected string literal in readmodel attribute",
+        )),
+    }
+}
+
+fn parse_direct_string_attr(attr: &Attribute, attr_name: &str) -> syn::Result<String> {
+    parse_optional_direct_string_attr(attr)?.ok_or_else(|| {
+        syn::Error::new_spanned(attr, format!("#[{attr_name}] requires a string literal"))
+    })
+}
+
+fn parse_optional_direct_string_attr(attr: &Attribute) -> syn::Result<Option<String>> {
+    match &attr.meta {
+        Meta::List(list) => Ok(Some(list.parse_args::<LitStr>()?.value())),
+        Meta::NameValue(name_value) => parse_string_expr(name_value.value.clone()).map(Some),
+        Meta::Path(_) => Ok(None),
+    }
+}
+
+fn parse_direct_index_attr(
+    attr: &Attribute,
+    attr_name: &str,
+    unique: bool,
+) -> syn::Result<IndexAttr> {
+    let mut name = None;
+    let mut columns = None;
+
+    match &attr.meta {
+        Meta::List(_) => {
+            attr.parse_nested_meta(|meta| {
+                if meta.path.is_ident("name") {
+                    name = Some(meta.value()?.parse::<LitStr>()?.value());
+                } else if meta.path.is_ident("columns") {
+                    let expr = meta.value()?.parse::<Expr>()?;
+                    columns = Some(parse_string_list(expr)?);
+                } else {
+                    return Err(meta.error(format!("unknown {attr_name} attribute")));
+                }
+                Ok(())
+            })?;
+        }
+        Meta::NameValue(name_value) => {
+            columns = Some(parse_string_list(name_value.value.clone())?);
+        }
+        Meta::Path(_) => {}
+    }
+
+    let columns = columns.ok_or_else(|| {
+        syn::Error::new_spanned(attr, format!("#[{attr_name}] requires columns = [\"...\"]"))
+    })?;
+    if columns.is_empty() {
+        return Err(syn::Error::new_spanned(
+            attr,
+            format!("#[{attr_name}] requires at least one column"),
+        ));
+    }
+
+    Ok(IndexAttr {
+        name,
+        columns,
+        unique,
+    })
+}
+
+fn parse_foreign_key(value: &str) -> syn::Result<ForeignKeyParts> {
+    let Some((table, column)) = value.split_once('.') else {
+        return Err(syn::Error::new(
+            proc_macro2::Span::call_site(),
+            "foreign_key must use `table.column` syntax",
+        ));
+    };
+    Ok(ForeignKeyParts {
+        table: table.to_string(),
+        column: column.to_string(),
+    })
+}
+
+pub(super) fn foreign_key_tokens(foreign_key: &ForeignKeyParts) -> proc_macro2::TokenStream {
+    let table = &foreign_key.table;
+    let column = &foreign_key.column;
+    quote! {
+        distributed::ForeignKey {
+            table: #table.to_string(),
+            column: #column.to_string(),
+        }
+    }
+}
diff --git a/distributed_macros/src/read_model/mod.rs b/distributed_macros/src/read_model/mod.rs
new file mode 100644
index 00000000..8b36dd40
--- /dev/null
+++ b/distributed_macros/src/read_model/mod.rs
@@ -0,0 +1,133 @@
+mod attrs;
+mod relational;
+mod types;
+
+use proc_macro::TokenStream;
+use quote::quote;
+use syn::{punctuated::Punctuated, Data, DeriveInput, Field, Fields, Token};
+
+use attrs::{FieldAttrs, StructAttrs};
+use relational::expand_relational_read_model;
+use types::to_snake_case;
+
+pub fn derive_read_model(input: TokenStream) -> TokenStream {
+    let input = syn::parse_macro_input!(input as DeriveInput);
+    match expand_read_model(input) {
+        Ok(expanded) => TokenStream::from(expanded),
+        Err(err) => err.to_compile_error().into(),
+    }
+}
+
+pub(crate) fn expand_read_model(input: DeriveInput) -> syn::Result<proc_macro2::TokenStream> {
+    let name = &input.ident;
+    let visibility = &input.vis;
+    let struct_attrs = StructAttrs::from_input(&input)?;
+    let fields = named_fields(&input)?;
+    let field_attrs = fields
+        .named
+        .iter()
+        .map(FieldAttrs::from_field)
+        .collect::<syn::Result<Vec<_>>>()?;
+    let relational =
+        struct_attrs.is_relational() || field_attrs.iter().any(FieldAttrs::is_relational);
+
+    let id_field = find_id_field(&fields.named, &field_attrs)?;
+    let collection = struct_attrs
+        .collection
+        .clone()
+        .or_else(|| struct_attrs.table.clone())
+        .unwrap_or_else(|| format!("{}s", to_snake_case(&name.to_string())));
+
+    let read_model_impl = if let Some(id_field) = &id_field {
+        Some(quote! {
+            impl distributed::ReadModel for #name {
+                const COLLECTION: &'static str = #collection;
+
+                fn id(&self) -> &str {
+                    &self.#id_field
+                }
+            }
+        })
+    } else if relational {
+        None
+    } else {
+        return Err(syn::Error::new_spanned(
+            input,
+            "ReadModel derive requires a field named `id` or a field marked with #[readmodel(id)]",
+        ));
+    };
+
+    let relational_impl = if relational {
+        Some(expand_relational_read_model(
+            name,
+            visibility,
+            &struct_attrs,
+            &fields.named,
+            &field_attrs,
+            id_field.as_ref(),
+        )?)
+    } else {
+        None
+    };
+
+    Ok(quote! {
+        #read_model_impl
+        #relational_impl
+    })
+}
+
+fn named_fields(input: &DeriveInput) -> syn::Result<&FieldsNamed> {
+    let Data::Struct(data_struct) = &input.data else {
+        return Err(syn::Error::new_spanned(
+            input,
+            "ReadModel derive can only be used on structs with named fields",
+        ));
+    };
+
+    let Fields::Named(fields) = &data_struct.fields else {
+        return Err(syn::Error::new_spanned(
+            &data_struct.fields,
+            "ReadModel derive requires named fields",
+        ));
+    };
+
+    Ok(fields)
+}
+
+type FieldsNamed = syn::FieldsNamed;
+
+fn find_id_field(
+    fields: &Punctuated<Field, Token![,]>,
+    field_attrs: &[FieldAttrs],
+) -> syn::Result<Option<syn::Ident>> {
+    let mut explicit_id: Option<syn::Ident> = None;
+    for (field, attrs) in fields.iter().zip(field_attrs) {
+        if attrs.id {
+            let ident = field.ident.clone().ok_or_else(|| {
+                syn::Error::new_spanned(field, "ReadModel id field must be named")
+            })?;
+            if let Some(previous) = &explicit_id {
+                return Err(syn::Error::new_spanned(
+                    field,
+                    format!(
+                        "Multiple #[readmodel(id)] fields found: `{}` and `{}`",
+                        previous, ident
+                    ),
+                ));
+            }
+            explicit_id = Some(ident);
+        }
+    }
+
+    if explicit_id.is_some() {
+        return Ok(explicit_id);
+    }
+
+    Ok(fields
+        .iter()
+        .filter_map(|field| field.ident.clone())
+        .find(|ident| ident == "id"))
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/distributed_macros/src/read_model/relational.rs b/distributed_macros/src/read_model/relational.rs
new file mode 100644
index 00000000..acff6fb9
--- /dev/null
+++ b/distributed_macros/src/read_model/relational.rs
@@ -0,0 +1,419 @@
+use quote::{format_ident, quote};
+use syn::{punctuated::Punctuated, Field, Token};
+
+use super::attrs::{foreign_key_tokens, FieldAttrs, RelationshipKindAttr, StructAttrs};
+use super::types::{
+    bytes_row_value_tokens, column_type_tokens, effect_model_wire_tokens, option_inner_type,
+    option_string_tokens, to_snake_case, vec_inner_type,
+};
+
+pub(super) fn expand_relational_read_model(
+    name: &syn::Ident,
+    visibility: &syn::Visibility,
+    struct_attrs: &StructAttrs,
+    fields: &Punctuated<Field, Token![,]>,
+    field_attrs: &[FieldAttrs],
+    id_field: Option<&syn::Ident>,
+) -> syn::Result<proc_macro2::TokenStream> {
+    let model_name = name.to_string();
+    let table_name = struct_attrs
+        .table
+        .clone()
+        .or_else(|| struct_attrs.collection.clone())
+        .unwrap_or_else(|| format!("{}s", to_snake_case(&model_name)));
+
+    let primary_key_fields =
+        relational_primary_key_fields(struct_attrs, fields, field_attrs, id_field);
+    let primary_key_columns = primary_key_fields
+        .iter()
+        .map(|column| quote! { #column.to_string() })
+        .collect::<Vec<_>>();
+
+    let effect_key_name = format_ident!("__Distributed{}EffectKey", name);
+    let mut effect_key_fields = Vec::new();
+    let mut effect_key_values = Vec::new();
+    for primary_key_column in &primary_key_fields {
+        let (field, _attrs) = fields
+            .iter()
+            .zip(field_attrs)
+            .find(|(field, attrs)| {
+                if attrs.relationship.is_some() || attrs.skip_query {
+                    return false;
+                }
+                let Some(ident) = &field.ident else {
+                    return false;
+                };
+                let field_name = ident.to_string();
+                attrs.column.as_deref().unwrap_or(&field_name) == primary_key_column
+            })
+            .ok_or_else(|| {
+                syn::Error::new(
+                    proc_macro2::Span::call_site(),
+                    format!(
+                        "primary-key column `{primary_key_column}` has no effect-key field on `{model_name}`"
+                    ),
+                )
+            })?;
+        let ident = field
+            .ident
+            .as_ref()
+            .expect("named read-model fields were validated");
+        let ty = &field.ty;
+        let marker = format_ident!("__Distributed{}EffectModelField_{}", name, ident);
+        effect_key_fields.push(quote! {
+            pub #ident: distributed::graphql::TypedEffectExpression<#ty>
+        });
+        effect_key_values.push(quote! {
+            distributed::graphql::__effect_key_field::<#marker>(value.#ident)
+        });
+    }
+
+    let mut column_defs = Vec::new();
+    let mut row_inserts = Vec::new();
+    let mut row_fields = Vec::new();
+    let mut key_inserts = Vec::new();
+    let mut foreign_keys = Vec::new();
+    let mut indexes = Vec::new();
+    let mut relationships = Vec::new();
+    let mut hydrate_include_arms = Vec::new();
+    let mut include_rows_arms = Vec::new();
+    let mut include_schema_arms = Vec::new();
+    let mut effect_markers = Vec::new();
+
+    for (field, attrs) in fields.iter().zip(field_attrs) {
+        let ident = field
+            .ident
+            .as_ref()
+            .ok_or_else(|| syn::Error::new_spanned(field, "ReadModel fields must be named"))?;
+        let field_name = ident.to_string();
+
+        if let Some(relationship) = attrs.relationship_tokens(&field_name)? {
+            relationships.push(relationship);
+            let (hydrate_arm, include_rows_arm, include_schema_arm) =
+                attrs.relationship_include_tokens(field, &field_name)?;
+            hydrate_include_arms.push(hydrate_arm);
+            include_rows_arms.push(include_rows_arm);
+            include_schema_arms.push(include_schema_arm);
+            let relationship_attr = attrs
+                .relationship
+                .as_ref()
+                .expect("relationship tokens require relationship metadata");
+            let target_ty = match relationship_attr.kind {
+                RelationshipKindAttr::HasMany | RelationshipKindAttr::ManyToMany => {
+                    vec_inner_type(&field.ty).expect("relationship shape was validated")
+                }
+                RelationshipKindAttr::BelongsTo => {
+                    option_inner_type(&field.ty).expect("relationship shape was validated")
+                }
+            };
+            let marker = format_ident!("__Distributed{}EffectRelationship_{}", name, ident);
+            effect_markers.push(quote! {
+                #[doc(hidden)]
+                #[allow(non_camel_case_types)]
+                #visibility struct #marker;
+
+                impl distributed::graphql::EffectRelationshipMarker for #marker {
+                    type Source = #name;
+                    type Target = #target_ty;
+                    const FIELD: &'static str = #field_name;
+                }
+            });
+            row_fields.push(quote! { #ident: ::core::default::Default::default() });
+            continue;
+        }
+
+        if attrs.skip_query {
+            row_fields.push(quote! { #ident: ::core::default::Default::default() });
+            continue;
+        }
+
+        let column_name = attrs.column.clone().unwrap_or_else(|| field_name.clone());
+        let field_ty = &field.ty;
+        let effect_wire = effect_model_wire_tokens(field_ty, attrs.jsonb, attrs.text);
+        let effect_marker = format_ident!("__Distributed{}EffectModelField_{}", name, ident);
+        effect_markers.push(quote! {
+            #[doc(hidden)]
+            #[allow(non_camel_case_types)]
+            #visibility struct #effect_marker;
+
+            impl distributed::graphql::EffectModelFieldMarker for #effect_marker {
+                type Model = #name;
+                type Value = #field_ty;
+                type Wire = #effect_wire;
+                const FIELD: &'static str = #column_name;
+            }
+        });
+        let primary_key = primary_key_fields
+            .iter()
+            .any(|pk| pk == &field_name || pk == &column_name);
+        let nullable = attrs.nullable || option_inner_type(&field.ty).is_some();
+        let column_type = column_type_tokens(&field.ty, attrs.jsonb, attrs.text);
+        let default_tokens = option_string_tokens(attrs.default.as_deref());
+        let foreign_key_value = attrs.foreign_key.as_ref().map(foreign_key_tokens);
+        let foreign_key = foreign_key_value
+            .as_ref()
+            .map(|foreign_key| quote! { Some(#foreign_key) })
+            .unwrap_or_else(|| quote! { None });
+        if let Some(foreign_key) = &foreign_key_value {
+            foreign_keys.push(foreign_key.clone());
+        }
+        let delegated_from = option_string_tokens(attrs.delegated_from.as_deref());
+        let has_default = attrs.has_default;
+        let jsonb = attrs.jsonb;
+
+        column_defs.push(quote! {
+            distributed::TableColumn {
+                field_name: #field_name.to_string(),
+                column_name: #column_name.to_string(),
+                column_type: #column_type,
+                nullable: #nullable,
+                has_default: #has_default,
+                default: #default_tokens,
+                primary_key: #primary_key,
+                foreign_key: #foreign_key,
+                delegated_from: #delegated_from,
+                jsonb: #jsonb,
+                skipped: false,
+            }
+        });
+
+        if attrs.text {
+            row_inserts.push(quote! {
+                row.insert(
+                    #column_name,
+                    distributed::RowValue::from_text_serde(
+                        &self.#ident,
+                        #nullable,
+                        #column_name,
+                    )?,
+                );
+            });
+        } else if let Some(value) = bytes_row_value_tokens(&field.ty, quote! { self.#ident }) {
+            row_inserts.push(quote! {
+                row.insert(#column_name, #value);
+            });
+        } else {
+            row_inserts.push(quote! {
+                row.insert_serde(#column_name, &self.#ident)?;
+            });
+        }
+        row_fields.push(quote! {
+            #ident: row.get_serde(#column_name)?
+        });
+
+        if primary_key {
+            if attrs.text {
+                key_inserts.push(quote! {
+                    key.values.insert(
+                        #column_name.to_string(),
+                        distributed::RowValue::from_text_serde(
+                            &self.#ident,
+                            #nullable,
+                            #column_name,
+                        )?,
+                    );
+                });
+            } else if let Some(value) = bytes_row_value_tokens(&field.ty, quote! { self.#ident }) {
+                key_inserts.push(quote! {
+                    key.values.insert(#column_name.to_string(), #value);
+                });
+            } else {
+                key_inserts.push(quote! {
+                    key.values.insert(
+                        #column_name.to_string(),
+                        distributed::RowValue::from_serde(&self.#ident)?,
+                    );
+                });
+            }
+        }
+
+        if attrs.indexed || attrs.unique {
+            let index_columns = vec![column_name.clone()];
+            let index_name = attrs
+                .index_name
+                .clone()
+                .unwrap_or_else(|| default_index_name(&table_name, &index_columns, attrs.unique));
+            let unique = attrs.unique;
+            indexes.push(index_def_tokens(index_name, index_columns, unique));
+        }
+    }
+
+    for index in &struct_attrs.indexes {
+        let index_columns = index
+            .columns
+            .iter()
+            .map(|column| resolve_column_reference(column, fields, field_attrs))
+            .collect::<Vec<_>>();
+        let index_name = index
+            .name
+            .clone()
+            .unwrap_or_else(|| default_index_name(&table_name, &index_columns, index.unique));
+        indexes.push(index_def_tokens(index_name, index_columns, index.unique));
+    }
+
+    Ok(quote! {
+        #[doc(hidden)]
+        #[allow(non_camel_case_types)]
+        #visibility struct #effect_key_name {
+            #(#effect_key_fields),*
+        }
+
+        impl ::core::convert::From<#effect_key_name>
+            for distributed::graphql::TypedEffectKey<#name>
+        {
+            fn from(value: #effect_key_name) -> Self {
+                distributed::graphql::__effect_key::<#name>(vec![#(#effect_key_values),*])
+            }
+        }
+
+        #(#effect_markers)*
+
+        impl distributed::RelationalReadModel for #name {
+            fn schema() -> &'static distributed::TableSchema {
+                static SCHEMA: ::std::sync::LazyLock<distributed::TableSchema> =
+                    ::std::sync::LazyLock::new(|| distributed::TableSchema {
+                        model_name: #model_name.to_string(),
+                        table_name: #table_name.to_string(),
+                        columns: vec![#(#column_defs),*],
+                        primary_key: distributed::PrimaryKey {
+                            columns: vec![#(#primary_key_columns),*],
+                        },
+                        version_column: Some(distributed::DEFAULT_TABLE_VERSION_COLUMN.to_string()),
+                        foreign_keys: vec![#(#foreign_keys),*],
+                        indexes: vec![#(#indexes),*],
+                        relationships: vec![#(#relationships),*],
+                        kind: distributed::TableKind::ReadModel,
+                    });
+                &SCHEMA
+            }
+
+            fn primary_key(&self) -> Result<distributed::RowKey, distributed::TableStoreError> {
+                let mut key = distributed::RowKey::default();
+                #(#key_inserts)*
+                Ok(key)
+            }
+
+            fn to_row(&self) -> Result<distributed::RowValues, distributed::TableStoreError> {
+                let mut row = distributed::RowValues::new();
+                #(#row_inserts)*
+                Ok(row)
+            }
+
+            fn from_row(row: distributed::RowValues) -> Result<Self, distributed::TableStoreError> {
+                Ok(Self {
+                    #(#row_fields),*
+                })
+            }
+        }
+
+        impl distributed::RelationalReadModelIncludes for #name {
+            fn hydrate_include(
+                &mut self,
+                include: &str,
+                rows: Vec<distributed::RowValues>,
+            ) -> Result<(), distributed::TableStoreError> {
+                match include {
+                    #(#hydrate_include_arms,)*
+                    _ => Err(distributed::TableStoreError::Metadata(format!(
+                        "read model `{}` has no hydratable relationship `{}`",
+                        #model_name,
+                        include
+                    ))),
+                }
+            }
+
+            fn include_rows(
+                &self,
+                include: &str,
+            ) -> Result<Vec<distributed::RowValues>, distributed::TableStoreError> {
+                match include {
+                    #(#include_rows_arms,)*
+                    _ => Err(distributed::TableStoreError::Metadata(format!(
+                        "read model `{}` has no tracked relationship `{}`",
+                        #model_name,
+                        include
+                    ))),
+                }
+            }
+
+            fn include_target_schema(
+                include: &str,
+            ) -> Result<&'static distributed::TableSchema, distributed::TableStoreError> {
+                match include {
+                    #(#include_schema_arms,)*
+                    _ => Err(distributed::TableStoreError::Metadata(format!(
+                        "read model `{}` has no tracked relationship `{}`",
+                        #model_name,
+                        include
+                    ))),
+                }
+            }
+        }
+    })
+}
+
+fn relational_primary_key_fields(
+    struct_attrs: &StructAttrs,
+    fields: &Punctuated<Field, Token![,]>,
+    field_attrs: &[FieldAttrs],
+    id_field: Option<&syn::Ident>,
+) -> Vec<String> {
+    if !struct_attrs.primary_key.is_empty() {
+        return struct_attrs
+            .primary_key
+            .iter()
+            .map(|key| resolve_column_reference(key, fields, field_attrs))
+            .collect();
+    }
+
+    id_field
+        .map(|id| {
+            let id_name = id.to_string();
+            resolve_column_reference(&id_name, fields, field_attrs)
+        })
+        .into_iter()
+        .collect()
+}
+
+fn resolve_column_reference(
+    reference: &str,
+    fields: &Punctuated<Field, Token![,]>,
+    field_attrs: &[FieldAttrs],
+) -> String {
+    fields
+        .iter()
+        .zip(field_attrs)
+        .find_map(|(field, attrs)| {
+            let field_name = field.ident.as_ref()?.to_string();
+            if field_name == reference {
+                Some(attrs.column.clone().unwrap_or(field_name))
+            } else {
+                None
+            }
+        })
+        .unwrap_or_else(|| reference.to_string())
+}
+
+fn default_index_name(table_name: &str, columns: &[String], unique: bool) -> String {
+    let prefix = if unique { "uq" } else { "idx" };
+    format!("{prefix}_{table_name}_{}", columns.join("_"))
+}
+
+fn index_def_tokens(
+    index_name: String,
+    index_columns: Vec<String>,
+    unique: bool,
+) -> proc_macro2::TokenStream {
+    let columns = index_columns
+        .iter()
+        .map(|column| quote! { #column.to_string() })
+        .collect::<Vec<_>>();
+
+    quote! {
+        distributed::TableIndex {
+            name: Some(#index_name.to_string()),
+            columns: vec![#(#columns),*],
+            unique: #unique,
+        }
+    }
+}
diff --git a/distributed_macros/src/read_model/tests.rs b/distributed_macros/src/read_model/tests.rs
new file mode 100644
index 00000000..f9ef6f7d
--- /dev/null
+++ b/distributed_macros/src/read_model/tests.rs
@@ -0,0 +1,413 @@
+use super::*;
+use syn::DeriveInput;
+
+#[test]
+fn expand_read_model_accepts_named_id_field() {
+    let input: DeriveInput = syn::parse_quote! {
+        struct CounterView {
+            id: String,
+            value: i32,
+        }
+    };
+
+    let expanded = expand_read_model(input).unwrap().to_string();
+
+    assert!(expanded.contains("impl distributed :: ReadModel for CounterView"));
+    assert!(expanded.contains("fn id"));
+}
+
+#[test]
+fn expand_read_model_accepts_explicit_id_attribute() {
+    let input: DeriveInput = syn::parse_quote! {
+        struct CounterView {
+            id: String,
+            #[readmodel(id)]
+            counter_id: String,
+            value: i32,
+        }
+    };
+
+    let expanded = expand_read_model(input).unwrap().to_string();
+
+    assert!(expanded.contains("& self . counter_id"));
+    assert!(!expanded.contains("& self . id"));
+}
+
+#[test]
+fn expand_read_model_accepts_direct_collection_attribute() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[collection("counter_views")]
+        struct CounterView {
+            #[id]
+            counter_id: String,
+            value: i32,
+        }
+    };
+
+    let expanded = expand_read_model(input).unwrap().to_string();
+
+    assert!(expanded.contains("const COLLECTION : & 'static str = \"counter_views\""));
+    assert!(expanded.contains("& self . counter_id"));
+}
+
+#[test]
+fn expand_read_model_accepts_direct_table_and_id_column_attributes() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[table = "counter_views"]
+        struct CounterView {
+            #[id("counter_id")]
+            id: String,
+            value: i32,
+        }
+    };
+
+    let expanded = expand_read_model(input).unwrap().to_string();
+
+    assert!(expanded.contains("table_name : \"counter_views\""));
+    assert!(expanded.contains("column_name : \"counter_id\""));
+}
+
+#[test]
+fn expand_read_model_accepts_direct_column_attribute() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[table("counter_views")]
+        struct CounterView {
+            #[id]
+            id: String,
+            #[column("counter_value")]
+            value: i32,
+        }
+    };
+
+    let expanded = expand_read_model(input).unwrap().to_string();
+
+    assert!(expanded.contains("column_name : \"counter_value\""));
+}
+
+#[test]
+fn expand_read_model_accepts_direct_index_attribute() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[table("counter_views")]
+        struct CounterView {
+            #[id]
+            id: String,
+            #[index("idx_counter_views_value")]
+            value: i32,
+        }
+    };
+
+    let expanded = expand_read_model(input).unwrap().to_string();
+
+    assert!(expanded.contains("name : Some (\"idx_counter_views_value\""));
+    assert!(expanded.contains("columns : vec ! [\"value\""));
+    assert!(expanded.contains("unique : false"));
+}
+
+#[test]
+fn expand_read_model_accepts_direct_unique_attribute() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[table("counter_views")]
+        struct CounterView {
+            #[id]
+            id: String,
+            #[unique("uq_counter_views_slug")]
+            slug: String,
+        }
+    };
+
+    let expanded = expand_read_model(input).unwrap().to_string();
+
+    assert!(expanded.contains("name : Some (\"uq_counter_views_slug\""));
+    assert!(expanded.contains("columns : vec ! [\"slug\""));
+    assert!(expanded.contains("unique : true"));
+}
+
+#[test]
+fn expand_read_model_accepts_struct_compound_index_attribute() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[table("account_summaries")]
+        #[index(name = "idx_account_summaries_owner_created", columns = ["owner", "created_at"])]
+        struct AccountSummary {
+            #[id("account_id")]
+            id: String,
+            owner: String,
+            #[column("created_at_utc")]
+            created_at: String,
+        }
+    };
+
+    let expanded = expand_read_model(input).unwrap().to_string();
+
+    assert!(expanded.contains("name : Some (\"idx_account_summaries_owner_created\""));
+    assert!(expanded.contains("columns : vec ! [\"owner\" . to_string () , \"created_at_utc\""));
+    assert!(expanded.contains("unique : false"));
+}
+
+#[test]
+fn expand_read_model_accepts_struct_compound_unique_attribute() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[table("accounts")]
+        #[unique(columns = ["tenant_id", "slug"])]
+        struct AccountSummary {
+            #[id("account_id")]
+            id: String,
+            tenant_id: String,
+            slug: String,
+        }
+    };
+
+    let expanded = expand_read_model(input).unwrap().to_string();
+
+    assert!(expanded.contains("name : Some (\"uq_accounts_tenant_id_slug\""));
+    assert!(expanded.contains("columns : vec ! [\"tenant_id\""));
+    assert!(expanded.contains("\"slug\""));
+    assert!(expanded.contains("unique : true"));
+}
+
+#[test]
+fn expand_read_model_rejects_struct_index_without_columns() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[table("counter_views")]
+        #[index]
+        struct CounterView {
+            #[id]
+            id: String,
+            value: i32,
+        }
+    };
+
+    let err = expand_read_model(input).expect_err("struct index needs columns");
+
+    assert!(
+        err.to_string().contains("#[index] requires columns"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn expand_read_model_rejects_direct_attributes_without_values() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[collection]
+        struct CounterView {
+            id: String,
+            value: i32,
+        }
+    };
+
+    let err = expand_read_model(input).expect_err("direct collection needs a value");
+
+    assert!(
+        err.to_string()
+            .contains("#[collection] requires a string literal"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn expand_read_model_rejects_missing_id_field_for_document_models() {
+    let input: DeriveInput = syn::parse_quote! {
+        struct CounterView {
+            value: i32,
+        }
+    };
+
+    let err = expand_read_model(input).expect_err("missing id field should return an error");
+
+    assert!(
+        err.to_string().contains("field named `id`"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn expand_read_model_allows_composite_relational_models_without_string_id() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[readmodel(table = "player_weapons", primary_key = ["player_id", "weapon_id"])]
+        struct PlayerWeapon {
+            #[readmodel(foreign_key = "players.player_id", delegated_from = "Player.player_id")]
+            player_id: String,
+            weapon_id: String,
+        }
+    };
+
+    let expanded = expand_read_model(input).unwrap().to_string();
+
+    assert!(expanded.contains("impl distributed :: RelationalReadModel for PlayerWeapon"));
+    assert!(!expanded.contains("impl distributed :: ReadModel for PlayerWeapon"));
+}
+
+#[test]
+fn expand_read_model_rejects_multiple_explicit_id_attributes() {
+    let input: DeriveInput = syn::parse_quote! {
+        struct CounterView {
+            #[readmodel(id)]
+            counter_id: String,
+            #[readmodel(id)]
+            tenant_id: String,
+            value: i32,
+        }
+    };
+
+    let err = expand_read_model(input).expect_err("multiple ids should return an error");
+
+    assert!(
+        err.to_string()
+            .contains("Multiple #[readmodel(id)] fields found"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn expand_read_model_rejects_unknown_struct_attributes() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[readmodel(tabel = "counter_views")]
+        struct CounterView {
+            id: String,
+            value: i32,
+        }
+    };
+
+    let err = expand_read_model(input).expect_err("unknown struct attribute should fail");
+
+    assert!(
+        err.to_string()
+            .contains("unknown readmodel struct attribute"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn expand_read_model_rejects_unknown_field_attributes() {
+    let input: DeriveInput = syn::parse_quote! {
+        struct CounterView {
+            #[readmodel(ide)]
+            id: String,
+            value: i32,
+        }
+    };
+
+    let err = expand_read_model(input).expect_err("unknown field attribute should fail");
+
+    assert!(
+        err.to_string()
+            .contains("unknown readmodel field attribute"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn expand_read_model_accepts_relationship_metadata_before_relationship_kind() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[readmodel(table = "players")]
+        struct Player {
+            #[readmodel(id, column = "player_id")]
+            id: String,
+            #[readmodel(foreign_key = "player_id", has_many = "PlayerWeapon")]
+            weapons: Vec<PlayerWeapon>,
+        }
+    };
+
+    let expanded = expand_read_model(input).unwrap().to_string();
+
+    assert!(expanded.contains("RelationshipKind :: HasMany"));
+    assert!(expanded.contains("foreign_key : Some (\"player_id\""));
+}
+
+#[test]
+fn expand_read_model_accepts_through_before_many_to_many() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[readmodel(table = "players")]
+        struct Player {
+            #[readmodel(id, column = "player_id")]
+            id: String,
+            #[readmodel(through = "player_weapon_links", foreign_key = "player_id", many_to_many = "Weapon")]
+            weapons: Vec<Weapon>,
+        }
+    };
+
+    let expanded = expand_read_model(input).unwrap().to_string();
+
+    assert!(expanded.contains("RelationshipKind :: ManyToMany"));
+    assert!(expanded.contains("through : Some (\"player_weapon_links\""));
+    assert!(expanded.contains("foreign_key : Some (\"player_id\""));
+}
+
+#[test]
+fn expand_read_model_rejects_tuple_structs() {
+    let input: DeriveInput = syn::parse_quote! {
+        struct CounterView(String);
+    };
+
+    let err = expand_read_model(input).expect_err("tuple struct should return an error");
+
+    assert!(
+        err.to_string().contains("requires named fields"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn expand_read_model_rejects_relationships_without_foreign_key() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[readmodel(table = "players")]
+        struct Player {
+            #[readmodel(id)]
+            player_id: String,
+            #[readmodel(has_many = "PlayerWeapon")]
+            weapons: Vec<PlayerWeapon>,
+        }
+    };
+
+    let err = expand_read_model(input).expect_err("missing relationship key should fail");
+
+    assert!(
+        err.to_string().contains("foreign_key"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn expand_read_model_rejects_duplicate_relationship_foreign_keys() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[readmodel(table = "players")]
+        struct Player {
+            #[readmodel(id)]
+            player_id: String,
+            #[readmodel(has_many = "PlayerWeapon", foreign_key = "player_id", foreign_key = "owner_id")]
+            weapons: Vec<PlayerWeapon>,
+        }
+    };
+
+    let err = expand_read_model(input).expect_err("duplicate relationship foreign key");
+
+    assert!(
+        err.to_string()
+            .contains("foreign_key declared more than once"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn expand_read_model_rejects_duplicate_pending_relationship_through_attrs() {
+    let input: DeriveInput = syn::parse_quote! {
+        #[readmodel(table = "players")]
+        struct Player {
+            #[readmodel(id)]
+            player_id: String,
+            #[readmodel(through = "player_weapon_links", through = "weapon_players", many_to_many = "Weapon")]
+            weapons: Vec<Weapon>,
+        }
+    };
+
+    let err = expand_read_model(input).expect_err("duplicate pending relationship through");
+
+    assert!(
+        err.to_string().contains("through declared more than once"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn snake_case_preserves_multi_char_lowercase_mapping() {
+    assert_eq!(to_snake_case("İdView"), "i\u{307}d_view");
+}
diff --git a/distributed_macros/src/read_model/types.rs b/distributed_macros/src/read_model/types.rs
new file mode 100644
index 00000000..ae557c22
--- /dev/null
+++ b/distributed_macros/src/read_model/types.rs
@@ -0,0 +1,193 @@
+use quote::{quote, ToTokens};
+use syn::{Field, GenericArgument, PathArguments, Type};
+
+pub(super) fn option_string_tokens(value: Option<&str>) -> proc_macro2::TokenStream {
+    match value {
+        Some(value) => quote! { Some(#value.to_string()) },
+        None => quote! { None },
+    }
+}
+
+pub(super) fn column_type_tokens(ty: &Type, jsonb: bool, text: bool) -> proc_macro2::TokenStream {
+    if jsonb {
+        return quote! { distributed::ColumnType::Json };
+    }
+    if text {
+        return quote! { distributed::ColumnType::Text };
+    }
+
+    let ty = option_inner_type(ty).unwrap_or(ty);
+    if let Some(last) = last_type_segment(ty) {
+        let ident = last.ident.to_string();
+        return match ident.as_str() {
+            "String" | "str" => quote! { distributed::ColumnType::Text },
+            "bool" => quote! { distributed::ColumnType::Boolean },
+            "i8" | "i16" | "i32" | "i64" | "isize" => {
+                quote! { distributed::ColumnType::Integer }
+            }
+            "u8" | "u16" | "u32" | "u64" | "usize" => {
+                quote! { distributed::ColumnType::UnsignedInteger }
+            }
+            "f32" | "f64" => quote! { distributed::ColumnType::Float },
+            "Vec" => {
+                if vec_inner_is_u8(last) {
+                    quote! { distributed::ColumnType::Bytes }
+                } else {
+                    quote! { distributed::ColumnType::Json }
+                }
+            }
+            "HashMap" | "BTreeMap" | "Value" => quote! { distributed::ColumnType::Json },
+            _ => {
+                let type_name = ty.to_token_stream().to_string();
+                quote! { distributed::ColumnType::Unsupported(#type_name.to_string()) }
+            }
+        };
+    }
+
+    let type_name = ty.to_token_stream().to_string();
+    quote! { distributed::ColumnType::Unsupported(#type_name.to_string()) }
+}
+
+pub(super) fn effect_model_wire_tokens(
+    ty: &Type,
+    jsonb: bool,
+    text: bool,
+) -> proc_macro2::TokenStream {
+    if jsonb {
+        return quote! { distributed::graphql::EffectWireJson };
+    }
+    if text {
+        return quote! { distributed::graphql::EffectWireString };
+    }
+    let ty = option_inner_type(ty).unwrap_or(ty);
+    let Some(last) = last_type_segment(ty) else {
+        return quote! { distributed::graphql::EffectWireUnsupported };
+    };
+    match last.ident.to_string().as_str() {
+        "String" | "str" => quote! { distributed::graphql::EffectWireString },
+        "bool" => quote! { distributed::graphql::EffectWireBoolean },
+        "i8" | "i16" | "i32" | "i64" | "isize" | "u8" | "u16" | "u32" | "u64" | "usize" => {
+            quote! { distributed::graphql::EffectWireBigInt }
+        }
+        "f32" | "f64" => quote! { distributed::graphql::EffectWireFloat },
+        "Vec" if vec_inner_is_u8(last) => quote! { distributed::graphql::EffectWireBytea },
+        "Vec" | "HashMap" | "BTreeMap" | "Value" => {
+            quote! { distributed::graphql::EffectWireJson }
+        }
+        _ => quote! { distributed::graphql::EffectWireUnsupported },
+    }
+}
+
+pub(super) fn bytes_row_value_tokens(
+    ty: &Type,
+    value: proc_macro2::TokenStream,
+) -> Option<proc_macro2::TokenStream> {
+    let option_inner = option_inner_type(ty);
+    let ty = option_inner.unwrap_or(ty);
+    let segment = last_type_segment(ty)?;
+    if segment.ident != "Vec" || !vec_inner_is_u8(segment) {
+        return None;
+    }
+
+    if option_inner.is_some() {
+        Some(quote! {
+            match &#value {
+                Some(value) => distributed::RowValue::Bytes(value.clone()),
+                None => distributed::RowValue::Null,
+            }
+        })
+    } else {
+        Some(quote! {
+            distributed::RowValue::Bytes(#value.clone())
+        })
+    }
+}
+
+pub(super) fn option_inner_type(ty: &Type) -> Option<&Type> {
+    let segment = last_type_segment(ty)?;
+    if segment.ident != "Option" {
+        return None;
+    }
+    let PathArguments::AngleBracketed(args) = &segment.arguments else {
+        return None;
+    };
+    args.args.iter().find_map(|arg| match arg {
+        GenericArgument::Type(ty) => Some(ty),
+        _ => None,
+    })
+}
+
+pub(super) fn vec_inner_type(ty: &Type) -> Option<&Type> {
+    let segment = last_type_segment(ty)?;
+    if segment.ident != "Vec" {
+        return None;
+    }
+    let PathArguments::AngleBracketed(args) = &segment.arguments else {
+        return None;
+    };
+    args.args.iter().find_map(|arg| match arg {
+        GenericArgument::Type(ty) => Some(ty),
+        _ => None,
+    })
+}
+
+pub(super) fn validate_relationship_target_type(
+    field: &Field,
+    ty: &Type,
+    target_model: &str,
+    field_name: &str,
+) -> syn::Result<()> {
+    let Some(segment) = last_type_segment(ty) else {
+        return Err(syn::Error::new_spanned(
+            field,
+            format!("relationship `{field_name}` target type must be a named read model"),
+        ));
+    };
+    if segment.ident != target_model {
+        return Err(syn::Error::new_spanned(
+            field,
+            format!(
+                "relationship `{field_name}` targets `{target_model}` but the field stores `{}`",
+                segment.ident
+            ),
+        ));
+    }
+    Ok(())
+}
+
+pub(super) fn last_type_segment(ty: &Type) -> Option<&syn::PathSegment> {
+    match ty {
+        Type::Path(path) => path.path.segments.last(),
+        Type::Reference(reference) => last_type_segment(&reference.elem),
+        _ => None,
+    }
+}
+
+pub(super) fn vec_inner_is_u8(segment: &syn::PathSegment) -> bool {
+    let PathArguments::AngleBracketed(args) = &segment.arguments else {
+        return false;
+    };
+    args.args.iter().any(|arg| match arg {
+        GenericArgument::Type(Type::Path(path)) => path
+            .path
+            .segments
+            .last()
+            .is_some_and(|segment| segment.ident == "u8"),
+        _ => false,
+    })
+}
+
+pub(super) fn to_snake_case(s: &str) -> String {
+    let mut result = String::new();
+    for (i, ch) in s.chars().enumerate() {
+        if ch.is_uppercase() {
+            if i > 0 {
+                result.push('_');
+            }
+            result.extend(ch.to_lowercase());
+        } else {
+            result.push(ch);
+        }
+    }
+    result
+}
diff --git a/distributed_macros/src/shared.rs b/distributed_macros/src/shared.rs
new file mode 100644
index 00000000..b30ad757
--- /dev/null
+++ b/distributed_macros/src/shared.rs
@@ -0,0 +1,171 @@
+use quote::quote;
+use syn::{Expr, FnArg, Ident, LitStr, Pat, ReturnType, Type};
+
+// Shared helpers
+// ============================================================================
+
+/// Extract parameter names and types from a method signature (excludes `self`).
+///
+/// Every parameter must be a plain identifier: its name is recorded in the
+/// event payload and used to call the method again on replay. A pattern like
+/// `(a, b): (u8, u8)` or `_: String` has no single name, so silently skipping
+/// it would drop the parameter from the payload and make the generated replay
+/// arm call the method with too few arguments — an arity error pointing at
+/// generated code, far from the cause. Reject it here with a spanned error.
+pub(crate) fn extract_params_with_types(
+    sig: &syn::Signature,
+    attr_name: &str,
+) -> syn::Result<Vec<(Ident, syn::Type)>> {
+    sig.inputs
+        .iter()
+        .filter_map(|arg| match arg {
+            FnArg::Typed(pat_type) => Some(pat_type),
+            FnArg::Receiver(_) => None,
+        })
+        .map(|pat_type| match &*pat_type.pat {
+            Pat::Ident(pat_ident) => Ok((pat_ident.ident.clone(), (*pat_type.ty).clone())),
+            other => Err(syn::Error::new_spanned(
+                other,
+                format!(
+                    "unsupported parameter pattern in #[{attr_name}] method — use a plain identifier"
+                ),
+            )),
+        })
+        .collect()
+}
+
+fn returns_result(sig: &syn::Signature) -> bool {
+    match &sig.output {
+        ReturnType::Default => false,
+        ReturnType::Type(_, ty) => match ty.as_ref() {
+            Type::Path(path) => path.path.segments.last().is_some_and(|segment| {
+                segment.ident == "Result" || segment.ident == "SourcedResult"
+            }),
+            _ => false,
+        },
+    }
+}
+
+pub(crate) fn ensure_sourced_result_signature(
+    sig: &mut syn::Signature,
+    attr_name: &str,
+) -> Result<bool, syn::Error> {
+    match &sig.output {
+        ReturnType::Default => {
+            sig.output = syn::parse_quote!(-> distributed::SourcedResult<()>);
+            Ok(true)
+        }
+        ReturnType::Type(_, _) if returns_result(sig) => Ok(false),
+        ReturnType::Type(_, ty) => Err(syn::Error::new_spanned(
+            ty,
+            format!(
+                "#[{}] methods must return Result<(), E>, SourcedResult, or omit the return type",
+                attr_name
+            ),
+        )),
+    }
+}
+
+/// Generate a digest call token stream.
+pub(crate) fn generate_digest_call(
+    entity_field: &Ident,
+    event_name: &LitStr,
+    param_names: &[&Ident],
+    version: Option<&syn::LitInt>,
+) -> proc_macro2::TokenStream {
+    match version {
+        Some(ver) => {
+            if param_names.is_empty() {
+                quote! { self.#entity_field.digest_v(#event_name, #ver, &())?; }
+            } else if param_names.len() == 1 {
+                let param = param_names[0];
+                quote! { self.#entity_field.digest_v(#event_name, #ver, &(#param.clone(),))?; }
+            } else {
+                quote! { self.#entity_field.digest_v(#event_name, #ver, &(#(#param_names.clone()),*))?; }
+            }
+        }
+        None => {
+            if param_names.is_empty() {
+                quote! { self.#entity_field.digest_empty(#event_name)?; }
+            } else if param_names.len() == 1 {
+                let param = param_names[0];
+                quote! { self.#entity_field.digest(#event_name, &(#param.clone(),))?; }
+            } else {
+                quote! { self.#entity_field.digest(#event_name, &(#(#param_names.clone()),*))?; }
+            }
+        }
+    }
+}
+
+/// Wrap a `Result<(), E>` command method with an optional guard and fallible prelude.
+pub(crate) fn wrap_result_body_with_guard(
+    guard: Option<&Expr>,
+    prepend: proc_macro2::TokenStream,
+    original_block: &syn::Block,
+    signature_synthesized: bool,
+) -> syn::Block {
+    match (guard, signature_synthesized) {
+        (Some(guard), true) => {
+            syn::parse_quote! {
+                {
+                    if #guard {
+                        #prepend
+                        #original_block;
+                    }
+                    Ok(())
+                }
+            }
+        }
+        (Some(guard), false) => {
+            syn::parse_quote! {
+                {
+                    if #guard {
+                        #prepend
+                        (|| #original_block)()?;
+                    }
+                    Ok(())
+                }
+            }
+        }
+        (None, true) => {
+            syn::parse_quote! {
+                {
+                    #prepend
+                    #original_block;
+                    Ok(())
+                }
+            }
+        }
+        (None, false) => {
+            syn::parse_quote! {
+                {
+                    #prepend
+                    (|| #original_block)()?;
+                    Ok(())
+                }
+            }
+        }
+    }
+}
+
+/// Generate an enqueue call token stream (for use within `#[sourced]`).
+pub(crate) fn generate_enqueue_call(
+    entity_field: &Ident,
+    emitter_field: &Ident,
+    event_name: &LitStr,
+    param_names: &[&Ident],
+) -> proc_macro2::TokenStream {
+    let enqueue_expr = if param_names.is_empty() {
+        quote! { self.#emitter_field.enqueue(#event_name, ""); }
+    } else if param_names.len() == 1 {
+        let param = param_names[0];
+        quote! { self.#emitter_field.enqueue_with(#event_name, &(#param.clone(),))?; }
+    } else {
+        quote! { self.#emitter_field.enqueue_with(#event_name, &(#(#param_names.clone()),*))?; }
+    };
+    quote! {
+        if !self.#entity_field.is_replaying() {
+            #enqueue_expr
+        };
+    }
+}
diff --git a/distributed_macros/src/sourced.rs b/distributed_macros/src/sourced.rs
new file mode 100644
index 00000000..8648d0ba
--- /dev/null
+++ b/distributed_macros/src/sourced.rs
@@ -0,0 +1,412 @@
+use proc_macro2::TokenStream as TokenStream2;
+use quote::{format_ident, quote};
+use syn::{
+    parse::{ParseStream, Parser},
+    Expr, FnArg, Ident, ItemImpl, LitStr, Token,
+};
+
+use crate::aggregate::{
+    aggregate_impl_tokens, event_variant_ident, generate_upcaster_tokens, parse_upcaster_list,
+    validate_aggregate_type_literal, UpcasterDef,
+};
+use crate::shared::{
+    ensure_sourced_result_signature, extract_params_with_types, generate_digest_call,
+    generate_enqueue_call, wrap_result_body_with_guard,
+};
+
+pub(crate) struct SourcedArgs {
+    entity_field: Ident,
+    enum_name: Option<LitStr>,
+    aggregate_type: Option<LitStr>,
+    enqueue: Option<Ident>, // Some(emitter_field) if enqueue enabled
+    pub(crate) upcasters: Vec<UpcasterDef>,
+}
+
+pub(crate) fn parse_sourced_args(input: ParseStream) -> syn::Result<SourcedArgs> {
+    if input.is_empty() {
+        return Err(
+            input.error("#[sourced] requires the entity field name, e.g. `#[sourced(entity)]`")
+        );
+    }
+    let entity_field: Ident = input.parse()?;
+    let mut enum_name = None;
+    let mut aggregate_type = None;
+    let mut enqueue = None;
+    let mut upcasters = Vec::new();
+
+    while input.peek(Token![,]) {
+        input.parse::<Token![,]>()?;
+        // Allow (and ignore) a trailing comma.
+        if input.is_empty() {
+            break;
+        }
+        let kw: Ident = input.parse()?;
+        if kw == "events" {
+            input.parse::<Token![=]>()?;
+            enum_name = Some(input.parse::<LitStr>()?);
+        } else if kw == "aggregate_type" {
+            input.parse::<Token![=]>()?;
+            let lit = input.parse::<LitStr>()?;
+            validate_aggregate_type_literal(&lit)?;
+            aggregate_type = Some(lit);
+        } else if kw == "enqueue" {
+            // Optional custom emitter field: enqueue(my_emitter)
+            if input.peek(syn::token::Paren) {
+                let inner;
+                syn::parenthesized!(inner in input);
+                enqueue = Some(inner.parse::<Ident>()?);
+            } else {
+                enqueue = Some(format_ident!("emitter"));
+            }
+        } else if kw == "upcasters" {
+            let upcaster_content;
+            syn::parenthesized!(upcaster_content in input);
+            upcasters = parse_upcaster_list(&upcaster_content)?;
+        } else {
+            return Err(syn::Error::new_spanned(
+                &kw,
+                format!(
+                    "unsupported key `{kw}` in #[sourced(...)]; expected `events`, `aggregate_type`, `enqueue`, or `upcasters`"
+                ),
+            ));
+        }
+    }
+
+    Ok(SourcedArgs {
+        entity_field,
+        enum_name,
+        aggregate_type,
+        enqueue,
+        upcasters,
+    })
+}
+
+pub(crate) struct EventAttr {
+    event_name: LitStr,
+    guard: Option<Expr>,
+    version: Option<syn::LitInt>,
+}
+
+pub(crate) fn parse_event_args(input: ParseStream) -> syn::Result<EventAttr> {
+    let event_name: LitStr = input.parse()?;
+    let mut guard = None;
+    let mut version = None;
+
+    while input.peek(Token![,]) {
+        input.parse::<Token![,]>()?;
+        // Allow (and ignore) a trailing comma.
+        if input.is_empty() {
+            break;
+        }
+        let ident: Ident = input.parse()?;
+        if ident == "when" {
+            input.parse::<Token![=]>()?;
+            guard = Some(input.parse()?);
+        } else if ident == "version" {
+            input.parse::<Token![=]>()?;
+            version = Some(input.parse()?);
+        } else {
+            return Err(syn::Error::new_spanned(
+                &ident,
+                format!("unsupported key `{ident}` in #[event(...)]; expected `when` or `version`"),
+            ));
+        }
+    }
+
+    Ok(EventAttr {
+        event_name,
+        guard,
+        version,
+    })
+}
+
+fn find_and_remove_event_attr(
+    attrs: &mut Vec<syn::Attribute>,
+) -> Result<Option<EventAttr>, syn::Error> {
+    let idx = attrs.iter().position(|a| a.path().is_ident("event"));
+    match idx {
+        Some(idx) => {
+            let attr = attrs.remove(idx);
+            let event_attr = attr.parse_args_with(parse_event_args)?;
+            Ok(Some(event_attr))
+        }
+        None => Ok(None),
+    }
+}
+
+struct EventMethodInfo {
+    event_name: LitStr,
+    method_name: Ident,
+    params: Vec<(Ident, syn::Type)>,
+}
+
+pub(crate) fn expand_sourced(attr: TokenStream2, item: TokenStream2) -> syn::Result<TokenStream2> {
+    let args = parse_sourced_args.parse2(attr)?;
+    let mut impl_block = syn::parse2::<ItemImpl>(item)?;
+
+    // Extract struct name from self type
+    let struct_name = match &*impl_block.self_ty {
+        syn::Type::Path(type_path) => match type_path.path.segments.last() {
+            Some(segment) => segment.ident.clone(),
+            None => {
+                return Err(syn::Error::new_spanned(
+                    &impl_block.self_ty,
+                    "#[sourced] requires a named type",
+                ));
+            }
+        },
+        _ => {
+            return Err(syn::Error::new_spanned(
+                &impl_block.self_ty,
+                "#[sourced] requires a named type",
+            ));
+        }
+    };
+
+    // Collect event info and modify methods
+    let mut event_methods: Vec<EventMethodInfo> = Vec::new();
+    // Detect duplicate event names so the conflict points at the offending
+    // attribute instead of surfacing as a confusing duplicate match arm later.
+    let mut seen_events: std::collections::HashSet<String> = std::collections::HashSet::new();
+    // Distinct event names can still derive the same enum variant because only
+    // the last `.`-segment is PascalCased (`user.completed` and
+    // `admin.completed` both become `Completed`). Track the derived idents so
+    // the collision is reported here, naming both event strings, instead of as
+    // a duplicate-variant error inside the generated enum.
+    let mut seen_variants: std::collections::HashMap<String, LitStr> =
+        std::collections::HashMap::new();
+
+    for item in &mut impl_block.items {
+        if let syn::ImplItem::Fn(method) = item {
+            match find_and_remove_event_attr(&mut method.attrs) {
+                Ok(Some(event_attr)) => {
+                    // Event methods are replayed as `self.method(...)`, so they
+                    // must take a `self` receiver. Reject free associated
+                    // functions up front with a pointed message.
+                    if !matches!(method.sig.inputs.first(), Some(FnArg::Receiver(_))) {
+                        return Err(syn::Error::new_spanned(
+                            &method.sig,
+                            "#[event] methods must take a `&mut self` receiver",
+                        ));
+                    }
+
+                    let event_key = event_attr.event_name.value();
+                    if !seen_events.insert(event_key.clone()) {
+                        return Err(syn::Error::new_spanned(
+                            &event_attr.event_name,
+                            format!("duplicate #[event] name `{event_key}` in this #[sourced] impl block"),
+                        ));
+                    }
+
+                    let variant = event_variant_ident(&event_attr.event_name);
+                    if let Some(prev) = seen_variants.get(&variant.to_string()) {
+                        return Err(syn::Error::new_spanned(
+                            &event_attr.event_name,
+                            format!(
+                                "#[event] names `{}` and `{event_key}` both derive the enum variant `{variant}`; rename one so the variant names are distinct",
+                                prev.value()
+                            ),
+                        ));
+                    }
+                    seen_variants.insert(variant.to_string(), event_attr.event_name.clone());
+
+                    let signature_synthesized =
+                        ensure_sourced_result_signature(&mut method.sig, "event")?;
+
+                    let params = extract_params_with_types(&method.sig, "event")?;
+                    let param_name_refs: Vec<&Ident> =
+                        params.iter().map(|(name, _)| name).collect();
+
+                    // Build prepend: optional enqueue + digest
+                    let enqueue_call = args.enqueue.as_ref().map(|emitter_field| {
+                        generate_enqueue_call(
+                            &args.entity_field,
+                            emitter_field,
+                            &event_attr.event_name,
+                            &param_name_refs,
+                        )
+                    });
+                    let digest_call = generate_digest_call(
+                        &args.entity_field,
+                        &event_attr.event_name,
+                        &param_name_refs,
+                        event_attr.version.as_ref(),
+                    );
+                    let prepend = quote! {
+                        #enqueue_call
+                        #digest_call
+                    };
+
+                    let new_body = wrap_result_body_with_guard(
+                        event_attr.guard.as_ref(),
+                        prepend,
+                        &method.block,
+                        signature_synthesized,
+                    );
+                    method.block = new_body;
+
+                    event_methods.push(EventMethodInfo {
+                        event_name: event_attr.event_name,
+                        method_name: method.sig.ident.clone(),
+                        params,
+                    });
+                }
+                Ok(None) => { /* not an event method, skip */ }
+                Err(err) => return Err(err),
+            }
+        }
+    }
+
+    // Determine enum name
+    let enum_name = if let Some(ref custom) = args.enum_name {
+        format_ident!("{}", custom.value())
+    } else {
+        format_ident!("{}Event", struct_name)
+    };
+
+    // Generate event enum
+    let enum_variants = event_methods.iter().map(|e| {
+        let variant_name = event_variant_ident(&e.event_name);
+        if e.params.is_empty() {
+            quote! { #variant_name }
+        } else {
+            let fields = e.params.iter().map(|(name, ty)| quote! { #name: #ty });
+            quote! { #variant_name { #(#fields),* } }
+        }
+    });
+
+    let enum_def = quote! {
+        #[allow(clippy::enum_variant_names)]
+        #[derive(Debug, Clone, PartialEq)]
+        pub enum #enum_name {
+            #(#enum_variants),*
+        }
+    };
+
+    // Generate event_name() method on the enum
+    let event_name_arms = event_methods.iter().map(|e| {
+        let variant_name = event_variant_ident(&e.event_name);
+        let name_str = &e.event_name;
+        if e.params.is_empty() {
+            quote! { #enum_name::#variant_name => #name_str }
+        } else {
+            quote! { #enum_name::#variant_name { .. } => #name_str }
+        }
+    });
+
+    let event_name_impl = quote! {
+        impl #enum_name {
+            pub fn event_name(&self) -> &'static str {
+                match self {
+                    #(#event_name_arms),*
+                }
+            }
+        }
+    };
+
+    // Generate TryFrom<&EventRecord>
+    let try_from_arms = event_methods.iter().map(|e| {
+        let variant_name = event_variant_ident(&e.event_name);
+        let event_name_str = &e.event_name;
+        if e.params.is_empty() {
+            quote! {
+                #event_name_str => Ok(#enum_name::#variant_name),
+            }
+        } else if e.params.len() == 1 {
+            let (name, _) = &e.params[0];
+            quote! {
+                #event_name_str => {
+                    let (#name,) = event.decode().map_err(|e| e.to_string())?;
+                    Ok(#enum_name::#variant_name { #name })
+                }
+            }
+        } else {
+            let names: Vec<_> = e.params.iter().map(|(n, _)| n).collect();
+            quote! {
+                #event_name_str => {
+                    let (#(#names),*) = event.decode().map_err(|e| e.to_string())?;
+                    Ok(#enum_name::#variant_name { #(#names),* })
+                }
+            }
+        }
+    });
+
+    let try_from_impl = quote! {
+        impl TryFrom<&distributed::EventRecord> for #enum_name {
+            type Error = String;
+            fn try_from(event: &distributed::EventRecord) -> Result<Self, Self::Error> {
+                match event.event_name.as_str() {
+                    #(#try_from_arms)*
+                    _ => Err(format!("Unknown event: {}", event.event_name)),
+                }
+            }
+        }
+    };
+
+    // Generate impl Aggregate
+    let entity_field = &args.entity_field;
+    let replay_arms: Vec<_> = event_methods
+        .iter()
+        .map(|e| {
+            let event_name_str = &e.event_name;
+            let method_name = &e.method_name;
+            if e.params.is_empty() {
+                quote! {
+                    #event_name_str => {
+                        self.#method_name().map_err(|e| e.to_string())?;
+                    }
+                }
+            } else if e.params.len() == 1 {
+                let (name, _) = &e.params[0];
+                quote! {
+                    #event_name_str => {
+                        let (#name,) = event.decode().map_err(|e| e.to_string())?;
+                        self.#method_name(#name).map_err(|e| e.to_string())?;
+                    }
+                }
+            } else {
+                let names: Vec<_> = e.params.iter().map(|(n, _)| n).collect();
+                quote! {
+                    #event_name_str => {
+                        let (#(#names),*) = event.decode().map_err(|e| e.to_string())?;
+                        self.#method_name(#(#names),*).map_err(|e| e.to_string())?;
+                    }
+                }
+            }
+        })
+        .collect();
+
+    let (upcaster_wrappers, upcasters_method) =
+        generate_upcaster_tokens(&struct_name, &args.upcasters);
+    let aggregate_type_method = args.aggregate_type.as_ref().map(|aggregate_type| {
+        quote! {
+            fn aggregate_type() -> &'static str {
+                #aggregate_type
+            }
+        }
+    });
+
+    // ReplayError stays `String` — see the rationale on `expand_aggregate`.
+    let aggregate_impl = aggregate_impl_tokens(
+        &struct_name,
+        entity_field,
+        &aggregate_type_method,
+        &replay_arms,
+        &upcasters_method,
+    );
+
+    let expanded = quote! {
+        #impl_block
+        #enum_def
+        #event_name_impl
+        #try_from_impl
+        #upcaster_wrappers
+        #aggregate_impl
+    };
+
+    Ok(expanded)
+}
+
+// ============================================================================
+// #[derive(ReadModel)] derive macro
+// ============================================================================
diff --git a/distributed_macros/tests/command_effects.rs b/distributed_macros/tests/command_effects.rs
new file mode 100644
index 00000000..f4b46537
--- /dev/null
+++ b/distributed_macros/tests/command_effects.rs
@@ -0,0 +1,214 @@
+#![allow(dead_code)]
+
+use distributed::graphql::SurfaceProjector;
+use distributed::{
+    command_confirmations, command_effects, command_input_defaults, GraphqlInput, ReadModel,
+    RelationalReadModel,
+};
+use serde::{Deserialize, Serialize};
+
+#[derive(GraphqlInput)]
+struct UpdateTodo {
+    tenant_id: String,
+    todo_id: String,
+    title: String,
+    optional_title: Option<String>,
+    generated_id: String,
+}
+
+#[derive(GraphqlInput)]
+struct TodoDetails {
+    title: String,
+}
+
+#[derive(GraphqlInput)]
+struct NestedUpdateTodo {
+    tenant_id: String,
+    todo_id: String,
+    details: TodoDetails,
+    optional_details: Option<TodoDetails>,
+    generated_id: String,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+enum TodoStatus {
+    Open,
+    Closed,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+enum TextKey {
+    Primary,
+}
+
+#[derive(Clone, ReadModel)]
+#[readmodel(table = "text_key_views", primary_key = ["key"])]
+struct TextKeyView {
+    #[readmodel(text)]
+    key: TextKey,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+enum StructuredTextKey {
+    Payload { value: String },
+}
+
+#[derive(Clone, ReadModel)]
+#[readmodel(table = "structured_text_key_views", primary_key = ["key"])]
+struct StructuredTextKeyView {
+    #[readmodel(text)]
+    key: StructuredTextKey,
+}
+
+#[derive(GraphqlInput)]
+struct LinkTodo {
+    parent_id: String,
+    child_id: String,
+}
+
+#[derive(Clone, ReadModel)]
+#[readmodel(table = "child_views", primary_key = ["child_id"])]
+struct ChildView {
+    child_id: String,
+}
+
+#[derive(Clone, ReadModel)]
+#[readmodel(table = "parent_views", primary_key = ["parent_id"])]
+struct ParentView {
+    parent_id: String,
+    #[readmodel(has_many = "ChildView", foreign_key = "parent_id")]
+    children: Vec<ChildView>,
+}
+
+#[derive(Clone, ReadModel)]
+#[readmodel(table = "todo_views", primary_key = ["tenant_id", "todo_id"])]
+struct TodoView {
+    tenant_id: String,
+    todo_id: String,
+    title: String,
+    completed: bool,
+    count: i64,
+    optional_title: Option<String>,
+    generated_id: String,
+    #[readmodel(text)]
+    status: TodoStatus,
+}
+
+#[test]
+fn command_effects_compile_complete_typed_keys_and_assignments() {
+    let _defaults = command_input_defaults! {
+        input: UpdateTodo;
+        default input.generated_id = uuid_v7();
+    };
+    let _effects = command_effects! {
+        input: UpdateTodo;
+        upsert TodoView {
+            key { tenant_id: input.tenant_id, todo_id: input.todo_id },
+            set {
+                title: input.title,
+                completed: false,
+                optional_title: input.optional_title,
+                generated_id: input.generated_id,
+                status: constant(TodoStatus::Open)
+            }
+        };
+        patch TodoView {
+            key { tenant_id: input.tenant_id, todo_id: input.todo_id },
+            set { title: input.title, count: constant(-1) }
+        };
+        patch TodoView {
+            key {
+                tenant_id: trusted("x-tenant-id"),
+                todo_id: input.todo_id
+            },
+            set { status: trusted("x-default-status") }
+        };
+        delete TodoView {
+            key { tenant_id: input.tenant_id, todo_id: input.todo_id }
+        };
+        invalidate TodoView;
+    };
+}
+
+#[test]
+fn nested_nullable_constants_and_ulid_default_compile() {
+    let _defaults = command_input_defaults! {
+        input: NestedUpdateTodo;
+        default input.generated_id = ulid();
+    };
+    let _effects = command_effects! {
+        input: NestedUpdateTodo;
+        patch TodoView {
+            key { tenant_id: input.tenant_id, todo_id: input.todo_id },
+            set {
+                title: input.details<TodoDetails>.title,
+                optional_title: input.optional_details<TodoDetails>.title,
+                generated_id: input.generated_id,
+                status: constant(TodoStatus::Closed)
+            }
+        };
+        patch TodoView {
+            key { tenant_id: input.tenant_id, todo_id: input.todo_id },
+            set { optional_title: null() }
+        };
+    };
+}
+
+#[test]
+fn text_backed_unit_enum_round_trips_and_structured_values_fail_closed() {
+    let view = TextKeyView {
+        key: TextKey::Primary,
+    };
+    let row = view.to_row().unwrap();
+    assert_eq!(row.get_serde::<TextKey>("key").unwrap(), TextKey::Primary);
+    assert_eq!(
+        view.primary_key().unwrap().values["key"],
+        distributed::RowValue::String("Primary".into())
+    );
+
+    let structured = StructuredTextKeyView {
+        key: StructuredTextKey::Payload {
+            value: "not scalar text".into(),
+        },
+    };
+    for error in [
+        structured.to_row().unwrap_err(),
+        structured.primary_key().unwrap_err(),
+    ] {
+        assert!(error
+            .to_string()
+            .contains("must serialize as a JSON string; got object"));
+    }
+}
+
+#[test]
+fn finite_confirmation_plan_reuses_the_projector_declaration() {
+    let projector = SurfaceProjector::new("project_todos")
+        .facts(["todo.changed"])
+        .models(["TodoView"]);
+    let _confirmations = command_confirmations! {
+        input: UpdateTodo;
+        confirm projector -> TodoView {
+            key { tenant_id: input.tenant_id, todo_id: input.todo_id },
+            partition: input.tenant_id
+        };
+    };
+}
+
+#[test]
+fn command_effects_compile_typed_relationships() {
+    let _effects = command_effects! {
+        input: LinkTodo;
+        link ParentView.children -> ChildView {
+            source { parent_id: input.parent_id },
+            target { child_id: input.child_id }
+        };
+        unlink ParentView.children -> ChildView {
+            source { parent_id: input.parent_id },
+            target { child_id: input.child_id }
+        };
+        invalidate ParentView.children {
+            source { parent_id: input.parent_id }
+        };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail.rs b/distributed_macros/tests/command_effects_compile_fail.rs
new file mode 100644
index 00000000..d12f106b
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail.rs
@@ -0,0 +1,7 @@
+//! Compile-time guarantees for typed command declarations and effect IR.
+
+#[test]
+fn command_effects_compile_fail() {
+    let tests = trybuild::TestCases::new();
+    tests.compile_fail("tests/command_effects_compile_fail/*.rs");
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/anonymous_generated_effect.rs b/distributed_macros/tests/command_effects_compile_fail/anonymous_generated_effect.rs
new file mode 100644
index 00000000..2d3db845
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/anonymous_generated_effect.rs
@@ -0,0 +1,24 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(GraphqlInput)]
+struct Input {
+    id: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+    generated_id: String,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        patch View {
+            key { id: input.id },
+            set { generated_id: uuid_v7() }
+        };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/anonymous_generated_effect.stderr b/distributed_macros/tests/command_effects_compile_fail/anonymous_generated_effect.stderr
new file mode 100644
index 00000000..6d7c9ec7
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/anonymous_generated_effect.stderr
@@ -0,0 +1,5 @@
+error: uuid_v7() cannot be used as an anonymous effect value; declare `default input.field = uuid_v7()` with command_input_defaults! and reference `input.field`
+  --> tests/command_effects_compile_fail/anonymous_generated_effect.rs:21:33
+   |
+21 |             set { generated_id: uuid_v7() }
+   |                                 ^^^^^^^
diff --git a/distributed_macros/tests/command_effects_compile_fail/assignment_type_mismatch.rs b/distributed_macros/tests/command_effects_compile_fail/assignment_type_mismatch.rs
new file mode 100644
index 00000000..e2f01832
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/assignment_type_mismatch.rs
@@ -0,0 +1,24 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+
+#[derive(GraphqlInput)]
+struct Input {
+    view_id: String,
+    title: String,
+}
+
+#[derive(Clone, ReadModel)]
+#[readmodel(table = "views", primary_key = ["view_id"])]
+struct View {
+    view_id: String,
+    count: i64,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        patch View {
+            key { view_id: input.view_id },
+            set { count: input.title }
+        };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/assignment_type_mismatch.stderr b/distributed_macros/tests/command_effects_compile_fail/assignment_type_mismatch.stderr
new file mode 100644
index 00000000..c75d31df
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/assignment_type_mismatch.stderr
@@ -0,0 +1,31 @@
+error[E0277]: the trait bound `distributed::graphql::TypedEffectExpression<std::string::String, distributed::graphql::EffectWireString>: distributed::graphql::EffectAssignmentExpression<i64>` is not satisfied
+  --> tests/command_effects_compile_fail/assignment_type_mismatch.rs:17:13
+   |
+17 |       let _ = command_effects! {
+   |  _____________^
+18 | |         input: Input;
+19 | |         patch View {
+20 | |             key { view_id: input.view_id },
+21 | |             set { count: input.title }
+22 | |         };
+23 | |     };
+   | |_____^ unsatisfied trait bound
+   |
+   = help: the trait `distributed::graphql::EffectAssignmentExpression<i64>` is not implemented for `distributed::graphql::TypedEffectExpression<std::string::String, distributed::graphql::EffectWireString>`
+help: `distributed::graphql::TypedEffectExpression<T, Wire>` implements trait `distributed::graphql::EffectAssignmentExpression<Target>`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | impl<T, Wire> EffectAssignmentExpression<T> for TypedEffectExpression<T, Wire> {
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `distributed::graphql::EffectAssignmentExpression<T>`
+...
+   | impl<T, Wire> EffectAssignmentExpression<Option<T>> for TypedEffectExpression<T, Wire> {
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `distributed::graphql::EffectAssignmentExpression<Option<T>>`
+note: required by a bound in `distributed::graphql::__effect_assignment`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | pub fn __effect_assignment<F, E>(value: E) -> CompiledEffectFieldValue<F::Model>
+   |        ------------------- required by a bound in this function
+...
+   |     E: EffectAssignmentExpression<F::Value>,
+   |        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `__effect_assignment`
+   = note: this error originates in the macro `command_effects` (in Nightly builds, run with -Z macro-backtrace for more info)
diff --git a/distributed_macros/tests/command_effects_compile_fail/causal_context_has_no_repository.rs b/distributed_macros/tests/command_effects_compile_fail/causal_context_has_no_repository.rs
new file mode 100644
index 00000000..d3312926
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/causal_context_has_no_repository.rs
@@ -0,0 +1,31 @@
+use distributed::microsvc::CausalCommandContext;
+use distributed::{Aggregate, Entity, EventRecord};
+
+#[derive(Default)]
+struct FixtureAggregate {
+    entity: Entity,
+}
+
+impl Aggregate for FixtureAggregate {
+    type ReplayError = String;
+
+    fn entity(&self) -> &Entity {
+        &self.entity
+    }
+
+    fn entity_mut(&mut self) -> &mut Entity {
+        &mut self.entity
+    }
+
+    fn replay_event(&mut self, _event: &EventRecord) -> Result<(), Self::ReplayError> {
+        Ok(())
+    }
+}
+
+fn handler(context: &CausalCommandContext<'_, FixtureAggregate>) {
+    let _ = context.repo();
+    let _ = context.dependencies();
+    let _ = context.read_model_store();
+}
+
+fn main() {}
diff --git a/distributed_macros/tests/command_effects_compile_fail/causal_context_has_no_repository.stderr b/distributed_macros/tests/command_effects_compile_fail/causal_context_has_no_repository.stderr
new file mode 100644
index 00000000..881c487b
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/causal_context_has_no_repository.stderr
@@ -0,0 +1,17 @@
+error[E0599]: no method named `repo` found for reference `&CausalCommandContext<'_, FixtureAggregate>` in the current scope
+  --> tests/command_effects_compile_fail/causal_context_has_no_repository.rs:26:21
+   |
+26 |     let _ = context.repo();
+   |                     ^^^^ method not found in `&CausalCommandContext<'_, FixtureAggregate>`
+
+error[E0599]: no method named `dependencies` found for reference `&CausalCommandContext<'_, FixtureAggregate>` in the current scope
+  --> tests/command_effects_compile_fail/causal_context_has_no_repository.rs:27:21
+   |
+27 |     let _ = context.dependencies();
+   |                     ^^^^^^^^^^^^ method not found in `&CausalCommandContext<'_, FixtureAggregate>`
+
+error[E0599]: no method named `read_model_store` found for reference `&CausalCommandContext<'_, FixtureAggregate>` in the current scope
+  --> tests/command_effects_compile_fail/causal_context_has_no_repository.rs:28:21
+   |
+28 |     let _ = context.read_model_store();
+   |                     ^^^^^^^^^^^^^^^^ method not found in `&CausalCommandContext<'_, FixtureAggregate>`
diff --git a/distributed_macros/tests/command_effects_compile_fail/committed_outcome_constructor.rs b/distributed_macros/tests/command_effects_compile_fail/committed_outcome_constructor.rs
new file mode 100644
index 00000000..1a4b3aff
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/committed_outcome_constructor.rs
@@ -0,0 +1,7 @@
+use distributed::graphql::Accepted;
+
+fn main() {
+    let _ = Accepted {
+        payload: String::from("not committed"),
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/committed_outcome_constructor.stderr b/distributed_macros/tests/command_effects_compile_fail/committed_outcome_constructor.stderr
new file mode 100644
index 00000000..fc1e430f
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/committed_outcome_constructor.stderr
@@ -0,0 +1,7 @@
+error[E0451]: field `payload` of struct `distributed::graphql::Accepted` is private
+ --> tests/command_effects_compile_fail/committed_outcome_constructor.rs:5:9
+  |
+4 |     let _ = Accepted {
+  |             -------- in this type
+5 |         payload: String::from("not committed"),
+  |         ^^^^^^^ private field
diff --git a/distributed_macros/tests/command_effects_compile_fail/confirmation_input_type_mismatch.rs b/distributed_macros/tests/command_effects_compile_fail/confirmation_input_type_mismatch.rs
new file mode 100644
index 00000000..3aba297d
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/confirmation_input_type_mismatch.rs
@@ -0,0 +1,35 @@
+use distributed::graphql::{typed_command, Accepted, SurfaceProjector};
+use distributed::{command_confirmations, GraphqlInput, GraphqlOutput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, GraphqlInput)]
+struct InputA {
+    id: String,
+}
+
+#[derive(Deserialize, GraphqlInput)]
+struct InputB {
+    id: String,
+}
+
+#[derive(Serialize, GraphqlOutput)]
+struct Output {
+    id: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+}
+
+fn main() {
+    let projector = SurfaceProjector::new("views")
+        .facts(["view.changed"])
+        .models(["View"]);
+    let confirmations = command_confirmations! {
+        input: InputB;
+        confirm projector -> View { key { id: input.id } };
+    };
+    let _ = typed_command::<InputA, Accepted<Output>>("view.create").confirmations(confirmations);
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/confirmation_input_type_mismatch.stderr b/distributed_macros/tests/command_effects_compile_fail/confirmation_input_type_mismatch.stderr
new file mode 100644
index 00000000..558bc659
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/confirmation_input_type_mismatch.stderr
@@ -0,0 +1,15 @@
+error[E0308]: mismatched types
+  --> tests/command_effects_compile_fail/confirmation_input_type_mismatch.rs:34:84
+   |
+34 |     let _ = typed_command::<InputA, Accepted<Output>>("view.create").confirmations(confirmations);
+   |                                                                      ------------- ^^^^^^^^^^^^^ expected `CompiledConfirmationPlan<InputA>`, found `CompiledConfirmationPlan<InputB>`
+   |                                                                      |
+   |                                                                      arguments to this method are incorrect
+   |
+   = note: expected struct `CompiledConfirmationPlan<InputA>`
+              found struct `CompiledConfirmationPlan<InputB>`
+note: method defined here
+  --> $WORKSPACE/src/graphql/command_contract/typed_command.rs
+   |
+   |     pub fn confirmations(mut self, confirmations: CompiledConfirmationPlan<I>) -> Self {
+   |            ^^^^^^^^^^^^^
diff --git a/distributed_macros/tests/command_effects_compile_fail/constant_enum_type_mismatch.rs b/distributed_macros/tests/command_effects_compile_fail/constant_enum_type_mismatch.rs
new file mode 100644
index 00000000..13625942
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/constant_enum_type_mismatch.rs
@@ -0,0 +1,26 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(GraphqlInput)]
+struct Input {
+    id: String,
+}
+
+#[derive(Serialize)]
+enum Status {
+    Open,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+    count: i64,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        patch View { key { id: input.id }, set { count: constant(Status::Open) } };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/constant_enum_type_mismatch.stderr b/distributed_macros/tests/command_effects_compile_fail/constant_enum_type_mismatch.stderr
new file mode 100644
index 00000000..e7b9972a
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/constant_enum_type_mismatch.stderr
@@ -0,0 +1,28 @@
+error[E0277]: the trait bound `distributed::graphql::TypedEffectExpression<Status, distributed::graphql::EffectWireLiteral>: distributed::graphql::EffectAssignmentExpression<i64>` is not satisfied
+  --> tests/command_effects_compile_fail/constant_enum_type_mismatch.rs:22:13
+   |
+22 |       let _ = command_effects! {
+   |  _____________^
+23 | |         input: Input;
+24 | |         patch View { key { id: input.id }, set { count: constant(Status::Open) } };
+25 | |     };
+   | |_____^ unsatisfied trait bound
+   |
+   = help: the trait `distributed::graphql::EffectAssignmentExpression<i64>` is not implemented for `distributed::graphql::TypedEffectExpression<Status, distributed::graphql::EffectWireLiteral>`
+help: `distributed::graphql::TypedEffectExpression<T, Wire>` implements trait `distributed::graphql::EffectAssignmentExpression<Target>`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | impl<T, Wire> EffectAssignmentExpression<T> for TypedEffectExpression<T, Wire> {
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `distributed::graphql::EffectAssignmentExpression<T>`
+...
+   | impl<T, Wire> EffectAssignmentExpression<Option<T>> for TypedEffectExpression<T, Wire> {
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `distributed::graphql::EffectAssignmentExpression<std::option::Option<T>>`
+note: required by a bound in `distributed::graphql::__effect_assignment`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | pub fn __effect_assignment<F, E>(value: E) -> CompiledEffectFieldValue<F::Model>
+   |        ------------------- required by a bound in this function
+...
+   |     E: EffectAssignmentExpression<F::Value>,
+   |        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `__effect_assignment`
+   = note: this error originates in the macro `command_effects` (in Nightly builds, run with -Z macro-backtrace for more info)
diff --git a/distributed_macros/tests/command_effects_compile_fail/duplicate_input_default.rs b/distributed_macros/tests/command_effects_compile_fail/duplicate_input_default.rs
new file mode 100644
index 00000000..e5d08c43
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/duplicate_input_default.rs
@@ -0,0 +1,14 @@
+use distributed::{command_input_defaults, GraphqlInput};
+
+#[derive(GraphqlInput)]
+struct Input {
+    id: String,
+}
+
+fn main() {
+    let _ = command_input_defaults! {
+        input: Input;
+        default input.id = uuid_v7();
+        default input.id = ulid();
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/duplicate_input_default.stderr b/distributed_macros/tests/command_effects_compile_fail/duplicate_input_default.stderr
new file mode 100644
index 00000000..89c5c1a5
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/duplicate_input_default.stderr
@@ -0,0 +1,5 @@
+error: duplicate generated input default `id`
+  --> tests/command_effects_compile_fail/duplicate_input_default.rs:12:23
+   |
+12 |         default input.id = ulid();
+   |                       ^^
diff --git a/distributed_macros/tests/command_effects_compile_fail/duplicate_set_field.rs b/distributed_macros/tests/command_effects_compile_fail/duplicate_set_field.rs
new file mode 100644
index 00000000..aaea950e
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/duplicate_set_field.rs
@@ -0,0 +1,25 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(GraphqlInput)]
+struct Input {
+    id: String,
+    title: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+    title: String,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        patch View {
+            key { id: input.id },
+            set { title: input.title, title: "duplicate" }
+        };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/duplicate_set_field.stderr b/distributed_macros/tests/command_effects_compile_fail/duplicate_set_field.stderr
new file mode 100644
index 00000000..32eccd91
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/duplicate_set_field.stderr
@@ -0,0 +1,5 @@
+error: duplicate command-effect field `title`
+  --> tests/command_effects_compile_fail/duplicate_set_field.rs:22:39
+   |
+22 |             set { title: input.title, title: "duplicate" }
+   |                                       ^^^^^
diff --git a/distributed_macros/tests/command_effects_compile_fail/effect_input_type_mismatch.rs b/distributed_macros/tests/command_effects_compile_fail/effect_input_type_mismatch.rs
new file mode 100644
index 00000000..559f055b
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/effect_input_type_mismatch.rs
@@ -0,0 +1,32 @@
+use distributed::graphql::{typed_command, Accepted};
+use distributed::{command_effects, GraphqlInput, GraphqlOutput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, GraphqlInput)]
+struct InputA {
+    id: String,
+}
+
+#[derive(Deserialize, GraphqlInput)]
+struct InputB {
+    id: String,
+}
+
+#[derive(Serialize, GraphqlOutput)]
+struct Output {
+    id: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+}
+
+fn main() {
+    let effects = command_effects! {
+        input: InputB;
+        delete View { key { id: input.id } };
+    };
+    let _ = typed_command::<InputA, Accepted<Output>>("view.delete").effects(effects);
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/effect_input_type_mismatch.stderr b/distributed_macros/tests/command_effects_compile_fail/effect_input_type_mismatch.stderr
new file mode 100644
index 00000000..9b3a4cb4
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/effect_input_type_mismatch.stderr
@@ -0,0 +1,15 @@
+error[E0308]: mismatched types
+  --> tests/command_effects_compile_fail/effect_input_type_mismatch.rs:31:78
+   |
+31 |     let _ = typed_command::<InputA, Accepted<Output>>("view.delete").effects(effects);
+   |                                                                      ------- ^^^^^^^ expected `CompiledCommandEffects<InputA>`, found `CompiledCommandEffects<InputB>`
+   |                                                                      |
+   |                                                                      arguments to this method are incorrect
+   |
+   = note: expected struct `CompiledCommandEffects<InputA>`
+              found struct `CompiledCommandEffects<InputB>`
+note: method defined here
+  --> $WORKSPACE/src/graphql/command_contract/typed_command.rs
+   |
+   |     pub fn effects(mut self, effects: CompiledCommandEffects<I>) -> Self {
+   |            ^^^^^^^
diff --git a/distributed_macros/tests/command_effects_compile_fail/forged_effect_constructors.rs b/distributed_macros/tests/command_effects_compile_fail/forged_effect_constructors.rs
new file mode 100644
index 00000000..f70cc1bf
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/forged_effect_constructors.rs
@@ -0,0 +1,10 @@
+use distributed::graphql::{TypedEffectExpression, TypedEffectKey, TypedEffectRelationship};
+
+struct Model;
+struct Target;
+
+fn main() {
+    let _ = TypedEffectExpression::<String>::__input("secret");
+    let _ = TypedEffectKey::<Model>::__from_generated("Forged", Vec::new());
+    let _ = TypedEffectRelationship::<Model, Target>::__from_names("Forged", "secret", "Target");
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/forged_effect_constructors.stderr b/distributed_macros/tests/command_effects_compile_fail/forged_effect_constructors.stderr
new file mode 100644
index 00000000..75c48601
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/forged_effect_constructors.stderr
@@ -0,0 +1,17 @@
+error[E0599]: no associated function or constant named `__input` found for struct `distributed::graphql::TypedEffectExpression<T, Wire>` in the current scope
+ --> tests/command_effects_compile_fail/forged_effect_constructors.rs:7:46
+  |
+7 |     let _ = TypedEffectExpression::<String>::__input("secret");
+  |                                              ^^^^^^^ associated function or constant not found in `distributed::graphql::TypedEffectExpression<std::string::String>`
+
+error[E0599]: no associated function or constant named `__from_generated` found for struct `distributed::graphql::TypedEffectKey<M>` in the current scope
+ --> tests/command_effects_compile_fail/forged_effect_constructors.rs:8:38
+  |
+8 |     let _ = TypedEffectKey::<Model>::__from_generated("Forged", Vec::new());
+  |                                      ^^^^^^^^^^^^^^^^ associated function or constant not found in `distributed::graphql::TypedEffectKey<Model>`
+
+error[E0599]: no associated function or constant named `__from_names` found for struct `distributed::graphql::TypedEffectRelationship<S, T>` in the current scope
+ --> tests/command_effects_compile_fail/forged_effect_constructors.rs:9:55
+  |
+9 |     let _ = TypedEffectRelationship::<Model, Target>::__from_names("Forged", "secret", "Target");
+  |                                                       ^^^^^^^^^^^^ associated function or constant not found in `distributed::graphql::TypedEffectRelationship<Model, Target>`
diff --git a/distributed_macros/tests/command_effects_compile_fail/generated_confirmation_identity.rs b/distributed_macros/tests/command_effects_compile_fail/generated_confirmation_identity.rs
new file mode 100644
index 00000000..a2aae7bc
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/generated_confirmation_identity.rs
@@ -0,0 +1,24 @@
+use distributed::graphql::SurfaceProjector;
+use distributed::{command_confirmations, GraphqlInput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(GraphqlInput)]
+struct Input {
+    id: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+}
+
+fn main() {
+    let projector = SurfaceProjector::new("views")
+        .facts(["view.changed"])
+        .models(["View"]);
+    let _ = command_confirmations! {
+        input: Input;
+        confirm projector -> View { key { id: uuid_v7() } };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/generated_confirmation_identity.stderr b/distributed_macros/tests/command_effects_compile_fail/generated_confirmation_identity.stderr
new file mode 100644
index 00000000..1bd2a524
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/generated_confirmation_identity.stderr
@@ -0,0 +1,5 @@
+error: uuid_v7() cannot be used as an anonymous effect value; declare `default input.field = uuid_v7()` with command_input_defaults! and reference `input.field`
+  --> tests/command_effects_compile_fail/generated_confirmation_identity.rs:22:47
+   |
+22 |         confirm projector -> View { key { id: uuid_v7() } };
+   |                                               ^^^^^^^
diff --git a/distributed_macros/tests/command_effects_compile_fail/incomplete_composite_key.rs b/distributed_macros/tests/command_effects_compile_fail/incomplete_composite_key.rs
new file mode 100644
index 00000000..5d12258b
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/incomplete_composite_key.rs
@@ -0,0 +1,21 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+
+#[derive(GraphqlInput)]
+struct Input {
+    tenant_id: String,
+    record_id: String,
+}
+
+#[derive(Clone, ReadModel)]
+#[readmodel(table = "views", primary_key = ["tenant_id", "record_id"])]
+struct View {
+    tenant_id: String,
+    record_id: String,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        delete View { key { record_id: input.record_id } };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/incomplete_composite_key.stderr b/distributed_macros/tests/command_effects_compile_fail/incomplete_composite_key.stderr
new file mode 100644
index 00000000..f6e7a320
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/incomplete_composite_key.stderr
@@ -0,0 +1,5 @@
+error[E0063]: missing field `tenant_id` in initializer of `__DistributedViewEffectKey`
+  --> tests/command_effects_compile_fail/incomplete_composite_key.rs:19:16
+   |
+19 |         delete View { key { record_id: input.record_id } };
+   |                ^^^^ missing `tenant_id`
diff --git a/distributed_macros/tests/command_effects_compile_fail/input_default_list.rs b/distributed_macros/tests/command_effects_compile_fail/input_default_list.rs
new file mode 100644
index 00000000..407564fb
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/input_default_list.rs
@@ -0,0 +1,13 @@
+use distributed::{command_input_defaults, GraphqlInput};
+
+#[derive(GraphqlInput)]
+struct Input {
+    ids: Vec<String>,
+}
+
+fn main() {
+    let _ = command_input_defaults! {
+        input: Input;
+        default input.ids = ulid();
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/input_default_list.stderr b/distributed_macros/tests/command_effects_compile_fail/input_default_list.stderr
new file mode 100644
index 00000000..114fb94d
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/input_default_list.stderr
@@ -0,0 +1,21 @@
+error[E0271]: type mismatch resolving `<__DistributedInputEffectInputField_ids as EffectInputFieldMarker>::Value == String`
+  --> tests/command_effects_compile_fail/input_default_list.rs:11:23
+   |
+11 |         default input.ids = ulid();
+   |                       ^^^ type mismatch resolving `<__DistributedInputEffectInputField_ids as EffectInputFieldMarker>::Value == String`
+   |
+note: expected this to be `std::string::String`
+  --> tests/command_effects_compile_fail/input_default_list.rs:5:10
+   |
+ 5 |     ids: Vec<String>,
+   |          ^^^^^^^^^^^
+   = note: expected struct `std::string::String`
+              found struct `Vec<std::string::String>`
+note: required by a bound in `distributed::graphql::__input_default_ulid`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | pub fn __input_default_ulid<I, F>() -> CompiledInputDefault<I>
+   |        -------------------- required by a bound in this function
+...
+   |     F: EffectInputFieldMarker<Input = I, Value = String>,
+   |                                          ^^^^^^^^^^^^^^ required by this bound in `__input_default_ulid`
diff --git a/distributed_macros/tests/command_effects_compile_fail/input_default_nullable.rs b/distributed_macros/tests/command_effects_compile_fail/input_default_nullable.rs
new file mode 100644
index 00000000..85b8563d
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/input_default_nullable.rs
@@ -0,0 +1,14 @@
+use distributed::{command_input_defaults, GraphqlInput};
+use serde::Deserialize;
+
+#[derive(Deserialize, GraphqlInput)]
+struct Input {
+    id: Option<String>,
+}
+
+fn main() {
+    let _ = command_input_defaults! {
+        input: Input;
+        default input.id = uuid_v7();
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/input_default_nullable.stderr b/distributed_macros/tests/command_effects_compile_fail/input_default_nullable.stderr
new file mode 100644
index 00000000..02f78447
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/input_default_nullable.stderr
@@ -0,0 +1,21 @@
+error[E0271]: type mismatch resolving `<__DistributedInputEffectInputField_id as EffectInputFieldMarker>::Value == String`
+  --> tests/command_effects_compile_fail/input_default_nullable.rs:12:23
+   |
+12 |         default input.id = uuid_v7();
+   |                       ^^ type mismatch resolving `<__DistributedInputEffectInputField_id as EffectInputFieldMarker>::Value == String`
+   |
+note: expected this to be `std::string::String`
+  --> tests/command_effects_compile_fail/input_default_nullable.rs:6:9
+   |
+ 6 |     id: Option<String>,
+   |         ^^^^^^^^^^^^^^
+   = note: expected struct `std::string::String`
+                found enum `std::option::Option<std::string::String>`
+note: required by a bound in `distributed::graphql::__input_default_uuid_v7`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | pub fn __input_default_uuid_v7<I, F>() -> CompiledInputDefault<I>
+   |        ----------------------- required by a bound in this function
+...
+   |     F: EffectInputFieldMarker<Input = I, Value = String>,
+   |                                          ^^^^^^^^^^^^^^ required by this bound in `__input_default_uuid_v7`
diff --git a/distributed_macros/tests/command_effects_compile_fail/input_default_wrong_type.rs b/distributed_macros/tests/command_effects_compile_fail/input_default_wrong_type.rs
new file mode 100644
index 00000000..79e27899
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/input_default_wrong_type.rs
@@ -0,0 +1,13 @@
+use distributed::{command_input_defaults, GraphqlInput};
+
+#[derive(GraphqlInput)]
+struct Input {
+    count: i64,
+}
+
+fn main() {
+    let _ = command_input_defaults! {
+        input: Input;
+        default input.count = uuid_v7();
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/input_default_wrong_type.stderr b/distributed_macros/tests/command_effects_compile_fail/input_default_wrong_type.stderr
new file mode 100644
index 00000000..440499b4
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/input_default_wrong_type.stderr
@@ -0,0 +1,19 @@
+error[E0271]: type mismatch resolving `<__DistributedInputEffectInputField_count as EffectInputFieldMarker>::Value == String`
+  --> tests/command_effects_compile_fail/input_default_wrong_type.rs:11:23
+   |
+11 |         default input.count = uuid_v7();
+   |                       ^^^^^ type mismatch resolving `<__DistributedInputEffectInputField_count as EffectInputFieldMarker>::Value == String`
+   |
+note: expected this to be `std::string::String`
+  --> tests/command_effects_compile_fail/input_default_wrong_type.rs:5:12
+   |
+ 5 |     count: i64,
+   |            ^^^
+note: required by a bound in `distributed::graphql::__input_default_uuid_v7`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | pub fn __input_default_uuid_v7<I, F>() -> CompiledInputDefault<I>
+   |        ----------------------- required by a bound in this function
+...
+   |     F: EffectInputFieldMarker<Input = I, Value = String>,
+   |                                          ^^^^^^^^^^^^^^ required by this bound in `__input_default_uuid_v7`
diff --git a/distributed_macros/tests/command_effects_compile_fail/list_path_descent.rs b/distributed_macros/tests/command_effects_compile_fail/list_path_descent.rs
new file mode 100644
index 00000000..4ba4c66c
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/list_path_descent.rs
@@ -0,0 +1,30 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(GraphqlInput)]
+struct ItemInput {
+    title: String,
+}
+
+#[derive(GraphqlInput)]
+struct Input {
+    id: String,
+    items: Vec<ItemInput>,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+    title: String,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        patch View {
+            key { id: input.id },
+            set { title: input.items<ItemInput>.title }
+        };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/list_path_descent.stderr b/distributed_macros/tests/command_effects_compile_fail/list_path_descent.stderr
new file mode 100644
index 00000000..d986467b
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/list_path_descent.stderr
@@ -0,0 +1,25 @@
+error[E0277]: the trait bound `distributed::graphql::EffectInputTerminalKind: distributed::graphql::EffectInputDescendableKind` is not satisfied
+  --> tests/command_effects_compile_fail/list_path_descent.rs:23:13
+   |
+23 |       let _ = command_effects! {
+   |  _____________^
+24 | |         input: Input;
+25 | |         patch View {
+26 | |             key { id: input.id },
+27 | |             set { title: input.items<ItemInput>.title }
+28 | |         };
+29 | |     };
+   | |_____^ the trait `distributed::graphql::EffectInputDescendableKind` is not implemented for `distributed::graphql::EffectInputTerminalKind`
+   |
+help: the trait `distributed::graphql::EffectInputFieldMarker` is implemented for `distributed::graphql::EffectInputPath<Outer, Inner>`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | / impl<Outer, Inner> EffectInputFieldMarker for EffectInputPath<Outer, Inner>
+   | | where
+   | |     Outer: EffectInputFieldMarker,
+   | |     Inner: EffectInputFieldMarker<Input = Outer::Nested>,
+   | |     Outer::PathKind: EffectInputDescendableKind,
+   | |     Outer::Nullability: CombineEffectNullability<Inner::Nullability>,
+   | |_____________________________________________________________________^
+   = note: required for `distributed::graphql::EffectInputPath<__DistributedInputEffectInputField_items, __DistributedItemInputEffectInputField_title>` to implement `distributed::graphql::EffectInputFieldMarker`
+   = note: this error originates in the macro `command_effects` (in Nightly builds, run with -Z macro-backtrace for more info)
diff --git a/distributed_macros/tests/command_effects_compile_fail/nested_optional_to_nonnull.rs b/distributed_macros/tests/command_effects_compile_fail/nested_optional_to_nonnull.rs
new file mode 100644
index 00000000..7ad91478
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/nested_optional_to_nonnull.rs
@@ -0,0 +1,30 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(GraphqlInput)]
+struct Details {
+    title: String,
+}
+
+#[derive(GraphqlInput)]
+struct Input {
+    id: String,
+    details: Option<Details>,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+    title: String,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        patch View {
+            key { id: input.id },
+            set { title: input.details<Details>.title }
+        };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/nested_optional_to_nonnull.stderr b/distributed_macros/tests/command_effects_compile_fail/nested_optional_to_nonnull.stderr
new file mode 100644
index 00000000..285b62b7
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/nested_optional_to_nonnull.stderr
@@ -0,0 +1,31 @@
+error[E0277]: the trait bound `distributed::graphql::TypedEffectExpression<std::option::Option<std::string::String>, distributed::graphql::EffectWireString>: distributed::graphql::EffectAssignmentExpression<std::string::String>` is not satisfied
+  --> tests/command_effects_compile_fail/nested_optional_to_nonnull.rs:23:13
+   |
+23 |       let _ = command_effects! {
+   |  _____________^
+24 | |         input: Input;
+25 | |         patch View {
+26 | |             key { id: input.id },
+27 | |             set { title: input.details<Details>.title }
+28 | |         };
+29 | |     };
+   | |_____^ unsatisfied trait bound
+   |
+   = help: the trait `distributed::graphql::EffectAssignmentExpression<std::string::String>` is not implemented for `distributed::graphql::TypedEffectExpression<std::option::Option<std::string::String>, distributed::graphql::EffectWireString>`
+help: `distributed::graphql::TypedEffectExpression<T, Wire>` implements trait `distributed::graphql::EffectAssignmentExpression<Target>`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | impl<T, Wire> EffectAssignmentExpression<T> for TypedEffectExpression<T, Wire> {
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `distributed::graphql::EffectAssignmentExpression<T>`
+...
+   | impl<T, Wire> EffectAssignmentExpression<Option<T>> for TypedEffectExpression<T, Wire> {
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `distributed::graphql::EffectAssignmentExpression<std::option::Option<T>>`
+note: required by a bound in `distributed::graphql::__effect_assignment`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | pub fn __effect_assignment<F, E>(value: E) -> CompiledEffectFieldValue<F::Model>
+   |        ------------------- required by a bound in this function
+...
+   |     E: EffectAssignmentExpression<F::Value>,
+   |        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `__effect_assignment`
+   = note: this error originates in the macro `command_effects` (in Nightly builds, run with -Z macro-backtrace for more info)
diff --git a/distributed_macros/tests/command_effects_compile_fail/nondeterministic_constant_call.rs b/distributed_macros/tests/command_effects_compile_fail/nondeterministic_constant_call.rs
new file mode 100644
index 00000000..ee6b4fac
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/nondeterministic_constant_call.rs
@@ -0,0 +1,25 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(GraphqlInput)]
+struct Input {
+    id: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+    count: i64,
+}
+
+fn count() -> i64 {
+    1
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        patch View { key { id: input.id }, set { count: constant(count()) } };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/nondeterministic_constant_call.stderr b/distributed_macros/tests/command_effects_compile_fail/nondeterministic_constant_call.stderr
new file mode 100644
index 00000000..8f488ada
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/nondeterministic_constant_call.stderr
@@ -0,0 +1,5 @@
+error: constant(...) accepts only a primitive literal (including a negative numeric literal) or a const/enum path; calls, macros, blocks, and other operators are not deterministic command-effect IR
+  --> tests/command_effects_compile_fail/nondeterministic_constant_call.rs:23:66
+   |
+23 |         patch View { key { id: input.id }, set { count: constant(count()) } };
+   |                                                                  ^^^^^^^
diff --git a/distributed_macros/tests/command_effects_compile_fail/nondeterministic_constant_operator.rs b/distributed_macros/tests/command_effects_compile_fail/nondeterministic_constant_operator.rs
new file mode 100644
index 00000000..24637e89
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/nondeterministic_constant_operator.rs
@@ -0,0 +1,21 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(GraphqlInput)]
+struct Input {
+    id: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+    count: i64,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        patch View { key { id: input.id }, set { count: constant(1 + 1) } };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/nondeterministic_constant_operator.stderr b/distributed_macros/tests/command_effects_compile_fail/nondeterministic_constant_operator.stderr
new file mode 100644
index 00000000..278b2020
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/nondeterministic_constant_operator.stderr
@@ -0,0 +1,5 @@
+error: constant(...) accepts only a primitive literal (including a negative numeric literal) or a const/enum path; calls, macros, blocks, and other operators are not deterministic command-effect IR
+  --> tests/command_effects_compile_fail/nondeterministic_constant_operator.rs:19:66
+   |
+19 |         patch View { key { id: input.id }, set { count: constant(1 + 1) } };
+   |                                                                  ^^^^^
diff --git a/distributed_macros/tests/command_effects_compile_fail/nullable_assignment_to_nonnull.rs b/distributed_macros/tests/command_effects_compile_fail/nullable_assignment_to_nonnull.rs
new file mode 100644
index 00000000..e7472c05
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/nullable_assignment_to_nonnull.rs
@@ -0,0 +1,22 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(GraphqlInput)]
+struct Input {
+    id: String,
+    title: Option<String>,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+    title: String,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        patch View { key { id: input.id }, set { title: input.title } };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/nullable_assignment_to_nonnull.stderr b/distributed_macros/tests/command_effects_compile_fail/nullable_assignment_to_nonnull.stderr
new file mode 100644
index 00000000..7aac9197
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/nullable_assignment_to_nonnull.stderr
@@ -0,0 +1,28 @@
+error[E0277]: the trait bound `distributed::graphql::TypedEffectExpression<std::option::Option<std::string::String>, distributed::graphql::EffectWireString>: distributed::graphql::EffectAssignmentExpression<std::string::String>` is not satisfied
+  --> tests/command_effects_compile_fail/nullable_assignment_to_nonnull.rs:18:13
+   |
+18 |       let _ = command_effects! {
+   |  _____________^
+19 | |         input: Input;
+20 | |         patch View { key { id: input.id }, set { title: input.title } };
+21 | |     };
+   | |_____^ unsatisfied trait bound
+   |
+   = help: the trait `distributed::graphql::EffectAssignmentExpression<std::string::String>` is not implemented for `distributed::graphql::TypedEffectExpression<std::option::Option<std::string::String>, distributed::graphql::EffectWireString>`
+help: `distributed::graphql::TypedEffectExpression<T, Wire>` implements trait `distributed::graphql::EffectAssignmentExpression<Target>`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | impl<T, Wire> EffectAssignmentExpression<T> for TypedEffectExpression<T, Wire> {
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `distributed::graphql::EffectAssignmentExpression<T>`
+...
+   | impl<T, Wire> EffectAssignmentExpression<Option<T>> for TypedEffectExpression<T, Wire> {
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `distributed::graphql::EffectAssignmentExpression<std::option::Option<T>>`
+note: required by a bound in `distributed::graphql::__effect_assignment`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | pub fn __effect_assignment<F, E>(value: E) -> CompiledEffectFieldValue<F::Model>
+   |        ------------------- required by a bound in this function
+...
+   |     E: EffectAssignmentExpression<F::Value>,
+   |        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `__effect_assignment`
+   = note: this error originates in the macro `command_effects` (in Nightly builds, run with -Z macro-backtrace for more info)
diff --git a/distributed_macros/tests/command_effects_compile_fail/primary_key_set_assignment.rs b/distributed_macros/tests/command_effects_compile_fail/primary_key_set_assignment.rs
new file mode 100644
index 00000000..bbf70ff8
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/primary_key_set_assignment.rs
@@ -0,0 +1,23 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, GraphqlInput)]
+struct Input {
+    id: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        upsert View {
+            key { id: input.id },
+            set { id: input.id }
+        };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/primary_key_set_assignment.stderr b/distributed_macros/tests/command_effects_compile_fail/primary_key_set_assignment.stderr
new file mode 100644
index 00000000..6639e4d3
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/primary_key_set_assignment.stderr
@@ -0,0 +1,5 @@
+error: effect set cannot assign key field `id`; upsert/patch identity materializes from `key` and rekeying is unsupported
+  --> tests/command_effects_compile_fail/primary_key_set_assignment.rs:20:19
+   |
+20 |             set { id: input.id }
+   |                   ^^
diff --git a/distributed_macros/tests/command_effects_compile_fail/projected_prepare_unavailable.rs b/distributed_macros/tests/command_effects_compile_fail/projected_prepare_unavailable.rs
new file mode 100644
index 00000000..693d8aac
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/projected_prepare_unavailable.rs
@@ -0,0 +1,13 @@
+use distributed::graphql::{PreparedCommand, Projected};
+use distributed::{GraphqlOutput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Serialize, Deserialize, GraphqlOutput, ReadModel)]
+#[readmodel(table = "outputs", primary_key = ["id"])]
+struct Output {
+    id: String,
+}
+
+fn main() {
+    let _ = PreparedCommand::<Projected<Output>>::prepare(Output { id: "one".into() });
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/projected_prepare_unavailable.stderr b/distributed_macros/tests/command_effects_compile_fail/projected_prepare_unavailable.stderr
new file mode 100644
index 00000000..2ba4cdf7
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/projected_prepare_unavailable.stderr
@@ -0,0 +1,13 @@
+error[E0599]: the associated function or constant `prepare` exists for struct `PreparedCommand<distributed::graphql::Projected<Output>>`, but its trait bounds were not satisfied
+  --> tests/command_effects_compile_fail/projected_prepare_unavailable.rs:12:51
+   |
+12 |     let _ = PreparedCommand::<Projected<Output>>::prepare(Output { id: "one".into() });
+   |                                                   ^^^^^^^ associated function or constant cannot be called due to unsatisfied trait bounds
+   |
+  ::: $WORKSPACE/src/graphql/command_contract/outcomes.rs
+   |
+   | pub struct Projected<T> {
+   | ----------------------- doesn't satisfy `_: PreparableOutcome`
+   |
+   = note: the following trait bounds were not satisfied:
+           `distributed::graphql::Projected<Output>: graphql::command_contract::outcomes::sealed::PreparableOutcome`
diff --git a/distributed_macros/tests/command_effects_compile_fail/runtime_path_constant.rs b/distributed_macros/tests/command_effects_compile_fail/runtime_path_constant.rs
new file mode 100644
index 00000000..0acc89cf
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/runtime_path_constant.rs
@@ -0,0 +1,25 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, GraphqlInput)]
+struct Input {
+    id: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+    title: String,
+}
+
+fn main() {
+    let generated_at_runtime = String::from("not deterministic declaration IR");
+    let _ = command_effects! {
+        input: Input;
+        patch View {
+            key { id: input.id },
+            set { title: constant(generated_at_runtime) }
+        };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/runtime_path_constant.stderr b/distributed_macros/tests/command_effects_compile_fail/runtime_path_constant.stderr
new file mode 100644
index 00000000..7b04a939
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/runtime_path_constant.stderr
@@ -0,0 +1,11 @@
+error[E0435]: attempt to use a non-constant value in a constant
+  --> tests/command_effects_compile_fail/runtime_path_constant.rs:22:35
+   |
+22 |             set { title: constant(generated_at_runtime) }
+   |                                   ^^^^^^^^^^^^^^^^^^^^ non-constant value
+   |
+help: consider using `const` instead of `let`
+   |
+17 -     let generated_at_runtime = String::from("not deterministic declaration IR");
+17 +     const generated_at_runtime: /* Type */ = String::from("not deterministic declaration IR");
+   |
diff --git a/distributed_macros/tests/command_effects_compile_fail/trusted_preset_without_scope.rs b/distributed_macros/tests/command_effects_compile_fail/trusted_preset_without_scope.rs
new file mode 100644
index 00000000..1416942b
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/trusted_preset_without_scope.rs
@@ -0,0 +1,23 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+
+#[derive(GraphqlInput)]
+struct Input {
+    view_id: String,
+}
+
+#[derive(Clone, ReadModel)]
+#[readmodel(table = "views", primary_key = ["view_id"])]
+struct View {
+    view_id: String,
+    status: String,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        patch View {
+            key { view_id: input.view_id },
+            set { status: trusted("") }
+        };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/trusted_preset_without_scope.stderr b/distributed_macros/tests/command_effects_compile_fail/trusted_preset_without_scope.stderr
new file mode 100644
index 00000000..2349d44e
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/trusted_preset_without_scope.stderr
@@ -0,0 +1,5 @@
+error: trusted() preset name must be 1..=128 bytes, have no surrounding whitespace, and contain no control characters
+  --> tests/command_effects_compile_fail/trusted_preset_without_scope.rs:20:35
+   |
+20 |             set { status: trusted("") }
+   |                                   ^^
diff --git a/distributed_macros/tests/command_effects_compile_fail/unknown_input_field.rs b/distributed_macros/tests/command_effects_compile_fail/unknown_input_field.rs
new file mode 100644
index 00000000..120616ea
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/unknown_input_field.rs
@@ -0,0 +1,19 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+
+#[derive(GraphqlInput)]
+struct Input {
+    view_id: String,
+}
+
+#[derive(Clone, ReadModel)]
+#[readmodel(table = "views", primary_key = ["view_id"])]
+struct View {
+    view_id: String,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        delete View { key { view_id: input.missing } };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/unknown_input_field.stderr b/distributed_macros/tests/command_effects_compile_fail/unknown_input_field.stderr
new file mode 100644
index 00000000..41927127
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/unknown_input_field.stderr
@@ -0,0 +1,14 @@
+error[E0425]: cannot find type `__DistributedInputEffectInputField_missing` in this scope
+  --> tests/command_effects_compile_fail/unknown_input_field.rs:17:44
+   |
+ 3 | #[derive(GraphqlInput)]
+   |          ------------ similarly named struct `__DistributedInputEffectInputField_view_id` defined here
+...
+17 |         delete View { key { view_id: input.missing } };
+   |                                            ^^^^^^^
+   |
+help: a struct with a similar name exists
+   |
+17 -         delete View { key { view_id: input.missing } };
+17 +         delete View { key { view_id: input.__DistributedInputEffectInputField_view_id } };
+   |
diff --git a/distributed_macros/tests/command_effects_compile_fail/unknown_model_field.rs b/distributed_macros/tests/command_effects_compile_fail/unknown_model_field.rs
new file mode 100644
index 00000000..82c40458
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/unknown_model_field.rs
@@ -0,0 +1,22 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+
+#[derive(GraphqlInput)]
+struct Input {
+    view_id: String,
+}
+
+#[derive(Clone, ReadModel)]
+#[readmodel(table = "views", primary_key = ["view_id"])]
+struct View {
+    view_id: String,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        patch View {
+            key { view_id: input.view_id },
+            set { missing: input.view_id }
+        };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/unknown_model_field.stderr b/distributed_macros/tests/command_effects_compile_fail/unknown_model_field.stderr
new file mode 100644
index 00000000..920faf6f
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/unknown_model_field.stderr
@@ -0,0 +1,14 @@
+error[E0425]: cannot find type `__DistributedViewEffectModelField_missing` in this scope
+  --> tests/command_effects_compile_fail/unknown_model_field.rs:19:19
+   |
+ 8 | #[derive(Clone, ReadModel)]
+   |                 --------- similarly named struct `__DistributedViewEffectModelField_view_id` defined here
+...
+19 |             set { missing: input.view_id }
+   |                   ^^^^^^^
+   |
+help: a struct with a similar name exists
+   |
+19 -             set { missing: input.view_id }
+19 +             set { __DistributedViewEffectModelField_view_id: input.view_id }
+   |
diff --git a/distributed_macros/tests/command_effects_compile_fail/wire_list_to_bytea_assignment.rs b/distributed_macros/tests/command_effects_compile_fail/wire_list_to_bytea_assignment.rs
new file mode 100644
index 00000000..815628e9
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/wire_list_to_bytea_assignment.rs
@@ -0,0 +1,25 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, GraphqlInput)]
+struct Input {
+    id: String,
+    bytes: Vec<u8>,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["id"])]
+struct View {
+    id: String,
+    bytes: Vec<u8>,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        patch View {
+            key { id: input.id },
+            set { bytes: input.bytes }
+        };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/wire_list_to_bytea_assignment.stderr b/distributed_macros/tests/command_effects_compile_fail/wire_list_to_bytea_assignment.stderr
new file mode 100644
index 00000000..76fbd82a
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/wire_list_to_bytea_assignment.stderr
@@ -0,0 +1,40 @@
+error[E0277]: the trait bound `distributed::graphql::EffectWireList: distributed::graphql::EffectWireCompatible<distributed::graphql::EffectWireBytea>` is not satisfied
+  --> tests/command_effects_compile_fail/wire_list_to_bytea_assignment.rs:18:13
+   |
+18 |       let _ = command_effects! {
+   |  _____________^
+19 | |         input: Input;
+20 | |         patch View {
+21 | |             key { id: input.id },
+22 | |             set { bytes: input.bytes }
+23 | |         };
+24 | |     };
+   | |_____^ unsatisfied trait bound
+   |
+   = help: the trait `distributed::graphql::EffectWireCompatible<distributed::graphql::EffectWireBytea>` is not implemented for `distributed::graphql::EffectWireList`
+help: `distributed::graphql::EffectWireList` implements trait `distributed::graphql::EffectWireCompatible<Target>`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   |           $(impl EffectWireCompatible<$wire> for $wire {})+
+   |             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `distributed::graphql::EffectWireCompatible<distributed::graphql::EffectWireList>`
+...
+   | / exact_effect_wire_compatibility!(
+   | |     EffectWireString,
+   | |     EffectWireBoolean,
+   | |     EffectWireBigInt,
+...  |
+   | |     EffectWireUnsupported,
+   | | );
+   | |_- in this macro invocation
+...
+   |   impl EffectWireCompatible<EffectWireJson> for EffectWireList {}
+   |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `distributed::graphql::EffectWireCompatible<distributed::graphql::EffectWireJson>`
+note: required by a bound in `distributed::graphql::__effect_assignment`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | pub fn __effect_assignment<F, E>(value: E) -> CompiledEffectFieldValue<F::Model>
+   |        ------------------- required by a bound in this function
+...
+   |     E::Wire: EffectWireCompatible<F::Wire>,
+   |              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `__effect_assignment`
+   = note: this error originates in the macro `command_effects` which comes from the expansion of the macro `exact_effect_wire_compatibility` (in Nightly builds, run with -Z macro-backtrace for more info)
diff --git a/distributed_macros/tests/command_effects_compile_fail/wire_list_to_bytea_key.rs b/distributed_macros/tests/command_effects_compile_fail/wire_list_to_bytea_key.rs
new file mode 100644
index 00000000..9a8d94c2
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/wire_list_to_bytea_key.rs
@@ -0,0 +1,21 @@
+use distributed::{command_effects, GraphqlInput, ReadModel};
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, GraphqlInput)]
+struct Input {
+    bytes_id: Vec<u8>,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "views", primary_key = ["bytes_id"])]
+struct View {
+    id: String,
+    bytes_id: Vec<u8>,
+}
+
+fn main() {
+    let _ = command_effects! {
+        input: Input;
+        delete View { key { bytes_id: input.bytes_id } };
+    };
+}
diff --git a/distributed_macros/tests/command_effects_compile_fail/wire_list_to_bytea_key.stderr b/distributed_macros/tests/command_effects_compile_fail/wire_list_to_bytea_key.stderr
new file mode 100644
index 00000000..2f3ae22a
--- /dev/null
+++ b/distributed_macros/tests/command_effects_compile_fail/wire_list_to_bytea_key.stderr
@@ -0,0 +1,37 @@
+error[E0277]: the trait bound `distributed::graphql::EffectWireList: distributed::graphql::EffectWireCompatible<distributed::graphql::EffectWireBytea>` is not satisfied
+  --> tests/command_effects_compile_fail/wire_list_to_bytea_key.rs:17:13
+   |
+17 |       let _ = command_effects! {
+   |  _____________^
+18 | |         input: Input;
+19 | |         delete View { key { bytes_id: input.bytes_id } };
+20 | |     };
+   | |_____^ unsatisfied trait bound
+   |
+   = help: the trait `distributed::graphql::EffectWireCompatible<distributed::graphql::EffectWireBytea>` is not implemented for `distributed::graphql::EffectWireList`
+help: `distributed::graphql::EffectWireList` implements trait `distributed::graphql::EffectWireCompatible<Target>`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   |           $(impl EffectWireCompatible<$wire> for $wire {})+
+   |             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `distributed::graphql::EffectWireCompatible<distributed::graphql::EffectWireList>`
+...
+   | / exact_effect_wire_compatibility!(
+   | |     EffectWireString,
+   | |     EffectWireBoolean,
+   | |     EffectWireBigInt,
+...  |
+   | |     EffectWireUnsupported,
+   | | );
+   | |_- in this macro invocation
+...
+   |   impl EffectWireCompatible<EffectWireJson> for EffectWireList {}
+   |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `distributed::graphql::EffectWireCompatible<distributed::graphql::EffectWireJson>`
+note: required by a bound in `distributed::graphql::__effect_key_assignment`
+  --> $WORKSPACE/src/graphql/command_contract/effect_wire.rs
+   |
+   | pub fn __effect_key_assignment<F, Wire>(
+   |        ----------------------- required by a bound in this function
+...
+   |     Wire: EffectWireCompatible<F::Wire>,
+   |           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `__effect_key_assignment`
+   = note: this error originates in the macro `command_effects` which comes from the expansion of the macro `exact_effect_wire_compatibility` (in Nightly builds, run with -Z macro-backtrace for more info)
diff --git a/distributed_macros/tests/graphql_compile_fail.rs b/distributed_macros/tests/graphql_compile_fail.rs
new file mode 100644
index 00000000..2cbead39
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail.rs
@@ -0,0 +1,7 @@
+//! Compile-time diagnostics specific to GraphqlInput / GraphqlOutput.
+
+#[test]
+fn graphql_compile_fail() {
+    let t = trybuild::TestCases::new();
+    t.compile_fail("tests/graphql_compile_fail/*.rs");
+}
diff --git a/distributed_macros/tests/graphql_compile_fail/nested_lists.rs b/distributed_macros/tests/graphql_compile_fail/nested_lists.rs
new file mode 100644
index 00000000..79e90030
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/nested_lists.rs
@@ -0,0 +1,8 @@
+use distributed::GraphqlInput;
+
+#[derive(GraphqlInput)]
+struct NestedLists {
+    values: Option<Vec<Option<Vec<String>>>>,
+}
+
+fn main() {}
diff --git a/distributed_macros/tests/graphql_compile_fail/nested_lists.stderr b/distributed_macros/tests/graphql_compile_fail/nested_lists.stderr
new file mode 100644
index 00000000..b3159e93
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/nested_lists.stderr
@@ -0,0 +1,5 @@
+error: nested lists are not supported for GraphqlInput/GraphqlOutput fields
+ --> tests/graphql_compile_fail/nested_lists.rs:5:13
+  |
+5 |     values: Option<Vec<Option<Vec<String>>>>,
+  |             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/distributed_macros/tests/graphql_compile_fail/serde_container_default.rs b/distributed_macros/tests/graphql_compile_fail/serde_container_default.rs
new file mode 100644
index 00000000..deb0cb83
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/serde_container_default.rs
@@ -0,0 +1,9 @@
+use distributed::GraphqlInput;
+
+#[derive(GraphqlInput)]
+#[serde(default = "default_input")]
+struct ContainerDefaultInput {
+    value: String,
+}
+
+fn main() {}
diff --git a/distributed_macros/tests/graphql_compile_fail/serde_container_default.stderr b/distributed_macros/tests/graphql_compile_fail/serde_container_default.stderr
new file mode 100644
index 00000000..6ad3ec64
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/serde_container_default.stderr
@@ -0,0 +1,5 @@
+error: #[serde(default)] is not supported by GraphqlInput because it changes the declared GraphQL object shape; define a separate wire type
+ --> tests/graphql_compile_fail/serde_container_default.rs:4:9
+  |
+4 | #[serde(default = "default_input")]
+  |         ^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/distributed_macros/tests/graphql_compile_fail/serde_default.rs b/distributed_macros/tests/graphql_compile_fail/serde_default.rs
new file mode 100644
index 00000000..ca463310
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/serde_default.rs
@@ -0,0 +1,9 @@
+use distributed::GraphqlInput;
+
+#[derive(GraphqlInput)]
+struct DefaultedInput {
+    #[serde(default)]
+    value: String,
+}
+
+fn main() {}
diff --git a/distributed_macros/tests/graphql_compile_fail/serde_default.stderr b/distributed_macros/tests/graphql_compile_fail/serde_default.stderr
new file mode 100644
index 00000000..a2fc841e
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/serde_default.stderr
@@ -0,0 +1,5 @@
+error: #[serde(default)] is not supported by GraphqlInput because it changes the declared GraphQL field shape; define a separate wire type
+ --> tests/graphql_compile_fail/serde_default.rs:5:13
+  |
+5 |     #[serde(default)]
+  |             ^^^^^^^
diff --git a/distributed_macros/tests/graphql_compile_fail/serde_kebab_case.rs b/distributed_macros/tests/graphql_compile_fail/serde_kebab_case.rs
new file mode 100644
index 00000000..375917b7
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/serde_kebab_case.rs
@@ -0,0 +1,9 @@
+use distributed::GraphqlOutput;
+
+#[derive(GraphqlOutput)]
+#[serde(rename_all = "kebab-case")]
+struct KebabCase {
+    field_name: String,
+}
+
+fn main() {}
diff --git a/distributed_macros/tests/graphql_compile_fail/serde_kebab_case.stderr b/distributed_macros/tests/graphql_compile_fail/serde_kebab_case.stderr
new file mode 100644
index 00000000..1197d383
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/serde_kebab_case.stderr
@@ -0,0 +1,5 @@
+error: serde kebab-case field names cannot be represented in GraphQL; use camelCase or snake_case
+ --> tests/graphql_compile_fail/serde_kebab_case.rs:4:22
+  |
+4 | #[serde(rename_all = "kebab-case")]
+  |                      ^^^^^^^^^^^^
diff --git a/distributed_macros/tests/graphql_compile_fail/serde_skip.rs b/distributed_macros/tests/graphql_compile_fail/serde_skip.rs
new file mode 100644
index 00000000..e7f761f5
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/serde_skip.rs
@@ -0,0 +1,9 @@
+use distributed::GraphqlOutput;
+
+#[derive(GraphqlOutput)]
+struct SkippedOutput {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    value: Option<String>,
+}
+
+fn main() {}
diff --git a/distributed_macros/tests/graphql_compile_fail/serde_skip.stderr b/distributed_macros/tests/graphql_compile_fail/serde_skip.stderr
new file mode 100644
index 00000000..dde24917
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/serde_skip.stderr
@@ -0,0 +1,5 @@
+error: #[serde(skip_serializing_if)] is not supported by GraphqlOutput because it changes the declared GraphQL field shape; define a separate wire type
+ --> tests/graphql_compile_fail/serde_skip.rs:5:13
+  |
+5 |     #[serde(skip_serializing_if = "Option::is_none")]
+  |             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/distributed_macros/tests/graphql_compile_fail/serde_transparent.rs b/distributed_macros/tests/graphql_compile_fail/serde_transparent.rs
new file mode 100644
index 00000000..23880153
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/serde_transparent.rs
@@ -0,0 +1,9 @@
+use distributed::GraphqlInput;
+
+#[derive(GraphqlInput)]
+#[serde(transparent)]
+struct TransparentInput {
+    value: String,
+}
+
+fn main() {}
diff --git a/distributed_macros/tests/graphql_compile_fail/serde_transparent.stderr b/distributed_macros/tests/graphql_compile_fail/serde_transparent.stderr
new file mode 100644
index 00000000..c8d1159d
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/serde_transparent.stderr
@@ -0,0 +1,5 @@
+error: #[serde(transparent)] is not supported by GraphqlInput because it changes the declared GraphQL object shape; define a separate wire type
+ --> tests/graphql_compile_fail/serde_transparent.rs:4:9
+  |
+4 | #[serde(transparent)]
+  |         ^^^^^^^^^^^
diff --git a/distributed_macros/tests/graphql_compile_fail/serde_with.rs b/distributed_macros/tests/graphql_compile_fail/serde_with.rs
new file mode 100644
index 00000000..a921590e
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/serde_with.rs
@@ -0,0 +1,9 @@
+use distributed::GraphqlOutput;
+
+#[derive(GraphqlOutput)]
+struct CustomOutput {
+    #[serde(with = "wire_value")]
+    value: String,
+}
+
+fn main() {}
diff --git a/distributed_macros/tests/graphql_compile_fail/serde_with.stderr b/distributed_macros/tests/graphql_compile_fail/serde_with.stderr
new file mode 100644
index 00000000..0707da8a
--- /dev/null
+++ b/distributed_macros/tests/graphql_compile_fail/serde_with.stderr
@@ -0,0 +1,5 @@
+error: #[serde(with)] is not supported by GraphqlOutput because it changes the declared GraphQL field shape; define a separate wire type
+ --> tests/graphql_compile_fail/serde_with.rs:5:13
+  |
+5 |     #[serde(with = "wire_value")]
+  |             ^^^^^^^^^^^^^^^^^^^
diff --git a/docs/metrics.md b/docs/metrics.md
deleted file mode 100644
index 0c08aac2..00000000
--- a/docs/metrics.md
+++ /dev/null
@@ -1,132 +0,0 @@
-# Metrics
-
-Distributed exposes framework-owned metrics behind the optional `metrics`
-feature. The feature has no OpenTelemetry SDK or Prometheus client dependency:
-the crate records bounded counters/gauges internally and renders Prometheus text
-from the HTTP `/metrics` endpoint when both `http` and `metrics` are enabled.
-
-## Enabling
-
-```toml
-distributed = { version = "...", features = ["http", "metrics"] }
-```
-
-Then expose a named HTTP service:
-
-```rust
-let service = std::sync::Arc::new(
-    distributed::microsvc::Service::new()
-        .named("orders")
-        .routes(routes),
-);
-distributed::microsvc::serve(service, "0.0.0.0:3000").await?;
-```
-
-Prometheus can scrape `GET /metrics` on the service's HTTP port. Hops
-ObserveStack should use the same scrape target and labels; dashboards can join
-these metrics with trace data by the stable `service` and message labels.
-
-The scrape route is unauthenticated by design. Do not expose `/metrics` on a
-public listener; keep it behind a private network, ingress policy, security
-group, or equivalent access control used only by the metrics collector.
-
-For services whose primary transport is not HTTP, run a metrics-only listener on
-a side port:
-
-```rust
-distributed::metrics::serve_http("0.0.0.0:9100", Some("orders-worker")).await?;
-```
-
-You can also compose the router into an existing axum app:
-
-```rust
-let metrics = distributed::metrics::http_router_for_service("orders-worker");
-```
-
-This listener exposes only `GET /metrics`; it does not expose command dispatch.
-
-## Labels
-
-Metric labels are intentionally bounded:
-
-- `service`: `Service::named(...)`, or `unnamed` when no service name was set.
-- `message_kind`: `command` or `event`.
-- `message`: registered command/event name; unknown-command failures are
-  bucketed as `unknown` rather than recording the unrecognized input.
-- `status`: bounded dispatch status such as `success`, `unknown_command`,
-  `decode_failed`, `guard_rejected`, `repository_error`, or `other_error`.
-- `transport`: built-in source label such as `in_memory`, `sqlite`,
-  `postgres`, `rabbitmq`, `kafka`, `nats`, or `outbox`.
-- `outcome`: bounded settle/publish outcome such as `ack`, `nack`,
-  `dead_letter`, `park`, `ignored`, `log_and_ack`, `published`, `released`, or
-  `failed`.
-- `failure_class`: `retryable` or `permanent`.
-- `action`: failure-policy action such as `nack`, `dead_letter`, `park`,
-  `log_and_ack`, `stop`, `recv_error`, or a settle failure label such as
-  `settle_ack`.
-
-Do not add IDs, trace IDs, user IDs, aggregate IDs, or other high-cardinality
-values as framework labels.
-
-The label names, framework status values, transport outcomes, failure actions,
-and outbox outcomes live in one internal telemetry vocabulary. New framework
-metrics should use that vocabulary rather than introducing ad hoc labels.
-
-## Metric Families
-
-- `distributed_service_info{service,version}` gauge.
-- `distributed_microsvc_dispatch_total{service,message_kind,message,status}`
-  counter.
-- `distributed_microsvc_dispatch_duration_seconds{service,message_kind,message,status}`
-  histogram.
-- `distributed_transport_messages_total{service,transport,message_kind,outcome}`
-  counter.
-- `distributed_transport_failures_total{service,transport,failure_class,action}`
-  counter.
-- `distributed_outbox_messages_total{service,outcome}` counter.
-- `distributed_outbox_pending_messages{service}` gauge.
-- `distributed_outbox_oldest_pending_age_seconds{service}` gauge.
-
-The registry also exposes an internal typed snapshot shape used by tests and
-future private diagnostics. The snapshot contains metric families, bounded
-labels, and numeric samples only; diagnostics must not add payloads, metadata,
-trace ids, aggregate ids, user ids, raw HTTP targets, or request ids to that
-shape.
-
-## Boundaries
-
-The `metrics` feature owns Prometheus text exposition for framework metrics. It
-does not install an OpenTelemetry metrics SDK, emit request-level HTTP metrics,
-or record user payload data.
-
-Direct transport receive paths emit receive/settle counters and failure
-counters. Outbox dispatch emits publish outcomes and backlog gauges. Direct
-`MessagePublisher` calls outside the outbox path do not emit publish metrics in
-this release; instrumenting those calls should use the same bounded vocabulary
-and should stay separate from outbox publish outcomes.
-
-## Scaffolded GitOps
-
-`dctl scaffold --gitops --metrics prometheus` adds the Distributed `metrics`
-feature to the generated service and emits Prometheus Operator resources for HTTP
-deployments:
-
-- `.gitops/deploy/templates/servicemonitor.yaml`
-- `.gitops/deploy/templates/prometheusrule.yaml`
-
-Plain `--gitops` does not emit `monitoring.coreos.com` resources, so generated
-charts still apply to clusters that do not have Prometheus Operator CRDs
-installed. Even when the templates are generated, `serviceMonitor.enabled` and
-`prometheusRule.enabled` default to `false`; enable them in the environment's
-Helm values only when the cluster has Prometheus Operator installed.
-
-Knative scaffolds enable the runtime metrics feature and expose the same
-`GET /metrics` endpoint from the CloudEvents router, but they do not emit a
-`ServiceMonitor`; Knative monitoring topology should be modeled by the platform
-layer.
-
-The generated `PrometheusRule` contains conservative starting alerts for:
-
-- elevated microsvc dispatch error rate;
-- oldest pending outbox message age;
-- repeated retryable transport failures.
diff --git a/docs/observability.md b/docs/observability.md
deleted file mode 100644
index 8fc2db1a..00000000
--- a/docs/observability.md
+++ /dev/null
@@ -1,179 +0,0 @@
-# Observability
-
-Distributed's base observability contract is metadata propagation. The default
-feature set has no OpenTelemetry SDK dependency, but the framework preserves W3C
-Trace Context across its event, outbox, bus, and service boundaries.
-
-## Trace Context Metadata
-
-Distributed uses these canonical lowercase metadata keys:
-
-| Key | Meaning |
-| --- | --- |
-| `traceparent` | W3C Trace Context trace and parent span identity |
-| `tracestate` | W3C vendor trace state |
-| `correlation_id` | Application workflow correlation id |
-| `causation_id` | Immediate message or event that caused the work |
-
-`Message` lookup is case-insensitive because wire transports vary in header
-casing. When Distributed writes trace keys through `TraceContext`, it writes the
-canonical lowercase form and replaces older case variants.
-
-```rust
-use distributed::{TraceContext, TRACEPARENT};
-use distributed::microsvc::{Message, MessageKind};
-
-let trace = TraceContext {
-    traceparent: Some("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01".into()),
-    tracestate: Some("vendor=value".into()),
-};
-
-let message = Message::new("checkout.started", MessageKind::Event, Vec::new())
-    .with_trace_context(&trace);
-
-assert_eq!(message.traceparent(), trace.traceparent.as_deref());
-assert_eq!(message.metadata(TRACEPARENT), trace.traceparent.as_deref());
-```
-
-Handlers can copy the incoming context into aggregate events or outbox messages:
-
-```rust
-# use distributed::{Entity, OutboxMessage};
-# use distributed::microsvc::{Context, Message, MessageKind};
-# fn example(ctx: &Context<()>) -> Result<(), distributed::EventRecordError> {
-let trace = ctx.message().trace_context();
-
-let mut entity = Entity::with_id("checkout-1");
-entity.set_trace_context(&trace);
-entity.digest_empty("checkout.started")?;
-
-let mut outbox = OutboxMessage::create("evt-1", "checkout.started", b"{}".to_vec())?;
-outbox.set_trace_context(&trace);
-# Ok(())
-# }
-```
-
-`EventRecord`, `Entity`, `OutboxMessage`, and `Message` all expose trace context
-helpers. Replays do not create spans or mutate trace context; they only read the
-metadata already stored with events.
-
-## Optional Span Feature
-
-The `otel` feature adds framework-owned `tracing` spans around dispatch,
-handler execution, transport receive, and outbox publish boundaries. When the
-incoming message carries W3C `traceparent` / `tracestate`, Distributed extracts
-that context and sets it as the OpenTelemetry parent for the framework span:
-
-```toml
-[dependencies]
-distributed = { version = "0.1", features = ["http", "otel"] }
-```
-
-The library feature intentionally does not install a global tracer or exporter.
-Hand-written service binaries should configure their own `tracing` subscriber
-and OpenTelemetry layer so deployment owners control sampling, resources,
-redaction, and export. `dctl scaffold --tracing` emits a default OTLP tracing
-setup in the generated `main.rs` for the common case.
-
-Framework span names are intentionally bounded:
-
-- `distributed.microsvc.dispatch`
-- `distributed.handler`
-- `distributed.transport.receive`
-- `distributed.outbox.publish`
-
-Each span uses the same framework-owned message attributes:
-
-- `distributed.message.name`
-- `distributed.message.kind`
-- `messaging.message.id`
-
-Future spans should use the same helper path so new attributes are reviewed in
-one place. Do not add payload fields, user ids, aggregate ids, or raw metadata
-values as framework span attributes.
-
-Recommended environment variables for OTLP exporters:
-
-```text
-OTEL_SERVICE_NAME=checkout-service
-OTEL_RESOURCE_ATTRIBUTES=service.namespace=ticketing,deployment.environment.name=prod
-OTEL_EXPORTER_OTLP_ENDPOINT=http://alloy-receiver.monitoring.svc:4317
-OTEL_EXPORTER_OTLP_PROTOCOL=grpc
-OTEL_TRACES_SAMPLER=parentbased_traceidratio
-```
-
-For Hops ObserveStack, prefer exporting to the Alloy receiver and letting
-ObserveStack route traces to Tempo:
-
-```text
-OTEL_EXPORTER_OTLP_ENDPOINT=http://alloy-receiver.monitoring.svc:4317
-OTEL_EXPORTER_OTLP_PROTOCOL=grpc
-```
-
-HTTP/protobuf exporters can instead use:
-
-```text
-OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://alloy-receiver.monitoring.svc:4318/v1/traces
-OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
-```
-
-## CLI And GitOps
-
-`dctl scaffold --tracing` enables the generated service's `distributed` `otel`
-feature and records tracing intent in `ServiceManifest` with
-`TracingManifest::otlp()`. It also adds the generated binary dependencies for
-`opentelemetry-otlp`, `tracing-opentelemetry`, and `tracing-subscriber`,
-initializes an OTLP tracer provider from `OTEL_EXPORTER_OTLP_*` environment
-variables, and shuts the provider down when the server exits. When GitOps output
-is requested, the deploy chart renders Helm values for OTLP configuration and
-conditionally injects:
-
-- `OTEL_SERVICE_NAME`
-- `OTEL_EXPORTER_OTLP_PROTOCOL`
-- `OTEL_EXPORTER_OTLP_ENDPOINT` when a chart value is set
-
-`dctl scaffold --metrics prometheus` generates a real `/metrics` endpoint in the
-service crate and records `MetricsEndpointManifest::prometheus_default()` in the
-service manifest. For generated HTTP Deployment + Service charts, GitOps output
-also includes a Prometheus Operator `ServiceMonitor` that scrapes the named
-`http` port at `/metrics`.
-
-Knative services can still generate the `/metrics` endpoint, but the generic
-GitOps renderer does not emit a `ServiceMonitor` for Knative because the correct
-scrape target is platform-specific.
-
-## Integration Tests
-
-CI verifies the observability surface at the docker level (see
-`integration-observability.yaml`):
-
-- `tests/metrics_exposition` drives real HTTP + outbox traffic, scrapes
-  `GET /metrics`, and lints the exposition with `promtool check metrics`
-  (skips when `PROMTOOL` is unset).
-- `tests/otel_export` builds a real OTLP pipeline the way a service binary
-  would, dispatches a message carrying a W3C `traceparent`, and asserts a real
-  OpenTelemetry Collector received `distributed.microsvc.dispatch` parented to
-  the incoming span (skips when `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` /
-  `OTEL_COLLECTOR_TRACES_FILE` are unset).
-- The scaffolded `ServiceMonitor` / `PrometheusRule` / OTLP env output is
-  rendered with `helm template` and validated against published CRD schemas
-  with `kubeconform`.
-
-Whether a Prometheus Operator actually reconciles the `ServiceMonitor` is a
-platform concern, verified on a live cluster rather than per PR.
-
-## Feature Boundaries
-
-The default feature set propagates W3C trace context metadata only.
-
-The `metrics` feature records framework metrics and renders Prometheus text. It
-does not expose OpenTelemetry metrics or request-level HTTP telemetry.
-
-The `otel` feature creates framework spans and parents them from W3C metadata
-when available. It does not install subscribers, exporters, sampling rules, or
-resource attributes.
-
-Future `logs` or private `diagnostics` features should build on the same
-bounded telemetry vocabulary. Logs may carry structured failure context, but
-must not log payloads or secrets by default. Diagnostics should read typed
-snapshots of framework state rather than parsing public Prometheus text.
diff --git a/docs/postgres-event-store.md b/docs/postgres-event-store.md
deleted file mode 100644
index acc8153e..00000000
--- a/docs/postgres-event-store.md
+++ /dev/null
@@ -1,392 +0,0 @@
-# Postgres Event Store Contract
-
-This is the storage contract for the future Postgres repository. It defines the
-durable representation and repository behavior before the SQL implementation
-lands.
-
-The event table stores aggregate-sourced replay records: write-side history for
-rehydrating one aggregate stream. It is not the domain-event bus. Published
-domain events, integration events, commands, and transport messages belong in
-the outbox/message tables with their own delivery, retry, and idempotency
-semantics.
-
-## Repository Scope
-
-The Postgres event store is responsible for:
-
-- loading aggregate streams by identity,
-- appending new aggregate event records,
-- enforcing optimistic concurrency,
-- preserving event payload compatibility metadata,
-- participating in one transaction boundary for structured commit batches.
-
-It is not responsible for broad product queries. Aggregate-wide predicate
-filtering is a scan/admin concern; production queries should use read models or
-declared store-specific indexes.
-
-## Stream Identity
-
-Stream identity is the pair `(aggregate_type, aggregate_id)`.
-
-`aggregate_id` is the entity ID already tracked by `Entity`.
-
-`aggregate_type` must be a stable application-level name, not an accidental Rust
-module path. The Postgres implementation should add an explicit aggregate type
-source before it writes rows, for example:
-
-- an associated constant or method on the aggregate type,
-- a derive/macro attribute such as `#[aggregate(type = "todos")]`,
-- a conservative default derived from the Rust type name only for tests.
-
-Do not use `std::any::type_name::<A>()` as the persisted default for production:
-module paths can change during refactors and would split or orphan existing
-streams.
-
-## Event Table
-
-Recommended table name: `aggregate_events`.
-
-| Column | Type | Notes |
-| --- | --- | --- |
-| `aggregate_type` | `text` | Stable aggregate type name; `NOT NULL`. |
-| `aggregate_id` | `text` | Aggregate stream identifier; `NOT NULL`. |
-| `sequence` | `bigint` | One-based stream position; `NOT NULL`. |
-| `event_name` | `text` | Stable replay event record name; `NOT NULL`. |
-| `event_version` | `integer` | Payload schema version; `NOT NULL DEFAULT 1`. |
-| `payload` | `bytea` | Encoded event payload bytes; `NOT NULL`. |
-| `payload_codec` | `text` | Codec label, initially `bitcode`; `NOT NULL`. |
-| `payload_codec_version` | `integer` | Codec metadata, initially `1`; `NOT NULL`. |
-| `metadata` | `jsonb` | Event metadata; `NOT NULL DEFAULT '{}'`. |
-| `recorded_at` | `timestamptz` | UTC instant for the event record; `NOT NULL`. |
-
-The DDL must declare `aggregate_type` and `aggregate_id` as `NOT NULL`; the
-checks below also reject empty strings. `sequence`, `event_name`,
-`event_version`, `payload`, `payload_codec`, `payload_codec_version`,
-`metadata`, and `recorded_at` must also be `NOT NULL`, and `metadata` must
-default to an empty JSON object.
-
-Required constraints:
-
-```sql
-PRIMARY KEY (aggregate_type, aggregate_id, sequence);
-CHECK (aggregate_type <> '');
-CHECK (aggregate_id <> '');
-CHECK (sequence > 0);
-CHECK (event_version > 0);
-CHECK (payload_codec <> '');
-CHECK (payload_codec_version > 0);
-```
-
-Required or recommended indexes:
-
-```sql
--- Primary replay path; covered by the primary key but listed as the core access pattern.
-(aggregate_type, aggregate_id, sequence);
-
--- Diagnostics, migrations, and upcaster audits.
-(aggregate_type, event_name, event_version);
-
--- Optional operational/audit browsing.
-(recorded_at);
-```
-
-The implementation may add a generated `stream_id` for internal convenience,
-but it must not replace the public identity contract. If present, `stream_id`
-must be derived from `(aggregate_type, aggregate_id)` and must remain unique
-with those columns.
-
-## Codec Validation and Error Model
-
-Payload codec metadata is part of the durable compatibility contract. The
-initial supported codec tuple is:
-
-```text
-payload_codec = "bitcode"
-payload_codec_version = 1
-```
-
-`event_version` describes the domain event payload schema and drives aggregate
-upcasters. `payload_codec` and `payload_codec_version` describe how bytes are
-encoded. These fields must be validated independently.
-
-On write, the repository must reject event, snapshot, read-model, and outbox
-payload rows with an unknown codec label, an unsupported codec version, or empty
-codec metadata before inserting any row in the transaction. The initial error
-should be a `RepositoryError::Model` wrapping the existing
-`EventRecordError::unsupported_codec(...)` message shape.
-
-On read, row decoding must reject unknown codec labels or versions unless the
-repository has an explicit decoder or migration path for that codec tuple.
-Aggregate payload decode failures during replay should surface as
-`RepositoryError::Replay`; row-level codec metadata failures before replay
-should surface as `RepositoryError::Model`.
-
-Postgres tests should cover:
-
-- insert/write rejection for unsupported `payload_codec`;
-- insert/write rejection for unsupported `payload_codec_version`;
-- read rejection for a row containing an unknown codec tuple;
-- successful `bitcode` version `1` event and snapshot round trip;
-- upcaster behavior remaining keyed by `event_version`, not by codec version.
-
-## Snapshot Table
-
-Snapshots should live in a side table, not as mixed rows in `aggregate_events`.
-That keeps the event table append-only and avoids a `snapshot` discriminator in
-the event log.
-
-Recommended table name: `aggregate_snapshots`.
-
-| Column | Type | Notes |
-| --- | --- | --- |
-| `aggregate_type` | `text` | Same stable aggregate type as events; `NOT NULL`. |
-| `aggregate_id` | `text` | Same aggregate ID as events; `NOT NULL`. |
-| `version` | `bigint` | Stream sequence covered by this snapshot; `NOT NULL`. |
-| `snapshot_type` | `text` | State snapshot payload type; `NOT NULL`. |
-| `snapshot_version` | `integer` | State snapshot payload version; `NOT NULL`. |
-| `payload` | `bytea` | Encoded state snapshot payload bytes; `NOT NULL`. |
-| `payload_codec` | `text` | Codec label; `NOT NULL`. |
-| `payload_codec_version` | `integer` | Codec metadata; `NOT NULL`. |
-| `metadata` | `jsonb` | Cache metadata; `NOT NULL`, default `{}`. |
-| `recorded_at` | `timestamptz` | UTC instant for the snapshot; `NOT NULL`. |
-
-The DDL must declare `aggregate_type` and `aggregate_id` as `NOT NULL`; the
-checks below also reject empty strings. `version`, `snapshot_type`,
-`snapshot_version`, `payload`, `payload_codec`, `payload_codec_version`,
-`metadata`, and `recorded_at` must also be `NOT NULL`.
-
-Required constraints and indexes:
-
-```sql
-PRIMARY KEY (aggregate_type, aggregate_id);
-CHECK (aggregate_type <> '');
-CHECK (aggregate_id <> '');
-CHECK (version > 0);
-CHECK (snapshot_type <> '');
-CHECK (snapshot_version > 0);
-CHECK (payload_codec <> '');
-CHECK (payload_codec_version > 0);
-```
-
-The first implementation is latest-only: writing a snapshot cache record
-upserts the `(aggregate_type, aggregate_id)` row. Hydration should load that
-record, then replay event rows where `sequence > snapshot.version` ordered
-ascending. If no usable snapshot exists, hydrate from sequence `1`.
-
-If the newest snapshot version exceeds the current maximum event sequence for
-the stream, the implementation should ignore that cache record and hydrate from
-sequence `1`. Snapshot cache fallback should be observable when tracing exists,
-but it should not turn a recoverable cache miss into command failure.
-
-Snapshot retention is implementation-specific but must be explicit. The current
-SQL adapters retain only the latest cache record per stream. Future adapters may
-retain last `N` or time-based cache records, but they must never prune aggregate
-events.
-
-## Transactional Read Models
-
-Postgres read-model write plans write relational table rows inside the same
-repository transaction as aggregate events. Mutations are written to the
-registered read-model tables generated from schema metadata
-(`bootstrap_table_schema_for_dev` for tests/local development, migration
-artifacts for managed environments). Those writes use the model's declared
-columns directly, including `jsonb` columns for collection fields and
-`_sourced_version` for optimistic row versions.
-
-There is no generic SQL document table in this repository contract. If a
-command-side view needs whole-view state in SQL, define a read-model table with
-an `id` column and one or more `jsonb` columns for the semistructured data.
-Generic document mutations require a dedicated document adapter rather than the
-Postgres event-store repository.
-
-`read_model_processed_messages` stores idempotency marks for distributed
-projectors that commit a read-model write plan and mark a message processed in
-one transaction:
-
-```sql
-PRIMARY KEY (consumer_name, message_id);
-CHECK (consumer_name <> '');
-CHECK (message_id <> '');
-```
-
-`read_model_processed_messages` is shared by relational write-plan commits so
-projectors can atomically write rows and record consumed messages.
-
-Relationship include loading is a separate query concern; the transactional
-write path persists the row mutations staged by `ReadModelWritePlan`.
-
-## Commit Semantics
-
-`Commit::commit` and `TransactionalCommit::commit_batch` establish the behavior
-that the Postgres implementation must preserve.
-
-Before writing:
-
-- normalize each entity into `(aggregate_type, aggregate_id)`;
-- reject duplicate stream identities inside one batch before any SQL write;
-- compute new event sequences from `entity.committed_version() + 1`;
-- reject empty aggregate IDs or aggregate types.
-
-Inside one database transaction:
-
-- verify each stream's stored version matches `entity.committed_version()`;
-- insert all new event rows with their computed sequence numbers;
-- write transaction-compatible outbox, read model, and snapshot rows included in
-  the structured batch;
-- commit once only after every write succeeds.
-
-After commit succeeds:
-
-- mark in-memory entities committed;
-- update snapshot version metadata;
-- return success.
-
-If any validation or write fails:
-
-- no event rows from the batch are visible;
-- no read model, outbox, or snapshot rows from the batch are visible;
-- entities keep their pending `new_events()` and committed versions for retry.
-
-The database must enforce the sequence invariant with
-`PRIMARY KEY (aggregate_type, aggregate_id, sequence)`. A unique violation on
-that key maps to `RepositoryError::ConcurrentWrite` after querying the current
-stream version for the actual value.
-
-## Optimistic Concurrency
-
-For each stream, the expected stored version is `entity.committed_version()`.
-The appended events receive sequences:
-
-```text
-expected_version + 1
-expected_version + 2
-...
-```
-
-Two writers appending to the same stream with the same expected version cannot
-both commit. Postgres may detect the conflict through an explicit version check,
-through the primary-key insert, or both. The public error should identify:
-
-- aggregate type,
-- aggregate ID,
-- expected version,
-- actual stored version.
-
-The current `RepositoryError::ConcurrentWrite { id, expected, actual }` can
-represent this initially by formatting `id` as a compact JSON object such as
-`{"aggregate_type":"todo","aggregate_id":"todo:1"}`. Generate that string with
-the JSON serializer rather than manual concatenation so embedded separators in
-either component cannot collide. A later API can split type and ID if needed.
-
-## Locking Model
-
-The Postgres repository enforces optimistic concurrency with the
-`(aggregate_type, aggregate_id, sequence)` primary key. That uniqueness
-constraint is the authoritative cross-process write-conflict boundary and holds
-regardless of any lock — concurrent writers to the same stream collide on the
-sequence and one fails.
-
-For workflows that want to *serialize* per-aggregate read/modify/write (rather
-than let a stale writer fail and retry), `QueuedRepository` can be backed by a
-durable lock manager instead of the default process-local
-`InMemoryLockManager`. `PostgresLockManager` (and `SqliteLockManager`)
-implement `LockManager` over an `aggregate_locks` lease table:
-
-- a held key is a row carrying an `owner_token` and an `expires_at` computed from
-  the database clock (one authoritative clock, so no cross-process skew);
-- acquisition is a single atomic conditional upsert (insert when absent, steal
-  when expired, re-acquire your own token); contention polls on a configurable
-  interval until won or `max_wait` elapses;
-- release is scoped to the owner token, so it never frees a holder that
-  legitimately reclaimed an expired lease.
-
-This is a **mutual-exclusion optimization, not a fencing guarantee.** A critical
-section that outlives `lease_ttl` can be stolen while the original holder still
-believes it holds the lock — safe only because the sequence primary key above is
-the real boundary (a stale writer fails its optimistic commit rather than
-corrupting data). v1 has **no lease renewal**, so set `lease_ttl` above the
-worst-case critical section. Rows from crashed holders are reused on the next
-acquire of the same key, or swept with `sweep_expired`.
-
-`QueuedRepository` over the in-memory manager remains a process-local convenience
-for examples, tests, and single-process adapters.
-
-## Backward Compatibility
-
-Rows or imported JSON records without event metadata deserialize with empty
-metadata. Postgres migrations should still write
-`metadata jsonb NOT NULL DEFAULT '{}'` so newly stored rows are explicit.
-
-Rows without payload codec metadata should be interpreted only by an explicit
-legacy import path. Newly written Postgres rows must always populate
-`payload_codec` and `payload_codec_version`.
-
-## Runtime Posture
-
-Postgres access is async-first through the public repository, read-model,
-snapshot, inbox, lock, and outbox traits. Do not add production Postgres access
-behind blocking adapters or synchronous repository shims; SQL I/O belongs in
-async `sqlx` paths.
-
-## TypeORM Lineage
-
-The old `sourced-repo-typeorm@3.2.14` shape is useful history, not the Rust
-contract.
-
-Carried forward:
-
-| TypeORM field | Rust/Postgres contract |
-| --- | --- |
-| `entityType` | `aggregate_type` |
-| `id` | `aggregate_id` |
-| `method` | `event_name` |
-| `version` | `sequence` |
-| `data jsonb` | `payload` plus explicit codec metadata |
-| `timestamp bigint` | `recorded_at timestamptz` |
-| `snapshotVersion` | snapshot row `version` |
-
-Intentionally changed:
-
-- The primary key is `(aggregate_type, aggregate_id, sequence)`, not
-  `(entityType, id, method, version)`.
-- `method`/`event_name` is not part of stream sequence uniqueness.
-- Snapshots move to `aggregate_snapshots` instead of sharing the event table
-  through a `snapshot` boolean.
-- TypeORM `synchronize: true` is not a migration strategy. Use explicit SQL
-  migrations.
-- Dynamic aggregate-field indexes are not inherited. Business queries belong in
-  read models or declared schema-backed indexes.
-- `findAll` is not inherited as an unspecified operation. If used over
-  aggregates, it must mean an explicit scan or a documented indexed query.
-
-## Existing Behavioral Tests
-
-The in-memory repository already pins the behaviors the Postgres repository must
-match:
-
-- `src/in_memory_repo/repository.rs::duplicate_stream_ids_rejected_before_write`
-  verifies duplicate stream IDs are rejected before any write.
-- `tests/event_store/main.rs::concurrent_writes_detected` verifies optimistic
-  conflicts return `ConcurrentWrite`.
-- `tests/event_store/main.rs::partial_conflict_rolls_back_entire_commit`
-  verifies a failed mixed-stream append leaves other streams unchanged.
-
-Postgres-specific tests should add:
-
-- schema migration smoke test for all tables, constraints, and indexes;
-- successful append and replay of one stream;
-- multi-stream `commit_batch` all-or-none behavior;
-- duplicate `(aggregate_type, aggregate_id)` in one batch rejected before SQL
-  writes;
-- concurrent append conflict on the same next sequence;
-- snapshot save and load from latest snapshot plus tail events;
-- codec rejection for unknown `payload_codec` or `payload_codec_version`;
-- read model/outbox/snapshot rollback when included in a transaction-compatible
-  batch.
-
-## Out Of Scope
-
-- Implementing the actual Postgres repository.
-- Designing the final read-model table layout.
-- Designing the outbox message table in detail.
-- Changing the established async repository trait surface.
diff --git a/docs/read-models.md b/docs/read-models.md
deleted file mode 100644
index 850bda9f..00000000
--- a/docs/read-models.md
+++ /dev/null
@@ -1,250 +0,0 @@
-# Read Models
-
-Read models are query-optimized projection state stored as relational rows with
-table, column, key, index, relationship, and schema metadata. Whole-view state
-belongs in a declared table too: use an `id` column and JSON/JSONB columns for
-semistructured fields.
-
-The current implementation keeps these paths explicit:
-
-| Path | API | Use when |
-|---|---|---|
-| Relational write mapping | `RelationalReadModel`, `ReadModelWritePlanBuilder`, `ReadModelWritePlan` | Normalized tables, composite keys, foreign keys, JSONB columns |
-| Explicit relationship includes | `store.workspace().load(...).include(...).one()`, `sync` | Internal primary-key reads with declared one-level relationships |
-| Schema lifecycle | `ReadModelSchemaRegistry`, `ReadModelSchemaAdapter` | Migration artifact generation, startup verification, explicit dev/test bootstrap |
-
-## Relational Models
-
-A model opts into relational metadata with `#[readmodel(table = "...")]` and
-field attributes. Common collection, table, column, id, index, and unique
-metadata also have direct helper attributes:
-
-```rust
-use serde::{Deserialize, Serialize};
-use distributed::ReadModel;
-
-#[derive(Clone, Debug, Serialize, Deserialize, ReadModel)]
-#[table("players")]
-pub struct PlayerView {
-    #[id("player_id")]
-    pub id: String,
-    pub display_name: String,
-    #[readmodel(jsonb)]
-    pub counters_by_game: std::collections::HashMap<String, i64>,
-    #[readmodel(has_many = "PlayerWeaponView", foreign_key = "player_id")]
-    pub weapons: Vec<PlayerWeaponView>,
-}
-
-#[derive(Clone, Debug, Serialize, Deserialize, ReadModel)]
-#[readmodel(table = "player_weapons", primary_key = ["player_id", "weapon_id"])]
-#[index(
-    name = "idx_player_weapons_player_acquired",
-    columns = ["player_id", "acquired_at"]
-)]
-pub struct PlayerWeaponView {
-    #[readmodel(foreign_key = "players.player_id", delegated_from = "PlayerView.player_id")]
-    pub player_id: String,
-    pub weapon_id: String,
-    #[index]
-    pub acquired_at: String,
-}
-```
-
-The derive emits `RelationalReadModel` metadata, row conversion, primary-key
-metadata, JSONB column metadata, indexes, and an adapter-owned version column.
-Composite and delegated keys are represented in the schema and in write-plan row
-mutations.
-
-Use `#[index]` or `#[index("index_name")]` for a secondary field index. Use
-`#[unique]` or `#[unique("index_name")]` for a unique field index.
-For compound indexes, put `#[index(columns = ["field_a", "field_b"])]` or
-`#[unique(columns = ["field_a", "field_b"])]` on the struct. Add
-`name = "..."` when the storage index name must be fixed.
-
-## Explicit Relationship Includes
-
-Relationship includes are primary-key anchored and opt-in. Register the
-relational schemas with an adapter, load one root row, ask for each relationship
-explicitly, mutate the hydrated struct, then sync the tracked workspace:
-
-```rust
-use distributed::{InMemoryReadModelStore, ReadModelWorkspaceExt, RowKey, RowValue};
-
-let store = InMemoryReadModelStore::new();
-store.register_schema::<PlayerView>()?;
-store.register_schema::<PlayerWeaponView>()?;
-
-let mut workspace = store.workspace();
-let mut player = workspace
-    .load::<PlayerView>(RowKey::new([("player_id", RowValue::String("player-1".into()))]))
-    .include("weapons")
-    .one()?
-    .expect("player should exist")
-    .data;
-
-player.display_name = "Ada Lovelace".into();
-player.weapons.push(PlayerWeaponView {
-    player_id: String::new(),
-    weapon_id: "sword".into(),
-    acquired_at: "2026-05-23".into(),
-});
-
-workspace.sync(player)?;
-workspace.commit()?;
-```
-
-`has_many` relationships hydrate `Vec<T>` fields. `belongs_to` relationships
-hydrate `Option<T>` fields.
-
-`sync` makes storage match the struct: added items are inserted, changed
-items updated, and **removed items deleted**. For an included `has_many`
-collection, dropping a child from the `Vec<T>` deletes that child row (the loaded
-collection is the complete owned set, so the struct is the source of truth).
-Added children have their delegated foreign keys filled before the write plan is
-staged. Every change — including the delete — lowers to an explicit mutation in
-the `ReadModelWritePlan`; nothing cascades to rows you did not load.
-
-Clearing a `belongs_to` field to `None` is a no-op on the target: it never
-deletes the owner, since other rows may reference it. To delete a whole root,
-use `delete::<Root>(key)`.
-
-This API is for command handlers, projectors, tests, admin tools, and adapter
-conformance that need typed internal includes. It is not a public query DSL.
-A query gateway (Hasura, PostgREST, custom GraphQL, …) remains a common
-choice for the public query API over normalized Postgres read models —
-command/write traffic still goes through `microsvc` handlers.
-
-## Command-Side Atomic Writes
-
-Use `ReadModelWritePlanBuilder` when a command or projector stages multiple
-row mutations:
-
-```rust
-use distributed::{ReadModelWritePlanBuilder, ReadModelWritePlanCommitExt};
-
-let mut read_models = ReadModelWritePlanBuilder::new();
-read_models.upsert(&player)?;
-read_models.upsert_related(&player, "weapons", &weapon)?;
-
-repo.read_models(read_models)
-    .commit(&mut aggregate)
-    .await?;
-```
-
-Builder ordering is semantic staging only. These forms are equivalent:
-
-```rust
-repo.read_models(read_models)
-    .outbox(message)
-    .commit(&mut aggregate)
-    .await?;
-
-repo.outbox(message)
-    .read_models(read_models)
-    .commit(&mut aggregate)
-    .await?;
-
-repo.aggregate(&mut aggregate)
-    .read_models(read_models)
-    .outbox(message)
-    .commit()
-    .await?;
-```
-
-## Standalone Distributed Projectors
-
-A read-model service can commit a write plan without owning an aggregate
-repository:
-
-```rust
-use distributed::{ReadModelError, ReadModelWritePlanBuilder, ReadModelWritePlanStore};
-
-async fn project_message(
-    store: &impl ReadModelWritePlanStore,
-    event_id: &str,
-    view: &PlayerView,
-) -> Result<(), ReadModelError> {
-    let mut read_models = ReadModelWritePlanBuilder::new();
-    read_models
-        .upsert(view)?
-        .mark_processed("game-view-projector", event_id);
-
-    let outcome = read_models.commit(store).await?;
-    if outcome.was_applied() || outcome.was_skipped() {
-        // Ack the broker message after commit returns.
-    }
-    Ok(())
-}
-```
-
-Processed-message marks are committed in the same adapter transaction as
-read-model writes when the adapter advertises that capability. Duplicate
-messages return a skipped outcome and do not apply the staged mutations again.
-
-## Schema Registry And Bootstrap
-
-Register relational models once and pass the registry to adapters:
-
-```rust
-use distributed::ReadModelSchemaRegistry;
-
-let mut registry = ReadModelSchemaRegistry::new();
-registry
-    .register::<PlayerView>()?
-    .register::<PlayerWeaponView>()?;
-
-registry.validate()?;
-```
-
-Adapters implement `ReadModelSchemaAdapter` to generate migration artifacts,
-verify startup schema, or explicitly bootstrap dev/test schemas. Production
-schema changes should be generated or user-authored migrations plus
-verification; normal repository construction and command handling should not
-silently sync production schemas.
-
-SQL repositories expose the same lifecycle through neutral table-schema APIs so
-read models and operational tables, such as the outbox table, use one metadata
-path:
-
-```rust
-let mut registry = TableSchemaRegistry::new();
-registry.register_schema(distributed::outbox_message_schema())?;
-
-let artifacts = repo.generate_table_migration_artifacts(&registry)?;
-let bootstrap = repo.bootstrap_table_schema_for_dev(&registry).await?;
-```
-
-Use generated artifacts as migration input for production tooling such as Atlas.
-Reserve `bootstrap_table_schema_for_dev` for tests and local development.
-
-## Whole-View Rows
-
-Bomberman `BoardView` is a read-model table row. It stores a whole game board
-view with nested players, bombs, explosions, tiles, turn state, and counters in
-declared columns, using JSON/JSONB for nested state.
-
-If a command projection needs this shape, define a table with an `id` column and
-JSON/JSONB columns for the board state:
-
-```rust
-#[derive(Clone, Debug, Serialize, Deserialize, ReadModel)]
-#[readmodel(table = "boards")]
-pub struct BoardView {
-    #[readmodel(id)]
-    pub game_id: String,
-    #[readmodel(jsonb)]
-    pub players: Vec<PlayerState>,
-    #[readmodel(jsonb)]
-    pub bombs: Vec<BombState>,
-}
-```
-
-It is still a relational row write. There is no generic document table hidden
-behind the SQL repositories.
-
-## Non-Goals
-
-The relational ORM slice is a persistence mapper, not a business layer. It does
-not own business logic, authorization policy, aggregate invariants, domain event
-selection, public query APIs, lifecycle hooks, hidden cascades, generic
-document-table mutation APIs, or broad SQL query DSLs.
diff --git a/docs/repositories.md b/docs/repositories.md
deleted file mode 100644
index 9d33f216..00000000
--- a/docs/repositories.md
+++ /dev/null
@@ -1,88 +0,0 @@
-# Repository Boundary
-
-Distributed, currently published from the `distributed` crate, keeps the
-repository API async-only. The repository traits are stream-aware and are used
-by the in-memory, SQLite, and Postgres adapters.
-
-Event-store adapters load and commit streams with `StreamIdentity`, the pair
-`(aggregate_type, aggregate_id)`, rather than an ID-only key.
-`Aggregate::aggregate_type()` provides the type component; the default uses
-Rust's type name for development compatibility, but production persistence
-should override it with an explicit durable name through `impl_aggregate!(...,
-aggregate_type = "...")`, `aggregate!(..., aggregate_type = "..." { ... })`, or
-`#[sourced(..., aggregate_type = "...")]`.
-
-## Core Traits
-
-- `GetStream` loads one or more event streams by full identity.
-- `TransactionalCommit` commits `CommitBatch` values with stream
-  writes, read-model write plans, and snapshots under one backend transaction.
-- `ReadModelWritePlanStore` and `RelationalReadModelQueryStore`
-  mirror the relational read-model write and primary-key load surfaces for
-  repository adapters.
-- `SnapshotStore` keys rebuildable snapshot cache records by full stream
-  identity. The record envelope carries stream identity, covered event version,
-  snapshot payload type/version, payload codec metadata, cache metadata, and
-  timestamp.
-- `OutboxStore` exposes async claim/update operations for durable outbox
-  table stores. Aggregate repositories commit outbox rows transactionally, but
-  workers do not hydrate outbox messages through aggregate repositories.
-
-## In-Memory Reference
-
-`InMemoryRepository`, `InMemoryReadModelStore`, and `InMemorySnapshotStore`
-implement the repository traits as a behavioral reference for conformance tests.
-The in-memory implementation is not a production I/O adapter; it exists so
-Postgres, SQLite, and other persistent backends can be tested against the same
-stream-aware contract before SQL code lands.
-
-The Postgres repository implements the traits directly with `sqlx`; database I/O
-is not hidden behind blocking wrappers in normal async runtimes.
-
-## SQLite Adapter
-
-The optional `sqlite` feature exports `SqliteRepository`, an async-only
-SQL-backed adapter for local persistence and conformance work:
-
-```rust
-let repo = distributed::SqliteRepository::connect_and_migrate("sqlite::memory:").await?;
-```
-
-`SqliteRepository::migrate` applies explicit SQLite migrations from
-`migrations/sqlite`. Plain construction from an existing pool does not create
-tables implicitly, so applications can control bootstrap order.
-
-The SQLite adapter persists aggregate events, relational read-model write
-plans, processed-message marks, and snapshots in one SQL transaction when they
-are staged through `CommitBatch`. It intentionally does not claim Postgres
-production readiness: Postgres-specific column types, isolation behavior, error
-mapping, deployment, and migration validation still belong to the Postgres
-adapter and its own tests.
-
-## Postgres Adapter
-
-The optional `postgres` feature exports `PostgresRepository`, an async-only
-SQLx adapter for the production SQL event-store path:
-
-```rust
-let repo =
-    distributed::PostgresRepository::connect_and_migrate(database_url).await?;
-```
-
-Local integration tests can use the root `compose.yaml` service:
-
-```bash
-docker compose up -d postgres
-DATABASE_URL=postgres://sourced:sourced@localhost:5432/distributed \
-  cargo test --features postgres --test postgres_repository
-```
-
-The SQLite and Postgres adapters persist aggregate event streams, read-model
-write plans, processed-message marks, snapshots, and outbox rows through
-explicit migrations plus registered table schemas. Relational read-model
-mutations (`upsert`, sparse `patch`, and `delete`) are lowered into SQL writes
-against the tables generated from `#[derive(ReadModel)]` / `RelationalReadModel`
-schema metadata, including JSON/JSONB columns and `_sourced_version` optimistic
-versions. SQL repositories do not persist generic document rows; whole-view
-state that belongs in SQL should be modeled as a declared read-model table with
-an `id` column and JSON/JSONB columns for semistructured fields.
diff --git a/docs/research-and-roadmap.md b/docs/research-and-roadmap.md
deleted file mode 100644
index 7707ac75..00000000
--- a/docs/research-and-roadmap.md
+++ /dev/null
@@ -1,87 +0,0 @@
-# Research & Roadmap
-
-Based on a review of the Rust ES ecosystem (cqrs-es, disintegrate, esrs, eventually-rs, kameo_es/SierraDB) and mature frameworks in other languages (Axon, EventFlow, Marten).
-
----
-
-## Prioritized Work Items
-
-### Core Improvements
-
-#### Trait support
-All competing frameworks are async-first. The current public persistence and transport traits are async-first, which supports direct integration with:
-- async databases (sqlx, sea-orm)
-- async message brokers (rdkafka, lapin)
-- async web frameworks (axum handlers)
-
-Foundation status: stream-aware repository/read-model/snapshot/outbox traits now form the async-only persistence surface. See [Repository Boundary](repositories.md). The SQL backends implement those traits directly instead of wrapping database I/O behind synchronous repository traits.
-
-### Later
-
-- **Postgres backend** — proves the trait design, makes the library production-usable. Use sqlx. The event-record storage contract is outlined in [Postgres Event Store Contract](postgres-event-store.md).
-- **API docs** — `cargo doc` with doc comments on all public traits/types.
-- **Publish to crates.io** — after the above items stabilize.
-- **Domain service** — TBD whether to keep. Not documenting further until decided.
-
----
-
-## Ecosystem Comparison (Reference)
-
-### Feature Matrix
-
-| Feature | distributed | cqrs-es | disintegrate | esrs | eventually-rs |
-|---------|-------------|---------|-------------|------|---------------|
-| Aggregates | Yes (PORS + macros) | Yes (trait) | Decision pattern | Yes (trait) | Yes (DDD) |
-| Event storage | In-memory | PG/MySQL/Dynamo | PG/In-memory | PG only | PG/In-memory |
-| Projections/Read models | Yes (3 strategies) | Query trait | EventListener | EventHandler (2 types) | Projection trait |
-| Snapshots | Yes (frequency-based) | Yes | Via StateQuery | Yes (Nth event) | No |
-| Outbox pattern | Yes (first-class) | No | No | Implicit (TransactionalEventHandler) | No |
-| Service bus (pub/sub + P2P) | Yes | No | No | No | No |
-| Saga support | Via aggregates | Via handlers | Via EventListener | Via handlers | Via Subscription |
-| Event upcasting | **No** | **Yes** | No | No | Partial |
-| Native async | Partial | Yes | Yes | Yes | Yes |
-| Testing framework | N/A (simple code) | Given-When-Then | In-memory store | Manual | AggregateRootBuilder |
-| Optimistic concurrency | Yes | Yes | Yes (+ validation queries) | Yes (+ pessimistic) | Yes |
-| Pessimistic locking | Yes (QueuedRepo) | No | No | Yes (lock_and_load) | No |
-| Event metadata | Yes | Yes | Yes | Yes | Yes |
-| Derive macros | digest, aggregate, ReadModel | No | Yes (Event, StateQuery) | No | No |
-| Observability | No | No | No | Yes (tracing) | No |
-| Pluggable infra (all concerns) | **Yes (6 traits)** | Partial (storage) | Partial (storage) | No (PG only) | Partial (storage) |
-
-### distributed differentiators (things others don't have)
-- **Outbox pattern as first-class** with fan-out and point-to-point routing
-- **Service bus** with both pub/sub and send/listen patterns
-- **Read model transactional commits** with decision flowchart for choosing consistency strategy
-- **6 pluggable infrastructure traits** (storage, messaging, read model store, snapshot store, outbox publishing, locking)
-- **Guard conditions on events** (`when = !self.completed`)
-- **PORS approach** — domain objects are plain structs, not framework types
-
-### Key competitors at a glance
-
-**cqrs-es** (~463 GitHub stars, most mature)
-- Best testing framework, event upcasting, 3 storage backends
-- Serverless-first design
-- Docs: [doc.rust-cqrs.org](https://doc.rust-cqrs.org/)
-
-**disintegrate** (innovative approach)
-- Decision pattern instead of aggregates
-- Validation queries for fine-grained optimistic concurrency
-- Derive macros for events and state queries
-- Docs: [docs.rs/disintegrate](https://docs.rs/disintegrate)
-
-**esrs** (production-proven at Prima.it)
-- Transactional vs eventually-consistent event handlers
-- Built-in tracing/observability
-- Pessimistic locking option
-- Docs: [docs.rs/esrs](https://docs.rs/esrs)
-
-**eventually-rs** (pre-1.0, DDD-pure)
-- Clean DDD abstractions
-- Subscription mechanism for reactive processing
-- Limited documentation
-- Docs: [docs.rs/eventually](https://docs.rs/eventually)
-
-**kameo_es + SierraDB** (successor to thalo, newest)
-- Actor-based (kameo) + distributed event store (SierraDB)
-- Historical + live subscriptions with guaranteed delivery
-- Very new, worth watching
diff --git a/docs/transports.md b/docs/transports.md
deleted file mode 100644
index 33c6b0e9..00000000
--- a/docs/transports.md
+++ /dev/null
@@ -1,230 +0,0 @@
-# Microservice Transports
-
-Distributed (published from the `distributed` crate) exposes an async-only
-transport layer under `bus`. The in-memory bus is the dev/test implementation of
-the same async contracts. The design line is:
-
-- **`microsvc`** owns handler registration, guards, typed input decoding,
-  dispatch, and handler metadata;
-- **transport adapters** own how messages are received, acknowledged, retried,
-  published, and mapped to external topics/subjects/queues/routes.
-
-The shared vocabulary lives in `bus` and depends on no concrete
-broker. The same application code runs over any transport — selecting one is an
-adapter/wiring change, not a handler change.
-
-## Core vocabulary
-
-| Type | Purpose |
-| --- | --- |
-| `TransportError` / `TransportErrorKind` | Retryable vs permanent classification. Drives redelivery vs the failure policy. |
-| `FailurePolicy` / `FailureAction` | What happens to a permanent failure: `Retry`, `DeadLetter`, `Park`, `LogAndAck`, `Stop`. |
-| `RunOptions` / `ConsumerDeliveryMode` / `InboxHook` | Idempotent dispatch by default; placeholder hook for the future consumer inbox. |
-| `TransportCapabilities` | Per-transport receive durability, publish confirmation, retry ownership, ack kind, Knative integration. |
-| `validate_stable_message_id` | Rules an inbox-enabled run uses to reject messages lacking a usable dedup key. |
-
-### Two confirmation thresholds
-
-Producing and consuming have *separate* completion thresholds:
-
-- **Producer publish threshold** — when an outbox row may be marked published:
-  Postgres transaction commit, RabbitMQ publisher confirm, Kafka producer ack
-  (`acks`), NATS JetStream publish ack, Knative 2xx, in-memory acceptance. Only
-  then is the row complete; an unknown outcome stays retryable.
-- **Consumer ack threshold** — when the adapter may acknowledge receipt: only
-  after the handler (and any inbox receipt) committed. The default never
-  silently acks a handler error — retryable failures redeliver, permanent
-  failures go through the `FailurePolicy`.
-
-## Receiving: `MessageSource` + `run_source`
-
-Direct transports implement `MessageSource` (pull a message) and
-`ReceivedMessage` (settle it). `run_source` drives the loop, dispatching through
-`Service::dispatch_message` and settling only after the handler completes:
-
-```rust,ignore
-use distributed::bus::{run_source, RunOptions};
-
-run_source(service, source, RunOptions::idempotent()).await?;
-```
-
-The runner acks on success, nacks retryable failures for redelivery, routes
-permanent failures through the failure policy, **acks-and-ignores** messages with
-no registered handler (so fan-out transports can over-deliver), stops gracefully
-when the source drains, and never swallows receive/settle errors. Inbox mode
-(`RunOptions::inbox(hook)`) enforces a stable message id before dispatch.
-
-## Publishing: `MessagePublisher` + outbox
-
-`MessagePublisher` is the single publish boundary; each adapter documents
-its publish threshold. `OutboxDispatcher` bridges durable outbox rows to a
-publisher, sharing one claim → publish → complete path between background polling
-(`dispatch_batch`) and after-commit immediate dispatch (`dispatch_ids`):
-
-```rust,ignore
-let dispatcher = OutboxDispatcher::new(store, publisher, "worker-1", lease, max_attempts);
-let outcome = dispatcher.dispatch_ids(&committed_ids).await?; // claim-before-publish
-```
-
-A row completes only after `publish()` resolves `Ok`; an unknown/failed publish
-leaves it retryable (release until the attempt ceiling, then fail). Outbox rows
-map to a canonical `Message` via `From<&OutboxMessage>`; framework-derived
-metadata (codec, destination, source aggregate) is namespaced under the reserved
-`x-sourced-` prefix so it cannot be shadowed by user metadata.
-
-Telemetry follows the same boundary. Consumer-side direct transports report
-receive/settle outcomes and classified failures. Producer-side outbox dispatch
-reports `published`, `released`, `failed`, and backlog gauges. A direct
-`MessagePublisher` call outside the outbox path is not counted as an outbox
-publish and currently has no direct publish metric; adding that should be a
-separate producer telemetry path with its own bounded labels.
-
-Trace context is normal metadata. Distributed preserves W3C `traceparent` and
-`tracestate` across `Message`, `EventRecord`, and `OutboxMessage` carriers
-without requiring an OpenTelemetry SDK in the default build. See
-[`observability.md`](observability.md) for trace helpers, the optional `otel`
-span feature, and GitOps observability output.
-
-## Adapters
-
-| Transport | Feature | Source / Publisher | Notes |
-| --- | --- | --- | --- |
-| In-memory | (always) | conformance fakes | Reference adapter; reused by `transport_conformance`. |
-| Postgres | (always) | `OutboxSource<PostgresOutboxStore>` | Outbox-backed durable receive: `FOR UPDATE SKIP LOCKED` + lease, ack→complete, nack→release, dead-letter/park→fail. The starter durable transport. |
-| NATS JetStream | `nats` | `NatsJetStreamSource` / `NatsPublisher` | ack/nak/term; stable id rides as `Nats-Msg-Id` (also the dedup key). |
-| RabbitMQ | `rabbitmq` | `RabbitSource` / `RabbitPublisher` | Publisher confirms; `basic_get`; ack/nack-requeue/reject. |
-| Kafka | `kafka` | `KafkaSource` / `KafkaPublisher` | `acks=all`; consumer-group offset commit on ack, seek-back on nack. |
-| Knative / HTTP | `http` | `cloud_events_router` (ingress) | Endpoint-driven, not a polling source; 200 success / 503 retryable / 422 permanent; `knative_triggers()` renders Trigger YAML from `subscription_plan()`. |
-
-Postgres is the low-ops starter: one Postgres cluster can back repositories,
-read models, outbox, and durable transport. (`sqlxmq` was evaluated but its
-push-based `JobRegistry` does not fit the pull-based `MessageSource` /
-`run_source` boundary, so the proven durable-queue patterns were borrowed rather
-than the crate — see `tasks/postgres-transport-adapter-first-pass`.)
-
-Retry/backoff/dead-lettering ownership differs: with Knative it is
-**platform-managed** (Delivery/Trigger config); with direct transports the
-adapter and this crate own it via the `FailurePolicy` and the outbox lease.
-
-## Bus facade: `send`/`listen` + `publish`/`subscribe`
-
-The adapters above are the low-level boundary. The **bus facade** is the
-ergonomic surface on top: a produce trait [`Bus`] (`send` a command, `publish` an
-event) and a consume trait [`BusConsumer`] (`listen` for commands, `subscribe` to
-events), implemented by a per-transport `*Bus` type. `listen`/`subscribe` derive
-the message names from the service's registered handlers
-(`command_names()`/`event_names()`), build the transport's source with the right
-topology, and run it through the shared `run_source` — handler code and
-`dispatch_message` never change.
-
-The app surface is identical across transports; only the constructor changes:
-
-```rust
-use std::sync::Arc;
-use distributed::bus::{Bus, BusConsumer, InMemoryBus, RunOptions};
-
-// Built once — handlers are transport-agnostic. The service name becomes the
-// default durable consumer group for broker-backed buses.
-let service = Arc::new(build_service().named("order-api"));
-
-// Dev/test: in-memory.
-let bus = InMemoryBus::new();
-bus.send("place.bet", payload).await?;          // point-to-point command (1:1)
-bus.publish("seat.reserved", payload).await?;   // fan-out event (1:N)
-bus.listen(service.clone(), RunOptions::idempotent()).await?;     // competing
-bus.subscribe(service.clone(), RunOptions::idempotent()).await?;  // fan-out
-
-// Production: swap the one constructor line — send/listen/publish/subscribe
-// and the handlers are unchanged. A named Service supplies the consumer group.
-let namespace = "orders-prod";
-//   let bus = NatsBus::connect("nats://localhost:4222").namespace(namespace).await?;
-//   let bus = PostgresBus::new(pool);
-//   let bus = SqliteBus::new(pool);
-//   let bus = RabbitBus::connect("amqp://localhost:5672/%2f").namespace(namespace).await?;
-//   let bus = KafkaBus::connect("localhost:9092").namespace(namespace).await?;
-```
-
-`group` and `namespace` are broker topology names, not the command/event names
-your service handles. Handler names come from the service's `subscription_plan()`.
-`Service::named(..)` supplies the default durable consumer `group`: all replicas
-of one service deployment use the same value; independent event consumers use
-different values so each gets its own event copy. Direct `Handlers` or manual
-`listen`/`subscribe` calls can set the group with `bus.group(..)` or
-`Handlers::named(..)`. `namespace` scopes streams, subjects, topics, queues, or
-exchanges on a shared broker. `PostgresBus` and `SqliteBus` do not take
-`namespace` because the database/schema/file behind `pool` already scopes their
-bus tables.
-
-Topology names are validated before broker use. Keep groups/service names to
-portable deployment IDs (`A-Z`, `a-z`, `0-9`, `_`, `-`); namespaces may also use
-`.`. Blank names, whitespace, control characters, path separators, broker
-wildcards, and names longer than 128 bytes are rejected.
-
-Consumer identity controls the durable broker state in each transport. Command
-handlers should normally be owned by one service deployment, with every replica
-using the same `group` so the deployment competes as one logical consumer. Event
-handlers use distinct `group`s when each service needs its own copy:
-
-| `*Bus` | Feature | `send` / `listen` (competing) | `publish` / `subscribe` (fan-out) |
-| --- | --- | --- | --- |
-| `InMemoryBus` | (always) | named queue, popped once | retained log + per-subscriber cursor |
-| `NatsBus` | `nats` | shared durable `{group}_cmd` on the stream | durable `{group}_evt` per group |
-| `PostgresBus` | `postgres` | `bus_queue`, `FOR UPDATE SKIP LOCKED` | `bus_log` + `bus_offset` per `group` (Kafka-style) |
-| `SqliteBus` | `sqlite` | `bus_queue`, atomic `UPDATE ... RETURNING` lease claim | `bus_log` + `bus_offset` per `group` |
-| `RabbitBus` | `rabbitmq` | default exchange → durable queue `{ns}.cmd.{name}` | topic exchange → queue `{ns}.evt.{group}` per group |
-| `KafkaBus` | `kafka` | shared consumer group `{ns}.{group}.cmd` | consumer group per service `{ns}.{group}.evt` |
-| `KnativeBus` | `http` | POST CloudEvent → `{target}-commands` broker-ingress | POST → own `{source}-events` broker; consume via generated Triggers |
-
-`KnativeBus` implements only [`Bus`] (produce → broker-ingress POST). It has no
-in-process consume loop: `KnativeBus::manifests(&plan, &subscriptions)` renders
-the role-based `Broker` + per-name `Trigger` YAML (subscriber URIs
-`/cloudevent/<type>`, with a `.local(addr)` kubefwd variant), and the service
-mounts `cloud_events_router` so those Triggers reach `dispatch_message`.
-
-`PostgresBus` uses the claim-lease work queue (not `sqlxmq`) for the same reason
-the low-level adapter does — sqlxmq's always-on push runner doesn't compose with
-the uniform drain-to-idle `run_source` model the facade shares; its `bus_log` +
-`bus_offset` fan-out gives single-DB transactional effectively-once (the offset
-advances with the effects). See `specs/transport-bus-facade`.
-
-`SqliteBus` is the same single-database pattern scaled down to a local SQLite
-file: `bus_queue` is claimed with a conditional `UPDATE ... RETURNING` because
-SQLite has no `FOR UPDATE SKIP LOCKED`, and `bus_log`/`bus_offset` provide
-fan-out. It is intended for local durable transport, tests, demos, and small
-single-node deployments, not as a high-throughput broker replacement.
-
-## Testing
-
-The reusable conformance harness (`tests/transport_conformance/`) proves the
-contract with adapter-neutral fakes; `tests/transport_in_memory/` runs it as the
-in-memory reference. Real-broker integration tests are feature-gated and skip
-when their env var is unset:
-
-```sh
-docker compose up -d   # postgres, rabbitmq, kafka, nats (see compose.yaml)
-
-DATABASE_URL=postgres://sourced:sourced@localhost:5432/distributed \
-  cargo test --test postgres_transport --features postgres
-cargo test --test sqlite_transport --features sqlite
-NATS_URL=nats://localhost:4222   cargo test --test nats_transport --features nats
-AMQP_URL=amqp://guest:guest@localhost:5672/%2f \
-  cargo test --test rabbitmq_transport --features rabbitmq
-KAFKA_BROKERS=127.0.0.1:9092     cargo test --test kafka_transport --features kafka
-```
-
-Each transport's integration binary also covers its `*Bus`: a competing-consumer
-case (one delivery across a shared group) and a fan-out case (every group sees
-every event), verified against the real broker. Each broker has a matching GitHub
-Actions job (reusable `.github/workflows/integration-*.yaml`) that runs on PRs and
-on push to `main`.
-
-## Status
-
-Implemented and verified: the core contracts, the source runner, the publisher /
-outbox dispatcher, the conformance harness, the Postgres / SQLite / NATS /
-RabbitMQ / Kafka adapters, the Knative ingress, and the **bus facade** (`Bus` +
-`BusConsumer` with `InMemoryBus` / `NatsBus` / `PostgresBus` / `SqliteBus` /
-`RabbitBus` / `KafkaBus` / `KnativeBus`, each with competing-vs-fan-out
-integration tests against its broker or local database).
-Still open: migrating the in-repo examples to showcase these APIs. See
-`tasks/transport-docs-examples-cutover`.
diff --git a/examples/graphiql.rs b/examples/graphiql.rs
new file mode 100644
index 00000000..9724f9f7
--- /dev/null
+++ b/examples/graphiql.rs
@@ -0,0 +1,106 @@
+//! Local GraphiQL playground for the GraphQL query service.
+//!
+//! Boots an in-memory SQLite read model, seeds sample orders, mounts GraphQL
+//! with GraphiQL enabled, and serves on `http://127.0.0.1:4000/graphql`.
+//!
+//! ```bash
+//! cargo run --example graphiql --features "graphql,sqlite"
+//! ```
+//!
+//! Open the URL in a browser. GraphiQL ships default headers `x-role: user`
+//! and `x-user-id: demo` (edit them in the Headers panel for other roles).
+//!
+//! Override bind address with `GRAPHIQL_ADDR` (default `127.0.0.1:4000`).
+
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+
+use std::sync::Arc;
+
+use distributed::graphql::GraphqlEngine;
+use distributed::microsvc::{serve, Service};
+use distributed::{
+    ColumnType, DistributedProjectManifest, PrimaryKey, TableColumn, TableKind, TableSchema,
+};
+use sqlx::sqlite::SqlitePoolOptions;
+
+fn orders_schema() -> TableSchema {
+    TableSchema {
+        model_name: "OrderView".into(),
+        table_name: "orders".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("order_id", "order_id", ColumnType::Text)
+            },
+            TableColumn::new("customer_id", "customer_id", ColumnType::Text),
+            TableColumn::new("status", "status", ColumnType::Text),
+            TableColumn {
+                column_type: ColumnType::Integer,
+                ..TableColumn::new("total_cents", "total_cents", ColumnType::Integer)
+            },
+        ],
+        primary_key: PrimaryKey::new(["order_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    }
+}
+
+async fn seed_pool() -> sqlx::SqlitePool {
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .expect("connect sqlite");
+    sqlx::query(
+        "CREATE TABLE orders (
+            order_id TEXT PRIMARY KEY,
+            customer_id TEXT NOT NULL,
+            status TEXT NOT NULL,
+            total_cents INTEGER NOT NULL
+        );
+        INSERT INTO orders VALUES
+            ('o1', 'c1', 'open', 1000),
+            ('o2', 'c1', 'shipped', 2000),
+            ('o3', 'c2', 'open', 500),
+            ('o4', 'demo', 'open', 4200);",
+    )
+    .execute(&pool)
+    .await
+    .expect("seed orders");
+    pool
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    let addr = std::env::var("GRAPHIQL_ADDR").unwrap_or_else(|_| "127.0.0.1:4000".into());
+    let pool = seed_pool().await;
+    let manifest = DistributedProjectManifest::new("graphiql-demo").table_schema(orders_schema());
+
+    let engine = GraphqlEngine::from_manifest(&manifest, pool)?
+        .roles(&["user", "anonymous"])
+        .grant_all("user")
+        .graphiql(true)
+        .build()?;
+
+    let service = Arc::new(Service::new().named("graphiql-demo").with_graphql(engine));
+
+    println!();
+    println!("  GraphiQL  →  http://{addr}/graphql");
+    println!("  Health    →  http://{addr}/health");
+    println!();
+    println!("  Default headers (already set in GraphiQL):");
+    println!("    x-role: user");
+    println!("    x-user-id: demo");
+    println!();
+    println!("  Try:");
+    println!("    {{ orders {{ order_id customer_id status total_cents }} }}");
+    println!("    {{ orders(where: {{ status: {{ _eq: \"open\" }} }}) {{ order_id status }} }}");
+    println!("    {{ orders_by_pk(order_id: \"o1\") {{ order_id status total_cents }} }}");
+    println!("    {{ orders_aggregate {{ aggregate {{ count }} }} }}");
+    println!();
+
+    serve(service, &addr).await?;
+    Ok(())
+}
diff --git a/js/.gitignore b/js/.gitignore
new file mode 100644
index 00000000..e7289959
--- /dev/null
+++ b/js/.gitignore
@@ -0,0 +1,3 @@
+dist/
+node_modules/
+*.tgz
diff --git a/js/README.md b/js/README.md
new file mode 100644
index 00000000..d9b1965f
--- /dev/null
+++ b/js/README.md
@@ -0,0 +1,454 @@
+# `@hops-ops/distributed`
+
+The generated, end-to-end typed client for
+[Distributed](https://github.com/hops-ops/distributed) services.
+
+Rust table, relationship, role, and command definitions produce one authorized
+client surface. `dctl client` combines that surface with application GraphQL
+documents and emits typed operations, live companions, route-load plans, and
+commands. This package executes those artifacts through one normalized,
+causally consistent browser replica.
+
+The intended application experience is:
+
+```ts
+const todos = Todos.use();
+const commands = useCommands();
+await commands.todo.create({ title });
+```
+
+Reads populate the replica on demand. Every UI consumer reads that same
+replica. Generated optimistic command effects update it synchronously, and
+server-issued record/index clocks reconcile the authoritative result without
+application-authored cache policies.
+
+## Install
+
+```bash
+npm install @hops-ops/distributed graphql
+```
+
+The package is ESM-only and requires Node 20 or newer for server-side use. It
+also runs in modern browsers. Svelte 5 and React are optional peers used only
+by the `/sveltekit` and `/react` entry points, respectively.
+
+## Generate the client surface
+
+The service, not the browser, owns authorization and GraphQL semantics:
+
+```bash
+dctl client-manifest > target/distributed-client.json
+
+dctl client \
+  --manifest target/distributed-client.json \
+  --role user \
+  --documents 'src/**/*.graphql' \
+  --out src/lib/generated/distributed
+```
+
+Use `--surface <name>` for a named application surface. CI can append `--check`
+to validate that committed artifacts are current without rewriting them.
+
+A co-located route document can opt into SSR and live continuation:
+
+```graphql
+query Todos @load @live {
+  todos(order_by: [{ status: asc }, { todo_id: asc }]) {
+    todo_id
+    title
+    status
+  }
+}
+```
+
+Generation validates the document against the selected role/application,
+injects wire-only identity and revision fields, and emits:
+
+- an exact typed operation and optional live companion;
+- normalization, identity, relationship, filter, order, and pagination plans;
+- the closed variable codec used before cache lookup or transport;
+- a static `@load` route registry;
+- an SSR-safe SvelteKit wrapper with static operation bindings and tree-local
+  client/command access;
+- a nested command tree with input defaults, optimistic effects, and causal
+  confirmation contracts;
+- an exact schema, protocol, and client-surface binding.
+
+Unsupported or unprovable behavior fails during generation. The runtime does
+not parse GraphQL documents, guess cache keys, or infer mutation effects.
+
+## SvelteKit
+
+Install Svelte and describe each generated authorization surface once:
+
+```bash
+npm install svelte
+```
+
+```js
+// distributed.config.js
+const serviceManifestArgs = [
+  'client-manifest',
+  '--manifest-path',
+  '../service/Cargo.toml',
+  '--package',
+  'service'
+];
+
+export const distributedClients = [
+  {
+    module: '$distributed',
+    manifest: { args: serviceManifestArgs },
+    surface: 'e2e-ui',
+    documents: ['src/routes/(app)/**/*.graphql'],
+    out: 'src/lib/generated/distributed'
+  },
+  {
+    module: '$distributed/admin',
+    manifest: {
+      args: [
+        ...serviceManifestArgs,
+        '--entrypoint',
+        'service::distributed_admin_client_surface'
+      ]
+    },
+    surface: 'e2e-ui-admin',
+    documents: ['src/routes/admin/**/*.graphql'],
+    out: 'src/lib/generated/distributed-admin'
+  }
+];
+
+export const distributedViteOptions = {
+  clients: distributedClients
+};
+```
+
+The common and elevated document sets must not overlap. The route group above
+keeps ordinary application documents out of the admin tree; each trust boundary
+has its own Rust manifest entrypoint, generated directory, virtual module, and
+request-local replica. A single-surface application can omit the second entry.
+
+The Vite integration runs `dctl client` at startup/build, watches GraphQL
+documents, stages all surfaces, commits a rollback-capable multi-output
+transaction, then triggers one reload. It exposes the generated Svelte wrapper
+through the configured virtual module:
+
+```ts
+// vite.config.ts
+import { sveltekit } from '@sveltejs/kit/vite';
+import {
+  distributedGraphqlProxy,
+  distributedSvelteKit
+} from '@hops-ops/distributed/sveltekit/vite';
+import { defineConfig } from 'vite';
+import { distributedViteOptions } from './distributed.config.js';
+
+export default defineConfig({
+  plugins: [distributedSvelteKit(distributedViteOptions), sveltekit()],
+  server: {
+    proxy: distributedGraphqlProxy('http://127.0.0.1:8791')
+  }
+});
+```
+
+Give SvelteKit’s language tools the identical aliases:
+
+```js
+// svelte.config.js
+import {
+  distributedSvelteKitAliases
+} from '@hops-ops/distributed/sveltekit/vite';
+import {
+  distributedClients,
+  distributedViteOptions
+} from './distributed.config.js';
+
+export default {
+  kit: {
+    alias: distributedSvelteKitAliases({
+      cwd: distributedViteOptions.cwd,
+      clients: distributedClients
+    })
+  }
+};
+```
+
+One-shot scripts use the same configuration and transaction:
+
+```js
+import {
+  checkDistributedSvelteKit,
+  generateDistributedSvelteKit
+} from '@hops-ops/distributed/sveltekit/vite';
+import { distributedViteOptions } from './distributed.config.js';
+
+await generateDistributedSvelteKit(distributedViteOptions);
+await checkDistributedSvelteKit(distributedViteOptions); // never writes
+```
+
+Create one request-local server replica in the root layout:
+
+```ts
+// src/routes/+layout.server.ts
+import {
+  createDistributedSvelteKitServer
+} from '@hops-ops/distributed/sveltekit';
+import {
+  DISTRIBUTED_ROUTE_OPERATIONS
+} from '$distributed';
+
+const distributed = createDistributedSvelteKitServer({
+  routes: DISTRIBUTED_ROUTE_OPERATIONS,
+  getSession: ({ locals }) => locals.auth(),
+  getRole: (session) => roleFromSession(session)
+});
+
+export const load = distributed.load;
+```
+
+The browser layout installs one client in Svelte context for the current
+authorization lifecycle. The generated module retains no client singleton:
+
+```ts
+// src/routes/+layout.svelte
+import { browser } from '$app/environment';
+import {
+  createPageDataSessionSource
+} from '@hops-ops/distributed/sveltekit';
+import { provideDistributed } from '$distributed';
+
+let { data, children } = $props();
+const pageData = createPageDataSessionSource(data);
+
+const client = provideDistributed({
+  browser,
+  session: pageData.session,
+  ...(data.distributed !== undefined &&
+  data.distributedAuthority !== undefined
+    ? {
+        hydration: data.distributed,
+        authority: data.distributedAuthority
+      }
+    : {})
+});
+
+$effect(() => pageData.set(data));
+```
+
+Route components import only their generated surface. Static operation wrappers
+resolve the nearest tree-local client when used:
+
+```ts
+// src/routes/todos/+page.svelte
+import { Todos, useCommands } from '$distributed';
+
+const todos = Todos.use(); // generated @live attaches automatically
+const commands = useCommands();
+
+await commands.todo.create({ title: 'Ship it' });
+// $todos.data, $todos.status, $todos.pending
+```
+
+When the Rust command declaration supplies a UUIDv7, ULID, or literal input
+default, generation makes that field optional and the runtime fills it exactly
+once. Components do not generate IDs or maintain optimistic/cache recipes.
+
+`@load` results are normalized on the server, dehydrated, and restored in the
+browser without a duplicate first request. Hydration cannot authorize itself:
+the server sends a separate authority value, and the adapter requires both
+values to match. Session, token, tenant, or role changes abort HTTP and live
+work, discard the old generation, and reconnect under server-issued scope.
+
+Use a separate generated surface and replica for elevated routes. A normal
+client cannot import or mix admin artifacts. Configure it as a separate virtual
+module such as `$distributed/admin` and provide it only in the elevated layout.
+
+## Framework-neutral replica
+
+Other frameworks can bind the same core directly:
+
+```ts
+import {
+  createDistributedReplica,
+  createReplicaGraphqlTransport
+} from '@hops-ops/distributed/replica';
+import { Operation_Todos } from './generated/distributed/index.js';
+
+const transport = createReplicaGraphqlTransport({
+  getUrl: () => '/graphql',
+  getAuth: () => ({ accessToken: session.accessToken })
+});
+const replica = createDistributedReplica({ transport });
+const todos = replica.watch(Operation_Todos, {}, { live: true });
+
+const unsubscribe = todos.subscribe((snapshot) => {
+  render(snapshot.data, snapshot.status);
+});
+```
+
+`watch()` reads synchronously, fetches only missing or stale projections,
+deduplicates work, and optionally maintains the generated live operation.
+`read()` is side-effect-free. `dehydrate()` and `hydrate()` transfer confirmed
+request-local state without exposing a public storage schema.
+
+The replica stores normalized records and exact argument-sensitive indexes,
+not GraphQL response blobs. Generated selection metadata reconstructs each
+operation result from that shared state, so a detail read, list read, live
+frame, or optimistic command can update every affected view in one transaction.
+
+## Commands and optimistic UI
+
+Generated `createCommands` binds the service-owned command artifacts to the
+same replica and GraphQL transport. A command call:
+
+1. validates and freezes its typed input;
+2. fills generated UUIDv7, ULID, or literal defaults exactly once;
+3. applies the generated optimistic effect transaction;
+4. dispatches the exact compiler-owned mutation;
+5. keeps ambiguous commits recoverable by command ID;
+6. confirms or rejects only its own optimistic layer;
+7. resolves projected completion only after exact causal evidence arrives.
+
+Applications do not provide list targets, merge functions, mutation update
+callbacks, or invalidation maps. If the compiler cannot prove safe maintenance,
+the generated plan marks the affected projection stale and the replica performs
+one deduplicated revalidation.
+
+Callers may bound their own causal wait without inventing a rollback:
+
+```ts
+const receipt = await commands.todo.create(
+  { title: 'Ship it' },
+  { signal: AbortSignal.timeout(5_000) }
+);
+await receipt.projected;
+```
+
+Before acceptance the signal cancels dispatch. After finite acceptance it
+rejects only that caller's `receipt.projected` wait; the optimistic layer and
+internal causal tracking remain active, and `receipt.status()` stays available.
+
+## React
+
+Install React and use the optional adapter over an application-owned replica:
+
+```tsx
+import {
+  DistributedProvider,
+  useDistributedQuery
+} from '@hops-ops/distributed/react';
+import { Operation_Todos } from './generated/distributed/index.js';
+
+function TodosView() {
+  const todos = useDistributedQuery(Operation_Todos, {}, { live: true });
+  return todos.complete
+    ? todos.data.todos.map((todo) => <div key={todo.todo_id}>{todo.title}</div>)
+    : null;
+}
+
+root.render(
+  <DistributedProvider replica={replica}>
+    <TodosView />
+  </DistributedProvider>
+);
+```
+
+The adapter is only a `useSyncExternalStore` bridge. It does not add another
+cache, transport, auth lifecycle, or command path. For SSR, create one replica
+per request and hydrate only under the same authoritative scope.
+
+## Persistence and diagnostics
+
+The default replica is memory-only. Optional IndexedDB persistence is explicit,
+confirmed-state-only, and governed by generated/application model policy.
+Optimistic layers, command inputs, credentials, cache authority, and live
+connections are never persisted as replica data.
+
+Diagnostics are also opt-in:
+
+```ts
+import {
+  createReplicaDiagnostics
+} from '@hops-ops/distributed/diagnostics';
+
+const diagnostics = createReplicaDiagnostics();
+const replica = createDistributedReplica({ transport, diagnostics });
+const commands = createCommands(replica, transport, { diagnostics });
+```
+
+Snapshots explain operation artifacts, normalized records, index coverage,
+optimistic layers, causal receipts, revalidation, response fences, and garbage
+collection. Defaults pseudonymize identities and omit values, arguments,
+credentials, trusted presets, raw command inputs, and cache scope. Revealing
+additional development detail requires an in-process capability plus an
+explicit redactor.
+
+## Protocol and security boundaries
+
+Every accepted artifact and response is protocol v1 and carries an exact
+schema/client-surface binding. Every response is also bound to a server-issued
+cache scope, operation ID, and trusted-preset inventory; any supplied record
+clocks or index vector are bound to that same scope. Missing, malformed,
+stale-schema, or cross-surface evidence fails closed. An exact authorized
+payload without a safely comparable index vector may render, but it cannot
+advance index clocks/vectors, observations, live resume, or optimistic
+confirmation. Independently valid record clocks remain usable.
+
+OIDC credentials authorize transport requests; decoded client claims never
+create cache authority. GraphQL remains the API and command proxy layer, while
+the service's SQL read models remain authoritative.
+
+Normative architecture and API decisions live in the Distributed GitKB,
+including `specs/query-layer/v1/cache-engine`. They are intentionally not
+duplicated as decision documents in this package.
+
+## Public entry points
+
+- `@hops-ops/distributed` — GraphQL HTTP/WebSocket, auth, and protocol
+  primitives.
+- `@hops-ops/distributed/replica` — replica, GraphQL transport, generated
+  command runtime, query-plan helpers, and optional persistence.
+- `@hops-ops/distributed/diagnostics` — redacted support snapshots and artifact
+  inspection.
+- `@hops-ops/distributed/sveltekit` — Svelte stores, SSR route loading,
+  hydration, auth lifecycle, and tree-local generated bindings.
+- `@hops-ops/distributed/sveltekit/vite` — Node-only one-shot/check/watch
+  generation, virtual module aliases, and GraphQL HTTP/WebSocket proxy helpers.
+- `@hops-ops/distributed/react` — provider and query hook over the same replica.
+
+All other subpaths are private and blocked by the package export map.
+
+## Pre-release clean break
+
+The earlier pilot API and persistence format are intentionally unsupported.
+There is no `QueryCache`, `CacheTarget`, `ListMergeSpec`, `target/at/by`
+addressing, manual cache-policy map, resource wrapper, document store, legacy
+command pipeline, or package-owned codegen executable.
+
+To move an existing pilot application:
+
+1. rerun `dctl client` and import its operation/command artifacts;
+2. compose one replica through the framework adapter or core transport;
+3. remove handwritten cache targets, merge/update callbacks, and invalidation
+   policies;
+4. discard prior browser cache and SSR payloads rather than migrating them.
+
+Only protocol-v1 generated artifacts and server envelopes are accepted.
+
+## Verification and release
+
+```bash
+npm ci
+npm run quality
+npm run release:dry-run
+```
+
+`quality` typechecks generated consumers, runs behavior and adapter suites,
+packs and installs the real tarball into clean consumers, verifies bundle
+boundaries, and runs `publint`. `release:dry-run` exercises npm's publish
+payload without publishing.
+
+Version tags (`vX.Y.Z`) publish with npm provenance through GitHub Actions
+trusted publishing. The package currently uses `UNLICENSED` because the
+repository has no top-level license file; changing that is an explicit
+maintainer decision.
diff --git a/js/package-lock.json b/js/package-lock.json
new file mode 100644
index 00000000..08af2582
--- /dev/null
+++ b/js/package-lock.json
@@ -0,0 +1,1078 @@
+{
+  "name": "@hops-ops/distributed",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@hops-ops/distributed",
+      "version": "0.1.0",
+      "license": "UNLICENSED",
+      "dependencies": {
+        "@graphql-typed-document-node/core": "^3.2.0",
+        "graphql": "^16.14.0"
+      },
+      "devDependencies": {
+        "@apollo/client": "^4.2.7",
+        "@types/node": "^20.0.0",
+        "@types/react": "19.2.17",
+        "esbuild": "^0.25.12",
+        "publint": "^0.3.22",
+        "react": "19.2.8",
+        "react-dom": "19.2.8",
+        "react-test-renderer": "19.2.8",
+        "svelte": "5.56.7",
+        "typescript": "5.8.3"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      },
+      "peerDependencies": {
+        "react": "^18.2.0 || ^19.0.0",
+        "svelte": "^5.0.0"
+      },
+      "peerDependenciesMeta": {
+        "react": {
+          "optional": true
+        },
+        "svelte": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@apollo/client": {
+      "version": "4.2.7",
+      "resolved": "https://registry.npmjs.org/@apollo/client/-/client-4.2.7.tgz",
+      "integrity": "sha512-Z129zR77VP0oWWIXPpHgwbtwhCVBzkw/FhiiymbqwlUniKb5z2KBeuQkpNIz3QfuO7ezHiaxsJ0PPjYBJTSHtg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@graphql-typed-document-node/core": "^3.1.1",
+        "@wry/caches": "^1.0.0",
+        "@wry/equality": "^0.5.6",
+        "@wry/trie": "^0.5.0",
+        "graphql-tag": "^2.12.6",
+        "optimism": "^0.18.0",
+        "tslib": "^2.3.0"
+      },
+      "peerDependencies": {
+        "graphql": "^16.0.0 || ^17.0.0",
+        "graphql-ws": "^5.5.5 || ^6.0.3",
+        "react": "^17.0.0 || ^18.0.0 || >=19.0.0-rc",
+        "react-dom": "^17.0.0 || ^18.0.0 || >=19.0.0-rc",
+        "rxjs": "^7.3.0",
+        "subscriptions-transport-ws": "^0.9.0 || ^0.11.0"
+      },
+      "peerDependenciesMeta": {
+        "graphql-ws": {
+          "optional": true
+        },
+        "react": {
+          "optional": true
+        },
+        "react-dom": {
+          "optional": true
+        },
+        "subscriptions-transport-ws": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz",
+      "integrity": "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.12.tgz",
+      "integrity": "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.12.tgz",
+      "integrity": "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.12.tgz",
+      "integrity": "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.12.tgz",
+      "integrity": "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.12.tgz",
+      "integrity": "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.12.tgz",
+      "integrity": "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.12.tgz",
+      "integrity": "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.12.tgz",
+      "integrity": "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.12.tgz",
+      "integrity": "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.12.tgz",
+      "integrity": "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.12.tgz",
+      "integrity": "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.12.tgz",
+      "integrity": "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.12.tgz",
+      "integrity": "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.12.tgz",
+      "integrity": "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.12.tgz",
+      "integrity": "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.12.tgz",
+      "integrity": "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.12.tgz",
+      "integrity": "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.12.tgz",
+      "integrity": "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.12.tgz",
+      "integrity": "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.12.tgz",
+      "integrity": "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.12.tgz",
+      "integrity": "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.12.tgz",
+      "integrity": "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@graphql-typed-document-node/core": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/@graphql-typed-document-node/core/-/core-3.2.0.tgz",
+      "integrity": "sha512-mB9oAsNCm9aM3/SOv4YtBMqZbYj10R7dkq8byBqxGY/ncFwhf2oQzMV+LCRlWoDSEBJ3COiR1yeDvMtsoOsuFQ==",
+      "license": "MIT",
+      "peerDependencies": {
+        "graphql": "^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0"
+      }
+    },
+    "node_modules/@jridgewell/gen-mapping": {
+      "version": "0.3.13",
+      "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
+      "integrity": "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.0",
+        "@jridgewell/trace-mapping": "^0.3.24"
+      }
+    },
+    "node_modules/@jridgewell/remapping": {
+      "version": "2.3.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/remapping/-/remapping-2.3.5.tgz",
+      "integrity": "sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/gen-mapping": "^0.3.5",
+        "@jridgewell/trace-mapping": "^0.3.24"
+      }
+    },
+    "node_modules/@jridgewell/resolve-uri": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@jridgewell/trace-mapping": {
+      "version": "0.3.31",
+      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz",
+      "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/resolve-uri": "^3.1.0",
+        "@jridgewell/sourcemap-codec": "^1.4.14"
+      }
+    },
+    "node_modules/@publint/pack": {
+      "version": "0.1.6",
+      "resolved": "https://registry.npmjs.org/@publint/pack/-/pack-0.1.6.tgz",
+      "integrity": "sha512-3uVNyGcVplhPZSLVyeIpL7+cIRn1YCSNHLG/rUIlBQMVH8YuN9++YF+5+UDIIO9RW98dujiUoTltO7RDB5bFJA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyexec": "^1.2.4"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://bjornlu.com/sponsor"
+      }
+    },
+    "node_modules/@sveltejs/acorn-typescript": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/@sveltejs/acorn-typescript/-/acorn-typescript-1.0.11.tgz",
+      "integrity": "sha512-LFuZUkjJ9iF7JZye/aG5XM0SFcQ5VyL0oVX4WJ9dc0Va3R3s0OauX1BESVCb+YN/ol8TAfqGDDAQsTG627Y5kw==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "acorn": "^8.9.0"
+      }
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/node": {
+      "version": "20.19.43",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz",
+      "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/@types/react": {
+      "version": "19.2.17",
+      "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.17.tgz",
+      "integrity": "sha512-MXfmqaVPEVgkBT/aY0aGCkRWWtByiYQXo3xdQ8r5RzuFrPiRn8Gar2tQdXSUQ2GKV3bkXckek89V8wQBY2Q/Aw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "csstype": "^3.2.2"
+      }
+    },
+    "node_modules/@types/trusted-types": {
+      "version": "2.0.7",
+      "resolved": "https://registry.npmjs.org/@types/trusted-types/-/trusted-types-2.0.7.tgz",
+      "integrity": "sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@wry/caches": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@wry/caches/-/caches-1.0.1.tgz",
+      "integrity": "sha512-bXuaUNLVVkD20wcGBWRyo7j9N3TxePEWFZj2Y+r9OoUzfqmavM84+mFykRicNsBqatba5JLay1t48wxaXaWnlA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "^2.3.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/@wry/context": {
+      "version": "0.7.4",
+      "resolved": "https://registry.npmjs.org/@wry/context/-/context-0.7.4.tgz",
+      "integrity": "sha512-jmT7Sb4ZQWI5iyu3lobQxICu2nC/vbUhP0vIdd6tHC9PTfenmRmuIFqktc6GH9cgi+ZHnsLWPvfSvc4DrYmKiQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "^2.3.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/@wry/equality": {
+      "version": "0.5.7",
+      "resolved": "https://registry.npmjs.org/@wry/equality/-/equality-0.5.7.tgz",
+      "integrity": "sha512-BRFORjsTuQv5gxcXsuDXx6oGRhuVsEGwZy6LOzRRfgu+eSfxbhUQ9L9YtSEIuIjY/o7g3iWFjrc5eSY1GXP2Dw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "^2.3.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/@wry/trie": {
+      "version": "0.5.0",
+      "resolved": "https://registry.npmjs.org/@wry/trie/-/trie-0.5.0.tgz",
+      "integrity": "sha512-FNoYzHawTMk/6KMQoEG5O4PuioX19UbwdQKF44yw0nLfOypfQdjtfZzo/UIJWAJ23sNIFbD1Ug9lbaDGMwbqQA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "^2.3.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/acorn": {
+      "version": "8.17.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.17.0.tgz",
+      "integrity": "sha512-xRQbDb9BnwDafYNn6Vwl839DYVjqXYb1XVGtWAZ1kcDc6iwAL4hg3B1dZlRiuENFeO2H53gFG3in621AdERVAg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/aria-query": {
+      "version": "5.3.1",
+      "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.1.tgz",
+      "integrity": "sha512-Z/ZeOgVl7bcSYZ/u/rh0fOpvEpq//LZmdbkXyc7syVzjPAhfOa9ebsdTSjEBDU4vs5nC98Kfduj1uFo0qyET3g==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/axobject-query": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/axobject-query/-/axobject-query-4.1.0.tgz",
+      "integrity": "sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/clsx": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
+      "integrity": "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/csstype": {
+      "version": "3.2.3",
+      "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
+      "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/devalue": {
+      "version": "5.8.2",
+      "resolved": "https://registry.npmjs.org/devalue/-/devalue-5.8.2.tgz",
+      "integrity": "sha512-DObPPAfdtFbXjxLqK8s2Xk9ZuWz5+ZoFEhC7J76es4GU/rEiXwHTmbImoCdyoCOcBH1UF3+Cz6Z2sYD4hyl5TA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/esbuild": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz",
+      "integrity": "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.25.12",
+        "@esbuild/android-arm": "0.25.12",
+        "@esbuild/android-arm64": "0.25.12",
+        "@esbuild/android-x64": "0.25.12",
+        "@esbuild/darwin-arm64": "0.25.12",
+        "@esbuild/darwin-x64": "0.25.12",
+        "@esbuild/freebsd-arm64": "0.25.12",
+        "@esbuild/freebsd-x64": "0.25.12",
+        "@esbuild/linux-arm": "0.25.12",
+        "@esbuild/linux-arm64": "0.25.12",
+        "@esbuild/linux-ia32": "0.25.12",
+        "@esbuild/linux-loong64": "0.25.12",
+        "@esbuild/linux-mips64el": "0.25.12",
+        "@esbuild/linux-ppc64": "0.25.12",
+        "@esbuild/linux-riscv64": "0.25.12",
+        "@esbuild/linux-s390x": "0.25.12",
+        "@esbuild/linux-x64": "0.25.12",
+        "@esbuild/netbsd-arm64": "0.25.12",
+        "@esbuild/netbsd-x64": "0.25.12",
+        "@esbuild/openbsd-arm64": "0.25.12",
+        "@esbuild/openbsd-x64": "0.25.12",
+        "@esbuild/openharmony-arm64": "0.25.12",
+        "@esbuild/sunos-x64": "0.25.12",
+        "@esbuild/win32-arm64": "0.25.12",
+        "@esbuild/win32-ia32": "0.25.12",
+        "@esbuild/win32-x64": "0.25.12"
+      }
+    },
+    "node_modules/esm-env": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/esm-env/-/esm-env-1.2.2.tgz",
+      "integrity": "sha512-Epxrv+Nr/CaL4ZcFGPJIYLWFom+YeV1DqMLHJoEd9SYRxNbaFruBwfEX/kkHUJf55j2+TUbmDcmuilbP1TmXHA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/esrap": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/esrap/-/esrap-2.3.0.tgz",
+      "integrity": "sha512-GQ/7RN8uOtEfNpzZzBMTzW9JBcX42oaSVtPzdF+6cEL8pqIL094iUpr9jzYGn4O4P/1S60dJ6izyT8F4LYARng==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.4.15"
+      },
+      "peerDependencies": {
+        "@typescript-eslint/types": "^8.2.0"
+      },
+      "peerDependenciesMeta": {
+        "@typescript-eslint/types": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/graphql": {
+      "version": "16.14.2",
+      "resolved": "https://registry.npmjs.org/graphql/-/graphql-16.14.2.tgz",
+      "integrity": "sha512-Chq1s4CY7jmh8gO2qvLIJyfCDIN+EHLFW/9iShnp1z8FjBQMoodWP1kDC36VAMXXIvAjj4ARa7ntfAV2BrjsbA==",
+      "license": "MIT",
+      "engines": {
+        "node": "^12.22.0 || ^14.16.0 || ^16.0.0 || >=17.0.0"
+      }
+    },
+    "node_modules/graphql-tag": {
+      "version": "2.12.7",
+      "resolved": "https://registry.npmjs.org/graphql-tag/-/graphql-tag-2.12.7.tgz",
+      "integrity": "sha512-xnE/NFzy+0eIesvAsREJZ284zTl/wYuBAvpsFSDhRGRdRHdnE90M21Q3xAWyYInb0J756c6x0pIQ62+vtvOs1Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "^2.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "graphql": "^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0"
+      }
+    },
+    "node_modules/is-reference": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/is-reference/-/is-reference-3.0.3.tgz",
+      "integrity": "sha512-ixkJoqQvAP88E6wLydLGGqCJsrFUnqoH6HnaczB8XmDH1oaWU+xxdptvikTgaEhtZ53Ky6YXiBuUI2WXLMCwjw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.6"
+      }
+    },
+    "node_modules/locate-character": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/locate-character/-/locate-character-3.0.0.tgz",
+      "integrity": "sha512-SW13ws7BjaeJ6p7Q6CO2nchbYEc3X3J6WrmTTDto7yMPqVSZTUyY5Tjbid+Ab8gLnATtygYtiDIJGQRRn2ZOiA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/magic-string": {
+      "version": "0.30.21",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
+      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.5"
+      }
+    },
+    "node_modules/mri": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/mri/-/mri-1.2.0.tgz",
+      "integrity": "sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/optimism": {
+      "version": "0.18.1",
+      "resolved": "https://registry.npmjs.org/optimism/-/optimism-0.18.1.tgz",
+      "integrity": "sha512-mLXNwWPa9dgFyDqkNi54sjDyNJ9/fTI6WGBLgnXku1vdKY/jovHfZT5r+aiVeFFLOz+foPNOm5YJ4mqgld2GBQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@wry/caches": "^1.0.0",
+        "@wry/context": "^0.7.0",
+        "@wry/trie": "^0.5.0",
+        "tslib": "^2.3.0"
+      }
+    },
+    "node_modules/package-manager-detector": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/package-manager-detector/-/package-manager-detector-1.8.0.tgz",
+      "integrity": "sha512-yQA4H19AmPEoMUeavPMDIe1higySl/gH/yaQrkT/s07Qp+7pp2hYz30N3z2l5BkjVkF9Ow6o0wjJamm2y7Sn0A==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/publint": {
+      "version": "0.3.22",
+      "resolved": "https://registry.npmjs.org/publint/-/publint-0.3.22.tgz",
+      "integrity": "sha512-6Z/scsr5CA7APdwyF35EY88CqgDj1textWuY788DVTJYPCWVv/Wn9G6KmLnrVRnStgYcahqN4wCDLZGSbQJ69w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@publint/pack": "^0.1.6",
+        "package-manager-detector": "^1.7.0",
+        "picocolors": "^1.1.1",
+        "sade": "^1.8.1"
+      },
+      "bin": {
+        "publint": "src/cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://bjornlu.com/sponsor"
+      }
+    },
+    "node_modules/react": {
+      "version": "19.2.8",
+      "resolved": "https://registry.npmjs.org/react/-/react-19.2.8.tgz",
+      "integrity": "sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-dom": {
+      "version": "19.2.8",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.8.tgz",
+      "integrity": "sha512-rVprimfGBG3DR+Tq0IQG2DT5PxKth1WIGDmj5yPmlzr4YBe7uyE+Du4oVqTDXZSHGGGXRtTJEGSSePyQCMBglQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "scheduler": "^0.27.0"
+      },
+      "peerDependencies": {
+        "react": "^19.2.8"
+      }
+    },
+    "node_modules/react-is": {
+      "version": "19.2.8",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-19.2.8.tgz",
+      "integrity": "sha512-s5un28nYxKJw5gvUHyW5PCC28CvBqLu9r3cWgzHT4Vo/5fqqkFcdRYsGcKf50WMPpjjFZS5d76fn3YCo2njKwQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/react-test-renderer": {
+      "version": "19.2.8",
+      "resolved": "https://registry.npmjs.org/react-test-renderer/-/react-test-renderer-19.2.8.tgz",
+      "integrity": "sha512-GHKPaDRaNYU24PHTLG8Bx8VMY9t+qNfxQbt/Yjp7aMWBkKU6766SR0n6TnYu7P5I1MfEuAMUadqiyDHyI4Yy9Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "react-is": "^19.2.8",
+        "scheduler": "^0.27.0"
+      },
+      "peerDependencies": {
+        "react": "^19.2.8"
+      }
+    },
+    "node_modules/rxjs": {
+      "version": "7.8.2",
+      "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.2.tgz",
+      "integrity": "sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "peer": true,
+      "dependencies": {
+        "tslib": "^2.1.0"
+      }
+    },
+    "node_modules/sade": {
+      "version": "1.8.1",
+      "resolved": "https://registry.npmjs.org/sade/-/sade-1.8.1.tgz",
+      "integrity": "sha512-xal3CZX1Xlo/k4ApwCFrHVACi9fBqJ7V+mwhBsuf/1IOKbBy098Fex+Wa/5QMubw09pSZ/u8EY8PWgevJsXp1A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mri": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/scheduler": {
+      "version": "0.27.0",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.27.0.tgz",
+      "integrity": "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/svelte": {
+      "version": "5.56.7",
+      "resolved": "https://registry.npmjs.org/svelte/-/svelte-5.56.7.tgz",
+      "integrity": "sha512-5qERUZX80oQj6XrDMUmD2Uhd/cIpCPDWWKBK3ZHmyRUC9apPyamWM8xMo31mbWsIQxwG2hVoSnOJ/EcnhVkkzQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/remapping": "^2.3.4",
+        "@jridgewell/sourcemap-codec": "^1.5.0",
+        "@sveltejs/acorn-typescript": "^1.0.10",
+        "@types/estree": "^1.0.5",
+        "@types/trusted-types": "^2.0.7",
+        "acorn": "^8.12.1",
+        "aria-query": "5.3.1",
+        "axobject-query": "^4.1.0",
+        "clsx": "^2.1.1",
+        "devalue": "^5.8.1",
+        "esm-env": "^1.2.1",
+        "esrap": "^2.2.12",
+        "is-reference": "^3.0.3",
+        "locate-character": "^3.0.0",
+        "magic-string": "^0.30.11",
+        "zimmerframe": "^1.1.2"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tinyexec": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.2.4.tgz",
+      "integrity": "sha512-SHf/r48b7vOrjve9PxJo3MN5v5yuyjHvdUcrQffT3WXMUfnGmHDVbC4k3sHJaJTgZCwpUplIaAo5ANtMyp3YHg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "dev": true,
+      "license": "0BSD"
+    },
+    "node_modules/typescript": {
+      "version": "5.8.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.8.3.tgz",
+      "integrity": "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/zimmerframe": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/zimmerframe/-/zimmerframe-1.1.4.tgz",
+      "integrity": "sha512-B58NGBEoc8Y9MWWCQGl/gq9xBCe4IiKM0a2x7GZdQKOW5Exr8S1W24J6OgM1njK8xCRGvAJIL/MxXHf6SkmQKQ==",
+      "dev": true,
+      "license": "MIT"
+    }
+  }
+}
diff --git a/js/package.json b/js/package.json
new file mode 100644
index 00000000..f7abd88c
--- /dev/null
+++ b/js/package.json
@@ -0,0 +1,95 @@
+{
+  "name": "@hops-ops/distributed",
+  "version": "0.1.0",
+  "description": "Typed GraphQL client, causal replica, command runtime, and framework adapters for Distributed services",
+  "type": "module",
+  "license": "UNLICENSED",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./replica": {
+      "types": "./dist/replica/index.d.ts",
+      "import": "./dist/replica/index.js"
+    },
+    "./diagnostics": {
+      "types": "./dist/diagnostics.d.ts",
+      "import": "./dist/diagnostics.js"
+    },
+    "./sveltekit": {
+      "types": "./dist/sveltekit/index.d.ts",
+      "import": "./dist/sveltekit/index.js"
+    },
+    "./sveltekit/vite": {
+      "types": "./dist/sveltekit/vite.d.ts",
+      "import": "./dist/sveltekit/vite.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit && npm run check:generated",
+    "check:generated": "tsc -p tsconfig.generated-tests.json --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "measure:cache-engines": "node scripts/measure-cache-engines.mjs",
+    "pack:smoke": "node scripts/pack-smoke.mjs",
+    "publint": "publint",
+    "release:dry-run": "npm publish --dry-run",
+    "quality": "npm run check && npm test && npm run pack:smoke && npm run publint",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@graphql-typed-document-node/core": "^3.2.0",
+    "graphql": "^16.14.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "svelte": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@apollo/client": "^4.2.7",
+    "@types/node": "^20.0.0",
+    "@types/react": "19.2.17",
+    "esbuild": "^0.25.12",
+    "publint": "^0.3.22",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "react-test-renderer": "19.2.8",
+    "svelte": "5.56.7",
+    "typescript": "5.8.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hops-ops/distributed.git",
+    "directory": "js"
+  },
+  "homepage": "https://github.com/hops-ops/distributed/tree/main/js#readme",
+  "bugs": {
+    "url": "https://github.com/hops-ops/distributed/issues"
+  }
+}
diff --git a/js/scripts/measure-cache-engines.mjs b/js/scripts/measure-cache-engines.mjs
new file mode 100644
index 00000000..26677002
--- /dev/null
+++ b/js/scripts/measure-cache-engines.mjs
@@ -0,0 +1,70 @@
+import { gzipSync } from 'node:zlib';
+import { build } from 'esbuild';
+
+const packageRoot = new URL('../', import.meta.url).pathname;
+
+async function bundle(contents, sourcefile) {
+	const result = await build({
+		stdin: {
+			contents,
+			loader: 'ts',
+			resolveDir: packageRoot,
+			sourcefile
+		},
+		bundle: true,
+		format: 'esm',
+		platform: 'browser',
+		target: ['es2022'],
+		minify: true,
+		metafile: true,
+		write: false,
+		logLevel: 'silent'
+	});
+	const output = result.outputFiles[0].contents;
+	return {
+		minifiedBytes: output.byteLength,
+		minifiedGzipBytes: gzipSync(output, { level: 9 }).byteLength,
+		moduleCount: Object.keys(result.metafile.inputs).length
+	};
+}
+
+const baseline = await bundle(`export const marker = 1;`, 'baseline.ts');
+const purposeBuilt = await bundle(
+	`export { createCacheEngine, cacheIndexKey } from './src/internal/cache-engine.ts';`,
+	'purpose-built.ts'
+);
+const apollo = await bundle(
+	`export { InMemoryCache } from '@apollo/client/cache';`,
+	'apollo.ts'
+);
+const unusedPurposeBuilt = await bundle(
+	`import { createCacheEngine } from './src/internal/cache-engine.ts'; export const marker = 1;`,
+	'unused-purpose-built.ts'
+);
+const unusedApollo = await bundle(
+	`import { InMemoryCache } from '@apollo/client/cache'; export const marker = 1;`,
+	'unused-apollo.ts'
+);
+
+const report = {
+	measurement: 'esbuild browser ESM, ES2022, minified; gzip level 9',
+	versions: {
+		esbuild: (await import('esbuild/package.json', { with: { type: 'json' } })).default.version,
+		apolloClient: (await import('@apollo/client/package.json', { with: { type: 'json' } })).default
+			.version
+	},
+	baseline,
+	candidates: {
+		purposeBuilt,
+		apollo
+	},
+	unusedImports: {
+		purposeBuilt: unusedPurposeBuilt,
+		apollo: unusedApollo,
+		matchesBaseline:
+			unusedPurposeBuilt.minifiedBytes === baseline.minifiedBytes &&
+			unusedApollo.minifiedBytes === baseline.minifiedBytes
+	}
+};
+
+process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
diff --git a/js/scripts/pack-smoke.mjs b/js/scripts/pack-smoke.mjs
new file mode 100644
index 00000000..3382f99f
--- /dev/null
+++ b/js/scripts/pack-smoke.mjs
@@ -0,0 +1,918 @@
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import {
+	mkdtemp,
+	mkdir,
+	readFile,
+	rm,
+	stat,
+	writeFile
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+import { build } from 'esbuild';
+
+const execFileAsync = promisify(execFile);
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+const nodeCommand = process.execPath;
+const removedSubpaths = Object.freeze([
+	'@hops-ops/distributed/cache',
+	'@hops-ops/distributed/commands',
+	'@hops-ops/distributed/codegen',
+	'@hops-ops/distributed/internal/cache-engine'
+]);
+
+async function run(command, args, cwd) {
+	try {
+		return await execFileAsync(command, args, {
+			cwd,
+			env: process.env,
+			maxBuffer: 10 * 1024 * 1024
+		});
+	} catch (error) {
+		const stdout =
+			typeof error.stdout === 'string' ? error.stdout.trim() : '';
+		const stderr =
+			typeof error.stderr === 'string' ? error.stderr.trim() : '';
+		const output = [stdout, stderr].filter(Boolean).join('\n');
+		throw new Error(
+			`Command failed: ${command} ${args.join(' ')}${
+				output.length === 0 ? '' : `\n${output}`
+			}`,
+			{ cause: error }
+		);
+	}
+}
+
+function collectPackageTargets(value, targets) {
+	if (typeof value === 'string') {
+		if (value.startsWith('./')) targets.add(value.slice(2));
+		else if (!value.startsWith('.') && !isAbsolute(value)) targets.add(value);
+		return;
+	}
+	if (Array.isArray(value)) {
+		for (const entry of value) collectPackageTargets(entry, targets);
+		return;
+	}
+	if (value !== null && typeof value === 'object') {
+		for (const entry of Object.values(value)) {
+			collectPackageTargets(entry, targets);
+		}
+	}
+}
+
+function parsePackResult(stdout) {
+	try {
+		return JSON.parse(stdout.trim());
+	} catch (error) {
+		throw new Error(`npm pack did not return valid JSON:\n${stdout.trim()}`, {
+			cause: error
+		});
+	}
+}
+
+function inspectPackageContract(packageJson) {
+	assert.deepEqual(Object.keys(packageJson.exports).sort(), [
+		'.',
+		'./diagnostics',
+		'./package.json',
+		'./react',
+		'./replica',
+		'./sveltekit',
+		'./sveltekit/vite'
+	]);
+	assert.equal(
+		packageJson.bin,
+		undefined,
+		'the npm package must not expose a package-owned generator'
+	);
+	for (const subpath of ['./cache', './commands', './codegen']) {
+		assert.equal(
+			Object.hasOwn(packageJson.exports, subpath),
+			false,
+			`${subpath} must not remain public`
+		);
+	}
+	assert.equal(
+		packageJson.peerDependenciesMeta?.react?.optional,
+		true,
+		'React must remain an optional peer'
+	);
+	assert.equal(
+		packageJson.peerDependenciesMeta?.svelte?.optional,
+		true,
+		'Svelte must remain an optional peer'
+	);
+}
+
+function inspectPackResult(packResult, packageJson) {
+	assert.equal(packResult.length, 1, 'npm pack must produce exactly one tarball');
+	const [packed] = packResult;
+	assert.equal(packed.name, packageJson.name);
+	assert.equal(packed.version, packageJson.version);
+	assert.ok(Array.isArray(packed.files), 'npm pack must report its file manifest');
+
+	const packedPaths = new Set(packed.files.map((file) => file.path));
+	const requiredPaths = new Set(['README.md', 'package.json']);
+	collectPackageTargets(packageJson.exports, requiredPaths);
+	for (const requiredPath of requiredPaths) {
+		assert.ok(packedPaths.has(requiredPath), `tarball is missing ${requiredPath}`);
+	}
+	assert.ok(
+		[...packedPaths].some((path) => path.startsWith('dist/')),
+		'tarball must contain built declarations and JavaScript'
+	);
+
+	const forbiddenSegments = new Set([
+		'src',
+		'tests',
+		'type-tests',
+		'scripts',
+		'node_modules'
+	]);
+	const forbiddenPaths = [...packedPaths].filter((path) =>
+		path.split('/').some((segment) => forbiddenSegments.has(segment))
+	);
+	assert.deepEqual(
+		forbiddenPaths,
+		[],
+		`tarball contains private paths: ${forbiddenPaths.join(', ')}`
+	);
+	return { packed, packedPaths };
+}
+
+const consumerTypeSource = `
+import {
+  DISTRIBUTED_PROTOCOL_VERSION,
+  documentToString,
+  parseDistributedProtocolEnvelope,
+  requestGraphql,
+  type GqlAuth,
+  type GqlDocument
+} from '@hops-ops/distributed';
+import {
+  createDistributedReplica,
+  createReplicaGraphqlTransport,
+  createReplicaIndexedDbPersistence,
+  type ReplicaOperationArtifact,
+  type ReplicaSnapshot,
+  type ReplicaSparse
+} from '@hops-ops/distributed/replica';
+import {
+  createReplicaDiagnostics,
+  type ReplicaDiagnosticsSnapshot
+} from '@hops-ops/distributed/diagnostics';
+// @ts-expect-error The removed document-cache type must stay absent.
+import type { QueryCache } from '@hops-ops/distributed';
+// @ts-expect-error The removed handwritten cache target must stay absent.
+import type { CacheTarget } from '@hops-ops/distributed';
+// @ts-expect-error The removed manual list reconciliation policy must stay absent.
+import type { ListMergeSpec } from '@hops-ops/distributed';
+// @ts-expect-error The removed pilot client factory must stay absent.
+import { createGraphqlClient } from '@hops-ops/distributed';
+// @ts-expect-error The removed resource wrapper must stay absent.
+import { defineResource } from '@hops-ops/distributed';
+// @ts-expect-error The removed pilot client type must stay absent.
+import type { GraphqlClient } from '@hops-ops/distributed';
+// @ts-expect-error The removed resource abstraction must stay absent.
+import type { GraphqlResource } from '@hops-ops/distributed';
+// @ts-expect-error The removed document-store abstraction must stay absent.
+import type { DocumentStore } from '@hops-ops/distributed';
+// @ts-expect-error The removed raw command definition must stay absent.
+import type { CommandDefinition } from '@hops-ops/distributed';
+// @ts-expect-error The removed manual command policy must stay absent.
+import type { CommandPolicy } from '@hops-ops/distributed';
+
+type TodosData = { todos: readonly { id: string; title: string }[] };
+type TodosVariables = Readonly<{ limit: number }>;
+
+const operation: ReplicaOperationArtifact<TodosData, TodosVariables> = {
+  id: 'query:todos',
+  document: 'query Todos($limit: Int!) { todos(limit: $limit) { id title } }',
+  protocol: {
+    version: 1,
+    schemaHash: \`sha256:\${'a'.repeat(64)}\`,
+    surface: { kind: 'role', name: 'user' },
+    operation: 'query:todos',
+    trustedPresets: []
+  },
+  variableCodec: {
+    version: 1,
+    limits: { maxDepth: 8, maxBoolWidth: 32, maxInList: 64 },
+    variables: {
+      limit: {
+        kind: 'scalar',
+        scalar: 'Int',
+        codec: 'int32',
+        nullable: false
+      }
+    },
+    inputs: {}
+  },
+  roots: [{
+    responseKey: 'todos',
+    field: 'todos',
+    cardinality: 'many',
+    nullable: false,
+    arguments: { limit: { kind: 'variable', name: 'limit' } },
+    dependencies: ['todos'],
+    selection: {
+      typename: 'todo',
+      storage: {
+        kind: 'normalized',
+        model: 'Todo',
+        identityFields: ['id']
+      },
+      members: [
+        {
+          kind: 'scalar',
+          responseKey: 'id',
+          field: 'id',
+          codec: 'ID',
+          nullable: false
+        },
+        {
+          kind: 'scalar',
+          responseKey: 'title',
+          field: 'title',
+          codec: 'String',
+          nullable: false
+        }
+      ]
+    }
+  }]
+};
+
+const auth: GqlAuth = { accessToken: 'token' };
+const document: GqlDocument<TodosData, TodosVariables> = operation.document;
+const diagnostics = createReplicaDiagnostics();
+const diagnosticSnapshot: ReplicaDiagnosticsSnapshot = diagnostics.getSnapshot();
+const transport = createReplicaGraphqlTransport({
+  getUrl: () => '/graphql',
+  getAuth: () => auth
+});
+const replica = createDistributedReplica({ transport, diagnostics });
+const snapshot: ReplicaSnapshot<TodosData> = replica.read(operation, { limit: 10 });
+const sparse: ReplicaSparse<TodosData> = {};
+if (snapshot.complete) snapshot.data.todos.map((todo) => todo.title);
+
+void [
+  DISTRIBUTED_PROTOCOL_VERSION,
+  documentToString(document),
+  parseDistributedProtocolEnvelope,
+  requestGraphql,
+  createReplicaIndexedDbPersistence,
+  diagnosticSnapshot,
+  sparse
+];
+`;
+
+const consumerRuntimeSource = `
+import assert from 'node:assert/strict';
+import * as rootSurface from '@hops-ops/distributed';
+import * as replicaSurface from '@hops-ops/distributed/replica';
+import * as diagnosticsSurface from '@hops-ops/distributed/diagnostics';
+import {
+  requestGraphql
+} from '@hops-ops/distributed';
+import {
+  createDistributedReplica
+} from '@hops-ops/distributed/replica';
+import {
+  createReplicaDiagnostics
+} from '@hops-ops/distributed/diagnostics';
+
+const schemaHash = \`sha256:\${'a'.repeat(64)}\`;
+const operation = Object.freeze({
+  id: 'query:todos',
+  document: 'query Todos { todos { id title } }',
+  protocol: Object.freeze({
+    version: 1,
+    schemaHash,
+    surface: Object.freeze({ kind: 'role', name: 'user' }),
+    operation: 'query:todos',
+    trustedPresets: Object.freeze([])
+  }),
+  variableCodec: Object.freeze({
+    version: 1,
+    limits: Object.freeze({
+      maxDepth: 8,
+      maxBoolWidth: 32,
+      maxInList: 64
+    }),
+    variables: Object.freeze({}),
+    inputs: Object.freeze({})
+  }),
+  roots: Object.freeze([Object.freeze({
+    responseKey: 'todos',
+    field: 'todos',
+    cardinality: 'many',
+    nullable: false,
+    dependencies: Object.freeze(['todos']),
+    selection: Object.freeze({
+      typename: 'todo',
+      storage: Object.freeze({
+        kind: 'normalized',
+        model: 'Todo',
+        identityFields: Object.freeze(['id'])
+      }),
+      members: Object.freeze([
+        Object.freeze({
+          kind: 'scalar',
+          responseKey: 'id',
+          field: 'id',
+          codec: 'ID',
+          nullable: false
+        }),
+        Object.freeze({
+          kind: 'scalar',
+          responseKey: 'title',
+          field: 'title',
+          codec: 'String',
+          nullable: false
+        })
+      ])
+    })
+  })])
+});
+
+const diagnostics = createReplicaDiagnostics();
+const replica = createDistributedReplica({ diagnostics });
+replica.writeResult(operation, {}, {
+  data: { todos: [{ id: 'todo-1', title: 'packed' }] },
+  extensions: {
+    distributed: {
+      protocolVersion: 1,
+      schemaHash,
+      cacheScope: 'scope:user',
+      operation: operation.id,
+      trustedPresets: [],
+      snapshot: {
+        scopeToken: 'snapshot:todos',
+        recordsComplete: true,
+        indexesComparable: true,
+        records: [{
+          path: ['todos', '0'],
+          model: 'Todo',
+          scopeToken: 'record:todo-1',
+          incarnation: '1',
+          revision: '1',
+          tombstone: false
+        }],
+        indexes: [{
+          projection: 'todos',
+          scopeToken: 'index:todos',
+          position: '1'
+        }],
+        observations: []
+      }
+    }
+  }
+}, 'network');
+assert.deepEqual(replica.read(operation, {}).data, {
+  todos: [{ id: 'todo-1', title: 'packed' }]
+});
+assert.equal(diagnostics.getSnapshot().records.length, 1);
+
+const result = await requestGraphql(
+  'https://example.test/graphql',
+  'query Health { health }',
+  {},
+  {},
+  {
+    fetch: async (_input, init) => {
+      const body = JSON.parse(String(init.body));
+      assert.equal(body.query, 'query Health { health }');
+      return new Response(JSON.stringify({ data: { health: 'ok' } }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' }
+      });
+    }
+  }
+);
+assert.equal(result.data.health, 'ok');
+
+assert.deepEqual(Object.keys(rootSurface).sort(), [
+  'DISTRIBUTED_PROTOCOL_VERSION',
+  'DistributedProtocolError',
+  'applyWsDevHeaderParams',
+  'authIdentityKey',
+  'buildAuthHeaders',
+  'compareDistributedDecimal',
+  'distributedLiveResumeExtensions',
+  'documentToString',
+  'graphqlWsUrl',
+  'httpUrlToWsUrl',
+  'jwtPayloadSub',
+  'parseDistributedProtocolEnvelope',
+  'parseGraphqlResponseExtensions',
+  'requestGraphql',
+  'subscribe',
+  'wsConnectionInitPayload'
+]);
+assert.deepEqual(Object.keys(replicaSurface).sort(), [
+  'REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED',
+  'ReplicaCommandContractError',
+  'ReplicaCommandRuntimeError',
+  'canonicalizeOperationVariables',
+  'compareReplicaOrder',
+  'createDistributedReplica',
+  'createReplicaCommandRuntime',
+  'createReplicaDevelopmentCapability',
+  'createReplicaDiagnostics',
+  'createReplicaGraphqlTransport',
+  'createReplicaIndexMaintenanceRegistry',
+  'createReplicaIndexedDbPersistence',
+  'decideReplicaPaginationMaintenance',
+  'evaluateReplicaFilter',
+  'formatReplicaIndexStaleReason',
+  'inspectReplicaCommandArtifact',
+  'inspectReplicaOperationArtifact',
+  'prepareReplicaCommand',
+  'replicaIndexKey',
+  'replicaRecordKey',
+  'verifyReplicaCommandReceipt'
+]);
+assert.deepEqual(Object.keys(diagnosticsSurface).sort(), [
+  'createReplicaDevelopmentCapability',
+  'createReplicaDiagnostics',
+  'inspectReplicaCommandArtifact',
+  'inspectReplicaOperationArtifact'
+]);
+for (const subpath of ${JSON.stringify(removedSubpaths)}) {
+  await assert.rejects(
+    import(subpath),
+    (error) => error?.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED',
+    \`\${subpath} must remain private\`
+  );
+}
+`;
+
+const svelteTypeSource = `
+import {
+  createDistributedSvelteKit,
+  createDistributedSvelteKitServer,
+  createPageDataSessionSource,
+  defineDistributedSvelteKitOperation,
+  provideDistributedSvelteKitClient,
+  useDistributedSvelteKitClient,
+  useDistributedSvelteKitCommands
+} from '@hops-ops/distributed/sveltekit';
+import {
+  checkDistributedSvelteKit,
+  distributedGraphqlProxy,
+  distributedSvelteKit,
+  distributedSvelteKitAliases,
+  generateDistributedSvelteKit
+} from '@hops-ops/distributed/sveltekit/vite';
+import type {
+  ReplicaOperationArtifact
+} from '@hops-ops/distributed/replica';
+// @ts-expect-error The removed Svelte pilot query helper must stay absent.
+import { createUseGraphql } from '@hops-ops/distributed/sveltekit';
+// @ts-expect-error The removed Svelte pilot load helper must stay absent.
+import { createLoadQuery } from '@hops-ops/distributed/sveltekit';
+// @ts-expect-error Node-only proxy helpers must not leak from the browser entry.
+import { distributedGraphqlProxy as leakedProxy } from '@hops-ops/distributed/sveltekit';
+
+type TodosData = { todos: readonly { id: string; title: string }[] };
+type TodosVariables = Readonly<{ limit: number }>;
+type Commands = {
+  readonly todo: {
+    readonly create: (input: { readonly title: string }) => Promise<unknown>
+  }
+};
+declare const operation: ReplicaOperationArtifact<TodosData, TodosVariables>;
+
+const pageData = createPageDataSessionSource({
+  session: null,
+  accessToken: null,
+  engineRole: null
+});
+const client = createDistributedSvelteKit<Commands>({
+  browser: false,
+  session: pageData.session
+});
+const Todos = defineDistributedSvelteKitOperation(operation);
+Todos.read({ limit: 10 });
+provideDistributedSvelteKitClient(client);
+useDistributedSvelteKitClient<Commands>().operation(operation);
+useDistributedSvelteKitCommands<Commands>().todo.create({ title: 'typed' });
+
+createDistributedSvelteKitServer({
+  routes: [],
+  getSession: async () => null,
+  getRole: () => 'user'
+});
+
+const compiler = {
+  clients: [{
+    module: '$distributed',
+    manifest: 'target/distributed-client.json',
+    role: 'user',
+    documents: ['src/**/*.graphql'],
+    out: 'src/lib/generated/distributed'
+  }]
+} as const;
+const plugin = distributedSvelteKit(compiler);
+const aliases = distributedSvelteKitAliases(compiler);
+const proxy = distributedGraphqlProxy('http://127.0.0.1:8791');
+
+void [
+  checkDistributedSvelteKit,
+  generateDistributedSvelteKit,
+  plugin,
+  aliases,
+  proxy,
+  leakedProxy
+];
+client.destroy();
+`;
+
+const svelteRuntimeSource = `
+import assert from 'node:assert/strict';
+import * as sveltekitSurface from '@hops-ops/distributed/sveltekit';
+import * as sveltekitViteSurface from '@hops-ops/distributed/sveltekit/vite';
+import {
+  createDistributedSvelteKit,
+  createPageDataSessionSource
+} from '@hops-ops/distributed/sveltekit';
+import {
+  distributedGraphqlProxy
+} from '@hops-ops/distributed/sveltekit/vite';
+
+assert.deepEqual(Object.keys(sveltekitSurface).sort(), [
+  'authFromPageData',
+  'bindSveltekitOperation',
+  'createDistributedSvelteKit',
+  'createDistributedSvelteKitServer',
+  'createPageDataSessionSource',
+  'defineDistributedSvelteKitOperation',
+  'provideDistributedSvelteKitClient',
+  'registerDistributedRoute',
+  'sessionSourceFromPageData',
+  'useDistributedSvelteKitClient',
+  'useDistributedSvelteKitCommands'
+]);
+assert.deepEqual(Object.keys(sveltekitViteSurface).sort(), [
+  'checkDistributedSvelteKit',
+  'distributedGraphqlProxy',
+  'distributedSvelteKit',
+  'distributedSvelteKitAliases',
+  'generateDistributedSvelteKit'
+]);
+assert.equal(typeof sveltekitViteSurface.generateDistributedSvelteKit, 'function');
+assert.equal(typeof sveltekitViteSurface.checkDistributedSvelteKit, 'function');
+
+const pageData = createPageDataSessionSource({
+  session: null,
+  accessToken: null,
+  engineRole: null
+});
+assert.deepEqual(pageData.get(), {
+  session: null,
+  accessToken: null,
+  engineRole: null
+});
+pageData.set({
+  session: { user: { sub: 'user-1' } },
+  accessToken: 'token',
+  engineRole: 'user'
+});
+assert.equal(pageData.session.getAuth().accessToken, 'token');
+
+const client = createDistributedSvelteKit({
+  browser: false,
+  session: pageData.session
+});
+assert.equal(typeof client.operation, 'function');
+client.destroy();
+
+assert.deepEqual(distributedGraphqlProxy('http://127.0.0.1:8791'), {
+  '/graphql': {
+    target: 'http://127.0.0.1:8791',
+    changeOrigin: true,
+    ws: true
+  }
+});
+`;
+
+const reactTypeSource = `
+import { createElement } from 'react';
+import {
+  DistributedProvider,
+  useDistributedQuery
+} from '@hops-ops/distributed/react';
+import type {
+  DistributedReplica,
+  ReplicaOperationArtifact
+} from '@hops-ops/distributed/replica';
+
+type TodosData = { todos: readonly { id: string; title: string }[] };
+declare const replica: DistributedReplica;
+declare const Todos: ReplicaOperationArtifact<
+  TodosData,
+  Readonly<Record<never, never>>
+>;
+
+function App() {
+  const todos = useDistributedQuery(Todos);
+  if (todos.complete) todos.data.todos.map((todo) => todo.title);
+  void todos.refresh;
+  return null;
+}
+
+createElement(DistributedProvider, { replica }, createElement(App));
+`;
+
+const reactRuntimeSource = `
+import assert from 'node:assert/strict';
+import * as reactSurface from '@hops-ops/distributed/react';
+import {
+  DistributedProvider,
+  useDistributedQuery,
+  useDistributedReplica
+} from '@hops-ops/distributed/react';
+
+assert.equal(typeof DistributedProvider, 'function');
+assert.equal(typeof useDistributedQuery, 'function');
+assert.equal(typeof useDistributedReplica, 'function');
+assert.deepEqual(Object.keys(reactSurface).sort(), [
+  'DistributedProvider',
+  'useDistributedQuery',
+  'useDistributedReplica'
+]);
+`;
+
+const tsconfig = (types) =>
+	`${JSON.stringify(
+		{
+			compilerOptions: {
+				target: 'ES2022',
+				module: 'NodeNext',
+				moduleResolution: 'NodeNext',
+				lib: ['ES2022', 'DOM'],
+				types,
+				strict: true,
+				noEmit: true,
+				verbatimModuleSyntax: true
+			},
+			include: ['consumer.ts']
+		},
+		null,
+		2
+	)}\n`;
+
+async function installConsumer(
+	directory,
+	name,
+	tarballPath,
+	typescriptVersion,
+	extraPackages = []
+) {
+	await writeFile(
+		join(directory, 'package.json'),
+		`${JSON.stringify(
+			{
+				name,
+				private: true,
+				type: 'module'
+			},
+			null,
+			2
+		)}\n`
+	);
+	await run(
+		npmCommand,
+		[
+			'install',
+			'--ignore-scripts',
+			'--no-audit',
+			'--no-fund',
+			'--save-exact',
+			tarballPath,
+			`typescript@${typescriptVersion}`,
+			...extraPackages
+		],
+		directory
+	);
+}
+
+async function typecheck(directory, types) {
+	await writeFile(join(directory, 'tsconfig.json'), tsconfig(types));
+	const tscPath = join(
+		directory,
+		'node_modules',
+		'typescript',
+		'bin',
+		'tsc'
+	);
+	await run(nodeCommand, [tscPath, '--project', 'tsconfig.json'], directory);
+}
+
+async function bundleInputs(directory, contents) {
+	const result = await build({
+		absWorkingDir: directory,
+		stdin: {
+			contents,
+			resolveDir: directory,
+			sourcefile: 'bundle-smoke.js'
+		},
+		bundle: true,
+		format: 'esm',
+		platform: 'browser',
+		target: 'es2022',
+		treeShaking: true,
+		write: false,
+		metafile: true,
+		logLevel: 'silent'
+	});
+	return Object.keys(result.metafile.inputs).map((path) =>
+		path.replaceAll('\\', '/')
+	);
+}
+
+async function smokePack() {
+	const packageJson = JSON.parse(
+		await readFile(join(packageRoot, 'package.json'), 'utf8')
+	);
+	inspectPackageContract(packageJson);
+	const typescriptVersion = packageJson.devDependencies?.typescript;
+	assert.ok(typescriptVersion, 'TypeScript must be a declared dev dependency');
+
+	const temporaryRoot = await mkdtemp(join(tmpdir(), 'distributed-pack-smoke-'));
+	try {
+		const packDirectory = join(temporaryRoot, 'pack');
+		const consumerDirectory = join(temporaryRoot, 'consumer');
+		const svelteConsumerDirectory = join(temporaryRoot, 'svelte-consumer');
+		const reactConsumerDirectory = join(temporaryRoot, 'react-consumer');
+		await Promise.all([
+			mkdir(packDirectory),
+			mkdir(consumerDirectory),
+			mkdir(svelteConsumerDirectory),
+			mkdir(reactConsumerDirectory)
+		]);
+
+		const { stdout } = await run(
+			npmCommand,
+			['pack', '--json', '--silent', '--pack-destination', packDirectory],
+			packageRoot
+		);
+		const { packed, packedPaths } = inspectPackResult(
+			parsePackResult(stdout),
+			packageJson
+		);
+		const tarballPath = isAbsolute(packed.filename)
+			? packed.filename
+			: resolve(packDirectory, packed.filename);
+		assert.ok(
+			tarballPath.startsWith(`${resolve(packDirectory)}${sep}`),
+			'npm pack returned a path outside the temporary pack directory'
+		);
+		assert.ok((await stat(tarballPath)).size > 0, 'tarball must not be empty');
+
+		await installConsumer(
+			consumerDirectory,
+			'distributed-pack-smoke-consumer',
+			tarballPath,
+			typescriptVersion
+		);
+		await writeFile(
+			join(consumerDirectory, 'consumer.ts'),
+			consumerTypeSource
+		);
+		await writeFile(
+			join(consumerDirectory, 'runtime.mjs'),
+			consumerRuntimeSource
+		);
+		await typecheck(consumerDirectory, []);
+		await run(nodeCommand, ['runtime.mjs'], consumerDirectory);
+		for (const peer of ['react', 'svelte']) {
+			await assert.rejects(
+				stat(join(consumerDirectory, 'node_modules', peer)),
+				(error) => error?.code === 'ENOENT',
+				`${peer} must remain optional for root/replica consumers`
+			);
+		}
+
+		const baseInputs = await bundleInputs(
+			consumerDirectory,
+			`
+				import '@hops-ops/distributed';
+				import '@hops-ops/distributed/replica';
+				import '@hops-ops/distributed/diagnostics';
+			`
+		);
+		assert.equal(
+			baseInputs.some((path) => /node_modules\/react(?:\/|$)/.test(path)),
+			false,
+			'framework-neutral entry points must not pull React into browser bundles'
+		);
+		assert.equal(
+			baseInputs.some((path) => /node_modules\/svelte(?:\/|$)/.test(path)),
+			false,
+			'framework-neutral entry points must not pull Svelte into browser bundles'
+		);
+		assert.equal(
+			baseInputs.some((path) => path.includes('/dist/sveltekit/')),
+			false,
+			'framework-neutral entry points must not pull the SvelteKit adapter'
+		);
+
+		await installConsumer(
+			svelteConsumerDirectory,
+			'distributed-svelte-pack-smoke-consumer',
+			tarballPath,
+			typescriptVersion,
+			[`svelte@${packageJson.devDependencies.svelte}`]
+		);
+		await writeFile(
+			join(svelteConsumerDirectory, 'consumer.ts'),
+			svelteTypeSource
+		);
+		await writeFile(
+			join(svelteConsumerDirectory, 'runtime.mjs'),
+			svelteRuntimeSource
+		);
+		await typecheck(svelteConsumerDirectory, []);
+		await run(nodeCommand, ['runtime.mjs'], svelteConsumerDirectory);
+		await assert.rejects(
+			stat(join(svelteConsumerDirectory, 'node_modules', 'react')),
+			(error) => error?.code === 'ENOENT',
+			'the SvelteKit entry point must not install React'
+		);
+
+		const svelteInputs = await bundleInputs(
+			svelteConsumerDirectory,
+			`import '@hops-ops/distributed/sveltekit';`
+		);
+		assert.equal(
+			svelteInputs.some((path) => /node_modules\/svelte(?:\/|$)/.test(path)),
+			true,
+			'the SvelteKit entry point must bind the installed Svelte peer'
+		);
+		assert.equal(
+			svelteInputs.some((path) => /node_modules\/react(?:\/|$)/.test(path)),
+			false,
+			'the SvelteKit entry point must not pull React'
+		);
+		assert.equal(
+			svelteInputs.some((path) => path.endsWith('/dist/sveltekit/vite.js')),
+			false,
+			'the browser SvelteKit entry point must not pull the Node-only Vite integration'
+		);
+
+		await installConsumer(
+			reactConsumerDirectory,
+			'distributed-react-pack-smoke-consumer',
+			tarballPath,
+			typescriptVersion,
+			[
+				`react@${packageJson.devDependencies.react}`,
+				`@types/react@${packageJson.devDependencies['@types/react']}`
+			]
+		);
+		await writeFile(
+			join(reactConsumerDirectory, 'consumer.ts'),
+			reactTypeSource
+		);
+		await writeFile(
+			join(reactConsumerDirectory, 'runtime.mjs'),
+			reactRuntimeSource
+		);
+		await typecheck(reactConsumerDirectory, ['react']);
+		await run(nodeCommand, ['runtime.mjs'], reactConsumerDirectory);
+		await assert.rejects(
+			stat(join(reactConsumerDirectory, 'node_modules', 'svelte')),
+			(error) => error?.code === 'ENOENT',
+			'the React entry point must not install Svelte'
+		);
+
+		const reactInputs = await bundleInputs(
+			reactConsumerDirectory,
+			`import '@hops-ops/distributed/react';`
+		);
+		assert.equal(
+			reactInputs.some((path) => /node_modules\/react(?:\/|$)/.test(path)),
+			true,
+			'the React entry point must bind the installed peer'
+		);
+		assert.equal(
+			reactInputs.some((path) => path.includes('/dist/sveltekit/')),
+			false,
+			'the React entry point must not pull the SvelteKit adapter'
+		);
+
+		console.log(
+			`Pack smoke passed for ${packageJson.name}@${packageJson.version} (${packedPaths.size} files).`
+		);
+	} finally {
+		await rm(temporaryRoot, { recursive: true, force: true });
+	}
+}
+
+await smokePack();
diff --git a/js/src/auth-headers.ts b/js/src/auth-headers.ts
new file mode 100644
index 00000000..6bf9adc3
--- /dev/null
+++ b/js/src/auth-headers.ts
@@ -0,0 +1,42 @@
+/** Bearer and DevHeaders mapping shared by HTTP and WebSocket transports. */
+import type { GqlAuth } from './types.js';
+
+/** HTTP headers for a JSON GraphQL request. */
+export function buildAuthHeaders(auth: GqlAuth = {}): Record<string, string> {
+	const headers: Record<string, string> = { 'content-type': 'application/json' };
+	const token = auth.accessToken?.trim() ?? '';
+
+	if (token) {
+		headers.authorization = `Bearer ${token}`;
+	} else if (auth.userId) {
+		headers['x-user-id'] = auth.userId;
+		headers['x-role'] = auth.role ?? 'user';
+	}
+
+	return headers;
+}
+
+/** `graphql-transport-ws` connection-init payload. */
+export function wsConnectionInitPayload(auth: GqlAuth = {}): Record<string, string> {
+	const payload: Record<string, string> = {};
+	const token = auth.accessToken?.trim() ?? '';
+
+	if (token) {
+		payload.authorization = `Bearer ${token}`;
+		payload.accessToken = token;
+	} else if (auth.userId) {
+		payload['x-user-id'] = auth.userId;
+		payload['x-role'] = auth.role ?? 'user';
+	}
+
+	return payload;
+}
+
+/** Add DevHeaders to a WebSocket URL when bearer authentication is absent. */
+export function applyWsDevHeaderParams(url: URL, auth: GqlAuth = {}): void {
+	const token = auth.accessToken?.trim() ?? '';
+	if (token || !auth.userId) return;
+
+	url.searchParams.set('x-user-id', auth.userId);
+	url.searchParams.set('x-role', auth.role ?? 'user');
+}
diff --git a/js/src/diagnostics.ts b/js/src/diagnostics.ts
new file mode 100644
index 00000000..a1332ae8
--- /dev/null
+++ b/js/src/diagnostics.ts
@@ -0,0 +1,36 @@
+export {
+	createReplicaDevelopmentCapability,
+	createReplicaDiagnostics,
+	inspectReplicaCommandArtifact,
+	inspectReplicaOperationArtifact
+} from './replica/diagnostics.js';
+export type {
+	ReplicaArtifactSourceLocation,
+	ReplicaCommandArtifactInspection,
+	ReplicaCommandEffectInspection,
+	ReplicaDevelopmentCapability,
+	ReplicaDiagnosticEvent,
+	ReplicaDiagnosticEventInput,
+	ReplicaDiagnosticFieldValueContext,
+	ReplicaDiagnosticFieldValuePolicy,
+	ReplicaDiagnosticIndex,
+	ReplicaDiagnosticIndexInput,
+	ReplicaDiagnosticLayer,
+	ReplicaDiagnosticLayerInput,
+	ReplicaDiagnosticReceipt,
+	ReplicaDiagnosticReceiptExpectationInput,
+	ReplicaDiagnosticReceiptInput,
+	ReplicaDiagnosticRecord,
+	ReplicaDiagnosticRecordInput,
+	ReplicaDiagnosticReasonContext,
+	ReplicaDiagnosticReasonPolicy,
+	ReplicaDiagnostics,
+	ReplicaDiagnosticsOptions,
+	ReplicaDiagnosticsSink,
+	ReplicaDiagnosticsSnapshot,
+	ReplicaDiagnosticScopeInput,
+	ReplicaDiagnosticStateInput,
+	ReplicaOperationArtifactInspection,
+	ReplicaOperationIndexInspection,
+	ReplicaOperationInjectedFieldInspection
+} from './replica/diagnostics.js';
diff --git a/js/src/document.ts b/js/src/document.ts
new file mode 100644
index 00000000..f3552e53
--- /dev/null
+++ b/js/src/document.ts
@@ -0,0 +1,16 @@
+/** Normalize GraphQL documents for HTTP and WebSocket wire formats. */
+import { print, type DocumentNode } from 'graphql';
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+
+import type { GraphqlVariables } from './types.js';
+
+/** A source string, GraphQL AST, or code-generated typed document. */
+export type GqlDocument<
+	TData = unknown,
+	TVariables extends GraphqlVariables = GraphqlVariables
+> = string | DocumentNode | TypedDocumentNode<TData, TVariables>;
+
+/** Convert a string or AST document to the GraphQL source sent on the wire. */
+export function documentToString(document: GqlDocument): string {
+	return typeof document === 'string' ? document : print(document);
+}
diff --git a/js/src/identity.ts b/js/src/identity.ts
new file mode 100644
index 00000000..efbaac8a
--- /dev/null
+++ b/js/src/identity.ts
@@ -0,0 +1,84 @@
+/** Authentication identity helpers for display and exact credential fencing. */
+import type { GqlAuth } from './types.js';
+
+/**
+ * Produce a stable UX identity without embedding a bearer token in labels.
+ *
+ * This value is not authoritative and must never decide cache reuse. JWTs use
+ * the unverified `sub` claim only so UI state can retain a friendly identity
+ * label across refreshes.
+ * Opaque bearer tokens use a non-cryptographic hash of the complete token.
+ * DevHeaders use the user and role pair.
+ */
+export function authIdentityKey(auth: GqlAuth): string {
+	const token = auth.accessToken?.trim() ?? '';
+	if (token) {
+		const subject = jwtPayloadSub(token);
+		return subject ? `sub:${subject}` : `bearer:${hashString(token)}`;
+	}
+
+	return `dev:${auth.userId ?? ''}:${auth.role ?? ''}`;
+}
+
+/**
+ * Exact local credential comparison used only to invalidate in-flight client work.
+ *
+ * It can close a generation, but cannot authorize reuse: only a server-issued
+ * Distributed cache scope does that for the replica.
+ */
+export function sameAuthCredential(left: GqlAuth, right: GqlAuth): boolean {
+	const leftToken = left.accessToken?.trim() ?? '';
+	const rightToken = right.accessToken?.trim() ?? '';
+	if (leftToken || rightToken) {
+		return leftToken.length > 0 && leftToken === rightToken;
+	}
+	return (
+		(left.userId ?? '') === (right.userId ?? '') &&
+		(left.role ?? '') === (right.role ?? '')
+	);
+}
+
+/** Detach caller-owned auth objects before transport and generation fencing. */
+export function snapshotAuthCredential(auth: GqlAuth): Readonly<GqlAuth> {
+	return Object.freeze({
+		...(auth.accessToken === undefined
+			? {}
+			: { accessToken: auth.accessToken }),
+		...(auth.userId === undefined ? {} : { userId: auth.userId }),
+		...(auth.role === undefined ? {} : { role: auth.role })
+	});
+}
+
+/** Decode an unverified JWT payload's `sub` claim for UI cache identity only. */
+export function jwtPayloadSub(token: string): string | null {
+	const parts = token.split('.');
+	if (parts.length !== 3 || !parts[1]) return null;
+
+	try {
+		const payload = JSON.parse(base64UrlDecode(parts[1])) as { sub?: unknown };
+		return typeof payload.sub === 'string' && payload.sub.length > 0 ? payload.sub : null;
+	} catch {
+		return null;
+	}
+}
+
+function base64UrlDecode(segment: string): string {
+	if (typeof globalThis.atob !== 'function') {
+		throw new Error('base64 decoding is unavailable in this runtime');
+	}
+
+	const padding = segment.length % 4 === 0 ? '' : '='.repeat(4 - (segment.length % 4));
+	const binary = globalThis.atob(segment.replace(/-/g, '+').replace(/_/g, '/') + padding);
+	const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+	return new TextDecoder().decode(bytes);
+}
+
+/** FNV-1a 32-bit: stable obfuscation for opaque tokens, not a security primitive. */
+function hashString(value: string): string {
+	let hash = 0x811c9dc5;
+	for (let index = 0; index < value.length; index += 1) {
+		hash ^= value.charCodeAt(index);
+		hash = Math.imul(hash, 0x01000193);
+	}
+	return (hash >>> 0).toString(16);
+}
diff --git a/js/src/index.ts b/js/src/index.ts
new file mode 100644
index 00000000..1d0b4653
--- /dev/null
+++ b/js/src/index.ts
@@ -0,0 +1,55 @@
+export type {
+	GqlAuth,
+	GqlError,
+	GqlErrorLocation,
+	GqlResult,
+	GraphqlVariables
+} from './types.js';
+export {
+	DISTRIBUTED_PROTOCOL_VERSION,
+	DistributedProtocolError,
+	compareDistributedDecimal,
+	distributedLiveResumeExtensions,
+	parseDistributedProtocolEnvelope,
+	parseGraphqlResponseExtensions,
+	type DistributedDecimalString,
+	type DistributedCommandConsistency,
+	type DistributedCommandMetadata,
+	type DistributedCommandState,
+	type DistributedIndexRevision,
+	type DistributedLiveCursor,
+	type DistributedLiveMetadata,
+	type DistributedLiveResumeExtensions,
+	type DistributedOpaqueString,
+	type DistributedProjectionExpectation,
+	type DistributedProjectionObservation,
+	type DistributedProtocolValue,
+	type DistributedProtocolEnvelope,
+	type DistributedProtocolErrorCode,
+	type DistributedQuerySnapshot,
+	type DistributedRecordRevision,
+	type DistributedTrustedPreset,
+	type DistributedTrustedPresetCodec,
+	type GraphqlResponseExtensions
+} from './protocol.js';
+export { documentToString, type GqlDocument } from './document.js';
+export {
+	applyWsDevHeaderParams,
+	buildAuthHeaders,
+	wsConnectionInitPayload
+} from './auth-headers.js';
+export {
+	requestGraphql,
+	type FetchLike,
+	type RequestGraphqlOptions
+} from './request.js';
+export {
+	graphqlWsUrl,
+	httpUrlToWsUrl,
+	subscribe,
+	type GqlWsHandlers,
+	type GqlWsResult,
+	type SubscribeOptions,
+	type WebSocketConstructor
+} from './websocket.js';
+export { authIdentityKey, jwtPayloadSub } from './identity.js';
diff --git a/js/src/internal/cache-engine.ts b/js/src/internal/cache-engine.ts
new file mode 100644
index 00000000..ac79359a
--- /dev/null
+++ b/js/src/internal/cache-engine.ts
@@ -0,0 +1,38 @@
+/** Private cache engine; implementation lives in ./cache-engine/. */
+export {
+	CacheRevisionConflictError,
+	cacheIndexKey,
+	createCacheEngine
+} from './cache-engine/index.js';
+export type {
+	BaseCacheWriter,
+	BaseRecordClock,
+	CacheEngine,
+	CacheEngineOptions,
+	CacheEngineSnapshot,
+	CacheIndex,
+	CacheIndexCoverage,
+	CacheIndexMetadata,
+	CacheListener,
+	CachePresence,
+	CacheReader,
+	CacheSelector,
+	CacheValue,
+	DerivedIndexMutation,
+	DerivedIndexReconciler,
+	IndexKey,
+	IndexWrite,
+	OptimisticCacheWriter,
+	OptimisticIndexWrite,
+	OptimisticLayerContext,
+	OptimisticLayerState,
+	OptimisticLayerView,
+	OptimisticRecordWrite,
+	RecordKey,
+	RecordLink,
+	RecordWrite,
+	Revision,
+	SparseRecord,
+	SparseRecordMeta,
+	WatchOptions
+} from './cache-engine/index.js';
diff --git a/js/src/internal/cache-engine/create.ts b/js/src/internal/cache-engine/create.ts
new file mode 100644
index 00000000..c1b98ac3
--- /dev/null
+++ b/js/src/internal/cache-engine/create.ts
@@ -0,0 +1,10 @@
+import { PurposeBuiltCacheEngine } from './engine.js';
+import { cacheIndexKey } from './helpers.js';
+import type { CacheEngine, CacheEngineOptions } from './types.js';
+
+/** Create the selected private cache-engine implementation. */
+export function createCacheEngine(options: CacheEngineOptions = {}): CacheEngine {
+	return new PurposeBuiltCacheEngine(options);
+}
+
+export { cacheIndexKey };
diff --git a/js/src/internal/cache-engine/engine.ts b/js/src/internal/cache-engine/engine.ts
new file mode 100644
index 00000000..ce627919
--- /dev/null
+++ b/js/src/internal/cache-engine/engine.ts
@@ -0,0 +1,1521 @@
+import { CacheRevisionConflictError } from './errors.js';
+import {
+	assertName,
+	assertSynchronousResult,
+	assertWriterActive,
+	cloneCacheValue,
+	cloneDerivedIndexOperations,
+	cloneFields,
+	cloneIndexMetadata,
+	cloneLink,
+	cloneLinks,
+	compareRecordTuple,
+	deepEqual,
+	dependenciesChanged,
+	derivedIndexKeys,
+	emptyVisibleRecord,
+	freezeRecord,
+	indexDependency,
+	indexMetadataWithoutStaleReason,
+	isOrderedSubsequence,
+	isVisibleRecordLive,
+	linkKeys,
+	operationDependencies,
+	parseSnapshot,
+	recordFieldDependency,
+	recordSeenDependency,
+	recordWildcardDependency,
+	refinementMetadataCompatible,
+	reportSafely,
+	reportUnhandledWatcherError,
+	revisionString,
+	revisionToken,
+	runDerivedIndexReconciler,
+	validateIndexWrite,
+	validateRecordKey
+} from './helpers.js';
+import type {
+	BaseCacheWriter,
+	CacheEngine,
+	CacheEngineOptions,
+	CacheEngineSnapshot,
+	CacheIndex,
+	CacheListener,
+	CachePresence,
+	CacheReader,
+	CacheSelector,
+	CacheValue,
+	DerivedIndexOperation,
+	DerivedIndexReconciler,
+	EngineBackup,
+	IndexKey,
+	IndexWrite,
+	MaterializedCacheGraph,
+	OptimisticCacheWriter,
+	OptimisticIndexWrite,
+	OptimisticLayer,
+	OptimisticLayerContext,
+	OptimisticLayerState,
+	OptimisticRecordWrite,
+	OverlayOperation,
+	RecordKey,
+	RecordLink,
+	RecordWrite,
+	Revision,
+	SparseRecord,
+	SparseRecordMeta,
+	StoredIndex,
+	StoredRecord,
+	VisibleIndex,
+	VisibleRecord,
+	WatchOptions,
+	Watcher
+} from './types.js';
+
+/**
+ * Minimum purpose-built implementation selected by the executable spike.
+ *
+ * It stores authoritative sparse records and exact indexes, then materializes
+ * named optimistic operation layers above them. Confirmation advances a
+ * per-dependency causal floor before removing the layer, so an older pending
+ * layer cannot become visible again after a newer command confirms.
+ */
+export class PurposeBuiltCacheEngine implements CacheEngine {
+	#records = new Map<RecordKey, StoredRecord>();
+	#indexes = new Map<IndexKey, StoredIndex>();
+	#layers: OptimisticLayer[] = [];
+	#derivedIndexOperations: DerivedIndexOperation[] = [];
+	#derivedIndexReconciler: DerivedIndexReconciler | undefined;
+	#reconcilingDerivedIndexes = false;
+	#confirmedFloors = new Map<string, number>();
+	#retained = new Map<RecordKey, number>();
+	#nextLayerSequence = 0;
+	#watchers = new Set<Watcher>();
+	#transactionDepth = 0;
+	#transactionLifecycleIndexes = new Set<IndexKey>();
+	#dirty = false;
+	#changedDependencies = new Set<string>();
+	readonly #reportWatcherError: (error: AggregateError) => void;
+
+	constructor(options: CacheEngineOptions = {}) {
+		this.#reportWatcherError = options.onWatcherError ?? reportUnhandledWatcherError;
+	}
+
+	read<T>(selector: CacheSelector<T>): T {
+		if (typeof selector !== 'function') throw new TypeError('cache selector must be a function');
+		return selector(this.#reader());
+	}
+
+	readConfirmed<T>(selector: CacheSelector<T>): T {
+		if (typeof selector !== 'function') throw new TypeError('cache selector must be a function');
+		return selector(this.#reader(undefined, false));
+	}
+
+	confirmedIndexFences(
+		keys: readonly IndexKey[]
+	): ReadonlyMap<IndexKey, string> {
+		const fences = new Map<IndexKey, string>();
+		for (const key of new Set(keys)) {
+			assertName(key, 'index key');
+			const index = this.#indexes.get(key);
+			if (index === undefined) continue;
+			const fence =
+				index.staleRevision !== undefined &&
+				index.staleRevision > index.revision
+					? index.staleRevision
+					: index.revision;
+			fences.set(key, revisionString(fence));
+		}
+		return fences;
+	}
+
+	watch<T>(
+		selector: CacheSelector<T>,
+		listener: CacheListener<T>,
+		options: WatchOptions = {}
+	): () => void {
+		if (typeof listener !== 'function') throw new TypeError('cache listener must be a function');
+		const { value, dependencies } = this.#select(selector);
+		const watcher: Watcher<T> = { selector, listener, value, dependencies };
+		this.#watchers.add(watcher as Watcher);
+		if (options.immediate) {
+			try {
+				listener(value, undefined);
+			} catch (error) {
+				this.#watchers.delete(watcher as Watcher);
+				reportSafely(
+					this.#reportWatcherError,
+					new AggregateError([error], 'initial cache watcher delivery failed')
+				);
+			}
+		}
+		return () => this.#watchers.delete(watcher as Watcher);
+	}
+
+	batch<T>(update: (writer: BaseCacheWriter) => T): T {
+		if (typeof update !== 'function') throw new TypeError('cache update must be a function');
+		if (this.#transactionDepth !== 0) {
+			throw new Error('nested cache batches are not supported');
+		}
+		return this.#transaction(() => {
+			const result = this.#runBaseUpdate(update);
+			this.#reconcileDerivedIndexes();
+			return result;
+		});
+	}
+
+	createOptimisticLayer(
+		id: string,
+		update: (writer: OptimisticCacheWriter) => void,
+		context?: OptimisticLayerContext
+	): void {
+		assertName(id, 'optimistic layer id');
+		if (this.#layers.some((layer) => layer.id === id)) {
+			throw new Error(`optimistic layer already exists: ${id}`);
+		}
+
+		if (typeof update !== 'function') {
+			throw new TypeError('optimistic layer update must be a function');
+		}
+		const operations: OverlayOperation[] = [];
+		this.#runOptimisticUpdate(update, operations);
+		const stableContext =
+			context === undefined ? undefined : cloneCacheValue(context);
+		this.#transaction(() => {
+			const before = this.#materialize();
+			this.#layers.push({
+				id,
+				sequence: ++this.#nextLayerSequence,
+				state: 'optimistic',
+				operations,
+				...(stableContext === undefined ? {} : { context: stableContext })
+			});
+			this.#markOverlayChanges(operations, before, this.#materialize());
+			this.#dirty = true;
+			this.#reconcileDerivedIndexes();
+		});
+	}
+
+	setDerivedIndexReconciler(
+		reconciler: DerivedIndexReconciler | undefined
+	): void {
+		if (reconciler !== undefined && typeof reconciler !== 'function') {
+			throw new TypeError('derived index reconciler must be a function');
+		}
+		const previous = this.#derivedIndexReconciler;
+		try {
+			this.#transaction(() => {
+				this.#derivedIndexReconciler = reconciler;
+				this.#reconcileDerivedIndexes();
+			});
+		} catch (error) {
+			this.#derivedIndexReconciler = previous;
+			throw error;
+		}
+	}
+
+	markOptimisticLayerAccepted(id: string): boolean {
+		const layer = this.#layers.find((candidate) => candidate.id === id);
+		if (!layer) return false;
+		this.#transaction(() => {
+			layer.state = 'accepted';
+			this.#reconcileDerivedIndexes();
+		});
+		return true;
+	}
+
+	confirmOptimisticLayer<T>(id: string, update: (writer: BaseCacheWriter) => T): T {
+		return this.confirmOptimisticLayers([id], update);
+	}
+
+	confirmOptimisticLayers<T>(
+		ids: readonly string[],
+		update: (writer: BaseCacheWriter) => T
+	): T {
+		const unique = [...new Set(ids)];
+		if (unique.length !== ids.length) {
+			throw new Error('optimistic layer confirmation contains duplicate ids');
+		}
+		const layers = unique.map((id) => {
+			const layer = this.#layers.find((candidate) => candidate.id === id);
+			if (!layer) throw new Error(`unknown optimistic layer: ${id}`);
+			return layer;
+		});
+
+		return this.#transaction(() => {
+			const before = this.#materialize();
+			const layerDependencies = new Map<string, number>();
+			for (const layer of layers) {
+				for (const operation of layer.operations) {
+					for (const dependency of operationDependencies(operation)) {
+						layerDependencies.set(
+							dependency,
+							Math.max(layerDependencies.get(dependency) ?? 0, layer.sequence)
+						);
+					}
+				}
+			}
+
+			// A command result may contain a full row, but only fields owned by this
+			// optimistic layer are confirmed. Advancing floors for every field in the
+			// server payload would incorrectly erase independent, older overlays.
+			const result = this.#runBaseUpdate(update);
+			for (const [dependency, sequence] of layerDependencies) {
+				const previous = this.#confirmedFloors.get(dependency) ?? 0;
+				if (sequence > previous) this.#confirmedFloors.set(dependency, sequence);
+			}
+			const removed = new Set(layers);
+			this.#layers = this.#layers.filter((candidate) => !removed.has(candidate));
+			for (const layer of layers) {
+				this.#markOverlayChanges(layer.operations, before, this.#materialize());
+			}
+			if (this.#layers.length === 0) this.#confirmedFloors.clear();
+			this.#dirty = true;
+			this.#reconcileDerivedIndexes();
+			return result;
+		});
+	}
+
+	rejectOptimisticLayer(id: string): boolean {
+		const layer = this.#layers.find((candidate) => candidate.id === id);
+		if (!layer) return false;
+		this.#transaction(() => {
+			const before = this.#materialize();
+			this.#layers = this.#layers.filter((candidate) => candidate !== layer);
+			this.#markOverlayChanges(layer.operations, before, this.#materialize());
+			if (this.#layers.length === 0) this.#confirmedFloors.clear();
+			this.#dirty = true;
+			this.#reconcileDerivedIndexes();
+		});
+		return true;
+	}
+
+	optimisticLayerState(id: string): OptimisticLayerState | undefined {
+		return this.#layers.find((layer) => layer.id === id)?.state;
+	}
+
+	extract(): CacheEngineSnapshot {
+		return Object.freeze({
+			version: 1 as const,
+			records: Object.freeze(
+				[...this.#records]
+					.sort(([left], [right]) => left.localeCompare(right))
+					.map(([key, record]) =>
+						Object.freeze({
+							key,
+							revision: revisionString(record.revision),
+							incarnation: revisionString(record.incarnation),
+							...(record.tombstoneRevision === undefined
+								? {}
+								: { tombstoneRevision: revisionString(record.tombstoneRevision) }),
+							fields: freezeRecord(
+								[...record.fields]
+									.sort(([left], [right]) => left.localeCompare(right))
+									.map(([name, field]) => [
+										name,
+										Object.freeze({
+											revision: revisionString(field.revision),
+											value: cloneCacheValue(field.value)
+										})
+									])
+							),
+							links: freezeRecord(
+								[...record.links]
+									.sort(([left], [right]) => left.localeCompare(right))
+									.map(([name, link]) => [
+										name,
+										Object.freeze({
+											revision: revisionString(link.revision),
+											value: cloneLink(link.value)
+										})
+									])
+							)
+						})
+					)
+			),
+			indexes: Object.freeze(
+				[...this.#indexes]
+					.sort(([left], [right]) => left.localeCompare(right))
+					.map(([key, index]) =>
+						Object.freeze({
+							key,
+							revision: revisionString(index.revision),
+							...(index.staleRevision === undefined
+								? {}
+								: { staleRevision: revisionString(index.staleRevision) }),
+							records: Object.freeze([...index.records]),
+							complete: index.complete,
+							deleted: index.deleted,
+							...(index.metadata === undefined
+								? {}
+								: { metadata: cloneIndexMetadata(index.metadata) })
+						})
+					)
+			)
+		});
+	}
+
+	restore(snapshot: CacheEngineSnapshot): void {
+		const restored = parseSnapshot(snapshot);
+		this.#transaction(() => {
+			this.#records = restored.records;
+			this.#indexes = restored.indexes;
+			this.#layers = [];
+			this.#derivedIndexOperations = [];
+			this.#confirmedFloors.clear();
+			this.#nextLayerSequence = 0;
+			this.#changedDependencies.add('*');
+			this.#dirty = true;
+		});
+	}
+
+	restoreConfirmed(snapshot: CacheEngineSnapshot): void {
+		const restored = parseSnapshot(snapshot);
+		this.#transaction(() => {
+			this.#records = restored.records;
+			this.#indexes = restored.indexes;
+			this.#derivedIndexOperations = [];
+			this.#changedDependencies.add('*');
+			this.#dirty = true;
+			this.#reconcileDerivedIndexes();
+		});
+	}
+
+	discardIndexes(keys: readonly IndexKey[]): void {
+		const unique = new Set<IndexKey>();
+		for (const key of keys) {
+			assertName(key, 'index key');
+			unique.add(key);
+		}
+		if (unique.size === 0) return;
+		this.#transaction(() => {
+			let changed = false;
+			for (const key of unique) {
+				if (!this.#indexes.delete(key)) continue;
+				this.#changedDependencies.add(indexDependency(key));
+				changed = true;
+			}
+			if (changed) this.#dirty = true;
+			this.#reconcileDerivedIndexes();
+		});
+	}
+
+	retain(key: RecordKey): void {
+		assertName(key, 'record key');
+		this.#retained.set(key, (this.#retained.get(key) ?? 0) + 1);
+	}
+
+	release(key: RecordKey): void {
+		const count = this.#retained.get(key);
+		if (count === undefined) return;
+		if (count <= 1) this.#retained.delete(key);
+		else this.#retained.set(key, count - 1);
+	}
+
+	gc(): readonly RecordKey[] {
+		return this.#transaction(() => {
+			// A destructive optimistic overlay must not make confirmed state
+			// collectible: rejecting that layer has to reveal the complete base
+			// graph again. Conversely, an optimistic index/link may be the only
+			// current root for an authoritative record. Preserve the union.
+			const optimisticRoots = this.#optimisticRecordRoots();
+			const baseGraph = this.#materialize(false);
+			const visibleGraph = this.#materialize(true);
+			const reachable = new Set<RecordKey>([
+				...this.#reachableRecords(baseGraph, optimisticRoots),
+				...this.#reachableRecords(visibleGraph, optimisticRoots)
+			]);
+
+			const collected: RecordKey[] = [];
+			for (const [key, record] of this.#records) {
+				// Tombstones are revision fences and cannot be collected like data rows.
+				if (record.tombstoneRevision === undefined && !reachable.has(key)) {
+					this.#records.delete(key);
+					this.#changedDependencies.add(recordSeenDependency(key));
+					this.#changedDependencies.add(recordWildcardDependency(key));
+					collected.push(key);
+				}
+			}
+			let indexesCollected = false;
+			for (const [key, index] of this.#indexes) {
+				const parent = index.metadata?.parent;
+				if (parent === undefined) continue;
+				const parentIsLive =
+					isVisibleRecordLive(baseGraph.records.get(parent)) ||
+					isVisibleRecordLive(visibleGraph.records.get(parent));
+				if (reachable.has(parent) && parentIsLive) continue;
+				this.#indexes.delete(key);
+				this.#changedDependencies.add(indexDependency(key));
+				indexesCollected = true;
+			}
+			if (collected.length > 0 || indexesCollected) this.#dirty = true;
+			this.#reconcileDerivedIndexes();
+			return Object.freeze(collected.sort());
+		});
+	}
+
+	#reader(
+		dependencies?: Set<string>,
+		includeOptimistic = true
+	): CacheReader {
+		// V1 executable-spike tradeoff: materializing the visible graph is
+		// O(records + indexes + overlay operations) per selector. The private seam
+		// keeps this replaceable with an incrementally indexed graph without
+		// changing generated artifacts or the public replica API.
+		const { records, indexes } = this.#materialize(includeOptimistic);
+		return Object.freeze({
+			recordMeta(key: RecordKey): SparseRecordMeta | undefined {
+				dependencies?.add(recordSeenDependency(key));
+				const record = records.get(key);
+				if (!record || record.tombstoned) return undefined;
+				return Object.freeze({
+					key,
+					incarnation: revisionString(record.incarnation)
+				});
+			},
+			field(key: RecordKey, name: string): CachePresence<CacheValue> {
+				assertName(name, 'record field');
+				dependencies?.add(recordSeenDependency(key));
+				dependencies?.add(recordFieldDependency(key, `field:${name}`));
+				const record = records.get(key);
+				if (!record || record.tombstoned || !record.fields.has(name)) {
+					return Object.freeze({ present: false });
+				}
+				return Object.freeze({
+					present: true,
+					value: cloneCacheValue(record.fields.get(name)!)
+				});
+			},
+			link(key: RecordKey, name: string): CachePresence<RecordLink> {
+				assertName(name, 'record link');
+				dependencies?.add(recordSeenDependency(key));
+				dependencies?.add(recordFieldDependency(key, `link:${name}`));
+				const record = records.get(key);
+				if (!record || record.tombstoned || !record.links.has(name)) {
+					return Object.freeze({ present: false });
+				}
+				return Object.freeze({
+					present: true,
+					value: cloneLink(record.links.get(name)!)
+				});
+			},
+			record(key: RecordKey): SparseRecord | undefined {
+				dependencies?.add(recordWildcardDependency(key));
+				const record = records.get(key);
+				if (!record || record.tombstoned) return undefined;
+				return Object.freeze({
+					key,
+					revision: revisionString(record.revision),
+					incarnation: revisionString(record.incarnation),
+					fields: freezeRecord(
+						[...record.fields].map(([name, value]) => [name, cloneCacheValue(value)])
+					),
+					links: freezeRecord(
+						[...record.links].map(([name, value]) => [name, cloneLink(value)])
+					)
+				});
+			},
+			index(key: IndexKey): CacheIndex | undefined {
+				dependencies?.add(indexDependency(key));
+				const index = indexes.get(key);
+				if (!index || index.deleted) return undefined;
+				return Object.freeze({
+					key,
+					revision: revisionString(index.revision),
+					...(index.staleRevision === undefined
+						? {}
+						: { staleRevision: revisionString(index.staleRevision) }),
+					records: Object.freeze([...index.records]),
+					complete: index.complete,
+					...(index.metadata === undefined
+						? {}
+						: { metadata: cloneIndexMetadata(index.metadata) })
+				});
+			}
+		});
+	}
+
+	#select<T>(selector: CacheSelector<T>): { value: T; dependencies: Set<string> } {
+		const dependencies = new Set<string>();
+		return { value: selector(this.#reader(dependencies)), dependencies };
+	}
+
+	#optimisticRecordRoots(): Set<RecordKey> {
+		const roots = new Set<RecordKey>();
+		for (const layer of this.#layers) {
+			for (const operation of layer.operations) {
+				if (operation.kind === 'write-record') {
+					roots.add(operation.write.key);
+					for (const link of Object.values(operation.write.links ?? {})) {
+						for (const key of linkKeys(link)) roots.add(key);
+					}
+				} else if (operation.kind === 'tombstone-record') {
+					roots.add(operation.key);
+				} else if (operation.kind === 'write-index') {
+					for (const key of operation.write.records) roots.add(key);
+				}
+			}
+		}
+		for (const operation of this.#derivedIndexOperations) {
+			if (operation.kind !== 'write-index') continue;
+			for (const key of operation.write.records) roots.add(key);
+		}
+		return roots;
+	}
+
+	#reachableRecords(
+		graph: {
+			records: Map<RecordKey, VisibleRecord>;
+			indexes: Map<IndexKey, VisibleIndex>;
+		},
+		extraRoots: ReadonlySet<RecordKey>
+	): Set<RecordKey> {
+		const reachable = new Set<RecordKey>([...this.#retained.keys(), ...extraRoots]);
+		const pending = [...reachable];
+		const relationshipIndexes = new Map<RecordKey, VisibleIndex[]>();
+		for (const index of graph.indexes.values()) {
+			if (index.deleted) continue;
+			const parent = index.metadata?.parent;
+			if (parent !== undefined) {
+				const indexes = relationshipIndexes.get(parent) ?? [];
+				indexes.push(index);
+				relationshipIndexes.set(parent, indexes);
+				continue;
+			}
+			for (const key of index.records) {
+				if (reachable.has(key)) continue;
+				reachable.add(key);
+				pending.push(key);
+			}
+		}
+		while (pending.length > 0) {
+			const key = pending.pop()!;
+			const record = graph.records.get(key);
+			if (!record || record.tombstoned) continue;
+			for (const link of record.links.values()) {
+				for (const key of linkKeys(link)) {
+					if (reachable.has(key)) continue;
+					reachable.add(key);
+				pending.push(key);
+				}
+			}
+			for (const index of relationshipIndexes.get(key) ?? []) {
+				for (const child of index.records) {
+					if (reachable.has(child)) continue;
+					reachable.add(child);
+					pending.push(child);
+				}
+			}
+		}
+		return reachable;
+	}
+
+	#materialize(includeOptimistic = true): MaterializedCacheGraph {
+		const records = new Map<RecordKey, VisibleRecord>();
+		const indexes = new Map<IndexKey, VisibleIndex>();
+
+		for (const [key, record] of this.#records) {
+			records.set(key, {
+				revision: record.revision,
+				incarnation: record.incarnation,
+				tombstoned: record.tombstoneRevision !== undefined,
+				fields: new Map([...record.fields].map(([name, field]) => [name, field.value])),
+				links: new Map([...record.links].map(([name, link]) => [name, link.value]))
+			});
+		}
+		for (const [key, index] of this.#indexes) {
+			indexes.set(key, {
+				revision: index.revision,
+				staleRevision: index.staleRevision,
+				records: [...index.records],
+				complete: index.complete,
+				deleted: index.deleted,
+				metadata: index.metadata
+			});
+		}
+
+		if (includeOptimistic) {
+			for (const layer of this.#layers) {
+				for (const operation of layer.operations) {
+					this.#applyOverlay(records, indexes, layer.sequence, operation);
+				}
+			}
+			for (const operation of this.#derivedIndexOperations) {
+				this.#applyDerivedIndexOperation(records, indexes, operation);
+			}
+		}
+
+		return { records, indexes };
+	}
+
+	#markOverlayChanges(
+		operations: readonly OverlayOperation[],
+		before: MaterializedCacheGraph,
+		after: MaterializedCacheGraph
+	): void {
+		for (const operation of operations) {
+			if (operation.kind === 'write-record') {
+				const key = operation.write.key;
+				this.#changedDependencies.add(recordWildcardDependency(key));
+				for (const name of Object.keys(operation.write.fields ?? {})) {
+					this.#changedDependencies.add(recordFieldDependency(key, `field:${name}`));
+				}
+				for (const name of Object.keys(operation.write.links ?? {})) {
+					this.#changedDependencies.add(recordFieldDependency(key, `link:${name}`));
+				}
+				const previous = before.records.get(key);
+				const next = after.records.get(key);
+				if (
+					(previous !== undefined && !previous.tombstoned) !==
+						(next !== undefined && !next.tombstoned) ||
+					previous?.incarnation !== next?.incarnation
+				) {
+					this.#changedDependencies.add(recordSeenDependency(key));
+				}
+				continue;
+			}
+			if (operation.kind === 'tombstone-record') {
+				this.#changedDependencies.add(recordSeenDependency(operation.key));
+				this.#changedDependencies.add(recordWildcardDependency(operation.key));
+				continue;
+			}
+			this.#changedDependencies.add(
+				indexDependency(operation.kind === 'write-index' ? operation.write.key : operation.key)
+			);
+		}
+	}
+
+	#applyOverlay(
+		records: Map<RecordKey, VisibleRecord>,
+		indexes: Map<IndexKey, VisibleIndex>,
+		sequence: number,
+		operation: OverlayOperation
+	): void {
+		if (operation.kind === 'write-record') {
+			const { key, fields = {}, links = {} } = operation.write;
+			let record = records.get(key);
+			let wrote = false;
+			for (const [name, value] of Object.entries(fields)) {
+				if (sequence <= this.#recordFieldFloor(key, `field:${name}`)) continue;
+				if (!record) record = emptyVisibleRecord();
+				record.fields.set(name, value);
+				wrote = true;
+			}
+			for (const [name, value] of Object.entries(links)) {
+				if (sequence <= this.#recordFieldFloor(key, `link:${name}`)) continue;
+				if (!record) record = emptyVisibleRecord();
+				record.links.set(name, value);
+				wrote = true;
+			}
+			if (wrote && record) {
+				record.tombstoned = false;
+				records.set(key, record);
+			}
+			return;
+		}
+
+		if (operation.kind === 'tombstone-record') {
+			if (sequence <= (this.#confirmedFloors.get(recordSeenDependency(operation.key)) ?? 0)) {
+				return;
+			}
+			const record = records.get(operation.key) ?? emptyVisibleRecord();
+			record.tombstoned = true;
+			record.fields.clear();
+			record.links.clear();
+			records.set(operation.key, record);
+			return;
+		}
+
+		const key = operation.kind === 'write-index' ? operation.write.key : operation.key;
+		if (sequence <= (this.#confirmedFloors.get(indexDependency(key)) ?? 0)) return;
+		if (operation.kind === 'write-index') {
+			let metadata = operation.write.metadata;
+			if (metadata?.parent !== undefined) {
+				const parent = records.get(metadata.parent);
+				if (!parent || parent.tombstoned) return;
+				if (
+					metadata.parentRevision !== undefined &&
+					revisionToken(metadata.parentRevision) !== parent.revision
+				) {
+					return;
+				}
+				if (
+					metadata.parentIncarnation !== undefined &&
+					revisionToken(metadata.parentIncarnation) !== parent.incarnation
+				) {
+					return;
+				}
+				metadata = cloneIndexMetadata({
+					...metadata,
+					parentIncarnation: revisionString(parent.incarnation)
+				});
+			}
+			indexes.set(key, {
+				revision: indexes.get(key)?.revision ?? 0n,
+				staleRevision: indexes.get(key)?.staleRevision,
+				records: [...operation.write.records],
+				complete: operation.write.complete ?? false,
+				deleted: false,
+				metadata
+			});
+		} else {
+			const index = indexes.get(key) ?? {
+				revision: 0n,
+				staleRevision: undefined,
+				records: [],
+				complete: false,
+				deleted: true,
+				metadata: undefined
+			};
+			index.deleted = true;
+			index.records = [];
+			indexes.set(key, index);
+		}
+	}
+
+	#applyDerivedIndexOperation(
+		records: Map<RecordKey, VisibleRecord>,
+		indexes: Map<IndexKey, VisibleIndex>,
+		operation: DerivedIndexOperation
+	): void {
+		if (operation.kind === 'mark-index-stale') {
+			const index = indexes.get(operation.key);
+			if (!index || index.deleted) return;
+			/*
+			 * Staleness is a freshness claim, not structural data loss. Keep a
+			 * previously complete visible index renderable while the owner
+			 * revalidates it. Operations that actually remove membership or
+			 * records explicitly clear `complete` in their own lifecycle path.
+			 */
+			if (
+				index.staleRevision === undefined ||
+				index.staleRevision < index.revision
+			) {
+				index.staleRevision = index.revision;
+			}
+			if (index.metadata !== undefined) {
+				index.metadata = cloneIndexMetadata({
+					...index.metadata,
+					staleReason: operation.reason
+				});
+			}
+			return;
+		}
+
+		const key =
+			operation.kind === 'write-index' ? operation.write.key : operation.key;
+		if (operation.kind === 'delete-index') {
+			const index = indexes.get(key) ?? {
+				revision: 0n,
+				staleRevision: undefined,
+				records: [],
+				complete: false,
+				deleted: true,
+				metadata: undefined
+			};
+			index.deleted = true;
+			index.records = [];
+			indexes.set(key, index);
+			return;
+		}
+
+		let metadata = operation.write.metadata;
+		if (metadata?.parent !== undefined) {
+			const parent = records.get(metadata.parent);
+			if (!parent || parent.tombstoned) return;
+			if (
+				metadata.parentRevision !== undefined &&
+				revisionToken(metadata.parentRevision) !== parent.revision
+			) {
+				return;
+			}
+			if (
+				metadata.parentIncarnation !== undefined &&
+				revisionToken(metadata.parentIncarnation) !== parent.incarnation
+			) {
+				return;
+			}
+			metadata = cloneIndexMetadata({
+				...metadata,
+				parentIncarnation: revisionString(parent.incarnation)
+			});
+		}
+		indexes.set(key, {
+			revision: indexes.get(key)?.revision ?? 0n,
+			staleRevision: indexes.get(key)?.staleRevision,
+			records: [...operation.write.records],
+			complete: operation.write.complete ?? false,
+			deleted: false,
+			metadata
+		});
+	}
+
+	#reconcileDerivedIndexes(): void {
+		if (this.#reconcilingDerivedIndexes) {
+			throw new Error('derived index reconciliation cannot be re-entered');
+		}
+		const reconciler = this.#derivedIndexReconciler;
+		let next: readonly DerivedIndexOperation[];
+		this.#reconcilingDerivedIndexes = true;
+		try {
+			next =
+				reconciler === undefined
+					? []
+					: cloneDerivedIndexOperations(
+							runDerivedIndexReconciler(
+								reconciler,
+								this.extract(),
+								this.#layers.map((layer) =>
+									Object.freeze({
+										id: layer.id,
+										sequence: layer.sequence,
+										state: layer.state,
+										...(layer.context === undefined
+											? {}
+											: { context: layer.context })
+									})
+								)
+							)
+						);
+		} finally {
+			this.#reconcilingDerivedIndexes = false;
+		}
+		const before = this.#materialize();
+		const previous = this.#derivedIndexOperations;
+		this.#derivedIndexOperations = [...next];
+		const after = this.#materialize();
+		let changed = false;
+		for (const key of derivedIndexKeys([...previous, ...next])) {
+			if (deepEqual(before.indexes.get(key), after.indexes.get(key))) continue;
+			this.#changedDependencies.add(indexDependency(key));
+			changed = true;
+		}
+		if (changed) this.#dirty = true;
+	}
+
+	#recordFieldFloor(key: RecordKey, field: string): number {
+		return Math.max(
+			this.#confirmedFloors.get(recordWildcardDependency(key)) ?? 0,
+			this.#confirmedFloors.get(recordFieldDependency(key, field)) ?? 0
+		);
+	}
+
+	#baseWriter(touched?: Set<string>, isActive: () => boolean = () => true): BaseCacheWriter {
+		return Object.freeze({
+			recordClock: (key: RecordKey) => {
+				assertWriterActive(isActive());
+				validateRecordKey(key);
+				const record = this.#records.get(key);
+				if (!record) return undefined;
+				return Object.freeze({
+					revision: revisionString(record.revision),
+					incarnation: revisionString(record.incarnation),
+					tombstoned: record.tombstoneRevision !== undefined
+				});
+			},
+			writeRecord: (write: RecordWrite) => {
+				assertWriterActive(isActive());
+				return this.#writeBaseRecord(write, touched);
+			},
+			tombstoneRecord: (
+				key: RecordKey,
+				revision: Revision,
+				incarnation?: Revision
+			) => {
+				assertWriterActive(isActive());
+				return this.#tombstoneBaseRecord(key, revision, incarnation, touched);
+			},
+			discardRecord: (key: RecordKey) => {
+				assertWriterActive(isActive());
+				return this.#discardBaseRecord(key, touched);
+			},
+			writeIndex: (write: IndexWrite) => {
+				assertWriterActive(isActive());
+				return this.#writeBaseIndex(write, touched);
+			},
+			markIndexStale: (key: IndexKey, reason: string, revision?: Revision) => {
+				assertWriterActive(isActive());
+				return this.#markBaseIndexStale(key, reason, revision, touched);
+			},
+			deleteIndex: (key: IndexKey, revision: Revision) => {
+				assertWriterActive(isActive());
+				return this.#deleteBaseIndex(key, revision, touched);
+			}
+		});
+	}
+
+	#optimisticWriter(
+		operations: OverlayOperation[],
+		isActive: () => boolean = () => true
+	): OptimisticCacheWriter {
+		return Object.freeze({
+			writeRecord(write: OptimisticRecordWrite): void {
+				assertWriterActive(isActive());
+				validateRecordKey(write.key);
+				const fields = cloneFields(write.fields);
+				const links = cloneLinks(write.links);
+				if (Object.keys(fields).length === 0 && Object.keys(links).length === 0) return;
+				operations.push({ kind: 'write-record', write: { key: write.key, fields, links } });
+			},
+			tombstoneRecord(key: RecordKey): void {
+				assertWriterActive(isActive());
+				validateRecordKey(key);
+				operations.push({ kind: 'tombstone-record', key });
+			},
+			writeIndex(write: OptimisticIndexWrite): void {
+				assertWriterActive(isActive());
+				validateIndexWrite(write);
+				operations.push({
+					kind: 'write-index',
+					write: {
+						key: write.key,
+						records: Object.freeze([...write.records]),
+						complete: write.complete ?? false,
+						...(write.metadata === undefined
+							? {}
+							: { metadata: cloneIndexMetadata(write.metadata) })
+					}
+				});
+			},
+			deleteIndex(key: IndexKey): void {
+				assertWriterActive(isActive());
+				assertName(key, 'index key');
+				operations.push({ kind: 'delete-index', key });
+			}
+		});
+	}
+
+	#runBaseUpdate<T>(
+		update: (writer: BaseCacheWriter) => T,
+		touched?: Set<string>
+	): T {
+		let active = true;
+		const writer = this.#baseWriter(touched, () => active);
+		try {
+			const result = update(writer);
+			assertSynchronousResult(result, 'cache update');
+			return result;
+		} finally {
+			active = false;
+		}
+	}
+
+	#runOptimisticUpdate(
+		update: (writer: OptimisticCacheWriter) => void,
+		operations: OverlayOperation[]
+	): void {
+		let active = true;
+		const writer = this.#optimisticWriter(operations, () => active);
+		try {
+			const result = update(writer);
+			assertSynchronousResult(result, 'optimistic layer update');
+		} finally {
+			active = false;
+		}
+	}
+
+	#writeBaseRecord(write: RecordWrite, touched?: Set<string>): boolean {
+		validateRecordKey(write.key);
+		const revision = revisionToken(write.revision);
+		const requestedIncarnation =
+			write.incarnation === undefined ? undefined : revisionToken(write.incarnation);
+		const fields = cloneFields(write.fields);
+		const links = cloneLinks(write.links);
+		for (const name of Object.keys(fields)) {
+			touched?.add(recordFieldDependency(write.key, `field:${name}`));
+		}
+		for (const name of Object.keys(links)) {
+			touched?.add(recordFieldDependency(write.key, `link:${name}`));
+		}
+		if (Object.keys(fields).length > 0 || Object.keys(links).length > 0) {
+			touched?.add(recordSeenDependency(write.key));
+		}
+
+		let record = this.#records.get(write.key);
+		if (
+			requestedIncarnation === undefined &&
+			record?.tombstoneRevision !== undefined
+		) {
+			if (revision < record.revision) return false;
+			if (revision === record.revision) {
+				throw new CacheRevisionConflictError(
+					recordSeenDependency(write.key),
+					revision
+				);
+			}
+		}
+		const incarnation =
+			requestedIncarnation ??
+			(record === undefined
+				? revision
+				: record.tombstoneRevision === undefined
+					? record.incarnation
+					: revision);
+		if (record !== undefined) {
+			const comparison = compareRecordTuple(
+				incarnation,
+				revision,
+				record.incarnation,
+				record.revision
+			);
+			if (comparison < 0) return false;
+			if (comparison === 0 && record.tombstoneRevision !== undefined) {
+				throw new CacheRevisionConflictError(
+					recordSeenDependency(write.key),
+					revision
+				);
+			}
+			if (
+				comparison > 0 &&
+				record.tombstoneRevision !== undefined &&
+				incarnation === record.incarnation
+			) {
+				throw new CacheRevisionConflictError(
+					recordSeenDependency(write.key),
+					revision
+				);
+			}
+		}
+
+		let changed = false;
+		let presenceChanged = false;
+		if (!record) {
+			this.#invalidateIndexesForRecordLifecycle(write.key, touched);
+			record = {
+				revision,
+				incarnation,
+				fields: new Map(),
+				links: new Map()
+			};
+			this.#records.set(write.key, record);
+			changed = true;
+			presenceChanged = true;
+		} else if (incarnation > record.incarnation) {
+			this.#invalidateIndexesForRecordLifecycle(write.key, touched);
+			record.fields.clear();
+			record.links.clear();
+			record.tombstoneRevision = undefined;
+			record.incarnation = incarnation;
+			record.revision = revision;
+			changed = true;
+			presenceChanged = true;
+		}
+
+		for (const [name, value] of Object.entries(fields)) {
+			const current = record.fields.get(name);
+			if (current && revision < current.revision) continue;
+			if (current && revision === current.revision) {
+				if (deepEqual(current.value, value)) continue;
+				throw new CacheRevisionConflictError(
+					recordFieldDependency(write.key, `field:${name}`),
+					revision
+				);
+			}
+			record.fields.set(name, { revision, value });
+			changed = true;
+		}
+		for (const [name, value] of Object.entries(links)) {
+			const current = record.links.get(name);
+			if (current && revision < current.revision) continue;
+			if (current && revision === current.revision) {
+				if (deepEqual(current.value, value)) continue;
+				throw new CacheRevisionConflictError(
+					recordFieldDependency(write.key, `link:${name}`),
+					revision
+				);
+			}
+			record.links.set(name, { revision, value });
+			changed = true;
+		}
+		if (incarnation === record.incarnation && revision > record.revision) {
+			record.revision = revision;
+			changed = true;
+		}
+		if (changed) {
+			this.#changedDependencies.add(recordWildcardDependency(write.key));
+			if (presenceChanged) this.#changedDependencies.add(recordSeenDependency(write.key));
+			for (const name of Object.keys(fields)) {
+				this.#changedDependencies.add(
+					recordFieldDependency(write.key, `field:${name}`)
+				);
+			}
+			for (const name of Object.keys(links)) {
+				this.#changedDependencies.add(
+					recordFieldDependency(write.key, `link:${name}`)
+				);
+			}
+			this.#dirty = true;
+		}
+		return changed;
+	}
+
+	#tombstoneBaseRecord(
+		key: RecordKey,
+		revisionValue: Revision,
+		incarnationValue?: Revision,
+		touched?: Set<string>
+	): boolean {
+		validateRecordKey(key);
+		const revision = revisionToken(revisionValue);
+		touched?.add(recordWildcardDependency(key));
+		touched?.add(recordSeenDependency(key));
+		const record = this.#records.get(key);
+		const incarnation =
+			incarnationValue === undefined
+				? (record?.incarnation ?? revision)
+				: revisionToken(incarnationValue);
+		if (record) {
+			const comparison = compareRecordTuple(
+				incarnation,
+				revision,
+				record.incarnation,
+				record.revision
+			);
+			if (comparison < 0) return false;
+			if (comparison === 0) {
+				if (record.tombstoneRevision !== undefined) return false;
+				throw new CacheRevisionConflictError(recordSeenDependency(key), revision);
+			}
+			record.incarnation = incarnation;
+			record.revision = revision;
+			record.tombstoneRevision = revision;
+			record.fields.clear();
+			record.links.clear();
+		} else {
+			this.#records.set(key, {
+				revision,
+				incarnation,
+				tombstoneRevision: revision,
+				fields: new Map(),
+				links: new Map()
+			});
+		}
+		this.#invalidateIndexesForRecordLifecycle(key, touched);
+		this.#changedDependencies.add(recordSeenDependency(key));
+		this.#changedDependencies.add(recordWildcardDependency(key));
+		this.#dirty = true;
+		return true;
+	}
+
+	#discardBaseRecord(key: RecordKey, touched?: Set<string>): boolean {
+		validateRecordKey(key);
+		const hadRecord = this.#records.has(key);
+		const hasIndexReference = [...this.#indexes.values()].some(
+			(index) =>
+				!index.deleted &&
+				(index.metadata?.parent === key || index.records.includes(key))
+		);
+		if (!hadRecord && !hasIndexReference) return false;
+		this.#records.delete(key);
+		touched?.add(recordSeenDependency(key));
+		touched?.add(recordWildcardDependency(key));
+		this.#invalidateIndexesForRecordLifecycle(key, touched);
+		this.#changedDependencies.add(recordSeenDependency(key));
+		this.#changedDependencies.add(recordWildcardDependency(key));
+		this.#dirty = true;
+		return true;
+	}
+
+	#invalidateIndexesForRecordLifecycle(
+		recordKey: RecordKey,
+		touched?: Set<string>
+	): void {
+		for (const [key, index] of this.#indexes) {
+			if (index.deleted) continue;
+			const ownedByRecord = index.metadata?.parent === recordKey;
+			const referencesRecord = index.records.includes(recordKey);
+			if (!ownedByRecord && !referencesRecord) continue;
+			this.#transactionLifecycleIndexes.add(key);
+			index.deleted = ownedByRecord;
+			index.records = ownedByRecord
+				? []
+				: index.records.filter((candidate) => candidate !== recordKey);
+			index.complete = false;
+			if (index.metadata !== undefined) {
+				index.metadata = cloneIndexMetadata({
+					...index.metadata,
+					staleReason: 'record-lifecycle-changed'
+				});
+			}
+			if (index.staleRevision === undefined || index.staleRevision < index.revision) {
+				index.staleRevision = index.revision;
+			}
+			touched?.add(indexDependency(key));
+			this.#changedDependencies.add(indexDependency(key));
+			this.#dirty = true;
+		}
+	}
+
+	#writeBaseIndex(write: IndexWrite, touched?: Set<string>): boolean {
+		validateIndexWrite(write);
+		const revision = revisionToken(write.revision);
+		touched?.add(indexDependency(write.key));
+		const current = this.#indexes.get(write.key);
+		if (current?.staleRevision !== undefined && revision < current.staleRevision) {
+			return false;
+		}
+		if (current && revision < current.revision) return false;
+		const records = [...write.records];
+		const complete = write.complete ?? false;
+		let metadata =
+			write.metadata === undefined ? undefined : cloneIndexMetadata(write.metadata);
+		if (metadata?.parent !== undefined) {
+			const parent = this.#records.get(metadata.parent);
+			if (!parent || parent.tombstoneRevision !== undefined) return false;
+			if (
+				metadata.parentRevision !== undefined &&
+				revisionToken(metadata.parentRevision) !== parent.revision
+			) {
+				throw new CacheRevisionConflictError(
+					recordSeenDependency(metadata.parent),
+					revisionToken(metadata.parentRevision)
+				);
+			}
+			if (
+				metadata.parentIncarnation !== undefined &&
+				revisionToken(metadata.parentIncarnation) !== parent.incarnation
+			) {
+				throw new CacheRevisionConflictError(
+					recordSeenDependency(metadata.parent),
+					revisionToken(metadata.parentIncarnation)
+				);
+			}
+			metadata = cloneIndexMetadata({
+				...metadata,
+				parentIncarnation: revisionString(parent.incarnation)
+			});
+		}
+		const staleRevision = metadata?.staleReason === undefined ? undefined : revision;
+		if (current && revision === current.revision) {
+			if (
+				current.deleted &&
+				current.metadata === undefined &&
+				current.records.length === 0 &&
+				current.staleRevision === revision
+			) {
+				// A hidden fence uses an empty deleted index so it materializes no
+				// membership. Revision zero is valid, so an equal-checkpoint success
+				// must be able to replace that sentinel state.
+				current.records = records;
+				current.complete = complete;
+				current.deleted = false;
+				current.metadata = metadata;
+				current.staleRevision = staleRevision;
+				this.#changedDependencies.add(indexDependency(write.key));
+				this.#dirty = true;
+				return true;
+			}
+			if (
+				complete &&
+				metadata?.staleReason === undefined &&
+				(this.#transactionLifecycleIndexes.has(write.key) ||
+					(!current.deleted &&
+						!current.complete &&
+						current.metadata?.staleReason !== 'record-lifecycle-changed' &&
+						isOrderedSubsequence(current.records, records) &&
+						refinementMetadataCompatible(current.metadata, metadata)))
+			) {
+				// A partial GraphQL result may be retried without the underlying read
+				// model advancing. Permit only the monotonic incomplete -> complete
+				// refinement; an already-authoritative membership still conflicts on
+				// any same-revision disagreement.
+				current.records = records;
+				current.complete = true;
+				current.deleted = false;
+				current.metadata = metadata;
+				current.staleRevision = undefined;
+				this.#changedDependencies.add(indexDependency(write.key));
+				this.#dirty = true;
+				return true;
+			}
+			const currentComparable = indexMetadataWithoutStaleReason(current.metadata);
+			const nextComparable = indexMetadataWithoutStaleReason(metadata);
+			if (
+				!current.deleted &&
+				current.complete === complete &&
+				deepEqual(current.records, records) &&
+				deepEqual(currentComparable, nextComparable)
+			) {
+				if (
+					deepEqual(current.metadata, metadata) &&
+					current.staleRevision === staleRevision
+				) {
+					return false;
+				}
+				current.metadata = metadata;
+				current.staleRevision = staleRevision;
+				this.#changedDependencies.add(indexDependency(write.key));
+				this.#dirty = true;
+				return true;
+			}
+			throw new CacheRevisionConflictError(indexDependency(write.key), revision);
+		}
+		this.#indexes.set(write.key, {
+			revision,
+			records,
+			complete,
+			deleted: false,
+			metadata,
+			staleRevision
+		});
+		this.#changedDependencies.add(indexDependency(write.key));
+		this.#dirty = true;
+		return true;
+	}
+
+	#markBaseIndexStale(
+		key: IndexKey,
+		reason: string,
+		revisionValue?: Revision,
+		touched?: Set<string>
+	): boolean {
+		assertName(key, 'index key');
+		assertName(reason, 'index stale reason');
+		let current = this.#indexes.get(key);
+		if (!current) {
+			if (revisionValue === undefined) return false;
+			const revision = revisionToken(revisionValue);
+			this.#indexes.set(key, {
+				revision: 0n,
+				staleRevision: revision,
+				records: [],
+				complete: false,
+				deleted: true,
+				metadata: undefined
+			});
+			touched?.add(indexDependency(key));
+			this.#changedDependencies.add(indexDependency(key));
+			this.#dirty = true;
+			return true;
+		}
+		if (current.deleted && revisionValue === undefined) return false;
+		const revision =
+			revisionValue === undefined ? current.revision : revisionToken(revisionValue);
+		const fence =
+			current.staleRevision !== undefined && current.staleRevision > current.revision
+				? current.staleRevision
+				: current.revision;
+		if (revision < fence) return false;
+		if (
+			current.staleRevision === revision &&
+			(current.metadata === undefined || current.metadata.staleReason === reason)
+		) {
+			return false;
+		}
+		touched?.add(indexDependency(key));
+		if (current.metadata !== undefined) {
+			current.metadata = cloneIndexMetadata({ ...current.metadata, staleReason: reason });
+		}
+		current.staleRevision = revision;
+		this.#changedDependencies.add(indexDependency(key));
+		this.#dirty = true;
+		return true;
+	}
+
+	#deleteBaseIndex(key: IndexKey, revisionValue: Revision, touched?: Set<string>): boolean {
+		assertName(key, 'index key');
+		const revision = revisionToken(revisionValue);
+		touched?.add(indexDependency(key));
+		const current = this.#indexes.get(key);
+		if (current?.staleRevision !== undefined && revision < current.staleRevision) {
+			return false;
+		}
+		if (current && revision < current.revision) return false;
+		if (current && revision === current.revision) {
+			if (current.deleted) return false;
+			throw new CacheRevisionConflictError(indexDependency(key), revision);
+		}
+		this.#indexes.set(key, {
+			revision,
+			records: [],
+			complete: false,
+			deleted: true,
+			metadata: current?.metadata,
+			staleRevision: undefined
+		});
+		this.#changedDependencies.add(indexDependency(key));
+		this.#dirty = true;
+		return true;
+	}
+
+	#transaction<T>(update: () => T): T {
+		const outermost = this.#transactionDepth === 0;
+		const backup = outermost ? this.#backup() : undefined;
+		if (outermost) this.#transactionLifecycleIndexes = new Set();
+		this.#transactionDepth += 1;
+		let result: T;
+		try {
+			result = update();
+		} catch (error) {
+			this.#transactionDepth -= 1;
+			if (outermost && backup) {
+				this.#restoreBackup(backup);
+				this.#dirty = false;
+				this.#transactionLifecycleIndexes = new Set();
+			}
+			throw error;
+		}
+		this.#transactionDepth -= 1;
+		if (outermost) {
+			const shouldFlush = this.#dirty;
+			const changedDependencies = this.#changedDependencies;
+			this.#dirty = false;
+			this.#changedDependencies = new Set();
+			this.#transactionLifecycleIndexes = new Set();
+			if (shouldFlush) this.#flushWatchers(changedDependencies);
+		}
+		return result;
+	}
+
+	#flushWatchers(changedDependencies: ReadonlySet<string>): void {
+		const errors: unknown[] = [];
+		for (const watcher of this.#watchers) {
+			if (!dependenciesChanged(watcher.dependencies, changedDependencies)) continue;
+			try {
+				const { value: next, dependencies } = this.#select(watcher.selector);
+				watcher.dependencies = dependencies;
+				if (deepEqual(next, watcher.value)) continue;
+				const previous = watcher.value;
+				watcher.value = next;
+				watcher.listener(next, previous);
+			} catch (error) {
+				errors.push(error);
+			}
+		}
+		if (errors.length > 0) {
+			reportSafely(
+				this.#reportWatcherError,
+				new AggregateError(
+					errors,
+					'cache transaction committed, but watcher delivery failed'
+				)
+			);
+		}
+	}
+
+	#backup(): EngineBackup {
+		const backup = structuredClone({
+			records: this.#records,
+			indexes: this.#indexes,
+			layers: this.#layers,
+			derivedIndexOperations: this.#derivedIndexOperations,
+			confirmedFloors: this.#confirmedFloors,
+			retained: this.#retained,
+			nextLayerSequence: this.#nextLayerSequence,
+			changedDependencies: new Set<string>()
+		});
+		backup.changedDependencies = new Set(this.#changedDependencies);
+		return backup;
+	}
+
+	#restoreBackup(backup: EngineBackup): void {
+		this.#records = backup.records;
+		this.#indexes = backup.indexes;
+		this.#layers = backup.layers;
+		this.#derivedIndexOperations = backup.derivedIndexOperations;
+		this.#confirmedFloors = backup.confirmedFloors;
+		this.#retained = backup.retained;
+		this.#nextLayerSequence = backup.nextLayerSequence;
+		this.#changedDependencies = new Set(backup.changedDependencies);
+	}
+}
diff --git a/js/src/internal/cache-engine/errors.ts b/js/src/internal/cache-engine/errors.ts
new file mode 100644
index 00000000..9ff7271e
--- /dev/null
+++ b/js/src/internal/cache-engine/errors.ts
@@ -0,0 +1,11 @@
+export class CacheRevisionConflictError extends Error {
+	readonly dependency: string;
+	readonly revision: string;
+
+	constructor(dependency: string, revision: bigint) {
+		super(`conflicting cache values at revision ${revision} for ${dependency}`);
+		this.name = 'CacheRevisionConflictError';
+		this.dependency = dependency;
+		this.revision = revision.toString(10);
+	}
+}
diff --git a/js/src/internal/cache-engine/helpers.ts b/js/src/internal/cache-engine/helpers.ts
new file mode 100644
index 00000000..6553c248
--- /dev/null
+++ b/js/src/internal/cache-engine/helpers.ts
@@ -0,0 +1,670 @@
+import type {
+	CacheEngineSnapshot,
+	CacheIndexCoverage,
+	CacheIndexMetadata,
+	CacheValue,
+	DerivedIndexMutation,
+	DerivedIndexOperation,
+	DerivedIndexReconciler,
+	IndexKey,
+	OptimisticLayerView,
+	OverlayOperation,
+	RecordKey,
+	RecordLink,
+	Revision,
+	StoredField,
+	StoredIndex,
+	StoredRecord,
+	VisibleRecord
+} from './types.js';
+
+import { assertName } from '../../lib/assert-name.js';
+import { deepEqual } from '../../lib/deep-equal.js';
+import { freezeRecord } from '../../lib/freeze-record.js';
+import { reportSafely, reportUnhandledError } from '../../lib/report.js';
+
+export function parseSnapshot(snapshot: CacheEngineSnapshot): {
+	records: Map<RecordKey, StoredRecord>;
+	indexes: Map<IndexKey, StoredIndex>;
+} {
+	if (!snapshot || snapshot.version !== 1) throw new TypeError('unsupported cache snapshot');
+	if (!Array.isArray(snapshot.records) || !Array.isArray(snapshot.indexes)) {
+		throw new TypeError('invalid cache snapshot collections');
+	}
+	const records = new Map<RecordKey, StoredRecord>();
+	for (const input of snapshot.records) {
+		validateRecordKey(input.key);
+		if (records.has(input.key)) throw new TypeError(`duplicate snapshot record: ${input.key}`);
+		const revision = revisionToken(input.revision);
+		const incarnation = revisionToken(input.incarnation ?? input.revision);
+		const tombstoneRevision =
+			input.tombstoneRevision === undefined
+				? undefined
+				: revisionToken(input.tombstoneRevision);
+		if (tombstoneRevision !== undefined && tombstoneRevision !== revision) {
+			throw new TypeError(`invalid tombstone revision for ${input.key}`);
+		}
+		const fields = new Map<string, StoredField<CacheValue>>();
+		for (const [name, field] of Object.entries(input.fields) as Array<
+			[string, { readonly revision: string; readonly value: CacheValue }]
+		>) {
+			assertName(name, 'record field');
+			const fieldRevision = revisionToken(field.revision);
+			if (fieldRevision > revision) throw new TypeError(`field revision exceeds ${input.key}`);
+			fields.set(name, { revision: fieldRevision, value: cloneCacheValue(field.value) });
+		}
+		const links = new Map<string, StoredField<RecordLink>>();
+		for (const [name, link] of Object.entries(input.links) as Array<
+			[string, { readonly revision: string; readonly value: RecordLink }]
+		>) {
+			assertName(name, 'record link');
+			const linkRevision = revisionToken(link.revision);
+			if (linkRevision > revision) throw new TypeError(`link revision exceeds ${input.key}`);
+			links.set(name, { revision: linkRevision, value: cloneLink(link.value) });
+		}
+		if (tombstoneRevision !== undefined && (fields.size > 0 || links.size > 0)) {
+			throw new TypeError(`tombstone record contains live fields: ${input.key}`);
+		}
+		records.set(input.key, {
+			revision,
+			incarnation,
+			tombstoneRevision,
+			fields,
+			links
+		});
+	}
+
+	const indexes = new Map<IndexKey, StoredIndex>();
+	for (const input of snapshot.indexes) {
+		validateIndexWrite(input);
+		if (indexes.has(input.key)) throw new TypeError(`duplicate snapshot index: ${input.key}`);
+		validateRecordKeys(input.records);
+		const revision = revisionToken(input.revision);
+		const staleRevision =
+			input.staleRevision === undefined
+				? undefined
+				: revisionToken(input.staleRevision);
+		if (staleRevision !== undefined && staleRevision < revision) {
+			throw new TypeError(`stale index revision precedes its snapshot: ${input.key}`);
+		}
+		indexes.set(input.key, {
+			revision,
+			staleRevision,
+			records: [...input.records],
+			complete: Boolean(input.complete),
+			deleted: Boolean(input.deleted),
+			metadata:
+				input.metadata === undefined ? undefined : cloneIndexMetadata(input.metadata)
+		});
+	}
+	return { records, indexes };
+}
+
+export function runDerivedIndexReconciler(
+	reconciler: DerivedIndexReconciler,
+	confirmed: CacheEngineSnapshot,
+	layers: readonly OptimisticLayerView[]
+): readonly DerivedIndexMutation[] {
+	const result = reconciler(confirmed, Object.freeze([...layers]));
+	assertSynchronousResult(result, 'derived index reconciler');
+	if (!Array.isArray(result)) {
+		throw new TypeError('derived index reconciler must return an array');
+	}
+	return result;
+}
+
+export function cloneDerivedIndexOperations(
+	input: readonly DerivedIndexMutation[]
+): readonly DerivedIndexOperation[] {
+	const operations: DerivedIndexOperation[] = [];
+	const keys = new Set<IndexKey>();
+	for (const [index, value] of input.entries()) {
+		const path = `derived index mutation ${index}`;
+		if (
+			value === null ||
+			typeof value !== 'object' ||
+			Array.isArray(value) ||
+			(Object.getPrototypeOf(value) !== Object.prototype &&
+				Object.getPrototypeOf(value) !== null)
+		) {
+			throw new TypeError(`${path} must be a plain object`);
+		}
+		if (value.kind === 'write') {
+			assertExactKeys(value, ['kind', 'write'], path);
+			const write = value.write;
+			if (
+				write === null ||
+				typeof write !== 'object' ||
+				Array.isArray(write) ||
+				(Object.getPrototypeOf(write) !== Object.prototype &&
+					Object.getPrototypeOf(write) !== null)
+			) {
+				throw new TypeError(`${path}.write must be a plain object`);
+			}
+			assertExactKeys(
+				write as unknown as Record<string, unknown>,
+				['key', 'records', 'complete', 'metadata'],
+				`${path}.write`,
+				['key', 'records']
+			);
+			validateIndexWrite(write);
+			if (
+				write.complete !== undefined &&
+				typeof write.complete !== 'boolean'
+			) {
+				throw new TypeError(`${path}.write.complete must be a boolean`);
+			}
+			if (keys.has(write.key)) {
+				throw new TypeError(`duplicate derived index mutation: ${write.key}`);
+			}
+			keys.add(write.key);
+			operations.push(
+				Object.freeze({
+					kind: 'write-index' as const,
+					write: Object.freeze({
+						key: write.key,
+						records: Object.freeze([...write.records]),
+						complete: write.complete ?? false,
+						...(write.metadata === undefined
+							? {}
+							: { metadata: cloneIndexMetadata(write.metadata) })
+					})
+				})
+			);
+			continue;
+		}
+		if (value.kind === 'stale') {
+			assertExactKeys(value, ['kind', 'key', 'reason'], path);
+			assertName(value.key, `${path} key`);
+			assertName(value.reason, `${path} reason`);
+			if (keys.has(value.key)) {
+				throw new TypeError(`duplicate derived index mutation: ${value.key}`);
+			}
+			keys.add(value.key);
+			operations.push(
+				Object.freeze({
+					kind: 'mark-index-stale' as const,
+					key: value.key,
+					reason: value.reason
+				})
+			);
+			continue;
+		}
+		if (value.kind === 'delete') {
+			assertExactKeys(value, ['kind', 'key'], path);
+			assertName(value.key, `${path} key`);
+			if (keys.has(value.key)) {
+				throw new TypeError(`duplicate derived index mutation: ${value.key}`);
+			}
+			keys.add(value.key);
+			operations.push(
+				Object.freeze({ kind: 'delete-index' as const, key: value.key })
+			);
+			continue;
+		}
+		throw new TypeError(`${path} has unsupported kind`);
+	}
+	return Object.freeze(
+		operations.sort((left, right) =>
+			derivedIndexOperationKey(left).localeCompare(
+				derivedIndexOperationKey(right)
+			)
+		)
+	);
+}
+
+export function derivedIndexKeys(
+	operations: readonly DerivedIndexOperation[]
+): readonly IndexKey[] {
+	return Object.freeze(
+		[...new Set(operations.map(derivedIndexOperationKey))].sort()
+	);
+}
+
+export function derivedIndexOperationKey(
+	operation: DerivedIndexOperation
+): IndexKey {
+	return operation.kind === 'write-index'
+		? operation.write.key
+		: operation.key;
+}
+
+export function assertExactKeys(
+	value: Record<string, unknown>,
+	allowed: readonly string[],
+	description: string,
+	required: readonly string[] = allowed
+): void {
+	const allowedKeys = new Set(allowed);
+	for (const key of Object.keys(value)) {
+		if (!allowedKeys.has(key)) {
+			throw new TypeError(`${description} contains unknown field ${key}`);
+		}
+	}
+	for (const key of required) {
+		if (!Object.prototype.hasOwnProperty.call(value, key)) {
+			throw new TypeError(`${description} is missing field ${key}`);
+		}
+	}
+}
+
+export function operationDependencies(operation: OverlayOperation): readonly string[] {
+	if (operation.kind === 'write-record') {
+		return [
+			recordSeenDependency(operation.write.key),
+			...Object.keys(operation.write.fields ?? {}).map((name) =>
+				recordFieldDependency(operation.write.key, `field:${name}`)
+			),
+			...Object.keys(operation.write.links ?? {}).map((name) =>
+				recordFieldDependency(operation.write.key, `link:${name}`)
+			)
+		];
+	}
+	if (operation.kind === 'tombstone-record') {
+		return [recordSeenDependency(operation.key), recordWildcardDependency(operation.key)];
+	}
+	return [indexDependency(operation.kind === 'write-index' ? operation.write.key : operation.key)];
+}
+
+export function recordSeenDependency(key: RecordKey): string {
+	return JSON.stringify(['record-seen', key]);
+}
+
+export function recordWildcardDependency(key: RecordKey): string {
+	return JSON.stringify(['record', key, '*']);
+}
+
+export function recordFieldDependency(key: RecordKey, field: string): string {
+	return JSON.stringify(['record', key, field]);
+}
+
+export function indexDependency(key: IndexKey): string {
+	return JSON.stringify(['index', key]);
+}
+
+export function dependenciesChanged(
+	dependencies: ReadonlySet<string>,
+	changed: ReadonlySet<string>
+): boolean {
+	if (changed.size === 0 || changed.has('*')) return true;
+	for (const dependency of dependencies) {
+		if (changed.has(dependency)) return true;
+	}
+	return false;
+}
+
+export function emptyVisibleRecord(): VisibleRecord {
+	return {
+		revision: 0n,
+		incarnation: 0n,
+		tombstoned: false,
+		fields: new Map(),
+		links: new Map()
+	};
+}
+
+export function isVisibleRecordLive(record: VisibleRecord | undefined): boolean {
+	return record !== undefined && !record.tombstoned;
+}
+
+export function validateRecordKey(key: RecordKey): void {
+	assertName(key, 'record key');
+}
+
+export function validateIndexWrite(write: {
+	key: IndexKey;
+	records: readonly RecordKey[];
+	metadata?: CacheIndexMetadata;
+}): void {
+	assertName(write.key, 'index key');
+	if (!Array.isArray(write.records)) throw new TypeError('index records must be an array');
+	validateRecordKeys(write.records);
+	if ('metadata' in write && write.metadata !== undefined) {
+		const metadata = cloneIndexMetadata(write.metadata);
+		const expectedKey = cacheIndexKey({
+			...(metadata.parent === undefined ? {} : { parent: metadata.parent }),
+			field: metadata.field,
+			arguments: metadata.arguments
+		});
+		if (write.key !== expectedKey) {
+			throw new TypeError(`index key does not match its metadata: expected ${expectedKey}`);
+		}
+	}
+}
+
+export function indexMetadataWithoutStaleReason(
+	metadata: CacheIndexMetadata | undefined
+): Omit<CacheIndexMetadata, 'staleReason'> | undefined {
+	if (metadata === undefined) return undefined;
+	const { staleReason: _staleReason, ...rest } = metadata;
+	return rest;
+}
+
+export function isOrderedSubsequence(
+	known: readonly RecordKey[],
+	complete: readonly RecordKey[]
+): boolean {
+	let knownIndex = 0;
+	for (const key of complete) {
+		if (key === known[knownIndex]) knownIndex += 1;
+	}
+	return knownIndex === known.length;
+}
+
+export function refinementMetadataCompatible(
+	current: CacheIndexMetadata | undefined,
+	next: CacheIndexMetadata | undefined
+): boolean {
+	if (current === undefined || next === undefined) return current === next;
+	return deepEqual(refinementMetadataIdentity(current), refinementMetadataIdentity(next));
+}
+
+export function refinementMetadataIdentity(metadata: CacheIndexMetadata): unknown {
+	return {
+		parent: metadata.parent,
+		parentRevision: metadata.parentRevision,
+		parentIncarnation: metadata.parentIncarnation,
+		field: metadata.field,
+		arguments: metadata.arguments,
+		dependencies: metadata.dependencies,
+		nullValue: metadata.nullValue,
+		coverage: coverageRequestIdentity(metadata.coverage)
+	};
+}
+
+export function coverageRequestIdentity(coverage: CacheIndexCoverage): unknown {
+	if (coverage.kind === 'complete' || coverage.kind === 'unknown') {
+		return { kind: coverage.kind };
+	}
+	if (coverage.kind === 'offset') {
+		return { kind: coverage.kind, offset: coverage.offset, limit: coverage.limit };
+	}
+	return {
+		kind: coverage.kind,
+		after: coverage.after,
+		before: coverage.before,
+		first: coverage.first,
+		last: coverage.last
+	};
+}
+
+export function cloneIndexMetadata(metadata: CacheIndexMetadata): CacheIndexMetadata {
+	if (!metadata || typeof metadata !== 'object') {
+		throw new TypeError('index metadata must be an object');
+	}
+	assertName(metadata.field, 'index field');
+	if (metadata.parent !== undefined) validateRecordKey(metadata.parent);
+	if (metadata.parentRevision !== undefined) revisionToken(metadata.parentRevision);
+	if (metadata.parentIncarnation !== undefined) revisionToken(metadata.parentIncarnation);
+	const argumentsValue = cloneCacheValue(metadata.arguments);
+	if (
+		argumentsValue === null ||
+		Array.isArray(argumentsValue) ||
+		typeof argumentsValue !== 'object'
+	) {
+		throw new TypeError('index arguments must be a plain object');
+	}
+	if (!Array.isArray(metadata.dependencies)) {
+		throw new TypeError('index dependencies must be an array');
+	}
+	const dependencies = [...metadata.dependencies];
+	const seen = new Set<string>();
+	for (const dependency of dependencies) {
+		assertName(dependency, 'index dependency');
+		if (seen.has(dependency)) {
+			throw new TypeError(`duplicate index dependency: ${dependency}`);
+		}
+		seen.add(dependency);
+	}
+	if (metadata.staleReason !== undefined) {
+		assertName(metadata.staleReason, 'index stale reason');
+	}
+	if (metadata.nullValue !== undefined && typeof metadata.nullValue !== 'boolean') {
+		throw new TypeError('index nullValue must be a boolean');
+	}
+
+	const coverage = cloneIndexCoverage(metadata.coverage);
+	return Object.freeze({
+		...(metadata.parent === undefined ? {} : { parent: metadata.parent }),
+		...(metadata.parentRevision === undefined
+			? {}
+			: { parentRevision: metadata.parentRevision }),
+		...(metadata.parentIncarnation === undefined
+			? {}
+			: { parentIncarnation: metadata.parentIncarnation }),
+		field: metadata.field,
+		arguments: argumentsValue as Readonly<Record<string, CacheValue>>,
+		coverage,
+		dependencies: Object.freeze(dependencies),
+		...(metadata.staleReason === undefined
+			? {}
+			: { staleReason: metadata.staleReason }),
+		...(metadata.nullValue === undefined ? {} : { nullValue: metadata.nullValue })
+	});
+}
+
+export function cloneIndexCoverage(coverage: CacheIndexCoverage): CacheIndexCoverage {
+	if (!coverage || typeof coverage !== 'object') {
+		throw new TypeError('index coverage must be an object');
+	}
+	if (coverage.kind === 'complete' || coverage.kind === 'unknown') {
+		return Object.freeze({ kind: coverage.kind });
+	}
+	if (coverage.kind === 'offset') {
+		assertNonNegativeSafeInteger(coverage.offset, 'offset coverage offset');
+		if (coverage.limit !== undefined) {
+			assertNonNegativeSafeInteger(coverage.limit, 'offset coverage limit');
+		}
+		if (coverage.returned !== undefined) {
+			assertNonNegativeSafeInteger(coverage.returned, 'offset coverage returned');
+		}
+		if (coverage.hasNext !== undefined && typeof coverage.hasNext !== 'boolean') {
+			throw new TypeError('offset coverage hasNext must be a boolean');
+		}
+		return Object.freeze({
+			kind: 'offset' as const,
+			offset: coverage.offset,
+			...(coverage.limit === undefined ? {} : { limit: coverage.limit }),
+			...(coverage.returned === undefined ? {} : { returned: coverage.returned }),
+			...(coverage.hasNext === undefined ? {} : { hasNext: coverage.hasNext })
+		});
+	}
+	if (coverage.kind === 'cursor') {
+		if (coverage.first !== undefined) {
+			assertNonNegativeSafeInteger(coverage.first, 'cursor coverage first');
+		}
+		if (coverage.last !== undefined) {
+			assertNonNegativeSafeInteger(coverage.last, 'cursor coverage last');
+		}
+		if (coverage.hasNext !== undefined && typeof coverage.hasNext !== 'boolean') {
+			throw new TypeError('cursor coverage hasNext must be a boolean');
+		}
+		if (
+			coverage.hasPrevious !== undefined &&
+			typeof coverage.hasPrevious !== 'boolean'
+		) {
+			throw new TypeError('cursor coverage hasPrevious must be a boolean');
+		}
+		return Object.freeze({
+			kind: 'cursor' as const,
+			...(coverage.after === undefined
+				? {}
+				: { after: cloneCacheValue(coverage.after) }),
+			...(coverage.before === undefined
+				? {}
+				: { before: cloneCacheValue(coverage.before) }),
+			...(coverage.first === undefined ? {} : { first: coverage.first }),
+			...(coverage.last === undefined ? {} : { last: coverage.last }),
+			...(coverage.start === undefined
+				? {}
+				: { start: cloneCacheValue(coverage.start) }),
+			...(coverage.end === undefined ? {} : { end: cloneCacheValue(coverage.end) }),
+			...(coverage.hasNext === undefined ? {} : { hasNext: coverage.hasNext }),
+			...(coverage.hasPrevious === undefined
+				? {}
+				: { hasPrevious: coverage.hasPrevious })
+		});
+	}
+	throw new TypeError('unsupported index coverage kind');
+}
+
+export function assertNonNegativeSafeInteger(value: number, description: string): void {
+	if (!Number.isSafeInteger(value) || value < 0) {
+		throw new TypeError(`${description} must be a non-negative safe integer`);
+	}
+}
+
+export function assertWriterActive(active: boolean): void {
+	if (!active) throw new Error('cache writer is no longer active');
+}
+
+export function assertSynchronousResult(result: unknown, description: string): void {
+	if (
+		result !== null &&
+		(typeof result === 'object' || typeof result === 'function') &&
+		typeof (result as { then?: unknown }).then === 'function'
+	) {
+		void Promise.resolve(result).catch(() => undefined);
+		throw new TypeError(`${description} must be synchronous`);
+	}
+}
+
+export function validateRecordKeys(keys: readonly RecordKey[]): void {
+	const seen = new Set<RecordKey>();
+	for (const key of keys) {
+		validateRecordKey(key);
+		if (seen.has(key)) throw new TypeError(`duplicate record in index: ${key}`);
+		seen.add(key);
+	}
+}
+
+export function revisionToken(value: Revision): bigint {
+	if (typeof value === 'bigint') {
+		if (value < 0n) throw new TypeError('revision must be an unsigned integer');
+		return value;
+	}
+	if (typeof value === 'number') {
+		if (!Number.isSafeInteger(value) || value < 0) {
+			throw new TypeError('numeric revision must be an unsigned safe integer');
+		}
+		return BigInt(value);
+	}
+	if (!/^(0|[1-9][0-9]*)$/.test(value)) {
+		throw new TypeError('string revision must be a canonical unsigned integer');
+	}
+	return BigInt(value);
+}
+
+export function compareRecordTuple(
+	leftIncarnation: bigint,
+	leftRevision: bigint,
+	rightIncarnation: bigint,
+	rightRevision: bigint
+): -1 | 0 | 1 {
+	if (leftIncarnation < rightIncarnation) return -1;
+	if (leftIncarnation > rightIncarnation) return 1;
+	if (leftRevision < rightRevision) return -1;
+	if (leftRevision > rightRevision) return 1;
+	return 0;
+}
+
+export function revisionString(value: bigint): string {
+	return value.toString(10);
+}
+
+export function cloneFields(
+	fields: Readonly<Record<string, CacheValue>> | undefined
+): Readonly<Record<string, CacheValue>> {
+	if (fields === undefined) return Object.freeze({});
+	return freezeRecord(
+		Object.entries(fields).map(([name, value]) => {
+			assertName(name, 'record field');
+			return [name, cloneCacheValue(value)];
+		})
+	);
+}
+
+export function cloneLinks(
+	links: Readonly<Record<string, RecordLink>> | undefined
+): Readonly<Record<string, RecordLink>> {
+	if (links === undefined) return Object.freeze({});
+	return freezeRecord(
+		Object.entries(links).map(([name, value]) => {
+			assertName(name, 'record link');
+			return [name, cloneLink(value)];
+		})
+	);
+}
+
+export function cloneLink(value: RecordLink): RecordLink {
+	if (value === null) return null;
+	if (typeof value === 'string') {
+		validateRecordKey(value);
+		return value;
+	}
+	if (!Array.isArray(value)) throw new TypeError('record link must be a key, key array, or null');
+	validateRecordKeys(value);
+	return Object.freeze([...value]);
+}
+
+export function linkKeys(value: RecordLink): readonly RecordKey[] {
+	if (value === null) return [];
+	return typeof value === 'string' ? [value] : value;
+}
+
+export function cloneCacheValue(value: CacheValue, ancestors = new Set<object>()): CacheValue {
+	if (
+		value === null ||
+		typeof value === 'string' ||
+		typeof value === 'boolean' ||
+		typeof value === 'number'
+	) {
+		if (typeof value === 'number' && !Number.isFinite(value)) {
+			throw new TypeError('cache numbers must be finite');
+		}
+		return value;
+	}
+	if (typeof value !== 'object') {
+		throw new TypeError('cache fields must contain JSON-compatible values; omit absent fields');
+	}
+	if (ancestors.has(value)) throw new TypeError('cache fields must not contain cycles');
+	ancestors.add(value);
+	let cloned: CacheValue;
+	if (Array.isArray(value)) {
+		cloned = Object.freeze(value.map((entry) => cloneCacheValue(entry, ancestors)));
+	} else {
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) {
+			throw new TypeError('cache objects must be plain JSON objects');
+		}
+		cloned = freezeRecord(
+			Object.entries(value).map(([key, entry]) => [key, cloneCacheValue(entry, ancestors)])
+		);
+	}
+	ancestors.delete(value);
+	return cloned;
+}
+
+export function canonicalValue(value: CacheValue): string {
+	if (value === null || typeof value !== 'object') return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(canonicalValue).join(',')}]`;
+	const record = value as Readonly<Record<string, CacheValue>>;
+	return `{${Object.keys(record)
+		.sort()
+		.map((key) => `${JSON.stringify(key)}:${canonicalValue(record[key]!)}`)
+		.join(',')}}`;
+}
+
+export function cacheIndexKey(input: {
+	parent?: RecordKey;
+	field: string;
+	arguments?: Readonly<Record<string, CacheValue>>;
+}): IndexKey {
+	assertName(input.field, 'index field');
+	if (input.parent !== undefined) validateRecordKey(input.parent);
+	const argumentsValue = cloneCacheValue(input.arguments ?? {});
+	return `${input.parent ?? '$root'}.${input.field}(${canonicalValue(argumentsValue)})`;
+}
+
+export { assertName, deepEqual, freezeRecord, reportSafely };
+export const reportUnhandledWatcherError = reportUnhandledError;
diff --git a/js/src/internal/cache-engine/index.ts b/js/src/internal/cache-engine/index.ts
new file mode 100644
index 00000000..bfb7632e
--- /dev/null
+++ b/js/src/internal/cache-engine/index.ts
@@ -0,0 +1,34 @@
+export type {
+	BaseCacheWriter,
+	BaseRecordClock,
+	CacheEngine,
+	CacheEngineOptions,
+	CacheEngineSnapshot,
+	CacheIndex,
+	CacheIndexCoverage,
+	CacheIndexMetadata,
+	CacheListener,
+	CachePresence,
+	CacheReader,
+	CacheSelector,
+	CacheValue,
+	DerivedIndexMutation,
+	DerivedIndexReconciler,
+	IndexKey,
+	IndexWrite,
+	OptimisticCacheWriter,
+	OptimisticIndexWrite,
+	OptimisticLayerContext,
+	OptimisticLayerState,
+	OptimisticLayerView,
+	OptimisticRecordWrite,
+	RecordKey,
+	RecordLink,
+	RecordWrite,
+	Revision,
+	SparseRecord,
+	SparseRecordMeta,
+	WatchOptions
+} from './types.js';
+export { CacheRevisionConflictError } from './errors.js';
+export { cacheIndexKey, createCacheEngine } from './create.js';
diff --git a/js/src/internal/cache-engine/types.ts b/js/src/internal/cache-engine/types.ts
new file mode 100644
index 00000000..3cbbba8f
--- /dev/null
+++ b/js/src/internal/cache-engine/types.ts
@@ -0,0 +1,341 @@
+export type Revision = number | string | bigint;
+export type RecordKey = string;
+export type IndexKey = string;
+
+export type CacheValue =
+	| null
+	| boolean
+	| number
+	| string
+	| readonly CacheValue[]
+	| { readonly [key: string]: CacheValue };
+
+export type RecordLink = RecordKey | readonly RecordKey[] | null;
+
+export type RecordWrite = {
+	key: RecordKey;
+	revision: Revision;
+	/** Stable incarnation fence. Defaults to the first live revision. */
+	incarnation?: Revision;
+	/** Omitted fields stay absent. A present `null` remains present. */
+	fields?: Readonly<Record<string, CacheValue>>;
+	/** Relationship identities are stored separately from scalar/JSON fields. */
+	links?: Readonly<Record<string, RecordLink>>;
+};
+
+export type OptimisticRecordWrite = Omit<RecordWrite, 'revision' | 'incarnation'>;
+
+export type CacheIndexCoverage =
+	| { readonly kind: 'complete' }
+	| { readonly kind: 'unknown' }
+	| {
+			readonly kind: 'offset';
+			readonly offset: number;
+			readonly limit?: number;
+			readonly returned?: number;
+			readonly hasNext?: boolean;
+	  }
+	| {
+			readonly kind: 'cursor';
+			readonly after?: CacheValue;
+			readonly before?: CacheValue;
+			readonly first?: number;
+			readonly last?: number;
+			readonly start?: CacheValue;
+			readonly end?: CacheValue;
+			readonly hasNext?: boolean;
+			readonly hasPrevious?: boolean;
+	  };
+
+export type CacheIndexMetadata = {
+	readonly parent?: RecordKey;
+	/** Parent row clock claimed by the response that produced this relationship. */
+	readonly parentRevision?: string;
+	/** Parent lifecycle fence stamped by the engine. */
+	readonly parentIncarnation?: string;
+	readonly field: string;
+	readonly arguments: Readonly<Record<string, CacheValue>>;
+	readonly coverage: CacheIndexCoverage;
+	readonly dependencies: readonly string[];
+	readonly staleReason?: string;
+	/** Distinguishes a present GraphQL `null` from an empty collection. */
+	readonly nullValue?: boolean;
+};
+
+export type IndexWrite = {
+	key: IndexKey;
+	revision: Revision;
+	records: readonly RecordKey[];
+	complete?: boolean;
+	metadata?: CacheIndexMetadata;
+};
+
+export type OptimisticIndexWrite = Omit<IndexWrite, 'revision'>;
+
+export type SparseRecord = {
+	readonly key: RecordKey;
+	readonly revision: string;
+	readonly incarnation: string;
+	readonly fields: Readonly<Record<string, CacheValue>>;
+	readonly links: Readonly<Record<string, RecordLink>>;
+};
+
+export type CacheIndex = {
+	readonly key: IndexKey;
+	readonly revision: string;
+	readonly staleRevision?: string;
+	readonly records: readonly RecordKey[];
+	readonly complete: boolean;
+	readonly metadata?: CacheIndexMetadata;
+};
+
+export type CachePresence<T> =
+	| { readonly present: false }
+	| { readonly present: true; readonly value: T };
+
+export type SparseRecordMeta = {
+	readonly key: RecordKey;
+	readonly incarnation: string;
+};
+
+export type BaseRecordClock = {
+	readonly revision: string;
+	readonly incarnation: string;
+	readonly tombstoned: boolean;
+};
+
+/** Raised when one source revision claims two different values. */
+
+export interface CacheReader {
+	recordMeta(key: RecordKey): SparseRecordMeta | undefined;
+	field(key: RecordKey, name: string): CachePresence<CacheValue>;
+	link(key: RecordKey, name: string): CachePresence<RecordLink>;
+	record(key: RecordKey): SparseRecord | undefined;
+	index(key: IndexKey): CacheIndex | undefined;
+}
+
+export interface BaseCacheWriter {
+	recordClock(key: RecordKey): BaseRecordClock | undefined;
+	writeRecord(write: RecordWrite): boolean;
+	tombstoneRecord(key: RecordKey, revision: Revision, incarnation?: Revision): boolean;
+	/** Drop uncertified fields while preserving higher protocol clocks externally. */
+	discardRecord(key: RecordKey): boolean;
+	writeIndex(write: IndexWrite): boolean;
+	markIndexStale(key: IndexKey, reason: string, revision?: Revision): boolean;
+	deleteIndex(key: IndexKey, revision: Revision): boolean;
+}
+
+export interface OptimisticCacheWriter {
+	writeRecord(write: OptimisticRecordWrite): void;
+	tombstoneRecord(key: RecordKey): void;
+	writeIndex(write: OptimisticIndexWrite): void;
+	deleteIndex(key: IndexKey): void;
+}
+
+export type CacheSelector<T> = (reader: CacheReader) => T;
+export type CacheListener<T> = (value: T, previous: T | undefined) => void;
+
+export type WatchOptions = {
+	immediate?: boolean;
+};
+
+export type CacheEngineOptions = {
+	/** Observer failures are reported after every eligible watcher was delivered. */
+	onWatcherError?: (error: AggregateError) => void;
+};
+
+export type OptimisticLayerState = 'optimistic' | 'accepted';
+
+export type CacheEngineSnapshot = {
+	readonly version: 1;
+	readonly records: readonly {
+		readonly key: RecordKey;
+		readonly revision: string;
+		readonly incarnation?: string;
+		readonly tombstoneRevision?: string;
+		readonly fields: Readonly<
+			Record<string, { readonly revision: string; readonly value: CacheValue }>
+		>;
+		readonly links: Readonly<
+			Record<string, { readonly revision: string; readonly value: RecordLink }>
+		>;
+	}[];
+	readonly indexes: readonly {
+		readonly key: IndexKey;
+		readonly revision: string;
+		readonly staleRevision?: string;
+		readonly records: readonly RecordKey[];
+		readonly complete: boolean;
+		readonly deleted: boolean;
+		readonly metadata?: CacheIndexMetadata;
+	}[];
+};
+
+/**
+ * Opaque, detached JSON context owned by the replica and carried with one
+ * optimistic layer. The cache engine never interprets it.
+ */
+export type OptimisticLayerContext = CacheValue;
+
+export type OptimisticLayerView = {
+	readonly id: string;
+	readonly sequence: number;
+	readonly state: OptimisticLayerState;
+	readonly context?: OptimisticLayerContext;
+};
+
+export type DerivedIndexMutation =
+	| {
+			readonly kind: 'write';
+			readonly write: OptimisticIndexWrite;
+	  }
+	| {
+			readonly kind: 'stale';
+			readonly key: IndexKey;
+			readonly reason: string;
+	  }
+	| {
+			readonly kind: 'delete';
+			readonly key: IndexKey;
+	  };
+
+/**
+ * Rebuild the complete derived-index overlay from confirmed state and the
+ * ordered semantic contexts of every surviving optimistic layer.
+ */
+export type DerivedIndexReconciler = (
+	confirmed: CacheEngineSnapshot,
+	layers: readonly OptimisticLayerView[]
+) => readonly DerivedIndexMutation[];
+
+export interface CacheEngine {
+	read<T>(selector: CacheSelector<T>): T;
+	/**
+	 * Read only the authoritative base graph, excluding optimistic records and
+	 * their derived-index overlay.
+	 */
+	readConfirmed<T>(selector: CacheSelector<T>): T;
+	/**
+	 * Return the authoritative write fence for requested base indexes.
+	 * Deleted sentinels remain visible here even though CacheReader hides them.
+	 */
+	confirmedIndexFences(
+		keys: readonly IndexKey[]
+	): ReadonlyMap<IndexKey, string>;
+	watch<T>(
+		selector: CacheSelector<T>,
+		listener: CacheListener<T>,
+		options?: WatchOptions
+	): () => void;
+	batch<T>(update: (writer: BaseCacheWriter) => T): T;
+	createOptimisticLayer(
+		id: string,
+		update: (writer: OptimisticCacheWriter) => void,
+		context?: OptimisticLayerContext
+	): void;
+	setDerivedIndexReconciler(reconciler: DerivedIndexReconciler | undefined): void;
+	markOptimisticLayerAccepted(id: string): boolean;
+	confirmOptimisticLayer<T>(id: string, update: (writer: BaseCacheWriter) => T): T;
+	confirmOptimisticLayers<T>(
+		ids: readonly string[],
+		update: (writer: BaseCacheWriter) => T
+	): T;
+	rejectOptimisticLayer(id: string): boolean;
+	optimisticLayerState(id: string): OptimisticLayerState | undefined;
+	extract(): CacheEngineSnapshot;
+	restore(snapshot: CacheEngineSnapshot): void;
+	/**
+	 * Replace only confirmed base state while preserving local optimistic layers,
+	 * their acceptance state, and causal sequencing floors.
+	 */
+	restoreConfirmed(snapshot: CacheEngineSnapshot): void;
+	/**
+	 * Drop incomparable/reset base indexes without assigning them a fabricated
+	 * revision. Pending optimistic overlays remain layered above the new gap.
+	 */
+	discardIndexes(keys: readonly IndexKey[]): void;
+	retain(key: RecordKey): void;
+	release(key: RecordKey): void;
+	gc(): readonly RecordKey[];
+}
+
+export type StoredField<T> = {
+	revision: bigint;
+	value: T;
+};
+
+export type StoredRecord = {
+	revision: bigint;
+	incarnation: bigint;
+	tombstoneRevision?: bigint;
+	fields: Map<string, StoredField<CacheValue>>;
+	links: Map<string, StoredField<RecordLink>>;
+};
+
+export type StoredIndex = {
+	revision: bigint;
+	staleRevision?: bigint;
+	records: RecordKey[];
+	complete: boolean;
+	deleted: boolean;
+	metadata?: CacheIndexMetadata;
+};
+
+export type OverlayOperation =
+	| { kind: 'write-record'; write: OptimisticRecordWrite }
+	| { kind: 'tombstone-record'; key: RecordKey }
+	| { kind: 'write-index'; write: OptimisticIndexWrite }
+	| { kind: 'delete-index'; key: IndexKey };
+
+export type OptimisticLayer = {
+	id: string;
+	sequence: number;
+	state: OptimisticLayerState;
+	operations: OverlayOperation[];
+	context?: OptimisticLayerContext;
+};
+
+export type DerivedIndexOperation =
+	| { kind: 'write-index'; write: OptimisticIndexWrite }
+	| { kind: 'mark-index-stale'; key: IndexKey; reason: string }
+	| { kind: 'delete-index'; key: IndexKey };
+
+export type VisibleRecord = {
+	revision: bigint;
+	incarnation: bigint;
+	tombstoned: boolean;
+	fields: Map<string, CacheValue>;
+	links: Map<string, RecordLink>;
+};
+
+export type VisibleIndex = {
+	revision: bigint;
+	staleRevision?: bigint;
+	records: RecordKey[];
+	complete: boolean;
+	deleted: boolean;
+	metadata?: CacheIndexMetadata;
+};
+
+export type MaterializedCacheGraph = {
+	records: Map<RecordKey, VisibleRecord>;
+	indexes: Map<IndexKey, VisibleIndex>;
+};
+
+export type Watcher<T = unknown> = {
+	selector: CacheSelector<T>;
+	listener: CacheListener<T>;
+	value: T;
+	dependencies: Set<string>;
+};
+
+export type EngineBackup = {
+	records: Map<RecordKey, StoredRecord>;
+	indexes: Map<IndexKey, StoredIndex>;
+	layers: OptimisticLayer[];
+	derivedIndexOperations: DerivedIndexOperation[];
+	confirmedFloors: Map<string, number>;
+	retained: Map<RecordKey, number>;
+	nextLayerSequence: number;
+	changedDependencies: Set<string>;
+};
diff --git a/js/src/lib/assert-name.ts b/js/src/lib/assert-name.ts
new file mode 100644
index 00000000..ac7d1d05
--- /dev/null
+++ b/js/src/lib/assert-name.ts
@@ -0,0 +1,9 @@
+/** Require a non-empty string (field names, layer ids, etc.). */
+export function assertName(
+	value: unknown,
+	description: string
+): asserts value is string {
+	if (typeof value !== 'string' || value.length === 0) {
+		throw new TypeError(`${description} must be a non-empty string`);
+	}
+}
diff --git a/js/src/lib/compare-code-units.ts b/js/src/lib/compare-code-units.ts
new file mode 100644
index 00000000..d4b560b8
--- /dev/null
+++ b/js/src/lib/compare-code-units.ts
@@ -0,0 +1,4 @@
+/** Lexicographic compare using UTF-16 code units (JS string order). */
+export function compareCodeUnits(left: string, right: string): number {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
diff --git a/js/src/lib/deep-equal.ts b/js/src/lib/deep-equal.ts
new file mode 100644
index 00000000..ec8f3584
--- /dev/null
+++ b/js/src/lib/deep-equal.ts
@@ -0,0 +1,28 @@
+/** Structural equality for JSON-like values (objects, arrays, primitives). */
+export function deepEqual(left: unknown, right: unknown): boolean {
+	if (Object.is(left, right)) return true;
+	if (typeof left !== typeof right || left === null || right === null) return false;
+	if (typeof left !== 'object' || typeof right !== 'object') return false;
+	if (Array.isArray(left) || Array.isArray(right)) {
+		if (
+			!Array.isArray(left) ||
+			!Array.isArray(right) ||
+			left.length !== right.length
+		) {
+			return false;
+		}
+		return left.every((entry, index) => deepEqual(entry, right[index]));
+	}
+	const leftRecord = left as Readonly<Record<string, unknown>>;
+	const rightRecord = right as Readonly<Record<string, unknown>>;
+	const leftKeys = Object.keys(leftRecord);
+	const rightKeys = Object.keys(rightRecord);
+	return (
+		leftKeys.length === rightKeys.length &&
+		leftKeys.every(
+			(key) =>
+				Object.prototype.hasOwnProperty.call(rightRecord, key) &&
+				deepEqual(leftRecord[key], rightRecord[key])
+		)
+	);
+}
diff --git a/js/src/lib/freeze-record.ts b/js/src/lib/freeze-record.ts
new file mode 100644
index 00000000..2a8b752e
--- /dev/null
+++ b/js/src/lib/freeze-record.ts
@@ -0,0 +1,15 @@
+/** Build an immutable plain object from key/value pairs. */
+export function freezeRecord<T>(
+	entries: readonly (readonly [string, T])[]
+): Readonly<Record<string, T>> {
+	const result: Record<string, T> = {};
+	for (const [key, value] of entries) {
+		Object.defineProperty(result, key, {
+			value,
+			enumerable: true,
+			configurable: false,
+			writable: false
+		});
+	}
+	return Object.freeze(result);
+}
diff --git a/js/src/lib/index.ts b/js/src/lib/index.ts
new file mode 100644
index 00000000..1719e4c9
--- /dev/null
+++ b/js/src/lib/index.ts
@@ -0,0 +1,6 @@
+export { assertName } from './assert-name.js';
+export { compareCodeUnits } from './compare-code-units.js';
+export { deepEqual } from './deep-equal.js';
+export { freezeRecord } from './freeze-record.js';
+export { isPlainRecord } from './is-plain-record.js';
+export { reportSafely, reportUnhandledError } from './report.js';
diff --git a/js/src/lib/is-plain-record.ts b/js/src/lib/is-plain-record.ts
new file mode 100644
index 00000000..075d9280
--- /dev/null
+++ b/js/src/lib/is-plain-record.ts
@@ -0,0 +1,10 @@
+/** True for non-null objects that are not arrays (own enumerable bag). */
+export function isPlainRecord(
+	value: unknown
+): value is Record<string, unknown> {
+	if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+		return false;
+	}
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
diff --git a/js/src/lib/report.ts b/js/src/lib/report.ts
new file mode 100644
index 00000000..cca85856
--- /dev/null
+++ b/js/src/lib/report.ts
@@ -0,0 +1,30 @@
+/**
+ * Deliver an AggregateError to a user reporter without letting the reporter
+ * change success semantics of the surrounding operation.
+ */
+export function reportSafely(
+	reporter: (error: AggregateError) => void,
+	error: AggregateError,
+	failureMessage = 'error reporter failed'
+): void {
+	try {
+		reporter(error);
+	} catch (reporterError) {
+		queueMicrotask(() => {
+			throw new AggregateError([error, reporterError], failureMessage);
+		});
+	}
+}
+
+/** Best-effort delivery of an unhandled AggregateError to the host. */
+export function reportUnhandledError(error: AggregateError): void {
+	const reportError = (globalThis as { reportError?: (cause: unknown) => void })
+		.reportError;
+	if (typeof reportError === 'function') {
+		reportError(error);
+		return;
+	}
+	queueMicrotask(() => {
+		throw error;
+	});
+}
diff --git a/js/src/protocol.ts b/js/src/protocol.ts
new file mode 100644
index 00000000..e4eef2d0
--- /dev/null
+++ b/js/src/protocol.ts
@@ -0,0 +1,964 @@
+/**
+ * Versioned framework metadata carried in GraphQL's top-level
+ * `extensions.distributed` response envelope.
+ *
+ * Domain result objects never contain these values. Hidden identities and
+ * positions remain opaque strings: the JavaScript client compares or returns
+ * them, but never parses them as numbers or reconstructs server scopes.
+ */
+
+/** The only Distributed GraphQL protocol version understood by this package. */
+export const DISTRIBUTED_PROTOCOL_VERSION = 1 as const;
+
+declare const opaqueDistributedString: unique symbol;
+declare const distributedDecimalString: unique symbol;
+
+/** Server-owned identity/token whose contents must not be interpreted by clients. */
+export type DistributedOpaqueString = string & {
+	readonly [opaqueDistributedString]: true;
+};
+
+/** Canonical unsigned u64 decimal carried without JavaScript numeric coercion. */
+export type DistributedDecimalString = string & {
+	readonly [distributedDecimalString]: true;
+};
+
+export type DistributedCommandState =
+	| 'in_progress'
+	| 'accepted'
+	| 'accepted_pending_projection'
+	| 'projected'
+	| 'rejected'
+	| 'projection_failed'
+	| 'expired'
+	| 'unknown';
+
+export type DistributedCommandConsistency =
+	| 'accepted'
+	| 'fact'
+	| 'projected';
+
+/** Closed wire codecs for server-derived, client-visible trusted presets. */
+export type DistributedTrustedPresetCodec =
+	| 'string'
+	| 'string_unvalidated_timestamp'
+	| 'base64'
+	| 'boolean'
+	| 'int32'
+	| 'float64'
+	| 'json_number_precision_limited'
+	| 'json';
+
+/** JSON value accepted by the Distributed protocol parser. */
+export type DistributedProtocolValue =
+	| null
+	| boolean
+	| number
+	| string
+	| readonly DistributedProtocolValue[]
+	| { readonly [key: string]: DistributedProtocolValue };
+
+/**
+ * One server-derived value valid only under its containing envelope's exact
+ * authoritative cache scope.
+ */
+export type DistributedTrustedPreset = Readonly<{
+	name: string;
+	codec: DistributedTrustedPresetCodec;
+	value: DistributedProtocolValue;
+}>;
+
+/** One finite, server-resolved projection obligation for a command. */
+export type DistributedProjectionExpectation = Readonly<
+	Record<string, unknown> & {
+		projection: string;
+		model: string;
+		scopeToken: DistributedOpaqueString;
+	}
+>;
+
+/** Comparable record evidence within one exact opaque record scope. */
+export type DistributedRecordRevision = Readonly<
+	Record<string, unknown> & {
+		path?: readonly string[];
+		model: string;
+		scopeToken: DistributedOpaqueString;
+		incarnation: DistributedDecimalString;
+		revision: DistributedDecimalString;
+		tombstone: boolean;
+	}
+>;
+
+/** Exact observation of one command causation in one projection obligation. */
+export type DistributedProjectionObservation = Readonly<
+	Record<string, unknown> & {
+		causationId: DistributedOpaqueString;
+		projection: string;
+		model: string;
+		scopeToken: DistributedOpaqueString;
+	}
+>;
+
+/** Opaque resumable position for one named projection scope. */
+export type DistributedLiveCursor = Readonly<
+	Record<string, unknown> & {
+		projection: string;
+		position: DistributedDecimalString;
+		token: DistributedOpaqueString;
+	}
+>;
+
+/** Comparable checkpoint for one exact query-index projection member. */
+export type DistributedIndexRevision = Readonly<
+	Record<string, unknown> & {
+		projection: string;
+		scopeToken: DistributedOpaqueString;
+		position: DistributedDecimalString;
+		resume?: DistributedLiveCursor;
+	}
+>;
+
+/**
+ * Record and causal-index evidence for one exact operation instance.
+ *
+ * The GraphQL payload itself is the authoritative query snapshot. These flags
+ * describe whether the server could additionally prove every normalized record
+ * clock and expose a safely comparable projection vector. Row-filtered
+ * authorization commonly makes `indexesComparable` false without making the
+ * authorized payload partial.
+ */
+export type DistributedQuerySnapshot = Readonly<
+	Record<string, unknown> & {
+		scopeToken: DistributedOpaqueString;
+		recordsComplete: boolean;
+		indexesComparable: boolean;
+		records: readonly DistributedRecordRevision[];
+		indexes: readonly DistributedIndexRevision[];
+		observations: readonly DistributedProjectionObservation[];
+	}
+>;
+
+/** Per-frame decision about live support, reset, and resumable cursors. */
+export type DistributedLiveMetadata = Readonly<
+	Record<string, unknown> & {
+		supported: boolean;
+		reset: boolean;
+		cursors: readonly DistributedLiveCursor[];
+	}
+>;
+
+/** Private GraphQL request extension consumed by generated live operations. */
+export type DistributedLiveResumeExtensions = Readonly<{
+	distributed: Readonly<{
+		resume: Readonly<{
+			cursors: readonly DistributedLiveCursor[];
+		}>;
+	}>;
+}>;
+
+/** Durable receipt/status metadata for one idempotent command identity. */
+export type DistributedCommandMetadata = Readonly<
+	Record<string, unknown> & {
+		commandId: DistributedOpaqueString;
+		causationId: DistributedOpaqueString;
+		state: DistributedCommandState;
+		consistency: DistributedCommandConsistency;
+		expects: readonly DistributedProjectionExpectation[];
+		/** Defaults to an empty array when omitted by the compact wire format. */
+		observations: readonly DistributedProjectionObservation[];
+		/** Defaults to an empty array when omitted by the compact wire format. */
+		records: readonly DistributedRecordRevision[];
+	}
+>;
+
+/** Canonical contents of top-level `extensions.distributed`. */
+export type DistributedProtocolEnvelope = Readonly<
+	Record<string, unknown> & {
+		protocolVersion: typeof DISTRIBUTED_PROTOCOL_VERSION;
+		schemaHash: string;
+		cacheScope: DistributedOpaqueString;
+		operation?: string;
+		command?: DistributedCommandMetadata;
+		snapshot?: DistributedQuerySnapshot;
+		live?: DistributedLiveMetadata;
+		/** Defaults to an empty array when omitted by the compact wire format. */
+		trustedPresets: readonly DistributedTrustedPreset[];
+	}
+>;
+
+/** GraphQL top-level extensions with a validated Distributed envelope. */
+export type GraphqlResponseExtensions = Readonly<
+	Record<string, unknown> & {
+		distributed?: DistributedProtocolEnvelope;
+	}
+>;
+
+export type DistributedProtocolErrorCode =
+	| 'DISTRIBUTED_PROTOCOL_INVALID'
+	| 'DISTRIBUTED_PROTOCOL_VERSION_UNSUPPORTED';
+
+/** Safe parse failure that reports structure, never hidden server values. */
+export class DistributedProtocolError extends Error {
+	readonly code: DistributedProtocolErrorCode;
+	readonly path: string;
+
+	constructor(code: DistributedProtocolErrorCode, path: string) {
+		super(
+			code === 'DISTRIBUTED_PROTOCOL_VERSION_UNSUPPORTED'
+				? 'Unsupported Distributed GraphQL protocol version'
+				: `Invalid Distributed GraphQL protocol envelope at ${path}`
+		);
+		this.name = 'DistributedProtocolError';
+		this.code = code;
+		this.path = path;
+	}
+}
+
+const COMMAND_STATES = new Set<DistributedCommandState>([
+	'in_progress',
+	'accepted',
+	'accepted_pending_projection',
+	'projected',
+	'rejected',
+	'projection_failed',
+	'expired',
+	'unknown'
+]);
+
+const COMMAND_CONSISTENCIES = new Set<DistributedCommandConsistency>([
+	'accepted',
+	'fact',
+	'projected'
+]);
+
+const MAX_PUBLIC_NAME_LENGTH = 512;
+const MAX_OPAQUE_STRING_LENGTH = 16_384;
+const MAX_EVIDENCE_ITEMS = 4_096;
+const MAX_LIVE_RESUME_CURSORS = 64;
+const MAX_PATH_SEGMENTS = 256;
+const MAX_TRUSTED_PRESETS = 4_096;
+const MAX_TRUSTED_PRESET_NAME_LENGTH = 128;
+const MAX_TRUSTED_PRESET_VALUE_DEPTH = 64;
+const MAX_UNSIGNED_64 = '18446744073709551615';
+const MAX_SAFE_INTEGER = 9_007_199_254_740_991;
+const CANONICAL_BASE64 =
+	/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+/**
+ * Parse GraphQL's optional top-level `extensions` object.
+ *
+ * Non-Distributed extension keys are preserved. When `distributed` is present,
+ * its required version/scope/schema fields and known receipt/evidence fields are
+ * validated. A malformed or incompatible envelope throws
+ * {@link DistributedProtocolError}; transports convert that into a fail-closed
+ * GraphQL result/error rather than exposing the accompanying data as trusted.
+ */
+export function parseGraphqlResponseExtensions(
+	value: unknown
+): GraphqlResponseExtensions | undefined {
+	if (value === undefined) return undefined;
+	const extensions = record(value, 'extensions');
+	if (extensions.distributed === undefined) {
+		return Object.freeze({ ...extensions });
+	}
+
+	return Object.freeze({
+		...extensions,
+		distributed: parseDistributedProtocolEnvelope(extensions.distributed)
+	});
+}
+
+/** Parse one `extensions.distributed` value independently of a transport. */
+export function parseDistributedProtocolEnvelope(
+	value: unknown
+): DistributedProtocolEnvelope {
+	const envelope = record(value, 'extensions.distributed');
+	if (envelope.protocolVersion !== DISTRIBUTED_PROTOCOL_VERSION) {
+		if (
+			typeof envelope.protocolVersion === 'number' &&
+			Number.isInteger(envelope.protocolVersion)
+		) {
+			throw new DistributedProtocolError(
+				'DISTRIBUTED_PROTOCOL_VERSION_UNSUPPORTED',
+				'extensions.distributed.protocolVersion'
+			);
+		}
+		invalid('extensions.distributed.protocolVersion');
+	}
+
+	const schemaHash = publicString(
+		envelope.schemaHash,
+		'extensions.distributed.schemaHash'
+	);
+	const cacheScope = opaqueString(
+		envelope.cacheScope,
+		'extensions.distributed.cacheScope'
+	);
+	const operation =
+		envelope.operation === undefined
+			? undefined
+			: publicString(
+					envelope.operation,
+					'extensions.distributed.operation'
+				);
+	const command =
+		envelope.command === undefined
+			? undefined
+			: parseCommand(envelope.command);
+	const snapshot =
+		envelope.snapshot === undefined
+			? undefined
+			: parseSnapshot(envelope.snapshot);
+	const live =
+		envelope.live === undefined
+			? undefined
+			: parseLive(envelope.live);
+	validateLiveSnapshot(snapshot, live);
+	const trustedPresets = parseDistributedTrustedPresetInventory(
+		envelope.trustedPresets
+	);
+
+	return Object.freeze({
+		...envelope,
+		protocolVersion: DISTRIBUTED_PROTOCOL_VERSION,
+		schemaHash,
+		cacheScope,
+		...(operation === undefined ? {} : { operation }),
+		...(command === undefined ? {} : { command }),
+		...(snapshot === undefined ? {} : { snapshot }),
+		...(live === undefined ? {} : { live }),
+		trustedPresets
+	}) as DistributedProtocolEnvelope;
+}
+
+/**
+ * Parse and deeply freeze one scope-wide trusted-preset value inventory.
+ *
+ * This is exported for the framework-neutral replica's internal command seam.
+ * Applications receive the same values through
+ * {@link parseDistributedProtocolEnvelope}; they must never supply this
+ * inventory as command authority.
+ *
+ * @internal
+ */
+export function parseDistributedTrustedPresetInventory(
+	value: unknown,
+	path = 'extensions.distributed.trustedPresets'
+): readonly DistributedTrustedPreset[] {
+	if (value === undefined) return Object.freeze([]);
+	if (!Array.isArray(value) || value.length > MAX_TRUSTED_PRESETS) {
+		invalid(path);
+	}
+	const names = new Set<string>();
+	const presets = value.map((candidate, index) => {
+		const itemPath = `${path}[${index}]`;
+		const item = record(candidate, itemPath);
+		const name = trustedPresetName(item.name, `${itemPath}.name`);
+		if (names.has(name)) invalid(`${itemPath}.name`);
+		names.add(name);
+		const codec = trustedPresetCodec(item.codec, `${itemPath}.codec`);
+		return Object.freeze({
+			name,
+			codec,
+			value: parseTrustedPresetValue(
+				item.value,
+				codec,
+				`${itemPath}.value`
+			)
+		});
+	});
+	return Object.freeze(presets);
+}
+
+/**
+ * Build the private request extension for a generated live resume.
+ *
+ * The server remains authoritative and verifies every token. This client-side
+ * check only prevents malformed, duplicate, or unbounded state from leaving
+ * the replica.
+ *
+ * @internal
+ */
+export function distributedLiveResumeExtensions(
+	value: readonly DistributedLiveCursor[]
+): DistributedLiveResumeExtensions {
+	if (
+		!Array.isArray(value) ||
+		value.length === 0 ||
+		value.length > MAX_LIVE_RESUME_CURSORS
+	) {
+		invalid('request.extensions.distributed.resume.cursors');
+	}
+	const cursors = Object.freeze(
+		value.map((cursor, index) =>
+			parseLiveCursor(
+				cursor,
+				`request.extensions.distributed.resume.cursors[${index}]`
+			)
+		)
+	);
+	assertUnique(
+		cursors.map((cursor) => cursor.projection),
+		'request.extensions.distributed.resume.cursors'
+	);
+	return Object.freeze({
+		distributed: Object.freeze({
+			resume: Object.freeze({ cursors })
+		})
+	});
+}
+
+function parseCommand(value: unknown): DistributedCommandMetadata {
+	const command = record(value, 'extensions.distributed.command');
+	const state = enumString(
+		command.state,
+		COMMAND_STATES,
+		'extensions.distributed.command.state'
+	);
+	const consistency = enumString(
+		command.consistency,
+		COMMAND_CONSISTENCIES,
+		'extensions.distributed.command.consistency'
+	);
+	if (!Array.isArray(command.expects)) {
+		invalid('extensions.distributed.command.expects');
+	}
+	if (command.expects.length > MAX_EVIDENCE_ITEMS) {
+		invalid('extensions.distributed.command.expects');
+	}
+
+	const expects = command.expects.map((expectation, index) => {
+		const path = `extensions.distributed.command.expects[${index}]`;
+		const item = record(expectation, path);
+		return Object.freeze({
+			...item,
+			projection: publicString(item.projection, `${path}.projection`),
+			model: publicString(item.model, `${path}.model`),
+			scopeToken: opaqueString(item.scopeToken, `${path}.scopeToken`)
+		}) as DistributedProjectionExpectation;
+	});
+	const observations = parseOptionalEvidenceArray(
+		command.observations,
+		'extensions.distributed.command.observations',
+		parseProjectionObservation
+	);
+	const records = parseOptionalEvidenceArray(
+		command.records,
+		'extensions.distributed.command.records',
+		parseRecordRevision
+	);
+	const commandId = opaqueString(
+		command.commandId,
+		'extensions.distributed.command.commandId'
+	);
+	const causationId = opaqueString(
+		command.causationId,
+		'extensions.distributed.command.causationId'
+	);
+	const expectationKeys = new Set(expects.map(projectionExpectationKey));
+	const seenObservations = new Set<string>();
+	for (const observation of observations) {
+		const key = projectionObservationKey(observation);
+		if (
+			observation.causationId !== causationId ||
+			!expectationKeys.has(projectionExpectationKey(observation)) ||
+			seenObservations.has(key)
+		) {
+			invalid('extensions.distributed.command.observations');
+		}
+		seenObservations.add(key);
+	}
+
+	return Object.freeze({
+		...command,
+		commandId,
+		causationId,
+		state,
+		consistency,
+		expects: Object.freeze(expects),
+		observations,
+		records
+	}) as DistributedCommandMetadata;
+}
+
+function parseSnapshot(value: unknown): DistributedQuerySnapshot {
+	const path = 'extensions.distributed.snapshot';
+	const snapshot = record(value, path);
+	if (typeof snapshot.recordsComplete !== 'boolean') {
+		invalid(`${path}.recordsComplete`);
+	}
+	if (typeof snapshot.indexesComparable !== 'boolean') {
+		invalid(`${path}.indexesComparable`);
+	}
+	const records = parseRequiredEvidenceArray(
+		snapshot.records,
+		`${path}.records`,
+		parseRecordRevision
+	);
+	const indexes = parseRequiredEvidenceArray(
+		snapshot.indexes,
+		`${path}.indexes`,
+		parseIndexRevision
+	);
+	const observations = parseRequiredEvidenceArray(
+		snapshot.observations,
+		`${path}.observations`,
+		parseProjectionObservation
+	);
+	assertUnique(
+		indexes.map((index) => index.projection),
+		`${path}.indexes`
+	);
+	if (
+		indexes.filter((index) => index.resume !== undefined).length >
+		MAX_LIVE_RESUME_CURSORS
+	) {
+		invalid(`${path}.indexes`);
+	}
+	if (
+		!snapshot.indexesComparable &&
+		(indexes.length > 0 || observations.length > 0)
+	) {
+		invalid(`${path}.indexesComparable`);
+	}
+
+	return Object.freeze({
+		...snapshot,
+		scopeToken: opaqueString(snapshot.scopeToken, `${path}.scopeToken`),
+		recordsComplete: snapshot.recordsComplete,
+		indexesComparable: snapshot.indexesComparable,
+		records,
+		indexes,
+		observations
+	}) as DistributedQuerySnapshot;
+}
+
+function parseLive(value: unknown): DistributedLiveMetadata {
+	const path = 'extensions.distributed.live';
+	const live = record(value, path);
+	if (typeof live.supported !== 'boolean') invalid(`${path}.supported`);
+	if (typeof live.reset !== 'boolean') invalid(`${path}.reset`);
+	if (
+		!Array.isArray(live.cursors) ||
+		live.cursors.length > MAX_LIVE_RESUME_CURSORS
+	) {
+		invalid(`${path}.cursors`);
+	}
+	const cursors = parseRequiredEvidenceArray(
+		live.cursors,
+		`${path}.cursors`,
+		parseLiveCursor
+	);
+	assertUnique(
+		cursors.map((cursor) => cursor.projection),
+		`${path}.cursors`
+	);
+	if (!live.supported && (!live.reset || cursors.length !== 0)) {
+		invalid(path);
+	}
+	return Object.freeze({
+		...live,
+		supported: live.supported,
+		reset: live.reset,
+		cursors
+	}) as DistributedLiveMetadata;
+}
+
+function validateLiveSnapshot(
+	snapshot: DistributedQuerySnapshot | undefined,
+	live: DistributedLiveMetadata | undefined
+): void {
+	if (live === undefined) return;
+	if (snapshot === undefined) invalid('extensions.distributed.snapshot');
+	if (!live.supported) return;
+	if (!snapshot.indexesComparable) {
+		invalid('extensions.distributed.snapshot.indexesComparable');
+	}
+	if (
+		live.cursors.length === 0 ||
+		snapshot.indexes.length !== live.cursors.length
+	) {
+		invalid('extensions.distributed.live.cursors');
+	}
+	const indexes = new Map(
+		snapshot.indexes.map((index) => [index.projection, index])
+	);
+	for (const cursor of live.cursors) {
+		const index = indexes.get(cursor.projection);
+		if (
+			index === undefined ||
+			index.position !== cursor.position ||
+			index.resume === undefined ||
+			index.resume.token !== cursor.token
+		) {
+			invalid('extensions.distributed.live.cursors');
+		}
+	}
+}
+
+function parseRecordRevision(
+	value: unknown,
+	path: string
+): DistributedRecordRevision {
+	const item = record(value, path);
+	let responsePath: readonly string[] | undefined;
+	if (item.path !== undefined) {
+		if (
+			!Array.isArray(item.path) ||
+			item.path.length === 0 ||
+			item.path.length > MAX_PATH_SEGMENTS
+		) {
+			invalid(`${path}.path`);
+		}
+		responsePath = Object.freeze(
+			item.path.map((segment, index) =>
+				publicString(segment, `${path}.path[${index}]`)
+			)
+		);
+	}
+	if (typeof item.tombstone !== 'boolean') invalid(`${path}.tombstone`);
+	return Object.freeze({
+		...item,
+		...(responsePath === undefined ? {} : { path: responsePath }),
+		model: publicString(item.model, `${path}.model`),
+		scopeToken: opaqueString(item.scopeToken, `${path}.scopeToken`),
+		incarnation: canonicalDecimal(item.incarnation, `${path}.incarnation`),
+		revision: canonicalDecimal(item.revision, `${path}.revision`),
+		tombstone: item.tombstone
+	}) as DistributedRecordRevision;
+}
+
+function parseProjectionObservation(
+	value: unknown,
+	path: string
+): DistributedProjectionObservation {
+	const item = record(value, path);
+	return Object.freeze({
+		...item,
+		causationId: opaqueString(item.causationId, `${path}.causationId`),
+		projection: publicString(item.projection, `${path}.projection`),
+		model: publicString(item.model, `${path}.model`),
+		scopeToken: opaqueString(item.scopeToken, `${path}.scopeToken`)
+	}) as DistributedProjectionObservation;
+}
+
+function parseIndexRevision(
+	value: unknown,
+	path: string
+): DistributedIndexRevision {
+	const item = record(value, path);
+	const projection = publicString(item.projection, `${path}.projection`);
+	const position = canonicalDecimal(item.position, `${path}.position`);
+	const resume =
+		item.resume === undefined
+			? undefined
+			: parseLiveCursor(item.resume, `${path}.resume`);
+	if (
+		resume !== undefined &&
+		(resume.projection !== projection || resume.position !== position)
+	) {
+		invalid(`${path}.resume`);
+	}
+	return Object.freeze({
+		...item,
+		projection,
+		scopeToken: opaqueString(item.scopeToken, `${path}.scopeToken`),
+		position,
+		...(resume === undefined ? {} : { resume })
+	}) as DistributedIndexRevision;
+}
+
+function parseLiveCursor(value: unknown, path: string): DistributedLiveCursor {
+	const item = record(value, path);
+	return Object.freeze({
+		...item,
+		projection: publicString(item.projection, `${path}.projection`),
+		position: canonicalDecimal(item.position, `${path}.position`),
+		token: opaqueString(item.token, `${path}.token`)
+	}) as DistributedLiveCursor;
+}
+
+function parseRequiredEvidenceArray<T>(
+	value: unknown,
+	path: string,
+	parse: (value: unknown, path: string) => T
+): readonly T[] {
+	if (!Array.isArray(value) || value.length > MAX_EVIDENCE_ITEMS) invalid(path);
+	return Object.freeze(value.map((item, index) => parse(item, `${path}[${index}]`)));
+}
+
+function parseOptionalEvidenceArray<T>(
+	value: unknown,
+	path: string,
+	parse: (value: unknown, path: string) => T
+): readonly T[] {
+	return value === undefined
+		? Object.freeze([])
+		: parseRequiredEvidenceArray(value, path, parse);
+}
+
+function projectionExpectationKey(
+	value: Pick<
+		DistributedProjectionExpectation | DistributedProjectionObservation,
+		'projection' | 'model' | 'scopeToken'
+	>
+): string {
+	return JSON.stringify([value.projection, value.model, value.scopeToken]);
+}
+
+function projectionObservationKey(value: DistributedProjectionObservation): string {
+	return JSON.stringify([
+		value.causationId,
+		value.projection,
+		value.model,
+		value.scopeToken
+	]);
+}
+
+function assertUnique(values: readonly string[], path: string): void {
+	if (new Set(values).size !== values.length) invalid(path);
+}
+
+function record(value: unknown, path: string): Record<string, unknown> {
+	if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+		invalid(path);
+	}
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) invalid(path);
+	return value as Record<string, unknown>;
+}
+
+function publicString(value: unknown, path: string): string {
+	if (
+		typeof value !== 'string' ||
+		value.length === 0 ||
+		value.length > MAX_PUBLIC_NAME_LENGTH
+	) {
+		invalid(path);
+	}
+	return value;
+}
+
+function trustedPresetName(value: unknown, path: string): string {
+	if (
+		typeof value !== 'string' ||
+		value.length === 0 ||
+		value.length > MAX_TRUSTED_PRESET_NAME_LENGTH ||
+		value.trim() !== value ||
+		/[\u0000-\u001f\u007f-\u009f]/.test(value)
+	) {
+		invalid(path);
+	}
+	return value;
+}
+
+/** @internal */
+export function isDistributedTrustedPresetCodec(
+	value: unknown
+): value is DistributedTrustedPresetCodec {
+	return (
+		value === 'string' ||
+		value === 'string_unvalidated_timestamp' ||
+		value === 'base64' ||
+		value === 'boolean' ||
+		value === 'int32' ||
+		value === 'float64' ||
+		value === 'json_number_precision_limited' ||
+		value === 'json'
+	);
+}
+
+function trustedPresetCodec(
+	value: unknown,
+	path: string
+): DistributedTrustedPresetCodec {
+	if (!isDistributedTrustedPresetCodec(value)) invalid(path);
+	return value;
+}
+
+function parseTrustedPresetValue(
+	value: unknown,
+	codec: DistributedTrustedPresetCodec,
+	path: string
+): DistributedProtocolValue {
+	switch (codec) {
+		case 'string':
+		case 'string_unvalidated_timestamp':
+			if (typeof value !== 'string') invalid(path);
+			return value;
+		case 'base64':
+			if (typeof value !== 'string' || !CANONICAL_BASE64.test(value)) {
+				invalid(path);
+			}
+			return value;
+		case 'boolean':
+			if (typeof value !== 'boolean') invalid(path);
+			return value;
+		case 'int32':
+			if (
+				typeof value !== 'number' ||
+				!Number.isInteger(value) ||
+				Object.is(value, -0) ||
+				value < -2_147_483_648 ||
+				value > 2_147_483_647
+			) {
+				invalid(path);
+			}
+			return value;
+		case 'json_number_precision_limited':
+			if (
+				typeof value !== 'number' ||
+				!Number.isInteger(value) ||
+				Object.is(value, -0) ||
+				value < -MAX_SAFE_INTEGER ||
+				value > MAX_SAFE_INTEGER
+			) {
+				invalid(path);
+			}
+			return value;
+		case 'float64':
+			if (typeof value !== 'number' || !Number.isFinite(value)) {
+				invalid(path);
+			}
+			return Object.is(value, -0) ? 0 : value;
+		case 'json':
+			return cloneProtocolValue(value, path);
+	}
+}
+
+function cloneProtocolValue(
+	value: unknown,
+	path: string,
+	active: Set<object> = new Set(),
+	depth = 0
+): DistributedProtocolValue {
+	if (depth > MAX_TRUSTED_PRESET_VALUE_DEPTH) invalid(path);
+	if (
+		value === null ||
+		typeof value === 'string' ||
+		typeof value === 'boolean'
+	) {
+		return value;
+	}
+	if (typeof value === 'number') {
+		if (!Number.isFinite(value)) invalid(path);
+		return Object.is(value, -0) ? 0 : value;
+	}
+	if (typeof value !== 'object' || active.has(value)) invalid(path);
+	active.add(value);
+	if (Array.isArray(value)) {
+		if (Object.getPrototypeOf(value) !== Array.prototype) invalid(path);
+		const ownKeys = Reflect.ownKeys(value);
+		if (
+			ownKeys.some(
+				(key) =>
+					key !== 'length' &&
+					(typeof key !== 'string' ||
+						!/^(0|[1-9][0-9]*)$/.test(key) ||
+						Number(key) >= value.length)
+			)
+		) {
+			invalid(path);
+		}
+		const result: DistributedProtocolValue[] = [];
+		for (let index = 0; index < value.length; index += 1) {
+			const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+			if (
+				descriptor === undefined ||
+				!('value' in descriptor) ||
+				descriptor.value === undefined
+			) {
+				invalid(`${path}[${index}]`);
+			}
+			result.push(
+				cloneProtocolValue(
+					descriptor.value,
+					`${path}[${index}]`,
+					active,
+					depth + 1
+				)
+			);
+		}
+		active.delete(value);
+		return Object.freeze(result);
+	}
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) invalid(path);
+	const keys = Reflect.ownKeys(value);
+	if (keys.some((key) => typeof key !== 'string')) invalid(path);
+	const result: Record<string, DistributedProtocolValue> = {};
+	for (const key of (keys as string[]).sort()) {
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (
+			descriptor === undefined ||
+			!('value' in descriptor) ||
+			descriptor.value === undefined
+		) {
+			invalid(`${path}.${key}`);
+		}
+		Object.defineProperty(result, key, {
+			value: cloneProtocolValue(
+				descriptor.value,
+				`${path}.${key}`,
+				active,
+				depth + 1
+			),
+			enumerable: true,
+			configurable: false,
+			writable: false
+		});
+	}
+	active.delete(value);
+	return Object.freeze(result);
+}
+
+function opaqueString(value: unknown, path: string): DistributedOpaqueString {
+	if (
+		typeof value !== 'string' ||
+		value.length === 0 ||
+		value.length > MAX_OPAQUE_STRING_LENGTH
+	) {
+		invalid(path);
+	}
+	return value as DistributedOpaqueString;
+}
+
+function canonicalDecimal(
+	value: unknown,
+	path: string
+): DistributedDecimalString {
+	if (
+		typeof value !== 'string' ||
+		!/^(0|[1-9][0-9]*)$/.test(value) ||
+		value.length > MAX_UNSIGNED_64.length ||
+		(value.length === MAX_UNSIGNED_64.length && value > MAX_UNSIGNED_64)
+	) {
+		invalid(path);
+	}
+	return value as DistributedDecimalString;
+}
+
+/**
+ * Compare two already-validated protocol decimals without converting either
+ * through JavaScript's numeric types.
+ */
+export function compareDistributedDecimal(
+	left: DistributedDecimalString,
+	right: DistributedDecimalString
+): -1 | 0 | 1 {
+	if (left.length !== right.length) return left.length < right.length ? -1 : 1;
+	return left === right ? 0 : left < right ? -1 : 1;
+}
+
+function enumString<T extends string>(
+	value: unknown,
+	values: ReadonlySet<T>,
+	path: string
+): T {
+	if (typeof value !== 'string' || !values.has(value as T)) invalid(path);
+	return value as T;
+}
+
+function invalid(path: string): never {
+	throw new DistributedProtocolError('DISTRIBUTED_PROTOCOL_INVALID', path);
+}
diff --git a/js/src/react/context.ts b/js/src/react/context.ts
new file mode 100644
index 00000000..4db37d5a
--- /dev/null
+++ b/js/src/react/context.ts
@@ -0,0 +1,52 @@
+'use client';
+
+import {
+	createContext,
+	createElement,
+	useContext,
+	type ReactElement,
+	type ReactNode
+} from 'react';
+
+import type { DistributedReplica } from '../replica/types.js';
+
+const DistributedReplicaContext = createContext<DistributedReplica | undefined>(
+	undefined
+);
+
+export type DistributedProviderProps = {
+	/**
+	 * One framework-neutral replica for this browser authorization lifecycle, or
+	 * one fresh replica for this server-render request.
+	 */
+	readonly replica: DistributedReplica;
+	readonly children?: ReactNode;
+};
+
+/**
+ * Makes an existing framework-neutral replica available to React.
+ *
+ * The provider deliberately does not create, hydrate, authorize, or retain a
+ * replica. Those lifecycles stay in the shared core and application
+ * composition, which keeps SSR request isolation explicit.
+ */
+export function DistributedProvider({
+	replica,
+	children
+}: DistributedProviderProps): ReactElement {
+	if (replica === undefined || replica === null) {
+		throw new TypeError('DistributedProvider requires a replica');
+	}
+	return createElement(DistributedReplicaContext.Provider, { value: replica }, children);
+}
+
+/** Read the exact replica supplied by the nearest DistributedProvider. */
+export function useDistributedReplica(): DistributedReplica {
+	const replica = useContext(DistributedReplicaContext);
+	if (replica === undefined) {
+		throw new Error(
+			'useDistributedReplica must be used inside a DistributedProvider'
+		);
+	}
+	return replica;
+}
diff --git a/js/src/react/index.ts b/js/src/react/index.ts
new file mode 100644
index 00000000..6a724d73
--- /dev/null
+++ b/js/src/react/index.ts
@@ -0,0 +1,11 @@
+'use client';
+
+export {
+	DistributedProvider,
+	useDistributedReplica,
+	type DistributedProviderProps
+} from './context.js';
+export {
+	useDistributedQuery,
+	type DistributedQueryResult
+} from './query.js';
diff --git a/js/src/react/query.ts b/js/src/react/query.ts
new file mode 100644
index 00000000..8afd81f1
--- /dev/null
+++ b/js/src/react/query.ts
@@ -0,0 +1,178 @@
+'use client';
+
+import { useDebugValue, useMemo, useSyncExternalStore } from 'react';
+
+import type { GraphqlVariables } from '../types.js';
+import { canonicalizeOperationVariables } from '../replica/identity.js';
+import type {
+	DistributedReplica,
+	ReplicaOperationArtifact,
+	ReplicaSnapshot,
+	ReplicaWatch,
+	WatchReplicaOptions
+} from '../replica/types.js';
+import { useDistributedReplica } from './context.js';
+
+const EMPTY_VARIABLES = Object.freeze({}) as Readonly<Record<never, never>>;
+
+type UseDistributedQueryArguments<TVariables extends GraphqlVariables> =
+	keyof TVariables extends never
+		? readonly [
+				variables?: TVariables,
+				options?: WatchReplicaOptions
+			]
+		: readonly [
+				variables: TVariables,
+				options?: WatchReplicaOptions
+			];
+
+export type DistributedQueryResult<TData> = ReplicaSnapshot<TData> & {
+	/** Force the shared cache-and-live coordinator to revalidate this operation. */
+	readonly refresh: () => Promise<void>;
+};
+
+/**
+ * React's commit-safe bridge around one framework-neutral ReplicaWatch.
+ *
+ * Constructing a core watch starts transport work, so this wrapper creates it
+ * only from React's subscribe phase. Server renders use the side-effect-free
+ * replica read path and therefore leave no abandoned watch behind.
+ */
+class ReactReplicaExternalStore<
+	TData,
+	TVariables extends GraphqlVariables
+> {
+	readonly #replica: DistributedReplica;
+	readonly #artifact: ReplicaOperationArtifact<TData, TVariables>;
+	readonly #variables: TVariables;
+	readonly #options: WatchReplicaOptions;
+	#watch: ReplicaWatch<TData> | undefined;
+	#snapshot: ReplicaSnapshot<TData> | undefined;
+	#subscriberCount = 0;
+
+	constructor(
+		replica: DistributedReplica,
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables,
+		options: WatchReplicaOptions
+	) {
+		this.#replica = replica;
+		this.#artifact = artifact;
+		this.#variables = variables;
+		this.#options = options;
+	}
+
+	readonly getSnapshot = (): ReplicaSnapshot<TData> => {
+		if (this.#watch !== undefined) {
+			this.#snapshot = this.#watch.get();
+		}
+		this.#snapshot ??= this.#replica.read(this.#artifact, this.#variables);
+		return this.#snapshot;
+	};
+
+	readonly getServerSnapshot = (): ReplicaSnapshot<TData> => this.getSnapshot();
+
+	readonly subscribe = (notify: () => void): (() => void) => {
+		const watch = this.#watch ?? this.#createWatch();
+		this.#subscriberCount += 1;
+		let active = true;
+		const unsubscribe = watch.subscribe((snapshot) => {
+			this.#snapshot = snapshot;
+			notify();
+		});
+
+		return () => {
+			if (!active) return;
+			active = false;
+			unsubscribe();
+			this.#subscriberCount -= 1;
+			if (this.#subscriberCount === 0 && this.#watch === watch) {
+				watch.destroy();
+				this.#watch = undefined;
+			}
+		};
+	};
+
+	readonly refresh = async (): Promise<void> => {
+		const activeWatch = this.#watch;
+		if (activeWatch !== undefined) {
+			await activeWatch.refresh();
+			return;
+		}
+
+		// This path is primarily defensive for an event fired before subscription
+		// commit. The temporary watch is always retired.
+		const temporaryWatch = this.#replica.watch(
+			this.#artifact,
+			this.#variables,
+			this.#options
+		);
+		try {
+			await temporaryWatch.refresh();
+			this.#snapshot = temporaryWatch.get();
+		} finally {
+			temporaryWatch.destroy();
+		}
+	};
+
+	#createWatch(): ReplicaWatch<TData> {
+		const watch = this.#replica.watch(
+			this.#artifact,
+			this.#variables,
+			this.#options
+		);
+		this.#watch = watch;
+		this.#snapshot = watch.get();
+		return watch;
+	}
+}
+
+/**
+ * Bind a generated operation artifact to React without introducing a React
+ * cache. All reads, fetches, live updates, optimism, and authorization fences
+ * continue through the supplied DistributedReplica.
+ */
+export function useDistributedQuery<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	artifact: ReplicaOperationArtifact<TData, TVariables>,
+	...args: UseDistributedQueryArguments<TVariables>
+): DistributedQueryResult<TData> {
+	const replica = useDistributedReplica();
+	const suppliedVariables = (args[0] ?? EMPTY_VARIABLES) as TVariables;
+	const live = args[1]?.live === true;
+
+	// Core canonicalization is the only operation-input authority. The JSON text
+	// is merely a React memo identity for that already-canonical frozen value.
+	const canonicalVariables = canonicalizeOperationVariables(
+		artifact,
+		suppliedVariables
+	);
+	const variableIdentity = JSON.stringify(canonicalVariables);
+	const store = useMemo(
+		() =>
+			new ReactReplicaExternalStore(
+				replica,
+				artifact,
+				canonicalVariables,
+				Object.freeze({ live })
+			),
+		[replica, artifact, variableIdentity, live]
+	);
+	const snapshot = useSyncExternalStore(
+		store.subscribe,
+		store.getSnapshot,
+		store.getServerSnapshot
+	);
+	useDebugValue(`${artifact.id}: ${snapshot.status}`);
+
+	return useMemo(
+		() =>
+			Object.freeze({
+				...snapshot,
+				refresh: store.refresh
+			}) as DistributedQueryResult<TData>,
+		[snapshot, store]
+	);
+}
diff --git a/js/src/replica/command-id.ts b/js/src/replica/command-id.ts
new file mode 100644
index 00000000..ee714ec3
--- /dev/null
+++ b/js/src/replica/command-id.ts
@@ -0,0 +1,21 @@
+/** Create a browser/Node UUIDv7 command identity. */
+export function createReplicaCommandId(): string {
+	const crypto = globalThis.crypto;
+	if (!crypto || typeof crypto.getRandomValues !== 'function') {
+		throw new Error('replica commands require crypto.getRandomValues');
+	}
+
+	const bytes = crypto.getRandomValues(new Uint8Array(16));
+	let timestamp = Date.now();
+	for (let index = 5; index >= 0; index -= 1) {
+		bytes[index] = timestamp & 0xff;
+		timestamp = Math.floor(timestamp / 256);
+	}
+	bytes[6] = (bytes[6]! & 0x0f) | 0x70;
+	bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+
+	const hex = [...bytes].map((value) => value.toString(16).padStart(2, '0'));
+	return `${hex.slice(0, 4).join('')}-${hex.slice(4, 6).join('')}-${hex
+		.slice(6, 8)
+		.join('')}-${hex.slice(8, 10).join('')}-${hex.slice(10).join('')}`;
+}
diff --git a/js/src/replica/command-runtime.ts b/js/src/replica/command-runtime.ts
new file mode 100644
index 00000000..da4bb9f0
--- /dev/null
+++ b/js/src/replica/command-runtime.ts
@@ -0,0 +1,33 @@
+/** Public entry for command runtime; implementation lives in ./command-runtime/. */
+export {
+	createReplicaCommandRuntime,
+	ReplicaCommandRuntimeError,
+	replicaCommandAuthority,
+	replicaCommandDirectProjection,
+	replicaCommandProjectedLifecycle,
+	replicaCommandProjectedLifecycleOf,
+	replicaResultObservation
+} from './command-runtime/index.js';
+export type {
+	ReplicaBoundCommand,
+	ReplicaBoundCommands,
+	ReplicaCommandAuthorityHost,
+	ReplicaCommandAuthorityRegistration,
+	ReplicaCommandAuthoritySnapshot,
+	ReplicaCommandCallOptions,
+	ReplicaCommandDirectProjection,
+	ReplicaCommandProjectedOutcome,
+	ReplicaCommandReceipt,
+	ReplicaCommandRecoveryReceipt,
+	ReplicaCommandRuntime,
+	ReplicaCommandRuntimeErrorCode,
+	ReplicaCommandRuntimeOptions,
+	ReplicaCommandStatus,
+	ReplicaCommandStatusArtifact,
+	ReplicaCommandStatusRequest,
+	ReplicaCommandSurfaceContract,
+	ReplicaCommandTransport,
+	ReplicaCommandTransportRequest,
+	ReplicaCommandTransportResult,
+	ReplicaResultObservationRegistration
+} from './command-runtime/index.js';
diff --git a/js/src/replica/command-runtime/constants.ts b/js/src/replica/command-runtime/constants.ts
new file mode 100644
index 00000000..7144fd52
--- /dev/null
+++ b/js/src/replica/command-runtime/constants.ts
@@ -0,0 +1,5 @@
+export const MAX_TRANSPORT_RETRIES = 8;
+export const MAX_OUTPUT_DEPTH = 64;
+export const INITIAL_STATUS_POLL_MS = 25;
+export const MAX_STATUS_POLL_MS = 1_000;
+export const SHA256 = /^sha256:[0-9a-f]{64}$/;
diff --git a/js/src/replica/command-runtime/create.ts b/js/src/replica/command-runtime/create.ts
new file mode 100644
index 00000000..449a8788
--- /dev/null
+++ b/js/src/replica/command-runtime/create.ts
@@ -0,0 +1,999 @@
+import {
+	parseGraphqlResponseExtensions,
+	type DistributedProtocolEnvelope
+} from '../../protocol.js';
+import {
+	matchReplicaTrustedPresetInventory,
+	prepareReplicaCommandWithTrustedPresets,
+	verifyReplicaCommandReceipt,
+	type ReplicaCommandArtifact,
+	type ReplicaPreparedCommand
+} from '../commands.js';
+import type { ReplicaResultEnvelope } from '../types.js';
+import {
+	applyOptimisticEffects,
+	attachAuthorityAbort,
+	callerProjectedPromise,
+	cloneScope,
+	commandOutput,
+	commandStatusArtifact,
+	commandStatusRequest,
+	commandSurfaceContract,
+	commandTransportRequest,
+	confirmDirectProjection,
+	defineBoundCommand,
+	dispatchPrepared,
+	failTrackedProjection,
+	freezeCommandTree,
+	graphqlCommandRejection,
+	linkAbortSignals,
+	monitorPendingProjection,
+	normalizeInventory,
+	normalizeRetries,
+	pendingProjection,
+	preparedSemanticChanges,
+	requireCommandEnvelope,
+	requireCommandRejectionEnvelope,
+	requireStatusEnvelope,
+	sameScope,
+	settleProjectionFailure,
+	settleProjectionSuccess,
+	settleTrackedProjection,
+	validateStatusProgression,
+	waitForCommandOperation
+} from './lib/index.js';
+import { ReplicaCommandRuntimeError } from './errors.js';
+import {
+	replicaCommandAuthority,
+	replicaCommandProjectedLifecycle,
+	replicaResultObservation
+} from './symbols.js';
+import type {
+	CapturedAuthority,
+	CommandEntry,
+	CommandStatusTracker,
+	PendingProjection,
+	ReplicaBoundCommands,
+	ReplicaCommandAuthorityHost,
+	ReplicaCommandAuthoritySnapshot,
+	ReplicaCommandCallOptions,
+	ReplicaCommandProjectedOutcome,
+	ReplicaCommandReceipt,
+	ReplicaCommandRecoveryReceipt,
+	ReplicaCommandRuntime,
+	ReplicaCommandRuntimeOptions,
+	ReplicaCommandStatus,
+	ReplicaCommandTransport,
+	ReplicaCommandTransportResult,
+	SemanticReplica
+} from './types.js';
+
+export function createReplicaCommandRuntime<
+	const TEntries extends Readonly<Record<string, CommandEntry>>
+>(
+	replica: ReplicaCommandAuthorityHost,
+	transport: ReplicaCommandTransport,
+	entries: TEntries,
+	options: ReplicaCommandRuntimeOptions = {}
+): ReplicaCommandRuntime<TEntries> {
+	const inventory = normalizeInventory(entries);
+	if (options.diagnostics !== undefined) {
+		for (const { artifact } of inventory) {
+			try {
+				options.diagnostics.command(artifact);
+			} catch (error) {
+				options.onBackgroundError?.(error);
+			}
+		}
+	}
+	const contract = commandSurfaceContract(
+		inventory.map(({ artifact }) => artifact),
+		options.status?.protocol.trustedPresets
+	);
+	const statusArtifact =
+		options.status === undefined
+			? undefined
+			: commandStatusArtifact(options.status, contract);
+	const replicaRevalidate =
+		typeof replica.revalidate === 'function'
+			? replica.revalidate.bind(replica)
+			: undefined;
+	if (statusArtifact !== undefined && transport.status === undefined) {
+		throw new TypeError(
+			'generated command status artifact requires transport.status'
+		);
+	}
+	if (
+		replicaRevalidate === undefined &&
+		inventory.some(({ artifact }) => artifact.revalidation.required)
+	) {
+		throw new TypeError(
+			'generated command revalidation plan requires replica.revalidate'
+		);
+	}
+	const registration = replica[replicaCommandAuthority]?.(contract);
+	const pending = new Map<string, PendingProjection>();
+	const unmanagedLayers = new Set<string>();
+	const runtimeAbort = new AbortController();
+	let disposed = false;
+
+	const rejectUnmanagedLayer = (commandId: string): boolean => {
+		unmanagedLayers.delete(commandId);
+		return replica.rejectOptimisticLayer(commandId);
+	};
+
+	const retireLayerAfterAuthoritativeRevalidation = (
+		commandId: string
+	): boolean => {
+		if (!replica.markOptimisticLayerAccepted(commandId)) {
+			// The authoritative result may already have retired this layer.
+			unmanagedLayers.delete(commandId);
+			return false;
+		}
+		replica.confirmOptimisticLayer(commandId, () => undefined);
+		unmanagedLayers.delete(commandId);
+		return true;
+	};
+
+	const authoritySnapshot = (): ReplicaCommandAuthoritySnapshot =>
+		registration?.read() ?? {
+			generation: replica.authorizationGeneration,
+			scope: replica.scope,
+			trustedPresets: Object.freeze([])
+		};
+
+	const currentAuthority = (): CapturedAuthority => {
+		if (disposed) {
+			throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_DISPOSED');
+		}
+		const snapshot = authoritySnapshot();
+		const scope = snapshot.scope;
+		if (
+			scope === undefined ||
+			scope.protocolVersion !== contract.protocolVersion ||
+			scope.schemaHash !== contract.schemaHash
+		) {
+			throw new ReplicaCommandRuntimeError(
+				'REPLICA_COMMAND_AUTHORITY_UNAVAILABLE'
+			);
+		}
+		const matched = matchReplicaTrustedPresetInventory(
+			contract.trustedPresets,
+			snapshot.trustedPresets
+		);
+		return Object.freeze({
+			generation: snapshot.generation,
+			scope: cloneScope(scope),
+			trustedPresets: matched.values,
+			...(snapshot.signal === undefined ? {} : { signal: snapshot.signal })
+		});
+	};
+
+	const stillCurrent = (captured: CapturedAuthority): boolean => {
+		const current = authoritySnapshot();
+		return (
+			!disposed &&
+			current.generation === captured.generation &&
+			current.scope !== undefined &&
+			sameScope(current.scope, captured.scope)
+		);
+	};
+
+	const revalidate = async (
+		prepared: ReplicaPreparedCommand<unknown, unknown>,
+		authoritySignal?: AbortSignal
+	): Promise<boolean> => {
+		if (replicaRevalidate === undefined) return false;
+		const revalidationSignals = linkAbortSignals([
+			authoritySignal,
+			runtimeAbort.signal
+		]);
+		try {
+			await waitForCommandOperation(
+				replicaRevalidate(prepared.revalidation),
+				revalidationSignals.signal
+			);
+			return true;
+		} catch (error) {
+			if (!disposed && authoritySignal?.aborted !== true) {
+				options.onBackgroundError?.(error);
+			}
+			throw error;
+		} finally {
+			revalidationSignals.dispose();
+		}
+	};
+	const revalidateInBackground = (
+		prepared: ReplicaPreparedCommand<unknown, unknown>,
+		authority?: CapturedAuthority
+	): void => {
+		void revalidate(prepared, authority?.signal).catch(() => undefined);
+	};
+	const revalidateAndConfirmUnmanagedInBackground = (
+		prepared: ReplicaPreparedCommand<unknown, unknown>,
+		authority: CapturedAuthority
+	): void => {
+		void revalidate(prepared, authority.signal)
+			.then((refreshed) => {
+				if (
+					refreshed &&
+					stillCurrent(authority) &&
+					unmanagedLayers.has(prepared.commandId)
+				) {
+					/*
+					 * A generated required revalidation is the canonical base
+					 * fence for commands without a finite observation contract.
+					 * Retire their accepted overlay only after that fetch settles.
+					 */
+					retireLayerAfterAuthoritativeRevalidation(
+						prepared.commandId
+					);
+				}
+			})
+			.catch(() => undefined);
+	};
+
+	const statusReader = <TInput, TOutput>(
+		prepared: ReplicaPreparedCommand<TInput, TOutput>,
+		authority: CapturedAuthority,
+		tracker: CommandStatusTracker
+	): (() => Promise<ReplicaCommandStatus>) => {
+		const read = async (): Promise<ReplicaCommandStatus> => {
+			if (disposed) {
+				throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_DISPOSED', {
+					commandId: prepared.commandId
+				});
+			}
+			if (statusArtifact === undefined || transport.status === undefined) {
+				throw new ReplicaCommandRuntimeError(
+					'REPLICA_COMMAND_STATUS_UNAVAILABLE',
+					{ commandId: prepared.commandId }
+				);
+			}
+			if (!stillCurrent(authority)) {
+				throw new ReplicaCommandRuntimeError(
+					'REPLICA_COMMAND_SCOPE_INVALIDATED',
+					{ commandId: prepared.commandId }
+				);
+			}
+			let result: ReplicaCommandTransportResult;
+			const statusSignals = linkAbortSignals([
+				authority.signal,
+				runtimeAbort.signal
+			]);
+			try {
+				result = await waitForCommandOperation(
+					transport.status(
+						commandStatusRequest(
+							statusArtifact,
+							prepared.commandId,
+							statusSignals.signal
+						)
+					),
+					statusSignals.signal
+				);
+			} catch (error) {
+				if (disposed) {
+					throw new ReplicaCommandRuntimeError(
+						'REPLICA_COMMAND_DISPOSED',
+						{ commandId: prepared.commandId, cause: error }
+					);
+				}
+				throw new ReplicaCommandRuntimeError(
+					authority.signal?.aborted
+						? 'REPLICA_COMMAND_SCOPE_INVALIDATED'
+						: 'REPLICA_COMMAND_TRANSPORT_AMBIGUOUS',
+					{ commandId: prepared.commandId, cause: error }
+				);
+			} finally {
+				statusSignals.dispose();
+			}
+			if (!stillCurrent(authority)) {
+				throw new ReplicaCommandRuntimeError(
+					'REPLICA_COMMAND_SCOPE_INVALIDATED',
+					{ commandId: prepared.commandId }
+				);
+			}
+			let status: ReplicaCommandStatus;
+			try {
+				status = requireStatusEnvelope(
+					result,
+					statusArtifact,
+					prepared,
+					authority,
+					contract
+				);
+				validateStatusProgression(tracker.state, tracker.metadata, status);
+			} catch (error) {
+				revalidateInBackground(prepared, authority);
+				throw new ReplicaCommandRuntimeError(
+					'REPLICA_COMMAND_PROTOCOL_INVALID',
+					{ commandId: prepared.commandId, cause: error }
+				);
+			}
+			tracker.state = status.state;
+			if (status.metadata !== undefined) {
+				tracker.metadata = status.metadata;
+				if (tracker.pending !== undefined) {
+					tracker.pending.metadata = status.metadata;
+				}
+			}
+			switch (status.state) {
+				case 'rejected':
+					rejectUnmanagedLayer(prepared.commandId);
+					failTrackedProjection(
+						tracker,
+						pending,
+						new ReplicaCommandRuntimeError(
+							'REPLICA_COMMAND_REJECTED',
+							{
+								commandId: prepared.commandId,
+								state: status.state
+							}
+						)
+					);
+					break;
+				case 'projection_failed':
+				case 'expired':
+					rejectUnmanagedLayer(prepared.commandId);
+					revalidateInBackground(prepared, authority);
+					failTrackedProjection(
+						tracker,
+						pending,
+						new ReplicaCommandRuntimeError(
+							'REPLICA_COMMAND_PROJECTION_FAILED',
+							{
+								commandId: prepared.commandId,
+								state: status.state
+							}
+						)
+					);
+					break;
+				case 'accepted':
+				case 'accepted_pending_projection':
+				case 'projected': {
+					const metadata = status.metadata!;
+					const remainsPending = replica.markOptimisticLayerAccepted(
+						prepared.commandId,
+						metadata
+					);
+					if (!remainsPending) {
+						unmanagedLayers.delete(prepared.commandId);
+						if (tracker.pending !== undefined) {
+							settleTrackedProjection(tracker, pending);
+						}
+					} else if (
+						metadata.state === 'projected' ||
+						(metadata.state === 'accepted' &&
+							prepared.confirmations === undefined &&
+							prepared.revalidation.required)
+					) {
+						/*
+						 * Status is causal truth, but it carries no canonical
+						 * query payload. `projected` fences asynchronous
+						 * projection; `accepted` is terminal when the generated
+						 * contract has no confirmations. In both cases, only a
+						 * query started after that fence may retire optimism.
+						 */
+						let refreshed = false;
+						try {
+							refreshed = await revalidate(
+								prepared,
+								authority.signal
+							);
+						} catch (error) {
+							if (disposed) {
+								throw new ReplicaCommandRuntimeError(
+									'REPLICA_COMMAND_DISPOSED',
+									{
+										commandId: prepared.commandId,
+										cause: error
+									}
+								);
+							}
+							if (
+								authority.signal?.aborted ||
+								!stillCurrent(authority)
+							) {
+								throw new ReplicaCommandRuntimeError(
+									'REPLICA_COMMAND_SCOPE_INVALIDATED',
+									{
+										commandId: prepared.commandId,
+										cause: error
+									}
+								);
+							}
+							// Keep the accepted layer and let the background
+							// status monitor retry the exact generated plan.
+						}
+						if (disposed) {
+							throw new ReplicaCommandRuntimeError(
+								'REPLICA_COMMAND_DISPOSED',
+								{ commandId: prepared.commandId }
+							);
+						}
+						if (
+							authority.signal?.aborted ||
+							!stillCurrent(authority)
+						) {
+							throw new ReplicaCommandRuntimeError(
+								'REPLICA_COMMAND_SCOPE_INVALIDATED',
+								{ commandId: prepared.commandId }
+							);
+						}
+						const controller = tracker.pending;
+						if (refreshed) {
+							if (
+								controller !== undefined &&
+								!controller.settled &&
+								pending.get(prepared.commandId) === controller
+							) {
+								retireLayerAfterAuthoritativeRevalidation(
+									prepared.commandId
+								);
+								settleTrackedProjection(tracker, pending);
+							} else if (
+								unmanagedLayers.has(prepared.commandId)
+							) {
+								/*
+								 * Recovery receipts and commands without a
+								 * finite projection awaitable have no
+								 * PendingProjection controller. The same
+								 * post-status canonical fetch still owns
+								 * retirement of their retained overlay.
+								 */
+								retireLayerAfterAuthoritativeRevalidation(
+									prepared.commandId
+								);
+							}
+						}
+					}
+					break;
+				}
+				case 'unknown':
+				case 'in_progress':
+					break;
+			}
+			return status;
+		};
+		return () => {
+			if (tracker.inFlight !== undefined) return tracker.inFlight;
+			let current: Promise<ReplicaCommandStatus>;
+			current = read().finally(() => {
+				if (tracker.inFlight === current) tracker.inFlight = undefined;
+			});
+			tracker.inFlight = current;
+			return current;
+		};
+	};
+
+	const invoke = async <TInput, TOutput>(
+		artifact: ReplicaCommandArtifact<TInput, TOutput>,
+		input: TInput,
+		callOptions: ReplicaCommandCallOptions<TOutput>
+	): Promise<ReplicaCommandReceipt<TOutput>> => {
+		const authority = currentAuthority();
+		const prepared = prepareReplicaCommandWithTrustedPresets(
+			artifact,
+			input,
+			authority.trustedPresets,
+			callOptions
+		);
+		const transportRetries = normalizeRetries(callOptions.transportRetries);
+		const semanticChanges = preparedSemanticChanges(prepared);
+		const requestSignals = linkAbortSignals([
+			authority.signal,
+			callOptions.signal,
+			runtimeAbort.signal
+		]);
+		const request = commandTransportRequest(prepared, requestSignals.signal);
+		if (request.signal?.aborted) {
+			requestSignals.dispose();
+			throw new ReplicaCommandRuntimeError(
+				stillCurrent(authority)
+					? 'REPLICA_COMMAND_ABORTED'
+					: 'REPLICA_COMMAND_SCOPE_INVALIDATED',
+				{ commandId: prepared.commandId, cause: request.signal.reason }
+			);
+		}
+		try {
+			(replica as SemanticReplica).createOptimisticLayer(
+				prepared.commandId,
+				(writer) =>
+					applyOptimisticEffects(writer, prepared.optimistic.operations),
+				semanticChanges
+			);
+		} catch (error) {
+			requestSignals.dispose();
+			throw error;
+		}
+		unmanagedLayers.add(prepared.commandId);
+
+		const statusTracker: CommandStatusTracker = {
+			state: undefined,
+			metadata: undefined,
+			inFlight: undefined
+		};
+		const readStatus = statusReader(prepared, authority, statusTracker);
+		const recovery: ReplicaCommandRecoveryReceipt<TOutput> = Object.freeze({
+			commandId: prepared.commandId,
+			status: readStatus
+		});
+		const recoveryForRetainedLayer = (
+			revalidateOnRollback = false
+		): ReplicaCommandRecoveryReceipt<TOutput> | undefined => {
+			if (statusArtifact !== undefined) return recovery;
+			/*
+			 * A manual status-less runtime cannot make an ambiguous layer
+			 * reachable again. Roll it back and let generated revalidation
+			 * restore canonical truth instead of leaking optimism forever.
+			 */
+			rejectUnmanagedLayer(prepared.commandId);
+			if (revalidateOnRollback) {
+				revalidateInBackground(prepared, authority);
+			}
+			return undefined;
+		};
+		let result: ReplicaCommandTransportResult;
+		let dispatchAttempted = false;
+		try {
+			result = await dispatchPrepared(
+				transport,
+				request,
+				transportRetries,
+				() => {
+					dispatchAttempted = true;
+				}
+			);
+		} catch (error) {
+			if (disposed) {
+				rejectUnmanagedLayer(prepared.commandId);
+				throw new ReplicaCommandRuntimeError(
+					'REPLICA_COMMAND_DISPOSED',
+					{ commandId: prepared.commandId, cause: error }
+				);
+			}
+			if (!dispatchAttempted) {
+				rejectUnmanagedLayer(prepared.commandId);
+				throw new ReplicaCommandRuntimeError(
+					stillCurrent(authority)
+						? 'REPLICA_COMMAND_ABORTED'
+						: 'REPLICA_COMMAND_SCOPE_INVALIDATED',
+					{ commandId: prepared.commandId, cause: error }
+				);
+			}
+			if (!stillCurrent(authority)) {
+				rejectUnmanagedLayer(prepared.commandId);
+				throw new ReplicaCommandRuntimeError(
+					'REPLICA_COMMAND_SCOPE_INVALIDATED',
+					{ commandId: prepared.commandId, cause: error }
+				);
+			}
+			throw new ReplicaCommandRuntimeError(
+				request.signal?.aborted
+					? 'REPLICA_COMMAND_ABORTED'
+					: 'REPLICA_COMMAND_TRANSPORT_AMBIGUOUS',
+				{
+					commandId: prepared.commandId,
+					cause: error,
+					recovery: recoveryForRetainedLayer(true)
+				}
+			);
+		} finally {
+			requestSignals.dispose();
+		}
+
+		if (!stillCurrent(authority)) {
+			rejectUnmanagedLayer(prepared.commandId);
+			throw new ReplicaCommandRuntimeError(
+				'REPLICA_COMMAND_SCOPE_INVALIDATED',
+				{ commandId: prepared.commandId }
+			);
+		}
+
+		const rejection = graphqlCommandRejection(result);
+		if (rejection !== undefined) {
+			try {
+				const rejectionEnvelope = requireCommandRejectionEnvelope(
+					result,
+					prepared,
+					authority
+				);
+				matchReplicaTrustedPresetInventory(
+					contract.trustedPresets,
+					rejectionEnvelope.trustedPresets
+				);
+			} catch (error) {
+				revalidateInBackground(prepared, authority);
+				throw new ReplicaCommandRuntimeError(
+					'REPLICA_COMMAND_PROTOCOL_INVALID',
+					{
+						commandId: prepared.commandId,
+						cause: error,
+						recovery: recoveryForRetainedLayer()
+					}
+				);
+			}
+			rejectUnmanagedLayer(prepared.commandId);
+			throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_REJECTED', {
+				commandId: prepared.commandId,
+				cause: new Error(rejection.message)
+			});
+		}
+
+		let distributed: DistributedProtocolEnvelope;
+		try {
+			distributed = requireCommandEnvelope(result, prepared, authority);
+			matchReplicaTrustedPresetInventory(
+				contract.trustedPresets,
+				distributed.trustedPresets
+			);
+		} catch (error) {
+			revalidateInBackground(prepared, authority);
+			throw new ReplicaCommandRuntimeError(
+				'REPLICA_COMMAND_PROTOCOL_INVALID',
+				{
+					commandId: prepared.commandId,
+					cause: error,
+					recovery: recoveryForRetainedLayer()
+				}
+			);
+		}
+
+		const metadata = distributed.command!;
+		statusTracker.state = metadata.state;
+		statusTracker.metadata = metadata;
+		if (metadata.state === 'rejected') {
+			rejectUnmanagedLayer(prepared.commandId);
+			throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_REJECTED', {
+				commandId: prepared.commandId,
+				state: metadata.state
+			});
+		}
+		if (metadata.state === 'expired') {
+			rejectUnmanagedLayer(prepared.commandId);
+			revalidateInBackground(prepared, authority);
+			throw new ReplicaCommandRuntimeError(
+				'REPLICA_COMMAND_PROJECTION_FAILED',
+				{ commandId: prepared.commandId, state: metadata.state }
+			);
+		}
+		if (metadata.state === 'unknown' || metadata.state === 'in_progress') {
+			throw new ReplicaCommandRuntimeError(
+				'REPLICA_COMMAND_OUTCOME_PENDING',
+				{
+					commandId: prepared.commandId,
+					state: metadata.state,
+					recovery: recoveryForRetainedLayer(true)
+				}
+			);
+		}
+		if (metadata.state === 'projection_failed') {
+			rejectUnmanagedLayer(prepared.commandId);
+			revalidateInBackground(prepared, authority);
+			throw new ReplicaCommandRuntimeError(
+				'REPLICA_COMMAND_PROJECTION_FAILED',
+				{ commandId: prepared.commandId, state: metadata.state }
+			);
+		}
+		if ((result.errors?.length ?? 0) > 0) {
+			let retainedRecovery: ReplicaCommandRecoveryReceipt<TOutput> | undefined;
+			if (prepared.confirmations?.kind === 'finite') {
+				replica.markOptimisticLayerAccepted(prepared.commandId, metadata);
+				retainedRecovery = recoveryForRetainedLayer();
+			} else {
+				rejectUnmanagedLayer(prepared.commandId);
+			}
+			revalidateInBackground(prepared, authority);
+			throw new ReplicaCommandRuntimeError(
+				'REPLICA_COMMAND_PROTOCOL_INVALID',
+				{ commandId: prepared.commandId, recovery: retainedRecovery }
+			);
+		}
+
+		let output: TOutput;
+		try {
+			output = commandOutput(
+				artifact,
+				result.data,
+				prepared.transport.mutationField
+			) as TOutput;
+		} catch (error) {
+			let retainedRecovery: ReplicaCommandRecoveryReceipt<TOutput> | undefined;
+			if (
+				prepared.consistency === 'projected' ||
+				prepared.confirmations?.kind !== 'finite'
+			) {
+				rejectUnmanagedLayer(prepared.commandId);
+			} else {
+				replica.markOptimisticLayerAccepted(prepared.commandId, metadata);
+				retainedRecovery = recoveryForRetainedLayer();
+			}
+			revalidateInBackground(prepared, authority);
+			throw new ReplicaCommandRuntimeError(
+				'REPLICA_COMMAND_PROTOCOL_INVALID',
+				{
+					commandId: prepared.commandId,
+					cause: error,
+					recovery: retainedRecovery
+				}
+			);
+		}
+		let projected:
+			| Promise<ReplicaCommandProjectedOutcome<TOutput>>
+			| undefined;
+		let projectionLifecycle:
+			| Promise<ReplicaCommandProjectedOutcome<TOutput>>
+			| undefined;
+		if (prepared.consistency === 'projected') {
+			if (metadata.state !== 'projected') {
+				throw new ReplicaCommandRuntimeError(
+					'REPLICA_COMMAND_OUTCOME_PENDING',
+					{
+						commandId: prepared.commandId,
+						state: metadata.state,
+						recovery: recoveryForRetainedLayer(true)
+					}
+				);
+			}
+			try {
+				confirmDirectProjection(replica, prepared, output, metadata);
+				unmanagedLayers.delete(prepared.commandId);
+			} catch (error) {
+				rejectUnmanagedLayer(prepared.commandId);
+				revalidateInBackground(prepared, authority);
+				throw new ReplicaCommandRuntimeError(
+					'REPLICA_COMMAND_PROTOCOL_INVALID',
+					{ commandId: prepared.commandId, cause: error }
+				);
+			}
+			projected = Promise.resolve(
+				Object.freeze({
+					commandId: prepared.commandId,
+					state: 'projected' as const,
+					result: output,
+					metadata
+				})
+			);
+		} else {
+			const remainsPending = replica.markOptimisticLayerAccepted(
+				prepared.commandId,
+				metadata
+			);
+			if (prepared.confirmations?.kind === 'finite') {
+				const controller = pendingProjection(
+					authority,
+					metadata,
+					prepared as ReplicaPreparedCommand<unknown, unknown>
+				);
+				statusTracker.pending = controller;
+				if (!remainsPending) {
+					unmanagedLayers.delete(prepared.commandId);
+					settleProjectionSuccess(controller);
+				} else {
+					/*
+					 * Receipt/status observations prove durable causality, not
+					 * that canonical query data was atomically ingested. Keep
+					 * the layer and await DistributedReplica retirement even
+					 * when every observation is already present here.
+					 */
+					pending.set(prepared.commandId, controller);
+					unmanagedLayers.delete(prepared.commandId);
+					attachAuthorityAbort(controller, () =>
+						pending.delete(prepared.commandId)
+					);
+					if (
+						statusArtifact !== undefined &&
+						replicaRevalidate !== undefined
+					) {
+						monitorPendingProjection(
+							controller,
+							readStatus,
+							() => pending.get(prepared.commandId) === controller,
+							options.onBackgroundError
+						);
+					}
+				}
+				projectionLifecycle =
+					controller.promise as Promise<
+						ReplicaCommandProjectedOutcome<TOutput>
+					>;
+				projected = callerProjectedPromise(
+					controller,
+					callOptions.signal
+				) as Promise<ReplicaCommandProjectedOutcome<TOutput>>;
+			}
+		}
+
+		if (prepared.revalidation.required) {
+			revalidateAndConfirmUnmanagedInBackground(prepared, authority);
+		}
+
+		const receiptValue = {
+			commandId: prepared.commandId,
+			state: metadata.state as ReplicaCommandReceipt<TOutput>['state'],
+			result: output,
+			metadata,
+			status: readStatus,
+			...(projected === undefined ? {} : { projected })
+		};
+		if (projectionLifecycle !== undefined) {
+			Object.defineProperty(receiptValue, replicaCommandProjectedLifecycle, {
+				value: projectionLifecycle,
+				enumerable: false,
+				configurable: false,
+				writable: false
+			});
+		}
+		const receipt = Object.freeze(
+			receiptValue
+		) as ReplicaCommandReceipt<TOutput>;
+		try {
+			await callOptions.onAccepted?.(receipt);
+		} catch (error) {
+			options.onBackgroundError?.(error);
+		}
+		return receipt;
+	};
+
+	const commands: Record<string, unknown> = Object.create(null) as Record<
+		string,
+		unknown
+	>;
+	for (const { key, artifact } of inventory) {
+		defineBoundCommand(
+			commands,
+			key,
+			artifact.input.kind === 'none'
+				? (callOptions: ReplicaCommandCallOptions<unknown> = {}) =>
+						invoke(artifact, undefined, callOptions)
+				: (
+						input: unknown,
+						callOptions: ReplicaCommandCallOptions<unknown> = {}
+					) => invoke(artifact, input, callOptions)
+		);
+	}
+	freezeCommandTree(commands);
+
+	const observeResult = (envelope: ReplicaResultEnvelope<unknown>): void => {
+		if (disposed || pending.size === 0) return;
+		let distributed: DistributedProtocolEnvelope | undefined;
+		try {
+			distributed = parseGraphqlResponseExtensions(envelope.extensions)
+				?.distributed;
+		} catch (error) {
+			options.onBackgroundError?.(error);
+			return;
+		}
+		if (distributed === undefined) return;
+		for (const [commandId, controller] of pending) {
+			if (!stillCurrent(controller.authority)) {
+				settleProjectionFailure(
+					controller,
+					new ReplicaCommandRuntimeError(
+						'REPLICA_COMMAND_SCOPE_INVALIDATED',
+						{ commandId }
+					)
+				);
+				pending.delete(commandId);
+				continue;
+			}
+			if (
+				distributed.schemaHash !== controller.authority.scope.schemaHash ||
+				distributed.cacheScope !== controller.authority.scope.cacheScope
+			) {
+				continue;
+			}
+			const command = distributed.command;
+			if (command?.commandId === commandId) {
+				try {
+					verifyReplicaCommandReceipt(controller.prepared, command);
+				} catch (error) {
+					revalidateInBackground(
+						controller.prepared,
+						controller.authority
+					);
+					settleProjectionFailure(
+						controller,
+						new ReplicaCommandRuntimeError(
+							'REPLICA_COMMAND_PROTOCOL_INVALID',
+							{ commandId, cause: error }
+						)
+					);
+					pending.delete(commandId);
+					continue;
+				}
+				if (command.causationId !== controller.causationId) {
+					settleProjectionFailure(
+						controller,
+						new ReplicaCommandRuntimeError(
+							'REPLICA_COMMAND_PROTOCOL_INVALID',
+							{ commandId }
+						)
+					);
+					pending.delete(commandId);
+					continue;
+				}
+				controller.metadata = command;
+				if (command.state === 'projection_failed') {
+					replica.rejectOptimisticLayer(commandId);
+					revalidateInBackground(
+						controller.prepared,
+						controller.authority
+					);
+					settleProjectionFailure(
+						controller,
+						new ReplicaCommandRuntimeError(
+							'REPLICA_COMMAND_PROJECTION_FAILED',
+							{ commandId, state: command.state }
+						)
+					);
+					pending.delete(commandId);
+					continue;
+				}
+				if (
+					command.state === 'rejected' ||
+					command.state === 'expired'
+				) {
+					replica.rejectOptimisticLayer(commandId);
+					revalidateInBackground(
+						controller.prepared,
+						controller.authority
+					);
+					settleProjectionFailure(
+						controller,
+						new ReplicaCommandRuntimeError(
+							command.state === 'rejected'
+								? 'REPLICA_COMMAND_REJECTED'
+								: 'REPLICA_COMMAND_PROJECTION_FAILED',
+							{ commandId, state: command.state }
+						)
+					);
+					pending.delete(commandId);
+					continue;
+				}
+			}
+			/*
+			 * DistributedReplica is the authority on whether this frame's
+			 * snapshot/observations were admissible. This callback runs only
+			 * after that exact frame committed.
+			 */
+			const remainsPending =
+				replica.markOptimisticLayerAccepted(commandId);
+			if (!remainsPending) {
+				settleProjectionSuccess(controller);
+				pending.delete(commandId);
+			}
+		}
+	};
+	const observationRegistration =
+		replica[replicaResultObservation]?.(observeResult);
+
+	return Object.freeze({
+		commands: commands as ReplicaBoundCommands<TEntries>,
+		observeResult,
+		dispose(): void {
+			if (disposed) return;
+			disposed = true;
+			runtimeAbort.abort(
+				new ReplicaCommandRuntimeError('REPLICA_COMMAND_DISPOSED')
+			);
+			observationRegistration?.dispose();
+			registration?.dispose();
+			for (const commandId of unmanagedLayers) {
+				replica.rejectOptimisticLayer(commandId);
+			}
+			unmanagedLayers.clear();
+			for (const [commandId, controller] of pending) {
+				replica.rejectOptimisticLayer(commandId);
+				settleProjectionFailure(
+					controller,
+					new ReplicaCommandRuntimeError('REPLICA_COMMAND_DISPOSED', {
+						commandId
+					})
+				);
+			}
+			pending.clear();
+		}
+	});
+}
diff --git a/js/src/replica/command-runtime/errors.ts b/js/src/replica/command-runtime/errors.ts
new file mode 100644
index 00000000..8691112c
--- /dev/null
+++ b/js/src/replica/command-runtime/errors.ts
@@ -0,0 +1,59 @@
+import type { DistributedCommandState } from '../../protocol.js';
+import type {
+	ReplicaCommandRecoveryReceipt,
+	ReplicaCommandRuntimeErrorCode
+} from './types.js';
+
+export function commandRuntimeErrorMessage(
+	code: ReplicaCommandRuntimeErrorCode
+): string {
+	switch (code) {
+		case 'REPLICA_COMMAND_ABORTED':
+			return 'Caller aborted command dispatch or projection visibility wait';
+		case 'REPLICA_COMMAND_AUTHORITY_UNAVAILABLE':
+			return 'Command dispatch requires a current authoritative replica scope';
+		case 'REPLICA_COMMAND_DISPOSED':
+			return 'Command runtime is disposed';
+		case 'REPLICA_COMMAND_OUTCOME_PENDING':
+			return 'Command outcome remains pending';
+		case 'REPLICA_COMMAND_PROJECTION_FAILED':
+			return 'Command projection failed';
+		case 'REPLICA_COMMAND_PROTOCOL_INVALID':
+			return 'Command response violated the generated protocol contract';
+		case 'REPLICA_COMMAND_REJECTED':
+			return 'Command was rejected';
+			case 'REPLICA_COMMAND_SCOPE_INVALIDATED':
+				return 'Command authorization scope changed';
+			case 'REPLICA_COMMAND_STATUS_UNAVAILABLE':
+				return 'Generated command status transport is unavailable';
+			case 'REPLICA_COMMAND_TRANSPORT_AMBIGUOUS':
+				return 'Command transport outcome is ambiguous';
+		}
+}
+
+/** Redacted typed failure from the integrated generated-command lifecycle. */
+export class ReplicaCommandRuntimeError extends Error {
+	readonly code: ReplicaCommandRuntimeErrorCode;
+	readonly commandId?: string;
+	readonly state?: DistributedCommandState;
+	readonly recovery?: ReplicaCommandRecoveryReceipt;
+
+	constructor(
+		code: ReplicaCommandRuntimeErrorCode,
+		options: Readonly<{
+			commandId?: string;
+			state?: DistributedCommandState;
+			cause?: unknown;
+			recovery?: ReplicaCommandRecoveryReceipt;
+		}> = {}
+	) {
+		super(commandRuntimeErrorMessage(code), {
+			...(options.cause === undefined ? {} : { cause: options.cause })
+		});
+		this.name = 'ReplicaCommandRuntimeError';
+		this.code = code;
+		this.commandId = options.commandId;
+		this.state = options.state;
+		this.recovery = options.recovery;
+	}
+}
diff --git a/js/src/replica/command-runtime/index.ts b/js/src/replica/command-runtime/index.ts
new file mode 100644
index 00000000..6256f959
--- /dev/null
+++ b/js/src/replica/command-runtime/index.ts
@@ -0,0 +1,32 @@
+export {
+	replicaCommandAuthority,
+	replicaCommandDirectProjection,
+	replicaCommandProjectedLifecycle,
+	replicaResultObservation
+} from './symbols.js';
+export type {
+	ReplicaBoundCommand,
+	ReplicaBoundCommands,
+	ReplicaCommandAuthorityHost,
+	ReplicaCommandAuthorityRegistration,
+	ReplicaCommandAuthoritySnapshot,
+	ReplicaCommandCallOptions,
+	ReplicaCommandDirectProjection,
+	ReplicaCommandProjectedOutcome,
+	ReplicaCommandReceipt,
+	ReplicaCommandRecoveryReceipt,
+	ReplicaCommandRuntime,
+	ReplicaCommandRuntimeErrorCode,
+	ReplicaCommandRuntimeOptions,
+	ReplicaCommandStatus,
+	ReplicaCommandStatusArtifact,
+	ReplicaCommandStatusRequest,
+	ReplicaCommandSurfaceContract,
+	ReplicaCommandTransport,
+	ReplicaCommandTransportRequest,
+	ReplicaCommandTransportResult,
+	ReplicaResultObservationRegistration
+} from './types.js';
+export { ReplicaCommandRuntimeError } from './errors.js';
+export { replicaCommandProjectedLifecycleOf } from './lifecycle.js';
+export { createReplicaCommandRuntime } from './create.js';
diff --git a/js/src/replica/command-runtime/lib/binding.ts b/js/src/replica/command-runtime/lib/binding.ts
new file mode 100644
index 00000000..0d966dbc
--- /dev/null
+++ b/js/src/replica/command-runtime/lib/binding.ts
@@ -0,0 +1,76 @@
+import { isPlainRecord } from '../../../lib/is-plain-record.js';
+
+export function defineBoundCommand(
+	root: Record<string, unknown>,
+	path: string,
+	command: unknown
+): void {
+	const segments = commandPathSegments(path);
+	let namespace = root;
+	for (let index = 0; index < segments.length; index += 1) {
+		const segment = segments[index]!;
+		const leaf = index === segments.length - 1;
+		const exists = Object.prototype.hasOwnProperty.call(namespace, segment);
+		if (leaf) {
+			if (exists) commandNamespaceCollision(path);
+			Object.defineProperty(namespace, segment, {
+				enumerable: true,
+				configurable: false,
+				writable: false,
+				value: command
+			});
+			continue;
+		}
+		if (exists) {
+			const value = namespace[segment];
+			if (!isPlainRecord(value)) commandNamespaceCollision(path);
+			namespace = value as Record<string, unknown>;
+			continue;
+		}
+		const child = Object.create(null) as Record<string, unknown>;
+		Object.defineProperty(namespace, segment, {
+			enumerable: true,
+			configurable: false,
+			writable: false,
+			value: child
+		});
+		namespace = child;
+	}
+}
+
+export function commandPathSegments(path: string): readonly string[] {
+	if (path.length === 0 || path.length > 512) {
+		throw new TypeError('replica command path is invalid');
+	}
+	const segments = path.split('.');
+	if (
+		segments.length > 64 ||
+		segments.some(
+			(segment) =>
+				segment.length === 0 ||
+				segment.length > 128 ||
+				segment.trim() !== segment ||
+				/[\u0000-\u001f\u007f-\u009f]/.test(segment) ||
+				segment === '__proto__' ||
+				segment === 'prototype' ||
+				segment === 'constructor'
+		)
+	) {
+		throw new TypeError(`replica command path ${path} is invalid`);
+	}
+	return Object.freeze(segments);
+}
+
+export function commandNamespaceCollision(path: string): never {
+	throw new TypeError(`replica command namespace collision at ${path}`);
+}
+
+export function freezeCommandTree(value: Record<string, unknown>): void {
+	for (const child of Object.values(value)) {
+		if (isPlainRecord(child)) {
+			freezeCommandTree(child as Record<string, unknown>);
+		}
+	}
+	Object.freeze(value);
+}
+
diff --git a/js/src/replica/command-runtime/lib/effects.ts b/js/src/replica/command-runtime/lib/effects.ts
new file mode 100644
index 00000000..b4ff3b80
--- /dev/null
+++ b/js/src/replica/command-runtime/lib/effects.ts
@@ -0,0 +1,141 @@
+import {
+	type ReplicaPreparedCommand,
+	type ReplicaPreparedCommandEffect,
+	type ReplicaPreparedEffectKey
+} from '../../commands.js';
+import { replicaRecordKey } from '../../identity.js';
+import type { ReplicaIndexSemanticChange } from '../../index-maintenance.js';
+import type {
+	ReplicaModelArtifact,
+	ReplicaOptimisticWriter,
+	ReplicaValue
+} from '../../types.js';
+
+export function applyOptimisticEffects(
+	writer: ReplicaOptimisticWriter,
+	effects: readonly ReplicaPreparedCommandEffect[]
+): void {
+	for (const effect of effects) {
+		switch (effect.kind) {
+			case 'upsert':
+			case 'patch': {
+				const model = modelFromKey(effect.model, effect.key);
+				writer.writeRecord(model, identityFromKey(effect.key), {
+					fields: fieldsFromEffect(effect.model, effect.key, effect.fields)
+				});
+				break;
+			}
+			case 'delete':
+				writer.tombstoneRecord(
+					modelFromKey(effect.model, effect.key),
+					identityFromKey(effect.key)
+				);
+				break;
+			case 'link':
+			case 'unlink':
+			case 'invalidate_model':
+			case 'invalidate_relationship':
+				// Task 8 consumes the exact semantic context. Guessing a to-one
+				// record link for a to-many relationship would corrupt truth.
+				break;
+		}
+	}
+}
+
+export function preparedSemanticChanges<TInput, TOutput>(
+	prepared: ReplicaPreparedCommand<TInput, TOutput>
+): readonly ReplicaIndexSemanticChange[] {
+	const dependencies = Object.freeze([...prepared.revalidation.dependencies]);
+	const changes: ReplicaIndexSemanticChange[] = [];
+	for (const effect of prepared.optimistic.operations) {
+		switch (effect.kind) {
+			case 'upsert':
+			case 'patch':
+			case 'delete':
+				// DistributedReplica captures ordinary writer mutations into the
+				// same layer context. Supplying them again would double-apply the
+				// semantic record operation.
+				break;
+			case 'link':
+			case 'unlink': {
+				const source = modelFromKey(
+					effect.relationship.sourceModel,
+					effect.source
+				);
+				const target = modelFromKey(
+					effect.relationship.targetModel,
+					effect.target
+				);
+				changes.push(
+					Object.freeze({
+						kind: effect.kind,
+						sourceModel: effect.relationship.sourceModel,
+						field: effect.relationship.field,
+						targetModel: effect.relationship.targetModel,
+						sourceKey: replicaRecordKey(
+							source,
+							identityFromKey(effect.source)
+						),
+						targetKey: replicaRecordKey(
+							target,
+							identityFromKey(effect.target)
+						),
+						dependencies
+					})
+				);
+				break;
+			}
+			case 'invalidate_model':
+			case 'invalidate_relationship':
+				changes.push(
+					Object.freeze({
+						kind: 'invalidate',
+						dependencies
+					})
+				);
+				break;
+		}
+	}
+	return Object.freeze(changes);
+}
+
+export function modelFromKey(
+	model: string,
+	key: ReplicaPreparedEffectKey
+): ReplicaModelArtifact {
+	return Object.freeze({
+		id: model,
+		identityFields: Object.freeze(key.fields.map(({ field }) => field))
+	});
+}
+
+export function identityFromKey(
+	key: ReplicaPreparedEffectKey
+): readonly ReplicaValue[] {
+	return Object.freeze(key.fields.map(({ value }) => value));
+}
+
+export function fieldsFromEffect(
+	model: string,
+	key: ReplicaPreparedEffectKey,
+	fields: readonly { readonly field: string; readonly value: ReplicaValue }[]
+): Readonly<Record<string, ReplicaValue>> {
+	const result: Record<string, ReplicaValue> = Object.create(null) as Record<
+		string,
+		ReplicaValue
+	>;
+	for (const field of [
+		{ field: '__typename', value: model },
+		...key.fields,
+		...fields
+	]) {
+		Object.defineProperty(result, field.field, {
+			enumerable: true,
+			configurable: false,
+			writable: false,
+			value: field.value
+		});
+	}
+	return Object.freeze(result);
+}
+
diff --git a/js/src/replica/command-runtime/lib/index.ts b/js/src/replica/command-runtime/lib/index.ts
new file mode 100644
index 00000000..b5c6769e
--- /dev/null
+++ b/js/src/replica/command-runtime/lib/index.ts
@@ -0,0 +1,9 @@
+/** Command-runtime support modules (inventory, transport, projection, …). */
+export * from './inventory.js';
+export * from './binding.js';
+export * from './effects.js';
+export * from './transport.js';
+export * from './status.js';
+export * from './output.js';
+export * from './projection.js';
+export * from './util.js';
diff --git a/js/src/replica/command-runtime/lib/inventory.ts b/js/src/replica/command-runtime/lib/inventory.ts
new file mode 100644
index 00000000..eae7da07
--- /dev/null
+++ b/js/src/replica/command-runtime/lib/inventory.ts
@@ -0,0 +1,228 @@
+import {
+	isDistributedTrustedPresetCodec
+} from '../../../protocol.js';
+import {
+	type ReplicaTrustedPresetDescriptor
+} from '../../commands.js';
+import {
+	SHA256
+} from '../constants.js';
+import type {
+	AnyCommandArtifact,
+	CommandEntry,
+	ReplicaCommandStatusArtifact,
+	ReplicaCommandSurfaceContract
+} from '../types.js';
+import { compareCodeUnits } from '../../../lib/compare-code-units.js';
+import {
+	commandNamespaceCollision,
+	commandPathSegments
+} from './binding.js';
+import {
+	cloneSurface,
+	sameSurface
+} from './util.js';
+export function normalizeInventory<TEntries extends Readonly<Record<string, CommandEntry>>>(
+	entries: TEntries
+): readonly { readonly key: string; readonly artifact: AnyCommandArtifact }[] {
+	if (entries === null || typeof entries !== 'object' || Array.isArray(entries)) {
+		throw new TypeError('replica command inventory must be an object');
+	}
+	const names = new Set<string>();
+	const inventory = Object.entries(entries).map(([key, entry]) => {
+		commandPathSegments(key);
+		const artifact = 'artifact' in entry ? entry.artifact : entry;
+		if (names.has(artifact.name)) {
+			throw new TypeError(`duplicate replica command artifact ${artifact.name}`);
+		}
+		names.add(artifact.name);
+		return Object.freeze({ key, artifact });
+	});
+	const sortedPaths = inventory.map(({ key }) => key).sort(compareCodeUnits);
+	for (let index = 1; index < sortedPaths.length; index += 1) {
+		const previous = sortedPaths[index - 1]!;
+		const current = sortedPaths[index]!;
+		if (current.startsWith(`${previous}.`)) {
+			commandNamespaceCollision(current);
+		}
+	}
+	return Object.freeze(inventory);
+}
+
+export function commandSurfaceContract(
+	artifacts: readonly AnyCommandArtifact[],
+	surfacePresets: readonly ReplicaTrustedPresetDescriptor[] | undefined
+): ReplicaCommandSurfaceContract {
+	if (artifacts.length === 0) {
+		throw new TypeError('replica command inventory must not be empty');
+	}
+	const first = artifacts[0]!;
+	const protocol = first.protocol;
+	if (protocol.surface === undefined) {
+		throw new TypeError('generated command protocol requires a client surface');
+	}
+	const trustedPresets = normalizePresetDescriptors(
+		protocol.trustedPresets,
+		'artifact.protocol.trustedPresets'
+	);
+	const commandPresets = new Map<string, ReplicaTrustedPresetDescriptor>();
+	for (const artifact of artifacts) {
+		if (
+			artifact.protocol.version !== 1 ||
+			artifact.protocol.schemaHash !== protocol.schemaHash ||
+			artifact.protocol.protocolHash !== protocol.protocolHash ||
+			!sameSurface(artifact.protocol.surface, protocol.surface) ||
+			!samePresetDescriptors(
+				normalizePresetDescriptors(
+					artifact.protocol.trustedPresets,
+					'artifact.protocol.trustedPresets'
+				),
+				trustedPresets
+			)
+		) {
+			throw new TypeError(
+				'replica command inventory spans incompatible client surfaces'
+			);
+		}
+		for (const descriptor of artifact.trustedPresets ?? []) {
+			const previous = commandPresets.get(descriptor.name);
+			if (previous !== undefined && previous.codec !== descriptor.codec) {
+				throw new TypeError(
+					`trusted preset ${descriptor.name} has conflicting codecs`
+				);
+			}
+			commandPresets.set(
+				descriptor.name,
+				Object.freeze({ name: descriptor.name, codec: descriptor.codec })
+			);
+		}
+	}
+	if (
+		surfacePresets !== undefined &&
+		!samePresetDescriptors(
+			normalizePresetDescriptors(
+				surfacePresets,
+				'status.protocol.trustedPresets'
+			),
+			trustedPresets
+		)
+	) {
+		throw new TypeError(
+			'generated command status inventory does not match its client surface'
+		);
+	}
+	const surfaceByName = new Map(
+		trustedPresets.map((descriptor) => [descriptor.name, descriptor] as const)
+	);
+	for (const descriptor of commandPresets.values()) {
+		if (surfaceByName.get(descriptor.name)?.codec !== descriptor.codec) {
+			throw new TypeError(
+				`command trusted preset ${descriptor.name} is absent from the client surface`
+			);
+		}
+	}
+	return Object.freeze({
+		protocolVersion: 1,
+		schemaHash: protocol.schemaHash,
+		protocolHash: protocol.protocolHash,
+		surface: cloneSurface(protocol.surface),
+		trustedPresets
+	});
+}
+
+export function commandStatusArtifact(
+	value: ReplicaCommandStatusArtifact,
+	contract: ReplicaCommandSurfaceContract
+): ReplicaCommandStatusArtifact {
+	if (
+		value === null ||
+		typeof value !== 'object' ||
+		typeof value.name !== 'string' ||
+		value.name.trim().length === 0 ||
+		typeof value.document !== 'string' ||
+		value.document.trim().length === 0 ||
+		typeof value.operationHash !== 'string' ||
+		!SHA256.test(value.operationHash) ||
+		value.protocol === null ||
+		typeof value.protocol !== 'object' ||
+		value.protocol.version !== 1 ||
+		value.protocol.operation !== value.operationHash ||
+		value.protocol.schemaHash !== contract.schemaHash ||
+		value.protocol.protocolHash !== contract.protocolHash ||
+		!sameSurface(value.protocol.surface, contract.surface)
+	) {
+		throw new TypeError('generated command status artifact is invalid');
+	}
+	const trustedPresets = normalizePresetDescriptors(
+		value.protocol.trustedPresets,
+		'status.protocol.trustedPresets'
+	);
+	if (!samePresetDescriptors(trustedPresets, contract.trustedPresets)) {
+		throw new TypeError(
+			'generated command status inventory does not match its client surface'
+		);
+	}
+	return Object.freeze({
+		name: value.name,
+		document: value.document,
+		operationHash: value.operationHash,
+		protocol: Object.freeze({
+			version: 1,
+			schemaHash: contract.schemaHash,
+			protocolHash: contract.protocolHash,
+			surface: cloneSurface(contract.surface),
+			operation: value.operationHash,
+			trustedPresets
+		})
+	});
+}
+
+export function normalizePresetDescriptors(
+	value: readonly ReplicaTrustedPresetDescriptor[],
+	path: string
+): readonly ReplicaTrustedPresetDescriptor[] {
+	if (!Array.isArray(value)) {
+		throw new TypeError(`${path} must be an array`);
+	}
+	const names = new Set<string>();
+	const result = value.map((descriptor, index) => {
+		if (
+			descriptor === null ||
+			typeof descriptor !== 'object' ||
+			typeof descriptor.name !== 'string' ||
+			descriptor.name.length === 0 ||
+			descriptor.name.length > 128 ||
+			descriptor.name.trim() !== descriptor.name ||
+			/[\u0000-\u001f\u007f-\u009f]/.test(descriptor.name) ||
+			names.has(descriptor.name) ||
+			!isDistributedTrustedPresetCodec(descriptor.codec)
+		) {
+			throw new TypeError(`${path}[${index}] is invalid`);
+		}
+		names.add(descriptor.name);
+		return Object.freeze({
+			name: descriptor.name,
+			codec: descriptor.codec
+		});
+	});
+	return Object.freeze(
+		result.sort(({ name: left }, { name: right }) =>
+			compareCodeUnits(left, right)
+		)
+	);
+}
+
+export function samePresetDescriptors(
+	left: readonly ReplicaTrustedPresetDescriptor[],
+	right: readonly ReplicaTrustedPresetDescriptor[]
+): boolean {
+	return (
+		left.length === right.length &&
+		left.every(
+			(descriptor, index) =>
+				descriptor.name === right[index]?.name &&
+				descriptor.codec === right[index]?.codec
+		)
+	);
+}
+
diff --git a/js/src/replica/command-runtime/lib/output.ts b/js/src/replica/command-runtime/lib/output.ts
new file mode 100644
index 00000000..7929cd37
--- /dev/null
+++ b/js/src/replica/command-runtime/lib/output.ts
@@ -0,0 +1,254 @@
+import {
+	type DistributedCommandMetadata
+} from '../../../protocol.js';
+import {
+	type ReplicaCommandArtifact
+} from '../../commands.js';
+import type {
+	ReplicaValue
+} from '../../types.js';
+import {
+	MAX_OUTPUT_DEPTH
+} from '../constants.js';
+import { ReplicaCommandRuntimeError } from '../errors.js';
+import { compareCodeUnits } from '../../../lib/compare-code-units.js';
+import { isPlainRecord } from '../../../lib/is-plain-record.js';
+import {
+	comparePropertyKeys,
+	outputInvalid
+} from './util.js';
+export function projectionExpectationFingerprint(
+	value: DistributedCommandMetadata['expects'][number]
+): string {
+	return tupleFingerprint([
+		value.projection,
+		value.model,
+		value.scopeToken
+	]);
+}
+
+export function projectionObservationFingerprint(
+	value: DistributedCommandMetadata['observations'][number]
+): string {
+	return tupleFingerprint([
+		value.causationId,
+		value.projection,
+		value.model,
+		value.scopeToken
+	]);
+}
+
+export function recordRevisionFingerprint(
+	value: DistributedCommandMetadata['records'][number]
+): string {
+	return tupleFingerprint([
+		value.model,
+		value.scopeToken,
+		value.incarnation,
+		value.revision,
+		value.tombstone ? '1' : '0',
+		...(value.path ?? [])
+	]);
+}
+
+export function tupleFingerprint(parts: readonly string[]): string {
+	return parts.map((part) => `${part.length}:${part}`).join('');
+}
+
+export function sameStringMultiset(
+	left: readonly string[],
+	right: readonly string[]
+): boolean {
+	if (left.length !== right.length) return false;
+	const sortedLeft = [...left].sort(compareCodeUnits);
+	const sortedRight = [...right].sort(compareCodeUnits);
+	return sortedLeft.every((value, index) => value === sortedRight[index]);
+}
+
+export function isStringSubset(
+	subset: readonly string[],
+	superset: readonly string[]
+): boolean {
+	const remaining = new Map<string, number>();
+	for (const value of superset) {
+		remaining.set(value, (remaining.get(value) ?? 0) + 1);
+	}
+	for (const value of subset) {
+		const count = remaining.get(value) ?? 0;
+		if (count === 0) return false;
+		remaining.set(value, count - 1);
+	}
+	return true;
+}
+
+export function commandOutput<TInput, TOutput>(
+	artifact: ReplicaCommandArtifact<TInput, TOutput>,
+	data: Readonly<Record<string, unknown>> | null | undefined,
+	field: string
+): unknown {
+	if (
+		data === undefined ||
+		data === null ||
+		!Object.prototype.hasOwnProperty.call(data, field) ||
+		Reflect.ownKeys(data).some((key) => key !== field)
+	) {
+		throw new ReplicaCommandRuntimeError(
+			'REPLICA_COMMAND_PROTOCOL_INVALID'
+		);
+	}
+	return cloneOutputShape(artifact.output, data[field], `data.${field}`, 0);
+}
+
+export function cloneOutputShape(
+	shape: ReplicaCommandArtifact<unknown, unknown>['output'],
+	value: unknown,
+	path: string,
+	depth: number
+): unknown {
+	if (depth > MAX_OUTPUT_DEPTH) outputInvalid(path);
+	if (shape.kind !== 'object') outputInvalid(path);
+	if (!isPlainRecord(value)) outputInvalid(path);
+	const known = new Set(shape.definition.fields.map(({ name }) => name));
+	for (const key of Reflect.ownKeys(value)) {
+		if (typeof key !== 'string' || !known.has(key)) outputInvalid(`${path}.${String(key)}`);
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (descriptor === undefined || !('value' in descriptor)) {
+			outputInvalid(`${path}.${key}`);
+		}
+	}
+	const output: Record<string, unknown> = {};
+	for (const field of shape.definition.fields) {
+		const present =
+			Object.prototype.hasOwnProperty.call(value, field.name) &&
+			value[field.name] !== undefined;
+		if (!present) {
+			outputInvalid(`${path}.${field.name}`);
+		}
+		const fieldValue = value[field.name];
+		if (fieldValue === null) {
+			if (!field.nullable) outputInvalid(`${path}.${field.name}`);
+			output[field.name] = null;
+			continue;
+		}
+		const cloneItem = (item: unknown, itemPath: string): unknown =>
+			field.nested === undefined
+				? cloneOutputScalar(field.codec, item, itemPath)
+				: cloneOutputShape(
+						{ kind: 'object', definition: field.nested },
+						item,
+						itemPath,
+						depth + 1
+					);
+		if (field.list) {
+			if (!Array.isArray(fieldValue)) outputInvalid(`${path}.${field.name}`);
+			output[field.name] = Object.freeze(
+				fieldValue.map((item, index) => {
+					if (item === null) {
+						if (!field.itemNullable) {
+							outputInvalid(`${path}.${field.name}[${index}]`);
+						}
+						return null;
+					}
+					return cloneItem(item, `${path}.${field.name}[${index}]`);
+				})
+			);
+		} else {
+			output[field.name] = cloneItem(fieldValue, `${path}.${field.name}`);
+		}
+	}
+	return Object.freeze(output);
+}
+
+export function cloneOutputScalar(
+	codec: string | undefined,
+	value: unknown,
+	path: string
+): ReplicaValue {
+	switch (codec) {
+		case 'string':
+		case 'string_unvalidated_timestamp':
+		case 'base64':
+			if (typeof value !== 'string') outputInvalid(path);
+			return value;
+		case 'boolean':
+			if (typeof value !== 'boolean') outputInvalid(path);
+			return value;
+		case 'int32':
+			if (
+				typeof value !== 'number' ||
+				!Number.isInteger(value) ||
+				value < -2_147_483_648 ||
+				value > 2_147_483_647
+			) {
+				outputInvalid(path);
+			}
+			return Object.is(value, -0) ? 0 : value;
+		case 'json_number_precision_limited':
+			if (typeof value !== 'number' || !Number.isInteger(value)) {
+				outputInvalid(path);
+			}
+			return Object.is(value, -0) ? 0 : value;
+		case 'float64':
+			if (typeof value !== 'number' || !Number.isFinite(value)) {
+				outputInvalid(path);
+			}
+			return Object.is(value, -0) ? 0 : value;
+		case 'json':
+			return cloneOutputJson(value, path, new Set(), 0);
+		default:
+			outputInvalid(`${path}.codec`);
+	}
+}
+
+export function cloneOutputJson(
+	value: unknown,
+	path: string,
+	active: Set<object>,
+	depth: number
+): ReplicaValue {
+	if (depth > MAX_OUTPUT_DEPTH) outputInvalid(path);
+	if (
+		value === null ||
+		typeof value === 'string' ||
+		typeof value === 'boolean'
+	) {
+		return value;
+	}
+	if (typeof value === 'number') {
+		if (!Number.isFinite(value)) outputInvalid(path);
+		return Object.is(value, -0) ? 0 : value;
+	}
+	if (typeof value !== 'object' || active.has(value)) outputInvalid(path);
+	active.add(value);
+	if (Array.isArray(value)) {
+		const output = Object.freeze(
+			value.map((item, index) =>
+				cloneOutputJson(item, `${path}[${index}]`, active, depth + 1)
+			)
+		);
+		active.delete(value);
+		return output;
+	}
+	if (!isPlainRecord(value)) outputInvalid(path);
+	const output: Record<string, ReplicaValue> = {};
+	for (const key of Reflect.ownKeys(value).sort(comparePropertyKeys)) {
+		if (typeof key !== 'string') outputInvalid(path);
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (
+			descriptor === undefined ||
+			!('value' in descriptor) ||
+			descriptor.value === undefined
+		) {
+			outputInvalid(`${path}.${key}`);
+		}
+		output[key] = cloneOutputJson(
+			descriptor.value,
+			`${path}.${key}`,
+			active,
+			depth + 1
+		);
+	}
+	active.delete(value);
+	return Object.freeze(output);
+}
+
diff --git a/js/src/replica/command-runtime/lib/projection.ts b/js/src/replica/command-runtime/lib/projection.ts
new file mode 100644
index 00000000..91000507
--- /dev/null
+++ b/js/src/replica/command-runtime/lib/projection.ts
@@ -0,0 +1,360 @@
+import {
+	type DistributedCommandMetadata
+} from '../../../protocol.js';
+import {
+	type ReplicaPreparedCommand
+} from '../../commands.js';
+import type {
+	ReplicaBaseWriter,
+	ReplicaModelArtifact,
+	ReplicaValue
+} from '../../types.js';
+import {
+	INITIAL_STATUS_POLL_MS,
+	MAX_STATUS_POLL_MS
+} from '../constants.js';
+import { ReplicaCommandRuntimeError } from '../errors.js';
+import { replicaCommandDirectProjection } from '../symbols.js';
+import type {
+	CapturedAuthority,
+	CommandStatusTracker,
+	PendingProjection,
+	ReplicaCommandAuthorityHost,
+	ReplicaCommandProjectedOutcome,
+	ReplicaCommandStatus
+} from '../types.js';
+import { isPlainRecord } from '../../../lib/is-plain-record.js';
+import {
+	cloneOutputJson
+} from './output.js';
+export function confirmDirectProjection<TInput, TOutput>(
+	replica: ReplicaCommandAuthorityHost,
+	prepared: ReplicaPreparedCommand<TInput, TOutput>,
+	output: TOutput,
+	metadata: DistributedCommandMetadata
+): void {
+	const direct = prepared.directProjection;
+	if (direct === undefined || !isPlainRecord(output)) {
+		throw new ReplicaCommandRuntimeError(
+			'REPLICA_COMMAND_PROTOCOL_INVALID',
+			{ commandId: prepared.commandId }
+		);
+	}
+	const identity: ReplicaValue[] = [];
+	for (const field of direct.identityFields) {
+		const value = output[field];
+		if (value === undefined || value === null) {
+			throw new ReplicaCommandRuntimeError(
+				'REPLICA_COMMAND_PROTOCOL_INVALID',
+				{ commandId: prepared.commandId }
+			);
+		}
+		identity.push(value as ReplicaValue);
+	}
+	const evidence = metadata.records.filter(
+		(record) =>
+			record.model === direct.model &&
+			!record.tombstone &&
+			(
+				record.path === undefined ||
+				(record.path.length === 1 &&
+					record.path[0] === prepared.transport.mutationField)
+			)
+	);
+	if (evidence.length !== 1) {
+		throw new ReplicaCommandRuntimeError(
+			'REPLICA_COMMAND_PROTOCOL_INVALID',
+			{ commandId: prepared.commandId }
+		);
+	}
+	const record = evidence[0]!;
+	const model: ReplicaModelArtifact = Object.freeze({
+		id: direct.model,
+		identityFields: direct.identityFields
+	});
+	const fields = cloneOutputJson(
+		output,
+		'projected.output',
+		new Set(),
+		0
+	) as Readonly<Record<string, ReplicaValue>>;
+	const confirmProtocolProjection = replica[replicaCommandDirectProjection];
+	if (confirmProtocolProjection !== undefined) {
+		confirmProtocolProjection.call(replica, prepared.commandId, {
+			model,
+			identity: Object.freeze(identity),
+			evidence: record,
+			fields
+		});
+		return;
+	}
+	replica.confirmOptimisticLayer(prepared.commandId, (writer: ReplicaBaseWriter) =>
+		writer.writeRecord(model, Object.freeze(identity), record.revision, {
+			incarnation: record.incarnation,
+			fields
+		})
+	);
+}
+
+export function pendingProjection(
+	authority: CapturedAuthority,
+	metadata: DistributedCommandMetadata,
+	prepared: ReplicaPreparedCommand<unknown, unknown>
+): PendingProjection {
+	let resolve!: (value: ReplicaCommandProjectedOutcome<unknown>) => void;
+	let reject!: (error: unknown) => void;
+	const promise = new Promise<ReplicaCommandProjectedOutcome<unknown>>(
+		(resolvePromise, rejectPromise) => {
+			resolve = resolvePromise;
+			reject = rejectPromise;
+		}
+	);
+	/*
+	 * Authority loss or a terminal status can arrive before application code
+	 * receives the accepted receipt. Mark the internal lifecycle promise handled
+	 * eagerly while preserving its rejection for every explicit awaiter.
+	 */
+	void promise.catch(() => undefined);
+	const controller: PendingProjection = {
+		commandId: metadata.commandId,
+		causationId: metadata.causationId,
+		authority,
+		resolve,
+		reject,
+		promise,
+		prepared,
+		metadata,
+		settled: false
+	};
+	return controller;
+}
+
+/**
+ * Generated fact commands converge without application polling. Durable status
+ * is the only completion signal; timers merely schedule reads and never infer a
+ * successful outcome.
+ */
+export function monitorPendingProjection(
+	controller: PendingProjection,
+	readStatus: () => Promise<ReplicaCommandStatus>,
+	retained: () => boolean,
+	reportError: ((error: unknown) => void) | undefined
+): void {
+	if (
+		controller.settled ||
+		!retained() ||
+		projectionAuthorityAborted(controller)
+	) {
+		return;
+	}
+	const monitorAbort = new AbortController();
+	const stopMonitor = () => monitorAbort.abort();
+	controller.stopMonitor = stopMonitor;
+	const signals =
+		controller.authority.signal === undefined
+			? [monitorAbort.signal]
+			: [controller.authority.signal, monitorAbort.signal];
+	void (async () => {
+		try {
+			let delay = INITIAL_STATUS_POLL_MS;
+			while (
+				!controller.settled &&
+				retained() &&
+				!projectionAuthorityAborted(controller)
+			) {
+				await waitForProjectionPoll(delay, signals);
+				if (
+					controller.settled ||
+					!retained() ||
+					projectionAuthorityAborted(controller)
+				) {
+					return;
+				}
+				try {
+					await readStatus();
+				} catch (error) {
+					if (
+						controller.settled ||
+						!retained() ||
+						projectionAuthorityAborted(controller)
+					) {
+						return;
+					}
+					reportBackgroundErrorSafely(reportError, error);
+				}
+				delay = Math.min(delay * 2, MAX_STATUS_POLL_MS);
+			}
+		} finally {
+			if (controller.stopMonitor === stopMonitor) {
+				controller.stopMonitor = undefined;
+			}
+			monitorAbort.abort();
+		}
+	})().catch((error: unknown) =>
+		reportBackgroundErrorSafely(reportError, error)
+	);
+}
+
+export function reportBackgroundErrorSafely(
+	reportError: ((error: unknown) => void) | undefined,
+	error: unknown
+): void {
+	if (reportError === undefined) return;
+	try {
+		reportError(error);
+	} catch {
+		// Error reporting is a terminal boundary and must never reject detached work.
+	}
+}
+
+export function projectionAuthorityAborted(
+	controller: PendingProjection
+): boolean {
+	return controller.authority.signal?.aborted === true;
+}
+
+export function waitForProjectionPoll(
+	delay: number,
+	signals: readonly AbortSignal[]
+): Promise<void> {
+	if (signals.some((signal) => signal.aborted)) return Promise.resolve();
+	return new Promise((resolve) => {
+		let settled = false;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const finish = () => {
+			if (settled) return;
+			settled = true;
+			if (timer !== undefined) clearTimeout(timer);
+			for (const signal of signals) {
+				signal.removeEventListener('abort', finish);
+			}
+			resolve();
+		};
+		timer = setTimeout(finish, delay);
+		/*
+		 * This poll owns the unresolved projected lifecycle. Keep Node's timer
+		 * referenced until projection settlement or runtime disposal calls
+		 * `finish`, which clears the timer and every abort listener.
+		 */
+		for (const signal of signals) {
+			signal.addEventListener('abort', finish, { once: true });
+		}
+		// Close the check/register race if either signal aborted synchronously.
+		if (signals.some((signal) => signal.aborted)) finish();
+	});
+}
+
+export function settleProjectionSuccess(controller: PendingProjection): void {
+	if (controller.settled) return;
+	controller.settled = true;
+	controller.abort?.();
+	controller.stopMonitor?.();
+	controller.resolve(
+		Object.freeze({
+			commandId: controller.commandId,
+			state: 'projected',
+			metadata: controller.metadata
+		})
+	);
+}
+
+export function callerProjectedPromise(
+	controller: PendingProjection,
+	signal: AbortSignal | undefined
+): Promise<ReplicaCommandProjectedOutcome<unknown>> {
+	if (signal === undefined) return controller.promise;
+	const callerSignal = signal;
+	const promise = new Promise<ReplicaCommandProjectedOutcome<unknown>>(
+		(resolve, reject) => {
+			let settled = false;
+			function settle(complete: () => void): void {
+				if (settled) return;
+				settled = true;
+				callerSignal.removeEventListener('abort', onAbort);
+				complete();
+			}
+			function onAbort(): void {
+				/*
+				 * Internal causal settlement wins once selected, even if its
+				 * promise callbacks have not run yet. Caller cancellation never
+				 * mutates that internal lifecycle.
+				 */
+				if (controller.settled) return;
+				settle(() =>
+					reject(
+						new ReplicaCommandRuntimeError('REPLICA_COMMAND_ABORTED', {
+							commandId: controller.commandId
+						})
+					)
+				);
+			}
+			callerSignal.addEventListener('abort', onAbort, { once: true });
+			void controller.promise.then(
+				(value) => settle(() => resolve(value)),
+				(error: unknown) => settle(() => reject(error))
+			);
+			if (callerSignal.aborted) onAbort();
+		}
+	);
+	/*
+	 * An AbortSignal can fire during an async `onAccepted` callback, before the
+	 * receipt reaches caller code. Keep that legitimate rejection observable
+	 * without creating a process-level unhandled-rejection race.
+	 */
+	void promise.catch(() => undefined);
+	return promise;
+}
+
+export function attachAuthorityAbort(
+	controller: PendingProjection,
+	onSettled: () => void
+): void {
+	const signal = controller.authority.signal;
+	if (signal === undefined) return;
+	const onAbort = () => {
+		settleProjectionFailure(
+			controller,
+			new ReplicaCommandRuntimeError(
+				'REPLICA_COMMAND_SCOPE_INVALIDATED',
+				{ commandId: controller.commandId }
+			)
+		);
+		onSettled();
+	};
+	signal.addEventListener('abort', onAbort, { once: true });
+	controller.abort = () => signal.removeEventListener('abort', onAbort);
+	if (signal.aborted) onAbort();
+}
+
+export function settleProjectionFailure(
+	controller: PendingProjection,
+	error: unknown
+): void {
+	if (controller.settled) return;
+	controller.settled = true;
+	controller.abort?.();
+	controller.stopMonitor?.();
+	controller.reject(error);
+}
+
+export function settleTrackedProjection(
+	tracker: CommandStatusTracker,
+	pending: Map<string, PendingProjection>
+): void {
+	const controller = tracker.pending;
+	if (controller === undefined || controller.settled) return;
+	settleProjectionSuccess(controller);
+	pending.delete(controller.commandId);
+}
+
+export function failTrackedProjection(
+	tracker: CommandStatusTracker,
+	pending: Map<string, PendingProjection>,
+	error: unknown
+): void {
+	const controller = tracker.pending;
+	if (controller === undefined) return;
+	settleProjectionFailure(controller, error);
+	pending.delete(controller.commandId);
+}
+
diff --git a/js/src/replica/command-runtime/lib/status.ts b/js/src/replica/command-runtime/lib/status.ts
new file mode 100644
index 00000000..183e70b9
--- /dev/null
+++ b/js/src/replica/command-runtime/lib/status.ts
@@ -0,0 +1,200 @@
+import {
+	parseGraphqlResponseExtensions,
+	type DistributedCommandMetadata,
+	type DistributedCommandState
+} from '../../../protocol.js';
+import {
+	matchReplicaTrustedPresetInventory,
+	verifyReplicaCommandReceipt,
+	type ReplicaPreparedCommand
+} from '../../commands.js';
+import type {
+	CapturedAuthority,
+	ReplicaCommandStatus,
+	ReplicaCommandStatusArtifact,
+	ReplicaCommandSurfaceContract,
+	ReplicaCommandTransportResult
+} from '../types.js';
+import { isPlainRecord } from '../../../lib/is-plain-record.js';
+import {
+	isStringSubset,
+	projectionExpectationFingerprint,
+	projectionObservationFingerprint,
+	recordRevisionFingerprint,
+	sameStringMultiset
+} from './output.js';
+export function requireStatusEnvelope<TInput, TOutput>(
+	result: ReplicaCommandTransportResult,
+	artifact: ReplicaCommandStatusArtifact,
+	prepared: ReplicaPreparedCommand<TInput, TOutput>,
+	authority: CapturedAuthority,
+	contract: ReplicaCommandSurfaceContract
+): ReplicaCommandStatus {
+	if (
+		!Number.isSafeInteger(result.status) ||
+		result.status < 200 ||
+		result.status >= 300 ||
+		(result.errors?.length ?? 0) !== 0
+	) {
+		throw new Error('command status request did not succeed');
+	}
+	const state = commandStatusOutput(result.data);
+	const distributed = parseGraphqlResponseExtensions(result.extensions)?.distributed;
+	if (
+		distributed === undefined ||
+		distributed.operation !== artifact.operationHash ||
+		distributed.protocolVersion !== authority.scope.protocolVersion ||
+		distributed.schemaHash !== authority.scope.schemaHash ||
+		distributed.cacheScope !== authority.scope.cacheScope ||
+		distributed.snapshot !== undefined ||
+		distributed.live !== undefined
+	) {
+		throw new Error('command status response does not match its generated scope');
+	}
+	matchReplicaTrustedPresetInventory(
+		contract.trustedPresets,
+		distributed.trustedPresets
+	);
+	const metadata = distributed.command;
+	if (metadata === undefined) {
+		if (state !== 'unknown' && state !== 'expired') {
+			throw new Error('command status omitted required causal metadata');
+		}
+		return Object.freeze({
+			commandId: prepared.commandId,
+			state
+		});
+	}
+	verifyReplicaCommandReceipt(prepared, metadata);
+	if (metadata.state !== state) {
+		throw new Error('command status data and causal metadata disagree');
+	}
+	return Object.freeze({
+		commandId: prepared.commandId,
+		state,
+		metadata
+	});
+}
+
+export function commandStatusOutput(
+	data: Readonly<Record<string, unknown>> | null | undefined
+): DistributedCommandState {
+	if (
+		data === undefined ||
+		data === null ||
+		!isPlainRecord(data) ||
+		Reflect.ownKeys(data).length !== 1 ||
+		!Object.prototype.hasOwnProperty.call(data, 'commandStatus')
+	) {
+		throw new Error('command status data has an invalid root shape');
+	}
+	const value = data.commandStatus;
+	if (
+		!isPlainRecord(value) ||
+		Reflect.ownKeys(value).length !== 1 ||
+		!Object.prototype.hasOwnProperty.call(value, 'state')
+	) {
+		throw new Error('command status data has an invalid result shape');
+	}
+	switch (value.state) {
+		case 'in_progress':
+		case 'accepted':
+		case 'accepted_pending_projection':
+		case 'projected':
+		case 'rejected':
+		case 'projection_failed':
+		case 'expired':
+		case 'unknown':
+			return value.state;
+		default:
+			throw new Error('command status data has an invalid state');
+	}
+}
+
+export function validateStatusProgression(
+	previousState: DistributedCommandState | undefined,
+	previous: DistributedCommandMetadata | undefined,
+	current: ReplicaCommandStatus
+): void {
+	if (
+		previousState !== undefined &&
+		!isStatusTransition(previousState, current.state)
+	) {
+		throw new Error('command status regressed or changed terminal outcome');
+	}
+	const next = current.metadata;
+	if (next === undefined) {
+		if (
+			(current.state !== 'unknown' && current.state !== 'expired') ||
+			(previous !== undefined && current.state === 'unknown')
+		) {
+			throw new Error('command status lost causal metadata');
+		}
+		return;
+	}
+	if (next.state !== current.state) {
+		throw new Error('command status metadata has an inconsistent state');
+	}
+	if (previous === undefined) return;
+	if (
+		next.commandId !== previous.commandId ||
+		next.causationId !== previous.causationId ||
+		next.consistency !== previous.consistency
+	) {
+		throw new Error('command status changed causal identity');
+	}
+	if (
+		!(
+			previous.state === 'in_progress' &&
+			previous.expects.length === 0
+		) &&
+		!sameStringMultiset(
+			previous.expects.map(projectionExpectationFingerprint),
+			next.expects.map(projectionExpectationFingerprint)
+		)
+	) {
+		throw new Error('command status changed projection expectations');
+	}
+	if (
+		!isStringSubset(
+			previous.observations.map(projectionObservationFingerprint),
+			next.observations.map(projectionObservationFingerprint)
+		) ||
+		!isStringSubset(
+			previous.records.map(recordRevisionFingerprint),
+			next.records.map(recordRevisionFingerprint)
+		)
+	) {
+		throw new Error('command status lost causal evidence');
+	}
+}
+
+export function isStatusTransition(
+	previous: DistributedCommandState,
+	next: DistributedCommandState
+): boolean {
+	switch (previous) {
+		case 'unknown':
+			return true;
+		case 'in_progress':
+			return next !== 'unknown';
+		case 'accepted':
+			return next === 'accepted' || next === 'expired';
+		case 'accepted_pending_projection':
+			return (
+				next === 'accepted_pending_projection' ||
+				next === 'projected' ||
+				next === 'projection_failed' ||
+				next === 'expired'
+			);
+		case 'projected':
+			return next === 'projected' || next === 'expired';
+		case 'rejected':
+			return next === 'rejected' || next === 'expired';
+		case 'projection_failed':
+			return next === 'projection_failed' || next === 'expired';
+		case 'expired':
+			return next === 'expired';
+	}
+}
+
diff --git a/js/src/replica/command-runtime/lib/transport.ts b/js/src/replica/command-runtime/lib/transport.ts
new file mode 100644
index 00000000..29b1bef0
--- /dev/null
+++ b/js/src/replica/command-runtime/lib/transport.ts
@@ -0,0 +1,168 @@
+import {
+	parseGraphqlResponseExtensions,
+	type DistributedProtocolEnvelope
+} from '../../../protocol.js';
+import type { GqlError } from '../../../types.js';
+import {
+	verifyReplicaCommandReceipt,
+	type ReplicaPreparedCommand
+} from '../../commands.js';
+import { ReplicaCommandRuntimeError } from '../errors.js';
+import type {
+	CapturedAuthority,
+	ReplicaCommandStatusArtifact,
+	ReplicaCommandStatusRequest,
+	ReplicaCommandTransport,
+	ReplicaCommandTransportRequest,
+	ReplicaCommandTransportResult
+} from '../types.js';
+import {
+	cloneSurface,
+	waitForCommandOperation
+} from './util.js';
+export function commandTransportRequest<TInput, TOutput>(
+	prepared: ReplicaPreparedCommand<TInput, TOutput>,
+	signal: AbortSignal | undefined
+): ReplicaCommandTransportRequest {
+	const surface = prepared.transport.protocol.surface;
+	if (surface === undefined) {
+		throw new ReplicaCommandRuntimeError(
+			'REPLICA_COMMAND_PROTOCOL_INVALID',
+			{ commandId: prepared.commandId }
+		);
+	}
+	return Object.freeze({
+		operation: 'mutation',
+		commandName: prepared.name,
+		commandId: prepared.commandId,
+		mutationField: prepared.transport.mutationField,
+		document: prepared.transport.document,
+		operationHash: prepared.transport.operationHash,
+		variables: prepared.transport.variables as Readonly<Record<string, unknown>>,
+		extensions: Object.freeze({
+			distributed: Object.freeze({
+				client: Object.freeze({
+					surface: cloneSurface(surface),
+					schemaHash: prepared.transport.protocol.schemaHash
+				})
+			})
+		}),
+		...(signal === undefined ? {} : { signal })
+	});
+}
+
+export function commandStatusRequest(
+	artifact: ReplicaCommandStatusArtifact,
+	commandId: string,
+	signal: AbortSignal | undefined
+): ReplicaCommandStatusRequest {
+	return Object.freeze({
+		operation: 'status',
+		commandId,
+		name: artifact.name,
+		document: artifact.document,
+		operationHash: artifact.operationHash,
+		variables: Object.freeze({ commandId }),
+		extensions: Object.freeze({
+			distributed: Object.freeze({
+				client: Object.freeze({
+					surface: cloneSurface(artifact.protocol.surface),
+					schemaHash: artifact.protocol.schemaHash
+				})
+			})
+		}),
+		...(signal === undefined ? {} : { signal })
+	});
+}
+
+export async function dispatchPrepared(
+	transport: ReplicaCommandTransport,
+	request: ReplicaCommandTransportRequest,
+	retries: number,
+	onAttempt: () => void
+): Promise<ReplicaCommandTransportResult> {
+	let error: unknown;
+	for (let attempt = 0; attempt <= retries; attempt += 1) {
+		if (request.signal?.aborted) {
+			throw request.signal.reason ?? new Error('command request aborted');
+		}
+		try {
+			onAttempt();
+			return await waitForCommandOperation(
+				transport.dispatch(request),
+				request.signal
+			);
+		} catch (candidate) {
+			error = candidate;
+			if (request.signal?.aborted) throw candidate;
+		}
+	}
+	throw error;
+}
+
+export function requireCommandEnvelope<TInput, TOutput>(
+	result: ReplicaCommandTransportResult,
+	prepared: ReplicaPreparedCommand<TInput, TOutput>,
+	authority: CapturedAuthority
+): DistributedProtocolEnvelope {
+	const distributed = parseGraphqlResponseExtensions(result.extensions)?.distributed;
+	if (
+		distributed === undefined ||
+		distributed.command === undefined ||
+		distributed.operation !== prepared.transport.operationHash ||
+		distributed.protocolVersion !== authority.scope.protocolVersion ||
+		distributed.schemaHash !== authority.scope.schemaHash ||
+		distributed.cacheScope !== authority.scope.cacheScope
+	) {
+		throw new Error('command response does not match its generated scope');
+	}
+	verifyReplicaCommandReceipt(prepared, distributed.command);
+	return distributed;
+}
+
+/**
+ * Domain rejection happens before a command receipt exists, so GraphQL cannot
+ * attach `distributed.command`. It still has to prove the exact generated
+ * operation and authoritative cache scope before the runtime may classify the
+ * response as a normal rejection instead of a protocol failure.
+ */
+export function requireCommandRejectionEnvelope<TInput, TOutput>(
+	result: ReplicaCommandTransportResult,
+	prepared: ReplicaPreparedCommand<TInput, TOutput>,
+	authority: CapturedAuthority
+): DistributedProtocolEnvelope {
+	const distributed = parseGraphqlResponseExtensions(result.extensions)?.distributed;
+	if (
+		!Number.isSafeInteger(result.status) ||
+		result.status < 200 ||
+		result.status >= 300 ||
+		result.data !== null ||
+		graphqlCommandRejection(result) === undefined ||
+		distributed === undefined ||
+		distributed.command !== undefined ||
+		distributed.operation !== prepared.transport.operationHash ||
+		distributed.protocolVersion !== authority.scope.protocolVersion ||
+		distributed.schemaHash !== authority.scope.schemaHash ||
+		distributed.cacheScope !== authority.scope.cacheScope
+	) {
+		throw new Error('command rejection does not match its generated scope');
+	}
+	return distributed;
+}
+
+export function graphqlCommandRejection(
+	result: ReplicaCommandTransportResult
+): GqlError | undefined {
+	const errors = result.errors;
+	if (
+		parseGraphqlResponseExtensions(result.extensions)?.distributed?.command !==
+			undefined ||
+		errors === undefined ||
+		errors.length === 0 ||
+		!errors.every((error) => error.extensions?.code === 'REJECTED')
+	) {
+		return undefined;
+	}
+	return errors[0];
+}
+
diff --git a/js/src/replica/command-runtime/lib/util.ts b/js/src/replica/command-runtime/lib/util.ts
new file mode 100644
index 00000000..d65b7c82
--- /dev/null
+++ b/js/src/replica/command-runtime/lib/util.ts
@@ -0,0 +1,171 @@
+import type {
+	ReplicaAuthoritativeScope,
+	ReplicaClientSurface
+} from '../../types.js';
+import {
+	MAX_TRANSPORT_RETRIES
+} from '../constants.js';
+import { ReplicaCommandRuntimeError } from '../errors.js';
+import { compareCodeUnits } from '../../../lib/compare-code-units.js';
+import { isPlainRecord } from '../../../lib/is-plain-record.js';
+
+export function normalizeRetries(value: number | undefined): number {
+	if (value === undefined) return 0;
+	if (!Number.isSafeInteger(value) || value < 0 || value > MAX_TRANSPORT_RETRIES) {
+		throw new TypeError(
+			`transportRetries must be an integer between 0 and ${MAX_TRANSPORT_RETRIES}`
+		);
+	}
+	return value;
+}
+
+export function cloneScope(scope: ReplicaAuthoritativeScope): ReplicaAuthoritativeScope {
+	return Object.freeze({
+		protocolVersion: 1,
+		schemaHash: scope.schemaHash,
+		cacheScope: scope.cacheScope
+	});
+}
+
+export function sameScope(
+	left: ReplicaAuthoritativeScope,
+	right: ReplicaAuthoritativeScope
+): boolean {
+	return (
+		left.protocolVersion === right.protocolVersion &&
+		left.schemaHash === right.schemaHash &&
+		left.cacheScope === right.cacheScope
+	);
+}
+
+export function sameSurface(
+	left: ReplicaClientSurface | undefined,
+	right: ReplicaClientSurface
+): boolean {
+	if (
+		left === undefined ||
+		left.kind !== right.kind ||
+		left.name !== right.name
+	) {
+		return false;
+	}
+	return (
+		left.kind === 'role' ||
+		(right.kind === 'application' &&
+			left.roles.length === right.roles.length &&
+			left.roles.every((role, index) => role === right.roles[index]))
+	);
+}
+
+export function cloneSurface(surface: ReplicaClientSurface): ReplicaClientSurface {
+	return surface.kind === 'role'
+		? Object.freeze({ kind: 'role', name: surface.name })
+		: Object.freeze({
+				kind: 'application',
+				name: surface.name,
+				roles: Object.freeze([...surface.roles])
+			});
+}
+
+export function linkAbortSignals(
+	signals: readonly (AbortSignal | undefined)[]
+): Readonly<{
+	signal: AbortSignal | undefined;
+	dispose(): void;
+}> {
+	const sources = [
+		...new Set(
+			signals.filter(
+				(signal): signal is AbortSignal => signal !== undefined
+			)
+		)
+	];
+	if (sources.length === 0) {
+		return Object.freeze({
+			signal: undefined,
+			dispose(): void {}
+		});
+	}
+	if (sources.length === 1) {
+		return Object.freeze({
+			signal: sources[0],
+			dispose(): void {}
+		});
+	}
+	const controller = new AbortController();
+	const listeners = new Map<AbortSignal, () => void>();
+	let disposed = false;
+	const dispose = (): void => {
+		if (disposed) return;
+		disposed = true;
+		for (const [source, listener] of listeners) {
+			source.removeEventListener('abort', listener);
+		}
+		listeners.clear();
+	};
+	const abort = (signal: AbortSignal) => {
+		if (!controller.signal.aborted) {
+			controller.abort(signal.reason);
+		}
+		dispose();
+	};
+	for (const source of sources) {
+		if (source.aborted) {
+			abort(source);
+			break;
+		}
+		const listener = () => abort(source);
+		listeners.set(source, listener);
+		source.addEventListener('abort', listener, { once: true });
+		// Close the check/register race if a source aborted synchronously.
+		if (source.aborted) {
+			listener();
+			break;
+		}
+	}
+	return Object.freeze({ signal: controller.signal, dispose });
+}
+
+export function waitForCommandOperation<T>(
+	operation: Promise<T> | T,
+	signal: AbortSignal | undefined
+): Promise<T> {
+	const result = Promise.resolve(operation);
+	if (signal === undefined) return result;
+	return new Promise<T>((resolve, reject) => {
+		let settled = false;
+		const finish = (complete: () => void): void => {
+			if (settled) return;
+			settled = true;
+			signal.removeEventListener('abort', onAbort);
+			complete();
+		};
+		const onAbort = (): void => {
+			finish(() =>
+				reject(
+					signal.reason ??
+						new ReplicaCommandRuntimeError('REPLICA_COMMAND_ABORTED')
+				)
+			);
+		};
+		signal.addEventListener('abort', onAbort, { once: true });
+		void result.then(
+			(value) => finish(() => resolve(value)),
+			(error: unknown) => finish(() => reject(error))
+		);
+		// Close the check/register race if the signal aborted synchronously.
+		if (signal.aborted) onAbort();
+	});
+}
+
+export function outputInvalid(path: string): never {
+	throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', {
+		cause: new TypeError(`invalid command output at ${path}`)
+	});
+}
+
+export function comparePropertyKeys(left: PropertyKey, right: PropertyKey): number {
+	return compareCodeUnits(String(left), String(right));
+}
+
+export { compareCodeUnits, isPlainRecord };
diff --git a/js/src/replica/command-runtime/lifecycle.ts b/js/src/replica/command-runtime/lifecycle.ts
new file mode 100644
index 00000000..a802e7f4
--- /dev/null
+++ b/js/src/replica/command-runtime/lifecycle.ts
@@ -0,0 +1,23 @@
+import { replicaCommandProjectedLifecycle } from './symbols.js';
+import type {
+	ReplicaCommandProjectedOutcome,
+	ReplicaCommandReceipt,
+	ReplicaCommandReceiptWithLifecycle
+} from './types.js';
+
+/**
+ * Package-private causal lifecycle used by framework adapters.
+ *
+ * A caller-scoped `receipt.projected` can reject when its AbortSignal fires
+ * after acceptance. The underlying command remains globally pending until
+ * canonical projection evidence settles this independent promise.
+ *
+ * @internal
+ */
+export function replicaCommandProjectedLifecycleOf(
+	receipt: ReplicaCommandReceipt<unknown>
+): Promise<ReplicaCommandProjectedOutcome<unknown>> | undefined {
+	return (receipt as ReplicaCommandReceiptWithLifecycle)[
+		replicaCommandProjectedLifecycle
+	];
+}
diff --git a/js/src/replica/command-runtime/symbols.ts b/js/src/replica/command-runtime/symbols.ts
new file mode 100644
index 00000000..4f9b58aa
--- /dev/null
+++ b/js/src/replica/command-runtime/symbols.ts
@@ -0,0 +1,36 @@
+/**
+ * Package-private authority handshake implemented by DistributedReplica.
+ *
+ * This symbol is intentionally not exported from the public replica barrel.
+ * Generated command binders can therefore consume server-derived preset values,
+ * while application code cannot pass an ambient caller-owned inventory.
+ *
+ * @internal
+ */
+export const replicaCommandAuthority = Symbol('distributed.replica.command-authority');
+/**
+ * Package-private post-commit observation channel implemented by
+ * DistributedReplica. Generated command runtimes register here so framework
+ * adapters never guess replica commit ordering.
+ *
+ * @internal
+ */
+export const replicaResultObservation = Symbol(
+	'distributed.replica.result-observation'
+);
+/**
+ * Package-private direct-projection commit implemented by DistributedReplica.
+ *
+ * The replica must advance its protocol record clock in the same confirmation
+ * path as the base-cache write. Otherwise an older query response can be
+ * mistaken for an incomplete write after the cache correctly rejects it.
+ *
+ * @internal
+ */
+export const replicaCommandDirectProjection = Symbol(
+	'distributed.replica.command-direct-projection'
+);
+/** @internal Package-private; intentionally absent from the public barrel. */
+export const replicaCommandProjectedLifecycle = Symbol(
+	'distributed.replica.command-projected-lifecycle'
+);
diff --git a/js/src/replica/command-runtime/types.ts b/js/src/replica/command-runtime/types.ts
new file mode 100644
index 00000000..c48fbcbb
--- /dev/null
+++ b/js/src/replica/command-runtime/types.ts
@@ -0,0 +1,363 @@
+import type {
+	DistributedCommandMetadata,
+	DistributedCommandState,
+	DistributedRecordRevision,
+	DistributedTrustedPreset
+} from '../../protocol.js';
+import type { GqlError } from '../../types.js';
+import type {
+	PrepareReplicaCommandOptions,
+	ReplicaCommandArtifact,
+	ReplicaPreparedCommand,
+	ReplicaTrustedPresetDescriptor
+} from '../commands.js';
+import type { ReplicaDiagnosticsSink } from '../diagnostics.js';
+import type { ReplicaIndexSemanticChange } from '../index-maintenance.js';
+import type {
+	DistributedReplica,
+	ReplicaAuthoritativeScope,
+	ReplicaClientSurface,
+	ReplicaIdentity,
+	ReplicaModelArtifact,
+	ReplicaOptimisticWriter,
+	ReplicaResultEnvelope,
+	ReplicaValue
+} from '../types.js';
+import {
+	replicaCommandAuthority,
+	replicaCommandDirectProjection,
+	replicaCommandProjectedLifecycle,
+	replicaResultObservation
+} from './symbols.js';
+
+export type ReplicaCommandSurfaceContract = Readonly<{
+	protocolVersion: 1;
+	schemaHash: string;
+	protocolHash: string;
+	surface: ReplicaClientSurface;
+	trustedPresets: readonly ReplicaTrustedPresetDescriptor[];
+}>;
+
+export type ReplicaCommandAuthoritySnapshot = Readonly<{
+	generation: number;
+	scope: ReplicaAuthoritativeScope | undefined;
+	trustedPresets: readonly DistributedTrustedPreset[];
+	/** Aborted by the replica when this authorization generation closes. */
+	signal?: AbortSignal;
+}>;
+
+export type ReplicaCommandAuthorityRegistration = Readonly<{
+	read(): ReplicaCommandAuthoritySnapshot;
+	dispose(): void;
+}>;
+
+export type ReplicaResultObservationRegistration = Readonly<{
+	dispose(): void;
+}>;
+
+export type ReplicaCommandDirectProjection = Readonly<{
+	model: ReplicaModelArtifact;
+	identity: ReplicaIdentity;
+	evidence: DistributedRecordRevision;
+	fields: Readonly<Record<string, ReplicaValue>>;
+}>;
+
+export type ReplicaCommandAuthorityHost = DistributedReplica & {
+	readonly [replicaCommandAuthority]?: (
+		contract: ReplicaCommandSurfaceContract
+	) => ReplicaCommandAuthorityRegistration;
+	readonly [replicaResultObservation]?: (
+		observer: (envelope: ReplicaResultEnvelope<unknown>) => void
+	) => ReplicaResultObservationRegistration;
+	readonly [replicaCommandDirectProjection]?: (
+		commandId: string,
+		projection: ReplicaCommandDirectProjection
+	) => void;
+};
+
+export type ReplicaCommandTransportRequest = Readonly<{
+	operation: 'mutation';
+	commandName: string;
+	commandId: string;
+	mutationField: string;
+	document: string;
+	operationHash: string;
+	variables: Readonly<Record<string, unknown>>;
+	extensions: Readonly<Record<string, unknown>>;
+	signal?: AbortSignal;
+}>;
+
+export type ReplicaCommandStatusArtifact = Readonly<{
+	name: string;
+	document: string;
+	operationHash: string;
+	protocol: Readonly<{
+		version: 1;
+		schemaHash: string;
+		protocolHash: string;
+		surface: ReplicaClientSurface;
+		operation: string;
+		/** Exact surface union: command presets plus client-evaluable policy claims. */
+		trustedPresets: readonly ReplicaTrustedPresetDescriptor[];
+	}>;
+}>;
+
+export type ReplicaCommandStatusRequest = Readonly<{
+	operation: 'status';
+	commandId: string;
+	name: string;
+	document: string;
+	operationHash: string;
+	variables: Readonly<{ commandId: string }>;
+	extensions: Readonly<Record<string, unknown>>;
+	signal?: AbortSignal;
+}>;
+
+export type ReplicaCommandTransportResult = Readonly<{
+	data?: Readonly<Record<string, unknown>> | null;
+	errors?: readonly GqlError[];
+	extensions?: unknown;
+	status: number;
+}>;
+
+export interface ReplicaCommandTransport {
+	dispatch(
+		request: ReplicaCommandTransportRequest
+	): Promise<ReplicaCommandTransportResult>;
+	/** Execute the exact compiler-owned command-status operation. */
+	status?(
+		request: ReplicaCommandStatusRequest
+	): Promise<ReplicaCommandTransportResult>;
+}
+
+export type ReplicaCommandProjectedOutcome<TOutput> = Readonly<{
+	commandId: string;
+	state: 'projected';
+	/** Present for same-transaction Projected<T>, absent for async facts. */
+	result?: TOutput;
+	metadata?: DistributedCommandMetadata;
+}>;
+
+export type ReplicaCommandStatus = Readonly<{
+	commandId: string;
+	state: DistributedCommandState;
+	/**
+	 * Durable causal evidence. The server deliberately omits it for the
+	 * non-enumerating `unknown` and compact `expired` states.
+	 */
+	metadata?: DistributedCommandMetadata;
+}>;
+
+export type ReplicaCommandReceipt<TOutput> = Readonly<{
+	commandId: string;
+	state: Extract<
+		DistributedCommandState,
+		'accepted' | 'accepted_pending_projection' | 'projected'
+	>;
+	/** Typed application payload returned by the generated mutation. */
+	result: TOutput;
+	metadata: DistributedCommandMetadata;
+	/** One exact generated status read. Calls coalesce while in flight. */
+	status(): Promise<ReplicaCommandStatus>;
+	/**
+	 * Causal visibility awaitable. It is omitted when no finite projection
+	 * contract exists and never resolves because a wall-clock timer elapsed.
+	 */
+	projected?: Promise<ReplicaCommandProjectedOutcome<TOutput>>;
+}>;
+
+export type ReplicaCommandReceiptWithLifecycle = ReplicaCommandReceipt<unknown> &
+	Readonly<{
+		[replicaCommandProjectedLifecycle]?: Promise<
+			ReplicaCommandProjectedOutcome<unknown>
+		>;
+	}>;
+
+/**
+ * Package-private causal lifecycle used by framework adapters.
+ *
+ * A caller-scoped `receipt.projected` can reject when its AbortSignal fires
+ * after acceptance. The underlying command remains globally pending until
+ * canonical projection evidence settles this independent promise.
+ *
+ * @internal
+ */
+
+/**
+ * Stable recovery handle attached to an ambiguous dispatch error.
+ *
+ * `status()` never infers success from time. The original immutable prepared
+ * mutation remains retained by the runtime/layer; status reports the durable
+ * server outcome without manufacturing rollback or confirmation.
+ */
+export type ReplicaCommandRecoveryReceipt<TOutput = unknown> = Readonly<{
+	commandId: string;
+	status(): Promise<ReplicaCommandStatus>;
+	/** Phantom slot retains the originating generated output type. */
+	readonly __output?: TOutput;
+}>;
+
+export type ReplicaCommandCallOptions<TOutput> = PrepareReplicaCommandOptions &
+	Readonly<{
+		/**
+		 * Cancels dispatch while the command outcome is unknown. After finite
+		 * acceptance it instead bounds only this caller's `receipt.projected`
+		 * wait; causal tracking and the optimistic layer continue independently.
+		 */
+		signal?: AbortSignal;
+		/** Exact same prepared request retries after thrown/ambiguous transport. */
+		transportRetries?: number;
+		onAccepted?: (
+			receipt: ReplicaCommandReceipt<TOutput>
+		) => void | Promise<void>;
+	}>;
+
+export type ReplicaCommandRuntimeErrorCode =
+	| 'REPLICA_COMMAND_ABORTED'
+	| 'REPLICA_COMMAND_AUTHORITY_UNAVAILABLE'
+	| 'REPLICA_COMMAND_DISPOSED'
+	| 'REPLICA_COMMAND_OUTCOME_PENDING'
+	| 'REPLICA_COMMAND_PROJECTION_FAILED'
+	| 'REPLICA_COMMAND_PROTOCOL_INVALID'
+	| 'REPLICA_COMMAND_REJECTED'
+	| 'REPLICA_COMMAND_SCOPE_INVALIDATED'
+	| 'REPLICA_COMMAND_STATUS_UNAVAILABLE'
+	| 'REPLICA_COMMAND_TRANSPORT_AMBIGUOUS';
+
+export type AnyCommandArtifact = ReplicaCommandArtifact<unknown, unknown>;
+export type CommandEntry =
+	| AnyCommandArtifact
+	| Readonly<{ artifact: AnyCommandArtifact }>;
+
+export type ArtifactOf<TEntry> = TEntry extends ReplicaCommandArtifact<
+	infer TInput,
+	infer TOutput
+>
+	? ReplicaCommandArtifact<TInput, TOutput>
+	: TEntry extends Readonly<{
+				artifact: ReplicaCommandArtifact<infer TInput, infer TOutput>;
+			}>
+		? ReplicaCommandArtifact<TInput, TOutput>
+		: never;
+
+export type InputOf<TEntry> =
+	ArtifactOf<TEntry> extends ReplicaCommandArtifact<infer TInput, unknown>
+		? TInput
+		: never;
+
+export type OutputOf<TEntry> =
+	ArtifactOf<TEntry> extends ReplicaCommandArtifact<unknown, infer TOutput>
+		? TOutput
+		: never;
+
+export type ReplicaBoundCommand<TInput, TOutput> = [TInput] extends [void]
+	? (
+			options?: ReplicaCommandCallOptions<TOutput>
+		) => Promise<ReplicaCommandReceipt<TOutput>>
+	: (
+			input: TInput,
+			options?: ReplicaCommandCallOptions<TOutput>
+		) => Promise<ReplicaCommandReceipt<TOutput>>;
+
+export type ReplicaBoundCommandPath<
+	TPath extends string,
+	TCommand
+> = TPath extends `${infer THead}.${infer TTail}`
+	? THead extends ''
+		? never
+		: Readonly<{
+				[TKey in THead]: ReplicaBoundCommandPath<TTail, TCommand>;
+			}>
+	: TPath extends ''
+		? never
+		: Readonly<{ [TKey in TPath]: TCommand }>;
+
+export type UnionToIntersection<TValue> = (
+	TValue extends unknown ? (value: TValue) => void : never
+) extends (value: infer TIntersection) => void
+	? TIntersection
+	: never;
+
+export type SimplifyCommandTree<TValue> = TValue extends (
+	...args: infer _TArguments
+) => infer _TResult
+	? TValue
+	: Readonly<{
+			[TKey in keyof TValue]: SimplifyCommandTree<TValue[TKey]>;
+		}>;
+
+export type ReplicaBoundCommands<
+	TEntries extends Readonly<Record<string, CommandEntry>>
+> = SimplifyCommandTree<
+	UnionToIntersection<
+		{
+			[TKey in Extract<keyof TEntries, string>]: ReplicaBoundCommandPath<
+				TKey,
+				ReplicaBoundCommand<
+					InputOf<TEntries[TKey]>,
+					OutputOf<TEntries[TKey]>
+				>
+			>;
+		}[Extract<keyof TEntries, string>]
+	>
+>;
+
+export type ReplicaCommandRuntimeOptions = Readonly<{
+	onBackgroundError?: (error: unknown) => void;
+	/** Exact generated status operation for delayed/ambiguous recovery. */
+	status?: ReplicaCommandStatusArtifact;
+	/** Optional shared replica diagnostics sink used only for static artifact inspection. */
+	diagnostics?: ReplicaDiagnosticsSink;
+}>;
+
+export interface ReplicaCommandRuntime<
+	TEntries extends Readonly<Record<string, CommandEntry>>
+> {
+	readonly commands: ReplicaBoundCommands<TEntries>;
+	/**
+	 * Observe a query/live result only after the replica committed it.
+	 *
+	 * This completes pending causal awaitables from exact scoped observations;
+	 * it does not normalize or confirm cache data itself.
+	 */
+	observeResult(envelope: ReplicaResultEnvelope<unknown>): void;
+	dispose(): void;
+}
+
+export type CapturedAuthority = Readonly<{
+	generation: number;
+	scope: ReplicaAuthoritativeScope;
+	trustedPresets: readonly DistributedTrustedPreset[];
+	signal?: AbortSignal;
+}>;
+
+export type PendingProjection = {
+	readonly commandId: string;
+	readonly causationId: string;
+	readonly authority: CapturedAuthority;
+	readonly resolve: (
+		value: ReplicaCommandProjectedOutcome<unknown>
+	) => void;
+	readonly reject: (error: unknown) => void;
+	readonly promise: Promise<ReplicaCommandProjectedOutcome<unknown>>;
+	readonly prepared: ReplicaPreparedCommand<unknown, unknown>;
+	abort?: () => void;
+	stopMonitor?: () => void;
+	metadata: DistributedCommandMetadata;
+	settled: boolean;
+};
+
+export type CommandStatusTracker = {
+	state: DistributedCommandState | undefined;
+	metadata: DistributedCommandMetadata | undefined;
+	inFlight: Promise<ReplicaCommandStatus> | undefined;
+	pending?: PendingProjection;
+};
+
+export type SemanticReplica = DistributedReplica & {
+	createOptimisticLayer(
+		id: string,
+		update: (writer: ReplicaOptimisticWriter) => void,
+		semanticChanges?: readonly ReplicaIndexSemanticChange[]
+	): void;
+};
diff --git a/js/src/replica/commands.ts b/js/src/replica/commands.ts
new file mode 100644
index 00000000..882e64c7
--- /dev/null
+++ b/js/src/replica/commands.ts
@@ -0,0 +1,40 @@
+/** Command artifacts and prepare/verify; implementation in ./commands/. */
+export {
+	matchReplicaTrustedPresetInventory,
+	prepareReplicaCommand,
+	prepareReplicaCommandWithTrustedPresets,
+	ReplicaCommandContractError,
+	verifyReplicaCommandReceipt
+} from './commands/index.js';
+export type {
+	PrepareReplicaCommandOptions,
+	ReplicaCommandArtifact,
+	ReplicaCommandConfirmation,
+	ReplicaCommandConfirmations,
+	ReplicaCommandContractErrorCode,
+	ReplicaCommandDirectProjection,
+	ReplicaCommandEffect,
+	ReplicaCommandEffectExpression,
+	ReplicaCommandEffectField,
+	ReplicaCommandEffectKey,
+	ReplicaCommandEffectRelationship,
+	ReplicaCommandEffects,
+	ReplicaCommandGenerators,
+	ReplicaCommandInputDefault,
+	ReplicaCommandInputDefaults,
+	ReplicaCommandRevalidationPlan,
+	ReplicaCommandScalarCodec,
+	ReplicaCommandShape,
+	ReplicaCommandTypeDefinition,
+	ReplicaCommandTypeField,
+	ReplicaCommandVariables,
+	ReplicaMatchedTrustedPresetInventory,
+	ReplicaPreparedCommand,
+	ReplicaPreparedCommandEffect,
+	ReplicaPreparedConfirmation,
+	ReplicaPreparedConfirmations,
+	ReplicaPreparedEffectField,
+	ReplicaPreparedEffectKey,
+	ReplicaReceiptVerification,
+	ReplicaTrustedPresetDescriptor
+} from './commands/index.js';
diff --git a/js/src/replica/commands/clone.ts b/js/src/replica/commands/clone.ts
new file mode 100644
index 00000000..1d063674
--- /dev/null
+++ b/js/src/replica/commands/clone.ts
@@ -0,0 +1,319 @@
+import type { ReplicaClientSurface, ReplicaValue } from '../types.js';
+import { createReplicaCommandId } from '../command-id.js';
+import { isPlainRecord } from '../../lib/is-plain-record.js';
+import {
+	MAX_TYPE_DEPTH
+} from './constants.js';
+import type {
+	ReplicaCommandGenerators,
+	ReplicaCommandInputDefault,
+	ReplicaCommandRevalidationPlan,
+	ReplicaCommandEffectRelationship,
+	ReplicaCommandScalarCodec,
+	ReplicaCommandTypeDefinition,
+	ReplicaCommandTypeField,
+	ReplicaTrustedPresetDescriptor
+} from './types.js';
+import {
+	artifactInvalid,
+	createUlid,
+	defineEnumerable,
+	inputInvalid,
+	requiredString,
+	samePath,
+	validateUlid,
+	validateUuidV7
+} from './util.js';
+
+export function cloneClientSurface(surface: ReplicaClientSurface): ReplicaClientSurface {
+	return surface.kind === 'role'
+		? Object.freeze({ kind: 'role' as const, name: surface.name })
+		: Object.freeze({
+				kind: 'application' as const,
+				name: surface.name,
+				roles: Object.freeze([...surface.roles])
+			});
+}
+
+export function cloneTrustedPresetDescriptors(
+	value: readonly ReplicaTrustedPresetDescriptor[]
+): readonly ReplicaTrustedPresetDescriptor[] {
+	return Object.freeze(
+		value.map(({ name, codec }) => Object.freeze({ name, codec }))
+	);
+}
+
+export function cloneDefinitionValue(
+	definition: ReplicaCommandTypeDefinition,
+	value: unknown,
+	path: readonly string[],
+	defaults: readonly ReplicaCommandInputDefault[],
+	generators: ReplicaCommandGenerators | undefined,
+	label: string
+): Readonly<Record<string, unknown>> {
+	if (!isPlainRecord(value)) inputInvalid(label);
+	const ownKeys = Reflect.ownKeys(value);
+	if (ownKeys.some((key) => typeof key !== 'string')) inputInvalid(label);
+	const known = new Set(definition.fields.map((field) => field.name));
+	for (const key of ownKeys as string[]) {
+		if (!known.has(key)) inputInvalid(`${label}.${key}`);
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (descriptor === undefined || !('value' in descriptor)) {
+			inputInvalid(`${label}.${key}`);
+		}
+	}
+
+	const result: Record<string, unknown> = {};
+	for (const field of definition.fields) {
+		const fieldPath = [...path, field.name];
+		const fieldLabel = `${label}.${field.name}`;
+		const present =
+			Object.prototype.hasOwnProperty.call(value, field.name) &&
+			value[field.name] !== undefined;
+		let fieldValue: unknown;
+		if (present) {
+			fieldValue = value[field.name];
+		} else {
+			const declared = defaults.find((entry) =>
+				samePath(entry.path, fieldPath)
+			);
+			if (declared !== undefined) {
+				fieldValue = generateDefault(declared, generators, fieldLabel);
+			} else if (field.nullable) {
+				continue;
+			} else {
+				inputInvalid(fieldLabel);
+			}
+		}
+		defineEnumerable(
+			result,
+			field.name,
+			cloneFieldValue(
+				field,
+				fieldValue,
+				fieldPath,
+				defaults,
+				generators,
+				fieldLabel
+			)
+		);
+	}
+	return Object.freeze(result);
+}
+
+export function cloneFieldValue(
+	field: ReplicaCommandTypeField,
+	value: unknown,
+	path: readonly string[],
+	defaults: readonly ReplicaCommandInputDefault[],
+	generators: ReplicaCommandGenerators | undefined,
+	label: string
+): unknown {
+	if (value === null) {
+		if (!field.nullable) inputInvalid(label);
+		return null;
+	}
+	if (field.list) {
+		if (!Array.isArray(value)) inputInvalid(label);
+		return Object.freeze(
+			value.map((item, index) => {
+				if (item === null) {
+					if (!field.itemNullable) inputInvalid(`${label}[${index}]`);
+					return null;
+				}
+				return cloneNonNullFieldValue(
+					field,
+					item,
+					path,
+					defaults,
+					generators,
+					`${label}[${index}]`
+				);
+			})
+		);
+	}
+	return cloneNonNullFieldValue(
+		field,
+		value,
+		path,
+		defaults,
+		generators,
+		label
+	);
+}
+
+export function cloneNonNullFieldValue(
+	field: ReplicaCommandTypeField,
+	value: unknown,
+	path: readonly string[],
+	defaults: readonly ReplicaCommandInputDefault[],
+	generators: ReplicaCommandGenerators | undefined,
+	label: string
+): unknown {
+	if (field.nested !== undefined) {
+		return cloneDefinitionValue(
+			field.nested,
+			value,
+			path,
+			defaults,
+			generators,
+			label
+		);
+	}
+	return cloneScalar(field.codec, value, label);
+}
+
+export function cloneScalar(
+	codec: ReplicaCommandScalarCodec | undefined,
+	value: unknown,
+	path: string
+): ReplicaValue {
+	switch (codec) {
+		case 'string':
+		case 'string_unvalidated_timestamp':
+		case 'base64':
+			if (typeof value !== 'string') inputInvalid(path);
+			return value;
+		case 'boolean':
+			if (typeof value !== 'boolean') inputInvalid(path);
+			return value;
+		case 'int32':
+			if (
+				typeof value !== 'number' ||
+				!Number.isInteger(value) ||
+				value < -2_147_483_648 ||
+				value > 2_147_483_647
+			) {
+				inputInvalid(path);
+			}
+			return Object.is(value, -0) ? 0 : value;
+		case 'json_number_precision_limited':
+			if (typeof value !== 'number' || !Number.isInteger(value)) {
+				inputInvalid(path);
+			}
+			return Object.is(value, -0) ? 0 : value;
+		case 'float64':
+			if (typeof value !== 'number' || !Number.isFinite(value)) {
+				inputInvalid(path);
+			}
+			return Object.is(value, -0) ? 0 : value;
+		case 'json':
+			return cloneJson(value, path);
+		default:
+			artifactInvalid(`${path}.codec`);
+	}
+}
+
+export function cloneJson(
+	value: unknown,
+	path: string,
+	active: Set<object> = new Set(),
+	depth = 0
+): ReplicaValue {
+	if (depth > MAX_TYPE_DEPTH) inputInvalid(path);
+	if (
+		value === null ||
+		typeof value === 'string' ||
+		typeof value === 'boolean'
+	) {
+		return value;
+	}
+	if (typeof value === 'number') {
+		if (!Number.isFinite(value)) inputInvalid(path);
+		return Object.is(value, -0) ? 0 : value;
+	}
+	if (Array.isArray(value)) {
+		if (active.has(value)) inputInvalid(path);
+		active.add(value);
+		const result = Object.freeze(
+			value.map((item, index) =>
+				cloneJson(item, `${path}[${index}]`, active, depth + 1)
+			)
+		);
+		active.delete(value);
+		return result;
+	}
+	if (!isPlainRecord(value)) inputInvalid(path);
+	if (active.has(value)) inputInvalid(path);
+	active.add(value);
+	const keys = Reflect.ownKeys(value);
+	if (keys.some((key) => typeof key !== 'string')) inputInvalid(path);
+	const result: Record<string, ReplicaValue> = {};
+	for (const key of (keys as string[]).sort()) {
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (
+			descriptor === undefined ||
+			!('value' in descriptor) ||
+			descriptor.value === undefined
+		) {
+			inputInvalid(`${path}.${key}`);
+		}
+		defineEnumerable(
+			result,
+			key,
+			cloneJson(descriptor.value, `${path}.${key}`, active, depth + 1)
+		);
+	}
+	active.delete(value);
+	return Object.freeze(result);
+}
+
+export function cloneRevalidation(
+	plan: ReplicaCommandRevalidationPlan
+): ReplicaCommandRevalidationPlan {
+	return Object.freeze({
+		version: 1 as const,
+		required: plan.required,
+		dependencies: Object.freeze([...plan.dependencies]),
+		models: Object.freeze([...plan.models]),
+		relationships: Object.freeze(
+			plan.relationships.map((relationship, index) =>
+				cloneRelationship(
+					relationship,
+					`artifact.revalidation.relationships[${index}]`
+				)
+			)
+		)
+	});
+}
+
+export function cloneRelationship(
+	relationship: ReplicaCommandEffectRelationship,
+	path: string
+): ReplicaCommandEffectRelationship {
+	return Object.freeze({
+		sourceModel: requiredString(
+			relationship.sourceModel,
+			`${path}.sourceModel`
+		),
+		field: requiredString(relationship.field, `${path}.field`),
+		targetModel: requiredString(
+			relationship.targetModel,
+			`${path}.targetModel`
+		)
+	});
+}
+
+
+export function generateDefault(
+	entry: ReplicaCommandInputDefault,
+	generators: ReplicaCommandGenerators | undefined,
+	path: string
+): string {
+	switch (entry.generator) {
+			case 'uuid_v7':
+				return validateUuidV7(
+					(generators?.uuidV7 ?? createReplicaCommandId)(),
+					path,
+					'REPLICA_COMMAND_INPUT_INVALID'
+				);
+		case 'ulid':
+			return validateUlid(
+				(generators?.ulid ?? createUlid)(),
+				path
+			);
+		default:
+			artifactInvalid(`${path}.generator`);
+	}
+}
+
diff --git a/js/src/replica/commands/constants.ts b/js/src/replica/commands/constants.ts
new file mode 100644
index 00000000..f087197d
--- /dev/null
+++ b/js/src/replica/commands/constants.ts
@@ -0,0 +1,7 @@
+export const SHA256 = /^sha256:[0-9a-f]{64}$/;
+export const UUID_V7 =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+export const GRAPHQL_NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
+export const ULID_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+export const MAX_TYPE_DEPTH = 64;
diff --git a/js/src/replica/commands/errors.ts b/js/src/replica/commands/errors.ts
new file mode 100644
index 00000000..8c901950
--- /dev/null
+++ b/js/src/replica/commands/errors.ts
@@ -0,0 +1,29 @@
+import type { ReplicaCommandContractErrorCode } from './types.js';
+
+export function commandErrorMessage(
+	code: ReplicaCommandContractErrorCode,
+	path: string
+): string {
+	switch (code) {
+		case 'REPLICA_COMMAND_ARTIFACT_INVALID':
+			return `Invalid generated replica command artifact at ${path}`;
+		case 'REPLICA_COMMAND_INPUT_INVALID':
+			return `Invalid replica command input at ${path}`;
+		case 'REPLICA_COMMAND_RECEIPT_MISMATCH':
+			return `Replica command receipt does not match ${path}`;
+		case 'REPLICA_COMMAND_TRUSTED_PRESET_MISMATCH':
+			return `Authoritative trusted preset inventory does not match ${path}`;
+	}
+}
+
+export class ReplicaCommandContractError extends Error {
+	readonly code: ReplicaCommandContractErrorCode;
+	readonly path: string;
+
+	constructor(code: ReplicaCommandContractErrorCode, path: string) {
+		super(commandErrorMessage(code, path));
+		this.name = 'ReplicaCommandContractError';
+		this.code = code;
+		this.path = path;
+	}
+}
diff --git a/js/src/replica/commands/implementation.ts b/js/src/replica/commands/implementation.ts
new file mode 100644
index 00000000..84b17b1d
--- /dev/null
+++ b/js/src/replica/commands/implementation.ts
@@ -0,0 +1,8 @@
+/** Re-export surface for command implementation modules (body-split). */
+export * from './util.js';
+export * from './clone.js';
+export * from './presets.js';
+export * from './validate.js';
+export * from './resolve.js';
+export * from './receipt.js';
+export * from './prepare.js';
diff --git a/js/src/replica/commands/index.ts b/js/src/replica/commands/index.ts
new file mode 100644
index 00000000..c5e97358
--- /dev/null
+++ b/js/src/replica/commands/index.ts
@@ -0,0 +1,45 @@
+export {
+	prepareReplicaCommand,
+	prepareReplicaCommandWithTrustedPresets
+} from './prepare.js';
+export {
+	matchReplicaTrustedPresetInventory
+} from './presets.js';
+export {
+	verifyReplicaCommandReceipt
+} from './receipt.js';
+export {
+	ReplicaCommandContractError
+} from './errors.js';
+export type {
+	PrepareReplicaCommandOptions,
+	ReplicaCommandArtifact,
+	ReplicaCommandConfirmation,
+	ReplicaCommandConfirmations,
+	ReplicaCommandContractErrorCode,
+	ReplicaCommandDirectProjection,
+	ReplicaCommandEffect,
+	ReplicaCommandEffectExpression,
+	ReplicaCommandEffectField,
+	ReplicaCommandEffectKey,
+	ReplicaCommandEffectRelationship,
+	ReplicaCommandEffects,
+	ReplicaCommandGenerators,
+	ReplicaCommandInputDefault,
+	ReplicaCommandInputDefaults,
+	ReplicaCommandRevalidationPlan,
+	ReplicaCommandScalarCodec,
+	ReplicaCommandShape,
+	ReplicaCommandTypeDefinition,
+	ReplicaCommandTypeField,
+	ReplicaCommandVariables,
+	ReplicaMatchedTrustedPresetInventory,
+	ReplicaPreparedCommand,
+	ReplicaPreparedCommandEffect,
+	ReplicaPreparedConfirmation,
+	ReplicaPreparedConfirmations,
+	ReplicaPreparedEffectField,
+	ReplicaPreparedEffectKey,
+	ReplicaReceiptVerification,
+	ReplicaTrustedPresetDescriptor
+} from './types.js';
diff --git a/js/src/replica/commands/prepare.ts b/js/src/replica/commands/prepare.ts
new file mode 100644
index 00000000..47fb71a0
--- /dev/null
+++ b/js/src/replica/commands/prepare.ts
@@ -0,0 +1,150 @@
+import type { DistributedTrustedPreset } from '../../protocol.js';
+import { createReplicaCommandId } from '../command-id.js';
+import type {
+	DeepReadonly,
+	PrepareReplicaCommandOptions,
+	ReplicaCommandArtifact,
+	ReplicaCommandVariables,
+	ReplicaPreparedCommand
+} from './types.js';
+import { validateArtifact } from './validate.js';
+import { selectReplicaTrustedPresetInventory } from './presets.js';
+import {
+	materializeInput,
+	resolveConfirmations,
+	resolveDirectProjection,
+	resolveEffect
+} from './resolve.js';
+import {
+	cloneClientSurface,
+	cloneRevalidation,
+	cloneTrustedPresetDescriptors
+} from './clone.js';
+import { validateUuidV7 } from './util.js';
+
+export function prepareReplicaCommand<TInput, TOutput>(
+	artifact: ReplicaCommandArtifact<TInput, TOutput>,
+	input: TInput,
+	options: PrepareReplicaCommandOptions = {}
+): ReplicaPreparedCommand<TInput, TOutput> {
+	return prepareReplicaCommandInternal(artifact, input, options);
+}
+
+/**
+ * Finalize a command with values obtained from the replica's current
+ * authoritative scope generation.
+ *
+ * The incoming inventory is scope-wide, so values owned by other commands are
+ * ignored. Every descriptor consumed by this artifact must nevertheless have
+ * one exact name/codec match before defaults, optimism, or transport state is
+ * created.
+ *
+ * This seam is package-internal and deliberately omitted from the public
+ * `@hops-ops/distributed/replica` entry point.
+ *
+ * @internal
+ */
+export function prepareReplicaCommandWithTrustedPresets<TInput, TOutput>(
+	artifact: ReplicaCommandArtifact<TInput, TOutput>,
+	input: TInput,
+	authoritativePresets: readonly DistributedTrustedPreset[],
+	options: PrepareReplicaCommandOptions = {}
+): ReplicaPreparedCommand<TInput, TOutput> {
+	return prepareReplicaCommandInternal(
+		artifact,
+		input,
+		options,
+		authoritativePresets
+	);
+}
+
+export function prepareReplicaCommandInternal<TInput, TOutput>(
+	artifact: ReplicaCommandArtifact<TInput, TOutput>,
+	input: TInput,
+	options: PrepareReplicaCommandOptions,
+	authoritativePresets?: readonly DistributedTrustedPreset[]
+): ReplicaPreparedCommand<TInput, TOutput> {
+	const descriptors = validateArtifact(
+		artifact,
+		authoritativePresets !== undefined
+	);
+	const trustedPresets =
+		authoritativePresets === undefined
+			? undefined
+			: selectReplicaTrustedPresetInventory(descriptors, authoritativePresets);
+	const defaults = artifact.inputDefaults?.defaults ?? [];
+	const finalizedInput = materializeInput(
+		artifact.input,
+		input,
+		defaults,
+		options.generators
+	) as DeepReadonly<TInput>;
+	const commandId = validateUuidV7(
+		options.commandId ?? createReplicaCommandId(),
+		'options.commandId',
+		'REPLICA_COMMAND_INPUT_INVALID'
+	);
+	const variables = Object.freeze({
+		commandId,
+		...(artifact.input.kind === 'none' ? {} : { input: finalizedInput })
+	}) as ReplicaCommandVariables<TInput>;
+	const operations = Object.freeze(
+		artifact.effects.operations.map((effect, index) =>
+			resolveEffect(
+				effect,
+				finalizedInput,
+				`artifact.effects.operations[${index}]`,
+				trustedPresets
+			)
+		)
+	);
+	const confirmations = resolveConfirmations(
+		artifact.confirmations,
+		finalizedInput,
+		trustedPresets
+	);
+	const directProjection = resolveDirectProjection(
+		artifact.directProjection,
+		finalizedInput,
+		trustedPresets
+	);
+	const protocol = Object.freeze({
+		...artifact.protocol,
+		surface: cloneClientSurface(artifact.protocol.surface),
+		trustedPresets: cloneTrustedPresetDescriptors(
+			artifact.protocol.trustedPresets
+		)
+	});
+	const revalidation = cloneRevalidation(artifact.revalidation);
+
+	return Object.freeze({
+		name: artifact.name,
+		commandId,
+		consistency: artifact.consistency,
+		input: finalizedInput,
+		transport: Object.freeze({
+			mutationField: artifact.mutationField,
+			document: artifact.document,
+			operationHash: artifact.operationHash,
+			protocol,
+			variables
+		}),
+		optimistic: Object.freeze({
+			version: 1 as const,
+			operations,
+			fallback: 'revalidate' as const
+		}),
+		...(confirmations === undefined ? {} : { confirmations }),
+		...(directProjection === undefined ? {} : { directProjection }),
+		revalidation
+	}) as ReplicaPreparedCommand<TInput, TOutput>;
+}
+
+/**
+ * Match two command-local inventories as exact name/codec sets.
+ *
+ * Both sides are reparsed instead of trusting TypeScript annotations. Missing,
+ * extra, duplicate, unsupported, or codec-mismatched entries fail closed.
+ *
+ * @internal
+ */
diff --git a/js/src/replica/commands/presets.ts b/js/src/replica/commands/presets.ts
new file mode 100644
index 00000000..3ba14454
--- /dev/null
+++ b/js/src/replica/commands/presets.ts
@@ -0,0 +1,119 @@
+import {
+	isDistributedTrustedPresetCodec,
+	parseDistributedTrustedPresetInventory,
+	type DistributedTrustedPreset
+} from '../../protocol.js';
+import type { ReplicaValue } from '../types.js';
+import { isPlainRecord } from '../../lib/is-plain-record.js';
+import type {
+	ReplicaMatchedTrustedPresetInventory,
+	ReplicaTrustedPresetDescriptor
+} from './types.js';
+import {
+	artifactInvalid,
+	trustedPresetMismatch
+} from './util.js';
+
+export function matchReplicaTrustedPresetInventory(
+	expected: readonly ReplicaTrustedPresetDescriptor[],
+	authoritative: readonly DistributedTrustedPreset[]
+): ReplicaMatchedTrustedPresetInventory {
+	const descriptors = parseReplicaTrustedPresetDescriptors(expected);
+	let values: readonly DistributedTrustedPreset[];
+	try {
+		values = parseDistributedTrustedPresetInventory(
+			authoritative,
+			'authoritativePresets'
+		);
+	} catch {
+		trustedPresetMismatch('authoritativePresets');
+	}
+	if (descriptors.length !== values.length) {
+		trustedPresetMismatch('authoritativePresets');
+	}
+	const byName = new Map(values.map((preset) => [preset.name, preset] as const));
+	for (let index = 0; index < descriptors.length; index += 1) {
+		const descriptor = descriptors[index]!;
+		const value = byName.get(descriptor.name);
+		if (value === undefined || value.codec !== descriptor.codec) {
+			trustedPresetMismatch(`authoritativePresets.${descriptor.name}`);
+		}
+	}
+	const resolve = (name: string): ReplicaValue => {
+		const value = byName.get(name);
+		if (value === undefined) {
+			trustedPresetMismatch(`authoritativePresets.${name}`);
+		}
+		return value.value as ReplicaValue;
+	};
+	return Object.freeze({
+		descriptors,
+		values,
+		resolve
+	});
+}
+
+export function selectReplicaTrustedPresetInventory(
+	expected: readonly ReplicaTrustedPresetDescriptor[],
+	authoritative: readonly DistributedTrustedPreset[]
+): ReplicaMatchedTrustedPresetInventory {
+	let values: readonly DistributedTrustedPreset[];
+	try {
+		values = parseDistributedTrustedPresetInventory(
+			authoritative,
+			'authoritativePresets'
+		);
+	} catch {
+		trustedPresetMismatch('authoritativePresets');
+	}
+	const names = new Set(expected.map(({ name }) => name));
+	return matchReplicaTrustedPresetInventory(
+		expected,
+		values.filter(({ name }) => names.has(name))
+	);
+}
+
+/**
+ * Verify one parsed server receipt against the immutable prepared contract.
+ *
+ * This does not drive command status or overlay retirement. It only decides
+ * whether task 9 may safely consume the receipt as matching evidence.
+ */
+export function parseReplicaTrustedPresetDescriptors(
+	value: unknown,
+	path = 'artifact.trustedPresets'
+): readonly ReplicaTrustedPresetDescriptor[] {
+	if (!Array.isArray(value)) artifactInvalid(path);
+	const names = new Set<string>();
+	return Object.freeze(
+		value.map((candidate, index) => {
+			const itemPath = `${path}[${index}]`;
+			if (!isPlainRecord(candidate)) artifactInvalid(itemPath);
+			const name = trustedPresetName(candidate.name, `${itemPath}.name`);
+			if (names.has(name)) artifactInvalid(`${itemPath}.name`);
+			names.add(name);
+			if (!isDistributedTrustedPresetCodec(candidate.codec)) {
+				artifactInvalid(`${itemPath}.codec`);
+			}
+			return Object.freeze({
+				name,
+				codec: candidate.codec
+			});
+		})
+	);
+}
+
+export function trustedPresetName(value: unknown, path: string): string {
+	if (
+		typeof value !== 'string' ||
+		value.length === 0 ||
+		value.length > 128 ||
+		value.trim() !== value ||
+		/[\u0000-\u001f\u007f-\u009f]/.test(value)
+	) {
+		artifactInvalid(path);
+	}
+	return value;
+}
+
+
diff --git a/js/src/replica/commands/receipt.ts b/js/src/replica/commands/receipt.ts
new file mode 100644
index 00000000..9fc54731
--- /dev/null
+++ b/js/src/replica/commands/receipt.ts
@@ -0,0 +1,52 @@
+import type { DistributedCommandMetadata } from '../../protocol.js';
+import type {
+	ReplicaPreparedCommand,
+	ReplicaReceiptVerification
+} from './types.js';
+import {
+	receiptMismatch,
+	sameProjectionMultiset
+} from './util.js';
+
+export function verifyReplicaCommandReceipt<TInput, TOutput>(
+	prepared: ReplicaPreparedCommand<TInput, TOutput>,
+	receipt: DistributedCommandMetadata
+): ReplicaReceiptVerification {
+	if (receipt.commandId !== prepared.commandId) {
+		receiptMismatch('receipt.commandId');
+	}
+	if (receipt.consistency !== prepared.consistency) {
+		receiptMismatch('receipt.consistency');
+	}
+
+	const contract = prepared.confirmations;
+	if (contract?.kind === 'unavailable') {
+		return Object.freeze({
+			kind: 'revalidate',
+			revalidate: true,
+			reason: 'confirmation_unavailable'
+		});
+	}
+
+	const expected =
+		contract?.kind === 'finite'
+			? contract.expected.map(({ projector, model }) => ({
+					projection: projector,
+					model
+				}))
+			: [];
+	if (receipt.state === 'in_progress' && receipt.expects.length === 0) {
+		return Object.freeze({
+			kind: 'deferred',
+			revalidate: prepared.revalidation.required
+		});
+	}
+	if (!sameProjectionMultiset(expected, receipt.expects)) {
+		receiptMismatch('receipt.expects');
+	}
+	return Object.freeze({
+		kind: receipt.state === 'in_progress' ? 'deferred' : 'matched',
+		revalidate: prepared.revalidation.required
+	});
+}
+
diff --git a/js/src/replica/commands/resolve.ts b/js/src/replica/commands/resolve.ts
new file mode 100644
index 00000000..54b88c87
--- /dev/null
+++ b/js/src/replica/commands/resolve.ts
@@ -0,0 +1,310 @@
+import type { ReplicaValue } from '../types.js';
+import { isPlainRecord } from '../../lib/is-plain-record.js';
+import {
+	GRAPHQL_NAME
+} from './constants.js';
+import type {
+	ReplicaCommandConfirmations,
+	ReplicaCommandDirectProjection,
+	ReplicaCommandEffect,
+	ReplicaCommandEffectExpression,
+	ReplicaCommandEffectField,
+	ReplicaCommandEffectKey,
+	ReplicaCommandGenerators,
+	ReplicaCommandInputDefault,
+	ReplicaCommandShape,
+	ReplicaCommandTypeDefinition,
+	ReplicaCommandTypeField,
+	ReplicaMatchedTrustedPresetInventory,
+	ReplicaPreparedCommand,
+	ReplicaPreparedCommandEffect,
+	ReplicaPreparedConfirmations,
+	ReplicaPreparedEffectField,
+	ReplicaPreparedEffectKey
+} from './types.js';
+import {
+	artifactInvalid,
+	inputInvalid,
+	requiredString
+} from './util.js';
+import {
+	cloneDefinitionValue,
+	cloneJson,
+	cloneRelationship
+} from './clone.js';
+
+export function materializeInput(
+	shape: ReplicaCommandShape,
+	input: unknown,
+	defaults: readonly ReplicaCommandInputDefault[],
+	generators: ReplicaCommandGenerators | undefined
+): unknown {
+	switch (shape.kind) {
+		case 'none':
+			if (input !== undefined) inputInvalid('input');
+			return undefined;
+		case 'object':
+			return cloneDefinitionValue(
+				shape.definition,
+				input,
+				[],
+				defaults,
+				generators,
+				'input'
+			);
+	}
+}
+
+export function resolveEffect(
+	effect: ReplicaCommandEffect,
+	input: unknown,
+	path: string,
+	trustedPresets: ReplicaMatchedTrustedPresetInventory | undefined
+): ReplicaPreparedCommandEffect {
+	switch (effect.kind) {
+		case 'upsert':
+		case 'patch':
+			return Object.freeze({
+				kind: effect.kind,
+				model: requiredString(effect.model, `${path}.model`),
+				key: resolveKey(effect.key, input, `${path}.key`, trustedPresets),
+				fields: resolveFields(
+					effect.fields,
+					input,
+					`${path}.fields`,
+					trustedPresets
+				)
+			});
+		case 'delete':
+			return Object.freeze({
+				kind: effect.kind,
+				model: requiredString(effect.model, `${path}.model`),
+				key: resolveKey(effect.key, input, `${path}.key`, trustedPresets)
+			});
+		case 'link':
+		case 'unlink':
+			return Object.freeze({
+				kind: effect.kind,
+				relationship: cloneRelationship(
+					effect.relationship,
+					`${path}.relationship`
+				),
+				source: resolveKey(
+					effect.source,
+					input,
+					`${path}.source`,
+					trustedPresets
+				),
+				target: resolveKey(
+					effect.target,
+					input,
+					`${path}.target`,
+					trustedPresets
+				)
+			});
+		case 'invalidate_model':
+			return Object.freeze({
+				kind: effect.kind,
+				model: requiredString(effect.model, `${path}.model`)
+			});
+		case 'invalidate_relationship':
+			return Object.freeze({
+				kind: effect.kind,
+				relationship: cloneRelationship(
+					effect.relationship,
+					`${path}.relationship`
+				),
+				source: resolveKey(
+					effect.source,
+					input,
+					`${path}.source`,
+					trustedPresets
+				)
+			});
+		default:
+			artifactInvalid(`${path}.kind`);
+	}
+}
+
+export function resolveKey(
+	key: ReplicaCommandEffectKey,
+	input: unknown,
+	path: string,
+	trustedPresets: ReplicaMatchedTrustedPresetInventory | undefined
+): ReplicaPreparedEffectKey {
+	if (
+		key === null ||
+		typeof key !== 'object' ||
+		!Array.isArray(key.fields) ||
+		key.fields.length === 0
+	) {
+		artifactInvalid(path);
+	}
+	return Object.freeze({
+		fields: resolveFields(
+			key.fields,
+			input,
+			`${path}.fields`,
+			trustedPresets
+		)
+	});
+}
+
+export function resolveFields(
+	fields: readonly ReplicaCommandEffectField[],
+	input: unknown,
+	path: string,
+	trustedPresets: ReplicaMatchedTrustedPresetInventory | undefined
+): readonly ReplicaPreparedEffectField[] {
+	if (!Array.isArray(fields)) artifactInvalid(path);
+	const names = new Set<string>();
+	return Object.freeze(
+		fields.map((field, index) => {
+			const fieldPath = `${path}[${index}]`;
+			const name = requiredString(field.field, `${fieldPath}.field`);
+			if (names.has(name)) artifactInvalid(`${fieldPath}.field`);
+			names.add(name);
+			return Object.freeze({
+				field: name,
+				value: resolveExpression(
+					field.value,
+					input,
+					`${fieldPath}.value`,
+					trustedPresets
+				)
+			});
+		})
+	);
+}
+
+export function resolveExpression(
+	expression: ReplicaCommandEffectExpression,
+	input: unknown,
+	path: string,
+	trustedPresets: ReplicaMatchedTrustedPresetInventory | undefined
+): ReplicaValue {
+	switch (expression.kind) {
+		case 'input':
+			return resolveInputPath(input, expression.path, path);
+		case 'constant':
+			return cloneJson(expression.value, `${path}.value`);
+		case 'null':
+			return null;
+		case 'trusted_preset':
+			if (trustedPresets === undefined) artifactInvalid(path);
+			return trustedPresets.resolve(expression.name);
+		default:
+			artifactInvalid(`${path}.kind`);
+	}
+}
+
+export function resolveInputPath(
+	input: unknown,
+	segments: readonly string[],
+	path: string
+): ReplicaValue {
+	if (
+		!Array.isArray(segments) ||
+		segments.length === 0 ||
+		segments.some((segment) => !GRAPHQL_NAME.test(segment))
+	) {
+		artifactInvalid(`${path}.path`);
+	}
+	let current = input;
+	for (const segment of segments) {
+		if (
+			!isPlainRecord(current) ||
+			!Object.prototype.hasOwnProperty.call(current, segment)
+		) {
+			inputInvalid(`input.${segments.join('.')}`);
+		}
+		current = current[segment];
+	}
+	if (current === undefined) inputInvalid(`input.${segments.join('.')}`);
+	return current as ReplicaValue;
+}
+
+export function resolveConfirmations(
+	confirmations: ReplicaCommandConfirmations | undefined,
+	input: unknown,
+	trustedPresets: ReplicaMatchedTrustedPresetInventory | undefined
+): ReplicaPreparedConfirmations | undefined {
+	if (confirmations === undefined) return undefined;
+	if (confirmations.kind === 'unavailable') {
+		return Object.freeze({ kind: 'unavailable' as const });
+	}
+	return Object.freeze({
+		kind: 'finite' as const,
+		expected: Object.freeze(
+			confirmations.expected.map((confirmation, index) => {
+				const path = `artifact.confirmations.expected[${index}]`;
+				const partition =
+					confirmation.partition === undefined
+						? undefined
+						: resolveExpression(
+								confirmation.partition,
+								input,
+								`${path}.partition`,
+								trustedPresets
+							);
+				return Object.freeze({
+					projector: requiredString(
+						confirmation.projector,
+						`${path}.projector`
+					),
+					model: requiredString(confirmation.model, `${path}.model`),
+					key: resolveKey(
+						confirmation.key,
+						input,
+						`${path}.key`,
+						trustedPresets
+					),
+					...(partition === undefined ? {} : { partition })
+				});
+			})
+		)
+	});
+}
+
+export function resolveDirectProjection(
+	direct: ReplicaCommandDirectProjection | undefined,
+	input: unknown,
+	trustedPresets: ReplicaMatchedTrustedPresetInventory | undefined
+): ReplicaPreparedCommand<unknown>['directProjection'] | undefined {
+	if (direct === undefined) return undefined;
+	const partition =
+		direct.partition === undefined
+			? undefined
+			: resolveExpression(
+					direct.partition,
+					input,
+					'artifact.directProjection.partition',
+					trustedPresets
+				);
+	return Object.freeze({
+		topology: Object.freeze({ ...direct.topology }),
+		model: direct.model,
+		identityFields: Object.freeze([...direct.identityFields]),
+		...(partition === undefined ? {} : { partition }),
+		changeEpoch: direct.changeEpoch
+	});
+}
+
+export function fieldAtPath(
+	definition: ReplicaCommandTypeDefinition,
+	segments: readonly string[],
+	path: string
+): ReplicaCommandTypeField {
+	let current = definition;
+	for (let index = 0; index < segments.length; index += 1) {
+		const field = current.fields.find(({ name }) => name === segments[index]);
+		if (field === undefined) artifactInvalid(`${path}.path`);
+		if (index + 1 === segments.length) return field;
+		if (field.list || field.nested === undefined) {
+			artifactInvalid(`${path}.path`);
+		}
+		current = field.nested;
+	}
+	artifactInvalid(`${path}.path`);
+}
+
diff --git a/js/src/replica/commands/types.ts b/js/src/replica/commands/types.ts
new file mode 100644
index 00000000..9dfa599d
--- /dev/null
+++ b/js/src/replica/commands/types.ts
@@ -0,0 +1,326 @@
+import type {
+	DistributedCommandConsistency,
+	DistributedTrustedPreset,
+	DistributedTrustedPresetCodec
+} from '../../protocol.js';
+import type { ReplicaClientSurface, ReplicaValue } from '../types.js';
+
+	/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export type ReplicaCommandScalarCodec = DistributedTrustedPresetCodec;
+
+/** Static name/codec declaration emitted without a server-derived value. */
+export type ReplicaTrustedPresetDescriptor = {
+	readonly name: string;
+	readonly codec: ReplicaCommandScalarCodec;
+};
+
+export type ReplicaCommandShape =
+	| { readonly kind: 'none' }
+	| {
+			readonly kind: 'object';
+			readonly definition: ReplicaCommandTypeDefinition;
+	  };
+
+export type ReplicaCommandTypeDefinition = {
+	readonly name: string;
+	readonly fields: readonly ReplicaCommandTypeField[];
+};
+
+export type ReplicaCommandTypeField = {
+	readonly name: string;
+	readonly typeName: string;
+	readonly nullable: boolean;
+	readonly list: boolean;
+	readonly itemNullable: boolean;
+	readonly codec?: ReplicaCommandScalarCodec;
+	readonly nested?: ReplicaCommandTypeDefinition;
+};
+
+export type ReplicaCommandInputDefault = {
+	readonly path: readonly string[];
+	readonly generator: 'uuid_v7' | 'ulid';
+};
+
+export type ReplicaCommandInputDefaults = {
+	readonly version: 1;
+	readonly defaults: readonly ReplicaCommandInputDefault[];
+};
+
+export type ReplicaCommandEffectExpression =
+	| { readonly kind: 'input'; readonly path: readonly string[] }
+	| { readonly kind: 'trusted_preset'; readonly name: string }
+	| { readonly kind: 'constant'; readonly value: ReplicaValue }
+	| { readonly kind: 'null' };
+
+export type ReplicaCommandEffectField = {
+	readonly field: string;
+	readonly value: ReplicaCommandEffectExpression;
+};
+
+export type ReplicaCommandEffectKey = {
+	readonly fields: readonly ReplicaCommandEffectField[];
+};
+
+export type ReplicaCommandEffectRelationship = {
+	readonly sourceModel: string;
+	readonly field: string;
+	readonly targetModel: string;
+};
+
+export type ReplicaCommandEffect =
+	| {
+			readonly kind: 'upsert' | 'patch';
+			readonly model: string;
+			readonly key: ReplicaCommandEffectKey;
+			readonly fields: readonly ReplicaCommandEffectField[];
+	  }
+	| {
+			readonly kind: 'delete';
+			readonly model: string;
+			readonly key: ReplicaCommandEffectKey;
+	  }
+	| {
+			readonly kind: 'link' | 'unlink';
+			readonly relationship: ReplicaCommandEffectRelationship;
+			readonly source: ReplicaCommandEffectKey;
+			readonly target: ReplicaCommandEffectKey;
+	  }
+	| {
+			readonly kind: 'invalidate_model';
+			readonly model: string;
+	  }
+	| {
+			readonly kind: 'invalidate_relationship';
+			readonly relationship: ReplicaCommandEffectRelationship;
+			readonly source: ReplicaCommandEffectKey;
+	  };
+
+export type ReplicaCommandEffects = {
+	readonly version: 1;
+	readonly operations: readonly ReplicaCommandEffect[];
+	readonly fallback: 'revalidate';
+};
+
+export type ReplicaCommandConfirmation = {
+	readonly projector: string;
+	readonly model: string;
+	readonly key: ReplicaCommandEffectKey;
+	readonly partition?: ReplicaCommandEffectExpression;
+};
+
+export type ReplicaCommandConfirmations =
+	| {
+			readonly version: 1;
+			readonly kind: 'finite';
+			readonly expected: readonly ReplicaCommandConfirmation[];
+			readonly fallback: 'revalidate';
+	  }
+	| {
+			readonly version: 1;
+			readonly kind: 'unavailable';
+			readonly expected: readonly [];
+			readonly fallback: 'revalidate';
+	  };
+
+export type ReplicaCommandDirectProjection = {
+	readonly topology: {
+		readonly version: 1;
+		readonly name: string;
+		readonly digest: string;
+	};
+	readonly model: string;
+	readonly identityFields: readonly string[];
+	readonly partition?: ReplicaCommandEffectExpression;
+	readonly changeEpoch: string;
+};
+
+/**
+ * Conservative invalidation inventory emitted by the compiler.
+ *
+ * `dependencies` are the role-visible physical/model dependencies which task 9
+ * may hand to the replica revalidator. `required` means the command cannot be
+ * proven by its local effect/confirmation contract alone.
+ */
+export type ReplicaCommandRevalidationPlan = {
+	readonly version: 1;
+	readonly required: boolean;
+	readonly dependencies: readonly string[];
+	readonly models: readonly string[];
+	readonly relationships: readonly ReplicaCommandEffectRelationship[];
+};
+
+/**
+ * Framework-neutral executable command descriptor emitted by `dctl client`.
+ *
+ * The compiler has already validated the Rust-owned declaration. Runtime
+ * validation remains fail-closed so a stale or hand-edited artifact cannot
+ * create optimistic cache truth.
+ */
+export type ReplicaCommandArtifact<TInput = void, TOutput = unknown> = {
+	readonly version: 1;
+	readonly name: string;
+	readonly mutationField: string;
+	readonly document: string;
+	readonly operationHash: string;
+	readonly protocol: {
+		readonly version: 1;
+		readonly schemaHash: string;
+		readonly protocolHash: string;
+		readonly surface: ReplicaClientSurface;
+		readonly operation: string;
+		/** Exact scope-wide preset inventory for this generated client surface. */
+		readonly trustedPresets: readonly ReplicaTrustedPresetDescriptor[];
+	};
+	readonly input: ReplicaCommandShape;
+	readonly output: ReplicaCommandShape;
+	readonly inputDefaults?: ReplicaCommandInputDefaults;
+	readonly consistency: DistributedCommandConsistency;
+	readonly effects: ReplicaCommandEffects;
+	readonly confirmations?: ReplicaCommandConfirmations;
+	readonly directProjection?: ReplicaCommandDirectProjection;
+	readonly trustedPresets?: readonly ReplicaTrustedPresetDescriptor[];
+	readonly revalidation: ReplicaCommandRevalidationPlan;
+	/** Phantom slots preserve generated input/output types. */
+	readonly __input?: TInput;
+	readonly __output?: TOutput;
+};
+
+export type ReplicaPreparedEffectField = {
+	readonly field: string;
+	readonly value: ReplicaValue;
+};
+
+export type ReplicaPreparedEffectKey = {
+	readonly fields: readonly ReplicaPreparedEffectField[];
+};
+
+export type ReplicaPreparedCommandEffect =
+	| {
+			readonly kind: 'upsert' | 'patch';
+			readonly model: string;
+			readonly key: ReplicaPreparedEffectKey;
+			readonly fields: readonly ReplicaPreparedEffectField[];
+	  }
+	| {
+			readonly kind: 'delete';
+			readonly model: string;
+			readonly key: ReplicaPreparedEffectKey;
+	  }
+	| {
+			readonly kind: 'link' | 'unlink';
+			readonly relationship: ReplicaCommandEffectRelationship;
+			readonly source: ReplicaPreparedEffectKey;
+			readonly target: ReplicaPreparedEffectKey;
+	  }
+	| {
+			readonly kind: 'invalidate_model';
+			readonly model: string;
+	  }
+	| {
+			readonly kind: 'invalidate_relationship';
+			readonly relationship: ReplicaCommandEffectRelationship;
+			readonly source: ReplicaPreparedEffectKey;
+	  };
+
+export type ReplicaPreparedConfirmation = {
+	readonly projector: string;
+	readonly model: string;
+	readonly key: ReplicaPreparedEffectKey;
+	readonly partition?: ReplicaValue;
+};
+
+export type ReplicaPreparedConfirmations =
+	| {
+			readonly kind: 'finite';
+			readonly expected: readonly ReplicaPreparedConfirmation[];
+	  }
+	| { readonly kind: 'unavailable' };
+
+export type DeepReadonly<T> = T extends (...args: never[]) => unknown
+	? T
+	: T extends readonly (infer TItem)[]
+		? readonly DeepReadonly<TItem>[]
+		: T extends object
+			? { readonly [TKey in keyof T]: DeepReadonly<T[TKey]> }
+			: T;
+
+export type ReplicaCommandVariables<TInput> = [TInput] extends [void]
+	? Readonly<{ commandId: string }>
+	: Readonly<{ commandId: string; input: DeepReadonly<TInput> }>;
+
+export type ReplicaPreparedCommand<TInput = void, TOutput = unknown> = {
+	readonly name: string;
+	readonly commandId: string;
+	readonly consistency: DistributedCommandConsistency;
+	readonly input: DeepReadonly<TInput>;
+	readonly transport: {
+		readonly mutationField: string;
+		readonly document: string;
+		readonly operationHash: string;
+		readonly protocol: ReplicaCommandArtifact<TInput, TOutput>['protocol'];
+		readonly variables: ReplicaCommandVariables<TInput>;
+	};
+	readonly optimistic: {
+		readonly version: 1;
+		readonly operations: readonly ReplicaPreparedCommandEffect[];
+		readonly fallback: 'revalidate';
+	};
+	readonly confirmations?: ReplicaPreparedConfirmations;
+	readonly directProjection?: {
+		readonly topology: ReplicaCommandDirectProjection['topology'];
+		readonly model: string;
+		readonly identityFields: readonly string[];
+		readonly partition?: ReplicaValue;
+		readonly changeEpoch: string;
+	};
+	readonly revalidation: ReplicaCommandRevalidationPlan;
+	/** Phantom output slot for generated wrappers. */
+	readonly __output?: TOutput;
+};
+
+export type ReplicaCommandGenerators = {
+	readonly uuidV7?: () => string;
+	readonly ulid?: () => string;
+};
+
+export type PrepareReplicaCommandOptions = {
+	readonly commandId?: string;
+	readonly generators?: ReplicaCommandGenerators;
+};
+
+/**
+ * Exact immutable command-local view over a server-derived scope inventory.
+ *
+ * The backing lookup is intentionally not exposed as a mutable Map.
+ *
+ * @internal
+ */
+export type ReplicaMatchedTrustedPresetInventory = Readonly<{
+	descriptors: readonly ReplicaTrustedPresetDescriptor[];
+	values: readonly DistributedTrustedPreset[];
+	resolve(name: string): ReplicaValue;
+}>;
+
+export type ReplicaReceiptVerification =
+	| {
+			readonly kind: 'matched';
+			readonly revalidate: boolean;
+	  }
+	| {
+			readonly kind: 'deferred';
+			readonly revalidate: boolean;
+	  }
+	| {
+			readonly kind: 'revalidate';
+			readonly revalidate: true;
+			readonly reason: 'confirmation_unavailable';
+	  };
+
+export type ReplicaCommandContractErrorCode =
+	| 'REPLICA_COMMAND_ARTIFACT_INVALID'
+	| 'REPLICA_COMMAND_INPUT_INVALID'
+	| 'REPLICA_COMMAND_RECEIPT_MISMATCH'
+	| 'REPLICA_COMMAND_TRUSTED_PRESET_MISMATCH';
+
+export type TrustedPresetReference = Readonly<{ name: string; path: string }>;
diff --git a/js/src/replica/commands/util.ts b/js/src/replica/commands/util.ts
new file mode 100644
index 00000000..d86018e4
--- /dev/null
+++ b/js/src/replica/commands/util.ts
@@ -0,0 +1,138 @@
+import {
+	SHA256,
+	ULID,
+	ULID_ALPHABET,
+	UUID_V7
+} from './constants.js';
+import type {
+	ReplicaCommandContractErrorCode,
+	ReplicaCommandScalarCodec
+} from './types.js';
+import { ReplicaCommandContractError } from './errors.js';
+import { isDistributedTrustedPresetCodec } from '../../protocol.js';
+
+export function createUlid(): string {
+	const crypto = globalThis.crypto;
+	if (!crypto || typeof crypto.getRandomValues !== 'function') {
+		throw new ReplicaCommandContractError(
+			'REPLICA_COMMAND_INPUT_INVALID',
+			'inputDefaults.ulid'
+		);
+	}
+	let timestamp = Date.now();
+	let time = '';
+	for (let index = 0; index < 10; index += 1) {
+		time = ULID_ALPHABET[timestamp % 32]! + time;
+		timestamp = Math.floor(timestamp / 32);
+	}
+	const bytes = crypto.getRandomValues(new Uint8Array(10));
+	let random = 0n;
+	for (const byte of bytes) random = (random << 8n) | BigInt(byte);
+	let suffix = '';
+	for (let index = 0; index < 16; index += 1) {
+		suffix = ULID_ALPHABET[Number(random & 31n)]! + suffix;
+		random >>= 5n;
+	}
+	return `${time}${suffix}`;
+}
+
+export function validateUuidV7(
+	value: unknown,
+	path: string,
+	code: ReplicaCommandContractErrorCode
+): string {
+	if (typeof value !== 'string' || !UUID_V7.test(value)) {
+		throw new ReplicaCommandContractError(code, path);
+	}
+	return value.toLowerCase();
+}
+
+export function validateUlid(value: unknown, path: string): string {
+	if (typeof value !== 'string' || !ULID.test(value.toUpperCase())) {
+		inputInvalid(path);
+	}
+	return value.toUpperCase();
+}
+
+export function sameProjectionMultiset(
+	expected: readonly { projection: string; model: string }[],
+	actual: readonly { projection: string; model: string }[]
+): boolean {
+	if (expected.length !== actual.length) return false;
+	const counts = new Map<string, number>();
+	for (const item of expected) {
+		const key = JSON.stringify([item.projection, item.model]);
+		counts.set(key, (counts.get(key) ?? 0) + 1);
+	}
+	for (const item of actual) {
+		const key = JSON.stringify([item.projection, item.model]);
+		const count = counts.get(key);
+		if (count === undefined) return false;
+		if (count === 1) counts.delete(key);
+		else counts.set(key, count - 1);
+	}
+	return counts.size === 0;
+}
+
+export function samePath(left: readonly string[], right: readonly string[]): boolean {
+	return (
+		left.length === right.length &&
+		left.every((segment, index) => segment === right[index])
+	);
+}
+
+export function isSupportedCodec(value: string): value is ReplicaCommandScalarCodec {
+	return isDistributedTrustedPresetCodec(value);
+}
+
+export function defineEnumerable<T>(
+	target: Record<string, T>,
+	key: string,
+	value: T
+): void {
+	Object.defineProperty(target, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+}
+
+export function nonempty(value: unknown, path: string): asserts value is string {
+	if (typeof value !== 'string' || value.trim() === '') artifactInvalid(path);
+}
+
+export function requiredString(value: unknown, path: string): string {
+	nonempty(value, path);
+	return value;
+}
+
+export function hash(value: unknown, path: string): void {
+	if (typeof value !== 'string' || !SHA256.test(value)) artifactInvalid(path);
+}
+
+export function artifactInvalid(path: string): never {
+	throw new ReplicaCommandContractError(
+		'REPLICA_COMMAND_ARTIFACT_INVALID',
+		path
+	);
+}
+
+export function inputInvalid(path: string): never {
+	throw new ReplicaCommandContractError('REPLICA_COMMAND_INPUT_INVALID', path);
+}
+
+export function receiptMismatch(path: string): never {
+	throw new ReplicaCommandContractError(
+		'REPLICA_COMMAND_RECEIPT_MISMATCH',
+		path
+	);
+}
+
+export function trustedPresetMismatch(path: string): never {
+	throw new ReplicaCommandContractError(
+		'REPLICA_COMMAND_TRUSTED_PRESET_MISMATCH',
+		path
+	);
+}
+
diff --git a/js/src/replica/commands/validate.ts b/js/src/replica/commands/validate.ts
new file mode 100644
index 00000000..19438f93
--- /dev/null
+++ b/js/src/replica/commands/validate.ts
@@ -0,0 +1,639 @@
+import type { ReplicaClientSurface } from '../types.js';
+import { isPlainRecord } from '../../lib/is-plain-record.js';
+import {
+	GRAPHQL_NAME,
+	MAX_TYPE_DEPTH
+} from './constants.js';
+import type {
+	ReplicaCommandArtifact,
+	ReplicaCommandEffect,
+	ReplicaCommandEffectExpression,
+	ReplicaCommandEffectField,
+	ReplicaCommandEffectKey,
+	ReplicaCommandEffectRelationship,
+	ReplicaCommandInputDefaults,
+	ReplicaCommandShape,
+	ReplicaCommandTypeDefinition,
+	ReplicaTrustedPresetDescriptor,
+	TrustedPresetReference
+} from './types.js';
+import {
+	artifactInvalid,
+	hash,
+	isSupportedCodec,
+	nonempty,
+	requiredString
+} from './util.js';
+import {
+	parseReplicaTrustedPresetDescriptors,
+	trustedPresetName
+} from './presets.js';
+import { fieldAtPath } from './resolve.js';
+
+export function validateArtifact<TInput, TOutput>(
+	artifact: ReplicaCommandArtifact<TInput, TOutput>,
+	allowTrustedPresets: boolean
+): readonly ReplicaTrustedPresetDescriptor[] {
+	if (artifact.version !== 1) artifactInvalid('artifact.version');
+	nonempty(artifact.name, 'artifact.name');
+	if (!GRAPHQL_NAME.test(artifact.mutationField)) {
+		artifactInvalid('artifact.mutationField');
+	}
+	nonempty(artifact.document, 'artifact.document');
+	hash(artifact.operationHash, 'artifact.operationHash');
+	if (artifact.protocol.version !== 1) artifactInvalid('artifact.protocol.version');
+	hash(artifact.protocol.schemaHash, 'artifact.protocol.schemaHash');
+	hash(artifact.protocol.protocolHash, 'artifact.protocol.protocolHash');
+	validateClientSurface(artifact.protocol.surface, 'artifact.protocol.surface');
+	if (artifact.protocol.operation !== artifact.operationHash) {
+		artifactInvalid('artifact.protocol.operation');
+	}
+	const surfaceTrustedPresets = parseReplicaTrustedPresetDescriptors(
+		artifact.protocol.trustedPresets,
+		'artifact.protocol.trustedPresets'
+	);
+	const trustedPresets = parseReplicaTrustedPresetDescriptors(
+		artifact.trustedPresets ?? [],
+		'artifact.trustedPresets'
+	);
+	const surfaceByName = new Map(
+		surfaceTrustedPresets.map((descriptor) => [
+			descriptor.name,
+			descriptor.codec
+		] as const)
+	);
+	for (let index = 0; index < trustedPresets.length; index += 1) {
+		const descriptor = trustedPresets[index]!;
+		if (surfaceByName.get(descriptor.name) !== descriptor.codec) {
+			artifactInvalid(`artifact.trustedPresets[${index}]`);
+		}
+	}
+	validateShape(artifact.input, 'artifact.input', 0, new Set());
+	validateShape(artifact.output, 'artifact.output', 0, new Set());
+	if (artifact.output.kind === 'none') artifactInvalid('artifact.output.kind');
+	validateDefaults(artifact.input, artifact.inputDefaults);
+	if (
+		artifact.consistency !== 'accepted' &&
+		artifact.consistency !== 'fact' &&
+		artifact.consistency !== 'projected'
+	) {
+		artifactInvalid('artifact.consistency');
+	}
+	if (artifact.effects.version !== 1) artifactInvalid('artifact.effects.version');
+	if (artifact.effects.fallback !== 'revalidate') {
+		artifactInvalid('artifact.effects.fallback');
+	}
+	if (!Array.isArray(artifact.effects.operations)) {
+		artifactInvalid('artifact.effects.operations');
+	}
+	for (let index = 0; index < artifact.effects.operations.length; index += 1) {
+		validateEffectArtifact(
+			artifact.effects.operations[index]!,
+			artifact.input,
+			`artifact.effects.operations[${index}]`
+		);
+	}
+	validateConfirmations(artifact);
+	validateDirectProjection(artifact);
+	validateRevalidation(artifact);
+	validateTrustedPresetReferences(
+		artifact,
+		trustedPresets,
+		allowTrustedPresets
+	);
+	return trustedPresets;
+}
+
+export function validateClientSurface(
+	surface: ReplicaClientSurface,
+	path: string
+): void {
+	if (surface === null || typeof surface !== 'object') artifactInvalid(path);
+	requiredString(surface.name, `${path}.name`);
+	if (surface.kind === 'role') return;
+	if (
+		surface.kind !== 'application' ||
+		!Array.isArray(surface.roles) ||
+		surface.roles.length === 0
+	) {
+		artifactInvalid(path);
+	}
+	const roles = new Set<string>();
+	for (let index = 0; index < surface.roles.length; index += 1) {
+		const role = requiredString(surface.roles[index], `${path}.roles[${index}]`);
+		if (roles.has(role)) artifactInvalid(`${path}.roles[${index}]`);
+		roles.add(role);
+	}
+}
+
+export function validateTrustedPresetReferences<TInput, TOutput>(
+	artifact: ReplicaCommandArtifact<TInput, TOutput>,
+	descriptors: readonly ReplicaTrustedPresetDescriptor[],
+	allowTrustedPresets: boolean
+): void {
+	const references = collectTrustedPresetReferences(artifact);
+	const declared = new Set(descriptors.map(({ name }) => name));
+	for (const reference of references) {
+		if (!declared.has(reference.name)) artifactInvalid(reference.path);
+	}
+	const referenced = new Set(references.map(({ name }) => name));
+	for (let index = 0; index < descriptors.length; index += 1) {
+		if (!referenced.has(descriptors[index]!.name)) {
+			artifactInvalid(`artifact.trustedPresets[${index}]`);
+		}
+	}
+	if (!allowTrustedPresets && references.length !== 0) {
+		artifactInvalid(references[0]!.path);
+	}
+}
+
+export function collectTrustedPresetReferences<TInput, TOutput>(
+	artifact: ReplicaCommandArtifact<TInput, TOutput>
+): readonly TrustedPresetReference[] {
+	const out: TrustedPresetReference[] = [];
+	const expression = (
+		value: ReplicaCommandEffectExpression,
+		path: string
+	): void => {
+		if (value.kind === 'trusted_preset') {
+			out.push(Object.freeze({ name: value.name, path }));
+		}
+	};
+	const fields = (
+		value: readonly ReplicaCommandEffectField[],
+		path: string
+	): void => {
+		for (let index = 0; index < value.length; index += 1) {
+			expression(value[index]!.value, `${path}[${index}].value`);
+		}
+	};
+	const key = (value: ReplicaCommandEffectKey, path: string): void => {
+		fields(value.fields, `${path}.fields`);
+	};
+
+	for (let index = 0; index < artifact.effects.operations.length; index += 1) {
+		const effect = artifact.effects.operations[index]!;
+		const path = `artifact.effects.operations[${index}]`;
+		switch (effect.kind) {
+			case 'upsert':
+			case 'patch':
+				key(effect.key, `${path}.key`);
+				fields(effect.fields, `${path}.fields`);
+				break;
+			case 'delete':
+				key(effect.key, `${path}.key`);
+				break;
+			case 'link':
+			case 'unlink':
+				key(effect.source, `${path}.source`);
+				key(effect.target, `${path}.target`);
+				break;
+			case 'invalidate_relationship':
+				key(effect.source, `${path}.source`);
+				break;
+			case 'invalidate_model':
+				break;
+		}
+	}
+	if (artifact.confirmations?.kind === 'finite') {
+		for (
+			let index = 0;
+			index < artifact.confirmations.expected.length;
+			index += 1
+		) {
+			const confirmation = artifact.confirmations.expected[index]!;
+			const path = `artifact.confirmations.expected[${index}]`;
+			key(confirmation.key, `${path}.key`);
+			if (confirmation.partition !== undefined) {
+				expression(confirmation.partition, `${path}.partition`);
+			}
+		}
+	}
+	if (artifact.directProjection?.partition !== undefined) {
+		expression(
+			artifact.directProjection.partition,
+			'artifact.directProjection.partition'
+		);
+	}
+	return Object.freeze(out);
+}
+
+export function validateShape(
+	shape: ReplicaCommandShape,
+	path: string,
+	depth: number,
+	active: Set<ReplicaCommandTypeDefinition>
+): void {
+	if (depth > MAX_TYPE_DEPTH) artifactInvalid(path);
+	switch (shape.kind) {
+		case 'none':
+			return;
+		case 'object':
+			validateDefinition(shape.definition, `${path}.definition`, depth, active);
+			return;
+		default:
+			artifactInvalid(`${path}.kind`);
+	}
+}
+
+export function validateDefinition(
+	definition: ReplicaCommandTypeDefinition,
+	path: string,
+	depth: number,
+	active: Set<ReplicaCommandTypeDefinition>
+): void {
+	if (depth > MAX_TYPE_DEPTH || active.has(definition)) artifactInvalid(path);
+	if (!GRAPHQL_NAME.test(definition.name) || !Array.isArray(definition.fields)) {
+		artifactInvalid(path);
+	}
+	active.add(definition);
+	const names = new Set<string>();
+	for (let index = 0; index < definition.fields.length; index += 1) {
+		const field = definition.fields[index]!;
+		const fieldPath = `${path}.fields[${index}]`;
+		if (!GRAPHQL_NAME.test(field.name) || !GRAPHQL_NAME.test(field.typeName)) {
+			artifactInvalid(fieldPath);
+		}
+		if (names.has(field.name)) artifactInvalid(`${fieldPath}.name`);
+		names.add(field.name);
+		if (
+			typeof field.nullable !== 'boolean' ||
+			typeof field.list !== 'boolean' ||
+			typeof field.itemNullable !== 'boolean' ||
+			(field.itemNullable && !field.list) ||
+			(field.codec === undefined) === (field.nested === undefined)
+		) {
+			artifactInvalid(fieldPath);
+		}
+		if (field.codec !== undefined && !isSupportedCodec(field.codec)) {
+			artifactInvalid(`${fieldPath}.codec`);
+		}
+		if (field.nested !== undefined) {
+			if (field.nested.name !== field.typeName) {
+				artifactInvalid(`${fieldPath}.nested.name`);
+			}
+			validateDefinition(field.nested, `${fieldPath}.nested`, depth + 1, active);
+		}
+	}
+	active.delete(definition);
+}
+
+export function validateDefaults(
+	shape: ReplicaCommandShape,
+	defaults: ReplicaCommandInputDefaults | undefined
+): void {
+	if (defaults === undefined) return;
+	if (defaults.version !== 1 || !Array.isArray(defaults.defaults)) {
+		artifactInvalid('artifact.inputDefaults');
+	}
+	if (shape.kind !== 'object' && defaults.defaults.length > 0) {
+		artifactInvalid('artifact.inputDefaults.defaults');
+	}
+	const paths = new Set<string>();
+	for (let index = 0; index < defaults.defaults.length; index += 1) {
+		const entry = defaults.defaults[index]!;
+		const path = `artifact.inputDefaults.defaults[${index}]`;
+		if (
+			!Array.isArray(entry.path) ||
+			entry.path.length === 0 ||
+			entry.path.some(
+				(segment: unknown) =>
+					typeof segment !== 'string' || !GRAPHQL_NAME.test(segment)
+			) ||
+			(entry.generator !== 'uuid_v7' && entry.generator !== 'ulid')
+		) {
+			artifactInvalid(path);
+		}
+		const key = entry.path.join('\u0000');
+		if (paths.has(key)) artifactInvalid(`${path}.path`);
+		paths.add(key);
+		if (shape.kind === 'object') {
+			const field = fieldAtPath(shape.definition, entry.path, path);
+			if (
+				field.nullable ||
+				field.list ||
+				field.nested !== undefined ||
+				field.codec !== 'string' ||
+				(field.typeName !== 'ID' && field.typeName !== 'String')
+			) {
+				artifactInvalid(path);
+			}
+		}
+	}
+}
+
+export function validateConfirmations<TInput, TOutput>(
+	artifact: ReplicaCommandArtifact<TInput, TOutput>
+): void {
+	const confirmations = artifact.confirmations;
+	if (confirmations === undefined) {
+		if (artifact.consistency === 'fact') {
+			artifactInvalid('artifact.confirmations');
+		}
+		return;
+	}
+	if (
+		confirmations.version !== 1 ||
+		confirmations.fallback !== 'revalidate' ||
+		!Array.isArray(confirmations.expected)
+	) {
+		artifactInvalid('artifact.confirmations');
+	}
+	if (confirmations.kind === 'unavailable') {
+		if (confirmations.expected.length !== 0) {
+			artifactInvalid('artifact.confirmations.expected');
+		}
+	} else if (confirmations.kind === 'finite') {
+		if (confirmations.expected.length === 0) {
+			artifactInvalid('artifact.confirmations.expected');
+		}
+	} else {
+		artifactInvalid('artifact.confirmations.kind');
+	}
+	if (artifact.consistency === 'projected') {
+		artifactInvalid('artifact.confirmations');
+	}
+	if (confirmations.kind === 'finite') {
+		for (let index = 0; index < confirmations.expected.length; index += 1) {
+			const confirmation = confirmations.expected[index]!;
+			const path = `artifact.confirmations.expected[${index}]`;
+			requiredString(confirmation.projector, `${path}.projector`);
+			requiredString(confirmation.model, `${path}.model`);
+			validateKeyArtifact(confirmation.key, artifact.input, `${path}.key`);
+			if (confirmation.partition !== undefined) {
+				validateExpressionArtifact(
+					confirmation.partition,
+					artifact.input,
+					`${path}.partition`
+				);
+			}
+		}
+	}
+}
+
+export function validateDirectProjection<TInput, TOutput>(
+	artifact: ReplicaCommandArtifact<TInput, TOutput>
+): void {
+	const direct = artifact.directProjection;
+	if (artifact.consistency === 'projected' && direct === undefined) {
+		artifactInvalid('artifact.directProjection');
+	}
+	if (artifact.consistency !== 'projected' && direct !== undefined) {
+		artifactInvalid('artifact.directProjection');
+	}
+	if (direct === undefined) return;
+	if (direct.topology.version !== 1) {
+		artifactInvalid('artifact.directProjection.topology.version');
+	}
+	nonempty(direct.topology.name, 'artifact.directProjection.topology.name');
+	hash(direct.topology.digest, 'artifact.directProjection.topology.digest');
+	nonempty(direct.model, 'artifact.directProjection.model');
+	nonempty(direct.changeEpoch, 'artifact.directProjection.changeEpoch');
+	if (
+		!Array.isArray(direct.identityFields) ||
+		direct.identityFields.length === 0 ||
+		artifact.output.kind !== 'object'
+	) {
+		artifactInvalid('artifact.directProjection.identityFields');
+	}
+	const identityFields = new Set<string>();
+	for (let index = 0; index < direct.identityFields.length; index += 1) {
+		const fieldName = direct.identityFields[index]!;
+		const path = `artifact.directProjection.identityFields[${index}]`;
+		if (
+			typeof fieldName !== 'string' ||
+			!GRAPHQL_NAME.test(fieldName) ||
+			identityFields.has(fieldName)
+		) {
+			artifactInvalid(path);
+		}
+		identityFields.add(fieldName);
+		const outputField = artifact.output.definition.fields.find(
+			(field) => field.name === fieldName
+		);
+		if (
+			outputField === undefined ||
+			outputField.nullable ||
+			outputField.list ||
+			outputField.codec === undefined ||
+			outputField.nested !== undefined
+		) {
+			artifactInvalid(path);
+		}
+	}
+	if (direct.partition !== undefined) {
+		validateExpressionArtifact(
+			direct.partition,
+			artifact.input,
+			'artifact.directProjection.partition'
+		);
+	}
+}
+
+export function validateRevalidation<TInput, TOutput>(
+	artifact: ReplicaCommandArtifact<TInput, TOutput>
+): void {
+	const plan = artifact.revalidation;
+	if (
+		plan.version !== 1 ||
+		typeof plan.required !== 'boolean' ||
+		!Array.isArray(plan.dependencies) ||
+		!Array.isArray(plan.models) ||
+		!Array.isArray(plan.relationships)
+	) {
+		artifactInvalid('artifact.revalidation');
+	}
+	for (const [index, dependency] of plan.dependencies.entries()) {
+		nonempty(dependency, `artifact.revalidation.dependencies[${index}]`);
+	}
+	for (const [index, model] of plan.models.entries()) {
+		nonempty(model, `artifact.revalidation.models[${index}]`);
+	}
+	for (const [index, relationship] of plan.relationships.entries()) {
+		validateRelationshipArtifact(
+			relationship,
+			`artifact.revalidation.relationships[${index}]`
+		);
+	}
+	if (
+		(artifact.effects.operations.length === 0 ||
+			(artifact.consistency !== 'projected' &&
+				artifact.confirmations?.kind !== 'finite')) &&
+		!plan.required
+	) {
+		artifactInvalid('artifact.revalidation.required');
+	}
+}
+
+export function validateEffectArtifact(
+	effect: ReplicaCommandEffect,
+	input: ReplicaCommandShape,
+	path: string
+): void {
+	if (effect === null || typeof effect !== 'object') artifactInvalid(path);
+	switch (effect.kind) {
+		case 'upsert':
+		case 'patch':
+			requiredString(effect.model, `${path}.model`);
+			validateKeyArtifact(effect.key, input, `${path}.key`);
+			validateFieldsArtifact(effect.fields, input, `${path}.fields`);
+			return;
+		case 'delete':
+			requiredString(effect.model, `${path}.model`);
+			validateKeyArtifact(effect.key, input, `${path}.key`);
+			return;
+		case 'link':
+		case 'unlink':
+			validateRelationshipArtifact(
+				effect.relationship,
+				`${path}.relationship`
+			);
+			validateKeyArtifact(effect.source, input, `${path}.source`);
+			validateKeyArtifact(effect.target, input, `${path}.target`);
+			return;
+		case 'invalidate_model':
+			requiredString(effect.model, `${path}.model`);
+			return;
+		case 'invalidate_relationship':
+			validateRelationshipArtifact(
+				effect.relationship,
+				`${path}.relationship`
+			);
+			validateKeyArtifact(effect.source, input, `${path}.source`);
+			return;
+		default:
+			artifactInvalid(`${path}.kind`);
+	}
+}
+
+export function validateKeyArtifact(
+	key: ReplicaCommandEffectKey,
+	input: ReplicaCommandShape,
+	path: string
+): void {
+	if (
+		key === null ||
+		typeof key !== 'object' ||
+		!Array.isArray(key.fields) ||
+		key.fields.length === 0
+	) {
+		artifactInvalid(path);
+	}
+	validateFieldsArtifact(key.fields, input, `${path}.fields`);
+}
+
+export function validateFieldsArtifact(
+	fields: readonly ReplicaCommandEffectField[],
+	input: ReplicaCommandShape,
+	path: string
+): void {
+	if (!Array.isArray(fields)) artifactInvalid(path);
+	const names = new Set<string>();
+	for (let index = 0; index < fields.length; index += 1) {
+		const field = fields[index]!;
+		const fieldPath = `${path}[${index}]`;
+		const name = requiredString(field.field, `${fieldPath}.field`);
+		if (names.has(name)) artifactInvalid(`${fieldPath}.field`);
+		names.add(name);
+		validateExpressionArtifact(field.value, input, `${fieldPath}.value`);
+	}
+}
+
+export function validateExpressionArtifact(
+	expression: ReplicaCommandEffectExpression,
+	input: ReplicaCommandShape,
+	path: string
+): void {
+	if (expression === null || typeof expression !== 'object') {
+		artifactInvalid(path);
+	}
+	switch (expression.kind) {
+		case 'input':
+			if (
+				!Array.isArray(expression.path) ||
+				expression.path.length === 0 ||
+				expression.path.some(
+					(segment: unknown) =>
+						typeof segment !== 'string' || !GRAPHQL_NAME.test(segment)
+				)
+			) {
+				artifactInvalid(`${path}.path`);
+			}
+			if (input.kind !== 'object') artifactInvalid(`${path}.path`);
+			fieldAtPath(input.definition, expression.path, path);
+			return;
+		case 'constant':
+			validateArtifactJson(expression.value, `${path}.value`, new Set(), 0);
+			return;
+		case 'null':
+			return;
+		case 'trusted_preset':
+			trustedPresetName(expression.name, `${path}.name`);
+			return;
+		case undefined:
+		default:
+			artifactInvalid(`${path}.kind`);
+	}
+}
+
+export function validateRelationshipArtifact(
+	relationship: ReplicaCommandEffectRelationship,
+	path: string
+): void {
+	if (relationship === null || typeof relationship !== 'object') {
+		artifactInvalid(path);
+	}
+	requiredString(relationship.sourceModel, `${path}.sourceModel`);
+	requiredString(relationship.field, `${path}.field`);
+	requiredString(relationship.targetModel, `${path}.targetModel`);
+}
+
+export function validateArtifactJson(
+	value: unknown,
+	path: string,
+	active: Set<object>,
+	depth: number
+): void {
+	if (depth > MAX_TYPE_DEPTH) artifactInvalid(path);
+	if (
+		value === null ||
+		typeof value === 'string' ||
+		typeof value === 'boolean'
+	) {
+		return;
+	}
+	if (typeof value === 'number') {
+		if (!Number.isFinite(value)) artifactInvalid(path);
+		return;
+	}
+	if (typeof value !== 'object') artifactInvalid(path);
+	if (active.has(value)) artifactInvalid(path);
+	active.add(value);
+	if (Array.isArray(value)) {
+		for (let index = 0; index < value.length; index += 1) {
+			validateArtifactJson(value[index], `${path}[${index}]`, active, depth + 1);
+		}
+		active.delete(value);
+		return;
+	}
+	if (!isPlainRecord(value)) artifactInvalid(path);
+	for (const key of Reflect.ownKeys(value)) {
+		if (typeof key !== 'string') artifactInvalid(path);
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (
+			descriptor === undefined ||
+			!('value' in descriptor) ||
+			descriptor.value === undefined
+		) {
+			artifactInvalid(`${path}.${key}`);
+		}
+		validateArtifactJson(
+			descriptor.value,
+			`${path}.${key}`,
+			active,
+			depth + 1
+		);
+	}
+	active.delete(value);
+}
+
diff --git a/js/src/replica/diagnostics.ts b/js/src/replica/diagnostics.ts
new file mode 100644
index 00000000..358d4a79
--- /dev/null
+++ b/js/src/replica/diagnostics.ts
@@ -0,0 +1,37 @@
+/** Replica diagnostics sink and artifact inspection; implementation in ./diagnostics/. */
+export {
+	createReplicaDevelopmentCapability,
+	createReplicaDiagnostics,
+	inspectReplicaCommandArtifact,
+	inspectReplicaOperationArtifact
+} from './diagnostics/index.js';
+export type {
+	ReplicaArtifactSourceLocation,
+	ReplicaCommandArtifactInspection,
+	ReplicaCommandEffectInspection,
+	ReplicaDevelopmentCapability,
+	ReplicaDiagnosticEvent,
+	ReplicaDiagnosticEventInput,
+	ReplicaDiagnosticFieldValueContext,
+	ReplicaDiagnosticFieldValuePolicy,
+	ReplicaDiagnosticIndex,
+	ReplicaDiagnosticIndexInput,
+	ReplicaDiagnosticLayer,
+	ReplicaDiagnosticLayerInput,
+	ReplicaDiagnosticReceipt,
+	ReplicaDiagnosticReceiptExpectationInput,
+	ReplicaDiagnosticReceiptInput,
+	ReplicaDiagnosticRecord,
+	ReplicaDiagnosticRecordInput,
+	ReplicaDiagnosticReasonContext,
+	ReplicaDiagnosticReasonPolicy,
+	ReplicaDiagnostics,
+	ReplicaDiagnosticsOptions,
+	ReplicaDiagnosticsSink,
+	ReplicaDiagnosticsSnapshot,
+	ReplicaDiagnosticScopeInput,
+	ReplicaDiagnosticStateInput,
+	ReplicaOperationArtifactInspection,
+	ReplicaOperationIndexInspection,
+	ReplicaOperationInjectedFieldInspection
+} from './diagnostics/index.js';
diff --git a/js/src/replica/diagnostics/event-log.ts b/js/src/replica/diagnostics/event-log.ts
new file mode 100644
index 00000000..cde6a12c
--- /dev/null
+++ b/js/src/replica/diagnostics/event-log.ts
@@ -0,0 +1,641 @@
+import { DIAGNOSTICS_BUNDLE_MARKER } from './types.js';
+import type { GraphqlVariables } from '../../types.js';
+import type {
+	ReplicaCommandArtifact
+} from '../commands.js';
+import type {
+	ReplicaIndexCoverage,
+	ReplicaOperationArtifact,
+	ReplicaValue
+} from '../types.js';
+import { reportUnhandledError } from '../../lib/report.js';
+import type {
+	ReplicaCommandArtifactInspection,
+	ReplicaDevelopmentCapability,
+	ReplicaDiagnosticEvent,
+	ReplicaDiagnosticEventInput,
+	ReplicaDiagnosticFieldValueContext,
+	ReplicaDiagnosticFieldValuePolicy,
+	ReplicaDiagnosticIndex,
+	ReplicaDiagnosticIndexInput,
+	ReplicaDiagnosticLayer,
+	ReplicaDiagnosticLayerInput,
+	ReplicaDiagnosticReasonContext,
+	ReplicaDiagnosticReasonPolicy,
+	ReplicaDiagnosticReceipt,
+	ReplicaDiagnosticReceiptInput,
+	ReplicaDiagnosticRecord,
+	ReplicaDiagnosticRecordInput,
+	ReplicaDiagnostics,
+	ReplicaDiagnosticsOptions,
+	ReplicaDiagnosticsSnapshot,
+	ReplicaDiagnosticScopeInput,
+	ReplicaDiagnosticStateInput,
+	ReplicaOperationArtifactInspection
+} from './types.js';
+import {
+	inspectReplicaCommandArtifact,
+	inspectReplicaOperationArtifact
+} from './inspect.js';
+
+const reportUnhandledObserverError = reportUnhandledError;
+const DEFAULT_MAX_EVENTS = 200;
+const MAX_EVENTS = 10_000;
+const MAX_VALUE_DEPTH = 64;
+const MAX_REASON_LENGTH = 160;
+const developmentCapabilities = new WeakSet<object>();
+
+
+export function createReplicaDevelopmentCapability(): ReplicaDevelopmentCapability {
+	const capability = Object.freeze({ version: 1 as const });
+	developmentCapabilities.add(capability);
+	return capability as ReplicaDevelopmentCapability;
+}
+
+/** Framework-neutral diagnostics store shared by every framework adapter. */
+export function createReplicaDiagnostics(
+	options: ReplicaDiagnosticsOptions = {}
+): ReplicaDiagnostics {
+	return new ReplicaDiagnosticsImpl(options);
+}
+
+class ReplicaDiagnosticsImpl implements ReplicaDiagnostics {
+	readonly includeStructuralIdentities: boolean;
+	readonly #maxEvents: number;
+	readonly #now: () => number;
+	readonly #reportObserverError: (error: AggregateError) => void;
+	readonly #fieldValues: ReplicaDiagnosticFieldValuePolicy | undefined;
+	readonly #reasons: ReplicaDiagnosticReasonPolicy | undefined;
+	readonly #listeners = new Set<(snapshot: ReplicaDiagnosticsSnapshot) => void>();
+	readonly #pseudonyms = new Map<string, Map<string, string>>();
+	readonly #operations = new Map<string, ReplicaOperationArtifactInspection>();
+	readonly #commands = new Map<string, ReplicaCommandArtifactInspection>();
+	#scope: ReplicaDiagnosticScopeInput = Object.freeze({
+		generation: 0,
+		established: false
+	});
+	#records: readonly ReplicaDiagnosticRecord[] = Object.freeze([]);
+	#indexes: readonly ReplicaDiagnosticIndex[] = Object.freeze([]);
+	#layers: readonly ReplicaDiagnosticLayer[] = Object.freeze([]);
+	#receipts: readonly ReplicaDiagnosticReceipt[] = Object.freeze([]);
+	#events: ReplicaDiagnosticEvent[] = [];
+	#sequence = 0;
+	#snapshotCache: ReplicaDiagnosticsSnapshot | undefined;
+
+	constructor(options: ReplicaDiagnosticsOptions) {
+		this.#maxEvents = boundedEventLimit(options.maxEvents);
+		this.#now = options.now ?? Date.now;
+		this.#reportObserverError =
+			options.onObserverError ?? reportUnhandledObserverError;
+		this.includeStructuralIdentities = validCapability(options.development);
+		if (options.fieldValues !== undefined) {
+			if (!validCapability(options.fieldValues.capability)) {
+				throw new TypeError(
+					'diagnostic field values require a development capability'
+				);
+			}
+			if (
+				typeof options.fieldValues.allow !== 'function' ||
+				typeof options.fieldValues.redact !== 'function'
+			) {
+				throw new TypeError(
+					'diagnostic field values require explicit allow and redact functions'
+				);
+			}
+			this.#fieldValues = options.fieldValues;
+		}
+		if (options.reasons !== undefined) {
+			if (!validCapability(options.reasons.capability)) {
+				throw new TypeError(
+					'diagnostic reasons require a development capability'
+				);
+			}
+			if (typeof options.reasons.redact !== 'function') {
+				throw new TypeError(
+					'diagnostic reasons require an explicit redact function'
+				);
+			}
+			this.#reasons = options.reasons;
+		}
+	}
+
+	redactRecordValue(
+		context: ReplicaDiagnosticFieldValueContext,
+		value: ReplicaValue
+	): ReplicaValue | undefined {
+		const policy = this.#fieldValues;
+		if (policy === undefined || !policy.allow(context)) return undefined;
+		const redacted = policy.redact(value, context);
+		return redacted === undefined
+			? undefined
+			: cloneDiagnosticValue(redacted, 'diagnostic field value');
+	}
+
+	update(state: ReplicaDiagnosticStateInput): void {
+		validateScope(state.scope);
+		if (state.scope.generation !== this.#scope.generation) {
+			this.#clearScopedState();
+		}
+		this.#scope = freezeScope(state.scope);
+		this.#records = Object.freeze(
+			state.records
+				.map((record) => this.#record(record))
+				.sort((left, right) => left.key.localeCompare(right.key))
+		);
+		this.#indexes = Object.freeze(
+			state.indexes
+				.map((index) => this.#index(index))
+				.sort((left, right) => left.key.localeCompare(right.key))
+		);
+		this.#layers = Object.freeze(
+			state.layers
+				.map((layer) => this.#layer(layer))
+				.sort((left, right) => left.sequence - right.sequence)
+		);
+		this.#receipts = Object.freeze(
+			state.receipts
+				.map((receipt) => this.#receipt(receipt))
+				.sort((left, right) => left.commandId.localeCompare(right.commandId))
+		);
+		this.#snapshotCache = undefined;
+		this.#notify();
+	}
+
+	event(input: ReplicaDiagnosticEventInput): void {
+		const at = this.#now();
+		if (!Number.isFinite(at)) {
+			throw new TypeError('diagnostic clock must return a finite number');
+		}
+		const event = this.#event(input, ++this.#sequence, at);
+		this.#events.push(event);
+		if (this.#events.length > this.#maxEvents) {
+			this.#events.splice(0, this.#events.length - this.#maxEvents);
+		}
+		this.#snapshotCache = undefined;
+		this.#notify();
+	}
+
+	operation<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>
+	): void {
+		const inspection = inspectReplicaOperationArtifact(artifact);
+		this.#operations.set(inspection.id, inspection);
+		this.#snapshotCache = undefined;
+		this.#notify();
+	}
+
+	command<TInput, TOutput>(artifact: ReplicaCommandArtifact<TInput, TOutput>): void {
+		const inspection = inspectReplicaCommandArtifact(artifact);
+		this.#commands.set(inspection.name, inspection);
+		this.#snapshotCache = undefined;
+		this.#notify();
+	}
+
+	inspectOperation<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>
+	): ReplicaOperationArtifactInspection {
+		const inspection = inspectReplicaOperationArtifact(artifact);
+		this.#operations.set(inspection.id, inspection);
+		this.#snapshotCache = undefined;
+		this.#notify();
+		return inspection;
+	}
+
+	inspectCommand<TInput, TOutput>(
+		artifact: ReplicaCommandArtifact<TInput, TOutput>
+	): ReplicaCommandArtifactInspection {
+		const inspection = inspectReplicaCommandArtifact(artifact);
+		this.#commands.set(inspection.name, inspection);
+		this.#snapshotCache = undefined;
+		this.#notify();
+		return inspection;
+	}
+
+	readonly snapshot = (): ReplicaDiagnosticsSnapshot => {
+		const cached = this.#snapshotCache;
+		if (cached !== undefined) return cached;
+		const snapshot = Object.freeze({
+			version: 1 as const,
+			marker: DIAGNOSTICS_BUNDLE_MARKER,
+			mode: this.includeStructuralIdentities ? 'development' : 'redacted',
+			sequence: this.#sequence,
+			scope: this.#scope,
+			records: this.#records,
+			indexes: this.#indexes,
+			layers: this.#layers,
+			receipts: this.#receipts,
+			artifacts: Object.freeze({
+				operations: Object.freeze(
+					[...this.#operations.values()].sort((left, right) =>
+						left.id.localeCompare(right.id)
+					)
+				),
+				commands: Object.freeze(
+					[...this.#commands.values()].sort((left, right) =>
+						left.name.localeCompare(right.name)
+					)
+				)
+			}),
+			events: Object.freeze([...this.#events])
+		});
+		this.#snapshotCache = snapshot;
+		return snapshot;
+	};
+
+	readonly getSnapshot = (): ReplicaDiagnosticsSnapshot => this.snapshot();
+
+	readonly subscribe = (
+		listener: (snapshot: ReplicaDiagnosticsSnapshot) => void
+	): (() => void) => {
+		if (typeof listener !== 'function') {
+			throw new TypeError('diagnostic listener must be a function');
+		}
+		this.#listeners.add(listener);
+		try {
+			listener(this.snapshot());
+		} catch (error) {
+			this.#listeners.delete(listener);
+			this.#report([error]);
+		}
+		return () => this.#listeners.delete(listener);
+	};
+
+	clear(): void {
+		this.#scope = Object.freeze({ generation: 0, established: false });
+		this.#clearScopedState();
+		this.#sequence = 0;
+		this.#snapshotCache = undefined;
+		this.#notify();
+	}
+
+	#clearScopedState(): void {
+		this.#records = Object.freeze([]);
+		this.#indexes = Object.freeze([]);
+		this.#layers = Object.freeze([]);
+		this.#receipts = Object.freeze([]);
+		this.#events = [];
+		this.#operations.clear();
+		this.#commands.clear();
+		this.#pseudonyms.clear();
+		this.#snapshotCache = undefined;
+	}
+
+	#record(input: ReplicaDiagnosticRecordInput): ReplicaDiagnosticRecord {
+		const values =
+			this.#fieldValues === undefined || input.values === undefined
+				? undefined
+				: freezeValueRecord(input.values, 'diagnostic record values');
+		return Object.freeze({
+			key: this.#identifier('record', input.key),
+			...(input.model === undefined ? {} : { model: input.model }),
+			revision: input.revision,
+			incarnation: input.incarnation,
+			tombstone: input.tombstone,
+			...(input.tombstoneRevision === undefined
+				? {}
+				: { tombstoneRevision: input.tombstoneRevision }),
+			presentFields: Object.freeze([...input.presentFields].sort()),
+			presentLinks: Object.freeze([...input.presentLinks].sort()),
+			...(values === undefined ? {} : { values })
+		});
+	}
+
+	#index(input: ReplicaDiagnosticIndexInput): ReplicaDiagnosticIndex {
+		const rawArguments = input.arguments ?? Object.freeze({});
+		const argumentsValue =
+			this.includeStructuralIdentities && Object.keys(rawArguments).length > 0
+				? freezeValueRecord(rawArguments, 'diagnostic index arguments')
+				: undefined;
+		const staleReason =
+			input.staleReason === undefined
+				? undefined
+				: this.#reason(
+						input.staleReason,
+						Object.freeze({
+							kind: 'index-stale' as const,
+							indexKey: input.key
+						}),
+						structuralStaleReason(input.staleReason)
+					);
+		return Object.freeze({
+			key: this.#identifier('index', input.key),
+			revision: input.revision,
+			...(input.staleRevision === undefined
+				? {}
+				: { staleRevision: input.staleRevision }),
+			records: Object.freeze(
+				input.records.map((key) => this.#identifier('record', key))
+			),
+			complete: input.complete,
+			deleted: input.deleted,
+			...(input.field === undefined ? {} : { field: input.field }),
+			...(input.parent === undefined
+				? {}
+				: { parent: this.#identifier('record', input.parent) }),
+			argumentNames: Object.freeze(
+				[...(input.argumentNames ?? Object.keys(rawArguments))].sort()
+			),
+			...(argumentsValue === undefined ? {} : { arguments: argumentsValue }),
+			...(input.coverage === undefined
+				? {}
+				: { coverage: freezeCoverage(input.coverage) }),
+			dependencies: Object.freeze([...(input.dependencies ?? [])].sort()),
+			...(staleReason === undefined ? {} : { staleReason }),
+			nullValue: input.nullValue === true
+		});
+	}
+
+	#layer(input: ReplicaDiagnosticLayerInput): ReplicaDiagnosticLayer {
+		return Object.freeze({
+			id: this.#identifier('transaction', input.id),
+			sequence: input.sequence,
+			state: input.state,
+			recordChanges: input.recordChanges,
+			indexChanges: input.indexChanges,
+			semanticChanges: input.semanticChanges
+		});
+	}
+
+	#receipt(input: ReplicaDiagnosticReceiptInput): ReplicaDiagnosticReceipt {
+		return Object.freeze({
+			commandId: this.#identifier('transaction', input.commandId),
+			state: input.state,
+			...(input.consistency === undefined
+				? {}
+				: { consistency: input.consistency }),
+			expectations: Object.freeze(
+				input.expectations
+					.map((expectation) =>
+						Object.freeze({
+							projection: expectation.projection,
+							model: expectation.model,
+							observed: expectation.observed
+						})
+					)
+					.sort((left, right) =>
+						`${left.projection}\0${left.model}`.localeCompare(
+							`${right.projection}\0${right.model}`
+						)
+					)
+			)
+		});
+	}
+
+	#event(
+		input: ReplicaDiagnosticEventInput,
+		sequence: number,
+		at: number
+	): ReplicaDiagnosticEvent {
+		if (input.kind === 'layer') {
+			const reason =
+				input.reason === undefined
+					? undefined
+					: this.#reason(
+							input.reason,
+							Object.freeze({
+								kind: 'layer' as const,
+								layerId: input.layer,
+								action: input.action
+							}),
+							structuralLayerReason(input.reason)
+						);
+			return Object.freeze({
+				...input,
+				layer: this.#identifier('transaction', input.layer),
+				...(reason === undefined ? {} : { reason }),
+				sequence,
+				at
+			});
+		}
+		if (input.kind === 'receipt') {
+			return Object.freeze({
+				...input,
+				command: this.#identifier('transaction', input.command),
+				sequence,
+				at
+			});
+		}
+		if (input.kind === 'index-decision') {
+			const reason =
+				input.reason === undefined
+					? undefined
+					: this.#reason(
+							input.reason,
+							Object.freeze({
+								kind: 'index-stale' as const,
+								indexKey: input.index
+							}),
+							structuralStaleReason(input.reason)
+						);
+			return Object.freeze({
+				...input,
+				index: this.#identifier('index', input.index),
+				...(reason === undefined ? {} : { reason }),
+				sequence,
+				at
+			});
+		}
+		return Object.freeze({ ...input, sequence, at });
+	}
+
+	#reason(
+		value: string,
+		context: ReplicaDiagnosticReasonContext,
+		fallback: string
+	): string {
+		const redacted = this.#reasons?.redact(value, context);
+		return redacted === undefined
+			? fallback
+			: boundedDiagnosticReason(redacted, fallback);
+	}
+
+	#identifier(kind: string, value: string): string {
+		if (this.includeStructuralIdentities) return value;
+		let values = this.#pseudonyms.get(kind);
+		if (values === undefined) {
+			values = new Map();
+			this.#pseudonyms.set(kind, values);
+		}
+		let identifier = values.get(value);
+		if (identifier === undefined) {
+			identifier = `${kind}#${values.size + 1}`;
+			values.set(value, identifier);
+		}
+		return identifier;
+	}
+
+	#notify(): void {
+		if (this.#listeners.size === 0) return;
+		const snapshot = this.snapshot();
+		const errors: unknown[] = [];
+		for (const listener of this.#listeners) {
+			try {
+				listener(snapshot);
+			} catch (error) {
+				errors.push(error);
+			}
+		}
+		this.#report(errors);
+	}
+
+	#report(errors: unknown[]): void {
+		if (errors.length === 0) return;
+		try {
+			this.#reportObserverError(
+				new AggregateError(errors, 'replica diagnostic listener failed')
+			);
+		} catch (reporterError) {
+			queueMicrotask(() => {
+				throw new AggregateError(
+					[...errors, reporterError],
+					'replica diagnostic error reporter failed'
+				);
+			});
+		}
+	}
+}
+
+function boundedEventLimit(value: number | undefined): number {
+	if (value === undefined) return DEFAULT_MAX_EVENTS;
+	if (!Number.isSafeInteger(value) || value < 1 || value > MAX_EVENTS) {
+		throw new TypeError(
+			`diagnostic maxEvents must be an integer between 1 and ${MAX_EVENTS}`
+		);
+	}
+	return value;
+}
+
+function structuralStaleReason(value: string): string {
+	switch (value) {
+		case 'application-stale':
+		case 'graphql-error':
+		case 'graphql-partial-error':
+		case 'incomplete-result':
+		case 'record-lifecycle-changed':
+		case 'revision-conflict':
+			return value;
+		default: {
+			const queryPlan = /^query-plan:([a-z][a-z0-9_]{0,63})(?::.*)?$/.exec(
+				value
+			);
+			return queryPlan === null
+				? 'application-stale'
+				: `query-plan:${queryPlan[1]}`;
+		}
+	}
+}
+
+function structuralLayerReason(value: string): string {
+	return value === 'retired-earlier-layer' ||
+		value === 'rejected-earlier-layer'
+		? value
+		: 'application-layer-change';
+}
+
+function boundedDiagnosticReason(value: string, fallback: string): string {
+	if (typeof value !== 'string') {
+		throw new TypeError('diagnostic reason redactor must return a string');
+	}
+	const normalized = value
+		.replace(/[\u0000-\u001f\u007f]/g, '\ufffd')
+		.trim();
+	if (normalized.length === 0) return fallback;
+	return [...normalized].slice(0, MAX_REASON_LENGTH).join('');
+}
+
+function validCapability(
+	capability: ReplicaDevelopmentCapability | undefined
+): boolean {
+	return (
+		capability !== undefined &&
+		typeof capability === 'object' &&
+		developmentCapabilities.has(capability)
+	);
+}
+
+function validateScope(scope: ReplicaDiagnosticScopeInput): void {
+	if (!Number.isSafeInteger(scope.generation) || scope.generation < 0) {
+		throw new TypeError('diagnostic scope generation must be an unsigned integer');
+	}
+	if (scope.established) {
+		if (scope.protocolVersion !== 1 || !nonempty(scope.schemaHash)) {
+			throw new TypeError(
+				'established diagnostic scope requires protocol and schema hash'
+			);
+		}
+	} else if (scope.protocolVersion !== undefined || scope.schemaHash !== undefined) {
+		throw new TypeError(
+			'unestablished diagnostic scope cannot carry protocol identity'
+		);
+	}
+}
+
+function freezeScope(scope: ReplicaDiagnosticScopeInput): ReplicaDiagnosticScopeInput {
+	return Object.freeze({
+		generation: scope.generation,
+		established: scope.established,
+		...(scope.protocolVersion === undefined
+			? {}
+			: { protocolVersion: scope.protocolVersion }),
+		...(scope.schemaHash === undefined ? {} : { schemaHash: scope.schemaHash })
+	});
+}
+
+function freezeCoverage(coverage: ReplicaIndexCoverage): ReplicaIndexCoverage {
+	return Object.freeze({ ...coverage });
+}
+
+function freezeValueRecord(
+	value: Readonly<Record<string, ReplicaValue>>,
+	description: string,
+	depth = 0
+): Readonly<Record<string, ReplicaValue>> {
+	const entries = Object.entries(value)
+		.sort(([left], [right]) => left.localeCompare(right))
+		.map(
+			([key, entry]) =>
+				[
+					key,
+					cloneDiagnosticValue(entry, `${description}.${key}`, depth + 1)
+				] as const
+		);
+	return Object.freeze(Object.fromEntries(entries));
+}
+
+function cloneDiagnosticValue(
+	value: ReplicaValue,
+	description: string,
+	depth = 0
+): ReplicaValue {
+	if (depth > MAX_VALUE_DEPTH) {
+		throw new TypeError(`${description} exceeds diagnostic value depth`);
+	}
+	if (
+		value === null ||
+		typeof value === 'string' ||
+		typeof value === 'boolean' ||
+		(typeof value === 'number' && Number.isFinite(value))
+	) {
+		return value;
+	}
+	if (Array.isArray(value)) {
+		return Object.freeze(
+			value.map((entry, index) =>
+				cloneDiagnosticValue(entry, `${description}[${index}]`, depth + 1)
+			)
+		);
+	}
+	if (typeof value !== 'object') {
+		throw new TypeError(`${description} must be a JSON-compatible value`);
+	}
+	return freezeValueRecord(
+		value as Readonly<Record<string, ReplicaValue>>,
+		description,
+		depth
+	);
+}
+
+function nonempty(value: unknown): value is string {
+	return typeof value === 'string' && value.length > 0;
+}
+
diff --git a/js/src/replica/diagnostics/implementation.ts b/js/src/replica/diagnostics/implementation.ts
new file mode 100644
index 00000000..949d8c17
--- /dev/null
+++ b/js/src/replica/diagnostics/implementation.ts
@@ -0,0 +1,4 @@
+/** Re-export surface for diagnostics modules (body-split). */
+export * from './types.js';
+export * from './inspect.js';
+export * from './event-log.js';
diff --git a/js/src/replica/diagnostics/index.ts b/js/src/replica/diagnostics/index.ts
new file mode 100644
index 00000000..1d676672
--- /dev/null
+++ b/js/src/replica/diagnostics/index.ts
@@ -0,0 +1,36 @@
+export {
+	createReplicaDevelopmentCapability,
+	createReplicaDiagnostics,
+	inspectReplicaCommandArtifact,
+	inspectReplicaOperationArtifact
+} from './implementation.js';
+export type {
+	ReplicaArtifactSourceLocation,
+	ReplicaCommandArtifactInspection,
+	ReplicaCommandEffectInspection,
+	ReplicaDevelopmentCapability,
+	ReplicaDiagnosticEvent,
+	ReplicaDiagnosticEventInput,
+	ReplicaDiagnosticFieldValueContext,
+	ReplicaDiagnosticFieldValuePolicy,
+	ReplicaDiagnosticIndex,
+	ReplicaDiagnosticIndexInput,
+	ReplicaDiagnosticLayer,
+	ReplicaDiagnosticLayerInput,
+	ReplicaDiagnosticReceipt,
+	ReplicaDiagnosticReceiptExpectationInput,
+	ReplicaDiagnosticReceiptInput,
+	ReplicaDiagnosticRecord,
+	ReplicaDiagnosticRecordInput,
+	ReplicaDiagnosticReasonContext,
+	ReplicaDiagnosticReasonPolicy,
+	ReplicaDiagnostics,
+	ReplicaDiagnosticsOptions,
+	ReplicaDiagnosticsSink,
+	ReplicaDiagnosticsSnapshot,
+	ReplicaDiagnosticScopeInput,
+	ReplicaDiagnosticStateInput,
+	ReplicaOperationArtifactInspection,
+	ReplicaOperationIndexInspection,
+	ReplicaOperationInjectedFieldInspection
+} from './implementation.js';
diff --git a/js/src/replica/diagnostics/inspect.ts b/js/src/replica/diagnostics/inspect.ts
new file mode 100644
index 00000000..9b8f09b5
--- /dev/null
+++ b/js/src/replica/diagnostics/inspect.ts
@@ -0,0 +1,233 @@
+import type { GraphqlVariables } from '../../types.js';
+import type {
+	ReplicaCommandArtifact,
+	ReplicaCommandEffectExpression
+} from '../commands.js';
+import type {
+	ReplicaObjectSelection,
+	ReplicaOperationArtifact,
+	ReplicaRootSelection
+} from '../types.js';
+import type {
+	ReplicaArtifactSourceLocation,
+	ReplicaCommandArtifactInspection,
+	ReplicaCommandEffectInspection,
+	ReplicaOperationArtifactInspection,
+	ReplicaOperationIndexInspection,
+	ReplicaOperationInjectedFieldInspection
+} from './types.js';
+
+export function inspectReplicaOperationArtifact<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	artifact: ReplicaOperationArtifact<TData, TVariables>
+): ReplicaOperationArtifactInspection {
+	const injected: ReplicaOperationInjectedFieldInspection[] = [];
+	const dependencies = new Set<string>();
+	const indexes: ReplicaOperationIndexInspection[] = [];
+
+	for (const root of artifact.roots) {
+		const path = root.responseKey;
+		inspectRoot(root, path, injected, dependencies, indexes);
+	}
+
+	const source = safeArtifactSource(artifact.source);
+	return Object.freeze({
+		kind: 'operation' as const,
+		id: artifact.id,
+		...(source === undefined
+			? {}
+			: {
+					source: Object.freeze({
+						path: source.path,
+						line: source.line,
+						column: source.column
+					})
+				}),
+		rootFields: Object.freeze(artifact.roots.map((root) => root.field)),
+		injectedFields: Object.freeze(injected),
+		dependencies: Object.freeze([...dependencies].sort()),
+		indexes: Object.freeze(indexes),
+		...(artifact.live === undefined
+			? {}
+			: { live: Object.freeze({ operation: artifact.live.id }) })
+	});
+}
+
+export function inspectReplicaCommandArtifact<TInput, TOutput>(
+	artifact: ReplicaCommandArtifact<TInput, TOutput>
+): ReplicaCommandArtifactInspection {
+	const effects = artifact.effects.operations.map((effect) => {
+		const models = new Set<string>();
+		const fields = new Set<string>();
+		const sources = new Set<ReplicaCommandEffectInspection['valueSources'][number]>();
+		if ('model' in effect) models.add(effect.model);
+		if ('relationship' in effect) {
+			models.add(effect.relationship.sourceModel);
+			models.add(effect.relationship.targetModel);
+			fields.add(effect.relationship.field);
+		}
+		if ('key' in effect) {
+			for (const field of effect.key.fields) {
+				fields.add(field.field);
+				sources.add(expressionSource(field.value));
+			}
+		}
+		if ('source' in effect) {
+			for (const field of effect.source.fields) {
+				fields.add(field.field);
+				sources.add(expressionSource(field.value));
+			}
+		}
+		if ('target' in effect) {
+			for (const field of effect.target.fields) {
+				fields.add(field.field);
+				sources.add(expressionSource(field.value));
+			}
+		}
+		if ('fields' in effect) {
+			for (const field of effect.fields) {
+				fields.add(field.field);
+				sources.add(expressionSource(field.value));
+			}
+		}
+		return Object.freeze({
+			kind: effect.kind,
+			models: Object.freeze([...models].sort()),
+			fields: Object.freeze([...fields].sort()),
+			valueSources: Object.freeze([...sources].sort())
+		});
+	});
+	return Object.freeze({
+		kind: 'command' as const,
+		name: artifact.name,
+		operation: artifact.operationHash,
+		consistency: artifact.consistency,
+		effects: Object.freeze(effects),
+		revalidation: Object.freeze({
+			required: artifact.revalidation.required,
+			dependencies: Object.freeze(
+				[...artifact.revalidation.dependencies].sort()
+			),
+			models: Object.freeze([...artifact.revalidation.models].sort())
+		})
+	});
+}
+
+function inspectRoot(
+	root: ReplicaRootSelection,
+	path: string,
+	injected: ReplicaOperationInjectedFieldInspection[],
+	dependencies: Set<string>,
+	indexes: ReplicaOperationIndexInspection[]
+): void {
+	for (const dependency of root.dependencies) dependencies.add(dependency);
+	indexes.push(
+		Object.freeze({
+			path,
+			field: root.field,
+			cardinality: root.cardinality,
+			dependencies: Object.freeze([...root.dependencies].sort()),
+			...(root.coverage === undefined
+				? {}
+				: { coverage: root.coverage.kind }),
+			filtered: root.filter !== undefined,
+			ordered: root.order !== undefined,
+			...(root.pagination === undefined
+				? {}
+				: { pagination: root.pagination.kind })
+		})
+	);
+	inspectSelection(
+		root.selection,
+		path,
+		injected,
+		dependencies,
+		indexes
+	);
+}
+
+function safeArtifactSource(
+	source: ReplicaOperationArtifact<unknown, GraphqlVariables>['source']
+): ReplicaArtifactSourceLocation | undefined {
+	if (source === undefined) return undefined;
+	const path = source.path;
+	const driveAbsolute = path.length >= 2 && path[1] === ':';
+	if (
+		path.length === 0 ||
+		path.length > 4_096 ||
+		/[\u0000-\u001f\u007f]/.test(path) ||
+		path.startsWith('/') ||
+		driveAbsolute ||
+		path.includes('\\') ||
+		path.split('/').includes('..') ||
+		(!path.endsWith('.graphql') && !path.endsWith('.gql')) ||
+		!Number.isSafeInteger(source.line) ||
+		source.line < 1 ||
+		!Number.isSafeInteger(source.column) ||
+		source.column < 1
+	) {
+		return undefined;
+	}
+	return Object.freeze({
+		path,
+		line: source.line,
+		column: source.column
+	});
+}
+
+function inspectSelection(
+	selection: ReplicaObjectSelection,
+	path: string,
+	injected: ReplicaOperationInjectedFieldInspection[],
+	dependencies: Set<string>,
+	indexes: ReplicaOperationIndexInspection[]
+): void {
+	for (const member of selection.members) {
+		const memberPath = `${path}.${member.responseKey}`;
+		if (member.kind === 'scalar') {
+			if (member.expose === false) {
+				injected.push(
+					Object.freeze({
+						path: memberPath,
+						responseKey: member.responseKey,
+						field: member.field
+					})
+				);
+			}
+			continue;
+		}
+		const indexDependencies = new Set([
+			...member.dependencies,
+			...(member.relationship?.dependencies ?? [])
+		]);
+		for (const dependency of indexDependencies) {
+			dependencies.add(dependency);
+		}
+		indexes.push(
+			Object.freeze({
+				path: memberPath,
+				field: member.field,
+				cardinality: member.cardinality,
+				dependencies: Object.freeze([...indexDependencies].sort()),
+				...(member.coverage === undefined
+					? {}
+					: { coverage: member.coverage.kind }),
+				filtered: member.filter !== undefined,
+				ordered: member.order !== undefined,
+				...(member.pagination === undefined
+					? {}
+					: { pagination: member.pagination.kind })
+			})
+		);
+		inspectSelection(member.selection, memberPath, injected, dependencies, indexes);
+	}
+}
+
+function expressionSource(
+	expression: ReplicaCommandEffectExpression
+): ReplicaCommandEffectInspection['valueSources'][number] {
+	return expression.kind;
+}
+
diff --git a/js/src/replica/diagnostics/types.ts b/js/src/replica/diagnostics/types.ts
new file mode 100644
index 00000000..bc63ccf4
--- /dev/null
+++ b/js/src/replica/diagnostics/types.ts
@@ -0,0 +1,378 @@
+import type { GraphqlVariables } from '../../types.js';
+import type { ReplicaCommandArtifact } from '../commands.js';
+import type {
+	ReplicaIndexCoverage,
+	ReplicaOperationArtifact,
+	ReplicaValue,
+	ReplicaWriteSource
+} from '../types.js';
+
+export const DIAGNOSTICS_BUNDLE_MARKER = 'distributed-replica-diagnostics-v1' as const;
+
+declare const developmentCapabilityBrand: unique symbol;
+
+export type ReplicaDevelopmentCapability = Readonly<{
+	readonly version: 1;
+	readonly [developmentCapabilityBrand]: true;
+}>;
+
+export type ReplicaDiagnosticFieldValueContext = Readonly<{
+	recordKey: string;
+	model?: string;
+	field: string;
+	kind: 'field' | 'link';
+}>;
+
+export type ReplicaDiagnosticFieldValuePolicy = Readonly<{
+	capability: ReplicaDevelopmentCapability;
+	/** A field must be explicitly authorized before its value reaches the redactor. */
+	allow(context: ReplicaDiagnosticFieldValueContext): boolean;
+	/**
+	 * Return a support-safe replacement. Returning undefined omits the value.
+	 * Raw values are never retained before this function returns.
+	 */
+	redact(
+		value: ReplicaValue,
+		context: ReplicaDiagnosticFieldValueContext
+	): ReplicaValue | undefined;
+}>;
+
+export type ReplicaDiagnosticReasonContext =
+	| Readonly<{
+			kind: 'index-stale';
+			indexKey: string;
+	  }>
+	| Readonly<{
+			kind: 'layer';
+			layerId: string;
+			action: 'created' | 'rebased' | 'accepted' | 'retired' | 'rejected';
+	  }>;
+
+export type ReplicaDiagnosticReasonPolicy = Readonly<{
+	capability: ReplicaDevelopmentCapability;
+	/**
+	 * Return a bounded support-safe replacement. Returning undefined keeps the
+	 * structural default (`application-stale`, for example).
+	 */
+	redact(
+		reason: string,
+		context: ReplicaDiagnosticReasonContext
+	): string | undefined;
+}>;
+
+export type ReplicaDiagnosticsOptions = Readonly<{
+	maxEvents?: number;
+	development?: ReplicaDevelopmentCapability;
+	fieldValues?: ReplicaDiagnosticFieldValuePolicy;
+	reasons?: ReplicaDiagnosticReasonPolicy;
+	now?: () => number;
+	onObserverError?: (error: AggregateError) => void;
+}>;
+
+export type ReplicaDiagnosticScopeInput = Readonly<{
+	generation: number;
+	established: boolean;
+	protocolVersion?: 1;
+	schemaHash?: string;
+}>;
+
+export type ReplicaDiagnosticRecordInput = Readonly<{
+	key: string;
+	model?: string;
+	revision: string;
+	incarnation: string;
+	tombstone: boolean;
+	tombstoneRevision?: string;
+	presentFields: readonly string[];
+	presentLinks: readonly string[];
+	/**
+	 * Values in this object must already be support-safe redactor output. Replica
+	 * core obtains them only through `redactRecordValue`.
+	 */
+	values?: Readonly<Record<string, ReplicaValue>>;
+}>;
+
+export type ReplicaDiagnosticIndexInput = Readonly<{
+	key: string;
+	revision: string;
+	staleRevision?: string;
+	records: readonly string[];
+	complete: boolean;
+	deleted: boolean;
+	field?: string;
+	parent?: string;
+	argumentNames?: readonly string[];
+	arguments?: Readonly<Record<string, ReplicaValue>>;
+	coverage?: ReplicaIndexCoverage;
+	dependencies?: readonly string[];
+	staleReason?: string;
+	nullValue?: boolean;
+}>;
+
+export type ReplicaDiagnosticLayerInput = Readonly<{
+	id: string;
+	sequence: number;
+	state: 'optimistic' | 'accepted';
+	recordChanges: number;
+	indexChanges: number;
+	semanticChanges: number;
+}>;
+
+export type ReplicaDiagnosticReceiptExpectationInput = Readonly<{
+	projection: string;
+	model: string;
+	observed: boolean;
+}>;
+
+export type ReplicaDiagnosticReceiptInput = Readonly<{
+	commandId: string;
+	state: 'optimistic' | 'accepted' | 'accepted_pending_projection';
+	consistency?: 'accepted' | 'fact' | 'projected';
+	expectations: readonly ReplicaDiagnosticReceiptExpectationInput[];
+}>;
+
+/** Engine-independent state contract implemented by DistributedReplica. */
+export type ReplicaDiagnosticStateInput = Readonly<{
+	scope: ReplicaDiagnosticScopeInput;
+	records: readonly ReplicaDiagnosticRecordInput[];
+	indexes: readonly ReplicaDiagnosticIndexInput[];
+	layers: readonly ReplicaDiagnosticLayerInput[];
+	receipts: readonly ReplicaDiagnosticReceiptInput[];
+}>;
+
+export type ReplicaDiagnosticEventInput =
+	| Readonly<{
+			kind: 'normalization';
+			operation: string;
+			source: ReplicaWriteSource;
+			records: number;
+			indexes: number;
+			partial: boolean;
+	  }>
+	| Readonly<{
+			kind: 'index-decision';
+			index: string;
+			decision: 'maintained' | 'stale' | 'revalidate';
+			reason?: string;
+	  }>
+	| Readonly<{
+			kind: 'revalidation';
+			operation: string;
+			action: 'requested' | 'deduplicated' | 'skipped-complete';
+			reason: 'watch' | 'refresh' | 'stale';
+	  }>
+	| Readonly<{
+			kind: 'layer';
+			layer: string;
+			action: 'created' | 'rebased' | 'accepted' | 'retired' | 'rejected';
+			recordChanges?: number;
+			indexChanges?: number;
+			reason?: string;
+	  }>
+	| Readonly<{
+			kind: 'receipt';
+			command: string;
+			state:
+				| 'optimistic'
+				| 'accepted'
+				| 'accepted_pending_projection'
+				| 'projected'
+				| 'rejected';
+			obligations: number;
+			observed: number;
+	  }>
+	| Readonly<{
+			kind: 'response-fenced';
+			operation: string;
+			transport: 'http' | 'live';
+			reason: 'authorization-generation' | 'operation-generation' | 'superseded';
+	  }>
+	| Readonly<{
+			kind: 'gc';
+			records: number;
+	  }>
+	| Readonly<{
+			kind: 'hydration';
+			action: 'accepted' | 'rejected';
+			reason:
+				| 'accepted'
+				| 'invalid'
+				| 'scope-mismatch'
+				| 'artifact-mismatch'
+				| 'active-scope-mismatch'
+				| 'metadata-mismatch';
+	  }>
+	| Readonly<{
+			kind: 'scope';
+			action: 'established' | 'changed' | 'invalidated';
+			generation: number;
+			schemaHash?: string;
+	  }>;
+
+export type ReplicaDiagnosticEvent = ReplicaDiagnosticEventInput &
+	Readonly<{
+		sequence: number;
+		at: number;
+	}>;
+
+export type ReplicaDiagnosticRecord = Readonly<{
+	key: string;
+	model?: string;
+	revision: string;
+	incarnation: string;
+	tombstone: boolean;
+	tombstoneRevision?: string;
+	presentFields: readonly string[];
+	presentLinks: readonly string[];
+	values?: Readonly<Record<string, ReplicaValue>>;
+}>;
+
+export type ReplicaDiagnosticIndex = Readonly<{
+	key: string;
+	revision: string;
+	staleRevision?: string;
+	records: readonly string[];
+	complete: boolean;
+	deleted: boolean;
+	field?: string;
+	parent?: string;
+	argumentNames: readonly string[];
+	arguments?: Readonly<Record<string, ReplicaValue>>;
+	coverage?: ReplicaIndexCoverage;
+	dependencies: readonly string[];
+	staleReason?: string;
+	nullValue: boolean;
+}>;
+
+export type ReplicaDiagnosticLayer = Readonly<{
+	id: string;
+	sequence: number;
+	state: 'optimistic' | 'accepted';
+	recordChanges: number;
+	indexChanges: number;
+	semanticChanges: number;
+}>;
+
+export type ReplicaDiagnosticReceipt = Readonly<{
+	commandId: string;
+	state: 'optimistic' | 'accepted' | 'accepted_pending_projection';
+	consistency?: 'accepted' | 'fact' | 'projected';
+	expectations: readonly ReplicaDiagnosticReceiptExpectationInput[];
+}>;
+
+export type ReplicaArtifactSourceLocation = Readonly<{
+	path: string;
+	line: number;
+	column: number;
+}>;
+
+export type ReplicaOperationInjectedFieldInspection = Readonly<{
+	path: string;
+	responseKey: string;
+	field: string;
+}>;
+
+export type ReplicaOperationIndexInspection = Readonly<{
+	path: string;
+	field: string;
+	cardinality: 'one' | 'many';
+	dependencies: readonly string[];
+	coverage?: ReplicaIndexCoverage['kind'];
+	filtered: boolean;
+	ordered: boolean;
+	pagination?: 'complete' | 'offset' | 'cursor';
+}>;
+
+export type ReplicaOperationArtifactInspection = Readonly<{
+	kind: 'operation';
+	id: string;
+	source?: ReplicaArtifactSourceLocation;
+	rootFields: readonly string[];
+	injectedFields: readonly ReplicaOperationInjectedFieldInspection[];
+	dependencies: readonly string[];
+	indexes: readonly ReplicaOperationIndexInspection[];
+	live?: Readonly<{ operation: string }>;
+}>;
+
+export type ReplicaCommandEffectInspection = Readonly<{
+	kind:
+		| 'upsert'
+		| 'patch'
+		| 'delete'
+		| 'link'
+		| 'unlink'
+		| 'invalidate_model'
+		| 'invalidate_relationship';
+	models: readonly string[];
+	fields: readonly string[];
+	valueSources: readonly (
+		| 'input'
+		| 'trusted_preset'
+		| 'constant'
+		| 'null'
+	)[];
+}>;
+
+export type ReplicaCommandArtifactInspection = Readonly<{
+	kind: 'command';
+	name: string;
+	operation: string;
+	consistency: 'accepted' | 'fact' | 'projected';
+	effects: readonly ReplicaCommandEffectInspection[];
+	revalidation: Readonly<{
+		required: boolean;
+		dependencies: readonly string[];
+		models: readonly string[];
+	}>;
+}>;
+
+export type ReplicaDiagnosticsSnapshot = Readonly<{
+	version: 1;
+	marker: typeof DIAGNOSTICS_BUNDLE_MARKER;
+	mode: 'redacted' | 'development';
+	sequence: number;
+	scope: ReplicaDiagnosticScopeInput;
+	records: readonly ReplicaDiagnosticRecord[];
+	indexes: readonly ReplicaDiagnosticIndex[];
+	layers: readonly ReplicaDiagnosticLayer[];
+	receipts: readonly ReplicaDiagnosticReceipt[];
+	artifacts: Readonly<{
+		operations: readonly ReplicaOperationArtifactInspection[];
+		commands: readonly ReplicaCommandArtifactInspection[];
+	}>;
+	events: readonly ReplicaDiagnosticEvent[];
+}>;
+
+/**
+ * Small core-facing contract. Implementations must not throw into replica
+ * transactions; DistributedReplica also catches sink failures defensively.
+ */
+export interface ReplicaDiagnosticsSink {
+	readonly includeStructuralIdentities: boolean;
+	redactRecordValue?(
+		context: ReplicaDiagnosticFieldValueContext,
+		value: ReplicaValue
+	): ReplicaValue | undefined;
+	update(state: ReplicaDiagnosticStateInput): void;
+	event(event: ReplicaDiagnosticEventInput): void;
+	operation<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>
+	): void;
+	command<TInput, TOutput>(artifact: ReplicaCommandArtifact<TInput, TOutput>): void;
+}
+
+export interface ReplicaDiagnostics extends ReplicaDiagnosticsSink {
+	snapshot(): ReplicaDiagnosticsSnapshot;
+	/** React/useSyncExternalStore-compatible alias with stable referential output. */
+	getSnapshot(): ReplicaDiagnosticsSnapshot;
+	subscribe(listener: (snapshot: ReplicaDiagnosticsSnapshot) => void): () => void;
+	inspectOperation<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>
+	): ReplicaOperationArtifactInspection;
+	inspectCommand<TInput, TOutput>(
+		artifact: ReplicaCommandArtifact<TInput, TOutput>
+	): ReplicaCommandArtifactInspection;
+	clear(): void;
+}
+
+/** Create an unforgeable, process-local opt-in to development identities. */
diff --git a/js/src/replica/distributed-replica.ts b/js/src/replica/distributed-replica.ts
new file mode 100644
index 00000000..241ad946
--- /dev/null
+++ b/js/src/replica/distributed-replica.ts
@@ -0,0 +1,2 @@
+/** Public entry for createDistributedReplica; implementation lives in ./distributed-replica/. */
+export { createDistributedReplica } from './distributed-replica/index.js';
diff --git a/js/src/replica/distributed-replica/clocks.ts b/js/src/replica/distributed-replica/clocks.ts
new file mode 100644
index 00000000..ff20bc6d
--- /dev/null
+++ b/js/src/replica/distributed-replica/clocks.ts
@@ -0,0 +1,239 @@
+import type { CacheValue } from '../../internal/cache-engine.js';
+import {
+	compareDistributedDecimal,
+	DistributedProtocolError,
+	type DistributedIndexRevision,
+	type DistributedLiveCursor,
+	type DistributedProtocolEnvelope,
+	type DistributedQuerySnapshot,
+	type DistributedRecordRevision
+} from '../../protocol.js';
+import type { ReplicaValue } from '../types.js';
+import type {
+	IndexDisposition,
+	IndexProtocolClock,
+	OperationProtocolState,
+	ProjectedRecordFence,
+	RecordProtocolClock
+} from './types.js';
+
+import { deepEqual } from '../../lib/deep-equal.js';
+
+export function sameRecordRevision(
+	left: DistributedRecordRevision,
+	right: DistributedRecordRevision
+): boolean {
+	return (
+		left.model === right.model &&
+		left.scopeToken === right.scopeToken &&
+		left.incarnation === right.incarnation &&
+		left.revision === right.revision &&
+		left.tombstone === right.tombstone
+	);
+}
+
+export function recordKeyMatchesModel(recordKey: string, model: string): boolean {
+	return recordKey.startsWith(`record:${encodeURIComponent(model)}:`);
+}
+
+export function modelFromRecordKey(recordKey: string): string | undefined {
+	if (!recordKey.startsWith('record:')) return undefined;
+	const separator = recordKey.indexOf(':', 'record:'.length);
+	if (separator === -1) return undefined;
+	try {
+		const model = decodeURIComponent(
+			recordKey.slice('record:'.length, separator)
+		);
+		return model.length === 0 ? undefined : model;
+	} catch {
+		return undefined;
+	}
+}
+
+export function compareIndexVector(
+	current: ReadonlyMap<string, IndexProtocolClock>,
+	incoming: readonly DistributedIndexRevision[]
+): IndexDisposition {
+	if (current.size === 0) return 'fresh';
+	if (current.size !== incoming.length) return 'incomparable';
+	let lower = false;
+	let higher = false;
+	for (const evidence of incoming) {
+		const previous = current.get(evidence.projection);
+		if (
+			previous === undefined ||
+			previous.scopeToken !== evidence.scopeToken
+		) {
+			return 'incomparable';
+		}
+		const comparison = compareDistributedDecimal(
+			evidence.position,
+			previous.position
+		);
+		lower ||= comparison < 0;
+		higher ||= comparison > 0;
+	}
+	if (lower && higher) return 'incomparable';
+	if (lower) return 'lower';
+	if (higher) return 'higher';
+	return 'equal';
+}
+
+export function compareSnapshotToOperationState(
+	state: OperationProtocolState,
+	snapshot: DistributedQuerySnapshot
+): IndexDisposition {
+	if (state.snapshotScope === undefined) return 'fresh';
+	if (state.snapshotScope !== snapshot.scopeToken) return 'incomparable';
+	if (state.indexClocks.size === 0 || snapshot.indexes.length === 0) {
+		return state.indexClocks.size === snapshot.indexes.length
+			? 'equal'
+			: 'incomparable';
+	}
+	return compareIndexVector(state.indexClocks, snapshot.indexes);
+}
+
+export function isComparableHandoffDisposition(
+	disposition: IndexDisposition
+): boolean {
+	return (
+		disposition === 'fresh' ||
+		disposition === 'equal' ||
+		disposition === 'higher'
+	);
+}
+
+export function indexClockMap(
+	indexes: readonly DistributedIndexRevision[]
+): Map<string, IndexProtocolClock> {
+	return new Map(
+		indexes.map((index) => [
+			index.projection,
+			{
+				scopeToken: index.scopeToken,
+				position: index.position
+			}
+		])
+	);
+}
+
+export function latestCursors(
+	snapshot: DistributedQuerySnapshot,
+	live: DistributedProtocolEnvelope['live']
+): readonly DistributedLiveCursor[] {
+	if (live !== undefined) {
+		return live.supported ? live.cursors : Object.freeze([]);
+	}
+	return Object.freeze(
+		snapshot.indexes.flatMap((index) =>
+			index.resume === undefined ? [] : [index.resume]
+		)
+	);
+}
+
+export function responsePathKey(path: readonly string[]): string {
+	return JSON.stringify(path);
+}
+
+export function compareRecordClock(
+	left: RecordProtocolClock,
+	right: RecordProtocolClock
+): -1 | 0 | 1 {
+	const incarnation = compareDistributedDecimal(
+		left.incarnation,
+		right.incarnation
+	);
+	return incarnation === 0
+		? compareDistributedDecimal(left.revision, right.revision)
+		: incarnation;
+}
+
+export function compareEvidenceToProjectedFence(
+	evidence: DistributedRecordRevision,
+	fence: ProjectedRecordFence
+): -1 | 0 | 1 | undefined {
+	if (evidence.scopeToken !== fence.clock.scopeToken) return undefined;
+	return compareRecordClock(
+		{
+			scopeToken: evidence.scopeToken,
+			incarnation: evidence.incarnation,
+			revision: evidence.revision,
+			tombstone: evidence.tombstone
+		},
+		fence.clock
+	);
+}
+
+export function sameRecordClock(
+	left: RecordProtocolClock,
+	right: RecordProtocolClock
+): boolean {
+	return (
+		left.scopeToken === right.scopeToken &&
+		left.incarnation === right.incarnation &&
+		left.revision === right.revision &&
+		left.tombstone === right.tombstone
+	);
+}
+
+export function incrementCanonicalDecimal(value: string): string {
+	const digits = [...value];
+	let carry = true;
+	for (let index = digits.length - 1; index >= 0 && carry; index -= 1) {
+		const digit = digits[index]!;
+		if (digit === '9') {
+			digits[index] = '0';
+		} else {
+			digits[index] = '0123456789'[
+				'0123456789'.indexOf(digit) + 1
+			]!;
+			carry = false;
+		}
+	}
+	if (carry) digits.unshift('1');
+	return digits.join('');
+}
+
+export function compareCanonicalDecimalStrings(
+	left: string,
+	right: string
+): number {
+	return left.length === right.length
+		? left.localeCompare(right)
+		: left.length < right.length
+			? -1
+			: 1;
+}
+
+export function protocolInvalid(path: string): never {
+	throw new DistributedProtocolError(
+		'DISTRIBUTED_PROTOCOL_INVALID',
+		path
+	);
+}
+
+export function freezeRecordClock(clock: RecordProtocolClock): RecordProtocolClock {
+	return Object.freeze({
+		scopeToken: clock.scopeToken,
+		incarnation: clock.incarnation,
+		revision: clock.revision,
+		tombstone: clock.tombstone
+	});
+}
+
+export function compareProjectedRecordFields(
+	projected: Readonly<Record<string, ReplicaValue>>,
+	incoming: Readonly<Record<string, CacheValue>>
+): 'conflict' | 'partial' | 'complete' {
+	let complete = true;
+	for (const [field, value] of Object.entries(projected)) {
+		if (!Object.prototype.hasOwnProperty.call(incoming, field)) {
+			complete = false;
+			continue;
+		}
+		if (!deepEqual(value, incoming[field])) return 'conflict';
+	}
+	return complete ? 'complete' : 'partial';
+}
+
+export { deepEqual };
diff --git a/js/src/replica/distributed-replica/constants.ts b/js/src/replica/distributed-replica/constants.ts
new file mode 100644
index 00000000..4bb10179
--- /dev/null
+++ b/js/src/replica/distributed-replica/constants.ts
@@ -0,0 +1,13 @@
+import type { GqlError } from '../../types.js';
+import type { DistributedTrustedPreset } from '../../protocol.js';
+
+export const EMPTY_ERRORS: readonly GqlError[] = Object.freeze([]);
+/** Matches protocol.ts MAX_EVIDENCE_ITEMS without making it public API. */
+export const MAX_ANONYMOUS_RECORD_CLOCKS = 4_096;
+export const SHA256 = /^sha256:[0-9a-f]{64}$/;
+export const EMPTY_TRUSTED_PRESETS: readonly DistributedTrustedPreset[] = Object.freeze([]);
+export const EMPTY_CACHE_SNAPSHOT = Object.freeze({
+	version: 1 as const,
+	records: Object.freeze([]),
+	indexes: Object.freeze([])
+});
diff --git a/js/src/replica/distributed-replica/helpers.ts b/js/src/replica/distributed-replica/helpers.ts
new file mode 100644
index 00000000..c6b56e6e
--- /dev/null
+++ b/js/src/replica/distributed-replica/helpers.ts
@@ -0,0 +1,739 @@
+import {
+	type BaseCacheWriter,
+	type CacheEngineSnapshot,
+	type CacheIndexCoverage,
+	type CacheIndexMetadata,
+	type CacheValue,
+	type OptimisticLayerView
+} from '../../internal/cache-engine.js';
+import type { GqlError, GraphqlVariables } from '../../types.js';
+import {
+	isDistributedTrustedPresetCodec,
+	type DistributedQuerySnapshot,
+	type DistributedRecordRevision,
+	type DistributedTrustedPreset
+} from '../../protocol.js';
+import type { ReplicaTrustedPresetDescriptor } from '../commands.js';
+import type { ReplicaCommandSurfaceContract } from '../command-runtime.js';
+import {
+	canonicalVariables,
+	cloneJsonValue,
+	replicaIndexKey,
+	replicaRecordKey,
+	resolveArguments
+} from '../identity.js';
+import {
+	type ReplicaIndexMaintenanceSnapshot,
+	type ReplicaIndexSemanticChange,
+	type ReplicaIndexSemanticLayer
+} from '../index-maintenance.js';
+import type { MaterializedReplicaResult } from '../materialize.js';
+import { validateReplicaOperationBinding as validatedArtifactBinding } from '../operation-binding.js';
+import {
+	embeddedRecordKey,
+	runtimeRoot,
+	type RuntimeObjectBranch,
+	type RuntimeObjectSelection,
+	type RuntimeRootSelection
+} from '../selection.js';
+import type {
+	ReplicaBaseWriter,
+	ReplicaIdentity,
+	ReplicaIndexTarget,
+	ReplicaModelArtifact,
+	ReplicaOperationArtifact,
+	ReplicaRecordPatch,
+	ReplicaResultEnvelope,
+	ReplicaRevision,
+	ReplicaSnapshot,
+	ReplicaStatus,
+	ReplicaWriteSource
+} from '../types.js';
+import {
+	deepEqual,
+	modelFromRecordKey,
+	protocolInvalid,
+	responsePathKey
+} from './clocks.js';
+import { EMPTY_ERRORS, SHA256 } from './constants.js';
+import type {
+	OperationProtocolSource,
+	QueryState,
+	RegisteredCommandAuthorityContract
+} from './types.js';
+
+import { reportSafely, reportUnhandledError } from '../../lib/report.js';
+
+export { deepEqual } from './clocks.js';
+
+export function prepareRecordEvidence(
+	snapshot: DistributedQuerySnapshot,
+	commandRecords: readonly DistributedRecordRevision[]
+): {
+	byPath: Map<string, DistributedRecordRevision>;
+	tombstones: readonly DistributedRecordRevision[];
+	pathless: readonly DistributedRecordRevision[];
+	livePaths: ReadonlySet<string>;
+} {
+	const byPath = new Map<string, DistributedRecordRevision>();
+	const tombstones: DistributedRecordRevision[] = [];
+	const pathless: DistributedRecordRevision[] = [];
+	const livePaths = new Set<string>();
+	for (const evidence of snapshot.records) {
+		if (evidence.path === undefined) {
+			if (evidence.tombstone) tombstones.push(evidence);
+			else pathless.push(evidence);
+			continue;
+		}
+		const key = responsePathKey(evidence.path);
+		if (byPath.has(key)) {
+			protocolInvalid('extensions.distributed.snapshot.records.path');
+		}
+		byPath.set(key, evidence);
+		if (evidence.tombstone) tombstones.push(evidence);
+		else livePaths.add(key);
+	}
+	for (const evidence of commandRecords) {
+		if (evidence.tombstone) tombstones.push(evidence);
+		else pathless.push(evidence);
+	}
+	return {
+		byPath,
+		tombstones: Object.freeze(tombstones),
+		pathless: Object.freeze(pathless),
+		livePaths
+	};
+}
+
+export function replicaResultIndexKeys<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	artifact: ReplicaOperationArtifact<TData, TVariables>,
+	variables: TVariables,
+	envelope: ReplicaResultEnvelope<TData>,
+	snapshot: DistributedQuerySnapshot
+): ReadonlySet<string> {
+	const keys = new Set<string>();
+	if (
+		envelope.data === undefined ||
+		envelope.data === null ||
+		!isReplicaResultObject(envelope.data) ||
+		(envelope.errors ?? []).some(
+			(error) => !Array.isArray(error.path) || error.path.length === 0
+		)
+	) {
+		return keys;
+	}
+	const errorPaths = (envelope.errors ?? []).flatMap((error) =>
+		Array.isArray(error.path) && error.path.length > 0
+			? [error.path]
+			: []
+	);
+	const evidencePaths = new Set(
+		snapshot.records.flatMap((record) =>
+			record.path === undefined || record.tombstone
+				? []
+				: [responsePathKey(record.path)]
+		)
+	);
+	for (const artifactRoot of artifact.roots) {
+		const root = runtimeRoot(artifactRoot);
+		const rootPath: readonly (string | number)[] = [root.responseKey];
+		const rootKey = replicaIndexKey({
+			field: root.field,
+			arguments: resolveArguments(
+				root.arguments,
+				variables,
+				root.coverage
+			)
+		});
+		keys.add(rootKey);
+		if (
+			resultPathBlocked(errorPaths, rootPath) ||
+			!Object.prototype.hasOwnProperty.call(
+				envelope.data,
+				root.responseKey
+			)
+		) {
+			continue;
+		}
+		const value = envelope.data[root.responseKey];
+		if (
+			value === null &&
+			resultPathHasErrors(errorPaths, rootPath)
+		) {
+			continue;
+		}
+		collectResultBranchIndexKeys(
+			artifact.id,
+			root,
+			value,
+			rootPath,
+			rootKey,
+			variables,
+			errorPaths,
+			evidencePaths,
+			keys
+		);
+	}
+	return keys;
+}
+
+export function collectResultBranchIndexKeys(
+	artifactId: string,
+	selection: RuntimeRootSelection | RuntimeObjectBranch,
+	value: unknown,
+	path: readonly (string | number)[],
+	enclosingIndexKey: string,
+	variables: GraphqlVariables,
+	errorPaths: readonly (readonly (string | number)[])[],
+	evidencePaths: ReadonlySet<string>,
+	keys: Set<string>
+): void {
+	if (value === null || value === undefined) return;
+	if (selection.cardinality === 'one') {
+		collectResultObjectIndexKeys(
+			artifactId,
+			selection.selection,
+			value,
+			path,
+			enclosingIndexKey,
+			undefined,
+			variables,
+			errorPaths,
+			evidencePaths,
+			keys
+		);
+		return;
+	}
+	if (!Array.isArray(value)) return;
+	for (const [ordinal, entry] of value.entries()) {
+		if (entry === null || entry === undefined) continue;
+		collectResultObjectIndexKeys(
+			artifactId,
+			selection.selection,
+			entry,
+			[...path, ordinal],
+			enclosingIndexKey,
+			ordinal,
+			variables,
+			errorPaths,
+			evidencePaths,
+			keys
+		);
+	}
+}
+
+export function collectResultObjectIndexKeys(
+	artifactId: string,
+	selection: RuntimeObjectSelection,
+	value: unknown,
+	path: readonly (string | number)[],
+	enclosingIndexKey: string,
+	ordinal: number | undefined,
+	variables: GraphqlVariables,
+	errorPaths: readonly (readonly (string | number)[])[],
+	evidencePaths: ReadonlySet<string>,
+	keys: Set<string>
+): void {
+	if (resultPathBlocked(errorPaths, path) || !isReplicaResultObject(value)) {
+		return;
+	}
+	const fields = new Map<string, CacheValue>();
+	for (const member of selection.members) {
+		if (member.kind !== 'scalar') continue;
+		const fieldPath = [...path, member.responseKey];
+		if (
+			resultPathBlocked(errorPaths, fieldPath) ||
+			!Object.prototype.hasOwnProperty.call(value, member.responseKey)
+		) {
+			continue;
+		}
+		const rawValue = value[member.responseKey];
+		if (rawValue === null && !member.nullable) continue;
+		if (!fields.has(member.field)) {
+			fields.set(
+				member.field,
+				cloneJsonValue(rawValue) as CacheValue
+			);
+		}
+	}
+	let parentKey: string;
+	if (
+		selection.storage.kind === 'normalized' &&
+		evidencePaths.has(responsePathKey(path.map(String)))
+	) {
+		const identity = selection.storage.identityFields.flatMap((field) => {
+			const value = fields.get(field);
+			return value === undefined || value === null ? [] : [value];
+		});
+		if (identity.length !== selection.storage.identityFields.length) return;
+		parentKey = replicaRecordKey(
+			{
+				id: selection.storage.model,
+				identityFields: selection.storage.identityFields
+			},
+			identity
+		);
+	} else {
+		parentKey = embeddedRecordKey(
+			artifactId,
+			enclosingIndexKey,
+			ordinal
+		);
+	}
+	for (const member of selection.members) {
+		if (member.kind !== 'branch') continue;
+		const branchPath = [...path, member.responseKey];
+		const branchKey = replicaIndexKey({
+			parent: parentKey,
+			field: member.field,
+			arguments: resolveArguments(
+				member.arguments,
+				variables,
+				member.coverage
+			)
+		});
+		keys.add(branchKey);
+		if (
+			resultPathBlocked(errorPaths, branchPath) ||
+			!Object.prototype.hasOwnProperty.call(value, member.responseKey)
+		) {
+			continue;
+		}
+		const branchValue = value[member.responseKey];
+		if (
+			branchValue === null &&
+			resultPathHasErrors(errorPaths, branchPath)
+		) {
+			continue;
+		}
+		collectResultBranchIndexKeys(
+			artifactId,
+			member,
+			branchValue,
+			branchPath,
+			branchKey,
+			variables,
+			errorPaths,
+			evidencePaths,
+			keys
+		);
+	}
+}
+
+export function resultPathBlocked(
+	errorPaths: readonly (readonly (string | number)[])[],
+	path: readonly (string | number)[]
+): boolean {
+	return errorPaths.some((errorPath) => resultPathPrefix(errorPath, path));
+}
+
+export function resultPathHasErrors(
+	errorPaths: readonly (readonly (string | number)[])[],
+	path: readonly (string | number)[]
+): boolean {
+	return errorPaths.some(
+		(errorPath) =>
+			resultPathPrefix(path, errorPath) ||
+			resultPathPrefix(errorPath, path)
+	);
+}
+
+export function resultPathPrefix(
+	prefix: readonly (string | number)[],
+	value: readonly (string | number)[]
+): boolean {
+	return (
+		prefix.length <= value.length &&
+		prefix.every((entry, index) => entry === value[index])
+	);
+}
+
+export function isReplicaResultObject(
+	value: unknown
+): value is Readonly<Record<string, unknown>> {
+	return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function indexMaintenanceSnapshot(
+	confirmed: CacheEngineSnapshot
+): ReplicaIndexMaintenanceSnapshot {
+	return Object.freeze({
+		records: Object.freeze(
+			confirmed.records.flatMap((record) => {
+				if (record.tombstoneRevision !== undefined) return [];
+				const model = modelFromRecordKey(record.key);
+				if (model === undefined) return [];
+				return [
+					Object.freeze({
+						key: record.key,
+						model,
+						fields: Object.freeze(
+							Object.fromEntries(
+								Object.entries(record.fields).map(([name, field]) => [
+									name,
+									field.value
+								])
+							)
+						)
+					})
+				];
+			})
+		),
+		indexes: Object.freeze(
+			confirmed.indexes.flatMap((index) => {
+				if (index.deleted || index.metadata === undefined) return [];
+				return [
+					Object.freeze({
+						key: index.key,
+						records: index.records,
+						complete: index.complete,
+						metadata: index.metadata
+					})
+				];
+			})
+		)
+	});
+}
+
+export function indexSemanticLayer(
+	layer: OptimisticLayerView
+): ReplicaIndexSemanticLayer {
+	const context = layer.context;
+	if (
+		context === null ||
+		Array.isArray(context) ||
+		typeof context !== 'object'
+	) {
+		throw new TypeError(
+			`optimistic layer ${layer.id} has invalid index-maintenance context`
+		);
+	}
+	const record = context as Readonly<Record<string, CacheValue>>;
+	if (record.id !== layer.id || !Array.isArray(record.changes)) {
+		throw new TypeError(
+			`optimistic layer ${layer.id} has invalid index-maintenance context`
+		);
+	}
+	return Object.freeze({
+		id: layer.id,
+		changes: record.changes as unknown as readonly ReplicaIndexSemanticChange[]
+	});
+}
+
+export function baseWriter(writer: BaseCacheWriter): ReplicaBaseWriter {
+	return Object.freeze({
+		writeRecord(
+			model: ReplicaModelArtifact,
+			identity: ReplicaIdentity,
+			revision: ReplicaRevision,
+			patch: ReplicaRecordPatch & { readonly incarnation?: ReplicaRevision }
+		): boolean {
+			return writer.writeRecord({
+				key: replicaRecordKey(model, identity),
+				revision,
+				...patch
+			});
+		},
+		tombstoneRecord(
+			model: ReplicaModelArtifact,
+			identity: ReplicaIdentity,
+			revision: ReplicaRevision
+		): boolean {
+			return writer.tombstoneRecord(replicaRecordKey(model, identity), revision);
+		},
+		writeIndex(
+			target: ReplicaIndexTarget,
+			records: readonly string[],
+			revision: ReplicaRevision
+		): boolean {
+			return writer.writeIndex({
+				key: indexKeyFromTarget(target),
+				revision,
+				records,
+				complete: target.complete ?? false,
+				metadata: metadataFromTarget(target)
+			});
+		},
+		deleteIndex(target: ReplicaIndexTarget, revision: ReplicaRevision): boolean {
+			return writer.deleteIndex(indexKeyFromTarget(target), revision);
+		}
+	});
+}
+
+export function metadataFromTarget(target: ReplicaIndexTarget): CacheIndexMetadata {
+	const dependencies = [...new Set(target.dependencies ?? [])].sort();
+	return Object.freeze({
+		...(target.parent === undefined ? {} : { parent: target.parent }),
+		field: target.field,
+		arguments: target.arguments ?? Object.freeze({}),
+		coverage: target.coverage ?? ({ kind: 'unknown' } as CacheIndexCoverage),
+		dependencies: Object.freeze(dependencies),
+		...(target.staleReason === undefined ? {} : { staleReason: target.staleReason }),
+		...(target.nullValue === undefined ? {} : { nullValue: target.nullValue })
+	});
+}
+
+export function indexKeyFromTarget(target: ReplicaIndexTarget): string {
+	return replicaIndexKey({
+		...(target.parent === undefined ? {} : { parent: target.parent }),
+		field: target.field,
+		arguments: target.arguments ?? {}
+	});
+}
+
+export function replicaClientRequestExtensions<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	artifact: ReplicaOperationArtifact<TData, TVariables>
+): { readonly extensions?: Readonly<Record<string, unknown>> } {
+	validatedArtifactBinding(artifact);
+	const protocol = artifact.protocol;
+	const surface =
+		protocol.surface.kind === 'role'
+			? Object.freeze({
+					kind: 'role' as const,
+					name: protocol.surface.name
+				})
+			: Object.freeze({
+					kind: 'application' as const,
+					name: protocol.surface.name,
+					roles: Object.freeze([...protocol.surface.roles])
+				});
+	return Object.freeze({
+		extensions: Object.freeze({
+			distributed: Object.freeze({
+				client: Object.freeze({
+					surface,
+					schemaHash: protocol.schemaHash
+				})
+			})
+		})
+	});
+}
+
+export function validatedCommandAuthorityContract(
+	value: ReplicaCommandSurfaceContract
+): RegisteredCommandAuthorityContract {
+	if (
+		value === null ||
+		typeof value !== 'object' ||
+		value.protocolVersion !== 1 ||
+		typeof value.schemaHash !== 'string' ||
+		!SHA256.test(value.schemaHash) ||
+		typeof value.protocolHash !== 'string' ||
+		!SHA256.test(value.protocolHash) ||
+		!Array.isArray(value.trustedPresets)
+	) {
+		throw new TypeError('replica command authority contract is invalid');
+	}
+	const surfaceIdentity = validatedSurfaceIdentity(value.surface);
+	const names = new Set<string>();
+	const trustedPresets = Object.freeze(
+		value.trustedPresets
+			.map((descriptor) => {
+				if (
+					descriptor === null ||
+					typeof descriptor !== 'object' ||
+					typeof descriptor.name !== 'string' ||
+					descriptor.name.length === 0 ||
+					descriptor.name.length > 128 ||
+					descriptor.name.trim() !== descriptor.name ||
+					/[\u0000-\u001f\u007f-\u009f]/.test(descriptor.name) ||
+					names.has(descriptor.name) ||
+					!isDistributedTrustedPresetCodec(descriptor.codec)
+				) {
+					throw new TypeError(
+						'replica command trusted preset contract is invalid'
+					);
+				}
+				names.add(descriptor.name);
+				return Object.freeze({
+					name: descriptor.name,
+					codec: descriptor.codec
+				});
+			})
+			.sort(({ name: left }, { name: right }) =>
+				left < right ? -1 : left > right ? 1 : 0
+			)
+	);
+	const fingerprint = JSON.stringify([
+		2,
+		value.schemaHash,
+		value.protocolHash,
+		surfaceIdentity,
+		trustedPresets
+	]);
+	return Object.freeze({
+		schemaHash: value.schemaHash,
+		protocolHash: value.protocolHash,
+		surfaceIdentity,
+		trustedPresets,
+		fingerprint
+	});
+}
+
+export function canonicalTrustedPresets(
+	value: readonly DistributedTrustedPreset[]
+): readonly DistributedTrustedPreset[] {
+	return Object.freeze(
+		[...value].sort(({ name: left }, { name: right }) =>
+			left < right ? -1 : left > right ? 1 : 0
+		)
+	);
+}
+
+export function trustedPresetInventoryFingerprint(
+	value: readonly DistributedTrustedPreset[]
+): string {
+	return JSON.stringify(canonicalTrustedPresets(value));
+}
+
+export function trustedPresetDescriptorFingerprint(
+	value: readonly ReplicaTrustedPresetDescriptor[]
+): string {
+	return JSON.stringify(value);
+}
+
+export function operationKey<TData, TVariables extends GraphqlVariables>(
+	artifact: ReplicaOperationArtifact<TData, TVariables>,
+	variables: TVariables
+): string {
+	const binding = validatedArtifactBinding(artifact);
+	const artifactIdentity = JSON.stringify([
+		binding.version,
+		binding.schemaHash,
+		binding.surfaceIdentity,
+		binding.operation,
+		artifact.id
+	]);
+	return `protocol:${artifactIdentity}:${canonicalVariables(variables)}`;
+}
+
+export function validatedSurfaceIdentity(
+	value: NonNullable<ReplicaOperationArtifact['protocol']>['surface']
+): string {
+	if (
+		value === null ||
+		typeof value !== 'object' ||
+		typeof value.name !== 'string' ||
+		value.name.length === 0
+	) {
+		throw new TypeError('replica artifact client surface is invalid');
+	}
+	if (value.kind === 'role') {
+		return JSON.stringify(['role', value.name]);
+	}
+	if (
+		value.kind !== 'application' ||
+		!Array.isArray(value.roles) ||
+		value.roles.length === 0 ||
+		value.roles.some(
+			(role) => typeof role !== 'string' || role.length === 0
+		) ||
+		new Set(value.roles).size !== value.roles.length ||
+		[...value.roles].sort().some((role, index) => role !== value.roles[index])
+	) {
+		throw new TypeError('replica artifact client surface is invalid');
+	}
+	return JSON.stringify(['application', value.name, value.roles]);
+}
+
+export function snapshotFrom<TData>(
+	materialized: MaterializedReplicaResult<TData>,
+	state: QueryState
+): ReplicaSnapshot<TData> {
+	const status: ReplicaStatus =
+		state.errors.length > 0
+			? 'error'
+			: materialized.stale
+				? 'stale'
+				: materialized.complete
+					? 'ready'
+					: 'loading';
+	const snapshot = Object.freeze({
+		data: materialized.data,
+		status,
+		fetching: state.fetching,
+		stale: materialized.stale,
+		complete: materialized.complete,
+		errors: state.errors,
+		live: state.live
+	});
+	// `materializeReplicaOperation` only reports complete after every generated
+	// selection is present; that runtime invariant is what promotes sparse data
+	// to the generated result type in ReplicaSnapshot's discriminated union.
+	return snapshot as ReplicaSnapshot<TData>;
+}
+
+export function snapshotEqual<TData>(
+	left: ReplicaSnapshot<TData>,
+	right: ReplicaSnapshot<TData>
+): boolean {
+	return (
+		left.data === right.data &&
+		left.status === right.status &&
+		left.fetching === right.fetching &&
+		left.stale === right.stale &&
+		left.complete === right.complete &&
+		left.errors === right.errors &&
+		left.live === right.live
+	);
+}
+
+export function freezeErrors(errors: readonly GqlError[]): readonly GqlError[] {
+	if (errors.length === 0) return EMPTY_ERRORS;
+	return Object.freeze(
+		errors.map((error) =>
+			(Object.freeze({
+				message: error.message,
+				...(error.locations === undefined
+					? {}
+					: {
+							locations: Object.freeze(
+								error.locations.map((location) => Object.freeze({ ...location }))
+							)
+						}),
+				...(error.path === undefined ? {} : { path: Object.freeze([...error.path]) }),
+				...(error.extensions === undefined
+					? {}
+					: {
+							extensions: cloneJsonValue(error.extensions) as GqlError['extensions']
+						})
+			}) as GqlError)
+		)
+	);
+}
+
+export function stableErrors(
+	current: readonly GqlError[],
+	next: readonly GqlError[]
+): readonly GqlError[] {
+	if (next.length === 0) return EMPTY_ERRORS;
+	return deepEqual(current, next) ? current : freezeErrors(next);
+}
+
+export function graphqlError(error: unknown): GqlError {
+	return Object.freeze({
+		message: error instanceof Error ? error.message : String(error),
+		extensions: Object.freeze({ code: 'REPLICA_TRANSPORT' })
+	});
+}
+
+export function assertWriteSource(source: ReplicaWriteSource): void {
+	if (!['network', 'live', 'ssr', 'restore', 'projected'].includes(source)) {
+		throw new TypeError(`unsupported replica write source: ${source}`);
+	}
+}
+
+export function protocolOperationSource(
+	source: ReplicaWriteSource
+): OperationProtocolSource {
+	return source === 'live' ? 'live' : 'query';
+}
+
+export { reportSafely };
+export const reportUnhandledObserverError = reportUnhandledError;
diff --git a/js/src/replica/distributed-replica/hydration.ts b/js/src/replica/distributed-replica/hydration.ts
new file mode 100644
index 00000000..23f10a2d
--- /dev/null
+++ b/js/src/replica/distributed-replica/hydration.ts
@@ -0,0 +1,579 @@
+import type { CacheEngineSnapshot } from '../../internal/cache-engine.js';
+import {
+	compareDistributedDecimal,
+	parseDistributedTrustedPresetInventory,
+	type DistributedDecimalString,
+	type DistributedOpaqueString
+} from '../../protocol.js';
+
+import { modelFromRecordKey } from './clocks.js';
+
+import { canonicalTrustedPresets } from './helpers.js';
+import type {
+	AnonymousRecordProtocolClock,
+	IndexProtocolClock,
+	OperationProtocolGroup,
+	OperationProtocolSource,
+	OperationProtocolState,
+	ParsedReplicaHydration,
+	ProtocolGeneration,
+	RecordProtocolClock,
+	SerializedOperationProtocolGroup,
+	SerializedOperationProtocolState
+} from './types.js';
+
+export function serializeOperationProtocolGroup(
+	key: string,
+	group: OperationProtocolGroup,
+	generation: number
+): SerializedOperationProtocolGroup {
+	return Object.freeze({
+		key,
+		...(group.query === undefined
+			? {}
+			: { query: serializeOperationProtocolState(group.query) }),
+		...(group.live === undefined
+			? {}
+			: { live: serializeOperationProtocolState(group.live) }),
+		...(group.active === undefined ? {} : { active: group.active }),
+		generation
+	});
+}
+
+export function serializeOperationProtocolState(
+	state: OperationProtocolState
+): SerializedOperationProtocolState {
+	return Object.freeze({
+		operation: state.operation,
+		...(state.snapshotScope === undefined
+			? {}
+			: { snapshotScope: state.snapshotScope }),
+		indexClocks: Object.freeze(
+			[...state.indexClocks]
+				.sort(([left], [right]) => left.localeCompare(right))
+				.map(([projection, clock]) =>
+					Object.freeze([
+						projection,
+						Object.freeze({
+							scopeToken: clock.scopeToken,
+							position: clock.position
+						})
+					] as const)
+				)
+		),
+		...(state.indexRevision === undefined
+			? {}
+			: { indexRevision: state.indexRevision }),
+		indexKeys: Object.freeze([...state.indexKeys].sort()),
+		pathRecords: Object.freeze(
+			[...state.pathRecords]
+				.sort(([left], [right]) => left.localeCompare(right))
+				.map(([path, key]) => Object.freeze([path, key] as const))
+		),
+		cursors: Object.freeze(
+			state.cursors.map((cursor) =>
+				Object.freeze({
+					projection: cursor.projection,
+					position: cursor.position,
+					token: cursor.token
+				})
+			)
+		)
+	});
+}
+
+export function parseAuthoritativeScope(
+	value: unknown
+): ProtocolGeneration | undefined {
+	try {
+		const scope = hydrationRecord(
+			value,
+			'authoritativeScope',
+			['protocolVersion', 'schemaHash', 'cacheScope']
+		);
+		if (scope.protocolVersion !== 1) {
+			hydrationInvalid('authoritativeScope.protocolVersion');
+		}
+		return Object.freeze({
+			protocolVersion: 1,
+			schemaHash: hydrationString(
+				scope.schemaHash,
+				'authoritativeScope.schemaHash'
+			),
+			cacheScope: hydrationOpaque(
+				scope.cacheScope,
+				'authoritativeScope.cacheScope'
+			)
+		});
+	} catch {
+		return undefined;
+	}
+}
+
+export function hydrationMetadataConsistent(
+	parsed: ParsedReplicaHydration
+): boolean {
+	try {
+		const recordByKey = new Map(
+			parsed.cache.records.map((record) => [record.key, record])
+		);
+		for (const record of parsed.cache.records) {
+			if (modelFromRecordKey(record.key) === undefined) continue;
+			const clock = parsed.recordClocks.get(record.key);
+			if (
+				clock === undefined ||
+				record.incarnation === undefined ||
+				clock.incarnation !== record.incarnation ||
+				clock.revision !== record.revision
+			) {
+				return false;
+			}
+			if (clock.tombstone) {
+				if (record.tombstoneRevision !== clock.revision) return false;
+			} else if (record.tombstoneRevision !== undefined) {
+				return false;
+			}
+		}
+		for (const [recordKey, clock] of parsed.recordClocks) {
+			const record = recordByKey.get(recordKey);
+			if (
+				record?.tombstoneRevision !== undefined &&
+				(
+					!clock.tombstone ||
+					record.tombstoneRevision !== clock.revision
+				)
+			) {
+				return false;
+			}
+		}
+
+		const revisionsByIndex = new Map<string, Set<string>>();
+		for (const group of parsed.operationProtocols.values()) {
+			for (const state of [group.query, group.live]) {
+				if (state === undefined) continue;
+				for (const recordKey of state.pathRecords.values()) {
+					if (
+						modelFromRecordKey(recordKey) !== undefined &&
+						!parsed.recordClocks.has(recordKey)
+					) {
+						return false;
+					}
+				}
+				if (state.indexRevision === undefined) {
+					if (state.indexKeys.size > 0) return false;
+					continue;
+				}
+				for (const indexKey of state.indexKeys) {
+					let revisions = revisionsByIndex.get(indexKey);
+					if (revisions === undefined) {
+						revisions = new Set();
+						revisionsByIndex.set(indexKey, revisions);
+					}
+					revisions.add(state.indexRevision);
+				}
+			}
+		}
+		const nextIndexRevision =
+			parsed.nextIndexRevision as DistributedDecimalString;
+		for (const index of parsed.cache.indexes) {
+			const revision = hydrationDecimal(
+				index.revision,
+				'state.payload.cache.indexes.revision'
+			);
+			if (
+				compareDistributedDecimal(revision, nextIndexRevision) > 0 ||
+				!revisionsByIndex.get(index.key)?.has(index.revision)
+			) {
+				return false;
+			}
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function parseReplicaHydration(
+	value: unknown
+): ParsedReplicaHydration | undefined {
+	try {
+		const state = hydrationRecord(
+			value,
+			'state',
+			['version', 'scope', 'payload']
+		);
+		if (state.version !== 1) hydrationInvalid('state.version');
+		const scopeValue = hydrationRecord(
+			state.scope,
+			'state.scope',
+			['protocolVersion', 'schemaHash', 'cacheScope']
+		);
+		if (scopeValue.protocolVersion !== 1) {
+			hydrationInvalid('state.scope.protocolVersion');
+		}
+		const scope: ProtocolGeneration = Object.freeze({
+			protocolVersion: 1,
+			schemaHash: hydrationString(
+				scopeValue.schemaHash,
+				'state.scope.schemaHash'
+			),
+			cacheScope: hydrationOpaque(
+				scopeValue.cacheScope,
+				'state.scope.cacheScope'
+			)
+		});
+		const payload = hydrationRecord(
+			state.payload,
+			'state.payload',
+			[
+				'cache',
+					'operations',
+					'recordClocks',
+					'anonymousRecordClocks',
+					'trustedPresets',
+					'nextIndexRevision'
+				]
+			);
+		const cache = payload.cache as CacheEngineSnapshot;
+		if (!isHydrationRecord(cache)) hydrationInvalid('state.payload.cache');
+		const operationsValue = hydrationArray(
+			payload.operations,
+			'state.payload.operations'
+		);
+		const operationProtocols = new Map<string, OperationProtocolGroup>();
+		const operationGenerations = new Map<string, number>();
+		for (const [index, entry] of operationsValue.entries()) {
+			const path = `state.payload.operations[${index}]`;
+			const raw = hydrationRecord(
+				entry,
+				path,
+				['key', 'query', 'live', 'active', 'generation'],
+				['key', 'generation']
+			);
+			const key = hydrationString(raw.key, `${path}.key`);
+			if (!key.startsWith('protocol:') || operationProtocols.has(key)) {
+				hydrationInvalid(`${path}.key`);
+			}
+			const query =
+				raw.query === undefined
+					? undefined
+					: parseOperationProtocolState(raw.query, `${path}.query`);
+			const live =
+				raw.live === undefined
+					? undefined
+					: parseOperationProtocolState(raw.live, `${path}.live`);
+			if (query === undefined && live === undefined) hydrationInvalid(path);
+			const active =
+				raw.active === undefined
+					? undefined
+					: hydrationOperationSource(raw.active, `${path}.active`);
+			if (
+				(active === 'query' && query === undefined) ||
+				(active === 'live' && live === undefined)
+			) {
+				hydrationInvalid(`${path}.active`);
+			}
+			operationProtocols.set(key, {
+				...(query === undefined ? {} : { query }),
+				...(live === undefined ? {} : { live }),
+				...(active === undefined ? {} : { active })
+			});
+			operationGenerations.set(
+				key,
+				hydrationGeneration(raw.generation, `${path}.generation`)
+			);
+		}
+
+		const recordClocks = new Map<string, RecordProtocolClock>();
+		const recordKeysByScope = new Map<DistributedOpaqueString, string>();
+		for (const [index, entry] of hydrationArray(
+			payload.recordClocks,
+			'state.payload.recordClocks'
+		).entries()) {
+			const path = `state.payload.recordClocks[${index}]`;
+			const pair = hydrationPair(entry, path);
+			const key = hydrationString(pair[0], `${path}[0]`);
+			if (recordClocks.has(key)) hydrationInvalid(`${path}[0]`);
+			const clock = parseRecordClock(pair[1], `${path}[1]`);
+			if (recordKeysByScope.has(clock.scopeToken)) {
+				hydrationInvalid(`${path}[1].scopeToken`);
+			}
+			recordClocks.set(key, clock);
+			recordKeysByScope.set(clock.scopeToken, key);
+		}
+
+		const anonymousRecordClocks = new Map<
+			DistributedOpaqueString,
+			AnonymousRecordProtocolClock
+		>();
+		for (const [index, entry] of hydrationArray(
+			payload.anonymousRecordClocks,
+			'state.payload.anonymousRecordClocks'
+		).entries()) {
+			const path = `state.payload.anonymousRecordClocks[${index}]`;
+			const pair = hydrationPair(entry, path);
+			const scopeToken = hydrationOpaque(pair[0], `${path}[0]`);
+			if (
+				anonymousRecordClocks.has(scopeToken) ||
+				recordKeysByScope.has(scopeToken)
+			) {
+				hydrationInvalid(`${path}[0]`);
+			}
+			const raw = hydrationRecord(
+				pair[1],
+				`${path}[1]`,
+				['model', 'clock']
+			);
+			const clock = parseRecordClock(raw.clock, `${path}[1].clock`);
+			if (clock.scopeToken !== scopeToken) {
+				hydrationInvalid(`${path}[1].clock.scopeToken`);
+			}
+			anonymousRecordClocks.set(
+				scopeToken,
+				Object.freeze({
+					model: hydrationString(raw.model, `${path}[1].model`),
+					clock
+					})
+				);
+			}
+			const trustedPresets = canonicalTrustedPresets(
+				parseDistributedTrustedPresetInventory(
+					payload.trustedPresets,
+					'state.payload.trustedPresets'
+				)
+			);
+			const nextIndexRevision = hydrationDecimal(
+				payload.nextIndexRevision,
+			'state.payload.nextIndexRevision'
+		);
+		for (const group of operationProtocols.values()) {
+			for (const operation of [group.query, group.live]) {
+				if (
+					operation?.indexRevision !== undefined &&
+					compareDistributedDecimal(
+						operation.indexRevision as DistributedDecimalString,
+						nextIndexRevision
+					) > 0
+				) {
+					hydrationInvalid('state.payload.nextIndexRevision');
+				}
+			}
+		}
+		return {
+			scope,
+			cache,
+			operationProtocols,
+			operationGenerations,
+				recordClocks,
+				recordKeysByScope,
+				anonymousRecordClocks,
+				trustedPresets,
+				nextIndexRevision
+			};
+	} catch {
+		return undefined;
+	}
+}
+
+export function parseOperationProtocolState(
+	value: unknown,
+	path: string
+): OperationProtocolState {
+	const raw = hydrationRecord(
+		value,
+		path,
+		[
+			'operation',
+			'snapshotScope',
+			'indexClocks',
+			'indexRevision',
+			'indexKeys',
+			'pathRecords',
+			'cursors'
+		],
+		['operation', 'indexClocks', 'indexKeys', 'pathRecords', 'cursors']
+	);
+	const indexClocks = new Map<string, IndexProtocolClock>();
+	for (const [index, entry] of hydrationArray(
+		raw.indexClocks,
+		`${path}.indexClocks`
+	).entries()) {
+		const entryPath = `${path}.indexClocks[${index}]`;
+		const pair = hydrationPair(entry, entryPath);
+		const projection = hydrationString(pair[0], `${entryPath}[0]`);
+		if (indexClocks.has(projection)) hydrationInvalid(`${entryPath}[0]`);
+		const clock = hydrationRecord(
+			pair[1],
+			`${entryPath}[1]`,
+			['scopeToken', 'position']
+		);
+		indexClocks.set(
+			projection,
+			Object.freeze({
+					scopeToken: hydrationOpaque(
+						clock.scopeToken,
+						`${entryPath}[1].scopeToken`
+					),
+				position: hydrationDecimal(
+					clock.position,
+					`${entryPath}[1].position`
+				)
+			})
+		);
+	}
+	const indexKeys = new Set<string>();
+	for (const [index, entry] of hydrationArray(
+		raw.indexKeys,
+		`${path}.indexKeys`
+	).entries()) {
+		const key = hydrationString(entry, `${path}.indexKeys[${index}]`);
+		if (indexKeys.has(key)) hydrationInvalid(`${path}.indexKeys[${index}]`);
+		indexKeys.add(key);
+	}
+	const pathRecords = new Map<string, string>();
+	for (const [index, entry] of hydrationArray(
+		raw.pathRecords,
+		`${path}.pathRecords`
+	).entries()) {
+		const entryPath = `${path}.pathRecords[${index}]`;
+		const pair = hydrationPair(entry, entryPath);
+		const responsePath = hydrationString(pair[0], `${entryPath}[0]`);
+		if (pathRecords.has(responsePath)) hydrationInvalid(`${entryPath}[0]`);
+		pathRecords.set(
+			responsePath,
+			hydrationString(pair[1], `${entryPath}[1]`)
+		);
+	}
+	const cursors = hydrationArray(raw.cursors, `${path}.cursors`).map(
+		(entry, index) => {
+			const entryPath = `${path}.cursors[${index}]`;
+			const cursor = hydrationRecord(
+				entry,
+				entryPath,
+				['projection', 'position', 'token']
+			);
+			return Object.freeze({
+				projection: hydrationString(
+					cursor.projection,
+					`${entryPath}.projection`
+				),
+				position: hydrationDecimal(
+					cursor.position,
+					`${entryPath}.position`
+				),
+				token: hydrationOpaque(cursor.token, `${entryPath}.token`)
+			});
+		}
+	);
+	return {
+		operation: hydrationString(raw.operation, `${path}.operation`),
+		...(raw.snapshotScope === undefined
+			? {}
+			: {
+					snapshotScope: hydrationOpaque(
+						raw.snapshotScope,
+						`${path}.snapshotScope`
+					)
+				}),
+		indexClocks,
+		...(raw.indexRevision === undefined
+			? {}
+			: {
+					indexRevision: hydrationDecimal(
+						raw.indexRevision,
+						`${path}.indexRevision`
+					)
+				}),
+		indexKeys,
+		pathRecords,
+		cursors: Object.freeze(cursors)
+	};
+}
+
+export function parseRecordClock(value: unknown, path: string): RecordProtocolClock {
+	const raw = hydrationRecord(
+		value,
+		path,
+		['scopeToken', 'incarnation', 'revision', 'tombstone']
+	);
+	if (typeof raw.tombstone !== 'boolean') hydrationInvalid(`${path}.tombstone`);
+	return Object.freeze({
+		scopeToken: hydrationOpaque(raw.scopeToken, `${path}.scopeToken`),
+		incarnation: hydrationDecimal(raw.incarnation, `${path}.incarnation`),
+		revision: hydrationDecimal(raw.revision, `${path}.revision`),
+		tombstone: raw.tombstone
+	});
+}
+
+export function hydrationRecord(
+	value: unknown,
+	path: string,
+	allowed: readonly string[],
+	required: readonly string[] = allowed
+): Record<string, unknown> {
+	if (!isHydrationRecord(value)) hydrationInvalid(path);
+	const allowedKeys = new Set(allowed);
+	for (const key of Object.keys(value)) {
+		if (!allowedKeys.has(key)) hydrationInvalid(`${path}.${key}`);
+	}
+	for (const key of required) {
+		if (!Object.prototype.hasOwnProperty.call(value, key)) {
+			hydrationInvalid(`${path}.${key}`);
+		}
+	}
+	return value;
+}
+
+export function isHydrationRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function hydrationArray(value: unknown, path: string): unknown[] {
+	if (!Array.isArray(value)) hydrationInvalid(path);
+	return value;
+}
+
+export function hydrationPair(value: unknown, path: string): readonly [unknown, unknown] {
+	if (!Array.isArray(value) || value.length !== 2) hydrationInvalid(path);
+	return value as unknown as readonly [unknown, unknown];
+}
+
+export function hydrationString(value: unknown, path: string): string {
+	if (typeof value !== 'string' || value.length === 0) hydrationInvalid(path);
+	return value;
+}
+
+export function hydrationOpaque(
+	value: unknown,
+	path: string
+): DistributedOpaqueString {
+	return hydrationString(value, path) as DistributedOpaqueString;
+}
+
+export function hydrationDecimal(
+	value: unknown,
+	path: string
+): DistributedDecimalString {
+	const string = hydrationString(value, path);
+	if (!/^(0|[1-9][0-9]*)$/.test(string)) hydrationInvalid(path);
+	return string as DistributedDecimalString;
+}
+
+export function hydrationGeneration(value: unknown, path: string): number {
+	if (!Number.isSafeInteger(value) || (value as number) < 0) {
+		hydrationInvalid(path);
+	}
+	return value as number;
+}
+
+export function hydrationOperationSource(
+	value: unknown,
+	path: string
+): OperationProtocolSource {
+	if (value !== 'query' && value !== 'live') hydrationInvalid(path);
+	return value;
+}
+
+export function hydrationInvalid(path: string): never {
+	throw new TypeError(`invalid replica hydration state at ${path}`);
+}
diff --git a/js/src/replica/distributed-replica/impl-diagnostics.ts b/js/src/replica/distributed-replica/impl-diagnostics.ts
new file mode 100644
index 00000000..3ad4c94f
--- /dev/null
+++ b/js/src/replica/distributed-replica/impl-diagnostics.ts
@@ -0,0 +1,275 @@
+import type { CacheEngine } from '../../internal/cache-engine.js';
+import type {
+	ReplicaDiagnosticEventInput,
+	ReplicaDiagnosticLayerInput,
+	ReplicaDiagnosticReceiptInput,
+	ReplicaDiagnosticsSink
+} from '../diagnostics.js';
+import type { GraphqlVariables } from '../../types.js';
+import type { ReplicaOperationArtifact, ReplicaValue } from '../types.js';
+import { modelFromRecordKey } from './clocks.js';
+import {
+	diagnosticReceiptCounts,
+	diagnosticReceiptExpectations
+} from './optimistic.js';
+import { reportSafely } from './helpers.js';
+import type {
+	OptimisticReceiptState,
+	ProtocolGeneration
+} from './types.js';
+
+/**
+ * Host for diagnostics sync and event emission.
+ */
+export type DiagnosticsHost = {
+	readonly engine: CacheEngine;
+	readonly diagnostics: ReplicaDiagnosticsSink | undefined;
+	readonly diagnosticLayers: Map<string, ReplicaDiagnosticLayerInput> | undefined;
+	readonly optimisticReceipts: Map<string, OptimisticReceiptState>;
+	readonly reportObserverError: (error: AggregateError) => void;
+	getProtocolGeneration(): ProtocolGeneration | undefined;
+	getProtocolGenerationSequence(): number;
+};
+
+export function syncDiagnostics(host: DiagnosticsHost): void {
+	const diagnostics = host.diagnostics;
+	if (diagnostics === undefined) return;
+	try {
+		const cache = host.engine.extract();
+		const records = cache.records.map((record) => {
+			const model = modelFromRecordKey(record.key);
+			const tombstone = record.tombstoneRevision !== undefined;
+			const values: Record<string, ReplicaValue> = {};
+			if (!tombstone && diagnostics.redactRecordValue !== undefined) {
+				for (const [field, entry] of Object.entries(record.fields)) {
+					const value = diagnostics.redactRecordValue(
+						Object.freeze({
+							recordKey: record.key,
+							...(model === undefined ? {} : { model }),
+							field,
+							kind: 'field' as const
+						}),
+						entry.value as ReplicaValue
+					);
+					if (value !== undefined) values[field] = value;
+				}
+				for (const [field, entry] of Object.entries(record.links)) {
+					const value = diagnostics.redactRecordValue(
+						Object.freeze({
+							recordKey: record.key,
+							...(model === undefined ? {} : { model }),
+							field,
+							kind: 'link' as const
+						}),
+						entry.value as ReplicaValue
+					);
+					if (value !== undefined) values[field] = value;
+				}
+			}
+			return Object.freeze({
+				key: record.key,
+				...(model === undefined ? {} : { model }),
+				revision: record.revision,
+				incarnation: record.incarnation ?? record.revision,
+				tombstone,
+				...(record.tombstoneRevision === undefined
+					? {}
+					: { tombstoneRevision: record.tombstoneRevision }),
+				presentFields: Object.freeze(
+					tombstone ? [] : Object.keys(record.fields).sort()
+				),
+				presentLinks: Object.freeze(
+					tombstone ? [] : Object.keys(record.links).sort()
+				),
+				...(Object.keys(values).length === 0
+					? {}
+					: { values: Object.freeze(values) })
+			});
+		});
+		const indexes = cache.indexes.map((index) =>
+			Object.freeze({
+				key: index.key,
+				revision: index.revision,
+				...(index.staleRevision === undefined
+					? {}
+					: { staleRevision: index.staleRevision }),
+				records: index.records,
+				complete: index.complete,
+				deleted: index.deleted,
+				...(index.metadata === undefined
+					? {}
+					: {
+							field: index.metadata.field,
+							...(index.metadata.parent === undefined
+								? {}
+								: { parent: index.metadata.parent }),
+							argumentNames: Object.freeze(
+								Object.keys(index.metadata.arguments).sort()
+							),
+							...(diagnostics.includeStructuralIdentities
+								? { arguments: index.metadata.arguments }
+								: {}),
+							coverage: index.metadata.coverage,
+							dependencies: index.metadata.dependencies,
+							...(index.metadata.staleReason === undefined
+								? {}
+								: { staleReason: index.metadata.staleReason }),
+							nullValue: index.metadata.nullValue === true
+						})
+			})
+		);
+		const receipts: ReplicaDiagnosticReceiptInput[] = [];
+		for (const layer of host.diagnosticLayers?.values() ?? []) {
+			const receipt = host.optimisticReceipts.get(layer.id);
+			receipts.push(
+				Object.freeze({
+					commandId: layer.id,
+					state:
+						receipt === undefined
+							? ('optimistic' as const)
+							: receipt.expectations.size === 0
+								? ('accepted' as const)
+								: ('accepted_pending_projection' as const),
+					expectations:
+						receipt === undefined
+							? Object.freeze([])
+							: diagnosticReceiptExpectations(receipt)
+				})
+			);
+		}
+		const scope = host.getProtocolGeneration();
+		diagnostics.update(
+			Object.freeze({
+				scope:
+					scope === undefined
+						? Object.freeze({
+								generation: host.getProtocolGenerationSequence(),
+								established: false
+							})
+						: Object.freeze({
+								generation: host.getProtocolGenerationSequence(),
+								established: true,
+								protocolVersion: 1 as const,
+								schemaHash: scope.schemaHash
+							}),
+				records: Object.freeze(records),
+				indexes: Object.freeze(indexes),
+				layers: Object.freeze([
+					...(host.diagnosticLayers?.values() ?? [])
+				]),
+				receipts: Object.freeze(receipts)
+			})
+		);
+	} catch (error) {
+		reportSafely(
+			host.reportObserverError,
+			new AggregateError([error], 'replica diagnostics update failed')
+		);
+	}
+}
+
+export function diagnosticEvent(
+	host: DiagnosticsHost,
+	event: ReplicaDiagnosticEventInput
+): void {
+	if (host.diagnostics === undefined) return;
+	try {
+		host.diagnostics.event(event);
+	} catch (error) {
+		reportSafely(
+			host.reportObserverError,
+			new AggregateError([error], 'replica diagnostics event failed')
+		);
+	}
+}
+
+export function diagnosticOperation<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	host: DiagnosticsHost,
+	artifact: ReplicaOperationArtifact<TData, TVariables>
+): void {
+	if (host.diagnostics === undefined) return;
+	try {
+		host.diagnostics.operation(artifact);
+	} catch (error) {
+		reportSafely(
+			host.reportObserverError,
+			new AggregateError([error], 'replica diagnostic artifact failed')
+		);
+	}
+}
+
+export function diagnosticScopeTransition(
+	host: DiagnosticsHost,
+	previous: ProtocolGeneration | undefined,
+	next: ProtocolGeneration
+): void {
+	if (host.diagnostics === undefined) return;
+	if (
+		previous !== undefined &&
+		previous.cacheScope === next.cacheScope &&
+		previous.schemaHash === next.schemaHash
+	) {
+		return;
+	}
+	diagnosticEvent(
+		host,
+		Object.freeze({
+			kind: 'scope',
+			action: previous === undefined ? 'established' : 'changed',
+			generation: host.getProtocolGenerationSequence(),
+			schemaHash: next.schemaHash
+		})
+	);
+}
+
+export function retireDiagnosticLayer(
+	host: DiagnosticsHost,
+	id: string,
+	action: 'retired' | 'rejected',
+	receiptState: 'projected' | 'rejected',
+	receipt?: OptimisticReceiptState
+): void {
+	const layers = host.diagnosticLayers;
+	const removed = layers?.get(id);
+	if (removed === undefined) return;
+	layers!.delete(id);
+	diagnosticEvent(
+		host,
+		Object.freeze({
+			kind: 'layer',
+			layer: id,
+			action,
+			recordChanges: removed.recordChanges,
+			indexChanges: removed.indexChanges
+		})
+	);
+	const causal = receipt ?? host.optimisticReceipts.get(id);
+	const counts = diagnosticReceiptCounts(causal);
+	diagnosticEvent(
+		host,
+		Object.freeze({
+			kind: 'receipt',
+			command: id,
+			state: receiptState,
+			obligations: counts.obligations,
+			observed: counts.observed
+		})
+	);
+	for (const layer of layers!.values()) {
+		if (layer.sequence <= removed.sequence) continue;
+		diagnosticEvent(
+			host,
+			Object.freeze({
+				kind: 'layer',
+				layer: layer.id,
+				action: 'rebased',
+				recordChanges: layer.recordChanges,
+				indexChanges: layer.indexChanges,
+				reason: `${action}-earlier-layer`
+			})
+		);
+	}
+}
diff --git a/js/src/replica/distributed-replica/impl-fetch-live.ts b/js/src/replica/distributed-replica/impl-fetch-live.ts
new file mode 100644
index 00000000..ff178acb
--- /dev/null
+++ b/js/src/replica/distributed-replica/impl-fetch-live.ts
@@ -0,0 +1,495 @@
+import { CacheRevisionConflictError } from '../../internal/cache-engine.js';
+import type { GraphqlVariables } from '../../types.js';
+import {
+	parseGraphqlResponseExtensions,
+	type DistributedLiveCursor,
+	type DistributedProtocolEnvelope
+} from '../../protocol.js';
+import type { ReplicaDiagnosticEventInput } from '../diagnostics.js';
+import type {
+	ReplicaOperationArtifact,
+	ReplicaResultEnvelope,
+	ReplicaTransport,
+	ReplicaWriteSource
+} from '../types.js';
+import {
+	graphqlError,
+	replicaClientRequestExtensions,
+	stableErrors
+} from './helpers.js';
+import type {
+	LiveEntry,
+	OperationProtocolGroup,
+	ProtocolGeneration,
+	QueryState
+} from './types.js';
+import type { ReplicaWatchState } from './watch.js';
+
+/**
+ * Host accessors for fetch / live subscription orchestration.
+ * Free functions never read private class fields; the class supplies state.
+ */
+export type FetchLiveHost = {
+	readonly transport: ReplicaTransport | undefined;
+	readonly inFlight: Map<string, Promise<void>>;
+	readonly inFlightAborts: Map<string, AbortController>;
+	readonly lives: Map<string, LiveEntry>;
+	readonly watches: Map<
+		string,
+		Set<ReplicaWatchState<unknown, GraphqlVariables>>
+	>;
+	readonly operationProtocols: Map<string, OperationProtocolGroup>;
+	readonly diagnostics: { readonly enabled: boolean };
+	protocolGenerationSequence(): number;
+	projectionGeneration(): number;
+	protocolGeneration(): ProtocolGeneration | undefined;
+	queryState(key: string): QueryState;
+	emitState(key: string, allowFetch: boolean): void;
+	operationGeneration(key: string): number;
+	allocateIndexRevision(): string;
+	writeCanonicalResult<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		stableVariables: TVariables,
+		envelope: ReplicaResultEnvelope<TData>,
+		source: ReplicaWriteSource,
+		requestRevision?: string,
+		responseProjectionGeneration?: number
+	): DistributedProtocolEnvelope;
+	diagnosticEvent(event: ReplicaDiagnosticEventInput): void;
+	resumeCursors(key: string): readonly DistributedLiveCursor[];
+};
+
+export function emitWatchState(host: FetchLiveHost, key: string, allowFetch: boolean): void {
+	for (const watch of host.watches.get(key) ?? []) watch._stateChanged(allowFetch);
+}
+
+export function closeActiveTransports(host: FetchLiveHost): void {
+	for (const controller of host.inFlightAborts.values()) controller.abort();
+	host.inFlightAborts.clear();
+	for (const entry of host.lives.values()) {
+		entry.active = false;
+		try {
+			entry.unsubscribe();
+		} catch {
+			// The generation fence is already closed; transport cleanup is best effort.
+		}
+	}
+	host.lives.clear();
+	host.inFlight.clear();
+}
+
+export function fetchWatch<TData, TVariables extends GraphqlVariables>(
+	host: FetchLiveHost,
+	watch: ReplicaWatchState<TData, TVariables>,
+	force: boolean
+): Promise<void> {
+	if (!host.transport) return Promise.resolve();
+	if (!force && watch.materialized.complete && !watch.materialized.stale) {
+		if (host.diagnostics.enabled) {
+			host.diagnosticEvent(
+				Object.freeze({
+					kind: 'revalidation',
+					operation: watch.artifact.id,
+					action: 'skipped-complete',
+					reason: 'watch'
+				})
+			);
+		}
+		return Promise.resolve();
+	}
+	const existing = host.inFlight.get(watch.key);
+	if (existing) {
+		if (host.diagnostics.enabled) {
+			host.diagnosticEvent(
+				Object.freeze({
+					kind: 'revalidation',
+					operation: watch.artifact.id,
+					action: 'deduplicated',
+					reason: force
+						? ('refresh' as const)
+						: watch.materialized.stale
+							? ('stale' as const)
+							: ('watch' as const)
+				})
+			);
+		}
+		return existing;
+	}
+
+	const state = host.queryState(watch.key);
+	if (host.diagnostics.enabled) {
+		host.diagnosticEvent(
+			Object.freeze({
+				kind: 'revalidation',
+				operation: watch.artifact.id,
+				action: 'requested',
+				reason: force
+					? ('refresh' as const)
+					: watch.materialized.stale
+						? ('stale' as const)
+						: ('watch' as const)
+			})
+		);
+	}
+	state.fetching = true;
+	host.emitState(watch.key, false);
+	const operationGeneration = host.operationGeneration(watch.key);
+	const authorizationGeneration = host.protocolGenerationSequence();
+	const projectionGeneration = host.projectionGeneration();
+	/*
+	 * Reserve local index ordering and the projection-fence generation when
+	 * the request starts, not when it finishes. Distinct operation artifacts
+	 * may share the same semantic index key; a slower earlier request must
+	 * not replace a later-started result merely because its response arrived
+	 * last, nor may it supersede a direct projection installed in between.
+	 */
+	const requestRevision = host.allocateIndexRevision();
+	const controller = new AbortController();
+	const request = Object.freeze({
+		operation: 'query' as const,
+		operationId: watch.artifact.id,
+		document: watch.artifact.document,
+		variables: watch.variables,
+		artifact: watch.artifact,
+		...replicaClientRequestExtensions(watch.artifact),
+		signal: controller.signal
+	});
+	let flight: Promise<void>;
+	flight = Promise.resolve()
+		.then(() => host.transport!.fetch(request))
+		.then((result) => {
+			if (host.protocolGenerationSequence() !== authorizationGeneration) {
+				if (host.diagnostics.enabled) {
+					host.diagnosticEvent(
+						Object.freeze({
+							kind: 'response-fenced',
+							operation: watch.artifact.id,
+							transport: 'http',
+							reason: 'authorization-generation'
+						})
+					);
+				}
+				return;
+			}
+			if (host.inFlight.get(watch.key) !== flight) {
+				if (host.diagnostics.enabled) {
+					host.diagnosticEvent(
+						Object.freeze({
+							kind: 'response-fenced',
+							operation: watch.artifact.id,
+							transport: 'http',
+							reason: 'superseded'
+						})
+					);
+				}
+				return;
+			}
+			if (host.operationGeneration(watch.key) !== operationGeneration) {
+				if (host.diagnostics.enabled) {
+					host.diagnosticEvent(
+						Object.freeze({
+							kind: 'response-fenced',
+							operation: watch.artifact.id,
+							transport: 'http',
+							reason: 'operation-generation'
+						})
+					);
+				}
+				return;
+			}
+			host.writeCanonicalResult(
+				watch.artifact,
+				watch.variables,
+				result,
+				'network',
+				requestRevision,
+				projectionGeneration
+			);
+		})
+		.catch((error: unknown) => {
+			if (host.inFlight.get(watch.key) !== flight) return;
+			if (controller.signal.aborted) return;
+			state.errors = stableErrors(state.errors, [graphqlError(error)]);
+		})
+		.finally(() => {
+			if (host.inFlight.get(watch.key) !== flight) return;
+			host.inFlight.delete(watch.key);
+			host.inFlightAborts.delete(watch.key);
+			state.fetching = false;
+			host.emitState(watch.key, false);
+		});
+	host.inFlight.set(watch.key, flight);
+	host.inFlightAborts.set(watch.key, controller);
+	return flight;
+}
+
+export function retainLive<TData, TVariables extends GraphqlVariables>(
+	host: FetchLiveHost,
+	watch: ReplicaWatchState<TData, TVariables>
+): void {
+	if (!watch.artifact.live || !host.transport?.subscribe) return;
+	const existing = host.lives.get(watch.key);
+	if (existing) {
+		existing.count += 1;
+		return;
+	}
+	const state = host.queryState(watch.key);
+	state.live = 'connecting';
+	const entry: LiveEntry = {
+		count: 1,
+		unsubscribe: () => undefined,
+		active: true,
+		protocolGeneration: host.protocolGenerationSequence()
+	};
+	host.lives.set(watch.key, entry);
+	const resume = host.resumeCursors(watch.key);
+	try {
+		const unsubscribe = host.transport.subscribe(
+			Object.freeze({
+				operation: 'live' as const,
+				operationId: watch.artifact.live.id,
+				document: watch.artifact.live.document,
+				variables: watch.variables,
+				artifact: watch.artifact,
+				...replicaClientRequestExtensions(watch.artifact),
+				...(resume === undefined || resume.length === 0
+					? {}
+					: { resume })
+			}),
+			{
+				next: (result) => {
+					// A live frame begins at this synchronous ingress boundary.
+					const projectionGeneration = host.projectionGeneration();
+					if (
+						entry.protocolGeneration !== host.protocolGenerationSequence()
+					) {
+						if (host.diagnostics.enabled) {
+							host.diagnosticEvent(
+								Object.freeze({
+									kind: 'response-fenced',
+									operation: watch.artifact.live!.id,
+									transport: 'live',
+									reason: 'authorization-generation'
+								})
+							);
+						}
+						return;
+					}
+					if (
+						entry.operationGeneration !== undefined &&
+						entry.operationGeneration !==
+							host.operationGeneration(watch.key)
+					) {
+						if (host.diagnostics.enabled) {
+							host.diagnosticEvent(
+								Object.freeze({
+									kind: 'response-fenced',
+									operation: watch.artifact.live!.id,
+									transport: 'live',
+									reason: 'operation-generation'
+								})
+							);
+						}
+						return;
+					}
+					if (
+						!entry.active ||
+						host.lives.get(watch.key) !== entry
+					) {
+						if (host.diagnostics.enabled) {
+							host.diagnosticEvent(
+								Object.freeze({
+									kind: 'response-fenced',
+									operation: watch.artifact.live!.id,
+									transport: 'live',
+									reason: 'superseded'
+								})
+							);
+						}
+						return;
+					}
+					let unsupportedLive = false;
+					try {
+						unsupportedLive =
+							parseGraphqlResponseExtensions(result.extensions)
+								?.distributed?.live?.supported === false;
+						if (unsupportedLive) state.live = 'off';
+						const distributed = host.writeCanonicalResult(
+							watch.artifact,
+							watch.variables,
+							result,
+							'live',
+							undefined,
+							projectionGeneration
+						);
+						if (distributed.live?.supported === false) {
+							fallbackFromLive(host, watch, entry);
+							return;
+						}
+						state.live = 'active';
+						entry.operationGeneration =
+							host.operationGeneration(watch.key);
+					} catch (error) {
+						if (
+							unsupportedLive &&
+							error instanceof CacheRevisionConflictError
+						) {
+							/*
+							 * Revision zero is shared by provisional fallbacks.
+							 * Another operation may already have filled the same
+							 * semantic index differently; HTTP remains authoritative.
+							 */
+							fallbackFromLive(host, watch, entry);
+							return;
+						}
+						state.live = 'error';
+						state.errors = stableErrors(state.errors, [graphqlError(error)]);
+						host.emitState(watch.key, false);
+					}
+				},
+				error: (error) => {
+					if (!entry.active || host.lives.get(watch.key) !== entry) return;
+					entry.active = false;
+					host.lives.delete(watch.key);
+					const unsub = entry.unsubscribe;
+					entry.unsubscribe = () => undefined;
+					try {
+						unsub();
+					} catch {
+						// The terminal stream is fenced; cleanup is best effort.
+					}
+					state.live = 'error';
+					state.errors = stableErrors(state.errors, [graphqlError(error)]);
+					host.emitState(watch.key, false);
+				},
+				complete: () => {
+					if (!entry.active || host.lives.get(watch.key) !== entry) return;
+					fallbackFromLive(host, watch, entry);
+				}
+			}
+		);
+		entry.unsubscribe = unsubscribe;
+		if (!entry.active || host.lives.get(watch.key) !== entry) {
+			entry.unsubscribe = () => undefined;
+			try {
+				unsubscribe();
+			} catch {
+				// A closed/superseded subscription is already fenced.
+			}
+			return;
+		}
+		state.live = 'active';
+	} catch (error) {
+		entry.active = false;
+		host.lives.delete(watch.key);
+		state.live = 'error';
+		state.errors = stableErrors(state.errors, [graphqlError(error)]);
+	}
+	host.emitState(watch.key, false);
+}
+
+export function fallbackFromLive<TData, TVariables extends GraphqlVariables>(
+	host: FetchLiveHost,
+	watch: ReplicaWatchState<TData, TVariables>,
+	entry: LiveEntry
+): void {
+	if (host.lives.get(watch.key) !== entry) {
+		void fetchWatch(host, watch, true);
+		return;
+	}
+	const protocol = host.operationProtocols.get(watch.key);
+	if (protocol?.active === 'live') protocol.active = undefined;
+	entry.active = false;
+	const unsubscribe = entry.unsubscribe;
+	entry.unsubscribe = () => undefined;
+	try {
+		unsubscribe();
+	} catch {
+		// The inactive stream is fenced; transport cleanup is best effort.
+	}
+	const state = host.queryState(watch.key);
+	state.live = 'off';
+	host.emitState(watch.key, false);
+	const authorizationGeneration = host.protocolGenerationSequence();
+	const supersededFlight =
+		entry.operationGeneration === undefined
+			? undefined
+			: host.inFlight.get(watch.key);
+	const refresh = (): void => {
+		if (
+			host.protocolGenerationSequence() !== authorizationGeneration ||
+			host.lives.get(watch.key) !== entry ||
+			entry.active
+		) {
+			return;
+		}
+		void fetchWatch(host, watch, true);
+	};
+	/*
+	 * Keep the inactive entry as an authorization-generation-scoped
+	 * sentinel. Query ingestion calls resumeLiveWatches(); deleting this
+	 * entry would otherwise reopen an unsupported or completed stream
+	 * immediately. Authorization invalidation clears it and may retry.
+	 *
+	 * A supported live frame advances the operation generation. Any HTTP
+	 * request that was already running is therefore doomed by its response
+	 * fence; drain it before starting the authoritative fallback. A first
+	 * unsupported frame never advances the generation, so its overlapping
+	 * HTTP request remains valid and can be reused directly.
+	 */
+	if (supersededFlight === undefined) {
+		refresh();
+	} else {
+		void supersededFlight.then(refresh, refresh);
+	}
+}
+
+export function restartLive(host: FetchLiveHost, key: string): void {
+	const previous = host.lives.get(key);
+	if (previous === undefined) return;
+	const count = previous.count;
+	previous.active = false;
+	host.lives.delete(key);
+	try {
+		previous.unsubscribe();
+	} catch {
+		// The old generation is already fenced; cleanup is best effort.
+	}
+	const watch = [...(host.watches.get(key) ?? [])].find(
+		(candidate) => candidate.liveRequested
+	);
+	if (watch === undefined) {
+		host.queryState(key).live = 'off';
+		return;
+	}
+	retainLive(host, watch);
+	const replacement = host.lives.get(key);
+	if (replacement !== undefined) replacement.count = count;
+}
+
+export function resumeLiveWatches(host: FetchLiveHost): void {
+	if (host.protocolGeneration() === undefined) return;
+	for (const [key, watches] of host.watches) {
+		if (host.lives.has(key)) continue;
+		const liveWatches = [...watches].filter(
+			(watch) => watch.liveRequested
+		);
+		const first = liveWatches[0];
+		if (first === undefined) continue;
+		retainLive(host, first);
+		const entry = host.lives.get(key);
+		if (entry !== undefined) entry.count = liveWatches.length;
+	}
+}
+
+export function releaseLive(host: FetchLiveHost, key: string): void {
+	const entry = host.lives.get(key);
+	if (!entry) return;
+	entry.count -= 1;
+	if (entry.count > 0) return;
+	entry.active = false;
+	host.lives.delete(key);
+	entry.unsubscribe();
+	host.queryState(key).live = 'off';
+	host.emitState(key, false);
+}
diff --git a/js/src/replica/distributed-replica/impl-hydration-orchestrate.ts b/js/src/replica/distributed-replica/impl-hydration-orchestrate.ts
new file mode 100644
index 00000000..8a7ad7af
--- /dev/null
+++ b/js/src/replica/distributed-replica/impl-hydration-orchestrate.ts
@@ -0,0 +1,465 @@
+import {
+	createCacheEngine,
+	type CacheEngine,
+	type CacheEngineSnapshot
+} from '../../internal/cache-engine.js';
+import type { GraphqlVariables } from '../../types.js';
+import type {
+	DistributedOpaqueString,
+	DistributedTrustedPreset
+} from '../../protocol.js';
+import { matchReplicaTrustedPresetInventory } from '../commands.js';
+import type { ReplicaDiagnosticEventInput } from '../diagnostics.js';
+import { replicaIndexKey, resolveArguments } from '../identity.js';
+import type { ReplicaIndexPlanRegistration } from '../index-maintenance.js';
+import {
+	runtimeRoot,
+	type RuntimeObjectBranch,
+	type RuntimeObjectSelection,
+	type RuntimeRootSelection
+} from '../selection.js';
+import type {
+	ReplicaAuthoritativeScope,
+	ReplicaDehydratedState
+} from '../types.js';
+import { freezeRecordClock } from './clocks.js';
+import { trustedPresetInventoryFingerprint } from './helpers.js';
+import {
+	hydrationMetadataConsistent,
+	parseAuthoritativeScope,
+	parseReplicaHydration,
+	serializeOperationProtocolGroup
+} from './hydration.js';
+import type {
+	AnonymousRecordProtocolClock,
+	OperationProtocolGroup,
+	OptimisticReceiptState,
+	ProtocolGeneration,
+	QueryState,
+	RecordProtocolClock,
+	RegisteredCommandAuthorityContract,
+	RenderedOperation,
+	ReplicaArtifactBinding,
+	ReplicaDehydratedPayloadV1
+} from './types.js';
+import type { ReplicaDiagnosticLayerInput } from '../diagnostics.js';
+
+/**
+ * Host for dehydrate / hydrate orchestration.
+ */
+export type HydrationHost = {
+	readonly engine: CacheEngine;
+	readonly operationProtocols: Map<string, OperationProtocolGroup>;
+	readonly operationGenerations: Map<string, number>;
+	readonly recordClocks: Map<string, RecordProtocolClock>;
+	readonly recordKeysByScope: Map<DistributedOpaqueString, string>;
+	readonly anonymousRecordClocks: Map<
+		DistributedOpaqueString,
+		AnonymousRecordProtocolClock
+	>;
+	readonly optimisticReceipts: Map<string, OptimisticReceiptState>;
+	readonly diagnosticLayers: Map<string, ReplicaDiagnosticLayerInput> | undefined;
+	readonly renderedOperations: Map<string, RenderedOperation>;
+	readonly readOperationKeys: Set<string>;
+	readonly watchRenderCounts: Map<string, number>;
+	readonly indexPlanRegistrations: Map<string, ReplicaIndexPlanRegistration>;
+	readonly queryStates: Map<string, QueryState>;
+	readonly diagnostics: { readonly enabled: boolean };
+	getProtocolGeneration(): ProtocolGeneration | undefined;
+	setProtocolGeneration(value: ProtocolGeneration | undefined): void;
+	getProtocolGenerationSequence(): number;
+	getTrustedPresets(): readonly DistributedTrustedPreset[];
+	setTrustedPresets(value: readonly DistributedTrustedPreset[]): void;
+	getNextIndexRevision(): string;
+	setNextIndexRevision(value: string): void;
+	getArtifactBinding(): ReplicaArtifactBinding | undefined;
+	setArtifactBinding(value: ReplicaArtifactBinding | undefined): void;
+	getCommandAuthorityContract():
+		| RegisteredCommandAuthorityContract
+		| undefined;
+	setDiagnosticLayerSequence(value: number): void;
+	operationGeneration(key: string): number;
+	closeActiveTransports(): void;
+	closeAuthorizationGeneration(): void;
+	resumeLiveWatches(): void;
+	syncDiagnostics(): void;
+	diagnosticEvent(event: ReplicaDiagnosticEventInput): void;
+	refreshIndexMaintenance(): void;
+	finishDehydration(): void;
+};
+
+export function reachableConfirmedState(host: HydrationHost): {
+	readonly cache: CacheEngineSnapshot;
+	readonly recordKeys: ReadonlySet<string>;
+	readonly clockRecordKeys: ReadonlySet<string>;
+	readonly models: ReadonlySet<string>;
+} {
+	const snapshot = host.engine.extract();
+	const indexes = new Map(snapshot.indexes.map((index) => [index.key, index]));
+	const records = new Map(snapshot.records.map((record) => [record.key, record]));
+	const indexKeys = new Set<string>();
+	const recordKeys = new Set<string>();
+	const clockRecordKeys = new Set<string>();
+	const recordFields = new Map<string, Set<string>>();
+	const models = new Set<string>();
+
+	const rememberSelection = (selection: RuntimeObjectSelection): void => {
+		if (selection.storage.kind === 'normalized') {
+			models.add(selection.storage.model);
+		}
+		for (const member of selection.members) {
+			if (member.kind === 'branch') rememberSelection(member.selection);
+		}
+	};
+	const rememberRecord = (
+		recordKey: string,
+		selection: RuntimeObjectSelection
+	): void => {
+		recordKeys.add(recordKey);
+		clockRecordKeys.add(recordKey);
+		let selected = recordFields.get(recordKey);
+		if (selected === undefined) {
+			selected = new Set();
+			recordFields.set(recordKey, selected);
+		}
+		for (const member of selection.members) {
+			if (member.kind === 'scalar') selected.add(member.field);
+		}
+	};
+	const visitObject = (
+		selection: RuntimeObjectSelection,
+		recordKey: string,
+		variables: GraphqlVariables
+	): void => {
+		rememberRecord(recordKey, selection);
+		for (const member of selection.members) {
+			if (member.kind !== 'branch') continue;
+			visitBranch(member, recordKey, variables);
+		}
+	};
+	const visitBranch = (
+		selection: RuntimeRootSelection | RuntimeObjectBranch,
+		parent: string | undefined,
+		variables: GraphqlVariables
+	): void => {
+		const key = replicaIndexKey({
+			...(parent === undefined ? {} : { parent }),
+			field: selection.field,
+			arguments: resolveArguments(
+				selection.arguments,
+				variables,
+				selection.coverage
+			)
+		});
+		const index = indexes.get(key);
+		if (index === undefined) return;
+		indexKeys.add(key);
+		for (const recordKey of index.records) {
+			visitObject(selection.selection, recordKey, variables);
+		}
+	};
+
+	for (const [key, rendered] of host.renderedOperations) {
+		for (const rootArtifact of rendered.artifact.roots) {
+			const root = runtimeRoot(rootArtifact);
+			rememberSelection(root.selection);
+			visitBranch(root, undefined, rendered.variables);
+		}
+		const group = host.operationProtocols.get(key);
+		for (const state of [group?.query, group?.live]) {
+			for (const recordKey of state?.pathRecords.values() ?? []) {
+				clockRecordKeys.add(recordKey);
+			}
+		}
+	}
+
+	return Object.freeze({
+		cache: Object.freeze({
+			version: 1 as const,
+			records: Object.freeze(
+				[...recordKeys]
+					.sort()
+					.flatMap((key) => {
+						const record = records.get(key);
+						if (record === undefined) return [];
+						const selected = recordFields.get(key) ?? new Set();
+						return [
+							Object.freeze({
+								...record,
+								fields: Object.freeze(
+									Object.fromEntries(
+										Object.entries(record.fields).filter(([field]) =>
+											selected.has(field)
+										)
+									)
+								),
+								links: Object.freeze({})
+							})
+						];
+					})
+			),
+			indexes: Object.freeze(
+				[...indexKeys]
+					.sort()
+					.flatMap((key) => {
+						const index = indexes.get(key);
+						return index === undefined ? [] : [index];
+					})
+			)
+		}),
+		recordKeys,
+		clockRecordKeys,
+		models
+	});
+}
+
+export function finishDehydration(host: HydrationHost): void {
+	let plansChanged = false;
+	for (const key of host.readOperationKeys) {
+		if (!host.watchRenderCounts.has(key)) {
+			host.renderedOperations.delete(key);
+			const registration = host.indexPlanRegistrations.get(key);
+			if (registration !== undefined) {
+				host.indexPlanRegistrations.delete(key);
+				registration.dispose();
+				plansChanged = true;
+			}
+		}
+	}
+	host.readOperationKeys.clear();
+	if (plansChanged) host.refreshIndexMaintenance();
+}
+
+export function dehydrateReplica(host: HydrationHost): ReplicaDehydratedState {
+	const scope = host.getProtocolGeneration();
+	if (scope === undefined) {
+		throw new Error(
+			'cannot dehydrate replica before the server establishes an authoritative scope'
+		);
+	}
+	const reachable = reachableConfirmedState(host);
+	const reachableIndexKeys = new Set(
+		reachable.cache.indexes.map((index) => index.key)
+	);
+	const operationKeys = new Set(host.renderedOperations.keys());
+	for (const [key, group] of host.operationProtocols) {
+		const governsReachableState = [group.query, group.live].some(
+			(state) =>
+				state !== undefined &&
+				(
+					[...state.indexKeys].some((indexKey) =>
+						reachableIndexKeys.has(indexKey)
+					) ||
+					[...state.pathRecords.values()].some((recordKey) =>
+						reachable.clockRecordKeys.has(recordKey)
+					)
+				)
+		);
+		if (governsReachableState) operationKeys.add(key);
+	}
+	const operations = [...operationKeys]
+		.sort()
+		.flatMap((key) => {
+			const group = host.operationProtocols.get(key);
+			if (group === undefined) return [];
+			return [
+				serializeOperationProtocolGroup(
+					key,
+					group,
+					host.operationGeneration(key)
+				)
+			];
+		});
+	const recordClocks = [...host.recordClocks]
+		.filter(([key]) => reachable.clockRecordKeys.has(key))
+		.sort(([left], [right]) => left.localeCompare(right))
+		.map(([key, clock]) =>
+			Object.freeze([key, freezeRecordClock(clock)] as const)
+		);
+	const anonymousRecordClocks = [...host.anonymousRecordClocks]
+		.filter(([, value]) => reachable.models.has(value.model))
+		.sort(([left], [right]) => left.localeCompare(right))
+		.map(([scopeToken, value]) =>
+			Object.freeze([
+				scopeToken,
+				Object.freeze({
+					model: value.model,
+					clock: freezeRecordClock(value.clock)
+				})
+			] as const)
+		);
+	const payload: ReplicaDehydratedPayloadV1 = Object.freeze({
+		cache: reachable.cache,
+		operations: Object.freeze(operations),
+		recordClocks: Object.freeze(recordClocks),
+		anonymousRecordClocks: Object.freeze(anonymousRecordClocks),
+		trustedPresets: host.getTrustedPresets(),
+		nextIndexRevision: host.getNextIndexRevision()
+	});
+	const state = Object.freeze({
+		version: 1 as const,
+		scope: Object.freeze({
+			protocolVersion: 1 as const,
+			schemaHash: scope.schemaHash,
+			cacheScope: scope.cacheScope
+		}),
+		payload
+	});
+	host.finishDehydration();
+	return state;
+}
+
+export function hydrateReplica(
+	host: HydrationHost,
+	state: ReplicaDehydratedState,
+	authoritativeScope: ReplicaAuthoritativeScope
+): boolean {
+	const rejected = (
+		reason:
+			| 'invalid'
+			| 'scope-mismatch'
+			| 'artifact-mismatch'
+			| 'active-scope-mismatch'
+			| 'metadata-mismatch'
+	): false => {
+		if (host.diagnostics.enabled) {
+			host.diagnosticEvent(
+				Object.freeze({ kind: 'hydration', action: 'rejected', reason })
+			);
+		}
+		return false;
+	};
+	const parsed = parseReplicaHydration(state);
+	const expectedScope = parseAuthoritativeScope(authoritativeScope);
+	if (parsed === undefined || expectedScope === undefined) {
+		return rejected('invalid');
+	}
+	if (
+		parsed.scope.protocolVersion !== expectedScope.protocolVersion ||
+		parsed.scope.schemaHash !== expectedScope.schemaHash ||
+		parsed.scope.cacheScope !== expectedScope.cacheScope
+	) {
+		return rejected('scope-mismatch');
+	}
+	const binding = host.getArtifactBinding();
+	if (
+		binding !== undefined &&
+		binding.schemaHash !== parsed.scope.schemaHash
+	) {
+		return rejected('artifact-mismatch');
+	}
+	const current = host.getProtocolGeneration();
+	if (
+		current !== undefined &&
+		(
+			current.protocolVersion !== parsed.scope.protocolVersion ||
+			current.schemaHash !== parsed.scope.schemaHash ||
+			current.cacheScope !== parsed.scope.cacheScope
+		)
+	) {
+		return rejected('active-scope-mismatch');
+	}
+	const preserveLocalCommandState = current !== undefined;
+
+	// Validate the private engine payload before closing transports or changing
+	// any live state. `restore` parses fully before its own transaction.
+	try {
+		createCacheEngine().restore(parsed.cache);
+		const expectedTrustedPresets =
+			binding?.trustedPresets !== undefined
+				? binding.trustedPresets
+				: host.getCommandAuthorityContract()?.trustedPresets;
+		if (expectedTrustedPresets !== undefined) {
+			matchReplicaTrustedPresetInventory(
+				expectedTrustedPresets,
+				parsed.trustedPresets
+			);
+		}
+		if (
+			preserveLocalCommandState &&
+			trustedPresetInventoryFingerprint(host.getTrustedPresets()) !==
+				trustedPresetInventoryFingerprint(parsed.trustedPresets)
+		) {
+			throw new TypeError(
+				'trusted presets changed within one authoritative cache scope'
+			);
+		}
+	} catch {
+		return rejected('invalid');
+	}
+	if (!hydrationMetadataConsistent(parsed)) {
+		return rejected('metadata-mismatch');
+	}
+
+	if (preserveLocalCommandState) {
+		host.closeActiveTransports();
+	} else {
+		host.closeAuthorizationGeneration();
+	}
+	host.queryStates.clear();
+	host.operationProtocols.clear();
+	for (const [key, group] of parsed.operationProtocols) {
+		host.operationProtocols.set(key, group);
+	}
+	host.operationGenerations.clear();
+	for (const [key, generation] of parsed.operationGenerations) {
+		host.operationGenerations.set(key, generation);
+	}
+	host.recordClocks.clear();
+	for (const [key, clock] of parsed.recordClocks) {
+		host.recordClocks.set(key, clock);
+	}
+	host.recordKeysByScope.clear();
+	for (const [scopeToken, key] of parsed.recordKeysByScope) {
+		host.recordKeysByScope.set(scopeToken, key);
+	}
+	host.anonymousRecordClocks.clear();
+	for (const [scopeToken, clock] of parsed.anonymousRecordClocks) {
+		host.anonymousRecordClocks.set(scopeToken, clock);
+	}
+	if (!preserveLocalCommandState) {
+		host.optimisticReceipts.clear();
+		host.diagnosticLayers?.clear();
+		host.setDiagnosticLayerSequence(0);
+	}
+	host.setTrustedPresets(parsed.trustedPresets);
+	host.setNextIndexRevision(parsed.nextIndexRevision);
+	host.setProtocolGeneration(parsed.scope);
+	host.setArtifactBinding(
+		Object.freeze({
+			version: 1,
+			schemaHash: parsed.scope.schemaHash,
+			...(binding?.surfaceIdentity !== undefined
+				? { surfaceIdentity: binding.surfaceIdentity }
+				: {}),
+			...(binding?.trustedPresets !== undefined
+				? { trustedPresets: binding.trustedPresets }
+				: {})
+		})
+	);
+	if (preserveLocalCommandState) {
+		host.engine.restoreConfirmed(parsed.cache);
+	} else {
+		host.engine.restore(parsed.cache);
+	}
+	host.resumeLiveWatches();
+	host.syncDiagnostics();
+	if (host.diagnostics.enabled) {
+		host.diagnosticEvent(
+			Object.freeze({
+				kind: 'hydration',
+				action: 'accepted',
+				reason: 'accepted'
+			})
+		);
+		host.diagnosticEvent(
+			Object.freeze({
+				kind: 'scope',
+				action: 'established',
+				generation: host.getProtocolGenerationSequence(),
+				schemaHash: parsed.scope.schemaHash
+			})
+		);
+	}
+	return true;
+}
diff --git a/js/src/replica/distributed-replica/impl-optimistic.ts b/js/src/replica/distributed-replica/impl-optimistic.ts
new file mode 100644
index 00000000..8a5438f7
--- /dev/null
+++ b/js/src/replica/distributed-replica/impl-optimistic.ts
@@ -0,0 +1,296 @@
+import type { CacheEngine } from '../../internal/cache-engine.js';
+import {
+	DistributedProtocolError,
+	type DistributedCommandMetadata,
+	type DistributedProjectionObservation
+} from '../../protocol.js';
+import type {
+	ReplicaDiagnosticEventInput,
+	ReplicaDiagnosticLayerInput
+} from '../diagnostics.js';
+import type { ReplicaIndexSemanticChange } from '../index-maintenance.js';
+import type {
+	ReplicaBaseWriter,
+	ReplicaOptimisticWriter
+} from '../types.js';
+import { protocolInvalid } from './clocks.js';
+import { baseWriter } from './helpers.js';
+import {
+	assertReplicaOptimisticLayerId,
+	captureReplicaOptimisticUpdate,
+	cloneOptimisticReceipt,
+	diagnosticReceiptCounts,
+	expectationKey,
+	optimisticReceiptState,
+	replayReplicaOptimisticUpdate,
+	sameReceipt
+} from './optimistic.js';
+import type { OptimisticReceiptState } from './types.js';
+
+/**
+ * Host for optimistic layer lifecycle and receipt planning.
+ */
+export type OptimisticHost = {
+	readonly engine: CacheEngine;
+	readonly optimisticReceipts: Map<string, OptimisticReceiptState>;
+	readonly diagnosticLayers: Map<string, ReplicaDiagnosticLayerInput> | undefined;
+	readonly diagnostics: { readonly enabled: boolean };
+	getDiagnosticLayerSequence(): number;
+	setDiagnosticLayerSequence(value: number): void;
+	diagnosticEvent(event: ReplicaDiagnosticEventInput): void;
+	syncDiagnostics(): void;
+	retireDiagnosticLayer(
+		id: string,
+		action: 'retired' | 'rejected',
+		receiptState: 'projected' | 'rejected',
+		receipt?: OptimisticReceiptState
+	): void;
+};
+
+export function createOptimisticLayerOn(
+	host: OptimisticHost,
+	id: string,
+	update: (writer: ReplicaOptimisticWriter) => void,
+	semanticChanges: readonly ReplicaIndexSemanticChange[] = Object.freeze([])
+): void {
+	assertReplicaOptimisticLayerId(id);
+	if (host.engine.optimisticLayerState(id) !== undefined) {
+		throw new Error(`optimistic layer already exists: ${id}`);
+	}
+	if (typeof update !== 'function') {
+		throw new TypeError('optimistic layer update must be a function');
+	}
+	const captured = captureReplicaOptimisticUpdate(
+		id,
+		update,
+		semanticChanges
+	);
+	host.engine.createOptimisticLayer(
+		id,
+		(writer) => replayReplicaOptimisticUpdate(writer, captured.operations),
+		captured.context
+	);
+	if (host.diagnosticLayers !== undefined) {
+		const recordChanges = captured.operations.filter(
+			(operation) =>
+				operation.kind === 'write-record' ||
+				operation.kind === 'tombstone-record'
+		).length;
+		const indexChanges = captured.operations.length - recordChanges;
+		const nextSequence = host.getDiagnosticLayerSequence() + 1;
+		host.setDiagnosticLayerSequence(nextSequence);
+		const layer = Object.freeze({
+			id,
+			sequence: nextSequence,
+			state: 'optimistic' as const,
+			recordChanges,
+			indexChanges,
+			semanticChanges: recordChanges + semanticChanges.length
+		});
+		host.diagnosticLayers.set(id, layer);
+		host.diagnosticEvent(
+			Object.freeze({
+				kind: 'layer',
+				layer: id,
+				action: 'created',
+				recordChanges,
+				indexChanges
+			})
+		);
+		host.diagnosticEvent(
+			Object.freeze({
+				kind: 'receipt',
+				command: id,
+				state: 'optimistic',
+				obligations: 0,
+				observed: 0
+			})
+		);
+		host.syncDiagnostics();
+	}
+}
+
+export function markOptimisticLayerAcceptedOn(
+	host: OptimisticHost,
+	id: string,
+	receipt?: DistributedCommandMetadata
+): boolean {
+	if (receipt !== undefined && receipt.commandId !== id) {
+		throw new TypeError('optimistic layer id must equal the causal command id');
+	}
+	const accepted = host.engine.markOptimisticLayerAccepted(id);
+	if (!accepted) return false;
+	const diagnosticLayer = host.diagnosticLayers?.get(id);
+	if (diagnosticLayer !== undefined) {
+		host.diagnosticLayers!.set(
+			id,
+			Object.freeze({ ...diagnosticLayer, state: 'accepted' as const })
+		);
+		host.diagnosticEvent(
+			Object.freeze({
+				kind: 'layer',
+				layer: id,
+				action: 'accepted',
+				recordChanges: diagnosticLayer.recordChanges,
+				indexChanges: diagnosticLayer.indexChanges
+			})
+		);
+	}
+	if (receipt === undefined) {
+		if (host.diagnostics.enabled) {
+			host.diagnosticEvent(
+				Object.freeze({
+					kind: 'receipt',
+					command: id,
+					state: 'accepted',
+					obligations: 0,
+					observed: 0
+				})
+			);
+		}
+		host.syncDiagnostics();
+		return true;
+	}
+	const next = optimisticReceiptState(receipt);
+	const current = host.optimisticReceipts.get(id);
+	if (current !== undefined && !sameReceipt(current, next)) {
+		throw new DistributedProtocolError(
+			'DISTRIBUTED_PROTOCOL_INVALID',
+			'extensions.distributed.command'
+		);
+	}
+	host.optimisticReceipts.set(id, next);
+	if (host.diagnostics.enabled) {
+		const counts = diagnosticReceiptCounts(next);
+		host.diagnosticEvent(
+			Object.freeze({
+				kind: 'receipt',
+				command: id,
+				state:
+					counts.obligations === 0
+						? ('accepted' as const)
+						: ('accepted_pending_projection' as const),
+				obligations: counts.obligations,
+				observed: counts.observed
+			})
+		);
+	}
+	host.syncDiagnostics();
+	return true;
+}
+
+export function confirmOptimisticLayerOn<T>(
+	host: OptimisticHost,
+	id: string,
+	update: (writer: ReplicaBaseWriter) => T
+): T {
+	const result = host.engine.confirmOptimisticLayer(id, (writer) =>
+		update(baseWriter(writer))
+	);
+	host.retireDiagnosticLayer(id, 'retired', 'projected');
+	host.optimisticReceipts.delete(id);
+	host.syncDiagnostics();
+	return result;
+}
+
+export function rejectOptimisticLayerOn(
+	host: OptimisticHost,
+	id: string
+): boolean {
+	const rejected = host.engine.rejectOptimisticLayer(id);
+	if (rejected) {
+		host.retireDiagnosticLayer(id, 'rejected', 'rejected');
+		host.optimisticReceipts.delete(id);
+		host.syncDiagnostics();
+	}
+	return rejected;
+}
+
+export function planOptimisticReceipts(
+	host: OptimisticHost,
+	command: DistributedCommandMetadata | undefined,
+	observations: readonly DistributedProjectionObservation[],
+	satisfactionAdmissible: boolean
+): {
+	updates: Map<string, OptimisticReceiptState>;
+	satisfied: string[];
+} {
+	const updates = new Map<string, OptimisticReceiptState>();
+	if (
+		command !== undefined &&
+		host.engine.optimisticLayerState(command.commandId) !== undefined
+	) {
+		const proposed = optimisticReceiptState(command);
+		const current = host.optimisticReceipts.get(command.commandId);
+		if (current !== undefined && !sameReceipt(current, proposed)) {
+			protocolInvalid('extensions.distributed.command');
+		}
+		updates.set(
+			command.commandId,
+			cloneOptimisticReceipt(current ?? proposed)
+		);
+	}
+	for (const [id, receipt] of host.optimisticReceipts) {
+		if (!updates.has(id)) {
+			updates.set(id, cloneOptimisticReceipt(receipt));
+		}
+	}
+	for (const receipt of updates.values()) {
+		for (const observation of observations) {
+			if (observation.causationId !== receipt.causationId) continue;
+			const key = expectationKey(observation);
+			if (receipt.expectations.has(key)) receipt.observed.add(key);
+		}
+	}
+	const satisfied = satisfactionAdmissible
+		? [...updates]
+				.filter(
+					([, receipt]) =>
+						receipt.expectations.size > 0 &&
+						[...receipt.expectations.keys()].every((key) =>
+							receipt.observed.has(key)
+						)
+				)
+				.map(([id]) => id)
+		: [];
+	return { updates, satisfied };
+}
+
+export function applyReceiptOnly(
+	host: OptimisticHost,
+	command: DistributedCommandMetadata | undefined
+): void {
+	if (command === undefined) return;
+	const plan = planOptimisticReceipts(
+		host,
+		command,
+		command.observations,
+		true
+	);
+	for (const [id, receipt] of plan.updates) {
+		host.optimisticReceipts.set(id, receipt);
+		host.engine.markOptimisticLayerAccepted(id);
+		const layer = host.diagnosticLayers?.get(id);
+		if (layer !== undefined) {
+			host.diagnosticLayers!.set(
+				id,
+				Object.freeze({ ...layer, state: 'accepted' as const })
+			);
+		}
+		if (host.diagnostics.enabled) {
+			const counts = diagnosticReceiptCounts(receipt);
+			host.diagnosticEvent(
+				Object.freeze({
+					kind: 'receipt',
+					command: id,
+					state:
+						counts.obligations === 0
+							? ('accepted' as const)
+							: ('accepted_pending_projection' as const),
+					obligations: counts.obligations,
+					observed: counts.observed
+				})
+			);
+		}
+	}
+}
diff --git a/js/src/replica/distributed-replica/impl-protocol.ts b/js/src/replica/distributed-replica/impl-protocol.ts
new file mode 100644
index 00000000..2d230b82
--- /dev/null
+++ b/js/src/replica/distributed-replica/impl-protocol.ts
@@ -0,0 +1,234 @@
+import type { CacheEngine } from '../../internal/cache-engine.js';
+import type { GraphqlVariables } from '../../types.js';
+import type {
+	DistributedOpaqueString,
+	DistributedProtocolEnvelope,
+	DistributedTrustedPreset
+} from '../../protocol.js';
+import { matchReplicaTrustedPresetInventory } from '../commands.js';
+import type {
+	ReplicaDiagnosticEventInput,
+	ReplicaDiagnosticLayerInput
+} from '../diagnostics.js';
+import type { ReplicaIndexPlanRegistration } from '../index-maintenance.js';
+import { validateReplicaOperationBinding as validatedArtifactBinding } from '../operation-binding.js';
+import type {
+	ReplicaOperationArtifact,
+	ReplicaWriteSource
+} from '../types.js';
+import { protocolInvalid } from './clocks.js';
+import { EMPTY_CACHE_SNAPSHOT, EMPTY_TRUSTED_PRESETS } from './constants.js';
+import {
+	canonicalTrustedPresets,
+	trustedPresetDescriptorFingerprint,
+	trustedPresetInventoryFingerprint
+} from './helpers.js';
+import type {
+	AnonymousRecordProtocolClock,
+	OperationProtocolGroup,
+	OptimisticReceiptState,
+	ProjectedRecordFence,
+	ProtocolGeneration,
+	QueryState,
+	RecordProtocolClock,
+	RegisteredCommandAuthorityContract,
+	RenderedOperation
+} from './types.js';
+import type { ReplicaWatchState } from './watch.js';
+
+/**
+ * Host for protocol generation staging, purge, and authorization closeout.
+ */
+export type ProtocolHost = {
+	readonly engine: CacheEngine;
+	readonly queryStates: Map<string, QueryState>;
+	readonly operationProtocols: Map<string, OperationProtocolGroup>;
+	readonly operationGenerations: Map<string, number>;
+	readonly recordClocks: Map<string, RecordProtocolClock>;
+	readonly recordKeysByScope: Map<DistributedOpaqueString, string>;
+	readonly projectedRecordFences: Map<string, ProjectedRecordFence>;
+	readonly anonymousRecordClocks: Map<
+		DistributedOpaqueString,
+		AnonymousRecordProtocolClock
+	>;
+	readonly optimisticReceipts: Map<string, OptimisticReceiptState>;
+	readonly diagnosticLayers: Map<string, ReplicaDiagnosticLayerInput> | undefined;
+	readonly indexPlanRegistrations: Map<string, ReplicaIndexPlanRegistration>;
+	readonly renderedOperations: Map<string, RenderedOperation>;
+	readonly readOperationKeys: Set<string>;
+	readonly watchRenderCounts: Map<string, number>;
+	readonly watches: Map<
+		string,
+		Set<ReplicaWatchState<unknown, GraphqlVariables>>
+	>;
+	readonly diagnostics: { readonly enabled: boolean };
+	getProtocolGeneration(): ProtocolGeneration | undefined;
+	setProtocolGeneration(value: ProtocolGeneration | undefined): void;
+	getProtocolGenerationSequence(): number;
+	bumpProtocolGenerationSequence(): void;
+	getTrustedPresets(): readonly DistributedTrustedPreset[];
+	setTrustedPresets(value: readonly DistributedTrustedPreset[]): void;
+	getCommandAuthorityContract():
+		| RegisteredCommandAuthorityContract
+		| undefined;
+	setProjectionGeneration(value: number): void;
+	setNextIndexRevision(value: string): void;
+	setDiagnosticLayerSequence(value: number): void;
+	clearIndexMaintenance(): void;
+	abortAuthorization(): void;
+	closeActiveTransports(): void;
+	syncDiagnostics(): void;
+	emitState(key: string, allowFetch: boolean): void;
+	diagnosticEvent(event: ReplicaDiagnosticEventInput): void;
+	rememberRenderedOperation<TData, TVariables extends GraphqlVariables>(
+		key: string,
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables,
+		source: 'read' | 'watch'
+	): void;
+};
+
+export function validateProtocolBinding<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	host: ProtocolHost,
+	artifact: ReplicaOperationArtifact<TData, TVariables>,
+	envelope: DistributedProtocolEnvelope,
+	source: ReplicaWriteSource
+): void {
+	const binding = artifact.protocol;
+	if (binding === undefined) {
+		protocolInvalid('extensions.distributed');
+	}
+	if (binding.version !== 1) {
+		throw new TypeError('replica artifact protocol version is unsupported');
+	}
+	if (binding.schemaHash !== envelope.schemaHash) {
+		purgeProtocolGeneration(host);
+		protocolInvalid('extensions.distributed.schemaHash');
+	}
+	const expectedOperation =
+		source === 'live' ? artifact.live?.id : binding.operation;
+	if (
+		expectedOperation === undefined ||
+		envelope.operation !== expectedOperation
+	) {
+		protocolInvalid('extensions.distributed.operation');
+	}
+}
+
+export function stageProtocolGeneration(
+	host: ProtocolHost,
+	envelope: DistributedProtocolEnvelope
+): ProtocolGeneration {
+	const next: ProtocolGeneration = {
+		protocolVersion: 1,
+		cacheScope: envelope.cacheScope,
+		schemaHash: envelope.schemaHash
+	};
+	const current = host.getProtocolGeneration();
+	if (current === undefined) return next;
+	if (
+		current.cacheScope === next.cacheScope &&
+		current.schemaHash === next.schemaHash
+	) {
+		return current;
+	}
+	purgeProtocolGeneration(host);
+	return next;
+}
+
+export function stageTrustedPresets<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	host: ProtocolHost,
+	incoming: readonly DistributedTrustedPreset[],
+	nextGeneration: ProtocolGeneration,
+	artifact: ReplicaOperationArtifact<TData, TVariables>
+): readonly DistributedTrustedPreset[] {
+	const presets = canonicalTrustedPresets(incoming);
+	try {
+		const binding = validatedArtifactBinding(artifact);
+		const operationDescriptors = binding.trustedPresets;
+		const commandDescriptors =
+			host.getCommandAuthorityContract()?.trustedPresets;
+		if (
+			commandDescriptors !== undefined &&
+			trustedPresetDescriptorFingerprint(operationDescriptors) !==
+				trustedPresetDescriptorFingerprint(commandDescriptors)
+		) {
+			throw new TypeError(
+				'operation and command trusted preset contracts differ'
+			);
+		}
+		matchReplicaTrustedPresetInventory(operationDescriptors, presets);
+		if (
+			host.getProtocolGeneration() === nextGeneration &&
+			trustedPresetInventoryFingerprint(host.getTrustedPresets()) !==
+				trustedPresetInventoryFingerprint(presets)
+		) {
+			throw new TypeError(
+				'trusted presets changed within one authoritative cache scope'
+			);
+		}
+		return presets;
+	} catch {
+		if (host.getProtocolGeneration() !== undefined) {
+			purgeProtocolGeneration(host);
+		}
+		protocolInvalid('extensions.distributed.trustedPresets');
+	}
+}
+
+export function purgeProtocolGeneration(host: ProtocolHost): void {
+	closeAuthorizationGeneration(host);
+	host.queryStates.clear();
+	host.operationProtocols.clear();
+	host.operationGenerations.clear();
+	host.recordClocks.clear();
+	host.recordKeysByScope.clear();
+	host.projectedRecordFences.clear();
+	host.anonymousRecordClocks.clear();
+	host.optimisticReceipts.clear();
+	host.diagnosticLayers?.clear();
+	host.setDiagnosticLayerSequence(0);
+	host.clearIndexMaintenance();
+	host.indexPlanRegistrations.clear();
+	host.renderedOperations.clear();
+	host.readOperationKeys.clear();
+	host.watchRenderCounts.clear();
+	host.setTrustedPresets(EMPTY_TRUSTED_PRESETS);
+	host.setProjectionGeneration(0);
+	host.setNextIndexRevision('0');
+	host.setProtocolGeneration(undefined);
+	host.engine.restore(EMPTY_CACHE_SNAPSHOT);
+	host.syncDiagnostics();
+	for (const watches of host.watches.values()) {
+		for (const watch of watches) {
+			host.rememberRenderedOperation(
+				watch.key,
+				watch.artifact,
+				watch.variables,
+				'watch'
+			);
+		}
+	}
+	for (const key of host.watches.keys()) host.emitState(key, true);
+	if (host.diagnostics.enabled) {
+		host.diagnosticEvent(
+			Object.freeze({
+				kind: 'scope',
+				action: 'invalidated',
+				generation: host.getProtocolGenerationSequence()
+			})
+		);
+	}
+}
+
+export function closeAuthorizationGeneration(host: ProtocolHost): void {
+	host.bumpProtocolGenerationSequence();
+	host.abortAuthorization();
+	host.closeActiveTransports();
+}
diff --git a/js/src/replica/distributed-replica/impl.ts b/js/src/replica/distributed-replica/impl.ts
new file mode 100644
index 00000000..b473fc9d
--- /dev/null
+++ b/js/src/replica/distributed-replica/impl.ts
@@ -0,0 +1,2630 @@
+import {
+	CacheRevisionConflictError,
+	createCacheEngine,
+	type BaseCacheWriter,
+	type CacheEngine,
+	type CacheEngineSnapshot,
+	type DerivedIndexMutation,
+	type DerivedIndexReconciler,
+	type OptimisticLayerView
+} from '../../internal/cache-engine.js';
+import type { GraphqlVariables } from '../../types.js';
+import {
+	compareDistributedDecimal,
+	DistributedProtocolError,
+	parseGraphqlResponseExtensions,
+	type DistributedCommandMetadata,
+	type DistributedLiveCursor,
+	type DistributedOpaqueString,
+	type DistributedProjectionObservation,
+	type DistributedProtocolEnvelope,
+	type DistributedQuerySnapshot,
+	type DistributedRecordRevision,
+	type DistributedTrustedPreset
+} from '../../protocol.js';
+import {
+	matchReplicaTrustedPresetInventory
+} from '../commands.js';
+import type {
+	ReplicaDiagnosticEventInput,
+	ReplicaDiagnosticLayerInput,
+	ReplicaDiagnosticsSink
+} from '../diagnostics.js';
+import {
+	replicaCommandAuthority,
+	replicaCommandDirectProjection,
+	replicaResultObservation,
+	type ReplicaCommandAuthorityRegistration,
+	type ReplicaCommandAuthoritySnapshot,
+	type ReplicaCommandDirectProjection,
+	type ReplicaCommandSurfaceContract,
+	type ReplicaResultObservationRegistration
+} from '../command-runtime.js';
+import {
+	canonicalizeOperationVariables,
+	replicaIndexKey,
+	replicaRecordKey,
+	resolveArguments
+} from '../identity.js';
+import {
+	materializeReplicaOperation,
+	type MaterializedReplicaResult
+} from '../materialize.js';
+import {
+	normalizeReplicaResult,
+	type ReplicaNormalizationProtocol,
+	type ReplicaProtocolRecordResolution
+} from '../normalize.js';
+import { createReplicaRevalidationMatcher } from '../revalidation.js';
+import {
+	validateReplicaOperationBinding as validatedArtifactBinding
+} from '../operation-binding.js';
+import {
+	createReplicaIndexMaintenanceRegistry,
+	formatReplicaIndexStaleReason,
+	type ReplicaIndexPlanRegistration,
+	type ReplicaIndexSemanticChange
+} from '../index-maintenance.js';
+import type {
+	DistributedReplicaOptions,
+	DistributedReplica as DistributedReplicaApi,
+	ReplicaAuthoritativeScope,
+	ReplicaBaseWriter,
+	ReplicaDehydratedState,
+	ReplicaIdentity,
+	ReplicaIndexInspection,
+	ReplicaIndexTarget,
+	ReplicaModelArtifact,
+	ReplicaOperationArtifact,
+	ReplicaOptimisticWriter,
+	ReplicaRecordInspection,
+	ReplicaRevalidationPlan,
+	ReplicaRevision,
+	ReplicaResultEnvelope,
+	ReplicaSnapshot,
+	ReplicaTransport,
+	ReplicaWatch,
+	ReplicaWriteSource,
+	WatchReplicaOptions
+} from '../types.js';
+import {
+	EMPTY_ERRORS,
+	EMPTY_TRUSTED_PRESETS,
+	MAX_ANONYMOUS_RECORD_CLOCKS
+} from './constants.js';
+import type {
+	AnonymousRecordProtocolClock,
+	IndexDisposition,
+	LiveEntry,
+	OperationProtocolGroup,
+	OperationProtocolSource,
+	OperationProtocolState,
+	OptimisticReceiptState,
+	ProjectedRecordFence,
+	ProtocolGeneration,
+	QueryState,
+	RecordProtocolClock,
+	RegisteredCommandAuthorityContract,
+	RenderedOperation,
+	ReplicaArtifactBinding,
+	SharedIndexDisposition,
+	ValidatedArtifactBinding
+} from './types.js';
+import {
+	compareCanonicalDecimalStrings,
+	compareEvidenceToProjectedFence,
+	compareIndexVector,
+	compareProjectedRecordFields,
+	compareRecordClock,
+	compareSnapshotToOperationState,
+	incrementCanonicalDecimal,
+	indexClockMap,
+	isComparableHandoffDisposition,
+	latestCursors,
+	protocolInvalid,
+	recordKeyMatchesModel,
+	responsePathKey,
+	sameRecordClock,
+	sameRecordRevision
+} from './clocks.js';
+import { diagnosticReceiptCounts } from './optimistic.js';
+import {
+	assertWriteSource,
+	indexKeyFromTarget,
+	indexMaintenanceSnapshot,
+	indexSemanticLayer,
+	operationKey,
+	prepareRecordEvidence,
+	protocolOperationSource,
+	replicaResultIndexKeys,
+	reportSafely,
+	reportUnhandledObserverError,
+	snapshotFrom,
+	stableErrors,
+	trustedPresetDescriptorFingerprint,
+	validatedCommandAuthorityContract
+} from './helpers.js';
+import { ReplicaWatchState } from './watch.js';
+import {
+	closeActiveTransports as closeActiveTransportsOn,
+	emitWatchState,
+	fetchWatch,
+	releaseLive as releaseLiveOn,
+	restartLive as restartLiveOn,
+	retainLive as retainLiveOn,
+	resumeLiveWatches as resumeLiveWatchesOn,
+	type FetchLiveHost
+} from './impl-fetch-live.js';
+import {
+	closeAuthorizationGeneration as closeAuthorizationGenerationOn,
+	purgeProtocolGeneration as purgeProtocolGenerationOn,
+	stageProtocolGeneration as stageProtocolGenerationOn,
+	stageTrustedPresets as stageTrustedPresetsOn,
+	validateProtocolBinding as validateProtocolBindingOn,
+	type ProtocolHost
+} from './impl-protocol.js';
+import {
+	applyReceiptOnly as applyReceiptOnlyOn,
+	confirmOptimisticLayerOn,
+	createOptimisticLayerOn,
+	markOptimisticLayerAcceptedOn,
+	planOptimisticReceipts as planOptimisticReceiptsOn,
+	rejectOptimisticLayerOn,
+	type OptimisticHost
+} from './impl-optimistic.js';
+import {
+	dehydrateReplica,
+	finishDehydration as finishDehydrationOn,
+	hydrateReplica,
+	type HydrationHost
+} from './impl-hydration-orchestrate.js';
+import {
+	diagnosticEvent as diagnosticEventOn,
+	diagnosticOperation as diagnosticOperationOn,
+	diagnosticScopeTransition as diagnosticScopeTransitionOn,
+	retireDiagnosticLayer as retireDiagnosticLayerOn,
+	syncDiagnostics as syncDiagnosticsOn,
+	type DiagnosticsHost
+} from './impl-diagnostics.js';
+
+export class DistributedReplicaImpl implements DistributedReplicaApi {
+	readonly #engine: CacheEngine;
+	readonly #transport: ReplicaTransport | undefined;
+	readonly #reportObserverError: (error: AggregateError) => void;
+	readonly #diagnostics: ReplicaDiagnosticsSink | undefined;
+	readonly #diagnosticLayers:
+		| Map<string, ReplicaDiagnosticLayerInput>
+		| undefined;
+	readonly #inFlight = new Map<string, Promise<void>>();
+	readonly #inFlightAborts = new Map<string, AbortController>();
+	readonly #queryStates = new Map<string, QueryState>();
+	readonly #watches = new Map<string, Set<ReplicaWatchState<unknown, GraphqlVariables>>>();
+	readonly #lives = new Map<string, LiveEntry>();
+	readonly #operationProtocols = new Map<string, OperationProtocolGroup>();
+	readonly #operationGenerations = new Map<string, number>();
+	readonly #recordClocks = new Map<string, RecordProtocolClock>();
+	readonly #recordKeysByScope = new Map<DistributedOpaqueString, string>();
+	readonly #projectedRecordFences = new Map<string, ProjectedRecordFence>();
+	readonly #anonymousRecordClocks = new Map<
+		DistributedOpaqueString,
+		AnonymousRecordProtocolClock
+	>();
+	readonly #optimisticReceipts = new Map<string, OptimisticReceiptState>();
+	readonly #renderedOperations = new Map<string, RenderedOperation>();
+	readonly #readOperationKeys = new Set<string>();
+	readonly #watchRenderCounts = new Map<string, number>();
+	readonly #resultObservers = new Set<
+		(envelope: ReplicaResultEnvelope<unknown>) => void
+	>();
+	readonly #indexMaintenance = createReplicaIndexMaintenanceRegistry();
+	readonly #indexPlanRegistrations = new Map<
+		string,
+		ReplicaIndexPlanRegistration
+	>();
+	readonly #derivedIndexReconciler: DerivedIndexReconciler = (
+		confirmed,
+		layers
+	) => this.#deriveMaintainedIndexes(confirmed, layers);
+	#commandAuthorityContract: RegisteredCommandAuthorityContract | undefined;
+	#trustedPresets: readonly DistributedTrustedPreset[] = EMPTY_TRUSTED_PRESETS;
+	#authorizationAbort = new AbortController();
+	#artifactBinding: ReplicaArtifactBinding | undefined;
+	#protocolGeneration: ProtocolGeneration | undefined;
+	#protocolGenerationSequence = 0;
+	#projectionGeneration = 0;
+	#nextIndexRevision = '0';
+	#diagnosticLayerSequence = 0;
+
+	#fetchLiveHostCache: FetchLiveHost | undefined;
+	#protocolHostCache: ProtocolHost | undefined;
+	#optimisticHostCache: OptimisticHost | undefined;
+	#hydrationHostCache: HydrationHost | undefined;
+	#diagnosticsHostCache: DiagnosticsHost | undefined;
+
+	constructor(options: DistributedReplicaOptions = {}) {
+		this.#transport = options.transport;
+		this.#reportObserverError = options.onObserverError ?? reportUnhandledObserverError;
+		this.#diagnostics = options.diagnostics;
+		this.#diagnosticLayers =
+			options.diagnostics === undefined ? undefined : new Map();
+		this.#engine = createCacheEngine({ onWatcherError: this.#reportObserverError });
+		this.#engine.setDerivedIndexReconciler(this.#derivedIndexReconciler);
+		this.#syncDiagnostics();
+	}
+
+	#diagnosticsEnabled(): { readonly enabled: boolean } {
+		return Object.freeze({ enabled: this.#diagnostics !== undefined });
+	}
+
+	#diagnosticsHost(): DiagnosticsHost {
+		if (this.#diagnosticsHostCache !== undefined) return this.#diagnosticsHostCache;
+		const self = this;
+		this.#diagnosticsHostCache = {
+			get engine() {
+				return self.#engine;
+			},
+			get diagnostics() {
+				return self.#diagnostics;
+			},
+			get diagnosticLayers() {
+				return self.#diagnosticLayers;
+			},
+			get optimisticReceipts() {
+				return self.#optimisticReceipts;
+			},
+			get reportObserverError() {
+				return self.#reportObserverError;
+			},
+			getProtocolGeneration: () => self.#protocolGeneration,
+			getProtocolGenerationSequence: () => self.#protocolGenerationSequence
+		};
+		return this.#diagnosticsHostCache;
+	}
+
+	#fetchLiveHost(): FetchLiveHost {
+		if (this.#fetchLiveHostCache !== undefined) return this.#fetchLiveHostCache;
+		const self = this;
+		this.#fetchLiveHostCache = {
+			get transport() {
+				return self.#transport;
+			},
+			get inFlight() {
+				return self.#inFlight;
+			},
+			get inFlightAborts() {
+				return self.#inFlightAborts;
+			},
+			get lives() {
+				return self.#lives;
+			},
+			get watches() {
+				return self.#watches;
+			},
+			get operationProtocols() {
+				return self.#operationProtocols;
+			},
+			get diagnostics() {
+				return self.#diagnosticsEnabled();
+			},
+			protocolGenerationSequence: () => self.#protocolGenerationSequence,
+			projectionGeneration: () => self.#projectionGeneration,
+			protocolGeneration: () => self.#protocolGeneration,
+			queryState: (key) => self.#queryState(key),
+			emitState: (key, allowFetch) => self.#emitState(key, allowFetch),
+			operationGeneration: (key) => self.#operationGeneration(key),
+			allocateIndexRevision: () => self.#allocateIndexRevision(),
+			writeCanonicalResult: (artifact, stableVariables, envelope, source, requestRevision, responseProjectionGeneration) =>
+				self.#writeCanonicalResult(
+					artifact,
+					stableVariables,
+					envelope,
+					source,
+					requestRevision,
+					responseProjectionGeneration
+				),
+			diagnosticEvent: (event) => self.#diagnosticEvent(event),
+			resumeCursors: (key) => self.#resumeCursors(key)
+		};
+		return this.#fetchLiveHostCache;
+	}
+
+	#protocolHost(): ProtocolHost {
+		if (this.#protocolHostCache !== undefined) return this.#protocolHostCache;
+		const self = this;
+		this.#protocolHostCache = {
+			get engine() {
+				return self.#engine;
+			},
+			get queryStates() {
+				return self.#queryStates;
+			},
+			get operationProtocols() {
+				return self.#operationProtocols;
+			},
+			get operationGenerations() {
+				return self.#operationGenerations;
+			},
+			get recordClocks() {
+				return self.#recordClocks;
+			},
+			get recordKeysByScope() {
+				return self.#recordKeysByScope;
+			},
+			get projectedRecordFences() {
+				return self.#projectedRecordFences;
+			},
+			get anonymousRecordClocks() {
+				return self.#anonymousRecordClocks;
+			},
+			get optimisticReceipts() {
+				return self.#optimisticReceipts;
+			},
+			get diagnosticLayers() {
+				return self.#diagnosticLayers;
+			},
+			get indexPlanRegistrations() {
+				return self.#indexPlanRegistrations;
+			},
+			get renderedOperations() {
+				return self.#renderedOperations;
+			},
+			get readOperationKeys() {
+				return self.#readOperationKeys;
+			},
+			get watchRenderCounts() {
+				return self.#watchRenderCounts;
+			},
+			get watches() {
+				return self.#watches;
+			},
+			get diagnostics() {
+				return self.#diagnosticsEnabled();
+			},
+			getProtocolGeneration: () => self.#protocolGeneration,
+			setProtocolGeneration: (value) => {
+				self.#protocolGeneration = value;
+			},
+			getProtocolGenerationSequence: () => self.#protocolGenerationSequence,
+			bumpProtocolGenerationSequence: () => {
+				self.#protocolGenerationSequence += 1;
+			},
+			getTrustedPresets: () => self.#trustedPresets,
+			setTrustedPresets: (value) => {
+				self.#trustedPresets = value;
+			},
+			getCommandAuthorityContract: () => self.#commandAuthorityContract,
+			setProjectionGeneration: (value) => {
+				self.#projectionGeneration = value;
+			},
+			setNextIndexRevision: (value) => {
+				self.#nextIndexRevision = value;
+			},
+			setDiagnosticLayerSequence: (value) => {
+				self.#diagnosticLayerSequence = value;
+			},
+			clearIndexMaintenance: () => {
+				self.#indexMaintenance.clear();
+			},
+			abortAuthorization: () => {
+				self.#authorizationAbort.abort();
+				self.#authorizationAbort = new AbortController();
+			},
+			closeActiveTransports: () => self.#closeActiveTransports(),
+			syncDiagnostics: () => self.#syncDiagnostics(),
+			emitState: (key, allowFetch) => self.#emitState(key, allowFetch),
+			diagnosticEvent: (event) => self.#diagnosticEvent(event),
+			rememberRenderedOperation: (key, artifact, variables, source) =>
+				self.#rememberRenderedOperation(key, artifact, variables, source)
+		};
+		return this.#protocolHostCache;
+	}
+
+	#optimisticHost(): OptimisticHost {
+		if (this.#optimisticHostCache !== undefined) return this.#optimisticHostCache;
+		const self = this;
+		this.#optimisticHostCache = {
+			get engine() {
+				return self.#engine;
+			},
+			get optimisticReceipts() {
+				return self.#optimisticReceipts;
+			},
+			get diagnosticLayers() {
+				return self.#diagnosticLayers;
+			},
+			get diagnostics() {
+				return self.#diagnosticsEnabled();
+			},
+			getDiagnosticLayerSequence: () => self.#diagnosticLayerSequence,
+			setDiagnosticLayerSequence: (value) => {
+				self.#diagnosticLayerSequence = value;
+			},
+			diagnosticEvent: (event) => self.#diagnosticEvent(event),
+			syncDiagnostics: () => self.#syncDiagnostics(),
+			retireDiagnosticLayer: (id, action, receiptState, receipt) =>
+				self.#retireDiagnosticLayer(id, action, receiptState, receipt)
+		};
+		return this.#optimisticHostCache;
+	}
+
+	#hydrationHost(): HydrationHost {
+		if (this.#hydrationHostCache !== undefined) return this.#hydrationHostCache;
+		const self = this;
+		this.#hydrationHostCache = {
+			get engine() {
+				return self.#engine;
+			},
+			get operationProtocols() {
+				return self.#operationProtocols;
+			},
+			get operationGenerations() {
+				return self.#operationGenerations;
+			},
+			get recordClocks() {
+				return self.#recordClocks;
+			},
+			get recordKeysByScope() {
+				return self.#recordKeysByScope;
+			},
+			get anonymousRecordClocks() {
+				return self.#anonymousRecordClocks;
+			},
+			get optimisticReceipts() {
+				return self.#optimisticReceipts;
+			},
+			get diagnosticLayers() {
+				return self.#diagnosticLayers;
+			},
+			get renderedOperations() {
+				return self.#renderedOperations;
+			},
+			get readOperationKeys() {
+				return self.#readOperationKeys;
+			},
+			get watchRenderCounts() {
+				return self.#watchRenderCounts;
+			},
+			get indexPlanRegistrations() {
+				return self.#indexPlanRegistrations;
+			},
+			get queryStates() {
+				return self.#queryStates;
+			},
+			get diagnostics() {
+				return self.#diagnosticsEnabled();
+			},
+			getProtocolGeneration: () => self.#protocolGeneration,
+			setProtocolGeneration: (value) => {
+				self.#protocolGeneration = value;
+			},
+			getProtocolGenerationSequence: () => self.#protocolGenerationSequence,
+			getTrustedPresets: () => self.#trustedPresets,
+			setTrustedPresets: (value) => {
+				self.#trustedPresets = value;
+			},
+			getNextIndexRevision: () => self.#nextIndexRevision,
+			setNextIndexRevision: (value) => {
+				self.#nextIndexRevision = value;
+			},
+			getArtifactBinding: () => self.#artifactBinding,
+			setArtifactBinding: (value) => {
+				self.#artifactBinding = value;
+			},
+			getCommandAuthorityContract: () => self.#commandAuthorityContract,
+			setDiagnosticLayerSequence: (value) => {
+				self.#diagnosticLayerSequence = value;
+			},
+			operationGeneration: (key) => self.#operationGeneration(key),
+			closeActiveTransports: () => self.#closeActiveTransports(),
+			closeAuthorizationGeneration: () => self.#closeAuthorizationGeneration(),
+			resumeLiveWatches: () => self.#resumeLiveWatches(),
+			syncDiagnostics: () => self.#syncDiagnostics(),
+			diagnosticEvent: (event) => self.#diagnosticEvent(event),
+			refreshIndexMaintenance: () => self.#refreshIndexMaintenance(),
+			finishDehydration: () => self.#finishDehydration()
+		};
+		return this.#hydrationHostCache;
+	}
+
+	get scope(): ReplicaAuthoritativeScope | undefined {
+		const scope = this.#protocolGeneration;
+		return scope === undefined
+			? undefined
+			: Object.freeze({
+					protocolVersion: scope.protocolVersion,
+					schemaHash: scope.schemaHash,
+					cacheScope: scope.cacheScope
+				});
+	}
+
+	get authorizationGeneration(): number {
+		return this.#protocolGenerationSequence;
+	}
+
+	[replicaCommandAuthority](
+		contract: ReplicaCommandSurfaceContract
+	): ReplicaCommandAuthorityRegistration {
+		const next = validatedCommandAuthorityContract(contract);
+		const current = this.#commandAuthorityContract;
+		if (current !== undefined && current.fingerprint !== next.fingerprint) {
+			throw new TypeError(
+				'command inventory does not match the active replica client surface'
+			);
+		}
+
+		const binding = this.#artifactBinding;
+		if (binding === undefined) {
+			this.#artifactBinding = Object.freeze({
+				version: 1,
+				schemaHash: next.schemaHash,
+				surfaceIdentity: next.surfaceIdentity,
+				trustedPresets: next.trustedPresets
+			});
+		} else if (
+			binding.version !== 1 ||
+			binding.schemaHash !== next.schemaHash ||
+			(
+				binding.surfaceIdentity !== undefined &&
+				binding.surfaceIdentity !== next.surfaceIdentity
+			) ||
+			(
+				binding.trustedPresets !== undefined &&
+				trustedPresetDescriptorFingerprint(binding.trustedPresets) !==
+					trustedPresetDescriptorFingerprint(next.trustedPresets)
+			)
+		) {
+			throw new TypeError(
+				'command inventory does not match the active replica client surface'
+			);
+		} else if (
+			binding.surfaceIdentity === undefined ||
+			binding.trustedPresets === undefined
+		) {
+			this.#artifactBinding = Object.freeze({
+				...binding,
+				...(binding.surfaceIdentity === undefined
+					? { surfaceIdentity: next.surfaceIdentity }
+					: {}),
+				...(binding.trustedPresets === undefined
+					? { trustedPresets: next.trustedPresets }
+					: {})
+			});
+		}
+
+		if (this.#protocolGeneration !== undefined) {
+			try {
+				matchReplicaTrustedPresetInventory(
+					next.trustedPresets,
+					this.#trustedPresets
+				);
+			} catch (error) {
+				this.#purgeProtocolGeneration();
+				throw error;
+			}
+		}
+		this.#commandAuthorityContract = next;
+
+		let active = true;
+		const read = (): ReplicaCommandAuthoritySnapshot => {
+			if (!active) {
+				throw new TypeError('replica command authority registration is disposed');
+			}
+			return Object.freeze({
+				generation: this.#protocolGenerationSequence,
+				scope: this.scope,
+				trustedPresets: this.#trustedPresets,
+				signal: this.#authorizationAbort.signal
+			});
+		};
+		return Object.freeze({
+			read,
+			dispose(): void {
+				active = false;
+			}
+		});
+	}
+
+	[replicaResultObservation](
+		observer: (envelope: ReplicaResultEnvelope<unknown>) => void
+	): ReplicaResultObservationRegistration {
+		if (typeof observer !== 'function') {
+			throw new TypeError('replica result observer must be a function');
+		}
+		this.#resultObservers.add(observer);
+		let active = true;
+		return Object.freeze({
+			dispose: (): void => {
+				if (!active) return;
+				active = false;
+				this.#resultObservers.delete(observer);
+			}
+		});
+	}
+
+	[replicaCommandDirectProjection](
+		commandId: string,
+		projection: ReplicaCommandDirectProjection
+	): void {
+		const { model, identity, evidence, fields } = projection;
+		if (evidence.model !== model.id || evidence.tombstone) {
+			protocolInvalid('extensions.distributed.command.records');
+		}
+		const recordKey = replicaRecordKey(model, identity);
+		const pendingRecordClocks = new Map<string, RecordProtocolClock>();
+		const pendingRecordScopes = new Map<DistributedOpaqueString, string>();
+		const pendingAnonymousRecordClocks = new Map<
+			DistributedOpaqueString,
+			AnonymousRecordProtocolClock
+		>();
+		const consumedAnonymousRecordClocks = new Set<DistributedOpaqueString>();
+		const apply = this.#resolveRecordEvidence(
+			recordKey,
+			evidence,
+			pendingRecordClocks,
+			pendingRecordScopes,
+			pendingAnonymousRecordClocks,
+			consumedAnonymousRecordClocks
+		);
+
+		this.confirmOptimisticLayer(commandId, (writer) => {
+			if (!apply) return false;
+			return writer.writeRecord(model, identity, evidence.revision, {
+				incarnation: evidence.incarnation,
+				fields
+			});
+		});
+
+		for (const [key, clock] of pendingRecordClocks) {
+			this.#recordClocks.set(key, clock);
+			this.#recordKeysByScope.set(clock.scopeToken, key);
+		}
+		for (const [scopeToken, key] of pendingRecordScopes) {
+			this.#recordKeysByScope.set(scopeToken, key);
+		}
+		for (const [scopeToken, clock] of pendingAnonymousRecordClocks) {
+			if (!consumedAnonymousRecordClocks.has(scopeToken)) {
+				this.#anonymousRecordClocks.set(scopeToken, clock);
+			}
+		}
+		for (const scopeToken of consumedAnonymousRecordClocks) {
+			this.#anonymousRecordClocks.delete(scopeToken);
+		}
+		if (apply) {
+			this.#projectionGeneration += 1;
+			/*
+			 * The command result is authoritative before an asynchronous read
+			 * model necessarily catches up. Retain its complete row and causal
+			 * clock as a write fence until a query acknowledges it or a newer
+			 * record/tombstone supersedes it.
+			 */
+			this.#projectedRecordFences.set(
+				recordKey,
+				Object.freeze({
+					fields: Object.freeze({ ...fields }),
+					clock: Object.freeze({
+						scopeToken: evidence.scopeToken,
+						incarnation: evidence.incarnation,
+						revision: evidence.revision,
+						tombstone: false
+					}),
+					projectionGeneration: this.#projectionGeneration
+				})
+			);
+		}
+	}
+
+	read<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables
+	): ReplicaSnapshot<TData> {
+		this.#bindArtifact(artifact);
+		const stableVariables = canonicalizeOperationVariables(artifact, variables);
+		const key = operationKey(artifact, stableVariables);
+		this.#rememberRenderedOperation(key, artifact, stableVariables, 'read');
+		const materialized = this.#engine.read((reader) =>
+			materializeReplicaOperation(reader, artifact, stableVariables)
+		);
+		return snapshotFrom(materialized, this.#queryState(key));
+	}
+
+	watch<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables,
+		options: WatchReplicaOptions = {}
+	): ReplicaWatch<TData> {
+		this.#bindArtifact(artifact);
+		return new ReplicaWatchState(this, artifact, variables, options);
+	}
+
+	writeResult<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables,
+		envelope: ReplicaResultEnvelope<TData>,
+		source: ReplicaWriteSource
+	): void {
+		assertWriteSource(source);
+		this.#bindArtifact(artifact);
+		const stableVariables = canonicalizeOperationVariables(artifact, variables);
+		this.#writeCanonicalResult(artifact, stableVariables, envelope, source);
+	}
+
+	revalidate(plan: ReplicaRevalidationPlan): Promise<void> {
+		const matches = createReplicaRevalidationMatcher(plan);
+		const generation = this.#protocolGenerationSequence;
+		const active = new Map<
+			string,
+			ReplicaWatchState<unknown, GraphqlVariables>
+		>();
+		for (const [key, watches] of this.#watches) {
+			const watch = watches.values().next().value;
+			if (watch !== undefined && matches(watch.artifact)) {
+				active.set(key, watch);
+			}
+		}
+		/*
+		 * A command-status observation may arrive while an older query is
+		 * already in flight. Drain that request first; the authoritative
+		 * revalidation below must start after the command fence.
+		 */
+		const prior = [...active.keys()].flatMap((key) => {
+			const request = this.#inFlight.get(key);
+			return request === undefined ? [] : [request];
+		});
+		return Promise.all(prior)
+			.then(() => {
+				if (this.#protocolGenerationSequence !== generation) return [];
+
+				/*
+				 * Stale every rendered matching root before fetching. This both
+				 * starts active watches through their normal coordinator and
+				 * leaves inactive SSR/read consumers fail-closed until a future
+				 * watch can refresh them.
+				 */
+				const rootKeys = new Set<string>();
+				for (const rendered of this.#renderedOperations.values()) {
+					if (!matches(rendered.artifact)) continue;
+					for (const root of rendered.artifact.roots) {
+						rootKeys.add(
+							replicaIndexKey({
+								field: root.field,
+								arguments: resolveArguments(
+									root.arguments,
+									rendered.variables,
+									root.coverage
+								)
+							})
+						);
+					}
+				}
+				for (const key of rootKeys) {
+					this.#engine.batch((writer) =>
+						writer.markIndexStale(
+							key,
+							'command-authoritative-revalidation'
+						)
+					);
+				}
+
+				// One operation key may have several component subscribers. The
+				// existing fetch coordinator owns deduplication and response fences.
+				return [...active.values()].map((watch) =>
+					this._fetch(watch, true).then(() => watch)
+				);
+			})
+			.then((requests) => Promise.all(requests))
+			.then((watches) => {
+				if (this.#protocolGenerationSequence !== generation) return;
+				const failed = watches.some((watch) => {
+					const state = this.#queryState(watch.key);
+					/*
+					 * Revalidation proves that the authoritative HTTP response
+					 * refreshed the confirmed graph. A surviving accepted layer
+					 * may deliberately keep the visible index stale when its row
+					 * policy cannot be evaluated locally; the command runtime
+					 * retires that layer only after this proof succeeds.
+					 */
+					const confirmed = this.#engine.readConfirmed((reader) =>
+						materializeReplicaOperation(
+							reader,
+							watch.artifact,
+							watch.variables
+						)
+					);
+					return (
+						state.errors.length > 0 ||
+						!confirmed.complete ||
+						confirmed.stale
+					);
+				});
+				if (failed) {
+					throw new Error(
+						'authoritative command revalidation did not produce a complete result'
+					);
+				}
+			});
+	}
+
+	invalidateAuthorization(): void {
+		this.#purgeProtocolGeneration();
+	}
+
+	dehydrate(): ReplicaDehydratedState {
+		return dehydrateReplica(this.#hydrationHost());
+	}
+
+		hydrate(
+		state: ReplicaDehydratedState,
+		authoritativeScope: ReplicaAuthoritativeScope
+	): boolean {
+		return hydrateReplica(this.#hydrationHost(), state, authoritativeScope);
+	}
+
+	#bindArtifact<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>
+	): void {
+		const next = validatedArtifactBinding(artifact);
+		this.#validateActiveArtifactTrustedPresets(next);
+		const current = this.#artifactBinding;
+		if (current === undefined) {
+			this.#artifactBinding = Object.freeze({
+				version: next.version,
+				schemaHash: next.schemaHash,
+				surfaceIdentity: next.surfaceIdentity,
+				trustedPresets: next.trustedPresets
+			});
+			return;
+		}
+		if (
+			(
+				current.surfaceIdentity === undefined ||
+				current.trustedPresets === undefined
+			) &&
+			current.version === next.version &&
+			current.schemaHash === next.schemaHash &&
+			(
+				current.surfaceIdentity === undefined ||
+				current.surfaceIdentity === next.surfaceIdentity
+			) &&
+			(
+				current.trustedPresets === undefined ||
+				trustedPresetDescriptorFingerprint(current.trustedPresets) ===
+					trustedPresetDescriptorFingerprint(next.trustedPresets)
+			)
+		) {
+			this.#artifactBinding = Object.freeze({
+				...current,
+				surfaceIdentity: next.surfaceIdentity,
+				trustedPresets: next.trustedPresets
+			});
+			return;
+		}
+		if (
+			current.version !== next.version ||
+			current.schemaHash !== next.schemaHash ||
+			(
+				current.surfaceIdentity !== undefined &&
+				current.surfaceIdentity !== next.surfaceIdentity
+			) ||
+			(
+				current.trustedPresets !== undefined &&
+				trustedPresetDescriptorFingerprint(
+					current.trustedPresets
+				) !== trustedPresetDescriptorFingerprint(next.trustedPresets)
+			)
+		) {
+			throw new TypeError(
+				'replica artifact schema does not match the active replica binding'
+			);
+		}
+	}
+
+	#validateActiveArtifactTrustedPresets(
+		binding: ValidatedArtifactBinding
+	): void {
+		if (this.#protocolGeneration === undefined) {
+			return;
+		}
+		try {
+			matchReplicaTrustedPresetInventory(
+				binding.trustedPresets,
+				this.#trustedPresets
+			);
+		} catch (error) {
+			this.#purgeProtocolGeneration();
+			throw error;
+		}
+	}
+
+	#writeCanonicalResult<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		stableVariables: TVariables,
+		envelope: ReplicaResultEnvelope<TData>,
+		source: ReplicaWriteSource,
+		requestRevision?: string,
+		responseProjectionGeneration?: number
+	): DistributedProtocolEnvelope {
+		const extensions = parseGraphqlResponseExtensions(envelope.extensions);
+		const parsedEnvelope: ReplicaResultEnvelope<TData> = Object.freeze({
+			...envelope,
+			...(extensions === undefined ? {} : { extensions })
+		});
+		const key = operationKey(artifact, stableVariables);
+		const distributed = extensions?.distributed;
+		if (distributed === undefined) {
+			protocolInvalid('extensions.distributed');
+		}
+		const accepted = this.#writeProtocolResult(
+			key,
+			artifact,
+			stableVariables,
+			parsedEnvelope,
+			source,
+			distributed,
+			requestRevision,
+			responseProjectionGeneration
+		);
+		if (accepted) this.#notifyResultObservers(parsedEnvelope);
+		return distributed;
+	}
+
+	#writeProtocolResult<TData, TVariables extends GraphqlVariables>(
+		key: string,
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		stableVariables: TVariables,
+		envelope: ReplicaResultEnvelope<TData>,
+		source: ReplicaWriteSource,
+		distributed: DistributedProtocolEnvelope,
+		requestRevision: string | undefined,
+		responseProjectionGeneration: number | undefined
+	): boolean {
+			this.#validateProtocolBinding(artifact, distributed, source);
+			const previousProtocolGeneration = this.#protocolGeneration;
+			const nextProtocolGeneration =
+				this.#stageProtocolGeneration(distributed);
+			const nextTrustedPresets = this.#stageTrustedPresets(
+				distributed.trustedPresets,
+				nextProtocolGeneration,
+				artifact
+			);
+
+		const snapshot = distributed.snapshot;
+		const live = distributed.live;
+		if (live !== undefined && snapshot === undefined) {
+			protocolInvalid('extensions.distributed.snapshot');
+		}
+		if (
+			source === 'live' &&
+			(envelope.data !== undefined || envelope.errors !== undefined) &&
+			(snapshot === undefined || live === undefined)
+		) {
+			protocolInvalid('extensions.distributed.live');
+		}
+
+		const operation = distributed.operation;
+		if ((snapshot !== undefined || live !== undefined) && operation === undefined) {
+			protocolInvalid('extensions.distributed.operation');
+		}
+		const operationSource = protocolOperationSource(source);
+		const operationState =
+			operation === undefined
+				? undefined
+				: this.#operationProtocol(key, operation, operationSource);
+			if (snapshot === undefined || operationState === undefined) {
+				this.#applyReceiptOnly(distributed.command);
+				this.#trustedPresets = nextTrustedPresets;
+				this.#protocolGeneration = nextProtocolGeneration;
+				this.#resumeLiveWatches();
+				this.#diagnosticScopeTransition(
+					previousProtocolGeneration,
+					nextProtocolGeneration
+				);
+				this.#syncDiagnostics();
+				return true;
+		}
+
+		this.#validateLiveSnapshot(snapshot, live);
+		const unsupportedLive =
+			source === 'live' && live?.supported === false;
+		const reset = live?.reset === true;
+		const group = this.#operationProtocols.get(key)!;
+		/*
+		 * An unsupported subscription response is an authorized fallback
+		 * snapshot, not a live source. In particular, a row-filtered snapshot
+		 * has no comparable index vector, so retaining live ownership here
+		 * would reject every later query handoff. Relinquish any prior live
+		 * ownership without advancing the generation; the forced HTTP fallback
+		 * starts against the generation that remains after this frame.
+		 */
+		if (unsupportedLive && group.active === 'live') {
+			group.active = undefined;
+		}
+		const previousActiveSource = group.active;
+		const handoff =
+			previousActiveSource !== undefined &&
+			previousActiveSource !== operationSource;
+		const activeState =
+			previousActiveSource === undefined
+				? undefined
+				: group[previousActiveSource];
+		const ownDisposition = reset
+			? 'fresh'
+			: compareSnapshotToOperationState(operationState, snapshot);
+		const activeDisposition =
+			handoff && activeState !== undefined
+				? compareSnapshotToOperationState(activeState, snapshot)
+				: 'fresh';
+		const sharedDisposition = this.#sharedIndexDisposition(
+			key,
+			replicaResultIndexKeys(
+				artifact,
+				stableVariables,
+				envelope,
+				snapshot
+			),
+			snapshot,
+			requestRevision,
+			source
+		);
+		const handoffBlocked =
+			handoff &&
+			(
+				!snapshot.indexesComparable ||
+				!isComparableHandoffDisposition(ownDisposition) ||
+				!isComparableHandoffDisposition(activeDisposition)
+			);
+		let disposition: IndexDisposition = handoffBlocked
+			? !isComparableHandoffDisposition(activeDisposition)
+				? activeDisposition
+				: !isComparableHandoffDisposition(ownDisposition)
+					? ownDisposition
+					: 'incomparable'
+			: ownDisposition;
+		if (
+			!handoffBlocked &&
+			isComparableHandoffDisposition(disposition) &&
+			sharedDisposition.compared
+		) {
+			disposition =
+				sharedDisposition.disposition === 'lower'
+					? 'lower'
+					: sharedDisposition.disposition ?? disposition;
+		}
+		const sourceSwitched =
+			!unsupportedLive &&
+			!handoffBlocked &&
+			isComparableHandoffDisposition(disposition) &&
+			this.#activateOperationSource(
+				key,
+				operationSource,
+				artifact,
+				stableVariables
+			);
+		const rejectedHandoff = handoff && !sourceSwitched;
+		if (
+			snapshot.indexesComparable &&
+			(reset || ownDisposition === 'incomparable')
+		) {
+			if (rejectedHandoff) {
+				this.#resetOperationState(operationState);
+			} else {
+				this.#discardOperationSnapshot(
+					operationState,
+					artifact,
+					stableVariables
+				);
+			}
+		}
+		if (sourceSwitched && disposition !== 'incomparable') {
+			// Query and live operation hashes describe independent protocol
+			// streams. A handoff is authoritative, but must receive a fresh local
+			// index revision rather than reusing the inactive stream's revision.
+			disposition = 'fresh';
+		}
+
+		if (!snapshot.indexesComparable) {
+			if (rejectedHandoff) {
+				this.#resetOperationState(operationState);
+			} else {
+				/*
+				 * The server-authorized GraphQL payload is still an exact
+				 * replacement result. Only its partition-wide causal vector is
+				 * unavailable (most commonly because exposing that position
+				 * would leak denied-row activity). Preserve local membership,
+				 * while dropping every capability that requires comparison.
+				 */
+				this.#resetOperationCausalState(operationState);
+			}
+			disposition = rejectedHandoff
+				? 'incomparable'
+				: sharedDisposition.disposition === 'lower'
+					? 'lower'
+					: 'fresh';
+		} else if (disposition === 'incomparable') {
+			if (rejectedHandoff) {
+				this.#resetOperationState(operationState);
+			} else {
+				this.#discardOperationSnapshot(
+					operationState,
+					artifact,
+					stableVariables
+				);
+			}
+		}
+
+		const writeIndexes =
+			!rejectedHandoff &&
+			disposition !== 'lower' &&
+			disposition !== 'incomparable';
+		/*
+		 * Revision zero is the cache engine's lowest legal checkpoint. It lets
+		 * an unsupported live response fill an empty cache immediately while
+		 * guaranteeing that any HTTP request revision can replace it.
+		 */
+		const indexRevision =
+			unsupportedLive
+				? '0'
+				: writeIndexes &&
+					  (
+							sourceSwitched ||
+							sharedDisposition.disposition === 'higher'
+						)
+					? this.#allocateIndexRevision()
+					: writeIndexes &&
+						  sharedDisposition.disposition === 'equal' &&
+						  sharedDisposition.indexRevision !== undefined
+						? sharedDisposition.indexRevision
+				: snapshot.indexesComparable &&
+					  disposition === 'equal' &&
+					  operationState.indexRevision !== undefined
+					? operationState.indexRevision
+					: (requestRevision ?? this.#allocateIndexRevision());
+		const recordEvidence = prepareRecordEvidence(
+			snapshot,
+			distributed.command?.records ?? Object.freeze([])
+		);
+		const pendingRecordClocks = new Map<string, RecordProtocolClock>();
+		const pendingRecordScopes = new Map<DistributedOpaqueString, string>();
+		const pendingAnonymousRecordClocks = new Map<
+			DistributedOpaqueString,
+			AnonymousRecordProtocolClock
+		>();
+		const consumedAnonymousRecordClocks = new Set<
+			DistributedOpaqueString
+		>();
+		const pendingPathRecords = new Map<string, string>();
+		const pendingProjectedRecordFenceClears = new Map<
+			string,
+			ProjectedRecordFence
+		>();
+		const consumedRecordPaths = new Set<string>();
+		const observationsAdmissible =
+			snapshot.recordsComplete &&
+				snapshot.indexesComparable &&
+				disposition !== 'incomparable' &&
+				(disposition !== 'lower' ||
+					this.#operationProtocols.get(key)?.active ===
+						operationSource);
+		const receiptPlan = this.#planOptimisticReceipts(
+			distributed.command,
+			[
+				...(distributed.command?.observations ?? []),
+				...(observationsAdmissible ? snapshot.observations : [])
+			],
+			observationsAdmissible
+		);
+		const normalizationProtocol: ReplicaNormalizationProtocol = {
+			indexRevision,
+			writeIndexes,
+			/*
+			 * This is cache-membership completeness, not causal-vector
+			 * comparability. normalizeReplicaResult independently downgrades
+			 * GraphQL path errors and missing selected fields.
+			 */
+			indexesComplete: true,
+			allowSnapshotOnlyRecords: !snapshot.recordsComplete,
+			record: (
+				path,
+				model,
+				recordKey,
+				fields
+			): ReplicaProtocolRecordResolution | undefined => {
+				const encodedPath = responsePathKey(path);
+				const evidence = recordEvidence.byPath.get(encodedPath);
+				if (evidence === undefined) {
+					if (snapshot.recordsComplete) {
+						protocolInvalid(
+							'extensions.distributed.snapshot.records'
+						);
+					}
+					return undefined;
+				}
+				if (evidence.model !== model) {
+					protocolInvalid(
+						'extensions.distributed.snapshot.records.model'
+					);
+				}
+				if (evidence.tombstone) {
+					protocolInvalid(
+						'extensions.distributed.snapshot.records.tombstone'
+					);
+				}
+				consumedRecordPaths.add(encodedPath);
+				const projectedFence =
+					this.#projectedRecordFences.get(recordKey);
+				const projectedDisposition =
+					projectedFence === undefined
+						? undefined
+						: compareProjectedRecordFields(
+								projectedFence.fields,
+								fields
+							);
+				const projectedClockComparison =
+					projectedFence === undefined
+						? undefined
+						: compareEvidenceToProjectedFence(
+								evidence,
+								projectedFence
+							);
+				const newerPostProjectionRow =
+					projectedFence !== undefined &&
+					projectedDisposition === 'conflict' &&
+					projectedClockComparison === 1 &&
+					responseProjectionGeneration !== undefined &&
+					responseProjectionGeneration >=
+						projectedFence.projectionGeneration;
+				/*
+				 * Snapshot bodies can race: SQL may be read before a command
+				 * while response evidence is stamped after it. Conflicting
+				 * pre-command responses therefore cannot override a projected
+				 * fence, even when their evidence revision is numerically later.
+				 * A causally newer row from an HTTP request or live frame that
+				 * began after the command is an atomic supersession and may
+				 * release the fence without first echoing the projected body.
+				 */
+				if (projectedFence !== undefined) {
+					const exactEcho =
+						projectedDisposition === 'complete' &&
+						(
+							projectedClockComparison === 0 ||
+							projectedClockComparison === 1
+						);
+					const newerPartial =
+						projectedDisposition === 'partial' &&
+						projectedClockComparison === 1;
+					if (exactEcho || newerPartial || newerPostProjectionRow) {
+						pendingProjectedRecordFenceClears.set(
+							recordKey,
+							projectedFence
+						);
+					}
+				}
+				const resolution = this.#resolveRecordEvidence(
+					recordKey,
+					evidence,
+					pendingRecordClocks,
+					pendingRecordScopes,
+					pendingAnonymousRecordClocks,
+					consumedAnonymousRecordClocks,
+					projectedDisposition === 'conflict' &&
+						!newerPostProjectionRow
+				);
+				pendingPathRecords.set(encodedPath, recordKey);
+				return Object.freeze({ evidence, apply: resolution });
+			}
+		};
+
+		const state = this.#queryState(key);
+		const previousErrors = state.errors;
+		state.errors = stableErrors(previousErrors, envelope.errors ?? []);
+		let summary: ReturnType<typeof normalizeReplicaResult>;
+		try {
+			const update = (writer: BaseCacheWriter) => {
+				this.#applyTombstoneEvidence(
+					writer,
+					recordEvidence.tombstones,
+					operationState,
+					pendingRecordClocks,
+					pendingRecordScopes,
+					pendingAnonymousRecordClocks,
+					consumedAnonymousRecordClocks,
+					consumedRecordPaths,
+					pendingProjectedRecordFenceClears
+				);
+				const normalized = normalizeReplicaResult(
+					writer,
+					artifact,
+					stableVariables,
+					envelope,
+					normalizationProtocol
+				);
+				for (const path of recordEvidence.livePaths) {
+					if (!consumedRecordPaths.has(path)) {
+						protocolInvalid(
+							'extensions.distributed.snapshot.records.path'
+						);
+					}
+				}
+				this.#applyPathlessEvidence(
+					writer,
+					recordEvidence.pathless,
+					recordEvidence.byPath,
+					consumedRecordPaths,
+					pendingRecordClocks,
+					pendingRecordScopes,
+					pendingAnonymousRecordClocks,
+					consumedAnonymousRecordClocks,
+					pendingProjectedRecordFenceClears
+				);
+				return normalized;
+			};
+			summary =
+				receiptPlan.satisfied.length === 0
+					? this.#engine.batch(update)
+					: this.#engine.confirmOptimisticLayers(
+							receiptPlan.satisfied,
+							update
+						);
+		} catch (error) {
+			state.errors = previousErrors;
+			if (
+				error instanceof CacheRevisionConflictError ||
+				error instanceof DistributedProtocolError
+			) {
+				this.#discardOperationSnapshot(
+					operationState,
+					artifact,
+					stableVariables
+				);
+			}
+			this.#emitState(key, false);
+			throw error;
+		}
+
+		for (const [recordKey, clock] of pendingRecordClocks) {
+			this.#recordClocks.set(recordKey, clock);
+			this.#recordKeysByScope.set(clock.scopeToken, recordKey);
+		}
+		for (const [scopeToken, recordKey] of pendingRecordScopes) {
+			this.#recordKeysByScope.set(scopeToken, recordKey);
+		}
+		for (const [scopeToken, clock] of pendingAnonymousRecordClocks) {
+			if (!consumedAnonymousRecordClocks.has(scopeToken)) {
+				this.#anonymousRecordClocks.set(scopeToken, clock);
+			}
+		}
+		for (const scopeToken of consumedAnonymousRecordClocks) {
+			this.#anonymousRecordClocks.delete(scopeToken);
+		}
+		for (const [path, recordKey] of pendingPathRecords) {
+			operationState.pathRecords.set(path, recordKey);
+		}
+		for (const [recordKey, projectedFields] of pendingProjectedRecordFenceClears) {
+			if (this.#projectedRecordFences.get(recordKey) === projectedFields) {
+				this.#projectedRecordFences.delete(recordKey);
+			}
+		}
+		for (const [id, receipt] of receiptPlan.updates) {
+			if (receiptPlan.satisfied.includes(id)) {
+				this.#retireDiagnosticLayer(id, 'retired', 'projected', receipt);
+				this.#optimisticReceipts.delete(id);
+			} else {
+				this.#optimisticReceipts.set(id, receipt);
+				this.#engine.markOptimisticLayerAccepted(id);
+				const layer = this.#diagnosticLayers?.get(id);
+				if (layer !== undefined) {
+					this.#diagnosticLayers!.set(
+						id,
+						Object.freeze({ ...layer, state: 'accepted' as const })
+					);
+				}
+				if (this.#diagnostics !== undefined) {
+					const counts = diagnosticReceiptCounts(receipt);
+					this.#diagnosticEvent(
+						Object.freeze({
+							kind: 'receipt',
+							command: id,
+							state:
+								counts.obligations === 0
+									? ('accepted' as const)
+									: ('accepted_pending_projection' as const),
+							obligations: counts.obligations,
+							observed: counts.observed
+						})
+					);
+				}
+			}
+		}
+		if (writeIndexes) {
+			operationState.indexRevision = indexRevision;
+			for (const indexKey of summary.indexKeys) {
+				operationState.indexKeys.add(indexKey);
+			}
+			if (snapshot.indexesComparable) {
+				operationState.snapshotScope = snapshot.scopeToken;
+				operationState.indexClocks = indexClockMap(snapshot.indexes);
+				operationState.cursors = latestCursors(snapshot, live);
+			} else {
+				this.#resetOperationCausalState(operationState);
+				operationState.indexRevision = indexRevision;
+				for (const indexKey of summary.indexKeys) {
+					operationState.indexKeys.add(indexKey);
+				}
+			}
+		} else if (live?.reset === true || !snapshot.indexesComparable) {
+			operationState.cursors = Object.freeze([]);
+		}
+		if (source === 'live' && !unsupportedLive) {
+			this.#advanceOperationGeneration(key);
+		}
+			if (source !== 'live' && sourceSwitched) {
+				this.#restartLive(key);
+			}
+			this.#trustedPresets = nextTrustedPresets;
+			this.#protocolGeneration = nextProtocolGeneration;
+		this.#resumeLiveWatches();
+		this.#emitState(key, false);
+		if (this.#diagnostics !== undefined) {
+			const cache = this.#engine.extract();
+			this.#diagnosticEvent(
+				Object.freeze({
+					kind: 'normalization',
+					operation: artifact.id,
+					source,
+					records: cache.records.length,
+					indexes: summary.indexKeys.length,
+					partial:
+						summary.partial ||
+						disposition === 'lower' ||
+						disposition === 'incomparable' ||
+						rejectedHandoff
+				})
+			);
+			for (const indexKey of summary.indexKeys) {
+				const index = cache.indexes.find(
+					(candidate) => candidate.key === indexKey && !candidate.deleted
+				);
+				const staleReason = index?.metadata?.staleReason;
+				this.#diagnosticEvent(
+					Object.freeze({
+						kind: 'index-decision',
+						index: indexKey,
+						decision:
+							!writeIndexes ||
+							!snapshot.indexesComparable ||
+							disposition === 'incomparable'
+								? ('revalidate' as const)
+								: staleReason === undefined
+									? ('maintained' as const)
+									: ('stale' as const),
+						...(staleReason === undefined
+							? {}
+							: { reason: staleReason })
+					})
+				);
+			}
+			this.#diagnosticScopeTransition(
+				previousProtocolGeneration,
+				nextProtocolGeneration
+			);
+			this.#syncDiagnostics();
+		}
+		if (disposition === 'incomparable' || rejectedHandoff) return false;
+		if (disposition !== 'lower') return true;
+		// A lower index snapshot from the already-active source cannot replace
+		// membership, but it can still carry independently fenced record clocks
+		// and exact causal observations. Notify only when that transaction
+		// actually committed data or receipt progress.
+		return summary.wrote || receiptPlan.satisfied.length > 0;
+	}
+
+	#notifyResultObservers(envelope: ReplicaResultEnvelope<unknown>): void {
+		if (this.#resultObservers.size === 0) return;
+		const errors: unknown[] = [];
+		for (const observer of [...this.#resultObservers]) {
+			try {
+				observer(envelope);
+			} catch (error) {
+				errors.push(error);
+			}
+		}
+		this._reportObserverErrors(errors);
+	}
+
+	createOptimisticLayer(
+		id: string,
+		update: (writer: ReplicaOptimisticWriter) => void,
+		semanticChanges: readonly ReplicaIndexSemanticChange[] = Object.freeze([])
+	): void {
+		createOptimisticLayerOn(this.#optimisticHost(), id, update, semanticChanges);
+	}
+
+	markOptimisticLayerAccepted(
+		id: string,
+		receipt?: DistributedCommandMetadata
+	): boolean {
+		return markOptimisticLayerAcceptedOn(this.#optimisticHost(), id, receipt);
+	}
+
+	confirmOptimisticLayer<T>(
+		id: string,
+		update: (writer: ReplicaBaseWriter) => T
+	): T {
+		return confirmOptimisticLayerOn(this.#optimisticHost(), id, update);
+	}
+
+	rejectOptimisticLayer(id: string): boolean {
+		return rejectOptimisticLayerOn(this.#optimisticHost(), id);
+	}
+
+		tombstoneRecord(
+		model: ReplicaModelArtifact,
+		identity: ReplicaIdentity,
+		revision: ReplicaRevision
+	): boolean {
+		const wrote = this.#engine.batch((writer) =>
+			writer.tombstoneRecord(replicaRecordKey(model, identity), revision)
+		);
+		if (wrote) this.#syncDiagnostics();
+		return wrote;
+	}
+
+	markIndexStale(target: ReplicaIndexTarget, reason: string): boolean {
+		const key = indexKeyFromTarget(target);
+		const marked = this.#engine.batch((writer) =>
+			writer.markIndexStale(key, reason)
+		);
+		if (marked) {
+			if (this.#diagnostics !== undefined) {
+				this.#diagnosticEvent(
+					Object.freeze({
+						kind: 'index-decision',
+						index: key,
+						decision: 'stale',
+						reason
+					})
+				);
+			}
+			this.#syncDiagnostics();
+		}
+		return marked;
+	}
+
+	retainRecord(model: ReplicaModelArtifact, identity: ReplicaIdentity): void {
+		this.#engine.retain(replicaRecordKey(model, identity));
+	}
+
+	releaseRecord(model: ReplicaModelArtifact, identity: ReplicaIdentity): void {
+		this.#engine.release(replicaRecordKey(model, identity));
+	}
+
+	gc(): readonly string[] {
+		const collected = this.#engine.gc();
+		if (this.#diagnostics !== undefined) {
+			this.#diagnosticEvent(
+				Object.freeze({
+					kind: 'gc',
+					records: collected.length
+				})
+			);
+		}
+		this.#syncDiagnostics();
+		return collected;
+	}
+
+	inspectRecord(
+		model: ReplicaModelArtifact,
+		identity: ReplicaIdentity
+	): ReplicaRecordInspection | undefined {
+		const key = replicaRecordKey(model, identity);
+		return this.#engine.read((reader) => {
+			const record = reader.record(key);
+			if (!record) return undefined;
+			return Object.freeze({
+				key,
+				revision: record.revision,
+				incarnation: record.incarnation,
+				presentFields: Object.freeze(Object.keys(record.fields).sort())
+			});
+		});
+	}
+
+	inspectIndex(target: ReplicaIndexTarget): ReplicaIndexInspection | undefined {
+		const key = indexKeyFromTarget(target);
+		return this.#engine.read((reader) => {
+			const index = reader.index(key);
+			if (!index?.metadata) return undefined;
+			return Object.freeze({
+				key,
+				revision: index.revision,
+				...(index.staleRevision === undefined
+					? {}
+					: { staleRevision: index.staleRevision }),
+				records: Object.freeze([...index.records]),
+				complete: index.complete,
+				field: index.metadata.field,
+				...(index.metadata.parent === undefined
+					? {}
+					: { parent: index.metadata.parent }),
+				arguments: index.metadata.arguments,
+				coverage: index.metadata.coverage,
+				dependencies: index.metadata.dependencies,
+				...(index.metadata.staleReason === undefined
+					? {}
+					: { staleReason: index.metadata.staleReason }),
+				nullValue: index.metadata.nullValue === true
+			});
+		});
+	}
+
+	#syncDiagnostics(): void {
+		syncDiagnosticsOn(this.#diagnosticsHost());
+	}
+
+	#diagnosticEvent(event: ReplicaDiagnosticEventInput): void {
+		diagnosticEventOn(this.#diagnosticsHost(), event);
+	}
+
+	#diagnosticOperation<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>
+	): void {
+		diagnosticOperationOn(this.#diagnosticsHost(), artifact);
+	}
+
+	#diagnosticScopeTransition(
+		previous: ProtocolGeneration | undefined,
+		next: ProtocolGeneration
+	): void {
+		diagnosticScopeTransitionOn(this.#diagnosticsHost(), previous, next);
+	}
+
+	#retireDiagnosticLayer(
+		id: string,
+		action: 'retired' | 'rejected',
+		receiptState: 'projected' | 'rejected',
+		receipt?: OptimisticReceiptState
+	): void {
+		retireDiagnosticLayerOn(this.#diagnosticsHost(), id, action, receiptState, receipt);
+	}
+
+	#validateProtocolBinding<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		envelope: DistributedProtocolEnvelope,
+		source: ReplicaWriteSource
+	): void {
+		validateProtocolBindingOn(this.#protocolHost(), artifact, envelope, source);
+	}
+
+	#stageProtocolGeneration(
+		envelope: DistributedProtocolEnvelope
+	): ProtocolGeneration {
+		return stageProtocolGenerationOn(this.#protocolHost(), envelope);
+	}
+
+	#stageTrustedPresets<TData, TVariables extends GraphqlVariables>(
+		incoming: readonly DistributedTrustedPreset[],
+		nextGeneration: ProtocolGeneration,
+		artifact: ReplicaOperationArtifact<TData, TVariables>
+	): readonly DistributedTrustedPreset[] {
+		return stageTrustedPresetsOn(
+			this.#protocolHost(),
+			incoming,
+			nextGeneration,
+			artifact
+		);
+	}
+
+	#purgeProtocolGeneration(): void {
+		purgeProtocolGenerationOn(this.#protocolHost());
+	}
+
+	#closeAuthorizationGeneration(): void {
+		closeAuthorizationGenerationOn(this.#protocolHost());
+	}
+
+	#closeActiveTransports(): void {
+		closeActiveTransportsOn(this.#fetchLiveHost());
+	}
+
+	#rememberRenderedOperation<TData, TVariables extends GraphqlVariables>(
+		key: string,
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables,
+		source: 'read' | 'watch'
+	): void {
+		this.#diagnosticOperation(artifact);
+		if (!this.#indexPlanRegistrations.has(key)) {
+			const registration = this.#indexMaintenance.registerOperation(
+				artifact,
+				variables
+			);
+			this.#indexPlanRegistrations.set(key, registration);
+			try {
+				this.#refreshIndexMaintenance();
+			} catch (error) {
+				this.#indexPlanRegistrations.delete(key);
+				registration.dispose();
+				throw error;
+			}
+		}
+		this.#renderedOperations.set(
+			key,
+			Object.freeze({
+				artifact: artifact as ReplicaOperationArtifact<unknown, GraphqlVariables>,
+				variables
+			})
+		);
+		if (source === 'read') {
+			this.#readOperationKeys.add(key);
+		} else {
+			this.#watchRenderCounts.set(
+				key,
+				(this.#watchRenderCounts.get(key) ?? 0) + 1
+			);
+		}
+	}
+
+	#forgetRenderedWatch(key: string): void {
+		const count = this.#watchRenderCounts.get(key);
+		if (count === undefined) return;
+		if (count > 1) {
+			this.#watchRenderCounts.set(key, count - 1);
+			return;
+		}
+		this.#watchRenderCounts.delete(key);
+		if (!this.#readOperationKeys.has(key)) {
+			this.#renderedOperations.delete(key);
+			this.#disposeIndexPlan(key);
+		}
+	}
+
+	#finishDehydration(): void {
+		finishDehydrationOn(this.#hydrationHost());
+	}
+
+	#disposeIndexPlan(key: string): void {
+		const registration = this.#indexPlanRegistrations.get(key);
+		if (registration === undefined) return;
+		this.#indexPlanRegistrations.delete(key);
+		registration.dispose();
+		this.#refreshIndexMaintenance();
+	}
+
+	#refreshIndexMaintenance(): void {
+		this.#engine.setDerivedIndexReconciler(this.#derivedIndexReconciler);
+	}
+
+	#deriveMaintainedIndexes(
+		confirmed: CacheEngineSnapshot,
+		layers: readonly OptimisticLayerView[]
+	): readonly DerivedIndexMutation[] {
+		const snapshot = indexMaintenanceSnapshot(confirmed);
+		const indexes = new Map(snapshot.indexes.map((index) => [index.key, index]));
+		const semanticLayers = layers.map(indexSemanticLayer);
+		const mutations: DerivedIndexMutation[] = [];
+			for (const decision of this.#indexMaintenance.evaluate(
+				snapshot,
+				semanticLayers,
+				this.#trustedPresets
+			)) {
+			if (decision.kind === 'unchanged') continue;
+			if (decision.kind === 'stale') {
+				mutations.push({
+					kind: 'stale',
+					key: decision.indexKey,
+					reason: formatReplicaIndexStaleReason(decision.reason)
+				});
+				continue;
+			}
+			const index = indexes.get(decision.indexKey);
+			if (index === undefined) {
+				throw new Error(
+					`index maintenance returned an unknown index: ${decision.indexKey}`
+				);
+			}
+			mutations.push({
+				kind: 'write',
+				write: {
+					key: decision.indexKey,
+					records: decision.records,
+					complete: true,
+					metadata: index.metadata
+				}
+			});
+		}
+		return Object.freeze(mutations);
+	}
+
+	#operationProtocol(
+		key: string,
+		operation: string,
+		source: OperationProtocolSource
+	): OperationProtocolState {
+		let group = this.#operationProtocols.get(key);
+		if (group === undefined) {
+			group = {};
+			this.#operationProtocols.set(key, group);
+		}
+		const current = group[source];
+		if (current !== undefined) {
+			if (current.operation !== operation) {
+				protocolInvalid('extensions.distributed.operation');
+			}
+			return current;
+		}
+		const created: OperationProtocolState = {
+			operation,
+			indexClocks: new Map(),
+			indexKeys: new Set(),
+			pathRecords: new Map(),
+			cursors: Object.freeze([])
+		};
+		group[source] = created;
+		return created;
+	}
+
+	#activateOperationSource<TData, TVariables extends GraphqlVariables>(
+		key: string,
+		source: OperationProtocolSource,
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables
+	): boolean {
+		const group = this.#operationProtocols.get(key);
+		if (group === undefined) return false;
+		const previous = group.active;
+		if (previous === source) return false;
+		if (previous !== undefined) {
+			const discardedStates = new Set(
+				[group.query, group.live].filter(
+					(state): state is OperationProtocolState =>
+						state !== undefined
+				)
+			);
+			const revisionsByKey = new Map<string, Set<string>>();
+			for (const state of [group.query, group.live]) {
+				if (state?.indexRevision === undefined) continue;
+				for (const indexKey of state.indexKeys) {
+					let revisions = revisionsByKey.get(indexKey);
+					if (revisions === undefined) {
+						revisions = new Set();
+						revisionsByKey.set(indexKey, revisions);
+					}
+					revisions.add(state.indexRevision);
+				}
+			}
+			for (const root of artifact.roots) {
+				const indexKey = replicaIndexKey({
+					field: root.field,
+					arguments: resolveArguments(
+						root.arguments,
+						variables,
+						root.coverage
+					)
+				});
+				let revisions = revisionsByKey.get(indexKey);
+				if (revisions === undefined) {
+					revisions = new Set();
+					revisionsByKey.set(indexKey, revisions);
+				}
+				for (const state of [group.query, group.live]) {
+					if (state?.indexRevision !== undefined) {
+						revisions.add(state.indexRevision);
+					}
+				}
+			}
+			const confirmedFences = this.#confirmedIndexFences(
+				revisionsByKey.keys()
+			);
+			const ownedKeys = [...revisionsByKey].flatMap(
+				([indexKey, revisions]) => {
+					const revision = confirmedFences.get(indexKey);
+					return revision !== undefined &&
+						revisions.has(revision) &&
+						!this.#indexClaimedByAnotherOperationState(
+							indexKey,
+							revision,
+							discardedStates
+						)
+						? [indexKey]
+						: [];
+				}
+			);
+			this.#engine.discardIndexes(ownedKeys);
+		}
+		group.active = source;
+		this.#advanceOperationGeneration(key);
+		return previous !== undefined;
+	}
+
+	#operationGeneration(key: string): number {
+		return this.#operationGenerations.get(key) ?? 0;
+	}
+
+	#indexClaimedByAnotherOperationState(
+		indexKey: string,
+		revision: string,
+		excluded: ReadonlySet<OperationProtocolState>
+	): boolean {
+		for (const group of this.#operationProtocols.values()) {
+			for (const state of [group.query, group.live]) {
+				if (
+					state !== undefined &&
+					!excluded.has(state) &&
+					state.indexRevision === revision &&
+					state.indexKeys.has(indexKey)
+				) {
+					return true;
+				}
+			}
+		}
+		return false;
+	}
+
+	#confirmedIndexFences(
+		indexKeys: Iterable<string>
+	): ReadonlyMap<string, string> {
+		return this.#engine.confirmedIndexFences([...indexKeys]);
+	}
+
+	#sharedIndexDisposition(
+		currentKey: string,
+		incomingIndexKeys: ReadonlySet<string>,
+		snapshot: DistributedQuerySnapshot,
+		requestRevision: string | undefined,
+		source: ReplicaWriteSource
+	): SharedIndexDisposition {
+		if (incomingIndexKeys.size === 0) return { compared: false };
+		const confirmedRevisions =
+			this.#confirmedIndexFences(incomingIndexKeys);
+		let compared = false;
+		let lower = false;
+		let higher = false;
+		let incomparable = false;
+		let equalRevision: string | undefined;
+		let latestOwnerRevision: string | undefined;
+		for (const [key, group] of this.#operationProtocols) {
+			if (key === currentKey) continue;
+			for (const state of [group.query, group.live]) {
+				if (state?.indexRevision === undefined) continue;
+				let ownsIncomingIndex = false;
+				for (const indexKey of state.indexKeys) {
+					if (
+						incomingIndexKeys.has(indexKey) &&
+						confirmedRevisions.get(indexKey) === state.indexRevision
+					) {
+						ownsIncomingIndex = true;
+						break;
+					}
+				}
+				if (!ownsIncomingIndex) continue;
+				latestOwnerRevision =
+					latestOwnerRevision === undefined ||
+					compareCanonicalDecimalStrings(
+						state.indexRevision,
+						latestOwnerRevision
+					) > 0
+						? state.indexRevision
+						: latestOwnerRevision;
+				/*
+				 * Snapshot scope is bound to one operation plan instance and is
+				 * not a cross-artifact identity. Shared semantic indexes are
+				 * comparable through their projection/scope/position vector.
+				 */
+				const disposition =
+					!snapshot.indexesComparable
+						? 'incomparable'
+						: state.indexClocks.size === 0 ||
+							  snapshot.indexes.length === 0
+							? state.indexClocks.size === snapshot.indexes.length
+								? 'equal'
+								: 'incomparable'
+							: compareIndexVector(
+									state.indexClocks,
+									snapshot.indexes
+								);
+				if (
+					disposition === 'fresh' ||
+					disposition === 'incomparable'
+				) {
+					incomparable = true;
+					continue;
+				}
+				compared = true;
+				if (disposition === 'lower') lower = true;
+				else if (disposition === 'higher') higher = true;
+				else {
+					equalRevision =
+						equalRevision === undefined ||
+						compareCanonicalDecimalStrings(
+							state.indexRevision,
+							equalRevision
+						) > 0
+							? state.indexRevision
+							: equalRevision;
+				}
+			}
+		}
+		/*
+		 * One response is a coherent replacement graph. If its vector straddles
+		 * the owners of two shared indexes, accepting only part would fabricate
+		 * a snapshot the server never produced, so preserve the current graph.
+		 */
+		if (lower) return { compared: true, disposition: 'lower' };
+		if (incomparable) {
+			/*
+			 * A comparable sibling must not promote an incomparable membership
+			 * to response-arrival order. Fall back to request-start order for
+			 * the whole graph, and reject it atomically when that request began
+			 * before any owner it would replace. Independent live streams have
+			 * no shared request-start fence, so they cannot safely replace it;
+			 * explicit synchronous ingress retains its caller-defined order.
+			 */
+			if (requestRevision === undefined && source === 'live') {
+				return { compared: true, disposition: 'lower' };
+			}
+			if (requestRevision === undefined) return { compared: false };
+			return latestOwnerRevision !== undefined &&
+				compareCanonicalDecimalStrings(requestRevision, latestOwnerRevision) <
+					0
+				? { compared: true, disposition: 'lower' }
+				: { compared: false };
+		}
+		if (!compared) return { compared: false };
+		if (higher) return { compared: true, disposition: 'higher' };
+		return {
+			compared: true,
+			disposition: 'equal',
+			...(equalRevision === undefined
+				? {}
+				: { indexRevision: equalRevision })
+		};
+	}
+
+	#advanceOperationGeneration(key: string): void {
+		this.#operationGenerations.set(
+			key,
+			this.#operationGeneration(key) + 1
+		);
+	}
+
+	#resumeCursors(key: string): readonly DistributedLiveCursor[] {
+		const group = this.#operationProtocols.get(key);
+		if (group?.active === 'query' && group.query?.cursors.length) {
+			return group.query.cursors;
+		}
+		if (group?.active === 'live' && group.live?.cursors.length) {
+			return group.live.cursors;
+		}
+		return group?.live?.cursors.length
+			? group.live.cursors
+			: (group?.query?.cursors ?? Object.freeze([]));
+	}
+
+	#discardOperationSnapshot<TData, TVariables extends GraphqlVariables>(
+		state: OperationProtocolState,
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables
+	): void {
+		const keys = new Set(state.indexKeys);
+		for (const root of artifact.roots) {
+			keys.add(
+				replicaIndexKey({
+					field: root.field,
+					arguments: resolveArguments(
+						root.arguments,
+						variables,
+						root.coverage
+					)
+				})
+			);
+		}
+		const indexRevision = state.indexRevision;
+		const discardedStates = new Set([state]);
+		const confirmedFence = this.#confirmedIndexFences(keys);
+		const ownedKeys =
+			indexRevision === undefined
+				? []
+				: [...keys].filter(
+						(key) =>
+							confirmedFence.get(key) === indexRevision &&
+							!this.#indexClaimedByAnotherOperationState(
+								key,
+								indexRevision,
+								discardedStates
+							)
+					);
+		this.#engine.discardIndexes(ownedKeys);
+		this.#resetOperationState(state);
+	}
+
+	#resetOperationState(state: OperationProtocolState): void {
+		this.#resetOperationCausalState(state);
+		state.indexRevision = undefined;
+		state.indexKeys.clear();
+		state.pathRecords.clear();
+	}
+
+	#resetOperationCausalState(state: OperationProtocolState): void {
+		state.snapshotScope = undefined;
+		state.indexClocks = new Map();
+		state.cursors = Object.freeze([]);
+	}
+
+	#allocateIndexRevision(): string {
+		this.#nextIndexRevision = incrementCanonicalDecimal(
+			this.#nextIndexRevision
+		);
+		return this.#nextIndexRevision;
+	}
+
+	#resolveRecordEvidence(
+		recordKey: string,
+		evidence: DistributedRecordRevision,
+		pendingClocks: Map<string, RecordProtocolClock>,
+		pendingScopes: Map<DistributedOpaqueString, string>,
+		pendingAnonymousClocks: Map<
+			DistributedOpaqueString,
+			AnonymousRecordProtocolClock
+		>,
+		consumedAnonymousClocks: Set<DistributedOpaqueString>,
+		projectedConflict = false
+	): boolean {
+		if (!recordKeyMatchesModel(recordKey, evidence.model)) {
+			protocolInvalid('extensions.distributed.snapshot.records.model');
+		}
+		const scopedKey =
+			pendingScopes.get(evidence.scopeToken) ??
+			this.#recordKeysByScope.get(evidence.scopeToken);
+		if (scopedKey !== undefined && scopedKey !== recordKey) {
+			protocolInvalid('extensions.distributed.snapshot.records.scopeToken');
+		}
+		pendingScopes.set(evidence.scopeToken, recordKey);
+
+		const incoming: RecordProtocolClock = {
+			scopeToken: evidence.scopeToken,
+			incarnation: evidence.incarnation,
+			revision: evidence.revision,
+			tombstone: evidence.tombstone
+		};
+		const pending = pendingClocks.get(recordKey);
+		if (pending !== undefined) {
+			if (!sameRecordClock(pending, incoming)) {
+				protocolInvalid('extensions.distributed.snapshot.records');
+			}
+			return true;
+		}
+		let current = this.#recordClocks.get(recordKey);
+		const anonymous =
+			pendingAnonymousClocks.get(evidence.scopeToken) ??
+			this.#anonymousRecordClocks.get(evidence.scopeToken);
+		if (anonymous !== undefined) {
+			if (anonymous.model !== evidence.model) {
+				protocolInvalid(
+					'extensions.distributed.snapshot.records.model'
+				);
+			}
+			consumedAnonymousClocks.add(evidence.scopeToken);
+			if (current === undefined) {
+				current = anonymous.clock;
+			} else {
+				if (current.scopeToken !== anonymous.clock.scopeToken) {
+					protocolInvalid(
+						'extensions.distributed.snapshot.records.scopeToken'
+					);
+				}
+				const anonymousComparison = compareRecordClock(
+					anonymous.clock,
+					current
+				);
+				if (
+					anonymousComparison === 0 &&
+					anonymous.clock.tombstone !== current.tombstone
+				) {
+					protocolInvalid(
+						'extensions.distributed.snapshot.records.tombstone'
+					);
+				}
+				if (anonymousComparison > 0) current = anonymous.clock;
+			}
+		}
+		if (current === undefined) {
+			pendingClocks.set(recordKey, incoming);
+			return true;
+		}
+		if (current.scopeToken !== incoming.scopeToken) {
+			protocolInvalid('extensions.distributed.snapshot.records.scopeToken');
+		}
+		if (projectedConflict) {
+			pendingClocks.set(recordKey, current);
+			return false;
+		}
+		const comparison = compareRecordClock(incoming, current);
+		if (comparison < 0) {
+			pendingClocks.set(recordKey, current);
+			return false;
+		}
+		if (comparison === 0) {
+			if (current.tombstone !== incoming.tombstone) {
+				protocolInvalid('extensions.distributed.snapshot.records.tombstone');
+			}
+			pendingClocks.set(recordKey, incoming);
+			return true;
+		}
+		if (
+			current.tombstone &&
+			!incoming.tombstone &&
+			compareDistributedDecimal(
+				incoming.incarnation,
+				current.incarnation
+			) <= 0
+		) {
+			protocolInvalid('extensions.distributed.snapshot.records.incarnation');
+		}
+		pendingClocks.set(recordKey, incoming);
+		return true;
+	}
+
+	#retainAnonymousRecordEvidence(
+		evidence: DistributedRecordRevision,
+		pendingAnonymousClocks: Map<
+			DistributedOpaqueString,
+			AnonymousRecordProtocolClock
+		>
+	): void {
+		const incoming: AnonymousRecordProtocolClock = {
+			model: evidence.model,
+			clock: {
+				scopeToken: evidence.scopeToken,
+				incarnation: evidence.incarnation,
+				revision: evidence.revision,
+				tombstone: evidence.tombstone
+			}
+		};
+		const current =
+			pendingAnonymousClocks.get(evidence.scopeToken) ??
+			this.#anonymousRecordClocks.get(evidence.scopeToken);
+		if (current === undefined) {
+			let retained = this.#anonymousRecordClocks.size;
+			for (const scopeToken of pendingAnonymousClocks.keys()) {
+				if (!this.#anonymousRecordClocks.has(scopeToken)) retained += 1;
+			}
+			if (retained >= MAX_ANONYMOUS_RECORD_CLOCKS) {
+				protocolInvalid(
+					'extensions.distributed.snapshot.records.capacity'
+				);
+			}
+			pendingAnonymousClocks.set(evidence.scopeToken, incoming);
+			return;
+		}
+		if (current.model !== incoming.model) {
+			protocolInvalid('extensions.distributed.snapshot.records.model');
+		}
+		const comparison = compareRecordClock(
+			incoming.clock,
+			current.clock
+		);
+		if (comparison < 0) return;
+		if (comparison === 0) {
+			if (current.clock.tombstone !== incoming.clock.tombstone) {
+				protocolInvalid(
+					'extensions.distributed.snapshot.records.tombstone'
+				);
+			}
+			return;
+		}
+		if (
+			current.clock.tombstone &&
+			!incoming.clock.tombstone &&
+			compareDistributedDecimal(
+				incoming.clock.incarnation,
+				current.clock.incarnation
+			) <= 0
+		) {
+			protocolInvalid(
+				'extensions.distributed.snapshot.records.incarnation'
+			);
+		}
+		pendingAnonymousClocks.set(evidence.scopeToken, incoming);
+	}
+
+	#applyTombstoneEvidence(
+		writer: BaseCacheWriter,
+		evidenceItems: readonly DistributedRecordRevision[],
+		operation: OperationProtocolState,
+		pendingClocks: Map<string, RecordProtocolClock>,
+		pendingScopes: Map<DistributedOpaqueString, string>,
+		pendingAnonymousClocks: Map<
+			DistributedOpaqueString,
+			AnonymousRecordProtocolClock
+		>,
+		consumedAnonymousClocks: Set<DistributedOpaqueString>,
+		consumedPaths: Set<string>,
+		pendingProjectedRecordFenceClears: Map<
+			string,
+			ProjectedRecordFence
+		>
+	): void {
+		for (const evidence of evidenceItems) {
+			const encodedPath =
+				evidence.path === undefined
+					? undefined
+					: responsePathKey(evidence.path);
+			const recordKey =
+				this.#recordKeysByScope.get(evidence.scopeToken) ??
+				(encodedPath === undefined
+					? undefined
+					: operation.pathRecords.get(encodedPath));
+			if (recordKey === undefined) {
+				this.#retainAnonymousRecordEvidence(
+					evidence,
+					pendingAnonymousClocks
+				);
+				continue;
+			}
+			if (encodedPath !== undefined) consumedPaths.add(encodedPath);
+			const projectedFence =
+				this.#projectedRecordFences.get(recordKey);
+			const projectedClockComparison =
+				projectedFence === undefined
+					? undefined
+					: compareEvidenceToProjectedFence(
+							evidence,
+							projectedFence
+						);
+			if (
+				projectedFence !== undefined &&
+				projectedClockComparison === 1
+			) {
+				pendingProjectedRecordFenceClears.set(
+					recordKey,
+					projectedFence
+				);
+			}
+			if (
+				this.#resolveRecordEvidence(
+					recordKey,
+					evidence,
+					pendingClocks,
+					pendingScopes,
+					pendingAnonymousClocks,
+					consumedAnonymousClocks,
+					projectedFence !== undefined &&
+						projectedClockComparison !== 1
+				)
+			) {
+				writer.tombstoneRecord(
+					recordKey,
+					evidence.revision,
+					evidence.incarnation
+				);
+			}
+		}
+	}
+
+	#applyPathlessEvidence(
+		writer: BaseCacheWriter,
+		evidenceItems: readonly DistributedRecordRevision[],
+		pathEvidence: ReadonlyMap<string, DistributedRecordRevision>,
+		consumedPaths: ReadonlySet<string>,
+		pendingClocks: Map<string, RecordProtocolClock>,
+		pendingScopes: Map<DistributedOpaqueString, string>,
+		pendingAnonymousClocks: Map<
+			DistributedOpaqueString,
+			AnonymousRecordProtocolClock
+		>,
+		consumedAnonymousClocks: Set<DistributedOpaqueString>,
+		pendingProjectedRecordFenceClears: Map<
+			string,
+			ProjectedRecordFence
+		>
+	): void {
+		for (const evidence of evidenceItems) {
+			const recordKey =
+				pendingScopes.get(evidence.scopeToken) ??
+				this.#recordKeysByScope.get(evidence.scopeToken);
+			if (recordKey === undefined) {
+				this.#retainAnonymousRecordEvidence(
+					evidence,
+					pendingAnonymousClocks
+				);
+				continue;
+			}
+			if (!recordKeyMatchesModel(recordKey, evidence.model)) {
+				protocolInvalid(
+					'extensions.distributed.snapshot.records.model'
+				);
+			}
+			let certifiedByPath = false;
+			for (const [path, candidate] of pathEvidence) {
+				if (
+					consumedPaths.has(path) &&
+					candidate.scopeToken === evidence.scopeToken &&
+					sameRecordRevision(candidate, evidence)
+				) {
+					certifiedByPath = true;
+					break;
+				}
+			}
+			if (certifiedByPath) continue;
+			const projectedFence =
+				this.#projectedRecordFences.get(recordKey);
+			const projectedClockComparison =
+				projectedFence === undefined
+					? undefined
+					: compareEvidenceToProjectedFence(
+							evidence,
+							projectedFence
+						);
+			if (
+				projectedFence !== undefined &&
+				projectedClockComparison === 1
+			) {
+				pendingProjectedRecordFenceClears.set(
+					recordKey,
+					projectedFence
+				);
+			}
+			if (
+				this.#resolveRecordEvidence(
+					recordKey,
+					evidence,
+					pendingClocks,
+					pendingScopes,
+					pendingAnonymousClocks,
+					consumedAnonymousClocks,
+					projectedFence !== undefined &&
+						projectedClockComparison !== 1
+				)
+			) {
+				// A change-log upsert proves only that a newer row exists. It
+				// advances the tuple fence, but cannot certify any cached field.
+				writer.discardRecord(recordKey);
+			}
+		}
+	}
+
+	#validateLiveSnapshot(
+		snapshot: DistributedQuerySnapshot,
+		live: DistributedProtocolEnvelope['live']
+	): void {
+		if (live === undefined || !live.supported) return;
+		if (!snapshot.indexesComparable) {
+			protocolInvalid(
+				'extensions.distributed.snapshot.indexesComparable'
+			);
+		}
+		const indexes = new Map(
+			snapshot.indexes.map((index) => [index.projection, index])
+		);
+		if (indexes.size !== live.cursors.length) {
+			protocolInvalid('extensions.distributed.live.cursors');
+		}
+		for (const cursor of live.cursors) {
+			const index = indexes.get(cursor.projection);
+			if (
+				index === undefined ||
+				index.position !== cursor.position ||
+				(index.resume !== undefined &&
+					index.resume.token !== cursor.token)
+			) {
+				protocolInvalid('extensions.distributed.live.cursors');
+			}
+		}
+	}
+
+	#planOptimisticReceipts(
+		command: DistributedCommandMetadata | undefined,
+		observations: readonly DistributedProjectionObservation[],
+		satisfactionAdmissible: boolean
+	): {
+		updates: Map<string, OptimisticReceiptState>;
+		satisfied: string[];
+	} {
+		return planOptimisticReceiptsOn(
+			this.#optimisticHost(),
+			command,
+			observations,
+			satisfactionAdmissible
+		);
+	}
+
+	#applyReceiptOnly(command: DistributedCommandMetadata | undefined): void {
+		applyReceiptOnlyOn(this.#optimisticHost(), command);
+	}
+
+		/** Package-internal hook used by one watched operation. */
+	_register<TData, TVariables extends GraphqlVariables>(
+		watch: ReplicaWatchState<TData, TVariables>
+	): () => void {
+		this.#rememberRenderedOperation(
+			watch.key,
+			watch.artifact,
+			watch.variables,
+			'watch'
+		);
+		let watches = this.#watches.get(watch.key);
+		if (!watches) {
+			watches = new Set();
+			this.#watches.set(
+				watch.key,
+				watches as Set<ReplicaWatchState<unknown, GraphqlVariables>>
+			);
+		}
+		watches.add(watch as ReplicaWatchState<unknown, GraphqlVariables>);
+		const unwatch = this.#engine.watch(
+			(reader) => materializeReplicaOperation(reader, watch.artifact, watch.variables),
+			(materialized) => watch._cacheChanged(materialized),
+			{ immediate: true }
+		);
+		if (watch.liveRequested) this.#retainLive(watch);
+		void this._fetch(watch, false);
+		return () => {
+			unwatch();
+			watches?.delete(watch as ReplicaWatchState<unknown, GraphqlVariables>);
+			if (watches?.size === 0) this.#watches.delete(watch.key);
+			this.#forgetRenderedWatch(watch.key);
+			if (watch.liveRequested) this.#releaseLive(watch.key);
+		};
+	}
+
+	/** Package-internal query-state lookup. */
+	_state(key: string): QueryState {
+		return this.#queryState(key);
+	}
+
+	/** Package-internal materialization for watch construction. */
+	_materialize<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables
+	): MaterializedReplicaResult<TData> {
+		return this.#engine.read((reader) =>
+			materializeReplicaOperation(reader, artifact, variables)
+		);
+	}
+
+	/** Package-internal cache-and-live coordinator. */
+	_fetch<TData, TVariables extends GraphqlVariables>(
+		watch: ReplicaWatchState<TData, TVariables>,
+		force: boolean
+	): Promise<void> {
+		return fetchWatch(this.#fetchLiveHost(), watch, force);
+	}
+
+		_reportObserverErrors(errors: unknown[]): void {
+		if (errors.length === 0) return;
+		reportSafely(
+			this.#reportObserverError,
+			new AggregateError(errors, 'replica observer delivery failed')
+		);
+	}
+
+	#queryState(key: string): QueryState {
+		let state = this.#queryStates.get(key);
+		if (!state) {
+			state = { fetching: false, errors: EMPTY_ERRORS, live: 'off' };
+			this.#queryStates.set(key, state);
+		}
+		return state;
+	}
+
+	#emitState(key: string, allowFetch: boolean): void {
+		emitWatchState(this.#fetchLiveHost(), key, allowFetch);
+	}
+
+	#retainLive<TData, TVariables extends GraphqlVariables>(
+		watch: ReplicaWatchState<TData, TVariables>
+	): void {
+		retainLiveOn(this.#fetchLiveHost(), watch);
+	}
+
+	#restartLive(key: string): void {
+		restartLiveOn(this.#fetchLiveHost(), key);
+	}
+
+	#resumeLiveWatches(): void {
+		resumeLiveWatchesOn(this.#fetchLiveHost());
+	}
+
+	#releaseLive(key: string): void {
+		releaseLiveOn(this.#fetchLiveHost(), key);
+	}
+}
diff --git a/js/src/replica/distributed-replica/index.ts b/js/src/replica/distributed-replica/index.ts
new file mode 100644
index 00000000..fcef3cea
--- /dev/null
+++ b/js/src/replica/distributed-replica/index.ts
@@ -0,0 +1,11 @@
+import type {
+	DistributedReplica as DistributedReplicaApi,
+	DistributedReplicaOptions
+} from '../types.js';
+import { DistributedReplicaImpl } from './impl.js';
+
+export function createDistributedReplica(
+	options: DistributedReplicaOptions = {}
+): DistributedReplicaApi {
+	return new DistributedReplicaImpl(options);
+}
diff --git a/js/src/replica/distributed-replica/optimistic.ts b/js/src/replica/distributed-replica/optimistic.ts
new file mode 100644
index 00000000..53c51fab
--- /dev/null
+++ b/js/src/replica/distributed-replica/optimistic.ts
@@ -0,0 +1,332 @@
+import {
+	type CacheIndexMetadata,
+	type CacheValue,
+	type OptimisticCacheWriter,
+	type RecordLink
+} from '../../internal/cache-engine.js';
+import type {
+	DistributedCommandMetadata,
+	DistributedOpaqueString
+} from '../../protocol.js';
+
+import { cloneJsonValue, replicaRecordKey } from '../identity.js';
+import type { ReplicaIndexSemanticChange } from '../index-maintenance.js';
+import type {
+	ReplicaIdentity,
+	ReplicaIndexTarget,
+	ReplicaModelArtifact,
+	ReplicaOptimisticWriter,
+	ReplicaRecordPatch
+} from '../types.js';
+import { protocolInvalid } from './clocks.js';
+import { indexKeyFromTarget, metadataFromTarget } from './helpers.js';
+import type {
+	CapturedReplicaOptimisticOperation,
+	CapturedReplicaOptimisticUpdate,
+	OptimisticReceiptState
+} from './types.js';
+
+export function optimisticReceiptState(
+	command: DistributedCommandMetadata
+): OptimisticReceiptState {
+	const expectations = new Map<string, true>();
+	for (const expectation of command.expects) {
+		const key = expectationKey(expectation);
+		if (expectations.has(key)) {
+			protocolInvalid('extensions.distributed.command.expects');
+		}
+		expectations.set(key, true);
+	}
+	const observed = new Set<string>();
+	for (const observation of command.observations) {
+		if (observation.causationId !== command.causationId) {
+			protocolInvalid('extensions.distributed.command.observations');
+		}
+		const key = expectationKey(observation);
+		if (!expectations.has(key)) {
+			protocolInvalid('extensions.distributed.command.observations');
+		}
+		observed.add(key);
+	}
+	return {
+		causationId: command.causationId,
+		expectations,
+		observed
+	};
+}
+
+export function cloneOptimisticReceipt(
+	receipt: OptimisticReceiptState
+): OptimisticReceiptState {
+	return {
+		causationId: receipt.causationId,
+		expectations: new Map(receipt.expectations),
+		observed: new Set(receipt.observed)
+	};
+}
+
+export function sameReceipt(
+	left: OptimisticReceiptState,
+	right: OptimisticReceiptState
+): boolean {
+	return (
+		left.causationId === right.causationId &&
+		left.expectations.size === right.expectations.size &&
+		[...left.expectations.keys()].every((key) =>
+			right.expectations.has(key)
+		)
+	);
+}
+
+export function diagnosticReceiptExpectations(
+	receipt: OptimisticReceiptState
+): readonly {
+	readonly projection: string;
+	readonly model: string;
+	readonly observed: boolean;
+}[] {
+	return Object.freeze(
+		[...receipt.expectations.keys()]
+			.map((key) => {
+				const parsed = JSON.parse(key) as unknown;
+				if (
+					!Array.isArray(parsed) ||
+					parsed.length !== 3 ||
+					typeof parsed[0] !== 'string' ||
+					typeof parsed[1] !== 'string'
+				) {
+					throw new TypeError('invalid internal projection expectation');
+				}
+				return Object.freeze({
+					projection: parsed[0],
+					model: parsed[1],
+					observed: receipt.observed.has(key)
+				});
+			})
+			.sort((left, right) =>
+				`${left.projection}\0${left.model}`.localeCompare(
+					`${right.projection}\0${right.model}`
+				)
+			)
+	);
+}
+
+export function diagnosticReceiptCounts(
+	receipt: OptimisticReceiptState | undefined
+): Readonly<{ obligations: number; observed: number }> {
+	return Object.freeze({
+		obligations: receipt?.expectations.size ?? 0,
+		observed: receipt?.observed.size ?? 0
+	});
+}
+
+export function expectationKey(value: {
+	readonly projection: string;
+	readonly model: string;
+	readonly scopeToken: DistributedOpaqueString;
+}): string {
+	return JSON.stringify([value.projection, value.model, value.scopeToken]);
+}
+
+export function captureReplicaOptimisticUpdate(
+	id: string,
+	update: (writer: ReplicaOptimisticWriter) => void,
+	semanticChanges: readonly ReplicaIndexSemanticChange[]
+): CapturedReplicaOptimisticUpdate {
+	if (!Array.isArray(semanticChanges)) {
+		throw new TypeError('optimistic semantic changes must be an array');
+	}
+	const suppliedChanges = cloneJsonValue(
+		semanticChanges
+	) as unknown as readonly ReplicaIndexSemanticChange[];
+	const operations: CapturedReplicaOptimisticOperation[] = [];
+	const changes: ReplicaIndexSemanticChange[] = [];
+	let active = true;
+	const assertActive = () => {
+		if (!active) throw new Error('replica optimistic writer is no longer active');
+	};
+	const writer: ReplicaOptimisticWriter = Object.freeze({
+		writeRecord(
+			model: ReplicaModelArtifact,
+			identity: ReplicaIdentity,
+			patch: ReplicaRecordPatch
+		): void {
+			assertActive();
+			const key = replicaRecordKey(model, identity);
+			const fields = cloneOptimisticFields(patch.fields);
+			const links = cloneOptimisticLinks(patch.links);
+			if (Object.keys(fields).length === 0 && Object.keys(links).length === 0) {
+				return;
+			}
+			operations.push(
+				Object.freeze({
+					kind: 'write-record' as const,
+					write: Object.freeze({ key, fields, links })
+				})
+			);
+			changes.push(
+				Object.freeze({
+					kind: 'upsert' as const,
+					model: model.id,
+					key,
+					fields
+				})
+			);
+		},
+		tombstoneRecord(
+			model: ReplicaModelArtifact,
+			identity: ReplicaIdentity
+		): void {
+			assertActive();
+			const key = replicaRecordKey(model, identity);
+			operations.push(
+				Object.freeze({ kind: 'tombstone-record' as const, key })
+			);
+			changes.push(
+				Object.freeze({
+					kind: 'delete' as const,
+					model: model.id,
+					key
+				})
+			);
+		},
+		writeIndex(target: ReplicaIndexTarget, records: readonly string[]): void {
+			assertActive();
+			if (!Array.isArray(records)) {
+				throw new TypeError('index records must be an array');
+			}
+			const metadata = cloneJsonValue(
+				metadataFromTarget(target)
+			) as unknown as CacheIndexMetadata;
+			operations.push(
+				Object.freeze({
+					kind: 'write-index' as const,
+					write: Object.freeze({
+						key: indexKeyFromTarget(target),
+						records: Object.freeze([...records]),
+						complete: target.complete ?? false,
+						metadata
+					})
+				})
+			);
+		},
+		deleteIndex(target: ReplicaIndexTarget): void {
+			assertActive();
+			operations.push(
+				Object.freeze({
+					kind: 'delete-index' as const,
+					key: indexKeyFromTarget(target)
+				})
+			);
+		}
+	});
+	try {
+		const result = update(writer);
+		assertReplicaOptimisticUpdateSynchronous(result);
+	} finally {
+		active = false;
+	}
+	changes.push(...suppliedChanges);
+	return Object.freeze({
+		operations: Object.freeze(operations),
+		context: cloneJsonValue({
+			id,
+			changes
+		}) as CacheValue
+	});
+}
+
+export function replayReplicaOptimisticUpdate(
+	writer: OptimisticCacheWriter,
+	operations: readonly CapturedReplicaOptimisticOperation[]
+): void {
+	for (const operation of operations) {
+		if (operation.kind === 'write-record') {
+			writer.writeRecord(operation.write);
+		} else if (operation.kind === 'tombstone-record') {
+			writer.tombstoneRecord(operation.key);
+		} else if (operation.kind === 'write-index') {
+			writer.writeIndex(operation.write);
+		} else {
+			writer.deleteIndex(operation.key);
+		}
+	}
+}
+
+export function cloneOptimisticFields(
+	fields: ReplicaRecordPatch['fields']
+): Readonly<Record<string, CacheValue>> {
+	if (fields === undefined) return Object.freeze({});
+	assertPlainReplicaRecord(fields, 'record fields');
+	return Object.freeze(
+		Object.fromEntries(
+			Object.entries(fields).map(([name, value]) => {
+				assertReplicaName(name, 'record field');
+				return [name, cloneJsonValue(value) as CacheValue];
+			})
+		)
+	);
+}
+
+export function cloneOptimisticLinks(
+	links: ReplicaRecordPatch['links']
+): Readonly<Record<string, RecordLink>> {
+	if (links === undefined) return Object.freeze({});
+	assertPlainReplicaRecord(links, 'record links');
+	return Object.freeze(
+		Object.fromEntries(
+			Object.entries(links).map(([name, value]) => {
+				assertReplicaName(name, 'record link');
+				if (value === null) return [name, null];
+				if (typeof value === 'string') {
+					assertReplicaName(value, 'record key');
+					return [name, value];
+				}
+				if (!Array.isArray(value)) {
+					throw new TypeError(
+						'record link must be a key, key array, or null'
+					);
+				}
+				const keys = value.map((key) => {
+					assertReplicaName(key, 'record key');
+					return key;
+				});
+				return [name, Object.freeze(keys)];
+			})
+		)
+	);
+}
+
+export function assertPlainReplicaRecord(
+	value: object,
+	description: string
+): void {
+	const prototype = Object.getPrototypeOf(value);
+	if (
+		Array.isArray(value) ||
+		(prototype !== Object.prototype && prototype !== null)
+	) {
+		throw new TypeError(`${description} must be a plain object`);
+	}
+}
+
+export function assertReplicaOptimisticLayerId(id: string): void {
+	assertReplicaName(id, 'optimistic layer id');
+}
+
+export function assertReplicaName(value: string, description: string): void {
+	if (typeof value !== 'string' || value.length === 0) {
+		throw new TypeError(`${description} must be a non-empty string`);
+	}
+}
+
+export function assertReplicaOptimisticUpdateSynchronous(result: unknown): void {
+	if (
+		result !== null &&
+		(typeof result === 'object' || typeof result === 'function') &&
+		typeof (result as { then?: unknown }).then === 'function'
+	) {
+		void Promise.resolve(result).catch(() => undefined);
+		throw new TypeError('optimistic layer update must be synchronous');
+	}
+}
diff --git a/js/src/replica/distributed-replica/types.ts b/js/src/replica/distributed-replica/types.ts
new file mode 100644
index 00000000..db59a184
--- /dev/null
+++ b/js/src/replica/distributed-replica/types.ts
@@ -0,0 +1,188 @@
+import type { GqlError, GraphqlVariables } from '../../types.js';
+import type {
+	CacheEngineSnapshot,
+	CacheValue,
+	OptimisticIndexWrite,
+	OptimisticRecordWrite
+} from '../../internal/cache-engine.js';
+import type {
+	DistributedDecimalString,
+	DistributedLiveCursor,
+	DistributedOpaqueString,
+	DistributedTrustedPreset
+} from '../../protocol.js';
+import type { ReplicaTrustedPresetDescriptor } from '../commands.js';
+import type { ValidatedReplicaOperationBinding } from '../operation-binding.js';
+import type {
+	ReplicaLiveState,
+	ReplicaOperationArtifact,
+	ReplicaValue
+} from '../types.js';
+
+export type QueryState = {
+	fetching: boolean;
+	errors: readonly GqlError[];
+	live: ReplicaLiveState;
+};
+
+export type LiveEntry = {
+	count: number;
+	unsubscribe: () => void;
+	active: boolean;
+	protocolGeneration: number;
+	operationGeneration?: number;
+};
+
+export type ProtocolGeneration = {
+	protocolVersion: 1;
+	cacheScope: DistributedOpaqueString;
+	schemaHash: string;
+};
+
+export type RenderedOperation = {
+	readonly artifact: ReplicaOperationArtifact<unknown, GraphqlVariables>;
+	readonly variables: GraphqlVariables;
+};
+
+export type SerializedOperationProtocolState = {
+	readonly operation: string;
+	readonly snapshotScope?: string;
+	readonly indexClocks: readonly (readonly [
+		string,
+		Readonly<{ scopeToken: string; position: string }>
+	])[];
+	readonly indexRevision?: string;
+	readonly indexKeys: readonly string[];
+	readonly pathRecords: readonly (readonly [string, string])[];
+	readonly cursors: readonly DistributedLiveCursor[];
+};
+
+export type SerializedOperationProtocolGroup = {
+	readonly key: string;
+	readonly query?: SerializedOperationProtocolState;
+	readonly live?: SerializedOperationProtocolState;
+	readonly active?: OperationProtocolSource;
+	readonly generation: number;
+};
+
+export type ReplicaDehydratedPayloadV1 = {
+	readonly cache: CacheEngineSnapshot;
+	readonly operations: readonly SerializedOperationProtocolGroup[];
+	readonly recordClocks: readonly (readonly [string, RecordProtocolClock])[];
+	readonly anonymousRecordClocks: readonly (readonly [
+		string,
+		AnonymousRecordProtocolClock
+	])[];
+	readonly trustedPresets: readonly DistributedTrustedPreset[];
+	readonly nextIndexRevision: string;
+};
+
+export type ParsedReplicaHydration = {
+	readonly scope: ProtocolGeneration;
+	readonly cache: CacheEngineSnapshot;
+	readonly operationProtocols: Map<string, OperationProtocolGroup>;
+	readonly operationGenerations: Map<string, number>;
+	readonly recordClocks: Map<string, RecordProtocolClock>;
+	readonly recordKeysByScope: Map<DistributedOpaqueString, string>;
+	readonly anonymousRecordClocks: Map<
+		DistributedOpaqueString,
+		AnonymousRecordProtocolClock
+	>;
+	readonly trustedPresets: readonly DistributedTrustedPreset[];
+	readonly nextIndexRevision: string;
+};
+
+export type RegisteredCommandAuthorityContract = {
+	readonly schemaHash: string;
+	readonly protocolHash: string;
+	readonly surfaceIdentity: string;
+	readonly trustedPresets: readonly ReplicaTrustedPresetDescriptor[];
+	readonly fingerprint: string;
+};
+
+export type ReplicaArtifactBinding = {
+	version: 1;
+	schemaHash: string;
+	surfaceIdentity?: string;
+	trustedPresets?: readonly ReplicaTrustedPresetDescriptor[];
+};
+
+export type ValidatedArtifactBinding = ValidatedReplicaOperationBinding;
+
+export type RecordProtocolClock = {
+	scopeToken: DistributedOpaqueString;
+	incarnation: DistributedDecimalString;
+	revision: DistributedDecimalString;
+	tombstone: boolean;
+};
+
+export type ProjectedRecordFence = {
+	readonly fields: Readonly<Record<string, ReplicaValue>>;
+	readonly clock: RecordProtocolClock;
+	readonly projectionGeneration: number;
+};
+
+export type AnonymousRecordProtocolClock = {
+	model: string;
+	clock: RecordProtocolClock;
+};
+
+export type IndexProtocolClock = {
+	scopeToken: DistributedOpaqueString;
+	position: DistributedDecimalString;
+};
+
+export type OperationProtocolState = {
+	operation: string;
+	snapshotScope?: DistributedOpaqueString;
+	indexClocks: Map<string, IndexProtocolClock>;
+	indexRevision?: string;
+	indexKeys: Set<string>;
+	pathRecords: Map<string, string>;
+	cursors: readonly DistributedLiveCursor[];
+};
+
+export type OperationProtocolSource = 'query' | 'live';
+
+export type OperationProtocolGroup = {
+	query?: OperationProtocolState;
+	live?: OperationProtocolState;
+	active?: OperationProtocolSource;
+};
+
+export type OptimisticReceiptState = {
+	causationId: DistributedOpaqueString;
+	expectations: ReadonlyMap<string, true>;
+	observed: Set<string>;
+};
+
+export type IndexDisposition = 'fresh' | 'equal' | 'higher' | 'lower' | 'incomparable';
+
+export type SharedIndexDisposition = {
+	readonly compared: boolean;
+	readonly disposition?: 'equal' | 'higher' | 'lower';
+	readonly indexRevision?: string;
+};
+
+export type CapturedReplicaOptimisticOperation =
+	| {
+			readonly kind: 'write-record';
+			readonly write: OptimisticRecordWrite;
+	  }
+	| {
+			readonly kind: 'tombstone-record';
+			readonly key: string;
+	  }
+	| {
+			readonly kind: 'write-index';
+			readonly write: OptimisticIndexWrite;
+	  }
+	| {
+			readonly kind: 'delete-index';
+			readonly key: string;
+	  };
+
+export type CapturedReplicaOptimisticUpdate = {
+	readonly operations: readonly CapturedReplicaOptimisticOperation[];
+	readonly context: CacheValue;
+};
diff --git a/js/src/replica/distributed-replica/watch.ts b/js/src/replica/distributed-replica/watch.ts
new file mode 100644
index 00000000..52026376
--- /dev/null
+++ b/js/src/replica/distributed-replica/watch.ts
@@ -0,0 +1,112 @@
+import type { GraphqlVariables } from '../../types.js';
+import { canonicalizeOperationVariables } from '../identity.js';
+import type { MaterializedReplicaResult } from '../materialize.js';
+import type {
+	ReplicaOperationArtifact,
+	ReplicaSnapshot,
+	ReplicaWatch,
+	WatchReplicaOptions
+} from '../types.js';
+import type { DistributedReplicaImpl } from './impl.js';
+import { operationKey, snapshotEqual, snapshotFrom, deepEqual } from './helpers.js';
+
+export class ReplicaWatchState<TData, TVariables extends GraphqlVariables>
+	implements ReplicaWatch<TData>
+{
+	readonly key: string;
+	readonly artifact: ReplicaOperationArtifact<TData, TVariables>;
+	readonly variables: TVariables;
+	readonly liveRequested: boolean;
+	materialized: MaterializedReplicaResult<TData>;
+	readonly #owner: DistributedReplicaImpl;
+	readonly #listeners = new Set<(snapshot: ReplicaSnapshot<TData>) => void>();
+	#snapshot: ReplicaSnapshot<TData>;
+	#identitySignature: string;
+	#destroyed = false;
+	readonly #unregister: () => void;
+
+	constructor(
+		owner: DistributedReplicaImpl,
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables,
+		options: WatchReplicaOptions
+	) {
+		this.#owner = owner;
+		this.artifact = artifact;
+		this.variables = canonicalizeOperationVariables(artifact, variables);
+		this.key = operationKey(artifact, this.variables);
+		this.liveRequested = options.live === true;
+		this.materialized = owner._materialize(artifact, this.variables);
+		this.#identitySignature = this.materialized.identitySignature;
+		this.#snapshot = snapshotFrom(this.materialized, owner._state(this.key));
+		this.#unregister = owner._register(this);
+	}
+
+	get(): ReplicaSnapshot<TData> {
+		return this.#snapshot;
+	}
+
+	subscribe(listener: (snapshot: ReplicaSnapshot<TData>) => void): () => void {
+		if (this.#destroyed) throw new Error('replica watch is destroyed');
+		if (typeof listener !== 'function') throw new TypeError('replica listener must be a function');
+		this.#listeners.add(listener);
+		try {
+			listener(this.#snapshot);
+		} catch (error) {
+			this.#listeners.delete(listener);
+			this.#owner._reportObserverErrors([error]);
+		}
+		return () => this.#listeners.delete(listener);
+	}
+
+	refresh(): Promise<void> {
+		if (this.#destroyed) return Promise.reject(new Error('replica watch is destroyed'));
+		return this.#owner._fetch(this, true);
+	}
+
+	destroy(): void {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		this.#unregister();
+		this.#listeners.clear();
+	}
+
+	_cacheChanged(materialized: MaterializedReplicaResult<TData>): void {
+		if (this.#destroyed) return;
+		this.materialized = materialized;
+		this.#sync(true);
+	}
+
+	_stateChanged(allowFetch: boolean): void {
+		if (this.#destroyed) return;
+		this.#sync(allowFetch);
+	}
+
+	#sync(allowFetch: boolean): void {
+		const state = this.#owner._state(this.key);
+		const nextRaw = snapshotFrom(this.materialized, state);
+		const keepData =
+			this.#identitySignature === this.materialized.identitySignature &&
+			deepEqual(this.#snapshot.data, nextRaw.data);
+		this.#identitySignature = this.materialized.identitySignature;
+		const next: ReplicaSnapshot<TData> = keepData
+			? (Object.freeze({
+					...nextRaw,
+					data: this.#snapshot.data
+				}) as ReplicaSnapshot<TData>)
+			: nextRaw;
+		if (!snapshotEqual(this.#snapshot, next)) {
+			this.#snapshot = next;
+			const errors: unknown[] = [];
+			for (const listener of this.#listeners) {
+				try {
+					listener(next);
+				} catch (error) {
+					errors.push(error);
+				}
+			}
+			this.#owner._reportObserverErrors(errors);
+		}
+		if (allowFetch) void this.#owner._fetch(this, false);
+	}
+}
diff --git a/js/src/replica/graphql-transport.ts b/js/src/replica/graphql-transport.ts
new file mode 100644
index 00000000..cc2f424f
--- /dev/null
+++ b/js/src/replica/graphql-transport.ts
@@ -0,0 +1,215 @@
+import { requestGraphql, type FetchLike } from '../request.js';
+import type { GqlAuth, GraphqlVariables } from '../types.js';
+import {
+	subscribe as subscribeGraphqlWs,
+	type WebSocketConstructor
+} from '../websocket.js';
+import type {
+	ReplicaCommandStatusRequest,
+	ReplicaCommandTransport,
+	ReplicaCommandTransportRequest,
+	ReplicaCommandTransportResult
+} from './command-runtime.js';
+import type {
+	ReplicaLiveObserver,
+	ReplicaResultEnvelope,
+	ReplicaTransport,
+	ReplicaTransportRequest
+} from './types.js';
+
+export type ReplicaGraphqlTransportOptions = Readonly<{
+	/** GraphQL HTTP endpoint. Same-origin paths and absolute URLs are supported. */
+	getUrl: () => string;
+	/** One injected credential source shared by HTTP, command, and WebSocket work. */
+	getAuth: () => GqlAuth | Promise<GqlAuth>;
+	/** Request-scoped SvelteKit fetch on the server, or a test/browser override. */
+	fetch?: FetchLike;
+	/** Browser/test WebSocket constructor override. */
+	webSocket?: WebSocketConstructor;
+}>;
+
+/**
+ * One concrete GraphQL transport for generated replica reads, live operations,
+ * command dispatch, and command-status recovery.
+ *
+ * The transport is intentionally framework-neutral. Framework adapters inject
+ * their request/session lifecycle but never duplicate GraphQL protocol logic.
+ */
+export type ReplicaGraphqlTransport = ReplicaTransport & ReplicaCommandTransport;
+
+export function createReplicaGraphqlTransport(
+	options: ReplicaGraphqlTransportOptions
+): ReplicaGraphqlTransport {
+	if (typeof options.getUrl !== 'function') {
+		throw new TypeError('replica GraphQL transport requires getUrl');
+	}
+	if (typeof options.getAuth !== 'function') {
+		throw new TypeError('replica GraphQL transport requires getAuth');
+	}
+
+	const execute = async (
+		document: string,
+		variables: Readonly<Record<string, unknown>>,
+		extensions: Readonly<Record<string, unknown>>,
+		signal?: AbortSignal
+	): Promise<ReplicaCommandTransportResult> => {
+		const auth = await options.getAuth();
+		const result = await requestGraphql(
+			options.getUrl(),
+			document,
+			auth,
+			variables,
+			{
+				...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+				extensions,
+				...(signal === undefined ? {} : { signal })
+			}
+		);
+		return Object.freeze({
+			...(result.data === undefined ? {} : { data: result.data }),
+			...(result.errors === undefined ? {} : { errors: result.errors }),
+			...(result.extensions === undefined
+				? {}
+				: { extensions: result.extensions }),
+			status: result.status
+		});
+	};
+
+	return Object.freeze({
+		async fetch<
+			TData = Record<string, unknown>,
+			TVariables extends GraphqlVariables = GraphqlVariables
+		>(
+			request: ReplicaTransportRequest<TData, TVariables>
+		): Promise<ReplicaResultEnvelope<TData>> {
+			const auth = await options.getAuth();
+			const result = await requestGraphql<TData, TVariables>(
+				options.getUrl(),
+				request.document,
+				auth,
+				request.variables,
+				{
+					...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+					...(request.extensions === undefined
+						? {}
+						: { extensions: request.extensions }),
+					...(request.signal === undefined
+						? {}
+						: { signal: request.signal })
+				}
+			);
+			return Object.freeze({
+				...(result.data === undefined ? {} : { data: result.data }),
+				...(result.errors === undefined ? {} : { errors: result.errors }),
+				...(result.extensions === undefined
+					? {}
+					: { extensions: result.extensions })
+			});
+		},
+
+		subscribe<
+			TData = Record<string, unknown>,
+			TVariables extends GraphqlVariables = GraphqlVariables
+		>(
+			request: ReplicaTransportRequest<TData, TVariables>,
+			observer: ReplicaLiveObserver<TData>
+		): () => void {
+			return subscribeReplicaOperation(options, request, observer);
+		},
+
+		dispatch(
+			request: ReplicaCommandTransportRequest
+		): Promise<ReplicaCommandTransportResult> {
+			return execute(
+				request.document,
+				request.variables,
+				request.extensions,
+				request.signal
+			);
+		},
+
+		status(
+			request: ReplicaCommandStatusRequest
+		): Promise<ReplicaCommandTransportResult> {
+			return execute(
+				request.document,
+				request.variables,
+				request.extensions,
+				request.signal
+			);
+		}
+	});
+}
+
+function subscribeReplicaOperation<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	options: ReplicaGraphqlTransportOptions,
+	request: ReplicaTransportRequest<TData, TVariables>,
+	observer: ReplicaLiveObserver<TData>
+): () => void {
+	let unsubscribe = (): void => undefined;
+	let closed = false;
+	const close = (): void => {
+		if (closed) return;
+		closed = true;
+		request.signal?.removeEventListener('abort', close);
+		unsubscribe();
+	};
+	const fail = (error: unknown): void => {
+		if (closed) return;
+		try {
+			observer.error(error);
+		} finally {
+			close();
+		}
+	};
+	if (request.signal?.aborted) {
+		return close;
+	}
+	request.signal?.addEventListener('abort', close, { once: true });
+
+	void Promise.resolve()
+		.then(() => options.getAuth())
+		.then((auth) => {
+			if (closed || request.signal?.aborted) return;
+			unsubscribe = subscribeGraphqlWs<TData, TVariables>(
+				request.document,
+				auth,
+				{
+					onNext: (result) => {
+						if (!closed) observer.next(result);
+					},
+					onError: fail,
+					onComplete: () => {
+						if (closed) return;
+						try {
+							observer.complete();
+						} finally {
+							close();
+						}
+					}
+				},
+				{
+					httpUrl: options.getUrl(),
+					variables: request.variables,
+					...(request.extensions === undefined
+						? {}
+						: { extensions: request.extensions }),
+					...(request.resume === undefined
+						? {}
+						: { resume: request.resume }),
+					...(options.webSocket === undefined
+						? {}
+						: { webSocket: options.webSocket })
+				}
+			);
+			if (closed || request.signal?.aborted) unsubscribe();
+		})
+		.catch((error: unknown) => {
+			fail(error);
+		});
+
+	return close;
+}
diff --git a/js/src/replica/identity.ts b/js/src/replica/identity.ts
new file mode 100644
index 00000000..7c6c41f2
--- /dev/null
+++ b/js/src/replica/identity.ts
@@ -0,0 +1,13 @@
+/** Replica identity/keys and variable codec; implementation in ./identity/. */
+export {
+	canonicalCacheValue,
+	canonicalVariables,
+	canonicalizeOperationVariables,
+	cloneJsonObject,
+	cloneJsonValue,
+	coverageFromArtifact,
+	replicaIndexKey,
+	replicaRecordKey,
+	resolveArguments,
+	resolveReplicaArgumentValue
+} from './identity/index.js';
diff --git a/js/src/replica/identity/clone.ts b/js/src/replica/identity/clone.ts
new file mode 100644
index 00000000..518ba040
--- /dev/null
+++ b/js/src/replica/identity/clone.ts
@@ -0,0 +1,64 @@
+import type { GraphqlVariables } from '../../types.js';
+import type { ReplicaValue } from '../types.js';
+import { freezeRecord } from '../../lib/freeze-record.js';
+
+export function canonicalVariables(variables: GraphqlVariables): string {
+	return canonicalCacheValue(cloneJsonObject(variables));
+}
+
+export function cloneJsonObject(
+	value: GraphqlVariables
+): Readonly<Record<string, ReplicaValue>> {
+	const entries: Array<readonly [string, ReplicaValue]> = [];
+	for (const [key, entry] of Object.entries(value)) {
+		if (entry === undefined) continue;
+		entries.push([key, cloneJsonValue(entry)]);
+	}
+	return freezeRecord(entries);
+}
+
+export function cloneJsonValue(value: unknown, ancestors = new Set<object>()): ReplicaValue {
+	if (
+		value === null ||
+		typeof value === 'string' ||
+		typeof value === 'boolean' ||
+		typeof value === 'number'
+	) {
+		if (typeof value === 'number' && !Number.isFinite(value)) {
+			throw new TypeError('replica values must contain only finite numbers');
+		}
+		return value;
+	}
+	if (typeof value !== 'object') {
+		throw new TypeError('replica values must be JSON-compatible');
+	}
+	if (ancestors.has(value)) throw new TypeError('replica values must not contain cycles');
+	ancestors.add(value);
+	let cloned: ReplicaValue;
+	if (Array.isArray(value)) {
+		cloned = Object.freeze(value.map((entry) => cloneJsonValue(entry, ancestors)));
+	} else {
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) {
+			throw new TypeError('replica objects must be plain JSON objects');
+		}
+		cloned = freezeRecord(
+			Object.entries(value).flatMap(([key, entry]) =>
+				entry === undefined ? [] : [[key, cloneJsonValue(entry, ancestors)] as const]
+			)
+		);
+	}
+	ancestors.delete(value);
+	return cloned;
+}
+
+export function canonicalCacheValue(value: ReplicaValue): string {
+	if (value === null || typeof value !== 'object') return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(canonicalCacheValue).join(',')}]`;
+	const record = value as Readonly<Record<string, ReplicaValue>>;
+	return `{${Object.keys(record)
+		.sort()
+		.map((key) => `${JSON.stringify(key)}:${canonicalCacheValue(record[key]!)}`)
+		.join(',')}}`;
+}
+
diff --git a/js/src/replica/identity/codec.ts b/js/src/replica/identity/codec.ts
new file mode 100644
index 00000000..a6a7747f
--- /dev/null
+++ b/js/src/replica/identity/codec.ts
@@ -0,0 +1,1156 @@
+import type { GraphqlVariables } from '../../types.js';
+import type {
+	ReplicaOperationArtifact,
+	ReplicaVariableCodecArtifact,
+	ReplicaVariableCodecLimits,
+	ReplicaVariableFilterInputDefinition,
+	ReplicaVariableFilterInputField,
+	ReplicaVariableInputDefinition,
+	ReplicaVariableInputRef,
+	ReplicaVariableOrderInputDefinition,
+	ReplicaValue
+} from '../types.js';
+import { validateReplicaOperationBinding } from '../operation-binding.js';
+import { compareCodeUnits } from '../../lib/compare-code-units.js';
+import { freezeRecord } from '../../lib/freeze-record.js';
+import { isPlainRecord } from '../../lib/is-plain-record.js';
+import { FILTER_OPERATORS, GRAPHQL_NAME, MAX_VARIABLE_CODEC_DEPTH } from './constants.js';
+
+export type VariableCodecRegistry = {
+	readonly limits: ReplicaVariableCodecLimits;
+	readonly variables: ReadonlyMap<string, ReplicaVariableInputRef>;
+	readonly inputs: ReadonlyMap<string, ReplicaVariableInputDefinition>;
+};
+
+/**
+ * Apply the exact compiler-owned GraphQL input coercion contract before an
+ * operation can acquire cache identity or reach a transport.
+ */
+export function canonicalizeOperationVariables<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	artifact: ReplicaOperationArtifact<TData, TVariables>,
+	variables: TVariables
+): TVariables {
+	validateReplicaOperationBinding(artifact);
+	const codec = artifact.variableCodec;
+	if (codec === undefined) {
+		throw new TypeError('protocol-v1 replica artifact requires variableCodec');
+	}
+
+	const registry = validateVariableCodec(codec);
+	const supplied = new Map(
+		inputRecordEntries(variables, 'variables').map(([name, value]) => {
+			if (!registry.variables.has(name)) {
+				variableValueInvalid(`variables.${name}`, 'unknown operation variable');
+			}
+			return [name, value] as const;
+		})
+	);
+	const canonical: Array<readonly [string, ReplicaValue]> = [];
+	for (const [name, input] of [...registry.variables].sort(([left], [right]) =>
+		compareCodeUnits(left, right)
+	)) {
+		const present = supplied.has(name) && supplied.get(name) !== undefined;
+		if (!present) {
+			if (!input.nullable) {
+				variableValueInvalid(`variables.${name}`, 'required variable is missing');
+			}
+			continue;
+		}
+		canonical.push([
+			name,
+			canonicalizeInputRef(
+				input,
+				supplied.get(name),
+				registry,
+				`variables.${name}`,
+				new Set(),
+				0
+			)
+		]);
+	}
+	return freezeRecord(canonical) as TVariables;
+}
+
+export function validateVariableCodec(codec: ReplicaVariableCodecArtifact): VariableCodecRegistry {
+	const root = artifactRecord(
+		codec,
+		'artifact.variableCodec',
+		['version', 'limits', 'variables', 'inputs']
+	);
+	if (root.version !== 1) variableCodecInvalid('artifact.variableCodec.version');
+	const rawLimits = artifactRecord(
+		root.limits,
+		'artifact.variableCodec.limits',
+		['maxDepth', 'maxBoolWidth', 'maxInList']
+	);
+	const limits: ReplicaVariableCodecLimits = {
+		maxDepth: validateCodecLimit(
+			rawLimits.maxDepth,
+			'artifact.variableCodec.limits.maxDepth'
+		),
+		maxBoolWidth: validateCodecLimit(
+			rawLimits.maxBoolWidth,
+			'artifact.variableCodec.limits.maxBoolWidth'
+		),
+		maxInList: validateCodecLimit(
+			rawLimits.maxInList,
+			'artifact.variableCodec.limits.maxInList'
+		)
+	};
+
+	const inputEntries = artifactRecordEntries(root.inputs, 'artifact.variableCodec.inputs');
+	const inputs = new Map<string, ReplicaVariableInputDefinition>();
+	for (const [name, definition] of inputEntries) {
+		assertGraphqlName(name, `artifact.variableCodec.inputs.${name}`);
+		inputs.set(name, definition as ReplicaVariableInputDefinition);
+	}
+
+	const variableEntries = artifactRecordEntries(
+		root.variables,
+		'artifact.variableCodec.variables'
+	);
+	const variables = new Map<string, ReplicaVariableInputRef>();
+	for (const [name, input] of variableEntries) {
+		assertGraphqlName(name, `artifact.variableCodec.variables.${name}`);
+		validateInputRef(
+			input,
+			`artifact.variableCodec.variables.${name}`,
+			inputs,
+			limits,
+			new Set(),
+			0
+		);
+		variables.set(name, input as ReplicaVariableInputRef);
+	}
+
+	for (const [name, definition] of inputs) {
+		validateInputDefinition(
+			definition,
+			`artifact.variableCodec.inputs.${name}`,
+			inputs,
+			new Set(),
+			0
+		);
+	}
+	return { limits, variables, inputs };
+}
+
+export function validateInputRef(
+	value: unknown,
+	path: string,
+	inputs: ReadonlyMap<string, ReplicaVariableInputDefinition>,
+	limits: ReplicaVariableCodecLimits,
+	active: Set<object>,
+	depth: number
+): void {
+	checkCodecDepth(depth, path);
+	const ref = artifactRecord(value, path);
+	withActiveArtifact(ref, active, path, () => {
+		switch (ref.kind) {
+			case 'scalar':
+				exactArtifactKeys(ref, path, [
+					'kind',
+					'scalar',
+					'codec',
+					'nullable'
+				]);
+				assertBoolean(ref.nullable, `${path}.nullable`);
+				validateScalarContract(ref.scalar, ref.codec, path);
+				return;
+			case 'enum':
+				exactArtifactKeys(ref, path, ['kind', 'name', 'values', 'nullable']);
+				assertGraphqlName(ref.name, `${path}.name`);
+				assertBoolean(ref.nullable, `${path}.nullable`);
+				validateStringInventory(ref.values, `${path}.values`);
+				return;
+			case 'input': {
+				const hasFilterBaseDepth = Object.prototype.hasOwnProperty.call(
+					ref,
+					'filterBaseDepth'
+				);
+				exactArtifactKeys(
+					ref,
+					path,
+					hasFilterBaseDepth
+						? ['kind', 'name', 'nullable', 'filterBaseDepth']
+						: ['kind', 'name', 'nullable']
+				);
+				assertGraphqlName(ref.name, `${path}.name`);
+				assertBoolean(ref.nullable, `${path}.nullable`);
+				const definition = inputs.get(ref.name);
+				if (definition === undefined) variableCodecInvalid(`${path}.name`);
+				const definitionKind = artifactRecord(
+					definition,
+					`artifact.variableCodec.inputs.${ref.name}`
+				).kind;
+				if (definitionKind === 'filter') {
+					if (!hasFilterBaseDepth) {
+						variableCodecInvalid(`${path}.filterBaseDepth`);
+					}
+					const filterBaseDepth = validateCodecLimit(
+						ref.filterBaseDepth,
+						`${path}.filterBaseDepth`
+					);
+					if (filterBaseDepth > limits.maxDepth) {
+						variableCodecInvalid(`${path}.filterBaseDepth`);
+					}
+				} else if (hasFilterBaseDepth) {
+					variableCodecInvalid(`${path}.filterBaseDepth`);
+				}
+				return;
+			}
+			case 'list': {
+				const hasMaxItems = Object.prototype.hasOwnProperty.call(ref, 'maxItems');
+				exactArtifactKeys(
+					ref,
+					path,
+					hasMaxItems
+						? ['kind', 'nullable', 'maxItems', 'item']
+						: ['kind', 'nullable', 'item']
+				);
+				assertBoolean(ref.nullable, `${path}.nullable`);
+				if (hasMaxItems) validateCodecLimit(ref.maxItems, `${path}.maxItems`);
+				validateInputRef(
+					ref.item,
+					`${path}.item`,
+					inputs,
+					limits,
+					active,
+					depth + 1
+				);
+				return;
+			}
+			default:
+				variableCodecInvalid(`${path}.kind`);
+		}
+	});
+}
+
+export function validateInputDefinition(
+	value: ReplicaVariableInputDefinition,
+	path: string,
+	inputs: ReadonlyMap<string, ReplicaVariableInputDefinition>,
+	active: Set<object>,
+	depth: number
+): void {
+	checkCodecDepth(depth, path);
+	const definition = artifactRecord(value, path);
+	withActiveArtifact(definition, active, path, () => {
+		switch (definition.kind) {
+			case 'filter':
+				exactArtifactKeys(definition, path, [
+					'kind',
+					'model',
+					'fields',
+					'relationships'
+				]);
+				assertNonemptyString(definition.model, `${path}.model`);
+				validateFilterInputDefinition(
+					definition as ReplicaVariableFilterInputDefinition,
+					path,
+					inputs,
+					active,
+					depth + 1
+				);
+				return;
+			case 'order':
+				exactArtifactKeys(definition, path, [
+					'kind',
+					'model',
+					'fields',
+					'values'
+				]);
+				assertNonemptyString(definition.model, `${path}.model`);
+				validateOrderInputDefinition(
+					definition as ReplicaVariableOrderInputDefinition,
+					path,
+					active
+				);
+				return;
+			default:
+				variableCodecInvalid(`${path}.kind`);
+		}
+	});
+}
+
+export function validateFilterInputDefinition(
+	definition: ReplicaVariableFilterInputDefinition,
+	path: string,
+	inputs: ReadonlyMap<string, ReplicaVariableInputDefinition>,
+	active: Set<object>,
+	depth: number
+): void {
+	const fields = artifactArray(definition.fields, `${path}.fields`);
+	const relationships = artifactArray(
+		definition.relationships,
+		`${path}.relationships`
+	);
+	const names = new Set(['_and', '_or', '_not']);
+	for (let index = 0; index < fields.length; index += 1) {
+		const fieldPath = `${path}.fields[${index}]`;
+		const field = artifactRecord(fields[index], fieldPath, [
+			'field',
+			'scalar',
+			'codec',
+			'nullable',
+			'operators'
+		]);
+		withActiveArtifact(field, active, fieldPath, () => {
+			assertGraphqlName(field.field, `${fieldPath}.field`);
+			if (names.has(field.field)) variableCodecInvalid(`${fieldPath}.field`);
+			names.add(field.field);
+			assertBoolean(field.nullable, `${fieldPath}.nullable`);
+			validateScalarContract(field.scalar, field.codec, fieldPath);
+			const operators = artifactArray(field.operators, `${fieldPath}.operators`);
+			if (operators.length === 0) variableCodecInvalid(`${fieldPath}.operators`);
+			const seen = new Set<string>();
+			for (let operator = 0; operator < operators.length; operator += 1) {
+				const value = operators[operator];
+				if (
+					typeof value !== 'string' ||
+					!FILTER_OPERATORS.has(value) ||
+					seen.has(value)
+				) {
+					variableCodecInvalid(`${fieldPath}.operators[${operator}]`);
+				}
+				validateFilterOperatorContract(
+					field.scalar as string,
+					value,
+					`${fieldPath}.operators[${operator}]`
+				);
+				seen.add(value);
+			}
+		});
+	}
+	for (let index = 0; index < relationships.length; index += 1) {
+		const relationshipPath = `${path}.relationships[${index}]`;
+		const relationship = artifactRecord(
+			relationships[index],
+			relationshipPath,
+			['field', 'target']
+		);
+		withActiveArtifact(relationship, active, relationshipPath, () => {
+			assertGraphqlName(relationship.field, `${relationshipPath}.field`);
+			if (names.has(relationship.field)) {
+				variableCodecInvalid(`${relationshipPath}.field`);
+			}
+			names.add(relationship.field);
+			const target = artifactRecord(
+				relationship.target,
+				`${relationshipPath}.target`
+			);
+			withActiveArtifact(target, active, `${relationshipPath}.target`, () => {
+				if (target.kind === 'opaque') {
+					exactArtifactKeys(target, `${relationshipPath}.target`, ['kind']);
+					return;
+				}
+				if (target.kind !== 'input') {
+					variableCodecInvalid(`${relationshipPath}.target.kind`);
+				}
+				exactArtifactKeys(target, `${relationshipPath}.target`, ['kind', 'name']);
+				assertGraphqlName(target.name, `${relationshipPath}.target.name`);
+				const targetDefinition = inputs.get(target.name);
+				if (
+					targetDefinition === undefined ||
+					artifactRecord(
+						targetDefinition,
+						`artifact.variableCodec.inputs.${target.name}`
+					).kind !== 'filter'
+				) {
+					variableCodecInvalid(`${relationshipPath}.target.name`);
+				}
+			});
+		});
+	}
+	checkCodecDepth(depth, path);
+}
+
+export function validateOrderInputDefinition(
+	definition: ReplicaVariableOrderInputDefinition,
+	path: string,
+	active: Set<object>
+): void {
+	const fields = artifactArray(definition.fields, `${path}.fields`);
+	if (fields.length === 0) variableCodecInvalid(`${path}.fields`);
+	const names = new Set<string>();
+	for (let index = 0; index < fields.length; index += 1) {
+		const fieldPath = `${path}.fields[${index}]`;
+		const field = artifactRecord(fields[index], fieldPath, [
+			'field',
+			'scalar',
+			'codec',
+			'nullable'
+		]);
+		withActiveArtifact(field, active, fieldPath, () => {
+			assertGraphqlName(field.field, `${fieldPath}.field`);
+			if (names.has(field.field)) variableCodecInvalid(`${fieldPath}.field`);
+			names.add(field.field);
+			assertBoolean(field.nullable, `${fieldPath}.nullable`);
+			validateScalarContract(field.scalar, field.codec, fieldPath);
+		});
+	}
+	validateStringInventory(definition.values, `${path}.values`);
+}
+
+export function canonicalizeInputRef(
+	input: ReplicaVariableInputRef,
+	value: unknown,
+	registry: VariableCodecRegistry,
+	path: string,
+	active: Set<object>,
+	depth: number
+): ReplicaValue {
+	checkValueDepth(depth, path);
+	if (input.kind === 'input') {
+		const definition = registry.inputs.get(input.name);
+		if (definition === undefined) {
+			variableCodecInvalid(`artifact.variableCodec.inputs.${input.name}`);
+		}
+		if (definition.kind === 'filter') {
+			if (input.filterBaseDepth === undefined) {
+				variableCodecInvalid(`${path}.filterBaseDepth`);
+			}
+			checkFilterDepth(input.filterBaseDepth, registry.limits, path);
+		}
+	}
+	if (value === null) {
+		if (!input.nullable) variableValueInvalid(path, 'non-null value required');
+		return null;
+	}
+	switch (input.kind) {
+		case 'scalar':
+			return canonicalizeScalar(input.scalar, input.codec, value, path);
+		case 'enum':
+			if (typeof value !== 'string' || !input.values.includes(value)) {
+				variableValueInvalid(path, `expected enum ${input.name}`);
+			}
+			return value;
+		case 'input': {
+			const definition = registry.inputs.get(input.name);
+			if (definition === undefined) {
+				variableCodecInvalid(`artifact.variableCodec.inputs.${input.name}`);
+			}
+			return canonicalizeInputDefinition(
+				definition,
+				value,
+				registry,
+				path,
+				active,
+				depth + 1,
+				input.filterBaseDepth
+			);
+		}
+		case 'list': {
+			const values = Array.isArray(value)
+				? inputArrayValues(value, path)
+				: [value];
+			if (input.maxItems !== undefined && values.length > input.maxItems) {
+				variableValueInvalid(
+					path,
+					`list contains ${values.length} items, exceeding maxItems ${input.maxItems}`
+				);
+			}
+			const tracksArray = Array.isArray(value);
+			if (tracksArray) beginValue(value, active, path);
+			try {
+				return Object.freeze(
+					values.map((entry, index) => {
+						const item = entry === undefined ? null : entry;
+						return canonicalizeInputRef(
+							input.item,
+							item,
+							registry,
+							`${path}[${index}]`,
+							active,
+							depth + 1
+						);
+					})
+				);
+			} finally {
+				if (tracksArray) active.delete(value);
+			}
+		}
+	}
+}
+
+export function canonicalizeInputDefinition(
+	definition: ReplicaVariableInputDefinition,
+	value: unknown,
+	registry: VariableCodecRegistry,
+	path: string,
+	active: Set<object>,
+	depth: number,
+	filterBaseDepth: number | undefined
+): ReplicaValue {
+	checkValueDepth(depth, path);
+	if (definition.kind === 'filter') {
+		if (filterBaseDepth === undefined) {
+			variableCodecInvalid(`${path}.filterBaseDepth`);
+		}
+		return canonicalizeFilterInput(
+			definition,
+			value,
+			registry,
+			path,
+			active,
+			depth,
+			filterBaseDepth
+		);
+	}
+	return canonicalizeOrderInput(definition, value, path, active, depth);
+}
+
+export function canonicalizeFilterInput(
+	definition: ReplicaVariableFilterInputDefinition,
+	value: unknown,
+	registry: VariableCodecRegistry,
+	path: string,
+	active: Set<object>,
+	depth: number,
+	filterDepth: number
+): ReplicaValue {
+	checkValueDepth(depth, path);
+	checkFilterDepth(filterDepth, registry.limits, path);
+	const entries = inputRecordEntries(value, path);
+	beginValue(value as object, active, path);
+	try {
+		const fields = new Map(definition.fields.map((field) => [field.field, field]));
+		const relationships = new Map(
+			definition.relationships.map((relationship) => [
+				relationship.field,
+				relationship.target
+			])
+		);
+		const canonical: Array<readonly [string, ReplicaValue]> = [];
+		for (const [field, fieldValue] of entries.sort(([left], [right]) =>
+			compareCodeUnits(left, right)
+		)) {
+			if (fieldValue === undefined) continue;
+			const fieldPath = `${path}.${field}`;
+			if (field === '_and' || field === '_or') {
+				if (fieldValue === null) {
+					canonical.push([field, null]);
+					continue;
+				}
+				const predicates = Array.isArray(fieldValue)
+					? inputArrayValues(fieldValue, fieldPath)
+					: [fieldValue];
+				if (predicates.length > registry.limits.maxBoolWidth) {
+					variableValueInvalid(
+						fieldPath,
+						`boolean list contains ${predicates.length} items, exceeding maxBoolWidth ${registry.limits.maxBoolWidth}`
+					);
+				}
+				if (Array.isArray(fieldValue)) beginValue(fieldValue, active, fieldPath);
+				try {
+					canonical.push([
+						field,
+						Object.freeze(
+							predicates.map((predicate, index) => {
+								if (predicate === null || predicate === undefined) {
+									variableValueInvalid(
+										`${fieldPath}[${index}]`,
+										'filter list items must be non-null'
+									);
+								}
+								return canonicalizeFilterInput(
+									definition,
+									predicate,
+									registry,
+									`${fieldPath}[${index}]`,
+									active,
+									depth + 1,
+									filterDepth + 1
+								);
+							})
+						)
+					]);
+				} finally {
+					if (Array.isArray(fieldValue)) active.delete(fieldValue);
+				}
+				continue;
+			}
+			if (field === '_not') {
+				const childFilterDepth = filterDepth + 1;
+				checkFilterDepth(childFilterDepth, registry.limits, fieldPath);
+				canonical.push([
+					field,
+					fieldValue === null
+						? null
+						: canonicalizeFilterInput(
+								definition,
+								fieldValue,
+								registry,
+								fieldPath,
+								active,
+								depth + 1,
+								childFilterDepth
+							)
+				]);
+				continue;
+			}
+			const comparison = fields.get(field);
+			if (comparison !== undefined) {
+				canonical.push([
+					field,
+					fieldValue === null
+						? null
+						: canonicalizeFilterComparison(
+								comparison,
+								fieldValue,
+								fieldPath,
+								active,
+								depth + 1,
+								registry.limits
+							)
+				]);
+				continue;
+			}
+			const relationship = relationships.get(field);
+			if (relationship !== undefined) {
+				const childFilterDepth = filterDepth + 1;
+				checkFilterDepth(childFilterDepth, registry.limits, fieldPath);
+				if (fieldValue === null) {
+					canonical.push([field, null]);
+				} else if (relationship.kind === 'opaque') {
+					canonical.push([
+						field,
+						cloneCanonicalJsonObject(
+							fieldValue,
+							fieldPath,
+							active,
+							depth + 1,
+							true
+						)
+					]);
+				} else {
+					const target = registry.inputs.get(relationship.name);
+					if (target?.kind !== 'filter') {
+						variableCodecInvalid(
+							`artifact.variableCodec.inputs.${relationship.name}`
+						);
+					}
+					canonical.push([
+						field,
+						canonicalizeFilterInput(
+							target,
+							fieldValue,
+							registry,
+							fieldPath,
+							active,
+							depth + 1,
+							childFilterDepth
+						)
+					]);
+				}
+				continue;
+			}
+			variableValueInvalid(fieldPath, 'unknown filter field');
+		}
+		return freezeRecord(canonical);
+	} finally {
+		active.delete(value as object);
+	}
+}
+
+export function canonicalizeFilterComparison(
+	field: ReplicaVariableFilterInputField,
+	value: unknown,
+	path: string,
+	active: Set<object>,
+	depth: number,
+	limits: ReplicaVariableCodecLimits
+): ReplicaValue {
+	checkValueDepth(depth, path);
+	const entries = inputRecordEntries(value, path);
+	beginValue(value as object, active, path);
+	try {
+		const allowed = new Set(field.operators);
+		const canonical: Array<readonly [string, ReplicaValue]> = [];
+		for (const [operator, operand] of entries.sort(([left], [right]) =>
+			compareCodeUnits(left, right)
+		)) {
+			if (operand === undefined) continue;
+			const operatorPath = `${path}.${operator}`;
+			if (!allowed.has(operator as never)) {
+				variableValueInvalid(operatorPath, 'unknown filter operator');
+			}
+			if (operator === '_in' || operator === '_nin') {
+				if (operand === null) {
+					variableValueInvalid(operatorPath, 'filter list must be non-null');
+				}
+				const values = Array.isArray(operand)
+					? inputArrayValues(operand, operatorPath)
+					: [operand];
+				if (values.length > limits.maxInList) {
+					variableValueInvalid(
+						operatorPath,
+						`filter list contains ${values.length} items, exceeding maxInList ${limits.maxInList}`
+					);
+				}
+				if (Array.isArray(operand)) beginValue(operand, active, operatorPath);
+				try {
+					canonical.push([
+						operator,
+						Object.freeze(
+							values.map((item, index) => {
+								if (item === null || item === undefined) {
+									variableValueInvalid(
+										`${operatorPath}[${index}]`,
+										'filter list items must be non-null'
+									);
+								}
+								return canonicalizeScalar(
+									field.scalar,
+									field.codec,
+									item,
+									`${operatorPath}[${index}]`
+								);
+							})
+						)
+					]);
+				} finally {
+					if (Array.isArray(operand)) active.delete(operand);
+				}
+				continue;
+			}
+			if (operand === null) {
+				canonical.push([operator, null]);
+				continue;
+			}
+			if (operator === '_is_null') {
+				if (typeof operand !== 'boolean') {
+					variableValueInvalid(operatorPath, 'expected boolean or null');
+				}
+				canonical.push([operator, operand]);
+				continue;
+			}
+			if (operator === '_like' || operator === '_ilike' || operator === '_has_key') {
+				if (typeof operand !== 'string') {
+					variableValueInvalid(operatorPath, 'expected string or null');
+				}
+				canonical.push([operator, operand]);
+				continue;
+			}
+			canonical.push([
+				operator,
+				canonicalizeScalar(field.scalar, field.codec, operand, operatorPath)
+			]);
+		}
+		return freezeRecord(canonical);
+	} finally {
+		active.delete(value as object);
+	}
+}
+
+export function canonicalizeOrderInput(
+	definition: ReplicaVariableOrderInputDefinition,
+	value: unknown,
+	path: string,
+	active: Set<object>,
+	depth: number
+): ReplicaValue {
+	checkValueDepth(depth, path);
+	const entries = inputRecordEntries(value, path).filter(
+		([, fieldValue]) => fieldValue !== undefined
+	);
+	if (entries.length !== 1) {
+		variableValueInvalid(path, 'order object must contain exactly one field');
+	}
+	const [field, direction] = entries[0]!;
+	if (!definition.fields.some((candidate) => candidate.field === field)) {
+		variableValueInvalid(`${path}.${field}`, 'unknown order field');
+	}
+	if (typeof direction !== 'string' || !definition.values.includes(direction)) {
+		variableValueInvalid(`${path}.${field}`, 'unknown order direction');
+	}
+	beginValue(value as object, active, path);
+	try {
+		return freezeRecord([[field, direction]]);
+	} finally {
+		active.delete(value as object);
+	}
+}
+
+export function canonicalizeScalar(
+	scalar: string,
+	codec: string,
+	value: unknown,
+	path: string
+): ReplicaValue {
+	switch (`${scalar}:${codec}`) {
+		case 'ID:string':
+			if (typeof value === 'string') return value;
+			if (typeof value === 'number' && Number.isSafeInteger(value)) {
+				return String(Object.is(value, -0) ? 0 : value);
+			}
+			variableValueInvalid(path, 'ID must be a string or safe integer');
+		case 'String:string':
+		case 'Timestamptz:string_unvalidated_timestamp':
+			if (typeof value !== 'string') variableValueInvalid(path, 'expected string');
+			return value;
+		case 'Bytea:base64':
+			return canonicalizeBase64(value, path);
+		case 'Boolean:boolean':
+			if (typeof value !== 'boolean') variableValueInvalid(path, 'expected boolean');
+			return value;
+		case 'Int:int32':
+			if (
+				typeof value !== 'number' ||
+				!Number.isInteger(value) ||
+				value < -2_147_483_648 ||
+				value > 2_147_483_647
+			) {
+				variableValueInvalid(path, 'expected signed 32-bit integer');
+			}
+			return Object.is(value, -0) ? 0 : value;
+		case 'Float:float64':
+			if (typeof value !== 'number' || !Number.isFinite(value)) {
+				variableValueInvalid(path, 'expected finite number');
+			}
+			return Object.is(value, -0) ? 0 : value;
+		case 'BigInt:json_number_precision_limited':
+			if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+				variableValueInvalid(path, 'expected safe integer');
+			}
+			return Object.is(value, -0) ? 0 : value;
+		case 'JSON:json':
+			return cloneCanonicalJsonValue(value, path, new Set(), 0, false);
+		default:
+			variableCodecInvalid(path);
+	}
+}
+
+export function canonicalizeBase64(value: unknown, path: string): string {
+	if (typeof value !== 'string') variableValueInvalid(path, 'expected base64 string');
+	const decode = globalThis.atob;
+	const encode = globalThis.btoa;
+	if (typeof decode !== 'function' || typeof encode !== 'function') {
+		variableValueInvalid(path, 'base64 codec is unavailable in this runtime');
+	}
+	try {
+		const canonical = encode(decode(value));
+		if (canonical !== value) {
+			variableValueInvalid(path, 'expected canonical standard base64');
+		}
+		return canonical;
+	} catch {
+		variableValueInvalid(path, 'expected canonical standard base64');
+	}
+}
+
+export function cloneCanonicalJsonObject(
+	value: unknown,
+	path: string,
+	active: Set<object>,
+	depth: number,
+	omitUndefined: boolean
+): Readonly<Record<string, ReplicaValue>> {
+	const entries = inputRecordEntries(value, path);
+	checkValueDepth(depth, path);
+	beginValue(value as object, active, path);
+	try {
+		const canonical: Array<readonly [string, ReplicaValue]> = [];
+		for (const [key, entry] of entries.sort(([left], [right]) =>
+			compareCodeUnits(left, right)
+		)) {
+			if (entry === undefined && omitUndefined) continue;
+			if (entry === undefined) variableValueInvalid(`${path}.${key}`, 'expected JSON value');
+			canonical.push([
+				key,
+				cloneCanonicalJsonValue(
+					entry,
+					`${path}.${key}`,
+					active,
+					depth + 1,
+					omitUndefined
+				)
+			]);
+		}
+		return freezeRecord(canonical);
+	} finally {
+		active.delete(value as object);
+	}
+}
+
+export function cloneCanonicalJsonValue(
+	value: unknown,
+	path: string,
+	active: Set<object>,
+	depth: number,
+	omitUndefined: boolean
+): ReplicaValue {
+	checkValueDepth(depth, path);
+	if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+		return value;
+	}
+	if (typeof value === 'number') {
+		if (!Number.isFinite(value)) variableValueInvalid(path, 'expected finite JSON number');
+		if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+			variableValueInvalid(path, 'expected safe integer or non-integer finite JSON number');
+		}
+		return Object.is(value, -0) ? 0 : value;
+	}
+	if (Array.isArray(value)) {
+		beginValue(value, active, path);
+		try {
+			return Object.freeze(
+				inputArrayValues(value, path).map((entry, index) => {
+					if (entry === undefined) {
+						variableValueInvalid(`${path}[${index}]`, 'expected JSON value');
+					}
+					return cloneCanonicalJsonValue(
+						entry,
+						`${path}[${index}]`,
+						active,
+						depth + 1,
+						omitUndefined
+					);
+				})
+			);
+		} finally {
+			active.delete(value);
+		}
+	}
+	return cloneCanonicalJsonObject(value, path, active, depth, omitUndefined);
+}
+
+export function validateScalarContract(scalar: unknown, codec: unknown, path: string): void {
+	if (
+		typeof scalar !== 'string' ||
+		typeof codec !== 'string' ||
+		![
+			'ID:string',
+			'String:string',
+			'Bytea:base64',
+			'Timestamptz:string_unvalidated_timestamp',
+			'Boolean:boolean',
+			'Int:int32',
+			'Float:float64',
+			'BigInt:json_number_precision_limited',
+			'JSON:json'
+		].includes(`${scalar}:${codec}`)
+	) {
+		variableCodecInvalid(`${path}.codec`);
+	}
+}
+
+export function validateFilterOperatorContract(
+	scalar: string,
+	operator: string,
+	path: string
+): void {
+	if (
+		(operator === '_like' || operator === '_ilike') &&
+		scalar !== 'String'
+	) {
+		variableCodecInvalid(path);
+	}
+	if (
+		(operator === '_contains' ||
+			operator === '_contained_in' ||
+			operator === '_has_key') &&
+		scalar !== 'JSON'
+	) {
+		variableCodecInvalid(path);
+	}
+}
+
+export function validateStringInventory(value: unknown, path: string): void {
+	const values = artifactArray(value, path);
+	if (values.length === 0) variableCodecInvalid(path);
+	const seen = new Set<string>();
+	for (let index = 0; index < values.length; index += 1) {
+		const entry = values[index];
+		if (
+			typeof entry !== 'string' ||
+			!GRAPHQL_NAME.test(entry) ||
+			seen.has(entry)
+		) {
+			variableCodecInvalid(`${path}[${index}]`);
+		}
+		seen.add(entry);
+	}
+}
+
+export function artifactRecord(
+	value: unknown,
+	path: string,
+	expectedKeys?: readonly string[]
+): Record<string, unknown> {
+	const entries = artifactRecordEntries(value, path);
+	const record = value as Record<string, unknown>;
+	if (expectedKeys !== undefined) exactArtifactKeys(record, path, expectedKeys, entries);
+	return record;
+}
+
+export function artifactRecordEntries(
+	value: unknown,
+	path: string
+): Array<readonly [string, unknown]> {
+	return dataRecordEntries(value, path, variableCodecInvalid);
+}
+
+export function inputRecordEntries(
+	value: unknown,
+	path: string
+): Array<readonly [string, unknown]> {
+	return dataRecordEntries(value, path, (invalidPath) =>
+		variableValueInvalid(invalidPath, 'expected plain input object')
+	);
+}
+
+export function dataRecordEntries(
+	value: unknown,
+	path: string,
+	fail: (path: string) => never
+): Array<readonly [string, unknown]> {
+	if (!isPlainRecord(value)) fail(path);
+	const entries: Array<readonly [string, unknown]> = [];
+	for (const key of Reflect.ownKeys(value)) {
+		if (typeof key !== 'string') fail(path);
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (
+			descriptor === undefined ||
+			!descriptor.enumerable ||
+			!('value' in descriptor)
+		) {
+			fail(`${path}.${key}`);
+		}
+		entries.push([key, descriptor.value]);
+	}
+	return entries;
+}
+
+export function exactArtifactKeys(
+	value: Record<string, unknown>,
+	path: string,
+	expected: readonly string[],
+	entries = artifactRecordEntries(value, path)
+): void {
+	const actual = new Set(entries.map(([key]) => key));
+	if (
+		actual.size !== expected.length ||
+		expected.some((key) => !actual.has(key))
+	) {
+		variableCodecInvalid(path);
+	}
+}
+
+export function artifactArray(value: unknown, path: string): readonly unknown[] {
+	if (!Array.isArray(value)) variableCodecInvalid(path);
+	return arrayDataValues(value, path, variableCodecInvalid);
+}
+
+export function inputArrayValues(value: readonly unknown[], path: string): readonly unknown[] {
+	return arrayDataValues(value, path, (invalidPath) =>
+		variableValueInvalid(invalidPath, 'expected dense data-only input array')
+	);
+}
+
+export function arrayDataValues(
+	value: readonly unknown[],
+	path: string,
+	fail: (path: string) => never
+): readonly unknown[] {
+	const result: unknown[] = [];
+	const indexes = new Set<string>();
+	for (let index = 0; index < value.length; index += 1) {
+		const key = String(index);
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (
+			descriptor === undefined ||
+			!descriptor.enumerable ||
+			!('value' in descriptor)
+		) {
+			fail(`${path}[${index}]`);
+		}
+		indexes.add(key);
+		result.push(descriptor.value);
+	}
+	for (const key of Reflect.ownKeys(value)) {
+		if (key === 'length' || (typeof key === 'string' && indexes.has(key))) continue;
+		fail(path);
+	}
+	return result;
+}
+
+export function withActiveArtifact(
+	value: object,
+	active: Set<object>,
+	path: string,
+	run: () => void
+): void {
+	if (active.has(value)) variableCodecInvalid(path);
+	active.add(value);
+	try {
+		run();
+	} finally {
+		active.delete(value);
+	}
+}
+
+export function beginValue(value: object, active: Set<object>, path: string): void {
+	if (active.has(value)) variableValueInvalid(path, 'input values must not contain cycles');
+	active.add(value);
+}
+
+export function assertGraphqlName(value: unknown, path: string): asserts value is string {
+	if (typeof value !== 'string' || !GRAPHQL_NAME.test(value)) {
+		variableCodecInvalid(path);
+	}
+}
+
+export function assertNonemptyString(value: unknown, path: string): asserts value is string {
+	if (typeof value !== 'string' || value.length === 0) variableCodecInvalid(path);
+}
+
+export function assertBoolean(value: unknown, path: string): asserts value is boolean {
+	if (typeof value !== 'boolean') variableCodecInvalid(path);
+}
+
+export function validateCodecLimit(value: unknown, path: string): number {
+	if (
+		typeof value !== 'number' ||
+		!Number.isSafeInteger(value) ||
+		value < 0
+	) {
+		variableCodecInvalid(path);
+	}
+	return value;
+}
+
+export function checkCodecDepth(depth: number, path: string): void {
+	if (depth > MAX_VARIABLE_CODEC_DEPTH) variableCodecInvalid(path);
+}
+
+export function checkValueDepth(depth: number, path: string): void {
+	if (depth > MAX_VARIABLE_CODEC_DEPTH) {
+		variableValueInvalid(path, 'input nesting exceeds the supported depth');
+	}
+}
+
+export function checkFilterDepth(
+	depth: number,
+	limits: ReplicaVariableCodecLimits,
+	path: string
+): void {
+	if (depth > limits.maxDepth) {
+		variableValueInvalid(
+			path,
+			`filter nesting reaches depth ${depth}, exceeding maxDepth ${limits.maxDepth}`
+		);
+	}
+}
+
+export function variableCodecInvalid(path: string): never {
+	throw new TypeError(`invalid replica variable codec at ${path}`);
+}
+
+export function variableValueInvalid(path: string, detail: string): never {
+	throw new TypeError(`invalid GraphQL operation input at ${path}: ${detail}`);
+}
+
diff --git a/js/src/replica/identity/constants.ts b/js/src/replica/identity/constants.ts
new file mode 100644
index 00000000..e4e26ef4
--- /dev/null
+++ b/js/src/replica/identity/constants.ts
@@ -0,0 +1,19 @@
+export const GRAPHQL_NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
+export const MAX_VARIABLE_CODEC_DEPTH = 64;
+export const FILTER_OPERATORS = new Set([
+	'_eq',
+	'_neq',
+	'_gt',
+	'_gte',
+	'_lt',
+	'_lte',
+	'_in',
+	'_nin',
+	'_is_null',
+	'_like',
+	'_ilike',
+	'_contains',
+	'_contained_in',
+	'_has_key'
+]);
+
diff --git a/js/src/replica/identity/implementation.ts b/js/src/replica/identity/implementation.ts
new file mode 100644
index 00000000..f8b1fe2f
--- /dev/null
+++ b/js/src/replica/identity/implementation.ts
@@ -0,0 +1,5 @@
+/** Re-export surface for identity implementation modules (body-split). */
+export * from './constants.js';
+export * from './keys.js';
+export * from './codec.js';
+export * from './clone.js';
diff --git a/js/src/replica/identity/index.ts b/js/src/replica/identity/index.ts
new file mode 100644
index 00000000..8e7fbcdd
--- /dev/null
+++ b/js/src/replica/identity/index.ts
@@ -0,0 +1,16 @@
+export {
+	replicaRecordKey,
+	replicaIndexKey,
+	resolveArguments,
+	resolveReplicaArgumentValue,
+	coverageFromArtifact
+} from './keys.js';
+export {
+	canonicalizeOperationVariables
+} from './codec.js';
+export {
+	canonicalVariables,
+	cloneJsonObject,
+	cloneJsonValue,
+	canonicalCacheValue
+} from './clone.js';
diff --git a/js/src/replica/identity/keys.ts b/js/src/replica/identity/keys.ts
new file mode 100644
index 00000000..e19c14c9
--- /dev/null
+++ b/js/src/replica/identity/keys.ts
@@ -0,0 +1,250 @@
+import { cacheIndexKey } from '../../internal/cache-engine.js';
+import type { GraphqlVariables } from '../../types.js';
+import type {
+	ReplicaArgumentValue,
+	ReplicaArgumentsArtifact,
+	ReplicaCoverageArtifact,
+	ReplicaIdentity,
+	ReplicaIndexCoverage,
+	ReplicaModelArtifact,
+	ReplicaValue
+} from '../types.js';
+import { assertName } from '../../lib/assert-name.js';
+import { freezeRecord } from '../../lib/freeze-record.js';
+import { canonicalCacheValue, cloneJsonValue } from './clone.js';
+
+export function replicaRecordKey(
+	model: ReplicaModelArtifact,
+	identity: ReplicaIdentity
+): string {
+	assertName(model.id, 'model id');
+	if (!Array.isArray(model.identityFields) || model.identityFields.length === 0) {
+		throw new TypeError(`model ${model.id} must declare at least one identity field`);
+	}
+	const parts = Array.isArray(identity) ? identity : [identity];
+	if (parts.length !== model.identityFields.length) {
+		throw new TypeError(
+			`model ${model.id} identity expected ${model.identityFields.length} part(s), received ${parts.length}`
+		);
+	}
+	return `record:${encodeURIComponent(model.id)}:${canonicalCacheValue(
+		parts.map((part) => cloneJsonValue(part))
+	)}`;
+}
+
+export function replicaIndexKey(input: {
+	readonly parent?: string;
+	readonly field: string;
+	readonly arguments?: Readonly<Record<string, ReplicaValue>>;
+}): string {
+	return cacheIndexKey({
+		...(input.parent === undefined ? {} : { parent: input.parent }),
+		field: input.field,
+		arguments: input.arguments ?? {}
+	});
+}
+
+export function resolveArguments(
+	artifact: ReplicaArgumentsArtifact | undefined,
+	variables: GraphqlVariables,
+	coverage?: ReplicaCoverageArtifact
+): Readonly<Record<string, ReplicaValue>> {
+	const entries: Array<readonly [string, ReplicaValue]> = [];
+	for (const [argument, source] of Object.entries(artifact ?? {})) {
+		assertName(argument, 'GraphQL argument');
+		const value = resolveReplicaArgumentValue(source, variables);
+		if (value !== undefined) entries.push([argument, value]);
+	}
+	const resolved = freezeRecord(entries);
+	return coverage?.kind === 'offset'
+		? effectiveOffsetArguments(resolved, coverage)
+		: resolved;
+}
+
+export function resolveReplicaArgumentValue(
+	source: ReplicaArgumentValue,
+	variables: GraphqlVariables,
+	position: 'argument' | 'object' | 'list' = 'argument'
+): ReplicaValue | undefined {
+	if (source.kind === 'literal') return cloneJsonValue(source.value);
+	if (source.kind === 'variable') {
+		assertName(source.name, 'GraphQL variable');
+		if (
+			!Object.prototype.hasOwnProperty.call(variables, source.name) ||
+			variables[source.name] === undefined
+		) {
+			return position === 'list' ? null : undefined;
+		}
+		return cloneJsonValue(variables[source.name]);
+	}
+	if (source.kind === 'list') {
+		if (!Array.isArray(source.items)) {
+			throw new TypeError('GraphQL list argument source must contain an items array');
+		}
+		return Object.freeze(
+			source.items.map(
+				(item) => resolveReplicaArgumentValue(item, variables, 'list') ?? null
+			)
+		);
+	}
+	if (source.kind === 'object') {
+		if (
+			source.fields === null ||
+			typeof source.fields !== 'object' ||
+			Array.isArray(source.fields)
+		) {
+			throw new TypeError('GraphQL object argument source must contain a fields object');
+		}
+		const entries: Array<readonly [string, ReplicaValue]> = [];
+		for (const [field, value] of Object.entries(source.fields)) {
+			assertName(field, 'GraphQL input field');
+			const resolved = resolveReplicaArgumentValue(value, variables, 'object');
+			if (resolved !== undefined) entries.push([field, resolved]);
+		}
+		return freezeRecord(entries);
+	}
+	throw new TypeError('unsupported argument source');
+}
+
+export function coverageFromArtifact(
+	artifact: ReplicaCoverageArtifact | undefined,
+	argumentsValue: Readonly<Record<string, ReplicaValue>>,
+	returned: number
+): ReplicaIndexCoverage {
+	if (artifact === undefined || artifact.kind === 'complete') {
+		return Object.freeze({ kind: 'complete' });
+	}
+	if (artifact.kind === 'offset') {
+		const window = effectiveOffsetWindow(argumentsValue, artifact);
+		return Object.freeze({
+			kind: 'offset' as const,
+			offset: window.offset,
+			...(window.limit === undefined ? {} : { limit: window.limit }),
+			returned
+		});
+	}
+	return Object.freeze({
+		kind: 'cursor' as const,
+		...cacheArgument(argumentsValue, artifact.afterArgument, 'after'),
+		...cacheArgument(argumentsValue, artifact.beforeArgument, 'before'),
+		...numericCoverageArgument(argumentsValue, artifact.firstArgument, 'first'),
+		...numericCoverageArgument(argumentsValue, artifact.lastArgument, 'last')
+	});
+}
+
+export type OffsetCoverageArtifact = Extract<ReplicaCoverageArtifact, { readonly kind: 'offset' }>;
+
+export function effectiveOffsetArguments(
+	argumentsValue: Readonly<Record<string, ReplicaValue>>,
+	artifact: OffsetCoverageArtifact
+): Readonly<Record<string, ReplicaValue>> {
+	const window = effectiveOffsetWindow(argumentsValue, artifact);
+	const entries = new Map(Object.entries(argumentsValue));
+	if (artifact.offsetArgument !== undefined) {
+		assertName(artifact.offsetArgument, 'offset pagination argument');
+		entries.set(artifact.offsetArgument, window.offset);
+	}
+	if (artifact.limitArgument !== undefined) {
+		assertName(artifact.limitArgument, 'limit pagination argument');
+		if (window.limit === undefined) entries.delete(artifact.limitArgument);
+		else entries.set(artifact.limitArgument, window.limit);
+	}
+	return freezeRecord([...entries.entries()]);
+}
+
+export function effectiveOffsetWindow(
+	argumentsValue: Readonly<Record<string, ReplicaValue>>,
+	artifact: OffsetCoverageArtifact
+): { readonly offset: number; readonly limit?: number } {
+	const configuredDefault = coverageBound(artifact.defaultLimit, 'defaultLimit');
+	const configuredMax = coverageBound(artifact.maxLimit, 'maxLimit');
+	if (
+		configuredDefault !== undefined &&
+		configuredMax !== undefined &&
+		configuredDefault > configuredMax
+	) {
+		throw new TypeError('offset coverage defaultLimit must not exceed maxLimit');
+	}
+	const offset =
+		serverNonNegativeIntegerArgument(argumentsValue, artifact.offsetArgument) ?? 0;
+	const requested = serverNonNegativeIntegerArgument(
+		argumentsValue,
+		artifact.limitArgument
+	);
+	const selected = requested ?? configuredDefault;
+	const limit =
+		selected === undefined || configuredMax === undefined
+			? selected
+			: Math.min(selected, configuredMax);
+	return {
+		offset,
+		...(limit === undefined ? {} : { limit })
+	};
+}
+
+/**
+ * Distributed's SQL compiler treats an omitted, explicit-null, or negative
+ * nullable Int as absent before applying the server default. Other values
+ * cannot appear in a successful GraphQL response and remain fail-fast here.
+ */
+export function serverNonNegativeIntegerArgument(
+	argumentsValue: Readonly<Record<string, ReplicaValue>>,
+	argument: string | undefined
+): number | undefined {
+	if (
+		argument === undefined ||
+		!Object.prototype.hasOwnProperty.call(argumentsValue, argument)
+	) {
+		return undefined;
+	}
+	const value = argumentsValue[argument];
+	if (value === null) return undefined;
+	if (!Number.isSafeInteger(value)) {
+		throw new TypeError(`pagination argument ${argument} must be an integer or null`);
+	}
+	if ((value as number) < 0) return undefined;
+	return (value as number) === 0 ? 0 : (value as number);
+}
+
+export function coverageBound(value: number | undefined, field: string): number | undefined {
+	if (value === undefined) return undefined;
+	if (!Number.isSafeInteger(value) || value < 0) {
+		throw new TypeError(`offset coverage ${field} must be a non-negative safe integer`);
+	}
+	return value;
+}
+
+export function cacheArgument<K extends 'after' | 'before'>(
+	argumentsValue: Readonly<Record<string, ReplicaValue>>,
+	argument: string | undefined,
+	key: K
+): Partial<Record<K, ReplicaValue>> {
+	if (argument === undefined || !Object.prototype.hasOwnProperty.call(argumentsValue, argument)) {
+		return {};
+	}
+	return { [key]: argumentsValue[argument]! } as Partial<Record<K, ReplicaValue>>;
+}
+
+export function numericCoverageArgument<K extends 'first' | 'last'>(
+	argumentsValue: Readonly<Record<string, ReplicaValue>>,
+	argument: string | undefined,
+	key: K
+): Partial<Record<K, number>> {
+	const value = numericArgument(argumentsValue, argument);
+	return value === undefined ? {} : ({ [key]: value } as Partial<Record<K, number>>);
+}
+
+export function numericArgument(
+	argumentsValue: Readonly<Record<string, ReplicaValue>>,
+	argument: string | undefined
+): number | undefined {
+	if (argument === undefined || !Object.prototype.hasOwnProperty.call(argumentsValue, argument)) {
+		return undefined;
+	}
+	const value = argumentsValue[argument];
+	if (!Number.isSafeInteger(value) || (value as number) < 0) {
+		throw new TypeError(`pagination argument ${argument} must be a non-negative integer`);
+	}
+	return value as number;
+}
+
diff --git a/js/src/replica/index-maintenance.ts b/js/src/replica/index-maintenance.ts
new file mode 100644
index 00000000..b8419475
--- /dev/null
+++ b/js/src/replica/index-maintenance.ts
@@ -0,0 +1,20 @@
+/** Index maintenance registry and plan evaluation; implementation in ./index-maintenance/. */
+export {
+	createReplicaIndexMaintenanceRegistry,
+	formatReplicaIndexStaleReason
+} from './index-maintenance/index.js';
+export type {
+	ReplicaIndexDependencyChange,
+	ReplicaIndexMaintenanceDecision,
+	ReplicaIndexMaintenanceIndex,
+	ReplicaIndexMaintenanceReason,
+	ReplicaIndexMaintenanceReasonCode,
+	ReplicaIndexMaintenanceRecord,
+	ReplicaIndexMaintenanceRegistry,
+	ReplicaIndexMaintenanceSnapshot,
+	ReplicaIndexPlanRegistration,
+	ReplicaIndexRecordChange,
+	ReplicaIndexRelationshipChange,
+	ReplicaIndexSemanticChange,
+	ReplicaIndexSemanticLayer
+} from './index-maintenance/index.js';
diff --git a/js/src/replica/index-maintenance/engine.ts b/js/src/replica/index-maintenance/engine.ts
new file mode 100644
index 00000000..5b3f3304
--- /dev/null
+++ b/js/src/replica/index-maintenance/engine.ts
@@ -0,0 +1,1119 @@
+import type { GraphqlVariables } from '../../types.js';
+import type { DistributedTrustedPreset } from '../../protocol.js';
+import {
+	replicaIndexKey,
+	resolveArguments
+} from '../identity.js';
+import {
+	compareReplicaOrder,
+	decideReplicaPaginationMaintenance,
+	evaluateReplicaFilter
+} from '../query-plan.js';
+import type {
+	ReplicaFilterArtifact,
+	ReplicaCoverageArtifact,
+	ReplicaIndexRecordChange,
+	ReplicaIndexRelationshipChange,
+	ReplicaIndexSemanticChange,
+	ReplicaObjectBranch,
+	ReplicaOperationArtifact,
+	ReplicaOrderArtifact,
+	ReplicaPaginationArtifact,
+	ReplicaRelationshipArtifact,
+	ReplicaRootSelection,
+	ReplicaSurfaceTrustedPresetDescriptor,
+	ReplicaValue
+} from '../types.js';
+import { compareCodeUnits } from '../../lib/compare-code-units.js';
+import type {
+	ReplicaIndexMaintenanceDecision,
+	ReplicaIndexMaintenanceIndex,
+	ReplicaIndexMaintenanceReason,
+	ReplicaIndexMaintenanceReasonCode,
+	ReplicaIndexMaintenanceRecord,
+	ReplicaIndexSemanticLayer
+} from './types.js';
+
+export type PlanKind = 'entity' | 'relationship' | 'snapshot';
+
+export type RegisteredPlan = {
+	readonly registration: string;
+	readonly kind: PlanKind;
+	readonly exactIndexKey?: string;
+	readonly parentModel?: string;
+	readonly targetModel?: string;
+	readonly field: string;
+	readonly arguments: Readonly<Record<string, ReplicaValue>>;
+	readonly dependencies: readonly string[];
+	readonly cardinality: 'one' | 'many';
+	readonly filter?: ReplicaFilterArtifact;
+	readonly order?: ReplicaOrderArtifact;
+	readonly pagination?: ReplicaPaginationArtifact;
+	readonly coverage?: ReplicaCoverageArtifact;
+	readonly relationship?: ReplicaRelationshipArtifact;
+	readonly variables: GraphqlVariables;
+	readonly trustedPresets: readonly ReplicaSurfaceTrustedPresetDescriptor[];
+	readonly path: readonly (string | number)[];
+	readonly signature: string;
+};
+
+export type MutableRecord = {
+	readonly key: string;
+	readonly model: string;
+	fields: Record<string, ReplicaValue>;
+};
+
+export type AppliedChanges = {
+	readonly baseRecords: ReadonlyMap<string, MutableRecord>;
+	readonly records: Map<string, MutableRecord>;
+	readonly recordChanges: readonly ReplicaIndexRecordChange[];
+	readonly relationshipChanges: readonly ReplicaIndexRelationshipChange[];
+	readonly invalidatedDependencies: ReadonlySet<string>;
+	readonly allDependencies: ReadonlySet<string>;
+};
+
+export function formatReplicaIndexStaleReason(
+	reasonValue: ReplicaIndexMaintenanceReason
+): string {
+	const path =
+		reasonValue.path.length === 0
+			? ''
+			: `:${reasonValue.path.map(String).join('.')}`;
+	return `query-plan:${reasonValue.code}${path}`;
+}
+
+export function compilePlans(
+	registration: string,
+	artifact: ReplicaOperationArtifact<unknown, GraphqlVariables>,
+	variables: GraphqlVariables
+): readonly RegisteredPlan[] {
+	const plans: RegisteredPlan[] = [];
+	const trustedPresets = artifact.protocol.trustedPresets;
+	for (const [index, root] of artifact.roots.entries()) {
+		const path: readonly (string | number)[] = ['roots', index, root.field];
+		const targetModel = selectionModel(root.selection);
+		const kind: PlanKind =
+			targetModel === undefined ? 'snapshot' : 'entity';
+		const argumentsValue = resolveArguments(
+			root.arguments,
+			variables,
+			root.coverage
+		);
+		plans.push(
+			plan({
+				registration,
+				kind,
+				exactIndexKey: replicaIndexKey({
+					field: root.field,
+					arguments: argumentsValue
+				}),
+				targetModel,
+				field: root.field,
+				arguments: argumentsValue,
+				dependencies: root.dependencies,
+				cardinality: root.cardinality,
+				filter: root.filter,
+				order: root.order,
+				pagination: root.pagination,
+				coverage: root.coverage,
+				variables,
+				trustedPresets,
+				path
+			})
+		);
+		compileSelectionPlans(
+			plans,
+			registration,
+			root.selection,
+			targetModel,
+			variables,
+			trustedPresets,
+			path
+		);
+	}
+	return Object.freeze(plans);
+}
+
+export function compileSelectionPlans(
+	output: RegisteredPlan[],
+	registration: string,
+	selection: ReplicaRootSelection['selection'],
+	parentModel: string | undefined,
+	variables: GraphqlVariables,
+	trustedPresets: readonly ReplicaSurfaceTrustedPresetDescriptor[],
+	path: readonly (string | number)[]
+): void {
+	for (const [index, member] of selection.members.entries()) {
+		if (member.kind !== 'branch') continue;
+		compileBranchPlan(
+			output,
+			registration,
+			member,
+			parentModel,
+			variables,
+			trustedPresets,
+			[...path, 'members', index, member.field]
+		);
+	}
+}
+
+export function compileBranchPlan(
+	output: RegisteredPlan[],
+	registration: string,
+	branch: ReplicaObjectBranch,
+	parentModel: string | undefined,
+	variables: GraphqlVariables,
+	trustedPresets: readonly ReplicaSurfaceTrustedPresetDescriptor[],
+	path: readonly (string | number)[]
+): void {
+	const argumentsValue = resolveArguments(
+		branch.arguments,
+		variables,
+		branch.coverage
+	);
+	const targetModel = selectionModel(branch.selection);
+	output.push(
+		plan({
+			registration,
+			kind: branch.semantic === 'relationship' ? 'relationship' : 'snapshot',
+			parentModel,
+			targetModel,
+			field: branch.field,
+			arguments: argumentsValue,
+			dependencies: branch.dependencies,
+			cardinality: branch.cardinality,
+			filter: branch.filter,
+			order: branch.order,
+			pagination: branch.pagination,
+			coverage: branch.coverage,
+			relationship: branch.relationship,
+			variables,
+			trustedPresets,
+			path
+		})
+	);
+	compileSelectionPlans(
+		output,
+		registration,
+		branch.selection,
+		targetModel ?? parentModel,
+		variables,
+		trustedPresets,
+		path
+	);
+}
+
+export function plan(
+	value: Omit<RegisteredPlan, 'signature'>
+): RegisteredPlan {
+	const signature = canonicalValue({
+		kind: value.kind,
+		parentModel: value.parentModel ?? null,
+		targetModel: value.targetModel ?? null,
+		field: value.field,
+		arguments: value.arguments,
+		dependencies: [...value.dependencies].sort(compareCodeUnits),
+		cardinality: value.cardinality,
+		filter: value.filter ?? null,
+		order: value.order ?? null,
+		pagination: value.pagination ?? null,
+		coverage: value.coverage ?? null,
+		relationship: value.relationship ?? null,
+		trustedPresets: value.trustedPresets
+	});
+	return Object.freeze({
+		...value,
+		arguments: cloneRecord(value.arguments),
+		dependencies: Object.freeze([...new Set(value.dependencies)].sort(compareCodeUnits)),
+		trustedPresets: Object.freeze(
+			value.trustedPresets.map((descriptor) =>
+				Object.freeze({ name: descriptor.name, codec: descriptor.codec })
+			)
+		),
+		path: Object.freeze([...value.path]),
+		signature
+	});
+}
+
+export function selectionModel(
+	selection: ReplicaRootSelection['selection']
+): string | undefined {
+	return selection.storage.kind === 'normalized'
+		? selection.storage.model
+		: undefined;
+}
+
+export function instantiatePlans(
+	plans: readonly RegisteredPlan[],
+	indexes: ReadonlyMap<string, ReplicaIndexMaintenanceIndex>
+): Map<string, RegisteredPlan[]> {
+	const result = new Map<string, RegisteredPlan[]>();
+	for (const value of plans) {
+		if (value.exactIndexKey !== undefined) {
+			if (indexes.has(value.exactIndexKey)) {
+				appendPlan(result, value.exactIndexKey, value);
+			}
+			continue;
+		}
+		for (const index of indexes.values()) {
+			const parent = index.metadata.parent;
+			if (
+				parent === undefined ||
+				index.metadata.field !== value.field ||
+				replicaIndexKey({
+					parent,
+					field: value.field,
+					arguments: value.arguments
+				}) !== index.key ||
+				(value.parentModel !== undefined &&
+					!recordKeyMatchesModel(parent, value.parentModel))
+			) {
+				continue;
+			}
+			appendPlan(result, index.key, value);
+		}
+	}
+	return result;
+}
+
+export function appendPlan(
+	output: Map<string, RegisteredPlan[]>,
+	key: string,
+	value: RegisteredPlan
+): void {
+	const current = output.get(key) ?? [];
+	if (
+		current.some(
+			(candidate) =>
+				candidate.registration === value.registration &&
+				candidate.signature === value.signature
+		)
+	) {
+		return;
+	}
+	current.push(value);
+	output.set(key, current);
+}
+
+export function applyLayers(
+	base: readonly ReplicaIndexMaintenanceRecord[],
+	layers: readonly ReplicaIndexSemanticLayer[]
+): AppliedChanges {
+	const records = new Map<string, MutableRecord>();
+	for (const input of base) {
+		validateName(input.key, 'record key');
+		validateName(input.model, 'record model');
+		if (records.has(input.key)) {
+			throw new TypeError(`duplicate maintenance record: ${input.key}`);
+		}
+		records.set(input.key, {
+			key: input.key,
+			model: input.model,
+			fields: { ...input.fields }
+		});
+	}
+	const baseRecords = new Map(
+		[...records].map(([key, record]) => [
+			key,
+			{
+				key: record.key,
+				model: record.model,
+				fields: { ...record.fields }
+			}
+		])
+	);
+	const recordChanges: ReplicaIndexRecordChange[] = [];
+	const relationshipChanges: ReplicaIndexRelationshipChange[] = [];
+	const invalidatedDependencies = new Set<string>();
+	const allDependencies = new Set<string>();
+	const layerIds = new Set<string>();
+	for (const layer of layers) {
+		validateName(layer.id, 'semantic layer id');
+		if (layerIds.has(layer.id)) {
+			throw new TypeError(`duplicate semantic layer: ${layer.id}`);
+		}
+		layerIds.add(layer.id);
+		for (const change of layer.changes) {
+			if (change.kind === 'invalidate') {
+				for (const dependency of validateDependencies(change.dependencies)) {
+					invalidatedDependencies.add(dependency);
+					allDependencies.add(dependency);
+				}
+				continue;
+			}
+			if (isRelationshipChange(change)) {
+				validateName(change.sourceModel, 'relationship source model');
+				validateName(change.field, 'relationship field');
+				validateName(change.targetModel, 'relationship target model');
+				validateName(change.sourceKey, 'relationship source key');
+				validateName(change.targetKey, 'relationship target key');
+				for (const dependency of validateDependencies(change.dependencies)) {
+					allDependencies.add(dependency);
+				}
+				relationshipChanges.push(change);
+				continue;
+			}
+			validateName(change.model, 'record change model');
+			validateName(change.key, 'record change key');
+			for (const dependency of validateDependencies(change.dependencies ?? [])) {
+				allDependencies.add(dependency);
+			}
+			recordChanges.push(change);
+			if (change.kind === 'delete') {
+				records.delete(change.key);
+				continue;
+			}
+			const current = records.get(change.key);
+			if (current !== undefined && current.model !== change.model) {
+				throw new TypeError(`record model changed for ${change.key}`);
+			}
+			records.set(change.key, {
+				key: change.key,
+				model: change.model,
+				fields: { ...(current?.fields ?? {}), ...change.fields }
+			});
+		}
+	}
+	return {
+		baseRecords,
+		records,
+		recordChanges: Object.freeze(recordChanges),
+		relationshipChanges: Object.freeze(relationshipChanges),
+		invalidatedDependencies,
+		allDependencies
+	};
+}
+
+export function validateIndexes(
+	input: readonly ReplicaIndexMaintenanceIndex[]
+): Map<string, ReplicaIndexMaintenanceIndex> {
+	const indexes = new Map<string, ReplicaIndexMaintenanceIndex>();
+	for (const index of input) {
+		validateName(index.key, 'index key');
+		if (indexes.has(index.key)) {
+			throw new TypeError(`duplicate maintenance index: ${index.key}`);
+		}
+		indexes.set(index.key, index);
+	}
+	return indexes;
+}
+
+export function planAffected(
+	planValue: RegisteredPlan,
+	index: ReplicaIndexMaintenanceIndex,
+	changes: AppliedChanges
+): boolean {
+	if (
+		planValue.kind === 'snapshot' &&
+		intersects(planValue.dependencies, changes.allDependencies)
+	) {
+		return true;
+	}
+	if (
+		intersects(planValue.dependencies, changes.invalidatedDependencies)
+	) {
+		return true;
+	}
+	if (
+		planValue.targetModel !== undefined &&
+		changes.recordChanges.some(({ model }) => model === planValue.targetModel)
+	) {
+		return true;
+	}
+	if (
+		planValue.kind === 'relationship' &&
+		planValue.parentModel !== undefined &&
+		changes.recordChanges.some((change) =>
+			parentRecordChangeAffectsRelationship(planValue, index, change)
+		)
+	) {
+		return true;
+	}
+	return changes.relationshipChanges.some((change) =>
+		relationshipChangeMatches(planValue, index, change)
+	);
+}
+
+export function evaluatePlan(
+	planValue: RegisteredPlan,
+	index: ReplicaIndexMaintenanceIndex,
+	changes: AppliedChanges,
+	trustedPresets: readonly DistributedTrustedPreset[]
+): ReplicaIndexMaintenanceDecision {
+	if (planValue.kind === 'snapshot') {
+		return stale(
+			index.key,
+			reason(
+				'aggregate_dependency_changed',
+				planValue.path,
+				'an aggregate or embedded query snapshot dependency changed'
+			)
+		);
+	}
+	if (intersects(planValue.dependencies, changes.invalidatedDependencies)) {
+		return stale(
+			index.key,
+			reason(
+				'dependency_changed',
+				planValue.path,
+				'a declared dependency changed without locally provable row evidence'
+			)
+		);
+	}
+	/*
+	 * Freshness and structure are independent. Revalidation deliberately marks
+	 * a complete index stale while retaining its last authoritative membership.
+	 * Pending semantic layers must keep rebasing over that membership; the
+	 * derived write preserves the stale metadata until the network result lands.
+	 */
+	if (!index.complete) {
+		return stale(
+			index.key,
+			reason(
+				'index_incomplete',
+				['indexes', index.key],
+				'only a structurally complete index can be maintained locally'
+			)
+		);
+	}
+	if (planValue.cardinality !== 'many') {
+		const targetChanges = changes.recordChanges.filter(
+			(change) => change.model === planValue.targetModel
+		);
+		if (
+			changes.relationshipChanges.length === 0 &&
+			targetChanges.length > 0 &&
+			targetChanges.every(
+				(change) =>
+					change.kind === 'upsert' && index.records.includes(change.key)
+			)
+		) {
+			// Updating fields on the already-selected singular identity cannot
+			// change that index's membership. The sparse record dependency will
+			// still publish selected field changes to the UI.
+			return unchanged(index.key);
+		}
+		return stale(
+			index.key,
+			reason(
+				'unsupported_cardinality',
+				planValue.path,
+				'local query-index maintenance is limited to collection fields'
+			)
+		);
+	}
+	if (
+		index.metadata.field !== planValue.field ||
+		!sameValue(index.metadata.arguments, planValue.arguments)
+	) {
+		return stale(
+			index.key,
+			reason(
+				'invalid_index_metadata',
+				['indexes', index.key],
+				'stored index metadata does not match its compiler plan'
+			)
+		);
+	}
+	const duplicate = firstDuplicate(index.records);
+	if (duplicate !== undefined) {
+		return stale(
+			index.key,
+			reason(
+				'duplicate_index_record',
+				['indexes', index.key],
+				`stored index contains duplicate record ${duplicate}`
+			)
+		);
+	}
+	if (
+		planValue.kind === 'relationship' &&
+		planValue.relationship?.maintenance !== 'local'
+	) {
+		return stale(
+			index.key,
+			reason(
+				'relationship_maintenance_revalidate',
+				planValue.path,
+				'the compiler marked this relationship as revalidation-only'
+			)
+		);
+	}
+	return maintainEntityIndex(planValue, index, changes, trustedPresets);
+}
+
+export function maintainEntityIndex(
+	planValue: RegisteredPlan,
+	index: ReplicaIndexMaintenanceIndex,
+	changes: AppliedChanges,
+	trustedPresets: readonly DistributedTrustedPreset[]
+): ReplicaIndexMaintenanceDecision {
+	const current = [...index.records];
+	const members = new Set(current);
+	const candidates = new Set<string>();
+	for (const change of changes.recordChanges) {
+		if (change.model === planValue.targetModel) candidates.add(change.key);
+	}
+	const relationshipOverrides = new Map<string, boolean>();
+	if (planValue.kind === 'relationship') {
+		const parentChanged = changes.recordChanges.some((change) =>
+			parentRecordChangeAffectsRelationship(planValue, index, change)
+		);
+		if (parentChanged) {
+			return stale(
+				index.key,
+				reason(
+					'relationship_mapping_unknown',
+					planValue.path,
+					'a parent-key dependency changed and sparse target coverage cannot prove the new relationship'
+				)
+			);
+		}
+		for (const change of changes.relationshipChanges) {
+			if (!relationshipChangeMatches(planValue, index, change)) continue;
+			const missing = planValue.relationship!.dependencies.filter(
+				(dependency) => !change.dependencies.includes(dependency)
+			);
+			if (missing.length > 0) {
+				return stale(
+					index.key,
+					reason(
+						'relationship_dependency_missing',
+						planValue.path,
+						`relationship change omits declared dependencies: ${missing.join(', ')}`
+					)
+				);
+			}
+			candidates.add(change.targetKey);
+			relationshipOverrides.set(change.targetKey, change.kind === 'link');
+		}
+	}
+
+	let inserted = false;
+	let removed = false;
+	for (const key of candidates) {
+		const record = changes.records.get(key);
+		let related = true;
+		if (planValue.kind === 'relationship') {
+			const override = relationshipOverrides.get(key);
+			if (override !== undefined) {
+				related = override;
+			} else if (members.has(key)) {
+				related = true;
+			} else {
+				const relation = relationshipMembership(
+					planValue,
+					index,
+					record,
+					changes.records
+				);
+				if ('reason' in relation) return stale(index.key, relation.reason);
+				related = relation.related;
+			}
+		}
+		if (record === undefined || !related) {
+			if (members.delete(key)) removed = true;
+			continue;
+		}
+		const filter = evaluateMembership(planValue, record, trustedPresets);
+		if ('reason' in filter) return stale(index.key, filter.reason);
+		if (filter.matches) {
+			if (!members.has(key)) {
+				members.add(key);
+				inserted = true;
+			}
+		} else if (members.delete(key)) {
+			removed = true;
+		}
+	}
+
+	let activeOrderChanged = false;
+	if (planValue.order !== undefined) {
+		for (const key of candidates) {
+			if (!members.has(key)) continue;
+			const before = changes.baseRecords.get(key);
+			const after = changes.records.get(key);
+			if (before === undefined || after === undefined) continue;
+			const compared = compareReplicaOrder(
+				planValue.order,
+				before.fields,
+				after.fields,
+				planValue.variables
+			);
+			if (compared.result === 'unknown') {
+				return stale(index.key, compared.reason);
+			}
+			if (compared.result !== 'equal') {
+				activeOrderChanged = true;
+				break;
+			}
+		}
+	}
+	let records = current.filter((key) => members.has(key));
+	for (const key of members) {
+		if (!records.includes(key)) records.push(key);
+	}
+	const needsOrder = inserted || activeOrderChanged;
+	if (needsOrder) {
+		if (planValue.order === undefined && inserted) {
+			return stale(
+				index.key,
+				reason(
+					'missing_order_plan',
+					planValue.path,
+					'an inserted record cannot be positioned without a compiler order plan'
+				)
+			);
+		}
+		if (planValue.order !== undefined) {
+			const sorted = sortRecords(
+				records,
+				planValue.order,
+				changes.records,
+				planValue.variables,
+				planValue.path
+			);
+			if ('reason' in sorted) return stale(index.key, sorted.reason);
+			records = [...sorted.records];
+		}
+	}
+	const reordered =
+		!inserted &&
+		!removed &&
+		(activeOrderChanged || !sameStringList(records, current));
+	const changeKind =
+		inserted
+			? 'insert'
+			: removed
+				? 'delete'
+				: reordered
+					? 'reorder'
+					: 'stable_update';
+	if (planValue.pagination === undefined) {
+		if (
+			changeKind === 'stable_update' &&
+			sameStringList(records, current)
+		) {
+			// An uncertified collection can still prove a membership/order no-op;
+			// that stable update needs no index write or revalidation.
+			return unchanged(index.key);
+		}
+		return stale(
+			index.key,
+			reason(
+				'invalid_artifact',
+				planValue.path,
+				'collection plan is missing its pagination maintenance contract'
+			)
+		);
+	}
+	const coverageReason = certifyOffsetCoverage(
+		planValue,
+		index,
+		current.length,
+		changeKind
+	);
+	if (coverageReason !== undefined) {
+		return stale(index.key, coverageReason);
+	}
+	const pagination = decideReplicaPaginationMaintenance(
+		planValue.pagination,
+		index.metadata.coverage,
+		{ kind: changeKind }
+	);
+	if (pagination.decision === 'revalidate') {
+		return stale(index.key, pagination.reason);
+	}
+	if (
+		planValue.pagination.kind === 'offset' &&
+		index.metadata.coverage.kind === 'offset' &&
+		index.metadata.coverage.offset === 0 &&
+		index.metadata.coverage.limit !== undefined &&
+		records.length > index.metadata.coverage.limit
+	) {
+		// Locality above is possible only because the base first page was
+		// non-full, so this is the complete optimistic ordered set. Preserve the
+		// operation's exact window when stacked optimistic inserts cross its
+		// limit.
+		records = records.slice(0, index.metadata.coverage.limit);
+	}
+	return sameStringList(records, current)
+		? unchanged(index.key)
+		: write(index.key, records);
+}
+
+export function certifyOffsetCoverage(
+	planValue: RegisteredPlan,
+	index: ReplicaIndexMaintenanceIndex,
+	confirmedRecords: number,
+	changeKind: 'insert' | 'delete' | 'reorder' | 'stable_update'
+): ReplicaIndexMaintenanceReason | undefined {
+	if (
+		planValue.pagination?.kind !== 'offset' ||
+		changeKind === 'stable_update'
+	) {
+		return undefined;
+	}
+	const artifact = planValue.coverage;
+	const coverage = index.metadata.coverage;
+	if (artifact?.kind !== 'offset' || coverage.kind !== 'offset') {
+		return reason(
+			'invalid_index_metadata',
+			['indexes', index.key, 'coverage'],
+			'offset pagination locality requires its exact compiler coverage contract'
+		);
+	}
+	const expectedOffset =
+		artifact.offsetArgument === undefined
+			? 0
+			: planValue.arguments[artifact.offsetArgument];
+	const configuredLimit =
+		artifact.limitArgument === undefined
+			? artifact.defaultLimit
+			: planValue.arguments[artifact.limitArgument];
+	const expectedLimit =
+		typeof configuredLimit === 'number' &&
+		typeof artifact.maxLimit === 'number'
+			? Math.min(configuredLimit, artifact.maxLimit)
+			: configuredLimit;
+	if (
+		typeof expectedOffset !== 'number' ||
+		!Number.isSafeInteger(expectedOffset) ||
+		expectedOffset < 0 ||
+		(typeof expectedLimit !== 'number' &&
+			expectedLimit !== undefined) ||
+		(typeof expectedLimit === 'number' &&
+			(!Number.isSafeInteger(expectedLimit) || expectedLimit < 0)) ||
+		coverage.offset !== expectedOffset ||
+		coverage.limit !== expectedLimit ||
+		coverage.returned !== confirmedRecords ||
+		coverage.hasNext === true
+	) {
+		return reason(
+			'invalid_index_metadata',
+			['indexes', index.key, 'coverage'],
+			'offset coverage does not match the request, confirmed index size, or observed page boundary'
+		);
+	}
+	return undefined;
+}
+
+export function parentRecordChangeAffectsRelationship(
+	planValue: RegisteredPlan,
+	index: ReplicaIndexMaintenanceIndex,
+	change: ReplicaIndexRecordChange
+): boolean {
+	if (
+		change.model !== planValue.parentModel ||
+		change.key !== index.metadata.parent
+	) {
+		return false;
+	}
+	if (change.kind === 'delete') return true;
+	const relationship = planValue.relationship;
+	if (relationship === undefined) {
+		// A forged relationship branch without its compiler-owned mapping must
+		// be evaluated and rejected instead of silently ignoring a parent change.
+		return true;
+	}
+	const mapping = relationship.keyMapping;
+	const mappingFields =
+		mapping.kind === 'embedded' ? Object.freeze([]) : mapping.local;
+	if (
+		mappingFields.some((field) =>
+			Object.prototype.hasOwnProperty.call(change.fields, field)
+		)
+	) {
+		return true;
+	}
+	const dependencies = new Set(change.dependencies ?? []);
+	return relationship.dependencies.some((dependency) =>
+		dependencies.has(dependency)
+	);
+}
+
+export function relationshipMembership(
+	planValue: RegisteredPlan,
+	index: ReplicaIndexMaintenanceIndex,
+	target: MutableRecord | undefined,
+	records: ReadonlyMap<string, MutableRecord>
+):
+	| { readonly related: boolean }
+	| { readonly reason: ReplicaIndexMaintenanceReason } {
+	if (target === undefined) return { related: false };
+	const relationship = planValue.relationship;
+	const parentKey = index.metadata.parent;
+	if (relationship === undefined || parentKey === undefined) {
+		return {
+			reason: reason(
+				'relationship_mapping_unknown',
+				planValue.path,
+				'relationship plan or parent identity is unavailable'
+			)
+		};
+	}
+	if (relationship.keyMapping.kind !== 'direct') {
+		return {
+			reason: reason(
+				'relationship_mapping_unknown',
+				planValue.path,
+				'a non-member through/opaque relationship requires explicit link evidence'
+			)
+		};
+	}
+	const parent = records.get(parentKey);
+	if (parent === undefined) {
+		return {
+			reason: reason(
+				'missing_parent_record',
+				planValue.path,
+				'relationship parent record is absent'
+			)
+		};
+	}
+	for (let indexValue = 0; indexValue < relationship.keyMapping.local.length; indexValue += 1) {
+		const local = relationship.keyMapping.local[indexValue]!;
+		const remote = relationship.keyMapping.remote[indexValue]!;
+		if (
+			!Object.prototype.hasOwnProperty.call(parent.fields, local) ||
+			!Object.prototype.hasOwnProperty.call(target.fields, remote)
+		) {
+			return {
+				reason: reason(
+					'missing_field',
+					[...planValue.path, 'relationship', local, remote],
+					'relationship key fields are not completely present'
+				)
+			};
+		}
+		if (!sameValue(parent.fields[local], target.fields[remote])) {
+			return { related: false };
+		}
+	}
+	return { related: true };
+}
+
+export function evaluateMembership(
+	planValue: RegisteredPlan,
+	record: MutableRecord,
+	trustedPresets: readonly DistributedTrustedPreset[]
+):
+	| { readonly matches: boolean }
+	| { readonly reason: ReplicaIndexMaintenanceReason } {
+	if (planValue.filter === undefined) return { matches: true };
+	const evaluated = evaluateReplicaFilter(
+		planValue.filter,
+		record.fields,
+		planValue.variables,
+		{
+			trustedPresets: {
+				descriptors: planValue.trustedPresets,
+				values: trustedPresets
+			}
+		}
+	);
+	return evaluated.result === 'unknown'
+		? { reason: evaluated.reason }
+		: { matches: evaluated.result === 'match' };
+}
+
+export function sortRecords(
+	keys: readonly string[],
+	order: ReplicaOrderArtifact,
+	records: ReadonlyMap<string, MutableRecord>,
+	variables: GraphqlVariables,
+	path: readonly (string | number)[]
+):
+	| { readonly records: readonly string[] }
+	| { readonly reason: ReplicaIndexMaintenanceReason } {
+	let unknown: ReplicaIndexMaintenanceReason | undefined;
+	const sorted = [...keys].sort((leftKey, rightKey) => {
+		if (unknown !== undefined || leftKey === rightKey) return 0;
+		const left = records.get(leftKey);
+		const right = records.get(rightKey);
+		if (left === undefined || right === undefined) {
+			unknown = reason(
+				'missing_index_record',
+				path,
+				`ordered index references missing record ${left === undefined ? leftKey : rightKey}`
+			);
+			return 0;
+		}
+		const compared = compareReplicaOrder(
+			order,
+			left.fields,
+			right.fields,
+			variables
+		);
+		if (compared.result === 'unknown') {
+			unknown = compared.reason;
+			return 0;
+		}
+		if (compared.result === 'equal') {
+			unknown = reason(
+				'non_unique_order',
+				path,
+				`distinct records ${leftKey} and ${rightKey} have no deterministic order`
+			);
+			return 0;
+		}
+		return compared.result === 'less' ? -1 : 1;
+	});
+	return unknown === undefined
+		? { records: Object.freeze(sorted) }
+		: { reason: unknown };
+}
+
+export function relationshipChangeMatches(
+	planValue: RegisteredPlan,
+	index: ReplicaIndexMaintenanceIndex,
+	change: ReplicaIndexRelationshipChange
+): boolean {
+	return (
+		planValue.kind === 'relationship' &&
+		planValue.parentModel === change.sourceModel &&
+		planValue.field === change.field &&
+		planValue.targetModel === change.targetModel &&
+		index.metadata.parent === change.sourceKey
+	);
+}
+
+export function isRelationshipChange(
+	change: ReplicaIndexSemanticChange
+): change is ReplicaIndexRelationshipChange {
+	return change.kind === 'link' || change.kind === 'unlink';
+}
+
+export function validateDependencies(value: readonly string[]): readonly string[] {
+	if (!Array.isArray(value)) throw new TypeError('dependencies must be an array');
+	const seen = new Set<string>();
+	for (const dependency of value) {
+		validateName(dependency, 'dependency');
+		if (seen.has(dependency)) {
+			throw new TypeError(`duplicate dependency: ${dependency}`);
+		}
+		seen.add(dependency);
+	}
+	return value;
+}
+
+export function intersects(
+	left: readonly string[],
+	right: ReadonlySet<string>
+): boolean {
+	return left.some((value) => right.has(value));
+}
+
+export function recordKeyMatchesModel(key: string, model: string): boolean {
+	return key.startsWith(`record:${encodeURIComponent(model)}:`);
+}
+
+export function firstDuplicate(values: readonly string[]): string | undefined {
+	const seen = new Set<string>();
+	for (const value of values) {
+		if (seen.has(value)) return value;
+		seen.add(value);
+	}
+	return undefined;
+}
+
+export function write(
+	indexKey: string,
+	records: readonly string[]
+): ReplicaIndexMaintenanceDecision {
+	return Object.freeze({
+		kind: 'write' as const,
+		indexKey,
+		records: Object.freeze([...records]),
+		complete: true as const
+	});
+}
+
+export function stale(
+	indexKey: string,
+	reasonValue: ReplicaIndexMaintenanceReason
+): ReplicaIndexMaintenanceDecision {
+	return Object.freeze({
+		kind: 'stale' as const,
+		indexKey,
+		reason: reasonValue
+	});
+}
+
+export function unchanged(indexKey: string): ReplicaIndexMaintenanceDecision {
+	return Object.freeze({ kind: 'unchanged' as const, indexKey });
+}
+
+export function reason(
+	code: ReplicaIndexMaintenanceReasonCode,
+	path: readonly (string | number)[],
+	message: string
+): ReplicaIndexMaintenanceReason {
+	return Object.freeze({
+		code,
+		path: Object.freeze([...path]),
+		message
+	});
+}
+
+export function sameStringList(
+	left: readonly string[],
+	right: readonly string[]
+): boolean {
+	return (
+		left.length === right.length &&
+		left.every((value, index) => value === right[index])
+	);
+}
+
+export function sameValue(left: unknown, right: unknown): boolean {
+	return canonicalValue(left) === canonicalValue(right);
+}
+
+export function cloneRecord(
+	value: Readonly<Record<string, ReplicaValue>>
+): Readonly<Record<string, ReplicaValue>> {
+	return Object.freeze(
+		Object.fromEntries(
+			Object.entries(value)
+				.sort(([left], [right]) => compareCodeUnits(left, right))
+				.map(([key, entry]) => [key, cloneValue(entry)])
+		)
+	);
+}
+
+export function cloneValue(value: ReplicaValue): ReplicaValue {
+	if (Array.isArray(value)) return Object.freeze(value.map(cloneValue));
+	if (value !== null && typeof value === 'object') {
+		return cloneRecord(value as Readonly<Record<string, ReplicaValue>>);
+	}
+	return value;
+}
+
+export function canonicalValue(value: unknown): string {
+	if (value === null) return 'null';
+	if (typeof value === 'string') return JSON.stringify(value);
+	if (typeof value === 'boolean') return value ? 'true' : 'false';
+	if (typeof value === 'number') {
+		if (!Number.isFinite(value)) throw new TypeError('canonical values must be finite');
+		return Object.is(value, -0) ? '0' : JSON.stringify(value);
+	}
+	if (Array.isArray(value)) {
+		return `[${value.map(canonicalValue).join(',')}]`;
+	}
+	if (typeof value === 'object') {
+		const entries = Object.entries(value as Readonly<Record<string, unknown>>)
+			.filter(([, entry]) => entry !== undefined)
+			.sort(([left], [right]) => compareCodeUnits(left, right));
+		return `{${entries
+			.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalValue(entry)}`)
+			.join(',')}}`;
+	}
+	throw new TypeError('canonical values must be JSON-compatible');
+}
+
+export function validateName(value: string, description: string): void {
+	if (typeof value !== 'string' || value.length === 0) {
+		throw new TypeError(`${description} must be a non-empty string`);
+	}
+}
diff --git a/js/src/replica/index-maintenance/implementation.ts b/js/src/replica/index-maintenance/implementation.ts
new file mode 100644
index 00000000..4749f593
--- /dev/null
+++ b/js/src/replica/index-maintenance/implementation.ts
@@ -0,0 +1,4 @@
+/** Re-export surface for index-maintenance modules (body-split). */
+export * from './types.js';
+export * from './engine.js';
+export * from './registry.js';
diff --git a/js/src/replica/index-maintenance/index.ts b/js/src/replica/index-maintenance/index.ts
new file mode 100644
index 00000000..2aefcba5
--- /dev/null
+++ b/js/src/replica/index-maintenance/index.ts
@@ -0,0 +1,19 @@
+export {
+	createReplicaIndexMaintenanceRegistry,
+	formatReplicaIndexStaleReason
+} from './implementation.js';
+export type {
+	ReplicaIndexDependencyChange,
+	ReplicaIndexMaintenanceDecision,
+	ReplicaIndexMaintenanceIndex,
+	ReplicaIndexMaintenanceReason,
+	ReplicaIndexMaintenanceReasonCode,
+	ReplicaIndexMaintenanceRecord,
+	ReplicaIndexMaintenanceRegistry,
+	ReplicaIndexMaintenanceSnapshot,
+	ReplicaIndexPlanRegistration,
+	ReplicaIndexRecordChange,
+	ReplicaIndexRelationshipChange,
+	ReplicaIndexSemanticChange,
+	ReplicaIndexSemanticLayer
+} from './implementation.js';
diff --git a/js/src/replica/index-maintenance/registry.ts b/js/src/replica/index-maintenance/registry.ts
new file mode 100644
index 00000000..719af226
--- /dev/null
+++ b/js/src/replica/index-maintenance/registry.ts
@@ -0,0 +1,97 @@
+import type { GraphqlVariables } from '../../types.js';
+import type { DistributedTrustedPreset } from '../../protocol.js';
+import { canonicalizeOperationVariables } from '../identity.js';
+import { compareCodeUnits } from '../../lib/compare-code-units.js';
+import type { ReplicaOperationArtifact } from '../types.js';
+import type {
+	ReplicaIndexMaintenanceDecision,
+	ReplicaIndexMaintenanceRegistry,
+	ReplicaIndexMaintenanceSnapshot,
+	ReplicaIndexPlanRegistration,
+	ReplicaIndexSemanticLayer
+} from './types.js';
+import {
+	applyLayers,
+	canonicalValue,
+	compilePlans,
+	evaluatePlan,
+	instantiatePlans,
+	planAffected,
+	reason,
+	stale,
+	validateIndexes,
+	type RegisteredPlan
+} from './engine.js';
+
+class PurposeBuiltIndexMaintenanceRegistry
+	implements ReplicaIndexMaintenanceRegistry
+{
+	readonly #plans = new Map<string, readonly RegisteredPlan[]>();
+	#nextRegistration = 0;
+
+	registerOperation<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables
+	): ReplicaIndexPlanRegistration {
+		const canonicalVariables = canonicalizeOperationVariables(artifact, variables);
+		const id = `${artifact.id}:${canonicalValue(canonicalVariables)}:${++this.#nextRegistration}`;
+		this.#plans.set(id, compilePlans(id, artifact, canonicalVariables));
+		let active = true;
+		return Object.freeze({
+			id,
+			dispose: () => {
+				if (!active) return;
+				active = false;
+				this.#plans.delete(id);
+			}
+		});
+	}
+
+	evaluate(
+		snapshot: ReplicaIndexMaintenanceSnapshot,
+		layers: readonly ReplicaIndexSemanticLayer[],
+		trustedPresets: readonly DistributedTrustedPreset[] = Object.freeze([])
+	): readonly ReplicaIndexMaintenanceDecision[] {
+		const applied = applyLayers(snapshot.records, layers);
+		const indexes = validateIndexes(snapshot.indexes);
+		const plansByIndex = instantiatePlans(
+			[...this.#plans.values()].flat(),
+			indexes
+		);
+		const decisions: ReplicaIndexMaintenanceDecision[] = [];
+		for (const [indexKey, plans] of [...plansByIndex].sort(([left], [right]) =>
+			compareCodeUnits(left, right)
+		)) {
+			const index = indexes.get(indexKey);
+			if (index === undefined) continue;
+			const affected = plans.filter((plan) => planAffected(plan, index, applied));
+			if (affected.length === 0) continue;
+			const signatures = new Set(affected.map(({ signature }) => signature));
+			if (signatures.size !== 1) {
+				decisions.push(
+					stale(
+						indexKey,
+						reason(
+							'conflicting_index_plan',
+							['indexes', indexKey],
+							'multiple active artifacts disagree about one semantic index plan'
+						)
+					)
+				);
+				continue;
+			}
+			decisions.push(
+				evaluatePlan(affected[0]!, index, applied, trustedPresets)
+			);
+		}
+		return Object.freeze(decisions);
+	}
+
+	clear(): void {
+		this.#plans.clear();
+	}
+}
+
+export function createReplicaIndexMaintenanceRegistry(): ReplicaIndexMaintenanceRegistry {
+	return new PurposeBuiltIndexMaintenanceRegistry();
+}
diff --git a/js/src/replica/index-maintenance/types.ts b/js/src/replica/index-maintenance/types.ts
new file mode 100644
index 00000000..536d1f62
--- /dev/null
+++ b/js/src/replica/index-maintenance/types.ts
@@ -0,0 +1,103 @@
+import type { GraphqlVariables } from '../../types.js';
+import type { DistributedTrustedPreset } from '../../protocol.js';
+import type {
+	ReplicaIndexCoverage,
+	ReplicaIndexSemanticChange,
+	ReplicaOperationArtifact,
+	ReplicaValue
+} from '../types.js';
+
+export type {
+	ReplicaIndexDependencyChange,
+	ReplicaIndexRecordChange,
+	ReplicaIndexRelationshipChange,
+	ReplicaIndexSemanticChange
+} from '../types.js';
+
+export type ReplicaIndexMaintenanceRecord = {
+	readonly key: string;
+	readonly model: string;
+	readonly fields: Readonly<Record<string, ReplicaValue>>;
+};
+
+export type ReplicaIndexMaintenanceIndex = {
+	readonly key: string;
+	readonly records: readonly string[];
+	readonly complete: boolean;
+	readonly metadata: {
+		readonly parent?: string;
+		readonly field: string;
+		readonly arguments: Readonly<Record<string, ReplicaValue>>;
+		readonly coverage: ReplicaIndexCoverage;
+		readonly dependencies: readonly string[];
+		readonly staleReason?: string;
+	};
+};
+
+export type ReplicaIndexSemanticLayer = {
+	readonly id: string;
+	readonly changes: readonly ReplicaIndexSemanticChange[];
+};
+
+export type ReplicaIndexMaintenanceSnapshot = {
+	readonly records: readonly ReplicaIndexMaintenanceRecord[];
+	readonly indexes: readonly ReplicaIndexMaintenanceIndex[];
+};
+
+export type ReplicaIndexMaintenanceReasonCode =
+	| 'aggregate_dependency_changed'
+	| 'conflicting_index_plan'
+	| 'dependency_changed'
+	| 'duplicate_index_record'
+	| 'index_incomplete'
+	| 'invalid_index_metadata'
+	| 'missing_index_record'
+	| 'missing_order_plan'
+	| 'missing_parent_record'
+	| 'non_unique_order'
+	| 'relationship_dependency_missing'
+	| 'relationship_maintenance_revalidate'
+	| 'relationship_mapping_unknown'
+	| 'unsupported_cardinality'
+	| import('../query-plan.js').ReplicaQueryPlanReasonCode;
+
+export type ReplicaIndexMaintenanceReason = {
+	readonly code: ReplicaIndexMaintenanceReasonCode;
+	readonly path: readonly (string | number)[];
+	readonly message: string;
+};
+
+export type ReplicaIndexMaintenanceDecision =
+	| {
+			readonly kind: 'write';
+			readonly indexKey: string;
+			readonly records: readonly string[];
+			readonly complete: true;
+	  }
+	| {
+			readonly kind: 'stale';
+			readonly indexKey: string;
+			readonly reason: ReplicaIndexMaintenanceReason;
+	  }
+	| {
+			readonly kind: 'unchanged';
+			readonly indexKey: string;
+	  };
+
+export type ReplicaIndexPlanRegistration = {
+	readonly id: string;
+	dispose(): void;
+};
+
+export interface ReplicaIndexMaintenanceRegistry {
+	registerOperation<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables
+	): ReplicaIndexPlanRegistration;
+	evaluate(
+		snapshot: ReplicaIndexMaintenanceSnapshot,
+		layers: readonly ReplicaIndexSemanticLayer[],
+		trustedPresets?: readonly DistributedTrustedPreset[]
+	): readonly ReplicaIndexMaintenanceDecision[];
+	clear(): void;
+}
diff --git a/js/src/replica/index.ts b/js/src/replica/index.ts
new file mode 100644
index 00000000..445e4227
--- /dev/null
+++ b/js/src/replica/index.ts
@@ -0,0 +1,227 @@
+export { createDistributedReplica } from './distributed-replica.js';
+export {
+	createReplicaDevelopmentCapability,
+	createReplicaDiagnostics,
+	inspectReplicaCommandArtifact,
+	inspectReplicaOperationArtifact
+} from './diagnostics.js';
+export type {
+	ReplicaArtifactSourceLocation,
+	ReplicaCommandArtifactInspection,
+	ReplicaCommandEffectInspection,
+	ReplicaDevelopmentCapability,
+	ReplicaDiagnosticEvent,
+	ReplicaDiagnosticEventInput,
+	ReplicaDiagnosticFieldValueContext,
+	ReplicaDiagnosticFieldValuePolicy,
+	ReplicaDiagnosticIndex,
+	ReplicaDiagnosticIndexInput,
+	ReplicaDiagnosticLayer,
+	ReplicaDiagnosticLayerInput,
+	ReplicaDiagnosticReceipt,
+	ReplicaDiagnosticReceiptExpectationInput,
+	ReplicaDiagnosticReceiptInput,
+	ReplicaDiagnosticRecord,
+	ReplicaDiagnosticRecordInput,
+	ReplicaDiagnosticReasonContext,
+	ReplicaDiagnosticReasonPolicy,
+	ReplicaDiagnostics,
+	ReplicaDiagnosticsOptions,
+	ReplicaDiagnosticsSink,
+	ReplicaDiagnosticsSnapshot,
+	ReplicaDiagnosticScopeInput,
+	ReplicaDiagnosticStateInput,
+	ReplicaOperationArtifactInspection,
+	ReplicaOperationIndexInspection,
+	ReplicaOperationInjectedFieldInspection
+} from './diagnostics.js';
+export { createReplicaGraphqlTransport } from './graphql-transport.js';
+export type {
+	ReplicaGraphqlTransport,
+	ReplicaGraphqlTransportOptions
+} from './graphql-transport.js';
+export {
+	canonicalizeOperationVariables,
+	replicaIndexKey,
+	replicaRecordKey
+} from './identity.js';
+export {
+	prepareReplicaCommand,
+	ReplicaCommandContractError,
+	verifyReplicaCommandReceipt
+} from './commands.js';
+export {
+	createReplicaCommandRuntime,
+	ReplicaCommandRuntimeError
+} from './command-runtime.js';
+export {
+	createReplicaIndexedDbPersistence,
+	REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED
+} from './persistence.js';
+export type {
+	ReplicaBoundCommand,
+	ReplicaBoundCommands,
+	ReplicaCommandCallOptions,
+	ReplicaCommandProjectedOutcome,
+	ReplicaCommandReceipt,
+	ReplicaCommandRecoveryReceipt,
+	ReplicaCommandRuntime,
+	ReplicaCommandRuntimeErrorCode,
+	ReplicaCommandRuntimeOptions,
+	ReplicaCommandStatus,
+	ReplicaCommandStatusArtifact,
+	ReplicaCommandStatusRequest,
+	ReplicaCommandTransport,
+	ReplicaCommandTransportRequest,
+	ReplicaCommandTransportResult
+} from './command-runtime.js';
+export type {
+	ReplicaIndexedDbFactory,
+	ReplicaIndexedDbPersistence,
+	ReplicaIndexedDbPersistenceOptions,
+	ReplicaPersistenceModelPolicy,
+	ReplicaPersistencePolicy
+} from './persistence.js';
+export type {
+	PrepareReplicaCommandOptions,
+	ReplicaCommandArtifact,
+	ReplicaCommandConfirmation,
+	ReplicaCommandConfirmations,
+	ReplicaCommandContractErrorCode,
+	ReplicaCommandDirectProjection,
+	ReplicaCommandEffect,
+	ReplicaCommandEffectExpression,
+	ReplicaCommandEffectField,
+	ReplicaCommandEffectKey,
+	ReplicaCommandEffectRelationship,
+	ReplicaCommandEffects,
+	ReplicaCommandGenerators,
+	ReplicaCommandInputDefault,
+	ReplicaCommandInputDefaults,
+	ReplicaCommandRevalidationPlan,
+	ReplicaCommandScalarCodec,
+	ReplicaCommandShape,
+	ReplicaCommandTypeDefinition,
+	ReplicaCommandTypeField,
+	ReplicaCommandVariables,
+	ReplicaTrustedPresetDescriptor,
+	ReplicaPreparedCommand,
+	ReplicaPreparedCommandEffect,
+	ReplicaPreparedConfirmation,
+	ReplicaPreparedConfirmations,
+	ReplicaPreparedEffectField,
+	ReplicaPreparedEffectKey,
+	ReplicaReceiptVerification
+} from './commands.js';
+export {
+	compareReplicaOrder,
+	decideReplicaPaginationMaintenance,
+	evaluateReplicaFilter
+} from './query-plan.js';
+export {
+	createReplicaIndexMaintenanceRegistry,
+	formatReplicaIndexStaleReason
+} from './index-maintenance.js';
+export type {
+	ReplicaIndexDependencyChange,
+	ReplicaIndexMaintenanceDecision,
+	ReplicaIndexMaintenanceIndex,
+	ReplicaIndexMaintenanceReason,
+	ReplicaIndexMaintenanceReasonCode,
+	ReplicaIndexMaintenanceRecord,
+	ReplicaIndexMaintenanceRegistry,
+	ReplicaIndexMaintenanceSnapshot,
+	ReplicaIndexPlanRegistration,
+	ReplicaIndexRecordChange,
+	ReplicaIndexRelationshipChange,
+	ReplicaIndexSemanticChange,
+	ReplicaIndexSemanticLayer
+} from './index-maintenance.js';
+export type {
+	ReplicaFilterEvaluation,
+	ReplicaFilterEvaluationOptions,
+	ReplicaOrderComparison,
+	ReplicaPaginationChange,
+	ReplicaPaginationMaintenanceDecision,
+	ReplicaQueryPlanPath,
+	ReplicaQueryPlanReason,
+	ReplicaQueryPlanReasonCode,
+	ReplicaRelationshipFilterRequest
+} from './query-plan.js';
+export type {
+	DistributedReplicaOptions,
+	DistributedReplica,
+	ReplicaArgumentsArtifact,
+	ReplicaArgumentValue,
+	ReplicaAuthoritativeScope,
+	ReplicaBaseWriter,
+	ReplicaBranchSemantic,
+	ReplicaClientSurface,
+	ReplicaCoverageArtifact,
+	ReplicaDehydratedState,
+	ReplicaFilterArtifact,
+	ReplicaFilterExpression,
+	ReplicaFilterFieldArtifact,
+	ReplicaFilterLiteral,
+	ReplicaFilterOperand,
+	ReplicaFilterOperator,
+	ReplicaIdentity,
+	ReplicaIndexCoverage,
+	ReplicaIndexInspection,
+	ReplicaIndexTarget,
+	ReplicaListValue,
+	ReplicaLiveObserver,
+	ReplicaLiveState,
+	ReplicaLiteralValue,
+	ReplicaModelArtifact,
+	ReplicaObjectBranch,
+	ReplicaObjectMember,
+	ReplicaObjectSelection,
+	ReplicaObjectValue,
+	ReplicaOperationArtifact,
+	ReplicaOperationSourceLocation,
+	ReplicaOperationProtocol,
+	ReplicaOrderArtifact,
+	ReplicaOrderFieldArtifact,
+	ReplicaOrderTieBreakerArtifact,
+	ReplicaOptimisticWriter,
+	ReplicaPaginationArtifact,
+	ReplicaPaginationDisposition,
+	ReplicaProtocolOperationArtifact,
+	ReplicaRecordInspection,
+	ReplicaRecordPatch,
+	ReplicaRevalidationPlan,
+	ReplicaRevalidationRelationship,
+	ReplicaRevision,
+	ReplicaRelationshipArtifact,
+	ReplicaRelationshipKeyMapping,
+	ReplicaRelationshipKind,
+	ReplicaResultEnvelope,
+	ReplicaRowPolicyArtifact,
+	ReplicaRootSelection,
+	ReplicaScalarSelection,
+	ReplicaSelectionStorage,
+	ReplicaSparse,
+	ReplicaSnapshot,
+	ReplicaStatus,
+	ReplicaTransport,
+	ReplicaTransportRequest,
+	ReplicaVariableValue,
+	ReplicaVariableCodecArtifact,
+	ReplicaVariableEnumInputRef,
+	ReplicaVariableFilterInputDefinition,
+	ReplicaVariableFilterInputField,
+	ReplicaVariableFilterInputRelationship,
+	ReplicaVariableFilterInputTarget,
+	ReplicaVariableInputDefinition,
+	ReplicaVariableInputRef,
+	ReplicaVariableListInputRef,
+	ReplicaVariableNamedInputRef,
+	ReplicaVariableOrderInputDefinition,
+	ReplicaVariableOrderInputField,
+	ReplicaVariableScalarInputRef,
+	ReplicaValue,
+	ReplicaWatch,
+	ReplicaWriteSource,
+	WatchReplicaOptions
+} from './types.js';
diff --git a/js/src/replica/materialize.ts b/js/src/replica/materialize.ts
new file mode 100644
index 00000000..ba2d787d
--- /dev/null
+++ b/js/src/replica/materialize.ts
@@ -0,0 +1,237 @@
+import type { CacheIndex, CacheReader } from '../internal/cache-engine.js';
+import type { GraphqlVariables } from '../types.js';
+import { replicaIndexKey, resolveArguments } from './identity.js';
+import {
+	runtimeRoot,
+	type RuntimeObjectBranch,
+	type RuntimeObjectSelection,
+	type RuntimeRootSelection
+} from './selection.js';
+import type { ReplicaOperationArtifact, ReplicaSparse } from './types.js';
+
+export type MaterializedReplicaResult<TData> = {
+	readonly data: ReplicaSparse<TData>;
+	readonly complete: boolean;
+	readonly stale: boolean;
+	readonly identitySignature: string;
+};
+
+type MaterializedObject = {
+	value?: Readonly<Record<string, unknown>>;
+	complete: boolean;
+	stale: boolean;
+	identitySignature: string;
+};
+
+type MaterializedBranch = {
+	value?: unknown;
+	present: boolean;
+	complete: boolean;
+	stale: boolean;
+	identitySignature: string;
+};
+
+type RuntimeBranchSelection = RuntimeRootSelection | RuntimeObjectBranch;
+
+export function materializeReplicaOperation<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	reader: CacheReader,
+	artifact: ReplicaOperationArtifact<TData, TVariables>,
+	variables: TVariables
+): MaterializedReplicaResult<TData> {
+	const output: Record<string, unknown> = {};
+	let complete = true;
+	let stale = false;
+	const signatures: string[] = [];
+	for (const artifactRoot of artifact.roots) {
+		const root = runtimeRoot(artifactRoot);
+		const argumentsValue = resolveArguments(root.arguments, variables, root.coverage);
+		const indexKey = replicaIndexKey({ field: root.field, arguments: argumentsValue });
+		const index = reader.index(indexKey);
+		const branch = materializeBranch(reader, root, index, variables);
+		if (branch.present) {
+			defineOutputValue(output, root.responseKey, branch.value);
+		}
+		complete &&= branch.complete;
+		stale ||= branch.stale;
+		signatures.push(`${indexKey}:${branch.identitySignature}`);
+	}
+	return Object.freeze({
+		data: Object.freeze(output) as ReplicaSparse<TData>,
+		complete,
+		stale,
+		identitySignature: signatures.join('|')
+	});
+}
+
+function materializeBranch(
+	reader: CacheReader,
+	selection: RuntimeBranchSelection,
+	index: CacheIndex | undefined,
+	variables: GraphqlVariables
+): MaterializedBranch {
+	if (!index || !index.metadata) {
+		return {
+			present: false,
+			complete: false,
+			stale: false,
+			identitySignature: 'missing-index'
+		};
+	}
+	const stale = index.metadata.staleReason !== undefined;
+	/*
+	 * Completeness and freshness are independent. A stale complete index still
+	 * has a structurally materializable result and remains visible during
+	 * stale-while-revalidate. Partial/lifecycle-invalidated indexes explicitly
+	 * carry `complete=false` and remain sparse.
+	 */
+	const indexComplete = index.complete;
+	if (index.metadata.nullValue) {
+		return {
+			value: null,
+			present: true,
+			complete: indexComplete && selection.nullable,
+			stale,
+			identitySignature: `null:${index.metadata.staleReason ?? ''}`
+		};
+	}
+
+	if (selection.cardinality === 'one') {
+		const key = index.records[0];
+		if (key === undefined) {
+			return {
+				present: false,
+				complete: false,
+				stale,
+				identitySignature: `missing-record:${index.metadata.staleReason ?? ''}`
+			};
+		}
+		const object = materializeObject(reader, selection.selection, key, variables);
+		return {
+			value: object.value,
+			present: object.value !== undefined,
+			complete: indexComplete && index.records.length === 1 && object.complete,
+			stale: stale || object.stale,
+			identitySignature: object.identitySignature
+		};
+	}
+
+	const values: Readonly<Record<string, unknown>>[] = [];
+	let childrenComplete = true;
+	let childrenStale = false;
+	const signatures: string[] = [];
+	for (const key of index.records) {
+		const object = materializeObject(reader, selection.selection, key, variables);
+		if (object.value !== undefined) values.push(object.value);
+		else childrenComplete = false;
+		childrenComplete &&= object.complete;
+		childrenStale ||= object.stale;
+		signatures.push(object.identitySignature);
+	}
+	return {
+		value: Object.freeze(values),
+		present: true,
+		complete: indexComplete && childrenComplete,
+		stale: stale || childrenStale,
+		identitySignature: signatures.join(',')
+	};
+}
+
+function materializeObject(
+	reader: CacheReader,
+	selection: RuntimeObjectSelection,
+	key: string,
+	variables: GraphqlVariables
+): MaterializedObject {
+	const record = reader.recordMeta(key);
+	if (!record) {
+		return {
+			complete: false,
+			stale: false,
+			identitySignature: `${key}:missing`
+		};
+	}
+	const output: Record<string, unknown> = {};
+	let complete = true;
+	let stale = false;
+	const nestedSignatures: string[] = [];
+	for (const member of selection.members) {
+		if (member.kind !== 'scalar') continue;
+		const presence = reader.field(key, member.field);
+		if (!presence.present || (presence.value === null && !member.nullable)) {
+			complete = false;
+			continue;
+		}
+		if (member.expose !== false) {
+			defineOutputValue(output, member.responseKey, presence.value);
+		}
+	}
+
+	for (const member of selection.members) {
+		if (member.kind !== 'branch') continue;
+		const branchResult = materializeNestedBranch(
+			reader,
+			key,
+			record.incarnation,
+			member,
+			variables
+		);
+		if (member.expose !== false && branchResult.present) {
+			defineOutputValue(output, member.responseKey, branchResult.value);
+		}
+		complete &&= branchResult.complete;
+		stale ||= branchResult.stale;
+		nestedSignatures.push(`${member.field}:${branchResult.identitySignature}`);
+	}
+
+	return {
+		value: Object.freeze(output),
+		complete,
+		stale,
+		identitySignature: `${key}@${record.incarnation}[${nestedSignatures.join('|')}]`
+	};
+}
+
+function materializeNestedBranch(
+	reader: CacheReader,
+	parentKey: string,
+	parentIncarnation: string,
+	selection: RuntimeObjectBranch,
+	variables: GraphqlVariables
+): MaterializedBranch {
+	const argumentsValue = resolveArguments(
+		selection.arguments,
+		variables,
+		selection.coverage
+	);
+	const indexKey = replicaIndexKey({
+		parent: parentKey,
+		field: selection.field,
+		arguments: argumentsValue
+	});
+	const index = reader.index(indexKey);
+	if (index?.metadata?.parentIncarnation !== parentIncarnation) {
+		return {
+			present: false,
+			complete: false,
+			stale: index !== undefined,
+			identitySignature: `parent-incarnation-mismatch:${parentIncarnation}`
+		};
+	}
+	return materializeBranch(reader, selection, index, variables);
+}
+
+function defineOutputValue(
+	output: Record<string, unknown>,
+	key: string,
+	value: unknown
+): void {
+	Object.defineProperty(output, key, {
+		value,
+		enumerable: true,
+		configurable: false,
+		writable: false
+	});
+}
diff --git a/js/src/replica/normalize.ts b/js/src/replica/normalize.ts
new file mode 100644
index 00000000..2193e88e
--- /dev/null
+++ b/js/src/replica/normalize.ts
@@ -0,0 +1,549 @@
+import type {
+	BaseCacheWriter,
+	CacheIndexMetadata,
+	CacheValue,
+	RecordKey,
+	Revision
+} from '../internal/cache-engine.js';
+import type { DistributedRecordRevision } from '../protocol.js';
+import type { GqlError, GraphqlVariables } from '../types.js';
+import {
+	cloneJsonValue,
+	coverageFromArtifact,
+	replicaIndexKey,
+	replicaRecordKey,
+	resolveArguments
+} from './identity.js';
+import {
+	embeddedRecordKey,
+	runtimeRoot,
+	type RuntimeObjectBranch,
+	type RuntimeObjectSelection,
+	type RuntimeRootSelection
+} from './selection.js';
+import type {
+	ReplicaOperationArtifact,
+	ReplicaRevision,
+	ReplicaResultEnvelope
+} from './types.js';
+
+import { deepEqual } from '../lib/deep-equal.js';
+
+export type ReplicaNormalizationSummary = {
+	readonly wrote: boolean;
+	readonly partial: boolean;
+	readonly indexKeys: readonly string[];
+};
+
+export type ReplicaProtocolRecordResolution = {
+	readonly evidence: DistributedRecordRevision;
+	/** False means a same-scope newer base record already won. */
+	readonly apply: boolean;
+};
+
+export type ReplicaNormalizationProtocol = {
+	readonly indexRevision: ReplicaRevision;
+	readonly writeIndexes: boolean;
+	readonly indexesComplete: boolean;
+	/**
+	 * Missing causal record evidence may use operation-local snapshot storage.
+	 * Such rows remain renderable without impersonating a shared normalized
+	 * identity.
+	 */
+	readonly allowSnapshotOnlyRecords: boolean;
+	readonly record: (
+		path: readonly string[],
+		model: string,
+		key: string,
+		fields: Readonly<Record<string, CacheValue>>
+	) => ReplicaProtocolRecordResolution | undefined;
+};
+
+type NormalizedBranch = {
+	keys: RecordKey[];
+	nullValue: boolean;
+	partial: boolean;
+};
+
+type ErrorPaths = {
+	global: boolean;
+	paths: readonly (readonly (string | number)[])[];
+};
+
+type RuntimeBranchSelection = RuntimeRootSelection | RuntimeObjectBranch;
+
+export function normalizeReplicaResult<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	writer: BaseCacheWriter,
+	artifact: ReplicaOperationArtifact<TData, TVariables>,
+	variables: TVariables,
+	envelope: ReplicaResultEnvelope<TData>,
+	protocol: ReplicaNormalizationProtocol
+): ReplicaNormalizationSummary {
+	validateArtifact(artifact);
+	const snapshotRevision = protocol.indexRevision;
+	const errors = collectErrorPaths(envelope.errors ?? []);
+	if (errors.global || envelope.data === undefined) {
+		return Object.freeze({ wrote: false, partial: errors.global, indexKeys: [] });
+	}
+	if (envelope.data === null && (envelope.errors?.length ?? 0) > 0) {
+		// `data: null` is a valid GraphQL error result after non-null propagation.
+		// The ingress coordinator will stale the operation roots without replacing
+		// the last known-good memberships.
+		return Object.freeze({ wrote: false, partial: true, indexKeys: [] });
+	}
+	if (envelope.data === null || !isObject(envelope.data)) {
+		throw new TypeError(`operation ${artifact.id} returned a non-object GraphQL data value`);
+	}
+
+	let wrote = false;
+	let partial = false;
+	const indexKeys: string[] = [];
+	for (const artifactRoot of artifact.roots) {
+		const root = runtimeRoot(artifactRoot);
+		const path: readonly (string | number)[] = [root.responseKey];
+		const hasValue = Object.prototype.hasOwnProperty.call(envelope.data, root.responseKey);
+		const blocked = pathBlocked(errors, path);
+		const argumentsValue = resolveArguments(root.arguments, variables, root.coverage);
+		const key = replicaIndexKey({ field: root.field, arguments: argumentsValue });
+		const hasErrors = pathHasErrors(errors, path);
+		const rawValue = hasValue ? envelope.data[root.responseKey] : undefined;
+		if (blocked || !hasValue || (rawValue === null && hasErrors)) {
+			wrote =
+				protocol.writeIndexes
+					? writer.markIndexStale(
+							key,
+							hasErrors ? 'graphql-partial-error' : 'incomplete-result',
+							snapshotRevision
+						) || wrote
+					: wrote;
+			indexKeys.push(key);
+			partial = true;
+			continue;
+		}
+		const branch = normalizeBranch(
+			writer,
+			artifact.id,
+			root,
+			rawValue,
+			path,
+			key,
+			snapshotRevision,
+			variables,
+			errors,
+			protocol,
+			indexKeys
+		);
+		const rootPartial =
+			branch.partial ||
+			hasErrors ||
+			!protocol.indexesComplete;
+		const metadata = indexMetadata(
+			root,
+			argumentsValue,
+			branch,
+			rootPartial,
+			hasErrors
+		);
+		if (
+			protocol.writeIndexes &&
+			writer.writeIndex({
+				key,
+				revision: snapshotRevision,
+				records: branch.keys,
+				complete: !rootPartial,
+				metadata
+			})
+		) {
+			wrote = true;
+		}
+		indexKeys.push(key);
+		partial ||= rootPartial;
+	}
+	return Object.freeze({
+		wrote,
+		partial,
+		indexKeys: Object.freeze(indexKeys)
+	});
+}
+
+function normalizeBranch(
+	writer: BaseCacheWriter,
+	artifactId: string,
+	selection: RuntimeBranchSelection,
+	value: unknown,
+	path: readonly (string | number)[],
+	indexKey: string,
+	snapshotRevision: Revision,
+	variables: GraphqlVariables,
+	errors: ErrorPaths,
+	protocol: ReplicaNormalizationProtocol,
+	indexKeys: string[]
+): NormalizedBranch {
+	if (value === null) {
+		if (!selection.nullable && !pathHasErrors(errors, path)) {
+			throw new TypeError(
+				`operation ${artifactId} returned null for non-null field ${pathLabel(path)}`
+			);
+		}
+		return { keys: [], nullValue: true, partial: false };
+	}
+	if (value === undefined) return { keys: [], nullValue: false, partial: true };
+	if (selection.cardinality === 'one') {
+		const object = normalizeObject(
+			writer,
+			artifactId,
+			selection.selection,
+			value,
+			path,
+			indexKey,
+			undefined,
+			snapshotRevision,
+			variables,
+			errors,
+			protocol,
+			indexKeys
+		);
+		return {
+			keys: object.key === undefined ? [] : [object.key],
+			nullValue: false,
+			partial: object.partial
+		};
+	}
+	if (!Array.isArray(value)) {
+		throw new TypeError(
+			`operation ${artifactId} returned a non-list value for ${pathLabel(path)}`
+		);
+	}
+	const keys: RecordKey[] = [];
+	let partial = false;
+	for (const [ordinal, entry] of value.entries()) {
+		const entryPath = [...path, ordinal];
+		if (entry === null || entry === undefined) {
+			if (pathHasErrors(errors, entryPath)) {
+				partial = true;
+				continue;
+			}
+			throw new TypeError(
+				`operation ${artifactId} returned null for non-null list item ${pathLabel(
+					entryPath
+				)}`
+			);
+		}
+		const object = normalizeObject(
+			writer,
+			artifactId,
+			selection.selection,
+			entry,
+			entryPath,
+			indexKey,
+			ordinal,
+			snapshotRevision,
+			variables,
+			errors,
+			protocol,
+			indexKeys
+		);
+		if (object.key === undefined) partial = true;
+		else keys.push(object.key);
+		partial ||= object.partial;
+	}
+	return { keys, nullValue: false, partial };
+}
+
+function normalizeObject(
+	writer: BaseCacheWriter,
+	artifactId: string,
+	selection: RuntimeObjectSelection,
+	value: unknown,
+	path: readonly (string | number)[],
+	enclosingIndexKey: string,
+	ordinal: number | undefined,
+	snapshotRevision: Revision,
+	variables: GraphqlVariables,
+	errors: ErrorPaths,
+	protocol: ReplicaNormalizationProtocol,
+	indexKeys: string[]
+): { key?: RecordKey; partial: boolean } {
+	if (pathBlocked(errors, path)) return { partial: true };
+	if (!isObject(value)) {
+		throw new TypeError(
+			`operation ${artifactId} returned a non-object value for ${pathLabel(path)}`
+		);
+	}
+
+	const fields: Record<string, CacheValue> = Object.create(null) as Record<
+		string,
+		CacheValue
+	>;
+	let partial = false;
+	for (const member of selection.members) {
+		if (member.kind !== 'scalar') continue;
+		const fieldPath = [...path, member.responseKey];
+		const hasValue = Object.prototype.hasOwnProperty.call(value, member.responseKey);
+		const rawValue = hasValue ? value[member.responseKey] : undefined;
+		if (
+			pathBlocked(errors, fieldPath) ||
+			!hasValue
+		) {
+			partial = true;
+			continue;
+		}
+		if (rawValue === null && !member.nullable) {
+			if (pathHasErrors(errors, fieldPath)) {
+				partial = true;
+				continue;
+			}
+			throw new TypeError(
+				`operation ${artifactId} returned null for non-null field ${pathLabel(
+					fieldPath
+				)}`
+			);
+		}
+		const next = cloneJsonValue(rawValue);
+		if (Object.prototype.hasOwnProperty.call(fields, member.field)) {
+			if (!deepEqual(fields[member.field], next)) {
+				throw new TypeError(
+					`operation aliases disagree for ${selection.typename}.${member.field}`
+				);
+			}
+			continue;
+		}
+		fields[member.field] = next;
+	}
+
+	let key: RecordKey;
+	let revision: Revision;
+	let incarnation: Revision | undefined;
+	let resolution: ReplicaProtocolRecordResolution | undefined;
+	if (selection.storage.kind === 'normalized') {
+		const identity: CacheValue[] = [];
+		for (const field of selection.storage.identityFields) {
+			if (
+				!Object.prototype.hasOwnProperty.call(fields, field) ||
+				fields[field] === null
+			) {
+				return { partial: true };
+			}
+			identity.push(fields[field]!);
+		}
+		key = replicaRecordKey(
+			{
+				id: selection.storage.model,
+				identityFields: selection.storage.identityFields
+			},
+			identity
+		);
+		resolution = protocol.record(
+			path.map(String),
+			selection.storage.model,
+			key,
+			fields
+		);
+		if (resolution === undefined) {
+			if (!protocol.allowSnapshotOnlyRecords) {
+				return { key, partial: true };
+			}
+			/*
+			 * This row came from an exact authorized query, but the selected
+			 * surface has no safely comparable record clock for its model.
+			 * Scope the storage to this operation/index position so a later
+			 * snapshot can replace it without corrupting causally normalized
+			 * state shared by another operation.
+			 */
+			key = embeddedRecordKey(artifactId, enclosingIndexKey, ordinal);
+			revision = snapshotRevision;
+			incarnation = snapshotRevision;
+		} else {
+			if (resolution.evidence.tombstone) {
+				throw new TypeError('live GraphQL row carries tombstone record evidence');
+			}
+			revision = resolution.evidence.revision;
+			incarnation = resolution.evidence.incarnation;
+		}
+	} else {
+		// Embedded output is an operation-local replacement snapshot, not a
+		// normalized server record. Its synthetic incarnation deliberately
+		// advances with the enclosing response so removed sparse fields disappear.
+		key = embeddedRecordKey(artifactId, enclosingIndexKey, ordinal);
+		revision = snapshotRevision;
+		incarnation = snapshotRevision;
+	}
+
+	if (resolution?.apply !== false) {
+		writer.writeRecord({
+			key,
+			revision,
+			...(incarnation === undefined ? {} : { incarnation }),
+			fields
+		});
+	}
+	const storedClock = writer.recordClock(key);
+	if (
+		storedClock === undefined ||
+		storedClock.tombstoned ||
+		(resolution?.apply !== false &&
+			(storedClock.revision !== String(revision) ||
+				(incarnation !== undefined &&
+					storedClock.incarnation !== String(incarnation))))
+	) {
+		return { partial: true };
+	}
+
+	for (const member of selection.members) {
+		if (member.kind !== 'branch') continue;
+		const branchPath = [...path, member.responseKey];
+		const hasValue = Object.prototype.hasOwnProperty.call(value, member.responseKey);
+		const blocked = pathBlocked(errors, branchPath);
+		const hasErrors = pathHasErrors(errors, branchPath);
+		const rawValue = hasValue ? value[member.responseKey] : undefined;
+		const argumentsValue = resolveArguments(
+			member.arguments,
+			variables,
+			member.coverage
+		);
+		const branchIndexKey = replicaIndexKey({
+			parent: key,
+			field: member.field,
+			arguments: argumentsValue
+		});
+		indexKeys.push(branchIndexKey);
+		if (!hasValue || blocked || (rawValue === null && hasErrors)) {
+			if (protocol.writeIndexes) {
+				writer.markIndexStale(
+					branchIndexKey,
+					hasErrors ? 'graphql-partial-error' : 'incomplete-result',
+					snapshotRevision
+				);
+			}
+			partial = true;
+			continue;
+		}
+		const branch = normalizeBranch(
+			writer,
+			artifactId,
+			member,
+			rawValue,
+			branchPath,
+			branchIndexKey,
+			snapshotRevision,
+			variables,
+			errors,
+			protocol,
+			indexKeys
+		);
+		const branchPartial =
+			branch.partial ||
+			hasErrors ||
+			!protocol.indexesComplete;
+		if (protocol.writeIndexes) {
+			writer.writeIndex({
+				key: branchIndexKey,
+				revision: snapshotRevision,
+				records: branch.keys,
+				complete: !branchPartial,
+				metadata: indexMetadata(
+					member,
+					argumentsValue,
+					branch,
+					branchPartial,
+					hasErrors,
+					key,
+					storedClock.revision
+				)
+			});
+		}
+		partial ||= branchPartial;
+	}
+
+	return { key, partial };
+}
+
+function indexMetadata(
+	selection: RuntimeBranchSelection,
+	argumentsValue: Readonly<Record<string, CacheValue>>,
+	branch: NormalizedBranch,
+	partial: boolean,
+	hasErrors: boolean,
+	parent?: RecordKey,
+	parentRevision?: Revision
+): CacheIndexMetadata {
+	return Object.freeze({
+		...(parent === undefined ? {} : { parent }),
+		...(parentRevision === undefined ? {} : { parentRevision: String(parentRevision) }),
+		field: selection.field,
+		arguments: argumentsValue,
+		coverage: coverageFromArtifact(
+			selection.coverage,
+			argumentsValue,
+			branch.keys.length
+		),
+		dependencies: Object.freeze([...new Set(selection.dependencies)].sort()),
+		...(partial
+			? { staleReason: hasErrors ? 'graphql-partial-error' : 'incomplete-result' }
+			: {}),
+		nullValue: branch.nullValue
+	});
+}
+
+function collectErrorPaths(errors: readonly GqlError[]): ErrorPaths {
+	const paths: Array<readonly (string | number)[]> = [];
+	let global = false;
+	for (const error of errors) {
+		if (!Array.isArray(error.path) || error.path.length === 0) {
+			global = true;
+			continue;
+		}
+		paths.push(Object.freeze([...error.path]));
+	}
+	return { global, paths };
+}
+
+function pathBlocked(errors: ErrorPaths, path: readonly (string | number)[]): boolean {
+	return errors.global || errors.paths.some((errorPath) => isPrefix(errorPath, path));
+}
+
+function pathHasErrors(errors: ErrorPaths, path: readonly (string | number)[]): boolean {
+	return (
+		errors.global ||
+		errors.paths.some(
+			(errorPath) => isPrefix(path, errorPath) || isPrefix(errorPath, path)
+		)
+	);
+}
+
+function isPrefix(
+	prefix: readonly (string | number)[],
+	value: readonly (string | number)[]
+): boolean {
+	return (
+		prefix.length <= value.length &&
+		prefix.every((entry, index) => entry === value[index])
+	);
+}
+
+function validateArtifact(artifact: {
+	readonly id: string;
+	readonly roots: readonly unknown[];
+}): void {
+	if (!artifact || typeof artifact !== 'object') {
+		throw new TypeError('replica artifact is required');
+	}
+	if (typeof artifact.id !== 'string' || artifact.id.length === 0) {
+		throw new TypeError('replica artifact id must be a non-empty string');
+	}
+	if (!Array.isArray(artifact.roots) || artifact.roots.length === 0) {
+		throw new TypeError(`operation ${artifact.id} must contain at least one root selection`);
+	}
+}
+
+function pathLabel(path: readonly (string | number)[]): string {
+	return path.map(String).join('.');
+}
+
+function isObject(value: unknown): value is Readonly<Record<string, unknown>> {
+	return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
diff --git a/js/src/replica/operation-binding.ts b/js/src/replica/operation-binding.ts
new file mode 100644
index 00000000..a7ec9f87
--- /dev/null
+++ b/js/src/replica/operation-binding.ts
@@ -0,0 +1,118 @@
+import { isDistributedTrustedPresetCodec } from '../protocol.js';
+import type { GraphqlVariables } from '../types.js';
+import type {
+	ReplicaClientSurface,
+	ReplicaOperationArtifact,
+	ReplicaSurfaceTrustedPresetDescriptor
+} from './types.js';
+
+export type ValidatedReplicaOperationBinding = {
+	readonly version: 1;
+	readonly schemaHash: string;
+	readonly operation: string;
+	readonly surfaceIdentity: string;
+	readonly trustedPresets: readonly ReplicaSurfaceTrustedPresetDescriptor[];
+};
+
+/**
+ * Validate the exact compiler-owned protocol identity before an operation may
+ * acquire a cache key, register a maintenance plan, or reach a transport.
+ */
+export function validateReplicaOperationBinding<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	artifact: ReplicaOperationArtifact<TData, TVariables>
+): ValidatedReplicaOperationBinding {
+	if (typeof artifact.id !== 'string' || artifact.id.length === 0) {
+		throw new TypeError('replica artifact id must be a non-empty string');
+	}
+	const binding = artifact.protocol;
+	if (
+		binding === undefined ||
+		binding.version !== 1 ||
+		typeof binding.schemaHash !== 'string' ||
+		binding.schemaHash.length === 0 ||
+		typeof binding.operation !== 'string' ||
+		binding.operation.length === 0 ||
+		binding.operation !== artifact.id
+	) {
+		throw new TypeError('replica artifact protocol binding is invalid');
+	}
+	if (artifact.variableCodec === undefined) {
+		throw new TypeError('protocol-v1 replica artifact requires variableCodec');
+	}
+	return Object.freeze({
+		version: binding.version,
+		schemaHash: binding.schemaHash,
+		operation: binding.operation,
+		surfaceIdentity: validateReplicaSurfaceIdentity(binding.surface),
+		trustedPresets: canonicalTrustedPresetDescriptors(
+			binding.trustedPresets
+		)
+	});
+}
+
+function validateReplicaSurfaceIdentity(value: ReplicaClientSurface): string {
+	if (
+		value === null ||
+		typeof value !== 'object' ||
+		typeof value.name !== 'string' ||
+		value.name.length === 0
+	) {
+		throw new TypeError('replica artifact client surface is invalid');
+	}
+	if (value.kind === 'role') {
+		return JSON.stringify(['role', value.name]);
+	}
+	if (
+		value.kind !== 'application' ||
+		!Array.isArray(value.roles) ||
+		value.roles.length === 0 ||
+		value.roles.some(
+			(role) => typeof role !== 'string' || role.length === 0
+		) ||
+		new Set(value.roles).size !== value.roles.length ||
+		[...value.roles].sort().some((role, index) => role !== value.roles[index])
+	) {
+		throw new TypeError('replica artifact client surface is invalid');
+	}
+	return JSON.stringify(['application', value.name, value.roles]);
+}
+
+function canonicalTrustedPresetDescriptors(
+	value: unknown
+): readonly ReplicaSurfaceTrustedPresetDescriptor[] {
+	if (!Array.isArray(value)) {
+		throw new TypeError('replica artifact trusted preset contract is invalid');
+	}
+	const names = new Set<string>();
+	return Object.freeze(
+		value
+			.map((candidate) => {
+				if (
+					candidate === null ||
+					typeof candidate !== 'object' ||
+					typeof candidate.name !== 'string' ||
+					candidate.name.length === 0 ||
+					candidate.name.length > 128 ||
+					candidate.name.trim() !== candidate.name ||
+					/[\u0000-\u001f\u007f-\u009f]/.test(candidate.name) ||
+					names.has(candidate.name) ||
+					!isDistributedTrustedPresetCodec(candidate.codec)
+				) {
+					throw new TypeError(
+						'replica artifact trusted preset contract is invalid'
+					);
+				}
+				names.add(candidate.name);
+				return Object.freeze({
+					name: candidate.name,
+					codec: candidate.codec
+				});
+			})
+			.sort(({ name: left }, { name: right }) =>
+				left < right ? -1 : left > right ? 1 : 0
+			)
+	);
+}
diff --git a/js/src/replica/persistence.ts b/js/src/replica/persistence.ts
new file mode 100644
index 00000000..35f3046d
--- /dev/null
+++ b/js/src/replica/persistence.ts
@@ -0,0 +1,12 @@
+/** Confirmed-state IndexedDB persistence; implementation in ./persistence/. */
+export {
+	createReplicaIndexedDbPersistence,
+	REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED
+} from './persistence/index.js';
+export type {
+	ReplicaIndexedDbFactory,
+	ReplicaIndexedDbPersistence,
+	ReplicaIndexedDbPersistenceOptions,
+	ReplicaPersistenceModelPolicy,
+	ReplicaPersistencePolicy
+} from './persistence/index.js';
diff --git a/js/src/replica/persistence/idb.ts b/js/src/replica/persistence/idb.ts
new file mode 100644
index 00000000..46035877
--- /dev/null
+++ b/js/src/replica/persistence/idb.ts
@@ -0,0 +1,262 @@
+import type {
+	ReplicaAuthoritativeScope,
+	ReplicaDehydratedState
+} from '../types.js';
+import type {
+	ReplicaIndexedDbFactory,
+	ReplicaIndexedDbPersistence,
+	ReplicaIndexedDbPersistenceOptions
+} from './types.js';
+import {
+	DATABASE_VERSION,
+	DEFAULT_DATABASE_NAME,
+	STORE_NAME,
+	filterReplicaState,
+	normalizePolicy,
+	parseAuthoritativeScope,
+	parseReplicaState,
+	parseStoredEntry,
+	persistenceIdentity,
+	sameScope,
+	type NormalizedPolicy,
+	type StoredReplicaEntry
+} from './state.js';
+
+export class IndexedDbConfirmedStatePersistence
+	implements ReplicaIndexedDbPersistence
+{
+	readonly supportsOfflineCommandOutbox = false as const;
+	readonly #factory: ReplicaIndexedDbFactory;
+	readonly #databaseName: string;
+	readonly #policy: NormalizedPolicy;
+	#databasePromise: Promise<IDBDatabase> | undefined;
+	#closed = false;
+
+	constructor(
+		factory: ReplicaIndexedDbFactory,
+		databaseName: string,
+		policy: NormalizedPolicy
+	) {
+		this.#factory = factory;
+		this.#databaseName = databaseName;
+		this.#policy = policy;
+	}
+
+	async save(state: ReplicaDehydratedState): Promise<boolean> {
+		this.#assertOpen();
+		const parsed = parseReplicaState(state);
+		const filtered = filterReplicaState(parsed, this.#policy);
+		const identity = persistenceIdentity(parsed.scope);
+		if (filtered === undefined) {
+			// A newly restrictive policy must not leave a previously durable copy.
+			await this.#delete(identity);
+			return false;
+		}
+		const entry: StoredReplicaEntry = Object.freeze({
+			formatVersion: 1 as const,
+			identity,
+			storedAt: Date.now(),
+			state: filtered
+		});
+		await this.#write(entry);
+		return true;
+	}
+
+	async restore(
+		authoritativeScope: ReplicaAuthoritativeScope
+	): Promise<ReplicaDehydratedState | undefined> {
+		this.#assertOpen();
+		const scope = parseAuthoritativeScope(authoritativeScope);
+		const identity = persistenceIdentity(scope);
+		const raw = await this.#read(identity);
+		if (raw === undefined) return undefined;
+
+		try {
+			const entry = parseStoredEntry(raw);
+			const parsed = parseReplicaState(entry.state);
+			if (
+				entry.identity !== identity ||
+				!sameScope(parsed.scope, scope)
+			) {
+				throw new TypeError('persisted replica scope does not match its key');
+			}
+			const filtered = filterReplicaState(parsed, this.#policy);
+			if (filtered === undefined) {
+				await this.#delete(identity);
+				return undefined;
+			}
+			// Reapply the current policy to the durable copy as well as the value
+			// returned to memory. This removes data made memory-only by a newer
+			// manifest instead of leaving it at rest under an older policy.
+			await this.#write(
+				Object.freeze({
+					formatVersion: 1 as const,
+					identity,
+					storedAt: entry.storedAt,
+					state: filtered
+				})
+			);
+			return filtered;
+		} catch {
+			// Never consume a questionable snapshot. Deletion is best-effort so an
+			// IndexedDB failure cannot turn corrupt data into accepted state.
+			try {
+				await this.#delete(identity);
+			} catch {
+				// A later restore will reject the same entry again.
+			}
+			return undefined;
+		}
+	}
+
+	async discard(authoritativeScope: ReplicaAuthoritativeScope): Promise<void> {
+		this.#assertOpen();
+		await this.#delete(
+			persistenceIdentity(parseAuthoritativeScope(authoritativeScope))
+		);
+	}
+
+	close(): void {
+		if (this.#closed) return;
+		this.#closed = true;
+		const pending = this.#databasePromise;
+		if (pending !== undefined) {
+			void pending.then(
+				(database) => database.close(),
+				() => undefined
+			);
+		}
+	}
+
+	async #read(identity: string): Promise<unknown | undefined> {
+		return this.#transaction('readonly', (store) =>
+			requestResult(store.get(identity))
+		);
+	}
+
+	async #write(entry: StoredReplicaEntry): Promise<void> {
+		await this.#transaction('readwrite', async (store) => {
+			await requestResult(store.put(entry));
+		});
+	}
+
+	async #delete(identity: string): Promise<void> {
+		await this.#transaction('readwrite', async (store) => {
+			await requestResult(store.delete(identity));
+		});
+	}
+
+	async #transaction<T>(
+		mode: IDBTransactionMode,
+		operation: (store: IDBObjectStore) => Promise<T>
+	): Promise<T> {
+		const database = await this.#database();
+		this.#assertOpen();
+		const transaction = database.transaction(STORE_NAME, mode);
+		const completion = transactionResult(transaction);
+		try {
+			const result = await operation(transaction.objectStore(STORE_NAME));
+			await completion;
+			return result;
+		} catch (error) {
+			try {
+				transaction.abort();
+			} catch {
+				// It may already have completed or aborted.
+			}
+			await completion.catch(() => undefined);
+			throw error;
+		}
+	}
+
+	#database(): Promise<IDBDatabase> {
+		this.#assertOpen();
+		this.#databasePromise ??= openDatabase(
+			this.#factory,
+			this.#databaseName
+		);
+		return this.#databasePromise;
+	}
+
+	#assertOpen(): void {
+		if (this.#closed) {
+			throw new Error('replica IndexedDB persistence is closed');
+		}
+	}
+}
+
+/**
+ * Create opt-in confirmed-state persistence. Merely creating a replica never
+ * opens IndexedDB; applications must explicitly create and call this adapter.
+ */
+export function createReplicaIndexedDbPersistence(
+	options: ReplicaIndexedDbPersistenceOptions = {}
+): ReplicaIndexedDbPersistence {
+	const factory =
+		options.indexedDB ??
+		(globalThis as { indexedDB?: ReplicaIndexedDbFactory }).indexedDB;
+	if (factory === undefined || typeof factory.open !== 'function') {
+		throw new TypeError('IndexedDB is unavailable in this runtime');
+	}
+	const databaseName = options.databaseName ?? DEFAULT_DATABASE_NAME;
+	if (typeof databaseName !== 'string' || databaseName.length === 0) {
+		throw new TypeError('replica persistence databaseName must be non-empty');
+	}
+	return new IndexedDbConfirmedStatePersistence(
+		factory,
+		databaseName,
+		normalizePolicy(options.policy)
+	);
+}
+
+export function openDatabase(
+	factory: ReplicaIndexedDbFactory,
+	name: string
+): Promise<IDBDatabase> {
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		const request = factory.open(name, DATABASE_VERSION);
+		request.onupgradeneeded = () => {
+			const database = request.result;
+			if (!database.objectStoreNames.contains(STORE_NAME)) {
+				database.createObjectStore(STORE_NAME, { keyPath: 'identity' });
+			}
+		};
+		request.onsuccess = () => {
+			if (settled) {
+				request.result.close();
+				return;
+			}
+			settled = true;
+			resolve(request.result);
+		};
+		request.onerror = () => {
+			if (settled) return;
+			settled = true;
+			reject(request.error ?? new Error('failed to open replica IndexedDB'));
+		};
+		request.onblocked = () => {
+			if (settled) return;
+			settled = true;
+			reject(new Error('replica IndexedDB upgrade is blocked'));
+		};
+	});
+}
+
+export function requestResult<T>(request: IDBRequest<T>): Promise<T> {
+	return new Promise((resolve, reject) => {
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () =>
+			reject(request.error ?? new Error('replica IndexedDB request failed'));
+	});
+}
+
+export function transactionResult(transaction: IDBTransaction): Promise<void> {
+	return new Promise((resolve, reject) => {
+		transaction.oncomplete = () => resolve();
+		transaction.onabort = () =>
+			reject(transaction.error ?? new Error('replica IndexedDB transaction aborted'));
+		transaction.onerror = () =>
+			reject(transaction.error ?? new Error('replica IndexedDB transaction failed'));
+	});
+}
diff --git a/js/src/replica/persistence/implementation.ts b/js/src/replica/persistence/implementation.ts
new file mode 100644
index 00000000..54639d57
--- /dev/null
+++ b/js/src/replica/persistence/implementation.ts
@@ -0,0 +1,4 @@
+/** Re-export surface for persistence modules (body-split). */
+export * from './types.js';
+export * from './state.js';
+export * from './idb.js';
diff --git a/js/src/replica/persistence/index.ts b/js/src/replica/persistence/index.ts
new file mode 100644
index 00000000..098782c5
--- /dev/null
+++ b/js/src/replica/persistence/index.ts
@@ -0,0 +1,11 @@
+export {
+	createReplicaIndexedDbPersistence,
+	REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED
+} from './implementation.js';
+export type {
+	ReplicaIndexedDbFactory,
+	ReplicaIndexedDbPersistence,
+	ReplicaIndexedDbPersistenceOptions,
+	ReplicaPersistenceModelPolicy,
+	ReplicaPersistencePolicy
+} from './implementation.js';
diff --git a/js/src/replica/persistence/state.ts b/js/src/replica/persistence/state.ts
new file mode 100644
index 00000000..c51ef6f6
--- /dev/null
+++ b/js/src/replica/persistence/state.ts
@@ -0,0 +1,1083 @@
+import {
+	createCacheEngine,
+	type CacheEngineSnapshot,
+	type RecordLink
+} from '../../internal/cache-engine.js';
+import {
+	parseDistributedTrustedPresetInventory,
+	type DistributedTrustedPreset
+} from '../../protocol.js';
+import type {
+	ReplicaAuthoritativeScope,
+	ReplicaDehydratedState
+} from '../types.js';
+import { freezeRecord } from '../../lib/freeze-record.js';
+import type {
+	ReplicaPersistenceModelPolicy,
+	ReplicaPersistencePolicy
+} from './types.js';
+
+export const DATABASE_VERSION = 1;
+export const ENTRY_FORMAT_VERSION = 1;
+export const STORE_NAME = 'confirmed-replicas';
+export const DEFAULT_DATABASE_NAME = '@hops-ops/distributed:replica';
+export const GRAPHQL_NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
+export const DECIMAL = /^(0|[1-9][0-9]*)$/;
+
+
+export type RecordClockV1 = {
+	readonly scopeToken: string;
+	readonly incarnation: string;
+	readonly revision: string;
+	readonly tombstone: boolean;
+};
+
+export type AnonymousRecordClockV1 = {
+	readonly model: string;
+	readonly clock: RecordClockV1;
+};
+
+export type OperationProtocolStateV1 = {
+	readonly operation: string;
+	readonly snapshotScope?: string;
+	readonly indexClocks: readonly (readonly [
+		string,
+		Readonly<{ scopeToken: string; position: string }>
+	])[];
+	readonly indexRevision?: string;
+	readonly indexKeys: readonly string[];
+	readonly pathRecords: readonly (readonly [string, string])[];
+	readonly cursors: readonly Readonly<{
+		projection: string;
+		position: string;
+		token: string;
+	}>[];
+};
+
+export type OperationProtocolGroupV1 = {
+	readonly key: string;
+	readonly query?: OperationProtocolStateV1;
+	readonly live?: OperationProtocolStateV1;
+	readonly active?: 'query' | 'live';
+	readonly generation: number;
+};
+
+export type ReplicaPersistencePayloadV1 = {
+	readonly cache: CacheEngineSnapshot;
+	readonly operations: readonly OperationProtocolGroupV1[];
+	readonly recordClocks: readonly (readonly [string, RecordClockV1])[];
+	readonly anonymousRecordClocks: readonly (readonly [
+		string,
+		AnonymousRecordClockV1
+	])[];
+	readonly trustedPresets: readonly DistributedTrustedPreset[];
+	readonly nextIndexRevision: string;
+};
+
+export type ParsedReplicaState = {
+	readonly state: ReplicaDehydratedState;
+	readonly scope: ReplicaAuthoritativeScope;
+	readonly payload: ReplicaPersistencePayloadV1;
+};
+
+export type StoredReplicaEntry = {
+	readonly formatVersion: 1;
+	readonly identity: string;
+	readonly storedAt: number;
+	readonly state: ReplicaDehydratedState;
+};
+
+export type NormalizedPolicy = ReadonlyMap<string, ReplicaPersistenceModelPolicy>;
+
+export function normalizePolicy(
+	policy: ReplicaPersistencePolicy | undefined
+): NormalizedPolicy {
+	if (policy === undefined) return new Map();
+	const raw = exactRecord(policy, 'persistence policy', ['models']);
+	const models = plainRecord(raw.models, 'persistence policy.models');
+	const result = new Map<string, ReplicaPersistenceModelPolicy>();
+	for (const [model, value] of Object.entries(models)) {
+		if (!GRAPHQL_NAME.test(model)) {
+			throw new TypeError(`invalid persistence policy model: ${model}`);
+		}
+		const entry = exactRecord(
+			value,
+			`persistence policy.models.${model}`,
+			['retention', 'sensitive']
+		);
+		if (
+			entry.retention !== 'persist-confirmed' &&
+			entry.retention !== 'memory-only'
+		) {
+			throw new TypeError(
+				`invalid persistence retention for model ${model}`
+			);
+		}
+		if (typeof entry.sensitive !== 'boolean') {
+			throw new TypeError(
+				`persistence sensitivity for model ${model} must be boolean`
+			);
+		}
+		result.set(
+			model,
+			Object.freeze({
+				retention: entry.retention,
+				sensitive: entry.sensitive
+			})
+		);
+	}
+	return result;
+}
+
+export function filterReplicaState(
+	parsed: ParsedReplicaState,
+	policy: NormalizedPolicy
+): ReplicaDehydratedState | undefined {
+	const allowsModel = (model: string): boolean => {
+		const decision = policy.get(model);
+		return (
+			decision?.retention === 'persist-confirmed' &&
+			decision.sensitive === false
+		);
+	};
+	const allowedRecord = (key: string): boolean => {
+		const model = modelFromRecordKey(key);
+		return model !== undefined && allowsModel(model);
+	};
+
+	const recordClocks = parsed.payload.recordClocks.filter(([key]) =>
+		allowedRecord(key)
+	);
+	const recordClockKeys = new Set(recordClocks.map(([key]) => key));
+	const initialRecords = parsed.payload.cache.records.filter((record) =>
+		allowedRecord(record.key)
+	);
+	const liveRecordKeys = new Set(
+		initialRecords
+			.filter((record) => record.tombstoneRevision === undefined)
+			.map((record) => record.key)
+	);
+	const records = initialRecords.map((record) =>
+		Object.freeze({
+			...record,
+			links: freezeRecord(
+				Object.entries(record.links).filter(([, link]) =>
+					linkReferencesOnly(link.value, liveRecordKeys)
+				)
+			)
+		})
+	);
+
+	const candidateIndexes = new Map(
+		parsed.payload.cache.indexes
+			.filter(
+				(index) =>
+					!index.deleted &&
+					index.records.length > 0 &&
+					index.records.every((key) => liveRecordKeys.has(key)) &&
+					(
+						index.metadata?.parent === undefined ||
+						liveRecordKeys.has(index.metadata.parent)
+					)
+			)
+			.map((index) => [index.key, index] as const)
+	);
+
+	const initiallyEligible = new Map<
+		OperationProtocolStateV1,
+		OperationProtocolStateV1
+	>();
+	for (const group of parsed.payload.operations) {
+		for (const state of [group.query, group.live]) {
+			if (
+				state !== undefined &&
+				operationStateAllowed(
+					state,
+					candidateIndexes,
+					recordClockKeys,
+					allowedRecord
+				)
+			) {
+				initiallyEligible.set(state, state);
+			}
+		}
+	}
+
+	let eligible = initiallyEligible;
+	let finalIndexKeys = indexesProvenByOperations(
+		candidateIndexes,
+		eligible.values()
+	);
+	for (;;) {
+		const nextEligible = new Map<
+			OperationProtocolStateV1,
+			OperationProtocolStateV1
+		>();
+		for (const state of eligible.values()) {
+			if (state.indexKeys.every((key) => finalIndexKeys.has(key))) {
+				nextEligible.set(state, state);
+			}
+		}
+		const nextIndexKeys = indexesProvenByOperations(
+			candidateIndexes,
+			nextEligible.values()
+		);
+		if (
+			nextEligible.size === eligible.size &&
+			nextIndexKeys.size === finalIndexKeys.size
+		) {
+			eligible = nextEligible;
+			finalIndexKeys = nextIndexKeys;
+			break;
+		}
+		eligible = nextEligible;
+		finalIndexKeys = nextIndexKeys;
+	}
+
+	const indexes = parsed.payload.cache.indexes.filter((index) =>
+		finalIndexKeys.has(index.key)
+	);
+	const operations = parsed.payload.operations.flatMap((group) => {
+		const query =
+			group.query !== undefined && eligible.has(group.query)
+				? group.query
+				: undefined;
+		const live =
+			group.live !== undefined && eligible.has(group.live)
+				? group.live
+				: undefined;
+		if (query === undefined && live === undefined) return [];
+		const active =
+			group.active === 'query' && query !== undefined
+				? 'query'
+				: group.active === 'live' && live !== undefined
+					? 'live'
+					: undefined;
+		return [
+			Object.freeze({
+				key: group.key,
+				...(query === undefined ? {} : { query }),
+				...(live === undefined ? {} : { live }),
+				...(active === undefined ? {} : { active }),
+				generation: group.generation
+			})
+		];
+	});
+	const anonymousRecordClocks =
+		parsed.payload.anonymousRecordClocks.filter(([, value]) =>
+			allowsModel(value.model)
+		);
+
+	const cache = canonicalCacheSnapshot({
+		version: 1,
+		records,
+		indexes
+	});
+	if (
+		cache.records.length === 0 &&
+		cache.indexes.length === 0 &&
+		recordClocks.length === 0 &&
+		anonymousRecordClocks.length === 0
+	) {
+		return undefined;
+	}
+	const payload: ReplicaPersistencePayloadV1 = Object.freeze({
+		cache,
+		operations: Object.freeze(operations),
+		recordClocks: Object.freeze(recordClocks),
+		anonymousRecordClocks: Object.freeze(anonymousRecordClocks),
+		/*
+		 * Presets are part of the exact server-issued cache scope contract. A
+		 * restored cache cannot safely evaluate generated row policies or command
+		 * effects without the matching inventory. The entry remains opt-in,
+		 * confirmed-state-only, and keyed by that independently re-established
+		 * opaque scope; transport credentials and command inputs are still absent.
+		 */
+		trustedPresets: parsed.payload.trustedPresets,
+		nextIndexRevision: parsed.payload.nextIndexRevision
+	});
+	assertMetadataConsistent(payload);
+	return Object.freeze({
+		version: 1 as const,
+		scope: parsed.scope,
+		payload
+	});
+}
+
+export function operationStateAllowed(
+	state: OperationProtocolStateV1,
+	indexes: ReadonlyMap<string, CacheEngineSnapshot['indexes'][number]>,
+	recordClockKeys: ReadonlySet<string>,
+	allowedRecord: (key: string) => boolean
+): boolean {
+	if (state.indexKeys.length === 0 && state.pathRecords.length === 0) {
+		return false;
+	}
+	if (state.indexKeys.some((key) => !indexes.has(key))) return false;
+	for (const [, key] of state.pathRecords) {
+		if (!allowedRecord(key) || !recordClockKeys.has(key)) return false;
+	}
+	return true;
+}
+
+export function indexesProvenByOperations(
+	candidates: ReadonlyMap<string, CacheEngineSnapshot['indexes'][number]>,
+	states: Iterable<OperationProtocolStateV1>
+): Set<string> {
+	const result = new Set<string>();
+	for (const state of states) {
+		if (state.indexRevision === undefined) continue;
+		for (const key of state.indexKeys) {
+			if (candidates.get(key)?.revision === state.indexRevision) {
+				result.add(key);
+			}
+		}
+	}
+	return result;
+}
+
+export function linkReferencesOnly(
+	link: RecordLink,
+	allowedLiveRecordKeys: ReadonlySet<string>
+): boolean {
+	if (link === null) return true;
+	if (typeof link === 'string') return allowedLiveRecordKeys.has(link);
+	return link.every((key) => allowedLiveRecordKeys.has(key));
+}
+
+export function parseReplicaState(value: unknown): ParsedReplicaState {
+	const state = exactRecord(value, 'state', ['version', 'scope', 'payload']);
+	if (state.version !== 1) throw new TypeError('unsupported replica state version');
+	const scope = parseAuthoritativeScope(state.scope);
+	const payloadValue = exactRecord(
+		state.payload,
+		'state.payload',
+		[
+			'cache',
+			'operations',
+			'recordClocks',
+			'anonymousRecordClocks',
+			'trustedPresets',
+			'nextIndexRevision'
+		]
+	);
+	const cache = parseCacheSnapshot(payloadValue.cache);
+	const operations = parseOperations(payloadValue.operations);
+	const recordClocks = parseRecordClocks(payloadValue.recordClocks);
+	const anonymousRecordClocks = parseAnonymousRecordClocks(
+		payloadValue.anonymousRecordClocks,
+		recordClocks
+	);
+	const trustedPresets = parseDistributedTrustedPresetInventory(
+		payloadValue.trustedPresets,
+		'state.payload.trustedPresets'
+	);
+	const nextIndexRevision = decimalString(
+		payloadValue.nextIndexRevision,
+		'state.payload.nextIndexRevision'
+	);
+	const payload: ReplicaPersistencePayloadV1 = Object.freeze({
+		cache,
+		operations,
+		recordClocks,
+		anonymousRecordClocks,
+		trustedPresets,
+		nextIndexRevision
+	});
+	assertMetadataConsistent(payload);
+	const normalizedState: ReplicaDehydratedState = Object.freeze({
+		version: 1 as const,
+		scope,
+		payload
+	});
+	return Object.freeze({ state: normalizedState, scope, payload });
+}
+
+export function parseAuthoritativeScope(value: unknown): ReplicaAuthoritativeScope {
+	const scope = exactRecord(
+		value,
+		'authoritative scope',
+		['protocolVersion', 'schemaHash', 'cacheScope']
+	);
+	if (scope.protocolVersion !== 1) {
+		throw new TypeError('unsupported authoritative protocol version');
+	}
+	return Object.freeze({
+		protocolVersion: 1 as const,
+		schemaHash: nonEmptyString(scope.schemaHash, 'authoritative scope schemaHash'),
+		cacheScope: nonEmptyString(scope.cacheScope, 'authoritative scope cacheScope')
+	});
+}
+
+export function parseCacheSnapshot(value: unknown): CacheEngineSnapshot {
+	const cache = exactRecord(value, 'state.payload.cache', [
+		'version',
+		'records',
+		'indexes'
+	]);
+	if (cache.version !== 1) throw new TypeError('unsupported cache snapshot');
+	for (const [index, value] of arrayValue(
+		cache.records,
+		'state.payload.cache.records'
+	).entries()) {
+		const path = `state.payload.cache.records[${index}]`;
+		const record = exactRecord(
+			value,
+			path,
+			['key', 'revision', 'incarnation', 'tombstoneRevision', 'fields', 'links'],
+			['key', 'revision', 'fields', 'links']
+		);
+		nonEmptyString(record.key, `${path}.key`);
+		decimalString(record.revision, `${path}.revision`);
+		if (record.incarnation !== undefined) {
+			decimalString(record.incarnation, `${path}.incarnation`);
+		}
+		if (record.tombstoneRevision !== undefined) {
+			decimalString(record.tombstoneRevision, `${path}.tombstoneRevision`);
+		}
+		for (const [name, fieldValue] of Object.entries(
+			plainRecord(record.fields, `${path}.fields`)
+		)) {
+			const field = exactRecord(
+				fieldValue,
+				`${path}.fields.${name}`,
+				['revision', 'value']
+			);
+			decimalString(field.revision, `${path}.fields.${name}.revision`);
+			assertJsonValue(field.value, `${path}.fields.${name}.value`);
+		}
+		for (const [name, linkValue] of Object.entries(
+			plainRecord(record.links, `${path}.links`)
+		)) {
+			const link = exactRecord(
+				linkValue,
+				`${path}.links.${name}`,
+				['revision', 'value']
+			);
+			decimalString(link.revision, `${path}.links.${name}.revision`);
+			assertRecordLink(link.value, `${path}.links.${name}.value`);
+		}
+	}
+	for (const [index, value] of arrayValue(
+		cache.indexes,
+		'state.payload.cache.indexes'
+	).entries()) {
+		const path = `state.payload.cache.indexes[${index}]`;
+		const entry = exactRecord(
+			value,
+			path,
+			[
+				'key',
+				'revision',
+				'staleRevision',
+				'records',
+				'complete',
+				'deleted',
+				'metadata'
+			],
+			['key', 'revision', 'records', 'complete', 'deleted']
+		);
+		nonEmptyString(entry.key, `${path}.key`);
+		decimalString(entry.revision, `${path}.revision`);
+		if (entry.staleRevision !== undefined) {
+			decimalString(entry.staleRevision, `${path}.staleRevision`);
+		}
+		const seen = new Set<string>();
+		for (const [recordIndex, key] of arrayValue(
+			entry.records,
+			`${path}.records`
+		).entries()) {
+			const recordKey = nonEmptyString(key, `${path}.records[${recordIndex}]`);
+			if (seen.has(recordKey)) {
+				throw new TypeError(`duplicate record at ${path}.records[${recordIndex}]`);
+			}
+			seen.add(recordKey);
+		}
+		booleanValue(entry.complete, `${path}.complete`);
+		booleanValue(entry.deleted, `${path}.deleted`);
+		if (entry.metadata !== undefined) {
+			assertIndexMetadata(entry.metadata, `${path}.metadata`);
+		}
+	}
+	return canonicalCacheSnapshot(cache as unknown as CacheEngineSnapshot);
+}
+
+export function canonicalCacheSnapshot(
+	value: CacheEngineSnapshot
+): CacheEngineSnapshot {
+	const engine = createCacheEngine();
+	engine.restore(value);
+	return engine.extract();
+}
+
+export function assertIndexMetadata(value: unknown, path: string): void {
+	const metadata = exactRecord(
+		value,
+		path,
+		[
+			'parent',
+			'parentRevision',
+			'parentIncarnation',
+			'field',
+			'arguments',
+			'coverage',
+			'dependencies',
+			'staleReason',
+			'nullValue'
+		],
+		['field', 'arguments', 'coverage', 'dependencies']
+	);
+	if (metadata.parent !== undefined) nonEmptyString(metadata.parent, `${path}.parent`);
+	if (metadata.parentRevision !== undefined) {
+		decimalString(metadata.parentRevision, `${path}.parentRevision`);
+	}
+	if (metadata.parentIncarnation !== undefined) {
+		decimalString(metadata.parentIncarnation, `${path}.parentIncarnation`);
+	}
+	nonEmptyString(metadata.field, `${path}.field`);
+	const argumentsValue = plainRecord(metadata.arguments, `${path}.arguments`);
+	assertJsonValue(argumentsValue, `${path}.arguments`);
+	assertCoverage(metadata.coverage, `${path}.coverage`);
+	const seen = new Set<string>();
+	for (const [index, dependency] of arrayValue(
+		metadata.dependencies,
+		`${path}.dependencies`
+	).entries()) {
+		const name = nonEmptyString(
+			dependency,
+			`${path}.dependencies[${index}]`
+		);
+		if (seen.has(name)) {
+			throw new TypeError(`duplicate dependency at ${path}.dependencies[${index}]`);
+		}
+		seen.add(name);
+	}
+	if (metadata.staleReason !== undefined) {
+		nonEmptyString(metadata.staleReason, `${path}.staleReason`);
+	}
+	if (metadata.nullValue !== undefined) {
+		booleanValue(metadata.nullValue, `${path}.nullValue`);
+	}
+}
+
+export function assertCoverage(value: unknown, path: string): void {
+	const coverage = plainRecord(value, path);
+	if (coverage.kind === 'complete' || coverage.kind === 'unknown') {
+		exactKeys(coverage, path, ['kind']);
+		return;
+	}
+	if (coverage.kind === 'offset') {
+		exactKeys(
+			coverage,
+			path,
+			['kind', 'offset', 'limit', 'returned', 'hasNext'],
+			['kind', 'offset']
+		);
+		nonNegativeInteger(coverage.offset, `${path}.offset`);
+		if (coverage.limit !== undefined) nonNegativeInteger(coverage.limit, `${path}.limit`);
+		if (coverage.returned !== undefined) {
+			nonNegativeInteger(coverage.returned, `${path}.returned`);
+		}
+		if (coverage.hasNext !== undefined) booleanValue(coverage.hasNext, `${path}.hasNext`);
+		return;
+	}
+	if (coverage.kind === 'cursor') {
+		exactKeys(
+			coverage,
+			path,
+			[
+				'kind',
+				'after',
+				'before',
+				'first',
+				'last',
+				'start',
+				'end',
+				'hasNext',
+				'hasPrevious'
+			],
+			['kind']
+		);
+		for (const key of ['after', 'before', 'start', 'end'] as const) {
+			if (coverage[key] !== undefined) {
+				assertJsonValue(coverage[key], `${path}.${key}`);
+			}
+		}
+		for (const key of ['first', 'last'] as const) {
+			if (coverage[key] !== undefined) {
+				nonNegativeInteger(coverage[key], `${path}.${key}`);
+			}
+		}
+		for (const key of ['hasNext', 'hasPrevious'] as const) {
+			if (coverage[key] !== undefined) {
+				booleanValue(coverage[key], `${path}.${key}`);
+			}
+		}
+		return;
+	}
+	throw new TypeError(`unsupported index coverage at ${path}`);
+}
+
+export function parseOperations(value: unknown): readonly OperationProtocolGroupV1[] {
+	const groups: OperationProtocolGroupV1[] = [];
+	const keys = new Set<string>();
+	for (const [index, entry] of arrayValue(
+		value,
+		'state.payload.operations'
+	).entries()) {
+		const path = `state.payload.operations[${index}]`;
+		const raw = exactRecord(
+			entry,
+			path,
+			['key', 'query', 'live', 'active', 'generation'],
+			['key', 'generation']
+		);
+		const key = nonEmptyString(raw.key, `${path}.key`);
+		if (!key.startsWith('protocol:') || keys.has(key)) {
+			throw new TypeError(`invalid or duplicate operation key at ${path}.key`);
+		}
+		keys.add(key);
+		const query =
+			raw.query === undefined
+				? undefined
+				: parseOperationState(raw.query, `${path}.query`);
+		const live =
+			raw.live === undefined
+				? undefined
+				: parseOperationState(raw.live, `${path}.live`);
+		if (query === undefined && live === undefined) {
+			throw new TypeError(`operation has no protocol state at ${path}`);
+		}
+		const active =
+			raw.active === undefined
+				? undefined
+				: operationSource(raw.active, `${path}.active`);
+		if (
+			(active === 'query' && query === undefined) ||
+			(active === 'live' && live === undefined)
+		) {
+			throw new TypeError(`invalid active operation source at ${path}.active`);
+		}
+		groups.push(
+			Object.freeze({
+				key,
+				...(query === undefined ? {} : { query }),
+				...(live === undefined ? {} : { live }),
+				...(active === undefined ? {} : { active }),
+				generation: nonNegativeInteger(raw.generation, `${path}.generation`)
+			})
+		);
+	}
+	return Object.freeze(groups);
+}
+
+export function parseOperationState(
+	value: unknown,
+	path: string
+): OperationProtocolStateV1 {
+	const raw = exactRecord(
+		value,
+		path,
+		[
+			'operation',
+			'snapshotScope',
+			'indexClocks',
+			'indexRevision',
+			'indexKeys',
+			'pathRecords',
+			'cursors'
+		],
+		['operation', 'indexClocks', 'indexKeys', 'pathRecords', 'cursors']
+	);
+	const indexClocks = parseUniquePairs(
+		raw.indexClocks,
+		`${path}.indexClocks`,
+		(entry, entryPath) => {
+			const clock = exactRecord(entry, entryPath, ['scopeToken', 'position']);
+			return Object.freeze({
+				scopeToken: nonEmptyString(clock.scopeToken, `${entryPath}.scopeToken`),
+				position: decimalString(clock.position, `${entryPath}.position`)
+			});
+		}
+	);
+	const indexKeys = uniqueStrings(raw.indexKeys, `${path}.indexKeys`);
+	const pathRecords = parseUniquePairs(
+		raw.pathRecords,
+		`${path}.pathRecords`,
+		(entry, entryPath) => nonEmptyString(entry, entryPath)
+	);
+	const cursors = arrayValue(raw.cursors, `${path}.cursors`).map(
+		(entry, index) => {
+			const entryPath = `${path}.cursors[${index}]`;
+			const cursor = exactRecord(
+				entry,
+				entryPath,
+				['projection', 'position', 'token']
+			);
+			return Object.freeze({
+				projection: nonEmptyString(cursor.projection, `${entryPath}.projection`),
+				position: decimalString(cursor.position, `${entryPath}.position`),
+				token: nonEmptyString(cursor.token, `${entryPath}.token`)
+			});
+		}
+	);
+	return Object.freeze({
+		operation: nonEmptyString(raw.operation, `${path}.operation`),
+		...(raw.snapshotScope === undefined
+			? {}
+			: {
+					snapshotScope: nonEmptyString(
+						raw.snapshotScope,
+						`${path}.snapshotScope`
+					)
+				}),
+		indexClocks,
+		...(raw.indexRevision === undefined
+			? {}
+			: {
+					indexRevision: decimalString(
+						raw.indexRevision,
+						`${path}.indexRevision`
+					)
+				}),
+		indexKeys,
+		pathRecords,
+		cursors: Object.freeze(cursors)
+	});
+}
+
+export function parseRecordClocks(
+	value: unknown
+): readonly (readonly [string, RecordClockV1])[] {
+	return parseUniquePairs(
+		value,
+		'state.payload.recordClocks',
+		(entry, path) => parseRecordClock(entry, path)
+	);
+}
+
+export function parseAnonymousRecordClocks(
+	value: unknown,
+	recordClocks: readonly (readonly [string, RecordClockV1])[]
+): readonly (readonly [string, AnonymousRecordClockV1])[] {
+	const recordScopes = new Set(recordClocks.map(([, clock]) => clock.scopeToken));
+	const result = parseUniquePairs(
+		value,
+		'state.payload.anonymousRecordClocks',
+		(entry, path) => {
+			const raw = exactRecord(entry, path, ['model', 'clock']);
+			return Object.freeze({
+				model: nonEmptyString(raw.model, `${path}.model`),
+				clock: parseRecordClock(raw.clock, `${path}.clock`)
+			});
+		}
+	);
+	for (const [scopeToken, value] of result) {
+		if (
+			value.clock.scopeToken !== scopeToken ||
+			recordScopes.has(scopeToken)
+		) {
+			throw new TypeError(
+				`invalid anonymous record scope at state.payload.anonymousRecordClocks`
+			);
+		}
+	}
+	return result;
+}
+
+export function parseRecordClock(value: unknown, path: string): RecordClockV1 {
+	const clock = exactRecord(
+		value,
+		path,
+		['scopeToken', 'incarnation', 'revision', 'tombstone']
+	);
+	return Object.freeze({
+		scopeToken: nonEmptyString(clock.scopeToken, `${path}.scopeToken`),
+		incarnation: decimalString(clock.incarnation, `${path}.incarnation`),
+		revision: decimalString(clock.revision, `${path}.revision`),
+		tombstone: booleanValue(clock.tombstone, `${path}.tombstone`)
+	});
+}
+
+export function assertMetadataConsistent(payload: ReplicaPersistencePayloadV1): void {
+	const clocksByRecord = new Map(payload.recordClocks);
+	const recordScopes = new Set<string>();
+	for (const [key, clock] of payload.recordClocks) {
+		if (recordScopes.has(clock.scopeToken)) {
+			throw new TypeError(`duplicate record scope token for ${key}`);
+		}
+		recordScopes.add(clock.scopeToken);
+	}
+	for (const record of payload.cache.records) {
+		if (modelFromRecordKey(record.key) === undefined) continue;
+		const clock = clocksByRecord.get(record.key);
+		const incarnation = record.incarnation ?? record.revision;
+		if (
+			clock === undefined ||
+			clock.incarnation !== incarnation ||
+			clock.revision !== record.revision ||
+			(
+				clock.tombstone
+					? record.tombstoneRevision !== clock.revision
+					: record.tombstoneRevision !== undefined
+			)
+		) {
+			throw new TypeError(`inconsistent persisted record clock for ${record.key}`);
+		}
+	}
+	const indexRevisions = new Map<string, Set<string>>();
+	for (const group of payload.operations) {
+		for (const state of [group.query, group.live]) {
+			if (state === undefined) continue;
+			if (
+				state.indexRevision !== undefined &&
+				compareDecimal(state.indexRevision, payload.nextIndexRevision) > 0
+			) {
+				throw new TypeError(`operation index revision exceeds checkpoint`);
+			}
+			if (state.indexRevision === undefined && state.indexKeys.length > 0) {
+				throw new TypeError(`operation index keys lack a revision`);
+			}
+			for (const [, recordKey] of state.pathRecords) {
+				if (
+					modelFromRecordKey(recordKey) !== undefined &&
+					!clocksByRecord.has(recordKey)
+				) {
+					throw new TypeError(`operation path lacks a record clock`);
+				}
+			}
+			if (state.indexRevision !== undefined) {
+				for (const key of state.indexKeys) {
+					const revisions = indexRevisions.get(key) ?? new Set<string>();
+					revisions.add(state.indexRevision);
+					indexRevisions.set(key, revisions);
+				}
+			}
+		}
+	}
+	for (const index of payload.cache.indexes) {
+		if (
+			compareDecimal(index.revision, payload.nextIndexRevision) > 0 ||
+			!indexRevisions.get(index.key)?.has(index.revision)
+		) {
+			throw new TypeError(`index lacks matching operation checkpoint: ${index.key}`);
+		}
+	}
+}
+
+export function parseStoredEntry(value: unknown): StoredReplicaEntry {
+	const entry = exactRecord(
+		value,
+		'persisted replica entry',
+		['formatVersion', 'identity', 'storedAt', 'state']
+	);
+	if (entry.formatVersion !== ENTRY_FORMAT_VERSION) {
+		throw new TypeError('unsupported persisted replica entry version');
+	}
+	const storedAt = nonNegativeInteger(entry.storedAt, 'persisted replica storedAt');
+	return Object.freeze({
+		formatVersion: 1 as const,
+		identity: nonEmptyString(entry.identity, 'persisted replica identity'),
+		storedAt,
+		state: entry.state as ReplicaDehydratedState
+	});
+}
+
+export function persistenceIdentity(scope: ReplicaAuthoritativeScope): string {
+	// JSON tuple encoding is unambiguous even when opaque scope values contain
+	// punctuation used by human-readable key formats.
+	return JSON.stringify([
+		'distributed-confirmed-replica',
+		ENTRY_FORMAT_VERSION,
+		scope.protocolVersion,
+		scope.schemaHash,
+		scope.cacheScope
+	]);
+}
+
+export function sameScope(
+	left: ReplicaAuthoritativeScope,
+	right: ReplicaAuthoritativeScope
+): boolean {
+	return (
+		left.protocolVersion === right.protocolVersion &&
+		left.schemaHash === right.schemaHash &&
+		left.cacheScope === right.cacheScope
+	);
+}
+
+export function modelFromRecordKey(key: string): string | undefined {
+	if (!key.startsWith('record:')) return undefined;
+	const separator = key.indexOf(':', 'record:'.length);
+	if (separator < 0 || separator === key.length - 1) return undefined;
+	try {
+		const model = decodeURIComponent(key.slice('record:'.length, separator));
+		return GRAPHQL_NAME.test(model) ? model : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function parseUniquePairs<T>(
+	value: unknown,
+	path: string,
+	parseValue: (value: unknown, path: string) => T
+): readonly (readonly [string, T])[] {
+	const result: Array<readonly [string, T]> = [];
+	const keys = new Set<string>();
+	for (const [index, entry] of arrayValue(value, path).entries()) {
+		const entryPath = `${path}[${index}]`;
+		if (!Array.isArray(entry) || entry.length !== 2) {
+			throw new TypeError(`invalid pair at ${entryPath}`);
+		}
+		const key = nonEmptyString(entry[0], `${entryPath}[0]`);
+		if (keys.has(key)) throw new TypeError(`duplicate key at ${entryPath}[0]`);
+		keys.add(key);
+		result.push(
+			Object.freeze([
+				key,
+				parseValue(entry[1], `${entryPath}[1]`)
+			] as const)
+		);
+	}
+	return Object.freeze(result);
+}
+
+export function uniqueStrings(value: unknown, path: string): readonly string[] {
+	const result: string[] = [];
+	const seen = new Set<string>();
+	for (const [index, entry] of arrayValue(value, path).entries()) {
+		const string = nonEmptyString(entry, `${path}[${index}]`);
+		if (seen.has(string)) throw new TypeError(`duplicate value at ${path}[${index}]`);
+		seen.add(string);
+		result.push(string);
+	}
+	return Object.freeze(result);
+}
+
+export function assertRecordLink(value: unknown, path: string): void {
+	if (value === null) return;
+	if (typeof value === 'string' && value.length > 0) return;
+	if (!Array.isArray(value)) throw new TypeError(`invalid record link at ${path}`);
+	const seen = new Set<string>();
+	for (const [index, entry] of value.entries()) {
+		const key = nonEmptyString(entry, `${path}[${index}]`);
+		if (seen.has(key)) throw new TypeError(`duplicate record link at ${path}[${index}]`);
+		seen.add(key);
+	}
+}
+
+export function assertJsonValue(
+	value: unknown,
+	path: string,
+	ancestors = new Set<object>()
+): void {
+	if (
+		value === null ||
+		typeof value === 'string' ||
+		typeof value === 'boolean'
+	) {
+		return;
+	}
+	if (typeof value === 'number') {
+		if (!Number.isFinite(value)) throw new TypeError(`non-finite number at ${path}`);
+		return;
+	}
+	if (typeof value !== 'object') throw new TypeError(`non-JSON value at ${path}`);
+	if (ancestors.has(value)) throw new TypeError(`cyclic JSON value at ${path}`);
+	ancestors.add(value);
+	if (Array.isArray(value)) {
+		for (const [index, entry] of value.entries()) {
+			assertJsonValue(entry, `${path}[${index}]`, ancestors);
+		}
+	} else {
+		const record = plainRecord(value, path);
+		for (const [key, entry] of Object.entries(record)) {
+			assertJsonValue(entry, `${path}.${key}`, ancestors);
+		}
+	}
+	ancestors.delete(value);
+}
+
+export function exactRecord(
+	value: unknown,
+	path: string,
+	allowed: readonly string[],
+	required: readonly string[] = allowed
+): Record<string, unknown> {
+	const record = plainRecord(value, path);
+	exactKeys(record, path, allowed, required);
+	return record;
+}
+
+export function exactKeys(
+	record: Record<string, unknown>,
+	path: string,
+	allowed: readonly string[],
+	required: readonly string[] = allowed
+): void {
+	const allowedKeys = new Set(allowed);
+	for (const key of Object.keys(record)) {
+		if (!allowedKeys.has(key)) throw new TypeError(`unknown field ${path}.${key}`);
+	}
+	for (const key of required) {
+		if (!Object.prototype.hasOwnProperty.call(record, key)) {
+			throw new TypeError(`missing field ${path}.${key}`);
+		}
+	}
+}
+
+export function plainRecord(value: unknown, path: string): Record<string, unknown> {
+	if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+		throw new TypeError(`expected object at ${path}`);
+	}
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) {
+		throw new TypeError(`expected plain object at ${path}`);
+	}
+	return value as Record<string, unknown>;
+}
+
+export function arrayValue(value: unknown, path: string): unknown[] {
+	if (!Array.isArray(value)) throw new TypeError(`expected array at ${path}`);
+	return value;
+}
+
+export function nonEmptyString(value: unknown, path: string): string {
+	if (typeof value !== 'string' || value.length === 0) {
+		throw new TypeError(`expected non-empty string at ${path}`);
+	}
+	return value;
+}
+
+export function decimalString(value: unknown, path: string): string {
+	const string = nonEmptyString(value, path);
+	if (!DECIMAL.test(string)) throw new TypeError(`expected decimal at ${path}`);
+	return string;
+}
+
+export function booleanValue(value: unknown, path: string): boolean {
+	if (typeof value !== 'boolean') throw new TypeError(`expected boolean at ${path}`);
+	return value;
+}
+
+export function operationSource(value: unknown, path: string): 'query' | 'live' {
+	if (value !== 'query' && value !== 'live') {
+		throw new TypeError(`expected operation source at ${path}`);
+	}
+	return value;
+}
+
+export function nonNegativeInteger(value: unknown, path: string): number {
+	if (!Number.isSafeInteger(value) || (value as number) < 0) {
+		throw new TypeError(`expected non-negative safe integer at ${path}`);
+	}
+	return value as number;
+}
+
+export function compareDecimal(left: string, right: string): -1 | 0 | 1 {
+	const leftValue = BigInt(left);
+	const rightValue = BigInt(right);
+	return leftValue < rightValue ? -1 : leftValue > rightValue ? 1 : 0;
+}
+
diff --git a/js/src/replica/persistence/types.ts b/js/src/replica/persistence/types.ts
new file mode 100644
index 00000000..1944040c
--- /dev/null
+++ b/js/src/replica/persistence/types.ts
@@ -0,0 +1,69 @@
+import type {
+	ReplicaAuthoritativeScope,
+	ReplicaDehydratedState
+} from '../types.js';
+
+export const REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED = false as const;
+
+export type ReplicaPersistenceModelPolicy = {
+	/**
+	 * Durable storage is an explicit per-model choice. `memory-only` is always
+	 * honored, even when the model is otherwise non-sensitive.
+	 */
+	readonly retention: 'persist-confirmed' | 'memory-only';
+	/**
+	 * Sensitivity must be classified explicitly. Sensitive or unclassified
+	 * models are never written to durable storage.
+	 */
+	readonly sensitive: boolean;
+};
+
+export type ReplicaPersistencePolicy = {
+	readonly models: Readonly<Record<string, ReplicaPersistenceModelPolicy>>;
+};
+
+export type ReplicaIndexedDbFactory = Pick<IDBFactory, 'open'>;
+
+export type ReplicaIndexedDbPersistenceOptions = {
+	/**
+	 * Defaults to the browser's IndexedDB factory. Supplying a factory makes the
+	 * boundary deterministic in tests and non-window runtimes.
+	 */
+	readonly indexedDB?: ReplicaIndexedDbFactory;
+	readonly databaseName?: string;
+	/**
+	 * Missing models, missing policy, `memory-only`, and `sensitive: true` all
+	 * fail closed. A model persists only when both fields explicitly allow it.
+	 */
+	readonly policy?: ReplicaPersistencePolicy;
+};
+
+export interface ReplicaIndexedDbPersistence {
+	readonly supportsOfflineCommandOutbox: false;
+
+	/**
+	 * Validate, policy-filter, and persist one confirmed dehydration envelope.
+	 *
+	 * Returns false when policy leaves no durable records or causal fences.
+	 * Malformed caller input rejects rather than entering durable storage.
+	 */
+	save(state: ReplicaDehydratedState): Promise<boolean>;
+
+	/**
+	 * Restore only after the caller has independently obtained the exact current
+	 * server scope. Corrupt, unsupported, or mismatched entries are deleted and
+	 * return undefined.
+	 */
+	restore(
+		authoritativeScope: ReplicaAuthoritativeScope
+	): Promise<ReplicaDehydratedState | undefined>;
+
+	/** Delete confirmed state for exactly one independently authoritative scope. */
+	discard(authoritativeScope: ReplicaAuthoritativeScope): Promise<void>;
+
+	/**
+	 * Close this instance's database handle. Persistence deliberately performs
+	 * no BroadcastChannel, leader election, or active multi-tab synchronization.
+	 */
+	close(): void;
+}
diff --git a/js/src/replica/query-plan.ts b/js/src/replica/query-plan.ts
new file mode 100644
index 00000000..c758d253
--- /dev/null
+++ b/js/src/replica/query-plan.ts
@@ -0,0 +1,17 @@
+/** Query plan evaluation; implementation lives in ./query-plan/. */
+export {
+	compareReplicaOrder,
+	decideReplicaPaginationMaintenance,
+	evaluateReplicaFilter
+} from './query-plan/index.js';
+export type {
+	ReplicaFilterEvaluation,
+	ReplicaFilterEvaluationOptions,
+	ReplicaOrderComparison,
+	ReplicaPaginationChange,
+	ReplicaPaginationMaintenanceDecision,
+	ReplicaQueryPlanPath,
+	ReplicaQueryPlanReason,
+	ReplicaQueryPlanReasonCode,
+	ReplicaRelationshipFilterRequest
+} from './query-plan/index.js';
diff --git a/js/src/replica/query-plan/constants.ts b/js/src/replica/query-plan/constants.ts
new file mode 100644
index 00000000..2f2d494c
--- /dev/null
+++ b/js/src/replica/query-plan/constants.ts
@@ -0,0 +1,13 @@
+import type {
+	ReplicaFilterEvaluation,
+	ReplicaOrderComparison,
+	ReplicaPaginationMaintenanceDecision
+} from './types.js';
+
+export const FILTER_MATCH = Object.freeze({ result: 'match' as const }) satisfies ReplicaFilterEvaluation;
+export const FILTER_NO_MATCH = Object.freeze({ result: 'no_match' as const }) satisfies ReplicaFilterEvaluation;
+export const ORDER_EQUAL = Object.freeze({ result: 'equal' as const }) satisfies ReplicaOrderComparison;
+export const PAGINATION_LOCAL = Object.freeze({
+	decision: 'local' as const
+}) satisfies ReplicaPaginationMaintenanceDecision;
+export const UTF8_ENCODER = new TextEncoder();
diff --git a/js/src/replica/query-plan/filter.ts b/js/src/replica/query-plan/filter.ts
new file mode 100644
index 00000000..69849ec5
--- /dev/null
+++ b/js/src/replica/query-plan/filter.ts
@@ -0,0 +1,981 @@
+import type { GraphqlVariables } from '../../types.js';
+
+import type {
+	ReplicaFilterArtifact,
+	ReplicaFilterExpression,
+	ReplicaFilterFieldArtifact,
+	ReplicaFilterLiteral,
+	ReplicaFilterOperator,
+	ReplicaRelationshipArtifact,
+	ReplicaRelationshipKeyMapping,
+	ReplicaValue
+} from '../types.js';
+import {
+	FILTER_MATCH,
+	FILTER_NO_MATCH
+} from './constants.js';
+import {
+	recordField,
+	resolveInput,
+	resolveOperand,
+	uniqueStringList
+} from './resolve.js';
+import type {
+	FilterCatalog,
+	ReplicaFilterEvaluation,
+	ReplicaFilterEvaluationOptions,
+	ReplicaQueryPlanPath,
+	ReplicaQueryPlanReason,
+	ResolvedOperand
+} from './types.js';
+import {
+	isFiniteNumber,
+	isInt32,
+	isName,
+	isPortableNumericCodec,
+	isRecord,
+	isSafeIntegerNumber,
+	isScalarCodecPair,
+	reason
+} from './util.js';
+
+export function evaluateReplicaFilter(
+	artifact: ReplicaFilterArtifact,
+	record: Readonly<Record<string, ReplicaValue>>,
+	variables: GraphqlVariables = {},
+	options: ReplicaFilterEvaluationOptions = {}
+): ReplicaFilterEvaluation {
+	const catalog = filterCatalog(artifact);
+	if ('reason' in catalog) return filterUnknown(catalog.reason);
+
+	const input = resolveInput(artifact.input, variables, ['where']);
+	const caller =
+		input.kind === 'unknown'
+			? filterUnknown(input.reason)
+			: input.kind === 'omitted' || input.value === null
+				? FILTER_MATCH
+				: evaluateCallerWhere(
+						input.value,
+						record,
+						catalog,
+						options,
+						['where']
+					);
+	const policy = evaluateRowPolicy(
+		artifact,
+		record,
+		catalog,
+		options,
+		['rowPolicy']
+	);
+	return filterAnd([caller, policy]);
+}
+
+export function evaluateCallerWhere(
+	value: ReplicaValue,
+	record: Readonly<Record<string, ReplicaValue>>,
+	catalog: FilterCatalog,
+	options: ReplicaFilterEvaluationOptions,
+	path: ReplicaQueryPlanPath
+): ReplicaFilterEvaluation {
+	if (value === null) return FILTER_MATCH;
+	if (!isRecord(value)) {
+		return filterUnknown(
+			reason(
+				'invalid_filter_input',
+				path,
+				'where predicates must be objects'
+			)
+		);
+	}
+	const predicates: ReplicaFilterEvaluation[] = [];
+	for (const [key, predicate] of Object.entries(value)) {
+		const predicatePath = [...path, key];
+		if (key === '_and' || key === '_or') {
+			if (predicate === null) continue;
+			const items = Array.isArray(predicate)
+				? predicate
+				: isRecord(predicate)
+					? [predicate]
+					: undefined;
+			if (items === undefined) {
+				predicates.push(
+					filterUnknown(
+						reason(
+							'invalid_filter_input',
+							predicatePath,
+							`${key} must be an object or list of objects`
+						)
+					)
+				);
+				continue;
+			}
+			// The server treats both empty caller lists as no predicate (TRUE).
+			if (items.length === 0) continue;
+			const evaluated = items.map((item, index) =>
+				evaluateCallerWhere(
+					item,
+					record,
+					catalog,
+					options,
+					[...predicatePath, index]
+				)
+			);
+			predicates.push(key === '_and' ? filterAnd(evaluated) : filterOr(evaluated));
+			continue;
+		}
+		if (key === '_not') {
+			if (predicate === null) {
+				predicates.push(FILTER_NO_MATCH);
+			} else {
+				predicates.push(
+					filterNot(
+						evaluateCallerWhere(
+							predicate,
+							record,
+							catalog,
+							options,
+							predicatePath
+						)
+					)
+				);
+			}
+			continue;
+		}
+
+		const field = catalog.fields.get(key);
+		if (field !== undefined) {
+			predicates.push(
+				evaluateCallerField(field, predicate, record, predicatePath)
+			);
+			continue;
+		}
+		const relationship = catalog.relationships.get(key);
+		if (relationship !== undefined) {
+			const resolver = options.resolveRelationship;
+			predicates.push(
+				resolver === undefined
+					? filterUnknown(
+							reason(
+								'relationship_resolver_required',
+								predicatePath,
+								`relationship predicate ${key} requires an explicit resolver`
+							)
+						)
+					: resolver({
+							source: 'caller',
+							relationship,
+							predicate,
+							record,
+							path: Object.freeze(predicatePath)
+						})
+			);
+			continue;
+		}
+		predicates.push(
+			filterUnknown(
+				reason(
+					'unknown_field',
+					predicatePath,
+					`where field ${key} is not declared by the artifact`
+				)
+			)
+		);
+	}
+	return filterAnd(predicates);
+}
+
+export function evaluateCallerField(
+	field: ReplicaFilterFieldArtifact,
+	value: ReplicaValue,
+	record: Readonly<Record<string, ReplicaValue>>,
+	path: ReplicaQueryPlanPath
+): ReplicaFilterEvaluation {
+	if (value === null) return FILTER_MATCH;
+	if (!isRecord(value)) {
+		return filterUnknown(
+			reason(
+				'invalid_filter_input',
+				path,
+				`comparison expression for ${field.field} must be an object`
+			)
+		);
+	}
+	const predicates: ReplicaFilterEvaluation[] = [];
+	for (const [rawOperator, rhs] of Object.entries(value)) {
+		const operatorPath = [...path, rawOperator];
+		if (
+			!isFilterOperator(rawOperator) ||
+			!field.operators.includes(rawOperator)
+		) {
+			predicates.push(
+				filterUnknown(
+					reason(
+						'unsupported_operator',
+						operatorPath,
+						`operator ${rawOperator} is not declared for ${field.field}`
+					)
+				)
+			);
+			continue;
+		}
+		const left = recordField(record, field.field, operatorPath);
+		if (left.kind === 'unknown') {
+			predicates.push(filterUnknown(left.reason));
+			continue;
+		}
+		predicates.push(
+			evaluateClientOperator(field, rawOperator, left.value, rhs, operatorPath)
+		);
+	}
+	return filterAnd(predicates);
+}
+
+export function evaluateClientOperator(
+	field: ReplicaFilterFieldArtifact,
+	operator: ReplicaFilterOperator,
+	left: ReplicaValue,
+	rhs: ReplicaValue,
+	path: ReplicaQueryPlanPath
+): ReplicaFilterEvaluation {
+	if (operator === '_is_null') {
+		if (rhs !== null && typeof rhs !== 'boolean') {
+			return filterUnknown(
+				reason(
+					'invalid_filter_value',
+					path,
+					'_is_null must be a boolean or null'
+				)
+			);
+		}
+		const wantsNull = rhs === true;
+		return (left === null) === wantsNull ? FILTER_MATCH : FILTER_NO_MATCH;
+	}
+	if (operator === '_in' || operator === '_nin') {
+		if (rhs === null) {
+			return filterUnknown(
+				reason('invalid_filter_value', path, `${operator} requires a list`)
+			);
+		}
+		const values = Array.isArray(rhs) ? rhs : [rhs];
+		return evaluateIn(field.codec, left, values, operator === '_nin', path);
+	}
+	return evaluateComparison(field.codec, operator, left, rhs, path);
+}
+
+export function evaluateRowPolicy(
+	artifact: ReplicaFilterArtifact,
+	record: Readonly<Record<string, ReplicaValue>>,
+	catalog: FilterCatalog,
+	options: ReplicaFilterEvaluationOptions,
+	path: ReplicaQueryPlanPath
+): ReplicaFilterEvaluation {
+	const policy = artifact.rowPolicy;
+	if (policy.kind === 'unrestricted') return FILTER_MATCH;
+	if (policy.kind === 'server_only') {
+		return filterUnknown(
+			reason(
+				'server_only_policy',
+				path,
+				'server-only row policy cannot be evaluated in the replica'
+			)
+		);
+	}
+	if (policy.kind !== 'predicate' || !isRecord(policy.expression)) {
+		return filterUnknown(
+			reason('invalid_artifact', path, 'row policy artifact is malformed')
+		);
+	}
+	return evaluatePolicyExpression(
+		policy.expression,
+		record,
+		catalog,
+		options,
+		[...path, 'expression']
+	);
+}
+
+export function evaluatePolicyExpression(
+	expression: ReplicaFilterExpression,
+	record: Readonly<Record<string, ReplicaValue>>,
+	catalog: FilterCatalog,
+	options: ReplicaFilterEvaluationOptions,
+	path: ReplicaQueryPlanPath
+): ReplicaFilterEvaluation {
+	if (expression.kind === 'and' || expression.kind === 'or') {
+		if (!Array.isArray(expression.value)) {
+			return filterUnknown(
+				reason('invalid_artifact', path, 'row-policy boolean value must be a list')
+			);
+		}
+		const evaluated = expression.value.map((item, index) =>
+			evaluatePolicyExpression(
+				item,
+				record,
+				catalog,
+				options,
+				[...path, expression.kind, index]
+			)
+		);
+		// Unlike caller `_or: []`, a row-policy Or([]) is SQL FALSE.
+		return expression.kind === 'and' ? filterAnd(evaluated) : filterOr(evaluated);
+	}
+	if (expression.kind === 'not') {
+		return filterNot(
+			evaluatePolicyExpression(
+				expression.value,
+				record,
+				catalog,
+				options,
+				[...path, 'not']
+			)
+		);
+	}
+	if (expression.kind === 'rel') {
+		const field = expression.value.field;
+		const relationshipPath = [...path, 'rel', field];
+		const relationship = catalog.relationships.get(field);
+		if (relationship === undefined) {
+			return filterUnknown(
+				reason(
+					'unknown_relationship',
+					relationshipPath,
+					`row policy relationship ${field} is not declared by the artifact`
+				)
+			);
+		}
+		const resolver = options.resolveRelationship;
+		return resolver === undefined
+			? filterUnknown(
+					reason(
+						'relationship_resolver_required',
+						relationshipPath,
+						`row policy relationship ${field} requires an explicit resolver`
+					)
+				)
+			: resolver({
+					source: 'row_policy',
+					relationship,
+					predicate: expression.value.predicate,
+					record,
+					path: Object.freeze(relationshipPath)
+				});
+	}
+	if (
+		expression.kind !== 'cmp' &&
+		expression.kind !== 'in' &&
+		expression.kind !== 'is_null'
+	) {
+		return filterUnknown(
+			reason('invalid_artifact', path, 'row policy expression kind is unsupported')
+		);
+	}
+
+	const column = expression.value.column;
+	const field = catalog.fields.get(column);
+	const columnPath = [...path, expression.kind, column];
+	if (field === undefined) {
+		return filterUnknown(
+			reason(
+				'unknown_field',
+				columnPath,
+				`row policy field ${column} is not declared by the artifact`
+			)
+		);
+	}
+	const left = recordField(record, column, columnPath);
+	if (left.kind === 'unknown') return filterUnknown(left.reason);
+	if (expression.kind === 'is_null') {
+		if (typeof expression.value.is_null !== 'boolean') {
+			return filterUnknown(
+				reason(
+					'invalid_artifact',
+					[...columnPath, 'is_null'],
+					'row-policy is_null must be a boolean'
+				)
+			);
+		}
+		return (left.value === null) === expression.value.is_null
+			? FILTER_MATCH
+			: FILTER_NO_MATCH;
+	}
+	if (expression.kind === 'cmp') {
+		const operator = `_${expression.value.op}` as ReplicaFilterOperator;
+		if (
+			!isFilterOperator(operator) ||
+			!isOperatorScalarCompatible(field.scalar, operator)
+		) {
+			return filterUnknown(
+				reason(
+					'invalid_artifact',
+					[...columnPath, 'op'],
+					`row-policy operator ${expression.value.op} cannot target ${field.scalar}`
+				)
+			);
+		}
+		const operand = resolveOperand(
+			expression.value.rhs,
+			field,
+			options,
+			[...columnPath, 'rhs']
+		);
+		if (operand.kind === 'unknown') return filterUnknown(operand.reason);
+		const literalValidity = validateRowPolicyLiteral(
+			field,
+			operand,
+			[...columnPath, 'rhs'],
+			operator
+		);
+		if (literalValidity !== undefined) return filterUnknown(literalValidity);
+		return evaluateComparison(
+			field.codec,
+			`_${expression.value.op}` as ReplicaFilterOperator,
+			left.value,
+			operand.value,
+			columnPath
+		);
+	}
+	if (expression.kind === 'in') {
+		if (
+			typeof expression.value.negated !== 'boolean' ||
+			!Array.isArray(expression.value.values)
+		) {
+			return filterUnknown(
+				reason(
+					'invalid_artifact',
+					columnPath,
+					'row-policy IN values must be a list and negated must be a boolean'
+				)
+			);
+		}
+		const values: ReplicaValue[] = [];
+		for (const [index, operand] of expression.value.values.entries()) {
+			const operandPath = [...columnPath, 'values', index];
+			const resolved = resolveOperand(operand, field, options, operandPath);
+			if (resolved.kind === 'unknown') return filterUnknown(resolved.reason);
+			const literalValidity = validateRowPolicyLiteral(
+				field,
+				resolved,
+				operandPath
+			);
+			if (literalValidity !== undefined) return filterUnknown(literalValidity);
+			values.push(resolved.value);
+		}
+		return evaluateIn(
+			field.codec,
+			left.value,
+			values,
+			expression.value.negated,
+			columnPath
+		);
+	}
+	return filterUnknown(
+		reason('invalid_artifact', path, 'row policy expression kind is unsupported')
+	);
+}
+
+export function evaluateComparison(
+	codec: string,
+	operator: ReplicaFilterOperator,
+	left: ReplicaValue,
+	right: ReplicaValue,
+	path: ReplicaQueryPlanPath
+): ReplicaFilterEvaluation {
+	if (
+		operator === '_like' ||
+		operator === '_ilike' ||
+		operator === '_contains' ||
+		operator === '_contained_in' ||
+		operator === '_has_key'
+	) {
+		return filterUnknown(
+			reason(
+				'unsupported_operator',
+				path,
+				`${operator} has no certified cross-dialect replica evaluator`
+			)
+		);
+	}
+	if (left === null || right === null) {
+		return filterUnknown(
+			reason('sql_null', path, 'SQL comparison with null is unknown')
+		);
+	}
+	const validity = validateComparableValues(codec, left, right, path);
+	if (validity !== undefined) return filterUnknown(validity);
+	if (operator === '_eq' || operator === '_neq') {
+		if (codec === 'string' && left !== right) {
+			return filterUnknown(
+				reason(
+					'collation_not_portable',
+					path,
+					'non-identical strings require an explicit server collation contract'
+				)
+			);
+		}
+		const equal = left === right;
+		return equal === (operator === '_eq') ? FILTER_MATCH : FILTER_NO_MATCH;
+	}
+	if (
+		operator !== '_gt' &&
+		operator !== '_gte' &&
+		operator !== '_lt' &&
+		operator !== '_lte'
+	) {
+		return filterUnknown(
+			reason('unsupported_operator', path, `operator ${operator} is not portable`)
+		);
+	}
+	if (!isPortableNumericCodec(codec)) {
+		return filterUnknown(
+			reason(
+				'unsupported_operator',
+				path,
+				`${operator} is portable only for certified numeric codecs`
+			)
+		);
+	}
+	const a = left as number;
+	const b = right as number;
+	const matches =
+		operator === '_gt'
+			? a > b
+			: operator === '_gte'
+				? a >= b
+				: operator === '_lt'
+					? a < b
+					: a <= b;
+	return matches ? FILTER_MATCH : FILTER_NO_MATCH;
+}
+
+export function evaluateIn(
+	codec: string,
+	left: ReplicaValue,
+	values: readonly ReplicaValue[],
+	negated: boolean,
+	path: ReplicaQueryPlanPath
+): ReplicaFilterEvaluation {
+	// Server compilation special-cases empty lists before evaluating the column.
+	if (values.length === 0) return negated ? FILTER_MATCH : FILTER_NO_MATCH;
+	if (left === null) {
+		return filterUnknown(
+			reason('sql_null', path, 'SQL IN comparison with a null column is unknown')
+		);
+	}
+	// GraphQL rejects a type-invalid list before SQL runs. Validate every
+	// non-null candidate before allowing a later equality to establish truth.
+	// SQL NULL is different: a concrete equality may still dominate UNKNOWN.
+	for (const [index, candidate] of values.entries()) {
+		if (candidate === null) continue;
+		const validity = validateComparableValues(
+			codec,
+			left,
+			candidate,
+			[...path, index]
+		);
+		if (validity !== undefined) return filterUnknown(validity);
+	}
+	let firstUnknown: ReplicaQueryPlanReason | undefined;
+	for (const [index, candidate] of values.entries()) {
+		if (candidate === null) {
+			firstUnknown ??= reason(
+				'sql_null',
+				[...path, index],
+				'SQL IN list containing null can produce an unknown result'
+			);
+			continue;
+		}
+		if (left === candidate) return negated ? FILTER_NO_MATCH : FILTER_MATCH;
+		if (codec === 'string') {
+			firstUnknown ??= reason(
+				'collation_not_portable',
+				[...path, index],
+				'non-identical strings in SQL IN require an explicit server collation contract'
+			);
+		}
+	}
+	if (firstUnknown !== undefined) return filterUnknown(firstUnknown);
+	return negated ? FILTER_MATCH : FILTER_NO_MATCH;
+}
+
+export function validateComparableValues(
+	codec: string,
+	left: ReplicaValue,
+	right: ReplicaValue,
+	path: ReplicaQueryPlanPath
+): ReplicaQueryPlanReason | undefined {
+	if (codec === 'string') {
+		return typeof left === 'string' && typeof right === 'string'
+			? undefined
+			: reason(
+					'invalid_filter_value',
+					path,
+					'string codec requires string values'
+				);
+	}
+	if (codec === 'boolean') {
+		return typeof left === 'boolean' && typeof right === 'boolean'
+			? undefined
+			: reason(
+					'invalid_filter_value',
+					path,
+					'boolean codec requires boolean values'
+				);
+	}
+	if (codec === 'int32') {
+		return isInt32(left) && isInt32(right)
+			? undefined
+			: reason(
+					'invalid_filter_value',
+					path,
+					'int32 codec requires signed 32-bit integer values'
+				);
+	}
+	if (codec === 'float64') {
+		return isFiniteNumber(left) && isFiniteNumber(right)
+			? undefined
+			: reason(
+					'invalid_filter_value',
+					path,
+					'float64 codec requires finite number values'
+				);
+	}
+	if (codec === 'json_number_precision_limited') {
+		return isSafeIntegerNumber(left) && isSafeIntegerNumber(right)
+			? undefined
+			: reason(
+					'invalid_filter_value',
+					path,
+					'BigInt codec requires JavaScript-safe integer values'
+				);
+	}
+	return reason(
+		'unsupported_codec',
+		path,
+		`codec ${codec} has no certified replica comparison semantics`
+	);
+}
+
+/**
+ * Protocol v1 orders strings by their unsigned UTF-8 bytes. The GraphQL SQL
+ * compiler emits the matching binary collation for every textual ORDER BY,
+ * making optimistic index maintenance identical on SQLite and PostgreSQL.
+ */
+
+export function validateRowPolicyLiteral(
+	field: ReplicaFilterFieldArtifact,
+	operand: Extract<ResolvedOperand, { readonly kind: 'value' }>,
+	path: ReplicaQueryPlanPath,
+	operator?: ReplicaFilterOperator
+): ReplicaQueryPlanReason | undefined {
+	if (operand.source === 'trusted_preset') return undefined;
+	const literalKind = operand.literalKind;
+	if (literalKind === undefined) {
+		return reason(
+			'invalid_artifact',
+			path,
+			'row-policy literal is missing its tagged kind'
+		);
+	}
+	if (literalKind === 'null') return undefined;
+	const expected: readonly ReplicaFilterLiteral['kind'][] | undefined =
+		field.scalar === 'ID' ||
+		field.scalar === 'String' ||
+		field.scalar === 'Timestamptz'
+			? ['string']
+			: field.scalar === 'Boolean'
+				? ['bool']
+				: field.scalar === 'Int' || field.scalar === 'BigInt'
+					? ['i64']
+					: field.scalar === 'Float'
+						? ['f64', 'i64']
+						: field.scalar === 'JSON'
+							? operator === '_has_key'
+								? ['string']
+								: ['json']
+							: undefined;
+	if (expected?.includes(literalKind)) return undefined;
+	return reason(
+		'invalid_artifact',
+		path,
+		expected === undefined
+			? `scalar ${field.scalar} has no non-null row-policy literal encoding`
+			: `row-policy literal kind ${literalKind} cannot target ${field.scalar}; expected ${expected.join(' or ')}`
+	);
+}
+
+export function filterCatalog(
+	artifact: ReplicaFilterArtifact
+):
+	| FilterCatalog
+	| {
+			readonly reason: ReplicaQueryPlanReason;
+	  } {
+	const fields = new Map<string, ReplicaFilterFieldArtifact>();
+	for (const [index, field] of artifact.fields.entries()) {
+		if (
+			!isName(field.field) ||
+			!isScalarCodecPair(field.scalar, field.codec) ||
+			typeof field.nullable !== 'boolean' ||
+			!Array.isArray(field.operators) ||
+			fields.has(field.field)
+		) {
+			return {
+				reason: reason(
+					'invalid_artifact',
+					['filter', 'fields', index],
+					'filter fields must have unique names, exact scalar-codec pairs, nullability, and operators'
+				)
+			};
+		}
+		const operators = new Set<ReplicaFilterOperator>();
+		for (const [operatorIndex, operator] of field.operators.entries()) {
+			if (
+				!isFilterOperator(operator) ||
+				!isOperatorScalarCompatible(field.scalar, operator) ||
+				operators.has(operator)
+			) {
+				return {
+					reason: reason(
+						'invalid_artifact',
+						['filter', 'fields', index, 'operators', operatorIndex],
+						'filter operators must be unique and compatible with the field scalar'
+					)
+				};
+			}
+			operators.add(operator);
+		}
+		fields.set(field.field, field);
+	}
+	const relationships = new Map<string, ReplicaRelationshipArtifact>();
+	for (const [index, value] of artifact.relationships.entries()) {
+		const parsed = relationshipArtifact(value, [
+			'filter',
+			'relationships',
+			index
+		]);
+		if ('reason' in parsed) return parsed;
+		const relationship = parsed.value;
+		if (relationships.has(relationship.field)) {
+			return {
+				reason: reason(
+					'invalid_artifact',
+					['filter', 'relationships', index],
+					'filter relationship descriptors must have unique fields'
+				)
+			};
+		}
+		relationships.set(relationship.field, relationship);
+	}
+	return { fields, relationships };
+}
+
+export function relationshipArtifact(
+	value: unknown,
+	path: ReplicaQueryPlanPath
+):
+	| { readonly value: ReplicaRelationshipArtifact }
+	| { readonly reason: ReplicaQueryPlanReason } {
+	if (
+		!isRecord(value) ||
+		!isName(value.field) ||
+		!isName(value.targetModel) ||
+		(value.kind !== 'has_many' &&
+			value.kind !== 'belongs_to' &&
+			value.kind !== 'many_to_many') ||
+		(value.maintenance !== 'local' && value.maintenance !== 'revalidate')
+	) {
+		return {
+			reason: reason(
+				'invalid_artifact',
+				path,
+				'relationship descriptor has invalid field, target, kind, or maintenance'
+			)
+		};
+	}
+	const dependencies = uniqueStringList(value.dependencies);
+	if (dependencies === undefined || dependencies.length === 0) {
+		return {
+			reason: reason(
+				'invalid_artifact',
+				[...path, 'dependencies'],
+				'relationship dependencies must be a non-empty unique string list'
+			)
+		};
+	}
+	const keyMapping = relationshipKeyMapping(
+		value.keyMapping,
+		dependencies,
+		[...path, 'keyMapping']
+	);
+	if ('reason' in keyMapping) return keyMapping;
+	const localMapping =
+		keyMapping.value.kind === 'direct' || keyMapping.value.kind === 'through';
+	if (!localMapping && value.maintenance !== 'revalidate') {
+		return {
+			reason: reason(
+				'invalid_artifact',
+				[...path, 'maintenance'],
+				'opaque and embedded mappings must use revalidation maintenance'
+			)
+		};
+	}
+	return {
+		value: Object.freeze({
+			field: value.field,
+			targetModel: value.targetModel,
+			kind: value.kind,
+			keyMapping: keyMapping.value,
+			maintenance: value.maintenance,
+			dependencies
+		})
+	};
+}
+
+export function relationshipKeyMapping(
+	value: unknown,
+	dependencies: readonly string[],
+	path: ReplicaQueryPlanPath
+):
+	| { readonly value: ReplicaRelationshipKeyMapping }
+	| { readonly reason: ReplicaQueryPlanReason } {
+	if (!isRecord(value) || !isName(value.kind)) {
+		return {
+			reason: reason(
+				'invalid_artifact',
+				path,
+				'relationship key mapping must declare a supported kind'
+			)
+		};
+	}
+	if (value.kind === 'embedded') {
+		return { value: Object.freeze({ kind: 'embedded' as const }) };
+	}
+	const local = uniqueStringList(value.local);
+	const remote = uniqueStringList(value.remote);
+	if (
+		local === undefined ||
+		remote === undefined ||
+		local.length === 0 ||
+		local.length !== remote.length
+	) {
+		return {
+			reason: reason(
+				'invalid_artifact',
+				path,
+				'relationship key lists must be unique, non-empty, and equally sized'
+			)
+		};
+	}
+	if (value.kind === 'direct') {
+		return {
+			value: Object.freeze({ kind: 'direct' as const, local, remote })
+		};
+	}
+	if (
+		value.kind === 'through' &&
+		isName(value.table) &&
+		dependencies.includes(value.table) &&
+		isName(value.sourceForeignKey) &&
+		isName(value.targetForeignKey)
+	) {
+		return {
+			value: Object.freeze({
+				kind: 'through' as const,
+				local,
+				remote,
+				table: value.table,
+				sourceForeignKey: value.sourceForeignKey,
+				targetForeignKey: value.targetForeignKey
+			})
+		};
+	}
+	if (
+		value.kind === 'through_opaque' &&
+		isName(value.dependency) &&
+		dependencies.includes(value.dependency)
+	) {
+		return {
+			value: Object.freeze({
+				kind: 'through_opaque' as const,
+				local,
+				remote,
+				dependency: value.dependency
+			})
+		};
+	}
+	return {
+		reason: reason(
+			'invalid_artifact',
+			path,
+			'relationship key mapping is incomplete or references an undeclared dependency'
+		)
+	};
+}
+
+export function filterAnd(
+	values: readonly ReplicaFilterEvaluation[]
+): ReplicaFilterEvaluation {
+	let firstUnknown: ReplicaQueryPlanReason | undefined;
+	for (const value of values) {
+		if (value.result === 'no_match') return FILTER_NO_MATCH;
+		if (value.result === 'unknown') firstUnknown ??= value.reason;
+	}
+	return firstUnknown === undefined ? FILTER_MATCH : filterUnknown(firstUnknown);
+}
+
+export function filterOr(
+	values: readonly ReplicaFilterEvaluation[]
+): ReplicaFilterEvaluation {
+	let firstUnknown: ReplicaQueryPlanReason | undefined;
+	for (const value of values) {
+		if (value.result === 'match') return FILTER_MATCH;
+		if (value.result === 'unknown') firstUnknown ??= value.reason;
+	}
+	return firstUnknown === undefined ? FILTER_NO_MATCH : filterUnknown(firstUnknown);
+}
+
+export function filterNot(value: ReplicaFilterEvaluation): ReplicaFilterEvaluation {
+	if (value.result === 'unknown') return value;
+	return value.result === 'match' ? FILTER_NO_MATCH : FILTER_MATCH;
+}
+
+export function filterUnknown(reasonValue: ReplicaQueryPlanReason): ReplicaFilterEvaluation {
+	return Object.freeze({ result: 'unknown' as const, reason: reasonValue });
+}
+
+export function isFilterOperator(value: string): value is ReplicaFilterOperator {
+	return (
+		value === '_eq' ||
+		value === '_neq' ||
+		value === '_gt' ||
+		value === '_gte' ||
+		value === '_lt' ||
+		value === '_lte' ||
+		value === '_in' ||
+		value === '_nin' ||
+		value === '_is_null' ||
+		value === '_like' ||
+		value === '_ilike' ||
+		value === '_contains' ||
+		value === '_contained_in' ||
+		value === '_has_key'
+	);
+}
+
+export function isOperatorScalarCompatible(
+	scalar: string,
+	operator: ReplicaFilterOperator
+): boolean {
+	if (operator === '_like' || operator === '_ilike') {
+		return scalar === 'String';
+	}
+	if (
+		operator === '_contains' ||
+		operator === '_contained_in' ||
+		operator === '_has_key'
+	) {
+		return scalar === 'JSON';
+	}
+	return true;
+}
diff --git a/js/src/replica/query-plan/index.ts b/js/src/replica/query-plan/index.ts
new file mode 100644
index 00000000..4f4a13f0
--- /dev/null
+++ b/js/src/replica/query-plan/index.ts
@@ -0,0 +1,14 @@
+export type {
+	ReplicaFilterEvaluation,
+	ReplicaFilterEvaluationOptions,
+	ReplicaOrderComparison,
+	ReplicaPaginationChange,
+	ReplicaPaginationMaintenanceDecision,
+	ReplicaQueryPlanPath,
+	ReplicaQueryPlanReason,
+	ReplicaQueryPlanReasonCode,
+	ReplicaRelationshipFilterRequest
+} from './types.js';
+export { evaluateReplicaFilter } from './filter.js';
+export { compareReplicaOrder } from './order.js';
+export { decideReplicaPaginationMaintenance } from './pagination.js';
diff --git a/js/src/replica/query-plan/order.ts b/js/src/replica/query-plan/order.ts
new file mode 100644
index 00000000..8dec31e5
--- /dev/null
+++ b/js/src/replica/query-plan/order.ts
@@ -0,0 +1,287 @@
+import type { GraphqlVariables } from '../../types.js';
+import type {
+	ReplicaOrderArtifact,
+	ReplicaOrderFieldArtifact,
+	ReplicaValue
+} from '../types.js';
+import { ORDER_EQUAL, UTF8_ENCODER } from './constants.js';
+import { recordField, resolveInput } from './resolve.js';
+import type {
+	OrderDirection,
+	ReplicaOrderComparison,
+	ReplicaQueryPlanPath,
+	ReplicaQueryPlanReason
+} from './types.js';
+import {
+	isName,
+	isPortableNumericCodec,
+	isRecord,
+	isScalarCodecPair,
+	reason
+} from './util.js';
+import { validateComparableValues } from './filter.js';
+
+export function compareReplicaOrder(
+	artifact: ReplicaOrderArtifact,
+	left: Readonly<Record<string, ReplicaValue>>,
+	right: Readonly<Record<string, ReplicaValue>>,
+	variables: GraphqlVariables = {}
+): ReplicaOrderComparison {
+	const fields = new Map<string, ReplicaOrderFieldArtifact>();
+	for (const [index, field] of artifact.fields.entries()) {
+		if (
+			!isName(field.field) ||
+			!isScalarCodecPair(field.scalar, field.codec) ||
+			typeof field.nullable !== 'boolean' ||
+			fields.has(field.field)
+		) {
+			return orderUnknown(
+				reason(
+					'invalid_artifact',
+					['order', 'fields', index],
+					'order fields must have unique names, exact scalar-codec pairs, and nullability'
+				)
+			);
+		}
+		fields.set(field.field, field);
+	}
+	const tieBreakerFields = new Set<string>();
+	for (const [index, tieBreaker] of artifact.tieBreakers.entries()) {
+		if (
+			!isName(tieBreaker.field) ||
+			!isScalarCodecPair(tieBreaker.scalar, tieBreaker.codec) ||
+			tieBreaker.nullable !== false ||
+			tieBreakerFields.has(tieBreaker.field)
+		) {
+			return orderUnknown(
+				reason(
+					'invalid_artifact',
+					['order', 'tieBreakers', index],
+					'order tie-breakers must have unique fields and exact scalar-codec pairs'
+				)
+			);
+		}
+		tieBreakerFields.add(tieBreaker.field);
+	}
+
+	const input = resolveInput(artifact.input, variables, ['order_by']);
+	if (input.kind === 'unknown') return orderUnknown(input.reason);
+	const entries: readonly ReplicaValue[] =
+		input.kind === 'omitted' || input.value === null
+			? []
+			: Array.isArray(input.value)
+				? input.value
+				: isRecord(input.value)
+					? [input.value]
+					: [];
+	if (
+		input.kind === 'value' &&
+		input.value !== null &&
+		!Array.isArray(input.value) &&
+		!isRecord(input.value)
+	) {
+		return orderUnknown(
+			reason(
+				'invalid_order_input',
+				['order_by'],
+				'order_by must be an object or a list of objects'
+			)
+		);
+	}
+
+	for (const [index, entry] of entries.entries()) {
+		const path: ReplicaQueryPlanPath = ['order_by', index];
+		if (!isRecord(entry)) {
+			return orderUnknown(
+				reason(
+					'invalid_order_input',
+					path,
+					'each order_by entry must be an object'
+				)
+			);
+		}
+		const pairs = Object.entries(entry);
+		if (pairs.length === 0) continue;
+		if (pairs.length > 1) {
+			return orderUnknown(
+				reason(
+					'ambiguous_order_entry',
+					path,
+					'each order_by entry may declare at most one field'
+				)
+			);
+		}
+		const [fieldName, rawDirection] = pairs[0]!;
+		const field = fields.get(fieldName);
+		if (field === undefined) {
+			return orderUnknown(
+				reason(
+					'unknown_field',
+					[...path, fieldName],
+					`order field ${fieldName} is not declared by the artifact`
+				)
+			);
+		}
+		if (!isOrderDirection(rawDirection)) {
+			return orderUnknown(
+				reason(
+					'invalid_order_direction',
+					[...path, fieldName],
+					`order direction for ${fieldName} is not supported`
+				)
+			);
+		}
+		if (field.nullable && !hasExplicitNullPlacement(rawDirection)) {
+			return orderUnknown(
+				reason(
+					'implicit_null_order',
+					[...path, fieldName],
+					`nullable order field ${fieldName} requires explicit null placement`
+				)
+			);
+		}
+		const compared = compareOrderField(
+			field.field,
+			field.codec,
+			field.nullable,
+			rawDirection,
+			left,
+			right,
+			[...path, fieldName]
+		);
+		if (compared.result !== 'equal') return compared;
+	}
+
+	for (const [index, tieBreaker] of artifact.tieBreakers.entries()) {
+		const compared = compareOrderField(
+			tieBreaker.field,
+			tieBreaker.codec,
+			false,
+			'asc',
+			left,
+			right,
+			['order', 'tieBreakers', index, tieBreaker.field]
+		);
+		if (compared.result !== 'equal') return compared;
+	}
+	if (artifact.tieBreakers.length === 0) {
+		return orderUnknown(
+			reason(
+				'invalid_artifact',
+				['order', 'tieBreakers'],
+				'equal order values require a complete identity tie-breaker'
+			)
+		);
+	}
+	return ORDER_EQUAL;
+}
+
+export function compareOrderField(
+	field: string,
+	codec: string,
+	nullable: boolean,
+	direction: OrderDirection,
+	left: Readonly<Record<string, ReplicaValue>>,
+	right: Readonly<Record<string, ReplicaValue>>,
+	path: ReplicaQueryPlanPath
+): ReplicaOrderComparison {
+	const a = recordField(left, field, path);
+	if (a.kind === 'unknown') return orderUnknown(a.reason);
+	const b = recordField(right, field, path);
+	if (b.kind === 'unknown') return orderUnknown(b.reason);
+	if ((a.value === null || b.value === null) && !nullable) {
+		return orderUnknown(
+			reason(
+				'invalid_order_value',
+				path,
+				`non-null order field ${field} contains null`
+			)
+		);
+	}
+	if (a.value === null || b.value === null) {
+		if (a.value === null && b.value === null) return ORDER_EQUAL;
+		if (!hasExplicitNullPlacement(direction)) {
+			return orderUnknown(
+				reason(
+					'implicit_null_order',
+					path,
+					`nullable order field ${field} requires explicit null placement`
+				)
+			);
+		}
+		const nullFirst = direction.endsWith('_nulls_first');
+		return orderResult((a.value === null) === nullFirst ? -1 : 1);
+	}
+
+	const validity = validateComparableValues(codec, a.value, b.value, path);
+	if (validity !== undefined) return orderUnknown(validity);
+	let comparison: -1 | 0 | 1;
+	if (isPortableNumericCodec(codec)) {
+		comparison =
+			(a.value as number) < (b.value as number)
+				? -1
+				: (a.value as number) > (b.value as number)
+					? 1
+					: 0;
+	} else if (codec === 'boolean') {
+		comparison =
+			a.value === b.value ? 0 : a.value === false && b.value === true ? -1 : 1;
+	} else if (codec === 'string') {
+		comparison = compareUtf8(
+			a.value as string,
+			b.value as string
+		);
+	} else {
+		return orderUnknown(
+			reason(
+				'unsupported_codec',
+				path,
+				`codec ${codec} has no certified replica comparator`
+			)
+		);
+	}
+	if (comparison === 0) return ORDER_EQUAL;
+	return orderResult(direction.startsWith('desc') ? invert(comparison) : comparison);
+}
+
+export function compareUtf8(left: string, right: string): -1 | 0 | 1 {
+	if (left === right) return 0;
+	const leftBytes = UTF8_ENCODER.encode(left);
+	const rightBytes = UTF8_ENCODER.encode(right);
+	const length = Math.min(leftBytes.length, rightBytes.length);
+	for (let index = 0; index < length; index += 1) {
+		const a = leftBytes[index]!;
+		const b = rightBytes[index]!;
+		if (a !== b) return a < b ? -1 : 1;
+	}
+	return leftBytes.length < rightBytes.length ? -1 : 1;
+}
+
+export function orderUnknown(reasonValue: ReplicaQueryPlanReason): ReplicaOrderComparison {
+	return Object.freeze({ result: 'unknown' as const, reason: reasonValue });
+}
+
+export function orderResult(comparison: -1 | 1): ReplicaOrderComparison {
+	return Object.freeze({
+		result: comparison < 0 ? ('less' as const) : ('greater' as const)
+	});
+}
+
+export function isOrderDirection(value: ReplicaValue): value is OrderDirection {
+	return (
+		value === 'asc' ||
+		value === 'asc_nulls_first' ||
+		value === 'asc_nulls_last' ||
+		value === 'desc' ||
+		value === 'desc_nulls_first' ||
+		value === 'desc_nulls_last'
+	);
+}
+
+export function hasExplicitNullPlacement(direction: OrderDirection): boolean {
+	return direction.includes('_nulls_');
+}
+
+export function invert(value: -1 | 1): -1 | 1 {
+	return value === -1 ? 1 : -1;
+}
diff --git a/js/src/replica/query-plan/pagination.ts b/js/src/replica/query-plan/pagination.ts
new file mode 100644
index 00000000..f65f1689
--- /dev/null
+++ b/js/src/replica/query-plan/pagination.ts
@@ -0,0 +1,160 @@
+import type {
+	ReplicaIndexCoverage,
+	ReplicaPaginationArtifact,
+	ReplicaPaginationDisposition
+} from '../types.js';
+import { PAGINATION_LOCAL } from './constants.js';
+import type {
+	ReplicaPaginationChange,
+	ReplicaPaginationMaintenanceDecision,
+	ReplicaQueryPlanReason,
+	ReplicaQueryPlanReasonCode
+} from './types.js';
+import { reason } from './util.js';
+
+export function decideReplicaPaginationMaintenance(
+	artifact: ReplicaPaginationArtifact,
+	coverage: ReplicaIndexCoverage,
+	change: ReplicaPaginationChange
+): ReplicaPaginationMaintenanceDecision {
+	const invalidPolicy = validatePaginationPolicies(artifact);
+	if (invalidPolicy !== undefined) return paginationRevalidate(invalidPolicy);
+	if (coverage.kind === 'unknown') {
+		return paginationRevalidate(
+			reason(
+				'unknown_coverage',
+				['pagination', 'coverage'],
+				'unknown index coverage cannot be maintained locally'
+			)
+		);
+	}
+	if (coverage.kind !== artifact.kind) {
+		return paginationRevalidate(
+			reason(
+				'coverage_mismatch',
+				['pagination', 'coverage'],
+				`artifact coverage ${artifact.kind} does not match index coverage ${coverage.kind}`
+			)
+		);
+	}
+	if (artifact.kind === 'cursor') {
+		return paginationRevalidate(
+			reason(
+				'cursor_not_certified',
+				['pagination', 'kind'],
+				'cursor locality requires a versioned compiler proof IR'
+			)
+		);
+	}
+
+	const policy = policyForChange(artifact, change);
+	if (policy === 'local') {
+		if (
+			artifact.kind !== 'offset' ||
+			change.kind === 'stable_update'
+		) {
+			return PAGINATION_LOCAL;
+		}
+		if (
+			coverage.kind === 'offset' &&
+			coverage.offset === 0 &&
+			coverage.limit !== undefined &&
+			coverage.returned !== undefined &&
+			coverage.returned < coverage.limit
+		) {
+			// A non-full first page proves that the server returned the complete
+			// ordered set. The index runtime can therefore apply all optimistic
+			// membership/order changes and truncate back to the declared limit.
+			return PAGINATION_LOCAL;
+		}
+	}
+	const [code, message]: readonly [ReplicaQueryPlanReasonCode, string] =
+		change.kind === 'insert'
+			? [
+					'insert_changes_offset_window',
+					'an insert is local only for a proven non-full first offset page'
+				]
+			: change.kind === 'delete'
+				? [
+						'delete_changes_offset_window',
+						'a delete is local only for a proven non-full first offset page'
+					]
+				: change.kind === 'reorder'
+					? [
+							'reorder_changes_offset_window',
+							'a reorder is local only for a proven non-full first offset page'
+						]
+					: [
+							'invalid_pagination_policy',
+							'the artifact requires stable updates to revalidate'
+						];
+	return paginationRevalidate(reason(code, ['pagination', change.kind], message));
+}
+
+export function paginationRevalidate(
+	reasonValue: ReplicaQueryPlanReason
+): ReplicaPaginationMaintenanceDecision {
+	return Object.freeze({
+		decision: 'revalidate' as const,
+		reason: reasonValue
+	});
+}
+
+export function validatePaginationPolicies(
+	artifact: ReplicaPaginationArtifact
+): ReplicaQueryPlanReason | undefined {
+	if (
+		artifact.kind !== 'complete' &&
+		artifact.kind !== 'offset' &&
+		artifact.kind !== 'cursor'
+	) {
+		return reason(
+			'invalid_pagination_policy',
+			['pagination', 'kind'],
+			'pagination kind must be complete, offset, or cursor'
+		);
+	}
+	const values: readonly (readonly [
+		keyof Pick<
+			ReplicaPaginationArtifact,
+			'insert' | 'delete' | 'reorder' | 'stableUpdate'
+		>,
+		ReplicaPaginationDisposition
+	])[] = [
+		['insert', artifact.insert],
+		['delete', artifact.delete],
+		['reorder', artifact.reorder],
+		['stableUpdate', artifact.stableUpdate]
+	];
+	for (const [field, value] of values) {
+		if (value !== 'local' && value !== 'revalidate') {
+			return reason(
+				'invalid_pagination_policy',
+				['pagination', field],
+				`pagination policy ${field} must be local or revalidate`
+			);
+		}
+	}
+	const exact =
+		artifact.kind === 'complete'
+			? values.every(([, value]) => value === 'local')
+			: artifact.kind === 'offset'
+				? artifact.stableUpdate === 'local'
+				: true;
+	return exact
+		? undefined
+		: reason(
+				'invalid_pagination_policy',
+				['pagination'],
+				`${artifact.kind} pagination policies do not match the conservative compiler contract`
+			);
+}
+
+export function policyForChange(
+	artifact: ReplicaPaginationArtifact,
+	change: ReplicaPaginationChange
+): ReplicaPaginationDisposition {
+	return change.kind === 'stable_update'
+		? artifact.stableUpdate
+		: artifact[change.kind];
+}
diff --git a/js/src/replica/query-plan/resolve.ts b/js/src/replica/query-plan/resolve.ts
new file mode 100644
index 00000000..4dd4dadd
--- /dev/null
+++ b/js/src/replica/query-plan/resolve.ts
@@ -0,0 +1,265 @@
+import type { GraphqlVariables } from '../../types.js';
+import type { DistributedTrustedPreset } from '../../protocol.js';
+import type {
+	ReplicaArgumentValue,
+	ReplicaFilterFieldArtifact,
+	ReplicaFilterOperand,
+	ReplicaSurfaceTrustedPresetDescriptor,
+	ReplicaValue
+} from '../types.js';
+import { resolveReplicaArgumentValue } from '../identity.js';
+import type {
+	ReplicaFilterEvaluationOptions,
+	ReplicaQueryPlanPath,
+	ReplicaQueryPlanReason,
+	ResolvedInput,
+	ResolvedOperand
+} from './types.js';
+import {
+	isFiniteNumber,
+	isName,
+	isRecord,
+	isReplicaValue,
+	reason
+} from './util.js';
+
+export function resolveInput(
+	input: ReplicaArgumentValue | undefined,
+	variables: GraphqlVariables,
+	path: ReplicaQueryPlanPath
+): ResolvedInput {
+	if (input === undefined) return { kind: 'omitted' };
+	try {
+		const value = resolveReplicaArgumentValue(input, variables);
+		return value === undefined
+			? { kind: 'omitted' }
+			: { kind: 'value', value };
+	} catch (error) {
+		return {
+			kind: 'unknown',
+			reason: reason(
+				'invalid_argument_value',
+				path,
+				error instanceof Error
+					? error.message
+					: 'plan input could not be resolved'
+			)
+		};
+	}
+}
+
+export function resolveOperand(
+	operand: ReplicaFilterOperand,
+	field: ReplicaFilterFieldArtifact,
+	options: ReplicaFilterEvaluationOptions,
+	path: ReplicaQueryPlanPath
+): ResolvedOperand {
+	if (operand.kind === 'claim') {
+		return resolveTrustedPresetOperand(
+			operand.value.header,
+			field,
+			options,
+			path
+		);
+	}
+	if (operand.kind !== 'lit' || !isRecord(operand.value)) {
+		return {
+			kind: 'unknown',
+			reason: reason('invalid_artifact', path, 'row-policy operand is malformed')
+		};
+	}
+	const literal = operand.value;
+	if (literal.kind === 'null') {
+		return {
+			kind: 'value',
+			value: null,
+			literalKind: literal.kind,
+			source: 'literal'
+		};
+	}
+	if (
+		literal.kind === 'string' &&
+		typeof literal.value === 'string'
+	) {
+		return {
+			kind: 'value',
+			value: literal.value,
+			literalKind: literal.kind,
+			source: 'literal'
+		};
+	}
+	if (literal.kind === 'bool' && typeof literal.value === 'boolean') {
+		return {
+			kind: 'value',
+			value: literal.value,
+			literalKind: literal.kind,
+			source: 'literal'
+		};
+	}
+	if (
+		(literal.kind === 'i64' && Number.isSafeInteger(literal.value)) ||
+		(literal.kind === 'f64' && isFiniteNumber(literal.value))
+	) {
+		return {
+			kind: 'value',
+			value: literal.value,
+			literalKind: literal.kind,
+			source: 'literal'
+		};
+	}
+	if (literal.kind === 'json' && isReplicaValue(literal.value)) {
+		return {
+			kind: 'value',
+			value: literal.value,
+			literalKind: literal.kind,
+			source: 'literal'
+		};
+	}
+	return {
+		kind: 'unknown',
+		reason: reason(
+			'invalid_artifact',
+			path,
+			'row-policy literal is not a portable JSON value'
+		)
+	};
+}
+
+export function resolveTrustedPresetOperand(
+	name: string,
+	field: ReplicaFilterFieldArtifact,
+	options: ReplicaFilterEvaluationOptions,
+	path: ReplicaQueryPlanPath
+): ResolvedOperand {
+	const inventory = options.trustedPresets;
+	if (inventory === undefined) {
+		return {
+			kind: 'unknown',
+			reason: reason(
+				'claim_operand',
+				path,
+				`claim ${name} has no authoritative scope-bound preset inventory`
+			)
+		};
+	}
+	const descriptors = new Map<string, ReplicaSurfaceTrustedPresetDescriptor>();
+	for (const [index, descriptor] of inventory.descriptors.entries()) {
+		if (
+			typeof descriptor?.name !== 'string' ||
+			descriptor.name.length === 0 ||
+			typeof descriptor.codec !== 'string' ||
+			descriptors.has(descriptor.name)
+		) {
+			return {
+				kind: 'unknown',
+				reason: reason(
+					'claim_inventory',
+					[...path, 'descriptors', index],
+					'trusted preset descriptor inventory is malformed or duplicated'
+				)
+			};
+		}
+		descriptors.set(descriptor.name, descriptor);
+	}
+	const values = new Map<string, DistributedTrustedPreset>();
+	for (const [index, preset] of inventory.values.entries()) {
+		if (
+			typeof preset?.name !== 'string' ||
+			preset.name.length === 0 ||
+			typeof preset.codec !== 'string' ||
+			values.has(preset.name)
+		) {
+			return {
+				kind: 'unknown',
+				reason: reason(
+					'claim_inventory',
+					[...path, 'values', index],
+					'trusted preset value inventory is malformed or duplicated'
+				)
+			};
+		}
+		values.set(preset.name, preset);
+	}
+	if (
+		descriptors.size !== values.size ||
+		[...descriptors].some(
+			([presetName, descriptor]) =>
+				values.get(presetName)?.codec !== descriptor.codec
+		)
+	) {
+		return {
+			kind: 'unknown',
+			reason: reason(
+				'claim_inventory',
+				path,
+				'trusted preset descriptors and scope-bound values do not form an exact union'
+			)
+		};
+	}
+	const descriptor = descriptors.get(name);
+	const preset = values.get(name);
+	if (descriptor === undefined || preset === undefined) {
+		return {
+			kind: 'unknown',
+			reason: reason(
+				'claim_operand',
+				path,
+				`claim ${name} is absent from the selected client surface`
+			)
+		};
+	}
+	if (descriptor.codec !== field.codec) {
+		return {
+			kind: 'unknown',
+			reason: reason(
+				'claim_operand',
+				path,
+				`claim ${name} codec ${descriptor.codec} cannot target ${field.field}:${field.codec}`
+			)
+		};
+	}
+	if (!isReplicaValue(preset.value)) {
+		return {
+			kind: 'unknown',
+			reason: reason(
+				'claim_inventory',
+				path,
+				`claim ${name} is not a portable replica value`
+			)
+		};
+	}
+	return {
+		kind: 'value',
+		value: preset.value,
+		source: 'trusted_preset'
+	};
+}
+
+export function recordField(
+	record: Readonly<Record<string, ReplicaValue>>,
+	field: string,
+	path: ReplicaQueryPlanPath
+):
+	| { readonly kind: 'value'; readonly value: ReplicaValue }
+	| { readonly kind: 'unknown'; readonly reason: ReplicaQueryPlanReason } {
+	if (!Object.prototype.hasOwnProperty.call(record, field)) {
+		return {
+			kind: 'unknown',
+			reason: reason(
+				'missing_field',
+				path,
+				`record does not contain canonical field ${field}`
+			)
+		};
+	}
+	return { kind: 'value', value: record[field]! };
+}
+
+export function uniqueStringList(value: unknown): readonly string[] | undefined {
+	if (!Array.isArray(value) || value.some((entry) => !isName(entry))) {
+		return undefined;
+	}
+	const values = value as string[];
+	if (new Set(values).size !== values.length) return undefined;
+	return Object.freeze([...values]);
+}
diff --git a/js/src/replica/query-plan/types.ts b/js/src/replica/query-plan/types.ts
new file mode 100644
index 00000000..a0f74b69
--- /dev/null
+++ b/js/src/replica/query-plan/types.ts
@@ -0,0 +1,137 @@
+
+import type { DistributedTrustedPreset } from '../../protocol.js';
+import type {
+	ReplicaFilterExpression,
+	ReplicaFilterFieldArtifact,
+	ReplicaFilterLiteral,
+	ReplicaRelationshipArtifact,
+	ReplicaSurfaceTrustedPresetDescriptor,
+	ReplicaValue
+} from '../types.js';
+
+export type ReplicaQueryPlanPath = readonly (string | number)[];
+
+export type ReplicaQueryPlanReasonCode =
+	| 'ambiguous_order_entry'
+	| 'claim_operand'
+	| 'claim_inventory'
+	| 'collation_not_portable'
+	| 'coverage_mismatch'
+	| 'cursor_not_certified'
+	| 'delete_changes_offset_window'
+	| 'implicit_null_order'
+	| 'invalid_argument_value'
+	| 'insert_changes_offset_window'
+	| 'invalid_artifact'
+	| 'invalid_filter_input'
+	| 'invalid_filter_value'
+	| 'invalid_order_direction'
+	| 'invalid_order_input'
+	| 'invalid_order_value'
+	| 'invalid_pagination_policy'
+	| 'missing_field'
+	| 'relationship_resolver_required'
+	| 'reorder_changes_offset_window'
+	| 'server_only_policy'
+	| 'sql_null'
+	| 'unknown_coverage'
+	| 'unknown_field'
+	| 'unknown_relationship'
+	| 'unsupported_codec'
+	| 'unsupported_operator';
+
+export type ReplicaQueryPlanReason = {
+	readonly code: ReplicaQueryPlanReasonCode;
+	readonly path: ReplicaQueryPlanPath;
+	readonly message: string;
+};
+
+export type ReplicaFilterEvaluation =
+	| { readonly result: 'match' | 'no_match' }
+	| {
+			readonly result: 'unknown';
+			readonly reason: ReplicaQueryPlanReason;
+	  };
+
+export type ReplicaRelationshipFilterRequest =
+	| {
+			readonly source: 'caller';
+			readonly relationship: ReplicaRelationshipArtifact;
+			readonly predicate: ReplicaValue;
+			readonly record: Readonly<Record<string, ReplicaValue>>;
+			readonly path: ReplicaQueryPlanPath;
+	  }
+	| {
+			readonly source: 'row_policy';
+			readonly relationship: ReplicaRelationshipArtifact;
+			readonly predicate: ReplicaFilterExpression;
+			readonly record: Readonly<Record<string, ReplicaValue>>;
+			readonly path: ReplicaQueryPlanPath;
+	  };
+
+export type ReplicaFilterEvaluationOptions = {
+	/**
+	 * Resolves the server's EXISTS semantics for a relationship predicate.
+	 * The resolver is responsible for the target model's row policy as well as
+	 * the supplied predicate; omitting it deliberately produces `unknown`.
+	 */
+	readonly resolveRelationship?: (
+		request: ReplicaRelationshipFilterRequest
+	) => ReplicaFilterEvaluation;
+	/**
+	 * Static compiler-owned descriptor union paired with the current
+	 * server-derived, cache-scope-bound values. The evaluator never reads
+	 * ambient token claims or caller headers.
+	 */
+	readonly trustedPresets?: {
+		readonly descriptors: readonly ReplicaSurfaceTrustedPresetDescriptor[];
+		readonly values: readonly DistributedTrustedPreset[];
+	};
+};
+
+export type ReplicaOrderComparison =
+	| { readonly result: 'less' | 'equal' | 'greater' }
+	| {
+			readonly result: 'unknown';
+			readonly reason: ReplicaQueryPlanReason;
+	  };
+
+export type ReplicaPaginationChange =
+	| { readonly kind: 'insert' }
+	| { readonly kind: 'delete' }
+	| { readonly kind: 'reorder' }
+	| { readonly kind: 'stable_update' };
+
+export type ReplicaPaginationMaintenanceDecision =
+	| { readonly decision: 'local' }
+	| {
+			readonly decision: 'revalidate';
+			readonly reason: ReplicaQueryPlanReason;
+	  };
+
+export type FilterCatalog = {
+	readonly fields: ReadonlyMap<string, ReplicaFilterFieldArtifact>;
+	readonly relationships: ReadonlyMap<string, ReplicaRelationshipArtifact>;
+};
+
+export type ResolvedInput =
+	| { readonly kind: 'omitted' }
+	| { readonly kind: 'value'; readonly value: ReplicaValue }
+	| { readonly kind: 'unknown'; readonly reason: ReplicaQueryPlanReason };
+
+export type ResolvedOperand =
+	| {
+			readonly kind: 'value';
+			readonly value: ReplicaValue;
+			readonly literalKind?: ReplicaFilterLiteral['kind'];
+			readonly source: 'literal' | 'trusted_preset';
+	  }
+	| { readonly kind: 'unknown'; readonly reason: ReplicaQueryPlanReason };
+
+export type OrderDirection =
+	| 'asc'
+	| 'asc_nulls_first'
+	| 'asc_nulls_last'
+	| 'desc'
+	| 'desc_nulls_first'
+	| 'desc_nulls_last';
diff --git a/js/src/replica/query-plan/util.ts b/js/src/replica/query-plan/util.ts
new file mode 100644
index 00000000..99cb125f
--- /dev/null
+++ b/js/src/replica/query-plan/util.ts
@@ -0,0 +1,89 @@
+import type { ReplicaValue } from '../types.js';
+import type {
+	ReplicaQueryPlanPath,
+	ReplicaQueryPlanReason,
+	ReplicaQueryPlanReasonCode
+} from './types.js';
+
+export function reason(
+	code: ReplicaQueryPlanReasonCode,
+	path: ReplicaQueryPlanPath,
+	message: string
+): ReplicaQueryPlanReason {
+	return Object.freeze({
+		code,
+		path: Object.freeze([...path]),
+		message
+	});
+}
+
+export function isScalarCodecPair(scalar: unknown, codec: unknown): boolean {
+	if (typeof scalar !== 'string' || typeof codec !== 'string') return false;
+	return (
+		`${scalar}:${codec}` === 'ID:string' ||
+		`${scalar}:${codec}` === 'String:string' ||
+		`${scalar}:${codec}` === 'Bytea:base64' ||
+		`${scalar}:${codec}` ===
+			'Timestamptz:string_unvalidated_timestamp' ||
+		`${scalar}:${codec}` === 'Boolean:boolean' ||
+		`${scalar}:${codec}` === 'Int:int32' ||
+		`${scalar}:${codec}` === 'Float:float64' ||
+		`${scalar}:${codec}` ===
+			'BigInt:json_number_precision_limited' ||
+		`${scalar}:${codec}` === 'JSON:json'
+	);
+}
+
+export function isPortableNumericCodec(codec: string): boolean {
+	return (
+		codec === 'int32' ||
+		codec === 'float64' ||
+		codec === 'json_number_precision_limited'
+	);
+}
+
+export function isSafeIntegerNumber(value: ReplicaValue): value is number {
+	return typeof value === 'number' && Number.isSafeInteger(value);
+}
+
+export function isInt32(value: ReplicaValue): value is number {
+	return (
+		Number.isInteger(value) &&
+		(value as number) >= -2_147_483_648 &&
+		(value as number) <= 2_147_483_647
+	);
+}
+
+export function isFiniteNumber(value: unknown): value is number {
+	return typeof value === 'number' && Number.isFinite(value);
+}
+
+export function isName(value: unknown): value is string {
+	return typeof value === 'string' && value.length > 0;
+}
+
+export function isRecord(value: ReplicaValue | unknown): value is {
+	readonly [key: string]: ReplicaValue;
+} {
+	return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function isReplicaValue(value: unknown, ancestors = new Set<object>()): value is ReplicaValue {
+	if (
+		value === null ||
+		typeof value === 'string' ||
+		typeof value === 'boolean' ||
+		isFiniteNumber(value)
+	) {
+		return true;
+	}
+	if (typeof value !== 'object' || ancestors.has(value)) return false;
+	ancestors.add(value);
+	const valid = Array.isArray(value)
+		? value.every((entry) => isReplicaValue(entry, ancestors))
+		: (Object.getPrototypeOf(value) === Object.prototype ||
+				Object.getPrototypeOf(value) === null) &&
+			Object.values(value).every((entry) => isReplicaValue(entry, ancestors));
+	ancestors.delete(value);
+	return valid;
+}
diff --git a/js/src/replica/revalidation.ts b/js/src/replica/revalidation.ts
new file mode 100644
index 00000000..c1e6dce7
--- /dev/null
+++ b/js/src/replica/revalidation.ts
@@ -0,0 +1,144 @@
+import type { GraphqlVariables } from '../types.js';
+import type {
+	ReplicaObjectSelection,
+	ReplicaOperationArtifact,
+	ReplicaRevalidationPlan
+} from './types.js';
+
+type RevalidationInventory = {
+	readonly dependencies: ReadonlySet<string>;
+	readonly models: ReadonlySet<string>;
+	readonly relationships: ReadonlySet<string>;
+	readonly global: boolean;
+};
+
+/**
+ * Compile one validated command inventory into a reusable operation matcher.
+ *
+ * Adapters only forward generated plans; the replica owns knowledge of active
+ * operation artifacts and therefore remains the framework-neutral coordinator.
+ */
+export function createReplicaRevalidationMatcher(
+	plan: ReplicaRevalidationPlan
+): (
+	artifact: ReplicaOperationArtifact<unknown, GraphqlVariables>
+) => boolean {
+	const inventory = revalidationInventory(plan);
+	return (artifact) =>
+		inventory.global ||
+		artifact.roots.some(
+			(root) =>
+				intersects(root.dependencies, inventory.dependencies) ||
+				selectionMatches(root.selection, undefined, inventory)
+		);
+}
+
+function selectionMatches(
+	selection: ReplicaObjectSelection,
+	parentModel: string | undefined,
+	inventory: RevalidationInventory
+): boolean {
+	const model =
+		selection.storage.kind === 'normalized'
+			? selection.storage.model
+			: parentModel;
+	if (
+		selection.storage.kind === 'normalized' &&
+		inventory.models.has(selection.storage.model)
+	) {
+		return true;
+	}
+	for (const member of selection.members) {
+		if (member.kind !== 'branch') continue;
+		if (intersects(member.dependencies, inventory.dependencies)) return true;
+		if (
+			member.semantic === 'relationship' &&
+			model !== undefined &&
+			inventory.relationships.has(
+				relationshipKey(model, member.field, member.relationship.targetModel)
+			)
+		) {
+			return true;
+		}
+		if (selectionMatches(member.selection, model, inventory)) return true;
+	}
+	return false;
+}
+
+function revalidationInventory(
+	value: ReplicaRevalidationPlan
+): RevalidationInventory {
+	if (
+		value === null ||
+		typeof value !== 'object' ||
+		!Array.isArray(value.dependencies) ||
+		!Array.isArray(value.models) ||
+		!Array.isArray(value.relationships)
+	) {
+		invalidPlan();
+	}
+	const dependencies = stringSet(value.dependencies, 'dependencies');
+	const models = stringSet(value.models, 'models');
+	const relationships = new Set<string>();
+	for (const [index, relationship] of value.relationships.entries()) {
+		if (
+			relationship === null ||
+			typeof relationship !== 'object' ||
+			!validName(relationship.sourceModel) ||
+			!validName(relationship.field) ||
+			!validName(relationship.targetModel)
+		) {
+			invalidPlan(`relationships[${index}]`);
+		}
+		relationships.add(
+			relationshipKey(
+				relationship.sourceModel,
+				relationship.field,
+				relationship.targetModel
+			)
+		);
+	}
+	return Object.freeze({
+		dependencies,
+		models,
+		relationships,
+		global:
+			dependencies.size === 0 &&
+			models.size === 0 &&
+			relationships.size === 0
+	});
+}
+
+function stringSet(values: readonly string[], path: string): ReadonlySet<string> {
+	const result = new Set<string>();
+	for (const [index, value] of values.entries()) {
+		if (!validName(value)) invalidPlan(`${path}[${index}]`);
+		result.add(value);
+	}
+	return result;
+}
+
+function validName(value: unknown): value is string {
+	return typeof value === 'string' && value.length > 0;
+}
+
+function intersects(
+	left: readonly string[],
+	right: ReadonlySet<string>
+): boolean {
+	return left.some((value) => right.has(value));
+}
+
+function relationshipKey(
+	sourceModel: string,
+	field: string,
+	targetModel: string
+): string {
+	return JSON.stringify([sourceModel, field, targetModel]);
+}
+
+function invalidPlan(path?: string): never {
+	throw new TypeError(
+		`replica revalidation plan${path === undefined ? '' : ` ${path}`} is invalid`
+	);
+}
diff --git a/js/src/replica/selection.ts b/js/src/replica/selection.ts
new file mode 100644
index 00000000..0936e5d0
--- /dev/null
+++ b/js/src/replica/selection.ts
@@ -0,0 +1,185 @@
+import type {
+	ReplicaObjectBranch,
+	ReplicaObjectSelection,
+	ReplicaRootSelection,
+	ReplicaScalarSelection,
+	ReplicaSelectionStorage
+} from './types.js';
+
+import { assertName } from '../lib/assert-name.js';
+
+export type RuntimeScalarSelection = ReplicaScalarSelection & {
+	readonly nullable: boolean;
+};
+
+export type RuntimeObjectSelection = {
+	readonly typename: string;
+	readonly storage: ReplicaSelectionStorage;
+	readonly members: readonly RuntimeObjectMember[];
+};
+
+export type RuntimeObjectBranch = Omit<ReplicaObjectBranch, 'selection'> & {
+	readonly selection: RuntimeObjectSelection;
+	readonly expose?: boolean;
+};
+
+export type RuntimeObjectMember = RuntimeScalarSelection | RuntimeObjectBranch;
+
+export type RuntimeRootSelection = Omit<ReplicaRootSelection, 'nullable' | 'selection'> & {
+	readonly nullable: boolean;
+	readonly selection: RuntimeObjectSelection;
+};
+
+export function runtimeRoot(selection: ReplicaRootSelection): RuntimeRootSelection {
+	assertBranchShape(selection, 'root');
+	if (typeof selection.nullable !== 'boolean') {
+		throw new TypeError(
+			`root ${selection.responseKey} must declare exact nullability`
+		);
+	}
+	return Object.freeze({
+		...selection,
+		nullable: selection.nullable,
+		selection: runtimeObject(selection.selection)
+	});
+}
+
+export function embeddedRecordKey(
+	artifactId: string,
+	enclosingIndexKey: string,
+	ordinal: number | undefined
+): string {
+	const slot = ordinal === undefined ? 'one' : `ordinal:${ordinal}`;
+	return `embedded:${encodeURIComponent(artifactId)}:${encodeURIComponent(
+		enclosingIndexKey
+	)}:${slot}`;
+}
+
+function runtimeObject(
+	selection: ReplicaObjectSelection
+): RuntimeObjectSelection {
+	assertName(selection.typename, 'selection typename');
+	assertStorage(selection.storage);
+	if (!Array.isArray(selection.members)) {
+		throw new TypeError(`selection ${selection.typename} members must be an array`);
+	}
+	return Object.freeze({
+		typename: selection.typename,
+		storage: freezeStorage(selection.storage),
+		members: Object.freeze(
+			selection.members.map((member) => {
+				if (member.kind === 'scalar') return runtimeScalar(member);
+				if (member.kind !== 'branch') {
+					throw new TypeError(
+						`selection ${selection.typename} contains an unsupported member`
+					);
+				}
+				assertBranchShape(member, `branch ${member.responseKey}`);
+				if (
+					member.semantic !== 'relationship' &&
+					member.semantic !== 'aggregate' &&
+					member.semantic !== 'aggregate_fields' &&
+					member.semantic !== 'aggregate_nodes'
+				) {
+					throw new TypeError(
+						`branch ${member.responseKey} has unsupported semantic ${String(
+							member.semantic
+						)}`
+					);
+				}
+				if (typeof member.nullable !== 'boolean') {
+					throw new TypeError(
+						`branch ${member.responseKey} must declare exact nullability`
+					);
+				}
+				return Object.freeze({
+					...member,
+					dependencies: freezeDependencies(
+						member.dependencies,
+						member.responseKey
+					),
+					selection: runtimeObject(member.selection)
+				});
+			})
+		)
+	});
+}
+
+function runtimeScalar(selection: ReplicaScalarSelection): RuntimeScalarSelection {
+	if (selection.kind !== 'scalar') {
+		throw new TypeError('object scalar member must have kind scalar');
+	}
+	assertName(selection.responseKey, 'scalar response key');
+	assertName(selection.field, `scalar ${selection.responseKey} field`);
+	assertName(selection.codec, `scalar ${selection.responseKey} codec`);
+	if (typeof selection.nullable !== 'boolean') {
+		throw new TypeError(
+			`scalar ${selection.responseKey} must declare exact nullability`
+		);
+	}
+	return Object.freeze({
+		...selection,
+		nullable: selection.nullable
+	});
+}
+
+function assertBranchShape(
+	selection: Pick<
+		ReplicaRootSelection | ReplicaObjectBranch,
+		'responseKey' | 'field' | 'cardinality' | 'dependencies'
+	>,
+	description: string
+): void {
+	assertName(selection.responseKey, `${description} response key`);
+	assertName(selection.field, `${description} field`);
+	if (selection.cardinality !== 'one' && selection.cardinality !== 'many') {
+		throw new TypeError(`${description} has unsupported cardinality`);
+	}
+	freezeDependencies(selection.dependencies, selection.responseKey);
+}
+
+function freezeDependencies(
+	dependencies: readonly string[],
+	responseKey: string
+): readonly string[] {
+	if (!Array.isArray(dependencies)) {
+		throw new TypeError(`branch ${responseKey} dependencies must be an array`);
+	}
+	for (const dependency of dependencies) {
+		assertName(dependency, `branch ${responseKey} dependency`);
+	}
+	return Object.freeze([...dependencies]);
+}
+
+function assertStorage(storage: ReplicaSelectionStorage): void {
+	if (storage.kind === 'embedded') return;
+	if (storage.kind !== 'normalized') {
+		throw new TypeError('selection has unsupported storage');
+	}
+	assertName(storage.model, 'normalized model');
+	if (!Array.isArray(storage.identityFields) || storage.identityFields.length === 0) {
+		throw new TypeError(
+			`normalized model ${storage.model} must declare at least one identity field`
+		);
+	}
+	const unique = new Set<string>();
+	for (const field of storage.identityFields) {
+		assertName(field, `normalized model ${storage.model} identity field`);
+		if (unique.has(field)) {
+			throw new TypeError(
+				`normalized model ${storage.model} contains duplicate identity field ${field}`
+			);
+		}
+		unique.add(field);
+	}
+}
+
+function freezeStorage(storage: ReplicaSelectionStorage): ReplicaSelectionStorage {
+	if (storage.kind === 'embedded') return Object.freeze({ kind: 'embedded' as const });
+	return Object.freeze({
+		kind: 'normalized' as const,
+		model: storage.model,
+		identityFields: Object.freeze([...storage.identityFields])
+	});
+}
+
diff --git a/js/src/replica/types.ts b/js/src/replica/types.ts
new file mode 100644
index 00000000..ffccfe77
--- /dev/null
+++ b/js/src/replica/types.ts
@@ -0,0 +1,870 @@
+import type { GqlError, GraphqlVariables } from '../types.js';
+import type {
+	DistributedCommandMetadata,
+	DistributedLiveCursor,
+	DistributedTrustedPresetCodec,
+	GraphqlResponseExtensions
+} from '../protocol.js';
+import type { ReplicaDiagnosticsSink } from './diagnostics.js';
+
+export type ReplicaRevision = number | string | bigint;
+export type ReplicaValue =
+	| null
+	| boolean
+	| number
+	| string
+	| readonly ReplicaValue[]
+	| { readonly [key: string]: ReplicaValue };
+
+export type ReplicaIndexRecordChange =
+	| {
+			readonly kind: 'upsert';
+			readonly model: string;
+			readonly key: string;
+			readonly fields: Readonly<Record<string, ReplicaValue>>;
+			readonly dependencies?: readonly string[];
+	  }
+	| {
+			readonly kind: 'delete';
+			readonly model: string;
+			readonly key: string;
+			readonly dependencies?: readonly string[];
+	  };
+
+export type ReplicaIndexRelationshipChange = {
+	readonly kind: 'link' | 'unlink';
+	readonly sourceModel: string;
+	readonly field: string;
+	readonly targetModel: string;
+	readonly sourceKey: string;
+	readonly targetKey: string;
+	readonly dependencies: readonly string[];
+};
+
+export type ReplicaIndexDependencyChange = {
+	readonly kind: 'invalidate';
+	readonly dependencies: readonly string[];
+};
+
+/** Compiler/runtime semantic evidence carried by one optimistic layer. */
+export type ReplicaIndexSemanticChange =
+	| ReplicaIndexRecordChange
+	| ReplicaIndexRelationshipChange
+	| ReplicaIndexDependencyChange;
+
+export type ReplicaIndexCoverage =
+	| { readonly kind: 'complete' }
+	| { readonly kind: 'unknown' }
+	| {
+			readonly kind: 'offset';
+			readonly offset: number;
+			readonly limit?: number;
+			readonly returned?: number;
+			readonly hasNext?: boolean;
+	  }
+	| {
+			readonly kind: 'cursor';
+			readonly after?: ReplicaValue;
+			readonly before?: ReplicaValue;
+			readonly first?: number;
+			readonly last?: number;
+			readonly start?: ReplicaValue;
+			readonly end?: ReplicaValue;
+			readonly hasNext?: boolean;
+			readonly hasPrevious?: boolean;
+	  };
+
+/** Minimal model identity emitted by a generated operation artifact. */
+export type ReplicaModelArtifact = {
+	readonly id: string;
+	readonly identityFields: readonly string[];
+};
+
+export type ReplicaLiteralValue = {
+	readonly kind: 'literal';
+	readonly value: ReplicaValue;
+};
+
+export type ReplicaVariableValue = {
+	readonly kind: 'variable';
+	readonly name: string;
+};
+
+export type ReplicaListValue = {
+	readonly kind: 'list';
+	readonly items: readonly ReplicaArgumentValue[];
+};
+
+export type ReplicaObjectValue = {
+	readonly kind: 'object';
+	readonly fields: Readonly<Record<string, ReplicaArgumentValue>>;
+};
+
+export type ReplicaArgumentValue =
+	| ReplicaLiteralValue
+	| ReplicaVariableValue
+	| ReplicaListValue
+	| ReplicaObjectValue;
+export type ReplicaArgumentsArtifact = Readonly<Record<string, ReplicaArgumentValue>>;
+
+export type ReplicaVariableScalarInputRef = {
+	readonly kind: 'scalar';
+	readonly scalar: string;
+	readonly codec: string;
+	readonly nullable: boolean;
+};
+
+export type ReplicaVariableEnumInputRef = {
+	readonly kind: 'enum';
+	readonly name: string;
+	readonly values: readonly string[];
+	readonly nullable: boolean;
+};
+
+export type ReplicaVariableNamedInputRef = {
+	readonly kind: 'input';
+	readonly name: string;
+	readonly nullable: boolean;
+	/** Required for filter inputs; omitted for other named inputs. */
+	readonly filterBaseDepth?: number;
+};
+
+export type ReplicaVariableListInputRef = {
+	readonly kind: 'list';
+	readonly nullable: boolean;
+	/** Most restrictive list-width cap across every use of this variable. */
+	readonly maxItems?: number;
+	readonly item: ReplicaVariableInputRef;
+};
+
+/** Compiler-owned GraphQL input coercion contract for one operation variable. */
+export type ReplicaVariableInputRef =
+	| ReplicaVariableScalarInputRef
+	| ReplicaVariableEnumInputRef
+	| ReplicaVariableNamedInputRef
+	| ReplicaVariableListInputRef;
+
+export type ReplicaVariableFilterInputField = {
+	readonly field: string;
+	readonly scalar: string;
+	readonly codec: string;
+	/** Record-column nullability; comparison operands follow the GraphQL input grammar. */
+	readonly nullable: boolean;
+	readonly operators: readonly ReplicaFilterOperator[];
+};
+
+export type ReplicaVariableFilterInputTarget =
+	| { readonly kind: 'input'; readonly name: string }
+	| { readonly kind: 'opaque' };
+
+export type ReplicaVariableFilterInputRelationship = {
+	readonly field: string;
+	readonly target: ReplicaVariableFilterInputTarget;
+};
+
+export type ReplicaVariableFilterInputDefinition = {
+	readonly kind: 'filter';
+	readonly model: string;
+	readonly fields: readonly ReplicaVariableFilterInputField[];
+	readonly relationships: readonly ReplicaVariableFilterInputRelationship[];
+};
+
+export type ReplicaVariableOrderInputField = {
+	readonly field: string;
+	readonly scalar: string;
+	readonly codec: string;
+	readonly nullable: boolean;
+};
+
+export type ReplicaVariableOrderInputDefinition = {
+	readonly kind: 'order';
+	readonly model: string;
+	readonly fields: readonly ReplicaVariableOrderInputField[];
+	readonly values: readonly string[];
+};
+
+export type ReplicaVariableInputDefinition =
+	| ReplicaVariableFilterInputDefinition
+	| ReplicaVariableOrderInputDefinition;
+
+export type ReplicaVariableCodecLimits = {
+	readonly maxDepth: number;
+	readonly maxBoolWidth: number;
+	readonly maxInList: number;
+};
+
+/** Exact variable codec emitted beside a generated operation artifact. */
+export type ReplicaVariableCodecArtifact = {
+	readonly version: 1;
+	readonly limits: ReplicaVariableCodecLimits;
+	readonly variables: Readonly<Record<string, ReplicaVariableInputRef>>;
+	readonly inputs: Readonly<Record<string, ReplicaVariableInputDefinition>>;
+};
+
+export type ReplicaFilterOperator =
+	| '_eq'
+	| '_neq'
+	| '_gt'
+	| '_gte'
+	| '_lt'
+	| '_lte'
+	| '_in'
+	| '_nin'
+	| '_is_null'
+	| '_like'
+	| '_ilike'
+	| '_contains'
+	| '_contained_in'
+	| '_has_key';
+
+export type ReplicaFilterFieldArtifact = {
+	readonly field: string;
+	readonly scalar: string;
+	readonly codec: string;
+	readonly nullable: boolean;
+	readonly operators: readonly ReplicaFilterOperator[];
+};
+
+export type ReplicaRelationshipKind =
+	| 'has_many'
+	| 'belongs_to'
+	| 'many_to_many';
+
+export type ReplicaRelationshipKeyMapping =
+	| {
+			readonly kind: 'direct';
+			readonly local: readonly string[];
+			readonly remote: readonly string[];
+	  }
+	| {
+			readonly kind: 'through';
+			readonly local: readonly string[];
+			readonly remote: readonly string[];
+			readonly table: string;
+			readonly sourceForeignKey: string;
+			readonly targetForeignKey: string;
+	  }
+	| {
+			readonly kind: 'through_opaque';
+			readonly local: readonly string[];
+			readonly remote: readonly string[];
+			readonly dependency: string;
+	  }
+	| { readonly kind: 'embedded' };
+
+/**
+ * Compiler-owned relationship facts. Task 8 consumes this descriptor to
+ * resolve predicates and maintain links without rediscovering schema metadata.
+ */
+export type ReplicaRelationshipArtifact = {
+	readonly field: string;
+	readonly targetModel: string;
+	readonly kind: ReplicaRelationshipKind;
+	readonly keyMapping: ReplicaRelationshipKeyMapping;
+	readonly maintenance: 'local' | 'revalidate';
+	readonly dependencies: readonly string[];
+};
+
+export type ReplicaFilterLiteral =
+	| { readonly kind: 'string'; readonly value: string }
+	| { readonly kind: 'i64'; readonly value: number }
+	| { readonly kind: 'f64'; readonly value: number }
+	| { readonly kind: 'bool'; readonly value: boolean }
+	| { readonly kind: 'json'; readonly value: ReplicaValue }
+	| { readonly kind: 'null' };
+
+/** Manifest-v5 row-policy operand, preserved without ambient claim access. */
+export type ReplicaFilterOperand =
+	| { readonly kind: 'lit'; readonly value: ReplicaFilterLiteral }
+	| {
+			readonly kind: 'claim';
+			readonly value: { readonly header: string };
+	  };
+
+/** Manifest-v5 tagged row-policy expression. */
+export type ReplicaFilterExpression =
+	| {
+			readonly kind: 'and' | 'or';
+			readonly value: readonly ReplicaFilterExpression[];
+	  }
+	| { readonly kind: 'not'; readonly value: ReplicaFilterExpression }
+	| {
+			readonly kind: 'cmp';
+			readonly value: {
+				readonly column: string;
+				readonly op:
+					| 'eq'
+					| 'neq'
+					| 'gt'
+					| 'gte'
+					| 'lt'
+					| 'lte'
+					| 'like'
+					| 'ilike'
+					| 'contains'
+					| 'contained_in'
+					| 'has_key';
+				readonly rhs: ReplicaFilterOperand;
+			};
+	  }
+	| {
+			readonly kind: 'in';
+			readonly value: {
+				readonly column: string;
+				readonly values: readonly ReplicaFilterOperand[];
+				readonly negated: boolean;
+			};
+	  }
+	| {
+			readonly kind: 'is_null';
+			readonly value: {
+				readonly column: string;
+				readonly is_null: boolean;
+			};
+	  }
+	| {
+			readonly kind: 'rel';
+			readonly value: {
+				readonly field: string;
+				readonly predicate: ReplicaFilterExpression;
+			};
+	  };
+
+export type ReplicaRowPolicyArtifact =
+	| { readonly kind: 'unrestricted' }
+	| { readonly kind: 'server_only' }
+	| {
+			readonly kind: 'predicate';
+			readonly expression: ReplicaFilterExpression;
+	  };
+
+export type ReplicaFilterArtifact = {
+	/** Exact literal or variable supplying the operation's `where` input. */
+	readonly input?: ReplicaArgumentValue;
+	readonly fields: readonly ReplicaFilterFieldArtifact[];
+	readonly relationships: readonly ReplicaRelationshipArtifact[];
+	readonly rowPolicy: ReplicaRowPolicyArtifact;
+};
+
+export type ReplicaOrderFieldArtifact = {
+	readonly field: string;
+	readonly scalar: string;
+	readonly codec: string;
+	readonly nullable: boolean;
+};
+
+export type ReplicaOrderTieBreakerArtifact = {
+	readonly field: string;
+	readonly scalar: string;
+	readonly codec: string;
+	/** Generated identity fields are always non-null. */
+	readonly nullable: false;
+};
+
+export type ReplicaOrderArtifact = {
+	/** Exact literal or variable supplying the operation's `order_by` input. */
+	readonly input?: ReplicaArgumentValue;
+	readonly fields: readonly ReplicaOrderFieldArtifact[];
+	/** Server-appended primary-key fields, in their exact comparison order. */
+	readonly tieBreakers: readonly ReplicaOrderTieBreakerArtifact[];
+};
+
+export type ReplicaPaginationDisposition = 'local' | 'revalidate';
+
+type ReplicaPaginationPolicies = {
+	readonly insert: ReplicaPaginationDisposition;
+	readonly delete: ReplicaPaginationDisposition;
+	readonly reorder: ReplicaPaginationDisposition;
+	readonly stableUpdate: ReplicaPaginationDisposition;
+};
+
+export type ReplicaPaginationArtifact = ReplicaPaginationPolicies &
+	(
+		| { readonly kind: 'complete' | 'offset' }
+		| {
+				/**
+				 * Cursor locality is unavailable until the compiler emits a
+				 * versioned proof IR understood by the runtime.
+				 */
+				readonly kind: 'cursor';
+		  }
+	);
+
+export type ReplicaCoverageArtifact =
+	| { readonly kind: 'complete' }
+	| {
+			readonly kind: 'offset';
+			readonly offsetArgument?: string;
+			readonly limitArgument?: string;
+			readonly defaultLimit?: number;
+			readonly maxLimit?: number;
+	  }
+	| {
+			readonly kind: 'cursor';
+			readonly afterArgument?: string;
+			readonly beforeArgument?: string;
+			readonly firstArgument?: string;
+			readonly lastArgument?: string;
+	  };
+
+export type ReplicaScalarSelection = {
+	readonly kind: 'scalar';
+	/** GraphQL response key after aliases are applied. */
+	readonly responseKey: string;
+	/** Canonical schema/read-model field name. */
+	readonly field: string;
+	/** Exact scalar codec and nullability emitted by the client compiler. */
+	readonly codec: string;
+	readonly nullable: boolean;
+	/** Wire-only identity fields set this false. */
+	readonly expose?: boolean;
+};
+
+export type ReplicaSelectionStorage =
+	| {
+			readonly kind: 'normalized';
+			readonly model: string;
+			readonly identityFields: readonly string[];
+	  }
+	| { readonly kind: 'embedded' };
+
+export type ReplicaBranchSemantic =
+	| 'relationship'
+	| 'aggregate'
+	| 'aggregate_fields'
+	| 'aggregate_nodes';
+
+/** Recursive compiler-owned object algebra used by manifest v7 artifacts. */
+export type ReplicaObjectSelection = {
+	readonly typename: string;
+	readonly storage: ReplicaSelectionStorage;
+	readonly members: readonly ReplicaObjectMember[];
+};
+
+type ReplicaObjectBranchBase = {
+	readonly kind: 'branch';
+	readonly responseKey: string;
+	readonly field: string;
+	readonly cardinality: 'one' | 'many';
+	readonly nullable: boolean;
+	readonly arguments?: ReplicaArgumentsArtifact;
+	readonly dependencies: readonly string[];
+	readonly coverage?: ReplicaCoverageArtifact;
+	readonly filter?: ReplicaFilterArtifact;
+	readonly order?: ReplicaOrderArtifact;
+	readonly pagination?: ReplicaPaginationArtifact;
+	readonly selection: ReplicaObjectSelection;
+};
+
+export type ReplicaObjectBranch =
+	| (ReplicaObjectBranchBase & {
+			readonly semantic: 'relationship';
+			readonly relationship: ReplicaRelationshipArtifact;
+	  })
+	| (ReplicaObjectBranchBase & {
+			readonly semantic: Exclude<ReplicaBranchSemantic, 'relationship'>;
+			readonly relationship?: never;
+	  });
+
+export type ReplicaObjectMember = ReplicaScalarSelection | ReplicaObjectBranch;
+
+export type ReplicaRootSelection = {
+	readonly responseKey: string;
+	readonly field: string;
+	readonly cardinality: 'one' | 'many';
+	readonly nullable: boolean;
+	readonly arguments?: ReplicaArgumentsArtifact;
+	readonly dependencies: readonly string[];
+	readonly coverage?: ReplicaCoverageArtifact;
+	readonly filter?: ReplicaFilterArtifact;
+	readonly order?: ReplicaOrderArtifact;
+	readonly pagination?: ReplicaPaginationArtifact;
+	readonly selection: ReplicaObjectSelection;
+};
+
+/**
+ * Narrow runtime contract expected from generated code.
+ *
+ * It deliberately does not mirror the Rust client-manifest JSON. The compiler
+ * owns lowering the manifest and GraphQL AST into this executable descriptor.
+ */
+type ReplicaOperationArtifactBase<
+	TData = Record<string, unknown>,
+	TVariables extends GraphqlVariables = GraphqlVariables
+> = {
+	readonly id: string;
+	readonly document: string;
+	/** Normalized compiler-owned provenance for diagnostics and support tooling. */
+	readonly source?: ReplicaOperationSourceLocation;
+	readonly roots: readonly ReplicaRootSelection[];
+	readonly live?: {
+		readonly id: string;
+		readonly document: string;
+	};
+	/** Phantom slots preserve generated result/variables types. */
+	readonly __result?: TData;
+	readonly __variables?: TVariables;
+};
+
+export type ReplicaOperationSourceLocation = {
+	readonly path: string;
+	readonly line: number;
+	readonly column: number;
+};
+
+export type ReplicaOperationProtocol = {
+	readonly version: 1;
+	/** Opaque service schema fingerprint, compared byte-for-byte. */
+	readonly schemaHash: string;
+	readonly surface: ReplicaClientSurface;
+	/** Opaque operation identity, required to match the artifact id exactly. */
+	readonly operation: string;
+	/**
+	 * Exact descriptor union for the selected client surface. Generated
+	 * artifacts repeat this small static contract so every query can validate
+	 * scope-bound preset values without depending on command registration.
+	 */
+	readonly trustedPresets: readonly ReplicaSurfaceTrustedPresetDescriptor[];
+};
+
+export type ReplicaSurfaceTrustedPresetDescriptor = {
+	readonly name: string;
+	readonly codec: DistributedTrustedPresetCodec;
+};
+
+/** Exact static client surface selected at code-generation time. */
+export type ReplicaClientSurface =
+	| {
+			readonly kind: 'role';
+			readonly name: string;
+	  }
+	| {
+			readonly kind: 'application';
+			readonly name: string;
+			readonly roles: readonly string[];
+	  };
+
+/** Compiler-owned causal artifact. Protocol and variable identity are inseparable. */
+export type ReplicaProtocolOperationArtifact<
+	TData = Record<string, unknown>,
+	TVariables extends GraphqlVariables = GraphqlVariables
+> = ReplicaOperationArtifactBase<TData, TVariables> & {
+	readonly protocol: ReplicaOperationProtocol;
+	/** Exact compiler-owned GraphQL variable coercion and identity contract. */
+	readonly variableCodec: ReplicaVariableCodecArtifact;
+};
+
+export type ReplicaOperationArtifact<
+	TData = Record<string, unknown>,
+	TVariables extends GraphqlVariables = GraphqlVariables
+> = ReplicaProtocolOperationArtifact<TData, TVariables>;
+
+export type ReplicaWriteSource = 'network' | 'live' | 'ssr' | 'restore' | 'projected';
+
+export type ReplicaResultEnvelope<TData = unknown> = {
+	readonly data?: TData | null;
+	readonly errors?: readonly GqlError[];
+	/** Strictly parsed Distributed v1 response metadata. */
+	readonly extensions?: GraphqlResponseExtensions;
+};
+
+export type ReplicaTransportRequest<
+	TData = Record<string, unknown>,
+	TVariables extends GraphqlVariables = GraphqlVariables
+> = {
+	readonly operation: 'query' | 'live';
+	readonly operationId: string;
+	readonly document: string;
+	readonly variables: TVariables;
+	readonly artifact: ReplicaOperationArtifact<TData, TVariables>;
+	/** Generated surface/schema selector forwarded as GraphQL request extensions. */
+	readonly extensions?: Readonly<Record<string, unknown>>;
+	/**
+	 * Authorization-generation cancellation. Transports must forward this to
+	 * their underlying HTTP request when they support cancellation.
+	 */
+	readonly signal?: AbortSignal;
+	/** Latest server-issued cursors for the private generated resume extension. */
+	readonly resume?: readonly DistributedLiveCursor[];
+};
+
+export type ReplicaLiveObserver<TData = unknown> = {
+	next(result: ReplicaResultEnvelope<TData>): void;
+	error(error: unknown): void;
+	complete(): void;
+};
+
+export type ReplicaTransport = {
+	fetch<
+		TData = Record<string, unknown>,
+		TVariables extends GraphqlVariables = GraphqlVariables
+	>(
+		request: ReplicaTransportRequest<TData, TVariables>
+	): Promise<ReplicaResultEnvelope<TData>>;
+	subscribe?<
+		TData = Record<string, unknown>,
+		TVariables extends GraphqlVariables = GraphqlVariables
+	>(
+		request: ReplicaTransportRequest<TData, TVariables>,
+		observer: ReplicaLiveObserver<TData>
+	): () => void;
+};
+
+export type ReplicaStatus = 'loading' | 'ready' | 'stale' | 'error';
+export type ReplicaLiveState = 'off' | 'connecting' | 'active' | 'error';
+
+/** The exact runtime shape while some selected cache fields are still absent. */
+export type ReplicaSparse<T> = T extends readonly (infer TItem)[]
+	? readonly ReplicaSparse<TItem>[]
+	: T extends object
+		? { readonly [K in keyof T]?: ReplicaSparse<T[K]> }
+		: T;
+
+type ReplicaSnapshotState = {
+	readonly fetching: boolean;
+	readonly errors: readonly GqlError[];
+	readonly live: ReplicaLiveState;
+};
+
+/**
+ * A structurally complete snapshot carries the generated result type even
+ * while its freshness is stale or a refresh failed. Only snapshots missing
+ * selected fields or index structure expose a deep sparse result.
+ */
+export type ReplicaSnapshot<TData> = ReplicaSnapshotState &
+	(
+		| ({
+				readonly data: TData;
+				readonly complete: true;
+		  } & (
+				| {
+						readonly status: 'ready';
+						readonly stale: false;
+				  }
+				| {
+						readonly status: 'stale';
+						readonly stale: true;
+				  }
+				| {
+						readonly status: 'error';
+						readonly stale: boolean;
+				  }
+		  ))
+		| {
+				readonly data: ReplicaSparse<TData>;
+				readonly status: 'loading';
+				readonly stale: false;
+				readonly complete: false;
+		  }
+		| {
+				readonly data: ReplicaSparse<TData>;
+				readonly status: 'stale';
+				readonly stale: true;
+				readonly complete: false;
+		  }
+		| {
+				readonly data: ReplicaSparse<TData>;
+				readonly status: 'error';
+				readonly stale: boolean;
+				readonly complete: false;
+		  }
+	);
+
+export type ReplicaWatch<TData> = {
+	get(): ReplicaSnapshot<TData>;
+	subscribe(listener: (snapshot: ReplicaSnapshot<TData>) => void): () => void;
+	refresh(): Promise<void>;
+	destroy(): void;
+};
+
+export type WatchReplicaOptions = {
+	readonly live?: boolean;
+};
+
+export type DistributedReplicaOptions = {
+	readonly transport?: ReplicaTransport;
+	readonly onObserverError?: (error: AggregateError) => void;
+	/** Opt-in framework-neutral diagnostics; absent in production by default. */
+	readonly diagnostics?: ReplicaDiagnosticsSink;
+};
+
+/** Server-issued authorization/cache namespace. Client-decoded claims never create one. */
+export type ReplicaAuthoritativeScope = {
+	readonly protocolVersion: 1;
+	readonly schemaHash: string;
+	readonly cacheScope: string;
+};
+
+/**
+ * Opaque, engine-independent SSR transfer owned by Distributed.
+ *
+ * `payload` is intentionally not a public cache-engine schema. Applications
+ * pass the value back to `hydrate` without interpreting it.
+ */
+export type ReplicaDehydratedState = {
+	readonly version: 1;
+	readonly scope: ReplicaAuthoritativeScope;
+	readonly payload: unknown;
+};
+
+export type ReplicaRecordInspection = {
+	readonly key: string;
+	readonly revision: string;
+	readonly incarnation: string;
+	readonly presentFields: readonly string[];
+};
+
+export type ReplicaIndexInspection = {
+	readonly key: string;
+	readonly revision: string;
+	readonly staleRevision?: string;
+	readonly records: readonly string[];
+	readonly complete: boolean;
+	readonly field: string;
+	readonly parent?: string;
+	readonly arguments: Readonly<Record<string, ReplicaValue>>;
+	readonly coverage: ReplicaIndexCoverage;
+	readonly dependencies: readonly string[];
+	readonly staleReason?: string;
+	readonly nullValue: boolean;
+};
+
+export type ReplicaIdentity = ReplicaValue | readonly ReplicaValue[];
+
+/** Exact relationship identity used to target authoritative query revalidation. */
+export type ReplicaRevalidationRelationship = {
+	readonly sourceModel: string;
+	readonly field: string;
+	readonly targetModel: string;
+};
+
+/**
+ * Compiler-owned inventory used to find active operations affected by a
+ * command. An empty inventory conservatively targets every active operation.
+ */
+export type ReplicaRevalidationPlan = {
+	readonly dependencies: readonly string[];
+	readonly models: readonly string[];
+	readonly relationships: readonly ReplicaRevalidationRelationship[];
+};
+
+export type ReplicaIndexTarget = {
+	readonly parent?: string;
+	readonly field: string;
+	readonly arguments?: Readonly<Record<string, ReplicaValue>>;
+	readonly coverage?: ReplicaIndexCoverage;
+	readonly dependencies?: readonly string[];
+	readonly complete?: boolean;
+	readonly staleReason?: string;
+	readonly nullValue?: boolean;
+};
+
+export type ReplicaRecordPatch = {
+	readonly fields?: Readonly<Record<string, ReplicaValue>>;
+	readonly links?: Readonly<Record<string, string | readonly string[] | null>>;
+};
+
+export interface ReplicaOptimisticWriter {
+	writeRecord(
+		model: ReplicaModelArtifact,
+		identity: ReplicaIdentity,
+		patch: ReplicaRecordPatch
+	): void;
+	tombstoneRecord(model: ReplicaModelArtifact, identity: ReplicaIdentity): void;
+	writeIndex(target: ReplicaIndexTarget, records: readonly string[]): void;
+	deleteIndex(target: ReplicaIndexTarget): void;
+}
+
+export interface ReplicaBaseWriter {
+	writeRecord(
+		model: ReplicaModelArtifact,
+		identity: ReplicaIdentity,
+		revision: ReplicaRevision,
+		patch: ReplicaRecordPatch & { readonly incarnation?: ReplicaRevision }
+	): boolean;
+	tombstoneRecord(
+		model: ReplicaModelArtifact,
+		identity: ReplicaIdentity,
+		revision: ReplicaRevision
+	): boolean;
+	writeIndex(
+		target: ReplicaIndexTarget,
+		records: readonly string[],
+		revision: ReplicaRevision
+	): boolean;
+	deleteIndex(target: ReplicaIndexTarget, revision: ReplicaRevision): boolean;
+}
+
+export interface DistributedReplica {
+	/** The current server-issued scope, absent until authoritative evidence arrives. */
+	readonly scope: ReplicaAuthoritativeScope | undefined;
+	/** Monotonic local fence for authorization changes and server scope changes. */
+	readonly authorizationGeneration: number;
+	read<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables
+	): ReplicaSnapshot<TData>;
+	watch<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables,
+		options?: WatchReplicaOptions
+	): ReplicaWatch<TData>;
+	writeResult<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>,
+		variables: TVariables,
+		envelope: ReplicaResultEnvelope<TData>,
+		source: ReplicaWriteSource
+	): void;
+	/**
+	 * Force deduplicated authoritative reads for active operations selected by a
+	 * compiler-owned dependency/model/relationship inventory.
+	 */
+	revalidate(plan: ReplicaRevalidationPlan): Promise<void>;
+	/**
+	 * Proactively closes the current authorization generation.
+	 *
+	 * Token/session changes may call this before the next server response, but
+	 * they cannot choose or restore a cache scope.
+	 */
+	invalidateAuthorization(): void;
+	/** Serialize confirmed state reachable from operations rendered by this replica. */
+	dehydrate(): ReplicaDehydratedState;
+	/**
+	 * Restore a server-rendered payload against the independently authoritative
+	 * scope for the current SSR response. Returns false on scope/schema mismatch
+	 * and never partially restores malformed state. Persisted state must wait for
+	 * a fresh server scope and pass that scope here.
+	 */
+	hydrate(
+		state: ReplicaDehydratedState,
+		authoritativeScope: ReplicaAuthoritativeScope
+	): boolean;
+	createOptimisticLayer(
+		id: string,
+		update: (writer: ReplicaOptimisticWriter) => void,
+		semanticChanges?: readonly ReplicaIndexSemanticChange[]
+	): void;
+	markOptimisticLayerAccepted(
+		id: string,
+		receipt?: DistributedCommandMetadata
+	): boolean;
+	confirmOptimisticLayer<T>(
+		id: string,
+		update: (writer: ReplicaBaseWriter) => T
+	): T;
+	rejectOptimisticLayer(id: string): boolean;
+	tombstoneRecord(
+		model: ReplicaModelArtifact,
+		identity: ReplicaIdentity,
+		revision: ReplicaRevision
+	): boolean;
+	markIndexStale(target: ReplicaIndexTarget, reason: string): boolean;
+	retainRecord(model: ReplicaModelArtifact, identity: ReplicaIdentity): void;
+	releaseRecord(model: ReplicaModelArtifact, identity: ReplicaIdentity): void;
+	gc(): readonly string[];
+	inspectRecord(
+		model: ReplicaModelArtifact,
+		identity: ReplicaIdentity
+	): ReplicaRecordInspection | undefined;
+	inspectIndex(target: ReplicaIndexTarget): ReplicaIndexInspection | undefined;
+}
diff --git a/js/src/request.ts b/js/src/request.ts
new file mode 100644
index 00000000..230de42d
--- /dev/null
+++ b/js/src/request.ts
@@ -0,0 +1,188 @@
+/** Isomorphic HTTP GraphQL request helper with injectable URL and authentication. */
+import { buildAuthHeaders } from './auth-headers.js';
+import { documentToString, type GqlDocument } from './document.js';
+import {
+	DistributedProtocolError,
+	parseGraphqlResponseExtensions
+} from './protocol.js';
+import type {
+	GqlAuth,
+	GqlError,
+	GqlResult,
+	GraphqlVariables
+} from './types.js';
+
+/** Fetch-compatible transport, including SvelteKit's request-scoped `fetch`. */
+export type FetchLike = typeof globalThis.fetch;
+
+export type RequestGraphqlOptions = {
+	/** Override the runtime's global fetch implementation. */
+	fetch?: FetchLike;
+	/** Framework-owned GraphQL request extensions. */
+	extensions?: Readonly<Record<string, unknown>>;
+	/** Cancel the underlying HTTP request when its authorization generation closes. */
+	signal?: AbortSignal;
+};
+
+type GraphqlResponseBody<TData> = {
+	data?: TData;
+	errors?: GqlError[];
+	error?: string;
+	extensions?: unknown;
+};
+
+type ParsedResponseBody<TData> = {
+	body: GraphqlResponseBody<TData>;
+	rawText?: string;
+};
+
+async function readResponseBody<TData>(response: Response): Promise<ParsedResponseBody<TData>> {
+	let rawText: string | undefined;
+	if (typeof response.text === 'function') {
+		try {
+			rawText = await response.text();
+		} catch {
+			// A fetch-compatible test double may only implement json().
+		}
+	}
+
+	if (rawText !== undefined) {
+		try {
+			return { body: asResponseBody<TData>(JSON.parse(rawText)) };
+		} catch {
+			return { body: {}, rawText };
+		}
+	}
+
+	try {
+		return { body: asResponseBody<TData>(await response.json()) };
+	} catch {
+		return { body: {} };
+	}
+}
+
+function asResponseBody<TData>(value: unknown): GraphqlResponseBody<TData> {
+	return value !== null && typeof value === 'object' && !Array.isArray(value)
+		? (value as GraphqlResponseBody<TData>)
+		: {};
+}
+
+function httpFailureMessage(
+	response: Response,
+	body: GraphqlResponseBody<unknown>,
+	rawText: string | undefined
+): string {
+	const jsonDetail = typeof body.error === 'string' ? body.error.trim() : '';
+	if (jsonDetail) return jsonDetail;
+
+	const statusText = response.statusText?.trim();
+	const status = `HTTP ${response.status}${statusText ? ` ${statusText}` : ''}`;
+	const textDetail = rawText?.trim() ?? '';
+	if (
+		!textDetail ||
+		/^<(?:!doctype\s+html|html|head|body)(?:\s|>)/i.test(textDetail)
+	) {
+		return status;
+	}
+
+	const maxDetailLength = 500;
+	const boundedDetail =
+		textDetail.length > maxDetailLength
+			? `${textDetail.slice(0, maxDetailLength - 1)}…`
+			: textDetail;
+	return `${status}: ${boundedDetail}`;
+}
+
+/** POST a GraphQL document to `url`. */
+export async function requestGraphql<
+	TData = Record<string, unknown>,
+	TVariables extends GraphqlVariables = GraphqlVariables
+>(
+	url: string,
+	document: GqlDocument<TData, TVariables>,
+	auth: GqlAuth = {},
+	variables: TVariables = {} as TVariables,
+	options: RequestGraphqlOptions = {}
+): Promise<GqlResult<TData>> {
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+	if (typeof fetchImpl !== 'function') {
+		throw new Error(
+			'requestGraphql requires a fetch implementation in this runtime; pass { fetch } as the final argument'
+		);
+	}
+
+	const token = auth.accessToken?.trim() ?? '';
+	const response = await fetchImpl(url, {
+		method: 'POST',
+		headers: buildAuthHeaders(auth),
+		body: JSON.stringify({
+			query: documentToString(document),
+			variables,
+			...(options.extensions === undefined
+				? {}
+				: { extensions: options.extensions })
+		}),
+		...(options.signal === undefined ? {} : { signal: options.signal })
+	});
+
+	const { body, rawText } = await readResponseBody<TData>(response);
+	let extensions;
+	try {
+		extensions = parseGraphqlResponseExtensions(body.extensions);
+	} catch (error) {
+		if (error instanceof DistributedProtocolError) {
+			return {
+				data: undefined,
+				errors: [
+					...(body.errors ?? []),
+					{
+						message: error.message,
+						extensions: { code: error.code }
+					}
+				],
+				status: response.status
+			};
+		}
+		throw error;
+	}
+
+	if (response.status === 401) {
+		const detail =
+			body.errors?.[0]?.message ??
+			body.error ??
+			(token
+				? 'Bearer rejected (audience/issuer/expiry) — sign out and back in'
+				: 'no access token — re-login; check OIDC scopes include the project audience');
+
+		return {
+			data: body.data,
+			errors: [{ message: detail }],
+			...(extensions === undefined ? {} : { extensions }),
+			status: response.status
+		};
+	}
+
+	if (
+		response.status >= 400 &&
+		response.status < 600 &&
+		!body.errors?.length
+	) {
+		return {
+			data: body.data,
+			errors: [{ message: httpFailureMessage(response, body, rawText) }],
+			...(extensions === undefined ? {} : { extensions }),
+			status: response.status
+		};
+	}
+
+	return {
+		data: body.data,
+		errors: body.errors,
+		...(extensions === undefined ? {} : { extensions }),
+		status: response.status
+	};
+}
+
+export type { GqlDocument } from './document.js';
+export { documentToString } from './document.js';
+export { buildAuthHeaders } from './auth-headers.js';
diff --git a/js/src/sveltekit/auth.ts b/js/src/sveltekit/auth.ts
new file mode 100644
index 00000000..b89436eb
--- /dev/null
+++ b/js/src/sveltekit/auth.ts
@@ -0,0 +1,27 @@
+import type { GqlAuth } from '../types.js';
+
+/** Minimal page-data shape needed to bind browser GraphQL authentication. */
+export type PageGraphqlData = {
+	accessToken?: string | null;
+	session?: {
+		accessToken?: string | null;
+		user?: {
+			id?: string | null;
+			name?: string | null;
+			email?: string | null;
+			username?: string | null;
+			groups?: string[];
+		} | null;
+	} | null;
+	engineRole?: string | null;
+};
+
+/** Map SSR/page data into GraphQL auth (Bearer preferred; DevHeaders for local development). */
+export function authFromPageData(data: PageGraphqlData): GqlAuth {
+	const accessToken = data.accessToken ?? data.session?.accessToken ?? null;
+	return {
+		accessToken,
+		userId: accessToken ? undefined : (data.session?.user?.id ?? undefined),
+		role: data.engineRole ?? undefined
+	};
+}
diff --git a/js/src/sveltekit/context.ts b/js/src/sveltekit/context.ts
new file mode 100644
index 00000000..59c51540
--- /dev/null
+++ b/js/src/sveltekit/context.ts
@@ -0,0 +1,101 @@
+import { getContext, setContext } from 'svelte';
+
+import type {
+	ReplicaOperationArtifact,
+	ReplicaSnapshot
+} from '../replica/index.js';
+import type { GraphqlVariables } from '../types.js';
+import type {
+	DistributedSvelteKitClient,
+	SveltekitBoundOperation
+} from './replica.js';
+
+const DISTRIBUTED_CLIENT_CONTEXT = Symbol(
+	'@hops-ops/distributed/sveltekit/client'
+);
+
+type AnyDistributedSvelteKitClient = DistributedSvelteKitClient<unknown>;
+
+/**
+ * Install one client in the current Svelte component tree.
+ *
+ * The context key is module-global, but the client value is not: Svelte owns
+ * it per component tree/request. A nested elevated layout may deliberately
+ * replace the nearest user-safe client.
+ */
+export function provideDistributedSvelteKitClient<TCommands>(
+	client: DistributedSvelteKitClient<TCommands>
+): DistributedSvelteKitClient<TCommands> {
+	if (
+		client === null ||
+		typeof client !== 'object' ||
+		typeof client.operation !== 'function'
+	) {
+		throw new TypeError(
+			'provideDistributedSvelteKitClient requires a Distributed SvelteKit client'
+		);
+	}
+	setContext(
+		DISTRIBUTED_CLIENT_CONTEXT,
+		client as AnyDistributedSvelteKitClient
+	);
+	return client;
+}
+
+/**
+ * Resolve the nearest client during component initialization.
+ *
+ * This intentionally calls Svelte `getContext` each time. Generated modules
+ * may contain static operation wrappers, but never capture a client or command
+ * tree at module evaluation time.
+ */
+export function useDistributedSvelteKitClient<
+	TCommands = Readonly<Record<never, never>>
+>(): DistributedSvelteKitClient<TCommands> {
+	const client = getContext<AnyDistributedSvelteKitClient | undefined>(
+		DISTRIBUTED_CLIENT_CONTEXT
+	);
+	if (client === undefined) {
+		throw new Error(
+			'Distributed client is missing from the active Svelte component tree; call generated provideDistributed(...) in a parent layout'
+		);
+	}
+	return client as DistributedSvelteKitClient<TCommands>;
+}
+
+/** Resolve the nearest generated command surface without a global proxy. */
+export function useDistributedSvelteKitCommands<TCommands>(): TCommands {
+	return useDistributedSvelteKitClient<TCommands>().commands;
+}
+
+/**
+ * Define one SSR-safe generated operation wrapper.
+ *
+ * The wrapper stores only immutable compiler output. `use()` and `read()`
+ * resolve the nearest tree-local client when the component calls them.
+ */
+export function defineDistributedSvelteKitOperation<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	artifact: ReplicaOperationArtifact<TData, TVariables>
+): SveltekitBoundOperation<TData, TVariables> {
+	const use = ((...args: unknown[]) => {
+		const operation =
+			useDistributedSvelteKitClient<unknown>().operation(artifact);
+		const invoke = operation.use as (
+			...values: unknown[]
+		) => ReturnType<SveltekitBoundOperation<TData, TVariables>['use']>;
+		return invoke(...args);
+	}) as SveltekitBoundOperation<TData, TVariables>['use'];
+
+	return Object.freeze({
+		artifact,
+		use,
+		read(variables: TVariables): ReplicaSnapshot<TData> {
+			return useDistributedSvelteKitClient<unknown>()
+				.operation(artifact)
+				.read(variables);
+		}
+	});
+}
diff --git a/js/src/sveltekit/index.ts b/js/src/sveltekit/index.ts
new file mode 100644
index 00000000..fab8b500
--- /dev/null
+++ b/js/src/sveltekit/index.ts
@@ -0,0 +1,38 @@
+export { authFromPageData, type PageGraphqlData } from './auth.js';
+export {
+	defineDistributedSvelteKitOperation,
+	provideDistributedSvelteKitClient,
+	useDistributedSvelteKitClient,
+	useDistributedSvelteKitCommands
+} from './context.js';
+export {
+	bindSveltekitOperation,
+	createPageDataSessionSource,
+	createDistributedSvelteKit,
+	sessionSourceFromPageData,
+	type CreateDistributedSvelteKitOptions,
+	type DistributedSvelteKitClient,
+	type SveltekitBoundOperation,
+	type SveltekitCommandRuntimeFactory,
+	type SveltekitCommandRuntimeFactoryOptions,
+	type SveltekitCommandRuntimeLike,
+	type SveltekitDistributedPageData,
+	type SveltekitPageDataSessionSource,
+	type SveltekitPageDataSource,
+	type SveltekitQuerySnapshot,
+	type SveltekitQueryStore,
+	type SveltekitReplicaAuthority,
+	type SveltekitReplicaHydration,
+	type SveltekitSessionSource,
+	type UseSveltekitOperationOptions
+} from './replica.js';
+export {
+	createDistributedSvelteKitServer,
+	registerDistributedRoute,
+	type CreateDistributedSvelteKitServerOptions,
+	type DistributedRouteOperation,
+	type DistributedRoutePlan,
+	type DistributedRouteVariables,
+	type DistributedSvelteKitServer,
+	type SveltekitServerLoadEventLike
+} from './server-replica.js';
diff --git a/js/src/sveltekit/replica.ts b/js/src/sveltekit/replica.ts
new file mode 100644
index 00000000..6078206a
--- /dev/null
+++ b/js/src/sveltekit/replica.ts
@@ -0,0 +1,837 @@
+import {
+	sameAuthCredential,
+	snapshotAuthCredential
+} from '../identity.js';
+import {
+	createDistributedReplica,
+	createReplicaGraphqlTransport,
+	type DistributedReplica,
+	type DistributedReplicaOptions,
+	type ReplicaAuthoritativeScope,
+	type ReplicaCommandReceipt,
+	type ReplicaCommandRuntime,
+	type ReplicaCommandRuntimeOptions,
+	type ReplicaGraphqlTransport,
+	type ReplicaOperationArtifact,
+	type ReplicaSnapshot,
+	type ReplicaWatch,
+	type WatchReplicaOptions
+} from '../replica/index.js';
+import type { GqlAuth, GqlError, GraphqlVariables } from '../types.js';
+import type { WebSocketConstructor } from '../websocket.js';
+import type { FetchLike } from '../request.js';
+import { replicaCommandProjectedLifecycleOf } from '../replica/command-runtime.js';
+import { authFromPageData, type PageGraphqlData } from './auth.js';
+
+type UnknownCommandEntries = Readonly<Record<string, never>>;
+
+export type SveltekitSessionSource = Readonly<{
+	/** Current credential. HTTP, WS, and commands all call this exact source. */
+	getAuth(): GqlAuth | Promise<GqlAuth>;
+	/**
+	 * Notify on token, logout, role, tenant, or session changes.
+	 *
+	 * The adapter re-reads `getAuth`; callers never label a cache scope.
+	 */
+	subscribe?(listener: () => void): () => void;
+}>;
+
+export type SveltekitPageDataSource<TData extends PageGraphqlData> = Readonly<{
+	get(): TData;
+	subscribe?(listener: () => void): () => void;
+}>;
+
+export type SveltekitPageDataSessionSource<TData extends PageGraphqlData> =
+	Readonly<{
+		session: SveltekitSessionSource;
+		get(): TData;
+		set(next: TData): void;
+	}>;
+
+export type SveltekitReplicaHydration = Readonly<{
+	version: 1;
+	state: import('../replica/index.js').ReplicaDehydratedState;
+	readonly operations?: readonly string[];
+}>;
+
+/**
+ * Independently trusted SSR/session authority for one hydration transfer.
+ *
+ * Do not persist this beside replica state. State never authorizes its own
+ * scope; the adapter compares its embedded scope to this server-owned value.
+ */
+export type SveltekitReplicaAuthority = Readonly<{
+	version: 1;
+	scope: ReplicaAuthoritativeScope;
+}>;
+
+export type SveltekitDistributedPageData = PageGraphqlData &
+	Readonly<{
+		distributed?: SveltekitReplicaHydration;
+		distributedAuthority?: SveltekitReplicaAuthority;
+	}>;
+
+export type SveltekitCommandRuntimeLike<TCommands> = Pick<
+	ReplicaCommandRuntime<UnknownCommandEntries>,
+	'dispose'
+> &
+	Readonly<{
+		commands: TCommands;
+	}>;
+
+export type SveltekitCommandRuntimeFactory<TCommands> = (
+	replica: DistributedReplica,
+	transport: ReplicaGraphqlTransport,
+	options: SveltekitCommandRuntimeFactoryOptions
+) => SveltekitCommandRuntimeLike<TCommands>;
+
+export type SveltekitCommandRuntimeFactoryOptions = Pick<
+	ReplicaCommandRuntimeOptions,
+	'diagnostics'
+>;
+
+export type CreateDistributedSvelteKitOptions<TCommands = Readonly<Record<never, never>>> =
+	Readonly<{
+		session: SveltekitSessionSource;
+		/** Same-origin `/graphql` by default. */
+		url?: string | (() => string);
+		fetch?: FetchLike;
+		webSocket?: WebSocketConstructor;
+		/**
+		 * Set to SvelteKit's `$app/environment` `browser` flag. When false,
+		 * store subscriptions remain side-effect-free during component SSR.
+		 */
+		browser?: boolean;
+		hydration?: SveltekitReplicaHydration;
+		/** Required with `hydration`; must come from current trusted SSR page data. */
+		authority?: SveltekitReplicaAuthority;
+		createCommands?: SveltekitCommandRuntimeFactory<TCommands>;
+		replica?: Omit<DistributedReplicaOptions, 'transport'>;
+		onAuthError?: (error: unknown) => void;
+	}>;
+
+export type SveltekitQuerySnapshot<TData> = ReplicaSnapshot<TData> &
+	Readonly<{
+	loading: boolean;
+	error?: GqlError;
+	/** Causally accepted commands still waiting for projection visibility. */
+	pending: readonly ReplicaCommandReceipt<unknown>[];
+	refetch(): Promise<void>;
+}>;
+
+export interface SveltekitQueryStore<TData> {
+	/** Current value for imperative code and adapter conformance. */
+	get(): SveltekitQuerySnapshot<TData>;
+	/** Svelte-readable store contract; use `$query` in a component. */
+	subscribe(listener: (snapshot: SveltekitQuerySnapshot<TData>) => void): () => void;
+	refetch(): Promise<void>;
+	destroy(): void;
+	readonly data: ReplicaSnapshot<TData>['data'];
+	readonly status: ReplicaSnapshot<TData>['status'];
+	readonly complete: boolean;
+	readonly loading: boolean;
+	readonly fetching: boolean;
+	readonly stale: boolean;
+	readonly live: ReplicaSnapshot<TData>['live'];
+	readonly errors: readonly GqlError[];
+	readonly error: GqlError | undefined;
+	readonly pending: readonly ReplicaCommandReceipt<unknown>[];
+}
+
+export type UseSveltekitOperationOptions = Readonly<{
+	/** Defaults to true when the compiler emitted a live companion. */
+	live?: boolean;
+}>;
+
+type UseOperationArguments<TVariables extends GraphqlVariables> =
+	Record<string, never> extends TVariables
+		?
+				| []
+				| [variables: TVariables]
+				| [
+						variables: TVariables,
+						options: UseSveltekitOperationOptions
+				  ]
+		: [
+				variables: TVariables,
+				options?: UseSveltekitOperationOptions
+		  ];
+
+export type SveltekitBoundOperation<
+	TData,
+	TVariables extends GraphqlVariables
+> = Readonly<{
+	artifact: ReplicaOperationArtifact<TData, TVariables>;
+	use(
+		...args: UseOperationArguments<TVariables>
+	): SveltekitQueryStore<TData>;
+	read(variables: TVariables): ReplicaSnapshot<TData>;
+}>;
+
+export type DistributedSvelteKitClient<TCommands> = Readonly<{
+	replica: DistributedReplica;
+	transport: ReplicaGraphqlTransport;
+	commands: TCommands;
+	operation<TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>
+	): SveltekitBoundOperation<TData, TVariables>;
+	/**
+	 * Apply a server seed. A malformed or mismatched seed closes the old
+	 * generation and returns false so the bound operation refetches.
+	 */
+	hydrate(
+		hydration: SveltekitReplicaHydration,
+		authority: SveltekitReplicaAuthority
+	): boolean;
+	invalidateAuthorization(): void;
+	destroy(): void;
+}>;
+
+/**
+ * Bind the framework-neutral replica to Svelte's readable-store lifecycle.
+ *
+ * Generated `$distributed` modules call this once, then export
+ * `client.operation(Operation_Todos)` and `client.commands`.
+ */
+export function createDistributedSvelteKit<TCommands = Readonly<Record<never, never>>>(
+	options: CreateDistributedSvelteKitOptions<TCommands>
+): DistributedSvelteKitClient<TCommands> {
+	if (
+		options.session === null ||
+		typeof options.session !== 'object' ||
+		typeof options.session.getAuth !== 'function'
+	) {
+		throw new TypeError('Distributed SvelteKit requires one session source');
+	}
+	if (
+		(options.hydration === undefined) !==
+		(options.authority === undefined)
+	) {
+		throw new TypeError(
+			'Distributed SvelteKit hydration requires separate trusted SSR authority'
+		);
+	}
+
+	let replica: DistributedReplica | undefined;
+	const auth = createAuthorizationFence(
+		options.session,
+		() => replica?.invalidateAuthorization(),
+		options.onAuthError
+	);
+	const configuredUrl = options.url;
+	const transport = createReplicaGraphqlTransport({
+		getUrl:
+			typeof configuredUrl === 'function'
+				? configuredUrl
+				: () => configuredUrl ?? '/graphql',
+		getAuth: auth.read,
+		...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+		...(options.webSocket === undefined
+			? {}
+			: { webSocket: options.webSocket })
+	});
+	replica = createDistributedReplica({
+		transport,
+		...(options.replica ?? {})
+	});
+
+	const stores = new Set<SveltekitQueryStoreImpl<unknown>>();
+	const pending = new PendingReceiptStore();
+	let destroyed = false;
+	const hydrate = (
+		hydration: SveltekitReplicaHydration,
+		authority: SveltekitReplicaAuthority
+	): boolean => {
+		let accepted = false;
+		try {
+			const expected = validatedHydrationAuthority(authority);
+			const active = replica!.scope;
+			if (active !== undefined && !sameReplicaScope(active, expected)) {
+				throw new TypeError(
+					'Distributed SvelteKit hydration authority changed before session invalidation'
+				);
+			}
+			accepted =
+				hydration?.version === 1 &&
+				replica!.hydrate(hydration.state, expected);
+		} catch {
+			accepted = false;
+		}
+		if (!accepted) replica!.invalidateAuthorization();
+		return accepted;
+	};
+	if (options.hydration !== undefined && options.authority !== undefined) {
+		hydrate(options.hydration, options.authority);
+	}
+
+	// Hydration must precede command authority registration: trusted presets are
+	// server-derived and restored only as part of an exact authoritative seed.
+	const commandRuntime = options.createCommands?.(
+		replica,
+		transport,
+		Object.freeze({
+			...(options.replica?.diagnostics === undefined
+				? {}
+				: { diagnostics: options.replica.diagnostics })
+		})
+	);
+	const commands =
+		commandRuntime === undefined
+			? (Object.freeze({}) as TCommands)
+			: wrapCommandTree(commandRuntime.commands, pending);
+
+	const operation = <TData, TVariables extends GraphqlVariables>(
+		artifact: ReplicaOperationArtifact<TData, TVariables>
+	): SveltekitBoundOperation<TData, TVariables> =>
+		bindOperation(replica!, artifact, pending, {
+			isAlive: () => !destroyed,
+			activateWatches: () => options.browser ?? true,
+			active: (store) => {
+				stores.add(store as SveltekitQueryStoreImpl<unknown>);
+			},
+			idle: (store) => {
+				stores.delete(store as SveltekitQueryStoreImpl<unknown>);
+			}
+		});
+
+	return Object.freeze({
+		replica,
+		transport,
+		commands,
+		operation,
+		hydrate,
+		invalidateAuthorization(): void {
+			if (!destroyed) replica!.invalidateAuthorization();
+		},
+		destroy(): void {
+			if (destroyed) return;
+			destroyed = true;
+			auth.dispose();
+			for (const store of [...stores]) store.destroy();
+			stores.clear();
+			pending.clear();
+			commandRuntime?.dispose();
+		}
+	});
+}
+
+/**
+ * Low-level composition seam for applications that already own a replica.
+ *
+ * Most SvelteKit applications use `createDistributedSvelteKit().operation()`;
+ * this form exists for custom composition and framework adapter conformance.
+ */
+export function bindSveltekitOperation<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	replica: DistributedReplica,
+	artifact: ReplicaOperationArtifact<TData, TVariables>
+): SveltekitBoundOperation<TData, TVariables> {
+	return bindOperation(
+		replica,
+		artifact,
+		new PendingReceiptStore(),
+		{
+			isAlive: () => true,
+			activateWatches: () => true,
+			active: () => undefined,
+			idle: () => undefined
+		}
+	);
+}
+
+/** Map SvelteKit page data into the one shared transport/session source. */
+export function sessionSourceFromPageData<TData extends PageGraphqlData>(
+	source: SveltekitPageDataSource<TData>
+): SveltekitSessionSource {
+	if (
+		source === null ||
+		typeof source !== 'object' ||
+		typeof source.get !== 'function'
+	) {
+		throw new TypeError('page-data session source requires get');
+	}
+	return Object.freeze({
+		getAuth: () => authFromPageData(source.get()),
+		...(source.subscribe === undefined
+			? {}
+			: { subscribe: source.subscribe.bind(source) })
+	});
+}
+
+/**
+ * Create the single mutable page-data/session source owned by one layout.
+ *
+ * HTTP, WebSocket reconnects, commands, and authorization invalidation all
+ * observe `session`; navigation updates the same source through `set`.
+ */
+export function createPageDataSessionSource<TData extends PageGraphqlData>(
+	initial: TData
+): SveltekitPageDataSessionSource<TData> {
+	let current = initial;
+	const listeners = new Set<() => void>();
+	const source = Object.freeze({
+		get(): TData {
+			return current;
+		},
+		subscribe(listener: () => void): () => void {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	});
+	return Object.freeze({
+		session: sessionSourceFromPageData(source),
+		get: source.get,
+		set(next: TData): void {
+			current = next;
+			for (const listener of [...listeners]) listener();
+		}
+	});
+}
+
+function bindOperation<TData, TVariables extends GraphqlVariables>(
+	replica: DistributedReplica,
+	artifact: ReplicaOperationArtifact<TData, TVariables>,
+	pending: PendingReceiptStore,
+	lifecycle: SveltekitStoreLifecycle<TData>
+): SveltekitBoundOperation<TData, TVariables> {
+	const use = (
+		...args: UseOperationArguments<TVariables>
+	): SveltekitQueryStore<TData> => {
+		const variables = (args[0] ?? {}) as TVariables;
+		const useOptions = args[1] as UseSveltekitOperationOptions | undefined;
+		const store = new SveltekitQueryStoreImpl(
+			replica,
+			artifact,
+			variables,
+			Object.freeze({
+				live: useOptions?.live ?? artifact.live !== undefined
+			}),
+			pending,
+			lifecycle
+		);
+		return store;
+	};
+	return Object.freeze({
+		artifact,
+		use,
+		read: (variables: TVariables) => replica.read(artifact, variables)
+	});
+}
+
+type SveltekitStoreLifecycle<TData> = Readonly<{
+	isAlive(): boolean;
+	activateWatches(): boolean;
+	active(store: SveltekitQueryStoreImpl<TData>): void;
+	idle(store: SveltekitQueryStoreImpl<TData>): void;
+}>;
+
+class SveltekitQueryStoreImpl<TData> implements SveltekitQueryStore<TData> {
+	readonly #replica: DistributedReplica;
+	readonly #artifact: ReplicaOperationArtifact<TData, GraphqlVariables>;
+	readonly #variables: GraphqlVariables;
+	readonly #options: WatchReplicaOptions;
+	readonly #pending: PendingReceiptStore;
+	readonly #lifecycle: SveltekitStoreLifecycle<TData>;
+	readonly #listeners = new Set<
+		(snapshot: SveltekitQuerySnapshot<TData>) => void
+	>();
+	#watch: ReplicaWatch<TData> | undefined;
+	#unsubscribeWatch: (() => void) | undefined;
+	#unsubscribePending: (() => void) | undefined;
+	#snapshot: SveltekitQuerySnapshot<TData>;
+	#destroyed = false;
+
+	constructor(
+		replica: DistributedReplica,
+		artifact: ReplicaOperationArtifact<TData, GraphqlVariables>,
+		variables: GraphqlVariables,
+		options: WatchReplicaOptions,
+		pending: PendingReceiptStore,
+		lifecycle: SveltekitStoreLifecycle<TData>
+	) {
+		this.#replica = replica;
+		this.#artifact = artifact;
+		this.#variables = variables;
+		this.#options = options;
+		this.#pending = pending;
+		this.#lifecycle = lifecycle;
+		this.#snapshot = querySnapshot(
+			replica.read(artifact, variables),
+			pending.get(),
+			() => this.refetch()
+		);
+	}
+
+	get(): SveltekitQuerySnapshot<TData> {
+		if (!this.#destroyed && this.#watch === undefined) {
+			this.#snapshot = querySnapshot(
+				this.#replica.read(this.#artifact, this.#variables),
+				this.#pending.get(),
+				() => this.refetch()
+			);
+		}
+		return this.#snapshot;
+	}
+
+	subscribe(
+		listener: (snapshot: SveltekitQuerySnapshot<TData>) => void
+	): () => void {
+		if (this.#destroyed) {
+			throw new Error('Distributed SvelteKit query is destroyed');
+		}
+		if (typeof listener !== 'function') {
+			throw new TypeError('Distributed SvelteKit query listener must be a function');
+		}
+		if (!this.#lifecycle.isAlive()) {
+			throw new Error('Distributed SvelteKit client is destroyed');
+		}
+		if (
+			this.#listeners.size === 0 &&
+			this.#lifecycle.activateWatches()
+		) {
+			this.#activate();
+		}
+		this.#listeners.add(listener);
+		listener(this.#snapshot);
+		let active = true;
+		return () => {
+			if (!active) return;
+			active = false;
+			this.#listeners.delete(listener);
+			if (this.#listeners.size === 0) this.#deactivate();
+		};
+	}
+
+	async refetch(): Promise<void> {
+		if (this.#destroyed) {
+			throw new Error('Distributed SvelteKit query is destroyed');
+		}
+		if (!this.#lifecycle.isAlive()) {
+			throw new Error('Distributed SvelteKit client is destroyed');
+		}
+		if (this.#watch !== undefined) {
+			await this.#watch.refresh();
+			return;
+		}
+		const temporary = this.#replica.watch(
+			this.#artifact,
+			this.#variables,
+			{ ...this.#options, live: false }
+		);
+		try {
+			await temporary.refresh();
+			this.#snapshot = querySnapshot(
+				temporary.get(),
+				this.#pending.get(),
+				() => this.refetch()
+			);
+		} finally {
+			temporary.destroy();
+		}
+	}
+
+	destroy(): void {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		this.#deactivate();
+		this.#listeners.clear();
+	}
+
+	get data(): ReplicaSnapshot<TData>['data'] {
+		return this.#snapshot.data;
+	}
+	get status(): ReplicaSnapshot<TData>['status'] {
+		return this.#snapshot.status;
+	}
+	get complete(): boolean {
+		return this.#snapshot.complete;
+	}
+	get loading(): boolean {
+		return this.#snapshot.loading;
+	}
+	get fetching(): boolean {
+		return this.#snapshot.fetching;
+	}
+	get stale(): boolean {
+		return this.#snapshot.stale;
+	}
+	get live(): ReplicaSnapshot<TData>['live'] {
+		return this.#snapshot.live;
+	}
+	get errors(): readonly GqlError[] {
+		return this.#snapshot.errors;
+	}
+	get error(): GqlError | undefined {
+		return this.#snapshot.error;
+	}
+	get pending(): readonly ReplicaCommandReceipt<unknown>[] {
+		return this.#snapshot.pending;
+	}
+
+	#activate(): void {
+		let watch: ReplicaWatch<TData> | undefined;
+		try {
+			watch = this.#replica.watch(
+				this.#artifact,
+				this.#variables,
+				this.#options
+			);
+			this.#watch = watch;
+			this.#snapshot = querySnapshot(
+				watch.get(),
+				this.#pending.get(),
+				() => this.refetch()
+			);
+			this.#unsubscribeWatch = watch.subscribe((snapshot) => {
+				this.#publish(snapshot, this.#pending.get());
+			});
+			this.#unsubscribePending = this.#pending.subscribe((receipts) => {
+				const current = this.#watch;
+				if (current !== undefined) this.#publish(current.get(), receipts);
+			});
+			this.#lifecycle.active(this);
+		} catch (error) {
+			this.#unsubscribeWatch?.();
+			this.#unsubscribePending?.();
+			watch?.destroy();
+			this.#watch = undefined;
+			this.#unsubscribeWatch = undefined;
+			this.#unsubscribePending = undefined;
+			throw error;
+		}
+	}
+
+	#deactivate(): void {
+		if (this.#watch === undefined) return;
+		this.#unsubscribeWatch?.();
+		this.#unsubscribePending?.();
+		this.#watch.destroy();
+		this.#watch = undefined;
+		this.#unsubscribeWatch = undefined;
+		this.#unsubscribePending = undefined;
+		this.#lifecycle.idle(this);
+	}
+
+	#publish(
+		replicaSnapshot: ReplicaSnapshot<TData>,
+		receipts: readonly ReplicaCommandReceipt<unknown>[]
+	): void {
+		if (this.#destroyed) return;
+		const next = querySnapshot(replicaSnapshot, receipts, () => this.refetch());
+		if (sameQuerySnapshot(this.#snapshot, next)) return;
+		this.#snapshot = next;
+		for (const listener of [...this.#listeners]) listener(next);
+	}
+}
+
+class PendingReceiptStore {
+	readonly #receipts = new Map<string, ReplicaCommandReceipt<unknown>>();
+	readonly #listeners = new Set<
+		(receipts: readonly ReplicaCommandReceipt<unknown>[]) => void
+	>();
+	#snapshot: readonly ReplicaCommandReceipt<unknown>[] = Object.freeze([]);
+
+	get(): readonly ReplicaCommandReceipt<unknown>[] {
+		return this.#snapshot;
+	}
+
+	subscribe(
+		listener: (receipts: readonly ReplicaCommandReceipt<unknown>[]) => void
+	): () => void {
+		this.#listeners.add(listener);
+		return () => this.#listeners.delete(listener);
+	}
+
+	track(receipt: ReplicaCommandReceipt<unknown>): void {
+		const lifecycle =
+			replicaCommandProjectedLifecycleOf(receipt) ?? receipt.projected;
+		if (lifecycle === undefined || this.#receipts.has(receipt.commandId)) {
+			return;
+		}
+		this.#receipts.set(receipt.commandId, receipt);
+		this.#publish();
+		void lifecycle.then(
+			() => this.#remove(receipt.commandId),
+			() => this.#remove(receipt.commandId)
+		);
+	}
+
+	clear(): void {
+		if (this.#receipts.size === 0) return;
+		this.#receipts.clear();
+		this.#publish();
+		this.#listeners.clear();
+	}
+
+	#remove(commandId: string): void {
+		if (!this.#receipts.delete(commandId)) return;
+		this.#publish();
+	}
+
+	#publish(): void {
+		this.#snapshot = Object.freeze([...this.#receipts.values()]);
+		for (const listener of [...this.#listeners]) listener(this.#snapshot);
+	}
+}
+
+function wrapCommandTree<TCommands>(
+	value: TCommands,
+	pending: PendingReceiptStore
+): TCommands {
+	if (typeof value === 'function') {
+		const command = value as (...args: unknown[]) => unknown;
+		return ((...args: unknown[]) => {
+			const result = command(...args);
+			if (isPromiseLike(result)) {
+				return result.then((receipt: unknown) => {
+					if (isCommandReceipt(receipt)) pending.track(receipt);
+					return receipt;
+				});
+			}
+			return result;
+		}) as TCommands;
+	}
+	if (value === null || typeof value !== 'object') return value;
+	const output = Object.create(null) as Record<string, unknown>;
+	for (const key of Object.keys(value)) {
+		output[key] = wrapCommandTree(
+			(value as Record<string, unknown>)[key],
+			pending
+		);
+	}
+	return Object.freeze(output) as TCommands;
+}
+
+function isCommandReceipt(
+	value: unknown
+): value is ReplicaCommandReceipt<unknown> {
+	return (
+		value !== null &&
+		typeof value === 'object' &&
+		typeof (value as { commandId?: unknown }).commandId === 'string' &&
+		typeof (value as { status?: unknown }).status === 'function'
+	);
+}
+
+function isPromiseLike(value: unknown): value is Promise<unknown> {
+	return (
+		value !== null &&
+		(typeof value === 'object' || typeof value === 'function') &&
+		typeof (value as { then?: unknown }).then === 'function'
+	);
+}
+
+function querySnapshot<TData>(
+	snapshot: ReplicaSnapshot<TData>,
+	pending: readonly ReplicaCommandReceipt<unknown>[],
+	refetch: () => Promise<void>
+): SveltekitQuerySnapshot<TData> {
+	return Object.freeze({
+		...snapshot,
+		loading: snapshot.fetching || snapshot.status === 'loading',
+		...(snapshot.errors[0] === undefined
+			? {}
+			: { error: snapshot.errors[0] }),
+		pending,
+		refetch
+	}) as SveltekitQuerySnapshot<TData>;
+}
+
+function sameQuerySnapshot<TData>(
+	left: SveltekitQuerySnapshot<TData>,
+	right: SveltekitQuerySnapshot<TData>
+): boolean {
+	return (
+		left.data === right.data &&
+		left.status === right.status &&
+		left.complete === right.complete &&
+		left.loading === right.loading &&
+		left.fetching === right.fetching &&
+		left.stale === right.stale &&
+		left.live === right.live &&
+		left.errors === right.errors &&
+		left.pending === right.pending
+	);
+}
+
+function createAuthorizationFence(
+	source: SveltekitSessionSource,
+	invalidate: () => void,
+	onError: ((error: unknown) => void) | undefined
+): Readonly<{ read(): Promise<GqlAuth>; dispose(): void }> {
+	let current: Readonly<GqlAuth> | undefined;
+	let queue = Promise.resolve();
+	let disposed = false;
+	const read = (): Promise<GqlAuth> => {
+		const candidate = Promise.resolve().then(() => source.getAuth());
+		const transition = queue.then(async () => {
+			try {
+				const next = snapshotAuthCredential(await candidate);
+				if (
+					current !== undefined &&
+					!sameAuthCredential(current, next)
+				) {
+					invalidate();
+				}
+				current = next;
+				return next;
+			} catch (error) {
+				current = undefined;
+				invalidate();
+				throw error;
+			}
+		});
+		queue = transition.then(
+			() => undefined,
+			() => undefined
+		);
+		return transition;
+	};
+	const unsubscribe = source.subscribe?.(() => {
+		if (disposed) return;
+		void read().catch((error: unknown) => onError?.(error));
+	});
+	// Snapshot the bind-time credential so a later first request can fence a
+	// token refresh that retained the same unverified JWT subject.
+	void read().catch((error: unknown) => onError?.(error));
+	return Object.freeze({
+		read,
+		dispose(): void {
+			if (disposed) return;
+			disposed = true;
+			unsubscribe?.();
+		}
+	});
+}
+
+function validatedHydrationAuthority(
+	value: SveltekitReplicaAuthority
+): ReplicaAuthoritativeScope {
+	const scope = value?.scope;
+	if (
+		value?.version !== 1 ||
+		scope === null ||
+		typeof scope !== 'object' ||
+		scope.protocolVersion !== 1 ||
+		typeof scope.schemaHash !== 'string' ||
+		scope.schemaHash.length === 0 ||
+		typeof scope.cacheScope !== 'string' ||
+		scope.cacheScope.length === 0
+	) {
+		throw new TypeError('Distributed SvelteKit hydration authority is invalid');
+	}
+	return scope;
+}
+
+function sameReplicaScope(
+	left: ReplicaAuthoritativeScope,
+	right: ReplicaAuthoritativeScope
+): boolean {
+	return (
+		left.protocolVersion === right.protocolVersion &&
+		left.schemaHash === right.schemaHash &&
+		left.cacheScope === right.cacheScope
+	);
+}
diff --git a/js/src/sveltekit/server-replica.ts b/js/src/sveltekit/server-replica.ts
new file mode 100644
index 00000000..427ef40b
--- /dev/null
+++ b/js/src/sveltekit/server-replica.ts
@@ -0,0 +1,290 @@
+import {
+	createDistributedReplica,
+	createReplicaGraphqlTransport,
+	type ReplicaDehydratedState,
+	type ReplicaOperationArtifact,
+	type ReplicaWatch
+} from '../replica/index.js';
+import type { FetchLike } from '../request.js';
+import type { GqlAuth, GraphqlVariables } from '../types.js';
+import { authFromPageData, type PageGraphqlData } from './auth.js';
+import type {
+	SveltekitDistributedPageData,
+	SveltekitReplicaAuthority,
+	SveltekitReplicaHydration
+} from './replica.js';
+
+export type DistributedRoutePlan = Readonly<{
+	operation: string;
+	route: string;
+	source_path?: string;
+	discovery: 'convention' | 'explicit';
+}>;
+
+export type DistributedRouteOperation = Readonly<{
+	plan: DistributedRoutePlan;
+	artifact: ReplicaOperationArtifact<unknown, GraphqlVariables>;
+}>;
+
+export type SveltekitServerLoadEventLike<TLocals = unknown> = Readonly<{
+	locals: TLocals;
+	route?: Readonly<{ id?: string | null }>;
+	url?: URL;
+	fetch?: FetchLike;
+}>;
+
+export type DistributedRouteVariables<
+	TEvent extends SveltekitServerLoadEventLike
+> = Readonly<
+	Record<
+		string,
+		(event: TEvent) => GraphqlVariables | Promise<GraphqlVariables>
+	>
+>;
+
+export type CreateDistributedSvelteKitServerOptions<
+	TSession extends NonNullable<PageGraphqlData['session']>,
+	TEvent extends SveltekitServerLoadEventLike = SveltekitServerLoadEventLike
+> = Readonly<{
+	routes: readonly DistributedRouteOperation[];
+	getSession(event: TEvent): Promise<TSession | null>;
+	getRole(
+		session: TSession | null,
+		event: TEvent
+	): string | null | undefined;
+	getAuth?(pageData: PageGraphqlData, event: TEvent): GqlAuth;
+	/** Private API origin or same-origin `/graphql`; defaults to `/graphql`. */
+	getUrl?(event: TEvent): string;
+	/** Variables for routed operations that do not accept `{}`. */
+	variables?: DistributedRouteVariables<TEvent>;
+}>;
+
+export type DistributedSvelteKitServer<TEvent> = Readonly<{
+	load(event: TEvent): Promise<SveltekitDistributedPageData & {
+		gqlError: string | null;
+	}>;
+}>;
+
+/**
+ * One app-level root layout loader for every compiler-discovered `@load`
+ * operation. Each invocation creates a fresh replica and never shares SSR data
+ * across requests.
+ */
+export function createDistributedSvelteKitServer<
+	TSession extends NonNullable<PageGraphqlData['session']>,
+	TEvent extends SveltekitServerLoadEventLike = SveltekitServerLoadEventLike
+>(
+	options: CreateDistributedSvelteKitServerOptions<TSession, TEvent>
+): DistributedSvelteKitServer<TEvent> {
+	const routes = validateRoutes(options.routes);
+	return Object.freeze({
+		async load(event: TEvent) {
+			const session = await options.getSession(event);
+			const accessToken = session?.accessToken ?? null;
+			const engineRole = options.getRole(session, event) ?? null;
+			const pageData: PageGraphqlData = {
+				session,
+				accessToken,
+				engineRole
+			};
+			const auth =
+				options.getAuth?.(pageData, event) ?? authFromPageData(pageData);
+			const routeId = routeIdentity(event);
+			const selected = routes.filter(({ plan }) => plan.route === routeId);
+			if (selected.length === 0) {
+				return {
+					...pageData,
+					gqlError: null
+				};
+			}
+
+			const fetchImpl = event.fetch;
+			const transport = createReplicaGraphqlTransport({
+				getUrl: () => options.getUrl?.(event) ?? '/graphql',
+				getAuth: () => auth,
+				...(fetchImpl === undefined ? {} : { fetch: fetchImpl })
+			});
+			const replica = createDistributedReplica({ transport });
+			const watches: Array<{
+				operation: string;
+				artifact: ReplicaOperationArtifact<unknown, GraphqlVariables>;
+				variables: GraphqlVariables;
+				watch: ReplicaWatch<unknown>;
+			}> = [];
+			try {
+				for (const binding of selected) {
+					let variables: GraphqlVariables;
+					try {
+						variables =
+							(await options.variables?.[binding.plan.operation]?.(event)) ??
+							{};
+						const watch = replica.watch(
+							binding.artifact,
+							variables,
+							{ live: false }
+						);
+						watches.push({
+							operation: binding.plan.operation,
+							artifact: binding.artifact,
+							variables,
+							watch
+						});
+					} catch (error) {
+						if (options.variables?.[binding.plan.operation] === undefined) {
+							throw new Error(
+								`Distributed @load operation \`${binding.plan.operation}\` needs route variables; configure variables.${binding.plan.operation}(event) in createDistributedSvelteKitServer`,
+								{ cause: error }
+							);
+						}
+						throw error;
+					}
+				}
+				await Promise.all(watches.map(({ watch }) => watch.refresh()));
+				const errors = watches.flatMap(({ watch }) => watch.get().errors);
+				for (const { artifact, variables, watch } of watches) {
+					// Preserve exact rendered-operation reachability after the
+					// temporary watch is released.
+					replica.read(artifact, variables);
+					watch.destroy();
+				}
+				const transfer =
+					replica.scope === undefined
+						? undefined
+						: hydrationTransfer(
+								replica.dehydrate(),
+								selected.map(({ plan }) => plan.operation)
+							);
+				return {
+					...pageData,
+					...(transfer === undefined
+						? {}
+						: {
+								distributed: transfer.hydration,
+								distributedAuthority: transfer.authority
+							}),
+					gqlError:
+						errors[0]?.message ??
+						(transfer === undefined
+							? 'Distributed GraphQL response did not establish an authoritative cache scope'
+							: null)
+				};
+			} finally {
+				for (const { watch } of watches) watch.destroy();
+			}
+		}
+	});
+}
+
+/**
+ * Explicit one-line fallback when the compiler cannot discover route ownership.
+ *
+ * Prefer co-locating `+page.graphql`; the compiler diagnostic includes the
+ * equivalent `--route Operation=/route-id` registration.
+ */
+export function registerDistributedRoute<
+	TData,
+	TVariables extends GraphqlVariables
+>(
+	route: string,
+	operation: string,
+	artifact: ReplicaOperationArtifact<TData, TVariables>
+): DistributedRouteOperation {
+	return Object.freeze({
+		plan: Object.freeze({
+			operation: nonEmpty(operation, 'operation'),
+			route: normalizeRoute(route),
+			discovery: 'explicit' as const
+		}),
+		artifact: artifact as ReplicaOperationArtifact<unknown, GraphqlVariables>
+	});
+}
+
+function hydrationTransfer(
+	state: ReplicaDehydratedState,
+	operations: readonly string[]
+): Readonly<{
+	hydration: SveltekitReplicaHydration;
+	authority: SveltekitReplicaAuthority;
+}> {
+	return Object.freeze({
+		hydration: Object.freeze({
+			version: 1,
+			state,
+			operations: Object.freeze([...operations])
+		}),
+		authority: Object.freeze({
+			version: 1,
+			scope: state.scope
+		})
+	});
+}
+
+function validateRoutes(
+	value: readonly DistributedRouteOperation[]
+): readonly DistributedRouteOperation[] {
+	if (!Array.isArray(value)) {
+		throw new TypeError(
+			'createDistributedSvelteKitServer requires generated DISTRIBUTED_ROUTE_OPERATIONS'
+		);
+	}
+	const identities = new Set<string>();
+	return Object.freeze(
+		value.map((binding, index) => {
+			if (
+				binding === null ||
+				typeof binding !== 'object' ||
+				binding.plan === null ||
+				typeof binding.plan !== 'object' ||
+				binding.artifact === null ||
+				typeof binding.artifact !== 'object'
+			) {
+				throw new TypeError(`invalid Distributed route binding at index ${index}`);
+			}
+			const operation = nonEmpty(binding.plan.operation, 'route operation');
+			const route = normalizeRoute(binding.plan.route);
+			if (binding.artifact.id.length === 0) {
+				throw new TypeError(`invalid Distributed route artifact for ${operation}`);
+			}
+			const identity = `${route}\u0000${operation}`;
+			if (identities.has(identity)) {
+				throw new TypeError(
+					`duplicate Distributed route operation ${operation} at ${route}`
+				);
+			}
+			identities.add(identity);
+			return Object.freeze({
+				plan: Object.freeze({
+					...binding.plan,
+					operation,
+					route
+				}),
+				artifact: binding.artifact
+			});
+		})
+	);
+}
+
+function routeIdentity(event: SveltekitServerLoadEventLike): string {
+	const route = event.route?.id;
+	if (typeof route === 'string' && route.length > 0) return normalizeRoute(route);
+	if (event.url !== undefined) return normalizeRoute(event.url.pathname);
+	throw new Error(
+		'Distributed SvelteKit route loading requires event.route.id or event.url.pathname'
+	);
+}
+
+function normalizeRoute(value: string): string {
+	const route = nonEmpty(value, 'route');
+	if (!route.startsWith('/')) {
+		throw new TypeError('Distributed route must start with /');
+	}
+	if (route.length === 1) return route;
+	return route.replace(/\/+$/, '');
+}
+
+function nonEmpty(value: unknown, label: string): string {
+	if (typeof value !== 'string' || value.trim().length === 0) {
+		throw new TypeError(`Distributed ${label} must be a non-empty string`);
+	}
+	return value.trim();
+}
diff --git a/js/src/sveltekit/vite.ts b/js/src/sveltekit/vite.ts
new file mode 100644
index 00000000..f28ca5da
--- /dev/null
+++ b/js/src/sveltekit/vite.ts
@@ -0,0 +1,1296 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import {
+	existsSync,
+	lstatSync,
+	realpathSync
+} from 'node:fs';
+import {
+	cp,
+	lstat,
+	mkdir,
+	mkdtemp,
+	open,
+	readFile,
+	realpath,
+	rename,
+	rm,
+	unlink,
+	writeFile
+} from 'node:fs/promises';
+import {
+	basename,
+	dirname,
+	isAbsolute,
+	join,
+	relative,
+	resolve,
+	sep
+} from 'node:path';
+import { isMainThread } from 'node:worker_threads';
+
+const GENERATED_SVELTEKIT_MODULE = 'sveltekit.ts';
+const MAX_COMMAND_OUTPUT_BYTES = 16 * 1024 * 1024;
+const MODULE_NAME = /^\$distributed(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/;
+const COMPILER_LOCK = join('.svelte-kit', 'distributed', 'compiler.lock');
+const COMPILER_COORDINATORS = Symbol.for(
+	'@hops-ops/distributed/sveltekit/compiler-coordinators/v1'
+);
+
+export type DistributedGraphqlProxyOptions = {
+	/** Absolute Distributed API origin, for example `http://127.0.0.1:8791`. */
+	target: string;
+	/** Proxy key. Defaults to `/graphql` and includes its `/ws` child. */
+	path?: string;
+};
+
+/** Vite proxy config for GraphQL HTTP and WebSocket traffic. */
+export function distributedGraphqlProxy(
+	options: DistributedGraphqlProxyOptions | string
+): Record<string, { target: string; changeOrigin: true; ws: true }> {
+	const target = (
+		typeof options === 'string' ? options : options.target
+	)
+		.trim()
+		.replace(/\/$/, '');
+	const path =
+		typeof options === 'string' ? '/graphql' : (options.path ?? '/graphql');
+	if (!/^https?:\/\//.test(target)) {
+		throw new Error(
+			'distributedGraphqlProxy target must be an absolute http(s) URL'
+		);
+	}
+	if (!path.startsWith('/')) {
+		throw new Error('distributedGraphqlProxy path must start with /');
+	}
+	return { [path]: { target, changeOrigin: true, ws: true } };
+}
+
+export type DistributedSvelteKitManifestSource =
+	| string
+	| Readonly<{
+			/**
+			 * Arguments passed to the configured dctl command. The first value
+			 * must be `client-manifest`; stdout becomes ephemeral compiler input.
+			 */
+			args: readonly string[];
+	  }>;
+
+export type DistributedSvelteKitClientCompiler = Readonly<{
+	/** `$distributed` or an explicit elevated entrypoint such as `$distributed/admin`. */
+	module: string;
+	/** Existing manifest path, or canonical `dctl client-manifest` argv. */
+	manifest: DistributedSvelteKitManifestSource;
+	/** Verify exactly one concrete role. Mutually exclusive with `surface`. */
+	role?: string;
+	/** Verify exactly one Rust-declared application surface. */
+	surface?: string;
+	/** GraphQL globs passed verbatim as repeated `dctl client --documents`. */
+	documents: readonly string[];
+	/** Explicit `OPERATION=/route` fallbacks. */
+	routes?: readonly string[];
+	/** Compiler-owned artifact directory, relative to `cwd` by default. */
+	out: string;
+}>;
+
+export type DistributedSvelteKitViteOptions = Readonly<{
+	/** Project root used for dctl cwd, document globs, and output containment. */
+	cwd?: string;
+	/** Executable invoked without a shell. Defaults to `dctl`. */
+	command?: string;
+	/** Prefix argv, e.g. `cargo run ... --`; never interpreted by a shell. */
+	commandArgs?: readonly string[];
+	clients: readonly DistributedSvelteKitClientCompiler[];
+}>;
+
+type ResolvedClient = Readonly<{
+	module: string;
+	manifest: DistributedSvelteKitManifestSource;
+	selector: readonly ['--role' | '--surface', string];
+	documents: readonly string[];
+	routes: readonly string[];
+	out: string;
+	entry: string;
+	watchRoots: readonly string[];
+}>;
+
+type ResolvedIntegration = Readonly<{
+	cwd: string;
+	command: string;
+	commandArgs: readonly string[];
+	clients: readonly ResolvedClient[];
+}>;
+
+type CompilerCoordinator = {
+	path: string;
+	references: number;
+	ready: Promise<void>;
+	tail: Promise<void>;
+	startupRuns: Map<string, Promise<void>>;
+	closing?: Promise<void>;
+};
+
+type CompilerLockLease = {
+	coordinator: CompilerCoordinator;
+	released: boolean;
+};
+
+type ViteWebSocketLike = Readonly<{
+	send(payload: unknown): void;
+}>;
+
+type ViteModuleGraphLike = Readonly<{
+	getModuleById(id: string): unknown;
+	invalidateModule(module: unknown): void;
+}>;
+
+type ViteServerLike = Readonly<{
+	watcher: Readonly<{ add(paths: string | readonly string[]): void }>;
+	ws: ViteWebSocketLike;
+	moduleGraph: ViteModuleGraphLike;
+	httpServer?:
+		| Readonly<{
+				once(event: 'close', listener: () => void): void;
+		  }>
+		| null;
+}>;
+
+type ViteHotContextLike = Readonly<{
+	file: string;
+	server: ViteServerLike;
+}>;
+
+type RollupWatchContextLike = Readonly<{
+	addWatchFile(path: string): void;
+}>;
+
+/** Minimal structural Vite plugin type; avoids making Vite a runtime dependency. */
+export type DistributedSvelteKitVitePlugin = Readonly<{
+	name: string;
+	enforce: 'pre';
+	configResolved(config: Readonly<{ root: string }>): Promise<void>;
+	configureServer(server: ViteServerLike): void;
+	buildStart(this: RollupWatchContextLike): void;
+	resolveId(source: string): string | undefined;
+	load(id: string): string | undefined;
+	handleHotUpdate(context: ViteHotContextLike): Promise<never[] | undefined>;
+	watchChange(id: string): Promise<void>;
+	closeBundle(): Promise<void>;
+}>;
+
+/** Generate every configured surface through the same transaction used by Vite. */
+export async function generateDistributedSvelteKit(
+	options: DistributedSvelteKitViteOptions
+): Promise<void> {
+	await runCompilerOnce(options, 'generate');
+}
+
+/** Check every configured surface through canonical `dctl client --check`; never write. */
+export async function checkDistributedSvelteKit(
+	options: DistributedSvelteKitViteOptions
+): Promise<void> {
+	await runCompilerOnce(options, 'check');
+}
+
+/**
+ * Compiler-watching Vite integration for one or more authorization surfaces.
+ *
+ * Every run stages every surface first, then swaps the complete generated
+ * trees as one rollback-capable transaction. Child processes are serialized,
+ * coalesced, abortable, and always invoked without a shell.
+ */
+export function distributedSvelteKit(
+	options: DistributedSvelteKitViteOptions
+): DistributedSvelteKitVitePlugin {
+	let resolved: ResolvedIntegration | undefined;
+	let dirty = false;
+	let running: Promise<void> | undefined;
+	let completedGeneration = 0;
+	let reloadedGeneration = 0;
+	let stopped = false;
+	const children = new Set<ChildProcess>();
+	const cancellation = new AbortController();
+	let lock: CompilerLockLease | undefined;
+
+	const stop = async (): Promise<void> => {
+		if (stopped) return;
+		stopped = true;
+		dirty = false;
+		cancellation.abort();
+		for (const child of children) killChild(child, 'SIGTERM');
+		const force = setTimeout(() => {
+			for (const child of children) killChild(child, 'SIGKILL');
+		}, 1_500);
+		force.unref();
+		await Promise.race([
+			running?.catch(() => undefined) ?? Promise.resolve(),
+			new Promise<void>((resolvePromise) => {
+				const bounded = setTimeout(resolvePromise, 3_000);
+				bounded.unref();
+			})
+		]);
+		clearTimeout(force);
+		if (lock !== undefined) {
+			await releaseCompilerLock(lock);
+			lock = undefined;
+		}
+	};
+
+	const compile = (reason: string, startup = false): Promise<void> => {
+		if (stopped) {
+			return Promise.reject(
+				new Error(`Distributed SvelteKit compiler is closed (${reason})`)
+			);
+		}
+		dirty = true;
+		if (running !== undefined) return running;
+		running = (async () => {
+			let startupPending = startup;
+			while (dirty && !stopped) {
+				dirty = false;
+				const lease = requireCompilerLock(lock);
+				const integration = requireResolved(resolved);
+				const operation = () =>
+					compileTransaction(integration, children, cancellation.signal);
+				await (startupPending
+					? withCompilerStartup(lease, integration, operation)
+					: withCompilerLock(lease, operation));
+				startupPending = false;
+			}
+			completedGeneration += 1;
+		})().finally(() => {
+			running = undefined;
+		});
+		return running;
+	};
+
+	return {
+		name: '@hops-ops/distributed:sveltekit',
+		enforce: 'pre',
+		async configResolved(config): Promise<void> {
+			if (resolved !== undefined) {
+				throw new Error(
+					'Distributed SvelteKit Vite plugin was configured more than once'
+				);
+			}
+			resolved = resolveIntegration(options, options.cwd ?? config.root);
+			await validateResolvedPaths(resolved);
+			/*
+			 * SvelteKit post-build analysis loads Vite config in an isolated
+			 * worker marked with SVELTEKIT_FORK. That pass reads framework
+			 * configuration only; running the compiler there would contend with
+			 * the owning build's physical project lock and duplicate generation.
+			 */
+			if (!isMainThread && process.env.SVELTEKIT_FORK === 'true') return;
+			lock = await acquireCompilerLock(resolved.cwd);
+			try {
+				await compile('Vite startup', true);
+			} catch (error) {
+				await releaseCompilerLock(lock);
+				lock = undefined;
+				throw error;
+			}
+		},
+		configureServer(server): void {
+			const integration = requireResolved(resolved);
+			const roots = integration.clients.flatMap((client) => client.watchRoots);
+			if (roots.length > 0) server.watcher.add(roots);
+			server.httpServer?.once('close', () => {
+				void stop();
+			});
+		},
+		buildStart(): void {
+			const integration = requireResolved(resolved);
+			for (const client of integration.clients) {
+				for (const root of client.watchRoots) this.addWatchFile(root);
+			}
+		},
+		resolveId(source): string | undefined {
+			const client = resolved?.clients.find(
+				(candidate) => candidate.module === source
+			);
+			return client === undefined ? undefined : virtualId(client.module);
+		},
+		load(id): string | undefined {
+			const client = resolved?.clients.find(
+				(candidate) => virtualId(candidate.module) === id
+			);
+			if (client === undefined) return undefined;
+			return `export * from ${JSON.stringify(portablePath(client.entry))};\n`;
+		},
+		async handleHotUpdate(context): Promise<never[] | undefined> {
+			const integration = requireResolved(resolved);
+			if (!isGraphqlInput(context.file, integration)) return undefined;
+			try {
+				await compile(`GraphQL change ${context.file}`);
+			} catch (error) {
+				context.server.ws.send({
+					type: 'error',
+					err: viteError(error)
+				});
+				throw error;
+			}
+			if (completedGeneration <= reloadedGeneration) return [];
+			for (const client of integration.clients) {
+				const module = context.server.moduleGraph.getModuleById(
+					virtualId(client.module)
+				);
+				if (module !== undefined) {
+					context.server.moduleGraph.invalidateModule(module);
+				}
+			}
+			context.server.ws.send({ type: 'full-reload', path: '*' });
+			reloadedGeneration = completedGeneration;
+			return [];
+		},
+		async watchChange(id): Promise<void> {
+			const integration = requireResolved(resolved);
+			if (isGraphqlInput(id, integration)) {
+				await compile(`GraphQL watch change ${id}`);
+			}
+		},
+		closeBundle: stop
+	};
+}
+
+async function runCompilerOnce(
+	options: DistributedSvelteKitViteOptions,
+	mode: 'generate' | 'check'
+): Promise<void> {
+	const integration = resolveIntegration(
+		options,
+		options.cwd ?? process.cwd()
+	);
+	await validateResolvedPaths(integration);
+	const lock = await acquireCompilerLock(integration.cwd);
+	const children = new Set<ChildProcess>();
+	const cancellation = new AbortController();
+	const cancel = (): void => {
+		cancellation.abort();
+		for (const child of children) killChild(child, 'SIGTERM');
+	};
+	process.once('SIGINT', cancel);
+	process.once('SIGTERM', cancel);
+	try {
+		await withCompilerLock(lock, () =>
+			mode === 'generate'
+				? compileTransaction(integration, children, cancellation.signal)
+				: checkTransaction(integration, children, cancellation.signal)
+		);
+	} finally {
+		process.removeListener('SIGINT', cancel);
+		process.removeListener('SIGTERM', cancel);
+		for (const child of children) killChild(child, 'SIGKILL');
+		await releaseCompilerLock(lock);
+	}
+}
+
+/**
+ * SvelteKit language-tool aliases for the exact files used by Vite resolution.
+ *
+ * Keep this alongside the Vite plugin in the Node-only export. It performs no
+ * generation and is safe to call from `svelte.config.js`.
+ */
+export function distributedSvelteKitAliases(
+	options: Pick<DistributedSvelteKitViteOptions, 'cwd' | 'clients'>
+): Readonly<Record<string, string>> {
+	const integration = resolveIntegration(
+		{ ...options, command: 'dctl', commandArgs: [] },
+		options.cwd ?? process.cwd()
+	);
+	validateResolvedPathsSync(integration);
+	return Object.freeze(
+		Object.fromEntries(
+			[...integration.clients]
+				.sort(
+					(left, right) =>
+						right.module.length - left.module.length ||
+						left.module.localeCompare(right.module)
+				)
+				.map((client) => [client.module, client.entry])
+		)
+	);
+}
+
+function resolveIntegration(
+	options: DistributedSvelteKitViteOptions,
+	fallbackCwd: string
+): ResolvedIntegration {
+	if (options === null || typeof options !== 'object') {
+		throw new TypeError('distributedSvelteKit requires configuration');
+	}
+	const cwd = resolve(options.cwd ?? fallbackCwd);
+	const command = (options.command ?? 'dctl').trim();
+	if (command.length === 0) {
+		throw new TypeError('Distributed SvelteKit command must not be empty');
+	}
+	if (!Array.isArray(options.clients) || options.clients.length === 0) {
+		throw new TypeError(
+			'Distributed SvelteKit requires at least one client surface'
+		);
+	}
+	const modules = new Set<string>();
+	const outputs: string[] = [];
+	const clients = options.clients.map((client, index): ResolvedClient => {
+		if (client === null || typeof client !== 'object') {
+			throw new TypeError(`Distributed client[${index}] must be an object`);
+		}
+		if (!MODULE_NAME.test(client.module)) {
+			throw new TypeError(
+				`Distributed client module \`${client.module}\` must be $distributed or a safe $distributed/<entrypoint>`
+			);
+		}
+		if (modules.has(client.module)) {
+			throw new TypeError(
+				`duplicate Distributed client module \`${client.module}\``
+			);
+		}
+		modules.add(client.module);
+		const selector =
+			client.role !== undefined && client.surface === undefined
+				? (['--role', nonempty(client.role, `${client.module} role`)] as const)
+				: client.surface !== undefined && client.role === undefined
+					? ([
+							'--surface',
+							nonempty(client.surface, `${client.module} surface`)
+						] as const)
+					: undefined;
+		if (selector === undefined) {
+			throw new TypeError(
+				`Distributed client \`${client.module}\` requires exactly one of role or surface`
+			);
+		}
+		if (
+			!Array.isArray(client.documents) ||
+			client.documents.length === 0
+		) {
+			throw new TypeError(
+				`Distributed client \`${client.module}\` requires at least one GraphQL document glob`
+			);
+		}
+		const documents = client.documents.map((document: string, documentIndex: number) =>
+			nonempty(
+				document,
+				`${client.module} documents[${documentIndex}]`
+			)
+		);
+		const routes = (client.routes ?? []).map((route: string, routeIndex: number) =>
+			nonempty(route, `${client.module} routes[${routeIndex}]`)
+		);
+		validateManifestSource(client.module, client.manifest);
+		const out = containedPath(
+			cwd,
+			client.out,
+			`${client.module} generated output`
+		);
+		if (out === cwd) {
+			throw new TypeError(
+				`Distributed client \`${client.module}\` cannot use the project root as generated output`
+			);
+		}
+		for (const existing of outputs) {
+			if (isWithin(existing, out) || isWithin(out, existing)) {
+				throw new TypeError(
+					`Distributed client outputs must not overlap: \`${existing}\` and \`${out}\``
+				);
+			}
+		}
+		outputs.push(out);
+		return Object.freeze({
+			module: client.module,
+			manifest: client.manifest,
+			selector,
+			documents: Object.freeze(documents),
+			routes: Object.freeze(routes),
+			out,
+			entry: join(out, GENERATED_SVELTEKIT_MODULE),
+			watchRoots: Object.freeze(documentWatchRoots(cwd, documents, out))
+		});
+	});
+	return Object.freeze({
+		cwd,
+		command,
+		commandArgs: Object.freeze(
+			(options.commandArgs ?? []).map((argument, index) => {
+				if (typeof argument !== 'string') {
+					throw new TypeError(
+						`Distributed commandArgs[${index}] must be a string`
+					);
+				}
+				return argument;
+			})
+		),
+		clients: Object.freeze(clients)
+	});
+}
+
+function validateManifestSource(
+	module: string,
+	source: DistributedSvelteKitManifestSource
+): void {
+	if (typeof source === 'string') {
+		nonempty(source, `${module} manifest path`);
+		return;
+	}
+	if (
+		source === null ||
+		typeof source !== 'object' ||
+		!Array.isArray(source.args) ||
+		source.args.length === 0 ||
+		source.args[0] !== 'client-manifest' ||
+		source.args.some((argument) => typeof argument !== 'string')
+	) {
+		throw new TypeError(
+			`Distributed client \`${module}\` manifest args must begin with client-manifest`
+		);
+	}
+}
+
+function nonempty(value: unknown, label: string): string {
+	if (typeof value !== 'string' || value.trim().length === 0) {
+		throw new TypeError(`${label} must be a non-empty string`);
+	}
+	return value;
+}
+
+function containedPath(root: string, value: string, label: string): string {
+	const target = resolve(root, nonempty(value, label));
+	if (!isWithin(root, target)) {
+		throw new TypeError(`${label} must stay within project root ${root}`);
+	}
+	return target;
+}
+
+function isWithin(root: string, target: string): boolean {
+	const rel = relative(root, target);
+	return (
+		rel === '' ||
+		(!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel))
+	);
+}
+
+function documentWatchRoots(
+	cwd: string,
+	documents: readonly string[],
+	out: string
+): string[] {
+	const roots = new Set<string>();
+	for (const pattern of documents) {
+		const normalized = pattern.replaceAll('\\', '/');
+		const wildcard = normalized.search(/[*?[\]{}]/);
+		const prefix = wildcard === -1 ? normalized : normalized.slice(0, wildcard);
+		const base = prefix.endsWith('/')
+			? prefix.slice(0, -1)
+			: dirname(prefix);
+		const watch = resolve(cwd, base === '.' || base.length === 0 ? '.' : base);
+		if (!isWithin(cwd, watch)) {
+			throw new TypeError(
+				`Distributed GraphQL document glob \`${pattern}\` escapes project root ${cwd}`
+			);
+		}
+		if (!isWithin(out, watch)) roots.add(watch);
+	}
+	return [...roots].sort();
+}
+
+function isGraphqlInput(
+	file: string,
+	integration: ResolvedIntegration
+): boolean {
+	const absolute = resolve(integration.cwd, file);
+	if (
+		(!absolute.endsWith('.graphql') && !absolute.endsWith('.gql')) ||
+		!isWithin(integration.cwd, absolute)
+	) {
+		return false;
+	}
+	if (
+		integration.clients.some((client) => isWithin(client.out, absolute))
+	) {
+		return false;
+	}
+	return integration.clients.some((client) =>
+		client.watchRoots.some((root) => isWithin(root, absolute))
+	);
+}
+
+async function compileTransaction(
+	integration: ResolvedIntegration,
+	children: Set<ChildProcess>,
+	signal: AbortSignal
+): Promise<void> {
+	throwIfAborted(signal);
+	await validateResolvedPaths(integration);
+	const transaction = await mkdtemp(
+		join(integration.cwd, '.distributed-sveltekit-')
+	);
+	const staged: Array<{
+		client: ResolvedClient;
+		output: string;
+		backup: string;
+		hadOutput: boolean;
+	}> = [];
+	try {
+		for (const [index, client] of integration.clients.entries()) {
+			throwIfAborted(signal);
+			const manifest = await materializeManifest(
+				integration,
+				client,
+				transaction,
+				index,
+				children,
+				signal
+			);
+			const output = join(transaction, `output-${index}`);
+			let hadOutput = false;
+			try {
+				const metadata = await lstat(client.out);
+				if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+					throw new Error(
+						`generated output ${client.out} must be a real directory`
+					);
+				}
+				hadOutput = true;
+				await cp(client.out, output, {
+					recursive: true,
+					errorOnExist: true,
+					force: false,
+					dereference: false
+				});
+			} catch (error) {
+				if (!isMissing(error)) throw error;
+			}
+			const args = [
+				'client',
+				'--manifest',
+				manifest,
+				client.selector[0],
+				client.selector[1],
+				...client.documents.flatMap((document) => [
+					'--documents',
+					document
+				]),
+				...client.routes.flatMap((route) => ['--route', route]),
+				'--out',
+				output
+			];
+			await runCommand(integration, args, children, signal);
+			await validateGeneratedEntrypoint(integration.cwd, output, client.module);
+			staged.push({
+				client,
+				output,
+				backup: join(transaction, `backup-${index}`),
+				hadOutput
+			});
+		}
+		throwIfAborted(signal);
+		await commitOutputs(integration, staged, signal);
+	} finally {
+		await rm(transaction, { recursive: true, force: true });
+	}
+}
+
+async function checkTransaction(
+	integration: ResolvedIntegration,
+	children: Set<ChildProcess>,
+	signal: AbortSignal
+): Promise<void> {
+	throwIfAborted(signal);
+	await validateResolvedPaths(integration);
+	const transaction = await mkdtemp(
+		join(integration.cwd, '.distributed-sveltekit-check-')
+	);
+	try {
+		for (const [index, client] of integration.clients.entries()) {
+			throwIfAborted(signal);
+			const manifest = await materializeManifest(
+				integration,
+				client,
+				transaction,
+				index,
+				children,
+				signal
+			);
+			await runCommand(
+				integration,
+				[
+					'client',
+					'--check',
+					'--manifest',
+					manifest,
+					client.selector[0],
+					client.selector[1],
+					...client.documents.flatMap((document) => [
+						'--documents',
+						document
+					]),
+					...client.routes.flatMap((route) => ['--route', route]),
+					'--out',
+					client.out
+				],
+				children,
+				signal
+			);
+		}
+	} finally {
+		await rm(transaction, { recursive: true, force: true });
+	}
+}
+
+async function materializeManifest(
+	integration: ResolvedIntegration,
+	client: ResolvedClient,
+	transaction: string,
+	index: number,
+	children: Set<ChildProcess>,
+	signal: AbortSignal
+): Promise<string> {
+	throwIfAborted(signal);
+	if (typeof client.manifest === 'string') {
+		const path = containedPath(
+			integration.cwd,
+			client.manifest,
+			`${client.module} manifest`
+		);
+		const canonicalRoot = await realpath(integration.cwd);
+		const canonical = await realpath(path);
+		if (!isWithin(canonicalRoot, canonical)) {
+			throw new Error(
+				`Distributed manifest ${path} resolves outside project root ${integration.cwd}`
+			);
+		}
+		JSON.parse(await readFile(canonical, 'utf8')) as unknown;
+		return canonical;
+	}
+	const result = await runCommand(
+		integration,
+		[...client.manifest.args],
+		children,
+		signal
+	);
+	try {
+		JSON.parse(result.stdout) as unknown;
+	} catch (error) {
+		throw new Error(
+			`dctl client-manifest for ${client.module} did not emit valid JSON`,
+			{ cause: error }
+		);
+	}
+	const temporary = join(transaction, `manifest-${index}.json.tmp`);
+	const manifest = join(transaction, `manifest-${index}.json`);
+	await writeFile(temporary, result.stdout, {
+		encoding: 'utf8',
+		flag: 'wx'
+	});
+	await rename(temporary, manifest);
+	return manifest;
+}
+
+async function validateGeneratedEntrypoint(
+	cwd: string,
+	output: string,
+	module: string
+): Promise<void> {
+	const root = await realpath(cwd);
+	const entry = join(output, GENERATED_SVELTEKIT_MODULE);
+	const metadata = await lstat(entry);
+	if (metadata.isSymbolicLink() || !metadata.isFile()) {
+		throw new Error(
+			`dctl client for ${module} did not emit a regular ${GENERATED_SVELTEKIT_MODULE}`
+		);
+	}
+	const canonical = await realpath(entry);
+	if (!isWithin(root, canonical)) {
+		throw new Error(
+			`dctl client entrypoint ${canonical} escaped project root ${root}`
+		);
+	}
+}
+
+async function commitOutputs(
+	integration: ResolvedIntegration,
+	staged: readonly {
+		client: ResolvedClient;
+		output: string;
+		backup: string;
+		hadOutput: boolean;
+	}[],
+	signal: AbortSignal
+): Promise<void> {
+	throwIfAborted(signal);
+	await validateResolvedPaths(integration);
+	const applied: typeof staged[number][] = [];
+	try {
+		for (const item of staged) {
+			throwIfAborted(signal);
+			await mkdir(dirname(item.client.out), { recursive: true });
+			await validateNearestExistingParent(integration.cwd, item.client.out);
+			if (item.hadOutput) await rename(item.client.out, item.backup);
+			try {
+				await rename(item.output, item.client.out);
+			} catch (error) {
+				if (item.hadOutput) await rename(item.backup, item.client.out);
+				throw error;
+			}
+			applied.push(item);
+		}
+		throwIfAborted(signal);
+	} catch (error) {
+		for (const item of [...applied].reverse()) {
+			await rm(item.client.out, { recursive: true, force: true });
+			if (item.hadOutput) await rename(item.backup, item.client.out);
+		}
+		throw error;
+	}
+}
+
+async function runCommand(
+	integration: ResolvedIntegration,
+	args: readonly string[],
+	children: Set<ChildProcess>,
+	signal: AbortSignal
+): Promise<{ stdout: string; stderr: string }> {
+	throwIfAborted(signal);
+	const argv = [...integration.commandArgs, ...args];
+	return await new Promise((resolvePromise, rejectPromise) => {
+		const child = spawn(integration.command, argv, {
+			cwd: integration.cwd,
+			env: process.env,
+			shell: false,
+			detached: process.platform !== 'win32',
+			stdio: ['ignore', 'pipe', 'pipe']
+		});
+		children.add(child);
+		const stdout: Buffer[] = [];
+		const stderr: Buffer[] = [];
+		let bytes = 0;
+		let overflow = false;
+		let forceKill: ReturnType<typeof setTimeout> | undefined;
+		const cancel = (): void => {
+			killChild(child, 'SIGTERM');
+			forceKill ??= setTimeout(() => killChild(child, 'SIGKILL'), 1_500);
+			forceKill.unref();
+		};
+		signal.addEventListener('abort', cancel, { once: true });
+		const collect = (target: Buffer[]) => (chunk: Buffer | string): void => {
+			if (overflow) return;
+			const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			bytes += value.length;
+			if (bytes > MAX_COMMAND_OUTPUT_BYTES) {
+				overflow = true;
+				cancel();
+				return;
+			}
+			target.push(value);
+		};
+		child.stdout?.on('data', collect(stdout));
+		child.stderr?.on('data', collect(stderr));
+		child.once('error', (error) => {
+			children.delete(child);
+			signal.removeEventListener('abort', cancel);
+			if (forceKill !== undefined) clearTimeout(forceKill);
+			rejectPromise(
+				commandFailure(integration, argv, '', error.message)
+			);
+		});
+		child.once('close', (code, signal) => {
+			children.delete(child);
+			cancellationCleanup();
+			const out = Buffer.concat(stdout).toString('utf8');
+			const err = Buffer.concat(stderr).toString('utf8');
+			if (overflow) {
+				rejectPromise(
+					commandFailure(
+						integration,
+						argv,
+						err,
+						`output exceeded ${MAX_COMMAND_OUTPUT_BYTES} bytes`
+					)
+				);
+			} else if (code !== 0) {
+				rejectPromise(
+					commandFailure(
+						integration,
+						argv,
+						err,
+						`exit ${code ?? 'unknown'}${signal === null ? '' : ` (${signal})`}`
+					)
+				);
+			} else {
+				resolvePromise({ stdout: out, stderr: err });
+			}
+		});
+
+		function cancellationCleanup(): void {
+			signal.removeEventListener('abort', cancel);
+			if (forceKill !== undefined) clearTimeout(forceKill);
+		}
+	});
+}
+
+function commandFailure(
+	integration: ResolvedIntegration,
+	argv: readonly string[],
+	stderr: string,
+	summary: string
+): Error {
+	const renderedArgv = JSON.stringify([integration.command, ...argv]);
+	const details = [
+		`Distributed compiler command failed: ${summary}`,
+		`cwd: ${integration.cwd}`,
+		`argv: ${renderedArgv}`,
+		stderr.trim().length === 0 ? undefined : `stderr:\n${stderr.trim()}`
+	].filter((value): value is string => value !== undefined);
+	return new Error(details.join('\n'));
+}
+
+async function validateResolvedPaths(
+	integration: ResolvedIntegration
+): Promise<void> {
+	validateResolvedPathsSync(integration);
+}
+
+function validateResolvedPathsSync(integration: ResolvedIntegration): void {
+	const canonicalRoot = realpathSync(integration.cwd);
+	const physicalOutputs: Array<{ module: string; path: string }> = [];
+	for (const client of integration.clients) {
+		const output = plannedPhysicalPath(canonicalRoot, integration.cwd, client.out);
+		for (const existing of physicalOutputs) {
+			if (
+				physicalPathKey(output).startsWith(
+					`${physicalPathKey(existing.path)}${sep}`
+				) ||
+				physicalPathKey(existing.path).startsWith(
+					`${physicalPathKey(output)}${sep}`
+				) ||
+				physicalPathKey(existing.path) === physicalPathKey(output)
+			) {
+				throw new Error(
+					`Distributed client outputs physically overlap: ${existing.module} (${existing.path}) and ${client.module} (${output})`
+				);
+			}
+		}
+		physicalOutputs.push({ module: client.module, path: output });
+		for (const watchRoot of client.watchRoots) {
+			plannedPhysicalPath(canonicalRoot, integration.cwd, watchRoot);
+		}
+	}
+}
+
+function plannedPhysicalPath(
+	canonicalRoot: string,
+	lexicalRoot: string,
+	target: string
+): string {
+	const rel = relative(lexicalRoot, target);
+	let lexical = lexicalRoot;
+	if (rel !== '') {
+		for (const component of rel.split(sep)) {
+			lexical = join(lexical, component);
+			if (!existsSync(lexical)) break;
+			const metadata = lstatSync(lexical);
+			if (metadata.isSymbolicLink()) {
+				throw new Error(
+					`Distributed path ${target} contains symlink component ${lexical}`
+				);
+			}
+		}
+	}
+
+	let existing = target;
+	const suffix: string[] = [];
+	while (!existsSync(existing)) {
+		const parent = dirname(existing);
+		if (parent === existing) {
+			throw new Error(
+				`Distributed path ${target} has no existing parent within ${canonicalRoot}`
+			);
+		}
+		suffix.unshift(basename(existing));
+		existing = parent;
+	}
+	const canonicalExisting = realpathSync(existing);
+	if (!isWithin(canonicalRoot, canonicalExisting)) {
+		throw new Error(
+			`Distributed path ${target} resolves outside project root ${canonicalRoot}`
+		);
+	}
+	const planned = resolve(canonicalExisting, ...suffix);
+	if (!isWithin(canonicalRoot, planned)) {
+		throw new Error(
+			`Distributed path ${target} resolves outside project root ${canonicalRoot}`
+		);
+	}
+	return planned;
+}
+
+function physicalPathKey(path: string): string {
+	return process.platform === 'win32' || process.platform === 'darwin'
+		? path.toLocaleLowerCase('en-US')
+		: path;
+}
+
+async function validateNearestExistingParent(
+	root: string,
+	target: string
+): Promise<void> {
+	const canonicalRoot = realpathSync(root);
+	plannedPhysicalPath(canonicalRoot, root, target);
+}
+
+function compilerCoordinatorRegistry(): Map<string, CompilerCoordinator> {
+	const globalScope = globalThis as unknown as Record<symbol, unknown>;
+	const existing = globalScope[COMPILER_COORDINATORS];
+	if (existing instanceof Map) {
+		return existing as Map<string, CompilerCoordinator>;
+	}
+	const registry = new Map<string, CompilerCoordinator>();
+	globalScope[COMPILER_COORDINATORS] = registry;
+	return registry;
+}
+
+async function acquireCompilerLock(cwd: string): Promise<CompilerLockLease> {
+	const path = join(cwd, COMPILER_LOCK);
+	const registry = compilerCoordinatorRegistry();
+	for (;;) {
+		const existing = registry.get(path);
+		if (existing?.closing !== undefined) {
+			await existing.closing;
+			continue;
+		}
+		const coordinator =
+			existing ??
+			({
+				path,
+				references: 0,
+				ready: acquirePhysicalCompilerLock(cwd, path),
+				tail: Promise.resolve(),
+				startupRuns: new Map()
+			} satisfies CompilerCoordinator);
+		if (existing === undefined) registry.set(path, coordinator);
+		coordinator.references += 1;
+		try {
+			await coordinator.ready;
+			return { coordinator, released: false };
+		} catch (error) {
+			coordinator.references -= 1;
+			if (
+				coordinator.references === 0 &&
+				registry.get(path) === coordinator
+			) {
+				registry.delete(path);
+			}
+			throw error;
+		}
+	}
+}
+
+async function acquirePhysicalCompilerLock(
+	cwd: string,
+	path: string
+): Promise<void> {
+	await validateNearestExistingParent(cwd, dirname(path));
+	await mkdir(dirname(path), { recursive: true });
+	await validateNearestExistingParent(cwd, path);
+	for (let attempt = 0; attempt < 2; attempt += 1) {
+		try {
+			const handle = await open(path, 'wx', 0o600);
+			try {
+				await handle.writeFile(
+					`${JSON.stringify({ pid: process.pid, version: 1 })}\n`,
+					'utf8'
+				);
+			} finally {
+				await handle.close();
+			}
+			return;
+		} catch (error) {
+			if (!isAlreadyExists(error)) throw error;
+			let owner: unknown;
+			try {
+				owner = JSON.parse(await readFile(path, 'utf8')) as unknown;
+			} catch {
+				owner = undefined;
+			}
+			const pid =
+				owner !== null &&
+				typeof owner === 'object' &&
+				'pid' in owner &&
+				typeof owner.pid === 'number'
+					? owner.pid
+					: undefined;
+			if (pid !== undefined && processExists(pid)) {
+				throw new Error(
+					`Distributed SvelteKit compiler already owns ${cwd} (pid ${pid})`
+				);
+			}
+			await unlink(path).catch((unlinkError: unknown) => {
+				if (!isMissing(unlinkError)) throw unlinkError;
+			});
+		}
+	}
+	throw new Error(`could not acquire Distributed SvelteKit compiler lock ${path}`);
+}
+
+function withCompilerLock<T>(
+	lease: CompilerLockLease,
+	operation: () => Promise<T>
+): Promise<T> {
+	if (lease.released) {
+		return Promise.reject(
+			new Error('Distributed SvelteKit compiler lock lease is already released')
+		);
+	}
+	const coordinator = lease.coordinator;
+	const run = coordinator.tail.catch(() => undefined).then(operation);
+	coordinator.tail = run.then(
+		() => undefined,
+		() => undefined
+	);
+	return run;
+}
+
+function withCompilerStartup(
+	lease: CompilerLockLease,
+	integration: ResolvedIntegration,
+	operation: () => Promise<void>
+): Promise<void> {
+	if (lease.released) {
+		return Promise.reject(
+			new Error('Distributed SvelteKit compiler lock lease is already released')
+		);
+	}
+	const key = JSON.stringify(integration);
+	const coordinator = lease.coordinator;
+	const existing = coordinator.startupRuns.get(key);
+	if (existing !== undefined) return existing;
+	const run = withCompilerLock(lease, operation);
+	const cached = run.catch((error: unknown) => {
+		if (coordinator.startupRuns.get(key) === cached) {
+			coordinator.startupRuns.delete(key);
+		}
+		throw error;
+	});
+	coordinator.startupRuns.set(key, cached);
+	return cached;
+}
+
+function requireCompilerLock(
+	lease: CompilerLockLease | undefined
+): CompilerLockLease {
+	if (lease === undefined) {
+		throw new Error('Distributed SvelteKit compiler lock is not initialized');
+	}
+	return lease;
+}
+
+async function releaseCompilerLock(lease: CompilerLockLease): Promise<void> {
+	if (lease.released) return;
+	lease.released = true;
+	const coordinator = lease.coordinator;
+	await coordinator.tail.catch(() => undefined);
+	coordinator.references -= 1;
+	if (coordinator.references > 0) return;
+	if (coordinator.references < 0) {
+		throw new Error('Distributed SvelteKit compiler lock reference underflow');
+	}
+	const registry = compilerCoordinatorRegistry();
+	if (registry.get(coordinator.path) !== coordinator) return;
+	const closing = unlink(coordinator.path)
+		.catch((error: unknown) => {
+			if (!isMissing(error)) throw error;
+		})
+		.finally(() => {
+			if (registry.get(coordinator.path) === coordinator) {
+				registry.delete(coordinator.path);
+			}
+		});
+	coordinator.closing = closing;
+	await closing;
+}
+
+function processExists(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (
+			error !== null &&
+			typeof error === 'object' &&
+			'code' in error &&
+			error.code === 'EPERM'
+		);
+	}
+}
+
+function killChild(
+	child: ChildProcess,
+	signal: NodeJS.Signals
+): void {
+	if (child.pid === undefined) return;
+	if (process.platform !== 'win32') {
+		try {
+			process.kill(-child.pid, signal);
+			return;
+		} catch {
+			// The child may have exited or failed to become its own process group.
+		}
+	}
+	child.kill(signal);
+}
+
+function throwIfAborted(signal: AbortSignal): void {
+	if (!signal.aborted) return;
+	const error = new Error('Distributed SvelteKit compiler was cancelled');
+	error.name = 'AbortError';
+	throw error;
+}
+
+function isMissing(error: unknown): boolean {
+	return (
+		error !== null &&
+		typeof error === 'object' &&
+		'code' in error &&
+		error.code === 'ENOENT'
+	);
+}
+
+function isAlreadyExists(error: unknown): boolean {
+	return (
+		error !== null &&
+		typeof error === 'object' &&
+		'code' in error &&
+		error.code === 'EEXIST'
+	);
+}
+
+function requireResolved(
+	value: ResolvedIntegration | undefined
+): ResolvedIntegration {
+	if (value === undefined) {
+		throw new Error(
+			'Distributed SvelteKit Vite plugin has not received resolved config'
+		);
+	}
+	return value;
+}
+
+function virtualId(module: string): string {
+	return `\0@hops-ops/distributed:sveltekit:${module}`;
+}
+
+function portablePath(path: string): string {
+	return path.replaceAll('\\', '/');
+}
+
+function viteError(error: unknown): Readonly<{
+	message: string;
+	stack?: string;
+}> {
+	if (error instanceof Error) {
+		return {
+			message: error.message,
+			...(error.stack === undefined ? {} : { stack: error.stack })
+		};
+	}
+	return { message: String(error) };
+}
diff --git a/js/src/types.ts b/js/src/types.ts
new file mode 100644
index 00000000..ba84f311
--- /dev/null
+++ b/js/src/types.ts
@@ -0,0 +1,36 @@
+/** Shared GraphQL client types for browser and server runtimes. */
+import type { GraphqlResponseExtensions } from './protocol.js';
+
+/** Variables accepted by an untyped GraphQL operation. */
+export type GraphqlVariables = Record<string, unknown>;
+
+/** Standard source location attached to a GraphQL error. */
+export type GqlErrorLocation = {
+	line: number;
+	column: number;
+};
+
+/** GraphQL execution or transport error returned by the server. */
+export type GqlError = {
+	message: string;
+	locations?: GqlErrorLocation[];
+	path?: Array<string | number>;
+	extensions?: Record<string, unknown> & { code?: string };
+};
+
+/** Result returned by {@link requestGraphql}. */
+export type GqlResult<TData> = {
+	data?: TData;
+	errors?: GqlError[];
+	/** Validated GraphQL response extensions, including Distributed receipts. */
+	extensions?: GraphqlResponseExtensions;
+	status: number;
+};
+
+/** Authentication material understood by Distributed's GraphQL transports. */
+export type GqlAuth = {
+	accessToken?: string | null;
+	/** DevHeaders offline fallback only; ignored when an access token is present. */
+	userId?: string | null;
+	role?: string | null;
+};
diff --git a/js/src/websocket.ts b/js/src/websocket.ts
new file mode 100644
index 00000000..65c8c0ed
--- /dev/null
+++ b/js/src/websocket.ts
@@ -0,0 +1,291 @@
+/** Minimal `graphql-transport-ws` client with injectable browser primitives. */
+import {
+	applyWsDevHeaderParams,
+	wsConnectionInitPayload
+} from './auth-headers.js';
+import { documentToString, type GqlDocument } from './document.js';
+import {
+	DistributedProtocolError,
+	distributedLiveResumeExtensions,
+	parseGraphqlResponseExtensions,
+	type DistributedLiveCursor,
+	type GraphqlResponseExtensions
+} from './protocol.js';
+import type {
+	GqlAuth,
+	GqlError,
+	GraphqlVariables
+} from './types.js';
+
+/** Constructor accepted by the WebSocket transport (native or test implementation). */
+export type WebSocketConstructor = typeof globalThis.WebSocket;
+
+/** GraphQL execution payload delivered by a subscription. */
+export type GqlWsResult<TData = unknown> = {
+	data?: TData | null;
+	errors?: GqlError[];
+	/** Validated top-level GraphQL extensions for this live frame. */
+	extensions?: GraphqlResponseExtensions;
+};
+
+export type GqlWsHandlers<TData = unknown> = {
+	onNext: (result: GqlWsResult<TData>) => void;
+	onError?: (error: unknown) => void;
+	onComplete?: () => void;
+};
+
+export type SubscribeOptions<
+	TVariables extends GraphqlVariables = GraphqlVariables
+> = {
+	/** HTTP GraphQL URL used to derive the `.../ws` endpoint. */
+	httpUrl?: string;
+	/** Variables for the subscription operation. */
+	variables?: TVariables;
+	/**
+	 * Latest server-issued cursors for a generated live operation.
+	 * @internal Application code must not synthesize resume tokens.
+	 */
+	resume?: readonly DistributedLiveCursor[];
+	/**
+	 * Framework-owned GraphQL request extensions.
+	 * @internal Generated transports, not application code, supply this value.
+	 */
+	extensions?: Readonly<Record<string, unknown>>;
+	/** Override the runtime's global WebSocket constructor. */
+	webSocket?: WebSocketConstructor;
+};
+
+function browserLocation(): Location | undefined {
+	return typeof window === 'undefined' ? undefined : window.location;
+}
+
+/** Build a same-origin WebSocket URL in a browser, or retain the path on a server. */
+export function graphqlWsUrl(path = '/graphql/ws'): string {
+	const location = browserLocation();
+	if (!location) return path;
+
+	const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+	const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+	return `${protocol}//${location.host}${normalizedPath}`;
+}
+
+/** Map an HTTP GraphQL URL to its `graphql-transport-ws` endpoint. */
+export function httpUrlToWsUrl(httpUrl: string): string {
+	const location = browserLocation();
+	const base = location?.href ?? 'http://127.0.0.1/';
+
+	try {
+		const url = new URL(httpUrl, base);
+		const path = url.pathname.replace(/\/$/, '');
+		const wsPath = path.endsWith('/ws') ? path : `${path}/ws`;
+
+		if (httpUrl.startsWith('/')) {
+			return location
+				? graphqlWsUrl(wsPath)
+				: `ws://127.0.0.1${wsPath.startsWith('/') ? wsPath : `/${wsPath}`}`;
+		}
+
+		url.protocol = url.protocol === 'https:' || url.protocol === 'wss:' ? 'wss:' : 'ws:';
+		url.pathname = wsPath;
+		url.search = '';
+		url.hash = '';
+		return url.toString();
+	} catch {
+		return location ? graphqlWsUrl('/graphql/ws') : 'ws://127.0.0.1/graphql/ws';
+	}
+}
+
+/** Open one GraphQL subscription and return an idempotent unsubscribe function. */
+export function subscribe<
+	TData = unknown,
+	TVariables extends GraphqlVariables = GraphqlVariables
+>(
+	document: GqlDocument<TData, TVariables>,
+	auth: GqlAuth = {},
+	handlers: GqlWsHandlers<TData>,
+	options: SubscribeOptions<TVariables> = {}
+): () => void {
+	const WebSocketImpl = options.webSocket ?? globalThis.WebSocket;
+	if (typeof WebSocketImpl !== 'function') {
+		throw new Error(
+			'subscribe requires a WebSocket implementation in this runtime; pass { webSocket } in the options'
+		);
+	}
+
+	const query = documentToString(document);
+	const location = browserLocation();
+	const href = options.httpUrl
+		? httpUrlToWsUrl(options.httpUrl)
+		: graphqlWsUrl('/graphql/ws');
+	const url = new URL(href, location?.href ?? 'ws://127.0.0.1/');
+	applyWsDevHeaderParams(url, auth);
+
+	const socket = new WebSocketImpl(url.toString(), 'graphql-transport-ws');
+	const operationId = '1';
+	let closed = false;
+
+	const rejectProtocolFrame = (error: unknown) => {
+		handlers.onError?.(error);
+		if (closed) return;
+		closed = true;
+		if (socket.readyState === WebSocketImpl.OPEN) {
+			try {
+				socket.send(JSON.stringify({ type: 'complete', id: operationId }));
+			} catch {
+				// The protocol is already rejected; closing is the remaining fence.
+			}
+		}
+		socket.close();
+	};
+
+	socket.onopen = () => {
+		socket.send(
+			JSON.stringify({
+				type: 'connection_init',
+				payload: wsConnectionInitPayload(auth)
+			})
+		);
+	};
+
+	socket.onmessage = (event) => {
+		let message: { type: string; id?: string; payload?: unknown };
+		try {
+			message = JSON.parse(String(event.data)) as typeof message;
+		} catch {
+			return;
+		}
+
+		switch (message.type) {
+			case 'connection_ack':
+				const resumeExtensions =
+					options.resume === undefined || options.resume.length === 0
+						? undefined
+						: distributedLiveResumeExtensions(options.resume);
+				const extensions = mergeRequestExtensions(
+					options.extensions,
+					resumeExtensions
+				);
+				socket.send(
+					JSON.stringify({
+						type: 'subscribe',
+						id: operationId,
+						payload: {
+							query,
+							variables: options.variables ?? {},
+							...(extensions === undefined ? {} : { extensions })
+						}
+					})
+				);
+				break;
+			case 'next':
+				try {
+					handlers.onNext(parseNextPayload<TData>(message.payload));
+				} catch (error) {
+					rejectProtocolFrame(error);
+				}
+				break;
+			case 'error':
+				handlers.onError?.(message.payload ?? 'subscription error');
+				break;
+			case 'complete':
+				handlers.onComplete?.();
+				break;
+			case 'ping':
+				socket.send(JSON.stringify({ type: 'pong' }));
+				break;
+			case 'connection_error':
+				handlers.onError?.(message.payload ?? 'connection error');
+				break;
+			default:
+				break;
+		}
+	};
+
+	socket.onerror = (event) => handlers.onError?.(event);
+	socket.onclose = (event) => {
+		if (!closed && !event.wasClean) {
+			handlers.onError?.(
+				`WebSocket closed (${event.code}${event.reason ? `: ${event.reason}` : ''}) — check the GraphQL WebSocket endpoint`
+			);
+		}
+		if (!closed) handlers.onComplete?.();
+	};
+
+	return () => {
+		if (closed) return;
+		closed = true;
+		if (socket.readyState === WebSocketImpl.OPEN) {
+			try {
+				socket.send(JSON.stringify({ type: 'complete', id: operationId }));
+			} catch {
+				// The transport may have closed between the ready-state check and send.
+			}
+		}
+		socket.close();
+	};
+}
+
+function mergeRequestExtensions(
+	base: Readonly<Record<string, unknown>> | undefined,
+	resume: Readonly<Record<string, unknown>> | undefined
+): Readonly<Record<string, unknown>> | undefined {
+	if (base === undefined) return resume;
+	if (resume === undefined) return base;
+	const baseDistributed = requestExtensionRecord(
+		base.distributed,
+		'request.extensions.distributed'
+	);
+	const resumeDistributed = requestExtensionRecord(
+		resume.distributed,
+		'request.extensions.distributed'
+	);
+	for (const key of Object.keys(resumeDistributed)) {
+		if (Object.hasOwn(baseDistributed, key)) {
+			throw new DistributedProtocolError(
+				'DISTRIBUTED_PROTOCOL_INVALID',
+				`request.extensions.distributed.${key}`
+			);
+		}
+	}
+	return Object.freeze({
+		...base,
+		distributed: Object.freeze({
+			...baseDistributed,
+			...resumeDistributed
+		})
+	});
+}
+
+function requestExtensionRecord(
+	value: unknown,
+	path: string
+): Readonly<Record<string, unknown>> {
+	if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+		throw new DistributedProtocolError(
+			'DISTRIBUTED_PROTOCOL_INVALID',
+			path
+		);
+	}
+	return value as Readonly<Record<string, unknown>>;
+}
+
+function parseNextPayload<TData>(value: unknown): GqlWsResult<TData> {
+	if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+		throw new DistributedProtocolError(
+			'DISTRIBUTED_PROTOCOL_INVALID',
+			'websocket.next.payload'
+		);
+	}
+	const payload = value as Record<string, unknown>;
+	if (payload.errors !== undefined && !Array.isArray(payload.errors)) {
+		throw new DistributedProtocolError(
+			'DISTRIBUTED_PROTOCOL_INVALID',
+			'websocket.next.payload.errors'
+		);
+	}
+	const extensions = parseGraphqlResponseExtensions(payload.extensions);
+	return {
+		...(payload as GqlWsResult<TData>),
+		...(extensions === undefined ? {} : { extensions })
+	};
+}
diff --git a/js/tests/cache-engine-conformance.test.mjs b/js/tests/cache-engine-conformance.test.mjs
new file mode 100644
index 00000000..b8075552
--- /dev/null
+++ b/js/tests/cache-engine-conformance.test.mjs
@@ -0,0 +1,1001 @@
+import assert from 'node:assert/strict';
+import { readFile, readdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { InMemoryCache } from '@apollo/client/cache';
+import { gql } from '@apollo/client';
+import {
+	CacheRevisionConflictError,
+	cacheIndexKey,
+	createCacheEngine
+} from '../dist/internal/cache-engine.js';
+
+const TODO = 'Todo:todo-1';
+const OTHER_TODO = 'Todo:todo-2';
+const USER = 'User:user-1';
+const OPEN = cacheIndexKey({ field: 'todos', arguments: { status: 'open', first: 20 } });
+const OWNED_OPEN = cacheIndexKey({
+	field: 'todos',
+	arguments: { status: 'open', owner: 'user-1', first: 20 }
+});
+const ALL = cacheIndexKey({ field: 'todos', arguments: { first: 20 } });
+const USER_TODOS = cacheIndexKey({ parent: USER, field: 'todos', arguments: { first: 20 } });
+
+function todoFields(reader) {
+	return reader.record(TODO)?.fields;
+}
+
+function todoAt(reader, indexKey) {
+	const index = reader.index(indexKey);
+	return index?.records.map((key) => reader.record(key)?.fields);
+}
+
+/** Generated-like response plan: aliases and fragments map to canonical fields. */
+function normalizeAliasedTodo(writer, payload, revision) {
+	writer.writeRecord({
+		key: `Todo:${payload.todoId}`,
+		revision,
+		fields: {
+			id: payload.todoId,
+			title: payload.headline,
+			status: payload.state,
+			description: payload.description
+		},
+		links: { owner: `User:${payload.ownerId}` }
+	});
+	writer.writeRecord({
+		key: `User:${payload.ownerId}`,
+		revision,
+		fields: { id: payload.ownerId, name: payload.ownerName },
+		links: { todos: [`Todo:${payload.todoId}`] }
+	});
+	writer.writeIndex({ key: OPEN, revision, records: [TODO], complete: true });
+	writer.writeIndex({ key: OWNED_OPEN, revision, records: [TODO], complete: true });
+	writer.writeIndex({ key: ALL, revision, records: [TODO], complete: true });
+	writer.writeIndex({ key: USER_TODOS, revision, records: [TODO], complete: true });
+}
+
+test('purpose-built engine normalizes sparse records, links, and exact indexes in one batch', () => {
+	const engine = createCacheEngine();
+	const notifications = new Map();
+	const watch = (name, selector) =>
+		engine.watch(selector, () => notifications.set(name, (notifications.get(name) ?? 0) + 1));
+
+	watch('by-pk', (reader) => reader.record(TODO));
+	watch('alias-fragment', (reader) => reader.record(TODO)?.fields.title);
+	watch('open', (reader) => todoAt(reader, OPEN));
+	watch('owned-open', (reader) => todoAt(reader, OWNED_OPEN));
+	watch('all', (reader) => todoAt(reader, ALL));
+	watch('relationship', (reader) => todoAt(reader, USER_TODOS));
+	watch('unrelated', (reader) => reader.record(OTHER_TODO));
+
+	engine.batch((writer) => {
+		normalizeAliasedTodo(
+			writer,
+			{
+				todoId: 'todo-1',
+				headline: 'original',
+				state: 'open',
+				description: null,
+				ownerId: 'user-1',
+				ownerName: 'Ada'
+			},
+			1
+		);
+	});
+
+	assert.deepEqual(Object.fromEntries(notifications), {
+		'by-pk': 1,
+		'alias-fragment': 1,
+		open: 1,
+		'owned-open': 1,
+		all: 1,
+		relationship: 1
+	});
+	const initial = engine.read((reader) => reader.record(TODO));
+	assert.equal(initial.fields.title, 'original');
+	assert.equal(initial.fields.description, null);
+	assert.equal(Object.hasOwn(initial.fields, 'description'), true);
+	assert.equal(Object.hasOwn(initial.fields, 'estimate'), false);
+	assert.equal(initial.links.owner, USER);
+
+	for (const key of notifications.keys()) notifications.set(key, 0);
+	engine.batch((writer) => {
+		// A partial fragment updates only fields it selected.
+		writer.writeRecord({ key: TODO, revision: 2, fields: { title: 'updated' } });
+	});
+
+	assert.deepEqual(Object.fromEntries(notifications), {
+		'by-pk': 1,
+		'alias-fragment': 1,
+		open: 1,
+		'owned-open': 1,
+		all: 1,
+		relationship: 1
+	});
+	const updated = engine.read((reader) => reader.record(TODO));
+	assert.equal(updated.fields.title, 'updated');
+	assert.equal(updated.fields.description, null);
+	assert.equal(Object.hasOwn(updated.fields, 'estimate'), false);
+});
+
+test('purpose-built engine keeps argument-sensitive roots distinct and batches watchers once', () => {
+	const engine = createCacheEngine();
+	const canonicalA = cacheIndexKey({
+		field: 'todos',
+		arguments: { where: { status: 'open', owner: 'one' }, first: 20 }
+	});
+	const canonicalB = cacheIndexKey({
+		field: 'todos',
+		arguments: { first: 20, where: { owner: 'one', status: 'open' } }
+	});
+	const closed = cacheIndexKey({
+		field: 'todos',
+		arguments: { first: 20, where: { owner: 'one', status: 'closed' } }
+	});
+	assert.equal(canonicalA, canonicalB);
+	assert.notEqual(canonicalA, closed);
+
+	let calls = 0;
+	engine.watch((reader) => todoAt(reader, canonicalA), () => calls++);
+	engine.batch((writer) => {
+		writer.writeRecord({ key: TODO, revision: 1, fields: { id: 'todo-1', status: 'open' } });
+		writer.writeIndex({ key: canonicalA, revision: 1, records: [TODO], complete: true });
+		writer.writeRecord({ key: TODO, revision: 2, fields: { title: 'batched' } });
+	});
+	assert.equal(calls, 1);
+	assert.equal(engine.read((reader) => reader.index(closed)), undefined);
+});
+
+test('tracked field dependencies skip selectors for unrelated record fields', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) =>
+		writer.writeRecord({
+			key: TODO,
+			revision: 1,
+			fields: { title: 'one', status: 'open', description: 'initial' }
+		})
+	);
+	let titleSelections = 0;
+	let statusSelections = 0;
+	engine.watch(
+		(reader) => {
+			titleSelections += 1;
+			const field = reader.field(TODO, 'title');
+			return field.present ? field.value : undefined;
+		},
+		() => undefined
+	);
+	engine.watch(
+		(reader) => {
+			statusSelections += 1;
+			const field = reader.field(TODO, 'status');
+			return field.present ? field.value : undefined;
+		},
+		() => undefined
+	);
+	titleSelections = 0;
+	statusSelections = 0;
+
+	engine.batch((writer) =>
+		writer.writeRecord({ key: TODO, revision: 2, fields: { description: 'unrelated' } })
+	);
+	assert.equal(titleSelections, 0);
+	assert.equal(statusSelections, 0);
+
+	engine.batch((writer) =>
+		writer.writeRecord({ key: TODO, revision: 3, fields: { title: 'two' } })
+	);
+	assert.equal(titleSelections, 1);
+	assert.equal(statusSelections, 0);
+});
+
+test('named optimistic layers survive acceptance and stale base responses', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) => {
+		writer.writeRecord({ key: TODO, revision: 4, fields: { status: 'open' } });
+	});
+	engine.createOptimisticLayer('complete-1', (writer) => {
+		writer.writeRecord({ key: TODO, fields: { status: 'completed-optimistic' } });
+	});
+	assert.equal(engine.markOptimisticLayerAccepted('complete-1'), true);
+	assert.equal(engine.optimisticLayerState('complete-1'), 'accepted');
+
+	engine.batch((writer) => {
+		assert.equal(
+			writer.writeRecord({ key: TODO, revision: 3, fields: { status: 'open-stale' } }),
+			false
+		);
+	});
+	assert.equal(engine.read((reader) => todoFields(reader).status), 'completed-optimistic');
+	assert.equal(engine.optimisticLayerState('complete-1'), 'accepted');
+});
+
+test('causal confirmation writes base and retires its layer atomically', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) => {
+		writer.writeRecord({ key: TODO, revision: 1, fields: { status: 'open' } });
+	});
+	engine.createOptimisticLayer('complete-1', (writer) => {
+		writer.writeRecord({ key: TODO, fields: { status: 'optimistic' } });
+	});
+	let calls = 0;
+	const values = [];
+	engine.watch(
+		(reader) => reader.record(TODO)?.fields.status,
+		(value) => {
+			calls++;
+			values.push(value);
+		}
+	);
+
+	engine.confirmOptimisticLayer('complete-1', (writer) => {
+		writer.writeRecord({ key: TODO, revision: 2, fields: { status: 'projected' } });
+	});
+	assert.equal(calls, 1);
+	assert.deepEqual(values, ['projected']);
+	assert.equal(engine.optimisticLayerState('complete-1'), undefined);
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.status), 'projected');
+});
+
+test('same-entity optimistic layers confirm and reject out of order without cross-rollback', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) => {
+		writer.writeRecord({ key: TODO, revision: 1, fields: { title: 'base', status: 'open' } });
+	});
+
+	engine.createOptimisticLayer('title-a', (writer) => {
+		writer.writeRecord({ key: TODO, fields: { title: 'A' } });
+	});
+	engine.createOptimisticLayer('title-b', (writer) => {
+		writer.writeRecord({ key: TODO, fields: { title: 'B' } });
+	});
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'B');
+
+	// B confirms first. A stays tracked but cannot reappear above B's projection.
+	engine.confirmOptimisticLayer('title-b', (writer) => {
+		writer.writeRecord({ key: TODO, revision: 2, fields: { title: 'B projected' } });
+	});
+	assert.equal(engine.optimisticLayerState('title-a'), 'optimistic');
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'B projected');
+	engine.confirmOptimisticLayer('title-a', (writer) => {
+		assert.equal(
+			writer.writeRecord({ key: TODO, revision: 1, fields: { title: 'A stale projection' } }),
+			false
+		);
+	});
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'B projected');
+
+	engine.createOptimisticLayer('status-c', (writer) => {
+		writer.writeRecord({ key: TODO, fields: { status: 'C' } });
+	});
+	engine.createOptimisticLayer('status-d', (writer) => {
+		writer.writeRecord({ key: TODO, fields: { status: 'D' } });
+	});
+	// C confirms first, but the causally later pending D remains visible.
+	engine.confirmOptimisticLayer('status-c', (writer) => {
+		writer.writeRecord({ key: TODO, revision: 3, fields: { status: 'C projected' } });
+	});
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.status), 'D');
+	engine.rejectOptimisticLayer('status-d');
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.status), 'C projected');
+
+	engine.createOptimisticLayer('title-e', (writer) => {
+		writer.writeRecord({ key: TODO, fields: { title: 'E' } });
+	});
+	engine.createOptimisticLayer('title-f', (writer) => {
+		writer.writeRecord({ key: TODO, fields: { title: 'F' } });
+	});
+	engine.rejectOptimisticLayer('title-f');
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'E');
+	engine.confirmOptimisticLayer('title-e', (writer) => {
+		writer.writeRecord({ key: TODO, revision: 4, fields: { title: 'E projected' } });
+	});
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'E projected');
+});
+
+test('confirming one field does not retire an independent optimistic field', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) =>
+		writer.writeRecord({
+			key: TODO,
+			revision: 1,
+			fields: { title: 'base title', status: 'base status' }
+		})
+	);
+	engine.createOptimisticLayer('title-layer', (writer) => {
+		writer.writeRecord({ key: TODO, fields: { title: 'pending title' } });
+	});
+	engine.createOptimisticLayer('status-layer', (writer) => {
+		writer.writeRecord({ key: TODO, fields: { status: 'pending status' } });
+	});
+
+	engine.confirmOptimisticLayer('status-layer', (writer) => {
+		// Projectors commonly return a full row, including fields owned by other
+		// in-flight commands.
+		writer.writeRecord({
+			key: TODO,
+			revision: 2,
+			fields: { title: 'server title', status: 'projected status' }
+		});
+	});
+	assert.deepEqual(engine.read((reader) => reader.record(TODO)?.fields), {
+		title: 'pending title',
+		status: 'projected status'
+	});
+	assert.equal(engine.optimisticLayerState('title-layer'), 'optimistic');
+	engine.rejectOptimisticLayer('title-layer');
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'server title');
+});
+
+test('field and link selectors observe base and optimistic tombstones', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) =>
+		writer.writeRecord({
+			key: TODO,
+			revision: 1,
+			fields: { title: 'visible' },
+			links: { owner: USER }
+		})
+	);
+	const fieldPresence = [];
+	const linkPresence = [];
+	engine.watch((reader) => reader.field(TODO, 'title'), (value) => fieldPresence.push(value));
+	engine.watch((reader) => reader.link(TODO, 'owner'), (value) => linkPresence.push(value));
+
+	engine.batch((writer) => writer.tombstoneRecord(TODO, 2));
+	assert.deepEqual(fieldPresence, [{ present: false }]);
+	assert.deepEqual(linkPresence, [{ present: false }]);
+
+	engine.batch((writer) =>
+		writer.writeRecord({
+			key: TODO,
+			revision: 3,
+			fields: { title: 'recreated' },
+			links: { owner: USER }
+		})
+	);
+	fieldPresence.length = 0;
+	linkPresence.length = 0;
+	engine.createOptimisticLayer('delete-visible-record', (writer) => {
+		writer.tombstoneRecord(TODO);
+	});
+	assert.deepEqual(fieldPresence, [{ present: false }]);
+	assert.deepEqual(linkPresence, [{ present: false }]);
+	engine.rejectOptimisticLayer('delete-visible-record');
+	assert.equal(engine.read((reader) => reader.field(TODO, 'title')).present, true);
+});
+
+test('newer stale markers fence older index writes and deletes', () => {
+	const engine = createCacheEngine();
+	const metadata = {
+		field: 'todos',
+		arguments: { first: 20 },
+		coverage: { kind: 'complete' },
+		dependencies: ['todos']
+	};
+	engine.batch((writer) =>
+		writer.writeIndex({ key: ALL, revision: 10, records: [TODO], complete: true, metadata })
+	);
+	engine.batch((writer) => {
+		assert.equal(writer.markIndexStale(ALL, 'late-error', 9), false);
+		assert.equal(writer.markIndexStale(ALL, 'new-error', 11), true);
+		assert.equal(
+			writer.writeIndex({
+				key: ALL,
+				revision: 10,
+				records: [OTHER_TODO],
+				complete: true,
+				metadata
+			}),
+			false
+		);
+		assert.equal(writer.deleteIndex(ALL, 10), false);
+	});
+	assert.equal(engine.read((reader) => reader.index(ALL)?.revision), '10');
+	assert.equal(engine.read((reader) => reader.index(ALL)?.staleRevision), '11');
+	assert.equal(engine.read((reader) => reader.index(ALL)?.metadata.staleReason), 'new-error');
+
+	engine.batch((writer) =>
+		writer.writeIndex({ key: ALL, revision: 11, records: [TODO], complete: true, metadata })
+	);
+	assert.equal(engine.read((reader) => reader.index(ALL)?.staleRevision), undefined);
+	assert.equal(engine.read((reader) => reader.index(ALL)?.metadata.staleReason), undefined);
+});
+
+test('missing index checkpoints survive extract/restore without inventing membership', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) => {
+		assert.equal(writer.markIndexStale(ALL, 'uncached-error', 10), true);
+	});
+	assert.equal(engine.read((reader) => reader.index(ALL)), undefined);
+	const restored = createCacheEngine();
+	restored.restore(JSON.parse(JSON.stringify(engine.extract())));
+	assert.equal(restored.read((reader) => reader.index(ALL)), undefined);
+	restored.batch((writer) => {
+		assert.equal(
+			writer.writeIndex({ key: ALL, revision: 9, records: [TODO], complete: true }),
+			false
+		);
+	});
+	assert.equal(restored.read((reader) => reader.index(ALL)), undefined);
+
+	const zero = cacheIndexKey({ field: 'zero_revision', arguments: {} });
+	const zeroFenced = createCacheEngine();
+	zeroFenced.batch((writer) => writer.markIndexStale(zero, 'revision-zero-error', 0));
+	const zeroRestored = createCacheEngine();
+	zeroRestored.restore(JSON.parse(JSON.stringify(zeroFenced.extract())));
+	zeroRestored.batch((writer) => {
+		assert.equal(
+			writer.writeIndex({ key: zero, revision: 0, records: [TODO], complete: true }),
+			true
+		);
+	});
+	assert.deepEqual(zeroRestored.read((reader) => reader.index(zero)?.records), [TODO]);
+});
+
+test('confirmed index fences include visible, stale, and hidden base checkpoints', () => {
+	const engine = createCacheEngine();
+	const stale = cacheIndexKey({ field: 'stale_todos', arguments: {} });
+	const deleted = cacheIndexKey({ field: 'deleted_todos', arguments: {} });
+	const hiddenStale = cacheIndexKey({
+		field: 'hidden_stale_todos',
+		arguments: {}
+	});
+	const missing = cacheIndexKey({ field: 'missing_todos', arguments: {} });
+	engine.batch((writer) => {
+		writer.writeIndex({
+			key: ALL,
+			revision: 5,
+			records: [TODO],
+			complete: true
+		});
+		writer.writeIndex({
+			key: stale,
+			revision: 4,
+			records: [TODO],
+			complete: true
+		});
+		writer.markIndexStale(stale, 'partial-error', 7);
+		writer.deleteIndex(deleted, 9);
+		writer.markIndexStale(hiddenStale, 'missing-result', 11);
+	});
+
+	assert.deepEqual(
+		[...engine.confirmedIndexFences([
+			ALL,
+			stale,
+			deleted,
+			hiddenStale,
+			missing
+		])],
+		[
+			[ALL, '5'],
+			[stale, '7'],
+			[deleted, '9'],
+			[hiddenStale, '11']
+		]
+	);
+	assert.equal(engine.read((reader) => reader.index(deleted)), undefined);
+	assert.equal(engine.read((reader) => reader.index(hiddenStale)), undefined);
+});
+
+test('one authoritative batch may rewrite lifecycle-invalidated membership at its checkpoint', () => {
+	const engine = createCacheEngine();
+	const metadata = {
+		field: 'todos',
+		arguments: { first: 20 },
+		coverage: { kind: 'complete' },
+		dependencies: ['todos']
+	};
+	engine.batch((writer) => {
+		writer.writeRecord({ key: TODO, revision: 1, fields: { id: 'todo-1' } });
+		writer.writeRecord({ key: OTHER_TODO, revision: 1, fields: { id: 'todo-2' } });
+		writer.writeRecord({ key: USER, revision: 1, fields: { id: 'user-1' } });
+		writer.writeIndex({
+			key: ALL,
+			revision: 2,
+			records: [TODO, OTHER_TODO, USER],
+			complete: true,
+			metadata
+		});
+	});
+	engine.batch((writer) => {
+		writer.tombstoneRecord(TODO, 3);
+		assert.equal(
+			writer.writeIndex({
+				key: ALL,
+				revision: 2,
+				records: [USER, OTHER_TODO],
+				complete: true,
+				metadata
+			}),
+			true
+		);
+	});
+	const index = engine.read((reader) => reader.index(ALL));
+	assert.deepEqual(index.records, [USER, OTHER_TODO]);
+	assert.equal(index.complete, true);
+	assert.equal(index.staleRevision, undefined);
+});
+
+test('record revisions and tombstones reject stale overwrite and resurrection', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) => {
+		writer.writeRecord({ key: TODO, revision: '8', fields: { title: 'latest', status: 'open' } });
+		assert.equal(writer.tombstoneRecord(TODO, 9n), true);
+	});
+	assert.equal(engine.read((reader) => reader.record(TODO)), undefined);
+
+	engine.batch((writer) => {
+		assert.equal(writer.writeRecord({ key: TODO, revision: 8, fields: { title: 'stale' } }), false);
+		assert.equal(writer.tombstoneRecord(TODO, 7), false);
+	});
+	assert.throws(
+		() =>
+			engine.batch((writer) =>
+				writer.writeRecord({ key: TODO, revision: 9, fields: { title: 'same' } })
+			),
+		CacheRevisionConflictError
+	);
+	assert.equal(engine.read((reader) => reader.record(TODO)), undefined);
+
+	engine.batch((writer) => {
+		assert.equal(
+			writer.writeRecord({ key: TODO, revision: 10, fields: { id: 'todo-1', title: 'recreated' } }),
+			true
+		);
+	});
+	const recreated = engine.read((reader) => reader.record(TODO));
+	assert.equal(recreated.fields.title, 'recreated');
+	assert.equal(Object.hasOwn(recreated.fields, 'status'), false);
+});
+
+test('SSR extract and restore contain confirmed base only', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) => {
+		writer.writeRecord({ key: TODO, revision: 1, fields: { title: 'confirmed' } });
+		writer.writeIndex({ key: ALL, revision: 1, records: [TODO], complete: true });
+	});
+	engine.createOptimisticLayer('rename-1', (writer) => {
+		writer.writeRecord({ key: TODO, fields: { title: 'optimistic secret' } });
+		writer.writeRecord({ key: OTHER_TODO, fields: { title: 'optimistic insert' } });
+		writer.writeIndex({ key: ALL, records: [TODO, OTHER_TODO], complete: true });
+	});
+
+	const snapshot = engine.extract();
+	const serialized = JSON.stringify(snapshot);
+	assert.doesNotMatch(serialized, /optimistic/);
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'optimistic secret');
+
+	const restored = createCacheEngine();
+	restored.restore(JSON.parse(serialized));
+	assert.equal(restored.read((reader) => reader.record(TODO)?.fields.title), 'confirmed');
+	assert.equal(restored.read((reader) => reader.record(OTHER_TODO)), undefined);
+	assert.deepEqual(restored.read((reader) => reader.index(ALL)?.records), [TODO]);
+	assert.equal(restored.optimisticLayerState('rename-1'), undefined);
+});
+
+test('GC traverses confirmed indexes and relationship links while retaining tombstone fences', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) => {
+		writer.writeRecord({ key: USER, revision: 1, fields: { name: 'Ada' }, links: { todos: [TODO] } });
+		writer.writeRecord({ key: TODO, revision: 1, fields: { title: 'reachable' } });
+		writer.writeRecord({ key: OTHER_TODO, revision: 1, fields: { title: 'orphan' } });
+		writer.writeRecord({ key: 'Todo:deleted', revision: 1, fields: { title: 'deleted' } });
+		writer.tombstoneRecord('Todo:deleted', 2);
+		writer.writeIndex({ key: ALL, revision: 1, records: [USER], complete: true });
+	});
+	assert.deepEqual(engine.gc(), [OTHER_TODO]);
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'reachable');
+
+	engine.batch((writer) => writer.deleteIndex(ALL, 2));
+	engine.retain(USER);
+	assert.deepEqual(engine.gc(), []);
+	engine.release(USER);
+	assert.deepEqual(engine.gc(), [TODO, USER]);
+	assert.match(JSON.stringify(engine.extract()), /Todo:deleted/);
+});
+
+test('GC treats parent-scoped indexes as edges, not immortal roots', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) => {
+		writer.writeRecord({ key: USER, revision: 1, fields: { id: 'user-1' } });
+		writer.writeRecord({ key: TODO, revision: 1, fields: { id: 'todo-1' } });
+		writer.writeIndex({ key: ALL, revision: 1, records: [USER], complete: true });
+		writer.writeIndex({
+			key: USER_TODOS,
+			revision: 1,
+			records: [TODO],
+			complete: true,
+			metadata: {
+				parent: USER,
+				parentRevision: '1',
+				field: 'todos',
+				arguments: { first: 20 },
+				coverage: { kind: 'complete' },
+				dependencies: ['todos']
+			}
+		});
+	});
+	assert.deepEqual(engine.gc(), []);
+	engine.batch((writer) => writer.deleteIndex(ALL, 2));
+	assert.deepEqual(engine.gc(), [TODO, USER]);
+	assert.equal(engine.read((reader) => reader.index(USER_TODOS)), undefined);
+});
+
+test('GC cannot corrupt rollback beneath destructive optimistic overlays', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) => {
+		writer.writeRecord({ key: USER, revision: 1, fields: { name: 'Ada' }, links: { todos: [TODO] } });
+		writer.writeRecord({ key: TODO, revision: 1, fields: { title: 'confirmed child' } });
+		writer.writeRecord({ key: OTHER_TODO, revision: 1, fields: { title: 'optimistic root' } });
+		writer.writeIndex({ key: ALL, revision: 1, records: [USER], complete: true });
+	});
+
+	engine.createOptimisticLayer('rewrite-roots', (writer) => {
+		writer.tombstoneRecord(USER);
+		writer.writeIndex({ key: ALL, records: [OTHER_TODO], complete: true });
+	});
+	assert.deepEqual(engine.gc(), []);
+	engine.rejectOptimisticLayer('rewrite-roots');
+	assert.deepEqual(engine.read((reader) => reader.index(ALL)?.records), [USER]);
+	assert.deepEqual(engine.read((reader) => reader.record(USER)?.links.todos), [TODO]);
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'confirmed child');
+	assert.deepEqual(engine.gc(), [OTHER_TODO]);
+
+	engine.createOptimisticLayer('delete-root', (writer) => writer.deleteIndex(ALL));
+	assert.deepEqual(engine.gc(), []);
+	engine.rejectOptimisticLayer('delete-root');
+	assert.deepEqual(engine.read((reader) => reader.index(ALL)?.records), [USER]);
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'confirmed child');
+});
+
+test('GC preserves every record that can reappear from a non-current optimistic layer', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) => {
+		writer.writeRecord({ key: USER, revision: 1, fields: { name: 'Ada' } });
+		writer.writeRecord({ key: TODO, revision: 1, fields: { title: 'hidden by top layer' } });
+		writer.writeIndex({ key: USER_TODOS, revision: 1, records: [USER], complete: true });
+	});
+
+	engine.createOptimisticLayer('older-root-and-link', (writer) => {
+		writer.writeRecord({ key: USER, links: { todos: [TODO] } });
+		writer.writeIndex({ key: ALL, records: [TODO], complete: true });
+	});
+	engine.createOptimisticLayer('newer-hides-root-and-link', (writer) => {
+		writer.writeRecord({ key: USER, links: { todos: [] } });
+		writer.writeIndex({ key: ALL, records: [], complete: true });
+	});
+	assert.deepEqual(engine.read((reader) => reader.record(USER)?.links.todos), []);
+	assert.deepEqual(engine.read((reader) => reader.index(ALL)?.records), []);
+	assert.deepEqual(engine.gc(), []);
+
+	engine.rejectOptimisticLayer('newer-hides-root-and-link');
+	assert.deepEqual(engine.read((reader) => reader.record(USER)?.links.todos), [TODO]);
+	assert.deepEqual(engine.read((reader) => reader.index(ALL)?.records), [TODO]);
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'hidden by top layer');
+
+	engine.rejectOptimisticLayer('older-root-and-link');
+	assert.deepEqual(engine.gc(), [TODO]);
+});
+
+test('failed batches restore base state without notifying observers', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) => writer.writeRecord({ key: TODO, revision: 1, fields: { title: 'base' } }));
+	let calls = 0;
+	engine.watch((reader) => reader.record(TODO)?.fields.title, () => calls++);
+	assert.throws(
+		() =>
+			engine.batch((writer) => {
+				writer.writeRecord({ key: TODO, revision: 2, fields: { title: 'should roll back' } });
+				throw new Error('abort');
+			}),
+		/abort/
+	);
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'base');
+	assert.equal(calls, 0);
+});
+
+test('nested batches are rejected before inner writes and rollback clears dependency dirt', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) => {
+		writer.writeRecord({ key: TODO, revision: 1, fields: { title: 'outer' } });
+		assert.throws(
+			() =>
+				engine.batch((inner) => {
+					inner.writeRecord({ key: TODO, revision: 2, fields: { status: 'leaked' } });
+				}),
+			/nested cache batches/
+		);
+		writer.writeRecord({ key: TODO, revision: 2, fields: { title: 'outer committed' } });
+	});
+	assert.equal(Object.hasOwn(engine.read((reader) => reader.record(TODO).fields), 'status'), false);
+
+	let statusSelections = 0;
+	engine.watch(
+		(reader) => {
+			statusSelections += 1;
+			return reader.field(TODO, 'status');
+		},
+		() => undefined
+	);
+	statusSelections = 0;
+	assert.throws(
+		() =>
+			engine.batch((writer) => {
+				writer.writeRecord({ key: TODO, revision: 3, fields: { status: 'rolled back' } });
+				throw new Error('rollback dependency set');
+			}),
+		/rollback dependency set/
+	);
+	engine.batch((writer) =>
+		writer.writeRecord({ key: TODO, revision: 3, fields: { title: 'unrelated' } })
+	);
+	assert.equal(statusSelections, 0);
+});
+
+test('async base and optimistic updaters are rejected, rolled back, and revoked', async () => {
+	const engine = createCacheEngine();
+	let releaseBase;
+	const baseGate = new Promise((resolve) => {
+		releaseBase = resolve;
+	});
+	let baseLateError;
+	let finishBase;
+	const baseFinished = new Promise((resolve) => {
+		finishBase = resolve;
+	});
+	assert.throws(
+		() =>
+			engine.batch(async (writer) => {
+				writer.writeRecord({ key: TODO, revision: 1, fields: { title: 'escaped' } });
+				await baseGate;
+				try {
+					writer.writeRecord({ key: TODO, revision: 2, fields: { title: 'late' } });
+				} catch (error) {
+					baseLateError = error;
+				} finally {
+					finishBase();
+				}
+			}),
+		/cache update must be synchronous/
+	);
+	assert.equal(engine.read((reader) => reader.record(TODO)), undefined);
+	releaseBase();
+	await baseFinished;
+	assert.match(String(baseLateError), /writer is no longer active/);
+	assert.equal(engine.read((reader) => reader.record(TODO)), undefined);
+
+	let releaseLayer;
+	const layerGate = new Promise((resolve) => {
+		releaseLayer = resolve;
+	});
+	let layerLateError;
+	let finishLayer;
+	const layerFinished = new Promise((resolve) => {
+		finishLayer = resolve;
+	});
+	assert.throws(
+		() =>
+			engine.createOptimisticLayer('async-layer', async (writer) => {
+				writer.writeRecord({ key: TODO, fields: { title: 'escaped optimistic' } });
+				await layerGate;
+				try {
+					writer.writeRecord({ key: TODO, fields: { title: 'late optimistic' } });
+				} catch (error) {
+					layerLateError = error;
+				} finally {
+					finishLayer();
+				}
+			}),
+		/optimistic layer update must be synchronous/
+	);
+	assert.equal(engine.optimisticLayerState('async-layer'), undefined);
+	releaseLayer();
+	await layerFinished;
+	assert.match(String(layerLateError), /writer is no longer active/);
+
+	engine.createOptimisticLayer('confirm-async', (writer) => {
+		writer.writeRecord({ key: TODO, fields: { title: 'pending confirmation' } });
+	});
+	assert.throws(
+		() =>
+			engine.confirmOptimisticLayer('confirm-async', async (writer) => {
+				writer.writeRecord({ key: TODO, revision: 3, fields: { title: 'escaped confirm' } });
+			}),
+		/cache update must be synchronous/
+	);
+	assert.equal(engine.optimisticLayerState('confirm-async'), 'optimistic');
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'pending confirmation');
+});
+
+test('watcher failures are isolated after commit and reported as one aggregate', () => {
+	const reported = [];
+	const engine = createCacheEngine({ onWatcherError: (error) => reported.push(error) });
+	const delivered = [];
+	engine.watch(
+		(reader) => reader.record(TODO)?.fields.title,
+		() => {
+			delivered.push('first');
+			throw new Error('first watcher failed');
+		}
+	);
+	engine.watch(
+		(reader) => reader.record(TODO)?.fields.title,
+		() => delivered.push('second')
+	);
+
+	engine.batch((writer) =>
+		writer.writeRecord({ key: TODO, revision: 1, fields: { title: 'committed' } })
+	);
+	assert.deepEqual(delivered, ['first', 'second']);
+	assert.equal(reported.length, 1);
+	assert.ok(reported[0] instanceof AggregateError);
+	assert.match(reported[0].message, /transaction committed/);
+	assert.equal(reported[0].errors.length, 1);
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'committed');
+});
+
+test('a failing immediate watcher is reported and unregistered', () => {
+	const reported = [];
+	const engine = createCacheEngine({ onWatcherError: (error) => reported.push(error) });
+	engine.batch((writer) =>
+		writer.writeRecord({ key: TODO, revision: 1, fields: { title: 'initial' } })
+	);
+	let calls = 0;
+	engine.watch(
+		(reader) => reader.field(TODO, 'title'),
+		() => {
+			calls += 1;
+			throw new Error('immediate failed');
+		},
+		{ immediate: true }
+	);
+	assert.equal(calls, 1);
+	assert.equal(reported.length, 1);
+	engine.batch((writer) =>
+		writer.writeRecord({ key: TODO, revision: 2, fields: { title: 'later' } })
+	);
+	assert.equal(calls, 1);
+});
+
+test('same-revision disagreement raises a deterministic conflict and rolls back', () => {
+	const engine = createCacheEngine();
+	engine.batch((writer) => {
+		writer.writeRecord({ key: TODO, revision: 4, fields: { title: 'canonical' } });
+		writer.writeIndex({ key: ALL, revision: 4, records: [TODO], complete: true });
+	});
+
+	assert.throws(
+		() =>
+			engine.batch((writer) => {
+				writer.writeRecord({ key: OTHER_TODO, revision: 1, fields: { title: 'rolled back' } });
+				writer.writeRecord({ key: TODO, revision: 4, fields: { title: 'conflict' } });
+			}),
+		(error) =>
+			error instanceof CacheRevisionConflictError &&
+			error.revision === '4' &&
+			error.dependency.includes('field:title')
+	);
+	assert.equal(engine.read((reader) => reader.record(OTHER_TODO)), undefined);
+	assert.equal(engine.read((reader) => reader.record(TODO)?.fields.title), 'canonical');
+
+	assert.throws(
+		() =>
+			engine.batch((writer) =>
+				writer.writeIndex({ key: ALL, revision: 4, records: [], complete: true })
+			),
+		CacheRevisionConflictError
+	);
+	assert.deepEqual(engine.read((reader) => reader.index(ALL)?.records), [TODO]);
+	assert.throws(
+		() => engine.batch((writer) => writer.tombstoneRecord(TODO, 4)),
+		CacheRevisionConflictError
+	);
+});
+
+test('structured index metadata must agree with its canonical key', () => {
+	const engine = createCacheEngine();
+	assert.throws(
+		() =>
+			engine.batch((writer) =>
+				writer.writeIndex({
+					key: ALL,
+					revision: 1,
+					records: [],
+					metadata: {
+						field: 'different_root',
+						arguments: {},
+						coverage: { kind: 'complete' },
+						dependencies: []
+					}
+				})
+			),
+		/index key does not match its metadata/
+	);
+});
+
+const APOLLO_TODO = gql`
+	fragment CacheEngineTodo on Todo {
+		id
+		status
+	}
+	query CacheEngineTodoQuery {
+		todo {
+			__typename
+			...CacheEngineTodo
+		}
+	}
+`;
+
+function apolloWrite(cache, status) {
+	cache.writeQuery({
+		query: APOLLO_TODO,
+		data: { todo: { __typename: 'Todo', id: 'todo-1', status } }
+	});
+}
+
+test('Apollo 4 public APIs pass basic layers/batching/extract but expose the causal ordering gap', () => {
+	const cache = new InMemoryCache({
+		typePolicies: { Todo: { keyFields: ['id'] } }
+	});
+	apolloWrite(cache, 'base');
+	let calls = 0;
+	cache.watch({ query: APOLLO_TODO, optimistic: true, callback: () => calls++ });
+	cache.batch({
+		optimistic: 'A',
+		update() {
+			apolloWrite(cache, 'A');
+		}
+	});
+	cache.batch({
+		optimistic: 'B',
+		update() {
+			apolloWrite(cache, 'B');
+		}
+	});
+	assert.equal(cache.readQuery({ query: APOLLO_TODO }, true).todo.status, 'B');
+	assert.equal(calls, 2, 'each public batch broadcasts once');
+
+	const baseSnapshot = JSON.stringify(cache.extract(false));
+	const optimisticSnapshot = JSON.stringify(cache.extract(true));
+	assert.match(baseSnapshot, /base/);
+	assert.doesNotMatch(baseSnapshot, /"status":"A"|"status":"B"/);
+	assert.match(optimisticSnapshot, /"status":"B"/);
+
+	cache.batch({
+		update() {
+			apolloWrite(cache, 'B projected');
+		},
+		removeOptimistic: 'B'
+	});
+	// Native Apollo layer ordering reveals older A after newer B confirms.
+	assert.equal(cache.readQuery({ query: APOLLO_TODO }, true).todo.status, 'A');
+	cache.removeOptimistic('A');
+	assert.equal(cache.readQuery({ query: APOLLO_TODO }, true).todo.status, 'B projected');
+
+	// Apollo has no source-revision/tombstone fence: arrival order can resurrect stale data.
+	cache.evict({ id: 'Todo:{"id":"todo-1"}' });
+	apolloWrite(cache, 'stale resurrection');
+	assert.equal(cache.readQuery({ query: APOLLO_TODO }).todo.status, 'stale resurrection');
+});
+
+test('built declarations contain no Apollo/vendor types', async () => {
+	const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+	const declarationFiles = [];
+	async function visit(directory) {
+		for (const entry of await readdir(directory, { withFileTypes: true })) {
+			const path = join(directory, entry.name);
+			if (entry.isDirectory()) await visit(path);
+			else if (entry.name.endsWith('.d.ts')) declarationFiles.push(path);
+		}
+	}
+	await visit(join(packageRoot, 'dist'));
+	assert.ok(declarationFiles.length > 0);
+	for (const path of declarationFiles) {
+		const declaration = await readFile(path, 'utf8');
+		assert.doesNotMatch(declaration, /@apollo\/client|\bApollo(?:Cache|Client|Link)\b/);
+	}
+});
diff --git a/js/tests/cache-engine-derived-index.test.mjs b/js/tests/cache-engine-derived-index.test.mjs
new file mode 100644
index 00000000..856239fd
--- /dev/null
+++ b/js/tests/cache-engine-derived-index.test.mjs
@@ -0,0 +1,367 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+	cacheIndexKey,
+	createCacheEngine
+} from '../dist/internal/cache-engine.js';
+
+const BASE = 'Todo:base';
+const A = 'Todo:a';
+const B = 'Todo:b';
+const SERVER = 'Todo:server';
+const TODOS = cacheIndexKey({ field: 'todos', arguments: {} });
+const METADATA = Object.freeze({
+	field: 'todos',
+	arguments: Object.freeze({}),
+	coverage: Object.freeze({ kind: 'complete' }),
+	dependencies: Object.freeze(['todos'])
+});
+
+function seed(engine) {
+	engine.batch((writer) => {
+		writer.writeRecord({
+			key: BASE,
+			revision: 1,
+			fields: { id: 'base', title: 'base' }
+		});
+		writer.writeIndex({
+			key: TODOS,
+			revision: 1,
+			records: [BASE],
+			complete: true,
+			metadata: METADATA
+		});
+	});
+}
+
+function membershipReconciler(observations = []) {
+	return (confirmed, layers) => {
+		const index = confirmed.indexes.find(
+			(candidate) => candidate.key === TODOS && !candidate.deleted
+		);
+		observations.push({
+			confirmedRecords: confirmed.records.map(({ key }) => key),
+			layers
+		});
+		if (index === undefined) return [];
+		return [
+			{
+				kind: 'write',
+				write: {
+					key: TODOS,
+					records: [
+						...index.records,
+						...layers.flatMap((layer) => layer.context?.records ?? [])
+					],
+					complete: true,
+					metadata: index.metadata
+				}
+			}
+		];
+	};
+}
+
+test('derived indexes rebase from confirmed state plus surviving semantic layers', () => {
+	const engine = createCacheEngine();
+	seed(engine);
+	const observations = [];
+	engine.setDerivedIndexReconciler(membershipReconciler(observations));
+
+	const contextA = { records: [A] };
+	const contextB = { records: [B] };
+	engine.createOptimisticLayer(
+		'A',
+		(writer) =>
+			writer.writeRecord({
+				key: A,
+				fields: { id: 'a', title: 'from A' }
+			}),
+		contextA
+	);
+	engine.createOptimisticLayer(
+		'B',
+		(writer) =>
+			writer.writeRecord({
+				key: B,
+				fields: { id: 'b', title: 'from B' }
+			}),
+		contextB
+	);
+	assert.deepEqual(
+		engine.read((reader) => reader.index(TODOS)?.records),
+		[BASE, A, B]
+	);
+
+	// Context is detached at layer creation; caller mutation cannot alter a
+	// future full-overlay reconciliation.
+	contextB.records.push(A);
+	const delivered = [];
+	engine.watch(
+		(reader) => reader.index(TODOS)?.records,
+		(value) => delivered.push(value)
+	);
+	assert.equal(engine.rejectOptimisticLayer('A'), true);
+
+	assert.deepEqual(
+		engine.read((reader) => reader.index(TODOS)?.records),
+		[BASE, B]
+	);
+	assert.deepEqual(delivered, [[BASE, B]]);
+	assert.equal(engine.read((reader) => reader.record(A)), undefined);
+	assert.equal(engine.read((reader) => reader.record(B))?.fields.title, 'from B');
+	const last = observations.at(-1);
+	assert.deepEqual(last.confirmedRecords, [BASE]);
+	assert.deepEqual(last.layers.map(({ id }) => id), ['B']);
+	assert.equal(Object.isFrozen(last.layers), true);
+	assert.equal(Object.isFrozen(last.layers[0]), true);
+	assert.equal(Object.isFrozen(last.layers[0].context), true);
+	assert.equal(Object.isFrozen(last.layers[0].context.records), true);
+
+	delivered.length = 0;
+	engine.confirmOptimisticLayer('B', (writer) => {
+		writer.writeRecord({
+			key: B,
+			revision: 2,
+			fields: { id: 'b', title: 'confirmed B' }
+		});
+		writer.writeIndex({
+			key: TODOS,
+			revision: 2,
+			records: [BASE, B],
+			complete: true,
+			metadata: METADATA
+		});
+	});
+	assert.equal(engine.optimisticLayerState('B'), undefined);
+	assert.deepEqual(
+		engine.read((reader) => reader.index(TODOS)?.records),
+		[BASE, B]
+	);
+	assert.deepEqual(delivered, []);
+	assert.deepEqual(observations.at(-1).layers, []);
+});
+
+test('authoritative base writes reconcile pending derived indexes before one watcher flush', () => {
+	const engine = createCacheEngine();
+	seed(engine);
+	const observations = [];
+	engine.setDerivedIndexReconciler(membershipReconciler(observations));
+	engine.createOptimisticLayer(
+		'B',
+		(writer) =>
+			writer.writeRecord({
+				key: B,
+				fields: { id: 'b', title: 'pending B' }
+			}),
+		{ records: [B] }
+	);
+
+	const delivered = [];
+	engine.watch(
+		(reader) => reader.index(TODOS)?.records,
+		(value) => delivered.push(value)
+	);
+	engine.batch((writer) => {
+		writer.writeRecord({
+			key: SERVER,
+			revision: 2,
+			fields: { id: 'server', title: 'from server' }
+		});
+		writer.writeIndex({
+			key: TODOS,
+			revision: 2,
+			records: [BASE, SERVER],
+			complete: true,
+			metadata: METADATA
+		});
+	});
+
+	assert.deepEqual(
+		engine.read((reader) => reader.index(TODOS)?.records),
+		[BASE, SERVER, B]
+	);
+	assert.deepEqual(delivered, [[BASE, SERVER, B]]);
+	const last = observations.at(-1);
+	assert.deepEqual(
+		last.confirmedRecords.sort(),
+		[BASE, SERVER].sort()
+	);
+	assert.deepEqual(last.layers.map(({ id }) => id), ['B']);
+});
+
+test('derived stale/delete decisions are overlays and accepted-state changes reconcile atomically', () => {
+	const engine = createCacheEngine();
+	seed(engine);
+	engine.setDerivedIndexReconciler((_confirmed, layers) => {
+		const layer = layers.at(-1);
+		if (layer?.context?.mode === 'delete') {
+			return [{ kind: 'delete', key: TODOS }];
+		}
+		if (layer?.state === 'accepted') {
+			return [{ kind: 'stale', key: TODOS, reason: 'awaiting-projection' }];
+		}
+		return [];
+	});
+	engine.createOptimisticLayer('lifecycle', () => undefined, {
+		mode: 'stale-after-accept'
+	});
+	assert.equal(engine.read((reader) => reader.index(TODOS)?.complete), true);
+
+	const delivered = [];
+	engine.watch(
+		(reader) => reader.index(TODOS),
+		(value) => delivered.push(value)
+	);
+	assert.equal(engine.markOptimisticLayerAccepted('lifecycle'), true);
+	const stale = engine.read((reader) => reader.index(TODOS));
+	assert.equal(
+		stale.complete,
+		true,
+		'freshness uncertainty must retain structurally complete visible data'
+	);
+	assert.equal(stale.metadata.staleReason, 'awaiting-projection');
+	assert.equal(delivered.length, 1);
+
+	assert.equal(engine.rejectOptimisticLayer('lifecycle'), true);
+	const restored = engine.read((reader) => reader.index(TODOS));
+	assert.equal(restored.complete, true);
+	assert.equal(restored.metadata.staleReason, undefined);
+
+	engine.createOptimisticLayer('delete', () => undefined, { mode: 'delete' });
+	assert.equal(engine.read((reader) => reader.index(TODOS)), undefined);
+	engine.rejectOptimisticLayer('delete');
+	assert.deepEqual(
+		engine.read((reader) => reader.index(TODOS)?.records),
+		[BASE]
+	);
+});
+
+test('reconciler failures and invalid mutations roll back base and layer lifecycle state', async () => {
+	const engine = createCacheEngine();
+	seed(engine);
+	const stable = membershipReconciler();
+	let rejectBlocked = false;
+	engine.setDerivedIndexReconciler((confirmed, layers) => {
+		const title = confirmed.records
+			.find(({ key }) => key === BASE)
+			?.fields.title.value;
+		if (title === 'bad') throw new Error('cannot derive bad base');
+		if (rejectBlocked && layers.length === 0) {
+			throw new Error('cannot derive rejected layer');
+		}
+		return stable(confirmed, layers);
+	});
+	engine.createOptimisticLayer(
+		'A',
+		(writer) => writer.writeRecord({ key: A, fields: { id: 'a' } }),
+		{ records: [A] }
+	);
+	const delivered = [];
+	engine.watch(
+		(reader) => reader.index(TODOS)?.records,
+		(value) => delivered.push(value)
+	);
+
+	assert.throws(
+		() =>
+			engine.batch((writer) =>
+				writer.writeRecord({
+					key: BASE,
+					revision: 2,
+					fields: { title: 'bad' }
+				})
+			),
+		/cannot derive bad base/
+	);
+	assert.equal(
+		engine.read((reader) => reader.record(BASE)?.fields.title),
+		'base'
+	);
+	assert.deepEqual(
+		engine.read((reader) => reader.index(TODOS)?.records),
+		[BASE, A]
+	);
+	assert.deepEqual(delivered, []);
+
+	rejectBlocked = true;
+	assert.throws(
+		() => engine.rejectOptimisticLayer('A'),
+		/cannot derive rejected layer/
+	);
+	assert.equal(engine.optimisticLayerState('A'), 'optimistic');
+	assert.deepEqual(
+		engine.read((reader) => reader.index(TODOS)?.records),
+		[BASE, A]
+	);
+	assert.deepEqual(delivered, []);
+	rejectBlocked = false;
+
+	assert.throws(
+		() =>
+			engine.setDerivedIndexReconciler(() => [
+				{
+					kind: 'write',
+					write: {
+						key: TODOS,
+						records: [BASE],
+						complete: true,
+						metadata: METADATA
+					}
+				},
+				{ kind: 'stale', key: TODOS, reason: 'duplicate' }
+			]),
+		/duplicate derived index mutation/
+	);
+	assert.deepEqual(
+		engine.read((reader) => reader.index(TODOS)?.records),
+		[BASE, A]
+	);
+
+	assert.throws(
+		() =>
+			engine.createOptimisticLayer('invalid-context', () => undefined, {
+				invalid: () => undefined
+			}),
+		/JSON-compatible/
+	);
+	assert.equal(engine.optimisticLayerState('invalid-context'), undefined);
+
+	assert.throws(
+		() =>
+			engine.setDerivedIndexReconciler(async () => {
+				await Promise.resolve();
+				return [];
+			}),
+		/derived index reconciler must be synchronous/
+	);
+	assert.deepEqual(
+		engine.read((reader) => reader.index(TODOS)?.records),
+		[BASE, A]
+	);
+	await Promise.resolve();
+});
+
+test('restore clears optimistic contexts and the derived overlay without serializing either', () => {
+	const engine = createCacheEngine();
+	seed(engine);
+	const confirmed = engine.extract();
+	engine.setDerivedIndexReconciler(membershipReconciler());
+	engine.createOptimisticLayer(
+		'A',
+		(writer) => writer.writeRecord({ key: A, fields: { secret: 'optimistic' } }),
+		{ records: [A], secret: 'semantic-context' }
+	);
+	assert.deepEqual(
+		engine.read((reader) => reader.index(TODOS)?.records),
+		[BASE, A]
+	);
+	assert.doesNotMatch(JSON.stringify(engine.extract()), /optimistic|semantic-context/);
+
+	engine.restore(confirmed);
+	assert.equal(engine.optimisticLayerState('A'), undefined);
+	assert.equal(engine.read((reader) => reader.record(A)), undefined);
+	assert.deepEqual(
+		engine.read((reader) => reader.index(TODOS)?.records),
+		[BASE]
+	);
+});
diff --git a/js/tests/fixtures/adapter-conformance.mjs b/js/tests/fixtures/adapter-conformance.mjs
new file mode 100644
index 00000000..79dd21e4
--- /dev/null
+++ b/js/tests/fixtures/adapter-conformance.mjs
@@ -0,0 +1,631 @@
+import assert from 'node:assert/strict';
+
+import {
+	createDistributedReplica,
+	createReplicaCommandRuntime
+} from '../../dist/replica/index.js';
+
+export const REACT_FIXTURE_SCHEMA = `sha256:${'a'.repeat(64)}`;
+export const REACT_FIXTURE_SURFACE = Object.freeze({
+	kind: 'role',
+	name: 'user'
+});
+
+export const TodoModel = Object.freeze({
+	id: 'TodoView',
+	identityFields: Object.freeze(['id'])
+});
+
+const RequiredRevalidationCommand = Object.freeze({
+	version: 1,
+	name: 'todo.revalidate',
+	mutationField: 'revalidateTodos',
+	document:
+		'mutation RevalidateTodos($commandId: ID!) { revalidateTodos(commandId: $commandId) }',
+	operationHash: `sha256:${'b'.repeat(64)}`,
+	protocol: Object.freeze({
+		version: 1,
+		schemaHash: REACT_FIXTURE_SCHEMA,
+		protocolHash: `sha256:${'c'.repeat(64)}`,
+		surface: REACT_FIXTURE_SURFACE,
+		operation: `sha256:${'b'.repeat(64)}`,
+		trustedPresets: Object.freeze([])
+	}),
+	input: Object.freeze({ kind: 'none' }),
+	output: Object.freeze({
+		kind: 'object',
+		definition: Object.freeze({
+			name: 'RevalidateTodosResult',
+			fields: Object.freeze([
+				Object.freeze({
+					name: 'accepted',
+					typeName: 'Boolean',
+					nullable: false,
+					list: false,
+					itemNullable: false,
+					codec: 'boolean'
+				})
+			])
+		})
+	}),
+	consistency: 'accepted',
+	effects: Object.freeze({
+		version: 1,
+		operations: Object.freeze([]),
+		fallback: 'revalidate'
+	}),
+	revalidation: Object.freeze({
+		version: 1,
+		required: true,
+		dependencies: Object.freeze(['todos']),
+		models: Object.freeze([TodoModel.id]),
+		relationships: Object.freeze([])
+	}),
+	trustedPresets: Object.freeze([])
+});
+
+const NoVariables = Object.freeze({
+	version: 1,
+	limits: Object.freeze({
+		maxDepth: 8,
+		maxBoolWidth: 256,
+		maxInList: 1_000
+	}),
+	variables: Object.freeze({}),
+	inputs: Object.freeze({})
+});
+
+const TodoByIdVariables = Object.freeze({
+	version: 1,
+	limits: NoVariables.limits,
+	variables: Object.freeze({
+		id: Object.freeze({
+			kind: 'scalar',
+			scalar: 'ID',
+			codec: 'string',
+			nullable: false
+		})
+	}),
+	inputs: Object.freeze({})
+});
+
+const todoSelection = Object.freeze({
+	typename: TodoModel.id,
+	storage: Object.freeze({
+		kind: 'normalized',
+		model: TodoModel.id,
+		identityFields: TodoModel.identityFields
+	}),
+	members: Object.freeze([
+		Object.freeze({
+			kind: 'scalar',
+			responseKey: 'id',
+			field: 'id',
+			codec: 'ID',
+			nullable: false
+		}),
+		Object.freeze({
+			kind: 'scalar',
+			responseKey: 'title',
+			field: 'title',
+			codec: 'String',
+			nullable: false
+		}),
+		Object.freeze({
+			kind: 'scalar',
+			responseKey: 'status',
+			field: 'status',
+			codec: 'String',
+			nullable: false
+		})
+	])
+});
+
+export const TodosArtifact = Object.freeze({
+	id: 'query:react-fixture-todos',
+	document: 'query ReactFixtureTodos { todos { id title status } }',
+	protocol: Object.freeze({
+		version: 1,
+		schemaHash: REACT_FIXTURE_SCHEMA,
+		surface: REACT_FIXTURE_SURFACE,
+		operation: 'query:react-fixture-todos',
+		trustedPresets: Object.freeze([])
+	}),
+	variableCodec: NoVariables,
+	live: Object.freeze({
+		id: 'live:react-fixture-todos',
+		document:
+			'subscription ReactFixtureTodosLive { todos { id title status } }'
+	}),
+	roots: Object.freeze([
+		Object.freeze({
+			responseKey: 'todos',
+			field: 'todos',
+			cardinality: 'many',
+			nullable: false,
+			dependencies: Object.freeze(['todos']),
+			selection: todoSelection
+		})
+	])
+});
+
+export const OpenTodosArtifact = Object.freeze({
+	...TodosArtifact,
+	id: 'query:react-fixture-open-todos',
+	document:
+		'query ReactFixtureOpenTodos { todos(where: { completed: { _eq: false } }) { id title status completed } }',
+	protocol: Object.freeze({
+		...TodosArtifact.protocol,
+		operation: 'query:react-fixture-open-todos'
+	}),
+	live: Object.freeze({
+		id: 'live:react-fixture-open-todos',
+		document:
+			'subscription ReactFixtureOpenTodosLive { todos(where: { completed: { _eq: false } }) { id title status completed } }'
+	}),
+	roots: Object.freeze([
+		Object.freeze({
+			...TodosArtifact.roots[0],
+			selection: Object.freeze({
+				...todoSelection,
+				members: Object.freeze([
+					...todoSelection.members,
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: 'completed',
+						field: 'completed',
+						codec: 'Boolean',
+						nullable: false
+					})
+				])
+			}),
+			coverage: Object.freeze({ kind: 'complete' }),
+			filter: Object.freeze({
+				input: Object.freeze({
+					kind: 'literal',
+					value: Object.freeze({
+						completed: Object.freeze({ _eq: false })
+					})
+				}),
+				fields: Object.freeze([
+					Object.freeze({
+						field: 'completed',
+						scalar: 'Boolean',
+						codec: 'boolean',
+						nullable: false,
+						operators: Object.freeze(['_eq'])
+					})
+				]),
+				relationships: Object.freeze([]),
+				rowPolicy: Object.freeze({ kind: 'unrestricted' })
+			}),
+			pagination: Object.freeze({
+				kind: 'complete',
+				insert: 'local',
+				delete: 'local',
+				reorder: 'local',
+				stableUpdate: 'local'
+			})
+		})
+	])
+});
+
+export const TodoByIdArtifact = Object.freeze({
+	id: 'query:react-fixture-todo-by-id',
+	document:
+		'query ReactFixtureTodoById($id: ID!) { todo(id: $id) { id title status } }',
+	protocol: Object.freeze({
+		version: 1,
+		schemaHash: REACT_FIXTURE_SCHEMA,
+		surface: REACT_FIXTURE_SURFACE,
+		operation: 'query:react-fixture-todo-by-id',
+		trustedPresets: Object.freeze([])
+	}),
+	variableCodec: TodoByIdVariables,
+	roots: Object.freeze([
+		Object.freeze({
+			responseKey: 'todo',
+			field: 'todo',
+			cardinality: 'one',
+			nullable: true,
+			arguments: Object.freeze({
+				id: Object.freeze({ kind: 'variable', name: 'id' })
+			}),
+			dependencies: Object.freeze(['todos']),
+			selection: todoSelection
+		})
+	])
+});
+
+function deferred() {
+	let resolveDeferred;
+	let rejectDeferred;
+	let settled = false;
+	const promise = new Promise((resolve, reject) => {
+		resolveDeferred = resolve;
+		rejectDeferred = reject;
+	});
+	return {
+		promise,
+		get settled() {
+			return settled;
+		},
+		resolve(value) {
+			if (settled) return;
+			settled = true;
+			resolveDeferred(value);
+		},
+		reject(error) {
+			if (settled) return;
+			settled = true;
+			rejectDeferred(error);
+		}
+	};
+}
+
+export class ControlledReplicaTransport {
+	fetches = [];
+	lives = [];
+
+	fetch(request) {
+		const response = deferred();
+		const entry = { request, response };
+		this.fetches.push(entry);
+		return response.promise;
+	}
+
+	subscribe(request, observer) {
+		const entry = {
+			request,
+			observer,
+			closed: false
+		};
+		this.lives.push(entry);
+		return () => {
+			entry.closed = true;
+		};
+	}
+
+	latestOpenLive() {
+		return [...this.lives].reverse().find((entry) => !entry.closed);
+	}
+}
+
+export function todoFrame(
+	artifact,
+	rows,
+	{
+		cacheScope = 'cache:user-a',
+		position = '1',
+		source = 'query',
+		reset = false,
+		errors
+	} = {}
+) {
+	const root = artifact.roots[0];
+	const isMany = root.cardinality === 'many';
+	const operation =
+		source === 'live' ? artifact.live?.id : artifact.protocol.operation;
+	if (operation === undefined) {
+		throw new TypeError('live fixture frame requires a live artifact');
+	}
+	const dataValue = isMany ? rows : (rows[0] ?? null);
+	const records = rows.map((row, index) => ({
+		path: isMany
+			? [root.responseKey, String(index)]
+			: [root.responseKey],
+		model: TodoModel.id,
+		scopeToken: `record:${row.id}`,
+		incarnation: '1',
+		revision: position,
+		tombstone: false
+	}));
+	const resume = {
+		projection: 'todos-projector',
+		position,
+		token: `resume:${cacheScope}:${position}`
+	};
+	return {
+		data: { [root.responseKey]: dataValue },
+		...(errors === undefined ? {} : { errors }),
+		extensions: {
+			distributed: {
+				protocolVersion: 1,
+				schemaHash: artifact.protocol.schemaHash,
+				cacheScope,
+				operation,
+				trustedPresets: [],
+				snapshot: {
+					scopeToken: `snapshot:${root.field}`,
+					recordsComplete: true,
+					indexesComparable: true,
+					records,
+					indexes: [
+						{
+							projection: 'todos-projector',
+							scopeToken: `index:${root.field}`,
+							position,
+							resume
+						}
+					],
+					observations: []
+				},
+				...(source === 'live'
+					? {
+							live: {
+								supported: true,
+								reset,
+								cursors: [resume]
+							}
+						}
+					: {})
+			}
+		}
+	};
+}
+
+function currentTitle(snapshot) {
+	return snapshot.data.todos?.[0]?.title;
+}
+
+/**
+ * Framework-neutral adapter behavioral contract.
+ *
+ * `mount` is the only framework-specific input. It binds one operation and
+ * returns the familiar external-store controls, allowing Svelte and React to
+ * execute the same state-transition assertions.
+ */
+export async function assertReplicaAdapterConformance({ mount }) {
+	const transport = new ControlledReplicaTransport();
+	const replica = createDistributedReplica({ transport });
+	const commandRuntime = createReplicaCommandRuntime(
+		replica,
+		Object.freeze({
+			dispatch: () => Promise.reject(new Error('unused command transport'))
+		}),
+		{ revalidateTodos: RequiredRevalidationCommand }
+	);
+	const adapter = await mount({
+		replica,
+		artifact: TodosArtifact,
+		variables: {},
+		options: { live: true }
+	});
+
+	try {
+		assert.equal(adapter.getSnapshot().status, 'loading');
+		assert.equal(adapter.getSnapshot().fetching, true);
+		assert.equal(transport.fetches.length, 1);
+		assert.equal(transport.lives.length, 1);
+
+		await adapter.settle(() => {
+			transport.fetches[0].response.resolve(
+				todoFrame(
+					TodosArtifact,
+					[{ id: 'todo-1', title: 'server', status: 'open' }],
+					{ position: '1' }
+				)
+			);
+		});
+		assert.equal(adapter.getSnapshot().status, 'ready');
+		assert.equal(adapter.getSnapshot().live, 'active');
+		assert.equal(currentTitle(adapter.getSnapshot()), 'server');
+
+		const fetchesBeforeOptimism = transport.fetches.length;
+		await adapter.settle(() => {
+			replica.createOptimisticLayer('cmd-pending', (writer) => {
+				writer.writeRecord(TodoModel, 'todo-1', {
+					fields: { title: 'optimistic' }
+				});
+			});
+			assert.equal(replica.markOptimisticLayerAccepted('cmd-pending'), true);
+		});
+		assert.equal(currentTitle(adapter.getSnapshot()), 'optimistic');
+		const optimisticRevalidation =
+			transport.fetches.length > fetchesBeforeOptimism
+				? transport.fetches.at(-1)
+				: undefined;
+
+		const firstLive = transport.latestOpenLive();
+		assert.ok(firstLive, 'live subscription must remain attached');
+		await adapter.settle(() => {
+			firstLive.observer.next(
+				todoFrame(
+					TodosArtifact,
+					[{ id: 'todo-1', title: 'stale-server', status: 'open' }],
+					{ position: '2', source: 'live', reset: true }
+				)
+			);
+		});
+		assert.equal(
+			currentTitle(adapter.getSnapshot()),
+			'optimistic',
+			'accepted optimism must remain above a stale projected read'
+		);
+		if (optimisticRevalidation !== undefined) {
+			await adapter.settle(() => {
+				optimisticRevalidation.response.resolve(
+					todoFrame(
+						TodosArtifact,
+						[{ id: 'todo-1', title: 'superseded-query', status: 'open' }],
+						{ position: '3' }
+					)
+				);
+			});
+			assert.equal(
+				currentTitle(adapter.getSnapshot()),
+				'optimistic',
+				'a query from before the live handoff must be generation-fenced'
+			);
+		}
+
+		await adapter.settle(() => {
+			replica.confirmOptimisticLayer('cmd-pending', (writer) =>
+				writer.writeRecord(TodoModel, 'todo-1', '3', {
+					fields: { title: 'projected' }
+				})
+			);
+		});
+		assert.equal(
+			currentTitle(adapter.getSnapshot()),
+			'projected',
+			'Projected confirmation must atomically replace the pending layer'
+		);
+
+		await adapter.settle(() => {
+			replica.createOptimisticLayer('cmd-rejected', (writer) => {
+				writer.writeRecord(TodoModel, 'todo-1', {
+					fields: { title: 'will-roll-back' }
+				});
+			});
+		});
+		assert.equal(currentTitle(adapter.getSnapshot()), 'will-roll-back');
+		await adapter.settle(() => {
+			assert.equal(replica.rejectOptimisticLayer('cmd-rejected'), true);
+		});
+		assert.equal(currentTitle(adapter.getSnapshot()), 'projected');
+
+		const backgroundFetches = transport.fetches.filter(
+			(entry) => !entry.response.settled
+		);
+		if (backgroundFetches.length > 0) {
+			await adapter.settle(() => {
+				for (const entry of backgroundFetches) {
+					entry.response.resolve(
+						todoFrame(
+							TodosArtifact,
+							[{ id: 'todo-1', title: 'projected', status: 'done' }],
+							{ position: '30' }
+						)
+					);
+				}
+			});
+		}
+		assert.equal(
+			transport.fetches.some((entry) => !entry.response.settled),
+			false,
+			'pre-existing conservative revalidation must be drained'
+		);
+
+		const activeLive = transport.latestOpenLive();
+		assert.ok(activeLive, 'live subscription must survive query handoff');
+		await adapter.settle(() => {
+			activeLive.observer.next(
+				todoFrame(
+					TodosArtifact,
+					[{ id: 'todo-1', title: 'live', status: 'done' }],
+					{ position: '40', source: 'live', reset: true }
+				)
+			);
+		});
+		assert.equal(currentTitle(adapter.getSnapshot()), 'live');
+
+		const liveHandoffFetches = transport.fetches.filter(
+			(entry) => !entry.response.settled
+		);
+		if (liveHandoffFetches.length > 0) {
+			await adapter.settle(() => {
+				for (const entry of liveHandoffFetches) {
+					entry.response.resolve(
+						todoFrame(
+							TodosArtifact,
+							[{ id: 'todo-1', title: 'live', status: 'done' }],
+							{ position: '45' }
+						)
+					);
+				}
+			});
+		}
+		assert.equal(
+			transport.fetches.some((entry) => !entry.response.settled),
+			false,
+			'live handoff revalidation must settle before explicit stale coverage'
+		);
+
+		const fetchesBeforeStale = transport.fetches.length;
+		await adapter.settle(() => {
+			assert.equal(
+				replica.markIndexStale({ field: 'todos' }, 'adapter-conformance'),
+				true
+			);
+		});
+		assert.equal(
+			transport.fetches.length,
+			fetchesBeforeStale + 1,
+			'stale transition must start a fresh revalidation'
+		);
+		assert.equal(adapter.getSnapshot().status, 'stale');
+		assert.equal(
+			adapter.getSnapshot().complete,
+			true,
+			'stale complete data must remain renderable during revalidation'
+		);
+		assert.equal(
+			currentTitle(adapter.getSnapshot()),
+			'live',
+			'stale-while-revalidate must retain the last materialized view'
+		);
+		assert.equal(adapter.getSnapshot().fetching, true);
+		const staleFetch = transport.fetches.at(-1);
+		await adapter.settle(() => {
+			staleFetch.response.resolve(
+				todoFrame(
+					TodosArtifact,
+					[{ id: 'todo-1', title: 'revalidated', status: 'done' }],
+					{ position: '50' }
+				)
+			);
+		});
+		assert.equal(adapter.getSnapshot().status, 'ready');
+		assert.equal(currentTitle(adapter.getSnapshot()), 'revalidated');
+
+		await adapter.settle(() => {
+			void adapter.refetch();
+		});
+		const failedFetch = transport.fetches.at(-1);
+		await adapter.settle(() => {
+			failedFetch.response.reject(new Error('adapter conformance network failure'));
+		});
+		assert.equal(adapter.getSnapshot().status, 'error');
+		assert.equal(adapter.getSnapshot().errors.length, 1);
+
+		await adapter.settle(() => {
+			void adapter.refetch();
+		});
+		const oldIdentityFetch = transport.fetches.at(-1);
+		await adapter.settle(() => {
+			replica.invalidateAuthorization();
+		});
+		assert.equal(oldIdentityFetch.request.signal.aborted, true);
+		assert.equal(adapter.getSnapshot().status, 'loading');
+		const newIdentityFetch = transport.fetches.at(-1);
+		assert.notEqual(newIdentityFetch, oldIdentityFetch);
+
+		await adapter.settle(() => {
+			oldIdentityFetch.response.resolve(
+				todoFrame(
+					TodosArtifact,
+					[{ id: 'todo-old', title: 'late-old-user', status: 'open' }],
+					{ cacheScope: 'cache:user-a', position: '51' }
+				)
+			);
+		});
+		assert.notEqual(currentTitle(adapter.getSnapshot()), 'late-old-user');
+
+		await adapter.settle(() => {
+			newIdentityFetch.response.resolve(
+				todoFrame(
+					TodosArtifact,
+					[{ id: 'todo-new', title: 'new-user', status: 'open' }],
+					{ cacheScope: 'cache:user-b', position: '1' }
+				)
+			);
+		});
+		assert.equal(adapter.getSnapshot().status, 'ready');
+		assert.equal(currentTitle(adapter.getSnapshot()), 'new-user');
+		assert.equal(replica.scope.cacheScope, 'cache:user-b');
+	} finally {
+		commandRuntime.dispose();
+		await adapter.dispose();
+	}
+}
diff --git a/js/tests/fixtures/react-todo-app.mjs b/js/tests/fixtures/react-todo-app.mjs
new file mode 100644
index 00000000..72b83179
--- /dev/null
+++ b/js/tests/fixtures/react-todo-app.mjs
@@ -0,0 +1,54 @@
+import { createElement } from 'react';
+
+import { useDistributedQuery } from '../../dist/react/index.js';
+import {
+	OpenTodosArtifact,
+	TodoByIdArtifact
+} from './adapter-conformance.mjs';
+
+/**
+ * Minimal generated-artifact consumer. It owns no cache, transport, auth, or
+ * command reconciliation logic; the command prop has the same nested shape as
+ * a generated ReplicaCommandRuntime.
+ */
+export function ReactTodoApp({ commands, selectedId = 'todo-1' }) {
+	const todos = useDistributedQuery(OpenTodosArtifact);
+	const todo = useDistributedQuery(TodoByIdArtifact, { id: selectedId });
+	const rows = todos.data.todos ?? [];
+	const selected = todo.data.todo;
+
+	return createElement(
+		'main',
+		{
+			'data-list-status': todos.status,
+			'data-detail-status': todo.status
+		},
+		createElement(
+			'ul',
+			{ 'data-testid': 'todo-list' },
+			...rows.map((row) =>
+				createElement(
+					'li',
+					{ key: row.id, 'data-todo-id': row.id },
+					createElement('span', { 'data-testid': `list-${row.id}` }, row.title),
+					createElement(
+						'button',
+						{
+							type: 'button',
+							onClick: () => commands.todo.complete({ todoId: row.id })
+						},
+						'Complete'
+					)
+				)
+			)
+		),
+		createElement(
+			'aside',
+			{
+				'data-testid': 'todo-detail',
+				'data-todo-id': selected?.id
+			},
+			selected?.title ?? 'Loading'
+		)
+	);
+}
diff --git a/js/tests/protocol-transport.test.mjs b/js/tests/protocol-transport.test.mjs
new file mode 100644
index 00000000..a54bac68
--- /dev/null
+++ b/js/tests/protocol-transport.test.mjs
@@ -0,0 +1,548 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import {
+	DISTRIBUTED_PROTOCOL_VERSION,
+	DistributedProtocolError,
+	parseDistributedProtocolEnvelope,
+	parseGraphqlResponseExtensions,
+	requestGraphql,
+	subscribe
+} from '@hops-ops/distributed';
+
+function distributedEnvelope() {
+	return {
+		protocolVersion: DISTRIBUTED_PROTOCOL_VERSION,
+		schemaHash: 'sha256:schema-v2',
+		cacheScope: 'opaque:principal-and-grants',
+		operation: 'sha256:operation',
+		command: {
+			commandId: 'opaque-command-id',
+			causationId: 'opaque-causation-id',
+			state: 'accepted_pending_projection',
+			consistency: 'fact',
+			expects: [
+				{
+					projection: 'todos',
+					model: 'TodoView',
+					scopeToken: 'opaque:tenant-key-and-generation'
+				}
+			],
+			observations: [
+				{
+					causationId: 'opaque-causation-id',
+					projection: 'todos',
+					model: 'TodoView',
+					scopeToken: 'opaque:tenant-key-and-generation'
+				}
+			],
+			records: [
+				{
+					model: 'TodoView',
+					scopeToken: 'opaque:record-scope',
+					incarnation: '18446744073709551614',
+					revision: '18446744073709551615',
+					tombstone: false
+				}
+			]
+		},
+		snapshot: {
+			scopeToken: 'opaque:query-snapshot',
+			recordsComplete: true,
+			indexesComparable: true,
+			records: [
+				{
+					path: ['live'],
+					model: 'TodoView',
+					scopeToken: 'opaque:record-scope',
+					incarnation: '18446744073709551614',
+					revision: '18446744073709551615',
+					tombstone: false
+				}
+			],
+			indexes: [
+				{
+					projection: 'todos',
+					scopeToken: 'opaque:index-scope',
+					position: '18446744073709551615',
+					resume: {
+						projection: 'todos',
+						position: '18446744073709551615',
+						token: 'opaque:resume'
+					}
+				}
+			],
+			observations: []
+		},
+		live: {
+			supported: true,
+			reset: false,
+			cursors: [
+				{
+					projection: 'todos',
+					position: '18446744073709551615',
+					token: 'opaque:resume'
+				}
+			]
+		},
+		trustedPresets: [],
+		futureMetadata: { retained: true }
+	};
+}
+
+function responseExtensions() {
+	return {
+		traceId: 'trace-1',
+		distributed: distributedEnvelope()
+	};
+}
+
+test('protocol parser validates receipts while retaining future metadata opaquely', () => {
+	const extensions = parseGraphqlResponseExtensions(responseExtensions());
+	assert.deepEqual(extensions, responseExtensions());
+	assert.equal(
+		typeof extensions.distributed.snapshot.records[0].incarnation,
+		'string'
+	);
+	assert.equal(
+		extensions.distributed.snapshot.records[0].revision,
+		'18446744073709551615'
+	);
+	assert.equal(
+		extensions.distributed.command.expects[0].scopeToken,
+		'opaque:tenant-key-and-generation'
+	);
+	assert.equal(Object.isFrozen(extensions.distributed.command.expects), true);
+	assert.equal(Object.isFrozen(extensions.distributed.command.records), true);
+	assert.equal(Object.isFrozen(extensions.distributed.snapshot.indexes), true);
+	assert.equal(Object.isFrozen(extensions.distributed.live.cursors), true);
+	assert.equal(Object.isFrozen(extensions.distributed), true);
+
+	assert.throws(
+		() =>
+			parseDistributedProtocolEnvelope({
+				...distributedEnvelope(),
+				protocolVersion: 3
+			}),
+		(error) =>
+			error instanceof DistributedProtocolError &&
+			error.code === 'DISTRIBUTED_PROTOCOL_VERSION_UNSUPPORTED' &&
+			!error.message.includes('3')
+	);
+	assert.throws(
+		() =>
+			parseDistributedProtocolEnvelope({
+				...distributedEnvelope(),
+				command: {
+					...distributedEnvelope().command,
+					expects: [
+						{
+							projection: 'todos',
+							model: 'TodoView',
+							scopeToken: 9007199254740992
+						}
+					]
+				}
+			}),
+		(error) =>
+			error instanceof DistributedProtocolError &&
+			error.code === 'DISTRIBUTED_PROTOCOL_INVALID' &&
+			error.path.endsWith('.scopeToken')
+	);
+	assert.throws(
+		() =>
+			parseDistributedProtocolEnvelope({
+				...distributedEnvelope(),
+				snapshot: {
+					...distributedEnvelope().snapshot,
+					indexes: [
+						{
+							...distributedEnvelope().snapshot.indexes[0],
+							position: '18446744073709551616'
+						}
+					]
+				}
+			}),
+		(error) =>
+			error instanceof DistributedProtocolError &&
+			error.path.endsWith('.position')
+	);
+
+	const {
+		recordsComplete: _recordsComplete,
+		indexesComparable: _indexesComparable,
+		...legacySnapshot
+	} = distributedEnvelope().snapshot;
+	assert.throws(
+		() =>
+			parseDistributedProtocolEnvelope({
+				...distributedEnvelope(),
+				snapshot: { ...legacySnapshot, complete: true }
+			}),
+		(error) =>
+			error instanceof DistributedProtocolError &&
+			error.path ===
+				'extensions.distributed.snapshot.recordsComplete'
+	);
+	assert.throws(
+		() =>
+			parseDistributedProtocolEnvelope({
+				...distributedEnvelope(),
+				snapshot: {
+					...distributedEnvelope().snapshot,
+					indexesComparable: undefined
+				}
+			}),
+		(error) =>
+			error instanceof DistributedProtocolError &&
+			error.path ===
+				'extensions.distributed.snapshot.indexesComparable'
+	);
+});
+
+test('protocol parser requires exact live snapshot alignment', () => {
+	const envelope = distributedEnvelope();
+	assert.throws(
+		() =>
+			parseDistributedProtocolEnvelope({
+				...envelope,
+				snapshot: undefined,
+				live: { supported: false, reset: true, cursors: [] }
+			}),
+		(error) =>
+			error instanceof DistributedProtocolError &&
+			error.path === 'extensions.distributed.snapshot'
+	);
+	assert.throws(
+		() =>
+			parseDistributedProtocolEnvelope({
+				...envelope,
+				snapshot: {
+					...envelope.snapshot,
+					indexesComparable: false,
+					indexes: [],
+					observations: []
+				},
+				live: { supported: true, reset: true, cursors: [] }
+			}),
+		(error) =>
+			error instanceof DistributedProtocolError &&
+			error.path ===
+				'extensions.distributed.snapshot.indexesComparable'
+	);
+
+	const mismatches = [
+		[
+			'empty supported cursor inventory',
+			{
+				...envelope,
+				snapshot: { ...envelope.snapshot, indexes: [] },
+				live: { ...envelope.live, cursors: [] }
+			}
+		],
+		[
+			'cursor count',
+			{
+				...envelope,
+				live: { ...envelope.live, cursors: [] }
+			}
+		],
+		[
+			'cursor projection',
+			{
+				...envelope,
+				live: {
+					...envelope.live,
+					cursors: [
+						{ ...envelope.live.cursors[0], projection: 'other-projector' }
+					]
+				}
+			}
+		],
+		[
+			'cursor position',
+			{
+				...envelope,
+				live: {
+					...envelope.live,
+					cursors: [{ ...envelope.live.cursors[0], position: '1' }]
+				}
+			}
+		],
+		[
+			'cursor token',
+			{
+				...envelope,
+				live: {
+					...envelope.live,
+					cursors: [{ ...envelope.live.cursors[0], token: 'opaque:other' }]
+				}
+			}
+		],
+		[
+			'missing snapshot resume',
+			{
+				...envelope,
+				snapshot: {
+					...envelope.snapshot,
+					indexes: envelope.snapshot.indexes.map(
+						({ resume: _resume, ...index }) => index
+					)
+				}
+			}
+		]
+	];
+	for (const [description, invalidEnvelope] of mismatches) {
+		assert.throws(
+			() => parseDistributedProtocolEnvelope(invalidEnvelope),
+			(error) =>
+				error instanceof DistributedProtocolError &&
+				error.path === 'extensions.distributed.live.cursors',
+			description
+		);
+	}
+});
+
+test('protocol parser accepts 64 resume cursors and rejects 65', () => {
+	const cursors = Array.from({ length: 65 }, (_, index) => ({
+		projection: `projection-${index}`,
+		position: String(index + 1),
+		token: `opaque:resume-${index}`
+	}));
+	const indexes = cursors.map((cursor, index) => ({
+		projection: cursor.projection,
+		scopeToken: `opaque:index-${index}`,
+		position: cursor.position,
+		resume: cursor
+	}));
+	const envelope = distributedEnvelope();
+	const accepted = parseDistributedProtocolEnvelope({
+		...envelope,
+		snapshot: { ...envelope.snapshot, indexes: indexes.slice(0, 64) },
+		live: { supported: true, reset: false, cursors: cursors.slice(0, 64) }
+	});
+	assert.equal(accepted.live.cursors.length, 64);
+	assert.equal(accepted.snapshot.indexes.length, 64);
+
+	assert.throws(
+		() =>
+			parseDistributedProtocolEnvelope({
+				...envelope,
+				live: { supported: true, reset: false, cursors }
+			}),
+		(error) =>
+			error instanceof DistributedProtocolError &&
+			error.path === 'extensions.distributed.live.cursors'
+	);
+	assert.throws(
+		() =>
+			parseDistributedProtocolEnvelope({
+				...envelope,
+				snapshot: { ...envelope.snapshot, indexes },
+				live: { supported: false, reset: true, cursors: [] }
+			}),
+		(error) =>
+			error instanceof DistributedProtocolError &&
+			error.path === 'extensions.distributed.snapshot.indexes'
+	);
+});
+
+test('HTTP preserves a valid Distributed envelope without adding metadata to data', async () => {
+	const extensions = responseExtensions();
+	const result = await requestGraphql(
+		'/graphql',
+		'mutation Change { change { ok } }',
+		{},
+		{},
+		{
+			fetch: async () => ({
+				status: 202,
+				json: async () => ({
+					data: { change: { ok: true } },
+					extensions
+				})
+			})
+		}
+	);
+
+	assert.deepEqual(result, {
+		data: { change: { ok: true } },
+		errors: undefined,
+		extensions,
+		status: 202
+	});
+	assert.deepEqual(result.data.change, { ok: true });
+	assert.equal('distributed' in result.data.change, false);
+});
+
+test('HTTP rejects malformed or incompatible Distributed envelopes fail closed', async () => {
+	const incompatible = await requestGraphql(
+		'/graphql',
+		'query Read { item { id } }',
+		{},
+		{},
+		{
+			fetch: async () => ({
+				status: 200,
+				json: async () => ({
+					data: { item: { id: 'must-not-be-trusted' } },
+					extensions: {
+						distributed: {
+							...distributedEnvelope(),
+							protocolVersion: 99
+						}
+					}
+				})
+			})
+		}
+	);
+	assert.equal(incompatible.data, undefined);
+	assert.equal(
+		incompatible.errors[0].extensions.code,
+		'DISTRIBUTED_PROTOCOL_VERSION_UNSUPPORTED'
+	);
+	assert.equal('extensions' in incompatible, false);
+
+	const malformed = await requestGraphql(
+		'/graphql',
+		'query Read { item { id } }',
+		{},
+		{},
+		{
+			fetch: async () => ({
+				status: 200,
+				json: async () => ({
+					data: { item: { id: 'must-not-be-trusted' } },
+					extensions: {
+						distributed: {
+							...distributedEnvelope(),
+							cacheScope: { tenant: 'hidden' }
+						}
+					}
+				})
+			})
+		}
+	);
+	assert.equal(malformed.data, undefined);
+	assert.equal(
+		malformed.errors[0].extensions.code,
+		'DISTRIBUTED_PROTOCOL_INVALID'
+	);
+	assert.match(malformed.errors[0].message, /cacheScope$/);
+	assert.equal(malformed.errors[0].message.includes('hidden'), false);
+});
+
+class FakeWebSocket {
+	static OPEN = 1;
+	static instances = [];
+
+	constructor(url, protocol) {
+		this.url = url;
+		this.protocol = protocol;
+		this.readyState = 0;
+		this.sent = [];
+		this.closeCount = 0;
+		FakeWebSocket.instances.push(this);
+	}
+
+	send(value) {
+		this.sent.push(JSON.parse(value));
+	}
+
+	close() {
+		this.closeCount += 1;
+		this.readyState = 3;
+	}
+
+	open() {
+		this.readyState = FakeWebSocket.OPEN;
+		this.onopen?.({});
+	}
+
+	message(message) {
+		this.onmessage?.({ data: JSON.stringify(message) });
+	}
+}
+
+test('GraphQL-WS preserves valid envelopes and terminates on incompatible frames', () => {
+	FakeWebSocket.instances.length = 0;
+	const next = [];
+	const errors = [];
+	const stop = subscribe(
+		'subscription Live { live { id } }',
+		{},
+		{
+			onNext: (result) => next.push(result),
+			onError: (error) => errors.push(error)
+		},
+		{
+			webSocket: FakeWebSocket,
+			httpUrl: '/graphql',
+			resume: distributedEnvelope().live.cursors
+		}
+	);
+	const socket = FakeWebSocket.instances[0];
+	socket.open();
+	socket.message({ type: 'connection_ack' });
+	assert.deepEqual(socket.sent[1].payload.extensions, {
+		distributed: {
+			resume: {
+				cursors: distributedEnvelope().live.cursors
+			}
+		}
+	});
+	socket.message({
+		type: 'next',
+		id: '1',
+		payload: {
+			data: { live: { id: 'row-1' } },
+			extensions: responseExtensions()
+		}
+	});
+	assert.deepEqual(next[0], {
+		data: { live: { id: 'row-1' } },
+		extensions: responseExtensions()
+	});
+	assert.deepEqual(errors, []);
+	stop();
+
+	const rejectedNext = [];
+	const rejectedErrors = [];
+	subscribe(
+		'subscription Live { live { id } }',
+		{},
+		{
+			onNext: (result) => rejectedNext.push(result),
+			onError: (error) => rejectedErrors.push(error)
+		},
+		{ webSocket: FakeWebSocket, httpUrl: '/graphql' }
+	);
+	const rejectedSocket = FakeWebSocket.instances[1];
+	rejectedSocket.open();
+	rejectedSocket.message({ type: 'connection_ack' });
+	rejectedSocket.message({
+		type: 'next',
+		id: '1',
+		payload: {
+			data: { live: { id: 'must-not-be-trusted' } },
+			extensions: {
+				distributed: {
+					...distributedEnvelope(),
+					protocolVersion: 7
+				}
+			}
+		}
+	});
+
+	assert.deepEqual(rejectedNext, []);
+	assert.equal(rejectedErrors.length, 1);
+	assert.equal(
+		rejectedErrors[0].code,
+		'DISTRIBUTED_PROTOCOL_VERSION_UNSUPPORTED'
+	);
+	assert.deepEqual(rejectedSocket.sent.at(-1), {
+		type: 'complete',
+		id: '1'
+	});
+	assert.equal(rejectedSocket.closeCount, 1);
+});
diff --git a/js/tests/react-adapter.test.mjs b/js/tests/react-adapter.test.mjs
new file mode 100644
index 00000000..8aba2fb1
--- /dev/null
+++ b/js/tests/react-adapter.test.mjs
@@ -0,0 +1,361 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import test from 'node:test';
+
+import {
+	act,
+	createElement
+} from 'react';
+import { renderToString } from 'react-dom/server';
+import { create as createTestRenderer } from 'react-test-renderer';
+import { build } from 'esbuild';
+
+import {
+	DistributedProvider,
+	useDistributedQuery
+} from '../dist/react/index.js';
+import {
+	createDistributedReplica
+} from '../dist/replica/index.js';
+import {
+	assertReplicaAdapterConformance,
+	OpenTodosArtifact,
+	REACT_FIXTURE_SCHEMA,
+	TodoByIdArtifact,
+	TodoModel,
+	TodosArtifact,
+	todoFrame
+} from './fixtures/adapter-conformance.mjs';
+import { ReactTodoApp } from './fixtures/react-todo-app.mjs';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+async function flushMicrotasks() {
+	for (let iteration = 0; iteration < 8; iteration += 1) {
+		await Promise.resolve();
+	}
+}
+
+async function mountReactQuery({
+	replica,
+	artifact,
+	variables,
+	options
+}) {
+	let current;
+
+	function Probe() {
+		current = useDistributedQuery(artifact, variables, options);
+		return createElement('output', {
+			'data-status': current.status,
+			'data-fetching': String(current.fetching)
+		});
+	}
+
+	let renderer;
+	await act(async () => {
+		renderer = createTestRenderer(
+			createElement(
+				DistributedProvider,
+				{ replica },
+				createElement(Probe)
+			)
+		);
+		await flushMicrotasks();
+	});
+
+	return {
+		getSnapshot() {
+			assert.ok(current, 'React query must render a snapshot');
+			return current;
+		},
+		async settle(action) {
+			await act(async () => {
+				action?.();
+				await flushMicrotasks();
+			});
+		},
+		refetch() {
+			return current.refresh();
+		},
+		async dispose() {
+			await act(async () => {
+				renderer.unmount();
+				await flushMicrotasks();
+			});
+		}
+	};
+}
+
+function noOpCommands() {
+	return Object.freeze({
+		todo: Object.freeze({
+			complete: async () => Object.freeze({ state: 'accepted' })
+		})
+	});
+}
+
+function seedTodoReplica(
+	replica,
+	{
+		id = 'todo-1',
+		title,
+		cacheScope,
+		position = '1'
+	}
+) {
+	const row = { id, title, status: 'open', completed: false };
+	replica.writeResult(
+		OpenTodosArtifact,
+		{},
+		todoFrame(OpenTodosArtifact, [row], { cacheScope, position }),
+		'ssr'
+	);
+	replica.writeResult(
+		TodoByIdArtifact,
+		{ id },
+		todoFrame(TodoByIdArtifact, [row], {
+			cacheScope,
+			position: String(Number(position) + 1)
+		}),
+		'ssr'
+	);
+}
+
+function renderTodoApp(replica, selectedId = 'todo-1') {
+	return renderToString(
+		createElement(
+			DistributedProvider,
+			{ replica },
+			createElement(ReactTodoApp, {
+				commands: noOpCommands(),
+				selectedId
+			})
+		)
+	);
+}
+
+test('React passes the shared replica adapter conformance contract', async () => {
+	await assertReplicaAdapterConformance({ mount: mountReactQuery });
+});
+
+test('minimal React fixture shares normalized detail/list state and generated command shape', async () => {
+	const replica = createDistributedReplica();
+	seedTodoReplica(replica, {
+		title: 'Shared record',
+		cacheScope: 'cache:fixture'
+	});
+	const commandCalls = [];
+	const commands = {
+		todo: {
+			async complete(input) {
+				commandCalls.push(input);
+				replica.createOptimisticLayer('fixture-command', (writer) => {
+					writer.writeRecord(TodoModel, input.todoId, {
+						fields: {
+							title: 'Optimistic in both views',
+							status: 'done',
+							completed: true
+						}
+					});
+				});
+				return { state: 'accepted_pending_projection' };
+			}
+		}
+	};
+
+	let renderer;
+	await act(async () => {
+		renderer = createTestRenderer(
+			createElement(
+				DistributedProvider,
+				{ replica },
+				createElement(ReactTodoApp, { commands })
+			)
+		);
+		await flushMicrotasks();
+	});
+
+	const listTitles = () =>
+		renderer.root
+			.findAll(
+				(node) =>
+					typeof node.props?.['data-testid'] === 'string' &&
+					node.props['data-testid'].startsWith('list-')
+			)
+			.map((node) => node.children.join(''));
+	const detailTitle = () =>
+		renderer.root.findByProps({ 'data-testid': 'todo-detail' }).children.join('');
+	assert.deepEqual(listTitles(), ['Shared record']);
+	assert.equal(detailTitle(), 'Shared record');
+
+	const button = renderer.root.findByType('button');
+	await act(async () => {
+		await button.props.onClick();
+		await flushMicrotasks();
+	});
+	assert.deepEqual(commandCalls, [{ todoId: 'todo-1' }]);
+	assert.deepEqual(
+		listTitles(),
+		[],
+		'the optimistic status change must remove the record from the open filter'
+	);
+	assert.equal(detailTitle(), 'Optimistic in both views');
+
+	await act(async () => {
+		replica.confirmOptimisticLayer('fixture-command', (writer) => {
+			writer.writeRecord(TodoModel, 'todo-1', '3', {
+				fields: {
+					title: 'Projected in both views',
+					status: 'done',
+					completed: true
+				}
+			});
+			writer.writeIndex(
+				{
+					field: 'todos',
+					arguments: {},
+					coverage: { kind: 'complete' },
+					dependencies: ['todos'],
+					complete: true
+				},
+				[],
+				'3'
+			);
+		});
+		await flushMicrotasks();
+	});
+	assert.deepEqual(listTitles(), []);
+	assert.equal(detailTitle(), 'Projected in both views');
+
+	await act(async () => {
+		renderer.unmount();
+		await flushMicrotasks();
+	});
+});
+
+test('React SSR uses the core request snapshot for hydration and rejects scope mismatch', async () => {
+	const serverReplica = createDistributedReplica();
+	seedTodoReplica(serverReplica, {
+		title: 'Server request A',
+		cacheScope: 'cache:ssr-a'
+	});
+	const serverHtml = renderTodoApp(serverReplica);
+	const dehydrated = serverReplica.dehydrate();
+
+	const browserReplica = createDistributedReplica();
+	assert.equal(
+		browserReplica.hydrate(
+			JSON.parse(JSON.stringify(dehydrated)),
+			dehydrated.scope
+		),
+		true
+	);
+	const hydrationHtml = renderTodoApp(browserReplica);
+	assert.equal(hydrationHtml, serverHtml);
+	assert.match(hydrationHtml, /Server request A/);
+
+	const mismatchedReplica = createDistributedReplica();
+	assert.equal(
+		mismatchedReplica.hydrate(dehydrated, {
+			...dehydrated.scope,
+			cacheScope: 'cache:other-user'
+		}),
+		false
+	);
+	const mismatchedHtml = renderTodoApp(mismatchedReplica);
+	assert.doesNotMatch(mismatchedHtml, /Server request A/);
+	assert.match(mismatchedHtml, /Loading/);
+});
+
+test('concurrent React server renders keep replicas and authorization scopes isolated', async () => {
+	const first = createDistributedReplica();
+	const second = createDistributedReplica();
+	seedTodoReplica(first, {
+		id: 'todo-a',
+		title: 'Request A only',
+		cacheScope: 'cache:request-a'
+	});
+	seedTodoReplica(second, {
+		id: 'todo-b',
+		title: 'Request B only',
+		cacheScope: 'cache:request-b'
+	});
+
+	const [firstHtml, secondHtml] = await Promise.all([
+		Promise.resolve().then(() => renderTodoApp(first, 'todo-a')),
+		Promise.resolve().then(() => renderTodoApp(second, 'todo-b'))
+	]);
+	assert.match(firstHtml, /Request A only/);
+	assert.doesNotMatch(firstHtml, /Request B only/);
+	assert.match(secondHtml, /Request B only/);
+	assert.doesNotMatch(secondHtml, /Request A only/);
+	assert.equal(first.dehydrate().scope.cacheScope, 'cache:request-a');
+	assert.equal(second.dehydrate().scope.cacheScope, 'cache:request-b');
+});
+
+test('React hook requires an explicit provider', () => {
+	function MissingProvider() {
+		useDistributedQuery(TodosArtifact);
+		return null;
+	}
+	assert.throws(
+		() => renderToString(createElement(MissingProvider)),
+		/inside a DistributedProvider/
+	);
+});
+
+test('React and SvelteKit subpaths remain bundle-isolated and React is optional', async () => {
+	const packageJson = JSON.parse(
+		await readFile(new URL('../package.json', import.meta.url), 'utf8')
+	);
+	assert.match(packageJson.peerDependencies.react, /18/);
+	assert.equal(packageJson.peerDependenciesMeta.react.optional, true);
+
+	const [reactBundle, svelteBundle] = await Promise.all([
+		build({
+			entryPoints: ['src/react/index.ts'],
+			bundle: true,
+			format: 'esm',
+			platform: 'browser',
+			external: ['react'],
+			metafile: true,
+			write: false,
+			logLevel: 'silent'
+		}),
+		build({
+			entryPoints: ['src/sveltekit/index.ts'],
+			bundle: true,
+			format: 'esm',
+			platform: 'browser',
+			metafile: true,
+			write: false,
+			logLevel: 'silent'
+		})
+	]);
+	const reactInputs = Object.keys(reactBundle.metafile.inputs);
+	const svelteInputs = Object.keys(svelteBundle.metafile.inputs);
+	assert.equal(
+		reactInputs.some((path) => path.includes('/sveltekit/')),
+		false,
+		'React bundle must not pull in the SvelteKit adapter'
+	);
+	assert.equal(
+		svelteInputs.some((path) => path.includes('/react/')),
+		false,
+		'SvelteKit bundle must not pull in the React adapter'
+	);
+	assert.equal(
+		svelteInputs.some((path) => path.includes('node_modules/react/')),
+		false,
+		'SvelteKit bundle must not require the optional React peer'
+	);
+});
+
+test('React fixture protocol remains on the exact generated surface', () => {
+	assert.equal(TodosArtifact.protocol.schemaHash, REACT_FIXTURE_SCHEMA);
+	assert.deepEqual(TodosArtifact.protocol.surface, {
+		kind: 'role',
+		name: 'user'
+	});
+});
diff --git a/js/tests/replica-command-artifacts.test.mjs b/js/tests/replica-command-artifacts.test.mjs
new file mode 100644
index 00000000..34b7a677
--- /dev/null
+++ b/js/tests/replica-command-artifacts.test.mjs
@@ -0,0 +1,989 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	prepareReplicaCommand,
+	ReplicaCommandContractError,
+	verifyReplicaCommandReceipt
+} from '../dist/replica/index.js';
+
+const HASH_A = `sha256:${'a'.repeat(64)}`;
+const HASH_B = `sha256:${'b'.repeat(64)}`;
+const HASH_C = `sha256:${'c'.repeat(64)}`;
+const COMMAND_ID = '018f47de-3d2a-7abc-8abc-0123456789ab';
+const OTHER_COMMAND_ID = '018f47de-3d2a-7def-8def-0123456789ab';
+const GENERATED_UUID = '018f47de-3d2a-7123-8123-0123456789ab';
+const GENERATED_ULID = '01J0Z6YV6E0000000000000000';
+
+const scalarField = (
+	name,
+	typeName = 'String',
+	codec = 'string',
+	overrides = {}
+) =>
+	Object.freeze({
+		name,
+		typeName,
+		nullable: false,
+		list: false,
+		itemNullable: false,
+		codec,
+		...overrides
+	});
+
+const nestedField = (name, definition, overrides = {}) =>
+	Object.freeze({
+		name,
+		typeName: definition.name,
+		nullable: false,
+		list: false,
+		itemNullable: false,
+		nested: definition,
+		...overrides
+	});
+
+const META_TYPE = Object.freeze({
+	name: 'CreateMetaInput',
+	fields: Object.freeze([
+		scalarField('count', 'Int', 'int32'),
+		scalarField('note', 'String', 'string', { nullable: true })
+	])
+});
+
+const CREATE_TYPE = Object.freeze({
+	name: 'CreateTodoInput',
+	fields: Object.freeze([
+		scalarField('code', 'ID'),
+		scalarField('id', 'ID'),
+		nestedField('meta', META_TYPE),
+		scalarField('title')
+	])
+});
+
+const OUTPUT = Object.freeze({
+	kind: 'object',
+	definition: Object.freeze({
+		name: 'CommandResult',
+		fields: Object.freeze([
+			scalarField('value', 'JSON', 'json', { nullable: true })
+		])
+	})
+});
+const INPUT = Object.freeze({
+	kind: 'object',
+	definition: CREATE_TYPE
+});
+const JSON_IMPORT_INPUT = Object.freeze({
+	kind: 'object',
+	definition: Object.freeze({
+		name: 'ImportTodosInput',
+		fields: Object.freeze([scalarField('payload', 'JSON', 'json')])
+	})
+});
+const PROJECTED_OUTPUT = Object.freeze({
+	kind: 'object',
+	definition: Object.freeze({
+		name: 'Todo',
+		fields: Object.freeze([
+			scalarField('id', 'ID'),
+			scalarField('title')
+		])
+	})
+});
+
+const inputValue = (path) => Object.freeze({ kind: 'input', path: Object.freeze(path) });
+const constantValue = (value) => Object.freeze({ kind: 'constant', value });
+const effectField = (field, value) => Object.freeze({ field, value });
+const key = (...fields) => Object.freeze({ fields: Object.freeze(fields) });
+
+const TODO_RELATIONSHIP = Object.freeze({
+	sourceModel: 'Todo',
+	field: 'related',
+	targetModel: 'Todo'
+});
+
+function baseArtifact(overrides = {}) {
+	return {
+		version: 1,
+		name: 'todo.create',
+		mutationField: 'createTodo',
+		document:
+			'mutation Client_createTodo($commandId: ID!, $input: CreateTodoInput!) { createTodo(commandId: $commandId, input: $input) }',
+		operationHash: HASH_A,
+		protocol: {
+			version: 1,
+			schemaHash: HASH_B,
+			protocolHash: HASH_C,
+			surface: { kind: 'role', name: 'user' },
+			operation: HASH_A,
+			trustedPresets: []
+		},
+		input: INPUT,
+		output: OUTPUT,
+		inputDefaults: {
+			version: 1,
+			defaults: [
+				{ path: ['code'], generator: 'ulid' },
+				{ path: ['id'], generator: 'uuid_v7' }
+			]
+		},
+		consistency: 'fact',
+		effects: {
+			version: 1,
+			operations: [
+				{
+					kind: 'upsert',
+					model: 'Todo',
+					key: key(effectField('id', inputValue(['id']))),
+					fields: [
+						effectField('title', inputValue(['title'])),
+						effectField('count', inputValue(['meta', 'count']))
+					]
+				}
+			],
+			fallback: 'revalidate'
+		},
+		confirmations: {
+			version: 1,
+			kind: 'finite',
+			expected: [
+				{
+					projector: 'todos',
+					model: 'Todo',
+					key: key(effectField('id', inputValue(['id'])))
+				}
+			],
+			fallback: 'revalidate'
+		},
+		revalidation: {
+			version: 1,
+			required: false,
+			dependencies: ['todo_rows'],
+			models: ['Todo'],
+			relationships: []
+		},
+		...overrides
+	};
+}
+
+function projectedArtifact(directOverrides = {}) {
+	return baseArtifact({
+		output: PROJECTED_OUTPUT,
+		consistency: 'projected',
+		confirmations: undefined,
+		directProjection: {
+			topology: {
+				version: 1,
+				name: 'todos',
+				digest: HASH_C
+			},
+			model: 'Todo',
+			identityFields: ['id'],
+			partition: inputValue(['meta', 'count']),
+			changeEpoch: 'todos-v1',
+			...directOverrides
+		}
+	});
+}
+
+function receipt(prepared, state, overrides = {}) {
+	return {
+		commandId: prepared.commandId,
+		causationId: 'opaque-causation',
+		state,
+		consistency: prepared.consistency,
+		expects: [],
+		observations: [],
+		records: [],
+		...overrides
+	};
+}
+
+function expectation(projection, model, token) {
+	return { projection, model, scopeToken: token };
+}
+
+test('preparation fills omitted UUIDv7/ULID defaults once and closes every input expression', () => {
+	let uuidCalls = 0;
+	let ulidCalls = 0;
+	const callerInput = {
+		title: 'Ship it',
+		meta: { count: 3 }
+	};
+	const prepared = prepareReplicaCommand(baseArtifact(), callerInput, {
+		commandId: COMMAND_ID,
+		generators: {
+			uuidV7: () => {
+				uuidCalls += 1;
+				return GENERATED_UUID;
+			},
+			ulid: () => {
+				ulidCalls += 1;
+				return GENERATED_ULID;
+			}
+		}
+	});
+
+	assert.deepEqual(callerInput, { title: 'Ship it', meta: { count: 3 } });
+	assert.equal(prepared.input.id, GENERATED_UUID);
+	assert.equal(prepared.input.code, GENERATED_ULID);
+	assert.equal(prepared.transport.variables.input, prepared.input);
+	assert.deepEqual(prepared.transport.variables, {
+		commandId: COMMAND_ID,
+		input: {
+			code: GENERATED_ULID,
+			id: GENERATED_UUID,
+			meta: { count: 3 },
+			title: 'Ship it'
+		}
+	});
+	assert.deepEqual(prepared.optimistic.operations[0], {
+		kind: 'upsert',
+		model: 'Todo',
+		key: { fields: [{ field: 'id', value: GENERATED_UUID }] },
+		fields: [
+			{ field: 'title', value: 'Ship it' },
+			{ field: 'count', value: 3 }
+		]
+	});
+	assert.equal(prepared.confirmations.expected[0].key.fields[0].value, GENERATED_UUID);
+	assert.equal(uuidCalls, 1);
+	assert.equal(ulidCalls, 1);
+
+	// The prepared value itself is the retry unit; reading/reusing it performs no work.
+	assert.equal(prepared.transport.variables.input.id, GENERATED_UUID);
+	assert.equal(prepared.optimistic.operations[0].key.fields[0].value, GENERATED_UUID);
+	assert.equal(uuidCalls, 1);
+	assert.equal(ulidCalls, 1);
+});
+
+test('explicit defaulted fields are retained and their generators never run', () => {
+	let calls = 0;
+	const prepared = prepareReplicaCommand(
+		baseArtifact(),
+		{
+			code: 'caller-code',
+			id: 'caller-id',
+			meta: { count: 1 },
+			title: 'Explicit'
+		},
+		{
+			commandId: COMMAND_ID.toUpperCase(),
+			generators: {
+				uuidV7: () => {
+					calls += 1;
+					return GENERATED_UUID;
+				},
+				ulid: () => {
+					calls += 1;
+					return GENERATED_ULID;
+				}
+			}
+		}
+	);
+
+	assert.equal(prepared.commandId, COMMAND_ID);
+	assert.equal(prepared.input.id, 'caller-id');
+	assert.equal(prepared.input.code, 'caller-code');
+	assert.equal(calls, 0);
+});
+
+test('real default generators produce canonical values', () => {
+	const prepared = prepareReplicaCommand(
+		baseArtifact(),
+		{ meta: { count: 1 }, title: 'Generated' },
+		{ commandId: COMMAND_ID }
+	);
+
+	assert.match(prepared.input.id, /^[0-9a-f]{8}-[0-9a-f]{4}-7/);
+	assert.match(prepared.input.code, /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/);
+});
+
+test('none inputs and typed JSON fields produce exact canonical transport variables', () => {
+	const noInput = prepareReplicaCommand(
+		baseArtifact({
+			name: 'todo.rebuild',
+			mutationField: 'rebuildTodos',
+			document:
+				'mutation Client_rebuildTodos($commandId: ID!) { rebuildTodos(commandId: $commandId) }',
+			input: { kind: 'none' },
+			inputDefaults: undefined,
+			consistency: 'accepted',
+			effects: { version: 1, operations: [], fallback: 'revalidate' },
+			confirmations: undefined,
+			revalidation: {
+				version: 1,
+				required: true,
+				dependencies: ['todo_rows'],
+				models: ['Todo'],
+				relationships: []
+			}
+		}),
+		undefined,
+		{ commandId: COMMAND_ID }
+	);
+	assert.deepEqual(noInput.transport.variables, { commandId: COMMAND_ID });
+	assert.equal(noInput.input, undefined);
+
+	const json = prepareReplicaCommand(
+		baseArtifact({
+			name: 'todo.import',
+			mutationField: 'importTodos',
+			document:
+				'mutation Client_importTodos($commandId: ID!, $input: ImportTodosInput!) { importTodos(commandId: $commandId, input: $input) }',
+			input: JSON_IMPORT_INPUT,
+			inputDefaults: undefined,
+			consistency: 'accepted',
+			effects: { version: 1, operations: [], fallback: 'revalidate' },
+			confirmations: undefined,
+			revalidation: {
+				version: 1,
+				required: true,
+				dependencies: ['todo_rows'],
+				models: ['Todo'],
+				relationships: []
+			}
+		}),
+		{ payload: { z: [2, 1], a: { y: true, x: null } } },
+		{ commandId: COMMAND_ID }
+	);
+	assert.deepEqual(Object.keys(json.input), ['payload']);
+	assert.deepEqual(Object.keys(json.input.payload), ['a', 'z']);
+	assert.deepEqual(Object.keys(json.input.payload.a), ['x', 'y']);
+	assert.equal(json.transport.variables.input, json.input);
+
+	const cyclic = {};
+	cyclic.self = cyclic;
+	assert.throws(
+		() =>
+			prepareReplicaCommand(
+				baseArtifact({
+					name: 'todo.import',
+					mutationField: 'importTodos',
+					document:
+						'mutation Client_importTodos($commandId: ID!, $input: ImportTodosInput!) { importTodos(commandId: $commandId, input: $input) }',
+					input: JSON_IMPORT_INPUT,
+					inputDefaults: undefined,
+					consistency: 'accepted',
+					effects: { version: 1, operations: [], fallback: 'revalidate' },
+					confirmations: undefined,
+					revalidation: {
+						version: 1,
+						required: true,
+						dependencies: ['todo_rows'],
+						models: ['Todo'],
+						relationships: []
+					}
+				}),
+				{ payload: cyclic },
+				{ commandId: COMMAND_ID }
+			),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.code === 'REPLICA_COMMAND_INPUT_INVALID'
+	);
+});
+
+test('nested paths resolve exactly and missing or type-invalid values fail closed', () => {
+	const nullableMeta = {
+		...META_TYPE,
+		fields: [
+			scalarField('count', 'Int', 'int32'),
+			scalarField('note', 'String', 'string', { nullable: true })
+		]
+	};
+	const artifact = baseArtifact({
+		input: {
+			kind: 'object',
+			definition: {
+				...CREATE_TYPE,
+				fields: [
+					scalarField('code', 'ID'),
+					scalarField('id', 'ID'),
+					nestedField('meta', nullableMeta),
+					scalarField('title')
+				]
+			}
+		},
+		effects: {
+			version: 1,
+			operations: [
+				{
+					kind: 'patch',
+					model: 'Todo',
+					key: key(effectField('id', inputValue(['id']))),
+					fields: [effectField('note', inputValue(['meta', 'note']))]
+				}
+			],
+			fallback: 'revalidate'
+		}
+	});
+
+	assert.throws(
+		() =>
+			prepareReplicaCommand(
+				artifact,
+				{ meta: { count: 1 }, title: 'Absent note' },
+				{
+					commandId: COMMAND_ID,
+					generators: {
+						uuidV7: () => GENERATED_UUID,
+						ulid: () => GENERATED_ULID
+					}
+				}
+			),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.code === 'REPLICA_COMMAND_INPUT_INVALID' &&
+			error.path === 'input.meta.note'
+	);
+	assert.throws(
+		() =>
+			prepareReplicaCommand(
+				baseArtifact(),
+				{ meta: { count: 'one' }, title: 'Wrong type' },
+				{
+					commandId: COMMAND_ID,
+					generators: {
+						uuidV7: () => GENERATED_UUID,
+						ulid: () => GENERATED_ULID
+					}
+				}
+			),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.code === 'REPLICA_COMMAND_INPUT_INVALID' &&
+			error.path === 'input.meta.count'
+	);
+	assert.throws(
+		() =>
+			prepareReplicaCommand(
+				baseArtifact(),
+				{ extra: true, meta: { count: 1 }, title: 'Unknown field' },
+				{
+					commandId: COMMAND_ID,
+					generators: {
+						uuidV7: () => GENERATED_UUID,
+						ulid: () => GENERATED_ULID
+					}
+				}
+			),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.path === 'input.extra'
+	);
+});
+
+test('the closed optimistic IR supports every declared effect kind', () => {
+	const artifact = baseArtifact({
+		effects: {
+			version: 1,
+			operations: [
+				{
+					kind: 'upsert',
+					model: 'Todo',
+					key: key(effectField('id', inputValue(['id']))),
+					fields: [effectField('title', inputValue(['title']))]
+				},
+				{
+					kind: 'patch',
+					model: 'Todo',
+					key: key(effectField('id', inputValue(['id']))),
+					fields: [effectField('rank', constantValue(2))]
+				},
+				{
+					kind: 'delete',
+					model: 'Todo',
+					key: key(effectField('id', inputValue(['id'])))
+				},
+				{
+					kind: 'link',
+					relationship: TODO_RELATIONSHIP,
+					source: key(effectField('id', inputValue(['id']))),
+					target: key(effectField('id', constantValue('target')))
+				},
+				{
+					kind: 'unlink',
+					relationship: TODO_RELATIONSHIP,
+					source: key(effectField('id', inputValue(['id']))),
+					target: key(effectField('id', constantValue('target')))
+				},
+				{ kind: 'invalidate_model', model: 'Todo' },
+				{
+					kind: 'invalidate_relationship',
+					relationship: TODO_RELATIONSHIP,
+					source: key(effectField('id', inputValue(['id'])))
+				}
+			],
+			fallback: 'revalidate'
+		},
+		revalidation: {
+			version: 1,
+			required: false,
+			dependencies: ['todo_rows', 'todo_links'],
+			models: ['Todo'],
+			relationships: [TODO_RELATIONSHIP]
+		}
+	});
+	const prepared = prepareReplicaCommand(
+		artifact,
+		{ meta: { count: 4 }, title: 'All effects' },
+		{
+			commandId: COMMAND_ID,
+			generators: {
+				uuidV7: () => GENERATED_UUID,
+				ulid: () => GENERATED_ULID
+			}
+		}
+	);
+
+	assert.deepEqual(
+		prepared.optimistic.operations.map(({ kind }) => kind),
+		[
+			'upsert',
+			'patch',
+			'delete',
+			'link',
+			'unlink',
+			'invalidate_model',
+			'invalidate_relationship'
+		]
+	);
+	assert.equal(prepared.optimistic.operations[0].key.fields[0].value, GENERATED_UUID);
+	assert.equal(prepared.optimistic.operations[1].fields[0].value, 2);
+	assert.equal(prepared.optimistic.operations[3].target.fields[0].value, 'target');
+});
+
+test('unknown generators/effects and unresolved trusted presets fail before optimism', () => {
+	const options = {
+		commandId: COMMAND_ID,
+		generators: {
+			uuidV7: () => GENERATED_UUID,
+			ulid: () => GENERATED_ULID
+		}
+	};
+	const input = { meta: { count: 1 }, title: 'Invalid IR' };
+
+	assert.throws(
+		() =>
+			prepareReplicaCommand(
+				baseArtifact({
+					protocol: {
+						version: 1,
+						schemaHash: HASH_B,
+						protocolHash: HASH_C,
+						operation: HASH_A,
+						trustedPresets: []
+					}
+				}),
+				input,
+				options
+			),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.path === 'artifact.protocol.surface'
+	);
+	assert.throws(
+		() =>
+			prepareReplicaCommand(
+				baseArtifact({
+					protocol: {
+						version: 1,
+						schemaHash: HASH_B,
+						protocolHash: HASH_C,
+						surface: { kind: 'role', name: 'user' },
+						operation: HASH_B,
+						trustedPresets: []
+					}
+				}),
+				input,
+				options
+			),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.path === 'artifact.protocol.operation'
+	);
+	assert.throws(
+		() =>
+			prepareReplicaCommand(
+				baseArtifact({
+					inputDefaults: {
+						version: 1,
+						defaults: [{ path: ['id'], generator: 'uuid_v4' }]
+					}
+				}),
+				input,
+				options
+			),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.code === 'REPLICA_COMMAND_ARTIFACT_INVALID'
+	);
+	assert.throws(
+		() =>
+			prepareReplicaCommand(
+				baseArtifact({
+					effects: {
+						version: 1,
+						operations: [{ kind: 'explode' }],
+						fallback: 'revalidate'
+					}
+				}),
+				input,
+				options
+			),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.path === 'artifact.effects.operations[0].kind'
+	);
+	assert.throws(
+		() =>
+			prepareReplicaCommand(
+				baseArtifact({
+					effects: {
+						version: 1,
+						operations: [
+							{
+								kind: 'patch',
+								model: 'Todo',
+								key: key(effectField('id', inputValue(['id']))),
+								fields: [
+									effectField('owner', {
+										kind: 'trusted_preset',
+										name: 'current_tenant'
+									})
+								]
+							}
+						],
+						fallback: 'revalidate'
+					}
+				}),
+				input,
+				options
+			),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.code === 'REPLICA_COMMAND_ARTIFACT_INVALID'
+	);
+	assert.throws(
+		() =>
+			prepareReplicaCommand(baseArtifact(), input, {
+				commandId: COMMAND_ID,
+				generators: {
+					uuidV7: () => 'not-a-uuid',
+					ulid: () => GENERATED_ULID
+				}
+			}),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.code === 'REPLICA_COMMAND_INPUT_INVALID'
+	);
+});
+
+test('finite receipts compare projector/model as an exact multiset including multiplicity', () => {
+	const finiteArtifact = baseArtifact({
+		confirmations: {
+			version: 1,
+			kind: 'finite',
+			expected: [
+				{
+					projector: 'todos',
+					model: 'Todo',
+					key: key(effectField('id', inputValue(['id'])))
+				},
+				{
+					projector: 'todos',
+					model: 'Todo',
+					key: key(effectField('id', inputValue(['code'])))
+				},
+				{
+					projector: 'search',
+					model: 'TodoSearch',
+					key: key(effectField('id', inputValue(['id'])))
+				}
+			],
+			fallback: 'revalidate'
+		}
+	});
+	const prepared = prepareReplicaCommand(
+		finiteArtifact,
+		{ meta: { count: 1 }, title: 'Receipt' },
+		{
+			commandId: COMMAND_ID,
+			generators: {
+				uuidV7: () => GENERATED_UUID,
+				ulid: () => GENERATED_ULID
+			}
+		}
+	);
+
+	assert.deepEqual(
+		verifyReplicaCommandReceipt(prepared, receipt(prepared, 'in_progress')),
+		{ kind: 'deferred', revalidate: false }
+	);
+	assert.deepEqual(
+		verifyReplicaCommandReceipt(
+			prepared,
+			receipt(prepared, 'accepted_pending_projection', {
+				expects: [
+					expectation('search', 'TodoSearch', 'token-3'),
+					expectation('todos', 'Todo', 'token-1'),
+					expectation('todos', 'Todo', 'token-2')
+				]
+			})
+		),
+		{ kind: 'matched', revalidate: false }
+	);
+	assert.throws(
+		() =>
+			verifyReplicaCommandReceipt(
+				prepared,
+				receipt(prepared, 'accepted_pending_projection', {
+					expects: [
+						expectation('search', 'TodoSearch', 'token-3'),
+						expectation('todos', 'Todo', 'token-1')
+					]
+				})
+			),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.code === 'REPLICA_COMMAND_RECEIPT_MISMATCH' &&
+			error.path === 'receipt.expects'
+	);
+	assert.throws(
+		() =>
+			verifyReplicaCommandReceipt(
+				prepared,
+				receipt(prepared, 'accepted_pending_projection')
+			),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.path === 'receipt.expects'
+	);
+	assert.throws(
+		() =>
+			verifyReplicaCommandReceipt(prepared, {
+				...receipt(prepared, 'accepted_pending_projection'),
+				commandId: OTHER_COMMAND_ID
+			}),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.path === 'receipt.commandId'
+	);
+	assert.throws(
+		() =>
+			verifyReplicaCommandReceipt(prepared, {
+				...receipt(prepared, 'accepted_pending_projection'),
+				consistency: 'accepted'
+			}),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.path === 'receipt.consistency'
+	);
+});
+
+test('unavailable confirmation contracts always force conservative revalidation', () => {
+	const artifact = baseArtifact({
+		consistency: 'accepted',
+		confirmations: {
+			version: 1,
+			kind: 'unavailable',
+			expected: [],
+			fallback: 'revalidate'
+		},
+		revalidation: {
+			version: 1,
+			required: true,
+			dependencies: ['todo_rows'],
+			models: ['Todo'],
+			relationships: []
+		}
+	});
+	const prepared = prepareReplicaCommand(
+		artifact,
+		{ meta: { count: 1 }, title: 'Unavailable' },
+		{
+			commandId: COMMAND_ID,
+			generators: {
+				uuidV7: () => GENERATED_UUID,
+				ulid: () => GENERATED_ULID
+			}
+		}
+	);
+
+	assert.deepEqual(
+		verifyReplicaCommandReceipt(
+			prepared,
+			receipt(prepared, 'accepted', {
+				expects: [expectation('hidden', 'Hidden', 'opaque')]
+			})
+		),
+		{
+			kind: 'revalidate',
+			revalidate: true,
+			reason: 'confirmation_unavailable'
+		}
+	);
+});
+
+test('accepted commands without finite confirmations require canonical revalidation', () => {
+	const invalid = baseArtifact({
+		consistency: 'accepted',
+		confirmations: undefined
+	});
+	const input = { meta: { count: 1 }, title: 'No finite fence' };
+	const options = {
+		commandId: COMMAND_ID,
+		generators: {
+			uuidV7: () => GENERATED_UUID,
+			ulid: () => GENERATED_ULID
+		}
+	};
+
+	assert.throws(
+		() => prepareReplicaCommand(invalid, input, options),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.path === 'artifact.revalidation.required'
+	);
+
+	const valid = baseArtifact({
+		consistency: 'accepted',
+		confirmations: undefined,
+		revalidation: {
+			...invalid.revalidation,
+			required: true
+		}
+	});
+	assert.equal(
+		prepareReplicaCommand(valid, input, options).revalidation.required,
+		true
+	);
+});
+
+test('projected commands close the direct projection partition from finalized input', () => {
+	const artifact = projectedArtifact();
+	const prepared = prepareReplicaCommand(
+		artifact,
+		{ meta: { count: 7 }, title: 'Projected' },
+		{
+			commandId: COMMAND_ID,
+			generators: {
+				uuidV7: () => GENERATED_UUID,
+				ulid: () => GENERATED_ULID
+			}
+		}
+	);
+
+	assert.equal(prepared.directProjection.partition, 7);
+	assert.equal(prepared.directProjection.topology.name, 'todos');
+	assert.deepEqual(prepared.directProjection.identityFields, ['id']);
+	assert.notEqual(
+		prepared.directProjection.identityFields,
+		artifact.directProjection.identityFields
+	);
+	assert.equal(Object.isFrozen(prepared.directProjection), true);
+	assert.equal(Object.isFrozen(prepared.directProjection.topology), true);
+	assert.equal(Object.isFrozen(prepared.directProjection.identityFields), true);
+	assert.deepEqual(
+		verifyReplicaCommandReceipt(prepared, receipt(prepared, 'projected')),
+		{ kind: 'matched', revalidate: false }
+	);
+});
+
+test('projected command identity facts reject missing, unknown, and duplicate fields', () => {
+	const input = { meta: { count: 7 }, title: 'Projected' };
+	const options = {
+		commandId: COMMAND_ID,
+		generators: {
+			uuidV7: () => GENERATED_UUID,
+			ulid: () => GENERATED_ULID
+		}
+	};
+	const cases = [
+		{
+			identityFields: undefined,
+			path: 'artifact.directProjection.identityFields'
+		},
+		{ identityFields: [], path: 'artifact.directProjection.identityFields' },
+		{
+			identityFields: ['missing'],
+			path: 'artifact.directProjection.identityFields[0]'
+		},
+		{
+			identityFields: ['id', 'id'],
+			path: 'artifact.directProjection.identityFields[1]'
+		}
+	];
+
+	for (const { identityFields, path } of cases) {
+		assert.throws(
+			() =>
+				prepareReplicaCommand(
+					projectedArtifact({ identityFields }),
+					input,
+					options
+				),
+			(error) =>
+				error instanceof ReplicaCommandContractError &&
+				error.code === 'REPLICA_COMMAND_ARTIFACT_INVALID' &&
+				error.path === path
+		);
+	}
+
+	assert.throws(
+		() =>
+			prepareReplicaCommand(
+				{
+					...projectedArtifact(),
+					output: OUTPUT
+				},
+				input,
+				options
+			),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.code === 'REPLICA_COMMAND_ARTIFACT_INVALID' &&
+			error.path === 'artifact.directProjection.identityFields[0]'
+	);
+});
+
+test('prepared command input, variables, effects, confirmations, and plans are deeply frozen', () => {
+	const prepared = prepareReplicaCommand(
+		baseArtifact(),
+		{ meta: { count: 2, note: 'nested' }, title: 'Frozen' },
+		{
+			commandId: COMMAND_ID,
+			generators: {
+				uuidV7: () => GENERATED_UUID,
+				ulid: () => GENERATED_ULID
+			}
+		}
+	);
+
+	for (const value of [
+		prepared,
+		prepared.input,
+		prepared.input.meta,
+		prepared.transport,
+		prepared.transport.protocol,
+		prepared.transport.variables,
+		prepared.optimistic,
+		prepared.optimistic.operations,
+		prepared.optimistic.operations[0],
+		prepared.optimistic.operations[0].key,
+		prepared.optimistic.operations[0].key.fields,
+		prepared.confirmations,
+		prepared.confirmations.expected,
+		prepared.confirmations.expected[0],
+		prepared.revalidation,
+		prepared.revalidation.dependencies,
+		prepared.revalidation.models,
+		prepared.revalidation.relationships
+	]) {
+		assert.equal(Object.isFrozen(value), true);
+	}
+	assert.throws(() => {
+		prepared.input.meta.count = 9;
+	}, TypeError);
+});
diff --git a/js/tests/replica-command-runtime.test.mjs b/js/tests/replica-command-runtime.test.mjs
new file mode 100644
index 00000000..ceebc896
--- /dev/null
+++ b/js/tests/replica-command-runtime.test.mjs
@@ -0,0 +1,2821 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	createReplicaCommandRuntime,
+	replicaCommandAuthority,
+	ReplicaCommandRuntimeError
+} from '../dist/replica/command-runtime.js';
+import {
+	createDistributedReplica,
+	replicaRecordKey
+} from '../dist/replica/index.js';
+
+const HASH_A = `sha256:${'a'.repeat(64)}`;
+const HASH_B = `sha256:${'b'.repeat(64)}`;
+const HASH_C = `sha256:${'c'.repeat(64)}`;
+const HASH_D = `sha256:${'d'.repeat(64)}`;
+const HASH_E = `sha256:${'e'.repeat(64)}`;
+const COMMAND_A = '018f47de-3d2a-7abc-8abc-0123456789ab';
+const COMMAND_B = '018f47de-3d2a-7def-8def-0123456789ab';
+const GENERATED_ID = '018f47de-3d2a-7123-8123-0123456789ab';
+const SURFACE = Object.freeze({ kind: 'role', name: 'user' });
+const SCOPE = Object.freeze({
+	protocolVersion: 1,
+	schemaHash: HASH_B,
+	cacheScope: 'scope:user'
+});
+const Todo = Object.freeze({ id: 'Todo', identityFields: Object.freeze(['id']) });
+const STATUS_DOCUMENT =
+	'query Distributed_CommandStatus($commandId: ID!) { commandStatus(commandId: $commandId) { state } }';
+const COMMAND_STATUS = Object.freeze({
+	name: 'Distributed_CommandStatus',
+	document: STATUS_DOCUMENT,
+	operationHash: HASH_D,
+	protocol: Object.freeze({
+		version: 1,
+		schemaHash: HASH_B,
+		protocolHash: HASH_C,
+		surface: SURFACE,
+		operation: HASH_D,
+		trustedPresets: Object.freeze([
+			Object.freeze({ name: 'owner', codec: 'string' })
+		])
+	})
+});
+
+const scalar = (name, typeName = 'String', codec = 'string', overrides = {}) =>
+	Object.freeze({
+		name,
+		typeName,
+		codec,
+		nullable: false,
+		list: false,
+		itemNullable: false,
+		...overrides
+	});
+
+const inputExpression = (path) =>
+	Object.freeze({ kind: 'input', path: Object.freeze(path) });
+const trustedPreset = (name) => Object.freeze({ kind: 'trusted_preset', name });
+const effectField = (field, value) => Object.freeze({ field, value });
+const effectKey = (...fields) => Object.freeze({ fields: Object.freeze(fields) });
+
+const TodoInput = Object.freeze({
+	name: 'TodoInput',
+	fields: Object.freeze([scalar('id', 'ID'), scalar('title')])
+});
+const TodoOutput = Object.freeze({
+	name: 'Todo',
+	fields: Object.freeze([scalar('id', 'ID'), scalar('title')])
+});
+const CommandOutput = Object.freeze({
+	name: 'CommandResult',
+	fields: Object.freeze([scalar('ok', 'Boolean', 'boolean')])
+});
+
+function artifact(overrides = {}) {
+	return Object.freeze({
+		version: 1,
+		name: 'todo.create',
+		mutationField: 'createTodo',
+		document:
+			'mutation Client_createTodo($commandId: ID!, $input: TodoInput!) { createTodo(commandId: $commandId, input: $input) }',
+		operationHash: HASH_A,
+		protocol: Object.freeze({
+			version: 1,
+			schemaHash: HASH_B,
+			protocolHash: HASH_C,
+			surface: SURFACE,
+			operation: HASH_A,
+			trustedPresets: Object.freeze([
+				Object.freeze({ name: 'owner', codec: 'string' })
+			])
+		}),
+		input: Object.freeze({ kind: 'object', definition: TodoInput }),
+		output: Object.freeze({ kind: 'object', definition: CommandOutput }),
+		consistency: 'fact',
+		effects: Object.freeze({
+			version: 1,
+			operations: Object.freeze([
+				Object.freeze({
+					kind: 'upsert',
+					model: 'Todo',
+					key: effectKey(effectField('id', inputExpression(['id']))),
+					fields: Object.freeze([
+						effectField('title', inputExpression(['title'])),
+						effectField('owner', trustedPreset('owner'))
+					])
+				})
+			]),
+			fallback: 'revalidate'
+		}),
+		confirmations: Object.freeze({
+			version: 1,
+			kind: 'finite',
+			expected: Object.freeze([
+				Object.freeze({
+					projector: 'todos',
+					model: 'Todo',
+					key: effectKey(effectField('id', inputExpression(['id'])))
+				})
+			]),
+			fallback: 'revalidate'
+		}),
+		trustedPresets: Object.freeze([
+			Object.freeze({ name: 'owner', codec: 'string' })
+		]),
+		revalidation: Object.freeze({
+			version: 1,
+			required: false,
+			dependencies: Object.freeze(['todos']),
+			models: Object.freeze(['Todo']),
+			relationships: Object.freeze([])
+		}),
+		...overrides
+	});
+}
+
+function commandEnvelope(commandId, options = {}) {
+	const state = options.state ?? 'accepted_pending_projection';
+	const consistency = options.consistency ?? 'fact';
+	const expects = options.expects ?? [
+		{ projection: 'todos', model: 'Todo', scopeToken: 'todo:scope' }
+	];
+	return {
+		data:
+			options.data === undefined
+				? { createTodo: { ok: true } }
+				: options.data,
+		errors: options.errors,
+		status: options.status ?? 200,
+		extensions: {
+			distributed: {
+				protocolVersion: 1,
+				schemaHash: HASH_B,
+				cacheScope: 'scope:user',
+				operation: options.operation ?? HASH_A,
+				trustedPresets:
+					options.trustedPresets ??
+					[{ name: 'owner', codec: 'string', value: 'user-1' }],
+				command: {
+					commandId,
+					causationId: options.causationId ?? `cause:${commandId}`,
+					state,
+					consistency,
+					expects,
+					observations: options.observations ?? [],
+					records: options.records ?? []
+				}
+			}
+		}
+	};
+}
+
+function scopeQueryArtifact(options = {}) {
+	const operation = options.operation ?? HASH_D;
+	const members = [
+		Object.freeze({
+			kind: 'scalar',
+			responseKey: 'id',
+			field: 'id',
+			codec: 'ID',
+			nullable: false
+		}),
+		...(options.includeTitle === false
+			? []
+			: [
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: 'title',
+						field: 'title',
+						codec: 'String',
+						nullable: false
+					})
+				])
+	];
+	return Object.freeze({
+		id: operation,
+		document:
+			options.includeTitle === false
+				? 'query ClientScopeId { todos { id } }'
+				: 'query ClientScope { todos { id title } }',
+		protocol: Object.freeze({
+			version: 1,
+			schemaHash: HASH_B,
+			surface: SURFACE,
+			operation,
+			trustedPresets: Object.freeze([
+				Object.freeze({ name: 'owner', codec: 'string' })
+			])
+		}),
+		variableCodec: Object.freeze({
+			version: 1,
+			limits: Object.freeze({
+				maxDepth: 8,
+				maxBoolWidth: 32,
+				maxInList: 64
+			}),
+			variables: Object.freeze({}),
+			inputs: Object.freeze({})
+		}),
+		roots: Object.freeze([
+			Object.freeze({
+				responseKey: 'todos',
+				field: 'todos',
+				cardinality: 'many',
+				nullable: false,
+				dependencies: Object.freeze(['todos']),
+				selection: Object.freeze({
+					typename: Todo.id,
+					storage: Object.freeze({
+						kind: 'normalized',
+						model: Todo.id,
+						identityFields: Todo.identityFields
+					}),
+					members: Object.freeze(members)
+				})
+			})
+		])
+	});
+}
+
+function scopeSnapshotEnvelope(position, options = {}) {
+	const resume = Object.freeze({
+		projection: 'todos',
+		position,
+		token: `resume:${position}`
+	});
+	return {
+		data: { todos: [] },
+		extensions: {
+			distributed: {
+				protocolVersion: 1,
+				schemaHash: HASH_B,
+				cacheScope: 'scope:user',
+				operation: options.operation ?? HASH_D,
+				trustedPresets: [
+					{ name: 'owner', codec: 'string', value: 'user-1' }
+				],
+				...(options.command === undefined
+					? {}
+					: { command: options.command }),
+				snapshot: {
+					scopeToken: 'snapshot:scope',
+					recordsComplete: true,
+					indexesComparable: true,
+					records: [],
+					indexes: [
+						{
+							projection: 'todos',
+							scopeToken: 'index:todos',
+							position,
+							resume
+						}
+					],
+					observations: options.observations ?? []
+				}
+			}
+		}
+	};
+}
+
+function scopeTodoSnapshotEnvelope(position, title, options = {}) {
+	const envelope = scopeSnapshotEnvelope(position, options);
+	envelope.data = { todos: [{ id: 'todo-1', title }] };
+	envelope.extensions.distributed.snapshot.records = [
+		{
+			path: ['todos', '0'],
+			model: Todo.id,
+			scopeToken: 'record:todo-1',
+			incarnation: '1',
+			revision: options.recordRevision ?? position,
+			tombstone: false
+		}
+	];
+	return envelope;
+}
+
+function scopeTodoIdSnapshotEnvelope(position, operation) {
+	const envelope = scopeSnapshotEnvelope(position, { operation });
+	envelope.data = { todos: [{ id: 'todo-1' }] };
+	envelope.extensions.distributed.snapshot.records = [
+		{
+			path: ['todos', '0'],
+			model: Todo.id,
+			scopeToken: 'record:todo-1',
+			incarnation: '1',
+			revision: position,
+			tombstone: false
+		}
+	];
+	return envelope;
+}
+
+function scopeLiveQueryArtifact() {
+	return Object.freeze({
+		...scopeQueryArtifact(),
+		live: Object.freeze({
+			id: HASH_E,
+			document: 'subscription ClientScopeLive { todos { id title } }'
+		})
+	});
+}
+
+function scopeLiveTodoSnapshotEnvelope(position, title) {
+	const envelope = scopeTodoSnapshotEnvelope(position, title, {
+		operation: HASH_E
+	});
+	const resume = envelope.extensions.distributed.snapshot.indexes[0].resume;
+	envelope.extensions.distributed.live = {
+		supported: true,
+		reset: true,
+		cursors: [resume]
+	};
+	return envelope;
+}
+
+function projectedTodoArtifact() {
+	return artifact({
+		name: 'todo.project',
+		mutationField: 'createTodo',
+		document:
+			'mutation Client_createTodo($commandId: ID!, $input: TodoInput!) { createTodo(commandId: $commandId, input: $input) { id title } }',
+		output: Object.freeze({ kind: 'object', definition: TodoOutput }),
+		consistency: 'projected',
+		confirmations: undefined,
+		directProjection: Object.freeze({
+			topology: Object.freeze({
+				version: 1,
+				name: 'todos',
+				digest: HASH_C
+			}),
+			model: Todo.id,
+			identityFields: Todo.identityFields,
+			changeEpoch: 'todos-v1'
+		})
+	});
+}
+
+async function directlyProjectTodo(
+	replica,
+	revision = '3',
+	title = 'projected-newer'
+) {
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(
+					commandEnvelope(request.commandId, {
+						state: 'projected',
+						consistency: 'projected',
+						expects: [],
+						data: {
+							createTodo: {
+								id: 'todo-1',
+								title
+							}
+						},
+						records: [
+							{
+								model: Todo.id,
+								scopeToken: 'record:todo-1',
+								incarnation: '1',
+								revision,
+								tombstone: false
+							}
+						]
+					})
+				)
+		},
+		{ projectTodo: projectedTodoArtifact() }
+	);
+	await runtime.commands.projectTodo(
+		{ id: 'todo-1', title },
+		{ commandId: COMMAND_A }
+	);
+	return runtime;
+}
+
+function statusEnvelope(commandId, options = {}) {
+	const state = options.state ?? 'accepted_pending_projection';
+	const envelope = commandEnvelope(commandId, {
+		...options,
+		state,
+		operation: options.operation ?? HASH_D,
+		data: { commandStatus: { state } }
+	});
+	if (options.omitMetadata) {
+		delete envelope.extensions.distributed.command;
+	}
+	return envelope;
+}
+
+class FakeReplica {
+	scope = SCOPE;
+	authorizationGeneration = 1;
+	base = new Map();
+	layers = new Map();
+	accepted = new Map();
+	contracts = [];
+	revalidations = [];
+	onRevalidate;
+	authority = {
+		generation: 1,
+		scope: SCOPE,
+		trustedPresets: Object.freeze([
+			Object.freeze({ name: 'owner', codec: 'string', value: 'user-1' })
+		]),
+		controller: new AbortController()
+	};
+
+	[replicaCommandAuthority] = (contract) => {
+		this.contracts.push(contract);
+		return Object.freeze({
+			read: () => ({
+				generation: this.authority.generation,
+				scope: this.authority.scope,
+				trustedPresets: this.authority.trustedPresets,
+				signal: this.authority.controller.signal
+			}),
+			dispose() {}
+		});
+	};
+
+	createOptimisticLayer(id, update, semanticChanges = []) {
+		if (this.layers.has(id)) throw new Error('optimistic layer already exists');
+		const operations = [];
+		update({
+			writeRecord: (model, identity, patch) =>
+				operations.push({
+					kind: 'write',
+					key: replicaRecordKey(model, identity),
+					fields: patch.fields ?? {}
+				}),
+			tombstoneRecord: (model, identity) =>
+				operations.push({
+					kind: 'delete',
+					key: replicaRecordKey(model, identity)
+				}),
+			writeIndex() {},
+			deleteIndex() {}
+		});
+		this.layers.set(id, {
+			operations,
+			semanticChanges,
+			state: 'optimistic'
+		});
+	}
+
+	markOptimisticLayerAccepted(id, receipt) {
+		const layer = this.layers.get(id);
+		if (!layer) return false;
+		layer.state = 'accepted';
+		this.accepted.set(id, receipt);
+		return true;
+	}
+
+	rejectOptimisticLayer(id) {
+		this.accepted.delete(id);
+		return this.layers.delete(id);
+	}
+
+	confirmOptimisticLayer(id, update) {
+		const result = update({
+			writeRecord: (model, identity, revision, patch) => {
+				const key = replicaRecordKey(model, identity);
+				this.base.set(key, {
+					revision: String(revision),
+					incarnation: String(patch.incarnation ?? revision),
+					fields: { ...(this.base.get(key)?.fields ?? {}), ...(patch.fields ?? {}) }
+				});
+				return true;
+			},
+			tombstoneRecord: () => true,
+			writeIndex: () => true,
+			deleteIndex: () => true
+		});
+		this.layers.delete(id);
+		this.accepted.delete(id);
+		return result;
+	}
+
+	revalidate(plan) {
+		this.revalidations.push(plan);
+		return this.onRevalidate?.(plan);
+	}
+
+	visible(model, identity) {
+		const key = replicaRecordKey(model, identity);
+		let record = this.base.get(key);
+		let value =
+			record === undefined
+				? undefined
+				: { revision: record.revision, fields: { ...record.fields } };
+		for (const layer of this.layers.values()) {
+			for (const operation of layer.operations) {
+				if (operation.key !== key) continue;
+				if (operation.kind === 'delete') value = undefined;
+				else {
+					value = {
+						revision: 'optimistic',
+						fields: { ...(value?.fields ?? {}), ...operation.fields }
+					};
+				}
+			}
+		}
+		return value;
+	}
+
+	invalidateAuthorization() {
+		this.authorizationGeneration += 1;
+		this.scope = undefined;
+		this.layers.clear();
+	}
+
+	// Unused DistributedReplica methods keep this test double honest at the seam.
+	read() {
+		throw new Error('unused');
+	}
+	watch() {
+		throw new Error('unused');
+	}
+	writeResult() {
+		throw new Error('unused');
+	}
+	dehydrate() {
+		throw new Error('unused');
+	}
+	hydrate() {
+		throw new Error('unused');
+	}
+	tombstoneRecord() {
+		throw new Error('unused');
+	}
+	markIndexStale() {
+		throw new Error('unused');
+	}
+	retainRecord() {}
+	releaseRecord() {}
+	gc() {
+		return [];
+	}
+	inspectRecord() {
+		return undefined;
+	}
+	inspectIndex() {
+		return undefined;
+	}
+}
+
+test('real replica authority gates commands on its server-issued scope inventory', async () => {
+	const replica = createDistributedReplica();
+	const command = artifact();
+	const scopeOperation = Object.freeze({
+		id: HASH_D,
+		document: 'query ClientScope { __typename }',
+		protocol: Object.freeze({
+			version: 1,
+			schemaHash: HASH_B,
+			surface: SURFACE,
+			operation: HASH_D,
+			trustedPresets: Object.freeze([
+				Object.freeze({ name: 'owner', codec: 'string' })
+			])
+		}),
+		variableCodec: Object.freeze({
+			version: 1,
+			limits: Object.freeze({
+				maxDepth: 8,
+				maxBoolWidth: 32,
+				maxInList: 64
+			}),
+			variables: Object.freeze({}),
+			inputs: Object.freeze({})
+		}),
+		roots: Object.freeze([
+			Object.freeze({
+				responseKey: 'todos',
+				field: 'todos',
+				cardinality: 'many',
+				nullable: false,
+				dependencies: Object.freeze(['todos']),
+				selection: Object.freeze({
+					typename: Todo.id,
+					storage: Object.freeze({
+						kind: 'normalized',
+						model: Todo.id,
+						identityFields: Todo.identityFields
+					}),
+					members: Object.freeze([
+						Object.freeze({
+							kind: 'scalar',
+							responseKey: 'id',
+							field: 'id',
+							codec: 'ID',
+							nullable: false
+						}),
+						Object.freeze({
+							kind: 'scalar',
+							responseKey: 'title',
+							field: 'title',
+							codec: 'String',
+							nullable: false
+						})
+					])
+				})
+			})
+		])
+	});
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(
+					commandEnvelope(request.commandId, {
+						observations: [
+							{
+								causationId: `cause:${request.commandId}`,
+								projection: 'todos',
+								model: 'Todo',
+								scopeToken: 'todo:scope'
+							}
+						]
+					})
+				)
+		},
+		{ createTodo: command }
+	);
+
+	await assert.rejects(
+		runtime.commands.createTodo(
+			{ id: 'todo-before-scope', title: 'blocked' },
+			{ commandId: COMMAND_A }
+		),
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_AUTHORITY_UNAVAILABLE'
+	);
+	replica.writeResult(
+		scopeOperation,
+		{},
+		{
+			extensions: {
+				distributed: {
+					protocolVersion: 1,
+					schemaHash: HASH_B,
+					cacheScope: 'scope:user',
+					operation: HASH_D,
+					trustedPresets: [
+						{ name: 'owner', codec: 'string', value: 'user-1' }
+					]
+				}
+			}
+		},
+		'network'
+	);
+
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-after-scope', title: 'allowed' },
+		{ commandId: COMMAND_B }
+	);
+	assert.ok(replica.inspectRecord(Todo, 'todo-after-scope'));
+	replica.writeResult(
+		scopeOperation,
+		{},
+		{
+			data: { todos: [] },
+			extensions: {
+				distributed: {
+					protocolVersion: 1,
+					schemaHash: HASH_B,
+					cacheScope: 'scope:user',
+					operation: HASH_D,
+					trustedPresets: [
+						{ name: 'owner', codec: 'string', value: 'user-1' }
+					],
+					command: receipt.metadata,
+					snapshot: {
+						scopeToken: 'snapshot:scope',
+						recordsComplete: true,
+						indexesComparable: true,
+						records: [],
+						indexes: [],
+						observations: [
+							{
+								causationId: receipt.metadata.causationId,
+								projection: 'todos',
+								model: 'Todo',
+								scopeToken: 'todo:scope'
+							}
+						]
+					}
+				}
+			}
+		},
+		'network'
+	);
+	assert.equal((await receipt.projected).state, 'projected');
+	assert.equal(replica.inspectRecord(Todo, 'todo-after-scope'), undefined);
+	runtime.dispose();
+});
+
+test('lower snapshot from the active source retires causally satisfied optimism and resolves projected', async () => {
+	const replica = createDistributedReplica();
+	const command = artifact();
+	const scopeOperation = scopeQueryArtifact();
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(commandEnvelope(request.commandId))
+		},
+		{ createTodo: command }
+	);
+
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeSnapshotEnvelope('5'),
+		'network'
+	);
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-lower', title: 'pending' },
+		{ commandId: COMMAND_B }
+	);
+	let projected;
+	void receipt.projected.then((outcome) => {
+		projected = outcome;
+	});
+
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeSnapshotEnvelope('4', {
+			command: receipt.metadata,
+			observations: [
+				{
+					causationId: receipt.metadata.causationId,
+					projection: 'todos',
+					model: 'Todo',
+					scopeToken: 'todo:scope'
+				}
+			]
+		}),
+		'network'
+	);
+	await Promise.resolve();
+	assert.equal(projected?.state, 'projected');
+
+	// The transaction retired the old layer even though its index position was
+	// lower; the same identity can be used for a fresh test layer.
+	replica.createOptimisticLayer(COMMAND_B, () => undefined);
+	assert.equal(replica.rejectOptimisticLayer(COMMAND_B), true);
+	runtime.dispose();
+});
+
+test('binder registers the exact preset union and retries one frozen prepared unit', async () => {
+	const replica = new FakeReplica();
+	let uuidCalls = 0;
+	const requests = [];
+	let acceptedEnvelope;
+	const transport = {
+		async dispatch(request) {
+			requests.push(request);
+			assert.equal(replica.visible(Todo, GENERATED_ID).fields.owner, 'user-1');
+			assert.equal(
+				replica.visible(Todo, GENERATED_ID).fields.__typename,
+				Todo.id
+			);
+			if (requests.length === 1) throw new Error('ambiguous disconnect');
+			acceptedEnvelope = commandEnvelope(request.commandId, {
+				observations: [
+					{
+						causationId: `cause:${request.commandId}`,
+						projection: 'todos',
+						model: 'Todo',
+						scopeToken: 'todo:scope'
+					}
+				]
+			});
+			return acceptedEnvelope;
+		}
+	};
+	const command = artifact({
+		inputDefaults: Object.freeze({
+			version: 1,
+			defaults: Object.freeze([
+				Object.freeze({ path: Object.freeze(['id']), generator: 'uuid_v7' })
+			])
+		})
+	});
+	const runtime = createReplicaCommandRuntime(replica, transport, {
+		createTodo: command
+	});
+
+	const receipt = await runtime.commands.createTodo(
+		{ title: 'one' },
+		{
+			commandId: COMMAND_A,
+			transportRetries: 1,
+			generators: {
+				uuidV7: () => {
+					uuidCalls += 1;
+					return GENERATED_ID;
+				}
+			}
+		}
+	);
+
+	assert.equal(uuidCalls, 1);
+	assert.equal(requests.length, 2);
+	assert.equal(requests[0], requests[1], 'retry must reuse the exact request object');
+	assert.equal(requests[0].variables.input.id, GENERATED_ID);
+	assert.deepEqual(requests[0].extensions, {
+		distributed: {
+			client: {
+				surface: SURFACE,
+				schemaHash: HASH_B
+			}
+		}
+	});
+	assert.deepEqual(replica.contracts[0].trustedPresets, [
+		{ name: 'owner', codec: 'string' }
+	]);
+	assert.equal(replica.layers.get(COMMAND_A).state, 'accepted');
+	assert.equal(replica.layers.get(COMMAND_A).semanticChanges.length, 0);
+	assert.deepEqual(receipt.result, { ok: true });
+	assert.ok(Object.isFrozen(receipt.result));
+	let projectedSettled = false;
+	void receipt.projected.then(() => {
+		projectedSettled = true;
+	});
+	await Promise.resolve();
+	assert.equal(
+		projectedSettled,
+		false,
+		'receipt observations cannot confirm canonical cache ingestion'
+	);
+	replica.confirmOptimisticLayer(COMMAND_A, () => undefined);
+	runtime.observeResult(acceptedEnvelope);
+	assert.deepEqual(await receipt.projected, {
+		commandId: COMMAND_A,
+		state: 'projected',
+		metadata: receipt.metadata
+	});
+	runtime.dispose();
+});
+
+test('pre-dispatch validation and an already-aborted caller never create optimism', async () => {
+	const replica = new FakeReplica();
+	let dispatches = 0;
+	let statusReads = 0;
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch(request) {
+				dispatches += 1;
+				return Promise.resolve(commandEnvelope(request.commandId));
+			},
+			status(request) {
+				statusReads += 1;
+				return Promise.resolve(statusEnvelope(request.commandId));
+			}
+		},
+		{ createTodo: artifact() },
+		{ status: COMMAND_STATUS }
+	);
+
+	await assert.rejects(
+		runtime.commands.createTodo(
+			{ id: 'todo-invalid-retries', title: 'must-not-appear' },
+			{ commandId: COMMAND_A, transportRetries: -1 }
+		),
+		/transportRetries must be an integer/
+	);
+	assert.equal(replica.layers.size, 0);
+
+	const caller = new AbortController();
+	caller.abort('deadline elapsed before invocation');
+	await assert.rejects(
+		runtime.commands.createTodo(
+			{ id: 'todo-already-aborted', title: 'must-not-appear' },
+			{ commandId: COMMAND_B, signal: caller.signal }
+		),
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_ABORTED' &&
+			error.recovery === undefined
+	);
+	assert.equal(replica.layers.size, 0);
+	assert.equal(dispatches, 0);
+	assert.equal(statusReads, 0);
+	runtime.dispose();
+});
+
+test('same-scope hydration replaces confirmed state without invalidating accepted optimism', async () => {
+	const replica = createDistributedReplica();
+	const navigationReplica = createDistributedReplica();
+	const command = artifact();
+	const scopeOperation = scopeQueryArtifact();
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(commandEnvelope(request.commandId))
+		},
+		{ createTodo: command }
+	);
+
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeSnapshotEnvelope('1'),
+		'network'
+	);
+	const generation = replica.authorizationGeneration;
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-navigation', title: 'optimistic across navigation' },
+		{ commandId: COMMAND_A }
+	);
+	assert.ok(replica.inspectRecord(Todo, 'todo-navigation'));
+
+	navigationReplica.read(scopeOperation, {});
+	navigationReplica.writeResult(
+		scopeOperation,
+		{},
+		scopeSnapshotEnvelope('2'),
+		'network'
+	);
+	const navigationState = navigationReplica.dehydrate();
+	assert.equal(replica.hydrate(navigationState, SCOPE), true);
+	assert.equal(
+		replica.authorizationGeneration,
+		generation,
+		'same-scope hydration must not close command authority'
+	);
+	assert.ok(
+		replica.inspectRecord(Todo, 'todo-navigation'),
+		'accepted optimism must remain above the replacement confirmed base'
+	);
+
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeSnapshotEnvelope('3', {
+			command: receipt.metadata,
+			observations: [
+				{
+					causationId: receipt.metadata.causationId,
+					projection: 'todos',
+					model: 'Todo',
+					scopeToken: 'todo:scope'
+				}
+			]
+		}),
+		'network'
+	);
+	assert.equal((await receipt.projected).state, 'projected');
+	assert.equal(replica.inspectRecord(Todo, 'todo-navigation'), undefined);
+	runtime.dispose();
+});
+
+test('explicit rejection removes only its own layer and rebases later work', async () => {
+	const replica = new FakeReplica();
+	replica.base.set(replicaRecordKey(Todo, 'todo-1'), {
+		revision: '1',
+		incarnation: '1',
+		fields: { id: 'todo-1', title: 'base' }
+	});
+	let resolveDispatch;
+	const transport = {
+		dispatch: () =>
+			new Promise((resolve) => {
+				resolveDispatch = resolve;
+			})
+	};
+	const acceptedArtifact = artifact({
+		name: 'todo.rename',
+		mutationField: 'renameTodo',
+		document:
+			'mutation Client_renameTodo($commandId: ID!, $input: TodoInput!) { renameTodo(commandId: $commandId, input: $input) }',
+		consistency: 'accepted',
+		trustedPresets: Object.freeze([]),
+		confirmations: undefined,
+		revalidation: Object.freeze({
+			version: 1,
+			required: true,
+			dependencies: Object.freeze(['todos']),
+			models: Object.freeze(['Todo']),
+			relationships: Object.freeze([])
+		}),
+		effects: {
+			version: 1,
+			operations: [
+				{
+					kind: 'patch',
+					model: 'Todo',
+					key: effectKey(effectField('id', inputExpression(['id']))),
+					fields: [
+						effectField('title', inputExpression(['title']))
+					]
+				}
+			],
+			fallback: 'revalidate'
+		}
+	});
+	const runtime = createReplicaCommandRuntime(replica, transport, {
+		renameTodo: acceptedArtifact
+	});
+	const rejected = runtime.commands.renameTodo(
+		{ id: 'todo-1', title: 'A' },
+		{ commandId: COMMAND_A }
+	);
+	await Promise.resolve();
+	assert.equal(replica.visible(Todo, 'todo-1').fields.title, 'A');
+
+	replica.createOptimisticLayer(COMMAND_B, (writer) => {
+		writer.writeRecord(Todo, 'todo-1', { fields: { title: 'B' } });
+	});
+	resolveDispatch(
+		commandEnvelope(COMMAND_A, {
+			state: 'rejected',
+			consistency: 'accepted',
+			expects: [],
+			operation: HASH_A,
+			data: null,
+			errors: [{ message: 'denied', extensions: { code: 'REJECTED' } }]
+		})
+	);
+
+	await assert.rejects(
+		rejected,
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_REJECTED'
+	);
+	assert.equal(replica.layers.has(COMMAND_A), false);
+	assert.equal(replica.layers.has(COMMAND_B), true);
+	assert.equal(replica.visible(Todo, 'todo-1').fields.title, 'B');
+	runtime.dispose();
+});
+
+test('scoped GraphQL domain rejection without a receipt is not a protocol failure', async () => {
+	const replica = new FakeReplica();
+	replica.base.set(replicaRecordKey(Todo, 'todo-1'), {
+		revision: '1',
+		incarnation: '1',
+		fields: { id: 'todo-1', title: 'base' }
+	});
+	const response = commandEnvelope(COMMAND_A, {
+		data: null,
+		errors: [
+			{
+				message: 'rejected: cannot move: row already 0',
+				extensions: { code: 'REJECTED', status: 422 }
+			}
+		]
+	});
+	delete response.extensions.distributed.command;
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{ dispatch: () => Promise.resolve(response) },
+		{ createTodo: artifact() }
+	);
+
+	await assert.rejects(
+		runtime.commands.createTodo(
+			{ id: 'todo-1', title: 'optimistic' },
+			{ commandId: COMMAND_A }
+		),
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_REJECTED' &&
+			error.cause?.message === 'rejected: cannot move: row already 0'
+	);
+	assert.equal(replica.layers.has(COMMAND_A), false);
+	runtime.dispose();
+});
+
+test('Projected<T> validates and writes canonical data while retiring its layer atomically', async () => {
+	const replica = new FakeReplica();
+	replica.base.set(replicaRecordKey(Todo, 'todo-1'), {
+		revision: '1',
+		incarnation: '1',
+		fields: { id: 'todo-1', title: 'base' }
+	});
+	const projectedArtifact = artifact({
+		name: 'todo.project',
+		mutationField: 'projectTodo',
+		document:
+			'mutation Client_projectTodo($commandId: ID!, $input: TodoInput!) { projectTodo(commandId: $commandId, input: $input) { id title } }',
+		output: Object.freeze({ kind: 'object', definition: TodoOutput }),
+		consistency: 'projected',
+		trustedPresets: Object.freeze([]),
+		confirmations: undefined,
+		effects: {
+			version: 1,
+			operations: [
+				{
+					kind: 'patch',
+					model: 'Todo',
+					key: effectKey(effectField('id', inputExpression(['id']))),
+					fields: [
+						effectField('title', inputExpression(['title']))
+					]
+				}
+			],
+			fallback: 'revalidate'
+		},
+		directProjection: Object.freeze({
+			topology: Object.freeze({
+				version: 1,
+				name: 'todos',
+				digest: HASH_C
+			}),
+			model: 'Todo',
+			identityFields: Object.freeze(['id']),
+			changeEpoch: 'todos-v1'
+		})
+	});
+	const transport = {
+		async dispatch(request) {
+			assert.equal(replica.visible(Todo, 'todo-1').fields.title, 'optimistic');
+			return commandEnvelope(request.commandId, {
+				state: 'projected',
+				consistency: 'projected',
+				expects: [],
+				data: { projectTodo: { id: 'todo-1', title: 'canonical' } },
+				records: [
+					{
+						model: 'Todo',
+						scopeToken: 'record:todo-1',
+						incarnation: '1',
+						revision: '2',
+						tombstone: false
+					}
+				]
+			});
+		}
+	};
+	const runtime = createReplicaCommandRuntime(replica, transport, {
+		projectTodo: projectedArtifact
+	});
+
+	const receipt = await runtime.commands.projectTodo(
+		{ id: 'todo-1', title: 'optimistic' },
+		{ commandId: COMMAND_A }
+	);
+
+	assert.equal(replica.layers.has(COMMAND_A), false);
+	assert.deepEqual(replica.visible(Todo, 'todo-1'), {
+		revision: '2',
+		fields: { id: 'todo-1', title: 'canonical' }
+	});
+	assert.deepEqual(await receipt.projected, {
+		commandId: COMMAND_A,
+		state: 'projected',
+		result: { id: 'todo-1', title: 'canonical' },
+		metadata: receipt.metadata
+	});
+	runtime.dispose();
+});
+
+test('Projected<T> advances record clocks so older query responses stay complete', async () => {
+	const replica = createDistributedReplica();
+	const scopeOperation = scopeQueryArtifact();
+	const projectedArtifact = artifact({
+		name: 'todo.project',
+		mutationField: 'createTodo',
+		document:
+			'mutation Client_createTodo($commandId: ID!, $input: TodoInput!) { createTodo(commandId: $commandId, input: $input) { id title } }',
+		output: Object.freeze({ kind: 'object', definition: TodoOutput }),
+		consistency: 'projected',
+		confirmations: undefined,
+		directProjection: Object.freeze({
+			topology: Object.freeze({
+				version: 1,
+				name: 'todos',
+				digest: HASH_C
+			}),
+			model: Todo.id,
+			identityFields: Todo.identityFields,
+			changeEpoch: 'todos-v1'
+		})
+	});
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(
+					commandEnvelope(request.commandId, {
+						state: 'projected',
+						consistency: 'projected',
+						expects: [],
+						data: {
+							createTodo: {
+								id: 'todo-1',
+								title: 'projected-newer'
+							}
+						},
+						records: [
+							{
+								model: Todo.id,
+								scopeToken: 'record:todo-1',
+								incarnation: '1',
+								revision: '3',
+								tombstone: false
+							}
+						]
+					})
+				)
+		},
+		{ projectTodo: projectedArtifact }
+	);
+
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeTodoSnapshotEnvelope('1', 'initial'),
+		'network'
+	);
+	await runtime.commands.projectTodo(
+		{ id: 'todo-1', title: 'projected-newer' },
+		{ commandId: COMMAND_A }
+	);
+
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeTodoSnapshotEnvelope('2', 'stale-response'),
+		'network'
+	);
+	const snapshot = replica.read(scopeOperation, {});
+	assert.equal(snapshot.complete, true);
+	assert.equal(snapshot.data.todos[0].title, 'projected-newer');
+	assert.equal(replica.inspectRecord(Todo, 'todo-1').revision, '3');
+
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeTodoSnapshotEnvelope('4', 'projected-newer'),
+		'network'
+	);
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeTodoSnapshotEnvelope('5', 'server-newest'),
+		'network'
+	);
+	assert.equal(replica.read(scopeOperation, {}).data.todos[0].title, 'server-newest');
+	runtime.dispose();
+});
+
+test('Projected<T> rejects a conflicting snapshot body even with later evidence', async () => {
+	const replica = createDistributedReplica();
+	const scopeOperation = scopeQueryArtifact();
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeTodoSnapshotEnvelope('1', 'initial'),
+		'network'
+	);
+	const runtime = await directlyProjectTodo(replica);
+
+	/*
+	 * Reproduce the live-query race: SQL body predates the projected
+	 * command, but response evidence is stamped after it. The projected
+	 * row must win until an exact echo, tombstone, partial supersession,
+	 * or pathless supersession releases the fence.
+	 */
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeTodoSnapshotEnvelope('4', 'server-stale-body', {
+			recordRevision: '999999999999999999'
+		}),
+		'network'
+	);
+
+	assert.equal(
+		replica.read(scopeOperation, {}).data.todos[0].title,
+		'projected-newer'
+	);
+	assert.equal(replica.inspectRecord(Todo, 'todo-1').revision, '3');
+	runtime.dispose();
+});
+
+test('Projected<T> rejects a conflicting HTTP response started before the projection', async () => {
+	let resolveFetch;
+	let markFetchStarted;
+	const fetchStarted = new Promise((resolve) => {
+		markFetchStarted = resolve;
+	});
+	const fetchResult = new Promise((resolve) => {
+		resolveFetch = resolve;
+	});
+	const replica = createDistributedReplica({
+		transport: {
+			fetch: () => {
+				markFetchStarted();
+				return fetchResult;
+			}
+		}
+	});
+	const scopeOperation = scopeQueryArtifact();
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeTodoSnapshotEnvelope('1', 'initial'),
+		'network'
+	);
+	const watch = replica.watch(scopeOperation, {});
+	const refresh = watch.refresh();
+	await fetchStarted;
+	const runtime = await directlyProjectTodo(replica);
+
+	resolveFetch(
+		scopeTodoSnapshotEnvelope('4', 'pre-command-body', {
+			recordRevision: '999999999999999999'
+		})
+	);
+	await refresh;
+
+	assert.equal(watch.get().data.todos[0].title, 'projected-newer');
+	assert.equal(replica.inspectRecord(Todo, 'todo-1').revision, '3');
+	watch.destroy();
+	runtime.dispose();
+});
+
+test('Projected<T> accepts a causally newer post-command HTTP row before the projected echo', async () => {
+	let resolveFetch;
+	let markFetchStarted;
+	const fetchStarted = new Promise((resolve) => {
+		markFetchStarted = resolve;
+	});
+	const fetchResult = new Promise((resolve) => {
+		resolveFetch = resolve;
+	});
+	const replica = createDistributedReplica({
+		transport: {
+			fetch: () => {
+				markFetchStarted();
+				return fetchResult;
+			}
+		}
+	});
+	const scopeOperation = scopeQueryArtifact();
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeTodoSnapshotEnvelope('1', 'initial'),
+		'network'
+	);
+	const watch = replica.watch(scopeOperation, {});
+	const runtime = await directlyProjectTodo(replica);
+	const refresh = watch.refresh();
+	await fetchStarted;
+
+	resolveFetch(scopeTodoSnapshotEnvelope('4', 'server-newer'));
+	await refresh;
+
+	assert.equal(watch.get().data.todos[0].title, 'server-newer');
+	assert.equal(replica.inspectRecord(Todo, 'todo-1').revision, '4');
+	watch.destroy();
+	runtime.dispose();
+});
+
+test('Projected<T> accepts a causally newer live row before the projected echo', async () => {
+	let liveObserver;
+	const replica = createDistributedReplica({
+		transport: {
+			subscribe: (_request, observer) => {
+				liveObserver = observer;
+				return () => {};
+			}
+		}
+	});
+	const scopeOperation = scopeLiveQueryArtifact();
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeTodoSnapshotEnvelope('1', 'initial'),
+		'network'
+	);
+	const watch = replica.watch(scopeOperation, {}, { live: true });
+	const runtime = await directlyProjectTodo(replica);
+
+	liveObserver.next(scopeLiveTodoSnapshotEnvelope('4', 'server-newer'));
+
+	assert.equal(watch.get().data.todos[0].title, 'server-newer');
+	assert.equal(replica.inspectRecord(Todo, 'todo-1').revision, '4');
+	watch.destroy();
+	runtime.dispose();
+});
+
+test('Projected<T> accepts a pathless supersession before the projected echo', async () => {
+	const replica = createDistributedReplica();
+	const scopeOperation = scopeQueryArtifact();
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeTodoSnapshotEnvelope('1', 'initial'),
+		'network'
+	);
+	const runtime = await directlyProjectTodo(replica);
+
+	const pathlessNewer = scopeSnapshotEnvelope('4');
+	pathlessNewer.data = { todos: [] };
+	pathlessNewer.extensions.distributed.snapshot.records = [
+		{
+			model: Todo.id,
+			scopeToken: 'record:todo-1',
+			incarnation: '1',
+			revision: '4',
+			tombstone: false
+		}
+	];
+	replica.writeResult(scopeOperation, {}, pathlessNewer, 'network');
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeTodoSnapshotEnvelope('5', 'server-newer'),
+		'network'
+	);
+
+	assert.equal(replica.read(scopeOperation, {}).data.todos[0].title, 'server-newer');
+	assert.equal(replica.inspectRecord(Todo, 'todo-1').revision, '5');
+	runtime.dispose();
+});
+
+test('Projected<T> accepts a causally newer tombstone before the projected echo', async () => {
+	const replica = createDistributedReplica();
+	const scopeOperation = scopeQueryArtifact();
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeTodoSnapshotEnvelope('1', 'initial'),
+		'network'
+	);
+	const runtime = await directlyProjectTodo(replica);
+	const deleted = scopeSnapshotEnvelope('4');
+	deleted.extensions.distributed.snapshot.records = [
+		{
+			model: Todo.id,
+			scopeToken: 'record:todo-1',
+			incarnation: '1',
+			revision: '4',
+			tombstone: true
+		}
+	];
+
+	replica.writeResult(scopeOperation, {}, deleted, 'network');
+
+	assert.equal(replica.inspectRecord(Todo, 'todo-1'), undefined);
+	runtime.dispose();
+});
+
+test('Projected<T> clears its fence when a newer partial selection supersedes it', async () => {
+	const replica = createDistributedReplica();
+	const partialOperation = scopeQueryArtifact({ includeTitle: false });
+	const fullOperation = scopeQueryArtifact({ operation: HASH_E });
+	replica.writeResult(
+		fullOperation,
+		{},
+		scopeTodoSnapshotEnvelope('1', 'initial', { operation: HASH_E }),
+		'network'
+	);
+	const runtime = await directlyProjectTodo(replica);
+
+	replica.writeResult(
+		partialOperation,
+		{},
+		scopeTodoIdSnapshotEnvelope('4', HASH_D),
+		'network'
+	);
+	replica.writeResult(
+		fullOperation,
+		{},
+		scopeTodoSnapshotEnvelope('5', 'server-newest', { operation: HASH_E }),
+		'network'
+	);
+
+	assert.equal(
+		replica.read(fullOperation, {}).data.todos[0].title,
+		'server-newest'
+	);
+	assert.equal(replica.inspectRecord(Todo, 'todo-1').revision, '5');
+	runtime.dispose();
+});
+
+test('Projected<T> retains its authoritative row while a later revalidation reads a lagging projection', async () => {
+	let resolveFetch;
+	let markFetchStarted;
+	const fetchStarted = new Promise((resolve) => {
+		markFetchStarted = resolve;
+	});
+	const fetchResult = new Promise((resolve) => {
+		resolveFetch = resolve;
+	});
+	const replica = createDistributedReplica({
+		transport: {
+			fetch: () => {
+				markFetchStarted();
+				return fetchResult;
+			}
+		}
+	});
+	const scopeOperation = scopeQueryArtifact();
+	const projectedArtifact = artifact({
+		name: 'todo.project',
+		mutationField: 'createTodo',
+		document:
+			'mutation Client_createTodo($commandId: ID!, $input: TodoInput!) { createTodo(commandId: $commandId, input: $input) { id title } }',
+		output: Object.freeze({ kind: 'object', definition: TodoOutput }),
+		consistency: 'projected',
+		confirmations: undefined,
+		directProjection: Object.freeze({
+			topology: Object.freeze({
+				version: 1,
+				name: 'todos',
+				digest: HASH_C
+			}),
+			model: Todo.id,
+			identityFields: Todo.identityFields,
+			changeEpoch: 'todos-v1'
+		})
+	});
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(
+					commandEnvelope(request.commandId, {
+						state: 'projected',
+						consistency: 'projected',
+						expects: [],
+						data: {
+							createTodo: {
+								id: 'todo-1',
+								title: 'projected-newer'
+							}
+						},
+						records: [
+							{
+								model: Todo.id,
+								scopeToken: 'record:todo-1',
+								incarnation: '1',
+								revision: '6',
+								tombstone: false
+							}
+						]
+					})
+				)
+		},
+		{ projectTodo: projectedArtifact }
+	);
+
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeTodoSnapshotEnvelope('4', 'initial'),
+		'network'
+	);
+	const watch = replica.watch(scopeOperation, {});
+	await runtime.commands.projectTodo(
+		{ id: 'todo-1', title: 'projected-newer' },
+		{ commandId: COMMAND_A }
+	);
+	const refresh = watch.refresh();
+	await fetchStarted;
+	resolveFetch(
+		scopeTodoSnapshotEnvelope('7', 'stale-snapshot', {
+			recordRevision: '5'
+		})
+	);
+	await refresh;
+
+	const snapshot = watch.get();
+	assert.equal(snapshot.complete, true);
+	assert.equal(snapshot.data.todos[0].title, 'projected-newer');
+	assert.equal(replica.inspectRecord(Todo, 'todo-1').revision, '6');
+	watch.destroy();
+	runtime.dispose();
+});
+
+test('relationship and invalidation effects stay semantic instead of guessing list links', async () => {
+	const replica = new FakeReplica();
+	replica.onRevalidate = () => new Promise(() => undefined);
+	const relationshipArtifact = artifact({
+		name: 'todo.relate',
+		mutationField: 'relateTodo',
+		document:
+			'mutation Client_relateTodo($commandId: ID!, $input: TodoInput!) { relateTodo(commandId: $commandId, input: $input) }',
+		consistency: 'accepted',
+		trustedPresets: Object.freeze([]),
+		confirmations: undefined,
+		revalidation: Object.freeze({
+			version: 1,
+			required: true,
+			dependencies: Object.freeze(['todos']),
+			models: Object.freeze(['Todo']),
+			relationships: Object.freeze([])
+		}),
+		effects: {
+			version: 1,
+			operations: [
+				{
+					kind: 'link',
+					relationship: {
+						sourceModel: 'Todo',
+						field: 'related',
+						targetModel: 'Todo'
+					},
+					source: effectKey(
+						effectField('id', inputExpression(['id']))
+					),
+					target: effectKey(
+						effectField('id', inputExpression(['title']))
+					)
+				},
+				{ kind: 'invalidate_model', model: 'Todo' }
+			],
+			fallback: 'revalidate'
+		}
+	});
+	const transport = {
+		dispatch: (request) =>
+			Promise.resolve(
+				commandEnvelope(request.commandId, {
+					state: 'accepted',
+					consistency: 'accepted',
+					expects: [],
+					data: { relateTodo: { ok: true } }
+				})
+			)
+	};
+	const runtime = createReplicaCommandRuntime(replica, transport, {
+		relateTodo: relationshipArtifact
+	});
+
+	await runtime.commands.relateTodo(
+		{ id: 'todo-1', title: 'todo-2' },
+		{ commandId: COMMAND_A }
+	);
+
+	const layer = replica.layers.get(COMMAND_A);
+	assert.deepEqual(layer.operations, []);
+	assert.deepEqual(layer.semanticChanges, [
+		{
+			kind: 'link',
+			sourceModel: 'Todo',
+			field: 'related',
+			targetModel: 'Todo',
+			sourceKey: replicaRecordKey(Todo, 'todo-1'),
+			targetKey: replicaRecordKey(Todo, 'todo-2'),
+			dependencies: ['todos']
+		},
+		{ kind: 'invalidate', dependencies: ['todos'] }
+	]);
+	runtime.dispose();
+});
+
+test('authorization abort rejects and untracks a pending projected awaitable', async () => {
+	const replica = new FakeReplica();
+	const transport = {
+		dispatch: (request) => Promise.resolve(commandEnvelope(request.commandId))
+	};
+	const runtime = createReplicaCommandRuntime(replica, transport, {
+		createTodo: artifact()
+	});
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-1', title: 'pending' },
+		{ commandId: COMMAND_A }
+	);
+
+	replica.authority.generation += 1;
+	replica.authority.controller.abort('logout');
+	await assert.rejects(
+		receipt.projected,
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_SCOPE_INVALIDATED'
+	);
+
+	// Late matching evidence cannot resurrect or re-resolve the settled handle.
+	runtime.observeResult(
+		commandEnvelope(COMMAND_A, {
+			observations: [
+				{
+					causationId: `cause:${COMMAND_A}`,
+					projection: 'todos',
+					model: 'Todo',
+					scopeToken: 'todo:scope'
+				}
+			]
+		})
+	);
+	runtime.dispose();
+});
+
+test('caller abort after acceptance only rejects its projection wait while causality continues', async () => {
+	const replica = createDistributedReplica();
+	const command = artifact();
+	const scopeOperation = scopeQueryArtifact();
+	const caller = new AbortController();
+	const statusRequests = [];
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(commandEnvelope(request.commandId)),
+			status(request) {
+				statusRequests.push(request);
+				return Promise.resolve(statusEnvelope(request.commandId));
+			}
+		},
+		{ createTodo: command },
+		{ status: COMMAND_STATUS }
+	);
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeSnapshotEnvelope('1'),
+		'network'
+	);
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-deadline', title: 'optimistic' },
+		{ commandId: COMMAND_A, signal: caller.signal }
+	);
+
+	caller.abort('caller deadline');
+	await assert.rejects(
+		receipt.projected,
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_ABORTED'
+	);
+	assert.ok(
+		replica.inspectRecord(Todo, 'todo-deadline'),
+		'caller cancellation must preserve the accepted optimistic layer'
+	);
+
+	const status = await receipt.status();
+	assert.equal(status.state, 'accepted_pending_projection');
+	assert.equal(statusRequests.length, 1);
+	assert.notEqual(
+		statusRequests[0].signal,
+		caller.signal,
+		'status recovery must remain bound to authority, not caller cancellation'
+	);
+	assert.equal(statusRequests[0].signal?.aborted, false);
+
+	replica.writeResult(
+		scopeOperation,
+		{},
+		scopeSnapshotEnvelope('2', {
+			command: receipt.metadata,
+			observations: [
+				{
+					causationId: receipt.metadata.causationId,
+					projection: 'todos',
+					model: 'Todo',
+					scopeToken: 'todo:scope'
+				}
+			]
+		}),
+		'network'
+	);
+	assert.equal(
+		replica.inspectRecord(Todo, 'todo-deadline'),
+		undefined,
+		'later causal evidence must still retire the optimistic layer'
+	);
+	await assert.rejects(
+		receipt.projected,
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_ABORTED'
+	);
+	runtime.dispose();
+});
+
+test('matching wire observations resolve only after the replica retires the layer', async () => {
+	const replica = new FakeReplica();
+	const transport = {
+		dispatch: (request) => Promise.resolve(commandEnvelope(request.commandId))
+	};
+	const runtime = createReplicaCommandRuntime(replica, transport, {
+		createTodo: artifact()
+	});
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-1', title: 'pending' },
+		{ commandId: COMMAND_A }
+	);
+	const observed = commandEnvelope(COMMAND_A, {
+		observations: [
+			{
+				causationId: `cause:${COMMAND_A}`,
+				projection: 'todos',
+				model: 'Todo',
+				scopeToken: 'todo:scope'
+			}
+		]
+	});
+	let settled = false;
+	void receipt.projected.then(() => {
+		settled = true;
+	});
+
+	// Calling the hook early cannot turn a merely syntactic match into proof.
+	runtime.observeResult(observed);
+	await Promise.resolve();
+	assert.equal(settled, false);
+	assert.equal(replica.layers.has(COMMAND_A), true);
+
+	// The query/live coordinator atomically merges base and retires the layer.
+	replica.confirmOptimisticLayer(COMMAND_A, () => undefined);
+	runtime.observeResult(observed);
+	assert.deepEqual(await receipt.projected, {
+		commandId: COMMAND_A,
+		state: 'projected',
+		metadata: observed.extensions.distributed.command
+	});
+	runtime.dispose();
+});
+
+test('required command revalidation plans require a replica coordinator at construction', () => {
+	const required = artifact({
+		revalidation: Object.freeze({
+			version: 1,
+			required: true,
+			dependencies: Object.freeze(['todos']),
+			models: Object.freeze(['Todo']),
+			relationships: Object.freeze([])
+		})
+	});
+	const replica = new FakeReplica();
+	replica.revalidate = undefined;
+	assert.throws(
+		() =>
+			createReplicaCommandRuntime(
+				replica,
+				{ dispatch: () => Promise.reject(new Error('unused')) },
+				{ createTodo: required }
+			),
+		/generated command revalidation plan requires replica\.revalidate/
+	);
+});
+
+test('required revalidation retires unavailable-confirmation optimism only after canonical refresh', async () => {
+	const required = artifact({
+		confirmations: Object.freeze({
+			version: 1,
+			kind: 'unavailable',
+			expected: Object.freeze([]),
+			fallback: 'revalidate'
+		}),
+		revalidation: Object.freeze({
+			version: 1,
+			required: true,
+			dependencies: Object.freeze(['todos']),
+			models: Object.freeze(['Todo']),
+			relationships: Object.freeze([])
+		})
+	});
+	const replica = new FakeReplica();
+	let resolveRefresh;
+	const refresh = new Promise((resolve) => {
+		resolveRefresh = resolve;
+	});
+	replica.onRevalidate = () => refresh;
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(commandEnvelope(request.commandId))
+		},
+		{ createTodo: required }
+	);
+
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-required-refresh', title: 'optimistic until canonical' },
+		{ commandId: COMMAND_A }
+	);
+	assert.equal(receipt.projected, undefined);
+	assert.equal(replica.revalidations.length, 1);
+	assert.equal(
+		replica.layers.has(COMMAND_A),
+		true,
+		'acceptance alone must not retire non-canonical optimism'
+	);
+
+	resolveRefresh();
+	await refresh;
+	await new Promise((resolve) => setImmediate(resolve));
+	assert.equal(
+		replica.layers.has(COMMAND_A),
+		false,
+		'the completed generated refresh is the retirement fence'
+	);
+	runtime.dispose();
+});
+
+test('generated status is required at construction and coalesces exact causal reads', async () => {
+	const missingStatusReplica = new FakeReplica();
+	assert.throws(
+		() =>
+			createReplicaCommandRuntime(
+				missingStatusReplica,
+				{ dispatch: () => Promise.reject(new Error('unused')) },
+				{ createTodo: artifact() },
+				{ status: COMMAND_STATUS }
+			),
+		/generated command status artifact requires transport\.status/
+	);
+
+	const replica = new FakeReplica();
+	const statusRequests = [];
+	let resolveStatus;
+	const transport = {
+		dispatch: (request) => Promise.resolve(commandEnvelope(request.commandId)),
+		status(request) {
+			statusRequests.push(request);
+			return new Promise((resolve) => {
+				resolveStatus = resolve;
+			});
+		}
+	};
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		transport,
+		{ createTodo: artifact() },
+		{ status: COMMAND_STATUS }
+	);
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-status', title: 'pending' },
+		{ commandId: COMMAND_A }
+	);
+	const projectedEnvelope = statusEnvelope(COMMAND_A, {
+		state: 'projected',
+		observations: [
+			{
+				causationId: `cause:${COMMAND_A}`,
+				projection: 'todos',
+				model: 'Todo',
+				scopeToken: 'todo:scope'
+			}
+		]
+	});
+
+	const first = receipt.status();
+	const second = receipt.status();
+	assert.equal(first, second, 'concurrent status reads must coalesce');
+	assert.equal(statusRequests.length, 1);
+	const { signal, ...wireRequest } = statusRequests[0];
+	assert.notEqual(
+		signal,
+		replica.authority.controller.signal,
+		'status cancellation combines replica authority with runtime teardown'
+	);
+	assert.equal(signal.aborted, false);
+	assert.deepEqual(wireRequest, {
+		operation: 'status',
+		commandId: COMMAND_A,
+		name: 'Distributed_CommandStatus',
+		document: STATUS_DOCUMENT,
+		operationHash: HASH_D,
+		variables: { commandId: COMMAND_A },
+		extensions: {
+			distributed: {
+				client: {
+					surface: SURFACE,
+					schemaHash: HASH_B
+				}
+			}
+		}
+	});
+	resolveStatus(projectedEnvelope);
+	const status = await first;
+	assert.equal(status.state, 'projected');
+	assert.equal(status.metadata.commandId, COMMAND_A);
+
+	assert.equal((await receipt.projected).state, 'projected');
+	assert.equal(
+		replica.layers.has(COMMAND_A),
+		false,
+		'status-projected revalidation retires optimism only after it completes'
+	);
+	assert.equal(replica.revalidations.length, 1);
+	assert.deepEqual(replica.revalidations[0], artifact().revalidation);
+
+	runtime.dispose();
+});
+
+test('projected recovery status revalidates and retires optimism without a projection controller', async () => {
+	const replica = new FakeReplica();
+	let resolveRefresh;
+	const refresh = new Promise((resolve) => {
+		resolveRefresh = resolve;
+	});
+	replica.onRevalidate = () => refresh;
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(
+					commandEnvelope(request.commandId, {
+						state: 'in_progress',
+						expects: []
+					})
+				),
+			status: (request) =>
+				Promise.resolve(
+					statusEnvelope(request.commandId, {
+						state: 'projected',
+						observations: [
+							{
+								causationId: `cause:${request.commandId}`,
+								projection: 'todos',
+								model: 'Todo',
+								scopeToken: 'todo:scope'
+							}
+						]
+					})
+				)
+		},
+		{ createTodo: artifact() },
+		{ status: COMMAND_STATUS }
+	);
+
+	let failure;
+	try {
+		await runtime.commands.createTodo(
+			{ id: 'todo-recovery-projected', title: 'recover causally' },
+			{ commandId: COMMAND_A }
+		);
+		assert.fail('in-progress dispatch should expose recovery');
+	} catch (error) {
+		failure = error;
+	}
+	assert.equal(failure.code, 'REPLICA_COMMAND_OUTCOME_PENDING');
+	assert.equal(failure.recovery.commandId, COMMAND_A);
+
+	let statusSettled = false;
+	const status = failure.recovery.status().finally(() => {
+		statusSettled = true;
+	});
+	await new Promise((resolve) => setImmediate(resolve));
+	assert.equal(replica.revalidations.length, 1);
+	assert.equal(statusSettled, false);
+	assert.equal(
+		replica.layers.has(COMMAND_A),
+		true,
+		'projected status alone carries no canonical query payload'
+	);
+
+	resolveRefresh();
+	assert.equal((await status).state, 'projected');
+	assert.equal(replica.layers.has(COMMAND_A), false);
+	runtime.dispose();
+});
+
+test('terminal accepted recovery revalidates before retiring optimism', async () => {
+	const replica = new FakeReplica();
+	let resolveRefresh;
+	const refresh = new Promise((resolve) => {
+		resolveRefresh = resolve;
+	});
+	replica.onRevalidate = () => refresh;
+	const accepted = artifact({
+		consistency: 'accepted',
+		confirmations: undefined,
+		revalidation: Object.freeze({
+			version: 1,
+			required: true,
+			dependencies: Object.freeze(['todos']),
+			models: Object.freeze(['Todo']),
+			relationships: Object.freeze([])
+		})
+	});
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: () => Promise.reject(new Error('accepted response lost')),
+			status: (request) =>
+				Promise.resolve(
+					statusEnvelope(request.commandId, {
+						state: 'accepted',
+						consistency: 'accepted',
+						expects: []
+					})
+				)
+		},
+		{ createTodo: accepted },
+		{ status: COMMAND_STATUS }
+	);
+
+	let failure;
+	try {
+		await runtime.commands.createTodo(
+			{ id: 'todo-recovery-accepted', title: 'recover terminally' },
+			{ commandId: COMMAND_A }
+		);
+		assert.fail('ambiguous dispatch should expose recovery');
+	} catch (error) {
+		failure = error;
+	}
+	assert.equal(failure.code, 'REPLICA_COMMAND_TRANSPORT_AMBIGUOUS');
+	assert.equal(failure.recovery.commandId, COMMAND_A);
+
+	let statusSettled = false;
+	const status = failure.recovery.status().finally(() => {
+		statusSettled = true;
+	});
+	await new Promise((resolve) => setImmediate(resolve));
+	assert.equal(replica.revalidations.length, 1);
+	assert.equal(statusSettled, false);
+	assert.equal(
+		replica.layers.has(COMMAND_A),
+		true,
+		'terminal acceptance alone has no canonical query payload'
+	);
+
+	resolveRefresh();
+	assert.equal((await status).state, 'accepted');
+	assert.equal(replica.layers.has(COMMAND_A), false);
+	runtime.dispose();
+});
+
+test('completed dispatch and status reads release linked abort listeners', async () => {
+	const replica = new FakeReplica();
+	const authoritySignal = replica.authority.controller.signal;
+	const originalAddEventListener =
+		authoritySignal.addEventListener.bind(authoritySignal);
+	const originalRemoveEventListener =
+		authoritySignal.removeEventListener.bind(authoritySignal);
+	const activeAbortListeners = new Set();
+	authoritySignal.addEventListener = (type, listener, options) => {
+		if (type === 'abort') activeAbortListeners.add(listener);
+		return originalAddEventListener(type, listener, options);
+	};
+	authoritySignal.removeEventListener = (type, listener, options) => {
+		if (type === 'abort') activeAbortListeners.delete(listener);
+		return originalRemoveEventListener(type, listener, options);
+	};
+
+	let runtime;
+	try {
+		const accepted = artifact({
+			consistency: 'accepted',
+			confirmations: undefined,
+			revalidation: Object.freeze({
+				version: 1,
+				required: true,
+				dependencies: Object.freeze(['todos']),
+				models: Object.freeze(['Todo']),
+				relationships: Object.freeze([])
+			})
+		});
+		runtime = createReplicaCommandRuntime(
+			replica,
+			{
+				dispatch: (request) =>
+					Promise.resolve(
+						commandEnvelope(request.commandId, {
+							state: 'accepted',
+							consistency: 'accepted',
+							expects: []
+						})
+					),
+				status: (request) =>
+					Promise.resolve(
+						statusEnvelope(request.commandId, {
+							state: 'accepted',
+							consistency: 'accepted',
+							expects: []
+						})
+					)
+			},
+			{ createTodo: accepted },
+			{ status: COMMAND_STATUS }
+		);
+		const receipt = await runtime.commands.createTodo(
+			{ id: 'todo-listener-cleanup', title: 'bounded listeners' },
+			{ commandId: COMMAND_A }
+		);
+		assert.equal(activeAbortListeners.size, 0);
+
+		for (let read = 0; read < 32; read += 1) {
+			assert.equal((await receipt.status()).state, 'accepted');
+			assert.equal(
+				activeAbortListeners.size,
+				0,
+				`status read ${read + 1} must release its authority listener`
+			);
+		}
+	} finally {
+		runtime?.dispose();
+		delete authoritySignal.addEventListener;
+		delete authoritySignal.removeEventListener;
+	}
+});
+
+test('optimistic layer creation failure releases linked abort listeners', async () => {
+	const replica = new FakeReplica();
+	replica.createOptimisticLayer(COMMAND_A, () => undefined);
+	const authoritySignal = replica.authority.controller.signal;
+	const originalAddEventListener =
+		authoritySignal.addEventListener.bind(authoritySignal);
+	const originalRemoveEventListener =
+		authoritySignal.removeEventListener.bind(authoritySignal);
+	const activeAbortListeners = new Set();
+	authoritySignal.addEventListener = (type, listener, options) => {
+		if (type === 'abort') activeAbortListeners.add(listener);
+		return originalAddEventListener(type, listener, options);
+	};
+	authoritySignal.removeEventListener = (type, listener, options) => {
+		if (type === 'abort') activeAbortListeners.delete(listener);
+		return originalRemoveEventListener(type, listener, options);
+	};
+
+	let dispatches = 0;
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: () => {
+				dispatches += 1;
+				return Promise.reject(new Error('must not dispatch'));
+			}
+		},
+		{ createTodo: artifact() }
+	);
+	try {
+		await assert.rejects(
+			runtime.commands.createTodo(
+				{ id: 'todo-duplicate-layer', title: 'must fail locally' },
+				{ commandId: COMMAND_A }
+			),
+			/optimistic layer already exists/
+		);
+		assert.equal(dispatches, 0);
+		assert.equal(
+			activeAbortListeners.size,
+			0,
+			'pre-dispatch failure must release its authority listener'
+		);
+	} finally {
+		runtime.dispose();
+		replica.rejectOptimisticLayer(COMMAND_A);
+		delete authoritySignal.addEventListener;
+		delete authoritySignal.removeEventListener;
+	}
+});
+
+test('accepted facts poll durable status and revalidate before retiring optimism', async () => {
+	const replica = new FakeReplica();
+	let statusReads = 0;
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(commandEnvelope(request.commandId)),
+			status(request) {
+				statusReads += 1;
+				return Promise.resolve(
+					statusEnvelope(request.commandId, {
+						state:
+							statusReads === 1
+								? 'accepted_pending_projection'
+								: 'projected',
+						observations:
+							statusReads === 1
+								? []
+								: [
+										{
+											causationId: `cause:${request.commandId}`,
+											projection: 'todos',
+											model: 'Todo',
+											scopeToken: 'todo:scope'
+										}
+									]
+					})
+				);
+			}
+		},
+		{ createTodo: artifact() },
+		{ status: COMMAND_STATUS }
+	);
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-auto-status', title: 'eventually canonical' },
+		{ commandId: COMMAND_A }
+	);
+
+	assert.equal((await receipt.projected).state, 'projected');
+	assert.equal(statusReads, 2);
+	assert.equal(replica.revalidations.length, 1);
+	assert.deepEqual(replica.revalidations[0], artifact().revalidation);
+	assert.equal(replica.layers.has(COMMAND_A), false);
+	runtime.dispose();
+});
+
+test('disposing during dispatch aborts the request and removes pre-acceptance optimism', async () => {
+	const replica = new FakeReplica();
+	let dispatchStarted;
+	const started = new Promise((resolve) => {
+		dispatchStarted = resolve;
+	});
+	let dispatchRequest;
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch(request) {
+				dispatchRequest = request;
+				dispatchStarted();
+				return new Promise(() => undefined);
+			}
+		},
+		{ createTodo: artifact() }
+	);
+	const invocation = runtime.commands.createTodo(
+		{ id: 'todo-dispose-dispatch', title: 'must not leak' },
+		{ commandId: COMMAND_A }
+	);
+	const commandFailure = assert.rejects(
+		invocation,
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_DISPOSED'
+	);
+
+	await started;
+	assert.equal(replica.layers.has(COMMAND_A), true);
+	assert.equal(dispatchRequest.signal.aborted, false);
+	assert.equal(replica.authority.controller.signal.aborted, false);
+
+	runtime.dispose();
+	await commandFailure;
+	assert.equal(dispatchRequest.signal.aborted, true);
+	assert.equal(
+		replica.authority.controller.signal.aborted,
+		false,
+		'runtime teardown must not invalidate the replica authorization generation'
+	);
+	assert.equal(
+		replica.layers.has(COMMAND_A),
+		false,
+		'terminal local teardown must remove its pre-acceptance layer'
+	);
+});
+
+test('disposing aborts an in-flight status read and removes accepted optimism', async () => {
+	const replica = new FakeReplica();
+	let statusStarted;
+	const started = new Promise((resolve) => {
+		statusStarted = resolve;
+	});
+	let statusRequest;
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(commandEnvelope(request.commandId)),
+			status(request) {
+				statusRequest = request;
+				statusStarted();
+				return new Promise(() => undefined);
+			}
+		},
+		{ createTodo: artifact() },
+		{ status: COMMAND_STATUS }
+	);
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-dispose-status', title: 'must stop polling' },
+		{ commandId: COMMAND_A }
+	);
+	const statusFailure = assert.rejects(
+		receipt.status(),
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_DISPOSED'
+	);
+	const projectionFailure = assert.rejects(
+		receipt.projected,
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_DISPOSED'
+	);
+
+	await started;
+	assert.equal(statusRequest.signal.aborted, false);
+	assert.equal(replica.layers.has(COMMAND_A), true);
+
+	runtime.dispose();
+	await Promise.all([statusFailure, projectionFailure]);
+	assert.equal(statusRequest.signal.aborted, true);
+	assert.equal(replica.authority.controller.signal.aborted, false);
+	assert.equal(replica.layers.has(COMMAND_A), false);
+});
+
+test('disposing during required status revalidation rejects the status read', async () => {
+	const replica = new FakeReplica();
+	let refreshStarted;
+	const started = new Promise((resolve) => {
+		refreshStarted = resolve;
+	});
+	replica.onRevalidate = () => {
+		refreshStarted();
+		return new Promise(() => undefined);
+	};
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(commandEnvelope(request.commandId)),
+			status: (request) =>
+				Promise.resolve(
+					statusEnvelope(request.commandId, {
+						state: 'projected',
+						observations: [
+							{
+								causationId: `cause:${request.commandId}`,
+								projection: 'todos',
+								model: 'Todo',
+								scopeToken: 'todo:scope'
+							}
+						]
+					})
+				)
+		},
+		{ createTodo: artifact() },
+		{ status: COMMAND_STATUS }
+	);
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-dispose-revalidation', title: 'must stop refreshing' },
+		{ commandId: COMMAND_A }
+	);
+	const statusFailure = assert.rejects(
+		receipt.status(),
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_DISPOSED'
+	);
+	const projectionFailure = assert.rejects(
+		receipt.projected,
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_DISPOSED'
+	);
+
+	await started;
+	assert.equal(replica.layers.has(COMMAND_A), true);
+	assert.equal(replica.revalidations.length, 1);
+
+	runtime.dispose();
+	await Promise.all([statusFailure, projectionFailure]);
+	assert.equal(replica.authority.controller.signal.aborted, false);
+	assert.equal(replica.layers.has(COMMAND_A), false);
+});
+
+test('authority invalidation during required status revalidation rejects stale status', async () => {
+	const replica = new FakeReplica();
+	let refreshStarted;
+	const started = new Promise((resolve) => {
+		refreshStarted = resolve;
+	});
+	replica.onRevalidate = () => {
+		refreshStarted();
+		return new Promise(() => undefined);
+	};
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(commandEnvelope(request.commandId)),
+			status: (request) =>
+				Promise.resolve(
+					statusEnvelope(request.commandId, {
+						state: 'projected',
+						observations: [
+							{
+								causationId: `cause:${request.commandId}`,
+								projection: 'todos',
+								model: 'Todo',
+								scopeToken: 'todo:scope'
+							}
+						]
+					})
+				)
+		},
+		{ createTodo: artifact() },
+		{ status: COMMAND_STATUS }
+	);
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-stale-revalidation', title: 'must reject stale status' },
+		{ commandId: COMMAND_A }
+	);
+	const statusFailure = assert.rejects(
+		receipt.status(),
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_SCOPE_INVALIDATED'
+	);
+	const projectionFailure = assert.rejects(
+		receipt.projected,
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_SCOPE_INVALIDATED'
+	);
+
+	await started;
+	replica.authority.generation += 1;
+	replica.authority.scope = undefined;
+	replica.layers.clear();
+	replica.authority.controller.abort('logout');
+	await Promise.all([statusFailure, projectionFailure]);
+	assert.equal(replica.layers.has(COMMAND_A), false);
+
+	runtime.dispose();
+});
+
+test('a pending fact owns its durable-status timer until disposal clears it', async () => {
+	const originalSetTimeout = globalThis.setTimeout;
+	const originalClearTimeout = globalThis.clearTimeout;
+	const scheduled = [];
+	const cleared = [];
+	globalThis.setTimeout = (callback, delay, ...args) => {
+		const timer = originalSetTimeout(callback, delay, ...args);
+		scheduled.push({ timer, delay });
+		return timer;
+	};
+	globalThis.clearTimeout = (timer) => {
+		cleared.push(timer);
+		return originalClearTimeout(timer);
+	};
+
+	let runtime;
+	try {
+		const replica = new FakeReplica();
+		runtime = createReplicaCommandRuntime(
+			replica,
+			{
+				dispatch: (request) =>
+					Promise.resolve(commandEnvelope(request.commandId)),
+				status: () => Promise.reject(new Error('must not be called'))
+			},
+			{ createTodo: artifact() },
+			{ status: COMMAND_STATUS }
+		);
+		const receipt = await runtime.commands.createTodo(
+			{ id: 'todo-cancel-poll', title: 'cancel poll' },
+			{ commandId: COMMAND_A }
+		);
+		const projectionFailure = assert.rejects(
+			receipt.projected,
+			(error) =>
+				error instanceof ReplicaCommandRuntimeError &&
+				error.code === 'REPLICA_COMMAND_DISPOSED'
+		);
+		const poll = scheduled.find(({ delay }) => delay === 25);
+		assert.ok(poll, 'accepted fact must schedule its first status poll');
+		assert.equal(
+			poll.timer.hasRef(),
+			true,
+			'pending projected work must keep Node alive until lifecycle settlement'
+		);
+
+		runtime.dispose();
+		await projectionFailure;
+		assert.equal(
+			cleared.includes(poll.timer),
+			true,
+			'projection settlement must clear rather than merely orphan the timer'
+		);
+	} finally {
+		runtime?.dispose();
+		for (const { timer } of scheduled) originalClearTimeout(timer);
+		globalThis.setTimeout = originalSetTimeout;
+		globalThis.clearTimeout = originalClearTimeout;
+	}
+});
+
+test('a throwing background-error reporter cannot reject the detached status monitor', async () => {
+	const replica = new FakeReplica();
+	let statusStarted;
+	const firstStatusRead = new Promise((resolve) => {
+		statusStarted = resolve;
+	});
+	let statusReads = 0;
+	let reports = 0;
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: (request) =>
+				Promise.resolve(commandEnvelope(request.commandId)),
+			status() {
+				statusReads += 1;
+				statusStarted();
+				return Promise.reject(new Error('transient status failure'));
+			}
+		},
+		{ createTodo: artifact() },
+		{
+			status: COMMAND_STATUS,
+			onBackgroundError() {
+				reports += 1;
+				throw new Error('reporter failure');
+			}
+		}
+	);
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-report-error', title: 'report safely' },
+		{ commandId: COMMAND_A }
+	);
+	const projectionFailure = assert.rejects(
+		receipt.projected,
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_DISPOSED'
+	);
+
+	await firstStatusRead;
+	await new Promise((resolve) => setImmediate(resolve));
+	assert.equal(statusReads, 1);
+	assert.equal(reports, 1);
+
+	runtime.dispose();
+	await projectionFailure;
+});
+
+test('dotted generated names become frozen nested namespaces and reject prefix collisions', () => {
+	const replica = new FakeReplica();
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{ dispatch: () => Promise.reject(new Error('unused')) },
+		{ 'todo.create': artifact() }
+	);
+	assert.equal(typeof runtime.commands.todo.create, 'function');
+	assert.equal(runtime.commands['todo.create'], undefined);
+	assert.equal(Object.isFrozen(runtime.commands), true);
+	assert.equal(Object.isFrozen(runtime.commands.todo), true);
+	runtime.dispose();
+
+	assert.throws(
+		() =>
+			createReplicaCommandRuntime(
+				new FakeReplica(),
+				{ dispatch: () => Promise.reject(new Error('unused')) },
+				{
+					todo: artifact({ name: 'todo.root' }),
+					'todo.create': artifact({ name: 'todo.create' })
+				}
+			),
+		/replica command namespace collision at todo\.create/
+	);
+});
+
+test('ambiguous and in-progress dispatches expose recovery without retiring optimism', async () => {
+	const replica = new FakeReplica();
+	const transport = {
+		dispatch(request) {
+			if (request.commandId === COMMAND_A) {
+				return Promise.reject(new Error('response lost'));
+			}
+			return Promise.resolve(
+				commandEnvelope(request.commandId, {
+					state: 'in_progress',
+					expects: []
+				})
+			);
+		},
+		status(request) {
+			return Promise.resolve(
+				request.commandId === COMMAND_A
+					? statusEnvelope(COMMAND_A, {
+							state: 'unknown',
+							omitMetadata: true
+						})
+					: statusEnvelope(COMMAND_B)
+			);
+		}
+	};
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		transport,
+		{ createTodo: artifact() },
+		{ status: COMMAND_STATUS }
+	);
+
+	let ambiguous;
+	try {
+		await runtime.commands.createTodo(
+			{ id: 'todo-ambiguous', title: 'ambiguous' },
+			{ commandId: COMMAND_A }
+		);
+		assert.fail('ambiguous dispatch should reject');
+	} catch (error) {
+		ambiguous = error;
+	}
+	assert.equal(ambiguous.code, 'REPLICA_COMMAND_TRANSPORT_AMBIGUOUS');
+	assert.equal(ambiguous.recovery.commandId, COMMAND_A);
+	assert.equal(replica.layers.get(COMMAND_A).state, 'optimistic');
+	const unknown = await ambiguous.recovery.status();
+	assert.deepEqual(unknown, { commandId: COMMAND_A, state: 'unknown' });
+	assert.equal(replica.layers.get(COMMAND_A).state, 'optimistic');
+
+	let inProgress;
+	try {
+		await runtime.commands.createTodo(
+			{ id: 'todo-progress', title: 'progress' },
+			{ commandId: COMMAND_B }
+		);
+		assert.fail('in-progress dispatch should reject');
+	} catch (error) {
+		inProgress = error;
+	}
+	assert.equal(inProgress.code, 'REPLICA_COMMAND_OUTCOME_PENDING');
+	assert.equal(inProgress.recovery.commandId, COMMAND_B);
+	assert.equal(replica.layers.get(COMMAND_B).state, 'optimistic');
+	assert.equal((await inProgress.recovery.status()).state, 'accepted_pending_projection');
+	assert.equal(replica.layers.get(COMMAND_B).state, 'accepted');
+
+	replica.rejectOptimisticLayer(COMMAND_A);
+	replica.rejectOptimisticLayer(COMMAND_B);
+	runtime.dispose();
+});
+
+test('terminal status rolls back only its layer and rejects its projected awaitable', async () => {
+	const replica = new FakeReplica();
+	const transport = {
+		dispatch: (request) => Promise.resolve(commandEnvelope(request.commandId)),
+		status: (request) =>
+			Promise.resolve(
+				statusEnvelope(request.commandId, {
+					state: 'projection_failed'
+				})
+			)
+	};
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		transport,
+		{ createTodo: artifact() },
+		{ status: COMMAND_STATUS }
+	);
+	const receipt = await runtime.commands.createTodo(
+		{ id: 'todo-failed', title: 'failed' },
+		{ commandId: COMMAND_A }
+	);
+	replica.createOptimisticLayer(COMMAND_B, () => undefined);
+	const projectedFailure = assert.rejects(
+		receipt.projected,
+		(error) =>
+			error instanceof ReplicaCommandRuntimeError &&
+			error.code === 'REPLICA_COMMAND_PROJECTION_FAILED'
+	);
+
+	assert.equal((await receipt.status()).state, 'projection_failed');
+	await projectedFailure;
+	assert.equal(replica.layers.has(COMMAND_A), false);
+	assert.equal(replica.layers.has(COMMAND_B), true);
+	assert.equal(replica.revalidations.length, 1);
+	assert.deepEqual(replica.revalidations[0], artifact().revalidation);
+	replica.rejectOptimisticLayer(COMMAND_B);
+	runtime.dispose();
+});
+
+test('post-dispatch protocol failure retains a reachable generated recovery handle', async () => {
+	const replica = new FakeReplica();
+	const transport = {
+		dispatch: (request) =>
+			Promise.resolve(
+				commandEnvelope(request.commandId, {
+					data: { unexpected: true }
+				})
+			),
+		status: (request) => Promise.resolve(statusEnvelope(request.commandId))
+	};
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		transport,
+		{ createTodo: artifact() },
+		{ status: COMMAND_STATUS }
+	);
+
+	let failure;
+	try {
+		await runtime.commands.createTodo(
+			{ id: 'todo-invalid-output', title: 'invalid' },
+			{ commandId: COMMAND_A }
+		);
+		assert.fail('invalid output should reject');
+	} catch (error) {
+		failure = error;
+	}
+	assert.equal(failure.code, 'REPLICA_COMMAND_PROTOCOL_INVALID');
+	assert.equal(failure.recovery.commandId, COMMAND_A);
+	assert.equal(replica.layers.get(COMMAND_A).state, 'accepted');
+	assert.equal((await failure.recovery.status()).state, 'accepted_pending_projection');
+	replica.rejectOptimisticLayer(COMMAND_A);
+	runtime.dispose();
+});
diff --git a/js/tests/replica-diagnostics.test.mjs b/js/tests/replica-diagnostics.test.mjs
new file mode 100644
index 00000000..7b19aeae
--- /dev/null
+++ b/js/tests/replica-diagnostics.test.mjs
@@ -0,0 +1,793 @@
+import assert from 'node:assert/strict';
+import { resolve } from 'node:path';
+import test from 'node:test';
+
+import { build } from 'esbuild';
+
+import {
+	createDistributedReplica,
+	createReplicaCommandRuntime,
+	createReplicaDevelopmentCapability,
+	createReplicaDiagnostics,
+	inspectReplicaCommandArtifact,
+	inspectReplicaOperationArtifact
+} from '../dist/replica/index.js';
+
+const Todo = Object.freeze({
+	id: 'Todo',
+	identityFields: Object.freeze(['id'])
+});
+
+const DIAGNOSTIC_SCHEMA_HASH = `sha256:${'b'.repeat(64)}`;
+
+const Todos = Object.freeze({
+	id: 'Todos.v1',
+	document: 'query Todos { todos { id title } }',
+	protocol: Object.freeze({
+		version: 1,
+		schemaHash: DIAGNOSTIC_SCHEMA_HASH,
+		surface: Object.freeze({ kind: 'role', name: 'user' }),
+		operation: 'Todos.v1',
+		trustedPresets: Object.freeze([])
+	}),
+	variableCodec: Object.freeze({
+		version: 1,
+		limits: Object.freeze({
+			maxDepth: 8,
+			maxBoolWidth: 32,
+			maxInList: 64
+		}),
+		variables: Object.freeze({}),
+		inputs: Object.freeze({})
+	}),
+	source: Object.freeze({
+		path: 'src/routes/todos/+page.graphql',
+		line: 2,
+		column: 1
+	}),
+	live: Object.freeze({
+		id: 'Todos.live.v1',
+		document: 'subscription TodosLive { todos { id title } }'
+	}),
+	roots: Object.freeze([
+		Object.freeze({
+			responseKey: 'todos',
+			field: 'todos',
+			cardinality: 'many',
+			nullable: false,
+			dependencies: Object.freeze(['todos']),
+			coverage: Object.freeze({ kind: 'complete' }),
+			selection: Object.freeze({
+				typename: 'todo',
+				storage: Object.freeze({
+					kind: 'normalized',
+					model: 'Todo',
+					identityFields: Object.freeze(['id'])
+				}),
+				members: Object.freeze([
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: 'id',
+						field: 'id',
+						codec: 'ID',
+						nullable: false
+					}),
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: 'title',
+						field: 'title',
+						codec: 'String',
+						nullable: false
+					}),
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: '_distributed_revision',
+						field: '__row_revision',
+						codec: 'BigInt',
+						nullable: false,
+						expose: false
+					})
+				])
+			})
+		})
+	])
+});
+
+function todosFrame(revision, data, errors = undefined) {
+	const position = String(revision);
+	const rows = Array.isArray(data?.todos) ? data.todos : [];
+	return {
+		data,
+		...(errors === undefined ? {} : { errors }),
+		extensions: {
+			distributed: {
+				protocolVersion: 1,
+				schemaHash: DIAGNOSTIC_SCHEMA_HASH,
+				cacheScope: 'scope:diagnostics-user',
+				operation: Todos.id,
+				trustedPresets: [],
+				snapshot: {
+					scopeToken: 'snapshot:todos',
+					recordsComplete: true,
+					indexesComparable: true,
+					records: rows.map((row, index) => ({
+						path: ['todos', String(index)],
+						model: Todo.id,
+						scopeToken: `record:todo:${row.id}`,
+						incarnation: '1',
+						revision: String(row._distributed_revision),
+						tombstone: false
+					})),
+					indexes: [
+						{
+							projection: 'todos',
+							scopeToken: 'index:todos',
+							position
+						}
+					],
+					observations: []
+				}
+			}
+		}
+	};
+}
+
+const commandArtifact = Object.freeze({
+	version: 1,
+	name: 'todo.rename',
+	mutationField: 'renameTodo',
+	document: 'mutation RenameTodo { renameTodo }',
+	operationHash: `sha256:${'a'.repeat(64)}`,
+	protocol: Object.freeze({
+		version: 1,
+		schemaHash: DIAGNOSTIC_SCHEMA_HASH,
+		protocolHash: `sha256:${'c'.repeat(64)}`,
+		surface: Object.freeze({ kind: 'role', name: 'user' }),
+		operation: `sha256:${'a'.repeat(64)}`,
+		trustedPresets: Object.freeze([])
+	}),
+	input: Object.freeze({
+		kind: 'object',
+		definition: Object.freeze({
+			name: 'RenameTodoInput',
+			fields: Object.freeze([
+				Object.freeze({
+					name: 'id',
+					typeName: 'ID',
+					nullable: false,
+					list: false,
+					itemNullable: false,
+					codec: 'string'
+				})
+			])
+		})
+	}),
+	output: Object.freeze({
+		kind: 'object',
+		definition: Object.freeze({
+			name: 'RenameTodoResult',
+			fields: Object.freeze([
+				Object.freeze({
+					name: 'accepted',
+					typeName: 'Boolean',
+					nullable: false,
+					list: false,
+					itemNullable: false,
+					codec: 'boolean'
+				})
+			])
+		})
+	}),
+	consistency: 'fact',
+	effects: Object.freeze({
+		version: 1,
+		operations: Object.freeze([
+			Object.freeze({
+				kind: 'patch',
+				model: 'Todo',
+				key: Object.freeze({
+					fields: Object.freeze([
+						Object.freeze({
+							field: 'id',
+							value: Object.freeze({
+								kind: 'input',
+								path: Object.freeze(['id'])
+							})
+						})
+					])
+				}),
+				fields: Object.freeze([
+					Object.freeze({
+						field: 'title',
+						value: Object.freeze({
+							kind: 'constant',
+							value: 'must-never-appear-in-inspection'
+						})
+					}),
+					Object.freeze({
+						field: 'owner_id',
+						value: Object.freeze({
+							kind: 'trusted_preset',
+							name: 'x-private-claim-name'
+						})
+					})
+				])
+			})
+		]),
+		fallback: 'revalidate'
+	}),
+	revalidation: Object.freeze({
+		version: 1,
+		required: false,
+		dependencies: Object.freeze(['todos']),
+		models: Object.freeze(['Todo']),
+		relationships: Object.freeze([])
+	})
+});
+
+function diagnosticState(overrides = {}) {
+	return Object.freeze({
+		scope: Object.freeze({ generation: 0, established: false }),
+		records: Object.freeze([]),
+		indexes: Object.freeze([]),
+		layers: Object.freeze([]),
+		receipts: Object.freeze([]),
+		...overrides
+	});
+}
+
+test('default snapshots redact identities, arguments, field values, and scope material', () => {
+	const diagnostics = createReplicaDiagnostics({ now: () => 10 });
+	diagnostics.update(
+		diagnosticState({
+			scope: Object.freeze({
+				generation: 1,
+				established: true,
+				protocolVersion: 1,
+				schemaHash: `sha256:${'d'.repeat(64)}`
+			}),
+			records: Object.freeze([
+				Object.freeze({
+					key: 'record:Todo:["private-todo-id"]',
+					model: 'Todo',
+					revision: '4',
+					incarnation: '1',
+					tombstone: false,
+					presentFields: Object.freeze(['id', 'title']),
+					presentLinks: Object.freeze([]),
+					values: Object.freeze({
+						id: 'private-todo-id',
+						title: 'private title'
+					})
+				})
+			]),
+			indexes: Object.freeze([
+				Object.freeze({
+					key: 'index:private-owner-filter',
+					revision: '8',
+					records: Object.freeze(['record:Todo:["private-todo-id"]']),
+					complete: true,
+					deleted: false,
+					field: 'todos',
+					argumentNames: Object.freeze(['where']),
+					arguments: Object.freeze({
+						where: Object.freeze({ owner_id: 'private-user-id' })
+					}),
+					coverage: Object.freeze({ kind: 'complete' }),
+					dependencies: Object.freeze(['todos'])
+				})
+			]),
+			layers: Object.freeze([
+				Object.freeze({
+					id: 'private-command-id',
+					sequence: 1,
+					state: 'accepted',
+					recordChanges: 1,
+					indexChanges: 0,
+					semanticChanges: 1
+				})
+			]),
+			receipts: Object.freeze([
+				Object.freeze({
+					commandId: 'private-command-id',
+					state: 'accepted_pending_projection',
+					expectations: Object.freeze([
+						Object.freeze({
+							projection: 'todos',
+							model: 'Todo',
+							observed: false
+						})
+					])
+				})
+			])
+		})
+	);
+
+	const snapshot = diagnostics.snapshot();
+	assert.equal(snapshot.mode, 'redacted');
+	assert.equal(snapshot.records[0].key, 'record#1');
+	assert.equal(snapshot.indexes[0].key, 'index#1');
+	assert.deepEqual(snapshot.indexes[0].records, ['record#1']);
+	assert.deepEqual(snapshot.indexes[0].argumentNames, ['where']);
+	assert.equal(snapshot.indexes[0].arguments, undefined);
+	assert.equal(snapshot.records[0].values, undefined);
+	assert.equal(snapshot.layers[0].id, snapshot.receipts[0].commandId);
+	const encoded = JSON.stringify(snapshot);
+	for (const secret of [
+		'private-todo-id',
+		'private title',
+		'private-user-id',
+		'private-owner-filter',
+		'private-command-id'
+	]) {
+		assert.equal(encoded.includes(secret), false, secret);
+	}
+	assert.equal(encoded.includes('cacheScope'), false);
+});
+
+test('snapshot identity is stable for Svelte stores and React external stores', () => {
+	const diagnostics = createReplicaDiagnostics({ now: () => 10 });
+	const initial = diagnostics.snapshot();
+	assert.equal(diagnostics.snapshot(), initial);
+
+	const svelteEmissions = [];
+	const { subscribe, getSnapshot } = diagnostics;
+	const unsubscribe = subscribe((snapshot) =>
+		svelteEmissions.push(snapshot)
+	);
+	const reactSnapshot = getSnapshot();
+	assert.equal(svelteEmissions[0], reactSnapshot);
+
+	diagnostics.event({ kind: 'gc', records: 0 });
+	const changed = diagnostics.snapshot();
+	assert.notEqual(changed, initial);
+	assert.equal(diagnostics.snapshot(), changed);
+	assert.equal(svelteEmissions.at(-1), changed);
+
+	unsubscribe();
+	diagnostics.event({ kind: 'gc', records: 0 });
+	assert.equal(svelteEmissions.length, 2);
+});
+
+test('field values require both a development capability and an explicit redactor', () => {
+	const capability = createReplicaDevelopmentCapability();
+	assert.throws(
+		() =>
+			createReplicaDiagnostics({
+				fieldValues: {
+					capability: Object.freeze({ version: 1 }),
+					allow: () => true,
+					redact: (value) => value
+				}
+			}),
+		/development capability/
+	);
+	const diagnostics = createReplicaDiagnostics({
+		development: capability,
+		fieldValues: {
+			capability,
+			allow: ({ field }) => field === 'title',
+			redact: () => '[support-redacted]'
+		}
+	});
+	const replica = createDistributedReplica({ diagnostics });
+	replica.writeResult(
+		Todos,
+		{},
+		todosFrame(1, {
+				todos: [
+					{
+						id: 'todo-1',
+						title: 'private title',
+						_distributed_revision: 1
+					}
+				]
+			}),
+		'network'
+	);
+	const snapshot = diagnostics.snapshot();
+	assert.equal(snapshot.mode, 'development');
+	assert.match(snapshot.records[0].key, /todo-1/);
+	assert.deepEqual(snapshot.records[0].values, {
+		title: '[support-redacted]'
+	});
+	assert.equal(JSON.stringify(snapshot).includes('private title'), false);
+});
+
+test('free-form reasons require a development capability and explicit redactor', () => {
+	const secret = 'private claim value embedded by application code';
+	assert.throws(
+		() =>
+			createReplicaDiagnostics({
+				reasons: {
+					capability: Object.freeze({ version: 1 }),
+					redact: () => '[safe]'
+				}
+			}),
+		/development capability/
+	);
+	const capability = createReplicaDevelopmentCapability();
+	const diagnostics = createReplicaDiagnostics({
+		development: capability,
+		reasons: {
+			capability,
+			redact: (_reason, context) => `[support:${context.kind}]`
+		}
+	});
+	diagnostics.update(
+		diagnosticState({
+			indexes: Object.freeze([
+				Object.freeze({
+					key: 'index:private',
+					revision: '1',
+					records: Object.freeze([]),
+					complete: false,
+					deleted: false,
+					staleReason: secret
+				})
+			])
+		})
+	);
+	diagnostics.event({
+		kind: 'index-decision',
+		index: 'index:private',
+		decision: 'stale',
+		reason: secret
+	});
+	const snapshot = diagnostics.snapshot();
+	assert.equal(snapshot.indexes[0].staleReason, '[support:index-stale]');
+	assert.equal(snapshot.events[0].reason, '[support:index-stale]');
+	assert.equal(JSON.stringify(snapshot).includes(secret), false);
+});
+
+test('artifact inspection explains source, injected fields, dependencies, live plan, and effects without values', () => {
+	const operation = inspectReplicaOperationArtifact(Todos);
+	assert.deepEqual(operation.source, {
+		path: 'src/routes/todos/+page.graphql',
+		line: 2,
+		column: 1
+	});
+	assert.deepEqual(operation.dependencies, ['todos']);
+	assert.deepEqual(operation.live, { operation: 'Todos.live.v1' });
+	assert.deepEqual(operation.injectedFields, [
+		{
+			path: 'todos._distributed_revision',
+			responseKey: '_distributed_revision',
+			field: '__row_revision'
+		}
+	]);
+	assert.deepEqual(operation.indexes[0], {
+		path: 'todos',
+		field: 'todos',
+		cardinality: 'many',
+		dependencies: ['todos'],
+		coverage: 'complete',
+		filtered: false,
+		ordered: false
+	});
+	const unsafeSource = inspectReplicaOperationArtifact(
+		Object.freeze({
+			...Todos,
+			source: Object.freeze({
+				path: '/private/user\nclaim-secret.graphql',
+				line: 1,
+				column: 1
+			})
+		})
+	);
+	assert.equal(unsafeSource.source, undefined);
+	assert.equal(JSON.stringify(unsafeSource).includes('claim-secret'), false);
+	const ambiguousWindowsSource = inspectReplicaOperationArtifact(
+		Object.freeze({
+			...Todos,
+			source: Object.freeze({
+				path: '..\\private\\claim-secret.graphql',
+				line: 1,
+				column: 1
+			})
+		})
+	);
+	assert.equal(ambiguousWindowsSource.source, undefined);
+	assert.equal(
+		JSON.stringify(ambiguousWindowsSource).includes('claim-secret'),
+		false
+	);
+
+	const command = inspectReplicaCommandArtifact(commandArtifact);
+	assert.deepEqual(command.effects, [
+		{
+			kind: 'patch',
+			models: ['Todo'],
+			fields: ['id', 'owner_id', 'title'],
+			valueSources: ['constant', 'input', 'trusted_preset']
+		}
+	]);
+	const encoded = JSON.stringify(command);
+	assert.equal(encoded.includes('must-never-appear'), false);
+	assert.equal(encoded.includes('x-private-claim-name'), false);
+});
+
+test('one diagnostics store receives both replica state and generated command artifacts', () => {
+	const diagnostics = createReplicaDiagnostics();
+	const replica = createDistributedReplica({ diagnostics });
+	const operationHash = `sha256:${'d'.repeat(64)}`;
+	const protocolTodos = Object.freeze({
+		...Todos,
+		id: operationHash,
+		live: undefined,
+		variableCodec: Object.freeze({
+			version: 1,
+			limits: Object.freeze({
+				maxDepth: 8,
+				maxBoolWidth: 32,
+				maxInList: 64
+			}),
+			variables: Object.freeze({}),
+			inputs: Object.freeze({})
+		}),
+		protocol: Object.freeze({
+			version: 1,
+			schemaHash: commandArtifact.protocol.schemaHash,
+			surface: commandArtifact.protocol.surface,
+			operation: operationHash,
+			trustedPresets: Object.freeze([])
+		})
+	});
+	replica.read(protocolTodos, {});
+	const runtime = createReplicaCommandRuntime(
+		replica,
+		{
+			dispatch: () => Promise.reject(new Error('not dispatched in this test'))
+		},
+		{ rename: commandArtifact },
+		{ diagnostics }
+	);
+
+	const snapshot = diagnostics.snapshot();
+	assert.deepEqual(
+		snapshot.artifacts.operations.map((operation) => operation.id),
+		[protocolTodos.id]
+	);
+	assert.deepEqual(
+		snapshot.artifacts.commands.map((command) => command.name),
+		[commandArtifact.name]
+	);
+	assert.equal(snapshot.records.length, 0);
+	runtime.dispose();
+});
+
+test('replica integration exposes structural normalization, index, layer, receipt, rebase, and GC reasons', () => {
+	let tick = 0;
+	const diagnostics = createReplicaDiagnostics({
+		maxEvents: 50,
+		now: () => ++tick
+	});
+	const replica = createDistributedReplica({ diagnostics });
+	replica.read(Todos, {});
+	replica.writeResult(
+		Todos,
+		{},
+		todosFrame(1, {
+				todos: [
+					{
+						id: 'todo-1',
+						title: 'private title',
+						_distributed_revision: 1
+					}
+				]
+			}),
+		'network'
+	);
+	const maliciousReason =
+		'claim=user-private-claim; row=todo-private-row; token=private-token';
+	replica.markIndexStale({ field: 'todos' }, maliciousReason);
+	replica.createOptimisticLayer('command-private-a', (writer) => {
+		writer.writeRecord(Todo, 'todo-1', {
+			fields: { title: 'optimistic private title' }
+		});
+	});
+	replica.createOptimisticLayer('command-private-b', (writer) => {
+		writer.writeRecord(Todo, 'todo-1', {
+			fields: { title: 'later private title' }
+		});
+	});
+	replica.markOptimisticLayerAccepted('command-private-a', {
+		commandId: 'command-private-a',
+		causationId: 'private-causation',
+		state: 'accepted_pending_projection',
+		consistency: 'fact',
+		expects: [
+			{
+				projection: 'todos',
+				model: 'Todo',
+				scopeToken: 'private-obligation-token'
+			}
+		],
+		observations: [],
+			records: []
+		});
+	const acceptedReceipt = diagnostics
+		.snapshot()
+		.receipts.find(
+			(receipt) => receipt.state === 'accepted_pending_projection'
+		);
+	assert.equal(acceptedReceipt?.state, 'accepted_pending_projection');
+	assert.equal(acceptedReceipt?.expectations[0].projection, 'todos');
+	replica.rejectOptimisticLayer('command-private-a');
+	replica.gc();
+
+	const snapshot = diagnostics.snapshot();
+	assert.equal(snapshot.records.length, 1);
+	assert.equal(snapshot.indexes.length, 1);
+	assert.equal(snapshot.layers.length, 1);
+	assert.equal(snapshot.receipts[0].state, 'optimistic');
+	assert.equal(snapshot.receipts[0].consistency, undefined);
+	assert.equal(snapshot.indexes[0].staleReason, 'application-stale');
+	assert.equal(snapshot.artifacts.operations[0].id, Todos.id);
+	assert(snapshot.events.some((event) => event.kind === 'normalization'));
+	assert(
+		snapshot.events.some(
+			(event) =>
+				event.kind === 'index-decision' &&
+				event.decision === 'maintained'
+		)
+	);
+	assert(
+		snapshot.events.some(
+			(event) =>
+				event.kind === 'index-decision' &&
+				event.decision === 'stale' &&
+				event.reason === 'application-stale'
+		)
+	);
+	assert(
+		snapshot.events.some(
+			(event) => event.kind === 'layer' && event.action === 'rebased'
+		)
+	);
+	assert(snapshot.events.some((event) => event.kind === 'receipt'));
+	assert(snapshot.events.some((event) => event.kind === 'gc'));
+	const encoded = JSON.stringify(snapshot);
+	for (const secret of [
+		'command-private-a',
+		'command-private-b',
+			'private-causation',
+			'private-obligation-token',
+			'private title',
+			maliciousReason,
+			'user-private-claim',
+			'todo-private-row',
+			'private-token'
+	]) {
+		assert.equal(encoded.includes(secret), false, secret);
+	}
+});
+
+test('event log is bounded and a scope generation change removes cross-scope state', () => {
+	let tick = 0;
+	const diagnostics = createReplicaDiagnostics({
+		maxEvents: 2,
+		now: () => ++tick
+	});
+	diagnostics.inspectOperation(Todos);
+	for (let index = 0; index < 3; index += 1) {
+		diagnostics.event({
+			kind: 'gc',
+			records: index
+		});
+	}
+	assert.deepEqual(
+		diagnostics.snapshot().events.map((event) => event.sequence),
+		[2, 3]
+	);
+	diagnostics.update(
+		diagnosticState({
+			scope: Object.freeze({
+				generation: 2,
+				established: true,
+				protocolVersion: 1,
+				schemaHash: `sha256:${'e'.repeat(64)}`
+			})
+		})
+	);
+	const snapshot = diagnostics.snapshot();
+	assert.equal(snapshot.events.length, 0);
+	assert.equal(snapshot.artifacts.operations.length, 0);
+	assert.equal(snapshot.records.length, 0);
+});
+
+test('late HTTP results are recorded as authorization-fenced without merging data', async () => {
+	let resolveFetch;
+	let startedResolve;
+	const started = new Promise((resolveStarted) => {
+		startedResolve = resolveStarted;
+	});
+	const diagnostics = createReplicaDiagnostics();
+	const replica = createDistributedReplica({
+		diagnostics,
+		transport: {
+			fetch: () =>
+				new Promise((resolveResult) => {
+					resolveFetch = resolveResult;
+					startedResolve();
+				})
+		}
+	});
+	const watch = replica.watch(Todos, {});
+	await started;
+	replica.invalidateAuthorization();
+	resolveFetch(
+		todosFrame(1, {
+			todos: [
+				{
+					id: 'late-private-id',
+					title: 'late private title',
+					_distributed_revision: 1
+				}
+			]
+		})
+	);
+	await new Promise((resolveTurn) => setImmediate(resolveTurn));
+	await new Promise((resolveTurn) => setImmediate(resolveTurn));
+	const snapshot = diagnostics.snapshot();
+	assert.equal(snapshot.records.length, 0);
+	assert(
+		snapshot.events.some(
+			(event) =>
+				event.kind === 'response-fenced' &&
+				event.transport === 'http' &&
+				event.reason === 'authorization-generation'
+		)
+	);
+	assert.equal(JSON.stringify(snapshot).includes('late-private-id'), false);
+	watch.destroy();
+});
+
+test('diagnostics code is tree-shaken unless explicitly imported', async () => {
+	const replicaEntry = resolve('dist/replica/index.js');
+	const withoutDiagnostics = await build({
+		stdin: {
+			contents: `import { createDistributedReplica } from ${JSON.stringify(
+				replicaEntry
+			)}; console.log(createDistributedReplica);`,
+			resolveDir: process.cwd(),
+			sourcefile: 'without-diagnostics.mjs'
+		},
+		bundle: true,
+		format: 'esm',
+		platform: 'browser',
+		target: 'es2022',
+		minify: true,
+		treeShaking: true,
+		write: false
+	});
+	assert.equal(
+		withoutDiagnostics.outputFiles[0].text.includes(
+			'distributed-replica-diagnostics-v1'
+		),
+		false
+	);
+
+	const withDiagnostics = await build({
+		stdin: {
+			contents: `import { createReplicaDiagnostics } from ${JSON.stringify(
+				replicaEntry
+			)}; console.log(createReplicaDiagnostics().snapshot().marker);`,
+			resolveDir: process.cwd(),
+			sourcefile: 'with-diagnostics.mjs'
+		},
+		bundle: true,
+		format: 'esm',
+		platform: 'browser',
+		target: 'es2022',
+		minify: true,
+		treeShaking: true,
+		write: false
+	});
+	assert.equal(
+		withDiagnostics.outputFiles[0].text.includes(
+			'distributed-replica-diagnostics-v1'
+		),
+		true
+	);
+});
diff --git a/js/tests/replica-graphql-transport.test.mjs b/js/tests/replica-graphql-transport.test.mjs
new file mode 100644
index 00000000..034982d8
--- /dev/null
+++ b/js/tests/replica-graphql-transport.test.mjs
@@ -0,0 +1,257 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	createReplicaGraphqlTransport
+} from '../dist/replica/index.js';
+
+function jsonResponse(body, status = 200) {
+	return {
+		status,
+		statusText: status === 200 ? 'OK' : 'Error',
+		text: async () => JSON.stringify(body)
+	};
+}
+
+function tick() {
+	return new Promise((resolve) => setImmediate(resolve));
+}
+
+test('replica GraphQL HTTP and command work share auth and preserve exact extensions and abort signals', async () => {
+	const calls = [];
+	const controller = new AbortController();
+	let authCalls = 0;
+	const transport = createReplicaGraphqlTransport({
+		getUrl: () => '/graphql',
+		getAuth: async () => {
+			authCalls += 1;
+			return { accessToken: 'access-token' };
+		},
+		fetch: async (url, init) => {
+			calls.push({ url, init, body: JSON.parse(init.body) });
+			return jsonResponse({ data: { ok: true } });
+		}
+	});
+	const clientExtensions = {
+		distributed: {
+			client: {
+				surface: { kind: 'role', name: 'user' },
+				schemaHash: `sha256:${'a'.repeat(64)}`
+			}
+		}
+	};
+
+	const query = await transport.fetch({
+		operation: 'query',
+		operationId: 'query:todos',
+		document: 'query Todos { todos { id } }',
+		variables: {},
+		artifact: { id: 'query:todos', document: '', roots: [] },
+		extensions: clientExtensions,
+		signal: controller.signal
+	});
+	assert.deepEqual(query.data, { ok: true });
+
+	const dispatched = await transport.dispatch({
+		operation: 'mutation',
+		commandName: 'todo.complete',
+		commandId: 'command-1',
+		mutationField: 'todoComplete',
+		document: 'mutation Complete { todoComplete }',
+		operationHash: `sha256:${'b'.repeat(64)}`,
+		variables: { commandId: 'command-1', input: { id: 'todo-1' } },
+		extensions: clientExtensions,
+		signal: controller.signal
+	});
+	assert.equal(dispatched.status, 200);
+
+	const status = await transport.status({
+		operation: 'status',
+		commandId: 'command-1',
+		name: 'CommandStatus',
+		document: 'query CommandStatus { commandStatus }',
+		operationHash: `sha256:${'c'.repeat(64)}`,
+		variables: { commandId: 'command-1' },
+		extensions: clientExtensions,
+		signal: controller.signal
+	});
+	assert.equal(status.status, 200);
+
+	assert.equal(authCalls, 3);
+	assert.equal(calls.length, 3);
+	for (const call of calls) {
+		assert.equal(call.url, '/graphql');
+		assert.equal(call.init.headers.authorization, 'Bearer access-token');
+		assert.equal(call.init.signal, controller.signal);
+		assert.deepEqual(call.body.extensions, clientExtensions);
+	}
+	assert.equal(calls[0].body.query, 'query Todos { todos { id } }');
+	assert.deepEqual(calls[1].body.variables, {
+		commandId: 'command-1',
+		input: { id: 'todo-1' }
+	});
+});
+
+test('replica GraphQL live work merges surface binding with resume and closes on abort', async () => {
+	class FakeWebSocket {
+		static CONNECTING = 0;
+		static OPEN = 1;
+		static CLOSING = 2;
+		static CLOSED = 3;
+		static instances = [];
+
+		readyState = FakeWebSocket.CONNECTING;
+		sent = [];
+		closed = false;
+
+		constructor(url, protocol) {
+			this.url = url;
+			this.protocol = protocol;
+			FakeWebSocket.instances.push(this);
+		}
+
+		send(value) {
+			this.sent.push(JSON.parse(value));
+		}
+
+		close() {
+			this.closed = true;
+			this.readyState = FakeWebSocket.CLOSED;
+		}
+
+		open() {
+			this.readyState = FakeWebSocket.OPEN;
+			this.onopen?.();
+		}
+
+		message(value) {
+			this.onmessage?.({ data: JSON.stringify(value) });
+		}
+	}
+
+	const controller = new AbortController();
+	const next = [];
+	const errors = [];
+	let completions = 0;
+	const transport = createReplicaGraphqlTransport({
+		getUrl: () => '/graphql',
+		getAuth: () => ({ userId: 'alice', role: 'user' }),
+		webSocket: FakeWebSocket
+	});
+	const extensions = {
+		distributed: {
+			client: {
+				surface: { kind: 'application', name: 'e2e-ui', roles: ['admin', 'user'] },
+				schemaHash: `sha256:${'d'.repeat(64)}`
+			}
+		}
+	};
+	const resume = [
+		{ projection: 'todos', position: '7', token: 'resume-token' }
+	];
+	const liveRequest = {
+		operation: 'live',
+		operationId: 'live:todos',
+		document: 'subscription TodosLive { todos { id } }',
+		variables: { room: 'lobby' },
+		artifact: { id: 'query:todos', document: '', roots: [] },
+		extensions,
+		resume,
+		signal: controller.signal
+	};
+	const observer = {
+		next: (value) => next.push(value),
+		error: (error) => errors.push(error),
+		complete: () => {
+			completions += 1;
+		}
+	};
+	const stop = transport.subscribe(
+		liveRequest,
+		observer
+	);
+	await tick();
+
+	assert.equal(FakeWebSocket.instances.length, 1);
+	const socket = FakeWebSocket.instances[0];
+	assert.equal(socket.protocol, 'graphql-transport-ws');
+	assert.match(socket.url, /graphql\/ws/);
+	assert.match(socket.url, /x-user-id=alice/);
+	socket.open();
+	assert.deepEqual(socket.sent[0], {
+		type: 'connection_init',
+		payload: { 'x-user-id': 'alice', 'x-role': 'user' }
+	});
+	socket.message({ type: 'connection_ack' });
+	assert.deepEqual(socket.sent[1], {
+		type: 'subscribe',
+		id: '1',
+		payload: {
+			query: 'subscription TodosLive { todos { id } }',
+			variables: { room: 'lobby' },
+			extensions: {
+				distributed: {
+					client: extensions.distributed.client,
+					resume: { cursors: resume }
+				}
+			}
+		}
+	});
+	socket.message({ type: 'next', payload: { data: { todos: [{ id: '1' }] } } });
+	assert.deepEqual(next, [{ data: { todos: [{ id: '1' }] } }]);
+	assert.deepEqual(errors, []);
+	socket.message({ type: 'complete', id: '1' });
+	assert.equal(completions, 1);
+	assert.equal(socket.closed, true);
+
+	const stopError = transport.subscribe(liveRequest, observer);
+	await tick();
+	const errorSocket = FakeWebSocket.instances[1];
+	errorSocket.open();
+	errorSocket.message({ type: 'error', id: '1', payload: 'terminal error' });
+	assert.deepEqual(errors, ['terminal error']);
+	assert.equal(errorSocket.closed, true);
+	assert.equal(completions, 1);
+
+	controller.abort();
+	assert.equal(socket.closed, true);
+	stop();
+	stopError();
+	assert.equal(socket.closed, true);
+	assert.equal(errorSocket.closed, true);
+	assert.equal(completions, 1);
+});
+
+test('canceling a live request before async auth resolves prevents a socket', async () => {
+	let release;
+	const auth = new Promise((resolve) => {
+		release = resolve;
+	});
+	class ForbiddenWebSocket {
+		constructor() {
+			throw new Error('socket must not open');
+		}
+	}
+	const transport = createReplicaGraphqlTransport({
+		getUrl: () => '/graphql',
+		getAuth: () => auth,
+		webSocket: ForbiddenWebSocket
+	});
+	const stop = transport.subscribe(
+		{
+			operation: 'live',
+			operationId: 'live',
+			document: 'subscription Live { items { id } }',
+			variables: {},
+			artifact: { id: 'query', document: '', roots: [] }
+		},
+		{
+			next: () => undefined,
+			error: () => undefined,
+			complete: () => undefined
+		}
+	);
+	stop();
+	release({});
+	await tick();
+});
diff --git a/js/tests/replica-index-maintenance.test.mjs b/js/tests/replica-index-maintenance.test.mjs
new file mode 100644
index 00000000..9d8e219a
--- /dev/null
+++ b/js/tests/replica-index-maintenance.test.mjs
@@ -0,0 +1,1224 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	createReplicaIndexMaintenanceRegistry,
+	formatReplicaIndexStaleReason,
+	replicaIndexKey,
+	replicaRecordKey
+} from '../dist/replica/index.js';
+
+const Todo = Object.freeze({ id: 'Todo', identityFields: Object.freeze(['id']) });
+const Board = Object.freeze({ id: 'Board', identityFields: Object.freeze(['id']) });
+const Card = Object.freeze({ id: 'Card', identityFields: Object.freeze(['id']) });
+
+const COMPLETE = Object.freeze({ kind: 'complete' });
+const COMPLETE_PAGINATION = Object.freeze({
+	kind: 'complete',
+	insert: 'local',
+	delete: 'local',
+	reorder: 'local',
+	stableUpdate: 'local'
+});
+const OFFSET_PAGINATION = Object.freeze({
+	kind: 'offset',
+	insert: 'local',
+	delete: 'local',
+	reorder: 'local',
+	stableUpdate: 'local'
+});
+
+const literal = (value) => Object.freeze({ kind: 'literal', value });
+const variable = (name) => Object.freeze({ kind: 'variable', name });
+const scalar = (responseKey, field) =>
+	Object.freeze({
+		kind: 'scalar',
+		responseKey,
+		field,
+		codec: 'string',
+		nullable: false
+	});
+const record = (model, identity, fields) =>
+	Object.freeze({
+		key: replicaRecordKey(model, identity),
+		model: model.id,
+		fields: Object.freeze({ ...fields })
+	});
+const index = (
+	field,
+	records,
+	{
+		parent,
+		arguments: argumentsValue = {},
+		coverage = COMPLETE,
+		dependencies = ['todos'],
+		complete = true,
+		staleReason
+	} = {}
+) =>
+	Object.freeze({
+		key: replicaIndexKey({
+			...(parent === undefined ? {} : { parent }),
+			field,
+			arguments: argumentsValue
+		}),
+		records: Object.freeze([...records]),
+		complete,
+		metadata: Object.freeze({
+			...(parent === undefined ? {} : { parent }),
+			field,
+			arguments: Object.freeze(argumentsValue),
+			coverage,
+			dependencies: Object.freeze([...dependencies]),
+			...(staleReason === undefined ? {} : { staleReason })
+		})
+	});
+
+const FILTER_FIELDS = Object.freeze([
+	Object.freeze({
+		field: 'active',
+		scalar: 'Boolean',
+		codec: 'boolean',
+		nullable: false,
+		operators: Object.freeze(['_eq'])
+	}),
+	Object.freeze({
+		field: 'id',
+		scalar: 'ID',
+		codec: 'string',
+		nullable: false,
+		operators: Object.freeze(['_eq'])
+	}),
+	Object.freeze({
+		field: 'rank',
+		scalar: 'Int',
+		codec: 'int32',
+		nullable: false,
+		operators: Object.freeze(['_eq', '_gt', '_gte', '_lt', '_lte'])
+	}),
+	Object.freeze({
+		field: 'tenantId',
+		scalar: 'ID',
+		codec: 'string',
+		nullable: false,
+		operators: Object.freeze(['_eq'])
+	})
+]);
+
+const ORDER = Object.freeze({
+	input: literal(Object.freeze([Object.freeze({ rank: 'asc' })])),
+	fields: Object.freeze(
+		FILTER_FIELDS.map(({ field, scalar: scalarName, codec, nullable }) =>
+			Object.freeze({ field, scalar: scalarName, codec, nullable })
+		)
+	),
+	tieBreakers: Object.freeze([
+		Object.freeze({
+			field: 'id',
+			scalar: 'ID',
+			codec: 'string',
+			nullable: false
+		})
+	])
+});
+
+const unrestrictedFilter = (input = literal({ active: { _eq: true } })) =>
+	Object.freeze({
+		input,
+		fields: FILTER_FIELDS,
+		relationships: Object.freeze([]),
+		rowPolicy: Object.freeze({ kind: 'unrestricted' })
+	});
+
+const TODO_SELECTION = Object.freeze({
+	typename: Todo.id,
+	storage: Object.freeze({
+		kind: 'normalized',
+		model: Todo.id,
+		identityFields: Todo.identityFields
+	}),
+	members: Object.freeze([
+		scalar('id', 'id'),
+		scalar('active', 'active'),
+		scalar('rank', 'rank'),
+		scalar('tenantId', 'tenantId')
+	])
+});
+
+const VARIABLE_CODEC = Object.freeze({
+	version: 1,
+	limits: Object.freeze({
+		maxDepth: 8,
+		maxBoolWidth: 256,
+		maxInList: 1_000
+	}),
+	variables: Object.freeze({
+		owner: Object.freeze({
+			kind: 'scalar',
+			scalar: 'ID',
+			codec: 'string',
+			nullable: false
+		})
+	}),
+	inputs: Object.freeze({})
+});
+
+const NO_VARIABLES = Object.freeze({
+	version: 1,
+	limits: Object.freeze({
+		maxDepth: 8,
+		maxBoolWidth: 256,
+		maxInList: 1_000
+	}),
+	variables: Object.freeze({}),
+	inputs: Object.freeze({})
+});
+
+function todoArtifact({
+	id = 'Todos',
+	responseKey = 'todos',
+	where = unrestrictedFilter(),
+	order = ORDER,
+	pagination = COMPLETE_PAGINATION,
+	coverage = COMPLETE,
+	arguments: argumentsValue = Object.freeze({ owner: variable('owner') }),
+	rowPolicy,
+	trustedPresets = Object.freeze([]),
+	extraRoots = []
+} = {}) {
+	const filter =
+		rowPolicy === undefined
+			? where
+			: Object.freeze({ ...where, rowPolicy: Object.freeze(rowPolicy) });
+	const root = Object.freeze({
+		responseKey,
+		field: 'todos',
+		cardinality: 'many',
+		nullable: false,
+		arguments: argumentsValue,
+		dependencies: Object.freeze(['todos']),
+		coverage,
+		filter,
+		order,
+		pagination,
+		selection: TODO_SELECTION
+	});
+	return Object.freeze({
+		id,
+		document: `query ${id} { ${responseKey}: todos { id } }`,
+		protocol: Object.freeze({
+			version: 1,
+			schemaHash: `sha256:${'1'.repeat(64)}`,
+			surface: Object.freeze({ kind: 'role', name: 'user' }),
+			operation: id,
+			trustedPresets
+		}),
+		variableCodec: VARIABLE_CODEC,
+		roots: Object.freeze([root, ...extraRoots])
+	});
+}
+
+function snapshot(records, indexes) {
+	return Object.freeze({
+		records: Object.freeze(records),
+		indexes: Object.freeze(indexes)
+	});
+}
+
+function layer(id, changes) {
+	return Object.freeze({ id, changes: Object.freeze(changes) });
+}
+
+function upsert(model, identity, fields, dependencies = ['todos']) {
+	return Object.freeze({
+		kind: 'upsert',
+		model: model.id,
+		key: replicaRecordKey(model, identity),
+		fields: Object.freeze(fields),
+		dependencies: Object.freeze(dependencies)
+	});
+}
+
+test('canonical operation instances deduplicate aliases and maintain complete membership/order', () => {
+	const baseA = record(Todo, 'a', {
+		id: 'a',
+		active: true,
+		rank: 2,
+		tenantId: 'tenant-1'
+	});
+	const rootAlias = Object.freeze({
+		...todoArtifact().roots[0],
+		responseKey: 'sameTodos'
+	});
+	const registry = createReplicaIndexMaintenanceRegistry();
+	registry.registerOperation(
+		todoArtifact({ extraRoots: [rootAlias] }),
+		{ owner: 1 }
+	);
+	const rootIndex = index('todos', [baseA.key], {
+		arguments: { owner: '1' }
+	});
+	const insertB = upsert(Todo, 'b', {
+		id: 'b',
+		active: true,
+		rank: 1,
+		tenantId: 'tenant-1'
+	});
+
+	let decisions = registry.evaluate(
+		snapshot([baseA], [rootIndex]),
+		[layer('insert-b', [insertB])]
+	);
+	assert.deepEqual(decisions, [
+		{
+			kind: 'write',
+			indexKey: rootIndex.key,
+			records: [insertB.key, baseA.key],
+			complete: true
+		}
+	]);
+
+	decisions = registry.evaluate(
+		snapshot([baseA], [rootIndex]),
+		[
+			layer('close-a', [
+				upsert(Todo, 'a', {
+					active: false
+				})
+			])
+		]
+	);
+	assert.deepEqual(decisions[0], {
+		kind: 'write',
+		indexKey: rootIndex.key,
+		records: [],
+		complete: true
+	});
+});
+
+test('maintenance registration rejects an unbound or mismatched operation artifact', () => {
+	const registry = createReplicaIndexMaintenanceRegistry();
+	const artifact = todoArtifact();
+	assert.throws(
+		() =>
+			registry.registerOperation(
+				Object.freeze({
+					...artifact,
+					protocol: Object.freeze({
+						...artifact.protocol,
+						operation: 'OtherOperation'
+					})
+				}),
+				{ owner: 'tenant-1' }
+			),
+		/replica artifact protocol binding is invalid/
+	);
+});
+
+test('semantic layers recompute from confirmed state when an earlier layer disappears', () => {
+	const base = record(Todo, 'base', {
+		id: 'base',
+		active: true,
+		rank: 1,
+		tenantId: 'tenant-1'
+	});
+	const registry = createReplicaIndexMaintenanceRegistry();
+	registry.registerOperation(todoArtifact(), { owner: 'owner-1' });
+	const root = index('todos', [base.key], {
+		arguments: { owner: 'owner-1' }
+	});
+	const insertA = upsert(Todo, 'a', {
+		id: 'a',
+		active: true,
+		rank: 2,
+		tenantId: 'tenant-1'
+	});
+	const insertB = upsert(Todo, 'b', {
+		id: 'b',
+		active: true,
+		rank: 3,
+		tenantId: 'tenant-1'
+	});
+
+	assert.deepEqual(
+		registry.evaluate(snapshot([base], [root]), [
+			layer('A', [insertA]),
+			layer('B', [insertB])
+		])[0].records,
+		[base.key, insertA.key, insertB.key]
+	);
+	assert.deepEqual(
+		registry.evaluate(snapshot([base], [root]), [layer('B', [insertB])])[0]
+			.records,
+		[base.key, insertB.key]
+	);
+});
+
+test('a stale complete index keeps a later patch ordered during rebase', () => {
+	const earlier = record(Todo, 'earlier', {
+		id: 'earlier',
+		active: true,
+		rank: 1,
+		tenantId: 'tenant-1'
+	});
+	const target = record(Todo, 'target', {
+		id: 'target',
+		active: true,
+		rank: 2,
+		tenantId: 'tenant-1'
+	});
+	const registry = createReplicaIndexMaintenanceRegistry();
+	registry.registerOperation(todoArtifact(), { owner: 'owner-1' });
+	const root = index('todos', [earlier.key, target.key], {
+		arguments: { owner: 'owner-1' },
+		staleReason: 'command-authoritative-revalidation'
+	});
+
+	const decisions = registry.evaluate(snapshot([earlier, target], [root]), [
+		layer('later-rank-change', [
+			upsert(Todo, 'target', {
+				rank: 0
+			})
+		])
+	]);
+
+	assert.deepEqual(decisions[0], {
+		kind: 'write',
+		indexKey: root.key,
+		records: [target.key, earlier.key],
+		complete: true
+	});
+});
+
+test('one record change updates every distinct exact root index once', () => {
+	const registry = createReplicaIndexMaintenanceRegistry();
+	const openArtifact = todoArtifact({
+		id: 'OpenTodos',
+		arguments: Object.freeze({
+			owner: variable('owner'),
+			state: literal('open')
+		})
+	});
+	const allArtifact = todoArtifact({
+		id: 'AllTodos',
+		arguments: Object.freeze({
+			owner: variable('owner'),
+			state: literal('all')
+		}),
+		where: unrestrictedFilter(literal({}))
+	});
+	registry.registerOperation(openArtifact, { owner: 'one' });
+	registry.registerOperation(allArtifact, { owner: 'one' });
+	const open = index('todos', [], {
+		arguments: { owner: 'one', state: 'open' }
+	});
+	const all = index('todos', [], {
+		arguments: { owner: 'one', state: 'all' }
+	});
+	const inserted = upsert(Todo, 'new', {
+		id: 'new',
+		active: true,
+		rank: 1,
+		tenantId: 'tenant-1'
+	});
+	const decisions = registry.evaluate(
+		snapshot([], [open, all]),
+		[layer('insert', [inserted])]
+	);
+	assert.equal(decisions.length, 2);
+	assert.deepEqual(
+		decisions.map(({ indexKey }) => indexKey).sort(),
+		[all.key, open.key].sort()
+	);
+	assert.ok(decisions.every(({ records }) => records[0] === inserted.key));
+});
+
+test('reorders are deterministic and duplicates fail closed', () => {
+	const a = record(Todo, 'a', {
+		id: 'a',
+		active: true,
+		rank: 1,
+		tenantId: 'tenant-1'
+	});
+	const b = record(Todo, 'b', {
+		id: 'b',
+		active: true,
+		rank: 2,
+		tenantId: 'tenant-1'
+	});
+	const registry = createReplicaIndexMaintenanceRegistry();
+	registry.registerOperation(todoArtifact(), { owner: 'one' });
+	const root = index('todos', [a.key, b.key], {
+		arguments: { owner: 'one' }
+	});
+	const reordered = registry.evaluate(
+		snapshot([a, b], [root]),
+		[layer('reorder', [upsert(Todo, 'a', { rank: 3 })])]
+	);
+	assert.deepEqual(reordered[0].records, [b.key, a.key]);
+
+	const duplicate = registry.evaluate(
+		snapshot(
+			[a, b],
+			[
+				Object.freeze({
+					...root,
+					records: Object.freeze([a.key, a.key])
+				})
+			]
+		),
+		[layer('touch', [upsert(Todo, 'a', { rank: 3 })])]
+	);
+	assert.equal(duplicate[0].kind, 'stale');
+	assert.equal(duplicate[0].reason.code, 'duplicate_index_record');
+});
+
+test('missing dependencies, claims, and offset windows become precise stale decisions', () => {
+	const registry = createReplicaIndexMaintenanceRegistry();
+	registry.registerOperation(todoArtifact(), { owner: 'one' });
+	const complete = index('todos', [], { arguments: { owner: 'one' } });
+	const missing = upsert(Todo, 'missing', {
+		id: 'missing',
+		rank: 1,
+		tenantId: 'tenant-1'
+	});
+	let decision = registry.evaluate(
+		snapshot([], [complete]),
+		[layer('missing', [missing])]
+	)[0];
+	assert.equal(decision.kind, 'stale');
+	assert.equal(decision.reason.code, 'missing_field');
+	assert.match(formatReplicaIndexStaleReason(decision.reason), /^query-plan:missing_field:/);
+
+	const claimPolicy = Object.freeze({
+		kind: 'predicate',
+		expression: Object.freeze({
+			kind: 'cmp',
+			value: Object.freeze({
+				column: 'rank',
+				op: 'eq',
+				rhs: Object.freeze({
+					kind: 'claim',
+					value: Object.freeze({ header: 'x-distributed-rank' })
+				})
+			})
+		})
+	});
+	const claimDescriptor = Object.freeze({
+		name: 'x-distributed-rank',
+		codec: 'int32'
+	});
+	const claimed = createReplicaIndexMaintenanceRegistry();
+	claimed.registerOperation(
+		todoArtifact({
+			id: 'ClaimedTodos',
+			rowPolicy: claimPolicy,
+			trustedPresets: Object.freeze([claimDescriptor])
+		}),
+		{ owner: 'one' }
+	);
+	decision = claimed.evaluate(
+		snapshot([], [complete]),
+		[
+			layer('claimed', [
+				upsert(Todo, 'claimed', {
+					id: 'claimed',
+					active: true,
+					rank: 1,
+					tenantId: 'tenant-1'
+				})
+			])
+		]
+	)[0];
+	assert.equal(decision.reason.code, 'claim_inventory');
+
+	const scopedRank = (value) =>
+		Object.freeze([
+			Object.freeze({
+				...claimDescriptor,
+				value
+			})
+		]);
+	decision = claimed.evaluate(
+		snapshot([], [complete]),
+		[
+			layer('claimed', [
+				upsert(Todo, 'claimed', {
+					id: 'claimed',
+					active: true,
+					rank: 1,
+					tenantId: 'tenant-1'
+				})
+			])
+		],
+		scopedRank(1)
+	)[0];
+	assert.deepEqual(decision, {
+		kind: 'write',
+		indexKey: complete.key,
+		records: [replicaRecordKey(Todo, 'claimed')],
+		complete: true
+	});
+
+	decision = claimed.evaluate(
+		snapshot([], [complete]),
+		[
+			layer('claimed', [
+				upsert(Todo, 'claimed', {
+					id: 'claimed',
+					active: true,
+					rank: 1,
+					tenantId: 'tenant-1'
+				})
+			])
+		],
+		scopedRank(2)
+	)[0];
+	assert.equal(decision.kind, 'unchanged');
+
+	decision = claimed.evaluate(
+		snapshot([], [complete]),
+		[
+			layer('claimed', [
+				upsert(Todo, 'claimed', {
+					id: 'claimed',
+					active: true,
+					rank: 1,
+					tenantId: 'tenant-1'
+				})
+			])
+		],
+		[
+			...scopedRank(1),
+			{ name: 'x-forged-extra', codec: 'string', value: 'forged' }
+		]
+	)[0];
+	assert.equal(decision.kind, 'stale');
+	assert.equal(decision.reason.code, 'claim_inventory');
+
+	const offsetRegistry = createReplicaIndexMaintenanceRegistry();
+	offsetRegistry.registerOperation(
+		todoArtifact({
+			id: 'OffsetTodos',
+			pagination: OFFSET_PAGINATION,
+			coverage: Object.freeze({
+				kind: 'offset',
+				offsetArgument: 'offset',
+				limitArgument: 'limit'
+			}),
+			arguments: Object.freeze({
+				owner: variable('owner'),
+				offset: literal(0),
+				limit: literal(10)
+			})
+		}),
+		{ owner: 'one' }
+	);
+	const offset = index('todos', [], {
+		arguments: { owner: 'one', offset: 0, limit: 10 },
+		coverage: { kind: 'offset', offset: 0, limit: 10, returned: 0 }
+	});
+	decision = offsetRegistry.evaluate(
+		snapshot([], [offset]),
+		[
+			layer('offset-insert', [
+				upsert(Todo, 'offset', {
+					id: 'offset',
+					active: true,
+					rank: 1,
+					tenantId: 'tenant-1'
+				})
+			])
+		]
+	)[0];
+	assert.deepEqual(decision, {
+		kind: 'write',
+		indexKey: offset.key,
+		records: [replicaRecordKey(Todo, 'offset')],
+		complete: true
+	});
+
+	const full = Object.freeze({
+		...offset,
+		records: Object.freeze(
+			Array.from({ length: 10 }, (_, item) => replicaRecordKey(Todo, `base-${item}`))
+		),
+		metadata: Object.freeze({
+			...offset.metadata,
+			coverage: Object.freeze({
+				kind: 'offset',
+				offset: 0,
+				limit: 10,
+				returned: 10
+			})
+		})
+	});
+	decision = offsetRegistry.evaluate(
+		snapshot(
+			Array.from({ length: 10 }, (_, item) =>
+				record(Todo, `base-${item}`, {
+					id: `base-${item}`,
+					active: true,
+					rank: item + 2,
+					tenantId: 'tenant-1'
+				})
+			),
+			[full]
+		),
+		[
+			layer('full-offset-insert', [
+				upsert(Todo, 'offset', {
+					id: 'offset',
+					active: true,
+					rank: 1,
+					tenantId: 'tenant-1'
+				})
+			])
+		]
+	)[0];
+	assert.equal(decision.kind, 'stale');
+	assert.equal(decision.reason.code, 'insert_changes_offset_window');
+
+	const first = record(Todo, 'first', {
+		id: 'first',
+		active: true,
+		rank: 1,
+		tenantId: 'tenant-1'
+	});
+	const boundary = record(Todo, 'boundary', {
+		id: 'boundary',
+		active: true,
+		rank: 2,
+		tenantId: 'tenant-1'
+	});
+	const fullBoundary = index('todos', [first.key, boundary.key], {
+		arguments: { owner: 'one', offset: 0, limit: 10 },
+		coverage: { kind: 'offset', offset: 0, limit: 10, returned: 2 }
+	});
+	const forgedCoverage = (coverage) =>
+		Object.freeze({
+			...fullBoundary,
+			metadata: Object.freeze({
+				...fullBoundary.metadata,
+				coverage: Object.freeze(coverage)
+			})
+		});
+	for (const coverage of [
+		{ kind: 'offset', offset: 1, limit: 10, returned: 2 },
+		{ kind: 'offset', offset: 0, limit: 10, returned: 1 },
+		{ kind: 'offset', offset: 0, limit: 10, returned: 2, hasNext: true }
+	]) {
+		decision = offsetRegistry.evaluate(
+			snapshot([first, boundary], [forgedCoverage(coverage)]),
+			[
+				layer('coverage-mismatch', [
+					upsert(Todo, 'third', {
+						id: 'third',
+						active: true,
+						rank: 3,
+						tenantId: 'tenant-1'
+					})
+				])
+			]
+		)[0];
+		assert.equal(decision.kind, 'stale');
+		assert.equal(decision.reason.code, 'invalid_index_metadata');
+	}
+});
+
+test('stacked local offset inserts preserve the exact first-page limit', () => {
+	const registry = createReplicaIndexMaintenanceRegistry();
+	registry.registerOperation(
+		todoArtifact({
+			id: 'SafeOffsetTodos',
+			pagination: OFFSET_PAGINATION,
+			coverage: Object.freeze({
+				kind: 'offset',
+				offsetArgument: 'offset',
+				limitArgument: 'limit'
+			}),
+			arguments: Object.freeze({
+				owner: variable('owner'),
+				offset: literal(0),
+				limit: literal(2)
+			})
+		}),
+		{ owner: 'one' }
+	);
+	const base = record(Todo, 'base', {
+		id: 'base',
+		active: true,
+		rank: 3,
+		tenantId: 'tenant-1'
+	});
+	const root = index('todos', [base.key], {
+		arguments: { owner: 'one', offset: 0, limit: 2 },
+		coverage: { kind: 'offset', offset: 0, limit: 2, returned: 1 }
+	});
+	const first = upsert(Todo, 'first', {
+		id: 'first',
+		active: true,
+		rank: 1,
+		tenantId: 'tenant-1'
+	});
+	const second = upsert(Todo, 'second', {
+		id: 'second',
+		active: true,
+		rank: 2,
+		tenantId: 'tenant-1'
+	});
+	const decision = registry.evaluate(
+		snapshot([base], [root]),
+		[layer('first', [first]), layer('second', [second])]
+	)[0];
+	assert.deepEqual(decision.records, [first.key, second.key]);
+
+	assert.deepEqual(
+		registry.evaluate(
+			snapshot([base], [root]),
+			[layer('second', [second])]
+		)[0].records,
+		[second.key, base.key]
+	);
+	assert.deepEqual(
+		registry.evaluate(
+			snapshot([base], [root]),
+			[layer('first', [first])]
+		)[0].records,
+		[first.key, base.key]
+	);
+});
+
+test('offset order changes use net tuples and full windows fail closed at unseen boundaries', () => {
+	const registry = createReplicaIndexMaintenanceRegistry();
+	registry.registerOperation(
+		todoArtifact({
+			id: 'OffsetOrderTodos',
+			pagination: OFFSET_PAGINATION,
+			coverage: Object.freeze({
+				kind: 'offset',
+				offsetArgument: 'offset',
+				limitArgument: 'limit'
+			}),
+			arguments: Object.freeze({
+				owner: variable('owner'),
+				offset: literal(0),
+				limit: literal(2)
+			})
+		}),
+		{ owner: 'one' }
+	);
+	const a = record(Todo, 'a', {
+		id: 'a',
+		active: true,
+		rank: 1,
+		tenantId: 'tenant-1'
+	});
+	const b = record(Todo, 'b', {
+		id: 'b',
+		active: true,
+		rank: 2,
+		tenantId: 'tenant-1'
+	});
+	const full = index('todos', [a.key, b.key], {
+		arguments: { owner: 'one', offset: 0, limit: 2 },
+		coverage: { kind: 'offset', offset: 0, limit: 2, returned: 2 }
+	});
+
+	let decision = registry.evaluate(
+		snapshot([a, b], [full]),
+		[layer('boundary', [upsert(Todo, 'b', { rank: 100 })])]
+	)[0];
+	assert.equal(decision.kind, 'stale');
+	assert.equal(decision.reason.code, 'reorder_changes_offset_window');
+
+	decision = registry.evaluate(
+		snapshot([a, b], [full]),
+		[
+			layer('away', [upsert(Todo, 'b', { rank: 100 })]),
+			layer('restore', [upsert(Todo, 'b', { rank: 2 })])
+		]
+	)[0];
+	assert.equal(decision.kind, 'unchanged');
+
+	const nonFull = Object.freeze({
+		...full,
+		metadata: Object.freeze({
+			...full.metadata,
+			coverage: Object.freeze({
+				kind: 'offset',
+				offset: 0,
+				limit: 3,
+				returned: 2
+			}),
+			arguments: Object.freeze({ owner: 'one', offset: 0, limit: 3 })
+		}),
+		key: replicaIndexKey({
+			field: 'todos',
+			arguments: { owner: 'one', offset: 0, limit: 3 }
+		})
+	});
+	const nonFullRegistry = createReplicaIndexMaintenanceRegistry();
+	nonFullRegistry.registerOperation(
+		todoArtifact({
+			id: 'NonFullOffsetOrderTodos',
+			pagination: OFFSET_PAGINATION,
+			coverage: Object.freeze({
+				kind: 'offset',
+				offsetArgument: 'offset',
+				limitArgument: 'limit'
+			}),
+			arguments: Object.freeze({
+				owner: variable('owner'),
+				offset: literal(0),
+				limit: literal(3)
+			})
+		}),
+		{ owner: 'one' }
+	);
+	decision = nonFullRegistry.evaluate(
+		snapshot([a, b], [nonFull]),
+		[layer('local-reorder', [upsert(Todo, 'a', { rank: 3 })])]
+	)[0];
+	assert.deepEqual(decision.records, [b.key, a.key]);
+
+	decision = nonFullRegistry.evaluate(
+		snapshot([a, b], [nonFull]),
+		[layer('local-delete', [Object.freeze({
+			kind: 'delete',
+			model: Todo.id,
+			key: a.key
+		})])]
+	)[0];
+	assert.deepEqual(decision.records, [b.key]);
+});
+
+test('cursor windows remain stale at integration boundaries without compiler proof IR', () => {
+	const registry = createReplicaIndexMaintenanceRegistry();
+	registry.registerOperation(
+		todoArtifact({
+			id: 'CursorTodos',
+			pagination: Object.freeze({
+				kind: 'cursor',
+				// Neither a forged flag nor local dispositions constitute a
+				// versioned compiler proof understood by this runtime.
+				certified: true,
+				insert: 'local',
+				delete: 'local',
+				reorder: 'local',
+				stableUpdate: 'local'
+			}),
+			coverage: Object.freeze({
+				kind: 'cursor',
+				afterArgument: 'after',
+				firstArgument: 'first'
+			}),
+			arguments: Object.freeze({
+				owner: variable('owner'),
+				after: literal('cursor-a'),
+				first: literal(10)
+			})
+		}),
+		{ owner: 'one' }
+	);
+	const window = index('todos', [], {
+		arguments: { owner: 'one', after: 'cursor-a', first: 10 },
+		coverage: {
+			kind: 'cursor',
+			after: 'cursor-a',
+			first: 10,
+			start: 'cursor-b',
+			end: 'cursor-z',
+			hasNext: true
+		}
+	});
+	const decision = registry.evaluate(
+		snapshot([], [window]),
+		[
+			layer('cursor-boundary-insert', [
+				upsert(Todo, 'cursor-c', {
+					id: 'cursor-c',
+					active: true,
+					rank: 3,
+					tenantId: 'tenant-1'
+				})
+			])
+		]
+	)[0];
+	assert.equal(decision.kind, 'stale');
+	assert.equal(decision.reason.code, 'cursor_not_certified');
+});
+
+function relationshipArtifact(
+	relationship,
+	{
+		id = 'BoardCards',
+		filter = unrestrictedFilter(),
+		order = ORDER
+	} = {}
+) {
+	const selection = Object.freeze({
+		typename: Board.id,
+		storage: Object.freeze({
+			kind: 'normalized',
+			model: Board.id,
+			identityFields: Board.identityFields
+		}),
+		members: Object.freeze([
+			scalar('id', 'id'),
+			Object.freeze({
+				kind: 'branch',
+				semantic: 'relationship',
+				responseKey: 'cards',
+				field: 'cards',
+				cardinality: 'many',
+				nullable: false,
+				dependencies: relationship.dependencies,
+				coverage: COMPLETE,
+				filter,
+				order,
+				pagination: COMPLETE_PAGINATION,
+				relationship,
+				selection: Object.freeze({
+					typename: Card.id,
+					storage: Object.freeze({
+						kind: 'normalized',
+						model: Card.id,
+						identityFields: Card.identityFields
+					}),
+					members: TODO_SELECTION.members
+				})
+			})
+		])
+	});
+	return Object.freeze({
+		id,
+		document: `query ${id} { board { cards { id } } }`,
+		protocol: Object.freeze({
+			version: 1,
+			schemaHash: `sha256:${'1'.repeat(64)}`,
+			surface: Object.freeze({ kind: 'role', name: 'user' }),
+			operation: id,
+			trustedPresets: Object.freeze([])
+		}),
+		variableCodec: NO_VARIABLES,
+		roots: Object.freeze([
+			Object.freeze({
+				responseKey: 'board',
+				field: 'board_by_pk',
+				cardinality: 'one',
+				nullable: false,
+				dependencies: Object.freeze(['boards']),
+				selection
+			})
+		])
+	});
+}
+
+const M2M = Object.freeze({
+	field: 'cards',
+	targetModel: 'Card',
+	kind: 'many_to_many',
+	keyMapping: Object.freeze({
+		kind: 'through',
+		local: Object.freeze(['id']),
+		remote: Object.freeze(['id']),
+		table: 'board_cards',
+		sourceForeignKey: 'board_id',
+		targetForeignKey: 'card_id'
+	}),
+	maintenance: 'local',
+	dependencies: Object.freeze(['board_cards', 'boards', 'cards'])
+});
+
+test('many-to-many link/unlink recomputes semantically and requires join dependencies', () => {
+	const board = record(Board, 'board-1', { id: 'board-1' });
+	const first = record(Card, 'card-1', {
+		id: 'card-1',
+		active: true,
+		rank: 1,
+		tenantId: 'tenant-1'
+	});
+	const second = record(Card, 'card-2', {
+		id: 'card-2',
+		active: true,
+		rank: 2,
+		tenantId: 'tenant-1'
+	});
+	const cards = index('cards', [first.key], {
+		parent: board.key,
+		dependencies: M2M.dependencies
+	});
+	const registry = createReplicaIndexMaintenanceRegistry();
+	registry.registerOperation(relationshipArtifact(M2M), {});
+	const link = Object.freeze({
+		kind: 'link',
+		sourceModel: 'Board',
+		field: 'cards',
+		targetModel: 'Card',
+		sourceKey: board.key,
+		targetKey: second.key,
+		dependencies: M2M.dependencies
+	});
+	let decision = registry.evaluate(
+		snapshot([board, first, second], [cards]),
+		[layer('link', [link])]
+	)[0];
+	assert.deepEqual(decision.records, [first.key, second.key]);
+
+	decision = registry.evaluate(
+		snapshot([board, first, second], [cards]),
+		[
+			layer('unlink', [
+				Object.freeze({ ...link, kind: 'unlink', targetKey: first.key })
+			])
+		]
+	)[0];
+	assert.deepEqual(decision.records, []);
+
+	decision = registry.evaluate(
+		snapshot([board, first, second], [cards]),
+		[
+			layer('unsafe-link', [
+				Object.freeze({
+					...link,
+					dependencies: Object.freeze(['boards', 'cards'])
+				})
+			])
+		]
+	)[0];
+	assert.equal(decision.kind, 'stale');
+	assert.equal(decision.reason.code, 'relationship_dependency_missing');
+});
+
+test('relationship target changes and opaque mappings fail closed without explicit proof', () => {
+	const board = record(Board, 'board-1', { id: 'board-1' });
+	const cards = index('cards', [], {
+		parent: board.key,
+		dependencies: M2M.dependencies
+	});
+	const registry = createReplicaIndexMaintenanceRegistry();
+	registry.registerOperation(relationshipArtifact(M2M), {});
+	let decision = registry.evaluate(
+		snapshot([board], [cards]),
+		[
+			layer('unproven-target', [
+				upsert(
+					Card,
+					'card-1',
+					{
+						id: 'card-1',
+						active: true,
+						rank: 1,
+						tenantId: 'tenant-1'
+					},
+					['cards']
+				)
+			])
+		]
+	)[0];
+	assert.equal(decision.reason.code, 'relationship_mapping_unknown');
+
+	const opaque = Object.freeze({
+		...M2M,
+		keyMapping: Object.freeze({
+			kind: 'through_opaque',
+			local: Object.freeze(['id']),
+			remote: Object.freeze(['id']),
+			dependency: 'private_membership'
+		}),
+		maintenance: 'revalidate',
+		dependencies: Object.freeze([
+			'private_membership',
+			'boards',
+			'cards'
+		])
+	});
+	const opaqueRegistry = createReplicaIndexMaintenanceRegistry();
+	opaqueRegistry.registerOperation(
+		relationshipArtifact(opaque, { id: 'OpaqueCards' }),
+		{}
+	);
+	const opaqueCards = index('cards', [], {
+		parent: board.key,
+		dependencies: opaque.dependencies
+	});
+	decision = opaqueRegistry.evaluate(
+		snapshot([board], [opaqueCards]),
+		[
+			layer('opaque-link', [
+				Object.freeze({
+					kind: 'link',
+					sourceModel: 'Board',
+					field: 'cards',
+					targetModel: 'Card',
+					sourceKey: board.key,
+					targetKey: replicaRecordKey(Card, 'card-1'),
+					dependencies: opaque.dependencies
+				})
+			])
+		]
+	)[0];
+	assert.equal(decision.reason.code, 'relationship_maintenance_revalidate');
+});
+
+test('aggregate snapshots invalidate from declared dependencies and registry clear fences scope changes', () => {
+	const aggregateArtifact = Object.freeze({
+		id: 'TodoAggregate',
+		document: 'query TodoAggregate { todos_aggregate { aggregate { count } } }',
+		protocol: Object.freeze({
+			version: 1,
+			schemaHash: `sha256:${'1'.repeat(64)}`,
+			surface: Object.freeze({ kind: 'role', name: 'user' }),
+			operation: 'TodoAggregate',
+			trustedPresets: Object.freeze([])
+		}),
+		variableCodec: NO_VARIABLES,
+		roots: Object.freeze([
+			Object.freeze({
+				responseKey: 'todos_aggregate',
+				field: 'todos_aggregate',
+				cardinality: 'one',
+				nullable: false,
+				dependencies: Object.freeze(['todos']),
+				selection: Object.freeze({
+					typename: 'todo_aggregate',
+					storage: Object.freeze({ kind: 'embedded' }),
+					members: Object.freeze([])
+				})
+			})
+		])
+	});
+	const aggregate = index('todos_aggregate', ['embedded:aggregate'], {
+		dependencies: ['todos']
+	});
+	const registry = createReplicaIndexMaintenanceRegistry();
+	registry.registerOperation(aggregateArtifact, {});
+	let decisions = registry.evaluate(
+		snapshot([], [aggregate]),
+		[
+			layer('invalidate', [
+				Object.freeze({
+					kind: 'invalidate',
+					dependencies: Object.freeze(['todos'])
+				})
+			])
+		]
+	);
+	assert.equal(decisions[0].kind, 'stale');
+	assert.equal(decisions[0].reason.code, 'aggregate_dependency_changed');
+
+	registry.clear();
+	decisions = registry.evaluate(
+		snapshot([], [aggregate]),
+		[
+			layer('old-scope', [
+				Object.freeze({
+					kind: 'invalidate',
+					dependencies: Object.freeze(['todos'])
+				})
+			])
+		]
+	);
+	assert.deepEqual(decisions, []);
+});
diff --git a/js/tests/replica-pagination-identity.test.mjs b/js/tests/replica-pagination-identity.test.mjs
new file mode 100644
index 00000000..098d9c9b
--- /dev/null
+++ b/js/tests/replica-pagination-identity.test.mjs
@@ -0,0 +1,81 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	coverageFromArtifact,
+	replicaIndexKey,
+	resolveArguments
+} from '../dist/replica/identity.js';
+
+const OFFSET_COVERAGE = Object.freeze({
+	kind: 'offset',
+	limitArgument: 'limit',
+	offsetArgument: 'offset',
+	defaultLimit: 25,
+	maxLimit: 100
+});
+
+const PAGINATION_ARGUMENTS = Object.freeze({
+	limit: Object.freeze({ kind: 'variable', name: 'limit' }),
+	offset: Object.freeze({ kind: 'variable', name: 'offset' })
+});
+
+function indexKey(variables) {
+	return replicaIndexKey({
+		field: 'todos',
+		arguments: resolveArguments(
+			PAGINATION_ARGUMENTS,
+			variables,
+			OFFSET_COVERAGE
+		)
+	});
+}
+
+test('offset index identity uses the exact effective server window', () => {
+	const defaultWindow = { limit: 25, offset: 0 };
+	for (const variables of [
+		{},
+		{ limit: null, offset: null },
+		{ limit: -1, offset: -1 },
+		{ limit: 25, offset: 0 }
+	]) {
+		assert.deepEqual(
+			resolveArguments(PAGINATION_ARGUMENTS, variables, OFFSET_COVERAGE),
+			defaultWindow
+		);
+		assert.equal(indexKey(variables), indexKey({ limit: 25, offset: 0 }));
+	}
+
+	assert.deepEqual(resolveArguments(undefined, {}, OFFSET_COVERAGE), defaultWindow);
+	assert.equal(indexKey({ limit: 1_000, offset: 4 }), indexKey({ limit: 100, offset: 4 }));
+});
+
+test('offset coverage accepts every pagination value accepted by the server', () => {
+	for (const argumentsValue of [
+		{},
+		{ limit: null, offset: null },
+		{ limit: -1, offset: -1 },
+		{ limit: 25, offset: 0 }
+	]) {
+		assert.deepEqual(coverageFromArtifact(OFFSET_COVERAGE, argumentsValue, 3), {
+			kind: 'offset',
+			offset: 0,
+			limit: 25,
+			returned: 3
+		});
+	}
+
+	assert.deepEqual(
+		coverageFromArtifact(OFFSET_COVERAGE, { limit: 1_000, offset: 4 }, 3),
+		{
+			kind: 'offset',
+			offset: 4,
+			limit: 100,
+			returned: 3
+		}
+	);
+	assert.throws(
+		() => coverageFromArtifact(OFFSET_COVERAGE, { limit: '25' }, 0),
+		/pagination argument limit must be an integer or null/
+	);
+});
diff --git a/js/tests/replica-persistence.test.mjs b/js/tests/replica-persistence.test.mjs
new file mode 100644
index 00000000..b6f84470
--- /dev/null
+++ b/js/tests/replica-persistence.test.mjs
@@ -0,0 +1,658 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	createReplicaIndexedDbPersistence,
+	REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED
+} from '../dist/replica/persistence.js';
+import {
+	createDistributedReplica,
+	replicaIndexKey,
+	replicaRecordKey
+} from '../dist/replica/index.js';
+import { replicaCommandAuthority } from '../dist/replica/command-runtime.js';
+
+const DATABASE = 'replica-persistence-test';
+const Todo = Object.freeze({
+	id: 'TodoView',
+	identityFields: Object.freeze(['id'])
+});
+const Secret = Object.freeze({
+	id: 'SecretView',
+	identityFields: Object.freeze(['id'])
+});
+
+const TodoKey = replicaRecordKey(Todo, 'todo-1');
+const SecretKey = replicaRecordKey(Secret, 'secret-1');
+const TodoIndex = replicaIndexKey({ field: 'todos' });
+const SecretIndex = replicaIndexKey({ field: 'secrets' });
+const MixedIndex = replicaIndexKey({ field: 'mixed' });
+const EmptyIndex = replicaIndexKey({ field: 'emptyTodos' });
+
+const TodoPolicy = Object.freeze({
+	models: Object.freeze({
+		TodoView: Object.freeze({
+			retention: 'persist-confirmed',
+			sensitive: false
+		}),
+		SecretView: Object.freeze({
+			retention: 'persist-confirmed',
+			sensitive: true
+		})
+	})
+});
+
+function scope(cacheScope = 'cache:tenant-a', schemaHash = 'schema:a') {
+	return {
+		protocolVersion: 1,
+		schemaHash,
+		cacheScope
+	};
+}
+
+function field(revision, value) {
+	return { revision, value };
+}
+
+function record(key, revision, fields, links = {}) {
+	return {
+		key,
+		revision,
+		incarnation: '1',
+		fields,
+		links
+	};
+}
+
+function index(key, fieldName, revision, records) {
+	return {
+		key,
+		revision,
+		records,
+		complete: true,
+		deleted: false,
+		metadata: {
+			field: fieldName,
+			arguments: {},
+			coverage: { kind: 'complete' },
+			dependencies: [fieldName]
+		}
+	};
+}
+
+function protocolState(operation, fieldName, revision, indexKey, pathRecord) {
+	return {
+		operation,
+		snapshotScope: `snapshot:${operation}`,
+		indexClocks: [
+			[
+				`${fieldName}-projector`,
+				{
+					scopeToken: `index:${operation}`,
+					position: revision
+				}
+			]
+		],
+		indexRevision: revision,
+		indexKeys: [indexKey],
+		pathRecords:
+			pathRecord === undefined ? [] : [[`${fieldName}.0`, pathRecord]],
+		cursors: []
+	};
+}
+
+function operation(key, state) {
+	return {
+		key: `protocol:${key}`,
+		query: state,
+		active: 'query',
+		generation: 0
+	};
+}
+
+function clock(scopeToken, revision = '1', tombstone = false) {
+	return {
+		scopeToken,
+		incarnation: '1',
+		revision,
+		tombstone
+	};
+}
+
+function state(authoritativeScope = scope()) {
+	return {
+		version: 1,
+		scope: authoritativeScope,
+		payload: {
+			cache: {
+				version: 1,
+				records: [
+					record(
+						TodoKey,
+						'1',
+						{
+							id: field('1', 'todo-1'),
+							title: field('1', 'visible')
+						},
+						{
+							self: field('1', TodoKey),
+							secret: field('1', SecretKey)
+						}
+					),
+					record(SecretKey, '1', {
+						id: field('1', 'secret-1'),
+						value: field('1', 'must stay memory-only')
+					})
+				],
+				indexes: [
+					index(TodoIndex, 'todos', '1', [TodoKey]),
+					index(SecretIndex, 'secrets', '2', [SecretKey]),
+					index(MixedIndex, 'mixed', '3', [TodoKey, SecretKey]),
+					index(EmptyIndex, 'emptyTodos', '4', [])
+				]
+			},
+			operations: [
+				operation(
+					'todos',
+					protocolState('query:todos', 'todos', '1', TodoIndex, TodoKey)
+				),
+				operation(
+					'secrets',
+					protocolState(
+						'query:secrets',
+						'secrets',
+						'2',
+						SecretIndex,
+						SecretKey
+					)
+				),
+				operation(
+					'mixed',
+					protocolState('query:mixed', 'mixed', '3', MixedIndex, TodoKey)
+				),
+				operation(
+					'empty',
+					protocolState('query:empty', 'emptyTodos', '4', EmptyIndex)
+				)
+			],
+			recordClocks: [
+				[TodoKey, clock('record:todo')],
+				[SecretKey, clock('record:secret')]
+			],
+			anonymousRecordClocks: [
+				[
+					'record:anonymous:todo',
+					{
+						model: 'TodoView',
+						clock: clock('record:anonymous:todo')
+					}
+				],
+				[
+					'record:anonymous:secret',
+					{
+						model: 'SecretView',
+						clock: clock('record:anonymous:secret')
+					}
+				]
+			],
+			trustedPresets: [
+					{
+						name: 'current_user_id',
+						codec: 'string',
+						value: 'user-1'
+					}
+				],
+			nextIndexRevision: '4'
+		}
+	};
+}
+
+test('persistence is explicit, IndexedDB-only, and fails closed without model policy', async () => {
+	const factory = new FakeIndexedDbFactory();
+	const persistence = createReplicaIndexedDbPersistence({
+		indexedDB: factory,
+		databaseName: DATABASE
+	});
+
+	assert.equal(REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED, false);
+	assert.equal(persistence.supportsOfflineCommandOutbox, false);
+	assert.equal(await persistence.save(state()), false);
+	assert.equal(factory.entries(DATABASE).size, 0);
+	assert.equal('localStorage' in factory, false);
+	persistence.close();
+});
+
+test('confirmed state is policy-filtered before a second instance restores it', async () => {
+	const factory = new FakeIndexedDbFactory();
+	const first = createReplicaIndexedDbPersistence({
+		indexedDB: factory,
+		databaseName: DATABASE,
+		policy: TodoPolicy
+	});
+	assert.equal(await first.save(state()), true);
+
+	const [stored] = [...factory.entries(DATABASE).values()];
+	assert.deepEqual(
+		stored.state.payload.cache.records.map((entry) => entry.key),
+		[TodoKey]
+	);
+	assert.deepEqual(
+		Object.keys(stored.state.payload.cache.records[0].links),
+		['self']
+	);
+	assert.deepEqual(
+		stored.state.payload.cache.indexes.map((entry) => entry.key),
+		[TodoIndex]
+	);
+	assert.deepEqual(
+		stored.state.payload.operations.map((entry) => entry.key),
+		['protocol:todos']
+	);
+	assert.deepEqual(
+		stored.state.payload.recordClocks.map(([key]) => key),
+		[TodoKey]
+	);
+	assert.deepEqual(
+		stored.state.payload.anonymousRecordClocks.map(([, entry]) => entry.model),
+		['TodoView']
+	);
+	assert.deepEqual(
+		stored.state.payload.trustedPresets,
+		state().payload.trustedPresets
+	);
+
+	const second = createReplicaIndexedDbPersistence({
+		indexedDB: factory,
+		databaseName: DATABASE,
+		policy: TodoPolicy
+	});
+	const restored = await second.restore(scope());
+	assert.deepEqual(restored, stored.state);
+	assert.equal(Object.isFrozen(restored), true);
+	assert.equal(Object.isFrozen(restored.payload), true);
+	assert.equal(
+		createDistributedReplica().hydrate(restored, scope()),
+		true,
+		JSON.stringify(restored, null, 2)
+	);
+
+	// Looking under a caller-supplied or decoded scope cannot find the entry.
+	assert.equal(await second.restore(scope('cache:tenant-b')), undefined);
+	assert.equal(factory.entries(DATABASE).size, 1);
+	first.close();
+	second.close();
+});
+
+test('restored trusted presets satisfy the generated command authority contract', async () => {
+	const factory = new FakeIndexedDbFactory();
+	const schemaHash = `sha256:${'a'.repeat(64)}`;
+	const authoritativeScope = scope('cache:tenant-a', schemaHash);
+	const persistence = createReplicaIndexedDbPersistence({
+		indexedDB: factory,
+		databaseName: DATABASE,
+		policy: TodoPolicy
+	});
+	assert.equal(await persistence.save(state(authoritativeScope)), true);
+	const restored = await persistence.restore(authoritativeScope);
+	const replica = createDistributedReplica();
+
+	assert.equal(replica.hydrate(restored, authoritativeScope), true);
+	const registration = replica[replicaCommandAuthority]({
+		protocolVersion: 1,
+		schemaHash,
+		protocolHash: `sha256:${'b'.repeat(64)}`,
+		surface: { kind: 'role', name: 'user' },
+		trustedPresets: [
+			{ name: 'current_user_id', codec: 'string' }
+		]
+	});
+	assert.deepEqual(registration.read().trustedPresets, [
+		{ name: 'current_user_id', codec: 'string', value: 'user-1' }
+	]);
+	registration.dispose();
+	persistence.close();
+});
+
+test('empty and mixed-policy indexes are conservatively dropped', async () => {
+	const factory = new FakeIndexedDbFactory();
+	const persistence = createReplicaIndexedDbPersistence({
+		indexedDB: factory,
+		databaseName: DATABASE,
+		policy: TodoPolicy
+	});
+	await persistence.save(state());
+	const restored = await persistence.restore(scope());
+
+	assert.deepEqual(
+		restored.payload.cache.indexes.map((entry) => entry.key),
+		[TodoIndex]
+	);
+	assert.equal(
+		restored.payload.operations.some(
+			(entry) =>
+				entry.key === 'protocol:mixed' || entry.key === 'protocol:empty'
+		),
+		false
+	);
+	persistence.close();
+});
+
+test('a stricter current policy rewrites and removes previously durable data', async () => {
+	const factory = new FakeIndexedDbFactory();
+	const permissive = createReplicaIndexedDbPersistence({
+		indexedDB: factory,
+		databaseName: DATABASE,
+		policy: {
+			models: {
+				TodoView: {
+					retention: 'persist-confirmed',
+					sensitive: false
+				},
+				SecretView: {
+					retention: 'persist-confirmed',
+					sensitive: false
+				}
+			}
+		}
+	});
+	await permissive.save(state());
+	assert.deepEqual(
+		[...factory.entries(DATABASE).values()][0].state.payload.cache.records.map(
+			(entry) => entry.key
+		),
+		[SecretKey, TodoKey]
+	);
+
+	const restricted = createReplicaIndexedDbPersistence({
+		indexedDB: factory,
+		databaseName: DATABASE,
+		policy: TodoPolicy
+	});
+	await restricted.restore(scope());
+	assert.deepEqual(
+		[...factory.entries(DATABASE).values()][0].state.payload.cache.records.map(
+			(entry) => entry.key
+		),
+		[TodoKey]
+	);
+	assert.deepEqual(
+		[...factory.entries(DATABASE).values()][0].state.payload.trustedPresets,
+		state().payload.trustedPresets
+	);
+	permissive.close();
+	restricted.close();
+});
+
+test('confirmed tombstone fences survive persistence for an allowed model', async () => {
+	const factory = new FakeIndexedDbFactory();
+	const persistence = createReplicaIndexedDbPersistence({
+		indexedDB: factory,
+		databaseName: DATABASE,
+		policy: TodoPolicy
+	});
+	const deletedKey = replicaRecordKey(Todo, 'todo-deleted');
+	const input = state();
+	input.payload.cache.records.push({
+		key: deletedKey,
+		revision: '5',
+		incarnation: '1',
+		tombstoneRevision: '5',
+		fields: {},
+		links: {}
+	});
+	input.payload.recordClocks.push([
+		deletedKey,
+		clock('record:todo-deleted', '5', true)
+	]);
+
+	assert.equal(await persistence.save(input), true);
+	const restored = await persistence.restore(scope());
+	assert.deepEqual(
+		restored.payload.cache.records.find((entry) => entry.key === deletedKey),
+		{
+			key: deletedKey,
+			revision: '5',
+			incarnation: '1',
+			tombstoneRevision: '5',
+			fields: {},
+			links: {}
+		}
+	);
+	assert.equal(createDistributedReplica().hydrate(restored, scope()), true);
+	persistence.close();
+});
+
+test('corrupt, unsupported, and internally mismatched entries are discarded', async (t) => {
+	for (const [name, corruption] of [
+		[
+			'unsupported persistence version',
+			(entry) => {
+				entry.formatVersion = 2;
+			}
+		],
+		[
+			'unsupported dehydration version',
+			(entry) => {
+				entry.state.version = 99;
+			}
+		],
+		[
+			'misfiled authoritative scope',
+			(entry) => {
+				entry.state.scope.cacheScope = 'cache:other';
+			}
+		],
+		[
+			'malformed causal revision',
+			(entry) => {
+				entry.state.payload.cache.records[0].revision = 'not-a-decimal';
+			}
+		]
+	]) {
+		await t.test(name, async () => {
+			const factory = new FakeIndexedDbFactory();
+			const persistence = createReplicaIndexedDbPersistence({
+				indexedDB: factory,
+				databaseName: DATABASE,
+				policy: TodoPolicy
+			});
+			await persistence.save(state());
+			const [entry] = [...factory.entries(DATABASE).values()];
+			corruption(entry);
+
+			assert.equal(await persistence.restore(scope()), undefined);
+			assert.equal(factory.entries(DATABASE).size, 0);
+			persistence.close();
+		});
+	}
+});
+
+test('malformed or command-like dehydration fields never enter IndexedDB', async () => {
+	const factory = new FakeIndexedDbFactory();
+	const persistence = createReplicaIndexedDbPersistence({
+		indexedDB: factory,
+		databaseName: DATABASE,
+		policy: TodoPolicy
+	});
+	const malformed = state();
+	malformed.payload.optimisticLayers = [{ id: 'command-1' }];
+
+	await assert.rejects(
+		() => persistence.save(malformed),
+		/unknown field state\.payload\.optimisticLayers/
+	);
+	assert.equal(factory.entries(DATABASE).size, 0);
+	persistence.close();
+});
+
+test('scope identity includes schema and protocol fingerprint exactly', async () => {
+	const factory = new FakeIndexedDbFactory();
+	const persistence = createReplicaIndexedDbPersistence({
+		indexedDB: factory,
+		databaseName: DATABASE,
+		policy: TodoPolicy
+	});
+	await persistence.save(state(scope('cache:tenant-a', 'schema:a')));
+	await persistence.save(state(scope('cache:tenant-a', 'schema:b')));
+
+	assert.equal(factory.entries(DATABASE).size, 2);
+	assert.notEqual(
+		[...factory.entries(DATABASE).keys()][0],
+		[...factory.entries(DATABASE).keys()][1]
+	);
+	assert.equal(
+		(await persistence.restore(scope('cache:tenant-a', 'schema:a'))).scope
+			.schemaHash,
+		'schema:a'
+	);
+	assert.equal(
+		(await persistence.restore(scope('cache:tenant-a', 'schema:b'))).scope
+			.schemaHash,
+		'schema:b'
+	);
+	persistence.close();
+});
+
+test('sensitive and memory-only models cannot be made durable accidentally', async () => {
+	const factory = new FakeIndexedDbFactory();
+	const persistence = createReplicaIndexedDbPersistence({
+		indexedDB: factory,
+		databaseName: DATABASE,
+		policy: {
+			models: {
+				TodoView: {
+					retention: 'memory-only',
+					sensitive: false
+				},
+				SecretView: {
+					retention: 'persist-confirmed',
+					sensitive: true
+				}
+			}
+		}
+	});
+
+	assert.equal(await persistence.save(state()), false);
+	assert.equal(factory.entries(DATABASE).size, 0);
+	persistence.close();
+});
+
+class FakeIndexedDbFactory {
+	#databases = new Map();
+
+	open(name, version) {
+		const request = fakeRequest();
+		queueMicrotask(() => {
+			let database = this.#databases.get(name);
+			const upgrade = database === undefined;
+			if (upgrade) {
+				database = {
+					version,
+					stores: new Map()
+				};
+				this.#databases.set(name, database);
+			}
+			request.result = new FakeDatabase(database);
+			if (upgrade) request.onupgradeneeded?.({ target: request });
+			queueMicrotask(() => request.onsuccess?.({ target: request }));
+		});
+		return request;
+	}
+
+	entries(name) {
+		const database = this.#databases.get(name);
+		if (database === undefined) return new Map();
+		return database.stores.get('confirmed-replicas') ?? new Map();
+	}
+}
+
+class FakeDatabase {
+	constructor(state) {
+		this.state = state;
+		this.objectStoreNames = {
+			contains: (name) => this.state.stores.has(name)
+		};
+	}
+
+	createObjectStore(name) {
+		const entries = new Map();
+		this.state.stores.set(name, entries);
+		return entries;
+	}
+
+	transaction(name) {
+		const entries = this.state.stores.get(name);
+		if (entries === undefined) throw new Error(`missing object store ${name}`);
+		return new FakeTransaction(entries);
+	}
+
+	close() {}
+}
+
+class FakeTransaction {
+	constructor(entries) {
+		this.entries = entries;
+		this.error = null;
+		this.completed = false;
+	}
+
+	objectStore() {
+		return {
+			get: (key) =>
+				this.#request(() => {
+					const value = this.entries.get(key);
+					return value === undefined ? undefined : structuredClone(value);
+				}),
+			put: (value) =>
+				this.#request(() => {
+					const cloned = structuredClone(value);
+					this.entries.set(cloned.identity, cloned);
+					return cloned.identity;
+				}),
+			delete: (key) =>
+				this.#request(() => {
+					this.entries.delete(key);
+					return undefined;
+				})
+		};
+	}
+
+	abort() {
+		if (this.completed) throw new Error('transaction already completed');
+		this.completed = true;
+		this.onabort?.({ target: this });
+	}
+
+	#request(work) {
+		const request = fakeRequest();
+		queueMicrotask(() => {
+			if (this.completed) return;
+			try {
+				request.result = work();
+				request.onsuccess?.({ target: request });
+				queueMicrotask(() => {
+					if (this.completed) return;
+					this.completed = true;
+					this.oncomplete?.({ target: this });
+				});
+			} catch (error) {
+				request.error = error;
+				this.error = error;
+				request.onerror?.({ target: request });
+				this.onerror?.({ target: this });
+			}
+		});
+		return request;
+	}
+}
+
+function fakeRequest() {
+	return {
+		result: undefined,
+		error: null,
+		onsuccess: null,
+		onerror: null,
+		onupgradeneeded: null,
+		onblocked: null
+	};
+}
diff --git a/js/tests/replica-protocol.test.mjs b/js/tests/replica-protocol.test.mjs
new file mode 100644
index 00000000..940382b4
--- /dev/null
+++ b/js/tests/replica-protocol.test.mjs
@@ -0,0 +1,2303 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	DISTRIBUTED_PROTOCOL_VERSION,
+	DistributedProtocolError,
+	parseDistributedProtocolEnvelope
+} from '../dist/index.js';
+import {
+	createDistributedReplica,
+	replicaRecordKey
+} from '../dist/replica/index.js';
+
+const Todo = Object.freeze({
+	id: 'TodoView',
+	identityFields: Object.freeze(['id'])
+});
+
+const NoVariables = Object.freeze({
+	version: 1,
+	limits: Object.freeze({
+		maxDepth: 8,
+		maxBoolWidth: 256,
+		maxInList: 1000
+	}),
+	variables: Object.freeze({}),
+	inputs: Object.freeze({})
+});
+
+const Todos = Object.freeze({
+	id: 'query:todos',
+	document: 'query Todos { todos { id title } }',
+	protocol: Object.freeze({
+		version: 1,
+		schemaHash: 'schema-a',
+		surface: Object.freeze({ kind: 'role', name: 'user' }),
+		operation: 'query:todos',
+		trustedPresets: Object.freeze([])
+	}),
+	variableCodec: NoVariables,
+	live: Object.freeze({
+		id: 'live:todos',
+		document: 'subscription TodosLive { todos { id title } }'
+	}),
+	roots: Object.freeze([
+		Object.freeze({
+			responseKey: 'todos',
+			field: 'todos',
+			cardinality: 'many',
+			nullable: false,
+			dependencies: Object.freeze(['todos']),
+			selection: Object.freeze({
+				typename: Todo.id,
+				storage: Object.freeze({
+					kind: 'normalized',
+					model: Todo.id,
+					identityFields: Todo.identityFields
+				}),
+				members: Object.freeze([
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: 'id',
+						field: 'id',
+						codec: 'ID',
+						nullable: false
+					}),
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: 'title',
+						field: 'title',
+						codec: 'String',
+						nullable: false
+					})
+				])
+			})
+		})
+	])
+});
+
+const TodosOtherOperation = Object.freeze({
+	...Todos,
+	id: 'query:todos-other',
+	protocol: Object.freeze({
+		version: 1,
+		schemaHash: 'schema-a',
+		surface: Object.freeze({ kind: 'role', name: 'user' }),
+		operation: 'query:todos-other',
+		trustedPresets: Object.freeze([])
+	}),
+	live: undefined
+});
+
+const TodosOtherLiveOperation = Object.freeze({
+	...TodosOtherOperation,
+	live: Object.freeze({
+		id: 'live:todos-other',
+		document: 'subscription TodosOtherLive { todos { id title } }'
+	})
+});
+
+/*
+ * Mirrors the generated Todos artifact's material index semantics: an exact,
+ * offset-backed collection whose authorization policy is server-only.
+ */
+const TodosServerOnly = Object.freeze({
+	...TodosOtherOperation,
+	id: 'query:todos-server-only',
+	document:
+		'query TodosServerOnly { todos(order_by: [{id: asc}]) { id title } }',
+	protocol: Object.freeze({
+		...TodosOtherOperation.protocol,
+		operation: 'query:todos-server-only'
+	}),
+	roots: Object.freeze([
+		Object.freeze({
+			...Todos.roots[0],
+			arguments: Object.freeze({
+				order_by: Object.freeze({
+					kind: 'literal',
+					value: Object.freeze([Object.freeze({ id: 'asc' })])
+				})
+			}),
+			coverage: Object.freeze({
+				kind: 'offset',
+				offsetArgument: 'offset',
+				limitArgument: 'limit',
+				defaultLimit: 100,
+				maxLimit: 1000
+			}),
+			filter: Object.freeze({
+				fields: Object.freeze([
+					Object.freeze({
+						field: 'id',
+						scalar: 'ID',
+						codec: 'string',
+						nullable: false,
+						operators: Object.freeze(['_eq'])
+					}),
+					Object.freeze({
+						field: 'title',
+						scalar: 'String',
+						codec: 'string',
+						nullable: false,
+						operators: Object.freeze(['_eq'])
+					})
+				]),
+				relationships: Object.freeze([]),
+				rowPolicy: Object.freeze({ kind: 'server_only' })
+			}),
+			order: Object.freeze({
+				input: Object.freeze({
+					kind: 'literal',
+					value: Object.freeze([Object.freeze({ id: 'asc' })])
+				}),
+				fields: Object.freeze([
+					Object.freeze({
+						field: 'id',
+						scalar: 'ID',
+						codec: 'string',
+						nullable: false
+					}),
+					Object.freeze({
+						field: 'title',
+						scalar: 'String',
+						codec: 'string',
+						nullable: false
+					})
+				]),
+				tieBreakers: Object.freeze([
+					Object.freeze({
+						field: 'id',
+						scalar: 'ID',
+						codec: 'string',
+						nullable: false
+					})
+				])
+			}),
+			pagination: Object.freeze({
+				kind: 'offset',
+				insert: 'local',
+				delete: 'local',
+				reorder: 'local',
+				stableUpdate: 'local'
+			})
+		})
+	])
+});
+
+const GamesWithOwner = Object.freeze({
+	id: 'query:games-with-owner',
+	document: 'query GamesWithOwner { games { id owner_id owner { id name } } }',
+	protocol: Object.freeze({
+		version: 1,
+		schemaHash: 'schema-a',
+		surface: Object.freeze({ kind: 'role', name: 'user' }),
+		operation: 'query:games-with-owner',
+		trustedPresets: Object.freeze([])
+	}),
+	variableCodec: NoVariables,
+	roots: Object.freeze([
+		Object.freeze({
+			responseKey: 'games',
+			field: 'games',
+			cardinality: 'many',
+			nullable: false,
+			dependencies: Object.freeze(['games']),
+			selection: Object.freeze({
+				typename: 'GameView',
+				storage: Object.freeze({
+					kind: 'normalized',
+					model: 'GameView',
+					identityFields: Object.freeze(['id'])
+				}),
+				members: Object.freeze([
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: 'id',
+						field: 'id',
+						codec: 'ID',
+						nullable: false
+					}),
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: 'owner_id',
+						field: 'owner_id',
+						codec: 'ID',
+						nullable: false
+					}),
+					Object.freeze({
+						kind: 'branch',
+						semantic: 'relationship',
+						responseKey: 'owner',
+						field: 'owner',
+						cardinality: 'one',
+						nullable: false,
+						dependencies: Object.freeze(['games', 'users']),
+						relationship: Object.freeze({
+							field: 'owner',
+							targetModel: 'UserView',
+							kind: 'belongs_to',
+							keyMapping: Object.freeze({
+								kind: 'direct',
+								local: Object.freeze(['owner_id']),
+								remote: Object.freeze(['id'])
+							}),
+							maintenance: 'revalidate',
+							dependencies: Object.freeze(['games', 'users'])
+						}),
+						selection: Object.freeze({
+							typename: 'UserView',
+							storage: Object.freeze({
+								kind: 'normalized',
+								model: 'UserView',
+								identityFields: Object.freeze(['id'])
+							}),
+							members: Object.freeze([
+								Object.freeze({
+									kind: 'scalar',
+									responseKey: 'id',
+									field: 'id',
+									codec: 'ID',
+									nullable: false
+								}),
+								Object.freeze({
+									kind: 'scalar',
+									responseKey: 'name',
+									field: 'name',
+									codec: 'String',
+									nullable: false
+								})
+							])
+						})
+					})
+				])
+			})
+		})
+	])
+});
+
+const FeaturedGamesWithOwner = Object.freeze({
+	...GamesWithOwner,
+	id: 'query:featured-games-with-owner',
+	document:
+		'query FeaturedGamesWithOwner { featuredGames { id owner_id owner { id name } } }',
+	protocol: Object.freeze({
+		...GamesWithOwner.protocol,
+		operation: 'query:featured-games-with-owner'
+	}),
+	roots: Object.freeze([
+		Object.freeze({
+			...GamesWithOwner.roots[0],
+			responseKey: 'featuredGames',
+			field: 'featured_games'
+		})
+	])
+});
+
+const GamesWithOwnerOtherOperation = Object.freeze({
+	...GamesWithOwner,
+	id: 'query:games-with-owner-other',
+	protocol: Object.freeze({
+		...GamesWithOwner.protocol,
+		operation: 'query:games-with-owner-other'
+	})
+});
+
+const GamesWithOwnerLiveOperation = Object.freeze({
+	...GamesWithOwner,
+	id: 'query:games-with-owner-live',
+	protocol: Object.freeze({
+		...GamesWithOwner.protocol,
+		operation: 'query:games-with-owner-live'
+	}),
+	live: Object.freeze({
+		id: 'live:games-with-owner',
+		document:
+			'subscription GamesWithOwnerLive { games { id owner_id owner { id name } } }'
+	})
+});
+
+function wireFrame(options = {}) {
+	const rows = options.rows ?? [{ id: 'todo-1', title: 'one' }];
+	const position = options.position ?? '1';
+	const projection = options.projection ?? 'todos-projector';
+	const resume = {
+		projection,
+		position,
+		token: options.resumeToken ?? `resume:${position}`
+	};
+	const records =
+		options.records ??
+		rows.map((row, index) => ({
+			path: ['todos', String(index)],
+			model: 'TodoView',
+			scopeToken: options.recordScope ?? `record:${row.id}`,
+			incarnation: options.incarnation ?? '1',
+			revision: options.revision ?? position,
+			tombstone: false
+		}));
+	const snapshot = {
+		scopeToken: options.snapshotScope ?? 'snapshot:query',
+		recordsComplete: options.recordsComplete ?? true,
+		indexesComparable: options.indexesComparable ?? true,
+		records,
+		indexes:
+			options.indexes ??
+			(options.indexesComparable === false
+				? []
+				: [
+						{
+							projection,
+							scopeToken: options.indexScope ?? 'index:query',
+							position,
+							resume
+						}
+					]),
+		observations: options.observations ?? []
+	};
+	const live =
+		options.live === undefined
+			? undefined
+			: {
+					supported: options.live.supported ?? true,
+					reset: options.live.reset ?? false,
+					cursors:
+						options.live.cursors ??
+						(options.live.supported === false ? [] : [resume])
+				};
+	return {
+		data: { todos: rows },
+		extensions: {
+			distributed: {
+				protocolVersion: DISTRIBUTED_PROTOCOL_VERSION,
+				schemaHash: options.schemaHash ?? 'schema-a',
+				cacheScope: options.cacheScope ?? 'cache:a',
+				operation: options.operation ?? 'query:todos',
+				...(options.command === undefined
+					? {}
+					: { command: options.command }),
+				snapshot,
+				...(live === undefined ? {} : { live })
+			}
+		}
+	};
+}
+
+function gamesFrame({
+	artifact,
+	responseKey,
+	position,
+	ownerId,
+	ownerName,
+	projection = 'games-owner-projector',
+	operation = artifact.id,
+	live,
+	indexesComparable = true
+}) {
+	return {
+		data: {
+			[responseKey]: [
+				{
+					id: 'game-1',
+					owner_id: ownerId,
+					owner: { id: ownerId, name: ownerName }
+				}
+			]
+		},
+		extensions: {
+			distributed: {
+				protocolVersion: DISTRIBUTED_PROTOCOL_VERSION,
+				schemaHash: 'schema-a',
+				cacheScope: 'cache:a',
+				operation,
+				snapshot: {
+					scopeToken: `snapshot:${artifact.id}`,
+					recordsComplete: true,
+					indexesComparable,
+					records: [
+						{
+							path: [responseKey, '0'],
+							model: 'GameView',
+							scopeToken: 'record:game-1',
+							incarnation: '1',
+							revision: position,
+							tombstone: false
+						},
+						{
+							path: [responseKey, '0', 'owner'],
+							model: 'UserView',
+							scopeToken: `record:${ownerId}`,
+							incarnation: '1',
+							revision: position,
+							tombstone: false
+						}
+					],
+					indexes: indexesComparable
+						? [
+								{
+									projection,
+									scopeToken: 'index:games',
+									position,
+									resume: {
+										projection,
+										position,
+										token: `resume:${position}`
+									}
+								}
+							]
+						: [],
+					observations: []
+				},
+				...(live === undefined ? {} : { live })
+			}
+		}
+	};
+}
+
+function write(replica, options = {}, source = 'network', artifact = Todos) {
+	replica.writeResult(artifact, {}, wireFrame(options), source);
+}
+
+function commandMetadata(options = {}) {
+	return parseDistributedProtocolEnvelope({
+		protocolVersion: DISTRIBUTED_PROTOCOL_VERSION,
+		schemaHash: 'schema-a',
+		cacheScope: 'cache:a',
+		operation: 'command:todo',
+		command: {
+			commandId: options.commandId ?? 'cmd-1',
+			causationId: options.causationId ?? 'cause-1',
+			state: options.state ?? 'accepted_pending_projection',
+			consistency: 'fact',
+			expects: [
+				{
+					projection: 'todos-projector',
+					model: 'TodoView',
+					scopeToken: options.expectationToken ?? 'expect:todo-1'
+				}
+			],
+			...(options.observations === undefined
+				? {}
+				: { observations: options.observations })
+		}
+	}).command;
+}
+
+test('authorized replacement snapshots render without a causal index vector', () => {
+	const replica = createDistributedReplica();
+	write(replica, {
+		recordsComplete: true,
+		indexesComparable: false,
+		rows: [{ id: 'todo-1', title: 'first authorized result' }]
+	});
+
+	const first = replica.read(Todos, {});
+	assert.equal(first.status, 'ready');
+	assert.equal(first.complete, true);
+	assert.deepEqual(first.data.todos, [
+		{ id: 'todo-1', title: 'first authorized result' }
+	]);
+	const firstIndex = replica.inspectIndex({ field: 'todos', arguments: {} });
+	assert.equal(firstIndex.complete, true);
+
+	write(replica, {
+		recordsComplete: true,
+		indexesComparable: false,
+		rows: [{ id: 'todo-2', title: 'replacement result' }],
+		recordScope: 'record:todo-2'
+	});
+
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-2', title: 'replacement result' }
+	]);
+	const replacementIndex = replica.inspectIndex({
+		field: 'todos',
+		arguments: {}
+	});
+	assert.notEqual(replacementIndex.revision, firstIndex.revision);
+});
+
+test('authoritative revalidation succeeds against confirmed data while a server-only optimistic index remains stale', async () => {
+	const fetches = [];
+	const replica = createDistributedReplica({
+		transport: {
+			fetch(request) {
+				let resolve;
+				const promise = new Promise((done) => {
+					resolve = done;
+				});
+				fetches.push({ request, resolve });
+				return promise;
+			}
+		}
+	});
+	const frame = (position, rows) =>
+		wireFrame({
+			operation: TodosServerOnly.id,
+			position,
+			recordsComplete: true,
+			indexesComparable: false,
+			rows
+		});
+	const watch = replica.watch(TodosServerOnly, {});
+	await Promise.resolve();
+	assert.equal(fetches.length, 1);
+	fetches[0].resolve(frame('1', [{ id: 'todo-1', title: 'base' }]));
+	await new Promise((resolve) => setImmediate(resolve));
+	assert.equal(watch.get().complete, true);
+
+	replica.createOptimisticLayer('cmd-server-only', (writer) => {
+		writer.writeRecord(Todo, 'todo-2', {
+			fields: { id: 'todo-2', title: 'optimistic' }
+		});
+	});
+	replica.markOptimisticLayerAccepted('cmd-server-only');
+	assert.equal(
+		watch.get().complete,
+		true,
+		'the structurally complete optimistic view must remain renderable'
+	);
+	assert.equal(watch.get().stale, true);
+
+	await new Promise((resolve) => setImmediate(resolve));
+	assert.equal(fetches.length, 2);
+	fetches[1].resolve(
+		frame('2', [
+			{ id: 'todo-1', title: 'base' },
+			{ id: 'todo-2', title: 'projected' }
+		])
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+	assert.equal(watch.get().complete, true);
+	assert.equal(watch.get().stale, true);
+	assert.deepEqual(watch.get().data.todos, [
+		{ id: 'todo-1', title: 'base' },
+		{ id: 'todo-2', title: 'optimistic' }
+	]);
+
+	const revalidation = replica.revalidate({
+		dependencies: ['todos'],
+		models: ['TodoView'],
+		relationships: []
+	});
+	await new Promise((resolve) => setImmediate(resolve));
+	assert.equal(fetches.length, 3);
+	fetches[2].resolve(
+		frame('3', [
+			{ id: 'todo-1', title: 'base' },
+			{ id: 'todo-2', title: 'projected' }
+		])
+	);
+	await revalidation;
+
+	assert.equal(
+		watch.get().complete,
+		true,
+		'the visible policy-safe overlay remains renderable until command retirement'
+	);
+	assert.equal(watch.get().stale, true);
+	replica.confirmOptimisticLayer('cmd-server-only', () => undefined);
+	assert.equal(watch.get().complete, true);
+	assert.equal(watch.get().stale, false);
+	assert.deepEqual(watch.get().data.todos, [
+		{ id: 'todo-1', title: 'base' },
+		{ id: 'todo-2', title: 'projected' }
+	]);
+	watch.destroy();
+});
+
+test('shared non-comparable membership follows request-start order across operations', async () => {
+	const fetches = [];
+	const replica = createDistributedReplica({
+		transport: {
+			fetch(request) {
+				let resolve;
+				const promise = new Promise((done) => {
+					resolve = done;
+				});
+				fetches.push({ request, resolve });
+				return promise;
+			}
+		}
+	});
+	const first = replica.watch(Todos, {});
+	const second = replica.watch(TodosOtherOperation, {});
+	await Promise.resolve();
+	assert.equal(fetches.length, 2);
+
+	fetches[1].resolve(
+		wireFrame({
+			operation: TodosOtherOperation.id,
+			recordsComplete: true,
+			indexesComparable: false,
+			rows: [{ id: 'todo-new', title: 'later request' }],
+			recordScope: 'record:todo-new'
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+	fetches[0].resolve(
+		wireFrame({
+			operation: Todos.id,
+			recordsComplete: true,
+			indexesComparable: false,
+			rows: [{ id: 'todo-old', title: 'slower earlier request' }],
+			recordScope: 'record:todo-old'
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+
+	/*
+	 * These artifacts describe the same field/arguments membership. Sharing is
+	 * intentional, but local request-start order—not response arrival—decides
+	 * which exact authorized replacement is newer when no server vector exists.
+	 */
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-new', title: 'later request' }
+	]);
+	assert.deepEqual(replica.read(TodosOtherOperation, {}).data.todos, [
+		{ id: 'todo-new', title: 'later request' }
+	]);
+	first.destroy();
+	second.destroy();
+});
+
+test('non-comparable request order is atomic across shared root and nested indexes', async () => {
+	const fetches = [];
+	const replica = createDistributedReplica({
+		transport: {
+			fetch(request) {
+				let resolve;
+				const promise = new Promise((done) => {
+					resolve = done;
+				});
+				fetches.push({ request, resolve });
+				return promise;
+			}
+		}
+	});
+	replica.writeResult(
+		GamesWithOwnerOtherOperation,
+		{},
+		gamesFrame({
+			artifact: GamesWithOwnerOtherOperation,
+			responseKey: 'games',
+			position: '1',
+			ownerId: 'user-root',
+			ownerName: 'root owner'
+		}),
+		'network'
+	);
+	const rootBefore = replica.inspectIndex({ field: 'games', arguments: {} });
+	const incoming = replica.watch(GamesWithOwner, {});
+	const incomingRefresh = incoming.refresh();
+	const nestedOwner = replica.watch(FeaturedGamesWithOwner, {});
+	await Promise.resolve();
+	assert.equal(fetches.length, 2);
+
+	fetches[1].resolve(
+		gamesFrame({
+			artifact: FeaturedGamesWithOwner,
+			responseKey: 'featuredGames',
+			position: '3',
+			ownerId: 'user-nested',
+			ownerName: 'later nested owner',
+			indexesComparable: false
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+	fetches[0].resolve(
+		gamesFrame({
+			artifact: GamesWithOwner,
+			responseKey: 'games',
+			position: '2',
+			ownerId: 'user-incoming',
+			ownerName: 'earlier whole graph',
+			indexesComparable: false
+		})
+	);
+	await incomingRefresh;
+
+	assert.equal(
+		replica.inspectIndex({ field: 'games', arguments: {} }).revision,
+		rootBefore.revision,
+		'the earlier request cannot update only its older root'
+	);
+	assert.equal(
+		replica.read(GamesWithOwner, {}).data.games[0].owner.name,
+		'later nested owner'
+	);
+	incoming.destroy();
+	nestedOwner.destroy();
+});
+
+test('shared comparable membership follows server vectors across operations', async (t) => {
+	const scenario = async ({
+		firstPosition,
+		firstTitle,
+		secondPosition,
+		secondTitle,
+		resolveSecondFirst,
+		expectedTitle
+	}) => {
+		const fetches = [];
+		const replica = createDistributedReplica({
+			transport: {
+				fetch(request) {
+					let resolve;
+					const promise = new Promise((done) => {
+						resolve = done;
+					});
+					fetches.push({ request, resolve });
+					return promise;
+				}
+			}
+		});
+		const first = replica.watch(Todos, {});
+		const second = replica.watch(TodosOtherOperation, {});
+		await Promise.resolve();
+		assert.equal(fetches.length, 2);
+		const firstFrame = wireFrame({
+			operation: Todos.id,
+			snapshotScope: 'snapshot:todos',
+			position: firstPosition,
+			rows: [{ id: 'todo-first', title: firstTitle }]
+		});
+		const secondFrame = wireFrame({
+			operation: TodosOtherOperation.id,
+			snapshotScope: 'snapshot:todos-other',
+			position: secondPosition,
+			rows: [{ id: 'todo-second', title: secondTitle }]
+		});
+		const order = resolveSecondFirst
+			? [
+					[fetches[1], secondFrame],
+					[fetches[0], firstFrame]
+				]
+			: [
+					[fetches[0], firstFrame],
+					[fetches[1], secondFrame]
+				];
+		for (const [fetch, frame] of order) {
+			fetch.resolve(frame);
+			await new Promise((resolve) => setImmediate(resolve));
+		}
+		assert.equal(replica.read(Todos, {}).data.todos[0].title, expectedTitle);
+		assert.equal(
+			replica.read(TodosOtherOperation, {}).data.todos[0].title,
+			expectedTitle
+		);
+		first.destroy();
+		second.destroy();
+	};
+
+	await t.test('a slower earlier request with a higher vector wins', () =>
+		scenario({
+			firstPosition: '10',
+			firstTitle: 'server position 10',
+			secondPosition: '9',
+			secondTitle: 'server position 9',
+			resolveSecondFirst: true,
+			expectedTitle: 'server position 10'
+		})
+	);
+	await t.test('a later-started lower vector cannot clobber', () =>
+		scenario({
+			firstPosition: '10',
+			firstTitle: 'server position 10',
+			secondPosition: '8',
+			secondTitle: 'server position 8',
+			resolveSecondFirst: false,
+			expectedTitle: 'server position 10'
+		})
+	);
+});
+
+test('a stale index fence retains its newer shared server vector', async () => {
+	const fetches = [];
+	const replica = createDistributedReplica({
+		transport: {
+			fetch(request) {
+				let resolve;
+				const promise = new Promise((done) => {
+					resolve = done;
+				});
+				fetches.push({ request, resolve });
+				return promise;
+			}
+		}
+	});
+	write(replica, {
+		position: '10',
+		rows: [{ id: 'todo-10', title: 'server position 10' }]
+	});
+	const partial = wireFrame({
+		position: '11',
+		rows: []
+	});
+	partial.data = {};
+	partial.errors = [{ message: 'root failed', path: ['todos'] }];
+	partial.extensions.distributed.snapshot.records = [];
+	replica.writeResult(Todos, {}, partial, 'network');
+	const staleFence = replica.inspectIndex({
+		field: 'todos',
+		arguments: {}
+	});
+	assert.equal(staleFence.staleRevision, '2');
+
+	const lower = replica.watch(TodosOtherOperation, {});
+	await Promise.resolve();
+	assert.equal(fetches.length, 1);
+	fetches[0].resolve(
+		wireFrame({
+			operation: TodosOtherOperation.id,
+			snapshotScope: 'snapshot:todos-other',
+			position: '9',
+			rows: [{ id: 'todo-9', title: 'lower server position' }]
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+
+	const after = replica.inspectIndex({ field: 'todos', arguments: {} });
+	assert.equal(after.revision, staleFence.revision);
+	assert.equal(after.staleRevision, staleFence.staleRevision);
+	assert.equal(replica.read(TodosOtherOperation, {}).stale, true);
+	lower.destroy();
+});
+
+test('comparable vectors govern nested indexes shared by distinct roots', async () => {
+	const fetches = [];
+	const replica = createDistributedReplica({
+		transport: {
+			fetch(request) {
+				let resolve;
+				const promise = new Promise((done) => {
+					resolve = done;
+				});
+				fetches.push({ request, resolve });
+				return promise;
+			}
+		}
+	});
+	const games = replica.watch(GamesWithOwner, {});
+	const featured = replica.watch(FeaturedGamesWithOwner, {});
+	await Promise.resolve();
+	assert.equal(fetches.length, 2);
+
+	fetches[1].resolve(
+		gamesFrame({
+			artifact: FeaturedGamesWithOwner,
+			responseKey: 'featuredGames',
+			position: '9',
+			ownerId: 'user-old',
+			ownerName: 'old owner'
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+	fetches[0].resolve(
+		gamesFrame({
+			artifact: GamesWithOwner,
+			responseKey: 'games',
+			position: '10',
+			ownerId: 'user-new',
+			ownerName: 'new owner'
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+
+	assert.equal(
+		replica.read(GamesWithOwner, {}).data.games[0].owner.name,
+		'new owner'
+	);
+	games.destroy();
+	featured.destroy();
+});
+
+test('a comparable shared root cannot promote an incomparable nested sibling', async () => {
+	const fetches = [];
+	const replica = createDistributedReplica({
+		transport: {
+			fetch(request) {
+				let resolve;
+				const promise = new Promise((done) => {
+					resolve = done;
+				});
+				fetches.push({ request, resolve });
+				return promise;
+			}
+		}
+	});
+	const incoming = replica.watch(GamesWithOwner, {});
+	const rootOwner = replica.watch(GamesWithOwnerOtherOperation, {});
+	const nestedOwner = replica.watch(FeaturedGamesWithOwner, {});
+	await Promise.resolve();
+	assert.equal(fetches.length, 3);
+
+	fetches[1].resolve(
+		gamesFrame({
+			artifact: GamesWithOwnerOtherOperation,
+			responseKey: 'games',
+			position: '5',
+			ownerId: 'user-root',
+			ownerName: 'root owner'
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+	fetches[2].resolve(
+		gamesFrame({
+			artifact: FeaturedGamesWithOwner,
+			responseKey: 'featuredGames',
+			position: '9',
+			ownerId: 'user-nested',
+			ownerName: 'incomparable nested owner',
+			projection: 'featured-games-projector'
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+	fetches[0].resolve(
+		gamesFrame({
+			artifact: GamesWithOwner,
+			responseKey: 'games',
+			position: '6',
+			ownerId: 'user-incoming',
+			ownerName: 'should remain fenced'
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+
+	assert.equal(
+		replica.read(GamesWithOwner, {}).data.games[0].owner.name,
+		'incomparable nested owner'
+	);
+	replica.writeResult(
+		GamesWithOwnerLiveOperation,
+		{},
+		gamesFrame({
+			artifact: GamesWithOwnerLiveOperation,
+			responseKey: 'games',
+			position: '7',
+			ownerId: 'user-live',
+			ownerName: 'unfenced live frame',
+			operation: GamesWithOwnerLiveOperation.live.id,
+			live: {
+				supported: true,
+				reset: false,
+				cursors: [
+					{
+						projection: 'games-owner-projector',
+						position: '7',
+						token: 'resume:7'
+					}
+				]
+			}
+		}),
+		'live'
+	);
+	assert.equal(
+		replica.read(GamesWithOwner, {}).data.games[0].owner.name,
+		'incomparable nested owner',
+		'a live frame without a request-start fence cannot promote the graph'
+	);
+	incoming.destroy();
+	rootOwner.destroy();
+	nestedOwner.destroy();
+});
+
+test('an older operation reset cannot erase a shared index owned by a newer artifact', () => {
+	const replica = createDistributedReplica();
+	write(
+		replica,
+		{
+			operation: Todos.live.id,
+			position: '5',
+			rows: [{ id: 'todo-live', title: 'old live owner' }],
+			live: { supported: true }
+		},
+		'live'
+	);
+	write(
+		replica,
+		{
+			operation: TodosOtherOperation.id,
+			snapshotScope: 'snapshot:todos-other',
+			position: '9',
+			rows: [{ id: 'todo-new', title: 'new artifact owner' }]
+		},
+		'network',
+		TodosOtherOperation
+	);
+	write(
+		replica,
+		{
+			operation: Todos.live.id,
+			position: '8',
+			rows: [{ id: 'todo-reset', title: 'older reset' }],
+			live: { supported: true, reset: true }
+		},
+		'live'
+	);
+
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-new', title: 'new artifact owner' }
+	]);
+});
+
+test('reset preserves an equal-vector index with another operation co-owner', () => {
+	const replica = createDistributedReplica();
+	write(
+		replica,
+		{
+			operation: Todos.live.id,
+			position: '5',
+			rows: [{ id: 'todo-shared', title: 'shared snapshot' }],
+			live: { supported: true }
+		},
+		'live'
+	);
+	write(
+		replica,
+		{
+			operation: TodosOtherOperation.id,
+			snapshotScope: 'snapshot:todos-other',
+			position: '5',
+			rows: [{ id: 'todo-shared', title: 'shared snapshot' }]
+		},
+		'network',
+		TodosOtherOperation
+	);
+	write(
+		replica,
+		{
+			operation: Todos.live.id,
+			position: '4',
+			rows: [{ id: 'todo-reset', title: 'older reset' }],
+			live: { supported: true, reset: true }
+		},
+		'live'
+	);
+
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-shared', title: 'shared snapshot' }
+	]);
+});
+
+test('snapshot-only nested records do not invalidate exact membership', () => {
+	const replica = createDistributedReplica();
+	replica.writeResult(
+		GamesWithOwner,
+		{},
+		{
+			data: {
+				games: [
+					{
+						id: 'game-1',
+						owner_id: 'user-1',
+						owner: { id: 'user-1', name: 'Pat' }
+					}
+				]
+			},
+			extensions: {
+				distributed: {
+					protocolVersion: DISTRIBUTED_PROTOCOL_VERSION,
+					schemaHash: 'schema-a',
+					cacheScope: 'cache:a',
+					operation: GamesWithOwner.id,
+					snapshot: {
+						scopeToken: 'snapshot:games',
+						recordsComplete: false,
+						indexesComparable: false,
+						records: [
+							{
+								path: ['games', '0'],
+								model: 'GameView',
+								scopeToken: 'record:game-1',
+								incarnation: '1',
+								revision: '1',
+								tombstone: false
+							}
+						],
+						indexes: [],
+						observations: []
+					}
+				}
+			}
+		},
+		'network'
+	);
+
+	const snapshot = replica.read(GamesWithOwner, {});
+	assert.equal(snapshot.status, 'ready');
+	assert.equal(snapshot.complete, true);
+	assert.deepEqual(snapshot.data.games, [
+		{
+			id: 'game-1',
+			owner_id: 'user-1',
+			owner: { id: 'user-1', name: 'Pat' }
+		}
+	]);
+});
+
+test('v1 replica ingress rejects tampered decimals before exposing data', () => {
+	const replica = createDistributedReplica();
+	const tampered = wireFrame();
+	tampered.extensions.distributed.snapshot.indexes[0].position = 1;
+
+	assert.throws(
+		() => replica.writeResult(Todos, {}, tampered, 'network'),
+		(error) =>
+			error instanceof DistributedProtocolError &&
+			error.path.endsWith('.position')
+	);
+	assert.equal(replica.read(Todos, {}).complete, false);
+	assert.equal(replica.inspectRecord(Todo, 'todo-1'), undefined);
+});
+
+test('record and index clocks reject lower or incomparable evidence without numeric coercion', () => {
+	const replica = createDistributedReplica();
+	write(replica, {
+		position: '18446744073709551615',
+		revision: '18446744073709551615',
+		rows: [{ id: 'todo-1', title: 'newest' }]
+	});
+	write(replica, {
+		position: '9',
+		revision: '9',
+		rows: [{ id: 'todo-1', title: 'late-old' }]
+	});
+
+	assert.equal(replica.read(Todos, {}).data.todos[0].title, 'newest');
+	assert.equal(
+		replica.inspectRecord(Todo, 'todo-1').revision,
+		'18446744073709551615'
+	);
+
+	assert.throws(
+		() =>
+			write(replica, {
+				position: '18446744073709551615',
+				revision: '18446744073709551615',
+				recordScope: 'record:incomparable',
+				rows: [{ id: 'todo-1', title: 'must-not-win' }]
+			}),
+		DistributedProtocolError
+	);
+	assert.equal(
+		replica.inspectRecord(Todo, 'todo-1').revision,
+		'18446744073709551615'
+	);
+	assert.equal(replica.inspectIndex({ field: 'todos', arguments: {} }), undefined);
+});
+
+test('tombstone and explicit recreate fences reject stale resurrection', () => {
+	const replica = createDistributedReplica();
+	write(replica, {
+		position: '1',
+		revision: '1',
+		rows: [{ id: 'todo-1', title: 'first lifecycle' }]
+	});
+	write(replica, {
+		position: '9',
+		rows: [],
+		records: [
+			{
+				path: ['todos', '0'],
+				model: 'TodoView',
+				scopeToken: 'record:todo-1',
+				incarnation: '1',
+				revision: '9',
+				tombstone: true
+			}
+		]
+	});
+	assert.equal(replica.inspectRecord(Todo, 'todo-1'), undefined);
+	assert.deepEqual(replica.read(Todos, {}).data.todos, []);
+
+	write(replica, {
+		position: '1',
+		revision: '1',
+		rows: [{ id: 'todo-1', title: 'delayed pre-delete' }]
+	});
+	assert.equal(replica.inspectRecord(Todo, 'todo-1'), undefined);
+
+	assert.throws(
+		() =>
+			write(replica, {
+				position: '10',
+				incarnation: '1',
+				revision: '10',
+				rows: [{ id: 'todo-1', title: 'implicit resurrection' }]
+			}),
+		DistributedProtocolError
+	);
+	assert.equal(replica.inspectRecord(Todo, 'todo-1'), undefined);
+
+	write(replica, {
+		position: '11',
+		incarnation: '2',
+		revision: '1',
+		rows: [{ id: 'todo-1', title: 'explicit recreate' }]
+	});
+	assert.equal(replica.read(Todos, {}).data.todos[0].title, 'explicit recreate');
+	assert.equal(replica.inspectRecord(Todo, 'todo-1').incarnation, '2');
+	assert.equal(replica.inspectRecord(Todo, 'todo-1').revision, '1');
+
+	write(replica, {
+		position: '12',
+		incarnation: '1',
+		revision: '12',
+		rows: [{ id: 'todo-1', title: 'stale prior lifecycle' }]
+	});
+	assert.equal(replica.read(Todos, {}).data.todos[0].title, 'explicit recreate');
+});
+
+test('live reset replaces its snapshot and a later query refetch may hand back', () => {
+	const replica = createDistributedReplica();
+	write(replica, {
+		position: '5',
+		rows: [{ id: 'todo-old', title: 'old snapshot' }],
+		recordScope: 'record:old'
+	});
+	write(
+		replica,
+		{
+			operation: 'live:todos',
+			position: '6',
+			rows: [{ id: 'todo-new', title: 'fresh live snapshot' }],
+			recordScope: 'record:new',
+			live: { reset: true }
+		},
+		'live'
+	);
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-new', title: 'fresh live snapshot' }
+	]);
+
+	write(replica, {
+		position: '7',
+		rows: [{ id: 'todo-old', title: 'later query refetch' }],
+		recordScope: 'record:old'
+	});
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-old', title: 'later query refetch' }
+	]);
+});
+
+test('a live handoff fences an HTTP response launched in the prior generation', async () => {
+	let resolveFetch;
+	let liveObserver;
+	const pendingFetch = new Promise((resolve) => {
+		resolveFetch = resolve;
+	});
+	const replica = createDistributedReplica({
+		transport: {
+			fetch() {
+				return pendingFetch;
+			},
+			subscribe(_request, observer) {
+				liveObserver = observer;
+				return () => {};
+			}
+		}
+	});
+	const watch = replica.watch(Todos, {}, { live: true });
+	await Promise.resolve();
+
+	liveObserver.next(
+		wireFrame({
+			operation: 'live:todos',
+			position: '1',
+			rows: [{ id: 'todo-live', title: 'live wins' }],
+			recordScope: 'record:live',
+			live: { reset: true }
+		})
+	);
+	resolveFetch(
+		wireFrame({
+			position: '99',
+			rows: [{ id: 'todo-http', title: 'stale HTTP' }],
+			recordScope: 'record:http'
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-live', title: 'live wins' }
+	]);
+	watch.destroy();
+});
+
+test('unsupported live fallback cannot fence HTTP membership or later revalidation', async () => {
+	const fetches = [];
+	const subscriptions = [];
+	let unsubscribeCount = 0;
+	const replica = createDistributedReplica({
+		transport: {
+			fetch(request) {
+				let resolve;
+				const promise = new Promise((done) => {
+					resolve = done;
+				});
+				fetches.push({ request, resolve });
+				return promise;
+			},
+			subscribe(request, observer) {
+				subscriptions.push({ request, observer });
+				return () => {
+					unsubscribeCount += 1;
+				};
+			}
+		}
+	});
+	const watch = replica.watch(Todos, {}, { live: true });
+	await Promise.resolve();
+	assert.equal(fetches.length, 1);
+	assert.equal(subscriptions.length, 1);
+
+	subscriptions[0].observer.next(
+		wireFrame({
+			operation: 'live:todos',
+			position: '1',
+			rows: [{ id: 'todo-live', title: 'provisional live fallback' }],
+			recordScope: 'record:live',
+			indexesComparable: false,
+			live: { supported: false, reset: true }
+		})
+	);
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-live', title: 'provisional live fallback' }
+	]);
+	assert.equal(watch.get().live, 'off');
+	assert.equal(unsubscribeCount, 1);
+
+	await Promise.resolve();
+	fetches[0].resolve(
+		wireFrame({
+			position: '2',
+			rows: [{ id: 'todo-http', title: 'newer HTTP membership' }],
+			recordScope: 'record:http',
+			indexesComparable: false
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-http', title: 'newer HTTP membership' }
+	]);
+	assert.equal(
+		subscriptions.length,
+		1,
+		'query fallback must not immediately reopen an unsupported stream'
+	);
+
+	const revalidation = replica.revalidate({
+		dependencies: ['todos'],
+		models: [],
+		relationships: []
+	});
+	await new Promise((resolve) => setImmediate(resolve));
+	assert.equal(fetches.length, 2);
+	fetches[1].resolve(
+		wireFrame({
+			position: '3',
+			rows: [{ id: 'todo-revalidated', title: 'revalidated membership' }],
+			recordScope: 'record:revalidated',
+			indexesComparable: false
+		})
+	);
+	await revalidation;
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-revalidated', title: 'revalidated membership' }
+	]);
+	assert.equal(subscriptions.length, 1);
+
+	watch.destroy();
+	assert.equal(unsubscribeCount, 1);
+});
+
+test('conflicting provisional live fallbacks still close and yield to HTTP', async () => {
+	const fetches = [];
+	let liveObserver;
+	let unsubscribeCount = 0;
+	const replica = createDistributedReplica({
+		transport: {
+			fetch() {
+				let resolve;
+				const promise = new Promise((done) => {
+					resolve = done;
+				});
+				fetches.push({ resolve });
+				return promise;
+			},
+			subscribe(_request, observer) {
+				liveObserver = observer;
+				return () => {
+					unsubscribeCount += 1;
+				};
+			}
+		}
+	});
+	replica.writeResult(
+		TodosOtherLiveOperation,
+		{},
+		wireFrame({
+			operation: 'live:todos-other',
+			rows: [{ id: 'todo-other', title: 'other provisional membership' }],
+			recordScope: 'record:other',
+			indexesComparable: false,
+			live: { supported: false, reset: true }
+		}),
+		'live'
+	);
+
+	const watch = replica.watch(Todos, {}, { live: true });
+	await Promise.resolve();
+	liveObserver.next(
+		wireFrame({
+			operation: 'live:todos',
+			rows: [{ id: 'todo-live', title: 'conflicting provisional membership' }],
+			recordScope: 'record:live',
+			indexesComparable: false,
+			live: { supported: false, reset: true }
+		})
+	);
+	assert.equal(watch.get().live, 'off');
+	assert.equal(unsubscribeCount, 1);
+
+	await Promise.resolve();
+	fetches[0].resolve(
+		wireFrame({
+			rows: [{ id: 'todo-http', title: 'authoritative HTTP membership' }],
+			recordScope: 'record:http',
+			indexesComparable: false
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-http', title: 'authoritative HTTP membership' }
+	]);
+
+	watch.destroy();
+	assert.equal(unsubscribeCount, 1);
+});
+
+test('completed supported live streams relinquish ownership and fall back to HTTP', async () => {
+	const fetches = [];
+	const subscriptions = [];
+	let unsubscribeCount = 0;
+	const replica = createDistributedReplica({
+		transport: {
+			fetch() {
+				let resolve;
+				const promise = new Promise((done) => {
+					resolve = done;
+				});
+				fetches.push({ resolve });
+				return promise;
+			},
+			subscribe(_request, observer) {
+				subscriptions.push(observer);
+				return () => {
+					unsubscribeCount += 1;
+				};
+			}
+		}
+	});
+	const watch = replica.watch(Todos, {}, { live: true });
+	await Promise.resolve();
+	assert.equal(fetches.length, 1);
+	assert.equal(watch.get().live, 'active');
+
+	subscriptions[0].next(
+		wireFrame({
+			operation: 'live:todos',
+			position: '2',
+			rows: [{ id: 'todo-live', title: 'supported live membership' }],
+			recordScope: 'record:live',
+			live: { supported: true, reset: true }
+		})
+	);
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-live', title: 'supported live membership' }
+	]);
+	subscriptions[0].complete();
+	assert.equal(watch.get().live, 'off');
+	assert.equal(unsubscribeCount, 1);
+
+	fetches[0].resolve(
+		wireFrame({
+			position: '99',
+			rows: [{ id: 'todo-old-http', title: 'superseded HTTP membership' }],
+			recordScope: 'record:old-http'
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-live', title: 'supported live membership' }
+	]);
+	assert.equal(fetches.length, 2);
+
+	fetches[1].resolve(
+		wireFrame({
+			position: '3',
+			rows: [{ id: 'todo-http', title: 'completion fallback' }],
+			recordScope: 'record:http',
+			indexesComparable: false
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-http', title: 'completion fallback' }
+	]);
+	assert.equal(subscriptions.length, 1);
+
+	watch.destroy();
+	assert.equal(unsubscribeCount, 1);
+});
+
+test('terminal live errors close their stream and allow a later HTTP retry', async () => {
+	const fetches = [];
+	const subscriptions = [];
+	let unsubscribeCount = 0;
+	const replica = createDistributedReplica({
+		transport: {
+			fetch() {
+				let resolve;
+				const promise = new Promise((done) => {
+					resolve = done;
+				});
+				fetches.push({ resolve });
+				return promise;
+			},
+			subscribe(_request, observer) {
+				subscriptions.push(observer);
+				return () => {
+					unsubscribeCount += 1;
+				};
+			}
+		}
+	});
+	write(replica, {
+		rows: [{ id: 'todo-query', title: 'initial query' }],
+		recordScope: 'record:query'
+	});
+	const watch = replica.watch(Todos, {}, { live: true });
+
+	subscriptions[0].error(new Error('terminal live failure'));
+	assert.equal(watch.get().live, 'error');
+	assert.equal(unsubscribeCount, 1);
+
+	const retry = watch.refresh();
+	await Promise.resolve();
+	assert.equal(fetches.length, 1);
+	fetches[0].resolve(
+		wireFrame({
+			position: '2',
+			rows: [{ id: 'todo-http', title: 'retry membership' }],
+			recordScope: 'record:http'
+		})
+	);
+	await retry;
+	assert.equal(subscriptions.length, 2);
+	assert.equal(watch.get().live, 'active');
+	assert.deepEqual(watch.get().errors, []);
+
+	watch.destroy();
+	assert.equal(unsubscribeCount, 2);
+});
+
+test('live advancement fences an overlapping refresh while a later clean refresh succeeds', async () => {
+	const fetches = [];
+	const subscriptions = [];
+	let liveObserver;
+	const replica = createDistributedReplica({
+		transport: {
+			fetch() {
+				let resolve;
+				const promise = new Promise((done) => {
+					resolve = done;
+				});
+				fetches.push({ promise, resolve });
+				return promise;
+			},
+			subscribe(request, observer) {
+				subscriptions.push({ request, observer });
+				liveObserver = observer;
+				return () => {};
+			}
+		}
+	});
+	const watch = replica.watch(Todos, {}, { live: true });
+	await Promise.resolve();
+	assert.equal(fetches.length, 1);
+	liveObserver.next(
+		wireFrame({
+			operation: 'live:todos',
+			position: '1',
+			rows: [{ id: 'todo-live', title: 'live one' }],
+			recordScope: 'record:live',
+			live: { reset: true }
+		})
+	);
+	fetches[0].resolve(
+		wireFrame({
+			position: '90',
+			rows: [{ id: 'todo-old-http', title: 'old HTTP' }],
+			recordScope: 'record:old-http'
+		})
+	);
+	await new Promise((resolve) => setImmediate(resolve));
+
+	const overlapping = watch.refresh();
+	await Promise.resolve();
+	assert.equal(fetches.length, 2);
+	liveObserver.next(
+		wireFrame({
+			operation: 'live:todos',
+			position: '2',
+			revision: '2',
+			rows: [{ id: 'todo-live', title: 'live two' }],
+			recordScope: 'record:live',
+			live: { reset: false }
+		})
+	);
+	fetches[1].resolve(
+		wireFrame({
+			position: '99',
+			rows: [{ id: 'todo-racing-http', title: 'racing HTTP' }],
+			recordScope: 'record:racing-http'
+		})
+	);
+	await overlapping;
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-live', title: 'live two' }
+	]);
+
+	const clean = watch.refresh();
+	const preRefreshObserver = liveObserver;
+	await Promise.resolve();
+	assert.equal(fetches.length, 3);
+	fetches[2].resolve(
+		wireFrame({
+			position: '100',
+			rows: [{ id: 'todo-refreshed', title: 'clean refresh' }],
+			recordScope: 'record:refreshed'
+		})
+	);
+	await clean;
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-refreshed', title: 'clean refresh' }
+	]);
+	assert.equal(subscriptions.length, 2);
+	assert.notEqual(liveObserver, preRefreshObserver);
+	assert.deepEqual(subscriptions[1].request.resume, [
+		{
+			projection: 'todos-projector',
+			position: '100',
+			token: 'resume:100'
+		}
+	]);
+
+	preRefreshObserver.next(
+		wireFrame({
+			operation: 'live:todos',
+			position: '999',
+			revision: '999',
+			rows: [{ id: 'todo-live', title: 'queued old subscription' }],
+			recordScope: 'record:live',
+			live: { reset: false }
+		})
+	);
+	liveObserver.next(
+		wireFrame({
+			operation: 'live:todos',
+			position: '101',
+			revision: '3',
+			rows: [{ id: 'todo-live', title: 'rebased live' }],
+			recordScope: 'record:live',
+			live: { reset: false }
+		})
+	);
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-live', title: 'rebased live' }
+	]);
+	watch.destroy();
+});
+
+test('HTTP handoff requires shared scope and an equal-or-newer active index vector', async () => {
+	const fetches = [];
+	const subscriptions = [];
+	let liveObserver;
+	const replica = createDistributedReplica({
+		transport: {
+			fetch() {
+				let resolve;
+				const promise = new Promise((done) => {
+					resolve = done;
+				});
+				fetches.push({ resolve });
+				return promise;
+			},
+			subscribe(request, observer) {
+				subscriptions.push(request);
+				liveObserver = observer;
+				return () => {};
+			}
+		}
+	});
+	write(replica, {
+		position: '5',
+		rows: [{ id: 'todo-query', title: 'query five' }],
+		recordScope: 'record:query'
+	});
+	const watch = replica.watch(Todos, {}, { live: true });
+	liveObserver.next(
+		wireFrame({
+			operation: 'live:todos',
+			position: '10',
+			rows: [{ id: 'todo-live', title: 'live ten' }],
+			recordScope: 'record:live',
+			live: { reset: true }
+		})
+	);
+
+	const lagging = watch.refresh();
+	await Promise.resolve();
+	fetches[0].resolve(
+		wireFrame({
+			position: '9',
+			rows: [{ id: 'todo-lagging', title: 'lagging HTTP' }],
+			recordScope: 'record:lagging'
+		})
+	);
+	await lagging;
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-live', title: 'live ten' }
+	]);
+	assert.equal(subscriptions.length, 1);
+
+	const incomparable = watch.refresh();
+	await Promise.resolve();
+	fetches[1].resolve(
+		wireFrame({
+			position: '11',
+			snapshotScope: 'snapshot:other',
+			indexScope: 'index:other',
+			rows: [{ id: 'todo-other', title: 'incomparable HTTP' }],
+			recordScope: 'record:other'
+		})
+	);
+	await incomparable;
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-live', title: 'live ten' }
+	]);
+	assert.equal(subscriptions.length, 1);
+
+	const newer = watch.refresh();
+	await Promise.resolve();
+	fetches[2].resolve(
+		wireFrame({
+			position: '11',
+			rows: [{ id: 'todo-newer', title: 'newer HTTP' }],
+			recordScope: 'record:newer'
+		})
+	);
+	await newer;
+	assert.deepEqual(replica.read(Todos, {}).data.todos, [
+		{ id: 'todo-newer', title: 'newer HTTP' }
+	]);
+	assert.equal(subscriptions.length, 2);
+	watch.destroy();
+});
+
+test('scope and schema generations purge old state before accepting fresh evidence', () => {
+	const replica = createDistributedReplica();
+	write(replica, {
+		rows: [{ id: 'todo-1', title: 'scope a' }],
+		recordScope: 'record:a'
+	});
+	write(replica, {
+		cacheScope: 'cache:b',
+		rows: [{ id: 'todo-1', title: 'scope b' }],
+		recordScope: 'record:b'
+	});
+	assert.equal(replica.read(Todos, {}).data.todos[0].title, 'scope b');
+
+	assert.throws(
+		() =>
+			write(replica, {
+				schemaHash: 'schema-tampered',
+				cacheScope: 'cache:b',
+				rows: [{ id: 'todo-1', title: 'wrong schema' }]
+			}),
+		DistributedProtocolError
+	);
+	assert.equal(replica.read(Todos, {}).complete, false);
+});
+
+test('protocol-bound artifacts reject results without a v1 envelope', () => {
+	const replica = createDistributedReplica();
+	assert.throws(
+		() =>
+			replica.writeResult(
+				Todos,
+				{},
+				{
+					data: { todos: [{ id: 'todo-1', title: 'unscoped' }] },
+					revision: '99'
+				},
+				'network'
+			),
+		(error) =>
+			error instanceof DistributedProtocolError &&
+			error.path === 'extensions.distributed'
+	);
+	assert.equal(replica.read(Todos, {}).complete, false);
+});
+
+test('only exact causation and expectation observations retire optimism', () => {
+	const replica = createDistributedReplica();
+	write(replica, {
+		position: '1',
+		revision: '1',
+		rows: [{ id: 'todo-1', title: 'base' }]
+	});
+	replica.createOptimisticLayer('cmd-1', (writer) => {
+		writer.writeRecord(Todo, 'todo-1', {
+			fields: { title: 'optimistic' }
+		});
+	});
+	replica.markOptimisticLayerAccepted('cmd-1', commandMetadata());
+
+	write(replica, {
+		position: '2',
+		revision: '2',
+		rows: [{ id: 'todo-1', title: 'server before observation' }],
+		observations: [
+			{
+				causationId: 'cause-1',
+				projection: 'todos-projector',
+				model: 'TodoView',
+				scopeToken: 'expect:other-record'
+			}
+		]
+	});
+	assert.equal(replica.read(Todos, {}).data.todos[0].title, 'optimistic');
+
+	write(replica, {
+		position: '3',
+		revision: '3',
+		rows: [{ id: 'todo-1', title: 'projected' }],
+		observations: [
+			{
+				causationId: 'cause-1',
+				projection: 'todos-projector',
+				model: 'TodoView',
+				scopeToken: 'expect:todo-1'
+			}
+		]
+	});
+	assert.equal(replica.read(Todos, {}).data.todos[0].title, 'projected');
+});
+
+test('discarded or incomplete snapshots cannot use observations to retire optimism', () => {
+	const replica = createDistributedReplica();
+	write(replica, {
+		position: '1',
+		revision: '1',
+		rows: [{ id: 'todo-1', title: 'base' }]
+	});
+	replica.createOptimisticLayer('cmd-1', (writer) => {
+		writer.writeRecord(Todo, 'todo-1', {
+			fields: { title: 'optimistic' }
+		});
+	});
+	replica.markOptimisticLayerAccepted('cmd-1', commandMetadata());
+	const observation = [
+		{
+			causationId: 'cause-1',
+			projection: 'todos-projector',
+			model: 'TodoView',
+			scopeToken: 'expect:todo-1'
+		}
+	];
+
+	write(replica, {
+		position: '2',
+		revision: '2',
+		snapshotScope: 'snapshot:incomparable',
+		indexScope: 'index:incomparable',
+		rows: [{ id: 'todo-1', title: 'incomparable base' }],
+		command: commandMetadata({ observations: observation })
+	});
+	write(replica, {
+		position: '3',
+		revision: '3',
+		snapshotScope: 'snapshot:incomparable',
+		indexScope: 'index:incomparable',
+		rows: [{ id: 'todo-1', title: 'canonical after discard' }]
+	});
+	assert.equal(
+		replica.read(Todos, {}).data.todos[0].title,
+		'canonical after discard'
+	);
+
+	replica.createOptimisticLayer('cmd-2', (writer) => {
+		writer.writeRecord(Todo, 'todo-1', {
+			fields: { title: 'optimistic incomplete' }
+		});
+	});
+	const secondReceipt = commandMetadata({
+		commandId: 'cmd-2',
+		causationId: 'cause-2'
+	});
+	replica.markOptimisticLayerAccepted('cmd-2', secondReceipt);
+	const secondObservation = [
+		{
+			causationId: 'cause-2',
+			projection: 'todos-projector',
+			model: 'TodoView',
+			scopeToken: 'expect:todo-1'
+		}
+	];
+
+	write(replica, {
+		position: '4',
+		revision: '4',
+		recordsComplete: false,
+		indexesComparable: false,
+		rows: [{ id: 'todo-1', title: 'incomplete base' }],
+		command: commandMetadata({
+			commandId: 'cmd-2',
+			causationId: 'cause-2',
+			observations: secondObservation
+		})
+	});
+	assert.throws(
+		() => replica.createOptimisticLayer('cmd-2', () => {}),
+		/optimistic layer already exists/,
+		'incomplete command observation must retain its optimistic layer'
+	);
+	write(replica, {
+		position: '5',
+		revision: '5',
+		snapshotScope: 'snapshot:incomparable',
+		indexScope: 'index:incomparable',
+		rows: [{ id: 'todo-1', title: 'canonical after incomplete' }]
+	});
+	assert.equal(
+		replica.read(Todos, {}).data.todos[0].title,
+		'canonical after incomplete'
+	);
+
+	replica.createOptimisticLayer('cmd-3', (writer) => {
+		writer.writeRecord(Todo, 'todo-1', {
+			fields: { title: 'optimistic snapshot observation' }
+		});
+	});
+	replica.markOptimisticLayerAccepted(
+		'cmd-3',
+		commandMetadata({ commandId: 'cmd-3', causationId: 'cause-3' })
+	);
+	const thirdObservation = [
+		{
+			causationId: 'cause-3',
+			projection: 'todos-projector',
+			model: 'TodoView',
+			scopeToken: 'expect:todo-1'
+		}
+	];
+
+	write(replica, {
+		position: '6',
+		revision: '6',
+		recordsComplete: false,
+		indexesComparable: true,
+		rows: [{ id: 'todo-1', title: 'incomplete snapshot observation' }],
+		observations: thirdObservation
+	});
+	write(replica, {
+		position: '7',
+		revision: '7',
+		snapshotScope: 'snapshot:incomparable',
+		indexScope: 'index:incomparable',
+		rows: [{ id: 'todo-1', title: 'clean without observation' }]
+	});
+	assert.equal(
+		replica.read(Todos, {}).data.todos[0].title,
+		'optimistic snapshot observation'
+	);
+	write(replica, {
+		position: '8',
+		revision: '8',
+		snapshotScope: 'snapshot:incomparable',
+		indexScope: 'index:incomparable',
+		rows: [{ id: 'todo-1', title: 'canonical base' }],
+		observations: thirdObservation
+	});
+	assert.equal(replica.read(Todos, {}).data.todos[0].title, 'canonical base');
+});
+
+test('pathless upserts advance the global fence without certifying stale fields', () => {
+	const replica = createDistributedReplica();
+	write(replica, {
+		position: '1',
+		revision: '1',
+		rows: [{ id: 'todo-1', title: 'cached one' }]
+	});
+
+	for (const revision of ['2', '3']) {
+		write(replica, {
+			position: revision,
+			recordsComplete: false,
+			indexesComparable: false,
+			rows: [],
+			records: [
+				{
+					model: 'TodoView',
+					scopeToken: 'record:todo-1',
+					incarnation: '1',
+					revision,
+					tombstone: false
+				}
+			]
+		});
+		assert.equal(replica.inspectRecord(Todo, 'todo-1'), undefined);
+	}
+
+	write(
+		replica,
+		{
+			operation: 'query:todos-other',
+			position: '2',
+			revision: '2',
+			rows: [{ id: 'todo-1', title: 'late other operation' }]
+		},
+		'network',
+		TodosOtherOperation
+	);
+	assert.equal(replica.inspectRecord(Todo, 'todo-1'), undefined);
+});
+
+test('an unseen pathless delete fences delayed identity discovery until recreation', () => {
+	const replica = createDistributedReplica();
+	write(replica, {
+		position: '9',
+		recordsComplete: false,
+		indexesComparable: false,
+		rows: [],
+		records: [
+			{
+				model: 'TodoView',
+				scopeToken: 'record:unseen',
+				incarnation: '1',
+				revision: '9',
+				tombstone: true
+			}
+		]
+	});
+
+	write(
+		replica,
+		{
+			operation: 'query:todos-other',
+			position: '1',
+			incarnation: '1',
+			revision: '1',
+			recordScope: 'record:unseen',
+			rows: [{ id: 'todo-unseen', title: 'delayed before delete' }]
+		},
+		'network',
+		TodosOtherOperation
+	);
+	assert.equal(replica.inspectRecord(Todo, 'todo-unseen'), undefined);
+	assert.equal(replica.read(TodosOtherOperation, {}).complete, false);
+
+	write(
+		replica,
+		{
+			operation: 'query:todos-other',
+			position: '2',
+			incarnation: '2',
+			revision: '1',
+			recordScope: 'record:unseen',
+			rows: [{ id: 'todo-unseen', title: 'recreated' }]
+		},
+		'network',
+		TodosOtherOperation
+	);
+	assert.equal(
+		replica.read(TodosOtherOperation, {}).data.todos[0].title,
+		'recreated'
+	);
+	assert.equal(replica.inspectRecord(Todo, 'todo-unseen').incarnation, '2');
+	assert.equal(replica.inspectRecord(Todo, 'todo-unseen').revision, '1');
+});
+
+test('anonymous pathless clock capacity fails closed without evicting retained fences', () => {
+	const replica = createDistributedReplica();
+	write(replica, {
+		position: '1',
+		recordsComplete: false,
+		indexesComparable: false,
+		rows: [],
+		records: Array.from({ length: 4_096 }, (_, index) => ({
+			model: 'TodoView',
+			scopeToken: `record:anonymous:${index}`,
+			incarnation: '1',
+			revision: '1',
+			tombstone: true
+		}))
+	});
+
+	assert.throws(
+		() =>
+			write(replica, {
+				position: '2',
+				recordsComplete: false,
+				indexesComparable: false,
+				rows: [],
+				records: [
+					{
+						model: 'TodoView',
+						scopeToken: 'record:anonymous:overflow',
+						incarnation: '1',
+						revision: '2',
+						tombstone: true
+					}
+				]
+			}),
+		(error) =>
+			error instanceof DistributedProtocolError &&
+			error.path.endsWith('.records.capacity')
+	);
+
+	write(
+		replica,
+		{
+			operation: 'query:todos-other',
+			position: '1',
+			incarnation: '1',
+			revision: '0',
+			recordScope: 'record:anonymous:0',
+			rows: [{ id: 'todo-delayed', title: 'must stay deleted' }]
+		},
+		'network',
+		TodosOtherOperation
+	);
+	assert.equal(replica.inspectRecord(Todo, 'todo-delayed'), undefined);
+});
+
+test('pathless delete and recreation handle reset revisions and duplicate final evidence', () => {
+	const replica = createDistributedReplica();
+	write(replica, {
+		position: '1',
+		revision: '1',
+		rows: [{ id: 'todo-1', title: 'first lifecycle' }]
+	});
+	write(replica, {
+		position: '9',
+		recordsComplete: false,
+		indexesComparable: false,
+		rows: [],
+		records: [
+			{
+				model: 'TodoView',
+				scopeToken: 'record:todo-1',
+				incarnation: '1',
+				revision: '9',
+				tombstone: true
+			}
+		]
+	});
+	assert.equal(replica.inspectRecord(Todo, 'todo-1'), undefined);
+
+	write(replica, {
+		position: '10',
+		recordsComplete: false,
+		indexesComparable: false,
+		rows: [],
+		records: [
+			{
+				model: 'TodoView',
+				scopeToken: 'record:todo-1',
+				incarnation: '2',
+				revision: '1',
+				tombstone: false
+			}
+		]
+	});
+	write(replica, {
+		position: '11',
+		incarnation: '2',
+		revision: '1',
+		rows: [{ id: 'todo-1', title: 'second lifecycle' }],
+		records: [
+			{
+				path: ['todos', '0'],
+				model: 'TodoView',
+				scopeToken: 'record:todo-1',
+				incarnation: '2',
+				revision: '1',
+				tombstone: false
+			},
+			{
+				model: 'TodoView',
+				scopeToken: 'record:todo-1',
+				incarnation: '2',
+				revision: '1',
+				tombstone: false
+			}
+		]
+	});
+	assert.equal(
+		replica.read(Todos, {}).data.todos[0].title,
+		'second lifecycle'
+	);
+	assert.equal(replica.inspectRecord(Todo, 'todo-1').incarnation, '2');
+	assert.equal(replica.inspectRecord(Todo, 'todo-1').revision, '1');
+});
+
+test('replica transport resumes from the latest server-issued cursor', () => {
+	const subscriptions = [];
+	const replica = createDistributedReplica({
+		transport: {
+			async fetch() {
+				throw new Error('complete cache must not refetch');
+			},
+			subscribe(request) {
+				subscriptions.push(request);
+				return () => {};
+			}
+		}
+	});
+	write(replica, {
+		position: '7',
+		resumeToken: 'resume:latest',
+		rows: [{ id: 'todo-1', title: 'cached' }]
+	});
+	const watch = replica.watch(Todos, {}, { live: true });
+	assert.equal(subscriptions.length, 1);
+	assert.deepEqual(subscriptions[0].resume, [
+		{
+			projection: 'todos-projector',
+			position: '7',
+			token: 'resume:latest'
+		}
+	]);
+	watch.destroy();
+});
+
+test('protocol record scopes remain opaque and never become replica identities', () => {
+	const replica = createDistributedReplica();
+	write(replica, {
+		recordScope: 'opaque:tenant/key/partition',
+		rows: [{ id: 'public-id', title: 'visible' }]
+	});
+	assert.equal(
+		replica.inspectRecord(Todo, 'public-id').key,
+		replicaRecordKey(Todo, 'public-id')
+	);
+	assert.equal(
+		replica.inspectRecord(Todo, 'opaque:tenant/key/partition'),
+		undefined
+	);
+});
diff --git a/js/tests/replica-query-plan-corpus.test.mjs b/js/tests/replica-query-plan-corpus.test.mjs
new file mode 100644
index 00000000..5a00d0b9
--- /dev/null
+++ b/js/tests/replica-query-plan-corpus.test.mjs
@@ -0,0 +1,88 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import test from 'node:test';
+
+import {
+	compareReplicaOrder,
+	evaluateReplicaFilter
+} from '../dist/replica/index.js';
+
+const corpus = JSON.parse(
+	await readFile(
+		new URL('../../tests/fixtures/client-query-plan-corpus.json', import.meta.url),
+		'utf8'
+	)
+);
+
+const literal = (value) => Object.freeze({ kind: 'literal', value });
+const field = (name, scalar, codec) =>
+	Object.freeze({
+		field: name,
+		scalar,
+		codec,
+		nullable: false,
+		operators: Object.freeze([
+			'_eq',
+			'_neq',
+			'_gt',
+			'_gte',
+			'_lt',
+			'_lte',
+			'_in',
+			'_nin',
+			'_is_null'
+		])
+	});
+const fields = Object.freeze([
+	field('id', 'ID', 'string'),
+	field('priority', 'BigInt', 'json_number_precision_limited'),
+	field('completed', 'Boolean', 'boolean')
+]);
+
+test('portable query plans match the shared SQLite server corpus', () => {
+	for (const entry of corpus.cases) {
+		const filter = Object.freeze({
+			input: literal(entry.where),
+			fields,
+			relationships: Object.freeze([]),
+			rowPolicy: Object.freeze({ kind: 'unrestricted' })
+		});
+		const order = Object.freeze({
+			input: literal(entry.orderBy),
+			fields: Object.freeze(
+				fields.map(({ field, scalar, codec, nullable }) => ({
+					field,
+					scalar,
+					codec,
+					nullable
+				}))
+			),
+			tieBreakers: Object.freeze([
+				Object.freeze({
+					field: 'id',
+					scalar: 'ID',
+					codec: 'string',
+					nullable: false
+				})
+			])
+		});
+		const matched = corpus.records.filter((record) => {
+			const evaluation = evaluateReplicaFilter(filter, record);
+			assert.notEqual(evaluation.result, 'unknown', entry.name);
+			return evaluation.result === 'match';
+		});
+		matched.sort((left, right) => {
+			const comparison = compareReplicaOrder(order, left, right);
+			assert.notEqual(comparison.result, 'unknown', entry.name);
+			return comparison.result === 'less'
+				? -1
+				: comparison.result === 'greater'
+					? 1
+					: 0;
+		});
+		const actual = matched
+			.slice(entry.offset, entry.offset + entry.limit)
+			.map((record) => record.id);
+		assert.deepEqual(actual, entry.expected, entry.name);
+	}
+});
diff --git a/js/tests/replica-query-plan.test.mjs b/js/tests/replica-query-plan.test.mjs
new file mode 100644
index 00000000..409650d6
--- /dev/null
+++ b/js/tests/replica-query-plan.test.mjs
@@ -0,0 +1,1286 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	compareReplicaOrder,
+	decideReplicaPaginationMaintenance,
+	evaluateReplicaFilter
+} from '../dist/replica/index.js';
+import { resolveArguments } from '../dist/replica/identity.js';
+
+const FILTER_FIELDS = Object.freeze([
+	Object.freeze({
+		field: 'id',
+		scalar: 'ID',
+		codec: 'string',
+		nullable: false,
+		operators: Object.freeze(['_eq', '_neq', '_in', '_nin'])
+	}),
+	Object.freeze({
+		field: 'priority',
+		scalar: 'Int',
+		codec: 'int32',
+		nullable: true,
+		operators: Object.freeze([
+			'_eq',
+			'_neq',
+			'_gt',
+			'_gte',
+			'_lt',
+			'_lte',
+			'_in',
+			'_nin',
+			'_is_null'
+		])
+	}),
+	Object.freeze({
+		field: 'active',
+		scalar: 'Boolean',
+		codec: 'boolean',
+		nullable: false,
+		operators: Object.freeze(['_eq', '_neq'])
+	}),
+	Object.freeze({
+		field: 'title',
+		scalar: 'String',
+		codec: 'string',
+		nullable: true,
+		operators: Object.freeze([
+			'_eq',
+			'_neq',
+			'_gt',
+			'_in',
+			'_nin',
+			'_like',
+			'_ilike'
+		])
+	}),
+	Object.freeze({
+		field: 'payload',
+		scalar: 'JSON',
+		codec: 'json',
+		nullable: true,
+		operators: Object.freeze(['_eq', '_contains'])
+	})
+]);
+
+const OWNER_RELATIONSHIP = Object.freeze({
+	field: 'owner',
+	targetModel: 'User',
+	kind: 'belongs_to',
+	keyMapping: Object.freeze({
+		kind: 'direct',
+		local: Object.freeze(['ownerId']),
+		remote: Object.freeze(['id'])
+	}),
+	maintenance: 'local',
+	dependencies: Object.freeze(['todo_rows', 'user_rows'])
+});
+
+function literal(value) {
+	return Object.freeze({ kind: 'literal', value: Object.freeze(value) });
+}
+
+function filterArtifact(
+	input,
+	rowPolicy = Object.freeze({ kind: 'unrestricted' }),
+	relationships = Object.freeze([OWNER_RELATIONSHIP])
+) {
+	return Object.freeze({
+		...(input === undefined ? {} : { input }),
+		fields: FILTER_FIELDS,
+		relationships,
+		rowPolicy
+	});
+}
+
+function result(value) {
+	return value.result;
+}
+
+test('caller where uses SQL three-valued boolean composition', () => {
+	const record = { id: 'todo-1', priority: 3, active: true, title: 'one', payload: null };
+	const falseDominatesUnknown = filterArtifact(
+		literal({
+			_and: [
+				{ priority: { _eq: null } },
+				{ active: { _eq: false } }
+			]
+		})
+	);
+	assert.equal(result(evaluateReplicaFilter(falseDominatesUnknown, record)), 'no_match');
+
+	const trueDominatesUnknown = filterArtifact(
+		literal({
+			_or: [
+				{ priority: { _eq: null } },
+				{ active: { _eq: true } }
+			]
+		})
+	);
+	assert.equal(result(evaluateReplicaFilter(trueDominatesUnknown, record)), 'match');
+
+	const stillUnknown = filterArtifact(
+		literal({ _not: { priority: { _eq: null } } })
+	);
+	assert.deepEqual(evaluateReplicaFilter(stillUnknown, record), {
+		result: 'unknown',
+		reason: {
+			code: 'sql_null',
+			path: ['where', '_not', 'priority', '_eq'],
+			message: 'SQL comparison with null is unknown'
+		}
+	});
+});
+
+test('caller and row-policy empty boolean lists preserve their distinct server semantics', () => {
+	const record = { id: 'todo-1', priority: 3, active: true, title: 'one', payload: null };
+	assert.equal(
+		result(evaluateReplicaFilter(filterArtifact(literal({ _and: [] })), record)),
+		'match'
+	);
+	assert.equal(
+		result(evaluateReplicaFilter(filterArtifact(literal({ _or: [] })), record)),
+		'match'
+	);
+	assert.equal(
+		result(
+			evaluateReplicaFilter(
+				filterArtifact(undefined, {
+					kind: 'predicate',
+					expression: { kind: 'and', value: [] }
+				}),
+				record
+			)
+		),
+		'match'
+	);
+	assert.equal(
+		result(
+			evaluateReplicaFilter(
+				filterArtifact(undefined, {
+					kind: 'predicate',
+					expression: { kind: 'or', value: [] }
+				}),
+				record
+			)
+		),
+		'no_match'
+	);
+});
+
+test('portable scalar filters handle numeric comparisons and exact SQL IN null behavior', () => {
+	const base = { id: 'todo-1', priority: 3, active: true, title: 'one', payload: null };
+	assert.equal(
+		result(
+			evaluateReplicaFilter(
+				filterArtifact(literal({ priority: { _gte: 3, _lt: 4 } })),
+				base
+			)
+		),
+		'match'
+	);
+	assert.equal(
+		result(
+			evaluateReplicaFilter(
+				filterArtifact(literal({ priority: { _in: [] } })),
+				{ ...base, priority: null }
+			)
+		),
+		'no_match'
+	);
+	assert.equal(
+		result(
+			evaluateReplicaFilter(
+				filterArtifact(literal({ priority: { _nin: [] } })),
+				{ ...base, priority: null }
+			)
+		),
+		'match'
+	);
+	assert.equal(
+		result(
+			evaluateReplicaFilter(
+				filterArtifact(literal({ priority: { _in: [3, null] } })),
+				base
+			)
+		),
+		'match'
+	);
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(literal({ priority: { _in: [2, null] } })),
+			base
+		).reason.code,
+		'sql_null'
+	);
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(literal({ priority: { _nin: [2, null] } })),
+			base
+		).reason.code,
+		'sql_null'
+	);
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(literal({ priority: { _in: ['bad', 3] } })),
+			base
+		).reason.code,
+		'invalid_filter_value'
+	);
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(literal({ priority: { _nin: ['bad', 2] } })),
+			base
+		).reason.code,
+		'invalid_filter_value'
+	);
+});
+
+test('BigInt plans compare only JavaScript-safe integer values', () => {
+	const bigintField = Object.freeze({
+		field: 'sequence',
+		scalar: 'BigInt',
+		codec: 'json_number_precision_limited',
+		nullable: false,
+		operators: Object.freeze(['_eq', '_gt', '_gte', '_lt', '_lte', '_in'])
+	});
+	const artifact = Object.freeze({
+		input: literal({ sequence: { _gte: 9_007_199_254_740_990 } }),
+		fields: Object.freeze([bigintField]),
+		relationships: Object.freeze([]),
+		rowPolicy: Object.freeze({ kind: 'unrestricted' })
+	});
+	assert.equal(
+		evaluateReplicaFilter(artifact, {
+			sequence: 9_007_199_254_740_991
+		}).result,
+		'match'
+	);
+	assert.equal(
+		evaluateReplicaFilter(artifact, {
+			sequence: 9_007_199_254_740_992
+		}).reason.code,
+		'invalid_filter_value'
+	);
+
+	const order = Object.freeze({
+		input: literal([{ sequence: 'asc' }]),
+		fields: Object.freeze([bigintField]),
+		tieBreakers: Object.freeze([
+			Object.freeze({
+				field: 'id',
+				scalar: 'ID',
+				codec: 'string',
+				nullable: false
+			})
+		])
+	});
+	assert.equal(
+		compareReplicaOrder(
+			order,
+			{ id: 'same', sequence: 9_007_199_254_740_990 },
+			{ id: 'same', sequence: 9_007_199_254_740_991 }
+		).result,
+		'less'
+	);
+});
+
+test('unequal string equality and IN require a collation contract', () => {
+	const base = {
+		id: 'todo-1',
+		priority: 3,
+		active: true,
+		title: 'one',
+		payload: null
+	};
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(literal({ title: { _eq: 'one' } })),
+			base
+		).result,
+		'match'
+	);
+	for (const where of [
+		{ title: { _eq: 'ONE' } },
+		{ title: { _neq: 'ONE' } },
+		{ title: { _in: ['ONE'] } },
+		{ title: { _nin: ['ONE'] } }
+	]) {
+		assert.equal(
+			evaluateReplicaFilter(filterArtifact(literal(where)), base).reason.code,
+			'collation_not_portable'
+		);
+	}
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(literal({ title: { _in: ['ONE', 'one'] } })),
+			base
+		).result,
+		'match'
+	);
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(literal({ title: { _nin: ['ONE', 'one'] } })),
+			base
+		).result,
+		'no_match'
+	);
+});
+
+test('query-plan artifacts require exact scalar-codec pairs', () => {
+	const invalidFilter = Object.freeze({
+		...filterArtifact(literal({ active: { _eq: true } })),
+		fields: Object.freeze([
+			Object.freeze({
+				...FILTER_FIELDS[2],
+				scalar: 'String',
+				codec: 'boolean'
+			})
+		])
+	});
+	assert.equal(
+		evaluateReplicaFilter(invalidFilter, { active: true }).reason.code,
+		'invalid_artifact'
+	);
+	const invalidOperator = Object.freeze({
+		...filterArtifact(literal({ active: { _like: 't%' } })),
+		fields: Object.freeze([
+			Object.freeze({
+				...FILTER_FIELDS[2],
+				operators: Object.freeze(['_like'])
+			})
+		])
+	});
+	assert.equal(
+		evaluateReplicaFilter(invalidOperator, { active: true }).reason.code,
+		'invalid_artifact'
+	);
+
+	const invalidOrder = Object.freeze({
+		input: literal([{ priority: 'asc' }]),
+		fields: Object.freeze([
+			Object.freeze({
+				field: 'priority',
+				scalar: 'BigInt',
+				codec: 'int32',
+				nullable: false
+			})
+		]),
+		tieBreakers: Object.freeze([
+			Object.freeze({
+				field: 'id',
+				scalar: 'ID',
+				codec: 'string'
+			})
+		])
+	});
+	assert.equal(
+		compareReplicaOrder(
+			invalidOrder,
+			{ id: 'one', priority: 1 },
+			{ id: 'two', priority: 2 }
+		).reason.code,
+		'invalid_artifact'
+	);
+});
+
+test('unsafe operators, codecs, and absent canonical fields explain why evaluation is unknown', () => {
+	const record = { id: 'todo-1', priority: 3, active: true, title: 'one', payload: null };
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(literal({ title: { _like: 'o%' } })),
+			record
+		).reason.code,
+		'unsupported_operator'
+	);
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(literal({ payload: { _eq: { a: 1 } } })),
+			{ ...record, payload: { a: 1 } }
+		).reason.code,
+		'unsupported_codec'
+	);
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(literal({ priority: { _eq: 3 } })),
+			{ id: 'todo-1', active: true, title: 'one', payload: null }
+		).reason.code,
+		'missing_field'
+	);
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(literal({ title: { _gt: 'a' } })),
+			record
+		).reason.code,
+		'unsupported_operator'
+	);
+});
+
+test('recursive argument sources resolve nested variables without runtime GraphQL parsing', () => {
+	const artifact = filterArtifact({
+		kind: 'object',
+		fields: {
+			_and: {
+				kind: 'list',
+				items: [
+					{
+						kind: 'object',
+						fields: {
+							priority: {
+								kind: 'object',
+								fields: {
+									_gte: { kind: 'variable', name: 'minimum' }
+								}
+							}
+						}
+					}
+				]
+			}
+		}
+	});
+	const record = { id: 'todo-1', priority: 4, active: true, title: 'one', payload: null };
+	assert.equal(result(evaluateReplicaFilter(artifact, record, { minimum: 3 })), 'match');
+	assert.equal(result(evaluateReplicaFilter(artifact, record, { minimum: 5 })), 'no_match');
+	// Missing nested variables omit their input-object field, exactly like GraphQL.
+	assert.equal(result(evaluateReplicaFilter(artifact, record, {})), 'match');
+});
+
+test('recursive argument sources preserve the same canonical cache identity inputs', () => {
+	const source = {
+		where: {
+			kind: 'object',
+			fields: {
+				priority: {
+					kind: 'object',
+					fields: {
+						_gte: { kind: 'variable', name: 'minimum' },
+						_lte: { kind: 'literal', value: 9 }
+					}
+				},
+				ids: {
+					kind: 'list',
+					items: [
+						{ kind: 'variable', name: 'firstId' },
+						{ kind: 'variable', name: 'optionalId' }
+					]
+				}
+			}
+		}
+	};
+	assert.deepEqual(resolveArguments(source, { minimum: 3, firstId: 'one' }), {
+		where: {
+			ids: ['one', null],
+			priority: { _gte: 3, _lte: 9 }
+		}
+	});
+	assert.deepEqual(resolveArguments(source, { firstId: 'one' }), {
+		where: {
+			ids: ['one', null],
+			priority: { _lte: 9 }
+		}
+	});
+});
+
+test('row policies are conjoined and never read ambient claims', () => {
+	const record = { id: 'todo-1', priority: 3, active: true, title: 'one', payload: null };
+	const policy = {
+		kind: 'predicate',
+		expression: {
+			kind: 'cmp',
+			value: {
+				column: 'active',
+				op: 'eq',
+				rhs: { kind: 'lit', value: { kind: 'bool', value: true } }
+			}
+		}
+	};
+	assert.equal(
+		result(
+			evaluateReplicaFilter(
+				filterArtifact(literal({ priority: { _gt: 2 } }), policy),
+				record
+			)
+		),
+		'match'
+	);
+	assert.equal(
+		result(
+			evaluateReplicaFilter(
+				filterArtifact(literal({ priority: { _gt: 4 } }), policy),
+				record
+			)
+		),
+		'no_match'
+	);
+
+	const claimPolicy = {
+		kind: 'predicate',
+		expression: {
+			kind: 'cmp',
+			value: {
+				column: 'priority',
+				op: 'eq',
+				rhs: {
+					kind: 'claim',
+					value: { header: 'x-distributed-priority' }
+				}
+			}
+		}
+	};
+	assert.equal(
+		evaluateReplicaFilter(filterArtifact(undefined, claimPolicy), record).reason.code,
+		'claim_operand'
+	);
+	const descriptor = Object.freeze({
+		name: 'x-distributed-priority',
+		codec: 'int32'
+	});
+	const scoped = (value) =>
+		Object.freeze({
+			trustedPresets: Object.freeze({
+				descriptors: Object.freeze([descriptor]),
+				values: Object.freeze([
+					Object.freeze({
+						...descriptor,
+						value
+					})
+				])
+			})
+		});
+	assert.equal(
+		result(
+			evaluateReplicaFilter(
+				filterArtifact(undefined, claimPolicy),
+				record,
+				{},
+				scoped(3)
+			)
+		),
+		'match'
+	);
+	assert.equal(
+		result(
+			evaluateReplicaFilter(
+				filterArtifact(undefined, claimPolicy),
+				record,
+				{},
+				scoped(4)
+			)
+		),
+		'no_match'
+	);
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(undefined, claimPolicy),
+			record,
+			{},
+			{
+				trustedPresets: {
+					descriptors: [descriptor],
+					values: []
+				}
+			}
+		).reason.code,
+		'claim_inventory'
+	);
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(undefined, claimPolicy),
+			record,
+			{},
+			{
+				trustedPresets: {
+					descriptors: [descriptor],
+					values: [
+						{ ...descriptor, value: 3 },
+						{ name: 'x-forged-extra', codec: 'string', value: 'forged' }
+					]
+				}
+			}
+		).reason.code,
+		'claim_inventory'
+	);
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(undefined, claimPolicy),
+			record,
+			{},
+			{
+				trustedPresets: {
+					descriptors: [descriptor],
+					values: [
+						{
+							name: descriptor.name,
+							codec: 'string',
+							value: '3'
+						}
+					]
+				}
+			}
+		).reason.code,
+		'claim_inventory'
+	);
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(undefined, { kind: 'server_only' }),
+			record
+		).reason.code,
+		'server_only_policy'
+	);
+});
+
+test('row-policy literal tags are checked before comparison', () => {
+	const record = {
+		id: 'todo-1',
+		priority: 3,
+		active: true,
+		title: 'one',
+		payload: { tenant: true }
+	};
+	const jsonAgainstString = {
+		kind: 'predicate',
+		expression: {
+			kind: 'cmp',
+			value: {
+				column: 'title',
+				op: 'eq',
+				rhs: { kind: 'lit', value: { kind: 'json', value: 'one' } }
+			}
+		}
+	};
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(undefined, jsonAgainstString),
+			record
+		).reason.code,
+		'invalid_artifact'
+	);
+
+	const jsonHasKey = {
+		kind: 'predicate',
+		expression: {
+			kind: 'cmp',
+			value: {
+				column: 'payload',
+				op: 'has_key',
+				rhs: { kind: 'lit', value: { kind: 'string', value: 'tenant' } }
+			}
+		}
+	};
+	assert.equal(
+		evaluateReplicaFilter(filterArtifact(undefined, jsonHasKey), record).reason.code,
+		'unsupported_operator'
+	);
+
+	const floatFromInteger = Object.freeze({
+		fields: Object.freeze([
+			Object.freeze({
+				field: 'score',
+				scalar: 'Float',
+				codec: 'float64',
+				nullable: false,
+				operators: Object.freeze(['_gt'])
+			})
+		]),
+		relationships: Object.freeze([]),
+		rowPolicy: Object.freeze({
+			kind: 'predicate',
+			expression: Object.freeze({
+				kind: 'cmp',
+				value: Object.freeze({
+					column: 'score',
+					op: 'gt',
+					rhs: Object.freeze({
+						kind: 'lit',
+						value: Object.freeze({ kind: 'i64', value: 1 })
+					})
+				})
+			})
+		})
+	});
+	assert.equal(
+		evaluateReplicaFilter(floatFromInteger, { score: 1.5 }).result,
+		'match'
+	);
+});
+
+test('malformed row-policy booleans fail closed', () => {
+	const record = {
+		id: 'todo-1',
+		priority: 3,
+		active: true,
+		title: 'one',
+		payload: null
+	};
+	const invalidIsNull = {
+		kind: 'predicate',
+		expression: {
+			kind: 'is_null',
+			value: { column: 'priority', is_null: 'yes' }
+		}
+	};
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(undefined, invalidIsNull),
+			record
+		).reason.code,
+		'invalid_artifact'
+	);
+
+	const invalidNegated = {
+		kind: 'predicate',
+		expression: {
+			kind: 'in',
+			value: {
+				column: 'priority',
+				values: [{ kind: 'lit', value: { kind: 'i64', value: 3 } }],
+				negated: 'false'
+			}
+		}
+	};
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(undefined, invalidNegated),
+			record
+		).reason.code,
+		'invalid_artifact'
+	);
+});
+
+test('relationship predicates require an explicit resolver carrying target-policy semantics', () => {
+	const artifact = filterArtifact(literal({ owner: { id: { _eq: 'user-1' } } }));
+	const record = { id: 'todo-1', priority: 3, active: true, title: 'one', payload: null };
+	assert.equal(
+		evaluateReplicaFilter(artifact, record).reason.code,
+		'relationship_resolver_required'
+	);
+	let request;
+	const evaluated = evaluateReplicaFilter(artifact, record, {}, {
+		resolveRelationship(value) {
+			request = value;
+			return { result: 'match' };
+		}
+	});
+	assert.equal(evaluated.result, 'match');
+	assert.equal(request.source, 'caller');
+	assert.deepEqual(request.relationship, OWNER_RELATIONSHIP);
+	assert.deepEqual(request.predicate, { id: { _eq: 'user-1' } });
+});
+
+test('relationship resolvers receive exact direct, belongs-to, has-many, m2m, and opaque plans', () => {
+	const relationships = Object.freeze([
+		OWNER_RELATIONSHIP,
+		Object.freeze({
+			field: 'children',
+			targetModel: 'Todo',
+			kind: 'has_many',
+			keyMapping: Object.freeze({
+				kind: 'direct',
+				local: Object.freeze(['id']),
+				remote: Object.freeze(['parentId'])
+			}),
+			maintenance: 'local',
+			dependencies: Object.freeze(['todo_rows'])
+		}),
+		Object.freeze({
+			field: 'members',
+			targetModel: 'User',
+			kind: 'many_to_many',
+			keyMapping: Object.freeze({
+				kind: 'through',
+				local: Object.freeze(['id']),
+				remote: Object.freeze(['id']),
+				table: 'todo_members',
+				sourceForeignKey: 'todo_id',
+				targetForeignKey: 'user_id'
+			}),
+			maintenance: 'local',
+			dependencies: Object.freeze(['todo_members', 'todo_rows', 'user_rows'])
+		}),
+		Object.freeze({
+			field: 'opaqueMembers',
+			targetModel: 'User',
+			kind: 'many_to_many',
+			keyMapping: Object.freeze({
+				kind: 'through_opaque',
+				local: Object.freeze(['id']),
+				remote: Object.freeze(['id']),
+				dependency: 'private_membership'
+			}),
+			maintenance: 'revalidate',
+			dependencies: Object.freeze([
+				'private_membership',
+				'todo_rows',
+				'user_rows'
+			])
+		}),
+		Object.freeze({
+			field: 'embeddedOwner',
+			targetModel: 'User',
+			kind: 'belongs_to',
+			keyMapping: Object.freeze({ kind: 'embedded' }),
+			maintenance: 'revalidate',
+			dependencies: Object.freeze(['todo_rows', 'user_rows'])
+		})
+	]);
+	const record = {
+		id: 'todo-1',
+		priority: 3,
+		active: true,
+		title: 'one',
+		payload: null
+	};
+	for (const expected of relationships) {
+		let request;
+		const evaluated = evaluateReplicaFilter(
+			filterArtifact(
+				literal({ [expected.field]: { id: { _eq: 'target-1' } } }),
+				Object.freeze({ kind: 'unrestricted' }),
+				relationships
+			),
+			record,
+			{},
+			{
+				resolveRelationship(value) {
+					request = value;
+					return { result: 'match' };
+				}
+			}
+		);
+		assert.equal(evaluated.result, 'match');
+		assert.deepEqual(request.relationship, expected);
+		assert.equal(Object.isFrozen(request.relationship), true);
+		assert.equal(Object.isFrozen(request.relationship.dependencies), true);
+	}
+});
+
+test('relationship descriptors fail closed when maintenance or key facts are forged', () => {
+	const record = {
+		id: 'todo-1',
+		priority: 3,
+		active: true,
+		title: 'one',
+		payload: null
+	};
+	const forgedOpaque = {
+		...OWNER_RELATIONSHIP,
+		keyMapping: {
+			kind: 'through_opaque',
+			local: ['ownerId'],
+			remote: ['id'],
+			dependency: 'private_membership'
+		},
+		maintenance: 'local',
+		dependencies: ['private_membership', 'todo_rows', 'user_rows']
+	};
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(
+				literal({ owner: { id: { _eq: 'user-1' } } }),
+				Object.freeze({ kind: 'unrestricted' }),
+				[forgedOpaque]
+			),
+			record
+		).reason.code,
+		'invalid_artifact'
+	);
+
+	const conservativeDirect = Object.freeze({
+		...OWNER_RELATIONSHIP,
+		maintenance: 'revalidate'
+	});
+	let request;
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(
+				literal({ owner: { id: { _eq: 'user-1' } } }),
+				Object.freeze({ kind: 'unrestricted' }),
+				[conservativeDirect]
+			),
+			record,
+			{},
+			{
+				resolveRelationship(value) {
+					request = value;
+					return { result: 'match' };
+				}
+			}
+		).result,
+		'match'
+	);
+	assert.equal(request.relationship.maintenance, 'revalidate');
+
+	const mismatchedKeys = {
+		...OWNER_RELATIONSHIP,
+		keyMapping: {
+			kind: 'direct',
+			local: ['ownerId', 'tenantId'],
+			remote: ['id']
+		}
+	};
+	assert.equal(
+		evaluateReplicaFilter(
+			filterArtifact(
+				literal({ owner: { id: { _eq: 'user-1' } } }),
+				Object.freeze({ kind: 'unrestricted' }),
+				[mismatchedKeys]
+			),
+			record
+		).reason.code,
+		'invalid_artifact'
+	);
+});
+
+const ORDER_FIELDS = Object.freeze([
+	Object.freeze({
+		field: 'priority',
+		scalar: 'Int',
+		codec: 'int32',
+		nullable: false
+	}),
+	Object.freeze({
+		field: 'score',
+		scalar: 'Float',
+		codec: 'float64',
+		nullable: true
+	}),
+	Object.freeze({
+		field: 'title',
+		scalar: 'String',
+		codec: 'string',
+		nullable: false
+	}),
+	Object.freeze({
+		field: 'payload',
+		scalar: 'JSON',
+		codec: 'json',
+		nullable: false
+	})
+]);
+
+function orderArtifact(
+	input,
+	tieBreakers = [
+		{
+			field: 'sequence',
+			scalar: 'BigInt',
+			codec: 'json_number_precision_limited',
+			nullable: false
+		}
+	]
+) {
+	return Object.freeze({
+		...(input === undefined ? {} : { input }),
+		fields: ORDER_FIELDS,
+		tieBreakers: Object.freeze(tieBreakers)
+	});
+}
+
+test('order comparison follows declared priority then exact identity tie-breakers', () => {
+	const artifact = orderArtifact({ kind: 'variable', name: 'order' });
+	const left = { priority: 3, score: 1, title: 'same', payload: {}, sequence: 2 };
+	const right = { priority: 2, score: 1, title: 'same', payload: {}, sequence: 1 };
+	assert.equal(
+		compareReplicaOrder(artifact, left, right, {
+			order: [{ priority: 'desc' }]
+		}).result,
+		'less'
+	);
+	assert.equal(
+		compareReplicaOrder(artifact, { ...left, priority: 2 }, right, {
+			order: [{ priority: 'desc' }]
+		}).result,
+		'greater'
+	);
+	assert.equal(
+		compareReplicaOrder(
+			orderArtifact(undefined),
+			{ ...left, sequence: 1 },
+			{ ...right, sequence: 2 }
+		).result,
+		'less'
+	);
+});
+
+test('order comparison validates entry shape, directions, and null placement', () => {
+	const left = { priority: 1, score: null, title: 'a', payload: {}, sequence: 1 };
+	const right = { priority: 1, score: 2, title: 'b', payload: {}, sequence: 2 };
+	assert.equal(
+		compareReplicaOrder(
+			orderArtifact(literal([{ score: 'asc_nulls_last' }])),
+			left,
+			right
+		).result,
+		'greater'
+	);
+	assert.equal(
+		compareReplicaOrder(orderArtifact(literal([{ score: 'asc' }])), left, right)
+			.reason.code,
+		'implicit_null_order'
+	);
+	assert.equal(
+		compareReplicaOrder(
+			orderArtifact(literal([{ priority: 'asc', title: 'asc' }])),
+			left,
+			right
+		).reason.code,
+		'ambiguous_order_entry'
+	);
+	assert.equal(
+		compareReplicaOrder(
+			orderArtifact(literal([{ priority: 'sideways' }])),
+			left,
+			right
+		).reason.code,
+		'invalid_order_direction'
+	);
+	assert.equal(
+		compareReplicaOrder(orderArtifact(literal([{ title: 'asc' }])), left, right)
+			.result,
+		'less'
+	);
+	assert.equal(
+		compareReplicaOrder(orderArtifact(literal([{ payload: 'asc' }])), left, right)
+			.reason.code,
+		'unsupported_codec'
+	);
+});
+
+test('string order uses unsigned UTF-8 bytes including supplementary code points', () => {
+	const order = orderArtifact(literal([{ title: 'asc' }]));
+	assert.equal(
+		compareReplicaOrder(
+			order,
+			{ title: '\u{10000}', sequence: 1 },
+			{ title: '\u{e000}', sequence: 2 }
+		).result,
+		'greater'
+	);
+	assert.equal(
+		compareReplicaOrder(
+			order,
+			{ title: 'same', sequence: 1 },
+			{ title: 'same', sequence: 2 }
+		).result,
+		'less'
+	);
+});
+
+test('tied comparisons without identity tie-breakers remain unknown', () => {
+	const noTieBreaker = orderArtifact(literal([{ priority: 'asc' }]), []);
+	const left = { priority: 1, score: 1, title: 'a', payload: {}, sequence: 1 };
+	const right = { priority: 1, score: 1, title: 'b', payload: {}, sequence: 2 };
+	assert.equal(
+		compareReplicaOrder(noTieBreaker, left, right).reason.code,
+		'invalid_artifact'
+	);
+	assert.equal(
+		compareReplicaOrder(noTieBreaker, left, { ...right, priority: 2 }).result,
+		'less'
+	);
+});
+
+test('order input supports GraphQL singleton-list coercion and recursive sources', () => {
+	const left = { priority: 1, score: 1, title: 'same', payload: {}, sequence: 1 };
+	const right = { priority: 2, score: 1, title: 'same', payload: {}, sequence: 2 };
+	assert.equal(
+		compareReplicaOrder(
+			orderArtifact({ kind: 'variable', name: 'order' }),
+			left,
+			right,
+			{ order: { priority: 'asc' } }
+		).result,
+		'less'
+	);
+	assert.equal(
+		compareReplicaOrder(
+			orderArtifact({
+				kind: 'list',
+				items: [
+					{
+						kind: 'object',
+						fields: {
+							priority: { kind: 'variable', name: 'direction' }
+						}
+					}
+				]
+			}),
+			left,
+			right,
+			{ direction: 'desc' }
+		).result,
+		'greater'
+	);
+});
+
+const COMPLETE_PAGINATION = Object.freeze({
+	kind: 'complete',
+	insert: 'local',
+	delete: 'local',
+	reorder: 'local',
+	stableUpdate: 'local'
+});
+const OFFSET_PAGINATION = Object.freeze({
+	kind: 'offset',
+	insert: 'revalidate',
+	delete: 'revalidate',
+	reorder: 'revalidate',
+	stableUpdate: 'local'
+});
+const LOCAL_OFFSET_PAGINATION = Object.freeze({
+	kind: 'offset',
+	insert: 'local',
+	delete: 'local',
+	reorder: 'local',
+	stableUpdate: 'local'
+});
+
+test('pagination plans make complete and offset maintenance decisions explicit', () => {
+	const complete = { kind: 'complete' };
+	for (const kind of ['insert', 'delete', 'reorder', 'stable_update']) {
+		assert.equal(
+			decideReplicaPaginationMaintenance(COMPLETE_PAGINATION, complete, { kind })
+				.decision,
+			'local'
+		);
+	}
+
+	const offset = { kind: 'offset', offset: 0, limit: 10, returned: 10 };
+	assert.equal(
+		decideReplicaPaginationMaintenance(OFFSET_PAGINATION, offset, {
+			kind: 'stable_update'
+		}).decision,
+		'local'
+	);
+	assert.equal(
+		decideReplicaPaginationMaintenance(OFFSET_PAGINATION, offset, {
+			kind: 'insert'
+		}).reason.code,
+		'insert_changes_offset_window'
+	);
+	assert.equal(
+		decideReplicaPaginationMaintenance(OFFSET_PAGINATION, offset, {
+			kind: 'delete'
+		}).reason.code,
+		'delete_changes_offset_window'
+	);
+	assert.equal(
+		decideReplicaPaginationMaintenance(OFFSET_PAGINATION, offset, {
+			kind: 'reorder'
+		}).reason.code,
+		'reorder_changes_offset_window'
+	);
+});
+
+test('pagination refuses unknown, mismatched, unsafe offset, and unproven cursor plans', () => {
+	assert.equal(
+		decideReplicaPaginationMaintenance(
+			OFFSET_PAGINATION,
+			{ kind: 'unknown' },
+			{ kind: 'stable_update' }
+		).reason.code,
+		'unknown_coverage'
+	);
+	assert.equal(
+		decideReplicaPaginationMaintenance(
+			OFFSET_PAGINATION,
+			{ kind: 'complete' },
+			{ kind: 'stable_update' }
+		).reason.code,
+		'coverage_mismatch'
+	);
+	assert.equal(
+		decideReplicaPaginationMaintenance(
+			LOCAL_OFFSET_PAGINATION,
+			{ kind: 'offset', offset: 0 },
+			{ kind: 'insert' }
+		).reason.code,
+		'insert_changes_offset_window'
+	);
+	assert.equal(
+		decideReplicaPaginationMaintenance(
+			{
+				kind: 'cursor',
+				insert: 'revalidate',
+				delete: 'revalidate',
+				reorder: 'revalidate',
+				stableUpdate: 'local'
+			},
+			{ kind: 'cursor', after: 'cursor-1' },
+			{ kind: 'stable_update' }
+		).reason.code,
+		'cursor_not_certified'
+	);
+	assert.equal(
+		decideReplicaPaginationMaintenance(
+			{
+				kind: 'cursor',
+				// A forged boolean is not a versioned proof IR.
+				certified: true,
+				insert: 'local',
+				delete: 'local',
+				reorder: 'local',
+				stableUpdate: 'local'
+			},
+			{ kind: 'cursor', after: 'cursor-1' },
+			{ kind: 'insert' }
+		).reason.code,
+		'cursor_not_certified'
+	);
+	assert.equal(
+		decideReplicaPaginationMaintenance(
+			{
+				kind: 'forged',
+				insert: 'local',
+				delete: 'local',
+				reorder: 'local',
+				stableUpdate: 'local'
+			},
+			{ kind: 'complete' },
+			{ kind: 'insert' }
+		).reason.code,
+		'invalid_pagination_policy'
+	);
+});
+
+test('offset locality requires a proven non-full first page', () => {
+	const safe = { kind: 'offset', offset: 0, limit: 10, returned: 9 };
+	for (const kind of ['insert', 'delete', 'reorder', 'stable_update']) {
+		assert.equal(
+			decideReplicaPaginationMaintenance(
+				LOCAL_OFFSET_PAGINATION,
+				safe,
+				{ kind }
+			).decision,
+			'local'
+		);
+	}
+
+	for (const [coverage, kind, code] of [
+		[
+			{ kind: 'offset', offset: 0, limit: 10, returned: 10 },
+			'insert',
+			'insert_changes_offset_window'
+		],
+		[
+			{ kind: 'offset', offset: 1, limit: 10, returned: 1 },
+			'delete',
+			'delete_changes_offset_window'
+		],
+		[
+			{ kind: 'offset', offset: 0, limit: 10 },
+			'reorder',
+			'reorder_changes_offset_window'
+		]
+	]) {
+		assert.equal(
+			decideReplicaPaginationMaintenance(
+				LOCAL_OFFSET_PAGINATION,
+				coverage,
+				{ kind }
+			).reason.code,
+			code
+		);
+	}
+});
diff --git a/js/tests/replica-result-observation.test.mjs b/js/tests/replica-result-observation.test.mjs
new file mode 100644
index 00000000..8e9bf591
--- /dev/null
+++ b/js/tests/replica-result-observation.test.mjs
@@ -0,0 +1,307 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	createDistributedReplica
+} from '../dist/replica/index.js';
+import {
+	replicaResultObservation
+} from '../dist/replica/command-runtime.js';
+
+const Item = Object.freeze({ id: 'Item', identityFields: ['id'] });
+const SCHEMA_HASH = `sha256:${'a'.repeat(64)}`;
+const Query = Object.freeze({
+	id: 'query:items',
+	document: 'query Items { items { id value } }',
+	protocol: Object.freeze({
+		version: 1,
+		schemaHash: SCHEMA_HASH,
+		surface: Object.freeze({ kind: 'role', name: 'user' }),
+		operation: 'query:items',
+		trustedPresets: Object.freeze([])
+	}),
+	variableCodec: Object.freeze({
+		version: 1,
+		limits: Object.freeze({
+			maxDepth: 8,
+			maxBoolWidth: 32,
+			maxInList: 64
+		}),
+		variables: Object.freeze({}),
+		inputs: Object.freeze({})
+	}),
+	live: Object.freeze({
+		id: 'live:items',
+		document: 'subscription ItemsLive { items { id value } }'
+	}),
+	roots: Object.freeze([
+		Object.freeze({
+			responseKey: 'items',
+			field: 'items',
+			cardinality: 'many',
+			nullable: false,
+			dependencies: Object.freeze(['items']),
+			selection: Object.freeze({
+				typename: Item.id,
+				storage: Object.freeze({
+					kind: 'normalized',
+					model: Item.id,
+					identityFields: Item.identityFields
+				}),
+				members: Object.freeze([
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: 'id',
+						field: 'id',
+						codec: 'ID',
+						nullable: false
+					}),
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: 'value',
+						field: 'value',
+						codec: 'String',
+						nullable: false
+					})
+				])
+			})
+		})
+	])
+});
+
+function frame(revision, value, operation = Query.id) {
+	return {
+		data: { items: [{ id: 'item-1', value }] },
+		extensions: {
+			distributed: {
+				protocolVersion: 1,
+				schemaHash: SCHEMA_HASH,
+				cacheScope: 'scope:user',
+				operation,
+				trustedPresets: [],
+				snapshot: {
+					scopeToken: 'snapshot:items',
+					recordsComplete: true,
+					indexesComparable: true,
+					records: [
+						{
+							path: ['items', '0'],
+							model: Item.id,
+							scopeToken: 'record:item-1',
+							incarnation: '1',
+							revision: String(revision),
+							tombstone: false
+						}
+					],
+					indexes: [
+						{
+							projection: 'items',
+							scopeToken: 'index:items',
+							position: String(revision),
+							...(operation === Query.live.id
+								? {
+										resume: {
+											projection: 'items',
+											position: String(revision),
+											token: `cursor:${revision}`
+										}
+									}
+								: {})
+						}
+					],
+					observations: []
+				},
+				...(operation === Query.live.id
+					? {
+							live: {
+								supported: true,
+								reset: false,
+								cursors: [
+									{
+										projection: 'items',
+										position: String(revision),
+										token: `cursor:${revision}`
+									}
+								]
+							}
+						}
+					: {})
+			}
+		}
+	};
+}
+
+function deferred() {
+	let resolve;
+	const promise = new Promise((done) => {
+		resolve = done;
+	});
+	return { promise, resolve };
+}
+
+async function waitFor(predicate) {
+	for (let attempt = 0; attempt < 100; attempt += 1) {
+		if (predicate()) return;
+		await new Promise((resolve) => setImmediate(resolve));
+	}
+	assert.fail('condition was not reached');
+}
+
+test('post-commit observations cover explicit, network, and live writes and ignore stale frames', async () => {
+	let liveObserver;
+	const replica = createDistributedReplica({
+		transport: {
+			fetch: () => Promise.resolve(frame(2, 'network')),
+			subscribe: (_request, observer) => {
+				liveObserver = observer;
+				return () => undefined;
+			}
+		}
+	});
+	const observed = [];
+	const registration = replica[replicaResultObservation]((envelope) => {
+		observed.push({
+			revision:
+				envelope.extensions.distributed.snapshot.records[0].revision,
+			value: replica.read(Query, {}).data.items?.[0]?.value
+		});
+	});
+
+	replica.writeResult(Query, {}, frame(1, 'explicit'), 'network');
+	assert.deepEqual(observed, [{ revision: '1', value: 'explicit' }]);
+
+	const watch = replica.watch(Query, {}, { live: true });
+	await watch.refresh();
+	await waitFor(() => watch.get().data.items?.[0]?.value === 'network');
+	assert.deepEqual(observed.at(-1), { revision: '2', value: 'network' });
+
+	liveObserver.next(frame(3, 'live', Query.live.id));
+	assert.equal(watch.get().data.items[0].value, 'live');
+	assert.deepEqual(observed.at(-1), { revision: '3', value: 'live' });
+
+	replica.writeResult(Query, {}, frame(2, 'stale'), 'network');
+	assert.equal(observed.length, 3);
+	assert.equal(watch.get().data.items[0].value, 'live');
+
+	registration.dispose();
+	replica.writeResult(Query, {}, frame(4, 'after-dispose'), 'network');
+	assert.equal(observed.length, 3);
+	watch.destroy();
+});
+
+test('observer failures are isolated after commit and invalid or scope-fenced work is never observed', async () => {
+	const response = deferred();
+	const reported = [];
+	let fetchCalls = 0;
+	const replica = createDistributedReplica({
+		transport: {
+			fetch: () => {
+				fetchCalls += 1;
+				return fetchCalls === 1
+					? response.promise
+					: new Promise(() => undefined);
+			}
+		},
+		onObserverError: (error) => reported.push(error)
+	});
+	let safeCalls = 0;
+	replica[replicaResultObservation](() => {
+		throw new Error('observer failed');
+	});
+	replica[replicaResultObservation](() => {
+		safeCalls += 1;
+	});
+
+	replica.writeResult(Query, {}, frame(1, 'committed'), 'network');
+	assert.equal(safeCalls, 1);
+	assert.equal(replica.read(Query, {}).data.items[0].value, 'committed');
+	assert.equal(reported.length, 1);
+	assert.match(reported[0].message, /replica observer delivery failed/);
+
+	assert.throws(
+		() => replica.writeResult(Query, {}, { data: { items: [] } }, 'network'),
+		(error) => error?.code === 'DISTRIBUTED_PROTOCOL_INVALID'
+	);
+	assert.equal(safeCalls, 1);
+
+	const watch = replica.watch(Query, {});
+	const flight = watch.refresh();
+	await new Promise((resolve) => setImmediate(resolve));
+	replica.invalidateAuthorization();
+	response.resolve(frame(2, 'late'));
+	await flight;
+	assert.equal(safeCalls, 1, 'late work from the closed generation is fenced');
+	watch.destroy();
+});
+
+test('receipt-only protocol frames notify only after the authoritative scope commits', () => {
+	const schemaHash = `sha256:${'a'.repeat(64)}`;
+	const operationHash = `sha256:${'b'.repeat(64)}`;
+	const artifact = Object.freeze({
+		id: operationHash,
+		document: 'query Scope { __typename }',
+		protocol: Object.freeze({
+			version: 1,
+			schemaHash,
+			surface: Object.freeze({ kind: 'role', name: 'user' }),
+			operation: operationHash,
+			trustedPresets: Object.freeze([])
+		}),
+		variableCodec: Object.freeze({
+			version: 1,
+			limits: Object.freeze({
+				maxDepth: 8,
+				maxBoolWidth: 32,
+				maxInList: 64
+			}),
+			variables: Object.freeze({}),
+			inputs: Object.freeze({})
+		}),
+		roots: Object.freeze([])
+	});
+	const replica = createDistributedReplica();
+	const scopes = [];
+	replica[replicaResultObservation](() => {
+		scopes.push(replica.scope?.cacheScope);
+	});
+
+	replica.writeResult(
+		artifact,
+		{},
+		{
+			extensions: {
+				distributed: {
+					protocolVersion: 1,
+					schemaHash,
+					cacheScope: 'scope:user',
+					operation: operationHash,
+					trustedPresets: []
+				}
+			}
+		},
+		'network'
+	);
+	assert.deepEqual(scopes, ['scope:user']);
+
+	assert.throws(
+		() =>
+			replica.writeResult(
+				artifact,
+				{},
+				{
+					extensions: {
+						distributed: {
+							protocolVersion: 1,
+							schemaHash: `sha256:${'c'.repeat(64)}`,
+							cacheScope: 'scope:forged',
+							operation: operationHash,
+							trustedPresets: []
+						}
+					}
+				},
+				'network'
+			),
+		(error) => error?.code === 'DISTRIBUTED_PROTOCOL_INVALID'
+	);
+	assert.deepEqual(scopes, ['scope:user']);
+});
diff --git a/js/tests/replica-revalidation.test.mjs b/js/tests/replica-revalidation.test.mjs
new file mode 100644
index 00000000..076c148f
--- /dev/null
+++ b/js/tests/replica-revalidation.test.mjs
@@ -0,0 +1,138 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createReplicaRevalidationMatcher } from '../dist/replica/revalidation.js';
+import { TodosArtifact } from './fixtures/adapter-conformance.mjs';
+
+const relationshipArtifact = Object.freeze({
+	...TodosArtifact,
+	id: 'query:users-and-todos',
+	roots: Object.freeze([
+		Object.freeze({
+			responseKey: 'users',
+			field: 'users',
+			cardinality: 'many',
+			nullable: false,
+			dependencies: Object.freeze(['users']),
+			selection: Object.freeze({
+				typename: 'UserView',
+				storage: Object.freeze({
+					kind: 'normalized',
+					model: 'UserView',
+					identityFields: Object.freeze(['id'])
+				}),
+				members: Object.freeze([
+					Object.freeze({
+						kind: 'branch',
+						semantic: 'relationship',
+						responseKey: 'todos',
+						field: 'todos',
+						cardinality: 'many',
+						nullable: false,
+						dependencies: Object.freeze(['user_todos']),
+						relationship: Object.freeze({
+							field: 'todos',
+							targetModel: 'TodoView',
+							kind: 'has_many',
+							keyMapping: Object.freeze({
+								kind: 'direct',
+								local: Object.freeze(['id']),
+								remote: Object.freeze(['owner_id'])
+							}),
+							maintenance: 'local',
+							dependencies: Object.freeze(['users', 'todos'])
+						}),
+						selection: Object.freeze({
+							typename: 'TodoView',
+							storage: Object.freeze({
+								kind: 'normalized',
+								model: 'TodoView',
+								identityFields: Object.freeze(['id'])
+							}),
+							members: Object.freeze([])
+						})
+					})
+				])
+			})
+		})
+	])
+});
+
+function plan(overrides = {}) {
+	return {
+		dependencies: [],
+		models: [],
+		relationships: [],
+		...overrides
+	};
+}
+
+test('revalidation matcher targets dependency, model, and exact relationship inventories', () => {
+	assert.equal(
+		createReplicaRevalidationMatcher(
+			plan({ dependencies: ['todos'] })
+		)(TodosArtifact),
+		true
+	);
+	assert.equal(
+		createReplicaRevalidationMatcher(
+			plan({ dependencies: ['unrelated'] })
+		)(TodosArtifact),
+		false
+	);
+	assert.equal(
+		createReplicaRevalidationMatcher(
+			plan({ models: ['TodoView'] })
+		)(TodosArtifact),
+		true
+	);
+	assert.equal(
+		createReplicaRevalidationMatcher(
+			plan({ dependencies: ['user_todos'] })
+		)(relationshipArtifact),
+		true,
+		'nested dependencies participate in targeting'
+	);
+	assert.equal(
+		createReplicaRevalidationMatcher(
+			plan({
+				relationships: [
+					{
+						sourceModel: 'UserView',
+						field: 'todos',
+						targetModel: 'TodoView'
+					}
+				]
+			})
+		)(relationshipArtifact),
+		true
+	);
+	assert.equal(
+		createReplicaRevalidationMatcher(
+			plan({
+				relationships: [
+					{
+						sourceModel: 'OtherView',
+						field: 'todos',
+						targetModel: 'TodoView'
+					}
+				]
+			})
+		)(relationshipArtifact),
+		false,
+		'relationship identity is an exact source/field/target triple'
+	);
+});
+
+test('empty revalidation inventory is conservative and malformed plans fail closed', () => {
+	assert.equal(createReplicaRevalidationMatcher(plan())(TodosArtifact), true);
+	assert.throws(
+		() =>
+			createReplicaRevalidationMatcher({
+				dependencies: ['todos'],
+				models: [],
+				relationships: [{ sourceModel: '', field: 'todos', targetModel: 'TodoView' }]
+			}),
+		/replica revalidation plan relationships\[0\] is invalid/
+	);
+});
diff --git a/js/tests/replica-rust-artifact-bridge.test.mjs b/js/tests/replica-rust-artifact-bridge.test.mjs
new file mode 100644
index 00000000..d754867d
--- /dev/null
+++ b/js/tests/replica-rust-artifact-bridge.test.mjs
@@ -0,0 +1,129 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+
+import {
+	canonicalizeOperationVariables,
+	createDistributedReplica
+} from '../dist/replica/index.js';
+
+const artifact = JSON.parse(
+	readFileSync(
+		new URL(
+			'../../distributed_cli/tests/fixtures/runtime-bridge-operation.json',
+			import.meta.url
+		),
+		'utf8'
+	)
+);
+
+const singletonVariables = {
+	id: 7,
+	tenantId: 'tenant-a'
+};
+
+const expandedVariables = {
+	id: '7',
+	tenantId: 'tenant-a'
+};
+
+function wireRecord(root) {
+	const values = {
+		__typename: root.selection.typename,
+		id: '7',
+		tenantId: 'tenant-a',
+		title: 'from the Rust artifact'
+	};
+	return Object.fromEntries(
+		root.selection.members
+			.filter((member) => member.kind === 'scalar')
+			.map((member) => {
+				assert.ok(
+					Object.hasOwn(values, member.field),
+					`bridge test needs a wire value for generated field ${member.field}`
+				);
+				return [member.responseKey, values[member.field]];
+			})
+	);
+}
+
+function protocolEnvelope(root) {
+	const projection = 'runtime-bridge-projector';
+	const position = '1';
+	return {
+		data: {
+			[root.responseKey]: wireRecord(root)
+		},
+		extensions: {
+			distributed: {
+				protocolVersion: artifact.protocol.version,
+				schemaHash: artifact.protocol.schemaHash,
+				cacheScope: 'runtime-bridge-cache',
+				operation: artifact.id,
+				snapshot: {
+					scopeToken: 'runtime-bridge-snapshot',
+					recordsComplete: true,
+					indexesComparable: true,
+					records: [
+						{
+							path: [root.responseKey],
+							model: root.selection.storage.model,
+							scopeToken: 'runtime-bridge-record-7',
+							incarnation: position,
+							revision: position,
+							tombstone: false
+						}
+					],
+					indexes: [
+						{
+							projection,
+							scopeToken: 'runtime-bridge-index',
+							position,
+							resume: {
+								projection,
+								position,
+								token: 'runtime-bridge-resume'
+							}
+						}
+					],
+					observations: []
+				}
+			}
+		}
+	};
+}
+
+test('the JS replica executes the exact machine-readable Rust operation artifact', () => {
+	assert.equal(artifact.protocol.operation, artifact.id);
+	assert.equal(artifact.roots.length, 1);
+
+	const canonicalSingleton = canonicalizeOperationVariables(
+		artifact,
+		singletonVariables
+	);
+	const canonicalExpanded = canonicalizeOperationVariables(
+		artifact,
+		expandedVariables
+	);
+	assert.deepEqual(canonicalSingleton, canonicalExpanded);
+
+	const root = artifact.roots[0];
+	const replica = createDistributedReplica();
+	replica.writeResult(
+		artifact,
+		singletonVariables,
+		protocolEnvelope(root),
+		'network'
+	);
+
+	const snapshot = replica.read(artifact, expandedVariables);
+	assert.equal(snapshot.status, 'ready');
+	assert.equal(snapshot.complete, true);
+	assert.equal(snapshot.stale, false);
+	assert.deepEqual(snapshot.data, {
+		[root.responseKey]: {
+			id: '7',
+			title: 'from the Rust artifact'
+		}
+	});
+});
diff --git a/js/tests/replica-scope-ssr.test.mjs b/js/tests/replica-scope-ssr.test.mjs
new file mode 100644
index 00000000..fc47a1d6
--- /dev/null
+++ b/js/tests/replica-scope-ssr.test.mjs
@@ -0,0 +1,548 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	createDistributedReplica,
+	replicaRecordKey
+} from '../dist/replica/index.js';
+import { replicaCommandAuthority } from '../dist/replica/command-runtime.js';
+
+const AUTH_SCHEMA_HASH = `sha256:${'a'.repeat(64)}`;
+const AUTH_PROTOCOL_HASH = `sha256:${'b'.repeat(64)}`;
+const USER_SURFACE = Object.freeze({ kind: 'role', name: 'user' });
+
+const Todo = Object.freeze({
+	id: 'TodoView',
+	identityFields: Object.freeze(['id'])
+});
+
+const NoVariables = Object.freeze({
+	version: 1,
+	limits: Object.freeze({
+		maxDepth: 8,
+		maxBoolWidth: 256,
+		maxInList: 1000
+	}),
+	variables: Object.freeze({}),
+	inputs: Object.freeze({})
+});
+
+function operation(id, field = 'todos', schemaHash = 'schema-a') {
+	return Object.freeze({
+		id,
+		document: `query ${id.replaceAll(':', '_')} { ${field} { id title } }`,
+		protocol: Object.freeze({
+			version: 1,
+			schemaHash,
+			surface: USER_SURFACE,
+			operation: id,
+			trustedPresets: Object.freeze([])
+		}),
+		variableCodec: NoVariables,
+		roots: Object.freeze([
+			Object.freeze({
+				responseKey: field,
+				field,
+				cardinality: 'many',
+				nullable: false,
+				dependencies: Object.freeze([field]),
+				selection: Object.freeze({
+					typename: Todo.id,
+					storage: Object.freeze({
+						kind: 'normalized',
+						model: Todo.id,
+						identityFields: Todo.identityFields
+					}),
+					members: Object.freeze([
+						Object.freeze({
+							kind: 'scalar',
+							responseKey: 'id',
+							field: 'id',
+							codec: 'ID',
+							nullable: false
+						}),
+						Object.freeze({
+							kind: 'scalar',
+							responseKey: 'title',
+							field: 'title',
+							codec: 'String',
+							nullable: false
+						})
+					])
+				})
+			})
+		])
+	});
+}
+
+const Todos = operation('query:todos');
+const HiddenTodos = operation('query:hidden-todos', 'hidden_todos');
+const ElevatedTodos = operation('query:elevated-todos', 'todos', 'schema-elevated');
+const AuthorizedTodosBase = operation(
+	'query:authorized-todos',
+	'todos',
+	AUTH_SCHEMA_HASH
+);
+const AuthorizedTodos = Object.freeze({
+	...AuthorizedTodosBase,
+	protocol: Object.freeze({
+		...AuthorizedTodosBase.protocol,
+		trustedPresets: Object.freeze([
+			Object.freeze({ name: 'owner', codec: 'string' })
+		])
+	})
+});
+const QueryScopedTodos = Object.freeze({
+	...operation('query:scoped-todos', 'todos', AUTH_SCHEMA_HASH),
+	protocol: Object.freeze({
+		...operation('query:scoped-todos', 'todos', AUTH_SCHEMA_HASH).protocol,
+		trustedPresets: Object.freeze([
+			Object.freeze({ name: 'owner', codec: 'string' })
+		])
+	})
+});
+const TodosWithSecret = Object.freeze({
+	...operation('query:todos-with-secret'),
+	roots: Object.freeze([
+		Object.freeze({
+			...Todos.roots[0],
+			selection: Object.freeze({
+				...Todos.roots[0].selection,
+				members: Object.freeze([
+					...Todos.roots[0].selection.members,
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: 'secret',
+						field: 'secret',
+						codec: 'String',
+						nullable: false
+					})
+				])
+			})
+		})
+	])
+});
+
+function frame(
+	artifact,
+	rows,
+	{
+		cacheScope = 'cache:a',
+		position = '1',
+		revision = position,
+		recordScope = (row) => `record:${row.id}`,
+		records,
+		snapshotScope = `snapshot:${artifact.id}`,
+		indexScope = `index:${artifact.id}`,
+		trustedPresets = []
+	} = {}
+) {
+	const field = artifact.roots[0].field;
+	const recordEvidence =
+		records ??
+		rows.map((row, index) => ({
+			path: [field, String(index)],
+			model: Todo.id,
+			scopeToken: recordScope(row),
+			incarnation: '1',
+			revision,
+			tombstone: false
+		}));
+	return {
+		data: { [field]: rows },
+		extensions: {
+			distributed: {
+				protocolVersion: 1,
+				schemaHash: artifact.protocol.schemaHash,
+				cacheScope,
+				operation: artifact.protocol.operation,
+				trustedPresets,
+				snapshot: {
+					scopeToken: snapshotScope,
+					recordsComplete: true,
+					indexesComparable: true,
+					records: recordEvidence,
+					indexes: [
+						{
+							projection: `${field}-projector`,
+							scopeToken: indexScope,
+							position
+						}
+					],
+					observations: []
+				}
+			}
+		}
+	};
+}
+
+function write(replica, artifact, rows, options) {
+	replica.writeResult(artifact, {}, frame(artifact, rows, options), 'network');
+}
+
+function jsonClone(value) {
+	return JSON.parse(JSON.stringify(value));
+}
+
+test('only a server response establishes a scope and permits SSR dehydration', () => {
+	const replica = createDistributedReplica();
+
+	assert.equal(replica.scope, undefined);
+	assert.throws(
+		() => replica.dehydrate(),
+		/server establishes an authoritative scope/
+	);
+
+	write(replica, Todos, [{ id: 'todo-1', title: 'one' }]);
+	assert.deepEqual(replica.scope, {
+		protocolVersion: 1,
+		schemaHash: 'schema-a',
+		cacheScope: 'cache:a'
+	});
+	assert.equal(Object.isFrozen(replica.scope), true);
+});
+
+test('query artifacts independently bind exact scope-preset inventories', () => {
+	const replica = createDistributedReplica();
+	write(replica, QueryScopedTodos, [{ id: 'todo-1', title: 'authorized' }], {
+		trustedPresets: [
+			{ name: 'owner', codec: 'string', value: 'user-1' }
+		]
+	});
+	assert.equal(replica.scope.cacheScope, 'cache:a');
+
+	assert.throws(
+		() =>
+			write(replica, QueryScopedTodos, [{ id: 'todo-2', title: 'forged' }], {
+				position: '2',
+				revision: '2',
+				trustedPresets: [
+					{ name: 'owner', codec: 'string', value: 'user-2' }
+				]
+			}),
+		(error) =>
+			error?.code === 'DISTRIBUTED_PROTOCOL_INVALID' &&
+			error?.path === 'extensions.distributed.trustedPresets'
+	);
+	assert.equal(
+		replica.scope,
+		undefined,
+		'a changed value inside one authoritative scope purges the generation'
+	);
+
+	for (const trustedPresets of [
+		[],
+		[
+			{ name: 'owner', codec: 'string', value: 'user-1' },
+			{ name: 'forged-extra', codec: 'string', value: 'forged' }
+		],
+		[{ name: 'owner', codec: 'int32', value: 1 }]
+	]) {
+		const candidate = createDistributedReplica();
+		assert.throws(
+			() =>
+				write(candidate, QueryScopedTodos, [], {
+					trustedPresets
+				}),
+			(error) =>
+				error?.code === 'DISTRIBUTED_PROTOCOL_INVALID' &&
+				error?.path === 'extensions.distributed.trustedPresets'
+		);
+		assert.equal(candidate.scope, undefined);
+	}
+});
+
+test('bound command authority is scope-derived, hydration-safe, and generation-fenced', () => {
+	const contract = Object.freeze({
+		protocolVersion: 1,
+		schemaHash: AUTH_SCHEMA_HASH,
+		protocolHash: AUTH_PROTOCOL_HASH,
+		surface: USER_SURFACE,
+		trustedPresets: Object.freeze([
+			Object.freeze({ name: 'owner', codec: 'string' })
+		])
+	});
+	const replica = createDistributedReplica();
+	const registration = replica[replicaCommandAuthority](contract);
+	const initial = registration.read();
+	assert.equal(initial.scope, undefined);
+	assert.deepEqual(initial.trustedPresets, []);
+	assert.equal(initial.signal.aborted, false);
+
+	write(replica, AuthorizedTodos, [{ id: 'todo-1', title: 'authorized' }], {
+		trustedPresets: [
+			{ name: 'owner', codec: 'string', value: 'user-1' }
+		]
+	});
+	const established = registration.read();
+	assert.equal(established.scope.cacheScope, 'cache:a');
+	assert.deepEqual(established.trustedPresets, [
+		{ name: 'owner', codec: 'string', value: 'user-1' }
+	]);
+	assert.equal(Object.isFrozen(established.trustedPresets), true);
+
+	replica.read(AuthorizedTodos, {});
+	const state = replica.dehydrate();
+	const browser = createDistributedReplica();
+	const browserRegistration = browser[replicaCommandAuthority](contract);
+	assert.equal(browser.hydrate(jsonClone(state), state.scope), true);
+	assert.deepEqual(browserRegistration.read().trustedPresets, [
+		{ name: 'owner', codec: 'string', value: 'user-1' }
+	]);
+
+	assert.throws(
+		() =>
+			write(replica, AuthorizedTodos, [{ id: 'todo-2', title: 'invalid' }], {
+				cacheScope: 'cache:b',
+				position: '2',
+				revision: '2',
+				trustedPresets: []
+			}),
+		(error) =>
+			error?.code === 'DISTRIBUTED_PROTOCOL_INVALID' &&
+			error?.path === 'extensions.distributed.trustedPresets'
+	);
+	assert.equal(established.signal.aborted, true);
+	assert.equal(replica.scope, undefined);
+	assert.deepEqual(registration.read().trustedPresets, []);
+
+	assert.throws(
+		() =>
+			replica[replicaCommandAuthority]({
+				...contract,
+				surface: { kind: 'role', name: 'admin' }
+			}),
+		/does not match the active replica client surface/
+	);
+	registration.dispose();
+	browserRegistration.dispose();
+});
+
+test('SSR dehydration includes confirmed reachable state and excludes optimistic or unrendered data', () => {
+	const replica = createDistributedReplica();
+	write(replica, HiddenTodos, [{ id: 'hidden-1', title: 'private hidden row' }]);
+	write(replica, TodosWithSecret, [
+		{ id: 'todo-1', title: 'older', secret: 'not rendered' }
+	]);
+	write(replica, Todos, [{ id: 'todo-1', title: 'confirmed' }], {
+		position: '2',
+		revision: '2'
+	});
+	replica.read(Todos, {});
+	replica.createOptimisticLayer('cmd-1', (writer) => {
+		writer.writeRecord(Todo, 'todo-1', {
+			fields: { title: 'optimistic' }
+		});
+	});
+	assert.equal(replica.read(Todos, {}).data.todos[0].title, 'optimistic');
+
+	const state = replica.dehydrate();
+	const payload = state.payload;
+	assert.deepEqual(
+		payload.cache.records.map((record) => record.key),
+		[replicaRecordKey(Todo, 'todo-1')]
+	);
+	assert.equal(
+		payload.cache.records.some((record) => record.key.includes('hidden-1')),
+		false
+	);
+	assert.equal(
+		Object.prototype.hasOwnProperty.call(
+			payload.cache.records[0].fields,
+			'secret'
+		),
+		false
+	);
+	assert.equal(payload.cache.indexes.length, 1);
+
+	const browserReplica = createDistributedReplica();
+	assert.equal(browserReplica.hydrate(jsonClone(state), state.scope), true);
+	assert.equal(
+		browserReplica.read(Todos, {}).data.todos[0].title,
+		'confirmed'
+	);
+	assert.deepEqual(browserReplica.scope, state.scope);
+});
+
+test('hydration rejects malformed, cross-scope, and elevated-schema state atomically', () => {
+	const current = createDistributedReplica();
+	write(current, Todos, [{ id: 'todo-1', title: 'current' }]);
+	current.read(Todos, {});
+	const currentState = current.dehydrate();
+	assert.equal(createDistributedReplica().hydrate(currentState, undefined), false);
+
+	const otherScope = createDistributedReplica();
+	write(
+		otherScope,
+		Todos,
+		[{ id: 'todo-1', title: 'other tenant' }],
+		{ cacheScope: 'cache:b', recordScope: () => 'record:b' }
+	);
+	otherScope.read(Todos, {});
+	assert.equal(
+		current.hydrate(otherScope.dehydrate(), current.scope),
+		false
+	);
+	assert.equal(current.read(Todos, {}).data.todos[0].title, 'current');
+	assert.equal(current.scope.cacheScope, 'cache:a');
+
+	const malformed = jsonClone(current.dehydrate());
+	malformed.payload.cache.records[0].revision = 'not-a-decimal';
+	assert.equal(current.hydrate(malformed, current.scope), false);
+	assert.equal(current.read(Todos, {}).data.todos[0].title, 'current');
+	const inconsistent = jsonClone(current.dehydrate());
+	inconsistent.payload.recordClocks[0][1].revision = '99';
+	assert.equal(current.hydrate(inconsistent, current.scope), false);
+	assert.equal(current.read(Todos, {}).data.todos[0].title, 'current');
+
+	const elevated = createDistributedReplica();
+	elevated.read(ElevatedTodos, {});
+	assert.equal(elevated.hydrate(current.dehydrate(), current.scope), false);
+	assert.equal(elevated.scope, undefined);
+	assert.equal(elevated.read(ElevatedTodos, {}).complete, false);
+});
+
+test('dehydration drops historical list members and destroyed watch reachability', () => {
+	const replica = createDistributedReplica();
+	const watch = replica.watch(Todos, {});
+	write(
+		replica,
+		Todos,
+		[
+			{ id: 'todo-a', title: 'a' },
+			{ id: 'todo-b', title: 'b' }
+		],
+		{ position: '1', revision: '1' }
+	);
+	write(replica, Todos, [{ id: 'todo-a', title: 'a2' }], {
+		position: '2',
+		revision: '2'
+	});
+	const state = replica.dehydrate();
+	assert.deepEqual(
+		state.payload.cache.records.map((record) => record.key),
+		[replicaRecordKey(Todo, 'todo-a')]
+	);
+
+	watch.destroy();
+	const afterDestroy = replica.dehydrate();
+	assert.deepEqual(afterDestroy.payload.cache.records, []);
+	assert.deepEqual(afterDestroy.payload.cache.indexes, []);
+});
+
+test('authorization invalidation aborts old HTTP and starts one generation-fenced replacement', async () => {
+	let request;
+	const requests = [];
+	const replica = createDistributedReplica({
+		transport: {
+			fetch(next) {
+				request = next;
+				let resolve;
+				const result = new Promise((done) => {
+					resolve = done;
+				});
+				requests.push({ request: next, result, resolve });
+				return result;
+			}
+		}
+	});
+	const watch = replica.watch(Todos, {});
+	await Promise.resolve();
+	assert.equal(request.signal.aborted, false);
+	assert.equal(requests.length, 1);
+	const generation = replica.authorizationGeneration;
+
+	replica.invalidateAuthorization();
+	assert.equal(requests[0].request.signal.aborted, true);
+	assert.equal(replica.authorizationGeneration, generation + 1);
+	await Promise.resolve();
+	assert.equal(requests.length, 2);
+	requests[0].resolve(
+		frame(Todos, [{ id: 'todo-late', title: 'must not appear' }])
+	);
+	await requests[0].result;
+	await Promise.resolve();
+
+	assert.equal(watch.get().complete, false);
+	assert.deepEqual(watch.get().data, {});
+	assert.equal(replica.scope, undefined);
+	requests[1].resolve(
+		frame(Todos, [{ id: 'todo-current', title: 'current generation' }])
+	);
+	await requests[1].result;
+	await Promise.resolve();
+	assert.equal(watch.get().data.todos[0].title, 'current generation');
+	watch.destroy();
+});
+
+test('a malformed response purges the prior scope without publishing its replacement', () => {
+	const replica = createDistributedReplica();
+	write(replica, Todos, [{ id: 'todo-a', title: 'scope a' }]);
+	assert.equal(replica.scope.cacheScope, 'cache:a');
+	assert.equal(replica.read(Todos, {}).data.todos[0].title, 'scope a');
+
+	assert.throws(
+		() =>
+			write(replica, Todos, [{ id: 'todo-b', title: 'invalid scope b' }], {
+				cacheScope: 'cache:b',
+				position: '2',
+				revision: '2',
+				records: []
+			}),
+		(error) =>
+			error?.code === 'DISTRIBUTED_PROTOCOL_INVALID' &&
+			error?.path === 'extensions.distributed.snapshot.records'
+	);
+	assert.equal(replica.scope, undefined);
+	assert.equal(replica.read(Todos, {}).complete, false);
+	assert.deepEqual(replica.read(Todos, {}).data, {});
+});
+
+test('hydrated protocol clocks reject stale rows and tombstone resurrection', () => {
+	const serverReplica = createDistributedReplica();
+	write(serverReplica, Todos, [{ id: 'todo-1', title: 'first' }]);
+	serverReplica.read(Todos, {});
+	write(serverReplica, Todos, [], {
+		position: '9',
+		revision: '9',
+		records: [
+			{
+				path: ['todos', '0'],
+				model: Todo.id,
+				scopeToken: 'record:todo-1',
+				incarnation: '1',
+				revision: '9',
+				tombstone: true
+			}
+		]
+	});
+	assert.deepEqual(serverReplica.read(Todos, {}).data.todos, []);
+
+	const browserReplica = createDistributedReplica();
+	const state = serverReplica.dehydrate();
+	assert.equal(browserReplica.hydrate(jsonClone(state), state.scope), true);
+	assert.deepEqual(browserReplica.read(Todos, {}).data.todos, []);
+
+	write(
+		browserReplica,
+		Todos,
+		[{ id: 'todo-1', title: 'stale resurrection' }],
+		{
+			position: '8',
+			revision: '8',
+			recordScope: () => 'record:todo-1'
+		}
+	);
+	assert.deepEqual(browserReplica.read(Todos, {}).data.todos, []);
+	assert.equal(browserReplica.inspectRecord(Todo, 'todo-1'), undefined);
+});
+
+test('SSR callers get isolated replicas rather than process-wide state', () => {
+	const firstRequest = createDistributedReplica();
+	const secondRequest = createDistributedReplica();
+	write(firstRequest, Todos, [{ id: 'todo-1', title: 'request one' }]);
+
+	assert.equal(firstRequest.read(Todos, {}).complete, true);
+	assert.equal(secondRequest.read(Todos, {}).complete, false);
+	assert.equal(secondRequest.scope, undefined);
+});
diff --git a/js/tests/replica-trusted-presets.test.mjs b/js/tests/replica-trusted-presets.test.mjs
new file mode 100644
index 00000000..88329f64
--- /dev/null
+++ b/js/tests/replica-trusted-presets.test.mjs
@@ -0,0 +1,333 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	DistributedProtocolError,
+	parseDistributedProtocolEnvelope
+} from '../dist/index.js';
+import {
+	matchReplicaTrustedPresetInventory,
+	prepareReplicaCommandWithTrustedPresets
+} from '../dist/replica/commands.js';
+import {
+	prepareReplicaCommand,
+	ReplicaCommandContractError
+} from '../dist/replica/index.js';
+
+const HASH_A = `sha256:${'a'.repeat(64)}`;
+const HASH_B = `sha256:${'b'.repeat(64)}`;
+const HASH_C = `sha256:${'c'.repeat(64)}`;
+const COMMAND_ID = '018f47de-3d2a-7abc-8abc-0123456789ab';
+
+function envelope(overrides = {}) {
+	return {
+		protocolVersion: 1,
+		schemaHash: HASH_A,
+		cacheScope: 'opaque:scope',
+		...overrides
+	};
+}
+
+function trusted(name) {
+	return { kind: 'trusted_preset', name };
+}
+
+function presetArtifact(overrides = {}) {
+	return {
+		version: 1,
+		name: 'todo.assign',
+		mutationField: 'assignTodo',
+		document:
+			'mutation Client_assignTodo($commandId: ID!) { assignTodo(commandId: $commandId) }',
+		operationHash: HASH_A,
+		protocol: {
+			version: 1,
+			schemaHash: HASH_B,
+			protocolHash: HASH_C,
+			surface: { kind: 'role', name: 'user' },
+			operation: HASH_A,
+			trustedPresets: [
+				{ name: 'x-default-status', codec: 'string' },
+				{ name: 'x-tenant', codec: 'string' }
+			]
+		},
+		input: { kind: 'none' },
+		output: {
+			kind: 'object',
+			definition: {
+				name: 'AssignTodoResult',
+				fields: [
+					{
+						name: 'accepted',
+						typeName: 'Boolean',
+						nullable: false,
+						list: false,
+						itemNullable: false,
+						codec: 'boolean'
+					}
+				]
+			}
+		},
+		consistency: 'accepted',
+		effects: {
+			version: 1,
+			operations: [
+				{
+					kind: 'patch',
+					model: 'Todo',
+					key: {
+						fields: [{ field: 'tenantId', value: trusted('x-tenant') }]
+					},
+					fields: [
+						{ field: 'status', value: trusted('x-default-status') }
+					]
+				}
+			],
+			fallback: 'revalidate'
+		},
+		trustedPresets: [
+			{ name: 'x-default-status', codec: 'string' },
+			{ name: 'x-tenant', codec: 'string' }
+		],
+		revalidation: {
+			version: 1,
+			required: true,
+			dependencies: ['todo_rows'],
+			models: ['Todo'],
+			relationships: []
+		},
+		...overrides
+	};
+}
+
+test('protocol parses every trusted-preset codec into a deep immutable inventory', () => {
+	const callerJson = {
+		nested: [{ enabled: true }],
+		safe: 9_007_199_254_740_991
+	};
+	const parsed = parseDistributedProtocolEnvelope(
+		envelope({
+			trustedPresets: [
+				{ name: 'string', codec: 'string', value: 'tenant-1' },
+				{
+					name: 'timestamp',
+					codec: 'string_unvalidated_timestamp',
+					value: '2026-07-23T00:00:00Z'
+				},
+				{ name: 'bytes', codec: 'base64', value: 'dGVuYW50LTE=' },
+				{ name: 'bool', codec: 'boolean', value: true },
+				{ name: 'int', codec: 'int32', value: -2_147_483_648 },
+				{ name: 'float', codec: 'float64', value: 1.25 },
+				{
+					name: 'bigint',
+					codec: 'json_number_precision_limited',
+					value: 9_007_199_254_740_991
+				},
+				{ name: 'json', codec: 'json', value: callerJson }
+			]
+		})
+	);
+
+	callerJson.nested[0].enabled = false;
+	assert.equal(parsed.trustedPresets.length, 8);
+	assert.deepEqual(parsed.trustedPresets[7].value, {
+		nested: [{ enabled: true }],
+		safe: 9_007_199_254_740_991
+	});
+	assert.equal(Object.isFrozen(parsed.trustedPresets), true);
+	assert.equal(Object.isFrozen(parsed.trustedPresets[0]), true);
+	assert.equal(Object.isFrozen(parsed.trustedPresets[7].value), true);
+	assert.equal(Object.isFrozen(parsed.trustedPresets[7].value.nested), true);
+	assert.equal(
+		Object.isFrozen(parsed.trustedPresets[7].value.nested[0]),
+		true
+	);
+
+	const omitted = parseDistributedProtocolEnvelope(envelope());
+	assert.deepEqual(omitted.trustedPresets, []);
+	assert.equal(Object.isFrozen(omitted.trustedPresets), true);
+});
+
+test('protocol rejects duplicate, unsupported, and codec-invalid trusted presets', () => {
+	const rejected = [
+		[
+			[
+				{ name: 'same', codec: 'string', value: 'first' },
+				{ name: 'same', codec: 'string', value: 'second' }
+			],
+			'.name'
+		],
+		[[{ name: 'tenant', codec: 'uuid', value: 'tenant-1' }], '.codec'],
+		[[{ name: ' tenant', codec: 'string', value: 'tenant-1' }], '.name'],
+		[[{ name: 'bytes', codec: 'base64', value: 'not base64' }], '.value'],
+		[[{ name: 'flag', codec: 'boolean', value: 'true' }], '.value'],
+		[[{ name: 'count', codec: 'int32', value: 2_147_483_648 }], '.value'],
+		[
+			[
+				{
+					name: 'count',
+					codec: 'json_number_precision_limited',
+					value: 9_007_199_254_740_992
+				}
+			],
+			'.value'
+		],
+		[[{ name: 'float', codec: 'float64', value: Infinity }], '.value'],
+		[[{ name: 'json', codec: 'json', value: { invalid: undefined } }], '.invalid']
+	];
+
+	for (const [trustedPresets, suffix] of rejected) {
+		assert.throws(
+			() =>
+				parseDistributedProtocolEnvelope(
+					envelope({ trustedPresets })
+				),
+			(error) =>
+				error instanceof DistributedProtocolError &&
+				error.code === 'DISTRIBUTED_PROTOCOL_INVALID' &&
+				error.path.endsWith(suffix)
+		);
+	}
+});
+
+test('exact inventory matching rejects missing, extra, and codec drift', () => {
+	const expected = [
+		{ name: 'x-default-status', codec: 'string' },
+		{ name: 'x-tenant', codec: 'string' }
+	];
+	const authoritative = parseDistributedProtocolEnvelope(
+		envelope({
+			trustedPresets: [
+				{ name: 'x-tenant', codec: 'string', value: 'tenant-1' },
+				{
+					name: 'x-default-status',
+					codec: 'string',
+					value: 'assigned'
+				}
+			]
+		})
+	).trustedPresets;
+	const matched = matchReplicaTrustedPresetInventory(expected, authoritative);
+
+	assert.equal(matched.resolve('x-tenant'), 'tenant-1');
+	assert.equal(matched.resolve('x-default-status'), 'assigned');
+	assert.equal(Object.isFrozen(matched), true);
+	assert.equal(Object.isFrozen(matched.descriptors), true);
+	assert.equal(Object.isFrozen(matched.values), true);
+
+	for (const candidate of [
+		authoritative.slice(0, 1),
+		[
+			...authoritative,
+			{ name: 'x-unrelated', codec: 'string', value: 'other' }
+		],
+		[
+			{ name: 'x-tenant', codec: 'json', value: 'tenant-1' },
+			authoritative[1]
+		]
+	]) {
+		assert.throws(
+			() => matchReplicaTrustedPresetInventory(expected, candidate),
+			(error) =>
+				error instanceof ReplicaCommandContractError &&
+				error.code === 'REPLICA_COMMAND_TRUSTED_PRESET_MISMATCH'
+		);
+	}
+});
+
+test('replica-bound preparation resolves only exact command descriptors while standalone stays closed', () => {
+	const artifact = presetArtifact();
+	const authoritative = parseDistributedProtocolEnvelope(
+		envelope({
+			trustedPresets: [
+				{
+					name: 'x-default-status',
+					codec: 'string',
+					value: 'assigned'
+				},
+				{ name: 'x-tenant', codec: 'string', value: 'tenant-1' },
+				{
+					name: 'x-other-command',
+					codec: 'boolean',
+					value: true
+				}
+			]
+		})
+	).trustedPresets;
+
+	assert.throws(
+		() =>
+			prepareReplicaCommand(artifact, undefined, {
+				commandId: COMMAND_ID
+			}),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.code === 'REPLICA_COMMAND_ARTIFACT_INVALID' &&
+			error.path.endsWith('.value')
+	);
+
+	const prepared = prepareReplicaCommandWithTrustedPresets(
+		artifact,
+		undefined,
+		authoritative,
+		{ commandId: COMMAND_ID }
+	);
+	assert.deepEqual(prepared.optimistic.operations, [
+		{
+			kind: 'patch',
+			model: 'Todo',
+			key: {
+				fields: [{ field: 'tenantId', value: 'tenant-1' }]
+			},
+			fields: [{ field: 'status', value: 'assigned' }]
+		}
+	]);
+
+	for (const malformedArtifact of [
+		presetArtifact({
+			trustedPresets: [
+				{ name: 'x-tenant', codec: 'string' },
+				{ name: 'x-tenant', codec: 'string' }
+			]
+		}),
+		presetArtifact({
+			trustedPresets: [
+				{ name: 'x-default-status', codec: 'uuid' },
+				{ name: 'x-tenant', codec: 'string' }
+			]
+		}),
+		presetArtifact({
+			trustedPresets: [
+				{ name: 'x-default-status', codec: 'string' },
+				{ name: 'x-tenant', codec: 'string' },
+				{ name: 'x-unused', codec: 'string' }
+			]
+		})
+	]) {
+		assert.throws(
+			() =>
+				prepareReplicaCommandWithTrustedPresets(
+					malformedArtifact,
+					undefined,
+					authoritative,
+					{ commandId: COMMAND_ID }
+				),
+			(error) =>
+				error instanceof ReplicaCommandContractError &&
+				error.code === 'REPLICA_COMMAND_ARTIFACT_INVALID'
+		);
+	}
+
+	assert.throws(
+		() =>
+			prepareReplicaCommandWithTrustedPresets(
+				artifact,
+				undefined,
+				authoritative.filter(({ name }) => name !== 'x-tenant'),
+				{ commandId: COMMAND_ID }
+			),
+		(error) =>
+			error instanceof ReplicaCommandContractError &&
+			error.code === 'REPLICA_COMMAND_TRUSTED_PRESET_MISMATCH'
+	);
+});
diff --git a/js/tests/replica-variable-codec.test.mjs b/js/tests/replica-variable-codec.test.mjs
new file mode 100644
index 00000000..cf1d4573
--- /dev/null
+++ b/js/tests/replica-variable-codec.test.mjs
@@ -0,0 +1,954 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	canonicalizeOperationVariables,
+	createDistributedReplica
+} from '../dist/replica/index.js';
+
+const Item = Object.freeze({ id: 'item-view', identityFields: Object.freeze(['id']) });
+
+const codecLimits = Object.freeze({
+	maxDepth: 64,
+	maxBoolWidth: 256,
+	maxInList: 1000
+});
+
+const variableCodec = Object.freeze({
+	version: 1,
+	limits: codecLimits,
+	variables: Object.freeze({
+		big: Object.freeze({
+			kind: 'scalar',
+			scalar: 'BigInt',
+			codec: 'json_number_precision_limited',
+			nullable: true
+		}),
+		blob: Object.freeze({
+			kind: 'scalar',
+			scalar: 'Bytea',
+			codec: 'base64',
+			nullable: true
+		}),
+		direction: Object.freeze({
+			kind: 'enum',
+			name: 'order_by',
+			values: Object.freeze(['asc', 'desc']),
+			nullable: true
+		}),
+		id: Object.freeze({
+			kind: 'scalar',
+			scalar: 'ID',
+			codec: 'string',
+			nullable: false
+		}),
+		offset: Object.freeze({
+			kind: 'scalar',
+			scalar: 'Int',
+			codec: 'int32',
+			nullable: true
+		}),
+		order: Object.freeze({
+			kind: 'list',
+			nullable: true,
+			item: Object.freeze({ kind: 'input', name: 'item_order_by', nullable: false })
+		}),
+		payload: Object.freeze({
+			kind: 'scalar',
+			scalar: 'JSON',
+			codec: 'json',
+			nullable: true
+		}),
+		ratio: Object.freeze({
+			kind: 'scalar',
+			scalar: 'Float',
+			codec: 'float64',
+			nullable: true
+		}),
+		where: Object.freeze({
+			kind: 'input',
+			name: 'item_bool_exp',
+			nullable: true,
+			filterBaseDepth: 0
+		})
+	}),
+	inputs: Object.freeze({
+		item_bool_exp: Object.freeze({
+			kind: 'filter',
+			model: 'item-view',
+			fields: Object.freeze([
+				Object.freeze({
+					field: 'id',
+					scalar: 'ID',
+					codec: 'string',
+					nullable: false,
+					operators: Object.freeze(['_eq', '_in', '_nin'])
+				}),
+				Object.freeze({
+					field: 'payload',
+					scalar: 'JSON',
+					codec: 'json',
+					nullable: true,
+					operators: Object.freeze(['_eq', '_contains', '_has_key'])
+				}),
+				Object.freeze({
+					field: 'priority',
+					scalar: 'Int',
+					codec: 'int32',
+					nullable: false,
+					operators: Object.freeze(['_eq', '_in', '_is_null'])
+				}),
+				Object.freeze({
+					field: 'title',
+					scalar: 'String',
+					codec: 'string',
+					nullable: false,
+					operators: Object.freeze(['_eq', '_like', '_ilike'])
+				})
+			]),
+			relationships: Object.freeze([
+				Object.freeze({
+					field: 'owner',
+					target: Object.freeze({ kind: 'input', name: 'user_bool_exp' })
+				}),
+				Object.freeze({
+					field: 'unplanned',
+					target: Object.freeze({ kind: 'opaque' })
+				})
+			])
+		}),
+		item_order_by: Object.freeze({
+			kind: 'order',
+			model: 'item-view',
+			fields: Object.freeze([
+				Object.freeze({
+					field: 'id',
+					scalar: 'ID',
+					codec: 'string',
+					nullable: false
+				}),
+				Object.freeze({
+					field: 'priority',
+					scalar: 'Int',
+					codec: 'int32',
+					nullable: false
+				})
+			]),
+			values: Object.freeze(['asc', 'desc'])
+		}),
+		user_bool_exp: Object.freeze({
+			kind: 'filter',
+			model: 'user-view',
+			fields: Object.freeze([
+				Object.freeze({
+					field: 'id',
+					scalar: 'ID',
+					codec: 'string',
+					nullable: false,
+					operators: Object.freeze(['_eq'])
+				})
+			]),
+			// A named registry cycle is valid and must not recurse during validation.
+			relationships: Object.freeze([
+				Object.freeze({
+					field: 'items',
+					target: Object.freeze({ kind: 'input', name: 'item_bool_exp' })
+				})
+			])
+		})
+	})
+});
+
+const CodecArtifact = Object.freeze({
+	id: 'query:codec-items',
+	document: 'query CodecItems { items { id title } }',
+	variableCodec,
+	protocol: Object.freeze({
+		version: 1,
+		schemaHash: 'schema-one',
+		surface: Object.freeze({ kind: 'role', name: 'user' }),
+		operation: 'query:codec-items',
+		trustedPresets: Object.freeze([])
+	}),
+	roots: Object.freeze([
+		Object.freeze({
+			responseKey: 'items',
+			field: 'items',
+			cardinality: 'many',
+			nullable: false,
+			arguments: Object.freeze({
+				id: Object.freeze({ kind: 'variable', name: 'id' }),
+				offset: Object.freeze({ kind: 'variable', name: 'offset' }),
+				order_by: Object.freeze({ kind: 'variable', name: 'order' }),
+				where: Object.freeze({ kind: 'variable', name: 'where' })
+			}),
+			coverage: Object.freeze({
+				kind: 'offset',
+				offsetArgument: 'offset',
+				defaultLimit: 25,
+				maxLimit: 100
+			}),
+			dependencies: Object.freeze(['items']),
+			selection: Object.freeze({
+				typename: Item.id,
+				storage: Object.freeze({
+					kind: 'normalized',
+					model: Item.id,
+					identityFields: Item.identityFields
+				}),
+				members: Object.freeze([
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: 'id',
+						field: 'id',
+						codec: 'ID',
+						nullable: false
+					}),
+					Object.freeze({
+						kind: 'scalar',
+						responseKey: 'title',
+						field: 'title',
+						codec: 'String',
+						nullable: false
+					})
+				])
+			})
+		})
+	])
+});
+
+const singletonVariables = Object.freeze({
+	id: 7,
+	offset: -1,
+	order: Object.freeze({ priority: 'asc' }),
+	where: Object.freeze({
+		_and: Object.freeze({
+			priority: Object.freeze({ _eq: -0 }),
+			id: Object.freeze({ _in: 7 })
+		})
+	})
+});
+
+const expandedVariables = Object.freeze({
+	where: Object.freeze({
+		_and: Object.freeze([
+			Object.freeze({
+				id: Object.freeze({ _in: Object.freeze(['7']) }),
+				priority: Object.freeze({ _eq: 0 })
+			})
+		])
+	}),
+	order: Object.freeze([Object.freeze({ priority: 'asc' })]),
+	offset: -1,
+	id: '7'
+});
+
+function codecWireFrame(title = 'schema one') {
+	const projection = 'items-projector';
+	const position = '1';
+	const resume = {
+		projection,
+		position,
+		token: 'resume:1'
+	};
+	return {
+		data: { items: [{ id: 'item-1', title }] },
+		extensions: {
+			distributed: {
+				protocolVersion: 1,
+				schemaHash: 'schema-one',
+				cacheScope: 'cache:one',
+				operation: CodecArtifact.id,
+				snapshot: {
+					scopeToken: 'snapshot:codec-items',
+					recordsComplete: true,
+					indexesComparable: true,
+					records: [
+						{
+							path: ['items', '0'],
+							model: Item.id,
+							scopeToken: 'record:item-1',
+							incarnation: '1',
+							revision: position,
+							tombstone: false
+						}
+					],
+					indexes: [
+						{
+							projection,
+							scopeToken: 'index:codec-items',
+							position,
+							resume
+						}
+					],
+					observations: []
+				}
+			}
+		}
+	};
+}
+
+function assertDeepFrozen(value) {
+	if (value === null || typeof value !== 'object') return;
+	assert.equal(Object.isFrozen(value), true);
+	for (const entry of Object.values(value)) assertDeepFrozen(entry);
+}
+
+async function flushMicrotasks() {
+	await Promise.resolve();
+	await Promise.resolve();
+	await new Promise((resolve) => setImmediate(resolve));
+}
+
+test('compiler variable codec canonicalizes ID, lists, filters, order, and key order', () => {
+	const singleton = canonicalizeOperationVariables(CodecArtifact, singletonVariables);
+	const expanded = canonicalizeOperationVariables(CodecArtifact, expandedVariables);
+
+	assert.deepEqual(singleton, expanded);
+	assert.deepEqual(singleton, {
+		id: '7',
+		offset: -1,
+		order: [{ priority: 'asc' }],
+		where: {
+			_and: [{ id: { _in: ['7'] }, priority: { _eq: 0 } }]
+		}
+	});
+	assertDeepFrozen(singleton);
+	assert.equal(JSON.stringify(singleton), JSON.stringify(expanded));
+});
+
+test('scalar canonicalization is deterministic and preserves omission versus null', () => {
+	const canonical = canonicalizeOperationVariables(CodecArtifact, {
+		id: -0,
+		big: -0,
+		blob: 'YQ==',
+		direction: 'asc',
+		payload: { z: -0, a: [true, 1] },
+		ratio: -0
+	});
+	assert.deepEqual(canonical, {
+		big: 0,
+		blob: 'YQ==',
+		direction: 'asc',
+		id: '0',
+		payload: { a: [true, 1], z: 0 },
+		ratio: 0
+	});
+	assertDeepFrozen(canonical);
+
+	const omitted = canonicalizeOperationVariables(CodecArtifact, {
+		id: '1',
+		where: undefined
+	});
+	const explicitNull = canonicalizeOperationVariables(CodecArtifact, {
+		id: '1',
+		where: null
+	});
+	assert.deepEqual(omitted, { id: '1' });
+	assert.deepEqual(explicitNull, { id: '1', where: null });
+	assert.notEqual(JSON.stringify(omitted), JSON.stringify(explicitNull));
+});
+
+test('canonical write and read variables share normalized index identity', () => {
+	const replica = createDistributedReplica();
+	replica.writeResult(
+		CodecArtifact,
+		singletonVariables,
+		codecWireFrame('canonical'),
+		'network'
+	);
+	const snapshot = replica.read(CodecArtifact, expandedVariables);
+	assert.equal(snapshot.status, 'ready');
+	assert.deepEqual(snapshot.data, {
+		items: [{ id: 'item-1', title: 'canonical' }]
+	});
+});
+
+test('invalid values, unknown inputs, sparse arrays, and accessors fail closed', () => {
+	for (const variables of [
+		{ id: Number.MAX_SAFE_INTEGER + 1 },
+		{ id: '1', blob: 'YQ' },
+		{ id: '1', blob: 'AB==' },
+		{ id: '1', offset: 2_147_483_648 },
+		{ id: '1', ratio: Number.POSITIVE_INFINITY },
+		{ id: '1', big: Number.MAX_SAFE_INTEGER + 1 },
+		{ id: '1', payload: { unsafe: Number.MAX_SAFE_INTEGER + 1 } },
+		{ id: '1', direction: 'sideways' },
+		{ id: '1', extra: undefined },
+		{ id: '1', where: { missing: { _eq: 1 } } },
+		{ id: '1', where: { priority: { _gt: 1 } } },
+		{ id: '1', where: { id: { _in: null } } },
+		{ id: '1', where: { id: { _in: [null] } } },
+		{ id: '1', order: { id: 'asc', priority: 'desc' } },
+		{ id: '1', where: { unplanned: 'not-an-object' } },
+		{ id: '1', payload: new Date() }
+	]) {
+		assert.throws(
+			() => canonicalizeOperationVariables(CodecArtifact, variables),
+			TypeError
+		);
+	}
+
+	const sparse = new Array(1);
+	assert.throws(
+		() =>
+			canonicalizeOperationVariables(CodecArtifact, {
+				id: '1',
+				where: { id: { _in: sparse } }
+			}),
+		/dense data-only input array/
+	);
+
+	let getterCalls = 0;
+	const accessor = [];
+	Object.defineProperty(accessor, '0', {
+		enumerable: true,
+		get() {
+			getterCalls += 1;
+			return '1';
+		}
+	});
+	accessor.length = 1;
+	assert.throws(
+		() =>
+			canonicalizeOperationVariables(CodecArtifact, {
+				id: '1',
+				where: { id: { _in: accessor } }
+			}),
+		/dense data-only input array/
+	);
+	assert.equal(getterCalls, 0);
+
+	const cyclicValue = {};
+	cyclicValue._not = cyclicValue;
+	assert.throws(
+		() =>
+			canonicalizeOperationVariables(CodecArtifact, {
+				id: '1',
+				where: cyclicValue
+			}),
+		/must not contain cycles/
+	);
+});
+
+test('deep acyclic filters fail with a typed depth error', () => {
+	const safetyArtifact = {
+		...CodecArtifact,
+		variableCodec: {
+			...variableCodec,
+			limits: { ...codecLimits, maxDepth: 100 }
+		}
+	};
+	let where = { id: { _eq: '1' } };
+	for (let depth = 0; depth < 70; depth += 1) {
+		where = { _not: where };
+	}
+	assert.throws(
+		() =>
+			canonicalizeOperationVariables(safetyArtifact, {
+				id: '1',
+				where
+			}),
+		(error) =>
+			error instanceof TypeError &&
+			error.message.startsWith('invalid GraphQL operation input at ') &&
+			error.message.endsWith('input nesting exceeds the supported depth')
+	);
+});
+
+test('filter semantic depth enforces exact and max-plus-one boundaries', () => {
+	const depthArtifact = {
+		...CodecArtifact,
+		variableCodec: {
+			...variableCodec,
+			limits: { ...codecLimits, maxDepth: 2 }
+		}
+	};
+	assert.deepEqual(
+		canonicalizeOperationVariables(depthArtifact, {
+			id: '1',
+			where: { _not: { _not: { id: { _eq: '1' }, _and: [] } } }
+		}).where,
+		{ _not: { _not: { _and: [], id: { _eq: '1' } } } }
+	);
+	for (const where of [
+		{ _not: { _not: { _not: { id: { _eq: '1' } } } } },
+		{ _not: { _not: { _not: null } } }
+	]) {
+		assert.throws(
+			() => canonicalizeOperationVariables(depthArtifact, { id: '1', where }),
+			/exceeding maxDepth 2/
+		);
+	}
+
+	const relationshipAtMax = {
+		...CodecArtifact,
+		variableCodec: {
+			...variableCodec,
+			limits: { ...codecLimits, maxDepth: 1 }
+		}
+	};
+	assert.deepEqual(
+		canonicalizeOperationVariables(relationshipAtMax, {
+			id: '1',
+			where: { owner: null }
+		}).where,
+		{ owner: null }
+	);
+	const relationshipPastMax = {
+		...relationshipAtMax,
+		variableCodec: {
+			...relationshipAtMax.variableCodec,
+			limits: { ...codecLimits, maxDepth: 0 }
+		}
+	};
+	assert.throws(
+		() =>
+			canonicalizeOperationVariables(relationshipPastMax, {
+				id: '1',
+				where: { owner: null }
+			}),
+		/exceeding maxDepth 0/
+	);
+	assert.deepEqual(
+		canonicalizeOperationVariables(relationshipPastMax, {
+			id: '1',
+			where: { _and: null, _or: [] }
+		}).where,
+		{ _and: null, _or: [] }
+	);
+});
+
+test('boolean and IN widths are checked after singleton coercion', () => {
+	const widthArtifact = {
+		...CodecArtifact,
+		variableCodec: {
+			...variableCodec,
+			limits: { maxDepth: 64, maxBoolWidth: 1, maxInList: 1 }
+		}
+	};
+	assert.deepEqual(
+		canonicalizeOperationVariables(widthArtifact, {
+			id: '1',
+			where: {
+				_and: { id: { _eq: 1 } },
+				id: { _in: 1 }
+			}
+		}).where,
+		{ _and: [{ id: { _eq: '1' } }], id: { _in: ['1'] } }
+	);
+	for (const where of [
+		{ _and: [{ id: { _eq: 1 } }, { id: { _eq: 2 } }] },
+		{ id: { _in: [1, 2] } }
+	]) {
+		assert.throws(
+			() => canonicalizeOperationVariables(widthArtifact, { id: '1', where }),
+			/exceeding max(BoolWidth|InList) 1/
+		);
+	}
+});
+
+test('per-variable maxItems applies after coercion while null skips it', () => {
+	const listArtifact = {
+		...CodecArtifact,
+		variableCodec: {
+			...variableCodec,
+			variables: {
+				...variableCodec.variables,
+				ids: {
+					kind: 'list',
+					nullable: true,
+					maxItems: 2,
+					item: {
+						kind: 'scalar',
+						scalar: 'ID',
+						codec: 'string',
+						nullable: false
+					}
+				}
+			}
+		}
+	};
+	assert.deepEqual(
+		canonicalizeOperationVariables(listArtifact, { id: '1', ids: 2 }).ids,
+		['2']
+	);
+	assert.deepEqual(
+		canonicalizeOperationVariables(listArtifact, { id: '1', ids: [2, 3] }).ids,
+		['2', '3']
+	);
+	assert.equal(
+		canonicalizeOperationVariables(listArtifact, { id: '1', ids: null }).ids,
+		null
+	);
+	assert.throws(
+		() =>
+			canonicalizeOperationVariables(listArtifact, {
+				id: '1',
+				ids: [1, 2, 3]
+			}),
+		/exceeding maxItems 2/
+	);
+});
+
+test('codec limits and per-variable constraints must be exact JS integers', () => {
+	const invalidCodecs = [
+		{ ...variableCodec, version: 2 },
+		{
+			...variableCodec,
+			limits: { ...codecLimits, maxDepth: Number.MAX_SAFE_INTEGER + 1 }
+		},
+		{
+			...variableCodec,
+			limits: { ...codecLimits, maxBoolWidth: -1 }
+		},
+		{
+			...variableCodec,
+			limits: { ...codecLimits, maxInList: 1.5 }
+		},
+		{
+			...variableCodec,
+			variables: {
+				...variableCodec.variables,
+				where: {
+					...variableCodec.variables.where,
+					filterBaseDepth: Number.MAX_SAFE_INTEGER + 1
+				}
+			}
+		},
+		{
+			...variableCodec,
+			variables: {
+				...variableCodec.variables,
+				values: {
+					kind: 'list',
+					nullable: true,
+					maxItems: Number.POSITIVE_INFINITY,
+					item: {
+						kind: 'scalar',
+						scalar: 'ID',
+						codec: 'string',
+						nullable: false
+					}
+				}
+			}
+		}
+	];
+	for (const invalidCodec of invalidCodecs) {
+		assert.throws(
+			() =>
+				canonicalizeOperationVariables(
+					{ ...CodecArtifact, variableCodec: invalidCodec },
+					{ id: '1' }
+				),
+			/invalid replica variable codec/
+		);
+	}
+});
+
+test('cyclic or incompatible codec artifacts fail without walking forever', () => {
+	const cyclicRef = { kind: 'list', nullable: true };
+	cyclicRef.item = cyclicRef;
+	const cyclicArtifact = {
+		...CodecArtifact,
+		variableCodec: {
+			version: 1,
+			limits: codecLimits,
+			variables: { value: cyclicRef },
+			inputs: {}
+		}
+	};
+	assert.throws(
+		() => canonicalizeOperationVariables(cyclicArtifact, { value: [] }),
+		/invalid replica variable codec/
+	);
+
+	const incompatibleArtifact = {
+		...CodecArtifact,
+		variableCodec: {
+			version: 1,
+			limits: codecLimits,
+			variables: {
+				where: {
+					kind: 'input',
+					name: 'bad_filter',
+					nullable: true,
+					filterBaseDepth: 0
+				}
+			},
+			inputs: {
+				bad_filter: {
+					kind: 'filter',
+					model: 'bad',
+					fields: [
+						{
+							field: 'count',
+							scalar: 'Int',
+							codec: 'int32',
+							nullable: false,
+							operators: ['_contains']
+						}
+					],
+					relationships: []
+				}
+			}
+		}
+	};
+	assert.throws(
+		() => canonicalizeOperationVariables(incompatibleArtifact, {}),
+		/invalid replica variable codec/
+	);
+});
+
+test('protocol artifacts require a codec before binding, cache access, or transport', async () => {
+	const fetches = [];
+	const replica = createDistributedReplica({
+		transport: {
+			fetch(request) {
+				fetches.push(request);
+				return new Promise(() => undefined);
+			}
+		}
+	});
+	const missingCodec = Object.freeze({
+		...CodecArtifact,
+		variableCodec: undefined
+	});
+	const unboundWithCodec = Object.freeze({
+		...CodecArtifact,
+		protocol: undefined
+	});
+	assert.throws(
+		() =>
+			canonicalizeOperationVariables(
+				unboundWithCodec,
+				singletonVariables
+			),
+		/replica artifact protocol binding is invalid/
+	);
+	for (const useArtifact of [
+		() => canonicalizeOperationVariables(missingCodec, singletonVariables),
+		() => replica.read(missingCodec, singletonVariables),
+		() =>
+			replica.writeResult(
+				missingCodec,
+				singletonVariables,
+				codecWireFrame('must not write'),
+				'network'
+			),
+		() => replica.watch(missingCodec, singletonVariables)
+	]) {
+		assert.throws(useArtifact, /protocol-v1 replica artifact requires variableCodec/);
+	}
+	await flushMicrotasks();
+	assert.equal(fetches.length, 0);
+	assert.equal(replica.inspectRecord(Item, 'item-1'), undefined);
+
+	const otherSchema = Object.freeze({
+		...CodecArtifact,
+		protocol: Object.freeze({
+			...CodecArtifact.protocol,
+			schemaHash: 'schema-two'
+		})
+	});
+	assert.equal(replica.read(otherSchema, expandedVariables).complete, false);
+});
+
+test('generated protocol identity is mandatory before cache identity or transport', async () => {
+	const fetches = [];
+	const replica = createDistributedReplica({
+		transport: {
+			fetch(request) {
+				fetches.push(request);
+				return new Promise(() => undefined);
+			}
+		}
+	});
+	const malformed = [
+		[
+			Object.freeze({ ...CodecArtifact, protocol: undefined }),
+			/replica artifact protocol binding is invalid/
+		],
+		[
+			Object.freeze({
+				...CodecArtifact,
+				protocol: Object.freeze({
+					...CodecArtifact.protocol,
+					surface: undefined
+				})
+			}),
+			/replica artifact client surface is invalid/
+		],
+		[
+			Object.freeze({
+				...CodecArtifact,
+				protocol: Object.freeze({
+					...CodecArtifact.protocol,
+					trustedPresets: undefined
+				})
+			}),
+			/replica artifact trusted preset contract is invalid/
+		],
+		[
+			Object.freeze({
+				...CodecArtifact,
+				protocol: Object.freeze({
+					...CodecArtifact.protocol,
+					operation: 'query:not-the-artifact'
+				})
+			}),
+			/replica artifact protocol binding is invalid/
+		]
+	];
+	for (const [artifact, expected] of malformed) {
+		assert.throws(
+			() => canonicalizeOperationVariables(artifact, singletonVariables),
+			expected
+		);
+		assert.throws(() => replica.read(artifact, singletonVariables), expected);
+		assert.throws(() => replica.watch(artifact, singletonVariables), expected);
+	}
+	await flushMicrotasks();
+	assert.equal(fetches.length, 0);
+});
+
+test('replica rejects schema and unbound artifact mixing before cache reads without purging', () => {
+	const replica = createDistributedReplica();
+	replica.writeResult(
+		CodecArtifact,
+		singletonVariables,
+		codecWireFrame(),
+		'network'
+	);
+	assert.deepEqual(replica.read(CodecArtifact, expandedVariables).data, {
+		items: [{ id: 'item-1', title: 'schema one' }]
+	});
+
+	const otherSchema = Object.freeze({
+		...CodecArtifact,
+		protocol: Object.freeze({
+			...CodecArtifact.protocol,
+			schemaHash: 'schema-two'
+		})
+	});
+	assert.throws(
+		() => replica.read(otherSchema, expandedVariables),
+		/does not match the active replica binding/
+	);
+	const unboundArtifact = Object.freeze({
+		...CodecArtifact,
+		protocol: undefined
+	});
+	assert.throws(
+		() => replica.read(unboundArtifact, expandedVariables),
+		/replica artifact protocol binding is invalid/
+	);
+	assert.throws(
+		() =>
+			replica.writeResult(
+				otherSchema,
+				expandedVariables,
+				codecWireFrame('wrong schema'),
+				'network'
+			),
+		/does not match the active replica binding/
+	);
+	assert.deepEqual(replica.read(CodecArtifact, expandedVariables).data, {
+		items: [{ id: 'item-1', title: 'schema one' }]
+	});
+});
+
+test('an invalid write source cannot bind a replica', () => {
+	const replica = createDistributedReplica();
+	assert.throws(
+		() =>
+			replica.writeResult(
+				CodecArtifact,
+				singletonVariables,
+				codecWireFrame(),
+				'invalid-source'
+			),
+		/unsupported replica write source/
+	);
+	const otherSchema = Object.freeze({
+		...CodecArtifact,
+		protocol: Object.freeze({
+			...CodecArtifact.protocol,
+			schemaHash: 'schema-two'
+		})
+	});
+	assert.equal(replica.read(otherSchema, expandedVariables).complete, false);
+});
+
+test('watch validates before transport and sends only canonical frozen variables', async () => {
+	const fetches = [];
+	const transport = {
+		fetch(request) {
+			fetches.push(request);
+			return new Promise(() => undefined);
+		}
+	};
+	const replica = createDistributedReplica({ transport });
+
+	assert.throws(
+		() =>
+			replica.watch(CodecArtifact, {
+				id: '1',
+				where: { unknown: {} }
+			}),
+		/unknown filter field/
+	);
+	await flushMicrotasks();
+	assert.equal(fetches.length, 0);
+
+	const first = replica.watch(CodecArtifact, singletonVariables);
+	const second = replica.watch(CodecArtifact, expandedVariables);
+	await flushMicrotasks();
+	assert.equal(fetches.length, 1);
+	assert.deepEqual(fetches[0].variables, canonicalizeOperationVariables(
+		CodecArtifact,
+		singletonVariables
+	));
+	assertDeepFrozen(fetches[0].variables);
+
+	const sameSchemaOtherOperation = Object.freeze({
+		...CodecArtifact,
+		id: 'query:codec-items-other',
+		protocol: Object.freeze({
+			...CodecArtifact.protocol,
+			operation: 'query:codec-items-other'
+		})
+	});
+	const third = replica.watch(sameSchemaOtherOperation, expandedVariables);
+	await flushMicrotasks();
+	assert.equal(fetches.length, 2);
+	assert.equal(fetches[1].operationId, sameSchemaOtherOperation.id);
+
+	const otherSchema = Object.freeze({
+		...CodecArtifact,
+		protocol: Object.freeze({
+			...CodecArtifact.protocol,
+			schemaHash: 'schema-two'
+		})
+	});
+	assert.throws(
+		() => replica.watch(otherSchema, expandedVariables),
+		/does not match the active replica binding/
+	);
+	await flushMicrotasks();
+	assert.equal(fetches.length, 2);
+
+	const mismatchedOperation = {
+		...CodecArtifact,
+		protocol: { ...CodecArtifact.protocol, operation: 'query:not-the-artifact' }
+	};
+	assert.throws(
+		() => replica.watch(mismatchedOperation, expandedVariables),
+		/protocol binding is invalid/
+	);
+	assert.equal(fetches.length, 2);
+
+	first.destroy();
+	second.destroy();
+	third.destroy();
+});
diff --git a/js/tests/sveltekit-adapter.test.mjs b/js/tests/sveltekit-adapter.test.mjs
new file mode 100644
index 00000000..16c8a5fb
--- /dev/null
+++ b/js/tests/sveltekit-adapter.test.mjs
@@ -0,0 +1,488 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	bindSveltekitOperation,
+	createPageDataSessionSource,
+	createDistributedSvelteKit,
+	defineDistributedSvelteKitOperation,
+	provideDistributedSvelteKitClient,
+	useDistributedSvelteKitClient,
+	useDistributedSvelteKitCommands
+} from '../dist/sveltekit/index.js';
+import { getAllContexts } from 'svelte';
+import { render } from 'svelte/server';
+import {
+	assertReplicaAdapterConformance,
+	ControlledReplicaTransport,
+	REACT_FIXTURE_SCHEMA,
+	TodosArtifact,
+	todoFrame
+} from './fixtures/adapter-conformance.mjs';
+import {
+	createDistributedReplica,
+	createReplicaCommandRuntime,
+	createReplicaDiagnostics
+} from '../dist/replica/index.js';
+import { replicaCommandProjectedLifecycle } from '../dist/replica/command-runtime.js';
+
+async function flushMicrotasks() {
+	for (let iteration = 0; iteration < 12; iteration += 1) {
+		await Promise.resolve();
+	}
+}
+
+function jsonResponse(body, status = 200) {
+	return {
+		status,
+		statusText: status === 200 ? 'OK' : 'Error',
+		text: async () => JSON.stringify(body)
+	};
+}
+
+test('generated wrappers resolve the nearest tree-local client and never capture module state', () => {
+	const wrapper = defineDistributedSvelteKitOperation(TodosArtifact);
+	const calls = [];
+	const client = (label) => ({
+		commands: Object.freeze({ label }),
+		operation(artifact) {
+			assert.equal(artifact, TodosArtifact);
+			return {
+				artifact,
+				use(...args) {
+					calls.push({ label, kind: 'use', args });
+					return { label, args };
+				},
+				read(variables) {
+					calls.push({ label, kind: 'read', variables });
+					return { label, variables };
+				}
+			};
+		}
+	});
+	const user = client('user');
+	const admin = client('admin');
+
+	void render(() => {
+		assert.equal(provideDistributedSvelteKitClient(user), user);
+		assert.equal(useDistributedSvelteKitClient(), user);
+		assert.deepEqual(useDistributedSvelteKitCommands(), { label: 'user' });
+		assert.deepEqual(wrapper.use({ limit: 1 }), {
+			label: 'user',
+			args: [{ limit: 1 }]
+		});
+
+		void render(
+			() => {
+				assert.equal(
+					useDistributedSvelteKitClient(),
+					user,
+					'a child inherits the nearest parent client'
+				);
+				provideDistributedSvelteKitClient(admin);
+				assert.deepEqual(useDistributedSvelteKitCommands(), { label: 'admin' });
+				assert.deepEqual(wrapper.read({ limit: 2 }), {
+					label: 'admin',
+					variables: { limit: 2 }
+				});
+			},
+			{ context: new Map(getAllContexts()) }
+		).body;
+
+		assert.equal(
+			useDistributedSvelteKitClient(),
+			user,
+			'leaving an elevated subtree restores the user-safe boundary'
+		);
+	}).body;
+	assert.deepEqual(
+		calls.map(({ label, kind }) => `${label}:${kind}`),
+		['user:use', 'admin:read']
+	);
+});
+
+test('page-data session source feeds one mutable auth lifecycle', () => {
+	const page = createPageDataSessionSource({
+		accessToken: 'token-a',
+		engineRole: 'user'
+	});
+	const notifications = [];
+	const unsubscribe = page.session.subscribe(() => {
+		notifications.push(page.get().accessToken);
+	});
+
+	assert.deepEqual(page.session.getAuth(), {
+		accessToken: 'token-a',
+		userId: undefined,
+		role: 'user'
+	});
+	page.set({
+		accessToken: null,
+		engineRole: 'admin',
+		session: { user: { id: 'dev-admin' } }
+	});
+	assert.deepEqual(notifications, [null]);
+	assert.deepEqual(page.session.getAuth(), {
+		accessToken: null,
+		userId: 'dev-admin',
+		role: 'admin'
+	});
+	unsubscribe();
+	page.set({ accessToken: 'ignored-after-unsubscribe' });
+	assert.deepEqual(notifications, [null]);
+});
+
+async function mountSveltekitQuery({
+	replica,
+	artifact,
+	variables,
+	options
+}) {
+	const operation = bindSveltekitOperation(replica, artifact);
+	const store = operation.use(variables, options);
+	let current = store.get();
+	const unsubscribe = store.subscribe((snapshot) => {
+		current = snapshot;
+	});
+
+	return {
+		getSnapshot() {
+			assert.ok(current, 'SvelteKit query must expose a snapshot');
+			return current;
+		},
+		async settle(action) {
+			action?.();
+			await flushMicrotasks();
+		},
+		refetch() {
+			return store.refetch();
+		},
+		async dispose() {
+			unsubscribe();
+			store.destroy();
+			await flushMicrotasks();
+		}
+	};
+}
+
+test('SvelteKit passes the shared replica adapter conformance contract', async () => {
+	await assertReplicaAdapterConformance({ mount: mountSveltekitQuery });
+});
+
+test('Svelte navigation owns exactly one lazy watch and live subscription', async () => {
+	const transport = new ControlledReplicaTransport();
+	const replica = createDistributedReplica({ transport });
+	const store = bindSveltekitOperation(replica, TodosArtifact).use(
+		{},
+		{ live: true }
+	);
+
+	assert.equal(store.get().status, 'loading');
+	assert.equal(transport.fetches.length, 0, 'constructing a store is side-effect free');
+	assert.equal(transport.lives.length, 0);
+
+	const first = store.subscribe(() => undefined);
+	const second = store.subscribe(() => undefined);
+	await flushMicrotasks();
+	assert.equal(transport.fetches.length, 1);
+	assert.equal(transport.lives.length, 1);
+	assert.equal(transport.lives[0].closed, false);
+
+	first();
+	assert.equal(transport.lives[0].closed, false, 'one subscriber still owns the watch');
+	second();
+	assert.equal(transport.lives[0].closed, true, 'route teardown retires live work');
+
+	const third = store.subscribe(() => undefined);
+	await flushMicrotasks();
+	assert.equal(
+		transport.fetches.length,
+		1,
+		'navigation back coalesces the still-pending HTTP fetch'
+	);
+	assert.equal(transport.lives.length, 2, 'navigation back starts one new live stream');
+	assert.equal(transport.lives[1].closed, false);
+	third();
+	assert.equal(transport.lives[1].closed, true);
+	store.destroy();
+	assert.throws(() => store.subscribe(() => undefined), /query is destroyed/);
+});
+
+test('component SSR subscriptions stay transport-free when browser is false', async () => {
+	let fetches = 0;
+	class ForbiddenWebSocket {
+		constructor() {
+			throw new Error('component SSR must not open WebSocket');
+		}
+	}
+	const client = createDistributedSvelteKit({
+		session: { getAuth: () => ({ accessToken: 'server-token' }) },
+		browser: false,
+		fetch: async () => {
+			fetches += 1;
+			throw new Error('component SSR must not fetch');
+		},
+		webSocket: ForbiddenWebSocket
+	});
+	const store = client.operation(TodosArtifact).use();
+	const values = [];
+	const unsubscribe = store.subscribe((snapshot) => values.push(snapshot.status));
+	await flushMicrotasks();
+	assert.deepEqual(values, ['loading']);
+	assert.equal(fetches, 0);
+	unsubscribe();
+	client.destroy();
+});
+
+test('caller projection cancellation does not hide a globally pending command', async () => {
+	let resolveGlobal;
+	let rejectCaller;
+	const globallyProjected = new Promise((resolve) => {
+		resolveGlobal = resolve;
+	});
+	const callerProjected = new Promise((_resolve, reject) => {
+		rejectCaller = reject;
+	});
+	const receiptValue = {
+		commandId: 'command-pending-after-caller-deadline',
+		state: 'accepted_pending_projection',
+		result: { accepted: true },
+		metadata: {},
+		status: () => Promise.resolve({ state: 'accepted_pending_projection' }),
+		projected: callerProjected
+	};
+	Object.defineProperty(receiptValue, replicaCommandProjectedLifecycle, {
+		value: globallyProjected
+	});
+	const receipt = Object.freeze(receiptValue);
+	const client = createDistributedSvelteKit({
+		session: { getAuth: () => ({ accessToken: 'token' }) },
+		browser: false,
+		createCommands() {
+			return {
+				commands: {
+					save: () => Promise.resolve(receipt)
+				},
+				dispose() {}
+			};
+		}
+	});
+	const query = client.operation(TodosArtifact).use();
+	const unsubscribe = query.subscribe(() => undefined);
+
+	const returned = await client.commands.save();
+	assert.equal(returned, receipt);
+	assert.deepEqual(query.get().pending, [receipt]);
+
+	const callerOutcome = assert.rejects(
+		callerProjected,
+		/caller deadline/
+	);
+	rejectCaller(new Error('caller deadline'));
+	await callerOutcome;
+	await flushMicrotasks();
+	assert.deepEqual(
+		query.get().pending,
+		[receipt],
+		'the adapter must observe the command-wide causal lifecycle'
+	);
+
+	resolveGlobal({
+		commandId: receipt.commandId,
+		state: 'projected'
+	});
+	await flushMicrotasks();
+	assert.deepEqual(query.get().pending, []);
+	unsubscribe();
+	query.destroy();
+	client.destroy();
+});
+
+test('pre-subscribe refetch uses one temporary HTTP watch and never opens live', async () => {
+	const transport = new ControlledReplicaTransport();
+	const replica = createDistributedReplica({ transport });
+	const store = bindSveltekitOperation(replica, TodosArtifact).use(
+		{},
+		{ live: true }
+	);
+
+	const refetch = store.refetch();
+	await flushMicrotasks();
+	assert.equal(transport.fetches.length, 1);
+	assert.equal(transport.lives.length, 0);
+	transport.fetches[0].response.resolve(
+		todoFrame(
+			TodosArtifact,
+			[{ id: 'todo-1', title: 'prefetched', status: 'open' }],
+			{ position: '1' }
+		)
+	);
+	await refetch;
+	assert.equal(store.get().data.todos[0].title, 'prefetched');
+
+	const unsubscribe = store.subscribe(() => undefined);
+	await flushMicrotasks();
+	assert.equal(transport.lives.length, 1);
+	assert.equal(transport.fetches.length, 1, 'hydrated cache avoids a duplicate first fetch');
+	unsubscribe();
+	store.destroy();
+});
+
+test('Svelte uses replica-owned revalidation with an undecorated GraphQL transport', async () => {
+	const requests = [];
+	let position = 0;
+	let commandTransport;
+	const client = createDistributedSvelteKit({
+		session: { getAuth: () => ({ accessToken: 'token' }) },
+		fetch: async (_url, init) => {
+			requests.push(JSON.parse(init.body));
+			position += 1;
+			return jsonResponse(
+				todoFrame(
+					TodosArtifact,
+					[{ id: 'todo-1', title: `server-${position}`, status: 'open' }],
+					{ position: String(position) }
+				)
+			);
+		},
+		createCommands(_replica, transport) {
+			commandTransport = transport;
+			return {
+				commands: Object.freeze({}),
+				dispose() {}
+			};
+		}
+	});
+	const store = client.operation(TodosArtifact).use({}, { live: false });
+	const unsubscribe = store.subscribe(() => undefined);
+	await store.refetch();
+	assert.equal(requests.length, 1);
+	assert.equal(store.get().status, 'ready');
+	assert.equal(commandTransport, client.transport);
+	assert.equal(commandTransport.revalidate, undefined);
+
+	const plan = (dependencies, models = []) => ({
+		dependencies,
+		models,
+		relationships: []
+	});
+	await client.replica.revalidate(plan(['unrelated']));
+	assert.equal(
+		requests.length,
+		1,
+		'an unrelated dependency inventory must not refresh this operation'
+	);
+
+	await Promise.all([
+		client.replica.revalidate(plan(['todos'])),
+		client.replica.revalidate(plan(['todos']))
+	]);
+	assert.equal(requests.length, 2, 'matching concurrent plans share one HTTP request');
+	assert.equal(store.get().data.todos[0].title, 'server-2');
+
+	await client.replica.revalidate(plan([], ['TodoView']));
+	assert.equal(requests.length, 3, 'model inventory also targets the operation');
+
+	unsubscribe();
+	store.destroy();
+	client.destroy();
+});
+
+test('Svelte composition shares one diagnostics sink with operations and generated commands', () => {
+	const diagnostics = createReplicaDiagnostics();
+	const operationHash = `sha256:${'b'.repeat(64)}`;
+	const RenameTodo = Object.freeze({
+		version: 1,
+		name: 'todo.rename',
+		mutationField: 'renameTodo',
+		document:
+			'mutation RenameTodo($commandId: ID!, $input: RenameTodoInput!) { renameTodo(commandId: $commandId, input: $input) }',
+		operationHash,
+		protocol: Object.freeze({
+			version: 1,
+			schemaHash: REACT_FIXTURE_SCHEMA,
+			protocolHash: `sha256:${'c'.repeat(64)}`,
+			surface: Object.freeze({ kind: 'role', name: 'user' }),
+			operation: operationHash,
+			trustedPresets: Object.freeze([])
+		}),
+		input: Object.freeze({
+			kind: 'object',
+			definition: Object.freeze({
+				name: 'RenameTodoInput',
+				fields: Object.freeze([
+					Object.freeze({
+						name: 'id',
+						typeName: 'ID',
+						nullable: false,
+						list: false,
+						itemNullable: false,
+						codec: 'string'
+					})
+				])
+			})
+		}),
+		output: Object.freeze({
+			kind: 'object',
+			definition: Object.freeze({
+				name: 'RenameTodoResult',
+				fields: Object.freeze([
+					Object.freeze({
+						name: 'accepted',
+						typeName: 'Boolean',
+						nullable: false,
+						list: false,
+						itemNullable: false,
+						codec: 'boolean'
+					})
+				])
+			})
+		}),
+		consistency: 'accepted',
+		effects: Object.freeze({
+			version: 1,
+			operations: Object.freeze([
+				Object.freeze({
+					kind: 'invalidate_model',
+					model: 'TodoView'
+				})
+			]),
+			fallback: 'revalidate'
+		}),
+		revalidation: Object.freeze({
+			version: 1,
+			required: true,
+			dependencies: Object.freeze(['todos']),
+			models: Object.freeze(['TodoView']),
+			relationships: Object.freeze([])
+		}),
+		trustedPresets: Object.freeze([])
+	});
+	let factoryOptions;
+	const client = createDistributedSvelteKit({
+		session: { getAuth: () => ({ accessToken: 'token' }) },
+		replica: { diagnostics },
+		createCommands(replica, transport, options) {
+			factoryOptions = options;
+			return createReplicaCommandRuntime(
+				replica,
+				transport,
+				{ renameTodo: RenameTodo },
+				options
+			);
+		}
+	});
+
+	client.operation(TodosArtifact).read({});
+	const snapshot = diagnostics.snapshot();
+	assert.equal(factoryOptions.diagnostics, diagnostics);
+	assert.deepEqual(
+		snapshot.artifacts.operations.map(({ id }) => id),
+		[TodosArtifact.id]
+	);
+	assert.deepEqual(
+		snapshot.artifacts.commands.map(({ name }) => name),
+		[RenameTodo.name]
+	);
+	client.destroy();
+});
diff --git a/js/tests/sveltekit-ssr.test.mjs b/js/tests/sveltekit-ssr.test.mjs
new file mode 100644
index 00000000..79161249
--- /dev/null
+++ b/js/tests/sveltekit-ssr.test.mjs
@@ -0,0 +1,325 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+	createDistributedSvelteKit,
+	createDistributedSvelteKitServer
+} from '../dist/sveltekit/index.js';
+import {
+	REACT_FIXTURE_SCHEMA,
+	TodosArtifact,
+	todoFrame
+} from './fixtures/adapter-conformance.mjs';
+
+function jsonResponse(body, status = 200) {
+	return {
+		status,
+		statusText: status === 200 ? 'OK' : 'Error',
+		text: async () => JSON.stringify(body)
+	};
+}
+
+async function flushMicrotasks() {
+	for (let iteration = 0; iteration < 16; iteration += 1) {
+		await Promise.resolve();
+	}
+}
+
+class SsrWebSocket {
+	static CONNECTING = 0;
+	static OPEN = 1;
+	static CLOSING = 2;
+	static CLOSED = 3;
+	static instances = [];
+
+	readyState = SsrWebSocket.CONNECTING;
+	closed = false;
+	sent = [];
+
+	constructor(url, protocol) {
+		this.url = url;
+		this.protocol = protocol;
+		SsrWebSocket.instances.push(this);
+	}
+
+	send(value) {
+		this.sent.push(JSON.parse(value));
+	}
+
+	close() {
+		this.closed = true;
+		this.readyState = SsrWebSocket.CLOSED;
+	}
+}
+
+function routeBinding(artifact = TodosArtifact) {
+	return Object.freeze({
+		plan: Object.freeze({
+			operation: 'Todos',
+			route: '/todos',
+			discovery: 'convention'
+		}),
+		artifact
+	});
+}
+
+function serverHarness() {
+	const calls = [];
+	let variablesCalls = 0;
+	const server = createDistributedSvelteKitServer({
+		routes: [routeBinding()],
+		getSession: async (event) => event.locals.session,
+		getRole: () => 'user',
+		variables: {
+			Todos: () => {
+				variablesCalls += 1;
+				return {};
+			}
+		}
+	});
+	const event = (token, position = '1') => ({
+		locals: {
+			session: {
+				accessToken: token,
+				user: { id: token }
+			}
+		},
+		route: { id: '/todos' },
+		url: new URL('https://app.example/todos'),
+		async fetch(url, init) {
+			const body = JSON.parse(init.body);
+			const authorization = init.headers.authorization;
+			calls.push({ url, init, body, authorization });
+			assert.deepEqual(body.extensions.distributed.client, {
+				surface: { kind: 'role', name: 'user' },
+				schemaHash: REACT_FIXTURE_SCHEMA
+			});
+			assert.equal(authorization, `Bearer ${token}`);
+			return jsonResponse(
+				todoFrame(
+					TodosArtifact,
+					[
+						{
+							id: `todo-${token}`,
+							title: `${token}:${position}`,
+							status: 'open'
+						}
+					],
+					{
+						cacheScope: `cache:${token}`,
+						position
+					}
+				)
+			);
+		}
+	});
+	return {
+		server,
+		event,
+		calls,
+		get variablesCalls() {
+			return variablesCalls;
+		}
+	};
+}
+
+test('static @load SSR is request-isolated and hydration avoids a duplicate first fetch', async () => {
+	const harness = serverHarness();
+	const [alice, bob] = await Promise.all([
+		harness.server.load(harness.event('alice')),
+		harness.server.load(harness.event('bob'))
+	]);
+
+	assert.equal(harness.calls.length, 2);
+	assert.equal(harness.variablesCalls, 2, 'variables run exactly once per request');
+	assert.equal(alice.gqlError, null);
+	assert.equal(bob.gqlError, null);
+	assert.equal(alice.distributed.state.scope.cacheScope, 'cache:alice');
+	assert.equal(bob.distributed.state.scope.cacheScope, 'cache:bob');
+	assert.equal(JSON.stringify(alice.distributed).includes('bob'), false);
+	assert.equal(JSON.stringify(bob.distributed).includes('alice'), false);
+
+	SsrWebSocket.instances.length = 0;
+	let browserFetches = 0;
+	const client = createDistributedSvelteKit({
+		session: { getAuth: () => ({ accessToken: 'alice' }) },
+		hydration: alice.distributed,
+		authority: alice.distributedAuthority,
+		fetch: async () => {
+			browserFetches += 1;
+			throw new Error('hydrated first render must not fetch');
+		},
+		webSocket: SsrWebSocket
+	});
+	const todos = client.operation(TodosArtifact).use();
+	assert.equal(todos.get().status, 'ready');
+	assert.equal(todos.get().data.todos[0].title, 'alice:1');
+	assert.equal(browserFetches, 0);
+	assert.equal(SsrWebSocket.instances.length, 0);
+
+	const unsubscribe = todos.subscribe(() => undefined);
+	await flushMicrotasks();
+	assert.equal(browserFetches, 0);
+	assert.equal(SsrWebSocket.instances.length, 1, '@live attaches after hydration');
+	unsubscribe();
+	assert.equal(SsrWebSocket.instances[0].closed, true);
+	client.destroy();
+});
+
+test('replica state never self-authorizes hydration scope', async () => {
+	const harness = serverHarness();
+	const [alice, bob] = await Promise.all([
+		harness.server.load(harness.event('alice')),
+		harness.server.load(harness.event('bob'))
+	]);
+
+	assert.throws(
+		() =>
+			createDistributedSvelteKit({
+				session: { getAuth: () => ({ accessToken: 'alice' }) },
+				hydration: alice.distributed
+			}),
+		/separate trusted SSR authority/
+	);
+
+	const client = createDistributedSvelteKit({
+		session: { getAuth: () => ({ accessToken: 'bob' }) }
+	});
+	assert.equal(
+		client.hydrate(alice.distributed, bob.distributedAuthority),
+		false,
+		'a replayed user-A state fails against current user-B page authority'
+	);
+	assert.equal(client.replica.scope, undefined);
+
+	const tampered = structuredClone(alice.distributed);
+	tampered.state.scope.cacheScope = 'cache:forged';
+	assert.equal(
+		client.hydrate(tampered, alice.distributedAuthority),
+		false,
+		'tampered state scope fails against the separately carried authority'
+	);
+	assert.equal(client.replica.scope, undefined);
+	client.destroy();
+});
+
+test('route misses do no GraphQL work and same-scope navigation replaces hydration', async () => {
+	const harness = serverHarness();
+	const missed = await harness.server.load({
+		...harness.event('alice'),
+		route: { id: '/session' },
+		url: new URL('https://app.example/session')
+	});
+	assert.equal(harness.calls.length, 0);
+	assert.equal(missed.distributed, undefined);
+	assert.equal(missed.gqlError, null);
+
+	const first = await harness.server.load(harness.event('alice', '1'));
+	const second = await harness.server.load(harness.event('alice', '2'));
+	let browserFetches = 0;
+	const client = createDistributedSvelteKit({
+		session: { getAuth: () => ({ accessToken: 'alice' }) },
+		hydration: first.distributed,
+		authority: first.distributedAuthority,
+		fetch: async () => {
+			browserFetches += 1;
+			throw new Error('navigation hydration must not fetch');
+		},
+		webSocket: SsrWebSocket
+	});
+	const todos = client.operation(TodosArtifact).use({}, { live: false });
+	const values = [];
+	const unsubscribe = todos.subscribe((snapshot) => {
+		values.push(snapshot.data.todos?.[0]?.title);
+	});
+	assert.equal(
+		client.hydrate(second.distributed, second.distributedAuthority),
+		true
+	);
+	assert.equal(todos.get().data.todos[0].title, 'alice:2');
+	assert.equal(values.at(-1), 'alice:2');
+	assert.equal(browserFetches, 0);
+	unsubscribe();
+	client.destroy();
+});
+
+test('auth changes purge old data, abort live work, and reject cross-scope hydration', async () => {
+	const harness = serverHarness();
+	const [alice, bob] = await Promise.all([
+		harness.server.load(harness.event('alice')),
+		harness.server.load(harness.event('bob'))
+	]);
+	let credential = { accessToken: 'alice' };
+	const listeners = new Set();
+	const requests = [];
+	SsrWebSocket.instances.length = 0;
+	const client = createDistributedSvelteKit({
+		session: {
+			getAuth: () => credential,
+			subscribe(listener) {
+				listeners.add(listener);
+				return () => listeners.delete(listener);
+			}
+		},
+		hydration: alice.distributed,
+		authority: alice.distributedAuthority,
+		fetch: (url, init) => {
+			requests.push({ url, init });
+			return new Promise(() => undefined);
+		},
+		webSocket: SsrWebSocket
+	});
+	const todos = client.operation(TodosArtifact).use();
+	const unsubscribe = todos.subscribe(() => undefined);
+	await flushMicrotasks();
+	assert.equal(todos.get().data.todos[0].title, 'alice:1');
+	assert.equal(SsrWebSocket.instances.length, 1);
+
+	assert.equal(
+		client.hydrate(bob.distributed, alice.distributedAuthority),
+		false,
+		'replayed state cannot authorize itself against current page authority'
+	);
+	assert.equal(todos.get().complete, false);
+	assert.equal(SsrWebSocket.instances[0].closed, true);
+
+	credential = {};
+	for (const listener of listeners) listener();
+	await flushMicrotasks();
+	assert.equal(todos.get().complete, false);
+	assert.deepEqual(todos.get().data, {});
+	assert.equal(requests.length, 2);
+	assert.equal(requests[0].init.signal.aborted, true);
+	assert.equal(requests[1].init.headers.authorization, undefined);
+
+	unsubscribe();
+	client.destroy();
+});
+
+test('one browser replica refuses to mix user and elevated generated surfaces', async () => {
+	const harness = serverHarness();
+	const alice = await harness.server.load(harness.event('alice'));
+	const client = createDistributedSvelteKit({
+		session: { getAuth: () => ({ accessToken: 'alice' }) },
+		hydration: alice.distributed,
+		authority: alice.distributedAuthority
+	});
+	client.operation(TodosArtifact).read({});
+
+	const adminOperation = Object.freeze({
+		...TodosArtifact,
+		id: 'query:admin-todos',
+		document: 'query AdminTodos { todos { id title status } }',
+		protocol: Object.freeze({
+			...TodosArtifact.protocol,
+			surface: Object.freeze({ kind: 'role', name: 'admin' }),
+			operation: 'query:admin-todos'
+		}),
+		live: undefined
+	});
+	assert.throws(
+		() => client.operation(adminOperation).read({}),
+		/active replica binding/
+	);
+	client.destroy();
+});
diff --git a/js/tests/sveltekit-vite.test.mjs b/js/tests/sveltekit-vite.test.mjs
new file mode 100644
index 00000000..8bbf0519
--- /dev/null
+++ b/js/tests/sveltekit-vite.test.mjs
@@ -0,0 +1,534 @@
+import assert from 'node:assert/strict';
+import {
+	mkdtemp,
+	mkdir,
+	readFile,
+	rm,
+	symlink,
+	writeFile
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Worker } from 'node:worker_threads';
+import test from 'node:test';
+
+import {
+	checkDistributedSvelteKit,
+	distributedSvelteKit,
+	distributedSvelteKitAliases,
+	generateDistributedSvelteKit
+} from '../dist/sveltekit/vite.js';
+
+const fakeDctlSource = String.raw`
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  writeFileSync
+} from 'node:fs';
+
+const args = process.argv.slice(2);
+appendFileSync(process.env.DISTRIBUTED_FAKE_LOG, JSON.stringify(args) + '\n');
+
+if (args[0] === 'client-manifest') {
+  process.stdout.write(JSON.stringify({ version: 7, source: args.at(-1) }));
+  process.exit(0);
+}
+
+if (args[0] !== 'client') {
+  process.stderr.write('unexpected fake command');
+  process.exit(64);
+}
+
+const value = (name) => args[args.indexOf(name) + 1];
+const surface = value('--surface') ?? value('--role');
+if (surface === process.env.DISTRIBUTED_FAKE_FAIL_SURFACE) {
+  process.stdout.write('sensitive schema and policy payload');
+  process.stderr.write('synthetic compiler failure');
+  process.exit(2);
+}
+
+const out = value('--out');
+if (args.includes('--check')) {
+  if (!existsSync(out + '/sveltekit.ts')) {
+    process.stderr.write('missing generated entrypoint');
+    process.exit(3);
+  }
+  process.stdout.write('fake client is current\n');
+  process.exit(0);
+}
+const delay = Number(process.env.DISTRIBUTED_FAKE_DELAY_MS ?? 0);
+if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay));
+mkdirSync(out, { recursive: true });
+writeFileSync(
+  out + '/sveltekit.ts',
+  '/** GENERATED by dctl client. Do not edit. */\nexport const surface = ' +
+    JSON.stringify(surface) + ';\n'
+);
+writeFileSync(
+  out + '/manifest.json',
+  JSON.stringify({ compiler_manifest_version: 1, operations: [] }) + '\n'
+);
+process.stdout.write('generated fake client\n');
+`;
+
+async function fixture(t) {
+	const root = await mkdtemp(join(tmpdir(), 'distributed-vite-test-'));
+	const script = join(root, 'fake-dctl.mjs');
+	const log = join(root, 'commands.log');
+	await writeFile(script, fakeDctlSource, 'utf8');
+	await writeFile(log, '', 'utf8');
+	await mkdir(join(root, 'src/routes/todos'), { recursive: true });
+	await mkdir(join(root, 'src/routes/admin'), { recursive: true });
+	await writeFile(
+		join(root, 'src/routes/todos/+page.graphql'),
+		'query Todos @load { todos { id } }\n'
+	);
+	await writeFile(
+		join(root, 'src/routes/admin/+page.graphql'),
+		'query AdminTodos @load { todos { id } }\n'
+	);
+	const previousLog = process.env.DISTRIBUTED_FAKE_LOG;
+	const previousFailure = process.env.DISTRIBUTED_FAKE_FAIL_SURFACE;
+	const previousDelay = process.env.DISTRIBUTED_FAKE_DELAY_MS;
+	process.env.DISTRIBUTED_FAKE_LOG = log;
+	delete process.env.DISTRIBUTED_FAKE_FAIL_SURFACE;
+	delete process.env.DISTRIBUTED_FAKE_DELAY_MS;
+	t.after(async () => {
+		if (previousLog === undefined) delete process.env.DISTRIBUTED_FAKE_LOG;
+		else process.env.DISTRIBUTED_FAKE_LOG = previousLog;
+		if (previousFailure === undefined) {
+			delete process.env.DISTRIBUTED_FAKE_FAIL_SURFACE;
+		} else {
+			process.env.DISTRIBUTED_FAKE_FAIL_SURFACE = previousFailure;
+		}
+		if (previousDelay === undefined) {
+			delete process.env.DISTRIBUTED_FAKE_DELAY_MS;
+		} else {
+			process.env.DISTRIBUTED_FAKE_DELAY_MS = previousDelay;
+		}
+		await rm(root, { recursive: true, force: true });
+	});
+	return { root, script, log };
+}
+
+function clients() {
+	return [
+		{
+			module: '$distributed',
+			manifest: { args: ['client-manifest', '--entrypoint', 'user'] },
+			surface: 'e2e-ui',
+			documents: ['src/routes/todos/+page.graphql'],
+			out: 'src/generated/user'
+		},
+		{
+			module: '$distributed/admin',
+			manifest: { args: ['client-manifest', '--entrypoint', 'admin'] },
+			surface: 'e2e-ui-admin',
+			documents: ['src/routes/admin/+page.graphql'],
+			out: 'src/generated/admin'
+		}
+	];
+}
+
+function pluginOptions(root, script) {
+	return {
+		cwd: root,
+		command: process.execPath,
+		commandArgs: [script],
+		clients: clients()
+	};
+}
+
+async function commandLog(path) {
+	const source = await readFile(path, 'utf8');
+	return source
+		.trim()
+		.split('\n')
+		.filter(Boolean)
+		.map((line) => JSON.parse(line));
+}
+
+test('Vite compiles and resolves isolated user/admin physical entrypoints', async (t) => {
+	const { root, script, log } = await fixture(t);
+	const options = pluginOptions(root, script);
+	const plugin = distributedSvelteKit(options);
+	await plugin.configResolved({ root });
+
+	const aliases = distributedSvelteKitAliases({
+		cwd: root,
+		clients: options.clients
+	});
+	assert.deepEqual(aliases, {
+		'$distributed/admin': join(root, 'src/generated/admin/sveltekit.ts'),
+		$distributed: join(root, 'src/generated/user/sveltekit.ts')
+	});
+
+	const userId = plugin.resolveId('$distributed');
+	const adminId = plugin.resolveId('$distributed/admin');
+	assert.match(userId, /^\0@hops-ops\/distributed:sveltekit:/);
+	assert.match(adminId, /^\0@hops-ops\/distributed:sveltekit:/);
+	assert.match(
+		plugin.load(userId),
+		new RegExp(
+			JSON.stringify(join(root, 'src/generated/user/sveltekit.ts')).replace(
+				/[.*+?^${}()|[\]\\]/g,
+				'\\$&'
+			)
+		)
+	);
+	assert.match(
+		await readFile(join(root, 'src/generated/admin/sveltekit.ts'), 'utf8'),
+		/e2e-ui-admin/
+	);
+
+	const initial = await commandLog(log);
+	assert.deepEqual(
+		initial.map((args) => args[0]),
+		['client-manifest', 'client', 'client-manifest', 'client']
+	);
+	assert.deepEqual(
+		initial
+			.filter((args) => args[0] === 'client')
+			.map((args) => args[args.indexOf('--surface') + 1]),
+		['e2e-ui', 'e2e-ui-admin']
+	);
+
+	const added = [];
+	const messages = [];
+	const invalidated = [];
+	const modules = new Map([
+		[userId, { id: userId }],
+		[adminId, { id: adminId }]
+	]);
+	const server = {
+		watcher: { add: (paths) => added.push(paths) },
+		ws: { send: (message) => messages.push(message) },
+		moduleGraph: {
+			getModuleById: (id) => modules.get(id),
+			invalidateModule: (module) => invalidated.push(module.id)
+		}
+	};
+	plugin.configureServer(server);
+	assert.ok(added.flat().some((path) => path.includes('src/routes/')));
+
+	const change = {
+		file: join(root, 'src/routes/todos/+page.graphql'),
+		server
+	};
+	await Promise.all([
+		plugin.handleHotUpdate(change),
+		plugin.handleHotUpdate(change),
+		plugin.handleHotUpdate(change)
+	]);
+	const afterChanges = await commandLog(log);
+	assert.equal(
+		afterChanges.length,
+		12,
+		'three overlapping notifications coalesce into one active and one trailing transaction'
+	);
+	assert.deepEqual(invalidated, [userId, adminId]);
+	assert.equal(
+		messages.filter((message) => message.type === 'full-reload').length,
+		1,
+		'one successful coalesced generation issues one full reload'
+	);
+	assert.equal(
+		await plugin.handleHotUpdate({
+			file: join(root, 'src/generated/user/ignored.graphql'),
+			server
+		}),
+		undefined,
+		'generated output changes never trigger the compiler'
+	);
+	await plugin.closeBundle();
+
+	const beforeCheck = await readFile(
+		join(root, 'src/generated/user/sveltekit.ts'),
+		'utf8'
+	);
+	await checkDistributedSvelteKit(options);
+	assert.equal(
+		await readFile(join(root, 'src/generated/user/sveltekit.ts'), 'utf8'),
+		beforeCheck,
+		'the shared check runner never rewrites generated output'
+	);
+	await generateDistributedSvelteKit(options);
+	assert.match(
+		await readFile(join(root, 'src/generated/user/sveltekit.ts'), 'utf8'),
+		/todos/
+	);
+});
+
+test('same-process Vite instances coalesce one shared startup generation', async (t) => {
+	const { root, script, log } = await fixture(t);
+	process.env.DISTRIBUTED_FAKE_DELAY_MS = '75';
+	const options = pluginOptions(root, script);
+	const first = distributedSvelteKit(options);
+	const second = distributedSvelteKit(options);
+
+	await Promise.all([
+		first.configResolved({ root }),
+		second.configResolved({ root })
+	]);
+	assert.deepEqual(
+		(await commandLog(log)).map((args) => args[0]),
+		[
+			'client-manifest',
+			'client',
+			'client-manifest',
+			'client'
+		],
+		'identical plugin instances compile one startup generation'
+	);
+
+	await first.closeBundle();
+	await second.watchChange(join(root, 'src/routes/todos/+page.graphql'));
+	assert.equal(
+		(await commandLog(log)).length,
+		8,
+		'the remaining instance retains the shared project lock'
+	);
+	await second.closeBundle();
+	await checkDistributedSvelteKit(options);
+});
+
+test('SvelteKit config-probe workers never compile or contend for the project lock', async (t) => {
+	const { root, script, log } = await fixture(t);
+	const options = pluginOptions(root, script);
+	const moduleUrl = new URL('../dist/sveltekit/vite.js', import.meta.url).href;
+	const resolved = await new Promise((resolvePromise, rejectPromise) => {
+		const worker = new Worker(
+			String.raw`
+const { parentPort, workerData } = require('node:worker_threads');
+(async () => {
+  const { distributedSvelteKit } = await import(workerData.moduleUrl);
+  const plugin = distributedSvelteKit(workerData.options);
+  await plugin.configResolved({ root: workerData.options.cwd });
+  const resolved = plugin.resolveId('$distributed');
+  await plugin.closeBundle();
+  parentPort.postMessage({ resolved });
+})().catch((error) => {
+  parentPort.postMessage({ error: error?.stack ?? String(error) });
+});
+`,
+			{
+				eval: true,
+				env: { ...process.env, SVELTEKIT_FORK: 'true' },
+				workerData: { moduleUrl, options }
+			}
+		);
+		worker.once('message', (message) => {
+			if (message?.error !== undefined) {
+				rejectPromise(new Error(message.error));
+			} else {
+				resolvePromise(message.resolved);
+			}
+		});
+		worker.once('error', rejectPromise);
+	});
+
+	assert.match(resolved, /^\0@hops-ops\/distributed:sveltekit:/);
+	assert.deepEqual(await commandLog(log), []);
+});
+
+test('multi-surface failure leaves old outputs intact and redacts stdout', async (t) => {
+	const { root, script } = await fixture(t);
+	const userOut = join(root, 'src/generated/user');
+	const adminOut = join(root, 'src/generated/admin');
+	await mkdir(userOut, { recursive: true });
+	await mkdir(adminOut, { recursive: true });
+	await writeFile(join(userOut, 'sveltekit.ts'), 'old-user\n');
+	await writeFile(join(adminOut, 'sveltekit.ts'), 'old-admin\n');
+	process.env.DISTRIBUTED_FAKE_FAIL_SURFACE = 'e2e-ui-admin';
+
+	const plugin = distributedSvelteKit(pluginOptions(root, script));
+	await assert.rejects(
+		plugin.configResolved({ root }),
+		(error) => {
+			assert.match(error.message, /synthetic compiler failure/);
+			assert.match(error.message, /argv: \[/);
+			assert.match(error.message, new RegExp(`cwd: ${root}`));
+			assert.doesNotMatch(error.message, /sensitive schema and policy payload/);
+			return true;
+		}
+	);
+	assert.equal(await readFile(join(userOut, 'sveltekit.ts'), 'utf8'), 'old-user\n');
+	assert.equal(
+		await readFile(join(adminOut, 'sveltekit.ts'), 'utf8'),
+		'old-admin\n'
+	);
+	await plugin.closeBundle();
+});
+
+test('configuration rejects ambiguous surfaces, aliases, and output containment hazards', async (t) => {
+	const { root, script } = await fixture(t);
+	assert.throws(
+		() =>
+			distributedSvelteKitAliases({
+				cwd: root,
+				clients: [
+					...clients(),
+					{
+						...clients()[0],
+						module: '$distributed/nested',
+						out: 'src/generated/user/nested'
+					}
+				]
+			}),
+		/outputs must not overlap/
+	);
+	assert.throws(
+		() =>
+			distributedSvelteKitAliases({
+				cwd: root,
+				clients: [
+					{
+						...clients()[0],
+						surface: 'e2e-ui',
+						role: 'user'
+					}
+				]
+			}),
+		/exactly one of role or surface/
+	);
+	assert.throws(
+		() =>
+			distributedSvelteKitAliases({
+				cwd: root,
+				clients: [clients()[0], { ...clients()[1], module: '$distributed' }]
+			}),
+		/duplicate Distributed client module/
+	);
+
+	const outside = await mkdtemp(join(tmpdir(), 'distributed-vite-outside-'));
+	t.after(() => rm(outside, { recursive: true, force: true }));
+	await symlink(outside, join(root, 'linked-output'));
+	assert.throws(
+		() =>
+			distributedSvelteKitAliases({
+				cwd: root,
+				clients: [
+					{
+						...clients()[0],
+						out: 'linked-output/user'
+					}
+				]
+			}),
+		/contains symlink component|resolves outside project root/,
+		'language-tool aliases reject an escaping symlink before Vite starts'
+	);
+	const plugin = distributedSvelteKit({
+		...pluginOptions(root, script),
+		clients: [
+			{
+				...clients()[0],
+				out: 'linked-output/user'
+			}
+		]
+	});
+	await assert.rejects(
+		plugin.configResolved({ root }),
+		/contains symlink component|resolves outside project root/
+	);
+	await plugin.closeBundle();
+
+	await mkdir(join(root, 'src/generated/shared'), { recursive: true });
+	await symlink(
+		join(root, 'src/generated/shared'),
+		join(root, 'src/generated/shared-alias')
+	);
+	assert.throws(
+		() =>
+			distributedSvelteKitAliases({
+				cwd: root,
+				clients: [
+					{ ...clients()[0], out: 'src/generated/shared/user' },
+					{
+						...clients()[1],
+						out: 'src/generated/shared-alias/user'
+					}
+				]
+			}),
+		/contains symlink component|physically overlap/,
+		'two lexical outputs cannot alias one physical authorization surface'
+	);
+});
+
+test('gql changes regenerate and cancellation before commit preserves old outputs', async (t) => {
+	const { root, script, log } = await fixture(t);
+	const options = pluginOptions(root, script);
+	const plugin = distributedSvelteKit(options);
+	await plugin.configResolved({ root });
+	const server = {
+		watcher: { add() {} },
+		ws: { send() {} },
+		moduleGraph: {
+			getModuleById: () => undefined,
+			invalidateModule() {}
+		}
+	};
+	const gql = join(root, 'src/routes/todos/extra.gql');
+	await writeFile(gql, 'query Extra { todos { id } }\n');
+	const beforeGql = (await commandLog(log)).length;
+	await plugin.handleHotUpdate({ file: gql, server });
+	assert.equal(
+		(await commandLog(log)).length,
+		beforeGql + 4,
+		'legacy .gql inputs receive the same compiler watch lifecycle'
+	);
+	await plugin.closeBundle();
+
+	const userOut = join(root, 'src/generated/user');
+	const adminOut = join(root, 'src/generated/admin');
+	await writeFile(join(userOut, 'sveltekit.ts'), 'stable-user\n');
+	await writeFile(join(adminOut, 'sveltekit.ts'), 'stable-admin\n');
+	process.env.DISTRIBUTED_FAKE_DELAY_MS = '5000';
+	const cancelling = distributedSvelteKit(options);
+	const startup = cancelling.configResolved({ root });
+	await waitFor(async () => (await commandLog(log)).at(-1)?.[0] === 'client');
+	await cancelling.closeBundle();
+	await assert.rejects(startup);
+	assert.equal(
+		await readFile(join(userOut, 'sveltekit.ts'), 'utf8'),
+		'stable-user\n'
+	);
+	assert.equal(
+		await readFile(join(adminOut, 'sveltekit.ts'), 'utf8'),
+		'stable-admin\n'
+	);
+});
+
+test('overflowing compiler output is bounded and force-killed', async (t) => {
+	const { root, log } = await fixture(t);
+	const script = join(root, 'overflow.mjs');
+	await writeFile(
+		script,
+		`process.on('SIGTERM', () => {});\n` +
+			`const chunk = 'x'.repeat(1024 * 1024);\n` +
+			`for (let i = 0; i < 20; i += 1) process.stdout.write(chunk);\n` +
+			`setInterval(() => {}, 1000);\n`,
+		'utf8'
+	);
+	process.env.DISTRIBUTED_FAKE_LOG = log;
+	const plugin = distributedSvelteKit({
+		...pluginOptions(root, script),
+		clients: [clients()[0]]
+	});
+	const started = Date.now();
+	await assert.rejects(
+		plugin.configResolved({ root }),
+		/output exceeded 16777216 bytes/
+	);
+	assert.ok(Date.now() - started < 5_000, 'overflow kill is bounded');
+	await plugin.closeBundle();
+});
+
+async function waitFor(predicate) {
+	const deadline = Date.now() + 3_000;
+	while (Date.now() < deadline) {
+		if (await predicate()) return;
+		await new Promise((resolve) => setTimeout(resolve, 10));
+	}
+	throw new Error('timed out waiting for fake compiler state');
+}
diff --git a/js/tsconfig.generated-tests.json b/js/tsconfig.generated-tests.json
new file mode 100644
index 00000000..ed51963c
--- /dev/null
+++ b/js/tsconfig.generated-tests.json
@@ -0,0 +1,24 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "declaration": false,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noEmit": true,
+    "outDir": "./dist-type-tests",
+    "paths": {
+      "@hops-ops/distributed/replica": ["./src/replica/index.ts"],
+      "@hops-ops/distributed/react": ["./src/react/index.ts"],
+      "@hops-ops/distributed/sveltekit": ["./src/sveltekit/index.ts"],
+      "@hops-ops/distributed/sveltekit/vite": ["./src/sveltekit/vite.ts"]
+    },
+    "rootDir": ".."
+  },
+  "include": [
+    "../distributed_cli/tests/fixtures/generated-*.ts",
+    "type-tests/**/*.ts"
+  ]
+}
diff --git a/js/tsconfig.json b/js/tsconfig.json
new file mode 100644
index 00000000..e432157d
--- /dev/null
+++ b/js/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM"],
+    "types": ["node"],
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules"]
+}
diff --git a/js/type-tests/generated-order-input.ts b/js/type-tests/generated-order-input.ts
new file mode 100644
index 00000000..0cd977a7
--- /dev/null
+++ b/js/type-tests/generated-order-input.ts
@@ -0,0 +1,29 @@
+import type { Operation_ScalarInputs_Variables } from '../../distributed_cli/tests/fixtures/generated-operation';
+
+type OrderValue = NonNullable<Operation_ScalarInputs_Variables['order']>;
+type OrderEntry = Exclude<OrderValue, readonly unknown[]>;
+
+export const orderByPriority: OrderEntry = {
+	priority: 'asc'
+};
+
+export const orderByIdThenPriority: readonly OrderEntry[] = [
+	{ id: 'asc' },
+	{ priority: 'desc_nulls_last' }
+];
+
+const multipleFieldsInOneOrderEntry = {
+	id: 'asc',
+	priority: 'desc'
+} as const;
+
+// @ts-expect-error Structural values with multiple known fields are ambiguous.
+export const rejectedMultipleFields: OrderEntry = multipleFieldsInOneOrderEntry;
+
+// @ts-expect-error An order entry cannot be empty.
+export const emptyOrderEntry: OrderEntry = {};
+
+export const unknownOrderField: OrderEntry = {
+	// @ts-expect-error Only compiler-authorized model fields may be ordered.
+	missing: 'asc'
+};
diff --git a/js/type-tests/react-adapter.ts b/js/type-tests/react-adapter.ts
new file mode 100644
index 00000000..845855da
--- /dev/null
+++ b/js/type-tests/react-adapter.ts
@@ -0,0 +1,67 @@
+import { createElement } from 'react';
+
+import {
+	DistributedProvider,
+	useDistributedQuery
+} from '@hops-ops/distributed/react';
+import type {
+	DistributedReplica,
+	ReplicaCommandArtifact,
+	ReplicaCommandRuntime,
+	ReplicaOperationArtifact
+} from '@hops-ops/distributed/replica';
+
+type Todo = {
+	id: string;
+	title: string;
+	status: 'open' | 'done';
+};
+type TodosResult = { todos: readonly Todo[] };
+type TodoResult = { todo: Todo | null };
+
+declare const replica: DistributedReplica;
+declare const Todos: ReplicaOperationArtifact<
+	TodosResult,
+	Readonly<Record<never, never>>
+>;
+declare const TodoById: ReplicaOperationArtifact<
+	TodoResult,
+	Readonly<{ id: string }>
+>;
+declare const generatedRuntime: ReplicaCommandRuntime<{
+	'todo.complete': ReplicaCommandArtifact<
+		Readonly<{ todoId: string }>,
+		Readonly<{ accepted: boolean }>
+	>;
+}>;
+
+function TodosView() {
+	const todos = useDistributedQuery(Todos);
+	const selected = useDistributedQuery(TodoById, { id: 'todo-1' }, { live: true });
+	void todos.refresh();
+
+	if (todos.complete) {
+		todos.data.todos.map((todo) => todo.title);
+	} else {
+		todos.data.todos?.map((todo) => todo?.title);
+	}
+	if (selected.complete) {
+		selected.data.todo?.status;
+	}
+
+	void generatedRuntime.commands.todo.complete({ todoId: 'todo-1' });
+	// @ts-expect-error Generated command input remains exact through React usage.
+	void generatedRuntime.commands.todo.complete({ id: 'todo-1' });
+	return null;
+}
+
+createElement(
+	DistributedProvider,
+	{ replica },
+	createElement(TodosView)
+);
+
+// @ts-expect-error Required generated operation variables cannot be omitted.
+useDistributedQuery(TodoById);
+// @ts-expect-error Unknown generated operation variables fail at compile time.
+useDistributedQuery(TodoById, { id: 'todo-1', forged: true });
diff --git a/js/type-tests/replica-command-runtime.ts b/js/type-tests/replica-command-runtime.ts
new file mode 100644
index 00000000..ee8069ac
--- /dev/null
+++ b/js/type-tests/replica-command-runtime.ts
@@ -0,0 +1,56 @@
+import {
+	createReplicaCommandRuntime,
+	type DistributedReplica,
+	type ReplicaCommandArtifact,
+	type ReplicaCommandTransport
+} from '@hops-ops/distributed/replica';
+
+type CreateInput = {
+	readonly id: string;
+};
+
+type CreateOutput = {
+	readonly ok: boolean;
+};
+
+declare const replica: DistributedReplica;
+declare const transport: ReplicaCommandTransport;
+declare const createArtifact: ReplicaCommandArtifact<CreateInput, CreateOutput>;
+declare const pingArtifact: ReplicaCommandArtifact<void, { readonly pong: true }>;
+
+const runtime = createReplicaCommandRuntime(replica, transport, {
+	create: createArtifact,
+	ping: { artifact: pingArtifact }
+});
+
+runtime.commands.create({ id: 'todo-1' }).then((receipt) => {
+	const ok: boolean = receipt.result.ok;
+	return ok;
+});
+runtime.commands.ping().then((receipt) => {
+	const pong: true = receipt.result.pong;
+	return pong;
+});
+runtime.commands.create({ id: 'todo-1' }).then((receipt) =>
+	receipt.status().then((status) => {
+		const state: string = status.state;
+		const metadata = status.metadata;
+		return { state, metadata };
+	})
+);
+
+const nestedRuntime = createReplicaCommandRuntime(replica, transport, {
+	'todo.create': createArtifact,
+	'todo.ping': { artifact: pingArtifact }
+});
+nestedRuntime.commands.todo.create({ id: 'todo-1' });
+nestedRuntime.commands.todo.ping();
+// @ts-expect-error Dotted inventory keys are nested callable namespaces.
+nestedRuntime.commands['todo.create'];
+
+// @ts-expect-error Generated input remains required.
+runtime.commands.create();
+// @ts-expect-error A void-input command accepts options, not domain input.
+runtime.commands.ping({ id: 'todo-1' });
+// @ts-expect-error Result types cannot bleed between generated commands.
+runtime.commands.create({ id: 'todo-1' }).then((receipt) => receipt.result.pong);
diff --git a/js/type-tests/replica-operation-artifact.ts b/js/type-tests/replica-operation-artifact.ts
new file mode 100644
index 00000000..52476370
--- /dev/null
+++ b/js/type-tests/replica-operation-artifact.ts
@@ -0,0 +1,136 @@
+import type {
+	ReplicaOperationArtifact,
+	ReplicaObjectMember,
+	ReplicaObjectSelection,
+	ReplicaOperationProtocol,
+	ReplicaPaginationArtifact,
+	ReplicaProtocolOperationArtifact,
+	ReplicaVariableCodecArtifact
+} from '@hops-ops/distributed/replica';
+
+type Data = {
+	readonly items: readonly { readonly id: string }[];
+};
+
+type Variables = {
+	readonly id: string;
+};
+
+const protocol = {
+	version: 1,
+	schemaHash: 'schema:type-test',
+	surface: {
+		kind: 'role',
+		name: 'user'
+	},
+	operation: 'query:type-test',
+	trustedPresets: []
+} as const satisfies ReplicaOperationProtocol;
+
+// @ts-expect-error Generated protocol artifacts always name their client surface.
+export const protocolWithoutSurface: ReplicaOperationProtocol = {
+	version: 1,
+	schemaHash: 'schema:type-test',
+	operation: 'query:type-test',
+	trustedPresets: []
+};
+
+// @ts-expect-error Generated protocol artifacts always carry the exact preset union.
+export const protocolWithoutTrustedPresets: ReplicaOperationProtocol = {
+	version: 1,
+	schemaHash: 'schema:type-test',
+	surface: { kind: 'role', name: 'user' },
+	operation: 'query:type-test'
+};
+
+const variableCodec = {
+	version: 1,
+	limits: {
+		maxDepth: 16,
+		maxBoolWidth: 32,
+		maxInList: 128
+	},
+	variables: {
+		id: {
+			kind: 'scalar',
+			scalar: 'ID',
+			codec: 'string',
+			nullable: false
+		}
+	},
+	inputs: {}
+} as const satisfies ReplicaVariableCodecArtifact;
+
+export const protocolArtifact: ReplicaProtocolOperationArtifact<Data, Variables> = {
+	id: protocol.operation,
+	document: 'query TypeTest($id: ID!) { items(id: $id) { id } }',
+	roots: [],
+	protocol,
+	variableCodec
+};
+
+export const protocolArtifactViaUnion: ReplicaOperationArtifact<Data, Variables> =
+	protocolArtifact;
+
+// @ts-expect-error Artifacts without protocol-v1 binding are unsupported.
+export const unboundArtifact: ReplicaOperationArtifact<Data, Variables> = {
+	id: 'unbound:type-test',
+	document: 'query TypeTest { items { id } }',
+	roots: []
+};
+
+// @ts-expect-error Protocol-v1 artifacts must include their variable codec.
+export const protocolWithoutCodec: ReplicaOperationArtifact<Data, Variables> = {
+	id: protocol.operation,
+	document: 'query TypeTest($id: ID!) { items(id: $id) { id } }',
+	roots: [],
+	protocol
+};
+
+type IndependentlyOptionalArtifact = Omit<
+	ReplicaProtocolOperationArtifact<Data, Variables>,
+	'protocol' | 'variableCodec'
+> & {
+	readonly protocol?: ReplicaOperationProtocol;
+	readonly variableCodec?: ReplicaVariableCodecArtifact;
+};
+
+declare const independentlyOptionalArtifact: IndependentlyOptionalArtifact;
+
+// @ts-expect-error Protocol and codec cannot be modeled as independent options.
+export const rejectedIndependentOptions: ReplicaOperationArtifact<Data, Variables> =
+	independentlyOptionalArtifact;
+
+const handwrittenEntitySelection = {
+	model: { id: 'Item', identityFields: ['id'] },
+	fields: []
+} as const;
+
+// @ts-expect-error The generated recursive object IR is the only selection shape.
+export const rejectedHandwrittenSelection: ReplicaObjectSelection =
+	handwrittenEntitySelection;
+
+// @ts-expect-error Generated scalars must bind an exact codec and nullability.
+export const rejectedUnboundScalar: ReplicaObjectMember = {
+	kind: 'scalar',
+	responseKey: 'id',
+	field: 'id'
+};
+
+export const unprovenCursorPagination: ReplicaPaginationArtifact = {
+	kind: 'cursor',
+	insert: 'revalidate',
+	delete: 'revalidate',
+	reorder: 'revalidate',
+	stableUpdate: 'revalidate'
+};
+
+export const forgedCertifiedCursor: ReplicaPaginationArtifact = {
+	kind: 'cursor',
+	// @ts-expect-error A boolean is not a versioned compiler cursor-proof IR.
+	certified: true,
+	insert: 'local',
+	delete: 'local',
+	reorder: 'local',
+	stableUpdate: 'local'
+};
diff --git a/js/type-tests/sveltekit-adapter.ts b/js/type-tests/sveltekit-adapter.ts
new file mode 100644
index 00000000..8ce17fbc
--- /dev/null
+++ b/js/type-tests/sveltekit-adapter.ts
@@ -0,0 +1,102 @@
+import {
+	bindSveltekitOperation,
+	createDistributedSvelteKit,
+	createDistributedSvelteKitServer
+} from '@hops-ops/distributed/sveltekit';
+import { distributedSvelteKit } from '@hops-ops/distributed/sveltekit/vite';
+import type {
+	DistributedReplica,
+	ReplicaCommandArtifact,
+	ReplicaCommandRuntime,
+	ReplicaOperationArtifact
+} from '@hops-ops/distributed/replica';
+
+type Todo = {
+	id: string;
+	title: string;
+	status: 'open' | 'done';
+};
+type TodosResult = { todos: readonly Todo[] };
+type TodoResult = { todo: Todo | null };
+
+declare const replica: DistributedReplica;
+declare const Todos: ReplicaOperationArtifact<
+	TodosResult,
+	Readonly<Record<never, never>>
+>;
+declare const TodoById: ReplicaOperationArtifact<
+	TodoResult,
+	Readonly<{ id: string }>
+>;
+declare const generatedRuntime: ReplicaCommandRuntime<{
+	'todo.complete': ReplicaCommandArtifact<
+		Readonly<{ todoId: string }>,
+		Readonly<{ accepted: boolean }>
+	>;
+}>;
+
+const standaloneTodos = bindSveltekitOperation(replica, Todos).use();
+standaloneTodos.subscribe((snapshot) => {
+	if (snapshot.complete) {
+		snapshot.data.todos.map((todo) => todo.title);
+	} else {
+		snapshot.data.todos?.map((todo) => todo?.title);
+	}
+});
+void standaloneTodos.refetch();
+
+const client = createDistributedSvelteKit({
+	session: {
+		getAuth: () => ({ accessToken: 'token' })
+	},
+	createCommands: () => generatedRuntime
+});
+const todos = client.operation(Todos).use({}, { live: true });
+const selected = client.operation(TodoById).use({ id: 'todo-1' });
+selected.data.todo?.status;
+todos.pending.map((receipt) => receipt.status());
+
+void client.commands.todo.complete({ todoId: 'todo-1' });
+// @ts-expect-error Generated command input remains exact through Svelte usage.
+void client.commands.todo.complete({ id: 'todo-1' });
+
+// @ts-expect-error Required generated operation variables cannot be omitted.
+client.operation(TodoById).use();
+// @ts-expect-error Unknown generated operation variables fail at compile time.
+client.operation(TodoById).use({ id: 'todo-1', forged: true });
+
+createDistributedSvelteKitServer({
+	routes: [
+		{
+			plan: {
+				operation: 'Todos',
+				route: '/todos',
+				discovery: 'convention'
+			},
+			artifact: Todos
+		}
+	] as const,
+	getSession: async () => null,
+	getRole: () => 'user'
+});
+
+const vitePlugin = distributedSvelteKit({
+	clients: [
+		{
+			module: '$distributed',
+			manifest: 'target/distributed-client.json',
+			role: 'user',
+			documents: ['src/**/*.graphql'],
+			out: 'src/lib/generated/distributed'
+		}
+	]
+});
+vitePlugin.configureServer({
+	watcher: { add: () => undefined },
+	ws: { send: () => undefined },
+	moduleGraph: {
+		getModuleById: () => undefined,
+		invalidateModule: () => undefined
+	},
+	httpServer: null
+});
diff --git a/migrations/postgres/0002_command_ledger.sql b/migrations/postgres/0002_command_ledger.sql
new file mode 100644
index 00000000..03bd717b
--- /dev/null
+++ b/migrations/postgres/0002_command_ledger.sql
@@ -0,0 +1,80 @@
+-- Durable idempotency ledger for typed commands. Retention compaction turns a
+-- row into a small permanent `expired` tombstone; command identities are never
+-- deleted or reusable.
+CREATE TABLE IF NOT EXISTS command_ledger (
+  service_id text NOT NULL,
+  principal_partition text NOT NULL,
+  command_id text NOT NULL,
+  command_name text NOT NULL,
+  command_contract_hash bytea NOT NULL,
+  input_hash bytea NOT NULL,
+  state text NOT NULL,
+  causation_id text NOT NULL,
+  attempt_token text,
+  attempt_number bigint NOT NULL,
+  lease_expires_at timestamptz,
+  outcome jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  completed_at timestamptz,
+  retention_expires_at timestamptz NOT NULL,
+  compacted_at timestamptz,
+  PRIMARY KEY (service_id, principal_partition, command_id),
+  UNIQUE (service_id, causation_id),
+  CHECK (service_id <> ''),
+  CHECK (principal_partition <> ''),
+  CHECK (command_id <> ''),
+  CHECK (command_name <> ''),
+  CHECK (octet_length(command_contract_hash) = 32),
+  CHECK (octet_length(input_hash) = 32),
+  CHECK (causation_id <> ''),
+  CHECK (attempt_number > 0),
+  CHECK (state IN (
+    'in_progress',
+    'retryable_unknown',
+    'accepted',
+    'accepted_pending_projection',
+    'projected',
+    'rejected',
+    'projection_failed',
+    'expired'
+  )),
+  CHECK (
+    (state = 'in_progress'
+      AND attempt_token IS NOT NULL
+      AND lease_expires_at IS NOT NULL
+      AND outcome IS NULL
+      AND completed_at IS NULL
+      AND compacted_at IS NULL)
+    OR
+    (state = 'retryable_unknown'
+      AND attempt_token IS NULL
+      AND lease_expires_at IS NULL
+      AND outcome IS NULL
+      AND completed_at IS NULL
+      AND compacted_at IS NULL)
+    OR
+    (state IN (
+        'accepted',
+        'accepted_pending_projection',
+        'projected',
+        'rejected',
+        'projection_failed'
+      )
+      AND attempt_token IS NULL
+      AND lease_expires_at IS NULL
+      AND outcome IS NOT NULL
+      AND completed_at IS NOT NULL
+      AND compacted_at IS NULL)
+    OR
+    (state = 'expired'
+      AND attempt_token IS NULL
+      AND lease_expires_at IS NULL
+      AND outcome IS NULL
+      AND compacted_at IS NOT NULL)
+  )
+);
+
+CREATE INDEX IF NOT EXISTS command_ledger_retention_idx
+  ON command_ledger (retention_expires_at)
+  WHERE state <> 'expired';
diff --git a/migrations/postgres/0003_projection_protocol.sql b/migrations/postgres/0003_projection_protocol.sql
new file mode 100644
index 00000000..761ed908
--- /dev/null
+++ b/migrations/postgres/0003_projection_protocol.sql
@@ -0,0 +1,691 @@
+-- Framework-owned causal projection protocol metadata.
+--
+-- This additive pre-release migration deliberately performs no backfill:
+-- existing read-model rows have no inferred causation, revision, checkpoint,
+-- observation, or ownership evidence. Adoption requires a rebuild into a new
+-- projection epoch or a separately verified importer.
+
+CREATE TABLE IF NOT EXISTS projection_partitions (
+  topology_bytes bytea NOT NULL,
+  topology_hash bytea NOT NULL,
+  partition_bytes bytea NOT NULL,
+  partition_hash bytea NOT NULL,
+  active_generation bigint NOT NULL DEFAULT 1,
+  change_epoch text NOT NULL,
+  change_head bigint NOT NULL DEFAULT 0,
+  compacted_through bigint NOT NULL DEFAULT 0,
+  pending_retry_failure_id text,
+  stopped_failure_id text,
+  stopped_source_bytes bytea,
+  stopped_source_hash bytea,
+  stopped_source_partition_bytes bytea,
+  stopped_source_partition_hash bytea,
+  stopped_source_epoch text,
+  stopped_source_position bigint,
+  stopped_generation bigint,
+  stopped_input_hash bytea,
+  stopped_message_id text,
+  stopped_causation_id text,
+  stopped_gap_free bigint,
+  PRIMARY KEY (topology_hash, partition_hash),
+  CHECK (octet_length(topology_bytes) BETWEEN 1 AND 4096),
+  CHECK (octet_length(topology_hash) = 32),
+  CHECK (octet_length(partition_bytes) BETWEEN 1 AND 4096),
+  CHECK (octet_length(partition_hash) = 32),
+  CHECK (active_generation > 0),
+  CHECK (char_length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_head >= 0),
+  CHECK (compacted_through >= 0 AND compacted_through <= change_head),
+  CHECK (pending_retry_failure_id IS NULL
+    OR char_length(pending_retry_failure_id) BETWEEN 1 AND 255),
+  CHECK (pending_retry_failure_id IS NULL OR stopped_failure_id IS NULL),
+  CHECK (
+    (stopped_failure_id IS NULL
+      AND stopped_source_bytes IS NULL
+      AND stopped_source_hash IS NULL
+      AND stopped_source_partition_bytes IS NULL
+      AND stopped_source_partition_hash IS NULL
+      AND stopped_source_epoch IS NULL
+      AND stopped_source_position IS NULL
+      AND stopped_generation IS NULL
+      AND stopped_input_hash IS NULL
+      AND stopped_message_id IS NULL
+      AND stopped_causation_id IS NULL
+      AND stopped_gap_free IS NULL)
+    OR
+    (stopped_failure_id IS NOT NULL
+      AND char_length(stopped_failure_id) BETWEEN 1 AND 255
+      AND stopped_source_bytes IS NOT NULL
+      AND octet_length(stopped_source_bytes) BETWEEN 1 AND 1024
+      AND stopped_source_hash IS NOT NULL
+      AND octet_length(stopped_source_hash) = 32
+      AND stopped_source_partition_bytes IS NOT NULL
+      AND octet_length(stopped_source_partition_bytes) BETWEEN 1 AND 4096
+      AND stopped_source_partition_hash IS NOT NULL
+      AND octet_length(stopped_source_partition_hash) = 32
+      AND stopped_source_epoch IS NOT NULL
+      AND char_length(stopped_source_epoch) BETWEEN 1 AND 128
+      AND stopped_source_position IS NOT NULL
+      AND stopped_source_position >= 0
+      AND stopped_generation IS NOT NULL
+      AND stopped_generation > 0
+      AND stopped_input_hash IS NOT NULL
+      AND octet_length(stopped_input_hash) = 32
+      AND stopped_message_id IS NOT NULL
+      AND char_length(stopped_message_id) BETWEEN 1 AND 255
+      AND stopped_causation_id IS NOT NULL
+      AND char_length(stopped_causation_id) BETWEEN 1 AND 128
+      AND stopped_gap_free IS NOT NULL
+      AND stopped_gap_free IN (0, 1))
+  )
+);
+
+-- Repair generations are partition-wide durable facts. Generation one is the
+-- original run; every later generation is linked to exactly one prior
+-- generation and immutable terminal failure. The retry failure link is checked
+-- by the repair transaction because a declarative foreign key would be
+-- circular with projection_failures -> projection_generations.
+CREATE TABLE IF NOT EXISTS projection_generations (
+  topology_hash bytea NOT NULL,
+  partition_hash bytea NOT NULL,
+  generation bigint NOT NULL,
+  retry_of_generation bigint,
+  retry_of_failure_id text,
+  PRIMARY KEY (topology_hash, partition_hash, generation),
+  UNIQUE (topology_hash, partition_hash, retry_of_failure_id),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  CHECK (octet_length(topology_hash) = 32),
+  CHECK (octet_length(partition_hash) = 32),
+  CHECK (generation > 0),
+  CHECK (
+    (generation = 1
+      AND retry_of_generation IS NULL
+      AND retry_of_failure_id IS NULL)
+    OR
+    (generation > 1
+      AND retry_of_generation IS NOT NULL
+      AND retry_of_generation > 0
+      AND retry_of_generation < generation
+      AND retry_of_failure_id IS NOT NULL
+      AND char_length(retry_of_failure_id) BETWEEN 1 AND 255)
+  )
+);
+
+-- Durable ordering capability for one exact source scope. It is independent of
+-- source epoch and repair generation, so a source cannot change between
+-- gap-tolerant and gap-free ordering after either advancement or first failure.
+CREATE TABLE IF NOT EXISTS projection_source_capabilities (
+  topology_hash bytea NOT NULL,
+  partition_hash bytea NOT NULL,
+  source_bytes bytea NOT NULL,
+  source_hash bytea NOT NULL,
+  source_partition_bytes bytea NOT NULL,
+  source_partition_hash bytea NOT NULL,
+  gap_free bigint NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    source_hash,
+    source_partition_hash
+  ),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  CHECK (octet_length(topology_hash) = 32),
+  CHECK (octet_length(partition_hash) = 32),
+  CHECK (octet_length(source_bytes) BETWEEN 1 AND 1024),
+  CHECK (octet_length(source_hash) = 32),
+  CHECK (octet_length(source_partition_bytes) BETWEEN 1 AND 4096),
+  CHECK (octet_length(source_partition_hash) = 32),
+  CHECK (gap_free IN (0, 1))
+);
+
+-- Generation-independent authenticated input identity. Repair generations
+-- scope outcomes/re-execution, not the identity of a source cursor or message.
+-- These rows survive repair and change-log compaction.
+CREATE TABLE IF NOT EXISTS projection_input_identities (
+  topology_hash bytea NOT NULL,
+  partition_hash bytea NOT NULL,
+  source_bytes bytea NOT NULL,
+  source_hash bytea NOT NULL,
+  source_partition_bytes bytea NOT NULL,
+  source_partition_hash bytea NOT NULL,
+  source_epoch text NOT NULL,
+  source_position bigint NOT NULL,
+  input_hash bytea NOT NULL,
+  message_id text NOT NULL,
+  causation_id text NOT NULL,
+  gap_free bigint NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    source_hash,
+    source_partition_hash,
+    source_epoch,
+    source_position
+  ),
+  UNIQUE (topology_hash, message_id),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  CHECK (octet_length(topology_hash) = 32),
+  CHECK (octet_length(partition_hash) = 32),
+  CHECK (octet_length(source_bytes) BETWEEN 1 AND 1024),
+  CHECK (octet_length(source_hash) = 32),
+  CHECK (octet_length(source_partition_bytes) BETWEEN 1 AND 4096),
+  CHECK (octet_length(source_partition_hash) = 32),
+  CHECK (char_length(source_epoch) BETWEEN 1 AND 128),
+  CHECK (source_position >= 0),
+  CHECK (octet_length(input_hash) = 32),
+  CHECK (char_length(message_id) BETWEEN 1 AND 255),
+  CHECK (char_length(causation_id) BETWEEN 1 AND 128),
+  CHECK (gap_free IN (0, 1))
+);
+
+-- One durable last-good checkpoint per exact ordered source scope and repair
+-- generation, including the change cursor allocated by its commit. Source
+-- epoch is fenced row data: an epoch mismatch is incomparable and requires a
+-- new projector topology plus read-model rebuild. Repair is failure-only and
+-- cannot bridge source epochs.
+CREATE TABLE IF NOT EXISTS projection_input_cursors (
+  topology_hash bytea NOT NULL,
+  partition_hash bytea NOT NULL,
+  source_bytes bytea NOT NULL,
+  source_hash bytea NOT NULL,
+  source_partition_bytes bytea NOT NULL,
+  source_partition_hash bytea NOT NULL,
+  source_epoch text NOT NULL,
+  source_position bigint NOT NULL,
+  input_hash bytea NOT NULL,
+  message_id text NOT NULL,
+  causation_id text NOT NULL,
+  gap_free bigint NOT NULL,
+  generation bigint NOT NULL,
+  change_epoch text NOT NULL,
+  change_position bigint NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    source_hash,
+    source_partition_hash,
+    generation
+  ),
+  UNIQUE (
+    topology_hash,
+    partition_hash,
+    source_hash,
+    source_partition_hash,
+    message_id,
+    generation
+  ),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  FOREIGN KEY (topology_hash, partition_hash, generation)
+    REFERENCES projection_generations (
+      topology_hash,
+      partition_hash,
+      generation
+    ),
+  CHECK (octet_length(topology_hash) = 32),
+  CHECK (octet_length(partition_hash) = 32),
+  CHECK (octet_length(source_bytes) BETWEEN 1 AND 1024),
+  CHECK (octet_length(source_hash) = 32),
+  CHECK (octet_length(source_partition_bytes) BETWEEN 1 AND 4096),
+  CHECK (octet_length(source_partition_hash) = 32),
+  CHECK (char_length(source_epoch) BETWEEN 1 AND 128),
+  CHECK (source_position >= 0),
+  CHECK (octet_length(input_hash) = 32),
+  CHECK (char_length(message_id) BETWEEN 1 AND 255),
+  CHECK (char_length(causation_id) BETWEEN 1 AND 128),
+  CHECK (gap_free IN (0, 1)),
+  CHECK (generation > 0),
+  CHECK (char_length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_position > 0)
+);
+
+-- Append-only identity evidence for every terminal input outcome. Unlike the
+-- mutable last-good cursor above, a receipt remains able to distinguish an exact
+-- duplicate from message-ID or source-cursor reuse after later checkpoints
+-- advance. Source scope is deliberately not part of the primary key so lookup
+-- by partition generation and message ID also detects cross-source reuse.
+-- The accepted change cursor remains durable after change-log compaction, so
+-- it intentionally has no foreign key to projection_changes.
+CREATE TABLE IF NOT EXISTS projection_input_receipts (
+  topology_hash bytea NOT NULL,
+  partition_hash bytea NOT NULL,
+  generation bigint NOT NULL,
+  message_id text NOT NULL,
+  source_bytes bytea NOT NULL,
+  source_hash bytea NOT NULL,
+  source_partition_bytes bytea NOT NULL,
+  source_partition_hash bytea NOT NULL,
+  source_epoch text NOT NULL,
+  source_position bigint NOT NULL,
+  input_hash bytea NOT NULL,
+  causation_id text NOT NULL,
+  gap_free bigint NOT NULL,
+  outcome_kind text NOT NULL,
+  failure_id text,
+  change_epoch text NOT NULL,
+  change_position bigint NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    generation,
+    message_id
+  ),
+  UNIQUE (
+    topology_hash,
+    partition_hash,
+    generation,
+    source_hash,
+    source_partition_hash,
+    source_epoch,
+    source_position
+  ),
+  UNIQUE (
+    topology_hash,
+    partition_hash,
+    change_epoch,
+    change_position
+  ),
+  FOREIGN KEY (topology_hash, partition_hash, generation)
+    REFERENCES projection_generations (
+      topology_hash,
+      partition_hash,
+      generation
+    ),
+  CHECK (octet_length(topology_hash) = 32),
+  CHECK (octet_length(partition_hash) = 32),
+  CHECK (generation > 0),
+  CHECK (char_length(message_id) BETWEEN 1 AND 255),
+  CHECK (octet_length(source_bytes) BETWEEN 1 AND 1024),
+  CHECK (octet_length(source_hash) = 32),
+  CHECK (octet_length(source_partition_bytes) BETWEEN 1 AND 4096),
+  CHECK (octet_length(source_partition_hash) = 32),
+  CHECK (char_length(source_epoch) BETWEEN 1 AND 128),
+  CHECK (source_position >= 0),
+  CHECK (octet_length(input_hash) = 32),
+  CHECK (char_length(causation_id) BETWEEN 1 AND 128),
+  CHECK (gap_free IN (0, 1)),
+  CHECK (outcome_kind IN ('applied', 'failed')),
+  CHECK (
+    (outcome_kind = 'applied' AND failure_id IS NULL)
+    OR
+    (outcome_kind = 'failed'
+      AND failure_id IS NOT NULL
+      AND char_length(failure_id) BETWEEN 1 AND 255)
+  ),
+  CHECK (char_length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_position > 0)
+);
+
+-- Per-table serialization point shared by raw writers and causal bootstrap.
+-- An insert-on-conflict followed by SELECT FOR UPDATE closes the absent-marker
+-- race: whichever transaction owns this row decides whether legacy data or a
+-- causal marker may be committed.
+CREATE TABLE IF NOT EXISTS projection_table_ownership_fences (
+  table_name text PRIMARY KEY,
+  CHECK (char_length(table_name) BETWEEN 1 AND 255)
+);
+
+-- Model-wide bootstrap marker used by raw write paths, which do not carry a
+-- typed projection partition. Presence makes the table exclusively causal;
+-- partition-specific ownership below must reference this exact table/model
+-- registration.
+CREATE TABLE IF NOT EXISTS projection_causal_tables (
+  table_name text NOT NULL,
+  model_name text NOT NULL,
+  ownership text NOT NULL DEFAULT 'causal',
+  PRIMARY KEY (table_name, model_name),
+  UNIQUE (table_name),
+  FOREIGN KEY (table_name)
+    REFERENCES projection_table_ownership_fences (table_name),
+  CHECK (char_length(table_name) BETWEEN 1 AND 255),
+  CHECK (char_length(model_name) BETWEEN 1 AND 255),
+  CHECK (ownership = 'causal')
+);
+
+-- Authoritative physical-table bootstrap declaration. Canonical topology bytes
+-- make digest collisions detectable; global table uniqueness deliberately
+-- forbids independent projector topologies from owning the same physical rows.
+CREATE TABLE IF NOT EXISTS projection_registered_models (
+  topology_bytes bytea NOT NULL,
+  topology_hash bytea NOT NULL,
+  model_name text NOT NULL,
+  table_name text NOT NULL,
+  PRIMARY KEY (topology_hash, model_name),
+  UNIQUE (table_name),
+  UNIQUE (topology_hash, table_name),
+  UNIQUE (topology_hash, model_name, table_name),
+  FOREIGN KEY (table_name, model_name)
+    REFERENCES projection_causal_tables (table_name, model_name),
+  CHECK (octet_length(topology_bytes) BETWEEN 1 AND 4096),
+  CHECK (octet_length(topology_hash) = 32),
+  CHECK (char_length(model_name) BETWEEN 1 AND 255),
+  CHECK (char_length(table_name) BETWEEN 1 AND 255)
+);
+
+-- Presence in this table is the fail-closed ownership marker. Raw/legacy write
+-- plans must reject an exact model/partition scope found here.
+CREATE TABLE IF NOT EXISTS projection_model_ownership (
+  topology_hash bytea NOT NULL,
+  partition_hash bytea NOT NULL,
+  model_name text NOT NULL,
+  table_name text NOT NULL,
+  ownership text NOT NULL DEFAULT 'causal',
+  PRIMARY KEY (topology_hash, partition_hash, model_name),
+  UNIQUE (topology_hash, partition_hash, table_name),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  FOREIGN KEY (topology_hash, model_name, table_name)
+    REFERENCES projection_registered_models (
+      topology_hash,
+      model_name,
+      table_name
+    ),
+  CHECK (octet_length(topology_hash) = 32),
+  CHECK (octet_length(partition_hash) = 32),
+  CHECK (char_length(model_name) BETWEEN 1 AND 255),
+  CHECK (char_length(table_name) BETWEEN 1 AND 255),
+  CHECK (ownership = 'causal')
+);
+
+-- Revision comparison is valid only after exact topology, partition, model,
+-- and canonical key scope equality. Tombstones remain durable; recreation
+-- advances incarnation rather than resetting an old comparison domain.
+CREATE TABLE IF NOT EXISTS projection_records (
+  topology_hash bytea NOT NULL,
+  partition_hash bytea NOT NULL,
+  model_name text NOT NULL,
+  canonical_key_bytes bytea NOT NULL,
+  canonical_key_hash bytea NOT NULL,
+  incarnation bigint NOT NULL,
+  revision bigint NOT NULL,
+  tombstone bigint NOT NULL,
+  change_epoch text NOT NULL,
+  change_position bigint NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    model_name,
+    canonical_key_hash
+  ),
+  FOREIGN KEY (topology_hash, partition_hash, model_name)
+    REFERENCES projection_model_ownership (
+      topology_hash,
+      partition_hash,
+      model_name
+    ),
+  CHECK (octet_length(topology_hash) = 32),
+  CHECK (octet_length(partition_hash) = 32),
+  CHECK (char_length(model_name) BETWEEN 1 AND 255),
+  CHECK (octet_length(canonical_key_bytes) BETWEEN 1 AND 16384),
+  CHECK (octet_length(canonical_key_hash) = 32),
+  CHECK (incarnation > 0),
+  CHECK (revision > 0),
+  CHECK (tombstone IN (0, 1)),
+  CHECK (char_length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_position > 0)
+);
+
+-- A physical primary-key row can have only one live causal scope under its
+-- owning topology. Tombstones may remain in prior partitions so an explicit
+-- delete followed by a partition move preserves incarnation history.
+CREATE UNIQUE INDEX IF NOT EXISTS projection_records_unique_live_identity
+  ON projection_records (
+    topology_hash,
+    model_name,
+    canonical_key_hash
+  )
+  WHERE tombstone = 0;
+
+-- Exact causation evidence is joined by the same canonical record/dependency
+-- scope used by command obligations; it is never inferred from a scalar max.
+CREATE TABLE IF NOT EXISTS projection_observations (
+  topology_hash bytea NOT NULL,
+  partition_hash bytea NOT NULL,
+  causation_id text NOT NULL,
+  model_name text NOT NULL,
+  scope_kind text NOT NULL,
+  canonical_key_bytes bytea NOT NULL,
+  canonical_key_hash bytea NOT NULL,
+  incarnation bigint,
+  revision bigint,
+  change_epoch text NOT NULL,
+  change_position bigint NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    causation_id,
+    model_name,
+    scope_kind,
+    canonical_key_hash
+  ),
+  FOREIGN KEY (topology_hash, partition_hash, model_name)
+    REFERENCES projection_model_ownership (
+      topology_hash,
+      partition_hash,
+      model_name
+    ),
+  CHECK (octet_length(topology_hash) = 32),
+  CHECK (octet_length(partition_hash) = 32),
+  CHECK (char_length(causation_id) BETWEEN 1 AND 128),
+  CHECK (char_length(model_name) BETWEEN 1 AND 255),
+  CHECK (scope_kind IN ('record', 'dependency')),
+  CHECK (octet_length(canonical_key_bytes) BETWEEN 1 AND 16384),
+  CHECK (octet_length(canonical_key_hash) = 32),
+  CHECK (
+    (scope_kind = 'record'
+      AND incarnation IS NOT NULL
+      AND incarnation > 0
+      AND revision IS NOT NULL
+      AND revision > 0)
+    OR
+    (scope_kind = 'dependency'
+      AND incarnation IS NULL
+      AND revision IS NULL)
+  ),
+  CHECK (char_length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_position > 0)
+);
+
+-- An exact failed cursor/generation is an immutable terminal fact. Repair
+-- creates a later linked generation; it never rewrites this row.
+CREATE TABLE IF NOT EXISTS projection_failures (
+  topology_hash bytea NOT NULL,
+  partition_hash bytea NOT NULL,
+  failure_id text NOT NULL,
+  source_bytes bytea NOT NULL,
+  source_hash bytea NOT NULL,
+  source_partition_bytes bytea NOT NULL,
+  source_partition_hash bytea NOT NULL,
+  source_epoch text NOT NULL,
+  source_position bigint NOT NULL,
+  input_hash bytea NOT NULL,
+  message_id text NOT NULL,
+  causation_id text NOT NULL,
+  gap_free bigint NOT NULL,
+  generation bigint NOT NULL,
+  failure_code text NOT NULL,
+  failure_bytes bytea NOT NULL,
+  failure_hash bytea NOT NULL,
+  change_epoch text NOT NULL,
+  change_position bigint NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    source_hash,
+    source_partition_hash,
+    source_epoch,
+    source_position,
+    generation
+  ),
+  UNIQUE (failure_id),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  FOREIGN KEY (topology_hash, partition_hash, generation)
+    REFERENCES projection_generations (
+      topology_hash,
+      partition_hash,
+      generation
+    ),
+  CHECK (octet_length(topology_hash) = 32),
+  CHECK (octet_length(partition_hash) = 32),
+  CHECK (char_length(failure_id) BETWEEN 1 AND 255),
+  CHECK (octet_length(source_bytes) BETWEEN 1 AND 1024),
+  CHECK (octet_length(source_hash) = 32),
+  CHECK (octet_length(source_partition_bytes) BETWEEN 1 AND 4096),
+  CHECK (octet_length(source_partition_hash) = 32),
+  CHECK (char_length(source_epoch) BETWEEN 1 AND 128),
+  CHECK (source_position >= 0),
+  CHECK (octet_length(input_hash) = 32),
+  CHECK (char_length(message_id) BETWEEN 1 AND 255),
+  CHECK (char_length(causation_id) BETWEEN 1 AND 128),
+  CHECK (gap_free IN (0, 1)),
+  CHECK (generation > 0),
+  CHECK (char_length(failure_code) BETWEEN 1 AND 255),
+  CHECK (octet_length(failure_bytes) BETWEEN 1 AND 1048576),
+  CHECK (octet_length(failure_hash) = 32),
+  CHECK (char_length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_position > 0)
+);
+
+-- Per-partition append log. Position zero is reserved for the empty
+-- head/compacted-through watermark and is never a stored change.
+CREATE TABLE IF NOT EXISTS projection_changes (
+  topology_hash bytea NOT NULL,
+  partition_hash bytea NOT NULL,
+  change_epoch text NOT NULL,
+  change_position bigint NOT NULL,
+  change_kind text NOT NULL,
+  causation_id text NOT NULL,
+  model_name text,
+  scope_kind text,
+  canonical_key_bytes bytea,
+  canonical_key_hash bytea,
+  incarnation bigint,
+  revision bigint,
+  failure_id text,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    change_epoch,
+    change_position
+  ),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  CHECK (octet_length(topology_hash) = 32),
+  CHECK (octet_length(partition_hash) = 32),
+  CHECK (char_length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_position > 0),
+  CHECK (change_kind IN (
+    'record_upsert',
+    'record_delete',
+    'record_recreate',
+    'observation',
+    'checkpoint',
+    'failure'
+  )),
+  CHECK (char_length(causation_id) BETWEEN 1 AND 128),
+  CHECK (
+    (change_kind IN ('record_upsert', 'record_delete', 'record_recreate')
+      AND model_name IS NOT NULL
+      AND char_length(model_name) BETWEEN 1 AND 255
+      AND scope_kind IS NULL
+      AND canonical_key_bytes IS NOT NULL
+      AND octet_length(canonical_key_bytes) BETWEEN 1 AND 16384
+      AND canonical_key_hash IS NOT NULL
+      AND octet_length(canonical_key_hash) = 32
+      AND incarnation IS NOT NULL
+      AND incarnation > 0
+      AND revision IS NOT NULL
+      AND revision > 0
+      AND failure_id IS NULL)
+    OR
+    (change_kind = 'observation'
+      AND model_name IS NOT NULL
+      AND char_length(model_name) BETWEEN 1 AND 255
+      AND scope_kind IN ('record', 'dependency')
+      AND canonical_key_bytes IS NOT NULL
+      AND octet_length(canonical_key_bytes) BETWEEN 1 AND 16384
+      AND canonical_key_hash IS NOT NULL
+      AND octet_length(canonical_key_hash) = 32
+      AND (
+        (scope_kind = 'record'
+          AND incarnation IS NOT NULL
+          AND incarnation > 0
+          AND revision IS NOT NULL
+          AND revision > 0)
+        OR
+        (scope_kind = 'dependency'
+          AND incarnation IS NULL
+          AND revision IS NULL)
+      )
+      AND failure_id IS NULL)
+    OR
+    (change_kind = 'checkpoint'
+      AND model_name IS NULL
+      AND scope_kind IS NULL
+      AND canonical_key_bytes IS NULL
+      AND canonical_key_hash IS NULL
+      AND incarnation IS NULL
+      AND revision IS NULL
+      AND failure_id IS NULL)
+    OR
+    (change_kind = 'failure'
+      AND model_name IS NULL
+      AND scope_kind IS NULL
+      AND canonical_key_bytes IS NULL
+      AND canonical_key_hash IS NULL
+      AND incarnation IS NULL
+      AND revision IS NULL
+      AND failure_id IS NOT NULL
+      AND char_length(failure_id) BETWEEN 1 AND 255)
+  )
+);
+
+CREATE INDEX IF NOT EXISTS projection_records_change_idx
+  ON projection_records (
+    topology_hash,
+    partition_hash,
+    change_epoch,
+    change_position
+  );
+
+CREATE INDEX IF NOT EXISTS projection_observations_causation_idx
+  ON projection_observations (
+    topology_hash,
+    partition_hash,
+    causation_id
+  );
+
+CREATE INDEX IF NOT EXISTS projection_input_receipts_causation_idx
+  ON projection_input_receipts (
+    topology_hash,
+    partition_hash,
+    causation_id
+  );
+
+CREATE INDEX IF NOT EXISTS projection_failures_causation_idx
+  ON projection_failures (
+    topology_hash,
+    partition_hash,
+    causation_id
+  );
+
+CREATE INDEX IF NOT EXISTS projection_changes_causation_idx
+  ON projection_changes (
+    topology_hash,
+    partition_hash,
+    causation_id
+  );
+
+CREATE INDEX IF NOT EXISTS projection_changes_record_idx
+  ON projection_changes (
+    topology_hash,
+    partition_hash,
+    model_name,
+    canonical_key_hash,
+    change_epoch,
+    change_position
+  );
diff --git a/migrations/sqlite/0002_command_ledger.sql b/migrations/sqlite/0002_command_ledger.sql
new file mode 100644
index 00000000..42ab8718
--- /dev/null
+++ b/migrations/sqlite/0002_command_ledger.sql
@@ -0,0 +1,81 @@
+-- Durable idempotency ledger for typed commands. Retention compaction turns a
+-- row into a small permanent `expired` tombstone; command identities are never
+-- deleted or reusable.
+CREATE TABLE IF NOT EXISTS command_ledger (
+  service_id TEXT NOT NULL,
+  principal_partition TEXT NOT NULL,
+  command_id TEXT NOT NULL,
+  command_name TEXT NOT NULL,
+  command_contract_hash BLOB NOT NULL,
+  input_hash BLOB NOT NULL,
+  state TEXT NOT NULL,
+  causation_id TEXT NOT NULL,
+  attempt_token TEXT,
+  attempt_number INTEGER NOT NULL,
+  lease_expires_at REAL,
+  outcome TEXT,
+  created_at REAL NOT NULL DEFAULT (unixepoch('now','subsec')),
+  updated_at REAL NOT NULL DEFAULT (unixepoch('now','subsec')),
+  completed_at REAL,
+  retention_expires_at REAL NOT NULL,
+  compacted_at REAL,
+  PRIMARY KEY (service_id, principal_partition, command_id),
+  UNIQUE (service_id, causation_id),
+  CHECK (service_id <> ''),
+  CHECK (principal_partition <> ''),
+  CHECK (command_id <> ''),
+  CHECK (command_name <> ''),
+  CHECK (typeof(command_contract_hash) = 'blob' AND length(command_contract_hash) = 32),
+  CHECK (typeof(input_hash) = 'blob' AND length(input_hash) = 32),
+  CHECK (causation_id <> ''),
+  CHECK (attempt_number > 0),
+  CHECK (outcome IS NULL OR json_valid(outcome)),
+  CHECK (state IN (
+    'in_progress',
+    'retryable_unknown',
+    'accepted',
+    'accepted_pending_projection',
+    'projected',
+    'rejected',
+    'projection_failed',
+    'expired'
+  )),
+  CHECK (
+    (state = 'in_progress'
+      AND attempt_token IS NOT NULL
+      AND lease_expires_at IS NOT NULL
+      AND outcome IS NULL
+      AND completed_at IS NULL
+      AND compacted_at IS NULL)
+    OR
+    (state = 'retryable_unknown'
+      AND attempt_token IS NULL
+      AND lease_expires_at IS NULL
+      AND outcome IS NULL
+      AND completed_at IS NULL
+      AND compacted_at IS NULL)
+    OR
+    (state IN (
+        'accepted',
+        'accepted_pending_projection',
+        'projected',
+        'rejected',
+        'projection_failed'
+      )
+      AND attempt_token IS NULL
+      AND lease_expires_at IS NULL
+      AND outcome IS NOT NULL
+      AND completed_at IS NOT NULL
+      AND compacted_at IS NULL)
+    OR
+    (state = 'expired'
+      AND attempt_token IS NULL
+      AND lease_expires_at IS NULL
+      AND outcome IS NULL
+      AND compacted_at IS NOT NULL)
+  )
+);
+
+CREATE INDEX IF NOT EXISTS command_ledger_retention_idx
+  ON command_ledger (retention_expires_at)
+  WHERE state <> 'expired';
diff --git a/migrations/sqlite/0003_projection_protocol.sql b/migrations/sqlite/0003_projection_protocol.sql
new file mode 100644
index 00000000..f5a013a6
--- /dev/null
+++ b/migrations/sqlite/0003_projection_protocol.sql
@@ -0,0 +1,724 @@
+-- Framework-owned causal projection protocol metadata.
+--
+-- This additive pre-release migration deliberately performs no backfill:
+-- existing read-model rows have no inferred causation, revision, checkpoint,
+-- observation, or ownership evidence. Adoption requires a rebuild into a new
+-- projection epoch or a separately verified importer.
+
+CREATE TABLE IF NOT EXISTS projection_partitions (
+  topology_bytes BLOB NOT NULL,
+  topology_hash BLOB NOT NULL,
+  partition_bytes BLOB NOT NULL,
+  partition_hash BLOB NOT NULL,
+  active_generation INTEGER NOT NULL DEFAULT 1,
+  change_epoch TEXT NOT NULL,
+  change_head INTEGER NOT NULL DEFAULT 0,
+  compacted_through INTEGER NOT NULL DEFAULT 0,
+  pending_retry_failure_id TEXT,
+  stopped_failure_id TEXT,
+  stopped_source_bytes BLOB,
+  stopped_source_hash BLOB,
+  stopped_source_partition_bytes BLOB,
+  stopped_source_partition_hash BLOB,
+  stopped_source_epoch TEXT,
+  stopped_source_position INTEGER,
+  stopped_generation INTEGER,
+  stopped_input_hash BLOB,
+  stopped_message_id TEXT,
+  stopped_causation_id TEXT,
+  stopped_gap_free INTEGER,
+  PRIMARY KEY (topology_hash, partition_hash),
+  CHECK (typeof(topology_bytes) = 'blob'
+    AND length(topology_bytes) BETWEEN 1 AND 4096),
+  CHECK (typeof(topology_hash) = 'blob' AND length(topology_hash) = 32),
+  CHECK (typeof(partition_bytes) = 'blob'
+    AND length(partition_bytes) BETWEEN 1 AND 4096),
+  CHECK (typeof(partition_hash) = 'blob' AND length(partition_hash) = 32),
+  CHECK (active_generation > 0),
+  CHECK (typeof(change_epoch) = 'text'
+    AND length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_head >= 0),
+  CHECK (compacted_through >= 0 AND compacted_through <= change_head),
+  CHECK (pending_retry_failure_id IS NULL
+    OR length(pending_retry_failure_id) BETWEEN 1 AND 255),
+  CHECK (pending_retry_failure_id IS NULL OR stopped_failure_id IS NULL),
+  CHECK (
+    (stopped_failure_id IS NULL
+      AND stopped_source_bytes IS NULL
+      AND stopped_source_hash IS NULL
+      AND stopped_source_partition_bytes IS NULL
+      AND stopped_source_partition_hash IS NULL
+      AND stopped_source_epoch IS NULL
+      AND stopped_source_position IS NULL
+      AND stopped_generation IS NULL
+      AND stopped_input_hash IS NULL
+      AND stopped_message_id IS NULL
+      AND stopped_causation_id IS NULL
+      AND stopped_gap_free IS NULL)
+    OR
+    (stopped_failure_id IS NOT NULL
+      AND length(stopped_failure_id) BETWEEN 1 AND 255
+      AND typeof(stopped_source_bytes) = 'blob'
+      AND length(stopped_source_bytes) BETWEEN 1 AND 1024
+      AND typeof(stopped_source_hash) = 'blob'
+      AND length(stopped_source_hash) = 32
+      AND typeof(stopped_source_partition_bytes) = 'blob'
+      AND length(stopped_source_partition_bytes) BETWEEN 1 AND 4096
+      AND typeof(stopped_source_partition_hash) = 'blob'
+      AND length(stopped_source_partition_hash) = 32
+      AND typeof(stopped_source_epoch) = 'text'
+      AND length(stopped_source_epoch) BETWEEN 1 AND 128
+      AND stopped_source_position IS NOT NULL
+      AND stopped_source_position >= 0
+      AND stopped_generation IS NOT NULL
+      AND stopped_generation > 0
+      AND typeof(stopped_input_hash) = 'blob'
+      AND length(stopped_input_hash) = 32
+      AND stopped_message_id IS NOT NULL
+      AND length(stopped_message_id) BETWEEN 1 AND 255
+      AND stopped_causation_id IS NOT NULL
+      AND length(stopped_causation_id) BETWEEN 1 AND 128
+      AND stopped_gap_free IS NOT NULL
+      AND stopped_gap_free IN (0, 1))
+  )
+);
+
+-- Repair generations are partition-wide durable facts. Generation one is the
+-- original run; every later generation is linked to exactly one prior
+-- generation and immutable terminal failure. The retry failure link is checked
+-- by the repair transaction because a declarative foreign key would be
+-- circular with projection_failures -> projection_generations.
+CREATE TABLE IF NOT EXISTS projection_generations (
+  topology_hash BLOB NOT NULL,
+  partition_hash BLOB NOT NULL,
+  generation INTEGER NOT NULL,
+  retry_of_generation INTEGER,
+  retry_of_failure_id TEXT,
+  PRIMARY KEY (topology_hash, partition_hash, generation),
+  UNIQUE (topology_hash, partition_hash, retry_of_failure_id),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  CHECK (typeof(topology_hash) = 'blob' AND length(topology_hash) = 32),
+  CHECK (typeof(partition_hash) = 'blob' AND length(partition_hash) = 32),
+  CHECK (generation > 0),
+  CHECK (
+    (generation = 1
+      AND retry_of_generation IS NULL
+      AND retry_of_failure_id IS NULL)
+    OR
+    (generation > 1
+      AND retry_of_generation IS NOT NULL
+      AND retry_of_generation > 0
+      AND retry_of_generation < generation
+      AND retry_of_failure_id IS NOT NULL
+      AND length(retry_of_failure_id) BETWEEN 1 AND 255)
+  )
+);
+
+-- Durable ordering capability for one exact source scope. It is independent of
+-- source epoch and repair generation, so a source cannot change between
+-- gap-tolerant and gap-free ordering after either advancement or first failure.
+CREATE TABLE IF NOT EXISTS projection_source_capabilities (
+  topology_hash BLOB NOT NULL,
+  partition_hash BLOB NOT NULL,
+  source_bytes BLOB NOT NULL,
+  source_hash BLOB NOT NULL,
+  source_partition_bytes BLOB NOT NULL,
+  source_partition_hash BLOB NOT NULL,
+  gap_free INTEGER NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    source_hash,
+    source_partition_hash
+  ),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  CHECK (typeof(topology_hash) = 'blob' AND length(topology_hash) = 32),
+  CHECK (typeof(partition_hash) = 'blob' AND length(partition_hash) = 32),
+  CHECK (typeof(source_bytes) = 'blob'
+    AND length(source_bytes) BETWEEN 1 AND 1024),
+  CHECK (typeof(source_hash) = 'blob' AND length(source_hash) = 32),
+  CHECK (typeof(source_partition_bytes) = 'blob'
+    AND length(source_partition_bytes) BETWEEN 1 AND 4096),
+  CHECK (typeof(source_partition_hash) = 'blob'
+    AND length(source_partition_hash) = 32),
+  CHECK (gap_free IN (0, 1))
+);
+
+-- Generation-independent authenticated input identity. Repair generations
+-- scope outcomes/re-execution, not the identity of a source cursor or message.
+-- These rows survive repair and change-log compaction.
+CREATE TABLE IF NOT EXISTS projection_input_identities (
+  topology_hash BLOB NOT NULL,
+  partition_hash BLOB NOT NULL,
+  source_bytes BLOB NOT NULL,
+  source_hash BLOB NOT NULL,
+  source_partition_bytes BLOB NOT NULL,
+  source_partition_hash BLOB NOT NULL,
+  source_epoch TEXT NOT NULL,
+  source_position INTEGER NOT NULL,
+  input_hash BLOB NOT NULL,
+  message_id TEXT NOT NULL,
+  causation_id TEXT NOT NULL,
+  gap_free INTEGER NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    source_hash,
+    source_partition_hash,
+    source_epoch,
+    source_position
+  ),
+  UNIQUE (topology_hash, message_id),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  CHECK (typeof(topology_hash) = 'blob' AND length(topology_hash) = 32),
+  CHECK (typeof(partition_hash) = 'blob' AND length(partition_hash) = 32),
+  CHECK (typeof(source_bytes) = 'blob'
+    AND length(source_bytes) BETWEEN 1 AND 1024),
+  CHECK (typeof(source_hash) = 'blob' AND length(source_hash) = 32),
+  CHECK (typeof(source_partition_bytes) = 'blob'
+    AND length(source_partition_bytes) BETWEEN 1 AND 4096),
+  CHECK (typeof(source_partition_hash) = 'blob'
+    AND length(source_partition_hash) = 32),
+  CHECK (typeof(source_epoch) = 'text'
+    AND length(source_epoch) BETWEEN 1 AND 128),
+  CHECK (source_position >= 0),
+  CHECK (typeof(input_hash) = 'blob' AND length(input_hash) = 32),
+  CHECK (length(message_id) BETWEEN 1 AND 255),
+  CHECK (length(causation_id) BETWEEN 1 AND 128),
+  CHECK (gap_free IN (0, 1))
+);
+
+-- One durable last-good checkpoint per exact ordered source scope and repair
+-- generation, including the change cursor allocated by its commit. Source
+-- epoch is fenced row data: an epoch mismatch is incomparable and requires a
+-- new projector topology plus read-model rebuild. Repair is failure-only and
+-- cannot bridge source epochs.
+CREATE TABLE IF NOT EXISTS projection_input_cursors (
+  topology_hash BLOB NOT NULL,
+  partition_hash BLOB NOT NULL,
+  source_bytes BLOB NOT NULL,
+  source_hash BLOB NOT NULL,
+  source_partition_bytes BLOB NOT NULL,
+  source_partition_hash BLOB NOT NULL,
+  source_epoch TEXT NOT NULL,
+  source_position INTEGER NOT NULL,
+  input_hash BLOB NOT NULL,
+  message_id TEXT NOT NULL,
+  causation_id TEXT NOT NULL,
+  gap_free INTEGER NOT NULL,
+  generation INTEGER NOT NULL,
+  change_epoch TEXT NOT NULL,
+  change_position INTEGER NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    source_hash,
+    source_partition_hash,
+    generation
+  ),
+  UNIQUE (
+    topology_hash,
+    partition_hash,
+    source_hash,
+    source_partition_hash,
+    message_id,
+    generation
+  ),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  FOREIGN KEY (topology_hash, partition_hash, generation)
+    REFERENCES projection_generations (
+      topology_hash,
+      partition_hash,
+      generation
+    ),
+  CHECK (typeof(topology_hash) = 'blob' AND length(topology_hash) = 32),
+  CHECK (typeof(partition_hash) = 'blob' AND length(partition_hash) = 32),
+  CHECK (typeof(source_bytes) = 'blob'
+    AND length(source_bytes) BETWEEN 1 AND 1024),
+  CHECK (typeof(source_hash) = 'blob' AND length(source_hash) = 32),
+  CHECK (typeof(source_partition_bytes) = 'blob'
+    AND length(source_partition_bytes) BETWEEN 1 AND 4096),
+  CHECK (typeof(source_partition_hash) = 'blob'
+    AND length(source_partition_hash) = 32),
+  CHECK (typeof(source_epoch) = 'text'
+    AND length(source_epoch) BETWEEN 1 AND 128),
+  CHECK (source_position >= 0),
+  CHECK (typeof(input_hash) = 'blob' AND length(input_hash) = 32),
+  CHECK (length(message_id) BETWEEN 1 AND 255),
+  CHECK (length(causation_id) BETWEEN 1 AND 128),
+  CHECK (gap_free IN (0, 1)),
+  CHECK (generation > 0),
+  CHECK (typeof(change_epoch) = 'text'
+    AND length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_position > 0)
+);
+
+-- Append-only identity evidence for every terminal input outcome. Unlike the
+-- mutable last-good cursor above, a receipt remains able to distinguish an exact
+-- duplicate from message-ID or source-cursor reuse after later checkpoints
+-- advance. Source scope is deliberately not part of the primary key so lookup
+-- by partition generation and message ID also detects cross-source reuse.
+-- The accepted change cursor remains durable after change-log compaction, so
+-- it intentionally has no foreign key to projection_changes.
+CREATE TABLE IF NOT EXISTS projection_input_receipts (
+  topology_hash BLOB NOT NULL,
+  partition_hash BLOB NOT NULL,
+  generation INTEGER NOT NULL,
+  message_id TEXT NOT NULL,
+  source_bytes BLOB NOT NULL,
+  source_hash BLOB NOT NULL,
+  source_partition_bytes BLOB NOT NULL,
+  source_partition_hash BLOB NOT NULL,
+  source_epoch TEXT NOT NULL,
+  source_position INTEGER NOT NULL,
+  input_hash BLOB NOT NULL,
+  causation_id TEXT NOT NULL,
+  gap_free INTEGER NOT NULL,
+  outcome_kind TEXT NOT NULL,
+  failure_id TEXT,
+  change_epoch TEXT NOT NULL,
+  change_position INTEGER NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    generation,
+    message_id
+  ),
+  UNIQUE (
+    topology_hash,
+    partition_hash,
+    generation,
+    source_hash,
+    source_partition_hash,
+    source_epoch,
+    source_position
+  ),
+  UNIQUE (
+    topology_hash,
+    partition_hash,
+    change_epoch,
+    change_position
+  ),
+  FOREIGN KEY (topology_hash, partition_hash, generation)
+    REFERENCES projection_generations (
+      topology_hash,
+      partition_hash,
+      generation
+    ),
+  CHECK (typeof(topology_hash) = 'blob' AND length(topology_hash) = 32),
+  CHECK (typeof(partition_hash) = 'blob' AND length(partition_hash) = 32),
+  CHECK (generation > 0),
+  CHECK (length(message_id) BETWEEN 1 AND 255),
+  CHECK (typeof(source_bytes) = 'blob'
+    AND length(source_bytes) BETWEEN 1 AND 1024),
+  CHECK (typeof(source_hash) = 'blob' AND length(source_hash) = 32),
+  CHECK (typeof(source_partition_bytes) = 'blob'
+    AND length(source_partition_bytes) BETWEEN 1 AND 4096),
+  CHECK (typeof(source_partition_hash) = 'blob'
+    AND length(source_partition_hash) = 32),
+  CHECK (typeof(source_epoch) = 'text'
+    AND length(source_epoch) BETWEEN 1 AND 128),
+  CHECK (source_position >= 0),
+  CHECK (typeof(input_hash) = 'blob' AND length(input_hash) = 32),
+  CHECK (length(causation_id) BETWEEN 1 AND 128),
+  CHECK (gap_free IN (0, 1)),
+  CHECK (outcome_kind IN ('applied', 'failed')),
+  CHECK (
+    (outcome_kind = 'applied' AND failure_id IS NULL)
+    OR
+    (outcome_kind = 'failed'
+      AND failure_id IS NOT NULL
+      AND length(failure_id) BETWEEN 1 AND 255)
+  ),
+  CHECK (typeof(change_epoch) = 'text'
+    AND length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_position > 0)
+);
+
+-- Per-table serialization point shared by raw writers and causal bootstrap.
+-- The first INSERT is a SQLite write and therefore serializes ownership
+-- decisions until transaction commit, closing the absent-marker race.
+CREATE TABLE IF NOT EXISTS projection_table_ownership_fences (
+  table_name TEXT PRIMARY KEY,
+  CHECK (length(table_name) BETWEEN 1 AND 255)
+);
+
+-- Model-wide bootstrap marker used by raw write paths, which do not carry a
+-- typed projection partition. Presence makes the table exclusively causal;
+-- partition-specific ownership below must reference this exact table/model
+-- registration.
+CREATE TABLE IF NOT EXISTS projection_causal_tables (
+  table_name TEXT NOT NULL,
+  model_name TEXT NOT NULL,
+  ownership TEXT NOT NULL DEFAULT 'causal',
+  PRIMARY KEY (table_name, model_name),
+  UNIQUE (table_name),
+  FOREIGN KEY (table_name)
+    REFERENCES projection_table_ownership_fences (table_name),
+  CHECK (length(table_name) BETWEEN 1 AND 255),
+  CHECK (length(model_name) BETWEEN 1 AND 255),
+  CHECK (ownership = 'causal')
+);
+
+-- Authoritative physical-table bootstrap declaration. Canonical topology bytes
+-- make digest collisions detectable; global table uniqueness deliberately
+-- forbids independent projector topologies from owning the same physical rows.
+CREATE TABLE IF NOT EXISTS projection_registered_models (
+  topology_bytes BLOB NOT NULL,
+  topology_hash BLOB NOT NULL,
+  model_name TEXT NOT NULL,
+  table_name TEXT NOT NULL,
+  PRIMARY KEY (topology_hash, model_name),
+  UNIQUE (table_name),
+  UNIQUE (topology_hash, table_name),
+  UNIQUE (topology_hash, model_name, table_name),
+  FOREIGN KEY (table_name, model_name)
+    REFERENCES projection_causal_tables (table_name, model_name),
+  CHECK (typeof(topology_bytes) = 'blob'
+    AND length(topology_bytes) BETWEEN 1 AND 4096),
+  CHECK (typeof(topology_hash) = 'blob' AND length(topology_hash) = 32),
+  CHECK (length(model_name) BETWEEN 1 AND 255),
+  CHECK (length(table_name) BETWEEN 1 AND 255)
+);
+
+-- Presence in this table is the fail-closed ownership marker. Raw/legacy write
+-- plans must reject an exact model/partition scope found here.
+CREATE TABLE IF NOT EXISTS projection_model_ownership (
+  topology_hash BLOB NOT NULL,
+  partition_hash BLOB NOT NULL,
+  model_name TEXT NOT NULL,
+  table_name TEXT NOT NULL,
+  ownership TEXT NOT NULL DEFAULT 'causal',
+  PRIMARY KEY (topology_hash, partition_hash, model_name),
+  UNIQUE (topology_hash, partition_hash, table_name),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  FOREIGN KEY (topology_hash, model_name, table_name)
+    REFERENCES projection_registered_models (
+      topology_hash,
+      model_name,
+      table_name
+    ),
+  CHECK (typeof(topology_hash) = 'blob' AND length(topology_hash) = 32),
+  CHECK (typeof(partition_hash) = 'blob' AND length(partition_hash) = 32),
+  CHECK (length(model_name) BETWEEN 1 AND 255),
+  CHECK (length(table_name) BETWEEN 1 AND 255),
+  CHECK (ownership = 'causal')
+);
+
+-- Revision comparison is valid only after exact topology, partition, model,
+-- and canonical key scope equality. Tombstones remain durable; recreation
+-- advances incarnation rather than resetting an old comparison domain.
+CREATE TABLE IF NOT EXISTS projection_records (
+  topology_hash BLOB NOT NULL,
+  partition_hash BLOB NOT NULL,
+  model_name TEXT NOT NULL,
+  canonical_key_bytes BLOB NOT NULL,
+  canonical_key_hash BLOB NOT NULL,
+  incarnation INTEGER NOT NULL,
+  revision INTEGER NOT NULL,
+  tombstone INTEGER NOT NULL,
+  change_epoch TEXT NOT NULL,
+  change_position INTEGER NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    model_name,
+    canonical_key_hash
+  ),
+  FOREIGN KEY (topology_hash, partition_hash, model_name)
+    REFERENCES projection_model_ownership (
+      topology_hash,
+      partition_hash,
+      model_name
+    ),
+  CHECK (typeof(topology_hash) = 'blob' AND length(topology_hash) = 32),
+  CHECK (typeof(partition_hash) = 'blob' AND length(partition_hash) = 32),
+  CHECK (length(model_name) BETWEEN 1 AND 255),
+  CHECK (typeof(canonical_key_bytes) = 'blob'
+    AND length(canonical_key_bytes) BETWEEN 1 AND 16384),
+  CHECK (typeof(canonical_key_hash) = 'blob'
+    AND length(canonical_key_hash) = 32),
+  CHECK (incarnation > 0),
+  CHECK (revision > 0),
+  CHECK (tombstone IN (0, 1)),
+  CHECK (typeof(change_epoch) = 'text'
+    AND length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_position > 0)
+);
+
+-- A physical primary-key row can have only one live causal scope under its
+-- owning topology. Tombstones may remain in prior partitions so an explicit
+-- delete followed by a partition move preserves incarnation history.
+CREATE UNIQUE INDEX IF NOT EXISTS projection_records_unique_live_identity
+  ON projection_records (
+    topology_hash,
+    model_name,
+    canonical_key_hash
+  )
+  WHERE tombstone = 0;
+
+-- Exact causation evidence is joined by the same canonical record/dependency
+-- scope used by command obligations; it is never inferred from a scalar max.
+CREATE TABLE IF NOT EXISTS projection_observations (
+  topology_hash BLOB NOT NULL,
+  partition_hash BLOB NOT NULL,
+  causation_id TEXT NOT NULL,
+  model_name TEXT NOT NULL,
+  scope_kind TEXT NOT NULL,
+  canonical_key_bytes BLOB NOT NULL,
+  canonical_key_hash BLOB NOT NULL,
+  incarnation INTEGER,
+  revision INTEGER,
+  change_epoch TEXT NOT NULL,
+  change_position INTEGER NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    causation_id,
+    model_name,
+    scope_kind,
+    canonical_key_hash
+  ),
+  FOREIGN KEY (topology_hash, partition_hash, model_name)
+    REFERENCES projection_model_ownership (
+      topology_hash,
+      partition_hash,
+      model_name
+    ),
+  CHECK (typeof(topology_hash) = 'blob' AND length(topology_hash) = 32),
+  CHECK (typeof(partition_hash) = 'blob' AND length(partition_hash) = 32),
+  CHECK (length(causation_id) BETWEEN 1 AND 128),
+  CHECK (length(model_name) BETWEEN 1 AND 255),
+  CHECK (scope_kind IN ('record', 'dependency')),
+  CHECK (typeof(canonical_key_bytes) = 'blob'
+    AND length(canonical_key_bytes) BETWEEN 1 AND 16384),
+  CHECK (typeof(canonical_key_hash) = 'blob'
+    AND length(canonical_key_hash) = 32),
+  CHECK (
+    (scope_kind = 'record'
+      AND incarnation IS NOT NULL
+      AND incarnation > 0
+      AND revision IS NOT NULL
+      AND revision > 0)
+    OR
+    (scope_kind = 'dependency'
+      AND incarnation IS NULL
+      AND revision IS NULL)
+  ),
+  CHECK (typeof(change_epoch) = 'text'
+    AND length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_position > 0)
+);
+
+-- An exact failed cursor/generation is an immutable terminal fact. Repair
+-- creates a later linked generation; it never rewrites this row.
+CREATE TABLE IF NOT EXISTS projection_failures (
+  topology_hash BLOB NOT NULL,
+  partition_hash BLOB NOT NULL,
+  failure_id TEXT NOT NULL,
+  source_bytes BLOB NOT NULL,
+  source_hash BLOB NOT NULL,
+  source_partition_bytes BLOB NOT NULL,
+  source_partition_hash BLOB NOT NULL,
+  source_epoch TEXT NOT NULL,
+  source_position INTEGER NOT NULL,
+  input_hash BLOB NOT NULL,
+  message_id TEXT NOT NULL,
+  causation_id TEXT NOT NULL,
+  gap_free INTEGER NOT NULL,
+  generation INTEGER NOT NULL,
+  failure_code TEXT NOT NULL,
+  failure_bytes BLOB NOT NULL,
+  failure_hash BLOB NOT NULL,
+  change_epoch TEXT NOT NULL,
+  change_position INTEGER NOT NULL,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    source_hash,
+    source_partition_hash,
+    source_epoch,
+    source_position,
+    generation
+  ),
+  UNIQUE (failure_id),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  FOREIGN KEY (topology_hash, partition_hash, generation)
+    REFERENCES projection_generations (
+      topology_hash,
+      partition_hash,
+      generation
+    ),
+  CHECK (typeof(topology_hash) = 'blob' AND length(topology_hash) = 32),
+  CHECK (typeof(partition_hash) = 'blob' AND length(partition_hash) = 32),
+  CHECK (length(failure_id) BETWEEN 1 AND 255),
+  CHECK (typeof(source_bytes) = 'blob'
+    AND length(source_bytes) BETWEEN 1 AND 1024),
+  CHECK (typeof(source_hash) = 'blob' AND length(source_hash) = 32),
+  CHECK (typeof(source_partition_bytes) = 'blob'
+    AND length(source_partition_bytes) BETWEEN 1 AND 4096),
+  CHECK (typeof(source_partition_hash) = 'blob'
+    AND length(source_partition_hash) = 32),
+  CHECK (typeof(source_epoch) = 'text'
+    AND length(source_epoch) BETWEEN 1 AND 128),
+  CHECK (source_position >= 0),
+  CHECK (typeof(input_hash) = 'blob' AND length(input_hash) = 32),
+  CHECK (length(message_id) BETWEEN 1 AND 255),
+  CHECK (length(causation_id) BETWEEN 1 AND 128),
+  CHECK (gap_free IN (0, 1)),
+  CHECK (generation > 0),
+  CHECK (length(failure_code) BETWEEN 1 AND 255),
+  CHECK (typeof(failure_bytes) = 'blob'
+    AND length(failure_bytes) BETWEEN 1 AND 1048576),
+  CHECK (typeof(failure_hash) = 'blob' AND length(failure_hash) = 32),
+  CHECK (typeof(change_epoch) = 'text'
+    AND length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_position > 0)
+);
+
+-- Per-partition append log. Position zero is reserved for the empty
+-- head/compacted-through watermark and is never a stored change.
+CREATE TABLE IF NOT EXISTS projection_changes (
+  topology_hash BLOB NOT NULL,
+  partition_hash BLOB NOT NULL,
+  change_epoch TEXT NOT NULL,
+  change_position INTEGER NOT NULL,
+  change_kind TEXT NOT NULL,
+  causation_id TEXT NOT NULL,
+  model_name TEXT,
+  scope_kind TEXT,
+  canonical_key_bytes BLOB,
+  canonical_key_hash BLOB,
+  incarnation INTEGER,
+  revision INTEGER,
+  failure_id TEXT,
+  PRIMARY KEY (
+    topology_hash,
+    partition_hash,
+    change_epoch,
+    change_position
+  ),
+  FOREIGN KEY (topology_hash, partition_hash)
+    REFERENCES projection_partitions (topology_hash, partition_hash),
+  CHECK (typeof(topology_hash) = 'blob' AND length(topology_hash) = 32),
+  CHECK (typeof(partition_hash) = 'blob' AND length(partition_hash) = 32),
+  CHECK (typeof(change_epoch) = 'text'
+    AND length(change_epoch) BETWEEN 1 AND 128),
+  CHECK (change_position > 0),
+  CHECK (change_kind IN (
+    'record_upsert',
+    'record_delete',
+    'record_recreate',
+    'observation',
+    'checkpoint',
+    'failure'
+  )),
+  CHECK (length(causation_id) BETWEEN 1 AND 128),
+  CHECK (
+    (change_kind IN ('record_upsert', 'record_delete', 'record_recreate')
+      AND model_name IS NOT NULL
+      AND length(model_name) BETWEEN 1 AND 255
+      AND scope_kind IS NULL
+      AND typeof(canonical_key_bytes) = 'blob'
+      AND length(canonical_key_bytes) BETWEEN 1 AND 16384
+      AND typeof(canonical_key_hash) = 'blob'
+      AND length(canonical_key_hash) = 32
+      AND incarnation IS NOT NULL
+      AND incarnation > 0
+      AND revision IS NOT NULL
+      AND revision > 0
+      AND failure_id IS NULL)
+    OR
+    (change_kind = 'observation'
+      AND model_name IS NOT NULL
+      AND length(model_name) BETWEEN 1 AND 255
+      AND scope_kind IN ('record', 'dependency')
+      AND typeof(canonical_key_bytes) = 'blob'
+      AND length(canonical_key_bytes) BETWEEN 1 AND 16384
+      AND typeof(canonical_key_hash) = 'blob'
+      AND length(canonical_key_hash) = 32
+      AND (
+        (scope_kind = 'record'
+          AND incarnation IS NOT NULL
+          AND incarnation > 0
+          AND revision IS NOT NULL
+          AND revision > 0)
+        OR
+        (scope_kind = 'dependency'
+          AND incarnation IS NULL
+          AND revision IS NULL)
+      )
+      AND failure_id IS NULL)
+    OR
+    (change_kind = 'checkpoint'
+      AND model_name IS NULL
+      AND scope_kind IS NULL
+      AND canonical_key_bytes IS NULL
+      AND canonical_key_hash IS NULL
+      AND incarnation IS NULL
+      AND revision IS NULL
+      AND failure_id IS NULL)
+    OR
+    (change_kind = 'failure'
+      AND model_name IS NULL
+      AND scope_kind IS NULL
+      AND canonical_key_bytes IS NULL
+      AND canonical_key_hash IS NULL
+      AND incarnation IS NULL
+      AND revision IS NULL
+      AND failure_id IS NOT NULL
+      AND length(failure_id) BETWEEN 1 AND 255)
+  )
+);
+
+CREATE INDEX IF NOT EXISTS projection_records_change_idx
+  ON projection_records (
+    topology_hash,
+    partition_hash,
+    change_epoch,
+    change_position
+  );
+
+CREATE INDEX IF NOT EXISTS projection_observations_causation_idx
+  ON projection_observations (
+    topology_hash,
+    partition_hash,
+    causation_id
+  );
+
+CREATE INDEX IF NOT EXISTS projection_input_receipts_causation_idx
+  ON projection_input_receipts (
+    topology_hash,
+    partition_hash,
+    causation_id
+  );
+
+CREATE INDEX IF NOT EXISTS projection_failures_causation_idx
+  ON projection_failures (
+    topology_hash,
+    partition_hash,
+    causation_id
+  );
+
+CREATE INDEX IF NOT EXISTS projection_changes_causation_idx
+  ON projection_changes (
+    topology_hash,
+    partition_hash,
+    causation_id
+  );
+
+CREATE INDEX IF NOT EXISTS projection_changes_record_idx
+  ON projection_changes (
+    topology_hash,
+    partition_hash,
+    model_name,
+    canonical_key_hash,
+    change_epoch,
+    change_position
+  );
diff --git a/scripts/ci-bootstrap-graphql-oidc.sh b/scripts/ci-bootstrap-graphql-oidc.sh
new file mode 100755
index 00000000..03070b0f
--- /dev/null
+++ b/scripts/ci-bootstrap-graphql-oidc.sh
@@ -0,0 +1,368 @@
+#!/usr/bin/env bash
+# Bootstrap live Zitadel for GraphQL OIDC e2e (D11 JWT-bearer mint).
+# Expects Zitadel from tests/graphql_oidc_zitadel/docker-compose.yml.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+COMPOSE_DIR="$ROOT/tests/graphql_oidc_zitadel"
+MACHINEKEY_DIR="$COMPOSE_DIR/machinekey"
+ZITADEL_HOST="${ZITADEL_HOST:-http://localhost:8080}"
+OUT="${GRAPHQL_OIDC_ENV:-$ROOT/graphql-oidc.env}"
+PROJECT_NAME="${GRAPHQL_OIDC_PROJECT:-distributed-graphql}"
+APP_NAME="${GRAPHQL_OIDC_APP:-graphql-api}"
+
+need() { command -v "$1" >/dev/null 2>&1 || { echo "ERROR: $1 required"; exit 1; }; }
+need jq
+need curl
+need openssl
+
+b64url() { openssl base64 -e -A | tr '+/' '-_' | tr -d '='; }
+
+echo "==> Waiting for Zitadel at $ZITADEL_HOST ..."
+for i in $(seq 1 90); do
+  if curl -fsS "$ZITADEL_HOST/debug/ready" >/dev/null 2>&1; then
+    echo "    ready"
+    break
+  fi
+  sleep 2
+  if [[ $i -eq 90 ]]; then
+    echo "ERROR: Zitadel never ready"
+    exit 1
+  fi
+done
+
+# Wait for FirstInstance machine key
+KEYFILE=""
+for i in $(seq 1 60); do
+  shopt -s nullglob
+  keys=("$MACHINEKEY_DIR"/*.json)
+  shopt -u nullglob
+  if [[ ${#keys[@]} -gt 0 ]]; then
+    KEYFILE="${keys[0]}"
+    break
+  fi
+  sleep 2
+done
+if [[ -z "$KEYFILE" || ! -s "$KEYFILE" ]]; then
+  echo "ERROR: no machine key in $MACHINEKEY_DIR (FirstInstance steps)"
+  exit 1
+fi
+echo "==> Using machine key: $KEYFILE"
+
+USER_ID=$(jq -r .userId "$KEYFILE")
+KEY_ID=$(jq -r .keyId "$KEYFILE")
+# Zitadel machine keys store PEM under .key
+KEY_PEM=$(jq -r .key "$KEYFILE")
+if [[ -z "$USER_ID" || "$USER_ID" == "null" || -z "$KEY_PEM" || "$KEY_PEM" == "null" ]]; then
+  echo "ERROR: invalid machine key JSON"
+  exit 1
+fi
+
+# Sign JWT-bearer assertion (same pattern as website setup-local-zitadel.sh)
+NOW=$(date +%s)
+EXP=$((NOW + 60))
+HEADER=$(printf '{"alg":"RS256","typ":"JWT","kid":"%s"}' "$KEY_ID" | b64url)
+PAYLOAD=$(printf '{"iss":"%s","sub":"%s","aud":"%s","iat":%s,"exp":%s}' \
+  "$USER_ID" "$USER_ID" "$ZITADEL_HOST" "$NOW" "$EXP" | b64url)
+SIGNING_INPUT="${HEADER}.${PAYLOAD}"
+TMPKEY=$(mktemp)
+trap 'rm -f "$TMPKEY"' EXIT
+printf '%s\n' "$KEY_PEM" > "$TMPKEY"
+SIGNATURE=$(printf '%s' "$SIGNING_INPUT" | openssl dgst -sha256 -sign "$TMPKEY" | b64url)
+JWT="${SIGNING_INPUT}.${SIGNATURE}"
+
+echo "==> Exchanging admin JWT for access token..."
+ACCESS_TOKEN=""
+for i in $(seq 1 60); do
+  # Refresh short-lived assertion if needed
+  if [[ $i -gt 1 ]]; then
+    NOW=$(date +%s)
+    EXP=$((NOW + 60))
+    PAYLOAD=$(printf '{"iss":"%s","sub":"%s","aud":"%s","iat":%s,"exp":%s}' \
+      "$USER_ID" "$USER_ID" "$ZITADEL_HOST" "$NOW" "$EXP" | b64url)
+    SIGNING_INPUT="${HEADER}.${PAYLOAD}"
+    SIGNATURE=$(printf '%s' "$SIGNING_INPUT" | openssl dgst -sha256 -sign "$TMPKEY" | b64url)
+    JWT="${SIGNING_INPUT}.${SIGNATURE}"
+  fi
+  TOKEN_RESPONSE=$(curl -sS -X POST "$ZITADEL_HOST/oauth/v2/token" \
+    -H 'Content-Type: application/x-www-form-urlencoded' \
+    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
+    --data-urlencode "scope=openid urn:zitadel:iam:org:project:id:zitadel:aud" \
+    --data-urlencode "assertion=$JWT" || true)
+  ACCESS_TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r '.access_token // empty' 2>/dev/null || true)
+  if [[ -n "$ACCESS_TOKEN" && "$ACCESS_TOKEN" != "null" ]]; then
+    echo "    got access token (attempt $i)"
+    break
+  fi
+  sleep 2
+  if [[ $i -eq 60 ]]; then
+    echo "ERROR: token exchange failed"
+    echo "$TOKEN_RESPONSE" | jq . 2>/dev/null || echo "$TOKEN_RESPONSE"
+    exit 1
+  fi
+done
+
+# curl -f exits 22 on 4xx/5xx; management returns 503 while projections catch up
+# after /debug/ready. Retry with backoff until we get HTTP 200.
+api() {
+  local method="$1" path="$2" body="${3:-}"
+  local attempt http_code out
+  for attempt in $(seq 1 45); do
+    if [[ -n "$body" ]]; then
+      out=$(curl -sS -w '\n%{http_code}' -X "$method" "$ZITADEL_HOST$path" \
+        -H "Authorization: Bearer $ACCESS_TOKEN" \
+        -H 'Content-Type: application/json' \
+        -d "$body" || true)
+    else
+      out=$(curl -sS -w '\n%{http_code}' -X "$method" "$ZITADEL_HOST$path" \
+        -H "Authorization: Bearer $ACCESS_TOKEN" || true)
+    fi
+    http_code=$(echo "$out" | tail -n1)
+    out=$(echo "$out" | sed '$d')
+    if [[ "$http_code" == "200" || "$http_code" == "201" ]]; then
+      printf '%s' "$out"
+      return 0
+    fi
+    # 401/403 are not readiness races
+    if [[ "$http_code" == "401" || "$http_code" == "403" ]]; then
+      echo "ERROR: management API $method $path → HTTP $http_code" >&2
+      echo "$out" >&2
+      return 1
+    fi
+    sleep 2
+  done
+  echo "ERROR: management API $method $path still not ready (last HTTP ${http_code:-none})" >&2
+  echo "$out" >&2
+  return 1
+}
+
+echo "==> Wait for management API (projects/_search) — /debug/ready is not enough"
+api POST /management/v1/projects/_search '{}' >/dev/null
+echo "    management API ready"
+
+echo "==> Ensure project $PROJECT_NAME"
+PROJECT_SEARCH=$(api POST /management/v1/projects/_search '{}')
+PROJECT_ID=$(echo "$PROJECT_SEARCH" | jq -r --arg n "$PROJECT_NAME" \
+  '.result[]? | select(.name == $n) | .id' | head -n1)
+if [[ -z "$PROJECT_ID" ]]; then
+  PROJECT_ID=$(api POST /management/v1/projects "$(jq -n --arg n "$PROJECT_NAME" '{name: $n}')" | jq -r .id)
+fi
+echo "    project=$PROJECT_ID"
+
+# Project roles admin + customer (required for E1 isolation via urn:zitadel:iam:org:project:roles)
+# Zitadel AddProjectRoleRequest uses **roleKey** (not key); search results use `key`.
+echo "==> Ensure project roles admin + customer"
+for role in admin customer; do
+  role_resp=$(api POST "/management/v1/projects/$PROJECT_ID/roles" \
+    "$(jq -n --arg k "$role" --arg d "$role" '{roleKey: $k, displayName: $d}')" 2>/dev/null || true)
+  roles_list=$(api POST "/management/v1/projects/$PROJECT_ID/roles/_search" '{}' 2>/dev/null || echo '{}')
+  if ! echo "$roles_list" | jq -e --arg k "$role" '.result[]? | select(.key == $k)' >/dev/null 2>&1; then
+    echo "ERROR: project role '$role' missing after create"
+    echo "create: $role_resp"
+    echo "list: $roles_list"
+    exit 1
+  fi
+  echo "    role ok: $role"
+done
+
+echo "==> Ensure OIDC app $APP_NAME (JWT access tokens + role assertion)"
+APP_SEARCH=$(api POST "/management/v1/projects/$PROJECT_ID/apps/_search" '{}')
+APP_ID=$(echo "$APP_SEARCH" | jq -r --arg n "$APP_NAME" \
+  '.result[]? | select(.name == $n) | .id' | head -n1)
+CLIENT_ID=""
+if [[ -z "$APP_ID" ]]; then
+  APP_RESP=$(api POST "/management/v1/projects/$PROJECT_ID/apps/oidc" "$(jq -n \
+    --arg name "$APP_NAME" \
+    '{
+      name: $name,
+      redirectUris: ["http://localhost/callback"],
+      responseTypes: ["OIDC_RESPONSE_TYPE_CODE"],
+      grantTypes: ["OIDC_GRANT_TYPE_AUTHORIZATION_CODE", "OIDC_GRANT_TYPE_REFRESH_TOKEN"],
+      appType: "OIDC_APP_TYPE_WEB",
+      authMethodType: "OIDC_AUTH_METHOD_TYPE_BASIC",
+      postLogoutRedirectUris: ["http://localhost/"],
+      version: "OIDC_VERSION_1_0",
+      devMode: true,
+      accessTokenType: "OIDC_TOKEN_TYPE_JWT",
+      accessTokenRoleAssertion: true,
+      idTokenRoleAssertion: true,
+      idTokenUserinfoAssertion: true
+    }')")
+  CLIENT_ID=$(echo "$APP_RESP" | jq -r '.clientId // empty')
+  APP_ID=$(echo "$APP_RESP" | jq -r '.appId // .id // empty')
+  echo "    create response clientId=$CLIENT_ID appId=$APP_ID"
+  if [[ -z "$CLIENT_ID" || "$CLIENT_ID" == "null" ]]; then
+    echo "ERROR: OIDC app create failed"
+    echo "$APP_RESP" | jq . 2>/dev/null || echo "$APP_RESP"
+    exit 1
+  fi
+else
+  # Existing app: client id from search result
+  CLIENT_ID=$(echo "$APP_SEARCH" | jq -r --arg n "$APP_NAME" \
+    '.result[]? | select(.name == $n) | .oidcConfig.clientId // empty' | head -n1)
+fi
+if [[ -z "$CLIENT_ID" || "$CLIENT_ID" == "null" ]]; then
+  echo "ERROR: could not resolve OIDC client id"
+  exit 1
+fi
+echo "    client_id=$CLIENT_ID"
+
+create_machine_with_key() {
+  # Logs to stderr so only the user id is captured on stdout.
+  local username="$1" role="$2" key_out="$3"
+  local search uid key_resp key_json
+
+  search=$(api POST /management/v1/users/_search "$(jq -n --arg n "$username" \
+    '{queries: [{userNameQuery: {userName: $n, method: "TEXT_QUERY_METHOD_EQUALS"}}]}')")
+  uid=$(echo "$search" | jq -r '.result[0].id // empty')
+  if [[ -z "$uid" ]]; then
+    echo "==> Creating machine user $username" >&2
+    uid=$(api POST /management/v1/users/machine "$(jq -n --arg u "$username" \
+      '{userName: $u, name: $u, description: "GraphQL e2e", accessTokenType: "ACCESS_TOKEN_TYPE_JWT"}')" \
+      | jq -r '.userId // empty')
+  fi
+  if [[ -z "$uid" || "$uid" == "null" ]]; then
+    echo "ERROR: machine user $username" >&2
+    exit 1
+  fi
+  echo "    user id: $uid" >&2
+
+  # Grant project role (must succeed for E1 isolation claims)
+  echo "    granting project role $role" >&2
+  grant_body=$(jq -n --arg pid "$PROJECT_ID" --arg r "$role" \
+    '{projectId: $pid, roleKeys: [$r]}')
+  grants=$(api POST "/management/v1/users/grants/_search" "$(jq -n --arg uid "$uid" \
+    '{queries: [{userIdQuery: {userId: $uid}}]}')" 2>/dev/null || echo '{}')
+  existing_grant=$(echo "$grants" | jq -r --arg pid "$PROJECT_ID" \
+    '.result[]? | select(.projectId == $pid) | .id // empty' | head -n1)
+  if [[ -n "$existing_grant" ]]; then
+    # One-shot update (do not use api() retry — 404 is not a readiness race)
+    http=$(curl -sS -o /tmp/zitadel-grant.json -w '%{http_code}' -X PUT \
+      "$ZITADEL_HOST/management/v1/users/$uid/grants/$existing_grant" \
+      -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
+      -d "$(jq -n --arg r "$role" '{roleKeys: [$r]}')" || echo 000)
+    # 200/201 ok; 400 "has not been changed" means grant already has roleKeys
+    if [[ "$http" == "200" || "$http" == "201" ]]; then
+      echo "    updated grant $existing_grant → $role" >&2
+    elif [[ "$http" == "400" ]] && grep -q 'has not been changed' /tmp/zitadel-grant.json 2>/dev/null; then
+      echo "    grant $existing_grant already has role $role" >&2
+    else
+      echo "ERROR: update grant $existing_grant → $role failed HTTP $http" >&2
+      cat /tmp/zitadel-grant.json >&2 || true
+      exit 1
+    fi
+  else
+    grant_resp=$(api POST "/management/v1/users/$uid/grants" "$grant_body") || {
+      echo "ERROR: grant role $role to $uid failed" >&2
+      exit 1
+    }
+    echo "    grant created for role $role" >&2
+  fi
+
+  # Machine key (JSON type 1) for JWT-bearer
+  echo "    creating machine key → $key_out" >&2
+  key_resp=$(api POST "/management/v1/users/$uid/keys" \
+    "$(jq -n '{type: "KEY_TYPE_JSON", expirationDate: "2029-01-01T00:00:00Z"}')")
+
+  if echo "$key_resp" | jq -e '.keyId and .key' >/dev/null 2>&1; then
+    echo "$key_resp" | jq -c --arg uid "$uid" \
+      '{keyId: .keyId, key: .key, userId: $uid}' > "$key_out"
+  elif echo "$key_resp" | jq -e '.keyDetails' >/dev/null 2>&1; then
+    # keyDetails is often base64-encoded JSON machine key
+    key_json=$(echo "$key_resp" | jq -r '.keyDetails' | base64 -d 2>/dev/null || true)
+    if ! echo "$key_json" | jq -e '.keyId and .key' >/dev/null 2>&1; then
+      key_json=$(echo "$key_resp" | jq -r '.keyDetails')
+    fi
+    if echo "$key_json" | jq -e '.keyId and .key' >/dev/null 2>&1; then
+      echo "$key_json" | jq -c --arg uid "$uid" \
+        '. + {userId: (.userId // $uid)}' > "$key_out"
+    else
+      echo "ERROR: could not parse keyDetails for $username" >&2
+      echo "$key_resp" | jq . >&2 || echo "$key_resp" >&2
+      exit 1
+    fi
+  else
+    echo "ERROR: unexpected key response for $username" >&2
+    echo "$key_resp" | jq . >&2 || echo "$key_resp" >&2
+    exit 1
+  fi
+
+  if [[ ! -s "$key_out" ]]; then
+    echo "ERROR: empty key file $key_out" >&2
+    exit 1
+  fi
+  # stdout: user id only
+  printf '%s\n' "$uid"
+}
+
+mkdir -p "$MACHINEKEY_DIR/e2e"
+CUSTOMER_KEY="$MACHINEKEY_DIR/e2e/customer.json"
+ADMIN_KEY="$MACHINEKEY_DIR/e2e/admin.json"
+CUSTOMER_UID=$(create_machine_with_key "graphql-e2e-customer" "customer" "$CUSTOMER_KEY")
+ADMIN_UID=$(create_machine_with_key "graphql-e2e-admin" "admin" "$ADMIN_KEY")
+# Strip any accidental whitespace
+CUSTOMER_UID=$(echo "$CUSTOMER_UID" | tr -d '[:space:]')
+ADMIN_UID=$(echo "$ADMIN_UID" | tr -d '[:space:]')
+
+# Prove customer token carries project roles (E1 isolation depends on this)
+echo "==> Verify customer JWT-bearer token includes project roles claim"
+verify_roles() {
+  local keyfile="$1" uid="$2"
+  local kid key_pem now exp header payload sig jwt tok claims
+  kid=$(jq -r '.keyId // .key_id' "$keyfile")
+  key_pem=$(jq -r '.key' "$keyfile")
+  now=$(date +%s)
+  exp=$((now + 60))
+  header=$(printf '{"alg":"RS256","typ":"JWT","kid":"%s"}' "$kid" | b64url)
+  payload=$(printf '{"iss":"%s","sub":"%s","aud":["%s/oauth/v2/token","%s"],"iat":%s,"exp":%s}' \
+    "$uid" "$uid" "$ZITADEL_HOST" "$ZITADEL_HOST" "$now" "$exp" | b64url)
+  TMPV=$(mktemp)
+  printf '%s\n' "$key_pem" > "$TMPV"
+  sig=$(printf '%s' "${header}.${payload}" | openssl dgst -sha256 -sign "$TMPV" | b64url)
+  rm -f "$TMPV"
+  jwt="${header}.${payload}.${sig}"
+  tok=$(curl -sS -X POST "$ZITADEL_HOST/oauth/v2/token" \
+    -H 'Content-Type: application/x-www-form-urlencoded' \
+    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
+    --data-urlencode "scope=openid profile urn:zitadel:iam:org:project:id:${PROJECT_ID}:aud urn:zitadel:iam:org:project:roles urn:zitadel:iam:org:projects:roles" \
+    --data-urlencode "assertion=$jwt" | jq -r '.access_token // empty')
+  if [[ -z "$tok" ]]; then
+    echo "ERROR: could not mint verify token for $uid"
+    return 1
+  fi
+  claims=$(python3 -c "
+import json,base64,sys
+t=sys.argv[1].split('.')[1]
+t += '=' * (-len(t) % 4)
+print(json.dumps(json.loads(base64.urlsafe_b64decode(t))))
+" "$tok")
+  # Generic or project-scoped role object (either form is valid for claim map)
+  if ! echo "$claims" | jq -e '
+      (."urn:zitadel:iam:org:project:roles" | type == "object")
+      or ([to_entries[] | select(.key | test("^urn:zitadel:iam:org:project:[^:]+:roles$"))] | length > 0)
+    ' >/dev/null; then
+    echo "ERROR: access token missing Zitadel project roles claim (E1 isolation will fail)"
+    echo "$claims" | jq .
+    return 1
+  fi
+  echo "    roles claim present: $(echo "$claims" | jq -c '[to_entries[] | select(.key | contains("roles")) | {key, roles: (.value | keys)}]')"
+}
+verify_roles "$CUSTOMER_KEY" "$CUSTOMER_UID"
+verify_roles "$ADMIN_KEY" "$ADMIN_UID"
+
+# Zitadel JWT-bearer access tokens with project:id:{PROJECT}:aud put the
+# **project id** in `aud` (not the OIDC app client id). Validate against that.
+umask 077
+cat > "$OUT" <<EOF
+ZITADEL_E2E=1
+OIDC_ISSUER=$ZITADEL_HOST
+OIDC_AUDIENCE=$PROJECT_ID
+OIDC_CLIENT_ID=$CLIENT_ID
+ZITADEL_PROJECT_ID=$PROJECT_ID
+GRAPHQL_E2E_CUSTOMER_KEY=$CUSTOMER_KEY
+GRAPHQL_E2E_ADMIN_KEY=$ADMIN_KEY
+GRAPHQL_E2E_CUSTOMER_USER_ID=$CUSTOMER_UID
+GRAPHQL_E2E_ADMIN_USER_ID=$ADMIN_UID
+EOF
+echo "==> Wrote $OUT"
+cat "$OUT"
diff --git a/scripts/graphql-skill-dry-run.sh b/scripts/graphql-skill-dry-run.sh
new file mode 100755
index 00000000..8fbe43a2
--- /dev/null
+++ b/scripts/graphql-skill-dry-run.sh
@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Dry-run: agent following only README + distributed-graphql skill can
+# scaffold --query-api and add a model exposure. Captures evidence for
+# tasks/graphql-qs-13-docs-skills AC2.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SCRATCH="${GROK_SCRATCH:-${1:-}}"
+if [[ -z "$SCRATCH" ]]; then
+  echo "usage: GROK_SCRATCH=<dir> $0   OR   $0 <scratch-dir>" >&2
+  exit 2
+fi
+mkdir -p "$SCRATCH"
+LOG="$SCRATCH/skill-dry-run.log"
+exec > >(tee "$LOG") 2>&1
+
+echo "=== skill dry-run start $(date -u +%Y-%m-%dT%H:%M:%SZ) ==="
+echo "ROOT=$ROOT"
+echo "SCRATCH=$SCRATCH"
+
+# 1) Load only README + skill (existence + frontmatter — the agent would read these)
+test -f "$ROOT/README.md"
+test -f "$ROOT/docs/graphql.md"
+SKILL="$ROOT/distributed_cli/skills/distributed-graphql/SKILL.md"
+test -f "$SKILL"
+grep -q '^name: distributed-graphql' "$SKILL"
+grep -q 'src/query/' "$SKILL"
+grep -q 'with_graphql' "$SKILL"
+echo "OK: README + skill present and teach query layout"
+
+# 2) Build dctl
+cd "$ROOT"
+cargo build -p distributed_cli --quiet
+DCTL="$ROOT/target/debug/dctl"
+test -x "$DCTL"
+
+# 3) Scaffold --query-api (as skill documents)
+DEMO="$SCRATCH/skill-dry-run-service"
+rm -rf "$DEMO"
+"$DCTL" scaffold skill-dry-run \
+  --path "$DEMO" \
+  --query-api \
+  --store sqlite \
+  --model Order \
+  --distributed-path "$ROOT" \
+  --force
+echo "OK: scaffold --query-api wrote $DEMO"
+
+# 4) Pin distributed path to this crate (scratch dirs break relative paths)
+python3 -c "
+from pathlib import Path
+import re
+p = Path(r'''$DEMO/Cargo.toml''')
+t = p.read_text()
+root = Path(r'''$ROOT''').resolve().as_posix()
+t = re.sub(
+    r'distributed = \{ path = \"[^\"]+\"',
+    'distributed = { path = \"' + root + '\"',
+    t,
+    count=1,
+)
+p.write_text(t)
+print('fixed distributed path ->', root)
+"
+
+# 5) Agent exercise: model exposure files exist; annotate following skill
+test -f "$DEMO/src/query/order.rs"
+test -f "$DEMO/src/query/roles.rs"
+grep -q 'pub const USER' "$DEMO/src/query/roles.rs"
+grep -q 'fn permissions' "$DEMO/src/query/order.rs"
+echo '// skill dry-run: role USER granted via grant_all in mod.rs; tighten in permissions()' >> "$DEMO/src/query/order.rs"
+echo "OK: model exposure files present (order + roles)"
+
+# 6) cargo check (must compile against real distributed)
+cd "$DEMO"
+cargo check
+echo "OK: cargo check exit=$?"
+
+echo "=== skill dry-run SUCCESS ==="
diff --git a/scripts/oidc-authentik-up.sh b/scripts/oidc-authentik-up.sh
new file mode 100755
index 00000000..2cd55db8
--- /dev/null
+++ b/scripts/oidc-authentik-up.sh
@@ -0,0 +1,343 @@
+#!/usr/bin/env bash
+# Start Authentik + bootstrap two M2M OAuth2 clients for GraphQL e2e (local + CI).
+# Pattern: compose up → wait healthy → docker exec bootstrap → write env.
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+COMPOSE="$ROOT/tests/graphql_oidc_authentik/docker-compose.yml"
+OUT="${GRAPHQL_OIDC_AUTHENTIK_ENV:-$ROOT/graphql-oidc-authentik.env}"
+BASE="${AUTHENTIK_URL:-http://localhost:9000}"
+AK_EMAIL="${AUTHENTIK_BOOTSTRAP_EMAIL:-akadmin@localhost}"
+AK_PASS="${AUTHENTIK_BOOTSTRAP_PASSWORD:-akadmin-e2e-pass}"
+
+export COMPOSE AUTHENTIK_URL="$BASE" AUTHENTIK_BOOTSTRAP_EMAIL="$AK_EMAIL" \
+  AUTHENTIK_BOOTSTRAP_PASSWORD="$AK_PASS" GRAPHQL_OIDC_AUTHENTIK_ENV="$OUT"
+
+cd "$ROOT"
+echo "==> docker compose up Authentik"
+docker compose -f "$COMPOSE" up -d --remove-orphans
+
+echo "==> Wait for Authentik live at $BASE"
+for i in $(seq 1 120); do
+  if curl -fsS "$BASE/-/health/live/" >/dev/null 2>&1 \
+    || curl -fsS "$BASE/api/v3/root/" >/dev/null 2>&1; then
+    echo "    live (${i}*3s)"
+    break
+  fi
+  sleep 3
+  if [[ $i -eq 120 ]]; then
+    echo "ERROR: Authentik never ready"
+    docker compose -f "$COMPOSE" logs --tail=120 server worker || true
+    exit 1
+  fi
+done
+
+# Migrations / bootstrap user settle
+echo "==> Wait for worker + bootstrap user"
+sleep 15
+for i in $(seq 1 40); do
+  if docker compose -f "$COMPOSE" exec -T worker ak version >/dev/null 2>&1; then
+    echo "    worker ak ready (${i})"
+    break
+  fi
+  sleep 3
+  if [[ $i -eq 40 ]]; then
+    echo "ERROR: worker never ready for ak"
+    docker compose -f "$COMPOSE" logs --tail=80 worker || true
+    exit 1
+  fi
+done
+
+echo "==> Bootstrap OAuth2 M2M clients via ak shell"
+# Create API token + two confidential OAuth2 providers/apps with client_credentials.
+# Prints KEY=value lines on stdout for the outer shell to capture.
+BOOT_OUT=$(docker compose -f "$COMPOSE" exec -T worker ak shell -c '
+from authentik.core.models import Token, TokenIntents, User, Application, Group
+from authentik.providers.oauth2.models import (
+    OAuth2Provider, ClientTypes, SubModes, IssuerMode, ScopeMapping,
+)
+from authentik.crypto.models import CertificateKeyPair
+from authentik.flows.models import Flow
+from django.db import transaction
+
+u = User.objects.filter(username="akadmin").first()
+if u is None:
+    u = User.objects.filter(is_superuser=True).first()
+assert u is not None, "no admin user yet"
+
+tok, _ = Token.objects.update_or_create(
+    identifier="graphql-e2e-api",
+    defaults={"user": u, "intent": TokenIntents.INTENT_API, "expiring": False},
+)
+
+auth_flow = Flow.objects.filter(slug="default-provider-authorization-implicit-consent").first()
+if auth_flow is None:
+    auth_flow = Flow.objects.filter(designation="authorization").first()
+assert auth_flow is not None, "no authorization flow"
+
+invalidation = Flow.objects.filter(slug="default-provider-invalidation-flow").first()
+if invalidation is None:
+    invalidation = Flow.objects.filter(designation="invalidation").first()
+
+# RS256 signing key required for JWKS-based validation (not HS256 client secret)
+signing = CertificateKeyPair.objects.filter(name__icontains="JWT").first()
+if signing is None:
+    signing = CertificateKeyPair.objects.filter(key_data__isnull=False).exclude(key_data="").first()
+assert signing is not None, "no CertificateKeyPair for JWT signing"
+
+# GLOBAL issuer so customer + admin tokens share one OIDC_ISSUER for e2e
+base_scopes = list(ScopeMapping.objects.filter(scope_name__in=["openid", "profile", "email"]))
+if not base_scopes:
+    base_scopes = list(ScopeMapping.objects.all()[:5])
+
+# Groups for E1 isolation: static ScopeMapping injects groups claim on token
+# (client_credentials has no interactive user; expression returns engine role names).
+def groups_scope(name: str, roles: list):
+    expr = "return " + repr(roles)
+    m, _ = ScopeMapping.objects.update_or_create(
+        name=name,
+        defaults={
+            "scope_name": "groups",
+            "expression": expr,
+            "description": f"GraphQL e2e groups {roles}",
+        },
+    )
+    return m
+
+# Real Group objects (for documentation / future user assignment)
+g_customer, _ = Group.objects.get_or_create(name="customer")
+g_admin, _ = Group.objects.get_or_create(name="admin")
+
+def ensure_m2m(name: str, client_id: str, roles: list):
+    with transaction.atomic():
+        defaults = {
+            "authorization_flow": auth_flow,
+            "client_type": ClientTypes.CONFIDENTIAL,
+            "client_id": client_id,
+            "include_claims_in_id_token": True,
+            "sub_mode": SubModes.USER_ID,
+            "issuer_mode": IssuerMode.GLOBAL,
+            "signing_key": signing,
+        }
+        if invalidation is not None:
+            defaults["invalidation_flow"] = invalidation
+        provider, _created = OAuth2Provider.objects.update_or_create(
+            name=f"{name}-provider",
+            defaults=defaults,
+        )
+        mappings = list(base_scopes) + [groups_scope(f"{name}-groups", roles)]
+        provider.property_mappings.set(mappings)
+        Application.objects.update_or_create(
+            slug=name,
+            defaults={
+                "name": name,
+                "provider": provider,
+                "meta_launch_url": "blank://blank",
+            },
+        )
+        return provider
+
+cust = ensure_m2m("graphql-e2e-customer", "graphql-e2e-customer", ["customer"])
+adm = ensure_m2m("graphql-e2e-admin", "graphql-e2e-admin", ["admin"])
+
+cust.refresh_from_db()
+adm.refresh_from_db()
+
+print(f"CUSTOMER_CLIENT_ID={cust.client_id}")
+print(f"CUSTOMER_CLIENT_SECRET={cust.client_secret}")
+print(f"ADMIN_CLIENT_ID={adm.client_id}")
+print(f"ADMIN_CLIENT_SECRET={adm.client_secret}")
+print(f"API_TOKEN={tok.key}")
+' 2>/tmp/authentik-bootstrap.err) || {
+  echo "ERROR: ak shell bootstrap failed"
+  cat /tmp/authentik-bootstrap.err || true
+  echo "$BOOT_OUT"
+  exit 1
+}
+
+# Merge stderr progress with any useful errors when parsing fails
+echo "$BOOT_OUT" | grep -E '^[A-Z_]+=' >/tmp/authentik-boot.env || {
+  echo "ERROR: bootstrap did not emit KEY=value lines"
+  echo "$BOOT_OUT"
+  cat /tmp/authentik-bootstrap.err || true
+  exit 1
+}
+
+# shellcheck disable=SC1091
+source /tmp/authentik-boot.env
+
+# GLOBAL issuer mode → discovery at origin; application slug path still works for apps.
+ISSUER="${BASE}/"
+TOKEN_URL="${BASE}/application/o/token/"
+
+# Wait for discovery (global issuer)
+echo "==> Wait for OIDC discovery at $ISSUER"
+for i in $(seq 1 60); do
+  if curl -fsS "${ISSUER}.well-known/openid-configuration" >/dev/null 2>&1 \
+    || curl -fsS "${BASE}/application/o/graphql-e2e-customer/.well-known/openid-configuration" >/dev/null 2>&1; then
+    # Prefer issuer advertised by application discovery when global not exposed
+    if ! curl -fsS "${ISSUER}.well-known/openid-configuration" >/dev/null 2>&1; then
+      ISSUER="${BASE}/application/o/graphql-e2e-customer/"
+    fi
+    echo "    discovery ready at $ISSUER (${i}s)"
+    break
+  fi
+  sleep 2
+  if [[ $i -eq 60 ]]; then
+    echo "ERROR: discovery never ready"
+    docker compose -f "$COMPOSE" logs --tail=80 server || true
+    exit 1
+  fi
+done
+
+# Wait until client_credentials mints tokens for BOTH clients (creates ak-*-client_credentials users)
+echo "==> Wait for client_credentials mint (customer + admin)"
+for label_id_sec in \
+  "customer:${CUSTOMER_CLIENT_ID}:${CUSTOMER_CLIENT_SECRET}" \
+  "admin:${ADMIN_CLIENT_ID}:${ADMIN_CLIENT_SECRET}"; do
+  label="${label_id_sec%%:*}"
+  rest="${label_id_sec#*:}"
+  cid="${rest%%:*}"
+  sec="${rest#*:}"
+  for i in $(seq 1 60); do
+    code=$(curl -sS -o /tmp/ak-token.json -w '%{http_code}' -X POST "$TOKEN_URL" \
+      -d "grant_type=client_credentials" \
+      -d "client_id=${cid}" \
+      -d "client_secret=${sec}" \
+      -d "scope=openid groups profile" || echo 000)
+    if [[ "$code" == "200" ]]; then
+      echo "    $label mint ready (${i}s)"
+      break
+    fi
+    sleep 2
+    if [[ $i -eq 60 ]]; then
+      echo "ERROR: client_credentials still failing for $label (HTTP $code)"
+      cat /tmp/ak-token.json 2>/dev/null || true
+      exit 1
+    fi
+  done
+done
+
+# Assign engine roles: Authentik creates ak-*-client_credentials users on first mint;
+# groups claim is sourced from user.ak_groups (static ScopeMapping alone is insufficient).
+echo "==> Assign customer/admin groups to M2M service users"
+docker compose -f "$COMPOSE" exec -T worker ak shell -c '
+from authentik.core.models import User, Group
+g_c, _ = Group.objects.get_or_create(name="customer")
+g_a, _ = Group.objects.get_or_create(name="admin")
+assigned = []
+for u in User.objects.filter(username__icontains="client_credentials"):
+    un = u.username.lower()
+    if "customer" in un:
+        u.ak_groups.set([g_c])
+        assigned.append((un, "customer"))
+    elif "admin" in un:
+        u.ak_groups.set([g_a])
+        assigned.append((un, "admin"))
+# also mint-created name pattern
+for u in User.objects.filter(name__icontains="client credentials"):
+    n = (u.name or "").lower() + " " + (u.username or "").lower()
+    if "customer" in n and not any(a[0]==u.username for a in assigned):
+        u.ak_groups.set([g_c]); assigned.append((u.username, "customer"))
+    if "admin" in n and "customer" not in n and not any(a[0]==u.username for a in assigned):
+        u.ak_groups.set([g_a]); assigned.append((u.username, "admin"))
+print("ASSIGNED", assigned)
+assert any(r=="customer" for _,r in assigned), "no customer M2M user found for group assignment"
+assert any(r=="admin" for _,r in assigned), "no admin M2M user found for group assignment"
+' 2>/tmp/authentik-groups.err || {
+  echo "ERROR: group assignment failed"
+  cat /tmp/authentik-groups.err || true
+  exit 1
+}
+
+# Re-mint and require non-empty groups claim
+echo "==> Verify groups claim on access tokens"
+for pair in "customer:${CUSTOMER_CLIENT_ID}:${CUSTOMER_CLIENT_SECRET}" "admin:${ADMIN_CLIENT_ID}:${ADMIN_CLIENT_SECRET}"; do
+  label="${pair%%:*}"
+  rest="${pair#*:}"
+  cid="${rest%%:*}"
+  sec="${rest#*:}"
+  code=$(curl -sS -o /tmp/ak-token-verify.json -w '%{http_code}' -X POST "$TOKEN_URL" \
+    -d "grant_type=client_credentials" \
+    -d "client_id=${cid}" \
+    -d "client_secret=${sec}" \
+    -d "scope=openid groups profile" || echo 000)
+  if [[ "$code" != "200" ]]; then
+    echo "ERROR: remint $label failed HTTP $code"
+    cat /tmp/ak-token-verify.json || true
+    exit 1
+  fi
+  groups=$(python3 - <<PY
+import json,base64
+tok=json.load(open("/tmp/ak-token-verify.json"))["access_token"]
+p=tok.split(".")[1]
+p += "=" * (-len(p) % 4)
+c=json.loads(base64.urlsafe_b64decode(p))
+print(c.get("groups"))
+PY
+)
+  echo "    $label groups=$groups"
+  if [[ "$groups" == "None" || "$groups" == "[]" || -z "$groups" ]]; then
+    echo "ERROR: $label token missing groups claim (got $groups)"
+    exit 1
+  fi
+done
+
+# Derive issuer + audience from **customer** token (primary OIDC_AUDIENCE for E1 isolation)
+curl -sS -o /tmp/ak-token.json -X POST "$TOKEN_URL" \
+  -d "grant_type=client_credentials" \
+  -d "client_id=${CUSTOMER_CLIENT_ID}" \
+  -d "client_secret=${CUSTOMER_CLIENT_SECRET}" \
+  -d "scope=openid groups profile" >/dev/null
+eval "$(python3 - <<PY
+import json,base64,shlex
+tok=json.load(open("/tmp/ak-token.json"))["access_token"]
+payload=tok.split(".")[1]
+payload += "=" * (-len(payload) % 4)
+claims=json.loads(base64.urlsafe_b64decode(payload))
+print("claims", {k: claims.get(k) for k in ("aud","azp","client_id","sub","iss","groups")}, file=__import__("sys").stderr)
+hdr=json.loads(base64.urlsafe_b64decode(tok.split(".")[0] + "=" * (-len(tok.split(".")[0]) % 4)))
+print("header", hdr, file=__import__("sys").stderr)
+if hdr.get("alg","").startswith("HS"):
+    raise SystemExit("token still HS* — signing_key not applied")
+if not claims.get("groups"):
+    raise SystemExit("customer token missing groups after assignment")
+aud=claims.get("aud")
+azp=claims.get("azp")
+if isinstance(aud, list):
+  aud = aud[0] if aud else (azp or "${CUSTOMER_CLIENT_ID}")
+elif not aud:
+  aud = azp or "${CUSTOMER_CLIENT_ID}"
+iss = claims.get("iss") or "${ISSUER}"
+print(f"AUD={shlex.quote(str(aud))}")
+print(f"ISSUER_RAW={shlex.quote(str(iss))}")
+PY
+)"
+# Prefer exact iss claim from token
+ISSUER="${ISSUER_RAW:-$ISSUER}"
+
+# JWKS lives on application path even when iss is GLOBAL (origin)
+JWKS_URI="${BASE}/application/o/graphql-e2e-customer/jwks/"
+if ! curl -fsS "$JWKS_URI" >/dev/null 2>&1; then
+  JWKS_URI=$(python3 - <<PY
+import json,urllib.request
+d=json.load(urllib.request.urlopen("${BASE}/application/o/graphql-e2e-customer/.well-known/openid-configuration"))
+print(d["jwks_uri"])
+PY
+)
+fi
+
+cat > "$OUT" <<EOF
+AUTHENTIK_E2E=1
+OIDC_ISSUER=$ISSUER
+OIDC_AUDIENCE=$AUD
+OIDC_JWKS_URI=$JWKS_URI
+AUTHENTIK_TOKEN_URL=$TOKEN_URL
+AUTHENTIK_E2E_CUSTOMER_CLIENT_ID=$CUSTOMER_CLIENT_ID
+AUTHENTIK_E2E_CUSTOMER_CLIENT_SECRET=$CUSTOMER_CLIENT_SECRET
+AUTHENTIK_E2E_ADMIN_CLIENT_ID=$ADMIN_CLIENT_ID
+AUTHENTIK_E2E_ADMIN_CLIENT_SECRET=$ADMIN_CLIENT_SECRET
+EOF
+
+echo "==> Wrote $OUT"
+cat "$OUT"
+echo "==> Done. source $OUT && cargo test --test graphql_oidc_authentik --features graphql,sqlite,metrics"
diff --git a/scripts/oidc-keycloak-up.sh b/scripts/oidc-keycloak-up.sh
new file mode 100755
index 00000000..ece8a689
--- /dev/null
+++ b/scripts/oidc-keycloak-up.sh
@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# Start Keycloak + write graphql-oidc-keycloak.env for e2e (local + CI).
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+COMPOSE="$ROOT/tests/graphql_oidc_keycloak/docker-compose.yml"
+OUT="${GRAPHQL_OIDC_KEYCLOAK_ENV:-$ROOT/graphql-oidc-keycloak.env}"
+ISSUER_HOST="${KEYCLOAK_ISSUER:-http://localhost:8081}"
+REALM=graphql
+ISSUER="${ISSUER_HOST}/realms/${REALM}"
+
+cd "$ROOT"
+echo "==> docker compose up Keycloak"
+docker compose -f "$COMPOSE" up -d --remove-orphans
+
+echo "==> Wait for OIDC discovery at $ISSUER"
+for i in $(seq 1 90); do
+  if curl -fsS "${ISSUER}/.well-known/openid-configuration" >/dev/null 2>&1; then
+    echo "    discovery ready (${i}s)"
+    break
+  fi
+  if ! docker compose -f "$COMPOSE" ps --status running --services 2>/dev/null | grep -q keycloak; then
+    echo "ERROR: keycloak not running"
+    docker compose -f "$COMPOSE" logs --tail=80 || true
+    exit 1
+  fi
+  sleep 2
+  if [[ $i -eq 90 ]]; then
+    echo "ERROR: Keycloak discovery never ready"
+    docker compose -f "$COMPOSE" logs --tail=100 || true
+    exit 1
+  fi
+done
+
+# Wait until client_credentials succeeds (realm import may lag discovery)
+echo "==> Wait for client_credentials mint"
+TOKEN_URL="${ISSUER}/protocol/openid-connect/token"
+for i in $(seq 1 60); do
+  code=$(curl -sS -o /tmp/kc-token.json -w '%{http_code}' -X POST "$TOKEN_URL" \
+    -d "grant_type=client_credentials" \
+    -d "client_id=graphql-e2e-customer" \
+    -d "client_secret=customer-secret-e2e" || echo 000)
+  if [[ "$code" == "200" ]]; then
+    echo "    mint ready (${i}s)"
+    break
+  fi
+  sleep 2
+  if [[ $i -eq 60 ]]; then
+    echo "ERROR: client_credentials still failing (HTTP $code)"
+    cat /tmp/kc-token.json 2>/dev/null || true
+    exit 1
+  fi
+done
+
+# Capture audience from access token (Keycloak often uses client_id or "account")
+AUD=$(python3 - <<PY
+import json,base64,urllib.request,urllib.parse
+url="${TOKEN_URL}"
+data=urllib.parse.urlencode({
+  "grant_type":"client_credentials",
+  "client_id":"graphql-e2e-customer",
+  "client_secret":"customer-secret-e2e",
+}).encode()
+req=urllib.request.Request(url,data=data,headers={"Content-Type":"application/x-www-form-urlencoded"})
+tok=json.load(urllib.request.urlopen(req))["access_token"]
+payload=tok.split(".")[1]
+payload += "=" * (-len(payload) % 4)
+claims=json.loads(base64.urlsafe_b64decode(payload))
+print("claims keys", sorted(claims.keys()), file=__import__("sys").stderr)
+print("aud", claims.get("aud"), "azp", claims.get("azp"), file=__import__("sys").stderr)
+aud=claims.get("aud")
+azp=claims.get("azp")
+# Prefer azp (authorized party / client id) when aud is account or list
+if isinstance(aud, list):
+  if azp:
+    print(azp)
+  else:
+    print(aud[0] if aud else "account")
+elif aud and aud != "account":
+  print(aud)
+elif azp:
+  print(azp)
+else:
+  print(aud or "graphql-e2e-customer")
+PY
+)
+
+cat > "$OUT" <<EOF
+KEYCLOAK_E2E=1
+OIDC_ISSUER=$ISSUER
+OIDC_AUDIENCE=$AUD
+OIDC_CLIENT_ID=graphql-e2e-customer
+KEYCLOAK_E2E_CUSTOMER_CLIENT_ID=graphql-e2e-customer
+KEYCLOAK_E2E_CUSTOMER_CLIENT_SECRET=customer-secret-e2e
+KEYCLOAK_E2E_ADMIN_CLIENT_ID=graphql-e2e-admin
+KEYCLOAK_E2E_ADMIN_CLIENT_SECRET=admin-secret-e2e
+EOF
+echo "==> Wrote $OUT"
+cat "$OUT"
+echo "==> Done. source $OUT && cargo test --test graphql_oidc_keycloak --features graphql,sqlite,metrics"
diff --git a/scripts/oidc-zitadel-up.sh b/scripts/oidc-zitadel-up.sh
new file mode 100755
index 00000000..fbe3abf1
--- /dev/null
+++ b/scripts/oidc-zitadel-up.sh
@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Start Zitadel compose for GraphQL OIDC e2e and bootstrap env (local + CI).
+#
+# Pattern for other IdP adapters (Keycloak/Authentik):
+#   1) Ensure writable dirs/volumes for IdP-generated secrets
+#   2) docker compose up -d --wait (or health probe)
+#   3) Run provider bootstrap → export GATE + OIDC_* + mint credentials
+#   4) cargo test --test graphql_oidc_<provider> with GATE=1
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+COMPOSE_FILE="$ROOT/tests/graphql_oidc_zitadel/docker-compose.yml"
+MACHINEKEY_DIR="$ROOT/tests/graphql_oidc_zitadel/machinekey"
+ZITADEL_HOST="${ZITADEL_HOST:-http://localhost:8080}"
+
+cd "$ROOT"
+
+echo "==> Prepare machinekey dir (writable by container — FirstInstance key)"
+# Zitadel runs as non-root by default; bind mounts on GHA are owned by runner
+# and get "permission denied" writing zitadel-admin-sa.json unless world-writable
+# (or the service runs as root — we do both for reliability).
+mkdir -p "$MACHINEKEY_DIR"
+chmod 777 "$MACHINEKEY_DIR"
+# Preserve FirstInstance admin SA key if present (Zitadel only writes it on first
+# init). Wipe only e2e keys so re-bootstrap can recreate machine keys safely.
+# Full reset: `docker compose -f ... down -v` then re-run this script.
+rm -rf "$MACHINEKEY_DIR/e2e"
+mkdir -p "$MACHINEKEY_DIR/e2e"
+chmod 777 "$MACHINEKEY_DIR" "$MACHINEKEY_DIR/e2e"
+
+echo "==> docker compose up"
+docker compose -f "$COMPOSE_FILE" up -d --remove-orphans
+
+echo "==> Wait for Zitadel process (/debug/ready is early; bootstrap waits for management)"
+for i in $(seq 1 90); do
+  # Prefer healthz (documented on Zitadel banner); fall back to ready.
+  if curl -fsS "$ZITADEL_HOST/debug/healthz" >/dev/null 2>&1 \
+    || curl -fsS "$ZITADEL_HOST/debug/ready" >/dev/null 2>&1; then
+    echo "    probe ok (${i}s) — management readiness is enforced in bootstrap"
+    break
+  fi
+  # Surface early container death (e.g. permission denied on machinekey)
+  if ! docker compose -f "$COMPOSE_FILE" ps --status running --services 2>/dev/null | grep -q '^zitadel$'; then
+    echo "ERROR: zitadel container not running"
+    docker compose -f "$COMPOSE_FILE" ps -a || true
+    docker compose -f "$COMPOSE_FILE" logs --tail=80 zitadel || true
+    exit 1
+  fi
+  sleep 2
+  if [[ $i -eq 90 ]]; then
+    echo "ERROR: Zitadel never became reachable"
+    docker compose -f "$COMPOSE_FILE" logs --tail=120 || true
+    exit 1
+  fi
+done
+
+echo "==> Wait for FirstInstance machine key"
+for i in $(seq 1 60); do
+  shopt -s nullglob
+  keys=("$MACHINEKEY_DIR"/*.json)
+  shopt -u nullglob
+  if [[ ${#keys[@]} -gt 0 && -s "${keys[0]}" ]]; then
+    echo "    found ${keys[0]}"
+    break
+  fi
+  sleep 2
+  if [[ $i -eq 60 ]]; then
+    # DB already initialized but host key was deleted → force FirstInstance rewrite
+    echo "    no admin SA key on host; recreating stack (down -v) so FirstInstance re-emits key"
+    docker compose -f "$COMPOSE_FILE" down -v || true
+    mkdir -p "$MACHINEKEY_DIR/e2e"
+    chmod 777 "$MACHINEKEY_DIR" "$MACHINEKEY_DIR/e2e"
+    docker compose -f "$COMPOSE_FILE" up -d --remove-orphans
+    for j in $(seq 1 90); do
+      shopt -s nullglob
+      keys=("$MACHINEKEY_DIR"/*.json)
+      shopt -u nullglob
+      if [[ ${#keys[@]} -gt 0 && -s "${keys[0]}" ]]; then
+        echo "    found ${keys[0]} after recreate"
+        break 2
+      fi
+      if curl -fsS "$ZITADEL_HOST/debug/ready" >/dev/null 2>&1; then
+        : # still waiting for key file
+      fi
+      sleep 2
+      if [[ $j -eq 90 ]]; then
+        echo "ERROR: no machine key in $MACHINEKEY_DIR after recreate"
+        ls -la "$MACHINEKEY_DIR" || true
+        docker compose -f "$COMPOSE_FILE" logs --tail=80 zitadel || true
+        exit 1
+      fi
+    done
+  fi
+done
+
+echo "==> Bootstrap OIDC app + e2e users (retries management API until not 503)"
+chmod +x "$ROOT/scripts/ci-bootstrap-graphql-oidc.sh"
+"$ROOT/scripts/ci-bootstrap-graphql-oidc.sh"
+
+echo "==> Done. Source env and run tests:"
+echo "    set -a && source $ROOT/graphql-oidc.env && set +a"
+echo "    cargo test --test graphql_oidc_zitadel --features graphql,sqlite,metrics"
diff --git a/scripts/setup-graphql-oidc-zitadel.sh b/scripts/setup-graphql-oidc-zitadel.sh
new file mode 100755
index 00000000..967d56a0
--- /dev/null
+++ b/scripts/setup-graphql-oidc-zitadel.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Local helper: start compose + bootstrap env for GraphQL OIDC e2e.
+# Delegates to oidc-zitadel-up.sh (machinekey perms + wait + bootstrap).
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+exec "$ROOT/scripts/oidc-zitadel-up.sh"
\ No newline at end of file
diff --git a/src/bus/error.rs b/src/bus/error.rs
index 008388d1..795ae9b6 100644
--- a/src/bus/error.rs
+++ b/src/bus/error.rs
@@ -46,6 +46,7 @@ pub struct TransportError {
     kind: TransportErrorKind,
     message: String,
     source: Option<Box<dyn Error + Send + Sync>>,
+    retain_and_stop: bool,
 }
 
 impl TransportError {
@@ -55,6 +56,7 @@ impl TransportError {
             kind: TransportErrorKind::Retryable,
             message: message.into(),
             source: None,
+            retain_and_stop: false,
         }
     }
 
@@ -64,6 +66,7 @@ impl TransportError {
             kind: TransportErrorKind::Permanent,
             message: message.into(),
             source: None,
+            retain_and_stop: false,
         }
     }
 
@@ -73,6 +76,7 @@ impl TransportError {
             kind,
             message: message.into(),
             source: None,
+            retain_and_stop: false,
         }
     }
 
@@ -82,6 +86,17 @@ impl TransportError {
         self
     }
 
+    /// Mark a durably recorded terminal delivery that must remain at its exact
+    /// source position while the consumer stops for operator repair.
+    pub(crate) fn retain_and_stop(mut self) -> Self {
+        self.retain_and_stop = true;
+        self
+    }
+
+    pub(crate) fn should_retain_and_stop(&self) -> bool {
+        self.retain_and_stop
+    }
+
     /// The retry classification of this error.
     pub fn kind(&self) -> TransportErrorKind {
         self.kind
diff --git a/src/bus/in_memory_bus.rs b/src/bus/in_memory_bus.rs
index 4e476255..2a76f974 100644
--- a/src/bus/in_memory_bus.rs
+++ b/src/bus/in_memory_bus.rs
@@ -14,11 +14,13 @@ use std::collections::{HashMap, VecDeque};
 use std::sync::{Arc, Mutex};
 
 use super::source::{MessageSource, ReceivedMessage};
-use super::Message;
 use super::{run_source, Bus, BusConsumer, MessageRouter, RunOptions, TransportError};
+use super::{Message, OrderedDelivery};
+use crate::projection_protocol::{ProjectionEpoch, ProjectionSource};
 
 type Queues = Arc<Mutex<HashMap<String, VecDeque<Message>>>>;
 type Topics = Arc<Mutex<HashMap<String, Vec<Message>>>>;
+type TopicCursors = Arc<Mutex<HashMap<String, usize>>>;
 
 fn lock_poisoned(what: &str) -> TransportError {
     TransportError::permanent(format!("in-memory bus {what} lock poisoned"))
@@ -28,10 +30,22 @@ fn lock_poisoned(what: &str) -> TransportError {
 ///
 /// Cheap to clone (shares the same queues/logs), so competing listeners and
 /// fan-out subscribers can each hold a clone.
-#[derive(Clone, Default)]
+#[derive(Clone)]
 pub struct InMemoryBus {
     queues: Queues,
     topics: Topics,
+    source_epoch: ProjectionEpoch,
+}
+
+impl Default for InMemoryBus {
+    fn default() -> Self {
+        Self {
+            queues: Queues::default(),
+            topics: Topics::default(),
+            source_epoch: ProjectionEpoch::new(format!("instance-{}", uuid::Uuid::now_v7()))
+                .expect("an in-memory bus UUID is a valid projection source epoch"),
+        }
+    }
 }
 
 impl InMemoryBus {
@@ -50,14 +64,58 @@ impl InMemoryBus {
     }
 
     fn append(&self, message: Message) -> Result<(), TransportError> {
-        self.topics
-            .lock()
-            .map_err(|_| lock_poisoned("topic"))?
+        let mut topics = self.topics.lock().map_err(|_| lock_poisoned("topic"))?;
+        if let Some(id) = message.id() {
+            if let Some(existing) = topics
+                .values()
+                .flat_map(|log| log.iter())
+                .find(|existing| existing.id() == Some(id))
+            {
+                validate_topic_retry(existing, &message)?;
+                return Ok(());
+            }
+        }
+        topics
             .entry(message.name().to_string())
             .or_default()
             .push(message);
         Ok(())
     }
+
+    #[cfg(test)]
+    pub(crate) fn ordered_topic_evidence(&self, name: &str, position: u64) -> OrderedDelivery {
+        OrderedDelivery::new(
+            ProjectionSource::new("in_memory.topic", name.as_bytes().to_vec())
+                .expect("an in-memory topic name is a valid projection source partition"),
+            self.source_epoch.clone(),
+            position,
+            true,
+        )
+        .expect("an in-memory topic position is valid ordered-delivery evidence")
+    }
+}
+
+/// Verify that an ambiguous publish retry using an existing stable ID is the
+/// exact causal envelope already retained in the ordered topic log.
+///
+/// Trace metadata can legitimately change when the producer retries after an
+/// unknown acknowledgement, so it is excluded. Causation is included because
+/// it is part of the projector's canonical input identity.
+fn validate_topic_retry(existing: &Message, retry: &Message) -> Result<(), TransportError> {
+    let matches = existing.name == retry.name
+        && existing.kind == retry.kind
+        && existing.payload == retry.payload
+        && existing.content_type == retry.content_type
+        && existing.causation_id() == retry.causation_id();
+    if matches {
+        return Ok(());
+    }
+
+    Err(TransportError::permanent(format!(
+        "in-memory bus ordered-topic message ID {:?} was reused with a different \
+         name, kind, payload, content type, or causation ID",
+        retry.id()
+    )))
 }
 
 impl Bus for InMemoryBus {
@@ -93,7 +151,8 @@ impl BusConsumer for InMemoryBus {
         let source = TopicSource {
             topics: self.topics.clone(),
             names,
-            cursors: HashMap::new(),
+            cursors: TopicCursors::default(),
+            source_epoch: self.source_epoch.clone(),
         };
         run_source(router, source, options).await
     }
@@ -116,7 +175,11 @@ impl MessageSource for QueueSource {
         let mut queues = self.queues.lock().map_err(|_| lock_poisoned("queue"))?;
         for name in &self.names {
             if let Some(message) = queues.get_mut(name).and_then(VecDeque::pop_front) {
-                return Ok(Some(InMemoryReceived { message }));
+                return Ok(Some(InMemoryReceived {
+                    message,
+                    ordered: None,
+                    topic_settlement: None,
+                }));
             }
         }
         Ok(None)
@@ -128,7 +191,8 @@ impl MessageSource for QueueSource {
 struct TopicSource {
     topics: Topics,
     names: Vec<String>,
-    cursors: HashMap<String, usize>,
+    cursors: TopicCursors,
+    source_epoch: ProjectionEpoch,
 }
 
 impl MessageSource for TopicSource {
@@ -140,33 +204,91 @@ impl MessageSource for TopicSource {
 
     async fn recv(&mut self) -> Result<Option<Self::Received>, TransportError> {
         let topics = self.topics.lock().map_err(|_| lock_poisoned("topic"))?;
+        let mut cursors = self
+            .cursors
+            .lock()
+            .map_err(|_| lock_poisoned("topic cursor"))?;
         for name in &self.names {
             let Some(log) = topics.get(name) else {
                 continue;
             };
-            let cursor = self.cursors.entry(name.clone()).or_insert(0);
+            let cursor = cursors.entry(name.clone()).or_insert(0);
             if *cursor < log.len() {
                 let message = log[*cursor].clone();
-                *cursor += 1;
-                return Ok(Some(InMemoryReceived { message }));
+                let position = u64::try_from(*cursor).map_err(|_| {
+                    TransportError::permanent(
+                        "in-memory topic position cannot fit the projection cursor domain",
+                    )
+                })?;
+                let source = ProjectionSource::new("in_memory.topic", name.as_bytes().to_vec())
+                    .map_err(|error| TransportError::permanent(error.to_string()))?;
+                let ordered =
+                    OrderedDelivery::new(source, self.source_epoch.clone(), position, true)
+                        .map_err(|error| TransportError::permanent(error.to_string()))?;
+                return Ok(Some(InMemoryReceived {
+                    message,
+                    ordered: Some(ordered),
+                    topic_settlement: Some(TopicSettlement {
+                        cursors: Arc::clone(&self.cursors),
+                        name: name.clone(),
+                        position: *cursor,
+                    }),
+                }));
             }
         }
         Ok(None)
     }
 }
 
-/// In-memory delivery. Settling is a no-op: queue pops and log cursors already
-/// advanced on `recv`, and the in-memory bus does not redeliver.
+struct TopicSettlement {
+    cursors: TopicCursors,
+    name: String,
+    position: usize,
+}
+
+impl TopicSettlement {
+    fn ack(self) -> Result<(), TransportError> {
+        let mut cursors = self
+            .cursors
+            .lock()
+            .map_err(|_| lock_poisoned("topic cursor"))?;
+        let cursor = cursors.entry(self.name).or_insert(0);
+        match (*cursor).cmp(&self.position) {
+            std::cmp::Ordering::Equal => {
+                *cursor = cursor.checked_add(1).ok_or_else(|| {
+                    TransportError::permanent("in-memory topic cursor overflowed")
+                })?;
+                Ok(())
+            }
+            std::cmp::Ordering::Greater => Ok(()),
+            std::cmp::Ordering::Less => Err(TransportError::permanent(
+                "in-memory topic delivery was acknowledged out of order",
+            )),
+        }
+    }
+}
+
+/// In-memory delivery. Queue settlement remains a no-op because queue messages
+/// are popped on receive. Retained-topic cursors advance only on `ack`; `nack`
+/// leaves the exact gap-free position available for redelivery.
 pub struct InMemoryReceived {
     message: Message,
+    ordered: Option<OrderedDelivery>,
+    topic_settlement: Option<TopicSettlement>,
 }
 
 impl ReceivedMessage for InMemoryReceived {
     fn message(&self) -> &Message {
         &self.message
     }
+    fn ordered_delivery(&self) -> Option<&OrderedDelivery> {
+        self.ordered.as_ref()
+    }
     async fn ack(self) -> Result<(), TransportError> {
-        Ok(())
+        match self.topic_settlement {
+            Some(settlement) => settlement.ack(),
+            None => Ok(()),
+        }
     }
     async fn nack(self, _reason: &str) -> Result<(), TransportError> {
         Ok(())
@@ -177,6 +299,7 @@ impl ReceivedMessage for InMemoryReceived {
 mod tests {
     use super::*;
     use crate::bus::{Handlers, MessageKind};
+    use crate::trace_context::{CAUSATION_ID, TRACEPARENT};
     use std::future::Future;
 
     fn block_on<F: Future>(future: F) -> F::Output {
@@ -300,6 +423,105 @@ mod tests {
         assert_eq!(b_ids, vec!["e0", "e1", "e2"]);
     }
 
+    #[test]
+    fn topic_nack_redelivers_exact_gap_free_position_and_ack_advances() {
+        let bus = InMemoryBus::new();
+        for id in ["e0", "e1"] {
+            block_on(bus.publish_message(
+                Message::new("evt", MessageKind::Event, b"{}".to_vec()).with_id(id),
+            ))
+            .unwrap();
+        }
+        let mut source = TopicSource {
+            topics: bus.topics.clone(),
+            names: vec!["evt".into()],
+            cursors: TopicCursors::default(),
+            source_epoch: bus.source_epoch.clone(),
+        };
+
+        let first = block_on(source.recv()).unwrap().unwrap();
+        assert_eq!(first.message().id(), Some("e0"));
+        assert_eq!(first.ordered_delivery().unwrap().position(), 0);
+        assert!(first.ordered_delivery().unwrap().is_gap_free());
+        block_on(first.nack("transient")).unwrap();
+
+        let replay = block_on(source.recv()).unwrap().unwrap();
+        assert_eq!(replay.message().id(), Some("e0"));
+        assert_eq!(replay.ordered_delivery().unwrap().position(), 0);
+        block_on(replay.ack()).unwrap();
+
+        let second = block_on(source.recv()).unwrap().unwrap();
+        assert_eq!(second.message().id(), Some("e1"));
+        assert_eq!(second.ordered_delivery().unwrap().position(), 1);
+        block_on(second.ack()).unwrap();
+        assert!(block_on(source.recv()).unwrap().is_none());
+    }
+
+    #[test]
+    fn topic_stable_id_retry_reuses_original_position_and_ignores_trace_only_metadata() {
+        let bus = InMemoryBus::new();
+        let original = Message::new("evt", MessageKind::Event, br#"{"value":1}"#.to_vec())
+            .with_id("e0")
+            .with_metadata(CAUSATION_ID, "command-1")
+            .with_metadata(TRACEPARENT, "first-span");
+        let retry = Message::new("evt", MessageKind::Event, br#"{"value":1}"#.to_vec())
+            .with_id("e0")
+            .with_metadata(CAUSATION_ID, "command-1")
+            .with_metadata(TRACEPARENT, "retry-span");
+        block_on(bus.publish_message(original)).unwrap();
+        block_on(bus.publish_message(retry)).unwrap();
+
+        let topics = bus.topics.lock().unwrap();
+        let log = topics.get("evt").unwrap();
+        assert_eq!(log.len(), 1);
+        assert_eq!(log[0].traceparent(), Some("first-span"));
+        drop(topics);
+
+        let mut source = TopicSource {
+            topics: bus.topics.clone(),
+            names: vec!["evt".into()],
+            cursors: TopicCursors::default(),
+            source_epoch: bus.source_epoch.clone(),
+        };
+        let received = block_on(source.recv()).unwrap().unwrap();
+        assert_eq!(received.message().id(), Some("e0"));
+        assert_eq!(received.ordered_delivery().unwrap().position(), 0);
+        block_on(received.ack()).unwrap();
+        assert!(block_on(source.recv()).unwrap().is_none());
+    }
+
+    #[test]
+    fn topic_stable_id_reuse_with_different_causal_envelope_is_permanent() {
+        let bus = InMemoryBus::new();
+        let original = Message::new("evt", MessageKind::Event, br#"{"value":1}"#.to_vec())
+            .with_id("e0")
+            .with_metadata(CAUSATION_ID, "command-1");
+        block_on(bus.publish_message(original)).unwrap();
+
+        let cases = [
+            Message::new("other", MessageKind::Event, br#"{"value":1}"#.to_vec())
+                .with_id("e0")
+                .with_metadata(CAUSATION_ID, "command-1"),
+            Message::new("evt", MessageKind::Command, br#"{"value":1}"#.to_vec())
+                .with_id("e0")
+                .with_metadata(CAUSATION_ID, "command-1"),
+            Message::new("evt", MessageKind::Event, br#"{"value":2}"#.to_vec())
+                .with_id("e0")
+                .with_metadata(CAUSATION_ID, "command-1"),
+            Message::new("evt", MessageKind::Event, br#"{"value":1}"#.to_vec())
+                .with_id("e0")
+                .with_metadata(CAUSATION_ID, "command-2"),
+        ];
+        for retry in cases {
+            let error = block_on(bus.publish_message(retry)).unwrap_err();
+            assert!(error.is_permanent());
+            assert!(error.message().contains("message ID"));
+        }
+
+        let topics = bus.topics.lock().unwrap();
+        assert_eq!(topics.values().map(Vec::len).sum::<usize>(), 1);
+    }
+
     #[test]
     fn unknown_command_is_acked_and_ignored() {
         // A command with no handler is ignored by the runner (acked), not an error.
diff --git a/src/bus/mod.rs b/src/bus/mod.rs
index 7ee59ec6..75b21e9d 100644
--- a/src/bus/mod.rs
+++ b/src/bus/mod.rs
@@ -101,6 +101,7 @@ mod message_name;
 mod nats;
 #[cfg(feature = "nats")]
 mod nats_bus;
+mod ordered_delivery;
 #[cfg(feature = "postgres")]
 mod postgres_bus;
 mod publisher;
@@ -148,6 +149,7 @@ pub use in_memory_bus::{InMemoryBus, InMemoryReceived};
 pub(crate) use message::{message_from_wire, strip_address_prefix};
 pub use message::{Message, MessageKind, PayloadDecodeError, SubscriptionPlan};
 pub use message_name::{validate_message_name, MessageNameError, MAX_MESSAGE_NAME_LEN};
+pub use ordered_delivery::OrderedDelivery;
 #[cfg(feature = "postgres")]
 pub use postgres_bus::{LogReceived, PostgresBus, QueueReceived};
 pub use publisher::MessagePublisher;
diff --git a/src/bus/ordered_delivery.rs b/src/bus/ordered_delivery.rs
new file mode 100644
index 00000000..8dc2628d
--- /dev/null
+++ b/src/bus/ordered_delivery.rs
@@ -0,0 +1,62 @@
+//! Framework-authenticated ordering evidence attached by receive adapters.
+//!
+//! A public [`Message`](super::Message) deliberately cannot carry this value in
+//! metadata. Only transport implementations inside this crate can construct an
+//! `OrderedDelivery`; the shared runner forwards it separately to the message
+//! router. Causal projector routes fail closed when it is absent.
+
+use crate::projection_protocol::{
+    ProjectionEpoch, ProjectionProtocolValidationError, ProjectionSource, MAX_PROJECTION_POSITION,
+};
+
+/// Exact ordered position authenticated by a built-in source adapter.
+///
+/// The fields are readable for diagnostics but construction is crate-private.
+/// Application messages, UUIDs, timestamps, delivery attempts, and arbitrary
+/// broker headers can therefore never mint projection ordering evidence.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct OrderedDelivery {
+    source: ProjectionSource,
+    epoch: ProjectionEpoch,
+    position: u64,
+    gap_free: bool,
+}
+
+impl OrderedDelivery {
+    pub(crate) fn new(
+        source: ProjectionSource,
+        epoch: ProjectionEpoch,
+        position: u64,
+        gap_free: bool,
+    ) -> Result<Self, ProjectionProtocolValidationError> {
+        if position > MAX_PROJECTION_POSITION {
+            return Err(ProjectionProtocolValidationError::TooLarge {
+                field: "ordered delivery position",
+                value: position,
+                max: MAX_PROJECTION_POSITION,
+            });
+        }
+        Ok(Self {
+            source,
+            epoch,
+            position,
+            gap_free,
+        })
+    }
+
+    pub fn source(&self) -> &ProjectionSource {
+        &self.source
+    }
+
+    pub fn epoch(&self) -> &ProjectionEpoch {
+        &self.epoch
+    }
+
+    pub fn position(&self) -> u64 {
+        self.position
+    }
+
+    pub fn is_gap_free(&self) -> bool {
+        self.gap_free
+    }
+}
diff --git a/src/bus/postgres_bus.rs b/src/bus/postgres_bus.rs
index 46705168..a1b57699 100644
--- a/src/bus/postgres_bus.rs
+++ b/src/bus/postgres_bus.rs
@@ -7,8 +7,9 @@
 //!   one of N competing `listen`ers handles each command and the row is deleted
 //!   on success (redelivered on nack, until a `dead_letter`/`park` drops it).
 //! - **`publish` / `subscribe` (fan-out):** Postgres modelled as a log — an
-//!   append-only `bus_log` table (monotonic `seq`, retained) plus a per-consumer
-//!   offset table (`bus_offset`: `consumer → last_seq`). `publish` appends; each
+//!   append-only `bus_log` table (monotonic `seq`, retained), its durable
+//!   generation identity (`bus_log_identity`), and a per-consumer offset table
+//!   (`bus_offset`: `consumer → (source_epoch, last_seq)`). `publish` appends; each
 //!   `subscribe`r (keyed by its `group`) reads `seq > last_seq` for its event
 //!   names in order and advances its own offset, so every group sees every event.
 //!   Because the log, the offset, and projection writes share one Postgres, the
@@ -40,13 +41,14 @@
 //! [`MessageSource`]: super::MessageSource
 //! [`run_source`]: super::run_source
 
-use sqlx::{PgPool, Row};
+use sqlx::{PgConnection, PgPool, Row};
 
 use super::sql_bus_common::{
-    db_err as sql_db_err, metadata_json, ClaimedRow, ReceivedRow, SqlBus, SqlBusDialect,
-    SqlLogReceived, SqlQueueReceived,
+    db_err as sql_db_err, message_from_row, metadata_json, validate_log_retry, ClaimedRow,
+    ReceivedRow, SqlBus, SqlBusDialect, SqlLogReceived, SqlQueueReceived,
 };
 use super::{Message, TransportError};
+use crate::projection_protocol::ProjectionEpoch;
 
 const SCHEMA: &str = "\
 CREATE TABLE IF NOT EXISTS bus_queue (
@@ -85,9 +87,21 @@ CREATE TABLE IF NOT EXISTS bus_log (
 CREATE INDEX IF NOT EXISTS bus_log_name_seq_idx ON bus_log (name, seq);
 CREATE TABLE IF NOT EXISTS bus_offset (
     consumer TEXT PRIMARY KEY,
+    source_epoch TEXT NOT NULL,
     last_seq BIGINT NOT NULL DEFAULT 0,
     CHECK (consumer <> ''),
+    CHECK (source_epoch <> ''),
     CHECK (last_seq >= 0)
+);
+CREATE TABLE IF NOT EXISTS bus_log_identity (
+    singleton    SMALLINT PRIMARY KEY DEFAULT 1,
+    source_epoch TEXT NOT NULL,
+    generation   BIGINT NOT NULL DEFAULT 1,
+    high_water   BIGINT NOT NULL DEFAULT 0,
+    CHECK (singleton = 1),
+    CHECK (source_epoch <> ''),
+    CHECK (generation > 0),
+    CHECK (high_water >= 0)
 )";
 
 fn db_err(context: &str, err: sqlx::Error) -> TransportError {
@@ -153,6 +167,121 @@ impl PostgresBusDialect {
             .map_err(|err| db_err(context, err))?;
         Ok(())
     }
+
+    /// Lock and verify the durable identity paired with `bus_log`.
+    ///
+    /// Every framework append takes this singleton lock before allocating a
+    /// sequence. That makes `high_water` an exact committed fence rather than a
+    /// best-effort observation. A lower current maximum proves only that the
+    /// currently observed log ends below a previously committed position. It
+    /// fails closed; only [`SqlBus::reset_ordered_log`] may retire that cursor
+    /// domain.
+    async fn reconcile_log_identity(
+        connection: &mut PgConnection,
+        epoch_candidate: &ProjectionEpoch,
+        expected_epoch: Option<&ProjectionEpoch>,
+    ) -> Result<ProjectionEpoch, TransportError> {
+        let inserted = sqlx::query(
+            "INSERT INTO bus_log_identity \
+                 (singleton, source_epoch, generation, high_water) \
+             VALUES (1, $1, 1, 0) \
+             ON CONFLICT (singleton) DO NOTHING",
+        )
+        .bind(epoch_candidate.as_str())
+        .execute(&mut *connection)
+        .await
+        .map_err(|err| db_err("prepare log identity", err))?
+        .rows_affected()
+            == 1;
+
+        let identity = sqlx::query(
+            "SELECT source_epoch, generation, high_water \
+             FROM bus_log_identity WHERE singleton = 1 FOR UPDATE",
+        )
+        .fetch_one(&mut *connection)
+        .await
+        .map_err(|err| db_err("lock log identity", err))?;
+        let source_epoch: String = identity
+            .try_get("source_epoch")
+            .map_err(|err| db_err("decode log identity epoch", err))?;
+        let high_water: i64 = identity
+            .try_get("high_water")
+            .map_err(|err| db_err("decode log identity high water", err))?;
+        let log_max: i64 = sqlx::query_scalar("SELECT COALESCE(MAX(seq), 0)::BIGINT FROM bus_log")
+            .fetch_one(&mut *connection)
+            .await
+            .map_err(|err| db_err("read log high water", err))?;
+
+        if inserted && log_max > 0 && expected_epoch.is_none() {
+            return Err(TransportError::permanent(format!(
+                "postgres bus ordered-log identity is missing while the log \
+                 still contains positions through {log_max}; refusing to assign \
+                 a random epoch, explicitly adopt the retained log with \
+                 with_source_epoch"
+            )));
+        }
+        if inserted {
+            // An identity recreated independently of its offsets cannot prove
+            // which cursor generation those offsets belong to. Retire them in
+            // the same transaction that installs the new identity.
+            sqlx::query("DELETE FROM bus_offset")
+                .execute(&mut *connection)
+                .await
+                .map_err(|err| db_err("clear unbound log offsets", err))?;
+        }
+        if log_max < high_water {
+            return Err(TransportError::permanent(format!(
+                "postgres bus observed ordered-log maximum {log_max} below durable \
+                 high-water {high_water}; ordinary startup cannot rotate cursor \
+                 identity, use reset_ordered_log with the expected epoch"
+            )));
+        } else if log_max > high_water {
+            sqlx::query("UPDATE bus_log_identity SET high_water = $1 WHERE singleton = 1")
+                .bind(log_max)
+                .execute(&mut *connection)
+                .await
+                .map_err(|err| db_err("advance log high water", err))?;
+        }
+        if let Some(expected_epoch) = expected_epoch {
+            if source_epoch != expected_epoch.as_str() {
+                return Err(TransportError::permanent(format!(
+                    "postgres bus configured source epoch {:?} does not match \
+                     durable ordered-log epoch {:?}",
+                    expected_epoch.as_str(),
+                    source_epoch
+                )));
+            }
+        }
+
+        ProjectionEpoch::new(source_epoch).map_err(|error| {
+            TransportError::permanent(format!("postgres bus corrupt log identity epoch: {error}"))
+        })
+    }
+
+    async fn lock_expected_log_epoch(
+        connection: &mut PgConnection,
+        expected_epoch: &ProjectionEpoch,
+    ) -> Result<(), TransportError> {
+        let actual: String = sqlx::query_scalar(
+            "SELECT source_epoch FROM bus_log_identity \
+             WHERE singleton = 1 FOR SHARE",
+        )
+        .fetch_one(&mut *connection)
+        .await
+        .map_err(|err| db_err("lock log identity for read", err))?;
+        let actual = ProjectionEpoch::new(actual).map_err(|error| {
+            TransportError::permanent(format!("postgres bus corrupt log identity epoch: {error}"))
+        })?;
+        if &actual != expected_epoch {
+            return Err(TransportError::permanent(format!(
+                "postgres bus ordered-log epoch changed from {:?} to {:?}; \
+                 the subscriber must restart",
+                expected_epoch.as_str(),
+                actual.as_str()
+            )));
+        }
+        Ok(())
+    }
 }
 
 impl SqlBusDialect for PostgresBusDialect {
@@ -167,6 +296,85 @@ impl SqlBusDialect for PostgresBusDialect {
         Ok(())
     }
 
+    async fn ensure_ordered_log_schema(&self) -> Result<(), TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin ordered-log schema upgrade", err))?;
+        // Serialize legacy duplicate inspection, deletion, and index creation
+        // with every writer, including writers that predate this framework.
+        sqlx::query("LOCK TABLE bus_log IN ACCESS EXCLUSIVE MODE")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|err| db_err("lock ordered log for schema upgrade", err))?;
+        sqlx::query("ALTER TABLE bus_offset ADD COLUMN IF NOT EXISTS source_epoch TEXT")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|err| db_err("add offset epoch", err))?;
+        sqlx::query("DELETE FROM bus_offset WHERE source_epoch IS NULL OR source_epoch = ''")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|err| db_err("clear legacy unbound offsets", err))?;
+        sqlx::query("ALTER TABLE bus_offset ALTER COLUMN source_epoch SET NOT NULL")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|err| db_err("require offset epoch", err))?;
+
+        let duplicate_rows = sqlx::query(
+            "SELECT seq, name, message_id, kind, payload, content_type, metadata \
+             FROM bus_log \
+             WHERE message_id IN ( \
+                 SELECT message_id FROM bus_log \
+                 WHERE message_id IS NOT NULL \
+                 GROUP BY message_id HAVING COUNT(*) > 1 \
+             ) \
+             ORDER BY message_id, seq",
+        )
+        .fetch_all(&mut *transaction)
+        .await
+        .map_err(|err| db_err("inspect legacy stable message IDs", err))?;
+        let mut authoritative: Option<(String, Message)> = None;
+        let mut redundant = Vec::new();
+        for row in &duplicate_rows {
+            let message_id: String = row
+                .try_get("message_id")
+                .map_err(|err| db_err("decode legacy stable message ID", err))?;
+            let message = message_from_row(Self::BACKEND, row)?;
+            match authoritative.as_ref() {
+                Some((authoritative_id, authoritative_message))
+                    if authoritative_id == &message_id =>
+                {
+                    validate_log_retry(Self::BACKEND, authoritative_message, &message)?;
+                    redundant.push(
+                        row.try_get::<i64, _>("seq")
+                            .map_err(|err| db_err("decode redundant log position", err))?,
+                    );
+                }
+                _ => authoritative = Some((message_id, message)),
+            }
+        }
+        if !redundant.is_empty() {
+            sqlx::query("DELETE FROM bus_log WHERE seq = ANY($1)")
+                .bind(&redundant)
+                .execute(&mut *transaction)
+                .await
+                .map_err(|err| db_err("deduplicate legacy stable message IDs", err))?;
+        }
+        sqlx::query(
+            "CREATE UNIQUE INDEX IF NOT EXISTS bus_log_message_id_unique_idx \
+             ON bus_log (message_id) WHERE message_id IS NOT NULL",
+        )
+        .execute(&mut *transaction)
+        .await
+        .map_err(|err| db_err("fence stable message IDs", err))?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit ordered-log schema upgrade", err))?;
+        Ok(())
+    }
+
     async fn insert_queue(&self, message: &Message) -> Result<(), TransportError> {
         self.insert(
             "INSERT INTO bus_queue (name, message_id, kind, payload, content_type, metadata) \
@@ -177,14 +385,162 @@ impl SqlBusDialect for PostgresBusDialect {
         .await
     }
 
-    async fn insert_log(&self, message: &Message) -> Result<(), TransportError> {
-        self.insert(
-            "INSERT INTO bus_log (name, message_id, kind, payload, content_type, metadata) \
-             VALUES ($1, $2, $3, $4, $5, $6)",
-            "append",
-            message,
+    async fn insert_log(
+        &self,
+        message: &Message,
+        epoch_candidate: &ProjectionEpoch,
+        expected_epoch: Option<&ProjectionEpoch>,
+    ) -> Result<(), TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin append", err))?;
+        Self::reconcile_log_identity(&mut transaction, epoch_candidate, expected_epoch).await?;
+
+        let metadata = metadata_json(message);
+        let inserted_seq = if message.id().is_some() {
+            sqlx::query_scalar::<_, i64>(
+                "INSERT INTO bus_log \
+                     (name, message_id, kind, payload, content_type, metadata) \
+                 VALUES ($1, $2, $3, $4, $5, $6) \
+                 ON CONFLICT (message_id) WHERE message_id IS NOT NULL DO NOTHING \
+                 RETURNING seq",
+            )
+            .bind(&message.name)
+            .bind(&message.id)
+            .bind(message.kind.as_str())
+            .bind(&message.payload)
+            .bind(&message.content_type)
+            .bind(&metadata)
+            .fetch_optional(&mut *transaction)
+            .await
+            .map_err(|err| db_err("append", err))?
+        } else {
+            Some(
+                sqlx::query_scalar::<_, i64>(
+                    "INSERT INTO bus_log \
+                         (name, message_id, kind, payload, content_type, metadata) \
+                     VALUES ($1, $2, $3, $4, $5, $6) \
+                     RETURNING seq",
+                )
+                .bind(&message.name)
+                .bind(&message.id)
+                .bind(message.kind.as_str())
+                .bind(&message.payload)
+                .bind(&message.content_type)
+                .bind(&metadata)
+                .fetch_one(&mut *transaction)
+                .await
+                .map_err(|err| db_err("append", err))?,
+            )
+        };
+
+        let seq = match inserted_seq {
+            Some(seq) => seq,
+            None => {
+                let existing = sqlx::query(
+                    "SELECT seq, name, message_id, kind, payload, content_type, metadata \
+                     FROM bus_log WHERE message_id = $1",
+                )
+                .bind(message.id())
+                .fetch_optional(&mut *transaction)
+                .await
+                .map_err(|err| db_err("read idempotent append", err))?
+                .ok_or_else(|| {
+                    TransportError::permanent(
+                        "postgres bus stable message ID conflict had no existing log row",
+                    )
+                })?;
+                let existing_message = message_from_row(Self::BACKEND, &existing)?;
+                validate_log_retry(Self::BACKEND, &existing_message, message)?;
+                existing
+                    .try_get("seq")
+                    .map_err(|err| db_err("decode idempotent append position", err))?
+            }
+        };
+
+        sqlx::query(
+            "UPDATE bus_log_identity SET high_water = GREATEST(high_water, $1) \
+             WHERE singleton = 1",
         )
+        .bind(seq)
+        .execute(&mut *transaction)
         .await
+        .map_err(|err| db_err("advance log high water", err))?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit append", err))?;
+        Ok(())
+    }
+
+    async fn prepare_log_epoch(
+        &self,
+        epoch_candidate: &ProjectionEpoch,
+        expected_epoch: Option<&ProjectionEpoch>,
+    ) -> Result<ProjectionEpoch, TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin log identity", err))?;
+        let epoch =
+            Self::reconcile_log_identity(&mut transaction, epoch_candidate, expected_epoch).await?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit log identity", err))?;
+        Ok(epoch)
+    }
+
+    async fn reset_log(
+        &self,
+        expected_epoch: &ProjectionEpoch,
+        next_epoch: &ProjectionEpoch,
+    ) -> Result<(), TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin ordered-log reset", err))?;
+        let actual: String = sqlx::query_scalar(
+            "SELECT source_epoch FROM bus_log_identity \
+             WHERE singleton = 1 FOR UPDATE",
+        )
+        .fetch_one(&mut *transaction)
+        .await
+        .map_err(|err| db_err("lock ordered-log reset fence", err))?;
+        if actual != expected_epoch.as_str() {
+            return Err(TransportError::permanent(format!(
+                "postgres bus ordered-log reset expected epoch {:?} but durable \
+                 epoch is {:?}",
+                expected_epoch.as_str(),
+                actual
+            )));
+        }
+        sqlx::query("TRUNCATE TABLE bus_log RESTART IDENTITY")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|err| db_err("clear ordered log", err))?;
+        sqlx::query("DELETE FROM bus_offset")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|err| db_err("clear ordered-log offsets", err))?;
+        sqlx::query(
+            "UPDATE bus_log_identity \
+             SET source_epoch = $1, generation = generation + 1, high_water = 0 \
+             WHERE singleton = 1",
+        )
+        .bind(next_epoch.as_str())
+        .execute(&mut *transaction)
+        .await
+        .map_err(|err| db_err("install next ordered-log epoch", err))?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit ordered-log reset", err))?;
+        Ok(())
     }
 
     async fn claim(
@@ -233,19 +589,34 @@ impl SqlBusDialect for PostgresBusDialect {
         names: &[String],
         consumer: &str,
         limit: i64,
+        expected_epoch: &ProjectionEpoch,
     ) -> Result<Vec<ReceivedRow>, TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin log read", err))?;
+        Self::lock_expected_log_epoch(&mut transaction, expected_epoch).await?;
         let rows = sqlx::query(
             "SELECT seq, name, message_id, kind, payload, content_type, metadata FROM bus_log \
              WHERE (name = ANY($1) OR name IS NULL) \
-                   AND seq > COALESCE((SELECT last_seq FROM bus_offset WHERE consumer = $2), 0) \
-             ORDER BY seq LIMIT $3",
+                   AND seq > COALESCE(( \
+                       SELECT last_seq FROM bus_offset \
+                       WHERE consumer = $2 AND source_epoch = $3 \
+                   ), 0) \
+             ORDER BY seq LIMIT $4",
         )
         .bind(names)
         .bind(consumer)
+        .bind(expected_epoch.as_str())
         .bind(limit)
-        .fetch_all(&self.pool)
+        .fetch_all(&mut *transaction)
         .await
         .map_err(|err| db_err("log read", err))?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit log read", err))?;
 
         Ok(rows
             .iter()
@@ -253,6 +624,23 @@ impl SqlBusDialect for PostgresBusDialect {
             .collect())
     }
 
+    async fn verify_log_epoch(
+        &self,
+        expected_epoch: &ProjectionEpoch,
+    ) -> Result<(), TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin log epoch check", err))?;
+        Self::lock_expected_log_epoch(&mut transaction, expected_epoch).await?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit log epoch check", err))?;
+        Ok(())
+    }
+
     async fn delete_claimed(&self, seq: i64, claim_token: &str) -> Result<(), TransportError> {
         sqlx::query("DELETE FROM bus_queue WHERE seq = $1 AND claim_token = $2")
             .bind(seq)
@@ -277,17 +665,38 @@ impl SqlBusDialect for PostgresBusDialect {
         Ok(())
     }
 
-    async fn advance_offset(&self, consumer: &str, seq: i64) -> Result<(), TransportError> {
+    async fn advance_offset(
+        &self,
+        consumer: &str,
+        seq: i64,
+        expected_epoch: &ProjectionEpoch,
+    ) -> Result<(), TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin advance offset", err))?;
+        Self::lock_expected_log_epoch(&mut transaction, expected_epoch).await?;
         sqlx::query(
-            "INSERT INTO bus_offset (consumer, last_seq) VALUES ($1, $2) \
-             ON CONFLICT (consumer) DO UPDATE SET last_seq = EXCLUDED.last_seq \
-             WHERE bus_offset.last_seq < EXCLUDED.last_seq",
+            "INSERT INTO bus_offset (consumer, source_epoch, last_seq) VALUES ($1, $2, $3) \
+             ON CONFLICT (consumer) DO UPDATE SET \
+                 source_epoch = EXCLUDED.source_epoch, \
+                 last_seq = CASE \
+                     WHEN bus_offset.source_epoch = EXCLUDED.source_epoch \
+                     THEN GREATEST(bus_offset.last_seq, EXCLUDED.last_seq) \
+                     ELSE EXCLUDED.last_seq \
+                 END",
         )
         .bind(consumer)
+        .bind(expected_epoch.as_str())
         .bind(seq)
-        .execute(&self.pool)
+        .execute(&mut *transaction)
         .await
         .map_err(|err| db_err("advance offset", err))?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit advance offset", err))?;
         Ok(())
     }
 }
diff --git a/src/bus/router.rs b/src/bus/router.rs
index 13de5236..0ad35dd9 100644
--- a/src/bus/router.rs
+++ b/src/bus/router.rs
@@ -10,7 +10,7 @@
 use std::future::Future;
 
 use super::TransportError;
-use super::{Message, MessageKind, SubscriptionPlan};
+use super::{Message, MessageKind, OrderedDelivery, SubscriptionPlan};
 
 /// What the receive loop and the consumer adapters need from a message consumer.
 ///
@@ -48,4 +48,17 @@ pub trait MessageRouter: Send + Sync {
         &self,
         message: &Message,
     ) -> impl Future<Output = Result<(), TransportError>> + Send;
+
+    /// Route one message together with adapter-authenticated ordering evidence.
+    ///
+    /// Ordinary routers and legacy event handlers keep the default behavior.
+    /// A causal projector-aware router overrides this method and fails closed
+    /// for its projector routes when `ordered` is absent.
+    fn dispatch_ordered(
+        &self,
+        message: &Message,
+        _ordered: Option<&OrderedDelivery>,
+    ) -> impl Future<Output = Result<(), TransportError>> + Send {
+        self.dispatch(message)
+    }
 }
diff --git a/src/bus/runner.rs b/src/bus/runner.rs
deleted file mode 100644
index c95c62b8..00000000
--- a/src/bus/runner.rs
+++ /dev/null
@@ -1,981 +0,0 @@
-//! The direct-source runner.
-//!
-//! [`run_source`] is the shared receive loop for direct transports. It owns the
-//! cross-cutting policy — when execution counts as successful, how retryable vs
-//! permanent failures are routed — while the adapter owns how acknowledgement
-//! maps back to the transport. The same dispatch/runner boundary is what the
-//! Knative/HTTP ingress will call, so consumer execution stays identical across
-//! ingress shapes.
-
-use std::future::Future;
-use std::sync::Arc;
-
-use super::source::{MessageSource, ReceivedMessage};
-use super::{FailureAction, MessageRouter, RunOptions, TransportError, TransportErrorKind};
-use super::{Message, MessageKind};
-
-/// Run the receive loop for a direct transport source.
-///
-/// For each message the runner:
-///
-/// 1. enforces the inbox stable-id contract (a no-op in idempotent mode);
-/// 2. dispatches through [`MessageRouter::dispatch`];
-/// 3. on success, acknowledges via the adapter;
-/// 4. on failure, routes through [`RunOptions::failure_policy`] — retryable
-///    failures are nacked for redelivery, permanent failures take the configured
-///    action ([dead-letter](FailureAction::DeadLetter), [park](FailureAction::Park),
-///    [log-and-ack](FailureAction::LogAndAck), or [stop](FailureAction::Stop)).
-///
-/// A message with no registered handler is **intentionally ignored**: the runner
-/// acks it and moves on rather than dead-lettering it. Fan-out event transports
-/// may deliver events this service does not consume, and acking matches
-/// `microsvc::subscribe`; production transports should use
-/// [`MessageRouter::subscription_plan`] to avoid delivering unrelated messages at all.
-///
-/// The runner **acks only after handler effects have completed**, never before.
-/// It stops gracefully when the source returns `Ok(None)`, having fully settled
-/// the in-flight message first. Receive and settle errors are propagated, not
-/// swallowed: a returned `Err` ends the run and the supervisor may restart it
-/// (already-committed effects make redelivery safe).
-///
-/// Inbox note: until the consumer-inbox subtask lands, inbox mode enforces the
-/// stable-id requirement and then dispatches like idempotent mode. The
-/// receipt-commit wrapping that makes it effectively-once is added there.
-///
-/// `I: Send` keeps the returned future `Send` so the runner can be spawned on a
-/// multi-threaded executor regardless of the inbox hook type.
-pub async fn run_source<R, S, I>(
-    router: Arc<R>,
-    mut source: S,
-    options: RunOptions<I>,
-) -> Result<(), TransportError>
-where
-    R: MessageRouter,
-    S: MessageSource,
-    I: Send,
-{
-    let service = router.consumer_group();
-    let transport = source.transport_name();
-
-    loop {
-        let Some(received) = recv_next(&mut source, service, transport).await? else {
-            break;
-        };
-
-        // A delivery the transport could not decode is a permanent failure: it
-        // carries no valid message to dispatch, and it must NOT be treated as an
-        // empty message (which would route to ack-and-ignore below and silently
-        // drop a corrupt row). Route it through the failure policy directly, the
-        // same as a permanent dispatch failure, so it is dead-lettered/parked.
-        if let Some(error) = received.decode_error() {
-            let action = options.failure_policy.resolve(error);
-            record_transport_failure(service, transport, error.kind(), action);
-            let kind = received.message().kind;
-            match action {
-                FailureAction::Nack => {
-                    let reason = error.to_string();
-                    settle_and_record(
-                        service,
-                        transport,
-                        kind,
-                        crate::telemetry::transport_outcome::NACK,
-                        crate::telemetry::transport_outcome::NACK,
-                        || received.nack(&reason),
-                    )
-                    .await?;
-                }
-                FailureAction::DeadLetter => {
-                    let reason = error.to_string();
-                    settle_and_record(
-                        service,
-                        transport,
-                        kind,
-                        crate::telemetry::transport_outcome::DEAD_LETTER,
-                        crate::telemetry::transport_outcome::DEAD_LETTER,
-                        || received.dead_letter(&reason),
-                    )
-                    .await?;
-                }
-                FailureAction::Park => {
-                    let reason = error.to_string();
-                    settle_and_record(
-                        service,
-                        transport,
-                        kind,
-                        crate::telemetry::transport_outcome::PARK,
-                        crate::telemetry::transport_outcome::PARK,
-                        || received.park(&reason),
-                    )
-                    .await?;
-                }
-                FailureAction::LogAndAck => {
-                    eprintln!("[bus::runner] dropping undecodable message after permanent failure: {error}");
-                    settle_and_record(
-                        service,
-                        transport,
-                        kind,
-                        crate::telemetry::transport_outcome::ACK,
-                        crate::telemetry::transport_outcome::LOG_AND_ACK,
-                        || received.ack(),
-                    )
-                    .await?;
-                }
-                FailureAction::Stop => return Err(TransportError::permanent(error.to_string())),
-            }
-            continue;
-        }
-        // No handler for this message: intentionally ignore (ack) rather than
-        // dead-letter, so unrelated fan-out events don't pile into the DLQ.
-        if !router.handles(received.message().kind, received.message().name()) {
-            let kind = received.message().kind;
-            settle_and_record(
-                service,
-                transport,
-                kind,
-                crate::telemetry::transport_outcome::ACK,
-                crate::telemetry::transport_outcome::IGNORED,
-                || received.ack(),
-            )
-            .await?;
-            continue;
-        }
-        let kind = received.message().kind;
-        match dispatch(router.as_ref(), &options, received.message()).await {
-            Ok(()) => {
-                settle_and_record(
-                    service,
-                    transport,
-                    kind,
-                    crate::telemetry::transport_outcome::ACK,
-                    crate::telemetry::transport_outcome::ACK,
-                    || received.ack(),
-                )
-                .await?;
-            }
-            Err(error) => match options.failure_policy.resolve(&error) {
-                action @ FailureAction::Nack => {
-                    record_transport_failure(service, transport, error.kind(), action);
-                    let reason = error.to_string();
-                    settle_and_record(
-                        service,
-                        transport,
-                        kind,
-                        crate::telemetry::transport_outcome::NACK,
-                        crate::telemetry::transport_outcome::NACK,
-                        || received.nack(&reason),
-                    )
-                    .await?;
-                }
-                action @ FailureAction::DeadLetter => {
-                    record_transport_failure(service, transport, error.kind(), action);
-                    let reason = error.to_string();
-                    settle_and_record(
-                        service,
-                        transport,
-                        kind,
-                        crate::telemetry::transport_outcome::DEAD_LETTER,
-                        crate::telemetry::transport_outcome::DEAD_LETTER,
-                        || received.dead_letter(&reason),
-                    )
-                    .await?;
-                }
-                action @ FailureAction::Park => {
-                    record_transport_failure(service, transport, error.kind(), action);
-                    let reason = error.to_string();
-                    settle_and_record(
-                        service,
-                        transport,
-                        kind,
-                        crate::telemetry::transport_outcome::PARK,
-                        crate::telemetry::transport_outcome::PARK,
-                        || received.park(&reason),
-                    )
-                    .await?;
-                }
-                FailureAction::LogAndAck => {
-                    record_transport_failure(
-                        service,
-                        transport,
-                        error.kind(),
-                        FailureAction::LogAndAck,
-                    );
-                    eprintln!(
-                        "[bus::runner] dropping message '{}' after permanent failure: {error}",
-                        received.message().name()
-                    );
-                    settle_and_record(
-                        service,
-                        transport,
-                        kind,
-                        crate::telemetry::transport_outcome::ACK,
-                        crate::telemetry::transport_outcome::LOG_AND_ACK,
-                        || received.ack(),
-                    )
-                    .await?;
-                }
-                FailureAction::Stop => {
-                    record_transport_failure(service, transport, error.kind(), FailureAction::Stop);
-                    return Err(error);
-                }
-            },
-        }
-    }
-    Ok(())
-}
-
-async fn settle_and_record<F, Fut>(
-    service: Option<&str>,
-    transport: &str,
-    kind: MessageKind,
-    settle_action: &'static str,
-    outcome: &'static str,
-    settle: F,
-) -> Result<(), TransportError>
-where
-    F: FnOnce() -> Fut,
-    Fut: Future<Output = Result<(), TransportError>>,
-{
-    match settle().await {
-        Ok(()) => {
-            record_transport_message(service, transport, kind, outcome);
-            Ok(())
-        }
-        Err(error) => {
-            record_transport_failure(
-                service,
-                transport,
-                error.kind(),
-                crate::telemetry::settle_failure_action(settle_action),
-            );
-            Err(error)
-        }
-    }
-}
-
-async fn recv_next<S: MessageSource>(
-    source: &mut S,
-    service: Option<&str>,
-    transport: &str,
-) -> Result<Option<S::Received>, TransportError> {
-    match source.recv().await {
-        Ok(received) => Ok(received),
-        Err(error) => {
-            record_transport_failure(
-                service,
-                transport,
-                error.kind(),
-                crate::telemetry::failure_action::RECV_ERROR,
-            );
-            Err(error)
-        }
-    }
-}
-
-/// Run consumer execution for one message and classify the outcome.
-///
-/// Enforces the inbox stable-id contract first (idempotent mode yields no key
-/// and skips it), then dispatches. A failed stable-id check is a permanent
-/// failure — redelivery cannot supply a missing or malformed id.
-async fn dispatch<R: MessageRouter, I>(
-    router: &R,
-    options: &RunOptions<I>,
-    message: &Message,
-) -> Result<(), TransportError> {
-    #[cfg(feature = "otel")]
-    {
-        use tracing::Instrument as _;
-
-        let span = transport_receive_span(message);
-        crate::trace_context::set_span_parent_from_metadata_if_no_current_span(
-            &span,
-            &message.metadata,
-        );
-        return async {
-            options
-                .validate_message_id(message)
-                .map_err(|err| TransportError::permanent(err.to_string()).with_source(err))?;
-            router.dispatch(message).await
-        }
-        .instrument(span)
-        .await;
-    }
-
-    #[cfg(not(feature = "otel"))]
-    {
-        options
-            .validate_message_id(message)
-            .map_err(|err| TransportError::permanent(err.to_string()).with_source(err))?;
-        router.dispatch(message).await
-    }
-}
-
-#[cfg(feature = "otel")]
-fn transport_receive_span(message: &Message) -> tracing::Span {
-    crate::telemetry::transport_receive_span(message)
-}
-
-fn record_transport_message(
-    service: Option<&str>,
-    transport: &str,
-    kind: MessageKind,
-    outcome: &str,
-) {
-    #[cfg(feature = "metrics")]
-    crate::metrics::record_transport_message(service, transport, kind, outcome);
-    #[cfg(not(feature = "metrics"))]
-    let _ = (service, transport, kind, outcome);
-}
-
-fn record_transport_failure<A>(
-    service: Option<&str>,
-    transport: &str,
-    kind: TransportErrorKind,
-    action: A,
-) where
-    A: IntoFailureActionLabel,
-{
-    #[cfg(feature = "metrics")]
-    crate::metrics::record_transport_failure(
-        service,
-        transport,
-        crate::telemetry::transport_failure_class(kind),
-        action.into_failure_action_label(),
-    );
-    #[cfg(not(feature = "metrics"))]
-    {
-        let _ = (service, transport, kind);
-        let _ = action.into_failure_action_label();
-    }
-}
-
-trait IntoFailureActionLabel {
-    fn into_failure_action_label(self) -> &'static str;
-}
-
-impl IntoFailureActionLabel for FailureAction {
-    fn into_failure_action_label(self) -> &'static str {
-        crate::telemetry::failure_action_label(self)
-    }
-}
-
-impl IntoFailureActionLabel for &'static str {
-    fn into_failure_action_label(self) -> &'static str {
-        self
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::bus::{FailurePolicy, Handlers, MessageKind};
-    use std::collections::VecDeque;
-    use std::future::Future;
-    use std::sync::Mutex;
-
-    // --- minimal runtime-free executor -------------------------------------
-    // The transport module is not feature-gated, so its tests run without an
-    // async runtime. The fake futures never suspend, so a busy-poll with a
-    // no-op waker drives them to completion.
-    fn block_on<F: Future>(future: F) -> F::Output {
-        use std::ptr;
-        use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
-
-        const VTABLE: RawWakerVTable = RawWakerVTable::new(
-            |_| RawWaker::new(ptr::null(), &VTABLE),
-            |_| {},
-            |_| {},
-            |_| {},
-        );
-        let raw = RawWaker::new(ptr::null(), &VTABLE);
-        let waker = unsafe { Waker::from_raw(raw) };
-        let mut cx = Context::from_waker(&waker);
-        let mut future = std::pin::pin!(future);
-        loop {
-            if let Poll::Ready(output) = future.as_mut().poll(&mut cx) {
-                return output;
-            }
-        }
-    }
-
-    // --- recorder + fakes ---------------------------------------------------
-    #[derive(Debug, Clone, PartialEq, Eq)]
-    enum Event {
-        Handled(String),
-        Ack,
-        Nack(String),
-        DeadLetter(String),
-        Park(String),
-    }
-
-    struct Recorder {
-        events: Mutex<Vec<Event>>,
-    }
-
-    impl Recorder {
-        fn new() -> Arc<Self> {
-            Arc::new(Self {
-                events: Mutex::new(Vec::new()),
-            })
-        }
-        fn push(&self, event: Event) {
-            self.events.lock().unwrap().push(event);
-        }
-        fn events(&self) -> Vec<Event> {
-            self.events.lock().unwrap().clone()
-        }
-    }
-
-    struct FakeReceived {
-        message: Message,
-        recorder: Arc<Recorder>,
-        settle_ok: bool,
-        decode_error: Option<TransportError>,
-    }
-
-    impl FakeReceived {
-        fn settle(self, event: Event) -> Result<(), TransportError> {
-            self.recorder.push(event);
-            if self.settle_ok {
-                Ok(())
-            } else {
-                Err(TransportError::retryable("settle failed"))
-            }
-        }
-    }
-
-    impl ReceivedMessage for FakeReceived {
-        fn message(&self) -> &Message {
-            &self.message
-        }
-        fn decode_error(&self) -> Option<&TransportError> {
-            self.decode_error.as_ref()
-        }
-        async fn ack(self) -> Result<(), TransportError> {
-            self.settle(Event::Ack)
-        }
-        async fn nack(self, reason: &str) -> Result<(), TransportError> {
-            self.settle(Event::Nack(reason.to_string()))
-        }
-        async fn dead_letter(self, reason: &str) -> Result<(), TransportError> {
-            self.settle(Event::DeadLetter(reason.to_string()))
-        }
-        async fn park(self, reason: &str) -> Result<(), TransportError> {
-            self.settle(Event::Park(reason.to_string()))
-        }
-    }
-
-    struct FakeSource {
-        queue: VecDeque<Message>,
-        recorder: Arc<Recorder>,
-        settle_ok: bool,
-        recv_error: bool,
-        // When set, every received message reports this as a decode failure,
-        // modeling a transport that claims a row/offset before decoding it.
-        decode_error: bool,
-    }
-
-    impl MessageSource for FakeSource {
-        type Received = FakeReceived;
-        async fn recv(&mut self) -> Result<Option<FakeReceived>, TransportError> {
-            if self.recv_error {
-                return Err(TransportError::retryable("recv failed"));
-            }
-            let decode_error = self.decode_error;
-            Ok(self.queue.pop_front().map(|message| FakeReceived {
-                message,
-                recorder: self.recorder.clone(),
-                settle_ok: self.settle_ok,
-                decode_error: decode_error
-                    .then(|| TransportError::permanent("corrupt row: name failed to decode")),
-            }))
-        }
-    }
-
-    // --- helpers ------------------------------------------------------------
-    fn event_message(name: &str, id: Option<&str>) -> Message {
-        let mut message = Message::new(name, MessageKind::Event, b"{}".to_vec());
-        if let Some(id) = id {
-            message = message.with_id(id);
-        }
-        message
-    }
-
-    fn router(recorder: &Arc<Recorder>) -> Arc<Handlers> {
-        let ok = recorder.clone();
-        let retryable = recorder.clone();
-        let permanent = recorder.clone();
-        Arc::new(
-            Handlers::new()
-                .on_event("ok", move |msg: &Message| {
-                    let ok = ok.clone();
-                    let name = msg.name().to_string();
-                    async move {
-                        ok.push(Event::Handled(name));
-                        Ok(())
-                    }
-                })
-                .on_event("retryable", move |msg: &Message| {
-                    let retryable = retryable.clone();
-                    let name = msg.name().to_string();
-                    async move {
-                        retryable.push(Event::Handled(name));
-                        Err(TransportError::retryable("infra"))
-                    }
-                })
-                .on_event("permanent", move |msg: &Message| {
-                    let permanent = permanent.clone();
-                    let name = msg.name().to_string();
-                    async move {
-                        permanent.push(Event::Handled(name));
-                        Err(TransportError::permanent("nope"))
-                    }
-                }),
-        )
-    }
-
-    struct RunResult {
-        outcome: Result<(), TransportError>,
-        events: Vec<Event>,
-    }
-
-    fn run<I: Send>(messages: Vec<Message>, options: RunOptions<I>) -> RunResult {
-        run_with(messages, options, true, false)
-    }
-
-    fn run_with<I: Send>(
-        messages: Vec<Message>,
-        options: RunOptions<I>,
-        settle_ok: bool,
-        recv_error: bool,
-    ) -> RunResult {
-        let recorder = Recorder::new();
-        let svc = router(&recorder);
-        let source = FakeSource {
-            queue: messages.into_iter().collect(),
-            recorder: recorder.clone(),
-            settle_ok,
-            recv_error,
-            decode_error: false,
-        };
-        let outcome = block_on(run_source(svc, source, options));
-        RunResult {
-            outcome,
-            events: recorder.events(),
-        }
-    }
-
-    // --- tests --------------------------------------------------------------
-    #[test]
-    fn success_dispatches_then_acks_in_order() {
-        let result = run(vec![event_message("ok", None)], RunOptions::idempotent());
-        assert!(result.outcome.is_ok());
-        // Handler effect is recorded before the ack: ack happens after success.
-        assert_eq!(
-            result.events,
-            vec![Event::Handled("ok".to_string()), Event::Ack]
-        );
-    }
-
-    #[test]
-    fn processes_every_message_then_stops_on_none() {
-        let result = run(
-            vec![event_message("ok", None), event_message("ok", None)],
-            RunOptions::idempotent(),
-        );
-        assert!(result.outcome.is_ok());
-        assert_eq!(
-            result.events,
-            vec![
-                Event::Handled("ok".to_string()),
-                Event::Ack,
-                Event::Handled("ok".to_string()),
-                Event::Ack,
-            ]
-        );
-    }
-
-    #[cfg(feature = "metrics")]
-    #[test]
-    fn metrics_record_success_and_failure_settlement_outcomes() {
-        let _guard = crate::metrics::lock_for_tests();
-        crate::metrics::reset_for_tests();
-
-        let recorder = Recorder::new();
-        let svc = Arc::new(
-            router(&recorder)
-                .as_ref()
-                .clone()
-                .named("metrics-runner-settlement"),
-        );
-        let source = FakeSource {
-            queue: vec![event_message("ok", None), event_message("retryable", None)]
-                .into_iter()
-                .collect(),
-            recorder,
-            settle_ok: true,
-            recv_error: false,
-            decode_error: false,
-        };
-
-        let outcome = block_on(run_source(svc, source, RunOptions::idempotent()));
-        assert!(outcome.is_ok());
-
-        let text = crate::metrics::prometheus_text();
-        assert!(
-            text.contains(
-                "distributed_transport_messages_total{service=\"metrics-runner-settlement\",transport=\"unknown\",message_kind=\"event\",outcome=\"ack\"} 1"
-            ),
-            "metrics should include the ack outcome:\n{text}"
-        );
-        assert!(
-            text.contains(
-                "distributed_transport_messages_total{service=\"metrics-runner-settlement\",transport=\"unknown\",message_kind=\"event\",outcome=\"nack\"} 1"
-            ),
-            "metrics should include the nack outcome:\n{text}"
-        );
-        assert!(
-            text.contains(
-                "distributed_transport_failures_total{service=\"metrics-runner-settlement\",transport=\"unknown\",failure_class=\"retryable\",action=\"nack\"} 1"
-            ),
-            "metrics should include the retryable failure action:\n{text}"
-        );
-    }
-
-    #[cfg(feature = "metrics")]
-    #[test]
-    fn metrics_record_settle_failures_before_propagating() {
-        let _guard = crate::metrics::lock_for_tests();
-        crate::metrics::reset_for_tests();
-
-        let recorder = Recorder::new();
-        let svc = Arc::new(
-            router(&recorder)
-                .as_ref()
-                .clone()
-                .named("metrics-runner-settle-failure"),
-        );
-        let source = FakeSource {
-            queue: vec![event_message("ok", None)].into_iter().collect(),
-            recorder,
-            settle_ok: false,
-            recv_error: false,
-            decode_error: false,
-        };
-
-        let outcome = block_on(run_source(svc, source, RunOptions::idempotent()));
-        assert!(outcome
-            .expect_err("settle error should propagate")
-            .is_retryable());
-
-        let text = crate::metrics::prometheus_text();
-        assert!(
-            text.contains(
-                "distributed_transport_failures_total{service=\"metrics-runner-settle-failure\",transport=\"unknown\",failure_class=\"retryable\",action=\"settle_ack\"} 1"
-            ),
-            "metrics should include the settle failure:\n{text}"
-        );
-        assert!(
-            !text.contains(
-                "distributed_transport_messages_total{service=\"metrics-runner-settle-failure\",transport=\"unknown\",message_kind=\"event\",outcome=\"ack\"} 1"
-            ),
-            "settle failure should not record an ack outcome:\n{text}"
-        );
-    }
-
-    #[test]
-    fn retryable_failure_nacks_without_acking() {
-        let result = run(
-            vec![event_message("retryable", None)],
-            RunOptions::idempotent(),
-        );
-        assert!(result.outcome.is_ok());
-        assert_eq!(
-            result.events.first(),
-            Some(&Event::Handled("retryable".to_string()))
-        );
-        assert!(matches!(result.events.get(1), Some(Event::Nack(_))));
-        assert!(!result.events.contains(&Event::Ack));
-    }
-
-    #[test]
-    fn permanent_failure_dead_letters_under_default_policy() {
-        let result = run(
-            vec![event_message("permanent", None)],
-            RunOptions::idempotent(),
-        );
-        assert!(result.outcome.is_ok());
-        assert_eq!(
-            result.events.first(),
-            Some(&Event::Handled("permanent".to_string()))
-        );
-        assert!(matches!(result.events.get(1), Some(Event::DeadLetter(_))));
-    }
-
-    #[test]
-    fn permanent_failure_parks_under_park_policy() {
-        let result = run(
-            vec![event_message("permanent", None)],
-            RunOptions::idempotent().with_failure_policy(FailurePolicy::Park),
-        );
-        assert!(result.outcome.is_ok());
-        assert!(matches!(result.events.get(1), Some(Event::Park(_))));
-    }
-
-    #[test]
-    fn permanent_failure_logs_and_acks_under_log_and_ack_policy() {
-        let result = run(
-            vec![event_message("permanent", None)],
-            RunOptions::idempotent().with_failure_policy(FailurePolicy::LogAndAck),
-        );
-        assert!(result.outcome.is_ok());
-        assert_eq!(result.events.get(1), Some(&Event::Ack));
-    }
-
-    #[test]
-    fn permanent_failure_nacks_under_retry_policy() {
-        let result = run(
-            vec![event_message("permanent", None)],
-            RunOptions::idempotent().with_failure_policy(FailurePolicy::Retry),
-        );
-        assert!(result.outcome.is_ok());
-        assert!(matches!(result.events.get(1), Some(Event::Nack(_))));
-    }
-
-    #[test]
-    fn stop_policy_returns_error_without_settling() {
-        let result = run(
-            vec![event_message("permanent", None), event_message("ok", None)],
-            RunOptions::idempotent().with_failure_policy(FailurePolicy::Stop),
-        );
-        let err = result
-            .outcome
-            .expect_err("stop policy should surface the error");
-        assert!(err.is_permanent());
-        // The handler ran, but the message was not settled and the second
-        // message was never processed.
-        assert_eq!(result.events, vec![Event::Handled("permanent".to_string())]);
-    }
-
-    #[test]
-    fn inbox_mode_rejects_message_without_stable_id_before_dispatch() {
-        let result = run(vec![event_message("ok", None)], RunOptions::inbox(()));
-        assert!(result.outcome.is_ok());
-        // Handler never ran (no Handled event); the missing id is a permanent
-        // failure routed to the default dead-letter policy, carrying the reason.
-        assert_eq!(result.events.len(), 1);
-        match &result.events[0] {
-            Event::DeadLetter(reason) => {
-                assert!(reason.contains("stable message id is required but missing"))
-            }
-            other => panic!("expected dead-letter, got {other:?}"),
-        }
-        assert!(!result.events.iter().any(|e| matches!(e, Event::Handled(_))));
-    }
-
-    #[test]
-    fn inbox_mode_dispatches_when_stable_id_is_present() {
-        let result = run(
-            vec![event_message("ok", Some("evt-1"))],
-            RunOptions::inbox(()),
-        );
-        assert!(result.outcome.is_ok());
-        assert_eq!(
-            result.events,
-            vec![Event::Handled("ok".to_string()), Event::Ack]
-        );
-    }
-
-    #[test]
-    fn recv_error_propagates_and_is_not_swallowed() {
-        let result = run_with(
-            vec![event_message("ok", None)],
-            RunOptions::idempotent(),
-            true,
-            true,
-        );
-        let err = result.outcome.expect_err("recv error should propagate");
-        assert!(err.is_retryable());
-        assert!(result.events.is_empty());
-    }
-
-    #[test]
-    fn settle_error_propagates_and_is_not_swallowed() {
-        let result = run_with(
-            vec![event_message("ok", None)],
-            RunOptions::idempotent(),
-            false,
-            false,
-        );
-        let err = result.outcome.expect_err("settle error should propagate");
-        assert!(err.is_retryable());
-        // The ack was attempted (recorded) before the error surfaced.
-        assert_eq!(
-            result.events,
-            vec![Event::Handled("ok".to_string()), Event::Ack]
-        );
-    }
-
-    #[test]
-    fn settle_error_on_failure_path_propagates() {
-        // A settle failure on the nack/failure-routing branch must propagate too,
-        // not just on the ack branch.
-        let result = run_with(
-            vec![event_message("retryable", None)],
-            RunOptions::idempotent(),
-            false,
-            false,
-        );
-        let err = result
-            .outcome
-            .expect_err("nack settle error should propagate");
-        assert!(err.is_retryable());
-        assert_eq!(
-            result.events.first(),
-            Some(&Event::Handled("retryable".to_string()))
-        );
-        assert!(matches!(result.events.get(1), Some(Event::Nack(_))));
-    }
-
-    #[test]
-    fn unhandled_message_is_acked_and_ignored() {
-        // No handler registered for "unrelated": ack-and-ignore, do not dispatch
-        // or dead-letter.
-        let result = run(
-            vec![event_message("unrelated", None), event_message("ok", None)],
-            RunOptions::idempotent(),
-        );
-        assert!(result.outcome.is_ok());
-        assert_eq!(
-            result.events,
-            vec![Event::Ack, Event::Handled("ok".to_string()), Event::Ack]
-        );
-    }
-
-    fn run_decode_error<I: Send>(messages: Vec<Message>, options: RunOptions<I>) -> RunResult {
-        let recorder = Recorder::new();
-        let svc = router(&recorder);
-        let source = FakeSource {
-            queue: messages.into_iter().collect(),
-            recorder: recorder.clone(),
-            settle_ok: true,
-            recv_error: false,
-            decode_error: true,
-        };
-        let outcome = block_on(run_source(svc, source, options));
-        RunResult {
-            outcome,
-            events: recorder.events(),
-        }
-    }
-
-    #[test]
-    fn corrupt_row_dead_letters_under_default_policy_not_acked_and_ignored() {
-        // The corrupt delivery has an unhandled (empty) name, which would
-        // otherwise fall into the ack-and-ignore path and silently drop it. The
-        // decode error must instead route it through the failure policy.
-        let result = run_decode_error(vec![event_message("", None)], RunOptions::idempotent());
-        assert!(result.outcome.is_ok());
-        assert_eq!(result.events.len(), 1);
-        match &result.events[0] {
-            Event::DeadLetter(reason) => assert!(reason.contains("corrupt row")),
-            other => panic!("expected dead-letter, got {other:?}"),
-        }
-        // It was never handled and never plain-acked.
-        assert!(!result.events.iter().any(|e| matches!(e, Event::Handled(_))));
-        assert!(!result.events.contains(&Event::Ack));
-    }
-
-    #[test]
-    fn corrupt_row_parks_under_park_policy() {
-        let result = run_decode_error(
-            vec![event_message("", None)],
-            RunOptions::idempotent().with_failure_policy(FailurePolicy::Park),
-        );
-        assert!(result.outcome.is_ok());
-        assert!(matches!(result.events.first(), Some(Event::Park(_))));
-    }
-
-    #[test]
-    fn corrupt_row_stops_under_stop_policy_with_permanent_error() {
-        let result = run_decode_error(
-            vec![event_message("", None)],
-            RunOptions::idempotent().with_failure_policy(FailurePolicy::Stop),
-        );
-        let err = result
-            .outcome
-            .expect_err("stop policy surfaces the decode error");
-        assert!(err.is_permanent());
-        assert!(
-            result.events.is_empty(),
-            "stop does not settle the corrupt row"
-        );
-    }
-
-    #[test]
-    fn run_source_future_is_send() {
-        // Guards the documented multi-threaded-executor contract for the common
-        // (no-inbox) path: the runner future must be Send.
-        fn assert_send<T: Send>(_: &T) {}
-        let recorder = Recorder::new();
-        let svc = router(&recorder);
-        let source = FakeSource {
-            queue: VecDeque::new(),
-            recorder,
-            settle_ok: true,
-            recv_error: false,
-            decode_error: false,
-        };
-        let future = run_source(svc, source, RunOptions::idempotent());
-        assert_send(&future);
-        // Drive it to completion (empty source -> immediate Ok).
-        assert!(block_on(future).is_ok());
-    }
-
-    // A fake that relies on the trait's DEFAULT dead_letter/park (which forward
-    // to nack), proving the "never silently dropped" degrade-to-redelivery
-    // property of the provided methods.
-    struct DefaultReceived {
-        message: Message,
-        recorder: Arc<Recorder>,
-    }
-
-    impl ReceivedMessage for DefaultReceived {
-        fn message(&self) -> &Message {
-            &self.message
-        }
-        async fn ack(self) -> Result<(), TransportError> {
-            self.recorder.push(Event::Ack);
-            Ok(())
-        }
-        async fn nack(self, reason: &str) -> Result<(), TransportError> {
-            self.recorder.push(Event::Nack(reason.to_string()));
-            Ok(())
-        }
-        // dead_letter and park intentionally NOT overridden.
-    }
-
-    #[test]
-    fn default_dead_letter_and_park_degrade_to_nack() {
-        let recorder = Recorder::new();
-        let dl = DefaultReceived {
-            message: event_message("ok", None),
-            recorder: recorder.clone(),
-        };
-        block_on(dl.dead_letter("boom")).unwrap();
-
-        let park = DefaultReceived {
-            message: event_message("ok", None),
-            recorder: recorder.clone(),
-        };
-        block_on(park.park("hold")).unwrap();
-
-        // Both defaults route to nack rather than dropping the message.
-        assert_eq!(
-            recorder.events(),
-            vec![
-                Event::Nack("boom".to_string()),
-                Event::Nack("hold".to_string())
-            ]
-        );
-    }
-}
diff --git a/src/bus/runner/mod.rs b/src/bus/runner/mod.rs
new file mode 100644
index 00000000..2e105dd0
--- /dev/null
+++ b/src/bus/runner/mod.rs
@@ -0,0 +1,15 @@
+//! The direct-source runner.
+//!
+//! [`run_source`] is the shared receive loop for direct transports. It owns the
+//! cross-cutting policy — when execution counts as successful, how retryable vs
+//! permanent failures are routed — while the adapter owns how acknowledgement
+//! maps back to the transport. The same dispatch/runner boundary is what the
+//! Knative/HTTP ingress will call, so consumer execution stays identical across
+//! ingress shapes.
+
+mod receive_loop;
+
+#[cfg(test)]
+mod tests;
+
+pub use receive_loop::run_source;
diff --git a/src/bus/runner/receive_loop.rs b/src/bus/runner/receive_loop.rs
new file mode 100644
index 00000000..c04ce842
--- /dev/null
+++ b/src/bus/runner/receive_loop.rs
@@ -0,0 +1,383 @@
+use std::future::Future;
+use std::sync::Arc;
+
+use crate::bus::source::{MessageSource, ReceivedMessage};
+use crate::bus::{FailureAction, MessageRouter, RunOptions, TransportError, TransportErrorKind};
+use crate::bus::{Message, MessageKind};
+
+/// Run the receive loop for a direct transport source.
+///
+/// For each message the runner:
+///
+/// 1. enforces the inbox stable-id contract (a no-op in idempotent mode);
+/// 2. dispatches through [`MessageRouter::dispatch`];
+/// 3. on success, acknowledges via the adapter;
+/// 4. on failure, routes through [`RunOptions::failure_policy`] — retryable
+///    failures are nacked for redelivery, permanent failures take the configured
+///    action ([dead-letter](FailureAction::DeadLetter), [park](FailureAction::Park),
+///    [log-and-ack](FailureAction::LogAndAck), or [stop](FailureAction::Stop)).
+///
+/// A message with no registered handler is **intentionally ignored**: the runner
+/// acks it and moves on rather than dead-lettering it. Fan-out event transports
+/// may deliver events this service does not consume, and acking matches
+/// `microsvc::subscribe`; production transports should use
+/// [`MessageRouter::subscription_plan`] to avoid delivering unrelated messages at all.
+///
+/// The runner **acks only after handler effects have completed**, never before.
+/// It stops gracefully when the source returns `Ok(None)`, having fully settled
+/// the in-flight message first. Receive and settle errors are propagated, not
+/// swallowed: a returned `Err` ends the run and the supervisor may restart it
+/// (already-committed effects make redelivery safe).
+///
+/// Inbox note: until the consumer-inbox subtask lands, inbox mode enforces the
+/// stable-id requirement and then dispatches like idempotent mode. The
+/// receipt-commit wrapping that makes it effectively-once is added there.
+///
+/// `I: Send` keeps the returned future `Send` so the runner can be spawned on a
+/// multi-threaded executor regardless of the inbox hook type.
+pub async fn run_source<R, S, I>(
+    router: Arc<R>,
+    mut source: S,
+    options: RunOptions<I>,
+) -> Result<(), TransportError>
+where
+    R: MessageRouter,
+    S: MessageSource,
+    I: Send,
+{
+    let service = router.consumer_group();
+    let transport = source.transport_name();
+
+    loop {
+        let Some(received) = recv_next(&mut source, service, transport).await? else {
+            break;
+        };
+
+        // A delivery the transport could not decode is a permanent failure: it
+        // carries no valid message to dispatch, and it must NOT be treated as an
+        // empty message (which would route to ack-and-ignore below and silently
+        // drop a corrupt row). Route it through the failure policy directly, the
+        // same as a permanent dispatch failure, so it is dead-lettered/parked.
+        if let Some(error) = received.decode_error() {
+            let action = options.failure_policy.resolve(error);
+            record_transport_failure(service, transport, error.kind(), action);
+            let kind = received.message().kind;
+            match action {
+                FailureAction::Nack => {
+                    let reason = error.to_string();
+                    settle_and_record(
+                        service,
+                        transport,
+                        kind,
+                        crate::telemetry::transport_outcome::NACK,
+                        crate::telemetry::transport_outcome::NACK,
+                        || received.nack(&reason),
+                    )
+                    .await?;
+                }
+                FailureAction::DeadLetter => {
+                    let reason = error.to_string();
+                    settle_and_record(
+                        service,
+                        transport,
+                        kind,
+                        crate::telemetry::transport_outcome::DEAD_LETTER,
+                        crate::telemetry::transport_outcome::DEAD_LETTER,
+                        || received.dead_letter(&reason),
+                    )
+                    .await?;
+                }
+                FailureAction::Park => {
+                    let reason = error.to_string();
+                    settle_and_record(
+                        service,
+                        transport,
+                        kind,
+                        crate::telemetry::transport_outcome::PARK,
+                        crate::telemetry::transport_outcome::PARK,
+                        || received.park(&reason),
+                    )
+                    .await?;
+                }
+                FailureAction::LogAndAck => {
+                    eprintln!("[bus::runner] dropping undecodable message after permanent failure: {error}");
+                    settle_and_record(
+                        service,
+                        transport,
+                        kind,
+                        crate::telemetry::transport_outcome::ACK,
+                        crate::telemetry::transport_outcome::LOG_AND_ACK,
+                        || received.ack(),
+                    )
+                    .await?;
+                }
+                FailureAction::Stop => return Err(TransportError::permanent(error.to_string())),
+            }
+            continue;
+        }
+        // No handler for this message: intentionally ignore (ack) rather than
+        // dead-letter, so unrelated fan-out events don't pile into the DLQ.
+        if !router.handles(received.message().kind, received.message().name()) {
+            let kind = received.message().kind;
+            settle_and_record(
+                service,
+                transport,
+                kind,
+                crate::telemetry::transport_outcome::ACK,
+                crate::telemetry::transport_outcome::IGNORED,
+                || received.ack(),
+            )
+            .await?;
+            continue;
+        }
+        let kind = received.message().kind;
+        match dispatch(
+            router.as_ref(),
+            &options,
+            received.message(),
+            received.ordered_delivery(),
+        )
+        .await
+        {
+            Ok(()) => {
+                settle_and_record(
+                    service,
+                    transport,
+                    kind,
+                    crate::telemetry::transport_outcome::ACK,
+                    crate::telemetry::transport_outcome::ACK,
+                    || received.ack(),
+                )
+                .await?;
+            }
+            Err(error) if error.should_retain_and_stop() => {
+                record_transport_failure(
+                    service,
+                    transport,
+                    error.kind(),
+                    crate::telemetry::transport_outcome::NACK,
+                );
+                let reason = error.to_string();
+                settle_and_record(
+                    service,
+                    transport,
+                    kind,
+                    crate::telemetry::transport_outcome::NACK,
+                    crate::telemetry::transport_outcome::NACK,
+                    || received.nack(&reason),
+                )
+                .await?;
+                return Err(error);
+            }
+            Err(error) => match options.failure_policy.resolve(&error) {
+                action @ FailureAction::Nack => {
+                    record_transport_failure(service, transport, error.kind(), action);
+                    let reason = error.to_string();
+                    settle_and_record(
+                        service,
+                        transport,
+                        kind,
+                        crate::telemetry::transport_outcome::NACK,
+                        crate::telemetry::transport_outcome::NACK,
+                        || received.nack(&reason),
+                    )
+                    .await?;
+                }
+                action @ FailureAction::DeadLetter => {
+                    record_transport_failure(service, transport, error.kind(), action);
+                    let reason = error.to_string();
+                    settle_and_record(
+                        service,
+                        transport,
+                        kind,
+                        crate::telemetry::transport_outcome::DEAD_LETTER,
+                        crate::telemetry::transport_outcome::DEAD_LETTER,
+                        || received.dead_letter(&reason),
+                    )
+                    .await?;
+                }
+                action @ FailureAction::Park => {
+                    record_transport_failure(service, transport, error.kind(), action);
+                    let reason = error.to_string();
+                    settle_and_record(
+                        service,
+                        transport,
+                        kind,
+                        crate::telemetry::transport_outcome::PARK,
+                        crate::telemetry::transport_outcome::PARK,
+                        || received.park(&reason),
+                    )
+                    .await?;
+                }
+                FailureAction::LogAndAck => {
+                    record_transport_failure(
+                        service,
+                        transport,
+                        error.kind(),
+                        FailureAction::LogAndAck,
+                    );
+                    eprintln!(
+                        "[bus::runner] dropping message '{}' after permanent failure: {error}",
+                        received.message().name()
+                    );
+                    settle_and_record(
+                        service,
+                        transport,
+                        kind,
+                        crate::telemetry::transport_outcome::ACK,
+                        crate::telemetry::transport_outcome::LOG_AND_ACK,
+                        || received.ack(),
+                    )
+                    .await?;
+                }
+                FailureAction::Stop => {
+                    record_transport_failure(service, transport, error.kind(), FailureAction::Stop);
+                    return Err(error);
+                }
+            },
+        }
+    }
+    Ok(())
+}
+
+async fn settle_and_record<F, Fut>(
+    service: Option<&str>,
+    transport: &str,
+    kind: MessageKind,
+    settle_action: &'static str,
+    outcome: &'static str,
+    settle: F,
+) -> Result<(), TransportError>
+where
+    F: FnOnce() -> Fut,
+    Fut: Future<Output = Result<(), TransportError>>,
+{
+    match settle().await {
+        Ok(()) => {
+            record_transport_message(service, transport, kind, outcome);
+            Ok(())
+        }
+        Err(error) => {
+            record_transport_failure(
+                service,
+                transport,
+                error.kind(),
+                crate::telemetry::settle_failure_action(settle_action),
+            );
+            Err(error)
+        }
+    }
+}
+
+async fn recv_next<S: MessageSource>(
+    source: &mut S,
+    service: Option<&str>,
+    transport: &str,
+) -> Result<Option<S::Received>, TransportError> {
+    match source.recv().await {
+        Ok(received) => Ok(received),
+        Err(error) => {
+            record_transport_failure(
+                service,
+                transport,
+                error.kind(),
+                crate::telemetry::failure_action::RECV_ERROR,
+            );
+            Err(error)
+        }
+    }
+}
+
+/// Run consumer execution for one message and classify the outcome.
+///
+/// Enforces the inbox stable-id contract first (idempotent mode yields no key
+/// and skips it), then dispatches. A failed stable-id check is a permanent
+/// failure — redelivery cannot supply a missing or malformed id.
+async fn dispatch<R: MessageRouter, I>(
+    router: &R,
+    options: &RunOptions<I>,
+    message: &Message,
+    ordered: Option<&crate::bus::OrderedDelivery>,
+) -> Result<(), TransportError> {
+    #[cfg(feature = "otel")]
+    {
+        use tracing::Instrument as _;
+
+        let span = transport_receive_span(message);
+        crate::trace_context::set_span_parent_from_metadata_if_no_current_span(
+            &span,
+            &message.metadata,
+        );
+        return async {
+            options
+                .validate_message_id(message)
+                .map_err(|err| TransportError::permanent(err.to_string()).with_source(err))?;
+            router.dispatch_ordered(message, ordered).await
+        }
+        .instrument(span)
+        .await;
+    }
+
+    #[cfg(not(feature = "otel"))]
+    {
+        options
+            .validate_message_id(message)
+            .map_err(|err| TransportError::permanent(err.to_string()).with_source(err))?;
+        router.dispatch_ordered(message, ordered).await
+    }
+}
+
+#[cfg(feature = "otel")]
+fn transport_receive_span(message: &Message) -> tracing::Span {
+    crate::telemetry::transport_receive_span(message)
+}
+
+fn record_transport_message(
+    service: Option<&str>,
+    transport: &str,
+    kind: MessageKind,
+    outcome: &str,
+) {
+    #[cfg(feature = "metrics")]
+    crate::metrics::record_transport_message(service, transport, kind, outcome);
+    #[cfg(not(feature = "metrics"))]
+    let _ = (service, transport, kind, outcome);
+}
+
+fn record_transport_failure<A>(
+    service: Option<&str>,
+    transport: &str,
+    kind: TransportErrorKind,
+    action: A,
+) where
+    A: IntoFailureActionLabel,
+{
+    #[cfg(feature = "metrics")]
+    crate::metrics::record_transport_failure(
+        service,
+        transport,
+        crate::telemetry::transport_failure_class(kind),
+        action.into_failure_action_label(),
+    );
+    #[cfg(not(feature = "metrics"))]
+    {
+        let _ = (service, transport, kind);
+        let _ = action.into_failure_action_label();
+    }
+}
+
+trait IntoFailureActionLabel {
+    fn into_failure_action_label(self) -> &'static str;
+}
+
+impl IntoFailureActionLabel for FailureAction {
+    fn into_failure_action_label(self) -> &'static str {
+        crate::telemetry::failure_action_label(self)
+    }
+}
+
+impl IntoFailureActionLabel for &'static str {
+    fn into_failure_action_label(self) -> &'static str {
+        self
+    }
+}
diff --git a/src/bus/runner/tests.rs b/src/bus/runner/tests.rs
new file mode 100644
index 00000000..a31074c2
--- /dev/null
+++ b/src/bus/runner/tests.rs
@@ -0,0 +1,649 @@
+use super::run_source;
+use crate::bus::source::{MessageSource, ReceivedMessage};
+use crate::bus::{FailurePolicy, Handlers, Message, MessageKind, RunOptions, TransportError};
+use std::collections::VecDeque;
+use std::future::Future;
+use std::sync::{Arc, Mutex};
+
+// --- minimal runtime-free executor -------------------------------------
+// The transport module is not feature-gated, so its tests run without an
+// async runtime. The fake futures never suspend, so a busy-poll with a
+// no-op waker drives them to completion.
+fn block_on<F: Future>(future: F) -> F::Output {
+    use std::ptr;
+    use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
+
+    const VTABLE: RawWakerVTable = RawWakerVTable::new(
+        |_| RawWaker::new(ptr::null(), &VTABLE),
+        |_| {},
+        |_| {},
+        |_| {},
+    );
+    let raw = RawWaker::new(ptr::null(), &VTABLE);
+    let waker = unsafe { Waker::from_raw(raw) };
+    let mut cx = Context::from_waker(&waker);
+    let mut future = std::pin::pin!(future);
+    loop {
+        if let Poll::Ready(output) = future.as_mut().poll(&mut cx) {
+            return output;
+        }
+    }
+}
+
+// --- recorder + fakes ---------------------------------------------------
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum Event {
+    Handled(String),
+    Ack,
+    Nack(String),
+    DeadLetter(String),
+    Park(String),
+}
+
+struct Recorder {
+    events: Mutex<Vec<Event>>,
+}
+
+impl Recorder {
+    fn new() -> Arc<Self> {
+        Arc::new(Self {
+            events: Mutex::new(Vec::new()),
+        })
+    }
+    fn push(&self, event: Event) {
+        self.events.lock().unwrap().push(event);
+    }
+    fn events(&self) -> Vec<Event> {
+        self.events.lock().unwrap().clone()
+    }
+}
+
+struct FakeReceived {
+    message: Message,
+    recorder: Arc<Recorder>,
+    settle_ok: bool,
+    decode_error: Option<TransportError>,
+}
+
+impl FakeReceived {
+    fn settle(self, event: Event) -> Result<(), TransportError> {
+        self.recorder.push(event);
+        if self.settle_ok {
+            Ok(())
+        } else {
+            Err(TransportError::retryable("settle failed"))
+        }
+    }
+}
+
+impl ReceivedMessage for FakeReceived {
+    fn message(&self) -> &Message {
+        &self.message
+    }
+    fn decode_error(&self) -> Option<&TransportError> {
+        self.decode_error.as_ref()
+    }
+    async fn ack(self) -> Result<(), TransportError> {
+        self.settle(Event::Ack)
+    }
+    async fn nack(self, reason: &str) -> Result<(), TransportError> {
+        self.settle(Event::Nack(reason.to_string()))
+    }
+    async fn dead_letter(self, reason: &str) -> Result<(), TransportError> {
+        self.settle(Event::DeadLetter(reason.to_string()))
+    }
+    async fn park(self, reason: &str) -> Result<(), TransportError> {
+        self.settle(Event::Park(reason.to_string()))
+    }
+}
+
+struct FakeSource {
+    queue: VecDeque<Message>,
+    recorder: Arc<Recorder>,
+    settle_ok: bool,
+    recv_error: bool,
+    // When set, every received message reports this as a decode failure,
+    // modeling a transport that claims a row/offset before decoding it.
+    decode_error: bool,
+}
+
+impl MessageSource for FakeSource {
+    type Received = FakeReceived;
+    async fn recv(&mut self) -> Result<Option<FakeReceived>, TransportError> {
+        if self.recv_error {
+            return Err(TransportError::retryable("recv failed"));
+        }
+        let decode_error = self.decode_error;
+        Ok(self.queue.pop_front().map(|message| FakeReceived {
+            message,
+            recorder: self.recorder.clone(),
+            settle_ok: self.settle_ok,
+            decode_error: decode_error
+                .then(|| TransportError::permanent("corrupt row: name failed to decode")),
+        }))
+    }
+}
+
+// --- helpers ------------------------------------------------------------
+fn event_message(name: &str, id: Option<&str>) -> Message {
+    let mut message = Message::new(name, MessageKind::Event, b"{}".to_vec());
+    if let Some(id) = id {
+        message = message.with_id(id);
+    }
+    message
+}
+
+fn router(recorder: &Arc<Recorder>) -> Arc<Handlers> {
+    let ok = recorder.clone();
+    let retryable = recorder.clone();
+    let permanent = recorder.clone();
+    let terminal = recorder.clone();
+    Arc::new(
+        Handlers::new()
+            .on_event("ok", move |msg: &Message| {
+                let ok = ok.clone();
+                let name = msg.name().to_string();
+                async move {
+                    ok.push(Event::Handled(name));
+                    Ok(())
+                }
+            })
+            .on_event("retryable", move |msg: &Message| {
+                let retryable = retryable.clone();
+                let name = msg.name().to_string();
+                async move {
+                    retryable.push(Event::Handled(name));
+                    Err(TransportError::retryable("infra"))
+                }
+            })
+            .on_event("permanent", move |msg: &Message| {
+                let permanent = permanent.clone();
+                let name = msg.name().to_string();
+                async move {
+                    permanent.push(Event::Handled(name));
+                    Err(TransportError::permanent("nope"))
+                }
+            })
+            .on_event("terminal", move |msg: &Message| {
+                let terminal = terminal.clone();
+                let name = msg.name().to_string();
+                async move {
+                    terminal.push(Event::Handled(name));
+                    Err(TransportError::permanent("durable projection failure").retain_and_stop())
+                }
+            }),
+    )
+}
+
+struct RunResult {
+    outcome: Result<(), TransportError>,
+    events: Vec<Event>,
+}
+
+fn run<I: Send>(messages: Vec<Message>, options: RunOptions<I>) -> RunResult {
+    run_with(messages, options, true, false)
+}
+
+fn run_with<I: Send>(
+    messages: Vec<Message>,
+    options: RunOptions<I>,
+    settle_ok: bool,
+    recv_error: bool,
+) -> RunResult {
+    let recorder = Recorder::new();
+    let svc = router(&recorder);
+    let source = FakeSource {
+        queue: messages.into_iter().collect(),
+        recorder: recorder.clone(),
+        settle_ok,
+        recv_error,
+        decode_error: false,
+    };
+    let outcome = block_on(run_source(svc, source, options));
+    RunResult {
+        outcome,
+        events: recorder.events(),
+    }
+}
+
+// --- tests --------------------------------------------------------------
+#[test]
+fn success_dispatches_then_acks_in_order() {
+    let result = run(vec![event_message("ok", None)], RunOptions::idempotent());
+    assert!(result.outcome.is_ok());
+    // Handler effect is recorded before the ack: ack happens after success.
+    assert_eq!(
+        result.events,
+        vec![Event::Handled("ok".to_string()), Event::Ack]
+    );
+}
+
+#[test]
+fn processes_every_message_then_stops_on_none() {
+    let result = run(
+        vec![event_message("ok", None), event_message("ok", None)],
+        RunOptions::idempotent(),
+    );
+    assert!(result.outcome.is_ok());
+    assert_eq!(
+        result.events,
+        vec![
+            Event::Handled("ok".to_string()),
+            Event::Ack,
+            Event::Handled("ok".to_string()),
+            Event::Ack,
+        ]
+    );
+}
+
+#[cfg(feature = "metrics")]
+#[test]
+fn metrics_record_success_and_failure_settlement_outcomes() {
+    let _guard = crate::metrics::lock_for_tests();
+    crate::metrics::reset_for_tests();
+
+    let recorder = Recorder::new();
+    let svc = Arc::new(
+        router(&recorder)
+            .as_ref()
+            .clone()
+            .named("metrics-runner-settlement"),
+    );
+    let source = FakeSource {
+        queue: vec![event_message("ok", None), event_message("retryable", None)]
+            .into_iter()
+            .collect(),
+        recorder,
+        settle_ok: true,
+        recv_error: false,
+        decode_error: false,
+    };
+
+    let outcome = block_on(run_source(svc, source, RunOptions::idempotent()));
+    assert!(outcome.is_ok());
+
+    let text = crate::metrics::prometheus_text();
+    assert!(
+            text.contains(
+                "distributed_transport_messages_total{service=\"metrics-runner-settlement\",transport=\"unknown\",message_kind=\"event\",outcome=\"ack\"} 1"
+            ),
+            "metrics should include the ack outcome:\n{text}"
+        );
+    assert!(
+            text.contains(
+                "distributed_transport_messages_total{service=\"metrics-runner-settlement\",transport=\"unknown\",message_kind=\"event\",outcome=\"nack\"} 1"
+            ),
+            "metrics should include the nack outcome:\n{text}"
+        );
+    assert!(
+            text.contains(
+                "distributed_transport_failures_total{service=\"metrics-runner-settlement\",transport=\"unknown\",failure_class=\"retryable\",action=\"nack\"} 1"
+            ),
+            "metrics should include the retryable failure action:\n{text}"
+        );
+}
+
+#[cfg(feature = "metrics")]
+#[test]
+fn metrics_record_settle_failures_before_propagating() {
+    let _guard = crate::metrics::lock_for_tests();
+    crate::metrics::reset_for_tests();
+
+    let recorder = Recorder::new();
+    let svc = Arc::new(
+        router(&recorder)
+            .as_ref()
+            .clone()
+            .named("metrics-runner-settle-failure"),
+    );
+    let source = FakeSource {
+        queue: vec![event_message("ok", None)].into_iter().collect(),
+        recorder,
+        settle_ok: false,
+        recv_error: false,
+        decode_error: false,
+    };
+
+    let outcome = block_on(run_source(svc, source, RunOptions::idempotent()));
+    assert!(outcome
+        .expect_err("settle error should propagate")
+        .is_retryable());
+
+    let text = crate::metrics::prometheus_text();
+    assert!(
+            text.contains(
+                "distributed_transport_failures_total{service=\"metrics-runner-settle-failure\",transport=\"unknown\",failure_class=\"retryable\",action=\"settle_ack\"} 1"
+            ),
+            "metrics should include the settle failure:\n{text}"
+        );
+    assert!(
+            !text.contains(
+                "distributed_transport_messages_total{service=\"metrics-runner-settle-failure\",transport=\"unknown\",message_kind=\"event\",outcome=\"ack\"} 1"
+            ),
+            "settle failure should not record an ack outcome:\n{text}"
+        );
+}
+
+#[test]
+fn retryable_failure_nacks_without_acking() {
+    let result = run(
+        vec![event_message("retryable", None)],
+        RunOptions::idempotent(),
+    );
+    assert!(result.outcome.is_ok());
+    assert_eq!(
+        result.events.first(),
+        Some(&Event::Handled("retryable".to_string()))
+    );
+    assert!(matches!(result.events.get(1), Some(Event::Nack(_))));
+    assert!(!result.events.contains(&Event::Ack));
+}
+
+#[test]
+fn permanent_failure_dead_letters_under_default_policy() {
+    let result = run(
+        vec![event_message("permanent", None)],
+        RunOptions::idempotent(),
+    );
+    assert!(result.outcome.is_ok());
+    assert_eq!(
+        result.events.first(),
+        Some(&Event::Handled("permanent".to_string()))
+    );
+    assert!(matches!(result.events.get(1), Some(Event::DeadLetter(_))));
+}
+
+#[test]
+fn permanent_failure_parks_under_park_policy() {
+    let result = run(
+        vec![event_message("permanent", None)],
+        RunOptions::idempotent().with_failure_policy(FailurePolicy::Park),
+    );
+    assert!(result.outcome.is_ok());
+    assert!(matches!(result.events.get(1), Some(Event::Park(_))));
+}
+
+#[test]
+fn permanent_failure_logs_and_acks_under_log_and_ack_policy() {
+    let result = run(
+        vec![event_message("permanent", None)],
+        RunOptions::idempotent().with_failure_policy(FailurePolicy::LogAndAck),
+    );
+    assert!(result.outcome.is_ok());
+    assert_eq!(result.events.get(1), Some(&Event::Ack));
+}
+
+#[test]
+fn durable_terminal_failure_nacks_and_stops_regardless_of_permanent_policy() {
+    for policy in [FailurePolicy::DeadLetter, FailurePolicy::LogAndAck] {
+        let result = run(
+            vec![event_message("terminal", None), event_message("ok", None)],
+            RunOptions::idempotent().with_failure_policy(policy),
+        );
+        let error = result
+            .outcome
+            .expect_err("durable terminal failure must stop the runner");
+        assert!(error.is_permanent());
+        assert!(error.should_retain_and_stop());
+        assert_eq!(
+            result.events.first(),
+            Some(&Event::Handled("terminal".to_string()))
+        );
+        assert!(
+            matches!(result.events.get(1), Some(Event::Nack(reason)) if reason.contains("durable projection failure"))
+        );
+        assert_eq!(
+            result.events.len(),
+            2,
+            "{policy:?} must neither settle terminal input destructively nor continue"
+        );
+    }
+}
+
+#[test]
+fn permanent_failure_nacks_under_retry_policy() {
+    let result = run(
+        vec![event_message("permanent", None)],
+        RunOptions::idempotent().with_failure_policy(FailurePolicy::Retry),
+    );
+    assert!(result.outcome.is_ok());
+    assert!(matches!(result.events.get(1), Some(Event::Nack(_))));
+}
+
+#[test]
+fn stop_policy_returns_error_without_settling() {
+    let result = run(
+        vec![event_message("permanent", None), event_message("ok", None)],
+        RunOptions::idempotent().with_failure_policy(FailurePolicy::Stop),
+    );
+    let err = result
+        .outcome
+        .expect_err("stop policy should surface the error");
+    assert!(err.is_permanent());
+    // The handler ran, but the message was not settled and the second
+    // message was never processed.
+    assert_eq!(result.events, vec![Event::Handled("permanent".to_string())]);
+}
+
+#[test]
+fn inbox_mode_rejects_message_without_stable_id_before_dispatch() {
+    let result = run(vec![event_message("ok", None)], RunOptions::inbox(()));
+    assert!(result.outcome.is_ok());
+    // Handler never ran (no Handled event); the missing id is a permanent
+    // failure routed to the default dead-letter policy, carrying the reason.
+    assert_eq!(result.events.len(), 1);
+    match &result.events[0] {
+        Event::DeadLetter(reason) => {
+            assert!(reason.contains("stable message id is required but missing"))
+        }
+        other => panic!("expected dead-letter, got {other:?}"),
+    }
+    assert!(!result.events.iter().any(|e| matches!(e, Event::Handled(_))));
+}
+
+#[test]
+fn inbox_mode_dispatches_when_stable_id_is_present() {
+    let result = run(
+        vec![event_message("ok", Some("evt-1"))],
+        RunOptions::inbox(()),
+    );
+    assert!(result.outcome.is_ok());
+    assert_eq!(
+        result.events,
+        vec![Event::Handled("ok".to_string()), Event::Ack]
+    );
+}
+
+#[test]
+fn recv_error_propagates_and_is_not_swallowed() {
+    let result = run_with(
+        vec![event_message("ok", None)],
+        RunOptions::idempotent(),
+        true,
+        true,
+    );
+    let err = result.outcome.expect_err("recv error should propagate");
+    assert!(err.is_retryable());
+    assert!(result.events.is_empty());
+}
+
+#[test]
+fn settle_error_propagates_and_is_not_swallowed() {
+    let result = run_with(
+        vec![event_message("ok", None)],
+        RunOptions::idempotent(),
+        false,
+        false,
+    );
+    let err = result.outcome.expect_err("settle error should propagate");
+    assert!(err.is_retryable());
+    // The ack was attempted (recorded) before the error surfaced.
+    assert_eq!(
+        result.events,
+        vec![Event::Handled("ok".to_string()), Event::Ack]
+    );
+}
+
+#[test]
+fn settle_error_on_failure_path_propagates() {
+    // A settle failure on the nack/failure-routing branch must propagate too,
+    // not just on the ack branch.
+    let result = run_with(
+        vec![event_message("retryable", None)],
+        RunOptions::idempotent(),
+        false,
+        false,
+    );
+    let err = result
+        .outcome
+        .expect_err("nack settle error should propagate");
+    assert!(err.is_retryable());
+    assert_eq!(
+        result.events.first(),
+        Some(&Event::Handled("retryable".to_string()))
+    );
+    assert!(matches!(result.events.get(1), Some(Event::Nack(_))));
+}
+
+#[test]
+fn unhandled_message_is_acked_and_ignored() {
+    // No handler registered for "unrelated": ack-and-ignore, do not dispatch
+    // or dead-letter.
+    let result = run(
+        vec![event_message("unrelated", None), event_message("ok", None)],
+        RunOptions::idempotent(),
+    );
+    assert!(result.outcome.is_ok());
+    assert_eq!(
+        result.events,
+        vec![Event::Ack, Event::Handled("ok".to_string()), Event::Ack]
+    );
+}
+
+fn run_decode_error<I: Send>(messages: Vec<Message>, options: RunOptions<I>) -> RunResult {
+    let recorder = Recorder::new();
+    let svc = router(&recorder);
+    let source = FakeSource {
+        queue: messages.into_iter().collect(),
+        recorder: recorder.clone(),
+        settle_ok: true,
+        recv_error: false,
+        decode_error: true,
+    };
+    let outcome = block_on(run_source(svc, source, options));
+    RunResult {
+        outcome,
+        events: recorder.events(),
+    }
+}
+
+#[test]
+fn corrupt_row_dead_letters_under_default_policy_not_acked_and_ignored() {
+    // The corrupt delivery has an unhandled (empty) name, which would
+    // otherwise fall into the ack-and-ignore path and silently drop it. The
+    // decode error must instead route it through the failure policy.
+    let result = run_decode_error(vec![event_message("", None)], RunOptions::idempotent());
+    assert!(result.outcome.is_ok());
+    assert_eq!(result.events.len(), 1);
+    match &result.events[0] {
+        Event::DeadLetter(reason) => assert!(reason.contains("corrupt row")),
+        other => panic!("expected dead-letter, got {other:?}"),
+    }
+    // It was never handled and never plain-acked.
+    assert!(!result.events.iter().any(|e| matches!(e, Event::Handled(_))));
+    assert!(!result.events.contains(&Event::Ack));
+}
+
+#[test]
+fn corrupt_row_parks_under_park_policy() {
+    let result = run_decode_error(
+        vec![event_message("", None)],
+        RunOptions::idempotent().with_failure_policy(FailurePolicy::Park),
+    );
+    assert!(result.outcome.is_ok());
+    assert!(matches!(result.events.first(), Some(Event::Park(_))));
+}
+
+#[test]
+fn corrupt_row_stops_under_stop_policy_with_permanent_error() {
+    let result = run_decode_error(
+        vec![event_message("", None)],
+        RunOptions::idempotent().with_failure_policy(FailurePolicy::Stop),
+    );
+    let err = result
+        .outcome
+        .expect_err("stop policy surfaces the decode error");
+    assert!(err.is_permanent());
+    assert!(
+        result.events.is_empty(),
+        "stop does not settle the corrupt row"
+    );
+}
+
+#[test]
+fn run_source_future_is_send() {
+    // Guards the documented multi-threaded-executor contract for the common
+    // (no-inbox) path: the runner future must be Send.
+    fn assert_send<T: Send>(_: &T) {}
+    let recorder = Recorder::new();
+    let svc = router(&recorder);
+    let source = FakeSource {
+        queue: VecDeque::new(),
+        recorder,
+        settle_ok: true,
+        recv_error: false,
+        decode_error: false,
+    };
+    let future = run_source(svc, source, RunOptions::idempotent());
+    assert_send(&future);
+    // Drive it to completion (empty source -> immediate Ok).
+    assert!(block_on(future).is_ok());
+}
+
+// A fake that relies on the trait's DEFAULT dead_letter/park (which forward
+// to nack), proving the "never silently dropped" degrade-to-redelivery
+// property of the provided methods.
+struct DefaultReceived {
+    message: Message,
+    recorder: Arc<Recorder>,
+}
+
+impl ReceivedMessage for DefaultReceived {
+    fn message(&self) -> &Message {
+        &self.message
+    }
+    async fn ack(self) -> Result<(), TransportError> {
+        self.recorder.push(Event::Ack);
+        Ok(())
+    }
+    async fn nack(self, reason: &str) -> Result<(), TransportError> {
+        self.recorder.push(Event::Nack(reason.to_string()));
+        Ok(())
+    }
+    // dead_letter and park intentionally NOT overridden.
+}
+
+#[test]
+fn default_dead_letter_and_park_degrade_to_nack() {
+    let recorder = Recorder::new();
+    let dl = DefaultReceived {
+        message: event_message("ok", None),
+        recorder: recorder.clone(),
+    };
+    block_on(dl.dead_letter("boom")).unwrap();
+
+    let park = DefaultReceived {
+        message: event_message("ok", None),
+        recorder: recorder.clone(),
+    };
+    block_on(park.park("hold")).unwrap();
+
+    // Both defaults route to nack rather than dropping the message.
+    assert_eq!(
+        recorder.events(),
+        vec![
+            Event::Nack("boom".to_string()),
+            Event::Nack("hold".to_string())
+        ]
+    );
+}
diff --git a/src/bus/source.rs b/src/bus/source.rs
index 08b74cde..a96c10bb 100644
--- a/src/bus/source.rs
+++ b/src/bus/source.rs
@@ -12,7 +12,7 @@
 
 use std::future::Future;
 
-use super::{Message, TransportError};
+use super::{Message, OrderedDelivery, TransportError};
 
 /// A transport a runner can pull messages from, one at a time.
 ///
@@ -51,6 +51,17 @@ pub trait ReceivedMessage: Send {
     /// The canonical message to dispatch.
     fn message(&self) -> &Message;
 
+    /// Adapter-authenticated ordered source position for causal projection.
+    ///
+    /// The default is deliberately unqualified. A source must override this
+    /// only when it has a durable numeric source position and an explicit epoch;
+    /// delivery tags, attempts, timestamps, UUIDs, and arrival order do not
+    /// qualify. The runner forwards this sealed value separately from message
+    /// metadata.
+    fn ordered_delivery(&self) -> Option<&OrderedDelivery> {
+        None
+    }
+
     /// A permanent decode failure for this delivery, if the transport could not
     /// reconstruct the message from its stored representation.
     ///
diff --git a/src/bus/sql_bus_common.rs b/src/bus/sql_bus_common.rs
index 0497b02e..5c3a689e 100644
--- a/src/bus/sql_bus_common.rs
+++ b/src/bus/sql_bus_common.rs
@@ -2,7 +2,8 @@
 //!
 //! Postgres and SQLite implement the same bus model — a claim-lease work queue
 //! (`bus_queue`) for point-to-point commands, and an append-only log plus a
-//! per-consumer offset table (`bus_log` + `bus_offset`) for fan-out events.
+//! durable generation identity and per-consumer offset table (`bus_log` +
+//! `bus_log_identity` + `bus_offset`) for fan-out events.
 //! They differ only in SQL dialect (placeholder style, database clock,
 //! name-list binding, claim-token minting) and pool type. Mirroring
 //! [`lock::sqlx_common`](crate::lock), everything else — the builders, the
@@ -38,12 +39,13 @@ use std::time::Duration;
 
 use sqlx::{ColumnIndex, Decode, Row, Type};
 
+use crate::projection_protocol::{ProjectionEpoch, ProjectionSource};
 use crate::sqlx_repo::is_sqlx_transient;
 
 use super::source::{MessageSource, ReceivedMessage};
 use super::{
-    run_source, Bus, BusConsumer, BusTopologyConfig, MessageRouter, RunOptions, TransportError,
-    TransportErrorKind,
+    run_source, Bus, BusConsumer, BusTopologyConfig, MessageRouter, OrderedDelivery, RunOptions,
+    TransportError, TransportErrorKind,
 };
 use super::{Message, MessageKind};
 
@@ -108,7 +110,7 @@ fn parse_metadata(backend: &str, value: &str) -> Result<Vec<(String, String)>, T
 /// already been selected or claimed, so callers surface the error through
 /// [`ReceivedMessage::decode_error`] and let the runner settle it through the
 /// configured failure policy.
-fn message_from_row<R>(backend: &str, row: &R) -> Result<Message, TransportError>
+pub(crate) fn message_from_row<R>(backend: &str, row: &R) -> Result<Message, TransportError>
 where
     R: Row,
     for<'a> &'a str: ColumnIndex<R>,
@@ -150,6 +152,39 @@ where
     })
 }
 
+/// Verify that a retry using an existing stable message ID still names the
+/// exact envelope a causal projector observes.
+///
+/// Trace metadata is deliberately excluded: an outbox retry may acquire a new
+/// span after an ambiguous publish acknowledgement. Causation is included
+/// because it is part of projection receipt identity. The first committed row
+/// remains authoritative for all other metadata.
+pub(crate) fn validate_log_retry(
+    backend: &str,
+    existing: &Message,
+    retry: &Message,
+) -> Result<(), TransportError> {
+    let matches = existing.name == retry.name
+        && existing.kind == retry.kind
+        && existing.payload == retry.payload
+        && existing.content_type == retry.content_type
+        && existing.causation_id() == retry.causation_id();
+    if matches {
+        return Ok(());
+    }
+
+    Err(TransportError::permanent(format!(
+        "{backend} bus ordered-log message ID {:?} was reused with a different \
+         name, kind, payload, content type, or causation ID",
+        retry.id()
+    )))
+}
+
+fn fresh_log_epoch() -> ProjectionEpoch {
+    ProjectionEpoch::new(format!("sql-log-{}", uuid::Uuid::now_v7()))
+        .expect("a UUID-backed SQL log epoch is valid")
+}
+
 /// A decoded `bus_queue`/`bus_log` row: its `seq` plus either the message or the
 /// decode failure (with an empty placeholder message the runner never
 /// dispatches — it sees `decode_error()` first).
@@ -199,7 +234,7 @@ pub struct ClaimedRow {
 pub trait SqlBusDialect: Clone + Send + Sync + 'static {
     /// Backend name used in error messages and consumer-group resolution.
     const BACKEND: &'static str;
-    /// Idempotent DDL for `bus_queue`/`bus_log`/`bus_offset`, `;`-separated.
+    /// Idempotent DDL for the queue, log, log identity, and offsets.
     const SCHEMA: &'static str;
 
     /// Execute one DDL statement from [`SCHEMA`](Self::SCHEMA) (hence
@@ -209,6 +244,15 @@ pub trait SqlBusDialect: Clone + Send + Sync + 'static {
         statement: &'static str,
     ) -> impl Future<Output = Result<(), TransportError>> + Send;
 
+    /// Upgrade legacy ordered-log state and install the stable message-ID
+    /// uniqueness fence.
+    ///
+    /// Implementations must perform duplicate validation/deduplication and
+    /// unique-index creation atomically. They also migrate offsets to carry the
+    /// cursor epoch, discarding legacy offsets that cannot be attributed to a
+    /// durable generation.
+    fn ensure_ordered_log_schema(&self) -> impl Future<Output = Result<(), TransportError>> + Send;
+
     /// Insert a command into `bus_queue`.
     fn insert_queue(
         &self,
@@ -219,6 +263,33 @@ pub trait SqlBusDialect: Clone + Send + Sync + 'static {
     fn insert_log(
         &self,
         message: &Message,
+        epoch_candidate: &ProjectionEpoch,
+        expected_epoch: Option<&ProjectionEpoch>,
+    ) -> impl Future<Output = Result<(), TransportError>> + Send;
+
+    /// Load the epoch durably paired with `bus_log`, creating it from
+    /// `epoch_candidate` when this is a new log.
+    ///
+    /// Implementations also detect one specific continuity violation: an
+    /// observed `MAX(seq)` below the persisted high-water mark. That condition
+    /// fails closed; a caller-provided candidate is never authorization to
+    /// rotate an existing cursor domain.
+    fn prepare_log_epoch(
+        &self,
+        epoch_candidate: &ProjectionEpoch,
+        expected_epoch: Option<&ProjectionEpoch>,
+    ) -> impl Future<Output = Result<ProjectionEpoch, TransportError>> + Send;
+
+    /// Compare-and-swap reset of the ordered log and its cursor domain.
+    ///
+    /// Implementations lock the current identity, verify `expected_epoch`,
+    /// clear the log and every offset, reset the backend sequence, and install
+    /// the distinct `next_epoch` with generation incremented and high-water
+    /// zero in one transaction.
+    fn reset_log(
+        &self,
+        expected_epoch: &ProjectionEpoch,
+        next_epoch: &ProjectionEpoch,
     ) -> impl Future<Output = Result<(), TransportError>> + Send;
 
     /// Atomically claim up to `limit` available `bus_queue` rows (lowest `seq`
@@ -242,8 +313,16 @@ pub trait SqlBusDialect: Clone + Send + Sync + 'static {
         names: &[String],
         consumer: &str,
         limit: i64,
+        expected_epoch: &ProjectionEpoch,
     ) -> impl Future<Output = Result<Vec<ReceivedRow>, TransportError>> + Send;
 
+    /// Fail unless `expected_epoch` is still the durable identity paired with
+    /// the current log generation.
+    fn verify_log_epoch(
+        &self,
+        expected_epoch: &ProjectionEpoch,
+    ) -> impl Future<Output = Result<(), TransportError>> + Send;
+
     /// Delete a claimed queue row, fenced by its claim token.
     fn delete_claimed(
         &self,
@@ -263,6 +342,7 @@ pub trait SqlBusDialect: Clone + Send + Sync + 'static {
         &self,
         consumer: &str,
         seq: i64,
+        expected_epoch: &ProjectionEpoch,
     ) -> impl Future<Output = Result<(), TransportError>> + Send;
 }
 
@@ -273,6 +353,7 @@ pub struct SqlBus<B> {
     dialect: B,
     topology: BusTopologyConfig,
     lease: Duration,
+    source_epoch: Option<ProjectionEpoch>,
 }
 
 impl<B: SqlBusDialect> SqlBus<B> {
@@ -281,6 +362,7 @@ impl<B: SqlBusDialect> SqlBus<B> {
             dialect,
             topology: BusTopologyConfig::default(),
             lease: DEFAULT_LEASE,
+            source_epoch: None,
         }
     }
 
@@ -297,7 +379,20 @@ impl<B: SqlBusDialect> SqlBus<B> {
         self
     }
 
-    /// Create the bus tables (`bus_queue`, `bus_log`, `bus_offset`) if absent.
+    /// Require an operator-controlled epoch for this append-only bus log.
+    ///
+    /// On a new empty log this value becomes its durable identity. It is also
+    /// required to explicitly adopt a retained nonempty log whose identity was
+    /// lost; adoption invalidates offsets that cannot be bound to the supplied
+    /// epoch. On an existing generation it must exactly match the persisted
+    /// identity. A builder can never relabel an identified generation or
+    /// authorize a reset.
+    pub fn with_source_epoch(mut self, epoch: ProjectionEpoch) -> Self {
+        self.source_epoch = Some(epoch);
+        self
+    }
+
+    /// Create the bus tables (queue, log, log identity, and offsets) if absent.
     ///
     /// Called by `listen`/`subscribe`; producers must ensure the tables exist
     /// before `send`/`publish`, either by calling this or through migrations.
@@ -309,8 +404,43 @@ impl<B: SqlBusDialect> SqlBus<B> {
             }
             self.dialect.execute_ddl(statement).await?;
         }
+        self.dialect.ensure_ordered_log_schema().await?;
+        // Persist the identity beside the log even for producer-only setups.
+        // Backups and explicit resets must treat `bus_log` and
+        // `bus_log_identity` as one unit.
+        let epoch_candidate = self.source_epoch.clone().unwrap_or_else(fresh_log_epoch);
+        self.dialect
+            .prepare_log_epoch(&epoch_candidate, self.source_epoch.as_ref())
+            .await?;
         Ok(())
     }
+
+    /// Destructively begin a new ordered-log cursor generation.
+    ///
+    /// This is the only supported way to reuse numeric `bus_log` positions.
+    /// It is fenced like compare-and-swap: `expected_epoch` must still be the
+    /// durable identity, and `next_epoch` must be distinct. On success the log,
+    /// backend sequence, and every consumer offset are cleared atomically while
+    /// the generation is incremented and the high-water mark returns to zero.
+    ///
+    /// A handler already dispatched from the retired generation cannot be
+    /// cancelled or have its application effects rolled back by this call.
+    /// Its later offset settlement is epoch-fenced and fails permanently; the
+    /// operator must stop consumers before reset and restart them against the
+    /// new generation. Projection handlers should still commit effects and
+    /// their own idempotency/checkpoint state transactionally.
+    pub async fn reset_ordered_log(
+        &self,
+        expected_epoch: &ProjectionEpoch,
+        next_epoch: &ProjectionEpoch,
+    ) -> Result<(), TransportError> {
+        if expected_epoch == next_epoch {
+            return Err(TransportError::permanent(
+                "ordered-log reset requires a distinct next epoch",
+            ));
+        }
+        self.dialect.reset_log(expected_epoch, next_epoch).await
+    }
 }
 
 impl<B: SqlBusDialect> Bus for SqlBus<B> {
@@ -319,7 +449,10 @@ impl<B: SqlBusDialect> Bus for SqlBus<B> {
     }
 
     async fn publish_message(&self, message: Message) -> Result<(), TransportError> {
-        self.dialect.insert_log(&message).await
+        let epoch_candidate = self.source_epoch.clone().unwrap_or_else(fresh_log_epoch);
+        self.dialect
+            .insert_log(&message, &epoch_candidate, self.source_epoch.as_ref())
+            .await
     }
 }
 
@@ -356,6 +489,11 @@ impl<B: SqlBusDialect> BusConsumer for SqlBus<B> {
         let group = self
             .topology
             .resolve_consumer_group(router.as_ref(), B::BACKEND)?;
+        let epoch_candidate = self.source_epoch.clone().unwrap_or_else(fresh_log_epoch);
+        let source_epoch = self
+            .dialect
+            .prepare_log_epoch(&epoch_candidate, self.source_epoch.as_ref())
+            .await?;
         let source = SqlLogSource {
             dialect: self.dialect.clone(),
             names,
@@ -363,6 +501,7 @@ impl<B: SqlBusDialect> BusConsumer for SqlBus<B> {
             buffer: VecDeque::new(),
             last_delivered: None,
             settled_seq: Arc::new(AtomicI64::new(0)),
+            source_epoch,
         };
         run_source(router, source, options).await
     }
@@ -472,6 +611,7 @@ struct SqlLogSource<B> {
     last_delivered: Option<i64>,
     /// Highest `seq` settled forward by this source's handles.
     settled_seq: Arc<AtomicI64>,
+    source_epoch: ProjectionEpoch,
 }
 
 impl<B: SqlBusDialect> MessageSource for SqlLogSource<B> {
@@ -482,6 +622,9 @@ impl<B: SqlBusDialect> MessageSource for SqlLogSource<B> {
     }
 
     async fn recv(&mut self) -> Result<Option<Self::Received>, TransportError> {
+        // Validate even when `buffer` already contains read-ahead. A log reset
+        // retires every cached row from the prior generation immediately.
+        self.dialect.verify_log_epoch(&self.source_epoch).await?;
         if let Some(last) = self.last_delivered {
             if self.settled_seq.load(Ordering::Acquire) < last {
                 // The last entry was nacked: the offset did not move, so the
@@ -493,18 +636,38 @@ impl<B: SqlBusDialect> MessageSource for SqlLogSource<B> {
         if self.buffer.is_empty() {
             let rows = self
                 .dialect
-                .log_read(&self.names, &self.consumer, SOURCE_BATCH)
+                .log_read(
+                    &self.names,
+                    &self.consumer,
+                    SOURCE_BATCH,
+                    &self.source_epoch,
+                )
                 .await?;
             self.buffer.extend(rows);
         }
-        Ok(self.buffer.pop_front().map(|row| {
-            self.last_delivered = Some(row.seq);
-            SqlLogReceived {
-                dialect: self.dialect.clone(),
-                consumer: self.consumer.clone(),
-                settled_seq: self.settled_seq.clone(),
-                row,
-            }
+        let Some(row) = self.buffer.pop_front() else {
+            return Ok(None);
+        };
+        let position = u64::try_from(row.seq).map_err(|_| {
+            corrupt_row(
+                B::BACKEND,
+                format!(
+                    "bus_log seq {} is outside the projection cursor domain",
+                    row.seq
+                ),
+            )
+        })?;
+        let source = ProjectionSource::new(format!("{}.bus_log", B::BACKEND), b"global".to_vec())
+            .map_err(|error| corrupt_row(B::BACKEND, error.to_string()))?;
+        let ordered = OrderedDelivery::new(source, self.source_epoch.clone(), position, false)
+            .map_err(|error| corrupt_row(B::BACKEND, error.to_string()))?;
+        self.last_delivered = Some(row.seq);
+        Ok(Some(SqlLogReceived {
+            dialect: self.dialect.clone(),
+            consumer: self.consumer.clone(),
+            settled_seq: self.settled_seq.clone(),
+            row,
+            ordered,
         }))
     }
 }
@@ -517,6 +680,7 @@ pub struct SqlLogReceived<B> {
     consumer: String,
     settled_seq: Arc<AtomicI64>,
     row: ReceivedRow,
+    ordered: OrderedDelivery,
 }
 
 impl<B: SqlBusDialect> SqlLogReceived<B> {
@@ -524,7 +688,7 @@ impl<B: SqlBusDialect> SqlLogReceived<B> {
     /// source knows its buffered read-ahead is still valid.
     async fn settle_forward(self) -> Result<(), TransportError> {
         self.dialect
-            .advance_offset(&self.consumer, self.row.seq)
+            .advance_offset(&self.consumer, self.row.seq, self.ordered.epoch())
             .await?;
         self.settled_seq.store(self.row.seq, Ordering::Release);
         Ok(())
@@ -536,6 +700,10 @@ impl<B: SqlBusDialect> ReceivedMessage for SqlLogReceived<B> {
         &self.row.message
     }
 
+    fn ordered_delivery(&self) -> Option<&OrderedDelivery> {
+        Some(&self.ordered)
+    }
+
     fn decode_error(&self) -> Option<&TransportError> {
         self.row.decode_error.as_ref()
     }
diff --git a/src/bus/sqlite_bus.rs b/src/bus/sqlite_bus.rs
index 0cabe33f..8df2da90 100644
--- a/src/bus/sqlite_bus.rs
+++ b/src/bus/sqlite_bus.rs
@@ -7,8 +7,9 @@
 //!   table (`bus_queue`) claimed by one atomic `UPDATE ... RETURNING` under a
 //!   lease. SQLite serializes writers, so one of N competing `listen`ers handles
 //!   each command and the row is deleted on success.
-//! - **`publish` / `subscribe` (fan-out):** an append-only `bus_log` table plus
-//!   a per-consumer offset table (`bus_offset`). Each `group` reads independently
+//! - **`publish` / `subscribe` (fan-out):** an append-only `bus_log` table, its
+//!   durable generation identity (`bus_log_identity`), and a per-consumer
+//!   epoch-bound offset table (`bus_offset`). Each `group` reads independently
 //!   past its own offset, so every group sees every event.
 //!
 //! The bus model itself (builders, sources, settlement, corruption handling) is
@@ -25,13 +26,14 @@
 //! [`Bus`]: super::Bus
 //! [`BusConsumer`]: super::BusConsumer
 
-use sqlx::{QueryBuilder, Row, Sqlite, SqlitePool};
+use sqlx::{QueryBuilder, Row, Sqlite, SqliteConnection, SqlitePool};
 
 use super::sql_bus_common::{
-    db_err as sql_db_err, metadata_json, ClaimedRow, ReceivedRow, SqlBus, SqlBusDialect,
-    SqlLogReceived, SqlQueueReceived,
+    db_err as sql_db_err, message_from_row, metadata_json, validate_log_retry, ClaimedRow,
+    ReceivedRow, SqlBus, SqlBusDialect, SqlLogReceived, SqlQueueReceived,
 };
 use super::{Message, TransportError};
+use crate::projection_protocol::ProjectionEpoch;
 
 const SCHEMA: &str = "\
 CREATE TABLE IF NOT EXISTS bus_queue (
@@ -70,9 +72,21 @@ CREATE TABLE IF NOT EXISTS bus_log (
 CREATE INDEX IF NOT EXISTS bus_log_name_seq_idx ON bus_log (name, seq);
 CREATE TABLE IF NOT EXISTS bus_offset (
     consumer TEXT PRIMARY KEY,
+    source_epoch TEXT NOT NULL,
     last_seq INTEGER NOT NULL DEFAULT 0,
     CHECK (consumer <> ''),
+    CHECK (source_epoch <> ''),
     CHECK (last_seq >= 0)
+);
+CREATE TABLE IF NOT EXISTS bus_log_identity (
+    singleton    INTEGER PRIMARY KEY DEFAULT 1,
+    source_epoch TEXT NOT NULL,
+    generation   INTEGER NOT NULL DEFAULT 1,
+    high_water   INTEGER NOT NULL DEFAULT 0,
+    CHECK (singleton = 1),
+    CHECK (source_epoch <> ''),
+    CHECK (generation > 0),
+    CHECK (high_water >= 0)
 )";
 
 fn db_err(context: &str, err: sqlx::Error) -> TransportError {
@@ -150,6 +164,116 @@ impl SqliteBusDialect {
             .map_err(|err| db_err(context, err))?;
         Ok(())
     }
+
+    /// SQLite's first write serializes this transaction with every other
+    /// framework append. The singleton row therefore keeps the persisted
+    /// epoch/high-water pair exact. An observed maximum below the high-water
+    /// fails closed; only [`SqlBus::reset_ordered_log`] may retire the cursor
+    /// domain.
+    async fn reconcile_log_identity(
+        connection: &mut SqliteConnection,
+        epoch_candidate: &ProjectionEpoch,
+        expected_epoch: Option<&ProjectionEpoch>,
+    ) -> Result<ProjectionEpoch, TransportError> {
+        let inserted = sqlx::query(
+            "INSERT INTO bus_log_identity \
+                 (singleton, source_epoch, generation, high_water) \
+             VALUES (1, ?, 1, 0) \
+             ON CONFLICT (singleton) DO NOTHING",
+        )
+        .bind(epoch_candidate.as_str())
+        .execute(&mut *connection)
+        .await
+        .map_err(|err| db_err("prepare log identity", err))?
+        .rows_affected()
+            == 1;
+
+        let identity = sqlx::query(
+            "SELECT source_epoch, generation, high_water \
+             FROM bus_log_identity WHERE singleton = 1",
+        )
+        .fetch_one(&mut *connection)
+        .await
+        .map_err(|err| db_err("read log identity", err))?;
+        let source_epoch: String = identity
+            .try_get("source_epoch")
+            .map_err(|err| db_err("decode log identity epoch", err))?;
+        let high_water: i64 = identity
+            .try_get("high_water")
+            .map_err(|err| db_err("decode log identity high water", err))?;
+        let log_max: i64 = sqlx::query_scalar("SELECT COALESCE(MAX(seq), 0) FROM bus_log")
+            .fetch_one(&mut *connection)
+            .await
+            .map_err(|err| db_err("read log high water", err))?;
+
+        if inserted && log_max > 0 && expected_epoch.is_none() {
+            return Err(TransportError::permanent(format!(
+                "sqlite bus ordered-log identity is missing while the log still \
+                 contains positions through {log_max}; refusing to assign a \
+                 random epoch, explicitly adopt the retained log with \
+                 with_source_epoch"
+            )));
+        }
+        if inserted {
+            // An identity recreated independently of its offsets cannot prove
+            // which cursor generation those offsets belong to. Retire them in
+            // the same transaction that installs the new identity.
+            sqlx::query("DELETE FROM bus_offset")
+                .execute(&mut *connection)
+                .await
+                .map_err(|err| db_err("clear unbound log offsets", err))?;
+        }
+        if log_max < high_water {
+            return Err(TransportError::permanent(format!(
+                "sqlite bus observed ordered-log maximum {log_max} below durable \
+                 high-water {high_water}; ordinary startup cannot rotate cursor \
+                 identity, use reset_ordered_log with the expected epoch"
+            )));
+        } else if log_max > high_water {
+            sqlx::query("UPDATE bus_log_identity SET high_water = ? WHERE singleton = 1")
+                .bind(log_max)
+                .execute(&mut *connection)
+                .await
+                .map_err(|err| db_err("advance log high water", err))?;
+        }
+        if let Some(expected_epoch) = expected_epoch {
+            if source_epoch != expected_epoch.as_str() {
+                return Err(TransportError::permanent(format!(
+                    "sqlite bus configured source epoch {:?} does not match \
+                     durable ordered-log epoch {:?}",
+                    expected_epoch.as_str(),
+                    source_epoch
+                )));
+            }
+        }
+
+        ProjectionEpoch::new(source_epoch).map_err(|error| {
+            TransportError::permanent(format!("sqlite bus corrupt log identity epoch: {error}"))
+        })
+    }
+
+    async fn validate_expected_log_epoch(
+        connection: &mut SqliteConnection,
+        expected_epoch: &ProjectionEpoch,
+    ) -> Result<(), TransportError> {
+        let actual: String =
+            sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+                .fetch_one(&mut *connection)
+                .await
+                .map_err(|err| db_err("read log identity for delivery", err))?;
+        let actual = ProjectionEpoch::new(actual).map_err(|error| {
+            TransportError::permanent(format!("sqlite bus corrupt log identity epoch: {error}"))
+        })?;
+        if &actual != expected_epoch {
+            return Err(TransportError::permanent(format!(
+                "sqlite bus ordered-log epoch changed from {:?} to {:?}; \
+                 the subscriber must restart",
+                expected_epoch.as_str(),
+                actual.as_str()
+            )));
+        }
+        Ok(())
+    }
 }
 
 impl SqlBusDialect for SqliteBusDialect {
@@ -164,6 +288,94 @@ impl SqlBusDialect for SqliteBusDialect {
         Ok(())
     }
 
+    async fn ensure_ordered_log_schema(&self) -> Result<(), TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin ordered-log schema upgrade", err))?;
+        // Acquire SQLite's writer reservation before inspecting legacy rows so
+        // duplicate validation, deletion, and unique-index creation are one
+        // serialized migration.
+        sqlx::query("UPDATE bus_log SET seq = seq WHERE 0")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|err| db_err("lock ordered log for schema upgrade", err))?;
+        let offset_columns = sqlx::query("PRAGMA table_info(bus_offset)")
+            .fetch_all(&mut *transaction)
+            .await
+            .map_err(|err| db_err("inspect offset schema", err))?;
+        let has_source_epoch = offset_columns.iter().any(|column| {
+            column
+                .try_get::<String, _>("name")
+                .map(|name| name == "source_epoch")
+                .unwrap_or(false)
+        });
+        if !has_source_epoch {
+            sqlx::query("ALTER TABLE bus_offset ADD COLUMN source_epoch TEXT")
+                .execute(&mut *transaction)
+                .await
+                .map_err(|err| db_err("add offset epoch", err))?;
+        }
+        sqlx::query("DELETE FROM bus_offset WHERE source_epoch IS NULL OR source_epoch = ''")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|err| db_err("clear legacy unbound offsets", err))?;
+
+        let duplicate_rows = sqlx::query(
+            "SELECT seq, name, message_id, kind, payload, content_type, metadata \
+             FROM bus_log \
+             WHERE message_id IN ( \
+                 SELECT message_id FROM bus_log \
+                 WHERE message_id IS NOT NULL \
+                 GROUP BY message_id HAVING COUNT(*) > 1 \
+             ) \
+             ORDER BY message_id, seq",
+        )
+        .fetch_all(&mut *transaction)
+        .await
+        .map_err(|err| db_err("inspect legacy stable message IDs", err))?;
+        let mut authoritative: Option<(String, Message)> = None;
+        let mut redundant = Vec::new();
+        for row in &duplicate_rows {
+            let message_id: String = row
+                .try_get("message_id")
+                .map_err(|err| db_err("decode legacy stable message ID", err))?;
+            let message = message_from_row(Self::BACKEND, row)?;
+            match authoritative.as_ref() {
+                Some((authoritative_id, authoritative_message))
+                    if authoritative_id == &message_id =>
+                {
+                    validate_log_retry(Self::BACKEND, authoritative_message, &message)?;
+                    redundant.push(
+                        row.try_get::<i64, _>("seq")
+                            .map_err(|err| db_err("decode redundant log position", err))?,
+                    );
+                }
+                _ => authoritative = Some((message_id, message)),
+            }
+        }
+        for seq in redundant {
+            sqlx::query("DELETE FROM bus_log WHERE seq = ?")
+                .bind(seq)
+                .execute(&mut *transaction)
+                .await
+                .map_err(|err| db_err("deduplicate legacy stable message IDs", err))?;
+        }
+        sqlx::query(
+            "CREATE UNIQUE INDEX IF NOT EXISTS bus_log_message_id_unique_idx \
+             ON bus_log (message_id) WHERE message_id IS NOT NULL",
+        )
+        .execute(&mut *transaction)
+        .await
+        .map_err(|err| db_err("fence stable message IDs", err))?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit ordered-log schema upgrade", err))?;
+        Ok(())
+    }
+
     async fn insert_queue(&self, message: &Message) -> Result<(), TransportError> {
         self.insert(
             "INSERT INTO bus_queue (name, message_id, kind, payload, content_type, metadata) \
@@ -174,14 +386,171 @@ impl SqlBusDialect for SqliteBusDialect {
         .await
     }
 
-    async fn insert_log(&self, message: &Message) -> Result<(), TransportError> {
-        self.insert(
-            "INSERT INTO bus_log (name, message_id, kind, payload, content_type, metadata) \
-             VALUES (?, ?, ?, ?, ?, ?)",
-            "append",
-            message,
+    async fn insert_log(
+        &self,
+        message: &Message,
+        epoch_candidate: &ProjectionEpoch,
+        expected_epoch: Option<&ProjectionEpoch>,
+    ) -> Result<(), TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin append", err))?;
+        Self::reconcile_log_identity(&mut transaction, epoch_candidate, expected_epoch).await?;
+
+        let metadata = metadata_json(message);
+        let inserted_seq = if message.id().is_some() {
+            sqlx::query_scalar::<_, i64>(
+                "INSERT INTO bus_log \
+                     (name, message_id, kind, payload, content_type, metadata) \
+                 VALUES (?, ?, ?, ?, ?, ?) \
+                 ON CONFLICT (message_id) WHERE message_id IS NOT NULL DO NOTHING \
+                 RETURNING seq",
+            )
+            .bind(&message.name)
+            .bind(&message.id)
+            .bind(message.kind.as_str())
+            .bind(&message.payload)
+            .bind(&message.content_type)
+            .bind(&metadata)
+            .fetch_optional(&mut *transaction)
+            .await
+            .map_err(|err| db_err("append", err))?
+        } else {
+            Some(
+                sqlx::query_scalar::<_, i64>(
+                    "INSERT INTO bus_log \
+                         (name, message_id, kind, payload, content_type, metadata) \
+                     VALUES (?, ?, ?, ?, ?, ?) \
+                     RETURNING seq",
+                )
+                .bind(&message.name)
+                .bind(&message.id)
+                .bind(message.kind.as_str())
+                .bind(&message.payload)
+                .bind(&message.content_type)
+                .bind(&metadata)
+                .fetch_one(&mut *transaction)
+                .await
+                .map_err(|err| db_err("append", err))?,
+            )
+        };
+
+        let seq = match inserted_seq {
+            Some(seq) => seq,
+            None => {
+                let existing = sqlx::query(
+                    "SELECT seq, name, message_id, kind, payload, content_type, metadata \
+                     FROM bus_log WHERE message_id = ?",
+                )
+                .bind(message.id())
+                .fetch_optional(&mut *transaction)
+                .await
+                .map_err(|err| db_err("read idempotent append", err))?
+                .ok_or_else(|| {
+                    TransportError::permanent(
+                        "sqlite bus stable message ID conflict had no existing log row",
+                    )
+                })?;
+                let existing_message = message_from_row(Self::BACKEND, &existing)?;
+                validate_log_retry(Self::BACKEND, &existing_message, message)?;
+                existing
+                    .try_get("seq")
+                    .map_err(|err| db_err("decode idempotent append position", err))?
+            }
+        };
+
+        sqlx::query(
+            "UPDATE bus_log_identity SET high_water = MAX(high_water, ?) \
+             WHERE singleton = 1",
+        )
+        .bind(seq)
+        .execute(&mut *transaction)
+        .await
+        .map_err(|err| db_err("advance log high water", err))?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit append", err))?;
+        Ok(())
+    }
+
+    async fn prepare_log_epoch(
+        &self,
+        epoch_candidate: &ProjectionEpoch,
+        expected_epoch: Option<&ProjectionEpoch>,
+    ) -> Result<ProjectionEpoch, TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin log identity", err))?;
+        let epoch =
+            Self::reconcile_log_identity(&mut transaction, epoch_candidate, expected_epoch).await?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit log identity", err))?;
+        Ok(epoch)
+    }
+
+    async fn reset_log(
+        &self,
+        expected_epoch: &ProjectionEpoch,
+        next_epoch: &ProjectionEpoch,
+    ) -> Result<(), TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin ordered-log reset", err))?;
+        // Take the writer reservation before reading the compare-and-swap
+        // fence; no append or competing reset can commit between validation
+        // and generation replacement.
+        sqlx::query("UPDATE bus_log_identity SET high_water = high_water WHERE singleton = 1")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|err| db_err("lock ordered-log reset fence", err))?;
+        let actual: String =
+            sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+                .fetch_one(&mut *transaction)
+                .await
+                .map_err(|err| db_err("read ordered-log reset fence", err))?;
+        if actual != expected_epoch.as_str() {
+            return Err(TransportError::permanent(format!(
+                "sqlite bus ordered-log reset expected epoch {:?} but durable \
+                 epoch is {:?}",
+                expected_epoch.as_str(),
+                actual
+            )));
+        }
+        sqlx::query("DELETE FROM bus_log")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|err| db_err("clear ordered log", err))?;
+        sqlx::query("DELETE FROM sqlite_sequence WHERE name = 'bus_log'")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|err| db_err("reset ordered-log sequence", err))?;
+        sqlx::query("DELETE FROM bus_offset")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|err| db_err("clear ordered-log offsets", err))?;
+        sqlx::query(
+            "UPDATE bus_log_identity \
+             SET source_epoch = ?, generation = generation + 1, high_water = 0 \
+             WHERE singleton = 1",
         )
+        .bind(next_epoch.as_str())
+        .execute(&mut *transaction)
         .await
+        .map_err(|err| db_err("install next ordered-log epoch", err))?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit ordered-log reset", err))?;
+        Ok(())
     }
 
     async fn claim(
@@ -241,7 +610,14 @@ impl SqlBusDialect for SqliteBusDialect {
         names: &[String],
         consumer: &str,
         limit: i64,
+        expected_epoch: &ProjectionEpoch,
     ) -> Result<Vec<ReceivedRow>, TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin log read", err))?;
+        Self::validate_expected_log_epoch(&mut transaction, expected_epoch).await?;
         let mut query = QueryBuilder::<Sqlite>::new(
             "SELECT seq, name, message_id, kind, payload, content_type, metadata \
              FROM bus_log \
@@ -250,14 +626,20 @@ impl SqlBusDialect for SqliteBusDialect {
         push_name_filter(&mut query, names);
         query.push(" AND seq > COALESCE((SELECT last_seq FROM bus_offset WHERE consumer = ");
         query.push_bind(consumer);
+        query.push(" AND source_epoch = ");
+        query.push_bind(expected_epoch.as_str());
         query.push("), 0) ORDER BY seq LIMIT ");
         query.push_bind(limit);
 
         let rows = query
             .build()
-            .fetch_all(&self.pool)
+            .fetch_all(&mut *transaction)
             .await
             .map_err(|err| db_err("log read", err))?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit log read", err))?;
 
         Ok(rows
             .iter()
@@ -265,6 +647,23 @@ impl SqlBusDialect for SqliteBusDialect {
             .collect())
     }
 
+    async fn verify_log_epoch(
+        &self,
+        expected_epoch: &ProjectionEpoch,
+    ) -> Result<(), TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin log epoch check", err))?;
+        Self::validate_expected_log_epoch(&mut transaction, expected_epoch).await?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit log epoch check", err))?;
+        Ok(())
+    }
+
     async fn delete_claimed(&self, seq: i64, claim_token: &str) -> Result<(), TransportError> {
         sqlx::query("DELETE FROM bus_queue WHERE seq = ? AND claim_token = ?")
             .bind(seq)
@@ -289,17 +688,44 @@ impl SqlBusDialect for SqliteBusDialect {
         Ok(())
     }
 
-    async fn advance_offset(&self, consumer: &str, seq: i64) -> Result<(), TransportError> {
+    async fn advance_offset(
+        &self,
+        consumer: &str,
+        seq: i64,
+        expected_epoch: &ProjectionEpoch,
+    ) -> Result<(), TransportError> {
+        let mut transaction = self
+            .pool
+            .begin()
+            .await
+            .map_err(|err| db_err("begin advance offset", err))?;
+        // Take SQLite's writer reservation before checking the epoch so a
+        // generation rotation cannot commit between validation and settlement.
+        sqlx::query("UPDATE bus_log_identity SET high_water = high_water WHERE singleton = 1")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|err| db_err("lock log identity for settlement", err))?;
+        Self::validate_expected_log_epoch(&mut transaction, expected_epoch).await?;
         sqlx::query(
-            "INSERT INTO bus_offset (consumer, last_seq) VALUES (?, ?) \
-             ON CONFLICT (consumer) DO UPDATE SET last_seq = excluded.last_seq \
-             WHERE bus_offset.last_seq < excluded.last_seq",
+            "INSERT INTO bus_offset (consumer, source_epoch, last_seq) VALUES (?, ?, ?) \
+             ON CONFLICT (consumer) DO UPDATE SET \
+                 source_epoch = excluded.source_epoch, \
+                 last_seq = CASE \
+                     WHEN bus_offset.source_epoch = excluded.source_epoch \
+                     THEN MAX(bus_offset.last_seq, excluded.last_seq) \
+                     ELSE excluded.last_seq \
+                 END",
         )
         .bind(consumer)
+        .bind(expected_epoch.as_str())
         .bind(seq)
-        .execute(&self.pool)
+        .execute(&mut *transaction)
         .await
         .map_err(|err| db_err("advance offset", err))?;
+        transaction
+            .commit()
+            .await
+            .map_err(|err| db_err("commit advance offset", err))?;
         Ok(())
     }
 }
diff --git a/src/command_ledger/error.rs b/src/command_ledger/error.rs
new file mode 100644
index 00000000..e57485b3
--- /dev/null
+++ b/src/command_ledger/error.rs
@@ -0,0 +1,42 @@
+use std::fmt;
+
+use crate::repository::RepositoryError;
+
+/// Internal ledger error. Conflict is a reservation outcome, not an error, so
+/// the dispatcher can map it directly to `COMMAND_ID_REUSE` without inspecting
+/// strings or storage errors.
+#[derive(Debug)]
+pub(crate) enum CommandLedgerError {
+    Invalid(String),
+    Corrupt(String),
+    AttemptFenced { command_id: String },
+    Storage(RepositoryError),
+}
+
+impl fmt::Display for CommandLedgerError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Invalid(message) => write!(formatter, "invalid command ledger value: {message}"),
+            Self::Corrupt(message) => write!(formatter, "corrupt command ledger row: {message}"),
+            Self::AttemptFenced { command_id } => {
+                write!(formatter, "command attempt for `{command_id}` was fenced")
+            }
+            Self::Storage(error) => write!(formatter, "command ledger storage failed: {error}"),
+        }
+    }
+}
+
+impl std::error::Error for CommandLedgerError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Storage(error) => Some(error),
+            Self::Invalid(_) | Self::Corrupt(_) | Self::AttemptFenced { .. } => None,
+        }
+    }
+}
+
+impl From<RepositoryError> for CommandLedgerError {
+    fn from(error: RepositoryError) -> Self {
+        Self::Storage(error)
+    }
+}
diff --git a/src/command_ledger/ids.rs b/src/command_ledger/ids.rs
new file mode 100644
index 00000000..69501792
--- /dev/null
+++ b/src/command_ledger/ids.rs
@@ -0,0 +1,273 @@
+use std::fmt;
+
+use uuid::{Uuid, Variant};
+
+use super::CommandLedgerError;
+
+pub(crate) const SHA256_BYTES: usize = 32;
+pub(super) const COMMAND_REPLAY_VERSION: u16 = 2;
+
+/// Opaque identity for one concrete leaf repository instance.
+///
+/// Clones copy this value. Constructing a new leaf repository over even the
+/// same underlying pool creates a different identity, so GraphQL command
+/// binding must retain the repository handle that owns the causal committer.
+#[derive(Clone, Copy, PartialEq, Eq, Hash)]
+pub(crate) struct CausalStorageIdentity(Uuid);
+
+impl CausalStorageIdentity {
+    pub(crate) fn new() -> Self {
+        Self(Uuid::now_v7())
+    }
+}
+
+impl fmt::Debug for CausalStorageIdentity {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("CausalStorageIdentity([opaque])")
+    }
+}
+
+/// Canonical client-created UUIDv7 command identity.
+#[derive(Clone, PartialEq, Eq, Hash)]
+pub(crate) struct CommandId(String);
+
+impl CommandId {
+    pub(crate) fn parse(value: impl AsRef<str>) -> Result<Self, CommandLedgerError> {
+        let value = value.as_ref();
+        let parsed = Uuid::parse_str(value).map_err(|_| {
+            CommandLedgerError::Invalid(format!("command ID `{value}` must be a valid UUIDv7"))
+        })?;
+        if parsed.get_version_num() != 7 || parsed.get_variant() != Variant::RFC4122 {
+            return Err(CommandLedgerError::Invalid(format!(
+                "command ID `{value}` must be an RFC 4122 UUIDv7"
+            )));
+        }
+        Ok(Self(parsed.hyphenated().to_string()))
+    }
+
+    pub(crate) fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Debug for CommandId {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.debug_tuple("CommandId").field(&self.0).finish()
+    }
+}
+
+/// Versioned server-derived verified-principal partition.
+#[derive(Clone, PartialEq, Eq, Hash)]
+pub(crate) struct PrincipalPartitionId(String);
+
+impl PrincipalPartitionId {
+    pub(crate) fn new(value: impl Into<String>) -> Result<Self, CommandLedgerError> {
+        let value = value.into();
+        if value.trim().is_empty() {
+            return Err(CommandLedgerError::Invalid(
+                "principal partition must not be empty".into(),
+            ));
+        }
+        Ok(Self(value))
+    }
+
+    pub(crate) fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Debug for PrincipalPartitionId {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("PrincipalPartitionId([redacted])")
+    }
+}
+
+/// Complete non-forgeable ledger key.
+#[derive(Clone, PartialEq, Eq, Hash)]
+pub(crate) struct CommandLedgerKey {
+    service_id: String,
+    principal_partition: PrincipalPartitionId,
+    pub(super) command_id: CommandId,
+}
+
+impl CommandLedgerKey {
+    pub(crate) fn new(
+        service_id: impl Into<String>,
+        principal_partition: PrincipalPartitionId,
+        command_id: CommandId,
+    ) -> Result<Self, CommandLedgerError> {
+        let service_id = service_id.into();
+        if service_id.trim().is_empty() {
+            return Err(CommandLedgerError::Invalid(
+                "command ledger service ID must not be empty".into(),
+            ));
+        }
+        Ok(Self {
+            service_id,
+            principal_partition,
+            command_id,
+        })
+    }
+
+    pub(crate) fn service_id(&self) -> &str {
+        &self.service_id
+    }
+
+    pub(crate) fn principal_partition(&self) -> &str {
+        self.principal_partition.as_str()
+    }
+
+    pub(crate) fn command_id(&self) -> &str {
+        self.command_id.as_str()
+    }
+}
+
+impl fmt::Debug for CommandLedgerKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("CommandLedgerKey")
+            .field("service_id", &self.service_id)
+            .field("principal_partition", &"[redacted]")
+            .field("command_id", &self.command_id)
+            .finish()
+    }
+}
+
+macro_rules! fixed_hash {
+    ($name:ident, $description:literal) => {
+        #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+        pub(crate) struct $name([u8; SHA256_BYTES]);
+
+        impl $name {
+            pub(crate) fn new(bytes: [u8; SHA256_BYTES]) -> Self {
+                Self(bytes)
+            }
+
+            pub(crate) fn try_from_slice(bytes: &[u8]) -> Result<Self, CommandLedgerError> {
+                let bytes: [u8; SHA256_BYTES] = bytes.try_into().map_err(|_| {
+                    CommandLedgerError::Invalid(format!(
+                        "{} must contain exactly {SHA256_BYTES} bytes",
+                        $description
+                    ))
+                })?;
+                Ok(Self(bytes))
+            }
+
+            /// Parse the canonical wire spelling emitted by command-input and
+            /// command-contract code (`sha256:` followed by 64 lowercase hex
+            /// digits). Keeping this checked seam here prevents dispatch code
+            /// from hand-decoding identity material differently at each call
+            /// site.
+            #[cfg(test)]
+            pub(crate) fn parse_sha256(value: &str) -> Result<Self, CommandLedgerError> {
+                parse_sha256(value, $description).map(Self)
+            }
+
+            pub(crate) fn as_bytes(&self) -> &[u8; SHA256_BYTES] {
+                &self.0
+            }
+        }
+    };
+}
+
+fixed_hash!(CanonicalInputHash, "canonical command input hash");
+fixed_hash!(CommandContractFingerprint, "command contract fingerprint");
+
+#[cfg(test)]
+fn parse_sha256(
+    value: &str,
+    description: &'static str,
+) -> Result<[u8; SHA256_BYTES], CommandLedgerError> {
+    let encoded = value.strip_prefix("sha256:").ok_or_else(|| {
+        CommandLedgerError::Invalid(format!(
+            "{description} must use the canonical `sha256:<lowercase-hex>` format"
+        ))
+    })?;
+    if encoded.len() != SHA256_BYTES * 2 {
+        return Err(CommandLedgerError::Invalid(format!(
+            "{description} must contain exactly {} hexadecimal digits",
+            SHA256_BYTES * 2
+        )));
+    }
+
+    fn nibble(byte: u8) -> Option<u8> {
+        match byte {
+            b'0'..=b'9' => Some(byte - b'0'),
+            b'a'..=b'f' => Some(byte - b'a' + 10),
+            _ => None,
+        }
+    }
+
+    let encoded = encoded.as_bytes();
+    let mut digest = [0; SHA256_BYTES];
+    for (index, target) in digest.iter_mut().enumerate() {
+        let high = nibble(encoded[index * 2]);
+        let low = nibble(encoded[index * 2 + 1]);
+        let (Some(high), Some(low)) = (high, low) else {
+            return Err(CommandLedgerError::Invalid(format!(
+                "{description} must contain only lowercase hexadecimal digits"
+            )));
+        };
+        *target = (high << 4) | low;
+    }
+    Ok(digest)
+}
+
+/// Stable causation allocated exactly once when a ledger identity is inserted.
+#[derive(Clone, PartialEq, Eq, Hash)]
+pub(crate) struct CausationId(String);
+
+impl CausationId {
+    pub(crate) fn new() -> Self {
+        Self(Uuid::now_v7().hyphenated().to_string())
+    }
+
+    pub(crate) fn parse_stored(value: String) -> Result<Self, CommandLedgerError> {
+        parse_stored_uuid_v7("causation ID", value).map(Self)
+    }
+
+    pub(crate) fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Debug for CausationId {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.debug_tuple("CausationId").field(&self.0).finish()
+    }
+}
+
+/// Generation fence for one speculative handler attempt.
+#[derive(Clone, PartialEq, Eq)]
+pub(crate) struct AttemptToken(pub(super) String);
+
+impl AttemptToken {
+    pub(super) fn new() -> Self {
+        Self(Uuid::now_v7().hyphenated().to_string())
+    }
+
+    pub(crate) fn parse_stored(value: String) -> Result<Self, CommandLedgerError> {
+        parse_stored_uuid_v7("attempt token", value).map(Self)
+    }
+
+    pub(crate) fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Debug for AttemptToken {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("AttemptToken([redacted])")
+    }
+}
+
+fn parse_stored_uuid_v7(label: &str, value: String) -> Result<String, CommandLedgerError> {
+    let parsed = Uuid::parse_str(&value)
+        .map_err(|_| CommandLedgerError::Corrupt(format!("stored {label} is not a UUID")))?;
+    if parsed.get_version_num() != 7 || parsed.get_variant() != Variant::RFC4122 {
+        return Err(CommandLedgerError::Corrupt(format!(
+            "stored {label} is not an RFC 4122 UUIDv7"
+        )));
+    }
+    Ok(parsed.hyphenated().to_string())
+}
diff --git a/src/command_ledger/mod.rs b/src/command_ledger/mod.rs
new file mode 100644
index 00000000..0c89ed84
--- /dev/null
+++ b/src/command_ledger/mod.rs
@@ -0,0 +1,40 @@
+//! Adapter-neutral durable command identity and fenced commit primitives.
+//!
+//! This module is deliberately crate-private. Application handlers interact
+//! with the typed command API; only the framework dispatcher and repository
+//! adapters may reserve attempts or attach a ledger completion to a domain
+//! [`crate::repository::CommitBatch`]. Keeping the completion outside the public batch preserves
+//! the existing repository API while making causal completion inseparable from
+//! the backend transaction that stores the domain effects.
+
+#![cfg_attr(not(feature = "graphql"), allow(dead_code))]
+
+mod error;
+mod ids;
+mod record;
+mod reservation;
+mod state;
+mod traits;
+
+#[cfg(test)]
+mod tests;
+
+pub(crate) use error::CommandLedgerError;
+// PrincipalPartitionId is consumed by graphql/sqlx modules; unused on default features.
+#[cfg_attr(
+    not(any(feature = "graphql", feature = "sqlite", feature = "postgres")),
+    allow(unused_imports)
+)]
+pub(crate) use ids::{
+    AttemptToken, CanonicalInputHash, CausalStorageIdentity, CausationId,
+    CommandContractFingerprint, CommandId, CommandLedgerKey, PrincipalPartitionId, SHA256_BYTES,
+};
+pub(crate) use record::{CommandLedgerRecord, ReservationDecision};
+pub(crate) use reservation::{
+    AttemptFence, CausalCommitBatch, CommandAttempt, CommandCompletion, CommandLookup,
+    CommandLookupScope, CommandReplay, CommandReservation, ReservationOutcome,
+};
+pub(crate) use state::{CommandLedgerState, TerminalCommandState};
+pub(crate) use traits::{
+    CausalGetStream, CausalRepositoryIdentity, CausalTransactionalCommit, CommandLedgerStore,
+};
diff --git a/src/command_ledger/record.rs b/src/command_ledger/record.rs
new file mode 100644
index 00000000..4a6c57e9
--- /dev/null
+++ b/src/command_ledger/record.rs
@@ -0,0 +1,469 @@
+use std::time::{Duration, SystemTime};
+
+use serde_json::Value;
+
+use crate::projection_protocol::{ResolvedProjectionObligation, SameTransactionProjectionEvidence};
+
+use super::{
+    ids::COMMAND_REPLAY_VERSION, state::validate_projection_obligation_semantics, AttemptFence,
+    AttemptToken, CanonicalInputHash, CausationId, CommandAttempt, CommandCompletion,
+    CommandContractFingerprint, CommandLedgerError, CommandLedgerKey, CommandLedgerState,
+    CommandLookup, CommandLookupScope, CommandReplay, CommandReservation, ReservationOutcome,
+};
+
+/// Storage-neutral row representation shared by built-in adapters.
+#[derive(Clone, Debug)]
+pub(crate) struct CommandLedgerRecord {
+    pub(crate) key: CommandLedgerKey,
+    pub(crate) command_name: String,
+    pub(crate) contract_fingerprint: CommandContractFingerprint,
+    pub(crate) input_hash: CanonicalInputHash,
+    pub(crate) state: CommandLedgerState,
+    pub(crate) causation_id: CausationId,
+    pub(crate) attempt_token: Option<AttemptToken>,
+    pub(crate) attempt_number: u64,
+    pub(crate) lease_expires_at: Option<SystemTime>,
+    pub(crate) outcome_json: Option<String>,
+    #[allow(dead_code)]
+    pub(crate) created_at: SystemTime,
+    pub(crate) updated_at: SystemTime,
+    pub(crate) completed_at: Option<SystemTime>,
+    pub(crate) retention_expires_at: SystemTime,
+    pub(crate) compacted_at: Option<SystemTime>,
+}
+
+impl CommandLedgerRecord {
+    pub(crate) fn initial(
+        reservation: &CommandReservation,
+        now: SystemTime,
+    ) -> Result<Self, CommandLedgerError> {
+        Ok(Self {
+            key: reservation.key.clone(),
+            command_name: reservation.command_name.clone(),
+            contract_fingerprint: reservation.contract_fingerprint,
+            input_hash: reservation.input_hash,
+            state: CommandLedgerState::InProgress,
+            causation_id: reservation.candidate_causation.clone(),
+            attempt_token: Some(reservation.candidate_attempt.clone()),
+            attempt_number: 1,
+            lease_expires_at: Some(checked_deadline(now, reservation.lease, "attempt lease")?),
+            outcome_json: None,
+            created_at: now,
+            updated_at: now,
+            completed_at: None,
+            retention_expires_at: checked_deadline(
+                now,
+                reservation.retention,
+                "command retention",
+            )?,
+            compacted_at: None,
+        })
+    }
+
+    pub(crate) fn acquired_attempt(&self) -> Result<CommandAttempt, CommandLedgerError> {
+        let token = self.attempt_token.as_ref().ok_or_else(|| {
+            CommandLedgerError::Corrupt(format!(
+                "in-progress command `{}` has no attempt token",
+                self.key.command_id()
+            ))
+        })?;
+        Ok(CommandAttempt {
+            key: self.key.clone(),
+            contract_fingerprint: self.contract_fingerprint,
+            input_hash: self.input_hash,
+            causation_id: self.causation_id.clone(),
+            attempt_token: token.clone(),
+            attempt_number: self.attempt_number,
+        })
+    }
+
+    pub(crate) fn classify_reservation(
+        &self,
+        reservation: &CommandReservation,
+        now: SystemTime,
+    ) -> Result<ReservationDecision, CommandLedgerError> {
+        if self.state == CommandLedgerState::Expired || self.retention_expires_at <= now {
+            return Ok(ReservationDecision::Expire);
+        }
+        if self.command_name != reservation.command_name
+            || self.contract_fingerprint != reservation.contract_fingerprint
+            || self.input_hash != reservation.input_hash
+        {
+            return Ok(ReservationDecision::Conflict);
+        }
+        match self.state {
+            CommandLedgerState::InProgress => {
+                let lease = self.lease_expires_at.ok_or_else(|| {
+                    CommandLedgerError::Corrupt(format!(
+                        "in-progress command `{}` has no lease deadline",
+                        self.key.command_id()
+                    ))
+                })?;
+                if lease <= now {
+                    Ok(ReservationDecision::Reclaim)
+                } else {
+                    Ok(ReservationDecision::InProgress)
+                }
+            }
+            CommandLedgerState::RetryableUnknown => Ok(ReservationDecision::Reclaim),
+            state if state.is_replayable() => Ok(ReservationDecision::Replay),
+            CommandLedgerState::Expired => Ok(ReservationDecision::Expire),
+            other => Err(CommandLedgerError::Corrupt(format!(
+                "command `{}` has unsupported state `{}`",
+                self.key.command_id(),
+                other.as_str()
+            ))),
+        }
+    }
+
+    pub(crate) fn reclaim(
+        &mut self,
+        reservation: &CommandReservation,
+        now: SystemTime,
+    ) -> Result<(), CommandLedgerError> {
+        let attempt_number = self.attempt_number.checked_add(1).ok_or_else(|| {
+            CommandLedgerError::Corrupt(format!(
+                "command `{}` attempt counter overflowed",
+                self.key.command_id()
+            ))
+        })?;
+        let lease_expires_at = checked_deadline(now, reservation.lease, "attempt lease")?;
+        let retention_expires_at =
+            checked_deadline(now, reservation.retention, "command retention")?;
+
+        self.state = CommandLedgerState::InProgress;
+        self.attempt_token = Some(reservation.candidate_attempt.clone());
+        self.attempt_number = attempt_number;
+        self.lease_expires_at = Some(lease_expires_at);
+        self.retention_expires_at = retention_expires_at;
+        self.updated_at = now;
+        Ok(())
+    }
+
+    pub(crate) fn validate_stored_shape(&self) -> Result<(), CommandLedgerError> {
+        if self.command_name.trim().is_empty() || self.attempt_number == 0 {
+            return Err(CommandLedgerError::Corrupt(format!(
+                "command `{}` has invalid invariant fields",
+                self.key.command_id()
+            )));
+        }
+        let valid = match self.state {
+            CommandLedgerState::InProgress => {
+                self.attempt_token.is_some()
+                    && self.lease_expires_at.is_some()
+                    && self.outcome_json.is_none()
+                    && self.completed_at.is_none()
+                    && self.compacted_at.is_none()
+            }
+            CommandLedgerState::RetryableUnknown => {
+                self.attempt_token.is_none()
+                    && self.lease_expires_at.is_none()
+                    && self.outcome_json.is_none()
+                    && self.completed_at.is_none()
+                    && self.compacted_at.is_none()
+            }
+            state if state.is_replayable() => {
+                self.attempt_token.is_none()
+                    && self.lease_expires_at.is_none()
+                    && self.outcome_json.is_some()
+                    && self.completed_at.is_some()
+                    && self.compacted_at.is_none()
+            }
+            CommandLedgerState::Expired => {
+                self.attempt_token.is_none()
+                    && self.lease_expires_at.is_none()
+                    && self.outcome_json.is_none()
+                    && self.compacted_at.is_some()
+            }
+            _ => false,
+        };
+        if !valid {
+            return Err(CommandLedgerError::Corrupt(format!(
+                "command `{}` state `{}` has inconsistent nullable fields",
+                self.key.command_id(),
+                self.state.as_str()
+            )));
+        }
+        Ok(())
+    }
+
+    pub(crate) fn expire(&mut self, now: SystemTime) {
+        self.state = CommandLedgerState::Expired;
+        self.attempt_token = None;
+        self.lease_expires_at = None;
+        self.outcome_json = None;
+        self.updated_at = now;
+        self.compacted_at = Some(now);
+    }
+
+    pub(crate) fn matches_fence(&self, attempt: &AttemptFence) -> bool {
+        self.key == attempt.key
+            && self.contract_fingerprint == attempt.contract_fingerprint
+            && self.input_hash == attempt.input_hash
+            && self.state == CommandLedgerState::InProgress
+            && self.causation_id == attempt.causation_id
+            && self.attempt_token.as_ref() == Some(&attempt.attempt_token)
+            && self.attempt_number == attempt.attempt_number
+    }
+
+    pub(crate) fn matches_lookup_scope(&self, scope: CommandLookupScope<'_>) -> bool {
+        match scope {
+            CommandLookupScope::CommandName(expected) => self.command_name == expected,
+            CommandLookupScope::CommandContract {
+                command_name,
+                contract_fingerprint,
+            } => {
+                self.command_name == command_name
+                    && self.contract_fingerprint.as_bytes() == contract_fingerprint
+            }
+            CommandLookupScope::Attempt(attempt) => {
+                self.key == attempt.key
+                    && self.contract_fingerprint == attempt.contract_fingerprint
+                    && self.input_hash == attempt.input_hash
+                    && self.causation_id == attempt.causation_id
+                    && self.attempt_number == attempt.attempt_number
+                    && self
+                        .attempt_token
+                        .as_ref()
+                        .is_none_or(|token| token == &attempt.attempt_token)
+            }
+        }
+    }
+
+    /// Prove that a locked ledger row still belongs to this live attempt
+    /// without inspecting or mutating its eventual completion payload.
+    ///
+    /// SQL adapters use this as an early transaction preflight before any
+    /// domain or projection writes. The final conditional completion remains
+    /// the authoritative last statement and repeats the same fence check.
+    pub(crate) fn validate_live_attempt(
+        &self,
+        attempt: &AttemptFence,
+        now: SystemTime,
+    ) -> Result<(), CommandLedgerError> {
+        let lease_is_live = self
+            .lease_expires_at
+            .is_some_and(|lease_expires_at| lease_expires_at > now);
+        if self.matches_fence(attempt) && lease_is_live {
+            Ok(())
+        } else {
+            Err(CommandLedgerError::AttemptFenced {
+                command_id: attempt.key.command_id().to_string(),
+            })
+        }
+    }
+
+    pub(crate) fn mark_retryable_unknown(
+        &mut self,
+        attempt: &AttemptFence,
+        now: SystemTime,
+    ) -> Result<(), CommandLedgerError> {
+        if !self.matches_fence(attempt) {
+            return Err(CommandLedgerError::AttemptFenced {
+                command_id: attempt.key.command_id().to_string(),
+            });
+        }
+        self.state = CommandLedgerState::RetryableUnknown;
+        self.attempt_token = None;
+        self.lease_expires_at = None;
+        self.updated_at = now;
+        Ok(())
+    }
+
+    pub(crate) fn complete(
+        &mut self,
+        completion: &CommandCompletion,
+        now: SystemTime,
+    ) -> Result<(), CommandLedgerError> {
+        completion.validate_direct_projection()?;
+        self.validate_live_attempt(&completion.attempt.fence(), now)?;
+        let retention_expires_at =
+            checked_deadline(now, completion.retention, "command retention")?;
+        self.state = completion.state.into();
+        self.attempt_token = None;
+        self.lease_expires_at = None;
+        self.outcome_json = Some(completion.replay.clone());
+        self.updated_at = now;
+        self.completed_at = Some(now);
+        self.retention_expires_at = retention_expires_at;
+        Ok(())
+    }
+
+    pub(crate) fn replay(&self) -> Result<CommandReplay, CommandLedgerError> {
+        if !self.state.is_replayable() {
+            return Err(CommandLedgerError::Corrupt(format!(
+                "command `{}` state `{}` is not replayable",
+                self.key.command_id(),
+                self.state.as_str()
+            )));
+        }
+        let payload = self.outcome_json.as_deref().ok_or_else(|| {
+            CommandLedgerError::Corrupt(format!(
+                "replayable command `{}` has no outcome",
+                self.key.command_id()
+            ))
+        })?;
+        let envelope: Value = serde_json::from_str(payload).map_err(|error| {
+            CommandLedgerError::Corrupt(format!(
+                "command `{}` outcome is invalid JSON: {error}",
+                self.key.command_id()
+            ))
+        })?;
+        let Value::Object(mut envelope) = envelope else {
+            return Err(CommandLedgerError::Corrupt(format!(
+                "command `{}` replay envelope is not an object",
+                self.key.command_id()
+            )));
+        };
+        let version = envelope
+            .remove("version")
+            .and_then(|value| value.as_u64())
+            .ok_or_else(|| {
+                CommandLedgerError::Corrupt(format!(
+                    "command `{}` replay envelope has no numeric version",
+                    self.key.command_id()
+                ))
+            })?;
+        if version != u64::from(COMMAND_REPLAY_VERSION) {
+            return Err(CommandLedgerError::Corrupt(format!(
+                "command `{}` replay envelope version `{version}` is unsupported",
+                self.key.command_id()
+            )));
+        }
+        let outcome = envelope.remove("outcome").ok_or_else(|| {
+            CommandLedgerError::Corrupt(format!(
+                "command `{}` replay envelope has no outcome",
+                self.key.command_id()
+            ))
+        })?;
+        let projection_obligations_value =
+            envelope.remove("projection_obligations").ok_or_else(|| {
+                CommandLedgerError::Corrupt(format!(
+                    "command `{}` replay envelope has no projection obligations",
+                    self.key.command_id()
+                ))
+            })?;
+        let projection_obligations: Vec<ResolvedProjectionObligation> =
+            serde_json::from_value(projection_obligations_value.clone()).map_err(|error| {
+                CommandLedgerError::Corrupt(format!(
+                    "command `{}` replay projection obligations are invalid: {error}",
+                    self.key.command_id()
+                ))
+            })?;
+        let canonical_projection_obligations = serde_json::to_value(&projection_obligations)
+            .map_err(|error| {
+                CommandLedgerError::Corrupt(format!(
+                    "command `{}` replay projection obligations cannot be normalized: {error}",
+                    self.key.command_id()
+                ))
+            })?;
+        if canonical_projection_obligations != projection_obligations_value {
+            return Err(CommandLedgerError::Corrupt(format!(
+                "command `{}` replay projection obligations contain unknown or non-canonical fields",
+                self.key.command_id()
+            )));
+        }
+        validate_projection_obligation_semantics(self.state, &projection_obligations).map_err(
+            |error| {
+                CommandLedgerError::Corrupt(format!(
+                    "command `{}` replay projection obligations are inconsistent: {error}",
+                    self.key.command_id()
+                ))
+            },
+        )?;
+        let direct_projection = envelope.remove("direct_projection");
+        match (&direct_projection, self.state) {
+            (Some(value), CommandLedgerState::Projected) => {
+                SameTransactionProjectionEvidence::validate_replay_value(value).map_err(
+                    |error| {
+                        CommandLedgerError::Corrupt(format!(
+                            "command `{}` replay direct projection is invalid: {error}",
+                            self.key.command_id()
+                        ))
+                    },
+                )?;
+            }
+            (None, CommandLedgerState::Projected) => {
+                return Err(CommandLedgerError::Corrupt(format!(
+                    "command `{}` projected replay has no exact direct projection evidence",
+                    self.key.command_id()
+                )));
+            }
+            (Some(_), _) => {
+                return Err(CommandLedgerError::Corrupt(format!(
+                    "command `{}` non-projected replay contains direct projection evidence",
+                    self.key.command_id()
+                )));
+            }
+            (None, _) => {}
+        }
+        if !envelope.is_empty() {
+            return Err(CommandLedgerError::Corrupt(format!(
+                "command `{}` replay envelope has unknown fields",
+                self.key.command_id()
+            )));
+        }
+        Ok(CommandReplay {
+            command_id: self.key.command_id.clone(),
+            state: self.state,
+            causation_id: self.causation_id.clone(),
+            outcome,
+            projection_obligations,
+            direct_projection,
+        })
+    }
+
+    pub(crate) fn lookup(&self) -> Result<CommandLookup, CommandLedgerError> {
+        match self.state {
+            CommandLedgerState::InProgress => Ok(CommandLookup::InProgress {
+                causation_id: self.causation_id.clone(),
+            }),
+            CommandLedgerState::RetryableUnknown => Ok(CommandLookup::RetryableUnknown {
+                causation_id: self.causation_id.clone(),
+            }),
+            CommandLedgerState::Expired => Ok(CommandLookup::Expired),
+            state if state.is_replayable() => Ok(CommandLookup::Replay(self.replay()?)),
+            other => Err(CommandLedgerError::Corrupt(format!(
+                "command `{}` has unsupported lookup state `{}`",
+                self.key.command_id(),
+                other.as_str()
+            ))),
+        }
+    }
+
+    pub(crate) fn reservation_outcome(
+        &self,
+        decision: ReservationDecision,
+    ) -> Result<ReservationOutcome, CommandLedgerError> {
+        match decision {
+            ReservationDecision::Conflict => Ok(ReservationOutcome::Conflict),
+            ReservationDecision::Expire => Ok(ReservationOutcome::Expired),
+            ReservationDecision::InProgress => Ok(ReservationOutcome::InProgress {
+                causation_id: self.causation_id.clone(),
+            }),
+            ReservationDecision::Replay => Ok(ReservationOutcome::Replay(self.replay()?)),
+            ReservationDecision::Reclaim => {
+                Ok(ReservationOutcome::Acquired(self.acquired_attempt()?))
+            }
+        }
+    }
+}
+
+fn checked_deadline(
+    now: SystemTime,
+    duration: Duration,
+    label: &str,
+) -> Result<SystemTime, CommandLedgerError> {
+    now.checked_add(duration).ok_or_else(|| {
+        CommandLedgerError::Invalid(format!("{label} deadline exceeds SystemTime range"))
+    })
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum ReservationDecision {
+    Conflict,
+    Expire,
+    InProgress,
+    Replay,
+    Reclaim,
+}
diff --git a/src/command_ledger/reservation.rs b/src/command_ledger/reservation.rs
new file mode 100644
index 00000000..f9936e51
--- /dev/null
+++ b/src/command_ledger/reservation.rs
@@ -0,0 +1,448 @@
+use std::fmt;
+use std::time::Duration;
+
+use serde_json::Value;
+
+use crate::projection_protocol::{
+    ResolvedProjectionObligation, SameTransactionProjectionBatch, SameTransactionProjectionEvidence,
+};
+use crate::repository::CommitBatch;
+
+use super::{
+    ids::COMMAND_REPLAY_VERSION, state::validate_projection_obligation_semantics, AttemptToken,
+    CanonicalInputHash, CausationId, CommandContractFingerprint, CommandId, CommandLedgerError,
+    CommandLedgerKey, CommandLedgerState, TerminalCommandState, SHA256_BYTES,
+};
+
+/// One validated reservation request. Fresh candidate IDs lose a race safely:
+/// only the inserted row keeps them; every retry reads the winner's causation.
+pub(crate) struct CommandReservation {
+    pub(super) key: CommandLedgerKey,
+    pub(super) command_name: String,
+    pub(super) contract_fingerprint: CommandContractFingerprint,
+    pub(super) input_hash: CanonicalInputHash,
+    pub(super) lease: Duration,
+    pub(super) retention: Duration,
+    pub(super) candidate_causation: CausationId,
+    pub(super) candidate_attempt: AttemptToken,
+}
+
+impl CommandReservation {
+    pub(crate) fn new(
+        key: CommandLedgerKey,
+        command_name: impl Into<String>,
+        contract_fingerprint: CommandContractFingerprint,
+        input_hash: CanonicalInputHash,
+        lease: Duration,
+        retention: Duration,
+    ) -> Result<Self, CommandLedgerError> {
+        let command_name = command_name.into();
+        if command_name.trim().is_empty() {
+            return Err(CommandLedgerError::Invalid(
+                "command name must not be empty".into(),
+            ));
+        }
+        validate_positive_duration("command attempt lease", lease)?;
+        validate_positive_duration("command replay retention", retention)?;
+        if retention <= lease {
+            return Err(CommandLedgerError::Invalid(
+                "command replay retention must be longer than the attempt lease".into(),
+            ));
+        }
+        Ok(Self {
+            key,
+            command_name,
+            contract_fingerprint,
+            input_hash,
+            lease,
+            retention,
+            candidate_causation: CausationId::new(),
+            candidate_attempt: AttemptToken::new(),
+        })
+    }
+
+    pub(crate) fn key(&self) -> &CommandLedgerKey {
+        &self.key
+    }
+
+    pub(crate) fn command_name(&self) -> &str {
+        &self.command_name
+    }
+
+    pub(crate) fn contract_fingerprint_bytes(&self) -> &[u8; SHA256_BYTES] {
+        self.contract_fingerprint.as_bytes()
+    }
+
+    pub(crate) fn input_hash_bytes(&self) -> &[u8; SHA256_BYTES] {
+        self.input_hash.as_bytes()
+    }
+
+    pub(crate) fn lease(&self) -> Duration {
+        self.lease
+    }
+
+    pub(crate) fn retention(&self) -> Duration {
+        self.retention
+    }
+
+    pub(crate) fn candidate_causation(&self) -> &CausationId {
+        &self.candidate_causation
+    }
+
+    pub(crate) fn candidate_attempt(&self) -> &AttemptToken {
+        &self.candidate_attempt
+    }
+
+    pub(crate) fn acquired_candidate_attempt(&self) -> CommandAttempt {
+        CommandAttempt {
+            key: self.key.clone(),
+            contract_fingerprint: self.contract_fingerprint,
+            input_hash: self.input_hash,
+            causation_id: self.candidate_causation.clone(),
+            attempt_token: self.candidate_attempt.clone(),
+            attempt_number: 1,
+        }
+    }
+}
+
+fn validate_positive_duration(label: &str, duration: Duration) -> Result<(), CommandLedgerError> {
+    if duration.is_zero() || !duration.as_secs_f64().is_finite() {
+        return Err(CommandLedgerError::Invalid(format!(
+            "{label} must be a finite positive duration"
+        )));
+    }
+    Ok(())
+}
+
+/// Exclusive capability returned to the process that owns the current lease.
+/// It is intentionally not `Clone`: one owned value must be consumed by either
+/// terminal completion or the retryable-unknown transition.
+pub(crate) struct CommandAttempt {
+    pub(super) key: CommandLedgerKey,
+    pub(super) contract_fingerprint: CommandContractFingerprint,
+    pub(super) input_hash: CanonicalInputHash,
+    pub(super) causation_id: CausationId,
+    pub(super) attempt_token: AttemptToken,
+    pub(super) attempt_number: u64,
+}
+
+impl CommandAttempt {
+    pub(crate) fn key(&self) -> &CommandLedgerKey {
+        &self.key
+    }
+
+    pub(crate) fn causation_id(&self) -> &CausationId {
+        &self.causation_id
+    }
+
+    #[cfg(test)]
+    pub(crate) fn attempt_token(&self) -> &AttemptToken {
+        &self.attempt_token
+    }
+
+    #[cfg(test)]
+    pub(crate) fn attempt_number(&self) -> u64 {
+        self.attempt_number
+    }
+
+    /// Cloneable, read-only generation fence retained across a consuming
+    /// causal commit. If commit acknowledgement is ambiguous, the dispatcher
+    /// can look up the command and mark only this exact still-live attempt as
+    /// retryable-unknown; it never needs to reconstruct secret fence material
+    /// from strings.
+    pub(crate) fn fence(&self) -> AttemptFence {
+        AttemptFence {
+            key: self.key.clone(),
+            contract_fingerprint: self.contract_fingerprint,
+            input_hash: self.input_hash,
+            causation_id: self.causation_id.clone(),
+            attempt_token: self.attempt_token.clone(),
+            attempt_number: self.attempt_number,
+        }
+    }
+
+    pub(crate) fn complete(
+        self,
+        state: TerminalCommandState,
+        outcome: Value,
+        retention: Duration,
+    ) -> Result<CommandCompletion, CommandLedgerError> {
+        self.complete_with_obligations(state, outcome, Vec::new(), retention)
+    }
+
+    pub(crate) fn complete_with_obligations(
+        self,
+        state: TerminalCommandState,
+        outcome: Value,
+        projection_obligations: Vec<ResolvedProjectionObligation>,
+        retention: Duration,
+    ) -> Result<CommandCompletion, CommandLedgerError> {
+        validate_positive_duration("command replay retention", retention)?;
+        validate_projection_obligation_semantics(state.into(), &projection_obligations)
+            .map_err(CommandLedgerError::Invalid)?;
+        let replay = serde_json::to_string(&serde_json::json!({
+            "version": COMMAND_REPLAY_VERSION,
+            "outcome": outcome,
+            "projection_obligations": projection_obligations,
+        }))
+        .map_err(|error| {
+            CommandLedgerError::Invalid(format!(
+                "command replay serialization failed before commit: {error}"
+            ))
+        })?;
+        Ok(CommandCompletion {
+            attempt: self,
+            state,
+            replay,
+            direct_projection: None,
+            retention,
+        })
+    }
+}
+
+/// Read-only snapshot of one attempt generation, safe to retain while the
+/// owned [`CommandAttempt`] is consumed by completion.
+#[derive(Clone, Debug)]
+pub(crate) struct AttemptFence {
+    pub(super) key: CommandLedgerKey,
+    pub(super) contract_fingerprint: CommandContractFingerprint,
+    pub(super) input_hash: CanonicalInputHash,
+    pub(super) causation_id: CausationId,
+    pub(super) attempt_token: AttemptToken,
+    pub(super) attempt_number: u64,
+}
+
+impl AttemptFence {
+    pub(crate) fn key(&self) -> &CommandLedgerKey {
+        &self.key
+    }
+
+    pub(crate) fn causation_id(&self) -> &CausationId {
+        &self.causation_id
+    }
+
+    pub(crate) fn attempt_token(&self) -> &AttemptToken {
+        &self.attempt_token
+    }
+
+    pub(crate) fn attempt_number(&self) -> u64 {
+        self.attempt_number
+    }
+
+    pub(crate) fn contract_fingerprint_bytes(&self) -> &[u8; SHA256_BYTES] {
+        self.contract_fingerprint.as_bytes()
+    }
+
+    pub(crate) fn input_hash_bytes(&self) -> &[u8; SHA256_BYTES] {
+        self.input_hash.as_bytes()
+    }
+}
+
+/// Authorization scope for a command-ledger lookup.
+///
+/// Public status reads are bound to the selected command route. Ambiguous
+/// commit recovery instead presents the private attempt fence retained by the
+/// dispatcher, so it can recover a terminal outcome without trusting a route
+/// name supplied by the caller.
+#[derive(Clone, Copy, Debug)]
+pub(crate) enum CommandLookupScope<'a> {
+    CommandName(&'a str),
+    CommandContract {
+        command_name: &'a str,
+        contract_fingerprint: &'a [u8; SHA256_BYTES],
+    },
+    Attempt(&'a AttemptFence),
+}
+
+impl fmt::Debug for CommandAttempt {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("CommandAttempt")
+            .field("key", &self.key)
+            .field("causation_id", &self.causation_id)
+            .field("attempt_token", &"[redacted]")
+            .field("attempt_number", &self.attempt_number)
+            .finish()
+    }
+}
+
+/// A terminal command replay recovered without invoking application code.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct CommandReplay {
+    pub(crate) command_id: CommandId,
+    pub(crate) state: CommandLedgerState,
+    pub(crate) causation_id: CausationId,
+    pub(crate) outcome: Value,
+    pub(crate) projection_obligations: Vec<ResolvedProjectionObligation>,
+    /// Exact original direct-projection revision/change evidence.
+    ///
+    /// This is intentionally retained as the validated canonical replay value:
+    /// clients replay the original command outcome, while framework recovery
+    /// and diagnostics can prove which record version that transaction minted.
+    pub(crate) direct_projection: Option<Value>,
+}
+
+/// Result of one short reservation transaction.
+#[derive(Debug)]
+pub(crate) enum ReservationOutcome {
+    Acquired(CommandAttempt),
+    InProgress {
+        /// Retained for the public receipt/status envelope added by the causal
+        /// protocol layer; private dispatch currently exposes only the state.
+        #[allow(dead_code)]
+        causation_id: CausationId,
+    },
+    Replay(CommandReplay),
+    Conflict,
+    Expired,
+}
+
+/// Authorized status lookup result. Grant checks occur above this private
+/// storage layer; a raw command ID alone never reaches this API.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) enum CommandLookup {
+    InProgress { causation_id: CausationId },
+    RetryableUnknown { causation_id: CausationId },
+    Replay(CommandReplay),
+    Expired,
+    Unknown,
+}
+
+/// Exactly one fenced ledger completion attached to a domain commit.
+pub(crate) struct CommandCompletion {
+    pub(super) attempt: CommandAttempt,
+    pub(super) state: TerminalCommandState,
+    pub(super) replay: String,
+    direct_projection: Option<Value>,
+    pub(super) retention: Duration,
+}
+
+impl CommandCompletion {
+    pub(crate) fn attempt(&self) -> &CommandAttempt {
+        &self.attempt
+    }
+
+    pub(crate) fn state(&self) -> TerminalCommandState {
+        self.state
+    }
+
+    pub(crate) fn replay_json(&self) -> &str {
+        &self.replay
+    }
+
+    pub(crate) fn retention(&self) -> Duration {
+        self.retention
+    }
+
+    pub(crate) fn attempt_fence(&self) -> AttemptFence {
+        self.attempt.fence()
+    }
+
+    /// Attach adapter-allocated same-transaction projection evidence before
+    /// the ledger row is completed in that same transaction.
+    pub(crate) fn attach_direct_projection(
+        &mut self,
+        evidence: &SameTransactionProjectionEvidence,
+    ) -> Result<(), CommandLedgerError> {
+        if self.state != TerminalCommandState::Projected {
+            return Err(CommandLedgerError::Invalid(
+                "direct projection evidence may only complete a projected command".into(),
+            ));
+        }
+        if self.direct_projection.is_some() {
+            return Err(CommandLedgerError::Invalid(
+                "command completion already contains direct projection evidence".into(),
+            ));
+        }
+        let direct_projection = evidence.replay_value();
+        SameTransactionProjectionEvidence::validate_replay_value(&direct_projection)
+            .map_err(CommandLedgerError::Invalid)?;
+
+        let replay: Value = serde_json::from_str(&self.replay).map_err(|error| {
+            CommandLedgerError::Invalid(format!(
+                "command replay could not be extended with direct projection evidence: {error}"
+            ))
+        })?;
+        let Value::Object(mut replay) = replay else {
+            return Err(CommandLedgerError::Invalid(
+                "command replay envelope is not an object".into(),
+            ));
+        };
+        if replay
+            .insert("direct_projection".into(), direct_projection.clone())
+            .is_some()
+        {
+            return Err(CommandLedgerError::Invalid(
+                "command replay already has a direct projection field".into(),
+            ));
+        }
+        self.replay = serde_json::to_string(&replay).map_err(|error| {
+            CommandLedgerError::Invalid(format!(
+                "command replay serialization failed after direct projection: {error}"
+            ))
+        })?;
+        self.direct_projection = Some(direct_projection);
+        Ok(())
+    }
+
+    pub(super) fn validate_direct_projection(&self) -> Result<(), CommandLedgerError> {
+        match (self.state, self.direct_projection.is_some()) {
+            (TerminalCommandState::Projected, true)
+            | (
+                TerminalCommandState::Accepted
+                | TerminalCommandState::AcceptedPendingProjection
+                | TerminalCommandState::Rejected,
+                false,
+            ) => Ok(()),
+            (TerminalCommandState::Projected, false) => Err(CommandLedgerError::Invalid(
+                "projected command completion has no exact direct projection evidence".into(),
+            )),
+            (_, true) => Err(CommandLedgerError::Invalid(
+                "non-projected command completion contains direct projection evidence".into(),
+            )),
+        }
+    }
+}
+
+/// Existing public domain batch plus exactly one private ledger completion.
+pub(crate) struct CausalCommitBatch<'a> {
+    pub(crate) domain: CommitBatch<'a>,
+    pub(crate) completion: CommandCompletion,
+    pub(crate) direct_projection: Option<SameTransactionProjectionBatch>,
+}
+
+impl<'a> CausalCommitBatch<'a> {
+    pub(crate) fn new(domain: CommitBatch<'a>, completion: CommandCompletion) -> Self {
+        Self::build(domain, completion, None)
+    }
+
+    pub(crate) fn with_direct_projection(
+        domain: CommitBatch<'a>,
+        completion: CommandCompletion,
+        direct_projection: SameTransactionProjectionBatch,
+    ) -> Self {
+        Self::build(domain, completion, Some(direct_projection))
+    }
+
+    fn build(
+        mut domain: CommitBatch<'a>,
+        completion: CommandCompletion,
+        direct_projection: Option<SameTransactionProjectionBatch>,
+    ) -> Self {
+        // The attempt's stable causation is authoritative at the final boundary:
+        // handler metadata cannot accidentally (or deliberately) split the
+        // event/outbox effects from their durable command identity.
+        let causation_id = completion.attempt().causation_id().as_str();
+        for stream in &mut domain.streams {
+            stream.entity.overwrite_new_event_causation_id(causation_id);
+        }
+        for message in &mut domain.outbox_messages {
+            message.overwrite_causation_id(causation_id);
+        }
+        Self {
+            domain,
+            completion,
+            direct_projection,
+        }
+    }
+}
diff --git a/src/command_ledger/state.rs b/src/command_ledger/state.rs
new file mode 100644
index 00000000..8e990da8
--- /dev/null
+++ b/src/command_ledger/state.rs
@@ -0,0 +1,155 @@
+use std::collections::HashSet;
+
+use crate::projection_protocol::ResolvedProjectionObligation;
+
+use super::CommandLedgerError;
+
+/// Durable command lifecycle. `Unknown` is intentionally not stored: absence
+/// is represented by [`CommandLookup::Unknown`].
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum CommandLedgerState {
+    InProgress,
+    RetryableUnknown,
+    Accepted,
+    AcceptedPendingProjection,
+    Projected,
+    Rejected,
+    ProjectionFailed,
+    Expired,
+}
+
+impl CommandLedgerState {
+    pub(crate) fn as_str(self) -> &'static str {
+        match self {
+            Self::InProgress => "in_progress",
+            Self::RetryableUnknown => "retryable_unknown",
+            Self::Accepted => "accepted",
+            Self::AcceptedPendingProjection => "accepted_pending_projection",
+            Self::Projected => "projected",
+            Self::Rejected => "rejected",
+            Self::ProjectionFailed => "projection_failed",
+            Self::Expired => "expired",
+        }
+    }
+
+    pub(crate) fn parse(value: &str) -> Result<Self, CommandLedgerError> {
+        match value {
+            "in_progress" => Ok(Self::InProgress),
+            "retryable_unknown" => Ok(Self::RetryableUnknown),
+            "accepted" => Ok(Self::Accepted),
+            "accepted_pending_projection" => Ok(Self::AcceptedPendingProjection),
+            "projected" => Ok(Self::Projected),
+            "rejected" => Ok(Self::Rejected),
+            "projection_failed" => Ok(Self::ProjectionFailed),
+            "expired" => Ok(Self::Expired),
+            other => Err(CommandLedgerError::Corrupt(format!(
+                "stored command ledger state `{other}` is invalid"
+            ))),
+        }
+    }
+
+    pub(super) fn is_replayable(self) -> bool {
+        matches!(
+            self,
+            Self::Accepted
+                | Self::AcceptedPendingProjection
+                | Self::Projected
+                | Self::Rejected
+                | Self::ProjectionFailed
+        )
+    }
+}
+
+/// States the command dispatcher may commit through an attempt fence.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum TerminalCommandState {
+    Accepted,
+    AcceptedPendingProjection,
+    Projected,
+    Rejected,
+}
+
+impl From<TerminalCommandState> for CommandLedgerState {
+    fn from(value: TerminalCommandState) -> Self {
+        match value {
+            TerminalCommandState::Accepted => Self::Accepted,
+            TerminalCommandState::AcceptedPendingProjection => Self::AcceptedPendingProjection,
+            TerminalCommandState::Projected => Self::Projected,
+            TerminalCommandState::Rejected => Self::Rejected,
+        }
+    }
+}
+
+pub(super) fn validate_projection_obligation_semantics(
+    state: CommandLedgerState,
+    obligations: &[ResolvedProjectionObligation],
+) -> Result<(), String> {
+    match state {
+        CommandLedgerState::Accepted
+        | CommandLedgerState::Projected
+        | CommandLedgerState::Rejected => {
+            if !obligations.is_empty() {
+                return Err(format!(
+                    "state `{}` must not contain projection obligations",
+                    state.as_str()
+                ));
+            }
+        }
+        CommandLedgerState::AcceptedPendingProjection | CommandLedgerState::ProjectionFailed => {
+            if obligations.is_empty() {
+                return Err(format!(
+                    "state `{}` must contain at least one projection obligation",
+                    state.as_str()
+                ));
+            }
+        }
+        _ => {
+            return Err(format!(
+                "state `{}` cannot contain a replay payload",
+                state.as_str()
+            ));
+        }
+    }
+
+    for (obligation_index, obligation) in obligations.iter().enumerate() {
+        if obligation.projector.trim().is_empty() {
+            return Err(format!(
+                "projection obligation {obligation_index} has a blank projector"
+            ));
+        }
+        if obligation.model.trim().is_empty() {
+            return Err(format!(
+                "projection obligation {obligation_index} has a blank model"
+            ));
+        }
+        if obligation.scope.topology().name() != obligation.projector
+            || obligation.scope.model() != obligation.model
+        {
+            return Err(format!(
+                "projection obligation {obligation_index} logical projector/model does not match its exact canonical scope"
+            ));
+        }
+        if obligation.key.fields.is_empty() {
+            return Err(format!(
+                "projection obligation {obligation_index} has no key fields"
+            ));
+        }
+
+        let mut seen_fields = HashSet::with_capacity(obligation.key.fields.len());
+        for (field_index, field) in obligation.key.fields.iter().enumerate() {
+            if field.field.trim().is_empty() {
+                return Err(format!(
+                    "projection obligation {obligation_index} key field {field_index} has a blank name"
+                ));
+            }
+            if !seen_fields.insert(field.field.as_str()) {
+                return Err(format!(
+                    "projection obligation {obligation_index} contains duplicate key field `{}`",
+                    field.field
+                ));
+            }
+        }
+    }
+
+    Ok(())
+}
diff --git a/src/command_ledger/tests.rs b/src/command_ledger/tests.rs
new file mode 100644
index 00000000..7792ccde
--- /dev/null
+++ b/src/command_ledger/tests.rs
@@ -0,0 +1,1642 @@
+use super::*;
+use std::time::{Duration, SystemTime};
+
+use uuid::{Uuid, Variant};
+
+use super::ids::COMMAND_REPLAY_VERSION;
+use crate::entity::Entity;
+use crate::microsvc::HasOutboxStore;
+use crate::outbox::{OutboxMessage, OutboxMessageStatus};
+use crate::outbox_worker::OutboxStore;
+use crate::projection_protocol::{
+    ProjectionChange, ProjectionChangeCursor, ProjectionChangeKind, ProjectionEpoch,
+    ProjectionObservation, ProjectionObservationKind, ProjectionPartition,
+    ProjectionRecordMetadata, ProjectionRecordScope, ProjectorTopologyId, RecordRevision,
+    ResolvedProjectionKey, ResolvedProjectionKeyField, ResolvedProjectionObligation,
+    SameTransactionProjectionEvidence,
+};
+use crate::read_model::{ReadModelWritePlanBuilder, RelationalReadModel};
+use crate::repository::{
+    CommitBatch, GetStream, InboxReceipt, InboxStore, RelationalReadModelQueryStore, SnapshotStore,
+    SnapshotWrite, StreamIdentity, StreamWrite,
+};
+use crate::snapshot::SnapshotRecord;
+use crate::table::{
+    ColumnType, PrimaryKey, RowKey, RowValue, RowValues, TableColumn, TableKind, TableSchema,
+    TableSchemaRegistry, TableStoreError,
+};
+
+#[derive(Clone, Debug)]
+struct LedgerConformanceView {
+    id: String,
+    marker: String,
+}
+
+impl RelationalReadModel for LedgerConformanceView {
+    fn schema() -> &'static TableSchema {
+        static SCHEMA: std::sync::LazyLock<TableSchema> =
+            std::sync::LazyLock::new(|| TableSchema {
+                model_name: "LedgerConformanceView".into(),
+                table_name: "command_ledger_conformance_views".into(),
+                columns: vec![
+                    TableColumn {
+                        primary_key: true,
+                        ..TableColumn::new("id", "id", ColumnType::Text)
+                    },
+                    TableColumn::new("marker", "marker", ColumnType::Text),
+                ],
+                primary_key: PrimaryKey::new(["id"]),
+                version_column: Some(crate::table::DEFAULT_TABLE_VERSION_COLUMN.into()),
+                foreign_keys: Vec::new(),
+                indexes: Vec::new(),
+                relationships: Vec::new(),
+                kind: TableKind::ReadModel,
+            });
+        &SCHEMA
+    }
+
+    fn primary_key(&self) -> Result<RowKey, TableStoreError> {
+        Ok(RowKey::new([("id", RowValue::String(self.id.clone()))]))
+    }
+
+    fn to_row(&self) -> Result<RowValues, TableStoreError> {
+        let mut row = RowValues::new();
+        row.insert("id", RowValue::String(self.id.clone()));
+        row.insert("marker", RowValue::String(self.marker.clone()));
+        Ok(row)
+    }
+
+    fn from_row(row: RowValues) -> Result<Self, TableStoreError> {
+        Ok(Self {
+            id: row.get_serde("id")?,
+            marker: row.get_serde("marker")?,
+        })
+    }
+}
+
+fn conformance_table_registry() -> TableSchemaRegistry {
+    let mut registry = TableSchemaRegistry::new();
+    registry
+        .register::<LedgerConformanceView>()
+        .expect("ledger conformance schema should register");
+    registry
+}
+
+fn resolved_obligation(marker: &str) -> ResolvedProjectionObligation {
+    let projector = format!("projector-{marker}");
+    let topology =
+        crate::projection_protocol::ProjectorTopologyId::new(1, &projector, [7; 32]).unwrap();
+    let partition =
+        crate::projection_protocol::ProjectionPartition::new(b"test-partition".to_vec()).unwrap();
+    let scope = crate::projection_protocol::ProjectionRecordScope::new(
+        topology,
+        partition,
+        "LedgerConformanceView",
+        format!("key-{marker}").into_bytes(),
+    )
+    .unwrap();
+    ResolvedProjectionObligation {
+        projector,
+        model: "LedgerConformanceView".into(),
+        key: ResolvedProjectionKey {
+            fields: vec![ResolvedProjectionKeyField {
+                field: "id".into(),
+                value: serde_json::json!({"wire": marker, "wide": "18446744073709551615"}),
+            }],
+        },
+        partition: Some(serde_json::Value::Null),
+        scope,
+    }
+}
+
+fn direct_projection_evidence(marker: &str) -> SameTransactionProjectionEvidence {
+    let topology = ProjectorTopologyId::new(1, "ledger-direct-projector", [0x42; 32]).unwrap();
+    let partition = ProjectionPartition::new(format!("partition:{marker}")).unwrap();
+    let epoch = ProjectionEpoch::new("ledger-direct-v1").unwrap();
+    let scope = ProjectionRecordScope::new(
+        topology.clone(),
+        partition.clone(),
+        "LedgerConformanceView",
+        format!("key:{marker}"),
+    )
+    .unwrap();
+    let revision = RecordRevision::new(scope.clone(), 1, 1).unwrap();
+    let cursor = ProjectionChangeCursor::new(topology, partition, epoch, 1).unwrap();
+    let record = ProjectionRecordMetadata {
+        revision: revision.clone(),
+        tombstone: false,
+        change: cursor.clone(),
+    };
+    let change = ProjectionChange {
+        cursor: cursor.clone(),
+        kind: ProjectionChangeKind::RecordUpsert,
+        causation_id: format!("cause:{marker}"),
+        observation_kind: None,
+        scope: Some(scope.clone()),
+        revision: Some(revision.clone()),
+        failure_id: None,
+    };
+    let observation = ProjectionObservation {
+        causation_id: format!("cause:{marker}"),
+        kind: ProjectionObservationKind::Record,
+        revision: Some(revision),
+        scope,
+        change: cursor,
+    };
+    SameTransactionProjectionEvidence {
+        records: vec![record],
+        changes: vec![change],
+        observations: vec![observation],
+    }
+}
+
+fn attach_test_direct_projection(
+    mut completion: CommandCompletion,
+    marker: &str,
+) -> CommandCompletion {
+    completion
+        .attach_direct_projection(&direct_projection_evidence(marker))
+        .unwrap();
+    completion
+}
+
+fn fresh_attempt() -> CommandAttempt {
+    let request = reservation(&Uuid::now_v7().to_string(), 1, 2).unwrap();
+    CommandLedgerRecord::initial(&request, SystemTime::now())
+        .unwrap()
+        .acquired_attempt()
+        .unwrap()
+}
+
+fn completed_replay_record(
+    state: CommandLedgerState,
+    obligations: Vec<ResolvedProjectionObligation>,
+) -> CommandLedgerRecord {
+    let request = reservation(&Uuid::now_v7().to_string(), 1, 2).unwrap();
+    let started = SystemTime::UNIX_EPOCH + Duration::from_secs(100);
+    let mut row = CommandLedgerRecord::initial(&request, started).unwrap();
+    row.state = state;
+    row.attempt_token = None;
+    row.lease_expires_at = None;
+    row.outcome_json = Some(
+        serde_json::json!({
+            "version": COMMAND_REPLAY_VERSION,
+            "outcome": {"ok": true},
+            "projection_obligations": obligations,
+        })
+        .to_string(),
+    );
+    row.updated_at = started + Duration::from_secs(1);
+    row.completed_at = Some(started + Duration::from_secs(1));
+    row
+}
+
+fn reservation_for_partition(
+    command_id: &str,
+    principal_partition: &str,
+    command_name: &str,
+    contract: u8,
+    input: u8,
+) -> Result<CommandReservation, CommandLedgerError> {
+    reservation_for_partition_with_policy(
+        command_id,
+        principal_partition,
+        command_name,
+        contract,
+        input,
+        Duration::from_secs(30),
+        Duration::from_secs(300),
+    )
+}
+
+fn reservation_for_partition_with_policy(
+    command_id: &str,
+    principal_partition: &str,
+    command_name: &str,
+    contract: u8,
+    input: u8,
+    lease: Duration,
+    retention: Duration,
+) -> Result<CommandReservation, CommandLedgerError> {
+    CommandReservation::new(
+        CommandLedgerKey::new(
+            "orders",
+            PrincipalPartitionId::new(principal_partition)?,
+            CommandId::parse(command_id)?,
+        )?,
+        command_name,
+        CommandContractFingerprint::new([contract; 32]),
+        CanonicalInputHash::new([input; 32]),
+        lease,
+        retention,
+    )
+}
+
+fn reservation(
+    command_id: &str,
+    contract: u8,
+    input: u8,
+) -> Result<CommandReservation, CommandLedgerError> {
+    reservation_for_partition(
+        command_id,
+        "v1:sha256:principal",
+        "order.create",
+        contract,
+        input,
+    )
+}
+
+trait CommandLedgerAdapterConformance:
+    CommandLedgerStore
+    + CausalTransactionalCommit
+    + GetStream
+    + SnapshotStore
+    + InboxStore
+    + RelationalReadModelQueryStore
+    + HasOutboxStore
+{
+}
+
+impl<T> CommandLedgerAdapterConformance for T where
+    T: CommandLedgerStore
+        + CausalTransactionalCommit
+        + GetStream
+        + SnapshotStore
+        + InboxStore
+        + RelationalReadModelQueryStore
+        + HasOutboxStore
+{
+}
+
+async fn acquire<R>(repo: &R, request: CommandReservation) -> CommandAttempt
+where
+    R: CommandLedgerStore,
+{
+    match repo.reserve_command(request).await.unwrap() {
+        ReservationOutcome::Acquired(attempt) => attempt,
+        other => panic!("expected acquired command attempt, got {other:?}"),
+    }
+}
+
+async fn same_input_retries_and_identity_conflicts_conform<R>(repo: &R)
+where
+    R: CommandLedgerAdapterConformance,
+{
+    let id = Uuid::now_v7().to_string();
+    let request = reservation(&id, 11, 12).unwrap();
+    let key = request.key().clone();
+    let attempt = acquire(repo, request).await;
+    let causation = attempt.causation_id().clone();
+
+    match repo
+        .reserve_command(reservation(&id, 11, 12).unwrap())
+        .await
+        .unwrap()
+    {
+        ReservationOutcome::InProgress { causation_id } => {
+            assert_eq!(causation_id, causation)
+        }
+        other => panic!("same-input retry should remain in progress, got {other:?}"),
+    }
+    assert!(matches!(
+        repo.reserve_command(reservation(&id, 11, 99).unwrap())
+            .await
+            .unwrap(),
+        ReservationOutcome::Conflict
+    ));
+    assert!(matches!(
+        repo.reserve_command(
+            reservation_for_partition(&id, "v1:sha256:principal", "order.cancel", 11, 12,).unwrap(),
+        )
+        .await
+        .unwrap(),
+        ReservationOutcome::Conflict
+    ));
+
+    let expected_outcome = serde_json::json!({"order_id": "same-input"});
+    let completion = attempt
+        .complete(
+            TerminalCommandState::Accepted,
+            expected_outcome.clone(),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    repo.commit_causal_batch(CausalCommitBatch::new(CommitBatch::empty(), completion))
+        .await
+        .unwrap();
+
+    let reserved_replay = match repo
+        .reserve_command(reservation(&id, 11, 12).unwrap())
+        .await
+        .unwrap()
+    {
+        ReservationOutcome::Replay(replay) => replay,
+        other => panic!("completed same-input retry should replay, got {other:?}"),
+    };
+    assert_eq!(
+        repo.lookup_command(&key, CommandLookupScope::CommandName("order.cancel"))
+            .await
+            .unwrap(),
+        CommandLookup::Unknown,
+        "status lookup must not disclose a command owned by a different route"
+    );
+    let wrong_contract = [99; SHA256_BYTES];
+    assert_eq!(
+        repo.lookup_command(
+            &key,
+            CommandLookupScope::CommandContract {
+                command_name: "order.create",
+                contract_fingerprint: &wrong_contract,
+            },
+        )
+        .await
+        .unwrap(),
+        CommandLookup::Unknown,
+        "status lookup must not disclose a command owned by a drifted contract"
+    );
+    let current_contract = [11; SHA256_BYTES];
+    let contract_lookup = repo
+        .lookup_command(
+            &key,
+            CommandLookupScope::CommandContract {
+                command_name: "order.create",
+                contract_fingerprint: &current_contract,
+            },
+        )
+        .await
+        .unwrap();
+    let lookup_replay = match repo
+        .lookup_command(&key, CommandLookupScope::CommandName("order.create"))
+        .await
+        .unwrap()
+    {
+        CommandLookup::Replay(replay) => replay,
+        other => panic!("completed command lookup should replay, got {other:?}"),
+    };
+    assert_eq!(
+        contract_lookup,
+        CommandLookup::Replay(lookup_replay.clone())
+    );
+    assert_eq!(reserved_replay, lookup_replay);
+    assert_eq!(reserved_replay.state, CommandLedgerState::Accepted);
+    assert_eq!(reserved_replay.causation_id, causation);
+    assert_eq!(reserved_replay.outcome, expected_outcome);
+    assert!(reserved_replay.projection_obligations.is_empty());
+}
+
+async fn concurrent_reservations_have_one_winner_and_one_causation<R>(repo: &R)
+where
+    R: CommandLedgerAdapterConformance,
+{
+    let id = Uuid::now_v7().to_string();
+    let left = reservation(&id, 16, 17).unwrap();
+    let right = reservation(&id, 16, 17).unwrap();
+    let (left, right) = tokio::join!(repo.reserve_command(left), repo.reserve_command(right));
+    let outcomes = (left.unwrap(), right.unwrap());
+    let (winner, observed_causation) = match outcomes {
+        (
+            ReservationOutcome::Acquired(winner),
+            ReservationOutcome::InProgress { causation_id },
+        )
+        | (
+            ReservationOutcome::InProgress { causation_id },
+            ReservationOutcome::Acquired(winner),
+        ) => (winner, causation_id),
+        other => panic!(
+            "concurrent reservations should have one winner and one in-progress observer, got {other:?}"
+        ),
+    };
+    assert_eq!(winner.causation_id(), &observed_causation);
+
+    let completion = winner
+        .complete(
+            TerminalCommandState::Accepted,
+            serde_json::json!({"concurrent_winner": true}),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    repo.commit_causal_batch(CausalCommitBatch::new(CommitBatch::empty(), completion))
+        .await
+        .unwrap();
+}
+
+async fn expired_lease_reclaims_through_the_adapter_clock<R>(repo: &R)
+where
+    R: CommandLedgerAdapterConformance,
+{
+    let id = Uuid::now_v7().to_string();
+    let short_lease = reservation_for_partition_with_policy(
+        &id,
+        "v1:sha256:principal",
+        "order.create",
+        18,
+        19,
+        Duration::from_millis(100),
+        Duration::from_secs(300),
+    )
+    .unwrap();
+    let first = acquire(repo, short_lease).await;
+    let causation = first.causation_id().clone();
+    let first_token = first.attempt_token().as_str().to_string();
+
+    tokio::time::sleep(Duration::from_millis(300)).await;
+    let second = acquire(repo, reservation(&id, 18, 19).unwrap()).await;
+    assert_eq!(second.causation_id(), &causation);
+    assert_eq!(second.attempt_number(), 2);
+    assert_ne!(second.attempt_token().as_str(), first_token);
+
+    let completion = second
+        .complete(
+            TerminalCommandState::Accepted,
+            serde_json::json!({"lease_reclaimed": true}),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    repo.commit_causal_batch(CausalCommitBatch::new(CommitBatch::empty(), completion))
+        .await
+        .unwrap();
+}
+
+async fn terminal_replays_are_deterministic<R>(repo: &R)
+where
+    R: CommandLedgerAdapterConformance,
+{
+    let terminal_states = [
+        (TerminalCommandState::Accepted, CommandLedgerState::Accepted),
+        (
+            TerminalCommandState::AcceptedPendingProjection,
+            CommandLedgerState::AcceptedPendingProjection,
+        ),
+        (
+            TerminalCommandState::Projected,
+            CommandLedgerState::Projected,
+        ),
+        (TerminalCommandState::Rejected, CommandLedgerState::Rejected),
+    ];
+
+    for (index, (terminal_state, ledger_state)) in terminal_states.into_iter().enumerate() {
+        let id = Uuid::now_v7().to_string();
+        let request = reservation(&id, 21, index as u8 + 1).unwrap();
+        let key = request.key().clone();
+        let attempt = acquire(repo, request).await;
+        let causation = attempt.causation_id().clone();
+        let expected_outcome = serde_json::json!({
+            "terminal": ledger_state.as_str(),
+            "index": index,
+        });
+        let expected_obligations =
+            if terminal_state == TerminalCommandState::AcceptedPendingProjection {
+                vec![resolved_obligation(&format!("terminal-{index}"))]
+            } else {
+                Vec::new()
+            };
+        let mut completion = attempt
+            .complete_with_obligations(
+                terminal_state,
+                expected_outcome.clone(),
+                expected_obligations.clone(),
+                Duration::from_secs(300),
+            )
+            .unwrap();
+        let expected_direct_projection =
+            (terminal_state == TerminalCommandState::Projected).then(|| {
+                let evidence = direct_projection_evidence(&format!("terminal-{index}"));
+                completion.attach_direct_projection(&evidence).unwrap();
+                evidence.replay_value()
+            });
+        repo.commit_causal_batch(CausalCommitBatch::new(CommitBatch::empty(), completion))
+            .await
+            .unwrap();
+
+        let first = match repo
+            .lookup_command(&key, CommandLookupScope::CommandName("order.create"))
+            .await
+            .unwrap()
+        {
+            CommandLookup::Replay(replay) => replay,
+            other => panic!("terminal lookup should replay, got {other:?}"),
+        };
+        let second = match repo
+            .reserve_command(reservation(&id, 21, index as u8 + 1).unwrap())
+            .await
+            .unwrap()
+        {
+            ReservationOutcome::Replay(replay) => replay,
+            other => panic!("terminal reservation should replay, got {other:?}"),
+        };
+        assert_eq!(first, second);
+        assert_eq!(first.state, ledger_state);
+        assert_eq!(first.causation_id, causation);
+        assert_eq!(first.outcome, expected_outcome);
+        assert_eq!(first.projection_obligations, expected_obligations);
+        assert_eq!(first.direct_projection, expected_direct_projection);
+    }
+}
+
+async fn response_loss_replays_outcome_and_projection_obligations<R>(repo: &R)
+where
+    R: CommandLedgerAdapterConformance,
+{
+    let id = Uuid::now_v7().to_string();
+    let attempt = acquire(repo, reservation(&id, 31, 32).unwrap()).await;
+    let causation = attempt.causation_id().clone();
+    let expected_outcome = serde_json::json!({"order_id": "response-lost"});
+    let expected_obligations = vec![resolved_obligation("response-loss")];
+    let completion = attempt
+        .complete_with_obligations(
+            TerminalCommandState::AcceptedPendingProjection,
+            expected_outcome.clone(),
+            expected_obligations.clone(),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+
+    // Model a committed transaction whose HTTP/GraphQL acknowledgement was
+    // lost: the caller knows only that it must retry the same command ID.
+    repo.commit_causal_batch(CausalCommitBatch::new(CommitBatch::empty(), completion))
+        .await
+        .unwrap();
+
+    match repo
+        .reserve_command(reservation(&id, 31, 32).unwrap())
+        .await
+        .unwrap()
+    {
+        ReservationOutcome::Replay(replay) => {
+            assert_eq!(replay.state, CommandLedgerState::AcceptedPendingProjection);
+            assert_eq!(replay.causation_id, causation);
+            assert_eq!(replay.outcome, expected_outcome);
+            assert_eq!(replay.projection_obligations, expected_obligations);
+        }
+        other => panic!("retry after response loss should replay, got {other:?}"),
+    }
+}
+
+async fn retryable_unknown_reclaims_with_stable_causation<R>(repo: &R)
+where
+    R: CommandLedgerAdapterConformance,
+{
+    let id = Uuid::now_v7().to_string();
+    let request = reservation(&id, 41, 42).unwrap();
+    let key = request.key().clone();
+    let first = acquire(repo, request).await;
+    let causation = first.causation_id().clone();
+    let first_token = first.attempt_token().as_str().to_string();
+    repo.mark_retryable_unknown(first.fence()).await.unwrap();
+
+    match repo
+        .lookup_command(&key, CommandLookupScope::CommandName("order.create"))
+        .await
+        .unwrap()
+    {
+        CommandLookup::RetryableUnknown { causation_id } => {
+            assert_eq!(causation_id, causation)
+        }
+        other => panic!("abandoned attempt should be retryable-unknown, got {other:?}"),
+    }
+
+    let second = acquire(repo, reservation(&id, 41, 42).unwrap()).await;
+    assert_eq!(second.causation_id(), &causation);
+    assert_eq!(second.attempt_number(), 2);
+    assert_ne!(second.attempt_token().as_str(), first_token);
+    let completion = second
+        .complete(
+            TerminalCommandState::Accepted,
+            serde_json::json!({"reclaimed": true}),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    repo.commit_causal_batch(CausalCommitBatch::new(CommitBatch::empty(), completion))
+        .await
+        .unwrap();
+}
+
+async fn principal_partitions_are_isolated<R>(repo: &R)
+where
+    R: CommandLedgerAdapterConformance,
+{
+    let id = Uuid::now_v7().to_string();
+    let first_request =
+        reservation_for_partition(&id, "v1:sha256:principal-a", "order.create", 51, 52).unwrap();
+    let first_key = first_request.key().clone();
+    let first = acquire(repo, first_request).await;
+    let first_causation = first.causation_id().clone();
+    let first_outcome = serde_json::json!({"partition": "a"});
+    let completion = first
+        .complete(
+            TerminalCommandState::Accepted,
+            first_outcome.clone(),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    repo.commit_causal_batch(CausalCommitBatch::new(CommitBatch::empty(), completion))
+        .await
+        .unwrap();
+
+    let second_request =
+        reservation_for_partition(&id, "v1:sha256:principal-b", "order.create", 51, 52).unwrap();
+    let second_key = second_request.key().clone();
+    let second = acquire(repo, second_request).await;
+    let second_causation = second.causation_id().clone();
+    assert_ne!(second_causation, first_causation);
+    let second_outcome = serde_json::json!({"partition": "b"});
+    let completion = second
+        .complete(
+            TerminalCommandState::Rejected,
+            second_outcome.clone(),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    repo.commit_causal_batch(CausalCommitBatch::new(CommitBatch::empty(), completion))
+        .await
+        .unwrap();
+
+    let first_replay = match repo
+        .lookup_command(&first_key, CommandLookupScope::CommandName("order.create"))
+        .await
+        .unwrap()
+    {
+        CommandLookup::Replay(replay) => replay,
+        other => panic!("first principal should retain its replay, got {other:?}"),
+    };
+    let second_replay = match repo
+        .lookup_command(&second_key, CommandLookupScope::CommandName("order.create"))
+        .await
+        .unwrap()
+    {
+        CommandLookup::Replay(replay) => replay,
+        other => panic!("second principal should retain its replay, got {other:?}"),
+    };
+    assert_eq!(first_replay.state, CommandLedgerState::Accepted);
+    assert_eq!(first_replay.outcome, first_outcome);
+    assert_eq!(first_replay.causation_id, first_causation);
+    assert_eq!(second_replay.state, CommandLedgerState::Rejected);
+    assert_eq!(second_replay.outcome, second_outcome);
+    assert_eq!(second_replay.causation_id, second_causation);
+}
+
+async fn committed_events_and_outbox_round_trip_ledger_causation<R>(repo: &R)
+where
+    R: CommandLedgerAdapterConformance,
+{
+    let id = Uuid::now_v7().to_string();
+    let request = reservation(&id, 56, 57).unwrap();
+    let key = request.key().clone();
+    let attempt = acquire(repo, request).await;
+    let causation = attempt.causation_id().as_str().to_string();
+
+    let aggregate_id = format!("ledger-causation-stream-{}", Uuid::now_v7());
+    let identity = StreamIdentity::new("command-ledger-conformance", &aggregate_id).unwrap();
+    let mut entity = Entity::with_id(&aggregate_id);
+    entity.set_causation_id("handler-event-causation-must-be-replaced");
+    entity.digest_empty("CommandLedgerCausationEvent").unwrap();
+
+    let outbox_id = format!("ledger-causation-outbox-{}", Uuid::now_v7());
+    let mut message = OutboxMessage::create(
+        outbox_id.clone(),
+        "CommandLedgerCausationFact",
+        b"{}".to_vec(),
+    )
+    .unwrap();
+    message.set_causation_id("handler-outbox-causation-must-be-replaced");
+
+    let completion = attempt
+        .complete(
+            TerminalCommandState::Accepted,
+            serde_json::json!({"causation": "committed"}),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    let mut domain = CommitBatch::new(vec![StreamWrite::new(identity.clone(), &mut entity)]);
+    domain.outbox_messages.push(message);
+    repo.commit_causal_batch(CausalCommitBatch::new(domain, completion))
+        .await
+        .unwrap();
+
+    let stored_stream = repo
+        .get_stream(&identity)
+        .await
+        .unwrap()
+        .expect("causal stream should persist");
+    assert_eq!(stored_stream.events().len(), 1);
+    assert_eq!(
+        stored_stream.events()[0].causation_id(),
+        Some(causation.as_str())
+    );
+
+    let stored_message = repo
+        .outbox_store()
+        .messages_by_status(OutboxMessageStatus::Pending, 1_000)
+        .await
+        .unwrap()
+        .into_iter()
+        .find(|message| message.id() == outbox_id)
+        .expect("causal outbox message should persist");
+    assert_eq!(stored_message.causation_id(), Some(causation.as_str()));
+    match repo
+        .lookup_command(&key, CommandLookupScope::CommandName("order.create"))
+        .await
+        .unwrap()
+    {
+        CommandLookup::Replay(replay) => {
+            assert_eq!(replay.causation_id.as_str(), causation)
+        }
+        other => panic!("causal command should replay after commit, got {other:?}"),
+    }
+}
+
+async fn stale_fence_rolls_back_every_commit_participant<R>(repo: &R)
+where
+    R: CommandLedgerAdapterConformance,
+{
+    let id = Uuid::now_v7().to_string();
+    let key = reservation(&id, 61, 62).unwrap().key().clone();
+    let first = acquire(repo, reservation(&id, 61, 62).unwrap()).await;
+    repo.mark_retryable_unknown(first.fence()).await.unwrap();
+    let second = acquire(repo, reservation(&id, 61, 62).unwrap()).await;
+    let live_causation = second.causation_id().clone();
+
+    let aggregate_id = format!("ledger-stale-stream-{}", Uuid::now_v7());
+    let identity = StreamIdentity::new("command-ledger-conformance", &aggregate_id).unwrap();
+    let mut entity = Entity::with_id(&aggregate_id);
+    entity
+        .digest_empty("CommandLedgerConformanceEvent")
+        .unwrap();
+
+    let outbox_id = format!("ledger-stale-outbox-{}", Uuid::now_v7());
+    let outbox_message = OutboxMessage::create(
+        outbox_id.clone(),
+        "CommandLedgerConformanceFact",
+        b"{}".to_vec(),
+    )
+    .unwrap();
+
+    let read_model_id = format!("ledger-stale-view-{}", Uuid::now_v7());
+    let view = LedgerConformanceView {
+        id: read_model_id.clone(),
+        marker: "must-roll-back".into(),
+    };
+    let mut read_models = ReadModelWritePlanBuilder::new();
+    read_models.upsert(&view).unwrap();
+
+    let inbox_consumer = format!("ledger-consumer-{}", Uuid::now_v7());
+    let inbox_message_id = format!("ledger-message-{}", Uuid::now_v7());
+    let snapshot = SnapshotRecord::new(
+        identity.aggregate_type(),
+        identity.aggregate_id(),
+        1,
+        1,
+        vec![1, 2, 3],
+    );
+
+    let stale_completion = first
+        .complete(
+            TerminalCommandState::Accepted,
+            serde_json::json!({"winner": false}),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    let mut domain = CommitBatch::new(vec![StreamWrite::new(identity.clone(), &mut entity)]);
+    domain.outbox_messages.push(outbox_message);
+    domain
+        .read_model_plans
+        .push(read_models.into_write_plan().unwrap());
+    domain.snapshots.push(SnapshotWrite::Save {
+        identity: identity.clone(),
+        record: snapshot,
+    });
+    domain.inbox_receipts.push(InboxReceipt::new(
+        inbox_consumer.clone(),
+        inbox_message_id.clone(),
+    ));
+
+    let stale_result = repo
+        .commit_causal_batch(CausalCommitBatch::new(domain, stale_completion))
+        .await;
+    assert!(
+        matches!(stale_result, Err(CommandLedgerError::AttemptFenced { .. })),
+        "stale causal commit should be fenced after every participant is staged, got {stale_result:?}"
+    );
+
+    assert!(repo.get_stream(&identity).await.unwrap().is_none());
+    let pending = repo
+        .outbox_store()
+        .messages_by_status(OutboxMessageStatus::Pending, 1_000)
+        .await
+        .unwrap();
+    assert!(pending.iter().all(|message| message.id() != outbox_id));
+    let load = ReadModelWritePlanBuilder::new()
+        .load::<LedgerConformanceView>(RowKey::new([("id", RowValue::String(read_model_id))]))
+        .unwrap();
+    assert!(repo.load_graph(load).await.unwrap().root.is_none());
+    assert!(repo.get_snapshot(&identity).await.unwrap().is_none());
+    assert!(!repo
+        .inbox_contains(&inbox_consumer, &inbox_message_id)
+        .await
+        .unwrap());
+    match repo
+        .lookup_command(&key, CommandLookupScope::CommandName("order.create"))
+        .await
+        .unwrap()
+    {
+        CommandLookup::InProgress { causation_id } => {
+            assert_eq!(causation_id, live_causation)
+        }
+        other => panic!("stale commit must leave live attempt untouched, got {other:?}"),
+    }
+
+    let live_completion = second
+        .complete(
+            TerminalCommandState::Accepted,
+            serde_json::json!({"winner": true}),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    repo.commit_causal_batch(CausalCommitBatch::new(
+        CommitBatch::empty(),
+        live_completion,
+    ))
+    .await
+    .unwrap();
+}
+
+async fn compacted_expiry_is_a_permanent_tombstone<R>(repo: &R)
+where
+    R: CommandLedgerAdapterConformance,
+{
+    let id = Uuid::now_v7().to_string();
+    let request = reservation(&id, 71, 72).unwrap();
+    let key = request.key().clone();
+    let attempt = acquire(repo, request).await;
+    let completion = attempt
+        .complete(
+            TerminalCommandState::Accepted,
+            serde_json::json!({"short_lived": true}),
+            Duration::from_millis(100),
+        )
+        .unwrap();
+    repo.commit_causal_batch(CausalCommitBatch::new(CommitBatch::empty(), completion))
+        .await
+        .unwrap();
+
+    tokio::time::sleep(Duration::from_millis(300)).await;
+    assert!(repo.compact_expired_commands(1_000).await.unwrap() >= 1);
+    assert_eq!(
+        repo.lookup_command(&key, CommandLookupScope::CommandName("order.create"))
+            .await
+            .unwrap(),
+        CommandLookup::Expired
+    );
+    assert!(matches!(
+        repo.reserve_command(reservation(&id, 71, 72).unwrap())
+            .await
+            .unwrap(),
+        ReservationOutcome::Expired
+    ));
+    assert!(matches!(
+        repo.reserve_command(reservation(&id, 99, 99).unwrap())
+            .await
+            .unwrap(),
+        ReservationOutcome::Expired
+    ));
+}
+
+async fn run_command_ledger_adapter_conformance<R>(repo: &R)
+where
+    R: CommandLedgerAdapterConformance,
+{
+    same_input_retries_and_identity_conflicts_conform(repo).await;
+    concurrent_reservations_have_one_winner_and_one_causation(repo).await;
+    expired_lease_reclaims_through_the_adapter_clock(repo).await;
+    terminal_replays_are_deterministic(repo).await;
+    response_loss_replays_outcome_and_projection_obligations(repo).await;
+    retryable_unknown_reclaims_with_stable_causation(repo).await;
+    principal_partitions_are_isolated(repo).await;
+    committed_events_and_outbox_round_trip_ledger_causation(repo).await;
+    stale_fence_rolls_back_every_commit_participant(repo).await;
+    compacted_expiry_is_a_permanent_tombstone(repo).await;
+}
+
+#[test]
+fn command_id_requires_uuid_v7_and_canonicalizes() {
+    let id = Uuid::now_v7().simple().to_string().to_uppercase();
+    let parsed = CommandId::parse(id).unwrap();
+    assert_eq!(
+        Uuid::parse_str(parsed.as_str()).unwrap().get_version_num(),
+        7
+    );
+    assert!(CommandId::parse("67e55044-10b1-426f-9247-bb680e5fe0c8").is_err());
+    assert!(CommandId::parse("not-a-uuid").is_err());
+}
+
+#[test]
+fn uuid_v7_identities_require_the_rfc4122_variant() {
+    let mut bytes = *Uuid::now_v7().as_bytes();
+    bytes[8] &= 0x7f;
+    let ncs_variant_v7 = Uuid::from_bytes(bytes);
+    assert_eq!(ncs_variant_v7.get_version_num(), 7);
+    assert_eq!(ncs_variant_v7.get_variant(), Variant::NCS);
+    let spelling = ncs_variant_v7.hyphenated().to_string();
+
+    assert!(matches!(
+        CommandId::parse(&spelling),
+        Err(CommandLedgerError::Invalid(_))
+    ));
+    assert!(matches!(
+        CausationId::parse_stored(spelling.clone()),
+        Err(CommandLedgerError::Corrupt(_))
+    ));
+    assert!(matches!(
+        AttemptToken::parse_stored(spelling),
+        Err(CommandLedgerError::Corrupt(_))
+    ));
+
+    let valid = Uuid::now_v7().to_string();
+    assert!(CommandId::parse(&valid).is_ok());
+    assert!(CausationId::parse_stored(valid.clone()).is_ok());
+    assert!(AttemptToken::parse_stored(valid).is_ok());
+}
+
+#[test]
+fn prefixed_sha256_parser_is_checked_and_canonical() {
+    let encoded = format!("sha256:{}", "ab".repeat(32));
+    assert_eq!(
+        CanonicalInputHash::parse_sha256(&encoded)
+            .unwrap()
+            .as_bytes(),
+        &[0xab; 32]
+    );
+    assert!(CanonicalInputHash::parse_sha256(&"ab".repeat(32)).is_err());
+    assert!(
+        CommandContractFingerprint::parse_sha256(&format!("sha256:{}", "AB".repeat(32))).is_err()
+    );
+    assert!(CommandContractFingerprint::parse_sha256("sha256:00").is_err());
+}
+
+#[test]
+fn contract_and_input_hashes_are_distinct_identity_components() {
+    let id = Uuid::now_v7().to_string();
+    let now = SystemTime::UNIX_EPOCH + Duration::from_secs(100);
+    let original = reservation(&id, 1, 2).unwrap();
+    let row = CommandLedgerRecord::initial(&original, now).unwrap();
+
+    let contract_drift = reservation(&id, 9, 2).unwrap();
+    assert_eq!(
+        row.classify_reservation(&contract_drift, now).unwrap(),
+        ReservationDecision::Conflict
+    );
+    let input_drift = reservation(&id, 1, 9).unwrap();
+    assert_eq!(
+        row.classify_reservation(&input_drift, now).unwrap(),
+        ReservationDecision::Conflict
+    );
+}
+
+#[test]
+fn reclaim_preserves_causation_and_rotates_attempt_fence() {
+    let id = Uuid::now_v7().to_string();
+    let initial = reservation(&id, 1, 2).unwrap();
+    let started = SystemTime::UNIX_EPOCH + Duration::from_secs(100);
+    let mut row = CommandLedgerRecord::initial(&initial, started).unwrap();
+    let first_cause = row.causation_id.clone();
+    let first_token = row.attempt_token.as_ref().unwrap().0.clone();
+
+    let retry = reservation(&id, 1, 2).unwrap();
+    let after_lease = started + Duration::from_secs(31);
+    assert_eq!(
+        row.classify_reservation(&retry, after_lease).unwrap(),
+        ReservationDecision::Reclaim
+    );
+    row.reclaim(&retry, after_lease).unwrap();
+
+    assert_eq!(row.causation_id, first_cause);
+    assert_ne!(row.attempt_token.as_ref().unwrap().0, first_token);
+    assert_eq!(row.attempt_number, 2);
+}
+
+#[test]
+fn stale_attempt_cannot_complete_after_reclaim() {
+    let id = Uuid::now_v7().to_string();
+    let initial = reservation(&id, 1, 2).unwrap();
+    let started = SystemTime::UNIX_EPOCH + Duration::from_secs(100);
+    let mut row = CommandLedgerRecord::initial(&initial, started).unwrap();
+    let stale = row.acquired_attempt().unwrap();
+
+    let retry = reservation(&id, 1, 2).unwrap();
+    row.reclaim(&retry, started + Duration::from_secs(31))
+        .unwrap();
+    let completion = stale
+        .complete(
+            TerminalCommandState::Accepted,
+            serde_json::json!({"ok": true}),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+
+    assert!(matches!(
+        row.complete(&completion, started + Duration::from_secs(32)),
+        Err(CommandLedgerError::AttemptFenced { .. })
+    ));
+}
+
+#[test]
+fn completion_rejects_inconsistent_projection_obligation_states() {
+    for state in [
+        TerminalCommandState::Accepted,
+        TerminalCommandState::Projected,
+        TerminalCommandState::Rejected,
+    ] {
+        assert!(matches!(
+            fresh_attempt().complete_with_obligations(
+                state,
+                serde_json::json!({"ok": true}),
+                vec![resolved_obligation("unexpected")],
+                Duration::from_secs(300),
+            ),
+            Err(CommandLedgerError::Invalid(_))
+        ));
+    }
+
+    assert!(matches!(
+        fresh_attempt().complete_with_obligations(
+            TerminalCommandState::AcceptedPendingProjection,
+            serde_json::json!({"ok": true}),
+            Vec::new(),
+            Duration::from_secs(300),
+        ),
+        Err(CommandLedgerError::Invalid(_))
+    ));
+
+    for state in [
+        TerminalCommandState::Accepted,
+        TerminalCommandState::Projected,
+        TerminalCommandState::Rejected,
+    ] {
+        assert!(fresh_attempt()
+            .complete(
+                state,
+                serde_json::json!({"ok": true}),
+                Duration::from_secs(300),
+            )
+            .is_ok());
+    }
+    assert!(fresh_attempt()
+        .complete_with_obligations(
+            TerminalCommandState::AcceptedPendingProjection,
+            serde_json::json!({"ok": true}),
+            vec![resolved_obligation("pending")],
+            Duration::from_secs(300),
+        )
+        .is_ok());
+}
+
+#[test]
+fn completion_rejects_malformed_projection_obligations() {
+    let mut blank_projector = resolved_obligation("blank-projector");
+    blank_projector.projector = " \t".into();
+    let mut blank_model = resolved_obligation("blank-model");
+    blank_model.model = "\n".into();
+    let mut empty_key = resolved_obligation("empty-key");
+    empty_key.key.fields.clear();
+    let mut blank_field = resolved_obligation("blank-field");
+    blank_field.key.fields[0].field = "  ".into();
+    let mut duplicate_field = resolved_obligation("duplicate-field");
+    duplicate_field
+        .key
+        .fields
+        .push(duplicate_field.key.fields[0].clone());
+
+    for malformed in [
+        blank_projector,
+        blank_model,
+        empty_key,
+        blank_field,
+        duplicate_field,
+    ] {
+        assert!(matches!(
+            fresh_attempt().complete_with_obligations(
+                TerminalCommandState::AcceptedPendingProjection,
+                serde_json::json!({"ok": true}),
+                vec![malformed],
+                Duration::from_secs(300),
+            ),
+            Err(CommandLedgerError::Invalid(_))
+        ));
+    }
+}
+
+#[test]
+fn replay_rejects_inconsistent_projection_obligation_states() {
+    for state in [
+        CommandLedgerState::Accepted,
+        CommandLedgerState::Projected,
+        CommandLedgerState::Rejected,
+    ] {
+        let row = completed_replay_record(state, vec![resolved_obligation("unexpected")]);
+        assert!(row.validate_stored_shape().is_ok());
+        assert!(matches!(row.replay(), Err(CommandLedgerError::Corrupt(_))));
+    }
+
+    for state in [
+        CommandLedgerState::AcceptedPendingProjection,
+        CommandLedgerState::ProjectionFailed,
+    ] {
+        let row = completed_replay_record(state, Vec::new());
+        assert!(row.validate_stored_shape().is_ok());
+        assert!(matches!(row.replay(), Err(CommandLedgerError::Corrupt(_))));
+    }
+
+    let projection_failed = completed_replay_record(
+        CommandLedgerState::ProjectionFailed,
+        vec![resolved_obligation("failed")],
+    );
+    let replay = projection_failed.replay().unwrap();
+    assert_eq!(replay.state, CommandLedgerState::ProjectionFailed);
+    assert_eq!(replay.projection_obligations.len(), 1);
+}
+
+#[test]
+fn replay_rejects_malformed_projection_obligations() {
+    let mut blank_projector = resolved_obligation("blank-projector");
+    blank_projector.projector = " ".into();
+    let mut blank_model = resolved_obligation("blank-model");
+    blank_model.model.clear();
+    let mut empty_key = resolved_obligation("empty-key");
+    empty_key.key.fields.clear();
+    let mut blank_field = resolved_obligation("blank-field");
+    blank_field.key.fields[0].field = "\r\n".into();
+    let mut duplicate_field = resolved_obligation("duplicate-field");
+    duplicate_field
+        .key
+        .fields
+        .push(duplicate_field.key.fields[0].clone());
+
+    for malformed in [
+        blank_projector,
+        blank_model,
+        empty_key,
+        blank_field,
+        duplicate_field,
+    ] {
+        let row = completed_replay_record(
+            CommandLedgerState::AcceptedPendingProjection,
+            vec![malformed],
+        );
+        assert!(row.validate_stored_shape().is_ok());
+        assert!(matches!(row.replay(), Err(CommandLedgerError::Corrupt(_))));
+    }
+}
+
+#[test]
+fn replay_validates_envelope_and_returns_only_the_outcome() {
+    let id = Uuid::now_v7().to_string();
+    let reservation = reservation(&id, 1, 2).unwrap();
+    let started = SystemTime::UNIX_EPOCH + Duration::from_secs(100);
+    let mut row = CommandLedgerRecord::initial(&reservation, started).unwrap();
+    let obligation = resolved_obligation("round-trip");
+    let completion = row
+        .acquired_attempt()
+        .unwrap()
+        .complete_with_obligations(
+            TerminalCommandState::AcceptedPendingProjection,
+            serde_json::json!({"order_id": "o-1"}),
+            vec![obligation.clone()],
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    row.complete(&completion, started + Duration::from_secs(1))
+        .unwrap();
+    let replay = row.replay().unwrap();
+    assert_eq!(replay.outcome, serde_json::json!({"order_id": "o-1"}));
+    assert_eq!(replay.projection_obligations, vec![obligation.clone()]);
+
+    row.outcome_json = Some(r#"{"version":1,"outcome":null}"#.into());
+    assert!(matches!(row.replay(), Err(CommandLedgerError::Corrupt(_))));
+
+    let mut obligation_with_unknown_field = serde_json::to_value(obligation).unwrap();
+    obligation_with_unknown_field
+        .as_object_mut()
+        .unwrap()
+        .insert("unknown".into(), serde_json::json!(true));
+    row.outcome_json = Some(
+        serde_json::json!({
+            "version": 1,
+            "outcome": null,
+            "projection_obligations": [obligation_with_unknown_field],
+        })
+        .to_string(),
+    );
+    assert!(matches!(row.replay(), Err(CommandLedgerError::Corrupt(_))));
+
+    row.outcome_json = Some(r#"{"version":2,"outcome":null,"projection_obligations":[]}"#.into());
+    assert!(matches!(row.replay(), Err(CommandLedgerError::Corrupt(_))));
+}
+
+#[test]
+fn causal_batch_applies_the_authoritative_stamp_at_the_final_boundary() {
+    use crate::outbox::OutboxMessage;
+    use crate::repository::StreamWrite;
+
+    let id = Uuid::now_v7().to_string();
+    let reservation = reservation(&id, 1, 2).unwrap();
+    let row = CommandLedgerRecord::initial(&reservation, SystemTime::now()).unwrap();
+    let attempt = row.acquired_attempt().unwrap();
+    let causation = attempt.causation_id().as_str().to_string();
+    let completion = attempt
+        .complete(
+            TerminalCommandState::Accepted,
+            serde_json::json!({"ok": true}),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+
+    let mut entity = Entity::with_id("order-1");
+    entity.set_causation_id("handler-event-cause");
+    entity.digest_empty("OrderCreated").unwrap();
+    let mut message = OutboxMessage::create("fact-1", "OrderCreated", vec![]).unwrap();
+    message.set_causation_id("handler-fact-cause");
+    let mut domain = CommitBatch::new(vec![StreamWrite::new(
+        StreamIdentity::new("order", "order-1").unwrap(),
+        &mut entity,
+    )]);
+    domain.outbox_messages.push(message);
+
+    let causal = CausalCommitBatch::new(domain, completion);
+    assert_eq!(
+        causal.domain.streams[0].entity.new_events()[0].causation_id(),
+        Some(causation.as_str())
+    );
+    assert_eq!(
+        causal.domain.outbox_messages[0].causation_id(),
+        Some(causation.as_str())
+    );
+}
+
+#[tokio::test]
+async fn in_memory_command_ledger_adapter_conformance() {
+    use crate::in_memory_repo::InMemoryRepository;
+
+    let repo = InMemoryRepository::new();
+    repo.model_store()
+        .register_schema::<LedgerConformanceView>()
+        .unwrap();
+    run_command_ledger_adapter_conformance(&repo).await;
+}
+
+#[cfg(feature = "sqlite")]
+#[tokio::test]
+async fn sqlite_command_ledger_adapter_conformance() {
+    use crate::SqliteRepository;
+
+    let repo = SqliteRepository::connect_and_migrate("sqlite::memory:")
+        .await
+        .unwrap();
+    repo.bootstrap_table_schema_for_dev(&conformance_table_registry())
+        .await
+        .unwrap();
+    run_command_ledger_adapter_conformance(&repo).await;
+}
+
+#[cfg(feature = "sqlite")]
+#[tokio::test]
+async fn sqlite_terminal_replay_survives_pool_drop_and_reopen() {
+    use std::ffi::OsString;
+    use std::path::PathBuf;
+
+    use crate::SqliteRepository;
+
+    struct TempSqliteDatabase {
+        directory: PathBuf,
+        database: PathBuf,
+    }
+
+    impl TempSqliteDatabase {
+        fn new() -> Self {
+            let directory = std::env::temp_dir().join(format!(
+                "distributed-command-ledger-restart-{}",
+                Uuid::now_v7()
+            ));
+            std::fs::create_dir(&directory).unwrap();
+            let database = directory.join("ledger.sqlite3");
+            Self {
+                directory,
+                database,
+            }
+        }
+
+        fn url(&self) -> String {
+            format!(
+                "sqlite://{}?mode=rwc",
+                self.database
+                    .to_str()
+                    .expect("temporary SQLite path must be valid UTF-8")
+            )
+        }
+    }
+
+    impl Drop for TempSqliteDatabase {
+        fn drop(&mut self) {
+            for suffix in ["", "-shm", "-wal", "-journal"] {
+                let mut path = OsString::from(self.database.as_os_str());
+                path.push(suffix);
+                let _ = std::fs::remove_file(PathBuf::from(path));
+            }
+            let _ = std::fs::remove_dir(&self.directory);
+        }
+    }
+
+    let database = TempSqliteDatabase::new();
+    let database_url = database.url();
+    let repo = SqliteRepository::connect_and_migrate(&database_url)
+        .await
+        .unwrap();
+
+    let command_id = Uuid::now_v7().to_string();
+    let request = reservation(&command_id, 81, 82).unwrap();
+    let key = request.key().clone();
+    let attempt = acquire(&repo, request).await;
+    let expected_causation = attempt.causation_id().clone();
+    let expected_outcome = serde_json::json!({"order_id": "restart-order"});
+    let expected_obligations = vec![resolved_obligation("sqlite-restart")];
+
+    let aggregate_id = format!("sqlite-restart-stream-{}", Uuid::now_v7());
+    let identity = StreamIdentity::new("command-ledger-restart", &aggregate_id).unwrap();
+    let mut entity = Entity::with_id(&aggregate_id);
+    entity.digest_empty("SqliteRestartCommitted").unwrap();
+    let outbox_id = format!("sqlite-restart-outbox-{}", Uuid::now_v7());
+    let outbox_message =
+        OutboxMessage::create(&outbox_id, "SqliteRestartCommitted", b"{}".to_vec()).unwrap();
+
+    let completion = attempt
+        .complete_with_obligations(
+            TerminalCommandState::AcceptedPendingProjection,
+            expected_outcome.clone(),
+            expected_obligations.clone(),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    let mut domain = CommitBatch::new(vec![StreamWrite::new(identity.clone(), &mut entity)]);
+    domain.outbox_messages.push(outbox_message);
+    repo.commit_causal_batch(CausalCommitBatch::new(domain, completion))
+        .await
+        .unwrap();
+
+    repo.pool().close().await;
+    drop(repo);
+
+    let reopened = SqliteRepository::connect_and_migrate(&database_url)
+        .await
+        .unwrap();
+    let replay = match reopened
+        .lookup_command(&key, CommandLookupScope::CommandName("order.create"))
+        .await
+        .unwrap()
+    {
+        CommandLookup::Replay(replay) => replay,
+        other => panic!("reopened SQLite ledger should replay, got {other:?}"),
+    };
+    assert_eq!(replay.state, CommandLedgerState::AcceptedPendingProjection);
+    assert_eq!(replay.causation_id, expected_causation);
+    assert_eq!(replay.outcome, expected_outcome);
+    assert_eq!(replay.projection_obligations, expected_obligations);
+
+    let stored_stream = reopened
+        .get_stream(&identity)
+        .await
+        .unwrap()
+        .expect("reopened SQLite repository should retain the causal event stream");
+    assert_eq!(stored_stream.events().len(), 1);
+    assert_eq!(
+        stored_stream.events()[0].causation_id(),
+        Some(expected_causation.as_str())
+    );
+    let stored_outbox = reopened
+        .outbox_store()
+        .messages_by_status(OutboxMessageStatus::Pending, 1_000)
+        .await
+        .unwrap()
+        .into_iter()
+        .find(|message| message.id() == outbox_id)
+        .expect("reopened SQLite repository should retain the causal outbox fact");
+    assert_eq!(
+        stored_outbox.causation_id(),
+        Some(expected_causation.as_str())
+    );
+
+    reopened.pool().close().await;
+    drop(reopened);
+}
+
+#[cfg(feature = "postgres")]
+#[test]
+fn postgres_command_ledger_adapter_conformance_typechecks() {
+    fn assert_conformance<R: CommandLedgerAdapterConformance>() {}
+    assert_conformance::<crate::PostgresRepository>();
+}
+
+#[cfg(feature = "postgres")]
+#[tokio::test]
+async fn postgres_command_ledger_adapter_conformance_when_database_available() {
+    use crate::PostgresRepository;
+
+    let Ok(database_url) = std::env::var("DATABASE_URL") else {
+        eprintln!("skipping Postgres command-ledger conformance test without DATABASE_URL");
+        return;
+    };
+    let repo = PostgresRepository::connect_and_migrate(&database_url)
+        .await
+        .unwrap();
+    repo.bootstrap_table_schema_for_dev(&conformance_table_registry())
+        .await
+        .unwrap();
+    run_command_ledger_adapter_conformance(&repo).await;
+}
+
+#[tokio::test]
+async fn in_memory_adapter_reclaims_and_replays_with_a_stable_causation() {
+    use crate::in_memory_repo::InMemoryRepository;
+
+    let repo = InMemoryRepository::new();
+    assert_eq!(
+        repo.causal_storage_identity(),
+        repo.clone().causal_storage_identity()
+    );
+    assert_ne!(
+        repo.causal_storage_identity(),
+        InMemoryRepository::new().causal_storage_identity()
+    );
+
+    let id = Uuid::now_v7().to_string();
+    let first = match repo
+        .reserve_command(reservation(&id, 1, 2).unwrap())
+        .await
+        .unwrap()
+    {
+        ReservationOutcome::Acquired(attempt) => attempt,
+        other => panic!("expected acquired attempt, got {other:?}"),
+    };
+    let cause = first.causation_id().clone();
+    let first_token = first.attempt_token().as_str().to_string();
+    repo.mark_retryable_unknown(first.fence()).await.unwrap();
+
+    let second = match repo
+        .reserve_command(reservation(&id, 1, 2).unwrap())
+        .await
+        .unwrap()
+    {
+        ReservationOutcome::Acquired(attempt) => attempt,
+        other => panic!("expected reclaimed attempt, got {other:?}"),
+    };
+    assert_eq!(second.causation_id(), &cause);
+    assert_ne!(second.attempt_token().as_str(), first_token);
+    assert_eq!(second.attempt_number(), 2);
+
+    let completion = second
+        .complete(
+            TerminalCommandState::Accepted,
+            serde_json::json!({"ok": true}),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    repo.commit_causal_batch(CausalCommitBatch::new(CommitBatch::empty(), completion))
+        .await
+        .unwrap();
+
+    let key = reservation(&id, 1, 2).unwrap().key().clone();
+    match repo
+        .lookup_command(&key, CommandLookupScope::CommandName("order.create"))
+        .await
+        .unwrap()
+    {
+        CommandLookup::Replay(replay) => {
+            assert_eq!(replay.causation_id, cause);
+            assert_eq!(replay.outcome, serde_json::json!({"ok": true}));
+        }
+        other => panic!("expected replay, got {other:?}"),
+    }
+}
+
+#[tokio::test]
+async fn concurrent_in_memory_reservations_have_one_winner_and_one_cause() {
+    use crate::in_memory_repo::InMemoryRepository;
+
+    let repo = InMemoryRepository::new();
+    let id = Uuid::now_v7().to_string();
+    let left = reservation(&id, 5, 6).unwrap();
+    let right = reservation(&id, 5, 6).unwrap();
+    let (left, right) = tokio::join!(repo.reserve_command(left), repo.reserve_command(right));
+    let outcomes = [left.unwrap(), right.unwrap()];
+    let acquired = outcomes
+        .iter()
+        .filter(|outcome| matches!(outcome, ReservationOutcome::Acquired(_)))
+        .count();
+    assert_eq!(acquired, 1);
+    let causes = outcomes
+        .iter()
+        .map(|outcome| match outcome {
+            ReservationOutcome::Acquired(attempt) => attempt.causation_id().as_str(),
+            ReservationOutcome::InProgress { causation_id } => causation_id.as_str(),
+            other => panic!("unexpected concurrent reservation outcome: {other:?}"),
+        })
+        .collect::<Vec<_>>();
+    assert_eq!(causes[0], causes[1]);
+}
+
+#[cfg(feature = "sqlite")]
+#[tokio::test]
+async fn sqlite_adapter_enforces_attempt_fence_and_replays() {
+    use crate::outbox::{OutboxMessage, OutboxMessageStatus};
+    use crate::outbox_worker::OutboxStore;
+    use crate::SqliteRepository;
+
+    let repo = SqliteRepository::connect_and_migrate("sqlite::memory:")
+        .await
+        .unwrap();
+    let id = Uuid::now_v7().to_string();
+    let first = match repo
+        .reserve_command(reservation(&id, 3, 4).unwrap())
+        .await
+        .unwrap()
+    {
+        ReservationOutcome::Acquired(attempt) => attempt,
+        other => panic!("expected acquired attempt, got {other:?}"),
+    };
+    let cause = first.causation_id().clone();
+    repo.mark_retryable_unknown(first.fence()).await.unwrap();
+    let second = match repo
+        .reserve_command(reservation(&id, 3, 4).unwrap())
+        .await
+        .unwrap()
+    {
+        ReservationOutcome::Acquired(attempt) => attempt,
+        other => panic!("expected reclaimed attempt, got {other:?}"),
+    };
+    assert_eq!(second.causation_id(), &cause);
+
+    let stale = first
+        .complete(
+            TerminalCommandState::Accepted,
+            serde_json::json!({"winner": false}),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    let mut stale_domain = CommitBatch::empty();
+    stale_domain
+        .outbox_messages
+        .push(OutboxMessage::create("stale-effect", "ShouldRollback", vec![]).unwrap());
+    assert!(matches!(
+        repo.commit_causal_batch(CausalCommitBatch::new(stale_domain, stale))
+            .await,
+        Err(CommandLedgerError::AttemptFenced { .. })
+    ));
+    assert!(repo
+        .outbox_store()
+        .messages_by_status(OutboxMessageStatus::Pending, 10)
+        .await
+        .unwrap()
+        .is_empty());
+
+    let completion = second
+        .complete(
+            TerminalCommandState::Projected,
+            serde_json::json!({"winner": true}),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+    let completion = attach_test_direct_projection(completion, "sqlite-winner");
+    repo.commit_causal_batch(CausalCommitBatch::new(CommitBatch::empty(), completion))
+        .await
+        .unwrap();
+    let key = reservation(&id, 3, 4).unwrap().key().clone();
+    match repo
+        .lookup_command(&key, CommandLookupScope::CommandName("order.create"))
+        .await
+        .unwrap()
+    {
+        CommandLookup::Replay(replay) => {
+            assert_eq!(replay.state, CommandLedgerState::Projected);
+            assert_eq!(replay.causation_id, cause);
+            assert_eq!(replay.outcome, serde_json::json!({"winner": true}));
+        }
+        other => panic!("expected replay, got {other:?}"),
+    }
+}
+
+#[test]
+fn expiry_is_a_permanent_compact_tombstone() {
+    let id = Uuid::now_v7().to_string();
+    let original = reservation(&id, 1, 2).unwrap();
+    let started = SystemTime::UNIX_EPOCH + Duration::from_secs(100);
+    let mut row = CommandLedgerRecord::initial(&original, started).unwrap();
+    row.expire(started + Duration::from_secs(301));
+
+    let different = reservation(&id, 9, 9).unwrap();
+    assert_eq!(
+        row.classify_reservation(&different, started + Duration::from_secs(302))
+            .unwrap(),
+        ReservationDecision::Expire
+    );
+    assert!(row.outcome_json.is_none());
+    assert!(row.attempt_token.is_none());
+    assert_eq!(row.lookup().unwrap(), CommandLookup::Expired);
+}
diff --git a/src/command_ledger/traits.rs b/src/command_ledger/traits.rs
new file mode 100644
index 00000000..bd678363
--- /dev/null
+++ b/src/command_ledger/traits.rs
@@ -0,0 +1,61 @@
+use std::future::Future;
+
+use crate::entity::Entity;
+use crate::repository::{RepositoryError, StreamIdentity};
+
+use super::{
+    AttemptFence, CausalCommitBatch, CausalStorageIdentity, CommandLedgerError, CommandLedgerKey,
+    CommandLookup, CommandLookupScope, CommandReservation, ReservationOutcome,
+};
+
+/// Read capability used by the causal workspace. Unlike ordinary
+/// `QueuedRepository::get_stream`, wrapper implementations must not retain a
+/// queue lock while user handler code awaits.
+pub(crate) trait CausalGetStream: Send + Sync {
+    fn get_causal_stream<'a>(
+        &'a self,
+        identity: &'a StreamIdentity,
+    ) -> impl Future<Output = Result<Option<Entity>, RepositoryError>> + Send + 'a;
+}
+
+/// Proves that command reservation, stream loading, and causal commit are all
+/// routed to the same concrete leaf repository handle. Wrappers delegate the
+/// opaque value; independently constructed leaves always mint a new one.
+pub(crate) trait CausalRepositoryIdentity: Send + Sync {
+    fn causal_storage_identity(&self) -> CausalStorageIdentity;
+}
+
+/// Short-transaction ledger operations. Lease recovery is part of `reserve` so
+/// an adapter cannot expose a non-atomic read-then-steal sequence.
+pub(crate) trait CommandLedgerStore: Send + Sync {
+    fn reserve_command(
+        &self,
+        reservation: CommandReservation,
+    ) -> impl Future<Output = Result<ReservationOutcome, CommandLedgerError>> + Send + '_;
+
+    fn lookup_command<'a>(
+        &'a self,
+        key: &'a CommandLedgerKey,
+        scope: CommandLookupScope<'a>,
+    ) -> impl Future<Output = Result<CommandLookup, CommandLedgerError>> + Send + 'a;
+
+    fn mark_retryable_unknown(
+        &self,
+        attempt: AttemptFence,
+    ) -> impl Future<Output = Result<(), CommandLedgerError>> + Send + '_;
+
+    #[allow(dead_code)]
+    fn compact_expired_commands(
+        &self,
+        limit: usize,
+    ) -> impl Future<Output = Result<u64, CommandLedgerError>> + Send + '_;
+}
+
+/// Private transaction capability that makes terminal ledger completion an
+/// inseparable participant in the domain commit.
+pub(crate) trait CausalTransactionalCommit: Send + Sync {
+    fn commit_causal_batch<'a>(
+        &'a self,
+        batch: CausalCommitBatch<'a>,
+    ) -> impl Future<Output = Result<(), CommandLedgerError>> + Send + 'a;
+}
diff --git a/src/entity/entity.rs b/src/entity/entity.rs
index ecd44866..0cd3adeb 100644
--- a/src/entity/entity.rs
+++ b/src/entity/entity.rs
@@ -207,6 +207,25 @@ impl Entity {
         self.set_meta(CAUSATION_ID, id);
     }
 
+    /// Overwrite causation on every event not yet committed.
+    ///
+    /// The command ledger chooses the authoritative causation ID only after a
+    /// reservation succeeds. A handler may have emitted events before then or
+    /// replaced entity metadata, so merely configuring metadata for subsequent
+    /// events is insufficient. The causal batch constructor calls this once at
+    /// the final pre-commit boundary.
+    #[cfg_attr(not(feature = "graphql"), allow(dead_code))]
+    pub(crate) fn overwrite_new_event_causation_id(&mut self, id: &str) {
+        let start = (self.committed_version - self.prefix_version) as usize;
+        for event in &mut self.events[start..] {
+            event.overwrite_causation_id(id);
+        }
+        self.metadata
+            .retain(|key, _| !key.eq_ignore_ascii_case(CAUSATION_ID));
+        self.metadata
+            .insert(CAUSATION_ID.to_string(), id.to_string());
+    }
+
     /// Set W3C trace context for subsequent events.
     pub fn set_trace_context(&mut self, context: &TraceContext) {
         context.inject_map(&mut self.metadata);
@@ -607,6 +626,42 @@ mod tests {
         assert!(entity.events()[1].metadata.is_empty());
     }
 
+    #[test]
+    fn final_causal_stamp_overwrites_only_uncommitted_events() {
+        let mut entity = Entity::with_id("aggregate-1");
+        entity.set_causation_id("original-command");
+        entity.digest_empty("Created").unwrap();
+        entity.mark_committed();
+
+        entity.set_causation_id("handler-supplied");
+        entity.set_meta("Causation_Id", "forged-case-alias");
+        entity.digest_empty("Changed").unwrap();
+        entity.overwrite_new_event_causation_id("ledger-causation");
+
+        assert_eq!(entity.events()[0].causation_id(), Some("original-command"));
+        assert_eq!(entity.events()[1].causation_id(), Some("ledger-causation"));
+        assert_eq!(
+            entity.events()[1]
+                .metadata
+                .keys()
+                .filter(|key| key.eq_ignore_ascii_case(CAUSATION_ID))
+                .count(),
+            1
+        );
+        assert_eq!(
+            entity.metadata().get(CAUSATION_ID).map(String::as_str),
+            Some("ledger-causation")
+        );
+        assert_eq!(
+            entity
+                .metadata()
+                .keys()
+                .filter(|key| key.eq_ignore_ascii_case(CAUSATION_ID))
+                .count(),
+            1
+        );
+    }
+
     #[test]
     fn load_tail_records_true_version_without_full_history() {
         // A tail of 2 events after a snapshot prefix of 3: true version is 5,
diff --git a/src/entity/event_record.rs b/src/entity/event_record.rs
index cb4938e3..604962c4 100644
--- a/src/entity/event_record.rs
+++ b/src/entity/event_record.rs
@@ -241,6 +241,19 @@ impl EventRecord {
         self.meta(CAUSATION_ID)
     }
 
+    /// Replace causation metadata at the final causal-commit boundary.
+    ///
+    /// This is deliberately crate-private: application metadata may be set
+    /// while handling a command, but the ledger attempt is authoritative for
+    /// every newly persisted event in that command transaction.
+    #[cfg_attr(not(feature = "graphql"), allow(dead_code))]
+    pub(crate) fn overwrite_causation_id(&mut self, id: &str) {
+        self.metadata
+            .retain(|key, _| !key.eq_ignore_ascii_case(CAUSATION_ID));
+        self.metadata
+            .insert(CAUSATION_ID.to_string(), id.to_string());
+    }
+
     /// Get the W3C `traceparent`, if set.
     pub fn traceparent(&self) -> Option<&str> {
         self.meta(TRACEPARENT)
@@ -356,6 +369,26 @@ mod tests {
         assert_eq!(record.tracestate(), Some("vendor=value"));
     }
 
+    #[test]
+    fn final_causal_stamp_removes_case_insensitive_aliases() {
+        let mut metadata = HashMap::new();
+        metadata.insert(CAUSATION_ID.to_string(), "handler-supplied".to_string());
+        metadata.insert("Causation_Id".to_string(), "forged-case-alias".to_string());
+        let mut record = EventRecord::with_metadata("test_event", vec![], 1, metadata);
+
+        record.overwrite_causation_id("ledger-causation");
+
+        assert_eq!(record.causation_id(), Some("ledger-causation"));
+        assert_eq!(
+            record
+                .metadata
+                .keys()
+                .filter(|key| key.eq_ignore_ascii_case(CAUSATION_ID))
+                .count(),
+            1
+        );
+    }
+
     #[test]
     fn metadata_is_always_present_in_serialization() {
         let record = EventRecord::new("test_event", vec![], 1);
diff --git a/src/graphql/client_manifest/build.rs b/src/graphql/client_manifest/build.rs
new file mode 100644
index 00000000..6f95401a
--- /dev/null
+++ b/src/graphql/client_manifest/build.rs
@@ -0,0 +1,512 @@
+use super::*;
+
+/// Convenience wrapper used heavily by unit tests; production uses
+/// [`client_manifest_from_surface_with_execution`].
+#[cfg_attr(not(test), allow(dead_code))]
+pub(crate) fn client_manifest_from_surface(
+    service_id: &str,
+    identity: ClientSurfaceIdentity,
+    surface: &Surface,
+) -> Result<DistributedClientManifest, ClientManifestError> {
+    client_manifest_from_surface_with_execution(
+        service_id,
+        identity,
+        surface,
+        ClientExecutionLimits::default(),
+    )
+}
+
+pub(super) fn client_manifest_from_surface_with_execution(
+    service_id: &str,
+    identity: ClientSurfaceIdentity,
+    surface: &Surface,
+    execution: ClientExecutionLimits,
+) -> Result<DistributedClientManifest, ClientManifestError> {
+    if service_id.trim().is_empty() {
+        return Err(ClientManifestError("service_id must not be empty".into()));
+    }
+    let identity = identity.canonicalized()?;
+    match (&surface.selection, &identity) {
+        (SurfaceSelection::Catalog, _) => {
+            return Err(ClientManifestError(
+                "client manifests require an explicitly role- or application-selected Surface"
+                    .into(),
+            ));
+        }
+        (SurfaceSelection::Role { name: selected }, ClientSurfaceIdentity::Role { name })
+            if selected == name => {}
+        (
+            SurfaceSelection::Application {
+                name: selected_name,
+                roles: selected_roles,
+            },
+            ClientSurfaceIdentity::Application { name, roles },
+        ) if selected_name == name && selected_roles == roles => {}
+        _ => {
+            return Err(ClientManifestError(
+                "client Surface identity does not match its authorization selection provenance"
+                    .into(),
+            ));
+        }
+    }
+    validate_surface_structure(surface)?;
+
+    let live_models: BTreeSet<&str> = surface
+        .subscription_fields
+        .iter()
+        .filter(|root| root.kind == RootKind::List)
+        .map(|root| root.model_name.as_str())
+        .collect();
+    let mut models = Vec::new();
+    for model in surface.models.values() {
+        let mut fields: Vec<ClientField> = model
+            .columns
+            .iter()
+            .map(|field| {
+                let codec = scalar_codec(&field.scalar).ok_or_else(|| {
+                    ClientManifestError(format!(
+                        "model `{}` field `{}` uses unsupported scalar `{}`",
+                        model.model_name, field.name, field.scalar
+                    ))
+                })?;
+                Ok(ClientField {
+                    name: field.name.clone(),
+                    scalar: field.scalar.clone(),
+                    codec: codec.into(),
+                    nullable: field.nullable,
+                })
+            })
+            .collect::<Result<_, ClientManifestError>>()?;
+        fields.sort_by(|a, b| a.name.cmp(&b.name));
+        let field_by_name: BTreeMap<&str, &ClientField> = fields
+            .iter()
+            .map(|field| (field.name.as_str(), field))
+            .collect();
+        let normalization = if model_has_client_normalized_identity(model) {
+            ModelNormalization::Normalized {
+                fields: model
+                    .primary_key
+                    .iter()
+                    .map(|key| ClientKeyField {
+                        name: key.clone(),
+                        codec: field_by_name[key.as_str()].codec.clone(),
+                    })
+                    .collect(),
+                encoding: KEY_ENCODING.into(),
+            }
+        } else {
+            ModelNormalization::Embedded
+        };
+
+        let mut relationships = Vec::new();
+        for relationship in &model.relationships {
+            let Some(target) = surface.models.get(&relationship.target_model) else {
+                return Err(ClientManifestError(format!(
+                    "surface relationship `{}` targets absent model `{}`",
+                    relationship.name, relationship.target_model
+                )));
+            };
+            let target_field_by_name: BTreeMap<&str, &crate::graphql::surface::ColumnField> =
+                target
+                    .columns
+                    .iter()
+                    .map(|field| (field.name.as_str(), field))
+                    .collect();
+            let source_field_by_name: BTreeMap<&str, &crate::graphql::surface::ColumnField> = model
+                .columns
+                .iter()
+                .map(|field| (field.name.as_str(), field))
+                .collect();
+            let stable_key_mapping = |local: &[String], remote: &[String]| {
+                !local.is_empty()
+                    && local.len() == remote.len()
+                    && local.iter().all(|key| {
+                        source_field_by_name
+                            .get(key.as_str())
+                            .is_some_and(|field| field.scalar != "BigInt")
+                    })
+                    && remote.iter().all(|key| {
+                        target_field_by_name
+                            .get(key.as_str())
+                            .is_some_and(|field| field.scalar != "BigInt")
+                    })
+            };
+            let key_mapping = match &relationship.keys {
+                SurfaceRelationshipKeys::Direct { local, remote }
+                    if stable_key_mapping(local, remote) =>
+                {
+                    RelationshipKeyMapping::Direct {
+                        local: local.clone(),
+                        remote: remote.clone(),
+                    }
+                }
+                SurfaceRelationshipKeys::Through {
+                    local,
+                    remote,
+                    table,
+                    source_foreign_key,
+                    target_foreign_key,
+                } if stable_key_mapping(local, remote) => RelationshipKeyMapping::Through {
+                    local: local.clone(),
+                    remote: remote.clone(),
+                    table: table.clone(),
+                    source_foreign_key: source_foreign_key.clone(),
+                    target_foreign_key: target_foreign_key.clone(),
+                },
+                SurfaceRelationshipKeys::ThroughOpaque {
+                    local,
+                    remote,
+                    dependency,
+                } if stable_key_mapping(local, remote) => RelationshipKeyMapping::ThroughOpaque {
+                    local: local.clone(),
+                    remote: remote.clone(),
+                    dependency: dependency.clone(),
+                },
+                SurfaceRelationshipKeys::Embedded => RelationshipKeyMapping::Embedded,
+                _ => RelationshipKeyMapping::Embedded,
+            };
+            let maintenance = match &key_mapping {
+                RelationshipKeyMapping::Direct { .. } | RelationshipKeyMapping::Through { .. } => {
+                    ClientRelationshipMaintenance::Local
+                }
+                RelationshipKeyMapping::ThroughOpaque { .. } | RelationshipKeyMapping::Embedded => {
+                    ClientRelationshipMaintenance::Revalidate
+                }
+            };
+            relationships.push(ClientRelationship {
+                name: relationship.name.clone(),
+                target_model: relationship.target_model.clone(),
+                target_typename: relationship.target_object.clone(),
+                kind: match relationship.kind {
+                    RelationshipKind::HasMany => ClientRelationshipKind::HasMany,
+                    RelationshipKind::BelongsTo => ClientRelationshipKind::BelongsTo,
+                    RelationshipKind::ManyToMany => ClientRelationshipKind::ManyToMany,
+                },
+                list: relationship.list,
+                nullable: relationship.nullable,
+                arguments: relationship
+                    .arguments
+                    .iter()
+                    .map(argument_manifest)
+                    .collect(),
+                key_mapping,
+                maintenance,
+                dependencies: sorted_unique(relationship.dependencies.clone()),
+                filter: relationship.list.then(|| filter_semantics(surface, target)),
+                order: relationship.list.then(|| order_semantics(target)),
+                pagination: relationship
+                    .list
+                    .then(|| pagination_semantics(surface, target)),
+                aggregate: relationship.aggregate.as_ref().map(|aggregate| {
+                    ClientRelationshipAggregate {
+                        name: aggregate.name.clone(),
+                        arguments: aggregate.arguments.iter().map(argument_manifest).collect(),
+                        semantics: aggregate_semantics(
+                            target,
+                            aggregate.type_name.clone(),
+                            pagination_semantics(surface, target),
+                        ),
+                        dependencies: sorted_unique(aggregate.dependencies.clone()),
+                    }
+                }),
+                live: relationship.list && live_models.contains(relationship.target_model.as_str()),
+            });
+        }
+        relationships.sort_by(|a, b| a.name.cmp(&b.name));
+        let filter_input = filter_input(surface, model)?;
+        let causal_owner = model_has_visible_causal_owner(surface, &model.model_name);
+        models.push(ClientModel {
+            id: model.model_name.clone(),
+            typename: model.object_name.clone(),
+            source_table: model.table_name.clone(),
+            dependencies: vec![model.table_name.clone()],
+            normalization,
+            fields,
+            relationships,
+            filter_input,
+            row_policy: row_policy_manifest(&model.row_policy),
+            // `_sourced_version` is only source metadata. These flags derive
+            // from the role-visible Task 15 causal owner, never that column.
+            record_revisions: causal_owner,
+            tombstones: causal_owner,
+        });
+    }
+    models.sort_by(|a, b| a.id.cmp(&b.id));
+
+    let mut roots = Vec::new();
+    for (operation, fields) in [
+        (ClientRootOperation::Query, &surface.query_fields),
+        (
+            ClientRootOperation::Subscription,
+            &surface.subscription_fields,
+        ),
+    ] {
+        for root in fields {
+            let model = surface.models.get(&root.model_name).ok_or_else(|| {
+                ClientManifestError(format!(
+                    "root `{}` references absent model `{}`",
+                    root.name, root.model_name
+                ))
+            })?;
+            let has_filter = root
+                .arguments
+                .iter()
+                .any(|argument| argument.kind == SurfaceArgumentKind::Filter);
+            let filter = has_filter.then(|| filter_semantics(surface, model));
+            let has_order = root
+                .arguments
+                .iter()
+                .any(|argument| argument.kind == SurfaceArgumentKind::Order);
+            let order = has_order.then(|| order_semantics(model));
+            let pagination =
+                root.default_limit
+                    .zip(root.max_limit)
+                    .map(|(default_limit, max_limit)| ClientPaginationSemantics {
+                        kind: "offset".into(),
+                        default_limit,
+                        max_limit,
+                        coverage: "window".into(),
+                    });
+            let aggregate = matches!(root.kind, RootKind::Aggregate).then(|| {
+                aggregate_semantics(
+                    model,
+                    aggregate_type_name(&model.schema),
+                    pagination_semantics(surface, model),
+                )
+            });
+            roots.push(ClientRoot {
+                id: format!(
+                    "{}:{}",
+                    match operation {
+                        ClientRootOperation::Query => "query",
+                        ClientRootOperation::Subscription => "subscription",
+                    },
+                    root.name
+                ),
+                operation,
+                name: root.name.clone(),
+                kind: match root.kind {
+                    RootKind::List => ClientRootKind::List,
+                    RootKind::ByPk => ClientRootKind::ByPk,
+                    RootKind::Aggregate => ClientRootKind::Aggregate,
+                },
+                model: root.model_name.clone(),
+                arguments: root.arguments.iter().map(argument_manifest).collect(),
+                filter,
+                order,
+                pagination,
+                aggregate,
+                dependencies: sorted_unique(root.dependencies.clone()),
+                live: operation == ClientRootOperation::Subscription
+                    || surface.subscription_fields.iter().any(|candidate| {
+                        candidate.name == root.name && candidate.kind == root.kind
+                    }),
+            });
+        }
+    }
+    roots.sort_by(|a, b| a.id.cmp(&b.id));
+
+    let mut commands = Vec::new();
+    for command in &surface.commands {
+        let input = command_shape(&command.input)?;
+        let output = command_shape(&command.output)?;
+        let grants = sorted_unique(command.roles.clone());
+        let operation = command_operation(&command.field_name, &input, &output);
+        let operation_hash = hash_bytes(operation.as_bytes());
+        let consistency = CommandConsistencyExtension {
+            version: 1,
+            kind: match command.consistency {
+                CommandConsistency::Accepted => "accepted",
+                CommandConsistency::Fact => "fact",
+                CommandConsistency::Projected => "projected",
+            }
+            .into(),
+        };
+        let direct_projection = command_direct_projection_extension(command, surface)?;
+        let input_defaults = (!command.input_defaults.is_empty())
+            .then(|| {
+                command
+                    .input_defaults
+                    .iter()
+                    .map(|default| serde_json::to_value(default).map(canonical_json_value))
+                    .collect::<Result<Vec<_>, _>>()
+                    .map(|defaults| CommandInputDefaultsExtension {
+                        version: 1,
+                        defaults,
+                    })
+            })
+            .transpose()?;
+        let effects = command
+            .effects
+            .as_ref()
+            .map(|effects| {
+                let operations = effects
+                    .operations
+                    .iter()
+                    .map(|operation| serde_json::to_value(operation).map(canonical_json_value))
+                    .collect::<Result<Vec<_>, _>>()?;
+                let fallback = match effects.fallback {
+                    CommandEffectFallback::Revalidate => "revalidate",
+                };
+                Ok::<_, serde_json::Error>(CommandEffectsExtension {
+                    version: 1,
+                    operations,
+                    fallback: fallback.into(),
+                })
+            })
+            .transpose()?;
+        let confirmations = if command.confirmation_unavailable {
+            Some(CommandConfirmationsExtension {
+                version: COMMAND_CONFIRMATIONS_VERSION,
+                kind: "unavailable".into(),
+                expected: Vec::new(),
+                fallback: "revalidate".into(),
+            })
+        } else {
+            (!command.confirmations.is_empty() || command.consistency == CommandConsistency::Fact)
+                .then(|| {
+                    command
+                        .confirmations
+                        .iter()
+                        .map(|confirmation| {
+                            serde_json::to_value(confirmation).map(canonical_json_value)
+                        })
+                        .collect::<Result<Vec<_>, _>>()
+                        .map(|expected| CommandConfirmationsExtension {
+                            version: COMMAND_CONFIRMATIONS_VERSION,
+                            kind: "finite".into(),
+                            expected,
+                            fallback: "revalidate".into(),
+                        })
+                })
+                .transpose()?
+        };
+        let trusted_presets = command_trusted_preset_descriptors(command, surface)?;
+        commands.push(ClientCommand {
+            version: 1,
+            name: command.command_name.clone(),
+            mutation_field: command.field_name.clone(),
+            grants,
+            input,
+            output,
+            operation,
+            operation_hash,
+            extensions: ClientCommandExtensionSlots {
+                version: COMMAND_EXTENSION_SLOTS_VERSION,
+                consistency,
+                direct_projection,
+                input_defaults,
+                effects,
+                confirmations,
+                trusted_presets,
+            },
+        });
+    }
+    commands.sort_by(|a, b| a.name.cmp(&b.name));
+
+    let command_status = (!commands.is_empty()).then(|| {
+        let operation = command_status_operation();
+        ClientProtocolOperation {
+            name: "Distributed_CommandStatus".into(),
+            operation_hash: hash_bytes(operation.as_bytes()),
+            operation,
+        }
+    });
+    let protocol_operations = ClientProtocolOperations {
+        version: PROTOCOL_OPERATIONS_VERSION,
+        command_status,
+    };
+
+    let confirming_projectors: BTreeSet<&str> = surface
+        .commands
+        .iter()
+        .flat_map(|command| {
+            command
+                .confirmations
+                .iter()
+                .map(|confirmation| confirmation.projector.as_str())
+        })
+        .collect();
+    let mut projectors: Vec<ClientProjector> = surface
+        .projectors
+        .iter()
+        .map(|projector| ClientProjector {
+            version: PROJECTOR_ENTRY_VERSION,
+            name: projector.name.clone(),
+            facts: sorted_unique(projector.facts.clone()),
+            models: sorted_unique(projector.models.clone()),
+            dependencies: sorted_unique(projector.dependencies.clone()),
+            causal_confirmation: confirming_projectors.contains(projector.name.as_str()),
+        })
+        .collect();
+    projectors.sort_by(|a, b| a.name.cmp(&b.name));
+
+    let scalar_codecs = supported_scalar_codecs();
+    let record_evidence = query_footprint_has_record_evidence(surface);
+    let capabilities = ClientCapabilities {
+        live_queries: !surface.subscription_fields.is_empty(),
+        record_revisions: record_evidence,
+        tombstones: record_evidence,
+        causal_receipts: !commands.is_empty(),
+        live_resume: query_footprint_supports_live_resume(surface),
+        query_fallback: "revalidate".into(),
+        // Every generated operation consumes one authoritative scope envelope,
+        // including query-only surfaces.
+        cache_scope: true,
+        confirmed_persistence: false,
+    };
+    let protocol_fingerprint = protocol_fingerprint()?;
+
+    #[derive(Serialize)]
+    struct SchemaMaterial<'a> {
+        manifest_version: u32,
+        protocol_version: u32,
+        service_id: &'a str,
+        surface: &'a ClientSurfaceIdentity,
+        execution: &'a ClientExecutionLimits,
+        capabilities: &'a ClientCapabilities,
+        scalar_codecs: &'a [ScalarCodec],
+        models: &'a [ClientModel],
+        roots: &'a [ClientRoot],
+        commands: &'a [ClientCommand],
+        protocol_operations: &'a ClientProtocolOperations,
+        projectors: &'a [ClientProjector],
+    }
+    let schema_material = SchemaMaterial {
+        manifest_version: DISTRIBUTED_CLIENT_MANIFEST_VERSION,
+        protocol_version: DISTRIBUTED_CLIENT_PROTOCOL_VERSION,
+        service_id,
+        surface: &identity,
+        execution: &execution,
+        capabilities: &capabilities,
+        scalar_codecs: &scalar_codecs,
+        models: &models,
+        roots: &roots,
+        commands: &commands,
+        protocol_operations: &protocol_operations,
+        projectors: &projectors,
+    };
+    let schema_fingerprint = hash_json(&schema_material)?;
+
+    let manifest = DistributedClientManifest {
+        manifest_version: DISTRIBUTED_CLIENT_MANIFEST_VERSION,
+        protocol_version: DISTRIBUTED_CLIENT_PROTOCOL_VERSION,
+        service_id: service_id.into(),
+        surface: identity,
+        schema_fingerprint,
+        protocol_fingerprint,
+        execution,
+        capabilities,
+        scalar_codecs,
+        models,
+        roots,
+        commands,
+        protocol_operations,
+        projectors,
+    };
+    // Validate the one exact scope-wide descriptor union while the complete
+    // role-selected manifest is still available. The serialized manifest need
+    // not duplicate this deterministic derivation.
+    trusted_preset_descriptors(&manifest)?;
+    Ok(manifest)
+}
diff --git a/src/graphql/client_manifest/capabilities.rs b/src/graphql/client_manifest/capabilities.rs
new file mode 100644
index 00000000..3f1e591b
--- /dev/null
+++ b/src/graphql/client_manifest/capabilities.rs
@@ -0,0 +1,97 @@
+use super::*;
+
+pub(super) fn model_has_visible_causal_owner(surface: &Surface, model: &str) -> bool {
+    surface
+        .projectors
+        .iter()
+        .filter(|projector| projector.models.iter().any(|candidate| candidate == model))
+        .take(2)
+        .count()
+        == 1
+}
+
+fn selected_query_models(surface: &Surface) -> BTreeSet<String> {
+    let mut selected = surface
+        .query_fields
+        .iter()
+        .map(|root| root.model_name.clone())
+        .collect::<BTreeSet<_>>();
+    let mut pending = selected.iter().cloned().collect::<Vec<_>>();
+    while let Some(model_name) = pending.pop() {
+        let Some(model) = surface.models.get(&model_name) else {
+            continue;
+        };
+        for relationship in &model.relationships {
+            if selected.insert(relationship.target_model.clone()) {
+                pending.push(relationship.target_model.clone());
+            }
+        }
+    }
+    selected
+}
+
+fn selected_query_dependencies(surface: &Surface) -> BTreeSet<String> {
+    let mut dependencies = surface
+        .query_fields
+        .iter()
+        .flat_map(|root| root.dependencies.iter().cloned())
+        .collect::<BTreeSet<_>>();
+    for model_name in selected_query_models(surface) {
+        let Some(model) = surface.models.get(&model_name) else {
+            continue;
+        };
+        dependencies.insert(model.table_name.clone());
+        for relationship in &model.relationships {
+            dependencies.extend(relationship.dependencies.iter().cloned());
+            if let Some(aggregate) = &relationship.aggregate {
+                dependencies.extend(aggregate.dependencies.iter().cloned());
+            }
+        }
+    }
+    dependencies
+}
+
+pub(super) fn query_footprint_has_record_evidence(surface: &Surface) -> bool {
+    let models = selected_query_models(surface);
+    !models.is_empty()
+        && models
+            .iter()
+            .all(|model| model_has_visible_causal_owner(surface, model))
+}
+
+fn projector_partition_matches_authorization(
+    surface: &Surface,
+    projector: &crate::graphql::surface::SurfaceProjectionOwner,
+) -> bool {
+    projector.models.iter().all(|model| {
+        surface
+            .models
+            .get(model)
+            .is_some_and(|model| matches!(model.row_policy, SurfaceRowPolicy::Unrestricted))
+    })
+}
+
+pub(super) fn query_footprint_supports_live_resume(surface: &Surface) -> bool {
+    if surface.subscription_fields.is_empty() {
+        return false;
+    }
+    let dependencies = selected_query_dependencies(surface);
+    if dependencies.is_empty() {
+        return false;
+    }
+    dependencies.iter().all(|dependency| {
+        let mut owners = surface.projectors.iter().filter(|projector| {
+            projector
+                .dependencies
+                .iter()
+                .any(|candidate| candidate == dependency)
+        });
+        let Some(owner) = owners.next() else {
+            return false;
+        };
+        owners.next().is_none()
+            && owner.partition.preserves_source_sequence()
+            && owner.change_epoch.is_some()
+            && projector_partition_matches_authorization(surface, owner)
+    })
+}
diff --git a/src/graphql/client_manifest/codec.rs b/src/graphql/client_manifest/codec.rs
new file mode 100644
index 00000000..0becfc90
--- /dev/null
+++ b/src/graphql/client_manifest/codec.rs
@@ -0,0 +1,307 @@
+use super::*;
+
+pub(super) fn row_policy_manifest(policy: &SurfaceRowPolicy) -> ClientRowPolicy {
+    match policy {
+        SurfaceRowPolicy::Unrestricted => ClientRowPolicy::Unrestricted,
+        SurfaceRowPolicy::Predicate(predicate) => ClientRowPolicy::Predicate {
+            expression: predicate.clone(),
+        },
+        SurfaceRowPolicy::ServerOnly => ClientRowPolicy::ServerOnly,
+    }
+}
+
+pub(super) fn filter_semantics(
+    surface: &Surface,
+    model: &crate::graphql::surface::SurfaceModel,
+) -> ClientFilterSemantics {
+    ClientFilterSemantics {
+        fields: filter_fields(surface, model),
+        relationships: filter_relationship_names(model),
+        row_policy: row_policy_manifest(&model.row_policy),
+    }
+}
+
+pub(super) fn filter_input(
+    surface: &Surface,
+    model: &crate::graphql::surface::SurfaceModel,
+) -> Result<ClientFilterInput, ClientManifestError> {
+    let mut relationships = model
+        .relationships
+        .iter()
+        .map(|relationship| {
+            let target = surface
+                .models
+                .get(&relationship.target_model)
+                .ok_or_else(|| {
+                    ClientManifestError(format!(
+                        "model `{}` filter relationship `{}` targets absent model `{}`",
+                        model.model_name, relationship.name, relationship.target_model
+                    ))
+                })?;
+            Ok(ClientFilterInputRelationship {
+                field: relationship.name.clone(),
+                target_type: format!("{}_bool_exp", target.table_name),
+            })
+        })
+        .collect::<Result<Vec<_>, ClientManifestError>>()?;
+    relationships.sort_by(|left, right| left.field.cmp(&right.field));
+    Ok(ClientFilterInput {
+        type_name: format!("{}_bool_exp", model.table_name),
+        fields: filter_fields(surface, model),
+        relationships,
+    })
+}
+
+fn filter_fields(
+    surface: &Surface,
+    model: &crate::graphql::surface::SurfaceModel,
+) -> Vec<ClientFilterField> {
+    let mut fields: Vec<ClientFilterField> = model
+        .columns
+        .iter()
+        .map(|field| ClientFilterField {
+            name: field.name.clone(),
+            operators: surface
+                .comparison_ops_for_scalar(&field.scalar)
+                .into_iter()
+                .map(str::to_string)
+                .collect(),
+        })
+        .collect();
+    fields.sort_by(|a, b| a.name.cmp(&b.name));
+    fields
+}
+
+fn filter_relationship_names(model: &crate::graphql::surface::SurfaceModel) -> Vec<String> {
+    let mut relationships: Vec<String> = model
+        .relationships
+        .iter()
+        .map(|relationship| relationship.name.clone())
+        .collect();
+    relationships.sort();
+    relationships
+}
+
+pub(super) fn order_semantics(
+    model: &crate::graphql::surface::SurfaceModel,
+) -> ClientOrderSemantics {
+    let mut fields: Vec<String> = model
+        .columns
+        .iter()
+        .map(|field| field.name.clone())
+        .collect();
+    fields.sort();
+    ClientOrderSemantics {
+        fields,
+        values: [
+            "asc",
+            "asc_nulls_first",
+            "asc_nulls_last",
+            "desc",
+            "desc_nulls_first",
+            "desc_nulls_last",
+        ]
+        .into_iter()
+        .map(str::to_string)
+        .collect(),
+    }
+}
+
+pub(super) fn pagination_semantics(
+    surface: &Surface,
+    model: &crate::graphql::surface::SurfaceModel,
+) -> ClientPaginationSemantics {
+    let max_limit = model
+        .role_limit
+        .unwrap_or(surface.max_limit)
+        .min(surface.max_limit);
+    ClientPaginationSemantics {
+        kind: "offset".into(),
+        default_limit: surface.default_limit.min(max_limit),
+        max_limit,
+        coverage: "window".into(),
+    }
+}
+
+pub(super) fn aggregate_semantics(
+    model: &crate::graphql::surface::SurfaceModel,
+    wrapper_typename: String,
+    nodes_pagination: ClientPaginationSemantics,
+) -> ClientAggregateSemantics {
+    ClientAggregateSemantics {
+        wrapper_typename,
+        fields_typename: aggregate_fields_type_name(&model.schema),
+        nodes_pagination,
+        count: true,
+        nodes: true,
+        sum: Vec::new(),
+        avg: Vec::new(),
+        min: Vec::new(),
+        max: Vec::new(),
+    }
+}
+
+pub(super) fn argument_manifest(argument: &SurfaceArgument) -> ClientArgument {
+    ClientArgument {
+        name: argument.name.clone(),
+        kind: match argument.kind {
+            SurfaceArgumentKind::Filter => ClientArgumentKind::Filter,
+            SurfaceArgumentKind::Order => ClientArgumentKind::Order,
+            SurfaceArgumentKind::Limit => ClientArgumentKind::Limit,
+            SurfaceArgumentKind::Offset => ClientArgumentKind::Offset,
+            SurfaceArgumentKind::PrimaryKey => ClientArgumentKind::PrimaryKey,
+        },
+        type_name: argument.type_name.clone(),
+        nullable: argument.nullable,
+        list: argument.list,
+        codec: scalar_codec(&argument.type_name).map(str::to_string),
+    }
+}
+
+pub(super) fn command_shape(
+    shape: &SurfaceCommandShape,
+) -> Result<ClientCommandShape, ClientManifestError> {
+    match shape {
+        SurfaceCommandShape::None => Ok(ClientCommandShape::None),
+        SurfaceCommandShape::Typed(definition) => Ok(ClientCommandShape::Object {
+            definition: client_type(definition)?,
+        }),
+    }
+}
+
+fn client_type(definition: &SurfaceTypeDef) -> Result<ClientTypeDef, ClientManifestError> {
+    let mut fields = Vec::new();
+    for field in &definition.fields {
+        if !field.list && field.item_nullable {
+            return Err(ClientManifestError(format!(
+                "command type `{}` field `{}` marks non-list items nullable",
+                definition.name, field.name
+            )));
+        }
+        let nested = field
+            .nested
+            .as_deref()
+            .map(client_type)
+            .transpose()?
+            .map(Box::new);
+        let codec = scalar_codec(&field.type_name).map(str::to_string);
+        if codec.is_none() && nested.is_none() {
+            return Err(ClientManifestError(format!(
+                "command type `{}` field `{}` uses unknown scalar/object `{}`",
+                definition.name, field.name, field.type_name
+            )));
+        }
+        fields.push(ClientTypeField {
+            name: field.name.clone(),
+            type_name: field.type_name.clone(),
+            nullable: field.nullable,
+            list: field.list,
+            item_nullable: field.item_nullable,
+            codec,
+            nested,
+        });
+    }
+    fields.sort_by(|a, b| a.name.cmp(&b.name));
+    Ok(ClientTypeDef {
+        name: definition.name.clone(),
+        fields,
+    })
+}
+pub(super) fn supported_scalar_codecs() -> Vec<ScalarCodec> {
+    [
+        // SQL JSON projection currently emits integer JSON numbers. Browsers
+        // must treat values outside the JS safe-integer range as lossy.
+        ("BigInt", "json_number_precision_limited"),
+        ("Boolean", "boolean"),
+        ("Bytea", "base64"),
+        ("Float", "float64"),
+        ("ID", "string"),
+        ("Int", "int32"),
+        ("JSON", "json"),
+        ("String", "string"),
+        // Both dialects emit a string, but the framework does not normalize or
+        // validate RFC3339 at this layer yet.
+        ("Timestamptz", "string_unvalidated_timestamp"),
+    ]
+    .into_iter()
+    .map(|(scalar, codec)| ScalarCodec {
+        scalar: scalar.into(),
+        codec: codec.into(),
+    })
+    .collect()
+}
+
+pub(super) fn scalar_codec(scalar: &str) -> Option<&'static str> {
+    match scalar {
+        "BigInt" => Some("json_number_precision_limited"),
+        "Boolean" => Some("boolean"),
+        "Bytea" => Some("base64"),
+        "Float" => Some("float64"),
+        "ID" | "String" => Some("string"),
+        "Int" => Some("int32"),
+        "JSON" => Some("json"),
+        "Timestamptz" => Some("string_unvalidated_timestamp"),
+        _ => None,
+    }
+}
+
+pub(super) fn protocol_fingerprint() -> Result<String, ClientManifestError> {
+    #[derive(Serialize)]
+    struct ProtocolMaterial {
+        manifest_version: u32,
+        protocol_version: u32,
+        key_encoding: &'static str,
+        command_extension_slots_version: u32,
+        projector_entry_version: u32,
+        protocol_operations_version: u32,
+        query_capabilities_version: u32,
+        scalar_codecs: Vec<ScalarCodec>,
+    }
+    hash_json(&ProtocolMaterial {
+        manifest_version: DISTRIBUTED_CLIENT_PROTOCOL_MANIFEST_EPOCH,
+        protocol_version: DISTRIBUTED_CLIENT_PROTOCOL_VERSION,
+        key_encoding: KEY_ENCODING,
+        command_extension_slots_version: COMMAND_EXTENSION_SLOTS_VERSION,
+        projector_entry_version: PROJECTOR_ENTRY_VERSION,
+        protocol_operations_version: PROTOCOL_OPERATIONS_VERSION,
+        query_capabilities_version: QUERY_CAPABILITIES_VERSION,
+        scalar_codecs: supported_scalar_codecs(),
+    })
+}
+
+pub(super) fn hash_json(value: &impl Serialize) -> Result<String, ClientManifestError> {
+    let bytes = serde_json::to_vec(value)?;
+    Ok(hash_bytes(&bytes))
+}
+
+/// Canonicalize opaque manifest JSON before it enters a fingerprinted slot.
+///
+/// `serde_json::Value` object order otherwise depends on whether another crate
+/// enabled serde_json's `preserve_order` feature in the final Cargo graph.
+/// Client-manifest bytes must be identical in the server harness and dctl.
+pub(super) fn canonical_json_value(value: serde_json::Value) -> serde_json::Value {
+    match value {
+        serde_json::Value::Array(values) => {
+            serde_json::Value::Array(values.into_iter().map(canonical_json_value).collect())
+        }
+        serde_json::Value::Object(values) => {
+            let sorted = values
+                .into_iter()
+                .map(|(key, value)| (key, canonical_json_value(value)))
+                .collect::<BTreeMap<_, _>>();
+            serde_json::Value::Object(sorted.into_iter().collect())
+        }
+        scalar => scalar,
+    }
+}
+
+pub(super) fn hash_bytes(bytes: &[u8]) -> String {
+    let digest = Sha256::digest(bytes);
+    format!("sha256:{digest:x}")
+}
+
+pub(super) fn sorted_unique(mut values: Vec<String>) -> Vec<String> {
+    values.sort();
+    values.dedup();
+    values
+}
diff --git a/src/graphql/client_manifest/commands.rs b/src/graphql/client_manifest/commands.rs
new file mode 100644
index 00000000..b0c37a3f
--- /dev/null
+++ b/src/graphql/client_manifest/commands.rs
@@ -0,0 +1,372 @@
+use super::*;
+
+pub(super) fn command_direct_projection_extension(
+    command: &SurfaceCommand,
+    surface: &Surface,
+) -> Result<Option<CommandDirectProjectionExtension>, ClientManifestError> {
+    let projected = command.consistency == CommandConsistency::Projected;
+    let Some(target) = command.direct_projection.as_ref() else {
+        return if projected {
+            Err(ClientManifestError(format!(
+                "typed projected command `{}` is missing its bound direct projection target",
+                command.command_name
+            )))
+        } else {
+            Ok(None)
+        };
+    };
+    if !projected {
+        return Err(ClientManifestError(format!(
+            "typed non-projected command `{}` cannot export a direct projection target",
+            command.command_name
+        )));
+    }
+    let retained = command.projected_model.as_ref().ok_or_else(|| {
+        ClientManifestError(format!(
+            "typed projected command `{}` is missing its retained relational model",
+            command.command_name
+        ))
+    })?;
+    if target.model != retained.model {
+        return Err(ClientManifestError(format!(
+            "typed projected command `{}` direct target model `{}` differs from retained model `{}`",
+            command.command_name, target.model, retained.model
+        )));
+    }
+    let model = surface.models.get(&target.model).ok_or_else(|| {
+        ClientManifestError(format!(
+            "typed projected command `{}` direct target model `{}` is not authorized on this client surface",
+            command.command_name, target.model
+        ))
+    })?;
+    if !model_has_client_normalized_identity(model) {
+        return Err(ClientManifestError(format!(
+            "typed projected command `{}` direct target model `{}` has no complete authorized client identity",
+            command.command_name, target.model
+        )));
+    }
+    let SurfaceCommandShape::Typed(output) = &command.output else {
+        return Err(ClientManifestError(format!(
+            "typed projected command `{}` must return its exact relational model object",
+            command.command_name
+        )));
+    };
+    if output.name != model.object_name || output.fields.len() != model.columns.len() {
+        return Err(ClientManifestError(format!(
+            "typed projected command `{}` output does not match authorized model `{}`",
+            command.command_name, target.model
+        )));
+    }
+    for field in &output.fields {
+        let matches = model.columns.iter().any(|column| {
+            field.name == column.name
+                && field.type_name == column.scalar
+                && field.nullable == column.nullable
+                && !field.list
+                && !field.item_nullable
+                && field.nested.is_none()
+        });
+        if !matches {
+            return Err(ClientManifestError(format!(
+                "typed projected command `{}` output field `{}.{}` differs from authorized model `{}`",
+                command.command_name, output.name, field.name, target.model
+            )));
+        }
+    }
+
+    let topology = target.protocol_topology().ok_or_else(|| {
+        ClientManifestError(format!(
+            "typed projected command `{}` direct target is not bound to its compiled protocol topology",
+            command.command_name
+        ))
+    })?;
+    if topology.name() != target.projector {
+        return Err(ClientManifestError(format!(
+            "typed projected command `{}` direct target projector `{}` differs from bound topology `{}`",
+            command.command_name,
+            target.projector,
+            topology.name()
+        )));
+    }
+
+    let visible_owners = surface
+        .projectors
+        .iter()
+        .filter(|projector| projector.models.iter().any(|model| model == &target.model))
+        .collect::<Vec<_>>();
+    match visible_owners.as_slice() {
+        [] => {
+            if surface
+                .projectors
+                .iter()
+                .any(|projector| projector.name == topology.name())
+            {
+                return Err(ClientManifestError(format!(
+                    "typed projected command `{}` topology `{}` does not own model `{}` on this client surface",
+                    command.command_name,
+                    topology.name(),
+                    target.model
+                )));
+            }
+            // A role surface may omit the whole projector when the same
+            // topology also owns a denied model. The digest remains safe and
+            // exact without revealing that hidden ownership inventory.
+        }
+        [owner] if owner.name == topology.name() => {
+            if !target.topology_matches(
+                &owner.name,
+                &owner.facts,
+                &owner.models,
+                &owner.partition,
+                owner.change_epoch.as_deref(),
+            ) || !target.protocol_topology_matches(topology)
+            {
+                return Err(ClientManifestError(format!(
+                    "typed projected command `{}` direct target differs from visible owner `{}`",
+                    command.command_name, owner.name
+                )));
+            }
+        }
+        [owner] => {
+            return Err(ClientManifestError(format!(
+                "typed projected command `{}` names topology `{}` but visible owner `{}` owns model `{}`",
+                command.command_name,
+                topology.name(),
+                owner.name,
+                target.model
+            )));
+        }
+        owners => {
+            return Err(ClientManifestError(format!(
+                "typed projected command `{}` model `{}` has ambiguous visible ownership: {}",
+                command.command_name,
+                target.model,
+                owners
+                    .iter()
+                    .map(|owner| owner.name.as_str())
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            )));
+        }
+    }
+
+    let change_epoch = target.change_epoch.clone().ok_or_else(|| {
+        ClientManifestError(format!(
+            "typed projected command `{}` direct target has no registered change-log epoch",
+            command.command_name
+        ))
+    })?;
+    let partition = target
+        .partition
+        .as_ref()
+        .map(|partition| serde_json::to_value(partition).map(canonical_json_value))
+        .transpose()?;
+    let digest = topology
+        .digest()
+        .iter()
+        .map(|byte| format!("{byte:02x}"))
+        .collect::<String>();
+    Ok(Some(CommandDirectProjectionExtension {
+        topology: ClientProjectionTopologyIdentity {
+            version: topology.version(),
+            name: topology.name().to_string(),
+            digest: format!("sha256:{digest}"),
+        },
+        model: target.model.clone(),
+        partition,
+        change_epoch,
+    }))
+}
+pub(super) fn command_trusted_preset_descriptors(
+    command: &SurfaceCommand,
+    surface: &Surface,
+) -> Result<Vec<ClientTrustedPresetDescriptor>, ClientManifestError> {
+    fn register(
+        out: &mut BTreeMap<String, String>,
+        expression: &EffectExpression,
+        codec: &str,
+        command: &SurfaceCommand,
+    ) -> Result<(), ClientManifestError> {
+        let EffectExpression::TrustedPreset { name } = expression else {
+            return Ok(());
+        };
+        match out.entry(name.clone()) {
+            std::collections::btree_map::Entry::Vacant(entry) => {
+                entry.insert(codec.to_string());
+            }
+            std::collections::btree_map::Entry::Occupied(entry) if entry.get() == codec => {}
+            std::collections::btree_map::Entry::Occupied(entry) => {
+                return Err(ClientManifestError(format!(
+                    "command `{}` trusted preset `{name}` is used with incompatible codecs `{}` and `{codec}`",
+                    command.command_name,
+                    entry.get()
+                )));
+            }
+        }
+        Ok(())
+    }
+
+    fn field_codec<'a>(
+        surface: &'a Surface,
+        model: &str,
+        field: &str,
+    ) -> Result<&'static str, ClientManifestError> {
+        let column = surface
+            .models
+            .get(model)
+            .and_then(|model| model.columns.iter().find(|column| column.name == field))
+            .ok_or_else(|| {
+                ClientManifestError(format!(
+                    "trusted preset target references absent field `{model}.{field}`"
+                ))
+            })?;
+        scalar_codec(&column.scalar).ok_or_else(|| {
+            ClientManifestError(format!(
+                "trusted preset target `{model}.{field}` uses unsupported scalar `{}`",
+                column.scalar
+            ))
+        })
+    }
+
+    fn collect_key(
+        out: &mut BTreeMap<String, String>,
+        key: &EffectKey,
+        model: &str,
+        command: &SurfaceCommand,
+        surface: &Surface,
+    ) -> Result<(), ClientManifestError> {
+        for field in &key.fields {
+            register(
+                out,
+                &field.value,
+                field_codec(surface, model, &field.field)?,
+                command,
+            )?;
+        }
+        Ok(())
+    }
+
+    let mut out = BTreeMap::new();
+    if let Some(effects) = &command.effects {
+        for operation in &effects.operations {
+            match operation {
+                CommandEffect::Upsert { model, key, fields }
+                | CommandEffect::Patch { model, key, fields } => {
+                    collect_key(&mut out, key, model, command, surface)?;
+                    for field in fields {
+                        register(
+                            &mut out,
+                            &field.value,
+                            field_codec(surface, model, &field.field)?,
+                            command,
+                        )?;
+                    }
+                }
+                CommandEffect::Delete { model, key } => {
+                    collect_key(&mut out, key, model, command, surface)?;
+                }
+                CommandEffect::Link {
+                    relationship,
+                    source,
+                    target,
+                }
+                | CommandEffect::Unlink {
+                    relationship,
+                    source,
+                    target,
+                } => {
+                    collect_key(
+                        &mut out,
+                        source,
+                        &relationship.source_model,
+                        command,
+                        surface,
+                    )?;
+                    collect_key(
+                        &mut out,
+                        target,
+                        &relationship.target_model,
+                        command,
+                        surface,
+                    )?;
+                }
+                CommandEffect::InvalidateRelationship {
+                    relationship,
+                    source,
+                } => {
+                    collect_key(
+                        &mut out,
+                        source,
+                        &relationship.source_model,
+                        command,
+                        surface,
+                    )?;
+                }
+                CommandEffect::InvalidateModel { .. } => {}
+            }
+        }
+    }
+    for confirmation in &command.confirmations {
+        collect_key(
+            &mut out,
+            &confirmation.key,
+            &confirmation.model,
+            command,
+            surface,
+        )?;
+        if let Some(partition) = &confirmation.partition {
+            register(&mut out, partition, "string", command)?;
+        }
+    }
+    if let Some(direct) = &command.direct_projection {
+        if let Some(partition) = &direct.partition {
+            register(&mut out, partition, "string", command)?;
+        }
+    }
+
+    Ok(out
+        .into_iter()
+        .map(|(name, codec)| ClientTrustedPresetDescriptor { name, codec })
+        .collect())
+}
+pub(super) fn command_operation(
+    mutation_field: &str,
+    input: &ClientCommandShape,
+    output: &ClientCommandShape,
+) -> String {
+    let operation_name = format!("Client_{mutation_field}");
+    let (variables, arguments) = match input {
+        ClientCommandShape::None => (
+            "($commandId: ID!)".to_string(),
+            "(commandId: $commandId)".to_string(),
+        ),
+        ClientCommandShape::Object { definition } => (
+            format!("($commandId: ID!, $input: {}!)", definition.name),
+            "(commandId: $commandId, input: $input)".to_string(),
+        ),
+    };
+    let selection = match output {
+        ClientCommandShape::Object { definition } => {
+            format!(" {{ {} }}", command_selection(definition))
+        }
+        ClientCommandShape::None => String::new(),
+    };
+    format!("mutation {operation_name}{variables} {{ {mutation_field}{arguments}{selection} }}")
+}
+
+pub(super) fn command_status_operation() -> String {
+    "query Distributed_CommandStatus($commandId: ID!) { commandStatus(commandId: $commandId) { state } }"
+        .into()
+}
+
+fn command_selection(definition: &ClientTypeDef) -> String {
+    definition
+        .fields
+        .iter()
+        .map(|field| match &field.nested {
+            Some(nested) => format!("{} {{ {} }}", field.name, command_selection(nested)),
+            None => field.name.clone(),
+        })
+        .collect::<Vec<_>>()
+        .join(" ")
+}
diff --git a/src/graphql/client_manifest/error.rs b/src/graphql/client_manifest/error.rs
new file mode 100644
index 00000000..7b93db4d
--- /dev/null
+++ b/src/graphql/client_manifest/error.rs
@@ -0,0 +1,16 @@
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ClientManifestError(pub String);
+
+impl std::fmt::Display for ClientManifestError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl std::error::Error for ClientManifestError {}
+
+impl From<serde_json::Error> for ClientManifestError {
+    fn from(error: serde_json::Error) -> Self {
+        Self(format!("client manifest serialization failed: {error}"))
+    }
+}
diff --git a/src/graphql/client_manifest/export.rs b/src/graphql/client_manifest/export.rs
new file mode 100644
index 00000000..93638982
--- /dev/null
+++ b/src/graphql/client_manifest/export.rs
@@ -0,0 +1,151 @@
+use super::*;
+
+#[derive(Clone)]
+pub struct DistributedClientSurfaceExport {
+    service_id: String,
+    identity: ClientSurfaceIdentity,
+    surface: Arc<Surface>,
+    execution: ClientExecutionLimits,
+}
+
+/// Do not transitively format the selected Surface: it retains a private full
+/// catalog solely for server-side policy validation.
+impl std::fmt::Debug for DistributedClientSurfaceExport {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("DistributedClientSurfaceExport")
+            .field("service_id", &self.service_id)
+            .field("identity", &self.identity)
+            .finish_non_exhaustive()
+    }
+}
+
+impl DistributedClientSurfaceExport {
+    fn new(
+        service_id: impl Into<String>,
+        identity: ClientSurfaceIdentity,
+        surface: impl Into<Arc<Surface>>,
+        execution: ClientExecutionLimits,
+    ) -> Self {
+        Self {
+            service_id: service_id.into(),
+            identity,
+            surface: surface.into(),
+            execution,
+        }
+    }
+
+    /// Safe, low-boilerplate export path: authorization identity is derived
+    /// from the selected Surface and cannot be caller-asserted.
+    pub(crate) fn from_selected(
+        service_id: impl Into<String>,
+        surface: impl Into<Arc<Surface>>,
+    ) -> Result<Self, ClientManifestError> {
+        Self::from_selected_with_execution(service_id, surface, ClientExecutionLimits::default())
+    }
+
+    pub(crate) fn from_selected_with_execution(
+        service_id: impl Into<String>,
+        surface: impl Into<Arc<Surface>>,
+        execution: ClientExecutionLimits,
+    ) -> Result<Self, ClientManifestError> {
+        let surface = surface.into();
+        let service_id = service_id.into();
+        let identity = match &surface.selection {
+            SurfaceSelection::Catalog => {
+                return Err(ClientManifestError(
+                    "client exports require an explicitly role- or application-selected Surface"
+                        .into(),
+                ));
+            }
+            SurfaceSelection::Role { name } => ClientSurfaceIdentity::role(name),
+            SurfaceSelection::Application { name, roles } => {
+                ClientSurfaceIdentity::application(name, roles.clone())
+            }
+        };
+        validate_service_provenance(&service_id, &surface)?;
+        Ok(Self::new(service_id, identity, surface, execution))
+    }
+
+    /// Build a portable export whose service identity comes from the same
+    /// project manifest that supplied its table inventory.
+    pub fn from_project(
+        project: &DistributedProjectManifest,
+        surface: impl Into<Arc<Surface>>,
+    ) -> Result<Self, ClientManifestError> {
+        let surface = surface.into();
+        for model in surface.models.values() {
+            let Some(original) = project.tables.iter().find(|schema| {
+                schema.model_name == model.model_name && schema.table_name == model.table_name
+            }) else {
+                return Err(ClientManifestError(format!(
+                    "selected Surface model `{}` does not match the supplied project manifest inventory",
+                    model.model_name
+                )));
+            };
+            let mut selected_schema = model.schema.clone();
+            for column in &mut selected_schema.columns {
+                if let Some(original_column) = original
+                    .columns
+                    .iter()
+                    .find(|candidate| candidate.column_name == column.column_name)
+                {
+                    column.skipped = original_column.skipped;
+                }
+            }
+            selected_schema.relationships = original.relationships.clone();
+            if &selected_schema != original {
+                return Err(ClientManifestError(format!(
+                    "selected Surface model `{}` does not match the supplied project manifest inventory",
+                    model.model_name
+                )));
+            }
+        }
+        Self::from_selected(project.name.clone(), surface)
+    }
+
+    pub fn manifest(&self) -> Result<DistributedClientManifest, ClientManifestError> {
+        client_manifest_from_surface_with_execution(
+            &self.service_id,
+            self.identity.clone(),
+            &self.surface,
+            self.execution.clone(),
+        )
+    }
+
+    pub fn service_id(&self) -> &str {
+        &self.service_id
+    }
+
+    pub fn identity(&self) -> &ClientSurfaceIdentity {
+        &self.identity
+    }
+
+    pub fn surface(&self) -> &Arc<Surface> {
+        &self.surface
+    }
+
+    pub fn manifest_json_pretty(&self) -> Result<String, ClientManifestError> {
+        Ok(serde_json::to_string_pretty(&self.manifest()?)?)
+    }
+}
+
+fn validate_service_provenance(
+    service_id: &str,
+    surface: &Surface,
+) -> Result<(), ClientManifestError> {
+    let has_typed_commands = !surface.commands.is_empty();
+    match (&surface.service_binding, has_typed_commands) {
+        (Some(binding), _) if binding.service_id != service_id => Err(ClientManifestError(
+            format!(
+                "client export service ID `{service_id}` does not match typed Surface provenance `{}`",
+                binding.service_id
+            ),
+        )),
+        (None, true) => Err(ClientManifestError(
+            "typed client export requires Surface provenance from Surface::with_service"
+                .into(),
+        )),
+        _ => Ok(()),
+    }
+}
diff --git a/src/graphql/client_manifest/identity.rs b/src/graphql/client_manifest/identity.rs
new file mode 100644
index 00000000..59b899c4
--- /dev/null
+++ b/src/graphql/client_manifest/identity.rs
@@ -0,0 +1,54 @@
+use super::*;
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum ClientSurfaceIdentity {
+    Role { name: String },
+    Application { name: String, roles: Vec<String> },
+}
+
+impl ClientSurfaceIdentity {
+    pub fn role(name: impl Into<String>) -> Self {
+        Self::Role { name: name.into() }
+    }
+
+    pub fn application(
+        name: impl Into<String>,
+        roles: impl IntoIterator<Item = impl Into<String>>,
+    ) -> Self {
+        let mut roles: Vec<String> = roles.into_iter().map(Into::into).collect();
+        roles.sort();
+        roles.dedup();
+        Self::Application {
+            name: name.into(),
+            roles,
+        }
+    }
+
+    pub(super) fn canonicalized(self) -> Result<Self, ClientManifestError> {
+        match self {
+            Self::Role { name } if name.trim().is_empty() => Err(ClientManifestError(
+                "role surface name must not be empty".into(),
+            )),
+            Self::Role { name } => Ok(Self::Role { name }),
+            Self::Application { name, .. } if name.trim().is_empty() => Err(ClientManifestError(
+                "application surface name must not be empty".into(),
+            )),
+            Self::Application { name, mut roles } => {
+                if roles.iter().any(|role| role.trim().is_empty()) {
+                    return Err(ClientManifestError(format!(
+                        "application surface `{name}` contains an empty role id"
+                    )));
+                }
+                roles.sort();
+                roles.dedup();
+                if roles.is_empty() {
+                    return Err(ClientManifestError(format!(
+                        "application surface `{name}` must declare at least one role"
+                    )));
+                }
+                Ok(Self::Application { name, roles })
+            }
+        }
+    }
+}
diff --git a/src/graphql/client_manifest/limits.rs b/src/graphql/client_manifest/limits.rs
new file mode 100644
index 00000000..95cbb264
--- /dev/null
+++ b/src/graphql/client_manifest/limits.rs
@@ -0,0 +1,81 @@
+use super::*;
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientExecutionLimits {
+    pub max_depth: u64,
+    pub max_complexity: u64,
+    pub max_bool_width: u64,
+    pub max_in_list: u64,
+    pub complexity: ClientComplexityWeights,
+}
+
+impl Default for ClientExecutionLimits {
+    fn default() -> Self {
+        Self {
+            max_depth: DEFAULT_MAX_DEPTH as u64,
+            max_complexity: DEFAULT_MAX_COMPLEXITY as u64,
+            max_bool_width: DEFAULT_MAX_BOOL_WIDTH,
+            max_in_list: DEFAULT_MAX_IN_LIST,
+            complexity: ClientComplexityWeights::current(),
+        }
+    }
+}
+
+impl ClientExecutionLimits {
+    pub(crate) fn from_runtime(
+        max_depth: usize,
+        max_complexity: usize,
+        max_bool_width: usize,
+        max_in_list: usize,
+    ) -> Result<Self, ClientManifestError> {
+        Ok(Self {
+            max_depth: u64::try_from(max_depth).map_err(|_| {
+                ClientManifestError("GraphQL max_depth exceeds the client manifest range".into())
+            })?,
+            max_complexity: u64::try_from(max_complexity).map_err(|_| {
+                ClientManifestError(
+                    "GraphQL max_complexity exceeds the client manifest range".into(),
+                )
+            })?,
+            max_bool_width: u64::try_from(max_bool_width).map_err(|_| {
+                ClientManifestError(
+                    "GraphQL max_bool_width exceeds the client manifest range".into(),
+                )
+            })?,
+            max_in_list: u64::try_from(max_in_list).map_err(|_| {
+                ClientManifestError("GraphQL max_in_list exceeds the client manifest range".into())
+            })?,
+            complexity: ClientComplexityWeights::current(),
+        })
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientComplexityWeights {
+    pub version: u32,
+    pub scalar: u64,
+    pub belongs_to: u64,
+    pub has_many: u64,
+    pub m2m: u64,
+    pub aggregate: u64,
+    pub list_root: u64,
+    pub by_pk: u64,
+    pub list_fanout: u64,
+}
+
+impl ClientComplexityWeights {
+    pub(super) fn current() -> Self {
+        let weights = default_weights();
+        Self {
+            version: QUERY_COMPLEXITY_VERSION,
+            scalar: weights.scalar as u64,
+            belongs_to: weights.belongs_to as u64,
+            has_many: weights.has_many as u64,
+            m2m: weights.m2m as u64,
+            aggregate: weights.aggregate as u64,
+            list_root: weights.list_root as u64,
+            by_pk: weights.by_pk as u64,
+            list_fanout: weights.list_fanout as u64,
+        }
+    }
+}
diff --git a/src/graphql/client_manifest/mod.rs b/src/graphql/client_manifest/mod.rs
new file mode 100644
index 00000000..62ed2ac5
--- /dev/null
+++ b/src/graphql/client_manifest/mod.rs
@@ -0,0 +1,86 @@
+//! Versioned client contract derived from the shared, role-filtered GraphQL
+//! [`Surface`](super::surface::Surface).
+//!
+//! This module is intentionally pool-free. Runtime schema construction, engine
+//! export, and `dctl` all hand the same Surface to
+//! [`DistributedClientSurfaceExport::manifest`]; no consumer re-walks a table,
+//! command, permission, relationship, or projector registry.
+
+mod build;
+mod capabilities;
+mod codec;
+mod commands;
+mod error;
+mod export;
+mod identity;
+mod limits;
+mod types;
+mod validation;
+
+#[cfg(test)]
+mod tests;
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::sync::Arc;
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+use super::command_contract::{
+    CommandConsistency, CommandEffect, CommandEffectFallback, EffectExpression, EffectKey,
+};
+use super::complexity_contract::{default_weights, DEFAULT_MAX_COMPLEXITY, DEFAULT_MAX_DEPTH};
+use super::filter::{FilterExpr, Operand};
+use super::naming::{aggregate_fields_type_name, aggregate_type_name};
+use super::surface::{
+    model_has_client_normalized_identity, RootKind, Surface, SurfaceArgument, SurfaceArgumentKind,
+    SurfaceCommand, SurfaceCommandShape, SurfaceRelationshipKeys, SurfaceRowPolicy,
+    SurfaceSelection, SurfaceTypeDef,
+};
+use crate::manifest::DistributedProjectManifest;
+use crate::table::RelationshipKind;
+
+use build::client_manifest_from_surface_with_execution;
+use capabilities::{
+    model_has_visible_causal_owner, query_footprint_has_record_evidence,
+    query_footprint_supports_live_resume,
+};
+use codec::*;
+use commands::*;
+use validation::validate_surface_structure;
+
+// Used by unit tests (and still a thin production-friendly wrapper).
+#[cfg_attr(not(test), allow(unused_imports))]
+pub(crate) use build::client_manifest_from_surface;
+pub use error::ClientManifestError;
+pub use export::DistributedClientSurfaceExport;
+pub use identity::ClientSurfaceIdentity;
+pub use limits::{ClientComplexityWeights, ClientExecutionLimits};
+pub use types::{
+    ClientAggregateSemantics, ClientArgument, ClientArgumentKind, ClientCapabilities,
+    ClientCommand, ClientCommandExtensionSlots, ClientCommandShape, ClientField, ClientFilterField,
+    ClientFilterInput, ClientFilterInputRelationship, ClientFilterSemantics, ClientKeyField,
+    ClientModel, ClientOrderSemantics, ClientPaginationSemantics, ClientProjectionTopologyIdentity,
+    ClientProjector, ClientProtocolOperation, ClientProtocolOperations, ClientRelationship,
+    ClientRelationshipAggregate, ClientRelationshipKind, ClientRelationshipMaintenance, ClientRoot,
+    ClientRootKind, ClientRootOperation, ClientRowPolicy, ClientTrustedPresetDescriptor,
+    ClientTypeDef, ClientTypeField, CommandConfirmationsExtension, CommandConsistencyExtension,
+    CommandDirectProjectionExtension, CommandEffectsExtension, CommandInputDefaultsExtension,
+    DistributedClientManifest, ModelNormalization, RelationshipKeyMapping, ScalarCodec,
+};
+pub(crate) use validation::trusted_preset_descriptors;
+
+pub const DISTRIBUTED_CLIENT_MANIFEST_VERSION: u32 = 1;
+pub const DISTRIBUTED_CLIENT_PROTOCOL_VERSION: u32 = 1;
+// Protocol v1 is the first public wire family. The independent fingerprint below
+// changes when its generated command/scope contract changes, including trusted-preset descriptor slots.
+const DISTRIBUTED_CLIENT_PROTOCOL_MANIFEST_EPOCH: u32 = 1;
+const COMMAND_EXTENSION_SLOTS_VERSION: u32 = 1;
+const COMMAND_CONFIRMATIONS_VERSION: u32 = 1;
+const PROJECTOR_ENTRY_VERSION: u32 = 1;
+const PROTOCOL_OPERATIONS_VERSION: u32 = 1;
+const QUERY_CAPABILITIES_VERSION: u32 = 1;
+const QUERY_COMPLEXITY_VERSION: u32 = 1;
+const KEY_ENCODING: &str = "canonical_json_tuple_v1";
+const DEFAULT_MAX_BOOL_WIDTH: u64 = 256;
+const DEFAULT_MAX_IN_LIST: u64 = 1_000;
diff --git a/src/graphql/client_manifest/tests.rs b/src/graphql/client_manifest/tests.rs
new file mode 100644
index 00000000..d2538cc6
--- /dev/null
+++ b/src/graphql/client_manifest/tests.rs
@@ -0,0 +1,1610 @@
+use super::*;
+use crate::graphql::{
+    build_surface, claim, col, rel, surface_for_application, surface_for_role, typed_command,
+    Accepted, GraphqlInputType, GraphqlOutputType, GraphqlTypeDef, GraphqlTypeField,
+    PreparedCommand, RoleGrant, SurfaceCommand, SurfaceOptions, SurfaceProjector, SurfaceTypeField,
+};
+use crate::microsvc::{CausalCommandContext, HandlerError, Routes, Service};
+use crate::table::{
+    ColumnType, PrimaryKey, RelationshipDef, RelationshipKind, TableColumn, TableKind, TableSchema,
+};
+use std::any::TypeId;
+
+#[test]
+fn generated_causal_command_operation_requires_framework_command_id() {
+    let operation = command_operation(
+        "todo_create",
+        &ClientCommandShape::Object {
+            definition: ClientTypeDef {
+                name: "CreateTodoInput".into(),
+                fields: Vec::new(),
+            },
+        },
+        &ClientCommandShape::Object {
+            definition: ClientTypeDef {
+                name: "CreateTodoOutput".into(),
+                fields: vec![ClientTypeField {
+                    name: "id".into(),
+                    type_name: "String".into(),
+                    nullable: false,
+                    list: false,
+                    item_nullable: false,
+                    codec: Some("string".into()),
+                    nested: None,
+                }],
+            },
+        },
+    );
+    assert_eq!(
+            operation,
+            "mutation Client_todo_create($commandId: ID!, $input: CreateTodoInput!) { todo_create(commandId: $commandId, input: $input) { id } }"
+        );
+}
+
+fn column(name: &str, ty: ColumnType) -> TableColumn {
+    TableColumn::new(name, name, ty)
+}
+
+fn users() -> TableSchema {
+    TableSchema {
+        model_name: "UserView".into(),
+        table_name: "users".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..column("user_id", ColumnType::Text)
+            },
+            column("display_name", ColumnType::Text),
+            column("secret", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["user_id"]),
+        version_column: Some("_sourced_version".into()),
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    }
+}
+
+fn todos() -> TableSchema {
+    TableSchema {
+        model_name: "TodoView".into(),
+        table_name: "todos".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..column("todo_id", ColumnType::Text)
+            },
+            column("owner_id", ColumnType::Text),
+            column("title", ColumnType::Text),
+            column("completed", ColumnType::Boolean),
+        ],
+        primary_key: PrimaryKey::new(["todo_id"]),
+        version_column: Some("_sourced_version".into()),
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "owner".into(),
+            kind: RelationshipKind::BelongsTo,
+            target_model: "UserView".into(),
+            foreign_key: Some("owner_id".into()),
+            through: None,
+            target_foreign_key: None,
+        }],
+        kind: TableKind::ReadModel,
+    }
+}
+
+fn memberships() -> TableSchema {
+    TableSchema {
+        model_name: "MembershipView".into(),
+        table_name: "memberships".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..column("tenant_id", ColumnType::Text)
+            },
+            TableColumn {
+                primary_key: true,
+                ..column("user_id", ColumnType::Text)
+            },
+            column("role", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["tenant_id", "user_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    }
+}
+
+fn teams() -> TableSchema {
+    TableSchema {
+        model_name: "TeamView".into(),
+        table_name: "teams".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..column("team_id", ColumnType::Text)
+            },
+            column("name", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["team_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "members".into(),
+            kind: RelationshipKind::ManyToMany,
+            target_model: "UserView".into(),
+            foreign_key: Some("team_id".into()),
+            through: Some("private_team_members".into()),
+            target_foreign_key: Some("user_id".into()),
+        }],
+        kind: TableKind::ReadModel,
+    }
+}
+
+fn team_members() -> TableSchema {
+    TableSchema {
+        model_name: "PrivateTeamMember".into(),
+        table_name: "private_team_members".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..column("team_id", ColumnType::Text)
+            },
+            TableColumn {
+                primary_key: true,
+                ..column("user_id", ColumnType::Text)
+            },
+        ],
+        primary_key: PrimaryKey::new(["team_id", "user_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::Operational,
+    }
+}
+
+#[derive(Deserialize)]
+struct CompleteInput;
+impl GraphqlInputType for CompleteInput {
+    fn graphql_type() -> GraphqlTypeDef {
+        GraphqlTypeDef::new(
+            "CompleteTodoInput",
+            vec![GraphqlTypeField {
+                name: "todo_id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            }],
+        )
+        .with_type_id(TypeId::of::<Self>())
+    }
+}
+
+#[derive(Serialize)]
+struct CompletePayload;
+impl GraphqlOutputType for CompletePayload {
+    fn graphql_type() -> GraphqlTypeDef {
+        GraphqlTypeDef::new(
+            "CompleteTodoPayload",
+            vec![GraphqlTypeField {
+                name: "todo_id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            }],
+        )
+        .with_type_id(TypeId::of::<Self>())
+    }
+}
+
+#[derive(Default)]
+struct ManifestAggregate {
+    entity: crate::Entity,
+}
+
+impl crate::Aggregate for ManifestAggregate {
+    type ReplayError = std::convert::Infallible;
+
+    fn entity(&self) -> &crate::Entity {
+        &self.entity
+    }
+
+    fn entity_mut(&mut self) -> &mut crate::Entity {
+        &mut self.entity
+    }
+
+    fn replay_event(&mut self, _event: &crate::EventRecord) -> Result<(), Self::ReplayError> {
+        Ok(())
+    }
+}
+
+async fn complete_handler(
+    _context: &CausalCommandContext<'_, ManifestAggregate>,
+    _input: CompleteInput,
+) -> Result<PreparedCommand<Accepted<CompletePayload>>, HandlerError> {
+    Ok(
+        PreparedCommand::<Accepted<CompletePayload>>::prepare(CompletePayload)
+            .expect("serializable command payload"),
+    )
+}
+
+fn full_surface() -> Surface {
+    let service = Service::new().named("todos-service").routes(
+        Routes::new()
+            .with_repo(crate::AggregateRepository::<_, ManifestAggregate>::new(
+                crate::InMemoryRepository::new(),
+            ))
+            .typed_command(
+                typed_command::<CompleteInput, Accepted<CompletePayload>>("todo.complete")
+                    .field_name("todos_complete")
+                    .roles(["admin", "user"]),
+            )
+            .handle(complete_handler)
+            .typed_command(
+                typed_command::<CompleteInput, Accepted<CompletePayload>>("todo.force_archive")
+                    .field_name("todos_force_archive")
+                    .roles(["admin"]),
+            )
+            .handle(complete_handler),
+    );
+    build_surface(
+        &[todos(), users(), memberships()],
+        &SurfaceOptions::sqlite(),
+    )
+    .expect("surface")
+    .with_service(&service)
+    .expect("typed service")
+    .with_projectors([
+        SurfaceProjector::new("project_todos")
+            .facts(["todo.completed"])
+            .models(["TodoView"]),
+        SurfaceProjector::new("project_users")
+            .facts(["user.changed"])
+            .models(["UserView"]),
+    ])
+    .expect("projectors")
+}
+
+fn projected_surface() -> Surface {
+    use super::super::command_contract::{CommandEffects, CommandProjectedModel, EffectExpression};
+
+    let todo_schema: &'static TableSchema = Box::leak(Box::new(todos()));
+    let mut surface = build_surface(&[todo_schema.clone(), users()], &SurfaceOptions::sqlite())
+        .expect("projected surface");
+    let todo_model = surface.models["TodoView"].clone();
+    let mut output_fields = todo_model
+        .columns
+        .iter()
+        .map(|column| SurfaceTypeField {
+            name: column.name.clone(),
+            type_name: column.scalar.clone(),
+            nullable: column.nullable,
+            list: false,
+            item_nullable: false,
+            nested: None,
+        })
+        .collect::<Vec<_>>();
+    output_fields.sort_by(|left, right| left.name.cmp(&right.name));
+    surface.commands = vec![SurfaceCommand {
+        command_name: "todo.project".into(),
+        field_name: "todo_project".into(),
+        roles: vec!["user".into()],
+        input: SurfaceCommandShape::Typed(SurfaceTypeDef {
+            name: "ProjectTodoInput".into(),
+            fields: vec![SurfaceTypeField {
+                name: "todo_id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            }],
+        }),
+        output: SurfaceCommandShape::Typed(SurfaceTypeDef {
+            name: todo_model.object_name,
+            fields: output_fields,
+        }),
+        consistency: CommandConsistency::Projected,
+        input_defaults: Vec::new(),
+        effects: Some(CommandEffects::revalidate()),
+        confirmations: Vec::new(),
+        projected_model: Some(CommandProjectedModel {
+            output_type_id: TypeId::of::<()>(),
+            model: "TodoView".into(),
+            table: "todos".into(),
+            schema: todo_schema,
+            partition: Some(EffectExpression::Input {
+                path: vec!["todo_id".into()],
+            }),
+        }),
+        direct_projection: None,
+        confirmation_unavailable: false,
+    }];
+    surface.commands_attached = true;
+    surface
+        .with_projectors([SurfaceProjector::new("project_todo_domain")
+            .facts(["todo.changed", "user.changed"])
+            .models(["TodoView", "UserView"])
+            .partition_by(["todo_id"])
+            .change_epoch("todo-domain-v1")])
+        .expect("projected topology")
+}
+
+#[test]
+fn projected_command_exports_opaque_role_safe_direct_target() {
+    let full = projected_surface();
+    let selected = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([("TodoView".into(), RoleGrant::all_columns())]),
+    )
+    .expect("role selection");
+    assert!(
+        selected.projectors.is_empty(),
+        "the multi-model owner must be omitted when one owned model is denied"
+    );
+
+    let manifest = client_manifest_from_surface(
+        "todos-service",
+        ClientSurfaceIdentity::role("user"),
+        &selected,
+    )
+    .expect("projected client manifest");
+    let direct = manifest.commands[0]
+        .extensions
+        .direct_projection
+        .as_ref()
+        .expect("projected direct target");
+    assert_eq!(direct.topology.version, 1);
+    assert_eq!(direct.topology.name, "project_todo_domain");
+    assert_eq!(direct.topology.digest.len(), 71);
+    assert!(direct.topology.digest.starts_with("sha256:"));
+    assert!(direct.topology.digest[7..]
+        .bytes()
+        .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte)));
+    assert_eq!(direct.model, "TodoView");
+    assert_eq!(
+        direct.partition,
+        Some(serde_json::json!({"kind": "input", "path": ["todo_id"]}))
+    );
+    assert_eq!(direct.change_epoch, "todo-domain-v1");
+
+    let direct_wire = serde_json::to_value(direct).expect("direct target wire");
+    assert_eq!(
+        direct_wire
+            .as_object()
+            .expect("direct target object")
+            .keys()
+            .map(String::as_str)
+            .collect::<BTreeSet<_>>(),
+        BTreeSet::from(["change_epoch", "model", "partition", "topology"])
+    );
+    let wire = serde_json::to_string(&manifest).expect("client manifest wire");
+    assert!(!wire.contains("UserView"));
+    assert!(!wire.contains("users"));
+    assert!(!wire.contains("user.changed"));
+}
+
+#[test]
+fn trusted_preset_artifacts_expose_typed_descriptors_without_values() {
+    use super::super::command_contract::{
+        CommandEffect, CommandEffects, EffectExpression, EffectFieldValue, EffectKey,
+    };
+
+    let mut full = projected_surface();
+    full.commands[0].effects = Some(CommandEffects::new([CommandEffect::Patch {
+        model: "TodoView".into(),
+        key: EffectKey {
+            fields: vec![EffectFieldValue {
+                field: "todo_id".into(),
+                value: EffectExpression::Input {
+                    path: vec!["todo_id".into()],
+                },
+            }],
+        },
+        fields: vec![EffectFieldValue {
+            field: "owner_id".into(),
+            value: EffectExpression::TrustedPreset {
+                name: "x-user-id".into(),
+            },
+        }],
+    }]));
+    let selected = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([
+            ("TodoView".into(), RoleGrant::all_columns()),
+            ("UserView".into(), RoleGrant::all_columns()),
+        ]),
+    )
+    .expect("role selection");
+    let manifest = client_manifest_from_surface(
+        "todos-service",
+        ClientSurfaceIdentity::role("user"),
+        &selected,
+    )
+    .expect("trusted preset descriptor manifest");
+
+    assert_eq!(
+        manifest.commands[0].extensions.trusted_presets,
+        vec![ClientTrustedPresetDescriptor {
+            name: "x-user-id".into(),
+            codec: "string".into(),
+        }]
+    );
+    let wire = serde_json::to_value(manifest).expect("manifest JSON");
+    assert_eq!(
+        wire["commands"][0]["extensions"]["trusted_presets"],
+        serde_json::json!([{"name": "x-user-id", "codec": "string"}])
+    );
+    assert!(
+        !wire.to_string().contains("preset-value"),
+        "static artifacts must never freeze a runtime preset value"
+    );
+}
+
+#[test]
+fn projected_command_export_rejects_absent_or_wrong_direct_target() {
+    let full = projected_surface();
+    let mut selected = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([
+            ("TodoView".into(), RoleGrant::all_columns()),
+            ("UserView".into(), RoleGrant::all_columns()),
+        ]),
+    )
+    .expect("role selection");
+
+    selected.commands[0].direct_projection = None;
+    let error = client_manifest_from_surface(
+        "todos-service",
+        ClientSurfaceIdentity::role("user"),
+        &selected,
+    )
+    .expect_err("projected command cannot omit direct target");
+    assert!(error
+        .0
+        .contains("missing its bound direct projection target"));
+
+    let mut selected = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([
+            ("TodoView".into(), RoleGrant::all_columns()),
+            ("UserView".into(), RoleGrant::all_columns()),
+        ]),
+    )
+    .expect("role selection");
+    selected.commands[0]
+        .direct_projection
+        .as_mut()
+        .expect("bound target")
+        .model = "UserView".into();
+    let error = client_manifest_from_surface(
+        "todos-service",
+        ClientSurfaceIdentity::role("user"),
+        &selected,
+    )
+    .expect_err("direct target cannot name a different retained model");
+    assert!(error.0.contains("differs from retained model"));
+}
+
+fn grants() -> BTreeMap<String, BTreeMap<String, RoleGrant>> {
+    BTreeMap::from([
+        (
+            "admin".into(),
+            BTreeMap::from([
+                (
+                    "TodoView".into(),
+                    RoleGrant::all_columns().with_aggregations(),
+                ),
+                (
+                    "UserView".into(),
+                    RoleGrant::all_columns().with_aggregations(),
+                ),
+                ("MembershipView".into(), RoleGrant::all_columns()),
+            ]),
+        ),
+        (
+            "user".into(),
+            BTreeMap::from([
+                (
+                    "TodoView".into(),
+                    RoleGrant::all_columns()
+                        .rows(col("owner_id").eq(claim("x-user-id")))
+                        .limit(25),
+                ),
+                ("UserView".into(), RoleGrant::columns(["display_name"])),
+                (
+                    "MembershipView".into(),
+                    RoleGrant::columns(["tenant_id", "role"]),
+                ),
+            ]),
+        ),
+    ])
+}
+
+fn manifest_for_all_models(
+    service_id: &str,
+    role: &str,
+    full: &Surface,
+) -> DistributedClientManifest {
+    let grants = full
+        .models
+        .keys()
+        .map(|model| (model.clone(), RoleGrant::all_columns().with_aggregations()))
+        .collect();
+    let selected = surface_for_role(full, role, &grants).expect("role surface");
+    client_manifest_from_surface(service_id, ClientSurfaceIdentity::role(role), &selected)
+        .expect("client manifest")
+}
+
+#[test]
+fn role_manifest_is_deterministic_and_hides_denied_identity_and_commands() {
+    let full = full_surface();
+    let selected = surface_for_role(&full, "user", &grants()["user"]).unwrap();
+    let export = DistributedClientSurfaceExport::from_selected("todos-service", selected)
+        .expect("role-selected Surface");
+    let first = export.manifest().unwrap();
+    let second = export.manifest().unwrap();
+    assert_eq!(first, second);
+    assert_eq!(first.manifest_version, 1);
+    assert_eq!(first.schema_fingerprint, second.schema_fingerprint);
+    assert_eq!(
+        first.schema_fingerprint,
+        "sha256:62d5744879f473776824e00c101e5d323c27e37bd7a3ba610847cf0130861f93"
+    );
+    assert_eq!(
+        first.protocol_fingerprint,
+        "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273"
+    );
+
+    let user = first
+        .models
+        .iter()
+        .find(|model| model.id == "UserView")
+        .unwrap();
+    assert_eq!(user.normalization, ModelNormalization::Embedded);
+    assert!(user.record_revisions && user.tombstones);
+    assert_eq!(
+        user.fields
+            .iter()
+            .map(|field| field.name.as_str())
+            .collect::<Vec<_>>(),
+        vec!["display_name"]
+    );
+    let todo = first
+        .models
+        .iter()
+        .find(|model| model.id == "TodoView")
+        .unwrap();
+    assert!(todo.record_revisions && todo.tombstones);
+    assert_eq!(
+        todo.row_policy,
+        ClientRowPolicy::Predicate {
+            expression: col("owner_id").eq(claim("x-user-id")),
+        }
+    );
+    assert_eq!(
+        trusted_preset_descriptors(&first).unwrap(),
+        vec![ClientTrustedPresetDescriptor {
+            name: "x-user-id".into(),
+            codec: "string".into(),
+        }]
+    );
+    let owner = todo
+        .relationships
+        .iter()
+        .find(|rel| rel.name == "owner")
+        .unwrap();
+    assert!(!owner.nullable);
+    assert_eq!(owner.key_mapping, RelationshipKeyMapping::Embedded);
+    assert_eq!(owner.maintenance, ClientRelationshipMaintenance::Revalidate);
+    assert_eq!(owner.dependencies, vec!["todos", "users"]);
+    assert!(
+        !owner.live,
+        "singular relationships are not live list plans"
+    );
+    assert!(owner.arguments.is_empty());
+    assert!(owner.filter.is_none());
+    assert_eq!(todo.filter_input.type_name, "todos_bool_exp");
+    assert_eq!(
+        todo.filter_input
+            .relationships
+            .iter()
+            .find(|relationship| relationship.field == "owner")
+            .expect("singular relationship predicate")
+            .target_type,
+        user.filter_input.type_name
+    );
+    assert_eq!(user.filter_input.type_name, "users_bool_exp");
+    assert!(first.capabilities.live_queries);
+    assert!(!first.capabilities.record_revisions);
+    assert!(!first.capabilities.tombstones);
+    assert!(!first.capabilities.live_resume);
+    assert_eq!(first.capabilities.query_fallback, "revalidate");
+    assert!(first.capabilities.causal_receipts);
+    assert!(first.capabilities.cache_scope);
+    let membership = first
+        .models
+        .iter()
+        .find(|model| model.id == "MembershipView")
+        .unwrap();
+    assert!(!membership.record_revisions && !membership.tombstones);
+    let status = first
+        .protocol_operations
+        .command_status
+        .as_ref()
+        .expect("causal surfaces generate the framework status operation");
+    assert_eq!(status.name, "Distributed_CommandStatus");
+    assert_eq!(status.operation, command_status_operation());
+    assert_eq!(
+        status.operation_hash,
+        hash_bytes(status.operation.as_bytes())
+    );
+    assert!(first
+        .commands
+        .iter()
+        .any(|command| command.name == "todo.complete"));
+    assert!(!first
+        .commands
+        .iter()
+        .any(|command| command.name == "todo.force_archive"));
+    assert_eq!(first.commands[0].grants, vec!["user"]);
+    assert!(first.commands.iter().all(|command| {
+        command.extensions.consistency.kind == "accepted"
+            && command.extensions.effects.as_ref().is_some_and(|effects| {
+                effects.operations.is_empty() && effects.fallback == "revalidate"
+            })
+            && command.extensions.confirmations.is_none()
+    }));
+
+    let json = serde_json::to_string(&first).unwrap();
+    assert!(!json.contains("secret"));
+    assert!(!json.contains("user_id"));
+    assert!(!json.contains("force_archive"));
+    assert!(
+        json.contains("x-user-id"),
+        "portable row policies expose only the static claim name, never its value"
+    );
+}
+
+#[test]
+fn filter_execution_limits_are_schema_fingerprinted_without_changing_protocol_epoch() {
+    let full = full_surface();
+    let selected = surface_for_role(&full, "user", &grants()["user"]).unwrap();
+    let baseline = DistributedClientSurfaceExport::from_selected("todos-service", selected.clone())
+        .unwrap()
+        .manifest()
+        .unwrap();
+
+    let mut bool_limits = ClientExecutionLimits::default();
+    bool_limits.max_bool_width += 1;
+    let bool_manifest = DistributedClientSurfaceExport::from_selected_with_execution(
+        "todos-service",
+        selected.clone(),
+        bool_limits,
+    )
+    .unwrap()
+    .manifest()
+    .unwrap();
+
+    let mut in_limits = ClientExecutionLimits::default();
+    in_limits.max_in_list += 1;
+    let in_manifest = DistributedClientSurfaceExport::from_selected_with_execution(
+        "todos-service",
+        selected,
+        in_limits,
+    )
+    .unwrap()
+    .manifest()
+    .unwrap();
+
+    assert_ne!(
+        baseline.schema_fingerprint,
+        bool_manifest.schema_fingerprint
+    );
+    assert_ne!(baseline.schema_fingerprint, in_manifest.schema_fingerprint);
+    assert_ne!(
+        bool_manifest.schema_fingerprint,
+        in_manifest.schema_fingerprint
+    );
+    assert_eq!(baseline.protocol_version, 1);
+    assert_eq!(
+        baseline.protocol_fingerprint,
+        bool_manifest.protocol_fingerprint
+    );
+    assert_eq!(
+        baseline.protocol_fingerprint,
+        in_manifest.protocol_fingerprint
+    );
+}
+
+#[test]
+fn relationship_nullability_is_copied_from_the_authoritative_surface() {
+    let mut fingerprints = Vec::new();
+    for nullable in [false, true] {
+        let mut todo_schema = todos();
+        todo_schema
+            .columns
+            .iter_mut()
+            .find(|column| column.column_name == "owner_id")
+            .expect("owner foreign key")
+            .nullable = nullable;
+        let full = build_surface(&[todo_schema, users()], &SurfaceOptions::sqlite()).unwrap();
+        let selected = surface_for_role(
+            &full,
+            "user",
+            &BTreeMap::from([
+                ("TodoView".into(), RoleGrant::all_columns()),
+                ("UserView".into(), RoleGrant::all_columns()),
+            ]),
+        )
+        .unwrap();
+        let surface_nullable = selected.models["TodoView"]
+            .relationships
+            .iter()
+            .find(|relationship| relationship.name == "owner")
+            .expect("surface relationship")
+            .nullable;
+        assert_eq!(surface_nullable, nullable);
+
+        let manifest = client_manifest_from_surface(
+            "todos-service",
+            ClientSurfaceIdentity::role("user"),
+            &selected,
+        )
+        .unwrap();
+        fingerprints.push(manifest.schema_fingerprint.clone());
+        let owner = manifest
+            .models
+            .iter()
+            .find(|model| model.id == "TodoView")
+            .unwrap()
+            .relationships
+            .iter()
+            .find(|relationship| relationship.name == "owner")
+            .unwrap();
+        assert_eq!(owner.nullable, surface_nullable);
+        assert_eq!(serde_json::to_value(owner).unwrap()["nullable"], nullable);
+    }
+    assert_ne!(
+        fingerprints[0], fingerprints[1],
+        "relationship nullability is part of the schema fingerprint"
+    );
+}
+
+#[test]
+fn query_protocol_capabilities_are_complete_or_explicitly_revalidate() {
+    let fully_owned = build_surface(&[todos(), users()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_projectors([
+            SurfaceProjector::new("project_todos")
+                .facts(["todo.changed"])
+                .models(["TodoView"])
+                .change_epoch("todos-v1"),
+            SurfaceProjector::new("project_users")
+                .facts(["user.changed"])
+                .models(["UserView"])
+                .partition_constant(serde_json::json!({"scope": "all"}))
+                .change_epoch("users-v1"),
+        ])
+        .unwrap();
+    let fully_owned = manifest_for_all_models("query-capabilities", "user", &fully_owned);
+    assert!(fully_owned.capabilities.record_revisions);
+    assert!(fully_owned.capabilities.tombstones);
+    assert!(fully_owned.capabilities.live_resume);
+    assert_eq!(fully_owned.capabilities.query_fallback, "revalidate");
+    assert!(fully_owned
+        .models
+        .iter()
+        .all(|model| model.record_revisions && model.tombstones));
+    let wire = serde_json::to_value(&fully_owned).unwrap();
+    assert_eq!(wire["capabilities"]["record_revisions"], true);
+    assert_eq!(wire["capabilities"]["query_fallback"], "revalidate");
+    assert!(wire["capabilities"].get("framework_revisions").is_none());
+    assert!(wire["models"][0].get("framework_revision").is_none());
+
+    let dynamic = build_surface(&[users()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_projectors([SurfaceProjector::new("project_users")
+            .facts(["user.changed"])
+            .models(["UserView"])
+            .partition_by(["tenant_id"])
+            .change_epoch("users-v1")])
+        .unwrap();
+    let dynamic = manifest_for_all_models("query-capabilities", "user", &dynamic);
+    assert!(dynamic.capabilities.record_revisions);
+    assert!(dynamic.capabilities.tombstones);
+    assert!(!dynamic.capabilities.live_resume);
+    assert_eq!(dynamic.capabilities.query_fallback, "revalidate");
+
+    let row_filtered = build_surface(&[users()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_projectors([SurfaceProjector::new("project_users")
+            .facts(["user.changed"])
+            .models(["UserView"])
+            .change_epoch("users-v1")])
+        .unwrap();
+    let row_filtered = surface_for_role(
+        &row_filtered,
+        "user",
+        &BTreeMap::from([(
+            "UserView".into(),
+            RoleGrant::all_columns().rows(col("user_id").eq("visible-user")),
+        )]),
+    )
+    .unwrap();
+    let row_filtered = client_manifest_from_surface(
+        "query-capabilities",
+        ClientSurfaceIdentity::role("user"),
+        &row_filtered,
+    )
+    .unwrap();
+    assert!(row_filtered.capabilities.record_revisions);
+    assert!(row_filtered.capabilities.tombstones);
+    assert!(
+        !row_filtered.capabilities.live_resume,
+        "partition-wide positions and changes must not cross a row-authorization boundary"
+    );
+
+    let epochless = build_surface(&[users()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_projectors([SurfaceProjector::new("project_users")
+            .facts(["user.changed"])
+            .models(["UserView"])])
+        .unwrap();
+    let epochless = manifest_for_all_models("query-capabilities", "user", &epochless);
+    assert!(epochless.capabilities.record_revisions);
+    assert!(epochless.capabilities.tombstones);
+    assert!(!epochless.capabilities.live_resume);
+    assert_eq!(epochless.capabilities.query_fallback, "revalidate");
+
+    let unowned = build_surface(&[users()], &SurfaceOptions::sqlite()).unwrap();
+    let unowned = manifest_for_all_models("query-capabilities", "user", &unowned);
+    assert!(!unowned.capabilities.record_revisions);
+    assert!(!unowned.capabilities.tombstones);
+    assert!(!unowned.capabilities.live_resume);
+    assert_eq!(unowned.capabilities.query_fallback, "revalidate");
+    assert!(unowned
+        .models
+        .iter()
+        .all(|model| !model.record_revisions && !model.tombstones));
+
+    let mixed = build_surface(&[todos(), users()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_projectors([SurfaceProjector::new("project_todos")
+            .facts(["todo.changed"])
+            .models(["TodoView"])
+            .change_epoch("todos-v1")])
+        .unwrap();
+    let mixed = manifest_for_all_models("query-capabilities", "user", &mixed);
+    assert!(!mixed.capabilities.record_revisions);
+    assert!(!mixed.capabilities.tombstones);
+    assert!(!mixed.capabilities.live_resume);
+    assert_eq!(mixed.capabilities.query_fallback, "revalidate");
+    assert!(mixed
+        .models
+        .iter()
+        .find(|model| model.id == "TodoView")
+        .is_some_and(|model| model.record_revisions && model.tombstones));
+    assert!(mixed
+        .models
+        .iter()
+        .find(|model| model.id == "UserView")
+        .is_some_and(|model| !model.record_revisions && !model.tombstones));
+
+    let uncovered_join = build_surface(
+        &[teams(), users(), team_members()],
+        &SurfaceOptions::sqlite(),
+    )
+    .unwrap()
+    .with_projectors([
+        SurfaceProjector::new("project_teams")
+            .facts(["team.changed"])
+            .models(["TeamView"])
+            .change_epoch("teams-v1"),
+        SurfaceProjector::new("project_users")
+            .facts(["user.changed"])
+            .models(["UserView"])
+            .change_epoch("users-v1"),
+    ])
+    .unwrap();
+    let uncovered_join = manifest_for_all_models("query-capabilities", "user", &uncovered_join);
+    assert!(uncovered_join.capabilities.record_revisions);
+    assert!(uncovered_join.capabilities.tombstones);
+    assert!(!uncovered_join.capabilities.live_resume);
+    assert_eq!(uncovered_join.capabilities.query_fallback, "revalidate");
+
+    let mut query_only_options = SurfaceOptions::sqlite();
+    query_only_options.subscriptions = false;
+    let query_only = build_surface(&[users()], &query_only_options)
+        .unwrap()
+        .with_projectors([SurfaceProjector::new("project_users")
+            .facts(["user.changed"])
+            .models(["UserView"])
+            .change_epoch("users-v1")])
+        .unwrap();
+    let query_only = manifest_for_all_models("query-capabilities", "user", &query_only);
+    assert!(query_only.capabilities.record_revisions);
+    assert!(query_only.capabilities.tombstones);
+    assert!(!query_only.capabilities.live_queries);
+    assert!(!query_only.capabilities.live_resume);
+    assert_eq!(query_only.capabilities.query_fallback, "revalidate");
+
+    let empty = build_surface(&[], &SurfaceOptions::sqlite()).unwrap();
+    let empty = manifest_for_all_models("query-capabilities", "user", &empty);
+    assert!(!empty.capabilities.record_revisions);
+    assert!(!empty.capabilities.tombstones);
+    assert!(!empty.capabilities.live_resume);
+    assert_eq!(empty.capabilities.query_fallback, "revalidate");
+}
+
+#[test]
+fn composite_keys_normalize_in_declared_order_and_hidden_keys_embed() {
+    let full = full_surface();
+    let admin = surface_for_role(&full, "admin", &grants()["admin"]).unwrap();
+    let admin_manifest = client_manifest_from_surface(
+        "todos-service",
+        ClientSurfaceIdentity::role("admin"),
+        &admin,
+    )
+    .unwrap();
+    let membership = admin_manifest
+        .models
+        .iter()
+        .find(|model| model.id == "MembershipView")
+        .unwrap();
+    let ModelNormalization::Normalized { fields, encoding } = &membership.normalization else {
+        panic!("composite model should normalize")
+    };
+    assert_eq!(
+        fields
+            .iter()
+            .map(|field| field.name.as_str())
+            .collect::<Vec<_>>(),
+        vec!["tenant_id", "user_id"]
+    );
+    assert_eq!(encoding, KEY_ENCODING);
+
+    let user = surface_for_role(&full, "user", &grants()["user"]).unwrap();
+    let user_manifest =
+        client_manifest_from_surface("todos-service", ClientSurfaceIdentity::role("user"), &user)
+            .unwrap();
+    let membership = user_manifest
+        .models
+        .iter()
+        .find(|model| model.id == "MembershipView")
+        .unwrap();
+    assert_eq!(membership.normalization, ModelNormalization::Embedded);
+    assert!(!serde_json::to_string(membership)
+        .unwrap()
+        .contains("user_id"));
+}
+
+#[test]
+fn bigint_keys_embed_until_decimal_string_identity_is_available() {
+    let accounts = TableSchema {
+        model_name: "AccountView".into(),
+        table_name: "accounts".into(),
+        columns: vec![TableColumn {
+            primary_key: true,
+            ..column("account_id", ColumnType::Integer)
+        }],
+        primary_key: PrimaryKey::new(["account_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    };
+    let invoices = TableSchema {
+        model_name: "InvoiceView".into(),
+        table_name: "invoices".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..column("invoice_id", ColumnType::Text)
+            },
+            column("account_id", ColumnType::Integer),
+        ],
+        primary_key: PrimaryKey::new(["invoice_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "account".into(),
+            kind: RelationshipKind::BelongsTo,
+            target_model: "AccountView".into(),
+            foreign_key: Some("account_id".into()),
+            through: None,
+            target_foreign_key: None,
+        }],
+        kind: TableKind::ReadModel,
+    };
+    let full = build_surface(&[accounts, invoices], &SurfaceOptions::sqlite()).unwrap();
+    let selected = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([
+            (
+                "AccountView".into(),
+                RoleGrant::all_columns().rows(col("account_id").eq(9_007_199_254_740_992_i64)),
+            ),
+            ("InvoiceView".into(), RoleGrant::all_columns()),
+        ]),
+    )
+    .unwrap();
+    let manifest = DistributedClientSurfaceExport::from_selected("billing", selected)
+        .unwrap()
+        .manifest()
+        .unwrap();
+
+    let account = manifest
+        .models
+        .iter()
+        .find(|model| model.id == "AccountView")
+        .unwrap();
+    assert_eq!(account.normalization, ModelNormalization::Embedded);
+    assert_eq!(account.row_policy, ClientRowPolicy::ServerOnly);
+    assert!(!serde_json::to_string(account)
+        .unwrap()
+        .contains("9007199254740992"));
+    let relationship = manifest
+        .models
+        .iter()
+        .find(|model| model.id == "InvoiceView")
+        .unwrap()
+        .relationships
+        .iter()
+        .find(|relationship| relationship.name == "account")
+        .unwrap();
+    assert_eq!(relationship.key_mapping, RelationshipKeyMapping::Embedded);
+    assert_eq!(
+        relationship.maintenance,
+        ClientRelationshipMaintenance::Revalidate
+    );
+}
+
+#[test]
+fn application_surface_is_common_contract_with_safe_role_limit_semantics() {
+    let full = full_surface();
+    let all_grants = grants();
+    let selected =
+        surface_for_application(&full, "web", &["user".into(), "admin".into()], &all_grants)
+            .unwrap();
+    let manifest = client_manifest_from_surface(
+        "todos-service",
+        ClientSurfaceIdentity::application("web", ["admin", "user"]),
+        &selected,
+    )
+    .unwrap();
+    assert!(!manifest
+        .commands
+        .iter()
+        .any(|command| command.name == "todo.force_archive"));
+    let todos = manifest
+        .roots
+        .iter()
+        .find(|root| root.id == "query:todos")
+        .unwrap();
+    assert_eq!(todos.pagination.as_ref().unwrap().default_limit, 25);
+    assert_eq!(todos.pagination.as_ref().unwrap().max_limit, 25);
+    assert!(matches!(
+        todos.filter.as_ref().unwrap().row_policy,
+        ClientRowPolicy::ServerOnly
+    ));
+
+    let admin = surface_for_role(&full, "admin", &all_grants["admin"]).unwrap();
+    let admin_manifest = client_manifest_from_surface(
+        "todos-service",
+        ClientSurfaceIdentity::role("admin"),
+        &admin,
+    )
+    .unwrap();
+    let admin_todos = admin_manifest
+        .roots
+        .iter()
+        .find(|root| root.id == "query:todos")
+        .unwrap();
+    assert_eq!(admin_todos.pagination.as_ref().unwrap().default_limit, 100);
+    assert_eq!(admin_todos.pagination.as_ref().unwrap().max_limit, 1000);
+    assert_ne!(
+        manifest.schema_fingerprint,
+        admin_manifest.schema_fingerprint
+    );
+    assert_eq!(
+        manifest.protocol_fingerprint,
+        admin_manifest.protocol_fingerprint
+    );
+}
+
+#[test]
+fn mixed_target_projectors_are_omitted_for_role_and_application_surfaces() {
+    let full = build_surface(&[todos(), users(), teams()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_projectors([
+            SurfaceProjector::new("project_todos")
+                .facts(["todo.changed"])
+                .models(["TodoView"]),
+            SurfaceProjector::new("project_user_team")
+                .facts(["private-user.changed"])
+                .models(["UserView", "TeamView"]),
+        ])
+        .unwrap();
+    let restricted = BTreeMap::from([
+        ("TodoView".into(), RoleGrant::all_columns()),
+        ("UserView".into(), RoleGrant::all_columns()),
+    ]);
+    let admin = BTreeMap::from([
+        ("TodoView".into(), RoleGrant::all_columns()),
+        ("UserView".into(), RoleGrant::all_columns()),
+        ("TeamView".into(), RoleGrant::all_columns()),
+    ]);
+
+    let role = surface_for_role(&full, "restricted", &restricted).unwrap();
+    let role_manifest = DistributedClientSurfaceExport::from_selected("todos-service", role)
+        .unwrap()
+        .manifest()
+        .unwrap();
+    assert_eq!(
+        role_manifest
+            .projectors
+            .iter()
+            .map(|projector| projector.name.as_str())
+            .collect::<Vec<_>>(),
+        vec!["project_todos"]
+    );
+    assert!(!role_manifest.capabilities.record_revisions);
+    assert!(!role_manifest.capabilities.tombstones);
+    assert!(!role_manifest.capabilities.live_resume);
+    assert!(role_manifest
+        .models
+        .iter()
+        .find(|model| model.id == "TodoView")
+        .is_some_and(|model| model.record_revisions && model.tombstones));
+    assert!(role_manifest
+        .models
+        .iter()
+        .find(|model| model.id == "UserView")
+        .is_some_and(|model| !model.record_revisions && !model.tombstones));
+    let role_json = serde_json::to_string(&role_manifest).unwrap();
+    assert!(!role_json.contains("project_user_team"));
+    assert!(!role_json.contains("private-user.changed"));
+
+    let application = surface_for_application(
+        &full,
+        "web",
+        &["admin".into(), "restricted".into()],
+        &BTreeMap::from([("admin".into(), admin), ("restricted".into(), restricted)]),
+    )
+    .unwrap();
+    let application_manifest =
+        DistributedClientSurfaceExport::from_selected("todos-service", application)
+            .unwrap()
+            .manifest()
+            .unwrap();
+    assert_eq!(
+        application_manifest
+            .projectors
+            .iter()
+            .map(|projector| projector.name.as_str())
+            .collect::<Vec<_>>(),
+        vec!["project_todos"]
+    );
+    assert!(!application_manifest.capabilities.record_revisions);
+    assert!(!application_manifest.capabilities.tombstones);
+    assert!(!application_manifest.capabilities.live_resume);
+    let application_json = serde_json::to_string(&application_manifest).unwrap();
+    assert!(!application_json.contains("project_user_team"));
+    assert!(!application_json.contains("private-user.changed"));
+}
+
+#[test]
+fn aggregate_nodes_export_exact_role_bounded_window_semantics() {
+    let mut options = SurfaceOptions::sqlite();
+    options.default_limit = 7;
+    options.max_limit = 19;
+    let full = build_surface(&[teams(), users(), team_members()], &options).unwrap();
+    let selected = surface_for_role(
+        &full,
+        "admin",
+        &BTreeMap::from([
+            ("TeamView".into(), RoleGrant::all_columns()),
+            (
+                "UserView".into(),
+                RoleGrant::all_columns().with_aggregations().limit(13),
+            ),
+        ]),
+    )
+    .unwrap();
+    let manifest = client_manifest_from_surface(
+        "teams-service",
+        ClientSurfaceIdentity::role("admin"),
+        &selected,
+    )
+    .unwrap();
+
+    let users_aggregate = manifest
+        .roots
+        .iter()
+        .find(|root| root.operation == ClientRootOperation::Query && root.name == "users_aggregate")
+        .expect("aggregate root grant");
+    assert!(
+        users_aggregate.pagination.is_none(),
+        "ordinary root pagination must not stand in for aggregate nodes"
+    );
+    let root_semantics = users_aggregate
+        .aggregate
+        .as_ref()
+        .expect("aggregate root semantics");
+    assert_eq!(root_semantics.wrapper_typename, "users_aggregate");
+    assert_eq!(root_semantics.fields_typename, "users_aggregate_fields");
+    assert_eq!(
+        root_semantics.nodes_pagination,
+        ClientPaginationSemantics {
+            kind: "offset".into(),
+            default_limit: 7,
+            max_limit: 13,
+            coverage: "window".into(),
+        }
+    );
+
+    let members_aggregate = manifest
+        .models
+        .iter()
+        .find(|model| model.id == "TeamView")
+        .unwrap()
+        .relationships
+        .iter()
+        .find(|relationship| relationship.name == "members")
+        .unwrap()
+        .aggregate
+        .as_ref()
+        .expect("relationship aggregate grant");
+    assert_eq!(
+        members_aggregate.semantics.wrapper_typename,
+        "users_aggregate"
+    );
+    assert_eq!(
+        members_aggregate.semantics.fields_typename,
+        "users_aggregate_fields"
+    );
+    assert_eq!(
+        members_aggregate.semantics.nodes_pagination,
+        root_semantics.nodes_pagination
+    );
+    assert_eq!(
+        serde_json::to_value(&members_aggregate.semantics).unwrap()["nodes_pagination"],
+        serde_json::json!({
+            "kind": "offset",
+            "default_limit": 7,
+            "max_limit": 13,
+            "coverage": "window"
+        })
+    );
+}
+
+#[test]
+fn opaque_m2m_plan_preserves_invalidation_without_leaking_join_internals() {
+    let full = build_surface(
+        &[teams(), users(), team_members()],
+        &SurfaceOptions::sqlite(),
+    )
+    .unwrap();
+    let admin = surface_for_role(
+        &full,
+        "admin",
+        &BTreeMap::from([
+            ("TeamView".into(), RoleGrant::all_columns()),
+            (
+                "UserView".into(),
+                RoleGrant::all_columns().with_aggregations(),
+            ),
+        ]),
+    )
+    .unwrap();
+    let manifest = client_manifest_from_surface(
+        "teams-service",
+        ClientSurfaceIdentity::role("admin"),
+        &admin,
+    )
+    .unwrap();
+    assert!(!manifest.capabilities.causal_receipts);
+    assert!(manifest.capabilities.cache_scope);
+    assert!(manifest.protocol_operations.command_status.is_none());
+    let members = manifest
+        .models
+        .iter()
+        .find(|model| model.id == "TeamView")
+        .unwrap()
+        .relationships
+        .iter()
+        .find(|relationship| relationship.name == "members")
+        .unwrap();
+    assert!(!members.nullable, "list relationships are non-null lists");
+    let RelationshipKeyMapping::ThroughOpaque {
+        local,
+        remote,
+        dependency,
+    } = &members.key_mapping
+    else {
+        panic!("authorized source/target keys should retain an opaque m2m plan")
+    };
+    assert_eq!(local, &["team_id"]);
+    assert_eq!(remote, &["user_id"]);
+    assert!(dependency.starts_with("opaque:sha256:"));
+    assert_eq!(
+        members.maintenance,
+        ClientRelationshipMaintenance::Revalidate
+    );
+    let aggregate = members.aggregate.as_ref().expect("aggregate grant");
+    assert_eq!(aggregate.name, "members_aggregate");
+    assert_eq!(aggregate.semantics.wrapper_typename, "users_aggregate");
+    assert_eq!(
+        aggregate.semantics.fields_typename,
+        "users_aggregate_fields"
+    );
+    assert!(aggregate.semantics.count && aggregate.semantics.nodes);
+    assert_eq!(aggregate.dependencies, members.dependencies);
+    let users_aggregate = manifest
+        .roots
+        .iter()
+        .find(|root| root.operation == ClientRootOperation::Query && root.name == "users_aggregate")
+        .expect("aggregate root grant");
+    let users_aggregate_semantics = users_aggregate
+        .aggregate
+        .as_ref()
+        .expect("aggregate root semantics");
+    assert_eq!(
+        users_aggregate_semantics.wrapper_typename,
+        "users_aggregate"
+    );
+    assert_eq!(
+        users_aggregate_semantics.fields_typename,
+        "users_aggregate_fields"
+    );
+    assert!(members.dependencies.contains(&"teams".into()));
+    assert!(members.dependencies.contains(&"users".into()));
+    assert!(members
+        .dependencies
+        .iter()
+        .any(|dependency| dependency.starts_with("opaque:sha256:")));
+    let json = serde_json::to_string(&manifest).unwrap();
+    assert!(!json.contains("private_team_members"));
+
+    let mut renamed_team = teams();
+    renamed_team.relationships[0].through = Some("renamed_private_join".into());
+    let mut renamed_join = team_members();
+    renamed_join.table_name = "renamed_private_join".into();
+    let renamed_full = build_surface(
+        &[renamed_team, users(), renamed_join],
+        &SurfaceOptions::sqlite(),
+    )
+    .unwrap();
+    let renamed_admin = surface_for_role(
+        &renamed_full,
+        "admin",
+        &BTreeMap::from([
+            ("TeamView".into(), RoleGrant::all_columns()),
+            (
+                "UserView".into(),
+                RoleGrant::all_columns().with_aggregations(),
+            ),
+        ]),
+    )
+    .unwrap();
+    let renamed_manifest = client_manifest_from_surface(
+        "teams-service",
+        ClientSurfaceIdentity::role("admin"),
+        &renamed_admin,
+    )
+    .unwrap();
+    let renamed_members = renamed_manifest
+        .models
+        .iter()
+        .find(|model| model.id == "TeamView")
+        .unwrap()
+        .relationships
+        .iter()
+        .find(|relationship| relationship.name == "members")
+        .unwrap();
+    let RelationshipKeyMapping::ThroughOpaque {
+        dependency: renamed_dependency,
+        ..
+    } = &renamed_members.key_mapping
+    else {
+        panic!("renamed private join should remain opaque")
+    };
+    assert_eq!(renamed_dependency, dependency);
+
+    let denied = surface_for_role(
+        &full,
+        "limited",
+        &BTreeMap::from([
+            ("TeamView".into(), RoleGrant::columns(["name"])),
+            ("UserView".into(), RoleGrant::all_columns()),
+        ]),
+    )
+    .unwrap();
+    let denied = client_manifest_from_surface(
+        "teams-service",
+        ClientSurfaceIdentity::role("limited"),
+        &denied,
+    )
+    .unwrap();
+    let team = denied
+        .models
+        .iter()
+        .find(|model| model.id == "TeamView")
+        .unwrap();
+    let members = team
+        .relationships
+        .iter()
+        .find(|relationship| relationship.name == "members")
+        .unwrap();
+    assert_eq!(members.key_mapping, RelationshipKeyMapping::Embedded);
+    assert_eq!(
+        members.maintenance,
+        ClientRelationshipMaintenance::Revalidate
+    );
+    assert!(!members.dependencies.is_empty());
+    assert!(members.aggregate.is_none());
+    let team_json = serde_json::to_string(team).unwrap();
+    assert!(!team_json.contains("team_id"));
+    assert!(!team_json.contains("private_team_members"));
+}
+
+#[test]
+fn visible_read_model_join_emits_explicit_local_m2m_plan() {
+    let mut join = team_members();
+    join.model_name = "TeamMemberView".into();
+    join.kind = TableKind::ReadModel;
+    let full = build_surface(&[teams(), users(), join], &SurfaceOptions::sqlite()).unwrap();
+    let selected = surface_for_role(
+        &full,
+        "admin",
+        &BTreeMap::from([
+            ("TeamView".into(), RoleGrant::all_columns()),
+            ("UserView".into(), RoleGrant::all_columns()),
+            ("TeamMemberView".into(), RoleGrant::all_columns()),
+        ]),
+    )
+    .unwrap();
+    let manifest = DistributedClientSurfaceExport::from_selected("teams-service", selected)
+        .unwrap()
+        .manifest()
+        .unwrap();
+    let members = manifest
+        .models
+        .iter()
+        .find(|model| model.id == "TeamView")
+        .unwrap()
+        .relationships
+        .iter()
+        .find(|relationship| relationship.name == "members")
+        .unwrap();
+    assert_eq!(
+        members.key_mapping,
+        RelationshipKeyMapping::Through {
+            local: vec!["team_id".into()],
+            remote: vec!["user_id".into()],
+            table: "private_team_members".into(),
+            source_foreign_key: "team_id".into(),
+            target_foreign_key: "user_id".into(),
+        }
+    );
+    assert_eq!(members.maintenance, ClientRelationshipMaintenance::Local);
+    assert_eq!(
+        members.dependencies,
+        vec!["private_team_members", "teams", "users"]
+    );
+}
+
+#[test]
+fn relational_row_policy_is_server_only_when_relationship_key_is_hidden() {
+    let full = build_surface(&[todos(), users()], &SurfaceOptions::sqlite()).unwrap();
+    let selected = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([
+            (
+                "TodoView".into(),
+                RoleGrant::columns(["todo_id", "title", "completed"])
+                    .rows(rel("owner", col("display_name").eq("Patrick"))),
+            ),
+            ("UserView".into(), RoleGrant::columns(["display_name"])),
+        ]),
+    )
+    .unwrap();
+    let manifest = client_manifest_from_surface(
+        "todos-service",
+        ClientSurfaceIdentity::role("user"),
+        &selected,
+    )
+    .unwrap();
+    let todo = manifest
+        .models
+        .iter()
+        .find(|model| model.id == "TodoView")
+        .unwrap();
+    assert_eq!(todo.row_policy, ClientRowPolicy::ServerOnly);
+    let owner = todo
+        .relationships
+        .iter()
+        .find(|relationship| relationship.name == "owner")
+        .unwrap();
+    assert_eq!(owner.key_mapping, RelationshipKeyMapping::Embedded);
+    assert_eq!(owner.dependencies, vec!["todos", "users"]);
+    assert_eq!(owner.maintenance, ClientRelationshipMaintenance::Revalidate);
+    let json = serde_json::to_string(todo).unwrap();
+    assert!(!json.contains("owner_id"));
+    assert!(!json.contains("user_id"));
+    assert!(!json.contains("Patrick"));
+}
+
+#[test]
+fn application_role_sets_are_canonical_before_fingerprinting() {
+    let full = full_surface();
+    let selected =
+        surface_for_application(&full, "web", &["admin".into(), "user".into()], &grants()).unwrap();
+    let first = client_manifest_from_surface(
+        "todos-service",
+        ClientSurfaceIdentity::Application {
+            name: "web".into(),
+            roles: vec!["user".into(), "admin".into(), "user".into()],
+        },
+        &selected,
+    )
+    .unwrap();
+    let second = client_manifest_from_surface(
+        "todos-service",
+        ClientSurfaceIdentity::Application {
+            name: "web".into(),
+            roles: vec!["admin".into(), "user".into()],
+        },
+        &selected,
+    )
+    .unwrap();
+    assert_eq!(first, second);
+    assert_eq!(first.schema_fingerprint, second.schema_fingerprint);
+    assert_eq!(
+        first.surface,
+        ClientSurfaceIdentity::application("web", ["admin", "user"])
+    );
+}
+
+#[test]
+fn catalog_or_mismatched_surface_cannot_be_labeled_as_authorized() {
+    let full = full_surface();
+    let error =
+        DistributedClientSurfaceExport::from_selected("todos-service", full.clone()).unwrap_err();
+    assert!(error
+        .to_string()
+        .contains("explicitly role- or application-selected"));
+
+    let selected = surface_for_role(&full, "user", &grants()["user"]).unwrap();
+    let wrong_project = DistributedProjectManifest::new("wrong-service").table_schema(users());
+    let inventory_error =
+        DistributedClientSurfaceExport::from_project(&wrong_project, selected.clone()).unwrap_err();
+    assert!(inventory_error.to_string().contains("does not match"));
+
+    let error = client_manifest_from_surface(
+        "todos-service",
+        ClientSurfaceIdentity::role("admin"),
+        &selected,
+    )
+    .unwrap_err();
+    assert!(error.to_string().contains("does not match"));
+}
diff --git a/src/graphql/client_manifest/types.rs b/src/graphql/client_manifest/types.rs
new file mode 100644
index 00000000..145385f7
--- /dev/null
+++ b/src/graphql/client_manifest/types.rs
@@ -0,0 +1,420 @@
+use super::*;
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct DistributedClientManifest {
+    pub manifest_version: u32,
+    pub protocol_version: u32,
+    pub service_id: String,
+    pub surface: ClientSurfaceIdentity,
+    pub schema_fingerprint: String,
+    pub protocol_fingerprint: String,
+    pub execution: ClientExecutionLimits,
+    pub capabilities: ClientCapabilities,
+    pub scalar_codecs: Vec<ScalarCodec>,
+    pub models: Vec<ClientModel>,
+    pub roots: Vec<ClientRoot>,
+    pub commands: Vec<ClientCommand>,
+    pub protocol_operations: ClientProtocolOperations,
+    pub projectors: Vec<ClientProjector>,
+}
+
+/// Framework-owned operations generated alongside application operations.
+///
+/// Keeping these documents in the manifest means clients never synthesize a
+/// status query or guess the server's protocol field selection.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientProtocolOperations {
+    pub version: u32,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub command_status: Option<ClientProtocolOperation>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientProtocolOperation {
+    pub name: String,
+    pub operation: String,
+    pub operation_hash: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientCapabilities {
+    pub live_queries: bool,
+    pub record_revisions: bool,
+    pub tombstones: bool,
+    pub causal_receipts: bool,
+    pub live_resume: bool,
+    /// Safe behavior whenever exact query evidence or resume is unavailable.
+    pub query_fallback: String,
+    pub cache_scope: bool,
+    /// Durable restore of confirmed normalized state.
+    pub confirmed_persistence: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ScalarCodec {
+    pub scalar: String,
+    pub codec: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct ClientModel {
+    pub id: String,
+    pub typename: String,
+    pub source_table: String,
+    pub dependencies: Vec<String>,
+    pub normalization: ModelNormalization,
+    pub fields: Vec<ClientField>,
+    pub relationships: Vec<ClientRelationship>,
+    /// Exact GraphQL predicate input owned by this role-selected model.
+    ///
+    /// This is deliberately model-level rather than copied from a list root or
+    /// relationship selection. GraphQL bool-exp relationships exist regardless
+    /// of whether the corresponding object field accepts list arguments.
+    pub filter_input: ClientFilterInput,
+    pub row_policy: ClientRowPolicy,
+    pub record_revisions: bool,
+    pub tombstones: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum ModelNormalization {
+    Normalized {
+        fields: Vec<ClientKeyField>,
+        encoding: String,
+    },
+    Embedded,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientKeyField {
+    pub name: String,
+    pub codec: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientField {
+    pub name: String,
+    pub scalar: String,
+    pub codec: String,
+    pub nullable: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientFilterInput {
+    pub type_name: String,
+    pub fields: Vec<ClientFilterField>,
+    pub relationships: Vec<ClientFilterInputRelationship>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientFilterInputRelationship {
+    pub field: String,
+    pub target_type: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum ClientRowPolicy {
+    Unrestricted,
+    Predicate { expression: FilterExpr },
+    ServerOnly,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct ClientRelationship {
+    pub name: String,
+    pub target_model: String,
+    pub target_typename: String,
+    pub kind: ClientRelationshipKind,
+    pub list: bool,
+    /// Copied from the role-filtered Surface. Lists are non-null collections;
+    /// singular relationships retain the authoritative object nullability.
+    pub nullable: bool,
+    pub arguments: Vec<ClientArgument>,
+    pub key_mapping: RelationshipKeyMapping,
+    pub maintenance: ClientRelationshipMaintenance,
+    pub dependencies: Vec<String>,
+    pub filter: Option<ClientFilterSemantics>,
+    pub order: Option<ClientOrderSemantics>,
+    pub pagination: Option<ClientPaginationSemantics>,
+    pub aggregate: Option<ClientRelationshipAggregate>,
+    pub live: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientRelationshipAggregate {
+    pub name: String,
+    pub arguments: Vec<ClientArgument>,
+    pub semantics: ClientAggregateSemantics,
+    pub dependencies: Vec<String>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ClientRelationshipKind {
+    HasMany,
+    BelongsTo,
+    ManyToMany,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum RelationshipKeyMapping {
+    Direct {
+        local: Vec<String>,
+        remote: Vec<String>,
+    },
+    Through {
+        local: Vec<String>,
+        remote: Vec<String>,
+        table: String,
+        source_foreign_key: String,
+        target_foreign_key: String,
+    },
+    ThroughOpaque {
+        local: Vec<String>,
+        remote: Vec<String>,
+        dependency: String,
+    },
+    Embedded,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ClientRelationshipMaintenance {
+    /// Incoming normalized entities are sufficient to update membership.
+    Local,
+    /// Dependency changes mark the relationship stale and trigger revalidation.
+    Revalidate,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct ClientRoot {
+    pub id: String,
+    pub operation: ClientRootOperation,
+    pub name: String,
+    pub kind: ClientRootKind,
+    pub model: String,
+    pub arguments: Vec<ClientArgument>,
+    pub filter: Option<ClientFilterSemantics>,
+    pub order: Option<ClientOrderSemantics>,
+    pub pagination: Option<ClientPaginationSemantics>,
+    pub aggregate: Option<ClientAggregateSemantics>,
+    pub dependencies: Vec<String>,
+    pub live: bool,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ClientRootOperation {
+    Query,
+    Subscription,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ClientRootKind {
+    List,
+    ByPk,
+    Aggregate,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientArgument {
+    pub name: String,
+    pub kind: ClientArgumentKind,
+    pub type_name: String,
+    pub nullable: bool,
+    pub list: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub codec: Option<String>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ClientArgumentKind {
+    Filter,
+    Order,
+    Limit,
+    Offset,
+    PrimaryKey,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct ClientFilterSemantics {
+    pub fields: Vec<ClientFilterField>,
+    pub relationships: Vec<String>,
+    pub row_policy: ClientRowPolicy,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientFilterField {
+    pub name: String,
+    pub operators: Vec<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientOrderSemantics {
+    pub fields: Vec<String>,
+    pub values: Vec<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientPaginationSemantics {
+    pub kind: String,
+    pub default_limit: u64,
+    pub max_limit: u64,
+    pub coverage: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientAggregateSemantics {
+    /// Exact GraphQL wrapper object selected by this root or relationship.
+    pub wrapper_typename: String,
+    /// Exact GraphQL object returned by the wrapper's `aggregate` field.
+    pub fields_typename: String,
+    /// Authoritative bounded-window semantics for the wrapper's `nodes` field.
+    ///
+    /// Aggregate roots do not expose the ordinary list root's pagination
+    /// metadata, and relationship aggregates are distinct fields from their
+    /// sibling list relationships. Carrying this plan on the aggregate itself
+    /// prevents clients from treating an omitted/default-limited `nodes`
+    /// selection as a complete model collection.
+    pub nodes_pagination: ClientPaginationSemantics,
+    pub count: bool,
+    pub nodes: bool,
+    pub sum: Vec<String>,
+    pub avg: Vec<String>,
+    pub min: Vec<String>,
+    pub max: Vec<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientCommand {
+    pub version: u32,
+    pub name: String,
+    pub mutation_field: String,
+    pub grants: Vec<String>,
+    pub input: ClientCommandShape,
+    pub output: ClientCommandShape,
+    /// Canonical executable GraphQL operation; clients never synthesize it.
+    pub operation: String,
+    pub operation_hash: String,
+    pub extensions: ClientCommandExtensionSlots,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum ClientCommandShape {
+    None,
+    Object { definition: ClientTypeDef },
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientTypeDef {
+    pub name: String,
+    pub fields: Vec<ClientTypeField>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientTypeField {
+    pub name: String,
+    pub type_name: String,
+    pub nullable: bool,
+    pub list: bool,
+    pub item_nullable: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub codec: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub nested: Option<Box<ClientTypeDef>>,
+}
+
+/// Versioned typed command semantics exported from the executable service.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientCommandExtensionSlots {
+    pub version: u32,
+    pub consistency: CommandConsistencyExtension,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub direct_projection: Option<CommandDirectProjectionExtension>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub input_defaults: Option<CommandInputDefaultsExtension>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub effects: Option<CommandEffectsExtension>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub confirmations: Option<CommandConfirmationsExtension>,
+    /// Names and wire codecs only. Values are server-derived for the current
+    /// verified Session and are never frozen into a generated artifact.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub trusted_presets: Vec<ClientTrustedPresetDescriptor>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+pub struct ClientTrustedPresetDescriptor {
+    pub name: String,
+    pub codec: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CommandConsistencyExtension {
+    pub version: u32,
+    pub kind: String,
+}
+
+/// Opaque same-transaction target for one `Projected<T>` command.
+///
+/// The topology digest binds the scope-codec version, accepted facts, complete
+/// owned schemas, partition declaration, and physical ownership on the server.
+/// The role-selected client contract therefore needs only this exact identity,
+/// never the hidden topology inventory used to compile it.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CommandDirectProjectionExtension {
+    pub topology: ClientProjectionTopologyIdentity,
+    pub model: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub partition: Option<serde_json::Value>,
+    pub change_epoch: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientProjectionTopologyIdentity {
+    pub version: u32,
+    pub name: String,
+    pub digest: String,
+}
+
+/// Generators applied once to the canonical command input before dispatch.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CommandInputDefaultsExtension {
+    pub version: u32,
+    pub defaults: Vec<serde_json::Value>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CommandEffectsExtension {
+    pub version: u32,
+    pub operations: Vec<serde_json::Value>,
+    pub fallback: String,
+}
+
+/// Declaration-owned projector progress expected after a fact commit.
+/// Entries use the same closed input-expression/key IR as optimistic effects.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CommandConfirmationsExtension {
+    pub version: u32,
+    /// `finite` contains the complete authorized edge set; `unavailable`
+    /// intentionally carries no topology and requires revalidation.
+    pub kind: String,
+    pub expected: Vec<serde_json::Value>,
+    pub fallback: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClientProjector {
+    pub version: u32,
+    pub name: String,
+    pub facts: Vec<String>,
+    pub models: Vec<String>,
+    pub dependencies: Vec<String>,
+    pub causal_confirmation: bool,
+}
diff --git a/src/graphql/client_manifest/validation.rs b/src/graphql/client_manifest/validation.rs
new file mode 100644
index 00000000..d3b3b7ee
--- /dev/null
+++ b/src/graphql/client_manifest/validation.rs
@@ -0,0 +1,292 @@
+use super::*;
+
+pub(crate) fn trusted_preset_descriptors(
+    manifest: &DistributedClientManifest,
+) -> Result<Vec<ClientTrustedPresetDescriptor>, ClientManifestError> {
+    let models: BTreeMap<&str, &ClientModel> = manifest
+        .models
+        .iter()
+        .map(|model| (model.id.as_str(), model))
+        .collect();
+    let mut descriptors = BTreeMap::<String, String>::new();
+
+    for command in &manifest.commands {
+        for descriptor in &command.extensions.trusted_presets {
+            insert_trusted_preset_descriptor(
+                &mut descriptors,
+                descriptor,
+                &format!("command `{}`", command.name),
+            )?;
+        }
+    }
+    for model in &manifest.models {
+        if let ClientRowPolicy::Predicate { expression } = &model.row_policy {
+            collect_row_policy_trusted_presets(expression, model, &models, &mut descriptors)?;
+        }
+    }
+
+    Ok(descriptors
+        .into_iter()
+        .map(|(name, codec)| ClientTrustedPresetDescriptor { name, codec })
+        .collect())
+}
+
+fn collect_row_policy_trusted_presets(
+    expression: &FilterExpr,
+    model: &ClientModel,
+    models: &BTreeMap<&str, &ClientModel>,
+    descriptors: &mut BTreeMap<String, String>,
+) -> Result<(), ClientManifestError> {
+    match expression {
+        FilterExpr::And(expressions) | FilterExpr::Or(expressions) => {
+            for expression in expressions {
+                collect_row_policy_trusted_presets(expression, model, models, descriptors)?;
+            }
+        }
+        FilterExpr::Not(expression) => {
+            collect_row_policy_trusted_presets(expression, model, models, descriptors)?;
+        }
+        FilterExpr::Cmp {
+            column,
+            rhs: Operand::Claim(claim),
+            ..
+        } => {
+            insert_row_policy_trusted_preset(model, column, &claim.header, descriptors)?;
+        }
+        FilterExpr::In { column, values, .. } => {
+            for value in values {
+                if let Operand::Claim(claim) = value {
+                    insert_row_policy_trusted_preset(model, column, &claim.header, descriptors)?;
+                }
+            }
+        }
+        FilterExpr::Rel { field, predicate } => {
+            let relationship = model
+                .relationships
+                .iter()
+                .find(|relationship| relationship.name == *field)
+                .ok_or_else(|| {
+                    ClientManifestError(format!(
+                        "model `{}` client-visible row policy references absent relationship `{field}`",
+                        model.id
+                    ))
+                })?;
+            let target = models
+                .get(relationship.target_model.as_str())
+                .copied()
+                .ok_or_else(|| {
+                    ClientManifestError(format!(
+                        "model `{}` client-visible row policy relationship `{field}` targets absent model `{}`",
+                        model.id, relationship.target_model
+                    ))
+                })?;
+            collect_row_policy_trusted_presets(predicate, target, models, descriptors)?;
+        }
+        FilterExpr::Cmp { .. } | FilterExpr::IsNull { .. } => {}
+    }
+    Ok(())
+}
+
+fn insert_row_policy_trusted_preset(
+    model: &ClientModel,
+    column: &str,
+    name: &str,
+    descriptors: &mut BTreeMap<String, String>,
+) -> Result<(), ClientManifestError> {
+    let field = model
+        .fields
+        .iter()
+        .find(|field| field.name == column)
+        .ok_or_else(|| {
+            ClientManifestError(format!(
+                "model `{}` client-visible row policy references absent field `{column}`",
+                model.id
+            ))
+        })?;
+    if matches!(field.codec.as_str(), "base64" | "json") {
+        return Err(ClientManifestError(format!(
+            "model `{}` row-policy claim `{name}` targets `{column}` with non-local codec `{}`",
+            model.id, field.codec
+        )));
+    }
+    insert_trusted_preset_descriptor(
+        descriptors,
+        &ClientTrustedPresetDescriptor {
+            name: name.into(),
+            codec: field.codec.clone(),
+        },
+        &format!("model `{}` row policy field `{column}`", model.id),
+    )
+}
+
+fn insert_trusted_preset_descriptor(
+    descriptors: &mut BTreeMap<String, String>,
+    descriptor: &ClientTrustedPresetDescriptor,
+    owner: &str,
+) -> Result<(), ClientManifestError> {
+    if descriptor.name.is_empty()
+        || descriptor.name.len() > 128
+        || descriptor.name.trim() != descriptor.name
+        || descriptor.name.chars().any(char::is_control)
+    {
+        return Err(ClientManifestError(format!(
+            "{owner} has an invalid trusted preset name"
+        )));
+    }
+    match descriptors.entry(descriptor.name.clone()) {
+        std::collections::btree_map::Entry::Vacant(entry) => {
+            entry.insert(descriptor.codec.clone());
+        }
+        std::collections::btree_map::Entry::Occupied(entry) if entry.get() == &descriptor.codec => {
+        }
+        std::collections::btree_map::Entry::Occupied(entry) => {
+            return Err(ClientManifestError(format!(
+                "trusted preset `{}` uses incompatible codecs `{}` and `{}` across the selected client surface ({owner})",
+                descriptor.name,
+                entry.get(),
+                descriptor.codec
+            )));
+        }
+    }
+    Ok(())
+}
+pub(super) fn validate_surface_structure(surface: &Surface) -> Result<(), ClientManifestError> {
+    fn unique_nonempty<'a>(
+        values: impl IntoIterator<Item = &'a str>,
+        label: &str,
+    ) -> Result<(), ClientManifestError> {
+        let mut seen = BTreeSet::new();
+        for value in values {
+            if value.trim().is_empty() {
+                return Err(ClientManifestError(format!("{label} id must not be empty")));
+            }
+            if !seen.insert(value) {
+                return Err(ClientManifestError(format!(
+                    "duplicate {label} id `{value}`"
+                )));
+            }
+        }
+        Ok(())
+    }
+
+    unique_nonempty(
+        surface
+            .models
+            .values()
+            .map(|model| model.model_name.as_str()),
+        "model",
+    )?;
+    unique_nonempty(
+        surface
+            .models
+            .values()
+            .map(|model| model.table_name.as_str()),
+        "model source table",
+    )?;
+    unique_nonempty(
+        surface
+            .models
+            .values()
+            .map(|model| model.object_name.as_str()),
+        "model typename",
+    )?;
+    for (key, model) in &surface.models {
+        if key != &model.model_name {
+            return Err(ClientManifestError(format!(
+                "surface model map key `{key}` does not match model id `{}`",
+                model.model_name
+            )));
+        }
+        unique_nonempty(
+            model.columns.iter().map(|field| field.name.as_str()),
+            "field",
+        )?;
+        unique_nonempty(
+            model.relationships.iter().map(|field| field.name.as_str()),
+            "relationship",
+        )?;
+        if let SurfaceRowPolicy::Predicate(predicate) = &model.row_policy {
+            predicate
+                .validate_row_policy_literals()
+                .map_err(ClientManifestError)?;
+            if !predicate.is_client_portable() {
+                return Err(ClientManifestError(format!(
+                    "model `{}` exposes a row policy with a JavaScript-unsafe integer; select it through surface_for_role so it becomes server-only",
+                    model.model_name
+                )));
+            }
+        }
+        for relationship in &model.relationships {
+            if !surface.models.contains_key(&relationship.target_model) {
+                return Err(ClientManifestError(format!(
+                    "model `{}` relationship `{}` targets absent model `{}`",
+                    model.model_name, relationship.name, relationship.target_model
+                )));
+            }
+            unique_nonempty(
+                relationship.dependencies.iter().map(String::as_str),
+                &format!(
+                    "model `{}` relationship `{}` dependency",
+                    model.model_name, relationship.name
+                ),
+            )?;
+        }
+    }
+    unique_nonempty(
+        surface.query_fields.iter().map(|root| root.name.as_str()),
+        "query root",
+    )?;
+    unique_nonempty(
+        surface
+            .subscription_fields
+            .iter()
+            .map(|root| root.name.as_str()),
+        "subscription root",
+    )?;
+    unique_nonempty(
+        surface
+            .commands
+            .iter()
+            .map(|command| command.command_name.as_str()),
+        "command",
+    )?;
+    unique_nonempty(
+        surface
+            .commands
+            .iter()
+            .map(|command| command.field_name.as_str()),
+        "command mutation field",
+    )?;
+    for command in &surface.commands {
+        unique_nonempty(
+            command.roles.iter().map(String::as_str),
+            &format!("command `{}` role", command.command_name),
+        )?;
+    }
+    unique_nonempty(
+        surface
+            .projectors
+            .iter()
+            .map(|projector| projector.name.as_str()),
+        "projector",
+    )?;
+    for projector in &surface.projectors {
+        unique_nonempty(
+            projector.facts.iter().map(String::as_str),
+            &format!("projector `{}` fact", projector.name),
+        )?;
+        unique_nonempty(
+            projector.models.iter().map(String::as_str),
+            &format!("projector `{}` model", projector.name),
+        )?;
+        for model in &projector.models {
+            if !surface.models.contains_key(model) {
+                return Err(ClientManifestError(format!(
+                    "projector `{}` targets absent model `{model}`",
+                    projector.name
+                )));
+            }
+        }
+    }
+    Ok(())
+}
diff --git a/src/graphql/command_contract/direct_projection.rs b/src/graphql/command_contract/direct_projection.rs
new file mode 100644
index 00000000..04e27854
--- /dev/null
+++ b/src/graphql/command_contract/direct_projection.rs
@@ -0,0 +1,520 @@
+use std::any::TypeId;
+use std::marker::PhantomData;
+use std::sync::Arc;
+
+use super::effect_wire::{EffectWireCompatible, EffectWireString, TypedEffectExpression};
+use super::effects::EffectExpression;
+use super::projection_obligations::ProjectorTopologyIdentity;
+use super::projection_proof::canonical_json;
+use crate::microsvc::Session;
+use crate::projection_protocol::{
+    ProjectionEpoch, ProjectionModelOwnership, ProjectionPartition, ProjectionPartitionSpec,
+    ProjectionProtocolError, ProjectionScopeCodec, ProjectorTopologyId,
+    SameTransactionProjectionBatch,
+};
+use crate::read_model::RelationalReadModel;
+use crate::table::{TableMutation, TableSchema};
+
+/// Compiler-retained relational identity for one ordinary `Projected<M>`
+/// declaration before the GraphQL Surface resolves its unique physical owner.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct CommandProjectedModel {
+    pub(crate) output_type_id: TypeId,
+    pub(crate) model: String,
+    pub(crate) table: String,
+    pub(crate) schema: &'static TableSchema,
+    pub(crate) partition: Option<EffectExpression>,
+}
+
+impl CommandProjectedModel {
+    pub(super) fn new(output_type_id: TypeId, schema: &'static TableSchema) -> Self {
+        Self {
+            output_type_id,
+            model: schema.model_name.clone(),
+            table: schema.table_name.clone(),
+            schema,
+            partition: None,
+        }
+    }
+
+    pub(super) fn canonical_value(&self) -> serde_json::Value {
+        canonical_json(&serde_json::json!({
+            "model": self.model,
+            "table": self.table,
+            "partition": self.partition,
+        }))
+    }
+
+    pub(crate) fn partition_matches(&self, partition: &ProjectionPartitionSpec) -> bool {
+        match partition {
+            ProjectionPartitionSpec::Unit => self.partition.is_none(),
+            ProjectionPartitionSpec::Constant { value } => {
+                self.partition
+                    == Some(EffectExpression::Constant {
+                        value: value.clone(),
+                    })
+            }
+            ProjectionPartitionSpec::InputPath { .. } => self.partition.is_some(),
+        }
+    }
+
+    pub(crate) fn bind(
+        &self,
+        projector: &str,
+        facts: &[String],
+        models: &[String],
+        projector_partition: &ProjectionPartitionSpec,
+        change_epoch: Option<&str>,
+        mut ownership: Vec<ProjectionModelOwnership>,
+        protocol_topology: Option<ProjectorTopologyId>,
+    ) -> CommandDirectProjectionTarget {
+        ownership.sort_by(|left, right| {
+            (left.model.as_str(), left.table.as_str())
+                .cmp(&(right.model.as_str(), right.table.as_str()))
+        });
+        CommandDirectProjectionTarget {
+            projector: projector.to_string(),
+            model: self.model.clone(),
+            table: self.table.clone(),
+            output_type_id: self.output_type_id,
+            projector_topology: ProjectorTopologyIdentity::new(
+                projector,
+                facts,
+                models,
+                projector_partition,
+            ),
+            protocol_topology,
+            partition: self.partition.clone(),
+            change_epoch: change_epoch.map(str::to_string),
+            schema: self.schema,
+            ownership,
+        }
+    }
+}
+
+/// Compiler-owned direct target for one `Projected<M>` command.
+///
+/// This metadata is deliberately hidden from ordinary handler code. Generated
+/// declarations bind it once; application handlers still only call
+/// `context.projected(view)`.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct CommandDirectProjectionTarget {
+    pub(crate) projector: String,
+    pub(crate) model: String,
+    pub(crate) table: String,
+    pub(crate) output_type_id: TypeId,
+    projector_topology: ProjectorTopologyIdentity,
+    /// Exact post-bind protocol identity compiled from accepted facts, the
+    /// versioned scope codec, and every complete owned table schema. The
+    /// pre-bind typed declaration deliberately carries `None` and cannot
+    /// resolve into a direct projection participant.
+    protocol_topology: Option<ProjectorTopologyId>,
+    pub(crate) partition: Option<EffectExpression>,
+    pub(crate) change_epoch: Option<String>,
+    pub(crate) schema: &'static TableSchema,
+    /// Complete frozen model → physical-table inventory owned by the
+    /// projector topology. Bootstrap claims this entire set atomically even
+    /// though the direct command mutates exactly one output model.
+    pub(crate) ownership: Vec<ProjectionModelOwnership>,
+}
+
+impl CommandDirectProjectionTarget {
+    pub(crate) fn canonical_value(&self) -> serde_json::Value {
+        canonical_json(&serde_json::json!({
+            "projector": self.projector,
+            "projector_topology": self.projector_topology.canonical_value(),
+            "protocol_topology": self.protocol_topology.as_ref().map(|topology| serde_json::json!({
+                "version": topology.version(),
+                "name": topology.name(),
+                "digest": topology.digest(),
+            })),
+            "model": self.model,
+            "table": self.table,
+            "partition": self.partition,
+            "change_epoch": self.change_epoch,
+            "ownership": self.ownership.iter().map(|owner| serde_json::json!({
+                "model": owner.model,
+                "table": owner.table,
+            })).collect::<Vec<_>>(),
+        }))
+    }
+
+    pub(crate) fn topology_matches(
+        &self,
+        name: &str,
+        facts: &[String],
+        models: &[String],
+        projector_partition: &ProjectionPartitionSpec,
+        change_epoch: Option<&str>,
+    ) -> bool {
+        self.projector_topology
+            == ProjectorTopologyIdentity::new(name, facts, models, projector_partition)
+            && self.change_epoch.as_deref() == change_epoch
+    }
+
+    pub(crate) fn protocol_topology_matches(&self, topology: &ProjectorTopologyId) -> bool {
+        self.protocol_topology.as_ref() == Some(topology)
+    }
+
+    /// Exact compiled protocol topology retained by the declaration binder.
+    ///
+    /// Client-manifest export exposes only this opaque identity. The full
+    /// projector facts, schemas, tables, and ownership inventory remain
+    /// server-private.
+    pub(crate) fn protocol_topology(&self) -> Option<&ProjectorTopologyId> {
+        self.protocol_topology.as_ref()
+    }
+
+    pub(crate) fn resolve(
+        &self,
+        canonical_wire_input: &serde_json::Value,
+        session: Option<&Session>,
+    ) -> Result<ResolvedDirectProjectionTarget, DirectProjectionTargetResolutionError> {
+        let change_epoch = self.change_epoch.as_ref().ok_or_else(|| {
+            DirectProjectionTargetResolutionError::InvalidTarget {
+                projector: self.projector.clone(),
+                model: self.model.clone(),
+                reason: "registered projector has no change-log epoch".into(),
+            }
+        })?;
+        let change_epoch = ProjectionEpoch::new(change_epoch.clone()).map_err(|error| {
+            DirectProjectionTargetResolutionError::InvalidTarget {
+                projector: self.projector.clone(),
+                model: self.model.clone(),
+                reason: error.to_string(),
+            }
+        })?;
+        let topology = self.protocol_topology.clone().ok_or_else(|| {
+            DirectProjectionTargetResolutionError::InvalidTarget {
+                projector: self.projector.clone(),
+                model: self.model.clone(),
+                reason: "direct projection target was not bound to its complete compiled topology"
+                    .into(),
+            }
+        })?;
+        let codec = ProjectionScopeCodec::with_models(
+            topology,
+            [(self.schema.model_name.as_str(), self.schema)],
+        )
+        .map_err(
+            |error| DirectProjectionTargetResolutionError::InvalidTarget {
+                projector: self.projector.clone(),
+                model: self.model.clone(),
+                reason: error.to_string(),
+            },
+        )?;
+        let partition_value = self
+            .partition
+            .as_ref()
+            .map(|expression| {
+                resolve_direct_projection_expression(
+                    canonical_wire_input,
+                    self,
+                    "partition",
+                    expression,
+                    session,
+                    Some("String"),
+                )
+            })
+            .transpose()?;
+        let partition = codec
+            .encode_partition(partition_value.as_ref())
+            .map_err(
+                |error| DirectProjectionTargetResolutionError::InvalidTarget {
+                    projector: self.projector.clone(),
+                    model: self.model.clone(),
+                    reason: error.to_string(),
+                },
+            )?;
+        Ok(ResolvedDirectProjectionTarget {
+            codec: Arc::new(codec),
+            partition_value,
+            partition,
+            change_epoch,
+            model: self.model.clone(),
+            table: self.table.clone(),
+            schema: self.schema,
+            ownership: self.ownership.clone(),
+        })
+    }
+}
+
+/// Opaque compiler product attached to a typed projected command.
+#[doc(hidden)]
+pub struct CompiledDirectProjectionTarget<I, M>(
+    pub(super) CommandDirectProjectionTarget,
+    PhantomData<fn(I) -> M>,
+);
+
+impl<I, M> CompiledDirectProjectionTarget<I, M> {
+    /// Generated declarations may resolve the registered projection partition
+    /// from one typed canonical input expression.
+    #[doc(hidden)]
+    pub fn partition<Wire>(mut self, partition: TypedEffectExpression<String, Wire>) -> Self
+    where
+        Wire: EffectWireCompatible<EffectWireString>,
+    {
+        self.0.partition = Some(partition.__into_ir());
+        self
+    }
+}
+
+pub(crate) fn compiled_direct_projection_target<I, M>(
+    projector: &str,
+    facts: &[String],
+    models: &[String],
+    projector_partition: &ProjectionPartitionSpec,
+    change_epoch: Option<&str>,
+) -> CompiledDirectProjectionTarget<I, M>
+where
+    M: RelationalReadModel + 'static,
+{
+    let schema = M::schema();
+    let mut projected = CommandProjectedModel::new(TypeId::of::<M>(), schema);
+    if let ProjectionPartitionSpec::Constant { value } = projector_partition {
+        projected.partition = Some(EffectExpression::Constant {
+            value: value.clone(),
+        });
+    }
+    CompiledDirectProjectionTarget(
+        projected.bind(
+            projector,
+            facts,
+            models,
+            projector_partition,
+            change_epoch,
+            vec![
+                ProjectionModelOwnership::new(&schema.model_name, &schema.table_name)
+                    .expect("validated relational schema has bounded model/table names"),
+            ],
+            None,
+        ),
+        PhantomData,
+    )
+}
+
+pub(crate) struct ResolvedDirectProjectionTarget {
+    codec: Arc<ProjectionScopeCodec>,
+    partition_value: Option<serde_json::Value>,
+    partition: ProjectionPartition,
+    change_epoch: ProjectionEpoch,
+    model: String,
+    table: String,
+    schema: &'static TableSchema,
+    ownership: Vec<ProjectionModelOwnership>,
+}
+
+impl ResolvedDirectProjectionTarget {
+    pub(crate) fn registration(&self) -> (&ProjectorTopologyId, &[ProjectionModelOwnership]) {
+        (self.codec.topology(), &self.ownership)
+    }
+
+    pub(super) fn seal(
+        self,
+        mutation: TableMutation,
+        causation_id: &str,
+    ) -> Result<SameTransactionProjectionBatch, ProjectionProtocolError> {
+        let TableMutation::UpsertRow(row) = &mutation else {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "direct projection proof did not extract a full-row upsert".into(),
+            ));
+        };
+        if row.schema != self.schema
+            || row.schema.model_name != self.model
+            || row.schema.table_name != self.table
+        {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "direct projection target `{}`/`{}` does not match the staged row",
+                self.model, self.table
+            )));
+        }
+        let scope = self
+            .codec
+            .encode_row_scope(
+                self.codec.topology().name(),
+                &self.model,
+                self.partition_value.as_ref(),
+                &row.key,
+            )
+            .map_err(|error| ProjectionProtocolError::InvalidBatch(error.to_string()))?;
+        let ownership = ProjectionModelOwnership::new(self.model, self.table)?;
+        SameTransactionProjectionBatch::single_upsert(
+            self.codec.topology().clone(),
+            self.partition,
+            self.change_epoch,
+            ownership,
+            scope,
+            mutation,
+            causation_id,
+        )
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) enum DirectProjectionTargetResolutionError {
+    MissingInputPath {
+        projector: String,
+        model: String,
+        target: String,
+        path: Vec<String>,
+    },
+    TrustedPresetUnavailable {
+        projector: String,
+        model: String,
+        target: String,
+        preset: String,
+    },
+    InvalidConstant {
+        projector: String,
+        model: String,
+        target: String,
+        error: String,
+    },
+    InvalidTarget {
+        projector: String,
+        model: String,
+        reason: String,
+    },
+}
+
+impl std::fmt::Display for DirectProjectionTargetResolutionError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::MissingInputPath {
+                projector,
+                model,
+                target,
+                path,
+            } => write!(
+                formatter,
+                "direct projection `{projector}`/`{model}` {target} references absent canonical input path `{}`",
+                path.join("."),
+            ),
+            Self::TrustedPresetUnavailable {
+                projector,
+                model,
+                target,
+                preset,
+            } => write!(
+                formatter,
+                "direct projection `{projector}`/`{model}` {target} uses unavailable trusted preset `{preset}`",
+            ),
+            Self::InvalidConstant {
+                projector,
+                model,
+                target,
+                error,
+            } => write!(
+                formatter,
+                "direct projection `{projector}`/`{model}` {target} contains an invalid constant: {error}",
+            ),
+            Self::InvalidTarget {
+                projector,
+                model,
+                reason,
+            } => write!(
+                formatter,
+                "direct projection `{projector}`/`{model}` is invalid: {reason}"
+            ),
+        }
+    }
+}
+
+impl std::error::Error for DirectProjectionTargetResolutionError {}
+
+pub(super) fn resolve_trusted_preset(
+    session: Option<&Session>,
+    name: &str,
+    scalar: &str,
+) -> Option<serde_json::Value> {
+    use base64::Engine as _;
+
+    let raw = session?.get(name)?;
+    match scalar {
+        "ID" | "String" | "Timestamptz" => Some(serde_json::Value::String(raw.to_string())),
+        "Bytea" => {
+            let decoded = base64::engine::general_purpose::STANDARD.decode(raw).ok()?;
+            (base64::engine::general_purpose::STANDARD.encode(decoded) == raw)
+                .then(|| serde_json::Value::String(raw.to_string()))
+        }
+        "Boolean" => match raw {
+            "true" => Some(serde_json::Value::Bool(true)),
+            "false" => Some(serde_json::Value::Bool(false)),
+            _ => None,
+        },
+        "Int" => raw
+            .parse::<i32>()
+            .ok()
+            .filter(|value| value.to_string() == raw)
+            .map(|value| serde_json::json!(value)),
+        "BigInt" => raw
+            .parse::<i64>()
+            .ok()
+            .filter(|value| (-9_007_199_254_740_991..=9_007_199_254_740_991).contains(value))
+            .filter(|value| value.to_string() == raw)
+            .map(|value| serde_json::json!(value)),
+        "Float" => raw
+            .parse::<f64>()
+            .ok()
+            .filter(|value| value.is_finite())
+            .and_then(serde_json::Number::from_f64)
+            .map(serde_json::Value::Number),
+        "JSON" => serde_json::from_str(raw).ok(),
+        _ => None,
+    }
+}
+
+fn resolve_direct_projection_expression(
+    canonical_wire_input: &serde_json::Value,
+    target: &CommandDirectProjectionTarget,
+    field: &str,
+    expression: &EffectExpression,
+    session: Option<&Session>,
+    expected_scalar: Option<&str>,
+) -> Result<serde_json::Value, DirectProjectionTargetResolutionError> {
+    match expression {
+        EffectExpression::Input { path } => {
+            let mut value = canonical_wire_input;
+            if path.is_empty() {
+                return Err(DirectProjectionTargetResolutionError::MissingInputPath {
+                    projector: target.projector.clone(),
+                    model: target.model.clone(),
+                    target: field.to_string(),
+                    path: path.clone(),
+                });
+            }
+            for segment in path {
+                let Some(next) = value.as_object().and_then(|object| object.get(segment)) else {
+                    return Err(DirectProjectionTargetResolutionError::MissingInputPath {
+                        projector: target.projector.clone(),
+                        model: target.model.clone(),
+                        target: field.to_string(),
+                        path: path.clone(),
+                    });
+                };
+                value = next;
+            }
+            Ok(value.clone())
+        }
+        EffectExpression::Constant { value } => Ok(value.clone()),
+        EffectExpression::Null => Ok(serde_json::Value::Null),
+        EffectExpression::TrustedPreset { name } => {
+            resolve_trusted_preset(session, name, expected_scalar.unwrap_or("String")).ok_or_else(
+                || DirectProjectionTargetResolutionError::TrustedPresetUnavailable {
+                    projector: target.projector.clone(),
+                    model: target.model.clone(),
+                    target: field.to_string(),
+                    preset: name.clone(),
+                },
+            )
+        }
+        EffectExpression::InvalidConstant { error } => {
+            Err(DirectProjectionTargetResolutionError::InvalidConstant {
+                projector: target.projector.clone(),
+                model: target.model.clone(),
+                target: field.to_string(),
+                error: error.clone(),
+            })
+        }
+    }
+}
diff --git a/src/graphql/command_contract/effect_wire.rs b/src/graphql/command_contract/effect_wire.rs
new file mode 100644
index 00000000..94483f5b
--- /dev/null
+++ b/src/graphql/command_contract/effect_wire.rs
@@ -0,0 +1,997 @@
+use std::marker::PhantomData;
+
+use serde::ser::{
+    SerializeMap, SerializeSeq, SerializeStruct, SerializeStructVariant, SerializeTuple,
+    SerializeTupleStruct, SerializeTupleVariant,
+};
+use serde::Serialize;
+
+use super::effects::{
+    CommandEffect, CommandEffects, EffectExpression, EffectFieldValue, EffectKey,
+    EffectRelationship,
+};
+use super::projection_obligations::ProjectorTopologyIdentity;
+use super::projection_obligations::{
+    CommandInputDefault, CommandProjectionConfirmation, InputDefaultGenerator,
+};
+use crate::projection_protocol::ProjectionPartitionSpec;
+use crate::read_model::RelationalReadModel;
+
+/// Wire-shape proofs emitted by derives and erased after compatibility checks.
+#[doc(hidden)]
+pub struct EffectWireChecked;
+#[doc(hidden)]
+pub struct EffectWireLiteral;
+#[doc(hidden)]
+pub struct EffectWireString;
+#[doc(hidden)]
+pub struct EffectWireBoolean;
+#[doc(hidden)]
+pub struct EffectWireBigInt;
+#[doc(hidden)]
+pub struct EffectWireFloat;
+#[doc(hidden)]
+pub struct EffectWireJson;
+#[doc(hidden)]
+pub struct EffectWireBytea;
+#[doc(hidden)]
+pub struct EffectWireTimestamp;
+#[doc(hidden)]
+pub struct EffectWireList;
+#[doc(hidden)]
+pub struct EffectWireObject;
+#[doc(hidden)]
+pub struct EffectWireUnsupported;
+
+/// Closed compile-time compatibility relation between GraphQL input wire
+/// shapes and read-model scalar codecs.
+#[doc(hidden)]
+pub trait EffectWireCompatible<Target> {}
+
+macro_rules! exact_effect_wire_compatibility {
+    ($($wire:ty),+ $(,)?) => {
+        $(impl EffectWireCompatible<$wire> for $wire {})+
+    };
+}
+
+exact_effect_wire_compatibility!(
+    EffectWireString,
+    EffectWireBoolean,
+    EffectWireBigInt,
+    EffectWireFloat,
+    EffectWireJson,
+    EffectWireBytea,
+    EffectWireTimestamp,
+    EffectWireList,
+    EffectWireObject,
+    EffectWireUnsupported,
+);
+
+// JSON model columns deliberately accept a complete input container as their
+// leaf value. Other scalar codecs never accept list/object wire shapes.
+impl EffectWireCompatible<EffectWireJson> for EffectWireList {}
+impl EffectWireCompatible<EffectWireJson> for EffectWireObject {}
+
+// Constants and explicit null retain exact Rust value typing; Surface
+// validation checks their serialized scalar/null representation.
+impl<Target> EffectWireCompatible<Target> for EffectWireLiteral {}
+
+/// Typed portable expression used only while constructing erased effect IR.
+#[doc(hidden)]
+pub struct TypedEffectExpression<T, Wire = EffectWireChecked> {
+    expression: EffectExpression,
+    _value: PhantomData<fn() -> (T, Wire)>,
+}
+
+impl<T, Wire> TypedEffectExpression<T, Wire> {
+    #[doc(hidden)]
+    pub(crate) fn __into_ir(self) -> EffectExpression {
+        self.expression
+    }
+
+    fn erase_wire(self) -> TypedEffectExpression<T> {
+        TypedEffectExpression {
+            expression: self.expression,
+            _value: PhantomData,
+        }
+    }
+}
+
+/// Marker implemented only by `GraphqlInput` derive output in normal use.
+///
+/// The trait must be public because derive output lives in downstream crates.
+/// All marker metadata is still revalidated against the final command Surface;
+/// hand-written implementations cannot bypass runtime structural checks.
+#[doc(hidden)]
+pub struct EffectRequired;
+
+#[doc(hidden)]
+pub struct EffectNullable;
+
+/// Derive-owned classification for a field that is a nested input object and
+/// may therefore appear before another segment in an effect input path.
+#[doc(hidden)]
+pub struct EffectInputObjectKind;
+
+/// Derive-owned classification for scalar and list fields. These fields are
+/// valid leaves but cannot be traversed by effect input paths.
+#[doc(hidden)]
+pub struct EffectInputTerminalKind;
+
+#[doc(hidden)]
+pub trait EffectInputPathKind {}
+
+impl EffectInputPathKind for EffectInputObjectKind {}
+impl EffectInputPathKind for EffectInputTerminalKind {}
+
+/// Implemented only for the derive-owned nested-object classification.
+#[doc(hidden)]
+pub trait EffectInputDescendableKind: EffectInputPathKind {}
+
+impl EffectInputDescendableKind for EffectInputObjectKind {}
+
+#[doc(hidden)]
+pub trait EffectPathNullability {
+    type Applied<T>;
+}
+
+impl EffectPathNullability for EffectRequired {
+    type Applied<T> = T;
+}
+
+impl EffectPathNullability for EffectNullable {
+    type Applied<T> = Option<T>;
+}
+
+#[doc(hidden)]
+pub trait CombineEffectNullability<Other: EffectPathNullability> {
+    type Output: EffectPathNullability;
+}
+
+impl CombineEffectNullability<EffectRequired> for EffectRequired {
+    type Output = EffectRequired;
+}
+
+impl CombineEffectNullability<EffectNullable> for EffectRequired {
+    type Output = EffectNullable;
+}
+
+impl CombineEffectNullability<EffectRequired> for EffectNullable {
+    type Output = EffectNullable;
+}
+
+impl CombineEffectNullability<EffectNullable> for EffectNullable {
+    type Output = EffectNullable;
+}
+
+#[doc(hidden)]
+pub trait EffectInputFieldMarker {
+    type Input: 'static;
+    type Value;
+    type NonNullValue;
+    type Nullability: EffectPathNullability;
+    type PathKind: EffectInputPathKind;
+    type Wire;
+    /// Unwrapped object type used when descending through a nested input.
+    type Nested: 'static;
+    fn path() -> Vec<&'static str>;
+}
+
+/// Type-level composition of two derive-generated input-field markers.
+#[doc(hidden)]
+pub struct EffectInputPath<Outer, Inner>(PhantomData<fn(Outer) -> Inner>);
+
+impl<Outer, Inner> EffectInputFieldMarker for EffectInputPath<Outer, Inner>
+where
+    Outer: EffectInputFieldMarker,
+    Inner: EffectInputFieldMarker<Input = Outer::Nested>,
+    Outer::PathKind: EffectInputDescendableKind,
+    Outer::Nullability: CombineEffectNullability<Inner::Nullability>,
+{
+    type Input = Outer::Input;
+    type Value = <<Outer::Nullability as CombineEffectNullability<
+        Inner::Nullability,
+    >>::Output as EffectPathNullability>::Applied<Inner::NonNullValue>;
+    type NonNullValue = Inner::NonNullValue;
+    type Nullability = <Outer::Nullability as CombineEffectNullability<Inner::Nullability>>::Output;
+    type PathKind = Inner::PathKind;
+    type Wire = Inner::Wire;
+    type Nested = Inner::Nested;
+
+    fn path() -> Vec<&'static str> {
+        let mut path = Outer::path();
+        path.extend(Inner::path());
+        path
+    }
+}
+
+/// Convert a derive-generated input marker into a typed portable expression.
+#[doc(hidden)]
+pub fn __effect_input<I, F>() -> TypedEffectExpression<F::Value, F::Wire>
+where
+    I: 'static,
+    F: EffectInputFieldMarker<Input = I>,
+{
+    TypedEffectExpression {
+        expression: EffectExpression::Input {
+            path: F::path().into_iter().map(str::to_string).collect(),
+        },
+        _value: PhantomData,
+    }
+}
+
+/// Wraps a serializer so every nested value is visited through the same
+/// portable-JSON checks. This is intentionally one pass: even a stateful custom
+/// `Serialize` implementation cannot validate one value and emit another.
+struct StrictPortableJsonSerializer<S>(S);
+
+struct StrictPortableJsonValue<'a, T: ?Sized>(&'a T);
+
+impl<T> Serialize for StrictPortableJsonValue<'_, T>
+where
+    T: ?Sized + Serialize,
+{
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        self.0.serialize(StrictPortableJsonSerializer(serializer))
+    }
+}
+
+macro_rules! delegate_portable_scalar {
+    ($($method:ident($value:ty)),+ $(,)?) => {
+        $(
+            fn $method(self, value: $value) -> Result<Self::Ok, Self::Error> {
+                self.0.$method(value)
+            }
+        )+
+    };
+}
+
+impl<S> serde::Serializer for StrictPortableJsonSerializer<S>
+where
+    S: serde::Serializer,
+{
+    type Ok = S::Ok;
+    type Error = S::Error;
+    type SerializeSeq = StrictSerializeSeq<S::SerializeSeq>;
+    type SerializeTuple = StrictSerializeTuple<S::SerializeTuple>;
+    type SerializeTupleStruct = StrictSerializeTupleStruct<S::SerializeTupleStruct>;
+    type SerializeTupleVariant = StrictSerializeTupleVariant<S::SerializeTupleVariant>;
+    type SerializeMap = StrictSerializeMap<S::SerializeMap>;
+    type SerializeStruct = StrictSerializeStruct<S::SerializeStruct>;
+    type SerializeStructVariant = StrictSerializeStructVariant<S::SerializeStructVariant>;
+
+    delegate_portable_scalar! {
+        serialize_bool(bool),
+        serialize_i8(i8),
+        serialize_i16(i16),
+        serialize_i32(i32),
+        serialize_i64(i64),
+        serialize_i128(i128),
+        serialize_u8(u8),
+        serialize_u16(u16),
+        serialize_u32(u32),
+        serialize_u64(u64),
+        serialize_u128(u128),
+        serialize_char(char),
+    }
+
+    fn serialize_f32(self, value: f32) -> Result<Self::Ok, Self::Error> {
+        if !value.is_finite() {
+            return Err(<S::Error as serde::ser::Error>::custom(
+                "non-finite f32/f64 constants cannot be represented in portable JSON",
+            ));
+        }
+        self.0.serialize_f32(value)
+    }
+
+    fn serialize_f64(self, value: f64) -> Result<Self::Ok, Self::Error> {
+        if !value.is_finite() {
+            return Err(<S::Error as serde::ser::Error>::custom(
+                "non-finite f32/f64 constants cannot be represented in portable JSON",
+            ));
+        }
+        self.0.serialize_f64(value)
+    }
+
+    fn serialize_str(self, value: &str) -> Result<Self::Ok, Self::Error> {
+        self.0.serialize_str(value)
+    }
+
+    fn serialize_bytes(self, value: &[u8]) -> Result<Self::Ok, Self::Error> {
+        self.0.serialize_bytes(value)
+    }
+
+    fn serialize_none(self) -> Result<Self::Ok, Self::Error> {
+        self.0.serialize_none()
+    }
+
+    fn serialize_some<T>(self, value: &T) -> Result<Self::Ok, Self::Error>
+    where
+        T: ?Sized + Serialize,
+    {
+        self.0.serialize_some(&StrictPortableJsonValue(value))
+    }
+
+    fn serialize_unit(self) -> Result<Self::Ok, Self::Error> {
+        self.0.serialize_unit()
+    }
+
+    fn serialize_unit_struct(self, name: &'static str) -> Result<Self::Ok, Self::Error> {
+        self.0.serialize_unit_struct(name)
+    }
+
+    fn serialize_unit_variant(
+        self,
+        name: &'static str,
+        variant_index: u32,
+        variant: &'static str,
+    ) -> Result<Self::Ok, Self::Error> {
+        self.0.serialize_unit_variant(name, variant_index, variant)
+    }
+
+    fn serialize_newtype_struct<T>(
+        self,
+        name: &'static str,
+        value: &T,
+    ) -> Result<Self::Ok, Self::Error>
+    where
+        T: ?Sized + Serialize,
+    {
+        self.0
+            .serialize_newtype_struct(name, &StrictPortableJsonValue(value))
+    }
+
+    fn serialize_newtype_variant<T>(
+        self,
+        name: &'static str,
+        variant_index: u32,
+        variant: &'static str,
+        value: &T,
+    ) -> Result<Self::Ok, Self::Error>
+    where
+        T: ?Sized + Serialize,
+    {
+        self.0.serialize_newtype_variant(
+            name,
+            variant_index,
+            variant,
+            &StrictPortableJsonValue(value),
+        )
+    }
+
+    fn serialize_seq(self, len: Option<usize>) -> Result<Self::SerializeSeq, Self::Error> {
+        self.0.serialize_seq(len).map(StrictSerializeSeq)
+    }
+
+    fn serialize_tuple(self, len: usize) -> Result<Self::SerializeTuple, Self::Error> {
+        self.0.serialize_tuple(len).map(StrictSerializeTuple)
+    }
+
+    fn serialize_tuple_struct(
+        self,
+        name: &'static str,
+        len: usize,
+    ) -> Result<Self::SerializeTupleStruct, Self::Error> {
+        self.0
+            .serialize_tuple_struct(name, len)
+            .map(StrictSerializeTupleStruct)
+    }
+
+    fn serialize_tuple_variant(
+        self,
+        name: &'static str,
+        variant_index: u32,
+        variant: &'static str,
+        len: usize,
+    ) -> Result<Self::SerializeTupleVariant, Self::Error> {
+        self.0
+            .serialize_tuple_variant(name, variant_index, variant, len)
+            .map(StrictSerializeTupleVariant)
+    }
+
+    fn serialize_map(self, len: Option<usize>) -> Result<Self::SerializeMap, Self::Error> {
+        self.0.serialize_map(len).map(StrictSerializeMap)
+    }
+
+    fn serialize_struct(
+        self,
+        name: &'static str,
+        len: usize,
+    ) -> Result<Self::SerializeStruct, Self::Error> {
+        self.0
+            .serialize_struct(name, len)
+            .map(StrictSerializeStruct)
+    }
+
+    fn serialize_struct_variant(
+        self,
+        name: &'static str,
+        variant_index: u32,
+        variant: &'static str,
+        len: usize,
+    ) -> Result<Self::SerializeStructVariant, Self::Error> {
+        self.0
+            .serialize_struct_variant(name, variant_index, variant, len)
+            .map(StrictSerializeStructVariant)
+    }
+
+    fn is_human_readable(&self) -> bool {
+        self.0.is_human_readable()
+    }
+}
+
+struct StrictSerializeSeq<S>(S);
+
+impl<S> SerializeSeq for StrictSerializeSeq<S>
+where
+    S: SerializeSeq,
+{
+    type Ok = S::Ok;
+    type Error = S::Error;
+
+    fn serialize_element<T>(&mut self, value: &T) -> Result<(), Self::Error>
+    where
+        T: ?Sized + Serialize,
+    {
+        self.0.serialize_element(&StrictPortableJsonValue(value))
+    }
+
+    fn end(self) -> Result<Self::Ok, Self::Error> {
+        self.0.end()
+    }
+}
+
+struct StrictSerializeTuple<S>(S);
+
+impl<S> SerializeTuple for StrictSerializeTuple<S>
+where
+    S: SerializeTuple,
+{
+    type Ok = S::Ok;
+    type Error = S::Error;
+
+    fn serialize_element<T>(&mut self, value: &T) -> Result<(), Self::Error>
+    where
+        T: ?Sized + Serialize,
+    {
+        self.0.serialize_element(&StrictPortableJsonValue(value))
+    }
+
+    fn end(self) -> Result<Self::Ok, Self::Error> {
+        self.0.end()
+    }
+}
+
+struct StrictSerializeTupleStruct<S>(S);
+
+impl<S> SerializeTupleStruct for StrictSerializeTupleStruct<S>
+where
+    S: SerializeTupleStruct,
+{
+    type Ok = S::Ok;
+    type Error = S::Error;
+
+    fn serialize_field<T>(&mut self, value: &T) -> Result<(), Self::Error>
+    where
+        T: ?Sized + Serialize,
+    {
+        self.0.serialize_field(&StrictPortableJsonValue(value))
+    }
+
+    fn end(self) -> Result<Self::Ok, Self::Error> {
+        self.0.end()
+    }
+}
+
+struct StrictSerializeTupleVariant<S>(S);
+
+impl<S> SerializeTupleVariant for StrictSerializeTupleVariant<S>
+where
+    S: SerializeTupleVariant,
+{
+    type Ok = S::Ok;
+    type Error = S::Error;
+
+    fn serialize_field<T>(&mut self, value: &T) -> Result<(), Self::Error>
+    where
+        T: ?Sized + Serialize,
+    {
+        self.0.serialize_field(&StrictPortableJsonValue(value))
+    }
+
+    fn end(self) -> Result<Self::Ok, Self::Error> {
+        self.0.end()
+    }
+}
+
+struct StrictSerializeMap<S>(S);
+
+impl<S> SerializeMap for StrictSerializeMap<S>
+where
+    S: SerializeMap,
+{
+    type Ok = S::Ok;
+    type Error = S::Error;
+
+    fn serialize_key<T>(&mut self, key: &T) -> Result<(), Self::Error>
+    where
+        T: ?Sized + Serialize,
+    {
+        self.0.serialize_key(&StrictPortableJsonValue(key))
+    }
+
+    fn serialize_value<T>(&mut self, value: &T) -> Result<(), Self::Error>
+    where
+        T: ?Sized + Serialize,
+    {
+        self.0.serialize_value(&StrictPortableJsonValue(value))
+    }
+
+    fn end(self) -> Result<Self::Ok, Self::Error> {
+        self.0.end()
+    }
+}
+
+struct StrictSerializeStruct<S>(S);
+
+impl<S> SerializeStruct for StrictSerializeStruct<S>
+where
+    S: SerializeStruct,
+{
+    type Ok = S::Ok;
+    type Error = S::Error;
+
+    fn serialize_field<T>(&mut self, key: &'static str, value: &T) -> Result<(), Self::Error>
+    where
+        T: ?Sized + Serialize,
+    {
+        self.0.serialize_field(key, &StrictPortableJsonValue(value))
+    }
+
+    fn end(self) -> Result<Self::Ok, Self::Error> {
+        self.0.end()
+    }
+}
+
+struct StrictSerializeStructVariant<S>(S);
+
+impl<S> SerializeStructVariant for StrictSerializeStructVariant<S>
+where
+    S: SerializeStructVariant,
+{
+    type Ok = S::Ok;
+    type Error = S::Error;
+
+    fn serialize_field<T>(&mut self, key: &'static str, value: &T) -> Result<(), Self::Error>
+    where
+        T: ?Sized + Serialize,
+    {
+        self.0.serialize_field(key, &StrictPortableJsonValue(value))
+    }
+
+    fn end(self) -> Result<Self::Ok, Self::Error> {
+        self.0.end()
+    }
+}
+
+/// Serialize a deterministic value emitted by `command_effects!` while
+/// retaining its Rust type for assignment checking. Serialization failures are
+/// retained as private invalid IR and reported as configuration errors; a
+/// declaration must never panic while it is being assembled.
+#[doc(hidden)]
+pub fn __effect_constant<T: Serialize>(value: T) -> TypedEffectExpression<T, EffectWireLiteral> {
+    let expression = match StrictPortableJsonValue(&value).serialize(serde_json::value::Serializer)
+    {
+        Ok(value) => EffectExpression::Constant { value },
+        Err(error) => EffectExpression::InvalidConstant {
+            error: error.to_string(),
+        },
+    };
+    TypedEffectExpression {
+        expression,
+        _value: PhantomData,
+    }
+}
+
+/// Declare a typed value supplied only by the server's verified Session.
+///
+/// The generated artifact retains this bounded descriptor name. It never
+/// embeds a value supplied by the caller.
+#[doc(hidden)]
+pub fn __effect_trusted<T>(name: &'static str) -> TypedEffectExpression<T, EffectWireLiteral> {
+    TypedEffectExpression {
+        expression: EffectExpression::TrustedPreset {
+            name: name.to_string(),
+        },
+        _value: PhantomData,
+    }
+}
+
+/// Explicit nullable constant for optional model fields.
+#[doc(hidden)]
+pub fn __effect_null<T>() -> TypedEffectExpression<Option<T>, EffectWireLiteral> {
+    TypedEffectExpression {
+        expression: EffectExpression::Null,
+        _value: PhantomData,
+    }
+}
+
+/// Assignment compatibility implemented by framework expression types.
+/// Non-null values may flow into nullable fields; nullable values never flow
+/// into non-null fields. Key expressions remain exact and do not use this
+/// conversion.
+#[doc(hidden)]
+pub trait EffectAssignmentExpression<Target> {
+    type Wire;
+    fn into_assignment(self) -> TypedEffectExpression<Target, Self::Wire>;
+}
+
+impl<T, Wire> EffectAssignmentExpression<T> for TypedEffectExpression<T, Wire> {
+    type Wire = Wire;
+
+    fn into_assignment(self) -> TypedEffectExpression<T, Wire> {
+        self
+    }
+}
+
+impl<T, Wire> EffectAssignmentExpression<Option<T>> for TypedEffectExpression<T, Wire> {
+    type Wire = Wire;
+
+    fn into_assignment(self) -> TypedEffectExpression<Option<T>, Wire> {
+        TypedEffectExpression {
+            expression: self.expression,
+            _value: PhantomData,
+        }
+    }
+}
+
+/// Marker implemented by a `ReadModel` derive for one concrete model field.
+#[doc(hidden)]
+pub trait EffectModelFieldMarker {
+    type Model: RelationalReadModel;
+    type Value;
+    type Wire;
+    const FIELD: &'static str;
+}
+
+/// Marker implemented by a `ReadModel` derive for one relationship.
+#[doc(hidden)]
+pub trait EffectRelationshipMarker {
+    type Source: RelationalReadModel;
+    type Target: RelationalReadModel;
+    const FIELD: &'static str;
+}
+
+/// Typed model key generated as a named struct by `#[derive(ReadModel)]`.
+#[doc(hidden)]
+pub struct TypedEffectKey<M> {
+    key: EffectKey,
+    _model: PhantomData<fn() -> M>,
+}
+
+/// Opaque, typed confirmation target created from a projector declaration.
+///
+/// The projector object and model key are reused directly, avoiding a second
+/// application-maintained projector/model string join. Final Surface building
+/// still validates the target against authorized projector topology.
+#[doc(hidden)]
+pub struct CompiledProjectionConfirmation<I>(
+    pub(super) CommandProjectionConfirmation,
+    PhantomData<fn(I)>,
+);
+
+impl<I> CompiledProjectionConfirmation<I> {
+    /// Partition the expected projector progress by a deterministic string/ID
+    /// expression from the same command input.
+    pub fn partition<Wire>(mut self, partition: TypedEffectExpression<String, Wire>) -> Self
+    where
+        Wire: EffectWireCompatible<EffectWireString>,
+    {
+        self.0.partition = Some(partition.__into_ir());
+        self
+    }
+}
+
+pub(crate) fn projection_confirmation<M: RelationalReadModel>(
+    projector: &str,
+    facts: &[String],
+    models: &[String],
+    partition: &ProjectionPartitionSpec,
+    key: TypedEffectKey<M>,
+) -> CommandProjectionConfirmation {
+    CommandProjectionConfirmation {
+        projector: projector.to_string(),
+        model: M::schema().model_name.clone(),
+        key: key.key,
+        partition: match partition {
+            ProjectionPartitionSpec::Constant { value } => Some(EffectExpression::Constant {
+                value: value.clone(),
+            }),
+            ProjectionPartitionSpec::Unit | ProjectionPartitionSpec::InputPath { .. } => None,
+        },
+        projector_topology: ProjectorTopologyIdentity::new(projector, facts, models, partition),
+        protocol_topology: None,
+        schema: Some(M::schema()),
+    }
+}
+
+pub(crate) fn compiled_projection_confirmation<I, M: RelationalReadModel>(
+    projector: &str,
+    facts: &[String],
+    models: &[String],
+    partition: &ProjectionPartitionSpec,
+    key: TypedEffectKey<M>,
+) -> CompiledProjectionConfirmation<I> {
+    CompiledProjectionConfirmation(
+        projection_confirmation(projector, facts, models, partition, key),
+        PhantomData,
+    )
+}
+
+/// Compile-checked, declaration-owned projection confirmation plan.
+///
+/// The input type parameter prevents a plan built for a lookalike input type
+/// from being attached to a different command declaration.
+pub struct CompiledConfirmationPlan<I>(
+    pub(super) Vec<CommandProjectionConfirmation>,
+    PhantomData<fn(I)>,
+);
+
+#[doc(hidden)]
+pub fn __command_confirmations<I>(
+    confirmations: impl IntoIterator<Item = CompiledProjectionConfirmation<I>>,
+) -> CompiledConfirmationPlan<I> {
+    CompiledConfirmationPlan(
+        confirmations
+            .into_iter()
+            .map(|confirmation| confirmation.0)
+            .collect(),
+        PhantomData,
+    )
+}
+
+/// Opaque key field emitted by a `ReadModel` derive. Application code cannot
+/// assemble raw effect IR through the public typed-command API.
+#[doc(hidden)]
+pub struct CompiledEffectKeyField<M>(EffectFieldValue, PhantomData<fn() -> M>);
+
+#[doc(hidden)]
+pub fn __effect_key_field<F>(
+    value: TypedEffectExpression<F::Value>,
+) -> CompiledEffectKeyField<F::Model>
+where
+    F: EffectModelFieldMarker,
+{
+    CompiledEffectKeyField(
+        EffectFieldValue {
+            field: F::FIELD.to_string(),
+            value: value.__into_ir(),
+        },
+        PhantomData,
+    )
+}
+
+/// Prove one generated key expression's wire compatibility, then erase the
+/// proof so derive-generated composite key structs need no wire generics.
+#[doc(hidden)]
+pub fn __effect_key_assignment<F, Wire>(
+    value: TypedEffectExpression<F::Value, Wire>,
+) -> TypedEffectExpression<F::Value>
+where
+    F: EffectModelFieldMarker,
+    Wire: EffectWireCompatible<F::Wire>,
+{
+    value.erase_wire()
+}
+
+/// Assemble a typed model key from derive-generated field markers. The final
+/// Surface validator additionally requires the exact ordered primary key.
+#[doc(hidden)]
+pub fn __effect_key<M: RelationalReadModel>(
+    fields: Vec<CompiledEffectKeyField<M>>,
+) -> TypedEffectKey<M> {
+    TypedEffectKey {
+        key: EffectKey {
+            fields: fields.into_iter().map(|field| field.0).collect(),
+        },
+        _model: PhantomData,
+    }
+}
+
+/// Typed relationship marker generated by `#[derive(ReadModel)]`.
+#[doc(hidden)]
+pub struct TypedEffectRelationship<S, T> {
+    relationship: EffectRelationship,
+    _models: PhantomData<fn(S) -> T>,
+}
+
+impl<S, T> TypedEffectRelationship<S, T> {}
+
+/// Convert a derive-generated relationship marker into opaque typed IR.
+#[doc(hidden)]
+pub fn __effect_relationship<R>() -> TypedEffectRelationship<R::Source, R::Target>
+where
+    R: EffectRelationshipMarker,
+{
+    TypedEffectRelationship {
+        relationship: EffectRelationship {
+            source_model: R::Source::schema().model_name.clone(),
+            field: R::FIELD.to_string(),
+            target_model: R::Target::schema().model_name.clone(),
+        },
+        _models: PhantomData,
+    }
+}
+
+/// Type-checked field assignment helper used by the effect proc macro.
+#[doc(hidden)]
+pub fn __effect_assignment<F, E>(value: E) -> CompiledEffectFieldValue<F::Model>
+where
+    F: EffectModelFieldMarker,
+    E: EffectAssignmentExpression<F::Value>,
+    E::Wire: EffectWireCompatible<F::Wire>,
+{
+    let value = value.into_assignment();
+    CompiledEffectFieldValue(
+        EffectFieldValue {
+            field: F::FIELD.to_string(),
+            value: value.__into_ir(),
+        },
+        PhantomData,
+    )
+}
+
+/// Opaque type-checked field assignment emitted by `command_effects!`.
+#[doc(hidden)]
+pub struct CompiledEffectFieldValue<M>(EffectFieldValue, PhantomData<fn() -> M>);
+
+/// Opaque compiled effect operation. Only generated typed helpers can produce
+/// one; raw IR is not accepted by [`TypedCommand::effects`].
+#[doc(hidden)]
+pub struct CompiledEffectOperation(CommandEffect);
+
+/// One compile-checked generated canonical-input default.
+#[doc(hidden)]
+pub struct CompiledInputDefault<I>(CommandInputDefault, PhantomData<fn(I)>);
+
+/// Declaration-owned generated defaults for one exact command input type.
+pub struct CompiledInputDefaults<I>(pub(super) Vec<CommandInputDefault>, PhantomData<fn(I)>);
+
+#[doc(hidden)]
+pub fn __input_default_uuid_v7<I, F>() -> CompiledInputDefault<I>
+where
+    I: 'static,
+    F: EffectInputFieldMarker<Input = I, Value = String>,
+{
+    CompiledInputDefault(
+        CommandInputDefault {
+            path: F::path().into_iter().map(str::to_string).collect(),
+            generator: InputDefaultGenerator::UuidV7,
+        },
+        PhantomData,
+    )
+}
+
+#[doc(hidden)]
+pub fn __input_default_ulid<I, F>() -> CompiledInputDefault<I>
+where
+    I: 'static,
+    F: EffectInputFieldMarker<Input = I, Value = String>,
+{
+    CompiledInputDefault(
+        CommandInputDefault {
+            path: F::path().into_iter().map(str::to_string).collect(),
+            generator: InputDefaultGenerator::Ulid,
+        },
+        PhantomData,
+    )
+}
+
+#[doc(hidden)]
+pub fn __command_input_defaults<I>(
+    defaults: impl IntoIterator<Item = CompiledInputDefault<I>>,
+) -> CompiledInputDefaults<I> {
+    CompiledInputDefaults(
+        defaults.into_iter().map(|default| default.0).collect(),
+        PhantomData,
+    )
+}
+
+/// Opaque, compile-checked effect declaration returned by `command_effects!`.
+pub struct CompiledCommandEffects<I>(pub(super) CommandEffects, PhantomData<fn(I)>);
+
+#[doc(hidden)]
+pub fn __command_effects<I>(
+    operations: impl IntoIterator<Item = CompiledEffectOperation>,
+) -> CompiledCommandEffects<I> {
+    CompiledCommandEffects(
+        CommandEffects::new(operations.into_iter().map(|operation| operation.0)),
+        PhantomData,
+    )
+}
+
+/// Type-checked upsert helper used by the effect proc macro.
+#[doc(hidden)]
+pub fn __effect_upsert<M: RelationalReadModel>(
+    key: TypedEffectKey<M>,
+    fields: Vec<CompiledEffectFieldValue<M>>,
+) -> CompiledEffectOperation {
+    CompiledEffectOperation(CommandEffect::Upsert {
+        model: M::schema().model_name.clone(),
+        key: key.key,
+        fields: fields.into_iter().map(|field| field.0).collect(),
+    })
+}
+
+/// Type-checked patch helper used by the effect proc macro.
+#[doc(hidden)]
+pub fn __effect_patch<M: RelationalReadModel>(
+    key: TypedEffectKey<M>,
+    fields: Vec<CompiledEffectFieldValue<M>>,
+) -> CompiledEffectOperation {
+    CompiledEffectOperation(CommandEffect::Patch {
+        model: M::schema().model_name.clone(),
+        key: key.key,
+        fields: fields.into_iter().map(|field| field.0).collect(),
+    })
+}
+
+/// Type-checked delete helper used by the effect proc macro.
+#[doc(hidden)]
+pub fn __effect_delete<M: RelationalReadModel>(key: TypedEffectKey<M>) -> CompiledEffectOperation {
+    CompiledEffectOperation(CommandEffect::Delete {
+        model: M::schema().model_name.clone(),
+        key: key.key,
+    })
+}
+
+/// Type-checked link helper used by the effect proc macro.
+#[doc(hidden)]
+pub fn __effect_link<S: RelationalReadModel, T: RelationalReadModel>(
+    relationship: TypedEffectRelationship<S, T>,
+    source: TypedEffectKey<S>,
+    target: TypedEffectKey<T>,
+) -> CompiledEffectOperation {
+    CompiledEffectOperation(CommandEffect::Link {
+        relationship: relationship.relationship,
+        source: source.key,
+        target: target.key,
+    })
+}
+
+/// Type-checked unlink helper used by the effect proc macro.
+#[doc(hidden)]
+pub fn __effect_unlink<S: RelationalReadModel, T: RelationalReadModel>(
+    relationship: TypedEffectRelationship<S, T>,
+    source: TypedEffectKey<S>,
+    target: TypedEffectKey<T>,
+) -> CompiledEffectOperation {
+    CompiledEffectOperation(CommandEffect::Unlink {
+        relationship: relationship.relationship,
+        source: source.key,
+        target: target.key,
+    })
+}
+
+/// Type-checked model invalidation helper used by the effect proc macro.
+#[doc(hidden)]
+pub fn __effect_invalidate_model<M: RelationalReadModel>() -> CompiledEffectOperation {
+    CompiledEffectOperation(CommandEffect::InvalidateModel {
+        model: M::schema().model_name.clone(),
+    })
+}
+
+/// Type-checked relationship invalidation helper used by the effect proc macro.
+#[doc(hidden)]
+pub fn __effect_invalidate_relationship<S: RelationalReadModel, T: RelationalReadModel>(
+    relationship: TypedEffectRelationship<S, T>,
+    source: TypedEffectKey<S>,
+) -> CompiledEffectOperation {
+    CompiledEffectOperation(CommandEffect::InvalidateRelationship {
+        relationship: relationship.relationship,
+        source: source.key,
+    })
+}
diff --git a/src/graphql/command_contract/effects.rs b/src/graphql/command_contract/effects.rs
new file mode 100644
index 00000000..11c0e223
--- /dev/null
+++ b/src/graphql/command_contract/effects.rs
@@ -0,0 +1,174 @@
+use serde::{Deserialize, Serialize};
+
+use super::projection_obligations::CommandProjectionConfirmation;
+
+/// Portable value expression in a command effect.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub(crate) enum EffectExpression {
+    Input {
+        path: Vec<String>,
+    },
+    TrustedPreset {
+        name: String,
+    },
+    Constant {
+        value: serde_json::Value,
+    },
+    /// SQL null, emitted only by the type-checked `null()` expression.
+    Null,
+    /// Construction-time serialization failure. This private sentinel is
+    /// rejected before contract fingerprinting or Surface/manifest emission.
+    #[serde(skip)]
+    InvalidConstant {
+        error: String,
+    },
+}
+
+/// One model-field assignment in portable effect IR.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct EffectFieldValue {
+    pub field: String,
+    pub value: EffectExpression,
+}
+
+/// A complete, ordered model key in portable effect IR.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct EffectKey {
+    pub fields: Vec<EffectFieldValue>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct EffectRelationship {
+    pub source_model: String,
+    pub field: String,
+    pub target_model: String,
+}
+
+/// Closed portable command-effect operation set.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub(crate) enum CommandEffect {
+    Upsert {
+        model: String,
+        key: EffectKey,
+        fields: Vec<EffectFieldValue>,
+    },
+    Patch {
+        model: String,
+        key: EffectKey,
+        fields: Vec<EffectFieldValue>,
+    },
+    Delete {
+        model: String,
+        key: EffectKey,
+    },
+    Link {
+        relationship: EffectRelationship,
+        source: EffectKey,
+        target: EffectKey,
+    },
+    Unlink {
+        relationship: EffectRelationship,
+        source: EffectKey,
+        target: EffectKey,
+    },
+    InvalidateModel {
+        model: String,
+    },
+    InvalidateRelationship {
+        relationship: EffectRelationship,
+        source: EffectKey,
+    },
+}
+
+/// What the client must do when the declared operations cannot prove safety.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum CommandEffectFallback {
+    /// No local invention: mark affected selections stale and revalidate.
+    Revalidate,
+}
+
+/// Version-independent portable effect declaration attached to one command.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct CommandEffects {
+    pub operations: Vec<CommandEffect>,
+    pub fallback: CommandEffectFallback,
+}
+
+impl CommandEffects {
+    pub(crate) fn new(operations: impl IntoIterator<Item = CommandEffect>) -> Self {
+        Self {
+            operations: operations.into_iter().collect(),
+            fallback: CommandEffectFallback::Revalidate,
+        }
+    }
+
+    pub(crate) fn revalidate() -> Self {
+        Self::new([])
+    }
+
+    pub(crate) fn canonicalize(&mut self) {
+        for operation in &mut self.operations {
+            match operation {
+                CommandEffect::Upsert { fields, .. } | CommandEffect::Patch { fields, .. } => {
+                    fields.sort_by(|left, right| left.field.cmp(&right.field));
+                }
+                CommandEffect::Delete { .. }
+                | CommandEffect::Link { .. }
+                | CommandEffect::Unlink { .. }
+                | CommandEffect::InvalidateModel { .. }
+                | CommandEffect::InvalidateRelationship { .. } => {}
+            }
+        }
+    }
+
+    pub(super) fn invalid_constant_error(&self) -> Option<&str> {
+        self.operations
+            .iter()
+            .find_map(|operation| match operation {
+                CommandEffect::Upsert { key, fields, .. }
+                | CommandEffect::Patch { key, fields, .. } => invalid_key_constant(key)
+                    .or_else(|| fields.iter().find_map(invalid_field_constant)),
+                CommandEffect::Delete { key, .. } => invalid_key_constant(key),
+                CommandEffect::Link { source, target, .. }
+                | CommandEffect::Unlink { source, target, .. } => {
+                    invalid_key_constant(source).or_else(|| invalid_key_constant(target))
+                }
+                CommandEffect::InvalidateRelationship { source, .. } => {
+                    invalid_key_constant(source)
+                }
+                CommandEffect::InvalidateModel { .. } => None,
+            })
+    }
+}
+
+pub(super) fn invalid_expression_constant(expression: &EffectExpression) -> Option<&str> {
+    match expression {
+        EffectExpression::InvalidConstant { error } => Some(error),
+        EffectExpression::Input { .. }
+        | EffectExpression::TrustedPreset { .. }
+        | EffectExpression::Constant { .. }
+        | EffectExpression::Null => None,
+    }
+}
+
+fn invalid_field_constant(field: &EffectFieldValue) -> Option<&str> {
+    invalid_expression_constant(&field.value)
+}
+
+fn invalid_key_constant(key: &EffectKey) -> Option<&str> {
+    key.fields.iter().find_map(invalid_field_constant)
+}
+
+pub(super) fn invalid_confirmation_constant(
+    confirmation: &CommandProjectionConfirmation,
+) -> Option<&str> {
+    invalid_key_constant(&confirmation.key).or_else(|| {
+        confirmation
+            .partition
+            .as_ref()
+            .and_then(invalid_expression_constant)
+    })
+}
diff --git a/src/graphql/command_contract/mod.rs b/src/graphql/command_contract/mod.rs
new file mode 100644
index 00000000..1b6c56e6
--- /dev/null
+++ b/src/graphql/command_contract/mod.rs
@@ -0,0 +1,63 @@
+//! Typed command consistency, prepared completions, and portable client effects.
+//!
+//! This module deliberately separates declaration from durable completion. A
+//! handler may prepare a typed payload, but it cannot choose which projection
+//! confirmations count. That finite plan belongs to the command declaration,
+//! and only the framework-owned command-ledger committer may turn a preparation into
+//! an [`Accepted`], [`Fact`], or [`Projected`] value.
+
+#![cfg_attr(not(feature = "graphql"), allow(dead_code))]
+
+mod direct_projection;
+mod effect_wire;
+mod effects;
+mod outcomes;
+mod projection_obligations;
+mod projection_proof;
+mod typed_command;
+
+#[cfg(test)]
+mod tests;
+
+pub use direct_projection::CompiledDirectProjectionTarget;
+pub(crate) use direct_projection::{
+    compiled_direct_projection_target, CommandDirectProjectionTarget, CommandProjectedModel,
+    ResolvedDirectProjectionTarget,
+};
+pub(crate) use effect_wire::compiled_projection_confirmation;
+pub use effect_wire::{
+    __command_confirmations, __command_effects, __command_input_defaults, __effect_assignment,
+    __effect_constant, __effect_delete, __effect_input, __effect_invalidate_model,
+    __effect_invalidate_relationship, __effect_key, __effect_key_assignment, __effect_key_field,
+    __effect_link, __effect_null, __effect_patch, __effect_relationship, __effect_trusted,
+    __effect_unlink, __effect_upsert, __input_default_ulid, __input_default_uuid_v7,
+    CombineEffectNullability, CompiledCommandEffects, CompiledConfirmationPlan,
+    CompiledEffectFieldValue, CompiledEffectKeyField, CompiledEffectOperation,
+    CompiledInputDefault, CompiledInputDefaults, CompiledProjectionConfirmation,
+    EffectAssignmentExpression, EffectInputDescendableKind, EffectInputFieldMarker,
+    EffectInputObjectKind, EffectInputPath, EffectInputPathKind, EffectInputTerminalKind,
+    EffectModelFieldMarker, EffectNullable, EffectPathNullability, EffectRelationshipMarker,
+    EffectRequired, EffectWireBigInt, EffectWireBoolean, EffectWireBytea, EffectWireChecked,
+    EffectWireCompatible, EffectWireFloat, EffectWireJson, EffectWireList, EffectWireLiteral,
+    EffectWireObject, EffectWireString, EffectWireTimestamp, EffectWireUnsupported,
+    TypedEffectExpression, TypedEffectKey, TypedEffectRelationship,
+};
+pub(crate) use effects::{
+    CommandEffect, CommandEffectFallback, CommandEffects, EffectExpression, EffectFieldValue,
+    EffectKey, EffectRelationship,
+};
+pub use outcomes::{
+    Accepted, CommandConsistency, CommandOutcome, Fact, PrepareCommandError, PreparedCommand,
+    Projected,
+};
+pub(crate) use projection_obligations::{
+    validate_projection_confirmation_count, CommandInputDefault, CommandProjectionConfirmation,
+};
+// Re-exported for unit tests that resolve obligations through this module path.
+#[cfg_attr(not(test), allow(unused_imports))]
+pub(crate) use projection_obligations::{
+    ProjectionObligationResolutionError, ProjectorTopologyIdentity,
+};
+pub(crate) use projection_proof::{CommandCommitProofError, ProjectionCommitProof};
+pub use typed_command::{typed_command, TypedCommand};
+pub(crate) use typed_command::{TypedCommandContract, TypedServiceCommandBinding};
diff --git a/src/graphql/command_contract/outcomes.rs b/src/graphql/command_contract/outcomes.rs
new file mode 100644
index 00000000..ccdecaf5
--- /dev/null
+++ b/src/graphql/command_contract/outcomes.rs
@@ -0,0 +1,333 @@
+use std::any::TypeId;
+use std::marker::PhantomData;
+
+use serde::{Deserialize, Serialize};
+
+use super::direct_projection::ResolvedDirectProjectionTarget;
+use super::projection_proof::{CommandCommitProofError, ProjectionCommitProof};
+use super::typed_command::TypedCommandContract;
+use crate::graphql::types::GraphqlOutputType;
+use crate::outbox::OutboxMessage;
+use crate::projection_protocol::SameTransactionProjectionBatch;
+use crate::read_model::RelationalReadModel;
+use crate::table::{TableSchema, TableWritePlan};
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CommandConsistency {
+    /// The command was accepted. With no confirmation plan this is terminal;
+    /// with an explicit finite plan it is accepted pending projection.
+    Accepted,
+    /// A durable fact was committed and declared projectors are expected.
+    Fact,
+    /// The returned view was committed in the command transaction.
+    Projected,
+}
+
+mod sealed {
+    pub trait Outcome {}
+    pub trait PreparableOutcome {}
+}
+
+/// A committed accepted command result.
+///
+/// There is intentionally no public constructor. The durable command
+/// committer is the only framework component allowed to create this wrapper.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Accepted<T> {
+    payload: T,
+}
+
+/// A committed durable-fact command result.
+///
+/// There is intentionally no public constructor. The durable command
+/// committer is the only framework component allowed to create this wrapper.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Fact<T> {
+    payload: T,
+}
+
+/// A committed same-transaction projection result.
+///
+/// There is intentionally no public constructor. The durable command
+/// committer is the only framework component allowed to create this wrapper.
+/// `T` must be a relational read model, and preparation is available only
+/// through the framework-owned workspace that stages the exact row upsert.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Projected<T> {
+    payload: T,
+}
+
+macro_rules! committed_outcome {
+    ($wrapper:ident, $kind:expr) => {
+        impl<T> sealed::Outcome for $wrapper<T> {}
+
+        impl<T> CommandOutcome for $wrapper<T>
+        where
+            T: GraphqlOutputType + Serialize + Send + Sync + 'static,
+        {
+            type Payload = T;
+            const CONSISTENCY: CommandConsistency = $kind;
+
+            fn payload(&self) -> &T {
+                &self.payload
+            }
+
+            fn __finalize_committed(payload: T) -> Self {
+                Self::from_committed_payload(payload)
+            }
+        }
+    };
+}
+
+committed_outcome!(Accepted, CommandConsistency::Accepted);
+committed_outcome!(Fact, CommandConsistency::Fact);
+
+impl<T> sealed::Outcome for Projected<T> where T: RelationalReadModel {}
+
+impl<T> CommandOutcome for Projected<T>
+where
+    T: GraphqlOutputType + RelationalReadModel + Serialize + Send + Sync + 'static,
+{
+    type Payload = T;
+    const CONSISTENCY: CommandConsistency = CommandConsistency::Projected;
+
+    fn payload(&self) -> &T {
+        &self.payload
+    }
+
+    fn __finalize_committed(payload: T) -> Self {
+        Self::from_committed_payload(payload)
+    }
+
+    fn __projected_model() -> Option<(TypeId, &'static TableSchema)> {
+        Some((TypeId::of::<T>(), T::schema()))
+    }
+}
+
+macro_rules! crate_committed_constructor {
+    ($wrapper:ident) => {
+        impl<T> $wrapper<T> {
+            /// The ledger-aware committer is the only intended caller.
+            pub(crate) fn from_committed_payload(payload: T) -> Self {
+                Self { payload }
+            }
+        }
+    };
+}
+
+crate_committed_constructor!(Accepted);
+crate_committed_constructor!(Fact);
+
+impl<T> Projected<T>
+where
+    T: RelationalReadModel,
+{
+    /// Created only after a proof-bearing staged projection commits.
+    fn from_committed_payload(payload: T) -> Self {
+        Self { payload }
+    }
+}
+
+impl<T> sealed::PreparableOutcome for Accepted<T> {}
+impl<T> sealed::PreparableOutcome for Fact<T> {}
+
+/// Sealed type-level contract implemented by committed command outcomes.
+pub trait CommandOutcome: sealed::Outcome + Send + Sync + 'static {
+    type Payload: GraphqlOutputType + Serialize + Send + Sync + 'static;
+    const CONSISTENCY: CommandConsistency;
+
+    fn payload(&self) -> &Self::Payload;
+
+    #[doc(hidden)]
+    fn __finalize_committed(payload: Self::Payload) -> Self;
+
+    /// Compiler-only model identity retained by an ordinary
+    /// `typed_command::<I, Projected<M>>` declaration. The sealed default keeps
+    /// accepted/fact outcomes unbound while `Projected<M>` supplies its exact
+    /// relational schema without an application-facing projection target API.
+    #[doc(hidden)]
+    fn __projected_model() -> Option<(TypeId, &'static TableSchema)> {
+        None
+    }
+}
+
+/// Error produced while serializing a completion before commit I/O.
+#[derive(Debug)]
+pub enum PrepareCommandError {
+    Serialize(serde_json::Error),
+}
+
+impl std::fmt::Display for PrepareCommandError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Serialize(error) => {
+                write!(formatter, "command payload serialization failed: {error}")
+            }
+        }
+    }
+}
+
+impl std::error::Error for PrepareCommandError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Serialize(error) => Some(error),
+        }
+    }
+}
+
+impl From<serde_json::Error> for PrepareCommandError {
+    fn from(error: serde_json::Error) -> Self {
+        Self::Serialize(error)
+    }
+}
+
+/// A serialized command completion waiting for the atomic command committer.
+///
+/// Preparing is deliberately separate from returning a committed outcome: it
+/// proves serialization before transaction I/O while keeping both the durable
+/// outcome and the declaration-owned confirmation plan outside application
+/// handler control.
+pub struct PreparedCommand<K: CommandOutcome> {
+    payload: K::Payload,
+    serialized_payload: serde_json::Value,
+    projection_proof: Option<ProjectionCommitProof>,
+    _outcome: PhantomData<fn() -> K>,
+}
+
+impl<K: CommandOutcome> PreparedCommand<K> {
+    fn prepare_payload(payload: K::Payload) -> Result<Self, PrepareCommandError> {
+        let serialized_payload = serde_json::to_value(&payload)?;
+        Ok(Self {
+            payload,
+            serialized_payload,
+            projection_proof: None,
+            _outcome: PhantomData,
+        })
+    }
+
+    pub fn consistency(&self) -> CommandConsistency {
+        K::CONSISTENCY
+    }
+
+    pub fn serialized_payload(&self) -> &serde_json::Value {
+        &self.serialized_payload
+    }
+
+    /// Validate declaration-owned completion obligations against exactly what
+    /// the handler staged. This runs before any commit I/O.
+    pub(crate) fn validate_commit_evidence(
+        &self,
+        contract: &TypedCommandContract,
+        has_staged_aggregate_events: bool,
+        outbox_messages: &[OutboxMessage],
+        read_model_plans: &[TableWritePlan],
+    ) -> Result<(), CommandCommitProofError> {
+        if contract.consistency != K::CONSISTENCY {
+            return Err(CommandCommitProofError::ConsistencyMismatch {
+                declared: contract.consistency,
+                prepared: K::CONSISTENCY,
+            });
+        }
+        if contract.output_type_id != TypeId::of::<K::Payload>() {
+            return Err(CommandCommitProofError::OutputTypeMismatch);
+        }
+
+        match K::CONSISTENCY {
+            CommandConsistency::Accepted | CommandConsistency::Fact => {
+                if self.projection_proof.is_some() {
+                    return Err(CommandCommitProofError::UnexpectedProjectionProof);
+                }
+                contract.validate_outbox_fact_coverage(outbox_messages)
+            }
+            CommandConsistency::Projected => {
+                if !has_staged_aggregate_events && outbox_messages.is_empty() {
+                    return Err(CommandCommitProofError::DurableFactMissing);
+                }
+                if !contract.confirmations.is_empty() {
+                    return Err(CommandCommitProofError::ProjectedHasConfirmations);
+                }
+                self.projection_proof
+                    .as_ref()
+                    .ok_or(CommandCommitProofError::MissingProjectionProof)?
+                    .validate(contract.output_type_id, read_model_plans)
+            }
+        }
+    }
+
+    /// The durable committer is the sole intended consumer.
+    pub(crate) fn finalize_after_commit(self) -> (K, serde_json::Value) {
+        (
+            K::__finalize_committed(self.payload),
+            self.serialized_payload,
+        )
+    }
+
+    /// Remove the proof-matched projected upsert from ordinary table plans and
+    /// seal it as the repository's causal direct-projection participant.
+    ///
+    /// Accepted and Fact commands return no participant. A Projected command
+    /// must have exactly one resolved declaration-owned target; the extracted
+    /// mutation is never also submitted through the legacy/raw plan path.
+    pub(crate) fn seal_direct_projection(
+        &self,
+        target: Option<ResolvedDirectProjectionTarget>,
+        read_model_plans: &mut Vec<TableWritePlan>,
+        causation_id: &str,
+    ) -> Result<Option<SameTransactionProjectionBatch>, CommandCommitProofError> {
+        match K::CONSISTENCY {
+            CommandConsistency::Accepted | CommandConsistency::Fact => {
+                if target.is_some() {
+                    return Err(CommandCommitProofError::UnexpectedDirectProjectionTarget);
+                }
+                Ok(None)
+            }
+            CommandConsistency::Projected => {
+                let target =
+                    target.ok_or(CommandCommitProofError::MissingDirectProjectionTarget)?;
+                let proof = self
+                    .projection_proof
+                    .as_ref()
+                    .ok_or(CommandCommitProofError::MissingProjectionProof)?;
+                let mutation =
+                    proof.extract_exact_upsert(TypeId::of::<K::Payload>(), read_model_plans)?;
+                target
+                    .seal(mutation, causation_id)
+                    .map(Some)
+                    .map_err(|error| CommandCommitProofError::DirectProjection(error.to_string()))
+            }
+        }
+    }
+}
+
+impl<M> PreparedCommand<Projected<M>>
+where
+    M: GraphqlOutputType + RelationalReadModel + Serialize + Send + Sync + 'static,
+{
+    /// Build a projected completion from the exact model value whose full-row
+    /// upsert was staged by the framework-owned causal workspace.
+    pub(crate) fn prepare_projected(
+        payload: M,
+        proof: ProjectionCommitProof,
+    ) -> Result<Self, PrepareCommandError> {
+        let serialized_payload = serde_json::to_value(&payload)?;
+        Ok(Self {
+            payload,
+            serialized_payload,
+            projection_proof: Some(proof),
+            _outcome: PhantomData,
+        })
+    }
+}
+
+impl<K> PreparedCommand<K>
+where
+    K: CommandOutcome + sealed::PreparableOutcome,
+{
+    /// Prepare an accepted or fact payload for the durable committer.
+    /// Projected results require a staged transactional proof and do
+    /// not implement the private preparation capability.
+    pub fn prepare(payload: K::Payload) -> Result<Self, PrepareCommandError> {
+        Self::prepare_payload(payload)
+    }
+}
diff --git a/src/graphql/command_contract/projection_obligations.rs b/src/graphql/command_contract/projection_obligations.rs
new file mode 100644
index 00000000..f05529c5
--- /dev/null
+++ b/src/graphql/command_contract/projection_obligations.rs
@@ -0,0 +1,225 @@
+use serde::{Deserialize, Serialize};
+
+use super::effects::{EffectExpression, EffectKey};
+use super::projection_proof::canonical_json;
+use crate::projection_protocol::{ProjectionPartitionSpec, ProjectorTopologyId};
+use crate::table::TableSchema;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum InputDefaultGenerator {
+    UuidV7,
+    Ulid,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct CommandInputDefault {
+    pub path: Vec<String>,
+    pub generator: InputDefaultGenerator,
+}
+
+/// One declaration-owned projector/model/key confirmation target.
+///
+/// The dispatcher resolves these expressions from the retained canonical
+/// GraphQL wire input before commit I/O, then commits the finite obligations
+/// atomically with the command ledger/fact. Handlers cannot add, remove, or
+/// rewrite targets.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub(crate) struct CommandProjectionConfirmation {
+    pub projector: String,
+    pub model: String,
+    pub key: EffectKey,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub partition: Option<EffectExpression>,
+    /// Frozen declaration identity used for server-side topology validation
+    /// and typed service binding. It is intentionally absent from role client
+    /// manifests, whose projector catalog already carries authorized topology.
+    #[serde(skip_serializing)]
+    pub(super) projector_topology: ProjectorTopologyIdentity,
+    /// Exact server-side topology identity compiled from accepted facts, the
+    /// versioned scope codec, and every complete owned table schema. Typed
+    /// declarations start unbound; Surface/engine compilation must attach this
+    /// before an obligation can be lowered or committed.
+    #[serde(skip_serializing)]
+    pub(super) protocol_topology: Option<ProjectorTopologyId>,
+    #[serde(skip_serializing)]
+    pub(super) schema: Option<&'static TableSchema>,
+}
+
+/// Why a declaration-owned projection obligation could not be resolved before
+/// commit I/O.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) enum ProjectionObligationResolutionError {
+    MissingInputPath {
+        projector: String,
+        model: String,
+        target: String,
+        path: Vec<String>,
+    },
+    TrustedPresetUnavailable {
+        projector: String,
+        model: String,
+        target: String,
+        preset: String,
+    },
+    InvalidConstant {
+        projector: String,
+        model: String,
+        target: String,
+        error: String,
+    },
+    InvalidBinding {
+        projector: String,
+        model: String,
+        reason: String,
+    },
+}
+
+impl std::fmt::Display for ProjectionObligationResolutionError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::MissingInputPath {
+                projector,
+                model,
+                target,
+                path,
+            } => write!(
+                formatter,
+                "projection obligation `{projector}`/`{model}` {target} references absent canonical input path `{}`",
+                path.join("."),
+            ),
+            Self::TrustedPresetUnavailable {
+                projector,
+                model,
+                target,
+                preset,
+            } => write!(
+                formatter,
+                "projection obligation `{projector}`/`{model}` {target} uses unavailable trusted preset `{preset}`",
+            ),
+            Self::InvalidConstant {
+                projector,
+                model,
+                target,
+                error,
+            } => write!(
+                formatter,
+                "projection obligation `{projector}`/`{model}` {target} contains an invalid constant: {error}",
+            ),
+            Self::InvalidBinding {
+                projector,
+                model,
+                reason,
+            } => write!(
+                formatter,
+                "projection obligation `{projector}`/`{model}` is not bound to an exact topology: {reason}",
+            ),
+        }
+    }
+}
+
+impl std::error::Error for ProjectionObligationResolutionError {}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct ProjectorTopologyIdentity {
+    name: String,
+    pub(super) facts: Vec<String>,
+    models: Vec<String>,
+    partition: ProjectionPartitionSpec,
+}
+
+impl ProjectorTopologyIdentity {
+    pub(super) fn new(
+        name: &str,
+        facts: &[String],
+        models: &[String],
+        partition: &ProjectionPartitionSpec,
+    ) -> Self {
+        let mut facts = facts.to_vec();
+        facts.sort();
+        facts.dedup();
+        let mut models = models.to_vec();
+        models.sort();
+        models.dedup();
+        Self {
+            name: name.to_string(),
+            facts,
+            models,
+            partition: partition.clone(),
+        }
+    }
+
+    pub(super) fn canonical_value(&self) -> serde_json::Value {
+        canonical_json(&serde_json::json!({
+            "name": self.name,
+            "facts": self.facts,
+            "models": self.models,
+            "partition": self.partition,
+        }))
+    }
+}
+
+impl CommandProjectionConfirmation {
+    pub(crate) fn canonical_value(&self) -> serde_json::Value {
+        canonical_json(&serde_json::json!({
+            "projector": self.projector,
+            "projector_topology": self.projector_topology.canonical_value(),
+            "protocol_topology": self.protocol_topology.as_ref().map(|topology| serde_json::json!({
+                "version": topology.version(),
+                "name": topology.name(),
+                "digest": topology.digest(),
+            })),
+            "model": self.model,
+            "key": self.key,
+            "partition": self.partition,
+        }))
+    }
+
+    pub(crate) fn topology_matches(
+        &self,
+        name: &str,
+        facts: &[String],
+        models: &[String],
+        partition: &ProjectionPartitionSpec,
+    ) -> bool {
+        self.projector_topology == ProjectorTopologyIdentity::new(name, facts, models, partition)
+    }
+
+    pub(crate) fn bind_protocol_topology(&mut self, topology: ProjectorTopologyId) {
+        self.protocol_topology = Some(topology);
+    }
+
+    pub(crate) fn protocol_topology(&self) -> Option<&ProjectorTopologyId> {
+        self.protocol_topology.as_ref()
+    }
+
+    pub(crate) fn clear_protocol_topology(&mut self) {
+        self.protocol_topology = None;
+    }
+
+    pub(crate) fn partition_matches(&self, partition: &ProjectionPartitionSpec) -> bool {
+        match partition {
+            ProjectionPartitionSpec::Unit => self.partition.is_none(),
+            ProjectionPartitionSpec::Constant { value } => {
+                self.partition
+                    == Some(EffectExpression::Constant {
+                        value: value.clone(),
+                    })
+            }
+            ProjectionPartitionSpec::InputPath { .. } => self.partition.is_some(),
+        }
+    }
+}
+
+pub(crate) fn validate_projection_confirmation_count(
+    command_name: &str,
+    count: usize,
+) -> Result<(), String> {
+    if count > crate::projection_protocol::MAX_PROJECTION_EVIDENCE_BATCH_ITEMS {
+        return Err(format!(
+            "typed command `{command_name}` declares {count} projector confirmations; maximum is {}",
+            crate::projection_protocol::MAX_PROJECTION_EVIDENCE_BATCH_ITEMS
+        ));
+    }
+    Ok(())
+}
diff --git a/src/graphql/command_contract/projection_proof.rs b/src/graphql/command_contract/projection_proof.rs
new file mode 100644
index 00000000..83c63b2d
--- /dev/null
+++ b/src/graphql/command_contract/projection_proof.rs
@@ -0,0 +1,275 @@
+use std::any::TypeId;
+
+use sha2::{Digest, Sha256};
+
+use super::outcomes::CommandConsistency;
+use crate::read_model::RelationalReadModel;
+use crate::table::{
+    RowKey, RowValue, RowValues, RowWriteMode, TableMutation, TableStoreError, TableWritePlan,
+};
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) enum CommandCommitProofError {
+    ConsistencyMismatch {
+        declared: CommandConsistency,
+        prepared: CommandConsistency,
+    },
+    OutputTypeMismatch,
+    DurableFactMissing,
+    FactHasNoConfirmations,
+    UnreachableConfirmation {
+        projector: String,
+        expected_facts: Vec<String>,
+        staged_facts: Vec<String>,
+    },
+    UnexpectedProjectionProof,
+    MissingProjectionProof,
+    ProjectedHasConfirmations,
+    ProjectionOutputTypeMismatch,
+    ProjectionWriteMissing {
+        model: String,
+    },
+    ProjectionWriteConflict {
+        model: String,
+    },
+    ProjectionWriteMismatch {
+        model: String,
+    },
+    MissingDirectProjectionTarget,
+    UnexpectedDirectProjectionTarget,
+    DirectProjection(String),
+}
+
+impl std::fmt::Display for CommandCommitProofError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::ConsistencyMismatch { declared, prepared } => write!(
+                formatter,
+                "prepared command consistency {prepared:?} does not match declaration {declared:?}"
+            ),
+            Self::OutputTypeMismatch => {
+                formatter.write_str("prepared command output type does not match its declaration")
+            }
+            Self::DurableFactMissing => formatter.write_str(
+                "fact and projected commands require a staged aggregate event or outbox fact",
+            ),
+            Self::FactHasNoConfirmations => formatter.write_str(
+                "a fact command requires at least one finite projector confirmation",
+            ),
+            Self::UnreachableConfirmation {
+                projector,
+                expected_facts,
+                staged_facts,
+            } => write!(
+                formatter,
+                "projector `{projector}` cannot be reached: expected one of {expected_facts:?}, staged outbox facts were {staged_facts:?}"
+            ),
+            Self::UnexpectedProjectionProof => formatter.write_str(
+                "accepted and fact commands cannot carry a same-transaction projection proof",
+            ),
+            Self::MissingProjectionProof => formatter.write_str(
+                "projected command did not stage its returned read model as an exact upsert",
+            ),
+            Self::ProjectedHasConfirmations => formatter.write_str(
+                "projected command cannot declare asynchronous projector confirmations",
+            ),
+            Self::ProjectionOutputTypeMismatch => formatter.write_str(
+                "projected command proof is for a different Rust read-model type",
+            ),
+            Self::ProjectionWriteMissing { model } => write!(
+                formatter,
+                "projected command did not stage an upsert for returned model `{model}`"
+            ),
+            Self::ProjectionWriteConflict { model } => write!(
+                formatter,
+                "projected command staged more than one mutation for returned model `{model}` and key"
+            ),
+            Self::ProjectionWriteMismatch { model } => write!(
+                formatter,
+                "projected command staged a row that differs from returned model `{model}`"
+            ),
+            Self::MissingDirectProjectionTarget => formatter.write_str(
+                "projected command has no declaration-owned direct projection target",
+            ),
+            Self::UnexpectedDirectProjectionTarget => formatter.write_str(
+                "accepted and fact commands cannot carry a direct projection target",
+            ),
+            Self::DirectProjection(error) => {
+                write!(formatter, "direct projection target could not be sealed: {error}")
+            }
+        }
+    }
+}
+
+impl std::error::Error for CommandCommitProofError {}
+
+/// Private evidence tying a `Projected<M>` payload to one exact full-row
+/// upsert. Application handlers can obtain this only through the causal
+/// workspace's stage-and-prepare operation.
+pub(crate) struct ProjectionCommitProof {
+    model_type_id: TypeId,
+    model_name: String,
+    table_name: String,
+    key_fingerprint: String,
+    row_fingerprint: String,
+}
+
+impl ProjectionCommitProof {
+    pub(crate) fn for_model<M>(model: &M) -> Result<Self, TableStoreError>
+    where
+        M: RelationalReadModel + 'static,
+    {
+        let schema = M::schema();
+        schema.validate()?;
+        let key = model.primary_key()?;
+        let row = model.to_row()?;
+        Ok(Self {
+            model_type_id: TypeId::of::<M>(),
+            model_name: schema.model_name.clone(),
+            table_name: schema.table_name.clone(),
+            key_fingerprint: fingerprint_key(&key),
+            row_fingerprint: fingerprint_row(&row),
+        })
+    }
+
+    pub(super) fn validate(
+        &self,
+        output_type_id: TypeId,
+        plans: &[TableWritePlan],
+    ) -> Result<(), CommandCommitProofError> {
+        if self.model_type_id != output_type_id {
+            return Err(CommandCommitProofError::ProjectionOutputTypeMismatch);
+        }
+
+        let mut target_count = 0usize;
+        let mut exact_match = false;
+        for mutation in plans.iter().flat_map(|plan| &plan.mutations) {
+            let (schema, key) = match mutation {
+                TableMutation::UpsertRow(mutation) => (mutation.schema, &mutation.key),
+                TableMutation::PatchRow(mutation) => (mutation.schema, &mutation.key),
+                TableMutation::DeleteRow(mutation) => (mutation.schema, &mutation.key),
+            };
+            if schema.table_name != self.table_name || fingerprint_key(key) != self.key_fingerprint
+            {
+                continue;
+            }
+
+            target_count += 1;
+            if let TableMutation::UpsertRow(mutation) = mutation {
+                exact_match = mutation.mode == RowWriteMode::Upsert
+                    && mutation.schema.model_name == self.model_name
+                    && fingerprint_row(&mutation.values) == self.row_fingerprint;
+            }
+        }
+
+        match target_count {
+            0 => Err(CommandCommitProofError::ProjectionWriteMissing {
+                model: self.model_name.clone(),
+            }),
+            1 if exact_match => Ok(()),
+            1 => Err(CommandCommitProofError::ProjectionWriteMismatch {
+                model: self.model_name.clone(),
+            }),
+            _ => Err(CommandCommitProofError::ProjectionWriteConflict {
+                model: self.model_name.clone(),
+            }),
+        }
+    }
+
+    pub(super) fn extract_exact_upsert(
+        &self,
+        output_type_id: TypeId,
+        plans: &mut Vec<TableWritePlan>,
+    ) -> Result<TableMutation, CommandCommitProofError> {
+        self.validate(output_type_id, plans)?;
+
+        let mut found = None;
+        for (plan_index, plan) in plans.iter().enumerate() {
+            for (mutation_index, mutation) in plan.mutations.iter().enumerate() {
+                let TableMutation::UpsertRow(row) = mutation else {
+                    continue;
+                };
+                if row.schema.table_name == self.table_name
+                    && row.schema.model_name == self.model_name
+                    && fingerprint_key(&row.key) == self.key_fingerprint
+                    && row.mode == RowWriteMode::Upsert
+                    && fingerprint_row(&row.values) == self.row_fingerprint
+                {
+                    found = Some((plan_index, mutation_index));
+                }
+            }
+        }
+        let (plan_index, mutation_index) =
+            found.ok_or_else(|| CommandCommitProofError::ProjectionWriteMissing {
+                model: self.model_name.clone(),
+            })?;
+        let mutation = plans[plan_index].mutations.remove(mutation_index);
+        if plans[plan_index].mutations.is_empty() {
+            plans.remove(plan_index);
+        } else {
+            plans[plan_index].validate().map_err(|_| {
+                CommandCommitProofError::ProjectionWriteConflict {
+                    model: self.model_name.clone(),
+                }
+            })?;
+        }
+        Ok(mutation)
+    }
+}
+
+pub(super) fn fingerprint_key(key: &RowKey) -> String {
+    fingerprint_values("distributed.command-projection-key.v1", key.iter())
+}
+
+fn fingerprint_row(row: &RowValues) -> String {
+    fingerprint_values("distributed.command-projection-row.v1", row.iter())
+}
+
+fn fingerprint_values<'a>(
+    domain: &str,
+    values: impl Iterator<Item = (&'a str, &'a RowValue)>,
+) -> String {
+    let canonical = values
+        .map(|(column, value)| serde_json::json!([column, canonical_row_value(value)]))
+        .collect::<Vec<_>>();
+    let mut digest = Sha256::new();
+    digest.update(domain.as_bytes());
+    digest.update([0]);
+    digest.update(
+        serde_json::to_vec(&canonical)
+            .expect("canonical row projection fingerprint serialization cannot fail"),
+    );
+    format!("sha256:{:x}", digest.finalize())
+}
+
+fn canonical_row_value(value: &RowValue) -> serde_json::Value {
+    match value {
+        RowValue::Null => serde_json::json!(["null"]),
+        RowValue::Bool(value) => serde_json::json!(["bool", value]),
+        RowValue::I64(value) => serde_json::json!(["i64", value.to_string()]),
+        RowValue::U64(value) => serde_json::json!(["u64", value.to_string()]),
+        RowValue::F64(value) => serde_json::json!(["f64_bits", value.to_bits().to_string()]),
+        RowValue::String(value) => serde_json::json!(["string", value]),
+        RowValue::Bytes(value) => serde_json::json!(["bytes", value]),
+        RowValue::Json(value) => serde_json::json!(["json", canonical_json(value)]),
+    }
+}
+
+pub(super) fn canonical_json(value: &serde_json::Value) -> serde_json::Value {
+    match value {
+        serde_json::Value::Array(values) => {
+            serde_json::Value::Array(values.iter().map(canonical_json).collect())
+        }
+        serde_json::Value::Object(values) => {
+            let mut entries = values.iter().collect::<Vec<_>>();
+            entries.sort_by(|left, right| left.0.cmp(right.0));
+            serde_json::Value::Object(
+                entries
+                    .into_iter()
+                    .map(|(key, value)| (key.clone(), canonical_json(value)))
+                    .collect(),
+            )
+        }
+        scalar => scalar.clone(),
+    }
+}
diff --git a/src/graphql/command_contract/tests.rs b/src/graphql/command_contract/tests.rs
new file mode 100644
index 00000000..5336919f
--- /dev/null
+++ b/src/graphql/command_contract/tests.rs
@@ -0,0 +1,554 @@
+use super::*;
+use crate::graphql::{GraphqlInputType, GraphqlOutputType, GraphqlTypeDef, GraphqlTypeField};
+use crate::microsvc::Session;
+use crate::outbox::OutboxMessage;
+use crate::projection_protocol::{
+    ProjectionPartitionSpec, ProjectorTopologyId, ResolvedProjectionObligation,
+};
+use crate::table::{ColumnType, PrimaryKey, TableColumn, TableKind, TableSchema};
+use serde::{Deserialize, Serialize};
+use std::any::TypeId;
+
+#[allow(dead_code)]
+#[derive(Deserialize)]
+struct Input {
+    id: String,
+}
+
+impl GraphqlInputType for Input {
+    fn graphql_type() -> GraphqlTypeDef {
+        GraphqlTypeDef::new(
+            "Input",
+            vec![GraphqlTypeField {
+                name: "id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            }],
+        )
+        .with_type_id(TypeId::of::<Self>())
+    }
+}
+
+#[derive(Serialize)]
+struct Payload {
+    id: String,
+}
+
+impl GraphqlOutputType for Payload {
+    fn graphql_type() -> GraphqlTypeDef {
+        GraphqlTypeDef::new(
+            "Payload",
+            vec![GraphqlTypeField {
+                name: "id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            }],
+        )
+        .with_type_id(TypeId::of::<Self>())
+    }
+}
+
+#[test]
+fn preparation_serializes_and_retains_the_typed_payload_until_commit() {
+    let prepared = PreparedCommand::<Fact<Payload>>::prepare(Payload {
+        id: "todo-1".into(),
+    })
+    .unwrap();
+    assert_eq!(prepared.consistency(), CommandConsistency::Fact);
+    assert_eq!(prepared.serialized_payload()["id"], "todo-1");
+    let (committed, serialized) = prepared.finalize_after_commit();
+    assert_eq!(committed.payload().id, "todo-1");
+    assert_eq!(serialized["id"], "todo-1");
+}
+
+fn confirmation_with_facts(facts: &[&str]) -> CommandProjectionConfirmation {
+    CommandProjectionConfirmation {
+        projector: "project_todos".into(),
+        model: "TodoView".into(),
+        key: EffectKey { fields: Vec::new() },
+        partition: None,
+        projector_topology: ProjectorTopologyIdentity::new(
+            "project_todos",
+            &facts
+                .iter()
+                .map(|fact| (*fact).to_string())
+                .collect::<Vec<_>>(),
+            &["TodoView".into()],
+            &ProjectionPartitionSpec::unit(),
+        ),
+        protocol_topology: None,
+        schema: None,
+    }
+}
+
+#[test]
+fn confirmation_inventory_matches_the_bounded_status_batch() {
+    let maximum = crate::projection_protocol::MAX_PROJECTION_EVIDENCE_BATCH_ITEMS;
+    validate_projection_confirmation_count("todo.update", maximum)
+        .expect("the adapter's exact maximum must be accepted");
+    let error = validate_projection_confirmation_count("todo.update", maximum + 1)
+        .expect_err("one more confirmation must fail before service traffic");
+    assert!(error.contains(&format!("maximum is {maximum}")), "{error}");
+}
+
+fn confirmation_with_key(
+    projector: &str,
+    fields: impl IntoIterator<Item = (&'static str, EffectExpression)>,
+    partition: Option<EffectExpression>,
+) -> CommandProjectionConfirmation {
+    let fields = fields
+        .into_iter()
+        .map(|(field, value)| EffectFieldValue {
+            field: field.into(),
+            value,
+        })
+        .collect::<Vec<_>>();
+    let columns = fields
+        .iter()
+        .map(|field| TableColumn {
+            primary_key: true,
+            ..TableColumn::new(&field.field, &field.field, ColumnType::Json)
+        })
+        .collect::<Vec<_>>();
+    let primary_key = fields.iter().map(|field| field.field.as_str());
+    let schema = Box::leak(Box::new(TableSchema {
+        model_name: "TodoView".into(),
+        table_name: "todo_views".into(),
+        columns,
+        primary_key: PrimaryKey::new(primary_key),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    }));
+    CommandProjectionConfirmation {
+        projector: projector.into(),
+        model: "TodoView".into(),
+        key: EffectKey { fields },
+        partition,
+        projector_topology: ProjectorTopologyIdentity::new(
+            projector,
+            &["todo.changed".into()],
+            &["TodoView".into()],
+            &ProjectionPartitionSpec::unit(),
+        ),
+        protocol_topology: Some(ProjectorTopologyId::new(1, projector, [3; 32]).unwrap()),
+        schema: Some(schema),
+    }
+}
+
+#[test]
+fn projection_obligations_resolve_nested_canonical_wire_paths_in_declaration_order() {
+    let mut contract = typed_command::<Input, Accepted<Payload>>("todo.update").into_contract();
+    contract.confirmations = vec![
+        confirmation_with_key(
+            "project_second",
+            [
+                (
+                    "tenant_id",
+                    EffectExpression::Input {
+                        path: vec!["scope".into(), "tenantId".into()],
+                    },
+                ),
+                (
+                    "id",
+                    EffectExpression::Input {
+                        path: vec!["todoId".into()],
+                    },
+                ),
+            ],
+            Some(EffectExpression::Input {
+                path: vec!["scope".into(), "tenantId".into()],
+            }),
+        ),
+        confirmation_with_key(
+            "project_first",
+            [(
+                "id",
+                EffectExpression::Input {
+                    path: vec!["todoId".into()],
+                },
+            )],
+            None,
+        ),
+    ];
+    let canonical_wire = serde_json::json!({
+        "scope": { "tenantId": "tenant-7" },
+        "todoId": "todo-1"
+    });
+
+    let resolved = contract
+        .resolve_projection_obligations(&canonical_wire)
+        .unwrap();
+
+    assert_eq!(
+        resolved
+            .iter()
+            .map(|obligation| obligation.projector.as_str())
+            .collect::<Vec<_>>(),
+        ["project_second", "project_first"]
+    );
+    assert_eq!(
+        resolved[0]
+            .key
+            .fields
+            .iter()
+            .map(|field| field.field.as_str())
+            .collect::<Vec<_>>(),
+        ["tenant_id", "id"]
+    );
+    assert_eq!(resolved[0].key.fields[0].value, "tenant-7");
+    assert_eq!(resolved[0].key.fields[1].value, "todo-1");
+    assert_eq!(resolved[0].partition, Some(serde_json::json!("tenant-7")));
+    assert_eq!(resolved[1].key.fields[0].value, "todo-1");
+    assert_eq!(resolved[1].partition, None);
+}
+
+#[test]
+fn projection_obligations_preserve_constants_and_nulls_through_serde() {
+    let mut contract = typed_command::<Input, Accepted<Payload>>("todo.update").into_contract();
+    let constant = serde_json::json!({
+        "nested": [1, "two", null],
+        "large": u64::MAX,
+    });
+    contract.confirmations = vec![confirmation_with_key(
+        "project_todos",
+        [(
+            "constant_key",
+            EffectExpression::Constant {
+                value: constant.clone(),
+            },
+        )],
+        Some(EffectExpression::Null),
+    )];
+
+    let resolved = contract
+        .resolve_projection_obligations(&serde_json::json!({}))
+        .unwrap();
+
+    assert_eq!(resolved[0].key.fields[0].value, constant);
+    assert_eq!(resolved[0].partition, Some(serde_json::Value::Null));
+
+    let encoded = serde_json::to_value(&resolved).unwrap();
+    assert!(encoded[0]["partition"].is_null());
+    let decoded: Vec<ResolvedProjectionObligation> = serde_json::from_value(encoded).unwrap();
+    assert_eq!(decoded, resolved);
+}
+
+#[test]
+fn projection_obligation_resolution_fails_on_absent_input_paths() {
+    let mut contract = typed_command::<Input, Accepted<Payload>>("todo.update").into_contract();
+    contract.confirmations = vec![confirmation_with_key(
+        "project_todos",
+        [(
+            "tenant_id",
+            EffectExpression::Input {
+                path: vec!["scope".into(), "tenantId".into()],
+            },
+        )],
+        None,
+    )];
+
+    let error = contract
+        .resolve_projection_obligations(&serde_json::json!({ "scope": null }))
+        .unwrap_err();
+
+    assert!(matches!(
+        error,
+        ProjectionObligationResolutionError::MissingInputPath { path, .. }
+            if path == ["scope", "tenantId"]
+    ));
+}
+
+#[test]
+fn projection_obligation_resolution_rejects_unresolved_private_expressions() {
+    let mut contract = typed_command::<Input, Accepted<Payload>>("todo.update").into_contract();
+    contract.confirmations = vec![confirmation_with_key(
+        "project_todos",
+        [(
+            "tenant_id",
+            EffectExpression::TrustedPreset {
+                name: "tenant".into(),
+            },
+        )],
+        None,
+    )];
+    assert!(matches!(
+        contract.resolve_projection_obligations(&serde_json::json!({})),
+        Err(ProjectionObligationResolutionError::TrustedPresetUnavailable {
+            preset,
+            ..
+        }) if preset == "tenant"
+    ));
+    let mut session = Session::new();
+    session.set("tenant", "\"tenant-7\"");
+    let resolved = contract
+        .resolve_projection_obligations_from_session(&serde_json::json!({}), Some(&session))
+        .expect("server Session resolves the declared JSON-typed preset");
+    assert_eq!(resolved[0].key.fields[0].value, "tenant-7");
+    session.set("tenant", "not-json");
+    assert!(matches!(
+        contract
+            .resolve_projection_obligations_from_session(&serde_json::json!({}), Some(&session),),
+        Err(ProjectionObligationResolutionError::TrustedPresetUnavailable { .. })
+    ));
+
+    contract.confirmations = vec![confirmation_with_key(
+        "project_todos",
+        [],
+        Some(EffectExpression::InvalidConstant {
+            error: "not portable".into(),
+        }),
+    )];
+    assert!(matches!(
+        contract.resolve_projection_obligations(&serde_json::json!({})),
+        Err(ProjectionObligationResolutionError::InvalidConstant {
+            target,
+            error,
+            ..
+        }) if target == "partition" && error == "not portable"
+    ));
+}
+
+#[test]
+fn projection_obligation_resolution_is_empty_without_confirmations() {
+    let contract = typed_command::<Input, Accepted<Payload>>("todo.check").into_contract();
+
+    assert!(contract
+        .resolve_projection_obligations(&serde_json::json!("unused"))
+        .unwrap()
+        .is_empty());
+}
+
+#[test]
+fn finite_confirmation_requires_a_reachable_staged_outbox_fact() {
+    let mut contract = typed_command::<Input, Accepted<Payload>>("todo.create").into_contract();
+    contract.confirmations = vec![confirmation_with_facts(&["todo.created", "todo.recreated"])];
+    let prepared = PreparedCommand::<Accepted<Payload>>::prepare(Payload {
+        id: "todo-1".into(),
+    })
+    .unwrap();
+
+    let no_fact = prepared
+        .validate_commit_evidence(&contract, false, &[], &[])
+        .unwrap_err();
+    assert!(matches!(
+        no_fact,
+        CommandCommitProofError::UnreachableConfirmation { .. }
+    ));
+
+    let unrelated = OutboxMessage::create("message-1", "account.changed", Vec::new()).unwrap();
+    assert!(matches!(
+        prepared.validate_commit_evidence(&contract, false, &[unrelated], &[]),
+        Err(CommandCommitProofError::UnreachableConfirmation { .. })
+    ));
+
+    let reachable = OutboxMessage::create("message-2", "todo.created", Vec::new()).unwrap();
+    prepared
+        .validate_commit_evidence(&contract, false, &[reachable], &[])
+        .unwrap();
+
+    let directed =
+        OutboxMessage::create_to("message-3", "todo.created", "todo-projector", Vec::new())
+            .unwrap();
+    assert!(matches!(
+        prepared.validate_commit_evidence(&contract, false, &[directed], &[]),
+        Err(CommandCommitProofError::UnreachableConfirmation { .. })
+    ));
+
+    let mut published = OutboxMessage::create("message-4", "todo.created", Vec::new()).unwrap();
+    published.status = crate::outbox::OutboxMessageStatus::Published;
+    assert!(matches!(
+        prepared.validate_commit_evidence(&contract, false, &[published], &[]),
+        Err(CommandCommitProofError::UnreachableConfirmation { .. })
+    ));
+
+    let mut failed = OutboxMessage::create("message-5", "todo.created", Vec::new()).unwrap();
+    failed.status = crate::outbox::OutboxMessageStatus::Failed;
+    assert!(matches!(
+        prepared.validate_commit_evidence(&contract, false, &[failed], &[]),
+        Err(CommandCommitProofError::UnreachableConfirmation { .. })
+    ));
+}
+
+#[test]
+fn accepted_without_confirmations_allows_an_empty_domain_batch() {
+    let contract = typed_command::<Input, Accepted<Payload>>("todo.check").into_contract();
+    let prepared = PreparedCommand::<Accepted<Payload>>::prepare(Payload {
+        id: "todo-1".into(),
+    })
+    .unwrap();
+
+    prepared
+        .validate_commit_evidence(&contract, false, &[], &[])
+        .unwrap();
+}
+
+#[test]
+fn fact_without_a_finite_confirmation_fails_at_commit_validation() {
+    let contract = typed_command::<Input, Fact<Payload>>("todo.create").into_contract();
+    let prepared = PreparedCommand::<Fact<Payload>>::prepare(Payload {
+        id: "todo-1".into(),
+    })
+    .unwrap();
+    let fact = OutboxMessage::create("message-1", "todo.created", Vec::new()).unwrap();
+
+    assert_eq!(
+        prepared
+            .validate_commit_evidence(&contract, false, &[fact], &[])
+            .unwrap_err(),
+        CommandCommitProofError::FactHasNoConfirmations
+    );
+}
+
+#[test]
+fn per_route_fingerprint_is_stable_and_contract_sensitive() {
+    let first = typed_command::<Input, Accepted<Payload>>("todo.create")
+        .roles(["writer", "admin"])
+        .into_contract();
+    let reordered = typed_command::<Input, Accepted<Payload>>("todo.create")
+        .roles(["admin", "writer"])
+        .into_contract();
+    let renamed = typed_command::<Input, Accepted<Payload>>("todo.rename")
+        .roles(["admin", "writer"])
+        .into_contract();
+
+    assert_eq!(first.fingerprint_bytes(), reordered.fingerprint_bytes());
+    assert_ne!(first.fingerprint_bytes(), renamed.fingerprint_bytes());
+}
+
+#[test]
+fn command_fingerprints_canonicalize_nested_json_object_keys() {
+    fn contract_with_constant(order: [&str; 2]) -> TypedCommandContract {
+        let mut value = serde_json::Map::new();
+        for key in order {
+            value.insert(
+                key.into(),
+                serde_json::json!(if key == "a" { 1 } else { 2 }),
+            );
+        }
+        let mut contract = typed_command::<Input, Accepted<Payload>>("todo.update").into_contract();
+        contract.effects = CommandEffects::new([CommandEffect::Patch {
+            model: "Todo".into(),
+            key: EffectKey {
+                fields: vec![EffectFieldValue {
+                    field: "id".into(),
+                    value: EffectExpression::Input {
+                        path: vec!["id".into()],
+                    },
+                }],
+            },
+            fields: vec![EffectFieldValue {
+                field: "metadata".into(),
+                value: EffectExpression::Constant {
+                    value: serde_json::Value::Object(value),
+                },
+            }],
+        }]);
+        contract
+    }
+
+    let reverse_insertion = contract_with_constant(["z", "a"]);
+    let sorted_insertion = contract_with_constant(["a", "z"]);
+    assert_eq!(
+        reverse_insertion.fingerprint_bytes(),
+        sorted_insertion.fingerprint_bytes()
+    );
+
+    let route_fingerprint = format!(
+        "sha256:{}",
+        reverse_insertion
+            .fingerprint_bytes()
+            .iter()
+            .map(|byte| format!("{byte:02x}"))
+            .collect::<String>()
+    );
+    let reverse_binding =
+        TypedServiceCommandBinding::from_contracts("todos", &[reverse_insertion]).unwrap();
+    let sorted_binding =
+        TypedServiceCommandBinding::from_contracts("todos", &[sorted_insertion]).unwrap();
+    assert_eq!(
+        reverse_binding.structural_fingerprint,
+        sorted_binding.structural_fingerprint
+    );
+    assert_eq!(
+        (
+            route_fingerprint.as_str(),
+            reverse_binding.structural_fingerprint.as_str(),
+        ),
+        (
+            "sha256:1414f9c1c33dc256953744dc606d4d15879577c52fa2bbbe1fa24ad0103433e3",
+            "sha256:f40799bf6540528956fc50722ef607ed731d0707b8ebe0c169ef55bc2805d456",
+        )
+    );
+}
+
+#[test]
+fn binding_rejects_missing_graphql_type_ids() {
+    let mut contract = typed_command::<Input, Accepted<Payload>>("todo.create").into_contract();
+    contract.input.type_id = None;
+    let error = TypedServiceCommandBinding::from_contracts("todos", &[contract]).unwrap_err();
+    assert!(error.contains("input GraphQL metadata is missing"));
+}
+
+#[test]
+fn binding_canonicalizes_fields_and_roles_but_preserves_effect_order() {
+    let mut first = typed_command::<Input, Accepted<Payload>>("todo.create")
+        .roles(["writer", "admin"])
+        .into_contract();
+    first.input.fields.push(GraphqlTypeField {
+        name: "z_extra".into(),
+        type_name: "String".into(),
+        nullable: true,
+        list: false,
+        item_nullable: false,
+        nested: None,
+    });
+    first.effects.operations = vec![
+        CommandEffect::InvalidateModel {
+            model: "Zed".into(),
+        },
+        CommandEffect::InvalidateModel {
+            model: "Alpha".into(),
+        },
+    ];
+
+    let mut second = first.clone();
+    second.roles.reverse();
+    second.input.fields.reverse();
+    let first = TypedServiceCommandBinding::from_contracts("todos", &[first]).unwrap();
+    let second = TypedServiceCommandBinding::from_contracts("todos", &[second]).unwrap();
+    assert_eq!(first, second);
+
+    let mut reordered = typed_command::<Input, Accepted<Payload>>("todo.create")
+        .roles(["writer", "admin"])
+        .into_contract();
+    reordered.input.fields.push(GraphqlTypeField {
+        name: "z_extra".into(),
+        type_name: "String".into(),
+        nullable: true,
+        list: false,
+        item_nullable: false,
+        nested: None,
+    });
+    reordered.effects.operations = vec![
+        CommandEffect::InvalidateModel {
+            model: "Alpha".into(),
+        },
+        CommandEffect::InvalidateModel {
+            model: "Zed".into(),
+        },
+    ];
+    let reordered = TypedServiceCommandBinding::from_contracts("todos", &[reordered]).unwrap();
+    assert_ne!(
+        first.structural_fingerprint,
+        reordered.structural_fingerprint
+    );
+}
diff --git a/src/graphql/command_contract/typed_command.rs b/src/graphql/command_contract/typed_command.rs
new file mode 100644
index 00000000..bd63f877
--- /dev/null
+++ b/src/graphql/command_contract/typed_command.rs
@@ -0,0 +1,660 @@
+use std::any::TypeId;
+use std::collections::{BTreeMap, BTreeSet};
+use std::marker::PhantomData;
+
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+use sha2::{Digest, Sha256};
+
+use super::direct_projection::{
+    resolve_trusted_preset, CommandDirectProjectionTarget, CommandProjectedModel,
+    CompiledDirectProjectionTarget, DirectProjectionTargetResolutionError,
+    ResolvedDirectProjectionTarget,
+};
+use super::effect_wire::{CompiledCommandEffects, CompiledConfirmationPlan, CompiledInputDefaults};
+use super::effects::{
+    invalid_confirmation_constant, invalid_expression_constant, CommandEffects, EffectExpression,
+};
+use super::outcomes::{CommandConsistency, CommandOutcome, Projected};
+use super::projection_obligations::{
+    CommandInputDefault, CommandProjectionConfirmation, ProjectionObligationResolutionError,
+};
+use super::projection_proof::{canonical_json, CommandCommitProofError};
+use crate::graphql::naming;
+use crate::graphql::types::{GraphqlInputType, GraphqlOutputType, GraphqlTypeDef};
+use crate::microsvc::Session;
+use crate::outbox::OutboxMessage;
+use crate::projection_protocol::{
+    ProjectionEpoch, ProjectionScopeCodec, ResolvedProjectionKey, ResolvedProjectionKeyField,
+    ResolvedProjectionObligation,
+};
+use crate::read_model::RelationalReadModel;
+
+#[derive(Clone, Debug)]
+pub(crate) struct TypedCommandContract {
+    pub name: String,
+    pub field_name: String,
+    pub roles: Vec<String>,
+    pub input: GraphqlTypeDef,
+    pub output: GraphqlTypeDef,
+    pub input_type_id: TypeId,
+    pub output_type_id: TypeId,
+    pub consistency: CommandConsistency,
+    pub input_defaults: Vec<CommandInputDefault>,
+    pub effects: CommandEffects,
+    pub confirmations: Vec<CommandProjectionConfirmation>,
+    /// Present automatically for `Projected<M>` before Surface ownership is
+    /// resolved. This never requires an application declaration.
+    pub projected_model: Option<CommandProjectedModel>,
+    pub direct_projection: Option<CommandDirectProjectionTarget>,
+}
+
+impl TypedCommandContract {
+    /// Stable per-route identity used in the command ledger fingerprint.
+    ///
+    /// This is intentionally distinct from the service inventory digest: a
+    /// deployment may add unrelated routes without invalidating safe retries
+    /// for this command. The explicit domain/version prevents this byte digest
+    /// from aliasing any other SHA-256 use in the framework.
+    pub(crate) fn fingerprint_bytes(&self) -> [u8; 32] {
+        let mut digest = Sha256::new();
+        digest.update(b"distributed.typed-command-contract.v1");
+        digest.update([0]);
+        digest.update(
+            serde_json::to_vec(&self.canonical_value())
+                .expect("canonical typed command contract serialization cannot fail"),
+        );
+        digest.finalize().into()
+    }
+
+    pub(crate) fn canonical_value(&self) -> serde_json::Value {
+        let mut roles = self.roles.clone();
+        roles.sort();
+        roles.dedup();
+        let mut effects = self.effects.clone();
+        effects.canonicalize();
+        let mut input_defaults = self.input_defaults.clone();
+        input_defaults.sort_by(|left, right| left.path.cmp(&right.path));
+        let mut confirmations = self.confirmations.clone();
+        confirmations.sort_by(|left, right| {
+            serde_json::to_string(&left.canonical_value())
+                .expect("confirmation IR serialization cannot fail")
+                .cmp(
+                    &serde_json::to_string(&right.canonical_value())
+                        .expect("confirmation IR serialization cannot fail"),
+                )
+        });
+        let confirmations = confirmations
+            .iter()
+            .map(CommandProjectionConfirmation::canonical_value)
+            .collect::<Vec<_>>();
+        let direct_projection = self
+            .direct_projection
+            .as_ref()
+            .map(CommandDirectProjectionTarget::canonical_value);
+        let projected_model = self
+            .projected_model
+            .as_ref()
+            .map(CommandProjectedModel::canonical_value);
+        canonical_json(&serde_json::json!({
+            "name": self.name,
+            "field_name": self.field_name,
+            "roles": roles,
+            "input": canonical_graphql_type(&self.input),
+            "output": canonical_graphql_type(&self.output),
+            "consistency": self.consistency,
+            "input_defaults": input_defaults,
+            "effects": effects,
+            "confirmations": confirmations,
+            "projected_model": projected_model,
+            "direct_projection": direct_projection,
+        }))
+    }
+
+    /// Resolve the finite declaration-owned projection plan from the exact
+    /// canonical GraphQL wire input retained beside the decoded command.
+    ///
+    /// Resolution is pure and must run before commit I/O. Confirmation and key
+    /// field order are retained exactly as declared. Input values and constants
+    /// are cloned without a Rust DTO or SQL codec round trip, while explicit
+    /// null remains distinguishable from an undeclared partition.
+    #[allow(dead_code)]
+    pub(crate) fn resolve_projection_obligations(
+        &self,
+        canonical_wire_input: &serde_json::Value,
+    ) -> Result<Vec<ResolvedProjectionObligation>, ProjectionObligationResolutionError> {
+        self.resolve_projection_obligations_from_session(canonical_wire_input, None)
+    }
+
+    pub(crate) fn resolve_projection_obligations_from_session(
+        &self,
+        canonical_wire_input: &serde_json::Value,
+        session: Option<&Session>,
+    ) -> Result<Vec<ResolvedProjectionObligation>, ProjectionObligationResolutionError> {
+        self.confirmations
+            .iter()
+            .map(|confirmation| {
+                let fields = confirmation
+                    .key
+                    .fields
+                    .iter()
+                    .map(|field| {
+                        let target = format!("key field `{}`", field.field);
+                        resolve_projection_obligation_expression(
+                            canonical_wire_input,
+                            confirmation,
+                            &target,
+                            &field.value,
+                            session,
+                            confirmation
+                                .schema
+                                .and_then(|schema| {
+                                    schema
+                                        .columns
+                                        .iter()
+                                        .find(|column| column.column_name == field.field)
+                                })
+                                .and_then(|column| naming::scalar_type_name(&column.column_type)),
+                        )
+                        .map(|value| ResolvedProjectionKeyField {
+                            field: field.field.clone(),
+                            value,
+                        })
+                    })
+                    .collect::<Result<Vec<_>, _>>()?;
+                let partition = confirmation
+                    .partition
+                    .as_ref()
+                    .map(|expression| {
+                        resolve_projection_obligation_expression(
+                            canonical_wire_input,
+                            confirmation,
+                            "partition",
+                            expression,
+                            session,
+                            Some("String"),
+                        )
+                    })
+                    .transpose()?;
+                let key = ResolvedProjectionKey { fields };
+                let topology = confirmation.protocol_topology.clone().ok_or_else(|| {
+                    ProjectionObligationResolutionError::InvalidBinding {
+                        projector: confirmation.projector.clone(),
+                        model: confirmation.model.clone(),
+                        reason: "missing compiled topology identity".into(),
+                    }
+                })?;
+                let schema = confirmation.schema.ok_or_else(|| {
+                    ProjectionObligationResolutionError::InvalidBinding {
+                        projector: confirmation.projector.clone(),
+                        model: confirmation.model.clone(),
+                        reason: "missing retained relational schema".into(),
+                    }
+                })?;
+                let codec = ProjectionScopeCodec::with_models(
+                    topology,
+                    [(schema.model_name.as_str(), schema)],
+                )
+                .map_err(|error| {
+                    ProjectionObligationResolutionError::InvalidBinding {
+                        projector: confirmation.projector.clone(),
+                        model: confirmation.model.clone(),
+                        reason: error.to_string(),
+                    }
+                })?;
+                let scope = codec
+                    .encode_resolved_obligation_scope(
+                        &confirmation.projector,
+                        &confirmation.model,
+                        &key,
+                        partition.as_ref(),
+                    )
+                    .map_err(
+                        |error| ProjectionObligationResolutionError::InvalidBinding {
+                            projector: confirmation.projector.clone(),
+                            model: confirmation.model.clone(),
+                            reason: error.to_string(),
+                        },
+                    )?;
+                Ok(ResolvedProjectionObligation {
+                    projector: confirmation.projector.clone(),
+                    model: confirmation.model.clone(),
+                    key,
+                    partition,
+                    scope,
+                })
+            })
+            .collect()
+    }
+
+    pub(crate) fn resolve_direct_projection_target_from_session(
+        &self,
+        canonical_wire_input: &serde_json::Value,
+        session: Option<&Session>,
+    ) -> Result<Option<ResolvedDirectProjectionTarget>, DirectProjectionTargetResolutionError> {
+        self.direct_projection
+            .as_ref()
+            .map(|target| target.resolve(canonical_wire_input, session))
+            .transpose()
+    }
+
+    /// Prove that every finite asynchronous confirmation can be driven by a
+    /// fact staged in the durable outbox. Aggregate event records intentionally
+    /// do not count: they are write-side history and have no publication path.
+    pub(super) fn validate_outbox_fact_coverage(
+        &self,
+        outbox_messages: &[OutboxMessage],
+    ) -> Result<(), CommandCommitProofError> {
+        if self.consistency == CommandConsistency::Fact && self.confirmations.is_empty() {
+            return Err(CommandCommitProofError::FactHasNoConfirmations);
+        }
+
+        let staged_facts = outbox_messages
+            .iter()
+            .filter(|message| message.destination.is_none() && message.is_pending())
+            .map(|message| message.event_type.clone())
+            .collect::<BTreeSet<_>>();
+        for confirmation in &self.confirmations {
+            if confirmation
+                .projector_topology
+                .facts
+                .iter()
+                .any(|fact| staged_facts.contains(fact))
+            {
+                continue;
+            }
+            return Err(CommandCommitProofError::UnreachableConfirmation {
+                projector: confirmation.projector.clone(),
+                expected_facts: confirmation.projector_topology.facts.clone(),
+                staged_facts: staged_facts.iter().cloned().collect(),
+            });
+        }
+        Ok(())
+    }
+}
+
+fn resolve_projection_obligation_expression(
+    canonical_wire_input: &serde_json::Value,
+    confirmation: &CommandProjectionConfirmation,
+    target: &str,
+    expression: &EffectExpression,
+    session: Option<&Session>,
+    expected_scalar: Option<&str>,
+) -> Result<serde_json::Value, ProjectionObligationResolutionError> {
+    match expression {
+        EffectExpression::Input { path } => {
+            let mut value = canonical_wire_input;
+            if path.is_empty() {
+                return Err(ProjectionObligationResolutionError::MissingInputPath {
+                    projector: confirmation.projector.clone(),
+                    model: confirmation.model.clone(),
+                    target: target.to_string(),
+                    path: path.clone(),
+                });
+            }
+            for segment in path {
+                let Some(next) = value.as_object().and_then(|object| object.get(segment)) else {
+                    return Err(ProjectionObligationResolutionError::MissingInputPath {
+                        projector: confirmation.projector.clone(),
+                        model: confirmation.model.clone(),
+                        target: target.to_string(),
+                        path: path.clone(),
+                    });
+                };
+                value = next;
+            }
+            Ok(value.clone())
+        }
+        EffectExpression::Constant { value } => Ok(value.clone()),
+        EffectExpression::Null => Ok(serde_json::Value::Null),
+        EffectExpression::TrustedPreset { name } => {
+            resolve_trusted_preset(session, name, expected_scalar.unwrap_or("String")).ok_or_else(
+                || ProjectionObligationResolutionError::TrustedPresetUnavailable {
+                    projector: confirmation.projector.clone(),
+                    model: confirmation.model.clone(),
+                    target: target.to_string(),
+                    preset: name.clone(),
+                },
+            )
+        }
+        EffectExpression::InvalidConstant { error } => {
+            Err(ProjectionObligationResolutionError::InvalidConstant {
+                projector: confirmation.projector.clone(),
+                model: confirmation.model.clone(),
+                target: target.to_string(),
+                error: error.clone(),
+            })
+        }
+    }
+}
+
+fn canonical_graphql_type(definition: &GraphqlTypeDef) -> serde_json::Value {
+    let mut fields = definition.fields.iter().collect::<Vec<_>>();
+    fields.sort_by(|left, right| left.name.cmp(&right.name));
+    serde_json::json!({
+        "name": definition.name,
+        "fields": fields.into_iter().map(|field| serde_json::json!({
+            "name": field.name,
+            "type_name": field.type_name,
+            "nullable": field.nullable,
+            "list": field.list,
+            "item_nullable": field.item_nullable,
+            "nested": field.nested.as_deref().map(canonical_graphql_type),
+        })).collect::<Vec<_>>(),
+    })
+}
+
+/// Stable command inventory identity shared by a service and GraphQL engine.
+///
+/// The digest covers canonical wire structure while the non-serializable
+/// `TypeId` pairs prove that both sides were built from the exact Rust input
+/// and output types, not merely lookalike GraphQL shapes.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct TypedServiceCommandBinding {
+    pub service_id: String,
+    pub structural_fingerprint: String,
+    pub types: BTreeMap<String, (TypeId, TypeId)>,
+}
+
+impl TypedServiceCommandBinding {
+    pub(crate) fn from_contracts(
+        service_id: &str,
+        contracts: &[TypedCommandContract],
+    ) -> Result<Self, String> {
+        if service_id.trim().is_empty() {
+            return Err("typed command inventory requires a non-empty service ID".into());
+        }
+
+        let mut seen = BTreeSet::new();
+        let mut ordered = contracts.iter().collect::<Vec<_>>();
+        ordered.sort_by(|left, right| left.name.cmp(&right.name));
+        let mut types = BTreeMap::new();
+        let mut canonical = Vec::with_capacity(ordered.len());
+        for contract in ordered {
+            if contract.name.trim().is_empty() {
+                return Err("typed command id must not be empty".into());
+            }
+            if !seen.insert(contract.name.clone()) {
+                return Err(format!(
+                    "duplicate typed command declaration for `{}`",
+                    contract.name
+                ));
+            }
+            if contract.input.type_id != Some(contract.input_type_id) {
+                return Err(format!(
+                    "typed command `{}` input GraphQL metadata is missing or has a different Rust TypeId",
+                    contract.name
+                ));
+            }
+            if contract.output.type_id != Some(contract.output_type_id) {
+                return Err(format!(
+                    "typed command `{}` output GraphQL metadata is missing or has a different Rust TypeId",
+                    contract.name
+                ));
+            }
+            match contract.consistency {
+                CommandConsistency::Fact if contract.confirmations.is_empty() => {
+                    return Err(format!(
+                        "typed fact command `{}` must declare at least one expected projector confirmation",
+                        contract.name
+                    ));
+                }
+                CommandConsistency::Projected if !contract.confirmations.is_empty() => {
+                    return Err(format!(
+                        "typed projected command `{}` cannot declare asynchronous projector confirmations",
+                        contract.name
+                    ));
+                }
+                CommandConsistency::Projected if contract.projected_model.is_none() => {
+                    return Err(format!(
+                        "typed projected command `{}` is missing its compiler-retained relational model",
+                        contract.name
+                    ));
+                }
+                CommandConsistency::Accepted | CommandConsistency::Fact
+                    if contract.projected_model.is_some()
+                        || contract.direct_projection.is_some() =>
+                {
+                    return Err(format!(
+                        "typed non-projected command `{}` cannot carry direct projection metadata",
+                        contract.name
+                    ));
+                }
+                CommandConsistency::Fact
+                | CommandConsistency::Accepted
+                | CommandConsistency::Projected => {}
+            }
+            if let Some(projected) = &contract.projected_model {
+                if projected.output_type_id != contract.output_type_id {
+                    return Err(format!(
+                        "typed projected command `{}` retained model has a different Rust output type",
+                        contract.name
+                    ));
+                }
+                if projected.model != contract.output.name {
+                    return Err(format!(
+                        "typed projected command `{}` retained model `{}` differs from output `{}`",
+                        contract.name, projected.model, contract.output.name
+                    ));
+                }
+            }
+            if let Some(target) = &contract.direct_projection {
+                if target.output_type_id != contract.output_type_id {
+                    return Err(format!(
+                        "typed projected command `{}` direct target has a different Rust output type",
+                        contract.name
+                    ));
+                }
+                if target.model != contract.output.name {
+                    return Err(format!(
+                        "typed projected command `{}` direct target model `{}` differs from output `{}`",
+                        contract.name, target.model, contract.output.name
+                    ));
+                }
+                let Some(change_epoch) = target.change_epoch.as_deref() else {
+                    return Err(format!(
+                        "typed projected command `{}` direct target has no registered change-log epoch",
+                        contract.name
+                    ));
+                };
+                ProjectionEpoch::new(change_epoch).map_err(|error| {
+                    format!(
+                        "typed projected command `{}` direct target change epoch is invalid: {error}",
+                        contract.name
+                    )
+                })?;
+            }
+            if let Some(error) = contract
+                .effects
+                .invalid_constant_error()
+                .or_else(|| {
+                    contract
+                        .confirmations
+                        .iter()
+                        .find_map(invalid_confirmation_constant)
+                })
+                .or_else(|| {
+                    contract
+                        .direct_projection
+                        .as_ref()
+                        .and_then(|target| target.partition.as_ref())
+                        .and_then(invalid_expression_constant)
+                })
+                .or_else(|| {
+                    contract
+                        .projected_model
+                        .as_ref()
+                        .and_then(|model| model.partition.as_ref())
+                        .and_then(invalid_expression_constant)
+                })
+            {
+                return Err(format!(
+                    "typed command `{}` constant effect value failed to serialize: {error}",
+                    contract.name
+                ));
+            }
+            let mut confirmations = BTreeSet::new();
+            for confirmation in &contract.confirmations {
+                let canonical = serde_json::to_string(&confirmation.canonical_value())
+                    .expect("confirmation IR serialization cannot fail");
+                if !confirmations.insert(canonical) {
+                    return Err(format!(
+                        "typed command `{}` repeats an expected projector confirmation",
+                        contract.name
+                    ));
+                }
+            }
+            types.insert(
+                contract.name.clone(),
+                (contract.input_type_id, contract.output_type_id),
+            );
+            canonical.push(contract.canonical_value());
+        }
+
+        let material = canonical_json(&serde_json::json!({
+            "service_id": service_id,
+            "commands": canonical,
+        }));
+        let bytes = serde_json::to_vec(&material)
+            .expect("serializing canonical command inventory cannot fail");
+        Ok(Self {
+            service_id: service_id.to_string(),
+            structural_fingerprint: format!("sha256:{:x}", Sha256::digest(bytes)),
+            types,
+        })
+    }
+}
+
+/// A typed command declaration registered together with its executable handler.
+pub struct TypedCommand<I, K: CommandOutcome> {
+    route_name: &'static str,
+    contract: TypedCommandContract,
+    _types: PhantomData<fn(I) -> K>,
+}
+
+impl<I, K: CommandOutcome> Clone for TypedCommand<I, K> {
+    fn clone(&self) -> Self {
+        Self {
+            route_name: self.route_name,
+            contract: self.contract.clone(),
+            _types: PhantomData,
+        }
+    }
+}
+
+/// Begin a typed command declaration.
+pub fn typed_command<I, K>(name: &'static str) -> TypedCommand<I, K>
+where
+    I: GraphqlInputType + DeserializeOwned + Send + 'static,
+    K: CommandOutcome,
+{
+    let route_name = name;
+    let name = route_name.to_string();
+    let field_name = name
+        .chars()
+        .map(|character| match character {
+            '.' | '-' => '_',
+            other => other,
+        })
+        .collect();
+    let input = I::graphql_type();
+    let output = K::Payload::graphql_type();
+    let projected_model = K::__projected_model()
+        .map(|(output_type_id, schema)| CommandProjectedModel::new(output_type_id, schema));
+    TypedCommand {
+        route_name,
+        contract: TypedCommandContract {
+            name,
+            field_name,
+            roles: Vec::new(),
+            input,
+            output,
+            input_type_id: TypeId::of::<I>(),
+            output_type_id: TypeId::of::<K::Payload>(),
+            consistency: K::CONSISTENCY,
+            input_defaults: Vec::new(),
+            effects: CommandEffects::revalidate(),
+            confirmations: Vec::new(),
+            projected_model,
+            direct_projection: None,
+        },
+        _types: PhantomData,
+    }
+}
+
+impl<I, K: CommandOutcome> TypedCommand<I, K> {
+    pub fn field_name(mut self, field_name: impl Into<String>) -> Self {
+        self.contract.field_name = field_name.into();
+        self
+    }
+
+    pub fn roles(mut self, roles: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        self.contract.roles = roles.into_iter().map(Into::into).collect();
+        self.contract.roles.sort();
+        self.contract.roles.dedup();
+        self
+    }
+
+    pub fn effects(mut self, effects: CompiledCommandEffects<I>) -> Self {
+        self.contract.effects = effects.0;
+        self.contract.effects.canonicalize();
+        self
+    }
+
+    /// Declare values generated once into the canonical command input before
+    /// dispatch. Effects and confirmations must reference the finalized input
+    /// field rather than invoking a generator independently.
+    pub fn input_defaults(mut self, defaults: CompiledInputDefaults<I>) -> Self {
+        self.contract.input_defaults = defaults.0;
+        self.contract
+            .input_defaults
+            .sort_by(|left, right| left.path.cmp(&right.path));
+        self
+    }
+
+    /// Declare the finite projector/model/key progress that confirms this fact.
+    /// `Fact<_>` commands require at least one confirmation. `Accepted<_>` may
+    /// omit the plan (terminal accepted) or provide one (pending projection).
+    /// `Projected<_>` commands cannot carry asynchronous confirmations.
+    pub fn confirmations(mut self, confirmations: CompiledConfirmationPlan<I>) -> Self {
+        self.contract.confirmations = confirmations.0;
+        self
+    }
+
+    pub fn name(&self) -> &str {
+        &self.contract.name
+    }
+
+    pub fn consistency(&self) -> CommandConsistency {
+        self.contract.consistency
+    }
+
+    #[cfg(test)]
+    pub(crate) fn into_contract(self) -> TypedCommandContract {
+        self.contract
+    }
+
+    pub(crate) fn into_parts(self) -> (&'static str, TypedCommandContract) {
+        (self.route_name, self.contract)
+    }
+}
+
+impl<I, M> TypedCommand<I, Projected<M>>
+where
+    I: GraphqlInputType + DeserializeOwned + Send + 'static,
+    M: GraphqlOutputType + RelationalReadModel + Serialize + Send + Sync + 'static,
+{
+    /// Attach compiler-generated direct projection ownership metadata.
+    ///
+    /// Application handlers do not call this; generated service inventory
+    /// binds it from the registered projector declaration and handlers retain
+    /// the `context.projected(view)` API.
+    #[doc(hidden)]
+    pub fn __direct_projection(mut self, target: CompiledDirectProjectionTarget<I, M>) -> Self {
+        if let Some(projected) = &mut self.contract.projected_model {
+            projected.partition = target.0.partition.clone();
+        }
+        self.contract.direct_projection = Some(target.0);
+        self
+    }
+}
diff --git a/src/graphql/command_input.rs b/src/graphql/command_input.rs
new file mode 100644
index 00000000..2ae2bead
--- /dev/null
+++ b/src/graphql/command_input.rs
@@ -0,0 +1,542 @@
+//! Canonical typed GraphQL command-input validation.
+//!
+//! Authenticated GraphQL causal dispatch passes through this one validator
+//! before ledger reservation. Direct and bus transports currently fail closed;
+//! any future verified framework envelope must enter through this same path.
+//! The retained wire value is the source of hashing and declaration-expression
+//! resolution, so decoding the Rust input never becomes a second, potentially
+//! differently named serialization path.
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use base64::Engine as _;
+use serde::de::DeserializeOwned;
+use serde_json::{Number, Value};
+use sha2::{Digest, Sha256};
+
+use super::{GraphqlTypeDef, GraphqlTypeField};
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct CommandInputError {
+    message: String,
+}
+
+impl CommandInputError {
+    fn at(path: &str, message: impl Into<String>) -> Self {
+        Self {
+            message: format!("command input `{path}` {}", message.into()),
+        }
+    }
+
+    fn configuration(message: impl Into<String>) -> Self {
+        Self {
+            message: format!("command input definition {}", message.into()),
+        }
+    }
+}
+
+impl std::fmt::Display for CommandInputError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for CommandInputError {}
+
+/// Validated, recursively key-sorted GraphQL wire input and its stable digest.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct CanonicalCommandInput {
+    wire: Value,
+    digest: [u8; 32],
+}
+
+impl CanonicalCommandInput {
+    #[cfg(test)]
+    pub(crate) fn wire(&self) -> &Value {
+        &self.wire
+    }
+
+    #[cfg(test)]
+    pub(crate) fn hash(&self) -> String {
+        format!("sha256:{}", hex_digest(&self.digest))
+    }
+
+    /// Decode the retained wire value exactly once into the route's registered
+    /// Rust input type while keeping that same wire/hash for effects and ledger
+    /// completion. This intentionally never serializes `I` back to JSON.
+    pub(crate) fn decode<I: DeserializeOwned>(
+        self,
+    ) -> Result<CanonicalTypedCommandInput<I>, CommandInputError> {
+        let decoded = serde_json::from_value(self.wire.clone()).map_err(|error| {
+            CommandInputError::at(
+                "$",
+                format!("does not decode as the registered type: {error}"),
+            )
+        })?;
+        Ok(CanonicalTypedCommandInput {
+            decoded,
+            wire: self.wire,
+            digest: self.digest,
+        })
+    }
+}
+
+/// Private input envelope consumed by one exact typed route.
+pub(crate) struct CanonicalTypedCommandInput<I> {
+    decoded: I,
+    wire: Value,
+    digest: [u8; 32],
+}
+
+impl<I> CanonicalTypedCommandInput<I> {
+    #[cfg(test)]
+    pub(crate) fn decoded(&self) -> &I {
+        &self.decoded
+    }
+
+    #[cfg(test)]
+    pub(crate) fn wire(&self) -> &Value {
+        &self.wire
+    }
+
+    #[cfg(test)]
+    pub(crate) fn hash(&self) -> String {
+        format!("sha256:{}", hex_digest(&self.digest))
+    }
+
+    pub(crate) fn into_parts(self) -> (I, Value, [u8; 32]) {
+        (self.decoded, self.wire, self.digest)
+    }
+}
+
+pub(crate) fn canonicalize_command_input(
+    definition: &GraphqlTypeDef,
+    input: Value,
+) -> Result<CanonicalCommandInput, CommandInputError> {
+    let wire = canonicalize_object(definition, input, "$")?;
+    let bytes = serde_json::to_vec(&wire).map_err(|error| {
+        CommandInputError::at("$", format!("cannot be canonically encoded: {error}"))
+    })?;
+    let digest: [u8; 32] = Sha256::digest(bytes).into();
+    Ok(CanonicalCommandInput { wire, digest })
+}
+
+#[cfg(test)]
+fn hex_digest(digest: &[u8; 32]) -> String {
+    use std::fmt::Write as _;
+    let mut encoded = String::with_capacity(64);
+    for byte in digest {
+        write!(&mut encoded, "{byte:02x}").expect("writing to String cannot fail");
+    }
+    encoded
+}
+
+fn canonicalize_object(
+    definition: &GraphqlTypeDef,
+    value: Value,
+    path: &str,
+) -> Result<Value, CommandInputError> {
+    let Value::Object(mut object) = value else {
+        return Err(CommandInputError::at(path, "must be an object"));
+    };
+
+    let mut fields = BTreeMap::new();
+    for field in &definition.fields {
+        if fields.insert(field.name.as_str(), field).is_some() {
+            return Err(CommandInputError::configuration(format!(
+                "`{}` repeats field `{}`",
+                definition.name, field.name
+            )));
+        }
+    }
+    let declared = fields.keys().copied().collect::<BTreeSet<_>>();
+    let mut unknown = object
+        .keys()
+        .filter(|name| !declared.contains(name.as_str()))
+        .cloned()
+        .collect::<Vec<_>>();
+    unknown.sort();
+    if let Some(name) = unknown.first() {
+        return Err(CommandInputError::at(
+            &field_path(path, name),
+            "is not declared",
+        ));
+    }
+
+    let mut canonical = serde_json::Map::new();
+    for (name, field) in fields {
+        let Some(value) = object.remove(name) else {
+            if field.nullable {
+                continue;
+            }
+            return Err(CommandInputError::at(
+                &field_path(path, name),
+                "is required",
+            ));
+        };
+        canonical.insert(
+            name.to_string(),
+            canonicalize_field(field, value, &field_path(path, name))?,
+        );
+    }
+    Ok(Value::Object(canonical))
+}
+
+fn canonicalize_field(
+    field: &GraphqlTypeField,
+    value: Value,
+    path: &str,
+) -> Result<Value, CommandInputError> {
+    if value.is_null() {
+        return if field.nullable {
+            Ok(Value::Null)
+        } else {
+            Err(CommandInputError::at(path, "cannot be null"))
+        };
+    }
+
+    if field.list {
+        let Value::Array(values) = value else {
+            return Err(CommandInputError::at(path, "must be a list"));
+        };
+        let mut canonical = Vec::with_capacity(values.len());
+        for (index, value) in values.into_iter().enumerate() {
+            let item_path = format!("{path}[{index}]");
+            if value.is_null() {
+                if !field.item_nullable {
+                    return Err(CommandInputError::at(&item_path, "cannot be null"));
+                }
+                canonical.push(Value::Null);
+            } else {
+                canonical.push(canonicalize_leaf(field, value, &item_path)?);
+            }
+        }
+        return Ok(Value::Array(canonical));
+    }
+
+    canonicalize_leaf(field, value, path)
+}
+
+fn canonicalize_leaf(
+    field: &GraphqlTypeField,
+    value: Value,
+    path: &str,
+) -> Result<Value, CommandInputError> {
+    if let Some(nested) = field.nested.as_deref() {
+        return canonicalize_object(nested, value, path);
+    }
+
+    match field.type_name.as_str() {
+        "String" | "Timestamptz" => match value {
+            Value::String(value) => {
+                if field.type_name == "Timestamptz" && !is_rfc3339_timestamp(&value) {
+                    Err(CommandInputError::at(path, "must be an RFC 3339 timestamp"))
+                } else {
+                    Ok(Value::String(value))
+                }
+            }
+            _ => Err(CommandInputError::at(path, "must be a string")),
+        },
+        "ID" => match value {
+            Value::String(value) => Ok(Value::String(value)),
+            Value::Number(value) if value.is_i64() || value.is_u64() => {
+                Ok(Value::String(value.to_string()))
+            }
+            _ => Err(CommandInputError::at(
+                path,
+                "must be a string or integer ID",
+            )),
+        },
+        "Boolean" => match value {
+            Value::Bool(value) => Ok(Value::Bool(value)),
+            _ => Err(CommandInputError::at(path, "must be a boolean")),
+        },
+        "BigInt" => match value {
+            Value::Number(value) if value.is_i64() || value.is_u64() => Ok(Value::Number(value)),
+            _ => Err(CommandInputError::at(path, "must be an integer")),
+        },
+        "Int" => match value {
+            Value::Number(value)
+                if value
+                    .as_i64()
+                    .is_some_and(|value| i32::try_from(value).is_ok())
+                    || value
+                        .as_u64()
+                        .is_some_and(|value| i32::try_from(value).is_ok()) =>
+            {
+                Ok(Value::Number(value))
+            }
+            _ => Err(CommandInputError::at(path, "must be a 32-bit integer")),
+        },
+        "Float" => match value {
+            Value::Number(value) => {
+                let finite = value
+                    .as_f64()
+                    .and_then(Number::from_f64)
+                    .ok_or_else(|| CommandInputError::at(path, "must be a finite number"))?;
+                Ok(Value::Number(finite))
+            }
+            _ => Err(CommandInputError::at(path, "must be a number")),
+        },
+        "Bytea" => match value {
+            Value::String(value) => {
+                let decoded = base64::engine::general_purpose::STANDARD
+                    .decode(value)
+                    .map_err(|_| CommandInputError::at(path, "must be canonical base64"))?;
+                Ok(Value::String(
+                    base64::engine::general_purpose::STANDARD.encode(decoded),
+                ))
+            }
+            _ => Err(CommandInputError::at(path, "must be a base64 string")),
+        },
+        "JSON" => Ok(canonical_json(value)),
+        scalar => Err(CommandInputError::configuration(format!(
+            "`{}` field `{}` uses unsupported scalar `{scalar}`",
+            field.type_name, field.name
+        ))),
+    }
+}
+
+fn canonical_json(value: Value) -> Value {
+    match value {
+        Value::Array(values) => Value::Array(values.into_iter().map(canonical_json).collect()),
+        Value::Object(values) => {
+            let mut values = values.into_iter().collect::<Vec<_>>();
+            values.sort_by(|(left, _), (right, _)| left.cmp(right));
+            Value::Object(
+                values
+                    .into_iter()
+                    .map(|(key, value)| (key, canonical_json(value)))
+                    .collect(),
+            )
+        }
+        scalar => scalar,
+    }
+}
+
+fn field_path(parent: &str, field: &str) -> String {
+    if parent == "$" {
+        format!("$.{field}")
+    } else {
+        format!("{parent}.{field}")
+    }
+}
+
+fn is_rfc3339_timestamp(value: &str) -> bool {
+    let bytes = value.as_bytes();
+    if bytes.len() < 20
+        || bytes.get(4) != Some(&b'-')
+        || bytes.get(7) != Some(&b'-')
+        || !matches!(bytes.get(10), Some(b'T' | b't'))
+        || bytes.get(13) != Some(&b':')
+        || bytes.get(16) != Some(&b':')
+    {
+        return false;
+    }
+    let digits = |range: std::ops::Range<usize>| -> Option<u32> {
+        std::str::from_utf8(bytes.get(range)?).ok()?.parse().ok()
+    };
+    let (Some(year), Some(month), Some(day), Some(hour), Some(minute), Some(second)) = (
+        digits(0..4),
+        digits(5..7),
+        digits(8..10),
+        digits(11..13),
+        digits(14..16),
+        digits(17..19),
+    ) else {
+        return false;
+    };
+    let leap = year % 4 == 0 && (year % 100 != 0 || year % 400 == 0);
+    let max_day = match month {
+        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
+        4 | 6 | 9 | 11 => 30,
+        2 if leap => 29,
+        2 => 28,
+        _ => return false,
+    };
+    if day == 0 || day > max_day || hour > 23 || minute > 59 || second > 60 {
+        return false;
+    }
+
+    let mut cursor = 19;
+    if bytes.get(cursor) == Some(&b'.') {
+        cursor += 1;
+        let fraction_start = cursor;
+        while bytes.get(cursor).is_some_and(u8::is_ascii_digit) {
+            cursor += 1;
+        }
+        if cursor == fraction_start {
+            return false;
+        }
+    }
+    match bytes.get(cursor) {
+        Some(b'Z' | b'z') => cursor + 1 == bytes.len(),
+        Some(b'+' | b'-') => {
+            if cursor + 6 != bytes.len() || bytes.get(cursor + 3) != Some(&b':') {
+                return false;
+            }
+            let hour = std::str::from_utf8(&bytes[cursor + 1..cursor + 3])
+                .ok()
+                .and_then(|value| value.parse::<u32>().ok());
+            let minute = std::str::from_utf8(&bytes[cursor + 4..cursor + 6])
+                .ok()
+                .and_then(|value| value.parse::<u32>().ok());
+            matches!((hour, minute), (Some(0..=23), Some(0..=59)))
+        }
+        _ => false,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde::Deserialize;
+    use serde_json::json;
+
+    fn field(
+        name: &str,
+        type_name: &str,
+        nullable: bool,
+        list: bool,
+        item_nullable: bool,
+        nested: Option<GraphqlTypeDef>,
+    ) -> GraphqlTypeField {
+        GraphqlTypeField {
+            name: name.into(),
+            type_name: type_name.into(),
+            nullable,
+            list,
+            item_nullable,
+            nested: nested.map(Box::new),
+        }
+    }
+
+    fn definition() -> GraphqlTypeDef {
+        GraphqlTypeDef::new(
+            "Input",
+            vec![
+                field("id", "String", false, false, false, None),
+                field("note", "String", true, false, false, None),
+                field("tags", "String", false, true, false, None),
+                field(
+                    "nested",
+                    "NestedInput",
+                    false,
+                    false,
+                    false,
+                    Some(GraphqlTypeDef::new(
+                        "NestedInput",
+                        vec![field("count", "BigInt", false, false, false, None)],
+                    )),
+                ),
+                field("document", "JSON", true, false, false, None),
+            ],
+        )
+    }
+
+    #[test]
+    fn key_order_is_canonical_but_lists_are_preserved() {
+        let left = canonicalize_command_input(
+            &definition(),
+            json!({
+                "tags": ["b", "a"],
+                "nested": { "count": 2 },
+                "id": "one",
+                "document": { "z": 1, "a": { "y": 2, "x": 1 } }
+            }),
+        )
+        .unwrap();
+        let right = canonicalize_command_input(
+            &definition(),
+            json!({
+                "document": { "a": { "x": 1, "y": 2 }, "z": 1 },
+                "id": "one",
+                "nested": { "count": 2 },
+                "tags": ["b", "a"]
+            }),
+        )
+        .unwrap();
+        assert_eq!(left, right);
+        assert_eq!(left.wire()["tags"], json!(["b", "a"]));
+    }
+
+    #[test]
+    fn absent_nullable_and_explicit_null_remain_distinct() {
+        let absent = canonicalize_command_input(
+            &definition(),
+            json!({ "id": "one", "tags": [], "nested": { "count": 1 } }),
+        )
+        .unwrap();
+        let null = canonicalize_command_input(
+            &definition(),
+            json!({ "id": "one", "note": null, "tags": [], "nested": { "count": 1 } }),
+        )
+        .unwrap();
+        assert_ne!(absent.hash(), null.hash());
+        assert!(absent.wire().get("note").is_none());
+        assert!(null.wire()["note"].is_null());
+    }
+
+    #[test]
+    fn rejects_unknown_missing_null_list_and_scalar_violations() {
+        for (input, needle) in [
+            (
+                json!({ "id": "one", "extra": 1, "tags": [], "nested": { "count": 1 } }),
+                "$.extra` is not declared",
+            ),
+            (
+                json!({ "tags": [], "nested": { "count": 1 } }),
+                "$.id` is required",
+            ),
+            (
+                json!({ "id": null, "tags": [], "nested": { "count": 1 } }),
+                "$.id` cannot be null",
+            ),
+            (
+                json!({ "id": "one", "tags": [null], "nested": { "count": 1 } }),
+                "$.tags[0]` cannot be null",
+            ),
+            (
+                json!({ "id": "one", "tags": [], "nested": { "count": 1.5 } }),
+                "$.nested.count` must be an integer",
+            ),
+        ] {
+            let error = canonicalize_command_input(&definition(), input).unwrap_err();
+            assert!(error.to_string().contains(needle), "{error}");
+        }
+    }
+
+    #[test]
+    fn graphql_int_is_limited_to_the_signed_32_bit_range() {
+        let definition = GraphqlTypeDef::new(
+            "IntInput",
+            vec![field("value", "Int", false, false, false, None)],
+        );
+        canonicalize_command_input(&definition, json!({ "value": i32::MAX })).unwrap();
+        let error =
+            canonicalize_command_input(&definition, json!({ "value": i64::from(i32::MAX) + 1 }))
+                .unwrap_err();
+        assert!(error.to_string().contains("must be a 32-bit integer"));
+    }
+
+    #[derive(Debug, Deserialize, PartialEq, Eq)]
+    struct RenamedInput {
+        #[serde(rename = "wireId")]
+        id: String,
+    }
+
+    #[test]
+    fn decoding_retains_the_original_wire_instead_of_reserializing_rust() {
+        let definition = GraphqlTypeDef::new(
+            "RenamedInput",
+            vec![field("wireId", "String", false, false, false, None)],
+        );
+        let typed = canonicalize_command_input(&definition, json!({ "wireId": "one" }))
+            .unwrap()
+            .decode::<RenamedInput>()
+            .unwrap();
+        assert_eq!(typed.decoded(), &RenamedInput { id: "one".into() });
+        assert_eq!(typed.wire(), &json!({ "wireId": "one" }));
+        assert_eq!(typed.hash().len(), "sha256:".len() + 64);
+    }
+}
diff --git a/src/graphql/commands.rs b/src/graphql/commands.rs
new file mode 100644
index 00000000..eb3fc22e
--- /dev/null
+++ b/src/graphql/commands.rs
@@ -0,0 +1,255 @@
+//! Crate-private GraphQL command inventory.
+//!
+//! GraphQL mutations are derived exclusively from the executable service's
+//! typed causal command contracts. There is deliberately no second public
+//! registry, JSON-shaped escape hatch, or client policy catalog.
+
+#[cfg(feature = "graphql")]
+use std::collections::BTreeMap;
+use std::collections::BTreeSet;
+
+#[cfg(feature = "graphql")]
+use super::command_contract::CommandConsistency;
+use super::command_contract::TypedCommandContract;
+#[cfg(feature = "graphql")]
+use super::surface::SurfaceProjectionOwner;
+use super::surface::{SurfaceCommand, SurfaceCommandShape, SurfaceTypeDef, SurfaceTypeField};
+use super::types::GraphqlTypeDef;
+#[cfg(feature = "graphql")]
+use crate::projection_protocol::compile_projection_topology;
+
+#[derive(Clone, Debug, Default)]
+pub(crate) struct TypedCommandInventory {
+    contracts: Vec<TypedCommandContract>,
+}
+
+fn surface_type(definition: &GraphqlTypeDef) -> SurfaceTypeDef {
+    SurfaceTypeDef {
+        name: definition.name.clone(),
+        fields: definition
+            .fields
+            .iter()
+            .map(|field| SurfaceTypeField {
+                name: field.name.clone(),
+                type_name: field.type_name.clone(),
+                nullable: field.nullable,
+                list: field.list,
+                item_nullable: field.item_nullable,
+                nested: field.nested.as_deref().map(surface_type).map(Box::new),
+            })
+            .collect(),
+    }
+}
+
+impl TypedCommandInventory {
+    #[cfg(any(feature = "graphql", test))]
+    pub(crate) fn empty() -> Self {
+        Self::default()
+    }
+
+    pub(crate) fn from_contracts(contracts: &[TypedCommandContract]) -> Result<Self, String> {
+        let mut seen = BTreeSet::new();
+        let mut contracts = contracts.to_vec();
+        for contract in &contracts {
+            if contract.name.trim().is_empty() {
+                return Err("typed command id must not be empty".into());
+            }
+            if !seen.insert(contract.name.clone()) {
+                return Err(format!(
+                    "duplicate typed command declaration for `{}`",
+                    contract.name
+                ));
+            }
+        }
+        contracts.sort_by(|left, right| left.name.cmp(&right.name));
+        Ok(Self { contracts })
+    }
+
+    pub(crate) fn surface_commands(&self) -> Vec<SurfaceCommand> {
+        self.contracts
+            .iter()
+            .map(|contract| {
+                let mut roles = contract.roles.clone();
+                roles.sort();
+                roles.dedup();
+                SurfaceCommand {
+                    command_name: contract.name.clone(),
+                    field_name: contract.field_name.clone(),
+                    roles,
+                    input: SurfaceCommandShape::Typed(surface_type(&contract.input)),
+                    output: SurfaceCommandShape::Typed(surface_type(&contract.output)),
+                    consistency: contract.consistency,
+                    input_defaults: contract.input_defaults.clone(),
+                    effects: Some(contract.effects.clone()),
+                    confirmations: contract.confirmations.clone(),
+                    projected_model: contract.projected_model.clone(),
+                    direct_projection: contract.direct_projection.clone(),
+                    confirmation_unavailable: false,
+                }
+            })
+            .collect()
+    }
+
+    #[cfg(feature = "graphql")]
+    pub(crate) fn contracts_for_binding(&self) -> Vec<TypedCommandContract> {
+        self.contracts.clone()
+    }
+
+    /// Bind every confirmation and ordinary `Projected<M>` target to the exact
+    /// compiled projector registry. Runtime lowering never reconstructs
+    /// authority from projector/model strings.
+    #[cfg(feature = "graphql")]
+    pub(crate) fn bind_direct_projection_targets(
+        &mut self,
+        projectors: &[SurfaceProjectionOwner],
+        model_schemas: &BTreeMap<String, crate::table::TableSchema>,
+    ) -> Result<(), String> {
+        let mut compiled_projectors = BTreeMap::new();
+        for projector in projectors {
+            let schemas = projector
+                .models
+                .iter()
+                .map(|model| {
+                    model_schemas.get(model).ok_or_else(|| {
+                        format!(
+                            "projector `{}` references unknown model `{model}`",
+                            projector.name
+                        )
+                    })
+                })
+                .collect::<Result<Vec<_>, _>>()?;
+            let compiled = compile_projection_topology(
+                &projector.name,
+                &projector.facts,
+                &projector.models,
+                &projector.partition,
+                schemas,
+            )
+            .map_err(|error| {
+                format!(
+                    "projector `{}` has invalid compiled topology: {error}",
+                    projector.name
+                )
+            })?;
+            compiled_projectors.insert(projector.name.clone(), compiled);
+        }
+
+        for contract in &mut self.contracts {
+            let name = &contract.name;
+            for confirmation in &mut contract.confirmations {
+                let projector = projectors
+                    .iter()
+                    .find(|projector| projector.name == confirmation.projector)
+                    .ok_or_else(|| {
+                        format!(
+                            "typed command `{name}` expects unknown projector `{}`",
+                            confirmation.projector
+                        )
+                    })?;
+                if !confirmation.topology_matches(
+                    &projector.name,
+                    &projector.facts,
+                    &projector.models,
+                    &projector.partition,
+                ) {
+                    return Err(format!(
+                        "typed command `{name}` captured projector `{}` topology identity does not match the registered projector facts/models",
+                        confirmation.projector
+                    ));
+                }
+                if !confirmation.partition_matches(&projector.partition) {
+                    return Err(format!(
+                        "typed command `{name}` confirmation for projector `{}` does not provide the partition mapping required by its declaration",
+                        confirmation.projector
+                    ));
+                }
+                if !projector
+                    .models
+                    .iter()
+                    .any(|model| model == &confirmation.model)
+                {
+                    return Err(format!(
+                        "typed command `{name}` expects projector `{}` to confirm model `{}`, but that model is not in the projector topology",
+                        confirmation.projector, confirmation.model
+                    ));
+                }
+                let (topology, _) = compiled_projectors
+                    .get(&projector.name)
+                    .expect("every registered projector was compiled above");
+                confirmation.bind_protocol_topology(topology.clone());
+            }
+
+            if contract.consistency != CommandConsistency::Projected {
+                continue;
+            }
+            let projected = contract.projected_model.as_ref().ok_or_else(|| {
+                format!(
+                    "typed projected command `{name}` is missing its compiler-retained relational model"
+                )
+            })?;
+            let owners = projectors
+                .iter()
+                .filter(|projector| {
+                    projector
+                        .models
+                        .iter()
+                        .any(|model| model == &projected.model)
+                })
+                .collect::<Vec<_>>();
+            let projector = match owners.as_slice() {
+                [projector] => *projector,
+                [] => {
+                    return Err(format!(
+                        "typed projected command `{name}` output model `{}` has no registered SurfaceProjector owner",
+                        projected.model
+                    ));
+                }
+                _ => {
+                    return Err(format!(
+                        "typed projected command `{name}` output model `{}` has ambiguous SurfaceProjector ownership: {}",
+                        projected.model,
+                        owners
+                            .iter()
+                            .map(|owner| owner.name.as_str())
+                            .collect::<Vec<_>>()
+                            .join(", ")
+                    ));
+                }
+            };
+            if projector.change_epoch.is_none() {
+                return Err(format!(
+                    "typed projected command `{name}` owner `{}` has no registered change-log epoch",
+                    projector.name
+                ));
+            }
+            let registered_schema = model_schemas
+                .get(&projected.model)
+                .expect("projector ownership above requires a registered model schema");
+            if projected.schema != registered_schema {
+                return Err(format!(
+                    "typed projected command `{name}` retained schema for `{}` differs from the registered full table schema",
+                    projected.model
+                ));
+            }
+            if !projected.partition_matches(&projector.partition) {
+                return Err(format!(
+                    "typed projected command `{name}` does not provide the partition mapping required by projector `{}`",
+                    projector.name
+                ));
+            }
+            let (protocol_topology, ownership) = compiled_projectors
+                .get(&projector.name)
+                .expect("every registered projector was compiled above");
+            contract.direct_projection = Some(projected.bind(
+                &projector.name,
+                &projector.facts,
+                &projector.models,
+                &projector.partition,
+                projector.change_epoch.as_deref(),
+                ownership.clone(),
+                Some(protocol_topology.clone()),
+            ));
+        }
+        Ok(())
+    }
+}
diff --git a/src/graphql/compile/binds.rs b/src/graphql/compile/binds.rs
new file mode 100644
index 00000000..fa052f34
--- /dev/null
+++ b/src/graphql/compile/binds.rs
@@ -0,0 +1,138 @@
+use async_graphql::Value;
+use serde::Serialize;
+use serde_json::Value as JsonValue;
+
+use crate::graphql::filter::{LitValue, Operand};
+use crate::microsvc::Session;
+use crate::table::ColumnType;
+
+#[derive(Clone, Debug, Serialize)]
+#[serde(tag = "type", content = "value", rename_all = "snake_case")]
+pub enum BindValue {
+    Null,
+    Bool(bool),
+    I64(i64),
+    F64(f64),
+    Text(String),
+    Bytes(Vec<u8>),
+    Json(JsonValue),
+}
+
+pub(super) fn operand_to_bind(
+    op: &Operand,
+    session: &Session,
+    column_type: &ColumnType,
+) -> Result<BindValue, String> {
+    match op {
+        Operand::Lit(lit) => lit_to_bind(lit),
+        Operand::Claim(c) => {
+            let raw = session
+                .get(&c.header)
+                .or_else(|| session.get(&c.header.to_ascii_lowercase()))
+                .ok_or_else(|| format!("missing claim `{}`", c.header))?;
+            parse_claim(raw, column_type)
+        }
+    }
+}
+
+fn lit_to_bind(lit: &LitValue) -> Result<BindValue, String> {
+    Ok(match lit {
+        LitValue::String(s) => BindValue::Text(s.clone()),
+        LitValue::I64(i) => BindValue::I64(*i),
+        LitValue::F64(f) => BindValue::F64(*f),
+        LitValue::Bool(b) => BindValue::Bool(*b),
+        LitValue::Json(j) => BindValue::Json(j.clone()),
+        LitValue::Null => BindValue::Null,
+    })
+}
+
+fn parse_claim(raw: &str, column_type: &ColumnType) -> Result<BindValue, String> {
+    match column_type {
+        ColumnType::Integer | ColumnType::UnsignedInteger => raw
+            .parse::<i64>()
+            .map(BindValue::I64)
+            .map_err(|_| format!("claim value `{raw}` is not an integer")),
+        ColumnType::Float => raw
+            .parse::<f64>()
+            .map(BindValue::F64)
+            .map_err(|_| format!("claim value `{raw}` is not a float")),
+        ColumnType::Boolean => match raw {
+            "true" | "TRUE" | "1" => Ok(BindValue::Bool(true)),
+            "false" | "FALSE" | "0" => Ok(BindValue::Bool(false)),
+            _ => Err(format!("claim value `{raw}` is not a boolean")),
+        },
+        ColumnType::Json => Err("claims cannot compare to Json columns".into()),
+        _ => Ok(BindValue::Text(raw.to_string())),
+    }
+}
+
+pub(super) fn value_to_bind(v: &Value, column_type: &ColumnType) -> Result<BindValue, String> {
+    match v {
+        Value::Null => Ok(BindValue::Null),
+        Value::Boolean(b) => Ok(BindValue::Bool(*b)),
+        Value::Number(n) => {
+            if let Some(i) = n.as_i64() {
+                Ok(BindValue::I64(i))
+            } else if let Some(f) = n.as_f64() {
+                Ok(BindValue::F64(f))
+            } else {
+                Err("number out of range".into())
+            }
+        }
+        Value::String(s) => match column_type {
+            ColumnType::Bytes => {
+                use base64::Engine as _;
+                base64::engine::general_purpose::STANDARD
+                    .decode(s.as_bytes())
+                    .map(BindValue::Bytes)
+                    .map_err(|e| format!("invalid base64: {e}"))
+            }
+            ColumnType::Integer | ColumnType::UnsignedInteger => s
+                .parse::<i64>()
+                .map(BindValue::I64)
+                .map_err(|_| format!("expected integer, got `{s}`")),
+            _ => Ok(BindValue::Text(s.clone())),
+        },
+        Value::List(_) | Value::Object(_) | Value::Enum(_) => {
+            let json = value_to_json(v)?;
+            Ok(BindValue::Json(json))
+        }
+        _ => Err("unsupported GraphQL value for bind".into()),
+    }
+}
+
+fn value_to_json(v: &Value) -> Result<JsonValue, String> {
+    serde_json::to_value(v).map_err(|e| e.to_string())
+}
+
+#[cfg(test)]
+mod parse_claim_tests {
+    use super::*;
+
+    #[test]
+    fn integer_claim_ok_and_fail() {
+        assert!(matches!(
+            parse_claim("42", &ColumnType::Integer).unwrap(),
+            BindValue::I64(42)
+        ));
+        assert!(parse_claim("nope", &ColumnType::Integer).is_err());
+    }
+
+    #[test]
+    fn bool_claim_variants() {
+        assert!(matches!(
+            parse_claim("true", &ColumnType::Boolean).unwrap(),
+            BindValue::Bool(true)
+        ));
+        assert!(matches!(
+            parse_claim("0", &ColumnType::Boolean).unwrap(),
+            BindValue::Bool(false)
+        ));
+        assert!(parse_claim("maybe", &ColumnType::Boolean).is_err());
+    }
+
+    #[test]
+    fn json_claim_rejected() {
+        assert!(parse_claim("{}", &ColumnType::Json).is_err());
+    }
+}
diff --git a/src/graphql/compile/dialect.rs b/src/graphql/compile/dialect.rs
new file mode 100644
index 00000000..9a239497
--- /dev/null
+++ b/src/graphql/compile/dialect.rs
@@ -0,0 +1,181 @@
+use crate::table::RelationshipKind;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum SqlDialect {
+    #[cfg_attr(not(feature = "postgres"), allow(dead_code))]
+    Postgres,
+    Sqlite,
+}
+
+/// Dialect-specific SQL fragment table (dedup-4).
+///
+/// Prefer `dialect.ops()` over ad-hoc match arms for JSON aggregate / object /
+/// empty-array / ILIKE strings.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct DialectOps {
+    pub json_agg: &'static str,
+    pub empty_array: &'static str,
+    pub build_object: &'static str,
+    /// Deterministic UTF-8 byte order shared with the generated client replica.
+    pub binary_collation: &'static str,
+    /// SQLite wraps list roots with `json(...)`; Postgres leaves this empty.
+    pub json_cast_fn: Option<&'static str>,
+    /// Case-insensitive LIKE operator (`ILIKE` on PG; `LIKE` on SQLite).
+    pub ilike_op: &'static str,
+}
+
+impl SqlDialect {
+    pub fn ops(self) -> DialectOps {
+        match self {
+            SqlDialect::Postgres => DialectOps {
+                json_agg: "jsonb_agg",
+                empty_array: "'[]'::jsonb",
+                build_object: "jsonb_build_object",
+                binary_collation: r#""C""#,
+                json_cast_fn: None,
+                ilike_op: "ILIKE",
+            },
+            SqlDialect::Sqlite => DialectOps {
+                json_agg: "json_group_array",
+                empty_array: "'[]'",
+                build_object: "json_object",
+                binary_collation: "BINARY",
+                // Ensures json_object TEXT is treated as JSON, not a JSON string.
+                json_cast_fn: Some("json"),
+                ilike_op: "LIKE",
+            },
+        }
+    }
+}
+
+pub(super) fn placeholder(dialect: SqlDialect, n: usize) -> String {
+    match dialect {
+        SqlDialect::Postgres => format!("${n}"),
+        SqlDialect::Sqlite => "?".into(),
+    }
+}
+
+/// Direct (non-m2m) join equality for HasMany / BelongsTo (dedup-2).
+///
+/// # Arguments
+/// - `fk_col`: resolved SQL column name of the foreign key
+///   (on child for HasMany, on parent for BelongsTo)
+pub(crate) fn join_predicate_direct(
+    kind: RelationshipKind,
+    parent_alias: &str,
+    child_alias: &str,
+    parent_pk: &str,
+    child_pk: &str,
+    fk_col: &str,
+) -> Result<String, String> {
+    match kind {
+        RelationshipKind::HasMany => Ok(format!(
+            "{child_alias}.\"{fk_col}\" = {parent_alias}.\"{parent_pk}\""
+        )),
+        RelationshipKind::BelongsTo => Ok(format!(
+            "{child_alias}.\"{child_pk}\" = {parent_alias}.\"{fk_col}\""
+        )),
+        RelationshipKind::ManyToMany => {
+            Err("m2m relationships use join_predicate_m2m_*, not join_predicate_direct".into())
+        }
+    }
+}
+
+/// Through-row → parent PK predicate for m2m joins.
+pub(crate) fn join_predicate_m2m_parent(
+    through_alias: &str,
+    source_join_col: &str,
+    parent_alias: &str,
+    parent_pk: &str,
+) -> String {
+    format!("{through_alias}.\"{source_join_col}\" = {parent_alias}.\"{parent_pk}\"")
+}
+
+/// Through-row → target PK ON-clause fragment for m2m joins.
+pub(crate) fn join_predicate_m2m_target(
+    through_alias: &str,
+    target_fk: &str,
+    child_alias: &str,
+    child_pk: &str,
+) -> String {
+    format!("{through_alias}.\"{target_fk}\" = {child_alias}.\"{child_pk}\"")
+}
+
+#[cfg(test)]
+mod dialect_ops_tests {
+    use super::*;
+
+    #[test]
+    fn postgres_ops_table() {
+        let ops = SqlDialect::Postgres.ops();
+        assert_eq!(ops.json_agg, "jsonb_agg");
+        assert_eq!(ops.empty_array, "'[]'::jsonb");
+        assert_eq!(ops.build_object, "jsonb_build_object");
+        assert_eq!(ops.json_cast_fn, None);
+        assert_eq!(ops.ilike_op, "ILIKE");
+        assert_eq!(placeholder(SqlDialect::Postgres, 3), "$3");
+    }
+
+    #[test]
+    fn sqlite_ops_table() {
+        let ops = SqlDialect::Sqlite.ops();
+        assert_eq!(ops.json_agg, "json_group_array");
+        assert_eq!(ops.empty_array, "'[]'");
+        assert_eq!(ops.build_object, "json_object");
+        assert_eq!(ops.json_cast_fn, Some("json"));
+        assert_eq!(ops.ilike_op, "LIKE");
+        assert_eq!(placeholder(SqlDialect::Sqlite, 1), "?");
+    }
+}
+
+#[cfg(test)]
+mod join_predicate_tests {
+    use super::*;
+
+    #[test]
+    fn has_many_join() {
+        let sql = join_predicate_direct(
+            RelationshipKind::HasMany,
+            "t0",
+            "t1",
+            "order_id",
+            "line_id",
+            "order_id",
+        )
+        .unwrap();
+        assert_eq!(sql, r#"t1."order_id" = t0."order_id""#);
+    }
+
+    #[test]
+    fn belongs_to_join() {
+        let sql = join_predicate_direct(
+            RelationshipKind::BelongsTo,
+            "t0",
+            "t1",
+            "line_id",
+            "customer_id",
+            "customer_id",
+        )
+        .unwrap();
+        assert_eq!(sql, r#"t1."customer_id" = t0."customer_id""#);
+    }
+
+    #[test]
+    fn m2m_rejects_direct_helper() {
+        let err = join_predicate_direct(RelationshipKind::ManyToMany, "t0", "t1", "a", "b", "c")
+            .unwrap_err();
+        assert!(err.contains("m2m"), "{err}");
+    }
+
+    #[test]
+    fn m2m_fragments() {
+        assert_eq!(
+            join_predicate_m2m_target("j1", "post_id", "t1", "id"),
+            r#"j1."post_id" = t1."id""#
+        );
+        assert_eq!(
+            join_predicate_m2m_parent("j1", "user_id", "t0", "id"),
+            r#"j1."user_id" = t0."id""#
+        );
+    }
+}
diff --git a/src/graphql/compile/evidence.rs b/src/graphql/compile/evidence.rs
new file mode 100644
index 00000000..7a842fd6
--- /dev/null
+++ b/src/graphql/compile/evidence.rs
@@ -0,0 +1,732 @@
+use std::collections::BTreeMap;
+
+use serde_json::Value as JsonValue;
+
+use super::super::naming::is_valid_graphql_name;
+use super::projection::validate_response_key;
+
+pub(super) const QUERY_EVIDENCE_HIDDEN_PREFIX: &str = "0__distributed_evidence_pk_";
+const MAX_QUERY_EVIDENCE_NODES: usize = 1_024;
+const MAX_QUERY_EVIDENCE_KEY_FIELDS: usize = 64;
+const MAX_QUERY_EVIDENCE_RECORDS: usize = 4_096;
+
+#[derive(Clone, Debug)]
+pub(crate) struct QueryEvidencePlan {
+    root_response_key: String,
+    root: QueryEvidenceNode,
+}
+
+#[derive(Clone, Debug)]
+pub(super) enum QueryEvidenceNode {
+    Object(QueryEvidenceObjectPlan),
+    List(Box<QueryEvidenceNode>),
+}
+
+#[derive(Clone, Debug)]
+pub(super) struct QueryEvidenceObjectPlan {
+    pub(super) record: Option<QueryEvidenceRecordPlan>,
+    pub(super) fields: Vec<QueryEvidenceFieldPlan>,
+}
+
+#[derive(Clone, Debug)]
+pub(super) struct QueryEvidenceRecordPlan {
+    pub(super) model: String,
+    pub(super) key_fields: Vec<QueryEvidenceKeyPlan>,
+}
+
+#[derive(Clone, Debug)]
+pub(super) struct QueryEvidenceKeyPlan {
+    pub(super) hidden_key: String,
+    pub(super) column: String,
+}
+
+#[derive(Clone, Debug)]
+pub(super) struct QueryEvidenceFieldPlan {
+    /// Key present in the compiler-owned SQL JSON object. Projection storage is
+    /// response-keyed so repeated selections of one schema field remain
+    /// distinct when their arguments or nested selections differ.
+    pub(super) storage_key: String,
+    /// Key emitted in the final GraphQL response and therefore used in causal
+    /// record paths.
+    pub(super) response_key: String,
+    pub(super) node: Box<QueryEvidenceNode>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) enum QueryResponsePathSegment {
+    Field(String),
+    Index(usize),
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct QueryRecordEvidence {
+    pub(crate) model: String,
+    pub(crate) key_columns: BTreeMap<String, JsonValue>,
+    pub(crate) response_path: Vec<QueryResponsePathSegment>,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct ExtractedQueryEvidence {
+    pub(crate) records: Vec<QueryRecordEvidence>,
+    /// False means the bounded collector saw more records than it can safely
+    /// retain. Hidden fields were still removed, but callers must use their
+    /// conservative causal fallback instead of partial evidence.
+    pub(crate) complete: bool,
+}
+
+#[derive(Default)]
+struct QueryEvidencePlanSize {
+    nodes: usize,
+    key_fields: usize,
+}
+
+#[derive(Default)]
+struct QueryEvidenceExtraction {
+    records: Vec<QueryRecordEvidence>,
+    records_seen: usize,
+    overflowed: bool,
+    first_error: Option<String>,
+}
+
+impl QueryEvidencePlan {
+    pub(super) fn new(root_response_key: String, root: QueryEvidenceNode) -> Result<Self, String> {
+        validate_response_key(&root_response_key)?;
+        let mut size = QueryEvidencePlanSize::default();
+        root.validate(&mut size)?;
+        Ok(Self {
+            root_response_key,
+            root,
+        })
+    }
+
+    pub(super) fn extract_and_strip(
+        &self,
+        value: &mut JsonValue,
+    ) -> Result<ExtractedQueryEvidence, String> {
+        let mut extraction = QueryEvidenceExtraction::default();
+        let mut path = vec![QueryResponsePathSegment::Field(
+            self.root_response_key.clone(),
+        )];
+        self.root.visit_and_strip(value, &mut path, &mut extraction);
+
+        if let Some(error) = extraction.first_error {
+            return Err(error);
+        }
+        if extraction.overflowed {
+            extraction.records.clear();
+        }
+        Ok(ExtractedQueryEvidence {
+            records: extraction.records,
+            complete: !extraction.overflowed,
+        })
+    }
+}
+
+impl QueryEvidenceNode {
+    fn validate(&self, size: &mut QueryEvidencePlanSize) -> Result<(), String> {
+        size.nodes = size
+            .nodes
+            .checked_add(1)
+            .ok_or_else(|| "query causal-evidence plan size overflowed".to_string())?;
+        if size.nodes > MAX_QUERY_EVIDENCE_NODES {
+            return Err(format!(
+                "query causal-evidence plan exceeds {MAX_QUERY_EVIDENCE_NODES} nodes"
+            ));
+        }
+
+        match self {
+            Self::List(item) => item.validate(size),
+            Self::Object(object) => {
+                if let Some(record) = &object.record {
+                    if record.model.trim().is_empty() || record.key_fields.is_empty() {
+                        return Err(
+                            "query causal-evidence record has no model or primary key".into()
+                        );
+                    }
+                    size.key_fields = size
+                        .key_fields
+                        .checked_add(record.key_fields.len())
+                        .ok_or_else(|| {
+                            "query causal-evidence key-field count overflowed".to_string()
+                        })?;
+                    if size.key_fields > MAX_QUERY_EVIDENCE_KEY_FIELDS {
+                        return Err(format!(
+                            "query causal-evidence plan exceeds {MAX_QUERY_EVIDENCE_KEY_FIELDS} key fields"
+                        ));
+                    }
+                    let mut hidden_keys = std::collections::BTreeSet::new();
+                    let mut columns = std::collections::BTreeSet::new();
+                    for key in &record.key_fields {
+                        if !key.hidden_key.starts_with(QUERY_EVIDENCE_HIDDEN_PREFIX)
+                            || is_valid_graphql_name(&key.hidden_key)
+                            || key.column.trim().is_empty()
+                            || !hidden_keys.insert(key.hidden_key.as_str())
+                            || !columns.insert(key.column.as_str())
+                        {
+                            return Err(
+                                "query causal-evidence record has an invalid or duplicate key field"
+                                    .into(),
+                            );
+                        }
+                    }
+                }
+
+                let mut response_keys = std::collections::BTreeSet::new();
+                for field in &object.fields {
+                    validate_response_key(&field.storage_key)?;
+                    validate_response_key(&field.response_key)?;
+                    if !response_keys.insert(field.response_key.as_str()) {
+                        return Err(format!(
+                            "query causal-evidence object repeats response key `{}`",
+                            field.response_key
+                        ));
+                    }
+                    field.node.validate(size)?;
+                }
+                Ok(())
+            }
+        }
+    }
+
+    fn visit_and_strip(
+        &self,
+        value: &mut JsonValue,
+        path: &mut Vec<QueryResponsePathSegment>,
+        extraction: &mut QueryEvidenceExtraction,
+    ) {
+        match self {
+            Self::List(item) => match value {
+                JsonValue::Null => {}
+                JsonValue::Array(items) => {
+                    for (index, value) in items.iter_mut().enumerate() {
+                        path.push(QueryResponsePathSegment::Index(index));
+                        item.visit_and_strip(value, path, extraction);
+                        path.pop();
+                    }
+                }
+                // Walk the expected item shape as a defensive cleanup even
+                // when the database returned an impossible shape.
+                other => {
+                    extraction.record_error(format!(
+                        "query causal-evidence expected a list at {}",
+                        format_response_path(path)
+                    ));
+                    item.visit_and_strip(other, path, extraction);
+                }
+            },
+            Self::Object(object) => match value {
+                JsonValue::Null => {}
+                JsonValue::Object(map) => object.visit_and_strip(map, path, extraction),
+                JsonValue::Array(items) => {
+                    extraction.record_error(format!(
+                        "query causal-evidence expected an object at {}",
+                        format_response_path(path)
+                    ));
+                    for (index, value) in items.iter_mut().enumerate() {
+                        path.push(QueryResponsePathSegment::Index(index));
+                        if let JsonValue::Object(map) = value {
+                            object.visit_and_strip(map, path, extraction);
+                        }
+                        path.pop();
+                    }
+                }
+                _ => extraction.record_error(format!(
+                    "query causal-evidence expected an object at {}",
+                    format_response_path(path)
+                )),
+            },
+        }
+    }
+}
+
+impl QueryEvidenceObjectPlan {
+    fn visit_and_strip(
+        &self,
+        map: &mut serde_json::Map<String, JsonValue>,
+        path: &mut Vec<QueryResponsePathSegment>,
+        extraction: &mut QueryEvidenceExtraction,
+    ) {
+        if let Some(record) = &self.record {
+            let mut key_columns = BTreeMap::new();
+            let mut complete_key = true;
+            for key in &record.key_fields {
+                match map.remove(&key.hidden_key) {
+                    Some(value) => {
+                        key_columns.insert(key.column.clone(), value);
+                    }
+                    None => {
+                        complete_key = false;
+                        extraction.record_error(format!(
+                            "query causal-evidence is missing key column `{}` for model `{}` at {}",
+                            key.column,
+                            record.model,
+                            format_response_path(path)
+                        ));
+                    }
+                }
+            }
+            if complete_key {
+                extraction.records_seen += 1;
+                if extraction.records_seen <= MAX_QUERY_EVIDENCE_RECORDS {
+                    extraction.records.push(QueryRecordEvidence {
+                        model: record.model.clone(),
+                        key_columns,
+                        response_path: path.clone(),
+                    });
+                } else {
+                    extraction.overflowed = true;
+                }
+            }
+        }
+
+        // A newer compiler or malformed row must not leak an unrecognized
+        // reserved alias. This only examines record/container objects selected
+        // by the evidence tree; arbitrary user JSON values are never walked.
+        let unexpected_hidden = map
+            .keys()
+            .filter(|key| key.starts_with(QUERY_EVIDENCE_HIDDEN_PREFIX))
+            .cloned()
+            .collect::<Vec<_>>();
+        for key in unexpected_hidden {
+            map.remove(&key);
+            extraction.record_error(format!(
+                "query causal-evidence contained unexpected hidden field `{key}` at {}",
+                format_response_path(path)
+            ));
+        }
+
+        for field in &self.fields {
+            path.push(QueryResponsePathSegment::Field(field.response_key.clone()));
+            match map.get_mut(&field.storage_key) {
+                Some(value) => field.node.visit_and_strip(value, path, extraction),
+                None => extraction.record_error(format!(
+                    "query causal-evidence is missing storage field `{}` for response field `{}` at {}",
+                    field.storage_key,
+                    field.response_key,
+                    format_response_path(path)
+                )),
+            }
+            path.pop();
+        }
+    }
+}
+
+impl QueryEvidenceExtraction {
+    fn record_error(&mut self, error: String) {
+        if self.first_error.is_none() {
+            self.first_error = Some(error);
+        }
+    }
+}
+
+fn format_response_path(path: &[QueryResponsePathSegment]) -> String {
+    let mut rendered = String::from("$");
+    for segment in path {
+        match segment {
+            QueryResponsePathSegment::Field(field) => {
+                rendered.push('.');
+                rendered.push_str(field);
+            }
+            QueryResponsePathSegment::Index(index) => {
+                rendered.push('[');
+                rendered.push_str(&index.to_string());
+                rendered.push(']');
+            }
+        }
+    }
+    rendered
+}
+
+#[cfg(test)]
+mod query_evidence_tests {
+    use super::super::dialect::SqlDialect;
+    use super::super::projection::{chunked_json_object, compile_record_evidence_projection};
+    use super::*;
+    use crate::graphql::permissions::read;
+    use crate::table::{ColumnType, PrimaryKey, TableColumn, TableKind, TableSchema};
+
+    fn hidden(ordinal: usize) -> String {
+        format!("{QUERY_EVIDENCE_HIDDEN_PREFIX}{ordinal}")
+    }
+
+    fn evidence_alias(response_key: &str, node: QueryEvidenceNode) -> QueryEvidenceFieldPlan {
+        QueryEvidenceFieldPlan {
+            storage_key: response_key.into(),
+            response_key: response_key.into(),
+            node: Box::new(node),
+        }
+    }
+
+    fn object_node(
+        model: Option<&str>,
+        columns: &[&str],
+        fields: Vec<QueryEvidenceFieldPlan>,
+    ) -> QueryEvidenceNode {
+        QueryEvidenceNode::Object(QueryEvidenceObjectPlan {
+            record: model.map(|model| QueryEvidenceRecordPlan {
+                model: model.into(),
+                key_fields: columns
+                    .iter()
+                    .enumerate()
+                    .map(|(ordinal, column)| QueryEvidenceKeyPlan {
+                        hidden_key: hidden(ordinal),
+                        column: (*column).into(),
+                    })
+                    .collect(),
+            }),
+            fields,
+        })
+    }
+
+    fn list_node(item: QueryEvidenceNode) -> QueryEvidenceNode {
+        QueryEvidenceNode::List(Box::new(item))
+    }
+
+    fn object(entries: impl IntoIterator<Item = (impl Into<String>, JsonValue)>) -> JsonValue {
+        JsonValue::Object(
+            entries
+                .into_iter()
+                .map(|(key, value)| (key.into(), value))
+                .collect(),
+        )
+    }
+
+    #[test]
+    fn list_evidence_tracks_aliases_nested_relationships_and_composite_keys() {
+        let comment = || object_node(Some("Comment"), &["tenant_id", "comment_id"], Vec::new());
+        let plan = QueryEvidencePlan::new(
+            "usersAlias".into(),
+            list_node(object_node(
+                Some("User"),
+                &["user_id"],
+                vec![
+                    evidence_alias(
+                        "authorAlias",
+                        object_node(Some("Profile"), &["profile_id"], Vec::new()),
+                    ),
+                    evidence_alias("commentsAlias", list_node(comment())),
+                    evidence_alias(
+                        "commentsStatsAlias",
+                        object_node(
+                            None,
+                            &[],
+                            vec![evidence_alias("rowsAlias", list_node(comment()))],
+                        ),
+                    ),
+                ],
+            )),
+        )
+        .unwrap();
+
+        let metadata = object([(hidden(0), serde_json::json!("user-owned-json"))]);
+        let author = object([
+            (hidden(0), serde_json::json!("profile-1")),
+            ("displayName".into(), serde_json::json!("Pat")),
+        ]);
+        let first_comment = object([
+            (hidden(0), serde_json::json!("tenant-1")),
+            (hidden(1), serde_json::json!("9223372036854775807")),
+            ("body".into(), serde_json::json!("first")),
+        ]);
+        let second_comment = object([
+            (hidden(0), serde_json::json!("tenant-1")),
+            (hidden(1), serde_json::json!("9223372036854775808")),
+            ("body".into(), serde_json::json!("second")),
+        ]);
+        let aggregate_comment = object([
+            (hidden(0), serde_json::json!("tenant-1")),
+            (hidden(1), serde_json::json!("AP8=")),
+            ("body".into(), serde_json::json!("aggregate")),
+        ]);
+        let mut value = JsonValue::Array(vec![object([
+            (hidden(0), serde_json::json!("user-1")),
+            ("name".into(), serde_json::json!("User One")),
+            ("metadata".into(), metadata.clone()),
+            ("authorAlias".into(), author),
+            (
+                "commentsAlias".into(),
+                JsonValue::Array(vec![first_comment, second_comment]),
+            ),
+            (
+                "commentsStatsAlias".into(),
+                object([
+                    ("aggregate", serde_json::json!({"count": 1})),
+                    ("rowsAlias", JsonValue::Array(vec![aggregate_comment])),
+                ]),
+            ),
+        ])]);
+
+        let extracted = plan.extract_and_strip(&mut value).unwrap();
+        assert!(extracted.complete);
+        assert_eq!(extracted.records.len(), 5);
+        assert_eq!(
+            extracted.records[0],
+            QueryRecordEvidence {
+                model: "User".into(),
+                key_columns: BTreeMap::from([("user_id".into(), serde_json::json!("user-1"))]),
+                response_path: vec![
+                    QueryResponsePathSegment::Field("usersAlias".into()),
+                    QueryResponsePathSegment::Index(0),
+                ],
+            }
+        );
+        assert_eq!(
+            extracted.records[2].response_path,
+            vec![
+                QueryResponsePathSegment::Field("usersAlias".into()),
+                QueryResponsePathSegment::Index(0),
+                QueryResponsePathSegment::Field("commentsAlias".into()),
+                QueryResponsePathSegment::Index(0),
+            ]
+        );
+        assert_eq!(
+            extracted.records[2].key_columns,
+            BTreeMap::from([
+                (
+                    "comment_id".into(),
+                    serde_json::json!("9223372036854775807")
+                ),
+                ("tenant_id".into(), serde_json::json!("tenant-1")),
+            ])
+        );
+        assert_eq!(
+            extracted.records[4].response_path,
+            vec![
+                QueryResponsePathSegment::Field("usersAlias".into()),
+                QueryResponsePathSegment::Index(0),
+                QueryResponsePathSegment::Field("commentsStatsAlias".into()),
+                QueryResponsePathSegment::Field("rowsAlias".into()),
+                QueryResponsePathSegment::Index(0),
+            ]
+        );
+
+        let expected = JsonValue::Array(vec![object([
+            ("name", serde_json::json!("User One")),
+            ("metadata", metadata),
+            ("authorAlias", serde_json::json!({"displayName": "Pat"})),
+            (
+                "commentsAlias",
+                serde_json::json!([
+                    {"body": "first"},
+                    {"body": "second"}
+                ]),
+            ),
+            (
+                "commentsStatsAlias",
+                serde_json::json!({
+                    "aggregate": {"count": 1},
+                    "rowsAlias": [{"body": "aggregate"}]
+                }),
+            ),
+        ])]);
+        assert_eq!(value, expected);
+        assert_eq!(
+            value[0]["metadata"][hidden(0).as_str()],
+            serde_json::json!("user-owned-json"),
+            "plan-guided stripping must not recurse into arbitrary JSON scalars"
+        );
+    }
+
+    #[test]
+    fn by_pk_evidence_uses_the_root_alias_and_null_has_no_record() {
+        let plan = QueryEvidencePlan::new(
+            "itemAlias".into(),
+            object_node(Some("Item"), &["item_id"], Vec::new()),
+        )
+        .unwrap();
+        let mut value = object([
+            (hidden(0), serde_json::json!("item-1")),
+            ("label".into(), serde_json::json!("one")),
+        ]);
+
+        let extracted = plan.extract_and_strip(&mut value).unwrap();
+        assert_eq!(
+            extracted.records[0].response_path,
+            vec![QueryResponsePathSegment::Field("itemAlias".into())]
+        );
+        assert_eq!(value, serde_json::json!({"label": "one"}));
+
+        let mut absent = JsonValue::Null;
+        let extracted = plan.extract_and_strip(&mut absent).unwrap();
+        assert!(extracted.complete);
+        assert!(extracted.records.is_empty());
+    }
+
+    #[test]
+    fn hidden_aliases_cannot_collide_and_are_stripped_on_shape_errors() {
+        assert!(!is_valid_graphql_name(&hidden(0)));
+        let plan = QueryEvidencePlan::new(
+            "items".into(),
+            list_node(object_node(Some("Item"), &["id"], Vec::new())),
+        )
+        .unwrap();
+        let unexpected = hidden(99);
+        let mut value = JsonValue::Array(vec![
+            object([
+                (hidden(0), serde_json::json!("one")),
+                (unexpected, serde_json::json!("private")),
+            ]),
+            object([("visible", serde_json::json!(true))]),
+        ]);
+
+        let error = plan.extract_and_strip(&mut value).unwrap_err();
+        assert!(error.contains("unexpected hidden field"), "{error}");
+        assert!(value[0].as_object().unwrap().is_empty());
+        assert_eq!(value[1], serde_json::json!({"visible": true}));
+        assert!(
+            !serde_json::to_string(&value)
+                .unwrap()
+                .contains(QUERY_EVIDENCE_HIDDEN_PREFIX),
+            "all record-level hidden aliases must be removed even after the first error"
+        );
+    }
+
+    #[test]
+    fn record_collection_bound_falls_back_without_disclosing_hidden_keys() {
+        let plan = QueryEvidencePlan::new(
+            "items".into(),
+            list_node(object_node(Some("Item"), &["id"], Vec::new())),
+        )
+        .unwrap();
+        let mut value = JsonValue::Array(
+            (0..=MAX_QUERY_EVIDENCE_RECORDS)
+                .map(|index| object([(hidden(0), serde_json::json!(index))]))
+                .collect(),
+        );
+
+        let extracted = plan.extract_and_strip(&mut value).unwrap();
+        assert!(!extracted.complete);
+        assert!(extracted.records.is_empty());
+        assert!(value
+            .as_array()
+            .unwrap()
+            .iter()
+            .all(|value| value.as_object().unwrap().is_empty()));
+    }
+
+    #[test]
+    fn evidence_plan_rejects_key_field_and_node_bounds() {
+        let too_many_keys = (0..=MAX_QUERY_EVIDENCE_KEY_FIELDS)
+            .map(|ordinal| format!("column_{ordinal}"))
+            .collect::<Vec<_>>();
+        let key_refs = too_many_keys.iter().map(String::as_str).collect::<Vec<_>>();
+        let error = QueryEvidencePlan::new(
+            "items".into(),
+            object_node(Some("Wide"), &key_refs, Vec::new()),
+        )
+        .unwrap_err();
+        assert!(error.contains("key fields"), "{error}");
+
+        let mut deep = object_node(None, &[], Vec::new());
+        for _ in 0..MAX_QUERY_EVIDENCE_NODES {
+            deep = list_node(deep);
+        }
+        let error = QueryEvidencePlan::new("items".into(), deep).unwrap_err();
+        assert!(error.contains("nodes"), "{error}");
+    }
+
+    #[test]
+    fn compiler_injects_lossless_private_keys_even_when_not_selected() {
+        let schema = TableSchema {
+            model_name: "Composite".into(),
+            table_name: "composites".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new("sequence", "sequence_id", ColumnType::Text)
+                },
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new("digest", "digest_bytes", ColumnType::Bytes)
+                },
+                TableColumn::new("visible", "visible", ColumnType::Text),
+            ],
+            primary_key: PrimaryKey::new(["sequence_id", "digest_bytes"]),
+            version_column: None,
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        };
+        let permission = read().all_columns();
+        let mut binds = Vec::new();
+        let mut bytes_paths = Vec::new();
+        let (pairs, record) = compile_record_evidence_projection(
+            SqlDialect::Sqlite,
+            &schema,
+            &permission,
+            "t7",
+            &mut binds,
+            &mut bytes_paths,
+            "childrenAlias",
+        )
+        .unwrap();
+
+        assert_eq!(pairs.len(), 2);
+        let record = record.expect("client-normalized identity evidence");
+        assert_eq!(record.model, "Composite");
+        assert_eq!(record.key_fields[0].column, "sequence_id");
+        assert_eq!(pairs[0].0, hidden(0));
+        assert_eq!(pairs[0].1, "t7.\"sequence_id\"");
+        assert_eq!(pairs[1].0, hidden(1));
+        assert!(pairs[1].1.contains("hex"));
+        assert_eq!(bytes_paths, vec![format!("childrenAlias.{}", hidden(1))]);
+        let sql = chunked_json_object(SqlDialect::Sqlite, &pairs);
+        assert!(sql.contains(QUERY_EVIDENCE_HIDDEN_PREFIX), "{sql}");
+        assert!(!sql.contains("'visible'"), "{sql}");
+
+        let (postgres_pairs, _) = compile_record_evidence_projection(
+            SqlDialect::Postgres,
+            &schema,
+            &permission,
+            "t7",
+            &mut Vec::new(),
+            &mut Vec::new(),
+            "",
+        )
+        .unwrap();
+        assert_eq!(postgres_pairs[0].1, "t7.\"sequence_id\"");
+        assert!(
+            postgres_pairs[1].1.contains("replace(encode(")
+                && postgres_pairs[1].1.contains("E'\\n'"),
+            "{}",
+            postgres_pairs[1].1
+        );
+    }
+
+    #[test]
+    fn embedded_client_identity_omits_record_projection_but_not_row_data() {
+        let schema = TableSchema {
+            model_name: "BigIntRecord".into(),
+            table_name: "bigint_records".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new("sequence", "sequence_id", ColumnType::UnsignedInteger)
+                },
+                TableColumn::new("visible", "visible", ColumnType::Text),
+            ],
+            primary_key: PrimaryKey::new(["sequence_id"]),
+            version_column: None,
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        };
+        let permission = read().all_columns();
+
+        let (pairs, record) = compile_record_evidence_projection(
+            SqlDialect::Sqlite,
+            &schema,
+            &permission,
+            "t0",
+            &mut Vec::new(),
+            &mut Vec::new(),
+            "",
+        )
+        .unwrap();
+
+        assert!(pairs.is_empty());
+        assert!(record.is_none());
+    }
+}
diff --git a/src/graphql/compile/filter.rs b/src/graphql/compile/filter.rs
new file mode 100644
index 00000000..dc123e3e
--- /dev/null
+++ b/src/graphql/compile/filter.rs
@@ -0,0 +1,660 @@
+use async_graphql::Value;
+
+use crate::graphql::filter::{CmpOp, FilterExpr};
+use crate::microsvc::Session;
+use crate::table::{resolve_m2m_target_foreign_key, ColumnType, RelationshipKind, TableSchema};
+
+use super::super::engine::EngineInner;
+use super::super::permissions::ReadPermission;
+use super::binds::{operand_to_bind, value_to_bind, BindValue};
+use super::dialect::{
+    join_predicate_direct, join_predicate_m2m_parent, join_predicate_m2m_target, placeholder,
+    SqlDialect,
+};
+use super::relationship::column_name_for;
+
+pub(super) fn compile_where(
+    inner: &EngineInner,
+    session: &Session,
+    role: &str,
+    schema: &TableSchema,
+    perm: &ReadPermission,
+    client_where: Option<&Value>,
+    alias: &str,
+    binds: &mut Vec<BindValue>,
+    tables: &mut Vec<String>,
+    depth: usize,
+) -> Result<String, String> {
+    if depth > inner.max_depth {
+        return Err("max depth exceeded".into());
+    }
+    let mut preds = Vec::new();
+    if let Some(filter) = &perm.row_filter {
+        preds.push(compile_filter_expr(
+            inner, session, schema, filter, alias, binds, tables, depth,
+        )?);
+    }
+    if let Some(w) = client_where {
+        preds.push(compile_client_where(
+            inner, session, role, schema, perm, w, alias, binds, tables, depth,
+        )?);
+    }
+    if preds.is_empty() {
+        Ok("TRUE".into())
+    } else {
+        Ok(preds.join(" AND "))
+    }
+}
+
+fn compile_filter_expr(
+    inner: &EngineInner,
+    session: &Session,
+    schema: &TableSchema,
+    expr: &FilterExpr,
+    alias: &str,
+    binds: &mut Vec<BindValue>,
+    tables: &mut Vec<String>,
+    depth: usize,
+) -> Result<String, String> {
+    match expr {
+        FilterExpr::And(xs) => {
+            if xs.is_empty() {
+                return Ok("TRUE".into());
+            }
+            let parts: Result<Vec<_>, _> = xs
+                .iter()
+                .map(|x| {
+                    compile_filter_expr(inner, session, schema, x, alias, binds, tables, depth + 1)
+                })
+                .collect();
+            Ok(format!("({})", parts?.join(" AND ")))
+        }
+        FilterExpr::Or(xs) => {
+            if xs.is_empty() {
+                return Ok("FALSE".into());
+            }
+            let parts: Result<Vec<_>, _> = xs
+                .iter()
+                .map(|x| {
+                    compile_filter_expr(inner, session, schema, x, alias, binds, tables, depth + 1)
+                })
+                .collect();
+            Ok(format!("({})", parts?.join(" OR ")))
+        }
+        FilterExpr::Not(x) => Ok(format!(
+            "NOT ({})",
+            compile_filter_expr(inner, session, schema, x, alias, binds, tables, depth + 1)?
+        )),
+        FilterExpr::Cmp { column, op, rhs } => {
+            let col = schema
+                .columns
+                .iter()
+                .find(|c| c.column_name == *column)
+                .ok_or_else(|| format!("unknown column `{column}`"))?;
+            let bind = operand_to_bind(rhs, session, &col.column_type)?;
+            binds.push(bind);
+            let ph = placeholder(inner.dialect, binds.len());
+            let col_ref = format!("{alias}.\"{column}\"");
+            let sql_op = match op {
+                CmpOp::Eq => "=",
+                CmpOp::Neq => "<>",
+                CmpOp::Gt => ">",
+                CmpOp::Gte => ">=",
+                CmpOp::Lt => "<",
+                CmpOp::Lte => "<=",
+                CmpOp::Like => "LIKE",
+                CmpOp::Ilike => inner.dialect.ops().ilike_op,
+                CmpOp::Contains => {
+                    require_postgres_json_op(inner.dialect, "_contains")?;
+                    "@>"
+                }
+                CmpOp::ContainedIn => {
+                    require_postgres_json_op(inner.dialect, "_contained_in")?;
+                    "<@"
+                }
+                CmpOp::HasKey => {
+                    require_postgres_json_op(inner.dialect, "_has_key")?;
+                    "?"
+                }
+            };
+            let cast_ph = cast_placeholder(inner.dialect, &col.column_type, &ph);
+            Ok(format!("{col_ref} {sql_op} {cast_ph}"))
+        }
+        FilterExpr::In {
+            column,
+            values,
+            negated,
+        } => {
+            if values.is_empty() {
+                return Ok(if *negated {
+                    "TRUE".into()
+                } else {
+                    "FALSE".into()
+                });
+            }
+            if values.len() > inner.max_in_list {
+                return Err(format!(
+                    "_in list length {} exceeds max_in_list {}",
+                    values.len(),
+                    inner.max_in_list
+                ));
+            }
+            let col = schema
+                .columns
+                .iter()
+                .find(|c| c.column_name == *column)
+                .ok_or_else(|| format!("unknown column `{column}`"))?;
+            let col_ref = format!("{alias}.\"{column}\"");
+            match inner.dialect {
+                SqlDialect::Postgres => {
+                    // Expand as IN for simplicity (array bind is dialect-specific).
+                    let mut phs = Vec::new();
+                    for v in values {
+                        let bind = operand_to_bind(v, session, &col.column_type)?;
+                        binds.push(bind);
+                        phs.push(placeholder(inner.dialect, binds.len()));
+                    }
+                    let op = if *negated { "NOT IN" } else { "IN" };
+                    Ok(format!("{col_ref} {op} ({})", phs.join(", ")))
+                }
+                SqlDialect::Sqlite => {
+                    let mut phs = Vec::new();
+                    for v in values {
+                        let bind = operand_to_bind(v, session, &col.column_type)?;
+                        binds.push(bind);
+                        phs.push(placeholder(inner.dialect, binds.len()));
+                    }
+                    let op = if *negated { "NOT IN" } else { "IN" };
+                    Ok(format!("{col_ref} {op} ({})", phs.join(", ")))
+                }
+            }
+        }
+        FilterExpr::IsNull { column, is_null } => {
+            let col_ref = format!("{alias}.\"{column}\"");
+            Ok(if *is_null {
+                format!("{col_ref} IS NULL")
+            } else {
+                format!("{col_ref} IS NOT NULL")
+            })
+        }
+        FilterExpr::Rel { field, predicate } => {
+            let rel = schema
+                .relationships
+                .iter()
+                .find(|r| r.field_name == *field)
+                .ok_or_else(|| format!("unknown relationship `{field}`"))?;
+            let target = inner
+                .catalog
+                .get(&rel.target_model)
+                .ok_or_else(|| format!("rel target `{}` not in catalog", rel.target_model))?;
+            tables.push(target.schema.table_name.clone());
+            let child_alias = format!("r{depth}");
+            let fk = rel.foreign_key.as_deref().unwrap_or("");
+            let inner_pred = compile_filter_expr(
+                inner,
+                session,
+                &target.schema,
+                predicate,
+                &child_alias,
+                binds,
+                tables,
+                depth + 1,
+            )?;
+            match rel.kind {
+                RelationshipKind::HasMany => {
+                    let target_fk = column_name_for(&target.schema, fk).unwrap_or(fk);
+                    let source_col = schema
+                        .primary_key
+                        .columns
+                        .first()
+                        .map(|s| s.as_str())
+                        .unwrap_or("id");
+                    let join_pred = join_predicate_direct(
+                        RelationshipKind::HasMany,
+                        alias,
+                        &child_alias,
+                        source_col,
+                        "",
+                        target_fk,
+                    )?;
+                    Ok(format!(
+                        "EXISTS (SELECT 1 FROM \"{}\" {child_alias} WHERE {join_pred} AND ({inner_pred}))",
+                        target.schema.table_name
+                    ))
+                }
+                RelationshipKind::BelongsTo => {
+                    let source_fk = column_name_for(schema, fk).unwrap_or(fk);
+                    let target_pk = target
+                        .schema
+                        .primary_key
+                        .columns
+                        .first()
+                        .map(|s| s.as_str())
+                        .unwrap_or("id");
+                    let join_pred = join_predicate_direct(
+                        RelationshipKind::BelongsTo,
+                        alias,
+                        &child_alias,
+                        "",
+                        target_pk,
+                        source_fk,
+                    )?;
+                    Ok(format!(
+                        "EXISTS (SELECT 1 FROM \"{}\" {child_alias} WHERE {join_pred} AND ({inner_pred}))",
+                        target.schema.table_name
+                    ))
+                }
+                RelationshipKind::ManyToMany => {
+                    let through = rel
+                        .through
+                        .as_deref()
+                        .ok_or_else(|| "m2m rel missing through".to_string())?;
+                    let through_entry = inner
+                        .by_table
+                        .get(through)
+                        .and_then(|m| inner.catalog.get(m))
+                        .ok_or_else(|| format!("through `{through}` missing"))?;
+                    let target_fk = resolve_m2m_target_foreign_key(
+                        schema,
+                        rel,
+                        &through_entry.schema,
+                        &target.schema,
+                    )
+                    .map_err(|e| e.to_string())?;
+                    let source_pk = schema
+                        .primary_key
+                        .columns
+                        .first()
+                        .map(|s| s.as_str())
+                        .unwrap_or("id");
+                    let target_pk = target
+                        .schema
+                        .primary_key
+                        .columns
+                        .first()
+                        .map(|s| s.as_str())
+                        .unwrap_or("id");
+                    let j = format!("j{depth}");
+                    let on_target =
+                        join_predicate_m2m_target(&j, &target_fk, &child_alias, target_pk);
+                    let source_join_col = column_name_for(&through_entry.schema, fk).unwrap_or(fk);
+                    let parent_pred =
+                        join_predicate_m2m_parent(&j, source_join_col, alias, source_pk);
+                    Ok(format!(
+                        "EXISTS (SELECT 1 FROM \"{through}\" {j} JOIN \"{}\" {child_alias} ON {on_target} WHERE {parent_pred} AND ({inner_pred}))",
+                        target.schema.table_name
+                    ))
+                }
+            }
+        }
+    }
+}
+
+fn compile_client_where(
+    inner: &EngineInner,
+    session: &Session,
+    role: &str,
+    schema: &TableSchema,
+    perm: &ReadPermission,
+    value: &Value,
+    alias: &str,
+    binds: &mut Vec<BindValue>,
+    tables: &mut Vec<String>,
+    depth: usize,
+) -> Result<String, String> {
+    if depth > inner.max_depth {
+        return Err("max depth exceeded".into());
+    }
+    let Value::Object(map) = value else {
+        return Ok("TRUE".into());
+    };
+    let mut preds = Vec::new();
+    for (key, val) in map {
+        match key.as_str() {
+            "_and" => {
+                if let Value::List(items) = val {
+                    if items.len() > inner.max_bool_width {
+                        return Err(format!(
+                            "_and list length {} exceeds max_bool_width {}",
+                            items.len(),
+                            inner.max_bool_width
+                        ));
+                    }
+                    for item in items {
+                        preds.push(compile_client_where(
+                            inner,
+                            session,
+                            role,
+                            schema,
+                            perm,
+                            item,
+                            alias,
+                            binds,
+                            tables,
+                            depth + 1,
+                        )?);
+                    }
+                }
+            }
+            "_or" => {
+                if let Value::List(items) = val {
+                    if items.len() > inner.max_bool_width {
+                        return Err(format!(
+                            "_or list length {} exceeds max_bool_width {}",
+                            items.len(),
+                            inner.max_bool_width
+                        ));
+                    }
+                    let mut parts = Vec::new();
+                    for item in items {
+                        parts.push(compile_client_where(
+                            inner,
+                            session,
+                            role,
+                            schema,
+                            perm,
+                            item,
+                            alias,
+                            binds,
+                            tables,
+                            depth + 1,
+                        )?);
+                    }
+                    if !parts.is_empty() {
+                        preds.push(format!("({})", parts.join(" OR ")));
+                    }
+                }
+            }
+            "_not" => {
+                preds.push(format!(
+                    "NOT ({})",
+                    compile_client_where(
+                        inner,
+                        session,
+                        role,
+                        schema,
+                        perm,
+                        val,
+                        alias,
+                        binds,
+                        tables,
+                        depth + 1,
+                    )?
+                ));
+            }
+            col_name => {
+                if let Some(col) = schema.columns.iter().find(|c| c.column_name == *col_name) {
+                    if !perm.allows_column(col_name) {
+                        if inner.strict_where {
+                            return Err(format!("ungranted where column `{col_name}`"));
+                        }
+                        continue;
+                    }
+                    if let Value::Object(ops) = val {
+                        for (op, rhs) in ops {
+                            preds.push(compile_client_op(
+                                inner,
+                                session,
+                                col_name,
+                                &col.column_type,
+                                op,
+                                rhs,
+                                alias,
+                                binds,
+                            )?);
+                        }
+                    }
+                } else if let Some(rel) = schema
+                    .relationships
+                    .iter()
+                    .find(|r| r.field_name == *col_name)
+                {
+                    // Relationship predicate → EXISTS
+                    let target = match inner.catalog.get(&rel.target_model) {
+                        Some(t) => t,
+                        None => {
+                            if inner.strict_where {
+                                return Err(format!(
+                                    "unknown where field `{col_name}` (relationship target missing)"
+                                ));
+                            }
+                            continue;
+                        }
+                    };
+                    tables.push(target.schema.table_name.clone());
+                    let target_perm = match inner
+                        .permissions
+                        .get(&(rel.target_model.clone(), role.to_string()))
+                    {
+                        Some(p) => &p.permission,
+                        None => {
+                            if inner.strict_where {
+                                return Err(format!("ungranted where relationship `{col_name}`"));
+                            }
+                            continue;
+                        }
+                    };
+                    let child_alias = format!("cw{depth}");
+                    // Entering a relationship is a new target-model access path.
+                    // Compile the complete target WHERE so its row policy cannot
+                    // be bypassed by a source-model client predicate.
+                    let inner_pred = compile_where(
+                        inner,
+                        session,
+                        role,
+                        &target.schema,
+                        target_perm,
+                        Some(val),
+                        &child_alias,
+                        binds,
+                        tables,
+                        depth + 1,
+                    )?;
+                    let fk = rel.foreign_key.as_deref().unwrap_or("");
+                    match rel.kind {
+                        RelationshipKind::HasMany => {
+                            let target_fk = column_name_for(&target.schema, fk).unwrap_or(fk);
+                            let source_col = schema
+                                .primary_key
+                                .columns
+                                .first()
+                                .map(|s| s.as_str())
+                                .unwrap_or("id");
+                            let join_pred = join_predicate_direct(
+                                RelationshipKind::HasMany,
+                                alias,
+                                &child_alias,
+                                source_col,
+                                "",
+                                target_fk,
+                            )?;
+                            preds.push(format!(
+                                "EXISTS (SELECT 1 FROM \"{}\" {child_alias} WHERE {join_pred} AND ({inner_pred}))",
+                                target.schema.table_name
+                            ));
+                        }
+                        RelationshipKind::BelongsTo => {
+                            let source_fk = column_name_for(schema, fk).unwrap_or(fk);
+                            let target_pk = target
+                                .schema
+                                .primary_key
+                                .columns
+                                .first()
+                                .map(|s| s.as_str())
+                                .unwrap_or("id");
+                            let join_pred = join_predicate_direct(
+                                RelationshipKind::BelongsTo,
+                                alias,
+                                &child_alias,
+                                "",
+                                target_pk,
+                                source_fk,
+                            )?;
+                            preds.push(format!(
+                                "EXISTS (SELECT 1 FROM \"{}\" {child_alias} WHERE {join_pred} AND ({inner_pred}))",
+                                target.schema.table_name
+                            ));
+                        }
+                        RelationshipKind::ManyToMany => {
+                            let through = rel
+                                .through
+                                .as_deref()
+                                .ok_or_else(|| "m2m rel missing through".to_string())?;
+                            let through_entry = inner
+                                .by_table
+                                .get(through)
+                                .and_then(|m| inner.catalog.get(m))
+                                .ok_or_else(|| format!("through `{through}` missing"))?;
+                            let target_fk = resolve_m2m_target_foreign_key(
+                                schema,
+                                rel,
+                                &through_entry.schema,
+                                &target.schema,
+                            )
+                            .map_err(|e| e.to_string())?;
+                            let source_join_col =
+                                column_name_for(&through_entry.schema, fk).unwrap_or(fk);
+                            let source_pk = schema
+                                .primary_key
+                                .columns
+                                .first()
+                                .map(|s| s.as_str())
+                                .unwrap_or("id");
+                            let target_pk = target
+                                .schema
+                                .primary_key
+                                .columns
+                                .first()
+                                .map(|s| s.as_str())
+                                .unwrap_or("id");
+                            let join_alias = format!("cwj{depth}");
+                            tables.push(through.to_string());
+                            let on_target = join_predicate_m2m_target(
+                                &join_alias,
+                                &target_fk,
+                                &child_alias,
+                                target_pk,
+                            );
+                            let parent_pred = join_predicate_m2m_parent(
+                                &join_alias,
+                                source_join_col,
+                                alias,
+                                source_pk,
+                            );
+                            preds.push(format!(
+                                "EXISTS (SELECT 1 FROM \"{through}\" {join_alias} JOIN \"{}\" {child_alias} ON {on_target} WHERE {parent_pred} AND ({inner_pred}))",
+                                target.schema.table_name
+                            ));
+                        }
+                    }
+                } else if inner.strict_where {
+                    return Err(format!("unknown where field `{col_name}`"));
+                }
+                // soft-skip: ignore unknown keys when strict_where is false
+            }
+        }
+    }
+    if preds.is_empty() {
+        Ok("TRUE".into())
+    } else {
+        Ok(format!("({})", preds.join(" AND ")))
+    }
+}
+
+fn compile_client_op(
+    inner: &EngineInner,
+    _session: &Session,
+    column: &str,
+    column_type: &ColumnType,
+    op: &str,
+    rhs: &Value,
+    alias: &str,
+    binds: &mut Vec<BindValue>,
+) -> Result<String, String> {
+    let col_ref = format!("{alias}.\"{column}\"");
+    match op {
+        "_is_null" => {
+            let yes = matches!(rhs, Value::Boolean(true));
+            Ok(if yes {
+                format!("{col_ref} IS NULL")
+            } else {
+                format!("{col_ref} IS NOT NULL")
+            })
+        }
+        "_in" | "_nin" => {
+            let Value::List(items) = rhs else {
+                return Err(format!("{op} requires a list"));
+            };
+            if items.is_empty() {
+                return Ok(if op == "_in" {
+                    "FALSE".into()
+                } else {
+                    "TRUE".into()
+                });
+            }
+            if items.len() > inner.max_in_list {
+                return Err(format!(
+                    "{op} list length {} exceeds max_in_list {}",
+                    items.len(),
+                    inner.max_in_list
+                ));
+            }
+            let mut phs = Vec::new();
+            for item in items {
+                binds.push(value_to_bind(item, column_type)?);
+                phs.push(placeholder(inner.dialect, binds.len()));
+            }
+            let sql_op = if op == "_in" { "IN" } else { "NOT IN" };
+            Ok(format!("{col_ref} {sql_op} ({})", phs.join(", ")))
+        }
+        other => {
+            let sql_op = match other {
+                "_eq" => "=",
+                "_neq" => "<>",
+                "_gt" => ">",
+                "_gte" => ">=",
+                "_lt" => "<",
+                "_lte" => "<=",
+                "_like" => "LIKE",
+                "_ilike" => inner.dialect.ops().ilike_op,
+                "_contains" => {
+                    require_postgres_json_op(inner.dialect, "_contains")?;
+                    "@>"
+                }
+                "_contained_in" => {
+                    require_postgres_json_op(inner.dialect, "_contained_in")?;
+                    "<@"
+                }
+                "_has_key" => {
+                    require_postgres_json_op(inner.dialect, "_has_key")?;
+                    "?"
+                }
+                _ => return Err(format!("unknown comparison op `{other}`")),
+            };
+            binds.push(value_to_bind(rhs, column_type)?);
+            let ph = placeholder(inner.dialect, binds.len());
+            let cast_ph = cast_placeholder(inner.dialect, column_type, &ph);
+            Ok(format!("{col_ref} {sql_op} {cast_ph}"))
+        }
+    }
+}
+
+/// Postgres jsonb operators are not emitted on SQLite (would confuse the driver
+/// and risk opaque execute errors). Message must stay free of SQL fragments so
+/// [`super::schema::sanitize_compile_error`] maps to a stable client code.
+fn require_postgres_json_op(dialect: SqlDialect, op: &str) -> Result<(), String> {
+    match dialect {
+        SqlDialect::Postgres => Ok(()),
+        SqlDialect::Sqlite => Err(format!(
+            "unknown comparison op `{op}` is not supported on sqlite"
+        )),
+    }
+}
+
+fn cast_placeholder(dialect: SqlDialect, column_type: &ColumnType, ph: &str) -> String {
+    match (dialect, column_type) {
+        (SqlDialect::Postgres, ColumnType::Timestamp) => format!("{ph}::timestamptz"),
+        (SqlDialect::Postgres, ColumnType::Json) => format!("{ph}::jsonb"),
+        _ => ph.to_string(),
+    }
+}
diff --git a/src/graphql/compile/mod.rs b/src/graphql/compile/mod.rs
new file mode 100644
index 00000000..86361afb
--- /dev/null
+++ b/src/graphql/compile/mod.rs
@@ -0,0 +1,38 @@
+//! Selection set -> single SQL statement per root field (dialect-portable JSON tree).
+//!
+//! # v1 join / PK assumptions
+//!
+//! Relationship SQL assumes **single-column primary keys** and a single
+//! `foreign_key` column per relationship:
+//! - **HasMany**: FK lives on the child -> `child.fk = parent.pk`
+//! - **BelongsTo**: FK lives on the parent -> `child.pk = parent.fk`
+//! - **ManyToMany**: through-table holds both FKs; join helpers emit
+//!   through->target ON + through->parent WHERE fragments
+//!
+//! Multi-column PKs/FKs are out of scope until a dedicated policy task lands
+//! (see maintain-3 / maintain-5). Join equality is centralized in
+//! [`join_predicate_direct`] / [`join_predicate_m2m_parent`] /
+//! [`join_predicate_m2m_target`]. Dialect SQL fragments live on [`DialectOps`].
+#![allow(clippy::only_used_in_recursion, clippy::too_many_arguments)]
+
+mod binds;
+mod dialect;
+mod evidence;
+mod filter;
+mod projection;
+mod relationship;
+
+pub use binds::BindValue;
+#[allow(unused_imports)]
+pub use dialect::{DialectOps, SqlDialect};
+#[allow(unused_imports)]
+pub use projection::{
+    compile_list_sql_for_test, compile_root, selection_from_field, RootKind, SelectionNode, SqlPlan,
+};
+
+#[allow(unused_imports)]
+pub(crate) use dialect::{
+    join_predicate_direct, join_predicate_m2m_parent, join_predicate_m2m_target,
+};
+#[allow(unused_imports)]
+pub(crate) use evidence::{ExtractedQueryEvidence, QueryRecordEvidence, QueryResponsePathSegment};
diff --git a/src/graphql/compile/projection.rs b/src/graphql/compile/projection.rs
new file mode 100644
index 00000000..8e7b9fcf
--- /dev/null
+++ b/src/graphql/compile/projection.rs
@@ -0,0 +1,1036 @@
+use std::collections::BTreeMap;
+
+use async_graphql::Value;
+use serde_json::Value as JsonValue;
+
+use crate::microsvc::Session;
+use crate::table::{ColumnType, TableSchema};
+
+use super::super::engine::EngineInner;
+use super::super::naming::{is_valid_graphql_name, scalar_type_name};
+use super::super::permissions::ReadPermission;
+use super::binds::{value_to_bind, BindValue};
+use super::dialect::{placeholder, SqlDialect};
+use super::evidence::{
+    ExtractedQueryEvidence, QueryEvidenceFieldPlan, QueryEvidenceKeyPlan, QueryEvidenceNode,
+    QueryEvidenceObjectPlan, QueryEvidencePlan, QueryEvidenceRecordPlan,
+    QUERY_EVIDENCE_HIDDEN_PREFIX,
+};
+use super::filter::compile_where;
+use super::relationship::{compile_relationship_aggregate_subquery, compile_relationship_subquery};
+
+#[derive(Clone, Debug)]
+pub struct SqlPlan {
+    pub sql: String,
+    pub binds: Vec<BindValue>,
+    /// JSON paths (dot-separated response keys) that need hex→base64 rewrite (SQLite Bytes).
+    pub bytes_hex_paths: Vec<String>,
+    pub tables_touched: Vec<String>,
+    /// Compiler-owned shape for recovering every causal row identity. The
+    /// hidden SQL aliases it describes are stripped before GraphQL sees data.
+    pub(crate) evidence: QueryEvidencePlan,
+}
+
+impl SqlPlan {
+    /// Recover complete physical keys and remove all compiler-only aliases.
+    ///
+    /// Call this after dialect JSON normalization (including SQLite's
+    /// hex-to-base64 rewrite) and before converting to an async-graphql value.
+    /// Shape errors still perform every safe, plan-guided removal so internal
+    /// identity fields are never disclosed through an error path.
+    pub(crate) fn extract_evidence_and_strip(
+        &self,
+        value: &mut JsonValue,
+    ) -> Result<ExtractedQueryEvidence, String> {
+        self.evidence.extract_and_strip(value)
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct SelectionNode {
+    pub response_key: String,
+    pub field_name: String,
+    pub args: BTreeMap<String, Value>,
+    pub children: Vec<SelectionNode>,
+}
+
+/// Compile a root field selection into one SQL statement.
+pub fn compile_root(
+    inner: &EngineInner,
+    session: &Session,
+    role: &str,
+    model_name: &str,
+    kind: RootKind,
+    selection: &SelectionNode,
+) -> Result<SqlPlan, String> {
+    // Relationship-aware complexity before SQL (covers query + subscription paths).
+    let cost =
+        super::super::complexity::estimate_root_complexity(inner, model_name, kind, selection)?;
+    if super::super::complexity::exceeds_budget(cost, inner.max_complexity) {
+        return Err(format!(
+            "query too complex (estimated {cost}, max {})",
+            inner.max_complexity
+        ));
+    }
+
+    let entry = inner
+        .catalog
+        .get(model_name)
+        .ok_or_else(|| format!("unknown model `{model_name}`"))?;
+    let perm = inner
+        .permissions
+        .get(&(model_name.to_string(), role.to_string()))
+        .map(|p| &p.permission)
+        .ok_or_else(|| format!("role `{role}` has no permission on `{model_name}`"))?;
+
+    let mut binds = Vec::new();
+    let mut bytes_paths = Vec::new();
+    let mut tables = vec![entry.schema.table_name.clone()];
+    let alias = "t0";
+
+    let limit = resolve_limit(
+        selection.args.get("limit"),
+        perm.limit,
+        inner.default_limit,
+        inner.max_limit,
+    );
+    let offset = selection
+        .args
+        .get("offset")
+        .and_then(value_as_u64)
+        .unwrap_or(0);
+
+    let order_sql = compile_order_by(
+        &entry.schema,
+        selection.args.get("order_by"),
+        alias,
+        perm,
+        inner.strict_where,
+        inner.dialect,
+    )?;
+
+    let ops = inner.dialect.ops();
+
+    let (sql, evidence_root) = match kind {
+        RootKind::List => {
+            let (projection, object_evidence) = compile_object_projection(
+                inner,
+                session,
+                role,
+                &entry.schema,
+                perm,
+                selection,
+                alias,
+                &mut binds,
+                &mut bytes_paths,
+                &mut tables,
+                "",
+                0,
+            )?;
+            let where_sql = compile_where(
+                inner,
+                session,
+                role,
+                &entry.schema,
+                perm,
+                selection.args.get("where"),
+                alias,
+                &mut binds,
+                &mut tables,
+                0,
+            )?;
+            let json_agg = ops.json_agg;
+            let coalesce_empty = ops.empty_array;
+            let agg_arg = match ops.json_cast_fn {
+                None => "root".to_string(),
+                Some(f) => format!("{f}(root)"),
+            };
+            (
+                format!(
+                    "SELECT coalesce({json_agg}({agg_arg}), {coalesce_empty}) FROM (\n  SELECT {projection} AS root\n  FROM \"{}\" {alias}\n  WHERE {where_sql}\n  {order_sql}\n  LIMIT {} OFFSET {}\n) sub",
+                    entry.schema.table_name,
+                    {
+                        binds.push(BindValue::I64(limit as i64));
+                        placeholder(inner.dialect, binds.len())
+                    },
+                    {
+                        binds.push(BindValue::I64(offset as i64));
+                        placeholder(inner.dialect, binds.len())
+                    }
+                ),
+                QueryEvidenceNode::List(Box::new(QueryEvidenceNode::Object(object_evidence))),
+            )
+        }
+        RootKind::ByPk => {
+            // Projection first: nested has_many/m2m subqueries emit LIMIT/OFFSET
+            // `?` binds that appear in the SELECT text *before* the outer WHERE.
+            // SQLite binds are positional, so PK + filter binds must be pushed
+            // after projection binds (same order as `?` appearance in SQL).
+            let (projection, object_evidence) = compile_object_projection(
+                inner,
+                session,
+                role,
+                &entry.schema,
+                perm,
+                selection,
+                alias,
+                &mut binds,
+                &mut bytes_paths,
+                &mut tables,
+                "",
+                0,
+            )?;
+            let mut pk_preds = Vec::new();
+            for pk in &entry.schema.primary_key.columns {
+                let v = selection
+                    .args
+                    .get(pk)
+                    .ok_or_else(|| format!("missing primary key argument `{pk}`"))?;
+                let col = entry
+                    .schema
+                    .columns
+                    .iter()
+                    .find(|c| c.column_name == *pk)
+                    .ok_or_else(|| format!("pk column `{pk}` missing"))?;
+                let bind = value_to_bind(v, &col.column_type)?;
+                binds.push(bind);
+                let ph = placeholder(inner.dialect, binds.len());
+                pk_preds.push(format!("{alias}.\"{pk}\" = {ph}"));
+            }
+            let where_sql = compile_where(
+                inner,
+                session,
+                role,
+                &entry.schema,
+                perm,
+                selection.args.get("where"),
+                alias,
+                &mut binds,
+                &mut tables,
+                0,
+            )?;
+            let pk_where = pk_preds.join(" AND ");
+            let full_where = if where_sql == "TRUE" || where_sql == "true" {
+                pk_where
+            } else {
+                format!("({pk_where}) AND ({where_sql})")
+            };
+            (
+                format!(
+                    "SELECT {projection} FROM \"{}\" {alias} WHERE {full_where} LIMIT 1",
+                    entry.schema.table_name
+                ),
+                QueryEvidenceNode::Object(object_evidence),
+            )
+        }
+        RootKind::Aggregate => {
+            let json_agg = ops.json_agg;
+            let coalesce_empty = ops.empty_array;
+            let table = entry.schema.table_name.as_str();
+            let mut pairs = Vec::new();
+            let mut evidence_fields = Vec::new();
+            for aggregate_member in &selection.children {
+                match aggregate_member.field_name.as_str() {
+                    "__typename" => {}
+                    "aggregate" => {
+                        validate_response_key(&aggregate_member.response_key)?;
+                        let mut aggregate_pairs = Vec::new();
+                        for metric in &aggregate_member.children {
+                            match metric.field_name.as_str() {
+                                "__typename" => {}
+                                "count" => {
+                                    validate_response_key(&metric.response_key)?;
+                                    let where_for_count = compile_where(
+                                        inner,
+                                        session,
+                                        role,
+                                        &entry.schema,
+                                        perm,
+                                        selection.args.get("where"),
+                                        alias,
+                                        &mut binds,
+                                        &mut tables,
+                                        0,
+                                    )?;
+                                    aggregate_pairs.push((
+                                        metric.response_key.clone(),
+                                        format!(
+                                            "(SELECT count(*) FROM \"{table}\" {alias} WHERE {where_for_count})"
+                                        ),
+                                    ));
+                                }
+                                _ => {
+                                    return Err(
+                                        "aggregate fields selection contains an unsupported member"
+                                            .into(),
+                                    );
+                                }
+                            }
+                        }
+                        pairs.push((
+                            aggregate_member.response_key.clone(),
+                            chunked_json_object(inner.dialect, &aggregate_pairs),
+                        ));
+                    }
+                    "nodes" => {
+                        validate_response_key(&aggregate_member.response_key)?;
+                        let nodes_path = aggregate_member.response_key.as_str();
+                        let (nodes_proj, nodes_evidence) = compile_object_projection(
+                            inner,
+                            session,
+                            role,
+                            &entry.schema,
+                            perm,
+                            aggregate_member,
+                            alias,
+                            &mut binds,
+                            &mut bytes_paths,
+                            &mut tables,
+                            nodes_path,
+                            0,
+                        )?;
+                        let where_for_nodes = compile_where(
+                            inner,
+                            session,
+                            role,
+                            &entry.schema,
+                            perm,
+                            selection.args.get("where"),
+                            alias,
+                            &mut binds,
+                            &mut tables,
+                            0,
+                        )?;
+                        let lim = {
+                            binds.push(BindValue::I64(limit as i64));
+                            placeholder(inner.dialect, binds.len())
+                        };
+                        let off = {
+                            binds.push(BindValue::I64(offset as i64));
+                            placeholder(inner.dialect, binds.len())
+                        };
+                        pairs.push((
+                            aggregate_member.response_key.clone(),
+                            format!(
+                                "coalesce((SELECT {json_agg}(n) FROM (SELECT {nodes_proj} AS n FROM \"{table}\" {alias} WHERE {where_for_nodes} {order_sql} LIMIT {lim} OFFSET {off}) x), {coalesce_empty})"
+                            ),
+                        ));
+                        evidence_fields.push(QueryEvidenceFieldPlan {
+                            storage_key: aggregate_member.response_key.clone(),
+                            response_key: aggregate_member.response_key.clone(),
+                            node: Box::new(QueryEvidenceNode::List(Box::new(
+                                QueryEvidenceNode::Object(nodes_evidence),
+                            ))),
+                        });
+                    }
+                    _ => {
+                        return Err("aggregate selection contains an unsupported member".into());
+                    }
+                }
+            }
+
+            (
+                format!("SELECT {}", chunked_json_object(inner.dialect, &pairs)),
+                QueryEvidenceNode::Object(QueryEvidenceObjectPlan {
+                    record: None,
+                    fields: evidence_fields,
+                }),
+            )
+        }
+    };
+    let evidence = QueryEvidencePlan::new(selection.response_key.clone(), evidence_root)?;
+
+    Ok(SqlPlan {
+        sql,
+        binds,
+        bytes_hex_paths: bytes_paths,
+        tables_touched: tables,
+        evidence,
+    })
+}
+
+#[derive(Clone, Copy)]
+pub enum RootKind {
+    List,
+    ByPk,
+    Aggregate,
+}
+
+pub(super) fn validate_response_key(key: &str) -> Result<(), String> {
+    if is_valid_graphql_name(key) {
+        Ok(())
+    } else {
+        Err(format!("invalid GraphQL response key `{key}`"))
+    }
+}
+
+pub(super) fn resolve_limit(
+    client: Option<&Value>,
+    role_limit: Option<u64>,
+    default_limit: u64,
+    max_limit: u64,
+) -> u64 {
+    let client = client.and_then(value_as_u64).unwrap_or(default_limit);
+    let with_role = role_limit.map(|r| client.min(r)).unwrap_or(client);
+    with_role.min(max_limit)
+}
+
+pub(super) fn value_as_u64(v: &Value) -> Option<u64> {
+    match v {
+        Value::Number(n) => n
+            .as_u64()
+            .or_else(|| n.as_i64().and_then(|i| u64::try_from(i).ok())),
+        _ => None,
+    }
+}
+
+pub(super) fn compile_object_projection(
+    inner: &EngineInner,
+    session: &Session,
+    role: &str,
+    schema: &TableSchema,
+    perm: &ReadPermission,
+    selection: &SelectionNode,
+    alias: &str,
+    binds: &mut Vec<BindValue>,
+    bytes_paths: &mut Vec<String>,
+    tables: &mut Vec<String>,
+    path_prefix: &str,
+    depth: usize,
+) -> Result<(String, QueryEvidenceObjectPlan), String> {
+    if depth > inner.max_depth {
+        return Err("max depth exceeded".into());
+    }
+    let (mut pairs, record) = compile_record_evidence_projection(
+        inner.dialect,
+        schema,
+        perm,
+        alias,
+        binds,
+        bytes_paths,
+        path_prefix,
+    )?;
+    let mut evidence_fields = Vec::new();
+
+    // If no children, project all allowed columns.
+    let fields: Vec<&SelectionNode> = if selection.children.is_empty() {
+        Vec::new()
+    } else {
+        selection.children.iter().collect()
+    };
+
+    if fields.is_empty() {
+        for col in schema.columns.iter().filter(|c| !c.skipped) {
+            if !perm.allows_column(&col.column_name) {
+                continue;
+            }
+            let expr = column_json_expr(inner.dialect, alias, col, binds)?;
+            if matches!(col.column_type, ColumnType::Bytes)
+                && matches!(inner.dialect, SqlDialect::Sqlite)
+            {
+                let p = if path_prefix.is_empty() {
+                    col.column_name.clone()
+                } else {
+                    format!("{path_prefix}.{}", col.column_name)
+                };
+                bytes_paths.push(p);
+            }
+            validate_response_key(&col.column_name)?;
+            pairs.push((col.column_name.clone(), expr));
+        }
+    } else {
+        for child in fields {
+            if let Some(rel_name) = child.field_name.strip_suffix("_aggregate") {
+                if let Some(rel) = schema
+                    .relationships
+                    .iter()
+                    .find(|r| r.field_name == rel_name)
+                {
+                    let target_entry = match inner.catalog.get(&rel.target_model) {
+                        Some(e) => e,
+                        None => continue,
+                    };
+                    let target_perm = match inner
+                        .permissions
+                        .get(&(rel.target_model.clone(), role.to_string()))
+                    {
+                        Some(p) if p.permission.aggregations => &p.permission,
+                        _ => continue,
+                    };
+                    tables.push(target_entry.schema.table_name.clone());
+                    let child_path = if path_prefix.is_empty() {
+                        child.response_key.clone()
+                    } else {
+                        format!("{path_prefix}.{}", child.response_key)
+                    };
+                    let (sub, evidence_node) = compile_relationship_aggregate_subquery(
+                        inner,
+                        session,
+                        role,
+                        schema,
+                        alias,
+                        rel,
+                        target_entry,
+                        target_perm,
+                        child,
+                        binds,
+                        bytes_paths,
+                        tables,
+                        &child_path,
+                        depth + 1,
+                    )?;
+                    validate_response_key(&child.response_key)?;
+                    pairs.push((child.response_key.clone(), sub));
+                    evidence_fields.push(QueryEvidenceFieldPlan {
+                        storage_key: child.response_key.clone(),
+                        response_key: child.response_key.clone(),
+                        node: Box::new(evidence_node),
+                    });
+                }
+                continue;
+            }
+            if let Some(col) = schema
+                .columns
+                .iter()
+                .find(|c| c.column_name == child.field_name && !c.skipped)
+            {
+                if !perm.allows_column(&col.column_name) {
+                    continue;
+                }
+                let expr = column_json_expr(inner.dialect, alias, col, binds)?;
+                if matches!(col.column_type, ColumnType::Bytes)
+                    && matches!(inner.dialect, SqlDialect::Sqlite)
+                {
+                    let p = if path_prefix.is_empty() {
+                        child.response_key.clone()
+                    } else {
+                        format!("{path_prefix}.{}", child.response_key)
+                    };
+                    bytes_paths.push(p);
+                }
+                validate_response_key(&child.response_key)?;
+                pairs.push((child.response_key.clone(), expr));
+                continue;
+            }
+            if let Some(rel) = schema
+                .relationships
+                .iter()
+                .find(|r| r.field_name == child.field_name)
+            {
+                let target_entry = match inner.catalog.get(&rel.target_model) {
+                    Some(e) => e,
+                    None => continue,
+                };
+                let target_perm = match inner
+                    .permissions
+                    .get(&(rel.target_model.clone(), role.to_string()))
+                {
+                    Some(p) => &p.permission,
+                    None => continue, // untracked for role
+                };
+                tables.push(target_entry.schema.table_name.clone());
+                let child_path = if path_prefix.is_empty() {
+                    child.response_key.clone()
+                } else {
+                    format!("{path_prefix}.{}", child.response_key)
+                };
+                let (sub, evidence_node) = compile_relationship_subquery(
+                    inner,
+                    session,
+                    role,
+                    schema,
+                    alias,
+                    rel,
+                    target_entry,
+                    target_perm,
+                    child,
+                    binds,
+                    bytes_paths,
+                    tables,
+                    &child_path,
+                    depth + 1,
+                )?;
+                validate_response_key(&child.response_key)?;
+                pairs.push((child.response_key.clone(), sub));
+                evidence_fields.push(QueryEvidenceFieldPlan {
+                    storage_key: child.response_key.clone(),
+                    response_key: child.response_key.clone(),
+                    node: Box::new(evidence_node),
+                });
+            }
+        }
+    }
+
+    Ok((
+        chunked_json_object(inner.dialect, &pairs),
+        QueryEvidenceObjectPlan {
+            record,
+            fields: evidence_fields,
+        },
+    ))
+}
+
+pub(super) fn compile_record_evidence_projection(
+    dialect: SqlDialect,
+    schema: &TableSchema,
+    perm: &ReadPermission,
+    alias: &str,
+    binds: &mut Vec<BindValue>,
+    bytes_paths: &mut Vec<String>,
+    path_prefix: &str,
+) -> Result<(Vec<(String, String)>, Option<QueryEvidenceRecordPlan>), String> {
+    // Embedded client models deliberately have no stable normalized identity.
+    // Do not manufacture per-record evidence that the client cannot address;
+    // table/projector dependencies still flow through `tables_touched` and
+    // produce conservative index evidence.
+    if !has_client_normalized_identity(schema, perm) {
+        return Ok((Vec::new(), None));
+    }
+
+    let mut pairs = Vec::with_capacity(schema.primary_key.columns.len());
+    let mut key_fields = Vec::with_capacity(schema.primary_key.columns.len());
+
+    for (ordinal, column_name) in schema.primary_key.columns.iter().enumerate() {
+        let column = schema
+            .columns
+            .iter()
+            .find(|column| column.column_name == *column_name)
+            .ok_or_else(|| {
+                format!(
+                    "primary key column `{column_name}` missing from model `{}`",
+                    schema.model_name
+                )
+            })?;
+        let hidden_key = format!("{QUERY_EVIDENCE_HIDDEN_PREFIX}{ordinal}");
+        debug_assert!(!is_valid_graphql_name(&hidden_key));
+
+        // GraphQL BigInt uses decimal strings. Casting the private identity
+        // copy avoids any JSON-number precision loss while leaving the visible
+        // field's legacy representation unchanged.
+        let expression = match (&column.column_type, dialect) {
+            (ColumnType::Integer | ColumnType::UnsignedInteger, SqlDialect::Postgres) => {
+                format!("{alias}.\"{}\"::text", column.column_name)
+            }
+            (ColumnType::Integer | ColumnType::UnsignedInteger, SqlDialect::Sqlite) => {
+                format!("CAST({alias}.\"{}\" AS TEXT)", column.column_name)
+            }
+            // PostgreSQL's MIME-style base64 encoder inserts line breaks for
+            // long values. Evidence uses canonical RFC 4648 text so the scope
+            // codec can reject ambiguous spellings without rejecting valid
+            // byte primary keys.
+            (ColumnType::Bytes, SqlDialect::Postgres) => format!(
+                "replace(encode({alias}.\"{}\", 'base64'), E'\\n', '')",
+                column.column_name
+            ),
+            _ => column_json_expr(dialect, alias, column, binds)?,
+        };
+        if matches!(column.column_type, ColumnType::Bytes) && matches!(dialect, SqlDialect::Sqlite)
+        {
+            bytes_paths.push(if path_prefix.is_empty() {
+                hidden_key.clone()
+            } else {
+                format!("{path_prefix}.{hidden_key}")
+            });
+        }
+        pairs.push((hidden_key.clone(), expression));
+        key_fields.push(QueryEvidenceKeyPlan {
+            hidden_key,
+            column: column.column_name.clone(),
+        });
+    }
+
+    Ok((
+        pairs,
+        Some(QueryEvidenceRecordPlan {
+            model: schema.model_name.clone(),
+            key_fields,
+        }),
+    ))
+}
+
+fn has_client_normalized_identity(schema: &TableSchema, perm: &ReadPermission) -> bool {
+    !schema.primary_key.columns.is_empty()
+        && schema.primary_key.columns.iter().all(|key| {
+            schema
+                .columns
+                .iter()
+                .find(|column| column.column_name == *key)
+                .is_some_and(|column| {
+                    !column.skipped
+                        && !column.nullable
+                        && perm.allows_column(key)
+                        && scalar_type_name(&column.column_type)
+                            .is_some_and(|scalar| scalar != "BigInt")
+                })
+        })
+}
+
+pub(super) fn column_json_expr(
+    dialect: SqlDialect,
+    alias: &str,
+    col: &crate::table::TableColumn,
+    _binds: &mut Vec<BindValue>,
+) -> Result<String, String> {
+    let q = format!("{alias}.\"{}\"", col.column_name);
+    Ok(match (&col.column_type, dialect) {
+        (ColumnType::Timestamp, SqlDialect::Postgres) => format!("{q}::text"),
+        (ColumnType::Bytes, SqlDialect::Postgres) => format!("encode({q}, 'base64')"),
+        (ColumnType::Bytes, SqlDialect::Sqlite) => format!("hex({q})"),
+        (ColumnType::Json, SqlDialect::Postgres) => q.to_string(),
+        _ => q,
+    })
+}
+
+pub(super) fn chunked_json_object(dialect: SqlDialect, pairs: &[(String, String)]) -> String {
+    let build = dialect.ops().build_object;
+    if pairs.is_empty() {
+        return format!("{build}()");
+    }
+    let chunks: Vec<&[(String, String)]> = pairs.chunks(40).collect();
+    if chunks.len() == 1 {
+        return format!(
+            "{build}({})",
+            pairs
+                .iter()
+                .map(|(k, v)| format!("'{k}', {v}"))
+                .collect::<Vec<_>>()
+                .join(", ")
+        );
+    }
+    match dialect {
+        SqlDialect::Postgres => {
+            let parts: Vec<String> = chunks
+                .iter()
+                .map(|chunk| {
+                    format!(
+                        "{build}({})",
+                        chunk
+                            .iter()
+                            .map(|(k, v)| format!("'{k}', {v}"))
+                            .collect::<Vec<_>>()
+                            .join(", ")
+                    )
+                })
+                .collect();
+            parts.join(" || ")
+        }
+        SqlDialect::Sqlite => {
+            // Nested json_insert
+            let mut expr = format!(
+                "{build}({})",
+                chunks[0]
+                    .iter()
+                    .map(|(k, v)| format!("'{k}', {v}"))
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            );
+            for chunk in chunks.iter().skip(1) {
+                let inserts = chunk
+                    .iter()
+                    .map(|(k, v)| format!("'$.{k}', {v}"))
+                    .collect::<Vec<_>>()
+                    .join(", ");
+                expr = format!("json_insert({expr}, {inserts})");
+            }
+            expr
+        }
+    }
+}
+
+pub(super) fn compile_order_by(
+    schema: &TableSchema,
+    order_arg: Option<&Value>,
+    alias: &str,
+    perm: &ReadPermission,
+    strict: bool,
+    dialect: SqlDialect,
+) -> Result<String, String> {
+    let mut parts = Vec::new();
+    if let Some(Value::List(items)) = order_arg {
+        for item in items {
+            if let Value::Object(map) = item {
+                if map.len() > 1 {
+                    return Err(
+                        "ambiguous order_by entry: use one field per list entry to declare priority"
+                            .into(),
+                    );
+                }
+                for (col, dir) in map {
+                    if !schema.columns.iter().any(|c| c.column_name == *col) {
+                        if strict {
+                            return Err(format!("unknown order_by column `{col}`"));
+                        }
+                        continue;
+                    }
+                    if !perm.allows_column(col) {
+                        if strict {
+                            return Err(format!("ungranted order_by column `{col}`"));
+                        }
+                        continue;
+                    }
+                    let dir_s = match dir {
+                        Value::Enum(e) => e.as_str(),
+                        Value::String(s) => s.as_str(),
+                        _ => "asc",
+                    };
+                    let sql_dir = match dir_s {
+                        "desc" | "desc_nulls_first" | "desc_nulls_last" => "DESC",
+                        _ => "ASC",
+                    };
+                    let nulls = match dir_s {
+                        "asc_nulls_first" | "desc_nulls_first" => " NULLS FIRST",
+                        "asc_nulls_last" | "desc_nulls_last" => " NULLS LAST",
+                        _ => "",
+                    };
+                    let collation = schema
+                        .columns
+                        .iter()
+                        .find(|column| column.column_name == *col)
+                        .filter(|column| column.column_type == ColumnType::Text)
+                        .map(|_| format!(" COLLATE {}", dialect.ops().binary_collation))
+                        .unwrap_or_default();
+                    parts.push(format!("{alias}.\"{col}\"{collation} {sql_dir}{nulls}"));
+                }
+            }
+        }
+    }
+    // Always append PK asc tiebreaker.
+    for pk in &schema.primary_key.columns {
+        let collation = schema
+            .columns
+            .iter()
+            .find(|column| column.column_name == *pk)
+            .filter(|column| column.column_type == ColumnType::Text)
+            .map(|_| format!(" COLLATE {}", dialect.ops().binary_collation))
+            .unwrap_or_default();
+        parts.push(format!("{alias}.\"{pk}\"{collation} ASC"));
+    }
+    if parts.is_empty() {
+        Ok(String::new())
+    } else {
+        Ok(format!("ORDER BY {}", parts.join(", ")))
+    }
+}
+
+/// Walk async-graphql selection field into our SelectionNode tree.
+pub fn selection_from_field(field: async_graphql::SelectionField<'_>) -> SelectionNode {
+    let mut args = BTreeMap::new();
+    if let Ok(arg_list) = field.arguments() {
+        for (name, value) in arg_list {
+            args.insert(name.to_string(), value);
+        }
+    }
+    let mut children = Vec::new();
+    for sel in field.selection_set() {
+        children.push(selection_from_field(sel));
+    }
+    SelectionNode {
+        response_key: field.alias().unwrap_or_else(|| field.name()).to_string(),
+        field_name: field.name().to_string(),
+        args,
+        children,
+    }
+}
+
+/// Helper for pure unit tests without an engine.
+#[allow(dead_code)]
+pub fn compile_list_sql_for_test(
+    dialect: SqlDialect,
+    schema: &TableSchema,
+    where_sql: &str,
+    limit: u64,
+) -> String {
+    let ops = dialect.ops();
+    let json_agg = ops.json_agg;
+    let coalesce_empty = ops.empty_array;
+    let build = ops.build_object;
+    let pairs: Vec<String> = schema
+        .columns
+        .iter()
+        .filter(|c| !c.skipped)
+        .map(|c| format!("'{}', t0.\"{}\"", c.column_name, c.column_name))
+        .collect();
+    format!(
+        "SELECT coalesce({json_agg}(root), {coalesce_empty}) FROM (\n  SELECT {build}({}) AS root\n  FROM \"{}\" t0\n  WHERE {where_sql}\n  ORDER BY {}\n  LIMIT {limit} OFFSET 0\n) sub",
+        pairs.join(", "),
+        schema.table_name,
+        schema
+            .primary_key
+            .columns
+            .iter()
+            .map(|c| format!("t0.\"{c}\" ASC"))
+            .collect::<Vec<_>>()
+            .join(", ")
+    )
+}
+
+#[cfg(test)]
+mod security_tests {
+    use super::*;
+    use crate::graphql::naming::is_valid_graphql_name;
+
+    #[test]
+    fn response_key_validator_accepts_graphql_names() {
+        assert!(validate_response_key("order_id").is_ok());
+        assert!(validate_response_key("_x").is_ok());
+        assert!(validate_response_key("a1").is_ok());
+    }
+
+    #[test]
+    fn response_key_validator_rejects_injection_shaped_keys() {
+        assert!(validate_response_key("a', (SELECT 1), '").is_err());
+        assert!(validate_response_key("a b").is_err());
+        assert!(validate_response_key("").is_err());
+        assert!(validate_response_key("__proto__").is_err());
+        assert!(!is_valid_graphql_name("1bad"));
+    }
+
+    #[test]
+    fn resolve_limit_clamps_to_max() {
+        assert_eq!(resolve_limit(None, None, 100, 1000), 100);
+        assert_eq!(
+            resolve_limit(Some(&Value::from(9_000_000u64)), None, 100, 1000),
+            1000
+        );
+        assert_eq!(
+            resolve_limit(Some(&Value::from(50u64)), Some(10), 100, 1000),
+            10
+        );
+    }
+
+    #[test]
+    fn resolve_limit_ignores_negative_values() {
+        assert_eq!(resolve_limit(Some(&Value::from(-1)), None, 100, 1000), 100);
+        assert_eq!(value_as_u64(&Value::from(-1)), None);
+    }
+}
+
+#[cfg(test)]
+mod strict_order_by_tests {
+    use super::*;
+    use crate::graphql::permissions::read;
+    use crate::table::{ColumnType, PrimaryKey, TableColumn, TableKind, TableSchema};
+    use async_graphql::indexmap::IndexMap;
+    use async_graphql::Value as GqlValue;
+
+    fn item_schema() -> TableSchema {
+        TableSchema {
+            model_name: "Item".into(),
+            table_name: "items".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new("id", "id", ColumnType::Text)
+                },
+                TableColumn::new("name", "name", ColumnType::Text),
+                TableColumn::new("secret", "secret", ColumnType::Text),
+            ],
+            primary_key: PrimaryKey::new(["id"]),
+            version_column: None,
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        }
+    }
+
+    fn order_list(entries: Vec<(&str, &str)>) -> GqlValue {
+        let mut items = Vec::new();
+        for (col, dir) in entries {
+            let mut map = IndexMap::new();
+            map.insert(
+                async_graphql::Name::new(col),
+                GqlValue::Enum(async_graphql::Name::new(dir)),
+            );
+            items.push(GqlValue::Object(map));
+        }
+        GqlValue::List(items)
+    }
+
+    #[test]
+    fn strict_rejects_unknown_order_column() {
+        let schema = item_schema();
+        let perm = read().all_columns();
+        let arg = order_list(vec![("nope", "asc")]);
+        let err = compile_order_by(&schema, Some(&arg), "t0", &perm, true, SqlDialect::Sqlite)
+            .unwrap_err();
+        assert!(err.contains("unknown order_by"), "{err}");
+    }
+
+    #[test]
+    fn strict_rejects_ungranted_order_column() {
+        let schema = item_schema();
+        let perm = read().columns(["id", "name"]);
+        let arg = order_list(vec![("secret", "asc")]);
+        let err = compile_order_by(&schema, Some(&arg), "t0", &perm, true, SqlDialect::Sqlite)
+            .unwrap_err();
+        assert!(err.contains("ungranted order_by"), "{err}");
+    }
+
+    #[test]
+    fn soft_skip_ignores_unknown_and_ungranted_order() {
+        let schema = item_schema();
+        let perm = read().columns(["id", "name"]);
+        let arg = order_list(vec![("secret", "asc"), ("nope", "desc"), ("name", "desc")]);
+        let sql =
+            compile_order_by(&schema, Some(&arg), "t0", &perm, false, SqlDialect::Sqlite).unwrap();
+        assert!(sql.contains(r#"t0."name" COLLATE BINARY DESC"#), "{sql}");
+        assert!(!sql.contains("secret"), "{sql}");
+        assert!(!sql.contains("nope"), "{sql}");
+        assert!(
+            sql.contains(r#"t0."id" COLLATE BINARY ASC"#),
+            "pk tiebreak: {sql}"
+        );
+    }
+
+    #[test]
+    fn strict_accepts_granted_order_with_pk_tiebreak() {
+        let schema = item_schema();
+        let perm = read().all_columns();
+        let arg = order_list(vec![("name", "desc")]);
+        let sql =
+            compile_order_by(&schema, Some(&arg), "t0", &perm, true, SqlDialect::Sqlite).unwrap();
+        assert!(sql.contains(r#"t0."name" COLLATE BINARY DESC"#), "{sql}");
+        assert!(sql.contains(r#"t0."id" COLLATE BINARY ASC"#), "{sql}");
+    }
+
+    #[test]
+    fn multi_field_order_object_is_rejected_even_in_soft_mode() {
+        let schema = item_schema();
+        let perm = read().all_columns();
+        let mut entry = IndexMap::new();
+        entry.insert(
+            async_graphql::Name::new("name"),
+            GqlValue::Enum(async_graphql::Name::new("desc")),
+        );
+        entry.insert(
+            async_graphql::Name::new("id"),
+            GqlValue::Enum(async_graphql::Name::new("asc")),
+        );
+        let arg = GqlValue::List(vec![GqlValue::Object(entry)]);
+
+        let error = compile_order_by(&schema, Some(&arg), "t0", &perm, false, SqlDialect::Sqlite)
+            .unwrap_err();
+        assert!(error.contains("ambiguous order_by"), "{error}");
+        assert!(error.contains("one field per list entry"), "{error}");
+    }
+
+    #[test]
+    fn separate_order_entries_preserve_declared_priority() {
+        let schema = item_schema();
+        let perm = read().all_columns();
+        let arg = order_list(vec![("name", "desc"), ("secret", "asc")]);
+
+        let sql =
+            compile_order_by(&schema, Some(&arg), "t0", &perm, true, SqlDialect::Postgres).unwrap();
+        assert!(sql.contains(r#"t0."name" COLLATE "C" DESC"#), "{sql}");
+        assert!(sql.contains(r#"t0."secret" COLLATE "C" ASC"#), "{sql}");
+        let name_position = sql
+            .find(r#"t0."name" COLLATE "C" DESC"#)
+            .expect("name ordering");
+        let secret_position = sql
+            .find(r#"t0."secret" COLLATE "C" ASC"#)
+            .expect("secret ordering");
+        assert!(name_position < secret_position, "{sql}");
+    }
+}
diff --git a/src/graphql/compile/relationship.rs b/src/graphql/compile/relationship.rs
new file mode 100644
index 00000000..bbdbf9c8
--- /dev/null
+++ b/src/graphql/compile/relationship.rs
@@ -0,0 +1,496 @@
+use crate::microsvc::Session;
+use crate::table::{resolve_m2m_target_foreign_key, RelationshipKind, TableSchema};
+
+use super::super::engine::{CatalogEntry, EngineInner};
+use super::super::permissions::ReadPermission;
+use super::binds::BindValue;
+use super::dialect::{
+    join_predicate_direct, join_predicate_m2m_parent, join_predicate_m2m_target, placeholder,
+};
+use super::evidence::{QueryEvidenceFieldPlan, QueryEvidenceNode, QueryEvidenceObjectPlan};
+use super::filter::compile_where;
+use super::projection::{
+    chunked_json_object, compile_object_projection, compile_order_by, resolve_limit,
+    validate_response_key, value_as_u64, SelectionNode,
+};
+
+pub(super) fn compile_relationship_aggregate_subquery(
+    inner: &EngineInner,
+    session: &Session,
+    role: &str,
+    source: &TableSchema,
+    source_alias: &str,
+    rel: &crate::table::RelationshipDef,
+    target: &CatalogEntry,
+    target_perm: &ReadPermission,
+    selection: &SelectionNode,
+    binds: &mut Vec<BindValue>,
+    bytes_paths: &mut Vec<String>,
+    tables: &mut Vec<String>,
+    path_prefix: &str,
+    depth: usize,
+) -> Result<(String, QueryEvidenceNode), String> {
+    let child_alias = format!("ta{depth}");
+    let fk = rel.foreign_key.as_deref().unwrap_or("");
+    let source_pk = source
+        .primary_key
+        .columns
+        .first()
+        .map(|s| s.as_str())
+        .unwrap_or("id");
+
+    let (from_sql, join_pred) = match rel.kind {
+        RelationshipKind::HasMany => {
+            let target_fk = column_name_for(&target.schema, fk).unwrap_or(fk);
+            (
+                format!("\"{}\" {child_alias}", target.schema.table_name),
+                join_predicate_direct(
+                    RelationshipKind::HasMany,
+                    source_alias,
+                    &child_alias,
+                    source_pk,
+                    /* child_pk unused for has_many */ "",
+                    target_fk,
+                )?,
+            )
+        }
+        RelationshipKind::ManyToMany => {
+            let through_name = rel
+                .through
+                .as_deref()
+                .ok_or_else(|| "m2m missing through".to_string())?;
+            let through_model = inner
+                .by_table
+                .get(through_name)
+                .and_then(|m| inner.catalog.get(m))
+                .ok_or_else(|| format!("through table `{through_name}` not in catalog"))?;
+            let target_fk =
+                resolve_m2m_target_foreign_key(source, rel, &through_model.schema, &target.schema)
+                    .map_err(|e| e.to_string())?;
+            let source_join_col = column_name_for(&through_model.schema, fk).unwrap_or(fk);
+            let target_pk = target
+                .schema
+                .primary_key
+                .columns
+                .first()
+                .map(|s| s.as_str())
+                .unwrap_or("id");
+            let join_alias = format!("ja{depth}");
+            tables.push(through_name.to_string());
+            let on_target =
+                join_predicate_m2m_target(&join_alias, &target_fk, &child_alias, target_pk);
+            (
+                format!(
+                    "\"{}\" {child_alias} JOIN \"{through_name}\" {join_alias} ON {on_target}",
+                    target.schema.table_name
+                ),
+                join_predicate_m2m_parent(&join_alias, source_join_col, source_alias, source_pk),
+            )
+        }
+        RelationshipKind::BelongsTo => {
+            return Err("belongs_to aggregate is not supported".into());
+        }
+    };
+
+    let ops = inner.dialect.ops();
+    let json_agg = ops.json_agg;
+    let coalesce_empty = ops.empty_array;
+    let mut pairs = Vec::new();
+    let mut evidence_fields = Vec::new();
+    for aggregate_member in &selection.children {
+        match aggregate_member.field_name.as_str() {
+            "__typename" => {}
+            "aggregate" => {
+                validate_response_key(&aggregate_member.response_key)?;
+                let mut aggregate_pairs = Vec::new();
+                for metric in &aggregate_member.children {
+                    match metric.field_name.as_str() {
+                        "__typename" => {}
+                        "count" => {
+                            validate_response_key(&metric.response_key)?;
+                            let where_for_count = compile_where(
+                                inner,
+                                session,
+                                role,
+                                &target.schema,
+                                target_perm,
+                                selection.args.get("where"),
+                                &child_alias,
+                                binds,
+                                tables,
+                                depth,
+                            )?;
+                            aggregate_pairs.push((
+                                metric.response_key.clone(),
+                                format!(
+                                    "(SELECT count(*) FROM {from_sql} WHERE {join_pred} AND ({where_for_count}))"
+                                ),
+                            ));
+                        }
+                        _ => {
+                            return Err(
+                                "relationship aggregate fields selection contains an unsupported member"
+                                    .into(),
+                            );
+                        }
+                    }
+                }
+                pairs.push((
+                    aggregate_member.response_key.clone(),
+                    chunked_json_object(inner.dialect, &aggregate_pairs),
+                ));
+            }
+            "nodes" => {
+                validate_response_key(&aggregate_member.response_key)?;
+                let nodes_path = if path_prefix.is_empty() {
+                    aggregate_member.response_key.clone()
+                } else {
+                    format!("{path_prefix}.{}", aggregate_member.response_key)
+                };
+                let (nodes_proj, nodes_evidence) = compile_object_projection(
+                    inner,
+                    session,
+                    role,
+                    &target.schema,
+                    target_perm,
+                    aggregate_member,
+                    &child_alias,
+                    binds,
+                    bytes_paths,
+                    tables,
+                    &nodes_path,
+                    depth,
+                )?;
+                let where_for_nodes = compile_where(
+                    inner,
+                    session,
+                    role,
+                    &target.schema,
+                    target_perm,
+                    selection.args.get("where"),
+                    &child_alias,
+                    binds,
+                    tables,
+                    depth,
+                )?;
+                let order_sql = compile_order_by(
+                    &target.schema,
+                    selection.args.get("order_by"),
+                    &child_alias,
+                    target_perm,
+                    inner.strict_where,
+                    inner.dialect,
+                )?;
+                let limit = resolve_limit(
+                    selection.args.get("limit"),
+                    target_perm.limit,
+                    inner.default_limit,
+                    inner.max_limit,
+                );
+                let offset = selection
+                    .args
+                    .get("offset")
+                    .and_then(value_as_u64)
+                    .unwrap_or(0);
+                let lim = {
+                    binds.push(BindValue::I64(limit as i64));
+                    placeholder(inner.dialect, binds.len())
+                };
+                let off = {
+                    binds.push(BindValue::I64(offset as i64));
+                    placeholder(inner.dialect, binds.len())
+                };
+                pairs.push((
+                    aggregate_member.response_key.clone(),
+                    format!(
+                        "coalesce((SELECT {json_agg}(n) FROM (SELECT {nodes_proj} AS n FROM {from_sql} WHERE {join_pred} AND ({where_for_nodes}) {order_sql} LIMIT {lim} OFFSET {off}) nested_agg_rows), {coalesce_empty})"
+                    ),
+                ));
+                evidence_fields.push(QueryEvidenceFieldPlan {
+                    storage_key: aggregate_member.response_key.clone(),
+                    response_key: aggregate_member.response_key.clone(),
+                    node: Box::new(QueryEvidenceNode::List(Box::new(
+                        QueryEvidenceNode::Object(nodes_evidence),
+                    ))),
+                });
+            }
+            _ => {
+                return Err(
+                    "relationship aggregate selection contains an unsupported member".into(),
+                );
+            }
+        }
+    }
+
+    Ok((
+        chunked_json_object(inner.dialect, &pairs),
+        QueryEvidenceNode::Object(QueryEvidenceObjectPlan {
+            record: None,
+            fields: evidence_fields,
+        }),
+    ))
+}
+
+pub(super) fn compile_relationship_subquery(
+    inner: &EngineInner,
+    session: &Session,
+    role: &str,
+    source: &TableSchema,
+    source_alias: &str,
+    rel: &crate::table::RelationshipDef,
+    target: &CatalogEntry,
+    target_perm: &ReadPermission,
+    selection: &SelectionNode,
+    binds: &mut Vec<BindValue>,
+    bytes_paths: &mut Vec<String>,
+    tables: &mut Vec<String>,
+    path_prefix: &str,
+    depth: usize,
+) -> Result<(String, QueryEvidenceNode), String> {
+    let child_alias = format!("t{depth}");
+    let limit = resolve_limit(
+        selection.args.get("limit"),
+        target_perm.limit,
+        inner.default_limit,
+        inner.max_limit,
+    );
+    let offset = selection
+        .args
+        .get("offset")
+        .and_then(value_as_u64)
+        .unwrap_or(0);
+
+    let fk = rel.foreign_key.as_deref().unwrap_or("");
+    let fk_col = column_name_for(source, fk).unwrap_or(fk);
+    let target_fk_col = column_name_for(&target.schema, fk).unwrap_or(fk);
+    let source_pk_col = source
+        .primary_key
+        .columns
+        .first()
+        .map(|s| s.as_str())
+        .unwrap_or("id");
+    let target_pk_col = target
+        .schema
+        .primary_key
+        .columns
+        .first()
+        .map(|s| s.as_str())
+        .unwrap_or("id");
+
+    let join_pred = match &rel.kind {
+        RelationshipKind::HasMany => join_predicate_direct(
+            RelationshipKind::HasMany,
+            source_alias,
+            &child_alias,
+            source_pk_col,
+            target_pk_col,
+            target_fk_col,
+        )?,
+        RelationshipKind::BelongsTo => join_predicate_direct(
+            RelationshipKind::BelongsTo,
+            source_alias,
+            &child_alias,
+            source_pk_col,
+            target_pk_col,
+            fk_col,
+        )?,
+        RelationshipKind::ManyToMany => {
+            let through_name = rel
+                .through
+                .as_deref()
+                .ok_or_else(|| "m2m missing through".to_string())?;
+            let through_model = inner
+                .by_table
+                .get(through_name)
+                .and_then(|m| inner.catalog.get(m))
+                .ok_or_else(|| format!("through table `{through_name}` not in catalog"))?;
+            let target_fk =
+                resolve_m2m_target_foreign_key(source, rel, &through_model.schema, &target.schema)
+                    .map_err(|e| e.to_string())?;
+            let source_join_col = column_name_for(&through_model.schema, fk).unwrap_or(fk);
+            // Source PK for join (single-column assumption with FK fallback).
+            let source_pk = source
+                .primary_key
+                .columns
+                .first()
+                .map(|s| s.as_str())
+                .unwrap_or("id");
+            let target_pk = target
+                .schema
+                .primary_key
+                .columns
+                .first()
+                .map(|s| s.as_str())
+                .unwrap_or("id");
+            tables.push(through_name.to_string());
+            return compile_m2m_subquery(
+                inner,
+                session,
+                role,
+                source_alias,
+                source_pk,
+                through_name,
+                source_join_col,
+                &target_fk,
+                &target.schema,
+                target_pk,
+                target_perm,
+                selection,
+                binds,
+                bytes_paths,
+                tables,
+                path_prefix,
+                depth,
+                limit,
+                offset,
+            );
+        }
+    };
+
+    let order_sql = compile_order_by(
+        &target.schema,
+        selection.args.get("order_by"),
+        &child_alias,
+        target_perm,
+        inner.strict_where,
+        inner.dialect,
+    )?;
+    let (projection, object_evidence) = compile_object_projection(
+        inner,
+        session,
+        role,
+        &target.schema,
+        target_perm,
+        selection,
+        &child_alias,
+        binds,
+        bytes_paths,
+        tables,
+        path_prefix,
+        depth,
+    )?;
+    let where_extra = compile_where(
+        inner,
+        session,
+        role,
+        &target.schema,
+        target_perm,
+        selection.args.get("where"),
+        &child_alias,
+        binds,
+        tables,
+        depth,
+    )?;
+
+    let ops = inner.dialect.ops();
+    let json_agg = ops.json_agg;
+    let coalesce_empty = ops.empty_array;
+
+    match rel.kind {
+        RelationshipKind::BelongsTo => Ok((
+            format!(
+                "(SELECT {projection} FROM \"{}\" {child_alias} WHERE {join_pred} AND ({where_extra}) LIMIT 1)",
+                target.schema.table_name
+            ),
+            QueryEvidenceNode::Object(object_evidence),
+        )),
+        _ => {
+            binds.push(BindValue::I64(limit as i64));
+            let lim = placeholder(inner.dialect, binds.len());
+            binds.push(BindValue::I64(offset as i64));
+            let off = placeholder(inner.dialect, binds.len());
+            Ok((
+                format!(
+                    "(SELECT coalesce({json_agg}(obj), {coalesce_empty}) FROM (\n  SELECT {projection} AS obj\n  FROM \"{}\" {child_alias}\n  WHERE {join_pred} AND ({where_extra})\n  {order_sql}\n  LIMIT {lim} OFFSET {off}\n) inner_rows)",
+                    target.schema.table_name
+                ),
+                QueryEvidenceNode::List(Box::new(QueryEvidenceNode::Object(object_evidence))),
+            ))
+        }
+    }
+}
+
+fn compile_m2m_subquery(
+    inner: &EngineInner,
+    session: &Session,
+    role: &str,
+    source_alias: &str,
+    source_pk: &str,
+    through_name: &str,
+    source_join_col: &str,
+    target_fk: &str,
+    target_schema: &TableSchema,
+    target_pk: &str,
+    target_perm: &ReadPermission,
+    selection: &SelectionNode,
+    binds: &mut Vec<BindValue>,
+    bytes_paths: &mut Vec<String>,
+    tables: &mut Vec<String>,
+    path_prefix: &str,
+    depth: usize,
+    limit: u64,
+    offset: u64,
+) -> Result<(String, QueryEvidenceNode), String> {
+    let child_alias = format!("t{depth}");
+    let j_alias = format!("j{depth}");
+    let order_sql = compile_order_by(
+        target_schema,
+        selection.args.get("order_by"),
+        &child_alias,
+        target_perm,
+        inner.strict_where,
+        inner.dialect,
+    )?;
+    let (projection, object_evidence) = compile_object_projection(
+        inner,
+        session,
+        role,
+        target_schema,
+        target_perm,
+        selection,
+        &child_alias,
+        binds,
+        bytes_paths,
+        tables,
+        path_prefix,
+        depth,
+    )?;
+    let where_extra = compile_where(
+        inner,
+        session,
+        role,
+        target_schema,
+        target_perm,
+        selection.args.get("where"),
+        &child_alias,
+        binds,
+        tables,
+        depth,
+    )?;
+    let ops = inner.dialect.ops();
+    let json_agg = ops.json_agg;
+    let coalesce_empty = ops.empty_array;
+    binds.push(BindValue::I64(limit as i64));
+    let lim = placeholder(inner.dialect, binds.len());
+    binds.push(BindValue::I64(offset as i64));
+    let off = placeholder(inner.dialect, binds.len());
+    let on_target = join_predicate_m2m_target(&j_alias, target_fk, &child_alias, target_pk);
+    let parent_pred = join_predicate_m2m_parent(&j_alias, source_join_col, source_alias, source_pk);
+    Ok((
+        format!(
+            "(SELECT coalesce({json_agg}(obj), {coalesce_empty}) FROM (\n  SELECT {projection} AS obj\n  FROM \"{target_table}\" {child_alias}\n  JOIN \"{through_name}\" {j_alias} ON {on_target}\n  WHERE {parent_pred}\n    AND ({where_extra})\n  {order_sql}\n  LIMIT {lim} OFFSET {off}\n) x)",
+            target_table = target_schema.table_name,
+        ),
+        QueryEvidenceNode::List(Box::new(QueryEvidenceNode::Object(object_evidence))),
+    ))
+}
+
+pub(super) fn column_name_for<'a>(schema: &'a TableSchema, name: &str) -> Option<&'a str> {
+    schema.columns.iter().find_map(|c| {
+        if c.column_name == name || c.field_name == name {
+            Some(c.column_name.as_str())
+        } else {
+            None
+        }
+    })
+}
diff --git a/src/graphql/complexity.rs b/src/graphql/complexity.rs
new file mode 100644
index 00000000..89ede855
--- /dev/null
+++ b/src/graphql/complexity.rs
@@ -0,0 +1,249 @@
+//! Nested selection complexity estimation (ship-complexity-1).
+//!
+//! async-graphql's dynamic schema only supports flat `1 + children` complexity
+//! (no per-field weights). We estimate a **relationship-aware** cost from the
+//! selection tree before SQL compile so multi-level `has_many` fan-out is
+//! bounded by `max_complexity`, not just `max_depth`.
+
+use crate::table::{RelationshipKind, TableSchema};
+
+use super::compile::{RootKind, SelectionNode};
+pub(crate) use super::complexity_contract::{
+    default_weights, ComplexityWeights, DEFAULT_MAX_COMPLEXITY, DEFAULT_MAX_DEPTH,
+};
+use super::engine::EngineInner;
+
+/// Estimate complexity for a root field selection before SQL compile.
+pub fn estimate_root_complexity(
+    inner: &EngineInner,
+    model_name: &str,
+    kind: RootKind,
+    selection: &SelectionNode,
+) -> Result<usize, String> {
+    let entry = inner
+        .catalog
+        .get(model_name)
+        .ok_or_else(|| format!("unknown model `{model_name}`"))?;
+    let w = default_weights();
+    let child = estimate_object_selection(inner, &entry.schema, selection, &w)?;
+    let root = match kind {
+        RootKind::List => w
+            .list_root
+            .saturating_add(w.list_fanout.saturating_mul(child)),
+        RootKind::ByPk => w.by_pk.saturating_add(child),
+        RootKind::Aggregate => {
+            // Aggregate selection often has `nodes { ... }` and `aggregate { count }`.
+            w.aggregate.saturating_add(child)
+        }
+    };
+    Ok(root)
+}
+
+fn estimate_object_selection(
+    inner: &EngineInner,
+    schema: &TableSchema,
+    selection: &SelectionNode,
+    w: &ComplexityWeights,
+) -> Result<usize, String> {
+    let mut total = 0usize;
+    for child in &selection.children {
+        total = total.saturating_add(estimate_field(inner, schema, child, w)?);
+    }
+    // Object with no children (empty selection) still costs a scalar floor.
+    if selection.children.is_empty() {
+        return Ok(w.scalar);
+    }
+    Ok(total)
+}
+
+fn estimate_field(
+    inner: &EngineInner,
+    schema: &TableSchema,
+    node: &SelectionNode,
+    w: &ComplexityWeights,
+) -> Result<usize, String> {
+    let name = node.field_name.as_str();
+
+    // Nested aggregate field: `<rel>_aggregate`
+    if let Some(rel_name) = name.strip_suffix("_aggregate") {
+        if let Some(rel) = schema
+            .relationships
+            .iter()
+            .find(|r| r.field_name == rel_name)
+        {
+            let target = match inner.catalog.get(&rel.target_model) {
+                Some(t) => t,
+                None => return Ok(w.aggregate),
+            };
+            let child = estimate_object_selection(inner, &target.schema, node, w)?;
+            return Ok(w.aggregate.saturating_add(child));
+        }
+    }
+
+    if let Some(rel) = schema.relationships.iter().find(|r| r.field_name == name) {
+        let target = match inner.catalog.get(&rel.target_model) {
+            Some(t) => t,
+            None => return Ok(w.has_many),
+        };
+        let child = estimate_object_selection(inner, &target.schema, node, w)?;
+        return Ok(match rel.kind {
+            RelationshipKind::BelongsTo => w.belongs_to.saturating_add(child),
+            RelationshipKind::HasMany => w
+                .has_many
+                .saturating_add(w.list_fanout.saturating_mul(child)),
+            RelationshipKind::ManyToMany => {
+                w.m2m.saturating_add(w.list_fanout.saturating_mul(child))
+            }
+        });
+    }
+
+    // Aggregate nodes/count leaves on aggregate type
+    if name == "nodes" {
+        // nodes reuses parent schema when on aggregate — treated as list of same model
+        let child = estimate_object_selection(inner, schema, node, w)?;
+        return Ok(w.list_fanout.saturating_mul(child).max(w.scalar));
+    }
+    if name == "aggregate" || name == "count" {
+        return Ok(w.scalar);
+    }
+
+    // Scalar / unknown field
+    Ok(w.scalar)
+}
+
+/// True if estimated cost exceeds the engine budget.
+pub fn exceeds_budget(cost: usize, max_complexity: usize) -> bool {
+    cost > max_complexity
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::graphql::compile::SelectionNode;
+    use crate::table::{
+        ColumnType, PrimaryKey, RelationshipDef, RelationshipKind, TableColumn, TableKind,
+        TableSchema,
+    };
+    use std::collections::BTreeMap;
+
+    fn col(name: &str) -> TableColumn {
+        TableColumn::new(name, name, ColumnType::Text)
+    }
+
+    fn parent_schema() -> TableSchema {
+        TableSchema {
+            model_name: "Parent".into(),
+            table_name: "parents".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..col("parent_id")
+                },
+                col("name"),
+            ],
+            primary_key: PrimaryKey::new(["parent_id"]),
+            version_column: None,
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: vec![RelationshipDef {
+                field_name: "children".into(),
+                kind: RelationshipKind::HasMany,
+                target_model: "Child".into(),
+                foreign_key: Some("parent_id".into()),
+                through: None,
+                target_foreign_key: None,
+            }],
+            kind: TableKind::ReadModel,
+        }
+    }
+
+    fn child_schema() -> TableSchema {
+        TableSchema {
+            model_name: "Child".into(),
+            table_name: "children".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..col("child_id")
+                },
+                col("parent_id"),
+                col("name"),
+                // nested grandchildren for multi-level
+            ],
+            primary_key: PrimaryKey::new(["child_id"]),
+            version_column: None,
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: vec![RelationshipDef {
+                field_name: "grandchildren".into(),
+                kind: RelationshipKind::HasMany,
+                target_model: "Grandchild".into(),
+                foreign_key: Some("child_id".into()),
+                through: None,
+                target_foreign_key: None,
+            }],
+            kind: TableKind::ReadModel,
+        }
+    }
+
+    fn grand_schema() -> TableSchema {
+        TableSchema {
+            model_name: "Grandchild".into(),
+            table_name: "grandchildren".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..col("grand_id")
+                },
+                col("child_id"),
+                col("name"),
+            ],
+            primary_key: PrimaryKey::new(["grand_id"]),
+            version_column: None,
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        }
+    }
+
+    fn sel(field: &str, children: Vec<SelectionNode>) -> SelectionNode {
+        SelectionNode {
+            response_key: field.into(),
+            field_name: field.into(),
+            args: BTreeMap::new(),
+            children,
+        }
+    }
+
+    #[test]
+    fn nested_has_many_costs_more_than_flat_scalars() {
+        let w = default_weights();
+        // Pure formula check (mirrors estimate_field for has_many + list root).
+        // Mirrors estimate_root_complexity(List) for parent { id, children { a, b, grandchildren { x, y } } }
+        // with one scalar at each list level.
+        let grand = w.has_many + w.list_fanout * (w.scalar * 2);
+        let child = w.has_many + w.list_fanout * (w.scalar * 2 + grand);
+        let three_nest = w.list_root + w.list_fanout * (w.scalar + child);
+        let one_child = w.has_many + w.list_fanout * (w.scalar * 2);
+        let one_nest = w.list_root + w.list_fanout * (w.scalar + one_child);
+        let flat = w.list_root + w.list_fanout * (w.scalar * 3);
+        assert!(one_nest > flat, "nest={one_nest} flat={flat}");
+        assert!(three_nest > one_nest, "three={three_nest} one={one_nest}");
+        assert!(
+            three_nest > DEFAULT_MAX_COMPLEXITY,
+            "expected 3-level nest to exceed default budget, got {three_nest}"
+        );
+        assert!(
+            one_nest < DEFAULT_MAX_COMPLEXITY,
+            "expected 1-level nest under budget, got {one_nest}"
+        );
+        let _ = (parent_schema(), child_schema(), grand_schema(), sel);
+    }
+
+    #[test]
+    fn exceeds_budget_helper() {
+        assert!(exceeds_budget(501, 500));
+        assert!(!exceeds_budget(500, 500));
+    }
+}
diff --git a/src/graphql/complexity_contract.rs b/src/graphql/complexity_contract.rs
new file mode 100644
index 00000000..baed53ab
--- /dev/null
+++ b/src/graphql/complexity_contract.rs
@@ -0,0 +1,59 @@
+//! Feature-neutral query complexity contract shared by runtime execution and
+//! portable client-manifest generation.
+
+/// Default weights for nested query cost (v1 ship defaults).
+///
+/// | Kind | Weight role |
+/// |---|---|
+/// | scalar | +`scalar` per leaf field |
+/// | belongs_to | `belongs_to` + child selection cost |
+/// | has_many / m2m | `has_many`/`m2m` + `list_fanout` × child selection cost |
+/// | aggregate | `aggregate` + nodes child cost |
+/// | list root | `list_root` + child selection cost (fanout applied to list children) |
+/// | by_pk root | `by_pk` + child selection cost |
+///
+/// `list_fanout` models nested row multiplication without using the full
+/// `limit` (which defaults to 100 and would make any nest fail). It is a
+/// conservative multiplier so deep `has_many` trees grow faster than flat
+/// field counts.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct ComplexityWeights {
+    pub scalar: usize,
+    pub belongs_to: usize,
+    pub has_many: usize,
+    pub m2m: usize,
+    pub aggregate: usize,
+    pub list_root: usize,
+    pub by_pk: usize,
+    /// Multiplier for nested list relationship child selections.
+    pub list_fanout: usize,
+}
+
+impl Default for ComplexityWeights {
+    fn default() -> Self {
+        Self {
+            scalar: 1,
+            belongs_to: 2,
+            has_many: 10,
+            m2m: 12,
+            aggregate: 8,
+            list_root: 3,
+            by_pk: 1,
+            // Fan-out factor: deep has_many trees exceed
+            // DEFAULT_MAX_COMPLEXITY by about three nested levels while
+            // one-level nests remain usable.
+            list_fanout: 5,
+        }
+    }
+}
+
+/// Default engine budget (same as the historical builder default).
+pub(crate) const DEFAULT_MAX_COMPLEXITY: usize = 500;
+
+/// Default maximum GraphQL document depth.
+pub(crate) const DEFAULT_MAX_DEPTH: usize = 8;
+
+/// Ship-default weight table.
+pub(crate) fn default_weights() -> ComplexityWeights {
+    ComplexityWeights::default()
+}
diff --git a/src/graphql/engine/auth.rs b/src/graphql/engine/auth.rs
new file mode 100644
index 00000000..16c7150e
--- /dev/null
+++ b/src/graphql/engine/auth.rs
@@ -0,0 +1,101 @@
+use super::*;
+
+pub(crate) fn role_authorization_info(
+    role: &str,
+    permissions: &BTreeMap<(String, String), RoleModelPerm>,
+) -> Result<(String, Vec<String>), GraphqlBuildError> {
+    #[derive(Serialize)]
+    struct PermissionMaterial<'a> {
+        model: &'a str,
+        all_columns: bool,
+        columns: Vec<&'a str>,
+        row_filter: Option<&'a FilterExpr>,
+        limit: Option<u64>,
+        aggregations: bool,
+    }
+
+    #[derive(Serialize)]
+    struct RoleAuthorizationMaterial<'a> {
+        domain: &'static str,
+        version: u32,
+        role: &'a str,
+        permissions: Vec<PermissionMaterial<'a>>,
+    }
+
+    let mut claim_keys = BTreeSet::from([ROLE_KEY.to_string(), USER_ID_KEY.to_string()]);
+    let mut role_permissions = Vec::new();
+    for ((model, permission_role), entry) in permissions {
+        if permission_role != role {
+            continue;
+        }
+        if let Some(filter) = &entry.permission.row_filter {
+            collect_filter_claim_keys(filter, &mut claim_keys);
+        }
+        role_permissions.push(PermissionMaterial {
+            model,
+            all_columns: entry.permission.all_columns,
+            columns: entry
+                .permission
+                .columns
+                .as_ref()
+                .map(|columns| columns.iter().map(String::as_str).collect())
+                .unwrap_or_default(),
+            row_filter: entry.permission.row_filter.as_ref(),
+            limit: entry.permission.limit,
+            aggregations: entry.permission.aggregations,
+        });
+    }
+    let canonical = serde_json::to_vec(&RoleAuthorizationMaterial {
+        domain: "distributed.graphql.authorization-surface",
+        version: 1,
+        role,
+        permissions: role_permissions,
+    })
+    .map_err(|_| {
+        GraphqlBuildError(format!(
+            "failed to encode GraphQL authorization surface for role `{role}`"
+        ))
+    })?;
+    Ok((
+        format!("sha256:{:x}", Sha256::digest(canonical)),
+        claim_keys.into_iter().collect(),
+    ))
+}
+
+fn collect_filter_claim_keys(filter: &FilterExpr, keys: &mut BTreeSet<String>) {
+    fn collect_operand(operand: &Operand, keys: &mut BTreeSet<String>) {
+        if let Operand::Claim(claim) = operand {
+            keys.insert(claim.header.clone());
+        }
+    }
+
+    match filter {
+        FilterExpr::And(items) | FilterExpr::Or(items) => {
+            for item in items {
+                collect_filter_claim_keys(item, keys);
+            }
+        }
+        FilterExpr::Not(item)
+        | FilterExpr::Rel {
+            predicate: item, ..
+        } => {
+            collect_filter_claim_keys(item, keys);
+        }
+        FilterExpr::Cmp { rhs, .. } => collect_operand(rhs, keys),
+        FilterExpr::In { values, .. } => {
+            for value in values {
+                collect_operand(value, keys);
+            }
+        }
+        FilterExpr::IsNull { .. } => {}
+    }
+}
+
+pub(crate) fn identity_mode_label(mode: IdentityMode) -> &'static str {
+    match mode {
+        IdentityMode::TrustedProxy => "trusted_proxy",
+        IdentityMode::OidcBearer => "oidc_bearer",
+        IdentityMode::Hybrid => "hybrid",
+        IdentityMode::DevHeaders => "dev_headers",
+    }
+}
diff --git a/src/graphql/engine/builder.rs b/src/graphql/engine/builder.rs
new file mode 100644
index 00000000..7700212c
--- /dev/null
+++ b/src/graphql/engine/builder.rs
@@ -0,0 +1,815 @@
+use super::*;
+
+impl GraphqlEngineBuilder {
+    pub(crate) fn new(source: GraphqlPoolSource) -> Self {
+        Self {
+            service_id: None,
+            protocol_token_key: None,
+            protocol_namespace: None,
+            client_applications: BTreeMap::new(),
+            command_binding: None,
+            causal_storage_identity: source.causal_storage_identity,
+            pool: source.pool,
+            catalog: BTreeMap::new(),
+            by_table: BTreeMap::new(),
+            permissions: BTreeMap::new(),
+            roles: None,
+            anonymous_role: "anonymous".into(),
+            default_limit: 100,
+            max_limit: 1000,
+            max_depth: crate::graphql::complexity::DEFAULT_MAX_DEPTH,
+            max_complexity: crate::graphql::complexity::DEFAULT_MAX_COMPLEXITY,
+            max_in_list: 1000,
+            max_bool_width: 256,
+            // Fail-closed by default for unshipped GA: unknown/ungranted filter
+            // and order keys must not silently no-op.
+            strict_where: true,
+            introspection_for_anonymous: true,
+            statement_timeout: Duration::from_secs(5),
+            graphiql: false,
+            typed_commands: TypedCommandInventory::empty(),
+            projectors: Vec::new(),
+            change_rx: None,
+            pending_errors: Vec::new(),
+            // DevHeaders keeps ambient header tests/green; public scaffolds set OidcBearer (D6).
+            identity: IdentityConfig::dev_headers(),
+        }
+    }
+
+    pub fn model<M: RelationalReadModelIncludes>(mut self, perms: ModelPermissions<M>) -> Self {
+        let schema = M::schema().clone();
+        if let Err(e) = self.insert_catalog(schema.clone(), true) {
+            self.pending_errors.push(e.0);
+            return self;
+        }
+        // Shadow-register one-hop relationship targets.
+        for rel in &schema.relationships {
+            match M::include_target_schema(&rel.field_name) {
+                Ok(target) => {
+                    if let Err(e) = self.insert_catalog(target.clone(), false) {
+                        // Shadow insert conflict only if different schema.
+                        if !e.0.contains("identical") {
+                            self.pending_errors.push(e.0);
+                        }
+                    }
+                }
+                Err(err) => {
+                    self.pending_errors.push(format!(
+                        "include_target_schema for `{}`.`{}`: {err}",
+                        schema.model_name, rel.field_name
+                    ));
+                }
+            }
+        }
+        for (role, perm) in perms.entries {
+            let key = (schema.model_name.clone(), role.clone());
+            match self.permissions.entry(key) {
+                Entry::Vacant(entry) => {
+                    entry.insert(RoleModelPerm { permission: perm });
+                }
+                Entry::Occupied(_) => {
+                    self.pending_errors.push(format!(
+                        "duplicate permission for model `{}` role `{role}`",
+                        schema.model_name
+                    ));
+                }
+            }
+        }
+        self
+    }
+
+    pub fn table_schema(mut self, schema: TableSchema) -> Self {
+        if let Err(e) = self.insert_catalog(schema, false) {
+            self.pending_errors.push(e.0);
+        }
+        self
+    }
+
+    pub(crate) fn register_schema_exposed(
+        mut self,
+        schema: TableSchema,
+    ) -> Result<Self, GraphqlBuildError> {
+        self.insert_catalog(schema, true)?;
+        Ok(self)
+    }
+
+    fn insert_catalog(
+        &mut self,
+        schema: TableSchema,
+        exposed: bool,
+    ) -> Result<(), GraphqlBuildError> {
+        schema
+            .validate()
+            .map_err(|e| GraphqlBuildError(e.to_string()))?;
+        if let Some(existing) = self.by_table.get(&schema.table_name) {
+            if existing != &schema.model_name {
+                return Err(GraphqlBuildError(format!(
+                    "duplicate table_name `{}` for models `{existing}` and `{}`",
+                    schema.table_name, schema.model_name
+                )));
+            }
+        }
+        match self.catalog.get(&schema.model_name) {
+            Some(entry) if entry.schema != schema => {
+                return Err(GraphqlBuildError(format!(
+                    "conflicting schemas for model `{}`",
+                    schema.model_name
+                )));
+            }
+            Some(entry) => {
+                // Identical: upgrade shadow → exposed if needed.
+                if exposed && !entry.exposed {
+                    let mut upgraded = entry.clone();
+                    upgraded.exposed = true;
+                    self.catalog.insert(schema.model_name.clone(), upgraded);
+                }
+                return Ok(());
+            }
+            None => {}
+        }
+        self.by_table
+            .insert(schema.table_name.clone(), schema.model_name.clone());
+        self.catalog
+            .insert(schema.model_name.clone(), CatalogEntry { schema, exposed });
+        Ok(())
+    }
+
+    pub fn roles(mut self, roles: &[&str]) -> Self {
+        self.roles = Some(roles.iter().map(|r| (*r).to_string()).collect());
+        self
+    }
+
+    pub fn grant_all(mut self, role: &str) -> Self {
+        let exposed: Vec<String> = self
+            .catalog
+            .iter()
+            .filter(|(_, e)| e.exposed)
+            .map(|(n, _)| n.clone())
+            .collect();
+        for model in exposed {
+            let key = (model.clone(), role.to_string());
+            match self.permissions.entry(key) {
+                Entry::Vacant(entry) => {
+                    entry.insert(RoleModelPerm {
+                        permission: read().all_columns().aggregations(),
+                    });
+                }
+                Entry::Occupied(_) => {
+                    self.pending_errors.push(format!(
+                        "duplicate permission for model `{model}` role `{role}`"
+                    ));
+                }
+            }
+        }
+        self
+    }
+
+    pub fn permission<M: RelationalReadModelIncludes>(
+        mut self,
+        role: &str,
+        p: ReadPermission,
+    ) -> Self {
+        let model = M::schema().model_name.clone();
+        if !self.catalog.contains_key(&model) {
+            self.pending_errors.push(format!(
+                "permission for unregistered model `{model}` (role `{role}`)"
+            ));
+            return self;
+        }
+        let key = (model.clone(), role.to_string());
+        match self.permissions.entry(key) {
+            Entry::Vacant(entry) => {
+                entry.insert(RoleModelPerm { permission: p });
+            }
+            Entry::Occupied(_) => {
+                self.pending_errors.push(format!(
+                    "duplicate permission for model `{model}` role `{role}`"
+                ));
+            }
+        }
+        self
+    }
+
+    pub fn anonymous_role(mut self, name: &str) -> Self {
+        self.anonymous_role = name.to_string();
+        self
+    }
+    /// Set the stable service identity used by generated client manifests.
+    ///
+    /// [`GraphqlEngine::from_manifest`] supplies this automatically from the
+    /// project manifest. This setter is intended for manually assembled
+    /// engines, which otherwise cannot export a client manifest safely.
+    pub fn service_id(mut self, service_id: impl Into<String>) -> Self {
+        let service_id = service_id.into();
+        if service_id.trim().is_empty() {
+            self.pending_errors
+                .push("GraphQL client service ID must not be empty".into());
+            return self;
+        }
+        if let Some(binding) = &self.command_binding {
+            if binding.service_id != service_id {
+                self.pending_errors.push(format!(
+                    "GraphQL service ID `{service_id}` does not match bound executable service ID `{}`",
+                    binding.service_id
+                ));
+                return self;
+            }
+        }
+        if let Some(existing) = self.service_id.as_deref() {
+            if existing != service_id {
+                self.pending_errors.push(format!(
+                    "GraphQL service ID was already configured as `{existing}` and cannot be changed to `{service_id}`"
+                ));
+                return self;
+            }
+        }
+        self.service_id = Some(service_id);
+        self
+    }
+
+    /// Configure the stable deployment key used for opaque GraphQL protocol
+    /// tokens.
+    ///
+    /// All replicas serving the same endpoint namespace must receive the same
+    /// key, and rotations intentionally create new cache/projection scopes.
+    /// The key is never exposed to resolvers or serialized to clients.
+    pub fn protocol_token_key(mut self, key: [u8; 32]) -> Self {
+        if key.iter().all(|byte| *byte == 0) {
+            self.pending_errors
+                .push("GraphQL protocol token key must not be all zero".into());
+            return self;
+        }
+        self.protocol_token_key = Some(key);
+        self
+    }
+
+    /// Optionally isolate protocol tokens for one stable public endpoint.
+    ///
+    /// When omitted, the engine's service ID is the namespace. This is useful
+    /// when the same service exposes independently deployed GraphQL surfaces.
+    pub fn protocol_namespace(mut self, namespace: impl Into<String>) -> Self {
+        let namespace = namespace.into();
+        if namespace.trim().is_empty() {
+            self.pending_errors
+                .push("GraphQL protocol namespace must not be empty".into());
+            return self;
+        }
+        if namespace.len() > 255 || namespace.chars().any(char::is_control) {
+            self.pending_errors.push(
+                "GraphQL protocol namespace must be at most 255 bytes and contain no control characters"
+                    .into(),
+            );
+            return self;
+        }
+        self.protocol_namespace = Some(namespace);
+        self
+    }
+
+    /// Register one exact named application surface for generated clients.
+    ///
+    /// Runtime requests may select only this frozen name/role set. The server
+    /// still authorizes every request as its verified concrete role; the
+    /// application surface controls only the schema generation presented to
+    /// the client.
+    pub fn client_application_surface(
+        mut self,
+        application: impl Into<String>,
+        roles: impl IntoIterator<Item = impl Into<String>>,
+    ) -> Self {
+        let application = application.into();
+        let mut roles = roles.into_iter().map(Into::into).collect::<Vec<String>>();
+        roles.sort();
+        roles.dedup();
+        if application.is_empty()
+            || application.len() > 128
+            || application.trim() != application
+            || application.chars().any(char::is_control)
+        {
+            self.pending_errors.push(
+                "GraphQL client application name must be 1..=128 bytes, have no surrounding whitespace, and contain no control characters"
+                    .into(),
+            );
+            return self;
+        }
+        if roles.is_empty()
+            || roles.iter().any(|role| {
+                role.is_empty()
+                    || role.len() > 128
+                    || role.trim() != role
+                    || role.chars().any(char::is_control)
+            })
+        {
+            self.pending_errors.push(format!(
+                "GraphQL client application `{application}` must declare one or more bounded non-empty roles"
+            ));
+            return self;
+        }
+        if self
+            .client_applications
+            .insert(application.clone(), roles)
+            .is_some()
+        {
+            self.pending_errors.push(format!(
+                "GraphQL client application `{application}` was registered more than once"
+            ));
+        }
+        self
+    }
+
+    /// Derive GraphQL command mutations from the service's typed executable
+    /// inventory. This is the authoritative path: no second command list is
+    /// accepted, and attachment later verifies the complete structural digest
+    /// plus exact Rust input/output `TypeId`s.
+    pub fn service(mut self, service: &Service) -> Self {
+        if self.command_binding.is_some() {
+            self.pending_errors
+                .push("GraphQL service command inventory was configured more than once".into());
+            return self;
+        }
+        let binding = match service.typed_command_binding() {
+            Ok(binding) => binding,
+            Err(error) => {
+                self.pending_errors.push(error);
+                return self;
+            }
+        };
+        if let Some(configured) = self.service_id.as_deref() {
+            if configured != binding.service_id {
+                self.pending_errors.push(format!(
+                    "GraphQL service ID `{configured}` does not match executable service ID `{}`",
+                    binding.service_id
+                ));
+                return self;
+            }
+        }
+        let contracts = service.typed_command_contracts();
+        match TypedCommandInventory::from_contracts(&contracts) {
+            Ok(commands) => self.typed_commands = commands,
+            Err(error) => {
+                self.pending_errors.push(error);
+                return self;
+            }
+        }
+        self.service_id = Some(binding.service_id.clone());
+        self.command_binding = Some(binding);
+        self
+    }
+    pub fn default_limit(mut self, n: u64) -> Self {
+        self.default_limit = n;
+        self
+    }
+    pub fn max_limit(mut self, n: u64) -> Self {
+        self.max_limit = n;
+        self
+    }
+    pub fn max_depth(mut self, n: usize) -> Self {
+        self.max_depth = n;
+        self
+    }
+    /// Maximum nested-selection complexity budget (default
+    /// [`crate::graphql::complexity::DEFAULT_MAX_COMPLEXITY`]).
+    ///
+    /// Cost uses relationship-aware weights (see `complexity` module), not only
+    /// flat GraphQL field counts, so multi-level `has_many` trees are bounded.
+    pub fn max_complexity(mut self, n: usize) -> Self {
+        self.max_complexity = n;
+        self
+    }
+    pub fn max_in_list(mut self, n: usize) -> Self {
+        self.max_in_list = n;
+        self
+    }
+    /// Cap width of a single `_and` / `_or` list in client `where` (default 256).
+    pub fn max_bool_width(mut self, n: usize) -> Self {
+        self.max_bool_width = n;
+        self
+    }
+    /// Fail closed on unknown or ungranted client `where` / `order_by` keys.
+    ///
+    /// **Default: `true`.** Set `false` only for intentional Hasura-style
+    /// soft-skip of unknown keys (not recommended for production).
+    pub fn strict_where(mut self, on: bool) -> Self {
+        self.strict_where = on;
+        self
+    }
+    pub fn introspection_for_anonymous(mut self, on: bool) -> Self {
+        self.introspection_for_anonymous = on;
+        self
+    }
+    /// Declare projector topology for client invalidation planning. The model
+    /// and dependency IDs are validated when the one shared Surface is built.
+    pub fn client_projectors(
+        mut self,
+        projectors: impl IntoIterator<Item = SurfaceProjector>,
+    ) -> Self {
+        self.projectors = projectors.into_iter().map(Into::into).collect();
+        self
+    }
+
+    /// Declare a mixed client/query registry of async projectors and
+    /// same-transaction-only projection owners.
+    pub fn client_projection_owners(
+        mut self,
+        projectors: impl IntoIterator<Item = SurfaceProjectionOwner>,
+    ) -> Self {
+        self.projectors = projectors.into_iter().collect();
+        self
+    }
+    pub fn statement_timeout(mut self, d: Duration) -> Self {
+        self.statement_timeout = d;
+        self
+    }
+    /// Enable the GraphiQL IDE on `GET /graphql`.
+    ///
+    /// GraphiQL's full introspection query receives an isolated depth/complexity
+    /// allowance. Enabling an operational IDE never changes application query
+    /// limits, generated client manifests, or schema fingerprints.
+    pub fn graphiql(mut self, on: bool) -> Self {
+        self.graphiql = on;
+        self
+    }
+    /// Configure GraphQL HTTP identity mode (TrustedProxy / OidcBearer / Hybrid / DevHeaders).
+    pub fn identity(mut self, config: IdentityConfig) -> Self {
+        self.identity = config;
+        self
+    }
+    pub fn change_stream(mut self, rx: tokio::sync::broadcast::Receiver<ReadModelChange>) -> Self {
+        self.change_rx = Some(rx);
+        self
+    }
+
+    pub fn build(mut self) -> Result<GraphqlEngine, GraphqlBuildError> {
+        if !self.pending_errors.is_empty() {
+            return Err(GraphqlBuildError(self.pending_errors.join("; ")));
+        }
+        if self.protocol_namespace.is_some() && self.protocol_token_key.is_none() {
+            return Err(GraphqlBuildError(
+                "GraphQL protocol namespace requires a protocol token key".into(),
+            ));
+        }
+        if self.protocol_token_key.is_some() && self.service_id.is_none() {
+            return Err(GraphqlBuildError(
+                "GraphQL protocol tokens require a stable service ID; construct the engine with GraphqlEngine::from_manifest or GraphqlEngineBuilder::service_id"
+                    .into(),
+            ));
+        }
+
+        let model_schemas = self
+            .catalog
+            .iter()
+            .map(|(model, entry)| (model.clone(), entry.schema.clone()))
+            .collect::<BTreeMap<_, _>>();
+        self.typed_commands
+            .bind_direct_projection_targets(&self.projectors, &model_schemas)
+            .map_err(GraphqlBuildError)?;
+
+        if let Some(expected) = self.command_binding.as_ref() {
+            let service_id = self.service_id.as_deref().ok_or_else(|| {
+                GraphqlBuildError(
+                    "bound typed command inventory is missing its GraphQL service ID".into(),
+                )
+            })?;
+            let contracts = self.typed_commands.contracts_for_binding();
+            let actual = TypedServiceCommandBinding::from_contracts(service_id, &contracts)
+                .map_err(GraphqlBuildError)?;
+            // The builder copied this exact private command inventory from the
+            // service and prevents later replacement. Its only intentional
+            // structural change is the framework-owned direct-owner binding
+            // above, so retain the pre-bind exact Rust type proof and publish
+            // the final bound fingerprint for Service attachment.
+            if actual.service_id != expected.service_id || actual.types != expected.types {
+                return Err(GraphqlBuildError(
+                    "final GraphQL command inventory differs from the bound executable service inventory"
+                        .into(),
+                ));
+            }
+            self.command_binding = Some(actual);
+        }
+
+        // Validate permissions.
+        let declared_roles = self.roles.clone();
+        let anonymous = self.anonymous_role.clone();
+        let perm_keys: Vec<_> = self.permissions.keys().cloned().collect();
+        for (model, role) in &perm_keys {
+            if let Some(roles) = &declared_roles {
+                if !roles.contains(role) && role != &anonymous {
+                    return Err(GraphqlBuildError(format!(
+                        "permission for undeclared role `{role}` (model `{model}`)"
+                    )));
+                }
+            }
+            let entry = self.catalog.get(model).ok_or_else(|| {
+                GraphqlBuildError(format!("permission for unknown model `{model}`"))
+            })?;
+            let perm = &self.permissions[&(model.clone(), role.clone())].permission;
+
+            // Column allowlist validation.
+            if !perm.all_columns {
+                if let Some(cols) = &perm.columns {
+                    for col in cols {
+                        if !entry
+                            .schema
+                            .columns
+                            .iter()
+                            .any(|c| c.column_name == *col && !c.skipped)
+                        {
+                            return Err(GraphqlBuildError(format!(
+                                "unknown column `{col}` in permission for `{model}` role `{role}`"
+                            )));
+                        }
+                    }
+                }
+            }
+
+            if let Some(filter) = &perm.row_filter {
+                validate_filter(
+                    filter,
+                    &entry.schema,
+                    &self.catalog,
+                    role == &anonymous,
+                    model,
+                    role,
+                )?;
+            }
+        }
+
+        // Name grammar / collisions across exposed models.
+        validate_generated_names(&self.catalog)?;
+
+        // m2m resolution for catalog relationships used in permissions/schema.
+        for entry in self.catalog.values() {
+            for rel in &entry.schema.relationships {
+                if matches!(rel.kind, RelationshipKind::ManyToMany) {
+                    if rel.through.is_none() {
+                        return Err(GraphqlBuildError(format!(
+                            "model `{}` relationship `{}` many-to-many must declare `through`",
+                            entry.schema.model_name, rel.field_name
+                        )));
+                    }
+                    if let (Some(target), Some(through_name)) =
+                        (self.catalog.get(&rel.target_model), rel.through.as_deref())
+                    {
+                        if let Some(through_model) = self.by_table.get(through_name) {
+                            if let Some(through) = self.catalog.get(through_model) {
+                                resolve_m2m_target_foreign_key(
+                                    &entry.schema,
+                                    rel,
+                                    &through.schema,
+                                    &target.schema,
+                                )
+                                .map_err(|e| GraphqlBuildError(e.to_string()))?;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        let dialect = match &self.pool {
+            #[cfg(feature = "postgres")]
+            GraphqlPool::Postgres(_) => SqlDialect::Postgres,
+            #[cfg(feature = "sqlite")]
+            GraphqlPool::Sqlite(_) => SqlDialect::Sqlite,
+            #[allow(unreachable_patterns)]
+            _ => {
+                return Err(GraphqlBuildError(
+                    "GraphqlPool has no store feature enabled".into(),
+                ));
+            }
+        };
+
+        let tables: Vec<TableSchema> = self
+            .catalog
+            .values()
+            .map(|entry| entry.schema.clone())
+            .collect();
+        let surface_options = SurfaceOptions {
+            dialect: match dialect {
+                SqlDialect::Sqlite => SurfaceDialect::Sqlite,
+                SqlDialect::Postgres => SurfaceDialect::Postgres,
+            },
+            aggregates: true,
+            subscriptions: true,
+            default_limit: self.default_limit,
+            max_limit: self.max_limit,
+        };
+        let full_surface = Arc::new(
+            build_surface(&tables, &surface_options)
+                .map_err(GraphqlBuildError)?
+                .with_typed_commands(&self.typed_commands)
+                .map_err(GraphqlBuildError)?
+                .with_service_binding(self.command_binding.clone())
+                .with_projection_owners(self.projectors.clone())
+                .map_err(GraphqlBuildError)?,
+        );
+        let query_protocol = if self.protocol_token_key.is_some() {
+            QueryProtocolRuntime::compile(&full_surface).map_err(GraphqlBuildError)?
+        } else {
+            QueryProtocolRuntime::default()
+        };
+
+        let mut roles: BTreeSet<String> = self.permissions.keys().map(|(_, r)| r.clone()).collect();
+        if let Some(declared) = &declared_roles {
+            roles.extend(declared.iter().cloned());
+        }
+        roles.insert(anonymous.clone());
+
+        // Build per-role dynamic schemas.
+        let mut schemas = HashMap::new();
+        let mut graphiql_schemas = HashMap::new();
+        let mut role_surfaces = BTreeMap::new();
+        let mut protocol_roles = BTreeMap::new();
+        for role in &roles {
+            let grants = role_grants_from_model_role_perms(
+                role,
+                self.permissions
+                    .iter()
+                    .map(|(key, value)| (key, &value.permission)),
+            );
+            let role_surface = Arc::new(
+                surface_for_role(&full_surface, role, &grants).map_err(GraphqlBuildError)?,
+            );
+            let schema = dyn_schema::build_role_schema(
+                &role_surface,
+                self.max_depth,
+                self.max_complexity,
+                role == &anonymous && !self.introspection_for_anonymous,
+            )
+            .map_err(GraphqlBuildError)?;
+            if self.graphiql {
+                let graphiql_schema = dyn_schema::build_role_schema(
+                    &role_surface,
+                    self.max_depth.max(GRAPHIQL_INTROSPECTION_MAX_DEPTH_FLOOR),
+                    self.max_complexity
+                        .max(GRAPHIQL_INTROSPECTION_MAX_COMPLEXITY_FLOOR),
+                    role == &anonymous && !self.introspection_for_anonymous,
+                )
+                .map_err(GraphqlBuildError)?;
+                graphiql_schemas.insert(role.clone(), graphiql_schema);
+            }
+            if self.protocol_token_key.is_some() {
+                let service_id = self
+                    .service_id
+                    .as_deref()
+                    .expect("protocol configuration validated a service ID");
+                let (authorization_fingerprint, claim_keys) =
+                    role_authorization_info(role, &self.permissions)?;
+                let manifest = DistributedClientSurfaceExport::from_selected_with_execution(
+                    service_id,
+                    Arc::clone(&role_surface),
+                    ClientExecutionLimits::from_runtime(
+                        self.max_depth,
+                        self.max_complexity,
+                        self.max_bool_width,
+                        self.max_in_list,
+                    )
+                    .map_err(|error| GraphqlBuildError(error.to_string()))?,
+                )
+                .and_then(|export| export.manifest())
+                .map_err(|error| {
+                    GraphqlBuildError(format!(
+                        "failed to derive GraphQL protocol surface for role `{role}`: {error}"
+                    ))
+                })?;
+                let trusted_presets = protocol_trusted_presets(&manifest)?;
+                protocol_roles.insert(
+                    role.clone(),
+                    ProtocolRoleInfo {
+                        surface: ProtocolSurfaceInfo {
+                            schema_fingerprint: manifest.schema_fingerprint,
+                            protocol_fingerprint: manifest.protocol_fingerprint,
+                            trusted_presets,
+                        },
+                        authorization_fingerprint,
+                        claim_keys,
+                    },
+                );
+            }
+            schemas.insert(role.clone(), schema);
+            role_surfaces.insert(role.clone(), role_surface);
+        }
+
+        let mut application_surfaces = BTreeMap::new();
+        let mut protocol_applications = BTreeMap::new();
+        for (application, application_roles) in &self.client_applications {
+            let mut grants_by_role = BTreeMap::new();
+            for role in application_roles {
+                if !role_surfaces.contains_key(role) {
+                    return Err(GraphqlBuildError(format!(
+                        "client application surface `{application}` references unconfigured role `{role}`"
+                    )));
+                }
+                grants_by_role.insert(
+                    role.clone(),
+                    role_grants_from_model_role_perms(
+                        role,
+                        self.permissions
+                            .iter()
+                            .map(|(key, value)| (key, &value.permission)),
+                    ),
+                );
+            }
+            let application_surface = Arc::new(
+                surface_for_application(
+                    &full_surface,
+                    application,
+                    application_roles,
+                    &grants_by_role,
+                )
+                .map_err(GraphqlBuildError)?,
+            );
+            if self.protocol_token_key.is_some() {
+                let service_id = self
+                    .service_id
+                    .as_deref()
+                    .expect("protocol configuration validated a service ID");
+                let manifest = DistributedClientSurfaceExport::from_selected_with_execution(
+                    service_id,
+                    Arc::clone(&application_surface),
+                    ClientExecutionLimits::from_runtime(
+                        self.max_depth,
+                        self.max_complexity,
+                        self.max_bool_width,
+                        self.max_in_list,
+                    )
+                    .map_err(|error| GraphqlBuildError(error.to_string()))?,
+                )
+                .and_then(|export| export.manifest())
+                .map_err(|error| {
+                    GraphqlBuildError(format!(
+                        "failed to derive GraphQL protocol surface for application `{application}`: {error}"
+                    ))
+                })?;
+                let trusted_presets = protocol_trusted_presets(&manifest)?;
+                protocol_applications.insert(
+                    application.clone(),
+                    ProtocolApplicationInfo {
+                        roles: application_roles.clone(),
+                        surface: ProtocolSurfaceInfo {
+                            schema_fingerprint: manifest.schema_fingerprint,
+                            protocol_fingerprint: manifest.protocol_fingerprint,
+                            trusted_presets,
+                        },
+                    },
+                );
+            }
+            application_surfaces.insert(application.clone(), application_surface);
+        }
+
+        let change_hub = crate::graphql::subscribe::ChangeHub::new();
+        if let Some(rx) = self.change_rx {
+            crate::graphql::subscribe::spawn_change_forwarder(change_hub.clone(), rx);
+        }
+
+        let protocol = self.protocol_token_key.map(|key| {
+            let service_id = self
+                .service_id
+                .clone()
+                .expect("protocol configuration validated a service ID");
+            ProtocolRuntime {
+                codec: ProtocolTokenCodec::new(key),
+                namespace: self
+                    .protocol_namespace
+                    .unwrap_or_else(|| service_id.clone()),
+                service_id,
+                roles: protocol_roles,
+                applications: protocol_applications,
+            }
+        });
+        let identity_validator = self.identity.oidc.clone().map(OidcValidator::new);
+        let inner = Arc::new(EngineInner {
+            service_id: self.service_id,
+            command_binding: self.command_binding,
+            causal_storage_identity: self.causal_storage_identity,
+            pool: self.pool,
+            catalog: self.catalog,
+            by_table: self.by_table,
+            permissions: self.permissions,
+            roles,
+            anonymous_role: anonymous,
+            default_limit: self.default_limit,
+            max_limit: self.max_limit,
+            max_depth: self.max_depth,
+            max_complexity: self.max_complexity,
+            max_in_list: self.max_in_list,
+            max_bool_width: self.max_bool_width,
+            strict_where: self.strict_where,
+            introspection_for_anonymous: self.introspection_for_anonymous,
+            statement_timeout: self.statement_timeout,
+            graphiql: self.graphiql,
+            typed_commands: self.typed_commands,
+            role_surfaces,
+            application_surfaces,
+            schemas,
+            graphiql_schemas,
+            change_hub,
+            dialect,
+            identity: self.identity,
+            identity_validator,
+            protocol,
+            query_protocol,
+        });
+
+        Ok(GraphqlEngine { inner })
+    }
+}
diff --git a/src/graphql/engine/core.rs b/src/graphql/engine/core.rs
new file mode 100644
index 00000000..154733ce
--- /dev/null
+++ b/src/graphql/engine/core.rs
@@ -0,0 +1,277 @@
+use super::*;
+
+#[derive(Clone)]
+pub enum GraphqlPool {
+    #[cfg(feature = "postgres")]
+    Postgres(sqlx::PgPool),
+    #[cfg(feature = "sqlite")]
+    Sqlite(sqlx::SqlitePool),
+}
+
+#[cfg(feature = "postgres")]
+impl From<sqlx::PgPool> for GraphqlPool {
+    fn from(pool: sqlx::PgPool) -> Self {
+        GraphqlPool::Postgres(pool)
+    }
+}
+
+#[cfg(feature = "sqlite")]
+impl From<sqlx::SqlitePool> for GraphqlPool {
+    fn from(pool: sqlx::SqlitePool) -> Self {
+        GraphqlPool::Sqlite(pool)
+    }
+}
+
+/// Database source for a GraphQL engine.
+///
+/// Passing a Distributed repository handle instead of its raw pool preserves
+/// the opaque storage identity required to prove that `Projected` commands
+/// update the same database read by GraphQL.
+#[derive(Clone)]
+pub struct GraphqlPoolSource {
+    pub(crate) pool: GraphqlPool,
+    pub(crate) causal_storage_identity: Option<crate::command_ledger::CausalStorageIdentity>,
+}
+
+impl From<GraphqlPool> for GraphqlPoolSource {
+    fn from(pool: GraphqlPool) -> Self {
+        Self {
+            pool,
+            causal_storage_identity: None,
+        }
+    }
+}
+
+#[cfg(feature = "postgres")]
+impl From<sqlx::PgPool> for GraphqlPoolSource {
+    fn from(pool: sqlx::PgPool) -> Self {
+        GraphqlPool::from(pool).into()
+    }
+}
+
+#[cfg(feature = "sqlite")]
+impl From<sqlx::SqlitePool> for GraphqlPoolSource {
+    fn from(pool: sqlx::SqlitePool) -> Self {
+        GraphqlPool::from(pool).into()
+    }
+}
+
+#[cfg(feature = "postgres")]
+impl From<&crate::PostgresRepository> for GraphqlPoolSource {
+    fn from(repository: &crate::PostgresRepository) -> Self {
+        Self {
+            pool: GraphqlPool::Postgres(repository.pool().clone()),
+            causal_storage_identity: Some(repository.causal_storage_identity()),
+        }
+    }
+}
+
+#[cfg(feature = "sqlite")]
+impl From<&crate::SqliteRepository> for GraphqlPoolSource {
+    fn from(repository: &crate::SqliteRepository) -> Self {
+        Self {
+            pool: GraphqlPool::Sqlite(repository.pool().clone()),
+            causal_storage_identity: Some(repository.causal_storage_identity()),
+        }
+    }
+}
+
+#[cfg(all(test, feature = "sqlite"))]
+mod graphql_pool_source_identity_tests {
+    use super::GraphqlPoolSource;
+
+    fn pool() -> sqlx::SqlitePool {
+        sqlx::sqlite::SqlitePoolOptions::new()
+            .connect_lazy("sqlite::memory:")
+            .expect("lazy SQLite pool")
+    }
+
+    #[tokio::test]
+    async fn raw_pool_has_no_causal_storage_identity() {
+        let source = GraphqlPoolSource::from(pool());
+
+        assert!(source.causal_storage_identity.is_none());
+    }
+
+    #[tokio::test]
+    async fn repository_reference_carries_its_opaque_storage_identity() {
+        let repository = crate::SqliteRepository::new(pool());
+        let source = GraphqlPoolSource::from(&repository);
+
+        assert_eq!(
+            source.causal_storage_identity,
+            Some(repository.causal_storage_identity())
+        );
+    }
+
+    #[tokio::test]
+    async fn repository_and_pool_source_clones_preserve_storage_identity() {
+        let repository = crate::SqliteRepository::new(pool());
+        let repository_clone = repository.clone();
+        let source = GraphqlPoolSource::from(&repository);
+        let source_clone = source.clone();
+
+        assert_eq!(
+            GraphqlPoolSource::from(&repository_clone).causal_storage_identity,
+            source.causal_storage_identity
+        );
+        assert_eq!(
+            source_clone.causal_storage_identity,
+            source.causal_storage_identity
+        );
+    }
+
+    #[tokio::test]
+    async fn independent_repositories_over_the_same_pool_have_distinct_identities() {
+        let pool = pool();
+        let first = crate::SqliteRepository::new(pool.clone());
+        let second = crate::SqliteRepository::new(pool);
+
+        assert_ne!(
+            GraphqlPoolSource::from(&first).causal_storage_identity,
+            GraphqlPoolSource::from(&second).causal_storage_identity
+        );
+    }
+}
+
+#[derive(Debug)]
+pub struct GraphqlBuildError(pub String);
+
+impl std::fmt::Display for GraphqlBuildError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl std::error::Error for GraphqlBuildError {}
+
+impl From<String> for GraphqlBuildError {
+    fn from(s: String) -> Self {
+        Self(s)
+    }
+}
+
+impl From<&str> for GraphqlBuildError {
+    fn from(s: &str) -> Self {
+        Self(s.to_string())
+    }
+}
+
+#[derive(Clone)]
+pub(crate) struct CatalogEntry {
+    pub schema: TableSchema,
+    pub exposed: bool,
+}
+
+#[derive(Clone)]
+pub(crate) struct RoleModelPerm {
+    pub permission: ReadPermission,
+}
+
+#[derive(Clone)]
+pub(crate) struct ProtocolSurfaceInfo {
+    pub(crate) schema_fingerprint: String,
+    pub(crate) protocol_fingerprint: String,
+    pub(crate) trusted_presets: Vec<ClientTrustedPresetDescriptor>,
+}
+
+#[derive(Clone)]
+pub(crate) struct ProtocolRoleInfo {
+    pub(crate) surface: ProtocolSurfaceInfo,
+    pub(crate) authorization_fingerprint: String,
+    pub(crate) claim_keys: Vec<String>,
+}
+
+#[derive(Clone)]
+pub(crate) struct ProtocolApplicationInfo {
+    pub(crate) roles: Vec<String>,
+    pub(crate) surface: ProtocolSurfaceInfo,
+}
+
+#[derive(Clone)]
+pub(crate) struct ProtocolRuntime {
+    pub(crate) codec: ProtocolTokenCodec,
+    pub(crate) namespace: String,
+    pub(crate) service_id: String,
+    pub(crate) roles: BTreeMap<String, ProtocolRoleInfo>,
+    pub(crate) applications: BTreeMap<String, ProtocolApplicationInfo>,
+}
+
+pub(crate) struct EngineInner {
+    /// Stable service identity used by client manifest hashes and cache scopes.
+    /// Manifest-built engines populate this automatically; manual builders may
+    /// opt in with [`GraphqlEngineBuilder::service_id`].
+    pub service_id: Option<String>,
+    pub command_binding: Option<TypedServiceCommandBinding>,
+    pub causal_storage_identity: Option<crate::command_ledger::CausalStorageIdentity>,
+    pub pool: GraphqlPool,
+    pub catalog: BTreeMap<String, CatalogEntry>,
+    pub by_table: BTreeMap<String, String>,
+    pub permissions: BTreeMap<(String, String), RoleModelPerm>,
+    pub roles: BTreeSet<String>,
+    pub anonymous_role: String,
+    pub default_limit: u64,
+    pub max_limit: u64,
+    pub max_depth: usize,
+    #[allow(dead_code)]
+    pub max_complexity: usize,
+    pub max_in_list: usize,
+    /// Max length of a single `_and` / `_or` list in client `where` (breadth DoS).
+    pub max_bool_width: usize,
+    /// When true (default), unknown/ungranted client `where` and `order_by`
+    /// keys fail the request instead of soft-skipping.
+    pub strict_where: bool,
+    #[allow(dead_code)]
+    pub introspection_for_anonymous: bool,
+    pub statement_timeout: Duration,
+    pub graphiql: bool,
+    pub(crate) typed_commands: TypedCommandInventory,
+    pub role_surfaces: BTreeMap<String, Arc<Surface>>,
+    pub application_surfaces: BTreeMap<String, Arc<Surface>>,
+    pub schemas: HashMap<String, async_graphql::dynamic::Schema>,
+    /// Relaxed schemas selected only for pure introspection while GraphiQL is
+    /// enabled. Application operations always use `schemas` and its exact
+    /// manifest-fingerprinted execution limits.
+    pub graphiql_schemas: HashMap<String, async_graphql::dynamic::Schema>,
+    pub change_hub: crate::graphql::subscribe::ChangeHub,
+    pub dialect: SqlDialect,
+    /// Identity mode for HTTP session construction (see `identity` module).
+    pub identity: IdentityConfig,
+    pub(crate) identity_validator: Option<OidcValidator>,
+    pub(crate) protocol: Option<ProtocolRuntime>,
+    pub(crate) query_protocol: QueryProtocolRuntime,
+}
+
+pub struct GraphqlEngine {
+    pub(crate) inner: Arc<EngineInner>,
+}
+
+pub struct GraphqlEngineBuilder {
+    pub(crate) service_id: Option<String>,
+    pub(crate) protocol_token_key: Option<[u8; 32]>,
+    pub(crate) protocol_namespace: Option<String>,
+    pub(crate) client_applications: BTreeMap<String, Vec<String>>,
+    pub(crate) command_binding: Option<TypedServiceCommandBinding>,
+    pub(crate) causal_storage_identity: Option<crate::command_ledger::CausalStorageIdentity>,
+    pub(crate) pool: GraphqlPool,
+    pub(crate) catalog: BTreeMap<String, CatalogEntry>,
+    pub(crate) by_table: BTreeMap<String, String>,
+    pub(crate) permissions: BTreeMap<(String, String), RoleModelPerm>,
+    pub(crate) roles: Option<BTreeSet<String>>,
+    pub(crate) anonymous_role: String,
+    pub(crate) default_limit: u64,
+    pub(crate) max_limit: u64,
+    pub(crate) max_depth: usize,
+    pub(crate) max_complexity: usize,
+    pub(crate) max_in_list: usize,
+    pub(crate) max_bool_width: usize,
+    pub(crate) strict_where: bool,
+    pub(crate) introspection_for_anonymous: bool,
+    pub(crate) statement_timeout: Duration,
+    pub(crate) graphiql: bool,
+    pub(crate) typed_commands: TypedCommandInventory,
+    pub(crate) projectors: Vec<SurfaceProjectionOwner>,
+    pub(crate) change_rx: Option<tokio::sync::broadcast::Receiver<ReadModelChange>>,
+    pub(crate) pending_errors: Vec<String>,
+    pub(crate) identity: IdentityConfig,
+}
diff --git a/src/graphql/engine/introspection.rs b/src/graphql/engine/introspection.rs
new file mode 100644
index 00000000..df41a4e9
--- /dev/null
+++ b/src/graphql/engine/introspection.rs
@@ -0,0 +1,223 @@
+use super::*;
+
+/// True only when the selected query operation contains introspection root
+/// fields and nothing application-owned.
+///
+/// GraphiQL needs a deeper schema-introspection budget than application
+/// operations. Selection is deliberately fail-closed: mixed roots, missing or
+/// recursive fragments, over-budget documents, ambiguous operations,
+/// mutations, and subscriptions all stay on the normal
+/// manifest-fingerprinted schema.
+pub(crate) fn is_pure_introspection_request(request: &mut Request) -> bool {
+    if request.introspection_mode == async_graphql::IntrospectionMode::Disabled {
+        return false;
+    }
+    let operation_name = request.operation_name.clone();
+    // `Request::set_parsed_query` is public and async-graphql executes that
+    // cached AST when present. Inspect (and, for ordinary requests, populate)
+    // the exact AST execution will consume rather than reparsing `query`.
+    let Ok(document) = request.parsed_query() else {
+        return false;
+    };
+    let mut operations = document.operations.iter();
+    let operation = if let Some(requested) = operation_name.as_deref() {
+        operations
+            .find(|(name, _)| name.map(|name| name.as_str()) == Some(requested))
+            .map(|(_, operation)| operation)
+    } else {
+        let first = operations.next().map(|(_, operation)| operation);
+        if operations.next().is_some() {
+            None
+        } else {
+            first
+        }
+    };
+    let Some(operation) = operation else {
+        return false;
+    };
+    if operation.node.ty != async_graphql::parser::types::OperationType::Query {
+        return false;
+    }
+
+    fn selection_is_introspection_only(
+        selection: &async_graphql::parser::types::SelectionSet,
+        document: &async_graphql::parser::types::ExecutableDocument,
+        visiting: &mut BTreeSet<String>,
+        completed: &mut HashMap<String, bool>,
+        remaining_selections: &mut usize,
+        depth: usize,
+    ) -> bool {
+        if depth > REQUEST_ANALYSIS_MAX_DEPTH
+            || selection.items.is_empty()
+            || selection.items.len() > *remaining_selections
+        {
+            return false;
+        }
+        *remaining_selections -= selection.items.len();
+        selection.items.iter().all(|item| match &item.node {
+            async_graphql::parser::types::Selection::Field(field) => matches!(
+                field.node.name.node.as_str(),
+                "__schema" | "__type" | "__typename"
+            ),
+            async_graphql::parser::types::Selection::InlineFragment(fragment) => {
+                selection_is_introspection_only(
+                    &fragment.node.selection_set.node,
+                    document,
+                    visiting,
+                    completed,
+                    remaining_selections,
+                    depth + 1,
+                )
+            }
+            async_graphql::parser::types::Selection::FragmentSpread(spread) => {
+                let name = spread.node.fragment_name.node.to_string();
+                if let Some(valid) = completed.get(&name) {
+                    return *valid;
+                }
+                if !visiting.insert(name.clone()) {
+                    return false;
+                }
+                let valid = document
+                    .fragments
+                    .get(&spread.node.fragment_name.node)
+                    .is_some_and(|fragment| {
+                        selection_is_introspection_only(
+                            &fragment.node.selection_set.node,
+                            document,
+                            visiting,
+                            completed,
+                            remaining_selections,
+                            depth + 1,
+                        )
+                    });
+                visiting.remove(&name);
+                completed.insert(name, valid);
+                valid
+            }
+        })
+    }
+
+    let mut remaining_selections = REQUEST_ANALYSIS_MAX_SELECTIONS;
+    selection_is_introspection_only(
+        &operation.node.selection_set.node,
+        &document,
+        &mut BTreeSet::new(),
+        &mut HashMap::new(),
+        &mut remaining_selections,
+        0,
+    )
+}
+
+/// Resolve whether GraphiQL should be enabled from environment variables.
+///
+/// Policy (scaffold + operators):
+/// - `GRAPHIQL` if set: on unless value is `0` / `false` / `off` / `no` (case-insensitive)
+/// - else: **off** when `RUST_ENV` / `ENV` / `APP_ENV` is `production` or `prod`
+/// - else: **on** (local/dev default)
+///
+/// Pure inputs so tests do not mutate process env. See [`graphiql_enabled_from_env`].
+pub fn graphiql_enabled_from_env_vars(
+    graphiql: Option<&str>,
+    rust_env: Option<&str>,
+    env: Option<&str>,
+    app_env: Option<&str>,
+) -> bool {
+    if let Some(v) = graphiql {
+        return !matches!(
+            v.to_ascii_lowercase().as_str(),
+            "0" | "false" | "off" | "no"
+        );
+    }
+    let prod = rust_env
+        .or(env)
+        .or(app_env)
+        .unwrap_or("")
+        .to_ascii_lowercase();
+    !matches!(prod.as_str(), "production" | "prod")
+}
+
+/// Read process env and apply [`graphiql_enabled_from_env_vars`].
+pub fn graphiql_enabled_from_env() -> bool {
+    graphiql_enabled_from_env_vars(
+        std::env::var("GRAPHIQL").ok().as_deref(),
+        std::env::var("RUST_ENV").ok().as_deref(),
+        std::env::var("ENV").ok().as_deref(),
+        std::env::var("APP_ENV").ok().as_deref(),
+    )
+}
+
+#[cfg(test)]
+mod graphiql_env_tests {
+    use super::graphiql_enabled_from_env_vars;
+
+    #[test]
+    fn production_rust_env_disables_graphiql() {
+        assert!(!graphiql_enabled_from_env_vars(
+            None,
+            Some("production"),
+            None,
+            None
+        ));
+        assert!(!graphiql_enabled_from_env_vars(
+            None,
+            Some("prod"),
+            None,
+            None
+        ));
+        assert!(!graphiql_enabled_from_env_vars(
+            None,
+            Some("PRODUCTION"),
+            None,
+            None
+        ));
+    }
+
+    #[test]
+    fn non_production_enables_graphiql_by_default() {
+        assert!(graphiql_enabled_from_env_vars(
+            None,
+            Some("development"),
+            None,
+            None
+        ));
+        assert!(graphiql_enabled_from_env_vars(None, None, None, None));
+    }
+
+    #[test]
+    fn explicit_graphiql_overrides_production() {
+        assert!(graphiql_enabled_from_env_vars(
+            Some("1"),
+            Some("production"),
+            None,
+            None
+        ));
+        assert!(!graphiql_enabled_from_env_vars(
+            Some("0"),
+            Some("development"),
+            None,
+            None
+        ));
+        assert!(!graphiql_enabled_from_env_vars(
+            Some("false"),
+            None,
+            None,
+            None
+        ));
+    }
+
+    #[test]
+    fn env_and_app_env_aliases() {
+        assert!(!graphiql_enabled_from_env_vars(
+            None,
+            None,
+            Some("production"),
+            None
+        ));
+        assert!(!graphiql_enabled_from_env_vars(
+            None,
+            None,
+            None,
+            Some("prod")
+        ));
+    }
+}
diff --git a/src/graphql/engine/live_resume.rs b/src/graphql/engine/live_resume.rs
new file mode 100644
index 00000000..9ae02658
--- /dev/null
+++ b/src/graphql/engine/live_resume.rs
@@ -0,0 +1,140 @@
+use super::*;
+
+const MAX_LIVE_RESUME_PROJECTION_BYTES: usize = 512;
+
+/// Parse the private request extension used by generated live operations.
+/// Invalid input is a conservative reset signal, never trusted cursor state.
+pub(crate) fn parse_requested_live_resume(request: &Request) -> RequestedLiveResume {
+    let Some(distributed) = request.extensions.get("distributed") else {
+        return RequestedLiveResume::Absent;
+    };
+    let Ok(distributed) = distributed.clone().into_json() else {
+        return RequestedLiveResume::Invalid;
+    };
+    let Some(distributed) = distributed.as_object() else {
+        return RequestedLiveResume::Invalid;
+    };
+    let Some(resume) = distributed.get("resume") else {
+        return RequestedLiveResume::Absent;
+    };
+    let Some(cursors) = resume
+        .as_object()
+        .and_then(|resume| resume.get("cursors"))
+        .and_then(serde_json::Value::as_array)
+    else {
+        return RequestedLiveResume::Invalid;
+    };
+    if cursors.len() > MAX_LIVE_RESUME_CURSORS {
+        return RequestedLiveResume::Invalid;
+    }
+
+    let mut parsed = Vec::with_capacity(cursors.len());
+    for cursor in cursors {
+        let Some(cursor) = cursor.as_object() else {
+            return RequestedLiveResume::Invalid;
+        };
+        let Some(projection) = cursor.get("projection").and_then(serde_json::Value::as_str) else {
+            return RequestedLiveResume::Invalid;
+        };
+        if projection.is_empty() || projection.len() > MAX_LIVE_RESUME_PROJECTION_BYTES {
+            return RequestedLiveResume::Invalid;
+        }
+        let Some(position) = cursor.get("position").and_then(serde_json::Value::as_str) else {
+            return RequestedLiveResume::Invalid;
+        };
+        let Ok(parsed_position) = position.parse::<u64>() else {
+            return RequestedLiveResume::Invalid;
+        };
+        if parsed_position.to_string() != position {
+            return RequestedLiveResume::Invalid;
+        }
+        let Some(token) = cursor.get("token").and_then(serde_json::Value::as_str) else {
+            return RequestedLiveResume::Invalid;
+        };
+        let Ok(token) = OpaqueProtocolToken::parse(token) else {
+            return RequestedLiveResume::Invalid;
+        };
+        parsed.push(DistributedLiveCursor {
+            projection: projection.to_string(),
+            position: position.to_string(),
+            token,
+        });
+    }
+    RequestedLiveResume::Cursors(parsed)
+}
+
+#[cfg(test)]
+mod live_resume_request_tests {
+    use super::*;
+
+    fn request_with_resume(value: serde_json::Value) -> Request {
+        serde_json::from_value(serde_json::json!({
+            "query": "subscription Watch { todos { id } }",
+            "extensions": { "distributed": { "resume": value } }
+        }))
+        .expect("GraphQL request")
+    }
+
+    #[test]
+    fn live_resume_request_is_bounded_and_canonical() {
+        let token = ProtocolTokenCodec::new([9; 32])
+            .issue(ProtocolTokenPurpose::LiveResume, &("bounded-test", 7_u64))
+            .unwrap();
+        let request = request_with_resume(serde_json::json!({
+            "cursors": [{
+                "projection": "todos",
+                "position": "7",
+                "token": token.as_str()
+            }]
+        }));
+        let RequestedLiveResume::Cursors(cursors) = parse_requested_live_resume(&request) else {
+            panic!("valid cursor must parse")
+        };
+        assert_eq!(cursors.len(), 1);
+        assert_eq!(cursors[0].projection, "todos");
+        assert_eq!(cursors[0].position, "7");
+
+        for invalid in [
+            serde_json::json!({"cursors": [{
+                "projection": "todos", "position": "07", "token": token.as_str()
+            }]}),
+            serde_json::json!({"cursors": [{
+                "projection": "todos", "position": "7", "token": "not-a-token"
+            }]}),
+            serde_json::json!({"cursors": "not-an-array"}),
+        ] {
+            assert_eq!(
+                parse_requested_live_resume(&request_with_resume(invalid)),
+                RequestedLiveResume::Invalid
+            );
+        }
+
+        let too_many = vec![
+            serde_json::json!({
+                "projection": "todos",
+                "position": "7",
+                "token": token.as_str()
+            });
+            MAX_LIVE_RESUME_CURSORS + 1
+        ];
+        assert_eq!(
+            parse_requested_live_resume(&request_with_resume(
+                serde_json::json!({"cursors": too_many})
+            )),
+            RequestedLiveResume::Invalid
+        );
+    }
+
+    #[test]
+    fn request_without_resume_remains_a_fresh_subscription() {
+        let request: Request = serde_json::from_value(serde_json::json!({
+            "query": "subscription Watch { todos { id } }",
+            "extensions": { "distributed": {} }
+        }))
+        .unwrap();
+        assert_eq!(
+            parse_requested_live_resume(&request),
+            RequestedLiveResume::Absent
+        );
+    }
+}
diff --git a/src/graphql/engine/metrics.rs b/src/graphql/engine/metrics.rs
new file mode 100644
index 00000000..cacef84a
--- /dev/null
+++ b/src/graphql/engine/metrics.rs
@@ -0,0 +1,134 @@
+use super::*;
+
+pub(crate) fn protocol_internal_error_response() -> Response {
+    Response::from_errors(vec![ServerError::new(
+        "internal protocol response error",
+        None,
+    )])
+}
+
+pub(crate) fn attach_protocol_response(
+    mut response: Response,
+    accumulator: Option<&ProtocolResponseAccumulator>,
+) -> Response {
+    let Some(accumulator) = accumulator else {
+        return response;
+    };
+    if accumulator.attach(&mut response).is_ok() {
+        return response;
+    }
+
+    // A resolver cannot shadow the framework-owned extension. Replace a
+    // colliding response with a closed internal error and attach the one
+    // authoritative envelope.
+    let mut failure = protocol_internal_error_response();
+    if accumulator.attach(&mut failure).is_ok() {
+        failure
+    } else {
+        protocol_internal_error_response()
+    }
+}
+
+pub(crate) fn resolve_role(session: &Session, anonymous: &str) -> String {
+    session
+        .role()
+        .filter(|r| !r.is_empty())
+        .map(|s| s.to_string())
+        .unwrap_or_else(|| anonymous.to_string())
+}
+
+/// Map GraphQL response errors to coarse metric `status` labels.
+///
+/// Privacy: only stable class names (`ok`, `timeout`, `bad_request`,
+/// `forbidden`, `internal`, `error`) — never user/tenant/SQL text.
+pub(crate) fn metrics_status_for_response(response: &Response) -> &'static str {
+    if !response.is_err() {
+        return "ok";
+    }
+    for err in &response.errors {
+        if let Some(ext) = &err.extensions {
+            if let Some(code) = ext.get("code") {
+                let code = format!("{code:?}").to_ascii_uppercase();
+                if code.contains("TIMEOUT") {
+                    return "timeout";
+                }
+                if code.contains("BAD_REQUEST") {
+                    return "bad_request";
+                }
+                if code.contains("FORBIDDEN") {
+                    return "forbidden";
+                }
+                if code.contains("INTERNAL") {
+                    return "internal";
+                }
+            }
+        }
+        let msg = err.message.to_ascii_lowercase();
+        if msg.contains("timeout") {
+            return "timeout";
+        }
+        if msg.contains("not configured") || msg.contains("forbidden") {
+            return "forbidden";
+        }
+    }
+    "error"
+}
+
+pub(crate) fn record_metrics(
+    session: &Session,
+    root_field: &str,
+    status: &str,
+    duration: Duration,
+) {
+    let _ = session;
+    #[cfg(feature = "metrics")]
+    crate::metrics::record_graphql_request(None, root_field, status, duration);
+    #[cfg(not(feature = "metrics"))]
+    let _ = (root_field, status, duration);
+}
+
+#[cfg(test)]
+mod metrics_status_tests {
+    use super::metrics_status_for_response;
+    use async_graphql::{ErrorExtensionValues, Response, ServerError};
+
+    fn response_with_code(code: &str, message: &str) -> Response {
+        let mut err = ServerError::new(message, None);
+        let mut ext = ErrorExtensionValues::default();
+        ext.set("code", code);
+        err.extensions = Some(ext);
+        Response::from_errors(vec![err])
+    }
+
+    #[test]
+    fn ok_when_no_errors() {
+        let resp = Response::new(async_graphql::Value::Null);
+        assert_eq!(metrics_status_for_response(&resp), "ok");
+    }
+
+    #[test]
+    fn maps_extension_codes() {
+        assert_eq!(
+            metrics_status_for_response(&response_with_code("TIMEOUT", "statement timeout")),
+            "timeout"
+        );
+        assert_eq!(
+            metrics_status_for_response(&response_with_code("BAD_REQUEST", "bad request")),
+            "bad_request"
+        );
+        assert_eq!(
+            metrics_status_for_response(&response_with_code("INTERNAL", "internal error")),
+            "internal"
+        );
+        assert_eq!(
+            metrics_status_for_response(&response_with_code("FORBIDDEN", "nope")),
+            "forbidden"
+        );
+    }
+
+    #[test]
+    fn maps_message_fallback_timeout() {
+        let resp = Response::from_errors(vec![ServerError::new("statement timeout", None)]);
+        assert_eq!(metrics_status_for_response(&resp), "timeout");
+    }
+}
diff --git a/src/graphql/engine/mod.rs b/src/graphql/engine/mod.rs
new file mode 100644
index 00000000..6489a9ad
--- /dev/null
+++ b/src/graphql/engine/mod.rs
@@ -0,0 +1,97 @@
+//! GraphqlEngine builder, validation, and execute entrypoint.
+#![allow(clippy::items_after_test_module)]
+
+use std::any::TypeId;
+use std::collections::{btree_map::Entry, BTreeMap, BTreeSet, HashMap};
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_graphql::{Request, Response, ServerError, Value};
+use futures_util::stream::{self, BoxStream};
+use futures_util::StreamExt;
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+use crate::manifest::DistributedProjectManifest;
+use crate::microsvc::{Service, Session, ROLE_KEY, USER_ID_KEY};
+use crate::read_model::{ReadModelChange, RelationalReadModelIncludes};
+use crate::table::{
+    resolve_m2m_target_foreign_key, ColumnType, RelationshipKind, TableKind, TableSchema,
+};
+
+use super::client_manifest::{
+    trusted_preset_descriptors, ClientExecutionLimits, ClientManifestError, ClientSurfaceIdentity,
+    ClientTrustedPresetDescriptor, DistributedClientManifest, DistributedClientSurfaceExport,
+};
+use super::command_contract::TypedServiceCommandBinding;
+use super::commands::TypedCommandInventory;
+use super::compile::{SqlDialect, SqlPlan};
+use super::execute;
+use super::filter::{validate_row_policy_operand_literal, FilterExpr, Operand};
+use super::identity::{IdentityConfig, IdentityMode, OidcValidator, VerifiedPrincipal};
+use super::naming::{
+    by_pk_field, is_valid_graphql_name, object_type_name, reserved_type_names, root_list_field,
+};
+use super::permissions::{
+    read, role_grants_from_model_role_perms, ModelPermissions, ReadPermission,
+};
+use super::protocol::{
+    DistributedEnvelopeV1, DistributedLiveCursor, DistributedTrustedPreset, OpaqueProtocolToken,
+    ProtocolResponseAccumulator, ProtocolTokenCodec, ProtocolTokenPurpose, RequestedLiveResume,
+    MAX_LIVE_RESUME_CURSORS,
+};
+use super::query_protocol::QueryProtocolRuntime;
+use super::schema as dyn_schema;
+use super::sdl::{graphql_sdl_for_tables_with_options, graphql_sdl_from_surface, SdlOptions};
+use super::surface::{
+    build_surface, surface_for_application, surface_for_role, Surface, SurfaceDialect,
+    SurfaceOptions, SurfaceProjectionOwner, SurfaceProjector, SurfaceSelection,
+};
+
+const GRAPHIQL_INTROSPECTION_MAX_DEPTH_FLOOR: usize = 15;
+const GRAPHIQL_INTROSPECTION_MAX_COMPLEXITY_FLOOR: usize = 10_000;
+const REQUEST_ANALYSIS_MAX_DEPTH: usize = 128;
+const REQUEST_ANALYSIS_MAX_SELECTIONS: usize = 4_096;
+
+mod auth;
+mod builder;
+mod core;
+mod introspection;
+mod live_resume;
+mod metrics;
+mod protocol;
+mod public_api;
+mod request;
+mod validation;
+
+#[cfg(all(test, any(feature = "sqlite", feature = "postgres")))]
+mod tests;
+
+pub use core::{
+    GraphqlBuildError, GraphqlEngine, GraphqlEngineBuilder, GraphqlPool, GraphqlPoolSource,
+};
+pub use introspection::{graphiql_enabled_from_env, graphiql_enabled_from_env_vars};
+
+pub(crate) use auth::{identity_mode_label, role_authorization_info};
+pub(crate) use core::{
+    CatalogEntry, EngineInner, ProtocolApplicationInfo, ProtocolRoleInfo, ProtocolRuntime,
+    ProtocolSurfaceInfo, RoleModelPerm,
+};
+pub(crate) use introspection::is_pure_introspection_request;
+pub(crate) use live_resume::parse_requested_live_resume;
+pub(crate) use metrics::resolve_role;
+pub(crate) use metrics::{
+    attach_protocol_response, metrics_status_for_response, protocol_internal_error_response,
+    record_metrics,
+};
+pub(crate) use protocol::{
+    has_multiple_protocol_query_roots, operation_fingerprint, protocol_multi_root_error_response,
+    protocol_trusted_presets, resolve_protocol_preset, select_protocol_surface,
+};
+pub(crate) use validation::{execute_plan, validate_filter, validate_generated_names};
+
+/// Public helper for tests: compile + naming surface.
+#[allow(dead_code)]
+pub fn core_sdl_for_catalog(tables: &[TableSchema]) -> Result<String, String> {
+    validation::core_sdl_for_catalog(tables)
+}
diff --git a/src/graphql/engine/protocol.rs b/src/graphql/engine/protocol.rs
new file mode 100644
index 00000000..9eeddaad
--- /dev/null
+++ b/src/graphql/engine/protocol.rs
@@ -0,0 +1,267 @@
+use super::*;
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct RequestedProtocolClient {
+    surface: ClientSurfaceIdentity,
+    schema_hash: String,
+}
+
+fn requested_protocol_client(request: &Request) -> Result<Option<RequestedProtocolClient>, ()> {
+    let Some(distributed) = request.extensions.get("distributed") else {
+        return Ok(None);
+    };
+    let distributed = distributed.clone().into_json().map_err(|_| ())?;
+    let distributed = distributed.as_object().ok_or(())?;
+    let Some(client) = distributed.get("client") else {
+        return Ok(None);
+    };
+    serde_json::from_value(client.clone())
+        .map(Some)
+        .map_err(|_| ())
+}
+
+pub(crate) fn select_protocol_surface<'a>(
+    runtime: &'a ProtocolRuntime,
+    role: &str,
+    request: &Request,
+) -> Result<(ClientSurfaceIdentity, &'a ProtocolSurfaceInfo), ()> {
+    let Some(requested) = requested_protocol_client(request)? else {
+        let info = runtime.roles.get(role).ok_or(())?;
+        return Ok((ClientSurfaceIdentity::role(role), &info.surface));
+    };
+    match requested.surface {
+        ClientSurfaceIdentity::Role { name } => {
+            if name != role {
+                return Err(());
+            }
+            let info = runtime.roles.get(&name).ok_or(())?;
+            if requested.schema_hash != info.surface.schema_fingerprint {
+                return Err(());
+            }
+            Ok((ClientSurfaceIdentity::role(name), &info.surface))
+        }
+        ClientSurfaceIdentity::Application { name, roles } => {
+            let application = runtime.applications.get(&name).ok_or(())?;
+            if roles != application.roles
+                || roles
+                    .binary_search_by(|candidate| candidate.as_str().cmp(role))
+                    .is_err()
+                || requested.schema_hash != application.surface.schema_fingerprint
+            {
+                return Err(());
+            }
+            Ok((
+                ClientSurfaceIdentity::application(name, roles),
+                &application.surface,
+            ))
+        }
+    }
+}
+
+pub(crate) fn resolve_protocol_preset(
+    session: &Session,
+    descriptor: &ClientTrustedPresetDescriptor,
+) -> Option<DistributedTrustedPreset> {
+    use base64::Engine as _;
+
+    // Match SQL row-policy claim lookup exactly: applications commonly
+    // normalize HTTP header names to lowercase before constructing Session.
+    let raw = session
+        .get(&descriptor.name)
+        .or_else(|| session.get(&descriptor.name.to_ascii_lowercase()))?;
+    let value = match descriptor.codec.as_str() {
+        "string" | "string_unvalidated_timestamp" => serde_json::Value::String(raw.to_string()),
+        "base64" => {
+            let decoded = base64::engine::general_purpose::STANDARD.decode(raw).ok()?;
+            if base64::engine::general_purpose::STANDARD.encode(decoded) != raw {
+                return None;
+            }
+            serde_json::Value::String(raw.to_string())
+        }
+        "boolean" => match raw {
+            "true" => serde_json::Value::Bool(true),
+            "false" => serde_json::Value::Bool(false),
+            _ => return None,
+        },
+        "int32" => {
+            let parsed = raw.parse::<i32>().ok()?;
+            if parsed.to_string() != raw {
+                return None;
+            }
+            serde_json::Value::Number(parsed.into())
+        }
+        "json_number_precision_limited" => {
+            let parsed = raw.parse::<i64>().ok()?;
+            if !(-9_007_199_254_740_991..=9_007_199_254_740_991).contains(&parsed)
+                || parsed.to_string() != raw
+            {
+                return None;
+            }
+            serde_json::Value::Number(parsed.into())
+        }
+        "float64" => {
+            let parsed = raw.parse::<f64>().ok()?;
+            if !parsed.is_finite() {
+                return None;
+            }
+            serde_json::Value::Number(serde_json::Number::from_f64(parsed)?)
+        }
+        "json" => serde_json::from_str(raw).ok()?,
+        _ => return None,
+    };
+    Some(DistributedTrustedPreset {
+        name: descriptor.name.clone(),
+        codec: descriptor.codec.clone(),
+        value,
+    })
+}
+
+pub(crate) fn protocol_trusted_presets(
+    manifest: &DistributedClientManifest,
+) -> Result<Vec<ClientTrustedPresetDescriptor>, GraphqlBuildError> {
+    trusted_preset_descriptors(manifest).map_err(|error| GraphqlBuildError(error.to_string()))
+}
+
+pub(crate) fn operation_fingerprint(document: &str) -> String {
+    format!("sha256:{:x}", Sha256::digest(document.as_bytes()))
+}
+
+/// Until the query executor owns an operation-wide database transaction, two
+/// independent read roots cannot truthfully share one causal snapshot. Fail
+/// closed instead of merging separately observed rows and duplicate index
+/// vectors into an envelope that generated clients would treat as atomic.
+pub(crate) fn has_multiple_protocol_query_roots(
+    inner: &EngineInner,
+    role: &str,
+    request: &mut Request,
+) -> bool {
+    if inner.protocol.is_none() {
+        return false;
+    }
+    let Some(surface) = inner.role_surfaces.get(role) else {
+        return false;
+    };
+    let query_roots = surface
+        .query_root_names()
+        .into_iter()
+        .collect::<BTreeSet<_>>();
+    if query_roots.is_empty() {
+        return false;
+    }
+
+    let operation_name = request.operation_name.clone();
+    let Ok(document) = request.parsed_query() else {
+        return false;
+    };
+    let mut operations = document.operations.iter();
+    let operation = if let Some(requested) = operation_name.as_deref() {
+        operations
+            .find(|(name, _)| name.map(|name| name.as_str()) == Some(requested))
+            .map(|(_, operation)| operation)
+    } else {
+        let first = operations.next().map(|(_, operation)| operation);
+        if operations.next().is_some() {
+            None
+        } else {
+            first
+        }
+    };
+    let Some(operation) = operation else {
+        return false;
+    };
+    if operation.node.ty != async_graphql::parser::types::OperationType::Query {
+        return false;
+    }
+
+    fn collect_root_keys<'a>(
+        selection: &'a async_graphql::parser::types::SelectionSet,
+        document: &'a async_graphql::parser::types::ExecutableDocument,
+        query_roots: &BTreeSet<&str>,
+        visiting: &mut BTreeSet<String>,
+        completed: &mut BTreeSet<String>,
+        remaining_selections: &mut usize,
+        response_keys: &mut BTreeSet<String>,
+        depth: usize,
+    ) -> Result<(), ()> {
+        if response_keys.len() > 1 {
+            return Ok(());
+        }
+        if depth > REQUEST_ANALYSIS_MAX_DEPTH || selection.items.len() > *remaining_selections {
+            return Err(());
+        }
+        *remaining_selections -= selection.items.len();
+        for item in &selection.items {
+            match &item.node {
+                async_graphql::parser::types::Selection::Field(field) => {
+                    if query_roots.contains(field.node.name.node.as_str()) {
+                        response_keys.insert(field.node.response_key().node.to_string());
+                    }
+                }
+                async_graphql::parser::types::Selection::InlineFragment(fragment) => {
+                    collect_root_keys(
+                        &fragment.node.selection_set.node,
+                        document,
+                        query_roots,
+                        visiting,
+                        completed,
+                        remaining_selections,
+                        response_keys,
+                        depth + 1,
+                    )?;
+                }
+                async_graphql::parser::types::Selection::FragmentSpread(spread) => {
+                    let name = spread.node.fragment_name.node.to_string();
+                    if completed.contains(&name) {
+                        continue;
+                    }
+                    if !visiting.insert(name.clone()) {
+                        return Err(());
+                    }
+                    let Some(fragment) = document.fragments.get(&spread.node.fragment_name.node)
+                    else {
+                        return Err(());
+                    };
+                    let result = collect_root_keys(
+                        &fragment.node.selection_set.node,
+                        document,
+                        query_roots,
+                        visiting,
+                        completed,
+                        remaining_selections,
+                        response_keys,
+                        depth + 1,
+                    );
+                    visiting.remove(&name);
+                    result?;
+                    completed.insert(name);
+                }
+            }
+            if response_keys.len() > 1 {
+                return Ok(());
+            }
+        }
+        Ok(())
+    }
+
+    let mut response_keys = BTreeSet::new();
+    let mut remaining_selections = REQUEST_ANALYSIS_MAX_SELECTIONS;
+    let analysis = collect_root_keys(
+        &operation.node.selection_set.node,
+        &document,
+        &query_roots,
+        &mut BTreeSet::new(),
+        &mut BTreeSet::new(),
+        &mut remaining_selections,
+        &mut response_keys,
+        0,
+    );
+    analysis.is_err() || response_keys.len() > 1
+}
+
+pub(crate) fn protocol_multi_root_error_response() -> Response {
+    Response::from_errors(vec![ServerError::new(
+        "causal GraphQL operations currently support one read root so data and revision evidence share one atomic snapshot; split this operation into separate requests",
+        None,
+    )])
+}
diff --git a/src/graphql/engine/public_api.rs b/src/graphql/engine/public_api.rs
new file mode 100644
index 00000000..e78164c8
--- /dev/null
+++ b/src/graphql/engine/public_api.rs
@@ -0,0 +1,198 @@
+use super::*;
+
+impl GraphqlEngine {
+    pub fn builder(pool: impl Into<GraphqlPoolSource>) -> GraphqlEngineBuilder {
+        GraphqlEngineBuilder::new(pool.into())
+    }
+
+    pub fn from_manifest(
+        m: &DistributedProjectManifest,
+        pool: impl Into<GraphqlPoolSource>,
+    ) -> Result<GraphqlEngineBuilder, GraphqlBuildError> {
+        let mut builder = Self::builder(pool).service_id(m.name.clone());
+        for schema in &m.tables {
+            if schema.kind == TableKind::ReadModel {
+                builder = builder.register_schema_exposed(schema.clone())?;
+            } else {
+                // Operational tables never become roots, but the shared
+                // Surface needs them to derive opaque m2m dependencies.
+                builder = builder.table_schema(schema.clone());
+            }
+        }
+        Ok(builder)
+    }
+
+    pub fn sdl_for_role(&self, role: &str) -> Option<String> {
+        if !self.inner.roles.contains(role) && role != self.inner.anonymous_role {
+            // Still allow any role that has a built schema.
+        }
+        self.inner.schemas.get(role).map(|s| s.sdl())
+    }
+
+    /// Dep-free **surface IR** role SDL (A11 production path).
+    ///
+    /// Preferred for deterministic SDL generation and schema-drift checks. Uses
+    /// the same catalog grants as the engine build (A12 mapper). Runtime dump is
+    /// still available via [`Self::sdl_for_role`].
+    pub fn ir_sdl_for_role(&self, role: &str) -> Result<String, String> {
+        let surface = self
+            .inner
+            .role_surfaces
+            .get(role)
+            .ok_or_else(|| format!("role `{role}` is not configured for GraphQL"))?;
+        graphql_sdl_from_surface(surface)
+    }
+
+    /// Return the exact role Surface instance used to construct the runtime
+    /// schema. This is intentionally shared rather than reconstructed.
+    pub fn surface_for_role(&self, role: &str) -> Option<Arc<Surface>> {
+        self.inner.role_surfaces.get(role).cloned()
+    }
+
+    /// Stable service identity retained from [`DistributedProjectManifest::name`].
+    ///
+    /// Engines built manually return `None` unless the builder opted in with
+    /// [`GraphqlEngineBuilder::service_id`].
+    pub fn service_id(&self) -> Option<&str> {
+        self.inner.service_id.as_deref()
+    }
+
+    pub(crate) fn typed_command_binding(&self) -> Option<&TypedServiceCommandBinding> {
+        self.inner.command_binding.as_ref()
+    }
+
+    pub(crate) fn typed_command_contracts_for_service(
+        &self,
+    ) -> Result<Vec<crate::graphql::command_contract::TypedCommandContract>, String> {
+        Ok(self.inner.typed_commands.contracts_for_binding())
+    }
+
+    pub(crate) fn causal_storage_identity(
+        &self,
+    ) -> Option<crate::command_ledger::CausalStorageIdentity> {
+        self.inner.causal_storage_identity
+    }
+
+    pub(crate) fn causal_protocol_configured(&self) -> bool {
+        self.inner.protocol.is_some()
+    }
+
+    pub fn client_surface_for_role(
+        &self,
+        role: &str,
+    ) -> Result<DistributedClientSurfaceExport, ClientManifestError> {
+        let service_id = self.client_export_service_id()?;
+        let surface = self.surface_for_role(role).ok_or_else(|| {
+            ClientManifestError(format!("role `{role}` is not configured for GraphQL"))
+        })?;
+        DistributedClientSurfaceExport::from_selected_with_execution(
+            service_id,
+            surface,
+            ClientExecutionLimits::from_runtime(
+                self.inner.max_depth,
+                self.inner.max_complexity,
+                self.inner.max_bool_width,
+                self.inner.max_in_list,
+            )?,
+        )
+    }
+
+    pub fn client_manifest_for_role(
+        &self,
+        role: &str,
+    ) -> Result<DistributedClientManifest, ClientManifestError> {
+        self.client_surface_for_role(role)?.manifest()
+    }
+
+    pub fn client_surface_for_application(
+        &self,
+        application: &str,
+        roles: &[&str],
+    ) -> Result<DistributedClientSurfaceExport, ClientManifestError> {
+        let service_id = self.client_export_service_id()?;
+        let surface = self
+            .inner
+            .application_surfaces
+            .get(application)
+            .cloned()
+            .ok_or_else(|| {
+                ClientManifestError(format!(
+                    "application surface `{application}` is not registered"
+                ))
+            })?;
+        let mut requested_roles = roles
+            .iter()
+            .map(|role| (*role).to_string())
+            .collect::<Vec<_>>();
+        requested_roles.sort();
+        requested_roles.dedup();
+        let SurfaceSelection::Application {
+            roles: registered_roles,
+            ..
+        } = &surface.selection
+        else {
+            return Err(ClientManifestError(format!(
+                "registered application surface `{application}` has invalid identity"
+            )));
+        };
+        if requested_roles != *registered_roles {
+            return Err(ClientManifestError(format!(
+                "application surface `{application}` is registered for roles [{}], not [{}]",
+                registered_roles.join(", "),
+                requested_roles.join(", ")
+            )));
+        }
+        DistributedClientSurfaceExport::from_selected_with_execution(
+            service_id,
+            surface,
+            ClientExecutionLimits::from_runtime(
+                self.inner.max_depth,
+                self.inner.max_complexity,
+                self.inner.max_bool_width,
+                self.inner.max_in_list,
+            )?,
+        )
+    }
+
+    pub fn client_manifest_for_application(
+        &self,
+        application: &str,
+        roles: &[&str],
+    ) -> Result<DistributedClientManifest, ClientManifestError> {
+        self.client_surface_for_application(application, roles)?
+            .manifest()
+    }
+
+    fn client_export_service_id(&self) -> Result<String, ClientManifestError> {
+        self.inner.service_id.clone().ok_or_else(|| {
+            ClientManifestError(
+                "client export requires a service ID; construct the engine with GraphqlEngine::from_manifest or GraphqlEngineBuilder::service_id"
+                    .into(),
+            )
+        })
+    }
+
+    pub fn graphiql_enabled(&self) -> bool {
+        self.inner.graphiql
+    }
+
+    /// Identity configuration used by GraphQL HTTP handlers.
+    pub fn identity_config(&self) -> &IdentityConfig {
+        &self.inner.identity
+    }
+
+    pub(crate) fn identity_validator(&self) -> Option<&OidcValidator> {
+        self.inner.identity_validator.as_ref()
+    }
+
+    /// Whether unknown/ungranted client `where` and `order_by` keys fail closed.
+    /// Default is `true` (see [`GraphqlEngineBuilder::strict_where`]).
+    pub fn strict_where(&self) -> bool {
+        self.inner.strict_where
+    }
+
+    /// Hub used by live subscriptions (tests may publish directly).
+    pub fn change_hub(&self) -> &crate::graphql::subscribe::ChangeHub {
+        &self.inner.change_hub
+    }
+}
diff --git a/src/graphql/engine/request.rs b/src/graphql/engine/request.rs
new file mode 100644
index 00000000..906f05e5
--- /dev/null
+++ b/src/graphql/engine/request.rs
@@ -0,0 +1,190 @@
+use super::*;
+
+impl GraphqlEngine {
+    pub async fn execute(&self, session: &Session, mut request: Request) -> Response {
+        let role = resolve_role(session, &self.inner.anonymous_role);
+        let introspection = self.inner.graphiql && is_pure_introspection_request(&mut request);
+        let schema = if introspection {
+            self.inner
+                .graphiql_schemas
+                .get(&role)
+                .or_else(|| self.inner.schemas.get(&role))
+        } else {
+            self.inner.schemas.get(&role)
+        };
+        let Some(schema) = schema else {
+            return Response::from_errors(vec![ServerError::new(
+                format!("role `{role}` is not configured for GraphQL"),
+                None,
+            )]);
+        };
+        if has_multiple_protocol_query_roots(&self.inner, &role, &mut request) {
+            return protocol_multi_root_error_response();
+        }
+
+        let accumulator = match self.protocol_accumulator(&role, session, &request) {
+            Ok(accumulator) => accumulator,
+            Err(()) => return protocol_internal_error_response(),
+        };
+        if introspection {
+            // The relaxed schema is defense-in-depth restricted even if a
+            // future classifier or request extension behaves unexpectedly.
+            request = request.only_introspection();
+        }
+        let mut request = request.data(session.clone()).data(Arc::clone(&self.inner));
+        if let Some(accumulator) = &accumulator {
+            request = request.data(accumulator.clone());
+        }
+        let start = std::time::Instant::now();
+        let response =
+            attach_protocol_response(schema.execute(request).await, accumulator.as_ref());
+        let status = metrics_status_for_response(&response);
+        let root_field = match &response.data {
+            Value::Object(map) => map.keys().next().map(|s| s.as_str()).unwrap_or("_"),
+            _ => "_",
+        };
+        record_metrics(session, root_field, status, start.elapsed());
+        response
+    }
+
+    /// Execute a GraphQL subscription document as a stream of responses.
+    pub fn execute_stream(
+        &self,
+        session: &Session,
+        mut request: Request,
+    ) -> BoxStream<'static, async_graphql::Response> {
+        let role = resolve_role(session, &self.inner.anonymous_role);
+        let introspection = self.inner.graphiql && is_pure_introspection_request(&mut request);
+        let schema = if introspection {
+            self.inner
+                .graphiql_schemas
+                .get(&role)
+                .or_else(|| self.inner.schemas.get(&role))
+        } else {
+            self.inner.schemas.get(&role)
+        };
+        let Some(schema) = schema.cloned() else {
+            return stream::once(async move {
+                Response::from_errors(vec![ServerError::new(
+                    format!("role `{role}` is not configured for GraphQL"),
+                    None,
+                )])
+            })
+            .boxed();
+        };
+        if has_multiple_protocol_query_roots(&self.inner, &role, &mut request) {
+            return stream::once(async { protocol_multi_root_error_response() }).boxed();
+        }
+        let accumulator = match self.protocol_accumulator(&role, session, &request) {
+            Ok(accumulator) => accumulator,
+            Err(()) => {
+                return stream::once(async { protocol_internal_error_response() }).boxed();
+            }
+        };
+        if accumulator
+            .as_ref()
+            .is_some_and(|accumulator| accumulator.begin_stream().is_err())
+        {
+            return stream::once(async { protocol_internal_error_response() }).boxed();
+        }
+        if introspection {
+            request = request.only_introspection();
+        }
+        let mut request = request
+            .data(session.clone())
+            .data(std::sync::Arc::clone(&self.inner));
+        if let Some(accumulator) = &accumulator {
+            request = request.data(accumulator.clone());
+        }
+        schema
+            .execute_stream(request)
+            .map(move |response| attach_protocol_response(response, accumulator.as_ref()))
+            .boxed()
+    }
+
+    fn protocol_accumulator(
+        &self,
+        role: &str,
+        session: &Session,
+        request: &Request,
+    ) -> Result<Option<ProtocolResponseAccumulator>, ()> {
+        let Some(runtime) = &self.inner.protocol else {
+            return Ok(None);
+        };
+        let role_info = runtime.roles.get(role).ok_or(())?;
+        let (surface_identity, surface_info) =
+            select_protocol_surface(runtime, role, request).map_err(|_| ())?;
+        let trusted_presets = surface_info
+            .trusted_presets
+            .iter()
+            .map(|descriptor| resolve_protocol_preset(session, descriptor).ok_or(()))
+            .collect::<Result<Vec<_>, _>>()?;
+        let principal = request
+            .data
+            .get(&TypeId::of::<VerifiedPrincipal>())
+            .and_then(|principal| principal.downcast_ref::<VerifiedPrincipal>());
+        let principal_partition =
+            principal.map(|principal| principal.partition_for_service(&runtime.service_id));
+        let session_authorization_context = role_info
+            .claim_keys
+            .iter()
+            .map(|key| (key.as_str(), session.get(key)))
+            .collect::<Vec<_>>();
+
+        #[derive(Serialize)]
+        struct CacheScopeMaterial<'a> {
+            domain: &'static str,
+            version: u32,
+            namespace: &'a str,
+            service_id: &'a str,
+            role: &'a str,
+            surface: &'a ClientSurfaceIdentity,
+            schema_fingerprint: &'a str,
+            protocol_fingerprint: &'a str,
+            authorization_surface_fingerprint: &'a str,
+            identity_mode: &'static str,
+            verified_principal_partition: Option<&'a str>,
+            session_authorization_context: Vec<(&'a str, Option<&'a str>)>,
+            trusted_presets: &'a [DistributedTrustedPreset],
+        }
+
+        // Only session values that can affect authorization enter the HMAC:
+        // role/user plus claim keys referenced by this role's row policies.
+        // Ambient headers such as cookies or user-agent must not churn caches.
+        // Raw values and the verified principal partition remain private HMAC
+        // inputs and are never echoed in the response.
+        let material = CacheScopeMaterial {
+            domain: "distributed.graphql.cache-scope",
+            version: 1,
+            namespace: &runtime.namespace,
+            service_id: &runtime.service_id,
+            role,
+            surface: &surface_identity,
+            schema_fingerprint: &surface_info.schema_fingerprint,
+            protocol_fingerprint: &surface_info.protocol_fingerprint,
+            authorization_surface_fingerprint: &role_info.authorization_fingerprint,
+            identity_mode: identity_mode_label(self.inner.identity.mode),
+            verified_principal_partition: principal_partition.as_deref(),
+            session_authorization_context,
+            trusted_presets: &trusted_presets,
+        };
+        let cache_scope = runtime
+            .codec
+            .issue(ProtocolTokenPurpose::CacheScope, &material)
+            .map_err(|_| ())?;
+        let envelope = DistributedEnvelopeV1::new(
+            surface_info.schema_fingerprint.clone(),
+            cache_scope,
+            // Generated artifacts submit this exact document. Hashing its
+            // bytes matches manifest operation_hash and provides a useful
+            // identity/drift fence without claiming APQ negotiation.
+            Some(operation_fingerprint(&request.query)),
+        )
+        .with_trusted_presets(trusted_presets);
+        let accumulator = ProtocolResponseAccumulator::new(envelope, runtime.codec.clone());
+        accumulator
+            .set_requested_live_resume(parse_requested_live_resume(request))
+            .map_err(|_| ())?;
+        Ok(Some(accumulator))
+    }
+}
diff --git a/src/graphql/engine/tests.rs b/src/graphql/engine/tests.rs
new file mode 100644
index 00000000..016916b3
--- /dev/null
+++ b/src/graphql/engine/tests.rs
@@ -0,0 +1,2181 @@
+use super::*;
+
+#[cfg(all(test, any(feature = "sqlite", feature = "postgres")))]
+mod client_surface_parity_tests {
+    use std::any::TypeId;
+    use std::collections::{BTreeMap, BTreeSet};
+    use std::sync::Arc;
+
+    use sha2::{Digest, Sha256};
+
+    use super::*;
+    use crate::graphql::command_contract::{CommandEffects, TypedCommandContract};
+    use crate::graphql::commands::TypedCommandInventory;
+    #[cfg(feature = "sqlite")]
+    use crate::graphql::ModelNormalization;
+    use crate::graphql::{
+        claim, col, ClientRootOperation, CommandConsistency, DistributedClientSurfaceExport,
+        GraphqlInputType, GraphqlOutputType, GraphqlTypeDef, GraphqlTypeField, RoleGrant,
+    };
+    #[cfg(feature = "sqlite")]
+    use crate::table::RelationshipDef;
+    use crate::table::{ColumnType, PrimaryKey, TableColumn, TableKind, TableSchema};
+
+    fn orders() -> TableSchema {
+        TableSchema {
+            model_name: "OrderView".into(),
+            table_name: "orders".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new("order_id", "order_id", ColumnType::Text)
+                },
+                TableColumn::new("status", "status", ColumnType::Text),
+                TableColumn {
+                    jsonb: true,
+                    ..TableColumn::new("metadata", "metadata", ColumnType::Json)
+                },
+            ],
+            primary_key: PrimaryKey::new(["order_id"]),
+            version_column: Some("_sourced_version".into()),
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        }
+    }
+
+    fn duplicated_introspection_fragment_dag(depth: usize) -> String {
+        let mut document = String::from("query Introspection { ...F0 }\n");
+        for index in 0..depth {
+            document.push_str(&format!(
+                "fragment F{index} on Query {{ ...F{} ...F{} }}\n",
+                index + 1,
+                index + 1
+            ));
+        }
+        document.push_str(&format!("fragment F{depth} on Query {{ __typename }}\n"));
+        document
+    }
+
+    fn test_command<I, O>(
+        command_name: &str,
+        field_name: &str,
+        roles: &[&str],
+    ) -> TypedCommandContract
+    where
+        I: GraphqlInputType + 'static,
+        O: GraphqlOutputType + 'static,
+    {
+        TypedCommandContract {
+            name: command_name.into(),
+            field_name: field_name.into(),
+            roles: roles.iter().map(|role| (*role).into()).collect(),
+            input: I::graphql_type().with_type_id(TypeId::of::<I>()),
+            output: O::graphql_type().with_type_id(TypeId::of::<O>()),
+            input_type_id: TypeId::of::<I>(),
+            output_type_id: TypeId::of::<O>(),
+            consistency: CommandConsistency::Accepted,
+            input_defaults: Vec::new(),
+            effects: CommandEffects::revalidate(),
+            confirmations: Vec::new(),
+            projected_model: None,
+            direct_projection: None,
+        }
+    }
+
+    fn test_service_binding(
+        service_id: &str,
+        commands: &TypedCommandInventory,
+    ) -> TypedServiceCommandBinding {
+        TypedServiceCommandBinding::from_contracts(service_id, &commands.contracts_for_binding())
+            .unwrap()
+    }
+
+    fn type_field_names(sdl: &str, type_name: &str) -> BTreeSet<String> {
+        definition_field_names(sdl, "type", type_name)
+    }
+
+    fn input_field_names(sdl: &str, type_name: &str) -> BTreeSet<String> {
+        definition_field_names(sdl, "input", type_name)
+    }
+
+    fn definition_field_names(sdl: &str, declaration: &str, type_name: &str) -> BTreeSet<String> {
+        let marker = format!("{declaration} {type_name} {{");
+        let body = sdl
+            .split_once(&marker)
+            .unwrap_or_else(|| panic!("missing `{marker}` in SDL:\n{sdl}"))
+            .1
+            .split_once('}')
+            .expect("type block should close")
+            .0;
+        body.lines()
+            .filter_map(|line| {
+                let line = line.trim();
+                if line.is_empty() || line.starts_with('#') {
+                    return None;
+                }
+                line.split(['(', ':'])
+                    .next()
+                    .map(str::trim)
+                    .filter(|name| !name.is_empty())
+                    .map(str::to_string)
+            })
+            .collect()
+    }
+
+    #[cfg(feature = "sqlite")]
+    fn protocol_engine(namespace: &str) -> GraphqlEngine {
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .connect_lazy("sqlite::memory:")
+            .unwrap();
+        let project = DistributedProjectManifest::new("orders-service").table_schema(orders());
+        GraphqlEngine::from_manifest(&project, pool)
+            .unwrap()
+            .roles(&["user"])
+            .grant_all("user")
+            .protocol_token_key([7; 32])
+            .protocol_namespace(namespace)
+            .build()
+            .unwrap()
+    }
+
+    #[cfg(feature = "sqlite")]
+    fn policy_protocol_engine(namespace: &str, claim_key: &str) -> GraphqlEngine {
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .connect_lazy("sqlite::memory:")
+            .unwrap();
+        let project = DistributedProjectManifest::new("orders-service").table_schema(orders());
+        let mut builder = GraphqlEngine::from_manifest(&project, pool)
+            .unwrap()
+            .roles(&["user"])
+            .grant_all("user");
+        builder
+            .permissions
+            .get_mut(&("OrderView".into(), "user".into()))
+            .unwrap()
+            .permission
+            .row_filter = Some(col("status").eq(claim(claim_key)));
+        builder
+            .protocol_token_key([7; 32])
+            .protocol_namespace(namespace)
+            .build()
+            .unwrap()
+    }
+
+    #[cfg(feature = "sqlite")]
+    fn preset_protocol_engine() -> GraphqlEngine {
+        let mut engine = protocol_engine("preset-test");
+        Arc::get_mut(&mut engine.inner)
+            .expect("test owns the only engine Arc")
+            .protocol
+            .as_mut()
+            .expect("protocol")
+            .roles
+            .get_mut("user")
+            .expect("user protocol surface")
+            .surface
+            .trusted_presets = vec![
+            ClientTrustedPresetDescriptor {
+                name: "x-default-status".into(),
+                codec: "string".into(),
+            },
+            ClientTrustedPresetDescriptor {
+                name: "x-order-id".into(),
+                codec: "string".into(),
+            },
+        ];
+        engine
+    }
+
+    #[cfg(feature = "sqlite")]
+    fn distributed_extension(response: &Response) -> serde_json::Value {
+        serde_json::to_value(
+            response
+                .extensions
+                .get("distributed")
+                .expect("configured protocol response must carry one envelope"),
+        )
+        .unwrap()
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn client_manifest_exports_the_exact_runtime_execution_limits() {
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .connect_lazy("sqlite::memory:")
+            .unwrap();
+        let project = DistributedProjectManifest::new("orders-service").table_schema(orders());
+        let engine = GraphqlEngine::from_manifest(&project, pool)
+            .unwrap()
+            .roles(&["user"])
+            .grant_all("user")
+            .max_depth(6)
+            .max_complexity(37)
+            .build()
+            .unwrap();
+
+        let manifest = engine.client_manifest_for_role("user").unwrap();
+        assert_eq!(manifest.execution.max_depth, 6);
+        assert_eq!(manifest.execution.max_complexity, 37);
+        assert_eq!(manifest.execution.complexity.version, 1);
+        assert_eq!(manifest.execution.complexity.scalar, 1);
+        assert_eq!(manifest.execution.complexity.list_fanout, 5);
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn graphiql_isolated_introspection_does_not_change_the_client_contract() {
+        let build = |graphiql| {
+            let pool = sqlx::sqlite::SqlitePoolOptions::new()
+                .connect_lazy("sqlite::memory:")
+                .unwrap();
+            let project = DistributedProjectManifest::new("orders-service").table_schema(orders());
+            GraphqlEngine::from_manifest(&project, pool)
+                .unwrap()
+                .roles(&["user"])
+                .grant_all("user")
+                .client_application_surface("console", ["user"])
+                .protocol_token_key([7; 32])
+                .graphiql(graphiql)
+                .build()
+                .unwrap()
+        };
+        let without_graphiql = build(false);
+        let with_graphiql = build(true);
+        let generated = without_graphiql
+            .client_manifest_for_application("console", &["user"])
+            .unwrap();
+        let runtime = with_graphiql
+            .client_manifest_for_application("console", &["user"])
+            .unwrap();
+
+        assert_eq!(generated, runtime);
+        assert_eq!(runtime.execution.max_depth, 8);
+        assert_eq!(runtime.execution.max_complexity, 500);
+        assert_eq!(
+            with_graphiql.inner.schemas.get("user").unwrap().sdl(),
+            with_graphiql
+                .inner
+                .graphiql_schemas
+                .get("user")
+                .unwrap()
+                .sdl()
+        );
+
+        let mut session = Session::new();
+        session.set("x-role", "user");
+        let deep_introspection = r#"
+            query GraphiqlIntrospection {
+              __type(name: "OrderView") {
+                fields {
+                  type {
+                    ofType {
+                      ofType {
+                        ofType {
+                          ofType {
+                            ofType {
+                              ofType {
+                                ofType {
+                                  name
+                                }
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+        "#;
+        let strict = without_graphiql
+            .execute(&session, Request::new(deep_introspection))
+            .await;
+        assert!(
+            strict.is_err(),
+            "the normal schema must retain the manifest-fingerprinted depth limit"
+        );
+        let relaxed = with_graphiql
+            .execute(&session, Request::new(deep_introspection))
+            .await;
+        assert!(
+            !relaxed.is_err(),
+            "pure GraphiQL introspection should use its isolated allowance: {:?}",
+            relaxed.errors
+        );
+
+        let mut dag_request = Request::new(duplicated_introspection_fragment_dag(32));
+        assert!(
+            !has_multiple_protocol_query_roots(&with_graphiql.inner, "user", &mut dag_request),
+            "protocol root analysis must memoize shared fragment DAGs"
+        );
+        let executable_dag = duplicated_introspection_fragment_dag(12);
+        let dag_response = with_graphiql
+            .execute(&session, Request::new(&executable_dag))
+            .await;
+        assert!(
+            !dag_response.is_err(),
+            "memoized introspection DAG should execute: {:?}",
+            dag_response.errors
+        );
+        let dag_stream = with_graphiql
+            .execute_stream(&session, Request::new(executable_dag))
+            .collect::<Vec<_>>()
+            .await;
+        assert_eq!(dag_stream.len(), 1);
+        assert!(
+            !dag_stream[0].is_err(),
+            "memoized introspection DAG should execute through the streaming path"
+        );
+
+        let disabled = with_graphiql
+            .execute(
+                &session,
+                Request::new("{ __schema { queryType { name } } }").disable_introspection(),
+            )
+            .await;
+        assert_eq!(
+            disabled.data,
+            Value::Null,
+            "GraphiQL must not override request-level introspection denial"
+        );
+        let streamed = with_graphiql
+            .execute_stream(
+                &session,
+                Request::new("{ __schema { queryType { name } } }").disable_introspection(),
+            )
+            .collect::<Vec<_>>()
+            .await;
+        assert_eq!(streamed.len(), 1);
+        assert_eq!(
+            streamed[0].data,
+            Value::Null,
+            "the streaming path must preserve request-level introspection denial"
+        );
+    }
+
+    #[test]
+    fn graphiql_relaxation_is_selected_only_for_pure_introspection() {
+        let classify = |mut request| is_pure_introspection_request(&mut request);
+        assert!(classify(Request::new(
+            "query Introspection { __schema { queryType { name } } }"
+        )));
+        assert!(classify(
+            Request::new(
+                "query App { orders { order_id } } query Introspection { __type(name: \"OrderView\") { name } }"
+            )
+            .operation_name("Introspection")
+        ));
+        assert!(classify(Request::new(
+            "query ThroughFragment { ...Introspection } fragment Introspection on Query { __schema { queryType { name } } }"
+        )));
+        assert!(!classify(Request::new(
+            "query Mixed { __typename orders { order_id } }"
+        )));
+        assert!(!classify(Request::new(
+            "query App { orders { order_id } } query Introspection { __schema { queryType { name } } }"
+        )));
+        assert!(!classify(Request::new(
+            "mutation NotIntrospection { __typename }"
+        )));
+        assert!(!classify(Request::new(
+            "query ThroughFragment { ...Missing }"
+        )));
+        assert!(!classify(
+            Request::new("{ __schema { queryType { name } } }").disable_introspection()
+        ));
+
+        let mut cached_application =
+            Request::new("query Introspection { __schema { queryType { name } } }");
+        cached_application.set_parsed_query(
+            async_graphql::parser::parse_query("query App { orders { order_id } }").unwrap(),
+        );
+        assert!(
+            !is_pure_introspection_request(&mut cached_application),
+            "classification must inspect the same cached AST async-graphql executes"
+        );
+
+        assert!(
+            classify(Request::new(duplicated_introspection_fragment_dag(32))),
+            "shared fragment DAGs must be memoized rather than expanded exponentially"
+        );
+
+        let over_budget = (0..=REQUEST_ANALYSIS_MAX_SELECTIONS)
+            .map(|index| format!("f{index}: __typename"))
+            .collect::<Vec<_>>()
+            .join(" ");
+        assert!(
+            !classify(Request::new(format!("query TooWide {{ {over_budget} }}"))),
+            "untrusted classifier work must remain explicitly bounded"
+        );
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn configured_protocol_attaches_stable_role_and_identity_bound_envelopes() {
+        use crate::graphql::identity::VerifiedPrincipal;
+
+        let engine = protocol_engine("public/graphql");
+        let manifest = engine.client_manifest_for_role("user").unwrap();
+        let role_info = &engine
+            .inner
+            .protocol
+            .as_ref()
+            .unwrap()
+            .roles
+            .get("user")
+            .unwrap();
+        assert_eq!(
+            role_info.surface.schema_fingerprint,
+            manifest.schema_fingerprint
+        );
+        assert_eq!(
+            role_info.surface.protocol_fingerprint,
+            manifest.protocol_fingerprint
+        );
+
+        let mut session = Session::new();
+        session.set("x-role", "user");
+        session.set("x-tenant", "tenant-a");
+        let principal = VerifiedPrincipal::test_oidc(
+            "https://issuer.example",
+            "principal-a",
+            &["orders-service"],
+        );
+        let first = engine
+            .execute(
+                &session,
+                Request::new("{ __typename }").data(principal.clone()),
+            )
+            .await;
+        let second = engine
+            .execute(
+                &session,
+                Request::new("{ __typename }").data(principal.clone()),
+            )
+            .await;
+        let first = distributed_extension(&first);
+        let second = distributed_extension(&second);
+        assert_eq!(first, second);
+        assert_eq!(first["protocolVersion"], 1);
+        assert_eq!(first["schemaHash"], manifest.schema_fingerprint);
+        assert_eq!(
+            first["operation"],
+            "sha256:7f56e67dd21ab3f30d1ff8b7bed08893f0a0db86449836189b361dd1e56ddb4b"
+        );
+        let scope = first["cacheScope"].as_str().unwrap();
+        assert!(scope.starts_with("v1.cache-scope."));
+        assert!(!scope.contains("principal-a"));
+        assert!(!scope.contains("tenant-a"));
+
+        let generated_role_request = |name: &str, schema_hash: &str| -> Request {
+            serde_json::from_value(serde_json::json!({
+                "query": "{ __typename }",
+                "extensions": {
+                    "distributed": {
+                        "client": {
+                            "surface": {"kind": "role", "name": name},
+                            "schemaHash": schema_hash
+                        }
+                    }
+                }
+            }))
+            .expect("generated role request")
+        };
+        let generated_response = engine
+            .execute(
+                &session,
+                generated_role_request("user", &manifest.schema_fingerprint)
+                    .data(principal.clone()),
+            )
+            .await;
+        assert_eq!(first, distributed_extension(&generated_response));
+        for invalid in [
+            generated_role_request("admin", &manifest.schema_fingerprint),
+            generated_role_request("user", "sha256:stale-generation"),
+        ] {
+            let response = engine.execute(&session, invalid).await;
+            assert!(response.is_err());
+            assert!(!response.extensions.contains_key("distributed"));
+        }
+
+        let mut other_session = session.clone();
+        other_session.set("user-agent", "a totally different browser");
+        let other_session_response = engine
+            .execute(
+                &other_session,
+                Request::new("{ __typename }").data(principal.clone()),
+            )
+            .await;
+        assert_eq!(
+            first["cacheScope"],
+            distributed_extension(&other_session_response)["cacheScope"]
+        );
+
+        let mut other_user = session.clone();
+        other_user.set("x-user-id", "user-b");
+        let other_user_response = engine
+            .execute(
+                &other_user,
+                Request::new("{ __typename }").data(principal.clone()),
+            )
+            .await;
+        assert_ne!(
+            first["cacheScope"],
+            distributed_extension(&other_user_response)["cacheScope"]
+        );
+
+        let other_principal = VerifiedPrincipal::test_oidc(
+            "https://issuer.example",
+            "principal-b",
+            &["orders-service"],
+        );
+        let other_principal_response = engine
+            .execute(
+                &session,
+                Request::new("{ __typename }").data(other_principal),
+            )
+            .await;
+        assert_ne!(
+            first["cacheScope"],
+            distributed_extension(&other_principal_response)["cacheScope"]
+        );
+
+        let other_namespace = protocol_engine("internal/graphql");
+        let namespaced_response = other_namespace
+            .execute(&session, Request::new("{ __typename }").data(principal))
+            .await;
+        assert_ne!(
+            first["cacheScope"],
+            distributed_extension(&namespaced_response)["cacheScope"]
+        );
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn named_application_protocol_selection_is_registered_exact_and_role_bound() {
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .connect_lazy("sqlite::memory:")
+            .unwrap();
+        let project = DistributedProjectManifest::new("orders-service").table_schema(orders());
+        let engine = GraphqlEngine::from_manifest(&project, pool)
+            .unwrap()
+            .roles(&["admin", "user"])
+            .grant_all("admin")
+            .grant_all("user")
+            .client_application_surface("console", ["admin", "user"])
+            .protocol_token_key([7; 32])
+            .build()
+            .unwrap();
+        let manifest = engine
+            .client_manifest_for_application("console", &["user", "admin"])
+            .expect("registered application manifest");
+        assert!(engine
+            .client_manifest_for_application("console", &["user"])
+            .is_err());
+
+        let request = |schema_hash: &str, roles: serde_json::Value| -> Request {
+            serde_json::from_value(serde_json::json!({
+                "query": "{ __typename }",
+                "extensions": {
+                    "distributed": {
+                        "client": {
+                            "surface": {
+                                "kind": "application",
+                                "name": "console",
+                                "roles": roles
+                            },
+                            "schemaHash": schema_hash
+                        }
+                    }
+                }
+            }))
+            .expect("generated application request")
+        };
+
+        let mut user = Session::new();
+        user.set("x-role", "user");
+        user.set("x-user-id", "person-1");
+        let user_response = engine
+            .execute(
+                &user,
+                request(
+                    &manifest.schema_fingerprint,
+                    serde_json::json!(["admin", "user"]),
+                ),
+            )
+            .await;
+        let user_envelope = distributed_extension(&user_response);
+        assert_eq!(user_envelope["schemaHash"], manifest.schema_fingerprint);
+
+        let mut admin = user.clone();
+        admin.set("x-role", "admin");
+        let admin_response = engine
+            .execute(
+                &admin,
+                request(
+                    &manifest.schema_fingerprint,
+                    serde_json::json!(["admin", "user"]),
+                ),
+            )
+            .await;
+        let admin_envelope = distributed_extension(&admin_response);
+        assert_eq!(admin_envelope["schemaHash"], manifest.schema_fingerprint);
+        assert_ne!(
+            user_envelope["cacheScope"], admin_envelope["cacheScope"],
+            "one application schema never erases the concrete authorized role"
+        );
+
+        for invalid in [
+            request(
+                &manifest.schema_fingerprint,
+                serde_json::json!(["user", "admin"]),
+            ),
+            request(
+                "sha256:stale-generation",
+                serde_json::json!(["admin", "user"]),
+            ),
+        ] {
+            let response = engine.execute(&user, invalid).await;
+            assert!(response.is_err());
+            assert!(!response.extensions.contains_key("distributed"));
+        }
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn trusted_presets_are_session_derived_typed_and_scope_bound() {
+        let engine = preset_protocol_engine();
+        assert_eq!(
+            engine.inner.protocol.as_ref().unwrap().roles["user"]
+                .surface
+                .trusted_presets,
+            vec![
+                ClientTrustedPresetDescriptor {
+                    name: "x-default-status".into(),
+                    codec: "string".into(),
+                },
+                ClientTrustedPresetDescriptor {
+                    name: "x-order-id".into(),
+                    codec: "string".into(),
+                },
+            ]
+        );
+
+        let mut session = Session::new();
+        session.set("x-role", "user");
+        session.set("x-user-id", "person-1");
+        session.set("x-order-id", "order-1");
+        session.set("x-default-status", "assigned");
+        let first = engine
+            .execute(&session, Request::new("{ __typename }"))
+            .await;
+        let first = distributed_extension(&first);
+        assert_eq!(
+            first["trustedPresets"],
+            serde_json::json!([
+                {"name": "x-default-status", "codec": "string", "value": "assigned"},
+                {"name": "x-order-id", "codec": "string", "value": "order-1"}
+            ])
+        );
+
+        let mut changed = session.clone();
+        changed.set("x-default-status", "queued");
+        let changed = engine
+            .execute(&changed, Request::new("{ __typename }"))
+            .await;
+        let changed = distributed_extension(&changed);
+        assert_ne!(first["cacheScope"], changed["cacheScope"]);
+        assert_eq!(changed["trustedPresets"][0]["value"], "queued");
+
+        let mut missing = Session::new();
+        missing.set("x-role", "user");
+        missing.set("x-user-id", "person-1");
+        missing.set("x-order-id", "order-1");
+        let response = engine
+            .execute(&missing, Request::new("{ __typename }"))
+            .await;
+        assert!(response.is_err());
+        assert!(!response.extensions.contains_key("distributed"));
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn row_policy_presets_follow_sql_claim_case_normalization() {
+        let engine = policy_protocol_engine("mixed-case-policy", "X-Tenant");
+        assert_eq!(
+            engine.inner.protocol.as_ref().unwrap().roles["user"]
+                .surface
+                .trusted_presets,
+            vec![ClientTrustedPresetDescriptor {
+                name: "X-Tenant".into(),
+                codec: "string".into(),
+            }]
+        );
+
+        let mut session = Session::new();
+        session.set("x-role", "user");
+        session.set("x-user-id", "person-1");
+        // `operand_to_bind` accepts the normalized lowercase header for this
+        // mixed-case policy claim. The cache-scope envelope must expose the
+        // same resolved value or client policy evaluation would fail closed.
+        session.set("x-tenant", "tenant-1");
+        let response = engine
+            .execute(&session, Request::new("{ __typename }"))
+            .await;
+        assert_eq!(
+            distributed_extension(&response)["trustedPresets"],
+            serde_json::json!([
+                {"name": "X-Tenant", "codec": "string", "value": "tenant-1"}
+            ])
+        );
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn cache_scope_tracks_only_relevant_claims_and_private_policy() {
+        use crate::graphql::identity::VerifiedPrincipal;
+
+        let engine = policy_protocol_engine("public/graphql", "x-tenant");
+        let principal = VerifiedPrincipal::test_oidc(
+            "https://issuer.example",
+            "principal-a",
+            &["orders-service"],
+        );
+        let mut session = Session::new();
+        session.set("x-role", "user");
+        session.set("x-user-id", "user-a");
+        session.set("x-tenant", "tenant-a");
+        session.set("x-organization", "organization-a");
+        let response = engine
+            .execute(
+                &session,
+                Request::new("{ __typename }").data(principal.clone()),
+            )
+            .await;
+        let envelope = distributed_extension(&response);
+
+        let mut irrelevant = session.clone();
+        irrelevant.set("cookie", "rotated-cookie");
+        irrelevant.set("x-organization", "organization-b");
+        let response = engine
+            .execute(
+                &irrelevant,
+                Request::new("{ __typename }").data(principal.clone()),
+            )
+            .await;
+        assert_eq!(
+            envelope["cacheScope"],
+            distributed_extension(&response)["cacheScope"]
+        );
+
+        let mut other_tenant = session.clone();
+        other_tenant.set("x-tenant", "tenant-b");
+        let response = engine
+            .execute(
+                &other_tenant,
+                Request::new("{ __typename }").data(principal.clone()),
+            )
+            .await;
+        assert_ne!(
+            envelope["cacheScope"],
+            distributed_extension(&response)["cacheScope"]
+        );
+
+        let other_policy = policy_protocol_engine("public/graphql", "x-organization");
+        let response = other_policy
+            .execute(
+                &session,
+                Request::new("{ __typename }").data(principal.clone()),
+            )
+            .await;
+        assert_ne!(
+            envelope["cacheScope"],
+            distributed_extension(&response)["cacheScope"]
+        );
+
+        let mut anonymous = session;
+        anonymous.set("x-role", "anonymous");
+        let response = engine
+            .execute(&anonymous, Request::new("{ __typename }").data(principal))
+            .await;
+        assert_ne!(
+            envelope["cacheScope"],
+            distributed_extension(&response)["cacheScope"]
+        );
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn protocol_stream_uses_one_request_accumulator_and_raw_engine_has_no_envelope() {
+        use crate::graphql::identity::VerifiedPrincipal;
+
+        let engine = protocol_engine("public/graphql");
+        let mut session = Session::new();
+        session.set("x-role", "user");
+        let principal = VerifiedPrincipal::test_oidc(
+            "https://issuer.example",
+            "principal-a",
+            &["orders-service"],
+        );
+        let mut responses =
+            engine.execute_stream(&session, Request::new("{ __typename }").data(principal));
+        let response = responses.next().await.expect("one query response");
+        assert!(response.extensions.contains_key("distributed"));
+        assert!(responses.next().await.is_none());
+
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .connect_lazy("sqlite::memory:")
+            .unwrap();
+        let project = DistributedProjectManifest::new("orders-service").table_schema(orders());
+        let raw = GraphqlEngine::from_manifest(&project, pool)
+            .unwrap()
+            .roles(&["user"])
+            .grant_all("user")
+            .build()
+            .unwrap();
+        let response = raw.execute(&session, Request::new("{ __typename }")).await;
+        assert!(!response.extensions.contains_key("distributed"));
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn protocol_configuration_requires_real_key_and_service_identity() {
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .connect_lazy("sqlite::memory:")
+            .unwrap();
+        let result = GraphqlEngine::builder(pool.clone())
+            .service_id("orders-service")
+            .protocol_token_key([0; 32])
+            .build();
+        let error = match result {
+            Ok(_) => panic!("all-zero protocol key must fail"),
+            Err(error) => error,
+        };
+        assert!(error.to_string().contains("must not be all zero"));
+
+        let result = GraphqlEngine::builder(pool)
+            .protocol_token_key([7; 32])
+            .build();
+        let error = match result {
+            Ok(_) => panic!("protocol key without service identity must fail"),
+            Err(error) => error,
+        };
+        assert!(error.to_string().contains("stable service ID"));
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn one_role_surface_drives_runtime_sdl_manifest_and_limits() {
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .connect_lazy("sqlite::memory:")
+            .unwrap();
+        let project = DistributedProjectManifest::new("orders-service").table_schema(orders());
+        let commands = TypedCommandInventory::from_contracts(&[test_command::<
+            ChangeOrderInput,
+            ChangeOrderPayload,
+        >(
+            "order.refresh",
+            "orders_refresh",
+            &["user"],
+        )])
+        .unwrap();
+        let mut builder = GraphqlEngine::from_manifest(&project, pool)
+            .unwrap()
+            .roles(&["user"])
+            .grant_all("user")
+            .default_limit(7)
+            .max_limit(19)
+            .client_projectors([SurfaceProjector::new("project_orders")
+                .facts(["order.changed"])
+                .models(["OrderView"])]);
+        builder.command_binding = Some(test_service_binding("orders-service", &commands));
+        builder.typed_commands = commands;
+        let engine = builder.build().unwrap();
+
+        let stored = engine.surface_for_role("user").unwrap();
+        assert_eq!(engine.service_id(), Some("orders-service"));
+        let export = engine.client_surface_for_role("user").unwrap();
+        assert!(Arc::ptr_eq(&stored, export.surface()));
+        let manifest = export.manifest().unwrap();
+        assert_eq!(manifest, export.manifest().unwrap());
+        assert_eq!(manifest.service_id, "orders-service");
+        let static_sdl = engine.ir_sdl_for_role("user").unwrap();
+        let runtime_sdl = engine.sdl_for_role("user").unwrap();
+
+        for type_name in [
+            "Query",
+            "Subscription",
+            "Mutation",
+            "OrderView",
+            "orders_aggregate",
+            "orders_aggregate_fields",
+        ] {
+            assert_eq!(
+                type_field_names(&static_sdl, type_name),
+                type_field_names(&runtime_sdl, type_name),
+                "runtime/static field drift for {type_name}"
+            );
+        }
+
+        let query_roots: BTreeSet<String> = manifest
+            .roots
+            .iter()
+            .filter(|root| root.operation == ClientRootOperation::Query)
+            .map(|root| root.name.clone())
+            .collect();
+        let subscription_roots: BTreeSet<String> = manifest
+            .roots
+            .iter()
+            .filter(|root| root.operation == ClientRootOperation::Subscription)
+            .map(|root| root.name.clone())
+            .collect();
+        let runtime_query_roots = type_field_names(&runtime_sdl, "Query")
+            .into_iter()
+            .filter(|field| field != "commandStatus")
+            .collect();
+        assert_eq!(query_roots, runtime_query_roots);
+        assert_eq!(
+            subscription_roots,
+            type_field_names(&runtime_sdl, "Subscription")
+        );
+        assert_eq!(manifest.commands.len(), 1);
+        assert_eq!(manifest.commands[0].name, "order.refresh");
+        assert_eq!(
+            manifest
+                .protocol_operations
+                .command_status
+                .as_ref()
+                .unwrap()
+                .name,
+            "Distributed_CommandStatus"
+        );
+        assert_eq!(
+            type_field_names(&runtime_sdl, "Mutation"),
+            BTreeSet::from(["orders_refresh".into()])
+        );
+        assert_eq!(
+            manifest.models[0]
+                .fields
+                .iter()
+                .map(|field| field.name.clone())
+                .collect::<BTreeSet<_>>(),
+            type_field_names(&runtime_sdl, "OrderView")
+        );
+        assert_eq!(subscription_roots, BTreeSet::from(["orders".into()]));
+        assert!(!runtime_sdl.contains("type Subscription {\n\torders_by_pk"));
+
+        let list = manifest
+            .roots
+            .iter()
+            .find(|root| root.id == "query:orders")
+            .unwrap();
+        assert_eq!(list.pagination.as_ref().unwrap().default_limit, 7);
+        assert_eq!(list.pagination.as_ref().unwrap().max_limit, 19);
+        assert_eq!(manifest.projectors[0].name, "project_orders");
+        let runtime_json = input_field_names(&runtime_sdl, "JSON_comparison_exp");
+        assert_eq!(
+            runtime_json,
+            input_field_names(&static_sdl, "JSON_comparison_exp")
+        );
+        let metadata_ops: BTreeSet<String> = list
+            .filter
+            .as_ref()
+            .unwrap()
+            .fields
+            .iter()
+            .find(|field| field.name == "metadata")
+            .unwrap()
+            .operators
+            .iter()
+            .cloned()
+            .collect();
+        assert_eq!(metadata_ops, runtime_json);
+        for forbidden in ["_contains", "_contained_in", "_has_key"] {
+            assert!(!metadata_ops.contains(forbidden));
+        }
+        assert_eq!(
+            manifest.schema_fingerprint,
+            "sha256:7ab469f12920ea4c954eab0419bb50ee4bca155f7644d4dea9e0dfda022b1670"
+        );
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn manual_engine_client_export_requires_explicit_service_id() {
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .connect_lazy("sqlite::memory:")
+            .unwrap();
+        let engine = GraphqlEngine::builder(pool)
+            .register_schema_exposed(orders())
+            .unwrap()
+            .roles(&["user"])
+            .grant_all("user")
+            .build()
+            .unwrap();
+
+        let error = engine.client_surface_for_role("user").unwrap_err();
+        assert!(error
+            .to_string()
+            .contains("GraphqlEngineBuilder::service_id"));
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn empty_role_static_runtime_and_manifest_are_truthful() {
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .connect_lazy("sqlite::memory:")
+            .unwrap();
+        let project = DistributedProjectManifest::new("orders-service").table_schema(orders());
+        let engine = GraphqlEngine::from_manifest(&project, pool)
+            .unwrap()
+            .roles(&["empty"])
+            .build()
+            .unwrap();
+
+        let static_sdl = engine.ir_sdl_for_role("empty").unwrap();
+        let runtime_sdl = engine.sdl_for_role("empty").unwrap();
+        assert_eq!(
+            type_field_names(&static_sdl, "Query"),
+            BTreeSet::from(["_empty".into()])
+        );
+        assert_eq!(
+            type_field_names(&static_sdl, "Query"),
+            type_field_names(&runtime_sdl, "Query")
+        );
+        let manifest = engine.client_manifest_for_role("empty").unwrap();
+        assert!(manifest.roots.is_empty());
+        assert!(!manifest.capabilities.live_queries);
+    }
+
+    #[cfg(feature = "postgres")]
+    #[tokio::test]
+    async fn postgres_role_surface_drives_runtime_sdl_and_manifest() {
+        let pool = sqlx::postgres::PgPoolOptions::new()
+            .connect_lazy("postgres://postgres:postgres@localhost/distributed_test")
+            .unwrap();
+        let project = DistributedProjectManifest::new("orders-service").table_schema(orders());
+        let engine = GraphqlEngine::from_manifest(&project, pool)
+            .unwrap()
+            .roles(&["user"])
+            .grant_all("user")
+            .default_limit(7)
+            .max_limit(19)
+            .build()
+            .unwrap();
+
+        let export = engine.client_surface_for_role("user").unwrap();
+        let manifest = export.manifest().unwrap();
+        assert_eq!(manifest, export.manifest().unwrap());
+        let static_sdl = engine.ir_sdl_for_role("user").unwrap();
+        let runtime_sdl = engine.sdl_for_role("user").unwrap();
+        for type_name in [
+            "Query",
+            "Subscription",
+            "OrderView",
+            "orders_aggregate",
+            "orders_aggregate_fields",
+        ] {
+            assert_eq!(
+                type_field_names(&static_sdl, type_name),
+                type_field_names(&runtime_sdl, type_name),
+                "Postgres runtime/static field drift for {type_name}"
+            );
+        }
+
+        let query_roots: BTreeSet<String> = manifest
+            .roots
+            .iter()
+            .filter(|root| root.operation == ClientRootOperation::Query)
+            .map(|root| root.name.clone())
+            .collect();
+        let runtime_query_roots = type_field_names(&runtime_sdl, "Query")
+            .into_iter()
+            .filter(|field| field != "commandStatus")
+            .collect();
+        assert_eq!(query_roots, runtime_query_roots);
+        assert_eq!(
+            manifest.models[0]
+                .fields
+                .iter()
+                .map(|field| field.name.clone())
+                .collect::<BTreeSet<_>>(),
+            type_field_names(&runtime_sdl, "OrderView")
+        );
+
+        let runtime_json = input_field_names(&runtime_sdl, "JSON_comparison_exp");
+        assert_eq!(
+            runtime_json,
+            input_field_names(&static_sdl, "JSON_comparison_exp")
+        );
+        let metadata_ops: BTreeSet<String> = manifest
+            .roots
+            .iter()
+            .find(|root| root.id == "query:orders")
+            .unwrap()
+            .filter
+            .as_ref()
+            .unwrap()
+            .fields
+            .iter()
+            .find(|field| field.name == "metadata")
+            .unwrap()
+            .operators
+            .iter()
+            .cloned()
+            .collect();
+        assert_eq!(metadata_ops, runtime_json);
+        for required in ["_contains", "_contained_in", "_has_key"] {
+            assert!(metadata_ops.contains(required));
+        }
+        assert_eq!(manifest.service_id, "orders-service");
+        assert_eq!(
+            manifest.schema_fingerprint,
+            "sha256:03fa90383fc0b6aa6a53784cffb83f1fa0c1674c381f4ec175897ffec280ec8b"
+        );
+    }
+
+    fn customers() -> TableSchema {
+        TableSchema {
+            model_name: "CustomerView".into(),
+            table_name: "customers".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new("customer_id", "customer_id", ColumnType::Text)
+                },
+                TableColumn::new("display_name", "display_name", ColumnType::Text),
+                TableColumn::new("internal_note", "internal_note", ColumnType::Text),
+            ],
+            primary_key: PrimaryKey::new(["customer_id"]),
+            version_column: None,
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        }
+    }
+
+    fn type_field(
+        name: &str,
+        type_name: &str,
+        nullable: bool,
+        list: bool,
+        nested: Option<GraphqlTypeDef>,
+    ) -> GraphqlTypeField {
+        GraphqlTypeField {
+            name: name.into(),
+            type_name: type_name.into(),
+            nullable,
+            list,
+            item_nullable: false,
+            nested: nested.map(Box::new),
+        }
+    }
+
+    struct ChangeOrderInput;
+
+    impl GraphqlInputType for ChangeOrderInput {
+        fn graphql_type() -> GraphqlTypeDef {
+            let patch = GraphqlTypeDef::new(
+                "OrderPatchInput",
+                vec![
+                    type_field("status", "String", false, false, None),
+                    type_field("metadata", "JSON", true, false, None),
+                ],
+            );
+            GraphqlTypeDef::new(
+                "ChangeOrderInput",
+                vec![
+                    type_field("patch", "OrderPatchInput", false, false, Some(patch)),
+                    type_field("order_id", "String", false, false, None),
+                ],
+            )
+        }
+    }
+
+    struct ChangeOrderPayload;
+
+    impl GraphqlOutputType for ChangeOrderPayload {
+        fn graphql_type() -> GraphqlTypeDef {
+            let changed_order = GraphqlTypeDef::new(
+                "ChangedOrder",
+                vec![
+                    type_field("status", "String", false, false, None),
+                    type_field("order_id", "String", false, false, None),
+                ],
+            );
+            GraphqlTypeDef::new(
+                "ChangeOrderPayload",
+                vec![
+                    type_field("warnings", "String", true, true, None),
+                    type_field("order", "ChangedOrder", false, false, Some(changed_order)),
+                    type_field("accepted", "Boolean", false, false, None),
+                ],
+            )
+        }
+    }
+
+    fn matrix_project() -> DistributedProjectManifest {
+        DistributedProjectManifest::new("acceptance-service")
+            .table_schema(orders())
+            .table_schema(customers())
+    }
+
+    fn matrix_commands() -> TypedCommandInventory {
+        TypedCommandInventory::from_contracts(&[
+            test_command::<ChangeOrderInput, ChangeOrderPayload>(
+                "order.change",
+                "orders_change",
+                &["restricted", "admin"],
+            ),
+            test_command::<ChangeOrderInput, ChangeOrderPayload>(
+                "order.force_archive",
+                "orders_force_archive",
+                &["admin"],
+            ),
+        ])
+        .unwrap()
+    }
+
+    fn matrix_projectors() -> Vec<SurfaceProjector> {
+        vec![
+            SurfaceProjector::new("project_customers")
+                .facts(["customer.changed"])
+                .models(["CustomerView"]),
+            SurfaceProjector::new("project_orders")
+                .facts(["order.changed"])
+                .models(["OrderView"]),
+        ]
+    }
+
+    fn restricted_read() -> ReadPermission {
+        read()
+            .columns(["order_id", "status"])
+            .rows(col("status").eq("OPEN"))
+            .limit(5)
+    }
+
+    fn insert_permission(
+        builder: &mut GraphqlEngineBuilder,
+        model: &str,
+        role: &str,
+        permission: ReadPermission,
+    ) {
+        assert!(builder
+            .permissions
+            .insert((model.into(), role.into()), RoleModelPerm { permission },)
+            .is_none());
+    }
+
+    fn matrix_engine(pool: GraphqlPool) -> GraphqlEngine {
+        let project = matrix_project();
+        let mut builder = GraphqlEngine::from_manifest(&project, pool)
+            .unwrap()
+            .roles(&["restricted", "admin"])
+            .default_limit(11)
+            .max_limit(23)
+            .client_projectors(matrix_projectors());
+        let commands = matrix_commands();
+        builder.command_binding = Some(test_service_binding("acceptance-service", &commands));
+        builder.typed_commands = commands;
+        insert_permission(&mut builder, "OrderView", "restricted", restricted_read());
+        insert_permission(
+            &mut builder,
+            "OrderView",
+            "admin",
+            read().all_columns().aggregations(),
+        );
+        insert_permission(
+            &mut builder,
+            "CustomerView",
+            "admin",
+            read().all_columns().aggregations(),
+        );
+        builder.build().unwrap()
+    }
+
+    fn independent_manifest(dialect: SurfaceDialect, role: &str) -> DistributedClientManifest {
+        let project = matrix_project();
+        let options = SurfaceOptions {
+            dialect,
+            aggregates: true,
+            subscriptions: true,
+            default_limit: 11,
+            max_limit: 23,
+        };
+        let commands = matrix_commands();
+        let full = build_surface(&project.tables, &options)
+            .unwrap()
+            .with_typed_commands(&commands)
+            .unwrap()
+            .with_service_binding(Some(test_service_binding("acceptance-service", &commands)))
+            .with_projectors(matrix_projectors())
+            .unwrap();
+        let grants = match role {
+            "restricted" => BTreeMap::from([(
+                "OrderView".into(),
+                RoleGrant::columns(["order_id", "status"])
+                    .rows(col("status").eq("OPEN"))
+                    .limit(5),
+            )]),
+            "admin" => BTreeMap::from([
+                (
+                    "OrderView".into(),
+                    RoleGrant::all_columns().with_aggregations(),
+                ),
+                (
+                    "CustomerView".into(),
+                    RoleGrant::all_columns().with_aggregations(),
+                ),
+            ]),
+            other => panic!("unexpected matrix role `{other}`"),
+        };
+        let selected = surface_for_role(&full, role, &grants).unwrap();
+        DistributedClientSurfaceExport::from_project(&project, selected)
+            .unwrap()
+            .manifest()
+            .unwrap()
+    }
+
+    fn definition_inventory(sdl: &str) -> BTreeMap<String, BTreeSet<String>> {
+        let mut inventory: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
+        let mut current: Option<String> = None;
+        for line in sdl.lines() {
+            let line = line.trim();
+            if current.is_none() {
+                let declaration = line
+                    .strip_prefix("type ")
+                    .or_else(|| line.strip_prefix("input "));
+                if let Some(declaration) = declaration {
+                    if line.contains('{') {
+                        let name = declaration
+                            .split([' ', '{'])
+                            .next()
+                            .expect("definition name")
+                            .to_string();
+                        inventory.entry(name.clone()).or_default();
+                        current = Some(name);
+                    }
+                }
+                continue;
+            }
+            if line == "}" {
+                current = None;
+                continue;
+            }
+            if line.is_empty() || line.starts_with('#') || line.starts_with('"') {
+                continue;
+            }
+            let field = line
+                .split(['(', ':'])
+                .next()
+                .map(str::trim)
+                .filter(|field| !field.is_empty());
+            if let (Some(definition), Some(field)) = (&current, field) {
+                inventory
+                    .get_mut(definition)
+                    .expect("current definition")
+                    .insert(field.into());
+            }
+        }
+        inventory
+    }
+
+    fn sha256(bytes: &[u8]) -> String {
+        format!("sha256:{:x}", Sha256::digest(bytes))
+    }
+
+    #[derive(Clone, Copy)]
+    struct ArtifactGoldens {
+        manifest: &'static str,
+        static_sdl: &'static str,
+        runtime_sdl: &'static str,
+    }
+
+    async fn assert_role_matrix(
+        engine: &GraphqlEngine,
+        dialect: SurfaceDialect,
+        role: &str,
+        expected: ArtifactGoldens,
+    ) {
+        let stored = engine.surface_for_role(role).unwrap();
+        let export = engine.client_surface_for_role(role).unwrap();
+        assert!(Arc::ptr_eq(&stored, export.surface()));
+        let manifest = export.manifest().unwrap();
+        assert_eq!(manifest, export.manifest().unwrap());
+        assert_eq!(manifest, independent_manifest(dialect, role));
+
+        let static_sdl = engine.ir_sdl_for_role(role).unwrap();
+        let runtime_sdl = engine.sdl_for_role(role).unwrap();
+        assert_eq!(
+            definition_inventory(&static_sdl),
+            definition_inventory(&runtime_sdl),
+            "runtime/static definition drift for role `{role}`"
+        );
+
+        let query_roots: BTreeSet<String> = manifest
+            .roots
+            .iter()
+            .filter(|root| root.operation == ClientRootOperation::Query)
+            .map(|root| root.name.clone())
+            .collect();
+        let subscription_roots: BTreeSet<String> = manifest
+            .roots
+            .iter()
+            .filter(|root| root.operation == ClientRootOperation::Subscription)
+            .map(|root| root.name.clone())
+            .collect();
+        let runtime_read_roots = type_field_names(&runtime_sdl, "Query")
+            .into_iter()
+            .filter(|field| field != "commandStatus")
+            .collect::<BTreeSet<_>>();
+        assert_eq!(query_roots, runtime_read_roots);
+        assert_eq!(
+            subscription_roots,
+            type_field_names(&runtime_sdl, "Subscription")
+        );
+        let expected_commands = if role == "admin" { 2 } else { 1 };
+        assert_eq!(manifest.commands.len(), expected_commands);
+        assert_eq!(
+            manifest
+                .protocol_operations
+                .command_status
+                .as_ref()
+                .unwrap()
+                .name,
+            "Distributed_CommandStatus"
+        );
+        for model in &manifest.models {
+            let expected_fields: BTreeSet<String> = model
+                .fields
+                .iter()
+                .map(|field| field.name.clone())
+                .chain(model.relationships.iter().flat_map(|relationship| {
+                    std::iter::once(relationship.name.clone()).chain(
+                        relationship
+                            .aggregate
+                            .iter()
+                            .map(|aggregate| aggregate.name.clone()),
+                    )
+                }))
+                .collect();
+            assert_eq!(
+                expected_fields,
+                type_field_names(&static_sdl, &model.typename),
+                "manifest/static model drift for {}",
+                model.typename
+            );
+            assert_eq!(
+                expected_fields,
+                type_field_names(&runtime_sdl, &model.typename),
+                "manifest/runtime model drift for {}",
+                model.typename
+            );
+        }
+
+        let model_ids: BTreeSet<_> = manifest
+            .models
+            .iter()
+            .map(|model| model.id.as_str())
+            .collect();
+        let command_names: BTreeSet<_> = manifest
+            .commands
+            .iter()
+            .map(|command| command.name.as_str())
+            .collect();
+        let projector_names: BTreeSet<_> = manifest
+            .projectors
+            .iter()
+            .map(|projector| projector.name.as_str())
+            .collect();
+        match role {
+            "restricted" => {
+                assert_eq!(model_ids, BTreeSet::from(["OrderView"]));
+                assert_eq!(command_names, BTreeSet::from(["order.change"]));
+                assert_eq!(
+                    type_field_names(&runtime_sdl, "Mutation"),
+                    BTreeSet::from(["orders_change".into()])
+                );
+                assert_eq!(projector_names, BTreeSet::from(["project_orders"]));
+                assert!(!query_roots.contains("orders_aggregate"));
+                assert_eq!(manifest.models[0].fields.len(), 2);
+                assert_eq!(
+                    manifest
+                        .roots
+                        .iter()
+                        .find(|root| root.id == "query:orders")
+                        .unwrap()
+                        .pagination
+                        .as_ref()
+                        .unwrap()
+                        .default_limit,
+                    5
+                );
+            }
+            "admin" => {
+                assert_eq!(model_ids, BTreeSet::from(["CustomerView", "OrderView"]));
+                assert_eq!(
+                    command_names,
+                    BTreeSet::from(["order.change", "order.force_archive"])
+                );
+                assert_eq!(
+                    type_field_names(&runtime_sdl, "Mutation"),
+                    BTreeSet::from(["orders_change".into(), "orders_force_archive".into()])
+                );
+                assert_eq!(
+                    projector_names,
+                    BTreeSet::from(["project_customers", "project_orders"])
+                );
+                assert!(query_roots.contains("customers_aggregate"));
+                assert!(query_roots.contains("orders_aggregate"));
+            }
+            other => panic!("unexpected matrix role `{other}`"),
+        }
+
+        let manifest_json = serde_json::to_vec(&manifest).unwrap();
+        let actual_manifest = sha256(&manifest_json);
+        let actual_static_sdl = sha256(static_sdl.as_bytes());
+        let actual_runtime_sdl = sha256(runtime_sdl.as_bytes());
+        assert_eq!(actual_manifest, expected.manifest, "{dialect:?}/{role}");
+        assert_eq!(actual_static_sdl, expected.static_sdl, "{dialect:?}/{role}");
+        assert_eq!(
+            actual_runtime_sdl, expected.runtime_sdl,
+            "{dialect:?}/{role}"
+        );
+    }
+
+    async fn assert_nested_command_validates(engine: &GraphqlEngine) {
+        let operation = "mutation Client_orders_change($commandId: ID!, $input: ChangeOrderInput!) { orders_change(commandId: $commandId, input: $input) { accepted order { order_id status } warnings } }";
+        async_graphql::parser::parse_query(operation)
+            .expect("generated command operation must parse");
+
+        let request = Request::new(operation).variables(async_graphql::Variables::from_json(
+            serde_json::json!({
+                "commandId": "0190a000-0000-7000-8000-000000000042",
+                "input": {
+                    "order_id": "order-1",
+                    "patch": {
+                        "metadata": {"source": "acceptance"},
+                        "status": "READY"
+                    }
+                }
+            }),
+        ));
+        let mut session = Session::new();
+        session.set(crate::microsvc::ROLE_KEY, "admin");
+        let response = engine.execute(&session, request).await;
+        assert_eq!(response.errors.len(), 1, "{response:?}");
+        assert_eq!(
+            response.errors[0].message,
+            "command dispatcher not configured (use graphql_router_with_service)"
+        );
+    }
+
+    #[cfg(feature = "sqlite")]
+    const SQLITE_RESTRICTED_GOLDENS: ArtifactGoldens = ArtifactGoldens {
+        manifest: "sha256:b5c798e166e4c20cd7108eadd2411821af17be41c8a53d334520c42f78e8d798",
+        static_sdl: "sha256:c94afb7de76b34c6e36b897643d9523afa8872fa480bf104d8f54f95ef73ea0a",
+        runtime_sdl: "sha256:cf35a2fd5309ab6ca893b5820f4a5efdd9eef1df83013dbf6ac0ffdf63710e8e",
+    };
+
+    #[cfg(feature = "sqlite")]
+    const SQLITE_ADMIN_GOLDENS: ArtifactGoldens = ArtifactGoldens {
+        manifest: "sha256:c9eb42301111a32613a83b9e54bbc0784ef21fd5e570f41b332a31f70f9a60f0",
+        static_sdl: "sha256:8ffed8116b16792ab8f81940999489d73b51615eb863d32b1640446535913b89",
+        runtime_sdl: "sha256:d94970d5e6ca8745ec97a286332f7cf1a372e47f5e8e10df10bd67fd779d54e1",
+    };
+
+    #[cfg(feature = "postgres")]
+    const POSTGRES_RESTRICTED_GOLDENS: ArtifactGoldens = ArtifactGoldens {
+        manifest: "sha256:b5c798e166e4c20cd7108eadd2411821af17be41c8a53d334520c42f78e8d798",
+        static_sdl: "sha256:c94afb7de76b34c6e36b897643d9523afa8872fa480bf104d8f54f95ef73ea0a",
+        runtime_sdl: "sha256:cf35a2fd5309ab6ca893b5820f4a5efdd9eef1df83013dbf6ac0ffdf63710e8e",
+    };
+
+    #[cfg(feature = "postgres")]
+    const POSTGRES_ADMIN_GOLDENS: ArtifactGoldens = ArtifactGoldens {
+        manifest: "sha256:a6f45829b5395026aaad73fe36c9f5c6e50cd196cdf1fc31d396be6332f82217",
+        static_sdl: "sha256:5d3416d9926a5374ee95408c38e74bfd03b1b7ef4e2f7ee1f81752a102c4a989",
+        runtime_sdl: "sha256:08e621d86f6606260e653c67d27899f9c93a2ac4545ec0741d78445981d3d46f",
+    };
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn sqlite_restricted_admin_full_artifact_matrix() {
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .connect_lazy("sqlite::memory:")
+            .unwrap();
+        let engine = matrix_engine(pool.into());
+        assert_role_matrix(
+            &engine,
+            SurfaceDialect::Sqlite,
+            "restricted",
+            SQLITE_RESTRICTED_GOLDENS,
+        )
+        .await;
+        assert_role_matrix(
+            &engine,
+            SurfaceDialect::Sqlite,
+            "admin",
+            SQLITE_ADMIN_GOLDENS,
+        )
+        .await;
+        assert_nested_command_validates(&engine).await;
+    }
+
+    #[cfg(feature = "postgres")]
+    #[tokio::test]
+    async fn postgres_restricted_admin_full_artifact_matrix() {
+        let pool = sqlx::postgres::PgPoolOptions::new()
+            .connect_lazy("postgres://postgres:postgres@localhost/distributed_test")
+            .unwrap();
+        let engine = matrix_engine(pool.into());
+        assert_role_matrix(
+            &engine,
+            SurfaceDialect::Postgres,
+            "restricted",
+            POSTGRES_RESTRICTED_GOLDENS,
+        )
+        .await;
+        assert_role_matrix(
+            &engine,
+            SurfaceDialect::Postgres,
+            "admin",
+            POSTGRES_ADMIN_GOLDENS,
+        )
+        .await;
+        assert_nested_command_validates(&engine).await;
+    }
+
+    #[cfg(feature = "sqlite")]
+    fn composite_records() -> TableSchema {
+        TableSchema {
+            model_name: "CompositeRecord".into(),
+            table_name: "composite_records".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new("tenant_id", "tenant_id", ColumnType::Text)
+                },
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new("record_id", "record_id", ColumnType::Text)
+                },
+                TableColumn::new("value", "value", ColumnType::Text),
+            ],
+            primary_key: PrimaryKey::new(["tenant_id", "record_id"]),
+            version_column: None,
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        }
+    }
+
+    #[cfg(feature = "sqlite")]
+    fn root_arguments(sdl: &str, field: &str) -> BTreeMap<String, String> {
+        let marker = format!("{field}(");
+        let arguments = sdl
+            .split_once(&marker)
+            .unwrap_or_else(|| panic!("missing root field `{field}` in SDL:\n{sdl}"))
+            .1
+            .split_once(')')
+            .expect("root arguments should close")
+            .0;
+        arguments
+            .split(',')
+            .filter_map(|argument| argument.trim().split_once(':'))
+            .map(|(name, ty)| (name.trim().to_string(), ty.trim().to_string()))
+            .collect()
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn isolated_composite_key_root_has_runtime_static_manifest_parity() {
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .max_connections(1)
+            .connect("sqlite::memory:")
+            .await
+            .unwrap();
+        sqlx::query(
+            "CREATE TABLE composite_records (\
+                tenant_id TEXT NOT NULL, \
+                record_id TEXT NOT NULL, \
+                value TEXT NOT NULL, \
+                PRIMARY KEY (tenant_id, record_id)\
+            )",
+        )
+        .execute(&pool)
+        .await
+        .unwrap();
+        sqlx::query(
+            "INSERT INTO composite_records (tenant_id, record_id, value) VALUES \
+                ('tenant-a', 'record-1', 'first'), \
+                ('tenant-a', 'record-2', 'second')",
+        )
+        .execute(&pool)
+        .await
+        .unwrap();
+        let project =
+            DistributedProjectManifest::new("composite-service").table_schema(composite_records());
+        let engine = GraphqlEngine::from_manifest(&project, pool.clone())
+            .unwrap()
+            .roles(&["admin"])
+            .grant_all("admin")
+            .build()
+            .unwrap();
+        let static_sdl = engine.ir_sdl_for_role("admin").unwrap();
+        let runtime_sdl = engine.sdl_for_role("admin").unwrap();
+        let manifest = engine.client_manifest_for_role("admin").unwrap();
+        let by_pk = manifest
+            .roots
+            .iter()
+            .find(|root| root.id == "query:composite_records_by_pk")
+            .unwrap();
+        assert_eq!(
+            by_pk
+                .arguments
+                .iter()
+                .map(|argument| argument.name.as_str())
+                .collect::<Vec<_>>(),
+            vec!["tenant_id", "record_id"]
+        );
+        let manifest_arguments: BTreeMap<String, String> = by_pk
+            .arguments
+            .iter()
+            .map(|argument| {
+                let mut ty = if argument.list {
+                    format!("[{}!]", argument.type_name)
+                } else {
+                    argument.type_name.clone()
+                };
+                if !argument.nullable {
+                    ty.push('!');
+                }
+                (argument.name.clone(), ty)
+            })
+            .collect();
+        assert_eq!(
+            manifest_arguments,
+            BTreeMap::from([
+                ("record_id".into(), "String!".into()),
+                ("tenant_id".into(), "String!".into()),
+            ])
+        );
+        assert_eq!(
+            manifest_arguments,
+            root_arguments(&static_sdl, "composite_records_by_pk")
+        );
+        assert_eq!(
+            manifest_arguments,
+            root_arguments(&runtime_sdl, "composite_records_by_pk")
+        );
+        let ModelNormalization::Normalized { fields, encoding } = &manifest.models[0].normalization
+        else {
+            panic!("isolated composite key must be normalized")
+        };
+        assert_eq!(
+            fields
+                .iter()
+                .map(|field| field.name.as_str())
+                .collect::<Vec<_>>(),
+            vec!["tenant_id", "record_id"]
+        );
+        assert_eq!(encoding, "canonical_json_tuple_v1");
+
+        let mut session = Session::new();
+        session.set(crate::microsvc::ROLE_KEY, "admin");
+        let response = engine
+            .execute(
+                &session,
+                Request::new(
+                    r#"{
+                        selected: composite_records_by_pk(
+                            tenant_id: "tenant-a"
+                            record_id: "record-2"
+                        ) {
+                            tenant_id
+                            record_id
+                            value
+                        }
+                        missing: composite_records_by_pk(
+                            tenant_id: "tenant-a"
+                            record_id: "record-missing"
+                        ) {
+                            tenant_id
+                            record_id
+                            value
+                        }
+                    }"#,
+                ),
+            )
+            .await;
+        assert!(response.errors.is_empty(), "{response:?}");
+        assert_eq!(
+            response.data.into_json().unwrap(),
+            serde_json::json!({
+                "selected": {
+                    "tenant_id": "tenant-a",
+                    "record_id": "record-2",
+                    "value": "second"
+                },
+                "missing": null
+            })
+        );
+    }
+
+    #[cfg(feature = "sqlite")]
+    fn simple_records() -> TableSchema {
+        TableSchema {
+            model_name: "SimpleRecord".into(),
+            table_name: "simple_records".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new("simple_id", "simple_id", ColumnType::Text)
+                },
+                TableColumn::new("tenant_id", "tenant_id", ColumnType::Text),
+            ],
+            primary_key: PrimaryKey::new(["simple_id"]),
+            version_column: None,
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        }
+    }
+
+    #[cfg(feature = "sqlite")]
+    fn policy_parents() -> TableSchema {
+        TableSchema {
+            model_name: "PolicyParentView".into(),
+            table_name: "policy_parents".into(),
+            columns: vec![TableColumn {
+                primary_key: true,
+                ..TableColumn::new("parent_id", "parent_id", ColumnType::Text)
+            }],
+            primary_key: PrimaryKey::new(["parent_id"]),
+            version_column: None,
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: vec![RelationshipDef {
+                field_name: "children".into(),
+                kind: RelationshipKind::HasMany,
+                target_model: "PolicyChildView".into(),
+                foreign_key: Some("parent_id".into()),
+                through: None,
+                target_foreign_key: None,
+            }],
+            kind: TableKind::ReadModel,
+        }
+    }
+
+    #[cfg(feature = "sqlite")]
+    fn policy_children() -> TableSchema {
+        TableSchema {
+            model_name: "PolicyChildView".into(),
+            table_name: "policy_children".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new("child_id", "child_id", ColumnType::Text)
+                },
+                TableColumn::new("parent_id", "parent_id", ColumnType::Text),
+                TableColumn::new("label", "label", ColumnType::Text),
+                TableColumn::new("visibility", "visibility", ColumnType::Text),
+            ],
+            primary_key: PrimaryKey::new(["child_id"]),
+            version_column: None,
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        }
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn relationship_where_applies_the_target_models_row_policy() {
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .max_connections(1)
+            .connect("sqlite::memory:")
+            .await
+            .unwrap();
+        sqlx::query("CREATE TABLE policy_parents (parent_id TEXT PRIMARY KEY NOT NULL)")
+            .execute(&pool)
+            .await
+            .unwrap();
+        sqlx::query(
+            "CREATE TABLE policy_children (\
+                child_id TEXT PRIMARY KEY NOT NULL, \
+                parent_id TEXT NOT NULL, \
+                label TEXT NOT NULL, \
+                visibility TEXT NOT NULL\
+            )",
+        )
+        .execute(&pool)
+        .await
+        .unwrap();
+        sqlx::query(
+            "INSERT INTO policy_parents (parent_id) VALUES \
+                ('parent-allowed'), \
+                ('parent-denied')",
+        )
+        .execute(&pool)
+        .await
+        .unwrap();
+        sqlx::query(
+            "INSERT INTO policy_children (child_id, parent_id, label, visibility) VALUES \
+                ('child-allowed', 'parent-allowed', 'match', 'allowed'), \
+                ('child-denied', 'parent-denied', 'match', 'denied')",
+        )
+        .execute(&pool)
+        .await
+        .unwrap();
+
+        let project = DistributedProjectManifest::new("relationship-policy-service")
+            .table_schema(policy_parents())
+            .table_schema(policy_children());
+        let mut builder = GraphqlEngine::from_manifest(&project, pool)
+            .unwrap()
+            .roles(&["restricted"]);
+        insert_permission(
+            &mut builder,
+            "PolicyParentView",
+            "restricted",
+            read().all_columns(),
+        );
+        insert_permission(
+            &mut builder,
+            "PolicyChildView",
+            "restricted",
+            read().all_columns().rows(col("visibility").eq("allowed")),
+        );
+        let engine = builder.build().unwrap();
+        let mut session = Session::new();
+        session.set(crate::microsvc::ROLE_KEY, "restricted");
+
+        let response = engine
+            .execute(
+                &session,
+                Request::new(
+                    r#"{
+                        policy_parents(
+                            where: { children: { label: { _eq: "match" } } }
+                        ) {
+                            parent_id
+                        }
+                    }"#,
+                ),
+            )
+            .await;
+
+        assert!(response.errors.is_empty(), "{response:?}");
+        assert_eq!(
+            response.data.into_json().unwrap(),
+            serde_json::json!({
+                "policy_parents": [
+                    {"parent_id": "parent-allowed"}
+                ]
+            })
+        );
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn composite_key_relationship_topology_is_rejected_in_both_directions() {
+        let cases = [
+            {
+                let mut composite = composite_records();
+                composite.columns.push(TableColumn::new(
+                    "simple_id",
+                    "simple_id",
+                    ColumnType::Text,
+                ));
+                composite.relationships.push(RelationshipDef {
+                    field_name: "simple".into(),
+                    kind: RelationshipKind::BelongsTo,
+                    target_model: "SimpleRecord".into(),
+                    foreign_key: Some("simple_id".into()),
+                    through: None,
+                    target_foreign_key: None,
+                });
+                ("outgoing", composite, simple_records())
+            },
+            {
+                let composite = composite_records();
+                let mut simple = simple_records();
+                simple.relationships.push(RelationshipDef {
+                    field_name: "composite".into(),
+                    kind: RelationshipKind::BelongsTo,
+                    target_model: "CompositeRecord".into(),
+                    foreign_key: Some("tenant_id".into()),
+                    through: None,
+                    target_foreign_key: None,
+                });
+                ("incoming", composite, simple)
+            },
+        ];
+        for (direction, composite, simple) in cases {
+            let pool = sqlx::sqlite::SqlitePoolOptions::new()
+                .connect_lazy("sqlite::memory:")
+                .unwrap();
+            let project = DistributedProjectManifest::new("composite-service")
+                .table_schema(composite)
+                .table_schema(simple);
+            let error = GraphqlEngine::from_manifest(&project, pool)
+                .unwrap()
+                .roles(&["admin"])
+                .grant_all("admin")
+                .build()
+                .err()
+                .expect("composite relationship topology must fail");
+            assert!(
+                error.to_string().contains("relationship topology"),
+                "{direction}: {error}"
+            );
+        }
+    }
+
+    #[cfg(feature = "sqlite")]
+    fn metrics() -> TableSchema {
+        TableSchema {
+            model_name: "MetricView".into(),
+            table_name: "metrics".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new("metric_id", "metric_id", ColumnType::Text)
+                },
+                TableColumn::new("value", "value", ColumnType::Float),
+            ],
+            primary_key: PrimaryKey::new(["metric_id"]),
+            version_column: None,
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        }
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn engine_rejects_non_finite_row_policy_literals_and_accepts_finite_values() {
+        for value in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
+            for predicate in [col("value").eq(value), col("value").is_in([value])] {
+                let pool = sqlx::sqlite::SqlitePoolOptions::new()
+                    .connect_lazy("sqlite::memory:")
+                    .unwrap();
+                let project =
+                    DistributedProjectManifest::new("metrics-service").table_schema(metrics());
+                let mut builder = GraphqlEngine::from_manifest(&project, pool)
+                    .unwrap()
+                    .roles(&["restricted"]);
+                insert_permission(
+                    &mut builder,
+                    "MetricView",
+                    "restricted",
+                    read().all_columns().rows(predicate),
+                );
+                let error = builder
+                    .build()
+                    .err()
+                    .expect("non-finite row policy literal must fail");
+                assert!(error.to_string().contains("must be finite"), "{error}");
+            }
+        }
+
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .connect_lazy("sqlite::memory:")
+            .unwrap();
+        let project = DistributedProjectManifest::new("metrics-service").table_schema(metrics());
+        let mut builder = GraphqlEngine::from_manifest(&project, pool)
+            .unwrap()
+            .roles(&["restricted"]);
+        insert_permission(
+            &mut builder,
+            "MetricView",
+            "restricted",
+            read().all_columns().rows(FilterExpr::And(vec![
+                col("value").eq(1.25_f64),
+                col("value").is_in([-1.25_f64, 0.0, 99.5]),
+            ])),
+        );
+        builder.build().unwrap();
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn engine_rejects_mistyped_cmp_and_every_in_row_policy_literal() {
+        let invalid = [
+            (
+                FilterExpr::Cmp {
+                    column: "metric_id".into(),
+                    op: crate::graphql::filter::CmpOp::Eq,
+                    rhs: Operand::Lit(crate::graphql::LitValue::Json(serde_json::json!(
+                        "metric-1"
+                    ))),
+                },
+                "literal kind `json`",
+            ),
+            (
+                FilterExpr::In {
+                    column: "value".into(),
+                    values: vec![
+                        Operand::from(1.0),
+                        Operand::Lit(crate::graphql::LitValue::Json(serde_json::json!(2.0))),
+                    ],
+                    negated: false,
+                },
+                "IN operand 1",
+            ),
+            (
+                FilterExpr::Cmp {
+                    column: "metric_id".into(),
+                    op: crate::graphql::filter::CmpOp::HasKey,
+                    rhs: Operand::from("tenant"),
+                },
+                "operator `HasKey`",
+            ),
+        ];
+        for (predicate, expected) in invalid {
+            let pool = sqlx::sqlite::SqlitePoolOptions::new()
+                .connect_lazy("sqlite::memory:")
+                .unwrap();
+            let project =
+                DistributedProjectManifest::new("metrics-service").table_schema(metrics());
+            let mut builder = GraphqlEngine::from_manifest(&project, pool)
+                .unwrap()
+                .roles(&["restricted"]);
+            insert_permission(
+                &mut builder,
+                "MetricView",
+                "restricted",
+                read().all_columns().rows(predicate),
+            );
+            let error = builder
+                .build()
+                .err()
+                .expect("mistyped row-policy literal must fail");
+            assert!(error.to_string().contains(expected), "{error}");
+        }
+    }
+
+    #[cfg(feature = "sqlite")]
+    #[tokio::test]
+    async fn sqlite_nocase_can_equate_unequal_code_unit_strings() {
+        let pool = sqlx::sqlite::SqlitePoolOptions::new()
+            .connect("sqlite::memory:")
+            .await
+            .unwrap();
+        let equal: i64 = sqlx::query_scalar("SELECT 'A' = 'a' COLLATE NOCASE")
+            .fetch_one(&pool)
+            .await
+            .unwrap();
+        assert_eq!(equal, 1);
+        assert_ne!("A", "a");
+    }
+}
diff --git a/src/graphql/engine/validation.rs b/src/graphql/engine/validation.rs
new file mode 100644
index 00000000..4e0fd955
--- /dev/null
+++ b/src/graphql/engine/validation.rs
@@ -0,0 +1,173 @@
+use super::*;
+
+pub(crate) fn validate_generated_names(
+    catalog: &BTreeMap<String, CatalogEntry>,
+) -> Result<(), GraphqlBuildError> {
+    let mut names: BTreeSet<String> = reserved_type_names().map(str::to_string).collect();
+    for entry in catalog.values().filter(|e| e.exposed) {
+        let schema = &entry.schema;
+        for name in [
+            object_type_name(schema).to_string(),
+            root_list_field(schema).to_string(),
+            by_pk_field(schema),
+            format!("{}_bool_exp", schema.table_name),
+            format!("{}_order_by", schema.table_name),
+            format!("{}_aggregate", schema.table_name),
+        ] {
+            if !is_valid_graphql_name(&name) {
+                return Err(GraphqlBuildError(format!(
+                    "generated name `{name}` is not a valid GraphQL name"
+                )));
+            }
+            if !names.insert(name.clone()) {
+                return Err(GraphqlBuildError(format!(
+                    "generated name `{name}` collides with another type or field"
+                )));
+            }
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_filter(
+    filter: &FilterExpr,
+    schema: &TableSchema,
+    catalog: &BTreeMap<String, CatalogEntry>,
+    is_anonymous: bool,
+    model: &str,
+    role: &str,
+) -> Result<(), GraphqlBuildError> {
+    filter.validate_row_policy_literals().map_err(|error| {
+        GraphqlBuildError(format!(
+            "invalid row policy for model `{model}` role `{role}`: {error}"
+        ))
+    })?;
+    if is_anonymous {
+        let mut claims = Vec::new();
+        filter.visit_claims(|c| claims.push(c.to_string()));
+        if !claims.is_empty() {
+            return Err(GraphqlBuildError(format!(
+                "claim() is not allowed in anonymous role filters (model `{model}`, claims: {})",
+                claims.join(", ")
+            )));
+        }
+    }
+
+    filter.visit_columns(|col| {
+        let _ = col;
+    });
+    // Re-walk for proper error returns.
+    validate_filter_inner(filter, schema, catalog, model, role)
+}
+
+fn validate_filter_inner(
+    filter: &FilterExpr,
+    schema: &TableSchema,
+    catalog: &BTreeMap<String, CatalogEntry>,
+    model: &str,
+    role: &str,
+) -> Result<(), GraphqlBuildError> {
+    match filter {
+        FilterExpr::And(xs) | FilterExpr::Or(xs) => {
+            for x in xs {
+                validate_filter_inner(x, schema, catalog, model, role)?;
+            }
+        }
+        FilterExpr::Not(x) => validate_filter_inner(x, schema, catalog, model, role)?,
+        FilterExpr::Cmp { column, op, rhs } => {
+            let col = schema
+                .columns
+                .iter()
+                .find(|c| c.column_name == *column)
+                .ok_or_else(|| {
+                    GraphqlBuildError(format!(
+                        "unknown column `{column}` in filter for `{model}` role `{role}`"
+                    ))
+                })?;
+            if matches!(col.column_type, ColumnType::Json) && matches!(rhs, Operand::Claim(_)) {
+                return Err(GraphqlBuildError(format!(
+                    "claims cannot compare to Json columns (`{column}` on `{model}`)"
+                )));
+            }
+            validate_row_policy_operand_literal(column, &col.column_type, Some(*op), rhs).map_err(
+                |error| {
+                    GraphqlBuildError(format!(
+                        "invalid row policy for model `{model}` role `{role}`: {error}"
+                    ))
+                },
+            )?;
+        }
+        FilterExpr::In { column, values, .. } => {
+            let col = schema
+                .columns
+                .iter()
+                .find(|candidate| candidate.column_name == *column)
+                .ok_or_else(|| {
+                    GraphqlBuildError(format!(
+                        "unknown column `{column}` in filter for `{model}` role `{role}`"
+                    ))
+                })?;
+            for (index, value) in values.iter().enumerate() {
+                validate_row_policy_operand_literal(column, &col.column_type, None, value)
+                    .map_err(|error| {
+                        GraphqlBuildError(format!(
+                            "invalid row policy for model `{model}` role `{role}` IN operand {index}: {error}"
+                        ))
+                    })?;
+            }
+        }
+        FilterExpr::IsNull { column, .. } => {
+            if !schema.columns.iter().any(|c| c.column_name == *column) {
+                return Err(GraphqlBuildError(format!(
+                    "unknown column `{column}` in filter for `{model}` role `{role}`"
+                )));
+            }
+        }
+        FilterExpr::Rel { field, predicate } => {
+            let rel = schema
+                .relationships
+                .iter()
+                .find(|r| r.field_name == *field)
+                .ok_or_else(|| {
+                    GraphqlBuildError(format!(
+                        "rel(`{field}`) is not a relationship on model `{model}`"
+                    ))
+                })?;
+            let target = catalog.get(&rel.target_model).ok_or_else(|| {
+                GraphqlBuildError(format!(
+                    "rel(`{field}`) target `{}` is not in the catalog (model `{model}`)",
+                    rel.target_model
+                ))
+            })?;
+            if matches!(rel.kind, RelationshipKind::ManyToMany) {
+                let through = rel.through.as_deref().ok_or_else(|| {
+                    GraphqlBuildError(format!(
+                        "rel(`{field}`) many-to-many missing through on `{model}`"
+                    ))
+                })?;
+                let through_model = catalog
+                    .values()
+                    .find(|e| e.schema.table_name == through)
+                    .ok_or_else(|| {
+                        GraphqlBuildError(format!(
+                            "rel(`{field}`) through table `{through}` not in catalog"
+                        ))
+                    })?;
+                let _ = through_model;
+            }
+            validate_filter_inner(predicate, &target.schema, catalog, &rel.target_model, role)?;
+        }
+    }
+    Ok(())
+}
+
+/// Execute a compiled plan against the engine pool (used by root resolvers).
+pub(crate) async fn execute_plan(inner: &EngineInner, plan: &SqlPlan) -> Result<Value, String> {
+    execute::execute_sql(inner, plan).await
+}
+
+/// Public helper for tests: compile + naming surface.
+pub fn core_sdl_for_catalog(tables: &[TableSchema]) -> Result<String, String> {
+    // Dialect-independent / SQLite-default SDL (no PG JSON ops).
+    graphql_sdl_for_tables_with_options(tables, &SdlOptions::sqlite())
+}
diff --git a/src/graphql/execute.rs b/src/graphql/execute.rs
new file mode 100644
index 00000000..d0a25186
--- /dev/null
+++ b/src/graphql/execute.rs
@@ -0,0 +1,333 @@
+//! Dialect executors: run a SqlPlan and decode the single JSON column.
+#![allow(clippy::items_after_test_module)]
+
+use std::future::Future;
+use std::time::Duration;
+
+use async_graphql::Value;
+use serde_json::Value as JsonValue;
+
+use super::compile::{BindValue, ExtractedQueryEvidence, SqlDialect, SqlPlan};
+use super::engine::{EngineInner, GraphqlPool};
+
+pub async fn execute_sql(inner: &EngineInner, plan: &SqlPlan) -> Result<Value, String> {
+    match &inner.pool {
+        #[cfg(feature = "sqlite")]
+        GraphqlPool::Sqlite(pool) => execute_sqlite(pool, plan, inner.statement_timeout)
+            .await
+            .map(|executed| executed.value),
+        #[cfg(feature = "postgres")]
+        GraphqlPool::Postgres(pool) => execute_postgres(pool, plan, inner.statement_timeout)
+            .await
+            .map(|executed| executed.value),
+        #[allow(unreachable_patterns)]
+        _ => Err("no database pool available for GraphQL execution".into()),
+    }
+}
+
+pub(crate) struct ExecutedSql {
+    pub(crate) value: Value,
+    pub(crate) evidence: ExtractedQueryEvidence,
+}
+
+/// Wall-clock budget around a single statement future.
+///
+/// On elapse returns `Err("statement timeout")` — the stable string mapped to
+/// client `TIMEOUT` by [`super::schema::client_error_for_execute_err`].
+pub(crate) async fn apply_statement_timeout<T, F>(timeout: Duration, run: F) -> Result<T, String>
+where
+    F: Future<Output = Result<T, String>>,
+{
+    match tokio::time::timeout(timeout, run).await {
+        Ok(Ok(v)) => Ok(v),
+        Ok(Err(e)) => Err(e),
+        Err(_) => Err("statement timeout".into()),
+    }
+}
+
+/// Apply [`BindValue`]s to a sqlx query builder.
+///
+/// Shared by SQLite and Postgres executors so bind-order and type mapping stay
+/// in one place (dedup-3). Macro because sqlx `Query` is database-generic.
+macro_rules! apply_binds {
+    ($qb:expr, $binds:expr) => {{
+        let mut __qb = $qb;
+        for __bind in $binds {
+            __qb = match __bind {
+                BindValue::Null => __qb.bind(None::<String>),
+                BindValue::Bool(b) => __qb.bind(*b),
+                BindValue::I64(i) => __qb.bind(*i),
+                BindValue::F64(f) => __qb.bind(*f),
+                BindValue::Text(s) => __qb.bind(s.clone()),
+                BindValue::Bytes(b) => __qb.bind(b.clone()),
+                // No sqlx `json` feature — bind as text; compiler adds casts.
+                BindValue::Json(j) => __qb.bind(j.to_string()),
+            };
+        }
+        __qb
+    }};
+}
+
+#[cfg(feature = "sqlite")]
+async fn execute_sqlite(
+    pool: &sqlx::SqlitePool,
+    plan: &SqlPlan,
+    timeout: std::time::Duration,
+) -> Result<ExecutedSql, String> {
+    // SQL is compiler-produced from schema metadata + bound parameters only.
+    let text = apply_statement_timeout(timeout, fetch_sqlite_json(pool, plan)).await?;
+    decode_sqlite_value(text, plan)
+}
+
+/// Execute a compiled SQLite plan on a caller-owned read snapshot.
+#[cfg(feature = "sqlite")]
+pub(crate) async fn execute_sqlite_in_connection(
+    connection: &mut sqlx::SqliteConnection,
+    plan: &SqlPlan,
+) -> Result<ExecutedSql, String> {
+    let text = fetch_sqlite_json(&mut *connection, plan).await?;
+    decode_sqlite_value(text, plan)
+}
+
+#[cfg(feature = "sqlite")]
+async fn fetch_sqlite_json<'e, E>(executor: E, plan: &SqlPlan) -> Result<String, String>
+where
+    E: sqlx::Executor<'e, Database = sqlx::Sqlite>,
+{
+    use sqlx::Row;
+
+    let qb = apply_binds!(
+        sqlx::query(sqlx::AssertSqlSafe(plan.sql.clone())),
+        &plan.binds
+    );
+    // by_pk and filtered lookups may return zero rows → GraphQL null.
+    let row = qb
+        .fetch_optional(executor)
+        .await
+        .map_err(|e| format!("sqlite execute: {e}"))?;
+    match row {
+        Some(row) => row
+            .try_get::<Option<String>, _>(0)
+            .map_err(|e| format!("sqlite json column: {e}"))
+            .map(|value| value.unwrap_or_else(|| "null".into())),
+        None => Ok("null".into()),
+    }
+}
+
+#[cfg(feature = "sqlite")]
+fn decode_sqlite_value(text: String, plan: &SqlPlan) -> Result<ExecutedSql, String> {
+    let mut json: JsonValue =
+        serde_json::from_str(&text).map_err(|e| format!("json decode: {e}"))?;
+    deep_parse_json_strings(&mut json);
+    rewrite_hex_bytes(&mut json, &plan.bytes_hex_paths);
+    finish_executed_value(json, plan)
+}
+
+#[cfg(test)]
+mod statement_timeout_tests {
+    use super::apply_statement_timeout;
+    use std::time::Duration;
+
+    #[tokio::test(start_paused = true)]
+    async fn elapses_to_statement_timeout_error() {
+        let run = async {
+            tokio::time::sleep(Duration::from_secs(10)).await;
+            Ok::<String, String>("never".into())
+        };
+        let handle =
+            tokio::spawn(
+                async move { apply_statement_timeout(Duration::from_millis(1), run).await },
+            );
+        tokio::time::advance(Duration::from_millis(5)).await;
+        let err = handle.await.expect("join").expect_err("budget must elapse");
+        assert_eq!(err, "statement timeout");
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn completes_when_under_budget() {
+        let run = async { Ok::<String, String>("ok".into()) };
+        let handle =
+            tokio::spawn(async move { apply_statement_timeout(Duration::from_secs(5), run).await });
+        // Allow the ready future to be polled under paused time.
+        tokio::time::advance(Duration::from_millis(1)).await;
+        let v: String = handle.await.expect("join").expect("under budget");
+        assert_eq!(v, "ok");
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn propagates_inner_error() {
+        let run = async { Err::<String, String>("sqlite execute: boom".into()) };
+        let handle =
+            tokio::spawn(async move { apply_statement_timeout(Duration::from_secs(5), run).await });
+        tokio::time::advance(Duration::from_millis(1)).await;
+        let err = handle.await.expect("join").expect_err("inner err");
+        assert!(err.contains("boom"), "{err}");
+    }
+}
+
+/// Parse string-encoded JSON only for array elements (SQLite json_group_array
+/// quirk). Object property strings stay GraphQL String scalars (never re-typed).
+fn deep_parse_json_strings(value: &mut JsonValue) {
+    match value {
+        JsonValue::Array(items) => {
+            for item in items {
+                if let JsonValue::String(s) = item {
+                    let trimmed = s.trim();
+                    if (trimmed.starts_with('{') && trimmed.ends_with('}'))
+                        || (trimmed.starts_with('[') && trimmed.ends_with(']'))
+                    {
+                        if let Ok(mut parsed) = serde_json::from_str::<JsonValue>(s) {
+                            deep_parse_json_strings(&mut parsed);
+                            *item = parsed;
+                        }
+                    }
+                } else {
+                    deep_parse_json_strings(item);
+                }
+            }
+        }
+        JsonValue::Object(map) => {
+            for v in map.values_mut() {
+                match v {
+                    JsonValue::Object(_) | JsonValue::Array(_) => deep_parse_json_strings(v),
+                    // Leave scalar strings alone (including JSON-looking text columns).
+                    _ => {}
+                }
+            }
+        }
+        _ => {}
+    }
+}
+
+#[cfg(feature = "postgres")]
+async fn execute_postgres(
+    pool: &sqlx::PgPool,
+    plan: &SqlPlan,
+    timeout: std::time::Duration,
+) -> Result<ExecutedSql, String> {
+    let mut tx = pool
+        .begin()
+        .await
+        .map_err(|e| format!("postgres begin: {e}"))?;
+    let timeout_ms = timeout.as_millis() as i64;
+    sqlx::query(sqlx::AssertSqlSafe(format!(
+        "SET LOCAL statement_timeout = '{timeout_ms}ms'"
+    )))
+    .execute(&mut *tx)
+    .await
+    .map_err(|e| format!("statement_timeout: {e}"))?;
+
+    let value = fetch_postgres_value(&mut *tx, plan).await?;
+    tx.commit()
+        .await
+        .map_err(|e| format!("postgres commit: {e}"))?;
+
+    Ok(value)
+}
+
+/// Execute a compiled PostgreSQL plan on a caller-owned repeatable read
+/// snapshot. The caller configures `SET LOCAL statement_timeout` once for the
+/// complete physical-query/evidence transaction.
+#[cfg(feature = "postgres")]
+pub(crate) async fn execute_postgres_in_connection(
+    connection: &mut sqlx::PgConnection,
+    plan: &SqlPlan,
+) -> Result<ExecutedSql, String> {
+    fetch_postgres_value(&mut *connection, plan).await
+}
+
+#[cfg(feature = "postgres")]
+async fn fetch_postgres_value<'e, E>(executor: E, plan: &SqlPlan) -> Result<ExecutedSql, String>
+where
+    E: sqlx::Executor<'e, Database = sqlx::Postgres>,
+{
+    use sqlx::Row;
+    let qb = apply_binds!(
+        sqlx::query(sqlx::AssertSqlSafe(plan.sql.clone())),
+        &plan.binds
+    );
+    let row = qb
+        .fetch_optional(executor)
+        .await
+        .map_err(|e| format!("postgres execute: {e}"))?;
+
+    // Postgres returns `json`/`jsonb` which sqlx decodes as `Json<T>` when the
+    // `json` feature is on; some plans also cast to text. Accept both.
+    let json: JsonValue = match row {
+        Some(r) => {
+            if let Ok(j) = r.try_get::<sqlx::types::Json<JsonValue>, _>(0) {
+                j.0
+            } else if let Ok(s) = r.try_get::<String, _>(0) {
+                serde_json::from_str(&s).map_err(|e| format!("json decode: {e}"))?
+            } else if let Ok(Some(s)) = r.try_get::<Option<String>, _>(0) {
+                serde_json::from_str(&s).map_err(|e| format!("json decode: {e}"))?
+            } else if let Ok(None) = r.try_get::<Option<String>, _>(0) {
+                JsonValue::Null
+            } else {
+                return Err("postgres json column: unsupported type".into());
+            }
+        }
+        None => JsonValue::Null,
+    };
+    finish_executed_value(json, plan)
+}
+
+fn finish_executed_value(mut json: JsonValue, plan: &SqlPlan) -> Result<ExecutedSql, String> {
+    let evidence = plan.extract_evidence_and_strip(&mut json)?;
+    let value = Value::from_json(json).map_err(|e| format!("graphql value: {e}"))?;
+    Ok(ExecutedSql { value, evidence })
+}
+
+/// Rewrite hex-encoded Bytes paths to base64 (SQLite executor path).
+pub fn rewrite_hex_bytes(json: &mut JsonValue, paths: &[String]) {
+    for path in paths {
+        let parts: Vec<&str> = path.split('.').collect();
+        rewrite_path(json, &parts);
+    }
+}
+
+fn rewrite_path(json: &mut JsonValue, parts: &[&str]) {
+    if parts.is_empty() {
+        return;
+    }
+    match json {
+        JsonValue::Array(items) => {
+            for item in items {
+                rewrite_path(item, parts);
+            }
+        }
+        JsonValue::Object(map) => {
+            if parts.len() == 1 {
+                if let Some(JsonValue::String(hex)) = map.get_mut(parts[0]) {
+                    if let Some(b64) = hex_to_base64(hex) {
+                        *hex = b64;
+                    }
+                }
+            } else if let Some(child) = map.get_mut(parts[0]) {
+                rewrite_path(child, &parts[1..]);
+            }
+        }
+        _ => {}
+    }
+}
+
+fn hex_to_base64(hex: &str) -> Option<String> {
+    if !hex.len().is_multiple_of(2) {
+        return None;
+    }
+    let mut bytes = Vec::with_capacity(hex.len() / 2);
+    for i in (0..hex.len()).step_by(2) {
+        let byte = u8::from_str_radix(&hex[i..i + 2], 16).ok()?;
+        bytes.push(byte);
+    }
+    use base64::Engine as _;
+    Some(base64::engine::general_purpose::STANDARD.encode(bytes))
+}
+
+#[allow(dead_code)]
+pub fn dialect_name(d: SqlDialect) -> &'static str {
+    match d {
+        SqlDialect::Postgres => "postgres",
+        SqlDialect::Sqlite => "sqlite",
+    }
+}
diff --git a/src/graphql/filter.rs b/src/graphql/filter.rs
new file mode 100644
index 00000000..232055ae
--- /dev/null
+++ b/src/graphql/filter.rs
@@ -0,0 +1,806 @@
+//! Filter expression AST + column/claim/literal DSL for permission row filters
+//! and (via the compiler) client `where` arguments.
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value as JsonValue;
+
+use crate::table::ColumnType;
+
+/// Right-hand side of a comparison: literal, claim header, or nested operand.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", content = "value", rename_all = "snake_case")]
+pub enum Operand {
+    Lit(LitValue),
+    Claim(ClaimRef),
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", content = "value", rename_all = "snake_case")]
+pub enum LitValue {
+    String(String),
+    I64(i64),
+    F64(f64),
+    Bool(bool),
+    Json(JsonValue),
+    Null,
+}
+
+pub(crate) fn validate_row_policy_operand_literal(
+    column: &str,
+    column_type: &ColumnType,
+    op: Option<CmpOp>,
+    operand: &Operand,
+) -> Result<(), String> {
+    if let Some(op) = op {
+        let supported = match op {
+            CmpOp::Like | CmpOp::Ilike => matches!(column_type, ColumnType::Text),
+            CmpOp::Contains | CmpOp::ContainedIn | CmpOp::HasKey => {
+                matches!(column_type, ColumnType::Json)
+            }
+            CmpOp::Eq | CmpOp::Neq | CmpOp::Gt | CmpOp::Gte | CmpOp::Lt | CmpOp::Lte => true,
+        };
+        if !supported {
+            return Err(format!(
+                "row-policy operator `{op:?}` cannot target column `{column}` of type `{column_type:?}`"
+            ));
+        }
+    }
+    let Operand::Lit(literal) = operand else {
+        return Ok(());
+    };
+    if matches!(literal, LitValue::Null) {
+        return Ok(());
+    }
+    if let LitValue::F64(value) = literal {
+        if !value.is_finite() {
+            return Err(format!(
+                "row-policy floating-point literal `{value}` for column `{column}` must be finite"
+            ));
+        }
+    }
+    let compatible = match (column_type, literal) {
+        (ColumnType::Text | ColumnType::Timestamp, LitValue::String(_))
+        | (ColumnType::Boolean, LitValue::Bool(_))
+        | (ColumnType::Integer, LitValue::I64(_))
+        | (ColumnType::UnsignedInteger, LitValue::I64(0..))
+        | (ColumnType::Float, LitValue::F64(_) | LitValue::I64(_)) => true,
+        (ColumnType::Json, LitValue::String(_)) if matches!(op, Some(CmpOp::HasKey)) => true,
+        (ColumnType::Json, LitValue::Json(_)) if !matches!(op, Some(CmpOp::HasKey)) => true,
+        _ => false,
+    };
+    if compatible {
+        return Ok(());
+    }
+
+    let literal_kind = match literal {
+        LitValue::String(_) => "string",
+        LitValue::I64(_) => "i64",
+        LitValue::F64(_) => "f64",
+        LitValue::Bool(_) => "bool",
+        LitValue::Json(_) => "json",
+        LitValue::Null => "null",
+    };
+    let expected = match column_type {
+        ColumnType::Text | ColumnType::Timestamp => "a string literal",
+        ColumnType::Boolean => "a boolean literal",
+        ColumnType::Integer => "an i64 literal",
+        ColumnType::UnsignedInteger => "a non-negative i64 literal",
+        ColumnType::Float => "a finite f64 or i64 literal",
+        ColumnType::Json if matches!(op, Some(CmpOp::HasKey)) => "a string key literal",
+        ColumnType::Json => "an explicitly tagged JSON literal",
+        ColumnType::Bytes => "no non-null row-policy literal encoding is defined",
+        ColumnType::Unsupported(_) => "no row-policy literal encoding is supported",
+    };
+    Err(format!(
+        "row-policy literal kind `{literal_kind}` cannot target column `{column}` of type `{column_type:?}`; expected {expected}"
+    ))
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ClaimRef {
+    pub header: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ColRef {
+    pub name: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Deserialize)]
+#[serde(tag = "kind", content = "value", rename_all = "snake_case")]
+pub enum FilterExpr {
+    And(Vec<FilterExpr>),
+    Or(Vec<FilterExpr>),
+    Not(Box<FilterExpr>),
+    Cmp {
+        column: String,
+        op: CmpOp,
+        rhs: Operand,
+    },
+    In {
+        column: String,
+        values: Vec<Operand>,
+        negated: bool,
+    },
+    IsNull {
+        column: String,
+        is_null: bool,
+    },
+    Rel {
+        field: String,
+        predicate: Box<FilterExpr>,
+    },
+}
+
+// A handwritten serializer keeps the recursive AST out of serde's nested
+// generic ContentSerializer expansion (which otherwise overflows rustc's trait
+// solver when the AST is embedded in the versioned client manifest).
+impl Serialize for FilterExpr {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        use serde_json::{json, Value};
+        fn value(expression: &FilterExpr) -> Value {
+            match expression {
+                FilterExpr::And(items) => {
+                    json!({ "kind": "and", "value": items.iter().map(value).collect::<Vec<_>>() })
+                }
+                FilterExpr::Or(items) => {
+                    json!({ "kind": "or", "value": items.iter().map(value).collect::<Vec<_>>() })
+                }
+                FilterExpr::Not(item) => json!({ "kind": "not", "value": value(item) }),
+                FilterExpr::Cmp { column, op, rhs } => json!({
+                    "kind": "cmp",
+                    "value": { "column": column, "op": op, "rhs": rhs }
+                }),
+                FilterExpr::In {
+                    column,
+                    values,
+                    negated,
+                } => json!({
+                    "kind": "in",
+                    "value": { "column": column, "values": values, "negated": negated }
+                }),
+                FilterExpr::IsNull { column, is_null } => json!({
+                    "kind": "is_null",
+                    "value": { "column": column, "is_null": is_null }
+                }),
+                FilterExpr::Rel { field, predicate } => json!({
+                    "kind": "rel",
+                    "value": { "field": field, "predicate": value(predicate) }
+                }),
+            }
+        }
+        canonical_json_value(value(self)).serialize(serializer)
+    }
+}
+
+fn canonical_json_value(value: JsonValue) -> JsonValue {
+    match value {
+        JsonValue::Array(values) => {
+            JsonValue::Array(values.into_iter().map(canonical_json_value).collect())
+        }
+        JsonValue::Object(values) => {
+            let mut entries = values.into_iter().collect::<Vec<_>>();
+            entries.sort_by(|left, right| left.0.cmp(&right.0));
+            JsonValue::Object(
+                entries
+                    .into_iter()
+                    .map(|(key, value)| (key, canonical_json_value(value)))
+                    .collect(),
+            )
+        }
+        scalar => scalar,
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CmpOp {
+    Eq,
+    Neq,
+    Gt,
+    Gte,
+    Lt,
+    Lte,
+    Like,
+    Ilike,
+    Contains,
+    ContainedIn,
+    HasKey,
+}
+
+pub fn col(name: &str) -> ColRef {
+    ColRef {
+        name: name.to_string(),
+    }
+}
+
+pub fn claim(header: &str) -> ClaimRef {
+    ClaimRef {
+        header: header.to_string(),
+    }
+}
+
+pub fn lit(v: impl Into<LitValue>) -> LitValue {
+    v.into()
+}
+
+pub fn rel(field: &str, f: FilterExpr) -> FilterExpr {
+    FilterExpr::Rel {
+        field: field.to_string(),
+        predicate: Box::new(f),
+    }
+}
+
+impl From<&str> for LitValue {
+    fn from(s: &str) -> Self {
+        LitValue::String(s.to_string())
+    }
+}
+impl From<String> for LitValue {
+    fn from(s: String) -> Self {
+        LitValue::String(s)
+    }
+}
+impl From<i64> for LitValue {
+    fn from(v: i64) -> Self {
+        LitValue::I64(v)
+    }
+}
+impl From<i32> for LitValue {
+    fn from(v: i32) -> Self {
+        LitValue::I64(v as i64)
+    }
+}
+impl From<f64> for LitValue {
+    fn from(v: f64) -> Self {
+        LitValue::F64(v)
+    }
+}
+impl From<bool> for LitValue {
+    fn from(v: bool) -> Self {
+        LitValue::Bool(v)
+    }
+}
+impl From<JsonValue> for LitValue {
+    fn from(v: JsonValue) -> Self {
+        LitValue::Json(v)
+    }
+}
+
+impl From<LitValue> for Operand {
+    fn from(v: LitValue) -> Self {
+        Operand::Lit(v)
+    }
+}
+impl From<ClaimRef> for Operand {
+    fn from(c: ClaimRef) -> Self {
+        Operand::Claim(c)
+    }
+}
+impl From<&str> for Operand {
+    fn from(s: &str) -> Self {
+        Operand::Lit(LitValue::from(s))
+    }
+}
+impl From<String> for Operand {
+    fn from(s: String) -> Self {
+        Operand::Lit(LitValue::from(s))
+    }
+}
+impl From<i64> for Operand {
+    fn from(v: i64) -> Self {
+        Operand::Lit(LitValue::from(v))
+    }
+}
+impl From<f64> for Operand {
+    fn from(v: f64) -> Self {
+        Operand::Lit(LitValue::from(v))
+    }
+}
+impl From<f32> for Operand {
+    fn from(v: f32) -> Self {
+        Operand::Lit(LitValue::from(v as f64))
+    }
+}
+impl From<bool> for Operand {
+    fn from(v: bool) -> Self {
+        Operand::Lit(LitValue::from(v))
+    }
+}
+
+impl ColRef {
+    pub fn eq(self, rhs: impl Into<Operand>) -> FilterExpr {
+        FilterExpr::Cmp {
+            column: self.name,
+            op: CmpOp::Eq,
+            rhs: rhs.into(),
+        }
+    }
+    pub fn neq(self, rhs: impl Into<Operand>) -> FilterExpr {
+        FilterExpr::Cmp {
+            column: self.name,
+            op: CmpOp::Neq,
+            rhs: rhs.into(),
+        }
+    }
+    pub fn gt(self, rhs: impl Into<Operand>) -> FilterExpr {
+        FilterExpr::Cmp {
+            column: self.name,
+            op: CmpOp::Gt,
+            rhs: rhs.into(),
+        }
+    }
+    pub fn gte(self, rhs: impl Into<Operand>) -> FilterExpr {
+        FilterExpr::Cmp {
+            column: self.name,
+            op: CmpOp::Gte,
+            rhs: rhs.into(),
+        }
+    }
+    pub fn lt(self, rhs: impl Into<Operand>) -> FilterExpr {
+        FilterExpr::Cmp {
+            column: self.name,
+            op: CmpOp::Lt,
+            rhs: rhs.into(),
+        }
+    }
+    pub fn lte(self, rhs: impl Into<Operand>) -> FilterExpr {
+        FilterExpr::Cmp {
+            column: self.name,
+            op: CmpOp::Lte,
+            rhs: rhs.into(),
+        }
+    }
+    pub fn like(self, rhs: impl Into<Operand>) -> FilterExpr {
+        FilterExpr::Cmp {
+            column: self.name,
+            op: CmpOp::Like,
+            rhs: rhs.into(),
+        }
+    }
+    pub fn ilike(self, rhs: impl Into<Operand>) -> FilterExpr {
+        FilterExpr::Cmp {
+            column: self.name,
+            op: CmpOp::Ilike,
+            rhs: rhs.into(),
+        }
+    }
+    pub fn is_null(self, yes: bool) -> FilterExpr {
+        FilterExpr::IsNull {
+            column: self.name,
+            is_null: yes,
+        }
+    }
+    pub fn is_in(self, values: impl IntoIterator<Item = impl Into<Operand>>) -> FilterExpr {
+        FilterExpr::In {
+            column: self.name,
+            values: values.into_iter().map(Into::into).collect(),
+            negated: false,
+        }
+    }
+    pub fn not_in(self, values: impl IntoIterator<Item = impl Into<Operand>>) -> FilterExpr {
+        FilterExpr::In {
+            column: self.name,
+            values: values.into_iter().map(Into::into).collect(),
+            negated: true,
+        }
+    }
+}
+
+impl FilterExpr {
+    /// Validate row-policy literals before they reach either SQL execution or
+    /// a serialized client Surface. JSON cannot represent NaN or infinities;
+    /// accepting them would let distinct runtime policies collapse to the same
+    /// manifest/fingerprint.
+    pub fn validate_row_policy_literals(&self) -> Result<(), String> {
+        fn validate_operand(operand: &Operand) -> Result<(), String> {
+            if let Operand::Lit(LitValue::F64(value)) = operand {
+                if !value.is_finite() {
+                    return Err(format!(
+                        "row-policy floating-point literal `{value}` must be finite"
+                    ));
+                }
+            }
+            Ok(())
+        }
+
+        match self {
+            FilterExpr::And(expressions) | FilterExpr::Or(expressions) => {
+                for expression in expressions {
+                    expression.validate_row_policy_literals()?;
+                }
+            }
+            FilterExpr::Not(expression)
+            | FilterExpr::Rel {
+                predicate: expression,
+                ..
+            } => {
+                expression.validate_row_policy_literals()?;
+            }
+            FilterExpr::Cmp { rhs, .. } => validate_operand(rhs)?,
+            FilterExpr::In { values, .. } => {
+                for value in values {
+                    validate_operand(value)?;
+                }
+            }
+            FilterExpr::IsNull { .. } => {}
+        }
+        Ok(())
+    }
+
+    /// Whether this predicate can be evaluated by a JavaScript client without
+    /// changing integer identity/ordering semantics.
+    ///
+    /// Runtime SQL can safely retain all i64 values. Values outside the JS
+    /// safe-integer interval are therefore kept server-only in client
+    /// manifests until the wire protocol provides canonical decimal strings.
+    pub fn is_client_portable(&self) -> bool {
+        const JS_MAX_SAFE_INTEGER: i64 = 9_007_199_254_740_991;
+
+        fn json_is_portable(value: &JsonValue) -> bool {
+            match value {
+                JsonValue::Null | JsonValue::Bool(_) | JsonValue::String(_) => true,
+                JsonValue::Number(number) => {
+                    if let Some(value) = number.as_i64() {
+                        value.unsigned_abs() <= JS_MAX_SAFE_INTEGER as u64
+                    } else if let Some(value) = number.as_u64() {
+                        value <= JS_MAX_SAFE_INTEGER as u64
+                    } else {
+                        // serde_json accepts only finite JSON floats. Requiring a
+                        // representable f64 also fails closed if a future number
+                        // backend retains a value outside the JavaScript wire.
+                        number.as_f64().is_some_and(f64::is_finite)
+                    }
+                }
+                JsonValue::Array(values) => values.iter().all(json_is_portable),
+                JsonValue::Object(values) => values.values().all(json_is_portable),
+            }
+        }
+
+        fn operand_is_portable(operand: &Operand) -> bool {
+            match operand {
+                // Claim values are locally usable only after the selected
+                // Surface binds their exact typed descriptor/value inventory to
+                // the server-issued cache scope. Field visibility and codec
+                // compatibility are validated while that inventory is derived.
+                Operand::Claim(_) => true,
+                Operand::Lit(LitValue::I64(value)) => {
+                    value.unsigned_abs() <= JS_MAX_SAFE_INTEGER as u64
+                }
+                Operand::Lit(LitValue::Json(value)) => json_is_portable(value),
+                _ => true,
+            }
+        }
+
+        match self {
+            FilterExpr::And(expressions) | FilterExpr::Or(expressions) => {
+                expressions.iter().all(FilterExpr::is_client_portable)
+            }
+            FilterExpr::Not(expression)
+            | FilterExpr::Rel {
+                predicate: expression,
+                ..
+            } => expression.is_client_portable(),
+            FilterExpr::Cmp { rhs, .. } => operand_is_portable(rhs),
+            FilterExpr::In { values, .. } => values.iter().all(operand_is_portable),
+            FilterExpr::IsNull { .. } => true,
+        }
+    }
+
+    pub fn and(self, other: FilterExpr) -> FilterExpr {
+        match self {
+            FilterExpr::And(mut xs) => {
+                xs.push(other);
+                FilterExpr::And(xs)
+            }
+            other_self => FilterExpr::And(vec![other_self, other]),
+        }
+    }
+    pub fn or(self, other: FilterExpr) -> FilterExpr {
+        match self {
+            FilterExpr::Or(mut xs) => {
+                xs.push(other);
+                FilterExpr::Or(xs)
+            }
+            other_self => FilterExpr::Or(vec![other_self, other]),
+        }
+    }
+    #[allow(clippy::should_implement_trait)]
+    pub fn not(self) -> FilterExpr {
+        FilterExpr::Not(Box::new(self))
+    }
+
+    /// Walk columns / claims / rel fields for builder validation.
+    pub fn visit_columns(&self, mut f: impl FnMut(&str)) {
+        self.visit_columns_inner(&mut f);
+    }
+    fn visit_columns_inner(&self, f: &mut impl FnMut(&str)) {
+        match self {
+            FilterExpr::And(xs) | FilterExpr::Or(xs) => {
+                for x in xs {
+                    x.visit_columns_inner(f);
+                }
+            }
+            FilterExpr::Not(x) => x.visit_columns_inner(f),
+            FilterExpr::Cmp { column, .. }
+            | FilterExpr::In { column, .. }
+            | FilterExpr::IsNull { column, .. } => f(column),
+            FilterExpr::Rel { predicate, .. } => predicate.visit_columns_inner(f),
+        }
+    }
+
+    pub fn visit_claims(&self, mut f: impl FnMut(&str)) {
+        self.visit_claims_inner(&mut f);
+    }
+    fn visit_claims_inner(&self, f: &mut impl FnMut(&str)) {
+        match self {
+            FilterExpr::And(xs) | FilterExpr::Or(xs) => {
+                for x in xs {
+                    x.visit_claims_inner(f);
+                }
+            }
+            FilterExpr::Not(x) => x.visit_claims_inner(f),
+            FilterExpr::Cmp { rhs, .. } => {
+                if let Operand::Claim(c) = rhs {
+                    f(&c.header);
+                }
+            }
+            FilterExpr::In { values, .. } => {
+                for v in values {
+                    if let Operand::Claim(c) = v {
+                        f(&c.header);
+                    }
+                }
+            }
+            FilterExpr::IsNull { .. } => {}
+            FilterExpr::Rel { predicate, .. } => predicate.visit_claims_inner(f),
+        }
+    }
+
+    pub fn visit_rels(&self, mut f: impl FnMut(&str, &FilterExpr)) {
+        self.visit_rels_inner(&mut f);
+    }
+    fn visit_rels_inner(&self, f: &mut impl FnMut(&str, &FilterExpr)) {
+        match self {
+            FilterExpr::And(xs) | FilterExpr::Or(xs) => {
+                for x in xs {
+                    x.visit_rels_inner(f);
+                }
+            }
+            FilterExpr::Not(x) => x.visit_rels_inner(f),
+            FilterExpr::Rel { field, predicate } => {
+                f(field, predicate);
+                predicate.visit_rels_inner(f);
+            }
+            _ => {}
+        }
+    }
+}
+
+impl std::ops::Not for FilterExpr {
+    type Output = FilterExpr;
+
+    fn not(self) -> Self::Output {
+        FilterExpr::Not(Box::new(self))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        claim, col, validate_row_policy_operand_literal, CmpOp, FilterExpr, LitValue, Operand,
+    };
+    use crate::table::ColumnType;
+
+    #[test]
+    fn comparison_operands_accept_float_literals() {
+        let expr = col("price").gt(9.99);
+        let FilterExpr::Cmp {
+            rhs: Operand::Lit(LitValue::F64(value)),
+            ..
+        } = expr
+        else {
+            panic!("expected f64 literal operand");
+        };
+        assert!((value - 9.99).abs() < f64::EPSILON);
+
+        let expr = col("ratio").lt(0.5_f32);
+        let FilterExpr::Cmp {
+            rhs: Operand::Lit(LitValue::F64(value)),
+            ..
+        } = expr
+        else {
+            panic!("expected f32 literal operand to promote to f64");
+        };
+        assert!((value - 0.5).abs() < f64::EPSILON);
+    }
+
+    #[test]
+    fn row_policy_wire_json_is_canonical_across_map_backends() {
+        let mut value = serde_json::Map::new();
+        value.insert("z".into(), serde_json::json!(2));
+        value.insert("a".into(), serde_json::json!(1));
+        let expression = FilterExpr::In {
+            column: "metadata".into(),
+            values: vec![Operand::Lit(LitValue::Json(serde_json::Value::Object(
+                value,
+            )))],
+            negated: false,
+        };
+
+        assert_eq!(
+            serde_json::to_string(&expression).unwrap(),
+            r#"{"kind":"in","value":{"column":"metadata","negated":false,"values":[{"kind":"lit","value":{"kind":"json","value":{"a":1,"z":2}}}]}}"#
+        );
+    }
+
+    #[test]
+    fn row_policy_rejects_non_finite_floats_recursively_in_cmp_and_in() {
+        for value in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
+            let cmp = FilterExpr::Not(Box::new(FilterExpr::And(vec![col("price").gt(value)])));
+            assert!(cmp
+                .validate_row_policy_literals()
+                .unwrap_err()
+                .contains("must be finite"));
+
+            let in_list = FilterExpr::Or(vec![FilterExpr::In {
+                column: "price".into(),
+                values: vec![Operand::from(1.0), Operand::from(value)],
+                negated: false,
+            }]);
+            assert!(in_list
+                .validate_row_policy_literals()
+                .unwrap_err()
+                .contains("must be finite"));
+        }
+    }
+
+    #[test]
+    fn row_policy_literal_kinds_must_match_the_authoritative_column_type() {
+        let valid = [
+            (ColumnType::Text, LitValue::String("text".into())),
+            (
+                ColumnType::Timestamp,
+                LitValue::String("2026-01-01T00:00:00Z".into()),
+            ),
+            (ColumnType::Boolean, LitValue::Bool(true)),
+            (ColumnType::Integer, LitValue::I64(-1)),
+            (ColumnType::UnsignedInteger, LitValue::I64(1)),
+            (ColumnType::Float, LitValue::F64(1.5)),
+            (
+                ColumnType::Json,
+                LitValue::Json(serde_json::json!({"nested": true})),
+            ),
+            (ColumnType::Float, LitValue::I64(1)),
+        ];
+        for (column_type, literal) in valid {
+            validate_row_policy_operand_literal(
+                "value",
+                &column_type,
+                Some(CmpOp::Eq),
+                &Operand::Lit(literal),
+            )
+            .unwrap();
+            validate_row_policy_operand_literal(
+                "value",
+                &column_type,
+                Some(CmpOp::Eq),
+                &Operand::Lit(LitValue::Null),
+            )
+            .unwrap();
+        }
+
+        for (column_type, literal, expected) in [
+            (
+                ColumnType::Text,
+                LitValue::Json(serde_json::json!("text")),
+                "literal kind `json`",
+            ),
+            (
+                ColumnType::Json,
+                LitValue::String("text".into()),
+                "explicitly tagged JSON",
+            ),
+            (
+                ColumnType::UnsignedInteger,
+                LitValue::I64(-1),
+                "non-negative i64",
+            ),
+            (ColumnType::Boolean, LitValue::I64(1), "boolean literal"),
+            (
+                ColumnType::Bytes,
+                LitValue::String("YQ==".into()),
+                "no non-null",
+            ),
+            (
+                ColumnType::Unsupported("custom".into()),
+                LitValue::String("value".into()),
+                "no row-policy literal encoding",
+            ),
+        ] {
+            let error = validate_row_policy_operand_literal(
+                "value",
+                &column_type,
+                Some(CmpOp::Eq),
+                &Operand::Lit(literal),
+            )
+            .unwrap_err();
+            assert!(error.contains("column `value`"), "{error}");
+            assert!(error.contains(expected), "{error}");
+        }
+
+        validate_row_policy_operand_literal(
+            "metadata",
+            &ColumnType::Json,
+            Some(CmpOp::HasKey),
+            &Operand::Lit(LitValue::String("tenant".into())),
+        )
+        .unwrap();
+        let has_key_error = validate_row_policy_operand_literal(
+            "metadata",
+            &ColumnType::Json,
+            Some(CmpOp::HasKey),
+            &Operand::Lit(LitValue::Json(serde_json::json!("tenant"))),
+        )
+        .unwrap_err();
+        assert!(
+            has_key_error.contains("string key literal"),
+            "{has_key_error}"
+        );
+
+        for (column_type, op) in [
+            (ColumnType::Text, CmpOp::HasKey),
+            (ColumnType::Boolean, CmpOp::Like),
+            (ColumnType::Json, CmpOp::Ilike),
+        ] {
+            let error = validate_row_policy_operand_literal(
+                "value",
+                &column_type,
+                Some(op),
+                &Operand::Lit(LitValue::String("value".into())),
+            )
+            .unwrap_err();
+            assert!(error.contains("operator"), "{error}");
+            assert!(error.contains("column `value`"), "{error}");
+        }
+    }
+
+    #[test]
+    fn finite_floats_pass_and_js_unsafe_i64_is_not_client_portable() {
+        let finite = col("price")
+            .gte(-123.5)
+            .and(col("price").is_in([0.0, f64::MAX]));
+        finite.validate_row_policy_literals().unwrap();
+        assert!(finite.is_client_portable());
+
+        assert!(col("id").eq(9_007_199_254_740_991_i64).is_client_portable());
+        assert!(!col("id").eq(9_007_199_254_740_992_i64).is_client_portable());
+        assert!(!col("id").eq(i64::MIN).is_client_portable());
+
+        let safe_json = FilterExpr::Cmp {
+            column: "metadata".into(),
+            op: CmpOp::Contains,
+            rhs: Operand::Lit(LitValue::Json(serde_json::json!({
+                "nested": [9_007_199_254_740_991_u64, -9_007_199_254_740_991_i64]
+            }))),
+        };
+        assert!(safe_json.is_client_portable());
+
+        let unsafe_json = FilterExpr::Cmp {
+            column: "metadata".into(),
+            op: CmpOp::Contains,
+            rhs: Operand::Lit(LitValue::Json(serde_json::json!({
+                "nested": [9_007_199_254_740_992_u64]
+            }))),
+        };
+        assert!(!unsafe_json.is_client_portable());
+
+        assert!(
+            col("owner_id").eq(claim("x-user-id")).is_client_portable(),
+            "typed claim operands are portable once the selected surface binds their values"
+        );
+    }
+}
diff --git a/src/graphql/http.rs b/src/graphql/http.rs
new file mode 100644
index 00000000..2d27703a
--- /dev/null
+++ b/src/graphql/http.rs
@@ -0,0 +1,725 @@
+//! Axum GraphQL router (POST /graphql, optional GraphiQL + websocket upgrade).
+
+use std::sync::Arc;
+
+use async_graphql::http::{GraphiQLSource, ALL_WEBSOCKET_PROTOCOLS};
+use async_graphql::parser::types::OperationType;
+use async_graphql::{Data, Executor, Request, Response as GqlResponse, ServerError};
+use async_graphql_axum::{GraphQLProtocol, GraphQLRequest, GraphQLResponse, GraphQLWebSocket};
+use axum::extract::ws::WebSocketUpgrade;
+use axum::extract::{DefaultBodyLimit, State};
+use axum::http::{HeaderMap, StatusCode};
+use axum::response::{Html, IntoResponse, Response};
+use axum::routing::post;
+use axum::Router;
+use futures_util::stream::BoxStream;
+
+use crate::microsvc::{Service, Session, MAX_HTTP_BODY_BYTES, ROLE_KEY, USER_ID_KEY};
+
+use super::engine::GraphqlEngine;
+use super::identity::{
+    resolve_identity_with_validator, AuthError, IdentityMode, ResolvedIdentity, VerifiedPrincipal,
+};
+
+/// DevHeaders baked into GraphiQL for local exploration (not production security).
+const GRAPHIQL_DEV_USER: &str = "demo";
+const GRAPHIQL_DEV_ROLE: &str = "user";
+
+/// HTML for the GraphiQL IDE served on `GET /graphql` when GraphiQL is enabled.
+///
+/// Default identity headers (`x-role: user`, `x-user-id: demo`) are injected
+/// only for local exploration. Production scaffolds use `OidcBearer` (D6) —
+/// these headers are **not** a security mechanism. GraphiQL is off under
+/// production env policy (`graphiql_enabled_from_env`).
+///
+/// **Subscriptions:** GraphiQL runs them over WebSocket at `/graphql/ws`.
+/// Browsers cannot set custom WS headers; identity is supplied via
+/// `wsConnectionParams` → `connection_init` (and DevHeaders defaults if empty).
+///
+/// Note: do **not** put `?x-user-id=` query params in `subscription_endpoint` —
+/// GraphiQLSource HTML-escapes `=` / `&` (`&#x3D;`, `&amp;`), which breaks the URL.
+pub fn graphiql_page() -> Html<String> {
+    Html(
+        GraphiQLSource::build()
+            .endpoint("/graphql")
+            .subscription_endpoint("/graphql/ws")
+            .header(ROLE_KEY, GRAPHIQL_DEV_ROLE)
+            .header(USER_ID_KEY, GRAPHIQL_DEV_USER)
+            // Sent as connection_init payload for graphql-transport-ws.
+            .ws_connection_param(USER_ID_KEY, GRAPHIQL_DEV_USER)
+            .ws_connection_param(ROLE_KEY, GRAPHIQL_DEV_ROLE)
+            .title("Distributed GraphQL")
+            .finish(),
+    )
+}
+
+/// [`Executor`] for WebSocket subscriptions.
+///
+/// Prefers a [`Session`] injected via `connection_init` / `session_data` (GraphiQL
+/// wsConnectionParams), then falls back to the session from the HTTP upgrade.
+#[derive(Clone)]
+pub struct GraphqlSessionExecutor {
+    engine: Arc<GraphqlEngine>,
+    session: Session,
+    principal: Option<VerifiedPrincipal>,
+    service: Option<Arc<Service>>,
+}
+
+impl GraphqlSessionExecutor {
+    pub fn new(engine: Arc<GraphqlEngine>, session: Session) -> Self {
+        Self {
+            engine,
+            session,
+            principal: None,
+            service: None,
+        }
+    }
+
+    fn with_identity(
+        engine: Arc<GraphqlEngine>,
+        session: Session,
+        principal: Option<VerifiedPrincipal>,
+        service: Option<Arc<Service>>,
+    ) -> Self {
+        Self {
+            engine,
+            session,
+            principal,
+            service,
+        }
+    }
+}
+
+impl Executor for GraphqlSessionExecutor {
+    async fn execute(&self, request: Request) -> GqlResponse {
+        // Subscriptions must not go through execute() — that yields
+        // "Subscription root not found". GraphiQL should use the WS path only.
+        self.engine
+            .execute(
+                &self.session,
+                request_with_context(
+                    request,
+                    self.principal.clone(),
+                    self.service.as_ref().map(Arc::clone),
+                ),
+            )
+            .await
+    }
+
+    fn execute_stream(
+        &self,
+        request: Request,
+        session_data: Option<Arc<Data>>,
+    ) -> BoxStream<'static, GqlResponse> {
+        use std::any::TypeId;
+        let session = session_data
+            .as_ref()
+            .and_then(|d| d.get(&TypeId::of::<Session>()))
+            .and_then(|b| b.downcast_ref::<Session>())
+            .cloned()
+            .unwrap_or_else(|| self.session.clone());
+        let principal = session_data
+            .as_ref()
+            .and_then(|data| data.get(&TypeId::of::<VerifiedPrincipal>()))
+            .and_then(|principal| principal.downcast_ref::<VerifiedPrincipal>())
+            .cloned()
+            .or_else(|| self.principal.clone());
+        let operation_type = match websocket_operation_type(&request) {
+            Ok(operation_type) => operation_type,
+            Err(message) => {
+                return Box::pin(futures_util::stream::once(async move {
+                    GqlResponse::from_errors(vec![ServerError::new(message, None)])
+                }));
+            }
+        };
+        let service = self.service.as_ref().map(Arc::clone);
+        if operation_type == OperationType::Subscription {
+            return self
+                .engine
+                .execute_stream(&session, request_with_context(request, principal, service));
+        }
+
+        let engine = Arc::clone(&self.engine);
+        Box::pin(futures_util::stream::once(async move {
+            engine
+                .execute(&session, request_with_context(request, principal, service))
+                .await
+        }))
+    }
+}
+
+fn websocket_operation_type(request: &Request) -> Result<OperationType, &'static str> {
+    let document = async_graphql::parser::parse_query(&request.query)
+        .map_err(|_| "invalid GraphQL document")?;
+    let mut operations = document.operations.iter();
+    if let Some(requested_name) = request.operation_name.as_deref() {
+        return operations
+            .find(|(name, _)| name.map(|name| name.as_str()) == Some(requested_name))
+            .map(|(_, operation)| operation.node.ty)
+            .ok_or("GraphQL operation name was not found");
+    }
+
+    let (_, operation) = operations
+        .next()
+        .ok_or("GraphQL document contains no operation")?;
+    if operations.next().is_some() {
+        return Err("GraphQL operation name is required for multi-operation documents");
+    }
+    Ok(operation.node.ty)
+}
+
+fn request_with_principal(request: Request, principal: Option<VerifiedPrincipal>) -> Request {
+    match principal {
+        Some(principal) => request.data(principal),
+        None => request,
+    }
+}
+
+fn request_with_context(
+    request: Request,
+    principal: Option<VerifiedPrincipal>,
+    service: Option<Arc<Service>>,
+) -> Request {
+    let request = request_with_principal(request, principal);
+    match service {
+        Some(service) => request.data(service),
+        None => request,
+    }
+}
+
+/// Standalone GraphQL router with its own body limit.
+pub fn graphql_router(engine: Arc<GraphqlEngine>) -> Router {
+    let graphiql = engine.graphiql_enabled();
+    let mut router = Router::new().route(
+        "/graphql",
+        post(graphql_handler).get(move || async move {
+            if graphiql {
+                graphiql_page().into_response()
+            } else {
+                axum::http::StatusCode::METHOD_NOT_ALLOWED.into_response()
+            }
+        }),
+    );
+    router = router.layer(DefaultBodyLimit::max(MAX_HTTP_BODY_BYTES));
+    router.with_state(engine)
+}
+
+/// GraphQL router that can dispatch command mutations through a [`Service`].
+pub fn graphql_router_with_service(engine: Arc<GraphqlEngine>, service: Arc<Service>) -> Router {
+    service
+        .validate_graphql_engine(&engine)
+        .unwrap_or_else(|error| panic!("cannot serve GraphQL with this service: {error}"));
+
+    let graphiql = engine.graphiql_enabled();
+    let state = GraphqlHttpState {
+        engine,
+        service: Some(service),
+    };
+    let mut router = Router::new().route(
+        "/graphql",
+        post(graphql_handler_with_service).get(move || async move {
+            if graphiql {
+                graphiql_page().into_response()
+            } else {
+                axum::http::StatusCode::METHOD_NOT_ALLOWED.into_response()
+            }
+        }),
+    );
+    router = router.layer(DefaultBodyLimit::max(MAX_HTTP_BODY_BYTES));
+    router.with_state(state)
+}
+
+#[derive(Clone)]
+struct GraphqlHttpState {
+    engine: Arc<GraphqlEngine>,
+    service: Option<Arc<Service>>,
+}
+
+fn unauthorized_response() -> Response {
+    (
+        axum::http::StatusCode::UNAUTHORIZED,
+        [("content-type", "application/json")],
+        r#"{"errors":[{"message":"unauthorized","extensions":{"code":"UNAUTHENTICATED"}}]}"#,
+    )
+        .into_response()
+}
+
+async fn graphql_handler(
+    State(engine): State<Arc<GraphqlEngine>>,
+    headers: axum::http::HeaderMap,
+    req: GraphQLRequest,
+) -> Response {
+    let identity = match resolve_identity_with_validator(
+        &headers,
+        engine.identity_config(),
+        engine.identity_validator(),
+    )
+    .await
+    {
+        Ok(identity) => identity,
+        Err(AuthError::Unauthorized) => return unauthorized_response(),
+    };
+    let (session, principal) = identity.into_parts();
+    // GraphiQL demo headers only apply under DevHeaders; other modes ignore them for AuthZ.
+    let _ = engine.identity_config().mode == IdentityMode::DevHeaders;
+    let request = request_with_principal(req.into_inner(), principal);
+    let response = engine.execute(&session, request).await;
+    GraphQLResponse::from(response).into_response()
+}
+
+async fn graphql_handler_with_service(
+    State(state): State<GraphqlHttpState>,
+    headers: axum::http::HeaderMap,
+    req: GraphQLRequest,
+) -> Response {
+    let identity = match resolve_identity_with_validator(
+        &headers,
+        state.engine.identity_config(),
+        state.engine.identity_validator(),
+    )
+    .await
+    {
+        Ok(identity) => identity,
+        Err(AuthError::Unauthorized) => return unauthorized_response(),
+    };
+    let (session, principal) = identity.into_parts();
+    let mut request = request_with_principal(req.into_inner(), principal);
+    if let Some(service) = &state.service {
+        request = request.data(Arc::clone(service));
+    }
+    let response = state.engine.execute(&session, request).await;
+    GraphQLResponse::from(response).into_response()
+}
+
+/// Handler used when GraphQL is mounted on the microsvc router.
+pub async fn microsvc_graphql_handler(
+    State(service): State<Arc<Service>>,
+    headers: axum::http::HeaderMap,
+    req: GraphQLRequest,
+) -> Response {
+    let engine = service
+        .graphql_engine()
+        .expect("graphql route mounted without engine");
+    let identity = match resolve_identity_with_validator(
+        &headers,
+        engine.identity_config(),
+        engine.identity_validator(),
+    )
+    .await
+    {
+        Ok(identity) => identity,
+        Err(AuthError::Unauthorized) => return unauthorized_response(),
+    };
+    let (session, principal) = identity.into_parts();
+    let request = request_with_principal(req.into_inner(), principal).data(Arc::clone(&service));
+    let response = engine.execute(&session, request).await;
+    GraphQLResponse::from(response).into_response()
+}
+
+/// `GET /graphql` — GraphiQL HTML when not a WebSocket upgrade.
+pub async fn microsvc_graphql_get(State(service): State<Arc<Service>>) -> Response {
+    let graphiql = service
+        .graphql_engine()
+        .map(|e| e.graphiql_enabled())
+        .unwrap_or(false);
+    if graphiql {
+        graphiql_page().into_response()
+    } else {
+        StatusCode::METHOD_NOT_ALLOWED.into_response()
+    }
+}
+
+/// WebSocket upgrade for GraphQL subscriptions (`graphql-ws` / `graphql-transport-ws`).
+///
+/// **Auth best practice (OIDC):** browsers cannot set `Authorization` on the WS
+/// upgrade. Accept the upgrade, then require a Bearer access token in
+/// `connection_init` (payload `authorization` / `accessToken` / nested
+/// `headers.Authorization`). Validate with the same OidcBearer path as HTTP.
+///
+/// **DevHeaders (local):** identity from upgrade headers, query params, or
+/// GraphiQL `wsConnectionParams` (`x-user-id` / `x-role`). Empty clients remain
+/// anonymous; the GraphiQL page sends its demo identity explicitly.
+pub async fn microsvc_graphql_ws(
+    State(service): State<Arc<Service>>,
+    headers: HeaderMap,
+    uri: axum::http::Uri,
+    protocol: GraphQLProtocol,
+    upgrade: WebSocketUpgrade,
+) -> Response {
+    let engine = match service.graphql_engine() {
+        Some(e) => e,
+        None => return StatusCode::NOT_FOUND.into_response(),
+    };
+
+    let mut upgrade_headers = headers;
+    merge_identity_query_params(&mut upgrade_headers, uri.query());
+    let mode = engine.identity_config().mode;
+
+    // OidcBearer: do not fail the upgrade without a token — auth happens in
+    // connection_init (graphql-ws best practice). DevHeaders: resolve now.
+    let upgrade_identity = if mode == IdentityMode::OidcBearer || mode == IdentityMode::Hybrid {
+        ResolvedIdentity::unverified(Session::new())
+    } else {
+        match resolve_identity_with_validator(
+            &upgrade_headers,
+            engine.identity_config(),
+            engine.identity_validator(),
+        )
+        .await
+        {
+            Ok(identity) => identity,
+            Err(AuthError::Unauthorized) => return unauthorized_response(),
+        }
+    };
+
+    let (upgrade_session, upgrade_principal) = upgrade_identity.into_parts();
+    let executor = GraphqlSessionExecutor::with_identity(
+        Arc::clone(&engine),
+        upgrade_session.clone(),
+        upgrade_principal,
+        Some(Arc::clone(&service)),
+    );
+    let engine_for_init = Arc::clone(&engine);
+    upgrade
+        .protocols(ALL_WEBSOCKET_PROTOCOLS)
+        .on_upgrade(move |socket| {
+            let base = upgrade_session;
+            let upgrade_headers = upgrade_headers;
+            GraphQLWebSocket::new(socket, executor, protocol)
+                .on_connection_init(move |payload| {
+                    let base = base.clone();
+                    let engine = engine_for_init;
+                    let upgrade_headers = upgrade_headers;
+                    async move {
+                        let identity =
+                            match resolve_ws_identity(&engine, &upgrade_headers, base, &payload)
+                                .await
+                            {
+                                Ok(identity) => identity,
+                                Err(msg) => {
+                                    return Err(async_graphql::Error::new(msg));
+                                }
+                            };
+                        let (session, principal) = identity.into_parts();
+                        let mut data = Data::default();
+                        data.insert(session);
+                        if let Some(principal) = principal {
+                            data.insert(principal);
+                        }
+                        Ok(data)
+                    }
+                })
+                .serve()
+        })
+        .into_response()
+}
+
+/// Resolve session for a GraphQL WS connection after `connection_init`.
+async fn resolve_ws_identity(
+    engine: &GraphqlEngine,
+    upgrade_headers: &HeaderMap,
+    base: Session,
+    payload: &serde_json::Value,
+) -> Result<ResolvedIdentity, String> {
+    let mode = engine.identity_config().mode;
+    match mode {
+        IdentityMode::OidcBearer | IdentityMode::Hybrid => {
+            let mut headers = upgrade_headers.clone();
+            if let Some(auth) = bearer_from_connection_init(payload) {
+                if let Ok(val) = axum::http::HeaderValue::from_str(&auth) {
+                    headers.insert(axum::http::header::AUTHORIZATION, val);
+                }
+            }
+            resolve_identity_with_validator(
+                &headers,
+                engine.identity_config(),
+                engine.identity_validator(),
+            )
+            .await
+            .map_err(|_| {
+                "unauthorized: provide Authorization Bearer access_token in connection_init".into()
+            })
+        }
+        IdentityMode::DevHeaders | IdentityMode::TrustedProxy => Ok(ResolvedIdentity::unverified(
+            session_from_connection_init(base, payload, mode),
+        )),
+    }
+}
+
+/// Extract Bearer token from connection_init payload (several client conventions).
+fn bearer_from_connection_init(payload: &serde_json::Value) -> Option<String> {
+    let pick = |v: &serde_json::Value| -> Option<String> {
+        let s = v.as_str()?.trim();
+        if s.is_empty() {
+            return None;
+        }
+        if s.get(..7)
+            .is_some_and(|prefix| prefix.eq_ignore_ascii_case("bearer "))
+        {
+            Some(s.to_string())
+        } else {
+            Some(format!("Bearer {s}"))
+        }
+    };
+    if let Some(s) = payload
+        .get("Authorization")
+        .or_else(|| payload.get("authorization"))
+        .and_then(pick)
+    {
+        return Some(s);
+    }
+    if let Some(s) = payload
+        .get("accessToken")
+        .or_else(|| payload.get("access_token"))
+        .and_then(pick)
+    {
+        return Some(s);
+    }
+    if let Some(headers) = payload.get("headers").and_then(|h| h.as_object()) {
+        if let Some(s) = headers
+            .get("Authorization")
+            .or_else(|| headers.get("authorization"))
+            .and_then(pick)
+        {
+            return Some(s);
+        }
+    }
+    None
+}
+
+/// Merge `connection_init` / GraphiQL wsConnectionParams into the upgrade session.
+fn session_from_connection_init(
+    mut session: Session,
+    payload: &serde_json::Value,
+    mode: IdentityMode,
+) -> Session {
+    if mode != IdentityMode::DevHeaders {
+        // OIDC: allow Authorization in connection_init for WS clients that put the
+        // Bearer token there (GraphiQL Headers panel may not reach the upgrade).
+        if let Some(auth) = payload
+            .get("Authorization")
+            .or_else(|| payload.get("authorization"))
+            .and_then(|v| v.as_str())
+        {
+            session.set("authorization", auth);
+        }
+        if let Some(headers) = payload.get("headers").and_then(|h| h.as_object()) {
+            if let Some(auth) = headers
+                .get("Authorization")
+                .or_else(|| headers.get("authorization"))
+                .and_then(|v| v.as_str())
+            {
+                session.set("authorization", auth);
+            }
+        }
+        return session;
+    }
+
+    let apply = |session: &mut Session, key: &str, val: &str| {
+        if key.eq_ignore_ascii_case(USER_ID_KEY) || key.eq_ignore_ascii_case("x-user-id") {
+            session.set(USER_ID_KEY, val);
+        } else if key.eq_ignore_ascii_case(ROLE_KEY) || key.eq_ignore_ascii_case("x-role") {
+            session.set(ROLE_KEY, val);
+        }
+    };
+
+    if let Some(obj) = payload.as_object() {
+        for (k, v) in obj {
+            if let Some(s) = v.as_str() {
+                apply(&mut session, k, s);
+            }
+        }
+        if let Some(headers) = obj.get("headers").and_then(|h| h.as_object()) {
+            for (k, v) in headers {
+                if let Some(s) = v.as_str() {
+                    apply(&mut session, k, s);
+                }
+            }
+        }
+    }
+
+    session
+}
+
+fn merge_identity_query_params(headers: &mut HeaderMap, query: Option<&str>) {
+    let Some(q) = query else {
+        return;
+    };
+    for pair in q.split('&') {
+        let mut it = pair.splitn(2, '=');
+        let k = it.next().unwrap_or("");
+        let v = urlencoding_decode(it.next().unwrap_or(""));
+        match k {
+            "x-user-id" if !headers.contains_key("x-user-id") => {
+                if let Ok(val) = axum::http::HeaderValue::from_str(&v) {
+                    headers.insert("x-user-id", val);
+                }
+            }
+            "x-role" if !headers.contains_key("x-role") => {
+                if let Ok(val) = axum::http::HeaderValue::from_str(&v) {
+                    headers.insert("x-role", val);
+                }
+            }
+            _ => {}
+        }
+    }
+}
+
+fn urlencoding_decode(s: &str) -> String {
+    let mut out = String::with_capacity(s.len());
+    let b = s.as_bytes();
+    let mut i = 0;
+    while i < b.len() {
+        match b[i] {
+            b'+' => {
+                out.push(' ');
+                i += 1;
+            }
+            b'%' if i + 2 < b.len() => {
+                let h = |c: u8| -> Option<u8> {
+                    match c {
+                        b'0'..=b'9' => Some(c - b'0'),
+                        b'a'..=b'f' => Some(c - b'a' + 10),
+                        b'A'..=b'F' => Some(c - b'A' + 10),
+                        _ => None,
+                    }
+                };
+                if let (Some(hi), Some(lo)) = (h(b[i + 1]), h(b[i + 2])) {
+                    out.push((hi << 4 | lo) as char);
+                    i += 3;
+                } else {
+                    out.push('%');
+                    i += 1;
+                }
+            }
+            c => {
+                out.push(c as char);
+                i += 1;
+            }
+        }
+    }
+    out
+}
+
+#[cfg(test)]
+mod connection_init_tests {
+    use super::*;
+    use crate::graphql::IdentityMode;
+    use serde_json::json;
+    use std::any::TypeId;
+
+    #[test]
+    fn websocket_request_context_retains_attached_service() {
+        let service = Arc::new(Service::new());
+        let request = request_with_context(
+            Request::new("{ __typename }"),
+            None,
+            Some(Arc::clone(&service)),
+        );
+        let stored = request
+            .data
+            .get(&TypeId::of::<Arc<Service>>())
+            .and_then(|service| service.downcast_ref::<Arc<Service>>())
+            .expect("service request data");
+        assert!(Arc::ptr_eq(stored, &service));
+    }
+
+    #[test]
+    fn websocket_operation_routing_is_explicit_and_unambiguous() {
+        assert_eq!(
+            websocket_operation_type(&Request::new("{ __typename }")),
+            Ok(OperationType::Query)
+        );
+        assert_eq!(
+            websocket_operation_type(&Request::new("mutation Named { __typename }")),
+            Ok(OperationType::Mutation)
+        );
+        assert_eq!(
+            websocket_operation_type(
+                &Request::new("query Read { __typename } subscription Watch { __typename }")
+                    .operation_name("Watch")
+            ),
+            Ok(OperationType::Subscription)
+        );
+        assert_eq!(
+            websocket_operation_type(&Request::new(
+                "query Read { __typename } mutation Write { __typename }"
+            )),
+            Err("GraphQL operation name is required for multi-operation documents")
+        );
+        assert_eq!(
+            websocket_operation_type(
+                &Request::new("query Read { __typename }").operation_name("Missing")
+            ),
+            Err("GraphQL operation name was not found")
+        );
+        assert_eq!(
+            websocket_operation_type(&Request::new("not graphql")),
+            Err("invalid GraphQL document")
+        );
+    }
+
+    #[test]
+    fn connection_init_sets_dev_headers() {
+        let session = session_from_connection_init(
+            Session::new(),
+            &json!({"x-user-id": "alice", "x-role": "user"}),
+            IdentityMode::DevHeaders,
+        );
+        assert_eq!(session.user_id(), Some("alice"));
+        assert_eq!(session.role(), Some("user"));
+    }
+
+    #[test]
+    fn connection_init_nested_headers() {
+        let session = session_from_connection_init(
+            Session::new(),
+            &json!({"headers": {"x-user-id": "bob", "x-role": "admin"}}),
+            IdentityMode::DevHeaders,
+        );
+        assert_eq!(session.user_id(), Some("bob"));
+        assert_eq!(session.role(), Some("admin"));
+    }
+
+    #[test]
+    fn empty_init_remains_anonymous_in_dev() {
+        let session =
+            session_from_connection_init(Session::new(), &json!({}), IdentityMode::DevHeaders);
+        assert_eq!(session.user_id(), None);
+        assert_eq!(session.role(), None);
+    }
+
+    #[test]
+    fn bearer_from_connection_init_shapes() {
+        assert_eq!(
+            bearer_from_connection_init(&json!({"authorization": "Bearer abc"})).as_deref(),
+            Some("Bearer abc")
+        );
+        assert_eq!(
+            bearer_from_connection_init(&json!({"accessToken": "tok"})).as_deref(),
+            Some("Bearer tok")
+        );
+        assert_eq!(
+            bearer_from_connection_init(&json!({"headers": {"Authorization": "Bearer z"}}))
+                .as_deref(),
+            Some("Bearer z")
+        );
+        assert!(bearer_from_connection_init(&json!({})).is_none());
+    }
+
+    #[test]
+    fn bearer_from_connection_init_accepts_non_ascii_authorization() {
+        assert_eq!(
+            bearer_from_connection_init(&json!({"authorization": "éééé"})).as_deref(),
+            Some("Bearer éééé")
+        );
+    }
+
+    #[test]
+    fn bearer_from_connection_init_accepts_non_ascii_access_token() {
+        assert_eq!(
+            bearer_from_connection_init(&json!({"access_token": "éééé"})).as_deref(),
+            Some("Bearer éééé")
+        );
+    }
+}
diff --git a/src/graphql/identity/claims.rs b/src/graphql/identity/claims.rs
new file mode 100644
index 00000000..38c3734f
--- /dev/null
+++ b/src/graphql/identity/claims.rs
@@ -0,0 +1,232 @@
+//! JWT claims → Session mapping (spec D4/D5, fixtures F1/F2).
+
+use serde_json::Value;
+
+use crate::microsvc::{Session, ROLE_KEY, USER_ID_KEY};
+
+/// Configuration for claim → Session mapping.
+#[derive(Debug, Clone)]
+pub struct ClaimMapConfig {
+    /// JWT claim for subject → `x-user-id`.
+    pub subject_claim: String,
+    /// Ordered claim paths for role candidates.
+    pub role_claims: Vec<String>,
+    /// Priority list for selecting `x-role` (first match wins).
+    pub role_priority: Vec<String>,
+    /// Engine-configured role names (schema keys). Empty = accept any candidate.
+    pub engine_roles: Vec<String>,
+}
+
+impl Default for ClaimMapConfig {
+    fn default() -> Self {
+        Self {
+            subject_claim: "sub".into(),
+            role_claims: vec![
+                "urn:zitadel:iam:org:project:roles".into(),
+                "groups".into(),
+                "roles".into(),
+            ],
+            role_priority: vec![
+                "admin".into(),
+                "operator".into(),
+                "customer".into(),
+                "user".into(),
+            ],
+            engine_roles: Vec::new(),
+        }
+    }
+}
+
+/// Map validated JWT claims JSON to a Session.
+///
+/// Object role claims: keys sorted lexicographically (D5).
+/// `x-roles`: comma-separated allowlisted candidates in first-seen order.
+/// `x-role`: priority ∩ candidates (D4).
+pub fn map_claims_to_session(claims: &Value, config: &ClaimMapConfig) -> Result<Session, String> {
+    map_claims_to_session_with_provenance(claims, config).map(|mapped| mapped.session)
+}
+
+pub(crate) struct MappedClaims {
+    pub(crate) session: Session,
+    pub(crate) selected_role_is_asserted: bool,
+}
+
+pub(crate) fn map_claims_to_session_with_provenance(
+    claims: &Value,
+    config: &ClaimMapConfig,
+) -> Result<MappedClaims, String> {
+    let sub = claims
+        .get(&config.subject_claim)
+        .and_then(|v| v.as_str())
+        .filter(|s| !s.is_empty())
+        .ok_or_else(|| format!("missing non-empty subject claim `{}`", config.subject_claim))?;
+
+    let mut candidates: Vec<String> = Vec::new();
+    for path in &config.role_claims {
+        if let Some(node) = claim_path(claims, path) {
+            collect_role_candidates(node, &mut candidates);
+        }
+    }
+    // Zitadel project-scoped role claims look like
+    // `urn:zitadel:iam:org:project:{projectId}:roles` (object of role keys).
+    // Always scan for them so adapters need not hardcode project ids.
+    if let Some(obj) = claims.as_object() {
+        for (k, v) in obj {
+            if k.starts_with("urn:zitadel:iam:org:project:") && k.ends_with(":roles") {
+                collect_role_candidates(v, &mut candidates);
+            }
+        }
+    }
+
+    // Intersect with engine roles when configured.
+    let allowlisted: Vec<String> = if config.engine_roles.is_empty() {
+        candidates.clone()
+    } else {
+        candidates
+            .into_iter()
+            .filter(|c| config.engine_roles.iter().any(|e| e == c))
+            .collect()
+    };
+
+    let x_roles = allowlisted.join(",");
+    // Prefer explicit claim roles; if the subject is authenticated but no role
+    // claim matched engine roles, default to `user` when that role is configured
+    // (common for OIDC apps that assert roles asynchronously or omit them).
+    let asserted_role = select_role(&allowlisted, &config.role_priority);
+    let selected_role_is_asserted = asserted_role.is_some();
+    let x_role = asserted_role.or_else(|| {
+        if config.engine_roles.iter().any(|e| e == "user") {
+            Some("user".into())
+        } else {
+            None
+        }
+    });
+
+    let mut session = Session::new();
+    session.set(USER_ID_KEY, sub);
+    if let Some(role) = x_role {
+        session.set(ROLE_KEY, role);
+    }
+    if !x_roles.is_empty() {
+        session.set("x-roles", x_roles);
+    }
+
+    // Optional standard mappings when present.
+    if let Some(email) = claims.get("email").and_then(|v| v.as_str()) {
+        session.set("x-email", email);
+    }
+    if let Some(org) = claims
+        .get("org_id")
+        .and_then(|v| v.as_str())
+        .or_else(|| claims.get("orgId").and_then(|v| v.as_str()))
+    {
+        session.set("x-org-id", org);
+    }
+
+    Ok(MappedClaims {
+        session,
+        selected_role_is_asserted,
+    })
+}
+
+fn claim_path<'a>(claims: &'a Value, path: &str) -> Option<&'a Value> {
+    // Dotted path or single key (including URN keys with colons).
+    if path.contains('.') && !path.starts_with("urn:") {
+        let mut cur = claims;
+        for part in path.split('.') {
+            cur = cur.get(part)?;
+        }
+        Some(cur)
+    } else {
+        claims.get(path)
+    }
+}
+
+fn collect_role_candidates(node: &Value, out: &mut Vec<String>) {
+    match node {
+        Value::Object(map) => {
+            let mut keys: Vec<&String> = map.keys().collect();
+            keys.sort();
+            for k in keys {
+                push_unique(out, k.clone());
+            }
+        }
+        Value::Array(arr) => {
+            for v in arr {
+                if let Some(s) = v.as_str() {
+                    push_unique(out, s.to_string());
+                }
+            }
+        }
+        Value::String(s) => push_unique(out, s.clone()),
+        _ => {}
+    }
+}
+
+fn push_unique(out: &mut Vec<String>, s: String) {
+    if !out.iter().any(|e| e == &s) {
+        out.push(s);
+    }
+}
+
+fn select_role(allowlisted: &[String], priority: &[String]) -> Option<String> {
+    if allowlisted.is_empty() {
+        return None;
+    }
+    for p in priority {
+        if allowlisted.iter().any(|a| a == p) {
+            return Some(p.clone());
+        }
+    }
+    Some(allowlisted[0].clone())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn cfg_with_engine(roles: &[&str]) -> ClaimMapConfig {
+        ClaimMapConfig {
+            engine_roles: roles.iter().map(|s| (*s).to_string()).collect(),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn f1_zitadel_project_roles() {
+        let claims = json!({
+            "iss": "http://localhost:8080",
+            "aud": ["graphql-api", "123@graphql"],
+            "sub": "user-a-001",
+            "exp": 4102444800_i64,
+            "urn:zitadel:iam:org:project:roles": {
+                "customer": { "280664559058878577": "zitadel.localhost" },
+                "admin": { "280664559058878577": "zitadel.localhost" }
+            }
+        });
+        let session =
+            map_claims_to_session(&claims, &cfg_with_engine(&["admin", "customer", "user"]))
+                .unwrap();
+        assert_eq!(session.user_id(), Some("user-a-001"));
+        assert_eq!(session.role(), Some("admin"));
+        assert_eq!(session.get("x-roles"), Some("admin,customer"));
+    }
+
+    #[test]
+    fn f2_groups_array() {
+        let claims = json!({
+            "iss": "http://localhost:8080",
+            "aud": "graphql-api",
+            "sub": "user-b-002",
+            "exp": 4102444800_i64,
+            "groups": ["customer", "other-unmapped"]
+        });
+        let session =
+            map_claims_to_session(&claims, &cfg_with_engine(&["admin", "customer", "user"]))
+                .unwrap();
+        assert_eq!(session.user_id(), Some("user-b-002"));
+        assert_eq!(session.role(), Some("customer"));
+        assert_eq!(session.get("x-roles"), Some("customer"));
+    }
+}
diff --git a/src/graphql/identity/mod.rs b/src/graphql/identity/mod.rs
new file mode 100644
index 00000000..47ad99f7
--- /dev/null
+++ b/src/graphql/identity/mod.rs
@@ -0,0 +1,33 @@
+//! GraphQL identity modes: TrustedProxy, OidcBearer, Hybrid, DevHeaders.
+//!
+//! Normative behavior: package spec `specs/query-layer/identity` (D1–D14, F1–F10).
+//! This module only populates [`Session`]; GraphQL RBAC is unchanged.
+
+mod claims;
+mod oidc;
+mod resolve;
+
+pub use claims::{map_claims_to_session, ClaimMapConfig};
+pub(crate) use oidc::VerifiedPrincipal;
+pub use oidc::{OidcConfig, OidcValidator, ValidationError};
+pub use resolve::{
+    extract_bearer, public_oidc_identity_from_env, public_oidc_identity_from_env_vars,
+    resolve_session, resolve_session_sync, strip_identity_headers, AuthError, IdentityConfig,
+    IdentityMode, IdentityResolver, TrustedProxyConfig, DEFAULT_IDENTITY_STRIP_HEADERS,
+    UNSET_OIDC_AUDIENCE, UNSET_OIDC_ISSUER,
+};
+pub(crate) use resolve::{resolve_identity_with_validator, ResolvedIdentity};
+
+use crate::microsvc::Session;
+use axum::http::HeaderMap;
+
+/// Build a Session from all request headers (DevHeaders / mesh trust).
+pub fn session_from_all_headers(headers: &HeaderMap) -> Session {
+    let mut vars = std::collections::HashMap::new();
+    for (name, value) in headers.iter() {
+        if let Ok(v) = value.to_str() {
+            vars.insert(name.as_str().to_string(), v.to_string());
+        }
+    }
+    Session::from_map(vars)
+}
diff --git a/src/graphql/identity/oidc.rs b/src/graphql/identity/oidc.rs
new file mode 100644
index 00000000..373ffbe0
--- /dev/null
+++ b/src/graphql/identity/oidc.rs
@@ -0,0 +1,904 @@
+//! JWT access-token validation + JWKS (spec token validation checklist).
+
+use std::collections::HashMap;
+use std::sync::RwLock;
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+
+use jsonwebtoken::{decode, decode_header, Algorithm, DecodingKey, Validation};
+use serde::Deserialize;
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+use tokio::sync::Mutex as AsyncMutex;
+
+use super::claims::{map_claims_to_session_with_provenance, ClaimMapConfig};
+use crate::microsvc::Session;
+
+const DEFAULT_JWKS_CACHE_TTL: Duration = Duration::from_secs(300);
+const DEFAULT_JWKS_FORCED_REFRESH_COOLDOWN: Duration = Duration::from_secs(5);
+const OIDC_HTTP_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// OIDC validation configuration (behavior normative; field names free).
+#[derive(Debug, Clone)]
+pub struct OidcConfig {
+    pub issuer: String,
+    pub audience: String,
+    /// Additional accepted audiences (e.g. multiple Keycloak confidential clients
+    /// whose client_credentials tokens carry distinct `azp` values).
+    pub extra_audiences: Vec<String>,
+    pub jwks_uri: Option<String>,
+    /// How long live JWKS remain fresh before one request refreshes the cache.
+    pub jwks_cache_ttl: Duration,
+    /// Minimum interval between refreshes forced by tokens with unknown key IDs.
+    pub jwks_forced_refresh_cooldown: Duration,
+    pub clock_skew: Duration,
+    pub alg_allowlist: Vec<String>,
+    /// When true (default), missing Bearer → Unauthorized.
+    pub require_auth: bool,
+    /// When true, valid JWT with no engine role → Unauthorized (D14 default false).
+    pub require_role: bool,
+    pub claim_map: ClaimMapConfig,
+    /// Signed claim paths that participate in the durable command principal
+    /// partition. Every configured claim must be present as a portable,
+    /// non-null JSON value before a bearer identity can enter causal dispatch.
+    pub principal_tenant_claims: Vec<String>,
+    /// Static JWKS JSON for tests / offline (skips network).
+    pub static_jwks: Option<String>,
+}
+
+impl OidcConfig {
+    pub fn new(issuer: impl Into<String>, audience: impl Into<String>) -> Self {
+        Self {
+            issuer: issuer.into(),
+            audience: audience.into(),
+            extra_audiences: Vec::new(),
+            jwks_uri: None,
+            jwks_cache_ttl: DEFAULT_JWKS_CACHE_TTL,
+            jwks_forced_refresh_cooldown: DEFAULT_JWKS_FORCED_REFRESH_COOLDOWN,
+            clock_skew: Duration::from_secs(60),
+            alg_allowlist: vec!["RS256".into(), "ES256".into()],
+            require_auth: true,
+            require_role: false,
+            claim_map: ClaimMapConfig::default(),
+            principal_tenant_claims: Vec::new(),
+            static_jwks: None,
+        }
+    }
+
+    /// Accept additional audiences (multi-client M2M).
+    pub fn with_extra_audiences(
+        mut self,
+        audiences: impl IntoIterator<Item = impl Into<String>>,
+    ) -> Self {
+        self.extra_audiences = audiences.into_iter().map(Into::into).collect();
+        self
+    }
+
+    pub fn with_static_jwks(mut self, jwks: impl Into<String>) -> Self {
+        self.static_jwks = Some(jwks.into());
+        self
+    }
+
+    pub fn require_auth(mut self, on: bool) -> Self {
+        self.require_auth = on;
+        self
+    }
+
+    pub fn engine_roles(mut self, roles: &[&str]) -> Self {
+        self.claim_map.engine_roles = roles.iter().map(|s| (*s).to_string()).collect();
+        self
+    }
+
+    /// Bind durable command identity to these signed tenant claim paths.
+    pub fn principal_tenant_claims(
+        mut self,
+        claims: impl IntoIterator<Item = impl Into<String>>,
+    ) -> Self {
+        self.principal_tenant_claims = claims.into_iter().map(Into::into).collect();
+        self
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+enum VerifiedAudienceSource {
+    Aud,
+    AuthorizedParty,
+    ClientId,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+struct VerifiedAudience {
+    source: VerifiedAudienceSource,
+    value: String,
+}
+
+/// Authentication proof admitted to durable causal dispatch.
+///
+/// This type is deliberately crate-private, has no public constructor, and is
+/// not deserializable. A [`Session`] or trusted header map therefore cannot be
+/// upgraded into a ledger principal by application or transport code.
+#[derive(Clone, PartialEq, Eq)]
+pub(crate) struct VerifiedPrincipal {
+    issuer: String,
+    subject: String,
+    audiences: Vec<VerifiedAudience>,
+    tenant_partitions: Vec<(String, Value)>,
+}
+
+impl VerifiedPrincipal {
+    #[cfg(test)]
+    pub(crate) fn test_oidc(issuer: &str, subject: &str, audiences: &[&str]) -> Self {
+        assert!(
+            !issuer.trim().is_empty(),
+            "test OIDC issuer must not be empty"
+        );
+        assert!(
+            !subject.trim().is_empty(),
+            "test OIDC subject must not be empty"
+        );
+        assert!(
+            !audiences.is_empty() && audiences.iter().all(|value| !value.trim().is_empty()),
+            "test OIDC audiences must contain only non-empty values"
+        );
+        Self {
+            issuer: normalize_issuer(issuer),
+            subject: subject.to_string(),
+            audiences: audiences
+                .iter()
+                .map(|value| VerifiedAudience {
+                    source: VerifiedAudienceSource::Aud,
+                    value: (*value).to_string(),
+                })
+                .collect(),
+            tenant_partitions: Vec::new(),
+        }
+    }
+
+    #[cfg(test)]
+    pub(crate) fn issuer(&self) -> &str {
+        &self.issuer
+    }
+
+    #[cfg(test)]
+    pub(crate) fn subject(&self) -> &str {
+        &self.subject
+    }
+
+    /// Versioned, domain-separated partition for one exact service identity.
+    pub(crate) fn partition_for_service(&self, service_id: &str) -> String {
+        let mut audiences = self
+            .audiences
+            .iter()
+            .map(|audience| audience.value.as_str())
+            .collect::<Vec<_>>();
+        audiences.sort_unstable();
+        audiences.dedup();
+        let canonical = serde_json::to_vec(&serde_json::json!({
+            "domain": "distributed.principal-partition",
+            "version": 1,
+            "service_id": service_id,
+            "issuer": self.issuer,
+            "subject": self.subject,
+            "audiences": audiences,
+            "tenant_partitions": self.tenant_partitions,
+        }))
+        .expect("verified principal partition values are JSON serializable");
+        format!("v1:sha256:{:x}", Sha256::digest(canonical))
+    }
+}
+
+impl std::fmt::Debug for VerifiedPrincipal {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("VerifiedPrincipal")
+            .field("issuer", &self.issuer)
+            .field("subject", &"[redacted]")
+            .field("audiences", &"[redacted]")
+            .field("tenant_partitions", &"[redacted]")
+            .finish()
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ValidationError {
+    Malformed,
+    AlgNotAllowed,
+    AlgNone,
+    Signature,
+    Issuer,
+    Audience,
+    Expired,
+    NotYetValid,
+    MissingSub,
+    TenantPartition,
+    UnknownKid,
+    Jwks,
+    Other(String),
+}
+
+impl std::fmt::Display for ValidationError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Malformed => write!(f, "malformed token"),
+            Self::AlgNotAllowed => write!(f, "algorithm not allowed"),
+            Self::AlgNone => write!(f, "alg none rejected"),
+            Self::Signature => write!(f, "signature verification failed"),
+            Self::Issuer => write!(f, "issuer mismatch"),
+            Self::Audience => write!(f, "audience mismatch"),
+            Self::Expired => write!(f, "token expired"),
+            Self::NotYetValid => write!(f, "token not yet valid"),
+            Self::MissingSub => write!(f, "missing sub"),
+            Self::TenantPartition => write!(f, "missing or invalid tenant partition claim"),
+            Self::UnknownKid => write!(f, "unknown kid"),
+            Self::Jwks => write!(f, "jwks unavailable"),
+            Self::Other(s) => write!(f, "{s}"),
+        }
+    }
+}
+
+impl std::error::Error for ValidationError {}
+
+#[derive(Debug, Deserialize)]
+struct JwksDoc {
+    keys: Vec<JwkKey>,
+}
+
+#[derive(Debug, Deserialize, Clone)]
+struct JwkKey {
+    kid: Option<String>,
+    kty: String,
+    alg: Option<String>,
+    n: Option<String>,
+    e: Option<String>,
+    crv: Option<String>,
+    x: Option<String>,
+    y: Option<String>,
+    #[allow(dead_code)]
+    #[serde(rename = "use")]
+    use_: Option<String>,
+}
+
+struct JwksCache {
+    keys: HashMap<String, DecodingKey>,
+    refreshed_at: Option<Instant>,
+    last_forced_refresh: Option<Instant>,
+    generation: u64,
+}
+
+impl JwksCache {
+    fn is_fresh(&self, ttl: Duration) -> bool {
+        !self.keys.is_empty()
+            && self
+                .refreshed_at
+                .is_some_and(|refreshed_at| refreshed_at.elapsed() < ttl)
+    }
+}
+
+/// Validator with an expiring JWKS cache and single-flight live refresh.
+pub struct OidcValidator {
+    config: OidcConfig,
+    cache: RwLock<JwksCache>,
+    refresh: AsyncMutex<()>,
+    discovered_jwks_uri: RwLock<Option<String>>,
+    http: reqwest::Client,
+}
+
+impl OidcValidator {
+    pub fn new(config: OidcConfig) -> Self {
+        let v = Self {
+            config,
+            cache: RwLock::new(JwksCache {
+                keys: HashMap::new(),
+                refreshed_at: None,
+                last_forced_refresh: None,
+                generation: 0,
+            }),
+            refresh: AsyncMutex::new(()),
+            discovered_jwks_uri: RwLock::new(None),
+            http: reqwest::Client::new(),
+        };
+        if let Some(jwks) = &v.config.static_jwks {
+            let _ = v.load_jwks_json(jwks);
+        }
+        v
+    }
+
+    pub fn config(&self) -> &OidcConfig {
+        &self.config
+    }
+
+    pub fn load_jwks_json(&self, jwks: &str) -> Result<(), ValidationError> {
+        let keys = parse_jwks_keys(jwks)?;
+        let mut cache = self.cache.write().map_err(|_| ValidationError::Jwks)?;
+        cache.keys = keys;
+        cache.refreshed_at = Some(Instant::now());
+        cache.generation = cache.generation.wrapping_add(1);
+        Ok(())
+    }
+
+    /// Validate access-token JWT and map claims → Session.
+    pub fn validate_and_map(&self, token: &str) -> Result<Session, ValidationError> {
+        self.validate_and_map_principal(token)
+            .map(|(session, _)| session)
+    }
+
+    /// Validate one bearer token and retain the signed identity material used
+    /// by durable causal dispatch alongside the ordinary authorization session.
+    pub(crate) fn validate_and_map_principal(
+        &self,
+        token: &str,
+    ) -> Result<(Session, VerifiedPrincipal), ValidationError> {
+        let claims = self.validate_token(token)?;
+        let mapped = map_claims_to_session_with_provenance(&claims, &self.config.claim_map)
+            .map_err(|e| {
+                if e.contains("subject") {
+                    ValidationError::MissingSub
+                } else {
+                    ValidationError::Other(e)
+                }
+            })?;
+        if self.config.require_role && !mapped.selected_role_is_asserted {
+            return Err(ValidationError::Other(
+                "require_role: no asserted engine role".into(),
+            ));
+        }
+        let principal = verified_principal(&claims, &self.config)?;
+        Ok((mapped.session, principal))
+    }
+
+    /// Ensure JWKS is loaded (static or HTTP discovery / jwks_uri).
+    pub async fn ensure_jwks(&self) -> Result<(), ValidationError> {
+        let (generation, fresh) = self.cache_snapshot()?;
+        if fresh {
+            return Ok(());
+        }
+        self.refresh_jwks(generation, false).await
+    }
+
+    /// Async validate with JWKS fetch when needed.
+    pub async fn validate_and_map_async(&self, token: &str) -> Result<Session, ValidationError> {
+        self.validate_and_map_principal_async(token)
+            .await
+            .map(|(session, _)| session)
+    }
+
+    pub(crate) async fn validate_and_map_principal_async(
+        &self,
+        token: &str,
+    ) -> Result<(Session, VerifiedPrincipal), ValidationError> {
+        self.ensure_jwks().await?;
+        let generation = self.cache_generation()?;
+        match self.validate_and_map_principal(token) {
+            Err(ValidationError::UnknownKid) => {
+                self.refresh_jwks(generation, true).await?;
+                self.validate_and_map_principal(token)
+            }
+            result => result,
+        }
+    }
+
+    fn cache_snapshot(&self) -> Result<(u64, bool), ValidationError> {
+        let cache = self.cache.read().map_err(|_| ValidationError::Jwks)?;
+        Ok((cache.generation, cache.is_fresh(self.config.jwks_cache_ttl)))
+    }
+
+    fn cache_generation(&self) -> Result<u64, ValidationError> {
+        self.cache
+            .read()
+            .map(|cache| cache.generation)
+            .map_err(|_| ValidationError::Jwks)
+    }
+
+    async fn refresh_jwks(
+        &self,
+        observed_generation: u64,
+        unknown_kid: bool,
+    ) -> Result<(), ValidationError> {
+        let _refresh = self.refresh.lock().await;
+        {
+            let mut cache = self.cache.write().map_err(|_| ValidationError::Jwks)?;
+            if cache.generation != observed_generation {
+                return Ok(());
+            }
+            if unknown_kid {
+                if cache.last_forced_refresh.is_some_and(|last_refresh| {
+                    last_refresh.elapsed() < self.config.jwks_forced_refresh_cooldown
+                }) {
+                    return Ok(());
+                }
+                // Bound outbound work even when the attempted refresh fails.
+                cache.last_forced_refresh = Some(Instant::now());
+            } else if cache.is_fresh(self.config.jwks_cache_ttl) {
+                return Ok(());
+            }
+        }
+
+        if let Some(jwks) = &self.config.static_jwks {
+            return self.load_jwks_json(jwks);
+        }
+        let jwks_uri = self.live_jwks_uri().await?;
+        let body = self.http_get_text(&jwks_uri).await?;
+        self.load_jwks_json(&body)
+    }
+
+    async fn live_jwks_uri(&self) -> Result<String, ValidationError> {
+        if let Some(uri) = &self.config.jwks_uri {
+            return Ok(uri.clone());
+        }
+        if let Some(uri) = self
+            .discovered_jwks_uri
+            .read()
+            .map_err(|_| ValidationError::Jwks)?
+            .clone()
+        {
+            return Ok(uri);
+        }
+
+        let base = self.config.issuer.trim_end_matches('/');
+        let discovery_url = format!("{base}/.well-known/openid-configuration");
+        let body = self.http_get_text(&discovery_url).await?;
+        let document: Value = serde_json::from_str(&body).map_err(|_| ValidationError::Jwks)?;
+        let uri = document
+            .get("jwks_uri")
+            .and_then(Value::as_str)
+            .map(str::to_string)
+            .ok_or(ValidationError::Jwks)?;
+        *self
+            .discovered_jwks_uri
+            .write()
+            .map_err(|_| ValidationError::Jwks)? = Some(uri.clone());
+        Ok(uri)
+    }
+
+    async fn http_get_text(&self, url: &str) -> Result<String, ValidationError> {
+        let response = self
+            .http
+            .get(url)
+            .timeout(OIDC_HTTP_TIMEOUT)
+            .send()
+            .await
+            .map_err(|_| ValidationError::Jwks)?;
+        if !response.status().is_success() {
+            return Err(ValidationError::Jwks);
+        }
+        response.text().await.map_err(|_| ValidationError::Jwks)
+    }
+
+    /// Validate and return claims JSON (for tests).
+    pub fn validate_token(&self, token: &str) -> Result<Value, ValidationError> {
+        let token = token.trim();
+        if token.is_empty() {
+            return Err(ValidationError::Malformed);
+        }
+
+        let header = decode_header(token).map_err(|_| ValidationError::Malformed)?;
+        let alg_str = match header.alg {
+            Algorithm::RS256 => "RS256",
+            Algorithm::ES256 => "ES256",
+            Algorithm::HS256 | Algorithm::HS384 | Algorithm::HS512 => {
+                return Err(ValidationError::AlgNotAllowed);
+            }
+            _ => {
+                // jsonwebtoken may not decode "none"; check raw header.
+                if let Ok(raw_alg) = raw_header_alg(token) {
+                    if raw_alg.eq_ignore_ascii_case("none") {
+                        return Err(ValidationError::AlgNone);
+                    }
+                }
+                return Err(ValidationError::AlgNotAllowed);
+            }
+        };
+
+        if alg_str.eq_ignore_ascii_case("none") {
+            return Err(ValidationError::AlgNone);
+        }
+        if !self
+            .config
+            .alg_allowlist
+            .iter()
+            .any(|a| a.eq_ignore_ascii_case(alg_str))
+        {
+            return Err(ValidationError::AlgNotAllowed);
+        }
+
+        // Pre-check alg=none from raw header (defense if decode_header is lenient).
+        if let Ok(raw_alg) = raw_header_alg(token) {
+            if raw_alg.eq_ignore_ascii_case("none") {
+                return Err(ValidationError::AlgNone);
+            }
+        }
+
+        let kid = header.kid.unwrap_or_else(|| "_".into());
+        let key = self.key_for_kid(&kid)?;
+
+        let mut validation = Validation::new(header.alg);
+        // Accept issuer with or without trailing slash (Authentik GLOBAL iss often
+        // ends with `/` while config may omit it, and vice versa).
+        let iss_norm = normalize_issuer(&self.config.issuer);
+        let iss_slash = format!("{iss_norm}/");
+        validation.set_issuer(&[&iss_norm, &iss_slash]);
+        // Audience is checked manually: some IdPs (Keycloak client_credentials)
+        // omit `aud` and put the client in `azp` / `client_id` instead.
+        validation.validate_aud = false;
+        validation.leeway = self.config.clock_skew.as_secs();
+        validation.validate_exp = true;
+        validation.validate_nbf = true;
+
+        // Decode as generic JSON claims.
+        let data = decode::<Value>(token, &key, &validation).map_err(map_jwt_error)?;
+
+        let claims = data.claims;
+        if verified_audiences(&claims, &self.config.audience, &self.config.extra_audiences)
+            .is_none()
+        {
+            return Err(ValidationError::Audience);
+        }
+        // token_use if present
+        if let Some(tu) = claims.get("token_use").and_then(|v| v.as_str()) {
+            if tu != "access" {
+                return Err(ValidationError::Other("token_use must be access".into()));
+            }
+        }
+
+        // Ensure sub
+        let sub = claims.get("sub").and_then(|v| v.as_str()).unwrap_or("");
+        if sub.is_empty() {
+            return Err(ValidationError::MissingSub);
+        }
+
+        Ok(claims)
+    }
+
+    fn key_for_kid(&self, kid: &str) -> Result<DecodingKey, ValidationError> {
+        let cache = self.cache.read().map_err(|_| ValidationError::Jwks)?;
+        if let Some(key) = cache.keys.get(kid) {
+            return Ok(key.clone());
+        }
+        if kid == "_" {
+            return cache
+                .keys
+                .get("_")
+                .or_else(|| {
+                    (cache.keys.len() == 1)
+                        .then(|| cache.keys.values().next())
+                        .flatten()
+                })
+                .cloned()
+                .ok_or(ValidationError::UnknownKid);
+        }
+        Err(ValidationError::UnknownKid)
+    }
+}
+
+fn parse_jwks_keys(jwks: &str) -> Result<HashMap<String, DecodingKey>, ValidationError> {
+    let document: JwksDoc = serde_json::from_str(jwks).map_err(|_| ValidationError::Jwks)?;
+    let mut keys = HashMap::new();
+    for key in document.keys {
+        let decoding_key = match key.kty.as_str() {
+            "RSA" if jwk_alg_matches(key.alg.as_deref(), "RS256") => {
+                let (Some(n), Some(e)) = (key.n.as_deref(), key.e.as_deref()) else {
+                    continue;
+                };
+                DecodingKey::from_rsa_components(n, e).map_err(|_| ValidationError::Jwks)?
+            }
+            "EC" if key.crv.as_deref() == Some("P-256")
+                && jwk_alg_matches(key.alg.as_deref(), "ES256") =>
+            {
+                let (Some(x), Some(y)) = (key.x.as_deref(), key.y.as_deref()) else {
+                    continue;
+                };
+                DecodingKey::from_ec_components(x, y).map_err(|_| ValidationError::Jwks)?
+            }
+            _ => continue,
+        };
+        keys.insert(key.kid.unwrap_or_else(|| "_".into()), decoding_key);
+    }
+    if keys.is_empty() {
+        return Err(ValidationError::Jwks);
+    }
+    Ok(keys)
+}
+
+fn normalize_issuer(iss: &str) -> String {
+    iss.trim_end_matches('/').to_string()
+}
+
+fn jwk_alg_matches(jwk_alg: Option<&str>, expected: &str) -> bool {
+    jwk_alg.is_none_or(|alg| alg.eq_ignore_ascii_case(expected))
+}
+
+/// Return the signed audience assertions that satisfied policy. Source is
+/// retained for validation/audit, while principal partitioning uses the
+/// canonical verified values so equivalent IdP token representations are stable.
+fn verified_audiences(
+    claims: &Value,
+    expected: &str,
+    extra: &[String],
+) -> Option<Vec<VerifiedAudience>> {
+    let candidates: Vec<&str> = std::iter::once(expected.trim())
+        .chain(extra.iter().map(|s| s.as_str()))
+        .map(str::trim)
+        .filter(|candidate| !candidate.is_empty())
+        .collect();
+    if candidates.is_empty() {
+        return None;
+    }
+    if let Some(aud) = claims.get("aud") {
+        let asserted = match aud {
+            Value::String(value) => vec![value.as_str()],
+            Value::Array(values) => values.iter().filter_map(Value::as_str).collect(),
+            _ => Vec::new(),
+        };
+        let mut matched = asserted
+            .iter()
+            .filter(|value| candidates.contains(value))
+            .map(|value| VerifiedAudience {
+                source: VerifiedAudienceSource::Aud,
+                value: (*value).to_string(),
+            })
+            .collect::<Vec<_>>();
+        matched.sort();
+        matched.dedup();
+        if !matched.is_empty() {
+            return Some(matched);
+        }
+
+        // `aud` present but no match must not fall through to a weaker claim,
+        // unless it is only the explicit empty/`account` placeholder used by
+        // some client-credentials providers.
+        let placeholder = match aud {
+            Value::String(value) => value == "account" || value.is_empty(),
+            Value::Array(values) => {
+                values.is_empty()
+                    || values
+                        .iter()
+                        .all(|value| matches!(value.as_str(), Some("account") | Some("")))
+            }
+            _ => false,
+        };
+        if !placeholder {
+            return None;
+        }
+    }
+
+    let mut matched = Vec::new();
+    for (claim, source) in [
+        ("azp", VerifiedAudienceSource::AuthorizedParty),
+        ("client_id", VerifiedAudienceSource::ClientId),
+    ] {
+        if let Some(value) = claims.get(claim).and_then(Value::as_str) {
+            if candidates.contains(&value) {
+                matched.push(VerifiedAudience {
+                    source,
+                    value: value.to_string(),
+                });
+            }
+        }
+    }
+    matched.sort();
+    matched.dedup();
+    (!matched.is_empty()).then_some(matched)
+}
+
+fn verified_principal(
+    claims: &Value,
+    config: &OidcConfig,
+) -> Result<VerifiedPrincipal, ValidationError> {
+    let issuer = claims
+        .get("iss")
+        .and_then(Value::as_str)
+        .map(normalize_issuer)
+        .filter(|issuer| !issuer.is_empty())
+        .ok_or(ValidationError::Issuer)?;
+    let subject = claims
+        .get("sub")
+        .and_then(Value::as_str)
+        .filter(|subject| !subject.is_empty())
+        .ok_or(ValidationError::MissingSub)?
+        .to_string();
+    let audiences = verified_audiences(claims, &config.audience, &config.extra_audiences)
+        .ok_or(ValidationError::Audience)?;
+
+    let mut claim_paths = config
+        .principal_tenant_claims
+        .iter()
+        .map(|path| path.trim())
+        .filter(|path| !path.is_empty())
+        .collect::<Vec<_>>();
+    claim_paths.sort_unstable();
+    claim_paths.dedup();
+    let mut tenant_partitions = Vec::with_capacity(claim_paths.len());
+    for path in claim_paths {
+        let value = claim_at_path(claims, path).ok_or(ValidationError::TenantPartition)?;
+        if value.is_null() || value.as_str().is_some_and(|value| value.trim().is_empty()) {
+            return Err(ValidationError::TenantPartition);
+        }
+        tenant_partitions.push((path.to_string(), canonical_json_value(value)));
+    }
+
+    Ok(VerifiedPrincipal {
+        issuer,
+        subject,
+        audiences,
+        tenant_partitions,
+    })
+}
+
+fn claim_at_path<'a>(claims: &'a Value, path: &str) -> Option<&'a Value> {
+    if path.contains('.') && !path.starts_with("urn:") {
+        let mut current = claims;
+        for segment in path.split('.') {
+            current = current.get(segment)?;
+        }
+        Some(current)
+    } else {
+        claims.get(path)
+    }
+}
+
+fn canonical_json_value(value: &Value) -> Value {
+    match value {
+        Value::Array(values) => Value::Array(values.iter().map(canonical_json_value).collect()),
+        Value::Object(values) => {
+            let mut ordered = values.iter().collect::<Vec<_>>();
+            ordered.sort_by_key(|(name, _)| *name);
+            Value::Object(
+                ordered
+                    .into_iter()
+                    .map(|(key, value)| (key.clone(), canonical_json_value(value)))
+                    .collect(),
+            )
+        }
+        scalar => scalar.clone(),
+    }
+}
+
+fn raw_header_alg(token: &str) -> Result<String, ()> {
+    let part = token.split('.').next().ok_or(())?;
+    let bytes = b64url_decode(part).ok_or(())?;
+    let v: Value = serde_json::from_slice(&bytes).map_err(|_| ())?;
+    v.get("alg")
+        .and_then(|a| a.as_str())
+        .map(|s| s.to_string())
+        .ok_or(())
+}
+
+fn b64url_decode(s: &str) -> Option<Vec<u8>> {
+    use base64::Engine;
+    let s = s.replace('-', "+").replace('_', "/");
+    let pad = match s.len() % 4 {
+        2 => "==",
+        3 => "=",
+        _ => "",
+    };
+    base64::engine::general_purpose::STANDARD
+        .decode(format!("{s}{pad}"))
+        .ok()
+}
+
+fn map_jwt_error(e: jsonwebtoken::errors::Error) -> ValidationError {
+    use jsonwebtoken::errors::ErrorKind;
+    match e.kind() {
+        ErrorKind::InvalidAlgorithm | ErrorKind::InvalidAlgorithmName => {
+            ValidationError::AlgNotAllowed
+        }
+        ErrorKind::InvalidSignature => ValidationError::Signature,
+        ErrorKind::InvalidIssuer => ValidationError::Issuer,
+        ErrorKind::InvalidAudience => ValidationError::Audience,
+        ErrorKind::ExpiredSignature => ValidationError::Expired,
+        ErrorKind::ImmatureSignature => ValidationError::NotYetValid,
+        ErrorKind::Base64(_) | ErrorKind::Utf8(_) | ErrorKind::Json(_) => {
+            ValidationError::Malformed
+        }
+        _ => ValidationError::Other(e.to_string()),
+    }
+}
+
+/// Current unix time for tests that craft exp manually.
+#[allow(dead_code)]
+pub fn now_unix() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0)
+}
+
+#[cfg(test)]
+mod principal_tests {
+    use super::*;
+    use serde_json::json;
+
+    fn config() -> OidcConfig {
+        OidcConfig::new("https://issuer.example/", "api-a")
+            .with_extra_audiences(["api-b"])
+            .principal_tenant_claims(["tenant.id", "urn:example:partition"])
+    }
+
+    fn claims(audiences: Value) -> Value {
+        json!({
+            "iss": "https://issuer.example",
+            "sub": "subject-1",
+            "aud": audiences,
+            "tenant": { "id": { "region": "us", "number": 7 } },
+            "urn:example:partition": ["blue", 2]
+        })
+    }
+
+    #[test]
+    fn principal_partition_is_stable_and_service_scoped() {
+        let left = verified_principal(&claims(json!(["api-b", "api-a"])), &config()).unwrap();
+        let right = verified_principal(&claims(json!(["api-a", "api-b"])), &config()).unwrap();
+        assert_eq!(left, right);
+        assert_eq!(
+            left.partition_for_service("todos"),
+            right.partition_for_service("todos")
+        );
+        assert_ne!(
+            left.partition_for_service("todos"),
+            left.partition_for_service("billing")
+        );
+        assert_eq!(left.issuer(), "https://issuer.example");
+        assert_eq!(left.subject(), "subject-1");
+    }
+
+    #[test]
+    fn equivalent_verified_audience_sources_share_partition_identity() {
+        let aud = verified_principal(&claims(json!("api-a")), &config()).unwrap();
+        let mut fallback_claims = claims(json!("account"));
+        fallback_claims["azp"] = json!("api-a");
+        let azp = verified_principal(&fallback_claims, &config()).unwrap();
+        assert_eq!(
+            aud.partition_for_service("todos"),
+            azp.partition_for_service("todos")
+        );
+    }
+
+    #[test]
+    fn role_changes_do_not_create_a_new_principal_partition() {
+        let mut user = claims(json!("api-a"));
+        user["role"] = json!("user");
+        let mut admin = claims(json!("api-a"));
+        admin["role"] = json!("admin");
+        assert_eq!(
+            verified_principal(&user, &config())
+                .unwrap()
+                .partition_for_service("todos"),
+            verified_principal(&admin, &config())
+                .unwrap()
+                .partition_for_service("todos")
+        );
+    }
+
+    #[test]
+    fn configured_tenant_claim_is_required_and_cannot_be_null() {
+        let mut missing = claims(json!("api-a"));
+        missing.as_object_mut().unwrap().remove("tenant");
+        assert_eq!(
+            verified_principal(&missing, &config()).unwrap_err(),
+            ValidationError::TenantPartition
+        );
+
+        let mut null = claims(json!("api-a"));
+        null["tenant"]["id"] = Value::Null;
+        assert_eq!(
+            verified_principal(&null, &config()).unwrap_err(),
+            ValidationError::TenantPartition
+        );
+
+        let mut blank = claims(json!("api-a"));
+        blank["tenant"]["id"] = json!("   ");
+        assert_eq!(
+            verified_principal(&blank, &config()).unwrap_err(),
+            ValidationError::TenantPartition
+        );
+    }
+
+    #[test]
+    fn principal_debug_redacts_subject_and_tenant_values() {
+        let principal = verified_principal(&claims(json!("api-a")), &config()).unwrap();
+        let debug = format!("{principal:?}");
+        assert!(!debug.contains("subject-1"));
+        assert!(!debug.contains("api-a"));
+        assert!(!debug.contains("region"));
+        assert!(debug.contains("[redacted]"));
+    }
+}
diff --git a/src/graphql/identity/resolve.rs b/src/graphql/identity/resolve.rs
new file mode 100644
index 00000000..7e49e603
--- /dev/null
+++ b/src/graphql/identity/resolve.rs
@@ -0,0 +1,516 @@
+//! IdentityMode resolution (D1–D14).
+
+use axum::http::HeaderMap;
+
+use super::oidc::{OidcConfig, OidcValidator, ValidationError, VerifiedPrincipal};
+use super::session_from_all_headers;
+use crate::microsvc::{Session, ROLE_KEY, USER_ID_KEY};
+
+/// Default identity headers stripped under TrustedProxy (fail-closed).
+pub const DEFAULT_IDENTITY_STRIP_HEADERS: &[&str] = &[
+    "x-user-id",
+    "x-role",
+    "x-roles",
+    "x-hasura-user-id",
+    "x-hasura-role",
+    "x-hasura-allowed-roles",
+];
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum IdentityMode {
+    /// Mesh: strip client identity denylist (process-side defense). Gateway
+    /// inject under network isolation should use Hybrid missing-Bearer path
+    /// or configure gateway secret then trust.
+    TrustedProxy,
+    /// Public edge: Bearer JWT required when require_auth (default).
+    OidcBearer,
+    /// Dual path: missing Bearer → trust headers (gateway inject, F6);
+    /// invalid Bearer → 401 (D2); valid → OIDC (D3).
+    Hybrid,
+    /// Local GraphiQL / unit tests only — ambient header trust.
+    #[default]
+    DevHeaders,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct TrustedProxyConfig {
+    pub strip_headers: Vec<String>,
+    /// Optional (name, expected_value). Missing/wrong → 401 (D9).
+    pub gateway_secret_header: Option<(String, String)>,
+}
+
+impl TrustedProxyConfig {
+    pub fn with_defaults() -> Self {
+        Self {
+            strip_headers: DEFAULT_IDENTITY_STRIP_HEADERS
+                .iter()
+                .map(|s| (*s).to_string())
+                .collect(),
+            gateway_secret_header: None,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct IdentityConfig {
+    pub mode: IdentityMode,
+    pub oidc: Option<OidcConfig>,
+    pub trusted_proxy: TrustedProxyConfig,
+}
+
+impl Default for IdentityConfig {
+    fn default() -> Self {
+        // DevHeaders preserves existing ambient-header tests; scaffolds set OidcBearer (D6).
+        Self {
+            mode: IdentityMode::DevHeaders,
+            oidc: None,
+            trusted_proxy: TrustedProxyConfig::with_defaults(),
+        }
+    }
+}
+
+impl IdentityConfig {
+    pub fn oidc_bearer(oidc: OidcConfig) -> Self {
+        Self {
+            mode: IdentityMode::OidcBearer,
+            oidc: Some(oidc),
+            trusted_proxy: TrustedProxyConfig::with_defaults(),
+        }
+    }
+
+    pub fn hybrid(oidc: OidcConfig) -> Self {
+        Self {
+            mode: IdentityMode::Hybrid,
+            oidc: Some(oidc),
+            trusted_proxy: TrustedProxyConfig::with_defaults(),
+        }
+    }
+
+    pub fn trusted_proxy() -> Self {
+        Self {
+            mode: IdentityMode::TrustedProxy,
+            oidc: None,
+            trusted_proxy: TrustedProxyConfig::with_defaults(),
+        }
+    }
+
+    pub fn dev_headers() -> Self {
+        Self {
+            mode: IdentityMode::DevHeaders,
+            oidc: None,
+            trusted_proxy: TrustedProxyConfig::with_defaults(),
+        }
+    }
+}
+
+/// Reusable request identity resolver with one shared OIDC validator and JWKS cache.
+///
+/// Construct one resolver per service or middleware layer and reuse it across
+/// requests so live JWKS discovery, parsing, and refresh state remain cached.
+pub struct IdentityResolver {
+    config: IdentityConfig,
+    validator: Option<OidcValidator>,
+}
+
+impl IdentityResolver {
+    /// Build a resolver and its shared validator from one identity configuration.
+    pub fn new(config: IdentityConfig) -> Self {
+        let validator = match config.mode {
+            IdentityMode::OidcBearer | IdentityMode::Hybrid => {
+                config.oidc.clone().map(OidcValidator::new)
+            }
+            IdentityMode::DevHeaders | IdentityMode::TrustedProxy => None,
+        };
+        Self { config, validator }
+    }
+
+    /// Return the immutable identity configuration used for every resolution.
+    pub fn config(&self) -> &IdentityConfig {
+        &self.config
+    }
+
+    /// Resolve one request while reusing this resolver's live JWKS cache.
+    pub async fn resolve_session(&self, headers: &HeaderMap) -> Result<Session, AuthError> {
+        self.resolve_identity(headers)
+            .await
+            .map(|identity| identity.session)
+    }
+
+    pub(crate) async fn resolve_identity(
+        &self,
+        headers: &HeaderMap,
+    ) -> Result<ResolvedIdentity, AuthError> {
+        resolve_identity_with_validator(headers, &self.config, self.validator.as_ref()).await
+    }
+}
+
+/// Placeholder issuer/audience when OIDC env is unset — fail-closed (401) until configured.
+pub const UNSET_OIDC_ISSUER: &str = "http://localhost/unset-oidc-issuer";
+pub const UNSET_OIDC_AUDIENCE: &str = "unset-audience";
+
+/// Public GraphQL scaffold identity (D6/D7): always **`OidcBearer`** + `require_auth=true`.
+///
+/// Pure inputs so tests do not mutate process env. See [`public_oidc_identity_from_env`].
+///
+/// - When `issuer` and `audience` (or `client_id` as audience fallback) are non-empty → use them.
+/// - When unset → placeholder issuer/audience so requests still require Bearer and reject
+///   ambient `x-user-id` / `x-role` (never [`IdentityMode::DevHeaders`]).
+pub fn public_oidc_identity_from_env_vars(
+    issuer: Option<&str>,
+    audience: Option<&str>,
+    client_id: Option<&str>,
+    jwks_uri: Option<&str>,
+) -> IdentityConfig {
+    let iss = issuer
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .unwrap_or(UNSET_OIDC_ISSUER);
+    let aud = audience
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .or_else(|| client_id.map(str::trim).filter(|s| !s.is_empty()))
+        .unwrap_or(UNSET_OIDC_AUDIENCE);
+
+    let mut oidc = OidcConfig::new(iss, aud);
+    oidc.require_auth = true;
+    if let Some(jwks) = jwks_uri.map(str::trim).filter(|s| !s.is_empty()) {
+        oidc.jwks_uri = Some(jwks.to_string());
+    }
+    IdentityConfig::oidc_bearer(oidc)
+}
+
+/// Read process env (`OIDC_ISSUER`, `OIDC_AUDIENCE` / `OIDC_CLIENT_ID`, `OIDC_JWKS_URI`)
+/// and apply [`public_oidc_identity_from_env_vars`]. Always OidcBearer (D6).
+pub fn public_oidc_identity_from_env() -> IdentityConfig {
+    public_oidc_identity_from_env_vars(
+        std::env::var("OIDC_ISSUER").ok().as_deref(),
+        std::env::var("OIDC_AUDIENCE").ok().as_deref(),
+        std::env::var("OIDC_CLIENT_ID").ok().as_deref(),
+        std::env::var("OIDC_JWKS_URI").ok().as_deref(),
+    )
+}
+
+#[cfg(test)]
+mod public_default_tests {
+    use super::*;
+
+    #[test]
+    fn d6_unset_env_is_oidc_bearer_not_dev_headers() {
+        let cfg = public_oidc_identity_from_env_vars(None, None, None, None);
+        assert_eq!(cfg.mode, IdentityMode::OidcBearer);
+        assert_ne!(cfg.mode, IdentityMode::DevHeaders);
+        let oidc = cfg.oidc.as_ref().expect("oidc config");
+        assert!(oidc.require_auth);
+        assert_eq!(oidc.issuer, UNSET_OIDC_ISSUER);
+        assert_eq!(oidc.audience, UNSET_OIDC_AUDIENCE);
+    }
+
+    #[test]
+    fn d6_configured_env_uses_issuer_audience() {
+        let cfg = public_oidc_identity_from_env_vars(
+            Some("http://localhost:8080"),
+            Some("graphql-api"),
+            None,
+            Some("http://localhost:8080/oauth/v2/keys"),
+        );
+        assert_eq!(cfg.mode, IdentityMode::OidcBearer);
+        let oidc = cfg.oidc.as_ref().unwrap();
+        assert!(oidc.require_auth);
+        assert_eq!(oidc.issuer, "http://localhost:8080");
+        assert_eq!(oidc.audience, "graphql-api");
+        assert_eq!(
+            oidc.jwks_uri.as_deref(),
+            Some("http://localhost:8080/oauth/v2/keys")
+        );
+    }
+
+    #[test]
+    fn d6_client_id_falls_back_as_audience() {
+        let cfg =
+            public_oidc_identity_from_env_vars(Some("http://iss"), None, Some("client-123"), None);
+        assert_eq!(cfg.mode, IdentityMode::OidcBearer);
+        assert_eq!(cfg.oidc.as_ref().unwrap().audience, "client-123");
+    }
+
+    #[test]
+    fn d6_unset_rejects_ambient_headers_via_resolve() {
+        use axum::http::{HeaderMap, HeaderValue};
+        let cfg = public_oidc_identity_from_env_vars(None, None, None, None);
+        let mut headers = HeaderMap::new();
+        headers.insert("x-user-id", HeaderValue::from_static("attacker"));
+        headers.insert("x-role", HeaderValue::from_static("admin"));
+        // No Bearer → require_auth → Unauthorized (not DevHeaders trust)
+        assert_eq!(
+            resolve_session_sync(&headers, &cfg).unwrap_err(),
+            AuthError::Unauthorized
+        );
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AuthError {
+    Unauthorized,
+}
+
+/// A normal authorization session plus the optional bearer-only proof required
+/// for durable causal command dispatch.
+pub(crate) struct ResolvedIdentity {
+    session: Session,
+    principal: Option<VerifiedPrincipal>,
+}
+
+impl ResolvedIdentity {
+    pub(crate) fn unverified(session: Session) -> Self {
+        Self {
+            session,
+            principal: None,
+        }
+    }
+
+    fn verified(session: Session, principal: VerifiedPrincipal) -> Self {
+        Self {
+            session,
+            principal: Some(principal),
+        }
+    }
+
+    pub(crate) fn into_parts(self) -> (Session, Option<VerifiedPrincipal>) {
+        (self.session, self.principal)
+    }
+}
+
+impl From<ValidationError> for AuthError {
+    fn from(_: ValidationError) -> Self {
+        AuthError::Unauthorized
+    }
+}
+
+/// Extract Bearer token. Returns:
+/// - `Ok(None)` — no Authorization or non-Bearer scheme (missing)
+/// - `Ok(Some(token))` — Bearer with non-empty token
+/// - `Err(Unauthorized)` — Bearer scheme with empty token (present-but-invalid)
+pub fn extract_bearer(headers: &HeaderMap) -> Result<Option<String>, AuthError> {
+    let Some(value) = headers.get(axum::http::header::AUTHORIZATION) else {
+        return Ok(None);
+    };
+    let Ok(s) = value.to_str() else {
+        return Err(AuthError::Unauthorized);
+    };
+    let s = s.trim();
+    let mut parts = s.splitn(2, char::is_whitespace);
+    let scheme = parts.next().unwrap_or("");
+    if !scheme.eq_ignore_ascii_case("Bearer") {
+        return Ok(None);
+    }
+    let token = parts.next().map(str::trim).unwrap_or("");
+    if token.is_empty() {
+        return Err(AuthError::Unauthorized);
+    }
+    Ok(Some(token.to_string()))
+}
+
+/// Strip identity denylist headers; keep all others.
+pub fn strip_identity_headers(headers: &HeaderMap, strip: &[String]) -> Session {
+    let mut vars = std::collections::HashMap::new();
+    for (name, value) in headers.iter() {
+        let key = name.as_str();
+        if strip.iter().any(|s| s.eq_ignore_ascii_case(key)) {
+            continue;
+        }
+        if let Ok(v) = value.to_str() {
+            vars.insert(key.to_string(), v.to_string());
+        }
+    }
+    Session::from_map(vars)
+}
+
+fn check_gateway_secret(headers: &HeaderMap, cfg: &TrustedProxyConfig) -> Result<(), AuthError> {
+    if let Some((name, expected)) = &cfg.gateway_secret_header {
+        let got = headers
+            .get(name.as_str())
+            .and_then(|v| v.to_str().ok())
+            .unwrap_or("");
+        if got != expected {
+            return Err(AuthError::Unauthorized);
+        }
+    }
+    Ok(())
+}
+
+fn trusted_proxy_session(
+    headers: &HeaderMap,
+    cfg: &TrustedProxyConfig,
+) -> Result<Session, AuthError> {
+    check_gateway_secret(headers, cfg)?;
+    // Process-side strip of client identity denylist (F10).
+    Ok(strip_identity_headers(headers, &cfg.strip_headers))
+}
+
+/// Hybrid missing-Bearer path: trust headers for gateway inject (F6).
+/// When gateway_secret configured, still enforce it.
+fn hybrid_proxy_session(
+    headers: &HeaderMap,
+    cfg: &TrustedProxyConfig,
+) -> Result<Session, AuthError> {
+    check_gateway_secret(headers, cfg)?;
+    Ok(session_from_all_headers(headers))
+}
+
+fn oidc_identity(token: &str, oidc: &OidcConfig) -> Result<ResolvedIdentity, AuthError> {
+    let validator = OidcValidator::new(oidc.clone());
+    // On OIDC success, never merge client identity headers (caller passes token only).
+    // Static JWKS path (tests). Live JWKS uses resolve_identity async.
+    let (session, principal) = validator
+        .validate_and_map_principal(token)
+        .map_err(AuthError::from)?;
+    Ok(ResolvedIdentity::verified(session, principal))
+}
+
+async fn oidc_identity_async(
+    token: &str,
+    validator: &OidcValidator,
+) -> Result<ResolvedIdentity, AuthError> {
+    let (session, principal) = validator
+        .validate_and_map_principal_async(token)
+        .await
+        .map_err(AuthError::from)?;
+    Ok(ResolvedIdentity::verified(session, principal))
+}
+
+/// Resolve Session from headers + config (sync; uses static JWKS for OIDC).
+///
+/// For live JWKS fetch, prefer [`resolve_session`] after loading JWKS into config.static_jwks
+/// or extending the validator — unit tests always use static JWKS.
+pub fn resolve_session_sync(
+    headers: &HeaderMap,
+    config: &IdentityConfig,
+) -> Result<Session, AuthError> {
+    resolve_identity_sync(headers, config).map(|identity| identity.session)
+}
+
+pub(crate) fn resolve_identity_sync(
+    headers: &HeaderMap,
+    config: &IdentityConfig,
+) -> Result<ResolvedIdentity, AuthError> {
+    match config.mode {
+        IdentityMode::DevHeaders => Ok(ResolvedIdentity::unverified(session_from_all_headers(
+            headers,
+        ))),
+        IdentityMode::TrustedProxy => {
+            trusted_proxy_session(headers, &config.trusted_proxy).map(ResolvedIdentity::unverified)
+        }
+        IdentityMode::OidcBearer => {
+            let oidc = config.oidc.as_ref().ok_or(AuthError::Unauthorized)?;
+            match extract_bearer(headers)? {
+                None => {
+                    if oidc.require_auth {
+                        Err(AuthError::Unauthorized)
+                    } else {
+                        Ok(ResolvedIdentity::unverified(Session::new())) // anonymous F9
+                    }
+                }
+                Some(token) => oidc_identity(&token, oidc),
+            }
+        }
+        IdentityMode::Hybrid => {
+            let oidc = config.oidc.as_ref();
+            match extract_bearer(headers)? {
+                None => hybrid_proxy_session(headers, &config.trusted_proxy)
+                    .map(ResolvedIdentity::unverified), // D1 / F6
+                Some(token) => {
+                    let oidc = oidc.ok_or(AuthError::Unauthorized)?;
+                    // D2: invalid → 401, no proxy fallthrough
+                    oidc_identity(&token, oidc)
+                }
+            }
+        }
+    }
+}
+
+/// Resolve one Session, fetching JWKS when needed.
+///
+/// Services handling repeated requests should reuse [`IdentityResolver`] so
+/// live JWKS remain cached between calls.
+pub async fn resolve_session(
+    headers: &HeaderMap,
+    config: &IdentityConfig,
+) -> Result<Session, AuthError> {
+    IdentityResolver::new(config.clone())
+        .resolve_session(headers)
+        .await
+}
+
+pub(crate) async fn resolve_identity_with_validator(
+    headers: &HeaderMap,
+    config: &IdentityConfig,
+    validator: Option<&OidcValidator>,
+) -> Result<ResolvedIdentity, AuthError> {
+    match config.mode {
+        IdentityMode::OidcBearer => {
+            let oidc = config.oidc.as_ref().ok_or(AuthError::Unauthorized)?;
+            match extract_bearer(headers)? {
+                None => {
+                    if oidc.require_auth {
+                        Err(AuthError::Unauthorized)
+                    } else {
+                        Ok(ResolvedIdentity::unverified(Session::new()))
+                    }
+                }
+                Some(token) => {
+                    let validator = validator.ok_or(AuthError::Unauthorized)?;
+                    oidc_identity_async(&token, validator).await
+                }
+            }
+        }
+        IdentityMode::Hybrid => match extract_bearer(headers)? {
+            None => hybrid_proxy_session(headers, &config.trusted_proxy)
+                .map(ResolvedIdentity::unverified),
+            Some(token) => {
+                let _ = config.oidc.as_ref().ok_or(AuthError::Unauthorized)?;
+                let validator = validator.ok_or(AuthError::Unauthorized)?;
+                oidc_identity_async(&token, validator).await
+            }
+        },
+        _ => resolve_identity_sync(headers, config),
+    }
+}
+
+/// True if session has no elevated identity (no user id / role from convenience keys).
+#[allow(dead_code)]
+pub fn is_anonymous_identity(session: &Session) -> bool {
+    session.get(USER_ID_KEY).is_none() && session.get(ROLE_KEY).is_none()
+}
+
+#[cfg(test)]
+mod causal_identity_tests {
+    use super::*;
+    use axum::http::{HeaderMap, HeaderValue};
+
+    #[test]
+    fn ambient_and_proxy_identity_never_mint_a_causal_principal() {
+        let mut headers = HeaderMap::new();
+        headers.insert(USER_ID_KEY, HeaderValue::from_static("spoofed-user"));
+        headers.insert(ROLE_KEY, HeaderValue::from_static("admin"));
+
+        for config in [
+            IdentityConfig::dev_headers(),
+            IdentityConfig::trusted_proxy(),
+            IdentityConfig::hybrid(OidcConfig::new("https://issuer", "api")),
+        ] {
+            let identity = resolve_identity_sync(&headers, &config).unwrap();
+            let (_, principal) = identity.into_parts();
+            assert!(principal.is_none(), "mode {:?} minted a proof", config.mode);
+        }
+    }
+
+    #[test]
+    fn anonymous_oidc_mode_has_no_causal_principal_without_a_bearer() {
+        let config = IdentityConfig::oidc_bearer(
+            OidcConfig::new("https://issuer", "api").require_auth(false),
+        );
+        let identity = resolve_identity_sync(&HeaderMap::new(), &config).unwrap();
+        let (session, principal) = identity.into_parts();
+        assert!(is_anonymous_identity(&session));
+        assert!(principal.is_none());
+    }
+}
diff --git a/src/graphql/mod.rs b/src/graphql/mod.rs
new file mode 100644
index 00000000..b9cdb1a0
--- /dev/null
+++ b/src/graphql/mod.rs
@@ -0,0 +1,108 @@
+//! Auto-generated read-only GraphQL over relational read models.
+//!
+//! `naming` and `sdl` always compile (zero deps beyond the rest of the crate)
+//! so `dctl schema --format graphql` works without enabling the `graphql`
+//! feature. Execution, the dynamic schema, and the axum router sit behind
+//! `feature = "graphql"`.
+
+pub mod client_manifest;
+pub(crate) mod command_contract;
+pub mod naming;
+pub mod sdl;
+pub mod surface;
+
+// These modules are structural GraphQL metadata and deliberately remain
+// pool/server independent. `dctl` and the runtime engine must compile the same
+// surface without pulling in async-graphql or a database adapter.
+mod commands;
+mod complexity_contract;
+mod filter;
+mod permissions;
+mod types;
+
+pub use client_manifest::*;
+#[doc(hidden)]
+pub use command_contract::{
+    __command_confirmations, __command_effects, __command_input_defaults, __effect_assignment,
+    __effect_constant, __effect_delete, __effect_input, __effect_invalidate_model,
+    __effect_invalidate_relationship, __effect_key, __effect_key_assignment, __effect_key_field,
+    __effect_link, __effect_null, __effect_patch, __effect_relationship, __effect_trusted,
+    __effect_unlink, __effect_upsert, __input_default_ulid, __input_default_uuid_v7,
+    CombineEffectNullability, CompiledEffectFieldValue, CompiledEffectKeyField,
+    CompiledEffectOperation, CompiledInputDefault, EffectAssignmentExpression,
+    EffectInputDescendableKind, EffectInputFieldMarker, EffectInputObjectKind, EffectInputPath,
+    EffectInputPathKind, EffectInputTerminalKind, EffectModelFieldMarker, EffectNullable,
+    EffectPathNullability, EffectRelationshipMarker, EffectRequired, EffectWireBigInt,
+    EffectWireBoolean, EffectWireBytea, EffectWireChecked, EffectWireCompatible, EffectWireFloat,
+    EffectWireJson, EffectWireList, EffectWireLiteral, EffectWireObject, EffectWireString,
+    EffectWireTimestamp, EffectWireUnsupported,
+};
+pub use command_contract::{
+    typed_command, Accepted, CommandConsistency, CompiledCommandEffects, CompiledConfirmationPlan,
+    CompiledDirectProjectionTarget, CompiledInputDefaults, Fact, PrepareCommandError,
+    PreparedCommand, Projected, TypedCommand, TypedEffectExpression, TypedEffectKey,
+    TypedEffectRelationship,
+};
+pub use naming::{
+    aggregate_field, by_pk_field, comparison_op_fields, include_postgres_json_comparison_ops,
+    is_valid_graphql_name, object_type_name, root_list_field, scalar_type_name,
+    PORTABLE_COMPARISON_OPS, POSTGRES_JSON_COMPARISON_OPS, STRING_COMPARISON_OPS,
+};
+pub use sdl::{
+    graphql_sdl_for_role, graphql_sdl_for_tables, graphql_sdl_for_tables_with_options,
+    graphql_sdl_from_surface, SdlOptions,
+};
+pub use surface::{
+    build_surface, role_grants_for_role, surface_for_application, surface_for_role, RoleGrant,
+    RootField, RootKind, Surface, SurfaceArgument, SurfaceArgumentKind, SurfaceCommand,
+    SurfaceCommandShape, SurfaceDialect, SurfaceDirectProjection, SurfaceModel, SurfaceOptions,
+    SurfaceProjectionOwner, SurfaceProjector, SurfaceRelationshipAggregate,
+    SurfaceRelationshipKeys, SurfaceRowPolicy, SurfaceTypeDef, SurfaceTypeField,
+};
+
+pub use filter::{claim, col, lit, rel, ClaimRef, ColRef, FilterExpr, LitValue, Operand};
+pub use permissions::{
+    read, role_grant_from_read_permission, role_grants_from_model_role_perms, ModelPermissions,
+    ReadPermission,
+};
+pub use types::{GraphqlInputType, GraphqlOutputType, GraphqlTypeDef, GraphqlTypeField};
+
+#[cfg(feature = "graphql")]
+pub(crate) mod command_input;
+#[cfg(feature = "graphql")]
+mod compile;
+#[cfg(feature = "graphql")]
+mod complexity;
+#[cfg(feature = "graphql")]
+mod engine;
+#[cfg(feature = "graphql")]
+mod execute;
+#[cfg(feature = "graphql")]
+pub mod http;
+#[cfg(feature = "graphql")]
+pub mod identity;
+#[cfg(feature = "graphql")]
+pub(crate) mod protocol;
+#[cfg(feature = "graphql")]
+pub(crate) mod query_protocol;
+#[cfg(feature = "graphql")]
+mod schema;
+#[cfg(feature = "graphql")]
+pub mod subscribe;
+#[cfg(feature = "graphql")]
+pub use engine::{
+    graphiql_enabled_from_env, graphiql_enabled_from_env_vars, GraphqlBuildError, GraphqlEngine,
+    GraphqlEngineBuilder, GraphqlPool, GraphqlPoolSource,
+};
+#[cfg(feature = "graphql")]
+pub use http::{graphiql_page, graphql_router, graphql_router_with_service};
+#[cfg(feature = "graphql")]
+pub use identity::{
+    extract_bearer, map_claims_to_session, public_oidc_identity_from_env,
+    public_oidc_identity_from_env_vars, resolve_session, resolve_session_sync,
+    strip_identity_headers, AuthError, ClaimMapConfig, IdentityConfig, IdentityMode,
+    IdentityResolver, OidcConfig, OidcValidator, TrustedProxyConfig, ValidationError,
+    DEFAULT_IDENTITY_STRIP_HEADERS, UNSET_OIDC_AUDIENCE, UNSET_OIDC_ISSUER,
+};
+#[cfg(feature = "graphql")]
+pub use subscribe::ChangeHub;
diff --git a/src/graphql/naming.rs b/src/graphql/naming.rs
new file mode 100644
index 00000000..8b99db26
--- /dev/null
+++ b/src/graphql/naming.rs
@@ -0,0 +1,258 @@
+//! GraphQL name-derivation rules shared by the dep-free SDL renderer and the
+//! dynamic schema builder. Every generated name lives here and only here.
+
+use crate::table::{ColumnType, TableSchema};
+
+/// GraphQL name grammar: `[_A-Za-z][_0-9A-Za-z]*` with no leading `__`.
+pub fn is_valid_graphql_name(name: &str) -> bool {
+    let mut chars = name.chars();
+    match chars.next() {
+        Some('_') => {
+            if name.starts_with("__") {
+                return false;
+            }
+            chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
+        }
+        Some(c) if c.is_ascii_alphabetic() => chars.all(|c| c.is_ascii_alphanumeric() || c == '_'),
+        _ => false,
+    }
+}
+
+pub fn object_type_name(schema: &TableSchema) -> &str {
+    &schema.model_name
+}
+
+pub fn root_list_field(schema: &TableSchema) -> &str {
+    &schema.table_name
+}
+
+pub fn by_pk_field(schema: &TableSchema) -> String {
+    format!("{}_by_pk", schema.table_name)
+}
+
+pub fn aggregate_field(schema: &TableSchema) -> String {
+    format!("{}_aggregate", schema.table_name)
+}
+
+pub fn bool_exp_name(schema: &TableSchema) -> String {
+    format!("{}_bool_exp", schema.table_name)
+}
+
+pub fn order_by_name(schema: &TableSchema) -> String {
+    format!("{}_order_by", schema.table_name)
+}
+
+pub fn aggregate_type_name(schema: &TableSchema) -> String {
+    format!("{}_aggregate", schema.table_name)
+}
+
+pub fn aggregate_fields_type_name(schema: &TableSchema) -> String {
+    format!("{}_aggregate_fields", schema.table_name)
+}
+
+pub fn sum_fields_type_name(schema: &TableSchema) -> String {
+    format!("{}_sum_fields", schema.table_name)
+}
+
+pub fn avg_fields_type_name(schema: &TableSchema) -> String {
+    format!("{}_avg_fields", schema.table_name)
+}
+
+pub fn min_fields_type_name(schema: &TableSchema) -> String {
+    format!("{}_min_fields", schema.table_name)
+}
+
+pub fn max_fields_type_name(schema: &TableSchema) -> String {
+    format!("{}_max_fields", schema.table_name)
+}
+
+/// Map a column type to its GraphQL scalar type name (without nullability).
+pub fn scalar_type_name(column_type: &ColumnType) -> Option<&'static str> {
+    match column_type {
+        ColumnType::Text => Some("String"),
+        ColumnType::Boolean => Some("Boolean"),
+        ColumnType::Integer | ColumnType::UnsignedInteger => Some("BigInt"),
+        ColumnType::Float => Some("Float"),
+        ColumnType::Json => Some("JSON"),
+        ColumnType::Timestamp => Some("Timestamptz"),
+        ColumnType::Bytes => Some("Bytea"),
+        ColumnType::Unsupported(_) => None,
+    }
+}
+
+pub fn comparison_exp_name(scalar: &str) -> String {
+    format!("{scalar}_comparison_exp")
+}
+
+/// Portable comparison operators on every scalar's `*_comparison_exp`.
+///
+/// These compile on both SQLite and Postgres (with dialect-specific cast/ILIKE
+/// mapping handled at compile time).
+pub const PORTABLE_COMPARISON_OPS: &[&str] = &[
+    "_eq", "_neq", "_gt", "_gte", "_lt", "_lte", "_in", "_nin", "_is_null",
+];
+
+/// String-only comparison operators (portable; SQLite maps `_ilike` → `LIKE`).
+pub const STRING_COMPARISON_OPS: &[&str] = &["_like", "_ilike"];
+
+/// Postgres `jsonb` operators — only on `JSON_comparison_exp` when the engine
+/// dialect is Postgres. **Must not** appear on SQLite schema or SDL.
+pub const POSTGRES_JSON_COMPARISON_OPS: &[&str] = &["_contains", "_contained_in", "_has_key"];
+
+/// Whether the GraphQL surface should advertise PG JSON comparison ops.
+///
+/// Pass `true` only for Postgres-backed engines (or SDL rendered for PG).
+pub fn include_postgres_json_comparison_ops(dialect_is_postgres: bool) -> bool {
+    dialect_is_postgres
+}
+
+/// Comparison-exp field names for a GraphQL scalar given dialect JSON-op policy.
+pub fn comparison_op_fields(scalar: &str, postgres_json_ops: bool) -> Vec<&'static str> {
+    let mut ops: Vec<&'static str> = PORTABLE_COMPARISON_OPS.to_vec();
+    if scalar == "String" {
+        ops.extend_from_slice(STRING_COMPARISON_OPS);
+    }
+    if scalar == "JSON" && postgres_json_ops {
+        ops.extend_from_slice(POSTGRES_JSON_COMPARISON_OPS);
+    }
+    ops
+}
+
+/// Custom scalars emitted once, alphabetically.
+pub const CUSTOM_SCALARS: &[&str] = &["BigInt", "Bytea", "JSON", "Timestamptz"];
+
+/// Framework-owned causal command-status query field.
+pub const COMMAND_STATUS_ROOT_FIELD: &str = "commandStatus";
+
+/// Framework-owned causal command-status object and state enum.
+pub const DISTRIBUTED_COMMAND_STATUS_TYPE: &str = "DistributedCommandStatus";
+pub const DISTRIBUTED_COMMAND_STATE_TYPE: &str = "DistributedCommandState";
+
+/// Stable public command-state vocabulary. Lowercase values are intentional.
+pub const DISTRIBUTED_COMMAND_STATE_VALUES: &[&str] = &[
+    "in_progress",
+    "accepted",
+    "accepted_pending_projection",
+    "projected",
+    "rejected",
+    "projection_failed",
+    "expired",
+    "unknown",
+];
+
+/// Built-in + custom scalars that are reserved and must not collide with
+/// generated type names.
+pub fn reserved_type_names() -> impl Iterator<Item = &'static str> {
+    [
+        "String",
+        "Boolean",
+        "Int",
+        "Float",
+        "ID",
+        "Query",
+        "Mutation",
+        "Subscription",
+        "order_by",
+        "BigInt",
+        "Bytea",
+        "JSON",
+        "Timestamptz",
+    ]
+    .into_iter()
+}
+
+/// Additional names reserved only on a selected Surface with causal commands.
+///
+/// Legacy/query-only surfaces retain their existing namespace. The SDL and
+/// runtime builders opt into this set after role/application selection proves
+/// at least one visible command with a consistency contract.
+pub fn causal_protocol_type_names() -> impl Iterator<Item = &'static str> {
+    [
+        DISTRIBUTED_COMMAND_STATE_TYPE,
+        DISTRIBUTED_COMMAND_STATUS_TYPE,
+    ]
+    .into_iter()
+}
+
+pub fn order_by_enum_values() -> &'static [&'static str] {
+    &[
+        "asc",
+        "asc_nulls_first",
+        "asc_nulls_last",
+        "desc",
+        "desc_nulls_first",
+        "desc_nulls_last",
+    ]
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn validates_graphql_names() {
+        assert!(is_valid_graphql_name("players"));
+        assert!(is_valid_graphql_name("_private"));
+        assert!(is_valid_graphql_name("PlayerView"));
+        assert!(!is_valid_graphql_name("__typename"));
+        assert!(!is_valid_graphql_name("1players"));
+        assert!(!is_valid_graphql_name("play-ers"));
+        assert!(!is_valid_graphql_name(""));
+    }
+
+    #[test]
+    fn comparison_op_matrix_sqlite_omits_pg_json() {
+        assert!(!include_postgres_json_comparison_ops(false));
+        let json_ops = comparison_op_fields("JSON", false);
+        for op in POSTGRES_JSON_COMPARISON_OPS {
+            assert!(
+                !json_ops.contains(op),
+                "SQLite JSON comparison must not include {op}"
+            );
+        }
+        assert!(json_ops.contains(&"_eq"));
+        let string_ops = comparison_op_fields("String", false);
+        assert!(string_ops.contains(&"_like"));
+        assert!(string_ops.contains(&"_ilike"));
+        assert!(!string_ops.contains(&"_contains"));
+    }
+
+    #[test]
+    fn comparison_op_matrix_postgres_includes_json_ops() {
+        assert!(include_postgres_json_comparison_ops(true));
+        let json_ops = comparison_op_fields("JSON", true);
+        for op in POSTGRES_JSON_COMPARISON_OPS {
+            assert!(json_ops.contains(op), "PG JSON comparison missing {op}");
+        }
+    }
+
+    #[test]
+    fn causal_protocol_names_and_lowercase_states_are_frozen_separately() {
+        assert_eq!(
+            causal_protocol_type_names().collect::<Vec<_>>(),
+            [
+                DISTRIBUTED_COMMAND_STATE_TYPE,
+                DISTRIBUTED_COMMAND_STATUS_TYPE,
+            ]
+        );
+        assert!(!reserved_type_names().any(|name| {
+            name == DISTRIBUTED_COMMAND_STATE_TYPE || name == DISTRIBUTED_COMMAND_STATUS_TYPE
+        }));
+        assert_eq!(
+            DISTRIBUTED_COMMAND_STATE_VALUES,
+            &[
+                "in_progress",
+                "accepted",
+                "accepted_pending_projection",
+                "projected",
+                "rejected",
+                "projection_failed",
+                "expired",
+                "unknown",
+            ]
+        );
+        assert!(DISTRIBUTED_COMMAND_STATE_VALUES
+            .iter()
+            .all(|value| is_valid_graphql_name(value)));
+    }
+}
diff --git a/src/graphql/permissions.rs b/src/graphql/permissions.rs
new file mode 100644
index 00000000..8db26bb6
--- /dev/null
+++ b/src/graphql/permissions.rs
@@ -0,0 +1,215 @@
+//! Role-based **read** permissions for GraphQL models.
+//!
+//! # Mental model (deny-by-default)
+//!
+//! 1. A role that is **not** listed for a model cannot see that model at all.
+//! 2. **Columns** — explicit allowlist, or all columns.
+//! 3. **Rows** — optional predicate; when set, every access path (list, by_pk,
+//!    relationships, aggregates) AND’s it into SQL `WHERE`.
+//!
+//! ```ignore
+//! ModelPermissions::new()
+//!     .grant(
+//!         "user",
+//!         read()
+//!             .all_columns()
+//!             .rows(col("owner_id").eq(claim("x-user-id"))),
+//!     )
+//!     .grant("admin", read().all_columns().aggregations())
+//! ```
+//!
+//! Prefer this vocabulary over “filter” / bare “allow”: grants are roles,
+//! columns are field allowlists, rows are row scope.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::marker::PhantomData;
+
+use super::filter::FilterExpr;
+use super::surface::RoleGrant;
+
+/// Per-role read access for one model.
+#[derive(Clone, Debug)]
+pub struct ReadPermission {
+    /// Allowed column names. Empty means no columns (deny-by-default start).
+    pub(crate) columns: Option<BTreeSet<String>>,
+    pub(crate) all_columns: bool,
+    /// When set, rows must match this predicate (compiled into every WHERE).
+    pub(crate) row_filter: Option<FilterExpr>,
+    pub(crate) limit: Option<u64>,
+    pub(crate) aggregations: bool,
+}
+
+/// Start a deny-by-default read grant (no columns, no rows, no aggregations).
+pub fn read() -> ReadPermission {
+    ReadPermission {
+        columns: Some(BTreeSet::new()),
+        all_columns: false,
+        row_filter: None,
+        limit: None,
+        aggregations: false,
+    }
+}
+
+impl ReadPermission {
+    /// Allow every column on the model for this role.
+    pub fn all_columns(mut self) -> Self {
+        self.all_columns = true;
+        self.columns = None;
+        self
+    }
+
+    /// Allow only these columns (deny-by-default for the rest).
+    pub fn columns<I: IntoIterator<Item = impl Into<String>>>(mut self, i: I) -> Self {
+        self.all_columns = false;
+        self.columns = Some(i.into_iter().map(Into::into).collect());
+        self
+    }
+
+    /// Restrict visible rows to those matching `predicate`.
+    ///
+    /// Compiled into the `WHERE` of list, by_pk, nested relationships, EXISTS
+    /// filters, and aggregates — not an optional soft filter.
+    pub fn rows(mut self, predicate: FilterExpr) -> Self {
+        self.row_filter = Some(predicate);
+        self
+    }
+
+    /// Cap the default page size for this role on this model (still clamped by
+    /// engine max_limit).
+    pub fn limit(mut self, n: u64) -> Self {
+        self.limit = Some(n);
+        self
+    }
+
+    /// Enable aggregate root / nested aggregate fields for this role.
+    pub fn aggregations(mut self) -> Self {
+        self.aggregations = true;
+        self
+    }
+
+    #[cfg_attr(not(feature = "graphql"), allow(dead_code))]
+    pub(crate) fn allows_column(&self, name: &str) -> bool {
+        if self.all_columns {
+            return true;
+        }
+        self.columns
+            .as_ref()
+            .is_some_and(|cols| cols.contains(name))
+    }
+
+    #[allow(dead_code)]
+    pub(crate) fn allowed_columns_for<'a>(
+        &self,
+        schema_columns: impl Iterator<Item = &'a str>,
+    ) -> BTreeSet<String> {
+        if self.all_columns {
+            schema_columns.map(str::to_string).collect()
+        } else {
+            self.columns.clone().unwrap_or_default()
+        }
+    }
+
+    /// Map to feature-free surface IR grant (A12). Row filters / limits stay on
+    /// [`ReadPermission`] for execute; IR only needs column + aggregation surface.
+    pub fn to_role_grant(&self) -> RoleGrant {
+        role_grant_from_read_permission(self)
+    }
+}
+
+/// Pure A12 mapper: engine [`ReadPermission`] → surface [`RoleGrant`].
+pub fn role_grant_from_read_permission(perm: &ReadPermission) -> RoleGrant {
+    let mut g = if perm.all_columns {
+        RoleGrant::all_columns()
+    } else {
+        RoleGrant::columns(perm.columns.clone().unwrap_or_default())
+    };
+    if perm.aggregations {
+        g = g.with_aggregations();
+    }
+    if let Some(predicate) = &perm.row_filter {
+        g = g.rows(predicate.clone());
+    }
+    if let Some(limit) = perm.limit {
+        g = g.limit(limit);
+    }
+    g
+}
+
+/// Collect IR grants for one role from `(model_name, role) → ReadPermission` pairs.
+pub fn role_grants_from_model_role_perms<'a>(
+    role: &str,
+    entries: impl IntoIterator<Item = (&'a (String, String), &'a ReadPermission)>,
+) -> BTreeMap<String, RoleGrant> {
+    let mut out = BTreeMap::new();
+    for ((model, r), perm) in entries {
+        if r == role {
+            out.insert(model.clone(), role_grant_from_read_permission(perm));
+        }
+    }
+    out
+}
+
+/// Typed bag of `(role, ReadPermission)` pairs for one model.
+pub struct ModelPermissions<M> {
+    pub(crate) entries: Vec<(String, ReadPermission)>,
+    _marker: PhantomData<M>,
+}
+
+impl<M> Default for ModelPermissions<M> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<M> ModelPermissions<M> {
+    pub fn new() -> Self {
+        Self {
+            entries: Vec::new(),
+            _marker: PhantomData,
+        }
+    }
+
+    /// Grant `perm` to `role`. Roles never granted cannot query this model.
+    pub fn grant(mut self, role: &str, perm: ReadPermission) -> Self {
+        self.entries.push((role.to_string(), perm));
+        self
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a12_all_columns_maps() {
+        let g = role_grant_from_read_permission(&read().all_columns());
+        assert!(g.all_columns);
+        assert!(g.columns.is_empty());
+        assert!(!g.aggregations);
+    }
+
+    #[test]
+    fn a12_column_list_and_aggregations() {
+        let g =
+            role_grant_from_read_permission(&read().columns(["order_id", "status"]).aggregations());
+        assert!(!g.all_columns);
+        assert!(g.columns.contains("order_id"));
+        assert!(g.columns.contains("status"));
+        assert!(!g.columns.contains("meta"));
+        assert!(g.aggregations);
+        assert!(g.allows_column("order_id"));
+        assert!(!g.allows_column("meta"));
+    }
+
+    #[test]
+    fn a12_role_grants_from_model_role_perms_filters_role() {
+        let user = read().columns(["a"]);
+        let admin = read().all_columns().aggregations();
+        let key_u = ("M".to_string(), "user".to_string());
+        let key_a = ("M".to_string(), "admin".to_string());
+        let map = role_grants_from_model_role_perms("user", [(&key_u, &user), (&key_a, &admin)]);
+        assert_eq!(map.len(), 1);
+        assert!(map["M"].columns.contains("a"));
+        assert!(!map["M"].all_columns);
+    }
+}
diff --git a/src/graphql/protocol/accumulator.rs b/src/graphql/protocol/accumulator.rs
new file mode 100644
index 00000000..f7c4e08e
--- /dev/null
+++ b/src/graphql/protocol/accumulator.rs
@@ -0,0 +1,763 @@
+use std::collections::VecDeque;
+use std::fmt;
+use std::sync::{Arc, Mutex};
+
+use async_graphql::{Response, Value};
+use serde::Serialize;
+
+use super::{
+    DistributedCommandConsistency, DistributedCommandMetadata, DistributedCommandState,
+    DistributedEnvelopeV1, DistributedLiveCursor, DistributedLiveMetadata,
+    DistributedProjectionExpectation, DistributedProjectionObservation, DistributedQuerySnapshot,
+    DistributedRecordRevision, OpaqueProtocolToken, ProtocolTokenCodec, ProtocolTokenError,
+    ProtocolTokenPurpose, RequestedLiveResume,
+};
+use crate::command_ledger::CommandLedgerState;
+use crate::graphql::command_contract::CommandConsistency;
+use crate::microsvc::{
+    CausalCommandProjectionObligation, CausalCommandPublicState, CausalCommandPublicStatus,
+    CausalCommandReceiptSource, CausalProjectionEvidenceState,
+};
+
+#[derive(Serialize)]
+struct LiveResumeTokenMaterial<'a> {
+    domain: &'static str,
+    version: u32,
+    cache_scope: &'a str,
+    schema_hash: &'a str,
+    snapshot_scope: &'a str,
+    projection: &'a str,
+    topology: &'a crate::projection_protocol::ProjectorTopologyId,
+    partition: &'a crate::projection_protocol::ProjectionPartition,
+    epoch: &'a str,
+    position: String,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct ProtocolResponseAccumulator {
+    inner: Arc<ProtocolResponseState>,
+}
+
+#[derive(Debug)]
+struct ProtocolResponseState {
+    envelope: Mutex<DistributedEnvelopeV1>,
+    query_snapshot_scope: Mutex<Option<OpaqueProtocolToken>>,
+    requested_live_resume: Mutex<RequestedLiveResume>,
+    /// `None` is one-shot HTTP execution. `Some` is a stream FIFO containing
+    /// one immutable envelope per yielded GraphQL response.
+    stream_frames: Mutex<Option<VecDeque<DistributedEnvelopeV1>>>,
+    dispatch_claimed: Mutex<bool>,
+    codec: ProtocolTokenCodec,
+}
+
+impl ProtocolResponseAccumulator {
+    pub(crate) fn new(envelope: DistributedEnvelopeV1, codec: ProtocolTokenCodec) -> Self {
+        Self {
+            inner: Arc::new(ProtocolResponseState {
+                envelope: Mutex::new(envelope),
+                query_snapshot_scope: Mutex::new(None),
+                requested_live_resume: Mutex::new(RequestedLiveResume::Absent),
+                stream_frames: Mutex::new(None),
+                dispatch_claimed: Mutex::new(false),
+                codec,
+            }),
+        }
+    }
+
+    pub(crate) fn set_requested_live_resume(
+        &self,
+        requested: RequestedLiveResume,
+    ) -> Result<(), ProtocolAccumulatorError> {
+        *self
+            .inner
+            .requested_live_resume
+            .lock()
+            .map_err(|_| ProtocolAccumulatorError::Poisoned)? = requested;
+        Ok(())
+    }
+
+    pub(crate) fn requested_live_resume(
+        &self,
+    ) -> Result<RequestedLiveResume, ProtocolAccumulatorError> {
+        self.inner
+            .requested_live_resume
+            .lock()
+            .map(|requested| requested.clone())
+            .map_err(|_| ProtocolAccumulatorError::Poisoned)
+    }
+
+    /// Switch this request accumulator to stream mode before injecting it into
+    /// async-graphql. Producers then enqueue immutable frame envelopes; the
+    /// transport pops them in order and cannot race a later frame mutation.
+    pub(crate) fn begin_stream(&self) -> Result<(), ProtocolAccumulatorError> {
+        let mut frames = self
+            .inner
+            .stream_frames
+            .lock()
+            .map_err(|_| ProtocolAccumulatorError::Poisoned)?;
+        if frames.is_none() {
+            *frames = Some(VecDeque::new());
+        }
+        Ok(())
+    }
+
+    /// Stable operation-instance scope used by query/index evidence.
+    ///
+    /// Callers pass only canonical, bounded material (normally the generated
+    /// operation identity plus canonical variables/window). Authorization and
+    /// schema generation are always injected here and cannot be forgotten.
+    pub(crate) fn issue_query_snapshot_scope<T: Serialize>(
+        &self,
+        operation_instance: &T,
+    ) -> Result<OpaqueProtocolToken, ProtocolAccumulatorError> {
+        #[derive(Serialize)]
+        struct Material<'a, T> {
+            domain: &'static str,
+            version: u32,
+            cache_scope: &'a str,
+            schema_hash: &'a str,
+            operation_instance: &'a T,
+        }
+
+        self.with_envelope(|envelope| {
+            self.inner
+                .codec
+                .issue(
+                    ProtocolTokenPurpose::QuerySnapshot,
+                    &Material {
+                        domain: "distributed.graphql.query-snapshot",
+                        version: 1,
+                        cache_scope: envelope.cache_scope.as_str(),
+                        schema_hash: &envelope.schema_hash,
+                        operation_instance,
+                    },
+                )
+                .map_err(|_| ProtocolAccumulatorError::Encoding)
+        })?
+    }
+
+    pub(crate) fn bind_query_snapshot_scope<T: Serialize>(
+        &self,
+        operation_instance: &T,
+    ) -> Result<OpaqueProtocolToken, ProtocolAccumulatorError> {
+        let token = self.issue_query_snapshot_scope(operation_instance)?;
+        let mut existing = self
+            .inner
+            .query_snapshot_scope
+            .lock()
+            .map_err(|_| ProtocolAccumulatorError::Poisoned)?;
+        match existing.as_ref() {
+            None => *existing = Some(token.clone()),
+            Some(existing) if existing == &token => {}
+            Some(_) => return Err(ProtocolAccumulatorError::IncomparableSnapshot),
+        }
+        Ok(token)
+    }
+
+    pub(crate) fn query_snapshot_scope(
+        &self,
+    ) -> Result<OpaqueProtocolToken, ProtocolAccumulatorError> {
+        self.inner
+            .query_snapshot_scope
+            .lock()
+            .map_err(|_| ProtocolAccumulatorError::Poisoned)?
+            .clone()
+            .ok_or(ProtocolAccumulatorError::MissingSnapshotScope)
+    }
+
+    /// Stable record identity token. Revision numbers and operation identity
+    /// are deliberately excluded so values from separate queries remain
+    /// comparable only after this token matches.
+    pub(crate) fn issue_record_scope(
+        &self,
+        scope: &crate::projection_protocol::ProjectionRecordScope,
+    ) -> Result<OpaqueProtocolToken, ProtocolAccumulatorError> {
+        #[derive(Serialize)]
+        struct Material<'a> {
+            domain: &'static str,
+            version: u32,
+            cache_scope: &'a str,
+            schema_hash: &'a str,
+            scope: &'a crate::projection_protocol::ProjectionRecordScope,
+        }
+
+        self.with_envelope(|envelope| {
+            self.inner
+                .codec
+                .issue(
+                    ProtocolTokenPurpose::RecordRevision,
+                    &Material {
+                        domain: "distributed.graphql.record-scope",
+                        version: 1,
+                        cache_scope: envelope.cache_scope.as_str(),
+                        schema_hash: &envelope.schema_hash,
+                        scope,
+                    },
+                )
+                .map_err(|_| ProtocolAccumulatorError::Encoding)
+        })?
+    }
+
+    /// Stable exact-index scope. The current head is excluded so later
+    /// positions within the same projector/partition/query window compare.
+    #[allow(dead_code)]
+    pub(crate) fn issue_index_scope(
+        &self,
+        snapshot_scope: &OpaqueProtocolToken,
+        cursor: &crate::projection_protocol::ProjectionChangeCursor,
+    ) -> Result<OpaqueProtocolToken, ProtocolAccumulatorError> {
+        self.issue_index_scope_parts(
+            snapshot_scope,
+            cursor.topology(),
+            cursor.projection_partition(),
+            cursor.epoch(),
+        )
+    }
+
+    pub(crate) fn issue_index_scope_parts(
+        &self,
+        snapshot_scope: &OpaqueProtocolToken,
+        topology: &crate::projection_protocol::ProjectorTopologyId,
+        partition: &crate::projection_protocol::ProjectionPartition,
+        epoch: &crate::projection_protocol::ProjectionEpoch,
+    ) -> Result<OpaqueProtocolToken, ProtocolAccumulatorError> {
+        #[derive(Serialize)]
+        struct Material<'a> {
+            domain: &'static str,
+            version: u32,
+            cache_scope: &'a str,
+            schema_hash: &'a str,
+            snapshot_scope: &'a str,
+            topology: &'a crate::projection_protocol::ProjectorTopologyId,
+            partition: &'a crate::projection_protocol::ProjectionPartition,
+            epoch: &'a str,
+        }
+
+        self.with_envelope(|envelope| {
+            self.inner
+                .codec
+                .issue(
+                    ProtocolTokenPurpose::QueryIndex,
+                    &Material {
+                        domain: "distributed.graphql.query-index",
+                        version: 1,
+                        cache_scope: envelope.cache_scope.as_str(),
+                        schema_hash: &envelope.schema_hash,
+                        snapshot_scope: snapshot_scope.as_str(),
+                        topology,
+                        partition,
+                        epoch: epoch.as_str(),
+                    },
+                )
+                .map_err(|_| ProtocolAccumulatorError::Encoding)
+        })?
+    }
+
+    #[allow(dead_code)]
+    pub(crate) fn issue_live_resume(
+        &self,
+        projection: &str,
+        snapshot_scope: &OpaqueProtocolToken,
+        cursor: &crate::projection_protocol::ProjectionChangeCursor,
+    ) -> Result<DistributedLiveCursor, ProtocolAccumulatorError> {
+        self.issue_live_resume_position(
+            projection,
+            snapshot_scope,
+            cursor.topology(),
+            cursor.projection_partition(),
+            cursor.epoch(),
+            cursor.position(),
+        )
+    }
+
+    pub(crate) fn issue_live_resume_position(
+        &self,
+        projection: &str,
+        snapshot_scope: &OpaqueProtocolToken,
+        topology: &crate::projection_protocol::ProjectorTopologyId,
+        partition: &crate::projection_protocol::ProjectionPartition,
+        epoch: &crate::projection_protocol::ProjectionEpoch,
+        position: u64,
+    ) -> Result<DistributedLiveCursor, ProtocolAccumulatorError> {
+        let token = self.live_resume_token(
+            projection,
+            snapshot_scope,
+            topology,
+            partition,
+            epoch,
+            position,
+        )?;
+        Ok(DistributedLiveCursor {
+            projection: projection.to_string(),
+            position: position.to_string(),
+            token,
+        })
+    }
+
+    /// Verify a client-returned cursor against one server-derived static
+    /// projector scope. The public projection/position fields select the
+    /// finite candidate; hidden topology/partition/epoch remain MAC-bound.
+    #[allow(dead_code)]
+    pub(crate) fn verify_live_resume(
+        &self,
+        supplied: &DistributedLiveCursor,
+        snapshot_scope: &OpaqueProtocolToken,
+        expected: &crate::projection_protocol::ProjectionChangeCursor,
+    ) -> Result<(), ProtocolTokenError> {
+        if supplied.position != expected.position().to_string() {
+            return Err(ProtocolTokenError::Mismatch);
+        }
+        self.verify_live_resume_position(
+            supplied,
+            snapshot_scope,
+            &supplied.projection,
+            expected.topology(),
+            expected.projection_partition(),
+            expected.epoch(),
+            expected.position(),
+        )
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) fn verify_live_resume_position(
+        &self,
+        supplied: &DistributedLiveCursor,
+        snapshot_scope: &OpaqueProtocolToken,
+        projection: &str,
+        topology: &crate::projection_protocol::ProjectorTopologyId,
+        partition: &crate::projection_protocol::ProjectionPartition,
+        epoch: &crate::projection_protocol::ProjectionEpoch,
+        position: u64,
+    ) -> Result<(), ProtocolTokenError> {
+        if supplied.projection != projection || supplied.position != position.to_string() {
+            return Err(ProtocolTokenError::Mismatch);
+        }
+        self.with_envelope(|envelope| {
+            self.inner.codec.verify(
+                &supplied.token,
+                ProtocolTokenPurpose::LiveResume,
+                &LiveResumeTokenMaterial {
+                    domain: "distributed.graphql.live-resume",
+                    version: 1,
+                    cache_scope: envelope.cache_scope.as_str(),
+                    schema_hash: &envelope.schema_hash,
+                    snapshot_scope: snapshot_scope.as_str(),
+                    projection,
+                    topology,
+                    partition,
+                    epoch: epoch.as_str(),
+                    position: position.to_string(),
+                },
+            )
+        })
+        .map_err(|_| ProtocolTokenError::InvalidMaterial)?
+    }
+
+    fn live_resume_token(
+        &self,
+        projection: &str,
+        snapshot_scope: &OpaqueProtocolToken,
+        topology: &crate::projection_protocol::ProjectorTopologyId,
+        partition: &crate::projection_protocol::ProjectionPartition,
+        epoch: &crate::projection_protocol::ProjectionEpoch,
+        position: u64,
+    ) -> Result<OpaqueProtocolToken, ProtocolAccumulatorError> {
+        self.with_envelope(|envelope| {
+            self.inner
+                .codec
+                .issue(
+                    ProtocolTokenPurpose::LiveResume,
+                    &LiveResumeTokenMaterial {
+                        domain: "distributed.graphql.live-resume",
+                        version: 1,
+                        cache_scope: envelope.cache_scope.as_str(),
+                        schema_hash: &envelope.schema_hash,
+                        snapshot_scope: snapshot_scope.as_str(),
+                        projection,
+                        topology,
+                        partition,
+                        epoch: epoch.as_str(),
+                        position: position.to_string(),
+                    },
+                )
+                .map_err(|_| ProtocolAccumulatorError::Encoding)
+        })?
+    }
+
+    /// Issue the exact token used by both receipt expectations and query/live
+    /// observations. Equality is therefore meaningful without exposing or
+    /// reconstructing canonical partition/key bytes in JavaScript.
+    pub(crate) fn issue_projection_obligation_scope(
+        &self,
+        causation_id: &str,
+        projector: &str,
+        model: &str,
+        observation_kind: crate::projection_protocol::ProjectionObservationKind,
+        scope: &crate::projection_protocol::ProjectionRecordScope,
+    ) -> Result<OpaqueProtocolToken, ProtocolAccumulatorError> {
+        #[derive(Serialize)]
+        struct TokenMaterial<'a> {
+            domain: &'static str,
+            version: u32,
+            cache_scope: &'a str,
+            schema_hash: &'a str,
+            causation_id: &'a str,
+            projector: &'a str,
+            model: &'a str,
+            observation_kind: &'static str,
+            scope: &'a crate::projection_protocol::ProjectionRecordScope,
+        }
+
+        self.with_envelope(|envelope| {
+            self.inner
+                .codec
+                .issue(
+                    ProtocolTokenPurpose::ProjectionObligation,
+                    &TokenMaterial {
+                        domain: "distributed.graphql.projection-obligation",
+                        version: 1,
+                        cache_scope: envelope.cache_scope.as_str(),
+                        schema_hash: &envelope.schema_hash,
+                        causation_id,
+                        projector,
+                        model,
+                        observation_kind: observation_kind.as_storage_str(),
+                        scope,
+                    },
+                )
+                .map_err(|_| ProtocolAccumulatorError::Encoding)
+        })?
+    }
+
+    fn with_envelope<T>(
+        &self,
+        operation: impl FnOnce(&DistributedEnvelopeV1) -> T,
+    ) -> Result<T, ProtocolAccumulatorError> {
+        self.inner
+            .envelope
+            .lock()
+            .map(|envelope| operation(&envelope))
+            .map_err(|_| ProtocolAccumulatorError::Poisoned)
+    }
+
+    /// Reserve this operation's single causal-command dispatch slot before
+    /// invoking application code. This prevents a multi-field mutation from
+    /// committing a second causal command and only then discovering that one
+    /// response envelope cannot represent both receipts.
+    pub(crate) fn claim_dispatch(&self) -> Result<(), ProtocolAccumulatorError> {
+        let mut claimed = self
+            .inner
+            .dispatch_claimed
+            .lock()
+            .map_err(|_| ProtocolAccumulatorError::Poisoned)?;
+        if *claimed {
+            return Err(ProtocolAccumulatorError::MultipleCommands);
+        }
+        *claimed = true;
+        Ok(())
+    }
+
+    /// Convert exact durable replay material into the public wire receipt.
+    ///
+    /// The command payload is deliberately not consumed here. Canonical
+    /// projector partition/key material is fed only into HMAC token issuance
+    /// and can never appear in the serialized envelope.
+    pub(crate) fn record_receipt(
+        &self,
+        receipt: &CausalCommandReceiptSource,
+    ) -> Result<(), ProtocolAccumulatorError> {
+        let observed = (receipt.state == CommandLedgerState::Projected)
+            .then(|| (0..receipt.obligations.len()).collect::<Vec<_>>())
+            .unwrap_or_default();
+        self.record_command(self.metadata(
+            &receipt.command_id,
+            &receipt.causation_id,
+            command_state(receipt.state),
+            receipt.consistency,
+            &receipt.obligations,
+            receipt.direct_projection.as_ref(),
+            &observed,
+        )?)
+    }
+
+    /// Record the authorized public status when it contains a complete receipt.
+    ///
+    /// `unknown` and compact `expired` status intentionally omit command
+    /// metadata: their GraphQL data state remains useful without fabricating or
+    /// disclosing causation. `in_progress` is complete because the durable
+    /// reservation already has a causation ID and consistency contract.
+    pub(crate) fn record_status(
+        &self,
+        status: &CausalCommandPublicStatus,
+    ) -> Result<(), ProtocolAccumulatorError> {
+        let (Some(causation_id), Some(consistency)) =
+            (status.causation_id.as_deref(), status.consistency)
+        else {
+            return Ok(());
+        };
+        let observed = status
+            .evidence
+            .iter()
+            .filter(|evidence| evidence.state == CausalProjectionEvidenceState::Observed)
+            .map(|evidence| evidence.obligation_index)
+            .collect::<Vec<_>>();
+        self.record_command(self.metadata(
+            &status.command_id,
+            causation_id,
+            public_command_state(status.state),
+            consistency,
+            &status.obligations,
+            status.direct_projection.as_ref(),
+            &observed,
+        )?)
+    }
+
+    fn metadata(
+        &self,
+        command_id: &str,
+        causation_id: &str,
+        state: DistributedCommandState,
+        consistency: CommandConsistency,
+        obligations: &[CausalCommandProjectionObligation],
+        direct_projection: Option<&crate::projection_protocol::SameTransactionProjectionEvidence>,
+        observed_obligation_indices: &[usize],
+    ) -> Result<DistributedCommandMetadata, ProtocolAccumulatorError> {
+        let expects = obligations
+            .iter()
+            .map(|obligation| {
+                self.issue_projection_obligation_scope(
+                    causation_id,
+                    &obligation.projector,
+                    &obligation.model,
+                    obligation.observation_kind,
+                    &obligation.scope,
+                )
+                .map(|scope_token| DistributedProjectionExpectation {
+                    projection: obligation.projector.clone(),
+                    model: obligation.model.clone(),
+                    scope_token,
+                })
+            })
+            .collect::<Result<Vec<_>, _>>()?;
+        let mut seen_observations = std::collections::BTreeSet::new();
+        let observations = observed_obligation_indices
+            .iter()
+            .map(|index| {
+                if !seen_observations.insert(*index) {
+                    return Err(ProtocolAccumulatorError::Encoding);
+                }
+                let obligation = obligations
+                    .get(*index)
+                    .ok_or(ProtocolAccumulatorError::Encoding)?;
+                Ok(DistributedProjectionObservation {
+                    causation_id: causation_id.to_string(),
+                    projection: obligation.projector.clone(),
+                    model: obligation.model.clone(),
+                    scope_token: self.issue_projection_obligation_scope(
+                        causation_id,
+                        &obligation.projector,
+                        &obligation.model,
+                        obligation.observation_kind,
+                        &obligation.scope,
+                    )?,
+                })
+            })
+            .collect::<Result<Vec<_>, ProtocolAccumulatorError>>()?;
+        let records = direct_projection
+            .into_iter()
+            .flat_map(|evidence| evidence.records.iter())
+            .map(|record| {
+                Ok(DistributedRecordRevision {
+                    path: None,
+                    model: record.revision.scope().model().to_string(),
+                    scope_token: self.issue_record_scope(record.revision.scope())?,
+                    incarnation: record.revision.incarnation().to_string(),
+                    revision: record.revision.revision().to_string(),
+                    tombstone: record.tombstone,
+                })
+            })
+            .collect::<Result<Vec<_>, ProtocolAccumulatorError>>()?;
+
+        Ok(DistributedCommandMetadata {
+            command_id: command_id.to_string(),
+            causation_id: causation_id.to_string(),
+            state,
+            consistency: command_consistency(consistency),
+            expects,
+            observations,
+            records,
+        })
+    }
+
+    /// Record the one generated causal command represented by this operation.
+    /// Re-recording identical metadata is idempotent; a second distinct command
+    /// fails closed rather than attaching an ambiguous receipt.
+    pub(crate) fn record_command(
+        &self,
+        command: DistributedCommandMetadata,
+    ) -> Result<(), ProtocolAccumulatorError> {
+        let mut envelope = self
+            .inner
+            .envelope
+            .lock()
+            .map_err(|_| ProtocolAccumulatorError::Poisoned)?;
+        match &envelope.command {
+            None => envelope.command = Some(command),
+            Some(existing) if existing == &command => {}
+            Some(_) => return Err(ProtocolAccumulatorError::MultipleCommands),
+        }
+        Ok(())
+    }
+
+    /// Attach query/live evidence to this HTTP response or enqueue one
+    /// immutable GraphQL-WS frame envelope.
+    pub(crate) fn record_query_metadata(
+        &self,
+        mut snapshot: DistributedQuerySnapshot,
+        live: Option<DistributedLiveMetadata>,
+    ) -> Result<(), ProtocolAccumulatorError> {
+        snapshot.discard_incomparable_index_evidence();
+        let mut envelope = self
+            .inner
+            .envelope
+            .lock()
+            .map_err(|_| ProtocolAccumulatorError::Poisoned)?;
+        let mut frames = self
+            .inner
+            .stream_frames
+            .lock()
+            .map_err(|_| ProtocolAccumulatorError::Poisoned)?;
+
+        if let Some(frames) = frames.as_mut() {
+            let mut frame = envelope.clone();
+            frame.snapshot = Some(snapshot);
+            frame.live = live;
+            frames.push_back(frame);
+            return Ok(());
+        }
+
+        match &mut envelope.snapshot {
+            None => envelope.snapshot = Some(snapshot),
+            Some(existing) if existing.scope_token == snapshot.scope_token => {
+                existing.records_complete &= snapshot.records_complete;
+                existing.indexes_comparable &= snapshot.indexes_comparable;
+                existing.records.extend(snapshot.records);
+                existing.indexes.extend(snapshot.indexes);
+                existing.observations.extend(snapshot.observations);
+                existing.discard_incomparable_index_evidence();
+            }
+            Some(_) => return Err(ProtocolAccumulatorError::IncomparableSnapshot),
+        }
+        match (&envelope.live, live) {
+            (None, Some(live)) => envelope.live = Some(live),
+            (Some(existing), Some(live)) if existing == &live => {}
+            (Some(_), Some(_)) => return Err(ProtocolAccumulatorError::IncomparableSnapshot),
+            (_, None) => {}
+        }
+        Ok(())
+    }
+
+    #[allow(dead_code)]
+    pub(crate) fn snapshot(&self) -> Result<DistributedEnvelopeV1, ProtocolAccumulatorError> {
+        self.inner
+            .envelope
+            .lock()
+            .map(|envelope| envelope.clone())
+            .map_err(|_| ProtocolAccumulatorError::Poisoned)
+    }
+
+    pub(crate) fn attach(&self, response: &mut Response) -> Result<(), ProtocolAccumulatorError> {
+        if response.extensions.contains_key("distributed") {
+            return Err(ProtocolAccumulatorError::ExtensionCollision);
+        }
+        let envelope = {
+            let envelope = self
+                .inner
+                .envelope
+                .lock()
+                .map_err(|_| ProtocolAccumulatorError::Poisoned)?;
+            let mut frames = self
+                .inner
+                .stream_frames
+                .lock()
+                .map_err(|_| ProtocolAccumulatorError::Poisoned)?;
+            match frames.as_mut() {
+                Some(frames) => frames.pop_front().unwrap_or_else(|| envelope.clone()),
+                None => envelope.clone(),
+            }
+        };
+        let json =
+            serde_json::to_value(envelope).map_err(|_| ProtocolAccumulatorError::Encoding)?;
+        let value = Value::from_json(json).map_err(|_| ProtocolAccumulatorError::Encoding)?;
+        response.extensions.insert("distributed".into(), value);
+        Ok(())
+    }
+}
+
+fn command_consistency(value: CommandConsistency) -> DistributedCommandConsistency {
+    match value {
+        CommandConsistency::Accepted => DistributedCommandConsistency::Accepted,
+        CommandConsistency::Fact => DistributedCommandConsistency::Fact,
+        CommandConsistency::Projected => DistributedCommandConsistency::Projected,
+    }
+}
+
+fn command_state(value: CommandLedgerState) -> DistributedCommandState {
+    match value {
+        CommandLedgerState::InProgress | CommandLedgerState::RetryableUnknown => {
+            DistributedCommandState::InProgress
+        }
+        CommandLedgerState::Accepted => DistributedCommandState::Accepted,
+        CommandLedgerState::AcceptedPendingProjection => {
+            DistributedCommandState::AcceptedPendingProjection
+        }
+        CommandLedgerState::Projected => DistributedCommandState::Projected,
+        CommandLedgerState::Rejected => DistributedCommandState::Rejected,
+        CommandLedgerState::ProjectionFailed => DistributedCommandState::ProjectionFailed,
+        CommandLedgerState::Expired => DistributedCommandState::Expired,
+    }
+}
+
+fn public_command_state(value: CausalCommandPublicState) -> DistributedCommandState {
+    match value {
+        CausalCommandPublicState::InProgress => DistributedCommandState::InProgress,
+        CausalCommandPublicState::Accepted => DistributedCommandState::Accepted,
+        CausalCommandPublicState::AcceptedPendingProjection => {
+            DistributedCommandState::AcceptedPendingProjection
+        }
+        CausalCommandPublicState::Projected => DistributedCommandState::Projected,
+        CausalCommandPublicState::Rejected => DistributedCommandState::Rejected,
+        CausalCommandPublicState::ProjectionFailed => DistributedCommandState::ProjectionFailed,
+        CausalCommandPublicState::Expired => DistributedCommandState::Expired,
+        CausalCommandPublicState::Unknown => DistributedCommandState::Unknown,
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum ProtocolAccumulatorError {
+    Poisoned,
+    MultipleCommands,
+    ExtensionCollision,
+    IncomparableSnapshot,
+    MissingSnapshotScope,
+    Encoding,
+}
+
+impl fmt::Display for ProtocolAccumulatorError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(match self {
+            Self::Poisoned => "protocol response state is unavailable",
+            Self::MultipleCommands => {
+                "one GraphQL operation cannot carry multiple causal command receipts"
+            }
+            Self::ExtensionCollision => "GraphQL response already defines extensions.distributed",
+            Self::IncomparableSnapshot => {
+                "GraphQL operation produced incomparable query snapshot metadata"
+            }
+            Self::MissingSnapshotScope => "GraphQL query snapshot scope was not initialized",
+            Self::Encoding => "protocol response encoding failed",
+        })
+    }
+}
+
+impl std::error::Error for ProtocolAccumulatorError {}
diff --git a/src/graphql/protocol/mod.rs b/src/graphql/protocol/mod.rs
new file mode 100644
index 00000000..36e1b586
--- /dev/null
+++ b/src/graphql/protocol/mod.rs
@@ -0,0 +1,25 @@
+//! Versioned framework metadata carried in GraphQL response extensions.
+//!
+//! Domain payloads remain ordinary GraphQL data. This module owns the one
+//! `extensions.distributed` wire envelope plus opaque, keyed tokens for
+//! authorization and projection scopes. Tokens are comparable capabilities,
+//! never client-decodable identities and never bearer credentials.
+
+mod accumulator;
+#[cfg(test)]
+mod tests;
+mod token;
+mod types;
+
+pub(crate) use accumulator::ProtocolResponseAccumulator;
+pub(crate) use token::{
+    OpaqueProtocolToken, ProtocolTokenCodec, ProtocolTokenError, ProtocolTokenPurpose,
+    MAX_LIVE_RESUME_CURSORS,
+};
+pub(crate) use types::{
+    DistributedCommandConsistency, DistributedCommandMetadata, DistributedCommandState,
+    DistributedEnvelopeV1, DistributedIndexRevision, DistributedLiveCursor,
+    DistributedLiveMetadata, DistributedProjectionExpectation, DistributedProjectionObservation,
+    DistributedQuerySnapshot, DistributedRecordRevision, DistributedTrustedPreset,
+    RequestedLiveResume,
+};
diff --git a/src/graphql/protocol/tests.rs b/src/graphql/protocol/tests.rs
new file mode 100644
index 00000000..64ae1dd0
--- /dev/null
+++ b/src/graphql/protocol/tests.rs
@@ -0,0 +1,544 @@
+use super::*;
+use super::accumulator::ProtocolAccumulatorError;
+use crate::command_ledger::CommandLedgerState;
+use crate::graphql::command_contract::CommandConsistency;
+use crate::microsvc::{
+    CausalCommandProjectionObligation, CausalCommandPublicState, CausalCommandPublicStatus,
+    CausalCommandReceiptSource, CausalProjectionEvidenceState,
+};
+use crate::projection_protocol::{
+    ProjectionChange, ProjectionChangeCursor, ProjectionChangeKind, ProjectionEpoch,
+    ProjectionObservation, ProjectionObservationKind, ProjectionPartition,
+    ProjectionRecordMetadata, ProjectionRecordScope, ProjectorTopologyId, RecordRevision,
+    SameTransactionProjectionEvidence,
+};
+use async_graphql::{Response, Value};
+
+fn codec(byte: u8) -> ProtocolTokenCodec {
+    ProtocolTokenCodec::new([byte; 32])
+}
+
+#[test]
+fn opaque_tokens_are_deterministic_bound_and_non_disclosing() {
+    let material = ("tenant-7", "todos", "private-key-42");
+    let token = codec(7)
+        .issue(ProtocolTokenPurpose::ProjectionObligation, &material)
+        .unwrap();
+    let again = codec(7)
+        .issue(ProtocolTokenPurpose::ProjectionObligation, &material)
+        .unwrap();
+    assert_eq!(token, again);
+    assert!(!token.as_str().contains("tenant"));
+    assert!(!token.as_str().contains("private-key"));
+    codec(7)
+        .verify(
+            &token,
+            ProtocolTokenPurpose::ProjectionObligation,
+            &material,
+        )
+        .unwrap();
+    assert_eq!(
+        codec(7).verify(&token, ProtocolTokenPurpose::CacheScope, &material),
+        Err(ProtocolTokenError::Malformed)
+    );
+    assert_eq!(
+        codec(8).verify(
+            &token,
+            ProtocolTokenPurpose::ProjectionObligation,
+            &material
+        ),
+        Err(ProtocolTokenError::Mismatch)
+    );
+    assert_eq!(
+        codec(7).verify(
+            &token,
+            ProtocolTokenPurpose::ProjectionObligation,
+            &("tenant-7", "todos", "other")
+        ),
+        Err(ProtocolTokenError::Mismatch)
+    );
+    assert_eq!(format!("{token:?}"), "OpaqueProtocolToken([redacted])");
+}
+
+#[test]
+fn malformed_or_tampered_tokens_fail_closed() {
+    let material = ("scope", 9_u64);
+    let token = codec(3)
+        .issue(ProtocolTokenPurpose::CacheScope, &material)
+        .unwrap();
+    let mut changed = token.as_str().as_bytes().to_vec();
+    let last = changed.last_mut().unwrap();
+    *last = if *last == b'A' { b'B' } else { b'A' };
+    let tampered = OpaqueProtocolToken(String::from_utf8(changed).unwrap());
+    assert!(matches!(
+        codec(3).verify(&tampered, ProtocolTokenPurpose::CacheScope, &material),
+        Err(ProtocolTokenError::Mismatch | ProtocolTokenError::Malformed)
+    ));
+    let malformed = OpaqueProtocolToken("scope-is-not-a-token".into());
+    assert_eq!(
+        codec(3).verify(&malformed, ProtocolTokenPurpose::CacheScope, &material),
+        Err(ProtocolTokenError::Malformed)
+    );
+}
+
+fn command(id: &str) -> DistributedCommandMetadata {
+    DistributedCommandMetadata {
+        command_id: id.into(),
+        causation_id: "cause-17".into(),
+        state: DistributedCommandState::AcceptedPendingProjection,
+        consistency: DistributedCommandConsistency::Fact,
+        expects: vec![DistributedProjectionExpectation {
+            projection: "todos".into(),
+            model: "TodoView".into(),
+            scope_token: codec(9)
+                .issue(ProtocolTokenPurpose::ProjectionObligation, &(id, 42_u64))
+                .unwrap(),
+        }],
+        observations: Vec::new(),
+        records: Vec::new(),
+    }
+}
+
+fn receipt() -> CausalCommandReceiptSource {
+    let topology = ProjectorTopologyId::new(1, "todos", [17; 32]).unwrap();
+    let partition =
+        ProjectionPartition::new(br#"["tenant-private-900719925474099312345"]"#.to_vec()).unwrap();
+    let scope = ProjectionRecordScope::new(
+        topology,
+        partition,
+        "TodoView",
+        br#"["9223372036854775807","child-private"]"#.to_vec(),
+    )
+    .unwrap();
+    CausalCommandReceiptSource {
+        command_id: "0190a000-0000-7000-8000-000000000042".into(),
+        causation_id: "0190a000-0000-7000-8000-000000000017".into(),
+        consistency: CommandConsistency::Fact,
+        state: CommandLedgerState::AcceptedPendingProjection,
+        outcome: serde_json::json!({ "accepted": true }),
+        obligations: vec![CausalCommandProjectionObligation {
+            projector: "todos".into(),
+            model: "TodoView".into(),
+            scope,
+            observation_kind: ProjectionObservationKind::Record,
+        }],
+        direct_projection: None,
+    }
+}
+
+fn direct_projected_receipt() -> CausalCommandReceiptSource {
+    let mut receipt = receipt();
+    let scope = receipt.obligations[0].scope.clone();
+    let revision = RecordRevision::new(scope.clone(), 3, 9_007_199_254_740_991).unwrap();
+    let change = ProjectionChangeCursor::new(
+        scope.topology().clone(),
+        scope.projection_partition().clone(),
+        ProjectionEpoch::new("direct-v1").unwrap(),
+        17,
+    )
+    .unwrap();
+    receipt.consistency = CommandConsistency::Projected;
+    receipt.state = CommandLedgerState::Projected;
+    receipt.obligations.clear();
+    receipt.direct_projection = Some(SameTransactionProjectionEvidence {
+        records: vec![ProjectionRecordMetadata {
+            revision: revision.clone(),
+            tombstone: false,
+            change: change.clone(),
+        }],
+        changes: vec![ProjectionChange {
+            cursor: change.clone(),
+            kind: ProjectionChangeKind::RecordUpsert,
+            causation_id: receipt.causation_id.clone(),
+            observation_kind: None,
+            scope: Some(scope.clone()),
+            revision: Some(revision.clone()),
+            failure_id: None,
+        }],
+        observations: vec![ProjectionObservation {
+            causation_id: receipt.causation_id.clone(),
+            kind: ProjectionObservationKind::Record,
+            revision: Some(revision),
+            scope,
+            change,
+        }],
+    });
+    receipt
+}
+
+fn change_cursor(position: u64) -> ProjectionChangeCursor {
+    ProjectionChangeCursor::new(
+        ProjectorTopologyId::new(1, "todos", [17; 32]).unwrap(),
+        ProjectionPartition::new(br#"["tenant-private-900719925474099312345"]"#.to_vec()).unwrap(),
+        ProjectionEpoch::new("todos-v1").unwrap(),
+        position,
+    )
+    .unwrap()
+}
+
+fn query_snapshot(
+    accumulator: &ProtocolResponseAccumulator,
+    operation: &str,
+    position: u64,
+) -> DistributedQuerySnapshot {
+    let scope_token = accumulator
+        .issue_query_snapshot_scope(&(operation, "canonical-window"))
+        .unwrap();
+    let cursor = change_cursor(position);
+    DistributedQuerySnapshot {
+        scope_token: scope_token.clone(),
+        records_complete: true,
+        indexes_comparable: true,
+        records: Vec::new(),
+        indexes: vec![DistributedIndexRevision {
+            projection: "todos".into(),
+            scope_token: accumulator
+                .issue_index_scope(&scope_token, &cursor)
+                .unwrap(),
+            position: position.to_string(),
+            resume: Some(
+                accumulator
+                    .issue_live_resume("todos", &scope_token, &cursor)
+                    .unwrap(),
+            ),
+        }],
+        observations: Vec::new(),
+    }
+}
+
+fn accumulator(key: u8, cache_material: &str, schema: &str) -> ProtocolResponseAccumulator {
+    let codec = codec(key);
+    let cache_scope = codec
+        .issue(ProtocolTokenPurpose::CacheScope, &cache_material)
+        .unwrap();
+    ProtocolResponseAccumulator::new(DistributedEnvelopeV1::new(schema, cache_scope, None), codec)
+}
+
+#[test]
+fn accumulator_is_idempotent_and_rejects_ambiguous_receipts() {
+    let scope = codec(9)
+        .issue(ProtocolTokenPurpose::CacheScope, &("principal", "surface"))
+        .unwrap();
+    let accumulator = ProtocolResponseAccumulator::new(
+        DistributedEnvelopeV1::new("sha256:schema", scope, Some("sha256:operation".into())),
+        codec(9),
+    );
+    accumulator.claim_dispatch().unwrap();
+    assert_eq!(
+        accumulator.claim_dispatch(),
+        Err(ProtocolAccumulatorError::MultipleCommands)
+    );
+    accumulator.record_command(command("cmd-1")).unwrap();
+    accumulator.record_command(command("cmd-1")).unwrap();
+    assert_eq!(
+        accumulator.record_command(command("cmd-2")),
+        Err(ProtocolAccumulatorError::MultipleCommands)
+    );
+
+    let envelope = accumulator.snapshot().unwrap();
+    let json = serde_json::to_value(envelope).unwrap();
+    assert_eq!(json["protocolVersion"], 1);
+    assert_eq!(json["schemaHash"], "sha256:schema");
+    assert_eq!(json["operation"], "sha256:operation");
+    assert_eq!(json["command"]["commandId"], "cmd-1");
+    assert_eq!(json["command"]["state"], "accepted_pending_projection");
+    assert_eq!(json["command"]["expects"][0]["model"], "TodoView");
+    assert!(json["command"]["expects"][0]["scopeToken"]
+        .as_str()
+        .unwrap()
+        .starts_with("v1.projection-obligation."));
+}
+
+#[test]
+fn durable_receipts_issue_stable_generation_bound_non_disclosing_obligations() {
+    let receipt = receipt();
+    let first = accumulator(11, "principal-a", "sha256:schema-a");
+    first.record_receipt(&receipt).unwrap();
+    let first = serde_json::to_value(first.snapshot().unwrap()).unwrap();
+    let first_token = first["command"]["expects"][0]["scopeToken"]
+        .as_str()
+        .unwrap();
+    assert_eq!(first["command"]["state"], "accepted_pending_projection");
+    assert_eq!(first["command"]["consistency"], "fact");
+    assert!(!first_token.contains("tenant-private"));
+    assert!(!first_token.contains("9223372036854775807"));
+    assert!(!first_token.contains("child-private"));
+
+    let replay = accumulator(11, "principal-a", "sha256:schema-a");
+    replay.record_receipt(&receipt).unwrap();
+    let replay = serde_json::to_value(replay.snapshot().unwrap()).unwrap();
+    assert_eq!(
+        first_token,
+        replay["command"]["expects"][0]["scopeToken"]
+            .as_str()
+            .unwrap()
+    );
+
+    for changed in [
+        accumulator(12, "principal-a", "sha256:schema-a"),
+        accumulator(11, "principal-b", "sha256:schema-a"),
+        accumulator(11, "principal-a", "sha256:schema-b"),
+    ] {
+        changed.record_receipt(&receipt).unwrap();
+        let changed = serde_json::to_value(changed.snapshot().unwrap()).unwrap();
+        assert_ne!(
+            first_token,
+            changed["command"]["expects"][0]["scopeToken"]
+                .as_str()
+                .unwrap()
+        );
+    }
+}
+
+#[test]
+fn direct_projected_receipt_replays_exact_record_revision_as_decimal_strings() {
+    let receipt = direct_projected_receipt();
+    let first = accumulator(17, "principal-a", "sha256:schema-a");
+    first.record_receipt(&receipt).unwrap();
+    let command = serde_json::to_value(first.snapshot().unwrap()).unwrap()["command"].clone();
+    assert_eq!(command["state"], "projected");
+    assert_eq!(command["consistency"], "projected");
+    assert_eq!(command["records"][0]["incarnation"], "3");
+    assert_eq!(command["records"][0]["revision"], "9007199254740991");
+    assert_eq!(command["records"][0]["tombstone"], false);
+    assert!(command["records"][0].get("path").is_none());
+    let token = command["records"][0]["scopeToken"].as_str().unwrap();
+    assert!(token.starts_with("v1.record-revision."));
+    assert!(!token.contains("tenant-private"));
+    assert!(!token.contains("child-private"));
+
+    let replay = accumulator(17, "principal-a", "sha256:schema-a");
+    replay.record_receipt(&receipt).unwrap();
+    let replay = serde_json::to_value(replay.snapshot().unwrap()).unwrap();
+    assert_eq!(command["records"], replay["command"]["records"]);
+}
+
+#[test]
+fn unknown_status_does_not_fabricate_receipt_identity() {
+    let accumulator = accumulator(5, "principal-a", "sha256:schema-a");
+    accumulator
+        .record_status(&CausalCommandPublicStatus {
+            state: CausalCommandPublicState::Unknown,
+            command_id: "0190a000-0000-7000-8000-000000000099".into(),
+            causation_id: None,
+            consistency: None,
+            outcome: None,
+            obligations: Vec::new(),
+            evidence: Vec::new(),
+            direct_projection: None,
+        })
+        .unwrap();
+    let envelope = serde_json::to_value(accumulator.snapshot().unwrap()).unwrap();
+    assert!(envelope.get("command").is_none());
+}
+
+#[test]
+fn projected_status_exposes_only_matching_opaque_observations() {
+    let source = receipt();
+    let accumulator = accumulator(5, "principal-a", "sha256:schema-a");
+    accumulator
+        .record_status(&CausalCommandPublicStatus {
+            state: CausalCommandPublicState::Projected,
+            command_id: source.command_id,
+            causation_id: Some(source.causation_id.clone()),
+            consistency: Some(source.consistency),
+            outcome: Some(source.outcome),
+            obligations: source.obligations,
+            evidence: vec![crate::microsvc::CausalCommandProjectionEvidence {
+                obligation_index: 0,
+                state: CausalProjectionEvidenceState::Observed,
+                incarnation: Some(1),
+                revision: Some(7),
+            }],
+            direct_projection: None,
+        })
+        .unwrap();
+    let command = serde_json::to_value(accumulator.snapshot().unwrap()).unwrap()["command"].clone();
+    assert_eq!(command["state"], "projected");
+    assert_eq!(
+        command["observations"][0]["causationId"],
+        source.causation_id
+    );
+    assert_eq!(
+        command["observations"][0]["scopeToken"],
+        command["expects"][0]["scopeToken"]
+    );
+    let encoded = command.to_string();
+    assert!(!encoded.contains("tenant-private"));
+    assert!(!encoded.contains("9223372036854775807"));
+}
+
+#[test]
+fn revision_and_resume_tokens_are_scoped_comparable_and_tamper_evident() {
+    let accumulator = accumulator(31, "principal-a", "sha256:schema-a");
+    let snapshot_scope = accumulator
+        .issue_query_snapshot_scope(&("sha256:operation-a", "window-a"))
+        .unwrap();
+    let other_operation = accumulator
+        .issue_query_snapshot_scope(&("sha256:operation-b", "window-a"))
+        .unwrap();
+    assert_ne!(snapshot_scope, other_operation);
+
+    let receipt = receipt();
+    let scope = &receipt.obligations[0].scope;
+    let record_scope = accumulator.issue_record_scope(scope).unwrap();
+    assert_eq!(record_scope, accumulator.issue_record_scope(scope).unwrap());
+    assert!(!record_scope.as_str().contains("tenant-private"));
+    assert!(!record_scope.as_str().contains("9223372036854775807"));
+
+    let cursor = change_cursor(9_007_199_254_740_991);
+    let live = accumulator
+        .issue_live_resume("todos", &snapshot_scope, &cursor)
+        .unwrap();
+    assert_eq!(live.position, "9007199254740991");
+    accumulator
+        .verify_live_resume(&live, &snapshot_scope, &cursor)
+        .unwrap();
+
+    let parsed = OpaqueProtocolToken::parse(live.token.as_str()).unwrap();
+    assert_eq!(parsed, live.token);
+    let mut wrong_position = live.clone();
+    wrong_position.position = "9007199254740990".into();
+    assert_eq!(
+        accumulator.verify_live_resume(&wrong_position, &snapshot_scope, &cursor),
+        Err(ProtocolTokenError::Mismatch)
+    );
+    assert_eq!(
+        accumulator.verify_live_resume(&live, &other_operation, &cursor),
+        Err(ProtocolTokenError::Mismatch)
+    );
+    assert_eq!(
+        OpaqueProtocolToken::parse("v1.live-resume.not/canonical"),
+        Err(ProtocolTokenError::Malformed)
+    );
+}
+
+#[test]
+fn observation_tokens_exactly_match_receipt_obligations() {
+    let receipt = receipt();
+    let accumulator = accumulator(41, "principal-a", "sha256:schema-a");
+    accumulator.record_receipt(&receipt).unwrap();
+    let expectation = accumulator.snapshot().unwrap().command.unwrap().expects[0]
+        .scope_token
+        .clone();
+    let obligation = &receipt.obligations[0];
+    let observed = accumulator
+        .issue_projection_obligation_scope(
+            &receipt.causation_id,
+            &obligation.projector,
+            &obligation.model,
+            obligation.observation_kind,
+            &obligation.scope,
+        )
+        .unwrap();
+    assert_eq!(expectation, observed);
+}
+
+#[test]
+fn query_snapshot_merge_preserves_comparable_indexes_when_only_records_are_incomplete() {
+    let accumulator = accumulator(47, "principal-a", "sha256:schema-a");
+    let mut record_incomplete = query_snapshot(&accumulator, "operation-a", 1);
+    record_incomplete.records_complete = false;
+    let mut record_complete = query_snapshot(&accumulator, "operation-a", 2);
+    record_complete.indexes.clear();
+
+    accumulator
+        .record_query_metadata(record_incomplete, None)
+        .unwrap();
+    accumulator
+        .record_query_metadata(record_complete, None)
+        .unwrap();
+
+    let snapshot = accumulator.snapshot().unwrap().snapshot.unwrap();
+    assert!(!snapshot.records_complete);
+    assert!(snapshot.indexes_comparable);
+    assert_eq!(snapshot.indexes.len(), 1);
+    let wire = serde_json::to_value(snapshot).unwrap();
+    assert_eq!(wire["recordsComplete"], false);
+    assert_eq!(wire["indexesComparable"], true);
+    assert!(wire.get("complete").is_none());
+}
+
+#[test]
+fn query_snapshot_merge_discards_index_evidence_when_any_index_is_incomparable() {
+    let accumulator = accumulator(49, "principal-a", "sha256:schema-a");
+    let comparable = query_snapshot(&accumulator, "operation-a", 1);
+    let mut incomparable = query_snapshot(&accumulator, "operation-a", 2);
+    incomparable.indexes_comparable = false;
+    incomparable.observations = vec![DistributedProjectionObservation {
+        causation_id: "causation-private".into(),
+        projection: "todos".into(),
+        model: "TodoView".into(),
+        scope_token: incomparable.indexes[0].scope_token.clone(),
+    }];
+
+    accumulator.record_query_metadata(comparable, None).unwrap();
+    accumulator
+        .record_query_metadata(incomparable, None)
+        .unwrap();
+
+    let snapshot = accumulator.snapshot().unwrap().snapshot.unwrap();
+    assert!(snapshot.records_complete);
+    assert!(!snapshot.indexes_comparable);
+    assert!(snapshot.indexes.is_empty());
+    assert!(snapshot.observations.is_empty());
+    let wire = serde_json::to_value(snapshot).unwrap();
+    assert_eq!(wire["recordsComplete"], true);
+    assert_eq!(wire["indexesComparable"], false);
+    assert_eq!(wire["indexes"], serde_json::json!([]));
+    assert_eq!(wire["observations"], serde_json::json!([]));
+}
+
+#[test]
+fn stream_frames_are_immutable_fifo_and_do_not_bleed_forward() {
+    let accumulator = accumulator(51, "principal-a", "sha256:schema-a");
+    accumulator.begin_stream().unwrap();
+    let first = query_snapshot(&accumulator, "operation-a", 1);
+    let second = query_snapshot(&accumulator, "operation-a", 2);
+    accumulator
+        .record_query_metadata(
+            first.clone(),
+            Some(DistributedLiveMetadata {
+                supported: true,
+                reset: true,
+                cursors: vec![first.indexes[0].resume.clone().unwrap()],
+            }),
+        )
+        .unwrap();
+    accumulator
+        .record_query_metadata(
+            second.clone(),
+            Some(DistributedLiveMetadata {
+                supported: true,
+                reset: false,
+                cursors: vec![second.indexes[0].resume.clone().unwrap()],
+            }),
+        )
+        .unwrap();
+
+    let mut first_response = Response::new(Value::Null);
+    let mut second_response = Response::new(Value::Null);
+    let mut trailing_response = Response::new(Value::Null);
+    accumulator.attach(&mut first_response).unwrap();
+    accumulator.attach(&mut second_response).unwrap();
+    accumulator.attach(&mut trailing_response).unwrap();
+
+    let first_json = first_response.extensions["distributed"]
+        .clone()
+        .into_json()
+        .unwrap();
+    let second_json = second_response.extensions["distributed"]
+        .clone()
+        .into_json()
+        .unwrap();
+    let trailing_json = trailing_response.extensions["distributed"]
+        .clone()
+        .into_json()
+        .unwrap();
+    assert_eq!(first_json["snapshot"]["indexes"][0]["position"], "1");
+    assert_eq!(first_json["live"]["reset"], true);
+    assert_eq!(second_json["snapshot"]["indexes"][0]["position"], "2");
+    assert_eq!(second_json["live"]["reset"], false);
+    assert!(trailing_json.get("snapshot").is_none());
+    assert!(trailing_json.get("live").is_none());
+}
diff --git a/src/graphql/protocol/token.rs b/src/graphql/protocol/token.rs
new file mode 100644
index 00000000..635fa83a
--- /dev/null
+++ b/src/graphql/protocol/token.rs
@@ -0,0 +1,241 @@
+use std::fmt;
+
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use base64::Engine as _;
+use hmac::{Hmac, Mac};
+use serde::{Deserialize, Serialize};
+use sha2::Sha256;
+
+use crate::graphql::client_manifest::DISTRIBUTED_CLIENT_PROTOCOL_VERSION;
+
+const TOKEN_FORMAT_VERSION: &str = "v1";
+const TOKEN_MAC_BYTES: usize = 32;
+const TOKEN_DOMAIN: &[u8] = b"distributed.graphql.protocol-token";
+const MAX_TOKEN_MATERIAL_BYTES: usize = 1024 * 1024;
+const MAX_OPAQUE_TOKEN_BYTES: usize = 128;
+
+/// Maximum resumable projector partitions carried in one live operation.
+/// Request parsing and response generation share this bound so the server
+/// never emits a cursor set that a conforming client must reject.
+pub(crate) const MAX_LIVE_RESUME_CURSORS: usize = 64;
+
+/// One server-owned token. Its string contents have no public structure.
+#[derive(Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+pub(crate) struct OpaqueProtocolToken(pub(super) String);
+
+impl OpaqueProtocolToken {
+    pub(crate) fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    /// Parse one bounded framework token supplied back by a client.
+    ///
+    /// This validates only the canonical outer representation. Callers must
+    /// still verify its purpose and server-owned material before using it.
+    pub(crate) fn parse(value: &str) -> Result<Self, ProtocolTokenError> {
+        if value.is_empty() || value.len() > MAX_OPAQUE_TOKEN_BYTES {
+            return Err(ProtocolTokenError::Malformed);
+        }
+        let mut segments = value.split('.');
+        let version = segments.next().ok_or(ProtocolTokenError::Malformed)?;
+        let purpose = segments.next().ok_or(ProtocolTokenError::Malformed)?;
+        let encoded_mac = segments.next().ok_or(ProtocolTokenError::Malformed)?;
+        if segments.next().is_some()
+            || version != TOKEN_FORMAT_VERSION
+            || ProtocolTokenPurpose::from_label(purpose).is_none()
+        {
+            return Err(ProtocolTokenError::Malformed);
+        }
+        let supplied = URL_SAFE_NO_PAD
+            .decode(encoded_mac)
+            .map_err(|_| ProtocolTokenError::Malformed)?;
+        if supplied.len() != TOKEN_MAC_BYTES || URL_SAFE_NO_PAD.encode(&supplied) != encoded_mac {
+            return Err(ProtocolTokenError::Malformed);
+        }
+        Ok(Self(value.to_string()))
+    }
+}
+
+impl fmt::Debug for OpaqueProtocolToken {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("OpaqueProtocolToken([redacted])")
+    }
+}
+
+/// Domain separation for tokens that are intentionally not interchangeable.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum ProtocolTokenPurpose {
+    CacheScope,
+    ProjectionObligation,
+    ProjectionObservation,
+    RecordRevision,
+    QuerySnapshot,
+    QueryIndex,
+    LiveResume,
+}
+
+impl ProtocolTokenPurpose {
+    const fn label(self) -> &'static str {
+        match self {
+            Self::CacheScope => "cache-scope",
+            Self::ProjectionObligation => "projection-obligation",
+            Self::ProjectionObservation => "projection-observation",
+            Self::RecordRevision => "record-revision",
+            Self::QuerySnapshot => "query-snapshot",
+            Self::QueryIndex => "query-index",
+            Self::LiveResume => "live-resume",
+        }
+    }
+
+    fn from_label(value: &str) -> Option<Self> {
+        match value {
+            "cache-scope" => Some(Self::CacheScope),
+            "projection-obligation" => Some(Self::ProjectionObligation),
+            "projection-observation" => Some(Self::ProjectionObservation),
+            "record-revision" => Some(Self::RecordRevision),
+            "query-snapshot" => Some(Self::QuerySnapshot),
+            "query-index" => Some(Self::QueryIndex),
+            "live-resume" => Some(Self::LiveResume),
+            _ => None,
+        }
+    }
+}
+
+/// Stable deployment key for deterministic opaque protocol tokens.
+///
+/// The key is deliberately exact-sized and redacted from `Debug`. Deployments
+/// must preserve it across replicas and restarts whenever they want existing
+/// cache/resume tokens to remain comparable.
+#[derive(Clone)]
+pub(crate) struct ProtocolTokenCodec {
+    key: [u8; 32],
+}
+
+impl ProtocolTokenCodec {
+    pub(crate) fn new(key: [u8; 32]) -> Self {
+        Self { key }
+    }
+
+    /// Mint a deterministic token from a canonical serialization.
+    ///
+    /// Callers must use structs, tuples, ordered maps, or already-canonical
+    /// protocol values. Unordered application maps are not accepted protocol
+    /// material.
+    pub(crate) fn issue<T: Serialize>(
+        &self,
+        purpose: ProtocolTokenPurpose,
+        material: &T,
+    ) -> Result<OpaqueProtocolToken, ProtocolTokenError> {
+        let bytes =
+            serde_json::to_vec(material).map_err(|_| ProtocolTokenError::InvalidMaterial)?;
+        self.issue_bytes(purpose, &bytes)
+    }
+
+    pub(crate) fn issue_bytes(
+        &self,
+        purpose: ProtocolTokenPurpose,
+        canonical_material: &[u8],
+    ) -> Result<OpaqueProtocolToken, ProtocolTokenError> {
+        if canonical_material.is_empty() || canonical_material.len() > MAX_TOKEN_MATERIAL_BYTES {
+            return Err(ProtocolTokenError::InvalidMaterial);
+        }
+        let digest = self.mac(purpose, canonical_material);
+        Ok(OpaqueProtocolToken(format!(
+            "{TOKEN_FORMAT_VERSION}.{}.{}",
+            purpose.label(),
+            URL_SAFE_NO_PAD.encode(digest)
+        )))
+    }
+
+    /// Verify a token against the expected purpose and canonical material.
+    ///
+    /// Tokens carry no plaintext payload, so successful verification proves
+    /// only equality with server-owned expected material.
+    pub(crate) fn verify<T: Serialize>(
+        &self,
+        token: &OpaqueProtocolToken,
+        purpose: ProtocolTokenPurpose,
+        material: &T,
+    ) -> Result<(), ProtocolTokenError> {
+        let bytes =
+            serde_json::to_vec(material).map_err(|_| ProtocolTokenError::InvalidMaterial)?;
+        self.verify_bytes(token, purpose, &bytes)
+    }
+
+    pub(crate) fn verify_bytes(
+        &self,
+        token: &OpaqueProtocolToken,
+        purpose: ProtocolTokenPurpose,
+        canonical_material: &[u8],
+    ) -> Result<(), ProtocolTokenError> {
+        if canonical_material.is_empty() || canonical_material.len() > MAX_TOKEN_MATERIAL_BYTES {
+            return Err(ProtocolTokenError::InvalidMaterial);
+        }
+        let mut segments = token.as_str().split('.');
+        let version = segments.next().ok_or(ProtocolTokenError::Malformed)?;
+        let encoded_purpose = segments.next().ok_or(ProtocolTokenError::Malformed)?;
+        let encoded_mac = segments.next().ok_or(ProtocolTokenError::Malformed)?;
+        if segments.next().is_some()
+            || version != TOKEN_FORMAT_VERSION
+            || encoded_purpose != purpose.label()
+        {
+            return Err(ProtocolTokenError::Malformed);
+        }
+        let supplied = URL_SAFE_NO_PAD
+            .decode(encoded_mac)
+            .map_err(|_| ProtocolTokenError::Malformed)?;
+        if supplied.len() != TOKEN_MAC_BYTES {
+            return Err(ProtocolTokenError::Malformed);
+        }
+        let mut mac =
+            Hmac::<Sha256>::new_from_slice(&self.key).expect("HMAC-SHA256 accepts a 32-byte key");
+        update_mac(&mut mac, purpose, canonical_material);
+        mac.verify_slice(&supplied)
+            .map_err(|_| ProtocolTokenError::Mismatch)
+    }
+
+    fn mac(&self, purpose: ProtocolTokenPurpose, material: &[u8]) -> [u8; TOKEN_MAC_BYTES] {
+        let mut mac =
+            Hmac::<Sha256>::new_from_slice(&self.key).expect("HMAC-SHA256 accepts a 32-byte key");
+        update_mac(&mut mac, purpose, material);
+        mac.finalize().into_bytes().into()
+    }
+}
+
+impl fmt::Debug for ProtocolTokenCodec {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("ProtocolTokenCodec([redacted])")
+    }
+}
+
+fn update_mac(mac: &mut Hmac<Sha256>, purpose: ProtocolTokenPurpose, material: &[u8]) {
+    mac.update(TOKEN_DOMAIN);
+    mac.update(&DISTRIBUTED_CLIENT_PROTOCOL_VERSION.to_be_bytes());
+    update_segment(mac, purpose.label().as_bytes());
+    update_segment(mac, material);
+}
+
+fn update_segment(mac: &mut Hmac<Sha256>, value: &[u8]) {
+    mac.update(&(value.len() as u64).to_be_bytes());
+    mac.update(value);
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum ProtocolTokenError {
+    InvalidMaterial,
+    Malformed,
+    Mismatch,
+}
+
+impl fmt::Display for ProtocolTokenError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(match self {
+            Self::InvalidMaterial => "invalid protocol token material",
+            Self::Malformed => "malformed protocol token",
+            Self::Mismatch => "protocol token does not match the expected scope",
+        })
+    }
+}
+
+impl std::error::Error for ProtocolTokenError {}
diff --git a/src/graphql/protocol/types.rs b/src/graphql/protocol/types.rs
new file mode 100644
index 00000000..87ed92ae
--- /dev/null
+++ b/src/graphql/protocol/types.rs
@@ -0,0 +1,220 @@
+use serde::{Deserialize, Serialize};
+
+use crate::graphql::client_manifest::DISTRIBUTED_CLIENT_PROTOCOL_VERSION;
+
+use super::OpaqueProtocolToken;
+
+/// Stable command lifecycle vocabulary exposed to generated clients.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum DistributedCommandState {
+    InProgress,
+    Accepted,
+    AcceptedPendingProjection,
+    Projected,
+    Rejected,
+    ProjectionFailed,
+    Expired,
+    Unknown,
+}
+
+/// Typed Rust consistency guarantee, serialized independently of domain data.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum DistributedCommandConsistency {
+    Accepted,
+    Fact,
+    Projected,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct DistributedProjectionExpectation {
+    pub(crate) projection: String,
+    pub(crate) model: String,
+    pub(crate) scope_token: OpaqueProtocolToken,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct DistributedCommandMetadata {
+    pub(crate) command_id: String,
+    pub(crate) causation_id: String,
+    pub(crate) state: DistributedCommandState,
+    pub(crate) consistency: DistributedCommandConsistency,
+    pub(crate) expects: Vec<DistributedProjectionExpectation>,
+    /// Exact finite obligations already observed for this authorized command.
+    /// Tokens are identical to their matching `expects` entry, so the client
+    /// can retire optimism without reconstructing any hidden scope material.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub(crate) observations: Vec<DistributedProjectionObservation>,
+    /// Exact same-transaction revision evidence retained in the durable replay
+    /// envelope. Async commands leave this empty and confirm through expects.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub(crate) records: Vec<DistributedRecordRevision>,
+}
+
+/// Comparable revision for one record in a GraphQL response.
+///
+/// `scopeToken` is stable across operations and revisions but contains no
+/// model key, tenant, topology, or partition plaintext. Positions are decimal
+/// strings so JavaScript never coerces a future 64-bit value through `number`.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct DistributedRecordRevision {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) path: Option<Vec<String>>,
+    pub(crate) model: String,
+    pub(crate) scope_token: OpaqueProtocolToken,
+    pub(crate) incarnation: String,
+    pub(crate) revision: String,
+    pub(crate) tombstone: bool,
+}
+
+/// One causation observation whose scope token is byte-for-byte comparable to
+/// the corresponding command receipt obligation token.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct DistributedProjectionObservation {
+    pub(crate) causation_id: String,
+    pub(crate) projection: String,
+    pub(crate) model: String,
+    pub(crate) scope_token: OpaqueProtocolToken,
+}
+
+/// Client-returned live cursor. `projection` selects one finite, role-visible
+/// static projector scope; the token authenticates every hidden scope field,
+/// operation instance, generation, and position.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct DistributedLiveCursor {
+    pub(crate) projection: String,
+    pub(crate) position: String,
+    pub(crate) token: OpaqueProtocolToken,
+}
+
+/// Bounded interpretation of the optional client resume extension.
+///
+/// Malformed or unverifiable input is intentionally represented as `Invalid`
+/// rather than exposed as a request error: live execution must fall back to a
+/// fresh snapshot and must never merge against an untrusted cursor.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub(crate) enum RequestedLiveResume {
+    #[default]
+    Absent,
+    Invalid,
+    Cursors(Vec<DistributedLiveCursor>),
+}
+
+/// Comparable position for one projector/partition member of an exact query
+/// index snapshot. Positions from different `scopeToken`s are incomparable.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct DistributedIndexRevision {
+    pub(crate) projection: String,
+    pub(crate) scope_token: OpaqueProtocolToken,
+    pub(crate) position: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) resume: Option<DistributedLiveCursor>,
+}
+
+/// Evidence attached to one exact operation instance.
+///
+/// These two completeness dimensions are deliberately independent:
+///
+/// - `recordsComplete=false` means some returned normalized record lacks
+///   usable causal revision evidence.
+/// - `indexesComparable=false` means the server cannot expose one safe,
+///   complete projector-position vector for this authorized query.
+///
+/// A row-filtered query can therefore return complete authorized record
+/// evidence while keeping its partition-wide index positions private. Clients
+/// may treat that server-authorized payload as exact renderable membership, but
+/// must not use it for causal index comparison, live handoff/resume, local
+/// membership proofs, observations, or optimistic confirmation.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct DistributedQuerySnapshot {
+    pub(crate) scope_token: OpaqueProtocolToken,
+    pub(crate) records_complete: bool,
+    pub(crate) indexes_comparable: bool,
+    pub(crate) records: Vec<DistributedRecordRevision>,
+    pub(crate) indexes: Vec<DistributedIndexRevision>,
+    pub(crate) observations: Vec<DistributedProjectionObservation>,
+}
+
+impl DistributedQuerySnapshot {
+    pub(super) fn discard_incomparable_index_evidence(&mut self) {
+        if self.indexes_comparable {
+            return;
+        }
+        self.indexes.clear();
+        self.observations.clear();
+    }
+}
+
+/// Per-frame resumability decision for a live operation.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct DistributedLiveMetadata {
+    pub(crate) supported: bool,
+    pub(crate) reset: bool,
+    pub(crate) cursors: Vec<DistributedLiveCursor>,
+}
+
+/// One server-derived value for a descriptor already present in the selected
+/// static client surface. Values are valid only under this envelope's exact
+/// cache scope.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct DistributedTrustedPreset {
+    pub(crate) name: String,
+    pub(crate) codec: String,
+    pub(crate) value: serde_json::Value,
+}
+
+/// Canonical contents of GraphQL's top-level `extensions.distributed`.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct DistributedEnvelopeV1 {
+    pub(crate) protocol_version: u32,
+    pub(crate) schema_hash: String,
+    pub(crate) cache_scope: OpaqueProtocolToken,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) operation: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) command: Option<DistributedCommandMetadata>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) snapshot: Option<DistributedQuerySnapshot>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) live: Option<DistributedLiveMetadata>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub(crate) trusted_presets: Vec<DistributedTrustedPreset>,
+}
+
+impl DistributedEnvelopeV1 {
+    pub(crate) fn new(
+        schema_hash: impl Into<String>,
+        cache_scope: OpaqueProtocolToken,
+        operation: Option<String>,
+    ) -> Self {
+        Self {
+            protocol_version: DISTRIBUTED_CLIENT_PROTOCOL_VERSION,
+            schema_hash: schema_hash.into(),
+            cache_scope,
+            operation,
+            command: None,
+            snapshot: None,
+            live: None,
+            trusted_presets: Vec::new(),
+        }
+    }
+
+    pub(crate) fn with_trusted_presets(
+        mut self,
+        trusted_presets: Vec<DistributedTrustedPreset>,
+    ) -> Self {
+        self.trusted_presets = trusted_presets;
+        self
+    }
+}
diff --git a/src/graphql/query_protocol.rs b/src/graphql/query_protocol.rs
new file mode 100644
index 00000000..e5849279
--- /dev/null
+++ b/src/graphql/query_protocol.rs
@@ -0,0 +1,1063 @@
+//! Compiler-owned projection topology used to attach safe query/live evidence.
+//!
+//! This module never derives a projector partition from returned values. A
+//! record key may recover its unique durable scope through Task 15 metadata,
+//! while resumable index scopes are limited to Unit/Constant projectors whose
+//! partition exists even for an empty query result.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::sync::Arc;
+
+use async_graphql::Value;
+#[cfg(any(feature = "sqlite", feature = "postgres"))]
+use sqlx::{Encode, Executor, IntoArguments, Type};
+
+use super::compile::{ExtractedQueryEvidence, QueryResponsePathSegment, SqlPlan};
+use super::engine::EngineInner;
+#[cfg(any(feature = "sqlite", feature = "postgres"))]
+use super::engine::GraphqlPool;
+#[cfg(any(feature = "sqlite", feature = "postgres"))]
+use super::execute;
+use super::protocol::{
+    DistributedIndexRevision, DistributedLiveMetadata, DistributedQuerySnapshot,
+    DistributedRecordRevision, ProtocolResponseAccumulator, RequestedLiveResume,
+    MAX_LIVE_RESUME_CURSORS,
+};
+use super::surface::{Surface, SurfaceRowPolicy};
+use crate::projection_protocol::{
+    CompiledProjectionTopology, ProjectionChangeCursor, ProjectionChangeRead, ProjectionEpoch,
+    ProjectionLiveRecordBatchRequest, ProjectionLiveRecordRequest, ProjectionPartition,
+    ProjectionPartitionSnapshot, ProjectionPartitionSpec, ProjectionProtocolError,
+    ProjectionScopeCodec,
+};
+#[cfg(any(feature = "sqlite", feature = "postgres"))]
+use crate::sqlx_repo::projection_protocol::{
+    read_projection_changes_in_executor, read_projection_live_record_batch_in_executor,
+    read_projection_partition_snapshot_in_executor, with_projection_read_snapshot,
+};
+#[cfg(any(feature = "sqlite", feature = "postgres"))]
+use crate::sqlx_repo::repo::SqlxRepoBackend;
+
+#[derive(Clone, Debug)]
+pub(crate) struct QueryProjectorRuntime {
+    pub(crate) name: String,
+    pub(crate) codec: Arc<ProjectionScopeCodec>,
+    pub(crate) static_partition: Option<ProjectionPartition>,
+    pub(crate) change_epoch: Option<ProjectionEpoch>,
+    models: BTreeSet<String>,
+    dependencies: BTreeSet<String>,
+}
+
+impl QueryProjectorRuntime {
+    pub(crate) fn supports_resume(&self) -> bool {
+        self.static_partition.is_some() && self.change_epoch.is_some()
+    }
+
+    /// A partition-wide change cursor is safe to expose only when every model
+    /// sharing that projector partition is visible without row filtering on
+    /// this exact authorization surface. Otherwise positions, causations, and
+    /// tombstones could reveal activity from denied rows or models.
+    fn partition_matches_authorization(&self, surface: &Surface) -> bool {
+        self.models.iter().all(|model| {
+            surface
+                .models
+                .get(model)
+                .is_some_and(|model| matches!(model.row_policy, SurfaceRowPolicy::Unrestricted))
+        })
+    }
+}
+
+/// Full, authorization-independent topology compiled from complete schemas.
+/// Role selection only filters these already-compiled projector identities.
+#[derive(Clone, Debug, Default)]
+pub(crate) struct QueryProtocolRuntime {
+    projectors: BTreeMap<String, Arc<QueryProjectorRuntime>>,
+    model_owners: BTreeMap<String, Arc<QueryProjectorRuntime>>,
+    table_owners: BTreeMap<String, Arc<QueryProjectorRuntime>>,
+}
+
+#[derive(Clone, Debug, Default)]
+pub(crate) struct QueryIndexPlan {
+    pub(crate) comparable: bool,
+    pub(crate) projectors: Vec<Arc<QueryProjectorRuntime>>,
+}
+
+impl QueryProtocolRuntime {
+    pub(crate) fn compile(surface: &Surface) -> Result<Self, String> {
+        let mut runtime = Self::default();
+        for projector in &surface.projectors {
+            let schemas = projector
+                .models
+                .iter()
+                .map(|model| {
+                    surface
+                        .models
+                        .get(model)
+                        .map(|model| &model.schema)
+                        .ok_or_else(|| {
+                            format!(
+                                "query protocol projector `{}` references unknown model `{model}`",
+                                projector.name
+                            )
+                        })
+                })
+                .collect::<Result<Vec<_>, _>>()?;
+            let compiled = CompiledProjectionTopology::compile(
+                &projector.name,
+                &projector.facts,
+                &projector.models,
+                &projector.partition,
+                schemas,
+            )
+            .map_err(|error| {
+                format!(
+                    "query protocol projector `{}` cannot compile: {error}",
+                    projector.name
+                )
+            })?;
+            let codec = compiled.codec();
+            let static_partition = match &projector.partition {
+                ProjectionPartitionSpec::Unit => codec.encode_partition(None).map(Some),
+                ProjectionPartitionSpec::Constant { value } => {
+                    codec.encode_partition(Some(value)).map(Some)
+                }
+                ProjectionPartitionSpec::InputPath { .. } => Ok(None),
+            }
+            .map_err(|error| {
+                format!(
+                    "query protocol projector `{}` has invalid static partition: {error}",
+                    projector.name
+                )
+            })?;
+            let change_epoch = projector
+                .change_epoch
+                .as_deref()
+                .map(ProjectionEpoch::new)
+                .transpose()
+                .map_err(|error| {
+                    format!(
+                        "query protocol projector `{}` has invalid change epoch: {error}",
+                        projector.name
+                    )
+                })?;
+            let projection = Arc::new(QueryProjectorRuntime {
+                name: projector.name.clone(),
+                codec,
+                static_partition,
+                change_epoch,
+                models: projector.models.iter().cloned().collect(),
+                dependencies: projector.dependencies.iter().cloned().collect(),
+            });
+
+            for model in &projector.models {
+                if let Some(existing) = runtime
+                    .model_owners
+                    .insert(model.clone(), Arc::clone(&projection))
+                {
+                    return Err(format!(
+                        "query protocol model `{model}` has ambiguous owners `{}` and `{}`",
+                        existing.name, projector.name
+                    ));
+                }
+                let table = surface
+                    .models
+                    .get(model)
+                    .expect("compiled projector model exists")
+                    .table_name
+                    .clone();
+                if let Some(existing) = runtime
+                    .table_owners
+                    .insert(table.clone(), Arc::clone(&projection))
+                {
+                    return Err(format!(
+                        "query protocol table `{table}` has ambiguous owners `{}` and `{}`",
+                        existing.name, projector.name
+                    ));
+                }
+            }
+            runtime
+                .projectors
+                .insert(projector.name.clone(), projection);
+        }
+        Ok(runtime)
+    }
+
+    pub(crate) fn visible_model_owner(
+        &self,
+        role_surface: &Surface,
+        model: &str,
+    ) -> Option<Arc<QueryProjectorRuntime>> {
+        let owner = self.model_owners.get(model)?;
+        role_surface
+            .projectors
+            .iter()
+            .any(|projector| projector.name == owner.name)
+            .then(|| Arc::clone(owner))
+    }
+
+    /// Build one conservative vector over every physical dependency touched by
+    /// an exact query plan. Missing, denied, dynamic, epochless, or ambiguous
+    /// ownership makes the vector incomparable; no scalar maximum is invented.
+    pub(crate) fn index_plan(&self, role_surface: &Surface, tables: &[String]) -> QueryIndexPlan {
+        if tables.is_empty() {
+            return QueryIndexPlan::default();
+        }
+        let visible = role_surface
+            .projectors
+            .iter()
+            .map(|projector| projector.name.as_str())
+            .collect::<BTreeSet<_>>();
+        let mut selected = BTreeMap::<String, Arc<QueryProjectorRuntime>>::new();
+        for table in tables {
+            let candidates = self
+                .projectors
+                .values()
+                .filter(|projector| {
+                    visible.contains(projector.name.as_str())
+                        && projector.dependencies.contains(table)
+                })
+                .cloned()
+                .collect::<Vec<_>>();
+            let [candidate] = candidates.as_slice() else {
+                return QueryIndexPlan {
+                    comparable: false,
+                    projectors: Vec::new(),
+                };
+            };
+            if !candidate.supports_resume()
+                || !candidate.partition_matches_authorization(role_surface)
+            {
+                return QueryIndexPlan {
+                    comparable: false,
+                    projectors: Vec::new(),
+                };
+            }
+            selected.insert(candidate.name.clone(), Arc::clone(candidate));
+        }
+        QueryIndexPlan {
+            comparable: true,
+            projectors: selected.into_values().collect(),
+        }
+    }
+
+    #[allow(dead_code)]
+    pub(crate) fn is_empty(&self) -> bool {
+        self.projectors.is_empty()
+    }
+}
+
+pub(crate) struct ProtocolQueryExecution {
+    pub(crate) value: Value,
+    pub(crate) snapshot: DistributedQuerySnapshot,
+    pub(crate) live: Option<DistributedLiveMetadata>,
+}
+
+struct PreparedRecordProbe {
+    request: ProjectionLiveRecordRequest,
+    paths: Vec<Vec<String>>,
+}
+
+struct PreparedQueryEvidence {
+    records_complete: bool,
+    records: Vec<PreparedRecordProbe>,
+    indexes: QueryIndexPlan,
+}
+
+const MAX_PROTOCOL_EVIDENCE_ITEMS: usize = 4_096;
+
+struct PreparedLiveChange {
+    projection: String,
+    change: crate::projection_protocol::ProjectionChange,
+}
+
+struct PreparedLiveMetadata {
+    metadata: DistributedLiveMetadata,
+    changes: Vec<PreparedLiveChange>,
+}
+
+/// Execute the physical query and all record/index evidence reads inside one
+/// adapter snapshot. The returned GraphQL value has already had every hidden
+/// compiler key removed.
+#[cfg(any(feature = "sqlite", feature = "postgres"))]
+pub(crate) async fn execute_query_with_protocol(
+    inner: &EngineInner,
+    role_surface: Arc<Surface>,
+    accumulator: ProtocolResponseAccumulator,
+    plan: &SqlPlan,
+    live_resume: Option<RequestedLiveResume>,
+) -> Result<ProtocolQueryExecution, String> {
+    #[derive(serde::Serialize)]
+    struct QueryPlanInstance<'a> {
+        domain: &'static str,
+        version: u32,
+        sql: &'a str,
+        binds: &'a [super::compile::BindValue],
+        tables: &'a [String],
+    }
+
+    // Query and subscription documents retain distinct public operation
+    // hashes, but matching compiler plans share one comparable snapshot scope.
+    // This prevents a lagging refresh from being treated as authoritative over
+    // a newer live frame merely because the transport operation differs.
+    accumulator
+        .bind_query_snapshot_scope(&QueryPlanInstance {
+            domain: "distributed.graphql.query-plan-instance",
+            version: 1,
+            sql: &plan.sql,
+            binds: &plan.binds,
+            tables: &plan.tables_touched,
+        })
+        .map_err(|error| format!("query snapshot scope failed: {error}"))?;
+
+    // The snapshot helper accepts an HRTB closure whose returned future may
+    // borrow only its connection. Keep every other input owned by the closure
+    // so plan/runtime references cannot escape into that future.
+    let plan = plan.clone();
+    let runtime = inner.query_protocol.clone();
+    let statement_timeout = inner.statement_timeout;
+    match &inner.pool {
+        #[cfg(feature = "sqlite")]
+        GraphqlPool::Sqlite(pool) => {
+            let run = with_projection_read_snapshot(pool, move |connection| {
+                let role_surface = Arc::clone(&role_surface);
+                let accumulator = accumulator.clone();
+                let plan = plan.clone();
+                let runtime = runtime.clone();
+                let live_resume = live_resume.clone();
+                Box::pin(async move {
+                    let executed = execute::execute_sqlite_in_connection(connection, &plan)
+                        .await
+                        .map_err(query_execution_error)?;
+                    finish_protocol_query::<sqlx::Sqlite>(
+                        connection,
+                        &runtime,
+                        &role_surface,
+                        &accumulator,
+                        &plan,
+                        executed,
+                        live_resume,
+                    )
+                    .await
+                })
+            });
+            execute::apply_statement_timeout(statement_timeout, async {
+                run.await.map_err(|error| error.to_string())
+            })
+            .await
+        }
+        #[cfg(feature = "postgres")]
+        GraphqlPool::Postgres(pool) => {
+            let run = with_projection_read_snapshot(pool, move |connection| {
+                let role_surface = Arc::clone(&role_surface);
+                let accumulator = accumulator.clone();
+                let plan = plan.clone();
+                let runtime = runtime.clone();
+                let live_resume = live_resume.clone();
+                Box::pin(async move {
+                    let timeout_ms =
+                        i64::try_from(statement_timeout.as_millis()).unwrap_or(i64::MAX);
+                    sqlx::query(sqlx::AssertSqlSafe(format!(
+                        "SET LOCAL statement_timeout = '{timeout_ms}ms'"
+                    )))
+                    .execute(&mut *connection)
+                    .await
+                    .map_err(|error| {
+                        query_execution_error(format!("statement_timeout: {error}"))
+                    })?;
+                    let executed = execute::execute_postgres_in_connection(connection, &plan)
+                        .await
+                        .map_err(query_execution_error)?;
+                    finish_protocol_query::<sqlx::Postgres>(
+                        connection,
+                        &runtime,
+                        &role_surface,
+                        &accumulator,
+                        &plan,
+                        executed,
+                        live_resume,
+                    )
+                    .await
+                })
+            });
+            execute::apply_statement_timeout(statement_timeout, async {
+                run.await.map_err(|error| error.to_string())
+            })
+            .await
+        }
+        #[allow(unreachable_patterns)]
+        _ => Err("no database pool available for GraphQL execution".into()),
+    }
+}
+
+#[cfg(not(any(feature = "sqlite", feature = "postgres")))]
+pub(crate) async fn execute_query_with_protocol(
+    _inner: &EngineInner,
+    _role_surface: Arc<Surface>,
+    _accumulator: ProtocolResponseAccumulator,
+    _plan: &SqlPlan,
+    _live_resume: Option<RequestedLiveResume>,
+) -> Result<ProtocolQueryExecution, String> {
+    Err("no database pool available for GraphQL execution".into())
+}
+
+#[cfg(any(feature = "sqlite", feature = "postgres"))]
+fn query_execution_error(error: String) -> ProjectionProtocolError {
+    ProjectionProtocolError::InvalidBatch(format!("GraphQL query snapshot failed: {error}"))
+}
+
+#[cfg(any(feature = "sqlite", feature = "postgres"))]
+async fn finish_protocol_query<DB>(
+    connection: &mut DB::Connection,
+    runtime: &QueryProtocolRuntime,
+    role_surface: &Surface,
+    accumulator: &ProtocolResponseAccumulator,
+    plan: &SqlPlan,
+    executed: execute::ExecutedSql,
+    live_resume: Option<RequestedLiveResume>,
+) -> Result<ProtocolQueryExecution, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let prepared = prepare_query_evidence(runtime, role_surface, plan, executed.evidence)?;
+    // Store evidence batches are deliberately capped at 128 to bound one SQL
+    // statement. A query snapshot may carry up to 4,096 records, so read it in
+    // bounded chunks inside this same database snapshot and preserve positional
+    // alignment for the final wire envelope.
+    let mut record_metadata = Vec::with_capacity(prepared.records.len());
+    for records in prepared
+        .records
+        .chunks(crate::projection_protocol::MAX_PROJECTION_EVIDENCE_BATCH_ITEMS)
+    {
+        let record_batch = ProjectionLiveRecordBatchRequest::new(
+            records
+                .iter()
+                .map(|record| record.request.clone())
+                .collect(),
+        )?;
+        let batch =
+            read_projection_live_record_batch_in_executor::<DB>(connection, &record_batch).await?;
+        record_metadata.extend(batch.records);
+    }
+
+    let mut partitions = Vec::with_capacity(prepared.indexes.projectors.len());
+    for projector in &prepared.indexes.projectors {
+        let partition = projector
+            .static_partition
+            .as_ref()
+            .expect("comparable index plans retain a static partition");
+        let epoch = projector
+            .change_epoch
+            .as_ref()
+            .expect("comparable index plans retain a change epoch");
+        partitions.push(
+            read_projection_partition_snapshot_in_executor::<DB>(
+                connection,
+                projector.codec.topology(),
+                partition,
+                epoch,
+            )
+            .await?,
+        );
+    }
+
+    let (live, live_changes) = match live_resume {
+        Some(requested) => {
+            let prepared_live = wire_live_metadata::<DB>(
+                connection,
+                accumulator,
+                &prepared,
+                &partitions,
+                requested,
+            )
+            .await?;
+            (Some(prepared_live.metadata), prepared_live.changes)
+        }
+        None => (None, Vec::new()),
+    };
+    let snapshot = wire_query_snapshot(
+        accumulator,
+        prepared,
+        record_metadata,
+        partitions,
+        live_changes,
+    )?;
+    Ok(ProtocolQueryExecution {
+        value: executed.value,
+        snapshot,
+        live,
+    })
+}
+
+fn prepare_query_evidence(
+    runtime: &QueryProtocolRuntime,
+    role_surface: &Surface,
+    plan: &SqlPlan,
+    extracted: ExtractedQueryEvidence,
+) -> Result<PreparedQueryEvidence, ProjectionProtocolError> {
+    let mut records_complete = extracted.complete;
+    let mut records = Vec::<PreparedRecordProbe>::new();
+    let mut identities = BTreeMap::<(String, String, [u8; 32], Vec<u8>), usize>::new();
+
+    for record in extracted.records {
+        let Some(owner) = runtime.visible_model_owner(role_surface, &record.model) else {
+            records_complete = false;
+            continue;
+        };
+        let key = owner
+            .codec
+            .row_key_from_json_columns(&record.model, &record.key_columns)
+            .map_err(|error| {
+                ProjectionProtocolError::InvalidBatch(format!(
+                    "query evidence key for model `{}` is invalid: {error}",
+                    record.model
+                ))
+            })?;
+        let request = ProjectionLiveRecordRequest::new(&owner.codec, &record.model, key)?;
+        let identity = (
+            owner.name.clone(),
+            record.model,
+            request.canonical_key_hash,
+            request.canonical_key_bytes.clone(),
+        );
+        let path = record
+            .response_path
+            .into_iter()
+            .map(|segment| match segment {
+                QueryResponsePathSegment::Field(field) => field,
+                QueryResponsePathSegment::Index(index) => index.to_string(),
+            })
+            .collect::<Vec<_>>();
+        match identities.get(&identity).copied() {
+            Some(index) => records[index].paths.push(path),
+            None => {
+                identities.insert(identity, records.len());
+                records.push(PreparedRecordProbe {
+                    request,
+                    paths: vec![path],
+                });
+            }
+        }
+    }
+
+    let mut indexes = runtime.index_plan(role_surface, &plan.tables_touched);
+    if !query_index_budget_allows(indexes.projectors.len()) {
+        indexes.projectors.clear();
+        indexes.comparable = false;
+    }
+    Ok(PreparedQueryEvidence {
+        records_complete,
+        records,
+        indexes,
+    })
+}
+
+#[cfg(any(feature = "sqlite", feature = "postgres"))]
+async fn wire_live_metadata<DB>(
+    connection: &mut DB::Connection,
+    accumulator: &ProtocolResponseAccumulator,
+    prepared: &PreparedQueryEvidence,
+    partitions: &[ProjectionPartitionSnapshot],
+    requested: RequestedLiveResume,
+) -> Result<PreparedLiveMetadata, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    if partitions.len() != prepared.indexes.projectors.len() {
+        return Err(ProjectionProtocolError::InvalidBatch(
+            "query live adapter response length mismatch".into(),
+        ));
+    }
+    if !prepared.indexes.comparable
+        || prepared.indexes.projectors.is_empty()
+        || !live_resume_cursor_budget_allows(prepared.indexes.projectors.len())
+    {
+        return Ok(PreparedLiveMetadata {
+            metadata: DistributedLiveMetadata {
+                supported: false,
+                reset: true,
+                cursors: Vec::new(),
+            },
+            changes: Vec::new(),
+        });
+    }
+
+    let snapshot_scope = accumulator
+        .query_snapshot_scope()
+        .map_err(|error| ProjectionProtocolError::InvalidBatch(error.to_string()))?;
+    let mut current = Vec::with_capacity(prepared.indexes.projectors.len());
+    for (projector, partition_snapshot) in prepared.indexes.projectors.iter().zip(partitions) {
+        let partition = projector
+            .static_partition
+            .as_ref()
+            .expect("comparable live plans retain a static partition");
+        let epoch = projector
+            .change_epoch
+            .as_ref()
+            .expect("comparable live plans retain a change epoch");
+        let position = partition_snapshot
+            .head
+            .as_ref()
+            .map(ProjectionChangeCursor::position)
+            .unwrap_or(0);
+        current.push(
+            accumulator
+                .issue_live_resume_position(
+                    &projector.name,
+                    &snapshot_scope,
+                    projector.codec.topology(),
+                    partition,
+                    epoch,
+                    position,
+                )
+                .map_err(|error| ProjectionProtocolError::InvalidBatch(error.to_string()))?,
+        );
+    }
+
+    let mut reset = matches!(requested, RequestedLiveResume::Invalid);
+    let mut replayed_changes = Vec::new();
+    if let RequestedLiveResume::Cursors(supplied) = requested {
+        let mut supplied_by_projection = BTreeMap::new();
+        for cursor in supplied {
+            let projection = cursor.projection.clone();
+            if supplied_by_projection.insert(projection, cursor).is_some() {
+                reset = true;
+            }
+        }
+        if supplied_by_projection.len() != prepared.indexes.projectors.len() {
+            reset = true;
+        }
+
+        // Validate the complete cursor set before any change-log read. One
+        // invalid, missing, future, or duplicate cursor resets the whole
+        // logical snapshot; reading other partitions first would spend an
+        // attacker-amplifiable amount of work on evidence we must discard.
+        let mut validated = Vec::with_capacity(prepared.indexes.projectors.len());
+        for (projector, partition_snapshot) in prepared.indexes.projectors.iter().zip(partitions) {
+            let Some(supplied) = supplied_by_projection.remove(&projector.name) else {
+                reset = true;
+                continue;
+            };
+            let Ok(position) = supplied.position.parse::<u64>() else {
+                reset = true;
+                continue;
+            };
+            if position.to_string() != supplied.position {
+                reset = true;
+                continue;
+            }
+            let partition = projector
+                .static_partition
+                .as_ref()
+                .expect("comparable live plans retain a static partition");
+            let epoch = projector
+                .change_epoch
+                .as_ref()
+                .expect("comparable live plans retain a change epoch");
+            if accumulator
+                .verify_live_resume_position(
+                    &supplied,
+                    &snapshot_scope,
+                    &projector.name,
+                    projector.codec.topology(),
+                    partition,
+                    epoch,
+                    position,
+                )
+                .is_err()
+            {
+                reset = true;
+                continue;
+            }
+
+            let after = if position == 0 {
+                None
+            } else {
+                match ProjectionChangeCursor::new(
+                    projector.codec.topology().clone(),
+                    partition.clone(),
+                    epoch.clone(),
+                    position,
+                ) {
+                    Ok(cursor) => Some(cursor),
+                    Err(_) => {
+                        reset = true;
+                        continue;
+                    }
+                }
+            };
+            let current_position = partition_snapshot
+                .head
+                .as_ref()
+                .map(ProjectionChangeCursor::position)
+                .unwrap_or(0);
+            if position > current_position {
+                reset = true;
+                continue;
+            }
+            validated.push((
+                projector,
+                partition_snapshot,
+                after,
+                position,
+                current_position,
+            ));
+        }
+        if !supplied_by_projection.is_empty() {
+            reset = true;
+        }
+
+        let current_record_entries = prepared
+            .records
+            .iter()
+            .map(|record| record.paths.len())
+            .sum::<usize>();
+        if !reset {
+            for (projector, partition_snapshot, after, position, current_position) in validated {
+                if position == current_position {
+                    continue;
+                }
+                let remaining = MAX_PROTOCOL_EVIDENCE_ITEMS
+                    .saturating_sub(current_record_entries.saturating_add(replayed_changes.len()));
+                if remaining == 0 {
+                    reset = true;
+                    break;
+                }
+                let partition = projector
+                    .static_partition
+                    .as_ref()
+                    .expect("comparable live plans retain a static partition");
+                let read_limit = remaining.checked_add(1).unwrap_or(usize::MAX);
+                let read = read_projection_changes_in_executor::<DB>(
+                    connection,
+                    projector.codec.topology(),
+                    partition,
+                    after.as_ref(),
+                    read_limit,
+                )
+                .await?;
+                match read {
+                    ProjectionChangeRead::ResetRequired { .. } => {
+                        reset = true;
+                        break;
+                    }
+                    ProjectionChangeRead::Changes { head, changes, .. } => {
+                        let last_position = changes
+                            .last()
+                            .map(|change| change.cursor.position())
+                            .unwrap_or(position);
+                        if head != partition_snapshot.head
+                            || changes.len() > remaining
+                            || last_position != current_position
+                        {
+                            reset = true;
+                            break;
+                        }
+                        replayed_changes.extend(changes.into_iter().map(|change| {
+                            PreparedLiveChange {
+                                projection: projector.name.clone(),
+                                change,
+                            }
+                        }));
+                    }
+                }
+            }
+        }
+    }
+
+    if reset {
+        // A reset frame is a fresh authoritative snapshot. Never attach a
+        // partial or untrusted change-log suffix to data that the client must
+        // merge only after discarding its previous scoped state.
+        replayed_changes.clear();
+    }
+
+    Ok(PreparedLiveMetadata {
+        metadata: DistributedLiveMetadata {
+            supported: true,
+            reset,
+            cursors: current,
+        },
+        changes: replayed_changes,
+    })
+}
+
+fn live_resume_cursor_budget_allows(projector_count: usize) -> bool {
+    projector_count <= MAX_LIVE_RESUME_CURSORS
+}
+
+fn query_index_budget_allows(index_count: usize) -> bool {
+    index_count <= MAX_PROTOCOL_EVIDENCE_ITEMS
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn live_and_index_resume_budget_accepts_64_and_rejects_65() {
+        assert!(live_resume_cursor_budget_allows(MAX_LIVE_RESUME_CURSORS));
+        assert!(!live_resume_cursor_budget_allows(
+            MAX_LIVE_RESUME_CURSORS + 1
+        ));
+    }
+
+    #[test]
+    fn query_index_budget_accepts_4096_and_rejects_4097() {
+        assert!(query_index_budget_allows(MAX_PROTOCOL_EVIDENCE_ITEMS));
+        assert!(!query_index_budget_allows(MAX_PROTOCOL_EVIDENCE_ITEMS + 1));
+    }
+}
+
+fn wire_query_snapshot(
+    accumulator: &ProtocolResponseAccumulator,
+    mut prepared: PreparedQueryEvidence,
+    metadata: Vec<Option<crate::projection_protocol::ProjectionRecordMetadata>>,
+    partitions: Vec<ProjectionPartitionSnapshot>,
+    live_changes: Vec<PreparedLiveChange>,
+) -> Result<DistributedQuerySnapshot, ProjectionProtocolError> {
+    if metadata.len() != prepared.records.len()
+        || partitions.len() != prepared.indexes.projectors.len()
+    {
+        return Err(ProjectionProtocolError::InvalidBatch(
+            "query evidence adapter response length mismatch".into(),
+        ));
+    }
+    let snapshot_scope = accumulator
+        .query_snapshot_scope()
+        .map_err(|error| ProjectionProtocolError::InvalidBatch(error.to_string()))?;
+    let mut records = Vec::new();
+    let mut current_record_clocks = BTreeMap::<String, (u64, u64)>::new();
+    for (probe, metadata) in prepared.records.drain(..).zip(metadata) {
+        let Some(metadata) = metadata else {
+            prepared.records_complete = false;
+            continue;
+        };
+        let scope_token = accumulator
+            .issue_record_scope(metadata.revision.scope())
+            .map_err(|error| ProjectionProtocolError::InvalidBatch(error.to_string()))?;
+        current_record_clocks.insert(
+            scope_token.as_str().to_string(),
+            (
+                metadata.revision.incarnation(),
+                metadata.revision.revision(),
+            ),
+        );
+        for path in probe.paths {
+            if records.len() == MAX_PROTOCOL_EVIDENCE_ITEMS {
+                prepared.records_complete = false;
+                break;
+            }
+            records.push(DistributedRecordRevision {
+                path: Some(path),
+                model: metadata.revision.scope().model().to_string(),
+                scope_token: scope_token.clone(),
+                incarnation: metadata.revision.incarnation().to_string(),
+                revision: metadata.revision.revision().to_string(),
+                tombstone: metadata.tombstone,
+            });
+        }
+    }
+
+    let mut indexes = Vec::new();
+    let mut indexes_comparable = prepared.indexes.comparable;
+    let issue_index_resumes = live_resume_cursor_budget_allows(prepared.indexes.projectors.len());
+    for (projector, partition_snapshot) in prepared.indexes.projectors.into_iter().zip(partitions) {
+        if !query_index_budget_allows(indexes.len().saturating_add(1)) {
+            indexes_comparable = false;
+            break;
+        }
+        let partition = projector
+            .static_partition
+            .as_ref()
+            .expect("comparable index plans retain a static partition");
+        let epoch = projector
+            .change_epoch
+            .as_ref()
+            .expect("comparable index plans retain a change epoch");
+        let position = partition_snapshot
+            .head
+            .as_ref()
+            .map(|cursor| cursor.position())
+            .unwrap_or(0);
+        let scope_token = accumulator
+            .issue_index_scope_parts(
+                &snapshot_scope,
+                projector.codec.topology(),
+                partition,
+                epoch,
+            )
+            .map_err(|error| ProjectionProtocolError::InvalidBatch(error.to_string()))?;
+        let resume = if issue_index_resumes {
+            Some(
+                accumulator
+                    .issue_live_resume_position(
+                        &projector.name,
+                        &snapshot_scope,
+                        projector.codec.topology(),
+                        partition,
+                        epoch,
+                        position,
+                    )
+                    .map_err(|error| ProjectionProtocolError::InvalidBatch(error.to_string()))?,
+            )
+        } else {
+            None
+        };
+        indexes.push(DistributedIndexRevision {
+            projection: projector.name.clone(),
+            scope_token,
+            position: position.to_string(),
+            resume,
+        });
+    }
+
+    let mut observations = Vec::new();
+    let mut observation_tokens = BTreeSet::new();
+    let mut live_record_fences = BTreeMap::<String, ((u64, u64), DistributedRecordRevision)>::new();
+    for live in live_changes {
+        let change = live.change;
+        match change.kind {
+            crate::projection_protocol::ProjectionChangeKind::RecordUpsert
+            | crate::projection_protocol::ProjectionChangeKind::RecordDelete
+            | crate::projection_protocol::ProjectionChangeKind::RecordRecreate => {
+                let scope = change.scope.as_ref().ok_or_else(|| {
+                    ProjectionProtocolError::InvalidBatch(
+                        "live record change omitted its canonical scope".into(),
+                    )
+                })?;
+                let revision = change.revision.as_ref().ok_or_else(|| {
+                    ProjectionProtocolError::InvalidBatch(
+                        "live record change omitted its revision".into(),
+                    )
+                })?;
+                let record_scope_token = accumulator
+                    .issue_record_scope(scope)
+                    .map_err(|error| ProjectionProtocolError::InvalidBatch(error.to_string()))?;
+                let clock = (revision.incarnation(), revision.revision());
+                let wire_record = DistributedRecordRevision {
+                    path: None,
+                    model: scope.model().to_string(),
+                    scope_token: record_scope_token,
+                    incarnation: revision.incarnation().to_string(),
+                    revision: revision.revision().to_string(),
+                    tombstone: change.kind
+                        == crate::projection_protocol::ProjectionChangeKind::RecordDelete,
+                };
+                let scope_key = wire_record.scope_token.as_str().to_string();
+                match live_record_fences.get(&scope_key) {
+                    Some((existing, record)) if *existing > clock => {}
+                    Some((existing, record)) if *existing == clock => {
+                        if record.tombstone != wire_record.tombstone {
+                            return Err(ProjectionProtocolError::InvalidBatch(
+                                "one live record clock carried conflicting tombstone state".into(),
+                            ));
+                        }
+                    }
+                    _ => {
+                        live_record_fences.insert(scope_key, (clock, wire_record));
+                    }
+                }
+                let observation = super::protocol::DistributedProjectionObservation {
+                    causation_id: change.causation_id.clone(),
+                    projection: live.projection.clone(),
+                    model: scope.model().to_string(),
+                    scope_token: accumulator
+                        .issue_projection_obligation_scope(
+                            &change.causation_id,
+                            &live.projection,
+                            scope.model(),
+                            crate::projection_protocol::ProjectionObservationKind::Record,
+                            scope,
+                        )
+                        .map_err(|error| {
+                            ProjectionProtocolError::InvalidBatch(error.to_string())
+                        })?,
+                };
+                if observation_tokens.insert(observation.scope_token.as_str().to_string()) {
+                    observations.push(observation);
+                }
+            }
+            crate::projection_protocol::ProjectionChangeKind::Observation => {
+                let scope = change.scope.as_ref().ok_or_else(|| {
+                    ProjectionProtocolError::InvalidBatch(
+                        "live projection observation omitted its canonical scope".into(),
+                    )
+                })?;
+                let kind = change.observation_kind.ok_or_else(|| {
+                    ProjectionProtocolError::InvalidBatch(
+                        "live projection observation omitted its kind".into(),
+                    )
+                })?;
+                let observation = super::protocol::DistributedProjectionObservation {
+                    causation_id: change.causation_id.clone(),
+                    projection: live.projection.clone(),
+                    model: scope.model().to_string(),
+                    scope_token: accumulator
+                        .issue_projection_obligation_scope(
+                            &change.causation_id,
+                            &live.projection,
+                            scope.model(),
+                            kind,
+                            scope,
+                        )
+                        .map_err(|error| {
+                            ProjectionProtocolError::InvalidBatch(error.to_string())
+                        })?,
+                };
+                if observation_tokens.insert(observation.scope_token.as_str().to_string()) {
+                    observations.push(observation);
+                }
+            }
+            crate::projection_protocol::ProjectionChangeKind::Checkpoint
+            | crate::projection_protocol::ProjectionChangeKind::Failure => {}
+        }
+    }
+
+    for (scope, (clock, record)) in live_record_fences {
+        match current_record_clocks.get(&scope) {
+            Some(current) if *current == clock && !record.tombstone => continue,
+            Some(current) if *current >= clock => {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "live record suffix conflicts with current query-row evidence".into(),
+                ));
+            }
+            Some(_) => {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "current query-row evidence is older than its live suffix".into(),
+                ));
+            }
+            None => {}
+        }
+        if records.len() == MAX_PROTOCOL_EVIDENCE_ITEMS {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "live record evidence exceeded the bounded response budget".into(),
+            ));
+        }
+        records.push(record);
+    }
+
+    Ok(DistributedQuerySnapshot {
+        scope_token: snapshot_scope,
+        records_complete: prepared.records_complete,
+        indexes_comparable,
+        records,
+        indexes,
+        observations,
+    })
+}
diff --git a/src/graphql/schema.rs b/src/graphql/schema.rs
new file mode 100644
index 00000000..12e73ee3
--- /dev/null
+++ b/src/graphql/schema.rs
@@ -0,0 +1,1260 @@
+//! Per-role dynamic schema construction (async-graphql).
+#![allow(clippy::items_after_test_module, clippy::too_many_arguments)]
+
+use std::collections::BTreeMap;
+use std::sync::Arc;
+
+use async_graphql::dynamic::{
+    Enum, Field, FieldFuture, InputObject, InputValue, Object, Scalar, Schema, SchemaError, TypeRef,
+};
+use async_graphql::Value;
+
+use super::compile::{self, RootKind};
+use super::engine::EngineInner;
+use super::identity::VerifiedPrincipal;
+use super::naming::{
+    bool_exp_name, causal_protocol_type_names, comparison_exp_name, order_by_name,
+    COMMAND_STATUS_ROOT_FIELD, CUSTOM_SCALARS, DISTRIBUTED_COMMAND_STATE_TYPE,
+    DISTRIBUTED_COMMAND_STATE_VALUES, DISTRIBUTED_COMMAND_STATUS_TYPE,
+};
+use super::protocol::ProtocolResponseAccumulator;
+use super::surface::{
+    RootKind as SurfaceRootKind, Surface, SurfaceArgument, SurfaceCommandShape, SurfaceModel,
+    SurfaceTypeDef, SurfaceTypeField,
+};
+use crate::microsvc::Session;
+
+pub fn build_role_schema(
+    role_surface: &Surface,
+    max_depth: usize,
+    max_complexity: usize,
+    disable_introspection: bool,
+) -> Result<Schema, String> {
+    let has_causal_commands = !role_surface.commands.is_empty();
+    if has_causal_commands {
+        validate_causal_protocol_names(role_surface)?;
+    }
+
+    let mut query = Object::new("Query");
+    let mut registered_objects: BTreeMap<String, Object> = BTreeMap::new();
+    let mut registered_inputs: BTreeMap<String, InputObject> = BTreeMap::new();
+    let mut scalars_needed = std::collections::BTreeSet::<String>::new();
+
+    for scalar in CUSTOM_SCALARS {
+        scalars_needed.insert((*scalar).into());
+    }
+
+    // order_by enum as string scalar alternative — use InputObject with enum-like strings
+    // via TypeRef::named("order_by"). We'll register a scalar for simplicity in dynamic mode
+    // and accept enum values as strings. For fuller fidelity use Enum type.
+    let order_by_enum = async_graphql::dynamic::Enum::new("order_by")
+        .item("asc")
+        .item("asc_nulls_first")
+        .item("asc_nulls_last")
+        .item("desc")
+        .item("desc_nulls_first")
+        .item("desc_nulls_last");
+    let command_state_enum = has_causal_commands.then(|| {
+        let mut command_state = Enum::new(DISTRIBUTED_COMMAND_STATE_TYPE);
+        for state in DISTRIBUTED_COMMAND_STATE_VALUES {
+            command_state = command_state.item(*state);
+        }
+        command_state
+    });
+    if has_causal_commands {
+        let status = Object::new(DISTRIBUTED_COMMAND_STATUS_TYPE).field(Field::new(
+            "state",
+            TypeRef::named_nn(DISTRIBUTED_COMMAND_STATE_TYPE),
+            |ctx| FieldFuture::new(async move { schema_key_passthrough(&ctx, "state") }),
+        ));
+        registered_objects.insert(DISTRIBUTED_COMMAND_STATUS_TYPE.into(), status);
+    }
+
+    // Emit roots only for fields present on the role surface (IR inventory).
+    for root in &role_surface.query_fields {
+        let Some(model) = role_surface.models.get(&root.model_name) else {
+            continue;
+        };
+        let model_name = root.model_name.clone();
+        let obj_name = root.object.clone();
+
+        ensure_object_type(
+            &mut registered_objects,
+            &root.model_name,
+            role_surface,
+            &mut scalars_needed,
+        );
+        ensure_bool_exp(
+            &mut registered_inputs,
+            &root.model_name,
+            role_surface,
+            &mut scalars_needed,
+        );
+        ensure_order_by_input(&mut registered_inputs, model);
+
+        match root.kind {
+            SurfaceRootKind::List => {
+                let model_for_resolver = model_name.clone();
+                let list_field = with_field_arguments(
+                    Field::new(
+                        root.name.clone(),
+                        TypeRef::named_nn_list_nn(obj_name.clone()),
+                        move |ctx| {
+                            let model = model_for_resolver.clone();
+                            FieldFuture::new(async move {
+                                resolve_root(&ctx, &model, RootKind::List).await
+                            })
+                        },
+                    ),
+                    &root.arguments,
+                );
+                query = query.field(list_field);
+            }
+            SurfaceRootKind::ByPk => {
+                let model_for_pk = model_name.clone();
+                let mut pk_field = Field::new(
+                    root.name.clone(),
+                    TypeRef::named(obj_name.clone()),
+                    move |ctx| {
+                        let model = model_for_pk.clone();
+                        FieldFuture::new(
+                            async move { resolve_root(&ctx, &model, RootKind::ByPk).await },
+                        )
+                    },
+                );
+                pk_field = with_field_arguments(pk_field, &root.arguments);
+                query = query.field(pk_field);
+            }
+            SurfaceRootKind::Aggregate => {
+                let agg_type = root.name.clone();
+                ensure_aggregate_type(&mut registered_objects, model);
+                let model_for_agg = model_name.clone();
+                let agg_field = with_field_arguments(
+                    Field::new(root.name.clone(), TypeRef::named(agg_type), move |ctx| {
+                        let model = model_for_agg.clone();
+                        FieldFuture::new(async move {
+                            resolve_root(&ctx, &model, RootKind::Aggregate).await
+                        })
+                    }),
+                    &root.arguments,
+                );
+                query = query.field(agg_field);
+            }
+        }
+    }
+
+    // Comparison input types come from this exact role Surface instance.
+    // Only register when IR lists ops — never emit empty input objects.
+    for scalar in &scalars_needed {
+        if matches!(
+            scalar.as_str(),
+            "String" | "Boolean" | "BigInt" | "Float" | "JSON" | "Timestamptz" | "Bytea"
+        ) {
+            let scalar_name = scalar.as_str();
+            let name = comparison_exp_name(scalar_name);
+            let ops: Vec<String> = role_surface
+                .comparison_ops_for_scalar(scalar_name)
+                .into_iter()
+                .map(str::to_string)
+                .collect();
+            if ops.is_empty() {
+                continue;
+            }
+            registered_inputs.entry(name.clone()).or_insert_with(|| {
+                let mut input = InputObject::new(name);
+                for op in &ops {
+                    let ty = match op.as_str() {
+                        "_is_null" => TypeRef::named(TypeRef::BOOLEAN),
+                        "_in" | "_nin" => TypeRef::named_nn_list(scalar_name),
+                        "_has_key" => TypeRef::named("String"),
+                        _ => TypeRef::named(scalar_name),
+                    };
+                    input = input.field(InputValue::new(op.as_str(), ty));
+                }
+                input
+            });
+        }
+    }
+
+    // Empty-role Query must still define ≥1 field (async-graphql requirement).
+    // Spec: empty role → FORBIDDEN with extensions.code (no query surface).
+    if role_surface.query_fields.is_empty() && !has_causal_commands {
+        query = query.field(Field::new(
+            "_empty",
+            TypeRef::named_nn(TypeRef::BOOLEAN),
+            |_| {
+                FieldFuture::new(async {
+                    Err::<Option<Value>, _>(client_error("FORBIDDEN", "role has no GraphQL grants"))
+                })
+            },
+        ));
+    }
+    if has_causal_commands {
+        query = query.field(
+            Field::new(
+                COMMAND_STATUS_ROOT_FIELD,
+                TypeRef::named_nn(DISTRIBUTED_COMMAND_STATUS_TYPE),
+                |ctx| FieldFuture::new(async move { resolve_command_status(&ctx).await }),
+            )
+            .argument(InputValue::new("commandId", TypeRef::named_nn(TypeRef::ID))),
+        );
+    }
+
+    // Mutation root from commands
+    let mut mutation: Option<Object> = None;
+    if !role_surface.commands.is_empty() {
+        let mut mut_obj = Object::new("Mutation");
+        for cmd in &role_surface.commands {
+            let output_type = match &cmd.output {
+                SurfaceCommandShape::None => {
+                    return Err(format!(
+                        "command `{}` cannot declare an empty output",
+                        cmd.command_name
+                    ));
+                }
+                SurfaceCommandShape::Typed(t) => {
+                    ensure_command_output(&mut registered_objects, t);
+                    t.name.as_str()
+                }
+            };
+            let cmd_name = cmd.command_name.clone();
+            let mut field = Field::new(
+                cmd.field_name.clone(),
+                TypeRef::named_nn(output_type),
+                move |ctx| {
+                    let cmd_name = cmd_name.clone();
+                    FieldFuture::new(async move { resolve_command(&ctx, &cmd_name).await })
+                },
+            )
+            .argument(InputValue::new("commandId", TypeRef::named_nn(TypeRef::ID)));
+            match &cmd.input {
+                SurfaceCommandShape::None => {}
+                SurfaceCommandShape::Typed(tdef) => {
+                    // Register nested input type if needed
+                    ensure_command_input(&mut registered_inputs, tdef);
+                    field = field.argument(InputValue::new(
+                        "input",
+                        TypeRef::named_nn(tdef.name.as_str()),
+                    ));
+                }
+            }
+            mut_obj = mut_obj.field(field);
+        }
+        mutation = Some(mut_obj);
+    }
+
+    // Subscription root: live queries refreshed off ChangeHub (commit-path).
+    use async_graphql::dynamic::{Subscription, SubscriptionField, SubscriptionFieldFuture};
+    let mut subscription = Subscription::new("Subscription");
+    let mut has_subscription = false;
+    for sub_root in &role_surface.subscription_fields {
+        if !matches!(sub_root.kind, SurfaceRootKind::List) {
+            continue;
+        }
+        let Some(_model) = role_surface.models.get(&sub_root.model_name) else {
+            continue;
+        };
+        let model_for_sub = sub_root.model_name.clone();
+        let obj_name = sub_root.object.clone();
+        let field = with_subscription_arguments(
+            SubscriptionField::new(
+                sub_root.name.clone(),
+                TypeRef::named_nn_list_nn(obj_name),
+                move |ctx| {
+                    let model = model_for_sub.clone();
+                    // Extract owned data before the async block (stream is 'static).
+                    let inner = ctx.data_opt::<Arc<EngineInner>>().cloned();
+                    let session = ctx
+                        .data_opt::<Session>()
+                        .cloned()
+                        .unwrap_or_else(Session::new);
+                    let protocol = ctx.data_opt::<ProtocolResponseAccumulator>().cloned();
+                    let selection = compile::selection_from_field(ctx.field());
+                    SubscriptionFieldFuture::new(async move {
+                        let inner = inner.ok_or_else(|| {
+                            async_graphql::Error::new("GraphqlEngine not in request data")
+                        })?;
+                        let role = session
+                            .role()
+                            .map(|s| s.to_string())
+                            .unwrap_or_else(|| inner.anonymous_role.clone());
+                        let stream = super::subscribe::live_query_stream(
+                            inner, session, role, model, selection, protocol,
+                        )
+                        .await
+                        .map_err(async_graphql::Error::new)?;
+                        Ok(stream)
+                    })
+                },
+            ),
+            &sub_root.arguments,
+        );
+        subscription = subscription.field(field);
+        has_subscription = true;
+    }
+
+    let mut builder = if let Some(m) = mutation {
+        if has_subscription {
+            Schema::build(
+                query.type_name(),
+                Some(m.type_name()),
+                Some(subscription.type_name()),
+            )
+            .register(query)
+            .register(m)
+            .register(subscription)
+        } else {
+            Schema::build(query.type_name(), Some(m.type_name()), None)
+                .register(query)
+                .register(m)
+        }
+    } else if has_subscription {
+        Schema::build(query.type_name(), None, Some(subscription.type_name()))
+            .register(query)
+            .register(subscription)
+    } else {
+        Schema::build(query.type_name(), None, None).register(query)
+    };
+
+    builder = builder.register(order_by_enum);
+    if let Some(command_state_enum) = command_state_enum {
+        builder = builder.register(command_state_enum);
+    }
+    for name in CUSTOM_SCALARS {
+        builder = builder.register(Scalar::new(*name));
+    }
+    for (_, obj) in registered_objects {
+        builder = builder.register(obj);
+    }
+    for (_, input) in registered_inputs {
+        builder = builder.register(input);
+    }
+
+    let mut builder = builder
+        .limit_depth(max_depth)
+        .limit_complexity(max_complexity);
+    if disable_introspection {
+        builder = builder.disable_introspection();
+    }
+    builder.finish().map_err(|e: SchemaError| e.to_string())
+}
+
+fn validate_causal_protocol_names(surface: &Surface) -> Result<(), String> {
+    if surface
+        .query_fields
+        .iter()
+        .any(|root| root.name == COMMAND_STATUS_ROOT_FIELD)
+    {
+        return Err(format!(
+            "generated name `{COMMAND_STATUS_ROOT_FIELD}` collides with another type or field"
+        ));
+    }
+
+    for protocol_name in causal_protocol_type_names() {
+        let model_collision = surface.models.values().any(|model| {
+            model.object_name == protocol_name
+                || bool_exp_name(&model.schema) == protocol_name
+                || order_by_name(&model.schema) == protocol_name
+                || (model.aggregations
+                    && (format!("{}_aggregate", model.table_name) == protocol_name
+                        || format!("{}_aggregate_fields", model.table_name) == protocol_name))
+        });
+        let command_collision = surface.commands.iter().any(|command| {
+            command_shape_uses_type_name(&command.input, protocol_name)
+                || command_shape_uses_type_name(&command.output, protocol_name)
+        });
+        if surface.comparison_ops.contains_key(protocol_name)
+            || model_collision
+            || command_collision
+        {
+            return Err(format!(
+                "generated name `{protocol_name}` collides with a causal protocol type"
+            ));
+        }
+    }
+    Ok(())
+}
+
+fn command_shape_uses_type_name(shape: &SurfaceCommandShape, name: &str) -> bool {
+    match shape {
+        SurfaceCommandShape::None => false,
+        SurfaceCommandShape::Typed(definition) => command_type_uses_name(definition, name),
+    }
+}
+
+fn command_type_uses_name(definition: &SurfaceTypeDef, name: &str) -> bool {
+    definition.name == name
+        || definition.fields.iter().any(|field| {
+            field.type_name == name
+                || field
+                    .nested
+                    .as_deref()
+                    .is_some_and(|nested| command_type_uses_name(nested, name))
+        })
+}
+
+fn ensure_object_type(
+    objects: &mut BTreeMap<String, Object>,
+    model_name: &str,
+    surface: &Surface,
+    scalars: &mut std::collections::BTreeSet<String>,
+) {
+    let model = &surface.models[model_name];
+    let name = model.object_name.clone();
+    if objects.contains_key(&name) {
+        return;
+    }
+    // Break relationship cycles while nested object fields are registered.
+    objects.insert(name.clone(), Object::new(name.clone()));
+    let mut obj = Object::new(name.clone());
+    for column in &model.columns {
+        scalars.insert(column.scalar.clone());
+        let ty = if column.nullable {
+            TypeRef::named(column.scalar.as_str())
+        } else {
+            TypeRef::named_nn(column.scalar.as_str())
+        };
+        let key = column.name.clone();
+        obj = obj.field(Field::new(column.name.as_str(), ty, move |ctx| {
+            let key = key.clone();
+            FieldFuture::new(async move { response_key_passthrough(&ctx, &key) })
+        }));
+    }
+    for relationship in &model.relationships {
+        let Some(target) = surface.models.get(&relationship.target_model) else {
+            continue;
+        };
+        let target_obj = target.object_name.clone();
+        ensure_object_type(objects, &relationship.target_model, surface, scalars);
+        let key = relationship.name.clone();
+        if relationship.list {
+            let field = with_field_arguments(
+                Field::new(
+                    relationship.name.as_str(),
+                    TypeRef::named_nn_list_nn(target_obj),
+                    move |ctx| {
+                        let key = key.clone();
+                        FieldFuture::new(async move { response_key_passthrough(&ctx, &key) })
+                    },
+                ),
+                &relationship.arguments,
+            );
+            obj = obj.field(field);
+            if let Some(aggregate_plan) = &relationship.aggregate {
+                ensure_aggregate_type(objects, target);
+                let aggregate_name = aggregate_plan.name.clone();
+                let aggregate_type = aggregate_plan.type_name.clone();
+                let field_key = aggregate_name.clone();
+                let aggregate = with_field_arguments(
+                    Field::new(aggregate_name, TypeRef::named(aggregate_type), move |ctx| {
+                        let key = field_key.clone();
+                        FieldFuture::new(async move { response_key_passthrough(&ctx, &key) })
+                    }),
+                    &aggregate_plan.arguments,
+                );
+                obj = obj.field(aggregate);
+            }
+        } else {
+            let ty = if relationship.nullable {
+                TypeRef::named(target_obj)
+            } else {
+                TypeRef::named_nn(target_obj)
+            };
+            obj = obj.field(Field::new(relationship.name.as_str(), ty, move |ctx| {
+                let key = key.clone();
+                FieldFuture::new(async move { response_key_passthrough(&ctx, &key) })
+            }));
+        }
+    }
+    objects.insert(name, obj);
+}
+
+fn ensure_bool_exp(
+    inputs: &mut BTreeMap<String, InputObject>,
+    model_name: &str,
+    surface: &Surface,
+    scalars: &mut std::collections::BTreeSet<String>,
+) {
+    let model = &surface.models[model_name];
+    let name = bool_exp_name(&model.schema);
+    if inputs.contains_key(&name) {
+        return;
+    }
+    // Insert placeholder first to break cycles.
+    inputs.insert(name.clone(), InputObject::new(name.clone()));
+    let mut input = InputObject::new(name.clone());
+    // Optional list/recursive fields (Hasura-style); never required.
+    input = input.field(InputValue::new(
+        "_and",
+        TypeRef::named_nn_list(name.as_str()),
+    ));
+    input = input.field(InputValue::new(
+        "_or",
+        TypeRef::named_nn_list(name.as_str()),
+    ));
+    input = input.field(InputValue::new("_not", TypeRef::named(name.as_str())));
+    for column in &model.columns {
+        scalars.insert(column.scalar.clone());
+        let comparison = comparison_exp_name(&column.scalar);
+        input = input.field(InputValue::new(
+            column.name.as_str(),
+            TypeRef::named(comparison),
+        ));
+    }
+    for relationship in &model.relationships {
+        let Some(target) = surface.models.get(&relationship.target_model) else {
+            continue;
+        };
+        ensure_bool_exp(inputs, &relationship.target_model, surface, scalars);
+        let target_bool = bool_exp_name(&target.schema);
+        input = input.field(InputValue::new(
+            relationship.name.as_str(),
+            TypeRef::named(target_bool),
+        ));
+    }
+    inputs.insert(name, input);
+}
+
+fn ensure_order_by_input(inputs: &mut BTreeMap<String, InputObject>, model: &SurfaceModel) {
+    let name = order_by_name(&model.schema);
+    if inputs.contains_key(&name) {
+        return;
+    }
+    let mut input = InputObject::new(name.clone());
+    for column in &model.columns {
+        input = input.field(InputValue::new(
+            column.name.as_str(),
+            TypeRef::named("order_by"),
+        ));
+    }
+    inputs.insert(name, input);
+}
+
+fn ensure_aggregate_type(objects: &mut BTreeMap<String, Object>, model: &SurfaceModel) {
+    let agg = format!("{}_aggregate", model.table_name);
+    if objects.contains_key(&agg) {
+        return;
+    }
+    let fields_name = format!("{}_aggregate_fields", model.table_name);
+    let mut fields_obj = Object::new(fields_name.clone());
+    fields_obj = fields_obj.field(Field::new(
+        "count",
+        TypeRef::named_nn(TypeRef::INT),
+        |ctx| FieldFuture::new(async move { response_key_passthrough(&ctx, "count") }),
+    ));
+    objects.insert(fields_name.clone(), fields_obj);
+
+    let mut agg_obj = Object::new(agg.clone());
+    agg_obj = agg_obj.field(Field::new(
+        "aggregate",
+        TypeRef::named(fields_name),
+        |ctx| FieldFuture::new(async move { response_key_passthrough(&ctx, "aggregate") }),
+    ));
+    let obj = model.object_name.clone();
+    agg_obj = agg_obj.field(Field::new("nodes", TypeRef::named_nn_list_nn(obj), |ctx| {
+        FieldFuture::new(async move { response_key_passthrough(&ctx, "nodes") })
+    }));
+    objects.insert(agg, agg_obj);
+}
+
+fn surface_argument_type(argument: &SurfaceArgument) -> TypeRef {
+    match (argument.list, argument.nullable) {
+        (true, false) => TypeRef::named_nn_list_nn(argument.type_name.as_str()),
+        (true, true) => TypeRef::named_nn_list(argument.type_name.as_str()),
+        (false, false) => TypeRef::named_nn(argument.type_name.as_str()),
+        (false, true) => TypeRef::named(argument.type_name.as_str()),
+    }
+}
+
+fn with_field_arguments(mut field: Field, arguments: &[SurfaceArgument]) -> Field {
+    for argument in arguments {
+        field = field.argument(InputValue::new(
+            argument.name.as_str(),
+            surface_argument_type(argument),
+        ));
+    }
+    field
+}
+
+fn with_subscription_arguments(
+    mut field: async_graphql::dynamic::SubscriptionField,
+    arguments: &[SurfaceArgument],
+) -> async_graphql::dynamic::SubscriptionField {
+    for argument in arguments {
+        field = field.argument(InputValue::new(
+            argument.name.as_str(),
+            surface_argument_type(argument),
+        ));
+    }
+    field
+}
+
+fn ensure_command_input(inputs: &mut BTreeMap<String, InputObject>, tdef: &SurfaceTypeDef) {
+    if inputs.contains_key(&tdef.name) {
+        return;
+    }
+    let mut input = InputObject::new(tdef.name.clone());
+    for field in &tdef.fields {
+        let ty = command_field_type(field);
+        input = input.field(InputValue::new(field.name.as_str(), ty));
+        if let Some(nested) = &field.nested {
+            ensure_command_input(inputs, nested);
+        }
+    }
+    inputs.insert(tdef.name.clone(), input);
+}
+
+/// Register a typed command-mutation payload so field selection works on results.
+fn ensure_command_output(objects: &mut BTreeMap<String, Object>, tdef: &SurfaceTypeDef) {
+    if objects.contains_key(&tdef.name) {
+        return;
+    }
+    // Placeholder first so nested object cycles cannot re-enter forever.
+    objects.insert(tdef.name.clone(), Object::new(tdef.name.clone()));
+    let mut obj = Object::new(tdef.name.clone());
+    for field in &tdef.fields {
+        if let Some(nested) = &field.nested {
+            ensure_command_output(objects, nested);
+        }
+        let ty = command_field_type(field);
+        let key = field.name.clone();
+        obj = obj.field(Field::new(field.name.as_str(), ty, move |ctx| {
+            let key = key.clone();
+            FieldFuture::new(async move { schema_key_passthrough(&ctx, &key) })
+        }));
+    }
+    objects.insert(tdef.name.clone(), obj);
+}
+
+fn command_field_type(field: &SurfaceTypeField) -> TypeRef {
+    match (field.list, field.nullable, field.item_nullable) {
+        (true, false, false) => TypeRef::named_nn_list_nn(field.type_name.as_str()),
+        (true, true, false) => TypeRef::named_nn_list(field.type_name.as_str()),
+        (true, false, true) => TypeRef::named_list_nn(field.type_name.as_str()),
+        (true, true, true) => TypeRef::named_list(field.type_name.as_str()),
+        (false, false, _) => TypeRef::named_nn(field.type_name.as_str()),
+        (false, true, _) => TypeRef::named(field.type_name.as_str()),
+    }
+}
+
+fn response_key_passthrough(
+    ctx: &async_graphql::dynamic::ResolverContext<'_>,
+    key: &str,
+) -> Result<Option<Value>, async_graphql::Error> {
+    // SQL projection objects are keyed by response name so two selections of
+    // the same schema field can retain distinct arguments and sub-selections.
+    // An unaliased field's response name is its schema name.
+    let response_key = ctx.field().alias().unwrap_or(key);
+    passthrough_key(ctx, response_key)
+}
+
+fn schema_key_passthrough(
+    ctx: &async_graphql::dynamic::ResolverContext<'_>,
+    key: &str,
+) -> Result<Option<Value>, async_graphql::Error> {
+    // Command and status payloads are produced by framework/application code,
+    // not the SQL compiler, and therefore remain keyed by schema field name.
+    passthrough_key(ctx, key)
+}
+
+fn passthrough_key(
+    ctx: &async_graphql::dynamic::ResolverContext<'_>,
+    key: &str,
+) -> Result<Option<Value>, async_graphql::Error> {
+    let Some(value) = ctx.parent_value.as_value() else {
+        return Ok(None);
+    };
+    // Nested JSON may arrive as a string (SQLite json_group_array quirk).
+    if let Value::String(s) = value {
+        if let Ok(parsed) = serde_json::from_str::<serde_json::Value>(s) {
+            if let Ok(v) = Value::from_json(parsed) {
+                return Ok(lookup_key(&v, key));
+            }
+        }
+    }
+    Ok(lookup_key(value, key))
+}
+
+fn lookup_key(value: &Value, key: &str) -> Option<Value> {
+    match value {
+        Value::Object(map) => {
+            for (k, v) in map {
+                if k.as_str() == key {
+                    return (!matches!(v, Value::Null)).then(|| v.clone());
+                }
+            }
+            None
+        }
+        _ => None,
+    }
+}
+
+async fn resolve_root(
+    ctx: &async_graphql::dynamic::ResolverContext<'_>,
+    model: &str,
+    kind: RootKind,
+) -> Result<Option<Value>, async_graphql::Error> {
+    let inner = ctx
+        .data_opt::<Arc<EngineInner>>()
+        .cloned()
+        .ok_or_else(|| async_graphql::Error::new("GraphqlEngine not in request data"))?;
+    let session = ctx
+        .data_opt::<Session>()
+        .cloned()
+        .unwrap_or_else(Session::new);
+    let role = session
+        .role()
+        .map(|s| s.to_string())
+        .unwrap_or_else(|| inner.anonymous_role.clone());
+
+    let selection = compile::selection_from_field(ctx.field());
+    let plan = compile::compile_root(&inner, &session, &role, model, kind, &selection)
+        .map_err(|e| client_error("BAD_REQUEST", sanitize_compile_error(&e)))?;
+    let value = if let Some(protocol) = ctx.data_opt::<ProtocolResponseAccumulator>().cloned() {
+        let role_surface = inner.role_surfaces.get(&role).cloned().ok_or_else(|| {
+            client_error("INTERNAL", "authorized GraphQL role surface is unavailable")
+        })?;
+        let executed = super::query_protocol::execute_query_with_protocol(
+            &inner,
+            role_surface,
+            protocol.clone(),
+            &plan,
+            None,
+        )
+        .await
+        .map_err(|e| client_error_for_execute_err(&e))?;
+        protocol
+            .record_query_metadata(executed.snapshot, None)
+            .map_err(|_| client_error("INTERNAL", "query evidence encoding failed"))?;
+        executed.value
+    } else {
+        super::engine::execute_plan(&inner, &plan)
+            .await
+            .map_err(|e| client_error_for_execute_err(&e))?
+    };
+    // `None` (not `Some(Null)`) so nullable by_pk roots do not try to resolve
+    // non-null child fields on a null parent.
+    if matches!(value, Value::Null) {
+        Ok(None)
+    } else {
+        Ok(Some(value))
+    }
+}
+
+/// Closed set of engine-authored GraphQL `extensions.code` values (v1 freeze).
+/// Async-graphql document validation may still emit uncoded errors.
+#[allow(dead_code)] // public contract constant; asserted in unit tests
+pub const ENGINE_ERROR_CODES: &[&str] = &[
+    "BAD_REQUEST",
+    "FORBIDDEN",
+    "TIMEOUT",
+    "INTERNAL",
+    "UNAUTHORIZED", // command mutations
+    "NOT_FOUND",    // command mutations
+    "REJECTED",     // command mutations
+    "COMMAND_ID_REUSE",
+    "COMMAND_IN_PROGRESS",
+    "COMMAND_EXPIRED",
+];
+
+/// Map executor error strings to stable client errors (`extensions.code`).
+pub(crate) fn client_error_for_execute_err(e: &str) -> async_graphql::Error {
+    if e.contains("timeout") {
+        client_error("TIMEOUT", "statement timeout")
+    } else {
+        client_error("INTERNAL", "internal error")
+    }
+}
+
+fn sanitize_compile_error(e: &str) -> String {
+    // Stable short messages; never return raw SQL.
+    if e.contains("max depth") {
+        "max depth exceeded".into()
+    } else if e.contains("too complex") || e.contains("query too complex") {
+        "query too complex".into()
+    } else if e.contains("max_in_list")
+        || e.contains("_in list")
+        || e.contains("max_bool_width")
+        || e.contains("_and list")
+        || e.contains("_or list")
+    {
+        "list too long".into()
+    } else if e.contains("invalid GraphQL response key") {
+        "invalid response key".into()
+    } else if e.contains("unknown comparison")
+        || e.contains("unknown where field")
+        || e.contains("ungranted where")
+        || e.contains("unknown order_by")
+        || e.contains("ungranted order_by")
+        || e.contains("ambiguous order_by")
+    {
+        "invalid filter".into()
+    } else {
+        "bad request".into()
+    }
+}
+
+fn client_error(code: &str, message: impl Into<String>) -> async_graphql::Error {
+    use async_graphql::ErrorExtensions;
+    let code = code.to_string();
+    async_graphql::Error::new(message.into()).extend_with(move |_, ext| {
+        ext.set("code", code.as_str());
+    })
+}
+
+/// Command-mutation errors also carry numeric HTTP `extensions.status`.
+fn client_error_with_status(
+    code: &str,
+    status: u16,
+    message: impl Into<String>,
+) -> async_graphql::Error {
+    use async_graphql::ErrorExtensions;
+    let code = code.to_string();
+    async_graphql::Error::new(message.into()).extend_with(move |_, ext| {
+        ext.set("code", code.as_str());
+        ext.set("status", status as i32);
+    })
+}
+
+#[cfg(test)]
+mod execute_err_mapping_tests {
+    use super::{client_error_for_execute_err, sanitize_compile_error, ENGINE_ERROR_CODES};
+
+    #[test]
+    fn engine_error_codes_closed_set_v1() {
+        // Freeze: expanding this set is a client-breaking change.
+        assert_eq!(
+            ENGINE_ERROR_CODES,
+            &[
+                "BAD_REQUEST",
+                "FORBIDDEN",
+                "TIMEOUT",
+                "INTERNAL",
+                "UNAUTHORIZED",
+                "NOT_FOUND",
+                "REJECTED",
+                "COMMAND_ID_REUSE",
+                "COMMAND_IN_PROGRESS",
+                "COMMAND_EXPIRED",
+            ]
+        );
+    }
+
+    #[test]
+    fn statement_timeout_maps_to_timeout_code() {
+        let err = client_error_for_execute_err("statement timeout");
+        assert_eq!(err.message, "statement timeout");
+        let code = err
+            .extensions
+            .as_ref()
+            .and_then(|ext| ext.get("code"))
+            .map(|v| format!("{v:?}"));
+        assert!(
+            code.as_deref()
+                .map(|c| c.contains("TIMEOUT"))
+                .unwrap_or(false),
+            "expected TIMEOUT extension, got {code:?}"
+        );
+    }
+
+    #[test]
+    fn other_errors_map_to_internal() {
+        let err = client_error_for_execute_err("sqlite execute: boom");
+        assert_eq!(err.message, "internal error");
+        let code = err
+            .extensions
+            .as_ref()
+            .and_then(|ext| ext.get("code"))
+            .map(|v| format!("{v:?}"));
+        assert!(
+            code.as_deref()
+                .map(|c| c.contains("INTERNAL"))
+                .unwrap_or(false),
+            "expected INTERNAL extension, got {code:?}"
+        );
+    }
+
+    #[test]
+    fn sanitize_compile_error_table() {
+        assert_eq!(
+            sanitize_compile_error("max depth exceeded"),
+            "max depth exceeded"
+        );
+        assert_eq!(
+            sanitize_compile_error("_and list length 999 exceeds max_bool_width 256"),
+            "list too long"
+        );
+        assert_eq!(
+            sanitize_compile_error("_in list length 500 exceeds max_in_list 100"),
+            "list too long"
+        );
+        assert_eq!(
+            sanitize_compile_error("invalid GraphQL response key `x y`"),
+            "invalid response key"
+        );
+        assert_eq!(
+            sanitize_compile_error("unknown comparison op `_wat`"),
+            "invalid filter"
+        );
+        assert_eq!(
+            sanitize_compile_error("unknown where field `nope`"),
+            "invalid filter"
+        );
+        assert_eq!(
+            sanitize_compile_error("ungranted order_by column `secret`"),
+            "invalid filter"
+        );
+        assert_eq!(
+            sanitize_compile_error(
+                "ambiguous order_by entry: use one field per list entry to declare priority"
+            ),
+            "invalid filter"
+        );
+        assert_eq!(
+            sanitize_compile_error("SELECT * FROM secret"),
+            "bad request"
+        );
+    }
+}
+
+async fn resolve_command(
+    ctx: &async_graphql::dynamic::ResolverContext<'_>,
+    command_name: &str,
+) -> Result<Option<Value>, async_graphql::Error> {
+    use crate::microsvc::Service;
+
+    let session = ctx
+        .data_opt::<Session>()
+        .cloned()
+        .unwrap_or_else(Session::new);
+    let service = ctx.data_opt::<Arc<Service>>();
+    let Some(service) = service else {
+        return Err(client_error(
+            "INTERNAL",
+            "command dispatcher not configured (use graphql_router_with_service)",
+        ));
+    };
+
+    let input = ctx
+        .args
+        .get("input")
+        .map(|v| v.deserialize::<serde_json::Value>())
+        .transpose()
+        .map_err(|e| client_error("BAD_REQUEST", format!("invalid command input: {e:?}")))?
+        .unwrap_or(serde_json::json!({}));
+
+    let protocol = ctx
+        .data_opt::<ProtocolResponseAccumulator>()
+        .cloned()
+        .ok_or_else(|| {
+            client_error(
+                "INTERNAL",
+                "causal command protocol is not configured for this endpoint",
+            )
+        })?;
+    protocol
+        .claim_dispatch()
+        .map_err(|error| client_error("BAD_REQUEST", error.to_string()))?;
+    let command_id = ctx
+        .args
+        .get("commandId")
+        .ok_or_else(|| client_error("BAD_REQUEST", "missing commandId"))?
+        .deserialize::<String>()
+        .map_err(|_| client_error("BAD_REQUEST", "invalid commandId"))?;
+    let principal = ctx
+        .data_opt::<VerifiedPrincipal>()
+        .cloned()
+        .ok_or_else(|| {
+            client_error_with_status(
+                "UNAUTHORIZED",
+                401,
+                "durable commands require a verified OIDC bearer",
+            )
+        })?;
+    let result = service
+        .dispatch_causal_with_receipt(command_name, &command_id, input, session, principal)
+        .await
+        .map_err(|error| {
+            client_error_with_status(error.code(), error.status_code(), error.client_message())
+        })?;
+    protocol
+        .record_receipt(&result.receipt)
+        .map_err(|_| client_error("INTERNAL", "causal receipt encoding failed"))?;
+    Value::from_json(result.payload)
+        .map(Some)
+        .map_err(|e| client_error("INTERNAL", format!("response encode: {e}")))
+}
+
+async fn resolve_command_status(
+    ctx: &async_graphql::dynamic::ResolverContext<'_>,
+) -> Result<Option<Value>, async_graphql::Error> {
+    use crate::microsvc::Service;
+    use async_graphql::indexmap::IndexMap;
+
+    let session = ctx
+        .data_opt::<Session>()
+        .cloned()
+        .unwrap_or_else(Session::new);
+    let principal = ctx
+        .data_opt::<VerifiedPrincipal>()
+        .cloned()
+        .ok_or_else(|| {
+            client_error_with_status(
+                "UNAUTHORIZED",
+                401,
+                "durable command status requires a verified OIDC bearer",
+            )
+        })?;
+    let protocol = ctx
+        .data_opt::<ProtocolResponseAccumulator>()
+        .cloned()
+        .ok_or_else(|| {
+            client_error(
+                "INTERNAL",
+                "causal command protocol is not configured for this endpoint",
+            )
+        })?;
+    let service = ctx.data_opt::<Arc<Service>>().ok_or_else(|| {
+        client_error(
+            "INTERNAL",
+            "command dispatcher not configured (use graphql_router_with_service)",
+        )
+    })?;
+    let command_id = ctx
+        .args
+        .get("commandId")
+        .ok_or_else(|| client_error("BAD_REQUEST", "missing commandId"))?
+        .deserialize::<String>()
+        .map_err(|_| client_error("BAD_REQUEST", "invalid commandId"))?;
+
+    let status = service
+        .causal_command_status(&command_id, &session, principal)
+        .await
+        .map_err(|error| {
+            client_error_with_status(error.code(), error.status_code(), error.client_message())
+        })?;
+    protocol
+        .record_status(&status)
+        .map_err(|_| client_error("INTERNAL", "causal status encoding failed"))?;
+    let mut value = IndexMap::new();
+    value.insert(
+        async_graphql::Name::new("state"),
+        Value::Enum(async_graphql::Name::new(status.state.as_str())),
+    );
+    Ok(Some(Value::Object(value)))
+}
+
+#[cfg(test)]
+mod causal_command_schema_tests {
+    use std::collections::BTreeMap;
+    use std::sync::Arc;
+
+    use super::*;
+    use crate::graphql::command_contract::{CommandConsistency, CommandEffects};
+    use crate::graphql::protocol::{
+        DistributedEnvelopeV1, ProtocolResponseAccumulator, ProtocolTokenCodec,
+        ProtocolTokenPurpose,
+    };
+    use crate::graphql::sdl::graphql_sdl_from_surface;
+    use crate::graphql::surface::{
+        RootField, RootKind, SurfaceCommand, SurfaceDialect, SurfaceSelection,
+    };
+    use crate::microsvc::Service;
+
+    fn command_surface() -> Surface {
+        Surface {
+            selection: SurfaceSelection::Role {
+                name: "user".into(),
+            },
+            dialect: SurfaceDialect::Sqlite,
+            aggregates: false,
+            subscriptions: false,
+            default_limit: 100,
+            max_limit: 1000,
+            catalog: BTreeMap::new(),
+            models: BTreeMap::new(),
+            query_fields: Vec::new(),
+            subscription_fields: Vec::new(),
+            comparison_ops: BTreeMap::new(),
+            commands: vec![SurfaceCommand {
+                command_name: "todo.complete".into(),
+                field_name: "todo_complete".into(),
+                roles: vec!["user".into()],
+                input: SurfaceCommandShape::Typed(SurfaceTypeDef {
+                    name: "CompleteTodoInput".into(),
+                    fields: vec![SurfaceTypeField {
+                        name: "id".into(),
+                        type_name: "String".into(),
+                        nullable: false,
+                        list: false,
+                        item_nullable: false,
+                        nested: None,
+                    }],
+                }),
+                output: SurfaceCommandShape::Typed(SurfaceTypeDef {
+                    name: "CompleteTodoPayload".into(),
+                    fields: vec![SurfaceTypeField {
+                        name: "id".into(),
+                        type_name: "String".into(),
+                        nullable: false,
+                        list: false,
+                        item_nullable: false,
+                        nested: None,
+                    }],
+                }),
+                consistency: CommandConsistency::Accepted,
+                input_defaults: Vec::new(),
+                effects: Some(CommandEffects::revalidate()),
+                confirmations: Vec::new(),
+                projected_model: None,
+                direct_projection: None,
+                confirmation_unavailable: false,
+            }],
+            commands_attached: true,
+            projectors: Vec::new(),
+            projectors_attached: false,
+            service_binding: None,
+        }
+    }
+
+    fn runtime_sdl(surface: &Surface) -> String {
+        build_role_schema(surface, 32, 1_000, false)
+            .expect("role schema should build")
+            .sdl()
+    }
+
+    fn protocol_accumulator() -> ProtocolResponseAccumulator {
+        let codec = ProtocolTokenCodec::new([0x51; 32]);
+        let cache_scope = codec
+            .issue(
+                ProtocolTokenPurpose::CacheScope,
+                &("schema-unit-test", "status-test"),
+            )
+            .expect("test cache scope should encode");
+        ProtocolResponseAccumulator::new(
+            DistributedEnvelopeV1::new("sha256:schema-unit-test", cache_scope, None),
+            codec,
+        )
+    }
+
+    #[test]
+    fn causal_runtime_and_static_sdl_share_status_protocol() {
+        let surface = command_surface();
+        let static_sdl = graphql_sdl_from_surface(&surface).unwrap();
+        let runtime_sdl = runtime_sdl(&surface);
+
+        for expected in [
+            "enum DistributedCommandState",
+            "type DistributedCommandStatus",
+            "state: DistributedCommandState!",
+            "commandStatus(commandId: ID!): DistributedCommandStatus!",
+        ] {
+            assert!(
+                static_sdl.contains(expected),
+                "static SDL missing `{expected}`"
+            );
+            assert!(
+                runtime_sdl.contains(expected),
+                "runtime SDL missing `{expected}`:\n{runtime_sdl}"
+            );
+        }
+        for state in DISTRIBUTED_COMMAND_STATE_VALUES {
+            assert!(static_sdl.contains(&format!("\n  {state}\n")));
+            assert!(
+                runtime_sdl.contains(&format!("\t{state}\n"))
+                    || runtime_sdl.contains(&format!("\n  {state}\n")),
+                "runtime SDL missing lowercase enum value `{state}`:\n{runtime_sdl}"
+            );
+        }
+        assert!(!static_sdl.contains("_empty: Boolean!"));
+        assert!(!runtime_sdl.contains("_empty: Boolean!"));
+    }
+
+    #[test]
+    fn causal_runtime_schema_fails_closed_on_root_and_type_collisions() {
+        let mut root_collision = command_surface();
+        root_collision.query_fields.push(RootField {
+            name: COMMAND_STATUS_ROOT_FIELD.into(),
+            kind: RootKind::List,
+            object: "Unused".into(),
+            model_name: "Unused".into(),
+            arguments: Vec::new(),
+            dependencies: Vec::new(),
+            default_limit: None,
+            max_limit: None,
+        });
+        let error = build_role_schema(&root_collision, 32, 1_000, false).unwrap_err();
+        assert!(
+            error.contains(COMMAND_STATUS_ROOT_FIELD) && error.contains("collides"),
+            "{error}"
+        );
+
+        let mut type_collision = command_surface();
+        type_collision.commands[0].input = SurfaceCommandShape::Typed(SurfaceTypeDef {
+            name: DISTRIBUTED_COMMAND_STATUS_TYPE.into(),
+            fields: Vec::new(),
+        });
+        let error = build_role_schema(&type_collision, 32, 1_000, false).unwrap_err();
+        assert!(
+            error.contains(DISTRIBUTED_COMMAND_STATUS_TYPE)
+                && error.contains("causal protocol type"),
+            "{error}"
+        );
+    }
+
+    #[tokio::test]
+    async fn command_status_requires_verified_principal() {
+        let schema = build_role_schema(&command_surface(), 32, 1_000, false).unwrap();
+        let response = schema
+            .execute(format!(
+                "{{ {COMMAND_STATUS_ROOT_FIELD}(commandId: \"{}\") {{ state }} }}",
+                uuid::Uuid::now_v7()
+            ))
+            .await;
+
+        assert_eq!(response.errors.len(), 1, "{response:?}");
+        assert_eq!(
+            response.errors[0].message,
+            "durable command status requires a verified OIDC bearer"
+        );
+        let extensions = response.errors[0]
+            .extensions
+            .as_ref()
+            .expect("auth error extensions");
+        assert!(
+            format!("{:?}", extensions.get("code")).contains("UNAUTHORIZED"),
+            "{extensions:?}"
+        );
+        assert!(
+            format!("{:?}", extensions.get("status")).contains("401"),
+            "{extensions:?}"
+        );
+    }
+
+    #[tokio::test]
+    async fn authorized_unknown_status_returns_only_public_state() {
+        let schema = build_role_schema(&command_surface(), 32, 1_000, false).unwrap();
+        let request = async_graphql::Request::new(format!(
+            "{{ {COMMAND_STATUS_ROOT_FIELD}(commandId: \"{}\") {{ s: state }} }}",
+            uuid::Uuid::now_v7()
+        ))
+        .data(Arc::new(Service::new().named("status-test")))
+        .data(VerifiedPrincipal::test_oidc(
+            "https://issuer.example/",
+            "status-test-subject",
+            &["status-test-audience"],
+        ))
+        .data(protocol_accumulator());
+        let response = schema.execute(request).await;
+
+        assert!(response.errors.is_empty(), "{response:?}");
+        assert_eq!(
+            response.data.into_json().unwrap(),
+            serde_json::json!({
+                COMMAND_STATUS_ROOT_FIELD: {
+                    "s": "unknown"
+                }
+            })
+        );
+    }
+}
diff --git a/src/graphql/sdl.rs b/src/graphql/sdl.rs
new file mode 100644
index 00000000..e09f893b
--- /dev/null
+++ b/src/graphql/sdl.rs
@@ -0,0 +1,712 @@
+//! Dep-free SDL text renderer for `dctl schema --format graphql`.
+//!
+//! Renders the dialect-independent core query surface from `&[TableSchema]`.
+//! Artifact scope grows with the crate version (aggregates in phase 3,
+//! Subscription root in phase 4). Renderer and engine ship together.
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use crate::table::{TableKind, TableSchema};
+
+use super::naming::{
+    causal_protocol_type_names, comparison_exp_name, include_postgres_json_comparison_ops,
+    is_valid_graphql_name, order_by_enum_values, reserved_type_names, COMMAND_STATUS_ROOT_FIELD,
+    CUSTOM_SCALARS, DISTRIBUTED_COMMAND_STATE_TYPE, DISTRIBUTED_COMMAND_STATE_VALUES,
+    DISTRIBUTED_COMMAND_STATUS_TYPE,
+};
+
+/// Options controlling which surface slices the renderer emits.
+#[derive(Clone, Debug)]
+pub struct SdlOptions {
+    /// Emit `<table>_aggregate` roots and nested aggregate fields (phase 3).
+    pub aggregates: bool,
+    /// Emit Postgres `jsonb` comparison operators on `JSON_comparison_exp`.
+    ///
+    /// Must match the runtime engine dialect: **false for SQLite**, true for
+    /// Postgres. Defaults to false (SQLite / dialect-independent artifact).
+    /// See [`SdlOptions::sqlite`] / [`SdlOptions::postgres`].
+    pub jsonb_operators: bool,
+    /// Emit a Subscription root mirroring Query list fields (phase 4).
+    pub subscriptions: bool,
+}
+
+impl Default for SdlOptions {
+    fn default() -> Self {
+        Self::sqlite()
+    }
+}
+
+impl SdlOptions {
+    /// SDL for SQLite-backed engines (no PG JSON comparison ops).
+    pub fn sqlite() -> Self {
+        Self {
+            aggregates: true,
+            jsonb_operators: include_postgres_json_comparison_ops(false),
+            subscriptions: true,
+        }
+    }
+
+    /// SDL for Postgres-backed engines (includes jsonb comparison ops).
+    pub fn postgres() -> Self {
+        Self {
+            aggregates: true,
+            jsonb_operators: include_postgres_json_comparison_ops(true),
+            subscriptions: true,
+        }
+    }
+}
+
+/// Render GraphQL SDL for the given tables (ReadModel only; operational filtered).
+///
+/// Builds the shared [[surface]] IR first, then emits SDL only from that IR so
+/// dialect ops and model set cannot diverge from `build_surface`.
+pub fn graphql_sdl_for_tables(tables: &[TableSchema]) -> Result<String, String> {
+    graphql_sdl_for_tables_with_options(tables, &SdlOptions::default())
+}
+
+pub fn graphql_sdl_for_tables_with_options(
+    tables: &[TableSchema],
+    options: &SdlOptions,
+) -> Result<String, String> {
+    let surface_opts = super::surface::SurfaceOptions {
+        dialect: if options.jsonb_operators {
+            super::surface::SurfaceDialect::Postgres
+        } else {
+            super::surface::SurfaceDialect::Sqlite
+        },
+        aggregates: options.aggregates,
+        subscriptions: options.subscriptions,
+        default_limit: 100,
+        max_limit: 1000,
+    };
+    let surface = super::surface::build_surface(tables, &surface_opts)?;
+    graphql_sdl_from_surface(&surface)
+}
+
+/// Emit GraphQL SDL from a pre-built surface IR (role-filtered or full catalog).
+pub fn graphql_sdl_from_surface(surface: &super::surface::Surface) -> Result<String, String> {
+    graphql_sdl_from_read_models(surface)
+}
+
+/// Production path for **role-filtered** SDL (gap A10).
+///
+/// ```text
+/// build_surface → surface_for_role → graphql_sdl_from_surface
+/// ```
+///
+/// Prefer this over filtering full SDL as text. `grants` maps model_name →
+/// [`RoleGrant`](super::surface::RoleGrant) for the role.
+pub fn graphql_sdl_for_role(
+    tables: &[TableSchema],
+    options: &SdlOptions,
+    role: &str,
+    grants: &std::collections::BTreeMap<String, super::surface::RoleGrant>,
+) -> Result<String, String> {
+    let surface_opts = super::surface::SurfaceOptions {
+        dialect: if options.jsonb_operators {
+            super::surface::SurfaceDialect::Postgres
+        } else {
+            super::surface::SurfaceDialect::Sqlite
+        },
+        aggregates: options.aggregates,
+        subscriptions: options.subscriptions,
+        default_limit: 100,
+        max_limit: 1000,
+    };
+    let full = super::surface::build_surface(tables, &surface_opts)?;
+    let role_surface = super::surface::surface_for_role(&full, role, grants)?;
+    graphql_sdl_from_surface(&role_surface)
+}
+
+/// Internal renderer over an already IR-filtered set of read models.
+fn graphql_sdl_from_read_models(surface: &super::surface::Surface) -> Result<String, String> {
+    let has_causal_commands = !surface.commands.is_empty();
+    // Type names and root field names are separate GraphQL namespaces (Hasura
+    // reuses e.g. `players_aggregate` as both a root field and an object type).
+    let mut type_names: BTreeSet<String> = BTreeSet::new();
+    let mut query_fields: BTreeSet<String> = BTreeSet::new();
+    let mut subscription_fields: BTreeSet<String> = BTreeSet::new();
+    for reserved in reserved_type_names() {
+        type_names.insert(reserved.to_string());
+    }
+    if has_causal_commands {
+        for reserved in causal_protocol_type_names() {
+            type_names.insert(reserved.to_string());
+            if surface.commands.iter().any(|command| {
+                command_shape_uses_type_name(&command.input, reserved)
+                    || command_shape_uses_type_name(&command.output, reserved)
+            }) {
+                return Err(format!(
+                    "generated name `{reserved}` collides with a causal protocol type"
+                ));
+            }
+        }
+    }
+    for scalar in CUSTOM_SCALARS {
+        if !is_valid_graphql_name(scalar) {
+            return Err(format!("scalar `{scalar}` is not a valid GraphQL name"));
+        }
+    }
+
+    for comparison_name in surface.comparison_ops.keys() {
+        claim_name(&mut type_names, comparison_name)?;
+    }
+    for model in surface.models.values() {
+        claim_name(&mut type_names, &model.object_name)?;
+        claim_name(&mut type_names, &format!("{}_bool_exp", model.table_name))?;
+        claim_name(&mut type_names, &format!("{}_order_by", model.table_name))?;
+        if model.aggregations {
+            claim_name(&mut type_names, &format!("{}_aggregate", model.table_name))?;
+            claim_name(
+                &mut type_names,
+                &format!("{}_aggregate_fields", model.table_name),
+            )?;
+        }
+        for column in &model.columns {
+            if !is_valid_graphql_name(&column.name) {
+                return Err(format!(
+                    "model `{}` column `{}` is not a valid GraphQL name",
+                    model.model_name, column.name
+                ));
+            }
+        }
+        for relationship in &model.relationships {
+            if !is_valid_graphql_name(&relationship.name) {
+                return Err(format!(
+                    "model `{}` relationship `{}` is not a valid GraphQL name",
+                    model.model_name, relationship.name
+                ));
+            }
+        }
+    }
+    for root in &surface.query_fields {
+        claim_name(&mut query_fields, &root.name)?;
+    }
+    if has_causal_commands {
+        claim_name(&mut query_fields, COMMAND_STATUS_ROOT_FIELD)?;
+    }
+    for root in &surface.subscription_fields {
+        claim_name(&mut subscription_fields, &root.name)?;
+    }
+
+    let mut out = String::new();
+
+    // Custom scalars, alphabetically.
+    for scalar in CUSTOM_SCALARS {
+        out.push_str(&format!("scalar {scalar}\n"));
+    }
+    out.push('\n');
+
+    // order_by enum.
+    out.push_str("enum order_by {\n");
+    for v in order_by_enum_values() {
+        out.push_str(&format!("  {v}\n"));
+    }
+    out.push_str("}\n\n");
+
+    // Comparison input types (shared per scalar that appears).
+    let used_scalars: BTreeSet<&str> = surface
+        .models
+        .values()
+        .flat_map(|model| model.columns.iter().map(|column| column.scalar.as_str()))
+        .collect();
+    for scalar in &used_scalars {
+        let name = comparison_exp_name(scalar);
+        let operators = surface
+            .comparison_ops
+            .get(&name)
+            .ok_or_else(|| format!("Surface is missing comparison operator inventory `{name}`"))?;
+        emit_comparison_exp(&mut out, scalar, operators);
+    }
+
+    for model in surface.models.values() {
+        emit_object_type(&mut out, model, surface);
+        emit_bool_exp(&mut out, model, surface);
+        emit_order_by_input(&mut out, model);
+        if model.aggregations {
+            emit_aggregate_types(&mut out, model);
+        }
+    }
+
+    emit_command_types(&mut out, &surface.commands, &surface.models)?;
+    if has_causal_commands {
+        emit_causal_command_protocol_types(&mut out);
+    }
+
+    // Roots are emitted from the Surface inventory, not reconstructed from
+    // schemas. This is what keeps hidden/partial by-PK identity and per-model
+    // aggregate grants aligned with runtime and client manifest output.
+    out.push_str("type Query {\n");
+    if surface.query_fields.is_empty() && !has_causal_commands {
+        // async-graphql requires a non-empty Query object and the runtime uses
+        // this same fail-closed sentinel for roles with no readable models.
+        // It is intentionally not a client-manifest root.
+        out.push_str("  _empty: Boolean!\n");
+    } else {
+        for field in &surface.query_fields {
+            out.push_str(&surface_root_sdl(field));
+            out.push('\n');
+        }
+        if has_causal_commands {
+            out.push_str(&format!(
+                "  {COMMAND_STATUS_ROOT_FIELD}(commandId: ID!): {DISTRIBUTED_COMMAND_STATUS_TYPE}!\n"
+            ));
+        }
+    }
+    out.push_str("}\n");
+
+    if !surface.subscription_fields.is_empty() {
+        out.push_str("\ntype Subscription {\n");
+        for field in &surface.subscription_fields {
+            out.push_str(&surface_root_sdl(field));
+            out.push('\n');
+        }
+        out.push_str("}\n");
+    }
+
+    if !surface.commands.is_empty() {
+        out.push_str("\ntype Mutation {\n");
+        for command in &surface.commands {
+            let input = command_arguments_sdl(&command.input);
+            let output = match &command.output {
+                super::surface::SurfaceCommandShape::None => {
+                    return Err(format!(
+                        "command `{}` cannot declare an empty output",
+                        command.command_name
+                    ));
+                }
+                super::surface::SurfaceCommandShape::Typed(definition) => &definition.name,
+            };
+            out.push_str(&format!("  {}{}: {}!\n", command.field_name, input, output));
+        }
+        out.push_str("}\n");
+    }
+
+    Ok(out)
+}
+
+fn emit_causal_command_protocol_types(out: &mut String) {
+    out.push_str(&format!("enum {DISTRIBUTED_COMMAND_STATE_TYPE} {{\n"));
+    for state in DISTRIBUTED_COMMAND_STATE_VALUES {
+        out.push_str(&format!("  {state}\n"));
+    }
+    out.push_str("}\n\n");
+    out.push_str(&format!("type {DISTRIBUTED_COMMAND_STATUS_TYPE} {{\n"));
+    out.push_str(&format!("  state: {DISTRIBUTED_COMMAND_STATE_TYPE}!\n"));
+    out.push_str("}\n\n");
+}
+
+fn command_shape_uses_type_name(shape: &super::surface::SurfaceCommandShape, name: &str) -> bool {
+    match shape {
+        super::surface::SurfaceCommandShape::None => false,
+        super::surface::SurfaceCommandShape::Typed(definition) => {
+            command_type_uses_name(definition, name)
+        }
+    }
+}
+
+fn command_type_uses_name(definition: &super::surface::SurfaceTypeDef, name: &str) -> bool {
+    definition.name == name
+        || definition.fields.iter().any(|field| {
+            field.type_name == name
+                || field
+                    .nested
+                    .as_deref()
+                    .is_some_and(|nested| command_type_uses_name(nested, name))
+        })
+}
+
+fn command_arguments_sdl(input: &super::surface::SurfaceCommandShape) -> String {
+    let mut arguments = vec!["commandId: ID!".to_string()];
+    match input {
+        super::surface::SurfaceCommandShape::None => {}
+        super::surface::SurfaceCommandShape::Typed(definition) => {
+            arguments.push(format!("input: {}!", definition.name));
+        }
+    }
+    if arguments.is_empty() {
+        String::new()
+    } else {
+        format!("({})", arguments.join(", "))
+    }
+}
+
+fn surface_root_sdl(root: &super::surface::RootField) -> String {
+    let arguments = root
+        .arguments
+        .iter()
+        .map(|argument| {
+            let mut ty = if argument.list {
+                format!("[{}!]", argument.type_name)
+            } else {
+                argument.type_name.clone()
+            };
+            if !argument.nullable {
+                ty.push('!');
+            }
+            format!("{}: {ty}", argument.name)
+        })
+        .collect::<Vec<_>>();
+    let arguments = if arguments.is_empty() {
+        String::new()
+    } else {
+        format!("({})", arguments.join(", "))
+    };
+    let output = match root.kind {
+        super::surface::RootKind::List => format!("[{}!]!", root.object),
+        super::surface::RootKind::ByPk => root.object.clone(),
+        super::surface::RootKind::Aggregate => root.name.clone(),
+    };
+    format!("  {}{}: {}", root.name, arguments, output)
+}
+
+fn emit_command_types(
+    out: &mut String,
+    commands: &[super::surface::SurfaceCommand],
+    models: &BTreeMap<String, super::surface::SurfaceModel>,
+) -> Result<(), String> {
+    let mut inputs = BTreeMap::new();
+    let mut outputs = BTreeMap::new();
+    for command in commands {
+        if let super::surface::SurfaceCommandShape::Typed(definition) = &command.input {
+            collect_command_type(definition, &mut inputs)?;
+        }
+        if let super::surface::SurfaceCommandShape::Typed(definition) = &command.output {
+            let reuses_visible_model = super::surface::projected_output_reuses_surface_model(
+                &command.command_name,
+                command.consistency,
+                command.projected_model.as_ref(),
+                definition,
+                models,
+            )?;
+            if !reuses_visible_model {
+                collect_command_type(definition, &mut outputs)?;
+            }
+        }
+    }
+    for definition in inputs.values() {
+        emit_command_type(out, "input", definition);
+    }
+    for definition in outputs.values() {
+        emit_command_type(out, "type", definition);
+    }
+    Ok(())
+}
+
+fn collect_command_type(
+    definition: &super::surface::SurfaceTypeDef,
+    types: &mut BTreeMap<String, super::surface::SurfaceTypeDef>,
+) -> Result<(), String> {
+    if let Some(existing) = types.get(&definition.name) {
+        if existing != definition {
+            return Err(format!(
+                "command type `{}` has conflicting structural definitions",
+                definition.name
+            ));
+        }
+        return Ok(());
+    }
+    types.insert(definition.name.clone(), definition.clone());
+    for field in &definition.fields {
+        if let Some(nested) = &field.nested {
+            collect_command_type(nested, types)?;
+        }
+    }
+    Ok(())
+}
+
+fn emit_command_type(out: &mut String, keyword: &str, definition: &super::surface::SurfaceTypeDef) {
+    out.push_str(&format!("{keyword} {} {{\n", definition.name));
+    for field in &definition.fields {
+        let mut ty = if field.list {
+            if field.item_nullable {
+                format!("[{}]", field.type_name)
+            } else {
+                format!("[{}!]", field.type_name)
+            }
+        } else {
+            field.type_name.clone()
+        };
+        if !field.nullable {
+            ty.push('!');
+        }
+        out.push_str(&format!("  {}: {}\n", field.name, ty));
+    }
+    out.push_str("}\n\n");
+}
+
+fn claim_name(names: &mut BTreeSet<String>, name: &str) -> Result<(), String> {
+    if !is_valid_graphql_name(name) {
+        return Err(format!(
+            "generated name `{name}` is not a valid GraphQL name"
+        ));
+    }
+    if !names.insert(name.to_string()) {
+        return Err(format!(
+            "generated name `{name}` collides with another type or field"
+        ));
+    }
+    Ok(())
+}
+
+fn emit_comparison_exp(out: &mut String, scalar: &str, operators: &[String]) {
+    let name = comparison_exp_name(scalar);
+    out.push_str(&format!("input {name} {{\n"));
+    for operator in operators {
+        let operand = match operator.as_str() {
+            "_in" | "_nin" => format!("[{scalar}!]"),
+            "_is_null" => "Boolean".into(),
+            "_like" | "_ilike" | "_has_key" => "String".into(),
+            _ => scalar.to_string(),
+        };
+        out.push_str(&format!("  {operator}: {operand}\n"));
+    }
+    out.push_str("}\n\n");
+}
+
+fn emit_object_type(
+    out: &mut String,
+    model: &super::surface::SurfaceModel,
+    surface: &super::surface::Surface,
+) {
+    let name = &model.object_name;
+    out.push_str(&format!("type {name} {{\n"));
+    for column in &model.columns {
+        let null = if column.nullable { "" } else { "!" };
+        out.push_str(&format!("  {}: {}{}\n", column.name, column.scalar, null));
+    }
+    for relationship in &model.relationships {
+        let Some(target) = surface.models.get(&relationship.target_model) else {
+            continue;
+        };
+        if relationship.list {
+            out.push_str(&format!(
+                "  {}{}: [{}!]!\n",
+                relationship.name,
+                surface_arguments_sdl(&relationship.arguments),
+                target.object_name
+            ));
+        } else {
+            let null = if relationship.nullable { "" } else { "!" };
+            out.push_str(&format!(
+                "  {}: {}{}\n",
+                relationship.name, target.object_name, null
+            ));
+        }
+        if let Some(aggregate) = &relationship.aggregate {
+            out.push_str(&format!(
+                "  {}{}: {}\n",
+                aggregate.name,
+                surface_arguments_sdl(&aggregate.arguments),
+                aggregate.type_name
+            ));
+        }
+    }
+    out.push_str("}\n\n");
+}
+
+fn emit_bool_exp(
+    out: &mut String,
+    model: &super::surface::SurfaceModel,
+    surface: &super::surface::Surface,
+) {
+    let name = format!("{}_bool_exp", model.table_name);
+    out.push_str(&format!("input {name} {{\n"));
+    out.push_str(&format!("  _and: [{name}!]\n"));
+    out.push_str(&format!("  _or: [{name}!]\n"));
+    out.push_str(&format!("  _not: {name}\n"));
+    for column in &model.columns {
+        let cmp = comparison_exp_name(&column.scalar);
+        out.push_str(&format!("  {}: {}\n", column.name, cmp));
+    }
+    for relationship in &model.relationships {
+        let Some(target) = surface.models.get(&relationship.target_model) else {
+            continue;
+        };
+        let target_bool = format!("{}_bool_exp", target.table_name);
+        out.push_str(&format!("  {}: {}\n", relationship.name, target_bool));
+    }
+    out.push_str("}\n\n");
+}
+
+fn emit_order_by_input(out: &mut String, model: &super::surface::SurfaceModel) {
+    let name = format!("{}_order_by", model.table_name);
+    out.push_str(&format!("input {name} {{\n"));
+    for column in &model.columns {
+        out.push_str(&format!("  {}: order_by\n", column.name));
+    }
+    out.push_str("}\n\n");
+}
+
+fn emit_aggregate_types(out: &mut String, model: &super::surface::SurfaceModel) {
+    let agg = format!("{}_aggregate", model.table_name);
+    let fields = format!("{}_aggregate_fields", model.table_name);
+    let obj = &model.object_name;
+    out.push_str(&format!("type {agg} {{\n"));
+    out.push_str(&format!("  aggregate: {fields}\n"));
+    out.push_str(&format!("  nodes: [{obj}!]!\n"));
+    out.push_str("}\n\n");
+
+    out.push_str(&format!("type {fields} {{\n"));
+    out.push_str("  count: Int!\n");
+    out.push_str("}\n\n");
+}
+
+fn surface_arguments_sdl(arguments: &[super::surface::SurfaceArgument]) -> String {
+    if arguments.is_empty() {
+        return String::new();
+    }
+    let arguments = arguments
+        .iter()
+        .map(|argument| {
+            let mut type_name = if argument.list {
+                format!("[{}!]", argument.type_name)
+            } else {
+                argument.type_name.clone()
+            };
+            if !argument.nullable {
+                type_name.push('!');
+            }
+            format!("{}: {type_name}", argument.name)
+        })
+        .collect::<Vec<_>>()
+        .join(", ");
+    format!("({arguments})")
+}
+
+/// Filter operational tables and render SDL for a project manifest's tables.
+pub fn graphql_sdl_from_schemas(
+    schemas: impl IntoIterator<Item = TableSchema>,
+) -> Result<String, String> {
+    let tables: Vec<TableSchema> = schemas
+        .into_iter()
+        .filter(|t| matches!(t.kind, TableKind::ReadModel))
+        .collect();
+    graphql_sdl_for_tables(&tables)
+}
+
+#[cfg(test)]
+mod causal_command_sdl_tests {
+    use super::*;
+    use crate::graphql::command_contract::{CommandConsistency, CommandEffects};
+    use crate::graphql::surface::{SurfaceCommandShape, SurfaceTypeDef};
+
+    fn command_surface() -> crate::graphql::surface::Surface {
+        use crate::graphql::surface::{Surface, SurfaceCommand, SurfaceDialect, SurfaceSelection};
+
+        Surface {
+            selection: SurfaceSelection::Role {
+                name: "user".into(),
+            },
+            dialect: SurfaceDialect::Sqlite,
+            aggregates: false,
+            subscriptions: false,
+            default_limit: 100,
+            max_limit: 1000,
+            catalog: BTreeMap::new(),
+            models: BTreeMap::new(),
+            query_fields: Vec::new(),
+            subscription_fields: Vec::new(),
+            comparison_ops: BTreeMap::new(),
+            commands: vec![SurfaceCommand {
+                command_name: "todo.complete".into(),
+                field_name: "todo_complete".into(),
+                roles: vec!["user".into()],
+                input: SurfaceCommandShape::Typed(SurfaceTypeDef {
+                    name: "CompleteTodoInput".into(),
+                    fields: vec![crate::graphql::surface::SurfaceTypeField {
+                        name: "id".into(),
+                        type_name: "String".into(),
+                        nullable: false,
+                        list: false,
+                        item_nullable: false,
+                        nested: None,
+                    }],
+                }),
+                output: SurfaceCommandShape::Typed(SurfaceTypeDef {
+                    name: "CompleteTodoPayload".into(),
+                    fields: vec![crate::graphql::surface::SurfaceTypeField {
+                        name: "id".into(),
+                        type_name: "String".into(),
+                        nullable: false,
+                        list: false,
+                        item_nullable: false,
+                        nested: None,
+                    }],
+                }),
+                consistency: CommandConsistency::Accepted,
+                input_defaults: Vec::new(),
+                effects: Some(CommandEffects::revalidate()),
+                confirmations: Vec::new(),
+                projected_model: None,
+                direct_projection: None,
+                confirmation_unavailable: false,
+            }],
+            commands_attached: true,
+            projectors: Vec::new(),
+            projectors_attached: false,
+            service_binding: None,
+        }
+    }
+
+    #[test]
+    fn causal_mutations_require_framework_command_id_before_input() {
+        let typed = SurfaceCommandShape::Typed(SurfaceTypeDef {
+            name: "CompleteTodoInput".into(),
+            fields: Vec::new(),
+        });
+        assert_eq!(
+            command_arguments_sdl(&typed),
+            "(commandId: ID!, input: CompleteTodoInput!)"
+        );
+    }
+
+    #[test]
+    fn causal_surface_emits_status_root_and_lowercase_state_enum() {
+        let sdl = graphql_sdl_from_surface(&command_surface()).unwrap();
+
+        assert!(sdl.contains("commandStatus(commandId: ID!): DistributedCommandStatus!"));
+        assert!(sdl.contains("type DistributedCommandStatus {\n  state: DistributedCommandState!"));
+        for state in DISTRIBUTED_COMMAND_STATE_VALUES {
+            assert!(
+                sdl.contains(&format!("\n  {state}\n")),
+                "missing status state `{state}`:\n{sdl}"
+            );
+        }
+        assert!(!sdl.contains("_empty: Boolean!"));
+    }
+
+    #[test]
+    fn causal_status_root_and_types_fail_closed_on_collisions() {
+        use crate::graphql::surface::{RootField, RootKind};
+
+        let mut root_collision = command_surface();
+        root_collision.query_fields.push(RootField {
+            name: COMMAND_STATUS_ROOT_FIELD.into(),
+            kind: RootKind::List,
+            object: "Unused".into(),
+            model_name: "Unused".into(),
+            arguments: Vec::new(),
+            dependencies: Vec::new(),
+            default_limit: None,
+            max_limit: None,
+        });
+        let error = graphql_sdl_from_surface(&root_collision).unwrap_err();
+        assert!(
+            error.contains("commandStatus") && error.contains("collides"),
+            "{error}"
+        );
+
+        let mut type_collision = command_surface();
+        type_collision.commands[0].input = SurfaceCommandShape::Typed(SurfaceTypeDef {
+            name: DISTRIBUTED_COMMAND_STATUS_TYPE.into(),
+            fields: Vec::new(),
+        });
+        let error = graphql_sdl_from_surface(&type_collision).unwrap_err();
+        assert!(
+            error.contains(DISTRIBUTED_COMMAND_STATUS_TYPE)
+                && error.contains("causal protocol type"),
+            "{error}"
+        );
+    }
+}
diff --git a/src/graphql/subscribe.rs b/src/graphql/subscribe.rs
new file mode 100644
index 00000000..3dca2fe4
--- /dev/null
+++ b/src/graphql/subscribe.rs
@@ -0,0 +1,333 @@
+//! Commit-path subscription invalidation (live query refresh).
+//!
+//! Each subscription field:
+//! 1. Executes the query once and yields the initial result.
+//! 2. Listens on [`ChangeHub`] (fed by `change_stream` / repo broadcast).
+//! 3. On dirty tables intersecting the plan footprint, debounces, re-executes,
+//!    and yields only when the response hash changes (hash-gated push).
+
+use std::collections::BTreeSet;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::task::{Context, Poll};
+use std::time::Duration;
+
+use async_graphql::Value;
+use futures_util::Stream;
+use tokio::sync::{broadcast, mpsc};
+
+use crate::microsvc::Session;
+use crate::read_model::ReadModelChange;
+
+use super::compile::{self, RootKind, SelectionNode, SqlPlan};
+use super::engine::{execute_plan, EngineInner};
+use super::protocol::{ProtocolResponseAccumulator, RequestedLiveResume};
+
+/// Fan-out hub for read-model change notifications.
+#[derive(Clone, Debug)]
+pub struct ChangeHub {
+    tx: broadcast::Sender<ReadModelChange>,
+}
+
+impl ChangeHub {
+    pub fn new() -> Self {
+        let (tx, _) = broadcast::channel(256);
+        Self { tx }
+    }
+
+    pub fn subscribe(&self) -> broadcast::Receiver<ReadModelChange> {
+        self.tx.subscribe()
+    }
+
+    pub fn publish(&self, change: ReadModelChange) {
+        if change.is_empty() {
+            // Empty set is reserved as the all-dirty lag signal; allow it only
+            // when explicitly published for that purpose (forwarder).
+        }
+        let _ = self.tx.send(change);
+    }
+
+    /// Forward an external receiver into this hub until the source closes.
+    pub fn spawn_forward_from(&self, mut rx: broadcast::Receiver<ReadModelChange>) {
+        let tx = self.tx.clone();
+        tokio::spawn(async move {
+            loop {
+                match rx.recv().await {
+                    Ok(change) => {
+                        let _ = tx.send(change);
+                    }
+                    Err(broadcast::error::RecvError::Lagged(_)) => {
+                        // Empty tables = all-dirty for subscribers.
+                        let _ = tx.send(ReadModelChange {
+                            tables: BTreeSet::new(),
+                        });
+                    }
+                    Err(broadcast::error::RecvError::Closed) => break,
+                }
+            }
+        });
+    }
+}
+
+impl Default for ChangeHub {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+// Yield `Value` (not FieldValue<'static>) so HRTB `Into<FieldValue<'a>>` holds for any 'a.
+type LiveItem = Result<Value, async_graphql::Error>;
+
+/// Stream of GraphQL field values for one live subscription.
+pub struct LiveQueryStream {
+    rx: mpsc::Receiver<LiveItem>,
+}
+
+impl Stream for LiveQueryStream {
+    type Item = LiveItem;
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        self.rx.poll_recv(cx)
+    }
+}
+
+/// Build a live-query stream for a subscription root field.
+pub(crate) async fn live_query_stream(
+    inner: Arc<EngineInner>,
+    session: Session,
+    role: String,
+    model: String,
+    selection: SelectionNode,
+    protocol: Option<ProtocolResponseAccumulator>,
+) -> Result<LiveQueryStream, String> {
+    let plan: SqlPlan =
+        compile::compile_root(&inner, &session, &role, &model, RootKind::List, &selection)?;
+    let footprint = footprint_from_tables(&plan.tables_touched);
+    let mut change_rx = inner.change_hub.subscribe();
+    let (tx, rx) = mpsc::channel::<LiveItem>(8);
+    let debounce = Duration::from_millis(100);
+    let requested_live_resume = protocol
+        .as_ref()
+        .map(ProtocolResponseAccumulator::requested_live_resume)
+        .transpose()
+        .map_err(|error| error.to_string())?
+        .unwrap_or(RequestedLiveResume::Absent);
+
+    tokio::spawn(async move {
+        // 1) Initial execution + yield
+        let mut initial = match execute_list(
+            &inner,
+            &role,
+            &plan,
+            protocol.as_ref(),
+            requested_live_resume,
+        )
+        .await
+        {
+            Ok(executed) => executed,
+            Err(e) => {
+                let _ = tx.send(Err(async_graphql::Error::new(e))).await;
+                return;
+            }
+        };
+        if let Err(error) = initial.record_protocol_metadata(protocol.as_ref()) {
+            let _ = tx.send(Err(async_graphql::Error::new(error))).await;
+            return;
+        }
+        let mut last_hash = Some(initial.hash);
+        let mut next_live_resume = initial.next_live_resume;
+        if tx.send(Ok(initial.value)).await.is_err() {
+            return;
+        }
+
+        // 2) Change loop: dirty → debounce → re-exec → hash-gate → yield
+        loop {
+            let change = match change_rx.recv().await {
+                Ok(c) => c,
+                Err(broadcast::error::RecvError::Lagged(_)) => ReadModelChange {
+                    tables: BTreeSet::new(),
+                },
+                Err(broadcast::error::RecvError::Closed) => break,
+            };
+
+            if !footprint_hits(&footprint, &change) {
+                continue;
+            }
+
+            // Debounce / coalesce
+            tokio::time::sleep(debounce).await;
+            loop {
+                match change_rx.try_recv() {
+                    Ok(more) => {
+                        // Keep waiting only if still relevant; either way we re-exec once.
+                        let _ = more;
+                    }
+                    Err(broadcast::error::TryRecvError::Empty) => break,
+                    Err(broadcast::error::TryRecvError::Lagged(_)) => break,
+                    Err(broadcast::error::TryRecvError::Closed) => return,
+                }
+            }
+
+            match execute_list(
+                &inner,
+                &role,
+                &plan,
+                protocol.as_ref(),
+                next_live_resume.clone(),
+            )
+            .await
+            {
+                Ok(mut executed) => {
+                    // Advance the private replay cursor even when a redundant
+                    // execution is hash-gated. Protocol frame metadata is
+                    // enqueued only when the matching GraphQL value is emitted,
+                    // preserving exact data/envelope FIFO ordering.
+                    next_live_resume = executed.next_live_resume.clone();
+                    if last_hash == Some(executed.hash) {
+                        continue; // hash gate: no push on no-change
+                    }
+                    if let Err(error) = executed.record_protocol_metadata(protocol.as_ref()) {
+                        if tx
+                            .send(Err(async_graphql::Error::new(error)))
+                            .await
+                            .is_err()
+                        {
+                            return;
+                        }
+                        continue;
+                    }
+                    last_hash = Some(executed.hash);
+                    if tx.send(Ok(executed.value)).await.is_err() {
+                        return;
+                    }
+                }
+                Err(e) => {
+                    if tx.send(Err(async_graphql::Error::new(e))).await.is_err() {
+                        return;
+                    }
+                }
+            }
+        }
+    });
+
+    Ok(LiveQueryStream { rx })
+}
+
+struct ExecutedLiveQuery {
+    value: Value,
+    hash: u64,
+    snapshot: Option<super::protocol::DistributedQuerySnapshot>,
+    live: Option<super::protocol::DistributedLiveMetadata>,
+    next_live_resume: RequestedLiveResume,
+}
+
+impl ExecutedLiveQuery {
+    fn record_protocol_metadata(
+        &mut self,
+        protocol: Option<&ProtocolResponseAccumulator>,
+    ) -> Result<(), String> {
+        let Some(protocol) = protocol else {
+            return Ok(());
+        };
+        let snapshot = self
+            .snapshot
+            .take()
+            .ok_or_else(|| "causal live query omitted its snapshot metadata".to_string())?;
+        protocol
+            .record_query_metadata(snapshot, self.live.take())
+            .map_err(|error| error.to_string())
+    }
+}
+
+async fn execute_list(
+    inner: &EngineInner,
+    role: &str,
+    plan: &SqlPlan,
+    protocol: Option<&ProtocolResponseAccumulator>,
+    requested_live_resume: RequestedLiveResume,
+) -> Result<ExecutedLiveQuery, String> {
+    let Some(protocol) = protocol else {
+        let value = execute_plan(inner, plan).await?;
+        return Ok(ExecutedLiveQuery {
+            hash: response_hash(&value),
+            value,
+            snapshot: None,
+            live: None,
+            next_live_resume: RequestedLiveResume::Absent,
+        });
+    };
+
+    let role_surface = inner
+        .role_surfaces
+        .get(role)
+        .cloned()
+        .ok_or_else(|| "authorized GraphQL role surface is unavailable".to_string())?;
+    let executed = super::query_protocol::execute_query_with_protocol(
+        inner,
+        role_surface,
+        protocol.clone(),
+        plan,
+        Some(requested_live_resume),
+    )
+    .await?;
+    let hash = protocol_response_hash(&executed.value, &executed.snapshot, &executed.live);
+    let next_live_resume = executed
+        .live
+        .as_ref()
+        .filter(|live| live.supported)
+        .map(|live| RequestedLiveResume::Cursors(live.cursors.clone()))
+        .unwrap_or(RequestedLiveResume::Absent);
+    Ok(ExecutedLiveQuery {
+        value: executed.value,
+        hash,
+        snapshot: Some(executed.snapshot),
+        live: executed.live,
+        next_live_resume,
+    })
+}
+
+fn footprint_hits(footprint: &BTreeSet<String>, change: &ReadModelChange) -> bool {
+    // Empty tables = all-dirty (lag signal from forwarder).
+    if change.tables.is_empty() {
+        return true;
+    }
+    change.tables.iter().any(|t| footprint.contains(t))
+}
+
+/// Compute the table footprint of a compiled plan (for dirty matching).
+pub fn footprint_from_tables(tables: &[String]) -> BTreeSet<String> {
+    tables.iter().cloned().collect()
+}
+
+/// Hash a GraphQL JSON payload for hash-gated push (no push on no-change).
+pub fn response_hash(value: &Value) -> u64 {
+    use std::collections::hash_map::DefaultHasher;
+    use std::hash::{Hash, Hasher};
+    let mut h = DefaultHasher::new();
+    if let Ok(json) = serde_json::to_string(value) {
+        json.hash(&mut h);
+    } else {
+        format!("{value:?}").hash(&mut h);
+    }
+    h.finish()
+}
+
+fn protocol_response_hash(
+    value: &Value,
+    snapshot: &super::protocol::DistributedQuerySnapshot,
+    live: &Option<super::protocol::DistributedLiveMetadata>,
+) -> u64 {
+    use std::collections::hash_map::DefaultHasher;
+    use std::hash::{Hash, Hasher};
+    let mut hash = DefaultHasher::new();
+    match serde_json::to_string(&(value, snapshot, live)) {
+        Ok(encoded) => encoded.hash(&mut hash),
+        Err(_) => format!("{value:?}:{snapshot:?}:{live:?}").hash(&mut hash),
+    }
+    hash.finish()
+}
+
+/// Forward an external change receiver into the engine hub.
+pub fn spawn_change_forwarder(hub: ChangeHub, rx: broadcast::Receiver<ReadModelChange>) {
+    hub.spawn_forward_from(rx);
+}
diff --git a/src/graphql/surface/application.rs b/src/graphql/surface/application.rs
new file mode 100644
index 00000000..ab3dae90
--- /dev/null
+++ b/src/graphql/surface/application.rs
@@ -0,0 +1,616 @@
+use super::*;
+
+/// Role grant used by [`surface_for_role`] (feature-free; maps from `ReadPermission`
+/// when the `graphql` feature is enabled).
+#[derive(Clone, Debug)]
+pub struct RoleGrant {
+    pub all_columns: bool,
+    pub columns: BTreeSet<String>,
+    pub aggregations: bool,
+    pub row_policy: SurfaceRowPolicy,
+    pub limit: Option<u64>,
+}
+
+impl RoleGrant {
+    pub fn all_columns() -> Self {
+        Self {
+            all_columns: true,
+            columns: BTreeSet::new(),
+            aggregations: false,
+            row_policy: SurfaceRowPolicy::Unrestricted,
+            limit: None,
+        }
+    }
+
+    pub fn columns<I: IntoIterator<Item = impl Into<String>>>(cols: I) -> Self {
+        Self {
+            all_columns: false,
+            columns: cols.into_iter().map(Into::into).collect(),
+            aggregations: false,
+            row_policy: SurfaceRowPolicy::Unrestricted,
+            limit: None,
+        }
+    }
+
+    pub fn with_aggregations(mut self) -> Self {
+        self.aggregations = true;
+        self
+    }
+
+    pub fn rows(mut self, predicate: FilterExpr) -> Self {
+        self.row_policy = SurfaceRowPolicy::Predicate(predicate);
+        self
+    }
+
+    pub fn server_only_rows(mut self) -> Self {
+        self.row_policy = SurfaceRowPolicy::ServerOnly;
+        self
+    }
+
+    pub fn limit(mut self, limit: u64) -> Self {
+        self.limit = Some(limit);
+        self
+    }
+
+    pub fn allows_column(&self, name: &str) -> bool {
+        self.all_columns || self.columns.contains(name)
+    }
+}
+
+/// Build a role→grant map for one role from `(model_name, role) → grant` entries.
+///
+/// Entries whose role does not match are ignored. Used by export/SDL and engine
+/// adapters that already store grants keyed by `(model, role)`.
+pub fn role_grants_for_role(
+    role: &str,
+    model_role_grants: &BTreeMap<(String, String), RoleGrant>,
+) -> BTreeMap<String, RoleGrant> {
+    let mut out = BTreeMap::new();
+    for ((model, r), grant) in model_role_grants {
+        if r == role {
+            out.insert(model.clone(), grant.clone());
+        }
+    }
+    out
+}
+
+/// Apply role grants: drop ungranted models and columns (and relationships to
+/// dropped models). Aggregate roots omitted when `aggregations` is false.
+///
+/// `grants`: map of model_name → grant for this role. Missing model = not granted.
+/// Returns an error when a row policy contains a literal that cannot be
+/// represented faithfully by the shared runtime/client contract.
+pub fn surface_for_role(
+    surface: &Surface,
+    role: &str,
+    grants: &BTreeMap<String, RoleGrant>,
+) -> Result<Surface, String> {
+    // Validate the complete declared topology before authorization filtering.
+    // Only a projector hidden by a valid role selection may become
+    // `confirmation_unavailable`; an omitted catalog topology is an error.
+    validate_command_confirmation_topology(
+        &surface.commands,
+        &surface.projectors,
+        &surface.models,
+    )?;
+    validate_role_grants(surface, role, grants)?;
+    let mut models: BTreeMap<String, SurfaceModel> = BTreeMap::new();
+
+    for (model_name, model) in &surface.models {
+        let Some(grant) = grants.get(model_name) else {
+            continue;
+        };
+
+        let allowed_cols: BTreeSet<String> = model
+            .columns
+            .iter()
+            .filter(|c| grant.allows_column(&c.name))
+            .map(|c| c.name.clone())
+            .collect();
+
+        let columns: Vec<ColumnField> = model
+            .columns
+            .iter()
+            .filter(|c| allowed_cols.contains(&c.name))
+            .cloned()
+            .collect();
+
+        let mut schema = model.schema.clone();
+        for col in &mut schema.columns {
+            if !col.skipped && !allowed_cols.contains(&col.column_name) {
+                col.skipped = true;
+            }
+        }
+
+        models.insert(
+            model_name.clone(),
+            SurfaceModel {
+                model_name: model.model_name.clone(),
+                table_name: model.table_name.clone(),
+                object_name: model.object_name.clone(),
+                columns,
+                relationships: model.relationships.clone(),
+                primary_key: model.primary_key.clone(),
+                row_policy: grant.row_policy.clone(),
+                role_limit: grant.limit,
+                aggregations: grant.aggregations,
+                schema,
+            },
+        );
+    }
+
+    // Relationships only if target model remains granted (collect keys first).
+    let model_keys: BTreeSet<String> = models.keys().cloned().collect();
+    for model in models.values_mut() {
+        model
+            .relationships
+            .retain(|r| model_keys.contains(&r.target_model));
+        let rel_names: BTreeSet<String> =
+            model.relationships.iter().map(|r| r.name.clone()).collect();
+        model
+            .schema
+            .relationships
+            .retain(|r| model_keys.contains(&r.target_model) && rel_names.contains(&r.field_name));
+    }
+
+    validate_selected_composite_relationships(&models)?;
+    sanitize_relationship_identity(&mut models);
+
+    let aggregate_targets: BTreeMap<String, bool> = models
+        .iter()
+        .map(|(name, model)| (name.clone(), model.aggregations))
+        .collect();
+    for model in models.values_mut() {
+        for relationship in &mut model.relationships {
+            if !aggregate_targets
+                .get(&relationship.target_model)
+                .copied()
+                .unwrap_or(false)
+            {
+                relationship.aggregate = None;
+            } else if let Some(aggregate) = &mut relationship.aggregate {
+                aggregate.dependencies = relationship.dependencies.clone();
+            }
+        }
+    }
+
+    // A row predicate is portable only when every referenced model/field is
+    // present on this selected surface. Otherwise retain the authorization
+    // fact as `ServerOnly` without leaking the hidden dependency.
+    let model_names: Vec<String> = models.keys().cloned().collect();
+    for model_name in model_names {
+        let policy = models[&model_name].row_policy.clone();
+        if let SurfaceRowPolicy::Predicate(predicate) = &policy {
+            if !filter_is_surface_visible(predicate, &model_name, &models)
+                || !predicate.is_client_portable()
+            {
+                models.get_mut(&model_name).expect("model key").row_policy =
+                    SurfaceRowPolicy::ServerOnly;
+            }
+        }
+    }
+
+    let mut query_fields = Vec::new();
+    let mut subscription_fields = Vec::new();
+    for model in models.values() {
+        let grant = grants.get(&model.model_name);
+        let allow_agg = surface.aggregates && grant.is_some_and(|g| g.aggregations);
+        let list = root_list_field(&model.schema).to_string();
+        let by_pk = by_pk_field(&model.schema);
+        query_fields.push(root_field(
+            model,
+            list.clone(),
+            RootKind::List,
+            surface.default_limit,
+            surface.max_limit,
+        ));
+        let stable_key_visible = !model.primary_key.is_empty()
+            && model
+                .primary_key
+                .iter()
+                .all(|key| model.columns.iter().any(|column| column.name == *key));
+        if stable_key_visible {
+            query_fields.push(root_field(
+                model,
+                by_pk.clone(),
+                RootKind::ByPk,
+                surface.default_limit,
+                surface.max_limit,
+            ));
+        }
+        if allow_agg {
+            query_fields.push(root_field(
+                model,
+                format!("{}_aggregate", model.table_name),
+                RootKind::Aggregate,
+                surface.default_limit,
+                surface.max_limit,
+            ));
+        }
+        if surface.subscriptions {
+            subscription_fields.push(root_field(
+                model,
+                list,
+                RootKind::List,
+                surface.default_limit,
+                surface.max_limit,
+            ));
+        }
+    }
+    query_fields.sort_by(|a, b| a.name.cmp(&b.name));
+    subscription_fields.sort_by(|a, b| a.name.cmp(&b.name));
+
+    let postgres_json = include_postgres_json_comparison_ops(surface.dialect.is_postgres());
+    let mut used_scalars: BTreeSet<String> = BTreeSet::new();
+    for m in models.values() {
+        for c in &m.columns {
+            used_scalars.insert(c.scalar.clone());
+        }
+    }
+    let mut comparison_ops = BTreeMap::new();
+    for scalar in &used_scalars {
+        let ops = comparison_op_fields(scalar, postgres_json);
+        comparison_ops.insert(
+            comparison_exp_name(scalar),
+            ops.into_iter().map(str::to_string).collect(),
+        );
+    }
+
+    let aggregates = query_fields.iter().any(|f| f.kind == RootKind::Aggregate);
+
+    let mut commands: Vec<SurfaceCommand> = surface
+        .commands
+        .iter()
+        .filter(|command| {
+            command.roles.is_empty() || command.roles.iter().any(|allowed| allowed == role)
+        })
+        .cloned()
+        .collect();
+    for command in &mut commands {
+        command.roles = vec![role.to_string()];
+    }
+    sanitize_command_effects_for_models(&mut commands, &models);
+
+    let mut projectors = Vec::new();
+    for projector in &surface.projectors {
+        // Facts do not carry per-model provenance. If any target is denied,
+        // retaining a subset would leak fact IDs/topology from that denied
+        // domain, so omit the whole projector.
+        if projector
+            .models
+            .iter()
+            .any(|model| !models.contains_key(model))
+        {
+            continue;
+        }
+        let dependencies = projector
+            .models
+            .iter()
+            .filter_map(|model| models.get(model).map(|model| model.table_name.clone()))
+            .collect();
+        projectors.push(SurfaceProjectionOwner {
+            name: projector.name.clone(),
+            facts: projector.facts.clone(),
+            models: projector.models.clone(),
+            dependencies,
+            change_epoch: projector.change_epoch.clone(),
+            partition: projector.partition.clone(),
+            kind: projector.kind,
+        });
+    }
+    sanitize_command_confirmations(&mut commands, &projectors, &models);
+
+    Ok(Surface {
+        selection: SurfaceSelection::Role {
+            name: role.to_string(),
+        },
+        dialect: surface.dialect,
+        aggregates,
+        subscriptions: surface.subscriptions,
+        default_limit: surface.default_limit,
+        max_limit: surface.max_limit,
+        catalog: surface.catalog.clone(),
+        models,
+        query_fields,
+        subscription_fields,
+        comparison_ops,
+        commands,
+        commands_attached: surface.commands_attached,
+        projectors,
+        projectors_attached: surface.projectors_attached,
+        service_binding: surface.service_binding.clone(),
+    })
+}
+
+/// Composite identities are valid for isolated roots. Relationship compilation
+/// still uses a single-column join contract, so reject the topology only when
+/// both ends are reachable on this selected authorization surface. Keeping the
+/// check here makes runtime role schemas and pool-free/dctl exports fail at the
+/// same boundary without rejecting unrelated hidden catalog metadata.
+pub(in crate::graphql::surface) fn validate_selected_composite_relationships(
+    models: &BTreeMap<String, SurfaceModel>,
+) -> Result<(), String> {
+    for model in models.values() {
+        let pk_n = model.primary_key.len();
+        if pk_n <= 1 {
+            continue;
+        }
+        let relationship_topology = !model.relationships.is_empty()
+            || models.values().any(|candidate| {
+                candidate
+                    .relationships
+                    .iter()
+                    .any(|relationship| relationship.target_model == model.model_name)
+            });
+        if relationship_topology {
+            return Err(format!(
+                "model `{}` has a {pk_n}-column primary key and relationship topology; composite-key GraphQL models are supported only as isolated roots until composite relationship keys are implemented",
+                model.model_name
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(in crate::graphql::surface) fn validate_role_grants(
+    surface: &Surface,
+    role: &str,
+    grants: &BTreeMap<String, RoleGrant>,
+) -> Result<(), String> {
+    for (model, grant) in grants {
+        let selected_model = surface
+            .models
+            .get(model)
+            .ok_or_else(|| format!("permission for unknown model `{model}` in surface `{role}`"))?;
+
+        if !grant.all_columns {
+            for column in &grant.columns {
+                if !selected_model
+                    .schema
+                    .columns
+                    .iter()
+                    .any(|candidate| candidate.column_name == *column && !candidate.skipped)
+                {
+                    return Err(format!(
+                        "unknown column `{column}` in permission for `{model}` surface `{role}`"
+                    ));
+                }
+            }
+        }
+
+        if let SurfaceRowPolicy::Predicate(predicate) = &grant.row_policy {
+            predicate.validate_row_policy_literals().map_err(|error| {
+                format!("invalid row policy for model `{model}` in surface `{role}`: {error}")
+            })?;
+            validate_surface_filter(
+                predicate,
+                &selected_model.schema,
+                &surface.catalog,
+                model,
+                role,
+            )?;
+        }
+    }
+    Ok(())
+}
+
+/// Validate the executable row-policy graph against the same complete catalog
+/// used by the runtime compiler. This deliberately permits policy references
+/// to denied columns/models (the policy remains server-enforced) while rejecting
+/// identifiers and relationship shapes that the runtime cannot compile.
+pub(in crate::graphql::surface) fn validate_surface_filter(
+    filter: &FilterExpr,
+    schema: &TableSchema,
+    catalog: &BTreeMap<String, TableSchema>,
+    model: &str,
+    role: &str,
+) -> Result<(), String> {
+    match filter {
+        FilterExpr::And(items) | FilterExpr::Or(items) => {
+            for item in items {
+                validate_surface_filter(item, schema, catalog, model, role)?;
+            }
+        }
+        FilterExpr::Not(item) => {
+            validate_surface_filter(item, schema, catalog, model, role)?;
+        }
+        FilterExpr::Cmp { column, op, rhs } => {
+            let column_schema = schema
+                .columns
+                .iter()
+                .find(|candidate| candidate.column_name == *column)
+                .ok_or_else(|| {
+                    format!("unknown column `{column}` in filter for `{model}` surface `{role}`")
+                })?;
+            if matches!(column_schema.column_type, ColumnType::Json)
+                && matches!(rhs, Operand::Claim(_))
+            {
+                return Err(format!(
+                    "claims cannot compare to Json columns (`{column}` on `{model}`)"
+                ));
+            }
+            validate_row_policy_operand_literal(column, &column_schema.column_type, Some(*op), rhs)
+                .map_err(|error| {
+                    format!("invalid row policy for model `{model}` surface `{role}`: {error}")
+                })?;
+        }
+        FilterExpr::In { column, values, .. } => {
+            let column_schema = schema
+                .columns
+                .iter()
+                .find(|candidate| candidate.column_name == *column)
+                .ok_or_else(|| {
+                    format!("unknown column `{column}` in filter for `{model}` surface `{role}`")
+                })?;
+            for (index, value) in values.iter().enumerate() {
+                validate_row_policy_operand_literal(
+                    column,
+                    &column_schema.column_type,
+                    None,
+                    value,
+                )
+                .map_err(|error| {
+                        format!(
+                            "invalid row policy for model `{model}` surface `{role}` IN operand {index}: {error}"
+                        )
+                    })?;
+            }
+        }
+        FilterExpr::IsNull { column, .. } => {
+            if !schema
+                .columns
+                .iter()
+                .any(|candidate| candidate.column_name == *column)
+            {
+                return Err(format!(
+                    "unknown column `{column}` in filter for `{model}` surface `{role}`"
+                ));
+            }
+        }
+        FilterExpr::Rel { field, predicate } => {
+            let relationship = schema
+                .relationships
+                .iter()
+                .find(|candidate| candidate.field_name == *field)
+                .ok_or_else(|| {
+                    format!("rel(`{field}`) is not a relationship on model `{model}`")
+                })?;
+            let target = catalog.get(&relationship.target_model).ok_or_else(|| {
+                format!(
+                    "rel(`{field}`) target `{}` is not in the catalog (model `{model}`)",
+                    relationship.target_model
+                )
+            })?;
+
+            if schema.primary_key.columns.len() > 1 || target.primary_key.columns.len() > 1 {
+                return Err(format!(
+                    "row policy for model `{model}` surface `{role}` traverses relationship `{field}` with composite-key topology; composite relationship keys are not implemented"
+                ));
+            }
+
+            if matches!(relationship.kind, RelationshipKind::ManyToMany) {
+                let through = relationship.through.as_deref().ok_or_else(|| {
+                    format!("rel(`{field}`) many-to-many missing through on `{model}`")
+                })?;
+                if !catalog
+                    .values()
+                    .any(|candidate| candidate.table_name == through)
+                {
+                    return Err(format!(
+                        "rel(`{field}`) through table `{through}` not in catalog"
+                    ));
+                }
+            }
+            validate_surface_filter(predicate, target, catalog, &relationship.target_model, role)?;
+        }
+    }
+    Ok(())
+}
+
+/// Build an explicit named application surface as the structural intersection
+/// of all runtime roles it supports.
+///
+/// A missing role declaration is an error rather than an accidental empty or
+/// admin surface. Commands must be granted to every role; differing row
+/// predicates become `ServerOnly`, so the client revalidates membership without
+/// learning another role's policy.
+pub fn surface_for_application(
+    surface: &Surface,
+    application: &str,
+    roles: &[String],
+    grants_by_role: &BTreeMap<String, BTreeMap<String, RoleGrant>>,
+) -> Result<Surface, String> {
+    if application.trim().is_empty() {
+        return Err("application surface name must not be empty".into());
+    }
+    let mut roles = roles.to_vec();
+    roles.sort();
+    roles.dedup();
+    if roles.is_empty() {
+        return Err(format!(
+            "application surface `{application}` must declare at least one role"
+        ));
+    }
+    for role in &roles {
+        let Some(grants) = grants_by_role.get(role) else {
+            return Err(format!(
+                "application surface `{application}` references undeclared role `{role}`"
+            ));
+        };
+        // Validate every concrete role before intersecting it. Differing
+        // predicates collapse to ServerOnly below, but that must not hide a
+        // malformed identifier or unsupported relationship traversal.
+        let _ = surface_for_role(surface, role, grants)?;
+    }
+
+    let mut common = BTreeMap::new();
+    for (model_name, model) in &surface.models {
+        let grants: Option<Vec<&RoleGrant>> = roles
+            .iter()
+            .map(|role| {
+                grants_by_role
+                    .get(role)
+                    .and_then(|grants| grants.get(model_name))
+            })
+            .collect();
+        let Some(grants) = grants else {
+            continue;
+        };
+
+        let columns: BTreeSet<String> = model
+            .columns
+            .iter()
+            .map(|column| column.name.clone())
+            .filter(|column| grants.iter().all(|grant| grant.allows_column(column)))
+            .collect();
+        let aggregations = grants.iter().all(|grant| grant.aggregations);
+        let first_policy = grants[0].row_policy.clone();
+        let row_policy = if grants.iter().all(|grant| grant.row_policy == first_policy) {
+            first_policy
+        } else {
+            SurfaceRowPolicy::ServerOnly
+        };
+        let limit = grants.iter().filter_map(|grant| grant.limit).min();
+        common.insert(
+            model_name.clone(),
+            RoleGrant {
+                all_columns: false,
+                columns,
+                aggregations,
+                row_policy,
+                limit,
+            },
+        );
+    }
+
+    let mut selected = surface_for_role(surface, application, &common)?;
+    selected.commands = surface
+        .commands
+        .iter()
+        .filter(|command| {
+            command.roles.is_empty()
+                || roles
+                    .iter()
+                    .all(|role| command.roles.iter().any(|allowed| allowed == role))
+        })
+        .cloned()
+        .map(|mut command| {
+            command.roles = roles.clone();
+            command
+        })
+        .collect();
+    sanitize_command_effects_for_models(&mut selected.commands, &selected.models);
+    sanitize_command_confirmations(
+        &mut selected.commands,
+        &selected.projectors,
+        &selected.models,
+    );
+    selected
+        .commands
+        .sort_by(|a, b| a.command_name.cmp(&b.command_name));
+    selected.selection = SurfaceSelection::Application {
+        name: application.to_string(),
+        roles,
+    };
+    Ok(selected)
+}
diff --git a/src/graphql/surface/build.rs b/src/graphql/surface/build.rs
new file mode 100644
index 00000000..28ae2db7
--- /dev/null
+++ b/src/graphql/surface/build.rs
@@ -0,0 +1,280 @@
+use super::*;
+
+pub fn build_surface(tables: &[TableSchema], options: &SurfaceOptions) -> Result<Surface, String> {
+    let mut catalog = BTreeMap::new();
+    let mut all_table_ids = BTreeSet::new();
+    for schema in tables {
+        schema
+            .validate()
+            .map_err(|e| format!("schema `{}` invalid: {e}", schema.model_name))?;
+        if schema.model_name.trim().is_empty() {
+            return Err("table model id must not be empty".into());
+        }
+        if catalog
+            .insert(schema.model_name.clone(), schema.clone())
+            .is_some()
+        {
+            return Err(format!(
+                "duplicate table model id `{}` in Surface catalog",
+                schema.model_name
+            ));
+        }
+        if !all_table_ids.insert(schema.table_name.clone()) {
+            return Err(format!(
+                "table id `{}` collides with another table in Surface catalog",
+                schema.table_name
+            ));
+        }
+    }
+    let read_models: Vec<&TableSchema> = tables.iter().filter(|t| t.kind.is_read_model()).collect();
+
+    let mut model_ids = BTreeSet::new();
+    let mut table_ids = BTreeSet::new();
+    let mut object_ids = BTreeSet::new();
+    for schema in &read_models {
+        if schema.model_name.trim().is_empty() {
+            return Err("read model id must not be empty".into());
+        }
+        if !model_ids.insert(schema.model_name.clone()) {
+            return Err(format!(
+                "duplicate read model id `{}` in Surface inventory",
+                schema.model_name
+            ));
+        }
+        if !table_ids.insert(schema.table_name.clone()) {
+            return Err(format!(
+                "duplicate read-model table id `{}` in Surface inventory",
+                schema.table_name
+            ));
+        }
+        let object_id = object_type_name(schema).to_string();
+        if !object_ids.insert(object_id.clone()) {
+            return Err(format!(
+                "duplicate GraphQL object id `{object_id}` in Surface inventory"
+            ));
+        }
+        let mut relationship_ids = BTreeSet::new();
+        for relationship in &schema.relationships {
+            if relationship.field_name.trim().is_empty() {
+                return Err(format!(
+                    "model `{}` has a relationship with an empty field id",
+                    schema.model_name
+                ));
+            }
+            if !relationship_ids.insert(relationship.field_name.clone()) {
+                return Err(format!(
+                    "model `{}` declares duplicate relationship field `{}`",
+                    schema.model_name, relationship.field_name
+                ));
+            }
+            if matches!(relationship.kind, RelationshipKind::ManyToMany)
+                && relationship.through.is_none()
+            {
+                return Err(format!(
+                    "model `{}` relationship `{}` many-to-many must declare `through`",
+                    schema.model_name, relationship.field_name
+                ));
+            }
+        }
+    }
+
+    let by_model: BTreeMap<&str, &TableSchema> = read_models
+        .iter()
+        .map(|t| (t.model_name.as_str(), *t))
+        .collect();
+    // All tables (incl. operational / unexposed join tables) so m2m
+    // relationship_emitted can resolve `through` for bool_exp + object fields.
+    let by_table: BTreeMap<&str, &TableSchema> =
+        tables.iter().map(|t| (t.table_name.as_str(), t)).collect();
+
+    let postgres_json = include_postgres_json_comparison_ops(options.dialect.is_postgres());
+    let mut used_scalars: BTreeSet<String> = BTreeSet::new();
+    let mut models: BTreeMap<String, SurfaceModel> = BTreeMap::new();
+
+    for schema in &read_models {
+        let object_name = object_type_name(schema).to_string();
+        if !is_valid_graphql_name(&object_name) {
+            return Err(format!(
+                "object type `{object_name}` is not a valid GraphQL name"
+            ));
+        }
+        if !is_valid_graphql_name(root_list_field(schema)) {
+            return Err(format!(
+                "root field `{}` is not a valid GraphQL name",
+                root_list_field(schema)
+            ));
+        }
+
+        let mut columns = Vec::new();
+        for col in visible_columns(schema) {
+            if !is_valid_graphql_name(&col.column_name) {
+                return Err(format!(
+                    "model `{}` column `{}` is not a valid GraphQL name",
+                    schema.model_name, col.column_name
+                ));
+            }
+            let Some(scalar) = scalar_type_name(&col.column_type) else {
+                return Err(format!(
+                    "model `{}` column `{}` has unsupported type",
+                    schema.model_name, col.column_name
+                ));
+            };
+            used_scalars.insert(scalar.to_string());
+            columns.push(ColumnField {
+                name: col.column_name.clone(),
+                scalar: scalar.to_string(),
+                nullable: col.nullable,
+            });
+        }
+
+        let mut relationships = Vec::new();
+        for rel in &schema.relationships {
+            if !is_valid_graphql_name(&rel.field_name) {
+                return Err(format!(
+                    "model `{}` relationship `{}` is not a valid GraphQL name",
+                    schema.model_name, rel.field_name
+                ));
+            }
+            if !relationship_emitted(schema, rel, &by_model, &by_table) {
+                continue;
+            }
+            let target = by_model
+                .get(rel.target_model.as_str())
+                .expect("relationship_emitted");
+            let list = matches!(
+                rel.kind,
+                RelationshipKind::HasMany | RelationshipKind::ManyToMany
+            );
+            let nullable = if matches!(rel.kind, RelationshipKind::BelongsTo) {
+                schema
+                    .columns
+                    .iter()
+                    .find(|column| {
+                        rel.foreign_key.as_deref().is_some_and(|key| {
+                            column.column_name == key || column.field_name == key
+                        })
+                    })
+                    .map(|column| column.nullable)
+                    .unwrap_or(true)
+            } else {
+                false
+            };
+            let (keys, mut dependencies) = relationship_keys(schema, rel, target, &by_table)?;
+            dependencies.sort();
+            dependencies.dedup();
+            relationships.push(RelField {
+                name: rel.field_name.clone(),
+                target_model: rel.target_model.clone(),
+                target_object: object_type_name(target).to_string(),
+                kind: rel.kind.clone(),
+                list,
+                nullable,
+                arguments: if list {
+                    list_arguments(target)
+                } else {
+                    Vec::new()
+                },
+                keys,
+                aggregate: (options.aggregates && list).then(|| SurfaceRelationshipAggregate {
+                    name: format!("{}_aggregate", rel.field_name),
+                    type_name: format!("{}_aggregate", target.table_name),
+                    arguments: vec![SurfaceArgument {
+                        name: "where".into(),
+                        kind: SurfaceArgumentKind::Filter,
+                        type_name: format!("{}_bool_exp", target.table_name),
+                        nullable: true,
+                        list: false,
+                    }],
+                    dependencies: dependencies.clone(),
+                }),
+                dependencies,
+            });
+        }
+
+        models.insert(
+            schema.model_name.clone(),
+            SurfaceModel {
+                model_name: schema.model_name.clone(),
+                table_name: schema.table_name.clone(),
+                object_name,
+                columns,
+                relationships,
+                primary_key: schema.primary_key.columns.clone(),
+                row_policy: SurfaceRowPolicy::Unrestricted,
+                role_limit: None,
+                aggregations: options.aggregates,
+                schema: (*schema).clone(),
+            },
+        );
+    }
+
+    // Drop relationships whose target was not included (defensive).
+    let model_keys: BTreeSet<String> = models.keys().cloned().collect();
+    for model in models.values_mut() {
+        model
+            .relationships
+            .retain(|r| model_keys.contains(&r.target_model));
+    }
+
+    sanitize_relationship_identity(&mut models);
+
+    let aggregate_targets: BTreeMap<String, bool> = models
+        .iter()
+        .map(|(name, model)| (name.clone(), model.aggregations))
+        .collect();
+    for model in models.values_mut() {
+        for relationship in &mut model.relationships {
+            if !aggregate_targets
+                .get(&relationship.target_model)
+                .copied()
+                .unwrap_or(false)
+            {
+                relationship.aggregate = None;
+            } else if let Some(aggregate) = &mut relationship.aggregate {
+                aggregate.dependencies = relationship.dependencies.clone();
+            }
+        }
+    }
+
+    let mut comparison_ops = BTreeMap::new();
+    for scalar in &used_scalars {
+        let ops = comparison_op_fields(scalar, postgres_json);
+        comparison_ops.insert(
+            comparison_exp_name(scalar),
+            ops.into_iter().map(str::to_string).collect(),
+        );
+    }
+    // Always reserve custom scalar names for naming collisions checks downstream.
+    let _ = CUSTOM_SCALARS;
+
+    let (query_fields, subscription_fields) = root_fields_for_models(
+        &models,
+        options.aggregates,
+        options.subscriptions,
+        options.default_limit,
+        options.max_limit,
+    );
+
+    validate_root_ids(&query_fields, "query")?;
+    validate_root_ids(&subscription_fields, "subscription")?;
+    validate_generated_surface_names(&models, &comparison_ops)?;
+
+    Ok(Surface {
+        selection: SurfaceSelection::Catalog,
+        dialect: options.dialect,
+        aggregates: options.aggregates,
+        subscriptions: options.subscriptions,
+        default_limit: options.default_limit,
+        max_limit: options.max_limit,
+        catalog,
+        models,
+        query_fields,
+        subscription_fields,
+        comparison_ops,
+        commands: Vec::new(),
+        commands_attached: false,
+        projectors: Vec::new(),
+        projectors_attached: false,
+        service_binding: None,
+    })
+}
diff --git a/src/graphql/surface/commands.rs b/src/graphql/surface/commands.rs
new file mode 100644
index 00000000..6c13bd3a
--- /dev/null
+++ b/src/graphql/surface/commands.rs
@@ -0,0 +1,666 @@
+use super::*;
+
+pub(in crate::graphql::surface) fn validate_and_canonicalize_commands(
+    models: &BTreeMap<String, SurfaceModel>,
+    comparison_ops: &BTreeMap<String, Vec<String>>,
+    commands: &mut [SurfaceCommand],
+) -> Result<(), String> {
+    let mut names = BTreeSet::new();
+    let mut fields = BTreeSet::new();
+    let mut type_defs: BTreeMap<String, (bool, SurfaceTypeDef)> = BTreeMap::new();
+    let mut occupied_types: BTreeSet<String> = reserved_type_names().map(str::to_string).collect();
+    occupied_types.extend(comparison_ops.keys().cloned());
+    for model in models.values() {
+        occupied_types.insert(model.object_name.clone());
+        occupied_types.insert(format!("{}_bool_exp", model.table_name));
+        occupied_types.insert(format!("{}_order_by", model.table_name));
+        if model.aggregations {
+            occupied_types.insert(format!("{}_aggregate", model.table_name));
+            occupied_types.insert(format!("{}_aggregate_fields", model.table_name));
+        }
+    }
+    for command in commands.iter_mut() {
+        if command.command_name.trim().is_empty() {
+            return Err("command id must not be empty".into());
+        }
+        if !names.insert(command.command_name.clone()) {
+            return Err(format!("duplicate command id `{}`", command.command_name));
+        }
+        if !is_valid_graphql_name(&command.field_name) {
+            return Err(format!(
+                "command `{}` mutation field `{}` is not a valid GraphQL name",
+                command.command_name, command.field_name
+            ));
+        }
+        if !fields.insert(command.field_name.clone()) {
+            return Err(format!(
+                "duplicate command mutation field `{}`",
+                command.field_name
+            ));
+        }
+        validate_nonempty_unique_ids(
+            &command.roles,
+            &format!("command `{}` role", command.command_name),
+        )?;
+        command.roles.sort();
+        match &mut command.input {
+            SurfaceCommandShape::Typed(definition) => {
+                canonicalize_type_def(definition)?;
+                reject_occupied_command_types(definition, &occupied_types)?;
+                register_type_def(definition, true, &mut type_defs)?;
+            }
+            SurfaceCommandShape::None => {}
+        }
+        let output_command_name = command.command_name.clone();
+        let output_consistency = command.consistency;
+        let output_projected_model = command.projected_model.clone();
+        match &mut command.output {
+            SurfaceCommandShape::None => {
+                return Err(format!(
+                    "command `{}` cannot declare an empty output",
+                    command.command_name
+                ));
+            }
+            SurfaceCommandShape::Typed(definition) => {
+                canonicalize_type_def(definition)?;
+                if projected_output_reuses_surface_model(
+                    &output_command_name,
+                    output_consistency,
+                    output_projected_model.as_ref(),
+                    definition,
+                    models,
+                )? {
+                    // `Projected<M>` deliberately returns the already-exposed
+                    // normalized model object. Do not claim or re-emit a second
+                    // GraphQL type with the same name.
+                } else {
+                    reject_occupied_command_types(definition, &occupied_types)?;
+                    register_type_def(definition, false, &mut type_defs)?;
+                }
+            }
+        }
+        command
+            .input_defaults
+            .sort_by(|left, right| left.path.cmp(&right.path));
+        validate_command_input_defaults(command)?;
+        validate_command_effects(models, command)?;
+        validate_command_confirmations(models, command)?;
+        command.confirmations.sort_by(|left, right| {
+            serde_json::to_string(&left.canonical_value())
+                .expect("confirmation IR serialization cannot fail")
+                .cmp(
+                    &serde_json::to_string(&right.canonical_value())
+                        .expect("confirmation IR serialization cannot fail"),
+                )
+        });
+    }
+    commands.sort_by(|a, b| a.command_name.cmp(&b.command_name));
+    Ok(())
+}
+
+pub(crate) fn projected_output_reuses_surface_model(
+    command_name: &str,
+    consistency: CommandConsistency,
+    projected: Option<&CommandProjectedModel>,
+    definition: &SurfaceTypeDef,
+    models: &BTreeMap<String, SurfaceModel>,
+) -> Result<bool, String> {
+    if consistency != CommandConsistency::Projected {
+        return Ok(false);
+    }
+    let Some(projected) = projected else {
+        return Ok(false);
+    };
+    let Some(model) = models.get(&projected.model) else {
+        return Ok(false);
+    };
+    if definition.name != model.object_name {
+        return Ok(false);
+    }
+    if definition.fields.len() != model.columns.len() {
+        return Err(format!(
+            "typed projected command `{}` output `{}` does not match the normalized Surface model columns",
+            command_name, definition.name
+        ));
+    }
+    for field in &definition.fields {
+        let Some(column) = model
+            .columns
+            .iter()
+            .find(|column| column.name == field.name)
+        else {
+            return Err(format!(
+                "typed projected command `{}` output `{}` contains non-model field `{}`",
+                command_name, definition.name, field.name
+            ));
+        };
+        if field.type_name != column.scalar
+            || field.nullable != column.nullable
+            || field.list
+            || field.item_nullable
+            || field.nested.is_some()
+        {
+            return Err(format!(
+                "typed projected command `{}` output field `{}.{}` differs from its normalized Surface model column",
+                command_name, definition.name, field.name
+            ));
+        }
+    }
+    Ok(true)
+}
+
+pub(in crate::graphql::surface) fn validate_command_input_defaults(
+    command: &SurfaceCommand,
+) -> Result<(), String> {
+    if command.input_defaults.is_empty() {
+        return Ok(());
+    }
+    let SurfaceCommandShape::Typed(input) = &command.input else {
+        return Err(format!(
+            "typed command `{}` declares generated input defaults on an untyped input",
+            command.command_name
+        ));
+    };
+    let mut paths = BTreeSet::new();
+    for default in &command.input_defaults {
+        if default.path.len() != 1 {
+            return Err(format!(
+                "typed command `{}` generated input default must target exactly one top-level field",
+                command.command_name
+            ));
+        }
+        if !paths.insert(default.path.clone()) {
+            return Err(format!(
+                "typed command `{}` repeats generated input default `{}`",
+                command.command_name,
+                default.path.join(".")
+            ));
+        }
+        let field_name = &default.path[0];
+        let field = input
+            .fields
+            .iter()
+            .find(|field| field.name == *field_name)
+            .ok_or_else(|| {
+                format!(
+                    "typed command `{}` generated input default references unknown field `{field_name}`",
+                    command.command_name
+                )
+            })?;
+        if field.nullable
+            || field.list
+            || field.nested.is_some()
+            || !matches!(field.type_name.as_str(), "String" | "ID")
+        {
+            return Err(format!(
+                "typed command `{}` generated input default `{field_name}` requires a non-null, non-list String/ID field",
+                command.command_name
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(in crate::graphql::surface) fn validate_command_confirmations(
+    models: &BTreeMap<String, SurfaceModel>,
+    command: &SurfaceCommand,
+) -> Result<(), String> {
+    validate_projection_confirmation_count(&command.command_name, command.confirmations.len())?;
+    match command.consistency {
+        CommandConsistency::Fact if command.confirmations.is_empty() => {
+            return Err(format!(
+                "typed fact command `{}` must declare at least one expected projector confirmation",
+                command.command_name
+            ));
+        }
+        CommandConsistency::Projected if !command.confirmations.is_empty() => {
+            return Err(format!(
+                "typed projected command `{}` cannot declare asynchronous projector confirmations",
+                command.command_name
+            ));
+        }
+        CommandConsistency::Projected if command.projected_model.is_none() => {
+            return Err(format!(
+                "typed projected command `{}` is missing its compiler-retained relational model",
+                command.command_name
+            ));
+        }
+        CommandConsistency::Accepted | CommandConsistency::Fact
+            if command.projected_model.is_some() || command.direct_projection.is_some() =>
+        {
+            return Err(format!(
+                "typed non-projected command `{}` cannot carry direct projection metadata",
+                command.command_name
+            ));
+        }
+        _ => {}
+    }
+    if let Some(projected) = &command.projected_model {
+        let model = models.get(&projected.model).ok_or_else(|| {
+            format!(
+                "typed projected command `{}` output references unknown model `{}`",
+                command.command_name, projected.model
+            )
+        })?;
+        if model.table_name != projected.table {
+            return Err(format!(
+                "typed projected command `{}` output model `{}` resolves to table `{}`, not `{}`",
+                command.command_name, projected.model, model.table_name, projected.table
+            ));
+        }
+        if let Some(partition) = &projected.partition {
+            validate_effect_expression(
+                command,
+                partition,
+                &ColumnField {
+                    name: "projector partition".into(),
+                    scalar: "String".into(),
+                    nullable: false,
+                },
+            )?;
+        }
+    }
+    if let Some(target) = &command.direct_projection {
+        let model = models.get(&target.model).ok_or_else(|| {
+            format!(
+                "typed projected command `{}` targets unknown model `{}`",
+                command.command_name, target.model
+            )
+        })?;
+        if model.table_name != target.table {
+            return Err(format!(
+                "typed projected command `{}` target model `{}` resolves to table `{}`, not `{}`",
+                command.command_name, target.model, model.table_name, target.table
+            ));
+        }
+        if let Some(partition) = &target.partition {
+            validate_effect_expression(
+                command,
+                partition,
+                &ColumnField {
+                    name: "projector partition".into(),
+                    scalar: "String".into(),
+                    nullable: false,
+                },
+            )?;
+        }
+    }
+    if command.confirmation_unavailable {
+        return Err(format!(
+            "catalog command `{}` cannot start with an unavailable confirmation plan",
+            command.command_name
+        ));
+    }
+
+    let mut seen = BTreeSet::new();
+    for confirmation in &command.confirmations {
+        if confirmation.projector.trim().is_empty() {
+            return Err(format!(
+                "typed command `{}` confirmation projector must not be empty",
+                command.command_name
+            ));
+        }
+        validate_effect_key(models, command, &confirmation.model, &confirmation.key)?;
+        if let Some(partition) = &confirmation.partition {
+            validate_effect_expression(
+                command,
+                partition,
+                &ColumnField {
+                    name: "projector partition".into(),
+                    scalar: "String".into(),
+                    nullable: false,
+                },
+            )?;
+        }
+        let identity =
+            serde_json::to_string(confirmation).expect("confirmation IR serialization cannot fail");
+        if !seen.insert(identity) {
+            return Err(format!(
+                "typed command `{}` repeats an expected projector confirmation",
+                command.command_name
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(in crate::graphql::surface) fn bind_surface_direct_projection_targets(
+    commands: &mut [SurfaceCommand],
+    projectors: &[SurfaceProjectionOwner],
+    models: &BTreeMap<String, SurfaceModel>,
+) -> Result<(), String> {
+    let mut compiled_projectors = BTreeMap::new();
+    for projector in projectors {
+        let schemas = projector
+            .models
+            .iter()
+            .map(|model_name| {
+                models
+                    .get(model_name)
+                    .map(|model| &model.schema)
+                    .ok_or_else(|| {
+                        format!(
+                            "projector `{}` references unknown model `{model_name}`",
+                            projector.name
+                        )
+                    })
+            })
+            .collect::<Result<Vec<_>, _>>()?;
+        let compiled = compile_projection_topology(
+            &projector.name,
+            &projector.facts,
+            &projector.models,
+            &projector.partition,
+            schemas,
+        )
+        .map_err(|error| {
+            format!(
+                "projector `{}` has invalid compiled topology: {error}",
+                projector.name
+            )
+        })?;
+        compiled_projectors.insert(projector.name.clone(), compiled);
+    }
+
+    for command in commands {
+        for confirmation in &mut command.confirmations {
+            let projector = projectors
+                .iter()
+                .find(|projector| projector.name == confirmation.projector)
+                .ok_or_else(|| {
+                    format!(
+                        "typed command `{}` expects unknown projector `{}`",
+                        command.command_name, confirmation.projector
+                    )
+                })?;
+            if !confirmation.topology_matches(
+                &projector.name,
+                &projector.facts,
+                &projector.models,
+                &projector.partition,
+            ) {
+                return Err(format!(
+                    "typed command `{}` captured projector `{}` topology identity does not match the registered projector facts/models",
+                    command.command_name, confirmation.projector
+                ));
+            }
+            if !confirmation.partition_matches(&projector.partition) {
+                return Err(format!(
+                    "typed command `{}` confirmation for projector `{}` does not provide the partition mapping required by its declaration",
+                    command.command_name, confirmation.projector
+                ));
+            }
+            if !projector
+                .models
+                .iter()
+                .any(|model| model == &confirmation.model)
+            {
+                return Err(format!(
+                    "typed command `{}` expects projector `{}` to confirm model `{}`, but that model is not in the projector topology",
+                    command.command_name, confirmation.projector, confirmation.model
+                ));
+            }
+            let (topology, _) = compiled_projectors
+                .get(&projector.name)
+                .expect("every registered projector was compiled above");
+            confirmation.bind_protocol_topology(topology.clone());
+        }
+
+        if command.consistency != CommandConsistency::Projected {
+            continue;
+        }
+        let projected = command.projected_model.as_ref().ok_or_else(|| {
+            format!(
+                "typed projected command `{}` is missing its compiler-retained relational model",
+                command.command_name
+            )
+        })?;
+        let owners = projectors
+            .iter()
+            .filter(|projector| {
+                projector
+                    .models
+                    .iter()
+                    .any(|model| model == &projected.model)
+            })
+            .collect::<Vec<_>>();
+        let projector = match owners.as_slice() {
+            [projector] => *projector,
+            [] => {
+                return Err(format!(
+                    "typed projected command `{}` output model `{}` has no registered SurfaceProjector owner",
+                    command.command_name, projected.model
+                ))
+            }
+            _ => {
+                return Err(format!(
+                    "typed projected command `{}` output model `{}` has ambiguous SurfaceProjector ownership: {}",
+                    command.command_name,
+                    projected.model,
+                    owners
+                        .iter()
+                        .map(|owner| owner.name.as_str())
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                ))
+            }
+        };
+        if projector.change_epoch.is_none() {
+            return Err(format!(
+                "typed projected command `{}` owner `{}` has no registered change-log epoch",
+                command.command_name, projector.name
+            ));
+        }
+        let registered_schema = &models
+            .get(&projected.model)
+            .expect("projector ownership above requires a registered model")
+            .schema;
+        if projected.schema != registered_schema {
+            return Err(format!(
+                "typed projected command `{}` retained schema for `{}` differs from the registered full table schema",
+                command.command_name, projected.model
+            ));
+        }
+        if !projected.partition_matches(&projector.partition) {
+            return Err(format!(
+                "typed projected command `{}` does not provide the partition mapping required by projector `{}`",
+                command.command_name, projector.name
+            ));
+        }
+        let (protocol_topology, ownership) = compiled_projectors
+            .get(&projector.name)
+            .expect("every registered projector was compiled above");
+        command.direct_projection = Some(projected.bind(
+            &projector.name,
+            &projector.facts,
+            &projector.models,
+            &projector.partition,
+            projector.change_epoch.as_deref(),
+            ownership.clone(),
+            Some(protocol_topology.clone()),
+        ));
+    }
+    Ok(())
+}
+
+pub(in crate::graphql::surface) fn validate_command_confirmation_topology(
+    commands: &[SurfaceCommand],
+    projectors: &[SurfaceProjectionOwner],
+    models: &BTreeMap<String, SurfaceModel>,
+) -> Result<(), String> {
+    let mut compiled_projectors = BTreeMap::new();
+    let mut physical_owners = BTreeMap::new();
+    for projector in projectors {
+        let schemas = projector
+            .models
+            .iter()
+            .map(|model_name| {
+                models
+                    .get(model_name)
+                    .map(|model| &model.schema)
+                    .ok_or_else(|| {
+                        format!(
+                            "projector `{}` references unknown model `{model_name}`",
+                            projector.name
+                        )
+                    })
+            })
+            .collect::<Result<Vec<_>, _>>()?;
+        let compiled = compile_projection_topology(
+            &projector.name,
+            &projector.facts,
+            &projector.models,
+            &projector.partition,
+            schemas,
+        )
+        .map_err(|error| {
+            format!(
+                "projector `{}` has invalid compiled topology: {error}",
+                projector.name
+            )
+        })?;
+        for owner in &compiled.1 {
+            if let Some((existing_projector, existing_model)) = physical_owners.insert(
+                owner.table.clone(),
+                (projector.name.clone(), owner.model.clone()),
+            ) {
+                return Err(format!(
+                    "physical table `{}` has multiple projector owners: `{existing_projector}`/`{existing_model}` and `{}`/`{}`",
+                    owner.table, projector.name, owner.model
+                ));
+            }
+        }
+        compiled_projectors.insert(projector.name.clone(), compiled);
+    }
+
+    for command in commands {
+        for confirmation in &command.confirmations {
+            let projector = projectors
+                .iter()
+                .find(|projector| projector.name == confirmation.projector)
+                .ok_or_else(|| {
+                    format!(
+                        "typed command `{}` expects unknown projector `{}`",
+                        command.command_name, confirmation.projector
+                    )
+                })?;
+            if !projector
+                .models
+                .iter()
+                .any(|model| model == &confirmation.model)
+            {
+                return Err(format!(
+                    "typed command `{}` expects projector `{}` to confirm model `{}`, but that model is not in the projector topology",
+                    command.command_name, confirmation.projector, confirmation.model
+                ));
+            }
+            if !confirmation.topology_matches(
+                &projector.name,
+                &projector.facts,
+                &projector.models,
+                &projector.partition,
+            ) {
+                return Err(format!(
+                    "typed command `{}` captured projector `{}` topology identity does not match the registered projector facts/models",
+                    command.command_name, confirmation.projector
+                ));
+            }
+            let (expected_topology, _) = compiled_projectors
+                .get(&projector.name)
+                .expect("every registered projector was compiled above");
+            if confirmation.protocol_topology() != Some(expected_topology) {
+                return Err(format!(
+                    "typed command `{}` confirmation for projector `{}` is not bound to the exact compiled schema topology",
+                    command.command_name, confirmation.projector
+                ));
+            }
+        }
+        if let Some(target) = &command.direct_projection {
+            let projector = projectors
+                .iter()
+                .find(|projector| projector.name == target.projector)
+                .ok_or_else(|| {
+                    format!(
+                        "typed projected command `{}` expects unknown direct projector `{}`",
+                        command.command_name, target.projector
+                    )
+                })?;
+            if !projector.models.iter().any(|model| model == &target.model) {
+                return Err(format!(
+                    "typed projected command `{}` direct projector `{}` does not own model `{}`",
+                    command.command_name, target.projector, target.model
+                ));
+            }
+            if !target.topology_matches(
+                &projector.name,
+                &projector.facts,
+                &projector.models,
+                &projector.partition,
+                projector.change_epoch.as_deref(),
+            ) {
+                return Err(format!(
+                    "typed projected command `{}` captured direct projector `{}` topology/change epoch does not match the registered owner",
+                    command.command_name, target.projector
+                ));
+            }
+            let (expected_topology, _) = compiled_projectors
+                .get(&projector.name)
+                .expect("every registered projector was compiled above");
+            if !target.protocol_topology_matches(expected_topology) {
+                return Err(format!(
+                    "typed projected command `{}` direct projector `{}` is not bound to the exact compiled schema topology",
+                    command.command_name, target.projector
+                ));
+            }
+            if projector.change_epoch.is_none() {
+                return Err(format!(
+                    "typed projected command `{}` direct projector `{}` has no registered change-log epoch",
+                    command.command_name, target.projector
+                ));
+            }
+            let mut expected_ownership = projector
+                .models
+                .iter()
+                .map(|model_name| {
+                    let model = models.get(model_name).ok_or_else(|| {
+                        format!(
+                            "typed projected command `{}` owner `{}` references unknown model `{model_name}`",
+                            command.command_name, projector.name
+                        )
+                    })?;
+                    ProjectionModelOwnership::new(model_name, &model.table_name)
+                        .map_err(|error| error.to_string())
+                })
+                .collect::<Result<Vec<_>, _>>()?;
+            expected_ownership.sort_by(|left, right| {
+                (left.model.as_str(), left.table.as_str())
+                    .cmp(&(right.model.as_str(), right.table.as_str()))
+            });
+            if target.ownership != expected_ownership {
+                return Err(format!(
+                    "typed projected command `{}` direct projector `{}` captured an incomplete or stale model/table ownership inventory",
+                    command.command_name, target.projector
+                ));
+            }
+
+            let physical_owners = projectors
+                .iter()
+                .flat_map(|candidate| {
+                    candidate.models.iter().filter_map(move |model_name| {
+                        models
+                            .get(model_name)
+                            .filter(|model| model.table_name == target.table)
+                            .map(|_| (candidate.name.as_str(), model_name.as_str()))
+                    })
+                })
+                .collect::<Vec<_>>();
+            if physical_owners.as_slice() != [(target.projector.as_str(), target.model.as_str())] {
+                return Err(format!(
+                    "typed projected command `{}` model `{}` has ambiguous direct projection ownership",
+                    command.command_name, target.model
+                ));
+            }
+        }
+    }
+    Ok(())
+}
diff --git a/src/graphql/surface/effects.rs b/src/graphql/surface/effects.rs
new file mode 100644
index 00000000..a7bf2e41
--- /dev/null
+++ b/src/graphql/surface/effects.rs
@@ -0,0 +1,701 @@
+use super::*;
+
+pub(in crate::graphql::surface) fn validate_effect_key(
+    models: &BTreeMap<String, SurfaceModel>,
+    command: &SurfaceCommand,
+    model_name: &str,
+    key: &EffectKey,
+) -> Result<(), String> {
+    let model = models.get(model_name).ok_or_else(|| {
+        format!(
+            "typed command `{}` effect references unknown model `{model_name}`",
+            command.command_name
+        )
+    })?;
+    let fields: Vec<&str> = key
+        .fields
+        .iter()
+        .map(|field| field.field.as_str())
+        .collect();
+    if fields
+        != model
+            .primary_key
+            .iter()
+            .map(String::as_str)
+            .collect::<Vec<_>>()
+    {
+        return Err(format!(
+            "typed command `{}` effect key for `{model_name}` must exactly match ordered primary key ({})",
+            command.command_name,
+            model.primary_key.join(", ")
+        ));
+    }
+    for field in &key.fields {
+        let Some(column) = model
+            .columns
+            .iter()
+            .find(|column| column.name == field.field)
+        else {
+            return Err(format!(
+                "typed command `{}` effect key for `{model_name}` references primary-key field `{}` that is missing or hidden on the selected Surface",
+                command.command_name, field.field
+            ));
+        };
+        validate_effect_expression(command, &field.value, column)?;
+    }
+    Ok(())
+}
+
+pub(in crate::graphql::surface) fn validate_command_effects(
+    models: &BTreeMap<String, SurfaceModel>,
+    command: &SurfaceCommand,
+) -> Result<(), String> {
+    let Some(effects) = &command.effects else {
+        return Ok(());
+    };
+    for operation in &effects.operations {
+        validate_effect_operation(models, command, operation)?;
+    }
+    Ok(())
+}
+
+pub(in crate::graphql::surface) fn validate_effect_operation(
+    models: &BTreeMap<String, SurfaceModel>,
+    command: &SurfaceCommand,
+    operation: &CommandEffect,
+) -> Result<(), String> {
+    let validate_addressable = |model_name: &str| -> Result<(), String> {
+        let model = models.get(model_name).ok_or_else(|| {
+            format!(
+                "typed command `{}` effect references unknown model `{model_name}`",
+                command.command_name
+            )
+        })?;
+        if !model_has_client_normalized_identity(model) {
+            return Err(format!(
+                "typed command `{}` cannot use a key-addressed optimistic effect for embedded model `{model_name}`; the selected Surface requires a complete visible, supported, non-null, non-BigInt primary key",
+                command.command_name
+            ));
+        }
+        Ok(())
+    };
+    let validate_fields = |model_name: &str, fields: &[EffectFieldValue]| -> Result<(), String> {
+        let model = models.get(model_name).ok_or_else(|| {
+            format!(
+                "typed command `{}` effect references unknown model `{model_name}`",
+                command.command_name
+            )
+        })?;
+        let mut seen = BTreeSet::new();
+        for field in fields {
+            if !seen.insert(&field.field) {
+                return Err(format!(
+                    "typed command `{}` effect repeats `{model_name}.{}`",
+                    command.command_name, field.field
+                ));
+            }
+            let Some(column) = model
+                .columns
+                .iter()
+                .find(|candidate| candidate.name == field.field)
+            else {
+                return Err(format!(
+                    "typed command `{}` effect references unknown field `{model_name}.{}`",
+                    command.command_name, field.field
+                ));
+            };
+            if model.primary_key.iter().any(|key| key == &field.field) {
+                return Err(format!(
+                    "typed command `{}` effect cannot assign primary-key field `{model_name}.{}`; upsert identity materializes from `key` and rekeying is unsupported",
+                    command.command_name, field.field
+                ));
+            }
+            validate_effect_expression(command, &field.value, column)?;
+        }
+        Ok(())
+    };
+    let validate_relationship = |relationship: &EffectRelationship| -> Result<(), String> {
+        let source = models.get(&relationship.source_model).ok_or_else(|| {
+            format!(
+                "typed command `{}` effect references unknown model `{}`",
+                command.command_name, relationship.source_model
+            )
+        })?;
+        let declared = source
+            .relationships
+            .iter()
+            .find(|candidate| candidate.name == relationship.field)
+            .ok_or_else(|| {
+                format!(
+                    "typed command `{}` effect references unknown relationship `{}.{}`",
+                    command.command_name, relationship.source_model, relationship.field
+                )
+            })?;
+        if declared.target_model != relationship.target_model {
+            return Err(format!(
+                "typed command `{}` relationship `{}.{}` targets `{}`, not `{}`",
+                command.command_name,
+                relationship.source_model,
+                relationship.field,
+                declared.target_model,
+                relationship.target_model
+            ));
+        }
+        Ok(())
+    };
+
+    match operation {
+        CommandEffect::Upsert { model, key, fields }
+        | CommandEffect::Patch { model, key, fields } => {
+            validate_addressable(model)?;
+            validate_effect_key(models, command, model, key)?;
+            validate_fields(model, fields)
+        }
+        CommandEffect::Delete { model, key } => {
+            validate_addressable(model)?;
+            validate_effect_key(models, command, model, key)
+        }
+        CommandEffect::Link {
+            relationship,
+            source,
+            target,
+        }
+        | CommandEffect::Unlink {
+            relationship,
+            source,
+            target,
+        } => {
+            validate_relationship(relationship)?;
+            validate_addressable(&relationship.source_model)?;
+            validate_addressable(&relationship.target_model)?;
+            validate_effect_key(models, command, &relationship.source_model, source)?;
+            validate_effect_key(models, command, &relationship.target_model, target)
+        }
+        CommandEffect::InvalidateModel { model } => {
+            if !models.contains_key(model) {
+                return Err(format!(
+                    "typed command `{}` invalidates unknown model `{model}`",
+                    command.command_name
+                ));
+            }
+            Ok(())
+        }
+        CommandEffect::InvalidateRelationship {
+            relationship,
+            source,
+        } => {
+            validate_relationship(relationship)?;
+            validate_addressable(&relationship.source_model)?;
+            validate_effect_key(models, command, &relationship.source_model, source)
+        }
+    }
+}
+
+pub(in crate::graphql::surface) fn validate_effect_expression(
+    command: &SurfaceCommand,
+    expression: &EffectExpression,
+    expected: &ColumnField,
+) -> Result<(), String> {
+    match expression {
+        EffectExpression::Input { path } => {
+            let SurfaceCommandShape::Typed(input) = &command.input else {
+                return Err(format!(
+                    "typed command `{}` effect uses input on an untyped command",
+                    command.command_name
+                ));
+            };
+            if path.is_empty() {
+                return Err(format!(
+                    "typed command `{}` effect input path must not be empty",
+                    command.command_name
+                ));
+            }
+            let mut definition = input;
+            let mut inherited_nullable = false;
+            let mut leaf = None;
+            for (index, segment) in path.iter().enumerate() {
+                let Some(field) = definition
+                    .fields
+                    .iter()
+                    .find(|field| field.name == *segment)
+                else {
+                    return Err(format!(
+                        "typed command `{}` effect references unknown input path `{}`",
+                        command.command_name,
+                        path.join(".")
+                    ));
+                };
+                let last = index + 1 == path.len();
+                if last {
+                    leaf = Some(field);
+                    break;
+                }
+                if field.list {
+                    return Err(format!(
+                        "typed command `{}` effect input path `{}` cannot descend through list field `{}`",
+                        command.command_name,
+                        path.join("."),
+                        segment
+                    ));
+                }
+                inherited_nullable |= field.nullable;
+                let Some(nested) = field.nested.as_deref() else {
+                    return Err(format!(
+                        "typed command `{}` effect input path `{}` descends through scalar field `{}`",
+                        command.command_name,
+                        path.join("."),
+                        segment
+                    ));
+                };
+                definition = nested;
+            }
+            let field = leaf.expect("non-empty input paths always resolve a leaf or return");
+            let json_container_leaf =
+                expected.scalar == "JSON" && (field.list || field.nested.is_some());
+            if !json_container_leaf && (field.list || field.type_name != expected.scalar) {
+                return Err(format!(
+                    "typed command `{}` effect input `{}` has GraphQL type `{}`, but model field `{}` requires `{}`",
+                    command.command_name,
+                    path.join("."),
+                    field.type_name,
+                    expected.name,
+                    expected.scalar
+                ));
+            }
+            if (inherited_nullable || field.nullable) && !expected.nullable {
+                return Err(format!(
+                    "typed command `{}` nullable effect input `{}` cannot populate non-null model field `{}`",
+                    command.command_name,
+                    path.join("."),
+                    expected.name
+                ));
+            }
+        }
+        EffectExpression::TrustedPreset { name } => {
+            if name.is_empty()
+                || name.len() > 128
+                || name.trim() != name
+                || name.chars().any(char::is_control)
+            {
+                return Err(format!(
+                    "typed command `{}` trusted preset name must be 1..=128 bytes, have no surrounding whitespace, and contain no control characters",
+                    command.command_name
+                ));
+            }
+        }
+        EffectExpression::Constant { value } => {
+            let compatible = constant_matches_scalar(value, expected);
+            if !compatible {
+                return Err(format!(
+                    "typed command `{}` constant effect value is incompatible with model field `{}` (`{}`)",
+                    command.command_name, expected.name, expected.scalar
+                ));
+            }
+        }
+        EffectExpression::Null => {
+            if !expected.nullable {
+                return Err(format!(
+                    "typed command `{}` null effect value cannot populate non-null model field `{}`",
+                    command.command_name, expected.name
+                ));
+            }
+        }
+        EffectExpression::InvalidConstant { error } => {
+            return Err(format!(
+                "typed command `{}` constant effect value failed to serialize: {error}",
+                command.command_name
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(in crate::graphql::surface) fn constant_matches_scalar(
+    value: &serde_json::Value,
+    expected: &ColumnField,
+) -> bool {
+    use base64::Engine as _;
+
+    if expected.scalar == "JSON" {
+        return true;
+    }
+    // `serde_json` represents non-finite floats as JSON null. SQL null has a
+    // separate typed IR variant, so a constant null is invalid for every
+    // non-JSON scalar even when the target column is nullable.
+    if value.is_null() {
+        return false;
+    }
+    match (expected.scalar.as_str(), value) {
+        ("Boolean", serde_json::Value::Bool(_)) => true,
+        ("BigInt", serde_json::Value::Number(number)) => number.is_i64() || number.is_u64(),
+        ("Int", serde_json::Value::Number(number)) => {
+            number
+                .as_i64()
+                .is_some_and(|value| i32::try_from(value).is_ok())
+                || number
+                    .as_u64()
+                    .is_some_and(|value| i32::try_from(value).is_ok())
+        }
+        ("Float", serde_json::Value::Number(_)) => true,
+        ("String" | "ID", serde_json::Value::String(_)) => true,
+        ("Timestamptz", serde_json::Value::String(value)) => is_rfc3339_timestamp(value),
+        ("Bytea", serde_json::Value::String(value)) => base64::engine::general_purpose::STANDARD
+            .decode(value)
+            .is_ok(),
+        _ => false,
+    }
+}
+
+/// Small dependency-free RFC 3339 validator for deterministic manifest
+/// constants. Runtime database decoding remains dialect-owned.
+pub(in crate::graphql::surface) fn is_rfc3339_timestamp(value: &str) -> bool {
+    let bytes = value.as_bytes();
+    if bytes.len() < 20
+        || bytes.get(4) != Some(&b'-')
+        || bytes.get(7) != Some(&b'-')
+        || !matches!(bytes.get(10), Some(b'T' | b't'))
+        || bytes.get(13) != Some(&b':')
+        || bytes.get(16) != Some(&b':')
+    {
+        return false;
+    }
+    let digits = |range: std::ops::Range<usize>| -> Option<u32> {
+        std::str::from_utf8(bytes.get(range)?).ok()?.parse().ok()
+    };
+    let (Some(year), Some(month), Some(day), Some(hour), Some(minute), Some(second)) = (
+        digits(0..4),
+        digits(5..7),
+        digits(8..10),
+        digits(11..13),
+        digits(14..16),
+        digits(17..19),
+    ) else {
+        return false;
+    };
+    let leap = year % 4 == 0 && (year % 100 != 0 || year % 400 == 0);
+    let max_day = match month {
+        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
+        4 | 6 | 9 | 11 => 30,
+        2 if leap => 29,
+        2 => 28,
+        _ => return false,
+    };
+    if day == 0 || day > max_day || hour > 23 || minute > 59 || second > 60 {
+        return false;
+    }
+
+    let mut cursor = 19;
+    if bytes.get(cursor) == Some(&b'.') {
+        cursor += 1;
+        let fraction_start = cursor;
+        while bytes.get(cursor).is_some_and(u8::is_ascii_digit) {
+            cursor += 1;
+        }
+        if cursor == fraction_start {
+            return false;
+        }
+    }
+    match bytes.get(cursor) {
+        Some(b'Z' | b'z') => cursor + 1 == bytes.len(),
+        Some(b'+' | b'-') => {
+            if cursor + 6 != bytes.len() || bytes.get(cursor + 3) != Some(&b':') {
+                return false;
+            }
+            let offset_hour = std::str::from_utf8(&bytes[cursor + 1..cursor + 3])
+                .ok()
+                .and_then(|value| value.parse::<u32>().ok());
+            let offset_minute = std::str::from_utf8(&bytes[cursor + 4..cursor + 6])
+                .ok()
+                .and_then(|value| value.parse::<u32>().ok());
+            matches!((offset_hour, offset_minute), (Some(0..=23), Some(0..=59)))
+        }
+        _ => false,
+    }
+}
+
+pub(in crate::graphql::surface) fn sanitize_command_effects_for_models(
+    commands: &mut [SurfaceCommand],
+    models: &BTreeMap<String, SurfaceModel>,
+) {
+    for command in commands {
+        let Some(effects) = &command.effects else {
+            continue;
+        };
+        if effects
+            .operations
+            .iter()
+            .any(|operation| !effect_operation_visible(operation, models))
+        {
+            // Keep the command, but erase the entire optimistic plan. Partial
+            // optimism is harder to reason about than conservative revalidation
+            // and could leak denied model/field/preset names.
+            command.effects = Some(CommandEffects::revalidate());
+        }
+    }
+}
+
+pub(in crate::graphql::surface) fn sanitize_command_confirmations(
+    commands: &mut [SurfaceCommand],
+    projectors: &[SurfaceProjectionOwner],
+    models: &BTreeMap<String, SurfaceModel>,
+) {
+    for command in commands {
+        let all_visible = command.confirmations.iter().all(|confirmation| {
+            models.contains_key(&confirmation.model)
+                && projectors.iter().any(|projector| {
+                    projector.name == confirmation.projector
+                        && projector
+                            .models
+                            .iter()
+                            .any(|model| model == &confirmation.model)
+                })
+                && confirmation.key.fields.iter().all(|field| {
+                    models.get(&confirmation.model).is_some_and(|model| {
+                        model
+                            .columns
+                            .iter()
+                            .any(|column| column.name == field.field)
+                    }) && effect_expression_visible(&field.value)
+                })
+                && confirmation
+                    .partition
+                    .as_ref()
+                    .is_none_or(effect_expression_visible)
+        });
+        if !all_visible {
+            command.confirmations.clear();
+            command.confirmation_unavailable = true;
+            // Optimism and causal confirmation must be authorized as one plan.
+            // Keeping either a subset of edges or a partial optimistic write
+            // could disclose hidden topology and produce a state the server
+            // never promised to confirm.
+            command.effects = Some(CommandEffects::revalidate());
+        }
+    }
+}
+
+pub(in crate::graphql::surface) fn effect_operation_visible(
+    operation: &CommandEffect,
+    models: &BTreeMap<String, SurfaceModel>,
+) -> bool {
+    let key_visible = |model_name: &str, key: &EffectKey| {
+        models.get(model_name).is_some_and(|model| {
+            key.fields.iter().all(|field| {
+                model
+                    .columns
+                    .iter()
+                    .any(|column| column.name == field.field)
+                    && effect_expression_visible(&field.value)
+            })
+        })
+    };
+    let fields_visible = |model_name: &str, fields: &[EffectFieldValue]| {
+        models.get(model_name).is_some_and(|model| {
+            fields.iter().all(|field| {
+                model
+                    .columns
+                    .iter()
+                    .any(|column| column.name == field.field)
+                    && effect_expression_visible(&field.value)
+            })
+        })
+    };
+    let relationship_visible = |relationship: &EffectRelationship| {
+        models.get(&relationship.source_model).is_some_and(|model| {
+            model.relationships.iter().any(|candidate| {
+                candidate.name == relationship.field
+                    && candidate.target_model == relationship.target_model
+                    && models.contains_key(&relationship.target_model)
+            })
+        })
+    };
+    match operation {
+        CommandEffect::Upsert { model, key, fields }
+        | CommandEffect::Patch { model, key, fields } => {
+            key_visible(model, key) && fields_visible(model, fields)
+        }
+        CommandEffect::Delete { model, key } => key_visible(model, key),
+        CommandEffect::Link {
+            relationship,
+            source,
+            target,
+        }
+        | CommandEffect::Unlink {
+            relationship,
+            source,
+            target,
+        } => {
+            relationship_visible(relationship)
+                && key_visible(&relationship.source_model, source)
+                && key_visible(&relationship.target_model, target)
+        }
+        CommandEffect::InvalidateModel { model } => models.contains_key(model),
+        CommandEffect::InvalidateRelationship {
+            relationship,
+            source,
+        } => relationship_visible(relationship) && key_visible(&relationship.source_model, source),
+    }
+}
+
+pub(in crate::graphql::surface) fn effect_expression_visible(
+    expression: &EffectExpression,
+) -> bool {
+    // A selected client surface may expose the descriptor name, but never its
+    // value. Runtime values are read from the verified Session and travel only
+    // in the cache-scope-bound protocol envelope.
+    !matches!(expression, EffectExpression::InvalidConstant { .. })
+}
+
+pub(in crate::graphql::surface) fn reject_occupied_command_types(
+    definition: &SurfaceTypeDef,
+    occupied_types: &BTreeSet<String>,
+) -> Result<(), String> {
+    if occupied_types.contains(&definition.name) {
+        return Err(format!(
+            "command type `{}` collides with a Surface GraphQL type",
+            definition.name
+        ));
+    }
+    for field in &definition.fields {
+        if let Some(nested) = &field.nested {
+            reject_occupied_command_types(nested, occupied_types)?;
+        }
+    }
+    Ok(())
+}
+
+pub(in crate::graphql::surface) fn canonicalize_type_def(
+    definition: &mut SurfaceTypeDef,
+) -> Result<(), String> {
+    if !is_valid_graphql_name(&definition.name) {
+        return Err(format!(
+            "command type `{}` is not a valid GraphQL name",
+            definition.name
+        ));
+    }
+    if definition.fields.is_empty() {
+        return Err(format!(
+            "command type `{}` must declare at least one field",
+            definition.name
+        ));
+    }
+    let mut fields = BTreeSet::new();
+    for field in &mut definition.fields {
+        if !is_valid_graphql_name(&field.name) {
+            return Err(format!(
+                "command type `{}` field `{}` is not a valid GraphQL name",
+                definition.name, field.name
+            ));
+        }
+        if !fields.insert(field.name.clone()) {
+            return Err(format!(
+                "command type `{}` declares duplicate field `{}`",
+                definition.name, field.name
+            ));
+        }
+        if !field.list && field.item_nullable {
+            return Err(format!(
+                "command type `{}` field `{}` marks non-list items nullable",
+                definition.name, field.name
+            ));
+        }
+        if let Some(nested) = &mut field.nested {
+            canonicalize_type_def(nested)?;
+            if field.type_name != nested.name {
+                return Err(format!(
+                    "command type `{}` field `{}` names `{}` but embeds `{}`",
+                    definition.name, field.name, field.type_name, nested.name
+                ));
+            }
+        } else if !is_command_scalar(&field.type_name) {
+            return Err(format!(
+                "command type `{}` field `{}` references unknown type `{}` without a structural definition",
+                definition.name, field.name, field.type_name
+            ));
+        }
+    }
+    definition.fields.sort_by(|a, b| a.name.cmp(&b.name));
+    Ok(())
+}
+
+pub(in crate::graphql::surface) fn register_type_def(
+    definition: &SurfaceTypeDef,
+    input: bool,
+    type_defs: &mut BTreeMap<String, (bool, SurfaceTypeDef)>,
+) -> Result<(), String> {
+    if let Some((existing_input, existing)) = type_defs.get(&definition.name) {
+        if *existing_input != input || existing != definition {
+            return Err(format!(
+                "ambiguous duplicate command type id `{}`",
+                definition.name
+            ));
+        }
+    } else {
+        type_defs.insert(definition.name.clone(), (input, definition.clone()));
+    }
+    for field in &definition.fields {
+        if let Some(nested) = &field.nested {
+            register_type_def(nested, input, type_defs)?;
+        }
+    }
+    Ok(())
+}
+
+pub(in crate::graphql::surface) fn is_command_scalar(name: &str) -> bool {
+    matches!(name, "Boolean" | "Float" | "ID" | "Int" | "String") || CUSTOM_SCALARS.contains(&name)
+}
+
+pub(in crate::graphql::surface) fn filter_is_surface_visible(
+    predicate: &FilterExpr,
+    model_name: &str,
+    models: &BTreeMap<String, SurfaceModel>,
+) -> bool {
+    let Some(model) = models.get(model_name) else {
+        return false;
+    };
+    match predicate {
+        FilterExpr::And(items) | FilterExpr::Or(items) => items
+            .iter()
+            .all(|item| filter_is_surface_visible(item, model_name, models)),
+        FilterExpr::Not(item) => filter_is_surface_visible(item, model_name, models),
+        FilterExpr::Cmp { column, rhs, .. } => model
+            .columns
+            .iter()
+            .find(|field| field.name == *column)
+            .is_some_and(|field| policy_operand_is_client_typed(rhs, &field.scalar)),
+        FilterExpr::In { column, values, .. } => model
+            .columns
+            .iter()
+            .find(|field| field.name == *column)
+            .is_some_and(|field| {
+                values
+                    .iter()
+                    .all(|value| policy_operand_is_client_typed(value, &field.scalar))
+            }),
+        FilterExpr::IsNull { column, .. } => {
+            model.columns.iter().any(|field| field.name == *column)
+        }
+        FilterExpr::Rel { field, predicate } => model
+            .relationships
+            .iter()
+            .find(|relationship| relationship.name == *field)
+            .is_some_and(|relationship| {
+                matches!(
+                    relationship.keys,
+                    SurfaceRelationshipKeys::Direct { .. }
+                        | SurfaceRelationshipKeys::Through { .. }
+                ) && filter_is_surface_visible(predicate, &relationship.target_model, models)
+            }),
+    }
+}
+
+pub(in crate::graphql::surface) fn policy_operand_is_client_typed(
+    operand: &Operand,
+    scalar: &str,
+) -> bool {
+    !matches!(operand, Operand::Claim(_))
+        || matches!(
+            scalar,
+            "BigInt" | "Boolean" | "Float" | "ID" | "Int" | "String" | "Timestamptz"
+        )
+}
diff --git a/src/graphql/surface/identity.rs b/src/graphql/surface/identity.rs
new file mode 100644
index 00000000..255d39c2
--- /dev/null
+++ b/src/graphql/surface/identity.rs
@@ -0,0 +1,127 @@
+use super::*;
+
+pub(in crate::graphql::surface) fn sanitize_relationship_identity(
+    models: &mut BTreeMap<String, SurfaceModel>,
+) {
+    let visible_fields: BTreeMap<String, BTreeSet<String>> = models
+        .iter()
+        .map(|(name, model)| {
+            (
+                name.clone(),
+                model
+                    .columns
+                    .iter()
+                    .map(|field| field.name.clone())
+                    .collect(),
+            )
+        })
+        .collect();
+    let visible_tables: BTreeMap<String, BTreeSet<String>> = models
+        .values()
+        .map(|model| {
+            (
+                model.table_name.clone(),
+                model
+                    .columns
+                    .iter()
+                    .map(|field| field.name.clone())
+                    .collect(),
+            )
+        })
+        .collect();
+
+    for model in models.values_mut() {
+        let source_fields = &visible_fields[&model.model_name];
+        for relationship in &mut model.relationships {
+            let target_fields = &visible_fields[&relationship.target_model];
+            let keys_visible = match &relationship.keys {
+                SurfaceRelationshipKeys::Direct { local, remote } => {
+                    !local.is_empty()
+                        && local.len() == remote.len()
+                        && local.iter().all(|key| source_fields.contains(key))
+                        && remote.iter().all(|key| target_fields.contains(key))
+                }
+                SurfaceRelationshipKeys::Through {
+                    local,
+                    remote,
+                    table,
+                    source_foreign_key,
+                    target_foreign_key,
+                } => {
+                    let identity_visible = !local.is_empty()
+                        && local.len() == remote.len()
+                        && local.iter().all(|key| source_fields.contains(key))
+                        && remote.iter().all(|key| target_fields.contains(key));
+                    if identity_visible
+                        && !visible_tables.get(table).is_some_and(|fields| {
+                            fields.contains(source_foreign_key)
+                                && fields.contains(target_foreign_key)
+                        })
+                    {
+                        relationship.keys = SurfaceRelationshipKeys::ThroughOpaque {
+                            local: local.clone(),
+                            remote: remote.clone(),
+                            dependency: opaque_relationship_dependency_id(
+                                &model.model_name,
+                                &relationship.name,
+                                &relationship.target_model,
+                            ),
+                        };
+                    }
+                    identity_visible
+                }
+                SurfaceRelationshipKeys::ThroughOpaque { local, remote, .. } => {
+                    !local.is_empty()
+                        && local.len() == remote.len()
+                        && local.iter().all(|key| source_fields.contains(key))
+                        && remote.iter().all(|key| target_fields.contains(key))
+                }
+                SurfaceRelationshipKeys::Embedded => false,
+            };
+            if !keys_visible {
+                relationship.keys = SurfaceRelationshipKeys::Embedded;
+            }
+
+            // Visible read-model tables are already public manifest IDs. Any
+            // operational dependency (notably a private many-to-many join
+            // table) remains useful for conservative invalidation but is
+            // represented by a stable opaque ID instead of leaking its name.
+            relationship.dependencies = relationship
+                .dependencies
+                .iter()
+                .map(|dependency| {
+                    if visible_tables.contains_key(dependency)
+                        || dependency.starts_with("opaque:sha256:")
+                    {
+                        dependency.clone()
+                    } else {
+                        opaque_relationship_dependency_id(
+                            &model.model_name,
+                            &relationship.name,
+                            &relationship.target_model,
+                        )
+                    }
+                })
+                .collect();
+            relationship.dependencies.sort();
+            relationship.dependencies.dedup();
+            if let Some(aggregate) = &mut relationship.aggregate {
+                // Aggregate invalidation must never retain the pre-sanitized
+                // private dependency inventory.
+                aggregate.dependencies = relationship.dependencies.clone();
+            }
+        }
+    }
+}
+
+pub(in crate::graphql::surface) fn opaque_relationship_dependency_id(
+    source: &str,
+    relationship: &str,
+    target: &str,
+) -> String {
+    let material = format!(
+        "distributed.client.relationship-dependency.v1\0{source}\0{relationship}\0{target}\0join"
+    );
+    let digest = Sha256::digest(material.as_bytes());
+    format!("opaque:sha256:{digest:x}")
+}
diff --git a/src/graphql/surface/mod.rs b/src/graphql/surface/mod.rs
new file mode 100644
index 00000000..6fc5df36
--- /dev/null
+++ b/src/graphql/surface/mod.rs
@@ -0,0 +1,65 @@
+//! Shared GraphQL **surface IR** — single source of truth for the query/subscription
+//! type system a catalog (and optionally a role) can see.
+//!
+//! SDL emission and (over time) runtime schema construction consume this IR so
+//! dialect-honest comparison ops, roots, and column grants cannot diverge.
+//!
+//! Core types compile without the `graphql` feature so `dctl schema --format graphql`
+//! can share the same IR path.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::ops::Deref;
+
+use sha2::{Digest, Sha256};
+
+use super::command_contract::{
+    compiled_direct_projection_target, compiled_projection_confirmation,
+    validate_projection_confirmation_count, CommandConsistency, CommandDirectProjectionTarget,
+    CommandEffect, CommandEffects, CommandInputDefault, CommandProjectedModel,
+    CommandProjectionConfirmation, CompiledDirectProjectionTarget, CompiledProjectionConfirmation,
+    EffectExpression, EffectFieldValue, EffectKey, EffectRelationship, TypedEffectKey,
+};
+use super::filter::{validate_row_policy_operand_literal, FilterExpr, Operand};
+use crate::projection_protocol::ProjectionPartitionSpec;
+use crate::projection_protocol::{compile_projection_topology, ProjectionModelOwnership};
+use crate::table::{
+    resolve_m2m_target_foreign_key, ColumnType, RelationshipKind, TableColumn, TableSchema,
+};
+
+use super::naming::{
+    by_pk_field, comparison_exp_name, comparison_op_fields, include_postgres_json_comparison_ops,
+    is_valid_graphql_name, object_type_name, reserved_type_names, root_list_field,
+    scalar_type_name, CUSTOM_SCALARS,
+};
+
+mod application;
+mod build;
+mod commands;
+mod effects;
+mod identity;
+mod roots;
+mod types;
+mod validation;
+
+#[cfg(test)]
+mod tests;
+
+pub use application::{role_grants_for_role, surface_for_application, surface_for_role, RoleGrant};
+pub use build::build_surface;
+pub use types::{
+    ColumnField, RelField, RootField, RootKind, Surface, SurfaceArgument, SurfaceArgumentKind,
+    SurfaceCommand, SurfaceCommandShape, SurfaceDialect, SurfaceDirectProjection, SurfaceModel,
+    SurfaceOptions, SurfaceProjectionOwner, SurfaceProjector, SurfaceRelationshipAggregate,
+    SurfaceRelationshipKeys, SurfaceRowPolicy, SurfaceTypeDef, SurfaceTypeField,
+};
+
+pub(crate) use commands::projected_output_reuses_surface_model;
+pub(in crate::graphql::surface) use commands::{
+    bind_surface_direct_projection_targets, validate_and_canonicalize_commands,
+    validate_command_confirmation_topology,
+};
+pub(in crate::graphql::surface) use effects::*;
+pub(in crate::graphql::surface) use identity::*;
+pub(in crate::graphql::surface) use roots::*;
+pub(crate) use types::{model_has_client_normalized_identity, SurfaceSelection};
+pub(in crate::graphql::surface) use validation::*;
diff --git a/src/graphql/surface/roots.rs b/src/graphql/surface/roots.rs
new file mode 100644
index 00000000..79350b16
--- /dev/null
+++ b/src/graphql/surface/roots.rs
@@ -0,0 +1,244 @@
+use super::*;
+
+pub(in crate::graphql::surface) fn root_fields_for_models(
+    models: &BTreeMap<String, SurfaceModel>,
+    aggregates: bool,
+    subscriptions: bool,
+    default_limit: u64,
+    max_limit: u64,
+) -> (Vec<RootField>, Vec<RootField>) {
+    let mut query_fields = Vec::new();
+    let mut subscription_fields = Vec::new();
+    for model in models.values() {
+        let list = root_list_field(&model.schema).to_string();
+        let by_pk = by_pk_field(&model.schema);
+        query_fields.push(root_field(
+            model,
+            list.clone(),
+            RootKind::List,
+            default_limit,
+            max_limit,
+        ));
+        query_fields.push(root_field(
+            model,
+            by_pk.clone(),
+            RootKind::ByPk,
+            default_limit,
+            max_limit,
+        ));
+        if aggregates {
+            query_fields.push(root_field(
+                model,
+                format!("{}_aggregate", model.table_name),
+                RootKind::Aggregate,
+                default_limit,
+                max_limit,
+            ));
+        }
+        if subscriptions {
+            subscription_fields.push(root_field(
+                model,
+                list,
+                RootKind::List,
+                default_limit,
+                max_limit,
+            ));
+        }
+    }
+    query_fields.sort_by(|a, b| a.name.cmp(&b.name));
+    subscription_fields.sort_by(|a, b| a.name.cmp(&b.name));
+    (query_fields, subscription_fields)
+}
+
+pub(in crate::graphql::surface) fn root_field(
+    model: &SurfaceModel,
+    name: String,
+    kind: RootKind,
+    default_limit: u64,
+    max_limit: u64,
+) -> RootField {
+    let arguments = match kind {
+        RootKind::List => list_arguments(&model.schema),
+        RootKind::ByPk => primary_key_arguments(&model.schema),
+        RootKind::Aggregate => vec![SurfaceArgument {
+            name: "where".into(),
+            kind: SurfaceArgumentKind::Filter,
+            type_name: format!("{}_bool_exp", model.table_name),
+            nullable: true,
+            list: false,
+        }],
+    };
+    let is_windowed = matches!(kind, RootKind::List);
+    let effective_max = model.role_limit.unwrap_or(max_limit).min(max_limit);
+    let role_default = default_limit.min(effective_max);
+    RootField {
+        name,
+        kind,
+        object: model.object_name.clone(),
+        model_name: model.model_name.clone(),
+        arguments,
+        dependencies: vec![model.table_name.clone()],
+        default_limit: is_windowed.then_some(role_default),
+        max_limit: is_windowed.then_some(effective_max),
+    }
+}
+
+pub(in crate::graphql::surface) fn list_arguments(schema: &TableSchema) -> Vec<SurfaceArgument> {
+    vec![
+        SurfaceArgument {
+            name: "where".into(),
+            kind: SurfaceArgumentKind::Filter,
+            type_name: format!("{}_bool_exp", schema.table_name),
+            nullable: true,
+            list: false,
+        },
+        SurfaceArgument {
+            name: "order_by".into(),
+            kind: SurfaceArgumentKind::Order,
+            type_name: format!("{}_order_by", schema.table_name),
+            nullable: true,
+            list: true,
+        },
+        SurfaceArgument {
+            name: "limit".into(),
+            kind: SurfaceArgumentKind::Limit,
+            type_name: "Int".into(),
+            nullable: true,
+            list: false,
+        },
+        SurfaceArgument {
+            name: "offset".into(),
+            kind: SurfaceArgumentKind::Offset,
+            type_name: "Int".into(),
+            nullable: true,
+            list: false,
+        },
+    ]
+}
+
+pub(in crate::graphql::surface) fn primary_key_arguments(
+    schema: &TableSchema,
+) -> Vec<SurfaceArgument> {
+    schema
+        .primary_key
+        .columns
+        .iter()
+        .filter_map(|name| {
+            let column = schema
+                .columns
+                .iter()
+                .find(|column| column.column_name == *name && !column.skipped)?;
+            let scalar = scalar_type_name(&column.column_type)?;
+            Some(SurfaceArgument {
+                name: name.clone(),
+                kind: SurfaceArgumentKind::PrimaryKey,
+                type_name: scalar.into(),
+                nullable: false,
+                list: false,
+            })
+        })
+        .collect()
+}
+
+pub(in crate::graphql::surface) fn relationship_keys(
+    source: &TableSchema,
+    relationship: &crate::table::RelationshipDef,
+    target: &TableSchema,
+    by_table: &BTreeMap<&str, &TableSchema>,
+) -> Result<(SurfaceRelationshipKeys, Vec<String>), String> {
+    let foreign_key = relationship.foreign_key.as_deref().ok_or_else(|| {
+        format!(
+            "model `{}` relationship `{}` is missing foreign_key",
+            source.model_name, relationship.field_name
+        )
+    })?;
+    let mut dependencies = vec![source.table_name.clone(), target.table_name.clone()];
+    let keys = match relationship.kind {
+        RelationshipKind::BelongsTo => SurfaceRelationshipKeys::Direct {
+            local: vec![canonical_column_name(source, foreign_key, relationship)?],
+            remote: target.primary_key.columns.clone(),
+        },
+        RelationshipKind::HasMany => SurfaceRelationshipKeys::Direct {
+            local: source.primary_key.columns.clone(),
+            remote: vec![canonical_column_name(target, foreign_key, relationship)?],
+        },
+        RelationshipKind::ManyToMany => {
+            let through_name = relationship.through.as_deref().ok_or_else(|| {
+                format!(
+                    "model `{}` relationship `{}` is missing through table",
+                    source.model_name, relationship.field_name
+                )
+            })?;
+            let through = by_table.get(through_name).ok_or_else(|| {
+                format!(
+                    "model `{}` relationship `{}` references missing through table `{through_name}`",
+                    source.model_name, relationship.field_name
+                )
+            })?;
+            let target_foreign_key =
+                resolve_m2m_target_foreign_key(source, relationship, through, target)
+                    .map_err(|error| error.to_string())?;
+            dependencies.push(through.table_name.clone());
+            SurfaceRelationshipKeys::Through {
+                local: source.primary_key.columns.clone(),
+                remote: target.primary_key.columns.clone(),
+                table: through.table_name.clone(),
+                source_foreign_key: canonical_column_name(through, foreign_key, relationship)?,
+                target_foreign_key: canonical_column_name(
+                    through,
+                    &target_foreign_key,
+                    relationship,
+                )?,
+            }
+        }
+    };
+    Ok((keys, dependencies))
+}
+
+pub(in crate::graphql::surface) fn canonical_column_name(
+    schema: &TableSchema,
+    reference: &str,
+    relationship: &crate::table::RelationshipDef,
+) -> Result<String, String> {
+    schema
+        .columns
+        .iter()
+        .find(|column| column.column_name == reference || column.field_name == reference)
+        .map(|column| column.column_name.clone())
+        .ok_or_else(|| {
+            format!(
+                "relationship `{}` key `{reference}` is not a field or column on model `{}`",
+                relationship.field_name, schema.model_name
+            )
+        })
+}
+
+pub(in crate::graphql::surface) fn visible_columns(
+    schema: &TableSchema,
+) -> impl Iterator<Item = &TableColumn> {
+    schema.columns.iter().filter(|c| !c.skipped)
+}
+
+pub(in crate::graphql::surface) fn relationship_emitted(
+    schema: &TableSchema,
+    rel: &crate::table::RelationshipDef,
+    by_model: &BTreeMap<&str, &TableSchema>,
+    by_table: &BTreeMap<&str, &TableSchema>,
+) -> bool {
+    let Some(target) = by_model.get(rel.target_model.as_str()) else {
+        return false;
+    };
+    match rel.kind {
+        RelationshipKind::HasMany | RelationshipKind::BelongsTo => true,
+        RelationshipKind::ManyToMany => {
+            let Some(through_name) = rel.through.as_deref() else {
+                return false;
+            };
+            if let Some(through) = by_table.get(through_name) {
+                resolve_m2m_target_foreign_key(schema, rel, through, target).is_ok()
+            } else {
+                false
+            }
+        }
+    }
+}
diff --git a/src/graphql/surface/tests.rs b/src/graphql/surface/tests.rs
new file mode 100644
index 00000000..75c86c82
--- /dev/null
+++ b/src/graphql/surface/tests.rs
@@ -0,0 +1,1224 @@
+use std::any::TypeId;
+
+use super::*;
+use crate::graphql::command_contract::{CommandEffects, TypedCommandContract};
+use crate::graphql::commands::TypedCommandInventory;
+use crate::graphql::{GraphqlTypeDef, GraphqlTypeField};
+use crate::table::{ColumnType, PrimaryKey, RelationshipDef, TableColumn, TableKind};
+
+fn orders() -> TableSchema {
+    TableSchema {
+        model_name: "OrderView".into(),
+        table_name: "orders".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("order_id", "order_id", ColumnType::Text)
+            },
+            TableColumn::new("customer_id", "customer_id", ColumnType::Text),
+            TableColumn::new("status", "status", ColumnType::Text),
+            TableColumn {
+                jsonb: true,
+                ..TableColumn::new("meta", "meta", ColumnType::Json)
+            },
+        ],
+        primary_key: PrimaryKey::new(["order_id"]),
+        version_column: Some("_sourced_version".into()),
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    }
+}
+
+fn operational() -> TableSchema {
+    TableSchema {
+        model_name: "Outbox".into(),
+        table_name: "outbox".into(),
+        columns: vec![TableColumn {
+            primary_key: true,
+            ..TableColumn::new("id", "id", ColumnType::Text)
+        }],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::Operational,
+    }
+}
+
+fn test_command(
+    command_name: &str,
+    field_name: &str,
+    output: GraphqlTypeDef,
+) -> TypedCommandContract {
+    let input_type_id = TypeId::of::<String>();
+    let output_type_id = TypeId::of::<()>();
+    TypedCommandContract {
+        name: command_name.into(),
+        field_name: field_name.into(),
+        roles: Vec::new(),
+        input: GraphqlTypeDef::new(
+            "TestCommandInput",
+            vec![GraphqlTypeField {
+                name: "id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            }],
+        )
+        .with_type_id(input_type_id),
+        output: output.with_type_id(output_type_id),
+        input_type_id,
+        output_type_id,
+        consistency: CommandConsistency::Accepted,
+        input_defaults: Vec::new(),
+        effects: CommandEffects::revalidate(),
+        confirmations: Vec::new(),
+        projected_model: None,
+        direct_projection: None,
+    }
+}
+
+fn test_inventory(
+    contracts: impl IntoIterator<Item = TypedCommandContract>,
+) -> TypedCommandInventory {
+    TypedCommandInventory::from_contracts(&contracts.into_iter().collect::<Vec<_>>()).unwrap()
+}
+
+#[test]
+fn build_surface_skips_operational_and_lists_roots() {
+    let surface =
+        build_surface(&[orders(), operational()], &SurfaceOptions::sqlite()).expect("surface");
+    assert!(surface.models.contains_key("OrderView"));
+    assert!(!surface.models.contains_key("Outbox"));
+    let roots = surface.query_root_names();
+    assert!(roots.contains(&"orders"));
+    assert!(roots.contains(&"orders_by_pk"));
+    assert!(roots.contains(&"orders_aggregate"));
+}
+
+#[test]
+fn sqlite_surface_omits_pg_json_comparison_ops() {
+    let surface = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+    let ops = surface.comparison_ops_for_scalar("JSON");
+    assert!(ops.contains(&"_eq"));
+    for forbidden in ["_contains", "_contained_in", "_has_key"] {
+        assert!(
+            !ops.contains(&forbidden),
+            "SQLite must not expose {forbidden}"
+        );
+    }
+}
+
+#[test]
+fn postgres_surface_includes_pg_json_comparison_ops() {
+    let surface = build_surface(&[orders()], &SurfaceOptions::postgres()).unwrap();
+    let ops = surface.comparison_ops_for_scalar("JSON");
+    for required in ["_contains", "_contained_in", "_has_key"] {
+        assert!(ops.contains(&required), "Postgres missing {required}");
+    }
+}
+
+#[test]
+fn surface_rejects_duplicate_stable_model_ids() {
+    let error = build_surface(&[orders(), orders()], &SurfaceOptions::sqlite()).unwrap_err();
+    assert!(
+        error.contains("duplicate table model id `OrderView`"),
+        "{error}"
+    );
+}
+
+#[test]
+fn surface_rejects_model_and_generated_auxiliary_type_collision() {
+    let mut colliding = orders();
+    colliding.model_name = "orders_bool_exp".into();
+    colliding.table_name = "other_orders".into();
+    let error = build_surface(&[orders(), colliding], &SurfaceOptions::sqlite()).unwrap_err();
+    assert!(
+        error.contains("`orders_bool_exp` collides with another Surface type"),
+        "{error}"
+    );
+}
+
+#[test]
+fn projector_topology_rejects_duplicate_and_empty_ids() {
+    let surface = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+    let duplicate = surface
+        .clone()
+        .with_projectors([
+            SurfaceProjector::new("orders")
+                .facts(["order.changed"])
+                .models(["OrderView"]),
+            SurfaceProjector::new("orders")
+                .facts(["order.created"])
+                .models(["OrderView"]),
+        ])
+        .unwrap_err();
+    assert!(duplicate.contains("duplicate projector name `orders`"));
+
+    let empty_fact = surface
+        .clone()
+        .with_projectors([SurfaceProjector::new("orders")
+            .facts([""])
+            .models(["OrderView"])])
+        .unwrap_err();
+    assert!(empty_fact.contains("fact id must not be empty"));
+
+    let empty_model = surface
+        .clone()
+        .with_projectors([SurfaceProjector::new("orders")
+            .facts(["order.changed"])
+            .models([""])])
+        .unwrap_err();
+    assert!(empty_model.contains("model id must not be empty"));
+
+    let no_facts = surface
+        .clone()
+        .with_projectors([SurfaceProjector::new("orders").models(["OrderView"])])
+        .unwrap_err();
+    assert!(no_facts.contains("must declare at least one fact"));
+    let no_models = surface
+        .with_projectors([SurfaceProjector::new("orders").facts(["order.changed"])])
+        .unwrap_err();
+    assert!(no_models.contains("must declare at least one model"));
+}
+
+#[test]
+fn direct_projection_owner_requires_models_but_not_facts() {
+    let surface = build_surface(&[orders()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_projection_owners([SurfaceDirectProjection::new("orders")
+            .models(["OrderView"])
+            .change_epoch("orders-v1")
+            .into()])
+        .unwrap();
+    let [owner] = surface.projection_owners() else {
+        panic!("one direct owner should be retained");
+    };
+    assert!(owner.is_direct());
+    assert!(owner.facts.is_empty());
+    assert_eq!(owner.models, vec!["OrderView".to_string()]);
+
+    let error = build_surface(&[orders()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_projection_owners([SurfaceDirectProjection::new("orders")
+            .change_epoch("orders-v1")
+            .into()])
+        .unwrap_err();
+    assert!(error.contains("must declare at least one model"));
+}
+
+#[test]
+fn selected_surfaces_reject_command_and_projector_reattachment() {
+    let full = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+    let grants = BTreeMap::from([("OrderView".into(), RoleGrant::all_columns())]);
+    let selected = surface_for_role(&full, "user", &grants).unwrap();
+    assert!(selected
+        .clone()
+        .with_typed_commands(&TypedCommandInventory::empty())
+        .unwrap_err()
+        .contains("before authorization selection"));
+    assert!(selected
+        .with_projectors(Vec::<SurfaceProjector>::new())
+        .unwrap_err()
+        .contains("before authorization selection"));
+
+    let grants_by_role = BTreeMap::from([("user".into(), grants)]);
+    let application =
+        surface_for_application(&full, "web", &["user".into()], &grants_by_role).unwrap();
+    assert!(application
+        .clone()
+        .with_typed_commands(&TypedCommandInventory::empty())
+        .unwrap_err()
+        .contains("before authorization selection"));
+    assert!(application
+        .with_projectors(Vec::<SurfaceProjector>::new())
+        .unwrap_err()
+        .contains("before authorization selection"));
+}
+
+#[test]
+fn role_policy_rejects_non_finite_and_hides_js_unsafe_integers() {
+    let full = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+    for value in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
+        let grants = BTreeMap::from([(
+            "OrderView".into(),
+            RoleGrant::all_columns().rows(super::super::col("status").eq(value)),
+        )]);
+        assert!(surface_for_role(&full, "user", &grants)
+            .unwrap_err()
+            .contains("must be finite"));
+    }
+
+    let mut integer_orders = orders();
+    integer_orders.columns.push(TableColumn::new(
+        "sequence",
+        "sequence",
+        ColumnType::Integer,
+    ));
+    let full = build_surface(&[integer_orders], &SurfaceOptions::sqlite()).unwrap();
+    let grants = BTreeMap::from([(
+        "OrderView".into(),
+        RoleGrant::all_columns().rows(super::super::col("sequence").eq(9_007_199_254_740_992_i64)),
+    )]);
+    let selected = surface_for_role(&full, "user", &grants).unwrap();
+    assert_eq!(
+        selected.models["OrderView"].row_policy,
+        SurfaceRowPolicy::ServerOnly
+    );
+}
+
+#[test]
+fn command_surface_rejects_duplicate_mutation_field_ids() {
+    let output = GraphqlTypeDef::new(
+        "TestCommandPayload",
+        vec![GraphqlTypeField {
+            name: "id".into(),
+            type_name: "String".into(),
+            nullable: false,
+            list: false,
+            item_nullable: false,
+            nested: None,
+        }],
+    );
+    let commands = test_inventory([
+        test_command("order.create", "orders_write", output.clone()),
+        test_command("order.replace", "orders_write", output),
+    ]);
+    let error = build_surface(&[orders()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_typed_commands(&commands)
+        .unwrap_err();
+    assert!(error.contains("duplicate command mutation field `orders_write`"));
+}
+
+#[test]
+fn command_surface_rejects_empty_nested_and_surface_colliding_types() {
+    let empty = test_inventory([test_command(
+        "order.empty",
+        "order_empty",
+        GraphqlTypeDef::new("EmptyPayload", Vec::new()),
+    )]);
+    let error = build_surface(&[orders()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_typed_commands(&empty)
+        .unwrap_err();
+    assert!(error.contains("must declare at least one field"), "{error}");
+
+    let nested = test_inventory([test_command(
+        "order.nested_empty",
+        "order_nested_empty",
+        GraphqlTypeDef::new(
+            "OuterPayload",
+            vec![GraphqlTypeField {
+                name: "inner".into(),
+                type_name: "InnerPayload".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: Some(Box::new(GraphqlTypeDef::new("InnerPayload", Vec::new()))),
+            }],
+        ),
+    )]);
+    let error = build_surface(&[orders()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_typed_commands(&nested)
+        .unwrap_err();
+    assert!(error.contains("`InnerPayload` must declare at least one field"));
+
+    let collision = test_inventory([test_command(
+        "order.collision",
+        "order_collision",
+        GraphqlTypeDef::new(
+            "OrderView",
+            vec![GraphqlTypeField {
+                name: "order_id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            }],
+        ),
+    )]);
+    let error = build_surface(&[orders()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_typed_commands(&collision)
+        .unwrap_err();
+    assert!(error.contains("collides with a Surface GraphQL type"));
+}
+
+#[test]
+fn projected_output_reuse_and_sdl_emission_use_the_same_exact_predicate() {
+    let schema: &'static TableSchema = Box::leak(Box::new(orders()));
+    let projected_model = CommandProjectedModel {
+        output_type_id: std::any::TypeId::of::<()>(),
+        model: "OrderView".into(),
+        table: "orders".into(),
+        schema,
+        partition: None,
+    };
+    let projected_command = |output: SurfaceTypeDef| SurfaceCommand {
+        command_name: "order.projected".into(),
+        field_name: "order_projected".into(),
+        roles: Vec::new(),
+        input: SurfaceCommandShape::None,
+        output: SurfaceCommandShape::Typed(output),
+        consistency: CommandConsistency::Projected,
+        input_defaults: Vec::new(),
+        effects: Some(CommandEffects::revalidate()),
+        confirmations: Vec::new(),
+        projected_model: Some(projected_model.clone()),
+        direct_projection: None,
+        confirmation_unavailable: false,
+    };
+    let one_string_field = |name: &str| SurfaceTypeDef {
+        name: name.into(),
+        fields: vec![SurfaceTypeField {
+            name: "order_id".into(),
+            type_name: "String".into(),
+            nullable: false,
+            list: false,
+            item_nullable: false,
+            nested: None,
+        }],
+    };
+
+    let mut custom = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+    custom.commands = vec![projected_command(one_string_field(
+        "CustomProjectedPayload",
+    ))];
+    validate_and_canonicalize_commands(
+        &custom.models,
+        &custom.comparison_ops,
+        &mut custom.commands,
+    )
+    .unwrap();
+    let sdl = crate::graphql::sdl::graphql_sdl_from_surface(&custom).unwrap();
+    assert!(
+        sdl.contains("type CustomProjectedPayload {"),
+        "a non-reused projected output must still be emitted: {sdl}"
+    );
+
+    let mut mismatched = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+    mismatched.commands = vec![projected_command(one_string_field("OrderView"))];
+    let error = validate_and_canonicalize_commands(
+        &mismatched.models,
+        &mismatched.comparison_ops,
+        &mut mismatched.commands,
+    )
+    .unwrap_err();
+    assert!(
+        error.contains("does not match the normalized Surface model columns"),
+        "{error}"
+    );
+}
+
+#[test]
+fn surface_for_role_drops_ungranted_columns_and_models() {
+    let full = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+    let mut grants = BTreeMap::new();
+    grants.insert(
+        "OrderView".to_string(),
+        RoleGrant::columns(["order_id", "status"]),
+    );
+    let role_surface = surface_for_role(&full, "user", &grants).unwrap();
+    let model = role_surface.models.get("OrderView").expect("granted");
+    let col_names: Vec<_> = model.columns.iter().map(|c| c.name.as_str()).collect();
+    assert_eq!(col_names, vec!["order_id", "status"]);
+    assert!(!col_names.contains(&"customer_id"));
+    assert!(!col_names.contains(&"meta"));
+
+    let empty = surface_for_role(&full, "anon", &BTreeMap::new()).unwrap();
+    assert!(empty.models.is_empty());
+    assert!(empty.query_fields.is_empty());
+}
+
+#[test]
+fn role_surface_erases_denied_effects_and_retains_valid_trusted_presets() {
+    let mut full = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+    let input = SurfaceTypeDef {
+        name: "UpdateOrderInput".into(),
+        fields: vec![
+            SurfaceTypeField {
+                name: "order_id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            },
+            SurfaceTypeField {
+                name: "customer_id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            },
+        ],
+    };
+    let key = EffectKey {
+        fields: vec![EffectFieldValue {
+            field: "order_id".into(),
+            value: EffectExpression::Input {
+                path: vec!["order_id".into()],
+            },
+        }],
+    };
+    let denied_field_command = SurfaceCommand {
+        command_name: "order.assign_customer".into(),
+        field_name: "order_assign_customer".into(),
+        roles: Vec::new(),
+        input: SurfaceCommandShape::Typed(input.clone()),
+        output: SurfaceCommandShape::Typed(SurfaceTypeDef {
+            name: "AssignCustomerPayload".into(),
+            fields: vec![SurfaceTypeField {
+                name: "order_id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            }],
+        }),
+        consistency: CommandConsistency::Accepted,
+        input_defaults: Vec::new(),
+        effects: Some(CommandEffects::new([CommandEffect::Patch {
+            model: "OrderView".into(),
+            key: key.clone(),
+            fields: vec![EffectFieldValue {
+                field: "customer_id".into(),
+                value: EffectExpression::Input {
+                    path: vec!["customer_id".into()],
+                },
+            }],
+        }])),
+        confirmations: Vec::new(),
+        projected_model: None,
+        direct_projection: None,
+        confirmation_unavailable: false,
+    };
+    let trusted_preset_command = SurfaceCommand {
+        command_name: "order.apply_preset".into(),
+        field_name: "order_apply_preset".into(),
+        roles: Vec::new(),
+        input: SurfaceCommandShape::Typed(input),
+        output: SurfaceCommandShape::Typed(SurfaceTypeDef {
+            name: "ApplyPresetPayload".into(),
+            fields: vec![SurfaceTypeField {
+                name: "order_id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            }],
+        }),
+        consistency: CommandConsistency::Accepted,
+        input_defaults: Vec::new(),
+        effects: Some(CommandEffects::new([CommandEffect::Patch {
+            model: "OrderView".into(),
+            key,
+            fields: vec![EffectFieldValue {
+                field: "status".into(),
+                value: EffectExpression::TrustedPreset {
+                    name: "tenant-secret".into(),
+                },
+            }],
+        }])),
+        confirmations: Vec::new(),
+        projected_model: None,
+        direct_projection: None,
+        confirmation_unavailable: false,
+    };
+    full.commands = vec![denied_field_command, trusted_preset_command];
+    validate_and_canonicalize_commands(&full.models, &full.comparison_ops, &mut full.commands)
+        .unwrap();
+
+    let selected = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([(
+            "OrderView".into(),
+            RoleGrant::columns(["order_id", "status"]),
+        )]),
+    )
+    .unwrap();
+    let denied = selected
+        .commands
+        .iter()
+        .find(|command| command.command_name == "order.assign_customer")
+        .expect("denied-field command");
+    assert!(denied
+        .effects
+        .as_ref()
+        .is_some_and(|effects| effects.operations.is_empty()));
+    let trusted = selected
+        .commands
+        .iter()
+        .find(|command| command.command_name == "order.apply_preset")
+        .expect("trusted-preset command");
+    assert!(trusted
+        .effects
+        .as_ref()
+        .is_some_and(|effects| !effects.operations.is_empty()));
+
+    let manifest = super::super::client_manifest_from_surface(
+        "orders",
+        super::super::ClientSurfaceIdentity::role("user"),
+        &selected,
+    )
+    .unwrap();
+    let denied = manifest
+        .commands
+        .iter()
+        .find(|command| command.name == "order.assign_customer")
+        .expect("denied-field manifest command");
+    assert!(denied
+        .extensions
+        .effects
+        .as_ref()
+        .is_some_and(|effects| effects.operations.is_empty() && effects.fallback == "revalidate"));
+    assert!(denied.extensions.trusted_presets.is_empty());
+    let denied_effects_json = serde_json::to_string(&denied.extensions.effects).unwrap();
+    assert!(
+        !denied_effects_json.contains("customer_id"),
+        "{denied_effects_json}"
+    );
+    assert!(
+        !denied_effects_json.contains("tenant-secret"),
+        "{denied_effects_json}"
+    );
+
+    let trusted = manifest
+        .commands
+        .iter()
+        .find(|command| command.name == "order.apply_preset")
+        .expect("trusted-preset manifest command");
+    assert_eq!(
+        trusted.extensions.trusted_presets,
+        vec![super::super::ClientTrustedPresetDescriptor {
+            name: "tenant-secret".into(),
+            codec: "string".into(),
+        }]
+    );
+    let trusted_json = serde_json::to_string(trusted).unwrap();
+    assert!(trusted_json.contains("tenant-secret"), "{trusted_json}");
+    let preset_descriptors_json =
+        serde_json::to_string(&trusted.extensions.trusted_presets).unwrap();
+    assert!(
+        !preset_descriptors_json.contains("\"value\":"),
+        "{preset_descriptors_json}"
+    );
+}
+
+#[test]
+fn pool_free_role_selection_rejects_invalid_grants_and_policy_references() {
+    let full = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+
+    let unknown_model = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([("TypoView".into(), RoleGrant::all_columns())]),
+    )
+    .unwrap_err();
+    assert!(unknown_model.contains("unknown model `TypoView`"));
+
+    let unknown_column = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([(
+            "OrderView".into(),
+            RoleGrant::columns(["order_id", "statuz"]),
+        )]),
+    )
+    .unwrap_err();
+    assert!(unknown_column.contains("unknown column `statuz` in permission"));
+
+    let unknown_filter_column = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([(
+            "OrderView".into(),
+            RoleGrant::all_columns().rows(super::super::col("statuz").eq("open")),
+        )]),
+    )
+    .unwrap_err();
+    assert!(unknown_filter_column.contains("unknown column `statuz` in filter"));
+
+    let unknown_relationship = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([(
+            "OrderView".into(),
+            RoleGrant::all_columns().rows(super::super::rel(
+                "customer",
+                super::super::col("id").eq("c1"),
+            )),
+        )]),
+    )
+    .unwrap_err();
+    assert!(unknown_relationship.contains("is not a relationship on model `OrderView`"));
+}
+
+#[test]
+fn pool_free_role_selection_rejects_mistyped_row_policy_literals() {
+    let full = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+    let cmp_error = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([(
+            "OrderView".into(),
+            RoleGrant::all_columns().rows(FilterExpr::Cmp {
+                column: "status".into(),
+                op: super::super::filter::CmpOp::Eq,
+                rhs: Operand::Lit(super::super::LitValue::Json(serde_json::json!("open"))),
+            }),
+        )]),
+    )
+    .unwrap_err();
+    assert!(cmp_error.contains("literal kind `json`"), "{cmp_error}");
+    assert!(cmp_error.contains("column `status`"), "{cmp_error}");
+
+    let in_error = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([(
+            "OrderView".into(),
+            RoleGrant::all_columns().rows(FilterExpr::In {
+                column: "status".into(),
+                values: vec![
+                    Operand::from("open"),
+                    Operand::Lit(super::super::LitValue::Json(serde_json::json!("closed"))),
+                ],
+                negated: false,
+            }),
+        )]),
+    )
+    .unwrap_err();
+    assert!(in_error.contains("IN operand 1"), "{in_error}");
+}
+
+#[test]
+fn selected_surface_debug_does_not_leak_denied_schema_metadata() {
+    let full = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+    let selected = surface_for_role(
+        &full,
+        "user",
+        &BTreeMap::from([(
+            "OrderView".into(),
+            RoleGrant::columns(["order_id", "status"]),
+        )]),
+    )
+    .unwrap();
+
+    let debug = format!("{selected:?}");
+    assert!(debug.contains("OrderView"));
+    assert!(!debug.contains("customer_id"), "{debug}");
+    assert!(!debug.contains("meta"), "{debug}");
+}
+
+#[test]
+fn surface_for_role_omits_aggregate_without_grant() {
+    let full = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+    let mut grants = BTreeMap::new();
+    grants.insert("OrderView".to_string(), RoleGrant::all_columns());
+    let role_surface = surface_for_role(&full, "user", &grants).unwrap();
+    let names = role_surface.query_root_names();
+    assert!(names.contains(&"orders"));
+    assert!(!names.contains(&"orders_aggregate"));
+
+    let mut admin = BTreeMap::new();
+    admin.insert(
+        "OrderView".to_string(),
+        RoleGrant::all_columns().with_aggregations(),
+    );
+    let admin_surface = surface_for_role(&full, "admin", &admin).unwrap();
+    assert!(admin_surface
+        .query_root_names()
+        .contains(&"orders_aggregate"));
+}
+
+#[test]
+fn relationship_only_when_target_on_surface() {
+    let parent = TableSchema {
+        model_name: "ParentView".into(),
+        table_name: "parents".into(),
+        columns: vec![TableColumn {
+            primary_key: true,
+            ..TableColumn::new("id", "id", ColumnType::Text)
+        }],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "children".into(),
+            kind: RelationshipKind::HasMany,
+            target_model: "ChildView".into(),
+            foreign_key: Some("parent_id".into()),
+            through: None,
+            target_foreign_key: None,
+        }],
+        kind: TableKind::ReadModel,
+    };
+    let child = TableSchema {
+        model_name: "ChildView".into(),
+        table_name: "children".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("id", "id", ColumnType::Text)
+            },
+            TableColumn::new("parent_id", "parent_id", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    };
+    let both = build_surface(&[parent.clone(), child], &SurfaceOptions::sqlite()).unwrap();
+    assert!(both
+        .models
+        .get("ParentView")
+        .unwrap()
+        .relationships
+        .iter()
+        .any(|r| r.name == "children"));
+
+    let parent_only = build_surface(&[parent], &SurfaceOptions::sqlite()).unwrap();
+    assert!(parent_only
+        .models
+        .get("ParentView")
+        .unwrap()
+        .relationships
+        .is_empty());
+}
+
+#[test]
+fn surface_rejects_relationship_and_generated_aggregate_field_collisions() {
+    let child = TableSchema {
+        model_name: "CollisionChild".into(),
+        table_name: "collision_children".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("id", "id", ColumnType::Text)
+            },
+            TableColumn::new("parent_id", "parent_id", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    };
+    let parent = TableSchema {
+        model_name: "CollisionParent".into(),
+        table_name: "collision_parents".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("id", "id", ColumnType::Text)
+            },
+            TableColumn::new("children_aggregate", "children_aggregate", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "children".into(),
+            kind: RelationshipKind::HasMany,
+            target_model: "CollisionChild".into(),
+            foreign_key: Some("parent_id".into()),
+            through: None,
+            target_foreign_key: None,
+        }],
+        kind: TableKind::ReadModel,
+    };
+    let error = build_surface(&[parent, child], &SurfaceOptions::sqlite()).unwrap_err();
+    assert!(error.contains("relationship aggregate `children_aggregate` collides"));
+}
+
+#[test]
+fn relationship_keys_canonicalize_rust_field_names_to_graphql_columns() {
+    let account = TableSchema {
+        model_name: "AccountView".into(),
+        table_name: "accounts".into(),
+        columns: vec![TableColumn {
+            primary_key: true,
+            ..TableColumn::new("account_id", "account_id", ColumnType::Text)
+        }],
+        primary_key: PrimaryKey::new(["account_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    };
+    let order = TableSchema {
+        model_name: "RenamedOrderView".into(),
+        table_name: "renamed_orders".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("order_id", "order_id", ColumnType::Text)
+            },
+            TableColumn::new("accountId", "account_id", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["order_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "account".into(),
+            kind: RelationshipKind::BelongsTo,
+            target_model: "AccountView".into(),
+            foreign_key: Some("accountId".into()),
+            through: None,
+            target_foreign_key: None,
+        }],
+        kind: TableKind::ReadModel,
+    };
+    let surface = build_surface(&[order, account], &SurfaceOptions::sqlite()).unwrap();
+    let relationship = &surface.models["RenamedOrderView"].relationships[0];
+    assert_eq!(
+        relationship.keys,
+        SurfaceRelationshipKeys::Direct {
+            local: vec!["account_id".into()],
+            remote: vec!["account_id".into()],
+        }
+    );
+}
+
+#[test]
+fn pool_free_role_selection_rejects_only_reachable_composite_relationships() {
+    let composite = TableSchema {
+        model_name: "CompositeView".into(),
+        table_name: "composites".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("tenant_id", "tenant_id", ColumnType::Text)
+            },
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("record_id", "record_id", ColumnType::Text)
+            },
+        ],
+        primary_key: PrimaryKey::new(["tenant_id", "record_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    };
+    let simple = TableSchema {
+        model_name: "SimpleView".into(),
+        table_name: "simples".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("simple_id", "simple_id", ColumnType::Text)
+            },
+            TableColumn::new("tenant_id", "tenant_id", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["simple_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "composite".into(),
+            kind: RelationshipKind::BelongsTo,
+            target_model: "CompositeView".into(),
+            foreign_key: Some("tenant_id".into()),
+            through: None,
+            target_foreign_key: None,
+        }],
+        kind: TableKind::ReadModel,
+    };
+    let full = build_surface(&[simple, composite], &SurfaceOptions::sqlite()).unwrap();
+
+    // Hidden catalog metadata cannot create a false rejection.
+    let source_only = surface_for_role(
+        &full,
+        "source-only",
+        &BTreeMap::from([("SimpleView".into(), RoleGrant::all_columns())]),
+    )
+    .unwrap();
+    assert!(source_only.models["SimpleView"].relationships.is_empty());
+
+    // A server-only policy may legitimately traverse a denied model, but
+    // it must still be rejected when the runtime's current join compiler
+    // cannot represent that composite identity safely.
+    let hidden_policy_error = surface_for_role(
+        &full,
+        "source-policy",
+        &BTreeMap::from([(
+            "SimpleView".into(),
+            RoleGrant::all_columns().rows(super::super::rel(
+                "composite",
+                super::super::col("tenant_id").eq("tenant-a"),
+            )),
+        )]),
+    )
+    .unwrap_err();
+    assert!(
+        hidden_policy_error.contains("composite-key topology"),
+        "{hidden_policy_error}"
+    );
+
+    // Once both models are reachable, pool-free export fails at the same
+    // selected-Surface boundary as runtime engine construction.
+    let error = surface_for_role(
+        &full,
+        "both",
+        &BTreeMap::from([
+            ("CompositeView".into(), RoleGrant::all_columns()),
+            ("SimpleView".into(), RoleGrant::all_columns()),
+        ]),
+    )
+    .unwrap_err();
+    assert!(error.contains("relationship topology"), "{error}");
+}
+
+/// Production path: build_surface → surface_for_role → SDL (gap A10).
+#[test]
+fn role_sdl_production_path_omits_ungranted_columns() {
+    use super::super::sdl::{graphql_sdl_for_role, SdlOptions};
+
+    let mut grants = BTreeMap::new();
+    grants.insert(
+        "OrderView".to_string(),
+        RoleGrant::columns(["order_id", "status"]),
+    );
+    let sdl = graphql_sdl_for_role(&[orders()], &SdlOptions::sqlite(), "user", &grants)
+        .expect("role sdl");
+
+    // Granted
+    assert!(
+        sdl.contains("order_id") && sdl.contains("status"),
+        "expected granted columns in SDL: {sdl}"
+    );
+    // Ungranted column fields must not appear on the object type body.
+    // (meta / customer_id were not granted)
+    assert!(
+        !sdl.contains("customer_id"),
+        "ungranted customer_id leaked into role SDL: {sdl}"
+    );
+    assert!(
+        !sdl.contains("meta"),
+        "ungranted meta leaked into role SDL: {sdl}"
+    );
+    // SQLite: no PG JSON ops even if JSON columns were granted
+    for forbidden in ["_contains", "_contained_in", "_has_key"] {
+        assert!(
+            !sdl.contains(forbidden),
+            "SQLite role SDL must not expose {forbidden}"
+        );
+    }
+}
+
+#[test]
+fn role_sdl_empty_grants_has_no_query_roots() {
+    use super::super::sdl::{graphql_sdl_for_role, SdlOptions};
+
+    let sdl = graphql_sdl_for_role(&[orders()], &SdlOptions::sqlite(), "anon", &BTreeMap::new())
+        .expect("empty role sdl");
+    // No list roots for orders when model ungranted
+    assert!(
+        !sdl.contains("orders(") && !sdl.contains("orders:"),
+        "empty grants should not expose orders roots: {sdl}"
+    );
+    assert!(sdl.contains("type Query {\n  _empty: Boolean!\n}"));
+}
+
+#[test]
+fn constant_validation_uses_exact_wire_scalar_domains() {
+    let command = SurfaceCommand {
+        command_name: "test.constant".into(),
+        field_name: "test_constant".into(),
+        roles: Vec::new(),
+        input: SurfaceCommandShape::None,
+        output: SurfaceCommandShape::Typed(SurfaceTypeDef {
+            name: "ConstantPayload".into(),
+            fields: vec![SurfaceTypeField {
+                name: "ok".into(),
+                type_name: "Boolean".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            }],
+        }),
+        consistency: CommandConsistency::Accepted,
+        input_defaults: Vec::new(),
+        effects: Some(CommandEffects::revalidate()),
+        confirmations: Vec::new(),
+        projected_model: None,
+        direct_projection: None,
+        confirmation_unavailable: false,
+    };
+    let constant = |value| EffectExpression::Constant { value };
+    let column = |name: &str, scalar: &str| ColumnField {
+        name: name.into(),
+        scalar: scalar.into(),
+        nullable: false,
+    };
+
+    for (value, scalar) in [
+        (serde_json::json!(1.5), "BigInt"),
+        (serde_json::json!(2_147_483_648_i64), "Int"),
+        (serde_json::json!("not-a-timestamp"), "Timestamptz"),
+        (serde_json::json!("***"), "Bytea"),
+    ] {
+        assert!(
+            validate_effect_expression(&command, &constant(value), &column("value", scalar),)
+                .is_err()
+        );
+    }
+
+    for (value, scalar) in [
+        (serde_json::json!(42), "BigInt"),
+        (serde_json::json!("2026-07-22T12:30:45.123Z"), "Timestamptz"),
+        (serde_json::json!("AQID"), "Bytea"),
+    ] {
+        assert!(
+            validate_effect_expression(&command, &constant(value), &column("value", scalar),)
+                .is_ok()
+        );
+    }
+}
+
+#[test]
+fn missing_surface_primary_key_column_is_a_configuration_error_not_a_panic() {
+    let surface = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+    let mut model = surface.models["OrderView"].clone();
+    model.columns.retain(|column| column.name != "order_id");
+    let models = BTreeMap::from([("OrderView".into(), model)]);
+    let command = SurfaceCommand {
+        command_name: "order.patch".into(),
+        field_name: "order_patch".into(),
+        roles: Vec::new(),
+        input: SurfaceCommandShape::None,
+        output: SurfaceCommandShape::Typed(SurfaceTypeDef {
+            name: "PatchOrderPayload".into(),
+            fields: vec![SurfaceTypeField {
+                name: "order_id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            }],
+        }),
+        consistency: CommandConsistency::Accepted,
+        input_defaults: Vec::new(),
+        effects: Some(CommandEffects::revalidate()),
+        confirmations: Vec::new(),
+        projected_model: None,
+        direct_projection: None,
+        confirmation_unavailable: false,
+    };
+    let key = EffectKey {
+        fields: vec![EffectFieldValue {
+            field: "order_id".into(),
+            value: EffectExpression::Constant {
+                value: serde_json::json!("order-1"),
+            },
+        }],
+    };
+
+    let result =
+        std::panic::catch_unwind(|| validate_effect_key(&models, &command, "OrderView", &key));
+    let error = result
+        .expect("malformed Surface metadata must not panic")
+        .expect_err("missing primary-key column must fail closed");
+    assert!(error.contains("missing or hidden on the selected Surface"));
+}
+
+/// A7: role×dialect inventory + IR→SDL ops stay aligned (portable fixture).
+#[test]
+fn a7_role_dialect_parity_inventory_and_sdl_ops() {
+    use super::super::sdl::{graphql_sdl_for_role, SdlOptions};
+
+    let full_sqlite = build_surface(&[orders()], &SurfaceOptions::sqlite()).unwrap();
+    let full_pg = build_surface(&[orders()], &SurfaceOptions::postgres()).unwrap();
+
+    // Dialect honesty on full surface
+    let sqlite_json = full_sqlite.comparison_ops_for_scalar("JSON");
+    let pg_json = full_pg.comparison_ops_for_scalar("JSON");
+    assert!(sqlite_json.contains(&"_eq"));
+    assert!(!sqlite_json.contains(&"_contains"));
+    assert!(pg_json.contains(&"_contains"));
+
+    let mut grants = BTreeMap::new();
+    grants.insert(
+        "OrderView".to_string(),
+        RoleGrant::columns(["order_id", "status"]),
+    );
+
+    for (opts, dialect_label) in [
+        (SdlOptions::sqlite(), "sqlite"),
+        (SdlOptions::postgres(), "postgres"),
+    ] {
+        let full = build_surface(
+            &[orders()],
+            &SurfaceOptions {
+                dialect: if opts.jsonb_operators {
+                    SurfaceDialect::Postgres
+                } else {
+                    SurfaceDialect::Sqlite
+                },
+                aggregates: opts.aggregates,
+                subscriptions: opts.subscriptions,
+                default_limit: 100,
+                max_limit: 1000,
+            },
+        )
+        .unwrap();
+        let role_s = surface_for_role(&full, "user", &grants).unwrap();
+        let roots: Vec<_> = role_s.query_root_names();
+        assert!(
+            roots.contains(&"orders") && roots.contains(&"orders_by_pk"),
+            "{dialect_label}: missing list/by_pk roots {roots:?}"
+        );
+        assert!(
+            !roots.iter().any(|n| n.contains("aggregate")),
+            "{dialect_label}: aggregate without grant"
+        );
+        let cols: Vec<_> = role_s
+            .models
+            .get("OrderView")
+            .unwrap()
+            .columns
+            .iter()
+            .map(|c| c.name.as_str())
+            .collect();
+        assert_eq!(cols, vec!["order_id", "status"]);
+
+        let sdl = graphql_sdl_for_role(&[orders()], &opts, "user", &grants).unwrap();
+        assert!(
+            sdl.contains("order_id") && !sdl.contains("customer_id"),
+            "{dialect_label}: SDL column leak: {sdl}"
+        );
+        // SQLite role SDL never exposes PG JSON ops even if dialect flag wrong on unused scalars
+        if !opts.jsonb_operators {
+            for forbidden in ["_contains", "_contained_in", "_has_key"] {
+                assert!(
+                    !sdl.contains(forbidden),
+                    "{dialect_label}: {forbidden} in SDL"
+                );
+            }
+        }
+    }
+}
diff --git a/src/graphql/surface/types.rs b/src/graphql/surface/types.rs
new file mode 100644
index 00000000..e128b00a
--- /dev/null
+++ b/src/graphql/surface/types.rs
@@ -0,0 +1,711 @@
+use super::*;
+
+/// Dialect gate for comparison operators (JSON ops only on Postgres).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum SurfaceDialect {
+    Sqlite,
+    Postgres,
+}
+
+impl SurfaceDialect {
+    pub fn is_postgres(self) -> bool {
+        matches!(self, Self::Postgres)
+    }
+}
+
+/// Options for building a surface from a table catalog.
+#[derive(Clone, Debug)]
+pub struct SurfaceOptions {
+    pub dialect: SurfaceDialect,
+    pub aggregates: bool,
+    pub subscriptions: bool,
+    /// Default page size used when a list request omits `limit`.
+    pub default_limit: u64,
+    /// Absolute page-size ceiling enforced by the query compiler.
+    pub max_limit: u64,
+}
+
+impl SurfaceOptions {
+    pub fn sqlite() -> Self {
+        Self {
+            dialect: SurfaceDialect::Sqlite,
+            aggregates: true,
+            subscriptions: true,
+            default_limit: 100,
+            max_limit: 1000,
+        }
+    }
+
+    pub fn postgres() -> Self {
+        Self {
+            dialect: SurfaceDialect::Postgres,
+            aggregates: true,
+            subscriptions: true,
+            default_limit: 100,
+            max_limit: 1000,
+        }
+    }
+}
+
+/// Row-authorization semantics retained on the role/application surface.
+///
+/// `ServerOnly` is the fail-closed representation when a predicate differs
+/// across application roles or references a field that is not authorized on
+/// the selected surface. Clients may revalidate such collections but must not
+/// evaluate membership locally.
+#[derive(Clone, Debug, PartialEq)]
+pub enum SurfaceRowPolicy {
+    Unrestricted,
+    Predicate(FilterExpr),
+    ServerOnly,
+}
+
+/// Semantic category for one GraphQL field argument.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum SurfaceArgumentKind {
+    Filter,
+    Order,
+    Limit,
+    Offset,
+    PrimaryKey,
+}
+
+/// One accepted root/relationship argument from the shared Surface IR.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SurfaceArgument {
+    pub name: String,
+    pub kind: SurfaceArgumentKind,
+    pub type_name: String,
+    pub nullable: bool,
+    pub list: bool,
+}
+
+/// Kind of a GraphQL root field on Query / Subscription.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum RootKind {
+    List,
+    ByPk,
+    Aggregate,
+}
+
+/// One Query or Subscription root field inventory entry.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct RootField {
+    pub name: String,
+    pub kind: RootKind,
+    /// GraphQL object type name (`model_name`).
+    pub object: String,
+    /// Model name in the catalog (`schema.model_name`).
+    pub model_name: String,
+    pub arguments: Vec<SurfaceArgument>,
+    /// Physical read-model dependencies used only for invalidation planning.
+    pub dependencies: Vec<String>,
+    pub default_limit: Option<u64>,
+    pub max_limit: Option<u64>,
+}
+
+/// Column field on an object type (after skips / role filter).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ColumnField {
+    pub name: String,
+    pub scalar: String,
+    pub nullable: bool,
+}
+
+/// Relationship field inventory (target must be on the surface).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct RelField {
+    pub name: String,
+    pub target_model: String,
+    pub target_object: String,
+    pub kind: RelationshipKind,
+    pub list: bool,
+    /// Nullability of an object relationship. List relationships are always
+    /// non-null lists and ignore this flag.
+    pub nullable: bool,
+    pub arguments: Vec<SurfaceArgument>,
+    pub keys: SurfaceRelationshipKeys,
+    pub dependencies: Vec<String>,
+    pub aggregate: Option<SurfaceRelationshipAggregate>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SurfaceRelationshipAggregate {
+    pub name: String,
+    pub type_name: String,
+    pub arguments: Vec<SurfaceArgument>,
+    pub dependencies: Vec<String>,
+}
+
+/// Key/join metadata derived once from `RelationshipDef` while building the
+/// Surface. Manifest and compiler consumers never walk the table catalog again.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum SurfaceRelationshipKeys {
+    Direct {
+        local: Vec<String>,
+        remote: Vec<String>,
+    },
+    Through {
+        local: Vec<String>,
+        remote: Vec<String>,
+        table: String,
+        source_foreign_key: String,
+        target_foreign_key: String,
+    },
+    /// Source/target identities are authorized, while the operational join
+    /// table remains private. The opaque dependency is sufficient to mark
+    /// cached relationship edges stale without exposing join internals.
+    ThroughOpaque {
+        local: Vec<String>,
+        remote: Vec<String>,
+        dependency: String,
+    },
+    /// Relationship remains server-queryable, but its local/client identity
+    /// mapping is not authorized on this selected surface.
+    Embedded,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SurfaceTypeField {
+    pub name: String,
+    pub type_name: String,
+    pub nullable: bool,
+    pub list: bool,
+    pub item_nullable: bool,
+    pub nested: Option<Box<SurfaceTypeDef>>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SurfaceTypeDef {
+    pub name: String,
+    pub fields: Vec<SurfaceTypeField>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum SurfaceCommandShape {
+    None,
+    Typed(SurfaceTypeDef),
+}
+
+/// Structural command mutation carried by the same role-filtered Surface.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SurfaceCommand {
+    pub command_name: String,
+    pub field_name: String,
+    pub roles: Vec<String>,
+    pub input: SurfaceCommandShape,
+    pub output: SurfaceCommandShape,
+    pub consistency: CommandConsistency,
+    pub(crate) input_defaults: Vec<CommandInputDefault>,
+    pub(crate) effects: Option<CommandEffects>,
+    pub(crate) confirmations: Vec<CommandProjectionConfirmation>,
+    pub(crate) projected_model: Option<CommandProjectedModel>,
+    pub(crate) direct_projection: Option<CommandDirectProjectionTarget>,
+    /// Authorization selection erased at least one required confirmation.
+    /// No hidden projector/model/key IDs may survive into client artifacts.
+    pub(crate) confirmation_unavailable: bool,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(in crate::graphql::surface) enum SurfaceProjectionOwnerKind {
+    Direct,
+    Async,
+}
+
+/// Projection topology and complete read-model ownership declaration.
+///
+/// Construct an asynchronous owner through [`SurfaceProjector`] or a
+/// same-transaction-only owner through [`SurfaceDirectProjection`]. Keeping
+/// those public builder types separate prevents a direct owner from being
+/// registered as an asynchronous service route.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SurfaceProjectionOwner {
+    pub name: String,
+    pub facts: Vec<String>,
+    pub models: Vec<String>,
+    pub dependencies: Vec<String>,
+    pub(crate) change_epoch: Option<String>,
+    pub(crate) partition: ProjectionPartitionSpec,
+    pub(in crate::graphql::surface) kind: SurfaceProjectionOwnerKind,
+}
+
+impl SurfaceProjectionOwner {
+    pub fn is_direct(&self) -> bool {
+        matches!(self.kind, SurfaceProjectionOwnerKind::Direct)
+    }
+}
+
+/// Asynchronous fact-consuming projection declaration.
+///
+/// This is the only projection declaration accepted by
+/// [`crate::microsvc::Routes::causal_projector`]. Use
+/// [`SurfaceDirectProjection`] when `Projected<T>` owns the row entirely
+/// inside the command transaction.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SurfaceProjector {
+    owner: SurfaceProjectionOwner,
+}
+
+impl Deref for SurfaceProjector {
+    type Target = SurfaceProjectionOwner;
+
+    fn deref(&self) -> &Self::Target {
+        &self.owner
+    }
+}
+
+impl SurfaceProjector {
+    pub fn new(name: impl Into<String>) -> Self {
+        Self {
+            owner: SurfaceProjectionOwner {
+                name: name.into(),
+                facts: Vec::new(),
+                models: Vec::new(),
+                dependencies: Vec::new(),
+                change_epoch: None,
+                partition: ProjectionPartitionSpec::unit(),
+                kind: SurfaceProjectionOwnerKind::Async,
+            },
+        }
+    }
+
+    pub fn facts(mut self, facts: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        self.owner.facts = facts.into_iter().map(Into::into).collect();
+        self
+    }
+
+    pub fn models(mut self, models: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        self.owner.models = models.into_iter().map(Into::into).collect();
+        self
+    }
+
+    /// Register the opaque change-log epoch owned by this projector topology.
+    ///
+    /// Epoch contents have no ordering meaning. They fence live resume and
+    /// same-transaction record-change evidence across projector rebuilds.
+    pub fn change_epoch(mut self, epoch: impl Into<String>) -> Self {
+        self.owner.change_epoch = Some(epoch.into());
+        self
+    }
+
+    /// Derive a stable projection partition from one raw event JSON path.
+    ///
+    /// This closed declaration is evaluated before typed event decoding and is
+    /// hashed into the durable topology. Reuse this exact projector value for
+    /// GraphQL/direct binding and the asynchronous runtime.
+    pub fn partition_by(mut self, path: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        self.owner.partition = ProjectionPartitionSpec::input_path(path);
+        self
+    }
+
+    /// Use one deterministic constant partition (including explicit JSON null).
+    pub fn partition_constant(mut self, value: serde_json::Value) -> Self {
+        self.owner.partition = ProjectionPartitionSpec::constant(value);
+        self
+    }
+
+    /// Reuse this exact topology declaration in a typed command confirmation
+    /// plan. `command_confirmations!` calls this hidden seam so applications do
+    /// not repeat projector or model IDs as strings.
+    #[doc(hidden)]
+    pub fn __distributed_confirmation<I, M: crate::read_model::RelationalReadModel>(
+        &self,
+        key: TypedEffectKey<M>,
+    ) -> CompiledProjectionConfirmation<I> {
+        compiled_projection_confirmation(
+            &self.owner.name,
+            &self.owner.facts,
+            &self.owner.models,
+            &self.owner.partition,
+            key,
+        )
+    }
+
+    /// Compiler seam for binding one `Projected<M>` command to this exact
+    /// registered topology. Ordinary handlers never receive or construct it.
+    #[doc(hidden)]
+    pub fn __distributed_direct_projection<I, M>(&self) -> CompiledDirectProjectionTarget<I, M>
+    where
+        M: crate::read_model::RelationalReadModel + 'static,
+    {
+        compiled_direct_projection_target(
+            &self.owner.name,
+            &self.owner.facts,
+            &self.owner.models,
+            &self.owner.partition,
+            self.owner.change_epoch.as_deref(),
+        )
+    }
+}
+
+impl From<SurfaceProjector> for SurfaceProjectionOwner {
+    fn from(projector: SurfaceProjector) -> Self {
+        projector.owner
+    }
+}
+
+/// Same-transaction-only projection owner for `Projected<T>` commands.
+///
+/// It intentionally has no fact inventory and cannot be passed to an
+/// asynchronous projector route. The owner still supplies the complete model
+/// topology, partition codec, and change epoch used by direct commits, query
+/// evidence, live changes, and generated clients.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SurfaceDirectProjection {
+    owner: SurfaceProjectionOwner,
+}
+
+impl SurfaceDirectProjection {
+    pub fn new(name: impl Into<String>) -> Self {
+        Self {
+            owner: SurfaceProjectionOwner {
+                name: name.into(),
+                facts: Vec::new(),
+                models: Vec::new(),
+                dependencies: Vec::new(),
+                change_epoch: None,
+                partition: ProjectionPartitionSpec::unit(),
+                kind: SurfaceProjectionOwnerKind::Direct,
+            },
+        }
+    }
+
+    pub fn models(mut self, models: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        self.owner.models = models.into_iter().map(Into::into).collect();
+        self
+    }
+
+    /// Add one compile-checked relational model to this owner's inventory.
+    pub fn model<M>(mut self) -> Self
+    where
+        M: crate::read_model::RelationalReadModel,
+    {
+        self.owner.models.push(M::schema().model_name.clone());
+        self
+    }
+
+    /// Register the opaque change-log epoch for direct record evidence.
+    pub fn change_epoch(mut self, epoch: impl Into<String>) -> Self {
+        self.owner.change_epoch = Some(epoch.into());
+        self
+    }
+
+    /// Derive a stable direct-projection partition from a command input path.
+    pub fn partition_by(mut self, path: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        self.owner.partition = ProjectionPartitionSpec::input_path(path);
+        self
+    }
+
+    /// Use one deterministic constant partition (including explicit JSON null).
+    pub fn partition_constant(mut self, value: serde_json::Value) -> Self {
+        self.owner.partition = ProjectionPartitionSpec::constant(value);
+        self
+    }
+}
+
+impl From<SurfaceDirectProjection> for SurfaceProjectionOwner {
+    fn from(projection: SurfaceDirectProjection) -> Self {
+        projection.owner
+    }
+}
+
+/// One exposed read-model on the surface.
+#[derive(Clone)]
+pub struct SurfaceModel {
+    pub model_name: String,
+    pub table_name: String,
+    pub object_name: String,
+    pub columns: Vec<ColumnField>,
+    pub relationships: Vec<RelField>,
+    pub primary_key: Vec<String>,
+    pub row_policy: SurfaceRowPolicy,
+    pub role_limit: Option<u64>,
+    pub aggregations: bool,
+    /// Filtered schema clone (columns limited for role surfaces).
+    pub(crate) schema: TableSchema,
+}
+
+/// Whether this selected Surface exposes a complete client-safe normalized
+/// identity for the model. Both manifest normalization and keyed optimistic
+/// effects use this single predicate so an embedded model can never receive an
+/// operation that assumes a stable normalized cache key.
+pub(crate) fn model_has_client_normalized_identity(model: &SurfaceModel) -> bool {
+    !model.primary_key.is_empty()
+        && model.primary_key.iter().all(|key| {
+            model
+                .columns
+                .iter()
+                .find(|column| column.name == *key)
+                .is_some_and(|column| {
+                    !column.nullable
+                        && column.scalar != "BigInt"
+                        && matches!(
+                            column.scalar.as_str(),
+                            "Boolean"
+                                | "Bytea"
+                                | "Float"
+                                | "ID"
+                                | "Int"
+                                | "JSON"
+                                | "String"
+                                | "Timestamptz"
+                        )
+                })
+        })
+}
+
+/// Intermediate surface IR.
+#[derive(Clone)]
+pub struct Surface {
+    pub(crate) selection: SurfaceSelection,
+    // Structural fields stay crate-private so an authorized Surface cannot be
+    // mutated after selection and then exported under its original role/app
+    // provenance. Public consumers inspect derived artifacts or the read-only
+    // helpers below; only the selection/compiler pipeline may change the IR.
+    pub(crate) dialect: SurfaceDialect,
+    pub(crate) aggregates: bool,
+    pub(crate) subscriptions: bool,
+    pub(crate) default_limit: u64,
+    pub(crate) max_limit: u64,
+    /// Complete validated table catalog, including operational relationship
+    /// targets. It stays private and is carried through selection solely for
+    /// shared policy/topology validation; manifests never serialize it.
+    pub(crate) catalog: BTreeMap<String, TableSchema>,
+    /// Keyed by `model_name`.
+    pub(crate) models: BTreeMap<String, SurfaceModel>,
+    pub(crate) query_fields: Vec<RootField>,
+    pub(crate) subscription_fields: Vec<RootField>,
+    /// GraphQL comparison input name → operator field names (from `naming` only).
+    pub(crate) comparison_ops: BTreeMap<String, Vec<String>>,
+    pub(crate) commands: Vec<SurfaceCommand>,
+    /// Distinguishes an explicitly attached empty registry from a Surface that
+    /// has not selected its one authoritative command source yet.
+    pub(crate) commands_attached: bool,
+    pub(crate) projectors: Vec<SurfaceProjectionOwner>,
+    pub(crate) projectors_attached: bool,
+    /// Non-serializable provenance proving typed commands came from one
+    /// executable Service inventory rather than a lookalike command list.
+    pub(crate) service_binding:
+        Option<crate::graphql::command_contract::TypedServiceCommandBinding>,
+}
+
+/// Debug output is intentionally limited to already-authorized public IDs.
+/// The private catalog and filtered schema clones may contain denied names and
+/// must never become an authorization side channel through derived formatting.
+impl std::fmt::Debug for Surface {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("Surface")
+            .field("selection", &self.selection)
+            .field("dialect", &self.dialect)
+            .field("models", &self.models.keys().collect::<Vec<_>>())
+            .field("query_roots", &self.query_root_names())
+            .field("commands", &self.commands)
+            .field("projectors", &self.projectors)
+            .finish_non_exhaustive()
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) enum SurfaceSelection {
+    Catalog,
+    Role { name: String },
+    Application { name: String, roles: Vec<String> },
+}
+
+impl Surface {
+    /// Inventory of query root field names (sorted).
+    pub fn query_root_names(&self) -> Vec<&str> {
+        let mut names: Vec<&str> = self.query_fields.iter().map(|f| f.name.as_str()).collect();
+        names.sort();
+        names
+    }
+
+    /// Comparison operator fields for a scalar, empty if scalar unused.
+    pub fn comparison_ops_for_scalar(&self, scalar: &str) -> Vec<&str> {
+        let name = comparison_exp_name(scalar);
+        self.comparison_ops
+            .get(&name)
+            .map(|ops| ops.iter().map(String::as_str).collect())
+            .unwrap_or_default()
+    }
+
+    pub fn commands(&self) -> &[SurfaceCommand] {
+        &self.commands
+    }
+
+    pub fn projection_owners(&self) -> &[SurfaceProjectionOwner] {
+        &self.projectors
+    }
+
+    /// Backward-compatible name for the complete projection-owner registry.
+    ///
+    /// Direct-only owners are included even though they are not asynchronous
+    /// projectors.
+    pub fn projectors(&self) -> &[SurfaceProjectionOwner] {
+        self.projection_owners()
+    }
+
+    /// Attach the crate-private typed command inventory to this unselected
+    /// catalog surface. Public callers derive this exclusively via
+    /// [`Surface::with_service`].
+    pub(crate) fn with_typed_commands(
+        mut self,
+        commands: &crate::graphql::commands::TypedCommandInventory,
+    ) -> Result<Self, String> {
+        if !matches!(self.selection, SurfaceSelection::Catalog) {
+            return Err(
+                "commands can only be attached to the unselected catalog Surface before authorization selection"
+                    .into(),
+            );
+        }
+        if self.service_binding.is_some() {
+            return Err(
+                "commands are frozen after attachment from the executable Service inventory".into(),
+            );
+        }
+        if self.commands_attached {
+            return Err("a command registry has already been attached to this Surface".into());
+        }
+        self.commands = commands.surface_commands();
+        validate_and_canonicalize_commands(&self.models, &self.comparison_ops, &mut self.commands)?;
+        if self.projectors_attached {
+            bind_surface_direct_projection_targets(
+                &mut self.commands,
+                &self.projectors,
+                &self.models,
+            )?;
+            validate_command_confirmation_topology(&self.commands, &self.projectors, &self.models)?;
+        }
+        self.commands_attached = true;
+        Ok(self)
+    }
+
+    /// Pool-free authoritative typed command path. The executable Routes
+    /// inventory supplies both GraphQL declarations and non-forgeable service
+    /// provenance used by static client export.
+    pub fn with_service(mut self, service: &crate::microsvc::Service) -> Result<Self, String> {
+        if !matches!(self.selection, SurfaceSelection::Catalog) {
+            return Err(
+                "service commands can only be attached to the unselected catalog Surface before authorization selection"
+                    .into(),
+            );
+        }
+        if self.commands_attached {
+            return Err(
+                "service commands cannot replace an already attached command inventory".into(),
+            );
+        }
+        let binding = service.typed_command_binding()?;
+        let contracts = service.typed_command_contracts();
+        let commands = crate::graphql::commands::TypedCommandInventory::from_contracts(&contracts)?;
+        self = self.with_typed_commands(&commands)?;
+        self.service_binding = Some(binding);
+        Ok(self)
+    }
+
+    #[cfg(feature = "graphql")]
+    pub(crate) fn with_service_binding(
+        mut self,
+        binding: Option<crate::graphql::command_contract::TypedServiceCommandBinding>,
+    ) -> Self {
+        self.service_binding = binding;
+        self
+    }
+
+    /// Attach and validate projector topology against the already-built model
+    /// graph, deriving physical dependencies exactly once.
+    pub fn with_projectors(
+        self,
+        projectors: impl IntoIterator<Item = SurfaceProjector>,
+    ) -> Result<Self, String> {
+        self.with_projection_owners(projectors.into_iter().map(Into::into))
+    }
+
+    /// Attach and validate a mixed registry of asynchronous projectors and
+    /// same-transaction-only projection owners.
+    pub fn with_projection_owners(
+        mut self,
+        projectors: impl IntoIterator<Item = SurfaceProjectionOwner>,
+    ) -> Result<Self, String> {
+        if !matches!(self.selection, SurfaceSelection::Catalog) {
+            return Err(
+                "projection owners can only be attached to the unselected catalog Surface before authorization selection"
+                    .into(),
+            );
+        }
+        let mut out = Vec::new();
+        let mut names = BTreeSet::new();
+        for mut projector in projectors {
+            if projector.name.trim().is_empty() {
+                return Err("projector name must not be empty".into());
+            }
+            if !names.insert(projector.name.clone()) {
+                return Err(format!("duplicate projector name `{}`", projector.name));
+            }
+            match projector.kind {
+                SurfaceProjectionOwnerKind::Async if projector.facts.is_empty() => {
+                    return Err(format!(
+                        "projector `{}` must declare at least one fact",
+                        projector.name
+                    ));
+                }
+                SurfaceProjectionOwnerKind::Direct if !projector.facts.is_empty() => {
+                    return Err(format!(
+                        "direct projection owner `{}` cannot declare asynchronous facts",
+                        projector.name
+                    ));
+                }
+                SurfaceProjectionOwnerKind::Direct | SurfaceProjectionOwnerKind::Async => {}
+            }
+            validate_nonempty_unique_ids(
+                &projector.facts,
+                &format!("projector `{}` fact", projector.name),
+            )?;
+            if projector.models.is_empty() {
+                return Err(format!(
+                    "projector `{}` must declare at least one model",
+                    projector.name
+                ));
+            }
+            validate_nonempty_unique_ids(
+                &projector.models,
+                &format!("projector `{}` model", projector.name),
+            )?;
+            if let Some(epoch) = projector.change_epoch.as_deref() {
+                crate::projection_protocol::ProjectionEpoch::new(epoch).map_err(|error| {
+                    format!(
+                        "projector `{}` change-log epoch is invalid: {error}",
+                        projector.name
+                    )
+                })?;
+            }
+            projector.partition.validate().map_err(|error| {
+                format!(
+                    "projector `{}` has invalid partition declaration: {error}",
+                    projector.name
+                )
+            })?;
+            projector.facts.sort();
+            projector.models.sort();
+            let mut dependencies = BTreeSet::new();
+            for model in &projector.models {
+                let Some(surface_model) = self.models.get(model) else {
+                    return Err(format!(
+                        "projector `{}` targets unknown surface model `{model}`",
+                        projector.name
+                    ));
+                };
+                dependencies.insert(surface_model.table_name.clone());
+            }
+            projector.dependencies = dependencies.into_iter().collect();
+            out.push(projector);
+        }
+        out.sort_by(|a, b| a.name.cmp(&b.name));
+        bind_surface_direct_projection_targets(&mut self.commands, &out, &self.models)?;
+        self.projectors = out;
+        self.projectors_attached = true;
+        validate_command_confirmation_topology(&self.commands, &self.projectors, &self.models)?;
+        Ok(self)
+    }
+}
diff --git a/src/graphql/surface/validation.rs b/src/graphql/surface/validation.rs
new file mode 100644
index 00000000..d7a96ab2
--- /dev/null
+++ b/src/graphql/surface/validation.rs
@@ -0,0 +1,107 @@
+use super::*;
+
+pub(in crate::graphql::surface) fn validate_nonempty_unique_ids(
+    values: &[String],
+    label: &str,
+) -> Result<(), String> {
+    let mut seen = BTreeSet::new();
+    for value in values {
+        if value.trim().is_empty() {
+            return Err(format!("{label} id must not be empty"));
+        }
+        if !seen.insert(value) {
+            return Err(format!("duplicate {label} id `{value}`"));
+        }
+    }
+    Ok(())
+}
+
+pub(in crate::graphql::surface) fn validate_root_ids(
+    fields: &[RootField],
+    operation: &str,
+) -> Result<(), String> {
+    let mut names = BTreeSet::new();
+    for field in fields {
+        if field.name.trim().is_empty() {
+            return Err(format!("{operation} root id must not be empty"));
+        }
+        if !names.insert(&field.name) {
+            return Err(format!(
+                "duplicate {operation} root id `{}` in Surface inventory",
+                field.name
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(in crate::graphql::surface) fn validate_generated_surface_names(
+    models: &BTreeMap<String, SurfaceModel>,
+    comparison_ops: &BTreeMap<String, Vec<String>>,
+) -> Result<(), String> {
+    let mut type_names: BTreeSet<String> = reserved_type_names().map(str::to_string).collect();
+    let mut claim_type = |name: String| -> Result<(), String> {
+        if !is_valid_graphql_name(&name) {
+            return Err(format!(
+                "generated type name `{name}` is not a valid GraphQL name"
+            ));
+        }
+        if !type_names.insert(name.clone()) {
+            return Err(format!(
+                "generated type name `{name}` collides with another Surface type"
+            ));
+        }
+        Ok(())
+    };
+    for name in comparison_ops.keys() {
+        claim_type(name.clone())?;
+    }
+    for model in models.values() {
+        claim_type(model.object_name.clone())?;
+        claim_type(format!("{}_bool_exp", model.table_name))?;
+        claim_type(format!("{}_order_by", model.table_name))?;
+        if model.aggregations {
+            claim_type(format!("{}_aggregate", model.table_name))?;
+            claim_type(format!("{}_aggregate_fields", model.table_name))?;
+        }
+
+        let mut object_fields = BTreeSet::new();
+        for column in &model.columns {
+            if matches!(column.name.as_str(), "_and" | "_or" | "_not") {
+                return Err(format!(
+                    "model `{}` field `{}` collides with a generated boolean-expression field",
+                    model.model_name, column.name
+                ));
+            }
+            if !object_fields.insert(column.name.clone()) {
+                return Err(format!(
+                    "model `{}` has duplicate GraphQL object field `{}`",
+                    model.model_name, column.name
+                ));
+            }
+        }
+        for relationship in &model.relationships {
+            if matches!(relationship.name.as_str(), "_and" | "_or" | "_not") {
+                return Err(format!(
+                    "model `{}` relationship `{}` collides with a generated boolean-expression field",
+                    model.model_name, relationship.name
+                ));
+            }
+            if !object_fields.insert(relationship.name.clone()) {
+                return Err(format!(
+                    "model `{}` relationship `{}` collides with another object field",
+                    model.model_name, relationship.name
+                ));
+            }
+            if let Some(aggregate) = &relationship.aggregate {
+                if !object_fields.insert(aggregate.name.clone()) {
+                    return Err(format!(
+                        "model `{}` relationship aggregate `{}` collides with another object field",
+                        model.model_name, aggregate.name
+                    ));
+                }
+            }
+        }
+    }
+    Ok(())
+}
diff --git a/src/graphql/types.rs b/src/graphql/types.rs
new file mode 100644
index 00000000..d8749b32
--- /dev/null
+++ b/src/graphql/types.rs
@@ -0,0 +1,85 @@
+//! Command-mutation GraphQL type metadata (input/output derives).
+
+use std::any::TypeId;
+
+/// One field on a GraphQL input or output object.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GraphqlTypeField {
+    pub name: String,
+    pub type_name: String,
+    pub nullable: bool,
+    pub list: bool,
+    /// Whether list elements are nullable. Always `false` for non-list fields.
+    pub item_nullable: bool,
+    /// Nested object type definition when `type_name` is not a scalar.
+    pub nested: Option<Box<GraphqlTypeDef>>,
+}
+
+/// Full type definition for a derive-emitted input or output object.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GraphqlTypeDef {
+    pub name: String,
+    pub fields: Vec<GraphqlTypeField>,
+    pub type_id: Option<TypeId>,
+}
+
+impl GraphqlTypeDef {
+    pub fn new(name: impl Into<String>, fields: Vec<GraphqlTypeField>) -> Self {
+        Self {
+            name: name.into(),
+            fields,
+            type_id: None,
+        }
+    }
+
+    pub fn with_type_id(mut self, id: TypeId) -> Self {
+        self.type_id = Some(id);
+        self
+    }
+
+    /// Transitive nested type defs (depth-first, deduped by name).
+    pub fn transitive_nested(&self) -> Vec<GraphqlTypeDef> {
+        let mut out = Vec::new();
+        let mut seen = std::collections::BTreeSet::new();
+        self.collect_nested(&mut out, &mut seen);
+        out
+    }
+
+    fn collect_nested(
+        &self,
+        out: &mut Vec<GraphqlTypeDef>,
+        seen: &mut std::collections::BTreeSet<String>,
+    ) {
+        for field in &self.fields {
+            if let Some(nested) = &field.nested {
+                if seen.insert(nested.name.clone()) {
+                    out.push((**nested).clone());
+                    nested.collect_nested(out, seen);
+                }
+            }
+        }
+    }
+}
+
+pub trait GraphqlInputType {
+    fn graphql_type() -> GraphqlTypeDef;
+}
+
+pub trait GraphqlOutputType {
+    fn graphql_type() -> GraphqlTypeDef;
+}
+
+// Builtin scalar mappings for free-standing helpers used by derives.
+#[allow(dead_code)]
+pub fn scalar_for_rust_type(ty: &str) -> Option<&'static str> {
+    match ty {
+        "String" | "str" => Some("String"),
+        "bool" => Some("Boolean"),
+        "i8" | "i16" | "i32" | "i64" | "u8" | "u16" | "u32" | "u64" | "isize" | "usize" => {
+            Some("BigInt")
+        }
+        "f32" | "f64" => Some("Float"),
+        "Value" | "serde_json::Value" => Some("JSON"),
+        _ => None,
+    }
+}
diff --git a/src/in_memory_repo/mod.rs b/src/in_memory_repo/mod.rs
index 947157eb..971a2c14 100644
--- a/src/in_memory_repo/mod.rs
+++ b/src/in_memory_repo/mod.rs
@@ -1,3 +1,4 @@
+mod projection_protocol;
 mod repository;
 
 pub use repository::{InMemoryOutboxStore, InMemoryRepository};
diff --git a/src/in_memory_repo/projection_protocol/direct_projection.rs b/src/in_memory_repo/projection_protocol/direct_projection.rs
new file mode 100644
index 00000000..d41f32e5
--- /dev/null
+++ b/src/in_memory_repo/projection_protocol/direct_projection.rs
@@ -0,0 +1,120 @@
+use super::*;
+
+/// Stage one compiler-sealed same-transaction projected upsert against cloned
+/// row/protocol state. The caller publishes both clones only after every
+/// domain, ledger, and projection participant has passed validation.
+pub(in crate::in_memory_repo) fn stage_same_transaction_projection(
+    protocol: &mut InMemoryProjectionProtocolState,
+    staged_rows: &mut HashMap<String, StoredRow>,
+    batch: &SameTransactionProjectionBatch,
+    retention: ProjectionChangeRetention,
+) -> Result<SameTransactionProjectionEvidence, ProjectionProtocolError> {
+    batch.validate()?;
+    protocol.require_registered_topology(&batch.topology)?;
+
+    let partition_key = PartitionKey::new(&batch.topology, &batch.partition);
+    protocol.ensure_partition(&partition_key, &batch.change_epoch)?;
+    if let Some(failure_id) = protocol
+        .partitions
+        .get(&partition_key)
+        .and_then(|partition| partition.stopped_failure_id.clone())
+    {
+        return Err(ProjectionProtocolError::PartitionStopped { failure_id });
+    }
+    if protocol
+        .partitions
+        .get(&partition_key)
+        .is_some_and(|partition| partition.pending_retry_failure_id.is_some())
+    {
+        return Err(ProjectionProtocolError::IncomparableInput);
+    }
+    protocol.register_same_transaction_ownership(&partition_key, batch)?;
+
+    let mutation = &batch.mutations[0];
+    let lock_key = mutation.mutation.lock_key();
+    let row_exists = staged_rows.contains_key(&lock_key);
+    let revision = match protocol.records.get(&mutation.scope) {
+        None if !row_exists => RecordRevision::new(mutation.scope.clone(), 1, 1)?,
+        None => {
+            return Err(ProjectionProtocolError::RecordAlreadyExists {
+                model: mutation.scope.model().to_string(),
+            });
+        }
+        Some(metadata) if metadata.tombstone => {
+            return Err(ProjectionProtocolError::RecordTombstoned {
+                model: mutation.scope.model().to_string(),
+            });
+        }
+        Some(_) if !row_exists => {
+            return Err(ProjectionProtocolError::RecordMissing {
+                model: mutation.scope.model().to_string(),
+            });
+        }
+        Some(metadata) => RecordRevision::new(
+            mutation.scope.clone(),
+            metadata.revision.incarnation(),
+            checked_next(metadata.revision.revision(), "record revision")?,
+        )?,
+    };
+
+    let change = protocol.append_change(
+        &partition_key,
+        PendingChange {
+            kind: ProjectionChangeKind::RecordUpsert,
+            causation_id: batch.causation_id.clone(),
+            observation_kind: None,
+            scope: Some(mutation.scope.clone()),
+            revision: Some(revision.clone()),
+            failure_id: None,
+        },
+    )?;
+    let metadata = ProjectionRecordMetadata {
+        revision: revision.clone(),
+        tombstone: false,
+        change: change.cursor.clone(),
+    };
+    protocol.ensure_live_record_identity_available(&metadata)?;
+    protocol
+        .records
+        .insert(mutation.scope.clone(), metadata.clone());
+
+    apply_read_model_write_plan(
+        TableWritePlan::new(vec![mutation.mutation.clone()]),
+        staged_rows,
+    )?;
+    if !staged_rows.contains_key(&lock_key) {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "direct projection upsert left model `{}` without a physical row",
+            mutation.scope.model()
+        )));
+    }
+
+    let observation_key = ObservationKey {
+        causation_id: batch.causation_id.clone(),
+        scope: mutation.scope.clone(),
+        kind: ProjectionObservationKind::Record,
+    };
+    if protocol.observations.contains_key(&observation_key) {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "direct projection causation `{}` already observed this record",
+            batch.causation_id
+        )));
+    }
+    let observation = ProjectionObservation {
+        causation_id: batch.causation_id.clone(),
+        kind: ProjectionObservationKind::Record,
+        revision: Some(revision),
+        scope: mutation.scope.clone(),
+        change: change.cursor.clone(),
+    };
+    protocol
+        .observations
+        .insert(observation_key, observation.clone());
+    protocol.retain_change_suffix(&partition_key, retention)?;
+
+    Ok(SameTransactionProjectionEvidence {
+        records: vec![metadata],
+        changes: vec![change],
+        observations: vec![observation],
+    })
+}
diff --git a/src/in_memory_repo/projection_protocol/mod.rs b/src/in_memory_repo/projection_protocol/mod.rs
new file mode 100644
index 00000000..ee4fc963
--- /dev/null
+++ b/src/in_memory_repo/projection_protocol/mod.rs
@@ -0,0 +1,52 @@
+#![expect(
+    clippy::manual_async_fn,
+    reason = "trait impls preserve the ProjectionProtocolStore Send bounds"
+)]
+
+use std::collections::{BTreeMap, HashMap, HashSet};
+use std::future::Future;
+
+use super::InMemoryRepository;
+use crate::projection_protocol::{
+    change_kind_for_mutation, checked_next, failure_matches_batch, table_model_name,
+    ProjectionChange, ProjectionChangeCursor, ProjectionChangeKind, ProjectionChangeRead,
+    ProjectionChangeRetention, ProjectionCheckpoint, ProjectionCommitBatch,
+    ProjectionCommitOutcome, ProjectionCommitResult, ProjectionEpoch, ProjectionFailure,
+    ProjectionFailureBatch, ProjectionFailureLocation, ProjectionGeneration, ProjectionInputCursor,
+    ProjectionInputDisposition, ProjectionInputFingerprint, ProjectionLiveRecordBatch,
+    ProjectionLiveRecordBatchRequest, ProjectionMutationKind, ProjectionObligationEvidence,
+    ProjectionObligationEvidenceBatch, ProjectionObligationEvidenceBatchRequest,
+    ProjectionObservation, ProjectionObservationKind, ProjectionObservationTarget,
+    ProjectionPartition, ProjectionPartitionRuntimeState, ProjectionPendingRetry,
+    ProjectionProtocolError, ProjectionProtocolStore, ProjectionQuerySnapshot,
+    ProjectionQuerySnapshotBatch, ProjectionQuerySnapshotBatchRequest,
+    ProjectionQuerySnapshotRequest, ProjectionRecordExpectation, ProjectionRecordMetadata,
+    ProjectionRecordScope, ProjectionSource, ProjectorTopologyId, RecordRevision,
+    RevisionComparison, SameTransactionProjectionBatch, SameTransactionProjectionEvidence,
+    TrustedProjectionInput,
+};
+use crate::read_model::in_memory::{
+    apply_read_model_write_plan, relational_storage_key, StoredRow,
+};
+use crate::repository::RepositoryError;
+use crate::table::{TableMutation, TableStoreError, TableWritePlan};
+
+mod direct_projection;
+mod read_helpers;
+mod state;
+mod state_impl;
+mod store_impl;
+mod util;
+
+pub(super) use direct_projection::stage_same_transaction_projection;
+pub(super) use state::{reject_causal_owned_plans, InMemoryProjectionProtocolState};
+
+use read_helpers::{
+    read_projection_live_record_from_state, read_projection_obligation_evidence_from_state,
+    read_projection_query_snapshot_from_state,
+};
+use state::*;
+use util::storage_key_belongs_to_table;
+
+#[cfg(test)]
+mod tests;
diff --git a/src/in_memory_repo/projection_protocol/read_helpers.rs b/src/in_memory_repo/projection_protocol/read_helpers.rs
new file mode 100644
index 00000000..2848f63d
--- /dev/null
+++ b/src/in_memory_repo/projection_protocol/read_helpers.rs
@@ -0,0 +1,331 @@
+use super::*;
+
+pub(super) fn read_projection_query_snapshot_from_state(
+    rows: &HashMap<String, StoredRow>,
+    protocol: &InMemoryProjectionProtocolState,
+    request: &ProjectionQuerySnapshotRequest,
+) -> Result<ProjectionQuerySnapshot, ProjectionProtocolError> {
+    request.validate()?;
+    let registered_key = RegisteredModelKey {
+        topology: request.scope.topology().clone(),
+        model: request.scope.model().to_string(),
+    };
+    if protocol
+        .registered_models
+        .get(&registered_key)
+        .map(String::as_str)
+        != Some(request.schema.table_name.as_str())
+        || protocol
+            .authoritative_table_owners
+            .get(&request.schema.table_name)
+            != Some(&registered_key)
+    {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "projection query model `{}` is not the registered owner of table `{}`",
+            request.scope.model(),
+            request.schema.table_name
+        )));
+    }
+
+    let storage_key = relational_storage_key(&request.schema.table_name, &request.key);
+    let row = rows.get(&storage_key).map(|stored| stored.values.clone());
+    let record = protocol.records.get(&request.scope).cloned();
+    match (row.is_some(), record.as_ref()) {
+        (true, None)
+        | (
+            true,
+            Some(ProjectionRecordMetadata {
+                tombstone: true, ..
+            }),
+        ) => {
+            return Err(ProjectionProtocolError::RecordAlreadyExists {
+                model: request.scope.model().to_string(),
+            });
+        }
+        (
+            false,
+            Some(ProjectionRecordMetadata {
+                tombstone: false, ..
+            }),
+        ) => {
+            return Err(ProjectionProtocolError::RecordMissing {
+                model: request.scope.model().to_string(),
+            });
+        }
+        _ => {}
+    }
+
+    let partition_key = PartitionKey::new(
+        request.scope.topology(),
+        request.scope.projection_partition(),
+    );
+    let partition = protocol.partitions.get(&partition_key);
+    if record.is_some() && partition.is_none() {
+        return Err(ProjectionProtocolError::InvalidBatch(
+            "projection query record exists without partition state".into(),
+        ));
+    }
+
+    let (change_head, compacted_through) = match partition {
+        Some(partition) => {
+            if let Some(record) = &record {
+                if record.change.epoch() != &partition.change_epoch
+                    || record.change.position() > partition.change_head
+                {
+                    return Err(ProjectionProtocolError::InvalidBatch(
+                        "projection query record change lies outside its partition head".into(),
+                    ));
+                }
+            }
+            let head = if partition.change_head == 0 {
+                None
+            } else {
+                Some(ProjectionChangeCursor::new(
+                    request.scope.topology().clone(),
+                    request.scope.projection_partition().clone(),
+                    partition.change_epoch.clone(),
+                    partition.change_head,
+                )?)
+            };
+            (head, partition.compacted_through)
+        }
+        None => (None, 0),
+    };
+
+    let mut checkpoints = Vec::with_capacity(request.checkpoint_probes.len());
+    for probe in &request.checkpoint_probes {
+        let stored = protocol.inputs.get(&InputKey {
+            partition: partition_key.clone(),
+            source: probe.source.clone(),
+            generation: probe.generation,
+        });
+        let checkpoint = match stored {
+            Some(stored) => {
+                let Some(partition) = partition else {
+                    return Err(ProjectionProtocolError::InvalidBatch(
+                        "projection checkpoint exists without partition state".into(),
+                    ));
+                };
+                if stored.cursor.epoch() != &probe.epoch {
+                    return Err(ProjectionProtocolError::IncomparableInput);
+                }
+                if stored.checkpoint.change().epoch() != &partition.change_epoch
+                    || stored.checkpoint.change().position() > partition.change_head
+                {
+                    return Err(ProjectionProtocolError::InvalidBatch(
+                        "projection query checkpoint lies outside its partition head".into(),
+                    ));
+                }
+                Some(stored.checkpoint.clone())
+            }
+            None => None,
+        };
+        checkpoints.push(crate::projection_protocol::ProjectionCheckpointSnapshot {
+            probe: probe.clone(),
+            checkpoint,
+        });
+    }
+
+    Ok(ProjectionQuerySnapshot {
+        row,
+        record,
+        checkpoints,
+        change_head,
+        compacted_through,
+    })
+}
+
+pub(super) fn validate_observation_from_state(
+    protocol: &InMemoryProjectionProtocolState,
+    request: &crate::projection_protocol::ProjectionObligationEvidenceRequest,
+    observation: &ProjectionObservation,
+) -> Result<(), ProjectionProtocolError> {
+    if observation.causation_id != request.causation_id
+        || observation.kind != request.kind
+        || observation.scope != request.scope
+        || observation
+            .revision
+            .as_ref()
+            .is_some_and(|revision| revision.scope() != &request.scope)
+        || (request.kind == ProjectionObservationKind::Record) != observation.revision.is_some()
+    {
+        return Err(ProjectionProtocolError::InvalidBatch(
+            "stored projection observation does not match its exact evidence key".into(),
+        ));
+    }
+    let partition = protocol
+        .partitions
+        .get(&PartitionKey::new(
+            request.scope.topology(),
+            request.scope.projection_partition(),
+        ))
+        .ok_or_else(|| {
+            ProjectionProtocolError::InvalidBatch(
+                "stored projection observation has no partition state".into(),
+            )
+        })?;
+    if observation.change.topology() != request.scope.topology()
+        || observation.change.projection_partition() != request.scope.projection_partition()
+        || observation.change.epoch() != &partition.change_epoch
+        || observation.change.position() > partition.change_head
+    {
+        return Err(ProjectionProtocolError::InvalidBatch(
+            "stored projection observation change lies outside its partition".into(),
+        ));
+    }
+    Ok(())
+}
+
+pub(super) fn validate_failure_from_state(
+    protocol: &InMemoryProjectionProtocolState,
+    request: &crate::projection_protocol::ProjectionObligationEvidenceRequest,
+    failure: &ProjectionFailure,
+) -> Result<(), ProjectionProtocolError> {
+    if failure.causation_id != request.causation_id
+        || failure.input.topology() != request.scope.topology()
+        || failure.input.projection_partition() != request.scope.projection_partition()
+        || failure.change.topology() != request.scope.topology()
+        || failure.change.projection_partition() != request.scope.projection_partition()
+    {
+        return Err(ProjectionProtocolError::InvalidBatch(
+            "stored projection failure does not match its evidence scope".into(),
+        ));
+    }
+    let partition = protocol
+        .partitions
+        .get(&PartitionKey::new(
+            request.scope.topology(),
+            request.scope.projection_partition(),
+        ))
+        .ok_or_else(|| {
+            ProjectionProtocolError::InvalidBatch(
+                "stored projection failure has no partition state".into(),
+            )
+        })?;
+    if failure.change.epoch() != &partition.change_epoch
+        || failure.change.position() > partition.change_head
+    {
+        return Err(ProjectionProtocolError::InvalidBatch(
+            "stored projection failure change lies outside its partition".into(),
+        ));
+    }
+    Ok(())
+}
+
+pub(super) fn read_projection_obligation_evidence_from_state(
+    protocol: &InMemoryProjectionProtocolState,
+    request: &crate::projection_protocol::ProjectionObligationEvidenceRequest,
+) -> Result<ProjectionObligationEvidence, ProjectionProtocolError> {
+    request.validate()?;
+    let failure = protocol
+        .failures
+        .values()
+        .filter(|failure| {
+            failure.causation_id == request.causation_id
+                && failure.input.topology() == request.scope.topology()
+                && failure.input.projection_partition() == request.scope.projection_partition()
+        })
+        .min_by_key(|failure| failure.change.position())
+        .cloned();
+    if let Some(failure) = failure {
+        validate_failure_from_state(protocol, request, &failure)?;
+        return Ok(ProjectionObligationEvidence::TerminalFailure(failure));
+    }
+
+    let observation = protocol
+        .observations
+        .get(&ObservationKey {
+            causation_id: request.causation_id.clone(),
+            scope: request.scope.clone(),
+            kind: request.kind,
+        })
+        .cloned();
+    match observation {
+        Some(observation) => {
+            validate_observation_from_state(protocol, request, &observation)?;
+            Ok(ProjectionObligationEvidence::Observed(observation))
+        }
+        None => Ok(ProjectionObligationEvidence::Pending),
+    }
+}
+
+#[allow(dead_code)]
+pub(super) fn read_projection_live_record_from_state(
+    protocol: &InMemoryProjectionProtocolState,
+    request: &crate::projection_protocol::ProjectionLiveRecordRequest,
+) -> Result<Option<ProjectionRecordMetadata>, ProjectionProtocolError> {
+    request.validate()?;
+    let registered_key = RegisteredModelKey {
+        topology: request.topology.clone(),
+        model: request.model().to_string(),
+    };
+    if protocol
+        .registered_models
+        .get(&registered_key)
+        .map(String::as_str)
+        != Some(request.schema.table_name.as_str())
+        || protocol
+            .authoritative_table_owners
+            .get(&request.schema.table_name)
+            != Some(&registered_key)
+    {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "projection live-record model `{}` is not the registered owner of table `{}`",
+            request.model(),
+            request.schema.table_name
+        )));
+    }
+
+    let mut live = None;
+    for (scope, metadata) in &protocol.records {
+        if metadata.tombstone
+            || scope.topology() != &request.topology
+            || scope.model() != request.model()
+            || scope.key_digest() != request.canonical_key_hash
+        {
+            continue;
+        }
+        if scope.canonical_key_bytes() != request.canonical_key_bytes {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection live-record canonical key mismatch for model `{}`",
+                request.model()
+            )));
+        }
+        if metadata.revision.scope() != scope {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "projection live-record metadata is stored under a different scope".into(),
+            ));
+        }
+        if live.replace(metadata.clone()).is_some() {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection live-record identity for model `{}` is ambiguous across partitions",
+                request.model()
+            )));
+        }
+    }
+
+    if let Some(metadata) = &live {
+        let scope = metadata.revision.scope();
+        let partition = protocol
+            .partitions
+            .get(&PartitionKey::new(
+                scope.topology(),
+                scope.projection_partition(),
+            ))
+            .ok_or_else(|| {
+                ProjectionProtocolError::InvalidBatch(
+                    "projection live record has no partition state".into(),
+                )
+            })?;
+        if metadata.change.topology() != scope.topology()
+            || metadata.change.projection_partition() != scope.projection_partition()
+            || metadata.change.epoch() != &partition.change_epoch
+            || metadata.change.position() > partition.change_head
+        {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "projection live-record change lies outside its partition".into(),
+            ));
+        }
+    }
+    Ok(live)
+}
diff --git a/src/in_memory_repo/projection_protocol/state.rs b/src/in_memory_repo/projection_protocol/state.rs
new file mode 100644
index 00000000..2bf0f5cb
--- /dev/null
+++ b/src/in_memory_repo/projection_protocol/state.rs
@@ -0,0 +1,293 @@
+use super::*;
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub(super) struct PartitionKey {
+    pub(super) topology: ProjectorTopologyId,
+    pub(super) partition: ProjectionPartition,
+}
+
+impl PartitionKey {
+    pub(super) fn new(topology: &ProjectorTopologyId, partition: &ProjectionPartition) -> Self {
+        Self {
+            topology: topology.clone(),
+            partition: partition.clone(),
+        }
+    }
+
+    pub(super) fn from_input(input: &ProjectionInputCursor) -> Self {
+        Self::new(input.topology(), input.projection_partition())
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub(super) struct InputKey {
+    pub(super) partition: PartitionKey,
+    pub(super) source: ProjectionSource,
+    pub(super) generation: ProjectionGeneration,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub(super) struct SourceCapabilityKey {
+    pub(super) partition: PartitionKey,
+    pub(super) source: ProjectionSource,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub(super) struct CursorReceiptKey {
+    pub(super) partition: PartitionKey,
+    pub(super) source: ProjectionSource,
+    pub(super) source_epoch: ProjectionEpoch,
+    pub(super) source_position: u64,
+    pub(super) generation: ProjectionGeneration,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub(super) struct CursorIdentityKey {
+    pub(super) partition: PartitionKey,
+    pub(super) source: ProjectionSource,
+    pub(super) source_epoch: ProjectionEpoch,
+    pub(super) source_position: u64,
+}
+
+impl CursorReceiptKey {
+    pub(super) fn new(cursor: &ProjectionInputCursor, generation: ProjectionGeneration) -> Self {
+        Self {
+            partition: PartitionKey::from_input(cursor),
+            source: cursor.source().clone(),
+            source_epoch: cursor.epoch().clone(),
+            source_position: cursor.position(),
+            generation,
+        }
+    }
+}
+
+impl CursorIdentityKey {
+    pub(super) fn new(cursor: &ProjectionInputCursor) -> Self {
+        Self {
+            partition: PartitionKey::from_input(cursor),
+            source: cursor.source().clone(),
+            source_epoch: cursor.epoch().clone(),
+            source_position: cursor.position(),
+        }
+    }
+}
+
+impl SourceCapabilityKey {
+    pub(super) fn new(cursor: &ProjectionInputCursor) -> Self {
+        Self {
+            partition: PartitionKey::from_input(cursor),
+            source: cursor.source().clone(),
+        }
+    }
+}
+
+impl InputKey {
+    pub(super) fn new(cursor: &ProjectionInputCursor, generation: ProjectionGeneration) -> Self {
+        Self {
+            partition: PartitionKey::from_input(cursor),
+            source: cursor.source().clone(),
+            generation,
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub(super) struct MessageKey {
+    pub(super) topology: ProjectorTopologyId,
+    pub(super) message_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub(super) struct GenerationKey {
+    pub(super) partition: PartitionKey,
+    pub(super) generation: ProjectionGeneration,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub(super) struct OwnershipKey {
+    pub(super) partition: PartitionKey,
+    pub(super) model: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub(super) struct RegisteredModelKey {
+    pub(super) topology: ProjectorTopologyId,
+    pub(super) model: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub(super) struct ObservationKey {
+    pub(super) causation_id: String,
+    pub(super) scope: ProjectionRecordScope,
+    pub(super) kind: ProjectionObservationKind,
+}
+
+#[derive(Clone)]
+pub(super) struct StoredInput {
+    pub(super) cursor: ProjectionInputCursor,
+    pub(super) fingerprint: ProjectionInputFingerprint,
+    pub(super) message_id: String,
+    pub(super) causation_id: String,
+    pub(super) checkpoint: ProjectionCheckpoint,
+    pub(super) gap_free: bool,
+}
+
+#[derive(Clone)]
+pub(super) struct MessageIdentity {
+    pub(super) cursor: ProjectionInputCursor,
+    pub(super) fingerprint: ProjectionInputFingerprint,
+    pub(super) causation_id: String,
+    pub(super) gap_free: bool,
+}
+
+#[derive(Clone)]
+pub(super) struct InputIdentity {
+    pub(super) fingerprint: ProjectionInputFingerprint,
+    pub(super) message_id: String,
+    pub(super) causation_id: String,
+    pub(super) gap_free: bool,
+}
+
+#[derive(Clone)]
+pub(super) struct AppliedInputReceipt {
+    pub(super) fingerprint: ProjectionInputFingerprint,
+    pub(super) message_id: String,
+    pub(super) causation_id: String,
+    pub(super) gap_free: bool,
+    pub(super) checkpoint: ProjectionCheckpoint,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(super) struct GenerationLineage {
+    pub(super) retry_of_generation: Option<ProjectionGeneration>,
+    pub(super) retry_of_failure_id: Option<String>,
+}
+
+impl GenerationLineage {
+    pub(super) fn initial() -> Self {
+        Self {
+            retry_of_generation: None,
+            retry_of_failure_id: None,
+        }
+    }
+
+    pub(super) fn retry_of(generation: ProjectionGeneration, failure_id: String) -> Self {
+        Self {
+            retry_of_generation: Some(generation),
+            retry_of_failure_id: Some(failure_id),
+        }
+    }
+}
+
+#[derive(Clone)]
+pub(super) struct FailedInputFence {
+    pub(super) cursor: ProjectionInputCursor,
+    pub(super) fingerprint: ProjectionInputFingerprint,
+    pub(super) message_id: String,
+    pub(super) causation_id: String,
+    pub(super) generation: ProjectionGeneration,
+    pub(super) gap_free: bool,
+}
+
+impl FailedInputFence {
+    pub(super) fn from_input(input: &TrustedProjectionInput) -> Self {
+        Self {
+            cursor: input.cursor.clone(),
+            fingerprint: input.fingerprint,
+            message_id: input.message_id.clone(),
+            causation_id: input.causation_id.clone(),
+            generation: input.generation,
+            gap_free: input.gap_free,
+        }
+    }
+
+    pub(super) fn matches_retry(&self, input: &TrustedProjectionInput) -> bool {
+        self.cursor == input.cursor
+            && self.fingerprint == input.fingerprint
+            && self.message_id == input.message_id
+            && self.causation_id == input.causation_id
+            && self.gap_free == input.gap_free
+    }
+}
+
+#[derive(Clone)]
+pub(super) struct PartitionState {
+    pub(super) active_generation: ProjectionGeneration,
+    pub(super) change_epoch: ProjectionEpoch,
+    pub(super) change_head: u64,
+    pub(super) compacted_through: u64,
+    pub(super) stopped_failure_id: Option<String>,
+    pub(super) pending_retry_failure_id: Option<String>,
+    pub(super) changes: BTreeMap<u64, ProjectionChange>,
+}
+
+pub(super) struct PendingChange {
+    pub(super) kind: ProjectionChangeKind,
+    pub(super) causation_id: String,
+    pub(super) observation_kind: Option<ProjectionObservationKind>,
+    pub(super) scope: Option<ProjectionRecordScope>,
+    pub(super) revision: Option<RecordRevision>,
+    pub(super) failure_id: Option<String>,
+}
+
+impl PartitionState {
+    pub(super) fn new(change_epoch: ProjectionEpoch) -> Self {
+        Self {
+            active_generation: ProjectionGeneration::initial(),
+            change_epoch,
+            change_head: 0,
+            compacted_through: 0,
+            stopped_failure_id: None,
+            pending_retry_failure_id: None,
+            changes: BTreeMap::new(),
+        }
+    }
+}
+
+/// Dev-only in-memory representation of the durable projection protocol.
+///
+/// The state is cloned before every transaction. This intentionally favors
+/// simple, auditable atomicity over throughput: the production SQL adapters use
+/// database transactions, while this adapter is primarily for tests and local
+/// development.
+#[derive(Clone, Default)]
+pub(in crate::in_memory_repo) struct InMemoryProjectionProtocolState {
+    pub(super) partitions: HashMap<PartitionKey, PartitionState>,
+    pub(super) generations: HashMap<GenerationKey, GenerationLineage>,
+    pub(super) inputs: HashMap<InputKey, StoredInput>,
+    pub(super) input_identities: HashMap<CursorIdentityKey, InputIdentity>,
+    pub(super) messages: HashMap<MessageKey, MessageIdentity>,
+    pub(super) applied_receipts: HashMap<CursorReceiptKey, AppliedInputReceipt>,
+    pub(super) registered_topologies: HashSet<ProjectorTopologyId>,
+    pub(super) registered_models: HashMap<RegisteredModelKey, String>,
+    pub(super) authoritative_table_owners: HashMap<String, RegisteredModelKey>,
+    pub(super) ownership: HashMap<OwnershipKey, String>,
+    pub(super) gap_free_capabilities: HashMap<SourceCapabilityKey, bool>,
+    pub(super) records: HashMap<ProjectionRecordScope, ProjectionRecordMetadata>,
+    pub(super) observations: HashMap<ObservationKey, ProjectionObservation>,
+    pub(super) failures: HashMap<String, ProjectionFailure>,
+    pub(super) failure_inputs: HashMap<String, FailedInputFence>,
+}
+
+pub(in crate::in_memory_repo) fn reject_causal_owned_plans(
+    causal_tables: &HashSet<String>,
+    plans: &[TableWritePlan],
+) -> Result<(), TableStoreError> {
+    if let Some(table) = plans
+        .iter()
+        .flat_map(|plan| &plan.mutations)
+        .map(TableMutation::table_name)
+        .find(|table| causal_tables.contains(*table))
+    {
+        return Err(TableStoreError::CausalWriteRequired {
+            table: table.to_string(),
+        });
+    }
+    Ok(())
+}
+
+pub(super) enum InputDisposition {
+    New,
+    Duplicate(ProjectionCheckpoint),
+    Stale(ProjectionCheckpoint),
+}
diff --git a/src/in_memory_repo/projection_protocol/state_impl.rs b/src/in_memory_repo/projection_protocol/state_impl.rs
new file mode 100644
index 00000000..3161b9be
--- /dev/null
+++ b/src/in_memory_repo/projection_protocol/state_impl.rs
@@ -0,0 +1,748 @@
+use super::*;
+
+impl InMemoryProjectionProtocolState {
+    pub(super) fn ensure_live_record_identity_available(
+        &self,
+        metadata: &ProjectionRecordMetadata,
+    ) -> Result<(), ProjectionProtocolError> {
+        if metadata.tombstone {
+            return Ok(());
+        }
+        let candidate = metadata.revision.scope();
+        for (scope, stored) in &self.records {
+            if stored.tombstone
+                || scope == candidate
+                || scope.topology() != candidate.topology()
+                || scope.model() != candidate.model()
+                || scope.key_digest() != candidate.key_digest()
+            {
+                continue;
+            }
+            if scope.canonical_key_bytes() != candidate.canonical_key_bytes() {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection live-record key digest collision for model `{}`",
+                    candidate.model()
+                )));
+            }
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection live record for model `{}` is already owned by another partition",
+                candidate.model()
+            )));
+        }
+        Ok(())
+    }
+
+    pub(super) fn require_registered_topology(
+        &self,
+        topology: &ProjectorTopologyId,
+    ) -> Result<(), ProjectionProtocolError> {
+        if self.registered_topologies.contains(topology) {
+            Ok(())
+        } else {
+            Err(ProjectionProtocolError::InvalidBatch(
+                "projector topology was not bootstrapped before projector traffic".into(),
+            ))
+        }
+    }
+
+    pub(super) fn ensure_partition(
+        &mut self,
+        key: &PartitionKey,
+        change_epoch: &ProjectionEpoch,
+    ) -> Result<(), ProjectionProtocolError> {
+        match self.partitions.get(key) {
+            Some(partition) if &partition.change_epoch != change_epoch => {
+                return Err(ProjectionProtocolError::ScopeMismatch {
+                    field: "projection change epoch",
+                });
+            }
+            Some(_) => {}
+            None => {
+                self.partitions
+                    .insert(key.clone(), PartitionState::new(change_epoch.clone()));
+                self.generations.insert(
+                    GenerationKey {
+                        partition: key.clone(),
+                        generation: ProjectionGeneration::initial(),
+                    },
+                    GenerationLineage::initial(),
+                );
+            }
+        }
+        Ok(())
+    }
+
+    pub(super) fn validate_partition(
+        &self,
+        key: &PartitionKey,
+        input: &TrustedProjectionInput,
+        change_epoch: &ProjectionEpoch,
+    ) -> Result<(), ProjectionProtocolError> {
+        self.require_registered_topology(input.cursor.topology())?;
+        self.validate_known_input_identity(input)?;
+        let Some(partition) = self.partitions.get(key) else {
+            if input.generation != ProjectionGeneration::initial() {
+                return Err(ProjectionProtocolError::GenerationFenced {
+                    expected: ProjectionGeneration::initial().get(),
+                    actual: input.generation.get(),
+                });
+            }
+            self.validate_gap_free(&input.cursor, input.gap_free)?;
+            self.validate_input_identity(input)?;
+            return Ok(());
+        };
+        if &partition.change_epoch != change_epoch {
+            return Err(ProjectionProtocolError::ScopeMismatch {
+                field: "projection change epoch",
+            });
+        }
+        if input.generation != partition.active_generation {
+            return Err(ProjectionProtocolError::GenerationFenced {
+                expected: partition.active_generation.get(),
+                actual: input.generation.get(),
+            });
+        }
+        if !self.generations.contains_key(&GenerationKey {
+            partition: key.clone(),
+            generation: input.generation,
+        }) {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "active projection generation {} has no durable lineage",
+                input.generation.get()
+            )));
+        }
+        self.validate_gap_free(&input.cursor, input.gap_free)?;
+        self.validate_input_identity(input)?;
+        if let Some(failure_id) = &partition.stopped_failure_id {
+            return Err(ProjectionProtocolError::PartitionStopped {
+                failure_id: failure_id.clone(),
+            });
+        }
+        Ok(())
+    }
+
+    pub(super) fn validate_known_input_identity(
+        &self,
+        input: &TrustedProjectionInput,
+    ) -> Result<(), ProjectionProtocolError> {
+        let cursor_known = self
+            .input_identities
+            .contains_key(&CursorIdentityKey::new(&input.cursor));
+        let message_known = self.messages.contains_key(&MessageKey {
+            topology: input.cursor.topology().clone(),
+            message_id: input.message_id.clone(),
+        });
+        let source_capability_known = self
+            .gap_free_capabilities
+            .contains_key(&SourceCapabilityKey::new(&input.cursor));
+        if cursor_known || message_known || source_capability_known {
+            // Exact cursor corruption wins over message reuse; both are durable
+            // generation-independent identities. The source's fixed gap-free
+            // capability has the same precedence. An entirely unknown
+            // old-generation input is still rejected as GenerationFenced below.
+            self.validate_input_identity(input)?;
+            self.validate_gap_free(&input.cursor, input.gap_free)?;
+        }
+        Ok(())
+    }
+
+    pub(super) fn validate_pending_retry(
+        &self,
+        key: &PartitionKey,
+        input: &TrustedProjectionInput,
+    ) -> Result<(), ProjectionProtocolError> {
+        let Some(partition) = self.partitions.get(key) else {
+            return Ok(());
+        };
+        if let Some(failure_id) = &partition.pending_retry_failure_id {
+            let Some(fence) = self.failure_inputs.get(failure_id) else {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "pending projection retry `{failure_id}` has no exact input fence"
+                )));
+            };
+            if fence.cursor != input.cursor {
+                return Err(ProjectionProtocolError::IncomparableInput);
+            }
+            if !fence.matches_retry(input) {
+                return Err(ProjectionProtocolError::InputCorruption);
+            }
+        }
+        Ok(())
+    }
+
+    pub(super) fn validate_input_identity(
+        &self,
+        input: &TrustedProjectionInput,
+    ) -> Result<(), ProjectionProtocolError> {
+        if self
+            .input_identities
+            .get(&CursorIdentityKey::new(&input.cursor))
+            .is_some_and(|identity| {
+                identity.fingerprint != input.fingerprint
+                    || identity.message_id != input.message_id
+                    || identity.causation_id != input.causation_id
+                    || identity.gap_free != input.gap_free
+            })
+        {
+            return Err(ProjectionProtocolError::InputCorruption);
+        }
+        self.reject_reused_message(
+            &input.cursor,
+            input.fingerprint,
+            &input.message_id,
+            &input.causation_id,
+            input.gap_free,
+        )
+    }
+
+    pub(super) fn persist_input_identity(&mut self, input: &TrustedProjectionInput) {
+        self.input_identities
+            .entry(CursorIdentityKey::new(&input.cursor))
+            .or_insert_with(|| InputIdentity {
+                fingerprint: input.fingerprint,
+                message_id: input.message_id.clone(),
+                causation_id: input.causation_id.clone(),
+                gap_free: input.gap_free,
+            });
+        self.messages
+            .entry(MessageKey {
+                topology: input.cursor.topology().clone(),
+                message_id: input.message_id.clone(),
+            })
+            .or_insert_with(|| MessageIdentity {
+                cursor: input.cursor.clone(),
+                fingerprint: input.fingerprint,
+                causation_id: input.causation_id.clone(),
+                gap_free: input.gap_free,
+            });
+    }
+
+    pub(super) fn classify_input(
+        &self,
+        cursor: &ProjectionInputCursor,
+        fingerprint: ProjectionInputFingerprint,
+        message_id: &str,
+        causation_id: &str,
+        generation: ProjectionGeneration,
+        gap_free: bool,
+    ) -> Result<InputDisposition, ProjectionProtocolError> {
+        self.validate_gap_free(cursor, gap_free)?;
+        let candidate = TrustedProjectionInput {
+            cursor: cursor.clone(),
+            fingerprint,
+            message_id: message_id.to_string(),
+            causation_id: causation_id.to_string(),
+            generation,
+            gap_free,
+        };
+        self.validate_input_identity(&candidate)?;
+        if let Some(receipt) = self
+            .applied_receipts
+            .get(&CursorReceiptKey::new(cursor, generation))
+        {
+            if receipt.fingerprint == fingerprint
+                && receipt.message_id == message_id
+                && receipt.causation_id == causation_id
+                && receipt.gap_free == gap_free
+            {
+                return Ok(InputDisposition::Duplicate(receipt.checkpoint.clone()));
+            }
+            return Err(ProjectionProtocolError::InputCorruption);
+        }
+        let input_key = InputKey::new(cursor, generation);
+        let Some(previous) = self.inputs.get(&input_key) else {
+            self.reject_reused_message(cursor, fingerprint, message_id, causation_id, gap_free)?;
+            return Ok(InputDisposition::New);
+        };
+
+        match cursor.compare_position(&previous.cursor) {
+            RevisionComparison::Equal
+                if fingerprint != previous.fingerprint
+                    || message_id != previous.message_id
+                    || causation_id != previous.causation_id
+                    || gap_free != previous.gap_free =>
+            {
+                Err(ProjectionProtocolError::InputCorruption)
+            }
+            RevisionComparison::Equal => {
+                Ok(InputDisposition::Duplicate(previous.checkpoint.clone()))
+            }
+            RevisionComparison::Older => {
+                self.reject_reused_message(
+                    cursor,
+                    fingerprint,
+                    message_id,
+                    causation_id,
+                    gap_free,
+                )?;
+                Ok(InputDisposition::Stale(previous.checkpoint.clone()))
+            }
+            RevisionComparison::Incomparable => Err(ProjectionProtocolError::IncomparableInput),
+            RevisionComparison::Newer => {
+                self.reject_reused_message(
+                    cursor,
+                    fingerprint,
+                    message_id,
+                    causation_id,
+                    gap_free,
+                )?;
+                if gap_free
+                    && cursor.position()
+                        != checked_next(previous.cursor.position(), "gap-free projection input")?
+                {
+                    return Err(ProjectionProtocolError::IncomparableInput);
+                }
+                Ok(InputDisposition::New)
+            }
+        }
+    }
+
+    pub(super) fn reject_reused_message(
+        &self,
+        cursor: &ProjectionInputCursor,
+        fingerprint: ProjectionInputFingerprint,
+        message_id: &str,
+        causation_id: &str,
+        gap_free: bool,
+    ) -> Result<(), ProjectionProtocolError> {
+        let key = MessageKey {
+            topology: cursor.topology().clone(),
+            message_id: message_id.to_string(),
+        };
+        if let Some(previous) = self.messages.get(&key) {
+            if previous.cursor != *cursor
+                || previous.fingerprint != fingerprint
+                || previous.causation_id != causation_id
+                || previous.gap_free != gap_free
+            {
+                return Err(ProjectionProtocolError::MessageIdReuse {
+                    message_id: message_id.to_string(),
+                });
+            }
+        }
+        Ok(())
+    }
+
+    pub(super) fn validate_gap_free(
+        &self,
+        cursor: &ProjectionInputCursor,
+        gap_free: bool,
+    ) -> Result<(), ProjectionProtocolError> {
+        if self
+            .gap_free_capabilities
+            .get(&SourceCapabilityKey::new(cursor))
+            .is_some_and(|registered| *registered != gap_free)
+        {
+            return Err(ProjectionProtocolError::InputCorruption);
+        }
+        Ok(())
+    }
+
+    pub(super) fn has_exact_message_identity(&self, input: &TrustedProjectionInput) -> bool {
+        self.messages
+            .get(&MessageKey {
+                topology: input.cursor.topology().clone(),
+                message_id: input.message_id.clone(),
+            })
+            .is_some_and(|identity| {
+                identity.cursor == input.cursor
+                    && identity.fingerprint == input.fingerprint
+                    && identity.causation_id == input.causation_id
+                    && identity.gap_free == input.gap_free
+            })
+    }
+
+    pub(super) fn register_ownership(
+        &mut self,
+        partition: &PartitionKey,
+        batch: &ProjectionCommitBatch,
+    ) -> Result<(), ProjectionProtocolError> {
+        for declaration in &batch.ownership {
+            let registered_key = RegisteredModelKey {
+                topology: partition.topology.clone(),
+                model: declaration.model.clone(),
+            };
+            match self.registered_models.get(&registered_key) {
+                Some(table) if table == &declaration.table => {}
+                Some(table) => {
+                    return Err(ProjectionProtocolError::InvalidBatch(format!(
+                        "projection model `{}` was bootstrapped for table `{table}`, not `{}`",
+                        declaration.model, declaration.table
+                    )));
+                }
+                None => {
+                    return Err(ProjectionProtocolError::InvalidBatch(format!(
+                        "projection model `{}` was not registered before projector traffic",
+                        declaration.model
+                    )));
+                }
+            }
+            if self.authoritative_table_owners.get(&declaration.table) != Some(&registered_key) {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection table `{}` does not have model `{}` in this topology as its global authoritative owner",
+                    declaration.table, declaration.model
+                )));
+            }
+        }
+
+        crate::projection_protocol::validate_ownership_batch(&batch.ownership)?;
+
+        for declaration in &batch.ownership {
+            let key = OwnershipKey {
+                partition: partition.clone(),
+                model: declaration.model.clone(),
+            };
+            if let Some(previous) = self.ownership.get(&key) {
+                if previous != &declaration.table {
+                    return Err(ProjectionProtocolError::InvalidBatch(format!(
+                        "projection model `{}` is already bound to table `{previous}`",
+                        declaration.model
+                    )));
+                }
+            }
+            if let Some((other, _)) = self.ownership.iter().find(|(other, table)| {
+                other.partition == *partition
+                    && *table == &declaration.table
+                    && other.model != declaration.model
+            }) {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection table `{}` is already bound to model `{}`",
+                    declaration.table, other.model
+                )));
+            }
+            self.ownership.insert(key, declaration.table.clone());
+        }
+
+        for mutation in &batch.mutations {
+            let table = self.owned_table(partition, &mutation.scope)?;
+            if table != mutation.mutation.table_name() {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection model `{}` owns table `{table}`, but its mutation targets `{}`",
+                    mutation.scope.model(),
+                    mutation.mutation.table_name()
+                )));
+            }
+            if table_model_name(&mutation.mutation) != mutation.scope.model() {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection record model `{}` does not match table schema model `{}`",
+                    mutation.scope.model(),
+                    table_model_name(&mutation.mutation)
+                )));
+            }
+        }
+        for observation in &batch.observations {
+            self.owned_table(partition, observation.scope())?;
+        }
+        Ok(())
+    }
+
+    pub(super) fn register_same_transaction_ownership(
+        &mut self,
+        partition: &PartitionKey,
+        batch: &SameTransactionProjectionBatch,
+    ) -> Result<(), ProjectionProtocolError> {
+        let declaration = batch
+            .ownership
+            .first()
+            .expect("direct projection batch validation requires one owner");
+        let registered_key = RegisteredModelKey {
+            topology: partition.topology.clone(),
+            model: declaration.model.clone(),
+        };
+        match self.registered_models.get(&registered_key) {
+            Some(table) if table == &declaration.table => {}
+            Some(table) => {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection model `{}` was bootstrapped for table `{table}`, not `{}`",
+                    declaration.model, declaration.table
+                )));
+            }
+            None => {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection model `{}` was not registered before direct projection traffic",
+                    declaration.model
+                )));
+            }
+        }
+        if self.authoritative_table_owners.get(&declaration.table) != Some(&registered_key) {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection table `{}` does not have model `{}` in this topology as its global authoritative owner",
+                declaration.table, declaration.model
+            )));
+        }
+
+        let ownership_key = OwnershipKey {
+            partition: partition.clone(),
+            model: declaration.model.clone(),
+        };
+        if let Some(previous) = self.ownership.get(&ownership_key) {
+            if previous != &declaration.table {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection model `{}` is already bound to table `{previous}`",
+                    declaration.model
+                )));
+            }
+        }
+        if let Some((other, _)) = self.ownership.iter().find(|(other, table)| {
+            other.partition == *partition
+                && *table == &declaration.table
+                && other.model != declaration.model
+        }) {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection table `{}` is already bound to model `{}`",
+                declaration.table, other.model
+            )));
+        }
+        self.ownership
+            .insert(ownership_key, declaration.table.clone());
+
+        let mutation = batch
+            .mutations
+            .first()
+            .expect("direct projection batch validation requires one mutation");
+        let table = self.owned_table(partition, &mutation.scope)?;
+        if table != mutation.mutation.table_name()
+            || table_model_name(&mutation.mutation) != mutation.scope.model()
+        {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "direct projection record model `{}` does not own staged table `{}`",
+                mutation.scope.model(),
+                mutation.mutation.table_name()
+            )));
+        }
+        Ok(())
+    }
+
+    pub(super) fn owned_table<'a>(
+        &'a self,
+        partition: &PartitionKey,
+        scope: &ProjectionRecordScope,
+    ) -> Result<&'a str, ProjectionProtocolError> {
+        self.ownership
+            .get(&OwnershipKey {
+                partition: partition.clone(),
+                model: scope.model().to_string(),
+            })
+            .map(String::as_str)
+            .ok_or_else(|| {
+                ProjectionProtocolError::InvalidBatch(format!(
+                    "projection model `{}` has no causal ownership declaration",
+                    scope.model()
+                ))
+            })
+    }
+
+    pub(super) fn next_record(
+        &self,
+        scope: &ProjectionRecordScope,
+        expectation: &ProjectionRecordExpectation,
+        kind: ProjectionMutationKind,
+    ) -> Result<(RecordRevision, bool), ProjectionProtocolError> {
+        let current = self.records.get(scope);
+        match (expectation, current, kind) {
+            (ProjectionRecordExpectation::Missing, None, ProjectionMutationKind::Upsert) => {
+                Ok((RecordRevision::new(scope.clone(), 1, 1)?, false))
+            }
+            (ProjectionRecordExpectation::Missing, Some(metadata), _) if metadata.tombstone => {
+                Err(ProjectionProtocolError::RecordTombstoned {
+                    model: scope.model().to_string(),
+                })
+            }
+            (ProjectionRecordExpectation::Missing, Some(_), _) => {
+                Err(ProjectionProtocolError::RecordAlreadyExists {
+                    model: scope.model().to_string(),
+                })
+            }
+            (ProjectionRecordExpectation::Exact(_), None, _) => {
+                Err(ProjectionProtocolError::RecordMissing {
+                    model: scope.model().to_string(),
+                })
+            }
+            (ProjectionRecordExpectation::Exact(expected), Some(metadata), _) => {
+                if expected != &metadata.revision {
+                    return Err(ProjectionProtocolError::RecordRevisionConflict {
+                        model: scope.model().to_string(),
+                        expected_incarnation: expected.incarnation(),
+                        expected_revision: expected.revision(),
+                        actual_incarnation: metadata.revision.incarnation(),
+                        actual_revision: metadata.revision.revision(),
+                    });
+                }
+                match kind {
+                    ProjectionMutationKind::Upsert if metadata.tombstone => {
+                        Err(ProjectionProtocolError::RecordTombstoned {
+                            model: scope.model().to_string(),
+                        })
+                    }
+                    ProjectionMutationKind::Upsert => Ok((
+                        RecordRevision::new(
+                            scope.clone(),
+                            metadata.revision.incarnation(),
+                            checked_next(metadata.revision.revision(), "record revision")?,
+                        )?,
+                        false,
+                    )),
+                    ProjectionMutationKind::Delete if metadata.tombstone => {
+                        Err(ProjectionProtocolError::RecordTombstoned {
+                            model: scope.model().to_string(),
+                        })
+                    }
+                    ProjectionMutationKind::Delete => Ok((
+                        RecordRevision::new(
+                            scope.clone(),
+                            metadata.revision.incarnation(),
+                            checked_next(metadata.revision.revision(), "record revision")?,
+                        )?,
+                        true,
+                    )),
+                    ProjectionMutationKind::Recreate if !metadata.tombstone => {
+                        Err(ProjectionProtocolError::RecreateRequiresTombstone {
+                            model: scope.model().to_string(),
+                        })
+                    }
+                    ProjectionMutationKind::Recreate => Ok((
+                        RecordRevision::new(
+                            scope.clone(),
+                            checked_next(metadata.revision.incarnation(), "record incarnation")?,
+                            1,
+                        )?,
+                        false,
+                    )),
+                }
+            }
+            (_, _, ProjectionMutationKind::Delete | ProjectionMutationKind::Recreate) => {
+                Err(ProjectionProtocolError::InvalidBatch(
+                    "delete/recreate requires an exact record expectation".into(),
+                ))
+            }
+        }
+    }
+
+    pub(super) fn validate_physical_record(
+        &self,
+        scope: &ProjectionRecordScope,
+        expectation: &ProjectionRecordExpectation,
+        kind: ProjectionMutationKind,
+        row_exists: bool,
+    ) -> Result<(), ProjectionProtocolError> {
+        let should_exist = match (expectation, kind) {
+            (ProjectionRecordExpectation::Missing, ProjectionMutationKind::Upsert) => false,
+            (ProjectionRecordExpectation::Exact(_), ProjectionMutationKind::Recreate) => false,
+            (
+                ProjectionRecordExpectation::Exact(_),
+                ProjectionMutationKind::Upsert | ProjectionMutationKind::Delete,
+            ) => true,
+            _ => {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "projection mutation has no valid physical-row expectation".into(),
+                ));
+            }
+        };
+        if row_exists == should_exist {
+            return Ok(());
+        }
+        let expected = if should_exist { "present" } else { "absent" };
+        let actual = if row_exists { "present" } else { "absent" };
+        Err(ProjectionProtocolError::InvalidBatch(format!(
+            "projection record `{}` metadata requires its physical row to be {expected}, but it is {actual}",
+            scope.model()
+        )))
+    }
+
+    pub(super) fn append_change(
+        &mut self,
+        partition_key: &PartitionKey,
+        pending: PendingChange,
+    ) -> Result<ProjectionChange, ProjectionProtocolError> {
+        let partition = self
+            .partitions
+            .get_mut(partition_key)
+            .expect("partition is initialized before appending changes");
+        let position = partition.change_head.checked_add(1).ok_or(
+            ProjectionProtocolError::PositionOverflow {
+                domain: "projection change",
+            },
+        )?;
+        let cursor = ProjectionChangeCursor::new(
+            partition_key.topology.clone(),
+            partition_key.partition.clone(),
+            partition.change_epoch.clone(),
+            position,
+        )?;
+        let change = ProjectionChange {
+            cursor,
+            kind: pending.kind,
+            causation_id: pending.causation_id,
+            observation_kind: pending.observation_kind,
+            scope: pending.scope,
+            revision: pending.revision,
+            failure_id: pending.failure_id,
+        };
+        partition.change_head = position;
+        partition.changes.insert(position, change.clone());
+        Ok(change)
+    }
+
+    pub(super) fn compact_changes_through(
+        &mut self,
+        partition_key: &PartitionKey,
+        through: u64,
+    ) -> Result<u64, ProjectionProtocolError> {
+        let partition = self.partitions.get_mut(partition_key).ok_or_else(|| {
+            ProjectionProtocolError::InvalidBatch(
+                "cannot compact an unknown projection partition".into(),
+            )
+        })?;
+        if through > partition.change_head {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "cannot compact beyond the projection change head".into(),
+            ));
+        }
+        if through <= partition.compacted_through {
+            return Ok(partition.compacted_through);
+        }
+        let expected_removed = through - partition.compacted_through;
+        let actual_removed = u64::try_from(
+            partition
+                .changes
+                .range((
+                    std::ops::Bound::Excluded(partition.compacted_through),
+                    std::ops::Bound::Included(through),
+                ))
+                .count(),
+        )
+        .map_err(|_| {
+            ProjectionProtocolError::InvalidBatch(
+                "projection change compaction count exceeds u64".into(),
+            )
+        })?;
+        if actual_removed != expected_removed {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection change compaction expected to remove {expected_removed} contiguous entries but found {actual_removed}"
+            )));
+        }
+        partition.changes.retain(|position, _| *position > through);
+        partition.compacted_through = through;
+        Ok(through)
+    }
+
+    pub(super) fn retain_change_suffix(
+        &mut self,
+        partition_key: &PartitionKey,
+        retention: ProjectionChangeRetention,
+    ) -> Result<u64, ProjectionProtocolError> {
+        let head = self
+            .partitions
+            .get(partition_key)
+            .ok_or_else(|| {
+                ProjectionProtocolError::InvalidBatch(
+                    "cannot retain changes for an unknown projection partition".into(),
+                )
+            })?
+            .change_head;
+        self.compact_changes_through(
+            partition_key,
+            head.saturating_sub(retention.max_retained_changes()),
+        )
+    }
+}
diff --git a/src/in_memory_repo/projection_protocol/store_impl.rs b/src/in_memory_repo/projection_protocol/store_impl.rs
new file mode 100644
index 00000000..da74b9c6
--- /dev/null
+++ b/src/in_memory_repo/projection_protocol/store_impl.rs
@@ -0,0 +1,1113 @@
+use super::*;
+
+impl ProjectionProtocolStore for InMemoryRepository {
+    fn register_projection_models<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        ownership: &'a [crate::projection_protocol::ProjectionModelOwnership],
+    ) -> impl Future<Output = Result<(), ProjectionProtocolError>> + Send + 'a {
+        async move {
+            if ownership.is_empty() {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "projection topology bootstrap requires at least one model/table owner".into(),
+                ));
+            }
+            crate::projection_protocol::validate_ownership_batch(ownership)?;
+            // Serialize bootstrap against raw row writers. Once this returns,
+            // every repository-level legacy path observes the causal marker
+            // before it can acquire the row map for mutation.
+            let rows = self
+                .model_store
+                .relational_rows
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("projection ownership row fence"))?;
+            let mut protocol = self
+                .projection_protocol
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("projection ownership write"))?;
+            let mut staged = protocol.clone();
+            staged.registered_topologies.insert(topology.clone());
+            for declaration in ownership {
+                let key = RegisteredModelKey {
+                    topology: topology.clone(),
+                    model: declaration.model.clone(),
+                };
+                if let Some(previous) = staged.authoritative_table_owners.get(&declaration.table) {
+                    if previous != &key {
+                        return Err(ProjectionProtocolError::InvalidBatch(format!(
+                            "projection table `{}` already has authoritative owner `{}` in another topology",
+                            declaration.table, previous.model
+                        )));
+                    }
+                } else if rows.keys().any(|storage_key| {
+                    storage_key_belongs_to_table(storage_key, &declaration.table)
+                }) {
+                    return Err(ProjectionProtocolError::InvalidBatch(format!(
+                        "projection table `{}` contains rows without causal metadata; rebuild or verified import is required before registration",
+                        declaration.table
+                    )));
+                }
+                if let Some(previous) = staged.registered_models.get(&key) {
+                    if previous != &declaration.table {
+                        return Err(ProjectionProtocolError::InvalidBatch(format!(
+                            "projection model `{}` is already registered for table `{previous}`",
+                            declaration.model
+                        )));
+                    }
+                }
+                if let Some((other, _)) = staged.registered_models.iter().find(|(other, table)| {
+                    other.topology == *topology
+                        && *table == &declaration.table
+                        && other.model != declaration.model
+                }) {
+                    return Err(ProjectionProtocolError::InvalidBatch(format!(
+                        "projection table `{}` is already registered for model `{}`",
+                        declaration.table, other.model
+                    )));
+                }
+                staged
+                    .registered_models
+                    .insert(key.clone(), declaration.table.clone());
+                staged
+                    .authoritative_table_owners
+                    .insert(declaration.table.clone(), key);
+            }
+            let mut causal_tables = self
+                .causal_tables
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("causal table marker write"))?;
+            *protocol = staged;
+            causal_tables.extend(
+                ownership
+                    .iter()
+                    .map(|declaration| declaration.table.clone()),
+            );
+            Ok(())
+        }
+    }
+
+    fn commit_projection(
+        &self,
+        batch: ProjectionCommitBatch,
+    ) -> impl Future<Output = Result<ProjectionCommitResult, ProjectionProtocolError>> + Send + '_
+    {
+        async move {
+            batch.validate()?;
+            let partition_key = PartitionKey::from_input(&batch.input.cursor);
+
+            // All projection commits use one lock order: rows, protocol, inbox.
+            // Protocol/inbox guards therefore drop before the row guard, so a
+            // reader can never observe a row before its revision metadata.
+            let mut rows = self
+                .model_store
+                .relational_rows
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("projection rows write"))?;
+            let mut protocol = self
+                .projection_protocol
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("projection protocol write"))?;
+            let mut inbox = self
+                .inbox_store
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("projection inbox write"))?;
+
+            protocol.validate_partition(&partition_key, &batch.input, &batch.change_epoch)?;
+            match protocol.classify_input(
+                &batch.input.cursor,
+                batch.input.fingerprint,
+                &batch.input.message_id,
+                &batch.input.causation_id,
+                batch.input.generation,
+                batch.input.gap_free,
+            )? {
+                InputDisposition::Duplicate(checkpoint) => {
+                    return Ok(ProjectionCommitResult::not_applied(
+                        ProjectionCommitOutcome::Duplicate,
+                        Some(checkpoint),
+                    ));
+                }
+                InputDisposition::Stale(checkpoint) => {
+                    return Ok(ProjectionCommitResult::not_applied(
+                        ProjectionCommitOutcome::StaleInput,
+                        Some(checkpoint),
+                    ));
+                }
+                InputDisposition::New => {
+                    protocol.validate_pending_retry(&partition_key, &batch.input)?;
+                }
+            }
+
+            let receipt = batch.input.inbox_receipt();
+            receipt.validate()?;
+            if inbox.contains(&(receipt.consumer.clone(), receipt.message_id.clone())) {
+                return Err(ProjectionProtocolError::MessageIdReuse {
+                    message_id: batch.input.message_id.clone(),
+                });
+            }
+
+            let mut staged_protocol = protocol.clone();
+            let mut staged_inbox = inbox.clone();
+            staged_protocol.ensure_partition(&partition_key, &batch.change_epoch)?;
+            staged_protocol
+                .gap_free_capabilities
+                .entry(SourceCapabilityKey::new(&batch.input.cursor))
+                .or_insert(batch.input.gap_free);
+            staged_protocol.register_ownership(&partition_key, &batch)?;
+
+            let mut touched_rows = HashSet::with_capacity(batch.mutations.len());
+            for mutation in &batch.mutations {
+                let lock_key = mutation.mutation.lock_key();
+                if !touched_rows.insert(lock_key.clone()) {
+                    return Err(ProjectionProtocolError::InvalidBatch(format!(
+                        "projection batch repeats table row `{lock_key}`"
+                    )));
+                }
+            }
+            let mut staged_rows = HashMap::with_capacity(touched_rows.len());
+            for key in &touched_rows {
+                if let Some(row) = rows.get(key) {
+                    staged_rows.insert(key.clone(), row.clone());
+                }
+            }
+
+            let mut records = Vec::with_capacity(batch.mutations.len());
+            let mut changes =
+                Vec::with_capacity(batch.mutations.len() + batch.observations.len().max(1));
+            for mutation in &batch.mutations {
+                let (revision, tombstone) = staged_protocol.next_record(
+                    &mutation.scope,
+                    &mutation.expectation,
+                    mutation.kind,
+                )?;
+                staged_protocol.validate_physical_record(
+                    &mutation.scope,
+                    &mutation.expectation,
+                    mutation.kind,
+                    staged_rows.contains_key(&mutation.mutation.lock_key()),
+                )?;
+                let change = staged_protocol.append_change(
+                    &partition_key,
+                    PendingChange {
+                        kind: change_kind_for_mutation(mutation.kind),
+                        causation_id: batch.input.causation_id.clone(),
+                        observation_kind: None,
+                        scope: Some(mutation.scope.clone()),
+                        revision: Some(revision.clone()),
+                        failure_id: None,
+                    },
+                )?;
+                let metadata = ProjectionRecordMetadata {
+                    revision,
+                    tombstone,
+                    change: change.cursor.clone(),
+                };
+                staged_protocol.ensure_live_record_identity_available(&metadata)?;
+                staged_protocol
+                    .records
+                    .insert(mutation.scope.clone(), metadata.clone());
+                records.push(metadata);
+                changes.push(change);
+            }
+
+            apply_read_model_write_plan(
+                TableWritePlan::new(
+                    batch
+                        .mutations
+                        .iter()
+                        .map(|mutation| mutation.mutation.clone())
+                        .collect(),
+                ),
+                &mut staged_rows,
+            )?;
+            for mutation in &batch.mutations {
+                let row_exists = staged_rows.contains_key(&mutation.mutation.lock_key());
+                let should_exist = !matches!(mutation.kind, ProjectionMutationKind::Delete);
+                if row_exists != should_exist {
+                    return Err(ProjectionProtocolError::InvalidBatch(format!(
+                        "projection table mutation left model `{}` physical row {}",
+                        mutation.scope.model(),
+                        if row_exists {
+                            "present when deletion required absence"
+                        } else {
+                            "absent when persistence required presence"
+                        }
+                    )));
+                }
+            }
+
+            for request in &batch.observations {
+                let (scope, revision, staged_change) = match &request.target {
+                    ProjectionObservationTarget::StagedRecord(scope) => {
+                        let metadata = staged_protocol
+                            .records
+                            .get(scope)
+                            .expect("batch validation requires a staged record");
+                        (
+                            scope.clone(),
+                            Some(metadata.revision.clone()),
+                            Some(metadata.change.clone()),
+                        )
+                    }
+                    ProjectionObservationTarget::ExistingRecord(expected) => {
+                        let Some(metadata) = staged_protocol.records.get(expected.scope()) else {
+                            return Err(ProjectionProtocolError::RecordMissing {
+                                model: expected.scope().model().to_string(),
+                            });
+                        };
+                        if &metadata.revision != expected {
+                            return Err(ProjectionProtocolError::RecordRevisionConflict {
+                                model: expected.scope().model().to_string(),
+                                expected_incarnation: expected.incarnation(),
+                                expected_revision: expected.revision(),
+                                actual_incarnation: metadata.revision.incarnation(),
+                                actual_revision: metadata.revision.revision(),
+                            });
+                        }
+                        (expected.scope().clone(), Some(expected.clone()), None)
+                    }
+                    ProjectionObservationTarget::Dependency(scope) => (scope.clone(), None, None),
+                };
+                let observation_key = ObservationKey {
+                    causation_id: batch.input.causation_id.clone(),
+                    scope: scope.clone(),
+                    kind: request.kind,
+                };
+                if staged_protocol.observations.contains_key(&observation_key) {
+                    continue;
+                }
+                let change_cursor = match staged_change {
+                    Some(cursor) => cursor,
+                    None => {
+                        let change = staged_protocol.append_change(
+                            &partition_key,
+                            PendingChange {
+                                kind: ProjectionChangeKind::Observation,
+                                causation_id: batch.input.causation_id.clone(),
+                                observation_kind: Some(request.kind),
+                                scope: Some(scope.clone()),
+                                revision: revision.clone(),
+                                failure_id: None,
+                            },
+                        )?;
+                        let cursor = change.cursor.clone();
+                        changes.push(change);
+                        cursor
+                    }
+                };
+                let observation = ProjectionObservation {
+                    causation_id: batch.input.causation_id.clone(),
+                    kind: request.kind,
+                    revision,
+                    scope,
+                    change: change_cursor,
+                };
+                staged_protocol
+                    .observations
+                    .insert(observation_key, observation);
+            }
+
+            if changes.is_empty() {
+                changes.push(staged_protocol.append_change(
+                    &partition_key,
+                    PendingChange {
+                        kind: ProjectionChangeKind::Checkpoint,
+                        causation_id: batch.input.causation_id.clone(),
+                        observation_kind: None,
+                        scope: None,
+                        revision: None,
+                        failure_id: None,
+                    },
+                )?);
+            }
+            let checkpoint = ProjectionCheckpoint::new(
+                batch.input.cursor.clone(),
+                changes
+                    .last()
+                    .expect("every successful projection input emits a change")
+                    .cursor
+                    .clone(),
+                batch.input.gap_free,
+            )?;
+            let input_key = InputKey::new(&batch.input.cursor, batch.input.generation);
+            staged_protocol.inputs.insert(
+                input_key,
+                StoredInput {
+                    cursor: batch.input.cursor.clone(),
+                    fingerprint: batch.input.fingerprint,
+                    message_id: batch.input.message_id.clone(),
+                    causation_id: batch.input.causation_id.clone(),
+                    checkpoint: checkpoint.clone(),
+                    gap_free: batch.input.gap_free,
+                },
+            );
+            staged_protocol.persist_input_identity(&batch.input);
+            staged_protocol.applied_receipts.insert(
+                CursorReceiptKey::new(&batch.input.cursor, batch.input.generation),
+                AppliedInputReceipt {
+                    fingerprint: batch.input.fingerprint,
+                    message_id: batch.input.message_id.clone(),
+                    causation_id: batch.input.causation_id.clone(),
+                    gap_free: batch.input.gap_free,
+                    checkpoint: checkpoint.clone(),
+                },
+            );
+            staged_protocol
+                .partitions
+                .get_mut(&partition_key)
+                .expect("successful projection partition is initialized")
+                .pending_retry_failure_id = None;
+            staged_protocol
+                .retain_change_suffix(&partition_key, self.projection_change_retention)?;
+            staged_inbox.insert((receipt.consumer, receipt.message_id));
+
+            // No fallible operations below this point. Merge only touched rows,
+            // then publish the staged protocol/inbox maps while all guards remain
+            // held. The row write guard is declared first and releases last.
+            for key in touched_rows {
+                match staged_rows.remove(&key) {
+                    Some(row) => {
+                        rows.insert(key, row);
+                    }
+                    None => {
+                        rows.remove(&key);
+                    }
+                }
+            }
+            *protocol = staged_protocol;
+            *inbox = staged_inbox;
+
+            Ok(ProjectionCommitResult {
+                outcome: ProjectionCommitOutcome::Applied,
+                checkpoint: Some(checkpoint),
+                records,
+                changes,
+            })
+        }
+    }
+
+    fn record_projection_failure(
+        &self,
+        batch: ProjectionFailureBatch,
+    ) -> impl Future<Output = Result<ProjectionFailure, ProjectionProtocolError>> + Send + '_ {
+        async move {
+            batch.validate()?;
+            let partition_key = PartitionKey::from_input(&batch.input.cursor);
+
+            // Keep the same global lock order as successful commits even though
+            // failures intentionally do not touch rows.
+            let _rows = self
+                .model_store
+                .relational_rows
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("projection rows failure fence"))?;
+            let mut protocol = self
+                .projection_protocol
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("projection failure write"))?;
+            let mut inbox = self
+                .inbox_store
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("projection failure inbox write"))?;
+
+            protocol.require_registered_topology(batch.input.cursor.topology())?;
+            protocol.validate_known_input_identity(&batch.input)?;
+            if let Some(partition) = protocol.partitions.get(&partition_key) {
+                if batch.input.generation != partition.active_generation {
+                    return Err(ProjectionProtocolError::GenerationFenced {
+                        expected: partition.active_generation.get(),
+                        actual: batch.input.generation.get(),
+                    });
+                }
+                protocol.validate_gap_free(&batch.input.cursor, batch.input.gap_free)?;
+                protocol.validate_input_identity(&batch.input)?;
+                if let Some(stopped_failure_id) = &partition.stopped_failure_id {
+                    if stopped_failure_id == &batch.failure_id {
+                        if let Some(existing) = protocol.failures.get(stopped_failure_id) {
+                            if failure_matches_batch(existing, &batch)
+                                && protocol.failure_inputs.get(stopped_failure_id).is_some_and(
+                                    |fence| {
+                                        fence.generation == batch.input.generation
+                                            && fence.matches_retry(&batch.input)
+                                    },
+                                )
+                                && protocol.has_exact_message_identity(&batch.input)
+                            {
+                                return Ok(existing.clone());
+                            }
+                        }
+                    }
+                    return Err(ProjectionProtocolError::PartitionStopped {
+                        failure_id: stopped_failure_id.clone(),
+                    });
+                }
+            }
+            if protocol.failures.contains_key(&batch.failure_id) {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection failure ID `{}` is already bound to another failure",
+                    batch.failure_id
+                )));
+            }
+
+            protocol.validate_partition(&partition_key, &batch.input, &batch.change_epoch)?;
+            match protocol.classify_input(
+                &batch.input.cursor,
+                batch.input.fingerprint,
+                &batch.input.message_id,
+                &batch.input.causation_id,
+                batch.input.generation,
+                batch.input.gap_free,
+            )? {
+                InputDisposition::New => {
+                    protocol.validate_pending_retry(&partition_key, &batch.input)?;
+                }
+                InputDisposition::Duplicate(_) | InputDisposition::Stale(_) => {
+                    return Err(ProjectionProtocolError::InvalidBatch(
+                        "cannot record terminal failure for an already processed input".into(),
+                    ));
+                }
+            }
+
+            let receipt = batch.input.inbox_receipt();
+            receipt.validate()?;
+            if inbox.contains(&(receipt.consumer.clone(), receipt.message_id.clone())) {
+                return Err(ProjectionProtocolError::MessageIdReuse {
+                    message_id: batch.input.message_id.clone(),
+                });
+            }
+
+            let mut staged_protocol = protocol.clone();
+            let mut staged_inbox = inbox.clone();
+            staged_protocol.ensure_partition(&partition_key, &batch.change_epoch)?;
+            staged_protocol
+                .gap_free_capabilities
+                .entry(SourceCapabilityKey::new(&batch.input.cursor))
+                .or_insert(batch.input.gap_free);
+            let change = staged_protocol.append_change(
+                &partition_key,
+                PendingChange {
+                    kind: ProjectionChangeKind::Failure,
+                    causation_id: batch.input.causation_id.clone(),
+                    observation_kind: None,
+                    scope: None,
+                    revision: None,
+                    failure_id: Some(batch.failure_id.clone()),
+                },
+            )?;
+            let failure = ProjectionFailure {
+                failure_id: batch.failure_id.clone(),
+                input: batch.input.cursor.clone(),
+                input_fingerprint: batch.input.fingerprint,
+                message_id: batch.input.message_id.clone(),
+                causation_id: batch.input.causation_id.clone(),
+                generation: batch.input.generation,
+                gap_free: batch.input.gap_free,
+                failure_code: batch.failure_code,
+                failure_bytes: batch.failure_bytes,
+                failure_digest: batch.failure_digest,
+                change: change.cursor,
+            };
+            staged_protocol
+                .partitions
+                .get_mut(&partition_key)
+                .expect("failure partition was initialized")
+                .stopped_failure_id = Some(batch.failure_id.clone());
+            staged_protocol
+                .partitions
+                .get_mut(&partition_key)
+                .expect("failure partition was initialized")
+                .pending_retry_failure_id = None;
+            staged_protocol.persist_input_identity(&batch.input);
+            staged_protocol.failure_inputs.insert(
+                batch.failure_id.clone(),
+                FailedInputFence::from_input(&batch.input),
+            );
+            staged_protocol
+                .failures
+                .insert(batch.failure_id, failure.clone());
+            staged_protocol
+                .retain_change_suffix(&partition_key, self.projection_change_retention)?;
+            staged_inbox.insert((receipt.consumer, receipt.message_id));
+
+            *protocol = staged_protocol;
+            *inbox = staged_inbox;
+            Ok(failure)
+        }
+    }
+
+    fn projection_checkpoint<'a>(
+        &'a self,
+        cursor_scope: &'a ProjectionInputCursor,
+        generation: ProjectionGeneration,
+    ) -> impl Future<Output = Result<Option<ProjectionCheckpoint>, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            let protocol = self
+                .projection_protocol
+                .read()
+                .map_err(|_| RepositoryError::LockPoisoned("projection checkpoint read"))?;
+            let Some(input) = protocol
+                .inputs
+                .get(&InputKey::new(cursor_scope, generation))
+            else {
+                return Ok(None);
+            };
+            if matches!(
+                cursor_scope.compare_position(&input.cursor),
+                RevisionComparison::Incomparable
+            ) {
+                return Err(ProjectionProtocolError::IncomparableInput);
+            }
+            Ok(Some(input.checkpoint.clone()))
+        }
+    }
+
+    fn projection_record<'a>(
+        &'a self,
+        scope: &'a ProjectionRecordScope,
+    ) -> impl Future<Output = Result<Option<ProjectionRecordMetadata>, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        async move {
+            let protocol = self
+                .projection_protocol
+                .read()
+                .map_err(|_| RepositoryError::LockPoisoned("projection record read"))?;
+            Ok(protocol.records.get(scope).cloned())
+        }
+    }
+
+    fn projection_input_disposition<'a>(
+        &'a self,
+        input: &'a TrustedProjectionInput,
+    ) -> impl Future<Output = Result<ProjectionInputDisposition, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            let protocol = self
+                .projection_protocol
+                .read()
+                .map_err(|_| RepositoryError::LockPoisoned("projection input disposition read"))?;
+            protocol.require_registered_topology(input.cursor.topology())?;
+            protocol.validate_known_input_identity(input)?;
+            let partition_key = PartitionKey::from_input(&input.cursor);
+            let Some(partition) = protocol.partitions.get(&partition_key) else {
+                if input.generation != ProjectionGeneration::initial() {
+                    return Err(ProjectionProtocolError::GenerationFenced {
+                        expected: ProjectionGeneration::initial().get(),
+                        actual: input.generation.get(),
+                    });
+                }
+                protocol.validate_gap_free(&input.cursor, input.gap_free)?;
+                protocol.validate_input_identity(input)?;
+                return Ok(ProjectionInputDisposition::Pending);
+            };
+            if input.generation != partition.active_generation {
+                return Err(ProjectionProtocolError::GenerationFenced {
+                    expected: partition.active_generation.get(),
+                    actual: input.generation.get(),
+                });
+            }
+            if !protocol.generations.contains_key(&GenerationKey {
+                partition: partition_key.clone(),
+                generation: input.generation,
+            }) {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "active projection generation {} has no durable lineage",
+                    input.generation.get()
+                )));
+            }
+            protocol.validate_gap_free(&input.cursor, input.gap_free)?;
+            protocol.validate_input_identity(input)?;
+            if let Some(failure_id) = &partition.stopped_failure_id {
+                return Err(ProjectionProtocolError::PartitionStopped {
+                    failure_id: failure_id.clone(),
+                });
+            }
+            match protocol.classify_input(
+                &input.cursor,
+                input.fingerprint,
+                &input.message_id,
+                &input.causation_id,
+                input.generation,
+                input.gap_free,
+            )? {
+                InputDisposition::Duplicate(checkpoint) => {
+                    Ok(ProjectionInputDisposition::Duplicate(checkpoint))
+                }
+                InputDisposition::Stale(checkpoint) => {
+                    Ok(ProjectionInputDisposition::Stale(checkpoint))
+                }
+                InputDisposition::New => {
+                    protocol.validate_pending_retry(&partition_key, input)?;
+                    Ok(ProjectionInputDisposition::Pending)
+                }
+            }
+        }
+    }
+
+    fn projection_query_snapshot<'a>(
+        &'a self,
+        request: &'a ProjectionQuerySnapshotRequest,
+    ) -> impl Future<Output = Result<ProjectionQuerySnapshot, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            request.validate()?;
+
+            // Projection writers acquire rows before protocol. Holding both
+            // read guards in that same order prevents a writer from publishing
+            // either half of a row/revision/checkpoint snapshot independently.
+            let rows = self
+                .model_store
+                .relational_rows
+                .read()
+                .map_err(|_| RepositoryError::LockPoisoned("projection query rows read"))?;
+            let protocol = self
+                .projection_protocol
+                .read()
+                .map_err(|_| RepositoryError::LockPoisoned("projection query protocol read"))?;
+
+            read_projection_query_snapshot_from_state(&rows, &protocol, request)
+        }
+    }
+
+    fn projection_query_snapshot_batch<'a>(
+        &'a self,
+        request: &'a ProjectionQuerySnapshotBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionQuerySnapshotBatch, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            request.validate()?;
+            // Use the same writer lock order as the one-row primitive and hold
+            // both guards for the entire plan, not once per row.
+            let rows =
+                self.model_store.relational_rows.read().map_err(|_| {
+                    RepositoryError::LockPoisoned("projection query batch rows read")
+                })?;
+            let protocol = self.projection_protocol.read().map_err(|_| {
+                RepositoryError::LockPoisoned("projection query batch protocol read")
+            })?;
+            let snapshots = request
+                .requests
+                .iter()
+                .map(|row_request| {
+                    read_projection_query_snapshot_from_state(&rows, &protocol, row_request)
+                })
+                .collect::<Result<Vec<_>, _>>()?;
+            Ok(ProjectionQuerySnapshotBatch { snapshots })
+        }
+    }
+
+    fn projection_obligation_evidence_batch<'a>(
+        &'a self,
+        request: &'a ProjectionObligationEvidenceBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionObligationEvidenceBatch, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        async move {
+            request.validate()?;
+            let protocol = self.projection_protocol.read().map_err(|_| {
+                RepositoryError::LockPoisoned("projection obligation evidence read")
+            })?;
+            let evidence = request
+                .requests
+                .iter()
+                .map(|probe| read_projection_obligation_evidence_from_state(&protocol, probe))
+                .collect::<Result<Vec<_>, _>>()?;
+            Ok(ProjectionObligationEvidenceBatch { evidence })
+        }
+    }
+
+    fn projection_live_record_batch<'a>(
+        &'a self,
+        request: &'a ProjectionLiveRecordBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionLiveRecordBatch, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            request.validate()?;
+            let protocol = self
+                .projection_protocol
+                .read()
+                .map_err(|_| RepositoryError::LockPoisoned("projection live-record read"))?;
+            let records = request
+                .requests
+                .iter()
+                .map(|probe| read_projection_live_record_from_state(&protocol, probe))
+                .collect::<Result<Vec<_>, _>>()?;
+            Ok(ProjectionLiveRecordBatch { records })
+        }
+    }
+
+    fn projection_partition_runtime_state<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+    ) -> impl Future<Output = Result<Option<ProjectionPartitionRuntimeState>, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        async move {
+            let protocol = self.projection_protocol.read().map_err(|_| {
+                RepositoryError::LockPoisoned("projection partition runtime state read")
+            })?;
+            let Some(state) = protocol
+                .partitions
+                .get(&PartitionKey::new(topology, partition))
+            else {
+                return Ok(None);
+            };
+            let pending_retry = match &state.pending_retry_failure_id {
+                Some(failure_id) => {
+                    let failure = protocol.failures.get(failure_id).ok_or_else(|| {
+                        ProjectionProtocolError::InvalidBatch(format!(
+                            "pending projection retry failure `{failure_id}` is missing"
+                        ))
+                    })?;
+                    let fence = protocol.failure_inputs.get(failure_id).ok_or_else(|| {
+                        ProjectionProtocolError::InvalidBatch(format!(
+                            "pending projection retry failure `{failure_id}` has no input fence"
+                        ))
+                    })?;
+                    if state.stopped_failure_id.is_some()
+                        || failure.failure_id != *failure_id
+                        || failure.input.topology() != topology
+                        || failure.input.projection_partition() != partition
+                        || failure.generation.checked_next()? != state.active_generation
+                        || fence.cursor != failure.input
+                        || fence.fingerprint != failure.input_fingerprint
+                        || fence.message_id != failure.message_id
+                        || fence.causation_id != failure.causation_id
+                        || fence.generation != failure.generation
+                        || fence.gap_free != failure.gap_free
+                    {
+                        return Err(ProjectionProtocolError::InvalidBatch(format!(
+                            "pending projection retry failure `{failure_id}` is corrupt"
+                        )));
+                    }
+                    Some(ProjectionPendingRetry {
+                        failure_id: failure_id.clone(),
+                        input: failure.input.clone(),
+                        input_fingerprint: failure.input_fingerprint,
+                        message_id: failure.message_id.clone(),
+                        causation_id: failure.causation_id.clone(),
+                        failed_generation: failure.generation,
+                        gap_free: failure.gap_free,
+                    })
+                }
+                None => None,
+            };
+            Ok(Some(ProjectionPartitionRuntimeState {
+                active_generation: state.active_generation,
+                stopped_failure_id: state.stopped_failure_id.clone(),
+                pending_retry,
+            }))
+        }
+    }
+
+    fn projection_observation<'a>(
+        &'a self,
+        causation_id: &'a str,
+        scope: &'a ProjectionRecordScope,
+        kind: ProjectionObservationKind,
+    ) -> impl Future<Output = Result<Option<ProjectionObservation>, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            let protocol = self
+                .projection_protocol
+                .read()
+                .map_err(|_| RepositoryError::LockPoisoned("projection observation read"))?;
+            Ok(protocol
+                .observations
+                .get(&ObservationKey {
+                    causation_id: causation_id.to_string(),
+                    scope: scope.clone(),
+                    kind,
+                })
+                .cloned())
+        }
+    }
+
+    fn projection_changes<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        after: Option<&'a ProjectionChangeCursor>,
+        limit: usize,
+    ) -> impl Future<Output = Result<ProjectionChangeRead, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            let protocol = self
+                .projection_protocol
+                .read()
+                .map_err(|_| RepositoryError::LockPoisoned("projection changes read"))?;
+            let key = PartitionKey::new(topology, partition);
+            let Some(state) = protocol.partitions.get(&key) else {
+                return Ok(match after {
+                    Some(_) => ProjectionChangeRead::ResetRequired {
+                        head: None,
+                        compacted_through: 0,
+                    },
+                    None => ProjectionChangeRead::Changes {
+                        head: None,
+                        compacted_through: 0,
+                        changes: Vec::new(),
+                    },
+                });
+            };
+            let head = if state.change_head == 0 {
+                None
+            } else {
+                Some(ProjectionChangeCursor::new(
+                    topology.clone(),
+                    partition.clone(),
+                    state.change_epoch.clone(),
+                    state.change_head,
+                )?)
+            };
+            let after_position = match after {
+                None if state.compacted_through > 0 => {
+                    return Ok(ProjectionChangeRead::ResetRequired {
+                        head,
+                        compacted_through: state.compacted_through,
+                    });
+                }
+                None => 0,
+                Some(cursor)
+                    if cursor.topology() != topology
+                        || cursor.projection_partition() != partition
+                        || cursor.epoch() != &state.change_epoch
+                        || cursor.position() > state.change_head
+                        // `compacted_through` is the last removed change. An
+                        // exact cursor at that watermark is therefore the safe
+                        // boundary for resuming at the first retained change.
+                        || cursor.position() < state.compacted_through =>
+                {
+                    return Ok(ProjectionChangeRead::ResetRequired {
+                        head,
+                        compacted_through: state.compacted_through,
+                    });
+                }
+                Some(cursor) => cursor.position(),
+            };
+            let changes = if limit == 0 {
+                Vec::new()
+            } else {
+                state
+                    .changes
+                    .range((
+                        std::ops::Bound::Excluded(after_position),
+                        std::ops::Bound::Unbounded,
+                    ))
+                    .take(limit)
+                    .map(|(_, change)| change.clone())
+                    .collect()
+            };
+            Ok(ProjectionChangeRead::Changes {
+                head,
+                compacted_through: state.compacted_through,
+                changes,
+            })
+        }
+    }
+
+    fn repair_projection<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<ProjectionGeneration, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            let mut protocol = self
+                .projection_protocol
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("projection repair write"))?;
+            let key = PartitionKey::new(topology, partition);
+            let Some(state) = protocol.partitions.get(&key) else {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "cannot repair an unknown projection partition".into(),
+                ));
+            };
+            match &state.stopped_failure_id {
+                Some(stopped) if stopped == failure_id => {}
+                Some(stopped) => {
+                    return Err(ProjectionProtocolError::PartitionStopped {
+                        failure_id: stopped.clone(),
+                    });
+                }
+                None => {
+                    return Err(ProjectionProtocolError::InvalidBatch(
+                        "projection partition is not stopped".into(),
+                    ));
+                }
+            }
+            let Some(failure) = protocol.failures.get(failure_id) else {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "stopped projection failure `{failure_id}` is missing"
+                )));
+            };
+            if failure.input.topology() != topology
+                || failure.input.projection_partition() != partition
+            {
+                return Err(ProjectionProtocolError::ScopeMismatch {
+                    field: "projection repair failure",
+                });
+            }
+            if failure.generation != state.active_generation {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "stopped failure generation {} differs from active generation {}",
+                    failure.generation.get(),
+                    state.active_generation.get()
+                )));
+            }
+            let Some(failure_fence) = protocol.failure_inputs.get(failure_id) else {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "stopped projection failure `{failure_id}` has no exact input fence"
+                )));
+            };
+            if failure_fence.generation != state.active_generation
+                || failure_fence.cursor != failure.input
+                || failure_fence.fingerprint != failure.input_fingerprint
+                || failure_fence.message_id != failure.message_id
+                || failure_fence.causation_id != failure.causation_id
+            {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "stopped projection failure `{failure_id}` input fence is corrupt"
+                )));
+            }
+
+            let current_generation = state.active_generation;
+            let next_generation = current_generation.checked_next()?;
+            if protocol.generations.contains_key(&GenerationKey {
+                partition: key.clone(),
+                generation: next_generation,
+            }) {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection repair generation {} already exists",
+                    next_generation.get()
+                )));
+            }
+            if protocol
+                .generations
+                .iter()
+                .any(|(generation_key, lineage)| {
+                    generation_key.partition == key
+                        && lineage.retry_of_failure_id.as_deref() == Some(failure_id)
+                })
+            {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "stopped failure `{failure_id}` already has a repair generation"
+                )));
+            }
+            let copied_inputs = protocol
+                .inputs
+                .iter()
+                .filter(|(input_key, _)| {
+                    input_key.partition == key && input_key.generation == current_generation
+                })
+                .map(|(input_key, input)| {
+                    (
+                        InputKey {
+                            partition: input_key.partition.clone(),
+                            source: input_key.source.clone(),
+                            generation: next_generation,
+                        },
+                        input.clone(),
+                    )
+                })
+                .collect::<Vec<_>>();
+
+            let mut staged = protocol.clone();
+            for (input_key, input) in copied_inputs {
+                staged.inputs.insert(input_key, input);
+            }
+            staged.generations.insert(
+                GenerationKey {
+                    partition: key.clone(),
+                    generation: next_generation,
+                },
+                GenerationLineage::retry_of(current_generation, failure_id.to_string()),
+            );
+            let state = staged
+                .partitions
+                .get_mut(&key)
+                .expect("repair partition exists in staged state");
+            state.active_generation = next_generation;
+            state.stopped_failure_id = None;
+            state.pending_retry_failure_id = Some(failure_id.to_string());
+            *protocol = staged;
+            Ok(next_generation)
+        }
+    }
+
+    fn compact_projection_changes<'a>(
+        &'a self,
+        through: &'a ProjectionChangeCursor,
+    ) -> impl Future<Output = Result<u64, ProjectionProtocolError>> + Send + 'a {
+        async move {
+            let mut protocol = self
+                .projection_protocol
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("projection changes compaction"))?;
+            let key = PartitionKey::new(through.topology(), through.projection_partition());
+            let Some(partition) = protocol.partitions.get(&key) else {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "cannot compact an unknown projection partition".into(),
+                ));
+            };
+            if through.epoch() != &partition.change_epoch {
+                return Err(ProjectionProtocolError::ScopeMismatch {
+                    field: "projection compaction epoch",
+                });
+            }
+            if through.position() > partition.change_head {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "cannot compact beyond the projection change head".into(),
+                ));
+            }
+            protocol.compact_changes_through(&key, through.position())
+        }
+    }
+
+    fn projection_failure<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<Option<ProjectionFailure>, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            let protocol = self
+                .projection_protocol
+                .read()
+                .map_err(|_| RepositoryError::LockPoisoned("projection failure read"))?;
+            Ok(protocol
+                .failures
+                .get(failure_id)
+                .filter(|failure| {
+                    failure.input.topology() == topology
+                        && failure.input.projection_partition() == partition
+                })
+                .cloned())
+        }
+    }
+
+    fn projection_failure_location<'a>(
+        &'a self,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<Option<ProjectionFailureLocation>, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        async move {
+            let protocol = self
+                .projection_protocol
+                .read()
+                .map_err(|_| RepositoryError::LockPoisoned("projection failure location read"))?;
+            Ok(protocol
+                .failures
+                .get(failure_id)
+                .map(|failure| ProjectionFailureLocation {
+                    topology: failure.input.topology().clone(),
+                    partition: failure.input.projection_partition().clone(),
+                }))
+        }
+    }
+}
diff --git a/src/in_memory_repo/projection_protocol/tests.rs b/src/in_memory_repo/projection_protocol/tests.rs
new file mode 100644
index 00000000..ec4e0692
--- /dev/null
+++ b/src/in_memory_repo/projection_protocol/tests.rs
@@ -0,0 +1,2885 @@
+use std::sync::{Arc, Barrier, LazyLock};
+use std::time::Duration;
+
+use super::*;
+use crate::command_ledger::{
+    CanonicalInputHash, CausalCommitBatch, CausalTransactionalCommit, CommandContractFingerprint,
+    CommandId, CommandLedgerError, CommandLedgerKey, CommandLedgerStore, CommandReservation,
+    PrincipalPartitionId, ReservationOutcome, TerminalCommandState,
+};
+use crate::projection_protocol::{
+    ProjectionInputFingerprint, ProjectionModelOwnership, ProjectionObservationRequest,
+    ProjectionRecordMutation, ProjectionScopeCodec, TrustedProjectionInput,
+};
+use crate::repository::{CommitBatch, ReadModelWritePlanStore, TransactionalCommit};
+use crate::table::{
+    ColumnType, DeleteTableRowMutation, ExpectedVersion, PatchMode, PatchTableRowMutation,
+    PrimaryKey, RowKey, RowPatch, RowValue, RowValues, RowWriteMode, TableColumn, TableKind,
+    TableRowMutation, TableSchema,
+};
+
+fn topology() -> ProjectorTopologyId {
+    ProjectorTopologyId::new(1, "todo_projector", [7; 32]).unwrap()
+}
+
+fn other_topology() -> ProjectorTopologyId {
+    ProjectorTopologyId::new(1, "other_projector", [8; 32]).unwrap()
+}
+
+fn partition() -> ProjectionPartition {
+    ProjectionScopeCodec::new(topology())
+        .encode_partition(Some(&serde_json::json!("tenant-a")))
+        .unwrap()
+}
+
+fn source() -> ProjectionSource {
+    ProjectionSource::new("todo_stream", b"todo-1".to_vec()).unwrap()
+}
+
+fn input_cursor(position: u64, source_epoch: &str) -> ProjectionInputCursor {
+    ProjectionInputCursor::new(
+        topology(),
+        partition(),
+        source(),
+        ProjectionEpoch::new(source_epoch).unwrap(),
+        position,
+    )
+    .unwrap()
+}
+
+fn input(
+    position: u64,
+    fingerprint: &[u8],
+    message_id: &str,
+    causation_id: &str,
+    generation: ProjectionGeneration,
+) -> TrustedProjectionInput {
+    TrustedProjectionInput::mint(
+        input_cursor(position, "source-v1"),
+        ProjectionInputFingerprint::from_canonical_bytes(fingerprint),
+        message_id,
+        causation_id,
+        generation,
+        true,
+    )
+    .unwrap()
+}
+
+fn change_epoch() -> ProjectionEpoch {
+    ProjectionEpoch::new("changes-v1").unwrap()
+}
+
+fn change_cursor(position: u64) -> ProjectionChangeCursor {
+    ProjectionChangeCursor::new(topology(), partition(), change_epoch(), position).unwrap()
+}
+
+fn schema() -> &'static TableSchema {
+    static SCHEMA: LazyLock<TableSchema> = LazyLock::new(|| TableSchema {
+        model_name: "TodoView".into(),
+        table_name: "todo_views".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("id", "id", ColumnType::Text)
+            },
+            TableColumn {
+                nullable: true,
+                ..TableColumn::new("value", "value", ColumnType::Text)
+            },
+        ],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    });
+    &SCHEMA
+}
+
+fn scope_codec() -> ProjectionScopeCodec {
+    ProjectionScopeCodec::with_models(topology(), [("TodoView", schema())]).unwrap()
+}
+
+fn record_key() -> RowKey {
+    RowKey::new([("id", RowValue::String("todo-1".into()))])
+}
+
+fn record_scope() -> ProjectionRecordScope {
+    scope_codec()
+        .encode_row_scope_in_partition("TodoView", partition(), &record_key())
+        .unwrap()
+}
+
+fn ownership() -> ProjectionModelOwnership {
+    ProjectionModelOwnership::new("TodoView", "todo_views").unwrap()
+}
+
+#[derive(Clone, Copy)]
+struct ProjectionScenario;
+
+impl crate::projection_protocol::scenario_tests::ProjectionProtocolScenario for ProjectionScenario {
+    type Store = InMemoryRepository;
+
+    fn repository(&self) -> impl std::future::Future<Output = Self::Store> + Send {
+        repository()
+    }
+
+    fn topology(&self) -> ProjectorTopologyId {
+        topology()
+    }
+
+    fn other_topology(&self) -> ProjectorTopologyId {
+        other_topology()
+    }
+
+    fn partition(&self) -> ProjectionPartition {
+        partition()
+    }
+
+    fn change_epoch(&self) -> ProjectionEpoch {
+        change_epoch()
+    }
+
+    fn ownership(&self) -> ProjectionModelOwnership {
+        ownership()
+    }
+
+    fn mutation(
+        &self,
+        expectation: ProjectionRecordExpectation,
+        kind: ProjectionMutationKind,
+    ) -> ProjectionRecordMutation {
+        mutation(expectation, kind)
+    }
+
+    fn row_exists<'a>(
+        &'a self,
+        repository: &'a Self::Store,
+    ) -> impl std::future::Future<Output = bool> + Send + 'a {
+        async move { row_exists(repository) }
+    }
+}
+
+async fn repository() -> InMemoryRepository {
+    repository_with_retention(ProjectionChangeRetention::default()).await
+}
+
+async fn repository_with_retention(retention: ProjectionChangeRetention) -> InMemoryRepository {
+    let repository = InMemoryRepository::new().with_projection_change_retention(retention);
+    repository
+        .register_projection_models(&topology(), &[ownership()])
+        .await
+        .unwrap();
+    repository
+}
+
+fn upsert_table_mutation(valid: bool) -> TableMutation {
+    let key = record_key();
+    let values = if valid {
+        let mut values = RowValues::new();
+        values.insert("id", RowValue::String("todo-1".into()));
+        values
+    } else {
+        RowValues::new()
+    };
+    TableMutation::UpsertRow(TableRowMutation {
+        schema: schema(),
+        key,
+        values,
+        expected_version: ExpectedVersion::Any,
+        mode: RowWriteMode::Upsert,
+    })
+}
+
+fn valued_mutation(
+    value: u64,
+    expectation: ProjectionRecordExpectation,
+) -> ProjectionRecordMutation {
+    let mut values = RowValues::new();
+    values.insert("id", RowValue::String("todo-1".into()));
+    values.insert("value", RowValue::String(value.to_string()));
+    ProjectionRecordMutation::new(
+        record_scope(),
+        TableMutation::UpsertRow(TableRowMutation {
+            schema: schema(),
+            key: record_key(),
+            values,
+            expected_version: ExpectedVersion::Any,
+            mode: RowWriteMode::Upsert,
+        }),
+        expectation,
+        ProjectionMutationKind::Upsert,
+    )
+    .unwrap()
+}
+
+fn snapshot_request() -> ProjectionQuerySnapshotRequest {
+    ProjectionQuerySnapshotRequest::new(
+        &scope_codec(),
+        Some(&serde_json::json!("tenant-a")),
+        "TodoView",
+        record_key(),
+        vec![crate::projection_protocol::ProjectionCheckpointProbe::new(
+            topology(),
+            partition(),
+            source(),
+            ProjectionEpoch::new("source-v1").unwrap(),
+            ProjectionGeneration::initial(),
+        )],
+    )
+    .unwrap()
+}
+
+fn mutation(
+    expectation: ProjectionRecordExpectation,
+    kind: ProjectionMutationKind,
+) -> ProjectionRecordMutation {
+    let table = match kind {
+        ProjectionMutationKind::Delete => TableMutation::DeleteRow(DeleteTableRowMutation {
+            schema: schema(),
+            key: RowKey::new([("id", RowValue::String("todo-1".into()))]),
+            expected_version: ExpectedVersion::Any,
+        }),
+        ProjectionMutationKind::Upsert | ProjectionMutationKind::Recreate => {
+            upsert_table_mutation(true)
+        }
+    };
+    ProjectionRecordMutation::new(record_scope(), table, expectation, kind).unwrap()
+}
+
+fn patch_mutation(expected: RecordRevision) -> ProjectionRecordMutation {
+    ProjectionRecordMutation::new(
+        record_scope(),
+        TableMutation::PatchRow(PatchTableRowMutation {
+            schema: schema(),
+            key: RowKey::new([("id", RowValue::String("todo-1".into()))]),
+            patch: RowPatch::new().set("id", RowValue::String("todo-1".into())),
+            expected_version: ExpectedVersion::Any,
+            mode: PatchMode::UpdateExisting,
+        }),
+        ProjectionRecordExpectation::Exact(expected),
+        ProjectionMutationKind::Upsert,
+    )
+    .unwrap()
+}
+
+fn batch(
+    trusted: TrustedProjectionInput,
+    mutations: Vec<ProjectionRecordMutation>,
+    observations: Vec<ProjectionObservationRequest>,
+) -> ProjectionCommitBatch {
+    ProjectionCommitBatch {
+        input: trusted,
+        change_epoch: change_epoch(),
+        ownership: vec![ownership()],
+        mutations,
+        observations,
+    }
+}
+
+fn row_exists(repository: &InMemoryRepository) -> bool {
+    repository
+        .model_store
+        .relational_rows
+        .read()
+        .unwrap()
+        .contains_key(&upsert_table_mutation(true).lock_key())
+}
+
+fn row_version(repository: &InMemoryRepository) -> Option<u64> {
+    repository
+        .model_store
+        .relational_rows
+        .read()
+        .unwrap()
+        .get(&upsert_table_mutation(true).lock_key())
+        .map(|row| row.version)
+}
+
+fn direct_batch(causation_id: &str) -> SameTransactionProjectionBatch {
+    SameTransactionProjectionBatch::single_upsert(
+        topology(),
+        partition(),
+        change_epoch(),
+        ownership(),
+        record_scope(),
+        upsert_table_mutation(true),
+        causation_id,
+    )
+    .unwrap()
+}
+
+fn insert_physical_row(repository: &InMemoryRepository) {
+    let mut rows = repository.model_store.relational_rows.write().unwrap();
+    apply_read_model_write_plan(
+        TableWritePlan::new(vec![upsert_table_mutation(true)]),
+        &mut rows,
+    )
+    .unwrap();
+}
+
+fn remove_physical_row(repository: &InMemoryRepository) {
+    repository
+        .model_store
+        .relational_rows
+        .write()
+        .unwrap()
+        .remove(&upsert_table_mutation(true).lock_key());
+}
+
+fn assert_query_snapshot_is_coherent(snapshot: &ProjectionQuerySnapshot) {
+    let row = snapshot.row.as_ref().expect("physical row");
+    let record = snapshot.record.as_ref().expect("record metadata");
+    let checkpoint = snapshot.checkpoints[0]
+        .checkpoint
+        .as_ref()
+        .expect("source checkpoint");
+    let value = match row.get("value") {
+        Some(RowValue::String(value)) => value.parse::<u64>().unwrap(),
+        other => panic!("unexpected query snapshot value {other:?}"),
+    };
+    assert_eq!(value, record.revision.revision());
+    assert_eq!(value, checkpoint.input().position());
+    assert_eq!(record.change, *checkpoint.change());
+    assert_eq!(
+        snapshot.change_head.as_ref(),
+        Some(checkpoint.change()),
+        "live resume head must come from the same snapshot"
+    );
+    assert_eq!(snapshot.compacted_through, 0);
+}
+
+#[test]
+fn query_snapshot_probe_and_batch_bounds_are_explicit() {
+    let request = snapshot_request();
+    assert!(ProjectionQuerySnapshotBatchRequest::new(vec![
+        request.clone();
+        crate::projection_protocol::MAX_PROJECTION_QUERY_BATCH_ROWS
+    ])
+    .is_ok());
+    assert!(matches!(
+        ProjectionQuerySnapshotBatchRequest::new(vec![
+            request;
+            crate::projection_protocol::MAX_PROJECTION_QUERY_BATCH_ROWS + 1
+        ]),
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("maximum")
+    ));
+
+    let probes = (0..crate::projection_protocol::MAX_PROJECTION_QUERY_CHECKPOINT_PROBES)
+        .map(|index| {
+            crate::projection_protocol::ProjectionCheckpointProbe::new(
+                topology(),
+                partition(),
+                ProjectionSource::new(
+                    format!("source-{index}"),
+                    format!("partition-{index}").into_bytes(),
+                )
+                .unwrap(),
+                ProjectionEpoch::new("source-v1").unwrap(),
+                ProjectionGeneration::initial(),
+            )
+        })
+        .collect::<Vec<_>>();
+    assert!(ProjectionQuerySnapshotRequest::new(
+        &scope_codec(),
+        Some(&serde_json::json!("tenant-a")),
+        "TodoView",
+        record_key(),
+        probes.clone(),
+    )
+    .is_ok());
+    let max_probe_request = ProjectionQuerySnapshotRequest::new(
+        &scope_codec(),
+        Some(&serde_json::json!("tenant-a")),
+        "TodoView",
+        record_key(),
+        probes.clone(),
+    )
+    .unwrap();
+    assert!(matches!(
+        ProjectionQuerySnapshotBatchRequest::new(vec![max_probe_request; 33]),
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("aggregate checkpoint probes")
+    ));
+    let mut over_limit = probes;
+    over_limit.push(crate::projection_protocol::ProjectionCheckpointProbe::new(
+        topology(),
+        partition(),
+        ProjectionSource::new("source-over-limit", b"over-limit".to_vec()).unwrap(),
+        ProjectionEpoch::new("source-v1").unwrap(),
+        ProjectionGeneration::initial(),
+    ));
+    assert!(matches!(
+        ProjectionQuerySnapshotRequest::new(
+            &scope_codec(),
+            Some(&serde_json::json!("tenant-a")),
+            "TodoView",
+            record_key(),
+            over_limit,
+        ),
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("maximum")
+    ));
+
+    let evidence = (0..crate::projection_protocol::MAX_PROJECTION_EVIDENCE_BATCH_ITEMS)
+        .map(|index| {
+            crate::projection_protocol::ProjectionObligationEvidenceRequest::new(
+                format!("cause-{index}"),
+                record_scope(),
+                ProjectionObservationKind::Record,
+            )
+            .unwrap()
+        })
+        .collect::<Vec<_>>();
+    assert!(
+        crate::projection_protocol::ProjectionObligationEvidenceBatchRequest::new(evidence.clone())
+            .is_ok()
+    );
+    let mut too_many_evidence = evidence;
+    too_many_evidence.push(
+        crate::projection_protocol::ProjectionObligationEvidenceRequest::new(
+            "cause-over-limit",
+            record_scope(),
+            ProjectionObservationKind::Record,
+        )
+        .unwrap(),
+    );
+    assert!(matches!(
+        crate::projection_protocol::ProjectionObligationEvidenceBatchRequest::new(
+            too_many_evidence
+        ),
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("maximum")
+    ));
+    let duplicate = crate::projection_protocol::ProjectionObligationEvidenceRequest::new(
+        "duplicate-cause",
+        record_scope(),
+        ProjectionObservationKind::Record,
+    )
+    .unwrap();
+    assert!(matches!(
+        crate::projection_protocol::ProjectionObligationEvidenceBatchRequest::new(vec![
+            duplicate.clone(),
+            duplicate,
+        ]),
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("repeats")
+    ));
+
+    let live = (0..crate::projection_protocol::MAX_PROJECTION_EVIDENCE_BATCH_ITEMS)
+        .map(|index| {
+            crate::projection_protocol::ProjectionLiveRecordRequest::new(
+                &scope_codec(),
+                "TodoView",
+                RowKey::new([("id", RowValue::String(format!("todo-{index}")))]),
+            )
+            .unwrap()
+        })
+        .collect::<Vec<_>>();
+    assert!(
+        crate::projection_protocol::ProjectionLiveRecordBatchRequest::new(live.clone()).is_ok()
+    );
+    let mut too_many_live = live;
+    too_many_live.push(
+        crate::projection_protocol::ProjectionLiveRecordRequest::new(
+            &scope_codec(),
+            "TodoView",
+            RowKey::new([("id", RowValue::String("todo-over-limit".into()))]),
+        )
+        .unwrap(),
+    );
+    assert!(matches!(
+        crate::projection_protocol::ProjectionLiveRecordBatchRequest::new(too_many_live),
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("maximum")
+    ));
+}
+
+#[tokio::test]
+async fn query_snapshot_never_mixes_row_revision_checkpoint_or_resume_head() {
+    let repository = repository().await;
+    let first = repository
+        .commit_projection(batch(
+            input(
+                1,
+                b"snapshot-1",
+                "snapshot-message-1",
+                "snapshot-cause-1",
+                ProjectionGeneration::initial(),
+            ),
+            vec![valued_mutation(1, ProjectionRecordExpectation::Missing)],
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    let mut expected = first.records[0].revision.clone();
+    assert_query_snapshot_is_coherent(
+        &repository
+            .projection_query_snapshot(&snapshot_request())
+            .await
+            .unwrap(),
+    );
+
+    let writer_repository = repository.clone();
+    let writer = tokio::spawn(async move {
+        for position in 2..=64 {
+            let committed = writer_repository
+                .commit_projection(batch(
+                    input(
+                        position,
+                        format!("snapshot-{position}").as_bytes(),
+                        &format!("snapshot-message-{position}"),
+                        &format!("snapshot-cause-{position}"),
+                        ProjectionGeneration::initial(),
+                    ),
+                    vec![valued_mutation(
+                        position,
+                        ProjectionRecordExpectation::Exact(expected),
+                    )],
+                    Vec::new(),
+                ))
+                .await
+                .unwrap();
+            expected = committed.records[0].revision.clone();
+            tokio::task::yield_now().await;
+        }
+    });
+
+    while !writer.is_finished() {
+        let batch = repository
+            .projection_query_snapshot_batch(
+                &ProjectionQuerySnapshotBatchRequest::new(vec![
+                    snapshot_request(),
+                    snapshot_request(),
+                ])
+                .unwrap(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(batch.snapshots[0], batch.snapshots[1]);
+        assert_query_snapshot_is_coherent(&batch.snapshots[0]);
+        tokio::task::yield_now().await;
+    }
+    writer.await.unwrap();
+    assert_query_snapshot_is_coherent(
+        &repository
+            .projection_query_snapshot(&snapshot_request())
+            .await
+            .unwrap(),
+    );
+}
+
+#[tokio::test]
+async fn obligation_evidence_is_exact_bounded_and_failure_wins_after_compaction() {
+    let repository = repository().await;
+    let scope = record_scope();
+    let observed = repository
+        .commit_projection(batch(
+            input(
+                1,
+                b"observed",
+                "evidence-message-1",
+                "evidence-cause",
+                ProjectionGeneration::initial(),
+            ),
+            vec![mutation(
+                ProjectionRecordExpectation::Missing,
+                ProjectionMutationKind::Upsert,
+            )],
+            vec![ProjectionObservationRequest {
+                kind: ProjectionObservationKind::Record,
+                target: ProjectionObservationTarget::StagedRecord(scope.clone()),
+            }],
+        ))
+        .await
+        .unwrap();
+    let observed_probe = crate::projection_protocol::ProjectionObligationEvidenceRequest::new(
+        "evidence-cause",
+        scope.clone(),
+        ProjectionObservationKind::Record,
+    )
+    .unwrap();
+    let pending_probe = crate::projection_protocol::ProjectionObligationEvidenceRequest::new(
+        "pending-cause",
+        scope,
+        ProjectionObservationKind::Record,
+    )
+    .unwrap();
+    let before_failure = repository
+        .projection_obligation_evidence_batch(
+            &crate::projection_protocol::ProjectionObligationEvidenceBatchRequest::new(vec![
+                observed_probe.clone(),
+                pending_probe.clone(),
+            ])
+            .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert!(matches!(
+        &before_failure.evidence[0],
+        ProjectionObligationEvidence::Observed(observation)
+            if observation.change == observed.changes[0].cursor
+    ));
+    assert_eq!(
+        before_failure.evidence[1],
+        ProjectionObligationEvidence::Pending
+    );
+
+    let failure = repository
+        .record_projection_failure(
+            ProjectionFailureBatch::new(
+                input(
+                    2,
+                    b"failed",
+                    "evidence-message-2",
+                    "evidence-cause",
+                    ProjectionGeneration::initial(),
+                ),
+                change_epoch(),
+                "evidence-failure",
+                "decode_error",
+                b"bad evidence payload".to_vec(),
+            )
+            .unwrap(),
+        )
+        .await
+        .unwrap();
+    repository
+        .compact_projection_changes(&failure.change)
+        .await
+        .unwrap();
+    let after_failure = repository
+        .projection_obligation_evidence_batch(
+            &crate::projection_protocol::ProjectionObligationEvidenceBatchRequest::new(vec![
+                observed_probe,
+                pending_probe,
+            ])
+            .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert!(matches!(
+        &after_failure.evidence[0],
+        ProjectionObligationEvidence::TerminalFailure(stored)
+            if stored == &failure
+    ));
+    assert_eq!(
+        after_failure.evidence[1],
+        ProjectionObligationEvidence::Pending
+    );
+}
+
+#[tokio::test]
+async fn unpartitioned_live_record_follows_tombstone_partition_move_and_rejects_ambiguity() {
+    let repository = repository().await;
+    let old_scope = record_scope();
+    let created = repository
+        .commit_projection(batch(
+            input(
+                1,
+                b"old-partition",
+                "move-message-1",
+                "move-cause-1",
+                ProjectionGeneration::initial(),
+            ),
+            vec![mutation(
+                ProjectionRecordExpectation::Missing,
+                ProjectionMutationKind::Upsert,
+            )],
+            Vec::new(),
+        ))
+        .await
+        .unwrap()
+        .records
+        .remove(0);
+    let live_request = crate::projection_protocol::ProjectionLiveRecordBatchRequest::new(vec![
+        crate::projection_protocol::ProjectionLiveRecordRequest::new(
+            &scope_codec(),
+            "TodoView",
+            record_key(),
+        )
+        .unwrap(),
+    ])
+    .unwrap();
+    let live = repository
+        .projection_live_record_batch(&live_request)
+        .await
+        .unwrap();
+    assert_eq!(
+        live.records[0].as_ref().unwrap().revision.scope(),
+        &old_scope
+    );
+
+    repository
+        .commit_projection(batch(
+            input(
+                2,
+                b"old-delete",
+                "move-message-2",
+                "move-cause-2",
+                ProjectionGeneration::initial(),
+            ),
+            vec![mutation(
+                ProjectionRecordExpectation::Exact(created.revision),
+                ProjectionMutationKind::Delete,
+            )],
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(
+        repository
+            .projection_live_record_batch(&live_request)
+            .await
+            .unwrap()
+            .records,
+        vec![None]
+    );
+
+    let new_partition = scope_codec()
+        .encode_partition(Some(&serde_json::json!("tenant-b")))
+        .unwrap();
+    let new_scope = scope_codec()
+        .encode_row_scope_in_partition("TodoView", new_partition.clone(), &record_key())
+        .unwrap();
+    let new_input = TrustedProjectionInput::mint(
+        ProjectionInputCursor::new(
+            topology(),
+            new_partition,
+            source(),
+            ProjectionEpoch::new("source-v1").unwrap(),
+            1,
+        )
+        .unwrap(),
+        ProjectionInputFingerprint::from_canonical_bytes(b"new-partition"),
+        "move-message-3",
+        "move-cause-3",
+        ProjectionGeneration::initial(),
+        true,
+    )
+    .unwrap();
+    let moved = repository
+        .commit_projection(batch(
+            new_input,
+            vec![ProjectionRecordMutation::new(
+                new_scope.clone(),
+                upsert_table_mutation(true),
+                ProjectionRecordExpectation::Missing,
+                ProjectionMutationKind::Upsert,
+            )
+            .unwrap()],
+            Vec::new(),
+        ))
+        .await
+        .unwrap()
+        .records
+        .remove(0);
+    assert_eq!(
+        repository
+            .projection_live_record_batch(&live_request)
+            .await
+            .unwrap()
+            .records[0]
+            .as_ref()
+            .unwrap()
+            .revision
+            .scope(),
+        &new_scope
+    );
+    assert_eq!(moved.revision.scope(), &new_scope);
+
+    // Simulate durable metadata drift that bypassed the normal write
+    // fence. The read path must report corruption rather than choosing.
+    repository
+        .projection_protocol
+        .write()
+        .unwrap()
+        .records
+        .get_mut(&old_scope)
+        .unwrap()
+        .tombstone = false;
+    assert!(matches!(
+        repository.projection_live_record_batch(&live_request).await,
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("ambiguous")
+    ));
+}
+
+fn other_source_input(
+    message_id: &str,
+    generation: ProjectionGeneration,
+) -> TrustedProjectionInput {
+    TrustedProjectionInput::mint(
+        ProjectionInputCursor::new(
+            topology(),
+            partition(),
+            ProjectionSource::new("other_stream", b"other-1".to_vec()).unwrap(),
+            ProjectionEpoch::new("source-v1").unwrap(),
+            0,
+        )
+        .unwrap(),
+        ProjectionInputFingerprint::from_canonical_bytes(b"other-input"),
+        message_id,
+        "other-cause",
+        generation,
+        true,
+    )
+    .unwrap()
+}
+
+#[tokio::test]
+async fn direct_projection_is_fenced_while_exact_failure_repair_is_pending() {
+    let repository = repository().await;
+    assert_eq!(
+        repository
+            .projection_partition_runtime_state(&topology(), &partition())
+            .await
+            .unwrap(),
+        None
+    );
+    let failure = repository
+        .record_projection_failure(
+            ProjectionFailureBatch::new(
+                input(
+                    0,
+                    b"failed",
+                    "failed-message",
+                    "failed-cause",
+                    ProjectionGeneration::initial(),
+                ),
+                change_epoch(),
+                "failure-1",
+                "decode_error",
+                b"bad payload".to_vec(),
+            )
+            .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert!(failure.gap_free);
+    let stopped = repository
+        .projection_partition_runtime_state(&topology(), &partition())
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(stopped.active_generation, ProjectionGeneration::initial());
+    assert_eq!(stopped.stopped_failure_id.as_deref(), Some("failure-1"));
+    assert_eq!(stopped.pending_retry, None);
+    repository
+        .repair_projection(&topology(), &partition(), "failure-1")
+        .await
+        .unwrap();
+    let repaired = repository
+        .projection_partition_runtime_state(&topology(), &partition())
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(repaired.active_generation.get(), 2);
+    assert_eq!(repaired.stopped_failure_id, None);
+    let retry = repaired.pending_retry.unwrap();
+    assert_eq!(retry.failure_id, "failure-1");
+    assert_eq!(retry.input, failure.input);
+    assert_eq!(retry.input_fingerprint, failure.input_fingerprint);
+    assert_eq!(retry.message_id, failure.message_id);
+    assert_eq!(retry.causation_id, failure.causation_id);
+    assert_eq!(retry.failed_generation, failure.generation);
+    assert_eq!(retry.gap_free, failure.gap_free);
+
+    let mut staged_protocol = repository.projection_protocol.read().unwrap().clone();
+    let mut staged_rows = repository
+        .model_store
+        .relational_rows
+        .read()
+        .unwrap()
+        .clone();
+    assert!(matches!(
+        stage_same_transaction_projection(
+            &mut staged_protocol,
+            &mut staged_rows,
+            &direct_batch("direct-during-repair"),
+            repository.projection_change_retention,
+        ),
+        Err(ProjectionProtocolError::IncomparableInput)
+    ));
+
+    let partition_key = PartitionKey::new(&topology(), &partition());
+    let partition = staged_protocol.partitions.get(&partition_key).unwrap();
+    assert_eq!(partition.change_head, 1);
+    assert_eq!(partition.compacted_through, 0);
+    assert_eq!(
+        partition.pending_retry_failure_id.as_deref(),
+        Some("failure-1")
+    );
+    assert!(staged_protocol.ownership.is_empty());
+    assert!(staged_protocol.records.is_empty());
+    assert!(staged_protocol.observations.is_empty());
+    assert!(staged_rows.is_empty());
+}
+
+#[tokio::test]
+async fn direct_projection_reports_typed_physical_metadata_drift() {
+    let orphan_row = repository().await;
+    insert_physical_row(&orphan_row);
+    let mut staged_protocol = orphan_row.projection_protocol.read().unwrap().clone();
+    let mut staged_rows = orphan_row
+        .model_store
+        .relational_rows
+        .read()
+        .unwrap()
+        .clone();
+    assert!(matches!(
+        stage_same_transaction_projection(
+            &mut staged_protocol,
+            &mut staged_rows,
+            &direct_batch("direct-orphan-row"),
+            orphan_row.projection_change_retention,
+        ),
+        Err(ProjectionProtocolError::RecordAlreadyExists { model })
+            if model == "TodoView"
+    ));
+    assert!(orphan_row
+        .projection_record(&record_scope())
+        .await
+        .unwrap()
+        .is_none());
+    assert!(row_exists(&orphan_row));
+
+    let missing_row = repository().await;
+    let metadata = missing_row
+        .commit_projection(batch(
+            input(
+                0,
+                b"create",
+                "create-message",
+                "create-cause",
+                ProjectionGeneration::initial(),
+            ),
+            vec![mutation(
+                ProjectionRecordExpectation::Missing,
+                ProjectionMutationKind::Upsert,
+            )],
+            Vec::new(),
+        ))
+        .await
+        .unwrap()
+        .records
+        .remove(0);
+    remove_physical_row(&missing_row);
+    let mut staged_protocol = missing_row.projection_protocol.read().unwrap().clone();
+    let mut staged_rows = missing_row
+        .model_store
+        .relational_rows
+        .read()
+        .unwrap()
+        .clone();
+    assert!(matches!(
+        stage_same_transaction_projection(
+            &mut staged_protocol,
+            &mut staged_rows,
+            &direct_batch("direct-missing-row"),
+            missing_row.projection_change_retention,
+        ),
+        Err(ProjectionProtocolError::RecordMissing { model })
+            if model == "TodoView"
+    ));
+    assert_eq!(
+        missing_row
+            .projection_record(&record_scope())
+            .await
+            .unwrap(),
+        Some(metadata)
+    );
+    assert!(!row_exists(&missing_row));
+}
+
+#[tokio::test]
+async fn stale_direct_attempt_is_fenced_before_projection_drift_is_inspected() {
+    let repository = repository().await;
+    let retention = Duration::from_secs(3_600);
+    let command_key = CommandLedgerKey::new(
+        "in-memory-direct-precedence",
+        PrincipalPartitionId::new("tenant:direct-precedence").unwrap(),
+        CommandId::parse(uuid::Uuid::now_v7().hyphenated().to_string()).unwrap(),
+    )
+    .unwrap();
+    let reservation = CommandReservation::new(
+        command_key,
+        "project-todo",
+        CommandContractFingerprint::new([41; 32]),
+        CanonicalInputHash::new([42; 32]),
+        Duration::from_secs(30),
+        retention,
+    )
+    .unwrap();
+    let attempt = match repository.reserve_command(reservation).await.unwrap() {
+        ReservationOutcome::Acquired(attempt) => attempt,
+        _ => panic!("a fresh direct command must acquire its first attempt"),
+    };
+    let direct = direct_batch(attempt.causation_id().as_str());
+    let completion = attempt
+        .complete(
+            TerminalCommandState::Projected,
+            serde_json::json!({"projected": "must-not-run"}),
+            retention,
+        )
+        .unwrap();
+    repository
+        .mark_retryable_unknown(completion.attempt_fence())
+        .await
+        .unwrap();
+
+    // This orphan physical row would produce RecordAlreadyExists if the
+    // direct projection inspected protocol state before the stale attempt.
+    insert_physical_row(&repository);
+    assert!(matches!(
+        repository
+            .commit_causal_batch(CausalCommitBatch::with_direct_projection(
+                CommitBatch::empty(),
+                completion,
+                direct,
+            ))
+            .await,
+        Err(CommandLedgerError::AttemptFenced { .. })
+    ));
+    assert!(row_exists(&repository));
+    assert!(repository
+        .projection_record(&record_scope())
+        .await
+        .unwrap()
+        .is_none());
+    assert!(repository
+        .projection_protocol
+        .read()
+        .unwrap()
+        .partitions
+        .is_empty());
+}
+
+#[tokio::test]
+async fn automatic_change_retention_compacts_success_and_failure_prefixes() {
+    let repository = repository_with_retention(ProjectionChangeRetention::new(2).unwrap()).await;
+    for position in 0..4 {
+        repository
+            .commit_projection(batch(
+                input(
+                    position,
+                    format!("input-{position}").as_bytes(),
+                    &format!("message-{position}"),
+                    &format!("cause-{position}"),
+                    ProjectionGeneration::initial(),
+                ),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+    }
+
+    assert_eq!(
+        repository
+            .projection_changes(&topology(), &partition(), None, 100)
+            .await
+            .unwrap(),
+        ProjectionChangeRead::ResetRequired {
+            head: Some(change_cursor(4)),
+            compacted_through: 2,
+        }
+    );
+    let retained = repository
+        .projection_changes(&topology(), &partition(), Some(&change_cursor(2)), 100)
+        .await
+        .unwrap();
+    let ProjectionChangeRead::Changes {
+        head,
+        compacted_through,
+        changes,
+    } = retained
+    else {
+        panic!("the exact compacted-through cursor must resume retained changes");
+    };
+    assert_eq!(head, Some(change_cursor(4)));
+    assert_eq!(compacted_through, 2);
+    assert_eq!(
+        changes
+            .iter()
+            .map(|change| change.cursor.position())
+            .collect::<Vec<_>>(),
+        vec![3, 4]
+    );
+    assert!(matches!(
+        repository
+            .projection_changes(&topology(), &partition(), Some(&change_cursor(1)), 100)
+            .await
+            .unwrap(),
+        ProjectionChangeRead::ResetRequired {
+            compacted_through: 2,
+            ..
+        }
+    ));
+
+    repository
+        .record_projection_failure(
+            ProjectionFailureBatch::new(
+                input(
+                    4,
+                    b"failure",
+                    "message-4",
+                    "cause-4",
+                    ProjectionGeneration::initial(),
+                ),
+                change_epoch(),
+                "failure-4",
+                "decode_error",
+                b"bad payload".to_vec(),
+            )
+            .unwrap(),
+        )
+        .await
+        .unwrap();
+    let retained = repository
+        .projection_changes(&topology(), &partition(), Some(&change_cursor(3)), 100)
+        .await
+        .unwrap();
+    let ProjectionChangeRead::Changes {
+        head,
+        compacted_through,
+        changes,
+    } = retained
+    else {
+        panic!("the new compacted-through cursor must resume retained changes");
+    };
+    assert_eq!(head, Some(change_cursor(5)));
+    assert_eq!(compacted_through, 3);
+    assert_eq!(
+        changes
+            .iter()
+            .map(|change| (change.cursor.position(), change.kind))
+            .collect::<Vec<_>>(),
+        vec![
+            (4, ProjectionChangeKind::Checkpoint),
+            (5, ProjectionChangeKind::Failure),
+        ]
+    );
+}
+
+#[tokio::test]
+async fn direct_projection_retention_preserves_durable_evidence() {
+    let repository = repository_with_retention(ProjectionChangeRetention::new(1).unwrap()).await;
+    let mut staged_protocol = repository.projection_protocol.read().unwrap().clone();
+    let mut staged_rows = HashMap::new();
+
+    let first = stage_same_transaction_projection(
+        &mut staged_protocol,
+        &mut staged_rows,
+        &direct_batch("direct-1"),
+        repository.projection_change_retention,
+    )
+    .unwrap();
+    let second = stage_same_transaction_projection(
+        &mut staged_protocol,
+        &mut staged_rows,
+        &direct_batch("direct-2"),
+        repository.projection_change_retention,
+    )
+    .unwrap();
+
+    let partition = staged_protocol
+        .partitions
+        .get(&PartitionKey::new(&topology(), &partition()))
+        .unwrap();
+    assert_eq!(partition.change_head, 2);
+    assert_eq!(partition.compacted_through, 1);
+    assert_eq!(
+        partition.changes.keys().copied().collect::<Vec<_>>(),
+        vec![2]
+    );
+    assert_eq!(first.changes[0].cursor, change_cursor(1));
+    assert_eq!(second.changes[0].cursor, change_cursor(2));
+    assert_eq!(
+        staged_protocol
+            .records
+            .get(&record_scope())
+            .unwrap()
+            .revision
+            .revision(),
+        2
+    );
+    assert!(staged_protocol.observations.contains_key(&ObservationKey {
+        causation_id: "direct-1".into(),
+        scope: record_scope(),
+        kind: ProjectionObservationKind::Record,
+    }));
+    assert!(staged_protocol.observations.contains_key(&ObservationKey {
+        causation_id: "direct-2".into(),
+        scope: record_scope(),
+        kind: ProjectionObservationKind::Record,
+    }));
+    assert!(staged_rows.contains_key(&upsert_table_mutation(true).lock_key()));
+}
+
+#[tokio::test]
+async fn automatic_retention_failure_rolls_back_rows_protocol_and_inbox() {
+    let repository = repository_with_retention(ProjectionChangeRetention::new(1).unwrap()).await;
+    let created = repository
+        .commit_projection(batch(
+            input(
+                0,
+                b"create",
+                "message-0",
+                "cause-0",
+                ProjectionGeneration::initial(),
+            ),
+            vec![mutation(
+                ProjectionRecordExpectation::Missing,
+                ProjectionMutationKind::Upsert,
+            )],
+            Vec::new(),
+        ))
+        .await
+        .unwrap()
+        .records
+        .remove(0);
+    let row_version_before = row_version(&repository);
+    let inbox_before = repository.inbox_store.read().unwrap().clone();
+    {
+        let mut protocol = repository.projection_protocol.write().unwrap();
+        protocol
+            .partitions
+            .get_mut(&PartitionKey::new(&topology(), &partition()))
+            .unwrap()
+            .changes
+            .remove(&1);
+    }
+
+    assert!(matches!(
+        repository
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"update",
+                    "message-1",
+                    "cause-1",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![mutation(
+                    ProjectionRecordExpectation::Exact(created.revision.clone()),
+                    ProjectionMutationKind::Upsert,
+                )],
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains(
+                "projection change compaction expected to remove 1 contiguous entries but found 0"
+            )
+    ));
+
+    assert_eq!(row_version(&repository), row_version_before);
+    assert_eq!(
+        repository.projection_record(&record_scope()).await.unwrap(),
+        Some(created)
+    );
+    assert_eq!(*repository.inbox_store.read().unwrap(), inbox_before);
+    let protocol = repository.projection_protocol.read().unwrap();
+    let partition = protocol
+        .partitions
+        .get(&PartitionKey::new(&topology(), &partition()))
+        .unwrap();
+    assert_eq!(partition.change_head, 1);
+    assert_eq!(partition.compacted_through, 0);
+    assert!(partition.changes.is_empty());
+    assert!(!protocol
+        .input_identities
+        .contains_key(&CursorIdentityKey::new(&input_cursor(1, "source-v1"))));
+    assert!(!protocol
+        .applied_receipts
+        .contains_key(&CursorReceiptKey::new(
+            &input_cursor(1, "source-v1"),
+            ProjectionGeneration::initial(),
+        )));
+}
+
+#[tokio::test]
+async fn lengthening_retention_never_restores_a_compacted_prefix() {
+    let repository = repository_with_retention(ProjectionChangeRetention::new(1).unwrap()).await;
+    for position in 0..3 {
+        repository
+            .commit_projection(batch(
+                input(
+                    position,
+                    format!("input-{position}").as_bytes(),
+                    &format!("message-{position}"),
+                    &format!("cause-{position}"),
+                    ProjectionGeneration::initial(),
+                ),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+    }
+    assert_eq!(
+        repository
+            .compact_projection_changes(&change_cursor(3))
+            .await
+            .unwrap(),
+        3
+    );
+
+    let lengthened = repository
+        .clone()
+        .with_projection_change_retention(ProjectionChangeRetention::new(10).unwrap());
+    lengthened
+        .commit_projection(batch(
+            input(
+                3,
+                b"input-3",
+                "message-3",
+                "cause-3",
+                ProjectionGeneration::initial(),
+            ),
+            Vec::new(),
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(
+        lengthened
+            .projection_changes(&topology(), &partition(), None, 100)
+            .await
+            .unwrap(),
+        ProjectionChangeRead::ResetRequired {
+            head: Some(change_cursor(4)),
+            compacted_through: 3,
+        }
+    );
+    assert_eq!(
+        lengthened
+            .projection_changes(&topology(), &partition(), Some(&change_cursor(3)), 100)
+            .await
+            .unwrap(),
+        ProjectionChangeRead::Changes {
+            head: Some(change_cursor(4)),
+            compacted_through: 3,
+            changes: vec![ProjectionChange {
+                cursor: change_cursor(4),
+                kind: ProjectionChangeKind::Checkpoint,
+                causation_id: "cause-3".into(),
+                observation_kind: None,
+                scope: None,
+                revision: None,
+                failure_id: None,
+            }],
+        }
+    );
+}
+
+#[tokio::test]
+async fn malformed_projection_failure_is_rejected_before_memory_writes() {
+    let repository = repository().await;
+    let mut failure = ProjectionFailureBatch::new(
+        input(
+            0,
+            b"malformed-failure",
+            "message-malformed-failure",
+            "cause-malformed-failure",
+            ProjectionGeneration::initial(),
+        ),
+        change_epoch(),
+        "failure-malformed",
+        "decode_error",
+        b"bad payload".to_vec(),
+    )
+    .unwrap();
+    failure.failure_digest = [0; 32];
+
+    assert!(matches!(
+        repository.record_projection_failure(failure).await,
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("digest does not match")
+    ));
+    assert!(repository
+        .projection_failure(&topology(), &partition(), "failure-malformed")
+        .await
+        .unwrap()
+        .is_none());
+    assert!(repository
+        .projection_partition_runtime_state(&topology(), &partition())
+        .await
+        .unwrap()
+        .is_none());
+    assert!(repository.inbox_store.read().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn topology_bootstrap_is_required_for_noop_success_and_failure() {
+    let repository = InMemoryRepository::new();
+    let noop = ProjectionCommitBatch {
+        input: input(
+            0,
+            b"noop",
+            "message-noop",
+            "cause-noop",
+            ProjectionGeneration::initial(),
+        ),
+        change_epoch: change_epoch(),
+        ownership: Vec::new(),
+        mutations: Vec::new(),
+        observations: Vec::new(),
+    };
+    assert!(matches!(
+        repository.commit_projection(noop).await,
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("not bootstrapped")
+    ));
+    let failure = ProjectionFailureBatch::new(
+        input(
+            0,
+            b"failure",
+            "message-failure",
+            "cause-failure",
+            ProjectionGeneration::initial(),
+        ),
+        change_epoch(),
+        "failure-unbootstrapped",
+        "decode_error",
+        b"bad payload".to_vec(),
+    )
+    .unwrap();
+    assert!(matches!(
+        repository.record_projection_failure(failure).await,
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("not bootstrapped")
+    ));
+    assert!(repository
+        .projection_protocol
+        .read()
+        .unwrap()
+        .partitions
+        .is_empty());
+    assert!(repository.inbox_store.read().unwrap().is_empty());
+
+    assert!(matches!(
+        repository.register_projection_models(&topology(), &[]).await,
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("at least one model/table owner")
+    ));
+    repository
+        .register_projection_models(&topology(), &[ownership()])
+        .await
+        .unwrap();
+    let applied = repository
+        .commit_projection(batch(
+            input(
+                0,
+                b"noop",
+                "message-noop",
+                "cause-noop",
+                ProjectionGeneration::initial(),
+            ),
+            Vec::new(),
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(applied.outcome, ProjectionCommitOutcome::Applied);
+    repository
+        .record_projection_failure(
+            ProjectionFailureBatch::new(
+                input(
+                    1,
+                    b"failure",
+                    "message-failure",
+                    "cause-failure",
+                    ProjectionGeneration::initial(),
+                ),
+                change_epoch(),
+                "failure-bootstrapped",
+                "decode_error",
+                b"bad payload".to_vec(),
+            )
+            .unwrap(),
+        )
+        .await
+        .unwrap();
+}
+
+#[tokio::test]
+async fn registration_is_global_and_rejects_unowned_rows_atomically() {
+    let repository = InMemoryRepository::new();
+    repository
+        .model_store()
+        .commit_write_plan(TableWritePlan::new(vec![upsert_table_mutation(true)]))
+        .await
+        .unwrap();
+    assert!(matches!(
+        repository
+            .register_projection_models(&topology(), &[ownership()])
+            .await,
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("contains rows without causal metadata")
+    ));
+    {
+        let protocol = repository.projection_protocol.read().unwrap();
+        assert!(!protocol.registered_topologies.contains(&topology()));
+        assert!(protocol.registered_models.is_empty());
+        assert!(protocol.authoritative_table_owners.is_empty());
+    }
+    assert!(!repository
+        .causal_tables
+        .read()
+        .unwrap()
+        .contains("todo_views"));
+    repository
+        .model_store()
+        .commit_write_plan(TableWritePlan::new(vec![upsert_table_mutation(true)]))
+        .await
+        .unwrap();
+
+    let clean = InMemoryRepository::new();
+    clean
+        .register_projection_models(&topology(), &[ownership()])
+        .await
+        .unwrap();
+    assert!(matches!(
+        clean
+            .register_projection_models(&other_topology(), &[ownership()])
+            .await,
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("authoritative owner")
+    ));
+    let protocol = clean.projection_protocol.read().unwrap();
+    assert!(!protocol.registered_topologies.contains(&other_topology()));
+    assert_eq!(
+        protocol
+            .authoritative_table_owners
+            .get("todo_views")
+            .map(|owner| (&owner.topology, owner.model.as_str())),
+        Some((&topology(), "TodoView"))
+    );
+}
+
+#[tokio::test]
+async fn shared_registered_table_ownership_rejects_other_topology() {
+    crate::projection_protocol::scenario_tests::registered_table_ownership_rejects_other_topology(
+        ProjectionScenario,
+    )
+    .await;
+}
+
+#[tokio::test]
+async fn cursor_fences_are_exact_and_non_mutating() {
+    let repository = repository().await;
+    let applied = repository
+        .commit_projection(batch(
+            input(
+                1,
+                b"input-1",
+                "message-1",
+                "cause-1",
+                ProjectionGeneration::initial(),
+            ),
+            vec![mutation(
+                ProjectionRecordExpectation::Missing,
+                ProjectionMutationKind::Upsert,
+            )],
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(applied.outcome, ProjectionCommitOutcome::Applied);
+    assert!(row_exists(&repository));
+
+    let duplicate = repository
+        .commit_projection(batch(
+            input(
+                1,
+                b"input-1",
+                "message-1",
+                "cause-1",
+                ProjectionGeneration::initial(),
+            ),
+            vec![mutation(
+                ProjectionRecordExpectation::Missing,
+                ProjectionMutationKind::Upsert,
+            )],
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(duplicate.outcome, ProjectionCommitOutcome::Duplicate);
+    assert!(duplicate.changes.is_empty());
+
+    for corrupted in [
+        input(
+            1,
+            b"input-1",
+            "different-message",
+            "cause-1",
+            ProjectionGeneration::initial(),
+        ),
+        input(
+            1,
+            b"input-1",
+            "message-1",
+            "different-cause",
+            ProjectionGeneration::initial(),
+        ),
+    ] {
+        assert!(matches!(
+            repository
+                .commit_projection(batch(corrupted, Vec::new(), Vec::new()))
+                .await,
+            Err(ProjectionProtocolError::InputCorruption)
+        ));
+    }
+
+    let stale = repository
+        .commit_projection(batch(
+            input(
+                0,
+                b"older",
+                "message-0",
+                "cause-0",
+                ProjectionGeneration::initial(),
+            ),
+            Vec::new(),
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(stale.outcome, ProjectionCommitOutcome::StaleInput);
+    assert!(matches!(
+        repository
+            .commit_projection(batch(
+                input(
+                    0,
+                    b"older",
+                    "message-1",
+                    "cause-0",
+                    ProjectionGeneration::initial(),
+                ),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::MessageIdReuse { .. })
+    ));
+    let incomparable = TrustedProjectionInput::mint(
+        input_cursor(2, "source-v2"),
+        ProjectionInputFingerprint::from_canonical_bytes(b"new-epoch"),
+        "message-new-epoch",
+        "cause-new-epoch",
+        ProjectionGeneration::initial(),
+        true,
+    )
+    .unwrap();
+    assert!(matches!(
+        repository
+            .commit_projection(batch(incomparable, Vec::new(), Vec::new()))
+            .await,
+        Err(ProjectionProtocolError::IncomparableInput)
+    ));
+
+    assert!(matches!(
+        repository
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"corrupt",
+                    "message-corrupt",
+                    "cause-1",
+                    ProjectionGeneration::initial(),
+                ),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::InputCorruption)
+    ));
+    assert_eq!(
+        repository
+            .projection_changes(&topology(), &partition(), None, 100)
+            .await
+            .unwrap(),
+        ProjectionChangeRead::Changes {
+            head: applied
+                .checkpoint
+                .map(|checkpoint| checkpoint.change().clone()),
+            compacted_through: 0,
+            changes: applied.changes,
+        }
+    );
+}
+
+#[tokio::test]
+async fn message_receipts_and_gap_capability_are_immutable() {
+    let repo = repository().await;
+    for (position, fingerprint, message, cause) in [
+        (1, b"one".as_slice(), "message-1", "cause-1"),
+        (2, b"two".as_slice(), "message-2", "cause-2"),
+    ] {
+        repo.commit_projection(batch(
+            input(
+                position,
+                fingerprint,
+                message,
+                cause,
+                ProjectionGeneration::initial(),
+            ),
+            Vec::new(),
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    }
+
+    let old_duplicate = repo
+        .commit_projection(batch(
+            input(
+                1,
+                b"one",
+                "message-1",
+                "cause-1",
+                ProjectionGeneration::initial(),
+            ),
+            Vec::new(),
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(old_duplicate.outcome, ProjectionCommitOutcome::Duplicate);
+
+    let changed_old_cursor = input(
+        1,
+        b"one",
+        "new-message-at-old-cursor",
+        "cause-1",
+        ProjectionGeneration::initial(),
+    );
+    assert!(matches!(
+        repo.commit_projection(batch(changed_old_cursor, Vec::new(), Vec::new()))
+            .await,
+        Err(ProjectionProtocolError::InputCorruption)
+    ));
+
+    let reused_old_message = input(
+        3,
+        b"three",
+        "message-1",
+        "cause-3",
+        ProjectionGeneration::initial(),
+    );
+    assert!(matches!(
+        repo.commit_projection(batch(reused_old_message, Vec::new(), Vec::new()))
+            .await,
+        Err(ProjectionProtocolError::MessageIdReuse { .. })
+    ));
+
+    assert!(matches!(
+        repo.commit_projection(batch(
+            input(
+                4,
+                b"gap",
+                "gap-message",
+                "gap-cause",
+                ProjectionGeneration::initial(),
+            ),
+            Vec::new(),
+            Vec::new(),
+        ))
+        .await,
+        Err(ProjectionProtocolError::IncomparableInput)
+    ));
+
+    let changed_causation = TrustedProjectionInput::mint(
+        input_cursor(1, "source-v1"),
+        ProjectionInputFingerprint::from_canonical_bytes(b"one"),
+        "message-1",
+        "changed-cause",
+        ProjectionGeneration::initial(),
+        true,
+    )
+    .unwrap();
+    assert!(matches!(
+        repo.commit_projection(batch(changed_causation, Vec::new(), Vec::new()))
+            .await,
+        Err(ProjectionProtocolError::InputCorruption)
+    ));
+
+    for (position, fingerprint, message, cause) in [
+        (1, b"one".as_slice(), "old-capability", "cause-1"),
+        (2, b"two".as_slice(), "equal-capability", "cause-2"),
+        (3, b"three".as_slice(), "new-capability", "cause-3"),
+    ] {
+        let changed_capability = TrustedProjectionInput::mint(
+            input_cursor(position, "source-v1"),
+            ProjectionInputFingerprint::from_canonical_bytes(fingerprint),
+            message,
+            cause,
+            ProjectionGeneration::initial(),
+            false,
+        )
+        .unwrap();
+        assert!(matches!(
+            repo.commit_projection(batch(changed_capability, Vec::new(), Vec::new()))
+                .await,
+            Err(ProjectionProtocolError::InputCorruption)
+        ));
+    }
+
+    // A first-ever terminal failure also registers the source capability;
+    // repair generations cannot silently redefine it merely because there
+    // was no last-good checkpoint to copy.
+    let failed_first = repository().await;
+    failed_first
+        .record_projection_failure(
+            ProjectionFailureBatch::new(
+                input(
+                    0,
+                    b"failed-first",
+                    "failed-first-message",
+                    "failed-first-cause",
+                    ProjectionGeneration::initial(),
+                ),
+                change_epoch(),
+                "failed-first-id",
+                "decode_error",
+                b"bad first payload".to_vec(),
+            )
+            .unwrap(),
+        )
+        .await
+        .unwrap();
+    let repaired_generation = failed_first
+        .repair_projection(&topology(), &partition(), "failed-first-id")
+        .await
+        .unwrap();
+    let changed_after_repair = TrustedProjectionInput::mint(
+        input_cursor(0, "source-v1"),
+        ProjectionInputFingerprint::from_canonical_bytes(b"retry"),
+        "retry-message",
+        "retry-cause",
+        repaired_generation,
+        false,
+    )
+    .unwrap();
+    assert!(matches!(
+        failed_first
+            .commit_projection(batch(changed_after_repair, Vec::new(), Vec::new()))
+            .await,
+        Err(ProjectionProtocolError::InputCorruption)
+    ));
+}
+
+#[tokio::test]
+async fn message_identity_is_topology_wide_across_projection_partitions() {
+    crate::projection_protocol::scenario_tests::message_identity_is_topology_wide_across_projection_partitions(
+        ProjectionScenario,
+    )
+    .await;
+}
+
+#[tokio::test]
+async fn input_disposition_is_read_only_exact_and_repair_fenced() {
+    crate::projection_protocol::scenario_tests::input_disposition_is_read_only_exact_and_repair_fenced(
+        ProjectionScenario,
+    )
+    .await;
+}
+
+#[tokio::test]
+async fn repair_generation_retries_only_the_exact_failed_input() {
+    let repository = repository().await;
+    repository
+        .commit_projection(batch(
+            input(
+                1,
+                b"one",
+                "message-1",
+                "cause-1",
+                ProjectionGeneration::initial(),
+            ),
+            Vec::new(),
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    let failed_input = input(
+        2,
+        b"two",
+        "message-2",
+        "cause-2",
+        ProjectionGeneration::initial(),
+    );
+    repository
+        .record_projection_failure(
+            ProjectionFailureBatch::new(
+                failed_input.clone(),
+                change_epoch(),
+                "failure-2",
+                "decode_error",
+                b"bad payload".to_vec(),
+            )
+            .unwrap(),
+        )
+        .await
+        .unwrap();
+
+    let corrupt_stopped = input(
+        2,
+        b"changed",
+        "message-2",
+        "cause-2",
+        ProjectionGeneration::initial(),
+    );
+    assert!(matches!(
+        repository
+            .commit_projection(batch(corrupt_stopped, Vec::new(), Vec::new()))
+            .await,
+        Err(ProjectionProtocolError::InputCorruption)
+    ));
+
+    let generation = repository
+        .repair_projection(&topology(), &partition(), "failure-2")
+        .await
+        .unwrap();
+    {
+        let protocol = repository.projection_protocol.read().unwrap();
+        assert_eq!(
+            protocol.generations.get(&GenerationKey {
+                partition: PartitionKey::new(&topology(), &partition()),
+                generation,
+            }),
+            Some(&GenerationLineage {
+                retry_of_generation: Some(ProjectionGeneration::initial()),
+                retry_of_failure_id: Some("failure-2".into()),
+            })
+        );
+        assert_eq!(
+            protocol
+                .partitions
+                .get(&PartitionKey::new(&topology(), &partition()))
+                .and_then(|partition| partition.pending_retry_failure_id.as_deref()),
+            Some("failure-2")
+        );
+    }
+
+    assert!(matches!(
+        repository
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"changed-known-cursor",
+                    "message-1",
+                    "cause-1",
+                    ProjectionGeneration::initial(),
+                ),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::InputCorruption)
+    ));
+    let changed_source_capability = TrustedProjectionInput::mint(
+        input_cursor(3, "source-v1"),
+        ProjectionInputFingerprint::from_canonical_bytes(b"changed-source-capability"),
+        "changed-source-capability-message",
+        "changed-source-capability-cause",
+        ProjectionGeneration::initial(),
+        false,
+    )
+    .unwrap();
+    assert!(matches!(
+        repository
+            .commit_projection(batch(changed_source_capability, Vec::new(), Vec::new(),))
+            .await,
+        Err(ProjectionProtocolError::InputCorruption)
+    ));
+    assert!(matches!(
+        repository
+            .commit_projection(batch(
+                other_source_input("unknown-old-generation", ProjectionGeneration::initial()),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::GenerationFenced {
+            expected: 2,
+            actual: 1,
+        })
+    ));
+    assert!(matches!(
+        repository
+            .commit_projection(batch(
+                other_source_input("message-1", ProjectionGeneration::initial()),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::MessageIdReuse { message_id })
+            if message_id == "message-1"
+    ));
+
+    let inherited = repository
+        .commit_projection(batch(
+            input(1, b"one", "message-1", "cause-1", generation),
+            Vec::new(),
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(inherited.outcome, ProjectionCommitOutcome::Duplicate);
+    assert!(!repository
+        .projection_protocol
+        .read()
+        .unwrap()
+        .applied_receipts
+        .contains_key(&CursorReceiptKey::new(
+            &input_cursor(1, "source-v1"),
+            generation,
+        )));
+    let inherited_older = repository
+        .commit_projection(batch(
+            input(0, b"zero", "message-0", "cause-0", generation),
+            Vec::new(),
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(inherited_older.outcome, ProjectionCommitOutcome::StaleInput);
+
+    assert!(matches!(
+        repository
+            .commit_projection(batch(
+                other_source_input("other-message", generation),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::IncomparableInput)
+    ));
+    assert!(matches!(
+        repository
+            .commit_projection(batch(
+                other_source_input("message-1", generation),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::MessageIdReuse { message_id })
+            if message_id == "message-1"
+    ));
+    assert!(matches!(
+        repository
+            .commit_projection(batch(
+                input(2, b"changed", "message-2", "cause-2", generation),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::InputCorruption)
+    ));
+
+    let repaired = repository
+        .commit_projection(batch(
+            input(2, b"two", "message-2", "cause-2", generation),
+            Vec::new(),
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(repaired.outcome, ProjectionCommitOutcome::Applied);
+    assert!(repository
+        .projection_protocol
+        .read()
+        .unwrap()
+        .partitions
+        .get(&PartitionKey::new(&topology(), &partition()))
+        .unwrap()
+        .pending_retry_failure_id
+        .is_none());
+    assert_eq!(
+        repository
+            .commit_projection(batch(
+                input(3, b"three", "message-3", "cause-3", generation),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await
+            .unwrap()
+            .outcome,
+        ProjectionCommitOutcome::Applied
+    );
+
+    let failed_again = self::repository().await;
+    failed_again
+        .record_projection_failure(
+            ProjectionFailureBatch::new(
+                input(
+                    0,
+                    b"first-failure",
+                    "first-failure-message",
+                    "first-failure-cause",
+                    ProjectionGeneration::initial(),
+                ),
+                change_epoch(),
+                "first-failure",
+                "decode_error",
+                b"bad payload".to_vec(),
+            )
+            .unwrap(),
+        )
+        .await
+        .unwrap();
+    let retry_generation = failed_again
+        .repair_projection(&topology(), &partition(), "first-failure")
+        .await
+        .unwrap();
+    let retried_failure = failed_again
+        .record_projection_failure(
+            ProjectionFailureBatch::new(
+                input(
+                    0,
+                    b"first-failure",
+                    "first-failure-message",
+                    "first-failure-cause",
+                    retry_generation,
+                ),
+                change_epoch(),
+                "second-failure",
+                "decode_error",
+                b"still bad".to_vec(),
+            )
+            .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(retried_failure.generation, retry_generation);
+    assert!(matches!(
+        failed_again
+            .commit_projection(batch(
+                other_source_input("blocked-after-retry-failure", retry_generation),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::PartitionStopped { failure_id })
+            if failure_id == "second-failure"
+    ));
+}
+
+#[tokio::test]
+async fn tombstone_requires_explicit_exact_recreation() {
+    crate::projection_protocol::scenario_tests::tombstone_requires_explicit_exact_recreation(
+        ProjectionScenario,
+    )
+    .await;
+}
+
+#[tokio::test]
+async fn failure_recording_is_idempotent_for_exact_batch() {
+    crate::projection_protocol::scenario_tests::failure_recording_is_idempotent_for_exact_batch(
+        ProjectionScenario,
+    )
+    .await;
+}
+
+#[tokio::test]
+async fn physical_rows_must_match_projection_record_metadata() {
+    let create_with_orphan_row = repository().await;
+    insert_physical_row(&create_with_orphan_row);
+    assert!(matches!(
+        create_with_orphan_row
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"orphan",
+                    "message-orphan",
+                    "cause-orphan",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![mutation(
+                    ProjectionRecordExpectation::Missing,
+                    ProjectionMutationKind::Upsert,
+                )],
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("physical row to be absent")
+    ));
+    assert!(create_with_orphan_row
+        .projection_record(&record_scope())
+        .await
+        .unwrap()
+        .is_none());
+    assert!(create_with_orphan_row
+        .inbox_store
+        .read()
+        .unwrap()
+        .is_empty());
+    {
+        let protocol = create_with_orphan_row.projection_protocol.read().unwrap();
+        assert!(protocol.partitions.is_empty());
+        assert!(protocol.input_identities.is_empty());
+        assert!(protocol.applied_receipts.is_empty());
+    }
+
+    for operation in ["save", "patch", "delete"] {
+        let repository = repository().await;
+        let created = repository
+            .commit_projection(batch(
+                input(
+                    1,
+                    format!("{operation}-create").as_bytes(),
+                    &format!("{operation}-message-1"),
+                    &format!("{operation}-cause-1"),
+                    ProjectionGeneration::initial(),
+                ),
+                vec![mutation(
+                    ProjectionRecordExpectation::Missing,
+                    ProjectionMutationKind::Upsert,
+                )],
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        let metadata = created.records[0].clone();
+        let changes_before = repository
+            .projection_changes(&topology(), &partition(), None, 100)
+            .await
+            .unwrap();
+        let inbox_before = repository.inbox_store.read().unwrap().clone();
+        remove_physical_row(&repository);
+        let attempted = match operation {
+            "save" => mutation(
+                ProjectionRecordExpectation::Exact(metadata.revision.clone()),
+                ProjectionMutationKind::Upsert,
+            ),
+            "patch" => patch_mutation(metadata.revision.clone()),
+            "delete" => mutation(
+                ProjectionRecordExpectation::Exact(metadata.revision.clone()),
+                ProjectionMutationKind::Delete,
+            ),
+            _ => unreachable!(),
+        };
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        2,
+                        format!("{operation}-missing").as_bytes(),
+                        &format!("{operation}-message-2"),
+                        &format!("{operation}-cause-2"),
+                        ProjectionGeneration::initial(),
+                    ),
+                    vec![attempted],
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::InvalidBatch(message))
+                if message.contains("physical row to be present")
+        ));
+        assert_eq!(
+            repository.projection_record(&record_scope()).await.unwrap(),
+            Some(metadata)
+        );
+        assert_eq!(
+            repository
+                .projection_changes(&topology(), &partition(), None, 100)
+                .await
+                .unwrap(),
+            changes_before
+        );
+        assert_eq!(*repository.inbox_store.read().unwrap(), inbox_before);
+        let protocol = repository.projection_protocol.read().unwrap();
+        assert!(!protocol
+            .input_identities
+            .contains_key(&CursorIdentityKey::new(&input_cursor(2, "source-v1"))));
+        assert!(!protocol
+            .applied_receipts
+            .contains_key(&CursorReceiptKey::new(
+                &input_cursor(2, "source-v1"),
+                ProjectionGeneration::initial(),
+            )));
+    }
+
+    let recreate_with_row = repository().await;
+    let created = recreate_with_row
+        .commit_projection(batch(
+            input(
+                1,
+                b"create",
+                "recreate-message-1",
+                "recreate-cause-1",
+                ProjectionGeneration::initial(),
+            ),
+            vec![mutation(
+                ProjectionRecordExpectation::Missing,
+                ProjectionMutationKind::Upsert,
+            )],
+            Vec::new(),
+        ))
+        .await
+        .unwrap()
+        .records
+        .remove(0);
+    let deleted = recreate_with_row
+        .commit_projection(batch(
+            input(
+                2,
+                b"delete",
+                "recreate-message-2",
+                "recreate-cause-2",
+                ProjectionGeneration::initial(),
+            ),
+            vec![mutation(
+                ProjectionRecordExpectation::Exact(created.revision),
+                ProjectionMutationKind::Delete,
+            )],
+            Vec::new(),
+        ))
+        .await
+        .unwrap()
+        .records
+        .remove(0);
+    insert_physical_row(&recreate_with_row);
+    let changes_before = recreate_with_row
+        .projection_changes(&topology(), &partition(), None, 100)
+        .await
+        .unwrap();
+    let inbox_before = recreate_with_row.inbox_store.read().unwrap().clone();
+    assert!(matches!(
+        recreate_with_row
+            .commit_projection(batch(
+                input(
+                    3,
+                    b"recreate",
+                    "recreate-message-3",
+                    "recreate-cause-3",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![mutation(
+                    ProjectionRecordExpectation::Exact(deleted.revision.clone()),
+                    ProjectionMutationKind::Recreate,
+                )],
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("physical row to be absent")
+    ));
+    assert_eq!(
+        recreate_with_row
+            .projection_record(&record_scope())
+            .await
+            .unwrap(),
+        Some(deleted)
+    );
+    assert_eq!(
+        recreate_with_row
+            .projection_changes(&topology(), &partition(), None, 100)
+            .await
+            .unwrap(),
+        changes_before
+    );
+    assert_eq!(*recreate_with_row.inbox_store.read().unwrap(), inbox_before);
+    assert!(row_exists(&recreate_with_row));
+}
+
+#[tokio::test]
+async fn table_failure_rolls_back_rows_protocol_and_inbox() {
+    let repository = repository().await;
+    let invalid = ProjectionRecordMutation::new(
+        record_scope(),
+        upsert_table_mutation(false),
+        ProjectionRecordExpectation::Missing,
+        ProjectionMutationKind::Upsert,
+    )
+    .unwrap();
+    assert!(matches!(
+        repository
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"invalid",
+                    "message-invalid",
+                    "cause-invalid",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![invalid],
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::Table(_))
+    ));
+    assert!(!row_exists(&repository));
+    assert!(repository
+        .projection_record(&record_scope())
+        .await
+        .unwrap()
+        .is_none());
+    assert!(repository
+        .projection_checkpoint(
+            &input_cursor(1, "source-v1"),
+            ProjectionGeneration::initial()
+        )
+        .await
+        .unwrap()
+        .is_none());
+    assert!(repository.inbox_store.read().unwrap().is_empty());
+    {
+        let protocol = repository.projection_protocol.read().unwrap();
+        assert!(protocol.partitions.is_empty());
+        assert!(protocol.inputs.is_empty());
+        assert!(protocol.input_identities.is_empty());
+        assert!(protocol.messages.is_empty());
+        assert!(protocol.applied_receipts.is_empty());
+        assert!(protocol.observations.is_empty());
+        assert!(protocol.failures.is_empty());
+    }
+
+    let changes = repository
+        .projection_changes(&topology(), &partition(), None, 100)
+        .await
+        .unwrap();
+    assert_eq!(
+        changes,
+        ProjectionChangeRead::Changes {
+            head: None,
+            compacted_through: 0,
+            changes: Vec::new(),
+        }
+    );
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn concurrent_same_input_applies_once() {
+    let repository = repository().await;
+    let barrier = Arc::new(Barrier::new(2));
+    let mut joins = Vec::new();
+    for _ in 0..2 {
+        let repository = repository.clone();
+        let barrier = Arc::clone(&barrier);
+        joins.push(tokio::spawn(async move {
+            barrier.wait();
+            repository
+                .commit_projection(batch(
+                    input(
+                        1,
+                        b"same-input",
+                        "message-1",
+                        "cause-1",
+                        ProjectionGeneration::initial(),
+                    ),
+                    vec![mutation(
+                        ProjectionRecordExpectation::Missing,
+                        ProjectionMutationKind::Upsert,
+                    )],
+                    Vec::new(),
+                ))
+                .await
+                .unwrap()
+                .outcome
+        }));
+    }
+    let mut outcomes = Vec::with_capacity(joins.len());
+    for join in joins {
+        outcomes.push(join.await.unwrap());
+    }
+    assert_eq!(
+        outcomes
+            .iter()
+            .filter(|outcome| **outcome == ProjectionCommitOutcome::Applied)
+            .count(),
+        1
+    );
+    assert_eq!(
+        outcomes
+            .iter()
+            .filter(|outcome| **outcome == ProjectionCommitOutcome::Duplicate)
+            .count(),
+        1
+    );
+    assert_eq!(
+        repository
+            .projection_record(&record_scope())
+            .await
+            .unwrap()
+            .unwrap()
+            .revision
+            .revision(),
+        1
+    );
+}
+
+#[tokio::test]
+async fn observations_are_immutable_and_staged_records_reuse_row_changes() {
+    let repository = repository().await;
+    let scope = record_scope();
+    let first = repository
+        .commit_projection(batch(
+            input(
+                1,
+                b"first",
+                "message-1",
+                "cause-stable",
+                ProjectionGeneration::initial(),
+            ),
+            vec![mutation(
+                ProjectionRecordExpectation::Missing,
+                ProjectionMutationKind::Upsert,
+            )],
+            vec![ProjectionObservationRequest {
+                kind: ProjectionObservationKind::Record,
+                target: ProjectionObservationTarget::StagedRecord(scope.clone()),
+            }],
+        ))
+        .await
+        .unwrap();
+    assert_eq!(first.changes.len(), 1);
+    assert_eq!(first.changes[0].kind, ProjectionChangeKind::RecordUpsert);
+    let earliest = repository
+        .projection_observation("cause-stable", &scope, ProjectionObservationKind::Record)
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(earliest.change, first.changes[0].cursor);
+    assert_eq!(earliest.revision.as_ref(), Some(&first.records[0].revision));
+
+    let second = repository
+        .commit_projection(batch(
+            input(
+                2,
+                b"second",
+                "message-2",
+                "cause-stable",
+                ProjectionGeneration::initial(),
+            ),
+            vec![mutation(
+                ProjectionRecordExpectation::Exact(first.records[0].revision.clone()),
+                ProjectionMutationKind::Upsert,
+            )],
+            vec![ProjectionObservationRequest {
+                kind: ProjectionObservationKind::Record,
+                target: ProjectionObservationTarget::StagedRecord(scope.clone()),
+            }],
+        ))
+        .await
+        .unwrap();
+    assert_eq!(second.changes.len(), 1);
+    assert_eq!(second.changes[0].kind, ProjectionChangeKind::RecordUpsert);
+    assert_eq!(
+        repository
+            .projection_observation("cause-stable", &scope, ProjectionObservationKind::Record)
+            .await
+            .unwrap(),
+        Some(earliest)
+    );
+
+    let existing = repository
+        .commit_projection(batch(
+            input(
+                3,
+                b"existing",
+                "message-3",
+                "cause-existing",
+                ProjectionGeneration::initial(),
+            ),
+            Vec::new(),
+            vec![ProjectionObservationRequest {
+                kind: ProjectionObservationKind::Record,
+                target: ProjectionObservationTarget::ExistingRecord(
+                    second.records[0].revision.clone(),
+                ),
+            }],
+        ))
+        .await
+        .unwrap();
+    assert_eq!(existing.changes.len(), 1);
+    assert_eq!(existing.changes[0].kind, ProjectionChangeKind::Observation);
+    let earliest_existing = repository
+        .projection_observation("cause-existing", &scope, ProjectionObservationKind::Record)
+        .await
+        .unwrap()
+        .unwrap();
+
+    let repeated = repository
+        .commit_projection(batch(
+            input(
+                4,
+                b"existing-repeat",
+                "message-4",
+                "cause-existing",
+                ProjectionGeneration::initial(),
+            ),
+            Vec::new(),
+            vec![ProjectionObservationRequest {
+                kind: ProjectionObservationKind::Record,
+                target: ProjectionObservationTarget::ExistingRecord(
+                    second.records[0].revision.clone(),
+                ),
+            }],
+        ))
+        .await
+        .unwrap();
+    assert_eq!(repeated.changes.len(), 1);
+    assert_eq!(repeated.changes[0].kind, ProjectionChangeKind::Checkpoint);
+    assert_eq!(
+        repository
+            .projection_observation("cause-existing", &scope, ProjectionObservationKind::Record)
+            .await
+            .unwrap(),
+        Some(earliest_existing)
+    );
+}
+
+#[tokio::test]
+async fn dependency_failure_repair_and_resume_are_durable() {
+    let repository = repository().await;
+    let scope = record_scope();
+    let first = repository
+        .commit_projection(batch(
+            input(
+                1,
+                b"dependency",
+                "message-1",
+                "cause-1",
+                ProjectionGeneration::initial(),
+            ),
+            Vec::new(),
+            vec![ProjectionObservationRequest {
+                kind: ProjectionObservationKind::Dependency,
+                target: ProjectionObservationTarget::Dependency(scope.clone()),
+            }],
+        ))
+        .await
+        .unwrap();
+    let observation = repository
+        .projection_observation("cause-1", &scope, ProjectionObservationKind::Dependency)
+        .await
+        .unwrap()
+        .unwrap();
+    assert!(observation.revision.is_none());
+    assert_eq!(observation.scope, scope);
+
+    let failure_batch = ProjectionFailureBatch::new(
+        input(
+            2,
+            b"failure",
+            "message-2",
+            "cause-2",
+            ProjectionGeneration::initial(),
+        ),
+        change_epoch(),
+        "failure-2",
+        "decode_error",
+        b"bad payload".to_vec(),
+    )
+    .unwrap();
+    let failure = repository
+        .record_projection_failure(failure_batch.clone())
+        .await
+        .unwrap();
+    assert_eq!(
+        repository
+            .record_projection_failure(failure_batch.clone())
+            .await
+            .unwrap(),
+        failure
+    );
+    let changed_capability = ProjectionFailureBatch::new(
+        TrustedProjectionInput::mint(
+            input_cursor(2, "source-v1"),
+            ProjectionInputFingerprint::from_canonical_bytes(b"failure"),
+            "message-2",
+            "cause-2",
+            ProjectionGeneration::initial(),
+            false,
+        )
+        .unwrap(),
+        change_epoch(),
+        "failure-2",
+        "decode_error",
+        b"bad payload".to_vec(),
+    )
+    .unwrap();
+    assert!(matches!(
+        repository
+            .record_projection_failure(changed_capability)
+            .await,
+        Err(ProjectionProtocolError::InputCorruption)
+    ));
+    assert_eq!(
+        repository
+            .projection_failure(&topology(), &partition(), "failure-2")
+            .await
+            .unwrap(),
+        Some(failure.clone())
+    );
+    assert!(matches!(
+        repository
+            .commit_projection(batch(
+                input(
+                    3,
+                    b"blocked",
+                    "message-3",
+                    "cause-3",
+                    ProjectionGeneration::initial(),
+                ),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::PartitionStopped { .. })
+    ));
+
+    let generation = repository
+        .repair_projection(&topology(), &partition(), "failure-2")
+        .await
+        .unwrap();
+    assert_eq!(generation.get(), 2);
+    assert!(matches!(
+        repository.record_projection_failure(failure_batch).await,
+        Err(ProjectionProtocolError::GenerationFenced {
+            expected: 2,
+            actual: 1
+        })
+    ));
+    let repaired = repository
+        .commit_projection(batch(
+            input(2, b"failure", "message-2", "cause-2", generation),
+            Vec::new(),
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(repaired.changes[0].kind, ProjectionChangeKind::Checkpoint);
+
+    let compacted = repository
+        .compact_projection_changes(&first.changes[0].cursor)
+        .await
+        .unwrap();
+    assert_eq!(compacted, first.changes[0].cursor.position());
+    assert!(matches!(
+        repository
+            .projection_changes(&topology(), &partition(), None, 100)
+            .await
+            .unwrap(),
+        ProjectionChangeRead::ResetRequired {
+            compacted_through,
+            ..
+        } if compacted_through == compacted
+    ));
+    let boundary_resume = repository
+        .projection_changes(
+            &topology(),
+            &partition(),
+            Some(&first.changes[0].cursor),
+            100,
+        )
+        .await
+        .unwrap();
+    assert!(matches!(
+        boundary_resume,
+        ProjectionChangeRead::Changes {
+            compacted_through,
+            ref changes,
+            ..
+        } if compacted_through == compacted && changes.len() == 2
+    ));
+
+    repository
+        .compact_projection_changes(&failure.change)
+        .await
+        .unwrap();
+    assert!(matches!(
+        repository
+            .projection_changes(
+                &topology(),
+                &partition(),
+                Some(&first.changes[0].cursor),
+                100
+            )
+            .await
+            .unwrap(),
+        ProjectionChangeRead::ResetRequired { .. }
+    ));
+
+    let future = ProjectionChangeCursor::new(
+        topology(),
+        partition(),
+        change_epoch(),
+        repaired.changes[0].cursor.position() + 10,
+    )
+    .unwrap();
+    assert!(matches!(
+        repository
+            .projection_changes(&topology(), &partition(), Some(&future), 100)
+            .await
+            .unwrap(),
+        ProjectionChangeRead::ResetRequired { .. }
+    ));
+}
+
+#[tokio::test]
+async fn causal_owned_table_rejects_every_legacy_commit_path() {
+    let repository = repository().await;
+    let before_first_message = repository
+        .model_store()
+        .commit_write_plan(TableWritePlan::new(vec![upsert_table_mutation(true)]))
+        .await
+        .unwrap_err();
+    assert!(matches!(
+        before_first_message,
+        TableStoreError::CausalWriteRequired { ref table } if table == "todo_views"
+    ));
+    repository
+        .commit_projection(batch(
+            input(
+                1,
+                b"claim",
+                "message-1",
+                "cause-1",
+                ProjectionGeneration::initial(),
+            ),
+            vec![mutation(
+                ProjectionRecordExpectation::Missing,
+                ProjectionMutationKind::Upsert,
+            )],
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+
+    let direct = repository
+        .commit_write_plan(TableWritePlan::new(vec![upsert_table_mutation(true)]))
+        .await
+        .unwrap_err();
+    assert!(matches!(
+        direct,
+        TableStoreError::CausalWriteRequired { ref table } if table == "todo_views"
+    ));
+    let bare_handle = repository
+        .model_store()
+        .commit_write_plan(TableWritePlan::new(vec![upsert_table_mutation(true)]))
+        .await
+        .unwrap_err();
+    assert!(matches!(
+        bare_handle,
+        TableStoreError::CausalWriteRequired { ref table } if table == "todo_views"
+    ));
+
+    let mut raw_batch = CommitBatch::empty();
+    raw_batch
+        .read_model_plans
+        .push(TableWritePlan::new(vec![upsert_table_mutation(true)]));
+    let transactional = repository.commit_batch(raw_batch).await.unwrap_err();
+    assert!(matches!(
+        transactional,
+        RepositoryError::CausalWriteRequired { ref table } if table == "todo_views"
+    ));
+}
diff --git a/src/in_memory_repo/projection_protocol/util.rs b/src/in_memory_repo/projection_protocol/util.rs
new file mode 100644
index 00000000..6a4586aa
--- /dev/null
+++ b/src/in_memory_repo/projection_protocol/util.rs
@@ -0,0 +1,30 @@
+pub(super) fn storage_key_belongs_to_table(storage_key: &str, table: &str) -> bool {
+    let Some(mut fingerprint) = storage_key
+        .strip_prefix(table)
+        .and_then(|suffix| suffix.strip_prefix(':'))
+    else {
+        return false;
+    };
+    if fingerprint.is_empty() {
+        return false;
+    }
+    while !fingerprint.is_empty() {
+        let Some(length_end) = fingerprint.find(':') else {
+            return false;
+        };
+        let Ok(part_length) = fingerprint[..length_end].parse::<usize>() else {
+            return false;
+        };
+        let part_start = length_end + 1;
+        let Some(part_end) = part_start.checked_add(part_length) else {
+            return false;
+        };
+        if fingerprint.as_bytes().get(part_end) != Some(&b';')
+            || !fingerprint.is_char_boundary(part_end + 1)
+        {
+            return false;
+        }
+        fingerprint = &fingerprint[part_end + 1..];
+    }
+    true
+}
diff --git a/src/in_memory_repo/repository.rs b/src/in_memory_repo/repository.rs
index e4e8f7a5..94498c50 100644
--- a/src/in_memory_repo/repository.rs
+++ b/src/in_memory_repo/repository.rs
@@ -6,9 +6,22 @@
 use std::collections::{HashMap, HashSet};
 use std::future::Future;
 use std::sync::{Arc, RwLock};
+use std::time::SystemTime;
 
+use super::projection_protocol::{
+    reject_causal_owned_plans, stage_same_transaction_projection, InMemoryProjectionProtocolState,
+};
+use crate::command_ledger::{
+    AttemptFence, CausalCommitBatch, CausalGetStream, CausalRepositoryIdentity,
+    CausalStorageIdentity, CausalTransactionalCommit, CommandCompletion, CommandLedgerError,
+    CommandLedgerKey, CommandLedgerRecord, CommandLedgerStore, CommandLookup, CommandLookupScope,
+    CommandReservation, ReservationDecision, ReservationOutcome,
+};
 use crate::entity::{Entity, EventRecord};
 use crate::outbox::OutboxMessage;
+use crate::projection_protocol::{
+    ProjectionChangeRetention, ProjectionProtocolError, SameTransactionProjectionBatch,
+};
 use crate::read_model::in_memory::apply_read_model_write_plan;
 use crate::read_model::{
     InMemoryReadModelStore, ReadModelLoadGraph, ReadModelLoadRequest, ReadModelQueryCapabilities,
@@ -34,7 +47,7 @@ use crate::table::{TableAdapterCapabilities, TableCommitOutcome, TableStoreError
 pub struct InMemoryRepository {
     event_store: Arc<RwLock<HashMap<String, Vec<EventRecord>>>>,
     outbox_store: Arc<RwLock<HashMap<String, OutboxMessage>>>,
-    model_store: InMemoryReadModelStore,
+    pub(super) model_store: InMemoryReadModelStore,
     snapshot_store: InMemorySnapshotStore,
     /// Consumer inbox: the set of recorded `(consumer, message_id)` receipts.
     ///
@@ -43,7 +56,13 @@ pub struct InMemoryRepository {
     /// local development, not production effectively-once dedup — back a real
     /// deployment with the Postgres or SQLite inbox, which support
     /// [`purge_inbox_older_than`](crate::repository::InboxStore::purge_inbox_older_than).
-    inbox_store: Arc<RwLock<HashSet<(String, String)>>>,
+    pub(super) inbox_store: Arc<RwLock<HashSet<(String, String)>>>,
+    command_ledger: Arc<RwLock<HashMap<CommandLedgerKey, CommandLedgerRecord>>>,
+    pub(super) projection_protocol: Arc<RwLock<InMemoryProjectionProtocolState>>,
+    pub(super) causal_tables: Arc<RwLock<HashSet<String>>>,
+    pub(super) projection_change_retention: ProjectionChangeRetention,
+    #[cfg_attr(not(feature = "graphql"), allow(dead_code))]
+    causal_storage_identity: CausalStorageIdentity,
 }
 
 /// In-memory outbox table handle.
@@ -61,15 +80,41 @@ impl Default for InMemoryRepository {
 impl InMemoryRepository {
     /// Create a new empty repository.
     pub fn new() -> Self {
+        let causal_tables = Arc::new(RwLock::new(HashSet::new()));
         InMemoryRepository {
             event_store: Arc::new(RwLock::new(HashMap::new())),
             outbox_store: Arc::new(RwLock::new(HashMap::new())),
-            model_store: InMemoryReadModelStore::new(),
+            model_store: InMemoryReadModelStore::with_causal_table_marker(Arc::clone(
+                &causal_tables,
+            )),
             snapshot_store: InMemorySnapshotStore::new(),
             inbox_store: Arc::new(RwLock::new(HashSet::new())),
+            command_ledger: Arc::new(RwLock::new(HashMap::new())),
+            projection_protocol: Arc::new(RwLock::new(InMemoryProjectionProtocolState::default())),
+            causal_tables,
+            projection_change_retention: ProjectionChangeRetention::default(),
+            causal_storage_identity: CausalStorageIdentity::new(),
         }
     }
 
+    /// Configure the maximum newest projection changes retained per partition.
+    ///
+    /// The persisted compacted-through watermark remains authoritative when
+    /// this value is lengthened; previously compacted changes are never
+    /// advertised as restored.
+    pub fn with_projection_change_retention(
+        mut self,
+        retention: ProjectionChangeRetention,
+    ) -> Self {
+        self.projection_change_retention = retention;
+        self
+    }
+
+    #[cfg(test)]
+    pub(crate) fn causal_storage_identity(&self) -> CausalStorageIdentity {
+        self.causal_storage_identity
+    }
+
     #[cfg(test)]
     pub(crate) fn outbox_storage(&self) -> &RwLock<HashMap<String, OutboxMessage>> {
         self.outbox_store.as_ref()
@@ -117,6 +162,280 @@ impl InMemoryRepository {
     }
 }
 
+enum InMemoryCommitError {
+    Repository(RepositoryError),
+    Ledger(CommandLedgerError),
+    Projection(ProjectionProtocolError),
+}
+
+impl From<RepositoryError> for InMemoryCommitError {
+    fn from(error: RepositoryError) -> Self {
+        Self::Repository(error)
+    }
+}
+
+impl From<CommandLedgerError> for InMemoryCommitError {
+    fn from(error: CommandLedgerError) -> Self {
+        Self::Ledger(error)
+    }
+}
+
+impl From<TableStoreError> for InMemoryCommitError {
+    fn from(error: TableStoreError) -> Self {
+        Self::Repository(RepositoryError::from(error))
+    }
+}
+
+impl From<ProjectionProtocolError> for InMemoryCommitError {
+    fn from(error: ProjectionProtocolError) -> Self {
+        Self::Projection(error)
+    }
+}
+
+impl InMemoryRepository {
+    fn commit_batch_inner<'a>(
+        &'a self,
+        batch: CommitBatch<'a>,
+        mut completion: Option<CommandCompletion>,
+        direct_projection: Option<SameTransactionProjectionBatch>,
+    ) -> Result<(), InMemoryCommitError> {
+        let prepared = validate_commit_batch(&batch)?;
+        if let Some(direct_projection) = &direct_projection {
+            direct_projection.validate()?;
+            let completion = completion.as_ref().ok_or_else(|| {
+                CommandLedgerError::Invalid(
+                    "same-transaction direct projection requires a command completion".into(),
+                )
+            })?;
+            if direct_projection.causation_id != completion.attempt().causation_id().as_str() {
+                return Err(CommandLedgerError::Invalid(
+                    "direct projection causation differs from its command attempt".into(),
+                )
+                .into());
+            }
+        }
+
+        // All-or-nothing without cloning whole stores: every fallible check
+        // below runs against live maps or a batch-bounded staging copy. The
+        // ledger guard is deliberately acquired last to preserve one global
+        // lock order, then its exact attempt fence is validated before any
+        // durable map is mutated.
+        let mut storage = self
+            .event_store
+            .write()
+            .map_err(|_| RepositoryError::LockPoisoned("async stream write"))?;
+        let mut relational_rows = self
+            .model_store
+            .relational_rows
+            .write()
+            .map_err(|_| RepositoryError::LockPoisoned("async read model write"))?;
+        let causal_tables = self
+            .causal_tables
+            .read()
+            .map_err(|_| RepositoryError::LockPoisoned("projection ownership read"))?;
+        reject_causal_owned_plans(&causal_tables, &batch.read_model_plans)?;
+        if let Some(unregistered) = direct_projection.as_ref().and_then(|direct| {
+            direct
+                .mutations
+                .iter()
+                .map(|mutation| mutation.mutation.table_name())
+                .find(|table| !causal_tables.contains(*table))
+        }) {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "direct projection table `{unregistered}` is not registered as causal-owned"
+            ))
+            .into());
+        }
+        let mut protocol = direct_projection
+            .as_ref()
+            .map(|_| {
+                self.projection_protocol
+                    .write()
+                    .map_err(|_| RepositoryError::LockPoisoned("direct projection protocol write"))
+            })
+            .transpose()?;
+        let mut snapshot_storage = self
+            .snapshot_store
+            .storage
+            .write()
+            .map_err(|_| RepositoryError::LockPoisoned("async snapshot write"))?;
+        let mut outbox_storage = self
+            .outbox_store
+            .write()
+            .map_err(|_| RepositoryError::LockPoisoned("async outbox write"))?;
+        let mut inbox_storage = self
+            .inbox_store
+            .write()
+            .map_err(|_| RepositoryError::LockPoisoned("async inbox write"))?;
+        let mut ledger_storage = completion
+            .as_ref()
+            .map(|_| {
+                self.command_ledger
+                    .write()
+                    .map_err(|_| RepositoryError::LockPoisoned("command ledger write"))
+            })
+            .transpose()?;
+
+        // Match the SQL adapter's precedence: once every store lock is held,
+        // reject a stale/expired command attempt before inspecting projection
+        // tombstones, row drift, or any other domain participant. The final
+        // staged completion below repeats this fence at the atomic boundary.
+        if let Some(completion) = completion.as_ref() {
+            let record = ledger_storage
+                .as_ref()
+                .and_then(|ledger| ledger.get(completion.attempt().key()))
+                .ok_or_else(|| CommandLedgerError::AttemptFenced {
+                    command_id: completion.attempt().key().command_id().to_string(),
+                })?;
+            record.validate_live_attempt(&completion.attempt_fence(), SystemTime::now())?;
+        }
+
+        // Events: optimistic-concurrency check (reads only; appends cannot
+        // fail once every stream passed).
+        for append in &prepared {
+            let stored_len = stored_stream_version(storage.get(&append.identity.storage_key()));
+            if stored_len != append.expected_version {
+                return Err(RepositoryError::ConcurrentWrite {
+                    id: append.identity.to_string(),
+                    expected: append.expected_version,
+                    actual: stored_len,
+                }
+                .into());
+            }
+        }
+
+        // Read models can fail mid-application, so stage only touched rows.
+        let mut touched_rows: HashSet<String> = batch
+            .read_model_plans
+            .iter()
+            .flat_map(|plan| plan.mutations.iter().map(|mutation| mutation.lock_key()))
+            .collect();
+        if let Some(direct_projection) = &direct_projection {
+            touched_rows.extend(
+                direct_projection
+                    .mutations
+                    .iter()
+                    .map(|mutation| mutation.mutation.lock_key()),
+            );
+        }
+        let mut staged_rows = HashMap::with_capacity(touched_rows.len());
+        for key in &touched_rows {
+            if let Some(row) = relational_rows.get(key) {
+                staged_rows.insert(key.clone(), row.clone());
+            }
+        }
+        for plan in batch.read_model_plans.iter().cloned() {
+            apply_read_model_write_plan(plan, &mut staged_rows)?;
+        }
+        let mut staged_protocol = protocol.as_deref().cloned();
+        let direct_evidence = match (&mut staged_protocol, &direct_projection) {
+            (Some(staged_protocol), Some(direct_projection)) => {
+                Some(stage_same_transaction_projection(
+                    staged_protocol,
+                    &mut staged_rows,
+                    direct_projection,
+                    self.projection_change_retention,
+                )?)
+            }
+            (None, None) => None,
+            _ => unreachable!("direct projection protocol state is acquired with its batch"),
+        };
+        if let (Some(completion), Some(evidence)) = (&mut completion, &direct_evidence) {
+            completion.attach_direct_projection(evidence)?;
+        }
+        debug_assert!(
+            staged_rows.keys().all(|key| touched_rows.contains(key)),
+            "read model plan wrote a row outside its mutations' lock keys"
+        );
+
+        for message in &batch.outbox_messages {
+            if outbox_storage.contains_key(message.id()) {
+                return Err(RepositoryError::DuplicateOutboxMessageInBatch {
+                    id: message.id().to_string(),
+                }
+                .into());
+            }
+        }
+
+        let mut batch_receipts = HashSet::with_capacity(batch.inbox_receipts.len());
+        for receipt in &batch.inbox_receipts {
+            receipt.validate()?;
+            let key = (receipt.consumer.as_str(), receipt.message_id.as_str());
+            if inbox_storage.contains(&(receipt.consumer.clone(), receipt.message_id.clone()))
+                || !batch_receipts.insert(key)
+            {
+                return Err(RepositoryError::DuplicateInboxReceipt {
+                    consumer: receipt.consumer.clone(),
+                    message_id: receipt.message_id.clone(),
+                }
+                .into());
+            }
+        }
+
+        // Stage the terminal row only after every other fallible validation so
+        // its live-lease check is as close as possible to the atomic mutation
+        // boundary. The staged row remains hidden; assigning it to the held
+        // ledger map is the final mutation below.
+        let staged_ledger_record = completion
+            .as_ref()
+            .map(|completion| {
+                let record = ledger_storage
+                    .as_ref()
+                    .and_then(|ledger| ledger.get(completion.attempt().key()))
+                    .ok_or_else(|| CommandLedgerError::AttemptFenced {
+                        command_id: completion.attempt().key().command_id().to_string(),
+                    })?;
+                let mut staged = record.clone();
+                staged.complete(completion, SystemTime::now())?;
+                Ok::<_, CommandLedgerError>(staged)
+            })
+            .transpose()?;
+
+        // Nothing below can fail: mutate the live stores.
+        for append in prepared {
+            storage
+                .entry(append.identity.storage_key())
+                .or_insert_with(Vec::new)
+                .extend_from_slice(append.events);
+        }
+        for key in touched_rows {
+            match staged_rows.remove(&key) {
+                Some(row) => {
+                    relational_rows.insert(key, row);
+                }
+                None => {
+                    relational_rows.remove(&key);
+                }
+            }
+        }
+        for write in batch.snapshots {
+            match write {
+                SnapshotWrite::Save { identity, record } => {
+                    snapshot_storage.insert(identity.storage_key(), record);
+                }
+            }
+        }
+        for message in batch.outbox_messages {
+            outbox_storage.insert(message.id().to_string(), message);
+        }
+        for receipt in batch.inbox_receipts {
+            inbox_storage.insert((receipt.consumer, receipt.message_id));
+        }
+        for stream in batch.streams {
+            stream.entity.mark_committed();
+        }
+
+        if let (Some(protocol), Some(staged_protocol)) = (protocol.as_deref_mut(), staged_protocol)
+        {
+            *protocol = staged_protocol;
+        }
+        if let (Some(ledger), Some(record)) = (ledger_storage.as_mut(), staged_ledger_record) {
+            ledger.insert(record.key.clone(), record);
+        }
+        Ok(())
+    }
+}
+
 impl GetStream for InMemoryRepository {
     fn get_stream<'a>(
         &'a self,
@@ -140,148 +459,190 @@ impl GetStream for InMemoryRepository {
     }
 }
 
-impl TransactionalCommit for InMemoryRepository {
-    fn commit_batch<'a>(
+impl CausalGetStream for InMemoryRepository {
+    fn get_causal_stream<'a>(
         &'a self,
-        batch: CommitBatch<'a>,
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-        async move {
-            let prepared = validate_commit_batch(&batch)?;
+        identity: &'a StreamIdentity,
+    ) -> impl Future<Output = Result<Option<Entity>, RepositoryError>> + Send + 'a {
+        GetStream::get_stream(self, identity)
+    }
+}
 
-            // All-or-nothing without cloning the stores: every fallible check
-            // below runs against the live maps (reads) or a staging copy scoped
-            // to the rows this batch touches, and the live maps are only mutated
-            // once nothing can fail. All five write guards are held throughout so
-            // the batch stays atomic to readers.
-            let mut storage = self
-                .event_store
-                .write()
-                .map_err(|_| RepositoryError::LockPoisoned("async stream write"))?;
-            let mut relational_rows = self
-                .model_store
-                .relational_rows
-                .write()
-                .map_err(|_| RepositoryError::LockPoisoned("async read model write"))?;
-            let mut snapshot_storage = self
-                .snapshot_store
-                .storage
-                .write()
-                .map_err(|_| RepositoryError::LockPoisoned("async snapshot write"))?;
-            let mut outbox_storage = self
-                .outbox_store
-                .write()
-                .map_err(|_| RepositoryError::LockPoisoned("async outbox write"))?;
-            let mut inbox_storage = self
-                .inbox_store
-                .write()
-                .map_err(|_| RepositoryError::LockPoisoned("async inbox write"))?;
-
-            // Events: optimistic-concurrency check (reads only; appends cannot
-            // fail once every stream passed).
-            for append in &prepared {
-                let stored_len = stored_stream_version(storage.get(&append.identity.storage_key()));
-                if stored_len != append.expected_version {
-                    return Err(RepositoryError::ConcurrentWrite {
-                        id: append.identity.to_string(),
-                        expected: append.expected_version,
-                        actual: stored_len,
-                    });
-                }
-            }
+impl CausalRepositoryIdentity for InMemoryRepository {
+    fn causal_storage_identity(&self) -> CausalStorageIdentity {
+        self.causal_storage_identity
+    }
+}
 
-            // Read models: plans can fail mid-application, so apply them to a
-            // copy of only the rows they touch. Every touched storage key is
-            // known from the mutations up front (`lock_key` is the row's storage
-            // key), so the copy is bounded by the batch, not the store.
-            let touched_rows: HashSet<String> = batch
-                .read_model_plans
-                .iter()
-                .flat_map(|plan| plan.mutations.iter().map(|mutation| mutation.lock_key()))
-                .collect();
-            let mut staged_rows = HashMap::with_capacity(touched_rows.len());
-            for key in &touched_rows {
-                if let Some(row) = relational_rows.get(key) {
-                    staged_rows.insert(key.clone(), row.clone());
+impl CommandLedgerStore for InMemoryRepository {
+    fn reserve_command(
+        &self,
+        reservation: CommandReservation,
+    ) -> impl Future<Output = Result<ReservationOutcome, CommandLedgerError>> + Send + '_ {
+        async move {
+            let now = SystemTime::now();
+            let mut ledger = self
+                .command_ledger
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("command ledger reserve"))?;
+
+            match ledger.entry(reservation.key().clone()) {
+                std::collections::hash_map::Entry::Vacant(entry) => {
+                    let record = CommandLedgerRecord::initial(&reservation, now)?;
+                    let outcome = ReservationOutcome::Acquired(record.acquired_attempt()?);
+                    entry.insert(record);
+                    Ok(outcome)
                 }
-            }
-            // Clone plans: `prepared` borrows `batch` through the append loop
-            // below, so `batch.read_model_plans` cannot be moved out here.
-            for plan in batch.read_model_plans.iter().cloned() {
-                apply_read_model_write_plan(plan, &mut staged_rows)?;
-            }
-            debug_assert!(
-                staged_rows.keys().all(|key| touched_rows.contains(key)),
-                "read model plan wrote a row outside its mutations' lock keys"
-            );
-
-            // Outbox: duplicates against the store (intra-batch duplicates were
-            // rejected above).
-            for message in &batch.outbox_messages {
-                if outbox_storage.contains_key(message.id()) {
-                    return Err(RepositoryError::DuplicateOutboxMessageInBatch {
-                        id: message.id().to_string(),
-                    });
+                std::collections::hash_map::Entry::Occupied(mut entry) => {
+                    let decision = entry.get().classify_reservation(&reservation, now)?;
+                    match decision {
+                        ReservationDecision::Expire => {
+                            entry.get_mut().expire(now);
+                            Ok(ReservationOutcome::Expired)
+                        }
+                        ReservationDecision::Reclaim => {
+                            entry.get_mut().reclaim(&reservation, now)?;
+                            entry.get().reservation_outcome(decision)
+                        }
+                        other => entry.get().reservation_outcome(other),
+                    }
                 }
             }
+        }
+    }
 
-            // Inbox receipts gate effectively-once: a receipt that already exists
-            // (committed or duplicated in this batch) rolls the whole batch back
-            // so effects are not double-applied.
-            let mut batch_receipts = HashSet::with_capacity(batch.inbox_receipts.len());
-            for receipt in &batch.inbox_receipts {
-                receipt.validate()?;
-                let key = (receipt.consumer.as_str(), receipt.message_id.as_str());
-                if inbox_storage.contains(&(receipt.consumer.clone(), receipt.message_id.clone()))
-                    || !batch_receipts.insert(key)
-                {
-                    return Err(RepositoryError::DuplicateInboxReceipt {
-                        consumer: receipt.consumer.clone(),
-                        message_id: receipt.message_id.clone(),
-                    });
-                }
+    fn lookup_command<'a>(
+        &'a self,
+        key: &'a CommandLedgerKey,
+        scope: CommandLookupScope<'a>,
+    ) -> impl Future<Output = Result<CommandLookup, CommandLedgerError>> + Send + 'a {
+        async move {
+            let now = SystemTime::now();
+            let mut ledger = self
+                .command_ledger
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("command ledger lookup"))?;
+            let Some(record) = ledger.get_mut(key) else {
+                return Ok(CommandLookup::Unknown);
+            };
+            if !record.matches_lookup_scope(scope) {
+                return Ok(CommandLookup::Unknown);
             }
-            drop(batch_receipts);
-
-            // Nothing below can fail: mutate the live stores.
-            for append in prepared {
-                storage
-                    .entry(append.identity.storage_key())
-                    .or_insert_with(Vec::new)
-                    .extend_from_slice(append.events);
+            if record.state != crate::command_ledger::CommandLedgerState::Expired
+                && record.retention_expires_at <= now
+            {
+                record.expire(now);
             }
+            record.lookup()
+        }
+    }
 
-            for key in touched_rows {
-                match staged_rows.remove(&key) {
-                    Some(row) => {
-                        relational_rows.insert(key, row);
-                    }
-                    None => {
-                        relational_rows.remove(&key);
-                    }
-                }
-            }
+    fn mark_retryable_unknown(
+        &self,
+        attempt: AttemptFence,
+    ) -> impl Future<Output = Result<(), CommandLedgerError>> + Send + '_ {
+        async move {
+            let mut ledger = self
+                .command_ledger
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("command ledger retryable update"))?;
+            let record =
+                ledger
+                    .get_mut(attempt.key())
+                    .ok_or_else(|| CommandLedgerError::AttemptFenced {
+                        command_id: attempt.key().command_id().to_string(),
+                    })?;
+            record.mark_retryable_unknown(&attempt, SystemTime::now())
+        }
+    }
 
-            for write in batch.snapshots {
-                match write {
-                    SnapshotWrite::Save { identity, record } => {
-                        snapshot_storage.insert(identity.storage_key(), record);
-                    }
-                }
+    fn compact_expired_commands(
+        &self,
+        limit: usize,
+    ) -> impl Future<Output = Result<u64, CommandLedgerError>> + Send + '_ {
+        async move {
+            if limit == 0 {
+                return Ok(0);
             }
-
-            for message in batch.outbox_messages {
-                outbox_storage.insert(message.id().to_string(), message);
+            let now = SystemTime::now();
+            let mut ledger = self
+                .command_ledger
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("command ledger compaction"))?;
+            let mut candidates = ledger
+                .iter()
+                .filter(|(_, record)| {
+                    record.state != crate::command_ledger::CommandLedgerState::Expired
+                        && record.retention_expires_at <= now
+                })
+                .map(|(key, record)| (record.retention_expires_at, key.clone()))
+                .collect::<Vec<_>>();
+            candidates.sort_by(|left, right| {
+                left.0.cmp(&right.0).then_with(|| {
+                    left.1
+                        .service_id()
+                        .cmp(right.1.service_id())
+                        .then_with(|| {
+                            left.1
+                                .principal_partition()
+                                .cmp(right.1.principal_partition())
+                        })
+                        .then_with(|| left.1.command_id().cmp(right.1.command_id()))
+                })
+            });
+
+            let mut compacted = 0;
+            for (_, key) in candidates.into_iter().take(limit) {
+                if let Some(record) = ledger.get_mut(&key) {
+                    record.expire(now);
+                    compacted += 1;
+                }
             }
+            Ok(compacted)
+        }
+    }
+}
 
-            for receipt in batch.inbox_receipts {
-                inbox_storage.insert((receipt.consumer, receipt.message_id));
+impl TransactionalCommit for InMemoryRepository {
+    fn commit_batch<'a>(
+        &'a self,
+        batch: CommitBatch<'a>,
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+        async move {
+            match self.commit_batch_inner(batch, None, None) {
+                Ok(()) => Ok(()),
+                Err(InMemoryCommitError::Repository(error)) => Err(error),
+                Err(InMemoryCommitError::Ledger(error)) => Err(RepositoryError::Model(format!(
+                    "unexpected command ledger error in ordinary commit: {error}"
+                ))),
+                Err(InMemoryCommitError::Projection(error)) => Err(RepositoryError::Model(
+                    format!("unexpected projection protocol error in ordinary commit: {error}"),
+                )),
             }
+        }
+    }
+}
 
-            for stream in batch.streams {
-                stream.entity.mark_committed();
+impl CausalTransactionalCommit for InMemoryRepository {
+    fn commit_causal_batch<'a>(
+        &'a self,
+        batch: CausalCommitBatch<'a>,
+    ) -> impl Future<Output = Result<(), CommandLedgerError>> + Send + 'a {
+        async move {
+            match self.commit_batch_inner(
+                batch.domain,
+                Some(batch.completion),
+                batch.direct_projection,
+            ) {
+                Ok(()) => Ok(()),
+                Err(InMemoryCommitError::Repository(error)) => {
+                    Err(CommandLedgerError::Storage(error))
+                }
+                Err(InMemoryCommitError::Ledger(error)) => Err(error),
+                Err(InMemoryCommitError::Projection(error)) => Err(CommandLedgerError::Storage(
+                    RepositoryError::Model(error.to_string()),
+                )),
             }
-
-            Ok(())
         }
     }
 }
diff --git a/src/lib.rs b/src/lib.rs
index d6a0112c..8a1de15c 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,17 @@
 #![allow(clippy::module_inception)]
 #![doc = include_str!("../README.md")]
+// Projection + GraphQL client surfaces always compile (dctl / shared types), but many
+// call sites live behind optional features. Without those features rustc reports
+// false "never used" warnings for the protocol store helpers. CI builds with features.
+#![cfg_attr(
+    not(any(
+        feature = "graphql",
+        feature = "sqlite",
+        feature = "postgres",
+        test
+    )),
+    allow(dead_code)
+)]
 
 // Allow proc-macros to reference this crate by name even when used internally
 extern crate self as distributed;
@@ -9,9 +21,11 @@ pub mod bus;
 pub mod entity;
 pub mod repository;
 
+pub(crate) mod command_ledger;
 mod commit_builder;
 #[cfg(feature = "emitter")]
 pub mod emitter;
+pub mod graphql;
 mod in_memory_repo;
 pub mod lock;
 pub mod manifest;
@@ -22,6 +36,7 @@ pub mod outbox;
 pub mod outbox_worker;
 #[cfg(feature = "postgres")]
 pub mod postgres_repo;
+pub mod projection_protocol;
 pub mod queued_repo;
 pub mod read_model;
 pub mod snapshot;
@@ -108,8 +123,8 @@ pub use queued_repo::{
 // workspace/plan entry points, and the version marker. Load-graph, query, and
 // row-include plumbing stays reachable under `distributed::read_model::*`.
 pub use read_model::{
-    InMemoryReadModelStore, ReadModel, ReadModelWorkspaceExt, ReadModelWritePlanBuilder,
-    RelationalReadModel, RelationalReadModelIncludes, Versioned,
+    InMemoryReadModelStore, ReadModel, ReadModelChange, ReadModelWorkspaceExt,
+    ReadModelWritePlanBuilder, RelationalReadModel, RelationalReadModelIncludes, Versioned,
 };
 
 // Neutral table/row primitives: the canonical schema, row, mutation, write-plan,
@@ -121,10 +136,10 @@ pub use table::{
     ColumnType, DeleteTableRowMutation, ExpectedVersion, ForeignKey, PatchMode,
     PatchTableRowMutation, PrimaryKey, RelationshipDef, RelationshipKind, RowKey, RowPatch,
     RowValue, RowValues, RowWriteMode, TableAdapterCapabilities, TableColumn, TableCommitOutcome,
-    TableIndex, TableMigrationArtifact, TableModel, TableMutation, TableRowMutation, TableSchema,
-    TableSchemaAdapter, TableSchemaAdapterCapabilities, TableSchemaBootstrap, TableSchemaIssue,
-    TableSchemaIssueKind, TableSchemaRegistry, TableSchemaRegistryExt, TableSchemaVerification,
-    TableStoreError, TableWritePlan, DEFAULT_TABLE_VERSION_COLUMN,
+    TableIndex, TableKind, TableMigrationArtifact, TableModel, TableMutation, TableRowMutation,
+    TableSchema, TableSchemaAdapter, TableSchemaAdapterCapabilities, TableSchemaBootstrap,
+    TableSchemaIssue, TableSchemaIssueKind, TableSchemaRegistry, TableSchemaRegistryExt,
+    TableSchemaVerification, TableStoreError, TableWritePlan, DEFAULT_TABLE_VERSION_COLUMN,
 };
 
 pub use manifest::{
@@ -148,8 +163,27 @@ pub use snapshot::{hydrate_from_snapshot, InMemorySnapshotStore, SnapshotRecord,
 #[cfg(feature = "emitter")]
 pub use event_emitter_rs::EventEmitter;
 
+/// Register read models + permissions on a GraphQL engine builder.
+///
+/// ```ignore
+/// let builder = graphql_models!(builder, orders, players);
+/// // expands to builder.model::<orders::Model>(orders::permissions())...
+/// ```
+#[macro_export]
+macro_rules! graphql_models {
+    ($builder:expr, $($m:ident),+ $(,)?) => {
+        $builder $( .model::<$m::Model>($m::permissions()) )+
+    };
+}
+
+// Session convenience re-exports used by GraphQL permission filters.
+pub use microsvc::{ROLE_KEY, USER_ID_KEY};
+
 // Re-export proc macros
-pub use distributed_macros::{aggregate, digest, sourced, ReadModel, Snapshot};
+pub use distributed_macros::{
+    aggregate, command_confirmations, command_effects, command_input_defaults, digest, sourced,
+    GraphqlInput, GraphqlOutput, ReadModel, Snapshot,
+};
 
 // Re-export enqueue macro (requires "emitter" feature)
 #[cfg(feature = "emitter")]
diff --git a/src/manifest.rs b/src/manifest.rs
index 5a5f1065..75360766 100644
--- a/src/manifest.rs
+++ b/src/manifest.rs
@@ -111,6 +111,12 @@ impl DistributedProjectManifest {
     pub fn envelope(self) -> DistributedManifestEnvelope {
         DistributedManifestEnvelope::new(self)
     }
+
+    /// Render the dialect-independent GraphQL SDL artifact for all
+    /// [`TableKind::ReadModel`] tables in this manifest.
+    pub fn graphql_sdl(&self) -> Result<String, String> {
+        crate::graphql::graphql_sdl_for_tables(&self.tables)
+    }
 }
 
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
diff --git a/src/metrics.rs b/src/metrics.rs
deleted file mode 100644
index 799b5401..00000000
--- a/src/metrics.rs
+++ /dev/null
@@ -1,1071 +0,0 @@
-//! Prometheus-compatible framework metrics.
-//!
-//! This module intentionally has no SDK dependency. It records the framework
-//! counters and gauges Distributed owns, then renders Prometheus text exposition
-//! for HTTP scrape endpoints.
-
-use std::collections::BTreeMap;
-use std::sync::{Mutex, MutexGuard as StdMutexGuard, OnceLock};
-use std::time::Duration;
-
-use crate::bus::MessageKind;
-use crate::telemetry::{metric_labels, metric_names, service_label};
-
-#[cfg(feature = "http")]
-const PROMETHEUS_TEXT_CONTENT_TYPE: &str = "text/plain; version=0.0.4; charset=utf-8";
-const HISTOGRAM_BUCKETS: [f64; 11] = [
-    0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0,
-];
-const SERVICE_INFO_FAMILY: MetricFamily = MetricFamily::gauge(
-    metric_names::SERVICE_INFO,
-    "Static Distributed service metadata.",
-);
-const MICROSVC_DISPATCH_TOTAL_FAMILY: MetricFamily = MetricFamily::counter(
-    metric_names::MICROSVC_DISPATCH_TOTAL,
-    "Total microsvc dispatches by service, message kind, message, and status.",
-);
-const MICROSVC_DISPATCH_DURATION_FAMILY: MetricFamily = MetricFamily::histogram(
-    metric_names::MICROSVC_DISPATCH_DURATION_SECONDS,
-    "Microsvc dispatch duration in seconds.",
-);
-const TRANSPORT_MESSAGES_TOTAL_FAMILY: MetricFamily = MetricFamily::counter(
-    metric_names::TRANSPORT_MESSAGES_TOTAL,
-    "Total transport receive/settle outcomes.",
-);
-const TRANSPORT_FAILURES_TOTAL_FAMILY: MetricFamily = MetricFamily::counter(
-    metric_names::TRANSPORT_FAILURES_TOTAL,
-    "Total transport failures by class and chosen action.",
-);
-const OUTBOX_MESSAGES_TOTAL_FAMILY: MetricFamily = MetricFamily::counter(
-    metric_names::OUTBOX_MESSAGES_TOTAL,
-    "Total outbox publish outcomes.",
-);
-const OUTBOX_PENDING_MESSAGES_FAMILY: MetricFamily = MetricFamily::gauge(
-    metric_names::OUTBOX_PENDING_MESSAGES,
-    "Pending outbox message count.",
-);
-const OUTBOX_OLDEST_PENDING_AGE_FAMILY: MetricFamily = MetricFamily::gauge(
-    metric_names::OUTBOX_OLDEST_PENDING_AGE_SECONDS,
-    "Age in seconds of the oldest pending outbox message.",
-);
-
-static REGISTRY: OnceLock<MetricsRegistry> = OnceLock::new();
-
-#[cfg(test)]
-static TEST_LOCK: OnceLock<tokio::sync::Mutex<()>> = OnceLock::new();
-
-/// Record that a service exists so `/metrics` exposes a stable info series even
-/// before the first request.
-pub fn describe_service(service: Option<&str>) {
-    registry().describe_service(service_label(service));
-}
-
-/// Record one microsvc command/event dispatch result.
-pub fn record_microsvc_dispatch(
-    service: Option<&str>,
-    kind: MessageKind,
-    message: &str,
-    status: &str,
-    duration: Duration,
-) {
-    registry().record_microsvc_dispatch(DispatchKey {
-        service: service_label(service),
-        message_kind: kind.as_str().to_string(),
-        message: message.to_string(),
-        status: status.to_string(),
-        duration_seconds: duration.as_secs_f64(),
-    });
-}
-
-/// Record a transport receive/settle outcome.
-pub fn record_transport_message(
-    service: Option<&str>,
-    transport: &str,
-    kind: MessageKind,
-    outcome: &str,
-) {
-    registry().record_transport_message(TransportMessageKey {
-        service: service_label(service),
-        transport: transport.to_string(),
-        message_kind: kind.as_str().to_string(),
-        outcome: outcome.to_string(),
-    });
-}
-
-/// Record a classified transport failure and the action chosen for it.
-pub fn record_transport_failure(
-    service: Option<&str>,
-    transport: &str,
-    failure_class: &str,
-    action: &str,
-) {
-    registry().record_transport_failure(TransportFailureKey {
-        service: service_label(service),
-        transport: transport.to_string(),
-        failure_class: failure_class.to_string(),
-        action: action.to_string(),
-    });
-}
-
-/// Record one outbox dispatch state transition.
-pub fn record_outbox_message(service: Option<&str>, outcome: &str) {
-    record_outbox_messages(service, outcome, 1);
-}
-
-/// Record `count` outbox dispatch state transitions that settled together.
-pub fn record_outbox_messages(service: Option<&str>, outcome: &str, count: usize) {
-    if count == 0 {
-        return;
-    }
-    registry().record_outbox_messages(
-        OutboxMessageKey {
-            service: service_label(service),
-            outcome: outcome.to_string(),
-        },
-        count as u64,
-    );
-}
-
-/// Set outbox backlog gauges for a service.
-pub fn set_outbox_backlog(
-    service: Option<&str>,
-    pending: usize,
-    oldest_pending_age: Option<Duration>,
-) {
-    registry().set_outbox_backlog(
-        service_label(service),
-        pending as f64,
-        oldest_pending_age.map(|duration| duration.as_secs_f64()),
-    );
-}
-
-/// Render all currently recorded metrics in Prometheus text exposition format.
-pub fn prometheus_text() -> String {
-    render_prometheus(&snapshot())
-}
-
-/// Return a lock-free snapshot of bounded framework metric families.
-///
-/// The snapshot contains only metric names, bounded label names/values, and
-/// numeric samples. It deliberately excludes payloads, message metadata, trace
-/// identifiers, aggregate identifiers, and request-specific data so future
-/// diagnostics can reuse it without widening the telemetry privacy surface.
-pub(crate) fn snapshot() -> MetricsSnapshot {
-    registry().snapshot()
-}
-
-/// Build an axum router that exposes only `GET /metrics`.
-///
-/// This is intended for workers and services whose primary transport is not
-/// HTTP. Run it on a small side port so Prometheus can scrape the same
-/// framework metrics that the bus/outbox/runtime paths record. The endpoint is
-/// unauthenticated; bind it only on a private listener or behind equivalent
-/// network controls.
-#[cfg(feature = "http")]
-pub fn http_router() -> axum::Router {
-    http_router_with_state(MetricsHttpState::default())
-}
-
-/// Build an axum router that exposes only `GET /metrics` and records a stable
-/// service label before each scrape.
-#[cfg(feature = "http")]
-pub fn http_router_for_service(service: impl Into<String>) -> axum::Router {
-    http_router_with_state(MetricsHttpState {
-        service: Some(service.into()),
-    })
-}
-
-/// Serve only the metrics scrape endpoint at the given address.
-///
-/// This helper is deliberately independent of `microsvc::http`, so a NATS,
-/// Kafka, RabbitMQ, or outbox worker can expose Prometheus metrics without
-/// exposing command dispatch over HTTP. The endpoint is unauthenticated; do not
-/// bind it on a public interface unless an ingress or network policy restricts
-/// access.
-#[cfg(feature = "http")]
-pub async fn serve_http(addr: &str, service: Option<&str>) -> Result<(), std::io::Error> {
-    let app = match service {
-        Some(service) => http_router_for_service(service),
-        None => http_router(),
-    };
-    let listener = tokio::net::TcpListener::bind(addr).await?;
-    axum::serve(listener, app).await
-}
-
-/// Return a Prometheus text response for HTTP handlers.
-#[cfg(feature = "http")]
-pub fn prometheus_response(service: Option<&str>) -> impl axum::response::IntoResponse {
-    describe_service(service);
-    (
-        [(
-            axum::http::header::CONTENT_TYPE,
-            PROMETHEUS_TEXT_CONTENT_TYPE,
-        )],
-        prometheus_text(),
-    )
-}
-
-#[cfg(test)]
-pub(crate) fn reset_for_tests() {
-    registry().reset();
-}
-
-#[cfg(test)]
-pub(crate) fn lock_for_tests() -> tokio::sync::MutexGuard<'static, ()> {
-    TEST_LOCK
-        .get_or_init(|| tokio::sync::Mutex::new(()))
-        .blocking_lock()
-}
-
-#[cfg(test)]
-pub(crate) async fn async_lock_for_tests() -> tokio::sync::MutexGuard<'static, ()> {
-    TEST_LOCK
-        .get_or_init(|| tokio::sync::Mutex::new(()))
-        .lock()
-        .await
-}
-
-fn registry() -> &'static MetricsRegistry {
-    REGISTRY.get_or_init(MetricsRegistry::default)
-}
-
-#[cfg(feature = "http")]
-#[derive(Clone, Default)]
-struct MetricsHttpState {
-    service: Option<String>,
-}
-
-#[cfg(feature = "http")]
-fn http_router_with_state(state: MetricsHttpState) -> axum::Router {
-    axum::Router::new()
-        .route("/metrics", axum::routing::get(metrics_http_handler))
-        .with_state(state)
-}
-
-#[cfg(feature = "http")]
-async fn metrics_http_handler(
-    axum::extract::State(state): axum::extract::State<MetricsHttpState>,
-) -> impl axum::response::IntoResponse {
-    prometheus_response(state.service.as_deref())
-}
-
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub(crate) struct MetricFamily {
-    pub(crate) name: &'static str,
-    help: &'static str,
-    kind: MetricKind,
-}
-
-impl MetricFamily {
-    const fn counter(name: &'static str, help: &'static str) -> Self {
-        Self {
-            name,
-            help,
-            kind: MetricKind::Counter,
-        }
-    }
-
-    const fn gauge(name: &'static str, help: &'static str) -> Self {
-        Self {
-            name,
-            help,
-            kind: MetricKind::Gauge,
-        }
-    }
-
-    const fn histogram(name: &'static str, help: &'static str) -> Self {
-        Self {
-            name,
-            help,
-            kind: MetricKind::Histogram,
-        }
-    }
-
-    fn snapshot(self, samples: Vec<MetricSample>) -> MetricFamilySnapshot {
-        MetricFamilySnapshot {
-            family: self,
-            samples,
-        }
-    }
-}
-
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-enum MetricKind {
-    Counter,
-    Gauge,
-    Histogram,
-}
-
-impl MetricKind {
-    fn as_prometheus_type(self) -> &'static str {
-        match self {
-            Self::Counter => "counter",
-            Self::Gauge => "gauge",
-            Self::Histogram => "histogram",
-        }
-    }
-}
-
-/// Lock-free, bounded snapshot of framework-owned metric families.
-#[derive(Clone, Debug)]
-pub(crate) struct MetricsSnapshot {
-    families: Vec<MetricFamilySnapshot>,
-}
-
-impl MetricsSnapshot {
-    pub(crate) fn families(&self) -> &[MetricFamilySnapshot] {
-        &self.families
-    }
-}
-
-#[derive(Clone, Debug)]
-pub(crate) struct MetricFamilySnapshot {
-    pub(crate) family: MetricFamily,
-    pub(crate) samples: Vec<MetricSample>,
-}
-
-#[derive(Clone, Debug)]
-pub(crate) struct MetricSample {
-    pub(crate) labels: Vec<(String, String)>,
-    pub(crate) value: MetricSampleValue,
-}
-
-impl MetricSample {
-    fn counter(labels: Vec<(String, String)>, value: u64) -> Self {
-        Self {
-            labels,
-            value: MetricSampleValue::Counter(value),
-        }
-    }
-
-    fn gauge(labels: Vec<(String, String)>, value: f64) -> Self {
-        Self {
-            labels,
-            value: MetricSampleValue::Gauge(value),
-        }
-    }
-
-    fn histogram(labels: Vec<(String, String)>, histogram: &Histogram) -> Self {
-        let buckets = HISTOGRAM_BUCKETS
-            .iter()
-            .zip(histogram.bucket_counts.iter())
-            .map(|(upper_bound, count)| HistogramBucketSnapshot {
-                upper_bound: *upper_bound,
-                count: *count,
-            })
-            .collect();
-        Self {
-            labels,
-            value: MetricSampleValue::Histogram(HistogramSnapshot {
-                buckets,
-                sum: histogram.sum,
-                count: histogram.count,
-            }),
-        }
-    }
-}
-
-#[derive(Clone, Debug)]
-pub(crate) enum MetricSampleValue {
-    Counter(u64),
-    Gauge(f64),
-    Histogram(HistogramSnapshot),
-}
-
-#[derive(Clone, Debug)]
-pub(crate) struct HistogramSnapshot {
-    pub(crate) buckets: Vec<HistogramBucketSnapshot>,
-    pub(crate) sum: f64,
-    pub(crate) count: u64,
-}
-
-#[derive(Clone, Debug)]
-pub(crate) struct HistogramBucketSnapshot {
-    pub(crate) upper_bound: f64,
-    pub(crate) count: u64,
-}
-
-#[derive(Default)]
-struct MetricsRegistry {
-    service_info: Mutex<BTreeMap<String, ()>>,
-    dispatch_total: Mutex<BTreeMap<DispatchCounterKey, u64>>,
-    dispatch_duration: Mutex<BTreeMap<DispatchHistogramKey, Histogram>>,
-    transport_messages_total: Mutex<BTreeMap<TransportMessageKey, u64>>,
-    transport_failures_total: Mutex<BTreeMap<TransportFailureKey, u64>>,
-    outbox_messages_total: Mutex<BTreeMap<OutboxMessageKey, u64>>,
-    outbox_pending_messages: Mutex<BTreeMap<String, f64>>,
-    outbox_oldest_pending_age_seconds: Mutex<BTreeMap<String, f64>>,
-}
-
-impl MetricsRegistry {
-    fn describe_service(&self, service: String) {
-        self.note_service(service);
-    }
-
-    fn record_microsvc_dispatch(&self, key: DispatchKey) {
-        let service = key.service.clone();
-        self.lock(&self.dispatch_total)
-            .entry(key.counter_key())
-            .and_modify(|value| *value += 1)
-            .or_insert(1);
-        self.lock(&self.dispatch_duration)
-            .entry(key.histogram_key())
-            .or_insert_with(Histogram::new)
-            .observe(key.duration_seconds);
-        self.note_service(service);
-    }
-
-    fn record_transport_message(&self, key: TransportMessageKey) {
-        let service = key.service.clone();
-        self.lock(&self.transport_messages_total)
-            .entry(key)
-            .and_modify(|value| *value += 1)
-            .or_insert(1);
-        self.note_service(service);
-    }
-
-    fn record_transport_failure(&self, key: TransportFailureKey) {
-        let service = key.service.clone();
-        self.lock(&self.transport_failures_total)
-            .entry(key)
-            .and_modify(|value| *value += 1)
-            .or_insert(1);
-        self.note_service(service);
-    }
-
-    fn record_outbox_messages(&self, key: OutboxMessageKey, count: u64) {
-        let service = key.service.clone();
-        self.lock(&self.outbox_messages_total)
-            .entry(key)
-            .and_modify(|value| *value += count)
-            .or_insert(count);
-        self.note_service(service);
-    }
-
-    fn set_outbox_backlog(&self, service: String, pending: f64, oldest_pending_age: Option<f64>) {
-        self.lock(&self.outbox_pending_messages)
-            .insert(service.clone(), pending);
-        if let Some(age) = oldest_pending_age {
-            self.lock(&self.outbox_oldest_pending_age_seconds)
-                .insert(service.clone(), age);
-        } else {
-            self.lock(&self.outbox_oldest_pending_age_seconds)
-                .remove(&service);
-        }
-        self.note_service(service);
-    }
-
-    fn snapshot(&self) -> MetricsSnapshot {
-        let service_info = self.clone_locked(&self.service_info);
-        let dispatch_total = self.clone_locked(&self.dispatch_total);
-        let dispatch_duration = self.clone_locked(&self.dispatch_duration);
-        let transport_messages_total = self.clone_locked(&self.transport_messages_total);
-        let transport_failures_total = self.clone_locked(&self.transport_failures_total);
-        let outbox_messages_total = self.clone_locked(&self.outbox_messages_total);
-        let outbox_pending_messages = self.clone_locked(&self.outbox_pending_messages);
-        let outbox_oldest_pending_age_seconds =
-            self.clone_locked(&self.outbox_oldest_pending_age_seconds);
-
-        MetricsSnapshot {
-            families: vec![
-                SERVICE_INFO_FAMILY.snapshot(
-                    service_info
-                        .keys()
-                        .map(|service| {
-                            MetricSample::gauge(
-                                vec![
-                                    (metric_labels::SERVICE.to_string(), service.clone()),
-                                    (
-                                        metric_labels::VERSION.to_string(),
-                                        env!("CARGO_PKG_VERSION").to_string(),
-                                    ),
-                                ],
-                                1.0,
-                            )
-                        })
-                        .collect(),
-                ),
-                MICROSVC_DISPATCH_TOTAL_FAMILY.snapshot(
-                    dispatch_total
-                        .iter()
-                        .map(|(key, value)| MetricSample::counter(key.labels(), *value))
-                        .collect(),
-                ),
-                MICROSVC_DISPATCH_DURATION_FAMILY.snapshot(
-                    dispatch_duration
-                        .iter()
-                        .map(|(key, histogram)| MetricSample::histogram(key.labels(), histogram))
-                        .collect(),
-                ),
-                TRANSPORT_MESSAGES_TOTAL_FAMILY.snapshot(
-                    transport_messages_total
-                        .iter()
-                        .map(|(key, value)| MetricSample::counter(key.labels(), *value))
-                        .collect(),
-                ),
-                TRANSPORT_FAILURES_TOTAL_FAMILY.snapshot(
-                    transport_failures_total
-                        .iter()
-                        .map(|(key, value)| MetricSample::counter(key.labels(), *value))
-                        .collect(),
-                ),
-                OUTBOX_MESSAGES_TOTAL_FAMILY.snapshot(
-                    outbox_messages_total
-                        .iter()
-                        .map(|(key, value)| MetricSample::counter(key.labels(), *value))
-                        .collect(),
-                ),
-                OUTBOX_PENDING_MESSAGES_FAMILY.snapshot(
-                    outbox_pending_messages
-                        .iter()
-                        .map(|(service, value)| {
-                            MetricSample::gauge(service_labels(service), *value)
-                        })
-                        .collect(),
-                ),
-                OUTBOX_OLDEST_PENDING_AGE_FAMILY.snapshot(
-                    outbox_oldest_pending_age_seconds
-                        .iter()
-                        .map(|(service, value)| {
-                            MetricSample::gauge(service_labels(service), *value)
-                        })
-                        .collect(),
-                ),
-            ],
-        }
-    }
-
-    #[cfg(test)]
-    fn reset(&self) {
-        self.lock(&self.service_info).clear();
-        self.lock(&self.dispatch_total).clear();
-        self.lock(&self.dispatch_duration).clear();
-        self.lock(&self.transport_messages_total).clear();
-        self.lock(&self.transport_failures_total).clear();
-        self.lock(&self.outbox_messages_total).clear();
-        self.lock(&self.outbox_pending_messages).clear();
-        self.lock(&self.outbox_oldest_pending_age_seconds).clear();
-    }
-
-    fn note_service(&self, service: String) {
-        self.lock(&self.service_info).insert(service, ());
-    }
-
-    fn clone_locked<T: Clone>(&self, mutex: &Mutex<T>) -> T {
-        self.lock(mutex).clone()
-    }
-
-    fn lock<'a, T>(&self, mutex: &'a Mutex<T>) -> StdMutexGuard<'a, T> {
-        mutex
-            .lock()
-            .unwrap_or_else(|poisoned| poisoned.into_inner())
-    }
-}
-
-#[derive(Clone)]
-struct DispatchKey {
-    service: String,
-    message_kind: String,
-    message: String,
-    status: String,
-    duration_seconds: f64,
-}
-
-impl DispatchKey {
-    fn counter_key(&self) -> DispatchCounterKey {
-        DispatchCounterKey {
-            service: self.service.clone(),
-            message_kind: self.message_kind.clone(),
-            message: self.message.clone(),
-            status: self.status.clone(),
-        }
-    }
-
-    fn histogram_key(&self) -> DispatchHistogramKey {
-        DispatchHistogramKey {
-            service: self.service.clone(),
-            message_kind: self.message_kind.clone(),
-            message: self.message.clone(),
-            status: self.status.clone(),
-        }
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
-struct DispatchCounterKey {
-    service: String,
-    message_kind: String,
-    message: String,
-    status: String,
-}
-
-impl DispatchCounterKey {
-    fn labels(&self) -> Vec<(String, String)> {
-        vec![
-            (metric_labels::SERVICE.to_string(), self.service.clone()),
-            (
-                metric_labels::MESSAGE_KIND.to_string(),
-                self.message_kind.clone(),
-            ),
-            (metric_labels::MESSAGE.to_string(), self.message.clone()),
-            (metric_labels::STATUS.to_string(), self.status.clone()),
-        ]
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
-struct DispatchHistogramKey {
-    service: String,
-    message_kind: String,
-    message: String,
-    status: String,
-}
-
-impl DispatchHistogramKey {
-    fn labels(&self) -> Vec<(String, String)> {
-        vec![
-            (metric_labels::SERVICE.to_string(), self.service.clone()),
-            (
-                metric_labels::MESSAGE_KIND.to_string(),
-                self.message_kind.clone(),
-            ),
-            (metric_labels::MESSAGE.to_string(), self.message.clone()),
-            (metric_labels::STATUS.to_string(), self.status.clone()),
-        ]
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
-struct TransportMessageKey {
-    service: String,
-    transport: String,
-    message_kind: String,
-    outcome: String,
-}
-
-impl TransportMessageKey {
-    fn labels(&self) -> Vec<(String, String)> {
-        vec![
-            (metric_labels::SERVICE.to_string(), self.service.clone()),
-            (metric_labels::TRANSPORT.to_string(), self.transport.clone()),
-            (
-                metric_labels::MESSAGE_KIND.to_string(),
-                self.message_kind.clone(),
-            ),
-            (metric_labels::OUTCOME.to_string(), self.outcome.clone()),
-        ]
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
-struct TransportFailureKey {
-    service: String,
-    transport: String,
-    failure_class: String,
-    action: String,
-}
-
-impl TransportFailureKey {
-    fn labels(&self) -> Vec<(String, String)> {
-        vec![
-            (metric_labels::SERVICE.to_string(), self.service.clone()),
-            (metric_labels::TRANSPORT.to_string(), self.transport.clone()),
-            (
-                metric_labels::FAILURE_CLASS.to_string(),
-                self.failure_class.clone(),
-            ),
-            (metric_labels::ACTION.to_string(), self.action.clone()),
-        ]
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
-struct OutboxMessageKey {
-    service: String,
-    outcome: String,
-}
-
-impl OutboxMessageKey {
-    fn labels(&self) -> Vec<(String, String)> {
-        vec![
-            (metric_labels::SERVICE.to_string(), self.service.clone()),
-            (metric_labels::OUTCOME.to_string(), self.outcome.clone()),
-        ]
-    }
-}
-
-#[derive(Clone)]
-struct Histogram {
-    bucket_counts: [u64; HISTOGRAM_BUCKETS.len()],
-    sum: f64,
-    count: u64,
-}
-
-impl Histogram {
-    fn new() -> Self {
-        Self {
-            bucket_counts: [0; HISTOGRAM_BUCKETS.len()],
-            sum: 0.0,
-            count: 0,
-        }
-    }
-
-    fn observe(&mut self, value: f64) {
-        self.sum += value;
-        self.count += 1;
-        for (bucket, count) in HISTOGRAM_BUCKETS.iter().zip(self.bucket_counts.iter_mut()) {
-            if value <= *bucket {
-                *count += 1;
-            }
-        }
-    }
-}
-
-fn service_labels(service: &str) -> Vec<(String, String)> {
-    vec![(metric_labels::SERVICE.to_string(), service.to_string())]
-}
-
-fn render_prometheus(snapshot: &MetricsSnapshot) -> String {
-    let mut output = String::new();
-    for family_snapshot in snapshot.families() {
-        write_family_header(&mut output, family_snapshot.family);
-        for sample in &family_snapshot.samples {
-            match &sample.value {
-                MetricSampleValue::Counter(value) => {
-                    push_metric(
-                        &mut output,
-                        family_snapshot.family.name,
-                        &sample.labels,
-                        &value.to_string(),
-                    );
-                }
-                MetricSampleValue::Gauge(value) => {
-                    push_metric(
-                        &mut output,
-                        family_snapshot.family.name,
-                        &sample.labels,
-                        &format_float(*value),
-                    );
-                }
-                MetricSampleValue::Histogram(histogram) => {
-                    let bucket_name = format!("{}_bucket", family_snapshot.family.name);
-                    for bucket in &histogram.buckets {
-                        let mut labels = sample.labels.clone();
-                        labels.push((
-                            metric_labels::LE.to_string(),
-                            bucket.upper_bound.to_string(),
-                        ));
-                        push_metric(
-                            &mut output,
-                            &bucket_name,
-                            &labels,
-                            &bucket.count.to_string(),
-                        );
-                    }
-                    let mut labels = sample.labels.clone();
-                    labels.push((metric_labels::LE.to_string(), "+Inf".to_string()));
-                    push_metric(
-                        &mut output,
-                        &bucket_name,
-                        &labels,
-                        &histogram.count.to_string(),
-                    );
-                    push_metric(
-                        &mut output,
-                        &format!("{}_sum", family_snapshot.family.name),
-                        &sample.labels,
-                        &format_float(histogram.sum),
-                    );
-                    push_metric(
-                        &mut output,
-                        &format!("{}_count", family_snapshot.family.name),
-                        &sample.labels,
-                        &histogram.count.to_string(),
-                    );
-                }
-            }
-        }
-    }
-    output.push_str("# EOF\n");
-    output
-}
-
-fn write_family_header(output: &mut String, family: MetricFamily) {
-    output.push_str("# HELP ");
-    output.push_str(family.name);
-    output.push(' ');
-    output.push_str(family.help);
-    output.push('\n');
-    output.push_str("# TYPE ");
-    output.push_str(family.name);
-    output.push(' ');
-    output.push_str(family.kind.as_prometheus_type());
-    output.push('\n');
-}
-
-fn push_metric(output: &mut String, name: &str, labels: &[(String, String)], value: &str) {
-    output.push_str(name);
-    if !labels.is_empty() {
-        output.push('{');
-        for (index, (key, value)) in labels.iter().enumerate() {
-            if index > 0 {
-                output.push(',');
-            }
-            output.push_str(key.as_str());
-            output.push_str("=\"");
-            push_escaped_label_value(output, value);
-            output.push('"');
-        }
-        output.push('}');
-    }
-    output.push(' ');
-    output.push_str(value);
-    output.push('\n');
-}
-
-fn push_escaped_label_value(output: &mut String, value: &str) {
-    for ch in value.chars() {
-        match ch {
-            '\\' => output.push_str("\\\\"),
-            '"' => output.push_str("\\\""),
-            '\n' => output.push_str("\\n"),
-            _ => output.push(ch),
-        }
-    }
-}
-
-fn format_float(value: f64) -> String {
-    if value.fract() == 0.0 {
-        format!("{value:.0}")
-    } else {
-        value.to_string()
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::telemetry::{
-        dispatch_status, failure_action, failure_class, metric_labels, metric_names,
-        outbox_outcome, transport_outcome,
-    };
-    use std::collections::BTreeSet;
-
-    #[test]
-    fn prometheus_text_escapes_label_values() {
-        let _guard = lock_for_tests();
-        reset_for_tests();
-
-        record_microsvc_dispatch(
-            Some("svc\"one"),
-            MessageKind::Command,
-            "line\nbreak",
-            dispatch_status::SUCCESS,
-            Duration::from_millis(2),
-        );
-
-        let text = prometheus_text();
-
-        assert!(text.contains(
-            "distributed_microsvc_dispatch_total{service=\"svc\\\"one\",message_kind=\"command\",message=\"line\\nbreak\",status=\"success\"} 1"
-        ));
-    }
-
-    #[test]
-    fn histogram_records_cumulative_buckets() {
-        let _guard = lock_for_tests();
-        reset_for_tests();
-
-        record_microsvc_dispatch(
-            Some("orders"),
-            MessageKind::Event,
-            "orders.created",
-            dispatch_status::SUCCESS,
-            Duration::from_millis(7),
-        );
-
-        let text = prometheus_text();
-
-        assert!(text.contains(
-            "distributed_microsvc_dispatch_duration_seconds_bucket{service=\"orders\",message_kind=\"event\",message=\"orders.created\",status=\"success\",le=\"0.005\"} 0"
-        ));
-        assert!(text.contains(
-            "distributed_microsvc_dispatch_duration_seconds_bucket{service=\"orders\",message_kind=\"event\",message=\"orders.created\",status=\"success\",le=\"0.01\"} 1"
-        ));
-        assert!(text.contains(
-            "distributed_microsvc_dispatch_duration_seconds_count{service=\"orders\",message_kind=\"event\",message=\"orders.created\",status=\"success\"} 1"
-        ));
-    }
-
-    #[test]
-    fn snapshot_exposes_bounded_family_shape() {
-        let _guard = lock_for_tests();
-        reset_for_tests();
-
-        record_microsvc_dispatch(
-            Some("orders"),
-            MessageKind::Event,
-            "orders.created",
-            dispatch_status::SUCCESS,
-            Duration::from_millis(7),
-        );
-        record_transport_message(
-            Some("orders"),
-            "nats",
-            MessageKind::Event,
-            transport_outcome::ACK,
-        );
-        record_transport_failure(
-            Some("orders"),
-            "nats",
-            failure_class::RETRYABLE,
-            failure_action::NACK,
-        );
-        record_outbox_messages(Some("orders"), outbox_outcome::PUBLISHED, 2);
-        set_outbox_backlog(Some("orders"), 3, Some(Duration::from_secs(4)));
-
-        let snapshot = snapshot();
-        let family_names = snapshot
-            .families()
-            .iter()
-            .map(|family| family.family.name)
-            .collect::<Vec<_>>();
-
-        assert_eq!(
-            family_names,
-            vec![
-                metric_names::SERVICE_INFO,
-                metric_names::MICROSVC_DISPATCH_TOTAL,
-                metric_names::MICROSVC_DISPATCH_DURATION_SECONDS,
-                metric_names::TRANSPORT_MESSAGES_TOTAL,
-                metric_names::TRANSPORT_FAILURES_TOTAL,
-                metric_names::OUTBOX_MESSAGES_TOTAL,
-                metric_names::OUTBOX_PENDING_MESSAGES,
-                metric_names::OUTBOX_OLDEST_PENDING_AGE_SECONDS,
-            ]
-        );
-
-        let dispatch_family = snapshot
-            .families()
-            .iter()
-            .find(|family| family.family.name == metric_names::MICROSVC_DISPATCH_TOTAL)
-            .expect("dispatch family is present");
-        let dispatch_sample = dispatch_family
-            .samples
-            .iter()
-            .find(|sample| {
-                label_value(&sample.labels, metric_labels::MESSAGE) == Some("orders.created")
-            })
-            .expect("dispatch sample is present");
-        assert!(matches!(
-            &dispatch_sample.value,
-            MetricSampleValue::Counter(value) if *value == 1
-        ));
-
-        let duration_family = snapshot
-            .families()
-            .iter()
-            .find(|family| family.family.name == metric_names::MICROSVC_DISPATCH_DURATION_SECONDS)
-            .expect("duration family is present");
-        assert!(matches!(
-            &duration_family.samples[0].value,
-            MetricSampleValue::Histogram(_)
-        ));
-    }
-
-    #[test]
-    fn rendered_metrics_use_only_allowed_low_cardinality_labels() {
-        let _guard = lock_for_tests();
-        reset_for_tests();
-
-        describe_service(Some("orders"));
-        record_microsvc_dispatch(
-            Some("orders"),
-            MessageKind::Command,
-            "orders.create",
-            dispatch_status::SUCCESS,
-            Duration::from_millis(2),
-        );
-        record_transport_message(
-            Some("orders"),
-            "rabbitmq",
-            MessageKind::Command,
-            transport_outcome::ACK,
-        );
-        record_transport_failure(
-            Some("orders"),
-            "rabbitmq",
-            failure_class::PERMANENT,
-            failure_action::DEAD_LETTER,
-        );
-        record_outbox_messages(Some("orders"), outbox_outcome::RELEASED, 1);
-        set_outbox_backlog(Some("orders"), 1, Some(Duration::from_secs(30)));
-
-        let text = prometheus_text();
-        let label_names = rendered_label_names(&text);
-
-        for forbidden in crate::telemetry::privacy_policy::FORBIDDEN_METRIC_LABELS {
-            assert!(
-                !label_names.contains(*forbidden),
-                "forbidden label `{forbidden}` appeared in metrics:\n{text}"
-            );
-        }
-        for label in &label_names {
-            assert!(
-                crate::telemetry::privacy_policy::ALLOWED_METRIC_LABELS.contains(&label.as_str()),
-                "unexpected metric label `{label}` appeared in metrics:\n{text}"
-            );
-        }
-    }
-
-    fn label_value<'a>(labels: &'a [(String, String)], name: &str) -> Option<&'a str> {
-        labels
-            .iter()
-            .find(|(label, _)| label == name)
-            .map(|(_, value)| value.as_str())
-    }
-
-    fn rendered_label_names(text: &str) -> BTreeSet<String> {
-        let mut names = BTreeSet::new();
-        for line in text.lines().filter(|line| !line.starts_with('#')) {
-            let Some(open) = line.find('{') else {
-                continue;
-            };
-            let Some(close_offset) = line[open + 1..].find('}') else {
-                continue;
-            };
-            let labels = &line[open + 1..open + 1 + close_offset];
-            let bytes = labels.as_bytes();
-            let mut index = 0;
-            while index < bytes.len() {
-                let name_start = index;
-                while index < bytes.len() && bytes[index] != b'=' {
-                    index += 1;
-                }
-                if index >= bytes.len() {
-                    break;
-                }
-                names.insert(labels[name_start..index].to_string());
-                index += 1;
-
-                if bytes.get(index) == Some(&b'"') {
-                    index += 1;
-                }
-                while index < bytes.len() {
-                    match bytes[index] {
-                        b'\\' => index = (index + 2).min(bytes.len()),
-                        b'"' => {
-                            index += 1;
-                            break;
-                        }
-                        _ => index += 1,
-                    }
-                }
-                if bytes.get(index) == Some(&b',') {
-                    index += 1;
-                }
-            }
-        }
-        names
-    }
-}
diff --git a/src/metrics/api.rs b/src/metrics/api.rs
new file mode 100644
index 00000000..aee164b6
--- /dev/null
+++ b/src/metrics/api.rs
@@ -0,0 +1,125 @@
+use std::time::Duration;
+
+use crate::bus::MessageKind;
+use crate::telemetry::service_label;
+
+use super::prometheus::render_prometheus;
+use super::registry::{
+    registry, DispatchKey, GraphqlRequestKey, MetricsSnapshot, OutboxMessageKey,
+    TransportFailureKey, TransportMessageKey,
+};
+
+/// Record that a service exists so `/metrics` exposes a stable info series even
+/// before the first request.
+pub fn describe_service(service: Option<&str>) {
+    registry().describe_service(service_label(service));
+}
+
+/// Record one microsvc command/event dispatch result.
+pub fn record_microsvc_dispatch(
+    service: Option<&str>,
+    kind: MessageKind,
+    message: &str,
+    status: &str,
+    duration: Duration,
+) {
+    registry().record_microsvc_dispatch(DispatchKey {
+        service: service_label(service),
+        message_kind: kind.as_str().to_string(),
+        message: message.to_string(),
+        status: status.to_string(),
+        duration_seconds: duration.as_secs_f64(),
+    });
+}
+
+/// Record a transport receive/settle outcome.
+pub fn record_transport_message(
+    service: Option<&str>,
+    transport: &str,
+    kind: MessageKind,
+    outcome: &str,
+) {
+    registry().record_transport_message(TransportMessageKey {
+        service: service_label(service),
+        transport: transport.to_string(),
+        message_kind: kind.as_str().to_string(),
+        outcome: outcome.to_string(),
+    });
+}
+
+/// Record a classified transport failure and the action chosen for it.
+pub fn record_transport_failure(
+    service: Option<&str>,
+    transport: &str,
+    failure_class: &str,
+    action: &str,
+) {
+    registry().record_transport_failure(TransportFailureKey {
+        service: service_label(service),
+        transport: transport.to_string(),
+        failure_class: failure_class.to_string(),
+        action: action.to_string(),
+    });
+}
+
+/// Record one GraphQL request (root field execution).
+pub fn record_graphql_request(
+    service: Option<&str>,
+    root_field: &str,
+    status: &str,
+    duration: Duration,
+) {
+    registry().record_graphql_request(GraphqlRequestKey {
+        service: service_label(service),
+        root_field: root_field.to_string(),
+        status: status.to_string(),
+        duration_seconds: duration.as_secs_f64(),
+    });
+}
+
+/// Record one outbox dispatch state transition.
+pub fn record_outbox_message(service: Option<&str>, outcome: &str) {
+    record_outbox_messages(service, outcome, 1);
+}
+
+/// Record `count` outbox dispatch state transitions that settled together.
+pub fn record_outbox_messages(service: Option<&str>, outcome: &str, count: usize) {
+    if count == 0 {
+        return;
+    }
+    registry().record_outbox_messages(
+        OutboxMessageKey {
+            service: service_label(service),
+            outcome: outcome.to_string(),
+        },
+        count as u64,
+    );
+}
+
+/// Set outbox backlog gauges for a service.
+pub fn set_outbox_backlog(
+    service: Option<&str>,
+    pending: usize,
+    oldest_pending_age: Option<Duration>,
+) {
+    registry().set_outbox_backlog(
+        service_label(service),
+        pending as f64,
+        oldest_pending_age.map(|duration| duration.as_secs_f64()),
+    );
+}
+
+/// Render all currently recorded metrics in Prometheus text exposition format.
+pub fn prometheus_text() -> String {
+    render_prometheus(&snapshot())
+}
+
+/// Return a lock-free snapshot of bounded framework metric families.
+///
+/// The snapshot contains only metric names, bounded label names/values, and
+/// numeric samples. It deliberately excludes payloads, message metadata, trace
+/// identifiers, aggregate identifiers, and request-specific data so future
+/// diagnostics can reuse it without widening the telemetry privacy surface.
+pub(crate) fn snapshot() -> MetricsSnapshot {
+    registry().snapshot()
+}
diff --git a/src/metrics/http.rs b/src/metrics/http.rs
new file mode 100644
index 00000000..68d9ac61
--- /dev/null
+++ b/src/metrics/http.rs
@@ -0,0 +1,71 @@
+use super::api::{describe_service, prometheus_text};
+
+const PROMETHEUS_TEXT_CONTENT_TYPE: &str = "text/plain; version=0.0.4; charset=utf-8";
+
+/// Build an axum router that exposes only `GET /metrics`.
+///
+/// This is intended for workers and services whose primary transport is not
+/// HTTP. Run it on a small side port so Prometheus can scrape the same
+/// framework metrics that the bus/outbox/runtime paths record. The endpoint is
+/// unauthenticated; bind it only on a private listener or behind equivalent
+/// network controls.
+#[cfg(feature = "http")]
+pub fn http_router() -> axum::Router {
+    http_router_with_state(MetricsHttpState::default())
+}
+
+/// Build an axum router that exposes only `GET /metrics` and records a stable
+/// service label before each scrape.
+#[cfg(feature = "http")]
+pub fn http_router_for_service(service: impl Into<String>) -> axum::Router {
+    http_router_with_state(MetricsHttpState {
+        service: Some(service.into()),
+    })
+}
+
+/// Serve only the metrics scrape endpoint at the given address.
+///
+/// This helper is deliberately independent of `microsvc::http`, so a NATS,
+/// Kafka, RabbitMQ, or outbox worker can expose Prometheus metrics without
+/// exposing command dispatch over HTTP. The endpoint is unauthenticated; do not
+/// bind it on a public interface unless an ingress or network policy restricts
+/// access.
+#[cfg(feature = "http")]
+pub async fn serve_http(addr: &str, service: Option<&str>) -> Result<(), std::io::Error> {
+    let app = match service {
+        Some(service) => http_router_for_service(service),
+        None => http_router(),
+    };
+    let listener = tokio::net::TcpListener::bind(addr).await?;
+    axum::serve(listener, app).await
+}
+
+/// Return a Prometheus text response for HTTP handlers.
+#[cfg(feature = "http")]
+pub fn prometheus_response(service: Option<&str>) -> impl axum::response::IntoResponse {
+    describe_service(service);
+    (
+        [(
+            axum::http::header::CONTENT_TYPE,
+            PROMETHEUS_TEXT_CONTENT_TYPE,
+        )],
+        prometheus_text(),
+    )
+}
+
+#[derive(Clone, Default)]
+struct MetricsHttpState {
+    service: Option<String>,
+}
+
+fn http_router_with_state(state: MetricsHttpState) -> axum::Router {
+    axum::Router::new()
+        .route("/metrics", axum::routing::get(metrics_http_handler))
+        .with_state(state)
+}
+
+async fn metrics_http_handler(
+    axum::extract::State(state): axum::extract::State<MetricsHttpState>,
+) -> impl axum::response::IntoResponse {
+    prometheus_response(state.service.as_deref())
+}
diff --git a/src/metrics/mod.rs b/src/metrics/mod.rs
new file mode 100644
index 00000000..e64c212d
--- /dev/null
+++ b/src/metrics/mod.rs
@@ -0,0 +1,30 @@
+//! Prometheus-compatible framework metrics.
+//!
+//! This module intentionally has no SDK dependency. It records the framework
+//! counters and gauges Distributed owns, then renders Prometheus text exposition
+//! for HTTP scrape endpoints.
+
+mod api;
+
+#[cfg(feature = "http")]
+mod http;
+mod prometheus;
+mod registry;
+
+#[cfg(test)]
+mod test_support;
+
+#[cfg(test)]
+mod tests;
+
+pub use api::{
+    describe_service, prometheus_text, record_graphql_request, record_microsvc_dispatch,
+    record_outbox_message, record_outbox_messages, record_transport_failure,
+    record_transport_message, set_outbox_backlog,
+};
+
+#[cfg(feature = "http")]
+pub use http::{http_router, http_router_for_service, prometheus_response, serve_http};
+
+#[cfg(test)]
+pub(crate) use test_support::{async_lock_for_tests, lock_for_tests, reset_for_tests};
diff --git a/src/metrics/prometheus.rs b/src/metrics/prometheus.rs
new file mode 100644
index 00000000..7db43059
--- /dev/null
+++ b/src/metrics/prometheus.rs
@@ -0,0 +1,120 @@
+use crate::telemetry::metric_labels;
+
+use super::registry::{MetricFamily, MetricSampleValue, MetricsSnapshot};
+
+pub(super) fn render_prometheus(snapshot: &MetricsSnapshot) -> String {
+    let mut output = String::new();
+    for family_snapshot in snapshot.families() {
+        write_family_header(&mut output, family_snapshot.family);
+        for sample in &family_snapshot.samples {
+            match &sample.value {
+                MetricSampleValue::Counter(value) => {
+                    push_metric(
+                        &mut output,
+                        family_snapshot.family.name,
+                        &sample.labels,
+                        &value.to_string(),
+                    );
+                }
+                MetricSampleValue::Gauge(value) => {
+                    push_metric(
+                        &mut output,
+                        family_snapshot.family.name,
+                        &sample.labels,
+                        &format_float(*value),
+                    );
+                }
+                MetricSampleValue::Histogram(histogram) => {
+                    let bucket_name = format!("{}_bucket", family_snapshot.family.name);
+                    for bucket in &histogram.buckets {
+                        let mut labels = sample.labels.clone();
+                        labels.push((
+                            metric_labels::LE.to_string(),
+                            bucket.upper_bound.to_string(),
+                        ));
+                        push_metric(
+                            &mut output,
+                            &bucket_name,
+                            &labels,
+                            &bucket.count.to_string(),
+                        );
+                    }
+                    let mut labels = sample.labels.clone();
+                    labels.push((metric_labels::LE.to_string(), "+Inf".to_string()));
+                    push_metric(
+                        &mut output,
+                        &bucket_name,
+                        &labels,
+                        &histogram.count.to_string(),
+                    );
+                    push_metric(
+                        &mut output,
+                        &format!("{}_sum", family_snapshot.family.name),
+                        &sample.labels,
+                        &format_float(histogram.sum),
+                    );
+                    push_metric(
+                        &mut output,
+                        &format!("{}_count", family_snapshot.family.name),
+                        &sample.labels,
+                        &histogram.count.to_string(),
+                    );
+                }
+            }
+        }
+    }
+    output.push_str("# EOF\n");
+    output
+}
+
+fn write_family_header(output: &mut String, family: MetricFamily) {
+    output.push_str("# HELP ");
+    output.push_str(family.name);
+    output.push(' ');
+    output.push_str(family.help);
+    output.push('\n');
+    output.push_str("# TYPE ");
+    output.push_str(family.name);
+    output.push(' ');
+    output.push_str(family.kind.as_prometheus_type());
+    output.push('\n');
+}
+
+fn push_metric(output: &mut String, name: &str, labels: &[(String, String)], value: &str) {
+    output.push_str(name);
+    if !labels.is_empty() {
+        output.push('{');
+        for (index, (key, value)) in labels.iter().enumerate() {
+            if index > 0 {
+                output.push(',');
+            }
+            output.push_str(key.as_str());
+            output.push_str("=\"");
+            push_escaped_label_value(output, value);
+            output.push('"');
+        }
+        output.push('}');
+    }
+    output.push(' ');
+    output.push_str(value);
+    output.push('\n');
+}
+
+fn push_escaped_label_value(output: &mut String, value: &str) {
+    for ch in value.chars() {
+        match ch {
+            '\\' => output.push_str("\\\\"),
+            '"' => output.push_str("\\\""),
+            '\n' => output.push_str("\\n"),
+            _ => output.push(ch),
+        }
+    }
+}
+
+fn format_float(value: f64) -> String {
+    if value.fract() == 0.0 {
+        format!("{value:.0}")
+    } else {
+        value.to_string()
+    }
+}
diff --git a/src/metrics/registry.rs b/src/metrics/registry.rs
new file mode 100644
index 00000000..c312e073
--- /dev/null
+++ b/src/metrics/registry.rs
@@ -0,0 +1,622 @@
+use std::collections::BTreeMap;
+use std::sync::{Mutex, MutexGuard as StdMutexGuard, OnceLock};
+
+use crate::telemetry::{metric_labels, metric_names};
+
+const HISTOGRAM_BUCKETS: [f64; 11] = [
+    0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0,
+];
+const SERVICE_INFO_FAMILY: MetricFamily = MetricFamily::gauge(
+    metric_names::SERVICE_INFO,
+    "Static Distributed service metadata.",
+);
+const MICROSVC_DISPATCH_TOTAL_FAMILY: MetricFamily = MetricFamily::counter(
+    metric_names::MICROSVC_DISPATCH_TOTAL,
+    "Total microsvc dispatches by service, message kind, message, and status.",
+);
+const MICROSVC_DISPATCH_DURATION_FAMILY: MetricFamily = MetricFamily::histogram(
+    metric_names::MICROSVC_DISPATCH_DURATION_SECONDS,
+    "Microsvc dispatch duration in seconds.",
+);
+const TRANSPORT_MESSAGES_TOTAL_FAMILY: MetricFamily = MetricFamily::counter(
+    metric_names::TRANSPORT_MESSAGES_TOTAL,
+    "Total transport receive/settle outcomes.",
+);
+const TRANSPORT_FAILURES_TOTAL_FAMILY: MetricFamily = MetricFamily::counter(
+    metric_names::TRANSPORT_FAILURES_TOTAL,
+    "Total transport failures by class and chosen action.",
+);
+const OUTBOX_MESSAGES_TOTAL_FAMILY: MetricFamily = MetricFamily::counter(
+    metric_names::OUTBOX_MESSAGES_TOTAL,
+    "Total outbox publish outcomes.",
+);
+const OUTBOX_PENDING_MESSAGES_FAMILY: MetricFamily = MetricFamily::gauge(
+    metric_names::OUTBOX_PENDING_MESSAGES,
+    "Pending outbox message count.",
+);
+const OUTBOX_OLDEST_PENDING_AGE_FAMILY: MetricFamily = MetricFamily::gauge(
+    metric_names::OUTBOX_OLDEST_PENDING_AGE_SECONDS,
+    "Age in seconds of the oldest pending outbox message.",
+);
+const GRAPHQL_REQUEST_TOTAL_FAMILY: MetricFamily = MetricFamily::counter(
+    metric_names::GRAPHQL_REQUEST_TOTAL,
+    "Total GraphQL root-field executions by service, root_field, and status.",
+);
+const GRAPHQL_REQUEST_DURATION_FAMILY: MetricFamily = MetricFamily::histogram(
+    metric_names::GRAPHQL_REQUEST_DURATION_SECONDS,
+    "GraphQL root-field execution duration in seconds.",
+);
+
+static REGISTRY: OnceLock<MetricsRegistry> = OnceLock::new();
+
+pub(super) fn registry() -> &'static MetricsRegistry {
+    REGISTRY.get_or_init(MetricsRegistry::default)
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct MetricFamily {
+    pub(crate) name: &'static str,
+    pub(super) help: &'static str,
+    pub(super) kind: MetricKind,
+}
+
+impl MetricFamily {
+    const fn counter(name: &'static str, help: &'static str) -> Self {
+        Self {
+            name,
+            help,
+            kind: MetricKind::Counter,
+        }
+    }
+
+    const fn gauge(name: &'static str, help: &'static str) -> Self {
+        Self {
+            name,
+            help,
+            kind: MetricKind::Gauge,
+        }
+    }
+
+    const fn histogram(name: &'static str, help: &'static str) -> Self {
+        Self {
+            name,
+            help,
+            kind: MetricKind::Histogram,
+        }
+    }
+
+    pub(super) fn snapshot(self, samples: Vec<MetricSample>) -> MetricFamilySnapshot {
+        MetricFamilySnapshot {
+            family: self,
+            samples,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(super) enum MetricKind {
+    Counter,
+    Gauge,
+    Histogram,
+}
+
+impl MetricKind {
+    pub(super) fn as_prometheus_type(self) -> &'static str {
+        match self {
+            Self::Counter => "counter",
+            Self::Gauge => "gauge",
+            Self::Histogram => "histogram",
+        }
+    }
+}
+
+/// Lock-free, bounded snapshot of framework-owned metric families.
+#[derive(Clone, Debug)]
+pub(crate) struct MetricsSnapshot {
+    families: Vec<MetricFamilySnapshot>,
+}
+
+impl MetricsSnapshot {
+    pub(crate) fn families(&self) -> &[MetricFamilySnapshot] {
+        &self.families
+    }
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MetricFamilySnapshot {
+    pub(crate) family: MetricFamily,
+    pub(crate) samples: Vec<MetricSample>,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MetricSample {
+    pub(crate) labels: Vec<(String, String)>,
+    pub(crate) value: MetricSampleValue,
+}
+
+impl MetricSample {
+    fn counter(labels: Vec<(String, String)>, value: u64) -> Self {
+        Self {
+            labels,
+            value: MetricSampleValue::Counter(value),
+        }
+    }
+
+    fn gauge(labels: Vec<(String, String)>, value: f64) -> Self {
+        Self {
+            labels,
+            value: MetricSampleValue::Gauge(value),
+        }
+    }
+
+    fn histogram(labels: Vec<(String, String)>, histogram: &Histogram) -> Self {
+        let buckets = HISTOGRAM_BUCKETS
+            .iter()
+            .zip(histogram.bucket_counts.iter())
+            .map(|(upper_bound, count)| HistogramBucketSnapshot {
+                upper_bound: *upper_bound,
+                count: *count,
+            })
+            .collect();
+        Self {
+            labels,
+            value: MetricSampleValue::Histogram(HistogramSnapshot {
+                buckets,
+                sum: histogram.sum,
+                count: histogram.count,
+            }),
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub(crate) enum MetricSampleValue {
+    Counter(u64),
+    Gauge(f64),
+    Histogram(HistogramSnapshot),
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct HistogramSnapshot {
+    pub(crate) buckets: Vec<HistogramBucketSnapshot>,
+    pub(crate) sum: f64,
+    pub(crate) count: u64,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct HistogramBucketSnapshot {
+    pub(crate) upper_bound: f64,
+    pub(crate) count: u64,
+}
+
+#[derive(Default)]
+pub(super) struct MetricsRegistry {
+    service_info: Mutex<BTreeMap<String, ()>>,
+    dispatch_total: Mutex<BTreeMap<DispatchCounterKey, u64>>,
+    dispatch_duration: Mutex<BTreeMap<DispatchHistogramKey, Histogram>>,
+    transport_messages_total: Mutex<BTreeMap<TransportMessageKey, u64>>,
+    transport_failures_total: Mutex<BTreeMap<TransportFailureKey, u64>>,
+    outbox_messages_total: Mutex<BTreeMap<OutboxMessageKey, u64>>,
+    outbox_pending_messages: Mutex<BTreeMap<String, f64>>,
+    outbox_oldest_pending_age_seconds: Mutex<BTreeMap<String, f64>>,
+    graphql_request_total: Mutex<BTreeMap<GraphqlCounterKey, u64>>,
+    graphql_request_duration: Mutex<BTreeMap<GraphqlHistogramKey, Histogram>>,
+}
+
+impl MetricsRegistry {
+    pub(super) fn describe_service(&self, service: String) {
+        self.note_service(service);
+    }
+
+    pub(super) fn record_microsvc_dispatch(&self, key: DispatchKey) {
+        let service = key.service.clone();
+        self.lock(&self.dispatch_total)
+            .entry(key.counter_key())
+            .and_modify(|value| *value += 1)
+            .or_insert(1);
+        self.lock(&self.dispatch_duration)
+            .entry(key.histogram_key())
+            .or_insert_with(Histogram::new)
+            .observe(key.duration_seconds);
+        self.note_service(service);
+    }
+
+    pub(super) fn record_transport_message(&self, key: TransportMessageKey) {
+        let service = key.service.clone();
+        self.lock(&self.transport_messages_total)
+            .entry(key)
+            .and_modify(|value| *value += 1)
+            .or_insert(1);
+        self.note_service(service);
+    }
+
+    pub(super) fn record_transport_failure(&self, key: TransportFailureKey) {
+        let service = key.service.clone();
+        self.lock(&self.transport_failures_total)
+            .entry(key)
+            .and_modify(|value| *value += 1)
+            .or_insert(1);
+        self.note_service(service);
+    }
+
+    pub(super) fn record_outbox_messages(&self, key: OutboxMessageKey, count: u64) {
+        let service = key.service.clone();
+        self.lock(&self.outbox_messages_total)
+            .entry(key)
+            .and_modify(|value| *value += count)
+            .or_insert(count);
+        self.note_service(service);
+    }
+
+    pub(super) fn record_graphql_request(&self, key: GraphqlRequestKey) {
+        let service = key.service.clone();
+        self.lock(&self.graphql_request_total)
+            .entry(key.counter_key())
+            .and_modify(|value| *value += 1)
+            .or_insert(1);
+        self.lock(&self.graphql_request_duration)
+            .entry(key.histogram_key())
+            .or_insert_with(Histogram::new)
+            .observe(key.duration_seconds);
+        self.note_service(service);
+    }
+
+    pub(super) fn set_outbox_backlog(
+        &self,
+        service: String,
+        pending: f64,
+        oldest_pending_age: Option<f64>,
+    ) {
+        self.lock(&self.outbox_pending_messages)
+            .insert(service.clone(), pending);
+        if let Some(age) = oldest_pending_age {
+            self.lock(&self.outbox_oldest_pending_age_seconds)
+                .insert(service.clone(), age);
+        } else {
+            self.lock(&self.outbox_oldest_pending_age_seconds)
+                .remove(&service);
+        }
+        self.note_service(service);
+    }
+
+    pub(super) fn snapshot(&self) -> MetricsSnapshot {
+        let service_info = self.clone_locked(&self.service_info);
+        let dispatch_total = self.clone_locked(&self.dispatch_total);
+        let dispatch_duration = self.clone_locked(&self.dispatch_duration);
+        let transport_messages_total = self.clone_locked(&self.transport_messages_total);
+        let transport_failures_total = self.clone_locked(&self.transport_failures_total);
+        let outbox_messages_total = self.clone_locked(&self.outbox_messages_total);
+        let outbox_pending_messages = self.clone_locked(&self.outbox_pending_messages);
+        let outbox_oldest_pending_age_seconds =
+            self.clone_locked(&self.outbox_oldest_pending_age_seconds);
+        let graphql_request_total = self.clone_locked(&self.graphql_request_total);
+        let graphql_request_duration = self.clone_locked(&self.graphql_request_duration);
+
+        MetricsSnapshot {
+            families: vec![
+                SERVICE_INFO_FAMILY.snapshot(
+                    service_info
+                        .keys()
+                        .map(|service| {
+                            MetricSample::gauge(
+                                vec![
+                                    (metric_labels::SERVICE.to_string(), service.clone()),
+                                    (
+                                        metric_labels::VERSION.to_string(),
+                                        env!("CARGO_PKG_VERSION").to_string(),
+                                    ),
+                                ],
+                                1.0,
+                            )
+                        })
+                        .collect(),
+                ),
+                MICROSVC_DISPATCH_TOTAL_FAMILY.snapshot(
+                    dispatch_total
+                        .iter()
+                        .map(|(key, value)| MetricSample::counter(key.labels(), *value))
+                        .collect(),
+                ),
+                MICROSVC_DISPATCH_DURATION_FAMILY.snapshot(
+                    dispatch_duration
+                        .iter()
+                        .map(|(key, histogram)| MetricSample::histogram(key.labels(), histogram))
+                        .collect(),
+                ),
+                TRANSPORT_MESSAGES_TOTAL_FAMILY.snapshot(
+                    transport_messages_total
+                        .iter()
+                        .map(|(key, value)| MetricSample::counter(key.labels(), *value))
+                        .collect(),
+                ),
+                TRANSPORT_FAILURES_TOTAL_FAMILY.snapshot(
+                    transport_failures_total
+                        .iter()
+                        .map(|(key, value)| MetricSample::counter(key.labels(), *value))
+                        .collect(),
+                ),
+                OUTBOX_MESSAGES_TOTAL_FAMILY.snapshot(
+                    outbox_messages_total
+                        .iter()
+                        .map(|(key, value)| MetricSample::counter(key.labels(), *value))
+                        .collect(),
+                ),
+                OUTBOX_PENDING_MESSAGES_FAMILY.snapshot(
+                    outbox_pending_messages
+                        .iter()
+                        .map(|(service, value)| {
+                            MetricSample::gauge(service_labels(service), *value)
+                        })
+                        .collect(),
+                ),
+                OUTBOX_OLDEST_PENDING_AGE_FAMILY.snapshot(
+                    outbox_oldest_pending_age_seconds
+                        .iter()
+                        .map(|(service, value)| {
+                            MetricSample::gauge(service_labels(service), *value)
+                        })
+                        .collect(),
+                ),
+                GRAPHQL_REQUEST_TOTAL_FAMILY.snapshot(
+                    graphql_request_total
+                        .iter()
+                        .map(|(key, value)| MetricSample::counter(key.labels(), *value))
+                        .collect(),
+                ),
+                GRAPHQL_REQUEST_DURATION_FAMILY.snapshot(
+                    graphql_request_duration
+                        .iter()
+                        .map(|(key, histogram)| MetricSample::histogram(key.labels(), histogram))
+                        .collect(),
+                ),
+            ],
+        }
+    }
+
+    #[cfg(test)]
+    pub(super) fn reset(&self) {
+        self.lock(&self.service_info).clear();
+        self.lock(&self.dispatch_total).clear();
+        self.lock(&self.dispatch_duration).clear();
+        self.lock(&self.transport_messages_total).clear();
+        self.lock(&self.transport_failures_total).clear();
+        self.lock(&self.outbox_messages_total).clear();
+        self.lock(&self.outbox_pending_messages).clear();
+        self.lock(&self.outbox_oldest_pending_age_seconds).clear();
+    }
+
+    fn note_service(&self, service: String) {
+        self.lock(&self.service_info).insert(service, ());
+    }
+
+    fn clone_locked<T: Clone>(&self, mutex: &Mutex<T>) -> T {
+        self.lock(mutex).clone()
+    }
+
+    fn lock<'a, T>(&self, mutex: &'a Mutex<T>) -> StdMutexGuard<'a, T> {
+        mutex
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+    }
+}
+
+#[derive(Clone)]
+pub(super) struct DispatchKey {
+    pub(super) service: String,
+    pub(super) message_kind: String,
+    pub(super) message: String,
+    pub(super) status: String,
+    pub(super) duration_seconds: f64,
+}
+
+impl DispatchKey {
+    fn counter_key(&self) -> DispatchCounterKey {
+        DispatchCounterKey {
+            service: self.service.clone(),
+            message_kind: self.message_kind.clone(),
+            message: self.message.clone(),
+            status: self.status.clone(),
+        }
+    }
+
+    fn histogram_key(&self) -> DispatchHistogramKey {
+        DispatchHistogramKey {
+            service: self.service.clone(),
+            message_kind: self.message_kind.clone(),
+            message: self.message.clone(),
+            status: self.status.clone(),
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+struct DispatchCounterKey {
+    service: String,
+    message_kind: String,
+    message: String,
+    status: String,
+}
+
+impl DispatchCounterKey {
+    fn labels(&self) -> Vec<(String, String)> {
+        vec![
+            (metric_labels::SERVICE.to_string(), self.service.clone()),
+            (
+                metric_labels::MESSAGE_KIND.to_string(),
+                self.message_kind.clone(),
+            ),
+            (metric_labels::MESSAGE.to_string(), self.message.clone()),
+            (metric_labels::STATUS.to_string(), self.status.clone()),
+        ]
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+struct DispatchHistogramKey {
+    service: String,
+    message_kind: String,
+    message: String,
+    status: String,
+}
+
+impl DispatchHistogramKey {
+    fn labels(&self) -> Vec<(String, String)> {
+        vec![
+            (metric_labels::SERVICE.to_string(), self.service.clone()),
+            (
+                metric_labels::MESSAGE_KIND.to_string(),
+                self.message_kind.clone(),
+            ),
+            (metric_labels::MESSAGE.to_string(), self.message.clone()),
+            (metric_labels::STATUS.to_string(), self.status.clone()),
+        ]
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+pub(super) struct TransportMessageKey {
+    pub(super) service: String,
+    pub(super) transport: String,
+    pub(super) message_kind: String,
+    pub(super) outcome: String,
+}
+
+impl TransportMessageKey {
+    fn labels(&self) -> Vec<(String, String)> {
+        vec![
+            (metric_labels::SERVICE.to_string(), self.service.clone()),
+            (metric_labels::TRANSPORT.to_string(), self.transport.clone()),
+            (
+                metric_labels::MESSAGE_KIND.to_string(),
+                self.message_kind.clone(),
+            ),
+            (metric_labels::OUTCOME.to_string(), self.outcome.clone()),
+        ]
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+pub(super) struct TransportFailureKey {
+    pub(super) service: String,
+    pub(super) transport: String,
+    pub(super) failure_class: String,
+    pub(super) action: String,
+}
+
+impl TransportFailureKey {
+    fn labels(&self) -> Vec<(String, String)> {
+        vec![
+            (metric_labels::SERVICE.to_string(), self.service.clone()),
+            (metric_labels::TRANSPORT.to_string(), self.transport.clone()),
+            (
+                metric_labels::FAILURE_CLASS.to_string(),
+                self.failure_class.clone(),
+            ),
+            (metric_labels::ACTION.to_string(), self.action.clone()),
+        ]
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+pub(super) struct OutboxMessageKey {
+    pub(super) service: String,
+    pub(super) outcome: String,
+}
+
+impl OutboxMessageKey {
+    fn labels(&self) -> Vec<(String, String)> {
+        vec![
+            (metric_labels::SERVICE.to_string(), self.service.clone()),
+            (metric_labels::OUTCOME.to_string(), self.outcome.clone()),
+        ]
+    }
+}
+
+#[derive(Clone)]
+struct Histogram {
+    bucket_counts: [u64; HISTOGRAM_BUCKETS.len()],
+    sum: f64,
+    count: u64,
+}
+
+impl Histogram {
+    fn new() -> Self {
+        Self {
+            bucket_counts: [0; HISTOGRAM_BUCKETS.len()],
+            sum: 0.0,
+            count: 0,
+        }
+    }
+
+    fn observe(&mut self, value: f64) {
+        self.sum += value;
+        self.count += 1;
+        for (bucket, count) in HISTOGRAM_BUCKETS.iter().zip(self.bucket_counts.iter_mut()) {
+            if value <= *bucket {
+                *count += 1;
+            }
+        }
+    }
+}
+
+fn service_labels(service: &str) -> Vec<(String, String)> {
+    vec![(metric_labels::SERVICE.to_string(), service.to_string())]
+}
+#[derive(Clone, Debug)]
+pub(super) struct GraphqlRequestKey {
+    pub(super) service: String,
+    pub(super) root_field: String,
+    pub(super) status: String,
+    pub(super) duration_seconds: f64,
+}
+
+impl GraphqlRequestKey {
+    fn counter_key(&self) -> GraphqlCounterKey {
+        GraphqlCounterKey {
+            service: self.service.clone(),
+            root_field: self.root_field.clone(),
+            status: self.status.clone(),
+        }
+    }
+    fn histogram_key(&self) -> GraphqlHistogramKey {
+        GraphqlHistogramKey {
+            service: self.service.clone(),
+            root_field: self.root_field.clone(),
+            status: self.status.clone(),
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+struct GraphqlCounterKey {
+    service: String,
+    root_field: String,
+    status: String,
+}
+
+impl GraphqlCounterKey {
+    fn labels(&self) -> Vec<(String, String)> {
+        vec![
+            (metric_labels::SERVICE.to_string(), self.service.clone()),
+            ("root_field".to_string(), self.root_field.clone()),
+            (metric_labels::STATUS.to_string(), self.status.clone()),
+        ]
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+struct GraphqlHistogramKey {
+    service: String,
+    root_field: String,
+    status: String,
+}
+
+impl GraphqlHistogramKey {
+    fn labels(&self) -> Vec<(String, String)> {
+        vec![
+            (metric_labels::SERVICE.to_string(), self.service.clone()),
+            ("root_field".to_string(), self.root_field.clone()),
+            (metric_labels::STATUS.to_string(), self.status.clone()),
+        ]
+    }
+}
diff --git a/src/metrics/test_support.rs b/src/metrics/test_support.rs
new file mode 100644
index 00000000..2c58191b
--- /dev/null
+++ b/src/metrics/test_support.rs
@@ -0,0 +1,25 @@
+use std::sync::OnceLock;
+
+use super::registry::registry;
+
+static TEST_LOCK: OnceLock<tokio::sync::Mutex<()>> = OnceLock::new();
+
+#[cfg(test)]
+pub(crate) fn reset_for_tests() {
+    registry().reset();
+}
+
+#[cfg(test)]
+pub(crate) fn lock_for_tests() -> tokio::sync::MutexGuard<'static, ()> {
+    TEST_LOCK
+        .get_or_init(|| tokio::sync::Mutex::new(()))
+        .blocking_lock()
+}
+
+#[cfg(test)]
+pub(crate) async fn async_lock_for_tests() -> tokio::sync::MutexGuard<'static, ()> {
+    TEST_LOCK
+        .get_or_init(|| tokio::sync::Mutex::new(()))
+        .lock()
+        .await
+}
diff --git a/src/metrics/tests.rs b/src/metrics/tests.rs
new file mode 100644
index 00000000..d7bfaa3f
--- /dev/null
+++ b/src/metrics/tests.rs
@@ -0,0 +1,230 @@
+use super::api::snapshot;
+use super::registry::MetricSampleValue;
+use super::*;
+use crate::bus::MessageKind;
+use crate::telemetry::{
+    dispatch_status, failure_action, failure_class, metric_labels, metric_names, outbox_outcome,
+    transport_outcome,
+};
+use std::collections::BTreeSet;
+use std::time::Duration;
+
+#[test]
+fn prometheus_text_escapes_label_values() {
+    let _guard = lock_for_tests();
+    reset_for_tests();
+
+    record_microsvc_dispatch(
+        Some("svc\"one"),
+        MessageKind::Command,
+        "line\nbreak",
+        dispatch_status::SUCCESS,
+        Duration::from_millis(2),
+    );
+
+    let text = prometheus_text();
+
+    assert!(text.contains(
+            "distributed_microsvc_dispatch_total{service=\"svc\\\"one\",message_kind=\"command\",message=\"line\\nbreak\",status=\"success\"} 1"
+        ));
+}
+
+#[test]
+fn histogram_records_cumulative_buckets() {
+    let _guard = lock_for_tests();
+    reset_for_tests();
+
+    record_microsvc_dispatch(
+        Some("orders"),
+        MessageKind::Event,
+        "orders.created",
+        dispatch_status::SUCCESS,
+        Duration::from_millis(7),
+    );
+
+    let text = prometheus_text();
+
+    assert!(text.contains(
+            "distributed_microsvc_dispatch_duration_seconds_bucket{service=\"orders\",message_kind=\"event\",message=\"orders.created\",status=\"success\",le=\"0.005\"} 0"
+        ));
+    assert!(text.contains(
+            "distributed_microsvc_dispatch_duration_seconds_bucket{service=\"orders\",message_kind=\"event\",message=\"orders.created\",status=\"success\",le=\"0.01\"} 1"
+        ));
+    assert!(text.contains(
+            "distributed_microsvc_dispatch_duration_seconds_count{service=\"orders\",message_kind=\"event\",message=\"orders.created\",status=\"success\"} 1"
+        ));
+}
+
+#[test]
+fn snapshot_exposes_bounded_family_shape() {
+    let _guard = lock_for_tests();
+    reset_for_tests();
+
+    record_microsvc_dispatch(
+        Some("orders"),
+        MessageKind::Event,
+        "orders.created",
+        dispatch_status::SUCCESS,
+        Duration::from_millis(7),
+    );
+    record_transport_message(
+        Some("orders"),
+        "nats",
+        MessageKind::Event,
+        transport_outcome::ACK,
+    );
+    record_transport_failure(
+        Some("orders"),
+        "nats",
+        failure_class::RETRYABLE,
+        failure_action::NACK,
+    );
+    record_outbox_messages(Some("orders"), outbox_outcome::PUBLISHED, 2);
+    set_outbox_backlog(Some("orders"), 3, Some(Duration::from_secs(4)));
+
+    let snapshot = snapshot();
+    let family_names = snapshot
+        .families()
+        .iter()
+        .map(|family| family.family.name)
+        .collect::<Vec<_>>();
+
+    assert_eq!(
+        family_names,
+        vec![
+            metric_names::SERVICE_INFO,
+            metric_names::MICROSVC_DISPATCH_TOTAL,
+            metric_names::MICROSVC_DISPATCH_DURATION_SECONDS,
+            metric_names::TRANSPORT_MESSAGES_TOTAL,
+            metric_names::TRANSPORT_FAILURES_TOTAL,
+            metric_names::OUTBOX_MESSAGES_TOTAL,
+            metric_names::OUTBOX_PENDING_MESSAGES,
+            metric_names::OUTBOX_OLDEST_PENDING_AGE_SECONDS,
+            metric_names::GRAPHQL_REQUEST_TOTAL,
+            metric_names::GRAPHQL_REQUEST_DURATION_SECONDS,
+        ]
+    );
+
+    let dispatch_family = snapshot
+        .families()
+        .iter()
+        .find(|family| family.family.name == metric_names::MICROSVC_DISPATCH_TOTAL)
+        .expect("dispatch family is present");
+    let dispatch_sample = dispatch_family
+        .samples
+        .iter()
+        .find(|sample| {
+            label_value(&sample.labels, metric_labels::MESSAGE) == Some("orders.created")
+        })
+        .expect("dispatch sample is present");
+    assert!(matches!(
+        &dispatch_sample.value,
+        MetricSampleValue::Counter(1)
+    ));
+
+    let duration_family = snapshot
+        .families()
+        .iter()
+        .find(|family| family.family.name == metric_names::MICROSVC_DISPATCH_DURATION_SECONDS)
+        .expect("duration family is present");
+    assert!(matches!(
+        &duration_family.samples[0].value,
+        MetricSampleValue::Histogram(_)
+    ));
+}
+
+#[test]
+fn rendered_metrics_use_only_allowed_low_cardinality_labels() {
+    let _guard = lock_for_tests();
+    reset_for_tests();
+
+    describe_service(Some("orders"));
+    record_microsvc_dispatch(
+        Some("orders"),
+        MessageKind::Command,
+        "orders.create",
+        dispatch_status::SUCCESS,
+        Duration::from_millis(2),
+    );
+    record_transport_message(
+        Some("orders"),
+        "rabbitmq",
+        MessageKind::Command,
+        transport_outcome::ACK,
+    );
+    record_transport_failure(
+        Some("orders"),
+        "rabbitmq",
+        failure_class::PERMANENT,
+        failure_action::DEAD_LETTER,
+    );
+    record_outbox_messages(Some("orders"), outbox_outcome::RELEASED, 1);
+    set_outbox_backlog(Some("orders"), 1, Some(Duration::from_secs(30)));
+
+    let text = prometheus_text();
+    let label_names = rendered_label_names(&text);
+
+    for forbidden in crate::telemetry::privacy_policy::FORBIDDEN_METRIC_LABELS {
+        assert!(
+            !label_names.contains(*forbidden),
+            "forbidden label `{forbidden}` appeared in metrics:\n{text}"
+        );
+    }
+    for label in &label_names {
+        assert!(
+            crate::telemetry::privacy_policy::ALLOWED_METRIC_LABELS.contains(&label.as_str()),
+            "unexpected metric label `{label}` appeared in metrics:\n{text}"
+        );
+    }
+}
+
+fn label_value<'a>(labels: &'a [(String, String)], name: &str) -> Option<&'a str> {
+    labels
+        .iter()
+        .find(|(label, _)| label == name)
+        .map(|(_, value)| value.as_str())
+}
+
+fn rendered_label_names(text: &str) -> BTreeSet<String> {
+    let mut names = BTreeSet::new();
+    for line in text.lines().filter(|line| !line.starts_with('#')) {
+        let Some(open) = line.find('{') else {
+            continue;
+        };
+        let Some(close_offset) = line[open + 1..].find('}') else {
+            continue;
+        };
+        let labels = &line[open + 1..open + 1 + close_offset];
+        let bytes = labels.as_bytes();
+        let mut index = 0;
+        while index < bytes.len() {
+            let name_start = index;
+            while index < bytes.len() && bytes[index] != b'=' {
+                index += 1;
+            }
+            if index >= bytes.len() {
+                break;
+            }
+            names.insert(labels[name_start..index].to_string());
+            index += 1;
+
+            if bytes.get(index) == Some(&b'"') {
+                index += 1;
+            }
+            while index < bytes.len() {
+                match bytes[index] {
+                    b'\\' => index = (index + 2).min(bytes.len()),
+                    b'"' => {
+                        index += 1;
+                        break;
+                    }
+                    _ => index += 1,
+                }
+            }
+            if bytes.get(index) == Some(&b',') {
+                index += 1;
+            }
+        }
+    }
+    names
+}
diff --git a/src/microsvc/causal.rs b/src/microsvc/causal.rs
new file mode 100644
index 00000000..c2be0b40
--- /dev/null
+++ b/src/microsvc/causal.rs
@@ -0,0 +1,846 @@
+//! Framework-owned staging for typed causal command handlers.
+//!
+//! A workspace deliberately exposes neither its repository nor a commit
+//! operation. Handlers receive owned aggregate checkouts and may only return
+//! them to this staging area. The service dispatcher validates the resulting
+//! evidence, wraps its ordinary [`CommitBatch`] in the command-ledger fence,
+//! and is the only code allowed to commit it.
+
+#![cfg_attr(not(feature = "graphql"), allow(dead_code))]
+
+use std::collections::HashSet;
+use std::future::Future;
+use std::ops::{Deref, DerefMut};
+use std::pin::Pin;
+use std::sync::Mutex;
+
+use serde::Serialize;
+
+use crate::aggregate::{hydrate, Aggregate, AggregateRepository};
+use crate::command_ledger::CausalGetStream;
+use crate::graphql::command_contract::{
+    CommandCommitProofError, CommandOutcome, ProjectionCommitProof, ResolvedDirectProjectionTarget,
+    TypedCommandContract,
+};
+use crate::graphql::{GraphqlOutputType, PrepareCommandError, PreparedCommand, Projected};
+use crate::outbox::OutboxMessage;
+use crate::projection_protocol::SameTransactionProjectionBatch;
+use crate::read_model::{ReadModelWritePlanBuilder, RelationalReadModel};
+use crate::repository::{CommitBatch, RepositoryError, SnapshotWrite, StreamIdentity, StreamWrite};
+use crate::table::{TableStoreError, TableWritePlan};
+
+type LoadAggregateFuture<'a, A> =
+    Pin<Box<dyn Future<Output = Result<Option<A>, RepositoryError>> + Send + 'a>>;
+
+/// Erases the concrete backend from the handler-facing workspace while
+/// retaining the repository's explicitly non-locking causal load capability.
+trait CausalAggregateStore<A>: Send + Sync {
+    fn load<'a>(&'a self, identity: &'a StreamIdentity) -> LoadAggregateFuture<'a, A>;
+
+    fn snapshot_writes(
+        &self,
+        aggregate: &A,
+    ) -> Result<(Vec<SnapshotWrite>, Option<u64>), RepositoryError>;
+}
+
+struct AggregateStoreRef<'repo, R, A> {
+    repository: &'repo AggregateRepository<R, A>,
+}
+
+impl<R, A> CausalAggregateStore<A> for AggregateStoreRef<'_, R, A>
+where
+    R: CausalGetStream,
+    A: Aggregate + Send + Sync + 'static,
+{
+    fn load<'a>(&'a self, identity: &'a StreamIdentity) -> LoadAggregateFuture<'a, A> {
+        Box::pin(async move {
+            let Some(entity) = self.repository.repo().get_causal_stream(identity).await? else {
+                return Ok(None);
+            };
+            hydrate::<A>(entity).map(Some)
+        })
+    }
+
+    fn snapshot_writes(
+        &self,
+        aggregate: &A,
+    ) -> Result<(Vec<SnapshotWrite>, Option<u64>), RepositoryError> {
+        self.repository.snapshot_writes_for(aggregate)
+    }
+}
+
+#[derive(Clone, Debug)]
+enum CheckoutOrigin {
+    New,
+    Loaded {
+        identity: StreamIdentity,
+        committed_version: u64,
+    },
+}
+
+/// An aggregate value checked out of a causal workspace.
+///
+/// The value is owned, so no repository or queue lock survives across handler
+/// awaits. Its original stream identity and committed version remain private
+/// and are checked when the handler stages it back into the workspace.
+pub struct AggregateCheckout<A: Aggregate> {
+    aggregate: A,
+    origin: CheckoutOrigin,
+}
+
+impl<A: Aggregate> AggregateCheckout<A> {
+    fn loaded(identity: StreamIdentity, aggregate: A) -> Self {
+        let committed_version = aggregate.entity().committed_version();
+        Self {
+            aggregate,
+            origin: CheckoutOrigin::Loaded {
+                identity,
+                committed_version,
+            },
+        }
+    }
+
+    fn new(aggregate: A) -> Self {
+        Self {
+            aggregate,
+            origin: CheckoutOrigin::New,
+        }
+    }
+
+    pub fn aggregate(&self) -> &A {
+        &self.aggregate
+    }
+
+    pub fn aggregate_mut(&mut self) -> &mut A {
+        &mut self.aggregate
+    }
+}
+
+impl<A: Aggregate> Deref for AggregateCheckout<A> {
+    type Target = A;
+
+    fn deref(&self) -> &Self::Target {
+        &self.aggregate
+    }
+}
+
+impl<A: Aggregate> DerefMut for AggregateCheckout<A> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.aggregate
+    }
+}
+
+/// A deterministic staging error caught before command commit I/O.
+#[derive(Debug)]
+pub(crate) enum CausalWorkspaceError {
+    Repository(RepositoryError),
+    Table(TableStoreError),
+    Prepare(PrepareCommandError),
+    Poisoned,
+    IdentityChanged {
+        original: StreamIdentity,
+        current: StreamIdentity,
+    },
+    CommittedVersionChanged {
+        identity: StreamIdentity,
+        original: u64,
+        current: u64,
+    },
+    DuplicateStream(StreamIdentity),
+    ProjectionAlreadyStaged,
+    CommitBatchAlreadyPrepared,
+}
+
+impl std::fmt::Display for CausalWorkspaceError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Repository(error) => write!(formatter, "causal aggregate load failed: {error}"),
+            Self::Table(error) => write!(formatter, "causal read-model staging failed: {error}"),
+            Self::Prepare(error) => write!(formatter, "causal result preparation failed: {error}"),
+            Self::Poisoned => formatter.write_str("causal workspace lock poisoned"),
+            Self::IdentityChanged { original, current } => write!(
+                formatter,
+                "checked-out aggregate identity changed from `{original}` to `{current}`"
+            ),
+            Self::CommittedVersionChanged {
+                identity,
+                original,
+                current,
+            } => write!(
+                formatter,
+                "checked-out aggregate `{identity}` changed committed version from {original} to {current}"
+            ),
+            Self::DuplicateStream(identity) => {
+                write!(formatter, "aggregate stream `{identity}` was staged more than once")
+            }
+            Self::ProjectionAlreadyStaged => formatter.write_str(
+                "a causal command may prepare only one same-transaction projected result",
+            ),
+            Self::CommitBatchAlreadyPrepared => {
+                formatter.write_str("causal workspace commit batch was already prepared")
+            }
+        }
+    }
+}
+
+impl std::error::Error for CausalWorkspaceError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Repository(error) => Some(error),
+            Self::Table(error) => Some(error),
+            Self::Prepare(error) => Some(error),
+            Self::Poisoned
+            | Self::IdentityChanged { .. }
+            | Self::CommittedVersionChanged { .. }
+            | Self::DuplicateStream(_)
+            | Self::ProjectionAlreadyStaged
+            | Self::CommitBatchAlreadyPrepared => None,
+        }
+    }
+}
+
+impl From<RepositoryError> for CausalWorkspaceError {
+    fn from(error: RepositoryError) -> Self {
+        Self::Repository(error)
+    }
+}
+
+impl From<TableStoreError> for CausalWorkspaceError {
+    fn from(error: TableStoreError) -> Self {
+        Self::Table(error)
+    }
+}
+
+impl From<PrepareCommandError> for CausalWorkspaceError {
+    fn from(error: PrepareCommandError) -> Self {
+        Self::Prepare(error)
+    }
+}
+
+struct StagedAggregate<A> {
+    identity: StreamIdentity,
+    aggregate: A,
+    snapshot_version: Option<u64>,
+}
+
+struct WorkspaceState<A> {
+    aggregates: Vec<StagedAggregate<A>>,
+    identities: HashSet<StreamIdentity>,
+    outbox_messages: Vec<OutboxMessage>,
+    read_model_plans: Vec<TableWritePlan>,
+    snapshots: Vec<SnapshotWrite>,
+    projection_staged: bool,
+}
+
+impl<A> Default for WorkspaceState<A> {
+    fn default() -> Self {
+        Self {
+            aggregates: Vec::new(),
+            identities: HashSet::new(),
+            outbox_messages: Vec::new(),
+            read_model_plans: Vec::new(),
+            snapshots: Vec::new(),
+            projection_staged: false,
+        }
+    }
+}
+
+/// A handler-scoped unit of work. The concrete repository is erased and never
+/// exposed through this type.
+pub(crate) struct CausalWorkspace<'repo, A>
+where
+    A: Aggregate + Send + Sync + 'static,
+{
+    store: Box<dyn CausalAggregateStore<A> + 'repo>,
+    state: Mutex<WorkspaceState<A>>,
+}
+
+impl<'repo, A> CausalWorkspace<'repo, A>
+where
+    A: Aggregate + Send + Sync + 'static,
+{
+    pub(crate) fn new<R>(repository: &'repo AggregateRepository<R, A>) -> Self
+    where
+        R: CausalGetStream + 'repo,
+    {
+        Self {
+            store: Box::new(AggregateStoreRef { repository }),
+            state: Mutex::new(WorkspaceState::default()),
+        }
+    }
+
+    /// Load a full stream through the explicit causal/non-locking capability.
+    pub(crate) async fn load(
+        &self,
+        id: &str,
+    ) -> Result<Option<AggregateCheckout<A>>, CausalWorkspaceError> {
+        let identity = StreamIdentity::new(A::aggregate_type(), id)?;
+        Ok(self
+            .store
+            .load(&identity)
+            .await?
+            .map(|aggregate| AggregateCheckout::loaded(identity, aggregate)))
+    }
+
+    /// Create an empty owned checkout. The aggregate must establish a valid ID
+    /// before it is staged.
+    pub(crate) fn create(&self) -> AggregateCheckout<A> {
+        AggregateCheckout::new(A::new_empty())
+    }
+
+    /// Return a checkout to the unit of work after validating the original
+    /// identity/version fence and duplicate stream membership.
+    pub(crate) fn stage(&self, checkout: AggregateCheckout<A>) -> Result<(), CausalWorkspaceError> {
+        let AggregateCheckout { aggregate, origin } = checkout;
+        let identity = StreamIdentity::new(A::aggregate_type(), aggregate.entity().id())?;
+        let committed_version = aggregate.entity().committed_version();
+
+        match origin {
+            CheckoutOrigin::New => {
+                if committed_version != 0 {
+                    return Err(CausalWorkspaceError::CommittedVersionChanged {
+                        identity,
+                        original: 0,
+                        current: committed_version,
+                    });
+                }
+            }
+            CheckoutOrigin::Loaded {
+                identity: original_identity,
+                committed_version: original_version,
+            } => {
+                if identity != original_identity {
+                    return Err(CausalWorkspaceError::IdentityChanged {
+                        original: original_identity,
+                        current: identity,
+                    });
+                }
+                if committed_version != original_version {
+                    return Err(CausalWorkspaceError::CommittedVersionChanged {
+                        identity,
+                        original: original_version,
+                        current: committed_version,
+                    });
+                }
+            }
+        }
+
+        let (mut snapshots, snapshot_version) = self.store.snapshot_writes(&aggregate)?;
+        let mut state = self
+            .state
+            .lock()
+            .map_err(|_| CausalWorkspaceError::Poisoned)?;
+        if !state.identities.insert(identity.clone()) {
+            return Err(CausalWorkspaceError::DuplicateStream(identity));
+        }
+        state.snapshots.append(&mut snapshots);
+        state.aggregates.push(StagedAggregate {
+            identity,
+            aggregate,
+            snapshot_version,
+        });
+        Ok(())
+    }
+
+    pub(crate) fn stage_outbox(&self, message: OutboxMessage) -> Result<(), CausalWorkspaceError> {
+        self.state
+            .lock()
+            .map_err(|_| CausalWorkspaceError::Poisoned)?
+            .outbox_messages
+            .push(message);
+        Ok(())
+    }
+
+    pub(crate) fn stage_read_models(
+        &self,
+        builder: ReadModelWritePlanBuilder,
+    ) -> Result<(), CausalWorkspaceError> {
+        let plan = builder.into_write_plan()?;
+        self.stage_read_model_plan(plan)
+    }
+
+    pub(crate) fn stage_read_model_plan(
+        &self,
+        plan: TableWritePlan,
+    ) -> Result<(), CausalWorkspaceError> {
+        plan.validate()?;
+        self.state
+            .lock()
+            .map_err(|_| CausalWorkspaceError::Poisoned)?
+            .read_model_plans
+            .push(plan);
+        Ok(())
+    }
+
+    /// Atomically stage the returned view as one full-row upsert and prepare a
+    /// non-forgeable `Projected<M>` completion tied to that exact row.
+    pub(crate) fn prepare_projected<M>(
+        &self,
+        model: M,
+    ) -> Result<PreparedCommand<Projected<M>>, CausalWorkspaceError>
+    where
+        M: GraphqlOutputType + RelationalReadModel + Serialize + Send + Sync + 'static,
+    {
+        let mut builder = ReadModelWritePlanBuilder::new();
+        builder.upsert(&model)?;
+        let plan = builder.into_write_plan()?;
+        let proof = ProjectionCommitProof::for_model(&model)?;
+        let prepared = PreparedCommand::prepare_projected(model, proof)?;
+
+        let mut state = self
+            .state
+            .lock()
+            .map_err(|_| CausalWorkspaceError::Poisoned)?;
+        if state.projection_staged {
+            return Err(CausalWorkspaceError::ProjectionAlreadyStaged);
+        }
+        state.projection_staged = true;
+        state.read_model_plans.push(plan);
+        Ok(prepared)
+    }
+
+    pub(crate) fn into_parts(self) -> Result<CausalWorkspaceParts<A>, CausalWorkspaceError> {
+        let state = self
+            .state
+            .into_inner()
+            .map_err(|_| CausalWorkspaceError::Poisoned)?;
+        Ok(CausalWorkspaceParts {
+            aggregates: state.aggregates,
+            outbox_messages: state.outbox_messages,
+            read_model_plans: state.read_model_plans,
+            snapshots: state.snapshots,
+            batch_prepared: false,
+        })
+    }
+}
+
+/// Owned staged work retained by the dispatcher between handler completion and
+/// construction of the ledger-fenced commit batch.
+pub(crate) struct CausalWorkspaceParts<A> {
+    aggregates: Vec<StagedAggregate<A>>,
+    outbox_messages: Vec<OutboxMessage>,
+    read_model_plans: Vec<TableWritePlan>,
+    snapshots: Vec<SnapshotWrite>,
+    batch_prepared: bool,
+}
+
+impl<A> CausalWorkspaceParts<A>
+where
+    A: Aggregate,
+{
+    pub(crate) fn validate_prepared<K: CommandOutcome>(
+        &self,
+        contract: &TypedCommandContract,
+        prepared: &PreparedCommand<K>,
+    ) -> Result<(), CommandCommitProofError> {
+        prepared.validate_commit_evidence(
+            contract,
+            self.aggregates
+                .iter()
+                .any(|staged| !staged.aggregate.entity().new_events().is_empty()),
+            &self.outbox_messages,
+            &self.read_model_plans,
+        )
+    }
+
+    /// Seal the proof-matched projected row into the repository's private
+    /// direct-projection participant. This must run after evidence validation
+    /// and before the remaining ordinary table plans become a commit batch.
+    pub(crate) fn seal_direct_projection<K: CommandOutcome>(
+        &mut self,
+        prepared: &PreparedCommand<K>,
+        target: Option<ResolvedDirectProjectionTarget>,
+        causation_id: &str,
+    ) -> Result<Option<SameTransactionProjectionBatch>, CommandCommitProofError> {
+        prepared.seal_direct_projection(target, &mut self.read_model_plans, causation_id)
+    }
+
+    /// Borrow staged aggregates into the existing public commit-batch shape.
+    /// This is one-shot because its owned participants move into the batch.
+    pub(crate) fn prepare_commit_batch(&mut self) -> Result<CommitBatch<'_>, CausalWorkspaceError> {
+        if self.batch_prepared {
+            return Err(CausalWorkspaceError::CommitBatchAlreadyPrepared);
+        }
+        self.batch_prepared = true;
+
+        // Preserve ordinary AggregateCommit source metadata when the causal
+        // unit of work has one unambiguous source aggregate. A multi-aggregate
+        // command must associate each message explicitly (for example through
+        // OutboxMessage::domain_event); guessing would create false ordering
+        // evidence for downstream projectors.
+        if let [staged] = self.aggregates.as_slice() {
+            for message in &mut self.outbox_messages {
+                message.set_source(&staged.aggregate);
+            }
+        }
+
+        let streams = self
+            .aggregates
+            .iter_mut()
+            .map(|staged| StreamWrite::new(staged.identity.clone(), staged.aggregate.entity_mut()))
+            .collect();
+        let mut batch = CommitBatch::new(streams);
+        batch.outbox_messages = std::mem::take(&mut self.outbox_messages);
+        batch.read_model_plans = std::mem::take(&mut self.read_model_plans);
+        batch.snapshots = std::mem::take(&mut self.snapshots);
+        Ok(batch)
+    }
+
+    /// Apply snapshot cache bookkeeping only after the fenced commit succeeds.
+    pub(crate) fn mark_snapshot_versions_committed(&mut self) {
+        for staged in &mut self.aggregates {
+            if let Some(version) = staged.snapshot_version {
+                staged.aggregate.entity_mut().set_snapshot_version(version);
+            }
+        }
+    }
+
+    #[cfg(test)]
+    fn aggregate_count(&self) -> usize {
+        self.aggregates.len()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Arc;
+
+    use crate::entity::{Entity, EventRecord};
+    use crate::graphql::{GraphqlTypeDef, GraphqlTypeField};
+    use crate::table::{
+        ColumnType, PrimaryKey, RowKey, RowValue, RowValues, TableColumn, TableKind, TableMutation,
+        TableSchema,
+    };
+
+    #[derive(Clone, Default)]
+    struct TestAggregate {
+        entity: Entity,
+    }
+
+    impl Aggregate for TestAggregate {
+        type ReplayError = String;
+
+        fn aggregate_type() -> &'static str {
+            "workspace_test"
+        }
+
+        fn entity(&self) -> &Entity {
+            &self.entity
+        }
+
+        fn entity_mut(&mut self) -> &mut Entity {
+            &mut self.entity
+        }
+
+        fn replay_event(&mut self, _event: &EventRecord) -> Result<(), Self::ReplayError> {
+            Ok(())
+        }
+    }
+
+    #[derive(Clone)]
+    struct TestRepo {
+        entity: Arc<Entity>,
+    }
+
+    impl CausalGetStream for TestRepo {
+        fn get_causal_stream<'a>(
+            &'a self,
+            identity: &'a StreamIdentity,
+        ) -> impl Future<Output = Result<Option<Entity>, RepositoryError>> + Send + 'a {
+            async move {
+                Ok((identity.aggregate_id() == self.entity.id()).then(|| (*self.entity).clone()))
+            }
+        }
+    }
+
+    #[derive(Clone, Debug, Serialize)]
+    struct TestView {
+        id: String,
+        title: String,
+    }
+
+    impl RelationalReadModel for TestView {
+        fn schema() -> &'static TableSchema {
+            static SCHEMA: std::sync::LazyLock<TableSchema> =
+                std::sync::LazyLock::new(|| TableSchema {
+                    model_name: "TestView".into(),
+                    table_name: "test_views".into(),
+                    columns: vec![
+                        TableColumn {
+                            primary_key: true,
+                            ..TableColumn::new("id", "id", ColumnType::Text)
+                        },
+                        TableColumn::new("title", "title", ColumnType::Text),
+                    ],
+                    primary_key: PrimaryKey::new(["id"]),
+                    version_column: None,
+                    foreign_keys: Vec::new(),
+                    indexes: Vec::new(),
+                    relationships: Vec::new(),
+                    kind: TableKind::ReadModel,
+                });
+            &SCHEMA
+        }
+
+        fn primary_key(&self) -> Result<RowKey, TableStoreError> {
+            Ok(RowKey::new([(
+                "id",
+                crate::table::RowValue::String(self.id.clone()),
+            )]))
+        }
+
+        fn to_row(&self) -> Result<RowValues, TableStoreError> {
+            let mut values = RowValues::new();
+            values.insert("id", crate::table::RowValue::String(self.id.clone()));
+            values.insert("title", crate::table::RowValue::String(self.title.clone()));
+            Ok(values)
+        }
+
+        fn from_row(row: RowValues) -> Result<Self, TableStoreError> {
+            Ok(Self {
+                id: row.get_serde("id")?,
+                title: row.get_serde("title")?,
+            })
+        }
+    }
+
+    impl GraphqlOutputType for TestView {
+        fn graphql_type() -> GraphqlTypeDef {
+            GraphqlTypeDef::new(
+                "TestView",
+                vec![
+                    GraphqlTypeField {
+                        name: "id".into(),
+                        type_name: "String".into(),
+                        nullable: false,
+                        list: false,
+                        item_nullable: false,
+                        nested: None,
+                    },
+                    GraphqlTypeField {
+                        name: "title".into(),
+                        type_name: "String".into(),
+                        nullable: false,
+                        list: false,
+                        item_nullable: false,
+                        nested: None,
+                    },
+                ],
+            )
+            .with_type_id(std::any::TypeId::of::<Self>())
+        }
+    }
+
+    #[derive(serde::Deserialize)]
+    struct TestInput {}
+
+    impl crate::graphql::GraphqlInputType for TestInput {
+        fn graphql_type() -> GraphqlTypeDef {
+            GraphqlTypeDef::new("TestInput", Vec::new())
+                .with_type_id(std::any::TypeId::of::<Self>())
+        }
+    }
+
+    fn loaded_repo() -> AggregateRepository<TestRepo, TestAggregate> {
+        let mut entity = Entity::with_id("a-1");
+        entity
+            .digest_empty("Created")
+            .expect("test event should encode");
+        entity.mark_committed();
+        AggregateRepository::new(TestRepo {
+            entity: Arc::new(entity),
+        })
+    }
+
+    #[tokio::test]
+    async fn load_is_owned_and_stage_rejects_identity_and_version_tampering() {
+        let repository = loaded_repo();
+        let workspace = CausalWorkspace::new(&repository);
+
+        let mut renamed = workspace.load("a-1").await.unwrap().unwrap();
+        renamed.entity_mut().set_id("other");
+        assert!(matches!(
+            workspace.stage(renamed),
+            Err(CausalWorkspaceError::IdentityChanged { .. })
+        ));
+
+        let mut version_changed = workspace.load("a-1").await.unwrap().unwrap();
+        version_changed.entity_mut().load_from_history(Vec::new());
+        assert!(matches!(
+            workspace.stage(version_changed),
+            Err(CausalWorkspaceError::CommittedVersionChanged { .. })
+        ));
+    }
+
+    #[tokio::test]
+    async fn duplicate_streams_are_rejected_without_repository_locks() {
+        let repository = loaded_repo();
+        let workspace = CausalWorkspace::new(&repository);
+        let first = workspace.load("a-1").await.unwrap().unwrap();
+        let second = workspace.load("a-1").await.unwrap().unwrap();
+        workspace.stage(first).unwrap();
+        assert!(matches!(
+            workspace.stage(second),
+            Err(CausalWorkspaceError::DuplicateStream(_))
+        ));
+    }
+
+    #[tokio::test]
+    async fn create_stages_a_new_owned_aggregate_after_it_establishes_identity() {
+        let repository = loaded_repo();
+        let workspace = CausalWorkspace::new(&repository);
+        let mut checkout = workspace.create();
+        checkout.entity_mut().set_id("new-aggregate");
+        checkout.entity_mut().digest_empty("Created").unwrap();
+
+        workspace.stage(checkout).unwrap();
+
+        let parts = workspace.into_parts().unwrap();
+        assert_eq!(parts.aggregate_count(), 1);
+    }
+
+    #[tokio::test]
+    async fn workspace_drains_all_commit_participants_once() {
+        let repository = loaded_repo();
+        let workspace = CausalWorkspace::new(&repository);
+        let mut checkout = workspace.load("a-1").await.unwrap().unwrap();
+        checkout.entity_mut().digest_empty("Changed").unwrap();
+        workspace.stage(checkout).unwrap();
+        workspace
+            .stage_outbox(OutboxMessage::create("m-1", "test.changed", vec![1]).unwrap())
+            .unwrap();
+        let mut plan = ReadModelWritePlanBuilder::new();
+        plan.upsert(&TestView {
+            id: "v-1".into(),
+            title: "first".into(),
+        })
+        .unwrap();
+        workspace.stage_read_models(plan).unwrap();
+
+        let mut parts = workspace.into_parts().unwrap();
+        assert_eq!(parts.aggregate_count(), 1);
+        {
+            let batch = parts.prepare_commit_batch().unwrap();
+            assert_eq!(batch.streams.len(), 1);
+            assert_eq!(batch.outbox_messages.len(), 1);
+            assert_eq!(batch.read_model_plans.len(), 1);
+            assert_eq!(
+                batch.outbox_messages[0].source_aggregate_type.as_deref(),
+                Some(TestAggregate::aggregate_type())
+            );
+            assert_eq!(
+                batch.outbox_messages[0].source_aggregate_id.as_deref(),
+                Some("a-1")
+            );
+            assert_eq!(batch.outbox_messages[0].source_sequence, Some(2));
+        }
+        assert!(matches!(
+            parts.prepare_commit_batch(),
+            Err(CausalWorkspaceError::CommitBatchAlreadyPrepared)
+        ));
+    }
+
+    #[tokio::test]
+    async fn projected_result_is_tied_to_one_exact_staged_upsert() {
+        let repository = loaded_repo();
+        let workspace = CausalWorkspace::new(&repository);
+        let view = TestView {
+            id: "v-1".into(),
+            title: "projected".into(),
+        };
+        let prepared = workspace.prepare_projected(view).unwrap();
+        let mut aggregate = workspace.load("a-1").await.unwrap().unwrap();
+        aggregate.entity_mut().digest_empty("Projected").unwrap();
+        workspace.stage(aggregate).unwrap();
+        let parts = workspace.into_parts().unwrap();
+
+        let contract =
+            crate::graphql::typed_command::<TestInput, Projected<TestView>>("test.project")
+                .into_contract();
+        parts.validate_prepared(&contract, &prepared).unwrap();
+    }
+
+    #[tokio::test]
+    async fn projected_result_requires_a_durable_domain_fact() {
+        let repository = loaded_repo();
+        let workspace = CausalWorkspace::new(&repository);
+        let prepared = workspace
+            .prepare_projected(TestView {
+                id: "v-1".into(),
+                title: "projected".into(),
+            })
+            .unwrap();
+        let parts = workspace.into_parts().unwrap();
+        let contract =
+            crate::graphql::typed_command::<TestInput, Projected<TestView>>("test.project")
+                .into_contract();
+
+        assert!(matches!(
+            parts.validate_prepared(&contract, &prepared),
+            Err(CommandCommitProofError::DurableFactMissing)
+        ));
+    }
+
+    #[tokio::test]
+    async fn projected_proof_rejects_a_second_write_to_the_returned_key() {
+        let repository = loaded_repo();
+        let workspace = CausalWorkspace::new(&repository);
+        let prepared = workspace
+            .prepare_projected(TestView {
+                id: "v-1".into(),
+                title: "returned".into(),
+            })
+            .unwrap();
+        workspace
+            .stage_outbox(OutboxMessage::create("projection-2", "test.changed", vec![]).unwrap())
+            .unwrap();
+        let mut conflicting = ReadModelWritePlanBuilder::new();
+        conflicting
+            .upsert(&TestView {
+                id: "v-1".into(),
+                title: "overwritten".into(),
+            })
+            .unwrap();
+        workspace.stage_read_models(conflicting).unwrap();
+        let parts = workspace.into_parts().unwrap();
+        let contract =
+            crate::graphql::typed_command::<TestInput, Projected<TestView>>("test.project")
+                .into_contract();
+
+        assert!(matches!(
+            parts.validate_prepared(&contract, &prepared),
+            Err(CommandCommitProofError::ProjectionWriteConflict { .. })
+        ));
+    }
+
+    #[tokio::test]
+    async fn projected_proof_rejects_row_drift_after_preparation() {
+        let repository = loaded_repo();
+        let workspace = CausalWorkspace::new(&repository);
+        let prepared = workspace
+            .prepare_projected(TestView {
+                id: "v-1".into(),
+                title: "returned".into(),
+            })
+            .unwrap();
+        workspace
+            .stage_outbox(OutboxMessage::create("projection-3", "test.changed", vec![]).unwrap())
+            .unwrap();
+        let mut parts = workspace.into_parts().unwrap();
+        let TableMutation::UpsertRow(mutation) = &mut parts.read_model_plans[0].mutations[0] else {
+            panic!("projected preparation must stage a full-row upsert");
+        };
+        mutation
+            .values
+            .insert("title", RowValue::String("different".into()));
+        let contract =
+            crate::graphql::typed_command::<TestInput, Projected<TestView>>("test.project")
+                .into_contract();
+
+        assert!(matches!(
+            parts.validate_prepared(&contract, &prepared),
+            Err(CommandCommitProofError::ProjectionWriteMismatch { .. })
+        ));
+    }
+}
diff --git a/src/microsvc/dependencies.rs b/src/microsvc/dependencies.rs
index 9615ff85..0cdb2633 100644
--- a/src/microsvc/dependencies.rs
+++ b/src/microsvc/dependencies.rs
@@ -1,7 +1,11 @@
 //! Typed dependency wrappers for microsvc handlers.
 
-use crate::aggregate::AggregateRepository;
+use crate::aggregate::{Aggregate, AggregateRepository};
+use crate::command_ledger::{
+    CausalGetStream, CausalRepositoryIdentity, CausalTransactionalCommit, CommandLedgerStore,
+};
 use crate::outbox::OutboxPublisherConfig;
+use crate::projection_protocol::ProjectionProtocolStore;
 use crate::repository::{ReadModelWritePlanStore, RelationalReadModelQueryStore, Repository};
 
 /// Dependency capability for services that expose an aggregate repository.
@@ -11,6 +15,53 @@ pub trait HasRepo {
     fn repo(&self) -> &Self::Repo;
 }
 
+/// Sealed repository capability required by typed causal routes.
+///
+/// The framework implements this for its causal-capable repository adapters;
+/// applications never need to name or implement it.
+#[doc(hidden)]
+#[allow(private_bounds)]
+pub trait CausalRepositoryBackend:
+    CausalGetStream
+    + CommandLedgerStore
+    + CausalTransactionalCommit
+    + CausalRepositoryIdentity
+    + ProjectionProtocolStore
+    + Send
+    + Sync
+    + 'static
+{
+}
+
+impl<T> CausalRepositoryBackend for T where
+    T: CausalGetStream
+        + CommandLedgerStore
+        + CausalTransactionalCommit
+        + CausalRepositoryIdentity
+        + ProjectionProtocolStore
+        + Send
+        + Sync
+        + 'static
+{
+}
+
+/// Compile-time extraction of the one aggregate repository owned by a typed
+/// causal route bundle.
+///
+/// This is public only because it appears in the bounds of the public route
+/// builder; the framework supplies the implementations. Application handlers
+/// never receive the dependency value or the underlying backend through the
+/// causal command context.
+#[doc(hidden)]
+pub trait CausalRouteDependencies {
+    type Backend: CausalRepositoryBackend;
+    type Aggregate: Aggregate;
+
+    #[doc(hidden)]
+    fn __causal_aggregate_repository(&self)
+        -> &AggregateRepository<Self::Backend, Self::Aggregate>;
+}
+
 /// Dependency capability for services that expose a read-model store.
 pub trait HasReadModelStore {
     type ReadModelStore;
@@ -18,6 +69,38 @@ pub trait HasReadModelStore {
     fn read_model_store(&self) -> &Self::ReadModelStore;
 }
 
+/// Sealed storage capability required by framework-owned causal projector
+/// routes. Applications select one of the framework repository adapters; they
+/// never receive this commit capability in a projector handler.
+#[doc(hidden)]
+#[allow(private_bounds)]
+pub trait CausalProjectionStore: ProjectionProtocolStore + Clone + Send + Sync + 'static {}
+
+impl<T> CausalProjectionStore for T where T: ProjectionProtocolStore + Clone + Send + Sync + 'static {}
+
+/// Compile-time extraction of the read-model/projection store owned by a route
+/// bundle. Public only because it appears in the causal-projector builder's
+/// inferred bounds.
+#[doc(hidden)]
+pub trait CausalProjectionRouteDependencies {
+    type Store: CausalProjectionStore;
+
+    #[doc(hidden)]
+    fn __causal_projection_store(&self) -> &Self::Store;
+}
+
+impl<D> CausalProjectionRouteDependencies for D
+where
+    D: HasReadModelStore,
+    D::ReadModelStore: CausalProjectionStore,
+{
+    type Store = D::ReadModelStore;
+
+    fn __causal_projection_store(&self) -> &Self::Store {
+        self.read_model_store()
+    }
+}
+
 /// Dependency capability for repositories whose outbox commits can publish
 /// immediately.
 ///
@@ -130,6 +213,19 @@ impl<R, A> HasRepo for AggregateRepository<R, A> {
     }
 }
 
+impl<R, A> CausalRouteDependencies for AggregateRepository<R, A>
+where
+    R: CausalRepositoryBackend,
+    A: Aggregate,
+{
+    type Backend = R;
+    type Aggregate = A;
+
+    fn __causal_aggregate_repository(&self) -> &AggregateRepository<R, A> {
+        self
+    }
+}
+
 impl<S> HasReadModelStore for S
 where
     S: ReadModelWritePlanStore + RelationalReadModelQueryStore,
@@ -161,6 +257,19 @@ impl<R> HasRepo for RepoDependencies<R> {
     }
 }
 
+impl<R, A> CausalRouteDependencies for RepoDependencies<AggregateRepository<R, A>>
+where
+    R: CausalRepositoryBackend,
+    A: Aggregate,
+{
+    type Backend = R;
+    type Aggregate = A;
+
+    fn __causal_aggregate_repository(&self) -> &AggregateRepository<R, A> {
+        &self.repo
+    }
+}
+
 /// Dependencies for a service that only needs a read-model store.
 #[derive(Clone)]
 pub struct ReadModelStoreDependencies<S> {
@@ -206,6 +315,19 @@ impl<R, S> HasRepo for RepoReadModelDependencies<R, S> {
     }
 }
 
+impl<R, A, S> CausalRouteDependencies for RepoReadModelDependencies<AggregateRepository<R, A>, S>
+where
+    R: CausalRepositoryBackend,
+    A: Aggregate,
+{
+    type Backend = R;
+    type Aggregate = A;
+
+    fn __causal_aggregate_repository(&self) -> &AggregateRepository<R, A> {
+        &self.repo
+    }
+}
+
 impl<R, S> HasReadModelStore for RepoReadModelDependencies<R, S> {
     type ReadModelStore = S;
 
diff --git a/src/microsvc/error.rs b/src/microsvc/error.rs
index faeb341b..437eb8e4 100644
--- a/src/microsvc/error.rs
+++ b/src/microsvc/error.rs
@@ -3,8 +3,11 @@
 use std::error::Error;
 use std::fmt;
 
+use super::projector::ProjectionRepairHandle;
 use crate::bus::{PayloadDecodeError, TransportError, TransportErrorKind};
 use crate::lock::RetryClass;
+use crate::projection_protocol::ProjectionProtocolError;
+use crate::table::TableStoreError;
 use crate::{repository::RepositoryError, EventRecordError};
 
 /// Error type for command handler operations.
@@ -25,6 +28,22 @@ pub enum HandlerError {
     Repository(RepositoryError),
     /// Guard rejected the command (input validation failed).
     GuardRejected(String),
+    /// Causal projection protocol/storage failure.
+    Projection(ProjectionProtocolError),
+    /// A causal projector route was reached without adapter-authenticated
+    /// ordered delivery or another required stable envelope identity.
+    UnqualifiedProjectionDelivery(String),
+    /// An explicitly repaired partition is waiting for its exact failed input;
+    /// unrelated delivery must remain retryable and cannot invoke the handler.
+    ProjectionRepairPending { failure_id: String },
+    /// The terminal failure is already durable. The transport must retain this
+    /// exact delivery and stop so an operator can repair then restart.
+    ProjectionTerminalRecorded { repair: ProjectionRepairHandle },
+    /// A permanent causal-projector failure could not be represented by a
+    /// durable terminal record. The transport must retain this exact delivery
+    /// and stop rather than applying an ordinary dead-letter/drop policy across
+    /// an unproven causal gap.
+    ProjectionDeliveryHalted { source: Box<HandlerError> },
     /// Other error.
     Other(Box<dyn Error + Send + Sync>),
 }
@@ -41,6 +60,22 @@ impl fmt::Display for HandlerError {
             HandlerError::GuardRejected(name) => {
                 write!(f, "guard rejected command: {}", name)
             }
+            HandlerError::Projection(error) => write!(f, "projection error: {error}"),
+            HandlerError::UnqualifiedProjectionDelivery(message) => {
+                write!(f, "unqualified causal projector delivery: {message}")
+            }
+            HandlerError::ProjectionRepairPending { failure_id } => write!(
+                f,
+                "projection repair is waiting for exact failed input `{failure_id}`"
+            ),
+            HandlerError::ProjectionTerminalRecorded { repair } => write!(
+                f,
+                "projection terminal failure `{}` was recorded; retain delivery and stop; repair handle: {repair}",
+                repair.failure_id()
+            ),
+            HandlerError::ProjectionDeliveryHalted { .. } => f.write_str(
+                "causal projector delivery halted before a durable terminal record was available; retain delivery and stop",
+            ),
             HandlerError::Other(e) => write!(f, "handler error: {}", e),
         }
     }
@@ -50,6 +85,8 @@ impl Error for HandlerError {
     fn source(&self) -> Option<&(dyn Error + 'static)> {
         match self {
             HandlerError::Repository(e) => Some(e),
+            HandlerError::Projection(e) => Some(e),
+            HandlerError::ProjectionDeliveryHalted { source } => Some(source.as_ref()),
             HandlerError::Other(e) => Some(e.as_ref()),
             _ => None,
         }
@@ -68,6 +105,18 @@ impl From<EventRecordError> for HandlerError {
     }
 }
 
+impl From<ProjectionProtocolError> for HandlerError {
+    fn from(error: ProjectionProtocolError) -> Self {
+        Self::Projection(error)
+    }
+}
+
+impl From<TableStoreError> for HandlerError {
+    fn from(error: TableStoreError) -> Self {
+        Self::Projection(error.into())
+    }
+}
+
 impl From<serde_json::Error> for HandlerError {
     fn from(err: serde_json::Error) -> Self {
         HandlerError::DecodeFailed(err.to_string())
@@ -81,6 +130,15 @@ impl From<PayloadDecodeError> for HandlerError {
 }
 
 impl HandlerError {
+    /// Return the opaque operator repair handle carried by a durably recorded
+    /// terminal projector failure.
+    pub fn projection_repair_handle(&self) -> Option<&ProjectionRepairHandle> {
+        match self {
+            Self::ProjectionTerminalRecorded { repair } => Some(repair),
+            _ => None,
+        }
+    }
+
     /// Map this error to an HTTP-style status code.
     pub fn status_code(&self) -> u16 {
         match self {
@@ -91,6 +149,11 @@ impl HandlerError {
             HandlerError::Unauthorized(_) => 401,
             HandlerError::Repository(_) => 500,
             HandlerError::GuardRejected(_) => 400,
+            HandlerError::Projection(_)
+            | HandlerError::UnqualifiedProjectionDelivery(_)
+            | HandlerError::ProjectionRepairPending { .. }
+            | HandlerError::ProjectionTerminalRecorded { .. }
+            | HandlerError::ProjectionDeliveryHalted { .. } => 500,
             HandlerError::Other(_) => 500,
         }
     }
@@ -131,14 +194,30 @@ impl HandlerError {
                 RetryClass::Retryable => TransportErrorKind::Retryable,
                 RetryClass::Permanent => TransportErrorKind::Permanent,
             },
-            HandlerError::NotFound(_) | HandlerError::Other(_) => TransportErrorKind::Retryable,
+            HandlerError::Projection(error) => {
+                if super::projector::projection_error_is_retryable(error) {
+                    TransportErrorKind::Retryable
+                } else {
+                    TransportErrorKind::Permanent
+                }
+            }
+            HandlerError::ProjectionRepairPending { .. }
+            | HandlerError::NotFound(_)
+            | HandlerError::Other(_) => TransportErrorKind::Retryable,
+            HandlerError::ProjectionTerminalRecorded { .. }
+            | HandlerError::ProjectionDeliveryHalted { .. } => TransportErrorKind::Permanent,
             HandlerError::UnknownCommand(_)
             | HandlerError::DecodeFailed(_)
             | HandlerError::Rejected(_)
             | HandlerError::Unauthorized(_)
-            | HandlerError::GuardRejected(_) => TransportErrorKind::Permanent,
+            | HandlerError::GuardRejected(_)
+            | HandlerError::UnqualifiedProjectionDelivery(_) => TransportErrorKind::Permanent,
         }
     }
+
+    pub(crate) fn is_projection_retryable(&self) -> bool {
+        self.transport_error_kind().is_retryable()
+    }
 }
 
 /// Classify and convert a handler error into the transport's retryable/permanent
@@ -147,7 +226,17 @@ impl HandlerError {
 impl From<HandlerError> for TransportError {
     fn from(error: HandlerError) -> Self {
         let kind = error.transport_error_kind();
-        TransportError::new(kind, error.to_string()).with_source(error)
+        let retain_and_stop = matches!(
+            error,
+            HandlerError::ProjectionTerminalRecorded { .. }
+                | HandlerError::ProjectionDeliveryHalted { .. }
+        );
+        let transport = TransportError::new(kind, error.to_string()).with_source(error);
+        if retain_and_stop {
+            transport.retain_and_stop()
+        } else {
+            transport
+        }
     }
 }
 
diff --git a/src/microsvc/http.rs b/src/microsvc/http.rs
index b1ef5328..4f5e34c3 100644
--- a/src/microsvc/http.rs
+++ b/src/microsvc/http.rs
@@ -46,12 +46,37 @@ use super::session::Session;
 use super::MAX_HTTP_BODY_BYTES;
 
 /// Build an axum `Router` that dispatches commands via the given service.
+///
+/// By default mounts `POST /{command}`. Call [`Service::without_http_command_routes`]
+/// for GraphQL-only surfaces (health + GraphQL; no per-command HTTP).
 pub fn router(service: Arc<Service>) -> Router {
-    let router = Router::new()
-        .route("/health", get(health_handler))
-        .route("/{command}", axum::routing::post(command_handler));
+    let mut router = Router::new().route("/health", get(health_handler));
+    if service.http_command_routes_enabled() {
+        router = router.route("/{command}", axum::routing::post(command_handler));
+    }
     #[cfg(feature = "metrics")]
-    let router = router.route("/metrics", get(metrics_handler));
+    {
+        router = router.route("/metrics", get(metrics_handler));
+    }
+
+    // GraphQL must be registered before the body-limit layer so the limit wraps it.
+    // POST /graphql: queries/mutations. GET /graphql: GraphiQL.
+    // GET /graphql/ws: WebSocket subscriptions (graphql-ws protocol).
+    #[cfg(feature = "graphql")]
+    {
+        if service.graphql_engine().is_some() {
+            router = router
+                .route(
+                    "/graphql",
+                    axum::routing::post(crate::graphql::http::microsvc_graphql_handler)
+                        .get(crate::graphql::http::microsvc_graphql_get),
+                )
+                .route(
+                    "/graphql/ws",
+                    axum::routing::get(crate::graphql::http::microsvc_graphql_ws),
+                );
+        }
+    }
 
     router
         // Pin the body limit explicitly rather than relying on axum's default;
@@ -70,7 +95,19 @@ pub async fn serve(service: Arc<Service>, addr: &str) -> Result<(), std::io::Err
 /// `GET /health` — returns `{ "ok": true, "commands": [...] }`.
 async fn health_handler(State(service): State<Arc<Service>>) -> impl IntoResponse {
     let commands: Vec<&str> = service.command_names();
-    Json(json!({ "ok": true, "commands": commands }))
+    #[cfg(feature = "graphql")]
+    let body = {
+        let mut v = json!({ "ok": true, "commands": commands });
+        if service.graphql_engine().is_some() {
+            v.as_object_mut()
+                .unwrap()
+                .insert("graphql".into(), json!(true));
+        }
+        v
+    };
+    #[cfg(not(feature = "graphql"))]
+    let body = json!({ "ok": true, "commands": commands });
+    Json(body)
 }
 
 /// `GET /metrics` — returns Prometheus text metrics.
@@ -110,7 +147,13 @@ fn status_for_error(error: &HandlerError) -> StatusCode {
         HandlerError::DecodeFailed(_) | HandlerError::GuardRejected(_) => StatusCode::BAD_REQUEST,
         HandlerError::Rejected(_) => StatusCode::UNPROCESSABLE_ENTITY,
         HandlerError::Unauthorized(_) => StatusCode::UNAUTHORIZED,
-        HandlerError::Repository(_) | HandlerError::Other(_) => StatusCode::INTERNAL_SERVER_ERROR,
+        HandlerError::Repository(_)
+        | HandlerError::Projection(_)
+        | HandlerError::UnqualifiedProjectionDelivery(_)
+        | HandlerError::ProjectionRepairPending { .. }
+        | HandlerError::ProjectionTerminalRecorded { .. }
+        | HandlerError::ProjectionDeliveryHalted { .. }
+        | HandlerError::Other(_) => StatusCode::INTERNAL_SERVER_ERROR,
     }
 }
 
@@ -123,7 +166,7 @@ fn status_for_error(error: &HandlerError) -> StatusCode {
 /// client-supplied identity headers and inject only authenticated ones.
 /// Without that proxy, any client can set those headers and assume any
 /// identity/role. See the [`Session`] docs.
-fn session_from_headers(headers: &HeaderMap) -> Session {
+pub(crate) fn session_from_headers(headers: &HeaderMap) -> Session {
     let mut vars = std::collections::HashMap::new();
     for (name, value) in headers.iter() {
         if let Ok(v) = value.to_str() {
diff --git a/src/microsvc/message_router.rs b/src/microsvc/message_router.rs
index 20c6b4cb..20d21302 100644
--- a/src/microsvc/message_router.rs
+++ b/src/microsvc/message_router.rs
@@ -5,7 +5,7 @@
 //! retryable/permanent vocabulary happens here, on the microsvc side, so the
 //! bus-core runner only ever sees an already-classified `TransportError`.
 
-use crate::bus::{MessageRouter, TransportError};
+use crate::bus::{MessageRouter, OrderedDelivery, TransportError};
 use crate::microsvc::{Message, MessageKind, Service, SubscriptionPlan};
 
 impl MessageRouter for Service {
@@ -28,4 +28,15 @@ impl MessageRouter for Service {
             .map(|_| ())
             .map_err(TransportError::from)
     }
+
+    async fn dispatch_ordered(
+        &self,
+        message: &Message,
+        ordered: Option<&OrderedDelivery>,
+    ) -> Result<(), TransportError> {
+        self.dispatch_ordered_message(message, ordered)
+            .await
+            .map(|_| ())
+            .map_err(TransportError::from)
+    }
 }
diff --git a/src/microsvc/mod.rs b/src/microsvc/mod.rs
index 26837f63..3f49aae1 100644
--- a/src/microsvc/mod.rs
+++ b/src/microsvc/mod.rs
@@ -55,25 +55,42 @@
 //! }
 //! ```
 
+mod causal;
 mod context;
 mod dependencies;
 mod error;
 mod message_router;
+mod projector;
 mod runtime;
 mod service;
 mod session;
 
 pub use crate::bus::{Message, MessageKind, PayloadDecodeError, SubscriptionPlan};
+pub use causal::AggregateCheckout;
 pub use context::Context;
 pub use dependencies::{
-    ConfigurableOutboxPublisher, HasOutboxStore, HasReadModelStore, HasRepo,
-    ReadModelStoreDependencies, RepoDependencies, RepoReadModelDependencies,
+    CausalProjectionRouteDependencies, CausalProjectionStore, CausalRepositoryBackend,
+    CausalRouteDependencies, ConfigurableOutboxPublisher, HasOutboxStore, HasReadModelStore,
+    HasRepo, ReadModelStoreDependencies, RepoDependencies, RepoReadModelDependencies,
 };
 pub use error::HandlerError;
+pub use projector::{
+    CausalProjectorContext, CausalProjectorRouteBuilder, LoadedProjection, ProjectionRepairHandle,
+    ProjectionRepairHandleParseError,
+};
 pub use runtime::{DEFAULT_MAX_PUBLISH_ATTEMPTS, DEFAULT_PUBLISH_LEASE};
+#[cfg(all(feature = "graphql", test))]
+pub(crate) use service::CausalCommandProjectionEvidence;
+#[cfg(feature = "graphql")]
+pub use service::GraphqlServiceBindError;
 pub use service::{
-    CommandRequest, CommandResponse, DeliveryKind, HandlerNames, HandlerSpec, RouteBuilder, Routes,
-    Service,
+    CausalCommandContext, CommandRequest, CommandResponse, DeliveryKind, HandlerNames, HandlerSpec,
+    PreparedCommandHandler, RouteBuilder, Routes, Service, TypedRouteBuilder,
+};
+#[cfg(feature = "graphql")]
+pub(crate) use service::{
+    CausalCommandProjectionObligation, CausalCommandPublicState, CausalCommandPublicStatus,
+    CausalCommandReceiptSource, CausalProjectionEvidenceState,
 };
 pub use session::{Session, ROLE_KEY, USER_ID_KEY};
 
@@ -92,6 +109,10 @@ pub const MAX_HTTP_BODY_BYTES: usize = 1024 * 1024;
 #[cfg(feature = "http")]
 mod http;
 #[cfg(feature = "http")]
+// session_from_headers remains available for microsvc HTTP command path.
+#[allow(unused_imports)]
+pub(crate) use http::session_from_headers;
+#[cfg(feature = "http")]
 pub use http::{router, serve};
 
 // Knative / CloudEvents HTTP ingress (Service-coupled; the bus keeps only the
diff --git a/src/microsvc/projector/context.rs b/src/microsvc/projector/context.rs
new file mode 100644
index 00000000..4d70464f
--- /dev/null
+++ b/src/microsvc/projector/context.rs
@@ -0,0 +1,306 @@
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::{Arc, Mutex};
+
+use crate::bus::Message;
+use crate::projection_protocol::{
+    ProjectionProtocolError, ProjectionProtocolStore, ProjectionQuerySnapshot,
+    ProjectionQuerySnapshotRequest, ProjectionWorkspace, RecordRevision,
+};
+use crate::read_model::RelationalReadModel;
+use crate::table::{RowKey, RowPatch};
+
+use super::super::HandlerError;
+
+pub(super) trait ProjectionSnapshotReader: Send + Sync {
+    fn snapshot<'a>(
+        &'a self,
+        request: &'a ProjectionQuerySnapshotRequest,
+    ) -> Pin<
+        Box<
+            dyn Future<Output = Result<ProjectionQuerySnapshot, ProjectionProtocolError>>
+                + Send
+                + 'a,
+        >,
+    >;
+}
+
+impl<S> ProjectionSnapshotReader for S
+where
+    S: ProjectionProtocolStore,
+{
+    fn snapshot<'a>(
+        &'a self,
+        request: &'a ProjectionQuerySnapshotRequest,
+    ) -> Pin<
+        Box<
+            dyn Future<Output = Result<ProjectionQuerySnapshot, ProjectionProtocolError>>
+                + Send
+                + 'a,
+        >,
+    > {
+        Box::pin(self.projection_query_snapshot(request))
+    }
+}
+
+/// One typed row loaded with the exact protocol revision that fenced the same
+/// adapter snapshot.
+#[derive(Clone, Debug)]
+pub struct LoadedProjection<M> {
+    pub model: M,
+    pub revision: RecordRevision,
+}
+
+/// Framework-owned staging context for one ordered projector input.
+///
+/// The context intentionally exposes no arbitrary message metadata, dependency
+/// value, repository, commit method, or cursor constructor. Handler-visible
+/// semantics are limited to the typed payload plus the stable identity helpers
+/// below, all of which are included in the canonical input fingerprint.
+pub struct CausalProjectorContext {
+    event_name: String,
+    message_id: String,
+    causation_id: String,
+    snapshots: Arc<dyn ProjectionSnapshotReader>,
+    workspace: Arc<Mutex<Option<ProjectionWorkspace>>>,
+}
+
+impl CausalProjectorContext {
+    pub(super) fn new<S>(
+        message: &Message,
+        snapshots: S,
+        workspace: ProjectionWorkspace,
+    ) -> (Self, Arc<Mutex<Option<ProjectionWorkspace>>>)
+    where
+        S: ProjectionSnapshotReader + 'static,
+    {
+        let workspace = Arc::new(Mutex::new(Some(workspace)));
+        (
+            Self {
+                event_name: message.name().to_string(),
+                message_id: message
+                    .id()
+                    .expect("causal projector contexts require a stable message ID")
+                    .to_string(),
+                causation_id: message
+                    .causation_id()
+                    .expect("causal projector contexts require a causation ID")
+                    .to_string(),
+                snapshots: Arc::new(snapshots),
+                workspace: Arc::clone(&workspace),
+            },
+            workspace,
+        )
+    }
+
+    pub fn event_name(&self) -> &str {
+        &self.event_name
+    }
+
+    pub fn message_id(&self) -> &str {
+        &self.message_id
+    }
+
+    pub fn causation_id(&self) -> &str {
+        &self.causation_id
+    }
+
+    /// Load one live row and its exact revision from one adapter snapshot.
+    ///
+    /// Missing rows return `Ok(None)`. A durable tombstone fails closed; use a
+    /// separately loaded tombstone revision with [`recreate`](Self::recreate)
+    /// only in an explicit recovery/migration projector.
+    pub async fn load<M>(&self, key: RowKey) -> Result<Option<LoadedProjection<M>>, HandlerError>
+    where
+        M: RelationalReadModel,
+    {
+        let request = self
+            .workspace
+            .lock()
+            .map_err(|_| unavailable_workspace("build projection load"))?
+            .as_ref()
+            .ok_or_else(|| unavailable_workspace("build projection load"))?
+            .query_snapshot_request::<M>(key)?;
+        let snapshot = self.snapshots.snapshot(&request).await?;
+        match (snapshot.row, snapshot.record) {
+            (None, None) => Ok(None),
+            (Some(row), Some(record)) if !record.tombstone => Ok(Some(LoadedProjection {
+                model: M::from_row(row)?,
+                revision: record.revision,
+            })),
+            (None, Some(record)) if record.tombstone => {
+                Err(ProjectionProtocolError::RecordTombstoned {
+                    model: M::schema().model_name.clone(),
+                }
+                .into())
+            }
+            _ => Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection snapshot for model `{}` returned inconsistent physical/protocol state",
+                M::schema().model_name
+            ))
+            .into()),
+        }
+    }
+
+    /// Load the exact revision of a durable tombstone, if one exists.
+    ///
+    /// This is the explicit companion to [`recreate`](Self::recreate). Live
+    /// records return `Ok(None)`: callers cannot accidentally use a live
+    /// revision to cross the tombstone boundary.
+    pub async fn tombstone_revision<M>(
+        &self,
+        key: RowKey,
+    ) -> Result<Option<RecordRevision>, HandlerError>
+    where
+        M: RelationalReadModel,
+    {
+        let request = self
+            .workspace
+            .lock()
+            .map_err(|_| unavailable_workspace("build projection tombstone load"))?
+            .as_ref()
+            .ok_or_else(|| unavailable_workspace("build projection tombstone load"))?
+            .query_snapshot_request::<M>(key)?;
+        let snapshot = self.snapshots.snapshot(&request).await?;
+        match (snapshot.row, snapshot.record) {
+            (None, None) => Ok(None),
+            (Some(_), Some(record)) if !record.tombstone => Ok(None),
+            (None, Some(record)) if record.tombstone => Ok(Some(record.revision)),
+            _ => Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection snapshot for model `{}` returned inconsistent physical/protocol state",
+                M::schema().model_name
+            ))
+            .into()),
+        }
+    }
+
+    /// The polished full-row path: create a missing record or save a live one
+    /// under the exact revision read from the same adapter snapshot.
+    ///
+    /// It never crosses a tombstone. Concurrent writers are caught again by the
+    /// adapter's atomic revision fence at commit.
+    pub async fn project<M>(&self, model: &M) -> Result<&Self, HandlerError>
+    where
+        M: RelationalReadModel,
+    {
+        let key = model.primary_key()?;
+        let request = self
+            .workspace
+            .lock()
+            .map_err(|_| unavailable_workspace("build projection upsert"))?
+            .as_ref()
+            .ok_or_else(|| unavailable_workspace("build projection upsert"))?
+            .query_snapshot_request::<M>(key)?;
+        let snapshot = self.snapshots.snapshot(&request).await?;
+        let mut workspace = self
+            .workspace
+            .lock()
+            .map_err(|_| unavailable_workspace("stage projection upsert"))?;
+        let workspace = workspace
+            .as_mut()
+            .ok_or_else(|| unavailable_workspace("stage projection upsert"))?;
+        match (snapshot.row, snapshot.record) {
+            (None, None) => {
+                workspace.create(model)?;
+            }
+            (Some(_), Some(record)) if !record.tombstone => {
+                workspace.save(model, &record.revision)?;
+            }
+            (None, Some(record)) if record.tombstone => {
+                return Err(ProjectionProtocolError::RecordTombstoned {
+                    model: M::schema().model_name.clone(),
+                }
+                .into());
+            }
+            _ => {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection snapshot for model `{}` returned inconsistent physical/protocol state",
+                M::schema().model_name
+            ))
+                .into())
+            }
+        }
+        Ok(self)
+    }
+
+    pub fn create<M>(&self, model: &M) -> Result<&Self, HandlerError>
+    where
+        M: RelationalReadModel,
+    {
+        self.workspace
+            .lock()
+            .map_err(|_| unavailable_workspace("stage projection create"))?
+            .as_mut()
+            .ok_or_else(|| unavailable_workspace("stage projection create"))?
+            .create(model)?;
+        Ok(self)
+    }
+
+    pub fn save<M>(&self, model: &M, expected: &RecordRevision) -> Result<&Self, HandlerError>
+    where
+        M: RelationalReadModel,
+    {
+        self.workspace
+            .lock()
+            .map_err(|_| unavailable_workspace("stage projection save"))?
+            .as_mut()
+            .ok_or_else(|| unavailable_workspace("stage projection save"))?
+            .save(model, expected)?;
+        Ok(self)
+    }
+
+    pub fn patch<M>(
+        &self,
+        key: RowKey,
+        patch: RowPatch,
+        expected: &RecordRevision,
+    ) -> Result<&Self, HandlerError>
+    where
+        M: RelationalReadModel,
+    {
+        self.workspace
+            .lock()
+            .map_err(|_| unavailable_workspace("stage projection patch"))?
+            .as_mut()
+            .ok_or_else(|| unavailable_workspace("stage projection patch"))?
+            .patch::<M>(key, patch, expected)?;
+        Ok(self)
+    }
+
+    pub fn delete<M>(&self, key: RowKey, expected: &RecordRevision) -> Result<&Self, HandlerError>
+    where
+        M: RelationalReadModel,
+    {
+        self.workspace
+            .lock()
+            .map_err(|_| unavailable_workspace("stage projection delete"))?
+            .as_mut()
+            .ok_or_else(|| unavailable_workspace("stage projection delete"))?
+            .delete::<M>(key, expected)?;
+        Ok(self)
+    }
+
+    pub fn recreate<M>(
+        &self,
+        model: &M,
+        expected_tombstone: &RecordRevision,
+    ) -> Result<&Self, HandlerError>
+    where
+        M: RelationalReadModel,
+    {
+        self.workspace
+            .lock()
+            .map_err(|_| unavailable_workspace("stage projection recreate"))?
+            .as_mut()
+            .ok_or_else(|| unavailable_workspace("stage projection recreate"))?
+            .recreate(model, expected_tombstone)?;
+        Ok(self)
+    }
+}
+
+pub(super) fn unavailable_workspace(operation: &'static str) -> HandlerError {
+    ProjectionProtocolError::InvalidBatch(format!(
+        "causal projector workspace is unavailable while attempting to {operation}"
+    ))
+    .into()
+}
diff --git a/src/microsvc/projector/errors.rs b/src/microsvc/projector/errors.rs
new file mode 100644
index 00000000..d54b0468
--- /dev/null
+++ b/src/microsvc/projector/errors.rs
@@ -0,0 +1,237 @@
+use sha2::{Digest, Sha256};
+
+use crate::bus::{Message, OrderedDelivery};
+use crate::projection_protocol::{
+    CompiledProjectionTopology, ProjectionEpoch, ProjectionFailureBatch, ProjectionGeneration,
+    ProjectionInputCursor, ProjectionInputFingerprint, ProjectionPartition,
+    ProjectionPartitionRuntimeState, ProjectionProtocolError, ProjectionProtocolStore,
+    TrustedProjectionInput,
+};
+
+use super::super::HandlerError;
+use super::handle::ProjectionRepairHandle;
+
+pub(super) async fn record_ingress_failure<S>(
+    store: &S,
+    compiled: &CompiledProjectionTopology,
+    change_epoch: ProjectionEpoch,
+    message: &Message,
+    ordered: &OrderedDelivery,
+    message_id: &str,
+    causation_id: &str,
+    error: HandlerError,
+) -> Result<(), HandlerError>
+where
+    S: ProjectionProtocolStore,
+{
+    let partition =
+        ProjectionPartition::new(b"distributed.projection.ingress-failure-partition.v1\0".to_vec())
+            .map_err(ProjectionProtocolError::from)?;
+    let cursor = ProjectionInputCursor::new(
+        compiled.topology().clone(),
+        partition.clone(),
+        ordered.source().clone(),
+        ordered.epoch().clone(),
+        ordered.position(),
+    )
+    .map_err(ProjectionProtocolError::from)?;
+    let fingerprint = canonical_message_fingerprint(message);
+    store
+        .register_projection_models(compiled.topology(), compiled.ownership())
+        .await?;
+    let runtime_state = store
+        .projection_partition_runtime_state(compiled.topology(), &partition)
+        .await?;
+    let generation = preflight_runtime_state(
+        runtime_state.as_ref(),
+        &cursor,
+        fingerprint,
+        message_id,
+        causation_id,
+        false,
+    )?;
+    let input = TrustedProjectionInput::mint(
+        cursor,
+        fingerprint,
+        message_id,
+        causation_id,
+        generation,
+        false,
+    )?;
+    handle_projector_error(store, input, change_epoch, "ingress_partition", error).await
+}
+
+pub(super) fn preflight_runtime_state(
+    state: Option<&ProjectionPartitionRuntimeState>,
+    cursor: &ProjectionInputCursor,
+    fingerprint: ProjectionInputFingerprint,
+    message_id: &str,
+    causation_id: &str,
+    gap_free: bool,
+) -> Result<ProjectionGeneration, HandlerError> {
+    let Some(state) = state else {
+        return Ok(ProjectionGeneration::initial());
+    };
+    if let Some(failure_id) = &state.stopped_failure_id {
+        return Err(terminal_recorded(failure_id.clone()));
+    }
+    if let Some(pending) = &state.pending_retry {
+        if &pending.input != cursor {
+            return Err(terminal_recorded(pending.failure_id.clone()));
+        }
+        if pending.input_fingerprint != fingerprint
+            || pending.message_id != message_id
+            || pending.causation_id != causation_id
+            || pending.gap_free != gap_free
+        {
+            return Err(terminal_recorded(pending.failure_id.clone()));
+        }
+    }
+    Ok(state.active_generation)
+}
+
+pub(super) async fn handle_projector_error<S>(
+    store: &S,
+    input: TrustedProjectionInput,
+    change_epoch: ProjectionEpoch,
+    code: &'static str,
+    error: HandlerError,
+) -> Result<(), HandlerError>
+where
+    S: ProjectionProtocolStore,
+{
+    if error.is_projection_retryable() {
+        return Err(error);
+    }
+    let detail = error.to_string();
+    let failure_id =
+        record_terminal_failure(store, input, change_epoch, code, detail.as_bytes()).await?;
+    Err(terminal_recorded(failure_id))
+}
+
+pub(super) async fn record_terminal_protocol_failure<S>(
+    store: &S,
+    input: TrustedProjectionInput,
+    change_epoch: ProjectionEpoch,
+    code: &'static str,
+    error: ProjectionProtocolError,
+) -> Result<(), HandlerError>
+where
+    S: ProjectionProtocolStore,
+{
+    if let ProjectionProtocolError::PartitionStopped { failure_id } = error {
+        return Err(terminal_recorded(failure_id));
+    }
+    if projection_error_is_retryable(&error) {
+        return Err(error.into());
+    }
+    let detail = error.to_string();
+    let failure_id =
+        record_terminal_failure(store, input, change_epoch, code, detail.as_bytes()).await?;
+    Err(terminal_recorded(failure_id))
+}
+
+async fn record_terminal_failure<S>(
+    store: &S,
+    input: TrustedProjectionInput,
+    change_epoch: ProjectionEpoch,
+    code: &'static str,
+    detail: &[u8],
+) -> Result<String, HandlerError>
+where
+    S: ProjectionProtocolStore,
+{
+    const MAX_FAILURE_DETAIL_BYTES: usize = 1024 * 1024;
+
+    let failure_id = deterministic_failure_id(&input);
+    let detail = if detail.len() > MAX_FAILURE_DETAIL_BYTES {
+        &detail[..MAX_FAILURE_DETAIL_BYTES]
+    } else {
+        detail
+    };
+    let batch = ProjectionFailureBatch::new(
+        input,
+        change_epoch,
+        failure_id.clone(),
+        code,
+        detail.to_vec(),
+    )?;
+    match store.record_projection_failure(batch).await {
+        Ok(_) => Ok(failure_id),
+        // Another worker can durably stop this partition between our preflight
+        // and failure write. Retaining the current exact source position and
+        // stopping is the same required outcome as observing it in preflight.
+        Err(ProjectionProtocolError::PartitionStopped { failure_id }) => {
+            Err(terminal_recorded(failure_id))
+        }
+        Err(error) => Err(error.into()),
+    }
+}
+
+pub(super) fn terminal_recorded(failure_id: String) -> HandlerError {
+    HandlerError::ProjectionTerminalRecorded {
+        repair: ProjectionRepairHandle::for_failure(failure_id),
+    }
+}
+
+fn deterministic_failure_id(input: &TrustedProjectionInput) -> String {
+    let mut digest = Sha256::new();
+    digest.update(b"distributed.causal-projector.failure-id.v1\0");
+    digest.update(input.cursor.topology().canonical_bytes());
+    digest.update(input.cursor.projection_partition().canonical_bytes());
+    digest.update(input.cursor.source().name().as_bytes());
+    digest.update(input.cursor.source().canonical_partition_bytes());
+    digest.update(input.cursor.epoch().as_str().as_bytes());
+    digest.update(input.cursor.position().to_be_bytes());
+    digest.update(input.generation.get().to_be_bytes());
+    format!("{:x}", digest.finalize())
+}
+
+pub(super) fn canonical_message_fingerprint(message: &Message) -> ProjectionInputFingerprint {
+    let canonical = serde_json::json!({
+        "version": 1,
+        "id": message.id(),
+        "name": message.name(),
+        "kind": message.kind.as_str(),
+        "content_type": message.content_type,
+        "payload": message.payload,
+        "causation_id": message.causation_id(),
+    });
+    ProjectionInputFingerprint::from_canonical_bytes(
+        &serde_json::to_vec(&canonical)
+            .expect("a canonical transport message contains only serializable primitives"),
+    )
+}
+
+pub(in crate::microsvc) fn projection_error_is_retryable(error: &ProjectionProtocolError) -> bool {
+    use crate::lock::RetryClass;
+    use crate::table::TableStoreError;
+
+    match error {
+        ProjectionProtocolError::Repository(error) => error.is_retryable(),
+        ProjectionProtocolError::Table(TableStoreError::ConcurrencyConflict { .. })
+        | ProjectionProtocolError::Table(TableStoreError::NotFound { .. })
+        | ProjectionProtocolError::RecordRevisionConflict { .. }
+        | ProjectionProtocolError::GenerationFenced { .. } => true,
+        ProjectionProtocolError::Table(TableStoreError::BackendStorage { retryable, .. }) => {
+            *retryable
+        }
+        ProjectionProtocolError::Table(TableStoreError::Lock(error)) => {
+            error.kind() == RetryClass::Retryable
+        }
+        ProjectionProtocolError::Validation(_)
+        | ProjectionProtocolError::Table(_)
+        | ProjectionProtocolError::InvalidBatch(_)
+        | ProjectionProtocolError::ScopeMismatch { .. }
+        | ProjectionProtocolError::IncomparableInput
+        | ProjectionProtocolError::InputCorruption
+        | ProjectionProtocolError::MessageIdReuse { .. }
+        | ProjectionProtocolError::PartitionStopped { .. }
+        | ProjectionProtocolError::RecordMissing { .. }
+        | ProjectionProtocolError::RecordAlreadyExists { .. }
+        | ProjectionProtocolError::RecordTombstoned { .. }
+        | ProjectionProtocolError::RecreateRequiresTombstone { .. }
+        | ProjectionProtocolError::CausalWriteRequired { .. }
+        | ProjectionProtocolError::PositionOverflow { .. } => false,
+    }
+}
diff --git a/src/microsvc/projector/handle.rs b/src/microsvc/projector/handle.rs
new file mode 100644
index 00000000..9365e24b
--- /dev/null
+++ b/src/microsvc/projector/handle.rs
@@ -0,0 +1,111 @@
+use std::fmt;
+use std::str::FromStr;
+
+const PROJECTION_REPAIR_HANDLE_VERSION: u8 = 1;
+const PROJECTION_REPAIR_HANDLE_PREFIX: &str = "distributed-repair-v1:";
+const DETERMINISTIC_FAILURE_ID_BYTES: usize = 64;
+
+/// Transferable, non-sensitive operator handle for one durable projection
+/// failure.
+///
+/// The handle deliberately contains only a format version and the globally
+/// unique deterministic failure ID. It never serializes a canonical projection
+/// partition, which may contain tenant identifiers. During repair, the owning
+/// store resolves and validates the exact durable topology/partition scope and
+/// the [`Service`](super::Service) verifies that topology is registered.
+#[derive(Clone, PartialEq, Eq, Hash)]
+pub struct ProjectionRepairHandle {
+    version: u8,
+    failure_id: String,
+}
+
+impl ProjectionRepairHandle {
+    pub(super) fn for_failure(failure_id: String) -> Self {
+        debug_assert!(valid_deterministic_failure_id(&failure_id));
+        Self {
+            version: PROJECTION_REPAIR_HANDLE_VERSION,
+            failure_id,
+        }
+    }
+
+    pub fn version(&self) -> u8 {
+        self.version
+    }
+
+    pub fn failure_id(&self) -> &str {
+        &self.failure_id
+    }
+}
+
+impl fmt::Debug for ProjectionRepairHandle {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("ProjectionRepairHandle")
+            .field("version", &self.version)
+            .field("failure_id", &self.failure_id)
+            .finish()
+    }
+}
+
+impl fmt::Display for ProjectionRepairHandle {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            formatter,
+            "{PROJECTION_REPAIR_HANDLE_PREFIX}{}",
+            self.failure_id
+        )
+    }
+}
+
+/// Failure parsing an operator-supplied [`ProjectionRepairHandle`].
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct ProjectionRepairHandleParseError;
+
+impl fmt::Display for ProjectionRepairHandleParseError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("invalid projection repair handle")
+    }
+}
+
+impl std::error::Error for ProjectionRepairHandleParseError {}
+
+impl FromStr for ProjectionRepairHandle {
+    type Err = ProjectionRepairHandleParseError;
+
+    fn from_str(token: &str) -> Result<Self, Self::Err> {
+        let failure_id = token
+            .strip_prefix(PROJECTION_REPAIR_HANDLE_PREFIX)
+            .filter(|failure_id| valid_deterministic_failure_id(failure_id))
+            .ok_or(ProjectionRepairHandleParseError)?;
+        Ok(Self {
+            version: PROJECTION_REPAIR_HANDLE_VERSION,
+            failure_id: failure_id.to_string(),
+        })
+    }
+}
+
+impl serde::Serialize for ProjectionRepairHandle {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        serializer.serialize_str(&self.to_string())
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for ProjectionRepairHandle {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let token = String::deserialize(deserializer)?;
+        token.parse().map_err(serde::de::Error::custom)
+    }
+}
+
+fn valid_deterministic_failure_id(failure_id: &str) -> bool {
+    failure_id.len() == DETERMINISTIC_FAILURE_ID_BYTES
+        && failure_id
+            .bytes()
+            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+}
diff --git a/src/microsvc/projector/mod.rs b/src/microsvc/projector/mod.rs
new file mode 100644
index 00000000..acceed8b
--- /dev/null
+++ b/src/microsvc/projector/mod.rs
@@ -0,0 +1,26 @@
+//! Typed, capability-restricted causal projector routes.
+//!
+//! A projector handler receives typed input and a [`CausalProjectorContext`].
+//! It can load/stage projected rows, but it never receives the dependency
+//! bundle, repository, trusted transport cursor, or commit/failure methods.
+//! The framework authenticates ordering through the receive adapter, bootstraps
+//! the complete compiled topology, and owns the atomic protocol commit.
+
+mod context;
+mod errors;
+mod handle;
+mod registration;
+mod runtime;
+
+pub use context::{CausalProjectorContext, LoadedProjection};
+pub use handle::{ProjectionRepairHandle, ProjectionRepairHandleParseError};
+pub use registration::CausalProjectorRouteBuilder;
+
+pub(super) use errors::projection_error_is_retryable;
+pub(super) use runtime::{
+    ErasedProjectorHandler, ProjectorRegistration, ProjectorRepairFuture,
+    ProjectorRepairLookupFuture,
+};
+
+#[cfg(test)]
+mod tests;
diff --git a/src/microsvc/projector/registration.rs b/src/microsvc/projector/registration.rs
new file mode 100644
index 00000000..5d502543
--- /dev/null
+++ b/src/microsvc/projector/registration.rs
@@ -0,0 +1,113 @@
+use std::future::Future;
+use std::marker::PhantomData;
+use std::pin::Pin;
+use std::sync::Arc;
+
+use crate::graphql::SurfaceProjector;
+use crate::projection_protocol::{CompiledProjectionTopology, ProjectionEpoch};
+use crate::read_model::RelationalReadModel;
+use crate::table::TableSchema;
+
+use super::super::dependencies::CausalProjectionRouteDependencies;
+use super::super::service::{HandlerSpec, Routes};
+use super::super::HandlerError;
+use super::context::CausalProjectorContext;
+use super::runtime::RegisteredProjector;
+
+type ProjectorHandlerFuture =
+    Pin<Box<dyn Future<Output = Result<(), HandlerError>> + Send + 'static>>;
+pub(super) type ProjectorHandlerFn<I> =
+    dyn Fn(CausalProjectorContext, I) -> ProjectorHandlerFuture + Send + Sync;
+fn boxed_projector_handler<I, F, Fut>(handler: F) -> Arc<ProjectorHandlerFn<I>>
+where
+    I: Send + 'static,
+    F: Fn(CausalProjectorContext, I) -> Fut + Send + Sync + 'static,
+    Fut: Future<Output = Result<(), HandlerError>> + Send + 'static,
+{
+    Arc::new(move |context, input| Box::pin(handler(context, input)))
+}
+
+/// Builder for one typed causal projector route.
+pub struct CausalProjectorRouteBuilder<D, I> {
+    routes: Routes<D>,
+    declaration: SurfaceProjector,
+    schemas: Vec<&'static TableSchema>,
+    _input: PhantomData<fn(I)>,
+}
+
+impl<D, I> CausalProjectorRouteBuilder<D, I>
+where
+    D: CausalProjectionRouteDependencies + Send + Sync + 'static,
+    I: serde::de::DeserializeOwned + Send + 'static,
+{
+    pub(in crate::microsvc) fn new(routes: Routes<D>, declaration: SurfaceProjector) -> Self {
+        Self {
+            routes,
+            declaration,
+            schemas: Vec::new(),
+            _input: PhantomData,
+        }
+    }
+
+    /// Register one complete typed output model. Call once for every model in
+    /// the reused [`SurfaceProjector`] declaration.
+    pub fn model<M>(mut self) -> Self
+    where
+        M: RelationalReadModel + 'static,
+    {
+        self.schemas.push(M::schema());
+        self
+    }
+
+    /// Register the capability-restricted handler.
+    ///
+    /// Invalid/incomplete topology declarations panic at service construction,
+    /// before transport traffic can start, matching ordinary duplicate-route
+    /// registration behavior.
+    pub fn handle<F, Fut>(self, handler: F) -> Routes<D>
+    where
+        F: Fn(CausalProjectorContext, I) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = Result<(), HandlerError>> + Send + 'static,
+    {
+        if self.declaration.facts.is_empty() {
+            panic!(
+                "causal projector `{}` requires at least one accepted fact",
+                self.declaration.name
+            );
+        }
+        let change_epoch = self.declaration.change_epoch.as_ref().unwrap_or_else(|| {
+            panic!(
+                "causal projector `{}` requires a change-log epoch",
+                self.declaration.name
+            )
+        });
+        let change_epoch = ProjectionEpoch::new(change_epoch.clone()).unwrap_or_else(|error| {
+            panic!(
+                "causal projector `{}` has an invalid change-log epoch: {error}",
+                self.declaration.name
+            )
+        });
+        let compiled = CompiledProjectionTopology::compile(
+            &self.declaration.name,
+            &self.declaration.facts,
+            &self.declaration.models,
+            &self.declaration.partition,
+            self.schemas,
+        )
+        .unwrap_or_else(|error| {
+            panic!(
+                "causal projector `{}` has an invalid compiled topology: {error}",
+                self.declaration.name
+            )
+        });
+        let spec = HandlerSpec::projector(self.declaration.facts.clone());
+        self.routes.register_projector(
+            spec,
+            Box::new(RegisteredProjector::<I> {
+                compiled,
+                change_epoch,
+                handle: boxed_projector_handler(handler),
+            }),
+        )
+    }
+}
diff --git a/src/microsvc/projector/runtime.rs b/src/microsvc/projector/runtime.rs
new file mode 100644
index 00000000..779f2fde
--- /dev/null
+++ b/src/microsvc/projector/runtime.rs
@@ -0,0 +1,343 @@
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Arc;
+
+use serde_json::Value;
+
+use crate::bus::{Message, MessageKind, OrderedDelivery};
+use crate::projection_protocol::{
+    CompiledProjectionTopology, ProjectionEpoch, ProjectionGeneration, ProjectionInputCursor,
+    ProjectionInputDisposition, ProjectionModelOwnership, ProjectionProtocolError,
+    ProjectionProtocolStore, ProjectionWorkspace, ProjectorTopologyId, TrustedProjectionInput,
+};
+
+use super::super::dependencies::CausalProjectionRouteDependencies;
+use super::super::HandlerError;
+use super::context::{unavailable_workspace, CausalProjectorContext};
+use super::errors::{
+    canonical_message_fingerprint, handle_projector_error, preflight_runtime_state,
+    projection_error_is_retryable, record_ingress_failure, record_terminal_protocol_failure,
+    terminal_recorded,
+};
+use super::handle::ProjectionRepairHandle;
+use super::registration::ProjectorHandlerFn;
+
+pub(in crate::microsvc) type ProjectorDispatchFuture<'a> =
+    Pin<Box<dyn Future<Output = Result<(), HandlerError>> + Send + 'a>>;
+pub(in crate::microsvc) type ProjectorRepairFuture<'a> =
+    Pin<Box<dyn Future<Output = Result<Option<ProjectionGeneration>, HandlerError>> + Send + 'a>>;
+pub(in crate::microsvc) type ProjectorRepairLookupFuture<'a> =
+    Pin<Box<dyn Future<Output = Result<bool, HandlerError>> + Send + 'a>>;
+
+pub(in crate::microsvc) trait ErasedProjectorHandler<D>: Send + Sync {
+    fn dispatch<'a>(
+        &'a self,
+        dependencies: &'a D,
+        message: &'a Message,
+        ordered: Option<&'a OrderedDelivery>,
+    ) -> ProjectorDispatchFuture<'a>;
+
+    fn registration(&self) -> ProjectorRegistration;
+
+    fn bootstrap<'a>(&'a self, dependencies: &'a D) -> ProjectorDispatchFuture<'a>;
+
+    fn repair<'a>(
+        &'a self,
+        dependencies: &'a D,
+        handle: &'a ProjectionRepairHandle,
+    ) -> ProjectorRepairFuture<'a>;
+
+    fn locates_failure<'a>(
+        &'a self,
+        dependencies: &'a D,
+        handle: &'a ProjectionRepairHandle,
+    ) -> ProjectorRepairLookupFuture<'a>;
+}
+
+#[derive(Clone)]
+pub(in crate::microsvc) struct ProjectorRegistration {
+    pub(in crate::microsvc) topology: ProjectorTopologyId,
+    pub(in crate::microsvc) ownership: Vec<ProjectionModelOwnership>,
+}
+
+pub(super) struct RegisteredProjector<I> {
+    pub(super) compiled: CompiledProjectionTopology,
+    pub(super) change_epoch: ProjectionEpoch,
+    pub(super) handle: Arc<ProjectorHandlerFn<I>>,
+}
+
+impl<D, I> ErasedProjectorHandler<D> for RegisteredProjector<I>
+where
+    D: CausalProjectionRouteDependencies + Send + Sync + 'static,
+    I: serde::de::DeserializeOwned + Send + 'static,
+{
+    fn registration(&self) -> ProjectorRegistration {
+        ProjectorRegistration {
+            topology: self.compiled.topology().clone(),
+            ownership: self.compiled.ownership().to_vec(),
+        }
+    }
+
+    fn bootstrap<'a>(&'a self, dependencies: &'a D) -> ProjectorDispatchFuture<'a> {
+        Box::pin(async move {
+            dependencies
+                .__causal_projection_store()
+                .register_projection_models(self.compiled.topology(), self.compiled.ownership())
+                .await?;
+            Ok(())
+        })
+    }
+
+    fn repair<'a>(
+        &'a self,
+        dependencies: &'a D,
+        handle: &'a ProjectionRepairHandle,
+    ) -> ProjectorRepairFuture<'a> {
+        Box::pin(async move {
+            let store = dependencies.__causal_projection_store();
+            let Some(location) = store
+                .projection_failure_location(handle.failure_id())
+                .await?
+            else {
+                return Ok(None);
+            };
+            if &location.topology != self.compiled.topology() {
+                return Ok(None);
+            }
+            store
+                .register_projection_models(self.compiled.topology(), self.compiled.ownership())
+                .await?;
+            let generation = store
+                .repair_projection(&location.topology, &location.partition, handle.failure_id())
+                .await?;
+            Ok(Some(generation))
+        })
+    }
+
+    fn locates_failure<'a>(
+        &'a self,
+        dependencies: &'a D,
+        handle: &'a ProjectionRepairHandle,
+    ) -> ProjectorRepairLookupFuture<'a> {
+        Box::pin(async move {
+            let location = dependencies
+                .__causal_projection_store()
+                .projection_failure_location(handle.failure_id())
+                .await?;
+            Ok(location
+                .as_ref()
+                .is_some_and(|location| &location.topology == self.compiled.topology()))
+        })
+    }
+
+    fn dispatch<'a>(
+        &'a self,
+        dependencies: &'a D,
+        message: &'a Message,
+        ordered: Option<&'a OrderedDelivery>,
+    ) -> ProjectorDispatchFuture<'a> {
+        Box::pin(async move {
+            let ordered = ordered.ok_or_else(|| {
+                HandlerError::UnqualifiedProjectionDelivery(format!(
+                    "causal projector `{}` requires adapter-authenticated ordered delivery",
+                    self.compiled.topology().name()
+                ))
+            })?;
+            if message.kind != MessageKind::Event {
+                return Err(HandlerError::UnqualifiedProjectionDelivery(
+                    "causal projector routes accept only event deliveries".into(),
+                ));
+            }
+            let message_id = message.id().ok_or_else(|| {
+                HandlerError::UnqualifiedProjectionDelivery(
+                    "causal projector delivery is missing a stable message ID".into(),
+                )
+            })?;
+            let causation_id = message.causation_id().ok_or_else(|| {
+                HandlerError::UnqualifiedProjectionDelivery(
+                    "causal projector delivery is missing a causation ID".into(),
+                )
+            })?;
+
+            let mut canonical_input = None;
+            let partition_value = if self.compiled.partition().requires_input() {
+                match message.payload_json::<Value>() {
+                    Ok(input) => match self.compiled.partition().resolve(&input) {
+                        Ok(partition) => {
+                            canonical_input = Some(input);
+                            partition
+                        }
+                        Err(error) => {
+                            return record_ingress_failure(
+                                dependencies.__causal_projection_store(),
+                                &self.compiled,
+                                self.change_epoch.clone(),
+                                message,
+                                ordered,
+                                message_id,
+                                causation_id,
+                                error.into(),
+                            )
+                            .await
+                        }
+                    },
+                    Err(error) => {
+                        return record_ingress_failure(
+                            dependencies.__causal_projection_store(),
+                            &self.compiled,
+                            self.change_epoch.clone(),
+                            message,
+                            ordered,
+                            message_id,
+                            causation_id,
+                            HandlerError::from(error),
+                        )
+                        .await
+                    }
+                }
+            } else {
+                self.compiled.partition().resolve(&Value::Null)?
+            };
+            let projection_partition = self
+                .compiled
+                .codec()
+                .encode_partition(partition_value.as_ref())
+                .map_err(|error| {
+                    ProjectionProtocolError::InvalidBatch(format!(
+                        "causal projector partition could not be encoded: {error}"
+                    ))
+                })?;
+            let cursor = ProjectionInputCursor::new(
+                self.compiled.topology().clone(),
+                projection_partition.clone(),
+                ordered.source().clone(),
+                ordered.epoch().clone(),
+                ordered.position(),
+            )
+            .map_err(ProjectionProtocolError::from)?;
+            let fingerprint = canonical_message_fingerprint(message);
+            // Adapter gap-free evidence is scoped to its source partition.
+            // A dynamic input-path partition splits that sequence, so it can
+            // preserve ordering but cannot prove gap-free progress for any one
+            // derived projection partition.
+            let gap_free =
+                ordered.is_gap_free() && self.compiled.partition().preserves_source_sequence();
+            let store = dependencies.__causal_projection_store();
+
+            // Idempotent global ownership bootstrap deliberately precedes every
+            // partition read/handler invocation. Adapters make repeated exact
+            // registration cheap and reject any conflicting owner.
+            store
+                .register_projection_models(self.compiled.topology(), self.compiled.ownership())
+                .await?;
+            let runtime_state = store
+                .projection_partition_runtime_state(self.compiled.topology(), &projection_partition)
+                .await?;
+            let generation = preflight_runtime_state(
+                runtime_state.as_ref(),
+                &cursor,
+                fingerprint,
+                message_id,
+                causation_id,
+                gap_free,
+            )?;
+            let trusted = TrustedProjectionInput::mint(
+                cursor,
+                fingerprint,
+                message_id,
+                causation_id,
+                generation,
+                gap_free,
+            )?;
+            match store.projection_input_disposition(&trusted).await? {
+                ProjectionInputDisposition::Pending => {}
+                ProjectionInputDisposition::Duplicate(_) | ProjectionInputDisposition::Stale(_) => {
+                    return Ok(())
+                }
+            }
+            let failure_input = trusted.clone();
+            let canonical_input = match canonical_input {
+                Some(input) => input,
+                None => match message.payload_json::<Value>() {
+                    Ok(input) => input,
+                    Err(error) => {
+                        return handle_projector_error(
+                            store,
+                            failure_input,
+                            self.change_epoch.clone(),
+                            "json_decode",
+                            HandlerError::from(error),
+                        )
+                        .await
+                    }
+                },
+            };
+            let input = match serde_json::from_value::<I>(canonical_input) {
+                Ok(input) => input,
+                Err(error) => {
+                    return handle_projector_error(
+                        store,
+                        failure_input,
+                        self.change_epoch.clone(),
+                        "typed_decode",
+                        HandlerError::from(error),
+                    )
+                    .await
+                }
+            };
+            let workspace = ProjectionWorkspace::new(
+                self.compiled.codec(),
+                partition_value,
+                trusted,
+                self.change_epoch.clone(),
+            )?;
+            let (context, workspace) =
+                CausalProjectorContext::new(message, D::Store::clone(store), workspace);
+            if let Err(error) = (self.handle)(context, input).await {
+                return handle_projector_error(
+                    store,
+                    failure_input,
+                    self.change_epoch.clone(),
+                    "handler_error",
+                    error,
+                )
+                .await;
+            }
+            let workspace = workspace
+                .lock()
+                .map_err(|_| unavailable_workspace("seal projection batch"))?
+                .take()
+                .ok_or_else(|| unavailable_workspace("seal projection batch"))?;
+            let batch = match workspace.into_batch() {
+                Ok(batch) => batch,
+                Err(error) => {
+                    return record_terminal_protocol_failure(
+                        store,
+                        failure_input,
+                        self.change_epoch.clone(),
+                        "workspace_seal",
+                        error,
+                    )
+                    .await
+                }
+            };
+            match store.commit_projection(batch).await {
+                Ok(_) => Ok(()),
+                Err(ProjectionProtocolError::PartitionStopped { failure_id }) => {
+                    Err(terminal_recorded(failure_id))
+                }
+                Err(error) if projection_error_is_retryable(&error) => Err(error.into()),
+                Err(error) => {
+                    record_terminal_protocol_failure(
+                        store,
+                        failure_input,
+                        self.change_epoch.clone(),
+                        "commit_projection",
+                        error,
+                    )
+                    .await
+                }
+            }
+        })
+    }
+}
diff --git a/src/microsvc/projector/tests.rs b/src/microsvc/projector/tests.rs
new file mode 100644
index 00000000..87c189a9
--- /dev/null
+++ b/src/microsvc/projector/tests.rs
@@ -0,0 +1,405 @@
+use std::error::Error as _;
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex};
+
+use crate::bus::{Bus, FailurePolicy, InMemoryBus, RunOptions};
+use crate::bus::{Message, MessageKind};
+use crate::graphql::SurfaceProjector;
+use crate::microsvc::{CausalProjectorContext, HandlerError, ProjectionRepairHandle, Routes};
+use crate::projection_protocol::{
+    CompiledProjectionTopology, ProjectionCheckpointProbe, ProjectionGeneration,
+    ProjectionInputCursor, ProjectionProtocolStore, ProjectionQuerySnapshotRequest,
+};
+use crate::table::{RowKey, RowValue};
+use crate::{InMemoryRepository, RelationalReadModel};
+
+use crate::microsvc::Service;
+
+const FACT_NAME: &str = "task15.todo_changed";
+
+#[derive(Clone, Debug, serde::Deserialize)]
+struct TodoChanged {
+    id: String,
+    title: String,
+}
+
+#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize, crate::ReadModel)]
+#[readmodel(table = "task15_primary_views", primary_key = ["id"])]
+struct PrimaryView {
+    id: String,
+    title: String,
+}
+
+#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize, crate::ReadModel)]
+#[readmodel(table = "task15_secondary_views", primary_key = ["id"])]
+struct SecondaryView {
+    id: String,
+    title: String,
+}
+
+#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize, crate::ReadModel)]
+#[readmodel(table = "task15_malformed_views", primary_key = ["id"])]
+struct MalformedView {
+    id: String,
+}
+
+fn primary_projector() -> SurfaceProjector {
+    SurfaceProjector::new("task15_a_primary")
+        .facts([FACT_NAME])
+        .models(["PrimaryView"])
+        .change_epoch("task15-primary-v1")
+}
+
+fn secondary_projector() -> SurfaceProjector {
+    SurfaceProjector::new("task15_b_secondary")
+        .facts([FACT_NAME])
+        .models(["SecondaryView"])
+        .change_epoch("task15-secondary-v1")
+}
+
+fn fact_message(id: &str, title: &str) -> Message {
+    Message::new(
+        FACT_NAME,
+        MessageKind::Event,
+        serde_json::to_vec(&serde_json::json!({ "id": id, "title": title })).unwrap(),
+    )
+    .with_id(format!("fact-{id}"))
+    .with_metadata(crate::trace_context::CAUSATION_ID, format!("command-{id}"))
+}
+
+fn row_key(id: &str) -> RowKey {
+    RowKey::new([("id", RowValue::String(id.to_string()))])
+}
+
+#[tokio::test]
+async fn public_builder_fans_one_fact_out_and_replays_partial_success_exactly() {
+    let repository = InMemoryRepository::new();
+    let bus = InMemoryBus::new();
+    let calls = Arc::new(Mutex::new(Vec::new()));
+    let fail_secondary_once = Arc::new(AtomicBool::new(true));
+
+    let primary = primary_projector();
+    let secondary = secondary_projector();
+    let primary_calls = Arc::clone(&calls);
+    let secondary_calls = Arc::clone(&calls);
+    let secondary_failure = Arc::clone(&fail_secondary_once);
+    let routes = Routes::new()
+        .with_read_model_store(repository.clone())
+        .causal_projector::<TodoChanged>(primary.clone())
+        .model::<PrimaryView>()
+        .handle(move |context: CausalProjectorContext, fact: TodoChanged| {
+            let calls = Arc::clone(&primary_calls);
+            async move {
+                {
+                    let mut calls = calls.lock().unwrap();
+                    if calls.contains(&"primary") {
+                        return Err(HandlerError::Rejected(
+                            "an applied projector must not be reinvoked on sibling retry".into(),
+                        ));
+                    }
+                    calls.push("primary");
+                }
+                context
+                    .project(&PrimaryView {
+                        id: fact.id,
+                        title: fact.title,
+                    })
+                    .await?;
+                Ok(())
+            }
+        })
+        .causal_projector::<TodoChanged>(secondary)
+        .model::<SecondaryView>()
+        .handle(move |context: CausalProjectorContext, fact: TodoChanged| {
+            let calls = Arc::clone(&secondary_calls);
+            let fail = Arc::clone(&secondary_failure);
+            async move {
+                calls.lock().unwrap().push("secondary");
+                if fail.swap(false, Ordering::SeqCst) {
+                    return Err(HandlerError::Other(
+                        "injected transient projector failure".into(),
+                    ));
+                }
+                context
+                    .project(&SecondaryView {
+                        id: fact.id,
+                        title: fact.title,
+                    })
+                    .await?;
+                Ok(())
+            }
+        });
+    let service = Service::new().routes(routes).with_bus(bus.clone());
+    bus.publish_message(fact_message("todo-1", "causal cache"))
+        .await
+        .unwrap();
+
+    service.run(RunOptions::idempotent()).await.unwrap();
+    assert_eq!(
+        *calls.lock().unwrap(),
+        vec!["primary", "secondary", "secondary"],
+        "an applied sibling is skipped while only the failed projector retries"
+    );
+
+    let compiled = CompiledProjectionTopology::compile(
+        &primary.name,
+        &primary.facts,
+        &primary.models,
+        &primary.partition,
+        [PrimaryView::schema()],
+    )
+    .unwrap();
+    let codec = compiled.codec();
+    let partition = codec.encode_partition(None).unwrap();
+    let ordered = bus.ordered_topic_evidence(FACT_NAME, 0);
+    let cursor = ProjectionInputCursor::new(
+        compiled.topology().clone(),
+        partition.clone(),
+        ordered.source().clone(),
+        ordered.epoch().clone(),
+        ordered.position(),
+    )
+    .unwrap();
+    let snapshot = repository
+        .projection_query_snapshot(
+            &ProjectionQuerySnapshotRequest::new(
+                &codec,
+                None,
+                "PrimaryView",
+                row_key("todo-1"),
+                vec![ProjectionCheckpointProbe::new(
+                    compiled.topology().clone(),
+                    partition,
+                    ordered.source().clone(),
+                    ordered.epoch().clone(),
+                    ProjectionGeneration::initial(),
+                )],
+            )
+            .unwrap(),
+        )
+        .await
+        .unwrap();
+    let row = snapshot.row.expect("projected physical row");
+    assert_eq!(row.get_serde::<String>("title").unwrap(), "causal cache");
+    let record = snapshot.record.expect("projection record revision");
+    assert_eq!(record.revision.incarnation(), 1);
+    assert_eq!(record.revision.revision(), 1);
+    let checkpoint = snapshot.checkpoints[0]
+        .checkpoint
+        .as_ref()
+        .expect("source checkpoint");
+    assert_eq!(checkpoint.input(), &cursor);
+    assert!(checkpoint.is_gap_free());
+}
+
+#[tokio::test]
+async fn service_fans_same_fact_out_across_projector_only_route_bundles() {
+    static INFERRED_PRIMARY_CALLS: AtomicUsize = AtomicUsize::new(0);
+
+    let repository = InMemoryRepository::new();
+    let bus = InMemoryBus::new();
+    let secondary_calls = Arc::new(AtomicUsize::new(0));
+    INFERRED_PRIMARY_CALLS.store(0, Ordering::SeqCst);
+
+    let primary_routes = Routes::new()
+        .with_read_model_store(repository.clone())
+        .causal_projector::<TodoChanged>(primary_projector())
+        .model::<PrimaryView>()
+        .handle(|context, fact: TodoChanged| async move {
+            INFERRED_PRIMARY_CALLS.fetch_add(1, Ordering::SeqCst);
+            context
+                .project(&PrimaryView {
+                    id: fact.id,
+                    title: fact.title,
+                })
+                .await?;
+            Ok(())
+        });
+    let secondary_seen = Arc::clone(&secondary_calls);
+    let secondary_routes = Routes::new()
+        .with_read_model_store(repository)
+        .causal_projector::<TodoChanged>(secondary_projector())
+        .model::<SecondaryView>()
+        .handle(move |context: CausalProjectorContext, fact: TodoChanged| {
+            let seen = Arc::clone(&secondary_seen);
+            async move {
+                seen.fetch_add(1, Ordering::SeqCst);
+                context
+                    .project(&SecondaryView {
+                        id: fact.id,
+                        title: fact.title,
+                    })
+                    .await?;
+                Ok(())
+            }
+        });
+    let service = Service::new()
+        .routes(primary_routes)
+        .routes(secondary_routes)
+        .with_bus(bus.clone());
+    assert_eq!(
+        service.subscription_plan().events,
+        vec![FACT_NAME.to_string()]
+    );
+    bus.publish_message(fact_message("todo-2", "cross bundle"))
+        .await
+        .unwrap();
+    service.run(RunOptions::idempotent()).await.unwrap();
+
+    assert_eq!(INFERRED_PRIMARY_CALLS.load(Ordering::SeqCst), 1);
+    assert_eq!(secondary_calls.load(Ordering::SeqCst), 1);
+}
+
+fn malformed_service(repository: InMemoryRepository, invoked: Arc<AtomicUsize>) -> Service {
+    let projector = SurfaceProjector::new("task15_malformed")
+        .facts(["task15.malformed"])
+        .models(["MalformedView"])
+        .change_epoch("task15-malformed-v1")
+        .partition_by(["tenant"]);
+    Service::new().routes(
+        Routes::new()
+            .with_read_model_store(repository)
+            .causal_projector::<TodoChanged>(projector)
+            .model::<MalformedView>()
+            .handle(
+                move |_context: CausalProjectorContext, _fact: TodoChanged| {
+                    let invoked = Arc::clone(&invoked);
+                    async move {
+                        invoked.fetch_add(1, Ordering::SeqCst);
+                        Ok(())
+                    }
+                },
+            ),
+    )
+}
+
+fn repair_handle(error: &crate::bus::TransportError) -> ProjectionRepairHandle {
+    error
+        .source()
+        .and_then(|source| source.downcast_ref::<HandlerError>())
+        .and_then(HandlerError::projection_repair_handle)
+        .cloned()
+        .expect("terminal transport error carries an operator repair handle")
+}
+
+#[tokio::test]
+async fn malformed_ingress_emits_safe_handle_and_repair_restart_stays_terminal() {
+    let repository = InMemoryRepository::new();
+    let bus = InMemoryBus::new();
+    let invoked = Arc::new(AtomicUsize::new(0));
+    let malformed = Message::new(
+        "task15.malformed",
+        MessageKind::Event,
+        b"{tenant-secret".to_vec(),
+    )
+    .with_id("malformed-1")
+    .with_metadata(crate::trace_context::CAUSATION_ID, "command-malformed");
+    bus.publish_message(malformed).await.unwrap();
+
+    let first = malformed_service(repository.clone(), Arc::clone(&invoked))
+        .with_bus(bus.clone())
+        .run(RunOptions::idempotent())
+        .await
+        .expect_err("malformed ingress must retain its exact position and stop");
+    let first_handle = repair_handle(&first);
+    let token = first_handle.to_string();
+    assert!(!token.contains("tenant-secret"));
+    assert_eq!(
+        token.parse::<ProjectionRepairHandle>().unwrap(),
+        first_handle
+    );
+    assert_eq!(
+        serde_json::from_str::<ProjectionRepairHandle>(
+            &serde_json::to_string(&first_handle).unwrap()
+        )
+        .unwrap(),
+        first_handle
+    );
+
+    let repaired = malformed_service(repository, Arc::clone(&invoked));
+    assert_eq!(
+        repaired
+            .repair_projection(&first_handle)
+            .await
+            .unwrap()
+            .get(),
+        2
+    );
+    let second = repaired
+        .with_bus(bus)
+        .run(RunOptions::idempotent())
+        .await
+        .expect_err("unchanged malformed bytes must stop the repaired generation again");
+    let second_handle = repair_handle(&second);
+    assert_ne!(second_handle, first_handle);
+    assert_eq!(invoked.load(Ordering::SeqCst), 0);
+}
+
+#[test]
+fn repair_handle_parser_rejects_noncanonical_or_non_hash_tokens() {
+    for token in [
+        "",
+        "distributed-repair-v2:abcd",
+        "distributed-repair-v1:abcd",
+        "distributed-repair-v1:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+    ] {
+        assert!(token.parse::<ProjectionRepairHandle>().is_err(), "{token}");
+    }
+}
+
+#[tokio::test]
+async fn unrecorded_permanent_projector_failure_retains_and_stops_under_drop_policies() {
+    for policy in [FailurePolicy::DeadLetter, FailurePolicy::LogAndAck] {
+        let repository = InMemoryRepository::new();
+        let bus = InMemoryBus::new();
+        let invoked = Arc::new(AtomicUsize::new(0));
+        let handler_invoked = Arc::clone(&invoked);
+        let service = Service::new()
+            .routes(
+                Routes::new()
+                    .with_read_model_store(repository)
+                    .causal_projector::<TodoChanged>(primary_projector())
+                    .model::<PrimaryView>()
+                    .handle(move |_context, _fact| {
+                        let invoked = Arc::clone(&handler_invoked);
+                        async move {
+                            invoked.fetch_add(1, Ordering::SeqCst);
+                            Ok(())
+                        }
+                    }),
+            )
+            .with_bus(bus.clone());
+        bus.publish_message(Message::new(
+            FACT_NAME,
+            MessageKind::Event,
+            br#"{"id":"secret-tenant","title":"must not cross"}"#.to_vec(),
+        ))
+        .await
+        .unwrap();
+
+        let error = service
+            .run(RunOptions::idempotent().with_failure_policy(policy))
+            .await
+            .expect_err("unrecorded permanent projector failure must stop the runner");
+        assert!(error.is_permanent());
+        assert!(error.should_retain_and_stop());
+        let halted = error
+            .source()
+            .and_then(|source| source.downcast_ref::<HandlerError>());
+        assert!(
+            matches!(halted, Some(HandlerError::ProjectionDeliveryHalted { .. })),
+            "projector-only dispatch must erase the unrecorded internal failure"
+        );
+        assert!(
+            matches!(
+                halted
+                    .and_then(|halted| halted.source())
+                    .and_then(|source| source.downcast_ref::<HandlerError>()),
+                Some(HandlerError::UnqualifiedProjectionDelivery(_))
+            ),
+            "operator diagnostics retain the original failure only as an error source"
+        );
+        assert!(!error.to_string().contains("secret-tenant"));
+        assert_eq!(invoked.load(Ordering::SeqCst), 0);
+    }
+}
diff --git a/src/microsvc/runtime.rs b/src/microsvc/runtime.rs
index 7f6585db..9b2df1d9 100644
--- a/src/microsvc/runtime.rs
+++ b/src/microsvc/runtime.rs
@@ -18,7 +18,8 @@ use crate::bus::{Bus, BusConsumer, RunOptions, TransportError};
 
 /// Default lease for an immediate after-commit outbox publish. Short by design:
 /// it only needs to cover commit → publish, so a crash before the publish
-/// completes hands the row back to the polling worker quickly.
+/// completes hands the row back to a separately operated polling worker
+/// quickly.
 pub const DEFAULT_PUBLISH_LEASE: Duration = Duration::from_secs(5);
 
 /// Default publish-failure ceiling before an outbox row is permanently failed.
@@ -30,11 +31,17 @@ impl Service {
     /// Two effects, both composing with the rest of the builder:
     /// - installs an outbox publisher on the repository, so
     ///   `repo.outbox(msg).commit(agg)` claims the row in the commit transaction
-    ///   and publishes it immediately after commit through this bus (the polling
-    ///   worker stays the crash/retry backstop);
+    ///   and publishes it immediately after commit through this bus (a polling
+    ///   worker may be operated as the crash/retry backstop);
     /// - captures how to consume, so [`run`](Self::run) listens for the
     ///   registered command names (competing) and subscribes to the event names
     ///   (fan-out).
+    ///
+    /// `with_bus` and [`run`](Self::run) do not start an [`OutboxDispatcher`]
+    /// polling loop. Deploy one separately (in this process or another) when
+    /// durable recovery after a commit-to-publish process crash is required.
+    ///
+    /// [`OutboxDispatcher`]: crate::outbox_worker::OutboxDispatcher
     pub fn with_bus<B>(mut self, bus: B) -> Self
     where
         B: Bus + BusConsumer + 'static,
@@ -74,6 +81,9 @@ impl Service {
                 "Service::run requires a bus; call `with_bus` first",
             ));
         };
+        self.bootstrap_projectors()
+            .await
+            .map_err(TransportError::from)?;
         runner(Arc::new(self), options).await
     }
 }
diff --git a/src/microsvc/service.rs b/src/microsvc/service.rs
deleted file mode 100644
index df568dab..00000000
--- a/src/microsvc/service.rs
+++ /dev/null
@@ -1,1659 +0,0 @@
-//! Routes and service dispatch for microsvc.
-//!
-//! `Routes<D>` holds one dependency value and its command/event handlers.
-//! `Service` is the deployment-level router that collects one or more route
-//! bundles. Each handler receives a `Context<D>` and returns
-//! `Result<Value, HandlerError>`.
-//!
-//! ## Example
-//!
-//! The handler closure returns a future, and `dispatch` is awaited:
-//!
-//! ```ignore
-//! use distributed::microsvc;
-//! use serde_json::json;
-//!
-//! let routes = microsvc::Routes::new()
-//!     .with_dependencies(())
-//!     .command("order.create")
-//!     .handle(|ctx| {
-//!         let input = ctx.input::<CreateOrderInput>();
-//!         async move { Ok(json!({ "id": input?.id })) }
-//!     });
-//! let service = microsvc::Service::new().routes(routes);
-//!
-//! let result = service
-//!     .dispatch("order.create", json!({"id": "1"}), Session::new())
-//!     .await?;
-//! ```
-
-use std::collections::HashMap;
-use std::future::Future;
-use std::pin::Pin;
-use std::sync::Arc;
-use std::time::Duration;
-#[cfg(feature = "metrics")]
-use std::time::Instant;
-
-use serde_json::Value;
-
-use super::context::Context;
-use super::dependencies::{
-    ConfigurableOutboxPublisher, HasOutboxStore, HasReadModelStore, HasRepo,
-    RepoReadModelDependencies,
-};
-use super::error::HandlerError;
-use super::session::Session;
-use crate::bus::{
-    Bus, Message, MessageKind, MessagePublisher, RunOptions, SubscriptionPlan, TransportError,
-};
-use crate::outbox::OutboxPublisherConfig;
-use crate::outbox_worker::BusOutboxPublishHook;
-
-/// The bus run behavior captured by [`Service::with_bus`](crate::microsvc::Service::with_bus).
-pub(crate) type ServiceRunner = Box<
-    dyn Fn(
-            Arc<Service>,
-            RunOptions,
-        ) -> Pin<Box<dyn Future<Output = Result<(), TransportError>> + Send>>
-        + Send
-        + Sync,
->;
-
-type GuardFn<D> = dyn Fn(&Context<D>) -> bool + Send + Sync;
-type HandlerFuture<'a> = Pin<Box<dyn Future<Output = Result<Value, HandlerError>> + Send + 'a>>;
-type HandlerFn<D> = dyn for<'a> Fn(&'a Context<'a, D>) -> HandlerFuture<'a> + Send + Sync;
-
-/// Lets an `async fn handle(ctx: &Context<D>) -> Result<Value, HandlerError>`
-/// register directly as a handler. The higher-ranked bound ties the returned
-/// future's lifetime to the borrowed [`Context`], which a plain generic future
-/// parameter cannot express.
-pub trait Handler<'a, D: 'a>: Send + Sync {
-    /// The future returned by the handler for a context borrowed for `'a`.
-    type Future: Future<Output = Result<Value, HandlerError>> + Send + 'a;
-    fn call(&self, ctx: &'a Context<'a, D>) -> Self::Future;
-}
-
-impl<'a, D, F, Fut> Handler<'a, D> for F
-where
-    D: 'a,
-    F: Fn(&'a Context<'a, D>) -> Fut + Send + Sync,
-    Fut: Future<Output = Result<Value, HandlerError>> + Send + 'a,
-{
-    type Future = Fut;
-    fn call(&self, ctx: &'a Context<'a, D>) -> Fut {
-        self(ctx)
-    }
-}
-
-fn boxed_handler<D, F>(handler: F) -> Arc<HandlerFn<D>>
-where
-    F: for<'a> Handler<'a, D> + 'static,
-{
-    Arc::new(move |ctx| Box::pin(handler.call(ctx)) as HandlerFuture<'_>)
-}
-
-/// How a handler expects the transport to deliver matching messages.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum DeliveryKind {
-    /// Point-to-point delivery, normally used for command queues.
-    PointToPoint,
-    /// Fan-out delivery, normally used for event subscriptions.
-    FanOut,
-}
-
-/// Static message names attached to a handler spec.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum HandlerNames {
-    /// A single command or event name.
-    One(&'static str),
-    /// Multiple event names handled by one projection-style handler.
-    Many(&'static [&'static str]),
-}
-
-impl HandlerNames {
-    fn to_vec(self) -> Vec<&'static str> {
-        match self {
-            Self::One(name) => vec![name],
-            Self::Many(names) => names.to_vec(),
-        }
-    }
-}
-
-/// Transport-visible metadata for a registered handler.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct HandlerSpec {
-    names: HandlerNames,
-    pub kind: MessageKind,
-    pub delivery: DeliveryKind,
-}
-
-impl HandlerSpec {
-    /// A command handler that consumes JSON payloads.
-    pub const fn command(name: &'static str) -> Self {
-        Self {
-            names: HandlerNames::One(name),
-            kind: MessageKind::Command,
-            delivery: DeliveryKind::PointToPoint,
-        }
-    }
-
-    /// An event handler that consumes JSON payloads.
-    pub const fn event(name: &'static str) -> Self {
-        Self {
-            names: HandlerNames::One(name),
-            kind: MessageKind::Event,
-            delivery: DeliveryKind::FanOut,
-        }
-    }
-
-    /// An event handler that consumes several event names.
-    pub const fn events(names: &'static [&'static str]) -> Self {
-        Self {
-            names: HandlerNames::Many(names),
-            kind: MessageKind::Event,
-            delivery: DeliveryKind::FanOut,
-        }
-    }
-
-    /// Message names consumed by this handler.
-    pub fn names(&self) -> Vec<&'static str> {
-        self.names.to_vec()
-    }
-}
-
-/// A registered handler with optional guard.
-struct RegisteredHandler<D> {
-    guard: Option<Arc<GuardFn<D>>>,
-    handle: Arc<HandlerFn<D>>,
-}
-
-type OutboxConfigurator<D> = fn(&mut D, DynBusPublisher, String, Duration, u32, Option<String>);
-
-trait ErasedRoutes: Send + Sync {
-    fn handler_specs(&self) -> &[HandlerSpec];
-
-    fn dispatch<'a>(
-        &'a self,
-        message: &'a Message,
-        input: Value,
-        session: Session,
-    ) -> HandlerFuture<'a>;
-
-    fn configure_outbox_publisher(
-        &mut self,
-        publisher: DynBusPublisher,
-        worker_id: String,
-        lease: Duration,
-        max_attempts: u32,
-        service_name: Option<String>,
-    );
-}
-
-trait DynPublish: Send + Sync {
-    fn publish<'a>(
-        &'a self,
-        message: Message,
-    ) -> Pin<Box<dyn Future<Output = Result<(), TransportError>> + Send + 'a>>;
-}
-
-struct BusDynPublisher<B> {
-    bus: Arc<B>,
-}
-
-impl<B: Bus> DynPublish for BusDynPublisher<B> {
-    fn publish<'a>(
-        &'a self,
-        message: Message,
-    ) -> Pin<Box<dyn Future<Output = Result<(), TransportError>> + Send + 'a>> {
-        Box::pin(async move {
-            match message.kind {
-                MessageKind::Command => self.bus.send_message(message).await,
-                MessageKind::Event => self.bus.publish_message(message).await,
-            }
-        })
-    }
-}
-
-#[derive(Clone)]
-pub(crate) struct DynBusPublisher {
-    inner: Arc<dyn DynPublish>,
-}
-
-impl DynBusPublisher {
-    pub(crate) fn new<B>(bus: Arc<B>) -> Self
-    where
-        B: Bus + 'static,
-    {
-        Self {
-            inner: Arc::new(BusDynPublisher { bus }),
-        }
-    }
-}
-
-impl MessagePublisher for DynBusPublisher {
-    fn publish(
-        &self,
-        message: Message,
-    ) -> impl Future<Output = Result<(), TransportError>> + Send + '_ {
-        self.inner.publish(message)
-    }
-}
-
-fn configure_outbox_for<D>(
-    dependencies: &mut D,
-    publisher: DynBusPublisher,
-    worker_id: String,
-    lease: Duration,
-    max_attempts: u32,
-    service_name: Option<String>,
-) where
-    D: HasOutboxStore + ConfigurableOutboxPublisher,
-    D::OutboxStore: 'static,
-{
-    let hook = BusOutboxPublishHook::new(dependencies.outbox_store(), publisher, max_attempts)
-        .with_service(service_name);
-    dependencies.configure_outbox_publisher(OutboxPublisherConfig::new(
-        Arc::new(hook),
-        worker_id,
-        lease,
-    ));
-}
-
-/// Builder returned by [`Routes::command`], [`Routes::event`],
-/// [`Routes::events`], and [`Routes::handler`].
-pub struct RouteBuilder<D> {
-    routes: Routes<D>,
-    spec: HandlerSpec,
-}
-
-impl<D: Send + Sync + 'static> RouteBuilder<D> {
-    /// Register an async handler without a guard.
-    pub fn handle<F>(self, handler: F) -> Routes<D>
-    where
-        F: for<'a> Handler<'a, D> + 'static,
-    {
-        self.routes
-            .register_handler(self.spec, None, boxed_handler(handler))
-    }
-
-    /// Register an async handler with a (synchronous) guard.
-    pub fn guarded<G, F>(self, guard: G, handler: F) -> Routes<D>
-    where
-        G: Fn(&Context<D>) -> bool + Send + Sync + 'static,
-        F: for<'a> Handler<'a, D> + 'static,
-    {
-        self.routes
-            .register_handler(self.spec, Some(Arc::new(guard)), boxed_handler(handler))
-    }
-}
-
-/// A typed bundle of command/event handlers and the dependency value they use.
-///
-/// Handlers are keyed by kind, then name, so dispatch looks up by `&str`
-/// without allocating a key.
-pub struct Routes<D> {
-    dependencies: D,
-    handlers: HashMap<MessageKind, HashMap<String, RegisteredHandler<D>>>,
-    handler_specs: Vec<HandlerSpec>,
-    outbox_configurator: Option<OutboxConfigurator<D>>,
-}
-
-impl<D: Send + Sync + 'static> Routes<D> {
-    /// Build routes around an already-assembled dependency value.
-    pub(crate) fn from_dependencies(dependencies: D) -> Self {
-        Self {
-            dependencies,
-            handlers: HashMap::new(),
-            handler_specs: Vec::new(),
-            outbox_configurator: None,
-        }
-    }
-
-    fn with_outbox_configurator(mut self, configurator: OutboxConfigurator<D>) -> Self {
-        self.outbox_configurator = Some(configurator);
-        self
-    }
-
-    /// Fail fast if handlers are already registered. Dependency builders
-    /// reconstruct the route bundle around a new dependency type, which would
-    /// otherwise silently drop previously registered handlers.
-    fn assert_no_registrations(&self, builder: &str) {
-        assert!(
-            self.handlers.is_empty() && self.handler_specs.is_empty(),
-            "Routes::{builder} must be called before registering handlers"
-        );
-    }
-
-    /// Get a reference to the route dependencies.
-    pub fn dependencies(&self) -> &D {
-        &self.dependencies
-    }
-
-    /// Get the aggregate repository for routes whose dependencies expose one.
-    pub fn repo(&self) -> &D::Repo
-    where
-        D: HasRepo,
-    {
-        self.dependencies.repo()
-    }
-
-    /// Get the read-model store for routes whose dependencies expose one.
-    pub fn read_model_store(&self) -> &D::ReadModelStore
-    where
-        D: HasReadModelStore,
-    {
-        self.dependencies.read_model_store()
-    }
-
-    /// Start registering a command handler that consumes JSON payload input.
-    pub fn command(self, name: &'static str) -> RouteBuilder<D> {
-        self.handler(HandlerSpec::command(name))
-    }
-
-    /// Start registering an event handler that consumes JSON payload input.
-    pub fn event(self, name: &'static str) -> RouteBuilder<D> {
-        self.handler(HandlerSpec::event(name))
-    }
-
-    /// Start registering an event handler for several event names that consume JSON
-    /// payload input.
-    pub fn events(self, names: &'static [&'static str]) -> RouteBuilder<D> {
-        self.handler(HandlerSpec::events(names))
-    }
-
-    /// Start registering a handler from a transport-visible spec.
-    pub fn handler(self, spec: HandlerSpec) -> RouteBuilder<D> {
-        RouteBuilder { routes: self, spec }
-    }
-
-    fn register_handler(
-        mut self,
-        spec: HandlerSpec,
-        guard: Option<Arc<GuardFn<D>>>,
-        handle: Arc<HandlerFn<D>>,
-    ) -> Self {
-        let by_name = self.handlers.entry(spec.kind).or_default();
-        let names = spec.names();
-        for (position, name) in names.iter().enumerate() {
-            assert!(
-                !by_name.contains_key(*name) && !names[..position].contains(name),
-                "duplicate route registration for {:?} `{}`",
-                spec.kind,
-                name
-            );
-        }
-
-        for name in names {
-            by_name.insert(
-                name.to_string(),
-                RegisteredHandler {
-                    guard: guard.clone(),
-                    handle: handle.clone(),
-                },
-            );
-        }
-        self.handler_specs.push(spec);
-        self
-    }
-
-    fn registered_keys(&self) -> Vec<(MessageKind, String)> {
-        self.handlers
-            .iter()
-            .flat_map(|(kind, by_name)| by_name.keys().map(move |name| (*kind, name.clone())))
-            .collect()
-    }
-
-    async fn invoke(
-        &self,
-        message: &Message,
-        input: Value,
-        session: Session,
-    ) -> Result<Value, HandlerError> {
-        // Clone the handler/guard Arcs so the handler map is not borrowed across
-        // the (awaited) handler future.
-        let (guard, handle) = {
-            let handler = self
-                .handlers
-                .get(&message.kind)
-                .and_then(|by_name| by_name.get(message.name.as_str()))
-                .ok_or_else(|| HandlerError::UnknownCommand(message.name.clone()))?;
-            (handler.guard.clone(), handler.handle.clone())
-        };
-        let ctx = Context::new(message, input, session, &self.dependencies);
-
-        // Run guard (synchronous) if present.
-        if let Some(guard) = &guard {
-            if !guard(&ctx) {
-                return Err(HandlerError::GuardRejected(message.name.clone()));
-            }
-        }
-
-        handle(&ctx).await
-    }
-}
-
-impl<D> ErasedRoutes for Routes<D>
-where
-    D: Send + Sync + 'static,
-{
-    fn handler_specs(&self) -> &[HandlerSpec] {
-        &self.handler_specs
-    }
-
-    fn dispatch<'a>(
-        &'a self,
-        message: &'a Message,
-        input: Value,
-        session: Session,
-    ) -> HandlerFuture<'a> {
-        Box::pin(self.invoke(message, input, session))
-    }
-
-    fn configure_outbox_publisher(
-        &mut self,
-        publisher: DynBusPublisher,
-        worker_id: String,
-        lease: Duration,
-        max_attempts: u32,
-        service_name: Option<String>,
-    ) {
-        if let Some(configurator) = self.outbox_configurator {
-            configurator(
-                &mut self.dependencies,
-                publisher,
-                worker_id,
-                lease,
-                max_attempts,
-                service_name,
-            );
-        }
-    }
-}
-
-/// A microservice deployment that routes messages to one or more route bundles.
-pub struct Service {
-    name: Option<String>,
-    routes: Vec<Box<dyn ErasedRoutes>>,
-    index: HashMap<MessageKind, HashMap<String, usize>>,
-    handler_specs: Vec<HandlerSpec>,
-    runner: Option<ServiceRunner>,
-}
-
-impl Service {
-    /// Start building a deployment-level service.
-    pub fn new() -> Self {
-        Self {
-            name: None,
-            routes: Vec::new(),
-            index: HashMap::new(),
-            handler_specs: Vec::new(),
-            runner: None,
-        }
-    }
-
-    /// Build a service from a single route bundle.
-    pub fn route<D>(routes: Routes<D>) -> Self
-    where
-        D: Send + Sync + 'static,
-    {
-        Self::new().routes(routes)
-    }
-
-    /// Assign a stable service/deployment identity.
-    ///
-    /// Broker-backed buses use this as the default durable consumer group when the
-    /// bus itself was not configured with an explicit group. Use the same name for
-    /// every replica of one service deployment; use different names for independent
-    /// event consumers that each need their own event copy.
-    pub fn named(mut self, name: impl Into<String>) -> Self {
-        self.name = Some(name.into());
-        self
-    }
-
-    /// The stable service/deployment identity, if one was configured.
-    pub fn name(&self) -> Option<&str> {
-        self.name.as_deref()
-    }
-
-    /// Install the bus run behavior (used by `with_bus`).
-    pub(crate) fn set_runner(&mut self, runner: ServiceRunner) {
-        self.runner = Some(runner);
-    }
-
-    /// Take the installed bus run behavior (used by `run`).
-    pub(crate) fn take_runner(&mut self) -> Option<ServiceRunner> {
-        self.runner.take()
-    }
-
-    /// Add a typed route bundle to this service.
-    pub fn routes<D>(mut self, routes: Routes<D>) -> Self
-    where
-        D: Send + Sync + 'static,
-    {
-        self.add_routes(routes);
-        self
-    }
-
-    fn add_routes<D>(&mut self, routes: Routes<D>)
-    where
-        D: Send + Sync + 'static,
-    {
-        let keys = routes.registered_keys();
-        for (kind, name) in &keys {
-            assert!(
-                !self.handles_message(*kind, name),
-                "duplicate route registration for {:?} `{}`",
-                kind,
-                name
-            );
-        }
-
-        let route_index = self.routes.len();
-        for (kind, name) in keys {
-            self.index
-                .entry(kind)
-                .or_default()
-                .insert(name, route_index);
-        }
-        self.handler_specs.extend_from_slice(routes.handler_specs());
-        self.routes.push(Box::new(routes));
-    }
-
-    /// Dispatch a command by name.
-    ///
-    /// Builds a `Context` from the input and session, looks up the handler,
-    /// runs the guard (if any), then calls the handler.
-    pub async fn dispatch(
-        &self,
-        command: &str,
-        input: Value,
-        session: Session,
-    ) -> Result<Value, HandlerError> {
-        #[cfg(feature = "metrics")]
-        let started = Instant::now();
-        let result = self.dispatch_command_inner(command, input, session).await;
-        #[cfg(feature = "metrics")]
-        {
-            let error = result.as_ref().err();
-            crate::metrics::record_microsvc_dispatch(
-                self.name(),
-                MessageKind::Command,
-                crate::telemetry::handler_message_label(command, error),
-                error
-                    .map(crate::telemetry::handler_error_status)
-                    .unwrap_or(crate::telemetry::dispatch_status::SUCCESS),
-                started.elapsed(),
-            );
-        }
-        result
-    }
-
-    async fn dispatch_command_inner(
-        &self,
-        command: &str,
-        input: Value,
-        session: Session,
-    ) -> Result<Value, HandlerError> {
-        if !self.handles_message(MessageKind::Command, command) {
-            return Err(HandlerError::UnknownCommand(command.to_string()));
-        }
-
-        let payload = serde_json::to_vec(&input).map_err(|e| {
-            HandlerError::DecodeFailed(format!("invalid JSON input for command '{command}': {e}"))
-        })?;
-        let metadata = session
-            .variables()
-            .iter()
-            .map(|(key, value)| (key.clone(), value.clone()))
-            .collect();
-        let message = Message {
-            id: None,
-            name: command.to_string(),
-            kind: MessageKind::Command,
-            payload,
-            content_type: "application/json".to_string(),
-            metadata,
-        };
-
-        self.invoke_with_dispatch_span(&message, input, session)
-            .await
-    }
-
-    /// Dispatch a `CommandRequest`, returning a `CommandResponse`.
-    pub async fn dispatch_request(&self, request: &CommandRequest) -> CommandResponse {
-        let session = Session::from_map(request.session_variables.clone());
-        match self
-            .dispatch(&request.command, request.input.clone(), session)
-            .await
-        {
-            Ok(value) => CommandResponse {
-                status: 200,
-                body: value,
-            },
-            Err(e) => CommandResponse {
-                status: e.status_code(),
-                body: serde_json::json!({ "error": e.to_string() }),
-            },
-        }
-    }
-
-    /// Dispatch a transport message.
-    pub async fn dispatch_message(&self, message: &Message) -> Result<Value, HandlerError> {
-        #[cfg(feature = "metrics")]
-        let started = Instant::now();
-        let result = self.dispatch_message_inner(message).await;
-        #[cfg(feature = "metrics")]
-        {
-            let error = result.as_ref().err();
-            crate::metrics::record_microsvc_dispatch(
-                self.name(),
-                message.kind,
-                crate::telemetry::handler_message_label(message.name(), error),
-                error
-                    .map(crate::telemetry::handler_error_status)
-                    .unwrap_or(crate::telemetry::dispatch_status::SUCCESS),
-                started.elapsed(),
-            );
-        }
-        result
-    }
-
-    async fn dispatch_message_inner(&self, message: &Message) -> Result<Value, HandlerError> {
-        if !self.handles_message(message.kind, &message.name) {
-            return Err(HandlerError::UnknownCommand(message.name.clone()));
-        }
-
-        let input = match message_to_json_input(message) {
-            Ok(input) => input,
-            // Binary payloads (bitcode, octet-stream) legitimately fail JSON
-            // parsing: handlers for those read `ctx.message().payload` directly,
-            // so a `Null` input is the intended fallback. A payload that
-            // *claims* to be JSON but does not parse is a decode error — surface
-            // it instead of silently nulling the input.
-            Err(_) if !is_json_content_type(&message.content_type) => Value::Null,
-            Err(err) => return Err(err),
-        };
-        let session = message_to_session(message);
-        self.invoke_with_dispatch_span(message, input, session)
-            .await
-    }
-
-    async fn invoke_with_dispatch_span(
-        &self,
-        message: &Message,
-        input: Value,
-        session: Session,
-    ) -> Result<Value, HandlerError> {
-        #[cfg(feature = "otel")]
-        {
-            use tracing::Instrument as _;
-
-            let span = microsvc_dispatch_span(message);
-            crate::trace_context::set_span_parent_from_metadata_if_no_current_span(
-                &span,
-                &message.metadata,
-            );
-            return self.invoke(message, input, session).instrument(span).await;
-        }
-
-        #[cfg(not(feature = "otel"))]
-        {
-            self.invoke(message, input, session).await
-        }
-    }
-
-    async fn invoke(
-        &self,
-        message: &Message,
-        input: Value,
-        session: Session,
-    ) -> Result<Value, HandlerError> {
-        let route_index = self
-            .index
-            .get(&message.kind)
-            .and_then(|by_name| by_name.get(message.name.as_str()))
-            .copied()
-            .ok_or_else(|| HandlerError::UnknownCommand(message.name.clone()))?;
-        #[cfg(feature = "otel")]
-        let handler_span = microsvc_handler_span(message);
-        let dispatch = self.routes[route_index].dispatch(message, input, session);
-
-        #[cfg(feature = "otel")]
-        {
-            use tracing::Instrument as _;
-
-            return dispatch.instrument(handler_span).await;
-        }
-
-        #[cfg(not(feature = "otel"))]
-        {
-            dispatch.await
-        }
-    }
-
-    /// List registered command names.
-    pub fn command_names(&self) -> Vec<&str> {
-        names_by_kind(&self.handler_specs, MessageKind::Command)
-    }
-
-    /// List registered event names.
-    pub fn event_names(&self) -> Vec<&str> {
-        names_by_kind(&self.handler_specs, MessageKind::Event)
-    }
-
-    /// Return transport metadata for registered handlers.
-    pub fn handler_specs(&self) -> &[HandlerSpec] {
-        &self.handler_specs
-    }
-
-    /// Return the command/event names a transport should subscribe to.
-    pub fn subscription_plan(&self) -> SubscriptionPlan {
-        let mut plan = SubscriptionPlan::default();
-
-        for spec in &self.handler_specs {
-            for name in spec.names() {
-                let bucket = match spec.kind {
-                    MessageKind::Command => &mut plan.commands,
-                    MessageKind::Event => &mut plan.events,
-                };
-                if !bucket.iter().any(|existing| existing == name) {
-                    bucket.push(name.to_string());
-                }
-            }
-        }
-
-        plan
-    }
-
-    /// Return whether this service has a handler for the message name.
-    pub fn handles(&self, name: &str) -> bool {
-        self.index
-            .values()
-            .any(|by_name| by_name.contains_key(name))
-    }
-
-    /// Return whether this service has a handler for this message kind and name.
-    pub fn handles_message(&self, kind: MessageKind, name: &str) -> bool {
-        self.index
-            .get(&kind)
-            .is_some_and(|by_name| by_name.contains_key(name))
-    }
-
-    /// Return whether this service has an event handler for the message name.
-    pub fn handles_event(&self, name: &str) -> bool {
-        self.handles_message(MessageKind::Event, name)
-    }
-
-    /// Configure every route bundle that supports immediate outbox publishing.
-    pub(crate) fn configure_outbox_publishers(
-        &mut self,
-        publisher: DynBusPublisher,
-        worker_id: String,
-        lease: Duration,
-        max_attempts: u32,
-    ) {
-        let service_name = self.name.clone();
-        for route in &mut self.routes {
-            route.configure_outbox_publisher(
-                publisher.clone(),
-                worker_id.clone(),
-                lease,
-                max_attempts,
-                service_name.clone(),
-            );
-        }
-    }
-}
-
-impl Default for Service {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-// =============================================================================
-// Dependency builders: `Routes::new().with_repo(..)`
-// =============================================================================
-
-impl Default for Routes<()> {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-impl Routes<()> {
-    /// Start building a typed route bundle.
-    pub fn new() -> Self {
-        Self::from_dependencies(())
-    }
-
-    /// Use any custom dependency value for this route bundle.
-    pub fn with_dependencies<D>(self, dependencies: D) -> Routes<D>
-    where
-        D: Send + Sync + 'static,
-    {
-        self.assert_no_registrations("with_dependencies");
-        Routes::from_dependencies(dependencies)
-    }
-
-    /// Use an aggregate repository as the route bundle's dependency.
-    pub fn with_repo<R>(self, repo: R) -> Routes<R>
-    where
-        R: HasRepo + HasOutboxStore + ConfigurableOutboxPublisher + Send + Sync + 'static,
-    {
-        self.assert_no_registrations("with_repo");
-        Routes::from_dependencies(repo).with_outbox_configurator(configure_outbox_for::<R>)
-    }
-
-    /// Use a read-model store as the route bundle's dependency.
-    pub fn with_read_model_store<S>(self, read_model_store: S) -> Routes<S>
-    where
-        S: HasReadModelStore + Send + Sync + 'static,
-    {
-        self.assert_no_registrations("with_read_model_store");
-        Routes::from_dependencies(read_model_store)
-    }
-}
-
-impl<R> Routes<R>
-where
-    R: HasRepo + HasOutboxStore + ConfigurableOutboxPublisher + Send + Sync + 'static,
-{
-    /// Add a read-model store alongside the aggregate repository, so handlers can
-    /// reach both via `ctx.repo()` and `ctx.read_model_store()`. Call after
-    /// `with_repo`.
-    pub fn with_read_model_store<S>(
-        self,
-        read_model_store: S,
-    ) -> Routes<RepoReadModelDependencies<R, S>>
-    where
-        S: HasReadModelStore + Send + Sync + 'static,
-    {
-        self.assert_no_registrations("with_read_model_store");
-        Routes::from_dependencies(RepoReadModelDependencies::new(
-            self.dependencies,
-            read_model_store,
-        ))
-        .with_outbox_configurator(configure_outbox_for::<RepoReadModelDependencies<R, S>>)
-    }
-}
-
-// =============================================================================
-// Helpers: convert transport messages to dispatch inputs
-// =============================================================================
-
-fn names_by_kind(specs: &[HandlerSpec], kind: MessageKind) -> Vec<&str> {
-    let mut names = Vec::new();
-
-    for spec in specs.iter().filter(|spec| spec.kind == kind) {
-        for name in spec.names() {
-            if !names.contains(&name) {
-                names.push(name);
-            }
-        }
-    }
-
-    names
-}
-
-/// Whether a content type declares a JSON payload (`application/json` or any
-/// `+json` structured suffix), ignoring parameters like `;charset=utf-8`.
-fn is_json_content_type(content_type: &str) -> bool {
-    let essence = content_type
-        .split(';')
-        .next()
-        .unwrap_or(content_type)
-        .trim()
-        .to_ascii_lowercase();
-    essence == "application/json" || essence.ends_with("+json")
-}
-
-#[cfg(feature = "otel")]
-fn microsvc_dispatch_span(message: &Message) -> tracing::Span {
-    crate::telemetry::microsvc_dispatch_span(message)
-}
-
-#[cfg(feature = "otel")]
-fn microsvc_handler_span(message: &Message) -> tracing::Span {
-    crate::telemetry::microsvc_handler_span(message)
-}
-
-fn message_to_json_input(message: &Message) -> Result<Value, HandlerError> {
-    serde_json::from_slice::<Value>(&message.payload).map_err(|e| {
-        HandlerError::DecodeFailed(format!(
-            "invalid JSON payload for message '{}': {}",
-            message.name, e
-        ))
-    })
-}
-
-fn message_to_session(message: &Message) -> Session {
-    let vars: HashMap<String, String> = message
-        .metadata
-        .iter()
-        .map(|(key, value)| (key.to_ascii_lowercase(), value.clone()))
-        .collect();
-    Session::from_map(vars)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::{
-        sourced, AggregateBuilder, AggregateRepository, Entity, InMemoryRepository, Queueable,
-        QueuedRepository,
-    };
-    use serde_json::json;
-
-    #[derive(Default)]
-    struct RouteComboAggregate {
-        entity: Entity,
-    }
-
-    #[sourced(entity)]
-    impl RouteComboAggregate {
-        #[event("created")]
-        fn create(&mut self) {
-            self.entity.set_id("route-combo");
-        }
-    }
-
-    type RouteComboRepo =
-        AggregateRepository<QueuedRepository<InMemoryRepository>, RouteComboAggregate>;
-    type RouteComboDeps = RepoReadModelDependencies<RouteComboRepo, InMemoryRepository>;
-
-    fn test_routes() -> Routes<()> {
-        Routes::new().with_dependencies(())
-    }
-
-    fn test_service(routes: Routes<()>) -> Service {
-        Service::new().routes(routes)
-    }
-
-    #[test]
-    fn named_service_preserves_identity_with_route_bundles() {
-        let routes = Routes::new().with_read_model_store(crate::InMemoryRepository::new());
-        let service = Service::new().named("todo-api").routes(routes);
-
-        assert_eq!(service.name(), Some("todo-api"));
-        assert_eq!(
-            crate::bus::MessageRouter::consumer_group(&service),
-            Some("todo-api")
-        );
-    }
-
-    #[tokio::test]
-    async fn service_collects_route_bundles_with_different_dependencies() {
-        let service = Service::new()
-            .routes(
-                Routes::new()
-                    .with_dependencies(String::from("orders"))
-                    .command("string.dep")
-                    .handle(|ctx: &Context<String>| {
-                        let dep = ctx.dependencies().clone();
-                        async move { Ok(json!({ "dependency": dep })) }
-                    }),
-            )
-            .routes(
-                Routes::new()
-                    .with_dependencies(7_u32)
-                    .event("number.dep")
-                    .handle(|ctx: &Context<u32>| {
-                        let dep = *ctx.dependencies();
-                        async move { Ok(json!({ "dependency": dep })) }
-                    }),
-            );
-
-        let command = service
-            .dispatch("string.dep", json!({}), Session::new())
-            .await
-            .unwrap();
-        let event = service
-            .dispatch_message(&Message::new(
-                "number.dep",
-                MessageKind::Event,
-                br#"{}"#.to_vec(),
-            ))
-            .await
-            .unwrap();
-
-        assert_eq!(command, json!({ "dependency": "orders" }));
-        assert_eq!(event, json!({ "dependency": 7 }));
-        assert_eq!(
-            service.subscription_plan(),
-            SubscriptionPlan {
-                commands: vec!["string.dep".to_string()],
-                events: vec!["number.dep".to_string()],
-            }
-        );
-    }
-
-    #[tokio::test]
-    async fn service_dispatches_all_route_dependency_builder_combinations() {
-        let repo_only = InMemoryRepository::new().queued().aggregate();
-        let combo_repo = InMemoryRepository::new().queued().aggregate();
-        let service = Service::new()
-            .routes(
-                Routes::new()
-                    .with_dependencies(String::from("custom"))
-                    .command("custom.route")
-                    .handle(|ctx: &Context<String>| {
-                        let dependency = ctx.dependencies().clone();
-                        async move { Ok(json!({ "route": dependency })) }
-                    }),
-            )
-            .routes(
-                Routes::new()
-                    .with_repo(repo_only)
-                    .command("repo.route")
-                    .handle(|ctx: &Context<RouteComboRepo>| {
-                        let _ = ctx.repo();
-                        async move { Ok(json!({ "route": "repo" })) }
-                    }),
-            )
-            .routes(
-                Routes::new()
-                    .with_read_model_store(InMemoryRepository::new())
-                    .event("read.route")
-                    .handle(|ctx: &Context<InMemoryRepository>| {
-                        let _ = ctx.read_model_store();
-                        async move { Ok(json!({ "route": "read" })) }
-                    }),
-            )
-            .routes(
-                Routes::new()
-                    .with_repo(combo_repo)
-                    .with_read_model_store(InMemoryRepository::new())
-                    .command("repo-read.route")
-                    .handle(|ctx: &Context<RouteComboDeps>| {
-                        let _ = ctx.repo();
-                        let _ = ctx.read_model_store();
-                        async move { Ok(json!({ "route": "repo-read" })) }
-                    }),
-            );
-
-        let custom = service
-            .dispatch("custom.route", json!({}), Session::new())
-            .await
-            .unwrap();
-        let repo = service
-            .dispatch("repo.route", json!({}), Session::new())
-            .await
-            .unwrap();
-        let read = service
-            .dispatch_message(&Message::new(
-                "read.route",
-                MessageKind::Event,
-                br#"{}"#.to_vec(),
-            ))
-            .await
-            .unwrap();
-        let repo_read = service
-            .dispatch("repo-read.route", json!({}), Session::new())
-            .await
-            .unwrap();
-
-        assert_eq!(custom, json!({ "route": "custom" }));
-        assert_eq!(repo, json!({ "route": "repo" }));
-        assert_eq!(read, json!({ "route": "read" }));
-        assert_eq!(repo_read, json!({ "route": "repo-read" }));
-        assert_eq!(
-            service.subscription_plan(),
-            SubscriptionPlan {
-                commands: vec![
-                    "custom.route".to_string(),
-                    "repo.route".to_string(),
-                    "repo-read.route".to_string(),
-                ],
-                events: vec!["read.route".to_string()],
-            }
-        );
-    }
-
-    #[test]
-    fn duplicate_route_names_within_bundle_are_rejected() {
-        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
-            let _routes = test_routes()
-                .command("same")
-                .handle(|_: &Context<()>| async move { Ok(json!({})) })
-                .command("same")
-                .handle(|_: &Context<()>| async move { Ok(json!({})) });
-        }));
-
-        assert!(result.is_err());
-    }
-
-    #[test]
-    fn duplicate_route_bundle_add_is_rejected_atomically() {
-        let mut service = Service::new().routes(
-            test_routes()
-                .command("same")
-                .handle(|_: &Context<()>| async move { Ok(json!({})) }),
-        );
-        let conflicting = Routes::new()
-            .with_dependencies(7_u32)
-            .command("same")
-            .handle(|_: &Context<u32>| async move { Ok(json!({})) })
-            .command("new")
-            .handle(|_: &Context<u32>| async move { Ok(json!({})) });
-
-        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
-            service.add_routes(conflicting);
-        }));
-
-        assert!(result.is_err());
-        assert!(service.handles_message(MessageKind::Command, "same"));
-        assert!(!service.handles_message(MessageKind::Command, "new"));
-        assert_eq!(service.routes.len(), 1);
-        assert_eq!(service.command_names(), vec!["same"]);
-    }
-
-    #[tokio::test]
-    async fn dispatch_returns_handler_result() {
-        let service = test_service(
-            test_routes()
-                .command("ping")
-                .handle(|_ctx: &Context<()>| async move { Ok(json!({ "pong": true })) }),
-        );
-        let result = service
-            .dispatch("ping", json!({}), Session::new())
-            .await
-            .unwrap();
-        assert_eq!(result, json!({ "pong": true }));
-    }
-
-    #[tokio::test]
-    async fn unknown_command() {
-        // This dispatch records the same {unnamed, unknown, unknown_command}
-        // series into the process-global registry that
-        // `metrics_bucket_unknown_command_under_fixed_message_label` asserts
-        // an exact count on — serialize against it.
-        #[cfg(feature = "metrics")]
-        let _guard = crate::metrics::async_lock_for_tests().await;
-
-        let service = test_service(
-            test_routes()
-                .command("ping")
-                .handle(|_ctx: &Context<()>| async move { Ok(json!({})) }),
-        );
-        let result = service.dispatch("unknown", json!({}), Session::new()).await;
-        assert!(matches!(result, Err(HandlerError::UnknownCommand(ref s)) if s == "unknown"));
-    }
-
-    #[cfg(feature = "metrics")]
-    #[tokio::test]
-    async fn metrics_bucket_unknown_command_under_fixed_message_label() {
-        let _guard = crate::metrics::async_lock_for_tests().await;
-        crate::metrics::reset_for_tests();
-
-        let service = test_service(
-            test_routes()
-                .command("ping")
-                .handle(|_ctx: &Context<()>| async move { Ok(json!({})) }),
-        );
-
-        let result = service
-            .dispatch("attacker-controlled-path", json!({}), Session::new())
-            .await;
-        assert!(matches!(result, Err(HandlerError::UnknownCommand(_))));
-
-        let text = crate::metrics::prometheus_text();
-        assert!(
-            text.contains(
-                "distributed_microsvc_dispatch_total{service=\"unnamed\",message_kind=\"command\",message=\"unknown\",status=\"unknown_command\"} 1"
-            ),
-            "unknown commands should use a bounded message label:\n{text}"
-        );
-        assert!(
-            !text.contains("attacker-controlled-path"),
-            "unknown command input must not become a metric label:\n{text}"
-        );
-    }
-
-    #[tokio::test]
-    async fn handler_error_propagates() {
-        let service = test_service(test_routes().command("fail").handle(
-            |_ctx: &Context<()>| async move { Err(HandlerError::Rejected("nope".into())) },
-        ));
-        let result = service.dispatch("fail", json!({}), Session::new()).await;
-        assert!(matches!(result, Err(HandlerError::Rejected(ref s)) if s == "nope"));
-    }
-
-    #[tokio::test]
-    async fn decode_error_from_bad_payload() {
-        #[derive(serde::Deserialize)]
-        struct Input {
-            _name: String,
-        }
-
-        let service = test_service(test_routes().command("typed").handle(|ctx: &Context<()>| {
-            let input = ctx.input::<Input>();
-            async move {
-                let _input = input?;
-                Ok(json!({}))
-            }
-        }));
-        let result = service
-            .dispatch("typed", json!({ "wrong": 1 }), Session::new())
-            .await;
-        assert!(matches!(result, Err(HandlerError::DecodeFailed(_))));
-    }
-
-    #[test]
-    fn command_names_list() {
-        let service = test_service(
-            test_routes()
-                .command("a")
-                .handle(|_: &Context<()>| async move { Ok(json!({})) })
-                .command("b")
-                .handle(|_: &Context<()>| async move { Ok(json!({})) }),
-        );
-        let mut cmds = service.command_names();
-        cmds.sort();
-        assert_eq!(cmds, vec!["a", "b"]);
-    }
-
-    #[test]
-    fn subscription_plan_separates_commands_and_events() {
-        const EVENTS: &[&str] = &["checkout.started", "seat.reserved"];
-
-        let service = test_service(
-            test_routes()
-                .command("checkout.start")
-                .handle(|_: &Context<()>| async move { Ok(json!({})) })
-                .events(EVENTS)
-                .guarded(|_| true, |_: &Context<()>| async move { Ok(json!({})) }),
-        );
-
-        assert_eq!(
-            service.subscription_plan(),
-            SubscriptionPlan {
-                commands: vec!["checkout.start".to_string()],
-                events: vec!["checkout.started".to_string(), "seat.reserved".to_string()],
-            }
-        );
-    }
-
-    #[test]
-    fn event_conveniences_record_event_names() {
-        const EVENTS: &[&str] = &["seat.added", "seat.reserved"];
-
-        let service = test_service(
-            test_routes()
-                .event("checkout.started")
-                .handle(|_: &Context<()>| async move { Ok(json!({})) })
-                .events(EVENTS)
-                .handle(|_: &Context<()>| async move { Ok(json!({})) }),
-        );
-
-        let mut events = service.event_names();
-        events.sort();
-        assert_eq!(
-            events,
-            vec!["checkout.started", "seat.added", "seat.reserved"]
-        );
-    }
-
-    #[tokio::test]
-    async fn command_and_event_handlers_can_share_a_name() {
-        let service = test_service(
-            test_routes()
-                .command("shared")
-                .handle(|ctx: &Context<()>| {
-                    let kind = format!("{:?}", ctx.message().kind);
-                    async move { Ok(json!({ "kind": kind })) }
-                })
-                .event("shared")
-                .handle(|ctx: &Context<()>| {
-                    let event_id = ctx.message().id().map(|s| s.to_string());
-                    async move { Ok(json!({ "event_id": event_id })) }
-                }),
-        );
-        let event_message =
-            Message::new("shared", MessageKind::Event, br#"{}"#.to_vec()).with_id("evt-1");
-
-        let command_result = service
-            .dispatch("shared", json!({}), Session::new())
-            .await
-            .unwrap();
-        let event_result = service.dispatch_message(&event_message).await.unwrap();
-
-        assert_eq!(command_result, json!({ "kind": "Command" }));
-        assert_eq!(event_result, json!({ "event_id": "evt-1" }));
-        assert!(service.handles_message(MessageKind::Command, "shared"));
-        assert!(service.handles_message(MessageKind::Event, "shared"));
-    }
-
-    #[tokio::test]
-    async fn dispatch_message_delivers_payload_json_by_default() {
-        let service = test_service(test_routes().event("checkout.started").handle(
-            |ctx: &Context<()>| {
-                let has_checkout_id = ctx.has_fields(&["checkout_id"]);
-                let event_id = ctx.message().id().map(|s| s.to_string());
-                let checkout_id = ctx.raw_input()["checkout_id"]
-                    .as_str()
-                    .map(|s| s.to_string());
-                let user_id = ctx.user_id().map(|s| s.to_string());
-                async move {
-                    if !has_checkout_id {
-                        return Err(HandlerError::Rejected("missing checkout_id".into()));
-                    }
-
-                    Ok(json!({
-                        "event_id": event_id,
-                        "checkout_id": checkout_id.unwrap(),
-                        "user_id": user_id?,
-                    }))
-                }
-            },
-        ));
-        let message = Message {
-            id: Some("evt-1".to_string()),
-            name: "checkout.started".to_string(),
-            kind: MessageKind::Event,
-            payload: br#"{"checkout_id":"checkout-1"}"#.to_vec(),
-            content_type: "application/json".to_string(),
-            metadata: vec![("X-User-Id".to_string(), "user-1".to_string())],
-        };
-
-        let result = service.dispatch_message(&message).await.unwrap();
-
-        assert_eq!(
-            result,
-            json!({ "event_id": "evt-1", "checkout_id": "checkout-1", "user_id": "user-1" })
-        );
-    }
-
-    #[tokio::test]
-    async fn dispatch_message_surfaces_malformed_json_as_decode_error() {
-        let service = test_service(test_routes().event("checkout.started").handle(
-            |_ctx: &Context<()>| async move { panic!("handler must not run on a decode error") },
-        ));
-        let message = Message::new(
-            "checkout.started",
-            MessageKind::Event,
-            br#"{"checkout_id": oops"#.to_vec(),
-        );
-
-        let err = service.dispatch_message(&message).await.unwrap_err();
-
-        match err {
-            HandlerError::DecodeFailed(detail) => {
-                assert!(
-                    detail.contains("invalid JSON payload") && detail.contains("checkout.started"),
-                    "decode error should carry the parse failure, got: {detail}"
-                );
-            }
-            other => panic!("expected DecodeFailed, got {other:?}"),
-        }
-    }
-
-    #[tokio::test]
-    async fn dispatch_message_nulls_input_for_non_json_payloads() {
-        let service = test_service(test_routes().event("blob.stored").handle(
-            |ctx: &Context<()>| {
-                let input_is_null = ctx.raw_input().is_null();
-                let payload = ctx.message().payload().to_vec();
-                async move { Ok(json!({ "null_input": input_is_null, "len": payload.len() })) }
-            },
-        ));
-        let mut message = Message::new("blob.stored", MessageKind::Event, vec![0, 159, 146, 150]);
-        message.content_type = "application/octet-stream".to_string();
-
-        let result = service.dispatch_message(&message).await.unwrap();
-
-        assert_eq!(result, json!({ "null_input": true, "len": 4 }));
-    }
-
-    #[tokio::test]
-    async fn dispatch_message_always_exposes_message_metadata() {
-        let service = test_service(test_routes().event("seat.reserved").guarded(
-            |ctx| ctx.message().id().is_some(),
-            |ctx: &Context<()>| {
-                let input: Result<Value, _> = ctx.input();
-                let message = ctx.message();
-                let event_id = message.id().map(|s| s.to_string());
-                let name = message.name().to_string();
-                let correlation_id = message.correlation_id().map(|s| s.to_string());
-                async move {
-                    let input = input?;
-                    Ok(json!({
-                        "event_id": event_id,
-                        "name": name,
-                        "correlation_id": correlation_id,
-                        "seat_id": input["seat_id"].as_str().unwrap(),
-                    }))
-                }
-            },
-        ));
-        let message = Message {
-            id: Some("evt-2".to_string()),
-            name: "seat.reserved".to_string(),
-            kind: MessageKind::Event,
-            payload: br#"{"seat_id":"A-7"}"#.to_vec(),
-            content_type: "application/json".to_string(),
-            metadata: vec![("Correlation_ID".to_string(), "checkout-1".to_string())],
-        };
-
-        let result = service.dispatch_message(&message).await.unwrap();
-
-        assert_eq!(
-            result,
-            json!({
-                "event_id": "evt-2",
-                "name": "seat.reserved",
-                "correlation_id": "checkout-1",
-                "seat_id": "A-7",
-            })
-        );
-    }
-
-    #[tokio::test]
-    async fn dispatch_exposes_trace_context_from_session_metadata() {
-        let traceparent = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01";
-        let service = test_service(test_routes().command("checkout.start").handle(
-            |ctx: &Context<()>| {
-                let trace_context = ctx.message().trace_context();
-                async move {
-                    Ok(json!({
-                        "traceparent": trace_context.traceparent,
-                        "tracestate": trace_context.tracestate,
-                    }))
-                }
-            },
-        ));
-        let session = Session::from_map(HashMap::from([
-            ("traceparent".to_string(), traceparent.to_string()),
-            ("tracestate".to_string(), "vendor=value".to_string()),
-        ]));
-
-        let result = service
-            .dispatch("checkout.start", json!({}), session)
-            .await
-            .unwrap();
-
-        assert_eq!(
-            result,
-            json!({ "traceparent": traceparent, "tracestate": "vendor=value" })
-        );
-    }
-
-    #[tokio::test]
-    async fn guard_passes() {
-        let service = test_service(test_routes().command("greet").guarded(
-            |ctx| ctx.has_fields(&["name"]),
-            |ctx: &Context<()>| {
-                let name = ctx.raw_input()["name"].as_str().map(|s| s.to_string());
-                async move { Ok(json!({ "hello": name.unwrap() })) }
-            },
-        ));
-        let result = service
-            .dispatch("greet", json!({ "name": "Pat" }), Session::new())
-            .await
-            .unwrap();
-        assert_eq!(result, json!({ "hello": "Pat" }));
-    }
-
-    #[tokio::test]
-    async fn guard_rejects() {
-        let service = test_service(test_routes().command("greet").guarded(
-            |ctx| ctx.has_fields(&["name"]),
-            |_ctx: &Context<()>| async move {
-                panic!("handler should not run");
-                #[allow(unreachable_code)]
-                Ok(json!({}))
-            },
-        ));
-        let result = service
-            .dispatch("greet", json!({ "wrong": 1 }), Session::new())
-            .await;
-        assert!(matches!(result, Err(HandlerError::GuardRejected(ref s)) if s == "greet"));
-    }
-
-    #[tokio::test]
-    async fn guard_checks_session() {
-        let service = test_service(test_routes().command("admin").guarded(
-            |ctx| ctx.role() == Some("admin"),
-            |_ctx: &Context<()>| async move { Ok(json!({ "ok": true })) },
-        ));
-
-        // No role
-        assert!(service
-            .dispatch("admin", json!({}), Session::new())
-            .await
-            .is_err());
-
-        // Admin role
-        let mut session = Session::new();
-        session.set(crate::microsvc::ROLE_KEY, "admin");
-        assert!(service.dispatch("admin", json!({}), session).await.is_ok());
-    }
-
-    #[tokio::test]
-    async fn dispatch_request_success() {
-        let service = test_service(
-            test_routes()
-                .command("ping")
-                .handle(|_ctx: &Context<()>| async move { Ok(json!({ "pong": true })) }),
-        );
-        let request = CommandRequest {
-            command: "ping".to_string(),
-            input: json!({}),
-            session_variables: HashMap::new(),
-        };
-        let response = service.dispatch_request(&request).await;
-        assert_eq!(response.status, 200);
-        assert_eq!(response.body, json!({ "pong": true }));
-    }
-
-    #[tokio::test]
-    async fn dispatch_request_error_codes() {
-        let service = test_service(
-            test_routes()
-                .command("reject")
-                .handle(|_: &Context<()>| async move { Err(HandlerError::Rejected("no".into())) })
-                .command("unauth")
-                .handle(|ctx: &Context<()>| {
-                    let user_id = ctx.user_id().map(|s| s.to_string());
-                    async move {
-                        let _ = user_id?;
-                        Ok(json!({}))
-                    }
-                }),
-        );
-
-        let resp = service
-            .dispatch_request(&CommandRequest {
-                command: "unknown".to_string(),
-                input: json!({}),
-                session_variables: HashMap::new(),
-            })
-            .await;
-        assert_eq!(resp.status, 404);
-
-        let resp = service
-            .dispatch_request(&CommandRequest {
-                command: "reject".to_string(),
-                input: json!({}),
-                session_variables: HashMap::new(),
-            })
-            .await;
-        assert_eq!(resp.status, 422);
-
-        let resp = service
-            .dispatch_request(&CommandRequest {
-                command: "unauth".to_string(),
-                input: json!({}),
-                session_variables: HashMap::new(),
-            })
-            .await;
-        assert_eq!(resp.status, 401);
-    }
-
-    #[tokio::test]
-    async fn dispatch_request_passes_session() {
-        let service = test_service(test_routes().command("whoami").handle(|ctx: &Context<()>| {
-            let user_id = ctx.user_id().map(|s| s.to_string());
-            async move {
-                let user_id = user_id?;
-                Ok(json!({ "user_id": user_id }))
-            }
-        }));
-        let mut vars = HashMap::new();
-        vars.insert(crate::microsvc::USER_ID_KEY.to_string(), "user-99".to_string());
-        let request = CommandRequest {
-            command: "whoami".to_string(),
-            input: json!({}),
-            session_variables: vars,
-        };
-        let response = service.dispatch_request(&request).await;
-        assert_eq!(response.status, 200);
-        assert_eq!(response.body, json!({ "user_id": "user-99" }));
-    }
-
-    #[test]
-    fn command_request_requires_session_variables_field() {
-        let json = r#"{"command":"ping","input":{}}"#;
-        let result: Result<CommandRequest, _> = serde_json::from_str(json);
-        assert!(result.is_err());
-    }
-}
-
-// =============================================================================
-// Request / Response types
-// =============================================================================
-
-/// An inbound command request.
-///
-/// Generic command envelope used by in-process dispatch and adapters that
-/// already decoded a gateway payload. Example shape:
-/// ```json
-/// {
-///   "command": "order.create",
-///   "input": { "product_id": "SKU-1" },
-///   "session_variables": { "x-user-id": "user-42" }
-/// }
-/// ```
-///
-/// `session_variables` keys are deployment convention (see [`Session`]). A
-/// query-layer action (Hasura, custom BFF, …) can map its native claims into
-/// these variables before calling `dispatch_request`.
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
-pub struct CommandRequest {
-    /// Command name (URL path, action name, or explicit field).
-    pub command: String,
-    /// JSON input payload.
-    pub input: Value,
-    /// Opaque session variables (identity claims, roles, tenant, etc.).
-    pub session_variables: HashMap<String, String>,
-}
-
-/// Response from dispatching a command.
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
-pub struct CommandResponse {
-    /// HTTP-style status code.
-    pub status: u16,
-    /// Response body (handler result or error).
-    pub body: Value,
-}
diff --git a/src/microsvc/service/causal.rs b/src/microsvc/service/causal.rs
new file mode 100644
index 00000000..206f6a88
--- /dev/null
+++ b/src/microsvc/service/causal.rs
@@ -0,0 +1,763 @@
+#[cfg(feature = "graphql")]
+use std::time::Duration;
+
+#[cfg(feature = "graphql")]
+use serde_json::Value;
+
+#[cfg(feature = "graphql")]
+use crate::command_ledger::CausalTransactionalCommit;
+#[cfg(feature = "graphql")]
+use crate::command_ledger::{
+    AttemptFence, CausalCommitBatch, CommandAttempt, CommandId, CommandLedgerError,
+    CommandLedgerState, CommandLedgerStore, CommandLookup, CommandLookupScope, CommandReplay,
+    TerminalCommandState,
+};
+#[cfg(feature = "graphql")]
+use crate::graphql::command_contract::{CommandConsistency, TypedCommandContract};
+#[cfg(feature = "graphql")]
+use crate::microsvc::error::HandlerError;
+#[cfg(feature = "graphql")]
+use crate::microsvc::session::Session;
+#[cfg(feature = "graphql")]
+use crate::projection_protocol::{
+    ProjectionObligationEvidence, ProjectionObligationEvidenceBatchRequest,
+    ProjectionObligationEvidenceRequest, ProjectionObservationKind, ProjectionProtocolStore,
+    ProjectionRecordScope, SameTransactionProjectionEvidence,
+};
+#[cfg(feature = "graphql")]
+use crate::repository::CommitBatch;
+
+/// Stable transport classification for a typed causal command dispatch.
+///
+/// Public receipt/status envelopes map this private error set onto a stable
+/// mutation edge without exposing repository details.
+#[derive(Debug)]
+#[cfg(feature = "graphql")]
+pub(crate) enum CausalDispatchError {
+    BadRequest(String),
+    Forbidden,
+    CommandIdReuse,
+    InProgress,
+    Expired,
+    Rejected {
+        code: &'static str,
+        status: u16,
+        message: String,
+    },
+    Handler(HandlerError),
+    Internal(String),
+}
+
+#[cfg(feature = "graphql")]
+impl CausalDispatchError {
+    pub(crate) fn code(&self) -> &'static str {
+        match self {
+            Self::BadRequest(_) => "BAD_REQUEST",
+            Self::Forbidden => "FORBIDDEN",
+            Self::CommandIdReuse => "COMMAND_ID_REUSE",
+            Self::InProgress => "COMMAND_IN_PROGRESS",
+            Self::Expired => "COMMAND_EXPIRED",
+            Self::Rejected { code, .. } => code,
+            Self::Handler(error) => match error.status_code() {
+                400 => "BAD_REQUEST",
+                401 => "UNAUTHORIZED",
+                403 => "FORBIDDEN",
+                404 => "NOT_FOUND",
+                422 => "REJECTED",
+                _ => "INTERNAL",
+            },
+            Self::Internal(_) => "INTERNAL",
+        }
+    }
+
+    pub(crate) fn status_code(&self) -> u16 {
+        match self {
+            Self::BadRequest(_) => 400,
+            Self::Forbidden => 403,
+            Self::CommandIdReuse | Self::InProgress => 409,
+            Self::Expired => 410,
+            Self::Rejected { status, .. } => *status,
+            Self::Handler(error) => error.status_code(),
+            Self::Internal(_) => 500,
+        }
+    }
+
+    pub(crate) fn client_message(&self) -> String {
+        match self {
+            Self::BadRequest(message) => message.clone(),
+            Self::Rejected { message, .. } => message.clone(),
+            Self::Forbidden => "command is not allowed".into(),
+            Self::CommandIdReuse => "command ID was already used for different input".into(),
+            Self::InProgress => "command is already in progress".into(),
+            Self::Expired => "command ID has expired".into(),
+            Self::Handler(error) => error.client_facing_message(),
+            Self::Internal(_) => "internal error".into(),
+        }
+    }
+}
+
+#[cfg(feature = "graphql")]
+impl std::fmt::Display for CausalDispatchError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Internal(detail) => formatter.write_str(detail),
+            _ => formatter.write_str(&self.client_message()),
+        }
+    }
+}
+
+#[cfg(feature = "graphql")]
+impl std::error::Error for CausalDispatchError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Handler(error) => Some(error),
+            _ => None,
+        }
+    }
+}
+
+#[cfg(feature = "graphql")]
+impl From<HandlerError> for CausalDispatchError {
+    fn from(error: HandlerError) -> Self {
+        Self::Handler(error)
+    }
+}
+
+/// Exact compiler-bound projection obligation retained by the durable command
+/// replay.
+///
+/// The canonical scope remains a crate-private typed value. A transport layer
+/// may hand it to the protocol token codec, but this type deliberately has no
+/// serialization implementation that could expose topology, partition, or key
+/// bytes directly.
+#[cfg(feature = "graphql")]
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct CausalCommandProjectionObligation {
+    pub(crate) projector: String,
+    pub(crate) model: String,
+    pub(crate) scope: ProjectionRecordScope,
+    pub(crate) observation_kind: ProjectionObservationKind,
+}
+
+/// Durable receipt material for one exact command attempt.
+///
+/// `direct_projection` is decoded from the versioned ledger replay envelope;
+/// it is never reconstructed from the current read-model row.
+#[cfg(feature = "graphql")]
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct CausalCommandReceiptSource {
+    pub(crate) command_id: String,
+    pub(crate) causation_id: String,
+    pub(crate) consistency: CommandConsistency,
+    pub(crate) state: CommandLedgerState,
+    pub(crate) outcome: Value,
+    pub(crate) obligations: Vec<CausalCommandProjectionObligation>,
+    pub(crate) direct_projection: Option<SameTransactionProjectionEvidence>,
+}
+
+#[cfg(feature = "graphql")]
+impl CausalCommandReceiptSource {
+    pub(super) fn from_replay(
+        consistency: CommandConsistency,
+        replay: CommandReplay,
+    ) -> Result<Self, CausalDispatchError> {
+        let direct_projection = replay
+            .direct_projection
+            .as_ref()
+            .map(SameTransactionProjectionEvidence::from_replay_value)
+            .transpose()
+            .map_err(|error| {
+                CausalDispatchError::Internal(format!(
+                    "stored direct projection evidence is invalid: {error}"
+                ))
+            })?;
+        let obligations = replay
+            .projection_obligations
+            .into_iter()
+            .map(|obligation| CausalCommandProjectionObligation {
+                projector: obligation.projector,
+                model: obligation.model,
+                scope: obligation.scope,
+                // The current command compiler binds finite confirmations only
+                // to relational records. Persisting dependency-vs-record kind
+                // becomes mandatory before embedded confirmations are enabled.
+                observation_kind: ProjectionObservationKind::Record,
+            })
+            .collect();
+        Ok(Self {
+            command_id: replay.command_id.as_str().to_string(),
+            causation_id: replay.causation_id.as_str().to_string(),
+            consistency,
+            state: replay.state,
+            outcome: replay.outcome,
+            obligations,
+            direct_projection,
+        })
+    }
+}
+
+/// Successful typed causal dispatch plus its exact durable receipt source.
+#[cfg(feature = "graphql")]
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct CausalDispatchResult {
+    pub(crate) payload: Value,
+    pub(crate) receipt: CausalCommandReceiptSource,
+}
+
+/// Stable public command-status vocabulary.
+#[cfg(feature = "graphql")]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum CausalCommandPublicState {
+    InProgress,
+    Accepted,
+    AcceptedPendingProjection,
+    Projected,
+    Rejected,
+    ProjectionFailed,
+    Expired,
+    Unknown,
+}
+
+#[cfg(feature = "graphql")]
+impl CausalCommandPublicState {
+    pub(crate) const fn as_str(self) -> &'static str {
+        match self {
+            Self::InProgress => "in_progress",
+            Self::Accepted => "accepted",
+            Self::AcceptedPendingProjection => "accepted_pending_projection",
+            Self::Projected => "projected",
+            Self::Rejected => "rejected",
+            Self::ProjectionFailed => "projection_failed",
+            Self::Expired => "expired",
+            Self::Unknown => "unknown",
+        }
+    }
+}
+
+/// Sanitized evidence state for one durable obligation.
+///
+/// A terminal failure is intentionally only a semantic marker. Failure IDs,
+/// codes, bytes, digests, source cursors, and repair generations never cross
+/// this service boundary.
+#[cfg(feature = "graphql")]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum CausalProjectionEvidenceState {
+    Pending,
+    Observed,
+    TerminalFailure,
+}
+
+#[cfg(feature = "graphql")]
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct CausalCommandProjectionEvidence {
+    pub(crate) obligation_index: usize,
+    pub(crate) state: CausalProjectionEvidenceState,
+    pub(crate) incarnation: Option<u64>,
+    pub(crate) revision: Option<u64>,
+}
+
+/// Authorized, non-enumerating status for a client-created command ID.
+///
+/// Typed scopes and observations are crate-private inputs to the opaque token
+/// codec. This type is not serializable and contains no raw failure material.
+#[cfg(feature = "graphql")]
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct CausalCommandPublicStatus {
+    pub(crate) state: CausalCommandPublicState,
+    pub(crate) command_id: String,
+    pub(crate) causation_id: Option<String>,
+    pub(crate) consistency: Option<CommandConsistency>,
+    pub(crate) outcome: Option<Value>,
+    pub(crate) obligations: Vec<CausalCommandProjectionObligation>,
+    pub(crate) evidence: Vec<CausalCommandProjectionEvidence>,
+    pub(crate) direct_projection: Option<SameTransactionProjectionEvidence>,
+}
+
+#[cfg(feature = "graphql")]
+impl CausalCommandPublicStatus {
+    pub(super) fn unknown(command_id: impl Into<String>) -> Self {
+        Self {
+            state: CausalCommandPublicState::Unknown,
+            command_id: command_id.into(),
+            causation_id: None,
+            consistency: None,
+            outcome: None,
+            obligations: Vec::new(),
+            evidence: Vec::new(),
+            direct_projection: None,
+        }
+    }
+
+    pub(super) fn is_unknown(&self) -> bool {
+        self.state == CausalCommandPublicState::Unknown
+    }
+}
+
+/// Error returned when attaching a GraphQL engine whose typed command
+/// inventory is not exactly the executable service inventory, or whose query
+/// storage cannot prove the identity required by a `Projected` command.
+#[cfg(feature = "graphql")]
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GraphqlServiceBindError(pub String);
+
+#[cfg(feature = "graphql")]
+impl std::fmt::Display for GraphqlServiceBindError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(&self.0)
+    }
+}
+
+#[cfg(feature = "graphql")]
+impl std::error::Error for GraphqlServiceBindError {}
+
+#[cfg(feature = "graphql")]
+pub(super) fn ensure_causal_grant(
+    contract: &TypedCommandContract,
+    session: &Session,
+) -> Result<(), CausalDispatchError> {
+    if contract.roles.is_empty()
+        || session
+            .role()
+            .is_some_and(|role| contract.roles.iter().any(|allowed| allowed == role))
+    {
+        Ok(())
+    } else {
+        Err(CausalDispatchError::Forbidden)
+    }
+}
+
+#[cfg(feature = "graphql")]
+pub(super) fn causal_handler_error_code(error: &HandlerError) -> &'static str {
+    match error.status_code() {
+        400 => "BAD_REQUEST",
+        401 => "UNAUTHORIZED",
+        403 => "FORBIDDEN",
+        404 => "NOT_FOUND",
+        422 => "REJECTED",
+        _ => "REJECTED",
+    }
+}
+
+#[cfg(feature = "graphql")]
+pub(super) fn internal_ledger_error(error: CommandLedgerError) -> CausalDispatchError {
+    CausalDispatchError::Internal(error.to_string())
+}
+
+#[cfg(feature = "graphql")]
+pub(super) fn replay_result(
+    consistency: CommandConsistency,
+    replay: CommandReplay,
+) -> Result<CausalDispatchResult, CausalDispatchError> {
+    match replay.state {
+        CommandLedgerState::Accepted
+        | CommandLedgerState::AcceptedPendingProjection
+        | CommandLedgerState::Projected
+        | CommandLedgerState::ProjectionFailed => {
+            let receipt = CausalCommandReceiptSource::from_replay(consistency, replay)?;
+            Ok(CausalDispatchResult {
+                payload: receipt.outcome.clone(),
+                receipt,
+            })
+        }
+        CommandLedgerState::Rejected => replay_rejection(replay.outcome),
+        CommandLedgerState::InProgress
+        | CommandLedgerState::RetryableUnknown
+        | CommandLedgerState::Expired => Err(CausalDispatchError::Internal(
+            "stored replay has a non-terminal state".into(),
+        )),
+    }
+}
+
+#[cfg(feature = "graphql")]
+pub(super) fn replay_rejection(
+    outcome: Value,
+) -> Result<CausalDispatchResult, CausalDispatchError> {
+    let error = outcome
+        .get("error")
+        .and_then(Value::as_object)
+        .ok_or_else(|| CausalDispatchError::Internal("stored rejection is malformed".into()))?;
+    let code = match error.get("code").and_then(Value::as_str) {
+        Some("BAD_REQUEST") => "BAD_REQUEST",
+        Some("UNAUTHORIZED") => "UNAUTHORIZED",
+        Some("FORBIDDEN") => "FORBIDDEN",
+        Some("NOT_FOUND") => "NOT_FOUND",
+        Some("REJECTED") => "REJECTED",
+        _ => {
+            return Err(CausalDispatchError::Internal(
+                "stored rejection code is invalid".into(),
+            ))
+        }
+    };
+    let status = error
+        .get("status")
+        .and_then(Value::as_u64)
+        .and_then(|status| u16::try_from(status).ok())
+        .filter(|status| (400..500).contains(status))
+        .ok_or_else(|| {
+            CausalDispatchError::Internal("stored rejection status is invalid".into())
+        })?;
+    let message = error
+        .get("message")
+        .and_then(Value::as_str)
+        .ok_or_else(|| CausalDispatchError::Internal("stored rejection message is invalid".into()))?
+        .to_string();
+    Err(CausalDispatchError::Rejected {
+        code,
+        status,
+        message,
+    })
+}
+
+#[cfg(feature = "graphql")]
+pub(super) async fn commit_causal_rejection<R>(
+    repository: &R,
+    attempt: CommandAttempt,
+    consistency: CommandConsistency,
+    retention: Duration,
+    code: &'static str,
+    status: u16,
+    message: String,
+) -> Result<CausalDispatchResult, CausalDispatchError>
+where
+    R: CommandLedgerStore + CausalTransactionalCommit + Send + Sync,
+{
+    let outcome = serde_json::json!({
+        "error": {
+            "code": code,
+            "status": status,
+            "message": message,
+        }
+    });
+    let fence = attempt.fence();
+    let completion = attempt
+        .complete(TerminalCommandState::Rejected, outcome, retention)
+        .map_err(internal_ledger_error)?;
+    match repository
+        .commit_causal_batch(CausalCommitBatch::new(CommitBatch::empty(), completion))
+        .await
+    {
+        Ok(()) => Err(CausalDispatchError::Rejected {
+            code,
+            status,
+            message,
+        }),
+        Err(error) => {
+            recover_causal_commit_error(repository, fence, consistency, error.to_string()).await
+        }
+    }
+}
+
+#[cfg(feature = "graphql")]
+pub(super) async fn load_committed_dispatch_result<R>(
+    repository: &R,
+    fence: &AttemptFence,
+    consistency: CommandConsistency,
+) -> Result<CausalDispatchResult, CausalDispatchError>
+where
+    R: CommandLedgerStore + Send + Sync,
+{
+    match repository
+        .lookup_command(fence.key(), CommandLookupScope::Attempt(fence))
+        .await
+        .map_err(internal_ledger_error)?
+    {
+        CommandLookup::Replay(replay) => replay_result(consistency, replay),
+        CommandLookup::Expired => Err(CausalDispatchError::Expired),
+        CommandLookup::InProgress { .. }
+        | CommandLookup::RetryableUnknown { .. }
+        | CommandLookup::Unknown => Err(CausalDispatchError::Internal(
+            "committed command has no exact durable replay receipt".into(),
+        )),
+    }
+}
+
+#[cfg(feature = "graphql")]
+pub(super) async fn abandon_causal_attempt<R>(
+    repository: &R,
+    attempt: CommandAttempt,
+    consistency: CommandConsistency,
+    detail: String,
+) -> Result<CausalDispatchResult, CausalDispatchError>
+where
+    R: CommandLedgerStore + Send + Sync,
+{
+    let fence = attempt.fence();
+    match repository.mark_retryable_unknown(fence.clone()).await {
+        Ok(()) => Err(CausalDispatchError::Internal(detail)),
+        Err(CommandLedgerError::AttemptFenced { .. }) => {
+            resolve_ambiguous_lookup(repository, fence, consistency, detail).await
+        }
+        Err(error) => Err(CausalDispatchError::Internal(format!(
+            "{detail}; failed to mark command retryable: {error}"
+        ))),
+    }
+}
+
+#[cfg(feature = "graphql")]
+pub(super) async fn recover_causal_commit_error<R>(
+    repository: &R,
+    fence: AttemptFence,
+    consistency: CommandConsistency,
+    detail: String,
+) -> Result<CausalDispatchResult, CausalDispatchError>
+where
+    R: CommandLedgerStore + Send + Sync,
+{
+    resolve_ambiguous_lookup(repository, fence, consistency, detail).await
+}
+
+#[cfg(feature = "graphql")]
+pub(super) async fn resolve_ambiguous_lookup<R>(
+    repository: &R,
+    fence: AttemptFence,
+    consistency: CommandConsistency,
+    detail: String,
+) -> Result<CausalDispatchResult, CausalDispatchError>
+where
+    R: CommandLedgerStore + Send + Sync,
+{
+    match repository
+        .lookup_command(fence.key(), CommandLookupScope::Attempt(&fence))
+        .await
+    {
+        Ok(CommandLookup::Replay(replay)) => replay_result(consistency, replay),
+        Ok(CommandLookup::Expired) => Err(CausalDispatchError::Expired),
+        Ok(CommandLookup::RetryableUnknown { .. }) => Err(CausalDispatchError::Internal(detail)),
+        Ok(CommandLookup::InProgress { .. }) => {
+            match repository.mark_retryable_unknown(fence).await {
+                Ok(()) => Err(CausalDispatchError::Internal(detail)),
+                Err(CommandLedgerError::AttemptFenced { .. }) => {
+                    Err(CausalDispatchError::InProgress)
+                }
+                Err(error) => Err(CausalDispatchError::Internal(format!(
+                    "{detail}; command recovery failed: {error}"
+                ))),
+            }
+        }
+        Ok(CommandLookup::Unknown) => Err(CausalDispatchError::Internal(format!(
+            "{detail}; command ledger row disappeared"
+        ))),
+        Err(error) => Err(CausalDispatchError::Internal(format!(
+            "{detail}; command outcome lookup failed: {error}"
+        ))),
+    }
+}
+
+#[cfg(feature = "graphql")]
+pub(super) async fn evaluate_causal_command_status<R>(
+    repository: &R,
+    command_id: &CommandId,
+    consistency: CommandConsistency,
+    lookup: CommandLookup,
+) -> Result<CausalCommandPublicStatus, CausalDispatchError>
+where
+    R: CommandLedgerStore + ProjectionProtocolStore + Send + Sync,
+{
+    match lookup {
+        CommandLookup::Unknown => Ok(CausalCommandPublicStatus::unknown(command_id.as_str())),
+        CommandLookup::Expired => Ok(CausalCommandPublicStatus {
+            state: CausalCommandPublicState::Expired,
+            command_id: command_id.as_str().to_string(),
+            causation_id: None,
+            consistency: Some(consistency),
+            outcome: None,
+            obligations: Vec::new(),
+            evidence: Vec::new(),
+            direct_projection: None,
+        }),
+        CommandLookup::InProgress { causation_id }
+        | CommandLookup::RetryableUnknown { causation_id } => Ok(CausalCommandPublicStatus {
+            state: CausalCommandPublicState::InProgress,
+            command_id: command_id.as_str().to_string(),
+            causation_id: Some(causation_id.as_str().to_string()),
+            consistency: Some(consistency),
+            outcome: None,
+            obligations: Vec::new(),
+            evidence: Vec::new(),
+            direct_projection: None,
+        }),
+        CommandLookup::Replay(replay) => {
+            let receipt = CausalCommandReceiptSource::from_replay(consistency, replay)?;
+            let (state, evidence) = match receipt.state {
+                CommandLedgerState::Accepted => (CausalCommandPublicState::Accepted, Vec::new()),
+                CommandLedgerState::Projected => (
+                    CausalCommandPublicState::Projected,
+                    receipt
+                        .obligations
+                        .iter()
+                        .enumerate()
+                        .map(|(obligation_index, _)| CausalCommandProjectionEvidence {
+                            obligation_index,
+                            state: CausalProjectionEvidenceState::Observed,
+                            // The durable ledger state proves every finite
+                            // obligation. Exact record positions are optional
+                            // status detail and are not reconstructed from a
+                            // later row head.
+                            incarnation: None,
+                            revision: None,
+                        })
+                        .collect(),
+                ),
+                CommandLedgerState::Rejected => (CausalCommandPublicState::Rejected, Vec::new()),
+                CommandLedgerState::ProjectionFailed => {
+                    (CausalCommandPublicState::ProjectionFailed, Vec::new())
+                }
+                CommandLedgerState::AcceptedPendingProjection => {
+                    evaluate_pending_projection_evidence(repository, &receipt).await?
+                }
+                CommandLedgerState::InProgress
+                | CommandLedgerState::RetryableUnknown
+                | CommandLedgerState::Expired => {
+                    return Err(CausalDispatchError::Internal(format!(
+                        "stored replay has non-terminal state `{}`",
+                        receipt.state.as_str()
+                    )));
+                }
+            };
+            Ok(CausalCommandPublicStatus {
+                state,
+                command_id: receipt.command_id,
+                causation_id: Some(receipt.causation_id),
+                consistency: Some(receipt.consistency),
+                outcome: Some(receipt.outcome),
+                obligations: receipt.obligations,
+                evidence,
+                direct_projection: receipt.direct_projection,
+            })
+        }
+    }
+}
+
+#[cfg(feature = "graphql")]
+pub(super) async fn evaluate_pending_projection_evidence<R>(
+    repository: &R,
+    receipt: &CausalCommandReceiptSource,
+) -> Result<
+    (
+        CausalCommandPublicState,
+        Vec<CausalCommandProjectionEvidence>,
+    ),
+    CausalDispatchError,
+>
+where
+    R: ProjectionProtocolStore + Send + Sync,
+{
+    let requests = receipt
+        .obligations
+        .iter()
+        .map(|obligation| {
+            ProjectionObligationEvidenceRequest::new(
+                receipt.causation_id.clone(),
+                obligation.scope.clone(),
+                obligation.observation_kind,
+            )
+        })
+        .collect::<Result<Vec<_>, _>>()
+        .map_err(|error| {
+            CausalDispatchError::Internal(format!(
+                "stored projection obligation cannot be evaluated: {error}"
+            ))
+        })?;
+    let request = ProjectionObligationEvidenceBatchRequest::new(requests).map_err(|error| {
+        CausalDispatchError::Internal(format!(
+            "stored projection obligation batch is invalid: {error}"
+        ))
+    })?;
+    let batch = repository
+        .projection_obligation_evidence_batch(&request)
+        .await
+        .map_err(|error| {
+            CausalDispatchError::Internal(format!(
+                "projection obligation evidence lookup failed: {error}"
+            ))
+        })?;
+    if batch.evidence.len() != receipt.obligations.len() {
+        return Err(CausalDispatchError::Internal(format!(
+            "projection obligation evidence returned {} items for {} exact probes",
+            batch.evidence.len(),
+            receipt.obligations.len()
+        )));
+    }
+
+    let mut evidence = Vec::with_capacity(batch.evidence.len());
+    for (obligation_index, (obligation, item)) in
+        receipt.obligations.iter().zip(batch.evidence).enumerate()
+    {
+        let item = match item {
+            ProjectionObligationEvidence::Pending => CausalCommandProjectionEvidence {
+                obligation_index,
+                state: CausalProjectionEvidenceState::Pending,
+                incarnation: None,
+                revision: None,
+            },
+            ProjectionObligationEvidence::TerminalFailure(_) => CausalCommandProjectionEvidence {
+                obligation_index,
+                state: CausalProjectionEvidenceState::TerminalFailure,
+                incarnation: None,
+                revision: None,
+            },
+            ProjectionObligationEvidence::Observed(observation) => {
+                if observation.causation_id != receipt.causation_id
+                    || observation.kind != obligation.observation_kind
+                    || observation.scope != obligation.scope
+                {
+                    return Err(CausalDispatchError::Internal(
+                        "projection store returned evidence outside the exact obligation probe"
+                            .into(),
+                    ));
+                }
+                let (incarnation, revision) = match observation.revision.as_ref() {
+                    Some(record)
+                        if obligation.observation_kind == ProjectionObservationKind::Record
+                            && record.scope() == &obligation.scope =>
+                    {
+                        (Some(record.incarnation()), Some(record.revision()))
+                    }
+                    None if obligation.observation_kind
+                        == ProjectionObservationKind::Dependency =>
+                    {
+                        (None, None)
+                    }
+                    _ => {
+                        return Err(CausalDispatchError::Internal(
+                            "projection store returned an invalid revision for the obligation kind"
+                                .into(),
+                        ));
+                    }
+                };
+                CausalCommandProjectionEvidence {
+                    obligation_index,
+                    state: CausalProjectionEvidenceState::Observed,
+                    incarnation,
+                    revision,
+                }
+            }
+        };
+        evidence.push(item);
+    }
+
+    // Failure precedence is intentional: a terminal failure must never be
+    // hidden by observations from the remaining obligations.
+    let state = collapse_projection_evidence(&evidence);
+    Ok((state, evidence))
+}
+
+#[cfg(feature = "graphql")]
+pub(super) fn collapse_projection_evidence(
+    evidence: &[CausalCommandProjectionEvidence],
+) -> CausalCommandPublicState {
+    if evidence
+        .iter()
+        .any(|item| item.state == CausalProjectionEvidenceState::TerminalFailure)
+    {
+        CausalCommandPublicState::ProjectionFailed
+    } else if !evidence.is_empty()
+        && evidence
+            .iter()
+            .all(|item| item.state == CausalProjectionEvidenceState::Observed)
+    {
+        CausalCommandPublicState::Projected
+    } else {
+        CausalCommandPublicState::AcceptedPendingProjection
+    }
+}
diff --git a/src/microsvc/service/defaults.rs b/src/microsvc/service/defaults.rs
new file mode 100644
index 00000000..d4cfbc60
--- /dev/null
+++ b/src/microsvc/service/defaults.rs
@@ -0,0 +1,68 @@
+use super::routes::{configure_outbox_for, Routes};
+use crate::microsvc::dependencies::{
+    ConfigurableOutboxPublisher, HasOutboxStore, HasReadModelStore, HasRepo,
+    RepoReadModelDependencies,
+};
+
+impl Default for Routes<()> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Routes<()> {
+    /// Start building a typed route bundle.
+    pub fn new() -> Self {
+        Self::from_dependencies(())
+    }
+
+    /// Use any custom dependency value for this route bundle.
+    pub fn with_dependencies<D>(self, dependencies: D) -> Routes<D>
+    where
+        D: Send + Sync + 'static,
+    {
+        self.assert_no_registrations("with_dependencies");
+        Routes::from_dependencies(dependencies)
+    }
+
+    /// Use an aggregate repository as the route bundle's dependency.
+    pub fn with_repo<R>(self, repo: R) -> Routes<R>
+    where
+        R: HasRepo + HasOutboxStore + ConfigurableOutboxPublisher + Send + Sync + 'static,
+    {
+        self.assert_no_registrations("with_repo");
+        Routes::from_dependencies(repo).with_outbox_configurator(configure_outbox_for::<R>)
+    }
+
+    /// Use a read-model store as the route bundle's dependency.
+    pub fn with_read_model_store<S>(self, read_model_store: S) -> Routes<S>
+    where
+        S: HasReadModelStore + Send + Sync + 'static,
+    {
+        self.assert_no_registrations("with_read_model_store");
+        Routes::from_dependencies(read_model_store)
+    }
+}
+
+impl<R> Routes<R>
+where
+    R: HasRepo + HasOutboxStore + ConfigurableOutboxPublisher + Send + Sync + 'static,
+{
+    /// Add a read-model store alongside the aggregate repository, so handlers can
+    /// reach both via `ctx.repo()` and `ctx.read_model_store()`. Call after
+    /// `with_repo`.
+    pub fn with_read_model_store<S>(
+        self,
+        read_model_store: S,
+    ) -> Routes<RepoReadModelDependencies<R, S>>
+    where
+        S: HasReadModelStore + Send + Sync + 'static,
+    {
+        self.assert_no_registrations("with_read_model_store");
+        Routes::from_dependencies(RepoReadModelDependencies::new(
+            self.dependencies,
+            read_model_store,
+        ))
+        .with_outbox_configurator(configure_outbox_for::<RepoReadModelDependencies<R, S>>)
+    }
+}
diff --git a/src/microsvc/service/handlers.rs b/src/microsvc/service/handlers.rs
new file mode 100644
index 00000000..44917652
--- /dev/null
+++ b/src/microsvc/service/handlers.rs
@@ -0,0 +1,240 @@
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Arc;
+
+use serde_json::Value;
+
+use crate::aggregate::Aggregate;
+use crate::bus::Message;
+use crate::graphql::command_contract::CommandOutcome;
+use crate::graphql::{GraphqlOutputType, PreparedCommand, Projected};
+use crate::microsvc::causal::{CausalWorkspace, CausalWorkspaceError};
+use crate::microsvc::context::Context;
+use crate::microsvc::error::HandlerError;
+use crate::microsvc::session::Session;
+use crate::outbox::OutboxMessage;
+use crate::read_model::{ReadModelWritePlanBuilder, RelationalReadModel};
+
+pub(super) type GuardFn<D> = dyn Fn(&Context<D>) -> bool + Send + Sync;
+pub(super) type HandlerFuture<'a> =
+    Pin<Box<dyn Future<Output = Result<Value, HandlerError>> + Send + 'a>>;
+pub(super) type ProjectorBootstrapFuture<'a> =
+    Pin<Box<dyn Future<Output = Result<(), HandlerError>> + Send + 'a>>;
+pub(super) type HandlerFn<D> =
+    dyn for<'a> Fn(&'a Context<'a, D>) -> HandlerFuture<'a> + Send + Sync;
+
+/// Lets an `async fn handle(ctx: &Context<D>) -> Result<Value, HandlerError>`
+/// register directly as a handler. The higher-ranked bound ties the returned
+/// future's lifetime to the borrowed [`Context`], which a plain generic future
+/// parameter cannot express.
+pub trait Handler<'a, D: 'a>: Send + Sync {
+    /// The future returned by the handler for a context borrowed for `'a`.
+    type Future: Future<Output = Result<Value, HandlerError>> + Send + 'a;
+    fn call(&self, ctx: &'a Context<'a, D>) -> Self::Future;
+}
+
+/// Restricted metadata and staging context for one typed causal command.
+///
+/// The aggregate type is fixed by the route bundle. The context exposes owned
+/// checkouts and staging operations, but never the dependency value, backend,
+/// repository, or a commit method; the framework retains this route's fenced
+/// durable commit capability and attaches the command-attempt fence after the
+/// handler returns.
+///
+/// This is an API capability boundary, not a Rust sandbox. Application handler
+/// code is trusted: a closure can still capture an external client/repository or
+/// reach a global. Such out-of-band effects are outside the causal contract and
+/// may repeat if an expired attempt is reclaimed. Only work staged through this
+/// context receives the at-most-once committed-effects guarantee.
+pub struct CausalCommandContext<'a, A>
+where
+    A: Aggregate + Send + Sync + 'static,
+{
+    message: &'a Message,
+    session: &'a Session,
+    workspace: &'a CausalWorkspace<'a, A>,
+}
+
+impl<'a, A> CausalCommandContext<'a, A>
+where
+    A: Aggregate + Send + Sync + 'static,
+{
+    #[cfg(feature = "graphql")]
+    pub(super) fn new(
+        message: &'a Message,
+        session: &'a Session,
+        workspace: &'a CausalWorkspace<'a, A>,
+    ) -> Self {
+        Self {
+            message,
+            session,
+            workspace,
+        }
+    }
+
+    pub fn command_name(&self) -> &str {
+        self.message.name()
+    }
+
+    pub fn message_id(&self) -> Option<&str> {
+        self.message.id()
+    }
+
+    pub fn correlation_id(&self) -> Option<&str> {
+        self.message.correlation_id()
+    }
+
+    pub fn causation_id(&self) -> Option<&str> {
+        self.message.causation_id()
+    }
+
+    pub fn trace_context(&self) -> crate::TraceContext {
+        self.message.trace_context()
+    }
+
+    pub fn user_id(&self) -> Result<&str, HandlerError> {
+        self.session
+            .user_id()
+            .ok_or_else(|| HandlerError::Unauthorized("missing user ID in session".into()))
+    }
+
+    pub fn role(&self) -> Option<&str> {
+        self.session.role()
+    }
+
+    pub fn claim(&self, name: &str) -> Option<&str> {
+        self.session.get(name)
+    }
+
+    /// Load one aggregate as an owned checkout without retaining a queue lock.
+    pub async fn load(
+        &self,
+        id: &str,
+    ) -> Result<Option<crate::microsvc::AggregateCheckout<A>>, HandlerError> {
+        self.workspace
+            .load(id)
+            .await
+            .map_err(workspace_handler_error)
+    }
+
+    /// Start a new aggregate checkout. The handler must assign a valid entity
+    /// identity before staging it.
+    pub fn create(&self) -> crate::microsvc::AggregateCheckout<A> {
+        self.workspace.create()
+    }
+
+    /// Stage a checkout for the framework-owned atomic commit.
+    pub fn stage(
+        &self,
+        checkout: crate::microsvc::AggregateCheckout<A>,
+    ) -> Result<(), HandlerError> {
+        self.workspace
+            .stage(checkout)
+            .map_err(workspace_handler_error)
+    }
+
+    /// Stage one durable outbox fact in the command transaction.
+    pub fn stage_outbox(&self, message: OutboxMessage) -> Result<(), HandlerError> {
+        self.workspace
+            .stage_outbox(message)
+            .map_err(workspace_handler_error)
+    }
+
+    /// Stage a validated relational read-model write plan.
+    pub fn stage_read_models(&self, writes: ReadModelWritePlanBuilder) -> Result<(), HandlerError> {
+        self.workspace
+            .stage_read_models(writes)
+            .map_err(workspace_handler_error)
+    }
+
+    /// Stage the exact returned model as a full-row upsert and prepare a sealed
+    /// same-transaction projection result.
+    pub fn projected<M>(&self, model: M) -> Result<PreparedCommand<Projected<M>>, HandlerError>
+    where
+        M: GraphqlOutputType + RelationalReadModel + serde::Serialize + Send + Sync + 'static,
+    {
+        self.workspace
+            .prepare_projected(model)
+            .map_err(workspace_handler_error)
+    }
+}
+
+pub(super) fn workspace_handler_error(error: CausalWorkspaceError) -> HandlerError {
+    HandlerError::Other(Box::new(error))
+}
+
+/// A typed causal command handler. The framework binds the decoded input to
+/// the same `I` used by the GraphQL declaration, and the handler may only
+/// prepare a sealed consistency outcome for the durable committer.
+/// Captured external side effects are unsupported because handler invocation
+/// itself can repeat after lease expiry; see [`CausalCommandContext`].
+pub trait PreparedCommandHandler<'a, A, I, K>: Send + Sync
+where
+    A: Aggregate + Send + Sync + 'static,
+    K: CommandOutcome,
+{
+    type Future: Future<Output = Result<PreparedCommand<K>, HandlerError>> + Send + 'a;
+    fn call(&self, ctx: &'a CausalCommandContext<'a, A>, input: I) -> Self::Future;
+}
+
+impl<'a, D, F, Fut> Handler<'a, D> for F
+where
+    D: 'a,
+    F: Fn(&'a Context<'a, D>) -> Fut + Send + Sync,
+    Fut: Future<Output = Result<Value, HandlerError>> + Send + 'a,
+{
+    type Future = Fut;
+    fn call(&self, ctx: &'a Context<'a, D>) -> Fut {
+        self(ctx)
+    }
+}
+
+impl<'a, A, I, K, F, Fut> PreparedCommandHandler<'a, A, I, K> for F
+where
+    A: Aggregate + Send + Sync + 'static,
+    I: 'a,
+    K: CommandOutcome,
+    F: Fn(&'a CausalCommandContext<'a, A>, I) -> Fut + Send + Sync,
+    Fut: Future<Output = Result<PreparedCommand<K>, HandlerError>> + Send + 'a,
+{
+    type Future = Fut;
+
+    fn call(&self, ctx: &'a CausalCommandContext<'a, A>, input: I) -> Self::Future {
+        self(ctx, input)
+    }
+}
+
+pub(super) fn boxed_handler<D, F>(handler: F) -> Arc<HandlerFn<D>>
+where
+    F: for<'a> Handler<'a, D> + 'static,
+{
+    Arc::new(move |ctx| Box::pin(handler.call(ctx)) as HandlerFuture<'_>)
+}
+
+pub(super) type PreparedHandlerFuture<'a, K> =
+    Pin<Box<dyn Future<Output = Result<PreparedCommand<K>, HandlerError>> + Send + 'a>>;
+pub(super) type PreparedHandlerFn<A, I, K> = dyn for<'a> Fn(&'a CausalCommandContext<'a, A>, I) -> PreparedHandlerFuture<'a, K>
+    + Send
+    + Sync;
+pub(super) type CausalGuardFn<A> =
+    dyn for<'a> Fn(&CausalCommandContext<'a, A>) -> bool + Send + Sync;
+
+pub(super) fn boxed_prepared_handler<A, I, K, F>(handler: F) -> Arc<PreparedHandlerFn<A, I, K>>
+where
+    A: Aggregate + Send + Sync + 'static,
+    I: serde::de::DeserializeOwned + Send + 'static,
+    K: CommandOutcome,
+    F: for<'a> PreparedCommandHandler<'a, A, I, K> + 'static,
+{
+    Arc::new(move |context, input| {
+        Box::pin(handler.call(context, input)) as PreparedHandlerFuture<'_, K>
+    })
+}
+
+pub(super) fn boxed_causal_guard<A, G>(guard: G) -> Arc<CausalGuardFn<A>>
+where
+    A: Aggregate + Send + Sync + 'static,
+    G: for<'a> Fn(&CausalCommandContext<'a, A>) -> bool + Send + Sync + 'static,
+{
+    Arc::new(guard)
+}
diff --git a/src/microsvc/service/helpers.rs b/src/microsvc/service/helpers.rs
new file mode 100644
index 00000000..31ce820d
--- /dev/null
+++ b/src/microsvc/service/helpers.rs
@@ -0,0 +1,62 @@
+use std::collections::HashMap;
+
+use serde_json::Value;
+
+use super::routes::HandlerSpec;
+use crate::bus::{Message, MessageKind};
+use crate::microsvc::error::HandlerError;
+use crate::microsvc::session::Session;
+
+pub(super) fn names_by_kind(specs: &[HandlerSpec], kind: MessageKind) -> Vec<&str> {
+    let mut names = Vec::new();
+
+    for spec in specs.iter().filter(|spec| spec.kind == kind) {
+        for name in spec.names() {
+            if !names.contains(&name) {
+                names.push(name);
+            }
+        }
+    }
+
+    names
+}
+
+/// Whether a content type declares a JSON payload (`application/json` or any
+/// `+json` structured suffix), ignoring parameters like `;charset=utf-8`.
+pub(super) fn is_json_content_type(content_type: &str) -> bool {
+    let essence = content_type
+        .split(';')
+        .next()
+        .unwrap_or(content_type)
+        .trim()
+        .to_ascii_lowercase();
+    essence == "application/json" || essence.ends_with("+json")
+}
+
+#[cfg(feature = "otel")]
+pub(super) fn microsvc_dispatch_span(message: &Message) -> tracing::Span {
+    crate::telemetry::microsvc_dispatch_span(message)
+}
+
+#[cfg(feature = "otel")]
+pub(super) fn microsvc_handler_span(message: &Message) -> tracing::Span {
+    crate::telemetry::microsvc_handler_span(message)
+}
+
+pub(super) fn message_to_json_input(message: &Message) -> Result<Value, HandlerError> {
+    serde_json::from_slice::<Value>(&message.payload).map_err(|e| {
+        HandlerError::DecodeFailed(format!(
+            "invalid JSON payload for message '{}': {}",
+            message.name, e
+        ))
+    })
+}
+
+pub(super) fn message_to_session(message: &Message) -> Session {
+    let vars: HashMap<String, String> = message
+        .metadata
+        .iter()
+        .map(|(key, value)| (key.to_ascii_lowercase(), value.clone()))
+        .collect();
+    Session::from_map(vars)
+}
diff --git a/src/microsvc/service/mod.rs b/src/microsvc/service/mod.rs
new file mode 100644
index 00000000..ddd10273
--- /dev/null
+++ b/src/microsvc/service/mod.rs
@@ -0,0 +1,56 @@
+//! Routes and service dispatch for microsvc.
+//!
+//! `Routes<D>` holds one dependency value and its command/event handlers.
+//! `Service` is the deployment-level router that collects one or more route
+//! bundles. Each handler receives a `Context<D>` and returns
+//! `Result<Value, HandlerError>`.
+//!
+//! ## Example
+//!
+//! The handler closure returns a future, and `dispatch` is awaited:
+//!
+//! ```ignore
+//! use distributed::microsvc;
+//! use serde_json::json;
+//!
+//! let routes = microsvc::Routes::new()
+//!     .with_dependencies(())
+//!     .command("order.create")
+//!     .handle(|ctx| {
+//!         let input = ctx.input::<CreateOrderInput>();
+//!         async move { Ok(json!({ "id": input?.id })) }
+//!     });
+//! let service = microsvc::Service::new().routes(routes);
+//!
+//! let result = service
+//!     .dispatch("order.create", json!({"id": "1"}), Session::new())
+//!     .await?;
+//! ```
+
+mod causal;
+mod defaults;
+mod handlers;
+mod helpers;
+mod request;
+mod routes;
+mod runtime;
+
+#[cfg(feature = "graphql")]
+pub use causal::GraphqlServiceBindError;
+#[cfg(feature = "graphql")]
+pub(crate) use causal::{
+    CausalCommandProjectionObligation, CausalCommandPublicState, CausalCommandPublicStatus,
+    CausalCommandReceiptSource, CausalProjectionEvidenceState,
+};
+#[cfg(all(feature = "graphql", test))]
+pub(crate) use causal::CausalCommandProjectionEvidence;
+pub use handlers::{CausalCommandContext, PreparedCommandHandler};
+pub use request::{CommandRequest, CommandResponse};
+pub(crate) use routes::DynBusPublisher;
+pub use routes::{
+    DeliveryKind, HandlerNames, HandlerSpec, RouteBuilder, Routes, TypedRouteBuilder,
+};
+pub use runtime::Service;
+
+#[cfg(test)]
+mod tests;
diff --git a/src/microsvc/service/request.rs b/src/microsvc/service/request.rs
new file mode 100644
index 00000000..19b17cb6
--- /dev/null
+++ b/src/microsvc/service/request.rs
@@ -0,0 +1,37 @@
+use std::collections::HashMap;
+
+use serde_json::Value;
+
+/// An inbound command request.
+///
+/// Generic command envelope used by in-process dispatch and adapters that
+/// already decoded a gateway payload. Example shape:
+/// ```json
+/// {
+///   "command": "order.create",
+///   "input": { "product_id": "SKU-1" },
+///   "session_variables": { "x-user-id": "user-42" }
+/// }
+/// ```
+///
+/// `session_variables` keys are deployment convention (see [`Session`]). A
+/// query-layer action (Hasura, custom BFF, …) can map its native claims into
+/// these variables before calling `dispatch_request`.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct CommandRequest {
+    /// Command name (URL path, action name, or explicit field).
+    pub command: String,
+    /// JSON input payload.
+    pub input: Value,
+    /// Opaque session variables (identity claims, roles, tenant, etc.).
+    pub session_variables: HashMap<String, String>,
+}
+
+/// Response from dispatching a command.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct CommandResponse {
+    /// HTTP-style status code.
+    pub status: u16,
+    /// Response body (handler result or error).
+    pub body: Value,
+}
diff --git a/src/microsvc/service/routes.rs b/src/microsvc/service/routes.rs
new file mode 100644
index 00000000..8e4577c7
--- /dev/null
+++ b/src/microsvc/service/routes.rs
@@ -0,0 +1,1476 @@
+#[cfg(feature = "graphql")]
+use std::collections::BTreeMap;
+use std::collections::HashMap;
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::time::Duration;
+#[cfg(feature = "graphql")]
+use std::time::SystemTime;
+
+#[cfg(feature = "graphql")]
+use super::causal::{
+    abandon_causal_attempt, causal_handler_error_code, commit_causal_rejection,
+    ensure_causal_grant, evaluate_causal_command_status, internal_ledger_error,
+    load_committed_dispatch_result, recover_causal_commit_error, replay_result,
+    CausalCommandPublicStatus, CausalDispatchError, CausalDispatchResult,
+};
+use super::handlers::{
+    boxed_causal_guard, boxed_handler, boxed_prepared_handler, CausalCommandContext, CausalGuardFn,
+    GuardFn, Handler, HandlerFn, HandlerFuture, PreparedCommandHandler, PreparedHandlerFn,
+    ProjectorBootstrapFuture,
+};
+use crate::aggregate::Aggregate;
+use crate::bus::{Bus, Message, MessageKind, MessagePublisher, OrderedDelivery, TransportError};
+#[cfg(feature = "graphql")]
+use crate::command_ledger::{
+    CanonicalInputHash, CausalCommitBatch, CausalRepositoryIdentity, CausalTransactionalCommit,
+    CommandContractFingerprint, CommandId, CommandLedgerKey, CommandLedgerStore, CommandLookup,
+    CommandLookupScope, CommandReservation, PrincipalPartitionId, ReservationOutcome,
+    TerminalCommandState,
+};
+#[cfg(feature = "graphql")]
+use crate::graphql::command_contract::CommandConsistency;
+use crate::graphql::command_contract::{CommandOutcome, TypedCommandContract};
+#[cfg(feature = "graphql")]
+use crate::graphql::command_input::canonicalize_command_input;
+#[cfg(feature = "graphql")]
+use crate::graphql::identity::VerifiedPrincipal;
+use crate::graphql::{SurfaceProjector, TypedCommand};
+#[cfg(feature = "graphql")]
+use crate::microsvc::causal::CausalWorkspace;
+use crate::microsvc::context::Context;
+use crate::microsvc::dependencies::{
+    CausalProjectionRouteDependencies, CausalRouteDependencies, ConfigurableOutboxPublisher,
+    HasOutboxStore, HasReadModelStore, HasRepo,
+};
+use crate::microsvc::error::HandlerError;
+use crate::microsvc::projector::{
+    CausalProjectorRouteBuilder, ErasedProjectorHandler, ProjectionRepairHandle,
+    ProjectorRegistration, ProjectorRepairFuture, ProjectorRepairLookupFuture,
+};
+use crate::microsvc::session::Session;
+use crate::outbox::OutboxPublisherConfig;
+use crate::outbox_worker::BusOutboxPublishHook;
+#[cfg(feature = "graphql")]
+use crate::projection_protocol::ProjectionProtocolStore;
+use serde_json::Value;
+
+/// How a handler expects the transport to deliver matching messages.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DeliveryKind {
+    /// Point-to-point delivery, normally used for command queues.
+    PointToPoint,
+    /// Fan-out delivery, normally used for event subscriptions.
+    FanOut,
+}
+
+/// Static message names attached to a handler spec.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum HandlerNames {
+    /// A single command or event name.
+    One(&'static str),
+    /// Multiple event names handled by one projection-style handler.
+    Many(&'static [&'static str]),
+    /// Compiler-owned event names retained by a causal projector declaration.
+    Owned(Vec<String>),
+}
+
+impl HandlerNames {
+    fn to_vec(&self) -> Vec<&str> {
+        match self {
+            Self::One(name) => vec![*name],
+            Self::Many(names) => names.to_vec(),
+            Self::Owned(names) => names.iter().map(String::as_str).collect(),
+        }
+    }
+}
+
+/// Transport-visible metadata for a registered handler.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct HandlerSpec {
+    names: HandlerNames,
+    pub kind: MessageKind,
+    pub delivery: DeliveryKind,
+}
+
+impl HandlerSpec {
+    /// A command handler that consumes JSON payloads.
+    pub const fn command(name: &'static str) -> Self {
+        Self {
+            names: HandlerNames::One(name),
+            kind: MessageKind::Command,
+            delivery: DeliveryKind::PointToPoint,
+        }
+    }
+
+    /// An event handler that consumes JSON payloads.
+    pub const fn event(name: &'static str) -> Self {
+        Self {
+            names: HandlerNames::One(name),
+            kind: MessageKind::Event,
+            delivery: DeliveryKind::FanOut,
+        }
+    }
+
+    /// An event handler that consumes several event names.
+    pub const fn events(names: &'static [&'static str]) -> Self {
+        Self {
+            names: HandlerNames::Many(names),
+            kind: MessageKind::Event,
+            delivery: DeliveryKind::FanOut,
+        }
+    }
+
+    pub(crate) fn projector(names: Vec<String>) -> Self {
+        Self {
+            names: HandlerNames::Owned(names),
+            kind: MessageKind::Event,
+            delivery: DeliveryKind::FanOut,
+        }
+    }
+
+    /// Message names consumed by this handler.
+    pub fn names(&self) -> Vec<&str> {
+        self.names.to_vec()
+    }
+}
+
+enum RegisteredHandler<D> {
+    Legacy {
+        guard: Option<Arc<GuardFn<D>>>,
+        handle: Arc<HandlerFn<D>>,
+    },
+    Causal(Box<dyn ErasedCausalHandler<D>>),
+    Projector(Vec<Arc<dyn ErasedProjectorHandler<D>>>),
+}
+
+#[derive(Clone, Copy)]
+#[cfg_attr(not(feature = "graphql"), allow(dead_code))]
+pub(super) struct CausalCommandPolicy {
+    pub(super) attempt_lease: Duration,
+    pub(super) replay_retention: Duration,
+}
+
+impl Default for CausalCommandPolicy {
+    fn default() -> Self {
+        Self {
+            attempt_lease: Duration::from_secs(30),
+            replay_retention: Duration::from_secs(30 * 24 * 60 * 60),
+        }
+    }
+}
+#[cfg(feature = "graphql")]
+pub(super) type CausalHandlerFuture<'a> =
+    Pin<Box<dyn Future<Output = Result<CausalDispatchResult, CausalDispatchError>> + Send + 'a>>;
+#[cfg(feature = "graphql")]
+pub(super) type CausalStatusFuture<'a> = Pin<
+    Box<dyn Future<Output = Result<CausalCommandPublicStatus, CausalDispatchError>> + Send + 'a>,
+>;
+
+pub(super) trait ErasedCausalHandler<D>: Send + Sync {
+    fn contract(&self) -> &TypedCommandContract;
+
+    #[cfg(feature = "graphql")]
+    fn contract_mut(&mut self) -> &mut TypedCommandContract;
+
+    #[cfg(feature = "graphql")]
+    fn storage_identity(&self, dependencies: &D) -> crate::command_ledger::CausalStorageIdentity;
+
+    #[cfg(feature = "graphql")]
+    #[allow(clippy::too_many_arguments)]
+    fn dispatch<'a>(
+        &'a self,
+        dependencies: &'a D,
+        service_id: &'a str,
+        command_id: &'a str,
+        input: Value,
+        session: Session,
+        principal: VerifiedPrincipal,
+        policy: CausalCommandPolicy,
+    ) -> CausalHandlerFuture<'a>;
+
+    #[cfg(feature = "graphql")]
+    #[allow(dead_code)]
+    fn lookup<'a>(
+        &'a self,
+        dependencies: &'a D,
+        service_id: &'a str,
+        command_id: &'a str,
+        session: &'a Session,
+        principal: VerifiedPrincipal,
+    ) -> Pin<Box<dyn Future<Output = Result<CommandLookup, CausalDispatchError>> + Send + 'a>>;
+
+    #[cfg(feature = "graphql")]
+    fn status<'a>(
+        &'a self,
+        dependencies: &'a D,
+        service_id: &'a str,
+        command_id: &'a CommandId,
+        principal_partition: &'a PrincipalPartitionId,
+        session: &'a Session,
+    ) -> CausalStatusFuture<'a>;
+}
+
+struct RegisteredCausalHandler<A, I, K>
+where
+    A: Aggregate + Send + Sync + 'static,
+    K: CommandOutcome,
+{
+    contract: TypedCommandContract,
+    #[cfg_attr(not(feature = "graphql"), allow(dead_code))]
+    guard: Option<Arc<CausalGuardFn<A>>>,
+    #[cfg_attr(not(feature = "graphql"), allow(dead_code))]
+    handle: Arc<PreparedHandlerFn<A, I, K>>,
+    /// Retryable, fail-closed bootstrap for the bound projector's complete
+    /// model/table ownership inventory. `get_or_try_init` leaves the cell empty
+    /// after a transient registration failure.
+    #[cfg(feature = "graphql")]
+    direct_projection_bootstrap: tokio::sync::OnceCell<()>,
+    _types: std::marker::PhantomData<fn(A, I) -> K>,
+}
+
+impl<A, I, K> RegisteredCausalHandler<A, I, K>
+where
+    A: Aggregate + Send + Sync + 'static,
+    K: CommandOutcome,
+{
+    fn new(
+        contract: TypedCommandContract,
+        guard: Option<Arc<CausalGuardFn<A>>>,
+        handle: Arc<PreparedHandlerFn<A, I, K>>,
+    ) -> Self {
+        Self {
+            contract,
+            guard,
+            handle,
+            #[cfg(feature = "graphql")]
+            direct_projection_bootstrap: tokio::sync::OnceCell::new(),
+            _types: std::marker::PhantomData,
+        }
+    }
+}
+
+pub(super) type OutboxConfigurator<D> =
+    fn(&mut D, DynBusPublisher, String, Duration, u32, Option<String>);
+
+pub(super) trait ErasedRoutes: Send + Sync {
+    fn handler_specs(&self) -> &[HandlerSpec];
+
+    fn typed_command_contracts(&self) -> Vec<&TypedCommandContract>;
+
+    fn projector_registrations(&self) -> Vec<ProjectorRegistration>;
+
+    fn bootstrap_projectors(&self) -> ProjectorBootstrapFuture<'_>;
+
+    fn is_causal_projector(&self, message: &Message) -> bool;
+
+    fn is_projector_route(&self, kind: MessageKind, name: &str) -> bool;
+
+    fn repair_projection<'a>(
+        &'a self,
+        handle: &'a ProjectionRepairHandle,
+    ) -> ProjectorRepairFuture<'a>;
+
+    fn locates_projection_failure<'a>(
+        &'a self,
+        handle: &'a ProjectionRepairHandle,
+    ) -> ProjectorRepairLookupFuture<'a>;
+
+    #[cfg(feature = "graphql")]
+    fn bind_typed_command_contracts(
+        &mut self,
+        contracts: &BTreeMap<String, TypedCommandContract>,
+    ) -> Result<(), String>;
+
+    fn dispatch<'a>(
+        &'a self,
+        message: &'a Message,
+        input: Value,
+        session: Session,
+        ordered: Option<&'a OrderedDelivery>,
+    ) -> HandlerFuture<'a>;
+
+    #[cfg(feature = "graphql")]
+    #[allow(clippy::too_many_arguments)]
+    fn dispatch_causal<'a>(
+        &'a self,
+        command: &'a str,
+        service_id: &'a str,
+        command_id: &'a str,
+        input: Value,
+        session: Session,
+        principal: VerifiedPrincipal,
+        policy: CausalCommandPolicy,
+    ) -> CausalHandlerFuture<'a>;
+
+    #[cfg(feature = "graphql")]
+    #[allow(dead_code)]
+    fn lookup_causal<'a>(
+        &'a self,
+        command: &'a str,
+        service_id: &'a str,
+        command_id: &'a str,
+        session: &'a Session,
+        principal: VerifiedPrincipal,
+    ) -> Pin<Box<dyn Future<Output = Result<CommandLookup, CausalDispatchError>> + Send + 'a>>;
+
+    #[cfg(feature = "graphql")]
+    fn causal_command_status<'a>(
+        &'a self,
+        service_id: &'a str,
+        command_id: &'a CommandId,
+        principal_partition: &'a PrincipalPartitionId,
+        session: &'a Session,
+    ) -> CausalStatusFuture<'a>;
+
+    #[cfg(feature = "graphql")]
+    fn projected_storage_identities(&self) -> Vec<crate::command_ledger::CausalStorageIdentity>;
+
+    fn configure_outbox_publisher(
+        &mut self,
+        publisher: DynBusPublisher,
+        worker_id: String,
+        lease: Duration,
+        max_attempts: u32,
+        service_name: Option<String>,
+    );
+}
+
+trait DynPublish: Send + Sync {
+    fn publish<'a>(
+        &'a self,
+        message: Message,
+    ) -> Pin<Box<dyn Future<Output = Result<(), TransportError>> + Send + 'a>>;
+}
+
+struct BusDynPublisher<B> {
+    bus: Arc<B>,
+}
+
+impl<B: Bus> DynPublish for BusDynPublisher<B> {
+    fn publish<'a>(
+        &'a self,
+        message: Message,
+    ) -> Pin<Box<dyn Future<Output = Result<(), TransportError>> + Send + 'a>> {
+        Box::pin(async move {
+            match message.kind {
+                MessageKind::Command => self.bus.send_message(message).await,
+                MessageKind::Event => self.bus.publish_message(message).await,
+            }
+        })
+    }
+}
+
+#[derive(Clone)]
+pub(crate) struct DynBusPublisher {
+    inner: Arc<dyn DynPublish>,
+}
+
+impl DynBusPublisher {
+    pub(crate) fn new<B>(bus: Arc<B>) -> Self
+    where
+        B: Bus + 'static,
+    {
+        Self {
+            inner: Arc::new(BusDynPublisher { bus }),
+        }
+    }
+}
+
+impl MessagePublisher for DynBusPublisher {
+    fn publish(
+        &self,
+        message: Message,
+    ) -> impl Future<Output = Result<(), TransportError>> + Send + '_ {
+        self.inner.publish(message)
+    }
+}
+
+pub(super) fn configure_outbox_for<D>(
+    dependencies: &mut D,
+    publisher: DynBusPublisher,
+    worker_id: String,
+    lease: Duration,
+    max_attempts: u32,
+    service_name: Option<String>,
+) where
+    D: HasOutboxStore + ConfigurableOutboxPublisher,
+    D::OutboxStore: 'static,
+{
+    let hook = BusOutboxPublishHook::new(dependencies.outbox_store(), publisher, max_attempts)
+        .with_service(service_name);
+    dependencies.configure_outbox_publisher(OutboxPublisherConfig::new(
+        Arc::new(hook),
+        worker_id,
+        lease,
+    ));
+}
+
+/// Builder returned by [`Routes::command`], [`Routes::event`],
+/// [`Routes::events`], and [`Routes::handler`].
+pub struct RouteBuilder<D> {
+    routes: Routes<D>,
+    spec: HandlerSpec,
+}
+
+/// Builder returned by [`Routes::typed_command`].
+///
+/// Unlike a legacy JSON route, the declaration and executable handler share
+/// one route object, the same input and committed-outcome types, and the route
+/// bundle's single aggregate repository.
+pub struct TypedRouteBuilder<D, I, K: CommandOutcome> {
+    routes: Routes<D>,
+    route_name: &'static str,
+    contract: TypedCommandContract,
+    _types: std::marker::PhantomData<fn(I) -> K>,
+}
+
+impl<D: Send + Sync + 'static> RouteBuilder<D> {
+    /// Register an async handler without a guard.
+    pub fn handle<F>(self, handler: F) -> Routes<D>
+    where
+        F: for<'a> Handler<'a, D> + 'static,
+    {
+        self.routes
+            .register_handler(self.spec, None, boxed_handler(handler))
+    }
+
+    /// Register an async handler with a (synchronous) guard.
+    pub fn guarded<G, F>(self, guard: G, handler: F) -> Routes<D>
+    where
+        G: Fn(&Context<D>) -> bool + Send + Sync + 'static,
+        F: for<'a> Handler<'a, D> + 'static,
+    {
+        self.routes
+            .register_handler(self.spec, Some(Arc::new(guard)), boxed_handler(handler))
+    }
+}
+
+impl<D, I, K> TypedRouteBuilder<D, I, K>
+where
+    D: CausalRouteDependencies + Send + Sync + 'static,
+    D::Aggregate: Aggregate + Send + Sync + 'static,
+    I: serde::de::DeserializeOwned + Send + 'static,
+    K: CommandOutcome,
+{
+    /// Register a typed causal command handler without a guard.
+    pub fn handle<F>(self, handler: F) -> Routes<D>
+    where
+        F: for<'a> PreparedCommandHandler<'a, D::Aggregate, I, K> + 'static,
+    {
+        self.routes.register_typed_handler(
+            self.route_name,
+            self.contract,
+            None,
+            boxed_prepared_handler(handler),
+        )
+    }
+
+    /// Register a typed causal command handler with a synchronous guard.
+    pub fn guarded<G, F>(self, guard: G, handler: F) -> Routes<D>
+    where
+        G: for<'a> Fn(&CausalCommandContext<'a, D::Aggregate>) -> bool + Send + Sync + 'static,
+        F: for<'a> PreparedCommandHandler<'a, D::Aggregate, I, K> + 'static,
+    {
+        let guard = boxed_causal_guard(guard);
+        self.routes.register_typed_handler(
+            self.route_name,
+            self.contract,
+            Some(guard),
+            boxed_prepared_handler(handler),
+        )
+    }
+}
+
+/// A typed bundle of command/event handlers and the dependency value they use.
+///
+/// Handlers are keyed by kind, then name, so dispatch looks up by `&str`
+/// without allocating a key.
+pub struct Routes<D> {
+    pub(super) dependencies: D,
+    handlers: HashMap<MessageKind, HashMap<String, RegisteredHandler<D>>>,
+    handler_specs: Vec<HandlerSpec>,
+    projectors: Vec<Arc<dyn ErasedProjectorHandler<D>>>,
+    outbox_configurator: Option<OutboxConfigurator<D>>,
+}
+
+impl<D: Send + Sync + 'static> Routes<D> {
+    /// Build routes around an already-assembled dependency value.
+    pub(crate) fn from_dependencies(dependencies: D) -> Self {
+        Self {
+            dependencies,
+            handlers: HashMap::new(),
+            handler_specs: Vec::new(),
+            projectors: Vec::new(),
+            outbox_configurator: None,
+        }
+    }
+
+    pub(super) fn with_outbox_configurator(mut self, configurator: OutboxConfigurator<D>) -> Self {
+        self.outbox_configurator = Some(configurator);
+        self
+    }
+
+    /// Fail fast if handlers are already registered. Dependency builders
+    /// reconstruct the route bundle around a new dependency type, which would
+    /// otherwise silently drop previously registered handlers.
+    pub(super) fn assert_no_registrations(&self, builder: &str) {
+        assert!(
+            self.handlers.is_empty() && self.handler_specs.is_empty() && self.projectors.is_empty(),
+            "Routes::{builder} must be called before registering handlers"
+        );
+    }
+
+    /// Get a reference to the route dependencies.
+    pub fn dependencies(&self) -> &D {
+        &self.dependencies
+    }
+
+    /// Get the aggregate repository for routes whose dependencies expose one.
+    pub fn repo(&self) -> &D::Repo
+    where
+        D: HasRepo,
+    {
+        self.dependencies.repo()
+    }
+
+    /// Get the read-model store for routes whose dependencies expose one.
+    pub fn read_model_store(&self) -> &D::ReadModelStore
+    where
+        D: HasReadModelStore,
+    {
+        self.dependencies.read_model_store()
+    }
+
+    /// Start registering a command handler that consumes JSON payload input.
+    pub fn command(self, name: &'static str) -> RouteBuilder<D> {
+        self.handler(HandlerSpec::command(name))
+    }
+
+    /// Register a typed command declaration and its executable handler as one
+    /// inventory entry.
+    pub fn typed_command<I, K>(self, command: TypedCommand<I, K>) -> TypedRouteBuilder<D, I, K>
+    where
+        I: serde::de::DeserializeOwned + Send + 'static,
+        K: CommandOutcome,
+    {
+        let (route_name, contract) = command.into_parts();
+        TypedRouteBuilder {
+            routes: self,
+            route_name,
+            contract,
+            _types: std::marker::PhantomData,
+        }
+    }
+
+    /// Register one typed, ordered causal projector using the exact
+    /// [`SurfaceProjector`] declaration also supplied to the GraphQL engine.
+    pub fn causal_projector<I>(
+        self,
+        projector: SurfaceProjector,
+    ) -> CausalProjectorRouteBuilder<D, I>
+    where
+        D: CausalProjectionRouteDependencies,
+        I: serde::de::DeserializeOwned + Send + 'static,
+    {
+        CausalProjectorRouteBuilder::new(self, projector)
+    }
+
+    /// Start registering an event handler that consumes JSON payload input.
+    pub fn event(self, name: &'static str) -> RouteBuilder<D> {
+        self.handler(HandlerSpec::event(name))
+    }
+
+    /// Start registering an event handler for several event names that consume JSON
+    /// payload input.
+    pub fn events(self, names: &'static [&'static str]) -> RouteBuilder<D> {
+        self.handler(HandlerSpec::events(names))
+    }
+
+    /// Start registering a handler from a transport-visible spec.
+    pub fn handler(self, spec: HandlerSpec) -> RouteBuilder<D> {
+        RouteBuilder { routes: self, spec }
+    }
+
+    fn register_handler(
+        mut self,
+        spec: HandlerSpec,
+        guard: Option<Arc<GuardFn<D>>>,
+        handle: Arc<HandlerFn<D>>,
+    ) -> Self {
+        let by_name = self.handlers.entry(spec.kind).or_default();
+        let names = spec.names();
+        for (position, name) in names.iter().enumerate() {
+            assert!(
+                !by_name.contains_key(*name) && !names[..position].contains(name),
+                "duplicate route registration for {:?} `{}`",
+                spec.kind,
+                name
+            );
+        }
+
+        for name in names {
+            by_name.insert(
+                name.to_string(),
+                RegisteredHandler::Legacy {
+                    guard: guard.clone(),
+                    handle: handle.clone(),
+                },
+            );
+        }
+        self.handler_specs.push(spec);
+        self
+    }
+
+    fn register_typed_handler<I, K>(
+        mut self,
+        route_name: &'static str,
+        contract: TypedCommandContract,
+        guard: Option<Arc<CausalGuardFn<D::Aggregate>>>,
+        handle: Arc<PreparedHandlerFn<D::Aggregate, I, K>>,
+    ) -> Self
+    where
+        D: CausalRouteDependencies,
+        D::Aggregate: Aggregate + Send + Sync + 'static,
+        I: serde::de::DeserializeOwned + Send + 'static,
+        K: CommandOutcome,
+    {
+        assert_eq!(
+            route_name, contract.name,
+            "typed command route and contract ids must match"
+        );
+        let by_name = self.handlers.entry(MessageKind::Command).or_default();
+        assert!(
+            !by_name.contains_key(route_name),
+            "duplicate route registration for {:?} `{}`",
+            MessageKind::Command,
+            route_name,
+        );
+        by_name.insert(
+            route_name.to_string(),
+            RegisteredHandler::Causal(Box::new(
+                RegisteredCausalHandler::<D::Aggregate, I, K>::new(contract, guard, handle),
+            )),
+        );
+        self.handler_specs.push(HandlerSpec::command(route_name));
+        self
+    }
+
+    pub(in crate::microsvc) fn register_projector(
+        mut self,
+        spec: HandlerSpec,
+        handler: Box<dyn ErasedProjectorHandler<D>>,
+    ) -> Self {
+        let by_name = self.handlers.entry(MessageKind::Event).or_default();
+        let names = spec.names();
+        for (position, name) in names.iter().enumerate() {
+            assert!(
+                !names[..position].contains(name),
+                "causal projector repeats {:?} route `{}`",
+                MessageKind::Event,
+                name
+            );
+        }
+        let handler: Arc<dyn ErasedProjectorHandler<D>> = Arc::from(handler);
+        for name in names {
+            match by_name.get_mut(name) {
+                Some(RegisteredHandler::Projector(projectors)) => {
+                    projectors.push(Arc::clone(&handler));
+                    projectors.sort_by(|left, right| {
+                        let left = left.registration().topology;
+                        let right = right.registration().topology;
+                        left.name()
+                            .cmp(right.name())
+                            .then_with(|| left.digest().cmp(&right.digest()))
+                    });
+                }
+                Some(RegisteredHandler::Legacy { .. } | RegisteredHandler::Causal(_)) => {
+                    panic!(
+                        "causal projector route {:?} `{name}` collides with a non-projector handler",
+                        MessageKind::Event
+                    );
+                }
+                None => {
+                    by_name.insert(
+                        name.to_string(),
+                        RegisteredHandler::Projector(vec![Arc::clone(&handler)]),
+                    );
+                }
+            }
+        }
+        self.projectors.push(handler);
+        self.handler_specs.push(spec);
+        self
+    }
+
+    pub(super) fn typed_contracts(&self) -> Vec<&TypedCommandContract> {
+        self.handlers
+            .values()
+            .flat_map(HashMap::values)
+            .filter_map(|handler| match handler {
+                RegisteredHandler::Causal(handler) => Some(handler.contract()),
+                RegisteredHandler::Legacy { .. } | RegisteredHandler::Projector(_) => None,
+            })
+            .collect()
+    }
+
+    pub(super) fn registered_keys(&self) -> Vec<(MessageKind, String)> {
+        self.handlers
+            .iter()
+            .flat_map(|(kind, by_name)| by_name.keys().map(move |name| (*kind, name.clone())))
+            .collect()
+    }
+
+    async fn invoke(
+        &self,
+        message: &Message,
+        input: Value,
+        session: Session,
+        ordered: Option<&OrderedDelivery>,
+    ) -> Result<Value, HandlerError> {
+        // Clone the handler/guard Arcs so the handler map is not borrowed across
+        // the (awaited) handler future.
+        let (guard, handle) = {
+            let handler = self
+                .handlers
+                .get(&message.kind)
+                .and_then(|by_name| by_name.get(message.name.as_str()))
+                .ok_or_else(|| HandlerError::UnknownCommand(message.name.clone()))?;
+            match handler {
+                RegisteredHandler::Legacy { guard, handle } => (guard.clone(), handle.clone()),
+                RegisteredHandler::Causal(_) => {
+                    return Err(HandlerError::Unauthorized(
+                        "typed causal commands require a verified GraphQL bearer envelope".into(),
+                    ));
+                }
+                RegisteredHandler::Projector(projectors) => {
+                    for projector in projectors {
+                        if let Err(error) = projector
+                            .dispatch(&self.dependencies, message, ordered)
+                            .await
+                        {
+                            if error.is_projection_retryable()
+                                || matches!(
+                                    error,
+                                    HandlerError::ProjectionTerminalRecorded { .. }
+                                        | HandlerError::ProjectionDeliveryHalted { .. }
+                                )
+                            {
+                                return Err(error);
+                            }
+                            // Causal-projector delivery is stricter than the
+                            // service's ordinary permanent-failure policy. If a
+                            // permanent error was not converted to a durable
+                            // terminal record, dead-lettering or acknowledging
+                            // it would let later input cross an unproven gap.
+                            return Err(HandlerError::ProjectionDeliveryHalted {
+                                source: Box::new(error),
+                            });
+                        }
+                    }
+                    return Ok(Value::Null);
+                }
+            }
+        };
+        let ctx = Context::new(message, input, session, &self.dependencies);
+
+        // Run guard (synchronous) if present.
+        if let Some(guard) = &guard {
+            if !guard(&ctx) {
+                return Err(HandlerError::GuardRejected(message.name.clone()));
+            }
+        }
+
+        handle(&ctx).await
+    }
+}
+
+impl<D, A, I, K> ErasedCausalHandler<D> for RegisteredCausalHandler<A, I, K>
+where
+    D: CausalRouteDependencies<Aggregate = A> + Send + Sync + 'static,
+    A: Aggregate + Send + Sync + 'static,
+    I: serde::de::DeserializeOwned + Send + 'static,
+    K: CommandOutcome,
+{
+    fn contract(&self) -> &TypedCommandContract {
+        &self.contract
+    }
+
+    #[cfg(feature = "graphql")]
+    fn contract_mut(&mut self) -> &mut TypedCommandContract {
+        &mut self.contract
+    }
+
+    #[cfg(feature = "graphql")]
+    fn storage_identity(&self, dependencies: &D) -> crate::command_ledger::CausalStorageIdentity {
+        dependencies
+            .__causal_aggregate_repository()
+            .repo()
+            .causal_storage_identity()
+    }
+
+    #[cfg(feature = "graphql")]
+    fn dispatch<'a>(
+        &'a self,
+        dependencies: &'a D,
+        service_id: &'a str,
+        command_id: &'a str,
+        input: Value,
+        session: Session,
+        principal: VerifiedPrincipal,
+        policy: CausalCommandPolicy,
+    ) -> CausalHandlerFuture<'a> {
+        Box::pin(async move {
+            ensure_causal_grant(&self.contract, &session)?;
+
+            let canonical = canonicalize_command_input(&self.contract.input, input)
+                .map_err(|error| CausalDispatchError::BadRequest(error.to_string()))?;
+            let typed = canonical
+                .decode::<I>()
+                .map_err(|error| CausalDispatchError::BadRequest(error.to_string()))?;
+            let (input, wire, input_digest) = typed.into_parts();
+            let projection_obligations = self
+                .contract
+                .resolve_projection_obligations_from_session(&wire, Some(&session))
+                .map_err(|error| CausalDispatchError::Internal(error.to_string()))?;
+            let direct_projection_target = self
+                .contract
+                .resolve_direct_projection_target_from_session(&wire, Some(&session))
+                .map_err(|error| CausalDispatchError::Internal(error.to_string()))?;
+
+            let command_id = CommandId::parse(command_id)
+                .map_err(|error| CausalDispatchError::BadRequest(error.to_string()))?;
+            let partition = PrincipalPartitionId::new(principal.partition_for_service(service_id))
+                .map_err(internal_ledger_error)?;
+            let key = CommandLedgerKey::new(service_id, partition, command_id)
+                .map_err(internal_ledger_error)?;
+            let reservation = CommandReservation::new(
+                key,
+                self.contract.name.clone(),
+                CommandContractFingerprint::new(self.contract.fingerprint_bytes()),
+                CanonicalInputHash::new(input_digest),
+                policy.attempt_lease,
+                policy.replay_retention,
+            )
+            .map_err(internal_ledger_error)?;
+
+            let aggregate_repository = dependencies.__causal_aggregate_repository();
+            let repository = aggregate_repository.repo();
+            if let Some(target) = direct_projection_target.as_ref() {
+                let (topology, ownership) = target.registration();
+                self.direct_projection_bootstrap
+                    .get_or_try_init(|| async {
+                        repository
+                            .register_projection_models(topology, ownership)
+                            .await
+                            .map_err(|error| {
+                                CausalDispatchError::Internal(format!(
+                                    "direct projection ownership bootstrap failed: {error}"
+                                ))
+                            })
+                    })
+                    .await?;
+            }
+            let attempt = match repository
+                .reserve_command(reservation)
+                .await
+                .map_err(internal_ledger_error)?
+            {
+                ReservationOutcome::Acquired(attempt) => attempt,
+                ReservationOutcome::InProgress { .. } => {
+                    return Err(CausalDispatchError::InProgress)
+                }
+                ReservationOutcome::Replay(replay) => {
+                    return replay_result(self.contract.consistency, replay)
+                }
+                ReservationOutcome::Conflict => return Err(CausalDispatchError::CommandIdReuse),
+                ReservationOutcome::Expired => return Err(CausalDispatchError::Expired),
+            };
+
+            let payload = serde_json::to_vec(&wire).map_err(|error| {
+                CausalDispatchError::Internal(format!(
+                    "canonical command input could not be encoded: {error}"
+                ))
+            })?;
+            let mut metadata = session
+                .variables()
+                .iter()
+                .filter(|(name, _)| !name.eq_ignore_ascii_case(crate::trace_context::CAUSATION_ID))
+                .map(|(name, value)| (name.clone(), value.clone()))
+                .collect::<Vec<_>>();
+            metadata.push((
+                crate::trace_context::CAUSATION_ID.to_string(),
+                attempt.causation_id().as_str().to_string(),
+            ));
+            let message = Message {
+                id: Some(attempt.key().command_id().to_string()),
+                name: self.contract.name.clone(),
+                kind: MessageKind::Command,
+                payload,
+                content_type: "application/json".into(),
+                metadata,
+            };
+
+            let workspace = CausalWorkspace::new(aggregate_repository);
+            let context = CausalCommandContext::new(&message, &session, &workspace);
+            if self.guard.as_ref().is_some_and(|guard| !guard(&context)) {
+                return commit_causal_rejection(
+                    repository,
+                    attempt,
+                    self.contract.consistency,
+                    policy.replay_retention,
+                    "REJECTED",
+                    422,
+                    format!("guard rejected command: {}", self.contract.name),
+                )
+                .await;
+            }
+
+            let prepared = match (self.handle)(&context, input).await {
+                Ok(prepared) => prepared,
+                Err(error) if error.status_code() < 500 => {
+                    let code = causal_handler_error_code(&error);
+                    let status = error.status_code();
+                    let message = error.client_facing_message();
+                    return commit_causal_rejection(
+                        repository,
+                        attempt,
+                        self.contract.consistency,
+                        policy.replay_retention,
+                        code,
+                        status,
+                        message,
+                    )
+                    .await;
+                }
+                Err(error) => {
+                    return abandon_causal_attempt(
+                        repository,
+                        attempt,
+                        self.contract.consistency,
+                        error.to_string(),
+                    )
+                    .await;
+                }
+            };
+
+            let mut parts = match workspace.into_parts() {
+                Ok(parts) => parts,
+                Err(error) => {
+                    return abandon_causal_attempt(
+                        repository,
+                        attempt,
+                        self.contract.consistency,
+                        error.to_string(),
+                    )
+                    .await
+                }
+            };
+            if let Err(error) = parts.validate_prepared(&self.contract, &prepared) {
+                return abandon_causal_attempt(
+                    repository,
+                    attempt,
+                    self.contract.consistency,
+                    error.to_string(),
+                )
+                .await;
+            }
+            let direct_projection = match parts.seal_direct_projection(
+                &prepared,
+                direct_projection_target,
+                attempt.causation_id().as_str(),
+            ) {
+                Ok(direct_projection) => direct_projection,
+                Err(error) => {
+                    return abandon_causal_attempt(
+                        repository,
+                        attempt,
+                        self.contract.consistency,
+                        error.to_string(),
+                    )
+                    .await
+                }
+            };
+
+            let terminal_state = match self.contract.consistency {
+                CommandConsistency::Accepted if self.contract.confirmations.is_empty() => {
+                    TerminalCommandState::Accepted
+                }
+                CommandConsistency::Accepted | CommandConsistency::Fact => {
+                    TerminalCommandState::AcceptedPendingProjection
+                }
+                CommandConsistency::Projected => TerminalCommandState::Projected,
+            };
+            let replay_payload = prepared.serialized_payload().clone();
+            let publisher = aggregate_repository.outbox_publisher();
+            let mut batch = match parts.prepare_commit_batch() {
+                Ok(batch) => batch,
+                Err(error) => {
+                    return abandon_causal_attempt(
+                        repository,
+                        attempt,
+                        self.contract.consistency,
+                        format!("causal commit batch preparation failed: {error}"),
+                    )
+                    .await
+                }
+            };
+
+            // Match the ordinary aggregate commit path: when Service::with_bus
+            // installed an immediate publisher, make each fresh outbox row
+            // InFlight inside the same fenced transaction and publish it only
+            // after that transaction succeeds. A crash or publish failure leaves
+            // the durable lease for a separately operated polling worker to
+            // recover.
+            let mut claimed = Vec::new();
+            if let Some(config) = publisher {
+                let now = SystemTime::now();
+                let mut claim_error = None;
+                for message in &mut batch.outbox_messages {
+                    // The post-commit hook receives clones of this staged
+                    // batch. Stamp before cloning so the broker copy and the
+                    // persisted row carry the same authoritative causation.
+                    message.overwrite_causation_id(attempt.causation_id().as_str());
+                    if let Err(error) = message.claim_at(&config.worker_id, config.lease, now) {
+                        claim_error = Some(error.to_string());
+                        break;
+                    }
+                    claimed.push(message.clone());
+                }
+                if let Some(error) = claim_error {
+                    drop(batch);
+                    return abandon_causal_attempt(
+                        repository,
+                        attempt,
+                        self.contract.consistency,
+                        format!("causal outbox claim failed before commit: {error}"),
+                    )
+                    .await;
+                }
+            }
+
+            let fence = attempt.fence();
+            let completion = attempt
+                .complete_with_obligations(
+                    terminal_state,
+                    replay_payload.clone(),
+                    projection_obligations,
+                    policy.replay_retention,
+                )
+                .map_err(internal_ledger_error)?;
+            let causal_batch = match direct_projection {
+                Some(direct_projection) => {
+                    CausalCommitBatch::with_direct_projection(batch, completion, direct_projection)
+                }
+                None => CausalCommitBatch::new(batch, completion),
+            };
+            match repository.commit_causal_batch(causal_batch).await {
+                Ok(()) => {
+                    parts.mark_snapshot_versions_committed();
+                    if let Some(config) = publisher {
+                        let _ = config.hook.publish_claimed(claimed).await;
+                    }
+                    let (_committed, serialized) = prepared.finalize_after_commit();
+                    let result = load_committed_dispatch_result(
+                        repository,
+                        &fence,
+                        self.contract.consistency,
+                    )
+                    .await?;
+                    if result.payload != serialized {
+                        return Err(CausalDispatchError::Internal(
+                            "durable command replay outcome differs from the committed handler payload"
+                                .into(),
+                        ));
+                    }
+                    Ok(result)
+                }
+                Err(error) => {
+                    recover_causal_commit_error(
+                        repository,
+                        fence,
+                        self.contract.consistency,
+                        error.to_string(),
+                    )
+                    .await
+                }
+            }
+        })
+    }
+
+    #[cfg(feature = "graphql")]
+    fn lookup<'a>(
+        &'a self,
+        dependencies: &'a D,
+        service_id: &'a str,
+        command_id: &'a str,
+        session: &'a Session,
+        principal: VerifiedPrincipal,
+    ) -> Pin<Box<dyn Future<Output = Result<CommandLookup, CausalDispatchError>> + Send + 'a>> {
+        Box::pin(async move {
+            ensure_causal_grant(&self.contract, session)?;
+            let command_id = CommandId::parse(command_id)
+                .map_err(|error| CausalDispatchError::BadRequest(error.to_string()))?;
+            let partition = PrincipalPartitionId::new(principal.partition_for_service(service_id))
+                .map_err(internal_ledger_error)?;
+            let key = CommandLedgerKey::new(service_id, partition, command_id)
+                .map_err(internal_ledger_error)?;
+            dependencies
+                .__causal_aggregate_repository()
+                .repo()
+                .lookup_command(&key, CommandLookupScope::CommandName(&self.contract.name))
+                .await
+                .map_err(internal_ledger_error)
+        })
+    }
+
+    #[cfg(feature = "graphql")]
+    fn status<'a>(
+        &'a self,
+        dependencies: &'a D,
+        service_id: &'a str,
+        command_id: &'a CommandId,
+        principal_partition: &'a PrincipalPartitionId,
+        session: &'a Session,
+    ) -> CausalStatusFuture<'a> {
+        Box::pin(async move {
+            // Status is deliberately non-enumerating: handlers that are no
+            // longer visible under the caller's current grant are skipped as
+            // if no command had ever existed.
+            if ensure_causal_grant(&self.contract, session).is_err() {
+                return Ok(CausalCommandPublicStatus::unknown(command_id.as_str()));
+            }
+
+            let key =
+                CommandLedgerKey::new(service_id, principal_partition.clone(), command_id.clone())
+                    .map_err(internal_ledger_error)?;
+            let contract_fingerprint = self.contract.fingerprint_bytes();
+            let lookup = dependencies
+                .__causal_aggregate_repository()
+                .repo()
+                .lookup_command(
+                    &key,
+                    CommandLookupScope::CommandContract {
+                        command_name: &self.contract.name,
+                        contract_fingerprint: &contract_fingerprint,
+                    },
+                )
+                .await
+                .map_err(internal_ledger_error)?;
+            evaluate_causal_command_status(
+                dependencies.__causal_aggregate_repository().repo(),
+                command_id,
+                self.contract.consistency,
+                lookup,
+            )
+            .await
+        })
+    }
+}
+
+impl<D> ErasedRoutes for Routes<D>
+where
+    D: Send + Sync + 'static,
+{
+    fn handler_specs(&self) -> &[HandlerSpec] {
+        &self.handler_specs
+    }
+
+    fn typed_command_contracts(&self) -> Vec<&TypedCommandContract> {
+        self.typed_contracts()
+    }
+
+    fn projector_registrations(&self) -> Vec<ProjectorRegistration> {
+        self.projectors
+            .iter()
+            .map(|projector| projector.registration())
+            .collect()
+    }
+
+    fn bootstrap_projectors(&self) -> ProjectorBootstrapFuture<'_> {
+        Box::pin(async move {
+            for projector in &self.projectors {
+                projector.bootstrap(&self.dependencies).await?;
+            }
+            Ok(())
+        })
+    }
+
+    fn repair_projection<'a>(
+        &'a self,
+        handle: &'a ProjectionRepairHandle,
+    ) -> ProjectorRepairFuture<'a> {
+        Box::pin(async move {
+            let mut owner = None;
+            for (index, projector) in self.projectors.iter().enumerate() {
+                if projector
+                    .locates_failure(&self.dependencies, handle)
+                    .await?
+                {
+                    if owner.replace(index).is_some() {
+                        return Err(HandlerError::Projection(
+                            crate::projection_protocol::ProjectionProtocolError::InvalidBatch(
+                                "projection failure ID resolved to multiple registered projectors"
+                                    .into(),
+                            ),
+                        ));
+                    }
+                }
+            }
+            let Some(owner) = owner else {
+                return Ok(None);
+            };
+            self.projectors[owner]
+                .repair(&self.dependencies, handle)
+                .await
+        })
+    }
+
+    fn locates_projection_failure<'a>(
+        &'a self,
+        handle: &'a ProjectionRepairHandle,
+    ) -> ProjectorRepairLookupFuture<'a> {
+        Box::pin(async move {
+            let mut found = false;
+            for projector in &self.projectors {
+                if projector
+                    .locates_failure(&self.dependencies, handle)
+                    .await?
+                {
+                    if found {
+                        return Err(HandlerError::Projection(
+                            crate::projection_protocol::ProjectionProtocolError::InvalidBatch(
+                                "projection failure ID resolved to multiple registered projectors"
+                                    .into(),
+                            ),
+                        ));
+                    }
+                    found = true;
+                }
+            }
+            Ok(found)
+        })
+    }
+
+    fn is_causal_projector(&self, message: &Message) -> bool {
+        matches!(
+            self.handlers
+                .get(&message.kind)
+                .and_then(|handlers| handlers.get(message.name())),
+            Some(RegisteredHandler::Projector(_))
+        )
+    }
+
+    fn is_projector_route(&self, kind: MessageKind, name: &str) -> bool {
+        matches!(
+            self.handlers
+                .get(&kind)
+                .and_then(|handlers| handlers.get(name)),
+            Some(RegisteredHandler::Projector(_))
+        )
+    }
+
+    #[cfg(feature = "graphql")]
+    fn bind_typed_command_contracts(
+        &mut self,
+        contracts: &BTreeMap<String, TypedCommandContract>,
+    ) -> Result<(), String> {
+        for handlers in self.handlers.values_mut() {
+            for registered in handlers.values_mut() {
+                let RegisteredHandler::Causal(handler) = registered else {
+                    continue;
+                };
+                let current = handler.contract();
+                let bound = contracts.get(&current.name).ok_or_else(|| {
+                    format!(
+                        "GraphQL engine is missing typed command `{}` from the executable service",
+                        current.name
+                    )
+                })?;
+                let mut current_without_owner = current.clone();
+                current_without_owner.direct_projection = None;
+                for confirmation in &mut current_without_owner.confirmations {
+                    confirmation.clear_protocol_topology();
+                }
+                let mut bound_without_owner = bound.clone();
+                bound_without_owner.direct_projection = None;
+                for confirmation in &mut bound_without_owner.confirmations {
+                    confirmation.clear_protocol_topology();
+                }
+                if current.input_type_id != bound.input_type_id
+                    || current.output_type_id != bound.output_type_id
+                {
+                    return Err("typed command Rust input/output TypeId mismatch".into());
+                }
+                if current.consistency != bound.consistency
+                    || current.projected_model != bound.projected_model
+                    || current_without_owner.canonical_value()
+                        != bound_without_owner.canonical_value()
+                {
+                    return Err(format!(
+                        "typed command structural fingerprint mismatch for executable route `{}`",
+                        current.name
+                    ));
+                }
+                let contract = handler.contract_mut();
+                contract.confirmations = bound.confirmations.clone();
+                contract.direct_projection = bound.direct_projection.clone();
+            }
+        }
+        Ok(())
+    }
+
+    fn dispatch<'a>(
+        &'a self,
+        message: &'a Message,
+        input: Value,
+        session: Session,
+        ordered: Option<&'a OrderedDelivery>,
+    ) -> HandlerFuture<'a> {
+        Box::pin(self.invoke(message, input, session, ordered))
+    }
+
+    #[cfg(feature = "graphql")]
+    fn dispatch_causal<'a>(
+        &'a self,
+        command: &'a str,
+        service_id: &'a str,
+        command_id: &'a str,
+        input: Value,
+        session: Session,
+        principal: VerifiedPrincipal,
+        policy: CausalCommandPolicy,
+    ) -> CausalHandlerFuture<'a> {
+        let handler = self
+            .handlers
+            .get(&MessageKind::Command)
+            .and_then(|handlers| handlers.get(command));
+        match handler {
+            Some(RegisteredHandler::Causal(handler)) => handler.dispatch(
+                &self.dependencies,
+                service_id,
+                command_id,
+                input,
+                session,
+                principal,
+                policy,
+            ),
+            Some(RegisteredHandler::Legacy { .. })
+            | Some(RegisteredHandler::Projector(_))
+            | None => Box::pin(async move {
+                Err(CausalDispatchError::BadRequest(format!(
+                    "`{command}` is not a typed causal command"
+                )))
+            }),
+        }
+    }
+
+    #[cfg(feature = "graphql")]
+    fn lookup_causal<'a>(
+        &'a self,
+        command: &'a str,
+        service_id: &'a str,
+        command_id: &'a str,
+        session: &'a Session,
+        principal: VerifiedPrincipal,
+    ) -> Pin<Box<dyn Future<Output = Result<CommandLookup, CausalDispatchError>> + Send + 'a>> {
+        let handler = self
+            .handlers
+            .get(&MessageKind::Command)
+            .and_then(|handlers| handlers.get(command));
+        match handler {
+            Some(RegisteredHandler::Causal(handler)) => handler.lookup(
+                &self.dependencies,
+                service_id,
+                command_id,
+                session,
+                principal,
+            ),
+            Some(RegisteredHandler::Legacy { .. })
+            | Some(RegisteredHandler::Projector(_))
+            | None => Box::pin(async move {
+                Err(CausalDispatchError::BadRequest(format!(
+                    "`{command}` is not a typed causal command"
+                )))
+            }),
+        }
+    }
+
+    #[cfg(feature = "graphql")]
+    fn causal_command_status<'a>(
+        &'a self,
+        service_id: &'a str,
+        command_id: &'a CommandId,
+        principal_partition: &'a PrincipalPartitionId,
+        session: &'a Session,
+    ) -> CausalStatusFuture<'a> {
+        Box::pin(async move {
+            let mut handlers = self
+                .handlers
+                .get(&MessageKind::Command)
+                .into_iter()
+                .flat_map(HashMap::values)
+                .filter_map(|handler| match handler {
+                    RegisteredHandler::Causal(handler) => Some(handler.as_ref()),
+                    RegisteredHandler::Legacy { .. } | RegisteredHandler::Projector(_) => None,
+                })
+                .collect::<Vec<_>>();
+            handlers.sort_by(|left, right| left.contract().name.cmp(&right.contract().name));
+
+            for handler in handlers {
+                let status = handler
+                    .status(
+                        &self.dependencies,
+                        service_id,
+                        command_id,
+                        principal_partition,
+                        session,
+                    )
+                    .await?;
+                if !status.is_unknown() {
+                    return Ok(status);
+                }
+            }
+            Ok(CausalCommandPublicStatus::unknown(command_id.as_str()))
+        })
+    }
+
+    #[cfg(feature = "graphql")]
+    fn projected_storage_identities(&self) -> Vec<crate::command_ledger::CausalStorageIdentity> {
+        self.handlers
+            .values()
+            .flat_map(|handlers| handlers.values())
+            .filter_map(|handler| match handler {
+                RegisteredHandler::Causal(handler)
+                    if handler.contract().consistency == CommandConsistency::Projected =>
+                {
+                    Some(handler.storage_identity(&self.dependencies))
+                }
+                RegisteredHandler::Causal(_)
+                | RegisteredHandler::Legacy { .. }
+                | RegisteredHandler::Projector(_) => None,
+            })
+            .collect()
+    }
+
+    fn configure_outbox_publisher(
+        &mut self,
+        publisher: DynBusPublisher,
+        worker_id: String,
+        lease: Duration,
+        max_attempts: u32,
+        service_name: Option<String>,
+    ) {
+        if let Some(configurator) = self.outbox_configurator {
+            configurator(
+                &mut self.dependencies,
+                publisher,
+                worker_id,
+                lease,
+                max_attempts,
+                service_name,
+            );
+        }
+    }
+}
diff --git a/src/microsvc/service/runtime.rs b/src/microsvc/service/runtime.rs
new file mode 100644
index 00000000..6bf2330c
--- /dev/null
+++ b/src/microsvc/service/runtime.rs
@@ -0,0 +1,907 @@
+use std::collections::{BTreeMap, HashMap};
+use std::sync::Arc;
+use std::time::Duration;
+#[cfg(feature = "metrics")]
+use std::time::Instant;
+
+use serde_json::Value;
+
+#[cfg(feature = "graphql")]
+use super::causal::{
+    internal_ledger_error, CausalCommandPublicStatus, CausalDispatchError, CausalDispatchResult,
+    GraphqlServiceBindError,
+};
+use super::helpers::{
+    is_json_content_type, message_to_json_input, message_to_session, names_by_kind,
+};
+#[cfg(feature = "otel")]
+use super::helpers::{microsvc_dispatch_span, microsvc_handler_span};
+use super::request::{CommandRequest, CommandResponse};
+use super::routes::{CausalCommandPolicy, DynBusPublisher, ErasedRoutes, HandlerSpec, Routes};
+use crate::bus::{
+    Message, MessageKind, OrderedDelivery, RunOptions, SubscriptionPlan, TransportError,
+};
+#[cfg(feature = "graphql")]
+use crate::command_ledger::{CommandId, CommandLookup, PrincipalPartitionId};
+use crate::graphql::command_contract::{TypedCommandContract, TypedServiceCommandBinding};
+#[cfg(feature = "graphql")]
+use crate::graphql::identity::VerifiedPrincipal;
+use crate::microsvc::error::HandlerError;
+use crate::microsvc::projector::{ProjectionRepairHandle, ProjectorRegistration};
+use crate::microsvc::session::Session;
+
+/// The bus run behavior captured by [`Service::with_bus`](crate::microsvc::Service::with_bus).
+pub(crate) type ServiceRunner = Box<
+    dyn Fn(
+            Arc<Service>,
+            RunOptions,
+        ) -> std::pin::Pin<
+            Box<dyn std::future::Future<Output = Result<(), TransportError>> + Send>,
+        > + Send
+        + Sync,
+>;
+
+/// A microservice deployment that routes messages to one or more route bundles.
+pub struct Service {
+    name: Option<String>,
+    pub(super) routes: Vec<Box<dyn ErasedRoutes>>,
+    index: HashMap<MessageKind, HashMap<String, Vec<usize>>>,
+    handler_specs: Vec<HandlerSpec>,
+    causal_command_policy: CausalCommandPolicy,
+    runner: Option<ServiceRunner>,
+    /// When false, HTTP does not mount `POST /{command}` (GraphQL / health only).
+    /// Commands remain dispatchable via GraphQL mutations and in-process `dispatch`.
+    http_command_routes: bool,
+    #[cfg(feature = "graphql")]
+    graphql: Option<std::sync::Arc<crate::graphql::GraphqlEngine>>,
+}
+
+impl Service {
+    /// Start building a deployment-level service.
+    pub fn new() -> Self {
+        Self {
+            name: None,
+            routes: Vec::new(),
+            index: HashMap::new(),
+            handler_specs: Vec::new(),
+            causal_command_policy: CausalCommandPolicy::default(),
+            runner: None,
+            http_command_routes: true,
+            #[cfg(feature = "graphql")]
+            graphql: None,
+        }
+    }
+
+    /// Disable `POST /{command}` HTTP routes.
+    ///
+    /// Use when the public surface is GraphQL-only (command mutations + queries).
+    /// Handlers stay registered for GraphQL dispatch and bus consumers.
+    pub fn without_http_command_routes(mut self) -> Self {
+        self.http_command_routes = false;
+        self
+    }
+
+    /// Whether the HTTP router mounts per-command `POST /{name}` routes.
+    pub fn http_command_routes_enabled(&self) -> bool {
+        self.http_command_routes
+    }
+
+    /// Configure the durable command attempt lease and replay retention.
+    ///
+    /// The defaults are 30 seconds and 30 days. Retention must remain longer
+    /// than the attempt lease; deployments must also keep it beyond the retry
+    /// and resume window advertised to their generated clients.
+    pub fn causal_command_timing(
+        mut self,
+        attempt_lease: Duration,
+        replay_retention: Duration,
+    ) -> Self {
+        assert!(
+            !attempt_lease.is_zero(),
+            "causal command attempt lease must be positive"
+        );
+        assert!(
+            replay_retention > attempt_lease,
+            "causal command replay retention must exceed the attempt lease"
+        );
+        self.causal_command_policy = CausalCommandPolicy {
+            attempt_lease,
+            replay_retention,
+        };
+        self
+    }
+
+    /// Attach a GraphQL query engine served at `POST /graphql`.
+    ///
+    /// Panics when [`Self::try_with_graphql`] rejects the attachment. New code
+    /// that registers typed commands should prefer the fallible form.
+    #[cfg(feature = "graphql")]
+    pub fn with_graphql(self, engine: crate::graphql::GraphqlEngine) -> Self {
+        self.try_with_graphql(engine)
+            .unwrap_or_else(|error| panic!("cannot enable GraphQL: {error}"))
+    }
+
+    /// Validate and attach a GraphQL engine.
+    ///
+    /// Typed commands are compared by service ID, a canonical structural
+    /// fingerprint, and exact Rust input/output `TypeId`s. A validated engine
+    /// may attach and serve reads and durable typed mutations only when its
+    /// opaque causal protocol tokens are configured. `Projected` commands
+    /// additionally require the engine and command repository to carry the
+    /// same opaque causal-storage identity. Services with no typed commands
+    /// may attach a read-only engine.
+    #[cfg(feature = "graphql")]
+    pub fn try_with_graphql(
+        mut self,
+        engine: crate::graphql::GraphqlEngine,
+    ) -> Result<Self, GraphqlServiceBindError> {
+        if !self.typed_command_contracts().is_empty() {
+            let contracts = engine
+                .typed_command_contracts_for_service()
+                .map_err(GraphqlServiceBindError)?
+                .into_iter()
+                .map(|contract| (contract.name.clone(), contract))
+                .collect::<BTreeMap<_, _>>();
+            for routes in &mut self.routes {
+                routes
+                    .bind_typed_command_contracts(&contracts)
+                    .map_err(GraphqlServiceBindError)?;
+            }
+        }
+        self.validate_graphql_engine(&engine)?;
+        self.graphql = Some(std::sync::Arc::new(engine));
+        Ok(self)
+    }
+
+    #[cfg(feature = "graphql")]
+    pub(crate) fn validate_graphql_engine(
+        &self,
+        engine: &crate::graphql::GraphqlEngine,
+    ) -> Result<(), GraphqlServiceBindError> {
+        let service_id = self.name().ok_or_else(|| {
+            GraphqlServiceBindError(
+                "GraphQL attachment requires a stable Service::named identity".into(),
+            )
+        })?;
+        let engine_service_id = engine.service_id().ok_or_else(|| {
+            GraphqlServiceBindError(
+                "GraphQL attachment requires an engine with a validated service ID".into(),
+            )
+        })?;
+        if service_id != engine_service_id {
+            return Err(GraphqlServiceBindError(format!(
+                "service ID mismatch: executable service `{service_id}` vs GraphQL engine `{engine_service_id}`"
+            )));
+        }
+        if self.handles_message(crate::bus::MessageKind::Command, "graphql") {
+            return Err(GraphqlServiceBindError(
+                "a command named `graphql` is already registered".into(),
+            ));
+        }
+
+        let typed_commands = self.typed_command_contracts();
+        match (typed_commands.is_empty(), engine.typed_command_binding()) {
+            (true, None) => {}
+            (_, Some(engine_binding)) => {
+                let service_binding = self
+                    .typed_command_binding()
+                    .map_err(GraphqlServiceBindError)?;
+                if service_binding.service_id != engine_binding.service_id {
+                    return Err(GraphqlServiceBindError(format!(
+                        "service ID mismatch: executable service `{}` vs GraphQL engine `{}`",
+                        service_binding.service_id, engine_binding.service_id
+                    )));
+                }
+                if service_binding.structural_fingerprint != engine_binding.structural_fingerprint {
+                    return Err(GraphqlServiceBindError(format!(
+                        "typed command structural fingerprint mismatch: executable `{}` vs GraphQL `{}`",
+                        service_binding.structural_fingerprint,
+                        engine_binding.structural_fingerprint
+                    )));
+                }
+                if service_binding.types != engine_binding.types {
+                    return Err(GraphqlServiceBindError(
+                        "typed command Rust input/output TypeId mismatch".into(),
+                    ));
+                }
+            }
+            (false, None) => {
+                return Err(GraphqlServiceBindError(
+                    "GraphQL engine was not derived from this service's typed command inventory"
+                        .into(),
+                ));
+            }
+        }
+
+        if !typed_commands.is_empty() && !engine.causal_protocol_configured() {
+            return Err(GraphqlServiceBindError(
+                "typed causal commands require a configured GraphQL protocol token key".into(),
+            ));
+        }
+
+        let projected_identities = self
+            .routes
+            .iter()
+            .flat_map(|routes| routes.projected_storage_identities())
+            .collect::<Vec<_>>();
+        if !projected_identities.is_empty() {
+            let engine_identity = engine.causal_storage_identity().ok_or_else(|| {
+                GraphqlServiceBindError(
+                    "Projected commands require a GraphQL pool derived from the same repository handle"
+                        .into(),
+                )
+            })?;
+            if projected_identities
+                .iter()
+                .any(|identity| *identity != engine_identity)
+            {
+                return Err(GraphqlServiceBindError(
+                    "Projected command repository and GraphQL query pool storage identities differ"
+                        .into(),
+                ));
+            }
+        }
+
+        Ok(())
+    }
+
+    /// The attached GraphQL engine, if any.
+    #[cfg(feature = "graphql")]
+    pub fn graphql_engine(&self) -> Option<std::sync::Arc<crate::graphql::GraphqlEngine>> {
+        self.graphql.clone()
+    }
+
+    /// Build a service from a single route bundle.
+    pub fn route<D>(routes: Routes<D>) -> Self
+    where
+        D: Send + Sync + 'static,
+    {
+        Self::new().routes(routes)
+    }
+
+    /// Assign a stable service/deployment identity.
+    ///
+    /// Broker-backed buses use this as the default durable consumer group when the
+    /// bus itself was not configured with an explicit group. Use the same name for
+    /// every replica of one service deployment; use different names for independent
+    /// event consumers that each need their own event copy.
+    pub fn named(mut self, name: impl Into<String>) -> Self {
+        let name = name.into();
+        assert!(!name.trim().is_empty(), "service name must not be empty");
+        if let Some(existing) = self.name.as_deref() {
+            assert_eq!(
+                existing, name,
+                "service identity was already configured and cannot be changed"
+            );
+        }
+        #[cfg(feature = "graphql")]
+        if let Some(engine) = &self.graphql {
+            assert_eq!(
+                engine.service_id(),
+                Some(name.as_str()),
+                "attached GraphQL engine identity does not match renamed service"
+            );
+        }
+        self.name = Some(name);
+        self
+    }
+
+    /// The stable service/deployment identity, if one was configured.
+    pub fn name(&self) -> Option<&str> {
+        self.name.as_deref()
+    }
+
+    /// Install the bus run behavior (used by `with_bus`).
+    pub(crate) fn set_runner(&mut self, runner: ServiceRunner) {
+        self.runner = Some(runner);
+    }
+
+    /// Take the installed bus run behavior (used by `run`).
+    pub(crate) fn take_runner(&mut self) -> Option<ServiceRunner> {
+        self.runner.take()
+    }
+
+    /// Add a typed route bundle to this service.
+    pub fn routes<D>(mut self, routes: Routes<D>) -> Self
+    where
+        D: Send + Sync + 'static,
+    {
+        self.add_routes(routes);
+        self
+    }
+
+    pub(super) fn add_routes<D>(&mut self, routes: Routes<D>)
+    where
+        D: Send + Sync + 'static,
+    {
+        let keys = routes.registered_keys();
+        let new_projectors = routes.projector_registrations();
+        let existing_projectors = self
+            .routes
+            .iter()
+            .flat_map(|routes| routes.projector_registrations())
+            .collect::<Vec<_>>();
+        validate_projector_registrations(existing_projectors.iter().chain(new_projectors.iter()));
+        let typed_commands = routes
+            .typed_contracts()
+            .into_iter()
+            .cloned()
+            .collect::<Vec<_>>();
+        #[cfg(feature = "graphql")]
+        assert!(
+            self.graphql.is_none() || typed_commands.is_empty(),
+            "cannot add typed command routes after attaching a GraphQL engine"
+        );
+        for (kind, name) in &keys {
+            if let Some(existing) = self.index.get(kind).and_then(|by_name| by_name.get(name)) {
+                let projector_fanout = *kind == MessageKind::Event
+                    && routes.is_projector_route(*kind, name)
+                    && existing
+                        .iter()
+                        .all(|index| self.routes[*index].is_projector_route(*kind, name));
+                assert!(
+                    projector_fanout,
+                    "duplicate route registration for {:?} `{}` is allowed only between causal projectors",
+                    kind,
+                    name
+                );
+            }
+            #[cfg(feature = "graphql")]
+            assert!(
+                !(self.graphql.is_some()
+                    && *kind == crate::bus::MessageKind::Command
+                    && name == "graphql"),
+                "cannot register command `graphql` while GraphQL is enabled on this service"
+            );
+        }
+        let existing_commands = self.typed_command_contracts();
+        for contract in &typed_commands {
+            assert!(
+                !existing_commands
+                    .iter()
+                    .any(|registered| registered.name == contract.name),
+                "duplicate typed command declaration for `{}`",
+                contract.name
+            );
+        }
+
+        let route_index = self.routes.len();
+        for (kind, name) in keys {
+            self.index
+                .entry(kind)
+                .or_default()
+                .entry(name)
+                .or_default()
+                .push(route_index);
+        }
+        self.handler_specs.extend_from_slice(routes.handler_specs());
+        self.routes.push(Box::new(routes));
+    }
+
+    pub(crate) fn typed_command_contracts(&self) -> Vec<TypedCommandContract> {
+        self.routes
+            .iter()
+            .flat_map(|routes| routes.typed_command_contracts())
+            .cloned()
+            .collect()
+    }
+
+    pub(crate) fn typed_command_binding(&self) -> Result<TypedServiceCommandBinding, String> {
+        let service_id = self
+            .name()
+            .ok_or_else(|| "typed command inventory requires Service::named".to_string())?;
+        TypedServiceCommandBinding::from_contracts(service_id, &self.typed_command_contracts())
+    }
+
+    /// Execute one authenticated typed causal route through its durable ledger
+    /// and framework-owned staged commit boundary.
+    #[cfg(feature = "graphql")]
+    #[allow(dead_code)]
+    pub(crate) async fn dispatch_causal(
+        &self,
+        command: &str,
+        command_id: &str,
+        input: Value,
+        session: Session,
+        principal: VerifiedPrincipal,
+    ) -> Result<Value, CausalDispatchError> {
+        self.dispatch_causal_with_receipt(command, command_id, input, session, principal)
+            .await
+            .map(|result| result.payload)
+    }
+
+    /// Execute one authenticated typed causal route and retain the exact
+    /// durable replay material needed to construct a causal receipt.
+    #[cfg(feature = "graphql")]
+    pub(crate) async fn dispatch_causal_with_receipt(
+        &self,
+        command: &str,
+        command_id: &str,
+        input: Value,
+        session: Session,
+        principal: VerifiedPrincipal,
+    ) -> Result<CausalDispatchResult, CausalDispatchError> {
+        let service_id = self.name().ok_or_else(|| {
+            CausalDispatchError::Internal(
+                "typed causal dispatch requires Service::named identity".into(),
+            )
+        })?;
+        let route_index = self
+            .index
+            .get(&MessageKind::Command)
+            .and_then(|commands| commands.get(command))
+            .and_then(|indices| (indices.len() == 1).then_some(indices[0]))
+            .ok_or_else(|| CausalDispatchError::BadRequest("unknown typed command".into()))?;
+        self.routes[route_index]
+            .dispatch_causal(
+                command,
+                service_id,
+                command_id,
+                input,
+                session,
+                principal,
+                self.causal_command_policy,
+            )
+            .await
+    }
+
+    /// Resolve one client-created command ID without accepting a command name.
+    ///
+    /// The verified principal determines the private ledger partition and each
+    /// finite causal handler rechecks its current role grant and contract
+    /// fingerprint. Malformed, absent, wrong-principal, revoked, drifted, and
+    /// ambiguous IDs all collapse to `unknown`.
+    #[cfg(feature = "graphql")]
+    pub(crate) async fn causal_command_status(
+        &self,
+        command_id: &str,
+        session: &Session,
+        principal: VerifiedPrincipal,
+    ) -> Result<CausalCommandPublicStatus, CausalDispatchError> {
+        let Ok(parsed_command_id) = CommandId::parse(command_id) else {
+            return Ok(CausalCommandPublicStatus::unknown(command_id));
+        };
+        let service_id = self.name().ok_or_else(|| {
+            CausalDispatchError::Internal(
+                "typed causal status requires Service::named identity".into(),
+            )
+        })?;
+        let principal_partition =
+            PrincipalPartitionId::new(principal.partition_for_service(service_id))
+                .map_err(internal_ledger_error)?;
+
+        let mut found = None;
+        for routes in &self.routes {
+            let status = routes
+                .causal_command_status(
+                    service_id,
+                    &parsed_command_id,
+                    &principal_partition,
+                    session,
+                )
+                .await?;
+            if status.is_unknown() {
+                continue;
+            }
+            if found.replace(status).is_some() {
+                // Separate route bundles may use separate repositories. A
+                // duplicated bearer-scoped command ID is intentionally not
+                // enumerated or resolved by registration order.
+                return Ok(CausalCommandPublicStatus::unknown(
+                    parsed_command_id.as_str(),
+                ));
+            }
+        }
+        Ok(found.unwrap_or_else(|| CausalCommandPublicStatus::unknown(parsed_command_id.as_str())))
+    }
+
+    /// Private lookup seam used by replay recovery and the authorized status
+    /// envelope. The route rechecks the current role grant before deriving the
+    /// bearer-scoped ledger key.
+    #[cfg(feature = "graphql")]
+    #[allow(dead_code)]
+    pub(crate) async fn lookup_causal_command(
+        &self,
+        command: &str,
+        command_id: &str,
+        session: &Session,
+        principal: VerifiedPrincipal,
+    ) -> Result<CommandLookup, CausalDispatchError> {
+        let service_id = self.name().ok_or_else(|| {
+            CausalDispatchError::Internal(
+                "typed causal lookup requires Service::named identity".into(),
+            )
+        })?;
+        let route_index = self
+            .index
+            .get(&MessageKind::Command)
+            .and_then(|commands| commands.get(command))
+            .and_then(|indices| (indices.len() == 1).then_some(indices[0]))
+            .ok_or_else(|| CausalDispatchError::BadRequest("unknown typed command".into()))?;
+        self.routes[route_index]
+            .lookup_causal(command, service_id, command_id, session, principal)
+            .await
+    }
+
+    /// Dispatch a command by name.
+    ///
+    /// Builds a `Context` from the input and session, looks up the handler,
+    /// runs the guard (if any), then calls the handler.
+    pub async fn dispatch(
+        &self,
+        command: &str,
+        input: Value,
+        session: Session,
+    ) -> Result<Value, HandlerError> {
+        #[cfg(feature = "metrics")]
+        let started = Instant::now();
+        let result = self.dispatch_command_inner(command, input, session).await;
+        #[cfg(feature = "metrics")]
+        {
+            let error = result.as_ref().err();
+            crate::metrics::record_microsvc_dispatch(
+                self.name(),
+                MessageKind::Command,
+                crate::telemetry::handler_message_label(command, error),
+                error
+                    .map(crate::telemetry::handler_error_status)
+                    .unwrap_or(crate::telemetry::dispatch_status::SUCCESS),
+                started.elapsed(),
+            );
+        }
+        result
+    }
+
+    async fn dispatch_command_inner(
+        &self,
+        command: &str,
+        input: Value,
+        session: Session,
+    ) -> Result<Value, HandlerError> {
+        if !self.handles_message(MessageKind::Command, command) {
+            return Err(HandlerError::UnknownCommand(command.to_string()));
+        }
+
+        let payload = serde_json::to_vec(&input).map_err(|e| {
+            HandlerError::DecodeFailed(format!("invalid JSON input for command '{command}': {e}"))
+        })?;
+        let metadata = session
+            .variables()
+            .iter()
+            .map(|(key, value)| (key.clone(), value.clone()))
+            .collect();
+        let message = Message {
+            id: None,
+            name: command.to_string(),
+            kind: MessageKind::Command,
+            payload,
+            content_type: "application/json".to_string(),
+            metadata,
+        };
+
+        self.invoke_with_dispatch_span(&message, input, session, None)
+            .await
+    }
+
+    /// Dispatch a `CommandRequest`, returning a `CommandResponse`.
+    pub async fn dispatch_request(&self, request: &CommandRequest) -> CommandResponse {
+        let session = Session::from_map(request.session_variables.clone());
+        match self
+            .dispatch(&request.command, request.input.clone(), session)
+            .await
+        {
+            Ok(value) => CommandResponse {
+                status: 200,
+                body: value,
+            },
+            Err(e) => CommandResponse {
+                status: e.status_code(),
+                body: serde_json::json!({ "error": e.to_string() }),
+            },
+        }
+    }
+
+    /// Dispatch a transport message.
+    pub async fn dispatch_message(&self, message: &Message) -> Result<Value, HandlerError> {
+        self.dispatch_ordered_message(message, None).await
+    }
+
+    pub(crate) async fn dispatch_ordered_message(
+        &self,
+        message: &Message,
+        ordered: Option<&OrderedDelivery>,
+    ) -> Result<Value, HandlerError> {
+        #[cfg(feature = "metrics")]
+        let started = Instant::now();
+        let result = self.dispatch_message_inner(message, ordered).await;
+        #[cfg(feature = "metrics")]
+        {
+            let error = result.as_ref().err();
+            crate::metrics::record_microsvc_dispatch(
+                self.name(),
+                message.kind,
+                crate::telemetry::handler_message_label(message.name(), error),
+                error
+                    .map(crate::telemetry::handler_error_status)
+                    .unwrap_or(crate::telemetry::dispatch_status::SUCCESS),
+                started.elapsed(),
+            );
+        }
+        result
+    }
+
+    async fn dispatch_message_inner(
+        &self,
+        message: &Message,
+        ordered: Option<&OrderedDelivery>,
+    ) -> Result<Value, HandlerError> {
+        if !self.handles_message(message.kind, &message.name) {
+            return Err(HandlerError::UnknownCommand(message.name.clone()));
+        }
+
+        let route_indices = self
+            .index
+            .get(&message.kind)
+            .and_then(|by_name| by_name.get(message.name()))
+            .ok_or_else(|| HandlerError::UnknownCommand(message.name.clone()))?;
+        let projector_only = route_indices
+            .iter()
+            .all(|index| self.routes[*index].is_causal_projector(message));
+        let input = if projector_only {
+            // The causal projector owns raw parsing so unit/constant partition
+            // declarations can durably record typed decode failures at the
+            // authenticated source cursor.
+            Value::Null
+        } else {
+            match message_to_json_input(message) {
+                Ok(input) => input,
+                // Binary payloads (bitcode, octet-stream) legitimately fail JSON
+                // parsing: handlers for those read `ctx.message().payload` directly,
+                // so a `Null` input is the intended fallback. A payload that
+                // *claims* to be JSON but does not parse is a decode error — surface
+                // it instead of silently nulling the input.
+                Err(_) if !is_json_content_type(&message.content_type) => Value::Null,
+                Err(err) => return Err(err),
+            }
+        };
+        let session = message_to_session(message);
+        self.invoke_with_dispatch_span(message, input, session, ordered)
+            .await
+    }
+
+    async fn invoke_with_dispatch_span(
+        &self,
+        message: &Message,
+        input: Value,
+        session: Session,
+        ordered: Option<&OrderedDelivery>,
+    ) -> Result<Value, HandlerError> {
+        #[cfg(feature = "otel")]
+        {
+            use tracing::Instrument as _;
+
+            let span = microsvc_dispatch_span(message);
+            crate::trace_context::set_span_parent_from_metadata_if_no_current_span(
+                &span,
+                &message.metadata,
+            );
+            return self
+                .invoke(message, input, session, ordered)
+                .instrument(span)
+                .await;
+        }
+
+        #[cfg(not(feature = "otel"))]
+        {
+            self.invoke(message, input, session, ordered).await
+        }
+    }
+
+    async fn invoke(
+        &self,
+        message: &Message,
+        input: Value,
+        session: Session,
+        ordered: Option<&OrderedDelivery>,
+    ) -> Result<Value, HandlerError> {
+        let route_indices = self
+            .index
+            .get(&message.kind)
+            .and_then(|by_name| by_name.get(message.name.as_str()))
+            .cloned()
+            .ok_or_else(|| HandlerError::UnknownCommand(message.name.clone()))?;
+        #[cfg(feature = "otel")]
+        let handler_span = microsvc_handler_span(message);
+        let dispatch = async move {
+            let mut result = Value::Null;
+            for route_index in route_indices {
+                result = self.routes[route_index]
+                    .dispatch(message, input.clone(), session.clone(), ordered)
+                    .await?;
+            }
+            Ok(result)
+        };
+
+        #[cfg(feature = "otel")]
+        {
+            use tracing::Instrument as _;
+
+            return dispatch.instrument(handler_span).await;
+        }
+
+        #[cfg(not(feature = "otel"))]
+        {
+            dispatch.await
+        }
+    }
+
+    /// List registered command names.
+    pub fn command_names(&self) -> Vec<&str> {
+        names_by_kind(&self.handler_specs, MessageKind::Command)
+    }
+
+    /// List registered event names.
+    pub fn event_names(&self) -> Vec<&str> {
+        names_by_kind(&self.handler_specs, MessageKind::Event)
+    }
+
+    /// Return transport metadata for registered handlers.
+    pub fn handler_specs(&self) -> &[HandlerSpec] {
+        &self.handler_specs
+    }
+
+    /// Return the command/event names a transport should subscribe to.
+    pub fn subscription_plan(&self) -> SubscriptionPlan {
+        let mut plan = SubscriptionPlan::default();
+
+        for spec in &self.handler_specs {
+            for name in spec.names() {
+                let bucket = match spec.kind {
+                    MessageKind::Command => &mut plan.commands,
+                    MessageKind::Event => &mut plan.events,
+                };
+                if !bucket.iter().any(|existing| existing == name) {
+                    bucket.push(name.to_string());
+                }
+            }
+        }
+
+        plan
+    }
+
+    /// Return whether this service has a handler for the message name.
+    pub fn handles(&self, name: &str) -> bool {
+        self.index
+            .values()
+            .any(|by_name| by_name.contains_key(name))
+    }
+
+    /// Return whether this service has a handler for this message kind and name.
+    pub fn handles_message(&self, kind: MessageKind, name: &str) -> bool {
+        self.index
+            .get(&kind)
+            .is_some_and(|by_name| by_name.contains_key(name))
+    }
+
+    /// Return whether this service has an event handler for the message name.
+    pub fn handles_event(&self, name: &str) -> bool {
+        self.handles_message(MessageKind::Event, name)
+    }
+
+    /// Configure every route bundle that supports immediate outbox publishing.
+    pub(crate) fn configure_outbox_publishers(
+        &mut self,
+        publisher: DynBusPublisher,
+        worker_id: String,
+        lease: Duration,
+        max_attempts: u32,
+    ) {
+        let service_name = self.name.clone();
+        for route in &mut self.routes {
+            route.configure_outbox_publisher(
+                publisher.clone(),
+                worker_id.clone(),
+                lease,
+                max_attempts,
+                service_name.clone(),
+            );
+        }
+    }
+
+    pub(crate) async fn bootstrap_projectors(&self) -> Result<(), HandlerError> {
+        for routes in &self.routes {
+            routes.bootstrap_projectors().await?;
+        }
+        Ok(())
+    }
+
+    /// Begin a new repair generation for the durable terminal failure named by
+    /// an opaque operator handle.
+    ///
+    /// The handle carries no partition bytes. Each configured store resolves
+    /// the globally unique failure ID to its exact durable scope; repair is
+    /// allowed only when that exact compiled topology belongs to this service.
+    /// Rebuild the service with the same repository, call this method, then
+    /// restart consumption so the retained failed delivery is retried first.
+    pub async fn repair_projection(
+        &self,
+        handle: &ProjectionRepairHandle,
+    ) -> Result<crate::projection_protocol::ProjectionGeneration, HandlerError> {
+        // Resolve every candidate before mutating any store. A corrupt
+        // deployment that presents the same globally unique failure ID through
+        // multiple stores must fail without advancing even the first one.
+        let mut owner = None;
+        for (index, routes) in self.routes.iter().enumerate() {
+            if !routes.locates_projection_failure(handle).await? {
+                continue;
+            }
+            if owner.replace(index).is_some() {
+                return Err(HandlerError::Projection(
+                    crate::projection_protocol::ProjectionProtocolError::InvalidBatch(
+                        "projection failure ID resolved through multiple service route stores"
+                            .into(),
+                    ),
+                ));
+            }
+        }
+        let owner = owner.ok_or_else(|| {
+            HandlerError::Projection(
+                crate::projection_protocol::ProjectionProtocolError::InvalidBatch(format!(
+                    "projection repair handle `{handle}` does not name a failure owned by this service"
+                )),
+            )
+        })?;
+        self.routes[owner]
+            .repair_projection(handle)
+            .await?
+            .ok_or_else(|| {
+                HandlerError::Projection(
+                    crate::projection_protocol::ProjectionProtocolError::InvalidBatch(
+                        "projection failure disappeared after repair ownership resolution".into(),
+                    ),
+                )
+            })
+    }
+}
+
+pub(super) fn validate_projector_registrations<'a>(
+    registrations: impl IntoIterator<Item = &'a ProjectorRegistration>,
+) {
+    let mut topologies = BTreeMap::new();
+    let mut models = BTreeMap::new();
+    let mut tables = BTreeMap::new();
+    for registration in registrations {
+        let name = registration.topology.name().to_string();
+        if let Some(existing) = topologies.insert(name.clone(), registration.topology.clone()) {
+            assert_eq!(
+                existing, registration.topology,
+                "causal projector `{name}` is registered with conflicting compiled topologies"
+            );
+            panic!("causal projector `{name}` is registered more than once");
+        }
+        for owner in &registration.ownership {
+            if let Some((existing_projector, existing_table)) =
+                models.insert(owner.model.clone(), (name.clone(), owner.table.clone()))
+            {
+                panic!(
+                    "projection model `{}` has multiple owners: `{existing_projector}`/`{existing_table}` and `{name}`/`{}`",
+                    owner.model, owner.table
+                );
+            }
+            if let Some((existing_projector, existing_model)) =
+                tables.insert(owner.table.clone(), (name.clone(), owner.model.clone()))
+            {
+                panic!(
+                    "physical projection table `{}` has multiple owners: `{existing_projector}`/`{existing_model}` and `{name}`/`{}`",
+                    owner.table, owner.model
+                );
+            }
+        }
+    }
+}
+
+impl Default for Service {
+    fn default() -> Self {
+        Self::new()
+    }
+}
diff --git a/src/microsvc/service/tests.rs b/src/microsvc/service/tests.rs
new file mode 100644
index 00000000..31fb2683
--- /dev/null
+++ b/src/microsvc/service/tests.rs
@@ -0,0 +1,2593 @@
+#[cfg(feature = "graphql")]
+use super::causal::collapse_projection_evidence;
+use super::*;
+#[cfg(feature = "graphql")]
+use crate::aggregate::Aggregate;
+#[cfg(feature = "graphql")]
+use crate::bus::RunOptions;
+use crate::bus::{Message, MessageKind, SubscriptionPlan};
+#[cfg(feature = "graphql")]
+use crate::command_ledger::{
+    AttemptFence, CausalCommitBatch, CausalGetStream, CausalRepositoryIdentity,
+    CausalTransactionalCommit, CommandLedgerError, CommandLedgerKey, CommandLedgerState,
+    CommandLedgerStore, CommandLookup, CommandLookupScope, CommandReservation, ReservationOutcome,
+};
+#[cfg(feature = "graphql")]
+use crate::graphql::command_contract::CommandConsistency;
+#[cfg(feature = "graphql")]
+use crate::graphql::identity::VerifiedPrincipal;
+use crate::graphql::{
+    typed_command, Accepted, GraphqlInputType, GraphqlOutputType, GraphqlTypeDef, GraphqlTypeField,
+    PreparedCommand,
+};
+#[cfg(feature = "graphql")]
+use crate::graphql::{Projected, SurfaceDirectProjection, SurfaceProjector};
+#[cfg(feature = "graphql")]
+use crate::microsvc::HasOutboxStore;
+use crate::microsvc::{
+    CommandRequest, Context, HandlerError, RepoReadModelDependencies, Routes, Service, Session,
+};
+#[cfg(feature = "graphql")]
+use crate::outbox::OutboxMessage;
+#[cfg(feature = "graphql")]
+use crate::projection_protocol::{
+    ProjectionChangeCursor, ProjectionChangeRead, ProjectionCheckpoint, ProjectionCommitBatch,
+    ProjectionCommitResult, ProjectionFailure, ProjectionFailureBatch, ProjectionFailureLocation,
+    ProjectionGeneration, ProjectionInputCursor, ProjectionInputDisposition,
+    ProjectionLiveRecordBatch, ProjectionLiveRecordBatchRequest, ProjectionModelOwnership,
+    ProjectionObligationEvidenceBatch, ProjectionObligationEvidenceBatchRequest,
+    ProjectionObservation, ProjectionObservationKind, ProjectionPartition,
+    ProjectionPartitionRuntimeState, ProjectionProtocolError, ProjectionProtocolStore,
+    ProjectionQuerySnapshot, ProjectionQuerySnapshotBatch, ProjectionQuerySnapshotBatchRequest,
+    ProjectionQuerySnapshotRequest, ProjectionRecordMetadata, ProjectionRecordScope,
+    ProjectorTopologyId, TrustedProjectionInput,
+};
+use crate::{
+    sourced, AggregateBuilder, AggregateRepository, Entity, InMemoryRepository, Queueable,
+    QueuedRepository,
+};
+#[cfg(feature = "graphql")]
+use crate::{GetStream, OutboxStore};
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+use serde_json::Value;
+use std::collections::HashMap;
+#[cfg(feature = "graphql")]
+use std::future::Future;
+#[cfg(feature = "graphql")]
+use std::sync::atomic::AtomicUsize;
+use std::sync::atomic::{AtomicBool, Ordering};
+#[cfg(feature = "graphql")]
+use std::sync::{Arc, Mutex};
+
+#[cfg(feature = "graphql")]
+const TEST_PROTOCOL_TOKEN_KEY: [u8; 32] = [0x5a; 32];
+
+#[derive(Deserialize)]
+struct TypedInput {
+    id: String,
+}
+
+#[derive(Serialize)]
+struct TypedOutput {
+    id: String,
+}
+
+fn one_string_field(name: &str, field: &str) -> GraphqlTypeDef {
+    GraphqlTypeDef::new(
+        name,
+        vec![GraphqlTypeField {
+            name: field.into(),
+            type_name: "String".into(),
+            nullable: false,
+            list: false,
+            item_nullable: false,
+            nested: None,
+        }],
+    )
+}
+
+impl GraphqlInputType for TypedInput {
+    fn graphql_type() -> GraphqlTypeDef {
+        one_string_field("TypedInput", "id").with_type_id(std::any::TypeId::of::<Self>())
+    }
+}
+
+impl GraphqlOutputType for TypedOutput {
+    fn graphql_type() -> GraphqlTypeDef {
+        one_string_field("TypedOutput", "id").with_type_id(std::any::TypeId::of::<Self>())
+    }
+}
+
+#[cfg(feature = "graphql")]
+#[derive(Deserialize)]
+struct CausalTestInput {
+    id: String,
+    label: String,
+}
+
+#[cfg(feature = "graphql")]
+impl GraphqlInputType for CausalTestInput {
+    fn graphql_type() -> GraphqlTypeDef {
+        GraphqlTypeDef::new(
+            "CausalTestInput",
+            vec![
+                GraphqlTypeField {
+                    name: "id".into(),
+                    type_name: "String".into(),
+                    nullable: false,
+                    list: false,
+                    item_nullable: false,
+                    nested: None,
+                },
+                GraphqlTypeField {
+                    name: "label".into(),
+                    type_name: "String".into(),
+                    nullable: false,
+                    list: false,
+                    item_nullable: false,
+                    nested: None,
+                },
+            ],
+        )
+        .with_type_id(std::any::TypeId::of::<Self>())
+    }
+}
+
+#[cfg(feature = "graphql")]
+#[derive(Clone, Deserialize, crate::GraphqlInput)]
+struct CausalProjectionInput {
+    #[serde(rename = "todoId")]
+    id: String,
+    #[serde(rename = "tenantPartition")]
+    partition: String,
+}
+
+#[cfg(feature = "graphql")]
+#[derive(Clone, Serialize, Deserialize, crate::ReadModel)]
+#[readmodel(
+        table = "causal_projection_obligation_views",
+        primary_key = ["id"]
+    )]
+struct CausalProjectionObligationView {
+    id: String,
+}
+
+#[cfg(feature = "graphql")]
+#[derive(Clone, Serialize, Deserialize, crate::ReadModel)]
+#[readmodel(table = "causal_projection_sibling_views", primary_key = ["id"])]
+struct CausalProjectionSiblingView {
+    id: String,
+}
+
+#[cfg(feature = "graphql")]
+impl GraphqlOutputType for CausalProjectionObligationView {
+    fn graphql_type() -> GraphqlTypeDef {
+        one_string_field("CausalProjectionObligationView", "id")
+            .with_type_id(std::any::TypeId::of::<Self>())
+    }
+}
+
+#[cfg(feature = "graphql")]
+impl GraphqlOutputType for CausalProjectionSiblingView {
+    fn graphql_type() -> GraphqlTypeDef {
+        one_string_field("CausalProjectionSiblingView", "id")
+            .with_type_id(std::any::TypeId::of::<Self>())
+    }
+}
+
+static TYPED_HANDLER_INVOKED: AtomicBool = AtomicBool::new(false);
+static TYPED_GUARD_INVOKED: AtomicBool = AtomicBool::new(false);
+
+async fn typed_handler(
+    _context: &CausalCommandContext<'_, RouteComboAggregate>,
+    input: TypedInput,
+) -> Result<PreparedCommand<Accepted<TypedOutput>>, HandlerError> {
+    TYPED_HANDLER_INVOKED.store(true, Ordering::SeqCst);
+    Ok(PreparedCommand::prepare(TypedOutput { id: input.id }).unwrap())
+}
+
+#[derive(Default)]
+struct RouteComboAggregate {
+    entity: Entity,
+}
+
+#[sourced(entity)]
+impl RouteComboAggregate {
+    #[event("created")]
+    fn create(&mut self) {
+        self.entity.set_id("route-combo");
+    }
+}
+
+#[cfg(feature = "graphql")]
+#[derive(Default)]
+struct CausalDispatcherAggregate {
+    entity: Entity,
+}
+
+#[cfg(feature = "graphql")]
+impl CausalDispatcherAggregate {
+    fn record(&mut self, id: String) -> crate::SourcedResult {
+        self.entity.set_id(id);
+        self.entity.digest_empty("causal.recorded")
+    }
+}
+
+#[cfg(feature = "graphql")]
+impl Aggregate for CausalDispatcherAggregate {
+    type ReplayError = std::convert::Infallible;
+
+    fn aggregate_type() -> &'static str {
+        "service-causal-dispatcher-test"
+    }
+
+    fn entity(&self) -> &Entity {
+        &self.entity
+    }
+
+    fn entity_mut(&mut self) -> &mut Entity {
+        &mut self.entity
+    }
+
+    fn replay_event(&mut self, _event: &crate::EventRecord) -> Result<(), Self::ReplayError> {
+        Ok(())
+    }
+}
+
+#[cfg(feature = "graphql")]
+fn causal_test_principal() -> VerifiedPrincipal {
+    VerifiedPrincipal::test_oidc(
+        "https://issuer.example/",
+        "causal-test-subject",
+        &["distributed-tests"],
+    )
+}
+
+#[cfg(feature = "graphql")]
+fn causal_test_command_id() -> String {
+    uuid::Uuid::now_v7().hyphenated().to_string()
+}
+
+#[cfg(feature = "graphql")]
+fn causal_test_input(id: &str, label: &str) -> Value {
+    json!({ "id": id, "label": label })
+}
+
+#[cfg(feature = "graphql")]
+fn session_with_role(role: &str) -> Session {
+    let mut session = Session::new();
+    session.set(crate::microsvc::ROLE_KEY, role);
+    session
+}
+
+#[cfg(feature = "graphql")]
+#[derive(Clone, Copy)]
+enum InjectedCommitBehavior {
+    CommitThenErrorOnce,
+    ErrorBeforeCommitOnce,
+    Delegate,
+}
+
+#[cfg(feature = "graphql")]
+#[derive(Clone)]
+struct AmbiguousCommitRepository {
+    inner: InMemoryRepository,
+    behavior: Arc<Mutex<InjectedCommitBehavior>>,
+}
+
+#[cfg(feature = "graphql")]
+impl AmbiguousCommitRepository {
+    fn new(inner: InMemoryRepository, behavior: InjectedCommitBehavior) -> Self {
+        Self {
+            inner,
+            behavior: Arc::new(Mutex::new(behavior)),
+        }
+    }
+
+    fn injected_error() -> CommandLedgerError {
+        CommandLedgerError::Storage(crate::RepositoryError::retryable_storage(
+            "injected ambiguous causal commit",
+            std::io::Error::new(
+                std::io::ErrorKind::ConnectionReset,
+                "injected transport acknowledgement loss",
+            ),
+        ))
+    }
+}
+
+#[cfg(feature = "graphql")]
+impl CausalGetStream for AmbiguousCommitRepository {
+    fn get_causal_stream<'a>(
+        &'a self,
+        identity: &'a crate::StreamIdentity,
+    ) -> impl Future<Output = Result<Option<Entity>, crate::RepositoryError>> + Send + 'a {
+        CausalGetStream::get_causal_stream(&self.inner, identity)
+    }
+}
+
+#[cfg(feature = "graphql")]
+impl CausalRepositoryIdentity for AmbiguousCommitRepository {
+    fn causal_storage_identity(&self) -> crate::command_ledger::CausalStorageIdentity {
+        CausalRepositoryIdentity::causal_storage_identity(&self.inner)
+    }
+}
+
+#[cfg(feature = "graphql")]
+impl ProjectionProtocolStore for AmbiguousCommitRepository {
+    fn register_projection_models<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        ownership: &'a [ProjectionModelOwnership],
+    ) -> impl Future<Output = Result<(), ProjectionProtocolError>> + Send + 'a {
+        self.inner.register_projection_models(topology, ownership)
+    }
+
+    fn commit_projection(
+        &self,
+        batch: ProjectionCommitBatch,
+    ) -> impl Future<Output = Result<ProjectionCommitResult, ProjectionProtocolError>> + Send + '_
+    {
+        self.inner.commit_projection(batch)
+    }
+
+    fn record_projection_failure(
+        &self,
+        batch: ProjectionFailureBatch,
+    ) -> impl Future<Output = Result<ProjectionFailure, ProjectionProtocolError>> + Send + '_ {
+        self.inner.record_projection_failure(batch)
+    }
+
+    fn projection_checkpoint<'a>(
+        &'a self,
+        cursor_scope: &'a ProjectionInputCursor,
+        generation: ProjectionGeneration,
+    ) -> impl Future<Output = Result<Option<ProjectionCheckpoint>, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner.projection_checkpoint(cursor_scope, generation)
+    }
+
+    fn projection_record<'a>(
+        &'a self,
+        scope: &'a ProjectionRecordScope,
+    ) -> impl Future<Output = Result<Option<ProjectionRecordMetadata>, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        self.inner.projection_record(scope)
+    }
+
+    fn projection_input_disposition<'a>(
+        &'a self,
+        input: &'a TrustedProjectionInput,
+    ) -> impl Future<Output = Result<ProjectionInputDisposition, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner.projection_input_disposition(input)
+    }
+
+    fn projection_query_snapshot<'a>(
+        &'a self,
+        request: &'a ProjectionQuerySnapshotRequest,
+    ) -> impl Future<Output = Result<ProjectionQuerySnapshot, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner.projection_query_snapshot(request)
+    }
+
+    fn projection_query_snapshot_batch<'a>(
+        &'a self,
+        request: &'a ProjectionQuerySnapshotBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionQuerySnapshotBatch, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner.projection_query_snapshot_batch(request)
+    }
+
+    fn projection_obligation_evidence_batch<'a>(
+        &'a self,
+        request: &'a ProjectionObligationEvidenceBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionObligationEvidenceBatch, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        self.inner.projection_obligation_evidence_batch(request)
+    }
+
+    fn projection_live_record_batch<'a>(
+        &'a self,
+        request: &'a ProjectionLiveRecordBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionLiveRecordBatch, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner.projection_live_record_batch(request)
+    }
+
+    fn projection_partition_runtime_state<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+    ) -> impl Future<Output = Result<Option<ProjectionPartitionRuntimeState>, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        self.inner
+            .projection_partition_runtime_state(topology, partition)
+    }
+
+    fn projection_observation<'a>(
+        &'a self,
+        causation_id: &'a str,
+        scope: &'a ProjectionRecordScope,
+        kind: ProjectionObservationKind,
+    ) -> impl Future<Output = Result<Option<ProjectionObservation>, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner.projection_observation(causation_id, scope, kind)
+    }
+
+    fn projection_changes<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        after: Option<&'a ProjectionChangeCursor>,
+        limit: usize,
+    ) -> impl Future<Output = Result<ProjectionChangeRead, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner
+            .projection_changes(topology, partition, after, limit)
+    }
+
+    fn repair_projection<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<ProjectionGeneration, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner
+            .repair_projection(topology, partition, failure_id)
+    }
+
+    fn compact_projection_changes<'a>(
+        &'a self,
+        through: &'a ProjectionChangeCursor,
+    ) -> impl Future<Output = Result<u64, ProjectionProtocolError>> + Send + 'a {
+        self.inner.compact_projection_changes(through)
+    }
+
+    fn projection_failure<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<Option<ProjectionFailure>, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner
+            .projection_failure(topology, partition, failure_id)
+    }
+
+    fn projection_failure_location<'a>(
+        &'a self,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<Option<ProjectionFailureLocation>, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        self.inner.projection_failure_location(failure_id)
+    }
+}
+
+#[cfg(feature = "graphql")]
+impl CommandLedgerStore for AmbiguousCommitRepository {
+    fn reserve_command(
+        &self,
+        reservation: CommandReservation,
+    ) -> impl Future<Output = Result<ReservationOutcome, CommandLedgerError>> + Send + '_ {
+        CommandLedgerStore::reserve_command(&self.inner, reservation)
+    }
+
+    fn lookup_command<'a>(
+        &'a self,
+        key: &'a CommandLedgerKey,
+        scope: CommandLookupScope<'a>,
+    ) -> impl Future<Output = Result<CommandLookup, CommandLedgerError>> + Send + 'a {
+        CommandLedgerStore::lookup_command(&self.inner, key, scope)
+    }
+
+    fn mark_retryable_unknown(
+        &self,
+        attempt: AttemptFence,
+    ) -> impl Future<Output = Result<(), CommandLedgerError>> + Send + '_ {
+        CommandLedgerStore::mark_retryable_unknown(&self.inner, attempt)
+    }
+
+    fn compact_expired_commands(
+        &self,
+        limit: usize,
+    ) -> impl Future<Output = Result<u64, CommandLedgerError>> + Send + '_ {
+        CommandLedgerStore::compact_expired_commands(&self.inner, limit)
+    }
+}
+
+#[cfg(feature = "graphql")]
+impl CausalTransactionalCommit for AmbiguousCommitRepository {
+    fn commit_causal_batch<'a>(
+        &'a self,
+        batch: CausalCommitBatch<'a>,
+    ) -> impl Future<Output = Result<(), CommandLedgerError>> + Send + 'a {
+        async move {
+            let behavior = {
+                let mut behavior = self.behavior.lock().map_err(|_| {
+                    CommandLedgerError::Storage(crate::RepositoryError::LockPoisoned(
+                        "injected causal commit behavior",
+                    ))
+                })?;
+                std::mem::replace(&mut *behavior, InjectedCommitBehavior::Delegate)
+            };
+            match behavior {
+                InjectedCommitBehavior::CommitThenErrorOnce => {
+                    CausalTransactionalCommit::commit_causal_batch(&self.inner, batch).await?;
+                    Err(Self::injected_error())
+                }
+                InjectedCommitBehavior::ErrorBeforeCommitOnce => Err(Self::injected_error()),
+                InjectedCommitBehavior::Delegate => {
+                    CausalTransactionalCommit::commit_causal_batch(&self.inner, batch).await
+                }
+            }
+        }
+    }
+}
+
+#[cfg(feature = "graphql")]
+impl HasOutboxStore for AmbiguousCommitRepository {
+    type OutboxStore = crate::InMemoryOutboxStore;
+
+    fn outbox_store(&self) -> Self::OutboxStore {
+        self.inner.outbox_store()
+    }
+}
+
+type RouteComboRepo =
+    AggregateRepository<QueuedRepository<InMemoryRepository>, RouteComboAggregate>;
+type RouteComboDeps = RepoReadModelDependencies<RouteComboRepo, InMemoryRepository>;
+
+fn test_routes() -> Routes<()> {
+    Routes::new().with_dependencies(())
+}
+
+fn test_service(routes: Routes<()>) -> Service {
+    Service::new().routes(routes)
+}
+
+#[test]
+fn named_service_preserves_identity_with_route_bundles() {
+    let routes = Routes::new().with_read_model_store(crate::InMemoryRepository::new());
+    let service = Service::new().named("todo-api").routes(routes);
+
+    assert_eq!(service.name(), Some("todo-api"));
+    assert_eq!(
+        crate::bus::MessageRouter::consumer_group(&service),
+        Some("todo-api")
+    );
+}
+
+#[tokio::test]
+async fn typed_direct_dispatch_fails_before_invoking_handler() {
+    TYPED_HANDLER_INVOKED.store(false, Ordering::SeqCst);
+    let service = Service::new().named("todos").routes(
+        Routes::new()
+            .with_repo(
+                InMemoryRepository::new()
+                    .queued()
+                    .aggregate::<RouteComboAggregate>(),
+            )
+            .typed_command(typed_command::<TypedInput, Accepted<TypedOutput>>(
+                "todo.create",
+            ))
+            .handle(typed_handler),
+    );
+
+    let error = service
+        .dispatch("todo.create", json!({ "id": "todo-1" }), Session::new())
+        .await
+        .expect_err("typed causal commands must reject direct dispatch");
+
+    assert!(error.to_string().contains("verified GraphQL bearer"));
+    assert!(!TYPED_HANDLER_INVOKED.load(Ordering::SeqCst));
+}
+
+#[tokio::test]
+async fn typed_direct_dispatch_fails_before_invoking_guard_or_handler() {
+    TYPED_GUARD_INVOKED.store(false, Ordering::SeqCst);
+    TYPED_HANDLER_INVOKED.store(false, Ordering::SeqCst);
+    let service = Service::new().named("todos").routes(
+        Routes::new()
+            .with_repo(
+                InMemoryRepository::new()
+                    .queued()
+                    .aggregate::<RouteComboAggregate>(),
+            )
+            .typed_command(typed_command::<TypedInput, Accepted<TypedOutput>>(
+                "todo.guarded_create",
+            ))
+            .guarded(
+                |_| {
+                    TYPED_GUARD_INVOKED.store(true, Ordering::SeqCst);
+                    true
+                },
+                typed_handler,
+            ),
+    );
+
+    let error = service
+        .dispatch(
+            "todo.guarded_create",
+            json!({ "id": "todo-1" }),
+            Session::new(),
+        )
+        .await
+        .expect_err("typed causal commands must reject before application guards");
+
+    assert!(error.to_string().contains("verified GraphQL bearer"));
+    assert!(!TYPED_GUARD_INVOKED.load(Ordering::SeqCst));
+    assert!(!TYPED_HANDLER_INVOKED.load(Ordering::SeqCst));
+}
+
+#[cfg(feature = "graphql")]
+#[tokio::test]
+async fn causal_dispatch_replays_canonical_equivalent_input_without_reinvoking_handler() {
+    let handler_calls = Arc::new(AtomicUsize::new(0));
+    let route_handler_calls = Arc::clone(&handler_calls);
+    let repository = InMemoryRepository::new();
+    let service = Service::new().named("causal-tests").routes(
+        Routes::new()
+            .with_repo(repository.clone().aggregate::<CausalDispatcherAggregate>())
+            .typed_command(typed_command::<CausalTestInput, Accepted<TypedOutput>>(
+                "causal.replay",
+            ))
+            .handle(
+                move |_context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                      input: CausalTestInput| {
+                    let calls = Arc::clone(&route_handler_calls);
+                    async move {
+                        calls.fetch_add(1, Ordering::SeqCst);
+                        let _label = input.label;
+                        Ok(
+                            PreparedCommand::<Accepted<TypedOutput>>::prepare(TypedOutput {
+                                id: input.id,
+                            })
+                            .unwrap(),
+                        )
+                    }
+                },
+            ),
+    );
+    let command_id = causal_test_command_id();
+    let principal = causal_test_principal();
+    let first_input = serde_json::from_str(r#"{"id":"todo-1","label":"same"}"#).unwrap();
+    let equivalent_input = serde_json::from_str(r#"{"label":"same","id":"todo-1"}"#).unwrap();
+
+    let first = service
+        .dispatch_causal(
+            "causal.replay",
+            &command_id,
+            first_input,
+            Session::new(),
+            principal.clone(),
+        )
+        .await
+        .unwrap();
+    let replay = service
+        .dispatch_causal(
+            "causal.replay",
+            &command_id,
+            equivalent_input,
+            Session::new(),
+            principal,
+        )
+        .await
+        .unwrap();
+
+    assert_eq!(first, json!({ "id": "todo-1" }));
+    assert_eq!(replay, first);
+    assert_eq!(handler_calls.load(Ordering::SeqCst), 1);
+}
+
+#[cfg(feature = "graphql")]
+#[tokio::test]
+async fn causal_dispatch_receipt_and_status_use_the_exact_durable_replay() {
+    let handler_calls = Arc::new(AtomicUsize::new(0));
+    let route_handler_calls = Arc::clone(&handler_calls);
+    let service = Service::new().named("causal-tests").routes(
+        Routes::new()
+            .with_repo(InMemoryRepository::new().aggregate::<CausalDispatcherAggregate>())
+            .typed_command(typed_command::<CausalTestInput, Accepted<TypedOutput>>(
+                "causal.receipt",
+            ))
+            .handle(
+                move |_context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                      input: CausalTestInput| {
+                    let calls = Arc::clone(&route_handler_calls);
+                    async move {
+                        calls.fetch_add(1, Ordering::SeqCst);
+                        Ok(
+                            PreparedCommand::<Accepted<TypedOutput>>::prepare(TypedOutput {
+                                id: input.id,
+                            })
+                            .unwrap(),
+                        )
+                    }
+                },
+            ),
+    );
+    let command_id = causal_test_command_id();
+    let principal = causal_test_principal();
+
+    let first = service
+        .dispatch_causal_with_receipt(
+            "causal.receipt",
+            &command_id,
+            causal_test_input("todo-receipt", "first"),
+            Session::new(),
+            principal.clone(),
+        )
+        .await
+        .expect("fresh dispatch should return its durable receipt source");
+    let replay = service
+        .dispatch_causal_with_receipt(
+            "causal.receipt",
+            &command_id,
+            causal_test_input("todo-receipt", "first"),
+            Session::new(),
+            principal.clone(),
+        )
+        .await
+        .expect("response-loss retry should recover the same receipt source");
+
+    assert_eq!(first, replay);
+    assert_eq!(first.payload, json!({ "id": "todo-receipt" }));
+    assert_eq!(first.receipt.command_id, command_id);
+    assert_eq!(first.receipt.state, CommandLedgerState::Accepted);
+    assert_eq!(first.receipt.consistency, CommandConsistency::Accepted);
+    assert!(first.receipt.obligations.is_empty());
+    assert!(first.receipt.direct_projection.is_none());
+    assert_eq!(handler_calls.load(Ordering::SeqCst), 1);
+
+    let status = service
+        .causal_command_status(&command_id, &Session::new(), principal)
+        .await
+        .expect("same principal and current grant should resolve status");
+    assert_eq!(status.state, CausalCommandPublicState::Accepted);
+    assert_eq!(status.command_id, first.receipt.command_id);
+    assert_eq!(
+        status.causation_id.as_deref(),
+        Some(first.receipt.causation_id.as_str())
+    );
+    assert_eq!(status.consistency, Some(CommandConsistency::Accepted));
+    assert_eq!(status.outcome, Some(first.payload));
+    assert!(status.obligations.is_empty());
+    assert!(status.evidence.is_empty());
+    assert!(status.direct_projection.is_none());
+}
+
+#[cfg(feature = "graphql")]
+#[test]
+fn causal_status_projection_failure_precedes_observed_and_pending_evidence() {
+    let item = |obligation_index, state| CausalCommandProjectionEvidence {
+        obligation_index,
+        state,
+        incarnation: (state == CausalProjectionEvidenceState::Observed).then_some(1),
+        revision: (state == CausalProjectionEvidenceState::Observed).then_some(2),
+    };
+
+    assert_eq!(
+        collapse_projection_evidence(&[
+            item(0, CausalProjectionEvidenceState::Observed),
+            item(1, CausalProjectionEvidenceState::TerminalFailure),
+            item(2, CausalProjectionEvidenceState::Pending),
+        ]),
+        CausalCommandPublicState::ProjectionFailed
+    );
+    assert_eq!(
+        collapse_projection_evidence(&[
+            item(0, CausalProjectionEvidenceState::Observed),
+            item(1, CausalProjectionEvidenceState::Observed),
+        ]),
+        CausalCommandPublicState::Projected
+    );
+    assert_eq!(
+        collapse_projection_evidence(&[
+            item(0, CausalProjectionEvidenceState::Observed),
+            item(1, CausalProjectionEvidenceState::Pending),
+        ]),
+        CausalCommandPublicState::AcceptedPendingProjection
+    );
+    assert_eq!(
+        collapse_projection_evidence(&[]),
+        CausalCommandPublicState::AcceptedPendingProjection
+    );
+}
+
+#[cfg(feature = "graphql")]
+#[tokio::test]
+async fn causal_dispatch_rejects_same_command_id_with_different_input() {
+    let handler_calls = Arc::new(AtomicUsize::new(0));
+    let route_handler_calls = Arc::clone(&handler_calls);
+    let repository = InMemoryRepository::new();
+    let service = Service::new().named("causal-tests").routes(
+        Routes::new()
+            .with_repo(repository.clone().aggregate::<CausalDispatcherAggregate>())
+            .typed_command(typed_command::<CausalTestInput, Accepted<TypedOutput>>(
+                "causal.reuse",
+            ))
+            .handle(
+                move |_context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                      input: CausalTestInput| {
+                    let calls = Arc::clone(&route_handler_calls);
+                    async move {
+                        calls.fetch_add(1, Ordering::SeqCst);
+                        let _label = input.label;
+                        Ok(
+                            PreparedCommand::<Accepted<TypedOutput>>::prepare(TypedOutput {
+                                id: input.id,
+                            })
+                            .unwrap(),
+                        )
+                    }
+                },
+            ),
+    );
+    let command_id = causal_test_command_id();
+    let principal = causal_test_principal();
+
+    service
+        .dispatch_causal(
+            "causal.reuse",
+            &command_id,
+            causal_test_input("todo-1", "first"),
+            Session::new(),
+            principal.clone(),
+        )
+        .await
+        .unwrap();
+    let error = service
+        .dispatch_causal(
+            "causal.reuse",
+            &command_id,
+            causal_test_input("todo-1", "changed"),
+            Session::new(),
+            principal,
+        )
+        .await
+        .expect_err("different canonical input must conflict");
+
+    assert_eq!(error.code(), "COMMAND_ID_REUSE");
+    assert_eq!(error.status_code(), 409);
+    assert_eq!(handler_calls.load(Ordering::SeqCst), 1);
+}
+
+#[cfg(feature = "graphql")]
+#[tokio::test]
+async fn causal_guard_rejection_is_replayed_without_guard_or_handler_callback() {
+    let guard_calls = Arc::new(AtomicUsize::new(0));
+    let handler_calls = Arc::new(AtomicUsize::new(0));
+    let route_guard_calls = Arc::clone(&guard_calls);
+    let route_handler_calls = Arc::clone(&handler_calls);
+    let repository = InMemoryRepository::new();
+    let service = Service::new().named("causal-tests").routes(
+        Routes::new()
+            .with_repo(repository.clone().aggregate::<CausalDispatcherAggregate>())
+            .typed_command(typed_command::<CausalTestInput, Accepted<TypedOutput>>(
+                "causal.guard_rejection",
+            ))
+            .guarded(
+                move |_| {
+                    route_guard_calls.fetch_add(1, Ordering::SeqCst);
+                    false
+                },
+                move |_context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                      input: CausalTestInput| {
+                    let calls = Arc::clone(&route_handler_calls);
+                    async move {
+                        calls.fetch_add(1, Ordering::SeqCst);
+                        Ok(
+                            PreparedCommand::<Accepted<TypedOutput>>::prepare(TypedOutput {
+                                id: input.id,
+                            })
+                            .unwrap(),
+                        )
+                    }
+                },
+            ),
+    );
+    let command_id = causal_test_command_id();
+    let principal = causal_test_principal();
+
+    let first = service
+        .dispatch_causal(
+            "causal.guard_rejection",
+            &command_id,
+            causal_test_input("todo-1", "same"),
+            Session::new(),
+            principal.clone(),
+        )
+        .await
+        .expect_err("guard should reject first attempt");
+    let replay = service
+        .dispatch_causal(
+            "causal.guard_rejection",
+            &command_id,
+            causal_test_input("todo-1", "same"),
+            Session::new(),
+            principal,
+        )
+        .await
+        .expect_err("guard rejection should replay");
+
+    assert_eq!(first.code(), "REJECTED");
+    assert_eq!(first.status_code(), 422);
+    assert_eq!(replay.code(), first.code());
+    assert_eq!(replay.status_code(), first.status_code());
+    assert_eq!(replay.client_message(), first.client_message());
+    assert_eq!(guard_calls.load(Ordering::SeqCst), 1);
+    assert_eq!(handler_calls.load(Ordering::SeqCst), 0);
+}
+
+#[cfg(feature = "graphql")]
+#[tokio::test]
+async fn causal_handler_rejection_is_replayed_without_reinvoking_handler() {
+    let handler_calls = Arc::new(AtomicUsize::new(0));
+    let route_handler_calls = Arc::clone(&handler_calls);
+    let repository = InMemoryRepository::new();
+    let service = Service::new().named("causal-tests").routes(
+        Routes::new()
+            .with_repo(repository.clone().aggregate::<CausalDispatcherAggregate>())
+            .typed_command(typed_command::<CausalTestInput, Accepted<TypedOutput>>(
+                "causal.handler_rejection",
+            ))
+            .handle(
+                move |_context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                      _input: CausalTestInput| {
+                    let calls = Arc::clone(&route_handler_calls);
+                    async move {
+                        calls.fetch_add(1, Ordering::SeqCst);
+                        Err::<PreparedCommand<Accepted<TypedOutput>>, HandlerError>(
+                            HandlerError::Rejected("deterministic refusal".into()),
+                        )
+                    }
+                },
+            ),
+    );
+    let command_id = causal_test_command_id();
+    let principal = causal_test_principal();
+
+    let first = service
+        .dispatch_causal(
+            "causal.handler_rejection",
+            &command_id,
+            causal_test_input("todo-1", "same"),
+            Session::new(),
+            principal.clone(),
+        )
+        .await
+        .expect_err("handler should reject first attempt");
+    let replay = service
+        .dispatch_causal(
+            "causal.handler_rejection",
+            &command_id,
+            causal_test_input("todo-1", "same"),
+            Session::new(),
+            principal,
+        )
+        .await
+        .expect_err("handler rejection should replay");
+
+    assert_eq!(first.code(), "REJECTED");
+    assert_eq!(first.status_code(), 422);
+    assert_eq!(first.client_message(), "rejected: deterministic refusal");
+    assert_eq!(replay.code(), first.code());
+    assert_eq!(replay.status_code(), first.status_code());
+    assert_eq!(replay.client_message(), first.client_message());
+    assert_eq!(handler_calls.load(Ordering::SeqCst), 1);
+}
+
+#[cfg(feature = "graphql")]
+#[tokio::test]
+async fn causal_dispatch_checks_current_role_before_reservation_guard_and_handler() {
+    let guard_calls = Arc::new(AtomicUsize::new(0));
+    let handler_calls = Arc::new(AtomicUsize::new(0));
+    let route_guard_calls = Arc::clone(&guard_calls);
+    let route_handler_calls = Arc::clone(&handler_calls);
+    let repository = InMemoryRepository::new();
+    let service = Service::new().named("causal-tests").routes(
+        Routes::new()
+            .with_repo(repository.clone().aggregate::<CausalDispatcherAggregate>())
+            .typed_command(
+                typed_command::<CausalTestInput, Accepted<TypedOutput>>("causal.role_guarded")
+                    .roles(["admin"]),
+            )
+            .guarded(
+                move |_| {
+                    route_guard_calls.fetch_add(1, Ordering::SeqCst);
+                    true
+                },
+                move |_context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                      input: CausalTestInput| {
+                    let calls = Arc::clone(&route_handler_calls);
+                    async move {
+                        calls.fetch_add(1, Ordering::SeqCst);
+                        Ok(
+                            PreparedCommand::<Accepted<TypedOutput>>::prepare(TypedOutput {
+                                id: input.id,
+                            })
+                            .unwrap(),
+                        )
+                    }
+                },
+            ),
+    );
+    let command_id = causal_test_command_id();
+    let principal = causal_test_principal();
+
+    let denied_before_reservation = service
+        .dispatch_causal(
+            "causal.role_guarded",
+            &command_id,
+            causal_test_input("todo-1", "same"),
+            session_with_role("user"),
+            principal.clone(),
+        )
+        .await
+        .expect_err("current role must be denied before reservation");
+    assert_eq!(denied_before_reservation.code(), "FORBIDDEN");
+    assert_eq!(guard_calls.load(Ordering::SeqCst), 0);
+    assert_eq!(handler_calls.load(Ordering::SeqCst), 0);
+
+    let accepted = service
+        .dispatch_causal(
+            "causal.role_guarded",
+            &command_id,
+            causal_test_input("todo-1", "same"),
+            session_with_role("admin"),
+            principal.clone(),
+        )
+        .await
+        .expect("denied dispatch must not have reserved the command ID");
+    assert_eq!(accepted, json!({ "id": "todo-1" }));
+
+    let denied_before_replay = service
+        .dispatch_causal(
+            "causal.role_guarded",
+            &command_id,
+            causal_test_input("todo-1", "same"),
+            session_with_role("user"),
+            principal,
+        )
+        .await
+        .expect_err("current role must be rechecked before replay");
+    assert_eq!(denied_before_replay.code(), "FORBIDDEN");
+    assert_eq!(guard_calls.load(Ordering::SeqCst), 1);
+    assert_eq!(handler_calls.load(Ordering::SeqCst), 1);
+
+    let denied_lookup = service
+        .lookup_causal_command(
+            "causal.role_guarded",
+            &command_id,
+            &session_with_role("user"),
+            causal_test_principal(),
+        )
+        .await
+        .expect_err("current role must also be rechecked before status lookup");
+    assert_eq!(denied_lookup.code(), "FORBIDDEN");
+}
+
+#[cfg(feature = "graphql")]
+#[tokio::test]
+async fn causal_status_lookup_does_not_disclose_another_routes_command() {
+    let repository = InMemoryRepository::new();
+    let service = Service::new().named("causal-tests").routes(
+        Routes::new()
+            .with_repo(repository.aggregate::<CausalDispatcherAggregate>())
+            .typed_command(
+                typed_command::<CausalTestInput, Accepted<TypedOutput>>("causal.admin_only")
+                    .roles(["admin"]),
+            )
+            .handle(
+                |_context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                 input: CausalTestInput| async move {
+                    Ok(
+                        PreparedCommand::<Accepted<TypedOutput>>::prepare(TypedOutput {
+                            id: input.id,
+                        })
+                        .unwrap(),
+                    )
+                },
+            )
+            .typed_command(
+                typed_command::<CausalTestInput, Accepted<TypedOutput>>("causal.user_allowed")
+                    .roles(["user"]),
+            )
+            .handle(
+                |_context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                 input: CausalTestInput| async move {
+                    Ok(
+                        PreparedCommand::<Accepted<TypedOutput>>::prepare(TypedOutput {
+                            id: input.id,
+                        })
+                        .unwrap(),
+                    )
+                },
+            ),
+    );
+    let command_id = causal_test_command_id();
+    let principal = causal_test_principal();
+
+    service
+        .dispatch_causal(
+            "causal.admin_only",
+            &command_id,
+            causal_test_input("todo-secret", "classified"),
+            session_with_role("admin"),
+            principal.clone(),
+        )
+        .await
+        .expect("admin should be able to commit the protected command");
+
+    let denied = service
+        .lookup_causal_command(
+            "causal.admin_only",
+            &command_id,
+            &session_with_role("user"),
+            principal.clone(),
+        )
+        .await
+        .expect_err("the current role must not retain access to the protected route");
+    assert_eq!(denied.code(), "FORBIDDEN");
+
+    let cross_route = service
+        .lookup_causal_command(
+            "causal.user_allowed",
+            &command_id,
+            &session_with_role("user"),
+            principal.clone(),
+        )
+        .await
+        .expect("the allowed route should produce a non-disclosing status result");
+    assert_eq!(cross_route, CommandLookup::Unknown);
+
+    let authorized = service
+        .causal_command_status(&command_id, &session_with_role("admin"), principal.clone())
+        .await
+        .expect("current admin grant should recover the command without its route name");
+    assert_eq!(authorized.state, CausalCommandPublicState::Accepted);
+    assert_eq!(authorized.command_id, command_id);
+
+    let revoked = service
+        .causal_command_status(&command_id, &session_with_role("user"), principal.clone())
+        .await
+        .expect("revoked routes must collapse to a non-enumerating status");
+    assert_eq!(revoked.state, CausalCommandPublicState::Unknown);
+
+    let other_principal = VerifiedPrincipal::test_oidc(
+        "https://issuer.example/",
+        "another-subject",
+        &["distributed-tests"],
+    );
+    let wrong_principal = service
+        .causal_command_status(&command_id, &session_with_role("admin"), other_principal)
+        .await
+        .expect("another principal must not learn whether the command exists");
+    assert_eq!(wrong_principal.state, CausalCommandPublicState::Unknown);
+
+    let malformed = service
+        .causal_command_status(
+            "not-a-command-id",
+            &session_with_role("admin"),
+            principal.clone(),
+        )
+        .await
+        .expect("malformed IDs are non-enumerating, not validation or storage errors");
+    assert_eq!(malformed.state, CausalCommandPublicState::Unknown);
+    assert_eq!(malformed.command_id, "not-a-command-id");
+
+    let missing_id = causal_test_command_id();
+    let missing = service
+        .causal_command_status(&missing_id, &session_with_role("admin"), principal)
+        .await
+        .expect("absent IDs are non-enumerating");
+    assert_eq!(missing.state, CausalCommandPublicState::Unknown);
+}
+
+#[cfg(feature = "graphql")]
+#[tokio::test]
+async fn causal_dispatch_overwrites_event_and_outbox_causation_with_ledger_identity() {
+    let observed_causation = Arc::new(Mutex::new(None::<String>));
+    let route_observed_causation = Arc::clone(&observed_causation);
+    let projector_causation = Arc::new(Mutex::new(None::<String>));
+    let route_projector_causation = Arc::clone(&projector_causation);
+    let repository = InMemoryRepository::new();
+    let service = Service::new().named("causal-tests").routes(
+        Routes::new()
+            .with_repo(repository.clone().aggregate::<CausalDispatcherAggregate>())
+            .typed_command(typed_command::<CausalTestInput, Accepted<TypedOutput>>(
+                "causal.persist",
+            ))
+            .handle(
+                move |context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                      input: CausalTestInput| {
+                    let observed = Arc::clone(&route_observed_causation);
+                    let result = (|| {
+                        let causation = context
+                            .causation_id()
+                            .expect("reserved command causation")
+                            .to_string();
+                        *observed.lock().unwrap() = Some(causation);
+
+                        let mut checkout = context.create();
+                        checkout
+                            .entity_mut()
+                            .set_causation_id("handler-supplied-event-causation");
+                        checkout
+                            .record(input.id.clone())
+                            .map_err(|error| HandlerError::Other(Box::new(error)))?;
+                        context.stage(checkout)?;
+
+                        let mut outbox = OutboxMessage::create(
+                            format!("{}:fact", input.id),
+                            "causal.recorded",
+                            input.label.as_bytes().to_vec(),
+                        )
+                        .map_err(|error| HandlerError::Other(Box::new(error)))?;
+                        outbox.set_causation_id("handler-supplied-outbox-causation");
+                        context.stage_outbox(outbox)?;
+
+                        Ok(
+                            PreparedCommand::<Accepted<TypedOutput>>::prepare(TypedOutput {
+                                id: input.id,
+                            })
+                            .unwrap(),
+                        )
+                    })();
+                    async move { result }
+                },
+            )
+            .event("causal.recorded")
+            .handle(
+                move |context: &Context<
+                    AggregateRepository<InMemoryRepository, CausalDispatcherAggregate>,
+                >| {
+                    let causation = context.message().causation_id().map(str::to_string);
+                    let observed = Arc::clone(&route_projector_causation);
+                    async move {
+                        *observed.lock().unwrap() = causation;
+                        Ok(json!({ "projected": true }))
+                    }
+                },
+            ),
+    );
+    let command_id = causal_test_command_id();
+    let mut session = Session::new();
+    session.set(
+        crate::trace_context::CAUSATION_ID,
+        "caller-supplied-causation",
+    );
+    session.set(crate::trace_context::CORRELATION_ID, "caller-correlation");
+    session.set(
+        crate::trace_context::TRACEPARENT,
+        "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+    );
+    session.set(crate::trace_context::TRACESTATE, "vendor=value");
+
+    let result = service
+        .dispatch_causal(
+            "causal.persist",
+            &command_id,
+            causal_test_input("todo-causal", "payload"),
+            session,
+            causal_test_principal(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(result, json!({ "id": "todo-causal" }));
+
+    let causation = observed_causation
+        .lock()
+        .unwrap()
+        .clone()
+        .expect("handler observed causation");
+    let parsed_causation = uuid::Uuid::parse_str(&causation).unwrap();
+    assert_eq!(parsed_causation.get_version_num(), 7);
+    assert_ne!(causation, command_id);
+    assert_ne!(causation, "caller-supplied-causation");
+    assert_ne!(causation, "handler-supplied-event-causation");
+    assert_ne!(causation, "handler-supplied-outbox-causation");
+
+    let identity =
+        crate::StreamIdentity::new(CausalDispatcherAggregate::aggregate_type(), "todo-causal")
+            .unwrap();
+    let stored = repository
+        .get_stream(&identity)
+        .await
+        .unwrap()
+        .expect("causal aggregate stream");
+    assert_eq!(stored.events().len(), 1);
+    assert_eq!(stored.events()[0].causation_id(), Some(causation.as_str()));
+
+    let outbox_store = repository.outbox_store();
+    let pending = outbox_store.pending(10).await.unwrap();
+    assert_eq!(pending.len(), 1);
+    assert_eq!(pending[0].causation_id(), Some(causation.as_str()));
+
+    let projector_input = Message::from(pending[0].clone());
+    service.dispatch_message(&projector_input).await.unwrap();
+    assert_eq!(
+        projector_causation.lock().unwrap().as_deref(),
+        Some(causation.as_str())
+    );
+}
+
+#[cfg(feature = "graphql")]
+#[tokio::test]
+async fn causal_dispatch_uses_the_configured_immediate_outbox_publisher() {
+    let repository = InMemoryRepository::new();
+    let observed_broker_metadata = Arc::new(Mutex::new(None::<[String; 4]>));
+    let route_observed_broker_metadata = Arc::clone(&observed_broker_metadata);
+    let service = Service::new()
+        .named("causal-tests")
+        .routes(
+            Routes::new()
+                .with_repo(repository.clone().aggregate::<CausalDispatcherAggregate>())
+                .typed_command(typed_command::<CausalTestInput, Accepted<TypedOutput>>(
+                    "causal.publish_immediately",
+                ))
+                .handle(
+                    |context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                     input: CausalTestInput| {
+                        let result = (|| {
+                            let mut checkout = context.create();
+                            checkout
+                                .record(input.id.clone())
+                                .map_err(|error| HandlerError::Other(Box::new(error)))?;
+                            context.stage(checkout)?;
+                            context.stage_outbox(
+                                OutboxMessage::create(
+                                    format!("{}:immediate-fact", input.id),
+                                    "causal.immediate_fact",
+                                    input.label.as_bytes().to_vec(),
+                                )
+                                .map_err(|error| HandlerError::Other(Box::new(error)))?,
+                            )?;
+                            Ok(
+                                PreparedCommand::<Accepted<TypedOutput>>::prepare(TypedOutput {
+                                    id: input.id,
+                                })
+                                .unwrap(),
+                            )
+                        })();
+                        async move { result }
+                    },
+                )
+                .event("causal.immediate_fact")
+                .handle(
+                    move |context: &Context<
+                        AggregateRepository<InMemoryRepository, CausalDispatcherAggregate>,
+                    >| {
+                        let message = context.message();
+                        let metadata = [
+                            message.causation_id().unwrap_or_default().to_string(),
+                            message
+                                .metadata("x-sourced-source-aggregate-type")
+                                .unwrap_or_default()
+                                .to_string(),
+                            message
+                                .metadata("x-sourced-source-aggregate-id")
+                                .unwrap_or_default()
+                                .to_string(),
+                            message
+                                .metadata("x-sourced-source-sequence")
+                                .unwrap_or_default()
+                                .to_string(),
+                        ];
+                        let observed = Arc::clone(&route_observed_broker_metadata);
+                        async move {
+                            *observed.lock().unwrap() = Some(metadata);
+                            Ok(json!({ "projected": true }))
+                        }
+                    },
+                ),
+        )
+        .with_bus(crate::bus::InMemoryBus::new());
+
+    service
+        .dispatch_causal(
+            "causal.publish_immediately",
+            &causal_test_command_id(),
+            causal_test_input("todo-immediate", "payload"),
+            Session::new(),
+            causal_test_principal(),
+        )
+        .await
+        .expect("causal dispatch should commit before immediate publication");
+
+    let outbox = repository.outbox_store();
+    assert!(outbox.pending(usize::MAX).await.unwrap().is_empty());
+    let published = outbox
+        .messages_by_status(crate::outbox::OutboxMessageStatus::Published, usize::MAX)
+        .await
+        .unwrap();
+    assert_eq!(published.len(), 1);
+    assert_eq!(published[0].id(), "todo-immediate:immediate-fact");
+    assert_eq!(published[0].event_type, "causal.immediate_fact");
+    let causation = published[0]
+        .causation_id()
+        .expect("persisted outbox row should retain ledger causation")
+        .to_string();
+    assert_eq!(
+        published[0].source_aggregate_type.as_deref(),
+        Some(CausalDispatcherAggregate::aggregate_type())
+    );
+    assert_eq!(
+        published[0].source_aggregate_id.as_deref(),
+        Some("todo-immediate")
+    );
+    assert_eq!(published[0].source_sequence, Some(1));
+
+    service
+        .run(RunOptions::idempotent())
+        .await
+        .expect("attached bus should deliver the immediately published fact");
+    assert_eq!(
+        observed_broker_metadata.lock().unwrap().as_ref(),
+        Some(&[
+            causation,
+            CausalDispatcherAggregate::aggregate_type().to_string(),
+            "todo-immediate".to_string(),
+            "1".to_string(),
+        ]),
+        "the post-commit clone must carry authoritative causation and aggregate source metadata",
+    );
+}
+
+#[cfg(all(feature = "graphql", feature = "sqlite"))]
+#[tokio::test]
+async fn causal_dispatch_replay_contains_resolved_projection_obligation() {
+    let repository = crate::SqliteRepository::connect_and_migrate("sqlite::memory:")
+        .await
+        .expect("framework migrations should apply");
+    let projector = SurfaceProjector::new("project_causal_obligation")
+        .facts(["causal.obligation_fact"])
+        .models(["CausalProjectionObligationView"])
+        .partition_by(["tenantPartition"]);
+    let confirmations = crate::command_confirmations! {
+        input: CausalProjectionInput;
+        confirm projector -> CausalProjectionObligationView {
+            key { id: input.id },
+            partition: input.partition
+        };
+    };
+    let service = Service::new().named("causal-tests").routes(
+        Routes::new()
+            .with_repo(repository.clone().aggregate::<CausalDispatcherAggregate>())
+            .typed_command(
+                typed_command::<CausalProjectionInput, Accepted<TypedOutput>>(
+                    "causal.projection_obligation",
+                )
+                .confirmations(confirmations),
+            )
+            .handle(
+                |context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                 input: CausalProjectionInput| {
+                    let result = (|| {
+                        context.stage_outbox(
+                            OutboxMessage::create(
+                                format!("{}:obligation", input.id),
+                                "causal.obligation_fact",
+                                serde_json::to_vec(&json!({
+                                    "tenantPartition": input.partition
+                                }))
+                                .map_err(|error| HandlerError::Other(Box::new(error)))?,
+                            )
+                            .map_err(|error| HandlerError::Other(Box::new(error)))?,
+                        )?;
+                        Ok(
+                            PreparedCommand::<Accepted<TypedOutput>>::prepare(TypedOutput {
+                                id: input.id,
+                            })
+                            .unwrap(),
+                        )
+                    })();
+                    async move { result }
+                },
+            ),
+    );
+    let engine = crate::graphql::GraphqlEngine::builder(&repository)
+        .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+        .model::<CausalProjectionObligationView>(
+            crate::graphql::ModelPermissions::new()
+                .grant("anonymous", crate::graphql::read().all_columns()),
+        )
+        .service(&service)
+        .client_projectors([projector])
+        .build()
+        .expect("the public GraphQL binding path should compile projector topology");
+    let service = service
+        .try_with_graphql(engine)
+        .expect("compiled projector topology should bind to the executable service");
+    let command_id = causal_test_command_id();
+    let principal = causal_test_principal();
+
+    let result = service
+        .dispatch_causal(
+            "causal.projection_obligation",
+            &command_id,
+            json!({
+                "todoId": "todo-obligation",
+                "tenantPartition": "tenant-a"
+            }),
+            Session::new(),
+            principal.clone(),
+        )
+        .await
+        .expect("matching outbox fact should make the causal dispatch commit");
+    assert_eq!(result, json!({ "id": "todo-obligation" }));
+
+    let status = service
+        .causal_command_status(&command_id, &Session::new(), principal.clone())
+        .await
+        .expect("status should evaluate the stored finite obligation batch");
+    assert_eq!(
+        status.state,
+        CausalCommandPublicState::AcceptedPendingProjection
+    );
+    assert_eq!(status.consistency, Some(CommandConsistency::Accepted));
+    assert_eq!(status.obligations.len(), 1);
+    assert_eq!(status.obligations[0].projector, "project_causal_obligation");
+    assert_eq!(status.evidence.len(), 1);
+    assert_eq!(
+        status.evidence[0].state,
+        CausalProjectionEvidenceState::Pending
+    );
+    assert_eq!(status.evidence[0].obligation_index, 0);
+    assert_eq!(status.evidence[0].incarnation, None);
+    assert_eq!(status.evidence[0].revision, None);
+
+    let lookup = service
+        .lookup_causal_command(
+            "causal.projection_obligation",
+            &command_id,
+            &Session::new(),
+            principal,
+        )
+        .await
+        .expect("same principal should be able to recover its command");
+    let CommandLookup::Replay(replay) = lookup else {
+        panic!("completed command should be replayable");
+    };
+    assert_eq!(replay.state, CommandLedgerState::AcceptedPendingProjection);
+    assert_eq!(replay.projection_obligations.len(), 1);
+
+    let obligation = &replay.projection_obligations[0];
+    assert_eq!(obligation.projector, "project_causal_obligation");
+    assert_eq!(obligation.model, "CausalProjectionObligationView");
+    assert_eq!(obligation.key.fields.len(), 1);
+    assert_eq!(obligation.key.fields[0].field, "id");
+    assert_eq!(obligation.key.fields[0].value, json!("todo-obligation"));
+    assert_eq!(obligation.partition, Some(json!("tenant-a")));
+
+    let pending = repository.outbox_store().pending(10).await.unwrap();
+    assert_eq!(pending.len(), 1);
+    assert_eq!(pending[0].event_type, "causal.obligation_fact");
+}
+
+#[cfg(all(feature = "graphql", feature = "sqlite"))]
+#[tokio::test]
+async fn projected_command_auto_binds_bootstraps_and_replays_exact_direct_evidence() {
+    let repository = crate::SqliteRepository::connect_and_migrate("sqlite::memory:")
+        .await
+        .expect("framework migrations should apply");
+    let mut registry = crate::TableSchemaRegistry::new();
+    registry
+        .register::<CausalProjectionObligationView>()
+        .unwrap()
+        .register::<CausalProjectionSiblingView>()
+        .unwrap();
+    for statement in
+        crate::table::table_schema_statements(&registry, crate::table::TableSqlDialect::Sqlite)
+            .unwrap()
+    {
+        sqlx::query(crate::sqlx_repo::audited_table_schema_sql(statement))
+            .execute(repository.pool())
+            .await
+            .expect("test read-model schema should apply");
+    }
+
+    let handler_calls = Arc::new(AtomicUsize::new(0));
+    let route_handler_calls = Arc::clone(&handler_calls);
+    let service = Service::new().named("causal-direct").routes(
+        Routes::new()
+            .with_repo(repository.clone().aggregate::<CausalDispatcherAggregate>())
+            // No direct-target/cache/projection call is present: the
+            // `Projected<M>` output and Surface owner are the complete
+            // declaration.
+            .typed_command(typed_command::<
+                CausalProjectionInput,
+                Projected<CausalProjectionObligationView>,
+            >("causal.direct"))
+            .handle(
+                move |context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                      input: CausalProjectionInput| {
+                    let calls = Arc::clone(&route_handler_calls);
+                    let result = (|| {
+                        calls.fetch_add(1, Ordering::SeqCst);
+                        let mut checkout = context.create();
+                        checkout
+                            .record(input.id.clone())
+                            .map_err(|error| HandlerError::Other(Box::new(error)))?;
+                        context.stage(checkout)?;
+                        context.projected(CausalProjectionObligationView { id: input.id })
+                    })();
+                    async move { result }
+                },
+            ),
+    );
+    let projection = SurfaceDirectProjection::new("project_causal_direct")
+        .model::<CausalProjectionObligationView>()
+        .model::<CausalProjectionSiblingView>()
+        .change_epoch("causal-direct-v1");
+    let engine = crate::graphql::GraphqlEngine::builder(&repository)
+        .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+        .model::<CausalProjectionObligationView>(
+            crate::graphql::ModelPermissions::new()
+                .grant("anonymous", crate::graphql::read().all_columns()),
+        )
+        .model::<CausalProjectionSiblingView>(
+            crate::graphql::ModelPermissions::new()
+                .grant("anonymous", crate::graphql::read().all_columns()),
+        )
+        .service(&service)
+        .client_projection_owners([projection.into()])
+        .build()
+        .expect("ordinary Projected<M> declaration should auto-bind its unique owner");
+    let service = service
+        .try_with_graphql(engine)
+        .expect("bound direct target should attach to its executable route");
+    let contract = &service.typed_command_contracts()[0];
+    let target = contract
+        .direct_projection
+        .as_ref()
+        .expect("engine binding must populate the private direct target");
+    assert_eq!(target.projector, "project_causal_direct");
+    assert_eq!(
+        target.ownership.len(),
+        2,
+        "one direct route must freeze its owner's complete model inventory"
+    );
+    assert!(target.partition.is_none(), "zero-config partition is unit");
+
+    let command_id = causal_test_command_id();
+    let input = json!({
+        "todoId": "todo-direct",
+        "tenantPartition": "not-manual-projection-config"
+    });
+    let first = service
+        .dispatch_causal(
+            "causal.direct",
+            &command_id,
+            input.clone(),
+            Session::new(),
+            causal_test_principal(),
+        )
+        .await
+        .expect("direct command should atomically commit");
+    assert_eq!(first, json!({ "id": "todo-direct" }));
+    assert_eq!(handler_calls.load(Ordering::SeqCst), 1);
+
+    let direct_status = service
+        .causal_command_status(&command_id, &Session::new(), causal_test_principal())
+        .await
+        .expect("direct projected status should use ledger replay evidence");
+    assert_eq!(direct_status.state, CausalCommandPublicState::Projected);
+    assert_eq!(
+        direct_status.consistency,
+        Some(CommandConsistency::Projected)
+    );
+    assert!(direct_status.obligations.is_empty());
+    assert!(direct_status.evidence.is_empty());
+    let direct_status_evidence = direct_status
+        .direct_projection
+        .expect("direct status must retain the exact same-attempt evidence");
+
+    let stored_id: String =
+        sqlx::query_scalar("SELECT id FROM causal_projection_obligation_views WHERE id = ?")
+            .bind("todo-direct")
+            .fetch_one(repository.pool())
+            .await
+            .expect("returned row should be visible through the GraphQL read database");
+    assert_eq!(stored_id, "todo-direct");
+    let registered: i64 = sqlx::query_scalar(
+        "SELECT COUNT(*) FROM projection_registered_models WHERE model_name IN \
+             ('CausalProjectionObligationView', 'CausalProjectionSiblingView')",
+    )
+    .fetch_one(repository.pool())
+    .await
+    .unwrap();
+    assert_eq!(
+        registered, 2,
+        "lazy bootstrap must atomically register the owner's full inventory"
+    );
+    let sibling_rows: i64 =
+        sqlx::query_scalar("SELECT COUNT(*) FROM causal_projection_sibling_views")
+            .fetch_one(repository.pool())
+            .await
+            .unwrap();
+    assert_eq!(
+        sibling_rows, 0,
+        "the direct participant must mutate only its returned output model"
+    );
+
+    let lookup = service
+        .lookup_causal_command(
+            "causal.direct",
+            &command_id,
+            &Session::new(),
+            causal_test_principal(),
+        )
+        .await
+        .unwrap();
+    let CommandLookup::Replay(first_replay) = lookup else {
+        panic!("projected command should be terminally replayable");
+    };
+    assert_eq!(first_replay.state, CommandLedgerState::Projected);
+    let evidence = first_replay
+        .direct_projection
+        .clone()
+        .expect("replay must retain exact direct evidence");
+    crate::projection_protocol::SameTransactionProjectionEvidence::validate_replay_value(&evidence)
+        .unwrap();
+    assert_eq!(direct_status_evidence.replay_value(), evidence);
+    assert_eq!(evidence["records"].as_array().unwrap().len(), 1);
+    assert_eq!(evidence["changes"].as_array().unwrap().len(), 1);
+    assert_eq!(evidence["observations"].as_array().unwrap().len(), 1);
+    let async_input_rows: i64 = sqlx::query_scalar(
+        "SELECT \
+             (SELECT COUNT(*) FROM projection_input_identities) + \
+             (SELECT COUNT(*) FROM projection_input_cursors) + \
+             (SELECT COUNT(*) FROM projection_input_receipts)",
+    )
+    .fetch_one(repository.pool())
+    .await
+    .unwrap();
+    assert_eq!(
+        async_input_rows, 0,
+        "a direct-only projection must not create async input identities, cursors, or receipts"
+    );
+    let outbox_rows: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM outbox_messages")
+        .fetch_one(repository.pool())
+        .await
+        .unwrap();
+    assert_eq!(
+        outbox_rows, 0,
+        "a direct-only projection must not require an outbox fact"
+    );
+
+    let replayed = service
+        .dispatch_causal(
+            "causal.direct",
+            &command_id,
+            input,
+            Session::new(),
+            causal_test_principal(),
+        )
+        .await
+        .expect("response-loss retry should replay without invoking the handler");
+    assert_eq!(replayed, first);
+    assert_eq!(handler_calls.load(Ordering::SeqCst), 1);
+    let CommandLookup::Replay(second_replay) = service
+        .lookup_causal_command(
+            "causal.direct",
+            &command_id,
+            &Session::new(),
+            causal_test_principal(),
+        )
+        .await
+        .unwrap()
+    else {
+        panic!("replayed command should remain terminal");
+    };
+    assert_eq!(second_replay.direct_projection, Some(evidence));
+}
+
+#[cfg(feature = "graphql")]
+#[tokio::test]
+async fn causal_dispatch_recovers_committed_replay_after_commit_acknowledgement_loss() {
+    let handler_calls = Arc::new(AtomicUsize::new(0));
+    let route_handler_calls = Arc::clone(&handler_calls);
+    let repository = AmbiguousCommitRepository::new(
+        InMemoryRepository::new(),
+        InjectedCommitBehavior::CommitThenErrorOnce,
+    );
+    let service = Service::new().named("causal-tests").routes(
+        Routes::new()
+            .with_repo(repository.aggregate::<CausalDispatcherAggregate>())
+            .typed_command(typed_command::<CausalTestInput, Accepted<TypedOutput>>(
+                "causal.ambiguous_committed",
+            ))
+            .handle(
+                move |_context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                      input: CausalTestInput| {
+                    let calls = Arc::clone(&route_handler_calls);
+                    async move {
+                        calls.fetch_add(1, Ordering::SeqCst);
+                        Ok(
+                            PreparedCommand::<Accepted<TypedOutput>>::prepare(TypedOutput {
+                                id: input.id,
+                            })
+                            .unwrap(),
+                        )
+                    }
+                },
+            ),
+    );
+    let command_id = causal_test_command_id();
+    let principal = causal_test_principal();
+    let input = causal_test_input("todo-ambiguous", "same");
+
+    let recovered = service
+        .dispatch_causal(
+            "causal.ambiguous_committed",
+            &command_id,
+            input.clone(),
+            Session::new(),
+            principal.clone(),
+        )
+        .await
+        .expect("lookup should recover the committed outcome");
+    assert_eq!(recovered, json!({ "id": "todo-ambiguous" }));
+    assert!(matches!(
+        service
+            .lookup_causal_command(
+                "causal.ambiguous_committed",
+                &command_id,
+                &Session::new(),
+                principal.clone(),
+            )
+            .await
+            .unwrap(),
+        CommandLookup::Replay(_)
+    ));
+
+    let replay = service
+        .dispatch_causal(
+            "causal.ambiguous_committed",
+            &command_id,
+            input,
+            Session::new(),
+            principal,
+        )
+        .await
+        .unwrap();
+    assert_eq!(replay, recovered);
+    assert_eq!(handler_calls.load(Ordering::SeqCst), 1);
+}
+
+#[cfg(feature = "graphql")]
+#[tokio::test]
+async fn causal_dispatch_reclaims_retryable_attempt_after_precommit_failure() {
+    let handler_calls = Arc::new(AtomicUsize::new(0));
+    let route_handler_calls = Arc::clone(&handler_calls);
+    let repository = AmbiguousCommitRepository::new(
+        InMemoryRepository::new(),
+        InjectedCommitBehavior::ErrorBeforeCommitOnce,
+    );
+    let service = Service::new().named("causal-tests").routes(
+        Routes::new()
+            .with_repo(repository.aggregate::<CausalDispatcherAggregate>())
+            .typed_command(typed_command::<CausalTestInput, Accepted<TypedOutput>>(
+                "causal.ambiguous_retry",
+            ))
+            .handle(
+                move |_context: &CausalCommandContext<'_, CausalDispatcherAggregate>,
+                      input: CausalTestInput| {
+                    let calls = Arc::clone(&route_handler_calls);
+                    async move {
+                        calls.fetch_add(1, Ordering::SeqCst);
+                        Ok(
+                            PreparedCommand::<Accepted<TypedOutput>>::prepare(TypedOutput {
+                                id: input.id,
+                            })
+                            .unwrap(),
+                        )
+                    }
+                },
+            ),
+    );
+    let command_id = causal_test_command_id();
+    let principal = causal_test_principal();
+    let input = causal_test_input("todo-retry", "same");
+
+    let first = service
+        .dispatch_causal(
+            "causal.ambiguous_retry",
+            &command_id,
+            input.clone(),
+            Session::new(),
+            principal.clone(),
+        )
+        .await
+        .expect_err("pre-commit failure should remain unknown to the caller");
+    assert_eq!(first.code(), "INTERNAL");
+    assert_eq!(handler_calls.load(Ordering::SeqCst), 1);
+    assert!(matches!(
+        service
+            .lookup_causal_command(
+                "causal.ambiguous_retry",
+                &command_id,
+                &Session::new(),
+                principal.clone(),
+            )
+            .await
+            .unwrap(),
+        CommandLookup::RetryableUnknown { .. }
+    ));
+
+    let retried = service
+        .dispatch_causal(
+            "causal.ambiguous_retry",
+            &command_id,
+            input.clone(),
+            Session::new(),
+            principal.clone(),
+        )
+        .await
+        .expect("same-ID retry should reclaim and commit");
+    assert_eq!(retried, json!({ "id": "todo-retry" }));
+    assert_eq!(handler_calls.load(Ordering::SeqCst), 2);
+
+    let replay = service
+        .dispatch_causal(
+            "causal.ambiguous_retry",
+            &command_id,
+            input,
+            Session::new(),
+            principal,
+        )
+        .await
+        .unwrap();
+    assert_eq!(replay, retried);
+    assert_eq!(handler_calls.load(Ordering::SeqCst), 2);
+}
+
+#[tokio::test]
+async fn service_collects_route_bundles_with_different_dependencies() {
+    let service = Service::new()
+        .routes(
+            Routes::new()
+                .with_dependencies(String::from("orders"))
+                .command("string.dep")
+                .handle(|ctx: &Context<String>| {
+                    let dep = ctx.dependencies().clone();
+                    async move { Ok(json!({ "dependency": dep })) }
+                }),
+        )
+        .routes(
+            Routes::new()
+                .with_dependencies(7_u32)
+                .event("number.dep")
+                .handle(|ctx: &Context<u32>| {
+                    let dep = *ctx.dependencies();
+                    async move { Ok(json!({ "dependency": dep })) }
+                }),
+        );
+
+    let command = service
+        .dispatch("string.dep", json!({}), Session::new())
+        .await
+        .unwrap();
+    let event = service
+        .dispatch_message(&Message::new(
+            "number.dep",
+            MessageKind::Event,
+            br#"{}"#.to_vec(),
+        ))
+        .await
+        .unwrap();
+
+    assert_eq!(command, json!({ "dependency": "orders" }));
+    assert_eq!(event, json!({ "dependency": 7 }));
+    assert_eq!(
+        service.subscription_plan(),
+        SubscriptionPlan {
+            commands: vec!["string.dep".to_string()],
+            events: vec!["number.dep".to_string()],
+        }
+    );
+}
+
+#[tokio::test]
+async fn service_dispatches_all_route_dependency_builder_combinations() {
+    let repo_only = InMemoryRepository::new().queued().aggregate();
+    let combo_repo = InMemoryRepository::new().queued().aggregate();
+    let service = Service::new()
+        .routes(
+            Routes::new()
+                .with_dependencies(String::from("custom"))
+                .command("custom.route")
+                .handle(|ctx: &Context<String>| {
+                    let dependency = ctx.dependencies().clone();
+                    async move { Ok(json!({ "route": dependency })) }
+                }),
+        )
+        .routes(
+            Routes::new()
+                .with_repo(repo_only)
+                .command("repo.route")
+                .handle(|ctx: &Context<RouteComboRepo>| {
+                    let _ = ctx.repo();
+                    async move { Ok(json!({ "route": "repo" })) }
+                }),
+        )
+        .routes(
+            Routes::new()
+                .with_read_model_store(InMemoryRepository::new())
+                .event("read.route")
+                .handle(|ctx: &Context<InMemoryRepository>| {
+                    let _ = ctx.read_model_store();
+                    async move { Ok(json!({ "route": "read" })) }
+                }),
+        )
+        .routes(
+            Routes::new()
+                .with_repo(combo_repo)
+                .with_read_model_store(InMemoryRepository::new())
+                .command("repo-read.route")
+                .handle(|ctx: &Context<RouteComboDeps>| {
+                    let _ = ctx.repo();
+                    let _ = ctx.read_model_store();
+                    async move { Ok(json!({ "route": "repo-read" })) }
+                }),
+        );
+
+    let custom = service
+        .dispatch("custom.route", json!({}), Session::new())
+        .await
+        .unwrap();
+    let repo = service
+        .dispatch("repo.route", json!({}), Session::new())
+        .await
+        .unwrap();
+    let read = service
+        .dispatch_message(&Message::new(
+            "read.route",
+            MessageKind::Event,
+            br#"{}"#.to_vec(),
+        ))
+        .await
+        .unwrap();
+    let repo_read = service
+        .dispatch("repo-read.route", json!({}), Session::new())
+        .await
+        .unwrap();
+
+    assert_eq!(custom, json!({ "route": "custom" }));
+    assert_eq!(repo, json!({ "route": "repo" }));
+    assert_eq!(read, json!({ "route": "read" }));
+    assert_eq!(repo_read, json!({ "route": "repo-read" }));
+    assert_eq!(
+        service.subscription_plan(),
+        SubscriptionPlan {
+            commands: vec![
+                "custom.route".to_string(),
+                "repo.route".to_string(),
+                "repo-read.route".to_string(),
+            ],
+            events: vec!["read.route".to_string()],
+        }
+    );
+}
+
+#[test]
+fn duplicate_route_names_within_bundle_are_rejected() {
+    let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+        let _routes = test_routes()
+            .command("same")
+            .handle(|_: &Context<()>| async move { Ok(json!({})) })
+            .command("same")
+            .handle(|_: &Context<()>| async move { Ok(json!({})) });
+    }));
+
+    assert!(result.is_err());
+}
+
+#[test]
+fn duplicate_route_bundle_add_is_rejected_atomically() {
+    let mut service = Service::new().routes(
+        test_routes()
+            .command("same")
+            .handle(|_: &Context<()>| async move { Ok(json!({})) }),
+    );
+    let conflicting = Routes::new()
+        .with_dependencies(7_u32)
+        .command("same")
+        .handle(|_: &Context<u32>| async move { Ok(json!({})) })
+        .command("new")
+        .handle(|_: &Context<u32>| async move { Ok(json!({})) });
+
+    let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+        service.add_routes(conflicting);
+    }));
+
+    assert!(result.is_err());
+    assert!(service.handles_message(MessageKind::Command, "same"));
+    assert!(!service.handles_message(MessageKind::Command, "new"));
+    assert_eq!(service.routes.len(), 1);
+    assert_eq!(service.command_names(), vec!["same"]);
+}
+
+#[tokio::test]
+async fn dispatch_returns_handler_result() {
+    let service = test_service(
+        test_routes()
+            .command("ping")
+            .handle(|_ctx: &Context<()>| async move { Ok(json!({ "pong": true })) }),
+    );
+    let result = service
+        .dispatch("ping", json!({}), Session::new())
+        .await
+        .unwrap();
+    assert_eq!(result, json!({ "pong": true }));
+}
+
+#[tokio::test]
+async fn unknown_command() {
+    // This dispatch records the same {unnamed, unknown, unknown_command}
+    // series into the process-global registry that
+    // `metrics_bucket_unknown_command_under_fixed_message_label` asserts
+    // an exact count on — serialize against it.
+    #[cfg(feature = "metrics")]
+    let _guard = crate::metrics::async_lock_for_tests().await;
+
+    let service = test_service(
+        test_routes()
+            .command("ping")
+            .handle(|_ctx: &Context<()>| async move { Ok(json!({})) }),
+    );
+    let result = service.dispatch("unknown", json!({}), Session::new()).await;
+    assert!(matches!(result, Err(HandlerError::UnknownCommand(ref s)) if s == "unknown"));
+}
+
+#[cfg(feature = "metrics")]
+#[tokio::test]
+async fn metrics_bucket_unknown_command_under_fixed_message_label() {
+    let _guard = crate::metrics::async_lock_for_tests().await;
+    crate::metrics::reset_for_tests();
+
+    let service = test_service(
+        test_routes()
+            .command("ping")
+            .handle(|_ctx: &Context<()>| async move { Ok(json!({})) }),
+    );
+
+    let result = service
+        .dispatch("attacker-controlled-path", json!({}), Session::new())
+        .await;
+    assert!(matches!(result, Err(HandlerError::UnknownCommand(_))));
+
+    let text = crate::metrics::prometheus_text();
+    assert!(
+            text.contains(
+                "distributed_microsvc_dispatch_total{service=\"unnamed\",message_kind=\"command\",message=\"unknown\",status=\"unknown_command\"} 1"
+            ),
+            "unknown commands should use a bounded message label:\n{text}"
+        );
+    assert!(
+        !text.contains("attacker-controlled-path"),
+        "unknown command input must not become a metric label:\n{text}"
+    );
+}
+
+#[tokio::test]
+async fn handler_error_propagates() {
+    let service = test_service(
+        test_routes()
+            .command("fail")
+            .handle(|_ctx: &Context<()>| async move { Err(HandlerError::Rejected("nope".into())) }),
+    );
+    let result = service.dispatch("fail", json!({}), Session::new()).await;
+    assert!(matches!(result, Err(HandlerError::Rejected(ref s)) if s == "nope"));
+}
+
+#[tokio::test]
+async fn decode_error_from_bad_payload() {
+    #[derive(serde::Deserialize)]
+    struct Input {
+        _name: String,
+    }
+
+    let service = test_service(test_routes().command("typed").handle(|ctx: &Context<()>| {
+        let input = ctx.input::<Input>();
+        async move {
+            let _input = input?;
+            Ok(json!({}))
+        }
+    }));
+    let result = service
+        .dispatch("typed", json!({ "wrong": 1 }), Session::new())
+        .await;
+    assert!(matches!(result, Err(HandlerError::DecodeFailed(_))));
+}
+
+#[test]
+fn command_names_list() {
+    let service = test_service(
+        test_routes()
+            .command("a")
+            .handle(|_: &Context<()>| async move { Ok(json!({})) })
+            .command("b")
+            .handle(|_: &Context<()>| async move { Ok(json!({})) }),
+    );
+    let mut cmds = service.command_names();
+    cmds.sort();
+    assert_eq!(cmds, vec!["a", "b"]);
+}
+
+#[test]
+fn subscription_plan_separates_commands_and_events() {
+    const EVENTS: &[&str] = &["checkout.started", "seat.reserved"];
+
+    let service = test_service(
+        test_routes()
+            .command("checkout.start")
+            .handle(|_: &Context<()>| async move { Ok(json!({})) })
+            .events(EVENTS)
+            .guarded(|_| true, |_: &Context<()>| async move { Ok(json!({})) }),
+    );
+
+    assert_eq!(
+        service.subscription_plan(),
+        SubscriptionPlan {
+            commands: vec!["checkout.start".to_string()],
+            events: vec!["checkout.started".to_string(), "seat.reserved".to_string()],
+        }
+    );
+}
+
+#[test]
+fn event_conveniences_record_event_names() {
+    const EVENTS: &[&str] = &["seat.added", "seat.reserved"];
+
+    let service = test_service(
+        test_routes()
+            .event("checkout.started")
+            .handle(|_: &Context<()>| async move { Ok(json!({})) })
+            .events(EVENTS)
+            .handle(|_: &Context<()>| async move { Ok(json!({})) }),
+    );
+
+    let mut events = service.event_names();
+    events.sort();
+    assert_eq!(
+        events,
+        vec!["checkout.started", "seat.added", "seat.reserved"]
+    );
+}
+
+#[tokio::test]
+async fn command_and_event_handlers_can_share_a_name() {
+    let service = test_service(
+        test_routes()
+            .command("shared")
+            .handle(|ctx: &Context<()>| {
+                let kind = format!("{:?}", ctx.message().kind);
+                async move { Ok(json!({ "kind": kind })) }
+            })
+            .event("shared")
+            .handle(|ctx: &Context<()>| {
+                let event_id = ctx.message().id().map(|s| s.to_string());
+                async move { Ok(json!({ "event_id": event_id })) }
+            }),
+    );
+    let event_message =
+        Message::new("shared", MessageKind::Event, br#"{}"#.to_vec()).with_id("evt-1");
+
+    let command_result = service
+        .dispatch("shared", json!({}), Session::new())
+        .await
+        .unwrap();
+    let event_result = service.dispatch_message(&event_message).await.unwrap();
+
+    assert_eq!(command_result, json!({ "kind": "Command" }));
+    assert_eq!(event_result, json!({ "event_id": "evt-1" }));
+    assert!(service.handles_message(MessageKind::Command, "shared"));
+    assert!(service.handles_message(MessageKind::Event, "shared"));
+}
+
+#[tokio::test]
+async fn dispatch_message_delivers_payload_json_by_default() {
+    let service = test_service(test_routes().event("checkout.started").handle(
+        |ctx: &Context<()>| {
+            let has_checkout_id = ctx.has_fields(&["checkout_id"]);
+            let event_id = ctx.message().id().map(|s| s.to_string());
+            let checkout_id = ctx.raw_input()["checkout_id"]
+                .as_str()
+                .map(|s| s.to_string());
+            let user_id = ctx.user_id().map(|s| s.to_string());
+            async move {
+                if !has_checkout_id {
+                    return Err(HandlerError::Rejected("missing checkout_id".into()));
+                }
+
+                Ok(json!({
+                    "event_id": event_id,
+                    "checkout_id": checkout_id.unwrap(),
+                    "user_id": user_id?,
+                }))
+            }
+        },
+    ));
+    let message = Message {
+        id: Some("evt-1".to_string()),
+        name: "checkout.started".to_string(),
+        kind: MessageKind::Event,
+        payload: br#"{"checkout_id":"checkout-1"}"#.to_vec(),
+        content_type: "application/json".to_string(),
+        metadata: vec![("X-User-Id".to_string(), "user-1".to_string())],
+    };
+
+    let result = service.dispatch_message(&message).await.unwrap();
+
+    assert_eq!(
+        result,
+        json!({ "event_id": "evt-1", "checkout_id": "checkout-1", "user_id": "user-1" })
+    );
+}
+
+#[tokio::test]
+async fn dispatch_message_surfaces_malformed_json_as_decode_error() {
+    let service = test_service(test_routes().event("checkout.started").handle(
+        |_ctx: &Context<()>| async move { panic!("handler must not run on a decode error") },
+    ));
+    let message = Message::new(
+        "checkout.started",
+        MessageKind::Event,
+        br#"{"checkout_id": oops"#.to_vec(),
+    );
+
+    let err = service.dispatch_message(&message).await.unwrap_err();
+
+    match err {
+        HandlerError::DecodeFailed(detail) => {
+            assert!(
+                detail.contains("invalid JSON payload") && detail.contains("checkout.started"),
+                "decode error should carry the parse failure, got: {detail}"
+            );
+        }
+        other => panic!("expected DecodeFailed, got {other:?}"),
+    }
+}
+
+#[tokio::test]
+async fn dispatch_message_nulls_input_for_non_json_payloads() {
+    let service = test_service(
+        test_routes()
+            .event("blob.stored")
+            .handle(|ctx: &Context<()>| {
+                let input_is_null = ctx.raw_input().is_null();
+                let payload = ctx.message().payload().to_vec();
+                async move { Ok(json!({ "null_input": input_is_null, "len": payload.len() })) }
+            }),
+    );
+    let mut message = Message::new("blob.stored", MessageKind::Event, vec![0, 159, 146, 150]);
+    message.content_type = "application/octet-stream".to_string();
+
+    let result = service.dispatch_message(&message).await.unwrap();
+
+    assert_eq!(result, json!({ "null_input": true, "len": 4 }));
+}
+
+#[tokio::test]
+async fn dispatch_message_always_exposes_message_metadata() {
+    let service = test_service(test_routes().event("seat.reserved").guarded(
+        |ctx| ctx.message().id().is_some(),
+        |ctx: &Context<()>| {
+            let input: Result<Value, _> = ctx.input();
+            let message = ctx.message();
+            let event_id = message.id().map(|s| s.to_string());
+            let name = message.name().to_string();
+            let correlation_id = message.correlation_id().map(|s| s.to_string());
+            async move {
+                let input = input?;
+                Ok(json!({
+                    "event_id": event_id,
+                    "name": name,
+                    "correlation_id": correlation_id,
+                    "seat_id": input["seat_id"].as_str().unwrap(),
+                }))
+            }
+        },
+    ));
+    let message = Message {
+        id: Some("evt-2".to_string()),
+        name: "seat.reserved".to_string(),
+        kind: MessageKind::Event,
+        payload: br#"{"seat_id":"A-7"}"#.to_vec(),
+        content_type: "application/json".to_string(),
+        metadata: vec![("Correlation_ID".to_string(), "checkout-1".to_string())],
+    };
+
+    let result = service.dispatch_message(&message).await.unwrap();
+
+    assert_eq!(
+        result,
+        json!({
+            "event_id": "evt-2",
+            "name": "seat.reserved",
+            "correlation_id": "checkout-1",
+            "seat_id": "A-7",
+        })
+    );
+}
+
+#[tokio::test]
+async fn dispatch_exposes_trace_context_from_session_metadata() {
+    let traceparent = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01";
+    let service = test_service(test_routes().command("checkout.start").handle(
+        |ctx: &Context<()>| {
+            let trace_context = ctx.message().trace_context();
+            async move {
+                Ok(json!({
+                    "traceparent": trace_context.traceparent,
+                    "tracestate": trace_context.tracestate,
+                }))
+            }
+        },
+    ));
+    let session = Session::from_map(HashMap::from([
+        ("traceparent".to_string(), traceparent.to_string()),
+        ("tracestate".to_string(), "vendor=value".to_string()),
+    ]));
+
+    let result = service
+        .dispatch("checkout.start", json!({}), session)
+        .await
+        .unwrap();
+
+    assert_eq!(
+        result,
+        json!({ "traceparent": traceparent, "tracestate": "vendor=value" })
+    );
+}
+
+#[tokio::test]
+async fn guard_passes() {
+    let service = test_service(test_routes().command("greet").guarded(
+        |ctx| ctx.has_fields(&["name"]),
+        |ctx: &Context<()>| {
+            let name = ctx.raw_input()["name"].as_str().map(|s| s.to_string());
+            async move { Ok(json!({ "hello": name.unwrap() })) }
+        },
+    ));
+    let result = service
+        .dispatch("greet", json!({ "name": "Pat" }), Session::new())
+        .await
+        .unwrap();
+    assert_eq!(result, json!({ "hello": "Pat" }));
+}
+
+#[tokio::test]
+async fn guard_rejects() {
+    let service = test_service(test_routes().command("greet").guarded(
+        |ctx| ctx.has_fields(&["name"]),
+        |_ctx: &Context<()>| async move {
+            panic!("handler should not run");
+            #[allow(unreachable_code)]
+            Ok(json!({}))
+        },
+    ));
+    let result = service
+        .dispatch("greet", json!({ "wrong": 1 }), Session::new())
+        .await;
+    assert!(matches!(result, Err(HandlerError::GuardRejected(ref s)) if s == "greet"));
+}
+
+#[tokio::test]
+async fn guard_checks_session() {
+    let service = test_service(test_routes().command("admin").guarded(
+        |ctx| ctx.role() == Some("admin"),
+        |_ctx: &Context<()>| async move { Ok(json!({ "ok": true })) },
+    ));
+
+    // No role
+    assert!(service
+        .dispatch("admin", json!({}), Session::new())
+        .await
+        .is_err());
+
+    // Admin role
+    let mut session = Session::new();
+    session.set(crate::microsvc::ROLE_KEY, "admin");
+    assert!(service.dispatch("admin", json!({}), session).await.is_ok());
+}
+
+#[tokio::test]
+async fn dispatch_request_success() {
+    let service = test_service(
+        test_routes()
+            .command("ping")
+            .handle(|_ctx: &Context<()>| async move { Ok(json!({ "pong": true })) }),
+    );
+    let request = CommandRequest {
+        command: "ping".to_string(),
+        input: json!({}),
+        session_variables: HashMap::new(),
+    };
+    let response = service.dispatch_request(&request).await;
+    assert_eq!(response.status, 200);
+    assert_eq!(response.body, json!({ "pong": true }));
+}
+
+#[tokio::test]
+async fn dispatch_request_error_codes() {
+    let service = test_service(
+        test_routes()
+            .command("reject")
+            .handle(|_: &Context<()>| async move { Err(HandlerError::Rejected("no".into())) })
+            .command("unauth")
+            .handle(|ctx: &Context<()>| {
+                let user_id = ctx.user_id().map(|s| s.to_string());
+                async move {
+                    let _ = user_id?;
+                    Ok(json!({}))
+                }
+            }),
+    );
+
+    let resp = service
+        .dispatch_request(&CommandRequest {
+            command: "unknown".to_string(),
+            input: json!({}),
+            session_variables: HashMap::new(),
+        })
+        .await;
+    assert_eq!(resp.status, 404);
+
+    let resp = service
+        .dispatch_request(&CommandRequest {
+            command: "reject".to_string(),
+            input: json!({}),
+            session_variables: HashMap::new(),
+        })
+        .await;
+    assert_eq!(resp.status, 422);
+
+    let resp = service
+        .dispatch_request(&CommandRequest {
+            command: "unauth".to_string(),
+            input: json!({}),
+            session_variables: HashMap::new(),
+        })
+        .await;
+    assert_eq!(resp.status, 401);
+}
+
+#[tokio::test]
+async fn dispatch_request_passes_session() {
+    let service = test_service(test_routes().command("whoami").handle(|ctx: &Context<()>| {
+        let user_id = ctx.user_id().map(|s| s.to_string());
+        async move {
+            let user_id = user_id?;
+            Ok(json!({ "user_id": user_id }))
+        }
+    }));
+    let mut vars = HashMap::new();
+    vars.insert(
+        crate::microsvc::USER_ID_KEY.to_string(),
+        "user-99".to_string(),
+    );
+    let request = CommandRequest {
+        command: "whoami".to_string(),
+        input: json!({}),
+        session_variables: vars,
+    };
+    let response = service.dispatch_request(&request).await;
+    assert_eq!(response.status, 200);
+    assert_eq!(response.body, json!({ "user_id": "user-99" }));
+}
+
+#[test]
+fn command_request_requires_session_variables_field() {
+    let json = r#"{"command":"ping","input":{}}"#;
+    let result: Result<CommandRequest, _> = serde_json::from_str(json);
+    assert!(result.is_err());
+}
diff --git a/src/outbox/commit.rs b/src/outbox/commit.rs
index bde4535c..ffb08b67 100644
--- a/src/outbox/commit.rs
+++ b/src/outbox/commit.rs
@@ -134,9 +134,10 @@ where
     /// With a bus configured, each outbox row is **claimed in this same
     /// transaction** (born `InFlight` under a short lease) and published right
     /// after commit, so publication needs no separate claim and cannot race the
-    /// polling worker; a crash before publish hands the row back to the worker at
-    /// lease expiry, and a publish failure leaves it retryable. Without a bus,
-    /// rows are committed `pending` for the worker to publish.
+    /// polling worker; a crash before publish hands the row back to an
+    /// independently running worker at lease expiry, and a publish failure
+    /// leaves it retryable. Without a bus, rows are committed `pending` for the
+    /// worker to publish.
     ///
     /// Returns a [`CommitReceipt`] carrying the inserted outbox message ids.
     pub async fn commit(mut self, aggregate: &mut A) -> Result<CommitReceipt, RepositoryError> {
@@ -183,7 +184,8 @@ where
         }
 
         // Best-effort immediate publish. A failure leaves the claimed rows for
-        // the polling worker and never fails the already-committed command.
+        // an independently running polling worker and never fails the
+        // already-committed command.
         if let Some(config) = publisher {
             let _ = config.hook.publish_claimed(claimed).await;
         }
diff --git a/src/outbox/message.rs b/src/outbox/message.rs
index 828dc3ea..67d82925 100644
--- a/src/outbox/message.rs
+++ b/src/outbox/message.rs
@@ -485,6 +485,18 @@ impl OutboxMessage {
         self.set_meta(CAUSATION_ID, id);
     }
 
+    /// Replace causation metadata at the final causal-commit boundary.
+    ///
+    /// The ledger attempt, rather than handler-supplied metadata, is
+    /// authoritative for every outbox fact committed by a causal command.
+    #[cfg_attr(not(feature = "graphql"), allow(dead_code))]
+    pub(crate) fn overwrite_causation_id(&mut self, id: &str) {
+        self.metadata
+            .retain(|key, _| !key.eq_ignore_ascii_case(CAUSATION_ID));
+        self.metadata
+            .insert(CAUSATION_ID.to_string(), id.to_string());
+    }
+
     /// Set W3C trace context metadata.
     pub fn set_trace_context(&mut self, context: &TraceContext) {
         context.inject_map(&mut self.metadata);
@@ -707,6 +719,36 @@ mod tests {
         assert_eq!(message.meta("tenant"), Some("acme"));
     }
 
+    #[test]
+    fn final_causal_stamp_overwrites_handler_metadata() {
+        let mut message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
+        message.set_causation_id("handler-supplied");
+        message.set_meta("Causation_Id", "forged-case-alias");
+
+        message.overwrite_causation_id("ledger-causation");
+
+        assert_eq!(message.causation_id(), Some("ledger-causation"));
+        assert_eq!(
+            message
+                .metadata
+                .keys()
+                .filter(|key| key.eq_ignore_ascii_case(CAUSATION_ID))
+                .count(),
+            1
+        );
+
+        let transport: crate::bus::Message = message.into();
+        assert_eq!(transport.causation_id(), Some("ledger-causation"));
+        assert_eq!(
+            transport
+                .metadata
+                .iter()
+                .filter(|(key, _)| key.eq_ignore_ascii_case(CAUSATION_ID))
+                .count(),
+            1
+        );
+    }
+
     #[test]
     fn set_trace_context_replaces_existing_trace_metadata() {
         let mut message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
diff --git a/src/outbox/table.rs b/src/outbox/table.rs
index 47c54712..a71c972a 100644
--- a/src/outbox/table.rs
+++ b/src/outbox/table.rs
@@ -3,7 +3,7 @@ use std::time::{SystemTime, UNIX_EPOCH};
 use crate::outbox::{OutboxMessage, OutboxMessageStatus};
 use crate::table::{
     ColumnType, ExpectedVersion, PrimaryKey, RowKey, RowValue, RowValues, RowWriteMode,
-    TableColumn, TableIndex, TableModel, TableMutation, TableRowMutation, TableSchema,
+    TableColumn, TableIndex, TableKind, TableModel, TableMutation, TableRowMutation, TableSchema,
     TableStoreError, TableWritePlan,
 };
 
@@ -57,6 +57,7 @@ pub fn outbox_message_schema() -> &'static TableSchema {
             named_index("outbox_messages_destination_idx", ["destination", "status"]),
         ],
         relationships: Vec::new(),
+        kind: TableKind::Operational,
     });
     &SCHEMA
 }
diff --git a/src/outbox_worker/store.rs b/src/outbox_worker/store.rs
deleted file mode 100644
index e40d42cf..00000000
--- a/src/outbox_worker/store.rs
+++ /dev/null
@@ -1,1005 +0,0 @@
-#![expect(
-    clippy::manual_async_fn,
-    reason = "async trait impls return impl Future + Send to preserve public Send bounds"
-)]
-
-use std::future::Future;
-use std::time::{Duration, SystemTime};
-
-use crate::in_memory_repo::InMemoryOutboxStore;
-use crate::outbox::{OutboxMessage, OutboxMessageStatus};
-use crate::repository::RepositoryError;
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum OutboxPublishFailureAction {
-    Released,
-    Failed,
-}
-
-/// Lightweight outbox backlog summary for metrics and diagnostics.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
-pub struct OutboxBacklogStats {
-    /// Number of rows currently in the pending status.
-    pub pending: usize,
-    /// Creation time of the oldest pending row, when any pending rows exist.
-    pub oldest_created_at: Option<SystemTime>,
-}
-
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub struct ClaimOutboxMessages {
-    pub worker_id: String,
-    pub batch_size: usize,
-    pub lease: Duration,
-    pub destination: Option<String>,
-    /// Restrict the claim to this explicit set of message ids. `None` claims the
-    /// next claimable batch in created-at order (normal worker polling); `Some`
-    /// claims only the listed ids (after-commit immediate dispatch). Ids that are
-    /// not currently claimable are simply skipped — a raced id is not an error.
-    pub message_ids: Option<Vec<String>>,
-}
-
-impl ClaimOutboxMessages {
-    pub fn new(worker_id: impl Into<String>, batch_size: usize, lease: Duration) -> Self {
-        Self {
-            worker_id: worker_id.into(),
-            batch_size,
-            lease,
-            destination: None,
-            message_ids: None,
-        }
-    }
-
-    pub fn to_destination(mut self, destination: impl Into<String>) -> Self {
-        self.destination = Some(destination.into());
-        self
-    }
-
-    /// Restrict this claim to an explicit list of message ids (after-commit
-    /// immediate dispatch). The batch size is bounded by the id count.
-    pub fn for_ids(worker_id: impl Into<String>, ids: Vec<String>, lease: Duration) -> Self {
-        Self {
-            worker_id: worker_id.into(),
-            batch_size: ids.len(),
-            lease,
-            destination: None,
-            message_ids: Some(ids),
-        }
-    }
-
-    /// Whether `id` is selectable under this request's id filter.
-    fn selects(&self, id: &str) -> bool {
-        match &self.message_ids {
-            Some(ids) => ids.iter().any(|wanted| wanted == id),
-            None => true,
-        }
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub struct OutboxClaimRef {
-    pub message_id: String,
-    pub worker_id: String,
-    pub leased_until: SystemTime,
-    pub attempt: u32,
-}
-
-impl OutboxClaimRef {
-    pub fn from_message(message: &OutboxMessage) -> Result<Self, RepositoryError> {
-        let worker_id = message
-            .worker_id
-            .clone()
-            .ok_or_else(|| invalid_outbox_state(message, "outbox claim worker"))?;
-        let leased_until = message
-            .leased_until
-            .ok_or_else(|| invalid_outbox_state(message, "outbox claim lease"))?;
-
-        Ok(Self {
-            message_id: message.id().to_string(),
-            worker_id,
-            leased_until,
-            attempt: message.attempts,
-        })
-    }
-}
-
-/// Row bound for the default [`backlog_stats`] scan.
-///
-/// [`backlog_stats`]: OutboxStore::backlog_stats
-pub const BACKLOG_STATS_SCAN_LIMIT: usize = 1000;
-
-/// Store capability for claiming and updating durable outbox messages.
-pub trait OutboxStore: Send + Sync {
-    /// List up to `limit` messages with the given status, in claim order
-    /// (created-at, then message id). The listing is a diagnostic/ops read, so
-    /// the bound is mandatory: an outbox can grow far beyond what any caller
-    /// should page into memory at once.
-    fn messages_by_status(
-        &self,
-        status: OutboxMessageStatus,
-        limit: usize,
-    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + '_;
-
-    /// List up to `limit` pending messages (see [`messages_by_status`]).
-    ///
-    /// [`messages_by_status`]: OutboxStore::messages_by_status
-    fn pending(
-        &self,
-        limit: usize,
-    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + '_ {
-        async move {
-            self.messages_by_status(OutboxMessageStatus::Pending, limit)
-                .await
-        }
-    }
-
-    /// Return pending-row count and oldest pending creation time without
-    /// requiring callers to page full rows. Backends with query support should
-    /// override this with `COUNT`/`MIN(created_at)` or equivalent (both
-    /// in-tree stores do).
-    ///
-    /// The default pages up to [`BACKLOG_STATS_SCAN_LIMIT`] pending rows —
-    /// never the whole outbox, per the bound contract on
-    /// [`messages_by_status`]. The count saturates at that limit; the oldest
-    /// creation time stays exact because pending listings are in claim
-    /// (oldest-first) order.
-    ///
-    /// [`messages_by_status`]: OutboxStore::messages_by_status
-    fn backlog_stats(
-        &self,
-    ) -> impl Future<Output = Result<OutboxBacklogStats, RepositoryError>> + Send + '_ {
-        async move {
-            let pending = self.pending(BACKLOG_STATS_SCAN_LIMIT).await?;
-            let oldest_created_at = pending.first().map(|message| message.created_at);
-            Ok(OutboxBacklogStats {
-                pending: pending.len(),
-                oldest_created_at,
-            })
-        }
-    }
-
-    fn claim<'a>(
-        &'a self,
-        request: ClaimOutboxMessages,
-    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + 'a;
-
-    fn complete<'a>(
-        &'a self,
-        claim: &'a OutboxClaimRef,
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a;
-
-    /// Complete a batch of claims after their rows were published.
-    ///
-    /// Equivalent to calling [`complete`] for each claim; backends override it
-    /// to settle the batch in fewer round trips (one statement/transaction).
-    /// Error semantics match the serial loop: a claim that is no longer
-    /// completable (missing row, stale worker/attempt, expired lease) surfaces
-    /// the same `NotFound`/`InvalidState` error, and other claims in the batch
-    /// may already have been completed when the error is returned.
-    ///
-    /// [`complete`]: OutboxStore::complete
-    fn complete_many<'a>(
-        &'a self,
-        claims: &'a [OutboxClaimRef],
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-        async move {
-            for claim in claims {
-                self.complete(claim).await?;
-            }
-            Ok(())
-        }
-    }
-
-    fn release<'a>(
-        &'a self,
-        claim: &'a OutboxClaimRef,
-        error: &'a str,
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a;
-
-    fn fail<'a>(
-        &'a self,
-        claim: &'a OutboxClaimRef,
-        error: &'a str,
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a;
-
-    fn record_failure<'a>(
-        &'a self,
-        claim: &'a OutboxClaimRef,
-        error: &'a str,
-        max_attempts: u32,
-    ) -> impl Future<Output = Result<OutboxPublishFailureAction, RepositoryError>> + Send + 'a {
-        async move {
-            if claim.attempt >= max_attempts {
-                self.fail(claim, error).await?;
-                Ok(OutboxPublishFailureAction::Failed)
-            } else {
-                self.release(claim, error).await?;
-                Ok(OutboxPublishFailureAction::Released)
-            }
-        }
-    }
-}
-
-fn outbox_state(message: &OutboxMessage) -> String {
-    format!(
-        "{:?}, worker={:?}, leased_until={:?}, attempts={}",
-        message.status, message.worker_id, message.leased_until, message.attempts
-    )
-}
-
-fn invalid_outbox_state(message: &OutboxMessage, expected: &'static str) -> RepositoryError {
-    RepositoryError::InvalidState {
-        id: message.id().to_string(),
-        expected,
-        actual: outbox_state(message),
-    }
-}
-
-pub(crate) fn ensure_active_claim(
-    message: &OutboxMessage,
-    claim: Option<&OutboxClaimRef>,
-    now: SystemTime,
-) -> Result<(), RepositoryError> {
-    if !message.is_in_flight() {
-        return Err(invalid_outbox_state(message, "in-flight outbox message"));
-    }
-
-    if let Some(claim) = claim {
-        if !message.is_claimed_by(&claim.worker_id) {
-            return Err(invalid_outbox_state(
-                message,
-                "outbox claim held by requesting worker",
-            ));
-        }
-
-        if message.attempts != claim.attempt {
-            return Err(invalid_outbox_state(
-                message,
-                "outbox claim attempt held by requesting worker",
-            ));
-        }
-    }
-
-    if message.has_expired_lease_at(now) {
-        return Err(invalid_outbox_state(message, "unexpired outbox claim"));
-    }
-
-    Ok(())
-}
-
-/// Claim order: oldest row first, message id as the deterministic tiebreaker.
-/// The single definition both claim-order helpers sort by.
-fn claim_order_key(message: &OutboxMessage) -> (SystemTime, &str) {
-    (message.created_at, message.id())
-}
-
-fn sort_by_claim_order(messages: &mut [OutboxMessage]) {
-    messages.sort_by(|left, right| claim_order_key(left).cmp(&claim_order_key(right)));
-}
-
-fn claim_order_ids<'a>(messages: impl Iterator<Item = &'a OutboxMessage>) -> Vec<String> {
-    let mut messages: Vec<&OutboxMessage> = messages.collect();
-    messages.sort_by(|left, right| claim_order_key(left).cmp(&claim_order_key(right)));
-    messages
-        .into_iter()
-        .map(|message| message.id().to_string())
-        .collect()
-}
-
-impl InMemoryOutboxStore {
-    fn update_outbox_message<T>(
-        &self,
-        message_id: &str,
-        update: impl FnOnce(&mut OutboxMessage) -> Result<T, RepositoryError>,
-    ) -> Result<T, RepositoryError> {
-        let mut storage = self
-            .storage
-            .write()
-            .map_err(|_| RepositoryError::LockPoisoned("outbox write"))?;
-
-        let message = storage
-            .get_mut(message_id)
-            .ok_or_else(|| RepositoryError::NotFound {
-                id: message_id.to_string(),
-            })?;
-
-        update(message)
-    }
-}
-
-impl OutboxStore for InMemoryOutboxStore {
-    fn messages_by_status(
-        &self,
-        status: OutboxMessageStatus,
-        limit: usize,
-    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + '_ {
-        async move {
-            let storage = self
-                .storage
-                .read()
-                .map_err(|_| RepositoryError::LockPoisoned("outbox read"))?;
-
-            let mut messages = storage
-                .values()
-                .filter(|message| message.status == status)
-                .cloned()
-                .collect::<Vec<_>>();
-            sort_by_claim_order(&mut messages);
-            messages.truncate(limit);
-            Ok(messages)
-        }
-    }
-
-    fn backlog_stats(
-        &self,
-    ) -> impl Future<Output = Result<OutboxBacklogStats, RepositoryError>> + Send + '_ {
-        async move {
-            let storage = self
-                .storage
-                .read()
-                .map_err(|_| RepositoryError::LockPoisoned("outbox read"))?;
-
-            let mut stats = OutboxBacklogStats::default();
-            for message in storage
-                .values()
-                .filter(|message| message.status == OutboxMessageStatus::Pending)
-            {
-                stats.pending += 1;
-                stats.oldest_created_at = Some(
-                    stats
-                        .oldest_created_at
-                        .map_or(message.created_at, |oldest| oldest.min(message.created_at)),
-                );
-            }
-            Ok(stats)
-        }
-    }
-
-    fn claim<'a>(
-        &'a self,
-        request: ClaimOutboxMessages,
-    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + 'a {
-        async move {
-            let mut storage = self
-                .storage
-                .write()
-                .map_err(|_| RepositoryError::LockPoisoned("outbox write"))?;
-
-            if request.batch_size == 0 {
-                return Ok(Vec::new());
-            }
-
-            let now = SystemTime::now();
-            let ids = claim_order_ids(storage.values());
-            let mut claimed = Vec::new();
-            for id in ids {
-                if !request.selects(&id) {
-                    continue;
-                }
-
-                let Some(message) = storage.get_mut(&id) else {
-                    continue;
-                };
-
-                if message.is_claimable_at(now) {
-                    if let Some(destination) = request.destination.as_deref() {
-                        if message.destination.as_deref() != Some(destination) {
-                            continue;
-                        }
-                    }
-                    message.claim_at(&request.worker_id, request.lease, now)?;
-                    claimed.push(message.clone());
-                }
-
-                if claimed.len() >= request.batch_size {
-                    break;
-                }
-            }
-
-            Ok(claimed)
-        }
-    }
-
-    fn complete<'a>(
-        &'a self,
-        claim: &'a OutboxClaimRef,
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-        async move {
-            self.update_outbox_message(&claim.message_id, |message| {
-                ensure_active_claim(message, Some(claim), SystemTime::now())?;
-                message.complete()?;
-                Ok(())
-            })
-        }
-    }
-
-    /// Batched complete under a single write lock instead of one lock
-    /// acquisition per claim. Same per-claim validation as [`complete`];
-    /// claims before a failing one stay completed, like the serial loop.
-    ///
-    /// [`complete`]: OutboxStore::complete
-    fn complete_many<'a>(
-        &'a self,
-        claims: &'a [OutboxClaimRef],
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-        async move {
-            if claims.is_empty() {
-                return Ok(());
-            }
-            let mut storage = self
-                .storage
-                .write()
-                .map_err(|_| RepositoryError::LockPoisoned("outbox write"))?;
-            let now = SystemTime::now();
-            for claim in claims {
-                let message = storage.get_mut(&claim.message_id).ok_or_else(|| {
-                    RepositoryError::NotFound {
-                        id: claim.message_id.clone(),
-                    }
-                })?;
-                ensure_active_claim(message, Some(claim), now)?;
-                message.complete()?;
-            }
-            Ok(())
-        }
-    }
-
-    fn release<'a>(
-        &'a self,
-        claim: &'a OutboxClaimRef,
-        error: &'a str,
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-        async move {
-            self.update_outbox_message(&claim.message_id, |message| {
-                ensure_active_claim(message, Some(claim), SystemTime::now())?;
-                message.release(error.to_string())?;
-                Ok(())
-            })
-        }
-    }
-
-    fn fail<'a>(
-        &'a self,
-        claim: &'a OutboxClaimRef,
-        error: &'a str,
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-        async move {
-            self.update_outbox_message(&claim.message_id, |message| {
-                ensure_active_claim(message, Some(claim), SystemTime::now())?;
-                message.fail(error.to_string())?;
-                Ok(())
-            })
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::{CommitBatch, InMemoryRepository, TransactionalCommit};
-    use std::sync::{Arc, Barrier};
-    use std::thread;
-
-    async fn store_message(repo: &InMemoryRepository, message: OutboxMessage) -> String {
-        let id = message.id().to_string();
-        let mut batch = CommitBatch::empty();
-        batch.outbox_messages.push(message);
-        repo.commit_batch(batch).await.unwrap();
-        id
-    }
-
-    fn load_message(repo: &InMemoryRepository, id: &str) -> OutboxMessage {
-        repo.outbox_storage()
-            .read()
-            .unwrap()
-            .get(id)
-            .unwrap()
-            .clone()
-    }
-
-    #[tokio::test]
-    async fn claim_includes_expired_in_flight_messages() {
-        let repo = InMemoryRepository::new();
-        let mut message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
-        message
-            .claim_at("worker-1", Duration::from_secs(1), SystemTime::UNIX_EPOCH)
-            .unwrap();
-        let id = store_message(&repo, message).await;
-
-        let store = repo.outbox_store();
-        let claimed = store
-            .claim(ClaimOutboxMessages::new(
-                "worker-2",
-                1,
-                Duration::from_secs(60),
-            ))
-            .await
-            .unwrap();
-
-        assert_eq!(claimed.len(), 1);
-        assert_eq!(claimed[0].worker_id.as_deref(), Some("worker-2"));
-        assert_eq!(claimed[0].attempts, 2);
-
-        let stored = load_message(&repo, &id);
-        assert_eq!(stored.worker_id.as_deref(), Some("worker-2"));
-        assert_eq!(stored.attempts, 2);
-        assert!(stored.is_in_flight());
-    }
-
-    #[tokio::test]
-    async fn claim_skips_unexpired_in_flight_messages() {
-        let repo = InMemoryRepository::new();
-        let mut message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
-        message
-            .claim_for("worker-1", Duration::from_secs(60))
-            .unwrap();
-        let id = store_message(&repo, message).await;
-
-        let store = repo.outbox_store();
-        let claimed = store
-            .claim(ClaimOutboxMessages::new(
-                "worker-2",
-                1,
-                Duration::from_secs(60),
-            ))
-            .await
-            .unwrap();
-
-        assert!(claimed.is_empty());
-        let stored = load_message(&repo, &id);
-        assert_eq!(stored.worker_id.as_deref(), Some("worker-1"));
-        assert_eq!(stored.attempts, 1);
-    }
-
-    #[tokio::test]
-    async fn claim_uses_created_at_before_message_id_order() {
-        let repo = InMemoryRepository::new();
-        let mut newer = OutboxMessage::create("msg-a", "Event", b"{}".to_vec()).unwrap();
-        newer.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(10);
-        let mut older = OutboxMessage::create("msg-z", "Event", b"{}".to_vec()).unwrap();
-        older.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(1);
-        store_message(&repo, newer).await;
-        store_message(&repo, older).await;
-
-        let claimed = repo
-            .outbox_store()
-            .claim(ClaimOutboxMessages::new(
-                "worker-1",
-                1,
-                Duration::from_secs(60),
-            ))
-            .await
-            .unwrap();
-
-        assert_eq!(claimed[0].id(), "msg-z");
-    }
-
-    #[tokio::test]
-    async fn claim_by_explicit_ids_claims_only_requested() {
-        let repo = InMemoryRepository::new();
-        store_message(
-            &repo,
-            OutboxMessage::create("msg-a", "Event", b"{}".to_vec()).unwrap(),
-        )
-        .await;
-        store_message(
-            &repo,
-            OutboxMessage::create("msg-b", "Event", b"{}".to_vec()).unwrap(),
-        )
-        .await;
-        store_message(
-            &repo,
-            OutboxMessage::create("msg-c", "Event", b"{}".to_vec()).unwrap(),
-        )
-        .await;
-
-        let claimed = repo
-            .outbox_store()
-            .claim(ClaimOutboxMessages::for_ids(
-                "worker-1",
-                vec!["msg-b".to_string(), "msg-c".to_string()],
-                Duration::from_secs(60),
-            ))
-            .await
-            .unwrap();
-
-        let mut claimed_ids = claimed
-            .iter()
-            .map(|m| m.id().to_string())
-            .collect::<Vec<_>>();
-        claimed_ids.sort();
-        assert_eq!(claimed_ids, vec!["msg-b".to_string(), "msg-c".to_string()]);
-        // The unrequested row stays pending.
-        assert!(load_message(&repo, "msg-a").is_pending());
-    }
-
-    #[tokio::test]
-    async fn claim_by_ids_skips_unclaimable_without_error() {
-        let repo = InMemoryRepository::new();
-        let mut leased = OutboxMessage::create("msg-a", "Event", b"{}".to_vec()).unwrap();
-        leased
-            .claim_for("other-worker", Duration::from_secs(60))
-            .unwrap();
-        store_message(&repo, leased).await;
-
-        // Requesting a currently-leased id (and a missing id) yields no claim,
-        // not an error.
-        let claimed = repo
-            .outbox_store()
-            .claim(ClaimOutboxMessages::for_ids(
-                "worker-1",
-                vec!["msg-a".to_string(), "missing".to_string()],
-                Duration::from_secs(60),
-            ))
-            .await
-            .unwrap();
-
-        assert!(claimed.is_empty());
-    }
-
-    #[test]
-    fn sort_by_claim_order_uses_message_id_tiebreaker() {
-        let mut later = OutboxMessage::create("msg-c", "Event", b"{}".to_vec()).unwrap();
-        later.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(10);
-        let mut second = OutboxMessage::create("msg-b", "Event", b"{}".to_vec()).unwrap();
-        second.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(1);
-        let mut first = OutboxMessage::create("msg-a", "Event", b"{}".to_vec()).unwrap();
-        first.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(1);
-        let mut messages = vec![later, second, first];
-
-        sort_by_claim_order(&mut messages);
-
-        assert_eq!(
-            messages
-                .iter()
-                .map(|message| message.id())
-                .collect::<Vec<_>>(),
-            vec!["msg-a", "msg-b", "msg-c"]
-        );
-    }
-
-    #[tokio::test]
-    async fn backlog_stats_counts_pending_and_tracks_oldest_created_at() {
-        let repo = InMemoryRepository::new();
-        let mut older = OutboxMessage::create("msg-a", "Event", b"{}".to_vec()).unwrap();
-        older.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(1);
-        let mut newer = OutboxMessage::create("msg-b", "Event", b"{}".to_vec()).unwrap();
-        newer.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(10);
-        let mut settled = OutboxMessage::create("msg-c", "Event", b"{}".to_vec()).unwrap();
-        settled.fail("done".to_string()).unwrap();
-        store_message(&repo, newer).await;
-        store_message(&repo, settled).await;
-        store_message(&repo, older).await;
-
-        let stats = repo.outbox_store().backlog_stats().await.unwrap();
-
-        assert_eq!(
-            stats,
-            OutboxBacklogStats {
-                pending: 2,
-                oldest_created_at: Some(SystemTime::UNIX_EPOCH + Duration::from_secs(1)),
-            }
-        );
-    }
-
-    /// The default `backlog_stats` must honor the mandatory listing bound —
-    /// a store that only implements the required methods must never see an
-    /// unbounded (`usize::MAX`) page-in from the gauge path.
-    #[tokio::test]
-    async fn default_backlog_stats_scan_is_bounded() {
-        struct LimitProbeStore;
-
-        impl OutboxStore for LimitProbeStore {
-            fn messages_by_status(
-                &self,
-                _status: OutboxMessageStatus,
-                limit: usize,
-            ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + '_
-            {
-                async move {
-                    assert_eq!(limit, BACKLOG_STATS_SCAN_LIMIT);
-                    Ok(Vec::new())
-                }
-            }
-
-            fn claim<'a>(
-                &'a self,
-                _request: ClaimOutboxMessages,
-            ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + 'a
-            {
-                async move { unimplemented!("probe store only lists") }
-            }
-
-            fn complete<'a>(
-                &'a self,
-                _claim: &'a OutboxClaimRef,
-            ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-                async move { unimplemented!("probe store only lists") }
-            }
-
-            fn release<'a>(
-                &'a self,
-                _claim: &'a OutboxClaimRef,
-                _error: &'a str,
-            ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-                async move { unimplemented!("probe store only lists") }
-            }
-
-            fn fail<'a>(
-                &'a self,
-                _claim: &'a OutboxClaimRef,
-                _error: &'a str,
-            ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-                async move { unimplemented!("probe store only lists") }
-            }
-        }
-
-        let stats = LimitProbeStore.backlog_stats().await.unwrap();
-        assert_eq!(stats, OutboxBacklogStats::default());
-    }
-
-    #[tokio::test]
-    async fn competing_workers_only_claim_message_once() {
-        let repo = InMemoryRepository::new();
-        let message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
-        let id = store_message(&repo, message).await;
-
-        let barrier = Arc::new(Barrier::new(3));
-        let store_a = repo.outbox_store();
-        let store_b = repo.outbox_store();
-        let barrier_a = Arc::clone(&barrier);
-        let barrier_b = Arc::clone(&barrier);
-
-        let worker_a = thread::spawn(move || {
-            barrier_a.wait();
-            let rt = tokio::runtime::Runtime::new().unwrap();
-            rt.block_on(store_a.claim(ClaimOutboxMessages::new(
-                "worker-a",
-                1,
-                Duration::from_secs(60),
-            )))
-            .unwrap()
-            .len()
-        });
-        let worker_b = thread::spawn(move || {
-            barrier_b.wait();
-            let rt = tokio::runtime::Runtime::new().unwrap();
-            rt.block_on(store_b.claim(ClaimOutboxMessages::new(
-                "worker-b",
-                1,
-                Duration::from_secs(60),
-            )))
-            .unwrap()
-            .len()
-        });
-
-        barrier.wait();
-        let total_claimed = worker_a.join().unwrap() + worker_b.join().unwrap();
-
-        assert_eq!(total_claimed, 1);
-        let stored = load_message(&repo, &id);
-        assert!(stored.is_in_flight());
-        assert_eq!(stored.attempts, 1);
-    }
-
-    #[tokio::test]
-    async fn publish_failure_releases_until_retry_ceiling_then_fails() {
-        let repo = InMemoryRepository::new();
-        let message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
-        let id = store_message(&repo, message).await;
-
-        let store = repo.outbox_store();
-        let claimed = store
-            .claim(ClaimOutboxMessages::new(
-                "worker-1",
-                1,
-                Duration::from_secs(60),
-            ))
-            .await
-            .unwrap();
-        let claim = OutboxClaimRef::from_message(&claimed[0]).unwrap();
-        let action = store
-            .record_failure(&claim, "first failure", 2)
-            .await
-            .unwrap();
-        assert_eq!(action, OutboxPublishFailureAction::Released);
-
-        let stored = load_message(&repo, &id);
-        assert!(stored.is_pending());
-        assert_eq!(stored.attempts, 1);
-        assert_eq!(stored.last_error.as_deref(), Some("first failure"));
-
-        let claimed = store
-            .claim(ClaimOutboxMessages::new(
-                "worker-1",
-                1,
-                Duration::from_secs(60),
-            ))
-            .await
-            .unwrap();
-        let claim = OutboxClaimRef::from_message(&claimed[0]).unwrap();
-        let action = store
-            .record_failure(&claim, "second failure", 2)
-            .await
-            .unwrap();
-        assert_eq!(action, OutboxPublishFailureAction::Failed);
-
-        let stored = load_message(&repo, &id);
-        assert!(stored.is_failed());
-        assert_eq!(stored.attempts, 2);
-        assert_eq!(stored.last_error.as_deref(), Some("second failure"));
-    }
-
-    #[tokio::test]
-    async fn missing_message_updates_return_not_found() {
-        let store = InMemoryOutboxStore {
-            storage: Default::default(),
-        };
-        let claim = OutboxClaimRef {
-            message_id: "missing".into(),
-            worker_id: "worker-1".into(),
-            leased_until: SystemTime::now(),
-            attempt: 1,
-        };
-
-        let is_missing = |err: RepositoryError| matches!(&err, RepositoryError::NotFound { id } if id == "missing");
-        assert!(is_missing(store.complete(&claim).await.unwrap_err()));
-        assert!(is_missing(
-            store.release(&claim, "error").await.unwrap_err()
-        ));
-        assert!(is_missing(store.fail(&claim, "error").await.unwrap_err()));
-    }
-
-    #[tokio::test]
-    async fn stale_or_mismatched_claims_cannot_be_completed() {
-        let repo = InMemoryRepository::new();
-        let message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
-        let _id = store_message(&repo, message).await;
-
-        let store = repo.outbox_store();
-        let claimed = store
-            .claim(ClaimOutboxMessages::new(
-                "worker-1",
-                1,
-                Duration::from_secs(60),
-            ))
-            .await
-            .unwrap();
-        let mut claim = OutboxClaimRef::from_message(&claimed[0]).unwrap();
-        claim.worker_id = "worker-2".into();
-        let err = store.complete(&claim).await.unwrap_err();
-        assert!(matches!(err, RepositoryError::InvalidState { .. }));
-
-        let mut expired = OutboxMessage::create("msg-2", "Event", b"{}".to_vec()).unwrap();
-        expired
-            .claim_at("worker-1", Duration::from_secs(1), SystemTime::UNIX_EPOCH)
-            .unwrap();
-        let expired_id = store_message(&repo, expired).await;
-        let expired = load_message(&repo, &expired_id);
-        let claim = OutboxClaimRef::from_message(&expired).unwrap();
-        let err = store.complete(&claim).await.unwrap_err();
-        assert!(matches!(err, RepositoryError::InvalidState { .. }));
-    }
-
-    #[tokio::test]
-    async fn stale_attempt_claims_cannot_complete_later_claims() {
-        let repo = InMemoryRepository::new();
-        let message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
-        let _id = store_message(&repo, message).await;
-
-        let store = repo.outbox_store();
-        let claimed = store
-            .claim(ClaimOutboxMessages::new(
-                "worker-1",
-                1,
-                Duration::from_secs(60),
-            ))
-            .await
-            .unwrap();
-        let stale_claim = OutboxClaimRef::from_message(&claimed[0]).unwrap();
-        store.release(&stale_claim, "retry").await.unwrap();
-
-        let claimed = store
-            .claim(ClaimOutboxMessages::new(
-                "worker-1",
-                1,
-                Duration::from_secs(60),
-            ))
-            .await
-            .unwrap();
-        let current_claim = OutboxClaimRef::from_message(&claimed[0]).unwrap();
-
-        let err = store.complete(&stale_claim).await.unwrap_err();
-        assert!(matches!(err, RepositoryError::InvalidState { .. }));
-        store.complete(&current_claim).await.unwrap();
-    }
-
-    #[tokio::test]
-    async fn complete_many_completes_the_whole_batch() {
-        let repo = InMemoryRepository::new();
-        for id in ["msg-1", "msg-2", "msg-3"] {
-            store_message(
-                &repo,
-                OutboxMessage::create(id, "Event", b"{}".to_vec()).unwrap(),
-            )
-            .await;
-        }
-
-        let store = repo.outbox_store();
-        let claimed = store
-            .claim(ClaimOutboxMessages::new(
-                "worker-1",
-                3,
-                Duration::from_secs(60),
-            ))
-            .await
-            .unwrap();
-        let claims = claimed
-            .iter()
-            .map(OutboxClaimRef::from_message)
-            .collect::<Result<Vec<_>, _>>()
-            .unwrap();
-
-        store.complete_many(&claims).await.unwrap();
-
-        for id in ["msg-1", "msg-2", "msg-3"] {
-            assert!(load_message(&repo, id).is_published());
-        }
-    }
-
-    #[tokio::test]
-    async fn complete_many_rejects_stale_and_missing_claims() {
-        let repo = InMemoryRepository::new();
-        store_message(
-            &repo,
-            OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap(),
-        )
-        .await;
-
-        let store = repo.outbox_store();
-        let claimed = store
-            .claim(ClaimOutboxMessages::new(
-                "worker-1",
-                1,
-                Duration::from_secs(60),
-            ))
-            .await
-            .unwrap();
-        let claims = vec![OutboxClaimRef::from_message(&claimed[0]).unwrap()];
-
-        store.complete_many(&claims).await.unwrap();
-        // Re-settling the now-published row is a stale claim, same as `complete`.
-        let err = store.complete_many(&claims).await.unwrap_err();
-        assert!(matches!(err, RepositoryError::InvalidState { .. }));
-
-        let missing = vec![OutboxClaimRef {
-            message_id: "missing".into(),
-            worker_id: "worker-1".into(),
-            leased_until: SystemTime::now(),
-            attempt: 1,
-        }];
-        let err = store.complete_many(&missing).await.unwrap_err();
-        assert!(matches!(err, RepositoryError::NotFound { id } if id == "missing"));
-    }
-
-    #[tokio::test]
-    async fn already_published_message_is_not_completed_again() {
-        let repo = InMemoryRepository::new();
-        let message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
-        let _id = store_message(&repo, message).await;
-
-        let store = repo.outbox_store();
-        let claimed = store
-            .claim(ClaimOutboxMessages::new(
-                "worker-1",
-                1,
-                Duration::from_secs(60),
-            ))
-            .await
-            .unwrap();
-        let claim = OutboxClaimRef::from_message(&claimed[0]).unwrap();
-        store.complete(&claim).await.unwrap();
-
-        let err = store.complete(&claim).await.unwrap_err();
-        assert!(matches!(err, RepositoryError::InvalidState { .. }));
-    }
-}
diff --git a/src/outbox_worker/store/api.rs b/src/outbox_worker/store/api.rs
new file mode 100644
index 00000000..75e21b60
--- /dev/null
+++ b/src/outbox_worker/store/api.rs
@@ -0,0 +1,282 @@
+use std::future::Future;
+use std::time::{Duration, SystemTime};
+
+use crate::outbox::{OutboxMessage, OutboxMessageStatus};
+use crate::repository::RepositoryError;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OutboxPublishFailureAction {
+    Released,
+    Failed,
+}
+
+/// Lightweight outbox backlog summary for metrics and diagnostics.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct OutboxBacklogStats {
+    /// Number of rows currently in the pending status.
+    pub pending: usize,
+    /// Creation time of the oldest pending row, when any pending rows exist.
+    pub oldest_created_at: Option<SystemTime>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ClaimOutboxMessages {
+    pub worker_id: String,
+    pub batch_size: usize,
+    pub lease: Duration,
+    pub destination: Option<String>,
+    /// Restrict the claim to this explicit set of message ids. `None` claims the
+    /// next claimable batch in created-at order (normal worker polling); `Some`
+    /// claims only the listed ids (after-commit immediate dispatch). Ids that are
+    /// not currently claimable are simply skipped — a raced id is not an error.
+    pub message_ids: Option<Vec<String>>,
+}
+
+impl ClaimOutboxMessages {
+    pub fn new(worker_id: impl Into<String>, batch_size: usize, lease: Duration) -> Self {
+        Self {
+            worker_id: worker_id.into(),
+            batch_size,
+            lease,
+            destination: None,
+            message_ids: None,
+        }
+    }
+
+    pub fn to_destination(mut self, destination: impl Into<String>) -> Self {
+        self.destination = Some(destination.into());
+        self
+    }
+
+    /// Restrict this claim to an explicit list of message ids (after-commit
+    /// immediate dispatch). The batch size is bounded by the id count.
+    pub fn for_ids(worker_id: impl Into<String>, ids: Vec<String>, lease: Duration) -> Self {
+        Self {
+            worker_id: worker_id.into(),
+            batch_size: ids.len(),
+            lease,
+            destination: None,
+            message_ids: Some(ids),
+        }
+    }
+
+    /// Whether `id` is selectable under this request's id filter.
+    pub(super) fn selects(&self, id: &str) -> bool {
+        match &self.message_ids {
+            Some(ids) => ids.iter().any(|wanted| wanted == id),
+            None => true,
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct OutboxClaimRef {
+    pub message_id: String,
+    pub worker_id: String,
+    pub leased_until: SystemTime,
+    pub attempt: u32,
+}
+
+impl OutboxClaimRef {
+    pub fn from_message(message: &OutboxMessage) -> Result<Self, RepositoryError> {
+        let worker_id = message
+            .worker_id
+            .clone()
+            .ok_or_else(|| invalid_outbox_state(message, "outbox claim worker"))?;
+        let leased_until = message
+            .leased_until
+            .ok_or_else(|| invalid_outbox_state(message, "outbox claim lease"))?;
+
+        Ok(Self {
+            message_id: message.id().to_string(),
+            worker_id,
+            leased_until,
+            attempt: message.attempts,
+        })
+    }
+}
+
+/// Row bound for the default [`backlog_stats`] scan.
+///
+/// [`backlog_stats`]: OutboxStore::backlog_stats
+pub const BACKLOG_STATS_SCAN_LIMIT: usize = 1000;
+
+/// Store capability for claiming and updating durable outbox messages.
+pub trait OutboxStore: Send + Sync {
+    /// List up to `limit` messages with the given status, in claim order
+    /// (created-at, then message id). The listing is a diagnostic/ops read, so
+    /// the bound is mandatory: an outbox can grow far beyond what any caller
+    /// should page into memory at once.
+    fn messages_by_status(
+        &self,
+        status: OutboxMessageStatus,
+        limit: usize,
+    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + '_;
+
+    /// List up to `limit` pending messages (see [`messages_by_status`]).
+    ///
+    /// [`messages_by_status`]: OutboxStore::messages_by_status
+    fn pending(
+        &self,
+        limit: usize,
+    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + '_ {
+        async move {
+            self.messages_by_status(OutboxMessageStatus::Pending, limit)
+                .await
+        }
+    }
+
+    /// Return pending-row count and oldest pending creation time without
+    /// requiring callers to page full rows. Backends with query support should
+    /// override this with `COUNT`/`MIN(created_at)` or equivalent (both
+    /// in-tree stores do).
+    ///
+    /// The default pages up to [`BACKLOG_STATS_SCAN_LIMIT`] pending rows —
+    /// never the whole outbox, per the bound contract on
+    /// [`messages_by_status`]. The count saturates at that limit; the oldest
+    /// creation time stays exact because pending listings are in claim
+    /// (oldest-first) order.
+    ///
+    /// [`messages_by_status`]: OutboxStore::messages_by_status
+    fn backlog_stats(
+        &self,
+    ) -> impl Future<Output = Result<OutboxBacklogStats, RepositoryError>> + Send + '_ {
+        async move {
+            let pending = self.pending(BACKLOG_STATS_SCAN_LIMIT).await?;
+            let oldest_created_at = pending.first().map(|message| message.created_at);
+            Ok(OutboxBacklogStats {
+                pending: pending.len(),
+                oldest_created_at,
+            })
+        }
+    }
+
+    fn claim<'a>(
+        &'a self,
+        request: ClaimOutboxMessages,
+    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + 'a;
+
+    fn complete<'a>(
+        &'a self,
+        claim: &'a OutboxClaimRef,
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a;
+
+    /// Complete a batch of claims after their rows were published.
+    ///
+    /// Equivalent to calling [`complete`] for each claim; backends override it
+    /// to settle the batch in fewer round trips (one statement/transaction).
+    /// Error semantics match the serial loop: a claim that is no longer
+    /// completable (missing row, stale worker/attempt, expired lease) surfaces
+    /// the same `NotFound`/`InvalidState` error, and other claims in the batch
+    /// may already have been completed when the error is returned.
+    ///
+    /// [`complete`]: OutboxStore::complete
+    fn complete_many<'a>(
+        &'a self,
+        claims: &'a [OutboxClaimRef],
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+        async move {
+            for claim in claims {
+                self.complete(claim).await?;
+            }
+            Ok(())
+        }
+    }
+
+    fn release<'a>(
+        &'a self,
+        claim: &'a OutboxClaimRef,
+        error: &'a str,
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a;
+
+    fn fail<'a>(
+        &'a self,
+        claim: &'a OutboxClaimRef,
+        error: &'a str,
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a;
+
+    fn record_failure<'a>(
+        &'a self,
+        claim: &'a OutboxClaimRef,
+        error: &'a str,
+        max_attempts: u32,
+    ) -> impl Future<Output = Result<OutboxPublishFailureAction, RepositoryError>> + Send + 'a {
+        async move {
+            if claim.attempt >= max_attempts {
+                self.fail(claim, error).await?;
+                Ok(OutboxPublishFailureAction::Failed)
+            } else {
+                self.release(claim, error).await?;
+                Ok(OutboxPublishFailureAction::Released)
+            }
+        }
+    }
+}
+
+fn outbox_state(message: &OutboxMessage) -> String {
+    format!(
+        "{:?}, worker={:?}, leased_until={:?}, attempts={}",
+        message.status, message.worker_id, message.leased_until, message.attempts
+    )
+}
+
+fn invalid_outbox_state(message: &OutboxMessage, expected: &'static str) -> RepositoryError {
+    RepositoryError::InvalidState {
+        id: message.id().to_string(),
+        expected,
+        actual: outbox_state(message),
+    }
+}
+
+pub(crate) fn ensure_active_claim(
+    message: &OutboxMessage,
+    claim: Option<&OutboxClaimRef>,
+    now: SystemTime,
+) -> Result<(), RepositoryError> {
+    if !message.is_in_flight() {
+        return Err(invalid_outbox_state(message, "in-flight outbox message"));
+    }
+
+    if let Some(claim) = claim {
+        if !message.is_claimed_by(&claim.worker_id) {
+            return Err(invalid_outbox_state(
+                message,
+                "outbox claim held by requesting worker",
+            ));
+        }
+
+        if message.attempts != claim.attempt {
+            return Err(invalid_outbox_state(
+                message,
+                "outbox claim attempt held by requesting worker",
+            ));
+        }
+    }
+
+    if message.has_expired_lease_at(now) {
+        return Err(invalid_outbox_state(message, "unexpired outbox claim"));
+    }
+
+    Ok(())
+}
+
+/// Claim order: oldest row first, message id as the deterministic tiebreaker.
+/// The single definition both claim-order helpers sort by.
+fn claim_order_key(message: &OutboxMessage) -> (SystemTime, &str) {
+    (message.created_at, message.id())
+}
+
+pub(crate) fn sort_by_claim_order(messages: &mut [OutboxMessage]) {
+    messages.sort_by(|left, right| claim_order_key(left).cmp(&claim_order_key(right)));
+}
+
+pub(crate) fn claim_order_ids<'a>(
+    messages: impl Iterator<Item = &'a OutboxMessage>,
+) -> Vec<String> {
+    let mut messages: Vec<&OutboxMessage> = messages.collect();
+    messages.sort_by(|left, right| claim_order_key(left).cmp(&claim_order_key(right)));
+    messages
+        .into_iter()
+        .map(|message| message.id().to_string())
+        .collect()
+}
diff --git a/src/outbox_worker/store/in_memory.rs b/src/outbox_worker/store/in_memory.rs
new file mode 100644
index 00000000..e0b0053b
--- /dev/null
+++ b/src/outbox_worker/store/in_memory.rs
@@ -0,0 +1,198 @@
+use std::future::Future;
+use std::time::SystemTime;
+
+use crate::in_memory_repo::InMemoryOutboxStore;
+use crate::outbox::{OutboxMessage, OutboxMessageStatus};
+use crate::repository::RepositoryError;
+
+use super::{
+    claim_order_ids, ensure_active_claim, sort_by_claim_order, ClaimOutboxMessages,
+    OutboxBacklogStats, OutboxClaimRef, OutboxStore,
+};
+
+impl InMemoryOutboxStore {
+    fn update_outbox_message<T>(
+        &self,
+        message_id: &str,
+        update: impl FnOnce(&mut OutboxMessage) -> Result<T, RepositoryError>,
+    ) -> Result<T, RepositoryError> {
+        let mut storage = self
+            .storage
+            .write()
+            .map_err(|_| RepositoryError::LockPoisoned("outbox write"))?;
+
+        let message = storage
+            .get_mut(message_id)
+            .ok_or_else(|| RepositoryError::NotFound {
+                id: message_id.to_string(),
+            })?;
+
+        update(message)
+    }
+}
+
+impl OutboxStore for InMemoryOutboxStore {
+    fn messages_by_status(
+        &self,
+        status: OutboxMessageStatus,
+        limit: usize,
+    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + '_ {
+        async move {
+            let storage = self
+                .storage
+                .read()
+                .map_err(|_| RepositoryError::LockPoisoned("outbox read"))?;
+
+            let mut messages = storage
+                .values()
+                .filter(|message| message.status == status)
+                .cloned()
+                .collect::<Vec<_>>();
+            sort_by_claim_order(&mut messages);
+            messages.truncate(limit);
+            Ok(messages)
+        }
+    }
+
+    fn backlog_stats(
+        &self,
+    ) -> impl Future<Output = Result<OutboxBacklogStats, RepositoryError>> + Send + '_ {
+        async move {
+            let storage = self
+                .storage
+                .read()
+                .map_err(|_| RepositoryError::LockPoisoned("outbox read"))?;
+
+            let mut stats = OutboxBacklogStats::default();
+            for message in storage
+                .values()
+                .filter(|message| message.status == OutboxMessageStatus::Pending)
+            {
+                stats.pending += 1;
+                stats.oldest_created_at = Some(
+                    stats
+                        .oldest_created_at
+                        .map_or(message.created_at, |oldest| oldest.min(message.created_at)),
+                );
+            }
+            Ok(stats)
+        }
+    }
+
+    fn claim<'a>(
+        &'a self,
+        request: ClaimOutboxMessages,
+    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + 'a {
+        async move {
+            let mut storage = self
+                .storage
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("outbox write"))?;
+
+            if request.batch_size == 0 {
+                return Ok(Vec::new());
+            }
+
+            let now = SystemTime::now();
+            let ids = claim_order_ids(storage.values());
+            let mut claimed = Vec::new();
+            for id in ids {
+                if !request.selects(&id) {
+                    continue;
+                }
+
+                let Some(message) = storage.get_mut(&id) else {
+                    continue;
+                };
+
+                if message.is_claimable_at(now) {
+                    if let Some(destination) = request.destination.as_deref() {
+                        if message.destination.as_deref() != Some(destination) {
+                            continue;
+                        }
+                    }
+                    message.claim_at(&request.worker_id, request.lease, now)?;
+                    claimed.push(message.clone());
+                }
+
+                if claimed.len() >= request.batch_size {
+                    break;
+                }
+            }
+
+            Ok(claimed)
+        }
+    }
+
+    fn complete<'a>(
+        &'a self,
+        claim: &'a OutboxClaimRef,
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+        async move {
+            self.update_outbox_message(&claim.message_id, |message| {
+                ensure_active_claim(message, Some(claim), SystemTime::now())?;
+                message.complete()?;
+                Ok(())
+            })
+        }
+    }
+
+    /// Batched complete under a single write lock instead of one lock
+    /// acquisition per claim. Same per-claim validation as [`complete`];
+    /// claims before a failing one stay completed, like the serial loop.
+    ///
+    /// [`complete`]: OutboxStore::complete
+    fn complete_many<'a>(
+        &'a self,
+        claims: &'a [OutboxClaimRef],
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+        async move {
+            if claims.is_empty() {
+                return Ok(());
+            }
+            let mut storage = self
+                .storage
+                .write()
+                .map_err(|_| RepositoryError::LockPoisoned("outbox write"))?;
+            let now = SystemTime::now();
+            for claim in claims {
+                let message = storage.get_mut(&claim.message_id).ok_or_else(|| {
+                    RepositoryError::NotFound {
+                        id: claim.message_id.clone(),
+                    }
+                })?;
+                ensure_active_claim(message, Some(claim), now)?;
+                message.complete()?;
+            }
+            Ok(())
+        }
+    }
+
+    fn release<'a>(
+        &'a self,
+        claim: &'a OutboxClaimRef,
+        error: &'a str,
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+        async move {
+            self.update_outbox_message(&claim.message_id, |message| {
+                ensure_active_claim(message, Some(claim), SystemTime::now())?;
+                message.release(error.to_string())?;
+                Ok(())
+            })
+        }
+    }
+
+    fn fail<'a>(
+        &'a self,
+        claim: &'a OutboxClaimRef,
+        error: &'a str,
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+        async move {
+            self.update_outbox_message(&claim.message_id, |message| {
+                ensure_active_claim(message, Some(claim), SystemTime::now())?;
+                message.fail(error.to_string())?;
+                Ok(())
+            })
+        }
+    }
+}
diff --git a/src/outbox_worker/store/mod.rs b/src/outbox_worker/store/mod.rs
new file mode 100644
index 00000000..fd331668
--- /dev/null
+++ b/src/outbox_worker/store/mod.rs
@@ -0,0 +1,17 @@
+#![expect(
+    clippy::manual_async_fn,
+    reason = "async trait impls return impl Future + Send to preserve public Send bounds"
+)]
+
+mod api;
+mod in_memory;
+
+#[cfg(test)]
+mod tests;
+
+pub use api::{
+    ClaimOutboxMessages, OutboxBacklogStats, OutboxClaimRef, OutboxPublishFailureAction,
+    OutboxStore,
+};
+
+pub(crate) use api::{claim_order_ids, ensure_active_claim, sort_by_claim_order};
diff --git a/src/outbox_worker/store/tests.rs b/src/outbox_worker/store/tests.rs
new file mode 100644
index 00000000..51f5be0c
--- /dev/null
+++ b/src/outbox_worker/store/tests.rs
@@ -0,0 +1,533 @@
+use super::api::BACKLOG_STATS_SCAN_LIMIT;
+use super::*;
+use crate::{
+    CommitBatch, InMemoryOutboxStore, InMemoryRepository, OutboxMessage, OutboxMessageStatus,
+    RepositoryError, TransactionalCommit,
+};
+use std::future::Future;
+use std::sync::{Arc, Barrier};
+use std::thread;
+use std::time::{Duration, SystemTime};
+
+async fn store_message(repo: &InMemoryRepository, message: OutboxMessage) -> String {
+    let id = message.id().to_string();
+    let mut batch = CommitBatch::empty();
+    batch.outbox_messages.push(message);
+    repo.commit_batch(batch).await.unwrap();
+    id
+}
+
+fn load_message(repo: &InMemoryRepository, id: &str) -> OutboxMessage {
+    repo.outbox_storage()
+        .read()
+        .unwrap()
+        .get(id)
+        .unwrap()
+        .clone()
+}
+
+#[tokio::test]
+async fn claim_includes_expired_in_flight_messages() {
+    let repo = InMemoryRepository::new();
+    let mut message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
+    message
+        .claim_at("worker-1", Duration::from_secs(1), SystemTime::UNIX_EPOCH)
+        .unwrap();
+    let id = store_message(&repo, message).await;
+
+    let store = repo.outbox_store();
+    let claimed = store
+        .claim(ClaimOutboxMessages::new(
+            "worker-2",
+            1,
+            Duration::from_secs(60),
+        ))
+        .await
+        .unwrap();
+
+    assert_eq!(claimed.len(), 1);
+    assert_eq!(claimed[0].worker_id.as_deref(), Some("worker-2"));
+    assert_eq!(claimed[0].attempts, 2);
+
+    let stored = load_message(&repo, &id);
+    assert_eq!(stored.worker_id.as_deref(), Some("worker-2"));
+    assert_eq!(stored.attempts, 2);
+    assert!(stored.is_in_flight());
+}
+
+#[tokio::test]
+async fn claim_skips_unexpired_in_flight_messages() {
+    let repo = InMemoryRepository::new();
+    let mut message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
+    message
+        .claim_for("worker-1", Duration::from_secs(60))
+        .unwrap();
+    let id = store_message(&repo, message).await;
+
+    let store = repo.outbox_store();
+    let claimed = store
+        .claim(ClaimOutboxMessages::new(
+            "worker-2",
+            1,
+            Duration::from_secs(60),
+        ))
+        .await
+        .unwrap();
+
+    assert!(claimed.is_empty());
+    let stored = load_message(&repo, &id);
+    assert_eq!(stored.worker_id.as_deref(), Some("worker-1"));
+    assert_eq!(stored.attempts, 1);
+}
+
+#[tokio::test]
+async fn claim_uses_created_at_before_message_id_order() {
+    let repo = InMemoryRepository::new();
+    let mut newer = OutboxMessage::create("msg-a", "Event", b"{}".to_vec()).unwrap();
+    newer.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(10);
+    let mut older = OutboxMessage::create("msg-z", "Event", b"{}".to_vec()).unwrap();
+    older.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(1);
+    store_message(&repo, newer).await;
+    store_message(&repo, older).await;
+
+    let claimed = repo
+        .outbox_store()
+        .claim(ClaimOutboxMessages::new(
+            "worker-1",
+            1,
+            Duration::from_secs(60),
+        ))
+        .await
+        .unwrap();
+
+    assert_eq!(claimed[0].id(), "msg-z");
+}
+
+#[tokio::test]
+async fn claim_by_explicit_ids_claims_only_requested() {
+    let repo = InMemoryRepository::new();
+    store_message(
+        &repo,
+        OutboxMessage::create("msg-a", "Event", b"{}".to_vec()).unwrap(),
+    )
+    .await;
+    store_message(
+        &repo,
+        OutboxMessage::create("msg-b", "Event", b"{}".to_vec()).unwrap(),
+    )
+    .await;
+    store_message(
+        &repo,
+        OutboxMessage::create("msg-c", "Event", b"{}".to_vec()).unwrap(),
+    )
+    .await;
+
+    let claimed = repo
+        .outbox_store()
+        .claim(ClaimOutboxMessages::for_ids(
+            "worker-1",
+            vec!["msg-b".to_string(), "msg-c".to_string()],
+            Duration::from_secs(60),
+        ))
+        .await
+        .unwrap();
+
+    let mut claimed_ids = claimed
+        .iter()
+        .map(|m| m.id().to_string())
+        .collect::<Vec<_>>();
+    claimed_ids.sort();
+    assert_eq!(claimed_ids, vec!["msg-b".to_string(), "msg-c".to_string()]);
+    // The unrequested row stays pending.
+    assert!(load_message(&repo, "msg-a").is_pending());
+}
+
+#[tokio::test]
+async fn claim_by_ids_skips_unclaimable_without_error() {
+    let repo = InMemoryRepository::new();
+    let mut leased = OutboxMessage::create("msg-a", "Event", b"{}".to_vec()).unwrap();
+    leased
+        .claim_for("other-worker", Duration::from_secs(60))
+        .unwrap();
+    store_message(&repo, leased).await;
+
+    // Requesting a currently-leased id (and a missing id) yields no claim,
+    // not an error.
+    let claimed = repo
+        .outbox_store()
+        .claim(ClaimOutboxMessages::for_ids(
+            "worker-1",
+            vec!["msg-a".to_string(), "missing".to_string()],
+            Duration::from_secs(60),
+        ))
+        .await
+        .unwrap();
+
+    assert!(claimed.is_empty());
+}
+
+#[test]
+fn sort_by_claim_order_uses_message_id_tiebreaker() {
+    let mut later = OutboxMessage::create("msg-c", "Event", b"{}".to_vec()).unwrap();
+    later.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(10);
+    let mut second = OutboxMessage::create("msg-b", "Event", b"{}".to_vec()).unwrap();
+    second.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(1);
+    let mut first = OutboxMessage::create("msg-a", "Event", b"{}".to_vec()).unwrap();
+    first.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(1);
+    let mut messages = vec![later, second, first];
+
+    sort_by_claim_order(&mut messages);
+
+    assert_eq!(
+        messages
+            .iter()
+            .map(|message| message.id())
+            .collect::<Vec<_>>(),
+        vec!["msg-a", "msg-b", "msg-c"]
+    );
+}
+
+#[tokio::test]
+async fn backlog_stats_counts_pending_and_tracks_oldest_created_at() {
+    let repo = InMemoryRepository::new();
+    let mut older = OutboxMessage::create("msg-a", "Event", b"{}".to_vec()).unwrap();
+    older.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(1);
+    let mut newer = OutboxMessage::create("msg-b", "Event", b"{}".to_vec()).unwrap();
+    newer.created_at = SystemTime::UNIX_EPOCH + Duration::from_secs(10);
+    let mut settled = OutboxMessage::create("msg-c", "Event", b"{}".to_vec()).unwrap();
+    settled.fail("done".to_string()).unwrap();
+    store_message(&repo, newer).await;
+    store_message(&repo, settled).await;
+    store_message(&repo, older).await;
+
+    let stats = repo.outbox_store().backlog_stats().await.unwrap();
+
+    assert_eq!(
+        stats,
+        OutboxBacklogStats {
+            pending: 2,
+            oldest_created_at: Some(SystemTime::UNIX_EPOCH + Duration::from_secs(1)),
+        }
+    );
+}
+
+/// The default `backlog_stats` must honor the mandatory listing bound —
+/// a store that only implements the required methods must never see an
+/// unbounded (`usize::MAX`) page-in from the gauge path.
+#[tokio::test]
+async fn default_backlog_stats_scan_is_bounded() {
+    struct LimitProbeStore;
+
+    impl OutboxStore for LimitProbeStore {
+        fn messages_by_status(
+            &self,
+            _status: OutboxMessageStatus,
+            limit: usize,
+        ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + '_ {
+            async move {
+                assert_eq!(limit, BACKLOG_STATS_SCAN_LIMIT);
+                Ok(Vec::new())
+            }
+        }
+
+        fn claim<'a>(
+            &'a self,
+            _request: ClaimOutboxMessages,
+        ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + 'a {
+            async move { unimplemented!("probe store only lists") }
+        }
+
+        fn complete<'a>(
+            &'a self,
+            _claim: &'a OutboxClaimRef,
+        ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+            async move { unimplemented!("probe store only lists") }
+        }
+
+        fn release<'a>(
+            &'a self,
+            _claim: &'a OutboxClaimRef,
+            _error: &'a str,
+        ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+            async move { unimplemented!("probe store only lists") }
+        }
+
+        fn fail<'a>(
+            &'a self,
+            _claim: &'a OutboxClaimRef,
+            _error: &'a str,
+        ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+            async move { unimplemented!("probe store only lists") }
+        }
+    }
+
+    let stats = LimitProbeStore.backlog_stats().await.unwrap();
+    assert_eq!(stats, OutboxBacklogStats::default());
+}
+
+#[tokio::test]
+async fn competing_workers_only_claim_message_once() {
+    let repo = InMemoryRepository::new();
+    let message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
+    let id = store_message(&repo, message).await;
+
+    let barrier = Arc::new(Barrier::new(3));
+    let store_a = repo.outbox_store();
+    let store_b = repo.outbox_store();
+    let barrier_a = Arc::clone(&barrier);
+    let barrier_b = Arc::clone(&barrier);
+
+    let worker_a = thread::spawn(move || {
+        barrier_a.wait();
+        let rt = tokio::runtime::Runtime::new().unwrap();
+        rt.block_on(store_a.claim(ClaimOutboxMessages::new(
+            "worker-a",
+            1,
+            Duration::from_secs(60),
+        )))
+        .unwrap()
+        .len()
+    });
+    let worker_b = thread::spawn(move || {
+        barrier_b.wait();
+        let rt = tokio::runtime::Runtime::new().unwrap();
+        rt.block_on(store_b.claim(ClaimOutboxMessages::new(
+            "worker-b",
+            1,
+            Duration::from_secs(60),
+        )))
+        .unwrap()
+        .len()
+    });
+
+    barrier.wait();
+    let total_claimed = worker_a.join().unwrap() + worker_b.join().unwrap();
+
+    assert_eq!(total_claimed, 1);
+    let stored = load_message(&repo, &id);
+    assert!(stored.is_in_flight());
+    assert_eq!(stored.attempts, 1);
+}
+
+#[tokio::test]
+async fn publish_failure_releases_until_retry_ceiling_then_fails() {
+    let repo = InMemoryRepository::new();
+    let message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
+    let id = store_message(&repo, message).await;
+
+    let store = repo.outbox_store();
+    let claimed = store
+        .claim(ClaimOutboxMessages::new(
+            "worker-1",
+            1,
+            Duration::from_secs(60),
+        ))
+        .await
+        .unwrap();
+    let claim = OutboxClaimRef::from_message(&claimed[0]).unwrap();
+    let action = store
+        .record_failure(&claim, "first failure", 2)
+        .await
+        .unwrap();
+    assert_eq!(action, OutboxPublishFailureAction::Released);
+
+    let stored = load_message(&repo, &id);
+    assert!(stored.is_pending());
+    assert_eq!(stored.attempts, 1);
+    assert_eq!(stored.last_error.as_deref(), Some("first failure"));
+
+    let claimed = store
+        .claim(ClaimOutboxMessages::new(
+            "worker-1",
+            1,
+            Duration::from_secs(60),
+        ))
+        .await
+        .unwrap();
+    let claim = OutboxClaimRef::from_message(&claimed[0]).unwrap();
+    let action = store
+        .record_failure(&claim, "second failure", 2)
+        .await
+        .unwrap();
+    assert_eq!(action, OutboxPublishFailureAction::Failed);
+
+    let stored = load_message(&repo, &id);
+    assert!(stored.is_failed());
+    assert_eq!(stored.attempts, 2);
+    assert_eq!(stored.last_error.as_deref(), Some("second failure"));
+}
+
+#[tokio::test]
+async fn missing_message_updates_return_not_found() {
+    let store = InMemoryOutboxStore {
+        storage: Default::default(),
+    };
+    let claim = OutboxClaimRef {
+        message_id: "missing".into(),
+        worker_id: "worker-1".into(),
+        leased_until: SystemTime::now(),
+        attempt: 1,
+    };
+
+    let is_missing =
+        |err: RepositoryError| matches!(&err, RepositoryError::NotFound { id } if id == "missing");
+    assert!(is_missing(store.complete(&claim).await.unwrap_err()));
+    assert!(is_missing(
+        store.release(&claim, "error").await.unwrap_err()
+    ));
+    assert!(is_missing(store.fail(&claim, "error").await.unwrap_err()));
+}
+
+#[tokio::test]
+async fn stale_or_mismatched_claims_cannot_be_completed() {
+    let repo = InMemoryRepository::new();
+    let message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
+    let _id = store_message(&repo, message).await;
+
+    let store = repo.outbox_store();
+    let claimed = store
+        .claim(ClaimOutboxMessages::new(
+            "worker-1",
+            1,
+            Duration::from_secs(60),
+        ))
+        .await
+        .unwrap();
+    let mut claim = OutboxClaimRef::from_message(&claimed[0]).unwrap();
+    claim.worker_id = "worker-2".into();
+    let err = store.complete(&claim).await.unwrap_err();
+    assert!(matches!(err, RepositoryError::InvalidState { .. }));
+
+    let mut expired = OutboxMessage::create("msg-2", "Event", b"{}".to_vec()).unwrap();
+    expired
+        .claim_at("worker-1", Duration::from_secs(1), SystemTime::UNIX_EPOCH)
+        .unwrap();
+    let expired_id = store_message(&repo, expired).await;
+    let expired = load_message(&repo, &expired_id);
+    let claim = OutboxClaimRef::from_message(&expired).unwrap();
+    let err = store.complete(&claim).await.unwrap_err();
+    assert!(matches!(err, RepositoryError::InvalidState { .. }));
+}
+
+#[tokio::test]
+async fn stale_attempt_claims_cannot_complete_later_claims() {
+    let repo = InMemoryRepository::new();
+    let message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
+    let _id = store_message(&repo, message).await;
+
+    let store = repo.outbox_store();
+    let claimed = store
+        .claim(ClaimOutboxMessages::new(
+            "worker-1",
+            1,
+            Duration::from_secs(60),
+        ))
+        .await
+        .unwrap();
+    let stale_claim = OutboxClaimRef::from_message(&claimed[0]).unwrap();
+    store.release(&stale_claim, "retry").await.unwrap();
+
+    let claimed = store
+        .claim(ClaimOutboxMessages::new(
+            "worker-1",
+            1,
+            Duration::from_secs(60),
+        ))
+        .await
+        .unwrap();
+    let current_claim = OutboxClaimRef::from_message(&claimed[0]).unwrap();
+
+    let err = store.complete(&stale_claim).await.unwrap_err();
+    assert!(matches!(err, RepositoryError::InvalidState { .. }));
+    store.complete(&current_claim).await.unwrap();
+}
+
+#[tokio::test]
+async fn complete_many_completes_the_whole_batch() {
+    let repo = InMemoryRepository::new();
+    for id in ["msg-1", "msg-2", "msg-3"] {
+        store_message(
+            &repo,
+            OutboxMessage::create(id, "Event", b"{}".to_vec()).unwrap(),
+        )
+        .await;
+    }
+
+    let store = repo.outbox_store();
+    let claimed = store
+        .claim(ClaimOutboxMessages::new(
+            "worker-1",
+            3,
+            Duration::from_secs(60),
+        ))
+        .await
+        .unwrap();
+    let claims = claimed
+        .iter()
+        .map(OutboxClaimRef::from_message)
+        .collect::<Result<Vec<_>, _>>()
+        .unwrap();
+
+    store.complete_many(&claims).await.unwrap();
+
+    for id in ["msg-1", "msg-2", "msg-3"] {
+        assert!(load_message(&repo, id).is_published());
+    }
+}
+
+#[tokio::test]
+async fn complete_many_rejects_stale_and_missing_claims() {
+    let repo = InMemoryRepository::new();
+    store_message(
+        &repo,
+        OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap(),
+    )
+    .await;
+
+    let store = repo.outbox_store();
+    let claimed = store
+        .claim(ClaimOutboxMessages::new(
+            "worker-1",
+            1,
+            Duration::from_secs(60),
+        ))
+        .await
+        .unwrap();
+    let claims = vec![OutboxClaimRef::from_message(&claimed[0]).unwrap()];
+
+    store.complete_many(&claims).await.unwrap();
+    // Re-settling the now-published row is a stale claim, same as `complete`.
+    let err = store.complete_many(&claims).await.unwrap_err();
+    assert!(matches!(err, RepositoryError::InvalidState { .. }));
+
+    let missing = vec![OutboxClaimRef {
+        message_id: "missing".into(),
+        worker_id: "worker-1".into(),
+        leased_until: SystemTime::now(),
+        attempt: 1,
+    }];
+    let err = store.complete_many(&missing).await.unwrap_err();
+    assert!(matches!(err, RepositoryError::NotFound { id } if id == "missing"));
+}
+
+#[tokio::test]
+async fn already_published_message_is_not_completed_again() {
+    let repo = InMemoryRepository::new();
+    let message = OutboxMessage::create("msg-1", "Event", b"{}".to_vec()).unwrap();
+    let _id = store_message(&repo, message).await;
+
+    let store = repo.outbox_store();
+    let claimed = store
+        .claim(ClaimOutboxMessages::new(
+            "worker-1",
+            1,
+            Duration::from_secs(60),
+        ))
+        .await
+        .unwrap();
+    let claim = OutboxClaimRef::from_message(&claimed[0]).unwrap();
+    store.complete(&claim).await.unwrap();
+
+    let err = store.complete(&claim).await.unwrap_err();
+    assert!(matches!(err, RepositoryError::InvalidState { .. }));
+}
diff --git a/src/postgres_repo/mod.rs b/src/postgres_repo/mod.rs
index 3fc6f7ef..56879686 100644
--- a/src/postgres_repo/mod.rs
+++ b/src/postgres_repo/mod.rs
@@ -33,11 +33,23 @@ use crate::table::{
 };
 
 static POSTGRES_MIGRATOR: LazyLock<Migrator> = LazyLock::new(|| {
-    embedded_migrator(&[(
-        1,
-        "initial",
-        include_str!("../../migrations/postgres/0001_initial.sql"),
-    )])
+    embedded_migrator(&[
+        (
+            1,
+            "initial",
+            include_str!("../../migrations/postgres/0001_initial.sql"),
+        ),
+        (
+            2,
+            "command ledger",
+            include_str!("../../migrations/postgres/0002_command_ledger.sql"),
+        ),
+        (
+            3,
+            "projection protocol",
+            include_str!("../../migrations/postgres/0003_projection_protocol.sql"),
+        ),
+    ])
 });
 const POSTGRES_BACKEND: &str = "postgres";
 const BIGINT_STORAGE: &str = "bigint storage";
@@ -61,6 +73,17 @@ impl crate::sqlx_repo::repo::SqlxRepoBackend for Postgres {
     // must re-read stream versions over the pool (a separate connection).
     const CONFLICT_REREAD_IN_TX: bool = false;
     const NOW: &'static str = "now()";
+    const COMMAND_LEDGER_SELECT: &'static str = "command_name, command_contract_hash, \
+         input_hash, state, causation_id, attempt_token, attempt_number, \
+         EXTRACT(EPOCH FROM lease_expires_at)::double precision AS lease_expires_at, \
+         outcome::text AS outcome, \
+         EXTRACT(EPOCH FROM created_at)::double precision AS created_at, \
+         EXTRACT(EPOCH FROM updated_at)::double precision AS updated_at, \
+         EXTRACT(EPOCH FROM completed_at)::double precision AS completed_at, \
+         EXTRACT(EPOCH FROM retention_expires_at)::double precision AS retention_expires_at, \
+         EXTRACT(EPOCH FROM compacted_at)::double precision AS compacted_at";
+    const COMMAND_LEDGER_LOCK_SUFFIX: &'static str = " FOR UPDATE";
+    const COMMAND_LEDGER_COMPACTION_LOCK_SUFFIX: &'static str = " FOR UPDATE SKIP LOCKED";
     const EVENT_SELECT: &'static str = "event_name, \
          event_version, \
          payload, \
@@ -148,6 +171,25 @@ impl crate::sqlx_repo::repo::SqlxRepoBackend for Postgres {
         builder.push(")");
     }
 
+    fn push_command_ledger_now(builder: &mut QueryBuilder<Postgres>) {
+        builder.push("clock_timestamp()");
+    }
+
+    fn push_command_ledger_now_epoch(builder: &mut QueryBuilder<Postgres>) {
+        builder.push("EXTRACT(EPOCH FROM clock_timestamp())::double precision");
+    }
+
+    fn push_command_ledger_deadline(builder: &mut QueryBuilder<Postgres>, duration: Duration) {
+        builder.push("(clock_timestamp() + make_interval(secs => ");
+        builder.push_bind(duration.as_secs_f64());
+        builder.push("))");
+    }
+
+    fn push_command_ledger_json(builder: &mut QueryBuilder<Postgres>, json: &str) {
+        builder.push_bind(json);
+        builder.push("::jsonb");
+    }
+
     fn decode_timestamp(
         row: &sqlx::postgres::PgRow,
         column: &'static str,
@@ -433,6 +475,35 @@ impl crate::sqlx_repo::read_model::SqlxReadModelBackend for Postgres {
             }
         })
     }
+
+    #[allow(clippy::manual_async_fn)]
+    fn push_change_notify<'e, E>(
+        executor: E,
+        tables: &std::collections::BTreeSet<String>,
+    ) -> impl std::future::Future<Output = Result<(), ReadModelError>> + Send
+    where
+        E: sqlx::Executor<'e, Database = Postgres> + Send,
+    {
+        async move {
+            if tables.is_empty() {
+                return Ok(());
+            }
+            let payload = serde_json::to_string(&tables.iter().collect::<Vec<_>>())
+                .map_err(|err| ReadModelError::Serde(err.to_string()))?;
+            sqlx::query("SELECT pg_notify('distributed_read_model_changes', $1)")
+                .bind(payload)
+                .execute(executor)
+                .await
+                .map_err(|err| {
+                    crate::sqlx_repo::read_model_storage_error(
+                        "postgres",
+                        "pg_notify read model changes",
+                        err,
+                    )
+                })?;
+            Ok(())
+        }
+    }
 }
 
 fn push_postgres_type_cast(builder: &mut QueryBuilder<Postgres>, column: &ColumnDef) {
diff --git a/src/projection_protocol.rs b/src/projection_protocol.rs
new file mode 100644
index 00000000..ffb637d4
--- /dev/null
+++ b/src/projection_protocol.rs
@@ -0,0 +1,1617 @@
+//! Adapter-neutral identities and ordering vocabulary for durable projections.
+//!
+//! These types deliberately separate three different notions of progress:
+//!
+//! - [`ProjectionInputCursor`] orders trusted inputs from one exact source;
+//! - [`RecordRevision`] orders versions of one exact projected record; and
+//! - [`ProjectionChangeCursor`] orders durable changes emitted by a projector.
+//!
+//! None of them derives order from message IDs, timestamps, or arrival order.
+//! Cross-scope values are explicitly incomparable.
+
+use std::cmp::Ordering;
+use std::fmt;
+use std::num::{NonZeroU32, NonZeroU64};
+
+use serde::{Deserialize, Serialize};
+
+mod codec;
+mod store;
+mod workspace;
+
+pub(crate) use codec::{
+    compile_projection_topology, CompiledProjectionTopology, ProjectionPartitionSpec,
+    ProjectionScopeCodec,
+};
+use store::domain_separated_digest;
+pub use store::*;
+pub use workspace::ProjectionWorkspace;
+
+/// Maximum UTF-8 byte length of a projector topology name.
+pub const MAX_PROJECTOR_NAME_BYTES: usize = 128;
+/// Maximum UTF-8 byte length of a projection source name.
+pub const MAX_PROJECTION_SOURCE_NAME_BYTES: usize = 128;
+/// Maximum UTF-8 byte length of a projected model name.
+pub const MAX_PROJECTION_MODEL_NAME_BYTES: usize = 128;
+/// Maximum UTF-8 byte length of an opaque cursor epoch.
+pub const MAX_PROJECTION_EPOCH_BYTES: usize = 128;
+/// Maximum length of one canonical projection-partition encoding.
+pub const MAX_PROJECTION_PARTITION_BYTES: usize = 4 * 1024;
+/// Maximum length of one canonical source-partition encoding.
+pub const MAX_PROJECTION_SOURCE_PARTITION_BYTES: usize = 4 * 1024;
+/// Maximum length of one canonical projected-record key encoding.
+pub const MAX_PROJECTION_RECORD_KEY_BYTES: usize = 4 * 1024;
+/// Largest cursor/revision/generation value representable identically by every
+/// supported durable adapter (`INTEGER`/`BIGINT`).
+pub const MAX_PROJECTION_POSITION: u64 = i64::MAX as u64;
+
+const PROJECTION_PARTITION_DIGEST_DOMAIN: &[u8] = b"distributed.projection.partition.v1\0";
+const PROJECTOR_TOPOLOGY_IDENTITY_ENCODING_DOMAIN: &[u8] =
+    b"distributed.projection.topology-identity.v1\0";
+const PROJECTION_SOURCE_NAME_ENCODING_DOMAIN: &[u8] =
+    b"distributed.projection.source-name-encoding.v1\0";
+const PROJECTION_SOURCE_NAME_DIGEST_DOMAIN: &[u8] = b"distributed.projection.source-name.v1\0";
+const PROJECTION_SOURCE_PARTITION_DIGEST_DOMAIN: &[u8] =
+    b"distributed.projection.source-partition.v1\0";
+const PROJECTION_RECORD_KEY_DIGEST_DOMAIN: &[u8] = b"distributed.projection.record-key.v1\0";
+
+/// One declaration-owned projection obligation after every portable command
+/// expression has been resolved against the retained canonical GraphQL input.
+///
+/// The command ledger persists this adapter-neutral value. Projector
+/// registration later lowers it through the same scope codec that encodes
+/// projector-side rows, so there is no second string or key interpretation.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct ResolvedProjectionObligation {
+    pub(crate) projector: String,
+    pub(crate) model: String,
+    pub(crate) key: ResolvedProjectionKey,
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        deserialize_with = "deserialize_present_json_value"
+    )]
+    pub(crate) partition: Option<serde_json::Value>,
+    /// Canonical topology/partition/key identity computed by the bound compiler
+    /// before ledger I/O. Consumers validate the logical fields against this
+    /// exact scope; they never rebind old strings under a newer topology.
+    pub(crate) scope: ProjectionRecordScope,
+}
+
+fn deserialize_present_json_value<'de, D>(
+    deserializer: D,
+) -> Result<Option<serde_json::Value>, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    serde_json::Value::deserialize(deserializer).map(Some)
+}
+
+/// Complete projection key in declaration order.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct ResolvedProjectionKey {
+    pub(crate) fields: Vec<ResolvedProjectionKeyField>,
+}
+
+/// One resolved field in a complete projection key.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct ResolvedProjectionKeyField {
+    pub(crate) field: String,
+    pub(crate) value: serde_json::Value,
+}
+
+/// Invalid adapter-neutral projection protocol input.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ProjectionProtocolValidationError {
+    /// A required string or canonical byte sequence was empty.
+    Empty { field: &'static str },
+    /// A bounded value exceeded its maximum UTF-8/byte length.
+    TooLong {
+        field: &'static str,
+        len: usize,
+        max: usize,
+    },
+    /// An identity name contained whitespace or a control character.
+    InvalidNameCharacter {
+        field: &'static str,
+        byte_index: usize,
+        character: char,
+    },
+    /// An opaque string contained a control character.
+    InvalidOpaqueCharacter {
+        field: &'static str,
+        byte_index: usize,
+        character: char,
+    },
+    /// A value whose protocol domain starts at one was zero.
+    Zero { field: &'static str },
+    /// A numeric protocol value exceeded the cross-adapter signed-BIGINT range.
+    TooLarge {
+        field: &'static str,
+        value: u64,
+        max: u64,
+    },
+    /// Two values combined into one protocol object did not share its scope.
+    ScopeMismatch { field: &'static str },
+    /// Persisted canonical bytes do not conform to the named versioned format.
+    MalformedCanonicalEncoding { field: &'static str },
+}
+
+impl fmt::Display for ProjectionProtocolValidationError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Empty { field } => write!(formatter, "{field} must not be empty"),
+            Self::TooLong { field, len, max } => {
+                write!(
+                    formatter,
+                    "{field} is {len} bytes, exceeding the maximum of {max}"
+                )
+            }
+            Self::InvalidNameCharacter {
+                field,
+                byte_index,
+                character,
+            } => write!(
+                formatter,
+                "{field} contains invalid character {:?} at byte {byte_index}",
+                character.escape_default().to_string()
+            ),
+            Self::InvalidOpaqueCharacter {
+                field,
+                byte_index,
+                character,
+            } => write!(
+                formatter,
+                "{field} contains control character {:?} at byte {byte_index}",
+                character.escape_default().to_string()
+            ),
+            Self::Zero { field } => write!(formatter, "{field} must be greater than zero"),
+            Self::TooLarge { field, value, max } => {
+                write!(
+                    formatter,
+                    "{field} value {value} exceeds the maximum of {max}"
+                )
+            }
+            Self::ScopeMismatch { field } => {
+                write!(
+                    formatter,
+                    "{field} does not match the enclosing projection scope"
+                )
+            }
+            Self::MalformedCanonicalEncoding { field } => {
+                write!(formatter, "{field} has malformed canonical encoding")
+            }
+        }
+    }
+}
+
+impl std::error::Error for ProjectionProtocolValidationError {}
+
+/// Stable identity of one versioned projector topology declaration.
+///
+/// The digest is supplied by the topology compiler because this foundational
+/// layer does not know the declaration's canonical facts/models encoding.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct ProjectorTopologyId {
+    version: NonZeroU32,
+    name: String,
+    digest: [u8; 32],
+}
+
+impl ProjectorTopologyId {
+    /// Build a topology identity from its validated version, name, and
+    /// compiler-produced SHA-256 digest.
+    pub fn new(
+        version: u32,
+        name: impl Into<String>,
+        digest: [u8; 32],
+    ) -> Result<Self, ProjectionProtocolValidationError> {
+        let version = NonZeroU32::new(version).ok_or(ProjectionProtocolValidationError::Zero {
+            field: "projector topology version",
+        })?;
+        let name = validate_name(
+            "projector topology name",
+            name.into(),
+            MAX_PROJECTOR_NAME_BYTES,
+        )?;
+        Ok(Self {
+            version,
+            name,
+            digest,
+        })
+    }
+
+    pub fn version(&self) -> u32 {
+        self.version.get()
+    }
+
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    pub fn digest(&self) -> [u8; 32] {
+        self.digest
+    }
+
+    /// Stable database identity bytes for this exact compiled topology.
+    ///
+    /// The encoding is domain/version tagged and length-prefixes every
+    /// component, including the fixed-width values, so future formats cannot
+    /// alias this one by concatenation.
+    pub fn canonical_bytes(&self) -> Vec<u8> {
+        let version = self.version.get().to_be_bytes();
+        let mut bytes = Vec::with_capacity(
+            PROJECTOR_TOPOLOGY_IDENTITY_ENCODING_DOMAIN.len()
+                + (3 * std::mem::size_of::<u64>())
+                + version.len()
+                + self.name.len()
+                + self.digest.len(),
+        );
+        bytes.extend_from_slice(PROJECTOR_TOPOLOGY_IDENTITY_ENCODING_DOMAIN);
+        append_length_prefixed(&mut bytes, &version);
+        append_length_prefixed(&mut bytes, self.name.as_bytes());
+        append_length_prefixed(&mut bytes, &self.digest);
+        bytes
+    }
+
+    /// Reconstruct an exact compiler identity from adapter-owned canonical
+    /// bytes.
+    ///
+    /// This remains crate-private: public callers select registered projector
+    /// declarations and cannot mint topology authority from database-shaped
+    /// bytes.
+    pub(crate) fn from_canonical_bytes(
+        canonical_bytes: &[u8],
+    ) -> Result<Self, ProjectionProtocolValidationError> {
+        let encoded = canonical_bytes
+            .strip_prefix(PROJECTOR_TOPOLOGY_IDENTITY_ENCODING_DOMAIN)
+            .ok_or(
+                ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                    field: "projector topology identity",
+                },
+            )?;
+        let (version, encoded) = take_length_prefixed(encoded).ok_or(
+            ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                field: "projector topology identity",
+            },
+        )?;
+        let (name, encoded) = take_length_prefixed(encoded).ok_or(
+            ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                field: "projector topology identity",
+            },
+        )?;
+        let (digest, trailing) = take_length_prefixed(encoded).ok_or(
+            ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                field: "projector topology identity",
+            },
+        )?;
+        let version: [u8; std::mem::size_of::<u32>()] = version.try_into().map_err(|_| {
+            ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                field: "projector topology identity",
+            }
+        })?;
+        let name = std::str::from_utf8(name).map_err(|_| {
+            ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                field: "projector topology identity",
+            }
+        })?;
+        let digest: [u8; 32] = digest.try_into().map_err(|_| {
+            ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                field: "projector topology identity",
+            }
+        })?;
+        if !trailing.is_empty() {
+            return Err(
+                ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                    field: "projector topology identity",
+                },
+            );
+        }
+        let topology = Self::new(u32::from_be_bytes(version), name, digest)?;
+        if topology.canonical_bytes() != canonical_bytes {
+            return Err(
+                ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                    field: "projector topology identity",
+                },
+            );
+        }
+        Ok(topology)
+    }
+}
+
+impl Serialize for ProjectorTopologyId {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        #[derive(Serialize)]
+        struct Wire<'a> {
+            version: u32,
+            name: &'a str,
+            digest: [u8; 32],
+        }
+        Wire {
+            version: self.version(),
+            name: self.name(),
+            digest: self.digest(),
+        }
+        .serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for ProjectorTopologyId {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        #[derive(Deserialize)]
+        struct Wire {
+            version: u32,
+            name: String,
+            digest: [u8; 32],
+        }
+        let wire = Wire::deserialize(deserializer)?;
+        Self::new(wire.version, wire.name, wire.digest).map_err(serde::de::Error::custom)
+    }
+}
+
+/// Canonical projector partition and its domain-separated digest.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct ProjectionPartition {
+    canonical_bytes: Vec<u8>,
+    digest: [u8; 32],
+}
+
+impl ProjectionPartition {
+    pub fn new(
+        canonical_bytes: impl Into<Vec<u8>>,
+    ) -> Result<Self, ProjectionProtocolValidationError> {
+        let canonical_bytes = validate_canonical_bytes(
+            "projection partition",
+            canonical_bytes.into(),
+            MAX_PROJECTION_PARTITION_BYTES,
+        )?;
+        let digest = domain_separated_digest(PROJECTION_PARTITION_DIGEST_DOMAIN, &canonical_bytes);
+        Ok(Self {
+            canonical_bytes,
+            digest,
+        })
+    }
+
+    pub fn canonical_bytes(&self) -> &[u8] {
+        &self.canonical_bytes
+    }
+
+    pub fn digest(&self) -> [u8; 32] {
+        self.digest
+    }
+}
+
+impl Serialize for ProjectionPartition {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        self.canonical_bytes.serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for ProjectionPartition {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let canonical_bytes = Vec::<u8>::deserialize(deserializer)?;
+        Self::new(canonical_bytes).map_err(serde::de::Error::custom)
+    }
+}
+
+/// One ordered projection input source.
+///
+/// `name` identifies the source domain (for example an aggregate type), while
+/// `canonical_partition_bytes` identifies one ordered stream within it.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct ProjectionSource {
+    name: String,
+    name_digest: [u8; 32],
+    canonical_partition_bytes: Vec<u8>,
+    partition_digest: [u8; 32],
+}
+
+impl ProjectionSource {
+    pub fn new(
+        name: impl Into<String>,
+        canonical_partition_bytes: impl Into<Vec<u8>>,
+    ) -> Result<Self, ProjectionProtocolValidationError> {
+        let name = validate_name(
+            "projection source name",
+            name.into(),
+            MAX_PROJECTION_SOURCE_NAME_BYTES,
+        )?;
+        let canonical_partition_bytes = validate_canonical_bytes(
+            "projection source partition",
+            canonical_partition_bytes.into(),
+            MAX_PROJECTION_SOURCE_PARTITION_BYTES,
+        )?;
+        let name_digest =
+            domain_separated_digest(PROJECTION_SOURCE_NAME_DIGEST_DOMAIN, name.as_bytes());
+        let partition_digest = domain_separated_digest(
+            PROJECTION_SOURCE_PARTITION_DIGEST_DOMAIN,
+            &canonical_partition_bytes,
+        );
+        Ok(Self {
+            name,
+            name_digest,
+            canonical_partition_bytes,
+            partition_digest,
+        })
+    }
+
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    /// Domain/version-tagged canonical bytes for the source name.
+    pub fn canonical_name_bytes(&self) -> Vec<u8> {
+        let mut bytes = Vec::with_capacity(
+            PROJECTION_SOURCE_NAME_ENCODING_DOMAIN.len()
+                + std::mem::size_of::<u64>()
+                + self.name.len(),
+        );
+        bytes.extend_from_slice(PROJECTION_SOURCE_NAME_ENCODING_DOMAIN);
+        append_length_prefixed(&mut bytes, self.name.as_bytes());
+        bytes
+    }
+
+    /// Reconstruct a source identity from the exact bytes stored by adapters.
+    ///
+    /// This is crate-private because source adapters mint trusted identities;
+    /// public callers cannot turn arbitrary database-shaped bytes into cursor
+    /// authority.
+    pub(crate) fn from_canonical_name_bytes(
+        canonical_name_bytes: &[u8],
+        canonical_partition_bytes: impl Into<Vec<u8>>,
+    ) -> Result<Self, ProjectionProtocolValidationError> {
+        let encoded_name = canonical_name_bytes
+            .strip_prefix(PROJECTION_SOURCE_NAME_ENCODING_DOMAIN)
+            .ok_or(
+                ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                    field: "projection source name",
+                },
+            )?;
+        let (name, trailing) = take_length_prefixed(encoded_name).ok_or(
+            ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                field: "projection source name",
+            },
+        )?;
+        if !trailing.is_empty() {
+            return Err(
+                ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                    field: "projection source name",
+                },
+            );
+        }
+        let name = std::str::from_utf8(name).map_err(|_| {
+            ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                field: "projection source name",
+            }
+        })?;
+        let source = Self::new(name, canonical_partition_bytes)?;
+        if source.canonical_name_bytes() != canonical_name_bytes {
+            return Err(
+                ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                    field: "projection source name",
+                },
+            );
+        }
+        Ok(source)
+    }
+
+    /// Domain-separated digest of the source name.
+    ///
+    /// This is distinct from [`partition_digest`](Self::partition_digest);
+    /// neither digest implies input ordering.
+    pub fn digest(&self) -> [u8; 32] {
+        self.name_digest
+    }
+
+    pub fn canonical_partition_bytes(&self) -> &[u8] {
+        &self.canonical_partition_bytes
+    }
+
+    pub fn partition_digest(&self) -> [u8; 32] {
+        self.partition_digest
+    }
+}
+
+/// Opaque generation identifier for a cursor domain.
+///
+/// Epochs are compared only for exact equality. Their contents never imply
+/// ordering, even if an application chooses a timestamp- or UUID-shaped value.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct ProjectionEpoch(String);
+
+impl ProjectionEpoch {
+    pub fn new(value: impl Into<String>) -> Result<Self, ProjectionProtocolValidationError> {
+        validate_opaque(
+            "projection cursor epoch",
+            value.into(),
+            MAX_PROJECTION_EPOCH_BYTES,
+        )
+        .map(Self)
+    }
+
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+/// Trusted ordered input position for one exact projector/source scope.
+///
+/// There is intentionally no `Ord` or `PartialOrd` implementation: callers
+/// must use [`compare_position`](Self::compare_position), which rejects
+/// cross-scope and cross-epoch comparisons.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct ProjectionInputCursor {
+    topology: ProjectorTopologyId,
+    projection_partition: ProjectionPartition,
+    source: ProjectionSource,
+    epoch: ProjectionEpoch,
+    position: u64,
+}
+
+impl ProjectionInputCursor {
+    pub fn new(
+        topology: ProjectorTopologyId,
+        projection_partition: ProjectionPartition,
+        source: ProjectionSource,
+        epoch: ProjectionEpoch,
+        position: u64,
+    ) -> Result<Self, ProjectionProtocolValidationError> {
+        validate_portable_position("projection input position", position)?;
+        Ok(Self {
+            topology,
+            projection_partition,
+            source,
+            epoch,
+            position,
+        })
+    }
+
+    pub fn topology(&self) -> &ProjectorTopologyId {
+        &self.topology
+    }
+
+    pub fn projection_partition(&self) -> &ProjectionPartition {
+        &self.projection_partition
+    }
+
+    pub fn source(&self) -> &ProjectionSource {
+        &self.source
+    }
+
+    pub fn epoch(&self) -> &ProjectionEpoch {
+        &self.epoch
+    }
+
+    pub fn position(&self) -> u64 {
+        self.position
+    }
+
+    #[must_use]
+    pub fn compare_position(&self, other: &Self) -> RevisionComparison {
+        if self.topology != other.topology
+            || self.projection_partition != other.projection_partition
+            || self.source != other.source
+            || self.epoch != other.epoch
+        {
+            return RevisionComparison::Incomparable;
+        }
+        compare_ordering(self.position.cmp(&other.position))
+    }
+}
+
+/// Exact identity scope of one projected record.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct ProjectionRecordScope {
+    topology: ProjectorTopologyId,
+    projection_partition: ProjectionPartition,
+    model: String,
+    canonical_key_bytes: Vec<u8>,
+    key_digest: [u8; 32],
+}
+
+impl ProjectionRecordScope {
+    pub fn new(
+        topology: ProjectorTopologyId,
+        projection_partition: ProjectionPartition,
+        model: impl Into<String>,
+        canonical_key_bytes: impl Into<Vec<u8>>,
+    ) -> Result<Self, ProjectionProtocolValidationError> {
+        let model = validate_name(
+            "projection model",
+            model.into(),
+            MAX_PROJECTION_MODEL_NAME_BYTES,
+        )?;
+        let canonical_key_bytes = validate_canonical_bytes(
+            "projection record key",
+            canonical_key_bytes.into(),
+            MAX_PROJECTION_RECORD_KEY_BYTES,
+        )?;
+        let key_digest = Self::key_digest_for(&canonical_key_bytes);
+        Ok(Self {
+            topology,
+            projection_partition,
+            model,
+            canonical_key_bytes,
+            key_digest,
+        })
+    }
+
+    pub fn topology(&self) -> &ProjectorTopologyId {
+        &self.topology
+    }
+
+    pub fn projection_partition(&self) -> &ProjectionPartition {
+        &self.projection_partition
+    }
+
+    pub fn model(&self) -> &str {
+        &self.model
+    }
+
+    pub fn canonical_key_bytes(&self) -> &[u8] {
+        &self.canonical_key_bytes
+    }
+
+    pub fn key_digest(&self) -> [u8; 32] {
+        self.key_digest
+    }
+
+    pub(crate) fn key_digest_for(canonical_key_bytes: &[u8]) -> [u8; 32] {
+        domain_separated_digest(PROJECTION_RECORD_KEY_DIGEST_DOMAIN, canonical_key_bytes)
+    }
+}
+
+impl Serialize for ProjectionRecordScope {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        #[derive(Serialize)]
+        struct Wire<'a> {
+            topology: &'a ProjectorTopologyId,
+            partition: &'a ProjectionPartition,
+            model: &'a str,
+            key: &'a [u8],
+        }
+        Wire {
+            topology: self.topology(),
+            partition: self.projection_partition(),
+            model: self.model(),
+            key: self.canonical_key_bytes(),
+        }
+        .serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for ProjectionRecordScope {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        #[derive(Deserialize)]
+        struct Wire {
+            topology: ProjectorTopologyId,
+            partition: ProjectionPartition,
+            model: String,
+            key: Vec<u8>,
+        }
+        let wire = Wire::deserialize(deserializer)?;
+        Self::new(wire.topology, wire.partition, wire.model, wire.key)
+            .map_err(serde::de::Error::custom)
+    }
+}
+
+/// Durable version of one exact projected record.
+///
+/// Incarnation advances only on explicit recreation. Revision advances within
+/// that incarnation. Comparison is lexicographic and only valid for an
+/// identical [`ProjectionRecordScope`].
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct RecordRevision {
+    scope: ProjectionRecordScope,
+    incarnation: NonZeroU64,
+    revision: NonZeroU64,
+}
+
+impl RecordRevision {
+    pub fn new(
+        scope: ProjectionRecordScope,
+        incarnation: u64,
+        revision: u64,
+    ) -> Result<Self, ProjectionProtocolValidationError> {
+        validate_portable_position("projection record incarnation", incarnation)?;
+        validate_portable_position("projection record revision", revision)?;
+        let incarnation =
+            NonZeroU64::new(incarnation).ok_or(ProjectionProtocolValidationError::Zero {
+                field: "projection record incarnation",
+            })?;
+        let revision =
+            NonZeroU64::new(revision).ok_or(ProjectionProtocolValidationError::Zero {
+                field: "projection record revision",
+            })?;
+        Ok(Self {
+            scope,
+            incarnation,
+            revision,
+        })
+    }
+
+    pub fn scope(&self) -> &ProjectionRecordScope {
+        &self.scope
+    }
+
+    pub fn incarnation(&self) -> u64 {
+        self.incarnation.get()
+    }
+
+    pub fn revision(&self) -> u64 {
+        self.revision.get()
+    }
+
+    #[must_use]
+    pub fn compare(&self, other: &Self) -> RevisionComparison {
+        if self.scope != other.scope {
+            return RevisionComparison::Incomparable;
+        }
+        compare_ordering(
+            (self.incarnation, self.revision).cmp(&(other.incarnation, other.revision)),
+        )
+    }
+}
+
+/// Durable change-log position emitted by one projector partition.
+///
+/// This is intentionally distinct from [`ProjectionInputCursor`]: accepting an
+/// input and publishing a resumable change are different protocol facts.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct ProjectionChangeCursor {
+    topology: ProjectorTopologyId,
+    projection_partition: ProjectionPartition,
+    epoch: ProjectionEpoch,
+    position: NonZeroU64,
+}
+
+impl ProjectionChangeCursor {
+    pub fn new(
+        topology: ProjectorTopologyId,
+        projection_partition: ProjectionPartition,
+        epoch: ProjectionEpoch,
+        position: u64,
+    ) -> Result<Self, ProjectionProtocolValidationError> {
+        validate_portable_position("projection change position", position)?;
+        let position =
+            NonZeroU64::new(position).ok_or(ProjectionProtocolValidationError::Zero {
+                field: "projection change position",
+            })?;
+        Ok(Self {
+            topology,
+            projection_partition,
+            epoch,
+            position,
+        })
+    }
+
+    pub fn topology(&self) -> &ProjectorTopologyId {
+        &self.topology
+    }
+
+    pub fn projection_partition(&self) -> &ProjectionPartition {
+        &self.projection_partition
+    }
+
+    pub fn epoch(&self) -> &ProjectionEpoch {
+        &self.epoch
+    }
+
+    pub fn position(&self) -> u64 {
+        self.position.get()
+    }
+
+    #[must_use]
+    pub fn compare_position(&self, other: &Self) -> RevisionComparison {
+        if self.topology != other.topology
+            || self.projection_partition != other.projection_partition
+            || self.epoch != other.epoch
+        {
+            return RevisionComparison::Incomparable;
+        }
+        compare_ordering(self.position.cmp(&other.position))
+    }
+}
+
+/// Successful asynchronous advancement from a trusted input to a durable
+/// change-log position.
+///
+/// Same-transaction command projection does not construct this type: it has
+/// direct ledger-fenced record/change evidence and no asynchronous input
+/// checkpoint.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct ProjectionCheckpoint {
+    input: ProjectionInputCursor,
+    change: ProjectionChangeCursor,
+    gap_free: bool,
+}
+
+impl ProjectionCheckpoint {
+    pub fn new(
+        input: ProjectionInputCursor,
+        change: ProjectionChangeCursor,
+        gap_free: bool,
+    ) -> Result<Self, ProjectionProtocolValidationError> {
+        if input.topology != change.topology {
+            return Err(ProjectionProtocolValidationError::ScopeMismatch {
+                field: "projection checkpoint topology",
+            });
+        }
+        if input.projection_partition != change.projection_partition {
+            return Err(ProjectionProtocolValidationError::ScopeMismatch {
+                field: "projection checkpoint partition",
+            });
+        }
+        Ok(Self {
+            input,
+            change,
+            gap_free,
+        })
+    }
+
+    pub fn input(&self) -> &ProjectionInputCursor {
+        &self.input
+    }
+
+    pub fn change(&self) -> &ProjectionChangeCursor {
+        &self.change
+    }
+
+    /// Whether the registered ordered source proves there can be no omitted
+    /// input positions before this checkpoint.
+    ///
+    /// Only gap-free checkpoints may imply coverage of earlier causations;
+    /// all other sources require exact stored observations.
+    pub fn is_gap_free(&self) -> bool {
+        self.gap_free
+    }
+}
+
+/// Result of attempting one projection commit.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum ProjectionCommitOutcome {
+    Applied,
+    Duplicate,
+    StaleInput,
+}
+
+/// Explicit comparison result for scoped revisions and cursor positions.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum RevisionComparison {
+    Older,
+    Equal,
+    Newer,
+    Incomparable,
+}
+
+fn validate_name(
+    field: &'static str,
+    value: String,
+    max: usize,
+) -> Result<String, ProjectionProtocolValidationError> {
+    if value.is_empty() {
+        return Err(ProjectionProtocolValidationError::Empty { field });
+    }
+    if value.len() > max {
+        return Err(ProjectionProtocolValidationError::TooLong {
+            field,
+            len: value.len(),
+            max,
+        });
+    }
+    if let Some((byte_index, character)) = value
+        .char_indices()
+        .find(|(_, character)| character.is_control() || character.is_whitespace())
+    {
+        return Err(ProjectionProtocolValidationError::InvalidNameCharacter {
+            field,
+            byte_index,
+            character,
+        });
+    }
+    Ok(value)
+}
+
+fn validate_opaque(
+    field: &'static str,
+    value: String,
+    max: usize,
+) -> Result<String, ProjectionProtocolValidationError> {
+    if value.is_empty() {
+        return Err(ProjectionProtocolValidationError::Empty { field });
+    }
+    if value.len() > max {
+        return Err(ProjectionProtocolValidationError::TooLong {
+            field,
+            len: value.len(),
+            max,
+        });
+    }
+    if let Some((byte_index, character)) = value
+        .char_indices()
+        .find(|(_, character)| character.is_control())
+    {
+        return Err(ProjectionProtocolValidationError::InvalidOpaqueCharacter {
+            field,
+            byte_index,
+            character,
+        });
+    }
+    Ok(value)
+}
+
+fn validate_canonical_bytes(
+    field: &'static str,
+    value: Vec<u8>,
+    max: usize,
+) -> Result<Vec<u8>, ProjectionProtocolValidationError> {
+    if value.is_empty() {
+        return Err(ProjectionProtocolValidationError::Empty { field });
+    }
+    if value.len() > max {
+        return Err(ProjectionProtocolValidationError::TooLong {
+            field,
+            len: value.len(),
+            max,
+        });
+    }
+    Ok(value)
+}
+
+fn validate_portable_position(
+    field: &'static str,
+    value: u64,
+) -> Result<(), ProjectionProtocolValidationError> {
+    if value > MAX_PROJECTION_POSITION {
+        return Err(ProjectionProtocolValidationError::TooLarge {
+            field,
+            value,
+            max: MAX_PROJECTION_POSITION,
+        });
+    }
+    Ok(())
+}
+
+fn append_length_prefixed(target: &mut Vec<u8>, value: &[u8]) {
+    target.extend_from_slice(&(value.len() as u64).to_be_bytes());
+    target.extend_from_slice(value);
+}
+
+fn take_length_prefixed(bytes: &[u8]) -> Option<(&[u8], &[u8])> {
+    let length_bytes: [u8; std::mem::size_of::<u64>()] =
+        bytes.get(..std::mem::size_of::<u64>())?.try_into().ok()?;
+    let length = usize::try_from(u64::from_be_bytes(length_bytes)).ok()?;
+    let value_start = std::mem::size_of::<u64>();
+    let value_end = value_start.checked_add(length)?;
+    Some((bytes.get(value_start..value_end)?, bytes.get(value_end..)?))
+}
+
+fn compare_ordering(ordering: Ordering) -> RevisionComparison {
+    match ordering {
+        Ordering::Less => RevisionComparison::Older,
+        Ordering::Equal => RevisionComparison::Equal,
+        Ordering::Greater => RevisionComparison::Newer,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn topology(name: &str, marker: u8) -> ProjectorTopologyId {
+        ProjectorTopologyId::new(1, name, [marker; 32]).unwrap()
+    }
+
+    fn partition(value: &[u8]) -> ProjectionPartition {
+        ProjectionPartition::new(value.to_vec()).unwrap()
+    }
+
+    fn source(name: &str, value: &[u8]) -> ProjectionSource {
+        ProjectionSource::new(name, value.to_vec()).unwrap()
+    }
+
+    fn epoch(value: &str) -> ProjectionEpoch {
+        ProjectionEpoch::new(value).unwrap()
+    }
+
+    fn input_cursor(position: u64) -> ProjectionInputCursor {
+        ProjectionInputCursor::new(
+            topology("todos", 1),
+            partition(b"tenant:a"),
+            source("todo", b"todo:1"),
+            epoch("aggregate-stream-v1"),
+            position,
+        )
+        .unwrap()
+    }
+
+    fn change_cursor(position: u64) -> ProjectionChangeCursor {
+        ProjectionChangeCursor::new(
+            topology("todos", 1),
+            partition(b"tenant:a"),
+            epoch("projection-log-v1"),
+            position,
+        )
+        .unwrap()
+    }
+
+    fn record_scope() -> ProjectionRecordScope {
+        ProjectionRecordScope::new(
+            topology("todos", 1),
+            partition(b"tenant:a"),
+            "TodoView",
+            b"todo:1".to_vec(),
+        )
+        .unwrap()
+    }
+
+    #[test]
+    fn topology_validates_version_name_and_preserves_digest() {
+        let digest = [9; 32];
+        let topology = ProjectorTopologyId::new(7, "project_todos", digest).unwrap();
+        assert_eq!(topology.version(), 7);
+        assert_eq!(topology.name(), "project_todos");
+        assert_eq!(topology.digest(), digest);
+
+        assert_eq!(
+            ProjectorTopologyId::new(0, "project_todos", digest),
+            Err(ProjectionProtocolValidationError::Zero {
+                field: "projector topology version",
+            })
+        );
+        assert_eq!(
+            ProjectorTopologyId::new(1, "", digest),
+            Err(ProjectionProtocolValidationError::Empty {
+                field: "projector topology name",
+            })
+        );
+        assert!(matches!(
+            ProjectorTopologyId::new(1, "project todos", digest),
+            Err(ProjectionProtocolValidationError::InvalidNameCharacter {
+                field: "projector topology name",
+                ..
+            })
+        ));
+        assert!(matches!(
+            ProjectorTopologyId::new(1, "project\ntodos", digest),
+            Err(ProjectionProtocolValidationError::InvalidNameCharacter {
+                field: "projector topology name",
+                ..
+            })
+        ));
+
+        let boundary = "a".repeat(MAX_PROJECTOR_NAME_BYTES);
+        assert!(ProjectorTopologyId::new(1, boundary, digest).is_ok());
+        let overlong = "a".repeat(MAX_PROJECTOR_NAME_BYTES + 1);
+        assert_eq!(
+            ProjectorTopologyId::new(1, overlong, digest),
+            Err(ProjectionProtocolValidationError::TooLong {
+                field: "projector topology name",
+                len: MAX_PROJECTOR_NAME_BYTES + 1,
+                max: MAX_PROJECTOR_NAME_BYTES,
+            })
+        );
+    }
+
+    #[test]
+    fn topology_canonical_identity_is_deterministic_and_component_bound() {
+        let first = ProjectorTopologyId::new(7, "project_todos", [9; 32]).unwrap();
+        let same = ProjectorTopologyId::new(7, "project_todos", [9; 32]).unwrap();
+        let different_version = ProjectorTopologyId::new(8, "project_todos", [9; 32]).unwrap();
+        let different_name = ProjectorTopologyId::new(7, "project_todos_v2", [9; 32]).unwrap();
+        let different_digest = ProjectorTopologyId::new(7, "project_todos", [8; 32]).unwrap();
+
+        assert_eq!(first.canonical_bytes(), same.canonical_bytes());
+        assert_ne!(first.canonical_bytes(), different_version.canonical_bytes());
+        assert_ne!(first.canonical_bytes(), different_name.canonical_bytes());
+        assert_ne!(first.canonical_bytes(), different_digest.canonical_bytes());
+        assert!(first
+            .canonical_bytes()
+            .starts_with(PROJECTOR_TOPOLOGY_IDENTITY_ENCODING_DOMAIN));
+
+        let boundary =
+            ProjectorTopologyId::new(1, "a".repeat(MAX_PROJECTOR_NAME_BYTES), [0; 32]).unwrap();
+        assert!(boundary.canonical_bytes().len() > MAX_PROJECTOR_NAME_BYTES);
+    }
+
+    #[test]
+    fn canonical_values_are_nonempty_and_bounded() {
+        assert_eq!(
+            ProjectionPartition::new(Vec::new()),
+            Err(ProjectionProtocolValidationError::Empty {
+                field: "projection partition",
+            })
+        );
+        assert!(ProjectionPartition::new(vec![1; MAX_PROJECTION_PARTITION_BYTES]).is_ok());
+        assert_eq!(
+            ProjectionPartition::new(vec![1; MAX_PROJECTION_PARTITION_BYTES + 1]),
+            Err(ProjectionProtocolValidationError::TooLong {
+                field: "projection partition",
+                len: MAX_PROJECTION_PARTITION_BYTES + 1,
+                max: MAX_PROJECTION_PARTITION_BYTES,
+            })
+        );
+
+        assert_eq!(
+            ProjectionSource::new("todo", Vec::new()),
+            Err(ProjectionProtocolValidationError::Empty {
+                field: "projection source partition",
+            })
+        );
+        assert!(
+            ProjectionSource::new("todo", vec![1; MAX_PROJECTION_SOURCE_PARTITION_BYTES]).is_ok()
+        );
+        assert_eq!(
+            ProjectionSource::new("todo", vec![1; MAX_PROJECTION_SOURCE_PARTITION_BYTES + 1],),
+            Err(ProjectionProtocolValidationError::TooLong {
+                field: "projection source partition",
+                len: MAX_PROJECTION_SOURCE_PARTITION_BYTES + 1,
+                max: MAX_PROJECTION_SOURCE_PARTITION_BYTES,
+            })
+        );
+
+        assert_eq!(
+            ProjectionRecordScope::new(
+                topology("todos", 1),
+                partition(b"tenant:a"),
+                "TodoView",
+                Vec::new(),
+            ),
+            Err(ProjectionProtocolValidationError::Empty {
+                field: "projection record key",
+            })
+        );
+        assert!(ProjectionRecordScope::new(
+            topology("todos", 1),
+            partition(b"tenant:a"),
+            "TodoView",
+            vec![1; MAX_PROJECTION_RECORD_KEY_BYTES],
+        )
+        .is_ok());
+        assert_eq!(
+            ProjectionRecordScope::new(
+                topology("todos", 1),
+                partition(b"tenant:a"),
+                "TodoView",
+                vec![1; MAX_PROJECTION_RECORD_KEY_BYTES + 1],
+            ),
+            Err(ProjectionProtocolValidationError::TooLong {
+                field: "projection record key",
+                len: MAX_PROJECTION_RECORD_KEY_BYTES + 1,
+                max: MAX_PROJECTION_RECORD_KEY_BYTES,
+            })
+        );
+    }
+
+    #[test]
+    fn names_are_bounded_and_reject_whitespace_or_controls() {
+        assert_eq!(
+            ProjectionSource::new("", b"one".to_vec()),
+            Err(ProjectionProtocolValidationError::Empty {
+                field: "projection source name",
+            })
+        );
+        assert!(matches!(
+            ProjectionSource::new("todo source", b"one".to_vec()),
+            Err(ProjectionProtocolValidationError::InvalidNameCharacter {
+                field: "projection source name",
+                ..
+            })
+        ));
+        assert_eq!(
+            ProjectionSource::new(
+                "a".repeat(MAX_PROJECTION_SOURCE_NAME_BYTES + 1),
+                b"one".to_vec(),
+            ),
+            Err(ProjectionProtocolValidationError::TooLong {
+                field: "projection source name",
+                len: MAX_PROJECTION_SOURCE_NAME_BYTES + 1,
+                max: MAX_PROJECTION_SOURCE_NAME_BYTES,
+            })
+        );
+
+        assert!(matches!(
+            ProjectionRecordScope::new(
+                topology("todos", 1),
+                partition(b"tenant:a"),
+                "Todo View",
+                b"todo:1".to_vec(),
+            ),
+            Err(ProjectionProtocolValidationError::InvalidNameCharacter {
+                field: "projection model",
+                ..
+            })
+        ));
+        assert_eq!(
+            ProjectionRecordScope::new(
+                topology("todos", 1),
+                partition(b"tenant:a"),
+                "a".repeat(MAX_PROJECTION_MODEL_NAME_BYTES + 1),
+                b"todo:1".to_vec(),
+            ),
+            Err(ProjectionProtocolValidationError::TooLong {
+                field: "projection model",
+                len: MAX_PROJECTION_MODEL_NAME_BYTES + 1,
+                max: MAX_PROJECTION_MODEL_NAME_BYTES,
+            })
+        );
+    }
+
+    #[test]
+    fn digests_are_deterministic_and_domain_separated() {
+        let bytes = b"same-canonical-value".to_vec();
+        let first_partition = ProjectionPartition::new(bytes.clone()).unwrap();
+        let second_partition = ProjectionPartition::new(bytes.clone()).unwrap();
+        let source = ProjectionSource::new("source", bytes.clone()).unwrap();
+        let scope = ProjectionRecordScope::new(
+            topology("todos", 1),
+            first_partition.clone(),
+            "TodoView",
+            bytes,
+        )
+        .unwrap();
+
+        assert_eq!(first_partition.digest(), second_partition.digest());
+        assert_eq!(
+            source.digest(),
+            ProjectionSource::new("source", b"different-partition".to_vec())
+                .unwrap()
+                .digest()
+        );
+        assert_ne!(source.digest(), source.partition_digest());
+        assert_ne!(first_partition.digest(), source.partition_digest());
+        assert_ne!(first_partition.digest(), scope.key_digest());
+        assert_ne!(source.partition_digest(), scope.key_digest());
+        assert!(source
+            .canonical_name_bytes()
+            .starts_with(PROJECTION_SOURCE_NAME_ENCODING_DOMAIN));
+        assert_ne!(
+            source.canonical_name_bytes(),
+            source.canonical_partition_bytes()
+        );
+        assert_eq!(first_partition.canonical_bytes(), b"same-canonical-value");
+        assert_eq!(source.canonical_partition_bytes(), b"same-canonical-value");
+        assert_eq!(scope.canonical_key_bytes(), b"same-canonical-value");
+
+        let decoded = ProjectionSource::from_canonical_name_bytes(
+            &source.canonical_name_bytes(),
+            source.canonical_partition_bytes().to_vec(),
+        )
+        .unwrap();
+        assert_eq!(decoded, source);
+        assert_eq!(
+            ProjectionSource::from_canonical_name_bytes(
+                b"not-a-versioned-source",
+                b"partition".to_vec(),
+            ),
+            Err(
+                ProjectionProtocolValidationError::MalformedCanonicalEncoding {
+                    field: "projection source name",
+                }
+            )
+        );
+    }
+
+    #[test]
+    fn epoch_is_bounded_opaque_and_never_ordered_by_contents() {
+        let opaque = ProjectionEpoch::new("2026-07-22 10:00:00Z").unwrap();
+        assert_eq!(opaque.as_str(), "2026-07-22 10:00:00Z");
+        assert_eq!(
+            ProjectionEpoch::new(""),
+            Err(ProjectionProtocolValidationError::Empty {
+                field: "projection cursor epoch",
+            })
+        );
+        assert!(matches!(
+            ProjectionEpoch::new("epoch\n2"),
+            Err(ProjectionProtocolValidationError::InvalidOpaqueCharacter {
+                field: "projection cursor epoch",
+                ..
+            })
+        ));
+        assert!(ProjectionEpoch::new("a".repeat(MAX_PROJECTION_EPOCH_BYTES)).is_ok());
+        assert_eq!(
+            ProjectionEpoch::new("a".repeat(MAX_PROJECTION_EPOCH_BYTES + 1)),
+            Err(ProjectionProtocolValidationError::TooLong {
+                field: "projection cursor epoch",
+                len: MAX_PROJECTION_EPOCH_BYTES + 1,
+                max: MAX_PROJECTION_EPOCH_BYTES,
+            })
+        );
+    }
+
+    #[test]
+    fn input_cursor_allows_zero_and_compares_only_exact_scope() {
+        let zero = input_cursor(0);
+        assert_eq!(zero.position(), 0);
+        assert_eq!(
+            ProjectionInputCursor::new(
+                topology("todos", 1),
+                partition(b"tenant:a"),
+                source("todo", b"todo:1"),
+                epoch("aggregate-stream-v1"),
+                MAX_PROJECTION_POSITION + 1,
+            ),
+            Err(ProjectionProtocolValidationError::TooLarge {
+                field: "projection input position",
+                value: MAX_PROJECTION_POSITION + 1,
+                max: MAX_PROJECTION_POSITION,
+            })
+        );
+        assert_eq!(
+            zero.compare_position(&input_cursor(1)),
+            RevisionComparison::Older
+        );
+        let base = input_cursor(10);
+        assert_eq!(
+            input_cursor(9).compare_position(&base),
+            RevisionComparison::Older
+        );
+        assert_eq!(
+            base.compare_position(&input_cursor(10)),
+            RevisionComparison::Equal
+        );
+        assert_eq!(
+            input_cursor(11).compare_position(&base),
+            RevisionComparison::Newer
+        );
+
+        let different_topology = ProjectionInputCursor::new(
+            topology("todos", 2),
+            partition(b"tenant:a"),
+            source("todo", b"todo:1"),
+            epoch("aggregate-stream-v1"),
+            10,
+        )
+        .unwrap();
+        let different_partition = ProjectionInputCursor::new(
+            topology("todos", 1),
+            partition(b"tenant:b"),
+            source("todo", b"todo:1"),
+            epoch("aggregate-stream-v1"),
+            10,
+        )
+        .unwrap();
+        let different_source = ProjectionInputCursor::new(
+            topology("todos", 1),
+            partition(b"tenant:a"),
+            source("todo", b"todo:2"),
+            epoch("aggregate-stream-v1"),
+            10,
+        )
+        .unwrap();
+        let different_epoch = ProjectionInputCursor::new(
+            topology("todos", 1),
+            partition(b"tenant:a"),
+            source("todo", b"todo:1"),
+            epoch("aggregate-stream-v2"),
+            10,
+        )
+        .unwrap();
+
+        for other in [
+            different_topology,
+            different_partition,
+            different_source,
+            different_epoch,
+        ] {
+            assert_eq!(
+                base.compare_position(&other),
+                RevisionComparison::Incomparable
+            );
+        }
+    }
+
+    #[test]
+    fn record_revision_is_nonzero_lexicographic_and_scope_bound() {
+        let scope = record_scope();
+        assert_eq!(
+            RecordRevision::new(scope.clone(), 0, 1),
+            Err(ProjectionProtocolValidationError::Zero {
+                field: "projection record incarnation",
+            })
+        );
+        assert_eq!(
+            RecordRevision::new(scope.clone(), 1, 0),
+            Err(ProjectionProtocolValidationError::Zero {
+                field: "projection record revision",
+            })
+        );
+        assert_eq!(
+            RecordRevision::new(scope.clone(), MAX_PROJECTION_POSITION + 1, 1),
+            Err(ProjectionProtocolValidationError::TooLarge {
+                field: "projection record incarnation",
+                value: MAX_PROJECTION_POSITION + 1,
+                max: MAX_PROJECTION_POSITION,
+            })
+        );
+
+        let one_one = RecordRevision::new(scope.clone(), 1, 1).unwrap();
+        let one_two = RecordRevision::new(scope.clone(), 1, 2).unwrap();
+        let two_one = RecordRevision::new(scope.clone(), 2, 1).unwrap();
+        assert_eq!(one_one.compare(&one_two), RevisionComparison::Older);
+        assert_eq!(one_two.compare(&one_one), RevisionComparison::Newer);
+        assert_eq!(
+            one_one.compare(&RecordRevision::new(scope.clone(), 1, 1).unwrap()),
+            RevisionComparison::Equal
+        );
+        assert_eq!(one_two.compare(&two_one), RevisionComparison::Older);
+
+        let scopes = [
+            ProjectionRecordScope::new(
+                topology("other", 1),
+                partition(b"tenant:a"),
+                "TodoView",
+                b"todo:1".to_vec(),
+            )
+            .unwrap(),
+            ProjectionRecordScope::new(
+                topology("todos", 1),
+                partition(b"tenant:b"),
+                "TodoView",
+                b"todo:1".to_vec(),
+            )
+            .unwrap(),
+            ProjectionRecordScope::new(
+                topology("todos", 1),
+                partition(b"tenant:a"),
+                "OtherView",
+                b"todo:1".to_vec(),
+            )
+            .unwrap(),
+            ProjectionRecordScope::new(
+                topology("todos", 1),
+                partition(b"tenant:a"),
+                "TodoView",
+                b"todo:2".to_vec(),
+            )
+            .unwrap(),
+        ];
+        for other_scope in scopes {
+            let other = RecordRevision::new(other_scope, 1, 1).unwrap();
+            assert_eq!(one_one.compare(&other), RevisionComparison::Incomparable);
+        }
+    }
+
+    #[test]
+    fn change_cursor_is_distinct_nonzero_and_scope_bound() {
+        assert_eq!(
+            ProjectionChangeCursor::new(
+                topology("todos", 1),
+                partition(b"tenant:a"),
+                epoch("projection-log-v1"),
+                0,
+            ),
+            Err(ProjectionProtocolValidationError::Zero {
+                field: "projection change position",
+            })
+        );
+        assert_eq!(
+            ProjectionChangeCursor::new(
+                topology("todos", 1),
+                partition(b"tenant:a"),
+                epoch("projection-log-v1"),
+                MAX_PROJECTION_POSITION + 1,
+            ),
+            Err(ProjectionProtocolValidationError::TooLarge {
+                field: "projection change position",
+                value: MAX_PROJECTION_POSITION + 1,
+                max: MAX_PROJECTION_POSITION,
+            })
+        );
+
+        let base = change_cursor(10);
+        assert_eq!(
+            change_cursor(9).compare_position(&base),
+            RevisionComparison::Older
+        );
+        assert_eq!(
+            base.compare_position(&change_cursor(10)),
+            RevisionComparison::Equal
+        );
+        assert_eq!(
+            change_cursor(11).compare_position(&base),
+            RevisionComparison::Newer
+        );
+
+        let different_topology = ProjectionChangeCursor::new(
+            topology("todos", 2),
+            partition(b"tenant:a"),
+            epoch("projection-log-v1"),
+            10,
+        )
+        .unwrap();
+        let different_partition = ProjectionChangeCursor::new(
+            topology("todos", 1),
+            partition(b"tenant:b"),
+            epoch("projection-log-v1"),
+            10,
+        )
+        .unwrap();
+        let different_epoch = ProjectionChangeCursor::new(
+            topology("todos", 1),
+            partition(b"tenant:a"),
+            epoch("projection-log-v2"),
+            10,
+        )
+        .unwrap();
+
+        for other in [different_topology, different_partition, different_epoch] {
+            assert_eq!(
+                base.compare_position(&other),
+                RevisionComparison::Incomparable
+            );
+        }
+    }
+
+    #[test]
+    fn checkpoint_requires_matching_topology_and_projection_partition() {
+        let checkpoint =
+            ProjectionCheckpoint::new(input_cursor(7), change_cursor(11), true).unwrap();
+        assert_eq!(checkpoint.input().position(), 7);
+        assert_eq!(checkpoint.change().position(), 11);
+        assert!(checkpoint.is_gap_free());
+
+        let wrong_topology = ProjectionChangeCursor::new(
+            topology("other", 2),
+            partition(b"tenant:a"),
+            epoch("projection-log-v1"),
+            11,
+        )
+        .unwrap();
+        assert_eq!(
+            ProjectionCheckpoint::new(input_cursor(7), wrong_topology, true),
+            Err(ProjectionProtocolValidationError::ScopeMismatch {
+                field: "projection checkpoint topology",
+            })
+        );
+
+        let wrong_partition = ProjectionChangeCursor::new(
+            topology("todos", 1),
+            partition(b"tenant:b"),
+            epoch("projection-log-v1"),
+            11,
+        )
+        .unwrap();
+        assert_eq!(
+            ProjectionCheckpoint::new(input_cursor(7), wrong_partition, true),
+            Err(ProjectionProtocolValidationError::ScopeMismatch {
+                field: "projection checkpoint partition",
+            })
+        );
+    }
+
+    #[test]
+    fn commit_outcomes_are_closed_and_distinct() {
+        assert_ne!(
+            ProjectionCommitOutcome::Applied,
+            ProjectionCommitOutcome::Duplicate
+        );
+        assert_ne!(
+            ProjectionCommitOutcome::Applied,
+            ProjectionCommitOutcome::StaleInput
+        );
+        assert_ne!(
+            ProjectionCommitOutcome::Duplicate,
+            ProjectionCommitOutcome::StaleInput
+        );
+    }
+}
diff --git a/src/projection_protocol/codec/constants.rs b/src/projection_protocol/codec/constants.rs
new file mode 100644
index 00000000..150818ac
--- /dev/null
+++ b/src/projection_protocol/codec/constants.rs
@@ -0,0 +1,8 @@
+pub(super) const PARTITION_ENCODING_DOMAIN: &[u8] = b"distributed.projection.scope-partition.v1\0";
+pub(super) const RECORD_KEY_ENCODING_DOMAIN: &[u8] =
+    b"distributed.projection.scope-record-key.v1\0";
+pub(super) const COMPILED_TOPOLOGY_DOMAIN: &[u8] = b"distributed.projection.compiled-topology.v1\0";
+pub(super) const COMPILED_TOPOLOGY_VERSION: u32 = 1;
+pub(super) const SCOPE_CODEC_VERSION: u32 = 1;
+pub(super) const MAX_PARTITION_PATH_DEPTH: usize = 32;
+pub(super) const MAX_PARTITION_PATH_SEGMENT_BYTES: usize = 255;
diff --git a/src/projection_protocol/codec/errors.rs b/src/projection_protocol/codec/errors.rs
new file mode 100644
index 00000000..27043be3
--- /dev/null
+++ b/src/projection_protocol/codec/errors.rs
@@ -0,0 +1,205 @@
+use std::fmt;
+
+use crate::projection_protocol::ProjectionProtocolValidationError;
+
+/// A projection identity could not be encoded without ambiguity.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) enum ProjectionScopeCodecError {
+    BlankModelRegistration,
+    InvalidModelRegistration {
+        model: String,
+        reason: String,
+    },
+    ModelRegistrationMismatch {
+        declared: String,
+        schema: String,
+    },
+    DuplicateModelRegistration {
+        model: String,
+    },
+    ProjectorMismatch {
+        expected: String,
+        actual: String,
+    },
+    #[allow(dead_code)]
+    StoredScopeMismatch {
+        projector: String,
+        model: String,
+    },
+    UnknownModel {
+        projector: String,
+        model: String,
+    },
+    DuplicateKeyField {
+        model: String,
+        field: String,
+    },
+    ExtraKeyField {
+        model: String,
+        field: String,
+    },
+    MissingKeyField {
+        model: String,
+        field: String,
+    },
+    ExtraKeyColumn {
+        model: String,
+        column: String,
+    },
+    MissingKeyColumn {
+        model: String,
+        column: String,
+    },
+    NullPrimaryKey {
+        model: String,
+        field: String,
+    },
+    WrongJsonShape {
+        model: String,
+        field: String,
+        expected: &'static str,
+        actual: &'static str,
+    },
+    WrongRowValueShape {
+        model: String,
+        column: String,
+        expected: &'static str,
+        actual: &'static str,
+    },
+    IntegerOutOfRange {
+        model: String,
+        field: String,
+        expected: &'static str,
+    },
+    NonFiniteFloat {
+        model: String,
+        field: String,
+    },
+    InvalidBytes {
+        model: String,
+        field: String,
+    },
+    CanonicalEncodingTooLong {
+        target: &'static str,
+        max: usize,
+    },
+    Protocol(ProjectionProtocolValidationError),
+}
+
+impl fmt::Display for ProjectionScopeCodecError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::BlankModelRegistration => {
+                formatter.write_str("projection model registration must not be blank")
+            }
+            Self::InvalidModelRegistration { model, reason } => {
+                write!(formatter, "invalid projection model `{model}`: {reason}")
+            }
+            Self::ModelRegistrationMismatch { declared, schema } => write!(
+                formatter,
+                "projection model registration `{declared}` does not match schema model `{schema}`"
+            ),
+            Self::DuplicateModelRegistration { model } => {
+                write!(
+                    formatter,
+                    "projection model `{model}` is already registered"
+                )
+            }
+            Self::ProjectorMismatch { expected, actual } => write!(
+                formatter,
+                "projection scope belongs to projector `{expected}`, not `{actual}`"
+            ),
+            Self::StoredScopeMismatch { projector, model } => write!(
+                formatter,
+                "stored projection obligation `{projector}`/`{model}` scope does not match its canonical logical fields"
+            ),
+            Self::UnknownModel { projector, model } => write!(
+                formatter,
+                "projector `{projector}` does not register projection model `{model}`"
+            ),
+            Self::DuplicateKeyField { model, field } => {
+                write!(
+                    formatter,
+                    "projection key for `{model}` repeats field `{field}`"
+                )
+            }
+            Self::ExtraKeyField { model, field } => write!(
+                formatter,
+                "projection key for `{model}` contains non-key field `{field}`"
+            ),
+            Self::MissingKeyField { model, field } => {
+                write!(
+                    formatter,
+                    "projection key for `{model}` is missing field `{field}`"
+                )
+            }
+            Self::ExtraKeyColumn { model, column } => write!(
+                formatter,
+                "projector row key for `{model}` contains non-key column `{column}`"
+            ),
+            Self::MissingKeyColumn { model, column } => write!(
+                formatter,
+                "projector row key for `{model}` is missing column `{column}`"
+            ),
+            Self::NullPrimaryKey { model, field } => {
+                write!(
+                    formatter,
+                    "projection key `{model}.{field}` must not be null"
+                )
+            }
+            Self::WrongJsonShape {
+                model,
+                field,
+                expected,
+                actual,
+            } => write!(
+                formatter,
+                "projection key `{model}.{field}` must be {expected}, got {actual}"
+            ),
+            Self::WrongRowValueShape {
+                model,
+                column,
+                expected,
+                actual,
+            } => write!(
+                formatter,
+                "projector row key `{model}.{column}` must be {expected}, got {actual}"
+            ),
+            Self::IntegerOutOfRange {
+                model,
+                field,
+                expected,
+            } => write!(
+                formatter,
+                "projection key `{model}.{field}` is outside the {expected} range"
+            ),
+            Self::NonFiniteFloat { model, field } => write!(
+                formatter,
+                "projection key `{model}.{field}` must be a finite float"
+            ),
+            Self::InvalidBytes { model, field } => write!(
+                formatter,
+                "projection key `{model}.{field}` must be canonical standard base64"
+            ),
+            Self::CanonicalEncodingTooLong { target, max } => {
+                write!(formatter, "{target} canonical encoding exceeds {max} bytes")
+            }
+            Self::Protocol(error) => error.fmt(formatter),
+        }
+    }
+}
+
+impl std::error::Error for ProjectionScopeCodecError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Protocol(error) => Some(error),
+            _ => None,
+        }
+    }
+}
+
+impl From<ProjectionProtocolValidationError> for ProjectionScopeCodecError {
+    fn from(error: ProjectionProtocolValidationError) -> Self {
+        Self::Protocol(error)
+    }
+}
diff --git a/src/projection_protocol/codec/key.rs b/src/projection_protocol/codec/key.rs
new file mode 100644
index 00000000..76390cfd
--- /dev/null
+++ b/src/projection_protocol/codec/key.rs
@@ -0,0 +1,492 @@
+use std::collections::BTreeSet;
+
+use base64::engine::general_purpose::STANDARD as BASE64_STANDARD;
+use base64::Engine as _;
+
+use super::ProjectionScopeCodecError;
+use crate::projection_protocol::MAX_PROJECTION_MODEL_NAME_BYTES;
+use crate::table::{ColumnType, RowValue, TableColumn, TableKind, TableSchema};
+
+pub(super) fn validate_registration_name(model: &str) -> Result<(), ProjectionScopeCodecError> {
+    if model.trim().is_empty() {
+        return Err(ProjectionScopeCodecError::BlankModelRegistration);
+    }
+    if model.len() > MAX_PROJECTION_MODEL_NAME_BYTES {
+        return Err(ProjectionScopeCodecError::InvalidModelRegistration {
+            model: model.to_string(),
+            reason: format!(
+                "name is {} bytes, exceeding the maximum of {}",
+                model.len(),
+                MAX_PROJECTION_MODEL_NAME_BYTES
+            ),
+        });
+    }
+    if model
+        .chars()
+        .any(|character| character.is_control() || character.is_whitespace())
+    {
+        return Err(ProjectionScopeCodecError::InvalidModelRegistration {
+            model: model.to_string(),
+            reason: "name contains whitespace or a control character".into(),
+        });
+    }
+    Ok(())
+}
+
+pub(super) fn validate_model_schema(schema: &TableSchema) -> Result<(), ProjectionScopeCodecError> {
+    schema.validate().map_err(
+        |error| ProjectionScopeCodecError::InvalidModelRegistration {
+            model: schema.model_name.clone(),
+            reason: error.to_string(),
+        },
+    )?;
+    if !matches!(schema.kind, TableKind::ReadModel) {
+        return Err(ProjectionScopeCodecError::InvalidModelRegistration {
+            model: schema.model_name.clone(),
+            reason: "projection models must be read models".into(),
+        });
+    }
+
+    let mut primary_key_columns = BTreeSet::new();
+    let mut primary_key_fields = BTreeSet::new();
+    for column_name in &schema.primary_key.columns {
+        if !primary_key_columns.insert(column_name.as_str()) {
+            return Err(ProjectionScopeCodecError::InvalidModelRegistration {
+                model: schema.model_name.clone(),
+                reason: format!("primary key repeats column `{column_name}`"),
+            });
+        }
+        let column = key_column(schema, column_name).ok_or_else(|| {
+            ProjectionScopeCodecError::InvalidModelRegistration {
+                model: schema.model_name.clone(),
+                reason: format!("primary key references missing column `{column_name}`"),
+            }
+        })?;
+        if !column.primary_key {
+            return Err(ProjectionScopeCodecError::InvalidModelRegistration {
+                model: schema.model_name.clone(),
+                reason: format!(
+                    "primary-key list contains column `{column_name}` but the column is not marked primary-key"
+                ),
+            });
+        }
+        if column.field_name.trim().is_empty() {
+            return Err(ProjectionScopeCodecError::InvalidModelRegistration {
+                model: schema.model_name.clone(),
+                reason: format!("primary-key column `{column_name}` has a blank field name"),
+            });
+        }
+        if !primary_key_fields.insert(column.field_name.as_str()) {
+            return Err(ProjectionScopeCodecError::InvalidModelRegistration {
+                model: schema.model_name.clone(),
+                reason: format!(
+                    "primary key maps multiple columns to field `{}`",
+                    column.field_name
+                ),
+            });
+        }
+    }
+    if let Some(column) = schema.columns.iter().find(|column| {
+        column.primary_key && !primary_key_columns.contains(column.column_name.as_str())
+    }) {
+        return Err(ProjectionScopeCodecError::InvalidModelRegistration {
+            model: schema.model_name.clone(),
+            reason: format!(
+                "column `{}` is marked primary-key but absent from the primary-key list",
+                column.column_name
+            ),
+        });
+    }
+    Ok(())
+}
+
+pub(super) fn key_column<'a>(
+    schema: &'a TableSchema,
+    column_name: &str,
+) -> Option<&'a TableColumn> {
+    schema
+        .columns
+        .iter()
+        .find(|column| column.column_name == column_name)
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub(super) enum TypedKeyValue {
+    Text(String),
+    Boolean(bool),
+    Integer(i64),
+    UnsignedInteger(u64),
+    Float(f64),
+    Bytes(Vec<u8>),
+    Json(serde_json::Value),
+    Timestamp(String),
+}
+
+pub(super) fn typed_value_from_json(
+    schema: &TableSchema,
+    column: &TableColumn,
+    value: &serde_json::Value,
+) -> Result<TypedKeyValue, ProjectionScopeCodecError> {
+    if value.is_null() {
+        return Err(ProjectionScopeCodecError::NullPrimaryKey {
+            model: schema.model_name.clone(),
+            field: column.field_name.clone(),
+        });
+    }
+
+    let wrong_shape = |expected| ProjectionScopeCodecError::WrongJsonShape {
+        model: schema.model_name.clone(),
+        field: column.field_name.clone(),
+        expected,
+        actual: json_shape(value),
+    };
+    match &column.column_type {
+        ColumnType::Text => value
+            .as_str()
+            .map(|value| TypedKeyValue::Text(value.to_string()))
+            .ok_or_else(|| wrong_shape("a string")),
+        ColumnType::Boolean => value
+            .as_bool()
+            .map(TypedKeyValue::Boolean)
+            .ok_or_else(|| wrong_shape("a boolean")),
+        ColumnType::Integer => value.as_i64().map(TypedKeyValue::Integer).ok_or_else(|| {
+            ProjectionScopeCodecError::IntegerOutOfRange {
+                model: schema.model_name.clone(),
+                field: column.field_name.clone(),
+                expected: "signed 64-bit integer",
+            }
+        }),
+        ColumnType::UnsignedInteger => value
+            .as_u64()
+            .map(TypedKeyValue::UnsignedInteger)
+            .ok_or_else(|| ProjectionScopeCodecError::IntegerOutOfRange {
+                model: schema.model_name.clone(),
+                field: column.field_name.clone(),
+                expected: "unsigned 64-bit integer",
+            }),
+        ColumnType::Float => value
+            .as_f64()
+            .filter(|value| value.is_finite())
+            .map(TypedKeyValue::Float)
+            .ok_or_else(|| wrong_shape("a finite number")),
+        ColumnType::Bytes => {
+            let encoded = value
+                .as_str()
+                .ok_or_else(|| wrong_shape("a base64 string"))?;
+            let decoded = BASE64_STANDARD.decode(encoded).map_err(|_| {
+                ProjectionScopeCodecError::InvalidBytes {
+                    model: schema.model_name.clone(),
+                    field: column.field_name.clone(),
+                }
+            })?;
+            if BASE64_STANDARD.encode(&decoded) != encoded {
+                return Err(ProjectionScopeCodecError::InvalidBytes {
+                    model: schema.model_name.clone(),
+                    field: column.field_name.clone(),
+                });
+            }
+            Ok(TypedKeyValue::Bytes(decoded))
+        }
+        ColumnType::Json => Ok(TypedKeyValue::Json(value.clone())),
+        ColumnType::Timestamp => value
+            .as_str()
+            .map(|value| TypedKeyValue::Timestamp(value.to_string()))
+            .ok_or_else(|| wrong_shape("a timestamp string")),
+        ColumnType::Unsupported(type_name) => {
+            Err(ProjectionScopeCodecError::InvalidModelRegistration {
+                model: schema.model_name.clone(),
+                reason: format!(
+                    "primary-key field `{}` has unsupported type `{type_name}`",
+                    column.field_name
+                ),
+            })
+        }
+    }
+}
+
+pub(super) fn row_value_from_graphql_json(
+    schema: &TableSchema,
+    column: &TableColumn,
+    value: &serde_json::Value,
+) -> Result<RowValue, ProjectionScopeCodecError> {
+    if value.is_null() {
+        return Err(ProjectionScopeCodecError::NullPrimaryKey {
+            model: schema.model_name.clone(),
+            field: column.field_name.clone(),
+        });
+    }
+
+    let integer_out_of_range = |expected| ProjectionScopeCodecError::IntegerOutOfRange {
+        model: schema.model_name.clone(),
+        field: column.field_name.clone(),
+        expected,
+    };
+    let typed = match &column.column_type {
+        ColumnType::Integer => match value {
+            serde_json::Value::String(value) => {
+                let parsed = value
+                    .parse::<i64>()
+                    .map_err(|_| integer_out_of_range("signed 64-bit integer"))?;
+                if parsed.to_string() != *value {
+                    return Err(integer_out_of_range(
+                        "canonical signed 64-bit integer string",
+                    ));
+                }
+                TypedKeyValue::Integer(parsed)
+            }
+            _ => typed_value_from_json(schema, column, value)?,
+        },
+        ColumnType::UnsignedInteger => match value {
+            serde_json::Value::String(value) => {
+                let parsed = value
+                    .parse::<u64>()
+                    .map_err(|_| integer_out_of_range("unsigned 64-bit integer"))?;
+                if parsed.to_string() != *value {
+                    return Err(integer_out_of_range(
+                        "canonical unsigned 64-bit integer string",
+                    ));
+                }
+                TypedKeyValue::UnsignedInteger(parsed)
+            }
+            _ => typed_value_from_json(schema, column, value)?,
+        },
+        // SQLite's JSON1 extension exposes BOOLEAN-affinity columns as the
+        // lossless integer values 0/1. Accept exactly those private evidence
+        // representations in addition to native JSON booleans.
+        ColumnType::Boolean => match value.as_i64() {
+            Some(0) => TypedKeyValue::Boolean(false),
+            Some(1) => TypedKeyValue::Boolean(true),
+            _ => typed_value_from_json(schema, column, value)?,
+        },
+        _ => typed_value_from_json(schema, column, value)?,
+    };
+
+    Ok(match typed {
+        TypedKeyValue::Text(value) | TypedKeyValue::Timestamp(value) => RowValue::String(value),
+        TypedKeyValue::Boolean(value) => RowValue::Bool(value),
+        TypedKeyValue::Integer(value) => RowValue::I64(value),
+        TypedKeyValue::UnsignedInteger(value) => RowValue::U64(value),
+        TypedKeyValue::Float(value) => RowValue::F64(value),
+        TypedKeyValue::Bytes(value) => RowValue::Bytes(value),
+        TypedKeyValue::Json(value) => RowValue::Json(value),
+    })
+}
+
+pub(super) fn typed_value_from_row(
+    schema: &TableSchema,
+    column: &TableColumn,
+    value: &RowValue,
+) -> Result<TypedKeyValue, ProjectionScopeCodecError> {
+    if matches!(
+        value,
+        RowValue::Null | RowValue::Json(serde_json::Value::Null)
+    ) {
+        return Err(ProjectionScopeCodecError::NullPrimaryKey {
+            model: schema.model_name.clone(),
+            field: column.field_name.clone(),
+        });
+    }
+
+    let wrong_shape = |expected| ProjectionScopeCodecError::WrongRowValueShape {
+        model: schema.model_name.clone(),
+        column: column.column_name.clone(),
+        expected,
+        actual: row_value_shape(value),
+    };
+    match (&column.column_type, value) {
+        (ColumnType::Text, RowValue::String(value)) => Ok(TypedKeyValue::Text(value.clone())),
+        (ColumnType::Boolean, RowValue::Bool(value)) => Ok(TypedKeyValue::Boolean(*value)),
+        (ColumnType::Integer, RowValue::I64(value)) => Ok(TypedKeyValue::Integer(*value)),
+        (ColumnType::UnsignedInteger, RowValue::U64(value)) => {
+            Ok(TypedKeyValue::UnsignedInteger(*value))
+        }
+        (ColumnType::Float, RowValue::F64(value)) if value.is_finite() => {
+            Ok(TypedKeyValue::Float(*value))
+        }
+        (ColumnType::Float, RowValue::F64(_)) => Err(ProjectionScopeCodecError::NonFiniteFloat {
+            model: schema.model_name.clone(),
+            field: column.field_name.clone(),
+        }),
+        (ColumnType::Bytes, RowValue::Bytes(value)) => Ok(TypedKeyValue::Bytes(value.clone())),
+        (ColumnType::Json, RowValue::Json(value)) => Ok(TypedKeyValue::Json(value.clone())),
+        (ColumnType::Timestamp, RowValue::String(value)) => {
+            Ok(TypedKeyValue::Timestamp(value.clone()))
+        }
+        (ColumnType::Unsupported(type_name), _) => {
+            Err(ProjectionScopeCodecError::InvalidModelRegistration {
+                model: schema.model_name.clone(),
+                reason: format!(
+                    "primary-key column `{}` has unsupported type `{type_name}`",
+                    column.column_name
+                ),
+            })
+        }
+        (column_type, _) => Err(wrong_shape(row_value_expectation(column_type))),
+    }
+}
+
+pub(super) fn encode_typed_key_value(
+    encoder: &mut CanonicalEncoder,
+    value: TypedKeyValue,
+) -> Result<(), ProjectionScopeCodecError> {
+    match value {
+        TypedKeyValue::Text(value) => {
+            encoder.push_tag(0)?;
+            encoder.push_bytes(value.as_bytes())
+        }
+        TypedKeyValue::Boolean(value) => {
+            encoder.push_tag(1)?;
+            encoder.push_tag(u8::from(value))
+        }
+        TypedKeyValue::Integer(value) => {
+            encoder.push_tag(2)?;
+            encoder.push_raw(&value.to_be_bytes())
+        }
+        TypedKeyValue::UnsignedInteger(value) => {
+            encoder.push_tag(3)?;
+            encoder.push_raw(&value.to_be_bytes())
+        }
+        TypedKeyValue::Float(value) => {
+            encoder.push_tag(4)?;
+            let canonical = if value == 0.0 { 0.0 } else { value };
+            encoder.push_raw(&canonical.to_bits().to_be_bytes())
+        }
+        TypedKeyValue::Bytes(value) => {
+            encoder.push_tag(5)?;
+            encoder.push_bytes(&value)
+        }
+        TypedKeyValue::Json(value) => {
+            encoder.push_tag(6)?;
+            encode_json(encoder, &value)
+        }
+        TypedKeyValue::Timestamp(value) => {
+            encoder.push_tag(7)?;
+            encoder.push_bytes(value.as_bytes())
+        }
+    }
+}
+
+pub(super) fn encode_json(
+    encoder: &mut CanonicalEncoder,
+    value: &serde_json::Value,
+) -> Result<(), ProjectionScopeCodecError> {
+    match value {
+        serde_json::Value::Null => encoder.push_tag(0),
+        serde_json::Value::Bool(false) => encoder.push_tag(1),
+        serde_json::Value::Bool(true) => encoder.push_tag(2),
+        serde_json::Value::Number(value) => {
+            encoder.push_tag(3)?;
+            encoder.push_bytes(value.to_string().as_bytes())
+        }
+        serde_json::Value::String(value) => {
+            encoder.push_tag(4)?;
+            encoder.push_bytes(value.as_bytes())
+        }
+        serde_json::Value::Array(values) => {
+            encoder.push_tag(5)?;
+            encoder.push_len(values.len())?;
+            for value in values {
+                encode_json(encoder, value)?;
+            }
+            Ok(())
+        }
+        serde_json::Value::Object(values) => {
+            encoder.push_tag(6)?;
+            encoder.push_len(values.len())?;
+            let mut entries = values.iter().collect::<Vec<_>>();
+            entries.sort_by(|left, right| left.0.cmp(right.0));
+            for (key, value) in entries {
+                encoder.push_bytes(key.as_bytes())?;
+                encode_json(encoder, value)?;
+            }
+            Ok(())
+        }
+    }
+}
+
+pub(super) struct CanonicalEncoder {
+    target: &'static str,
+    max: usize,
+    bytes: Vec<u8>,
+}
+
+impl CanonicalEncoder {
+    pub(super) fn new(
+        target: &'static str,
+        domain: &[u8],
+        max: usize,
+    ) -> Result<Self, ProjectionScopeCodecError> {
+        let mut encoder = Self {
+            target,
+            max,
+            bytes: Vec::with_capacity(domain.len() + 32),
+        };
+        encoder.push_raw(domain)?;
+        Ok(encoder)
+    }
+
+    pub(super) fn push_tag(&mut self, tag: u8) -> Result<(), ProjectionScopeCodecError> {
+        self.push_raw(&[tag])
+    }
+
+    pub(super) fn push_len(&mut self, len: usize) -> Result<(), ProjectionScopeCodecError> {
+        self.push_raw(&(len as u64).to_be_bytes())
+    }
+
+    pub(super) fn push_bytes(&mut self, value: &[u8]) -> Result<(), ProjectionScopeCodecError> {
+        self.push_len(value.len())?;
+        self.push_raw(value)
+    }
+
+    pub(super) fn push_raw(&mut self, value: &[u8]) -> Result<(), ProjectionScopeCodecError> {
+        if self.bytes.len().saturating_add(value.len()) > self.max {
+            return Err(ProjectionScopeCodecError::CanonicalEncodingTooLong {
+                target: self.target,
+                max: self.max,
+            });
+        }
+        self.bytes.extend_from_slice(value);
+        Ok(())
+    }
+
+    pub(super) fn finish(self) -> Vec<u8> {
+        self.bytes
+    }
+}
+
+fn json_shape(value: &serde_json::Value) -> &'static str {
+    match value {
+        serde_json::Value::Null => "null",
+        serde_json::Value::Bool(_) => "boolean",
+        serde_json::Value::Number(_) => "number",
+        serde_json::Value::String(_) => "string",
+        serde_json::Value::Array(_) => "array",
+        serde_json::Value::Object(_) => "object",
+    }
+}
+
+fn row_value_shape(value: &RowValue) -> &'static str {
+    match value {
+        RowValue::Null => "null",
+        RowValue::Bool(_) => "boolean",
+        RowValue::I64(_) => "signed integer",
+        RowValue::U64(_) => "unsigned integer",
+        RowValue::F64(_) => "float",
+        RowValue::String(_) => "string",
+        RowValue::Bytes(_) => "bytes",
+        RowValue::Json(_) => "json",
+    }
+}
+
+fn row_value_expectation(column_type: &ColumnType) -> &'static str {
+    match column_type {
+        ColumnType::Text | ColumnType::Timestamp => "a string RowValue",
+        ColumnType::Boolean => "a boolean RowValue",
+        ColumnType::Integer => "a signed-integer RowValue",
+        ColumnType::UnsignedInteger => "an unsigned-integer RowValue",
+        ColumnType::Float => "a finite-float RowValue",
+        ColumnType::Bytes => "a bytes RowValue",
+        ColumnType::Json => "a JSON RowValue",
+        ColumnType::Unsupported(_) => "a supported RowValue",
+    }
+}
diff --git a/src/projection_protocol/codec/mod.rs b/src/projection_protocol/codec/mod.rs
new file mode 100644
index 00000000..ae0e8ad9
--- /dev/null
+++ b/src/projection_protocol/codec/mod.rs
@@ -0,0 +1,21 @@
+//! Canonical projection partition and record-key encoding.
+//!
+//! A projector topology owns one codec registry. Command obligations and
+//! projector-side row keys both pass through this registry, so field/column
+//! aliases and scalar representations cannot silently produce different
+//! record identities.
+
+mod constants;
+mod errors;
+mod key;
+mod partition;
+mod scope;
+mod topology;
+
+#[cfg(test)]
+mod tests;
+
+pub(crate) use errors::ProjectionScopeCodecError;
+pub(crate) use partition::ProjectionPartitionSpec;
+pub(crate) use scope::ProjectionScopeCodec;
+pub(crate) use topology::{compile_projection_topology, CompiledProjectionTopology};
diff --git a/src/projection_protocol/codec/partition.rs b/src/projection_protocol/codec/partition.rs
new file mode 100644
index 00000000..c579f878
--- /dev/null
+++ b/src/projection_protocol/codec/partition.rs
@@ -0,0 +1,96 @@
+use super::constants::{MAX_PARTITION_PATH_DEPTH, MAX_PARTITION_PATH_SEGMENT_BYTES};
+use crate::projection_protocol::{ProjectionProtocolError, MAX_PROJECTION_PARTITION_BYTES};
+
+/// Canonical declaration-owned partition derivation for one projector.
+///
+/// The runtime evaluates this closed IR from raw JSON before decoding the
+/// typed event. It is also part of the compiled topology digest, so changing
+/// partition semantics necessarily creates a different durable topology.
+#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub(crate) enum ProjectionPartitionSpec {
+    Unit,
+    InputPath { path: Vec<String> },
+    Constant { value: serde_json::Value },
+}
+
+impl ProjectionPartitionSpec {
+    pub(crate) fn unit() -> Self {
+        Self::Unit
+    }
+
+    pub(crate) fn input_path(path: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        Self::InputPath {
+            path: path.into_iter().map(Into::into).collect(),
+        }
+    }
+
+    pub(crate) fn constant(value: serde_json::Value) -> Self {
+        Self::Constant { value }
+    }
+
+    pub(crate) fn preserves_source_sequence(&self) -> bool {
+        matches!(self, Self::Unit | Self::Constant { .. })
+    }
+
+    pub(crate) fn requires_input(&self) -> bool {
+        matches!(self, Self::InputPath { .. })
+    }
+
+    pub(crate) fn validate(&self) -> Result<(), ProjectionProtocolError> {
+        match self {
+            Self::InputPath { path } => {
+                if path.is_empty()
+                    || path.len() > MAX_PARTITION_PATH_DEPTH
+                    || path.iter().any(|segment| {
+                        segment.trim().is_empty()
+                            || segment.as_bytes().len() > MAX_PARTITION_PATH_SEGMENT_BYTES
+                    })
+                {
+                    return Err(ProjectionProtocolError::InvalidBatch(format!(
+                        "projection partition input path must contain 1..={MAX_PARTITION_PATH_DEPTH} non-empty segments of at most {MAX_PARTITION_PATH_SEGMENT_BYTES} bytes"
+                    )));
+                }
+            }
+            Self::Constant { value } => {
+                let bytes = serde_json::to_vec(value).map_err(|error| {
+                    ProjectionProtocolError::InvalidBatch(format!(
+                        "projection partition constant cannot be serialized: {error}"
+                    ))
+                })?;
+                if bytes.len() > MAX_PROJECTION_PARTITION_BYTES {
+                    return Err(ProjectionProtocolError::InvalidBatch(format!(
+                        "projection partition constant exceeds {MAX_PROJECTION_PARTITION_BYTES} canonical JSON bytes"
+                    )));
+                }
+            }
+            Self::Unit => {}
+        }
+        Ok(())
+    }
+
+    pub(crate) fn resolve(
+        &self,
+        canonical_input: &serde_json::Value,
+    ) -> Result<Option<serde_json::Value>, ProjectionProtocolError> {
+        match self {
+            Self::Unit => Ok(None),
+            Self::Constant { value } => Ok(Some(value.clone())),
+            Self::InputPath { path } => {
+                let mut value = canonical_input;
+                for segment in path {
+                    value = value
+                        .as_object()
+                        .and_then(|object| object.get(segment))
+                        .ok_or_else(|| {
+                            ProjectionProtocolError::InvalidBatch(format!(
+                                "projection partition input path `{}` is absent",
+                                path.join(".")
+                            ))
+                        })?;
+                }
+                Ok(Some(value.clone()))
+            }
+        }
+    }
+}
diff --git a/src/projection_protocol/codec/scope.rs b/src/projection_protocol/codec/scope.rs
new file mode 100644
index 00000000..1b74e7dd
--- /dev/null
+++ b/src/projection_protocol/codec/scope.rs
@@ -0,0 +1,377 @@
+use std::collections::{BTreeMap, BTreeSet};
+use std::sync::Arc;
+
+use super::constants::{PARTITION_ENCODING_DOMAIN, RECORD_KEY_ENCODING_DOMAIN};
+use super::key::{
+    encode_json, encode_typed_key_value, key_column, row_value_from_graphql_json,
+    typed_value_from_json, typed_value_from_row, validate_model_schema, validate_registration_name,
+    CanonicalEncoder, TypedKeyValue,
+};
+use super::ProjectionScopeCodecError;
+use crate::projection_protocol::{
+    ProjectionPartition, ProjectionRecordScope, ProjectorTopologyId, ResolvedProjectionKey,
+    ResolvedProjectionObligation, MAX_PROJECTION_PARTITION_BYTES, MAX_PROJECTION_RECORD_KEY_BYTES,
+};
+use crate::table::{RowKey, TableColumn, TableSchema};
+
+/// A topology-bound registry for canonical projection partitions and keys.
+///
+/// Registration is deliberately explicit: the projector's declared model name
+/// must exactly match the registered schema's model name. Obligation keys use
+/// Rust/GraphQL `field_name`s, while projector [`RowKey`] values use storage
+/// `column_name`s; both are lowered in the schema's primary-key column order.
+#[derive(Clone, Debug)]
+pub(crate) struct ProjectionScopeCodec {
+    topology: ProjectorTopologyId,
+    models: BTreeMap<String, Arc<TableSchema>>,
+}
+
+impl ProjectionScopeCodec {
+    pub(crate) fn new(topology: ProjectorTopologyId) -> Self {
+        Self {
+            topology,
+            models: BTreeMap::new(),
+        }
+    }
+
+    pub(crate) fn with_models<'a>(
+        topology: ProjectorTopologyId,
+        models: impl IntoIterator<Item = (&'a str, &'a TableSchema)>,
+    ) -> Result<Self, ProjectionScopeCodecError> {
+        let mut codec = Self::new(topology);
+        for (model, schema) in models {
+            codec.register_model(model, schema)?;
+        }
+        Ok(codec)
+    }
+
+    pub(crate) fn topology(&self) -> &ProjectorTopologyId {
+        &self.topology
+    }
+
+    /// Register one projection model under its compiler-declared model name.
+    ///
+    /// The codec owns an immutable clone so runtime-loaded manifests and
+    /// generated static schemas have identical lifetime and mutation
+    /// semantics. A caller may discard or mutate its original clone after
+    /// registration without changing the compiled topology.
+    pub(crate) fn register_model(
+        &mut self,
+        declared_model: &str,
+        schema: &TableSchema,
+    ) -> Result<&mut Self, ProjectionScopeCodecError> {
+        validate_registration_name(declared_model)?;
+        if declared_model != schema.model_name {
+            return Err(ProjectionScopeCodecError::ModelRegistrationMismatch {
+                declared: declared_model.to_string(),
+                schema: schema.model_name.clone(),
+            });
+        }
+        if self.models.contains_key(declared_model) {
+            return Err(ProjectionScopeCodecError::DuplicateModelRegistration {
+                model: declared_model.to_string(),
+            });
+        }
+        validate_model_schema(schema)?;
+        self.models
+            .insert(declared_model.to_string(), Arc::new(schema.clone()));
+        Ok(self)
+    }
+
+    /// Encode the declaration's optional partition.
+    ///
+    /// `None` is a canonical unit scope. `Some(Value::Null)` is an explicit
+    /// JSON null and therefore has a distinct byte representation and digest.
+    pub(crate) fn encode_partition(
+        &self,
+        partition: Option<&serde_json::Value>,
+    ) -> Result<ProjectionPartition, ProjectionScopeCodecError> {
+        let mut encoder = CanonicalEncoder::new(
+            "projection partition",
+            PARTITION_ENCODING_DOMAIN,
+            MAX_PROJECTION_PARTITION_BYTES,
+        )?;
+        match partition {
+            None => encoder.push_tag(0)?,
+            Some(partition) => {
+                encoder.push_tag(1)?;
+                encode_json(&mut encoder, partition)?;
+            }
+        }
+        ProjectionPartition::new(encoder.finish()).map_err(Into::into)
+    }
+
+    /// Lower a command-ledger obligation into its exact durable record scope.
+    #[allow(dead_code)]
+    pub(crate) fn encode_obligation_scope(
+        &self,
+        obligation: &ResolvedProjectionObligation,
+    ) -> Result<ProjectionRecordScope, ProjectionScopeCodecError> {
+        let computed = self.encode_resolved_obligation_scope(
+            &obligation.projector,
+            &obligation.model,
+            &obligation.key,
+            obligation.partition.as_ref(),
+        )?;
+        if computed != obligation.scope {
+            return Err(ProjectionScopeCodecError::StoredScopeMismatch {
+                projector: obligation.projector.clone(),
+                model: obligation.model.clone(),
+            });
+        }
+        Ok(computed)
+    }
+
+    pub(crate) fn encode_resolved_obligation_scope(
+        &self,
+        projector: &str,
+        model: &str,
+        key: &ResolvedProjectionKey,
+        partition_value: Option<&serde_json::Value>,
+    ) -> Result<ProjectionRecordScope, ProjectionScopeCodecError> {
+        self.validate_projector(projector)?;
+        let schema = self.model(model)?;
+        let partition = self.encode_partition(partition_value)?;
+
+        let mut fields = BTreeMap::new();
+        for field in &key.fields {
+            if fields.insert(field.field.as_str(), &field.value).is_some() {
+                return Err(ProjectionScopeCodecError::DuplicateKeyField {
+                    model: model.to_string(),
+                    field: field.field.clone(),
+                });
+            }
+        }
+
+        let primary_key_fields = schema
+            .primary_key
+            .columns
+            .iter()
+            .map(|column_name| {
+                key_column(schema, column_name)
+                    .expect("registered projection schemas retain their validated key columns")
+                    .field_name
+                    .as_str()
+            })
+            .collect::<BTreeSet<_>>();
+        if let Some(extra) = fields
+            .keys()
+            .find(|field| !primary_key_fields.contains(**field))
+        {
+            return Err(ProjectionScopeCodecError::ExtraKeyField {
+                model: model.to_string(),
+                field: (*extra).to_string(),
+            });
+        }
+
+        let canonical_key_bytes = self.encode_key(schema, |column| {
+            fields
+                .get(column.field_name.as_str())
+                .copied()
+                .ok_or_else(|| ProjectionScopeCodecError::MissingKeyField {
+                    model: schema.model_name.clone(),
+                    field: column.field_name.clone(),
+                })
+                .and_then(|value| typed_value_from_json(schema, column, value))
+        })?;
+
+        ProjectionRecordScope::new(
+            self.topology.clone(),
+            partition,
+            schema.model_name.clone(),
+            canonical_key_bytes,
+        )
+        .map_err(Into::into)
+    }
+
+    /// Lower a projector-side row key into the same durable record scope used
+    /// by command obligations.
+    pub(crate) fn encode_row_scope(
+        &self,
+        projector: &str,
+        model: &str,
+        partition: Option<&serde_json::Value>,
+        key: &RowKey,
+    ) -> Result<ProjectionRecordScope, ProjectionScopeCodecError> {
+        self.validate_projector(projector)?;
+        let partition = self.encode_partition(partition)?;
+        self.encode_row_scope_in_partition(model, partition, key)
+    }
+
+    /// Lower a row key after the framework has already resolved the exact
+    /// canonical projector partition.
+    ///
+    /// Query snapshots use this seam so the physical row key and durable
+    /// record scope are derived by the same registered codec. Callers cannot
+    /// pair arbitrary row values with independently supplied scope bytes.
+    pub(crate) fn encode_row_scope_in_partition(
+        &self,
+        model: &str,
+        partition: ProjectionPartition,
+        key: &RowKey,
+    ) -> Result<ProjectionRecordScope, ProjectionScopeCodecError> {
+        let schema = self.model(model)?;
+        let canonical_key_bytes = self.encode_row_key(schema, key)?;
+
+        ProjectionRecordScope::new(
+            self.topology.clone(),
+            partition,
+            schema.model_name.clone(),
+            canonical_key_bytes,
+        )
+        .map_err(Into::into)
+    }
+
+    /// Encode only the typed primary-key identity, without choosing a
+    /// projector partition.
+    ///
+    /// Physical query rows do not carry their hidden causal partition. Query
+    /// evidence uses these canonical bytes to find the one live record across
+    /// partitions, then returns that record's exact stored scope.
+    pub(crate) fn encode_unpartitioned_row_key(
+        &self,
+        model: &str,
+        key: &RowKey,
+    ) -> Result<Vec<u8>, ProjectionScopeCodecError> {
+        let schema = self.model(model)?;
+        self.encode_row_key(schema, key)
+    }
+
+    /// Decode complete primary-key columns from GraphQL/JSON without passing
+    /// through JavaScript numeric coercion or a second schema interpretation.
+    ///
+    /// Integer keys accept either an exact JSON integer or the canonical
+    /// decimal string used by GraphQL `BigInt`. Byte keys require canonical
+    /// standard-base64. Returned [`RowKey`] values use physical column names,
+    /// ready for [`Self::encode_unpartitioned_row_key`].
+    pub(crate) fn row_key_from_json_columns(
+        &self,
+        model: &str,
+        values: &BTreeMap<String, serde_json::Value>,
+    ) -> Result<RowKey, ProjectionScopeCodecError> {
+        let schema = self.model(model)?;
+        let primary_key_columns = schema
+            .primary_key
+            .columns
+            .iter()
+            .map(String::as_str)
+            .collect::<BTreeSet<_>>();
+        if let Some(extra) = values
+            .keys()
+            .find(|column| !primary_key_columns.contains(column.as_str()))
+        {
+            return Err(ProjectionScopeCodecError::ExtraKeyColumn {
+                model: schema.model_name.clone(),
+                column: extra.clone(),
+            });
+        }
+
+        let mut key = RowKey::default();
+        for column_name in &schema.primary_key.columns {
+            let column = key_column(schema, column_name)
+                .expect("registered projection schemas retain their validated key columns");
+            let value = values.get(column_name).ok_or_else(|| {
+                ProjectionScopeCodecError::MissingKeyColumn {
+                    model: schema.model_name.clone(),
+                    column: column_name.clone(),
+                }
+            })?;
+            key.insert(
+                column_name,
+                row_value_from_graphql_json(schema, column, value)?,
+            );
+        }
+        Ok(key)
+    }
+
+    fn encode_row_key(
+        &self,
+        schema: &TableSchema,
+        key: &RowKey,
+    ) -> Result<Vec<u8>, ProjectionScopeCodecError> {
+        let primary_key_columns = schema
+            .primary_key
+            .columns
+            .iter()
+            .map(String::as_str)
+            .collect::<BTreeSet<_>>();
+        if let Some((extra, _)) = key
+            .iter()
+            .find(|(column, _)| !primary_key_columns.contains(*column))
+        {
+            return Err(ProjectionScopeCodecError::ExtraKeyColumn {
+                model: schema.model_name.clone(),
+                column: extra.to_string(),
+            });
+        }
+
+        self.encode_key(schema, |column| {
+            key.get(&column.column_name)
+                .ok_or_else(|| ProjectionScopeCodecError::MissingKeyColumn {
+                    model: schema.model_name.clone(),
+                    column: column.column_name.clone(),
+                })
+                .and_then(|value| typed_value_from_row(schema, column, value))
+        })
+    }
+
+    pub(crate) fn registered_schema(
+        &self,
+        model: &str,
+    ) -> Result<&TableSchema, ProjectionScopeCodecError> {
+        self.model(model)
+    }
+
+    pub(crate) fn registered_schema_owned(
+        &self,
+        model: &str,
+    ) -> Result<Arc<TableSchema>, ProjectionScopeCodecError> {
+        self.models
+            .get(model)
+            .cloned()
+            .ok_or_else(|| ProjectionScopeCodecError::UnknownModel {
+                projector: self.topology.name().to_string(),
+                model: model.to_string(),
+            })
+    }
+
+    fn validate_projector(&self, projector: &str) -> Result<(), ProjectionScopeCodecError> {
+        if projector == self.topology.name() {
+            Ok(())
+        } else {
+            Err(ProjectionScopeCodecError::ProjectorMismatch {
+                expected: self.topology.name().to_string(),
+                actual: projector.to_string(),
+            })
+        }
+    }
+
+    fn model(&self, model: &str) -> Result<&TableSchema, ProjectionScopeCodecError> {
+        self.models.get(model).map(AsRef::as_ref).ok_or_else(|| {
+            ProjectionScopeCodecError::UnknownModel {
+                projector: self.topology.name().to_string(),
+                model: model.to_string(),
+            }
+        })
+    }
+
+    fn encode_key(
+        &self,
+        schema: &TableSchema,
+        mut value_for: impl FnMut(&TableColumn) -> Result<TypedKeyValue, ProjectionScopeCodecError>,
+    ) -> Result<Vec<u8>, ProjectionScopeCodecError> {
+        let mut encoder = CanonicalEncoder::new(
+            "projection record key",
+            RECORD_KEY_ENCODING_DOMAIN,
+            MAX_PROJECTION_RECORD_KEY_BYTES,
+        )?;
+        encoder.push_len(schema.primary_key.columns.len())?;
+        for column_name in &schema.primary_key.columns {
+            let column = key_column(schema, column_name)
+                .expect("registered projection schemas retain their validated key columns");
+            encoder.push_bytes(column.column_name.as_bytes())?;
+            encode_typed_key_value(&mut encoder, value_for(column)?)?;
+        }
+        Ok(encoder.finish())
+    }
+}
diff --git a/src/projection_protocol/codec/tests.rs b/src/projection_protocol/codec/tests.rs
new file mode 100644
index 00000000..9d798770
--- /dev/null
+++ b/src/projection_protocol/codec/tests.rs
@@ -0,0 +1,628 @@
+use std::collections::BTreeMap;
+
+use super::{ProjectionScopeCodec, ProjectionScopeCodecError};
+use crate::projection_protocol::{
+    ProjectionRecordScope, ProjectorTopologyId, ResolvedProjectionKey, ResolvedProjectionKeyField,
+    ResolvedProjectionObligation,
+};
+use crate::table::{ColumnType, PrimaryKey, RowKey, RowValue, TableColumn, TableKind, TableSchema};
+
+fn topology() -> ProjectorTopologyId {
+    ProjectorTopologyId::new(3, "project_memberships", [7; 32]).unwrap()
+}
+
+fn schema(
+    model: &str,
+    table: &str,
+    columns: Vec<TableColumn>,
+    primary_key: &[&str],
+) -> &'static TableSchema {
+    Box::leak(Box::new(TableSchema {
+        model_name: model.into(),
+        table_name: table.into(),
+        columns,
+        primary_key: PrimaryKey::new(primary_key.iter().copied()),
+        version_column: Some("_sourced_version".into()),
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    }))
+}
+
+fn key_column(field: &str, column: &str, column_type: ColumnType) -> TableColumn {
+    TableColumn {
+        primary_key: true,
+        ..TableColumn::new(field, column, column_type)
+    }
+}
+
+fn obligation(
+    codec: &ProjectionScopeCodec,
+    projector: &str,
+    model: &str,
+    partition: Option<serde_json::Value>,
+    fields: impl IntoIterator<Item = (&'static str, serde_json::Value)>,
+) -> ResolvedProjectionObligation {
+    let key = ResolvedProjectionKey {
+        fields: fields
+            .into_iter()
+            .map(|(field, value)| ResolvedProjectionKeyField {
+                field: field.into(),
+                value,
+            })
+            .collect(),
+    };
+    let scope = codec
+        .encode_resolved_obligation_scope(projector, model, &key, partition.as_ref())
+        .unwrap_or_else(|_| {
+            ProjectionRecordScope::new(
+                codec.topology().clone(),
+                codec.encode_partition(partition.as_ref()).unwrap(),
+                model,
+                b"invalid-test-key".to_vec(),
+            )
+            .unwrap()
+        });
+    ResolvedProjectionObligation {
+        projector: projector.into(),
+        model: model.into(),
+        partition,
+        key,
+        scope,
+    }
+}
+
+#[test]
+fn obligation_and_row_keys_share_one_schema_ordered_composite_encoding() {
+    let membership = schema(
+        "Membership",
+        "memberships",
+        vec![
+            key_column("tenantId", "tenant_id", ColumnType::Text),
+            key_column("sequence", "member_sequence", ColumnType::UnsignedInteger),
+            key_column("attributes", "attributes_json", ColumnType::Json),
+        ],
+        &["tenant_id", "member_sequence", "attributes_json"],
+    );
+    let codec =
+        ProjectionScopeCodec::with_models(topology(), [("Membership", membership)]).unwrap();
+    let command_partition =
+        serde_json::from_str(r#"{"region":"west","tenant":{"id":"t-1","tier":2}}"#).unwrap();
+    let projector_partition =
+        serde_json::from_str(r#"{"tenant":{"tier":2,"id":"t-1"},"region":"west"}"#).unwrap();
+    let command = obligation(
+        &codec,
+        "project_memberships",
+        "Membership",
+        Some(command_partition),
+        [
+            (
+                "attributes",
+                serde_json::json!({"z": [2, 1], "a": {"b": true}}),
+            ),
+            ("sequence", serde_json::json!(42_u64)),
+            ("tenantId", serde_json::json!("t-1")),
+        ],
+    );
+    let row = RowKey::new([
+        ("tenant_id", RowValue::String("t-1".into())),
+        ("member_sequence", RowValue::U64(42)),
+        (
+            "attributes_json",
+            RowValue::Json(serde_json::json!({"a": {"b": true}, "z": [2, 1]})),
+        ),
+    ]);
+
+    let obligation_scope = codec.encode_obligation_scope(&command).unwrap();
+    let row_scope = codec
+        .encode_row_scope(
+            "project_memberships",
+            "Membership",
+            Some(&projector_partition),
+            &row,
+        )
+        .unwrap();
+
+    assert_eq!(obligation_scope, row_scope);
+    assert_eq!(
+        obligation_scope.canonical_key_bytes(),
+        row_scope.canonical_key_bytes()
+    );
+    assert_eq!(obligation_scope.key_digest(), row_scope.key_digest());
+}
+
+#[test]
+fn recursive_json_is_object_order_invariant_and_absent_is_not_null() {
+    let codec = ProjectionScopeCodec::new(topology());
+    let left = serde_json::from_str(r#"{"z":{"b":2,"a":1},"a":[{"y":true,"x":null}]}"#).unwrap();
+    let right = serde_json::from_str(r#"{"a":[{"x":null,"y":true}],"z":{"a":1,"b":2}}"#).unwrap();
+
+    assert_eq!(
+        codec.encode_partition(Some(&left)).unwrap(),
+        codec.encode_partition(Some(&right)).unwrap()
+    );
+
+    let absent = codec.encode_partition(None).unwrap();
+    let explicit_null = codec
+        .encode_partition(Some(&serde_json::Value::Null))
+        .unwrap();
+    assert_ne!(absent.canonical_bytes(), explicit_null.canonical_bytes());
+    assert_ne!(absent.digest(), explicit_null.digest());
+}
+
+#[test]
+fn integer_schema_controls_signedness_and_range() {
+    let signed = schema(
+        "SignedRecord",
+        "signed_records",
+        vec![key_column("id", "id", ColumnType::Integer)],
+        &["id"],
+    );
+    let unsigned = schema(
+        "UnsignedRecord",
+        "unsigned_records",
+        vec![key_column("id", "id", ColumnType::UnsignedInteger)],
+        &["id"],
+    );
+    let codec = ProjectionScopeCodec::with_models(
+        topology(),
+        [("SignedRecord", signed), ("UnsignedRecord", unsigned)],
+    )
+    .unwrap();
+
+    let signed_command = obligation(
+        &codec,
+        "project_memberships",
+        "SignedRecord",
+        None,
+        [("id", serde_json::json!(-1))],
+    );
+    let signed_row = RowKey::new([("id", RowValue::I64(-1))]);
+    assert_eq!(
+        codec.encode_obligation_scope(&signed_command).unwrap(),
+        codec
+            .encode_row_scope("project_memberships", "SignedRecord", None, &signed_row)
+            .unwrap()
+    );
+
+    let unsigned_command = obligation(
+        &codec,
+        "project_memberships",
+        "UnsignedRecord",
+        None,
+        [("id", serde_json::json!(u64::MAX))],
+    );
+    let unsigned_row = RowKey::new([("id", RowValue::U64(u64::MAX))]);
+    assert_eq!(
+        codec.encode_obligation_scope(&unsigned_command).unwrap(),
+        codec
+            .encode_row_scope("project_memberships", "UnsignedRecord", None, &unsigned_row)
+            .unwrap()
+    );
+
+    let negative_unsigned = obligation(
+        &codec,
+        "project_memberships",
+        "UnsignedRecord",
+        None,
+        [("id", serde_json::json!(-1))],
+    );
+    assert!(matches!(
+        codec.encode_obligation_scope(&negative_unsigned),
+        Err(ProjectionScopeCodecError::IntegerOutOfRange {
+            expected: "unsigned 64-bit integer",
+            ..
+        })
+    ));
+
+    let too_large_signed = obligation(
+        &codec,
+        "project_memberships",
+        "SignedRecord",
+        None,
+        [("id", serde_json::json!(u64::MAX))],
+    );
+    assert!(matches!(
+        codec.encode_obligation_scope(&too_large_signed),
+        Err(ProjectionScopeCodecError::IntegerOutOfRange {
+            expected: "signed 64-bit integer",
+            ..
+        })
+    ));
+    assert!(matches!(
+        codec.encode_row_scope(
+            "project_memberships",
+            "SignedRecord",
+            None,
+            &RowKey::new([("id", RowValue::U64(1))]),
+        ),
+        Err(ProjectionScopeCodecError::WrongRowValueShape { .. })
+    ));
+    assert!(matches!(
+        codec.encode_row_scope(
+            "project_memberships",
+            "UnsignedRecord",
+            None,
+            &RowKey::new([("id", RowValue::I64(1))]),
+        ),
+        Err(ProjectionScopeCodecError::WrongRowValueShape { .. })
+    ));
+}
+
+#[test]
+fn registration_and_topology_mismatches_fail_closed() {
+    let record = schema(
+        "Record",
+        "records",
+        vec![key_column("id", "record_id", ColumnType::Text)],
+        &["record_id"],
+    );
+    let mismatched = schema(
+        "Actual",
+        "actual",
+        vec![key_column("id", "id", ColumnType::Text)],
+        &["id"],
+    );
+    let malformed = schema(
+        "Malformed",
+        "malformed",
+        vec![TableColumn::new("id", "id", ColumnType::Text)],
+        &["id"],
+    );
+    let mut codec = ProjectionScopeCodec::new(topology());
+
+    assert_eq!(
+        codec.register_model("", record).unwrap_err(),
+        ProjectionScopeCodecError::BlankModelRegistration
+    );
+    assert!(matches!(
+        codec.register_model("Declared", mismatched),
+        Err(ProjectionScopeCodecError::ModelRegistrationMismatch { .. })
+    ));
+    assert!(matches!(
+        codec.register_model("Malformed", malformed),
+        Err(ProjectionScopeCodecError::InvalidModelRegistration { .. })
+    ));
+    codec.register_model("Record", record).unwrap();
+    assert!(matches!(
+        codec.register_model("Record", record),
+        Err(ProjectionScopeCodecError::DuplicateModelRegistration { .. })
+    ));
+
+    let wrong_projector = obligation(
+        &codec,
+        "another_projector",
+        "Record",
+        None,
+        [("id", serde_json::json!("r-1"))],
+    );
+    assert!(matches!(
+        codec.encode_obligation_scope(&wrong_projector),
+        Err(ProjectionScopeCodecError::ProjectorMismatch { .. })
+    ));
+    let unknown_model = obligation(
+        &codec,
+        "project_memberships",
+        "Unknown",
+        None,
+        [("id", serde_json::json!("r-1"))],
+    );
+    assert!(matches!(
+        codec.encode_obligation_scope(&unknown_model),
+        Err(ProjectionScopeCodecError::UnknownModel { .. })
+    ));
+    assert!(matches!(
+        codec.encode_row_scope(
+            "another_projector",
+            "Record",
+            None,
+            &RowKey::new([("record_id", RowValue::String("r-1".into()))]),
+        ),
+        Err(ProjectionScopeCodecError::ProjectorMismatch { .. })
+    ));
+}
+
+#[test]
+fn malformed_obligation_and_row_keys_fail_closed() {
+    let record = schema(
+        "Record",
+        "records",
+        vec![
+            key_column("id", "record_id", ColumnType::Text),
+            key_column("active", "is_active", ColumnType::Boolean),
+        ],
+        &["record_id", "is_active"],
+    );
+    let float_record = schema(
+        "FloatRecord",
+        "float_records",
+        vec![key_column("id", "id", ColumnType::Float)],
+        &["id"],
+    );
+    let bytes_record = schema(
+        "BytesRecord",
+        "bytes_records",
+        vec![key_column("id", "id", ColumnType::Bytes)],
+        &["id"],
+    );
+    let codec = ProjectionScopeCodec::with_models(
+        topology(),
+        [
+            ("Record", record),
+            ("FloatRecord", float_record),
+            ("BytesRecord", bytes_record),
+        ],
+    )
+    .unwrap();
+
+    let missing = obligation(
+        &codec,
+        "project_memberships",
+        "Record",
+        None,
+        [("id", serde_json::json!("r-1"))],
+    );
+    assert!(matches!(
+        codec.encode_obligation_scope(&missing),
+        Err(ProjectionScopeCodecError::MissingKeyField { field, .. })
+            if field == "active"
+    ));
+
+    let extra = obligation(
+        &codec,
+        "project_memberships",
+        "Record",
+        None,
+        [
+            ("id", serde_json::json!("r-1")),
+            ("active", serde_json::json!(true)),
+            ("other", serde_json::json!(1)),
+        ],
+    );
+    assert!(matches!(
+        codec.encode_obligation_scope(&extra),
+        Err(ProjectionScopeCodecError::ExtraKeyField { field, .. })
+            if field == "other"
+    ));
+
+    let duplicate = obligation(
+        &codec,
+        "project_memberships",
+        "Record",
+        None,
+        [
+            ("id", serde_json::json!("r-1")),
+            ("id", serde_json::json!("r-2")),
+            ("active", serde_json::json!(true)),
+        ],
+    );
+    assert!(matches!(
+        codec.encode_obligation_scope(&duplicate),
+        Err(ProjectionScopeCodecError::DuplicateKeyField { field, .. })
+            if field == "id"
+    ));
+
+    let null = obligation(
+        &codec,
+        "project_memberships",
+        "Record",
+        None,
+        [
+            ("id", serde_json::Value::Null),
+            ("active", serde_json::json!(true)),
+        ],
+    );
+    assert!(matches!(
+        codec.encode_obligation_scope(&null),
+        Err(ProjectionScopeCodecError::NullPrimaryKey { field, .. })
+            if field == "id"
+    ));
+
+    let wrong_json_shape = obligation(
+        &codec,
+        "project_memberships",
+        "Record",
+        None,
+        [
+            ("id", serde_json::json!("r-1")),
+            ("active", serde_json::json!("true")),
+        ],
+    );
+    assert!(matches!(
+        codec.encode_obligation_scope(&wrong_json_shape),
+        Err(ProjectionScopeCodecError::WrongJsonShape { field, .. })
+            if field == "active"
+    ));
+
+    assert!(matches!(
+        codec.encode_row_scope(
+            "project_memberships",
+            "Record",
+            None,
+            &RowKey::new([
+                ("record_id", RowValue::String("r-1".into())),
+                ("is_active", RowValue::String("true".into())),
+            ]),
+        ),
+        Err(ProjectionScopeCodecError::WrongRowValueShape { column, .. })
+            if column == "is_active"
+    ));
+    assert!(matches!(
+        codec.encode_row_scope(
+            "project_memberships",
+            "Record",
+            None,
+            &RowKey::new([
+                ("record_id", RowValue::String("r-1".into())),
+                ("is_active", RowValue::Bool(true)),
+                ("other", RowValue::I64(1)),
+            ]),
+        ),
+        Err(ProjectionScopeCodecError::ExtraKeyColumn { column, .. })
+            if column == "other"
+    ));
+    assert!(matches!(
+        codec.encode_row_scope(
+            "project_memberships",
+            "Record",
+            None,
+            &RowKey::new([("record_id", RowValue::String("r-1".into()))]),
+        ),
+        Err(ProjectionScopeCodecError::MissingKeyColumn { column, .. })
+            if column == "is_active"
+    ));
+    assert!(matches!(
+        codec.encode_row_scope(
+            "project_memberships",
+            "FloatRecord",
+            None,
+            &RowKey::new([("id", RowValue::F64(f64::NAN))]),
+        ),
+        Err(ProjectionScopeCodecError::NonFiniteFloat { .. })
+    ));
+
+    let noncanonical_base64 = obligation(
+        &codec,
+        "project_memberships",
+        "BytesRecord",
+        None,
+        [("id", serde_json::json!("AB=="))],
+    );
+    assert!(matches!(
+        codec.encode_obligation_scope(&noncanonical_base64),
+        Err(ProjectionScopeCodecError::InvalidBytes { .. })
+    ));
+}
+
+#[test]
+fn codec_owns_registered_schema_independently_of_the_caller() {
+    let mut original = TableSchema {
+        model_name: "OwnedRecord".into(),
+        table_name: "owned_records".into(),
+        columns: vec![key_column("id", "record_id", ColumnType::Text)],
+        primary_key: PrimaryKey::new(["record_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    };
+    let codec =
+        ProjectionScopeCodec::with_models(topology(), [("OwnedRecord", &original)]).unwrap();
+
+    original.model_name = "MutatedAfterRegistration".into();
+    original.table_name = "mutated_after_registration".into();
+    original.primary_key = PrimaryKey::new(["not_the_registered_key"]);
+    drop(original);
+
+    let registered = codec.registered_schema("OwnedRecord").unwrap();
+    assert_eq!(registered.model_name, "OwnedRecord");
+    assert_eq!(registered.table_name, "owned_records");
+    assert_eq!(registered.primary_key.columns, ["record_id"]);
+    assert_eq!(
+        codec
+            .registered_schema_owned("OwnedRecord")
+            .unwrap()
+            .table_name,
+        "owned_records"
+    );
+}
+
+#[test]
+fn graphql_json_columns_decode_lossless_composite_row_keys() {
+    let composite = TableSchema {
+        model_name: "CompositeRecord".into(),
+        table_name: "composite_records".into(),
+        columns: vec![
+            key_column("signed", "signed_id", ColumnType::Integer),
+            key_column("unsigned", "unsigned_id", ColumnType::UnsignedInteger),
+            key_column("active", "is_active", ColumnType::Boolean),
+            key_column("digest", "digest_bytes", ColumnType::Bytes),
+            key_column("attributes", "attributes_json", ColumnType::Json),
+        ],
+        primary_key: PrimaryKey::new([
+            "signed_id",
+            "unsigned_id",
+            "is_active",
+            "digest_bytes",
+            "attributes_json",
+        ]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    };
+    let codec =
+        ProjectionScopeCodec::with_models(topology(), [("CompositeRecord", &composite)]).unwrap();
+    let values = BTreeMap::from([
+        (
+            "signed_id".into(),
+            serde_json::Value::String(i64::MIN.to_string()),
+        ),
+        (
+            "unsigned_id".into(),
+            serde_json::Value::String(u64::MAX.to_string()),
+        ),
+        ("is_active".into(), serde_json::json!(1)),
+        ("digest_bytes".into(), serde_json::json!("AP8=")),
+        (
+            "attributes_json".into(),
+            serde_json::json!({"z": [2, 1], "a": true}),
+        ),
+    ]);
+
+    let decoded = codec
+        .row_key_from_json_columns("CompositeRecord", &values)
+        .unwrap();
+    let expected = RowKey::new([
+        ("signed_id", RowValue::I64(i64::MIN)),
+        ("unsigned_id", RowValue::U64(u64::MAX)),
+        ("is_active", RowValue::Bool(true)),
+        ("digest_bytes", RowValue::Bytes(vec![0, 255])),
+        (
+            "attributes_json",
+            RowValue::Json(serde_json::json!({"a": true, "z": [2, 1]})),
+        ),
+    ]);
+    assert_eq!(decoded, expected);
+    assert_eq!(
+        codec
+            .encode_unpartitioned_row_key("CompositeRecord", &decoded)
+            .unwrap(),
+        codec
+            .encode_unpartitioned_row_key("CompositeRecord", &expected)
+            .unwrap()
+    );
+
+    let mut missing = values.clone();
+    missing.remove("digest_bytes");
+    assert!(matches!(
+        codec.row_key_from_json_columns("CompositeRecord", &missing),
+        Err(ProjectionScopeCodecError::MissingKeyColumn { column, .. })
+            if column == "digest_bytes"
+    ));
+
+    let mut extra = values.clone();
+    extra.insert("other".into(), serde_json::json!(1));
+    assert!(matches!(
+        codec.row_key_from_json_columns("CompositeRecord", &extra),
+        Err(ProjectionScopeCodecError::ExtraKeyColumn { column, .. })
+            if column == "other"
+    ));
+
+    let mut noncanonical_integer = values.clone();
+    noncanonical_integer.insert("signed_id".into(), serde_json::json!("01"));
+    assert!(matches!(
+        codec.row_key_from_json_columns("CompositeRecord", &noncanonical_integer),
+        Err(ProjectionScopeCodecError::IntegerOutOfRange { .. })
+    ));
+
+    let mut noncanonical_bytes = values;
+    noncanonical_bytes.insert("digest_bytes".into(), serde_json::json!("AB=="));
+    assert!(matches!(
+        codec.row_key_from_json_columns("CompositeRecord", &noncanonical_bytes),
+        Err(ProjectionScopeCodecError::InvalidBytes { .. })
+    ));
+}
diff --git a/src/projection_protocol/codec/topology.rs b/src/projection_protocol/codec/topology.rs
new file mode 100644
index 00000000..e005e347
--- /dev/null
+++ b/src/projection_protocol/codec/topology.rs
@@ -0,0 +1,194 @@
+use std::collections::{BTreeMap, BTreeSet};
+use std::sync::Arc;
+
+use sha2::{Digest, Sha256};
+
+use super::constants::{COMPILED_TOPOLOGY_DOMAIN, COMPILED_TOPOLOGY_VERSION, SCOPE_CODEC_VERSION};
+use super::{ProjectionPartitionSpec, ProjectionScopeCodec};
+use crate::projection_protocol::{
+    ProjectionModelOwnership, ProjectionProtocolError, ProjectorTopologyId,
+};
+use crate::table::TableSchema;
+
+/// One compiler-owned projector identity, codec, and complete physical
+/// ownership inventory.
+///
+/// GraphQL direct projection binding and the asynchronous projector runtime
+/// both derive their protocol identity through [`compile_projection_topology`].
+/// This product additionally retains the full typed schema registry needed by
+/// a running asynchronous projector. Application code never receives the
+/// codec or the authority to mint protocol scopes.
+#[derive(Clone, Debug)]
+pub(crate) struct CompiledProjectionTopology {
+    topology: ProjectorTopologyId,
+    codec: Arc<ProjectionScopeCodec>,
+    ownership: Vec<ProjectionModelOwnership>,
+    partition: ProjectionPartitionSpec,
+}
+
+impl CompiledProjectionTopology {
+    pub(crate) fn compile<'a>(
+        name: &str,
+        facts: &[String],
+        declared_models: &[String],
+        partition: &ProjectionPartitionSpec,
+        schemas: impl IntoIterator<Item = &'a TableSchema>,
+    ) -> Result<Self, ProjectionProtocolError> {
+        let schemas = schemas.into_iter().collect::<Vec<_>>();
+        let (topology, ownership) = compile_projection_topology(
+            name,
+            facts,
+            declared_models,
+            partition,
+            schemas.iter().copied(),
+        )?;
+        let codec = ProjectionScopeCodec::with_models(
+            topology.clone(),
+            schemas
+                .iter()
+                .map(|schema| (schema.model_name.as_str(), *schema)),
+        )
+        .map_err(|error| {
+            ProjectionProtocolError::InvalidBatch(format!(
+                "invalid compiled projection scope codec: {error}"
+            ))
+        })?;
+        Ok(Self {
+            topology,
+            codec: Arc::new(codec),
+            ownership,
+            partition: partition.clone(),
+        })
+    }
+
+    pub(crate) fn topology(&self) -> &ProjectorTopologyId {
+        &self.topology
+    }
+
+    pub(crate) fn codec(&self) -> Arc<ProjectionScopeCodec> {
+        Arc::clone(&self.codec)
+    }
+
+    pub(crate) fn ownership(&self) -> &[ProjectionModelOwnership] {
+        &self.ownership
+    }
+
+    pub(crate) fn partition(&self) -> &ProjectionPartitionSpec {
+        &self.partition
+    }
+}
+
+/// Compile the exact protocol identity and model/table ownership for a
+/// projector declaration.
+///
+/// The digest includes the accepted fact inventory (empty for a direct-only
+/// owner), a fixed version of the canonical partition/key codec, and each
+/// complete registered table schema. It therefore changes whenever a model's
+/// physical table, field/column mapping, primary-key scope, or other schema
+/// contract changes. Callers may supply schemas in any order; the compiler
+/// sorts facts and models and rejects duplicates.
+pub(crate) fn compile_projection_topology<'a>(
+    name: &str,
+    facts: &[String],
+    declared_models: &[String],
+    partition: &ProjectionPartitionSpec,
+    schemas: impl IntoIterator<Item = &'a TableSchema>,
+) -> Result<(ProjectorTopologyId, Vec<ProjectionModelOwnership>), ProjectionProtocolError> {
+    partition.validate()?;
+    let mut facts = facts.to_vec();
+    facts.sort();
+    if facts.iter().any(|fact| fact.trim().is_empty()) {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "projector `{name}` contains an empty accepted fact"
+        )));
+    }
+    if facts.windows(2).any(|pair| pair[0] == pair[1]) {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "projector `{name}` repeats an accepted fact"
+        )));
+    }
+
+    if declared_models.is_empty() {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "projector `{name}` must declare at least one output model"
+        )));
+    }
+    let mut declared_models = declared_models.to_vec();
+    declared_models.sort();
+    if declared_models.iter().any(|model| model.trim().is_empty()) {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "projector `{name}` contains an empty output model"
+        )));
+    }
+    if declared_models.windows(2).any(|pair| pair[0] == pair[1]) {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "projector `{name}` repeats an output model"
+        )));
+    }
+
+    let mut schemas_by_model = BTreeMap::new();
+    for schema in schemas {
+        schema.validate()?;
+        if !schema.kind.is_read_model() {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projector `{name}` model `{}` is not a read model",
+                schema.model_name
+            )));
+        }
+        if schemas_by_model
+            .insert(schema.model_name.clone(), schema)
+            .is_some()
+        {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projector `{name}` repeats schema `{}`",
+                schema.model_name
+            )));
+        }
+    }
+    let registered_models = schemas_by_model.keys().cloned().collect::<Vec<_>>();
+    if registered_models != declared_models {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "projector `{name}` declared models {:?} but registered typed schemas {:?}",
+            declared_models, registered_models
+        )));
+    }
+
+    let mut ownership = Vec::with_capacity(schemas_by_model.len());
+    let mut compiled_models = Vec::with_capacity(schemas_by_model.len());
+    let mut physical_tables = BTreeSet::new();
+    for (model, schema) in schemas_by_model {
+        if !physical_tables.insert(schema.table_name.as_str()) {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projector `{name}` assigns more than one model to physical table `{}`",
+                schema.table_name
+            )));
+        }
+        ownership.push(ProjectionModelOwnership::new(
+            model.clone(),
+            schema.table_name.clone(),
+        )?);
+        compiled_models.push(serde_json::json!({
+            "model": model,
+            "table": schema.table_name,
+            "schema": schema,
+        }));
+    }
+
+    let canonical = serde_json::json!({
+        "topology_version": COMPILED_TOPOLOGY_VERSION,
+        "scope_codec_version": SCOPE_CODEC_VERSION,
+        "name": name,
+        "partition": partition,
+        "facts": facts,
+        "models": compiled_models,
+    });
+    let mut digest = Sha256::new();
+    digest.update(COMPILED_TOPOLOGY_DOMAIN);
+    digest.update(
+        serde_json::to_vec(&canonical)
+            .expect("compiled projection topology contains only serializable schema metadata"),
+    );
+    let topology =
+        ProjectorTopologyId::new(COMPILED_TOPOLOGY_VERSION, name, digest.finalize().into())?;
+    Ok((topology, ownership))
+}
diff --git a/src/projection_protocol/store/backend_helpers.rs b/src/projection_protocol/store/backend_helpers.rs
new file mode 100644
index 00000000..f82dd3ff
--- /dev/null
+++ b/src/projection_protocol/store/backend_helpers.rs
@@ -0,0 +1,122 @@
+use super::{
+    ProjectionChangeKind, ProjectionFailure, ProjectionFailureBatch, ProjectionMutationKind,
+    ProjectionProtocolError,
+};
+use crate::projection_protocol::MAX_PROJECTION_POSITION;
+use crate::table::TableMutation;
+
+pub(crate) fn checked_next(
+    value: u64,
+    domain: &'static str,
+) -> Result<u64, ProjectionProtocolError> {
+    if value >= MAX_PROJECTION_POSITION {
+        return Err(ProjectionProtocolError::PositionOverflow { domain });
+    }
+    Ok(value + 1)
+}
+
+pub(crate) fn table_model_name(mutation: &TableMutation) -> &str {
+    match mutation {
+        TableMutation::UpsertRow(mutation) => &mutation.schema.model_name,
+        TableMutation::PatchRow(mutation) => &mutation.schema.model_name,
+        TableMutation::DeleteRow(mutation) => &mutation.schema.model_name,
+    }
+}
+
+pub(crate) fn change_kind_for_mutation(kind: ProjectionMutationKind) -> ProjectionChangeKind {
+    match kind {
+        ProjectionMutationKind::Upsert => ProjectionChangeKind::RecordUpsert,
+        ProjectionMutationKind::Delete => ProjectionChangeKind::RecordDelete,
+        ProjectionMutationKind::Recreate => ProjectionChangeKind::RecordRecreate,
+    }
+}
+
+pub(crate) fn failure_matches_batch(
+    failure: &ProjectionFailure,
+    batch: &ProjectionFailureBatch,
+) -> bool {
+    failure.input == batch.input.cursor
+        && failure.input_fingerprint == batch.input.fingerprint
+        && failure.message_id == batch.input.message_id
+        && failure.causation_id == batch.input.causation_id
+        && failure.gap_free == batch.input.gap_free
+        && failure.generation == batch.input.generation
+        && failure.failure_code == batch.failure_code
+        && failure.failure_bytes == batch.failure_bytes
+        && failure.failure_digest == batch.failure_digest
+        && failure.change.epoch() == &batch.change_epoch
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::projection_protocol::{
+        ProjectionChangeCursor, ProjectionEpoch, ProjectionGeneration, ProjectionInputCursor,
+        ProjectionInputFingerprint, ProjectionPartition, ProjectionSource, ProjectorTopologyId,
+        TrustedProjectionInput,
+    };
+
+    fn topology() -> ProjectorTopologyId {
+        ProjectorTopologyId::new(1, "todos", [7; 32]).unwrap()
+    }
+
+    fn partition() -> ProjectionPartition {
+        ProjectionPartition::new(b"tenant:a".to_vec()).unwrap()
+    }
+
+    fn failure_batch() -> ProjectionFailureBatch {
+        let input = TrustedProjectionInput::mint(
+            ProjectionInputCursor::new(
+                topology(),
+                partition(),
+                ProjectionSource::new("todo_stream", b"todo-1".to_vec()).unwrap(),
+                ProjectionEpoch::new("source-v1").unwrap(),
+                1,
+            )
+            .unwrap(),
+            ProjectionInputFingerprint::from_canonical_bytes(b"input-1"),
+            "message-1",
+            "cause-1",
+            ProjectionGeneration::initial(),
+            true,
+        )
+        .unwrap();
+        ProjectionFailureBatch::new(
+            input,
+            ProjectionEpoch::new("changes-v1").unwrap(),
+            "failure-1",
+            "decode_error",
+            b"bad payload".to_vec(),
+        )
+        .unwrap()
+    }
+
+    #[test]
+    fn failure_matches_batch_rejects_mismatched_gap_free_identity() {
+        let batch = failure_batch();
+        let mut failure = ProjectionFailure {
+            failure_id: batch.failure_id.clone(),
+            input: batch.input.cursor.clone(),
+            input_fingerprint: batch.input.fingerprint.clone(),
+            message_id: batch.input.message_id.clone(),
+            causation_id: batch.input.causation_id.clone(),
+            generation: batch.input.generation,
+            gap_free: !batch.input.gap_free,
+            failure_code: batch.failure_code.clone(),
+            failure_bytes: batch.failure_bytes.clone(),
+            failure_digest: batch.failure_digest,
+            change: ProjectionChangeCursor::new(
+                topology(),
+                partition(),
+                batch.change_epoch.clone(),
+                1,
+            )
+            .unwrap(),
+        };
+
+        assert!(!failure_matches_batch(&failure, &batch));
+
+        failure.gap_free = batch.input.gap_free;
+        assert!(failure_matches_batch(&failure, &batch));
+    }
+}
diff --git a/src/projection_protocol/store/commit.rs b/src/projection_protocol/store/commit.rs
new file mode 100644
index 00000000..525a35f0
--- /dev/null
+++ b/src/projection_protocol/store/commit.rs
@@ -0,0 +1,306 @@
+use super::*;
+
+/// One closed asynchronous projector transaction.
+#[derive(Debug)]
+pub(crate) struct ProjectionCommitBatch {
+    pub(crate) input: TrustedProjectionInput,
+    pub(crate) change_epoch: ProjectionEpoch,
+    pub(crate) ownership: Vec<ProjectionModelOwnership>,
+    pub(crate) mutations: Vec<ProjectionRecordMutation>,
+    pub(crate) observations: Vec<ProjectionObservationRequest>,
+}
+
+impl ProjectionCommitBatch {
+    pub(crate) fn validate(&self) -> Result<(), ProjectionProtocolError> {
+        let topology = self.input.cursor.topology();
+        let partition = self.input.cursor.projection_partition();
+        self.input.inbox_receipt().validate()?;
+
+        let mut owned_models = std::collections::HashMap::new();
+        let mut owned_tables = std::collections::HashSet::new();
+        for ownership in &self.ownership {
+            if owned_models
+                .insert(ownership.model.as_str(), ownership.table.as_str())
+                .is_some()
+                || !owned_tables.insert(ownership.table.as_str())
+            {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection ownership repeats model `{}` or table `{}`",
+                    ownership.model, ownership.table
+                )));
+            }
+        }
+
+        let mut scopes = std::collections::HashSet::new();
+        for mutation in &self.mutations {
+            validate_scope(topology, partition, &mutation.scope)?;
+            let schema = match &mutation.mutation {
+                TableMutation::UpsertRow(mutation) => mutation.schema,
+                TableMutation::PatchRow(mutation) => mutation.schema,
+                TableMutation::DeleteRow(mutation) => mutation.schema,
+            };
+            if mutation.scope.model() != schema.model_name
+                || owned_models.get(mutation.scope.model()).copied()
+                    != Some(schema.table_name.as_str())
+            {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection record scope `{}` is not registered to table `{}`",
+                    mutation.scope.model(),
+                    schema.table_name
+                )));
+            }
+            if !scopes.insert(mutation.scope.clone()) {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection batch repeats model `{}` record scope",
+                    mutation.scope.model()
+                )));
+            }
+        }
+        TableWritePlan::new(
+            self.mutations
+                .iter()
+                .map(|mutation| mutation.mutation.clone())
+                .collect(),
+        )
+        .validate()?;
+
+        let mut observations = std::collections::HashSet::new();
+        for observation in &self.observations {
+            validate_scope(topology, partition, observation.scope())?;
+            if !owned_models.contains_key(observation.scope().model()) {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection observation scope `{}` is not registered",
+                    observation.scope().model()
+                )));
+            }
+            if !observations.insert((observation.kind, observation.scope().clone())) {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection batch repeats {:?} observation for model `{}`",
+                    observation.kind,
+                    observation.scope().model()
+                )));
+            }
+            match (&observation.kind, &observation.target) {
+                (
+                    ProjectionObservationKind::Record,
+                    ProjectionObservationTarget::StagedRecord(scope),
+                ) if !scopes.contains(scope) => {
+                    return Err(ProjectionProtocolError::InvalidBatch(format!(
+                        "projection observation for model `{}` references an unstaged record",
+                        scope.model()
+                    )));
+                }
+                (
+                    ProjectionObservationKind::Record,
+                    ProjectionObservationTarget::StagedRecord(_)
+                    | ProjectionObservationTarget::ExistingRecord(_),
+                )
+                | (
+                    ProjectionObservationKind::Dependency,
+                    ProjectionObservationTarget::Dependency(_),
+                ) => {}
+                _ => {
+                    return Err(ProjectionProtocolError::InvalidBatch(
+                        "projection observation kind and target disagree".into(),
+                    ));
+                }
+            }
+        }
+        Ok(())
+    }
+}
+
+/// One exact row mutation sealed out of a same-transaction command workspace.
+///
+/// Direct command projection deliberately has no caller-supplied record
+/// expectation. The adapter must inspect the authoritative record metadata
+/// while holding the registered projector partition lock: a missing row and
+/// missing metadata creates revision one, a live row advances its revision,
+/// and a tombstone or row/metadata disagreement fails closed.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct SameTransactionProjectionMutation {
+    pub(crate) scope: ProjectionRecordScope,
+    pub(crate) mutation: TableMutation,
+}
+
+/// A sealed direct projection participant in one ledger-fenced domain commit.
+///
+/// This is intentionally a different type from [`ProjectionCommitBatch`].
+/// Same-transaction projection has no source cursor, input fingerprint,
+/// consumer inbox receipt, repair generation, or async checkpoint.
+#[derive(Debug)]
+pub(crate) struct SameTransactionProjectionBatch {
+    pub(crate) topology: ProjectorTopologyId,
+    pub(crate) partition: ProjectionPartition,
+    pub(crate) change_epoch: ProjectionEpoch,
+    pub(crate) ownership: Vec<ProjectionModelOwnership>,
+    pub(crate) causation_id: String,
+    pub(crate) mutations: Vec<SameTransactionProjectionMutation>,
+    pub(crate) observations: Vec<ProjectionObservationRequest>,
+}
+
+impl SameTransactionProjectionBatch {
+    pub(crate) fn single_upsert(
+        topology: ProjectorTopologyId,
+        partition: ProjectionPartition,
+        change_epoch: ProjectionEpoch,
+        ownership: ProjectionModelOwnership,
+        scope: ProjectionRecordScope,
+        mutation: TableMutation,
+        causation_id: impl Into<String>,
+    ) -> Result<Self, ProjectionProtocolError> {
+        let observations = vec![ProjectionObservationRequest {
+            kind: ProjectionObservationKind::Record,
+            target: ProjectionObservationTarget::StagedRecord(scope.clone()),
+        }];
+        let batch = Self {
+            topology,
+            partition,
+            change_epoch,
+            ownership: vec![ownership],
+            causation_id: bounded_opaque(
+                "projection causation ID",
+                causation_id,
+                MAX_CAUSATION_ID_BYTES,
+            )?,
+            mutations: vec![SameTransactionProjectionMutation { scope, mutation }],
+            observations,
+        };
+        batch.validate()?;
+        Ok(batch)
+    }
+
+    pub(crate) fn validate(&self) -> Result<(), ProjectionProtocolError> {
+        if self.mutations.len() != 1 || self.observations.len() != 1 {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "a direct projected command must contain exactly one row upsert and one exact record observation"
+                    .into(),
+            ));
+        }
+        if self.ownership.len() != 1 {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "a direct projected command must declare exactly one output model owner".into(),
+            ));
+        }
+        bounded_opaque(
+            "projection causation ID",
+            self.causation_id.clone(),
+            MAX_CAUSATION_ID_BYTES,
+        )?;
+
+        let ownership = &self.ownership[0];
+        let staged = &self.mutations[0];
+        validate_scope(&self.topology, &self.partition, &staged.scope)?;
+        let TableMutation::UpsertRow(row) = &staged.mutation else {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "a direct projected command must seal one full-row upsert".into(),
+            ));
+        };
+        if row.mode != crate::table::RowWriteMode::Upsert
+            || row.expected_version != crate::table::ExpectedVersion::Any
+        {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "a direct projected command requires an unfenced full-row upsert; the projection protocol owns its revision fence"
+                    .into(),
+            ));
+        }
+        if staged.scope.model() != row.schema.model_name
+            || ownership.model != row.schema.model_name
+            || ownership.table != row.schema.table_name
+        {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "direct projection scope/ownership does not match model `{}` table `{}`",
+                row.schema.model_name, row.schema.table_name
+            )));
+        }
+        TableWritePlan::new(vec![staged.mutation.clone()]).validate()?;
+
+        let observation = &self.observations[0];
+        match (&observation.kind, &observation.target) {
+            (
+                ProjectionObservationKind::Record,
+                ProjectionObservationTarget::StagedRecord(scope),
+            ) if scope == &staged.scope => Ok(()),
+            _ => Err(ProjectionProtocolError::InvalidBatch(
+                "a direct projected command must observe the exact staged record scope".into(),
+            )),
+        }
+    }
+}
+
+/// Closed terminal-failure transaction for one exact input/generation.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct ProjectionFailureBatch {
+    pub(crate) input: TrustedProjectionInput,
+    pub(crate) change_epoch: ProjectionEpoch,
+    pub(crate) failure_id: String,
+    pub(crate) failure_code: String,
+    pub(crate) failure_bytes: Vec<u8>,
+    pub(crate) failure_digest: [u8; 32],
+}
+
+impl ProjectionFailureBatch {
+    /// Recompute the protocol fingerprint for persisted failure bytes.
+    ///
+    /// Storage adapters use this while decoding rows so corrupt bytes cannot
+    /// be returned with an otherwise well-formed stored digest.
+    pub(crate) fn fingerprint_bytes(failure_bytes: &[u8]) -> [u8; 32] {
+        domain_separated_digest(FAILURE_FINGERPRINT_DOMAIN, failure_bytes)
+    }
+
+    pub(crate) fn new(
+        input: TrustedProjectionInput,
+        change_epoch: ProjectionEpoch,
+        failure_id: impl Into<String>,
+        failure_code: impl Into<String>,
+        failure_bytes: impl Into<Vec<u8>>,
+    ) -> Result<Self, ProjectionProtocolError> {
+        let failure_bytes = failure_bytes.into();
+        let failure_digest = Self::fingerprint_bytes(&failure_bytes);
+        let batch = Self {
+            input,
+            change_epoch,
+            failure_id: failure_id.into(),
+            failure_code: failure_code.into(),
+            failure_bytes,
+            failure_digest,
+        };
+        batch.validate()?;
+        Ok(batch)
+    }
+
+    pub(crate) fn validate(&self) -> Result<(), ProjectionProtocolError> {
+        bounded_opaque(
+            "projection failure ID",
+            self.failure_id.clone(),
+            MAX_FAILURE_ID_BYTES,
+        )?;
+        bounded_name(
+            "projection failure code",
+            self.failure_code.clone(),
+            MAX_FAILURE_CODE_BYTES,
+        )?;
+        if self.failure_bytes.is_empty() || self.failure_bytes.len() > MAX_FAILURE_DETAIL_BYTES {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection failure details must contain 1..={MAX_FAILURE_DETAIL_BYTES} bytes"
+            )));
+        }
+        if Self::fingerprint_bytes(&self.failure_bytes) != self.failure_digest {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "projection failure digest does not match its exact bytes".into(),
+            ));
+        }
+        bounded_opaque(
+            "projection message ID",
+            self.input.message_id.clone(),
+            MAX_MESSAGE_ID_BYTES,
+        )?;
+        bounded_opaque(
+            "projection causation ID",
+            self.input.causation_id.clone(),
+            MAX_CAUSATION_ID_BYTES,
+        )?;
+        self.input.inbox_receipt().validate()?;
+        Ok(())
+    }
+}
diff --git a/src/projection_protocol/store/error.rs b/src/projection_protocol/store/error.rs
new file mode 100644
index 00000000..86fc1519
--- /dev/null
+++ b/src/projection_protocol/store/error.rs
@@ -0,0 +1,103 @@
+use super::*;
+
+#[derive(Debug)]
+#[non_exhaustive]
+pub enum ProjectionProtocolError {
+    Validation(ProjectionProtocolValidationError),
+    Repository(RepositoryError),
+    Table(TableStoreError),
+    InvalidBatch(String),
+    ScopeMismatch {
+        field: &'static str,
+    },
+    IncomparableInput,
+    InputCorruption,
+    MessageIdReuse {
+        message_id: String,
+    },
+    GenerationFenced {
+        expected: u64,
+        actual: u64,
+    },
+    PartitionStopped {
+        failure_id: String,
+    },
+    RecordMissing {
+        model: String,
+    },
+    RecordAlreadyExists {
+        model: String,
+    },
+    RecordRevisionConflict {
+        model: String,
+        expected_incarnation: u64,
+        expected_revision: u64,
+        actual_incarnation: u64,
+        actual_revision: u64,
+    },
+    RecordTombstoned {
+        model: String,
+    },
+    RecreateRequiresTombstone {
+        model: String,
+    },
+    CausalWriteRequired {
+        table: String,
+    },
+    PositionOverflow {
+        domain: &'static str,
+    },
+}
+
+impl fmt::Display for ProjectionProtocolError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Validation(error) => write!(formatter, "invalid projection protocol value: {error}"),
+            Self::Repository(error) => write!(formatter, "projection repository error: {error}"),
+            Self::Table(error) => write!(formatter, "projection table error: {error}"),
+            Self::InvalidBatch(message) => write!(formatter, "invalid projection batch: {message}"),
+            Self::ScopeMismatch { field } => write!(formatter, "{field} does not match the projection input scope"),
+            Self::IncomparableInput => formatter.write_str("projection input is incomparable with the durable checkpoint"),
+            Self::InputCorruption => formatter.write_str("the same projection input cursor was reused with different content"),
+            Self::MessageIdReuse { message_id } => write!(formatter, "projection message ID `{message_id}` was reused for a different input"),
+            Self::GenerationFenced { expected, actual } => write!(formatter, "projection generation {actual} is fenced; active generation is {expected}"),
+            Self::PartitionStopped { failure_id } => write!(formatter, "projection partition is stopped by terminal failure `{failure_id}`"),
+            Self::RecordMissing { model } => write!(formatter, "projection record `{model}` does not exist"),
+            Self::RecordAlreadyExists { model } => write!(formatter, "projection record `{model}` already exists"),
+            Self::RecordRevisionConflict { model, expected_incarnation, expected_revision, actual_incarnation, actual_revision } => write!(formatter, "projection record `{model}` expected revision ({expected_incarnation}, {expected_revision}) but found ({actual_incarnation}, {actual_revision})"),
+            Self::RecordTombstoned { model } => write!(formatter, "projection record `{model}` is tombstoned; use explicit recreate"),
+            Self::RecreateRequiresTombstone { model } => write!(formatter, "projection record `{model}` can only be recreated from its exact tombstone revision"),
+            Self::CausalWriteRequired { table } => write!(formatter, "table `{table}` is causal-owned and requires the projection commit path"),
+            Self::PositionOverflow { domain } => write!(formatter, "{domain} position overflow"),
+        }
+    }
+}
+
+impl std::error::Error for ProjectionProtocolError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Validation(error) => Some(error),
+            Self::Repository(error) => Some(error),
+            Self::Table(error) => Some(error),
+            _ => None,
+        }
+    }
+}
+
+impl From<ProjectionProtocolValidationError> for ProjectionProtocolError {
+    fn from(error: ProjectionProtocolValidationError) -> Self {
+        Self::Validation(error)
+    }
+}
+
+impl From<RepositoryError> for ProjectionProtocolError {
+    fn from(error: RepositoryError) -> Self {
+        Self::Repository(error)
+    }
+}
+
+impl From<TableStoreError> for ProjectionProtocolError {
+    fn from(error: TableStoreError) -> Self {
+        Self::Table(error)
+    }
+}
diff --git a/src/projection_protocol/store/helpers.rs b/src/projection_protocol/store/helpers.rs
new file mode 100644
index 00000000..761007a3
--- /dev/null
+++ b/src/projection_protocol/store/helpers.rs
@@ -0,0 +1,73 @@
+use super::*;
+
+pub(super) fn validate_scope(
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+    scope: &ProjectionRecordScope,
+) -> Result<(), ProjectionProtocolError> {
+    if scope.topology() != topology {
+        return Err(ProjectionProtocolError::ScopeMismatch {
+            field: "projection record topology",
+        });
+    }
+    if scope.projection_partition() != partition {
+        return Err(ProjectionProtocolError::ScopeMismatch {
+            field: "projection record partition",
+        });
+    }
+    Ok(())
+}
+
+pub(super) fn bounded_name(
+    field: &'static str,
+    value: impl Into<String>,
+    max: usize,
+) -> Result<String, ProjectionProtocolError> {
+    let value = value.into();
+    if value.is_empty()
+        || value.len() > max
+        || value
+            .chars()
+            .any(|character| character.is_control() || character.is_whitespace())
+    {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "{field} must contain 1..={max} non-whitespace, non-control UTF-8 bytes"
+        )));
+    }
+    Ok(value)
+}
+
+pub(super) fn bounded_opaque(
+    field: &'static str,
+    value: impl Into<String>,
+    max: usize,
+) -> Result<String, ProjectionProtocolError> {
+    let value = value.into();
+    if value.is_empty() || value.len() > max || value.chars().any(char::is_control) {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "{field} must contain 1..={max} non-control UTF-8 bytes"
+        )));
+    }
+    Ok(value)
+}
+
+pub(in crate::projection_protocol) fn domain_separated_digest(
+    domain: &[u8],
+    bytes: &[u8],
+) -> [u8; 32] {
+    let mut digest = Sha256::new();
+    digest.update(domain);
+    digest.update((bytes.len() as u64).to_be_bytes());
+    digest.update(bytes);
+    digest.finalize().into()
+}
+
+pub(super) fn digest_hex(bytes: &[u8; 32]) -> String {
+    const HEX: &[u8; 16] = b"0123456789abcdef";
+    let mut output = String::with_capacity(64);
+    for byte in bytes {
+        output.push(HEX[(byte >> 4) as usize] as char);
+        output.push(HEX[(byte & 0x0f) as usize] as char);
+    }
+    output
+}
diff --git a/src/projection_protocol/store/identity.rs b/src/projection_protocol/store/identity.rs
new file mode 100644
index 00000000..e428299a
--- /dev/null
+++ b/src/projection_protocol/store/identity.rs
@@ -0,0 +1,312 @@
+use super::*;
+
+pub(super) const INPUT_FINGERPRINT_DOMAIN: &[u8] = b"distributed.projection.input.v1\0";
+pub(super) const FAILURE_FINGERPRINT_DOMAIN: &[u8] = b"distributed.projection.failure.v1\0";
+pub(super) const MAX_MESSAGE_ID_BYTES: usize = 255;
+pub(super) const MAX_CAUSATION_ID_BYTES: usize = 128;
+pub(super) const MAX_FAILURE_ID_BYTES: usize = 255;
+pub(super) const MAX_FAILURE_CODE_BYTES: usize = 255;
+pub(super) const MAX_FAILURE_DETAIL_BYTES: usize = 1024 * 1024;
+pub(crate) const MAX_PROJECTION_QUERY_CHECKPOINT_PROBES: usize = 128;
+pub(crate) const MAX_PROJECTION_QUERY_BATCH_ROWS: usize = 4_096;
+pub(crate) const MAX_PROJECTION_QUERY_BATCH_CHECKPOINT_PROBES: usize = 4_096;
+pub(crate) const MAX_PROJECTION_EVIDENCE_BATCH_ITEMS: usize = 128;
+
+/// Default maximum number of durable changes retained per projector partition.
+pub const DEFAULT_MAX_RETAINED_PROJECTION_CHANGES: u64 = 4_096;
+
+/// Automatic per-partition change-log retention bound.
+///
+/// Every change-producing transaction retains at most this many newest entries
+/// and advances the durable compacted-through watermark only after the older
+/// contiguous prefix is actually removed. The watermark remains authoritative
+/// if configuration is later lengthened; compacted entries are never inferred
+/// or advertised as restored.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub struct ProjectionChangeRetention(NonZeroU64);
+
+impl ProjectionChangeRetention {
+    pub fn new(max_retained_changes: u64) -> Result<Self, ProjectionProtocolValidationError> {
+        if max_retained_changes > MAX_PROJECTION_POSITION {
+            return Err(ProjectionProtocolValidationError::TooLarge {
+                field: "projection retained change count",
+                value: max_retained_changes,
+                max: MAX_PROJECTION_POSITION,
+            });
+        }
+        NonZeroU64::new(max_retained_changes).map(Self).ok_or(
+            ProjectionProtocolValidationError::Zero {
+                field: "projection retained change count",
+            },
+        )
+    }
+
+    pub fn max_retained_changes(self) -> u64 {
+        self.0.get()
+    }
+}
+
+impl Default for ProjectionChangeRetention {
+    fn default() -> Self {
+        Self(
+            NonZeroU64::new(DEFAULT_MAX_RETAINED_PROJECTION_CHANGES)
+                .expect("the default projection change retention is nonzero"),
+        )
+    }
+}
+
+/// Explicit repair generation for one projector partition.
+///
+/// Generation one is the initial run. A terminal failure can only be retried
+/// after an operator creates a later generation linked to the failed one.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct ProjectionGeneration(NonZeroU64);
+
+impl ProjectionGeneration {
+    pub fn new(value: u64) -> Result<Self, ProjectionProtocolValidationError> {
+        if value > MAX_PROJECTION_POSITION {
+            return Err(ProjectionProtocolValidationError::TooLarge {
+                field: "projection generation",
+                value,
+                max: MAX_PROJECTION_POSITION,
+            });
+        }
+        NonZeroU64::new(value)
+            .map(Self)
+            .ok_or(ProjectionProtocolValidationError::Zero {
+                field: "projection generation",
+            })
+    }
+
+    pub fn initial() -> Self {
+        Self(NonZeroU64::MIN)
+    }
+
+    pub fn get(self) -> u64 {
+        self.0.get()
+    }
+
+    pub fn checked_next(self) -> Result<Self, ProjectionProtocolError> {
+        let next = self
+            .get()
+            .checked_add(1)
+            .ok_or(ProjectionProtocolError::PositionOverflow {
+                domain: "projection generation",
+            })?;
+        Self::new(next).map_err(|_| ProjectionProtocolError::PositionOverflow {
+            domain: "projection generation",
+        })
+    }
+}
+
+/// SHA-256 identity of the exact canonical projector input.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub struct ProjectionInputFingerprint([u8; 32]);
+
+impl ProjectionInputFingerprint {
+    /// Fingerprint bytes emitted by a registered source adapter after it has
+    /// canonicalized every semantic part of the input envelope.
+    pub fn from_canonical_bytes(bytes: &[u8]) -> Self {
+        Self(domain_separated_digest(INPUT_FINGERPRINT_DOMAIN, bytes))
+    }
+
+    pub(crate) fn from_digest(digest: [u8; 32]) -> Self {
+        Self(digest)
+    }
+
+    pub fn digest(self) -> [u8; 32] {
+        self.0
+    }
+}
+
+/// Framework-authenticated input used by the sealed asynchronous commit path.
+///
+/// Its constructor is crate-private by design. A public `Message` and its
+/// metadata cannot mint ordering evidence; only a registered transport/source
+/// adapter may do so after authenticating its cursor scope.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct TrustedProjectionInput {
+    pub(crate) cursor: ProjectionInputCursor,
+    pub(crate) fingerprint: ProjectionInputFingerprint,
+    pub(crate) message_id: String,
+    pub(crate) causation_id: String,
+    pub(crate) generation: ProjectionGeneration,
+    pub(crate) gap_free: bool,
+}
+
+impl TrustedProjectionInput {
+    pub(crate) fn mint(
+        cursor: ProjectionInputCursor,
+        fingerprint: ProjectionInputFingerprint,
+        message_id: impl Into<String>,
+        causation_id: impl Into<String>,
+        generation: ProjectionGeneration,
+        gap_free: bool,
+    ) -> Result<Self, ProjectionProtocolError> {
+        let message_id = bounded_opaque("projection message ID", message_id, MAX_MESSAGE_ID_BYTES)?;
+        let causation_id = bounded_opaque(
+            "projection causation ID",
+            causation_id,
+            MAX_CAUSATION_ID_BYTES,
+        )?;
+        Ok(Self {
+            cursor,
+            fingerprint,
+            message_id,
+            causation_id,
+            generation,
+            gap_free,
+        })
+    }
+
+    pub(crate) fn inbox_receipt(&self) -> InboxReceipt {
+        InboxReceipt::new(self.consumer_name(), self.message_id.clone())
+    }
+
+    pub(super) fn consumer_name(&self) -> String {
+        format!(
+            "projection:v1:{}:{}:{}",
+            digest_hex(&self.cursor.topology().digest()),
+            digest_hex(&self.cursor.projection_partition().digest()),
+            self.generation.get(),
+        )
+    }
+}
+
+/// Read-only disposition of one exact framework-authenticated input.
+///
+/// Projector runtimes use this before typed decoding and handler invocation so
+/// fan-out redelivery of an already committed sibling cannot rerun application
+/// projection logic. `Pending` is only returned after exact immutable identity,
+/// active generation, stop, source-capability, and repair fences pass.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) enum ProjectionInputDisposition {
+    Pending,
+    Duplicate(ProjectionCheckpoint),
+    Stale(ProjectionCheckpoint),
+}
+
+/// Fail-closed ownership registration for one projection model/table.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct ProjectionModelOwnership {
+    pub(crate) model: String,
+    pub(crate) table: String,
+}
+
+impl ProjectionModelOwnership {
+    pub(crate) fn new(
+        model: impl Into<String>,
+        table: impl Into<String>,
+    ) -> Result<Self, ProjectionProtocolError> {
+        Ok(Self {
+            model: bounded_name("projection model", model, 255)?,
+            table: bounded_name("projection table", table, 255)?,
+        })
+    }
+}
+
+/// Record state required before a staged mutation may apply.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) enum ProjectionRecordExpectation {
+    Missing,
+    Exact(RecordRevision),
+}
+
+/// Protocol meaning of a staged table mutation.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum ProjectionMutationKind {
+    Upsert,
+    Delete,
+    Recreate,
+}
+
+/// One scope-checked record mutation in a sealed projection batch.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct ProjectionRecordMutation {
+    pub(crate) scope: ProjectionRecordScope,
+    pub(crate) mutation: TableMutation,
+    pub(crate) expectation: ProjectionRecordExpectation,
+    pub(crate) kind: ProjectionMutationKind,
+}
+
+impl ProjectionRecordMutation {
+    pub(crate) fn new(
+        scope: ProjectionRecordScope,
+        mutation: TableMutation,
+        expectation: ProjectionRecordExpectation,
+        kind: ProjectionMutationKind,
+    ) -> Result<Self, ProjectionProtocolError> {
+        if let ProjectionRecordExpectation::Exact(revision) = &expectation {
+            if revision.scope() != &scope {
+                return Err(ProjectionProtocolError::ScopeMismatch {
+                    field: "projection record expectation",
+                });
+            }
+        }
+        let is_delete = matches!(mutation, TableMutation::DeleteRow(_));
+        if is_delete != matches!(kind, ProjectionMutationKind::Delete) {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "projection delete kind and table mutation disagree".into(),
+            ));
+        }
+        if matches!(
+            kind,
+            ProjectionMutationKind::Delete | ProjectionMutationKind::Recreate
+        ) && !matches!(expectation, ProjectionRecordExpectation::Exact(_))
+        {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "projection delete/recreate requires an exact record revision".into(),
+            ));
+        }
+        Ok(Self {
+            scope,
+            mutation,
+            expectation,
+            kind,
+        })
+    }
+}
+
+/// Whether an observation confirms a concrete row or a dependency scope.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum ProjectionObservationKind {
+    Record,
+    Dependency,
+}
+
+impl ProjectionObservationKind {
+    pub(crate) fn as_storage_str(self) -> &'static str {
+        match self {
+            Self::Record => "record",
+            Self::Dependency => "dependency",
+        }
+    }
+}
+
+/// Revision fence for one causation observation.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) enum ProjectionObservationTarget {
+    /// Observe the revision allocated to a mutation of this scope in the batch.
+    StagedRecord(ProjectionRecordScope),
+    /// Observe an already persisted exact revision without mutating the row.
+    ExistingRecord(RecordRevision),
+    /// Observe an embedded/dependency scope that has no independent row or
+    /// record revision. Clients revalidate its owning dependency when seen.
+    Dependency(ProjectionRecordScope),
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct ProjectionObservationRequest {
+    pub(crate) kind: ProjectionObservationKind,
+    pub(crate) target: ProjectionObservationTarget,
+}
+
+impl ProjectionObservationRequest {
+    pub(crate) fn scope(&self) -> &ProjectionRecordScope {
+        match &self.target {
+            ProjectionObservationTarget::StagedRecord(scope)
+            | ProjectionObservationTarget::Dependency(scope) => scope,
+            ProjectionObservationTarget::ExistingRecord(revision) => revision.scope(),
+        }
+    }
+}
diff --git a/src/projection_protocol/store/kind_codec.rs b/src/projection_protocol/store/kind_codec.rs
new file mode 100644
index 00000000..e364268f
--- /dev/null
+++ b/src/projection_protocol/store/kind_codec.rs
@@ -0,0 +1,25 @@
+use super::{ProjectionChangeKind, ProjectionObservationKind};
+
+impl ProjectionChangeKind {
+    pub(crate) fn from_storage_str(value: &str) -> Option<Self> {
+        match value {
+            "checkpoint" => Some(Self::Checkpoint),
+            "record_upsert" => Some(Self::RecordUpsert),
+            "record_delete" => Some(Self::RecordDelete),
+            "record_recreate" => Some(Self::RecordRecreate),
+            "observation" => Some(Self::Observation),
+            "failure" => Some(Self::Failure),
+            _ => None,
+        }
+    }
+}
+
+impl ProjectionObservationKind {
+    pub(crate) fn from_storage_str(value: &str) -> Option<Self> {
+        match value {
+            "record" => Some(Self::Record),
+            "dependency" => Some(Self::Dependency),
+            _ => None,
+        }
+    }
+}
diff --git a/src/projection_protocol/store/mod.rs b/src/projection_protocol/store/mod.rs
new file mode 100644
index 00000000..dab819b0
--- /dev/null
+++ b/src/projection_protocol/store/mod.rs
@@ -0,0 +1,95 @@
+//! Sealed projection commit vocabulary shared by repository adapters.
+//!
+//! Application projectors never construct these batches directly. A
+//! framework-owned workspace validates scopes and stages row mutations, then
+//! hands one closed batch to a repository. This keeps row data, dedupe,
+//! revisions, observations, checkpoints, and change publication inside one
+//! adapter transaction.
+
+// The store trait + query vocabulary is wider than the production call graph:
+// adapters implement the full surface, and many paths are only exercised by
+// adapter tests today. Keep the contract complete without drowning default
+// builds in dead_code noise.
+#![allow(dead_code)]
+
+use std::fmt;
+use std::future::Future;
+use std::num::NonZeroU64;
+use std::sync::Arc;
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+use super::{
+    ProjectionChangeCursor, ProjectionCheckpoint, ProjectionCommitOutcome, ProjectionEpoch,
+    ProjectionInputCursor, ProjectionPartition, ProjectionProtocolValidationError,
+    ProjectionRecordScope, ProjectionScopeCodec, ProjectionSource, ProjectorTopologyId,
+    RecordRevision, MAX_PROJECTION_PARTITION_BYTES, MAX_PROJECTION_POSITION,
+    MAX_PROJECTION_RECORD_KEY_BYTES,
+};
+use crate::repository::{InboxReceipt, RepositoryError};
+use crate::table::{
+    RowKey, RowValues, TableMutation, TableSchema, TableStoreError, TableWritePlan,
+};
+
+mod backend_helpers;
+mod commit;
+mod error;
+mod helpers;
+mod identity;
+mod kind_codec;
+mod ownership;
+mod query;
+mod replay;
+mod r#trait;
+
+#[cfg(test)]
+pub(crate) mod scenario_tests;
+#[cfg(test)]
+mod tests;
+
+use helpers::{bounded_name, bounded_opaque, digest_hex, validate_scope};
+use identity::{
+    FAILURE_FINGERPRINT_DOMAIN, MAX_CAUSATION_ID_BYTES, MAX_FAILURE_CODE_BYTES,
+    MAX_FAILURE_DETAIL_BYTES, MAX_FAILURE_ID_BYTES, MAX_MESSAGE_ID_BYTES,
+};
+
+pub(crate) use backend_helpers::{
+    change_kind_for_mutation, checked_next, failure_matches_batch, table_model_name,
+};
+pub(crate) use commit::{
+    ProjectionCommitBatch, ProjectionFailureBatch, SameTransactionProjectionBatch,
+};
+pub use error::ProjectionProtocolError;
+pub(super) use helpers::domain_separated_digest;
+pub use identity::{
+    ProjectionChangeRetention, ProjectionGeneration, ProjectionInputFingerprint,
+    ProjectionObservationKind, DEFAULT_MAX_RETAINED_PROJECTION_CHANGES,
+};
+pub(crate) use identity::{
+    ProjectionInputDisposition, ProjectionModelOwnership, ProjectionMutationKind,
+    ProjectionObservationRequest, ProjectionObservationTarget, ProjectionRecordExpectation,
+    ProjectionRecordMutation, TrustedProjectionInput, MAX_PROJECTION_EVIDENCE_BATCH_ITEMS,
+    MAX_PROJECTION_QUERY_BATCH_CHECKPOINT_PROBES, MAX_PROJECTION_QUERY_BATCH_ROWS,
+    MAX_PROJECTION_QUERY_CHECKPOINT_PROBES,
+};
+pub(crate) use ownership::validate_ownership_batch;
+pub use query::{
+    ProjectionChange, ProjectionChangeKind, ProjectionCommitResult, ProjectionFailure,
+    ProjectionObservation, ProjectionRecordMetadata,
+};
+// Several of these are only constructed from adapter unit tests; re-export for the
+// store surface and silence unused_imports on non-test lib builds.
+#[cfg_attr(not(test), allow(unused_imports))]
+pub(crate) use query::{
+    ProjectionCheckpointProbe, ProjectionCheckpointSnapshot, ProjectionFailureLocation,
+    ProjectionLiveRecordBatch, ProjectionLiveRecordBatchRequest, ProjectionLiveRecordRequest,
+    ProjectionObligationEvidence, ProjectionObligationEvidenceBatch,
+    ProjectionObligationEvidenceBatchRequest, ProjectionObligationEvidenceRequest,
+    ProjectionPartitionRuntimeState, ProjectionPartitionSnapshot, ProjectionPendingRetry,
+    ProjectionQuerySnapshot, ProjectionQuerySnapshotBatch, ProjectionQuerySnapshotBatchRequest,
+    ProjectionQuerySnapshotRequest,
+};
+pub use r#trait::ProjectionChangeRead;
+pub(crate) use r#trait::ProjectionProtocolStore;
+pub(crate) use replay::SameTransactionProjectionEvidence;
diff --git a/src/projection_protocol/store/ownership.rs b/src/projection_protocol/store/ownership.rs
new file mode 100644
index 00000000..26e8daeb
--- /dev/null
+++ b/src/projection_protocol/store/ownership.rs
@@ -0,0 +1,33 @@
+use std::collections::HashMap;
+
+use super::{ProjectionModelOwnership, ProjectionProtocolError};
+
+pub(crate) fn validate_ownership_batch(
+    ownership: &[ProjectionModelOwnership],
+) -> Result<(), ProjectionProtocolError> {
+    let mut models = HashMap::new();
+    let mut tables = HashMap::new();
+    for declaration in ownership {
+        if let Some(previous) =
+            models.insert(declaration.model.as_str(), declaration.table.as_str())
+        {
+            if previous != declaration.table {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection model `{}` declares both table `{previous}` and `{}`",
+                    declaration.model, declaration.table
+                )));
+            }
+        }
+        if let Some(previous) =
+            tables.insert(declaration.table.as_str(), declaration.model.as_str())
+        {
+            if previous != declaration.model {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection table `{}` is declared by both model `{previous}` and `{}`",
+                    declaration.table, declaration.model
+                )));
+            }
+        }
+    }
+    Ok(())
+}
diff --git a/src/projection_protocol/store/query.rs b/src/projection_protocol/store/query.rs
new file mode 100644
index 00000000..ea205c40
--- /dev/null
+++ b/src/projection_protocol/store/query.rs
@@ -0,0 +1,542 @@
+use super::*;
+
+/// Durable record metadata returned by projection stores and query snapshots.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ProjectionRecordMetadata {
+    pub revision: RecordRevision,
+    pub tombstone: bool,
+    pub change: ProjectionChangeCursor,
+}
+
+/// One exact input-source checkpoint requested alongside a physical query row.
+///
+/// The topology and partition are retained in every probe so a caller cannot
+/// accidentally combine source progress from another projector scope. The
+/// enclosing snapshot request validates those values before any adapter read.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub(crate) struct ProjectionCheckpointProbe {
+    pub(crate) topology: ProjectorTopologyId,
+    pub(crate) partition: ProjectionPartition,
+    pub(crate) source: ProjectionSource,
+    pub(crate) epoch: ProjectionEpoch,
+    pub(crate) generation: ProjectionGeneration,
+}
+
+impl ProjectionCheckpointProbe {
+    pub(crate) fn new(
+        topology: ProjectorTopologyId,
+        partition: ProjectionPartition,
+        source: ProjectionSource,
+        epoch: ProjectionEpoch,
+        generation: ProjectionGeneration,
+    ) -> Self {
+        Self {
+            topology,
+            partition,
+            source,
+            epoch,
+            generation,
+        }
+    }
+}
+
+/// Sealed adapter-neutral request for one causally versioned physical row.
+///
+/// Construction derives `scope` from the topology's registered key codec.
+/// Consequently the SQL/in-memory row key and projection metadata key cannot be
+/// supplied independently. Task 16 can add its wire envelope around this
+/// internal primitive without gaining authority to forge causal evidence.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct ProjectionQuerySnapshotRequest {
+    pub(crate) schema: Arc<TableSchema>,
+    pub(crate) key: RowKey,
+    pub(crate) scope: ProjectionRecordScope,
+    pub(crate) checkpoint_probes: Vec<ProjectionCheckpointProbe>,
+}
+
+impl ProjectionQuerySnapshotRequest {
+    pub(crate) fn new(
+        codec: &ProjectionScopeCodec,
+        partition: Option<&serde_json::Value>,
+        model: &str,
+        key: RowKey,
+        checkpoint_probes: Vec<ProjectionCheckpointProbe>,
+    ) -> Result<Self, ProjectionProtocolError> {
+        let schema = codec.registered_schema_owned(model).map_err(|error| {
+            ProjectionProtocolError::InvalidBatch(format!(
+                "invalid projection query snapshot model: {error}"
+            ))
+        })?;
+        let partition = codec.encode_partition(partition).map_err(|error| {
+            ProjectionProtocolError::InvalidBatch(format!(
+                "invalid projection query snapshot partition: {error}"
+            ))
+        })?;
+        let scope = codec
+            .encode_row_scope_in_partition(model, partition, &key)
+            .map_err(|error| {
+                ProjectionProtocolError::InvalidBatch(format!(
+                    "invalid projection query snapshot key: {error}"
+                ))
+            })?;
+        let request = Self {
+            schema,
+            key,
+            scope,
+            checkpoint_probes,
+        };
+        request.validate()?;
+        Ok(request)
+    }
+
+    pub(crate) fn validate(&self) -> Result<(), ProjectionProtocolError> {
+        if self.checkpoint_probes.len() > MAX_PROJECTION_QUERY_CHECKPOINT_PROBES {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection query snapshot has {} checkpoint probes; maximum is {}",
+                self.checkpoint_probes.len(),
+                MAX_PROJECTION_QUERY_CHECKPOINT_PROBES
+            )));
+        }
+        if self.scope.model() != self.schema.model_name {
+            return Err(ProjectionProtocolError::ScopeMismatch {
+                field: "projection query model",
+            });
+        }
+        crate::table::validate_key(&self.schema, &self.key)?;
+
+        let mut probes = std::collections::HashSet::new();
+        for probe in &self.checkpoint_probes {
+            if &probe.topology != self.scope.topology() {
+                return Err(ProjectionProtocolError::ScopeMismatch {
+                    field: "projection query checkpoint topology",
+                });
+            }
+            if &probe.partition != self.scope.projection_partition() {
+                return Err(ProjectionProtocolError::ScopeMismatch {
+                    field: "projection query checkpoint partition",
+                });
+            }
+            if !probes.insert((probe.source.clone(), probe.generation)) {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "projection query snapshot repeats one source/generation checkpoint probe"
+                        .into(),
+                ));
+            }
+        }
+        Ok(())
+    }
+}
+
+/// Result for one explicit checkpoint probe in a query snapshot.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct ProjectionCheckpointSnapshot {
+    pub(crate) probe: ProjectionCheckpointProbe,
+    pub(crate) checkpoint: Option<ProjectionCheckpoint>,
+}
+
+/// Physical row and every causal fence needed to consume it safely.
+///
+/// All fields come from one adapter snapshot. In particular, `change_head` is
+/// the live-resume boundary for this partition and must never be fetched after
+/// the row/revision in a second independent read.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct ProjectionQuerySnapshot {
+    pub(crate) row: Option<RowValues>,
+    pub(crate) record: Option<ProjectionRecordMetadata>,
+    pub(crate) checkpoints: Vec<ProjectionCheckpointSnapshot>,
+    pub(crate) change_head: Option<ProjectionChangeCursor>,
+    pub(crate) compacted_through: u64,
+}
+
+/// Sanitized live boundary for one exact projector partition, read inside the
+/// same adapter snapshot as a GraphQL query when used by Task 16.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct ProjectionPartitionSnapshot {
+    pub(crate) head: Option<ProjectionChangeCursor>,
+    pub(crate) compacted_through: u64,
+}
+
+/// A bounded set of row/evidence probes that must share one adapter snapshot.
+///
+/// This is the adapter-neutral convenience for known keys. Dynamic GraphQL
+/// list/relationship plans use the SQL repeatable-snapshot session so their
+/// physical membership query runs before these probes on the same connection.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct ProjectionQuerySnapshotBatchRequest {
+    pub(crate) requests: Vec<ProjectionQuerySnapshotRequest>,
+}
+
+impl ProjectionQuerySnapshotBatchRequest {
+    pub(crate) fn new(
+        requests: Vec<ProjectionQuerySnapshotRequest>,
+    ) -> Result<Self, ProjectionProtocolError> {
+        let request = Self { requests };
+        request.validate()?;
+        Ok(request)
+    }
+
+    pub(crate) fn validate(&self) -> Result<(), ProjectionProtocolError> {
+        if self.requests.len() > MAX_PROJECTION_QUERY_BATCH_ROWS {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection query snapshot batch has {} rows; maximum is {}",
+                self.requests.len(),
+                MAX_PROJECTION_QUERY_BATCH_ROWS
+            )));
+        }
+        let checkpoint_probes = self.requests.iter().try_fold(0usize, |total, request| {
+            total
+                .checked_add(request.checkpoint_probes.len())
+                .ok_or_else(|| {
+                    ProjectionProtocolError::InvalidBatch(
+                        "projection query snapshot batch checkpoint-probe count overflowed".into(),
+                    )
+                })
+        })?;
+        if checkpoint_probes > MAX_PROJECTION_QUERY_BATCH_CHECKPOINT_PROBES {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection query snapshot batch has {checkpoint_probes} aggregate checkpoint probes; maximum is {}",
+                MAX_PROJECTION_QUERY_BATCH_CHECKPOINT_PROBES
+            )));
+        }
+        for request in &self.requests {
+            request.validate()?;
+        }
+        Ok(())
+    }
+}
+
+#[derive(Clone, Debug, Default, PartialEq)]
+pub(crate) struct ProjectionQuerySnapshotBatch {
+    pub(crate) snapshots: Vec<ProjectionQuerySnapshot>,
+}
+
+/// One exact command obligation evidence probe.
+///
+/// The scope is already compiler-bound and canonical. A store must compare all
+/// of topology, partition, causation, model, observation kind, key bytes, and
+/// key digest; a digest lookup alone is never evidence.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub(crate) struct ProjectionObligationEvidenceRequest {
+    pub(crate) causation_id: String,
+    pub(crate) scope: ProjectionRecordScope,
+    pub(crate) kind: ProjectionObservationKind,
+}
+
+impl ProjectionObligationEvidenceRequest {
+    pub(crate) fn new(
+        causation_id: impl Into<String>,
+        scope: ProjectionRecordScope,
+        kind: ProjectionObservationKind,
+    ) -> Result<Self, ProjectionProtocolError> {
+        let request = Self {
+            causation_id: bounded_opaque(
+                "projection causation ID",
+                causation_id,
+                MAX_CAUSATION_ID_BYTES,
+            )?,
+            scope,
+            kind,
+        };
+        request.validate()?;
+        Ok(request)
+    }
+
+    pub(crate) fn validate(&self) -> Result<(), ProjectionProtocolError> {
+        bounded_opaque(
+            "projection causation ID",
+            self.causation_id.clone(),
+            MAX_CAUSATION_ID_BYTES,
+        )?;
+        Ok(())
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) enum ProjectionObligationEvidence {
+    Pending,
+    Observed(ProjectionObservation),
+    TerminalFailure(ProjectionFailure),
+}
+
+/// Bounded obligation probes evaluated from one adapter snapshot.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct ProjectionObligationEvidenceBatchRequest {
+    pub(crate) requests: Vec<ProjectionObligationEvidenceRequest>,
+}
+
+impl ProjectionObligationEvidenceBatchRequest {
+    pub(crate) fn new(
+        requests: Vec<ProjectionObligationEvidenceRequest>,
+    ) -> Result<Self, ProjectionProtocolError> {
+        let request = Self { requests };
+        request.validate()?;
+        Ok(request)
+    }
+
+    pub(crate) fn validate(&self) -> Result<(), ProjectionProtocolError> {
+        if self.requests.len() > MAX_PROJECTION_EVIDENCE_BATCH_ITEMS {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection obligation evidence batch has {} probes; maximum is {}",
+                self.requests.len(),
+                MAX_PROJECTION_EVIDENCE_BATCH_ITEMS
+            )));
+        }
+        let mut exact = std::collections::HashSet::new();
+        for request in &self.requests {
+            request.validate()?;
+            if !exact.insert((request.causation_id.as_str(), &request.scope, request.kind)) {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "projection obligation evidence batch repeats an exact probe".into(),
+                ));
+            }
+        }
+        Ok(())
+    }
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub(crate) struct ProjectionObligationEvidenceBatch {
+    pub(crate) evidence: Vec<ProjectionObligationEvidence>,
+}
+
+/// A typed physical-row key whose causal partition is deliberately unknown.
+///
+/// The registered codec supplies the topology, schema, and canonical key. The
+/// store may only return a live record after recovering its exact partition
+/// from durable metadata and proving that identity is unique.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct ProjectionLiveRecordRequest {
+    pub(crate) schema: Arc<TableSchema>,
+    pub(crate) topology: ProjectorTopologyId,
+    pub(crate) key: RowKey,
+    pub(crate) canonical_key_bytes: Vec<u8>,
+    pub(crate) canonical_key_hash: [u8; 32],
+}
+
+impl ProjectionLiveRecordRequest {
+    pub(crate) fn new(
+        codec: &ProjectionScopeCodec,
+        model: &str,
+        key: RowKey,
+    ) -> Result<Self, ProjectionProtocolError> {
+        let schema = codec.registered_schema_owned(model).map_err(|error| {
+            ProjectionProtocolError::InvalidBatch(format!(
+                "invalid projection live-record model: {error}"
+            ))
+        })?;
+        crate::table::validate_key(&schema, &key)?;
+        let canonical_key_bytes =
+            codec
+                .encode_unpartitioned_row_key(model, &key)
+                .map_err(|error| {
+                    ProjectionProtocolError::InvalidBatch(format!(
+                        "invalid projection live-record key: {error}"
+                    ))
+                })?;
+        let canonical_key_hash = ProjectionRecordScope::key_digest_for(&canonical_key_bytes);
+        Ok(Self {
+            schema,
+            topology: codec.topology().clone(),
+            key,
+            canonical_key_bytes,
+            canonical_key_hash,
+        })
+    }
+
+    pub(crate) fn model(&self) -> &str {
+        &self.schema.model_name
+    }
+
+    pub(crate) fn validate(&self) -> Result<(), ProjectionProtocolError> {
+        crate::table::validate_key(&self.schema, &self.key)?;
+        if self.canonical_key_bytes.is_empty()
+            || self.canonical_key_bytes.len() > super::MAX_PROJECTION_RECORD_KEY_BYTES
+        {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "projection live-record canonical key is empty or oversized".into(),
+            ));
+        }
+        if ProjectionRecordScope::key_digest_for(&self.canonical_key_bytes)
+            != self.canonical_key_hash
+        {
+            return Err(ProjectionProtocolError::InvalidBatch(
+                "projection live-record canonical key bytes and digest disagree".into(),
+            ));
+        }
+        Ok(())
+    }
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct ProjectionLiveRecordBatchRequest {
+    pub(crate) requests: Vec<ProjectionLiveRecordRequest>,
+}
+
+impl ProjectionLiveRecordBatchRequest {
+    pub(crate) fn new(
+        requests: Vec<ProjectionLiveRecordRequest>,
+    ) -> Result<Self, ProjectionProtocolError> {
+        let request = Self { requests };
+        request.validate()?;
+        Ok(request)
+    }
+
+    pub(crate) fn validate(&self) -> Result<(), ProjectionProtocolError> {
+        if self.requests.len() > MAX_PROJECTION_EVIDENCE_BATCH_ITEMS {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection live-record batch has {} rows; maximum is {}",
+                self.requests.len(),
+                MAX_PROJECTION_EVIDENCE_BATCH_ITEMS
+            )));
+        }
+        let mut identities = std::collections::HashSet::new();
+        for request in &self.requests {
+            request.validate()?;
+            if !identities.insert((
+                &request.topology,
+                request.model(),
+                request.canonical_key_hash,
+            )) {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "projection live-record batch repeats a topology/model/key identity".into(),
+                ));
+            }
+        }
+        Ok(())
+    }
+}
+
+/// Results are aligned positionally with the validated request batch.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub(crate) struct ProjectionLiveRecordBatch {
+    pub(crate) records: Vec<Option<ProjectionRecordMetadata>>,
+}
+
+/// Exact immutable identity that a repaired partition must retry first.
+///
+/// `failed_generation` identifies the generation that stopped. The enclosing
+/// runtime state carries the newly active generation under which this exact
+/// input must be retried.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct ProjectionPendingRetry {
+    pub(crate) failure_id: String,
+    pub(crate) input: ProjectionInputCursor,
+    pub(crate) input_fingerprint: ProjectionInputFingerprint,
+    pub(crate) message_id: String,
+    pub(crate) causation_id: String,
+    pub(crate) failed_generation: ProjectionGeneration,
+    pub(crate) gap_free: bool,
+}
+
+/// Runtime-visible fences for one exact projector partition.
+///
+/// A missing value means the partition has never been bootstrapped.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct ProjectionPartitionRuntimeState {
+    pub(crate) active_generation: ProjectionGeneration,
+    pub(crate) stopped_failure_id: Option<String>,
+    pub(crate) pending_retry: Option<ProjectionPendingRetry>,
+}
+
+/// Exact durable observation of one command causation.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ProjectionObservation {
+    pub causation_id: String,
+    pub kind: ProjectionObservationKind,
+    /// Present for record observations; absent for embedded/dependency scopes.
+    pub revision: Option<RecordRevision>,
+    /// Canonical dependency scope when no record revision exists.
+    pub scope: ProjectionRecordScope,
+    pub change: ProjectionChangeCursor,
+}
+
+/// Durable terminal failure for one exact input and repair generation.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ProjectionFailure {
+    pub failure_id: String,
+    pub input: ProjectionInputCursor,
+    pub input_fingerprint: ProjectionInputFingerprint,
+    pub message_id: String,
+    pub causation_id: String,
+    pub generation: ProjectionGeneration,
+    /// Whether the failed input source promised gap-free ordered delivery.
+    pub gap_free: bool,
+    pub failure_code: String,
+    pub failure_bytes: Vec<u8>,
+    pub failure_digest: [u8; 32],
+    pub change: ProjectionChangeCursor,
+}
+
+/// Adapter-resolved exact scope for one globally unique projection failure ID.
+///
+/// This is crate-private so an operator supplies only the opaque failure handle;
+/// the durable store, not the caller, reconstructs canonical topology and
+/// partition authority.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct ProjectionFailureLocation {
+    pub(crate) topology: ProjectorTopologyId,
+    pub(crate) partition: ProjectionPartition,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum ProjectionChangeKind {
+    /// A successful input with no row/observation change. This makes the exact
+    /// checkpoint resumable without pretending an old change head was newly
+    /// allocated and allows gap-free barriers to advance.
+    Checkpoint,
+    RecordUpsert,
+    RecordDelete,
+    RecordRecreate,
+    Observation,
+    Failure,
+}
+
+impl ProjectionChangeKind {
+    pub(crate) fn as_storage_str(self) -> &'static str {
+        match self {
+            Self::Checkpoint => "checkpoint",
+            Self::RecordUpsert => "record_upsert",
+            Self::RecordDelete => "record_delete",
+            Self::RecordRecreate => "record_recreate",
+            Self::Observation => "observation",
+            Self::Failure => "failure",
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ProjectionChange {
+    pub cursor: ProjectionChangeCursor,
+    pub kind: ProjectionChangeKind,
+    pub causation_id: String,
+    pub observation_kind: Option<ProjectionObservationKind>,
+    /// Canonical record/dependency identity for row and observation changes.
+    /// Checkpoint-only and failure entries deliberately carry no model scope.
+    pub scope: Option<ProjectionRecordScope>,
+    pub revision: Option<RecordRevision>,
+    pub failure_id: Option<String>,
+}
+
+/// Result and exact evidence produced by an asynchronous projection commit.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ProjectionCommitResult {
+    pub outcome: ProjectionCommitOutcome,
+    pub checkpoint: Option<ProjectionCheckpoint>,
+    pub records: Vec<ProjectionRecordMetadata>,
+    pub changes: Vec<ProjectionChange>,
+}
+
+impl ProjectionCommitResult {
+    pub(crate) fn not_applied(
+        outcome: ProjectionCommitOutcome,
+        checkpoint: Option<ProjectionCheckpoint>,
+    ) -> Self {
+        debug_assert!(outcome != ProjectionCommitOutcome::Applied);
+        Self {
+            outcome,
+            checkpoint,
+            records: Vec::new(),
+            changes: Vec::new(),
+        }
+    }
+}
diff --git a/src/projection_protocol/store/replay.rs b/src/projection_protocol/store/replay.rs
new file mode 100644
index 00000000..b4064eef
--- /dev/null
+++ b/src/projection_protocol/store/replay.rs
@@ -0,0 +1,479 @@
+use super::*;
+
+/// Exact evidence allocated for a same-transaction projected command.
+///
+/// The command ledger stores the canonical replay form produced by
+/// [`replay_value`](Self::replay_value), so response-loss recovery returns the
+/// revision and change allocated by the original transaction rather than the
+/// record's later head.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct SameTransactionProjectionEvidence {
+    pub(crate) records: Vec<ProjectionRecordMetadata>,
+    pub(crate) changes: Vec<ProjectionChange>,
+    pub(crate) observations: Vec<ProjectionObservation>,
+}
+
+impl SameTransactionProjectionEvidence {
+    pub(crate) fn replay_value(&self) -> serde_json::Value {
+        serde_json::to_value(SameTransactionReplayEnvelope::from(self))
+            .expect("same-transaction projection evidence contains only serializable primitives")
+    }
+
+    pub(crate) fn from_replay_value(value: &serde_json::Value) -> Result<Self, String> {
+        let decoded: SameTransactionReplayEnvelope = serde_json::from_value(value.clone())
+            .map_err(|error| format!("direct projection evidence is invalid: {error}"))?;
+        let evidence = decoded.into_evidence()?;
+        let canonical = serde_json::to_value(SameTransactionReplayEnvelope::from(&evidence))
+            .map_err(|error| format!("direct projection evidence cannot be normalized: {error}"))?;
+        if canonical != *value {
+            return Err(
+                "direct projection evidence contains unknown or non-canonical fields".into(),
+            );
+        }
+        Ok(evidence)
+    }
+
+    pub(crate) fn validate_replay_value(value: &serde_json::Value) -> Result<(), String> {
+        Self::from_replay_value(value).map(|_| ())
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct SameTransactionReplayEnvelope {
+    version: u16,
+    records: Vec<ReplayRecord>,
+    changes: Vec<ReplayChange>,
+    observations: Vec<ReplayObservation>,
+}
+
+impl From<&SameTransactionProjectionEvidence> for SameTransactionReplayEnvelope {
+    fn from(evidence: &SameTransactionProjectionEvidence) -> Self {
+        Self {
+            version: 1,
+            records: evidence.records.iter().map(ReplayRecord::from).collect(),
+            changes: evidence.changes.iter().map(ReplayChange::from).collect(),
+            observations: evidence
+                .observations
+                .iter()
+                .map(ReplayObservation::from)
+                .collect(),
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct ReplayScope {
+    topology_version: u32,
+    topology_name: String,
+    topology_digest: String,
+    partition: String,
+    partition_digest: String,
+    model: String,
+    key: String,
+    key_digest: String,
+}
+
+impl From<&ProjectionRecordScope> for ReplayScope {
+    fn from(scope: &ProjectionRecordScope) -> Self {
+        Self {
+            topology_version: scope.topology().version(),
+            topology_name: scope.topology().name().to_string(),
+            topology_digest: digest_hex(&scope.topology().digest()),
+            partition: bytes_hex(scope.projection_partition().canonical_bytes()),
+            partition_digest: digest_hex(&scope.projection_partition().digest()),
+            model: scope.model().to_string(),
+            key: bytes_hex(scope.canonical_key_bytes()),
+            key_digest: digest_hex(&scope.key_digest()),
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct ReplayRevision {
+    scope: ReplayScope,
+    incarnation: u64,
+    revision: u64,
+}
+
+impl From<&RecordRevision> for ReplayRevision {
+    fn from(revision: &RecordRevision) -> Self {
+        Self {
+            scope: ReplayScope::from(revision.scope()),
+            incarnation: revision.incarnation(),
+            revision: revision.revision(),
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct ReplayCursor {
+    topology_version: u32,
+    topology_name: String,
+    topology_digest: String,
+    partition: String,
+    partition_digest: String,
+    epoch: String,
+    position: u64,
+}
+
+impl From<&ProjectionChangeCursor> for ReplayCursor {
+    fn from(cursor: &ProjectionChangeCursor) -> Self {
+        Self {
+            topology_version: cursor.topology().version(),
+            topology_name: cursor.topology().name().to_string(),
+            topology_digest: digest_hex(&cursor.topology().digest()),
+            partition: bytes_hex(cursor.projection_partition().canonical_bytes()),
+            partition_digest: digest_hex(&cursor.projection_partition().digest()),
+            epoch: cursor.epoch().as_str().to_string(),
+            position: cursor.position(),
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct ReplayRecord {
+    revision: ReplayRevision,
+    tombstone: bool,
+    change: ReplayCursor,
+}
+
+impl From<&ProjectionRecordMetadata> for ReplayRecord {
+    fn from(record: &ProjectionRecordMetadata) -> Self {
+        Self {
+            revision: ReplayRevision::from(&record.revision),
+            tombstone: record.tombstone,
+            change: ReplayCursor::from(&record.change),
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct ReplayChange {
+    cursor: ReplayCursor,
+    kind: String,
+    causation_id: String,
+    observation_kind: Option<String>,
+    scope: Option<ReplayScope>,
+    revision: Option<ReplayRevision>,
+    failure_id: Option<String>,
+}
+
+impl From<&ProjectionChange> for ReplayChange {
+    fn from(change: &ProjectionChange) -> Self {
+        Self {
+            cursor: ReplayCursor::from(&change.cursor),
+            kind: change.kind.as_storage_str().to_string(),
+            causation_id: change.causation_id.clone(),
+            observation_kind: change
+                .observation_kind
+                .map(|kind| kind.as_storage_str().to_string()),
+            scope: change.scope.as_ref().map(ReplayScope::from),
+            revision: change.revision.as_ref().map(ReplayRevision::from),
+            failure_id: change.failure_id.clone(),
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct ReplayObservation {
+    causation_id: String,
+    kind: String,
+    revision: Option<ReplayRevision>,
+    scope: ReplayScope,
+    change: ReplayCursor,
+}
+
+impl From<&ProjectionObservation> for ReplayObservation {
+    fn from(observation: &ProjectionObservation) -> Self {
+        Self {
+            causation_id: observation.causation_id.clone(),
+            kind: observation.kind.as_storage_str().to_string(),
+            revision: observation.revision.as_ref().map(ReplayRevision::from),
+            scope: ReplayScope::from(&observation.scope),
+            change: ReplayCursor::from(&observation.change),
+        }
+    }
+}
+
+impl SameTransactionReplayEnvelope {
+    fn into_evidence(self) -> Result<SameTransactionProjectionEvidence, String> {
+        if self.version != 1 {
+            return Err(format!(
+                "direct projection evidence version {} is unsupported",
+                self.version
+            ));
+        }
+        let evidence = SameTransactionProjectionEvidence {
+            records: self
+                .records
+                .into_iter()
+                .map(ReplayRecord::into_record)
+                .collect::<Result<_, _>>()?,
+            changes: self
+                .changes
+                .into_iter()
+                .map(ReplayChange::into_change)
+                .collect::<Result<_, _>>()?,
+            observations: self
+                .observations
+                .into_iter()
+                .map(ReplayObservation::into_observation)
+                .collect::<Result<_, _>>()?,
+        };
+        validate_same_transaction_replay_evidence(&evidence)?;
+        Ok(evidence)
+    }
+}
+
+impl ReplayScope {
+    fn into_scope(self) -> Result<ProjectionRecordScope, String> {
+        let topology = decode_replay_topology(
+            self.topology_version,
+            self.topology_name,
+            self.topology_digest,
+        )?;
+        let partition = decode_replay_partition(self.partition, self.partition_digest)?;
+        let key = decode_replay_hex("record key", &self.key, MAX_PROJECTION_RECORD_KEY_BYTES)?;
+        let scope = ProjectionRecordScope::new(topology, partition, self.model, key)
+            .map_err(|error| replay_validation_error("record scope", error))?;
+        if digest_hex(&scope.key_digest()) != self.key_digest {
+            return Err(
+                "direct projection evidence record key digest does not match its canonical bytes"
+                    .into(),
+            );
+        }
+        Ok(scope)
+    }
+}
+
+impl ReplayRevision {
+    fn into_revision(self) -> Result<RecordRevision, String> {
+        RecordRevision::new(self.scope.into_scope()?, self.incarnation, self.revision)
+            .map_err(|error| replay_validation_error("record revision", error))
+    }
+}
+
+impl ReplayCursor {
+    fn into_cursor(self) -> Result<ProjectionChangeCursor, String> {
+        ProjectionChangeCursor::new(
+            decode_replay_topology(
+                self.topology_version,
+                self.topology_name,
+                self.topology_digest,
+            )?,
+            decode_replay_partition(self.partition, self.partition_digest)?,
+            ProjectionEpoch::new(self.epoch)
+                .map_err(|error| replay_validation_error("change epoch", error))?,
+            self.position,
+        )
+        .map_err(|error| replay_validation_error("change cursor", error))
+    }
+}
+
+impl ReplayRecord {
+    fn into_record(self) -> Result<ProjectionRecordMetadata, String> {
+        Ok(ProjectionRecordMetadata {
+            revision: self.revision.into_revision()?,
+            tombstone: self.tombstone,
+            change: self.change.into_cursor()?,
+        })
+    }
+}
+
+impl ReplayChange {
+    fn into_change(self) -> Result<ProjectionChange, String> {
+        Ok(ProjectionChange {
+            cursor: self.cursor.into_cursor()?,
+            kind: decode_replay_change_kind(&self.kind)?,
+            causation_id: bounded_opaque(
+                "projection causation ID",
+                self.causation_id,
+                MAX_CAUSATION_ID_BYTES,
+            )
+            .map_err(|error| replay_validation_error("change causation", error))?,
+            observation_kind: self
+                .observation_kind
+                .as_deref()
+                .map(decode_replay_observation_kind)
+                .transpose()?,
+            scope: self.scope.map(ReplayScope::into_scope).transpose()?,
+            revision: self
+                .revision
+                .map(ReplayRevision::into_revision)
+                .transpose()?,
+            failure_id: self
+                .failure_id
+                .map(|failure_id| {
+                    bounded_opaque("projection failure ID", failure_id, MAX_FAILURE_ID_BYTES)
+                        .map_err(|error| replay_validation_error("change failure ID", error))
+                })
+                .transpose()?,
+        })
+    }
+}
+
+impl ReplayObservation {
+    fn into_observation(self) -> Result<ProjectionObservation, String> {
+        Ok(ProjectionObservation {
+            causation_id: bounded_opaque(
+                "projection causation ID",
+                self.causation_id,
+                MAX_CAUSATION_ID_BYTES,
+            )
+            .map_err(|error| replay_validation_error("observation causation", error))?,
+            kind: decode_replay_observation_kind(&self.kind)?,
+            revision: self
+                .revision
+                .map(ReplayRevision::into_revision)
+                .transpose()?,
+            scope: self.scope.into_scope()?,
+            change: self.change.into_cursor()?,
+        })
+    }
+}
+
+fn decode_replay_topology(
+    version: u32,
+    name: String,
+    digest: String,
+) -> Result<ProjectorTopologyId, String> {
+    ProjectorTopologyId::new(
+        version,
+        name,
+        decode_replay_digest("topology digest", &digest)?,
+    )
+    .map_err(|error| replay_validation_error("topology", error))
+}
+
+fn decode_replay_partition(
+    canonical: String,
+    digest: String,
+) -> Result<ProjectionPartition, String> {
+    let partition = ProjectionPartition::new(decode_replay_hex(
+        "partition",
+        &canonical,
+        MAX_PROJECTION_PARTITION_BYTES,
+    )?)
+    .map_err(|error| replay_validation_error("partition", error))?;
+    if digest_hex(&partition.digest()) != digest {
+        return Err(
+            "direct projection evidence partition digest does not match its canonical bytes".into(),
+        );
+    }
+    Ok(partition)
+}
+
+fn decode_replay_digest(field: &str, value: &str) -> Result<[u8; 32], String> {
+    decode_replay_hex(field, value, 32)?
+        .try_into()
+        .map_err(|_| format!("direct projection evidence {field} must contain exactly 32 bytes"))
+}
+
+fn decode_replay_hex(field: &str, value: &str, max_bytes: usize) -> Result<Vec<u8>, String> {
+    if value.len() % 2 != 0 || value.len() > max_bytes.saturating_mul(2) {
+        return Err(format!(
+            "direct projection evidence {field} is not bounded canonical hexadecimal"
+        ));
+    }
+    let mut decoded = Vec::with_capacity(value.len() / 2);
+    for pair in value.as_bytes().chunks_exact(2) {
+        let high = decode_replay_hex_nibble(pair[0]).ok_or_else(|| {
+            format!("direct projection evidence {field} is not lowercase hexadecimal")
+        })?;
+        let low = decode_replay_hex_nibble(pair[1]).ok_or_else(|| {
+            format!("direct projection evidence {field} is not lowercase hexadecimal")
+        })?;
+        decoded.push((high << 4) | low);
+    }
+    Ok(decoded)
+}
+
+fn decode_replay_hex_nibble(value: u8) -> Option<u8> {
+    match value {
+        b'0'..=b'9' => Some(value - b'0'),
+        b'a'..=b'f' => Some(value - b'a' + 10),
+        _ => None,
+    }
+}
+
+fn decode_replay_change_kind(value: &str) -> Result<ProjectionChangeKind, String> {
+    ProjectionChangeKind::from_storage_str(value)
+        .ok_or_else(|| format!("direct projection evidence has unknown change kind `{value}`"))
+}
+
+fn decode_replay_observation_kind(value: &str) -> Result<ProjectionObservationKind, String> {
+    ProjectionObservationKind::from_storage_str(value)
+        .ok_or_else(|| format!("direct projection evidence has unknown observation kind `{value}`"))
+}
+
+fn validate_same_transaction_replay_evidence(
+    evidence: &SameTransactionProjectionEvidence,
+) -> Result<(), String> {
+    let [record] = evidence.records.as_slice() else {
+        return Err("direct projection evidence must contain exactly one projected record".into());
+    };
+    let [change] = evidence.changes.as_slice() else {
+        return Err("direct projection evidence must contain exactly one record change".into());
+    };
+    let [observation] = evidence.observations.as_slice() else {
+        return Err(
+            "direct projection evidence must contain exactly one record observation".into(),
+        );
+    };
+    if record.tombstone {
+        return Err("direct projection evidence cannot replay a tombstone".into());
+    }
+    if change.kind != ProjectionChangeKind::RecordUpsert
+        || change.observation_kind.is_some()
+        || change.failure_id.is_some()
+    {
+        return Err("direct projection evidence change must be a plain record upsert".into());
+    }
+    if change.scope.as_ref() != Some(record.revision.scope())
+        || change.revision.as_ref() != Some(&record.revision)
+    {
+        return Err(
+            "direct projection evidence change does not match the projected record revision".into(),
+        );
+    }
+    if change.cursor.topology() != record.revision.scope().topology()
+        || change.cursor.projection_partition() != record.revision.scope().projection_partition()
+    {
+        return Err(
+            "direct projection evidence change cursor does not match its record scope".into(),
+        );
+    }
+    if record.change != change.cursor {
+        return Err("direct projection evidence record and change cursors do not match".into());
+    }
+    if observation.kind != ProjectionObservationKind::Record
+        || observation.scope != *record.revision.scope()
+        || observation.revision.as_ref() != Some(&record.revision)
+    {
+        return Err(
+            "direct projection evidence observation does not match the projected record revision"
+                .into(),
+        );
+    }
+    if observation.change != change.cursor || observation.causation_id != change.causation_id {
+        return Err(
+            "direct projection evidence observation does not match its record change".into(),
+        );
+    }
+    Ok(())
+}
+
+fn replay_validation_error(field: &str, error: impl fmt::Display) -> String {
+    format!("direct projection evidence {field} is invalid: {error}")
+}
+
+fn bytes_hex(bytes: &[u8]) -> String {
+    bytes.iter().map(|byte| format!("{byte:02x}")).collect()
+}
diff --git a/src/projection_protocol/store/scenario_tests.rs b/src/projection_protocol/store/scenario_tests.rs
new file mode 100644
index 00000000..251254c1
--- /dev/null
+++ b/src/projection_protocol/store/scenario_tests.rs
@@ -0,0 +1,452 @@
+use std::future::Future;
+
+use super::*;
+
+pub(crate) trait ProjectionProtocolScenario {
+    type Store: ProjectionProtocolStore;
+
+    fn repository(&self) -> impl Future<Output = Self::Store> + Send;
+
+    fn topology(&self) -> ProjectorTopologyId;
+
+    fn other_topology(&self) -> ProjectorTopologyId;
+
+    fn partition(&self) -> ProjectionPartition;
+
+    fn source(&self, name: &str, key: &[u8]) -> ProjectionSource {
+        ProjectionSource::new(name, key.to_vec()).unwrap()
+    }
+
+    fn input_cursor(&self, position: u64) -> ProjectionInputCursor {
+        ProjectionInputCursor::new(
+            self.topology(),
+            self.partition(),
+            self.source("todo_stream", b"todo-1"),
+            ProjectionEpoch::new("source-v1").unwrap(),
+            position,
+        )
+        .unwrap()
+    }
+
+    fn input(
+        &self,
+        position: u64,
+        fingerprint: &[u8],
+        message_id: &str,
+        causation_id: &str,
+        generation: ProjectionGeneration,
+    ) -> TrustedProjectionInput {
+        TrustedProjectionInput::mint(
+            self.input_cursor(position),
+            ProjectionInputFingerprint::from_canonical_bytes(fingerprint),
+            message_id,
+            causation_id,
+            generation,
+            true,
+        )
+        .unwrap()
+    }
+
+    fn input_for_partition(
+        &self,
+        partition: ProjectionPartition,
+        position: u64,
+        fingerprint: &[u8],
+        message_id: &str,
+        causation_id: &str,
+    ) -> TrustedProjectionInput {
+        TrustedProjectionInput::mint(
+            ProjectionInputCursor::new(
+                self.topology(),
+                partition,
+                self.source("todo_stream", b"todo-1"),
+                ProjectionEpoch::new("source-v1").unwrap(),
+                position,
+            )
+            .unwrap(),
+            ProjectionInputFingerprint::from_canonical_bytes(fingerprint),
+            message_id,
+            causation_id,
+            ProjectionGeneration::initial(),
+            true,
+        )
+        .unwrap()
+    }
+
+    fn change_epoch(&self) -> ProjectionEpoch;
+
+    fn ownership(&self) -> ProjectionModelOwnership;
+
+    fn mutation(
+        &self,
+        expectation: ProjectionRecordExpectation,
+        kind: ProjectionMutationKind,
+    ) -> ProjectionRecordMutation;
+
+    fn row_exists<'a>(
+        &'a self,
+        repository: &'a Self::Store,
+    ) -> impl Future<Output = bool> + Send + 'a;
+
+    fn batch(
+        &self,
+        input: TrustedProjectionInput,
+        mutations: Vec<ProjectionRecordMutation>,
+        observations: Vec<ProjectionObservationRequest>,
+    ) -> ProjectionCommitBatch {
+        ProjectionCommitBatch {
+            input,
+            change_epoch: self.change_epoch(),
+            ownership: vec![self.ownership()],
+            mutations,
+            observations,
+        }
+    }
+}
+
+pub(crate) async fn input_disposition_is_read_only_exact_and_repair_fenced(
+    scenario: impl ProjectionProtocolScenario,
+) {
+    let repository = scenario.repository().await;
+    let first_input = scenario.input(
+        1,
+        b"preflight-one",
+        "preflight-message-1",
+        "preflight-cause-1",
+        ProjectionGeneration::initial(),
+    );
+    assert_eq!(
+        repository
+            .projection_input_disposition(&first_input)
+            .await
+            .unwrap(),
+        ProjectionInputDisposition::Pending
+    );
+    assert_eq!(
+        repository
+            .projection_partition_runtime_state(&scenario.topology(), &scenario.partition())
+            .await
+            .unwrap(),
+        None,
+        "a preflight read must not create projection partition state"
+    );
+
+    let applied = repository
+        .commit_projection(scenario.batch(first_input.clone(), Vec::new(), Vec::new()))
+        .await
+        .unwrap();
+    assert_eq!(
+        repository
+            .projection_input_disposition(&first_input)
+            .await
+            .unwrap(),
+        ProjectionInputDisposition::Duplicate(applied.checkpoint.unwrap())
+    );
+
+    let stale = scenario.input(
+        0,
+        b"preflight-stale",
+        "preflight-message-0",
+        "preflight-cause-0",
+        ProjectionGeneration::initial(),
+    );
+    assert!(matches!(
+        repository
+            .projection_input_disposition(&stale)
+            .await
+            .unwrap(),
+        ProjectionInputDisposition::Stale(checkpoint) if checkpoint.input().position() == 1
+    ));
+
+    let corrupted = scenario.input(
+        1,
+        b"preflight-corrupt",
+        "preflight-message-1",
+        "preflight-cause-1",
+        ProjectionGeneration::initial(),
+    );
+    assert!(matches!(
+        repository.projection_input_disposition(&corrupted).await,
+        Err(ProjectionProtocolError::InputCorruption)
+    ));
+
+    let reused_message = scenario.input(
+        2,
+        b"preflight-two",
+        "preflight-message-1",
+        "preflight-cause-2",
+        ProjectionGeneration::initial(),
+    );
+    assert!(matches!(
+        repository.projection_input_disposition(&reused_message).await,
+        Err(ProjectionProtocolError::MessageIdReuse { message_id })
+            if message_id == "preflight-message-1"
+    ));
+
+    let failed_input = scenario.input(
+        2,
+        b"preflight-two",
+        "preflight-message-2",
+        "preflight-cause-2",
+        ProjectionGeneration::initial(),
+    );
+    repository
+        .record_projection_failure(
+            ProjectionFailureBatch::new(
+                failed_input.clone(),
+                scenario.change_epoch(),
+                "preflight-failure-2",
+                "decode_error",
+                b"bad payload".to_vec(),
+            )
+            .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert!(matches!(
+        repository
+            .projection_input_disposition(&failed_input)
+            .await,
+        Err(ProjectionProtocolError::PartitionStopped { failure_id })
+            if failure_id == "preflight-failure-2"
+    ));
+
+    let generation = repository
+        .repair_projection(
+            &scenario.topology(),
+            &scenario.partition(),
+            "preflight-failure-2",
+        )
+        .await
+        .unwrap();
+    let retry = scenario.input(
+        2,
+        b"preflight-two",
+        "preflight-message-2",
+        "preflight-cause-2",
+        generation,
+    );
+    assert_eq!(
+        repository
+            .projection_input_disposition(&retry)
+            .await
+            .unwrap(),
+        ProjectionInputDisposition::Pending
+    );
+    assert!(matches!(
+        repository.projection_input_disposition(&first_input).await,
+        Err(ProjectionProtocolError::GenerationFenced {
+            expected: 2,
+            actual: 1
+        })
+    ));
+    assert!(matches!(
+        repository
+            .projection_input_disposition(&scenario.input(
+                3,
+                b"preflight-later",
+                "preflight-message-3",
+                "preflight-cause-3",
+                generation,
+            ))
+            .await,
+        Err(ProjectionProtocolError::IncomparableInput)
+    ));
+
+    let repaired = repository
+        .commit_projection(scenario.batch(retry.clone(), Vec::new(), Vec::new()))
+        .await
+        .unwrap();
+    assert_eq!(
+        repository
+            .projection_input_disposition(&retry)
+            .await
+            .unwrap(),
+        ProjectionInputDisposition::Duplicate(repaired.checkpoint.unwrap())
+    );
+}
+
+pub(crate) async fn message_identity_is_topology_wide_across_projection_partitions(
+    scenario: impl ProjectionProtocolScenario,
+) {
+    let repository = scenario.repository().await;
+    repository
+        .commit_projection(scenario.batch(
+            scenario.input(
+                1,
+                b"topology-wide-message",
+                "topology-wide-message",
+                "topology-wide-cause",
+                ProjectionGeneration::initial(),
+            ),
+            Vec::new(),
+            Vec::new(),
+        ))
+        .await
+        .unwrap();
+
+    let other_partition = ProjectionScopeCodec::new(scenario.topology())
+        .encode_partition(Some(&serde_json::json!("tenant-b")))
+        .unwrap();
+    let remapped = scenario.input_for_partition(
+        other_partition,
+        1,
+        b"topology-wide-message",
+        "topology-wide-message",
+        "topology-wide-cause",
+    );
+
+    assert!(matches!(
+        repository
+            .commit_projection(scenario.batch(remapped, Vec::new(), Vec::new()))
+            .await,
+        Err(ProjectionProtocolError::MessageIdReuse { message_id })
+            if message_id == "topology-wide-message"
+    ));
+}
+
+pub(crate) async fn failure_recording_is_idempotent_for_exact_batch(
+    scenario: impl ProjectionProtocolScenario,
+) {
+    let repository = scenario.repository().await;
+    let batch = ProjectionFailureBatch::new(
+        scenario.input(
+            1,
+            b"idempotent-failure",
+            "idempotent-failure-message",
+            "idempotent-failure-cause",
+            ProjectionGeneration::initial(),
+        ),
+        scenario.change_epoch(),
+        "idempotent-failure",
+        "decode_error",
+        b"bad payload".to_vec(),
+    )
+    .unwrap();
+
+    let failure = repository
+        .record_projection_failure(batch.clone())
+        .await
+        .unwrap();
+    assert_eq!(
+        repository.record_projection_failure(batch).await.unwrap(),
+        failure
+    );
+    assert_eq!(
+        repository
+            .projection_failure(
+                &scenario.topology(),
+                &scenario.partition(),
+                "idempotent-failure",
+            )
+            .await
+            .unwrap(),
+        Some(failure)
+    );
+}
+
+pub(crate) async fn registered_table_ownership_rejects_other_topology(
+    scenario: impl ProjectionProtocolScenario,
+) {
+    let repository = scenario.repository().await;
+    assert!(matches!(
+        repository
+            .register_projection_models(&scenario.other_topology(), &[scenario.ownership()])
+            .await,
+        Err(ProjectionProtocolError::InvalidBatch(message))
+            if message.contains("authorit")
+    ));
+}
+
+pub(crate) async fn tombstone_requires_explicit_exact_recreation(
+    scenario: impl ProjectionProtocolScenario,
+) {
+    let repository = scenario.repository().await;
+    let created = repository
+        .commit_projection(scenario.batch(
+            scenario.input(
+                1,
+                b"create",
+                "message-1",
+                "cause-1",
+                ProjectionGeneration::initial(),
+            ),
+            vec![scenario.mutation(
+                ProjectionRecordExpectation::Missing,
+                ProjectionMutationKind::Upsert,
+            )],
+            Vec::new(),
+        ))
+        .await
+        .unwrap()
+        .records
+        .pop()
+        .unwrap();
+    let deleted = repository
+        .commit_projection(scenario.batch(
+            scenario.input(
+                2,
+                b"delete",
+                "message-2",
+                "cause-2",
+                ProjectionGeneration::initial(),
+            ),
+            vec![scenario.mutation(
+                ProjectionRecordExpectation::Exact(created.revision),
+                ProjectionMutationKind::Delete,
+            )],
+            Vec::new(),
+        ))
+        .await
+        .unwrap()
+        .records
+        .pop()
+        .unwrap();
+    assert!(deleted.tombstone);
+    assert!(!scenario.row_exists(&repository).await);
+
+    assert!(matches!(
+        repository
+            .commit_projection(scenario.batch(
+                scenario.input(
+                    3,
+                    b"plain-upsert",
+                    "message-3",
+                    "cause-3",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![scenario.mutation(
+                    ProjectionRecordExpectation::Exact(deleted.revision.clone()),
+                    ProjectionMutationKind::Upsert,
+                )],
+                Vec::new(),
+            ))
+            .await,
+        Err(ProjectionProtocolError::RecordTombstoned { .. })
+    ));
+
+    let recreated = repository
+        .commit_projection(scenario.batch(
+            scenario.input(
+                3,
+                b"recreate",
+                "message-3b",
+                "cause-3",
+                ProjectionGeneration::initial(),
+            ),
+            vec![scenario.mutation(
+                ProjectionRecordExpectation::Exact(deleted.revision),
+                ProjectionMutationKind::Recreate,
+            )],
+            Vec::new(),
+        ))
+        .await
+        .unwrap()
+        .records
+        .pop()
+        .unwrap();
+    assert_eq!(recreated.revision.incarnation(), 2);
+    assert_eq!(recreated.revision.revision(), 1);
+    assert!(!recreated.tombstone);
+    assert!(scenario.row_exists(&repository).await);
+}
diff --git a/src/projection_protocol/store/tests.rs b/src/projection_protocol/store/tests.rs
new file mode 100644
index 00000000..bb401dd7
--- /dev/null
+++ b/src/projection_protocol/store/tests.rs
@@ -0,0 +1,383 @@
+use super::*;
+use crate::projection_protocol::{ResolvedProjectionKey, ResolvedProjectionObligation};
+use crate::table::{
+    DeleteTableRowMutation, ExpectedVersion, PrimaryKey, RowKey, RowValue, TableSchema,
+};
+
+fn topology() -> ProjectorTopologyId {
+    ProjectorTopologyId::new(1, "todos", [7; 32]).unwrap()
+}
+
+fn partition() -> ProjectionPartition {
+    ProjectionPartition::new(b"tenant:a".to_vec()).unwrap()
+}
+
+fn scope(model: &str, key: &[u8]) -> ProjectionRecordScope {
+    ProjectionRecordScope::new(topology(), partition(), model, key.to_vec()).unwrap()
+}
+
+fn schema() -> &'static TableSchema {
+    Box::leak(Box::new(TableSchema {
+        model_name: "TodoView".into(),
+        table_name: "todo_views".into(),
+        columns: Vec::new(),
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: Default::default(),
+    }))
+}
+
+fn same_transaction_evidence() -> SameTransactionProjectionEvidence {
+    let scope = scope("TodoView", b"todo-1");
+    let revision = RecordRevision::new(scope.clone(), 1, 1).unwrap();
+    let change = ProjectionChangeCursor::new(
+        topology(),
+        partition(),
+        ProjectionEpoch::new("changes-v1").unwrap(),
+        1,
+    )
+    .unwrap();
+    SameTransactionProjectionEvidence {
+        records: vec![ProjectionRecordMetadata {
+            revision: revision.clone(),
+            tombstone: false,
+            change: change.clone(),
+        }],
+        changes: vec![ProjectionChange {
+            cursor: change.clone(),
+            kind: ProjectionChangeKind::RecordUpsert,
+            causation_id: "cause-1".into(),
+            observation_kind: None,
+            scope: Some(scope.clone()),
+            revision: Some(revision.clone()),
+            failure_id: None,
+        }],
+        observations: vec![ProjectionObservation {
+            causation_id: "cause-1".into(),
+            kind: ProjectionObservationKind::Record,
+            revision: Some(revision),
+            scope,
+            change,
+        }],
+    }
+}
+
+fn failure_batch() -> ProjectionFailureBatch {
+    let input = TrustedProjectionInput::mint(
+        ProjectionInputCursor::new(
+            topology(),
+            partition(),
+            ProjectionSource::new("todo_stream", b"todo-1".to_vec()).unwrap(),
+            ProjectionEpoch::new("source-v1").unwrap(),
+            1,
+        )
+        .unwrap(),
+        ProjectionInputFingerprint::from_canonical_bytes(b"input-1"),
+        "message-1",
+        "cause-1",
+        ProjectionGeneration::initial(),
+        true,
+    )
+    .unwrap();
+    ProjectionFailureBatch::new(
+        input,
+        ProjectionEpoch::new("changes-v1").unwrap(),
+        "failure-1",
+        "decode_error",
+        b"bad payload".to_vec(),
+    )
+    .unwrap()
+}
+
+#[test]
+fn change_retention_is_nonzero_portable_and_bounded_by_default() {
+    assert_eq!(
+        ProjectionChangeRetention::default().max_retained_changes(),
+        DEFAULT_MAX_RETAINED_PROJECTION_CHANGES
+    );
+    assert_eq!(
+        ProjectionChangeRetention::new(0),
+        Err(ProjectionProtocolValidationError::Zero {
+            field: "projection retained change count",
+        })
+    );
+    assert_eq!(
+        ProjectionChangeRetention::new(u64::MAX),
+        Err(ProjectionProtocolValidationError::TooLarge {
+            field: "projection retained change count",
+            value: u64::MAX,
+            max: MAX_PROJECTION_POSITION,
+        })
+    );
+    assert_eq!(
+        ProjectionChangeRetention::new(MAX_PROJECTION_POSITION)
+            .unwrap()
+            .max_retained_changes(),
+        MAX_PROJECTION_POSITION
+    );
+}
+
+#[test]
+fn generations_are_nonzero_and_checked() {
+    assert!(ProjectionGeneration::new(0).is_err());
+    assert_eq!(ProjectionGeneration::initial().get(), 1);
+    assert_eq!(
+        ProjectionGeneration::new(7)
+            .unwrap()
+            .checked_next()
+            .unwrap()
+            .get(),
+        8
+    );
+    assert_eq!(
+        ProjectionGeneration::new(u64::MAX),
+        Err(ProjectionProtocolValidationError::TooLarge {
+            field: "projection generation",
+            value: u64::MAX,
+            max: MAX_PROJECTION_POSITION,
+        })
+    );
+    assert!(matches!(
+        ProjectionGeneration::new(MAX_PROJECTION_POSITION)
+            .unwrap()
+            .checked_next(),
+        Err(ProjectionProtocolError::PositionOverflow {
+            domain: "projection generation"
+        })
+    ));
+}
+
+#[test]
+fn trusted_input_identity_is_bounded_and_deterministic() {
+    let cursor = ProjectionInputCursor::new(
+        topology(),
+        partition(),
+        super::super::ProjectionSource::new("aggregate", b"todo:1".to_vec()).unwrap(),
+        ProjectionEpoch::new("source-v1").unwrap(),
+        0,
+    )
+    .unwrap();
+    let left = ProjectionInputFingerprint::from_canonical_bytes(b"same");
+    let right = ProjectionInputFingerprint::from_canonical_bytes(b"same");
+    assert_eq!(left, right);
+    let input = TrustedProjectionInput::mint(
+        cursor,
+        left,
+        "message-1",
+        "cause-1",
+        ProjectionGeneration::initial(),
+        false,
+    )
+    .unwrap();
+    assert!(input.inbox_receipt().validate().is_ok());
+    assert!(input.consumer_name().starts_with("projection:v1:"));
+}
+
+#[test]
+fn record_expectations_and_mutation_kinds_fail_closed() {
+    let first_scope = scope("TodoView", b"1");
+    let other_scope = scope("TodoView", b"2");
+    let revision = RecordRevision::new(other_scope, 1, 1).unwrap();
+    let delete = TableMutation::DeleteRow(DeleteTableRowMutation {
+        schema: schema(),
+        key: RowKey::new([("id", RowValue::String("1".into()))]),
+        expected_version: ExpectedVersion::Any,
+    });
+    assert!(matches!(
+        ProjectionRecordMutation::new(
+            first_scope.clone(),
+            delete.clone(),
+            ProjectionRecordExpectation::Exact(revision),
+            ProjectionMutationKind::Delete,
+        ),
+        Err(ProjectionProtocolError::ScopeMismatch { .. })
+    ));
+    assert!(matches!(
+        ProjectionRecordMutation::new(
+            first_scope,
+            delete,
+            ProjectionRecordExpectation::Missing,
+            ProjectionMutationKind::Delete,
+        ),
+        Err(ProjectionProtocolError::InvalidBatch(_))
+    ));
+}
+
+#[test]
+fn absent_and_explicit_null_obligation_partitions_survive_round_trip() {
+    let topology = ProjectorTopologyId::new(1, "todos", [9; 32]).unwrap();
+    let partition = super::super::ProjectionPartition::new(b"unit".to_vec()).unwrap();
+    let scope = super::super::ProjectionRecordScope::new(
+        topology,
+        partition,
+        "TodoView",
+        b"todo-1".to_vec(),
+    )
+    .unwrap();
+    let absent = ResolvedProjectionObligation {
+        projector: "todos".into(),
+        model: "TodoView".into(),
+        key: ResolvedProjectionKey { fields: Vec::new() },
+        partition: None,
+        scope,
+    };
+    let explicit_null = ResolvedProjectionObligation {
+        partition: Some(serde_json::Value::Null),
+        ..absent.clone()
+    };
+    let absent_json = serde_json::to_value(&absent).unwrap();
+    let null_json = serde_json::to_value(&explicit_null).unwrap();
+    assert!(absent_json.get("partition").is_none());
+    assert_eq!(null_json.get("partition"), Some(&serde_json::Value::Null));
+    assert_eq!(
+        serde_json::from_value::<ResolvedProjectionObligation>(null_json)
+            .unwrap()
+            .partition,
+        Some(serde_json::Value::Null)
+    );
+}
+
+#[test]
+fn same_transaction_replay_semantically_decodes_exact_typed_evidence() {
+    let replay = same_transaction_evidence().replay_value();
+    SameTransactionProjectionEvidence::validate_replay_value(&replay).unwrap();
+}
+
+#[test]
+fn same_transaction_replay_rejects_version_and_identity_digest_tampering() {
+    let valid = same_transaction_evidence().replay_value();
+    let mut cases = Vec::new();
+
+    let mut unsupported_version = valid.clone();
+    unsupported_version["version"] = serde_json::json!(2);
+    cases.push(("version", unsupported_version));
+
+    let mut malformed_topology_digest = valid.clone();
+    malformed_topology_digest["records"][0]["revision"]["scope"]["topology_digest"] =
+        serde_json::json!("00");
+    cases.push(("topology digest", malformed_topology_digest));
+
+    let mut mismatched_topology = valid.clone();
+    mismatched_topology["records"][0]["revision"]["scope"]["topology_digest"] =
+        serde_json::json!("08".repeat(32));
+    cases.push(("topology identity", mismatched_topology));
+
+    let mut mismatched_partition_digest = valid.clone();
+    mismatched_partition_digest["records"][0]["revision"]["scope"]["partition_digest"] =
+        serde_json::json!("00".repeat(32));
+    cases.push(("partition digest", mismatched_partition_digest));
+
+    let mut mismatched_key_digest = valid.clone();
+    mismatched_key_digest["records"][0]["revision"]["scope"]["key_digest"] =
+        serde_json::json!("00".repeat(32));
+    cases.push(("key digest", mismatched_key_digest));
+
+    let mut noncanonical_key = valid;
+    noncanonical_key["records"][0]["revision"]["scope"]["key"] = serde_json::json!("AA");
+    cases.push(("canonical key", noncanonical_key));
+
+    for (case, replay) in cases {
+        assert!(
+            SameTransactionProjectionEvidence::validate_replay_value(&replay).is_err(),
+            "{case} tampering must be rejected"
+        );
+    }
+}
+
+#[test]
+fn same_transaction_replay_rejects_cross_component_semantic_drift() {
+    let valid = same_transaction_evidence().replay_value();
+    let mut cases = Vec::new();
+
+    let mut zero_revision = valid.clone();
+    zero_revision["records"][0]["revision"]["revision"] = serde_json::json!(0);
+    cases.push(("zero revision", zero_revision));
+
+    let mut mismatched_revision = valid.clone();
+    mismatched_revision["changes"][0]["revision"]["revision"] = serde_json::json!(2);
+    cases.push(("mismatched revision", mismatched_revision));
+
+    let mut mismatched_cursor = valid.clone();
+    mismatched_cursor["observations"][0]["change"]["position"] = serde_json::json!(2);
+    cases.push(("mismatched cursor", mismatched_cursor));
+
+    let mut cursor_scope_drift = valid.clone();
+    let other_topology_digest = serde_json::json!("08".repeat(32));
+    cursor_scope_drift["records"][0]["change"]["topology_digest"] = other_topology_digest.clone();
+    cursor_scope_drift["changes"][0]["cursor"]["topology_digest"] = other_topology_digest.clone();
+    cursor_scope_drift["observations"][0]["change"]["topology_digest"] = other_topology_digest;
+    cases.push(("cursor/scope topology drift", cursor_scope_drift));
+
+    let mut mismatched_causation = valid.clone();
+    mismatched_causation["observations"][0]["causation_id"] = serde_json::json!("other-cause");
+    cases.push(("mismatched causation", mismatched_causation));
+
+    let mut tombstone = valid.clone();
+    tombstone["records"][0]["tombstone"] = serde_json::json!(true);
+    cases.push(("tombstone", tombstone));
+
+    let mut wrong_change_kind = valid.clone();
+    wrong_change_kind["changes"][0]["kind"] = serde_json::json!("record_delete");
+    cases.push(("wrong change kind", wrong_change_kind));
+
+    let mut duplicate_record = valid;
+    let record = duplicate_record["records"][0].clone();
+    duplicate_record["records"]
+        .as_array_mut()
+        .unwrap()
+        .push(record);
+    cases.push(("duplicate record", duplicate_record));
+
+    for (case, replay) in cases {
+        assert!(
+            SameTransactionProjectionEvidence::validate_replay_value(&replay).is_err(),
+            "{case} must be rejected"
+        );
+    }
+}
+
+#[test]
+fn failure_batch_validation_rechecks_all_mutable_identity_and_payload_fields() {
+    let valid = failure_batch();
+    valid.validate().unwrap();
+
+    let mut cases = Vec::new();
+    let mut empty_failure_id = valid.clone();
+    empty_failure_id.failure_id.clear();
+    cases.push(("empty failure ID", empty_failure_id));
+
+    let mut invalid_failure_code = valid.clone();
+    invalid_failure_code.failure_code = "decode error".into();
+    cases.push(("invalid failure code", invalid_failure_code));
+
+    let mut empty_details = valid.clone();
+    empty_details.failure_bytes.clear();
+    empty_details.failure_digest =
+        ProjectionFailureBatch::fingerprint_bytes(&empty_details.failure_bytes);
+    cases.push(("empty failure details", empty_details));
+
+    let mut oversized_details = valid.clone();
+    oversized_details.failure_bytes = vec![0; MAX_FAILURE_DETAIL_BYTES + 1];
+    oversized_details.failure_digest =
+        ProjectionFailureBatch::fingerprint_bytes(&oversized_details.failure_bytes);
+    cases.push(("oversized failure details", oversized_details));
+
+    let mut mismatched_digest = valid.clone();
+    mismatched_digest.failure_bytes[0] ^= 0xff;
+    cases.push(("mismatched failure digest", mismatched_digest));
+
+    let mut empty_message = valid.clone();
+    empty_message.input.message_id.clear();
+    cases.push(("empty input message ID", empty_message));
+
+    let mut invalid_causation = valid;
+    invalid_causation.input.causation_id = "cause\n2".into();
+    cases.push(("invalid input causation ID", invalid_causation));
+
+    for (case, batch) in cases {
+        assert!(batch.validate().is_err(), "{case} must be rejected");
+    }
+}
diff --git a/src/projection_protocol/store/trait.rs b/src/projection_protocol/store/trait.rs
new file mode 100644
index 00000000..f3733d3e
--- /dev/null
+++ b/src/projection_protocol/store/trait.rs
@@ -0,0 +1,140 @@
+use super::*;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ProjectionChangeRead {
+    Changes {
+        head: Option<ProjectionChangeCursor>,
+        compacted_through: u64,
+        changes: Vec<ProjectionChange>,
+    },
+    ResetRequired {
+        head: Option<ProjectionChangeCursor>,
+        compacted_through: u64,
+    },
+}
+
+/// Adapter contract for atomic causal projection persistence.
+pub(crate) trait ProjectionProtocolStore: Send + Sync {
+    /// Install model-wide causal ownership before projector traffic begins.
+    /// This bootstrap marker closes the absent-row race with legacy/raw write
+    /// plans; per-partition ownership is still verified inside each commit.
+    fn register_projection_models<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        ownership: &'a [ProjectionModelOwnership],
+    ) -> impl Future<Output = Result<(), ProjectionProtocolError>> + Send + 'a;
+
+    fn commit_projection(
+        &self,
+        batch: ProjectionCommitBatch,
+    ) -> impl Future<Output = Result<ProjectionCommitResult, ProjectionProtocolError>> + Send + '_;
+
+    fn record_projection_failure(
+        &self,
+        batch: ProjectionFailureBatch,
+    ) -> impl Future<Output = Result<ProjectionFailure, ProjectionProtocolError>> + Send + '_;
+
+    fn projection_checkpoint<'a>(
+        &'a self,
+        cursor_scope: &'a ProjectionInputCursor,
+        generation: ProjectionGeneration,
+    ) -> impl Future<Output = Result<Option<ProjectionCheckpoint>, ProjectionProtocolError>> + Send + 'a;
+
+    fn projection_record<'a>(
+        &'a self,
+        scope: &'a ProjectionRecordScope,
+    ) -> impl Future<Output = Result<Option<ProjectionRecordMetadata>, ProjectionProtocolError>>
+           + Send
+           + 'a;
+
+    fn projection_input_disposition<'a>(
+        &'a self,
+        input: &'a TrustedProjectionInput,
+    ) -> impl Future<Output = Result<ProjectionInputDisposition, ProjectionProtocolError>> + Send + 'a;
+
+    /// Read one physical row, its record metadata, requested source
+    /// checkpoints, and the partition live-resume boundary from one atomic
+    /// adapter snapshot.
+    fn projection_query_snapshot<'a>(
+        &'a self,
+        request: &'a ProjectionQuerySnapshotRequest,
+    ) -> impl Future<Output = Result<ProjectionQuerySnapshot, ProjectionProtocolError>> + Send + 'a;
+
+    fn projection_query_snapshot_batch<'a>(
+        &'a self,
+        request: &'a ProjectionQuerySnapshotBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionQuerySnapshotBatch, ProjectionProtocolError>> + Send + 'a;
+
+    fn projection_obligation_evidence_batch<'a>(
+        &'a self,
+        request: &'a ProjectionObligationEvidenceBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionObligationEvidenceBatch, ProjectionProtocolError>>
+           + Send
+           + 'a;
+
+    fn projection_live_record_batch<'a>(
+        &'a self,
+        request: &'a ProjectionLiveRecordBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionLiveRecordBatch, ProjectionProtocolError>> + Send + 'a;
+
+    fn projection_partition_runtime_state<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+    ) -> impl Future<Output = Result<Option<ProjectionPartitionRuntimeState>, ProjectionProtocolError>>
+           + Send
+           + 'a;
+
+    fn projection_observation<'a>(
+        &'a self,
+        causation_id: &'a str,
+        scope: &'a ProjectionRecordScope,
+        kind: ProjectionObservationKind,
+    ) -> impl Future<Output = Result<Option<ProjectionObservation>, ProjectionProtocolError>> + Send + 'a;
+
+    fn projection_changes<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        after: Option<&'a ProjectionChangeCursor>,
+        limit: usize,
+    ) -> impl Future<Output = Result<ProjectionChangeRead, ProjectionProtocolError>> + Send + 'a;
+
+    /// Start an explicitly linked repair generation for the immutable failure
+    /// currently stopping this exact partition. Implementations copy every
+    /// last-good source checkpoint, atomically switch the active generation,
+    /// and only then clear the stop fence.
+    fn repair_projection<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<ProjectionGeneration, ProjectionProtocolError>> + Send + 'a;
+
+    /// Compact durable changes through the supplied exact cursor. The returned
+    /// watermark is the last removed position; adapters never advertise a
+    /// larger window than they actually retain.
+    fn compact_projection_changes<'a>(
+        &'a self,
+        through: &'a ProjectionChangeCursor,
+    ) -> impl Future<Output = Result<u64, ProjectionProtocolError>> + Send + 'a;
+
+    fn projection_failure<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<Option<ProjectionFailure>, ProjectionProtocolError>> + Send + 'a;
+
+    /// Resolve a globally unique durable failure ID to its exact stored scope.
+    ///
+    /// Adapters must reconstruct and validate the canonical topology/partition
+    /// bytes they own. This is the safe basis for the public opaque repair
+    /// handle; callers never provide tenant-bearing partition bytes.
+    fn projection_failure_location<'a>(
+        &'a self,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<Option<ProjectionFailureLocation>, ProjectionProtocolError>>
+           + Send
+           + 'a;
+}
diff --git a/src/projection_protocol/workspace.rs b/src/projection_protocol/workspace.rs
new file mode 100644
index 00000000..c825e2d7
--- /dev/null
+++ b/src/projection_protocol/workspace.rs
@@ -0,0 +1,503 @@
+//! Framework-owned staging workspace for causal projectors.
+//!
+//! Handlers may describe row transitions, but they never receive a repository
+//! commit capability and cannot mint checkpoints, revisions, or observations.
+//! The workspace lowers typed model keys through the registered scope codec and
+//! seals the complete batch for the adapter after the handler returns.
+
+use std::collections::{BTreeMap, HashSet};
+use std::sync::Arc;
+
+use super::{
+    ProjectionCommitBatch, ProjectionEpoch, ProjectionModelOwnership, ProjectionMutationKind,
+    ProjectionObservationKind, ProjectionObservationRequest, ProjectionObservationTarget,
+    ProjectionProtocolError, ProjectionQuerySnapshotRequest, ProjectionRecordExpectation,
+    ProjectionRecordMutation, ProjectionRecordScope, ProjectionScopeCodec, RecordRevision,
+    TrustedProjectionInput,
+};
+use crate::read_model::RelationalReadModel;
+use crate::table::{
+    DeleteTableRowMutation, ExpectedVersion, PatchMode, PatchTableRowMutation, RowKey, RowPatch,
+    RowWriteMode, TableMutation, TableRowMutation, TableSchema,
+};
+
+/// Typed, commit-less workspace passed to a causal projector handler.
+///
+/// Every staged record is automatically observed for the input's causation.
+/// Declaration-owned dependency/existing-record observations are attached only
+/// through crate-private framework methods.
+#[derive(Debug)]
+pub struct ProjectionWorkspace {
+    codec: Arc<ProjectionScopeCodec>,
+    partition_value: Option<serde_json::Value>,
+    input: TrustedProjectionInput,
+    change_epoch: ProjectionEpoch,
+    ownership: BTreeMap<String, String>,
+    mutations: Vec<ProjectionRecordMutation>,
+    observations: Vec<ProjectionObservationRequest>,
+    staged_scopes: HashSet<ProjectionRecordScope>,
+}
+
+impl ProjectionWorkspace {
+    pub(crate) fn new(
+        codec: Arc<ProjectionScopeCodec>,
+        partition_value: Option<serde_json::Value>,
+        input: TrustedProjectionInput,
+        change_epoch: ProjectionEpoch,
+    ) -> Result<Self, ProjectionProtocolError> {
+        if codec.topology() != input.cursor.topology() {
+            return Err(ProjectionProtocolError::ScopeMismatch {
+                field: "projection workspace topology",
+            });
+        }
+        let partition = codec
+            .encode_partition(partition_value.as_ref())
+            .map_err(|error| ProjectionProtocolError::InvalidBatch(error.to_string()))?;
+        if &partition != input.cursor.projection_partition() {
+            return Err(ProjectionProtocolError::ScopeMismatch {
+                field: "projection workspace partition",
+            });
+        }
+        Ok(Self {
+            codec,
+            partition_value,
+            input,
+            change_epoch,
+            ownership: BTreeMap::new(),
+            mutations: Vec::new(),
+            observations: Vec::new(),
+            staged_scopes: HashSet::new(),
+        })
+    }
+
+    /// Stage a record that must not have prior protocol metadata.
+    pub fn create<M>(&mut self, model: &M) -> Result<&mut Self, ProjectionProtocolError>
+    where
+        M: RelationalReadModel,
+    {
+        let schema = M::schema();
+        schema.validate()?;
+        let key = model.primary_key()?;
+        let scope = self.scope(schema, &key)?;
+        let mutation = TableMutation::UpsertRow(TableRowMutation {
+            schema,
+            key,
+            values: model.to_row()?,
+            expected_version: ExpectedVersion::NotExists,
+            mode: RowWriteMode::Insert,
+        });
+        self.stage(
+            schema,
+            scope,
+            mutation,
+            ProjectionRecordExpectation::Missing,
+            ProjectionMutationKind::Upsert,
+        )
+    }
+
+    /// Stage a full-row update fenced by the exact protocol revision previously
+    /// loaded by the framework.
+    pub fn save<M>(
+        &mut self,
+        model: &M,
+        expected: &RecordRevision,
+    ) -> Result<&mut Self, ProjectionProtocolError>
+    where
+        M: RelationalReadModel,
+    {
+        let schema = M::schema();
+        schema.validate()?;
+        let key = model.primary_key()?;
+        let scope = self.scope(schema, &key)?;
+        let mutation = TableMutation::UpsertRow(TableRowMutation {
+            schema,
+            key,
+            values: model.to_row()?,
+            // The framework revision is the authoritative multi-source fence.
+            // The partition transaction serializes physical row writes.
+            expected_version: ExpectedVersion::Any,
+            mode: RowWriteMode::Upsert,
+        });
+        self.stage(
+            schema,
+            scope,
+            mutation,
+            ProjectionRecordExpectation::Exact(expected.clone()),
+            ProjectionMutationKind::Upsert,
+        )
+    }
+
+    /// Stage a sparse update fenced by an exact protocol revision.
+    pub fn patch<M>(
+        &mut self,
+        key: RowKey,
+        patch: RowPatch,
+        expected: &RecordRevision,
+    ) -> Result<&mut Self, ProjectionProtocolError>
+    where
+        M: RelationalReadModel,
+    {
+        let schema = M::schema();
+        schema.validate()?;
+        let scope = self.scope(schema, &key)?;
+        let mutation = TableMutation::PatchRow(PatchTableRowMutation {
+            schema,
+            key,
+            patch,
+            expected_version: ExpectedVersion::Any,
+            mode: PatchMode::UpdateExisting,
+        });
+        self.stage(
+            schema,
+            scope,
+            mutation,
+            ProjectionRecordExpectation::Exact(expected.clone()),
+            ProjectionMutationKind::Upsert,
+        )
+    }
+
+    /// Stage a durable tombstone and physical row deletion.
+    pub fn delete<M>(
+        &mut self,
+        key: RowKey,
+        expected: &RecordRevision,
+    ) -> Result<&mut Self, ProjectionProtocolError>
+    where
+        M: RelationalReadModel,
+    {
+        let schema = M::schema();
+        schema.validate()?;
+        let scope = self.scope(schema, &key)?;
+        let mutation = TableMutation::DeleteRow(DeleteTableRowMutation {
+            schema,
+            key,
+            expected_version: ExpectedVersion::Any,
+        });
+        self.stage(
+            schema,
+            scope,
+            mutation,
+            ProjectionRecordExpectation::Exact(expected.clone()),
+            ProjectionMutationKind::Delete,
+        )
+    }
+
+    /// Explicitly recreate a deleted record from its exact tombstone revision.
+    /// The adapter advances the incarnation atomically; ordinary `save` cannot
+    /// cross a tombstone.
+    pub fn recreate<M>(
+        &mut self,
+        model: &M,
+        expected_tombstone: &RecordRevision,
+    ) -> Result<&mut Self, ProjectionProtocolError>
+    where
+        M: RelationalReadModel,
+    {
+        let schema = M::schema();
+        schema.validate()?;
+        let key = model.primary_key()?;
+        let scope = self.scope(schema, &key)?;
+        let mutation = TableMutation::UpsertRow(TableRowMutation {
+            schema,
+            key,
+            values: model.to_row()?,
+            expected_version: ExpectedVersion::NotExists,
+            mode: RowWriteMode::Insert,
+        });
+        self.stage(
+            schema,
+            scope,
+            mutation,
+            ProjectionRecordExpectation::Exact(expected_tombstone.clone()),
+            ProjectionMutationKind::Recreate,
+        )
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.mutations.is_empty() && self.observations.is_empty()
+    }
+
+    /// Derive a physical-row + protocol snapshot request from this workspace's
+    /// exact compiled codec and partition. The handler can supply only a typed
+    /// model key; it cannot pair an arbitrary row with independently minted
+    /// revision/checkpoint scope bytes.
+    pub(crate) fn query_snapshot_request<M>(
+        &self,
+        key: RowKey,
+    ) -> Result<ProjectionQuerySnapshotRequest, ProjectionProtocolError>
+    where
+        M: RelationalReadModel,
+    {
+        self.ensure_registered_schema(M::schema())?;
+        ProjectionQuerySnapshotRequest::new(
+            &self.codec,
+            self.partition_value.as_ref(),
+            &M::schema().model_name,
+            key,
+            Vec::new(),
+        )
+    }
+
+    #[allow(dead_code)]
+    pub(crate) fn confirm_existing(
+        &mut self,
+        schema: &'static TableSchema,
+        revision: RecordRevision,
+    ) -> Result<&mut Self, ProjectionProtocolError> {
+        self.register_ownership(schema)?;
+        self.observations.push(ProjectionObservationRequest {
+            kind: ProjectionObservationKind::Record,
+            target: ProjectionObservationTarget::ExistingRecord(revision),
+        });
+        Ok(self)
+    }
+
+    #[allow(dead_code)]
+    pub(crate) fn confirm_dependency(
+        &mut self,
+        schema: &'static TableSchema,
+        key: &RowKey,
+    ) -> Result<&mut Self, ProjectionProtocolError> {
+        let scope = self.scope(schema, key)?;
+        self.observations.push(ProjectionObservationRequest {
+            kind: ProjectionObservationKind::Dependency,
+            target: ProjectionObservationTarget::Dependency(scope),
+        });
+        Ok(self)
+    }
+
+    pub(crate) fn ownership(
+        &self,
+    ) -> Result<Vec<ProjectionModelOwnership>, ProjectionProtocolError> {
+        self.ownership
+            .iter()
+            .map(|(model, table)| ProjectionModelOwnership::new(model.clone(), table.clone()))
+            .collect()
+    }
+
+    pub(crate) fn into_batch(self) -> Result<ProjectionCommitBatch, ProjectionProtocolError> {
+        let ownership = self.ownership()?;
+        let batch = ProjectionCommitBatch {
+            input: self.input,
+            change_epoch: self.change_epoch,
+            ownership,
+            mutations: self.mutations,
+            observations: self.observations,
+        };
+        batch.validate()?;
+        Ok(batch)
+    }
+
+    fn scope(
+        &mut self,
+        schema: &'static TableSchema,
+        key: &RowKey,
+    ) -> Result<ProjectionRecordScope, ProjectionProtocolError> {
+        self.register_ownership(schema)?;
+        self.codec
+            .encode_row_scope(
+                self.codec.topology().name(),
+                &schema.model_name,
+                self.partition_value.as_ref(),
+                key,
+            )
+            .map_err(|error| ProjectionProtocolError::InvalidBatch(error.to_string()))
+    }
+
+    fn register_ownership(
+        &mut self,
+        schema: &'static TableSchema,
+    ) -> Result<(), ProjectionProtocolError> {
+        self.ensure_registered_schema(schema)?;
+        match self
+            .ownership
+            .insert(schema.model_name.clone(), schema.table_name.clone())
+        {
+            Some(table) if table != schema.table_name => {
+                Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection model `{}` was staged for both table `{table}` and `{}`",
+                    schema.model_name, schema.table_name
+                )))
+            }
+            _ => Ok(()),
+        }
+    }
+
+    fn ensure_registered_schema(
+        &self,
+        schema: &'static TableSchema,
+    ) -> Result<(), ProjectionProtocolError> {
+        let registered = self
+            .codec
+            .registered_schema(&schema.model_name)
+            .map_err(|error| ProjectionProtocolError::InvalidBatch(error.to_string()))?;
+        if registered != schema {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection model `{}` schema differs from the exact compiled topology",
+                schema.model_name
+            )));
+        }
+        Ok(())
+    }
+
+    fn stage(
+        &mut self,
+        schema: &'static TableSchema,
+        scope: ProjectionRecordScope,
+        mutation: TableMutation,
+        expectation: ProjectionRecordExpectation,
+        kind: ProjectionMutationKind,
+    ) -> Result<&mut Self, ProjectionProtocolError> {
+        if !self.staged_scopes.insert(scope.clone()) {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection workspace repeats model `{}` record scope",
+                scope.model()
+            )));
+        }
+        self.register_ownership(schema)?;
+        self.mutations.push(ProjectionRecordMutation::new(
+            scope.clone(),
+            mutation,
+            expectation,
+            kind,
+        )?);
+        self.observations.push(ProjectionObservationRequest {
+            kind: ProjectionObservationKind::Record,
+            target: ProjectionObservationTarget::StagedRecord(scope),
+        });
+        Ok(self)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::projection_protocol::{
+        ProjectionGeneration, ProjectionInputCursor, ProjectionInputFingerprint, ProjectionSource,
+        ProjectorTopologyId,
+    };
+    use crate::table::{ColumnType, PrimaryKey, RowValue, RowValues, TableColumn, TableKind};
+
+    #[derive(Clone)]
+    struct TodoView {
+        id: u64,
+        title: String,
+    }
+
+    impl RelationalReadModel for TodoView {
+        fn schema() -> &'static TableSchema {
+            static SCHEMA: std::sync::OnceLock<TableSchema> = std::sync::OnceLock::new();
+            SCHEMA.get_or_init(|| TableSchema {
+                model_name: "TodoView".into(),
+                table_name: "todo_views".into(),
+                columns: vec![
+                    TableColumn {
+                        primary_key: true,
+                        ..TableColumn::new("id", "todo_id", ColumnType::UnsignedInteger)
+                    },
+                    TableColumn::new("title", "title", ColumnType::Text),
+                ],
+                primary_key: PrimaryKey::new(["todo_id"]),
+                version_column: Some("_sourced_version".into()),
+                foreign_keys: Vec::new(),
+                indexes: Vec::new(),
+                relationships: Vec::new(),
+                kind: TableKind::ReadModel,
+            })
+        }
+
+        fn primary_key(&self) -> Result<RowKey, crate::table::TableStoreError> {
+            Ok(RowKey::new([("todo_id", RowValue::U64(self.id))]))
+        }
+
+        fn to_row(&self) -> Result<RowValues, crate::table::TableStoreError> {
+            let mut values = RowValues::new();
+            values.insert("todo_id", RowValue::U64(self.id));
+            values.insert("title", RowValue::String(self.title.clone()));
+            Ok(values)
+        }
+
+        fn from_row(_row: RowValues) -> Result<Self, crate::table::TableStoreError> {
+            unreachable!("workspace staging test does not hydrate rows")
+        }
+    }
+
+    fn workspace() -> ProjectionWorkspace {
+        let topology = ProjectorTopologyId::new(1, "project_todos", [4; 32]).unwrap();
+        let mut codec = ProjectionScopeCodec::new(topology.clone());
+        codec
+            .register_model("TodoView", TodoView::schema())
+            .unwrap();
+        let partition_value = Some(serde_json::json!({"tenant": "a"}));
+        let partition = codec.encode_partition(partition_value.as_ref()).unwrap();
+        let cursor = ProjectionInputCursor::new(
+            topology,
+            partition,
+            ProjectionSource::new("todo-stream", b"todo:7".to_vec()).unwrap(),
+            ProjectionEpoch::new("source-v1").unwrap(),
+            0,
+        )
+        .unwrap();
+        let input = TrustedProjectionInput::mint(
+            cursor,
+            ProjectionInputFingerprint::from_canonical_bytes(b"input"),
+            "message-1",
+            "cause-1",
+            ProjectionGeneration::initial(),
+            true,
+        )
+        .unwrap();
+        ProjectionWorkspace::new(
+            Arc::new(codec),
+            partition_value,
+            input,
+            ProjectionEpoch::new("changes-v1").unwrap(),
+        )
+        .unwrap()
+    }
+
+    #[test]
+    fn create_stages_one_sealed_mutation_and_framework_observation() {
+        let mut workspace = workspace();
+        workspace
+            .create(&TodoView {
+                id: 7,
+                title: "write defensible code".into(),
+            })
+            .unwrap();
+        let batch = workspace.into_batch().unwrap();
+        assert_eq!(batch.mutations.len(), 1);
+        assert_eq!(batch.observations.len(), 1);
+        assert_eq!(batch.ownership.len(), 1);
+        assert!(matches!(
+            batch.observations[0].target,
+            ProjectionObservationTarget::StagedRecord(_)
+        ));
+    }
+
+    #[test]
+    fn workspace_rejects_revision_from_another_canonical_scope() {
+        let mut workspace = workspace();
+        let wrong_scope = ProjectionRecordScope::new(
+            workspace.input.cursor.topology().clone(),
+            workspace.input.cursor.projection_partition().clone(),
+            "TodoView",
+            b"different-key".to_vec(),
+        )
+        .unwrap();
+        let wrong_revision = RecordRevision::new(wrong_scope, 1, 1).unwrap();
+        let error = workspace
+            .save(
+                &TodoView {
+                    id: 7,
+                    title: "changed".into(),
+                },
+                &wrong_revision,
+            )
+            .unwrap_err();
+        assert!(matches!(
+            error,
+            ProjectionProtocolError::ScopeMismatch { .. }
+        ));
+    }
+}
diff --git a/src/queued_repo/repository.rs b/src/queued_repo/repository.rs
index 2147f661..1434a91b 100644
--- a/src/queued_repo/repository.rs
+++ b/src/queued_repo/repository.rs
@@ -6,8 +6,25 @@
 use std::future::Future;
 use std::sync::Arc;
 
+use crate::command_ledger::{
+    AttemptFence, CausalCommitBatch, CausalGetStream, CausalRepositoryIdentity,
+    CausalStorageIdentity, CausalTransactionalCommit, CommandLedgerError, CommandLedgerKey,
+    CommandLedgerStore, CommandLookup, CommandLookupScope, CommandReservation, ReservationOutcome,
+};
 use crate::entity::Entity;
 use crate::lock::{InMemoryLockManager, Lock, LockManager};
+use crate::projection_protocol::{
+    ProjectionChangeCursor, ProjectionChangeRead, ProjectionCheckpoint, ProjectionCommitBatch,
+    ProjectionCommitResult, ProjectionFailure, ProjectionFailureBatch, ProjectionFailureLocation,
+    ProjectionGeneration, ProjectionInputCursor, ProjectionInputDisposition,
+    ProjectionLiveRecordBatch, ProjectionLiveRecordBatchRequest, ProjectionModelOwnership,
+    ProjectionObligationEvidenceBatch, ProjectionObligationEvidenceBatchRequest,
+    ProjectionObservation, ProjectionObservationKind, ProjectionPartition,
+    ProjectionPartitionRuntimeState, ProjectionProtocolError, ProjectionProtocolStore,
+    ProjectionQuerySnapshot, ProjectionQuerySnapshotBatch, ProjectionQuerySnapshotBatchRequest,
+    ProjectionQuerySnapshotRequest, ProjectionRecordMetadata, ProjectionRecordScope,
+    ProjectorTopologyId, TrustedProjectionInput,
+};
 use crate::read_model::{ReadModelLoadGraph, ReadModelLoadRequest, ReadModelQueryCapabilities};
 use crate::repository::{
     CommitBatch, GetStream, InboxStore, ReadModelWritePlanStore, RelationalReadModelQueryStore,
@@ -165,6 +182,67 @@ where
     }
 }
 
+impl<R, L> CausalGetStream for QueuedRepository<R, L>
+where
+    R: CausalGetStream,
+    L: LockManager,
+{
+    fn get_causal_stream<'a>(
+        &'a self,
+        identity: &'a StreamIdentity,
+    ) -> impl Future<Output = Result<Option<Entity>, RepositoryError>> + Send + 'a {
+        // Deliberately bypass queue locking: a causal workspace may await user
+        // handler code between load and commit. Optimistic stream versions and
+        // the durable command attempt fence provide the authoritative safety.
+        self.inner.get_causal_stream(identity)
+    }
+}
+
+impl<R, L> CausalRepositoryIdentity for QueuedRepository<R, L>
+where
+    R: CausalRepositoryIdentity,
+    L: LockManager,
+{
+    fn causal_storage_identity(&self) -> CausalStorageIdentity {
+        self.inner.causal_storage_identity()
+    }
+}
+
+impl<R, L> CommandLedgerStore for QueuedRepository<R, L>
+where
+    R: CommandLedgerStore,
+    L: LockManager,
+{
+    fn reserve_command(
+        &self,
+        reservation: CommandReservation,
+    ) -> impl Future<Output = Result<ReservationOutcome, CommandLedgerError>> + Send + '_ {
+        self.inner.reserve_command(reservation)
+    }
+
+    fn lookup_command<'a>(
+        &'a self,
+        key: &'a CommandLedgerKey,
+        scope: CommandLookupScope<'a>,
+    ) -> impl Future<Output = Result<CommandLookup, CommandLedgerError>> + Send + 'a {
+        self.inner.lookup_command(key, scope)
+    }
+
+    fn mark_retryable_unknown(
+        &self,
+        attempt: AttemptFence,
+    ) -> impl Future<Output = Result<(), CommandLedgerError>> + Send + '_ {
+        self.inner.mark_retryable_unknown(attempt)
+    }
+
+    fn compact_expired_commands(
+        &self,
+        limit: usize,
+    ) -> impl Future<Output = Result<u64, CommandLedgerError>> + Send + '_ {
+        self.inner.compact_expired_commands(limit)
+    }
+}
+
 impl<R, L> TransactionalCommit for QueuedRepository<R, L>
 where
     R: TransactionalCommit,
@@ -201,6 +279,182 @@ where
     }
 }
 
+impl<R, L> CausalTransactionalCommit for QueuedRepository<R, L>
+where
+    R: CausalTransactionalCommit,
+    L: LockManager,
+{
+    fn commit_causal_batch<'a>(
+        &'a self,
+        batch: CausalCommitBatch<'a>,
+    ) -> impl Future<Output = Result<(), CommandLedgerError>> + Send + 'a {
+        // Causal loads deliberately bypass this wrapper's queue locks, so a
+        // causal commit never owns one to release. Delegating without touching
+        // the lock manager is essential: a matching lock may belong to an
+        // unrelated legacy load/commit flow that is still in progress.
+        self.inner.commit_causal_batch(batch)
+    }
+}
+
+impl<R, L> ProjectionProtocolStore for QueuedRepository<R, L>
+where
+    R: ProjectionProtocolStore,
+    L: LockManager,
+{
+    fn register_projection_models<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        ownership: &'a [ProjectionModelOwnership],
+    ) -> impl Future<Output = Result<(), ProjectionProtocolError>> + Send + 'a {
+        self.inner.register_projection_models(topology, ownership)
+    }
+
+    fn commit_projection(
+        &self,
+        batch: ProjectionCommitBatch,
+    ) -> impl Future<Output = Result<ProjectionCommitResult, ProjectionProtocolError>> + Send + '_
+    {
+        self.inner.commit_projection(batch)
+    }
+
+    fn record_projection_failure(
+        &self,
+        batch: ProjectionFailureBatch,
+    ) -> impl Future<Output = Result<ProjectionFailure, ProjectionProtocolError>> + Send + '_ {
+        self.inner.record_projection_failure(batch)
+    }
+
+    fn projection_checkpoint<'a>(
+        &'a self,
+        cursor_scope: &'a ProjectionInputCursor,
+        generation: ProjectionGeneration,
+    ) -> impl Future<Output = Result<Option<ProjectionCheckpoint>, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner.projection_checkpoint(cursor_scope, generation)
+    }
+
+    fn projection_record<'a>(
+        &'a self,
+        scope: &'a ProjectionRecordScope,
+    ) -> impl Future<Output = Result<Option<ProjectionRecordMetadata>, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        self.inner.projection_record(scope)
+    }
+
+    fn projection_input_disposition<'a>(
+        &'a self,
+        input: &'a TrustedProjectionInput,
+    ) -> impl Future<Output = Result<ProjectionInputDisposition, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner.projection_input_disposition(input)
+    }
+
+    fn projection_query_snapshot<'a>(
+        &'a self,
+        request: &'a ProjectionQuerySnapshotRequest,
+    ) -> impl Future<Output = Result<ProjectionQuerySnapshot, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner.projection_query_snapshot(request)
+    }
+
+    fn projection_query_snapshot_batch<'a>(
+        &'a self,
+        request: &'a ProjectionQuerySnapshotBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionQuerySnapshotBatch, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner.projection_query_snapshot_batch(request)
+    }
+
+    fn projection_obligation_evidence_batch<'a>(
+        &'a self,
+        request: &'a ProjectionObligationEvidenceBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionObligationEvidenceBatch, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        self.inner.projection_obligation_evidence_batch(request)
+    }
+
+    fn projection_live_record_batch<'a>(
+        &'a self,
+        request: &'a ProjectionLiveRecordBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionLiveRecordBatch, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner.projection_live_record_batch(request)
+    }
+
+    fn projection_partition_runtime_state<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+    ) -> impl Future<Output = Result<Option<ProjectionPartitionRuntimeState>, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        self.inner
+            .projection_partition_runtime_state(topology, partition)
+    }
+
+    fn projection_observation<'a>(
+        &'a self,
+        causation_id: &'a str,
+        scope: &'a ProjectionRecordScope,
+        kind: ProjectionObservationKind,
+    ) -> impl Future<Output = Result<Option<ProjectionObservation>, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner.projection_observation(causation_id, scope, kind)
+    }
+
+    fn projection_changes<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        after: Option<&'a ProjectionChangeCursor>,
+        limit: usize,
+    ) -> impl Future<Output = Result<ProjectionChangeRead, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner
+            .projection_changes(topology, partition, after, limit)
+    }
+
+    fn repair_projection<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<ProjectionGeneration, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner
+            .repair_projection(topology, partition, failure_id)
+    }
+
+    fn compact_projection_changes<'a>(
+        &'a self,
+        through: &'a ProjectionChangeCursor,
+    ) -> impl Future<Output = Result<u64, ProjectionProtocolError>> + Send + 'a {
+        self.inner.compact_projection_changes(through)
+    }
+
+    fn projection_failure<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<Option<ProjectionFailure>, ProjectionProtocolError>> + Send + 'a
+    {
+        self.inner
+            .projection_failure(topology, partition, failure_id)
+    }
+
+    fn projection_failure_location<'a>(
+        &'a self,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<Option<ProjectionFailureLocation>, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        self.inner.projection_failure_location(failure_id)
+    }
+}
+
 // Non-locking forwards: read models, snapshots, and the consumer inbox are not
 // gated by aggregate locks (matching the sync `SnapshotStore` delegation), so a
 // queued repository stays a complete drop-in for its inner async repository.
@@ -414,3 +668,75 @@ pub trait Queueable: Sized {
 }
 
 impl<T> Queueable for T {}
+
+#[cfg(test)]
+mod tests {
+    use std::time::Duration;
+
+    use uuid::Uuid;
+
+    use super::*;
+    use crate::command_ledger::{
+        CanonicalInputHash, CommandContractFingerprint, CommandId, PrincipalPartitionId,
+        TerminalCommandState,
+    };
+    use crate::in_memory_repo::InMemoryRepository;
+    use crate::repository::StreamWrite;
+
+    #[tokio::test]
+    async fn causal_commit_does_not_release_lock_owned_by_legacy_load() {
+        let repository = QueuedRepository::new(InMemoryRepository::new());
+        let aggregate_id = format!("queued-causal-lock-{}", Uuid::now_v7());
+        let identity = StreamIdentity::new("queued-causal-test", &aggregate_id).unwrap();
+
+        // The ordinary read API acquires and intentionally retains this lock
+        // until its legacy transaction commits or aborts.
+        assert!(repository.get_stream(&identity).await.unwrap().is_none());
+        let held_lock = repository
+            .lock_manager()
+            .get_lock(&identity.storage_key())
+            .unwrap();
+        assert!(!held_lock.try_lock().await.unwrap());
+
+        let command_id = Uuid::now_v7().to_string();
+        let reservation = CommandReservation::new(
+            CommandLedgerKey::new(
+                "queued-causal-test",
+                PrincipalPartitionId::new("v1:sha256:test-principal").unwrap(),
+                CommandId::parse(&command_id).unwrap(),
+            )
+            .unwrap(),
+            "test.create",
+            CommandContractFingerprint::new([1; 32]),
+            CanonicalInputHash::new([2; 32]),
+            Duration::from_secs(30),
+            Duration::from_secs(300),
+        )
+        .unwrap();
+        let attempt = match repository.reserve_command(reservation).await.unwrap() {
+            ReservationOutcome::Acquired(attempt) => attempt,
+            other => panic!("expected an acquired command attempt, got {other:?}"),
+        };
+        let completion = attempt
+            .complete(
+                TerminalCommandState::Accepted,
+                serde_json::json!({"accepted": true}),
+                Duration::from_secs(300),
+            )
+            .unwrap();
+        let mut entity = Entity::with_id(&aggregate_id);
+        entity.digest_empty("Created").unwrap();
+        let domain = CommitBatch::new(vec![StreamWrite::new(identity.clone(), &mut entity)]);
+
+        repository
+            .commit_causal_batch(CausalCommitBatch::new(domain, completion))
+            .await
+            .unwrap();
+
+        assert!(
+            !held_lock.try_lock().await.unwrap(),
+            "causal commit must not release a lock owned by a legacy load"
+        );
+        repository.abort(&identity).await.unwrap();
+    }
+}
diff --git a/src/read_model/change.rs b/src/read_model/change.rs
new file mode 100644
index 00000000..5a3fc448
--- /dev/null
+++ b/src/read_model/change.rs
@@ -0,0 +1,26 @@
+//! Read-model change notification seam (always compiled).
+//!
+//! The emitting side lives in `sqlx_repo` (broadcast + Postgres NOTIFY) and must
+//! not depend on the `graphql` feature. Subscriptions consume
+//! [`ReadModelChange`] via `SqlxRepository::read_model_changes()` or
+//! `GraphqlEngineBuilder::change_stream`.
+
+use std::collections::BTreeSet;
+
+/// Tables touched by a successful read-model write-plan commit.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct ReadModelChange {
+    pub tables: BTreeSet<String>,
+}
+
+impl ReadModelChange {
+    pub fn new(tables: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        Self {
+            tables: tables.into_iter().map(Into::into).collect(),
+        }
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.tables.is_empty()
+    }
+}
diff --git a/src/read_model/in_memory.rs b/src/read_model/in_memory.rs
index b32255e3..60b8156b 100644
--- a/src/read_model/in_memory.rs
+++ b/src/read_model/in_memory.rs
@@ -4,7 +4,7 @@
     reason = "async trait impls return impl Future + Send to preserve public Send bounds"
 )]
 
-use std::collections::{BTreeMap, HashMap};
+use std::collections::{BTreeMap, HashMap, HashSet};
 use std::future::Future;
 use std::sync::{Arc, RwLock};
 
@@ -142,7 +142,7 @@ pub(crate) fn apply_read_model_write_plan(
     Ok(TableCommitOutcome::applied())
 }
 
-fn relational_storage_key(table_name: &str, key: &RowKey) -> String {
+pub(crate) fn relational_storage_key(table_name: &str, key: &RowKey) -> String {
     format!("{}:{}", table_name, key_fingerprint(key))
 }
 
@@ -235,6 +235,7 @@ fn concurrency_conflict(
 pub struct InMemoryReadModelStore {
     pub(crate) relational_rows: Arc<RwLock<HashMap<String, StoredRow>>>,
     schema_registry: Arc<RwLock<TableSchemaRegistry>>,
+    causal_tables: Arc<RwLock<HashSet<String>>>,
 }
 
 impl Default for InMemoryReadModelStore {
@@ -246,9 +247,14 @@ impl Default for InMemoryReadModelStore {
 impl InMemoryReadModelStore {
     /// Create a new empty read model store.
     pub fn new() -> Self {
+        Self::with_causal_table_marker(Arc::new(RwLock::new(HashSet::new())))
+    }
+
+    pub(crate) fn with_causal_table_marker(causal_tables: Arc<RwLock<HashSet<String>>>) -> Self {
         Self {
             relational_rows: Arc::new(RwLock::new(HashMap::new())),
             schema_registry: Arc::new(RwLock::new(TableSchemaRegistry::new())),
+            causal_tables,
         }
     }
 
@@ -290,6 +296,19 @@ impl ReadModelWritePlanStore for InMemoryReadModelStore {
                 .relational_rows
                 .write()
                 .map_err(|_| TableStoreError::Storage("lock poisoned".into()))?;
+            let causal_tables = self.causal_tables.read().map_err(|_| {
+                TableStoreError::Storage("causal table marker lock poisoned".into())
+            })?;
+            if let Some(table) = plan
+                .mutations
+                .iter()
+                .map(TableMutation::table_name)
+                .find(|table| causal_tables.contains(*table))
+            {
+                return Err(TableStoreError::CausalWriteRequired {
+                    table: table.to_string(),
+                });
+            }
 
             let mut staged_rows = relational_rows.clone();
             let outcome = apply_read_model_write_plan(plan, &mut staged_rows)?;
@@ -579,6 +598,7 @@ mod tests {
                 foreign_keys: Vec::new(),
                 indexes: Vec::new(),
                 relationships: Vec::new(),
+                kind: crate::TableKind::ReadModel,
             });
         &SCHEMA
     }
diff --git a/src/read_model/mod.rs b/src/read_model/mod.rs
index f422f108..28569f86 100644
--- a/src/read_model/mod.rs
+++ b/src/read_model/mod.rs
@@ -26,11 +26,14 @@
 //! ```
 
 mod capabilities;
+pub mod change;
 pub(crate) mod in_memory;
 mod load;
 mod plan;
 mod workspace;
 
+pub use change::ReadModelChange;
+
 use serde::{de::DeserializeOwned, Serialize};
 
 use crate::table::{RowKey, RowValues, TableSchema, TableStoreError};
diff --git a/src/repository/error.rs b/src/repository/error.rs
index 7e79441c..c74f1741 100644
--- a/src/repository/error.rs
+++ b/src/repository/error.rs
@@ -35,6 +35,10 @@ pub enum RepositoryError {
         consumer: String,
         message_id: String,
     },
+    /// A raw/legacy repository batch targeted a causal-owned read-model table.
+    CausalWriteRequired {
+        table: String,
+    },
     InvalidStreamIdentity {
         aggregate_type: String,
         aggregate_id: String,
@@ -130,6 +134,7 @@ impl RepositoryError {
             | RepositoryError::DuplicateOutboxMessageInBatch { .. }
             | RepositoryError::DuplicateInboxReceipt { .. }
             | RepositoryError::InvalidInboxReceipt { .. }
+            | RepositoryError::CausalWriteRequired { .. }
             | RepositoryError::InvalidStreamIdentity { .. }
             | RepositoryError::InvalidState { .. }
             | RepositoryError::Replay(_)
@@ -181,6 +186,10 @@ impl fmt::Display for RepositoryError {
                 "invalid consumer inbox receipt (consumer `{}`, message `{}`): consumer and message id must be non-empty",
                 consumer, message_id
             ),
+            RepositoryError::CausalWriteRequired { table } => write!(
+                f,
+                "table `{table}` is causal-owned and requires the projection commit path"
+            ),
             RepositoryError::InvalidStreamIdentity {
                 aggregate_type,
                 aggregate_id,
@@ -240,16 +249,22 @@ impl From<LockError> for RepositoryError {
 
 impl From<TableStoreError> for RepositoryError {
     fn from(err: TableStoreError) -> Self {
+        if let TableStoreError::CausalWriteRequired { table } = err {
+            return RepositoryError::CausalWriteRequired { table };
+        }
         // Map to `Storage` so the read-model error keeps a retry signal and its
-        // source instead of collapsing to an opaque `Model` string. Only a lock
-        // failure carries a transient/permanent distinction we can recover here;
+        // source instead of collapsing to an opaque `Model` string. Locks and
+        // structured backend failures carry the retry classification through;
         // every other read-model variant is deterministic (a concurrency
         // conflict, serde/metadata fault, or not-found will fail the same way on
-        // redelivery). `TableStoreError::Storage` is itself a stringified backend
-        // error with no preserved retry signal — without changing `read_model`
-        // it is classified permanent, which is the safe default (it cannot loop
-        // forever; it surfaces to the failure policy).
-        let retryable = matches!(&err, TableStoreError::Lock(lock) if lock.is_retryable());
+        // redelivery). Legacy `TableStoreError::Storage` remains string-only and
+        // therefore permanent by default; guessing retryability from text would
+        // risk an infinite poison-message loop.
+        let retryable = match &err {
+            TableStoreError::Lock(lock) => lock.is_retryable(),
+            TableStoreError::BackendStorage { retryable, .. } => *retryable,
+            _ => false,
+        };
         RepositoryError::Storage {
             operation: "read model".into(),
             retryable,
@@ -270,3 +285,36 @@ impl From<EventRecordError> for RepositoryError {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn table_backend_retry_class_survives_repository_conversion() {
+        let transient = RepositoryError::from(TableStoreError::BackendStorage {
+            operation: "sqlite projection write".into(),
+            retryable: true,
+            message: "database is busy".into(),
+        });
+        let permanent = RepositoryError::from(TableStoreError::BackendStorage {
+            operation: "postgres projection write".into(),
+            retryable: false,
+            message: "constraint violation".into(),
+        });
+
+        assert!(transient.is_retryable());
+        assert!(!permanent.is_retryable());
+        assert!(transient.to_string().contains("retryable"));
+        assert!(permanent.to_string().contains("permanent"));
+
+        let causal = RepositoryError::from(TableStoreError::CausalWriteRequired {
+            table: "todo_views".into(),
+        });
+        assert!(matches!(
+            causal,
+            RepositoryError::CausalWriteRequired { ref table } if table == "todo_views"
+        ));
+        assert!(!causal.is_retryable());
+    }
+}
diff --git a/src/sqlite_repo/mod.rs b/src/sqlite_repo/mod.rs
index 501df4ba..d7e8b5f9 100644
--- a/src/sqlite_repo/mod.rs
+++ b/src/sqlite_repo/mod.rs
@@ -34,11 +34,23 @@ use crate::table::{
 };
 
 static SQLITE_MIGRATOR: LazyLock<Migrator> = LazyLock::new(|| {
-    embedded_migrator(&[(
-        1,
-        "initial",
-        include_str!("../../migrations/sqlite/0001_initial.sql"),
-    )])
+    embedded_migrator(&[
+        (
+            1,
+            "initial",
+            include_str!("../../migrations/sqlite/0001_initial.sql"),
+        ),
+        (
+            2,
+            "command ledger",
+            include_str!("../../migrations/sqlite/0002_command_ledger.sql"),
+        ),
+        (
+            3,
+            "projection protocol",
+            include_str!("../../migrations/sqlite/0003_projection_protocol.sql"),
+        ),
+    ])
 });
 const SQLITE_BACKEND: &str = "sqlite";
 const SIGNED_INTEGER_STORAGE: &str = "signed integer storage";
@@ -60,6 +72,11 @@ impl crate::sqlx_repo::repo::SqlxRepoBackend for Sqlite {
     // recovery re-reads stream versions in the same transaction.
     const CONFLICT_REREAD_IN_TX: bool = true;
     const NOW: &'static str = "CURRENT_TIMESTAMP";
+    const COMMAND_LEDGER_SELECT: &'static str = "command_name, command_contract_hash, \
+         input_hash, state, causation_id, attempt_token, attempt_number, lease_expires_at, \
+         outcome, created_at, updated_at, completed_at, retention_expires_at, compacted_at";
+    const COMMAND_LEDGER_LOCK_SUFFIX: &'static str = "";
+    const COMMAND_LEDGER_COMPACTION_LOCK_SUFFIX: &'static str = "";
     const EVENT_SELECT: &'static str = "event_name, event_version, payload, payload_codec, \
          payload_codec_version, metadata, sequence, recorded_at";
     const SNAPSHOT_SELECT: &'static str = "aggregate_type, aggregate_id, version, \
@@ -121,17 +138,39 @@ impl crate::sqlx_repo::repo::SqlxRepoBackend for Sqlite {
         builder.push_bind(epoch_secs);
     }
 
+    fn push_command_ledger_now(builder: &mut QueryBuilder<Sqlite>) {
+        builder.push("unixepoch('now','subsec')");
+    }
+
+    fn push_command_ledger_now_epoch(builder: &mut QueryBuilder<Sqlite>) {
+        builder.push("unixepoch('now','subsec')");
+    }
+
+    fn push_command_ledger_deadline(builder: &mut QueryBuilder<Sqlite>, duration: Duration) {
+        builder.push("(unixepoch('now','subsec') + ");
+        builder.push_bind(duration.as_secs_f64());
+        builder.push(")");
+    }
+
+    fn push_command_ledger_json(builder: &mut QueryBuilder<Sqlite>, json: &str) {
+        builder.push_bind(json);
+    }
+
     fn decode_timestamp(
         row: &SqliteRow,
         column: &'static str,
     ) -> Result<SystemTime, RepositoryError> {
-        system_time_from_storage(
-            row.try_get::<String, _>(column)
-                .map_err(|err| {
-                    repository_storage_error(&format!("decode {column} timestamp row"), err)
-                })?
-                .as_str(),
-        )
+        match row.try_get::<String, _>(column) {
+            Ok(value) => system_time_from_storage(&value),
+            Err(string_err) => {
+                let value = row.try_get::<f64, _>(column).map_err(|float_err| {
+                    RepositoryError::Model(format!(
+                        "decode {column} timestamp row failed as sqlite text ({string_err}) and real ({float_err})"
+                    ))
+                })?;
+                system_time_from_epoch_secs(value)
+            }
+        }
     }
 
     fn decode_optional_timestamp(
diff --git a/src/sqlx_repo/mod.rs b/src/sqlx_repo/mod.rs
index 207ad616..b6af4bcc 100644
--- a/src/sqlx_repo/mod.rs
+++ b/src/sqlx_repo/mod.rs
@@ -4,6 +4,8 @@ use crate::repository::RepositoryError;
 #[cfg(any(feature = "postgres", feature = "sqlite"))]
 use crate::table::TableStoreError;
 
+#[cfg(any(feature = "postgres", feature = "sqlite"))]
+pub(crate) mod projection_protocol;
 #[cfg(any(feature = "postgres", feature = "sqlite"))]
 pub(crate) mod read_model;
 #[cfg(any(feature = "postgres", feature = "sqlite"))]
@@ -196,7 +198,11 @@ pub(crate) fn read_model_storage_error(
     operation: &str,
     err: sqlx::Error,
 ) -> TableStoreError {
-    TableStoreError::Storage(format!("{backend} {operation} failed: {err}"))
+    TableStoreError::BackendStorage {
+        operation: format!("{backend} {operation}"),
+        retryable: is_sqlx_transient(&err),
+        message: err.to_string(),
+    }
 }
 
 #[cfg(test)]
diff --git a/src/sqlx_repo/projection_protocol/helpers.rs b/src/sqlx_repo/projection_protocol/helpers.rs
new file mode 100644
index 00000000..175aafde
--- /dev/null
+++ b/src/sqlx_repo/projection_protocol/helpers.rs
@@ -0,0 +1,106 @@
+use super::*;
+
+pub(super) fn protocol_storage_error<DB: SqlxRepoBackend>(
+    operation: &str,
+    error: sqlx::Error,
+) -> ProjectionProtocolError {
+    ProjectionProtocolError::Repository(repository_storage_error::<DB>(operation, error))
+}
+
+pub(super) fn corrupt_storage(message: impl Into<String>) -> ProjectionProtocolError {
+    ProjectionProtocolError::InvalidBatch(format!(
+        "corrupt projection protocol storage: {}",
+        message.into()
+    ))
+}
+
+pub(super) fn to_i64<DB: SqlxRepoBackend>(
+    value: u64,
+    field: &'static str,
+) -> Result<i64, ProjectionProtocolError> {
+    i64::try_from(value).map_err(|_| {
+        ProjectionProtocolError::Repository(RepositoryError::Model(format!(
+            "{} {field} value {value} exceeds signed bigint storage",
+            DB::BACKEND
+        )))
+    })
+}
+
+pub(super) fn from_i64<DB: SqlxRepoBackend>(
+    value: i64,
+    field: &'static str,
+) -> Result<u64, ProjectionProtocolError> {
+    u64::try_from(value)
+        .map_err(|_| corrupt_storage(format!("{} {field} value {value} is negative", DB::BACKEND)))
+}
+
+pub(super) fn digest_bytes(value: [u8; 32]) -> Vec<u8> {
+    value.to_vec()
+}
+
+pub(super) fn decode_digest(
+    value: Vec<u8>,
+    field: &'static str,
+) -> Result<[u8; 32], ProjectionProtocolError> {
+    value.try_into().map_err(|value: Vec<u8>| {
+        corrupt_storage(format!(
+            "{field} digest contains {} bytes instead of 32",
+            value.len()
+        ))
+    })
+}
+
+pub(super) fn verify_bytes(
+    actual: &[u8],
+    expected: &[u8],
+    field: &'static str,
+) -> Result<(), ProjectionProtocolError> {
+    if actual == expected {
+        Ok(())
+    } else {
+        Err(corrupt_storage(format!(
+            "{field} bytes do not match their hash lookup"
+        )))
+    }
+}
+
+pub(super) fn verify_digest(
+    actual: &[u8],
+    expected: [u8; 32],
+    field: &'static str,
+) -> Result<(), ProjectionProtocolError> {
+    verify_bytes(actual, &expected, field)
+}
+
+pub(super) async fn physical_row_exists_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    mutation: &TableMutation,
+) -> Result<bool, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let (schema, key) = match mutation {
+        TableMutation::UpsertRow(mutation) => (mutation.schema, &mutation.key),
+        TableMutation::PatchRow(mutation) => (mutation.schema, &mutation.key),
+        TableMutation::DeleteRow(mutation) => (mutation.schema, &mutation.key),
+    };
+    Ok(row_version_in_tx(tx, schema, key).await?.is_some())
+}
+
+pub(super) fn decode_change_kind(
+    value: &str,
+) -> Result<ProjectionChangeKind, ProjectionProtocolError> {
+    ProjectionChangeKind::from_storage_str(value)
+        .ok_or_else(|| corrupt_storage(format!("unknown projection change kind `{value}`")))
+}
+
+pub(super) fn decode_observation_kind(
+    value: &str,
+) -> Result<ProjectionObservationKind, ProjectionProtocolError> {
+    ProjectionObservationKind::from_storage_str(value)
+        .ok_or_else(|| corrupt_storage(format!("unknown projection observation kind `{value}`")))
+}
diff --git a/src/sqlx_repo/projection_protocol/identity.rs b/src/sqlx_repo/projection_protocol/identity.rs
new file mode 100644
index 00000000..40292979
--- /dev/null
+++ b/src/sqlx_repo/projection_protocol/identity.rs
@@ -0,0 +1,1030 @@
+use super::*;
+
+pub(super) fn ensure_active_input(
+    state: &PartitionState,
+    input: &TrustedProjectionInput,
+) -> Result<(), ProjectionProtocolError> {
+    if state.active_generation != input.generation {
+        return Err(ProjectionProtocolError::GenerationFenced {
+            expected: state.active_generation.get(),
+            actual: input.generation.get(),
+        });
+    }
+    if let Some(failure_id) = &state.stopped_failure_id {
+        return Err(ProjectionProtocolError::PartitionStopped {
+            failure_id: failure_id.clone(),
+        });
+    }
+    Ok(())
+}
+
+pub(super) fn verify_stored_change(
+    state: &PartitionState,
+    change: &ProjectionChangeCursor,
+) -> Result<(), ProjectionProtocolError> {
+    if change.epoch() != &state.change_epoch || change.position() > state.change_head {
+        return Err(corrupt_storage(
+            "stored projection outcome change is outside its partition head",
+        ));
+    }
+    Ok(())
+}
+
+pub(super) fn checkpoint_from_stored(
+    cursor_scope: &ProjectionInputCursor,
+    source_epoch: ProjectionEpoch,
+    source_position: u64,
+    change: ProjectionChangeCursor,
+    gap_free: bool,
+) -> Result<ProjectionCheckpoint, ProjectionProtocolError> {
+    ProjectionCheckpoint::new(
+        ProjectionInputCursor::new(
+            cursor_scope.topology().clone(),
+            cursor_scope.projection_partition().clone(),
+            cursor_scope.source().clone(),
+            source_epoch,
+            source_position,
+        )?,
+        change,
+        gap_free,
+    )
+    .map_err(ProjectionProtocolError::from)
+}
+
+pub(super) fn decode_stored_receipt<DB>(
+    row: &DB::Row,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+) -> Result<StoredReceipt, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let source_bytes: Vec<u8> = row
+        .try_get("source_bytes")
+        .map_err(|error| protocol_storage_error::<DB>("decode receipt source bytes", error))?;
+    let source_hash: Vec<u8> = row
+        .try_get("source_hash")
+        .map_err(|error| protocol_storage_error::<DB>("decode receipt source hash", error))?;
+    let source_partition_bytes: Vec<u8> =
+        row.try_get("source_partition_bytes").map_err(|error| {
+            protocol_storage_error::<DB>("decode receipt source partition bytes", error)
+        })?;
+    let source_partition_hash: Vec<u8> = row.try_get("source_partition_hash").map_err(|error| {
+        protocol_storage_error::<DB>("decode receipt source partition hash", error)
+    })?;
+    let source =
+        ProjectionSource::from_canonical_name_bytes(&source_bytes, source_partition_bytes.clone())?;
+    verify_digest(&source_hash, source.digest(), "projection receipt source")?;
+    verify_digest(
+        &source_partition_hash,
+        source.partition_digest(),
+        "projection receipt source partition",
+    )?;
+    let source_epoch: String = row
+        .try_get("source_epoch")
+        .map_err(|error| protocol_storage_error::<DB>("decode receipt source epoch", error))?;
+    let source_epoch = ProjectionEpoch::new(source_epoch)?;
+    let source_position = from_i64::<DB>(
+        row.try_get("source_position").map_err(|error| {
+            protocol_storage_error::<DB>("decode receipt source position", error)
+        })?,
+        "receipt source position",
+    )?;
+    let input_hash = decode_digest(
+        row.try_get("input_hash")
+            .map_err(|error| protocol_storage_error::<DB>("decode receipt input hash", error))?,
+        "projection input",
+    )?;
+    let message_id = row
+        .try_get("message_id")
+        .map_err(|error| protocol_storage_error::<DB>("decode receipt message ID", error))?;
+    let causation_id = row
+        .try_get("causation_id")
+        .map_err(|error| protocol_storage_error::<DB>("decode receipt causation ID", error))?;
+    let gap_free = match row
+        .try_get::<i64, _>("gap_free")
+        .map_err(|error| protocol_storage_error::<DB>("decode receipt gap-free flag", error))?
+    {
+        0 => false,
+        1 => true,
+        value => {
+            return Err(corrupt_storage(format!(
+                "receipt gap-free flag contains invalid value {value}"
+            )))
+        }
+    };
+    let outcome_kind: String = row
+        .try_get("outcome_kind")
+        .map_err(|error| protocol_storage_error::<DB>("decode receipt outcome", error))?;
+    if outcome_kind != "applied" && outcome_kind != "failed" {
+        return Err(corrupt_storage(format!(
+            "unknown projection receipt outcome `{outcome_kind}`"
+        )));
+    }
+    let failure_id: Option<String> = row
+        .try_get("failure_id")
+        .map_err(|error| protocol_storage_error::<DB>("decode receipt failure ID", error))?;
+    if (outcome_kind == "applied") != failure_id.is_none() {
+        return Err(corrupt_storage(
+            "projection receipt outcome/failure shape is inconsistent",
+        ));
+    }
+    let change_epoch: String = row
+        .try_get("change_epoch")
+        .map_err(|error| protocol_storage_error::<DB>("decode receipt change epoch", error))?;
+    let change_position = from_i64::<DB>(
+        row.try_get("change_position").map_err(|error| {
+            protocol_storage_error::<DB>("decode receipt change position", error)
+        })?,
+        "receipt change position",
+    )?;
+    let change = ProjectionChangeCursor::new(
+        topology.clone(),
+        partition.clone(),
+        ProjectionEpoch::new(change_epoch)?,
+        change_position,
+    )?;
+    Ok(StoredReceipt {
+        source_bytes,
+        source_hash,
+        source_partition_bytes,
+        source_partition_hash,
+        source_epoch,
+        source_position,
+        input_fingerprint: ProjectionInputFingerprint::from_digest(input_hash),
+        message_id,
+        causation_id,
+        gap_free,
+        outcome_kind,
+        change,
+    })
+}
+
+pub(super) fn receipt_matches_input(
+    receipt: &StoredReceipt,
+    input: &TrustedProjectionInput,
+) -> bool {
+    let source = input.cursor.source();
+    receipt.source_bytes == source.canonical_name_bytes()
+        && receipt.source_hash == digest_bytes(source.digest())
+        && receipt.source_partition_bytes == source.canonical_partition_bytes()
+        && receipt.source_partition_hash == digest_bytes(source.partition_digest())
+        && receipt.source_epoch == *input.cursor.epoch()
+        && receipt.source_position == input.cursor.position()
+        && receipt.input_fingerprint == input.fingerprint
+        && receipt.message_id == input.message_id
+        && receipt.causation_id == input.causation_id
+        && receipt.gap_free == input.gap_free
+}
+
+pub(super) fn decode_stored_input_identity<DB>(
+    row: &DB::Row,
+) -> Result<StoredInputIdentity, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let partition_bytes: Vec<u8> = row.try_get("partition_bytes").map_err(|error| {
+        protocol_storage_error::<DB>("decode input identity partition bytes", error)
+    })?;
+    let partition_hash: Vec<u8> = row.try_get("partition_hash").map_err(|error| {
+        protocol_storage_error::<DB>("decode input identity partition hash", error)
+    })?;
+    let decoded_partition = ProjectionPartition::new(partition_bytes.clone())?;
+    verify_digest(
+        &partition_hash,
+        decoded_partition.digest(),
+        "projection input identity partition",
+    )?;
+    let source_bytes: Vec<u8> = row.try_get("source_bytes").map_err(|error| {
+        protocol_storage_error::<DB>("decode input identity source bytes", error)
+    })?;
+    let source_hash: Vec<u8> = row.try_get("source_hash").map_err(|error| {
+        protocol_storage_error::<DB>("decode input identity source hash", error)
+    })?;
+    let source_partition_bytes: Vec<u8> =
+        row.try_get("source_partition_bytes").map_err(|error| {
+            protocol_storage_error::<DB>("decode input identity source partition bytes", error)
+        })?;
+    let source_partition_hash: Vec<u8> = row.try_get("source_partition_hash").map_err(|error| {
+        protocol_storage_error::<DB>("decode input identity source partition hash", error)
+    })?;
+    let source =
+        ProjectionSource::from_canonical_name_bytes(&source_bytes, source_partition_bytes.clone())?;
+    verify_digest(
+        &source_hash,
+        source.digest(),
+        "projection input identity source",
+    )?;
+    verify_digest(
+        &source_partition_hash,
+        source.partition_digest(),
+        "projection input identity source partition",
+    )?;
+    let source_epoch: String = row
+        .try_get("source_epoch")
+        .map_err(|error| protocol_storage_error::<DB>("decode input identity epoch", error))?;
+    let source_position = from_i64::<DB>(
+        row.try_get("source_position").map_err(|error| {
+            protocol_storage_error::<DB>("decode input identity position", error)
+        })?,
+        "projection input identity position",
+    )?;
+    let input_hash = decode_digest(
+        row.try_get("input_hash").map_err(|error| {
+            protocol_storage_error::<DB>("decode input identity fingerprint", error)
+        })?,
+        "projection input identity",
+    )?;
+    let gap_free = match row
+        .try_get::<i64, _>("gap_free")
+        .map_err(|error| protocol_storage_error::<DB>("decode input identity gap flag", error))?
+    {
+        0 => false,
+        1 => true,
+        value => {
+            return Err(corrupt_storage(format!(
+                "input identity gap-free flag contains invalid value {value}"
+            )))
+        }
+    };
+    Ok(StoredInputIdentity {
+        partition_bytes,
+        partition_hash,
+        source_bytes,
+        source_hash,
+        source_partition_bytes,
+        source_partition_hash,
+        source_epoch: ProjectionEpoch::new(source_epoch)?,
+        source_position,
+        input_fingerprint: ProjectionInputFingerprint::from_digest(input_hash),
+        message_id: row.try_get("message_id").map_err(|error| {
+            protocol_storage_error::<DB>("decode input identity message ID", error)
+        })?,
+        causation_id: row.try_get("causation_id").map_err(|error| {
+            protocol_storage_error::<DB>("decode input identity causation ID", error)
+        })?,
+        gap_free,
+    })
+}
+
+pub(super) fn input_identity_cursor_matches(
+    identity: &StoredInputIdentity,
+    input: &TrustedProjectionInput,
+) -> bool {
+    let source = input.cursor.source();
+    identity.partition_bytes == input.cursor.projection_partition().canonical_bytes()
+        && identity.partition_hash == digest_bytes(input.cursor.projection_partition().digest())
+        && identity.source_bytes == source.canonical_name_bytes()
+        && identity.source_hash == digest_bytes(source.digest())
+        && identity.source_partition_bytes == source.canonical_partition_bytes()
+        && identity.source_partition_hash == digest_bytes(source.partition_digest())
+        && identity.source_epoch == *input.cursor.epoch()
+        && identity.source_position == input.cursor.position()
+}
+
+pub(super) fn input_identity_matches(
+    identity: &StoredInputIdentity,
+    input: &TrustedProjectionInput,
+) -> bool {
+    input_identity_cursor_matches(identity, input)
+        && identity.input_fingerprint == input.fingerprint
+        && identity.message_id == input.message_id
+        && identity.causation_id == input.causation_id
+        && identity.gap_free == input.gap_free
+}
+
+pub(super) async fn input_identity_by_cursor_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+) -> Result<Option<StoredInputIdentity>, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = input.cursor.topology().digest();
+    let partition_hash = input.cursor.projection_partition().digest();
+    let source_hash = input.cursor.source().digest();
+    let source_partition_hash = input.cursor.source().partition_digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT partition.partition_bytes, identity.partition_hash, identity.source_bytes, \
+         identity.source_hash, identity.source_partition_bytes, identity.source_partition_hash, \
+         identity.source_epoch, identity.source_position, identity.input_hash, \
+         identity.message_id, identity.causation_id, identity.gap_free \
+         FROM projection_input_identities identity JOIN projection_partitions partition \
+         ON partition.topology_hash = identity.topology_hash \
+         AND partition.partition_hash = identity.partition_hash \
+         WHERE identity.topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND identity.partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(" AND identity.source_hash = ");
+    builder.push_bind(source_hash.as_slice());
+    builder.push(" AND identity.source_partition_hash = ");
+    builder.push_bind(source_partition_hash.as_slice());
+    builder.push(" AND identity.source_epoch = ");
+    builder.push_bind(input.cursor.epoch().as_str());
+    builder.push(" AND identity.source_position = ");
+    builder.push_bind(to_i64::<DB>(
+        input.cursor.position(),
+        "projection input identity position",
+    )?);
+    let row = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| {
+            protocol_storage_error::<DB>("load projection input identity by cursor", error)
+        })?;
+    row.map(|row| decode_stored_input_identity::<DB>(&row))
+        .transpose()
+}
+
+pub(super) async fn input_identity_by_message_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+) -> Result<Option<StoredInputIdentity>, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = input.cursor.topology().digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT partition.partition_bytes, identity.partition_hash, identity.source_bytes, \
+         identity.source_hash, identity.source_partition_bytes, identity.source_partition_hash, \
+         identity.source_epoch, identity.source_position, identity.input_hash, \
+         identity.message_id, identity.causation_id, identity.gap_free \
+         FROM projection_input_identities identity JOIN projection_partitions partition \
+         ON partition.topology_hash = identity.topology_hash \
+         AND partition.partition_hash = identity.partition_hash \
+         WHERE identity.topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND identity.message_id = ");
+    builder.push_bind(input.message_id.as_str());
+    let row = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| {
+            protocol_storage_error::<DB>("load projection input identity by message", error)
+        })?;
+    row.map(|row| decode_stored_input_identity::<DB>(&row))
+        .transpose()
+}
+
+pub(super) async fn receipt_by_message_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+) -> Result<Option<StoredReceipt>, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let generation = to_i64::<DB>(input.generation.get(), "projection generation")?;
+    let topology_hash = input.cursor.topology().digest();
+    let partition_hash = input.cursor.projection_partition().digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT source_bytes, source_hash, source_partition_bytes, source_partition_hash, \
+         source_epoch, source_position, input_hash, message_id, causation_id, outcome_kind, failure_id, \
+         gap_free, change_epoch, change_position FROM projection_input_receipts WHERE topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(" AND generation = ");
+    builder.push_bind(generation);
+    builder.push(" AND message_id = ");
+    builder.push_bind(input.message_id.as_str());
+    let row = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("load projection message receipt", error))?;
+    row.map(|row| {
+        decode_stored_receipt::<DB>(
+            &row,
+            input.cursor.topology(),
+            input.cursor.projection_partition(),
+        )
+    })
+    .transpose()
+}
+
+pub(super) async fn receipt_by_cursor_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+) -> Result<Option<StoredReceipt>, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let generation = to_i64::<DB>(input.generation.get(), "projection generation")?;
+    let position = to_i64::<DB>(input.cursor.position(), "projection input position")?;
+    let topology_hash = input.cursor.topology().digest();
+    let partition_hash = input.cursor.projection_partition().digest();
+    let source_hash = input.cursor.source().digest();
+    let source_partition_hash = input.cursor.source().partition_digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT source_bytes, source_hash, source_partition_bytes, source_partition_hash, \
+         source_epoch, source_position, input_hash, message_id, causation_id, outcome_kind, failure_id, \
+         gap_free, change_epoch, change_position FROM projection_input_receipts WHERE topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(" AND generation = ");
+    builder.push_bind(generation);
+    builder.push(" AND source_hash = ");
+    builder.push_bind(source_hash.as_slice());
+    builder.push(" AND source_partition_hash = ");
+    builder.push_bind(source_partition_hash.as_slice());
+    builder.push(" AND source_epoch = ");
+    builder.push_bind(input.cursor.epoch().as_str());
+    builder.push(" AND source_position = ");
+    builder.push_bind(position);
+    let row = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("load projection cursor receipt", error))?;
+    row.map(|row| {
+        decode_stored_receipt::<DB>(
+            &row,
+            input.cursor.topology(),
+            input.cursor.projection_partition(),
+        )
+    })
+    .transpose()
+}
+
+pub(super) async fn current_input_cursor_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+) -> Result<Option<StoredCursor>, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let generation = to_i64::<DB>(input.generation.get(), "projection generation")?;
+    let topology_hash = input.cursor.topology().digest();
+    let partition_hash = input.cursor.projection_partition().digest();
+    let source_hash = input.cursor.source().digest();
+    let source_partition_hash = input.cursor.source().partition_digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT source_bytes, source_hash, source_partition_bytes, source_partition_hash, \
+         source_epoch, source_position, input_hash, message_id, causation_id, \
+         gap_free, change_epoch, change_position FROM projection_input_cursors WHERE topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(" AND source_hash = ");
+    builder.push_bind(source_hash.as_slice());
+    builder.push(" AND source_partition_hash = ");
+    builder.push_bind(source_partition_hash.as_slice());
+    builder.push(" AND generation = ");
+    builder.push_bind(generation);
+    let Some(row) = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("load projection input cursor", error))?
+    else {
+        return Ok(None);
+    };
+
+    let source_bytes: Vec<u8> = row
+        .try_get("source_bytes")
+        .map_err(|error| protocol_storage_error::<DB>("decode cursor source bytes", error))?;
+    let source_digest: Vec<u8> = row
+        .try_get("source_hash")
+        .map_err(|error| protocol_storage_error::<DB>("decode cursor source hash", error))?;
+    let source_partition_bytes: Vec<u8> =
+        row.try_get("source_partition_bytes").map_err(|error| {
+            protocol_storage_error::<DB>("decode cursor source partition bytes", error)
+        })?;
+    let source_partition_digest: Vec<u8> =
+        row.try_get("source_partition_hash").map_err(|error| {
+            protocol_storage_error::<DB>("decode cursor source partition hash", error)
+        })?;
+    verify_bytes(
+        &source_bytes,
+        &input.cursor.source().canonical_name_bytes(),
+        "projection cursor source",
+    )?;
+    verify_digest(
+        &source_digest,
+        input.cursor.source().digest(),
+        "projection cursor source",
+    )?;
+    verify_bytes(
+        &source_partition_bytes,
+        input.cursor.source().canonical_partition_bytes(),
+        "projection cursor source partition",
+    )?;
+    verify_digest(
+        &source_partition_digest,
+        input.cursor.source().partition_digest(),
+        "projection cursor source partition",
+    )?;
+    let source_epoch: String = row
+        .try_get("source_epoch")
+        .map_err(|error| protocol_storage_error::<DB>("decode cursor source epoch", error))?;
+    let source_position = from_i64::<DB>(
+        row.try_get("source_position").map_err(|error| {
+            protocol_storage_error::<DB>("decode cursor source position", error)
+        })?,
+        "projection input position",
+    )?;
+    let input_hash = decode_digest(
+        row.try_get("input_hash")
+            .map_err(|error| protocol_storage_error::<DB>("decode cursor input hash", error))?,
+        "projection input",
+    )?;
+    let change_epoch: String = row
+        .try_get("change_epoch")
+        .map_err(|error| protocol_storage_error::<DB>("decode cursor change epoch", error))?;
+    let change_position = from_i64::<DB>(
+        row.try_get("change_position").map_err(|error| {
+            protocol_storage_error::<DB>("decode cursor change position", error)
+        })?,
+        "projection change position",
+    )?;
+    Ok(Some(StoredCursor {
+        source_epoch: ProjectionEpoch::new(source_epoch)?,
+        source_position,
+        input_fingerprint: ProjectionInputFingerprint::from_digest(input_hash),
+        message_id: row
+            .try_get("message_id")
+            .map_err(|error| protocol_storage_error::<DB>("decode cursor message ID", error))?,
+        causation_id: row
+            .try_get("causation_id")
+            .map_err(|error| protocol_storage_error::<DB>("decode cursor causation ID", error))?,
+        gap_free: match row
+            .try_get::<i64, _>("gap_free")
+            .map_err(|error| protocol_storage_error::<DB>("decode cursor gap-free flag", error))?
+        {
+            0 => false,
+            1 => true,
+            value => {
+                return Err(corrupt_storage(format!(
+                    "cursor gap-free flag contains invalid value {value}"
+                )))
+            }
+        },
+        change: ProjectionChangeCursor::new(
+            input.cursor.topology().clone(),
+            input.cursor.projection_partition().clone(),
+            ProjectionEpoch::new(change_epoch)?,
+            change_position,
+        )?,
+    }))
+}
+
+pub(super) fn stored_cursors_match(left: &StoredCursor, right: &StoredCursor) -> bool {
+    left.source_epoch == right.source_epoch
+        && left.source_position == right.source_position
+        && left.input_fingerprint == right.input_fingerprint
+        && left.message_id == right.message_id
+        && left.causation_id == right.causation_id
+        && left.gap_free == right.gap_free
+        && left.change == right.change
+}
+
+pub(super) async fn verify_inherited_cursor_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+    current: &StoredCursor,
+) -> Result<bool, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = input.cursor.topology().digest();
+    let partition_hash = input.cursor.projection_partition().digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT retry_of_generation FROM projection_generations WHERE topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(" AND generation = ");
+    builder.push_bind(to_i64::<DB>(
+        input.generation.get(),
+        "projection generation",
+    )?);
+    let row = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| {
+            protocol_storage_error::<DB>("load projection repair generation lineage", error)
+        })?
+        .ok_or_else(|| {
+            corrupt_storage(format!(
+                "active projection generation {} is missing",
+                input.generation.get()
+            ))
+        })?;
+    let parent: Option<i64> = row.try_get("retry_of_generation").map_err(|error| {
+        protocol_storage_error::<DB>("decode projection repair generation lineage", error)
+    })?;
+    let Some(parent) = parent else {
+        return Ok(false);
+    };
+    let parent = ProjectionGeneration::new(from_i64::<DB>(
+        parent,
+        "projection repair parent generation",
+    )?)?;
+    let mut parent_input = input.clone();
+    parent_input.generation = parent;
+    let parent_cursor = current_input_cursor_in_tx(tx, &parent_input)
+        .await?
+        .ok_or_else(|| {
+            corrupt_storage("projection repair generation contains a cursor absent from its parent")
+        })?;
+    if !stored_cursors_match(current, &parent_cursor) {
+        return Err(corrupt_storage(
+            "projection repair generation contains a cursor changed from its parent",
+        ));
+    }
+    Ok(true)
+}
+
+pub(super) async fn validate_source_capability_in_tx_mode<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+    register_missing: bool,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = input.cursor.topology().digest();
+    let partition_hash = input.cursor.projection_partition().digest();
+    let source_hash = input.cursor.source().digest();
+    let source_partition_hash = input.cursor.source().partition_digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT source_bytes, source_hash, source_partition_bytes, source_partition_hash, gap_free \
+         FROM projection_source_capabilities WHERE topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(" AND source_hash = ");
+    builder.push_bind(source_hash.as_slice());
+    builder.push(" AND source_partition_hash = ");
+    builder.push_bind(source_partition_hash.as_slice());
+    builder.push(" LIMIT 1");
+    let row = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| {
+            protocol_storage_error::<DB>("load projection source capability", error)
+        })?;
+    let Some(row) = row else {
+        if !register_missing {
+            return Ok(());
+        }
+        let source = input.cursor.source();
+        let source_bytes = source.canonical_name_bytes();
+        let source_hash = source.digest();
+        let source_partition_hash = source.partition_digest();
+        let mut insert = QueryBuilder::<DB>::new(
+            "INSERT INTO projection_source_capabilities \
+             (topology_hash, partition_hash, source_bytes, source_hash, source_partition_bytes, \
+             source_partition_hash, gap_free) VALUES (",
+        );
+        insert.push_bind(topology_hash.as_slice());
+        insert.push(", ");
+        insert.push_bind(partition_hash.as_slice());
+        insert.push(", ");
+        insert.push_bind(source_bytes.as_slice());
+        insert.push(", ");
+        insert.push_bind(source_hash.as_slice());
+        insert.push(", ");
+        insert.push_bind(source.canonical_partition_bytes());
+        insert.push(", ");
+        insert.push_bind(source_partition_hash.as_slice());
+        insert.push(", ");
+        insert.push_bind(i64::from(input.gap_free));
+        insert.push(
+            ") ON CONFLICT \
+             (topology_hash, partition_hash, source_hash, source_partition_hash) DO NOTHING",
+        );
+        let result = insert.build().execute(&mut **tx).await.map_err(|error| {
+            protocol_storage_error::<DB>("register projection source capability", error)
+        })?;
+        if DB::rows_affected(&result) != 1 {
+            return Err(corrupt_storage(
+                "projection source capability changed while its partition lock was held",
+            ));
+        }
+        return Ok(());
+    };
+    let source_bytes: Vec<u8> = row
+        .try_get("source_bytes")
+        .map_err(|error| protocol_storage_error::<DB>("decode capability source bytes", error))?;
+    let source_digest: Vec<u8> = row
+        .try_get("source_hash")
+        .map_err(|error| protocol_storage_error::<DB>("decode capability source hash", error))?;
+    let source_partition_bytes: Vec<u8> =
+        row.try_get("source_partition_bytes").map_err(|error| {
+            protocol_storage_error::<DB>("decode capability source partition bytes", error)
+        })?;
+    let source_partition_digest: Vec<u8> =
+        row.try_get("source_partition_hash").map_err(|error| {
+            protocol_storage_error::<DB>("decode capability source partition hash", error)
+        })?;
+    verify_bytes(
+        &source_bytes,
+        &input.cursor.source().canonical_name_bytes(),
+        "projection capability source",
+    )?;
+    verify_digest(
+        &source_digest,
+        input.cursor.source().digest(),
+        "projection capability source",
+    )?;
+    verify_bytes(
+        &source_partition_bytes,
+        input.cursor.source().canonical_partition_bytes(),
+        "projection capability source partition",
+    )?;
+    verify_digest(
+        &source_partition_digest,
+        input.cursor.source().partition_digest(),
+        "projection capability source partition",
+    )?;
+    let gap_free = match row.try_get::<i64, _>("gap_free").map_err(|error| {
+        protocol_storage_error::<DB>("decode projection source capability", error)
+    })? {
+        0 => false,
+        1 => true,
+        value => {
+            return Err(corrupt_storage(format!(
+                "source capability gap-free flag contains invalid value {value}"
+            )))
+        }
+    };
+    if gap_free != input.gap_free {
+        return Err(ProjectionProtocolError::InputCorruption);
+    }
+    Ok(())
+}
+
+pub(super) async fn validate_input_identity_in_tx_mode<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+    register_missing_source_capability: bool,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    validate_source_capability_in_tx_mode(tx, input, register_missing_source_capability).await?;
+    let exact_identity = input_identity_by_cursor_in_tx(tx, input).await?;
+    if let Some(identity) = &exact_identity {
+        if !input_identity_cursor_matches(identity, input) {
+            return Err(corrupt_storage(
+                "projection input identity hash lookup resolved different canonical source bytes",
+            ));
+        }
+        if !input_identity_matches(identity, input) {
+            return Err(ProjectionProtocolError::InputCorruption);
+        }
+    }
+    if let Some(identity) = input_identity_by_message_in_tx(tx, input).await? {
+        if !input_identity_cursor_matches(&identity, input) {
+            return Err(ProjectionProtocolError::MessageIdReuse {
+                message_id: input.message_id.clone(),
+            });
+        }
+        if !input_identity_matches(&identity, input) {
+            return Err(ProjectionProtocolError::InputCorruption);
+        }
+        if exact_identity.is_none() {
+            return Err(corrupt_storage(
+                "projection message identity exists without its exact cursor identity",
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(super) async fn validate_input_identity_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    validate_input_identity_in_tx_mode(tx, input, true).await
+}
+
+pub(super) async fn validate_input_identity_read_only_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    validate_input_identity_in_tx_mode(tx, input, false).await
+}
+
+pub(super) async fn classify_validated_input_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+    state: &PartitionState,
+) -> Result<InputDisposition, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    if let Some(receipt) = receipt_by_cursor_in_tx(tx, input).await? {
+        verify_stored_change(state, &receipt.change)?;
+        if receipt.source_bytes != input.cursor.source().canonical_name_bytes()
+            || receipt.source_hash != digest_bytes(input.cursor.source().digest())
+            || receipt.source_partition_bytes != input.cursor.source().canonical_partition_bytes()
+            || receipt.source_partition_hash
+                != digest_bytes(input.cursor.source().partition_digest())
+        {
+            return Err(corrupt_storage(
+                "projection cursor receipt hash lookup resolved different canonical bytes",
+            ));
+        }
+        if receipt.input_fingerprint != input.fingerprint
+            || receipt.message_id != input.message_id
+            || receipt.causation_id != input.causation_id
+            || receipt.gap_free != input.gap_free
+        {
+            return Err(ProjectionProtocolError::InputCorruption);
+        }
+        if receipt.outcome_kind != "applied" {
+            return Err(corrupt_storage(
+                "failed cursor receipt exists without a stopped partition",
+            ));
+        }
+        return Ok(InputDisposition::Duplicate(checkpoint_from_stored(
+            &input.cursor,
+            receipt.source_epoch,
+            receipt.source_position,
+            receipt.change,
+            receipt.gap_free,
+        )?));
+    }
+
+    if let Some(receipt) = receipt_by_message_in_tx(tx, input).await? {
+        verify_stored_change(state, &receipt.change)?;
+        if !receipt_matches_input(&receipt, input) {
+            return Err(ProjectionProtocolError::MessageIdReuse {
+                message_id: input.message_id.clone(),
+            });
+        }
+        if receipt.outcome_kind != "applied" {
+            return Err(corrupt_storage(
+                "failed input receipt exists without a stopped partition",
+            ));
+        }
+        return Ok(InputDisposition::Duplicate(checkpoint_from_stored(
+            &input.cursor,
+            receipt.source_epoch,
+            receipt.source_position,
+            receipt.change,
+            receipt.gap_free,
+        )?));
+    }
+
+    let Some(previous) = current_input_cursor_in_tx(tx, input).await? else {
+        return Ok(InputDisposition::New);
+    };
+    verify_stored_change(state, &previous.change)?;
+    if previous.gap_free != input.gap_free {
+        return Err(ProjectionProtocolError::InputCorruption);
+    }
+    if previous.source_epoch != *input.cursor.epoch() {
+        return Err(ProjectionProtocolError::IncomparableInput);
+    }
+    if input.cursor.position() < previous.source_position {
+        return Ok(InputDisposition::Stale(checkpoint_from_stored(
+            &input.cursor,
+            previous.source_epoch,
+            previous.source_position,
+            previous.change,
+            previous.gap_free,
+        )?));
+    }
+    if input.cursor.position() == previous.source_position {
+        if previous.input_fingerprint != input.fingerprint
+            || previous.message_id != input.message_id
+            || previous.causation_id != input.causation_id
+            || previous.gap_free != input.gap_free
+        {
+            return Err(ProjectionProtocolError::InputCorruption);
+        }
+        if !verify_inherited_cursor_in_tx(tx, input, &previous).await? {
+            return Err(corrupt_storage(
+                "projection input cursor has no receipt and was not inherited by repair",
+            ));
+        }
+        return Ok(InputDisposition::Duplicate(checkpoint_from_stored(
+            &input.cursor,
+            previous.source_epoch,
+            previous.source_position,
+            previous.change,
+            previous.gap_free,
+        )?));
+    }
+    if input.gap_free
+        && input.cursor.position()
+            != checked_next(previous.source_position, "gap-free projection input")?
+    {
+        return Err(ProjectionProtocolError::IncomparableInput);
+    }
+    Ok(InputDisposition::New)
+}
diff --git a/src/sqlx_repo/projection_protocol/locks.rs b/src/sqlx_repo/projection_protocol/locks.rs
new file mode 100644
index 00000000..810f6e56
--- /dev/null
+++ b/src/sqlx_repo/projection_protocol/locks.rs
@@ -0,0 +1,101 @@
+use super::*;
+
+pub(crate) const PROJECTION_CHANGE_NOTIFY_TABLE: &str = "projection_changes";
+
+/// Reject ordinary/raw table writes once a model-wide causal owner exists.
+///
+/// Both this path and `register_projection_models` first acquire the same
+/// durable per-table ownership fence in sorted order. The marker check and all
+/// physical writes remain inside that transaction, so an absent marker cannot
+/// race a first legacy row into a newly causal-owned table.
+pub(crate) async fn reject_causal_table_writes_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    tables: &BTreeSet<String>,
+) -> Result<(), TableStoreError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+{
+    lock_projection_table_ownership_fences_in_tx(tx, tables).await?;
+    for table in tables {
+        let mut builder = QueryBuilder::<DB>::new(
+            "SELECT table_name FROM projection_causal_tables WHERE table_name = ",
+        );
+        builder.push_bind(table.as_str());
+        builder.push(" LIMIT 1");
+        let row = builder
+            .build()
+            .fetch_optional(&mut **tx)
+            .await
+            .map_err(|error| {
+                crate::sqlx_repo::read_model_storage_error(
+                    DB::BACKEND,
+                    "check causal projection ownership",
+                    error,
+                )
+            })?;
+        if row.is_some() {
+            return Err(TableStoreError::CausalWriteRequired {
+                table: table.clone(),
+            });
+        }
+    }
+    Ok(())
+}
+
+pub(super) async fn lock_projection_table_ownership_fences_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    tables: &BTreeSet<String>,
+) -> Result<(), TableStoreError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+{
+    // BTreeSet iteration is deterministic, preventing multi-table writers and
+    // registration batches from deadlocking on opposite lock orders.
+    for table in tables {
+        let mut insert = QueryBuilder::<DB>::new(
+            "INSERT INTO projection_table_ownership_fences (table_name) VALUES (",
+        );
+        insert.push_bind(table.as_str());
+        insert.push(") ON CONFLICT (table_name) DO NOTHING");
+        insert.build().execute(&mut **tx).await.map_err(|error| {
+            crate::sqlx_repo::read_model_storage_error(
+                DB::BACKEND,
+                "acquire causal projection ownership fence",
+                error,
+            )
+        })?;
+
+        let mut lock = QueryBuilder::<DB>::new(
+            "SELECT table_name FROM projection_table_ownership_fences WHERE table_name = ",
+        );
+        lock.push_bind(table.as_str());
+        if DB::BACKEND == "postgres" {
+            lock.push(" FOR UPDATE");
+        }
+        if lock
+            .build()
+            .fetch_optional(&mut **tx)
+            .await
+            .map_err(|error| {
+                crate::sqlx_repo::read_model_storage_error(
+                    DB::BACKEND,
+                    "lock causal projection ownership fence",
+                    error,
+                )
+            })?
+            .is_none()
+        {
+            return Err(TableStoreError::Storage(format!(
+                "{} causal projection ownership fence `{table}` disappeared",
+                DB::BACKEND
+            )));
+        }
+    }
+    Ok(())
+}
diff --git a/src/sqlx_repo/projection_protocol/mod.rs b/src/sqlx_repo/projection_protocol/mod.rs
new file mode 100644
index 00000000..1f453c9a
--- /dev/null
+++ b/src/sqlx_repo/projection_protocol/mod.rs
@@ -0,0 +1,76 @@
+//! Generic SQLx persistence for the durable projection protocol.
+//!
+//! SQLite and PostgreSQL share the same state machine and SQL shape. Every
+//! mutating protocol operation first takes a portable partition lock by
+//! performing a no-op upsert on `projection_partitions`; all semantic
+//! decisions then happen before statements that could raise a constraint
+//! error, because PostgreSQL aborts a transaction after such an error.
+
+#![expect(
+    clippy::manual_async_fn,
+    reason = "trait impls return impl Future + Send to preserve Send bounds"
+)]
+
+use std::collections::{BTreeSet, HashMap};
+use std::future::Future;
+use std::pin::Pin;
+
+use sqlx::{Encode, Executor, IntoArguments, Pool, QueryBuilder, Row, Transaction, Type};
+
+use crate::projection_protocol::{
+    change_kind_for_mutation, checked_next, table_model_name, ProjectionChange,
+    ProjectionChangeCursor, ProjectionChangeKind, ProjectionChangeRead, ProjectionChangeRetention,
+    ProjectionCheckpoint, ProjectionCommitBatch, ProjectionCommitOutcome, ProjectionCommitResult,
+    ProjectionEpoch, ProjectionFailure, ProjectionFailureBatch, ProjectionFailureLocation,
+    ProjectionGeneration, ProjectionInputCursor, ProjectionInputDisposition,
+    ProjectionInputFingerprint, ProjectionLiveRecordBatch, ProjectionLiveRecordBatchRequest,
+    ProjectionModelOwnership, ProjectionMutationKind, ProjectionObligationEvidence,
+    ProjectionObligationEvidenceBatch, ProjectionObligationEvidenceBatchRequest,
+    ProjectionObservation, ProjectionObservationKind, ProjectionObservationTarget,
+    ProjectionPartition, ProjectionPartitionRuntimeState, ProjectionPartitionSnapshot,
+    ProjectionPendingRetry, ProjectionProtocolError, ProjectionProtocolStore,
+    ProjectionQuerySnapshot, ProjectionQuerySnapshotBatch, ProjectionQuerySnapshotBatchRequest,
+    ProjectionQuerySnapshotRequest, ProjectionRecordExpectation, ProjectionRecordMetadata,
+    ProjectionRecordScope, ProjectionSource, ProjectorTopologyId, RecordRevision,
+    SameTransactionProjectionBatch, SameTransactionProjectionEvidence, TrustedProjectionInput,
+};
+use crate::repository::RepositoryError;
+use crate::sqlx_repo::read_model::{
+    apply_read_model_write_plan_in_tx, push_key_predicates, quote_identifier, row_version_in_tx,
+    validate_sql_write_plan, validate_values_match_key, version_column,
+};
+use crate::sqlx_repo::repo::{repository_storage_error, SqlxRepoBackend, SqlxRepository};
+use crate::table::{
+    validate_row_values, RowValues, TableMutation, TableStoreError, TableWritePlan,
+};
+
+mod helpers;
+mod identity;
+mod locks;
+mod partitions;
+mod reads;
+mod store_impl;
+mod types;
+mod writes;
+
+use helpers::*;
+use identity::*;
+use locks::*;
+pub(crate) use locks::{reject_causal_table_writes_in_tx, PROJECTION_CHANGE_NOTIFY_TABLE};
+pub(crate) use partitions::read_projection_partition_snapshot_in_executor;
+use partitions::*;
+use reads::*;
+pub(crate) use reads::{
+    apply_same_transaction_projection_in_tx, read_projection_changes_in_executor,
+    read_projection_live_record_batch_in_executor,
+    read_projection_obligation_evidence_batch_in_executor,
+    read_projection_query_snapshot_in_executor, with_projection_read_snapshot,
+};
+use types::*;
+use writes::*;
+
+#[cfg(all(test, feature = "sqlite"))]
+include!("tests.rs");
+
+#[cfg(all(test, feature = "postgres"))]
+include!("postgres_tests.rs");
diff --git a/src/sqlx_repo/projection_protocol/partitions.rs b/src/sqlx_repo/projection_protocol/partitions.rs
new file mode 100644
index 00000000..d6c718ba
--- /dev/null
+++ b/src/sqlx_repo/projection_protocol/partitions.rs
@@ -0,0 +1,564 @@
+use super::*;
+
+pub(super) fn decode_partition_row<DB>(
+    row: &DB::Row,
+    topology: &ProjectorTopologyId,
+    partition: &crate::projection_protocol::ProjectionPartition,
+) -> Result<PartitionState, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_bytes: Vec<u8> = row
+        .try_get("topology_bytes")
+        .map_err(|error| protocol_storage_error::<DB>("decode projection topology bytes", error))?;
+    let partition_bytes: Vec<u8> = row.try_get("partition_bytes").map_err(|error| {
+        protocol_storage_error::<DB>("decode projection partition bytes", error)
+    })?;
+    verify_bytes(
+        &topology_bytes,
+        &topology.canonical_bytes(),
+        "projector topology",
+    )?;
+    verify_bytes(
+        &partition_bytes,
+        partition.canonical_bytes(),
+        "projection partition",
+    )?;
+
+    let active_generation = ProjectionGeneration::new(from_i64::<DB>(
+        row.try_get("active_generation").map_err(|error| {
+            protocol_storage_error::<DB>("decode projection active generation", error)
+        })?,
+        "projection active generation",
+    )?)?;
+    let change_epoch: String = row
+        .try_get("change_epoch")
+        .map_err(|error| protocol_storage_error::<DB>("decode projection change epoch", error))?;
+    let change_epoch = ProjectionEpoch::new(change_epoch)?;
+    let change_head = from_i64::<DB>(
+        row.try_get("change_head").map_err(|error| {
+            protocol_storage_error::<DB>("decode projection change head", error)
+        })?,
+        "projection change head",
+    )?;
+    let compacted_through = from_i64::<DB>(
+        row.try_get("compacted_through").map_err(|error| {
+            protocol_storage_error::<DB>("decode projection compaction watermark", error)
+        })?,
+        "projection compaction watermark",
+    )?;
+    if compacted_through > change_head {
+        return Err(corrupt_storage(
+            "projection compaction watermark exceeds change head",
+        ));
+    }
+    let stopped_failure_id = row.try_get("stopped_failure_id").map_err(|error| {
+        protocol_storage_error::<DB>("decode stopped projection failure", error)
+    })?;
+    let pending_retry_failure_id = row
+        .try_get("pending_retry_failure_id")
+        .map_err(|error| protocol_storage_error::<DB>("decode pending projection retry", error))?;
+    Ok(PartitionState {
+        active_generation,
+        change_epoch,
+        change_head,
+        compacted_through,
+        pending_retry_failure_id,
+        stopped_failure_id,
+    })
+}
+
+pub(super) async fn lock_partition_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    topology: &ProjectorTopologyId,
+    partition: &crate::projection_protocol::ProjectionPartition,
+    change_epoch: &ProjectionEpoch,
+) -> Result<PartitionState, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = topology.digest();
+    let partition_hash = partition.digest();
+    let topology_bytes = topology.canonical_bytes();
+    let mut builder = QueryBuilder::<DB>::new(
+        "INSERT INTO projection_partitions \
+         (topology_bytes, topology_hash, partition_bytes, partition_hash, active_generation, change_epoch) \
+         VALUES (",
+    );
+    builder.push_bind(topology_bytes.as_slice());
+    builder.push(", ");
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(partition.canonical_bytes());
+    builder.push(", ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(", 1, ");
+    builder.push_bind(change_epoch.as_str());
+    builder.push(
+        ") ON CONFLICT (topology_hash, partition_hash) DO UPDATE \
+         SET topology_hash = excluded.topology_hash \
+         RETURNING topology_bytes, partition_bytes, active_generation, change_epoch, \
+         change_head, compacted_through, pending_retry_failure_id, stopped_failure_id",
+    );
+    let row = builder
+        .build()
+        .fetch_one(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("lock projection partition", error))?;
+    let state = decode_partition_row::<DB>(&row, topology, partition)?;
+    if state.change_epoch != *change_epoch {
+        return Err(ProjectionProtocolError::IncomparableInput);
+    }
+
+    let mut generation = QueryBuilder::<DB>::new(
+        "INSERT INTO projection_generations \
+         (topology_hash, partition_hash, generation, retry_of_generation, retry_of_failure_id) \
+         VALUES (",
+    );
+    generation.push_bind(topology_hash.as_slice());
+    generation.push(", ");
+    generation.push_bind(partition_hash.as_slice());
+    generation.push(
+        ", 1, NULL, NULL) ON CONFLICT (topology_hash, partition_hash, generation) DO NOTHING",
+    );
+    generation
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|error| {
+            protocol_storage_error::<DB>("ensure initial projection generation", error)
+        })?;
+    verify_generation_exists_in_tx::<DB>(tx, topology, partition, state.active_generation).await?;
+    Ok(state)
+}
+
+pub(super) async fn lock_existing_partition_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    topology: &ProjectorTopologyId,
+    partition: &crate::projection_protocol::ProjectionPartition,
+) -> Result<Option<PartitionState>, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = topology.digest();
+    let partition_hash = partition.digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "UPDATE projection_partitions SET topology_hash = topology_hash WHERE topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(
+        " RETURNING topology_bytes, partition_bytes, active_generation, change_epoch, \
+         change_head, compacted_through, pending_retry_failure_id, stopped_failure_id",
+    );
+    let row = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("lock projection partition", error))?;
+    row.map(|row| decode_partition_row::<DB>(&row, topology, partition))
+        .transpose()
+}
+
+#[allow(dead_code)]
+pub(super) async fn load_partition<DB>(
+    pool: &Pool<DB>,
+    topology: &ProjectorTopologyId,
+    partition: &crate::projection_protocol::ProjectionPartition,
+) -> Result<Option<PartitionState>, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = topology.digest();
+    let partition_hash = partition.digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT topology_bytes, partition_bytes, active_generation, change_epoch, \
+         change_head, compacted_through, pending_retry_failure_id, stopped_failure_id \
+         FROM projection_partitions WHERE topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    let row = builder
+        .build()
+        .fetch_optional(pool)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("load projection partition", error))?;
+    row.map(|row| decode_partition_row::<DB>(&row, topology, partition))
+        .transpose()
+}
+
+pub(super) async fn load_partition_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+) -> Result<Option<PartitionState>, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    load_partition_in_connection(&mut **tx, topology, partition).await
+}
+
+pub(super) async fn load_partition_in_connection<DB>(
+    connection: &mut DB::Connection,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+) -> Result<Option<PartitionState>, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = topology.digest();
+    let partition_hash = partition.digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT topology_bytes, partition_bytes, active_generation, change_epoch, \
+         change_head, compacted_through, pending_retry_failure_id, stopped_failure_id \
+         FROM projection_partitions WHERE topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    let row = builder
+        .build()
+        .fetch_optional(&mut *connection)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("load projection partition", error))?;
+    row.map(|row| decode_partition_row::<DB>(&row, topology, partition))
+        .transpose()
+}
+
+/// Read the exact durable live boundary using a caller-owned SQL snapshot.
+pub(crate) async fn read_projection_partition_snapshot_in_executor<DB>(
+    connection: &mut DB::Connection,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+    declared_epoch: &ProjectionEpoch,
+) -> Result<ProjectionPartitionSnapshot, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let Some(state) = load_partition_in_connection(connection, topology, partition).await? else {
+        return Ok(ProjectionPartitionSnapshot {
+            head: None,
+            compacted_through: 0,
+        });
+    };
+    if &state.change_epoch != declared_epoch {
+        return Err(ProjectionProtocolError::IncomparableInput);
+    }
+    let head = (state.change_head != 0)
+        .then(|| {
+            ProjectionChangeCursor::new(
+                topology.clone(),
+                partition.clone(),
+                state.change_epoch,
+                state.change_head,
+            )
+        })
+        .transpose()?;
+    Ok(ProjectionPartitionSnapshot {
+        head,
+        compacted_through: state.compacted_through,
+    })
+}
+
+/// Load the runtime fence and its immutable pending-retry identity from one
+/// database statement. PostgreSQL's default READ COMMITTED isolation gives
+/// each statement its own snapshot, so independent partition/failure selects
+/// could otherwise report a mixed repair state.
+pub(super) async fn load_partition_runtime_state<DB>(
+    pool: &Pool<DB>,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+) -> Result<Option<ProjectionPartitionRuntimeState>, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = topology.digest();
+    let partition_hash = partition.digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT partition.topology_bytes, partition.partition_bytes, \
+         partition.active_generation, partition.change_epoch, partition.change_head, \
+         partition.compacted_through, partition.pending_retry_failure_id, \
+         partition.stopped_failure_id, failure.failure_id AS retry_failure_id, \
+         failure.source_bytes AS retry_source_bytes, failure.source_hash AS retry_source_hash, \
+         failure.source_partition_bytes AS retry_source_partition_bytes, \
+         failure.source_partition_hash AS retry_source_partition_hash, \
+         failure.source_epoch AS retry_source_epoch, \
+         failure.source_position AS retry_source_position, \
+         failure.input_hash AS retry_input_hash, failure.message_id AS retry_message_id, \
+         failure.causation_id AS retry_causation_id, failure.gap_free AS retry_gap_free, \
+         failure.generation AS retry_failed_generation \
+         FROM projection_partitions partition LEFT JOIN projection_failures failure \
+         ON failure.topology_hash = partition.topology_hash \
+         AND failure.partition_hash = partition.partition_hash \
+         AND failure.failure_id = partition.pending_retry_failure_id \
+         WHERE partition.topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition.partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    let Some(row) = builder
+        .build()
+        .fetch_optional(pool)
+        .await
+        .map_err(|error| {
+            protocol_storage_error::<DB>("load projection partition runtime state", error)
+        })?
+    else {
+        return Ok(None);
+    };
+
+    let state = decode_partition_row::<DB>(&row, topology, partition)?;
+    let pending_retry = match &state.pending_retry_failure_id {
+        Some(expected_failure_id) => {
+            if state.stopped_failure_id.is_some() {
+                return Err(corrupt_storage(
+                    "projection partition is both stopped and pending retry",
+                ));
+            }
+            let failure_id = row
+                .try_get::<Option<String>, _>("retry_failure_id")
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("decode pending retry failure ID", error)
+                })?
+                .ok_or_else(|| {
+                    corrupt_storage(format!(
+                        "pending projection retry failure `{expected_failure_id}` is missing"
+                    ))
+                })?;
+            if &failure_id != expected_failure_id {
+                return Err(corrupt_storage(
+                    "pending retry join returned the wrong failure",
+                ));
+            }
+            let source_bytes = row
+                .try_get::<Option<Vec<u8>>, _>("retry_source_bytes")
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("decode pending retry source bytes", error)
+                })?
+                .ok_or_else(|| corrupt_storage("pending retry source bytes are missing"))?;
+            let source_hash = row
+                .try_get::<Option<Vec<u8>>, _>("retry_source_hash")
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("decode pending retry source hash", error)
+                })?
+                .ok_or_else(|| corrupt_storage("pending retry source hash is missing"))?;
+            let source_partition_bytes = row
+                .try_get::<Option<Vec<u8>>, _>("retry_source_partition_bytes")
+                .map_err(|error| {
+                    protocol_storage_error::<DB>(
+                        "decode pending retry source partition bytes",
+                        error,
+                    )
+                })?
+                .ok_or_else(|| {
+                    corrupt_storage("pending retry source partition bytes are missing")
+                })?;
+            let source_partition_hash = row
+                .try_get::<Option<Vec<u8>>, _>("retry_source_partition_hash")
+                .map_err(|error| {
+                    protocol_storage_error::<DB>(
+                        "decode pending retry source partition hash",
+                        error,
+                    )
+                })?
+                .ok_or_else(|| corrupt_storage("pending retry source partition hash is missing"))?;
+            let source =
+                ProjectionSource::from_canonical_name_bytes(&source_bytes, source_partition_bytes)?;
+            verify_digest(
+                &source_hash,
+                source.digest(),
+                "pending retry projection source",
+            )?;
+            verify_digest(
+                &source_partition_hash,
+                source.partition_digest(),
+                "pending retry projection source partition",
+            )?;
+            let source_epoch = row
+                .try_get::<Option<String>, _>("retry_source_epoch")
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("decode pending retry source epoch", error)
+                })?
+                .ok_or_else(|| corrupt_storage("pending retry source epoch is missing"))?;
+            let source_position = from_i64::<DB>(
+                row.try_get::<Option<i64>, _>("retry_source_position")
+                    .map_err(|error| {
+                        protocol_storage_error::<DB>("decode pending retry source position", error)
+                    })?
+                    .ok_or_else(|| corrupt_storage("pending retry source position is missing"))?,
+                "pending retry source position",
+            )?;
+            let input_fingerprint = ProjectionInputFingerprint::from_digest(decode_digest(
+                row.try_get::<Option<Vec<u8>>, _>("retry_input_hash")
+                    .map_err(|error| {
+                        protocol_storage_error::<DB>("decode pending retry input hash", error)
+                    })?
+                    .ok_or_else(|| corrupt_storage("pending retry input hash is missing"))?,
+                "pending retry input",
+            )?);
+            let message_id = row
+                .try_get::<Option<String>, _>("retry_message_id")
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("decode pending retry message ID", error)
+                })?
+                .ok_or_else(|| corrupt_storage("pending retry message ID is missing"))?;
+            let causation_id = row
+                .try_get::<Option<String>, _>("retry_causation_id")
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("decode pending retry causation ID", error)
+                })?
+                .ok_or_else(|| corrupt_storage("pending retry causation ID is missing"))?;
+            let gap_free = match row
+                .try_get::<Option<i64>, _>("retry_gap_free")
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("decode pending retry gap-free flag", error)
+                })?
+                .ok_or_else(|| corrupt_storage("pending retry gap-free flag is missing"))?
+            {
+                0 => false,
+                1 => true,
+                value => {
+                    return Err(corrupt_storage(format!(
+                        "pending retry gap-free flag contains invalid value {value}"
+                    )))
+                }
+            };
+            let failed_generation = ProjectionGeneration::new(from_i64::<DB>(
+                row.try_get::<Option<i64>, _>("retry_failed_generation")
+                    .map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "decode pending retry failed generation",
+                            error,
+                        )
+                    })?
+                    .ok_or_else(|| corrupt_storage("pending retry failed generation is missing"))?,
+                "pending retry failed generation",
+            )?)?;
+            if failed_generation.checked_next()? != state.active_generation {
+                return Err(corrupt_storage(format!(
+                    "pending retry failure generation {} does not precede active generation {}",
+                    failed_generation.get(),
+                    state.active_generation.get()
+                )));
+            }
+            Some(ProjectionPendingRetry {
+                failure_id,
+                input: ProjectionInputCursor::new(
+                    topology.clone(),
+                    partition.clone(),
+                    source,
+                    ProjectionEpoch::new(source_epoch)?,
+                    source_position,
+                )?,
+                input_fingerprint,
+                message_id,
+                causation_id,
+                failed_generation,
+                gap_free,
+            })
+        }
+        None => None,
+    };
+
+    Ok(Some(ProjectionPartitionRuntimeState {
+        active_generation: state.active_generation,
+        stopped_failure_id: state.stopped_failure_id,
+        pending_retry,
+    }))
+}
+
+pub(super) async fn verify_generation_exists_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    topology: &ProjectorTopologyId,
+    partition: &crate::projection_protocol::ProjectionPartition,
+    generation: ProjectionGeneration,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    let generation_value = to_i64::<DB>(generation.get(), "projection generation")?;
+    let topology_hash = topology.digest();
+    let partition_hash = partition.digest();
+    let mut builder =
+        QueryBuilder::<DB>::new("SELECT 1 FROM projection_generations WHERE topology_hash = ");
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(" AND generation = ");
+    builder.push_bind(generation_value);
+    builder.push(" LIMIT 1");
+    if builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("verify projection generation", error))?
+        .is_none()
+    {
+        return Err(corrupt_storage(format!(
+            "active projection generation {} is missing",
+            generation.get()
+        )));
+    }
+    Ok(())
+}
diff --git a/src/sqlx_repo/projection_protocol/postgres_tests.rs b/src/sqlx_repo/projection_protocol/postgres_tests.rs
new file mode 100644
index 00000000..81483d4a
--- /dev/null
+++ b/src/sqlx_repo/projection_protocol/postgres_tests.rs
@@ -0,0 +1,1061 @@
+#[cfg(all(test, feature = "postgres"))]
+mod postgres_tests {
+    use std::sync::LazyLock;
+    use std::time::Duration;
+
+    use super::*;
+    use crate::command_ledger::{
+        CanonicalInputHash, CausalCommitBatch, CausalTransactionalCommit,
+        CommandContractFingerprint, CommandId, CommandLedgerKey, CommandLedgerStore,
+        CommandReservation, PrincipalPartitionId, ReservationOutcome, TerminalCommandState,
+    };
+    use crate::projection_protocol::{
+        ProjectionCheckpointProbe, ProjectionRecordMutation, ProjectionScopeCodec,
+    };
+    use crate::repository::{CommitBatch, ReadModelWritePlanStore};
+    use crate::table::{
+        ColumnType, DeleteTableRowMutation, ExpectedVersion, PrimaryKey, RowKey, RowValue,
+        RowValues, RowWriteMode, TableColumn, TableKind, TableRowMutation, TableSchema,
+        TableSchemaRegistry, TableStoreError, TableWritePlan,
+    };
+
+    fn topology() -> ProjectorTopologyId {
+        ProjectorTopologyId::new(1, "postgres_projection_runtime", [71; 32]).unwrap()
+    }
+
+    fn partition() -> ProjectionPartition {
+        ProjectionScopeCodec::new(topology())
+            .encode_partition(Some(&serde_json::json!("postgres-runtime-tenant")))
+            .unwrap()
+    }
+
+    fn change_epoch() -> ProjectionEpoch {
+        ProjectionEpoch::new("postgres-changes-v1").unwrap()
+    }
+
+    fn schema() -> &'static TableSchema {
+        static SCHEMA: LazyLock<TableSchema> = LazyLock::new(|| TableSchema {
+            model_name: "PostgresProjectionView".into(),
+            table_name: "postgres_projection_views".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new("id", "id", ColumnType::Text)
+                },
+                TableColumn::new("value", "value", ColumnType::Text),
+            ],
+            primary_key: PrimaryKey::new(["id"]),
+            version_column: Some(crate::table::DEFAULT_TABLE_VERSION_COLUMN.into()),
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        });
+        &SCHEMA
+    }
+
+    fn ownership() -> ProjectionModelOwnership {
+        ProjectionModelOwnership::new("PostgresProjectionView", "postgres_projection_views")
+            .unwrap()
+    }
+
+    fn scope_codec() -> ProjectionScopeCodec {
+        ProjectionScopeCodec::with_models(topology(), [("PostgresProjectionView", schema())])
+            .unwrap()
+    }
+
+    fn record_key() -> RowKey {
+        RowKey::new([("id", RowValue::String("runtime-row".into()))])
+    }
+
+    fn scope() -> ProjectionRecordScope {
+        scope_codec()
+            .encode_row_scope(
+                "postgres_projection_runtime",
+                "PostgresProjectionView",
+                Some(&serde_json::json!("postgres-runtime-tenant")),
+                &record_key(),
+            )
+            .unwrap()
+    }
+
+    fn source() -> ProjectionSource {
+        ProjectionSource::new("postgres_runtime_source", b"runtime-row".to_vec()).unwrap()
+    }
+
+    fn snapshot_request(generation: ProjectionGeneration) -> ProjectionQuerySnapshotRequest {
+        ProjectionQuerySnapshotRequest::new(
+            &scope_codec(),
+            Some(&serde_json::json!("postgres-runtime-tenant")),
+            "PostgresProjectionView",
+            record_key(),
+            vec![ProjectionCheckpointProbe::new(
+                topology(),
+                partition(),
+                source(),
+                ProjectionEpoch::new("postgres-source-v1").unwrap(),
+                generation,
+            )],
+        )
+        .unwrap()
+    }
+
+    fn input(
+        position: u64,
+        fingerprint: &[u8],
+        message_id: &str,
+        causation_id: &str,
+        generation: ProjectionGeneration,
+    ) -> TrustedProjectionInput {
+        TrustedProjectionInput::mint(
+            ProjectionInputCursor::new(
+                topology(),
+                partition(),
+                source(),
+                ProjectionEpoch::new("postgres-source-v1").unwrap(),
+                position,
+            )
+            .unwrap(),
+            ProjectionInputFingerprint::from_canonical_bytes(fingerprint),
+            message_id,
+            causation_id,
+            generation,
+            false,
+        )
+        .unwrap()
+    }
+
+    fn upsert_table_mutation(value: &str) -> TableMutation {
+        let mut values = RowValues::new();
+        values.insert("id", RowValue::String("runtime-row".into()));
+        values.insert("value", RowValue::String(value.into()));
+        TableMutation::UpsertRow(TableRowMutation {
+            schema: schema(),
+            key: record_key(),
+            values,
+            expected_version: ExpectedVersion::Any,
+            mode: RowWriteMode::Upsert,
+        })
+    }
+
+    fn upsert_mutation(
+        value: &str,
+        expectation: ProjectionRecordExpectation,
+        kind: ProjectionMutationKind,
+    ) -> ProjectionRecordMutation {
+        ProjectionRecordMutation::new(scope(), upsert_table_mutation(value), expectation, kind)
+            .unwrap()
+    }
+
+    fn delete_mutation(expected: RecordRevision) -> ProjectionRecordMutation {
+        ProjectionRecordMutation::new(
+            scope(),
+            TableMutation::DeleteRow(DeleteTableRowMutation {
+                schema: schema(),
+                key: record_key(),
+                expected_version: ExpectedVersion::Any,
+            }),
+            ProjectionRecordExpectation::Exact(expected),
+            ProjectionMutationKind::Delete,
+        )
+        .unwrap()
+    }
+
+    fn batch(
+        input: TrustedProjectionInput,
+        mutations: Vec<ProjectionRecordMutation>,
+    ) -> ProjectionCommitBatch {
+        ProjectionCommitBatch {
+            input,
+            change_epoch: change_epoch(),
+            ownership: vec![ownership()],
+            mutations,
+            observations: Vec::new(),
+        }
+    }
+
+    fn assert_live_snapshot(
+        snapshot: &ProjectionQuerySnapshot,
+        value: &str,
+        incarnation: u64,
+        revision: u64,
+        source_position: u64,
+    ) {
+        assert_eq!(
+            snapshot.row.as_ref().and_then(|row| row.get("value")),
+            Some(&RowValue::String(value.into()))
+        );
+        let record = snapshot.record.as_ref().expect("live record metadata");
+        assert!(!record.tombstone);
+        assert_eq!(record.revision.incarnation(), incarnation);
+        assert_eq!(record.revision.revision(), revision);
+        let checkpoint = snapshot.checkpoints[0]
+            .checkpoint
+            .as_ref()
+            .expect("explicit source checkpoint");
+        assert_eq!(checkpoint.input().position(), source_position);
+        assert_eq!(checkpoint.change(), &record.change);
+        assert_eq!(snapshot.change_head.as_ref(), Some(&record.change));
+    }
+
+    #[tokio::test]
+    async fn postgres_projection_protocol_runtime_conforms() {
+        let Ok(database_url) = std::env::var("DISTRIBUTED_TEST_POSTGRES_URL") else {
+            return;
+        };
+        let repository = SqlxRepository::<sqlx::Postgres>::connect_and_migrate(&database_url)
+            .await
+            .unwrap()
+            .with_projection_change_retention(ProjectionChangeRetention::new(3).unwrap());
+        let mut registry = TableSchemaRegistry::new();
+        registry.register_schema(schema().clone()).unwrap();
+        repository
+            .bootstrap_table_schema_for_dev(&registry)
+            .await
+            .unwrap();
+
+        let mut raw_first_tx = repository.pool().begin().await.unwrap();
+        let ownership_tables = BTreeSet::from(["postgres_projection_views".to_string()]);
+        lock_projection_table_ownership_fences_in_tx(&mut raw_first_tx, &ownership_tables)
+            .await
+            .unwrap();
+        let registration_repository = repository.clone();
+        let racing_registration = tokio::spawn(async move {
+            registration_repository
+                .register_projection_models(&topology(), &[ownership()])
+                .await
+        });
+        tokio::task::yield_now().await;
+        assert!(!racing_registration.is_finished());
+        apply_read_model_write_plan_in_tx(
+            &mut raw_first_tx,
+            TableWritePlan::new(vec![upsert_table_mutation("raw-first")]),
+        )
+        .await
+        .unwrap();
+        raw_first_tx.commit().await.unwrap();
+        assert!(matches!(
+            racing_registration.await.unwrap(),
+            Err(ProjectionProtocolError::InvalidBatch(message))
+                if message.contains("unverified legacy rows")
+        ));
+        sqlx::query("DELETE FROM postgres_projection_views WHERE id = $1")
+            .bind("runtime-row")
+            .execute(repository.pool())
+            .await
+            .unwrap();
+        repository
+            .register_projection_models(&topology(), &[ownership()])
+            .await
+            .unwrap();
+
+        assert_eq!(
+            repository
+                .projection_partition_runtime_state(&topology(), &partition())
+                .await
+                .unwrap(),
+            None
+        );
+        assert!(matches!(
+            repository
+                .commit_write_plan(TableWritePlan::new(vec![upsert_table_mutation("raw")]))
+                .await,
+            Err(TableStoreError::CausalWriteRequired { ref table })
+                if table == "postgres_projection_views"
+        ));
+
+        let mut local_changes = repository.read_model_changes();
+        let mut pg_changes = sqlx::postgres::PgListener::connect(&database_url)
+            .await
+            .unwrap();
+        pg_changes
+            .listen("distributed_read_model_changes")
+            .await
+            .unwrap();
+        let initial_input = input(
+            5,
+            b"postgres-checkpoint-5",
+            "postgres-message-5",
+            "postgres-cause-5",
+            ProjectionGeneration::initial(),
+        );
+        assert_eq!(
+            repository
+                .projection_input_disposition(&initial_input)
+                .await
+                .unwrap(),
+            ProjectionInputDisposition::Pending
+        );
+        let mut initial = batch(
+            initial_input.clone(),
+            vec![upsert_mutation(
+                "5",
+                ProjectionRecordExpectation::Missing,
+                ProjectionMutationKind::Upsert,
+            )],
+        );
+        initial.observations = vec![crate::projection_protocol::ProjectionObservationRequest {
+            kind: ProjectionObservationKind::Record,
+            target: ProjectionObservationTarget::StagedRecord(scope()),
+        }];
+        assert_eq!(
+            repository.commit_projection(initial).await.unwrap().outcome,
+            ProjectionCommitOutcome::Applied
+        );
+        assert!(matches!(
+            repository
+                .projection_input_disposition(&initial_input)
+                .await
+                .unwrap(),
+            ProjectionInputDisposition::Duplicate(checkpoint)
+                if checkpoint.input().position() == 5
+        ));
+        let local_change = tokio::time::timeout(Duration::from_secs(2), local_changes.recv())
+            .await
+            .unwrap()
+            .unwrap();
+        assert!(local_change.tables.contains(PROJECTION_CHANGE_NOTIFY_TABLE));
+        tokio::time::timeout(Duration::from_secs(2), pg_changes.recv())
+            .await
+            .expect("PostgreSQL notifies only after the projection transaction commits")
+            .unwrap();
+        assert_live_snapshot(
+            &repository
+                .projection_query_snapshot(&snapshot_request(ProjectionGeneration::initial()))
+                .await
+                .unwrap(),
+            "5",
+            1,
+            1,
+            5,
+        );
+        let causal_probe = crate::projection_protocol::ProjectionObligationEvidenceRequest::new(
+            "postgres-cause-5",
+            scope(),
+            ProjectionObservationKind::Record,
+        )
+        .unwrap();
+        assert!(matches!(
+            repository
+                .projection_obligation_evidence_batch(
+                    &ProjectionObligationEvidenceBatchRequest::new(vec![causal_probe.clone()])
+                        .unwrap(),
+                )
+                .await
+                .unwrap()
+                .evidence
+                .as_slice(),
+            [ProjectionObligationEvidence::Observed(_)]
+        ));
+
+        assert_eq!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        5,
+                        b"postgres-checkpoint-5",
+                        "postgres-message-5",
+                        "postgres-cause-5",
+                        ProjectionGeneration::initial(),
+                    ),
+                    vec![upsert_mutation(
+                        "ignored-duplicate",
+                        ProjectionRecordExpectation::Missing,
+                        ProjectionMutationKind::Upsert,
+                    )],
+                ))
+                .await
+                .unwrap()
+                .outcome,
+            ProjectionCommitOutcome::Duplicate
+        );
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        5,
+                        b"postgres-corrupt-5",
+                        "postgres-message-5",
+                        "postgres-cause-5",
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::InputCorruption)
+        ));
+        let remapped_partition = ProjectionScopeCodec::new(topology())
+            .encode_partition(Some(&serde_json::json!("postgres-other-tenant")))
+            .unwrap();
+        let remapped_message = TrustedProjectionInput::mint(
+            ProjectionInputCursor::new(
+                topology(),
+                remapped_partition,
+                source(),
+                ProjectionEpoch::new("postgres-source-v1").unwrap(),
+                5,
+            )
+            .unwrap(),
+            ProjectionInputFingerprint::from_canonical_bytes(b"postgres-checkpoint-5"),
+            "postgres-message-5",
+            "postgres-cause-5",
+            ProjectionGeneration::initial(),
+            false,
+        )
+        .unwrap();
+        assert!(matches!(
+            repository
+                .commit_projection(batch(remapped_message, Vec::new()))
+                .await,
+            Err(ProjectionProtocolError::MessageIdReuse { message_id })
+                if message_id == "postgres-message-5"
+        ));
+        let stale_input = input(
+            4,
+            b"postgres-stale-4",
+            "postgres-message-4",
+            "postgres-cause-4",
+            ProjectionGeneration::initial(),
+        );
+        assert_eq!(
+            repository
+                .commit_projection(batch(stale_input.clone(), Vec::new()))
+                .await
+                .unwrap()
+                .outcome,
+            ProjectionCommitOutcome::StaleInput
+        );
+        assert!(matches!(
+            repository
+                .projection_input_disposition(&stale_input)
+                .await
+                .unwrap(),
+            ProjectionInputDisposition::Stale(checkpoint)
+                if checkpoint.input().position() == 5
+        ));
+
+        let created = repository
+            .projection_record(&scope())
+            .await
+            .unwrap()
+            .unwrap();
+        let deleted = repository
+            .commit_projection(batch(
+                input(
+                    6,
+                    b"postgres-delete-6",
+                    "postgres-message-6",
+                    "postgres-cause-6",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![delete_mutation(created.revision)],
+            ))
+            .await
+            .unwrap();
+        assert!(deleted.records[0].tombstone);
+        assert!(repository
+            .projection_query_snapshot(&snapshot_request(ProjectionGeneration::initial()))
+            .await
+            .unwrap()
+            .row
+            .is_none());
+        let recreated = repository
+            .commit_projection(batch(
+                input(
+                    7,
+                    b"postgres-recreate-7",
+                    "postgres-message-7",
+                    "postgres-cause-7",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![upsert_mutation(
+                    "7",
+                    ProjectionRecordExpectation::Exact(deleted.records[0].revision.clone()),
+                    ProjectionMutationKind::Recreate,
+                )],
+            ))
+            .await
+            .unwrap();
+        assert_eq!(recreated.records[0].revision.incarnation(), 2);
+        assert_eq!(recreated.records[0].revision.revision(), 1);
+
+        let failed_input = input(
+            9,
+            b"postgres-failure-9",
+            "postgres-message-9",
+            "postgres-cause-5",
+            ProjectionGeneration::initial(),
+        );
+        let failure = repository
+            .record_projection_failure(
+                ProjectionFailureBatch::new(
+                    failed_input.clone(),
+                    change_epoch(),
+                    "postgres-failure-9",
+                    "decode_error",
+                    b"bad postgres payload".to_vec(),
+                )
+                .unwrap(),
+            )
+            .await
+            .unwrap();
+        assert!(matches!(
+            repository
+                .projection_input_disposition(&failed_input)
+                .await,
+            Err(ProjectionProtocolError::PartitionStopped { failure_id })
+                if failure_id == "postgres-failure-9"
+        ));
+        assert!(!failure.gap_free);
+        let stopped = repository
+            .projection_partition_runtime_state(&topology(), &partition())
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(stopped.active_generation, ProjectionGeneration::initial());
+        assert_eq!(
+            stopped.stopped_failure_id.as_deref(),
+            Some("postgres-failure-9")
+        );
+        assert_eq!(stopped.pending_retry, None);
+        let generation = repository
+            .repair_projection(&topology(), &partition(), "postgres-failure-9")
+            .await
+            .unwrap();
+        let retry_input = input(
+            9,
+            b"postgres-failure-9",
+            "postgres-message-9",
+            "postgres-cause-5",
+            generation,
+        );
+        assert_eq!(
+            repository
+                .projection_input_disposition(&retry_input)
+                .await
+                .unwrap(),
+            ProjectionInputDisposition::Pending
+        );
+        let repaired = repository
+            .projection_partition_runtime_state(&topology(), &partition())
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(repaired.active_generation, generation);
+        assert_eq!(repaired.stopped_failure_id, None);
+        let pending_retry = repaired.pending_retry.unwrap();
+        assert_eq!(pending_retry.failure_id, failure.failure_id);
+        assert_eq!(pending_retry.input, failure.input);
+        assert_eq!(pending_retry.input_fingerprint, failure.input_fingerprint);
+        assert_eq!(pending_retry.message_id, failure.message_id);
+        assert_eq!(pending_retry.causation_id, failure.causation_id);
+        assert_eq!(pending_retry.failed_generation, failure.generation);
+        assert_eq!(pending_retry.gap_free, failure.gap_free);
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        10,
+                        b"postgres-later-10",
+                        "postgres-message-10",
+                        "postgres-cause-10",
+                        generation,
+                    ),
+                    vec![upsert_mutation(
+                        "must-not-run-before-retry",
+                        ProjectionRecordExpectation::Exact(recreated.records[0].revision.clone(),),
+                        ProjectionMutationKind::Upsert,
+                    )],
+                ))
+                .await,
+            Err(ProjectionProtocolError::IncomparableInput)
+        ));
+        assert_eq!(
+            repository
+                .commit_projection(batch(retry_input, Vec::new()))
+                .await
+                .unwrap()
+                .outcome,
+            ProjectionCommitOutcome::Applied
+        );
+        assert_eq!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        10,
+                        b"postgres-later-10",
+                        "postgres-message-10",
+                        "postgres-cause-10",
+                        generation,
+                    ),
+                    vec![upsert_mutation(
+                        "10",
+                        ProjectionRecordExpectation::Exact(recreated.records[0].revision.clone()),
+                        ProjectionMutationKind::Upsert,
+                    )],
+                ))
+                .await
+                .unwrap()
+                .outcome,
+            ProjectionCommitOutcome::Applied
+        );
+
+        let before_rollback = repository
+            .projection_query_snapshot(&snapshot_request(generation))
+            .await
+            .unwrap();
+        assert_live_snapshot(&before_rollback, "10", 2, 2, 10);
+        let before_rollback_inbox: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM consumer_inbox")
+            .fetch_one(repository.pool())
+            .await
+            .unwrap();
+        sqlx::query(
+            "CREATE OR REPLACE FUNCTION fail_projection_record_write() RETURNS trigger \
+             LANGUAGE plpgsql AS $$ BEGIN RAISE EXCEPTION 'forced projection record failure'; \
+             END; $$",
+        )
+        .execute(repository.pool())
+        .await
+        .unwrap();
+        sqlx::query(
+            "CREATE TRIGGER fail_projection_record_write \
+             BEFORE INSERT OR UPDATE ON projection_records FOR EACH ROW \
+             EXECUTE FUNCTION fail_projection_record_write()",
+        )
+        .execute(repository.pool())
+        .await
+        .unwrap();
+        let mut rollback_local_changes = repository.read_model_changes();
+        let mut rollback_pg_changes = sqlx::postgres::PgListener::connect(&database_url)
+            .await
+            .unwrap();
+        rollback_pg_changes
+            .listen("distributed_read_model_changes")
+            .await
+            .unwrap();
+        assert!(repository
+            .commit_projection(batch(
+                input(
+                    11,
+                    b"postgres-rollback-11",
+                    "postgres-message-11",
+                    "postgres-cause-11",
+                    generation,
+                ),
+                vec![upsert_mutation(
+                    "must-roll-back",
+                    ProjectionRecordExpectation::Exact(
+                        before_rollback.record.as_ref().unwrap().revision.clone(),
+                    ),
+                    ProjectionMutationKind::Upsert,
+                )],
+            ))
+            .await
+            .is_err());
+        assert_eq!(
+            rollback_local_changes.try_recv(),
+            Err(tokio::sync::broadcast::error::TryRecvError::Empty)
+        );
+        assert!(
+            tokio::time::timeout(Duration::from_millis(150), rollback_pg_changes.recv())
+                .await
+                .is_err(),
+            "a rolled-back pg_notify must never be delivered"
+        );
+        assert_eq!(
+            repository
+                .projection_query_snapshot(&snapshot_request(generation))
+                .await
+                .unwrap(),
+            before_rollback
+        );
+        let after_rollback_inbox: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM consumer_inbox")
+            .fetch_one(repository.pool())
+            .await
+            .unwrap();
+        assert_eq!(after_rollback_inbox, before_rollback_inbox);
+        let rolled_back_receipt: i64 = sqlx::query_scalar(
+            "SELECT COUNT(*) FROM projection_input_receipts WHERE message_id = $1",
+        )
+        .bind("postgres-message-11")
+        .fetch_one(repository.pool())
+        .await
+        .unwrap();
+        assert_eq!(rolled_back_receipt, 0);
+        sqlx::query("DROP TRIGGER fail_projection_record_write ON projection_records")
+            .execute(repository.pool())
+            .await
+            .unwrap();
+        sqlx::query("DROP FUNCTION fail_projection_record_write()")
+            .execute(repository.pool())
+            .await
+            .unwrap();
+
+        let successful_11 = repository
+            .commit_projection(batch(
+                input(
+                    11,
+                    b"postgres-rollback-11",
+                    "postgres-message-11",
+                    "postgres-cause-11",
+                    generation,
+                ),
+                vec![upsert_mutation(
+                    "11",
+                    ProjectionRecordExpectation::Exact(
+                        before_rollback.record.as_ref().unwrap().revision.clone(),
+                    ),
+                    ProjectionMutationKind::Upsert,
+                )],
+            ))
+            .await
+            .unwrap();
+        tokio::time::timeout(Duration::from_secs(2), rollback_local_changes.recv())
+            .await
+            .expect("local change is published after commit")
+            .unwrap();
+        tokio::time::timeout(Duration::from_secs(2), rollback_pg_changes.recv())
+            .await
+            .expect("PostgreSQL notification is delivered after commit")
+            .unwrap();
+        let committed_11 = repository
+            .projection_query_snapshot(&snapshot_request(generation))
+            .await
+            .unwrap();
+        assert_live_snapshot(&committed_11, "11", 2, 3, 11);
+
+        let repeatable_request = snapshot_request(generation);
+        let repeatable_live_request = ProjectionLiveRecordBatchRequest::new(vec![
+            crate::projection_protocol::ProjectionLiveRecordRequest::new(
+                &scope_codec(),
+                "PostgresProjectionView",
+                record_key(),
+            )
+            .unwrap(),
+        ])
+        .unwrap();
+        let repeatable_expectation = successful_11.records[0].revision.clone();
+        let writer_repository = repository.clone();
+        let (inside_before, inside_live_before, inside_after, inside_live_after) =
+            with_projection_read_snapshot(repository.pool(), move |connection| {
+                Box::pin(async move {
+                    let before = read_projection_query_snapshot_in_executor::<sqlx::Postgres, _>(
+                        &mut *connection,
+                        &repeatable_request,
+                    )
+                    .await?;
+                    let live_before =
+                        read_projection_live_record_batch_in_executor::<sqlx::Postgres>(
+                            &mut *connection,
+                            &repeatable_live_request,
+                        )
+                        .await?;
+                    writer_repository
+                        .commit_projection(batch(
+                            input(
+                                12,
+                                b"postgres-repeatable-12",
+                                "postgres-message-12",
+                                "postgres-cause-12",
+                                generation,
+                            ),
+                            vec![upsert_mutation(
+                                "12",
+                                ProjectionRecordExpectation::Exact(repeatable_expectation),
+                                ProjectionMutationKind::Upsert,
+                            )],
+                        ))
+                        .await?;
+                    let after = read_projection_query_snapshot_in_executor::<sqlx::Postgres, _>(
+                        &mut *connection,
+                        &repeatable_request,
+                    )
+                    .await?;
+                    let live_after =
+                        read_projection_live_record_batch_in_executor::<sqlx::Postgres>(
+                            &mut *connection,
+                            &repeatable_live_request,
+                        )
+                        .await?;
+                    Ok((before, live_before, after, live_after))
+                })
+            })
+            .await
+            .unwrap();
+        assert_eq!(inside_after, inside_before);
+        assert_eq!(inside_live_after, inside_live_before);
+        assert_eq!(
+            inside_live_before.records[0], inside_before.record,
+            "physical query and magic live-record evidence share one repeatable snapshot"
+        );
+        assert_live_snapshot(&inside_before, "11", 2, 3, 11);
+        let committed_12 = repository
+            .projection_query_snapshot(&snapshot_request(generation))
+            .await
+            .unwrap();
+        assert_live_snapshot(&committed_12, "12", 2, 4, 12);
+        let committed_live = repository
+            .projection_live_record_batch(
+                &ProjectionLiveRecordBatchRequest::new(vec![
+                    crate::projection_protocol::ProjectionLiveRecordRequest::new(
+                        &scope_codec(),
+                        "PostgresProjectionView",
+                        record_key(),
+                    )
+                    .unwrap(),
+                ])
+                .unwrap(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(committed_live.records[0], committed_12.record);
+
+        let retained_failure_change: i64 =
+            sqlx::query_scalar("SELECT COUNT(*) FROM projection_changes WHERE failure_id = $1")
+                .bind(failure.failure_id.as_str())
+                .fetch_one(repository.pool())
+                .await
+                .unwrap();
+        assert_eq!(
+            retained_failure_change, 0,
+            "bounded retention must compact the failure change before evidence lookup"
+        );
+        assert!(matches!(
+            repository
+                .projection_obligation_evidence_batch(
+                    &ProjectionObligationEvidenceBatchRequest::new(vec![causal_probe]).unwrap(),
+                )
+                .await
+                .unwrap()
+                .evidence
+                .as_slice(),
+            [ProjectionObligationEvidence::TerminalFailure(stored)]
+                if stored == &failure
+        ));
+
+        let physical_version: i64 = sqlx::query_scalar(
+            "SELECT _sourced_version FROM postgres_projection_views WHERE id = $1",
+        )
+        .bind("runtime-row")
+        .fetch_one(repository.pool())
+        .await
+        .unwrap();
+        sqlx::query("DELETE FROM postgres_projection_views WHERE id = $1")
+            .bind("runtime-row")
+            .execute(repository.pool())
+            .await
+            .unwrap();
+        assert!(matches!(
+            repository
+                .projection_query_snapshot(&snapshot_request(generation))
+                .await,
+            Err(ProjectionProtocolError::RecordMissing { .. })
+        ));
+        sqlx::query(
+            "INSERT INTO postgres_projection_views (id, value, _sourced_version) \
+             VALUES ($1, $2, $3)",
+        )
+        .bind("runtime-row")
+        .bind("12")
+        .bind(physical_version)
+        .execute(repository.pool())
+        .await
+        .unwrap();
+        assert_eq!(
+            repository
+                .projection_query_snapshot(&snapshot_request(generation))
+                .await
+                .unwrap(),
+            committed_12
+        );
+
+        let retention = Duration::from_secs(3600);
+        let reservation = CommandReservation::new(
+            CommandLedgerKey::new(
+                "postgres-projection-runtime",
+                PrincipalPartitionId::new("tenant:postgres-direct").unwrap(),
+                CommandId::parse(uuid::Uuid::now_v7().hyphenated().to_string()).unwrap(),
+            )
+            .unwrap(),
+            "postgres-project-view",
+            CommandContractFingerprint::new([81; 32]),
+            CanonicalInputHash::new([82; 32]),
+            Duration::from_secs(30),
+            retention,
+        )
+        .unwrap();
+        let attempt = match repository.reserve_command(reservation).await.unwrap() {
+            ReservationOutcome::Acquired(attempt) => attempt,
+            _ => panic!("fresh PostgreSQL command must acquire its first attempt"),
+        };
+        let causation_id = attempt.causation_id().as_str().to_string();
+        let completion = attempt
+            .complete(
+                TerminalCommandState::Projected,
+                serde_json::json!({"postgres_projected": true}),
+                retention,
+            )
+            .unwrap();
+        let direct = SameTransactionProjectionBatch::single_upsert(
+            topology(),
+            partition(),
+            change_epoch(),
+            ownership(),
+            scope(),
+            upsert_table_mutation("direct"),
+            causation_id,
+        )
+        .unwrap();
+        repository
+            .commit_causal_batch(CausalCommitBatch::with_direct_projection(
+                CommitBatch::empty(),
+                completion,
+                direct,
+            ))
+            .await
+            .unwrap();
+        let after_direct = repository
+            .projection_record(&scope())
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(after_direct.revision.incarnation(), 2);
+        assert_eq!(after_direct.revision.revision(), 5);
+
+        let (head, compacted_through) = match repository
+            .projection_changes(&topology(), &partition(), None, 100)
+            .await
+            .unwrap()
+        {
+            ProjectionChangeRead::ResetRequired {
+                head,
+                compacted_through,
+            } => (head.unwrap(), compacted_through),
+            other => panic!("retention must require reset from origin: {other:?}"),
+        };
+        assert!(compacted_through > 0);
+        assert_eq!(head.position(), compacted_through + 3);
+        let boundary =
+            ProjectionChangeCursor::new(topology(), partition(), change_epoch(), compacted_through)
+                .unwrap();
+        match repository
+            .projection_changes(&topology(), &partition(), Some(&boundary), 100)
+            .await
+            .unwrap()
+        {
+            ProjectionChangeRead::Changes {
+                head: retained_head,
+                compacted_through: retained_watermark,
+                changes,
+            } => {
+                assert_eq!(retained_head, Some(head));
+                assert_eq!(retained_watermark, compacted_through);
+                assert_eq!(changes.len(), 3);
+                assert_eq!(changes[0].cursor.position(), compacted_through + 1);
+            }
+            other => panic!("exact compacted boundary must resume retained suffix: {other:?}"),
+        }
+
+        let resume_after = ProjectionChangeCursor::new(
+            topology(),
+            partition(),
+            change_epoch(),
+            compacted_through + 1,
+        )
+        .unwrap();
+        let compact_through = ProjectionChangeCursor::new(
+            topology(),
+            partition(),
+            change_epoch(),
+            compacted_through + 2,
+        )
+        .unwrap();
+        let reader_pool = repository.pool().clone();
+        let raced_resume_after = resume_after.clone();
+        let (state_observed_tx, state_observed_rx) = tokio::sync::oneshot::channel();
+        let (compaction_committed_tx, compaction_committed_rx) = tokio::sync::oneshot::channel();
+        let reader = tokio::spawn(async move {
+            read_projection_changes_in_snapshot(
+                &reader_pool,
+                topology(),
+                partition(),
+                Some(raced_resume_after),
+                100,
+                async move {
+                    state_observed_tx
+                        .send(())
+                        .expect("PostgreSQL resume reader reports its established snapshot");
+                    compaction_committed_rx
+                        .await
+                        .expect("PostgreSQL compaction completion reaches resume reader");
+                },
+            )
+            .await
+        });
+
+        state_observed_rx
+            .await
+            .expect("PostgreSQL resume reader establishes its snapshot");
+        assert_eq!(
+            tokio::time::timeout(
+                Duration::from_secs(5),
+                repository.compact_projection_changes(&compact_through),
+            )
+            .await
+            .expect("PostgreSQL compaction commits while repeatable reader remains open")
+            .unwrap(),
+            compacted_through + 2
+        );
+        compaction_committed_tx
+            .send(())
+            .expect("PostgreSQL resume reader remains active after compaction");
+
+        match reader.await.unwrap().unwrap() {
+            ProjectionChangeRead::Changes {
+                head,
+                compacted_through: raced_watermark,
+                changes,
+            } => {
+                assert_eq!(
+                    head.as_ref().map(ProjectionChangeCursor::position),
+                    Some(compacted_through + 3)
+                );
+                assert_eq!(raced_watermark, compacted_through);
+                assert_eq!(
+                    changes
+                        .iter()
+                        .map(|change| change.cursor.position())
+                        .collect::<Vec<_>>(),
+                    vec![compacted_through + 2, compacted_through + 3],
+                    "repeatable snapshot returns the complete pre-compaction suffix"
+                );
+            }
+            other => {
+                panic!("PostgreSQL repeatable resume must return its complete page: {other:?}")
+            }
+        }
+        assert!(matches!(
+            repository
+                .projection_changes(&topology(), &partition(), Some(&resume_after), 100)
+                .await
+                .unwrap(),
+            ProjectionChangeRead::ResetRequired {
+                compacted_through: fresh_watermark,
+                ..
+            } if fresh_watermark == compacted_through + 2
+        ));
+        assert!(matches!(
+            repository
+                .projection_changes(&topology(), &partition(), Some(&compact_through), 100)
+                .await
+                .unwrap(),
+            ProjectionChangeRead::Changes {
+                compacted_through: fresh_watermark,
+                ref changes,
+                ..
+            } if fresh_watermark == compacted_through + 2
+                && changes.len() == 1
+                && changes[0].cursor.position() == compacted_through + 3
+        ));
+    }
+}
diff --git a/src/sqlx_repo/projection_protocol/reads.rs b/src/sqlx_repo/projection_protocol/reads.rs
new file mode 100644
index 00000000..4553043c
--- /dev/null
+++ b/src/sqlx_repo/projection_protocol/reads.rs
@@ -0,0 +1,1776 @@
+use super::*;
+
+pub(super) fn decode_change_row<DB>(
+    row: &DB::Row,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+    expected_epoch: &ProjectionEpoch,
+) -> Result<ProjectionChange, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let change_epoch: String = row
+        .try_get("change_epoch")
+        .map_err(|error| protocol_storage_error::<DB>("decode projection change epoch", error))?;
+    let change_epoch = ProjectionEpoch::new(change_epoch)?;
+    if &change_epoch != expected_epoch {
+        return Err(corrupt_storage(
+            "projection change epoch differs from its partition",
+        ));
+    }
+    let change_position = from_i64::<DB>(
+        row.try_get("change_position").map_err(|error| {
+            protocol_storage_error::<DB>("decode projection change position", error)
+        })?,
+        "projection change position",
+    )?;
+    let kind_value: String = row
+        .try_get("change_kind")
+        .map_err(|error| protocol_storage_error::<DB>("decode projection change kind", error))?;
+    let kind = decode_change_kind(&kind_value)?;
+    let causation_id: String = row
+        .try_get("causation_id")
+        .map_err(|error| protocol_storage_error::<DB>("decode change causation ID", error))?;
+    let model_name: Option<String> = row
+        .try_get("model_name")
+        .map_err(|error| protocol_storage_error::<DB>("decode change model", error))?;
+    let scope_kind: Option<String> = row
+        .try_get("scope_kind")
+        .map_err(|error| protocol_storage_error::<DB>("decode change scope kind", error))?;
+    let key_bytes: Option<Vec<u8>> = row
+        .try_get("canonical_key_bytes")
+        .map_err(|error| protocol_storage_error::<DB>("decode change key bytes", error))?;
+    let key_hash: Option<Vec<u8>> = row
+        .try_get("canonical_key_hash")
+        .map_err(|error| protocol_storage_error::<DB>("decode change key hash", error))?;
+    let incarnation: Option<i64> = row
+        .try_get("incarnation")
+        .map_err(|error| protocol_storage_error::<DB>("decode change record incarnation", error))?;
+    let revision_value: Option<i64> = row
+        .try_get("revision")
+        .map_err(|error| protocol_storage_error::<DB>("decode change record revision", error))?;
+    let failure_id: Option<String> = row
+        .try_get("failure_id")
+        .map_err(|error| protocol_storage_error::<DB>("decode change failure ID", error))?;
+
+    let scope = match (model_name, key_bytes, key_hash) {
+        (Some(model), Some(bytes), Some(hash)) => {
+            let scope =
+                ProjectionRecordScope::new(topology.clone(), partition.clone(), model, bytes)?;
+            verify_digest(&hash, scope.key_digest(), "projection change key")?;
+            Some(scope)
+        }
+        (None, None, None) => None,
+        _ => {
+            return Err(corrupt_storage(
+                "projection change record scope has an inconsistent shape",
+            ))
+        }
+    };
+    let revision = match (scope.as_ref(), incarnation, revision_value) {
+        (Some(scope), Some(incarnation), Some(revision)) => Some(RecordRevision::new(
+            scope.clone(),
+            from_i64::<DB>(incarnation, "change record incarnation")?,
+            from_i64::<DB>(revision, "change record revision")?,
+        )?),
+        (_, None, None) => None,
+        _ => {
+            return Err(corrupt_storage(
+                "projection change record revision has an inconsistent shape",
+            ))
+        }
+    };
+    let observation_kind = scope_kind
+        .as_deref()
+        .map(decode_observation_kind)
+        .transpose()?;
+    match kind {
+        ProjectionChangeKind::RecordUpsert
+        | ProjectionChangeKind::RecordDelete
+        | ProjectionChangeKind::RecordRecreate
+            if scope.is_some()
+                && revision.is_some()
+                && observation_kind.is_none()
+                && failure_id.is_none() => {}
+        ProjectionChangeKind::Observation
+            if scope.is_some()
+                && observation_kind.is_some()
+                && failure_id.is_none()
+                && ((observation_kind == Some(ProjectionObservationKind::Record)
+                    && revision.is_some())
+                    || (observation_kind == Some(ProjectionObservationKind::Dependency)
+                        && revision.is_none())) => {}
+        ProjectionChangeKind::Checkpoint
+            if scope.is_none()
+                && revision.is_none()
+                && observation_kind.is_none()
+                && failure_id.is_none() => {}
+        ProjectionChangeKind::Failure
+            if scope.is_none()
+                && revision.is_none()
+                && observation_kind.is_none()
+                && failure_id.is_some() => {}
+        _ => {
+            return Err(corrupt_storage(format!(
+                "projection change `{kind_value}` payload has an inconsistent shape"
+            )))
+        }
+    }
+    Ok(ProjectionChange {
+        cursor: ProjectionChangeCursor::new(
+            topology.clone(),
+            partition.clone(),
+            change_epoch,
+            change_position,
+        )?,
+        kind,
+        causation_id,
+        observation_kind,
+        scope,
+        revision,
+        failure_id,
+    })
+}
+
+/// Apply one sealed same-transaction command projection inside its caller's
+/// already-open domain/ledger transaction.
+///
+/// The adapter, rather than the command handler, allocates record revisions
+/// and change cursors while holding the authoritative projection partition
+/// lock. The returned evidence is attached to the command completion before
+/// the caller executes the final ledger fence.
+pub(crate) async fn apply_same_transaction_projection_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    batch: &SameTransactionProjectionBatch,
+    retention: ProjectionChangeRetention,
+) -> Result<SameTransactionProjectionEvidence, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    batch.validate()?;
+    let write_plan = TableWritePlan::new(
+        batch
+            .mutations
+            .iter()
+            .map(|mutation| mutation.mutation.clone())
+            .collect(),
+    );
+    validate_sql_write_plan(&write_plan)?;
+    verify_registered_topology_in_tx(tx, &batch.topology).await?;
+    let mut state =
+        lock_partition_in_tx(tx, &batch.topology, &batch.partition, &batch.change_epoch).await?;
+    if let Some(failure_id) = &state.stopped_failure_id {
+        return Err(ProjectionProtocolError::PartitionStopped {
+            failure_id: failure_id.clone(),
+        });
+    }
+    if state.pending_retry_failure_id.is_some() {
+        return Err(ProjectionProtocolError::IncomparableInput);
+    }
+    ensure_partition_ownership_in_tx(tx, &batch.topology, &batch.partition, &batch.ownership)
+        .await?;
+
+    let staged = batch
+        .mutations
+        .first()
+        .expect("same-transaction projection validation requires one mutation");
+    let owner = batch
+        .ownership
+        .first()
+        .expect("same-transaction projection validation requires one owner");
+    if staged.mutation.table_name() != owner.table
+        || table_model_name(&staged.mutation) != staged.scope.model()
+    {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "direct projection mutation for model `{}` does not target its registered table",
+            staged.scope.model()
+        )));
+    }
+
+    let current = record_in_tx(tx, &staged.scope, &state.change_epoch).await?;
+    let physical_exists = physical_row_exists_in_tx(tx, &staged.mutation).await?;
+    match current.as_ref().map(|record| &record.metadata) {
+        None if physical_exists => {
+            return Err(ProjectionProtocolError::RecordAlreadyExists {
+                model: staged.scope.model().to_string(),
+            });
+        }
+        Some(metadata) if metadata.tombstone => {
+            return Err(ProjectionProtocolError::RecordTombstoned {
+                model: staged.scope.model().to_string(),
+            });
+        }
+        Some(_) if !physical_exists => {
+            return Err(ProjectionProtocolError::RecordMissing {
+                model: staged.scope.model().to_string(),
+            });
+        }
+        _ => {}
+    }
+    let expectation = current
+        .as_ref()
+        .map(|record| ProjectionRecordExpectation::Exact(record.metadata.revision.clone()))
+        .unwrap_or(ProjectionRecordExpectation::Missing);
+    let (revision, tombstone) = next_record(
+        &staged.scope,
+        &expectation,
+        ProjectionMutationKind::Upsert,
+        current.as_ref(),
+    )?;
+    debug_assert!(!tombstone);
+    let change = allocate_change(
+        &mut state,
+        &batch.topology,
+        &batch.partition,
+        ProjectionChangeKind::RecordUpsert,
+        batch.causation_id.clone(),
+        None,
+        Some(staged.scope.clone()),
+        Some(revision.clone()),
+        None,
+    )?;
+    let metadata = ProjectionRecordMetadata {
+        revision: revision.clone(),
+        tombstone,
+        change: change.cursor.clone(),
+    };
+
+    let observation_request = batch
+        .observations
+        .first()
+        .expect("same-transaction projection validation requires one observation");
+    if observation_in_tx(
+        tx,
+        &batch.causation_id,
+        &staged.scope,
+        observation_request.kind,
+        &state.change_epoch,
+    )
+    .await?
+    .is_some()
+    {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "direct projection causation `{}` already has record evidence",
+            batch.causation_id
+        )));
+    }
+    let observation = ProjectionObservation {
+        causation_id: batch.causation_id.clone(),
+        kind: observation_request.kind,
+        scope: staged.scope.clone(),
+        revision: Some(revision),
+        change: change.cursor.clone(),
+    };
+
+    apply_read_model_write_plan_in_tx(tx, write_plan).await?;
+    insert_change_in_tx(tx, &change).await?;
+    upsert_record_in_tx(tx, &metadata).await?;
+    insert_observation_in_tx(tx, &observation).await?;
+    update_partition_head_in_tx(
+        tx,
+        &batch.topology,
+        &batch.partition,
+        state.change_head,
+        None,
+    )
+    .await?;
+    retain_projection_change_suffix_in_tx(tx, &batch.topology, &batch.partition, &state, retention)
+        .await?;
+
+    Ok(SameTransactionProjectionEvidence {
+        records: vec![metadata],
+        changes: vec![change],
+        observations: vec![observation],
+    })
+}
+
+/// Execute the entire query-row/evidence read as one SQL statement.
+///
+/// PostgreSQL's default transaction isolation takes a fresh snapshot for every
+/// statement, so merely wrapping independent row and metadata selects in a
+/// transaction would still permit mixed evidence. This joined statement gives
+/// SQLite and PostgreSQL the same statement-level snapshot and repeats the
+/// physical/protocol columns only when multiple explicit checkpoint probes
+/// match.
+pub(crate) async fn read_projection_query_snapshot_in_executor<'e, DB, E>(
+    executor: E,
+    request: &ProjectionQuerySnapshotRequest,
+) -> Result<ProjectionQuerySnapshot, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    E: Executor<'e, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    request.validate()?;
+    let schema = request.schema.as_ref();
+    let physical_version_column = version_column(schema)?;
+    let topology_hash = request.scope.topology().digest();
+    let partition_hash = request.scope.projection_partition().digest();
+    let key_hash = request.scope.key_digest();
+
+    let mut builder = QueryBuilder::<DB>::new("SELECT ");
+    for (index, column) in schema.columns.iter().enumerate() {
+        if index > 0 {
+            builder.push(", ");
+        }
+        builder.push("snapshot_row.");
+        builder.push(quote_identifier(&column.column_name));
+        builder.push(" AS ");
+        builder.push(quote_identifier(&format!("ps_row_{index}")));
+    }
+    if !schema.columns.is_empty() {
+        builder.push(", ");
+    }
+    builder.push("snapshot_row.");
+    builder.push(quote_identifier(physical_version_column));
+    builder.push(
+        " AS ps_row_version, \
+         registered.topology_bytes AS ps_registered_topology_bytes, \
+         registered.table_name AS ps_registered_table, \
+         partition.topology_bytes AS ps_partition_topology_bytes, \
+         partition.partition_bytes AS ps_partition_bytes, \
+         partition.active_generation AS ps_active_generation, \
+         partition.change_epoch AS ps_change_epoch, \
+         partition.change_head AS ps_change_head, \
+         partition.compacted_through AS ps_compacted, \
+         record.canonical_key_bytes AS ps_record_key_bytes, \
+         record.canonical_key_hash AS ps_record_key_hash, \
+         record.incarnation AS ps_record_incarnation, \
+         record.revision AS ps_record_revision, \
+         record.tombstone AS ps_record_tombstone, \
+         record.change_epoch AS ps_record_change_epoch, \
+         record.change_position AS ps_record_change_position, \
+         checkpoint.source_bytes AS ps_cursor_source_bytes, \
+         checkpoint.source_hash AS ps_cursor_source_hash, \
+         checkpoint.source_partition_bytes AS ps_cursor_partition_bytes, \
+         checkpoint.source_partition_hash AS ps_cursor_partition_hash, \
+         checkpoint.source_epoch AS ps_cursor_source_epoch, \
+         checkpoint.source_position AS ps_cursor_source_position, \
+         checkpoint.gap_free AS ps_cursor_gap_free, \
+         checkpoint.generation AS ps_cursor_generation, \
+         checkpoint.change_epoch AS ps_cursor_change_epoch, \
+         checkpoint.change_position AS ps_cursor_change_position \
+         FROM (SELECT 1 AS snapshot_anchor) AS snapshot_anchor \
+         LEFT JOIN (SELECT ",
+    );
+    for (index, column) in schema.columns.iter().enumerate() {
+        if index > 0 {
+            builder.push(", ");
+        }
+        DB::push_select_column(&mut builder, column);
+    }
+    if !schema.columns.is_empty() {
+        builder.push(", ");
+    }
+    builder.push(quote_identifier(physical_version_column));
+    builder.push(" FROM ");
+    builder.push(quote_identifier(&schema.table_name));
+    push_key_predicates(&mut builder, schema, &request.key)?;
+    builder.push(") AS snapshot_row ON 1 = 1 ");
+
+    builder.push(
+        "LEFT JOIN projection_registered_models AS registered \
+         ON registered.topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND registered.model_name = ");
+    builder.push_bind(request.scope.model());
+
+    builder.push(
+        " LEFT JOIN projection_partitions AS partition \
+         ON partition.topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition.partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+
+    builder.push(
+        " LEFT JOIN projection_records AS record \
+         ON record.topology_hash = partition.topology_hash \
+         AND record.partition_hash = partition.partition_hash \
+         AND record.model_name = ",
+    );
+    builder.push_bind(request.scope.model());
+    builder.push(" AND record.canonical_key_hash = ");
+    builder.push_bind(key_hash.as_slice());
+
+    builder.push(
+        " LEFT JOIN projection_input_cursors AS checkpoint \
+         ON checkpoint.topology_hash = partition.topology_hash \
+         AND checkpoint.partition_hash = partition.partition_hash AND ",
+    );
+    if request.checkpoint_probes.is_empty() {
+        builder.push("1 = 0");
+    } else {
+        builder.push("(");
+        for (index, probe) in request.checkpoint_probes.iter().enumerate() {
+            if index > 0 {
+                builder.push(" OR ");
+            }
+            builder.push("(checkpoint.source_hash = ");
+            let source_hash = probe.source.digest();
+            builder.push_bind(source_hash.as_slice());
+            builder.push(" AND checkpoint.source_partition_hash = ");
+            let source_partition_hash = probe.source.partition_digest();
+            builder.push_bind(source_partition_hash.as_slice());
+            builder.push(" AND checkpoint.generation = ");
+            builder.push_bind(to_i64::<DB>(
+                probe.generation.get(),
+                "projection generation",
+            )?);
+            builder.push(")");
+        }
+        builder.push(")");
+    }
+    builder.push(
+        " ORDER BY checkpoint.source_hash, checkpoint.source_partition_hash, \
+         checkpoint.generation",
+    );
+
+    let rows = builder.build().fetch_all(executor).await.map_err(|error| {
+        protocol_storage_error::<DB>("read atomic projection query snapshot", error)
+    })?;
+    let first = rows.first().ok_or_else(|| {
+        corrupt_storage("atomic projection query snapshot returned no anchor row")
+    })?;
+
+    let row_version: Option<i64> = first.try_get("ps_row_version").map_err(|error| {
+        protocol_storage_error::<DB>("decode projection query row presence", error)
+    })?;
+    let physical_row = if row_version.is_some() {
+        let mut values = RowValues::new();
+        for (index, column) in schema.columns.iter().enumerate() {
+            let mut aliased = column.clone();
+            aliased.column_name = format!("ps_row_{index}");
+            values.insert(column.column_name.clone(), DB::row_value(first, &aliased)?);
+        }
+        validate_row_values(schema, &values, true)?;
+        validate_values_match_key(schema, &request.key, &values)?;
+        Some(values)
+    } else {
+        None
+    };
+
+    let registered_topology: Option<Vec<u8>> = first
+        .try_get("ps_registered_topology_bytes")
+        .map_err(|error| {
+            protocol_storage_error::<DB>("decode projection query registered topology", error)
+        })?;
+    let Some(registered_topology) = registered_topology else {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "projection query model `{}` has no registered topology owner",
+            request.scope.model()
+        )));
+    };
+    verify_bytes(
+        &registered_topology,
+        &request.scope.topology().canonical_bytes(),
+        "projection query registered topology",
+    )?;
+    let registered_table: Option<String> =
+        first.try_get("ps_registered_table").map_err(|error| {
+            protocol_storage_error::<DB>("decode projection query registered table", error)
+        })?;
+    if registered_table.as_deref() != Some(schema.table_name.as_str()) {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "projection query model `{}` is registered to table `{}`, not `{}`",
+            request.scope.model(),
+            registered_table.as_deref().unwrap_or("<missing>"),
+            schema.table_name
+        )));
+    }
+
+    let active_generation: Option<i64> =
+        first.try_get("ps_active_generation").map_err(|error| {
+            protocol_storage_error::<DB>("decode projection query partition presence", error)
+        })?;
+    let partition = match active_generation {
+        Some(active_generation) => {
+            let topology_bytes: Option<Vec<u8>> = first
+                .try_get("ps_partition_topology_bytes")
+                .map_err(|error| {
+                    protocol_storage_error::<DB>(
+                        "decode projection query partition topology",
+                        error,
+                    )
+                })?;
+            let partition_bytes: Option<Vec<u8>> =
+                first.try_get("ps_partition_bytes").map_err(|error| {
+                    protocol_storage_error::<DB>("decode projection query partition bytes", error)
+                })?;
+            verify_bytes(
+                topology_bytes
+                    .as_deref()
+                    .ok_or_else(|| corrupt_storage("partition topology bytes are missing"))?,
+                &request.scope.topology().canonical_bytes(),
+                "projection query partition topology",
+            )?;
+            verify_bytes(
+                partition_bytes
+                    .as_deref()
+                    .ok_or_else(|| corrupt_storage("partition bytes are missing"))?,
+                request.scope.projection_partition().canonical_bytes(),
+                "projection query partition",
+            )?;
+            let change_epoch: Option<String> =
+                first.try_get("ps_change_epoch").map_err(|error| {
+                    protocol_storage_error::<DB>("decode projection query change epoch", error)
+                })?;
+            let change_head: Option<i64> = first.try_get("ps_change_head").map_err(|error| {
+                protocol_storage_error::<DB>("decode projection query change head", error)
+            })?;
+            let compacted_through: Option<i64> =
+                first.try_get("ps_compacted").map_err(|error| {
+                    protocol_storage_error::<DB>(
+                        "decode projection query compaction watermark",
+                        error,
+                    )
+                })?;
+            let state = PartitionState {
+                active_generation: ProjectionGeneration::new(from_i64::<DB>(
+                    active_generation,
+                    "projection active generation",
+                )?)?,
+                change_epoch: ProjectionEpoch::new(
+                    change_epoch
+                        .ok_or_else(|| corrupt_storage("partition change epoch is missing"))?,
+                )?,
+                change_head: from_i64::<DB>(
+                    change_head
+                        .ok_or_else(|| corrupt_storage("partition change head is missing"))?,
+                    "projection change head",
+                )?,
+                compacted_through: from_i64::<DB>(
+                    compacted_through.ok_or_else(|| {
+                        corrupt_storage("partition compaction watermark is missing")
+                    })?,
+                    "projection compaction watermark",
+                )?,
+                pending_retry_failure_id: None,
+                stopped_failure_id: None,
+            };
+            if state.compacted_through > state.change_head {
+                return Err(corrupt_storage(
+                    "projection compaction watermark exceeds change head",
+                ));
+            }
+            Some(state)
+        }
+        None => None,
+    };
+
+    let record_incarnation: Option<i64> =
+        first.try_get("ps_record_incarnation").map_err(|error| {
+            protocol_storage_error::<DB>("decode projection query record presence", error)
+        })?;
+    let record = match record_incarnation {
+        Some(incarnation) => {
+            let Some(partition) = partition.as_ref() else {
+                return Err(corrupt_storage(
+                    "projection record exists without partition state",
+                ));
+            };
+            let key_bytes: Option<Vec<u8>> =
+                first.try_get("ps_record_key_bytes").map_err(|error| {
+                    protocol_storage_error::<DB>("decode projection query record key bytes", error)
+                })?;
+            let stored_key_hash: Option<Vec<u8>> =
+                first.try_get("ps_record_key_hash").map_err(|error| {
+                    protocol_storage_error::<DB>("decode projection query record key hash", error)
+                })?;
+            verify_bytes(
+                key_bytes
+                    .as_deref()
+                    .ok_or_else(|| corrupt_storage("projection record key bytes are missing"))?,
+                request.scope.canonical_key_bytes(),
+                "projection query record key",
+            )?;
+            verify_digest(
+                stored_key_hash
+                    .as_deref()
+                    .ok_or_else(|| corrupt_storage("projection record key hash is missing"))?,
+                request.scope.key_digest(),
+                "projection query record key",
+            )?;
+            let revision: Option<i64> = first.try_get("ps_record_revision").map_err(|error| {
+                protocol_storage_error::<DB>("decode projection query record revision", error)
+            })?;
+            let tombstone: Option<i64> = first.try_get("ps_record_tombstone").map_err(|error| {
+                protocol_storage_error::<DB>("decode projection query record tombstone", error)
+            })?;
+            let tombstone = match tombstone
+                .ok_or_else(|| corrupt_storage("projection record tombstone is missing"))?
+            {
+                0 => false,
+                1 => true,
+                value => {
+                    return Err(corrupt_storage(format!(
+                        "record tombstone contains invalid value {value}"
+                    )))
+                }
+            };
+            let record_change_epoch: Option<String> =
+                first.try_get("ps_record_change_epoch").map_err(|error| {
+                    protocol_storage_error::<DB>(
+                        "decode projection query record change epoch",
+                        error,
+                    )
+                })?;
+            let record_change_epoch = ProjectionEpoch::new(
+                record_change_epoch
+                    .ok_or_else(|| corrupt_storage("record change epoch is missing"))?,
+            )?;
+            if record_change_epoch != partition.change_epoch {
+                return Err(corrupt_storage(
+                    "projection record change epoch differs from its partition",
+                ));
+            }
+            let record_change_position: Option<i64> = first
+                .try_get("ps_record_change_position")
+                .map_err(|error| {
+                    protocol_storage_error::<DB>(
+                        "decode projection query record change position",
+                        error,
+                    )
+                })?;
+            let record_change_position = from_i64::<DB>(
+                record_change_position
+                    .ok_or_else(|| corrupt_storage("record change position is missing"))?,
+                "projection record change position",
+            )?;
+            if record_change_position > partition.change_head {
+                return Err(corrupt_storage(
+                    "projection record change exceeds its partition head",
+                ));
+            }
+            Some(ProjectionRecordMetadata {
+                revision: RecordRevision::new(
+                    request.scope.clone(),
+                    from_i64::<DB>(incarnation, "projection record incarnation")?,
+                    from_i64::<DB>(
+                        revision.ok_or_else(|| corrupt_storage("record revision is missing"))?,
+                        "projection record revision",
+                    )?,
+                )?,
+                tombstone,
+                change: ProjectionChangeCursor::new(
+                    request.scope.topology().clone(),
+                    request.scope.projection_partition().clone(),
+                    record_change_epoch,
+                    record_change_position,
+                )?,
+            })
+        }
+        None => None,
+    };
+
+    match (physical_row.is_some(), record.as_ref()) {
+        (true, None)
+        | (
+            true,
+            Some(ProjectionRecordMetadata {
+                tombstone: true, ..
+            }),
+        ) => {
+            return Err(ProjectionProtocolError::RecordAlreadyExists {
+                model: request.scope.model().to_string(),
+            });
+        }
+        (
+            false,
+            Some(ProjectionRecordMetadata {
+                tombstone: false, ..
+            }),
+        ) => {
+            return Err(ProjectionProtocolError::RecordMissing {
+                model: request.scope.model().to_string(),
+            });
+        }
+        _ => {}
+    }
+
+    let mut checkpoint_values = vec![None; request.checkpoint_probes.len()];
+    for row in &rows {
+        let stored_generation: Option<i64> =
+            row.try_get("ps_cursor_generation").map_err(|error| {
+                protocol_storage_error::<DB>("decode projection query checkpoint presence", error)
+            })?;
+        let Some(stored_generation) = stored_generation else {
+            continue;
+        };
+        let Some(partition) = partition.as_ref() else {
+            return Err(corrupt_storage(
+                "projection checkpoint exists without partition state",
+            ));
+        };
+        let generation = ProjectionGeneration::new(from_i64::<DB>(
+            stored_generation,
+            "projection checkpoint generation",
+        )?)?;
+        let source_bytes: Option<Vec<u8>> =
+            row.try_get("ps_cursor_source_bytes").map_err(|error| {
+                protocol_storage_error::<DB>(
+                    "decode projection query checkpoint source bytes",
+                    error,
+                )
+            })?;
+        let source_hash: Option<Vec<u8>> =
+            row.try_get("ps_cursor_source_hash").map_err(|error| {
+                protocol_storage_error::<DB>(
+                    "decode projection query checkpoint source hash",
+                    error,
+                )
+            })?;
+        let source_partition_bytes: Option<Vec<u8>> =
+            row.try_get("ps_cursor_partition_bytes").map_err(|error| {
+                protocol_storage_error::<DB>(
+                    "decode projection query checkpoint source partition bytes",
+                    error,
+                )
+            })?;
+        let source_partition_hash: Option<Vec<u8>> =
+            row.try_get("ps_cursor_partition_hash").map_err(|error| {
+                protocol_storage_error::<DB>(
+                    "decode projection query checkpoint source partition hash",
+                    error,
+                )
+            })?;
+        let source_hash = source_hash
+            .as_deref()
+            .ok_or_else(|| corrupt_storage("checkpoint source hash is missing"))?;
+        let source_partition_hash = source_partition_hash
+            .as_deref()
+            .ok_or_else(|| corrupt_storage("checkpoint source partition hash is missing"))?;
+        let Some(probe_index) = request.checkpoint_probes.iter().position(|probe| {
+            probe.generation == generation
+                && source_hash == probe.source.digest().as_slice()
+                && source_partition_hash == probe.source.partition_digest().as_slice()
+        }) else {
+            return Err(corrupt_storage(
+                "checkpoint row does not match an explicit query probe",
+            ));
+        };
+        let probe = &request.checkpoint_probes[probe_index];
+        verify_bytes(
+            source_bytes
+                .as_deref()
+                .ok_or_else(|| corrupt_storage("checkpoint source bytes are missing"))?,
+            &probe.source.canonical_name_bytes(),
+            "projection query checkpoint source",
+        )?;
+        verify_digest(
+            source_hash,
+            probe.source.digest(),
+            "projection query checkpoint source",
+        )?;
+        verify_bytes(
+            source_partition_bytes
+                .as_deref()
+                .ok_or_else(|| corrupt_storage("checkpoint source partition bytes are missing"))?,
+            probe.source.canonical_partition_bytes(),
+            "projection query checkpoint source partition",
+        )?;
+        verify_digest(
+            source_partition_hash,
+            probe.source.partition_digest(),
+            "projection query checkpoint source partition",
+        )?;
+        let source_epoch: Option<String> =
+            row.try_get("ps_cursor_source_epoch").map_err(|error| {
+                protocol_storage_error::<DB>(
+                    "decode projection query checkpoint source epoch",
+                    error,
+                )
+            })?;
+        let source_epoch = ProjectionEpoch::new(
+            source_epoch.ok_or_else(|| corrupt_storage("checkpoint source epoch is missing"))?,
+        )?;
+        if source_epoch != probe.epoch {
+            return Err(ProjectionProtocolError::IncomparableInput);
+        }
+        let source_position: Option<i64> =
+            row.try_get("ps_cursor_source_position").map_err(|error| {
+                protocol_storage_error::<DB>(
+                    "decode projection query checkpoint source position",
+                    error,
+                )
+            })?;
+        let gap_free: Option<i64> = row.try_get("ps_cursor_gap_free").map_err(|error| {
+            protocol_storage_error::<DB>("decode projection query checkpoint gap-free flag", error)
+        })?;
+        let gap_free =
+            match gap_free.ok_or_else(|| corrupt_storage("checkpoint gap-free flag is missing"))? {
+                0 => false,
+                1 => true,
+                value => {
+                    return Err(corrupt_storage(format!(
+                        "cursor gap-free flag contains invalid value {value}"
+                    )))
+                }
+            };
+        let checkpoint_change_epoch: Option<String> =
+            row.try_get("ps_cursor_change_epoch").map_err(|error| {
+                protocol_storage_error::<DB>(
+                    "decode projection query checkpoint change epoch",
+                    error,
+                )
+            })?;
+        let checkpoint_change_epoch = ProjectionEpoch::new(
+            checkpoint_change_epoch
+                .ok_or_else(|| corrupt_storage("checkpoint change epoch is missing"))?,
+        )?;
+        let checkpoint_change_position: Option<i64> =
+            row.try_get("ps_cursor_change_position").map_err(|error| {
+                protocol_storage_error::<DB>(
+                    "decode projection query checkpoint change position",
+                    error,
+                )
+            })?;
+        let checkpoint_change_position = from_i64::<DB>(
+            checkpoint_change_position
+                .ok_or_else(|| corrupt_storage("checkpoint change position is missing"))?,
+            "projection checkpoint change position",
+        )?;
+        if checkpoint_change_epoch != partition.change_epoch
+            || checkpoint_change_position > partition.change_head
+        {
+            return Err(corrupt_storage(
+                "projection checkpoint change lies outside its partition head",
+            ));
+        }
+        let checkpoint = ProjectionCheckpoint::new(
+            ProjectionInputCursor::new(
+                probe.topology.clone(),
+                probe.partition.clone(),
+                probe.source.clone(),
+                source_epoch,
+                from_i64::<DB>(
+                    source_position
+                        .ok_or_else(|| corrupt_storage("checkpoint source position is missing"))?,
+                    "projection checkpoint source position",
+                )?,
+            )?,
+            ProjectionChangeCursor::new(
+                probe.topology.clone(),
+                probe.partition.clone(),
+                checkpoint_change_epoch,
+                checkpoint_change_position,
+            )?,
+            gap_free,
+        )?;
+        if checkpoint_values[probe_index].replace(checkpoint).is_some() {
+            return Err(corrupt_storage(
+                "projection query returned duplicate checkpoint rows",
+            ));
+        }
+    }
+
+    let checkpoints = request
+        .checkpoint_probes
+        .iter()
+        .cloned()
+        .zip(checkpoint_values)
+        .map(
+            |(probe, checkpoint)| crate::projection_protocol::ProjectionCheckpointSnapshot {
+                probe,
+                checkpoint,
+            },
+        )
+        .collect();
+    let (change_head, compacted_through) = match partition {
+        Some(partition) => {
+            let head = if partition.change_head == 0 {
+                None
+            } else {
+                Some(ProjectionChangeCursor::new(
+                    request.scope.topology().clone(),
+                    request.scope.projection_partition().clone(),
+                    partition.change_epoch,
+                    partition.change_head,
+                )?)
+            };
+            (head, partition.compacted_through)
+        }
+        None => (None, 0),
+    };
+
+    Ok(ProjectionQuerySnapshot {
+        row: physical_row,
+        record,
+        checkpoints,
+        change_head,
+        compacted_through,
+    })
+}
+
+/// Resolve a bounded command-obligation set from one existing SQL snapshot.
+///
+/// Observations and failures are read in two set queries on the same borrowed
+/// connection. A durable failure is immutable and therefore wins even when an
+/// observation for the same causation also exists or its change entry has been
+/// compacted.
+pub(crate) async fn read_projection_obligation_evidence_batch_in_executor<DB>(
+    connection: &mut DB::Connection,
+    request: &ProjectionObligationEvidenceBatchRequest,
+) -> Result<ProjectionObligationEvidenceBatch, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    request.validate()?;
+    if request.requests.is_empty() {
+        return Ok(ProjectionObligationEvidenceBatch::default());
+    }
+
+    let mut observations = vec![None; request.requests.len()];
+    let mut observation_query = QueryBuilder::<DB>::new(
+        "SELECT observation.topology_hash AS evidence_topology_hash, \
+         observation.partition_hash AS evidence_partition_hash, \
+         observation.causation_id AS evidence_causation_id, \
+         observation.model_name AS evidence_model_name, \
+         observation.scope_kind AS evidence_scope_kind, \
+         observation.canonical_key_bytes, observation.canonical_key_hash, \
+         observation.incarnation, observation.revision, observation.change_epoch, \
+         observation.change_position, partition.topology_bytes AS evidence_topology_bytes, \
+         partition.partition_bytes AS evidence_partition_bytes, \
+         partition.change_epoch AS evidence_partition_epoch, \
+         partition.change_head AS evidence_partition_head \
+         FROM projection_observations AS observation \
+         INNER JOIN projection_partitions AS partition \
+         ON partition.topology_hash = observation.topology_hash \
+         AND partition.partition_hash = observation.partition_hash WHERE ",
+    );
+    for (index, probe) in request.requests.iter().enumerate() {
+        if index > 0 {
+            observation_query.push(" OR ");
+        }
+        let topology_hash = probe.scope.topology().digest();
+        let partition_hash = probe.scope.projection_partition().digest();
+        let key_hash = probe.scope.key_digest();
+        observation_query.push("(observation.topology_hash = ");
+        observation_query.push_bind(topology_hash.as_slice());
+        observation_query.push(" AND observation.partition_hash = ");
+        observation_query.push_bind(partition_hash.as_slice());
+        observation_query.push(" AND observation.causation_id = ");
+        observation_query.push_bind(probe.causation_id.as_str());
+        observation_query.push(" AND observation.model_name = ");
+        observation_query.push_bind(probe.scope.model());
+        observation_query.push(" AND observation.scope_kind = ");
+        observation_query.push_bind(probe.kind.as_storage_str());
+        observation_query.push(" AND observation.canonical_key_hash = ");
+        observation_query.push_bind(key_hash.as_slice());
+        observation_query.push(")");
+    }
+    let observation_rows = observation_query
+        .build()
+        .fetch_all(&mut *connection)
+        .await
+        .map_err(|error| {
+            protocol_storage_error::<DB>("read projection obligation observations", error)
+        })?;
+    for row in observation_rows {
+        let topology_hash = decode_digest(
+            row.try_get("evidence_topology_hash").map_err(|error| {
+                protocol_storage_error::<DB>("decode evidence topology hash", error)
+            })?,
+            "projection evidence topology",
+        )?;
+        let partition_hash = decode_digest(
+            row.try_get("evidence_partition_hash").map_err(|error| {
+                protocol_storage_error::<DB>("decode evidence partition hash", error)
+            })?,
+            "projection evidence partition",
+        )?;
+        let causation_id: String = row
+            .try_get("evidence_causation_id")
+            .map_err(|error| protocol_storage_error::<DB>("decode evidence causation ID", error))?;
+        let model: String = row
+            .try_get("evidence_model_name")
+            .map_err(|error| protocol_storage_error::<DB>("decode evidence model", error))?;
+        let kind_value: String = row.try_get("evidence_scope_kind").map_err(|error| {
+            protocol_storage_error::<DB>("decode evidence observation kind", error)
+        })?;
+        let kind = decode_observation_kind(&kind_value)?;
+        let key_hash = decode_digest(
+            row.try_get("canonical_key_hash")
+                .map_err(|error| protocol_storage_error::<DB>("decode evidence key hash", error))?,
+            "projection evidence key",
+        )?;
+        let key_bytes: Vec<u8> = row
+            .try_get("canonical_key_bytes")
+            .map_err(|error| protocol_storage_error::<DB>("decode evidence key bytes", error))?;
+        let digest_candidates = request
+            .requests
+            .iter()
+            .enumerate()
+            .filter(|(_, probe)| {
+                probe.scope.topology().digest() == topology_hash
+                    && probe.scope.projection_partition().digest() == partition_hash
+                    && probe.causation_id == causation_id
+                    && probe.scope.model() == model
+                    && probe.kind == kind
+                    && probe.scope.key_digest() == key_hash
+            })
+            .collect::<Vec<_>>();
+        let exact = digest_candidates
+            .iter()
+            .filter(|(_, probe)| probe.scope.canonical_key_bytes() == key_bytes.as_slice())
+            .map(|(index, _)| *index)
+            .collect::<Vec<_>>();
+        let [index] = exact.as_slice() else {
+            return Err(corrupt_storage(if digest_candidates.is_empty() {
+                "projection observation escaped its bounded evidence predicate".to_string()
+            } else {
+                "projection observation canonical key does not match its digest lookup".to_string()
+            }));
+        };
+        let probe = &request.requests[*index];
+        let topology_bytes: Vec<u8> = row.try_get("evidence_topology_bytes").map_err(|error| {
+            protocol_storage_error::<DB>("decode evidence topology bytes", error)
+        })?;
+        verify_bytes(
+            &topology_bytes,
+            &probe.scope.topology().canonical_bytes(),
+            "projection evidence topology",
+        )?;
+        let partition_bytes: Vec<u8> =
+            row.try_get("evidence_partition_bytes").map_err(|error| {
+                protocol_storage_error::<DB>("decode evidence partition bytes", error)
+            })?;
+        verify_bytes(
+            &partition_bytes,
+            probe.scope.projection_partition().canonical_bytes(),
+            "projection evidence partition",
+        )?;
+        let partition_epoch = ProjectionEpoch::new(
+            row.try_get::<String, _>("evidence_partition_epoch")
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("decode evidence partition epoch", error)
+                })?,
+        )?;
+        let partition_head = from_i64::<DB>(
+            row.try_get("evidence_partition_head").map_err(|error| {
+                protocol_storage_error::<DB>("decode evidence partition head", error)
+            })?,
+            "projection evidence partition head",
+        )?;
+        let observation = decode_observation_row::<DB>(
+            &row,
+            &probe.causation_id,
+            &probe.scope,
+            probe.kind,
+            &partition_epoch,
+        )?;
+        if observation.change.position() > partition_head {
+            return Err(corrupt_storage(
+                "projection observation change exceeds its partition head",
+            ));
+        }
+        if observations[*index].replace(observation).is_some() {
+            return Err(corrupt_storage(
+                "projection obligation evidence returned duplicate observations",
+            ));
+        }
+    }
+
+    let mut failures = vec![None; request.requests.len()];
+    let mut failure_query = QueryBuilder::<DB>::new(
+        "SELECT failure.topology_hash AS evidence_topology_hash, \
+         failure.partition_hash AS evidence_partition_hash, failure.failure_id, \
+         failure.source_bytes, failure.source_hash, failure.source_partition_bytes, \
+         failure.source_partition_hash, failure.source_epoch, failure.source_position, \
+         failure.input_hash, failure.message_id, failure.causation_id, failure.gap_free, \
+         failure.generation, failure.failure_code, failure.failure_bytes, \
+         failure.failure_hash, failure.change_epoch, failure.change_position, \
+         partition.topology_bytes AS evidence_topology_bytes, \
+         partition.partition_bytes AS evidence_partition_bytes, \
+         partition.change_epoch AS evidence_partition_epoch, \
+         partition.change_head AS evidence_partition_head \
+         FROM projection_failures AS failure \
+         INNER JOIN projection_partitions AS partition \
+         ON partition.topology_hash = failure.topology_hash \
+         AND partition.partition_hash = failure.partition_hash WHERE ",
+    );
+    for (index, probe) in request.requests.iter().enumerate() {
+        if index > 0 {
+            failure_query.push(" OR ");
+        }
+        let topology_hash = probe.scope.topology().digest();
+        let partition_hash = probe.scope.projection_partition().digest();
+        failure_query.push("(failure.topology_hash = ");
+        failure_query.push_bind(topology_hash.as_slice());
+        failure_query.push(" AND failure.partition_hash = ");
+        failure_query.push_bind(partition_hash.as_slice());
+        failure_query.push(" AND failure.causation_id = ");
+        failure_query.push_bind(probe.causation_id.as_str());
+        failure_query.push(")");
+    }
+    failure_query.push(
+        " ORDER BY failure.topology_hash, failure.partition_hash, \
+         failure.causation_id, failure.change_position, failure.failure_id",
+    );
+    let failure_rows = failure_query
+        .build()
+        .fetch_all(&mut *connection)
+        .await
+        .map_err(|error| {
+            protocol_storage_error::<DB>("read projection obligation failures", error)
+        })?;
+    for row in failure_rows {
+        let topology_hash = decode_digest(
+            row.try_get("evidence_topology_hash").map_err(|error| {
+                protocol_storage_error::<DB>("decode failure evidence topology hash", error)
+            })?,
+            "projection failure evidence topology",
+        )?;
+        let partition_hash = decode_digest(
+            row.try_get("evidence_partition_hash").map_err(|error| {
+                protocol_storage_error::<DB>("decode failure evidence partition hash", error)
+            })?,
+            "projection failure evidence partition",
+        )?;
+        let causation_id: String = row.try_get("causation_id").map_err(|error| {
+            protocol_storage_error::<DB>("decode failure evidence causation ID", error)
+        })?;
+        let matching = request
+            .requests
+            .iter()
+            .enumerate()
+            .filter(|(_, probe)| {
+                probe.scope.topology().digest() == topology_hash
+                    && probe.scope.projection_partition().digest() == partition_hash
+                    && probe.causation_id == causation_id
+            })
+            .map(|(index, _)| index)
+            .collect::<Vec<_>>();
+        let Some(first_index) = matching.first().copied() else {
+            return Err(corrupt_storage(
+                "projection failure escaped its bounded evidence predicate",
+            ));
+        };
+        let first = &request.requests[first_index];
+        let topology_bytes: Vec<u8> = row.try_get("evidence_topology_bytes").map_err(|error| {
+            protocol_storage_error::<DB>("decode failure evidence topology bytes", error)
+        })?;
+        verify_bytes(
+            &topology_bytes,
+            &first.scope.topology().canonical_bytes(),
+            "projection failure evidence topology",
+        )?;
+        let partition_bytes: Vec<u8> =
+            row.try_get("evidence_partition_bytes").map_err(|error| {
+                protocol_storage_error::<DB>("decode failure evidence partition bytes", error)
+            })?;
+        verify_bytes(
+            &partition_bytes,
+            first.scope.projection_partition().canonical_bytes(),
+            "projection failure evidence partition",
+        )?;
+        let partition_epoch = ProjectionEpoch::new(
+            row.try_get::<String, _>("evidence_partition_epoch")
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("decode failure evidence partition epoch", error)
+                })?,
+        )?;
+        let partition_head = from_i64::<DB>(
+            row.try_get("evidence_partition_head").map_err(|error| {
+                protocol_storage_error::<DB>("decode failure evidence partition head", error)
+            })?,
+            "projection failure evidence partition head",
+        )?;
+        let failure = decode_failure_row::<DB>(
+            &row,
+            first.scope.topology(),
+            first.scope.projection_partition(),
+            &partition_epoch,
+        )?
+        .failure;
+        if failure.causation_id != causation_id || failure.change.position() > partition_head {
+            return Err(corrupt_storage(
+                "projection failure evidence lies outside its exact partition/causation",
+            ));
+        }
+        // Rows are ordered by change position, so retaining the first durable
+        // failure preserves the command promise's original terminal outcome.
+        for index in matching {
+            if failures[index].is_none() {
+                failures[index] = Some(failure.clone());
+            }
+        }
+    }
+
+    let evidence = failures
+        .into_iter()
+        .zip(observations)
+        .map(|(failure, observation)| match (failure, observation) {
+            (Some(failure), _) => ProjectionObligationEvidence::TerminalFailure(failure),
+            (None, Some(observation)) => ProjectionObligationEvidence::Observed(observation),
+            (None, None) => ProjectionObligationEvidence::Pending,
+        })
+        .collect();
+    Ok(ProjectionObligationEvidenceBatch { evidence })
+}
+
+/// Recover exact live record scopes for typed physical-row keys without
+/// requiring the caller to know hidden projection partitions.
+pub(crate) async fn read_projection_live_record_batch_in_executor<DB>(
+    connection: &mut DB::Connection,
+    request: &ProjectionLiveRecordBatchRequest,
+) -> Result<ProjectionLiveRecordBatch, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    request.validate()?;
+    if request.requests.is_empty() {
+        return Ok(ProjectionLiveRecordBatch::default());
+    }
+
+    let mut registered = vec![false; request.requests.len()];
+    let mut registration_query = QueryBuilder::<DB>::new(
+        "SELECT topology_bytes, topology_hash, model_name, table_name \
+         FROM projection_registered_models WHERE ",
+    );
+    for (index, probe) in request.requests.iter().enumerate() {
+        if index > 0 {
+            registration_query.push(" OR ");
+        }
+        let topology_hash = probe.topology.digest();
+        registration_query.push("(topology_hash = ");
+        registration_query.push_bind(topology_hash.as_slice());
+        registration_query.push(" AND model_name = ");
+        registration_query.push_bind(probe.model());
+        registration_query.push(")");
+    }
+    let registration_rows = registration_query
+        .build()
+        .fetch_all(&mut *connection)
+        .await
+        .map_err(|error| {
+            protocol_storage_error::<DB>("read projection live-record registrations", error)
+        })?;
+    for row in registration_rows {
+        let topology_hash = decode_digest(
+            row.try_get("topology_hash").map_err(|error| {
+                protocol_storage_error::<DB>("decode live-record topology hash", error)
+            })?,
+            "projection live-record topology",
+        )?;
+        let model: String = row.try_get("model_name").map_err(|error| {
+            protocol_storage_error::<DB>("decode live-record registered model", error)
+        })?;
+        let topology_bytes: Vec<u8> = row.try_get("topology_bytes").map_err(|error| {
+            protocol_storage_error::<DB>("decode live-record topology bytes", error)
+        })?;
+        let table: String = row.try_get("table_name").map_err(|error| {
+            protocol_storage_error::<DB>("decode live-record registered table", error)
+        })?;
+        let matching = request
+            .requests
+            .iter()
+            .enumerate()
+            .filter(|(_, probe)| probe.topology.digest() == topology_hash && probe.model() == model)
+            .map(|(index, _)| index)
+            .collect::<Vec<_>>();
+        if matching.is_empty() {
+            return Err(corrupt_storage(
+                "projection registration escaped its bounded live-record predicate",
+            ));
+        }
+        for index in matching {
+            let probe = &request.requests[index];
+            verify_bytes(
+                &topology_bytes,
+                &probe.topology.canonical_bytes(),
+                "projection live-record topology",
+            )?;
+            if table != probe.schema.table_name {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection live-record model `{}` is registered to table `{table}`, not `{}`",
+                    probe.model(),
+                    probe.schema.table_name
+                )));
+            }
+            if std::mem::replace(&mut registered[index], true) {
+                return Err(corrupt_storage(
+                    "projection live-record model has duplicate registrations",
+                ));
+            }
+        }
+    }
+    for (index, is_registered) in registered.into_iter().enumerate() {
+        if !is_registered {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection live-record model `{}` has no registered topology owner",
+                request.requests[index].model()
+            )));
+        }
+    }
+
+    let mut record_query = QueryBuilder::<DB>::new(
+        "SELECT record.topology_hash AS live_topology_hash, record.partition_hash AS \
+         live_partition_hash, record.model_name AS live_model_name, \
+         record.canonical_key_bytes, record.canonical_key_hash, record.incarnation, \
+         record.revision, record.tombstone, record.change_epoch, record.change_position, \
+         partition.topology_bytes AS live_topology_bytes, \
+         partition.partition_bytes AS live_partition_bytes, \
+         partition.change_epoch AS live_partition_epoch, \
+         partition.change_head AS live_partition_head \
+         FROM projection_records AS record \
+         INNER JOIN projection_partitions AS partition \
+         ON partition.topology_hash = record.topology_hash \
+         AND partition.partition_hash = record.partition_hash \
+         WHERE record.tombstone = 0 AND (",
+    );
+    for (index, probe) in request.requests.iter().enumerate() {
+        if index > 0 {
+            record_query.push(" OR ");
+        }
+        let topology_hash = probe.topology.digest();
+        record_query.push("(record.topology_hash = ");
+        record_query.push_bind(topology_hash.as_slice());
+        record_query.push(" AND record.model_name = ");
+        record_query.push_bind(probe.model());
+        record_query.push(" AND record.canonical_key_hash = ");
+        record_query.push_bind(probe.canonical_key_hash.as_slice());
+        record_query.push(")");
+    }
+    record_query.push(")");
+    let rows = record_query
+        .build()
+        .fetch_all(&mut *connection)
+        .await
+        .map_err(|error| {
+            protocol_storage_error::<DB>("read projection live-record evidence", error)
+        })?;
+    let mut records = vec![None; request.requests.len()];
+    for row in rows {
+        let topology_hash = decode_digest(
+            row.try_get("live_topology_hash").map_err(|error| {
+                protocol_storage_error::<DB>("decode live-record topology hash", error)
+            })?,
+            "projection live-record topology",
+        )?;
+        let model: String = row
+            .try_get("live_model_name")
+            .map_err(|error| protocol_storage_error::<DB>("decode live-record model", error))?;
+        let key_hash = decode_digest(
+            row.try_get("canonical_key_hash").map_err(|error| {
+                protocol_storage_error::<DB>("decode live-record key hash", error)
+            })?,
+            "projection live-record key",
+        )?;
+        let key_bytes: Vec<u8> = row
+            .try_get("canonical_key_bytes")
+            .map_err(|error| protocol_storage_error::<DB>("decode live-record key bytes", error))?;
+        let digest_candidates = request
+            .requests
+            .iter()
+            .enumerate()
+            .filter(|(_, probe)| {
+                probe.topology.digest() == topology_hash
+                    && probe.model() == model
+                    && probe.canonical_key_hash == key_hash
+            })
+            .collect::<Vec<_>>();
+        let exact = digest_candidates
+            .iter()
+            .filter(|(_, probe)| probe.canonical_key_bytes == key_bytes)
+            .map(|(index, _)| *index)
+            .collect::<Vec<_>>();
+        let [index] = exact.as_slice() else {
+            return Err(corrupt_storage(if digest_candidates.is_empty() {
+                "projection record escaped its bounded live-record predicate".to_string()
+            } else {
+                "projection live-record canonical key does not match its digest lookup".to_string()
+            }));
+        };
+        let probe = &request.requests[*index];
+        let topology_bytes: Vec<u8> = row.try_get("live_topology_bytes").map_err(|error| {
+            protocol_storage_error::<DB>("decode live-record topology bytes", error)
+        })?;
+        verify_bytes(
+            &topology_bytes,
+            &probe.topology.canonical_bytes(),
+            "projection live-record topology",
+        )?;
+        let partition_bytes: Vec<u8> = row.try_get("live_partition_bytes").map_err(|error| {
+            protocol_storage_error::<DB>("decode live-record partition bytes", error)
+        })?;
+        let partition = ProjectionPartition::new(partition_bytes)?;
+        let stored_partition_hash: Vec<u8> =
+            row.try_get("live_partition_hash").map_err(|error| {
+                protocol_storage_error::<DB>("decode live-record partition hash", error)
+            })?;
+        verify_digest(
+            &stored_partition_hash,
+            partition.digest(),
+            "projection live-record partition",
+        )?;
+        let scope = ProjectionRecordScope::new(
+            probe.topology.clone(),
+            partition,
+            probe.model().to_string(),
+            key_bytes,
+        )?;
+        verify_digest(&key_hash, scope.key_digest(), "projection live-record key")?;
+        let incarnation = from_i64::<DB>(
+            row.try_get("incarnation").map_err(|error| {
+                protocol_storage_error::<DB>("decode live-record incarnation", error)
+            })?,
+            "projection live-record incarnation",
+        )?;
+        let revision = from_i64::<DB>(
+            row.try_get("revision").map_err(|error| {
+                protocol_storage_error::<DB>("decode live-record revision", error)
+            })?,
+            "projection live-record revision",
+        )?;
+        let tombstone: i64 = row
+            .try_get("tombstone")
+            .map_err(|error| protocol_storage_error::<DB>("decode live-record tombstone", error))?;
+        if tombstone != 0 {
+            return Err(corrupt_storage(
+                "projection live-record lookup returned a tombstone",
+            ));
+        }
+        let partition_epoch =
+            ProjectionEpoch::new(row.try_get::<String, _>("live_partition_epoch").map_err(
+                |error| protocol_storage_error::<DB>("decode live-record partition epoch", error),
+            )?)?;
+        let change_epoch =
+            ProjectionEpoch::new(row.try_get::<String, _>("change_epoch").map_err(|error| {
+                protocol_storage_error::<DB>("decode live-record change epoch", error)
+            })?)?;
+        if change_epoch != partition_epoch {
+            return Err(corrupt_storage(
+                "projection live-record change epoch differs from its partition",
+            ));
+        }
+        let change_position = from_i64::<DB>(
+            row.try_get("change_position").map_err(|error| {
+                protocol_storage_error::<DB>("decode live-record change position", error)
+            })?,
+            "projection live-record change position",
+        )?;
+        let partition_head = from_i64::<DB>(
+            row.try_get("live_partition_head").map_err(|error| {
+                protocol_storage_error::<DB>("decode live-record partition head", error)
+            })?,
+            "projection live-record partition head",
+        )?;
+        if change_position > partition_head {
+            return Err(corrupt_storage(
+                "projection live-record change exceeds its partition head",
+            ));
+        }
+        let metadata = ProjectionRecordMetadata {
+            revision: RecordRevision::new(scope.clone(), incarnation, revision)?,
+            tombstone: false,
+            change: ProjectionChangeCursor::new(
+                scope.topology().clone(),
+                scope.projection_partition().clone(),
+                change_epoch,
+                change_position,
+            )?,
+        };
+        if records[*index].replace(metadata).is_some() {
+            return Err(corrupt_storage(format!(
+                "projection live-record identity for model `{}` is ambiguous across partitions",
+                probe.model()
+            )));
+        }
+    }
+    Ok(ProjectionLiveRecordBatch { records })
+}
+
+/// Boxed operation run inside one framework-owned projection read snapshot.
+///
+/// The boxed lifetime prevents callers from leaking the borrowed connection
+/// beyond the transaction boundary.
+pub(crate) type ProjectionReadSnapshotFuture<'a, T> =
+    Pin<Box<dyn Future<Output = Result<T, ProjectionProtocolError>> + Send + 'a>>;
+
+/// Run a physical query plan and all of its causal-evidence probes in one
+/// repeatable database snapshot.
+///
+/// PostgreSQL uses `REPEATABLE READ READ ONLY`; its default READ COMMITTED
+/// isolation would let each metadata statement observe a newer commit than the
+/// physical GraphQL statement. SQLite holds one ordinary read transaction,
+/// whose first read establishes the snapshot for the remaining plan.
+pub(crate) async fn with_projection_read_snapshot<DB, T, F>(
+    pool: &Pool<DB>,
+    operation: F,
+) -> Result<T, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    T: Send,
+    F: for<'connection> FnOnce(
+            &'connection mut DB::Connection,
+        ) -> ProjectionReadSnapshotFuture<'connection, T>
+        + Send,
+    DB::Arguments: IntoArguments<DB>,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+{
+    let mut tx = pool
+        .begin()
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("begin projection read snapshot", error))?;
+    if DB::BACKEND == "postgres" {
+        sqlx::query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY")
+            .execute(&mut *tx)
+            .await
+            .map_err(|error| {
+                protocol_storage_error::<DB>("configure projection read snapshot", error)
+            })?;
+    }
+
+    let result = operation(&mut *tx).await;
+    match result {
+        Ok(value) => {
+            tx.commit().await.map_err(|error| {
+                protocol_storage_error::<DB>("commit projection read snapshot", error)
+            })?;
+            Ok(value)
+        }
+        Err(error) => {
+            tx.rollback().await.map_err(|rollback_error| {
+                protocol_storage_error::<DB>(
+                    "roll back failed projection read snapshot",
+                    rollback_error,
+                )
+            })?;
+            Err(error)
+        }
+    }
+}
+
+pub(super) async fn read_projection_changes_in_executor_after_state<DB, AfterState>(
+    connection: &mut DB::Connection,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+    after: Option<&ProjectionChangeCursor>,
+    limit: usize,
+    after_state: AfterState,
+) -> Result<ProjectionChangeRead, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    AfterState: Future<Output = ()> + Send,
+    DB::Arguments: IntoArguments<DB>,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let state = load_partition_in_connection(connection, topology, partition).await?;
+    after_state.await;
+    let Some(state) = state else {
+        return Ok(match after {
+            Some(_) => ProjectionChangeRead::ResetRequired {
+                head: None,
+                compacted_through: 0,
+            },
+            None => ProjectionChangeRead::Changes {
+                head: None,
+                compacted_through: 0,
+                changes: Vec::new(),
+            },
+        });
+    };
+    let head = if state.change_head == 0 {
+        None
+    } else {
+        Some(ProjectionChangeCursor::new(
+            topology.clone(),
+            partition.clone(),
+            state.change_epoch.clone(),
+            state.change_head,
+        )?)
+    };
+    if after.is_none() && state.compacted_through > 0 {
+        return Ok(ProjectionChangeRead::ResetRequired {
+            head,
+            compacted_through: state.compacted_through,
+        });
+    }
+    let start = match after {
+        Some(cursor)
+            if cursor.topology() != topology
+                || cursor.projection_partition() != partition
+                || cursor.epoch() != &state.change_epoch
+                || cursor.position() > state.change_head
+                || cursor.position() < state.compacted_through =>
+        {
+            return Ok(ProjectionChangeRead::ResetRequired {
+                head,
+                compacted_through: state.compacted_through,
+            });
+        }
+        Some(cursor) => cursor.position(),
+        None => state.compacted_through,
+    };
+    if limit == 0 || start == state.change_head {
+        return Ok(ProjectionChangeRead::Changes {
+            head,
+            compacted_through: state.compacted_through,
+            changes: Vec::new(),
+        });
+    }
+    let topology_hash = topology.digest();
+    let partition_hash = partition.digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT change_epoch, change_position, change_kind, causation_id, model_name, \
+         scope_kind, canonical_key_bytes, canonical_key_hash, incarnation, revision, \
+         failure_id FROM projection_changes WHERE topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(" AND change_epoch = ");
+    builder.push_bind(state.change_epoch.as_str());
+    builder.push(" AND change_position > ");
+    builder.push_bind(to_i64::<DB>(start, "projection change read position")?);
+    builder.push(" ORDER BY change_position ASC LIMIT ");
+    builder.push_bind(i64::try_from(limit).unwrap_or(i64::MAX));
+    let rows = builder
+        .build()
+        .fetch_all(&mut *connection)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("read projection changes", error))?;
+    let mut changes = Vec::with_capacity(rows.len());
+    let mut expected = checked_next(start, "projection change read")?;
+    for row in rows {
+        let change = decode_change_row::<DB>(&row, topology, partition, &state.change_epoch)?;
+        if change.cursor.position() != expected {
+            return Err(corrupt_storage(format!(
+                "projection change log expected position {expected} but found {}",
+                change.cursor.position()
+            )));
+        }
+        expected = if change.cursor.position() == state.change_head {
+            state.change_head
+        } else {
+            checked_next(change.cursor.position(), "projection change read")?
+        };
+        changes.push(change);
+    }
+    if changes.is_empty() {
+        return Err(corrupt_storage(format!(
+            "projection change log is missing retained position {}",
+            checked_next(start, "projection change read")?
+        )));
+    }
+    Ok(ProjectionChangeRead::Changes {
+        head,
+        compacted_through: state.compacted_through,
+        changes,
+    })
+}
+
+/// Read one durable resumable projection-change page using an existing
+/// database executor and therefore the caller's already-established snapshot.
+pub(crate) async fn read_projection_changes_in_executor<DB>(
+    connection: &mut DB::Connection,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+    after: Option<&ProjectionChangeCursor>,
+    limit: usize,
+) -> Result<ProjectionChangeRead, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    DB::Arguments: IntoArguments<DB>,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    read_projection_changes_in_executor_after_state::<DB, _>(
+        connection,
+        topology,
+        partition,
+        after,
+        limit,
+        std::future::ready(()),
+    )
+    .await
+}
+
+/// Read one resumable projection-change page from a new database snapshot.
+///
+/// `after_state` is normally an immediately-ready future. Tests use it to
+/// commit compaction after the partition watermark has been observed but
+/// before retained rows are read, proving both statements remain one view.
+#[allow(dead_code)]
+pub(super) async fn read_projection_changes_in_snapshot<DB, AfterState>(
+    pool: &Pool<DB>,
+    topology: ProjectorTopologyId,
+    partition: ProjectionPartition,
+    after: Option<ProjectionChangeCursor>,
+    limit: usize,
+    after_state: AfterState,
+) -> Result<ProjectionChangeRead, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    AfterState: Future<Output = ()> + Send + 'static,
+    DB::Arguments: IntoArguments<DB>,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    with_projection_read_snapshot(pool, move |connection| {
+        Box::pin(async move {
+            read_projection_changes_in_executor_after_state::<DB, _>(
+                connection,
+                &topology,
+                &partition,
+                after.as_ref(),
+                limit,
+                after_state,
+            )
+            .await
+        })
+    })
+    .await
+}
diff --git a/src/sqlx_repo/projection_protocol/store_impl.rs b/src/sqlx_repo/projection_protocol/store_impl.rs
new file mode 100644
index 00000000..4cbe95c8
--- /dev/null
+++ b/src/sqlx_repo/projection_protocol/store_impl.rs
@@ -0,0 +1,1416 @@
+use super::*;
+
+impl<DB> ProjectionProtocolStore for SqlxRepository<DB>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    fn register_projection_models<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        ownership: &'a [ProjectionModelOwnership],
+    ) -> impl Future<Output = Result<(), ProjectionProtocolError>> + Send + 'a {
+        async move {
+            if ownership.is_empty() {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "projection startup registration requires at least one owned model".into(),
+                ));
+            }
+            crate::projection_protocol::validate_ownership_batch(ownership)?;
+
+            let mut tx = self.pool().begin().await.map_err(|error| {
+                protocol_storage_error::<DB>("begin projection registration", error)
+            })?;
+            let ownership_tables = ownership
+                .iter()
+                .map(|declaration| declaration.table.clone())
+                .collect::<BTreeSet<_>>();
+            lock_projection_table_ownership_fences_in_tx(&mut tx, &ownership_tables).await?;
+            let topology_hash = topology.digest();
+            let topology_bytes = topology.canonical_bytes();
+            for declaration in ownership {
+                let mut global = QueryBuilder::<DB>::new(
+                    "SELECT model_name FROM projection_causal_tables WHERE table_name = ",
+                );
+                global.push_bind(declaration.table.as_str());
+                let existing = global
+                    .build()
+                    .fetch_optional(&mut *tx)
+                    .await
+                    .map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "load global causal projection registration",
+                            error,
+                        )
+                    })?;
+                if let Some(row) = existing {
+                    let model: String = row.try_get("model_name").map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "decode global causal projection registration",
+                            error,
+                        )
+                    })?;
+                    if model != declaration.model {
+                        return Err(ProjectionProtocolError::InvalidBatch(format!(
+                            "projection table `{}` is globally registered for model `{model}`",
+                            declaration.table
+                        )));
+                    }
+                } else {
+                    let mut legacy_rows = QueryBuilder::<DB>::new("SELECT 1 FROM ");
+                    legacy_rows.push(quote_identifier(&declaration.table));
+                    legacy_rows.push(" LIMIT 1");
+                    if legacy_rows
+                        .build()
+                        .fetch_optional(&mut *tx)
+                        .await
+                        .map_err(|error| {
+                            protocol_storage_error::<DB>(
+                                "verify empty table before causal registration",
+                                error,
+                            )
+                        })?
+                        .is_some()
+                    {
+                        return Err(ProjectionProtocolError::InvalidBatch(format!(
+                            "cannot causally register table `{}` because it already contains unverified legacy rows",
+                            declaration.table
+                        )));
+                    }
+                    let mut insert = QueryBuilder::<DB>::new(
+                        "INSERT INTO projection_causal_tables (table_name, model_name) VALUES (",
+                    );
+                    insert.push_bind(declaration.table.as_str());
+                    insert.push(", ");
+                    insert.push_bind(declaration.model.as_str());
+                    insert.push(") ON CONFLICT (table_name) DO NOTHING");
+                    insert.build().execute(&mut *tx).await.map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "insert global causal projection registration",
+                            error,
+                        )
+                    })?;
+                    let mut verify = QueryBuilder::<DB>::new(
+                        "SELECT model_name FROM projection_causal_tables WHERE table_name = ",
+                    );
+                    verify.push_bind(declaration.table.as_str());
+                    let row = verify
+                        .build()
+                        .fetch_optional(&mut *tx)
+                        .await
+                        .map_err(|error| {
+                            protocol_storage_error::<DB>(
+                                "verify global causal projection registration",
+                                error,
+                            )
+                        })?
+                        .ok_or_else(|| {
+                            corrupt_storage(
+                                "global causal projection registration disappeared after insert",
+                            )
+                        })?;
+                    let model: String = row.try_get("model_name").map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "decode global causal projection registration",
+                            error,
+                        )
+                    })?;
+                    if model != declaration.model {
+                        return Err(ProjectionProtocolError::InvalidBatch(format!(
+                            "projection table `{}` is globally registered for model `{model}`",
+                            declaration.table
+                        )));
+                    }
+                }
+
+                let mut physical_owner = QueryBuilder::<DB>::new(
+                    "SELECT topology_bytes, topology_hash, model_name \
+                     FROM projection_registered_models WHERE table_name = ",
+                );
+                physical_owner.push_bind(declaration.table.as_str());
+                if let Some(row) = physical_owner
+                    .build()
+                    .fetch_optional(&mut *tx)
+                    .await
+                    .map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "load authoritative projection table owner",
+                            error,
+                        )
+                    })?
+                {
+                    let owner_hash: Vec<u8> = row.try_get("topology_hash").map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "decode authoritative projection table owner",
+                            error,
+                        )
+                    })?;
+                    let owner_model: String = row.try_get("model_name").map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "decode authoritative projection table owner",
+                            error,
+                        )
+                    })?;
+                    if owner_hash != topology_hash || owner_model != declaration.model {
+                        return Err(ProjectionProtocolError::InvalidBatch(format!(
+                            "projection table `{}` is authoritatively owned by another topology/model",
+                            declaration.table
+                        )));
+                    }
+                    let owner_bytes: Vec<u8> = row.try_get("topology_bytes").map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "decode authoritative projection topology bytes",
+                            error,
+                        )
+                    })?;
+                    verify_bytes(
+                        &owner_bytes,
+                        &topology_bytes,
+                        "authoritative projector topology",
+                    )?;
+                    continue;
+                }
+
+                let mut registered = QueryBuilder::<DB>::new(
+                    "SELECT topology_bytes, table_name FROM projection_registered_models \
+                     WHERE topology_hash = ",
+                );
+                registered.push_bind(topology_hash.as_slice());
+                registered.push(" AND model_name = ");
+                registered.push_bind(declaration.model.as_str());
+                if let Some(row) =
+                    registered
+                        .build()
+                        .fetch_optional(&mut *tx)
+                        .await
+                        .map_err(|error| {
+                            protocol_storage_error::<DB>(
+                                "load topology projection registration",
+                                error,
+                            )
+                        })?
+                {
+                    let bytes: Vec<u8> = row.try_get("topology_bytes").map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "decode topology projection registration",
+                            error,
+                        )
+                    })?;
+                    verify_bytes(&bytes, &topology_bytes, "registered projector topology")?;
+                    let table: String = row.try_get("table_name").map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "decode topology projection registration",
+                            error,
+                        )
+                    })?;
+                    if table != declaration.table {
+                        return Err(ProjectionProtocolError::InvalidBatch(format!(
+                            "projection model `{}` is already registered for table `{table}`",
+                            declaration.model
+                        )));
+                    }
+                    continue;
+                }
+
+                let mut table_registration = QueryBuilder::<DB>::new(
+                    "SELECT topology_bytes, model_name FROM projection_registered_models \
+                     WHERE topology_hash = ",
+                );
+                table_registration.push_bind(topology_hash.as_slice());
+                table_registration.push(" AND table_name = ");
+                table_registration.push_bind(declaration.table.as_str());
+                if let Some(row) = table_registration
+                    .build()
+                    .fetch_optional(&mut *tx)
+                    .await
+                    .map_err(|error| {
+                        protocol_storage_error::<DB>("load topology table registration", error)
+                    })?
+                {
+                    let bytes: Vec<u8> = row.try_get("topology_bytes").map_err(|error| {
+                        protocol_storage_error::<DB>("decode topology table registration", error)
+                    })?;
+                    verify_bytes(&bytes, &topology_bytes, "registered projector topology")?;
+                    let model: String = row.try_get("model_name").map_err(|error| {
+                        protocol_storage_error::<DB>("decode topology table registration", error)
+                    })?;
+                    return Err(ProjectionProtocolError::InvalidBatch(format!(
+                        "projection table `{}` is already registered for model `{model}`",
+                        declaration.table
+                    )));
+                }
+
+                let mut insert = QueryBuilder::<DB>::new(
+                    "INSERT INTO projection_registered_models \
+                     (topology_bytes, topology_hash, model_name, table_name) VALUES (",
+                );
+                insert.push_bind(topology_bytes.as_slice());
+                insert.push(", ");
+                insert.push_bind(topology_hash.as_slice());
+                insert.push(", ");
+                insert.push_bind(declaration.model.as_str());
+                insert.push(", ");
+                insert.push_bind(declaration.table.as_str());
+                insert.push(") ON CONFLICT DO NOTHING");
+                let result = insert.build().execute(&mut *tx).await.map_err(|error| {
+                    protocol_storage_error::<DB>("insert topology projection registration", error)
+                })?;
+                if DB::rows_affected(&result) != 1 {
+                    let mut verify = QueryBuilder::<DB>::new(
+                        "SELECT topology_bytes, table_name FROM projection_registered_models \
+                         WHERE topology_hash = ",
+                    );
+                    verify.push_bind(topology_hash.as_slice());
+                    verify.push(" AND model_name = ");
+                    verify.push_bind(declaration.model.as_str());
+                    let row = verify
+                        .build()
+                        .fetch_optional(&mut *tx)
+                        .await
+                        .map_err(|error| {
+                            protocol_storage_error::<DB>(
+                                "verify concurrent topology projection registration",
+                                error,
+                            )
+                        })?
+                        .ok_or_else(|| {
+                            ProjectionProtocolError::InvalidBatch(format!(
+                                "projection table `{}` was concurrently registered to another model",
+                                declaration.table
+                            ))
+                        })?;
+                    let bytes: Vec<u8> = row.try_get("topology_bytes").map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "decode concurrent topology projection registration",
+                            error,
+                        )
+                    })?;
+                    verify_bytes(&bytes, &topology_bytes, "registered projector topology")?;
+                    let table: String = row.try_get("table_name").map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "decode concurrent topology projection registration",
+                            error,
+                        )
+                    })?;
+                    if table != declaration.table {
+                        return Err(ProjectionProtocolError::InvalidBatch(format!(
+                            "projection model `{}` was concurrently registered for table `{table}`",
+                            declaration.model
+                        )));
+                    }
+                }
+            }
+            tx.commit().await.map_err(|error| {
+                protocol_storage_error::<DB>("commit projection registration", error)
+            })
+        }
+    }
+
+    fn commit_projection(
+        &self,
+        batch: ProjectionCommitBatch,
+    ) -> impl Future<Output = Result<ProjectionCommitResult, ProjectionProtocolError>> + Send + '_
+    {
+        async move {
+            batch.validate()?;
+            let write_plan = TableWritePlan::new(
+                batch
+                    .mutations
+                    .iter()
+                    .map(|mutation| mutation.mutation.clone())
+                    .collect(),
+            );
+            validate_sql_write_plan(&write_plan)?;
+
+            let topology = batch.input.cursor.topology().clone();
+            let partition = batch.input.cursor.projection_partition().clone();
+            let mut tx =
+                self.pool().begin().await.map_err(|error| {
+                    protocol_storage_error::<DB>("begin projection commit", error)
+                })?;
+            verify_registered_topology_in_tx(&mut tx, &topology).await?;
+            let mut state =
+                lock_partition_in_tx(&mut tx, &topology, &partition, &batch.change_epoch).await?;
+            validate_input_identity_in_tx(&mut tx, &batch.input).await?;
+            ensure_active_input(&state, &batch.input)?;
+            match classify_validated_input_in_tx(&mut tx, &batch.input, &state).await? {
+                InputDisposition::Duplicate(checkpoint) => {
+                    return Ok(ProjectionCommitResult::not_applied(
+                        ProjectionCommitOutcome::Duplicate,
+                        Some(checkpoint),
+                    ));
+                }
+                InputDisposition::Stale(checkpoint) => {
+                    return Ok(ProjectionCommitResult::not_applied(
+                        ProjectionCommitOutcome::StaleInput,
+                        Some(checkpoint),
+                    ));
+                }
+                InputDisposition::New => {
+                    ensure_pending_retry_input_in_tx(&mut tx, &state, &batch.input).await?;
+                }
+            }
+            ensure_inbox_available_in_tx(&mut tx, &batch.input).await?;
+            ensure_partition_ownership_in_tx(&mut tx, &topology, &partition, &batch.ownership)
+                .await?;
+
+            for mutation in &batch.mutations {
+                if mutation.mutation.table_name()
+                    != batch
+                        .ownership
+                        .iter()
+                        .find(|owned| owned.model == mutation.scope.model())
+                        .map(|owned| owned.table.as_str())
+                        .unwrap_or_default()
+                    || table_model_name(&mutation.mutation) != mutation.scope.model()
+                {
+                    return Err(ProjectionProtocolError::InvalidBatch(format!(
+                        "projection mutation for model `{}` does not target its registered table",
+                        mutation.scope.model()
+                    )));
+                }
+            }
+
+            let mut records = Vec::with_capacity(batch.mutations.len());
+            let mut records_by_scope = HashMap::with_capacity(batch.mutations.len());
+            let mut changes =
+                Vec::with_capacity(batch.mutations.len() + batch.observations.len().max(1));
+            for mutation in &batch.mutations {
+                let current = record_in_tx(&mut tx, &mutation.scope, &state.change_epoch).await?;
+                let physical_exists =
+                    physical_row_exists_in_tx(&mut tx, &mutation.mutation).await?;
+                match current.as_ref().map(|record| &record.metadata) {
+                    None if physical_exists => {
+                        return Err(ProjectionProtocolError::RecordAlreadyExists {
+                            model: mutation.scope.model().to_string(),
+                        });
+                    }
+                    Some(metadata) if metadata.tombstone && physical_exists => {
+                        return Err(ProjectionProtocolError::RecordAlreadyExists {
+                            model: mutation.scope.model().to_string(),
+                        });
+                    }
+                    Some(metadata) if !metadata.tombstone && !physical_exists => {
+                        return Err(ProjectionProtocolError::RecordMissing {
+                            model: mutation.scope.model().to_string(),
+                        });
+                    }
+                    _ => {}
+                }
+                let (revision, tombstone) = next_record(
+                    &mutation.scope,
+                    &mutation.expectation,
+                    mutation.kind,
+                    current.as_ref(),
+                )?;
+                let change = allocate_change(
+                    &mut state,
+                    &topology,
+                    &partition,
+                    change_kind_for_mutation(mutation.kind),
+                    batch.input.causation_id.clone(),
+                    None,
+                    Some(mutation.scope.clone()),
+                    Some(revision.clone()),
+                    None,
+                )?;
+                let metadata = ProjectionRecordMetadata {
+                    revision,
+                    tombstone,
+                    change: change.cursor.clone(),
+                };
+                records_by_scope.insert(mutation.scope.clone(), metadata.clone());
+                records.push(metadata);
+                changes.push(change);
+            }
+
+            let mut observations = Vec::with_capacity(batch.observations.len());
+            for request in &batch.observations {
+                let (scope, revision, staged_change) = match &request.target {
+                    ProjectionObservationTarget::StagedRecord(scope) => {
+                        let metadata = records_by_scope.get(scope).ok_or_else(|| {
+                            ProjectionProtocolError::InvalidBatch(format!(
+                                "projection observation references unstaged model `{}`",
+                                scope.model()
+                            ))
+                        })?;
+                        (
+                            scope.clone(),
+                            Some(metadata.revision.clone()),
+                            Some(metadata.change.clone()),
+                        )
+                    }
+                    ProjectionObservationTarget::ExistingRecord(expected) => {
+                        let metadata =
+                            if let Some(metadata) = records_by_scope.get(expected.scope()) {
+                                metadata.clone()
+                            } else {
+                                record_in_tx(&mut tx, expected.scope(), &state.change_epoch)
+                                    .await?
+                                    .map(|record| record.metadata)
+                                    .ok_or_else(|| ProjectionProtocolError::RecordMissing {
+                                        model: expected.scope().model().to_string(),
+                                    })?
+                            };
+                        if metadata.revision != *expected {
+                            return Err(ProjectionProtocolError::RecordRevisionConflict {
+                                model: expected.scope().model().to_string(),
+                                expected_incarnation: expected.incarnation(),
+                                expected_revision: expected.revision(),
+                                actual_incarnation: metadata.revision.incarnation(),
+                                actual_revision: metadata.revision.revision(),
+                            });
+                        }
+                        if metadata.tombstone {
+                            return Err(ProjectionProtocolError::RecordTombstoned {
+                                model: expected.scope().model().to_string(),
+                            });
+                        }
+                        (expected.scope().clone(), Some(expected.clone()), None)
+                    }
+                    ProjectionObservationTarget::Dependency(scope) => (scope.clone(), None, None),
+                };
+                if observation_in_tx(
+                    &mut tx,
+                    &batch.input.causation_id,
+                    &scope,
+                    request.kind,
+                    &state.change_epoch,
+                )
+                .await?
+                .is_some()
+                {
+                    // Causation observations are immutable earliest evidence.
+                    // A later input carrying the same exact observation key
+                    // neither rewrites its revision nor emits a duplicate
+                    // change.
+                    continue;
+                }
+
+                let change_cursor = if let Some(change) = staged_change {
+                    change
+                } else {
+                    let change = allocate_change(
+                        &mut state,
+                        &topology,
+                        &partition,
+                        ProjectionChangeKind::Observation,
+                        batch.input.causation_id.clone(),
+                        Some(request.kind),
+                        Some(scope.clone()),
+                        revision.clone(),
+                        None,
+                    )?;
+                    let cursor = change.cursor.clone();
+                    changes.push(change);
+                    cursor
+                };
+                observations.push(ProjectionObservation {
+                    causation_id: batch.input.causation_id.clone(),
+                    kind: request.kind,
+                    revision,
+                    scope,
+                    change: change_cursor,
+                });
+            }
+
+            if changes.is_empty() {
+                changes.push(allocate_change(
+                    &mut state,
+                    &topology,
+                    &partition,
+                    ProjectionChangeKind::Checkpoint,
+                    batch.input.causation_id.clone(),
+                    None,
+                    None,
+                    None,
+                    None,
+                )?);
+            }
+            let final_change = changes
+                .last()
+                .expect("a successful projection commit always allocates a change")
+                .cursor
+                .clone();
+            let checkpoint = ProjectionCheckpoint::new(
+                batch.input.cursor.clone(),
+                final_change.clone(),
+                batch.input.gap_free,
+            )?;
+
+            apply_read_model_write_plan_in_tx(&mut tx, write_plan).await?;
+            for change in &changes {
+                insert_change_in_tx(&mut tx, change).await?;
+            }
+            for metadata in &records {
+                upsert_record_in_tx(&mut tx, metadata).await?;
+            }
+            for observation in &observations {
+                insert_observation_in_tx(&mut tx, observation).await?;
+            }
+            store_input_cursor_in_tx(&mut tx, &batch.input, &final_change).await?;
+            insert_input_identity_in_tx(&mut tx, &batch.input).await?;
+            insert_input_receipt_in_tx(&mut tx, &batch.input, "applied", None, &final_change)
+                .await?;
+            insert_inbox_in_tx(&mut tx, &batch.input).await?;
+            update_partition_head_in_tx(
+                &mut tx,
+                &topology,
+                &partition,
+                state.change_head,
+                state.pending_retry_failure_id.as_deref(),
+            )
+            .await?;
+            retain_projection_change_suffix_in_tx(
+                &mut tx,
+                &topology,
+                &partition,
+                &state,
+                self.projection_change_retention(),
+            )
+            .await?;
+
+            let mut changed_tables = batch
+                .mutations
+                .iter()
+                .map(|mutation| mutation.mutation.table_name().to_string())
+                .collect::<BTreeSet<_>>();
+            changed_tables.insert(PROJECTION_CHANGE_NOTIFY_TABLE.to_string());
+            if self.projection_notify_enabled() {
+                DB::push_change_notify(&mut *tx, &changed_tables).await?;
+            }
+            tx.commit().await.map_err(|error| {
+                protocol_storage_error::<DB>("commit projection transaction", error)
+            })?;
+            self.publish_read_model_change(crate::ReadModelChange {
+                tables: changed_tables,
+            });
+            Ok(ProjectionCommitResult {
+                outcome: ProjectionCommitOutcome::Applied,
+                checkpoint: Some(checkpoint),
+                records,
+                changes,
+            })
+        }
+    }
+
+    fn record_projection_failure(
+        &self,
+        batch: ProjectionFailureBatch,
+    ) -> impl Future<Output = Result<ProjectionFailure, ProjectionProtocolError>> + Send + '_ {
+        async move {
+            batch.validate()?;
+            let topology = batch.input.cursor.topology().clone();
+            let partition = batch.input.cursor.projection_partition().clone();
+            let mut tx =
+                self.pool().begin().await.map_err(|error| {
+                    protocol_storage_error::<DB>("begin projection failure", error)
+                })?;
+            verify_registered_topology_in_tx(&mut tx, &topology).await?;
+            let mut state =
+                lock_partition_in_tx(&mut tx, &topology, &partition, &batch.change_epoch).await?;
+            validate_input_identity_in_tx(&mut tx, &batch.input).await?;
+            if state.active_generation != batch.input.generation {
+                return Err(ProjectionProtocolError::GenerationFenced {
+                    expected: state.active_generation.get(),
+                    actual: batch.input.generation.get(),
+                });
+            }
+            if let Some(stopped_failure_id) = &state.stopped_failure_id {
+                if stopped_failure_id == &batch.failure_id {
+                    let existing = failure_in_tx(
+                        &mut tx,
+                        &topology,
+                        &partition,
+                        stopped_failure_id,
+                        &state.change_epoch,
+                    )
+                    .await?
+                    .ok_or_else(|| {
+                        corrupt_storage(format!(
+                            "stopped projection failure `{stopped_failure_id}` is missing"
+                        ))
+                    })?;
+                    if failure_matches_batch(&existing, &batch) {
+                        return Ok(existing.failure);
+                    }
+                    if existing.failure.input == batch.input.cursor {
+                        if existing.failure.input_fingerprint != batch.input.fingerprint
+                            || existing.failure.message_id != batch.input.message_id
+                            || existing.failure.causation_id != batch.input.causation_id
+                            || existing.failure.gap_free != batch.input.gap_free
+                        {
+                            return Err(ProjectionProtocolError::InputCorruption);
+                        }
+                    } else if existing.failure.message_id == batch.input.message_id {
+                        return Err(ProjectionProtocolError::MessageIdReuse {
+                            message_id: batch.input.message_id.clone(),
+                        });
+                    }
+                }
+                return Err(ProjectionProtocolError::PartitionStopped {
+                    failure_id: stopped_failure_id.clone(),
+                });
+            }
+            let mut failure_id_query =
+                QueryBuilder::<DB>::new("SELECT 1 FROM projection_failures WHERE failure_id = ");
+            failure_id_query.push_bind(batch.failure_id.as_str());
+            failure_id_query.push(" LIMIT 1");
+            if failure_id_query
+                .build()
+                .fetch_optional(&mut *tx)
+                .await
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("check projection failure ID", error)
+                })?
+                .is_some()
+            {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection failure ID `{}` is already bound to another failure",
+                    batch.failure_id
+                )));
+            }
+
+            match classify_validated_input_in_tx(&mut tx, &batch.input, &state).await? {
+                InputDisposition::New => {
+                    ensure_pending_retry_input_in_tx(&mut tx, &state, &batch.input).await?;
+                }
+                InputDisposition::Duplicate(_) | InputDisposition::Stale(_) => {
+                    return Err(ProjectionProtocolError::InvalidBatch(
+                        "cannot record terminal failure for an already processed input".into(),
+                    ));
+                }
+            }
+            ensure_inbox_available_in_tx(&mut tx, &batch.input).await?;
+            let change = allocate_change(
+                &mut state,
+                &topology,
+                &partition,
+                ProjectionChangeKind::Failure,
+                batch.input.causation_id.clone(),
+                None,
+                None,
+                None,
+                Some(batch.failure_id.clone()),
+            )?;
+            insert_change_in_tx(&mut tx, &change).await?;
+            insert_failure_in_tx(&mut tx, &batch, &change.cursor).await?;
+            insert_input_identity_in_tx(&mut tx, &batch.input).await?;
+            insert_input_receipt_in_tx(
+                &mut tx,
+                &batch.input,
+                "failed",
+                Some(&batch.failure_id),
+                &change.cursor,
+            )
+            .await?;
+            insert_inbox_in_tx(&mut tx, &batch.input).await?;
+            stop_partition_in_tx(&mut tx, &batch, state.change_head).await?;
+            retain_projection_change_suffix_in_tx(
+                &mut tx,
+                &topology,
+                &partition,
+                &state,
+                self.projection_change_retention(),
+            )
+            .await?;
+
+            let changed_tables = BTreeSet::from([PROJECTION_CHANGE_NOTIFY_TABLE.to_string()]);
+            if self.projection_notify_enabled() {
+                DB::push_change_notify(&mut *tx, &changed_tables).await?;
+            }
+            let failure = ProjectionFailure {
+                failure_id: batch.failure_id,
+                input: batch.input.cursor,
+                input_fingerprint: batch.input.fingerprint,
+                message_id: batch.input.message_id,
+                causation_id: batch.input.causation_id,
+                generation: batch.input.generation,
+                gap_free: batch.input.gap_free,
+                failure_code: batch.failure_code,
+                failure_bytes: batch.failure_bytes,
+                failure_digest: batch.failure_digest,
+                change: change.cursor,
+            };
+            tx.commit().await.map_err(|error| {
+                protocol_storage_error::<DB>("commit projection failure", error)
+            })?;
+            self.publish_read_model_change(crate::ReadModelChange {
+                tables: changed_tables,
+            });
+            Ok(failure)
+        }
+    }
+
+    fn projection_checkpoint<'a>(
+        &'a self,
+        cursor_scope: &'a ProjectionInputCursor,
+        generation: ProjectionGeneration,
+    ) -> impl Future<Output = Result<Option<ProjectionCheckpoint>, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            let Some(state) = load_partition(
+                self.pool(),
+                cursor_scope.topology(),
+                cursor_scope.projection_partition(),
+            )
+            .await?
+            else {
+                return Ok(None);
+            };
+            let probe = TrustedProjectionInput {
+                cursor: cursor_scope.clone(),
+                fingerprint: ProjectionInputFingerprint::from_digest([0; 32]),
+                message_id: String::new(),
+                causation_id: String::new(),
+                generation,
+                gap_free: false,
+            };
+            let mut tx = self.pool().begin().await.map_err(|error| {
+                protocol_storage_error::<DB>("begin projection checkpoint read", error)
+            })?;
+            let Some(stored) = current_input_cursor_in_tx(&mut tx, &probe).await? else {
+                return Ok(None);
+            };
+            verify_stored_change(&state, &stored.change)?;
+            if stored.source_epoch != *cursor_scope.epoch() {
+                return Err(ProjectionProtocolError::IncomparableInput);
+            }
+            Ok(Some(checkpoint_from_stored(
+                cursor_scope,
+                stored.source_epoch,
+                stored.source_position,
+                stored.change,
+                stored.gap_free,
+            )?))
+        }
+    }
+
+    fn projection_record<'a>(
+        &'a self,
+        scope: &'a ProjectionRecordScope,
+    ) -> impl Future<Output = Result<Option<ProjectionRecordMetadata>, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        async move {
+            let Some(state) =
+                load_partition(self.pool(), scope.topology(), scope.projection_partition()).await?
+            else {
+                return Ok(None);
+            };
+            let mut tx = self.pool().begin().await.map_err(|error| {
+                protocol_storage_error::<DB>("begin projection record read", error)
+            })?;
+            Ok(record_in_tx(&mut tx, scope, &state.change_epoch)
+                .await?
+                .map(|record| record.metadata))
+        }
+    }
+
+    fn projection_input_disposition<'a>(
+        &'a self,
+        input: &'a TrustedProjectionInput,
+    ) -> impl Future<Output = Result<ProjectionInputDisposition, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            let mut tx = self.pool().begin().await.map_err(|error| {
+                protocol_storage_error::<DB>("begin projection input disposition read", error)
+            })?;
+            if DB::BACKEND == "postgres" {
+                sqlx::query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY")
+                    .execute(&mut *tx)
+                    .await
+                    .map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "configure projection input disposition read",
+                            error,
+                        )
+                    })?;
+            }
+
+            let result = async {
+                verify_registered_topology_in_tx(&mut tx, input.cursor.topology()).await?;
+                // Durable cursor/message/capability corruption wins over a
+                // generation fence, matching commit/failure validation.
+                validate_input_identity_read_only_in_tx(&mut tx, input).await?;
+                let Some(state) = load_partition_in_tx(
+                    &mut tx,
+                    input.cursor.topology(),
+                    input.cursor.projection_partition(),
+                )
+                .await?
+                else {
+                    if input.generation != ProjectionGeneration::initial() {
+                        return Err(ProjectionProtocolError::GenerationFenced {
+                            expected: ProjectionGeneration::initial().get(),
+                            actual: input.generation.get(),
+                        });
+                    }
+                    return Ok(ProjectionInputDisposition::Pending);
+                };
+                if state.active_generation != input.generation {
+                    return Err(ProjectionProtocolError::GenerationFenced {
+                        expected: state.active_generation.get(),
+                        actual: input.generation.get(),
+                    });
+                }
+                verify_generation_exists_in_tx(
+                    &mut tx,
+                    input.cursor.topology(),
+                    input.cursor.projection_partition(),
+                    input.generation,
+                )
+                .await?;
+                if let Some(failure_id) = &state.stopped_failure_id {
+                    return Err(ProjectionProtocolError::PartitionStopped {
+                        failure_id: failure_id.clone(),
+                    });
+                }
+                match classify_validated_input_in_tx(&mut tx, input, &state).await? {
+                    InputDisposition::New => {
+                        ensure_pending_retry_input_in_tx(&mut tx, &state, input).await?;
+                        Ok(ProjectionInputDisposition::Pending)
+                    }
+                    InputDisposition::Duplicate(checkpoint) => {
+                        Ok(ProjectionInputDisposition::Duplicate(checkpoint))
+                    }
+                    InputDisposition::Stale(checkpoint) => {
+                        Ok(ProjectionInputDisposition::Stale(checkpoint))
+                    }
+                }
+            }
+            .await;
+
+            match result {
+                Ok(disposition) => {
+                    tx.commit().await.map_err(|error| {
+                        protocol_storage_error::<DB>(
+                            "commit projection input disposition read",
+                            error,
+                        )
+                    })?;
+                    Ok(disposition)
+                }
+                Err(error) => {
+                    tx.rollback().await.map_err(|rollback_error| {
+                        protocol_storage_error::<DB>(
+                            "roll back failed projection input disposition read",
+                            rollback_error,
+                        )
+                    })?;
+                    Err(error)
+                }
+            }
+        }
+    }
+
+    fn projection_query_snapshot<'a>(
+        &'a self,
+        request: &'a ProjectionQuerySnapshotRequest,
+    ) -> impl Future<Output = Result<ProjectionQuerySnapshot, ProjectionProtocolError>> + Send + 'a
+    {
+        read_projection_query_snapshot_in_executor(self.pool(), request)
+    }
+
+    fn projection_query_snapshot_batch<'a>(
+        &'a self,
+        request: &'a ProjectionQuerySnapshotBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionQuerySnapshotBatch, ProjectionProtocolError>> + Send + 'a
+    {
+        let request = request.clone();
+        async move {
+            request.validate()?;
+            with_projection_read_snapshot(self.pool(), move |connection| {
+                Box::pin(async move {
+                    let mut snapshots = Vec::with_capacity(request.requests.len());
+                    for row_request in &request.requests {
+                        snapshots.push(
+                            read_projection_query_snapshot_in_executor::<DB, _>(
+                                &mut *connection,
+                                row_request,
+                            )
+                            .await?,
+                        );
+                    }
+                    Ok(ProjectionQuerySnapshotBatch { snapshots })
+                })
+            })
+            .await
+        }
+    }
+
+    fn projection_obligation_evidence_batch<'a>(
+        &'a self,
+        request: &'a ProjectionObligationEvidenceBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionObligationEvidenceBatch, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        let request = request.clone();
+        async move {
+            request.validate()?;
+            with_projection_read_snapshot(self.pool(), move |connection| {
+                Box::pin(async move {
+                    read_projection_obligation_evidence_batch_in_executor::<DB>(
+                        connection, &request,
+                    )
+                    .await
+                })
+            })
+            .await
+        }
+    }
+
+    fn projection_live_record_batch<'a>(
+        &'a self,
+        request: &'a ProjectionLiveRecordBatchRequest,
+    ) -> impl Future<Output = Result<ProjectionLiveRecordBatch, ProjectionProtocolError>> + Send + 'a
+    {
+        let request = request.clone();
+        async move {
+            request.validate()?;
+            with_projection_read_snapshot(self.pool(), move |connection| {
+                Box::pin(async move {
+                    read_projection_live_record_batch_in_executor::<DB>(connection, &request).await
+                })
+            })
+            .await
+        }
+    }
+
+    fn projection_partition_runtime_state<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+    ) -> impl Future<Output = Result<Option<ProjectionPartitionRuntimeState>, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        load_partition_runtime_state(self.pool(), topology, partition)
+    }
+
+    fn projection_observation<'a>(
+        &'a self,
+        causation_id: &'a str,
+        scope: &'a ProjectionRecordScope,
+        kind: ProjectionObservationKind,
+    ) -> impl Future<Output = Result<Option<ProjectionObservation>, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            let Some(state) =
+                load_partition(self.pool(), scope.topology(), scope.projection_partition()).await?
+            else {
+                return Ok(None);
+            };
+            let mut tx = self.pool().begin().await.map_err(|error| {
+                protocol_storage_error::<DB>("begin projection observation read", error)
+            })?;
+            observation_in_tx(&mut tx, causation_id, scope, kind, &state.change_epoch).await
+        }
+    }
+
+    fn projection_changes<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        after: Option<&'a ProjectionChangeCursor>,
+        limit: usize,
+    ) -> impl Future<Output = Result<ProjectionChangeRead, ProjectionProtocolError>> + Send + 'a
+    {
+        let topology = topology.clone();
+        let partition = partition.clone();
+        let after = after.cloned();
+        async move {
+            read_projection_changes_in_snapshot(
+                self.pool(),
+                topology,
+                partition,
+                after,
+                limit,
+                std::future::ready(()),
+            )
+            .await
+        }
+    }
+
+    fn repair_projection<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<ProjectionGeneration, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            let mut tx =
+                self.pool().begin().await.map_err(|error| {
+                    protocol_storage_error::<DB>("begin projection repair", error)
+                })?;
+            let Some(state) = lock_existing_partition_in_tx(&mut tx, topology, partition).await?
+            else {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "cannot repair an unknown projection partition".into(),
+                ));
+            };
+            match &state.stopped_failure_id {
+                Some(stopped) if stopped == failure_id => {}
+                Some(stopped) => {
+                    return Err(ProjectionProtocolError::PartitionStopped {
+                        failure_id: stopped.clone(),
+                    });
+                }
+                None => {
+                    return Err(ProjectionProtocolError::InvalidBatch(
+                        "projection partition is not stopped".into(),
+                    ));
+                }
+            }
+            verify_generation_exists_in_tx(&mut tx, topology, partition, state.active_generation)
+                .await?;
+            let failure = failure_in_tx(
+                &mut tx,
+                topology,
+                partition,
+                failure_id,
+                &state.change_epoch,
+            )
+            .await?
+            .ok_or_else(|| {
+                corrupt_storage(format!(
+                    "stopped projection failure `{failure_id}` is missing"
+                ))
+            })?;
+            if failure.failure.generation != state.active_generation {
+                return Err(corrupt_storage(format!(
+                    "stopped failure generation {} differs from active generation {}",
+                    failure.failure.generation.get(),
+                    state.active_generation.get()
+                )));
+            }
+            let next_generation = state.active_generation.checked_next()?;
+            let topology_hash = topology.digest();
+            let partition_hash = partition.digest();
+            let old_generation =
+                to_i64::<DB>(state.active_generation.get(), "projection generation")?;
+            let next_generation_value =
+                to_i64::<DB>(next_generation.get(), "projection generation")?;
+
+            let mut existing = QueryBuilder::<DB>::new(
+                "SELECT 1 FROM projection_generations WHERE topology_hash = ",
+            );
+            existing.push_bind(topology_hash.as_slice());
+            existing.push(" AND partition_hash = ");
+            existing.push_bind(partition_hash.as_slice());
+            existing.push(" AND generation = ");
+            existing.push_bind(next_generation_value);
+            existing.push(" LIMIT 1");
+            if existing
+                .build()
+                .fetch_optional(&mut *tx)
+                .await
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("check projection repair generation", error)
+                })?
+                .is_some()
+            {
+                return Err(corrupt_storage(format!(
+                    "projection repair generation {} already exists",
+                    next_generation.get()
+                )));
+            }
+            let mut retry_link = QueryBuilder::<DB>::new(
+                "SELECT generation FROM projection_generations WHERE topology_hash = ",
+            );
+            retry_link.push_bind(topology_hash.as_slice());
+            retry_link.push(" AND partition_hash = ");
+            retry_link.push_bind(partition_hash.as_slice());
+            retry_link.push(" AND retry_of_failure_id = ");
+            retry_link.push_bind(failure_id);
+            retry_link.push(" LIMIT 1");
+            if retry_link
+                .build()
+                .fetch_optional(&mut *tx)
+                .await
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("check projection repair failure link", error)
+                })?
+                .is_some()
+            {
+                return Err(corrupt_storage(format!(
+                    "stopped failure `{failure_id}` already has a repair generation"
+                )));
+            }
+
+            let mut insert_generation = QueryBuilder::<DB>::new(
+                "INSERT INTO projection_generations \
+                 (topology_hash, partition_hash, generation, retry_of_generation, \
+                 retry_of_failure_id) VALUES (",
+            );
+            insert_generation.push_bind(topology_hash.as_slice());
+            insert_generation.push(", ");
+            insert_generation.push_bind(partition_hash.as_slice());
+            insert_generation.push(", ");
+            insert_generation.push_bind(next_generation_value);
+            insert_generation.push(", ");
+            insert_generation.push_bind(old_generation);
+            insert_generation.push(", ");
+            insert_generation.push_bind(failure_id);
+            insert_generation.push(")");
+            insert_generation
+                .build()
+                .execute(&mut *tx)
+                .await
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("insert projection repair generation", error)
+                })?;
+
+            let mut copy = QueryBuilder::<DB>::new(
+                "INSERT INTO projection_input_cursors \
+                 (topology_hash, partition_hash, source_bytes, source_hash, source_partition_bytes, \
+                 source_partition_hash, source_epoch, source_position, input_hash, message_id, \
+                 causation_id, gap_free, generation, change_epoch, change_position) \
+                 SELECT topology_hash, partition_hash, source_bytes, source_hash, \
+                 source_partition_bytes, source_partition_hash, source_epoch, source_position, \
+                 input_hash, message_id, causation_id, gap_free, ",
+            );
+            copy.push_bind(next_generation_value);
+            copy.push(
+                ", change_epoch, change_position FROM projection_input_cursors \
+                 WHERE topology_hash = ",
+            );
+            copy.push_bind(topology_hash.as_slice());
+            copy.push(" AND partition_hash = ");
+            copy.push_bind(partition_hash.as_slice());
+            copy.push(" AND generation = ");
+            copy.push_bind(old_generation);
+            copy.build().execute(&mut *tx).await.map_err(|error| {
+                protocol_storage_error::<DB>("copy projection repair checkpoints", error)
+            })?;
+
+            let mut activate =
+                QueryBuilder::<DB>::new("UPDATE projection_partitions SET active_generation = ");
+            activate.push_bind(next_generation_value);
+            activate.push(", pending_retry_failure_id = ");
+            activate.push_bind(failure_id);
+            activate.push(
+                ", stopped_failure_id = NULL, stopped_source_bytes = NULL, \
+                 stopped_source_hash = NULL, stopped_source_partition_bytes = NULL, \
+                 stopped_source_partition_hash = NULL, stopped_source_epoch = NULL, \
+                 stopped_source_position = NULL, stopped_generation = NULL, \
+                 stopped_input_hash = NULL, stopped_message_id = NULL, \
+                 stopped_causation_id = NULL, stopped_gap_free = NULL WHERE topology_hash = ",
+            );
+            activate.push_bind(topology_hash.as_slice());
+            activate.push(" AND partition_hash = ");
+            activate.push_bind(partition_hash.as_slice());
+            activate.push(" AND active_generation = ");
+            activate.push_bind(old_generation);
+            activate.push(" AND stopped_failure_id = ");
+            activate.push_bind(failure_id);
+            let result = activate.build().execute(&mut *tx).await.map_err(|error| {
+                protocol_storage_error::<DB>("activate projection repair generation", error)
+            })?;
+            if DB::rows_affected(&result) != 1 {
+                return Err(corrupt_storage(
+                    "projection stop fence changed while its partition lock was held",
+                ));
+            }
+            tx.commit()
+                .await
+                .map_err(|error| protocol_storage_error::<DB>("commit projection repair", error))?;
+            Ok(next_generation)
+        }
+    }
+
+    fn compact_projection_changes<'a>(
+        &'a self,
+        through: &'a ProjectionChangeCursor,
+    ) -> impl Future<Output = Result<u64, ProjectionProtocolError>> + Send + 'a {
+        async move {
+            let topology = through.topology();
+            let partition = through.projection_partition();
+            let mut tx = self.pool().begin().await.map_err(|error| {
+                protocol_storage_error::<DB>("begin projection change compaction", error)
+            })?;
+            let Some(state) = lock_existing_partition_in_tx(&mut tx, topology, partition).await?
+            else {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "cannot compact an unknown projection partition".into(),
+                ));
+            };
+            if through.epoch() != &state.change_epoch {
+                return Err(ProjectionProtocolError::ScopeMismatch {
+                    field: "projection compaction epoch",
+                });
+            }
+            if through.position() > state.change_head {
+                return Err(ProjectionProtocolError::InvalidBatch(
+                    "cannot compact beyond the projection change head".into(),
+                ));
+            }
+            if through.position() <= state.compacted_through {
+                return Ok(state.compacted_through);
+            }
+            let topology_hash = topology.digest();
+            let partition_hash = partition.digest();
+            let through_position =
+                to_i64::<DB>(through.position(), "projection compaction position")?;
+            let mut exact =
+                QueryBuilder::<DB>::new("SELECT 1 FROM projection_changes WHERE topology_hash = ");
+            exact.push_bind(topology_hash.as_slice());
+            exact.push(" AND partition_hash = ");
+            exact.push_bind(partition_hash.as_slice());
+            exact.push(" AND change_epoch = ");
+            exact.push_bind(state.change_epoch.as_str());
+            exact.push(" AND change_position = ");
+            exact.push_bind(through_position);
+            exact.push(" LIMIT 1");
+            if exact
+                .build()
+                .fetch_optional(&mut *tx)
+                .await
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("verify projection compaction cursor", error)
+                })?
+                .is_none()
+            {
+                return Err(corrupt_storage(format!(
+                    "projection compaction cursor {} is missing",
+                    through.position()
+                )));
+            }
+
+            let mut delete =
+                QueryBuilder::<DB>::new("DELETE FROM projection_changes WHERE topology_hash = ");
+            delete.push_bind(topology_hash.as_slice());
+            delete.push(" AND partition_hash = ");
+            delete.push_bind(partition_hash.as_slice());
+            delete.push(" AND change_epoch = ");
+            delete.push_bind(state.change_epoch.as_str());
+            delete.push(" AND change_position <= ");
+            delete.push_bind(through_position);
+            let result = delete.build().execute(&mut *tx).await.map_err(|error| {
+                protocol_storage_error::<DB>("compact projection changes", error)
+            })?;
+            let expected_removed = through.position() - state.compacted_through;
+            if DB::rows_affected(&result) != expected_removed {
+                return Err(corrupt_storage(format!(
+                    "projection compaction expected to remove {expected_removed} changes but removed {}",
+                    DB::rows_affected(&result)
+                )));
+            }
+
+            let mut watermark =
+                QueryBuilder::<DB>::new("UPDATE projection_partitions SET compacted_through = ");
+            watermark.push_bind(through_position);
+            watermark.push(" WHERE topology_hash = ");
+            watermark.push_bind(topology_hash.as_slice());
+            watermark.push(" AND partition_hash = ");
+            watermark.push_bind(partition_hash.as_slice());
+            let result = watermark.build().execute(&mut *tx).await.map_err(|error| {
+                protocol_storage_error::<DB>("advance projection compaction watermark", error)
+            })?;
+            if DB::rows_affected(&result) != 1 {
+                return Err(corrupt_storage(
+                    "projection partition disappeared during compaction",
+                ));
+            }
+            tx.commit().await.map_err(|error| {
+                protocol_storage_error::<DB>("commit projection change compaction", error)
+            })?;
+            Ok(through.position())
+        }
+    }
+
+    fn projection_failure<'a>(
+        &'a self,
+        topology: &'a ProjectorTopologyId,
+        partition: &'a ProjectionPartition,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<Option<ProjectionFailure>, ProjectionProtocolError>> + Send + 'a
+    {
+        async move {
+            let Some(state) = load_partition(self.pool(), topology, partition).await? else {
+                return Ok(None);
+            };
+            let mut tx = self.pool().begin().await.map_err(|error| {
+                protocol_storage_error::<DB>("begin projection failure read", error)
+            })?;
+            Ok(failure_in_tx(
+                &mut tx,
+                topology,
+                partition,
+                failure_id,
+                &state.change_epoch,
+            )
+            .await?
+            .map(|stored| stored.failure))
+        }
+    }
+
+    fn projection_failure_location<'a>(
+        &'a self,
+        failure_id: &'a str,
+    ) -> impl Future<Output = Result<Option<ProjectionFailureLocation>, ProjectionProtocolError>>
+           + Send
+           + 'a {
+        async move {
+            let mut builder = QueryBuilder::<DB>::new(
+                "SELECT partition.topology_bytes, partition.topology_hash, \
+                 partition.partition_bytes, partition.partition_hash \
+                 FROM projection_failures failure \
+                 INNER JOIN projection_partitions partition \
+                 ON partition.topology_hash = failure.topology_hash \
+                 AND partition.partition_hash = failure.partition_hash \
+                 WHERE failure.failure_id = ",
+            );
+            builder.push_bind(failure_id);
+            let Some(row) = builder
+                .build()
+                .fetch_optional(self.pool())
+                .await
+                .map_err(|error| {
+                    protocol_storage_error::<DB>("resolve projection failure location", error)
+                })?
+            else {
+                return Ok(None);
+            };
+
+            let topology_bytes: Vec<u8> = row.try_get("topology_bytes").map_err(|error| {
+                protocol_storage_error::<DB>("decode repair topology bytes", error)
+            })?;
+            let topology = ProjectorTopologyId::from_canonical_bytes(&topology_bytes)?;
+            let topology_hash: Vec<u8> = row.try_get("topology_hash").map_err(|error| {
+                protocol_storage_error::<DB>("decode repair topology hash", error)
+            })?;
+            verify_digest(
+                &topology_hash,
+                topology.digest(),
+                "projection repair topology",
+            )?;
+
+            let partition_bytes: Vec<u8> = row.try_get("partition_bytes").map_err(|error| {
+                protocol_storage_error::<DB>("decode repair partition bytes", error)
+            })?;
+            let partition = ProjectionPartition::new(partition_bytes)?;
+            let partition_hash: Vec<u8> = row.try_get("partition_hash").map_err(|error| {
+                protocol_storage_error::<DB>("decode repair partition hash", error)
+            })?;
+            verify_digest(
+                &partition_hash,
+                partition.digest(),
+                "projection repair partition",
+            )?;
+
+            Ok(Some(ProjectionFailureLocation {
+                topology,
+                partition,
+            }))
+        }
+    }
+}
diff --git a/src/sqlx_repo/projection_protocol/tests.rs b/src/sqlx_repo/projection_protocol/tests.rs
new file mode 100644
index 00000000..94d2f279
--- /dev/null
+++ b/src/sqlx_repo/projection_protocol/tests.rs
@@ -0,0 +1,2525 @@
+#[cfg(all(test, feature = "sqlite"))]
+mod tests {
+    use std::path::{Path, PathBuf};
+    use std::sync::LazyLock;
+    use std::time::Duration;
+
+    use sqlx::sqlite::{SqliteConnectOptions, SqliteJournalMode, SqlitePoolOptions};
+    use sqlx::Row;
+
+    use super::*;
+    use crate::command_ledger::{
+        CanonicalInputHash, CausalCommitBatch, CausalTransactionalCommit,
+        CommandContractFingerprint, CommandId, CommandLedgerError, CommandLedgerKey,
+        CommandLedgerStore, CommandLookup, CommandLookupScope, CommandReservation,
+        PrincipalPartitionId, ReservationOutcome, TerminalCommandState,
+    };
+    use crate::projection_protocol::{
+        ProjectionCheckpointProbe, ProjectionObservationRequest, ProjectionQuerySnapshotRequest,
+        ProjectionRecordMutation, ProjectionScopeCodec,
+    };
+    use crate::repository::{CommitBatch, ReadModelWritePlanStore, TransactionalCommit};
+    use crate::table::{
+        ColumnType, DeleteTableRowMutation, ExpectedVersion, PrimaryKey, RowKey, RowValue,
+        RowValues, RowWriteMode, TableColumn, TableKind, TableRowMutation, TableSchema,
+        TableSchemaRegistry,
+    };
+
+    fn topology() -> ProjectorTopologyId {
+        ProjectorTopologyId::new(1, "sql_todo_projector", [17; 32]).unwrap()
+    }
+
+    fn other_topology() -> ProjectorTopologyId {
+        ProjectorTopologyId::new(1, "other_sql_todo_projector", [99; 32]).unwrap()
+    }
+
+    fn partition() -> ProjectionPartition {
+        ProjectionScopeCodec::new(topology())
+            .encode_partition(Some(&serde_json::json!("tenant-sql")))
+            .unwrap()
+    }
+
+    fn source(name: &str, key: &[u8]) -> ProjectionSource {
+        ProjectionSource::new(name, key.to_vec()).unwrap()
+    }
+
+    fn input_cursor_for(
+        source: ProjectionSource,
+        position: u64,
+        source_epoch: &str,
+    ) -> ProjectionInputCursor {
+        ProjectionInputCursor::new(
+            topology(),
+            partition(),
+            source,
+            ProjectionEpoch::new(source_epoch).unwrap(),
+            position,
+        )
+        .unwrap()
+    }
+
+    fn input_cursor(position: u64) -> ProjectionInputCursor {
+        input_cursor_for(source("todo_stream", b"todo-1"), position, "source-v1")
+    }
+
+    fn input(
+        position: u64,
+        fingerprint: &[u8],
+        message_id: &str,
+        causation_id: &str,
+        generation: ProjectionGeneration,
+    ) -> TrustedProjectionInput {
+        TrustedProjectionInput::mint(
+            input_cursor(position),
+            ProjectionInputFingerprint::from_canonical_bytes(fingerprint),
+            message_id,
+            causation_id,
+            generation,
+            true,
+        )
+        .unwrap()
+    }
+
+    fn non_gap_input(
+        position: u64,
+        fingerprint: &[u8],
+        message_id: &str,
+        causation_id: &str,
+        generation: ProjectionGeneration,
+    ) -> TrustedProjectionInput {
+        TrustedProjectionInput::mint(
+            input_cursor(position),
+            ProjectionInputFingerprint::from_canonical_bytes(fingerprint),
+            message_id,
+            causation_id,
+            generation,
+            false,
+        )
+        .unwrap()
+    }
+
+    fn input_for_source(
+        source: ProjectionSource,
+        position: u64,
+        fingerprint: &[u8],
+        message_id: &str,
+        causation_id: &str,
+    ) -> TrustedProjectionInput {
+        TrustedProjectionInput::mint(
+            input_cursor_for(source, position, "source-v1"),
+            ProjectionInputFingerprint::from_canonical_bytes(fingerprint),
+            message_id,
+            causation_id,
+            ProjectionGeneration::initial(),
+            true,
+        )
+        .unwrap()
+    }
+
+    fn change_epoch() -> ProjectionEpoch {
+        ProjectionEpoch::new("changes-v1").unwrap()
+    }
+
+    fn schema() -> &'static TableSchema {
+        static SCHEMA: LazyLock<TableSchema> = LazyLock::new(|| TableSchema {
+            model_name: "SqlTodoView".into(),
+            table_name: "sql_todo_views".into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new("id", "id", ColumnType::Text)
+                },
+                TableColumn {
+                    nullable: true,
+                    ..TableColumn::new("value", "value", ColumnType::Text)
+                },
+            ],
+            primary_key: PrimaryKey::new(["id"]),
+            version_column: Some(crate::table::DEFAULT_TABLE_VERSION_COLUMN.into()),
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        });
+        &SCHEMA
+    }
+
+    fn scope_codec() -> ProjectionScopeCodec {
+        ProjectionScopeCodec::with_models(topology(), [("SqlTodoView", schema())]).unwrap()
+    }
+
+    fn record_key() -> RowKey {
+        RowKey::new([("id", RowValue::String("todo-1".into()))])
+    }
+
+    fn record_scope() -> ProjectionRecordScope {
+        scope_codec()
+            .encode_row_scope_in_partition("SqlTodoView", partition(), &record_key())
+            .unwrap()
+    }
+
+    fn ownership() -> ProjectionModelOwnership {
+        ProjectionModelOwnership::new("SqlTodoView", "sql_todo_views").unwrap()
+    }
+
+    #[derive(Clone, Copy)]
+    struct ProjectionScenario;
+
+    impl crate::projection_protocol::scenario_tests::ProjectionProtocolScenario for ProjectionScenario {
+        type Store = SqlxRepository<sqlx::Sqlite>;
+
+        fn repository(&self) -> impl std::future::Future<Output = Self::Store> + Send {
+            repository()
+        }
+
+        fn topology(&self) -> ProjectorTopologyId {
+            topology()
+        }
+
+        fn other_topology(&self) -> ProjectorTopologyId {
+            other_topology()
+        }
+
+        fn partition(&self) -> ProjectionPartition {
+            partition()
+        }
+
+        fn change_epoch(&self) -> ProjectionEpoch {
+            change_epoch()
+        }
+
+        fn ownership(&self) -> ProjectionModelOwnership {
+            ownership()
+        }
+
+        fn mutation(
+            &self,
+            expectation: ProjectionRecordExpectation,
+            kind: ProjectionMutationKind,
+        ) -> ProjectionRecordMutation {
+            mutation(expectation, kind)
+        }
+
+        fn row_exists<'a>(
+            &'a self,
+            repository: &'a Self::Store,
+        ) -> impl std::future::Future<Output = bool> + Send + 'a {
+            async move { self::row_exists(repository).await }
+        }
+    }
+
+    async fn repository() -> SqlxRepository<sqlx::Sqlite> {
+        let repository = unregistered_repository().await;
+        repository
+            .register_projection_models(&topology(), &[ownership()])
+            .await
+            .unwrap();
+        repository
+    }
+
+    async fn repository_with_retention(max_retained_changes: u64) -> SqlxRepository<sqlx::Sqlite> {
+        let repository = unregistered_repository()
+            .await
+            .with_projection_change_retention(
+                ProjectionChangeRetention::new(max_retained_changes).unwrap(),
+            );
+        repository
+            .register_projection_models(&topology(), &[ownership()])
+            .await
+            .unwrap();
+        repository
+    }
+
+    async fn wal_repository_with_retention(
+        max_retained_changes: u64,
+    ) -> (SqlxRepository<sqlx::Sqlite>, PathBuf) {
+        let database_path = std::env::temp_dir().join(format!(
+            "distributed-projection-resume-{}.sqlite",
+            uuid::Uuid::now_v7()
+        ));
+        let pool = SqlitePoolOptions::new()
+            .max_connections(5)
+            .connect_with(
+                SqliteConnectOptions::new()
+                    .filename(&database_path)
+                    .create_if_missing(true)
+                    .journal_mode(SqliteJournalMode::Wal),
+            )
+            .await
+            .unwrap();
+        let repository = SqlxRepository::<sqlx::Sqlite>::new(pool)
+            .with_projection_change_retention(
+                ProjectionChangeRetention::new(max_retained_changes).unwrap(),
+            );
+        repository.migrate().await.unwrap();
+        let mut registry = TableSchemaRegistry::new();
+        registry.register_schema(schema().clone()).unwrap();
+        repository
+            .bootstrap_table_schema_for_dev(&registry)
+            .await
+            .unwrap();
+        repository
+            .register_projection_models(&topology(), &[ownership()])
+            .await
+            .unwrap();
+        (repository, database_path)
+    }
+
+    async fn remove_wal_database(repository: SqlxRepository<sqlx::Sqlite>, path: &Path) {
+        repository.pool().close().await;
+        for candidate in [
+            path.to_path_buf(),
+            path.with_extension("sqlite-wal"),
+            path.with_extension("sqlite-shm"),
+        ] {
+            match std::fs::remove_file(&candidate) {
+                Ok(()) => {}
+                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+                Err(error) => panic!(
+                    "remove SQLite projection resume test file {}: {error}",
+                    candidate.display()
+                ),
+            }
+        }
+    }
+
+    async fn unregistered_repository() -> SqlxRepository<sqlx::Sqlite> {
+        let repository = SqlxRepository::<sqlx::Sqlite>::connect_and_migrate("sqlite::memory:")
+            .await
+            .unwrap();
+        let mut registry = TableSchemaRegistry::new();
+        registry.register_schema(schema().clone()).unwrap();
+        repository
+            .bootstrap_table_schema_for_dev(&registry)
+            .await
+            .unwrap();
+        repository
+    }
+
+    fn upsert_table_mutation(id: &str) -> TableMutation {
+        let key = RowKey::new([("id", RowValue::String(id.into()))]);
+        let mut values = RowValues::new();
+        values.insert("id", RowValue::String(id.into()));
+        TableMutation::UpsertRow(TableRowMutation {
+            schema: schema(),
+            key,
+            values,
+            expected_version: ExpectedVersion::Any,
+            mode: RowWriteMode::Upsert,
+        })
+    }
+
+    fn valued_mutation(
+        value: u64,
+        expectation: ProjectionRecordExpectation,
+    ) -> ProjectionRecordMutation {
+        let mut values = RowValues::new();
+        values.insert("id", RowValue::String("todo-1".into()));
+        values.insert("value", RowValue::String(value.to_string()));
+        ProjectionRecordMutation::new(
+            record_scope(),
+            TableMutation::UpsertRow(TableRowMutation {
+                schema: schema(),
+                key: record_key(),
+                values,
+                expected_version: ExpectedVersion::Any,
+                mode: RowWriteMode::Upsert,
+            }),
+            expectation,
+            ProjectionMutationKind::Upsert,
+        )
+        .unwrap()
+    }
+
+    fn snapshot_request() -> ProjectionQuerySnapshotRequest {
+        ProjectionQuerySnapshotRequest::new(
+            &scope_codec(),
+            Some(&serde_json::json!("tenant-sql")),
+            "SqlTodoView",
+            record_key(),
+            vec![ProjectionCheckpointProbe::new(
+                topology(),
+                partition(),
+                source("todo_stream", b"todo-1"),
+                ProjectionEpoch::new("source-v1").unwrap(),
+                ProjectionGeneration::initial(),
+            )],
+        )
+        .unwrap()
+    }
+
+    fn mutation(
+        expectation: ProjectionRecordExpectation,
+        kind: ProjectionMutationKind,
+    ) -> ProjectionRecordMutation {
+        let table = match kind {
+            ProjectionMutationKind::Delete => TableMutation::DeleteRow(DeleteTableRowMutation {
+                schema: schema(),
+                key: RowKey::new([("id", RowValue::String("todo-1".into()))]),
+                expected_version: ExpectedVersion::Any,
+            }),
+            ProjectionMutationKind::Upsert | ProjectionMutationKind::Recreate => {
+                upsert_table_mutation("todo-1")
+            }
+        };
+        ProjectionRecordMutation::new(record_scope(), table, expectation, kind).unwrap()
+    }
+
+    fn batch(
+        trusted: TrustedProjectionInput,
+        mutations: Vec<ProjectionRecordMutation>,
+        observations: Vec<ProjectionObservationRequest>,
+    ) -> ProjectionCommitBatch {
+        ProjectionCommitBatch {
+            input: trusted,
+            change_epoch: change_epoch(),
+            ownership: vec![ownership()],
+            mutations,
+            observations,
+        }
+    }
+
+    async fn row_exists(repository: &SqlxRepository<sqlx::Sqlite>) -> bool {
+        let row = sqlx::query("SELECT 1 AS present FROM sql_todo_views WHERE id = ? LIMIT 1")
+            .bind("todo-1")
+            .fetch_optional(repository.pool())
+            .await
+            .unwrap();
+        row.and_then(|row| row.try_get::<i64, _>("present").ok())
+            .is_some()
+    }
+
+    fn assert_query_snapshot_is_coherent(snapshot: &ProjectionQuerySnapshot) {
+        let row = snapshot.row.as_ref().expect("physical row");
+        let record = snapshot.record.as_ref().expect("record metadata");
+        let checkpoint = snapshot.checkpoints[0]
+            .checkpoint
+            .as_ref()
+            .expect("source checkpoint");
+        let value = match row.get("value") {
+            Some(RowValue::String(value)) => value.parse::<u64>().unwrap(),
+            other => panic!("unexpected query snapshot value {other:?}"),
+        };
+        assert_eq!(value, record.revision.revision());
+        assert_eq!(value, checkpoint.input().position());
+        assert_eq!(record.change, *checkpoint.change());
+        assert_eq!(
+            snapshot.change_head.as_ref(),
+            Some(checkpoint.change()),
+            "live resume head must come from the same SQL statement snapshot"
+        );
+        assert_eq!(snapshot.compacted_through, 0);
+    }
+
+    #[tokio::test]
+    async fn sqlite_query_snapshot_never_mixes_row_revision_checkpoint_or_resume_head() {
+        let repository = repository().await;
+        let first = repository
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"snapshot-1",
+                    "snapshot-message-1",
+                    "snapshot-cause-1",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![valued_mutation(1, ProjectionRecordExpectation::Missing)],
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        let mut expected = first.records[0].revision.clone();
+        assert_query_snapshot_is_coherent(
+            &repository
+                .projection_query_snapshot(&snapshot_request())
+                .await
+                .unwrap(),
+        );
+
+        let writer_repository = repository.clone();
+        let writer = tokio::spawn(async move {
+            for position in 2..=32 {
+                let committed = writer_repository
+                    .commit_projection(batch(
+                        input(
+                            position,
+                            format!("snapshot-{position}").as_bytes(),
+                            &format!("snapshot-message-{position}"),
+                            &format!("snapshot-cause-{position}"),
+                            ProjectionGeneration::initial(),
+                        ),
+                        vec![valued_mutation(
+                            position,
+                            ProjectionRecordExpectation::Exact(expected),
+                        )],
+                        Vec::new(),
+                    ))
+                    .await
+                    .unwrap();
+                expected = committed.records[0].revision.clone();
+                tokio::task::yield_now().await;
+            }
+        });
+
+        while !writer.is_finished() {
+            let batch = repository
+                .projection_query_snapshot_batch(
+                    &ProjectionQuerySnapshotBatchRequest::new(vec![
+                        snapshot_request(),
+                        snapshot_request(),
+                    ])
+                    .unwrap(),
+                )
+                .await
+                .unwrap();
+            assert_eq!(batch.snapshots[0], batch.snapshots[1]);
+            assert_query_snapshot_is_coherent(&batch.snapshots[0]);
+            tokio::task::yield_now().await;
+        }
+        writer.await.unwrap();
+        assert_query_snapshot_is_coherent(
+            &repository
+                .projection_query_snapshot(&snapshot_request())
+                .await
+                .unwrap(),
+        );
+    }
+
+    #[tokio::test]
+    async fn sqlite_input_disposition_is_read_only_exact_and_repair_fenced() {
+        crate::projection_protocol::scenario_tests::input_disposition_is_read_only_exact_and_repair_fenced(
+            ProjectionScenario,
+        )
+        .await;
+    }
+
+    #[tokio::test]
+    async fn sqlite_obligation_and_unpartitioned_live_evidence_are_exact_and_durable() {
+        let evidence_repository = repository().await;
+        let scope = record_scope();
+        let live_request = ProjectionLiveRecordBatchRequest::new(vec![
+            crate::projection_protocol::ProjectionLiveRecordRequest::new(
+                &scope_codec(),
+                "SqlTodoView",
+                record_key(),
+            )
+            .unwrap(),
+        ])
+        .unwrap();
+        assert_eq!(
+            evidence_repository
+                .projection_live_record_batch(&live_request)
+                .await
+                .unwrap()
+                .records,
+            vec![None]
+        );
+
+        let created = evidence_repository
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"evidence-created",
+                    "evidence-message-1",
+                    "evidence-cause",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![mutation(
+                    ProjectionRecordExpectation::Missing,
+                    ProjectionMutationKind::Upsert,
+                )],
+                vec![ProjectionObservationRequest {
+                    kind: ProjectionObservationKind::Record,
+                    target: ProjectionObservationTarget::StagedRecord(scope.clone()),
+                }],
+            ))
+            .await
+            .unwrap();
+        assert_eq!(
+            evidence_repository
+                .projection_live_record_batch(&live_request)
+                .await
+                .unwrap()
+                .records[0]
+                .as_ref()
+                .unwrap()
+                .revision
+                .scope(),
+            &scope
+        );
+        let observed = crate::projection_protocol::ProjectionObligationEvidenceRequest::new(
+            "evidence-cause",
+            scope.clone(),
+            ProjectionObservationKind::Record,
+        )
+        .unwrap();
+        let pending = crate::projection_protocol::ProjectionObligationEvidenceRequest::new(
+            "pending-cause",
+            scope.clone(),
+            ProjectionObservationKind::Record,
+        )
+        .unwrap();
+        let before_failure = evidence_repository
+            .projection_obligation_evidence_batch(
+                &ProjectionObligationEvidenceBatchRequest::new(vec![
+                    observed.clone(),
+                    pending.clone(),
+                ])
+                .unwrap(),
+            )
+            .await
+            .unwrap();
+        assert!(matches!(
+            &before_failure.evidence[0],
+            ProjectionObligationEvidence::Observed(observation)
+                if observation.change == created.changes[0].cursor
+        ));
+        assert_eq!(
+            before_failure.evidence[1],
+            ProjectionObligationEvidence::Pending
+        );
+
+        let failure = evidence_repository
+            .record_projection_failure(
+                ProjectionFailureBatch::new(
+                    input(
+                        2,
+                        b"evidence-failed",
+                        "evidence-message-2",
+                        "evidence-cause",
+                        ProjectionGeneration::initial(),
+                    ),
+                    change_epoch(),
+                    "evidence-failure",
+                    "decode_error",
+                    b"bad evidence payload".to_vec(),
+                )
+                .unwrap(),
+            )
+            .await
+            .unwrap();
+        evidence_repository
+            .compact_projection_changes(&failure.change)
+            .await
+            .unwrap();
+        let after_failure = evidence_repository
+            .projection_obligation_evidence_batch(
+                &ProjectionObligationEvidenceBatchRequest::new(vec![observed, pending]).unwrap(),
+            )
+            .await
+            .unwrap();
+        assert!(matches!(
+            &after_failure.evidence[0],
+            ProjectionObligationEvidence::TerminalFailure(stored)
+                if stored == &failure
+        ));
+        assert_eq!(
+            after_failure.evidence[1],
+            ProjectionObligationEvidence::Pending
+        );
+
+        let moved_repository = repository().await;
+        let old_scope = record_scope();
+        let old = moved_repository
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"move-old",
+                    "move-message-1",
+                    "move-cause-1",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![mutation(
+                    ProjectionRecordExpectation::Missing,
+                    ProjectionMutationKind::Upsert,
+                )],
+                Vec::new(),
+            ))
+            .await
+            .unwrap()
+            .records
+            .remove(0);
+        moved_repository
+            .commit_projection(batch(
+                input(
+                    2,
+                    b"move-delete",
+                    "move-message-2",
+                    "move-cause-2",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![mutation(
+                    ProjectionRecordExpectation::Exact(old.revision),
+                    ProjectionMutationKind::Delete,
+                )],
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        assert_eq!(
+            moved_repository
+                .projection_live_record_batch(&live_request)
+                .await
+                .unwrap()
+                .records,
+            vec![None]
+        );
+
+        let new_partition = scope_codec()
+            .encode_partition(Some(&serde_json::json!("tenant-moved")))
+            .unwrap();
+        let new_scope = scope_codec()
+            .encode_row_scope_in_partition("SqlTodoView", new_partition.clone(), &record_key())
+            .unwrap();
+        let new_input = TrustedProjectionInput::mint(
+            ProjectionInputCursor::new(
+                topology(),
+                new_partition,
+                source("todo_stream", b"todo-1"),
+                ProjectionEpoch::new("source-v1").unwrap(),
+                1,
+            )
+            .unwrap(),
+            ProjectionInputFingerprint::from_canonical_bytes(b"move-new"),
+            "move-message-3",
+            "move-cause-3",
+            ProjectionGeneration::initial(),
+            true,
+        )
+        .unwrap();
+        moved_repository
+            .commit_projection(ProjectionCommitBatch {
+                input: new_input,
+                change_epoch: change_epoch(),
+                ownership: vec![ownership()],
+                mutations: vec![ProjectionRecordMutation::new(
+                    new_scope.clone(),
+                    upsert_table_mutation("todo-1"),
+                    ProjectionRecordExpectation::Missing,
+                    ProjectionMutationKind::Upsert,
+                )
+                .unwrap()],
+                observations: Vec::new(),
+            })
+            .await
+            .unwrap();
+        assert_eq!(
+            moved_repository
+                .projection_live_record_batch(&live_request)
+                .await
+                .unwrap()
+                .records[0]
+                .as_ref()
+                .unwrap()
+                .revision
+                .scope(),
+            &new_scope
+        );
+
+        let old_partition_hash = partition().digest();
+        assert!(
+            sqlx::query(
+                "UPDATE projection_records SET tombstone = 0 \
+                 WHERE topology_hash = ? AND partition_hash = ? AND model_name = ?",
+            )
+            .bind(topology().digest().as_slice())
+            .bind(old_partition_hash.as_slice())
+            .bind("SqlTodoView")
+            .execute(moved_repository.pool())
+            .await
+            .is_err(),
+            "the partial unique index must reject a second live partition"
+        );
+        sqlx::query("DROP INDEX projection_records_unique_live_identity")
+            .execute(moved_repository.pool())
+            .await
+            .unwrap();
+        sqlx::query(
+            "UPDATE projection_records SET tombstone = 0 \
+             WHERE topology_hash = ? AND partition_hash = ? AND model_name = ?",
+        )
+        .bind(topology().digest().as_slice())
+        .bind(old_partition_hash.as_slice())
+        .bind("SqlTodoView")
+        .execute(moved_repository.pool())
+        .await
+        .unwrap();
+        assert!(matches!(
+            moved_repository
+                .projection_live_record_batch(&live_request)
+                .await,
+            Err(ProjectionProtocolError::InvalidBatch(message))
+                if message.contains("ambiguous")
+        ));
+
+        let drift_repository = repository().await;
+        drift_repository
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"drift",
+                    "drift-message-1",
+                    "drift-cause-1",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![mutation(
+                    ProjectionRecordExpectation::Missing,
+                    ProjectionMutationKind::Upsert,
+                )],
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        sqlx::query(
+            "UPDATE projection_records SET canonical_key_bytes = ? \
+             WHERE topology_hash = ? AND model_name = ?",
+        )
+        .bind(b"corrupt-key".as_slice())
+        .bind(topology().digest().as_slice())
+        .bind("SqlTodoView")
+        .execute(drift_repository.pool())
+        .await
+        .unwrap();
+        assert!(matches!(
+            drift_repository
+                .projection_live_record_batch(&live_request)
+                .await,
+            Err(ProjectionProtocolError::InvalidBatch(message))
+                if message.contains("canonical key")
+        ));
+
+        // Keep the compiler from treating the old exact scope as an incidental
+        // local: it is the durable tombstone retained across the move.
+        assert_ne!(old_scope, new_scope);
+    }
+
+    #[tokio::test]
+    async fn sqlite_receipts_source_fences_and_raw_write_fence_are_exact() {
+        let repository = repository().await;
+        let raw_error = repository
+            .commit_write_plan(TableWritePlan::new(vec![upsert_table_mutation("todo-1")]))
+            .await
+            .unwrap_err();
+        assert!(matches!(
+            raw_error,
+            TableStoreError::CausalWriteRequired { ref table } if table == "sql_todo_views"
+        ));
+
+        let applied = repository
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"one",
+                    "message-1",
+                    "cause-1",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![mutation(
+                    ProjectionRecordExpectation::Missing,
+                    ProjectionMutationKind::Upsert,
+                )],
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        assert_eq!(applied.outcome, ProjectionCommitOutcome::Applied);
+        assert!(row_exists(&repository).await);
+
+        let duplicate = repository
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"one",
+                    "message-1",
+                    "cause-1",
+                    ProjectionGeneration::initial(),
+                ),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        assert_eq!(duplicate.outcome, ProjectionCommitOutcome::Duplicate);
+        assert_eq!(
+            duplicate.checkpoint.as_ref().unwrap().change(),
+            applied.checkpoint.as_ref().unwrap().change()
+        );
+
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        1,
+                        b"changed",
+                        "new-message",
+                        "cause-1",
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::InputCorruption)
+        ));
+
+        repository
+            .commit_projection(batch(
+                input(
+                    2,
+                    b"two",
+                    "message-2",
+                    "cause-2",
+                    ProjectionGeneration::initial(),
+                ),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        let old_after_advance = repository
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"one",
+                    "message-1",
+                    "cause-1",
+                    ProjectionGeneration::initial(),
+                ),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        assert_eq!(
+            old_after_advance.outcome,
+            ProjectionCommitOutcome::Duplicate
+        );
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        1,
+                        b"changed-after-advance",
+                        "new-message-after-advance",
+                        "cause-1",
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::InputCorruption)
+        ));
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        3,
+                        b"three",
+                        "message-1",
+                        "cause-3",
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::MessageIdReuse { .. })
+        ));
+        let stale = repository
+            .commit_projection(batch(
+                input(
+                    0,
+                    b"stale",
+                    "stale-message",
+                    "stale-cause",
+                    ProjectionGeneration::initial(),
+                ),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        assert_eq!(stale.outcome, ProjectionCommitOutcome::StaleInput);
+        let changed_capability = TrustedProjectionInput::mint(
+            input_cursor(3),
+            ProjectionInputFingerprint::from_canonical_bytes(b"changed-capability"),
+            "capability-message",
+            "capability-cause",
+            ProjectionGeneration::initial(),
+            false,
+        )
+        .unwrap();
+        assert!(matches!(
+            repository
+                .commit_projection(batch(changed_capability, Vec::new(), Vec::new()))
+                .await,
+            Err(ProjectionProtocolError::InputCorruption)
+        ));
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        4,
+                        b"gap",
+                        "message-4",
+                        "cause-4",
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::IncomparableInput)
+        ));
+
+        let other_source = source("audit_stream", b"audit-1");
+        let other = input_for_source(
+            other_source.clone(),
+            41,
+            b"audit",
+            "audit-message",
+            "audit-cause",
+        );
+        repository
+            .commit_projection(batch(other, Vec::new(), Vec::new()))
+            .await
+            .unwrap();
+        assert_eq!(
+            repository
+                .projection_checkpoint(
+                    &input_cursor_for(other_source, 0, "source-v1"),
+                    ProjectionGeneration::initial(),
+                )
+                .await
+                .unwrap()
+                .unwrap()
+                .input()
+                .position(),
+            41
+        );
+
+        let mut transactional = CommitBatch::empty();
+        transactional
+            .read_model_plans
+            .push(TableWritePlan::new(vec![upsert_table_mutation("todo-1")]));
+        assert!(matches!(
+            repository.commit_batch(transactional).await,
+            Err(crate::RepositoryError::CausalWriteRequired { .. })
+        ));
+    }
+
+    #[tokio::test]
+    async fn sqlite_message_identity_is_topology_wide_across_projection_partitions() {
+        crate::projection_protocol::scenario_tests::message_identity_is_topology_wide_across_projection_partitions(
+            ProjectionScenario,
+        )
+        .await;
+    }
+
+    #[tokio::test]
+    async fn sqlite_failure_recording_is_idempotent_for_exact_batch() {
+        crate::projection_protocol::scenario_tests::failure_recording_is_idempotent_for_exact_batch(
+            ProjectionScenario,
+        )
+        .await;
+    }
+
+    #[tokio::test]
+    async fn sqlite_row_failure_rolls_back_protocol_receipt_inbox_and_domain_row() {
+        let repository = repository().await;
+        sqlx::query(
+            "CREATE TRIGGER fail_sql_todo_insert BEFORE INSERT ON sql_todo_views \
+             BEGIN SELECT RAISE(ABORT, 'forced projection row failure'); END",
+        )
+        .execute(repository.pool())
+        .await
+        .unwrap();
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        1,
+                        b"rollback",
+                        "rollback-message",
+                        "rollback-cause",
+                        ProjectionGeneration::initial(),
+                    ),
+                    vec![mutation(
+                        ProjectionRecordExpectation::Missing,
+                        ProjectionMutationKind::Upsert,
+                    )],
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::Table(_))
+        ));
+        assert!(!row_exists(&repository).await);
+        assert!(repository
+            .projection_record(&record_scope())
+            .await
+            .unwrap()
+            .is_none());
+        assert!(repository
+            .projection_checkpoint(&input_cursor(1), ProjectionGeneration::initial(),)
+            .await
+            .unwrap()
+            .is_none());
+        sqlx::query("DROP TRIGGER fail_sql_todo_insert")
+            .execute(repository.pool())
+            .await
+            .unwrap();
+        assert_eq!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        1,
+                        b"rollback",
+                        "rollback-message",
+                        "rollback-cause",
+                        ProjectionGeneration::initial(),
+                    ),
+                    vec![mutation(
+                        ProjectionRecordExpectation::Missing,
+                        ProjectionMutationKind::Upsert,
+                    )],
+                    Vec::new(),
+                ))
+                .await
+                .unwrap()
+                .outcome,
+            ProjectionCommitOutcome::Applied
+        );
+    }
+
+    #[tokio::test]
+    async fn sqlite_rejects_tampered_failure_digest_before_any_protocol_write() {
+        let repository = repository().await;
+        let mut failure = ProjectionFailureBatch::new(
+            input(
+                1,
+                b"tampered-failure",
+                "tampered-failure-message",
+                "tampered-failure-cause",
+                ProjectionGeneration::initial(),
+            ),
+            change_epoch(),
+            "tampered-failure-id",
+            "decode_error",
+            b"shape-valid failure details".to_vec(),
+        )
+        .unwrap();
+        failure.failure_digest[0] ^= 0xff;
+
+        assert!(matches!(
+            repository.record_projection_failure(failure).await,
+            Err(ProjectionProtocolError::InvalidBatch(message))
+                if message == "projection failure digest does not match its exact bytes"
+        ));
+        for (table, count_sql) in [
+            (
+                "projection_partitions",
+                "SELECT COUNT(*) FROM projection_partitions",
+            ),
+            (
+                "projection_changes",
+                "SELECT COUNT(*) FROM projection_changes",
+            ),
+            (
+                "projection_failures",
+                "SELECT COUNT(*) FROM projection_failures",
+            ),
+            (
+                "projection_input_identities",
+                "SELECT COUNT(*) FROM projection_input_identities",
+            ),
+            (
+                "projection_input_receipts",
+                "SELECT COUNT(*) FROM projection_input_receipts",
+            ),
+            ("consumer_inbox", "SELECT COUNT(*) FROM consumer_inbox"),
+        ] {
+            let count: i64 = sqlx::query_scalar(count_sql)
+                .fetch_one(repository.pool())
+                .await
+                .unwrap();
+            assert_eq!(
+                count, 0,
+                "tampered failure validation must precede writes to {table}"
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn sqlite_tombstones_observations_failure_repair_and_compaction_conform() {
+        let repository = repository().await;
+        let scope = record_scope();
+        assert_eq!(
+            repository
+                .projection_partition_runtime_state(&topology(), &partition())
+                .await
+                .unwrap(),
+            None
+        );
+        let created = repository
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"create",
+                    "message-1",
+                    "stable-cause",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![mutation(
+                    ProjectionRecordExpectation::Missing,
+                    ProjectionMutationKind::Upsert,
+                )],
+                vec![ProjectionObservationRequest {
+                    kind: ProjectionObservationKind::Record,
+                    target: ProjectionObservationTarget::StagedRecord(scope.clone()),
+                }],
+            ))
+            .await
+            .unwrap();
+        assert_eq!(created.changes.len(), 1);
+        let earliest = repository
+            .projection_observation("stable-cause", &scope, ProjectionObservationKind::Record)
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(earliest.change, created.changes[0].cursor);
+
+        let deleted = repository
+            .commit_projection(batch(
+                input(
+                    2,
+                    b"delete",
+                    "message-2",
+                    "stable-cause",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![mutation(
+                    ProjectionRecordExpectation::Exact(created.records[0].revision.clone()),
+                    ProjectionMutationKind::Delete,
+                )],
+                vec![ProjectionObservationRequest {
+                    kind: ProjectionObservationKind::Record,
+                    target: ProjectionObservationTarget::StagedRecord(scope.clone()),
+                }],
+            ))
+            .await
+            .unwrap();
+        assert!(deleted.records[0].tombstone);
+        assert!(!row_exists(&repository).await);
+        assert_eq!(
+            repository
+                .projection_observation("stable-cause", &scope, ProjectionObservationKind::Record,)
+                .await
+                .unwrap()
+                .unwrap(),
+            earliest
+        );
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        3,
+                        b"plain-upsert",
+                        "message-3",
+                        "cause-3",
+                        ProjectionGeneration::initial(),
+                    ),
+                    vec![mutation(
+                        ProjectionRecordExpectation::Exact(deleted.records[0].revision.clone(),),
+                        ProjectionMutationKind::Upsert,
+                    )],
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::RecordTombstoned { .. })
+        ));
+        let recreated = repository
+            .commit_projection(batch(
+                input(
+                    3,
+                    b"recreate",
+                    "message-3b",
+                    "cause-3",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![mutation(
+                    ProjectionRecordExpectation::Exact(deleted.records[0].revision.clone()),
+                    ProjectionMutationKind::Recreate,
+                )],
+                vec![ProjectionObservationRequest {
+                    kind: ProjectionObservationKind::Dependency,
+                    target: ProjectionObservationTarget::Dependency(scope.clone()),
+                }],
+            ))
+            .await
+            .unwrap();
+        assert_eq!(recreated.records[0].revision.incarnation(), 2);
+        assert_eq!(recreated.records[0].revision.revision(), 1);
+        assert_eq!(recreated.changes.len(), 2);
+        assert!(repository
+            .projection_observation("cause-3", &scope, ProjectionObservationKind::Dependency,)
+            .await
+            .unwrap()
+            .unwrap()
+            .revision
+            .is_none());
+
+        let failure_batch = ProjectionFailureBatch::new(
+            input(
+                4,
+                b"failure",
+                "message-4",
+                "cause-4",
+                ProjectionGeneration::initial(),
+            ),
+            change_epoch(),
+            "failure-4",
+            "decode_error",
+            b"bad payload".to_vec(),
+        )
+        .unwrap();
+        let failure = repository
+            .record_projection_failure(failure_batch.clone())
+            .await
+            .unwrap();
+        assert_eq!(
+            repository
+                .record_projection_failure(failure_batch.clone())
+                .await
+                .unwrap(),
+            failure
+        );
+        assert_eq!(
+            repository
+                .projection_failure(&topology(), &partition(), "failure-4")
+                .await
+                .unwrap(),
+            Some(failure.clone())
+        );
+        assert!(failure.gap_free);
+        let stopped = repository
+            .projection_partition_runtime_state(&topology(), &partition())
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(stopped.active_generation, ProjectionGeneration::initial());
+        assert_eq!(stopped.stopped_failure_id.as_deref(), Some("failure-4"));
+        assert_eq!(stopped.pending_retry, None);
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        5,
+                        b"blocked",
+                        "message-5",
+                        "cause-5",
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::PartitionStopped { .. })
+        ));
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        4,
+                        b"changed-while-stopped",
+                        "changed-message-4",
+                        "cause-4",
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::InputCorruption)
+        ));
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        5,
+                        b"reused-message-while-stopped",
+                        "message-4",
+                        "cause-5",
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::MessageIdReuse { .. })
+        ));
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        4,
+                        b"failure",
+                        "message-4",
+                        "cause-4",
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::PartitionStopped { .. })
+        ));
+        let generation = repository
+            .repair_projection(&topology(), &partition(), "failure-4")
+            .await
+            .unwrap();
+        assert_eq!(generation.get(), 2);
+        let repaired = repository
+            .projection_partition_runtime_state(&topology(), &partition())
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(repaired.active_generation, generation);
+        assert_eq!(repaired.stopped_failure_id, None);
+        let retry = repaired.pending_retry.unwrap();
+        assert_eq!(retry.failure_id, "failure-4");
+        assert_eq!(retry.input, failure.input);
+        assert_eq!(retry.input_fingerprint, failure.input_fingerprint);
+        assert_eq!(retry.message_id, failure.message_id);
+        assert_eq!(retry.causation_id, failure.causation_id);
+        assert_eq!(retry.failed_generation, failure.generation);
+        assert_eq!(retry.gap_free, failure.gap_free);
+        assert!(matches!(
+            repository.record_projection_failure(failure_batch).await,
+            Err(ProjectionProtocolError::GenerationFenced {
+                expected: 2,
+                actual: 1
+            })
+        ));
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        4,
+                        b"changed-old-generation",
+                        "changed-old-message-4",
+                        "cause-4",
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::InputCorruption)
+        ));
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(
+                        6,
+                        b"unknown-old-generation",
+                        "unknown-old-message-6",
+                        "unknown-old-cause-6",
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::GenerationFenced {
+                expected: 2,
+                actual: 1
+            })
+        ));
+        let changed_old_capability = TrustedProjectionInput::mint(
+            input_cursor(6),
+            ProjectionInputFingerprint::from_canonical_bytes(b"changed-old-capability"),
+            "changed-old-capability-message",
+            "changed-old-capability-cause",
+            ProjectionGeneration::initial(),
+            false,
+        )
+        .unwrap();
+        assert!(matches!(
+            repository
+                .commit_projection(batch(changed_old_capability, Vec::new(), Vec::new()))
+                .await,
+            Err(ProjectionProtocolError::InputCorruption)
+        ));
+        assert_eq!(
+            repository
+                .commit_projection(batch(
+                    input(3, b"recreate", "message-3b", "cause-3", generation),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await
+                .unwrap()
+                .outcome,
+            ProjectionCommitOutcome::Duplicate
+        );
+        assert_eq!(
+            repository
+                .commit_projection(batch(
+                    input(2, b"delete", "message-2", "stable-cause", generation),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await
+                .unwrap()
+                .outcome,
+            ProjectionCommitOutcome::StaleInput
+        );
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(5, b"later", "message-5", "cause-5", generation),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::IncomparableInput)
+        ));
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    input(4, b"retry", "message-4b", "cause-4", generation),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::InputCorruption)
+        ));
+        let repaired = repository
+            .commit_projection(batch(
+                input(4, b"failure", "message-4", "cause-4", generation),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        assert_eq!(repaired.changes[0].kind, ProjectionChangeKind::Checkpoint);
+        assert_eq!(
+            repository
+                .commit_projection(batch(
+                    input(5, b"later", "message-5", "cause-5", generation),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await
+                .unwrap()
+                .outcome,
+            ProjectionCommitOutcome::Applied
+        );
+
+        let compacted = repository
+            .compact_projection_changes(&created.changes[0].cursor)
+            .await
+            .unwrap();
+        assert_eq!(compacted, created.changes[0].cursor.position());
+        assert!(matches!(
+            repository
+                .projection_changes(
+                    &topology(),
+                    &partition(),
+                    Some(&created.changes[0].cursor),
+                    100,
+                )
+                .await
+                .unwrap(),
+            ProjectionChangeRead::Changes {
+                compacted_through,
+                ref changes,
+                ..
+            } if compacted_through == compacted && !changes.is_empty()
+        ));
+        assert!(matches!(
+            repository
+                .projection_changes(&topology(), &partition(), None, 100)
+                .await
+                .unwrap(),
+            ProjectionChangeRead::ResetRequired {
+                compacted_through,
+                ..
+            } if compacted_through == compacted
+        ));
+        repository
+            .compact_projection_changes(&failure.change)
+            .await
+            .unwrap();
+        assert!(matches!(
+            repository
+                .projection_changes(
+                    &topology(),
+                    &partition(),
+                    Some(&created.changes[0].cursor),
+                    100,
+                )
+                .await
+                .unwrap(),
+            ProjectionChangeRead::ResetRequired { .. }
+        ));
+
+        let failed_first = self::repository().await;
+        failed_first
+            .record_projection_failure(
+                ProjectionFailureBatch::new(
+                    input(
+                        0,
+                        b"failed-first",
+                        "failed-first-message",
+                        "failed-first-cause",
+                        ProjectionGeneration::initial(),
+                    ),
+                    change_epoch(),
+                    "failed-first-id",
+                    "decode_error",
+                    b"bad first payload".to_vec(),
+                )
+                .unwrap(),
+            )
+            .await
+            .unwrap();
+        let repaired_generation = failed_first
+            .repair_projection(&topology(), &partition(), "failed-first-id")
+            .await
+            .unwrap();
+        assert!(matches!(
+            failed_first
+                .commit_projection(batch(
+                    input(
+                        1,
+                        b"later-first",
+                        "later-first-message",
+                        "later-first-cause",
+                        repaired_generation,
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::IncomparableInput)
+        ));
+        let changed_after_repair = TrustedProjectionInput::mint(
+            input_cursor(0),
+            ProjectionInputFingerprint::from_canonical_bytes(b"retry"),
+            "retry-message",
+            "retry-cause",
+            repaired_generation,
+            false,
+        )
+        .unwrap();
+        assert!(matches!(
+            failed_first
+                .commit_projection(batch(changed_after_repair, Vec::new(), Vec::new()))
+                .await,
+            Err(ProjectionProtocolError::InputCorruption)
+        ));
+    }
+
+    #[tokio::test]
+    async fn sqlite_registration_rejects_legacy_rows_and_cross_topology_table_owners() {
+        let with_legacy_row = unregistered_repository().await;
+        assert!(matches!(
+            with_legacy_row
+                .register_projection_models(&topology(), &[])
+                .await,
+            Err(ProjectionProtocolError::InvalidBatch(message))
+                if message.contains("at least one owned model")
+        ));
+        with_legacy_row
+            .commit_write_plan(TableWritePlan::new(vec![upsert_table_mutation("legacy")]))
+            .await
+            .unwrap();
+        assert!(matches!(
+            with_legacy_row
+                .register_projection_models(&topology(), &[ownership()])
+                .await,
+            Err(ProjectionProtocolError::InvalidBatch(message))
+                if message.contains("unverified legacy rows")
+        ));
+
+        // Deterministically hold the raw-writer fence while bootstrap starts.
+        // Raw-first must commit its row; bootstrap then wakes, observes that
+        // legacy row under the same fence, and rejects causal ownership.
+        let racing = unregistered_repository().await;
+        let mut raw_tx = racing.pool().begin().await.unwrap();
+        let racing_tables = BTreeSet::from(["sql_todo_views".to_string()]);
+        lock_projection_table_ownership_fences_in_tx(&mut raw_tx, &racing_tables)
+            .await
+            .unwrap();
+        let registration_repository = racing.clone();
+        let registration = tokio::spawn(async move {
+            registration_repository
+                .register_projection_models(&topology(), &[ownership()])
+                .await
+        });
+        tokio::task::yield_now().await;
+        assert!(!registration.is_finished());
+        apply_read_model_write_plan_in_tx(
+            &mut raw_tx,
+            TableWritePlan::new(vec![upsert_table_mutation("racing-legacy")]),
+        )
+        .await
+        .unwrap();
+        raw_tx.commit().await.unwrap();
+        assert!(matches!(
+            registration.await.unwrap(),
+            Err(ProjectionProtocolError::InvalidBatch(message))
+                if message.contains("unverified legacy rows")
+        ));
+
+        let registered = repository().await;
+        assert!(matches!(
+            registered
+                .register_projection_models(&other_topology(), &[ownership()])
+                .await,
+            Err(ProjectionProtocolError::InvalidBatch(message))
+                if message.contains("authoritatively owned")
+        ));
+    }
+
+    #[tokio::test]
+    async fn sqlite_shared_registered_table_ownership_rejects_other_topology() {
+        crate::projection_protocol::scenario_tests::registered_table_ownership_rejects_other_topology(
+            ProjectionScenario,
+        )
+        .await;
+    }
+
+    #[tokio::test]
+    async fn sqlite_tombstone_requires_explicit_exact_recreation() {
+        crate::projection_protocol::scenario_tests::tombstone_requires_explicit_exact_recreation(
+            ProjectionScenario,
+        )
+        .await;
+    }
+
+    #[tokio::test]
+    async fn sqlite_non_gap_repair_requires_failed_cursor_before_later_input() {
+        let repository = repository().await;
+        repository
+            .commit_projection(batch(
+                non_gap_input(
+                    5,
+                    b"checkpoint-5",
+                    "non-gap-message-5",
+                    "non-gap-cause-5",
+                    ProjectionGeneration::initial(),
+                ),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        repository
+            .record_projection_failure(
+                ProjectionFailureBatch::new(
+                    non_gap_input(
+                        9,
+                        b"failure-9",
+                        "non-gap-message-9",
+                        "non-gap-cause-9",
+                        ProjectionGeneration::initial(),
+                    ),
+                    change_epoch(),
+                    "non-gap-failure-9",
+                    "decode_error",
+                    b"bad non-gap payload".to_vec(),
+                )
+                .unwrap(),
+            )
+            .await
+            .unwrap();
+        let generation = repository
+            .repair_projection(&topology(), &partition(), "non-gap-failure-9")
+            .await
+            .unwrap();
+
+        assert_eq!(
+            repository
+                .commit_projection(batch(
+                    non_gap_input(
+                        5,
+                        b"checkpoint-5",
+                        "non-gap-message-5",
+                        "non-gap-cause-5",
+                        generation,
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await
+                .unwrap()
+                .outcome,
+            ProjectionCommitOutcome::Duplicate
+        );
+        assert!(matches!(
+            repository
+                .commit_projection(batch(
+                    non_gap_input(
+                        10,
+                        b"later-10",
+                        "non-gap-message-10",
+                        "non-gap-cause-10",
+                        generation,
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::IncomparableInput)
+        ));
+        assert_eq!(
+            repository
+                .commit_projection(batch(
+                    non_gap_input(
+                        9,
+                        b"failure-9",
+                        "non-gap-message-9",
+                        "non-gap-cause-9",
+                        generation,
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await
+                .unwrap()
+                .outcome,
+            ProjectionCommitOutcome::Applied
+        );
+        assert_eq!(
+            repository
+                .commit_projection(batch(
+                    non_gap_input(
+                        10,
+                        b"later-10",
+                        "non-gap-message-10",
+                        "non-gap-cause-10",
+                        generation,
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await
+                .unwrap()
+                .outcome,
+            ProjectionCommitOutcome::Applied
+        );
+    }
+
+    #[tokio::test]
+    async fn sqlite_record_metadata_is_fenced_against_physical_row_drift() {
+        let missing_physical = repository().await;
+        let created = missing_physical
+            .commit_projection(batch(
+                input(
+                    1,
+                    b"create-for-drift",
+                    "drift-message-1",
+                    "drift-cause-1",
+                    ProjectionGeneration::initial(),
+                ),
+                vec![mutation(
+                    ProjectionRecordExpectation::Missing,
+                    ProjectionMutationKind::Upsert,
+                )],
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        sqlx::query("DELETE FROM sql_todo_views WHERE id = ?")
+            .bind("todo-1")
+            .execute(missing_physical.pool())
+            .await
+            .unwrap();
+        assert!(matches!(
+            missing_physical
+                .commit_projection(batch(
+                    input(
+                        2,
+                        b"update-after-drift",
+                        "drift-message-2",
+                        "drift-cause-2",
+                        ProjectionGeneration::initial(),
+                    ),
+                    vec![mutation(
+                        ProjectionRecordExpectation::Exact(created.records[0].revision.clone()),
+                        ProjectionMutationKind::Upsert,
+                    )],
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::RecordMissing { .. })
+        ));
+        let direct_missing = SameTransactionProjectionBatch::single_upsert(
+            topology(),
+            partition(),
+            change_epoch(),
+            ownership(),
+            record_scope(),
+            upsert_table_mutation("todo-1"),
+            "direct-missing-physical",
+        )
+        .unwrap();
+        let mut tx = missing_physical.pool().begin().await.unwrap();
+        assert!(matches!(
+            apply_same_transaction_projection_in_tx(
+                &mut tx,
+                &direct_missing,
+                missing_physical.projection_change_retention(),
+            )
+            .await,
+            Err(ProjectionProtocolError::RecordMissing { .. })
+        ));
+        drop(tx);
+
+        let untracked_physical = repository().await;
+        sqlx::query("INSERT INTO sql_todo_views (id, _sourced_version) VALUES (?, ?)")
+            .bind("todo-1")
+            .bind(1_i64)
+            .execute(untracked_physical.pool())
+            .await
+            .unwrap();
+        assert!(matches!(
+            untracked_physical
+                .commit_projection(batch(
+                    input(
+                        1,
+                        b"claim-untracked",
+                        "untracked-message-1",
+                        "untracked-cause-1",
+                        ProjectionGeneration::initial(),
+                    ),
+                    vec![mutation(
+                        ProjectionRecordExpectation::Missing,
+                        ProjectionMutationKind::Upsert,
+                    )],
+                    Vec::new(),
+                ))
+                .await,
+            Err(ProjectionProtocolError::RecordAlreadyExists { .. })
+        ));
+        let direct_untracked = SameTransactionProjectionBatch::single_upsert(
+            topology(),
+            partition(),
+            change_epoch(),
+            ownership(),
+            record_scope(),
+            upsert_table_mutation("todo-1"),
+            "direct-untracked-physical",
+        )
+        .unwrap();
+        let mut tx = untracked_physical.pool().begin().await.unwrap();
+        assert!(matches!(
+            apply_same_transaction_projection_in_tx(
+                &mut tx,
+                &direct_untracked,
+                untracked_physical.projection_change_retention(),
+            )
+            .await,
+            Err(ProjectionProtocolError::RecordAlreadyExists { .. })
+        ));
+    }
+
+    #[tokio::test]
+    async fn sqlite_retention_prunes_exact_prefix_and_never_restores_it() {
+        let repository = repository_with_retention(2).await;
+        let mut cursors = Vec::new();
+        for position in 1..=3 {
+            let result = repository
+                .commit_projection(batch(
+                    input(
+                        position,
+                        format!("retained-{position}").as_bytes(),
+                        &format!("retained-message-{position}"),
+                        &format!("retained-cause-{position}"),
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await
+                .unwrap();
+            cursors.push(result.changes[0].cursor.clone());
+        }
+        let failure = repository
+            .record_projection_failure(
+                ProjectionFailureBatch::new(
+                    input(
+                        4,
+                        b"retained-failure-4",
+                        "retained-message-4",
+                        "retained-cause-4",
+                        ProjectionGeneration::initial(),
+                    ),
+                    change_epoch(),
+                    "retained-failure-4",
+                    "decode_error",
+                    b"retention failure".to_vec(),
+                )
+                .unwrap(),
+            )
+            .await
+            .unwrap();
+        let retained: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM projection_changes")
+            .fetch_one(repository.pool())
+            .await
+            .unwrap();
+        assert_eq!(retained, 2);
+        assert!(matches!(
+            repository
+                .projection_changes(&topology(), &partition(), Some(&cursors[0]), 100)
+                .await
+                .unwrap(),
+            ProjectionChangeRead::ResetRequired {
+                compacted_through: 2,
+                ..
+            }
+        ));
+        assert!(matches!(
+            repository
+                .projection_changes(&topology(), &partition(), Some(&cursors[1]), 100)
+                .await
+                .unwrap(),
+            ProjectionChangeRead::Changes {
+                compacted_through: 2,
+                ref changes,
+                ..
+            } if changes.len() == 2
+                && changes[0].cursor.position() == 3
+                && changes[1].cursor == failure.change
+        ));
+
+        let repository = repository
+            .with_projection_change_retention(ProjectionChangeRetention::new(10).unwrap());
+        let generation = repository
+            .repair_projection(&topology(), &partition(), "retained-failure-4")
+            .await
+            .unwrap();
+        repository
+            .commit_projection(batch(
+                input(
+                    4,
+                    b"retained-failure-4",
+                    "retained-message-4",
+                    "retained-cause-4",
+                    generation,
+                ),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        repository
+            .commit_projection(batch(
+                input(
+                    5,
+                    b"retained-5",
+                    "retained-message-5",
+                    "retained-cause-5",
+                    generation,
+                ),
+                Vec::new(),
+                Vec::new(),
+            ))
+            .await
+            .unwrap();
+        let retained: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM projection_changes")
+            .fetch_one(repository.pool())
+            .await
+            .unwrap();
+        assert_eq!(retained, 4);
+        assert!(matches!(
+            repository
+                .projection_changes(&topology(), &partition(), None, 100)
+                .await
+                .unwrap(),
+            ProjectionChangeRead::ResetRequired {
+                compacted_through: 2,
+                ..
+            }
+        ));
+    }
+
+    #[tokio::test]
+    async fn sqlite_projection_change_executor_read_uses_existing_snapshot() {
+        let repository = repository().await;
+        let mut cursors = Vec::new();
+        for position in 1..=3 {
+            let result = repository
+                .commit_projection(batch(
+                    input(
+                        position,
+                        format!("executor-read-{position}").as_bytes(),
+                        &format!("executor-read-message-{position}"),
+                        &format!("executor-read-cause-{position}"),
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await
+                .unwrap();
+            cursors.push(result.changes[0].cursor.clone());
+        }
+
+        let read_topology = topology();
+        let read_partition = partition();
+        let resume_after = cursors[0].clone();
+        let read = with_projection_read_snapshot(repository.pool(), move |connection| {
+            Box::pin(async move {
+                read_projection_changes_in_executor::<sqlx::Sqlite>(
+                    connection,
+                    &read_topology,
+                    &read_partition,
+                    Some(&resume_after),
+                    100,
+                )
+                .await
+            })
+        })
+        .await
+        .unwrap();
+
+        match read {
+            ProjectionChangeRead::Changes {
+                head,
+                compacted_through,
+                changes,
+            } => {
+                assert_eq!(head.as_ref().map(ProjectionChangeCursor::position), Some(3));
+                assert_eq!(compacted_through, 0);
+                assert_eq!(
+                    changes
+                        .iter()
+                        .map(|change| change.cursor.position())
+                        .collect::<Vec<_>>(),
+                    vec![2, 3]
+                );
+            }
+            other => panic!("executor read must return the retained suffix: {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn sqlite_resume_and_concurrent_compaction_share_one_snapshot() {
+        let (repository, database_path) = wal_repository_with_retention(16).await;
+        let mut cursors = Vec::new();
+        for position in 1..=3 {
+            let result = repository
+                .commit_projection(batch(
+                    input(
+                        position,
+                        format!("resume-{position}").as_bytes(),
+                        &format!("resume-message-{position}"),
+                        &format!("resume-cause-{position}"),
+                        ProjectionGeneration::initial(),
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                ))
+                .await
+                .unwrap();
+            cursors.push(result.changes[0].cursor.clone());
+        }
+
+        let reader_pool = repository.pool().clone();
+        let resume_after = cursors[0].clone();
+        let compact_through = cursors[1].clone();
+        let (state_observed_tx, state_observed_rx) = tokio::sync::oneshot::channel();
+        let (compaction_committed_tx, compaction_committed_rx) = tokio::sync::oneshot::channel();
+        let reader = tokio::spawn(async move {
+            read_projection_changes_in_snapshot(
+                &reader_pool,
+                topology(),
+                partition(),
+                Some(resume_after),
+                100,
+                async move {
+                    state_observed_tx
+                        .send(())
+                        .expect("resume reader reports its established state snapshot");
+                    compaction_committed_rx
+                        .await
+                        .expect("compaction completion is reported to resume reader");
+                },
+            )
+            .await
+        });
+
+        state_observed_rx
+            .await
+            .expect("resume reader establishes its snapshot");
+        assert_eq!(
+            tokio::time::timeout(
+                Duration::from_secs(5),
+                repository.compact_projection_changes(&compact_through),
+            )
+            .await
+            .expect("WAL compaction commits while the reader snapshot remains open")
+            .unwrap(),
+            2
+        );
+        compaction_committed_tx
+            .send(())
+            .expect("resume reader remains active after concurrent compaction");
+
+        match reader.await.unwrap().unwrap() {
+            ProjectionChangeRead::Changes {
+                head,
+                compacted_through,
+                changes,
+            } => {
+                assert_eq!(head.as_ref().map(ProjectionChangeCursor::position), Some(3));
+                assert_eq!(compacted_through, 0);
+                assert_eq!(
+                    changes
+                        .iter()
+                        .map(|change| change.cursor.position())
+                        .collect::<Vec<_>>(),
+                    vec![2, 3],
+                    "the established snapshot returns the complete pre-compaction suffix"
+                );
+            }
+            other => panic!("established resume snapshot must return its complete page: {other:?}"),
+        }
+
+        assert!(matches!(
+            repository
+                .projection_changes(&topology(), &partition(), Some(&cursors[0]), 100)
+                .await
+                .unwrap(),
+            ProjectionChangeRead::ResetRequired {
+                compacted_through: 2,
+                ..
+            }
+        ));
+        assert!(matches!(
+            repository
+                .projection_changes(&topology(), &partition(), Some(&cursors[1]), 100)
+                .await
+                .unwrap(),
+            ProjectionChangeRead::Changes {
+                compacted_through: 2,
+                ref changes,
+                ..
+            } if changes.len() == 1 && changes[0].cursor.position() == 3
+        ));
+
+        remove_wal_database(repository, &database_path).await;
+    }
+
+    #[tokio::test]
+    async fn sqlite_same_transaction_projection_allocates_adapter_evidence() {
+        let repository = repository_with_retention(1).await;
+        let direct = |causation_id: &str| {
+            SameTransactionProjectionBatch::single_upsert(
+                topology(),
+                partition(),
+                change_epoch(),
+                ownership(),
+                record_scope(),
+                upsert_table_mutation("todo-1"),
+                causation_id,
+            )
+            .unwrap()
+        };
+
+        let mut tx = repository.pool().begin().await.unwrap();
+        let created = apply_same_transaction_projection_in_tx(
+            &mut tx,
+            &direct("direct-cause-1"),
+            repository.projection_change_retention(),
+        )
+        .await
+        .unwrap();
+        tx.commit().await.unwrap();
+        assert_eq!(created.records[0].revision.incarnation(), 1);
+        assert_eq!(created.records[0].revision.revision(), 1);
+        assert_eq!(created.changes[0].kind, ProjectionChangeKind::RecordUpsert);
+        assert_eq!(
+            created.observations[0].revision,
+            Some(created.records[0].revision.clone())
+        );
+        assert!(row_exists(&repository).await);
+
+        let mut tx = repository.pool().begin().await.unwrap();
+        let updated = apply_same_transaction_projection_in_tx(
+            &mut tx,
+            &direct("direct-cause-2"),
+            repository.projection_change_retention(),
+        )
+        .await
+        .unwrap();
+        tx.commit().await.unwrap();
+        assert_eq!(updated.records[0].revision.incarnation(), 1);
+        assert_eq!(updated.records[0].revision.revision(), 2);
+        assert_eq!(
+            updated.changes[0].cursor.position(),
+            created.changes[0].cursor.position() + 1
+        );
+        assert_eq!(
+            repository
+                .projection_observation(
+                    "direct-cause-2",
+                    &record_scope(),
+                    ProjectionObservationKind::Record,
+                )
+                .await
+                .unwrap()
+                .unwrap(),
+            updated.observations[0]
+        );
+        let retained: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM projection_changes")
+            .fetch_one(repository.pool())
+            .await
+            .unwrap();
+        assert_eq!(retained, 1);
+        assert!(matches!(
+            repository
+                .projection_changes(&topology(), &partition(), None, 100)
+                .await
+                .unwrap(),
+            ProjectionChangeRead::ResetRequired {
+                compacted_through: 1,
+                ..
+            }
+        ));
+    }
+
+    #[tokio::test]
+    async fn sqlite_direct_projection_and_ledger_replay_commit_atomically() {
+        let repository = repository().await;
+        let command_id = uuid::Uuid::now_v7().hyphenated().to_string();
+        let key = CommandLedgerKey::new(
+            "projection-runtime-test",
+            PrincipalPartitionId::new("tenant:direct").unwrap(),
+            CommandId::parse(command_id).unwrap(),
+        )
+        .unwrap();
+        let retention = Duration::from_secs(3600);
+        let reservation = CommandReservation::new(
+            key.clone(),
+            "project-todo",
+            CommandContractFingerprint::new([51; 32]),
+            CanonicalInputHash::new([52; 32]),
+            Duration::from_secs(30),
+            retention,
+        )
+        .unwrap();
+        let attempt = match repository.reserve_command(reservation).await.unwrap() {
+            ReservationOutcome::Acquired(attempt) => attempt,
+            _ => panic!("fresh command reservation must acquire its first attempt"),
+        };
+        let causation_id = attempt.causation_id().as_str().to_string();
+        let completion = attempt
+            .complete(
+                TerminalCommandState::Projected,
+                serde_json::json!({"projected": true}),
+                retention,
+            )
+            .unwrap();
+        let direct = SameTransactionProjectionBatch::single_upsert(
+            topology(),
+            partition(),
+            change_epoch(),
+            ownership(),
+            record_scope(),
+            upsert_table_mutation("todo-1"),
+            causation_id.as_str(),
+        )
+        .unwrap();
+
+        repository
+            .commit_causal_batch(CausalCommitBatch::with_direct_projection(
+                CommitBatch::empty(),
+                completion,
+                direct,
+            ))
+            .await
+            .unwrap();
+
+        let metadata = repository
+            .projection_record(&record_scope())
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(metadata.revision.revision(), 1);
+        assert!(row_exists(&repository).await);
+        match repository
+            .lookup_command(&key, CommandLookupScope::CommandName("project-todo"))
+            .await
+            .unwrap()
+        {
+            CommandLookup::Replay(replay) => {
+                assert_eq!(replay.outcome, serde_json::json!({"projected": true}));
+                assert!(replay.direct_projection.is_some());
+            }
+            _ => panic!("completed direct projection must replay its exact evidence"),
+        }
+
+        let failed_key = CommandLedgerKey::new(
+            "projection-runtime-test",
+            PrincipalPartitionId::new("tenant:direct").unwrap(),
+            CommandId::parse(uuid::Uuid::now_v7().hyphenated().to_string()).unwrap(),
+        )
+        .unwrap();
+        let failed_reservation = CommandReservation::new(
+            failed_key.clone(),
+            "project-todo",
+            CommandContractFingerprint::new([61; 32]),
+            CanonicalInputHash::new([62; 32]),
+            Duration::from_secs(30),
+            retention,
+        )
+        .unwrap();
+        let failed_attempt = match repository
+            .reserve_command(failed_reservation)
+            .await
+            .unwrap()
+        {
+            ReservationOutcome::Acquired(attempt) => attempt,
+            _ => panic!("fresh rollback reservation must acquire its first attempt"),
+        };
+        let failed_causation = failed_attempt.causation_id().as_str().to_string();
+        let failed_completion = failed_attempt
+            .complete(
+                TerminalCommandState::Projected,
+                serde_json::json!({"projected": "must-roll-back"}),
+                retention,
+            )
+            .unwrap();
+        let failed_direct = SameTransactionProjectionBatch::single_upsert(
+            topology(),
+            partition(),
+            change_epoch(),
+            ownership(),
+            record_scope(),
+            upsert_table_mutation("todo-1"),
+            failed_causation,
+        )
+        .unwrap();
+        sqlx::query(
+            "CREATE TRIGGER fail_direct_ledger_completion \
+             BEFORE UPDATE OF state ON command_ledger \
+             WHEN NEW.state = 'projected' \
+             BEGIN SELECT RAISE(ABORT, 'forced direct ledger failure'); END",
+        )
+        .execute(repository.pool())
+        .await
+        .unwrap();
+        assert!(repository
+            .commit_causal_batch(CausalCommitBatch::with_direct_projection(
+                CommitBatch::empty(),
+                failed_completion,
+                failed_direct,
+            ))
+            .await
+            .is_err());
+        assert_eq!(
+            repository
+                .projection_record(&record_scope())
+                .await
+                .unwrap()
+                .unwrap()
+                .revision
+                .revision(),
+            1
+        );
+        assert!(matches!(
+            repository
+                .lookup_command(&failed_key, CommandLookupScope::CommandName("project-todo"),)
+                .await
+                .unwrap(),
+            CommandLookup::InProgress { .. }
+        ));
+        sqlx::query("DROP TRIGGER fail_direct_ledger_completion")
+            .execute(repository.pool())
+            .await
+            .unwrap();
+
+        let fenced_key = CommandLedgerKey::new(
+            "projection-runtime-test",
+            PrincipalPartitionId::new("tenant:direct").unwrap(),
+            CommandId::parse(uuid::Uuid::now_v7().hyphenated().to_string()).unwrap(),
+        )
+        .unwrap();
+        let fenced_reservation = CommandReservation::new(
+            fenced_key,
+            "project-todo",
+            CommandContractFingerprint::new([71; 32]),
+            CanonicalInputHash::new([72; 32]),
+            Duration::from_secs(30),
+            retention,
+        )
+        .unwrap();
+        let fenced_attempt = match repository
+            .reserve_command(fenced_reservation)
+            .await
+            .unwrap()
+        {
+            ReservationOutcome::Acquired(attempt) => attempt,
+            _ => panic!("fresh fenced reservation must acquire its first attempt"),
+        };
+        let fenced_causation = fenced_attempt.causation_id().as_str().to_string();
+        let fenced_completion = fenced_attempt
+            .complete(
+                TerminalCommandState::Projected,
+                serde_json::json!({"projected": "must-not-run"}),
+                retention,
+            )
+            .unwrap();
+        repository
+            .mark_retryable_unknown(fenced_completion.attempt_fence())
+            .await
+            .unwrap();
+        let fenced_direct = SameTransactionProjectionBatch::single_upsert(
+            topology(),
+            partition(),
+            change_epoch(),
+            ownership(),
+            record_scope(),
+            upsert_table_mutation("todo-1"),
+            fenced_causation,
+        )
+        .unwrap();
+        sqlx::query(
+            "CREATE TRIGGER fail_if_fenced_projection_runs \
+             BEFORE UPDATE ON sql_todo_views \
+             BEGIN SELECT RAISE(ABORT, 'fenced direct projection executed'); END",
+        )
+        .execute(repository.pool())
+        .await
+        .unwrap();
+        assert!(matches!(
+            repository
+                .commit_causal_batch(CausalCommitBatch::with_direct_projection(
+                    CommitBatch::empty(),
+                    fenced_completion,
+                    fenced_direct,
+                ))
+                .await,
+            Err(CommandLedgerError::AttemptFenced { .. })
+        ));
+        assert_eq!(
+            repository
+                .projection_record(&record_scope())
+                .await
+                .unwrap()
+                .unwrap()
+                .revision
+                .revision(),
+            1
+        );
+        sqlx::query("DROP TRIGGER fail_if_fenced_projection_runs")
+            .execute(repository.pool())
+            .await
+            .unwrap();
+    }
+}
diff --git a/src/sqlx_repo/projection_protocol/types.rs b/src/sqlx_repo/projection_protocol/types.rs
new file mode 100644
index 00000000..27f6e6b0
--- /dev/null
+++ b/src/sqlx_repo/projection_protocol/types.rs
@@ -0,0 +1,69 @@
+use super::*;
+
+#[derive(Clone, Debug)]
+pub(super) struct PartitionState {
+    pub(super) active_generation: ProjectionGeneration,
+    pub(super) change_epoch: ProjectionEpoch,
+    pub(super) change_head: u64,
+    pub(super) compacted_through: u64,
+    pub(super) pending_retry_failure_id: Option<String>,
+    pub(super) stopped_failure_id: Option<String>,
+}
+
+#[derive(Clone, Debug)]
+pub(super) struct StoredCursor {
+    pub(super) source_epoch: ProjectionEpoch,
+    pub(super) source_position: u64,
+    pub(super) input_fingerprint: ProjectionInputFingerprint,
+    pub(super) message_id: String,
+    pub(super) causation_id: String,
+    pub(super) gap_free: bool,
+    pub(super) change: ProjectionChangeCursor,
+}
+
+#[derive(Clone, Debug)]
+pub(super) struct StoredReceipt {
+    pub(super) source_bytes: Vec<u8>,
+    pub(super) source_hash: Vec<u8>,
+    pub(super) source_partition_bytes: Vec<u8>,
+    pub(super) source_partition_hash: Vec<u8>,
+    pub(super) source_epoch: ProjectionEpoch,
+    pub(super) source_position: u64,
+    pub(super) input_fingerprint: ProjectionInputFingerprint,
+    pub(super) message_id: String,
+    pub(super) causation_id: String,
+    pub(super) gap_free: bool,
+    pub(super) outcome_kind: String,
+    pub(super) change: ProjectionChangeCursor,
+}
+
+#[derive(Clone, Debug)]
+pub(super) struct StoredInputIdentity {
+    pub(super) partition_bytes: Vec<u8>,
+    pub(super) partition_hash: Vec<u8>,
+    pub(super) source_bytes: Vec<u8>,
+    pub(super) source_hash: Vec<u8>,
+    pub(super) source_partition_bytes: Vec<u8>,
+    pub(super) source_partition_hash: Vec<u8>,
+    pub(super) source_epoch: ProjectionEpoch,
+    pub(super) source_position: u64,
+    pub(super) input_fingerprint: ProjectionInputFingerprint,
+    pub(super) message_id: String,
+    pub(super) causation_id: String,
+    pub(super) gap_free: bool,
+}
+
+#[derive(Clone, Debug)]
+pub(super) struct StoredRecord {
+    pub(super) metadata: ProjectionRecordMetadata,
+}
+
+pub(super) struct StoredFailure {
+    pub(super) failure: ProjectionFailure,
+}
+
+pub(super) enum InputDisposition {
+    New,
+    Duplicate(ProjectionCheckpoint),
+    Stale(ProjectionCheckpoint),
+}
diff --git a/src/sqlx_repo/projection_protocol/writes.rs b/src/sqlx_repo/projection_protocol/writes.rs
new file mode 100644
index 00000000..89eaf0be
--- /dev/null
+++ b/src/sqlx_repo/projection_protocol/writes.rs
@@ -0,0 +1,1561 @@
+use super::*;
+
+pub(super) async fn ensure_partition_ownership_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+    ownership: &[ProjectionModelOwnership],
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = topology.digest();
+    let partition_hash = partition.digest();
+    for declaration in ownership {
+        let mut registered = QueryBuilder::<DB>::new(
+            "SELECT topology_bytes, table_name FROM projection_registered_models \
+             WHERE topology_hash = ",
+        );
+        registered.push_bind(topology_hash.as_slice());
+        registered.push(" AND model_name = ");
+        registered.push_bind(declaration.model.as_str());
+        let Some(row) = registered
+            .build()
+            .fetch_optional(&mut **tx)
+            .await
+            .map_err(|error| {
+                protocol_storage_error::<DB>("verify causal projection registration", error)
+            })?
+        else {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection model `{}` was not registered before projector traffic",
+                declaration.model
+            )));
+        };
+        let registered_topology: Vec<u8> = row.try_get("topology_bytes").map_err(|error| {
+            protocol_storage_error::<DB>("decode causal projection registration", error)
+        })?;
+        verify_bytes(
+            &registered_topology,
+            &topology.canonical_bytes(),
+            "registered projector topology",
+        )?;
+        let registered_table: String = row.try_get("table_name").map_err(|error| {
+            protocol_storage_error::<DB>("decode causal projection registration", error)
+        })?;
+        if registered_table != declaration.table {
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection model `{}` was registered for table `{registered_table}`, not `{}`",
+                declaration.model, declaration.table
+            )));
+        }
+
+        let mut by_model = QueryBuilder::<DB>::new(
+            "SELECT table_name FROM projection_model_ownership WHERE topology_hash = ",
+        );
+        by_model.push_bind(topology_hash.as_slice());
+        by_model.push(" AND partition_hash = ");
+        by_model.push_bind(partition_hash.as_slice());
+        by_model.push(" AND model_name = ");
+        by_model.push_bind(declaration.model.as_str());
+        if let Some(row) = by_model
+            .build()
+            .fetch_optional(&mut **tx)
+            .await
+            .map_err(|error| {
+                protocol_storage_error::<DB>("load projection model ownership", error)
+            })?
+        {
+            let table: String = row.try_get("table_name").map_err(|error| {
+                protocol_storage_error::<DB>("decode projection model ownership", error)
+            })?;
+            if table != declaration.table {
+                return Err(ProjectionProtocolError::InvalidBatch(format!(
+                    "projection model `{}` is already bound to table `{table}`",
+                    declaration.model
+                )));
+            }
+            continue;
+        }
+
+        let mut by_table = QueryBuilder::<DB>::new(
+            "SELECT model_name FROM projection_model_ownership WHERE topology_hash = ",
+        );
+        by_table.push_bind(topology_hash.as_slice());
+        by_table.push(" AND partition_hash = ");
+        by_table.push_bind(partition_hash.as_slice());
+        by_table.push(" AND table_name = ");
+        by_table.push_bind(declaration.table.as_str());
+        if let Some(row) = by_table
+            .build()
+            .fetch_optional(&mut **tx)
+            .await
+            .map_err(|error| {
+                protocol_storage_error::<DB>("load projection table ownership", error)
+            })?
+        {
+            let model: String = row.try_get("model_name").map_err(|error| {
+                protocol_storage_error::<DB>("decode projection table ownership", error)
+            })?;
+            return Err(ProjectionProtocolError::InvalidBatch(format!(
+                "projection table `{}` is already bound to model `{model}`",
+                declaration.table
+            )));
+        }
+
+        let mut insert = QueryBuilder::<DB>::new(
+            "INSERT INTO projection_model_ownership \
+             (topology_hash, partition_hash, model_name, table_name) VALUES (",
+        );
+        insert.push_bind(topology_hash.as_slice());
+        insert.push(", ");
+        insert.push_bind(partition_hash.as_slice());
+        insert.push(", ");
+        insert.push_bind(declaration.model.as_str());
+        insert.push(", ");
+        insert.push_bind(declaration.table.as_str());
+        insert.push(") ON CONFLICT (topology_hash, partition_hash, model_name) DO NOTHING");
+        let result = insert.build().execute(&mut **tx).await.map_err(|error| {
+            protocol_storage_error::<DB>("insert projection model ownership", error)
+        })?;
+        if DB::rows_affected(&result) != 1 {
+            return Err(corrupt_storage(
+                "projection ownership changed while its partition lock was held",
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(super) async fn verify_registered_topology_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    topology: &ProjectorTopologyId,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = topology.digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT topology_bytes FROM projection_registered_models WHERE topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" LIMIT 1");
+    let Some(row) = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| {
+            protocol_storage_error::<DB>("verify registered projector topology", error)
+        })?
+    else {
+        return Err(ProjectionProtocolError::InvalidBatch(format!(
+            "projector topology `{}` has no registered model set",
+            topology.name()
+        )));
+    };
+    let topology_bytes: Vec<u8> = row.try_get("topology_bytes").map_err(|error| {
+        protocol_storage_error::<DB>("decode registered projector topology", error)
+    })?;
+    verify_bytes(
+        &topology_bytes,
+        &topology.canonical_bytes(),
+        "registered projector topology",
+    )
+}
+
+pub(super) async fn record_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    scope: &ProjectionRecordScope,
+    expected_change_epoch: &ProjectionEpoch,
+) -> Result<Option<StoredRecord>, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = scope.topology().digest();
+    let partition_hash = scope.projection_partition().digest();
+    let key_hash = scope.key_digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT canonical_key_bytes, canonical_key_hash, incarnation, revision, tombstone, \
+         change_epoch, change_position FROM projection_records WHERE topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(" AND model_name = ");
+    builder.push_bind(scope.model());
+    builder.push(" AND canonical_key_hash = ");
+    builder.push_bind(key_hash.as_slice());
+    let Some(row) = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("load projection record", error))?
+    else {
+        return Ok(None);
+    };
+    let key_bytes: Vec<u8> = row.try_get("canonical_key_bytes").map_err(|error| {
+        protocol_storage_error::<DB>("decode projection record key bytes", error)
+    })?;
+    let stored_key_hash: Vec<u8> = row.try_get("canonical_key_hash").map_err(|error| {
+        protocol_storage_error::<DB>("decode projection record key hash", error)
+    })?;
+    verify_bytes(
+        &key_bytes,
+        scope.canonical_key_bytes(),
+        "projection record key",
+    )?;
+    verify_digest(
+        &stored_key_hash,
+        scope.key_digest(),
+        "projection record key",
+    )?;
+    let incarnation = from_i64::<DB>(
+        row.try_get("incarnation")
+            .map_err(|error| protocol_storage_error::<DB>("decode record incarnation", error))?,
+        "record incarnation",
+    )?;
+    let revision = from_i64::<DB>(
+        row.try_get("revision")
+            .map_err(|error| protocol_storage_error::<DB>("decode record revision", error))?,
+        "record revision",
+    )?;
+    let tombstone_value: i64 = row
+        .try_get("tombstone")
+        .map_err(|error| protocol_storage_error::<DB>("decode record tombstone", error))?;
+    let tombstone = match tombstone_value {
+        0 => false,
+        1 => true,
+        value => {
+            return Err(corrupt_storage(format!(
+                "record tombstone contains invalid value {value}"
+            )))
+        }
+    };
+    let change_epoch: String = row
+        .try_get("change_epoch")
+        .map_err(|error| protocol_storage_error::<DB>("decode record change epoch", error))?;
+    let change_epoch = ProjectionEpoch::new(change_epoch)?;
+    if &change_epoch != expected_change_epoch {
+        return Err(corrupt_storage(
+            "projection record change epoch differs from its partition",
+        ));
+    }
+    let change_position = from_i64::<DB>(
+        row.try_get("change_position").map_err(|error| {
+            protocol_storage_error::<DB>("decode record change position", error)
+        })?,
+        "record change position",
+    )?;
+    Ok(Some(StoredRecord {
+        metadata: ProjectionRecordMetadata {
+            revision: RecordRevision::new(scope.clone(), incarnation, revision)?,
+            tombstone,
+            change: ProjectionChangeCursor::new(
+                scope.topology().clone(),
+                scope.projection_partition().clone(),
+                change_epoch,
+                change_position,
+            )?,
+        },
+    }))
+}
+
+pub(super) fn next_record(
+    scope: &ProjectionRecordScope,
+    expectation: &ProjectionRecordExpectation,
+    kind: ProjectionMutationKind,
+    current: Option<&StoredRecord>,
+) -> Result<(RecordRevision, bool), ProjectionProtocolError> {
+    let current = current.map(|record| &record.metadata);
+    match (expectation, current, kind) {
+        (ProjectionRecordExpectation::Missing, None, ProjectionMutationKind::Upsert) => {
+            Ok((RecordRevision::new(scope.clone(), 1, 1)?, false))
+        }
+        (ProjectionRecordExpectation::Missing, Some(metadata), _) if metadata.tombstone => {
+            Err(ProjectionProtocolError::RecordTombstoned {
+                model: scope.model().to_string(),
+            })
+        }
+        (ProjectionRecordExpectation::Missing, Some(_), _) => {
+            Err(ProjectionProtocolError::RecordAlreadyExists {
+                model: scope.model().to_string(),
+            })
+        }
+        (ProjectionRecordExpectation::Exact(_), None, _) => {
+            Err(ProjectionProtocolError::RecordMissing {
+                model: scope.model().to_string(),
+            })
+        }
+        (ProjectionRecordExpectation::Exact(expected), Some(metadata), _) => {
+            if expected != &metadata.revision {
+                return Err(ProjectionProtocolError::RecordRevisionConflict {
+                    model: scope.model().to_string(),
+                    expected_incarnation: expected.incarnation(),
+                    expected_revision: expected.revision(),
+                    actual_incarnation: metadata.revision.incarnation(),
+                    actual_revision: metadata.revision.revision(),
+                });
+            }
+            match kind {
+                ProjectionMutationKind::Upsert if metadata.tombstone => {
+                    Err(ProjectionProtocolError::RecordTombstoned {
+                        model: scope.model().to_string(),
+                    })
+                }
+                ProjectionMutationKind::Upsert => Ok((
+                    RecordRevision::new(
+                        scope.clone(),
+                        metadata.revision.incarnation(),
+                        checked_next(metadata.revision.revision(), "record revision")?,
+                    )?,
+                    false,
+                )),
+                ProjectionMutationKind::Delete if metadata.tombstone => {
+                    Err(ProjectionProtocolError::RecordTombstoned {
+                        model: scope.model().to_string(),
+                    })
+                }
+                ProjectionMutationKind::Delete => Ok((
+                    RecordRevision::new(
+                        scope.clone(),
+                        metadata.revision.incarnation(),
+                        checked_next(metadata.revision.revision(), "record revision")?,
+                    )?,
+                    true,
+                )),
+                ProjectionMutationKind::Recreate if !metadata.tombstone => {
+                    Err(ProjectionProtocolError::RecreateRequiresTombstone {
+                        model: scope.model().to_string(),
+                    })
+                }
+                ProjectionMutationKind::Recreate => Ok((
+                    RecordRevision::new(
+                        scope.clone(),
+                        checked_next(metadata.revision.incarnation(), "record incarnation")?,
+                        1,
+                    )?,
+                    false,
+                )),
+            }
+        }
+        (_, _, ProjectionMutationKind::Delete | ProjectionMutationKind::Recreate) => {
+            Err(ProjectionProtocolError::InvalidBatch(
+                "delete/recreate requires an exact record expectation".into(),
+            ))
+        }
+    }
+}
+
+pub(super) fn allocate_change(
+    state: &mut PartitionState,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+    kind: ProjectionChangeKind,
+    causation_id: String,
+    observation_kind: Option<ProjectionObservationKind>,
+    scope: Option<ProjectionRecordScope>,
+    revision: Option<RecordRevision>,
+    failure_id: Option<String>,
+) -> Result<ProjectionChange, ProjectionProtocolError> {
+    state.change_head = checked_next(state.change_head, "projection change")?;
+    Ok(ProjectionChange {
+        cursor: ProjectionChangeCursor::new(
+            topology.clone(),
+            partition.clone(),
+            state.change_epoch.clone(),
+            state.change_head,
+        )?,
+        kind,
+        causation_id,
+        observation_kind,
+        scope,
+        revision,
+        failure_id,
+    })
+}
+
+pub(super) async fn insert_change_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    change: &ProjectionChange,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    let cursor = &change.cursor;
+    let position = to_i64::<DB>(cursor.position(), "projection change position")?;
+    let topology_hash = cursor.topology().digest();
+    let partition_hash = cursor.projection_partition().digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "INSERT INTO projection_changes \
+         (topology_hash, partition_hash, change_epoch, change_position, change_kind, \
+         causation_id, model_name, scope_kind, canonical_key_bytes, canonical_key_hash, \
+         incarnation, revision, failure_id) VALUES (",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(cursor.epoch().as_str());
+    builder.push(", ");
+    builder.push_bind(position);
+    builder.push(", ");
+    builder.push_bind(change.kind.as_storage_str());
+    builder.push(", ");
+    builder.push_bind(change.causation_id.as_str());
+    builder.push(", ");
+    if let Some(scope) = &change.scope {
+        builder.push_bind(scope.model());
+    } else {
+        builder.push("NULL");
+    }
+    builder.push(", ");
+    if let Some(kind) = change.observation_kind {
+        builder.push_bind(kind.as_storage_str());
+    } else {
+        builder.push("NULL");
+    }
+    builder.push(", ");
+    if let Some(scope) = &change.scope {
+        builder.push_bind(scope.canonical_key_bytes());
+    } else {
+        builder.push("NULL");
+    }
+    builder.push(", ");
+    if let Some(scope) = &change.scope {
+        let key_hash = scope.key_digest();
+        builder.push_bind(key_hash.as_slice());
+    } else {
+        builder.push("NULL");
+    }
+    builder.push(", ");
+    if let Some(revision) = &change.revision {
+        builder.push_bind(to_i64::<DB>(
+            revision.incarnation(),
+            "projection record incarnation",
+        )?);
+    } else {
+        builder.push("NULL");
+    }
+    builder.push(", ");
+    if let Some(revision) = &change.revision {
+        builder.push_bind(to_i64::<DB>(
+            revision.revision(),
+            "projection record revision",
+        )?);
+    } else {
+        builder.push("NULL");
+    }
+    builder.push(", ");
+    if let Some(failure_id) = &change.failure_id {
+        builder.push_bind(failure_id.as_str());
+    } else {
+        builder.push("NULL");
+    }
+    builder.push(")");
+    builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("append projection change", error))?;
+    Ok(())
+}
+
+pub(super) async fn upsert_record_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    metadata: &ProjectionRecordMetadata,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    let scope = metadata.revision.scope();
+    let topology_hash = scope.topology().digest();
+    let partition_hash = scope.projection_partition().digest();
+    let key_hash = scope.key_digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "INSERT INTO projection_records \
+         (topology_hash, partition_hash, model_name, canonical_key_bytes, canonical_key_hash, \
+         incarnation, revision, tombstone, change_epoch, change_position) VALUES (",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(scope.model());
+    builder.push(", ");
+    builder.push_bind(scope.canonical_key_bytes());
+    builder.push(", ");
+    builder.push_bind(key_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        metadata.revision.incarnation(),
+        "projection record incarnation",
+    )?);
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        metadata.revision.revision(),
+        "projection record revision",
+    )?);
+    builder.push(", ");
+    builder.push_bind(i64::from(metadata.tombstone));
+    builder.push(", ");
+    builder.push_bind(metadata.change.epoch().as_str());
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        metadata.change.position(),
+        "projection record change position",
+    )?);
+    builder.push(
+        ") ON CONFLICT (topology_hash, partition_hash, model_name, canonical_key_hash) \
+         DO UPDATE SET canonical_key_bytes = excluded.canonical_key_bytes, \
+         incarnation = excluded.incarnation, revision = excluded.revision, \
+         tombstone = excluded.tombstone, change_epoch = excluded.change_epoch, \
+         change_position = excluded.change_position",
+    );
+    builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("store projection record", error))?;
+    Ok(())
+}
+
+pub(super) fn decode_observation_row<DB>(
+    row: &DB::Row,
+    causation_id: &str,
+    scope: &ProjectionRecordScope,
+    kind: ProjectionObservationKind,
+    expected_change_epoch: &ProjectionEpoch,
+) -> Result<ProjectionObservation, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let key_bytes: Vec<u8> = row
+        .try_get("canonical_key_bytes")
+        .map_err(|error| protocol_storage_error::<DB>("decode observation key bytes", error))?;
+    let stored_key_hash: Vec<u8> = row
+        .try_get("canonical_key_hash")
+        .map_err(|error| protocol_storage_error::<DB>("decode observation key hash", error))?;
+    verify_bytes(
+        &key_bytes,
+        scope.canonical_key_bytes(),
+        "projection observation key",
+    )?;
+    verify_digest(
+        &stored_key_hash,
+        scope.key_digest(),
+        "projection observation key",
+    )?;
+    let incarnation: Option<i64> = row
+        .try_get("incarnation")
+        .map_err(|error| protocol_storage_error::<DB>("decode observation incarnation", error))?;
+    let revision: Option<i64> = row
+        .try_get("revision")
+        .map_err(|error| protocol_storage_error::<DB>("decode observation revision", error))?;
+    let revision = match (kind, incarnation, revision) {
+        (ProjectionObservationKind::Record, Some(incarnation), Some(revision)) => {
+            Some(RecordRevision::new(
+                scope.clone(),
+                from_i64::<DB>(incarnation, "observation record incarnation")?,
+                from_i64::<DB>(revision, "observation record revision")?,
+            )?)
+        }
+        (ProjectionObservationKind::Dependency, None, None) => None,
+        _ => {
+            return Err(corrupt_storage(
+                "projection observation kind/revision shape is inconsistent",
+            ))
+        }
+    };
+    let change_epoch: String = row
+        .try_get("change_epoch")
+        .map_err(|error| protocol_storage_error::<DB>("decode observation change epoch", error))?;
+    let change_epoch = ProjectionEpoch::new(change_epoch)?;
+    if &change_epoch != expected_change_epoch {
+        return Err(corrupt_storage(
+            "projection observation change epoch differs from its partition",
+        ));
+    }
+    let change_position = from_i64::<DB>(
+        row.try_get("change_position").map_err(|error| {
+            protocol_storage_error::<DB>("decode observation change position", error)
+        })?,
+        "observation change position",
+    )?;
+    Ok(ProjectionObservation {
+        causation_id: causation_id.to_string(),
+        kind,
+        revision,
+        scope: scope.clone(),
+        change: ProjectionChangeCursor::new(
+            scope.topology().clone(),
+            scope.projection_partition().clone(),
+            change_epoch,
+            change_position,
+        )?,
+    })
+}
+
+pub(super) async fn observation_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    causation_id: &str,
+    scope: &ProjectionRecordScope,
+    kind: ProjectionObservationKind,
+    expected_change_epoch: &ProjectionEpoch,
+) -> Result<Option<ProjectionObservation>, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = scope.topology().digest();
+    let partition_hash = scope.projection_partition().digest();
+    let key_hash = scope.key_digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT canonical_key_bytes, canonical_key_hash, incarnation, revision, \
+         change_epoch, change_position FROM projection_observations WHERE topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(" AND causation_id = ");
+    builder.push_bind(causation_id);
+    builder.push(" AND model_name = ");
+    builder.push_bind(scope.model());
+    builder.push(" AND scope_kind = ");
+    builder.push_bind(kind.as_storage_str());
+    builder.push(" AND canonical_key_hash = ");
+    builder.push_bind(key_hash.as_slice());
+    let Some(row) = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("load projection observation", error))?
+    else {
+        return Ok(None);
+    };
+    decode_observation_row::<DB>(&row, causation_id, scope, kind, expected_change_epoch).map(Some)
+}
+
+pub(super) async fn insert_observation_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    observation: &ProjectionObservation,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    let scope = &observation.scope;
+    let topology_hash = scope.topology().digest();
+    let partition_hash = scope.projection_partition().digest();
+    let key_hash = scope.key_digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "INSERT INTO projection_observations \
+         (topology_hash, partition_hash, causation_id, model_name, scope_kind, \
+         canonical_key_bytes, canonical_key_hash, incarnation, revision, \
+         change_epoch, change_position) VALUES (",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(observation.causation_id.as_str());
+    builder.push(", ");
+    builder.push_bind(scope.model());
+    builder.push(", ");
+    builder.push_bind(observation.kind.as_storage_str());
+    builder.push(", ");
+    builder.push_bind(scope.canonical_key_bytes());
+    builder.push(", ");
+    builder.push_bind(key_hash.as_slice());
+    builder.push(", ");
+    if let Some(revision) = &observation.revision {
+        builder.push_bind(to_i64::<DB>(
+            revision.incarnation(),
+            "observation record incarnation",
+        )?);
+    } else {
+        builder.push("NULL");
+    }
+    builder.push(", ");
+    if let Some(revision) = &observation.revision {
+        builder.push_bind(to_i64::<DB>(
+            revision.revision(),
+            "observation record revision",
+        )?);
+    } else {
+        builder.push("NULL");
+    }
+    builder.push(", ");
+    builder.push_bind(observation.change.epoch().as_str());
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        observation.change.position(),
+        "observation change position",
+    )?);
+    builder.push(")");
+    builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("insert projection observation", error))?;
+    Ok(())
+}
+
+pub(super) async fn store_input_cursor_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+    change: &ProjectionChangeCursor,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    let cursor = &input.cursor;
+    let topology_hash = cursor.topology().digest();
+    let partition_hash = cursor.projection_partition().digest();
+    let source = cursor.source();
+    let source_bytes = source.canonical_name_bytes();
+    let source_hash = source.digest();
+    let source_partition_hash = source.partition_digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "INSERT INTO projection_input_cursors \
+         (topology_hash, partition_hash, source_bytes, source_hash, source_partition_bytes, \
+         source_partition_hash, source_epoch, source_position, input_hash, message_id, \
+         causation_id, gap_free, generation, change_epoch, change_position) VALUES (",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(source_bytes.as_slice());
+    builder.push(", ");
+    builder.push_bind(source_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(source.canonical_partition_bytes());
+    builder.push(", ");
+    builder.push_bind(source_partition_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(cursor.epoch().as_str());
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        cursor.position(),
+        "projection input position",
+    )?);
+    builder.push(", ");
+    let input_hash = input.fingerprint.digest();
+    builder.push_bind(input_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(input.message_id.as_str());
+    builder.push(", ");
+    builder.push_bind(input.causation_id.as_str());
+    builder.push(", ");
+    builder.push_bind(i64::from(input.gap_free));
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        input.generation.get(),
+        "projection generation",
+    )?);
+    builder.push(", ");
+    builder.push_bind(change.epoch().as_str());
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        change.position(),
+        "projection change position",
+    )?);
+    builder.push(
+        ") ON CONFLICT \
+         (topology_hash, partition_hash, source_hash, source_partition_hash, generation) \
+         DO UPDATE SET source_bytes = excluded.source_bytes, \
+         source_partition_bytes = excluded.source_partition_bytes, source_epoch = excluded.source_epoch, \
+         source_position = excluded.source_position, input_hash = excluded.input_hash, \
+         message_id = excluded.message_id, causation_id = excluded.causation_id, \
+         gap_free = excluded.gap_free, change_epoch = excluded.change_epoch, \
+         change_position = excluded.change_position",
+    );
+    builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("store projection input cursor", error))?;
+    Ok(())
+}
+
+pub(super) async fn insert_input_identity_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let cursor = &input.cursor;
+    let topology_hash = cursor.topology().digest();
+    let partition_hash = cursor.projection_partition().digest();
+    let source = cursor.source();
+    let source_bytes = source.canonical_name_bytes();
+    let source_hash = source.digest();
+    let source_partition_hash = source.partition_digest();
+    let input_hash = input.fingerprint.digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "INSERT INTO projection_input_identities \
+         (topology_hash, partition_hash, source_bytes, source_hash, source_partition_bytes, \
+         source_partition_hash, source_epoch, source_position, input_hash, message_id, \
+         causation_id, gap_free) VALUES (",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(source_bytes.as_slice());
+    builder.push(", ");
+    builder.push_bind(source_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(source.canonical_partition_bytes());
+    builder.push(", ");
+    builder.push_bind(source_partition_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(cursor.epoch().as_str());
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        cursor.position(),
+        "projection input identity position",
+    )?);
+    builder.push(", ");
+    builder.push_bind(input_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(input.message_id.as_str());
+    builder.push(", ");
+    builder.push_bind(input.causation_id.as_str());
+    builder.push(", ");
+    builder.push_bind(i64::from(input.gap_free));
+    builder.push(") ON CONFLICT DO NOTHING");
+    let result =
+        builder.build().execute(&mut **tx).await.map_err(|error| {
+            protocol_storage_error::<DB>("insert projection input identity", error)
+        })?;
+    if DB::rows_affected(&result) == 1 {
+        return Ok(());
+    }
+
+    if let Some(existing) = input_identity_by_cursor_in_tx(tx, input).await? {
+        if input_identity_matches(&existing, input) {
+            return Ok(());
+        }
+        return Err(ProjectionProtocolError::InputCorruption);
+    }
+    if input_identity_by_message_in_tx(tx, input).await?.is_some() {
+        return Err(ProjectionProtocolError::MessageIdReuse {
+            message_id: input.message_id.clone(),
+        });
+    }
+    Err(corrupt_storage(
+        "projection input identity collided without a readable conflicting row",
+    ))
+}
+
+pub(super) async fn insert_input_receipt_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+    outcome_kind: &'static str,
+    failure_id: Option<&str>,
+    change: &ProjectionChangeCursor,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    let cursor = &input.cursor;
+    let topology_hash = cursor.topology().digest();
+    let partition_hash = cursor.projection_partition().digest();
+    let source = cursor.source();
+    let source_bytes = source.canonical_name_bytes();
+    let source_hash = source.digest();
+    let source_partition_hash = source.partition_digest();
+    let input_hash = input.fingerprint.digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "INSERT INTO projection_input_receipts \
+         (topology_hash, partition_hash, generation, message_id, source_bytes, source_hash, \
+         source_partition_bytes, source_partition_hash, source_epoch, source_position, input_hash, \
+         causation_id, gap_free, outcome_kind, failure_id, change_epoch, change_position) VALUES (",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        input.generation.get(),
+        "projection generation",
+    )?);
+    builder.push(", ");
+    builder.push_bind(input.message_id.as_str());
+    builder.push(", ");
+    builder.push_bind(source_bytes.as_slice());
+    builder.push(", ");
+    builder.push_bind(source_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(source.canonical_partition_bytes());
+    builder.push(", ");
+    builder.push_bind(source_partition_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(cursor.epoch().as_str());
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        cursor.position(),
+        "projection input position",
+    )?);
+    builder.push(", ");
+    builder.push_bind(input_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(input.causation_id.as_str());
+    builder.push(", ");
+    builder.push_bind(i64::from(input.gap_free));
+    builder.push(", ");
+    builder.push_bind(outcome_kind);
+    builder.push(", ");
+    if let Some(failure_id) = failure_id {
+        builder.push_bind(failure_id);
+    } else {
+        builder.push("NULL");
+    }
+    builder.push(", ");
+    builder.push_bind(change.epoch().as_str());
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        change.position(),
+        "projection change position",
+    )?);
+    builder.push(") ON CONFLICT DO NOTHING");
+    let result =
+        builder.build().execute(&mut **tx).await.map_err(|error| {
+            protocol_storage_error::<DB>("insert projection input receipt", error)
+        })?;
+    if DB::rows_affected(&result) != 1 {
+        return Err(corrupt_storage(
+            "projection input receipt collided while its partition lock was held",
+        ));
+    }
+    Ok(())
+}
+
+pub(super) async fn ensure_inbox_available_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+{
+    let receipt = input.inbox_receipt();
+    receipt.validate()?;
+    let mut builder = QueryBuilder::<DB>::new("SELECT 1 FROM consumer_inbox WHERE consumer = ");
+    builder.push_bind(receipt.consumer.as_str());
+    builder.push(" AND message_id = ");
+    builder.push_bind(receipt.message_id.as_str());
+    builder.push(" LIMIT 1");
+    if builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("check projection consumer inbox", error))?
+        .is_some()
+    {
+        return Err(ProjectionProtocolError::MessageIdReuse {
+            message_id: input.message_id.clone(),
+        });
+    }
+    Ok(())
+}
+
+pub(super) async fn insert_inbox_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    input: &TrustedProjectionInput,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+{
+    let receipt = input.inbox_receipt();
+    let mut builder =
+        QueryBuilder::<DB>::new("INSERT INTO consumer_inbox (consumer, message_id) VALUES (");
+    builder.push_bind(receipt.consumer.as_str());
+    builder.push(", ");
+    builder.push_bind(receipt.message_id.as_str());
+    builder.push(") ON CONFLICT DO NOTHING");
+    let result =
+        builder.build().execute(&mut **tx).await.map_err(|error| {
+            protocol_storage_error::<DB>("insert projection consumer inbox", error)
+        })?;
+    if DB::rows_affected(&result) != 1 {
+        return Err(corrupt_storage(
+            "projection consumer inbox collided while its partition lock was held",
+        ));
+    }
+    Ok(())
+}
+
+pub(super) async fn update_partition_head_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+    change_head: u64,
+    clear_pending_retry: Option<&str>,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    let topology_hash = topology.digest();
+    let partition_hash = partition.digest();
+    let mut builder = QueryBuilder::<DB>::new("UPDATE projection_partitions SET change_head = ");
+    builder.push_bind(to_i64::<DB>(change_head, "projection change head")?);
+    if clear_pending_retry.is_some() {
+        builder.push(", pending_retry_failure_id = NULL");
+    }
+    builder.push(" WHERE topology_hash = ");
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    if let Some(failure_id) = clear_pending_retry {
+        builder.push(" AND pending_retry_failure_id = ");
+        builder.push_bind(failure_id);
+    }
+    let result =
+        builder.build().execute(&mut **tx).await.map_err(|error| {
+            protocol_storage_error::<DB>("advance projection change head", error)
+        })?;
+    if DB::rows_affected(&result) != 1 {
+        return Err(corrupt_storage(
+            "projection partition or pending retry fence changed while its lock was held",
+        ));
+    }
+    Ok(())
+}
+
+pub(super) async fn retain_projection_change_suffix_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+    state: &PartitionState,
+    retention: ProjectionChangeRetention,
+) -> Result<u64, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    let target = state.compacted_through.max(
+        state
+            .change_head
+            .saturating_sub(retention.max_retained_changes()),
+    );
+    if target <= state.compacted_through {
+        return Ok(state.compacted_through);
+    }
+
+    let topology_hash = topology.digest();
+    let partition_hash = partition.digest();
+    let old_watermark = to_i64::<DB>(state.compacted_through, "projection compaction watermark")?;
+    let target_watermark = to_i64::<DB>(target, "projection compaction watermark")?;
+    let mut delete =
+        QueryBuilder::<DB>::new("DELETE FROM projection_changes WHERE topology_hash = ");
+    delete.push_bind(topology_hash.as_slice());
+    delete.push(" AND partition_hash = ");
+    delete.push_bind(partition_hash.as_slice());
+    delete.push(" AND change_epoch = ");
+    delete.push_bind(state.change_epoch.as_str());
+    delete.push(" AND change_position > ");
+    delete.push_bind(old_watermark);
+    delete.push(" AND change_position <= ");
+    delete.push_bind(target_watermark);
+    let result =
+        delete.build().execute(&mut **tx).await.map_err(|error| {
+            protocol_storage_error::<DB>("retain projection change suffix", error)
+        })?;
+    let expected_removed = target - state.compacted_through;
+    if DB::rows_affected(&result) != expected_removed {
+        return Err(corrupt_storage(format!(
+            "projection retention expected to remove {expected_removed} changes but removed {}",
+            DB::rows_affected(&result)
+        )));
+    }
+
+    let mut update =
+        QueryBuilder::<DB>::new("UPDATE projection_partitions SET compacted_through = ");
+    update.push_bind(target_watermark);
+    update.push(" WHERE topology_hash = ");
+    update.push_bind(topology_hash.as_slice());
+    update.push(" AND partition_hash = ");
+    update.push_bind(partition_hash.as_slice());
+    update.push(" AND change_epoch = ");
+    update.push_bind(state.change_epoch.as_str());
+    update.push(" AND compacted_through = ");
+    update.push_bind(old_watermark);
+    update.push(" AND change_head = ");
+    update.push_bind(to_i64::<DB>(state.change_head, "projection change head")?);
+    let result = update.build().execute(&mut **tx).await.map_err(|error| {
+        protocol_storage_error::<DB>("advance projection retention watermark", error)
+    })?;
+    if DB::rows_affected(&result) != 1 {
+        return Err(corrupt_storage(
+            "projection partition changed while retaining its change suffix",
+        ));
+    }
+    Ok(target)
+}
+
+pub(super) fn decode_failure_row<DB>(
+    row: &DB::Row,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+    expected_change_epoch: &ProjectionEpoch,
+) -> Result<StoredFailure, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let source_bytes: Vec<u8> = row
+        .try_get("source_bytes")
+        .map_err(|error| protocol_storage_error::<DB>("decode failure source bytes", error))?;
+    let source_hash: Vec<u8> = row
+        .try_get("source_hash")
+        .map_err(|error| protocol_storage_error::<DB>("decode failure source hash", error))?;
+    let source_partition_bytes: Vec<u8> =
+        row.try_get("source_partition_bytes").map_err(|error| {
+            protocol_storage_error::<DB>("decode failure source partition bytes", error)
+        })?;
+    let source_partition_hash: Vec<u8> = row.try_get("source_partition_hash").map_err(|error| {
+        protocol_storage_error::<DB>("decode failure source partition hash", error)
+    })?;
+    let source =
+        ProjectionSource::from_canonical_name_bytes(&source_bytes, source_partition_bytes.clone())?;
+    verify_digest(&source_hash, source.digest(), "projection failure source")?;
+    verify_digest(
+        &source_partition_hash,
+        source.partition_digest(),
+        "projection failure source partition",
+    )?;
+    let source_epoch: String = row
+        .try_get("source_epoch")
+        .map_err(|error| protocol_storage_error::<DB>("decode failure source epoch", error))?;
+    let source_position = from_i64::<DB>(
+        row.try_get("source_position").map_err(|error| {
+            protocol_storage_error::<DB>("decode failure source position", error)
+        })?,
+        "failure source position",
+    )?;
+    let input_hash = decode_digest(
+        row.try_get("input_hash")
+            .map_err(|error| protocol_storage_error::<DB>("decode failure input hash", error))?,
+        "projection input",
+    )?;
+    let gap_free = match row
+        .try_get::<i64, _>("gap_free")
+        .map_err(|error| protocol_storage_error::<DB>("decode failure gap-free flag", error))?
+    {
+        0 => false,
+        1 => true,
+        value => {
+            return Err(corrupt_storage(format!(
+                "failure gap-free flag contains invalid value {value}"
+            )))
+        }
+    };
+    let failure_bytes: Vec<u8> = row
+        .try_get("failure_bytes")
+        .map_err(|error| protocol_storage_error::<DB>("decode projection failure bytes", error))?;
+    let failure_digest = decode_digest(
+        row.try_get("failure_hash").map_err(|error| {
+            protocol_storage_error::<DB>("decode projection failure hash", error)
+        })?,
+        "projection failure",
+    )?;
+    if ProjectionFailureBatch::fingerprint_bytes(&failure_bytes) != failure_digest {
+        return Err(corrupt_storage(
+            "projection failure bytes do not match their stored digest",
+        ));
+    }
+    let change_epoch: String = row
+        .try_get("change_epoch")
+        .map_err(|error| protocol_storage_error::<DB>("decode failure change epoch", error))?;
+    let change_epoch = ProjectionEpoch::new(change_epoch)?;
+    if &change_epoch != expected_change_epoch {
+        return Err(corrupt_storage(
+            "projection failure change epoch differs from its partition",
+        ));
+    }
+    let change_position = from_i64::<DB>(
+        row.try_get("change_position").map_err(|error| {
+            protocol_storage_error::<DB>("decode failure change position", error)
+        })?,
+        "failure change position",
+    )?;
+    let generation = ProjectionGeneration::new(from_i64::<DB>(
+        row.try_get("generation")
+            .map_err(|error| protocol_storage_error::<DB>("decode failure generation", error))?,
+        "projection failure generation",
+    )?)?;
+    Ok(StoredFailure {
+        failure: ProjectionFailure {
+            failure_id: row.try_get("failure_id").map_err(|error| {
+                protocol_storage_error::<DB>("decode projection failure ID", error)
+            })?,
+            input: ProjectionInputCursor::new(
+                topology.clone(),
+                partition.clone(),
+                source,
+                ProjectionEpoch::new(source_epoch)?,
+                source_position,
+            )?,
+            input_fingerprint: ProjectionInputFingerprint::from_digest(input_hash),
+            message_id: row.try_get("message_id").map_err(|error| {
+                protocol_storage_error::<DB>("decode failure message ID", error)
+            })?,
+            causation_id: row.try_get("causation_id").map_err(|error| {
+                protocol_storage_error::<DB>("decode failure causation ID", error)
+            })?,
+            generation,
+            gap_free,
+            failure_code: row.try_get("failure_code").map_err(|error| {
+                protocol_storage_error::<DB>("decode projection failure code", error)
+            })?,
+            failure_bytes,
+            failure_digest,
+            change: ProjectionChangeCursor::new(
+                topology.clone(),
+                partition.clone(),
+                change_epoch,
+                change_position,
+            )?,
+        },
+    })
+}
+
+pub(super) async fn failure_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    topology: &ProjectorTopologyId,
+    partition: &ProjectionPartition,
+    failure_id: &str,
+    expected_change_epoch: &ProjectionEpoch,
+) -> Result<Option<StoredFailure>, ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let topology_hash = topology.digest();
+    let partition_hash = partition.digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT failure_id, source_bytes, source_hash, source_partition_bytes, \
+         source_partition_hash, source_epoch, source_position, input_hash, message_id, \
+         causation_id, gap_free, generation, failure_code, failure_bytes, failure_hash, \
+         change_epoch, change_position FROM projection_failures WHERE topology_hash = ",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(" AND failure_id = ");
+    builder.push_bind(failure_id);
+    let row = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("load projection failure", error))?;
+    row.map(|row| decode_failure_row::<DB>(&row, topology, partition, expected_change_epoch))
+        .transpose()
+}
+
+pub(super) fn failure_matches_batch(
+    failure: &StoredFailure,
+    batch: &ProjectionFailureBatch,
+) -> bool {
+    crate::projection_protocol::failure_matches_batch(&failure.failure, batch)
+}
+
+pub(super) async fn ensure_pending_retry_input_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    state: &PartitionState,
+    input: &TrustedProjectionInput,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let Some(failure_id) = &state.pending_retry_failure_id else {
+        return Ok(());
+    };
+    let failure = failure_in_tx(
+        tx,
+        input.cursor.topology(),
+        input.cursor.projection_partition(),
+        failure_id,
+        &state.change_epoch,
+    )
+    .await?
+    .ok_or_else(|| {
+        corrupt_storage(format!(
+            "pending projection retry failure `{failure_id}` is missing"
+        ))
+    })?;
+    if failure.failure.generation.checked_next()? != state.active_generation {
+        return Err(corrupt_storage(format!(
+            "pending retry failure generation {} does not precede active generation {}",
+            failure.failure.generation.get(),
+            state.active_generation.get()
+        )));
+    }
+    if failure.failure.input != input.cursor {
+        return Err(ProjectionProtocolError::IncomparableInput);
+    }
+    if failure.failure.input_fingerprint != input.fingerprint
+        || failure.failure.message_id != input.message_id
+        || failure.failure.causation_id != input.causation_id
+        || failure.failure.gap_free != input.gap_free
+    {
+        return Err(ProjectionProtocolError::InputCorruption);
+    }
+    Ok(())
+}
+
+pub(super) async fn insert_failure_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    batch: &ProjectionFailureBatch,
+    change: &ProjectionChangeCursor,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    let cursor = &batch.input.cursor;
+    let topology_hash = cursor.topology().digest();
+    let partition_hash = cursor.projection_partition().digest();
+    let source = cursor.source();
+    let source_bytes = source.canonical_name_bytes();
+    let source_hash = source.digest();
+    let source_partition_hash = source.partition_digest();
+    let input_hash = batch.input.fingerprint.digest();
+    let mut builder = QueryBuilder::<DB>::new(
+        "INSERT INTO projection_failures \
+         (topology_hash, partition_hash, failure_id, source_bytes, source_hash, \
+         source_partition_bytes, source_partition_hash, source_epoch, source_position, \
+         input_hash, message_id, causation_id, gap_free, generation, failure_code, \
+         failure_bytes, failure_hash, change_epoch, change_position) VALUES (",
+    );
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(partition_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(batch.failure_id.as_str());
+    builder.push(", ");
+    builder.push_bind(source_bytes.as_slice());
+    builder.push(", ");
+    builder.push_bind(source_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(source.canonical_partition_bytes());
+    builder.push(", ");
+    builder.push_bind(source_partition_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(cursor.epoch().as_str());
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        cursor.position(),
+        "projection failure source position",
+    )?);
+    builder.push(", ");
+    builder.push_bind(input_hash.as_slice());
+    builder.push(", ");
+    builder.push_bind(batch.input.message_id.as_str());
+    builder.push(", ");
+    builder.push_bind(batch.input.causation_id.as_str());
+    builder.push(", ");
+    builder.push_bind(i64::from(batch.input.gap_free));
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        batch.input.generation.get(),
+        "projection failure generation",
+    )?);
+    builder.push(", ");
+    builder.push_bind(batch.failure_code.as_str());
+    builder.push(", ");
+    builder.push_bind(batch.failure_bytes.as_slice());
+    builder.push(", ");
+    builder.push_bind(batch.failure_digest.as_slice());
+    builder.push(", ");
+    builder.push_bind(change.epoch().as_str());
+    builder.push(", ");
+    builder.push_bind(to_i64::<DB>(
+        change.position(),
+        "projection failure change position",
+    )?);
+    builder.push(") ON CONFLICT DO NOTHING");
+    let result = builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("insert projection failure", error))?;
+    if DB::rows_affected(&result) != 1 {
+        return Err(corrupt_storage(
+            "projection failure collided while its partition lock was held",
+        ));
+    }
+    Ok(())
+}
+
+pub(super) async fn stop_partition_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    batch: &ProjectionFailureBatch,
+    change_head: u64,
+) -> Result<(), ProjectionProtocolError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    let cursor = &batch.input.cursor;
+    let topology_hash = cursor.topology().digest();
+    let partition_hash = cursor.projection_partition().digest();
+    let source = cursor.source();
+    let source_bytes = source.canonical_name_bytes();
+    let source_hash = source.digest();
+    let source_partition_hash = source.partition_digest();
+    let input_hash = batch.input.fingerprint.digest();
+    let mut builder = QueryBuilder::<DB>::new("UPDATE projection_partitions SET change_head = ");
+    builder.push_bind(to_i64::<DB>(change_head, "projection change head")?);
+    builder.push(", pending_retry_failure_id = NULL, stopped_failure_id = ");
+    builder.push_bind(batch.failure_id.as_str());
+    builder.push(", stopped_source_bytes = ");
+    builder.push_bind(source_bytes.as_slice());
+    builder.push(", stopped_source_hash = ");
+    builder.push_bind(source_hash.as_slice());
+    builder.push(", stopped_source_partition_bytes = ");
+    builder.push_bind(source.canonical_partition_bytes());
+    builder.push(", stopped_source_partition_hash = ");
+    builder.push_bind(source_partition_hash.as_slice());
+    builder.push(", stopped_source_epoch = ");
+    builder.push_bind(cursor.epoch().as_str());
+    builder.push(", stopped_source_position = ");
+    builder.push_bind(to_i64::<DB>(
+        cursor.position(),
+        "stopped projection source position",
+    )?);
+    builder.push(", stopped_generation = ");
+    builder.push_bind(to_i64::<DB>(
+        batch.input.generation.get(),
+        "stopped projection generation",
+    )?);
+    builder.push(", stopped_input_hash = ");
+    builder.push_bind(input_hash.as_slice());
+    builder.push(", stopped_message_id = ");
+    builder.push_bind(batch.input.message_id.as_str());
+    builder.push(", stopped_causation_id = ");
+    builder.push_bind(batch.input.causation_id.as_str());
+    builder.push(", stopped_gap_free = ");
+    builder.push_bind(i64::from(batch.input.gap_free));
+    builder.push(" WHERE topology_hash = ");
+    builder.push_bind(topology_hash.as_slice());
+    builder.push(" AND partition_hash = ");
+    builder.push_bind(partition_hash.as_slice());
+    let result = builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|error| protocol_storage_error::<DB>("stop projection partition", error))?;
+    if DB::rows_affected(&result) != 1 {
+        return Err(corrupt_storage(
+            "projection partition disappeared while recording its failure",
+        ));
+    }
+    Ok(())
+}
diff --git a/src/sqlx_repo/read_model.rs b/src/sqlx_repo/read_model.rs
deleted file mode 100644
index f9bb904c..00000000
--- a/src/sqlx_repo/read_model.rs
+++ /dev/null
@@ -1,1230 +0,0 @@
-//! Backend-agnostic read-model logic shared by the Postgres and SQLite repositories.
-//!
-//! Two layers live here:
-//!
-//! 1. **Pure helpers** (no `sqlx` types): write-plan validation, key/patch
-//!    reconciliation, row-version arithmetic, relationship-include resolution.
-//! 2. **The generic relational write path**: free functions over
-//!    `DB: SqlxReadModelBackend` that build and run the upsert/patch/delete SQL via
-//!    `QueryBuilder<DB>`. Only the value-binding (`Bool`/typed-`NULL`), the
-//!    `rows_affected` accessor, and two label strings differ per dialect; the
-//!    [`SqlxReadModelBackend`] trait carries exactly those — one trait, two
-//!    one-line-per-method impls — so the SQL-building logic exists once rather than
-//!    being mirrored (and risking silent drift) in `postgres_repo`/`sqlite_repo`.
-
-use std::collections::BTreeMap;
-use std::sync::RwLock;
-
-use sqlx::{Database, Encode, Executor, IntoArguments, QueryBuilder, Row, Transaction, Type};
-
-use crate::read_model::{
-    ReadModelIncludeRows, ReadModelLoadGraph, ReadModelLoadRequest, ReadModelQueryCapabilities,
-    Versioned,
-};
-use crate::table::TableSchemaRegistry;
-use crate::table::{
-    key_fingerprint, validate_key, validate_row_values, DeleteTableRowMutation, ExpectedVersion,
-    PatchMode, PatchTableRowMutation, RelationshipDef, RelationshipKind, RowKey, RowValue,
-    RowValues, RowWriteMode, TableAdapterCapabilities, TableColumn, TableCommitOutcome,
-    TableMutation, TableRowMutation, TableSchema, TableStoreError, TableWritePlan,
-};
-
-/// A resolved relationship include: the relationship metadata plus the registered
-/// schema of the target model, ready for the relational load path to query.
-#[derive(Clone)]
-pub(crate) struct IncludeSpec {
-    pub(crate) name: String,
-    pub(crate) relationship: RelationshipDef,
-    pub(crate) target_schema: TableSchema,
-}
-
-pub(crate) fn remember_read_model_schemas(
-    stored: &RwLock<TableSchemaRegistry>,
-    registry: &TableSchemaRegistry,
-) -> Result<(), TableStoreError> {
-    let mut stored = stored
-        .write()
-        .map_err(|_| TableStoreError::Storage("read-model schema registry lock poisoned".into()))?;
-
-    for schema in registry.schemas() {
-        if let Some(existing) = stored.schema_for_table(&schema.table_name) {
-            if existing != schema {
-                return Err(TableStoreError::Metadata(format!(
-                    "read-model schema registry already contains table `{}` with different metadata",
-                    schema.table_name
-                )));
-            }
-            continue;
-        }
-        stored.register_schema(schema.clone())?;
-    }
-
-    Ok(())
-}
-
-pub(crate) fn resolve_registered_read_model_schemas(
-    registry: &RwLock<TableSchemaRegistry>,
-    request: &ReadModelLoadRequest,
-) -> Result<(TableSchema, Vec<IncludeSpec>), TableStoreError> {
-    if request.includes.is_empty() {
-        return Ok((request.schema.clone(), Vec::new()));
-    }
-
-    let registry = registry
-        .read()
-        .map_err(|_| TableStoreError::Storage("read-model schema registry lock poisoned".into()))?;
-    let root_schema = registry
-        .schema_for_model(&request.schema.model_name)
-        .cloned()
-        .ok_or_else(|| {
-            TableStoreError::Metadata(format!(
-                "read model `{}` is not registered for relationship includes",
-                request.schema.model_name
-            ))
-        })?;
-    if root_schema != request.schema {
-        return Err(TableStoreError::Metadata(format!(
-            "read model `{}` load request does not match registered schema",
-            request.schema.model_name
-        )));
-    }
-
-    let mut include_specs = Vec::with_capacity(request.includes.len());
-    for include_name in &request.includes {
-        let relationship = root_schema
-            .relationships
-            .iter()
-            .find(|relationship| relationship.field_name == *include_name)
-            .ok_or_else(|| {
-                TableStoreError::Metadata(format!(
-                    "read model `{}` has no relationship `{}`",
-                    root_schema.model_name, include_name
-                ))
-            })?;
-        if matches!(relationship.kind, RelationshipKind::ManyToMany) {
-            return Err(TableStoreError::Metadata(format!(
-                "many-to-many relationship `{}` includes are not supported until join metadata declares source and target keys",
-                relationship.field_name
-            )));
-        }
-        let target_schema = registry
-            .schema_for_model(&relationship.target_model)
-            .ok_or_else(|| {
-                TableStoreError::Metadata(format!(
-                    "read model `{}` relationship `{}` targets unregistered model `{}`",
-                    root_schema.model_name, relationship.field_name, relationship.target_model
-                ))
-            })?;
-
-        include_specs.push(IncludeSpec {
-            name: include_name.clone(),
-            relationship: relationship.clone(),
-            target_schema: target_schema.clone(),
-        });
-    }
-
-    Ok((root_schema, include_specs))
-}
-
-pub(crate) fn sql_read_model_capabilities() -> TableAdapterCapabilities {
-    TableAdapterCapabilities {
-        relational_rows: true,
-        sparse_patches: true,
-        deletes: true,
-    }
-}
-
-pub(crate) fn validate_sql_write_plan(plan: &TableWritePlan) -> Result<(), TableStoreError> {
-    plan.validate_for(&sql_read_model_capabilities())
-}
-
-pub(crate) fn initial_row_version() -> u64 {
-    1
-}
-
-pub(crate) fn validate_row_expected_version(
-    schema: &TableSchema,
-    key: &RowKey,
-    expected_version: &ExpectedVersion,
-    current_version: Option<u64>,
-) -> Result<(), TableStoreError> {
-    match (expected_version, current_version) {
-        (ExpectedVersion::Any, _) => Ok(()),
-        (ExpectedVersion::Exact(expected), Some(actual)) if expected == &actual => Ok(()),
-        (ExpectedVersion::Exact(expected), Some(actual)) => {
-            Err(row_concurrency_conflict(schema, key, *expected, actual))
-        }
-        (ExpectedVersion::Exact(_), None) => Err(TableStoreError::NotFound {
-            collection: schema.table_name.clone(),
-            id: key_fingerprint(key),
-        }),
-        (ExpectedVersion::NotExists, None) => Ok(()),
-        (ExpectedVersion::NotExists, Some(actual)) => {
-            Err(row_concurrency_conflict(schema, key, 0, actual))
-        }
-    }
-}
-
-pub(crate) fn row_concurrency_conflict(
-    schema: &TableSchema,
-    key: &RowKey,
-    expected: u64,
-    actual: u64,
-) -> TableStoreError {
-    TableStoreError::ConcurrencyConflict {
-        collection: schema.table_name.clone(),
-        id: key_fingerprint(key),
-        expected,
-        actual,
-    }
-}
-
-pub(crate) fn row_values_from_key_and_patch(
-    schema: &TableSchema,
-    key: &RowKey,
-    patch: crate::table::RowPatch,
-) -> Result<RowValues, TableStoreError> {
-    let mut values = RowValues::new();
-    for (column, value) in key.iter() {
-        values.insert(column.to_string(), value.clone());
-    }
-    for (column, value) in patch.into_values() {
-        if schema
-            .primary_key
-            .columns
-            .iter()
-            .any(|primary_key| primary_key == &column)
-        {
-            let key_value = key.get(&column).ok_or_else(|| {
-                TableStoreError::Metadata(format!(
-                    "read model `{}` row key is missing primary-key column `{}`",
-                    schema.model_name, column
-                ))
-            })?;
-            if key_value != &value {
-                return Err(TableStoreError::Metadata(format!(
-                    "read model `{}` patch cannot change primary-key column `{}`",
-                    schema.model_name, column
-                )));
-            }
-        }
-        values.insert(column, value);
-    }
-    validate_row_values(schema, &values, true)?;
-    validate_values_match_key(schema, key, &values)?;
-    Ok(values)
-}
-
-pub(crate) fn patch_values_preserving_key<'schema>(
-    schema: &'schema TableSchema,
-    key: &RowKey,
-    patch: &crate::table::RowPatch,
-) -> Result<Vec<(&'schema TableColumn, RowValue)>, TableStoreError> {
-    let mut values = Vec::new();
-    for (column_name, value) in patch.iter() {
-        let column = column_by_name(schema, column_name)?;
-        if column.primary_key {
-            let key_value = key.get(column_name).ok_or_else(|| {
-                TableStoreError::Metadata(format!(
-                    "read model `{}` row key is missing primary-key column `{}`",
-                    schema.model_name, column_name
-                ))
-            })?;
-            if key_value != value {
-                return Err(TableStoreError::Metadata(format!(
-                    "read model `{}` patch cannot change primary-key column `{}`",
-                    schema.model_name, column_name
-                )));
-            }
-            continue;
-        }
-        values.push((column, value.clone()));
-    }
-    Ok(values)
-}
-
-pub(crate) fn validate_values_match_key(
-    schema: &TableSchema,
-    key: &RowKey,
-    values: &RowValues,
-) -> Result<(), TableStoreError> {
-    for column in &schema.primary_key.columns {
-        let key_value = key.get(column).ok_or_else(|| {
-            TableStoreError::Metadata(format!(
-                "read model `{}` row key is missing primary-key column `{}`",
-                schema.model_name, column
-            ))
-        })?;
-        let row_value = values.get(column).ok_or_else(|| {
-            TableStoreError::Metadata(format!(
-                "read model `{}` row is missing primary-key column `{}`",
-                schema.model_name, column
-            ))
-        })?;
-        if row_value != key_value {
-            return Err(TableStoreError::Metadata(format!(
-                "read model `{}` row values cannot change primary-key column `{}`",
-                schema.model_name, column
-            )));
-        }
-    }
-    Ok(())
-}
-
-pub(crate) fn belongs_to_target_column(
-    target_schema: &TableSchema,
-    source_column: &str,
-) -> Result<String, TableStoreError> {
-    if target_schema.primary_key.columns.len() != 1 {
-        return Err(TableStoreError::Metadata(format!(
-            "belongs_to target `{}` must have a single-column primary key to load from `{}`",
-            target_schema.model_name, source_column
-        )));
-    }
-
-    Ok(target_schema.primary_key.columns[0].clone())
-}
-
-pub(crate) fn empty_string_as_none(value: &str) -> Option<&str> {
-    if value.is_empty() {
-        None
-    } else {
-        Some(value)
-    }
-}
-
-pub(crate) fn row_write_values<'schema>(
-    schema: &'schema TableSchema,
-    values: &RowValues,
-) -> Result<Vec<(&'schema TableColumn, RowValue)>, TableStoreError> {
-    values
-        .iter()
-        .map(|(column_name, value)| Ok((column_by_name(schema, column_name)?, value.clone())))
-        .collect()
-}
-
-pub(crate) fn column_by_name<'schema>(
-    schema: &'schema TableSchema,
-    column_name: &str,
-) -> Result<&'schema TableColumn, TableStoreError> {
-    schema
-        .columns
-        .iter()
-        .find(|column| column.column_name == column_name)
-        .ok_or_else(|| {
-            TableStoreError::Metadata(format!(
-                "read model `{}` write references missing column `{}`",
-                schema.model_name, column_name
-            ))
-        })
-}
-
-pub(crate) fn version_column(schema: &TableSchema) -> Result<&str, TableStoreError> {
-    schema.version_column.as_deref().ok_or_else(|| {
-        TableStoreError::Metadata(format!(
-            "read model `{}` requires a version column for SQL write-plan persistence",
-            schema.model_name
-        ))
-    })
-}
-
-pub(crate) fn quote_identifier(value: &str) -> String {
-    format!("\"{}\"", value.replace('"', "\"\""))
-}
-
-use super::{read_model_i64_from_u64, read_model_storage_error, read_model_u64_from_i64};
-
-/// Dialect surface for the shared relational write path.
-///
-/// The upsert/patch/delete SQL is identical across Postgres and SQLite because
-/// `QueryBuilder<DB>` renders the right placeholder dialect; only two things
-/// genuinely differ: the value-binding for `Bool`/typed-`NULL` (Postgres binds
-/// native `bool` and needs explicit per-type `NULL` casts for `$N` inference;
-/// SQLite stores booleans as `i64` and collapses integer/bool `NULL`s) and the
-/// backend/storage labels used in numeric-conversion error messages. Those —
-/// and nothing else — live behind this trait, implemented once per backend.
-pub trait SqlxReadModelBackend: Database {
-    /// Backend name used in numeric-conversion error messages (`"postgres"`/`"sqlite"`).
-    const BACKEND: &'static str;
-    /// Human-readable storage label for the signed-64-bit version column.
-    const INTEGER_STORAGE: &'static str;
-
-    /// Bind one `RowValue` into the builder (dialect-specific encoding), then push
-    /// any required type cast (Postgres `::jsonb`/`::timestamptz`; SQLite none).
-    fn push_row_value_bind(
-        builder: &mut QueryBuilder<Self>,
-        value: RowValue,
-        column: &TableColumn,
-    ) -> Result<(), TableStoreError>;
-
-    /// Bind a typed `NULL` for the column's type (Postgres needs the concrete
-    /// `Option::<T>::None` per type so `$N` infers correctly).
-    fn push_null_bind(
-        builder: &mut QueryBuilder<Self>,
-        column: &TableColumn,
-    ) -> Result<(), TableStoreError>;
-
-    /// Affected-row count of a write result. `sqlx` exposes `rows_affected` only as
-    /// an inherent method on each backend's `QueryResult`, not via a shared trait,
-    /// so the one-line accessor is delegated here.
-    fn rows_affected(result: &Self::QueryResult) -> u64;
-
-    /// Render one `SELECT`-list column. Postgres casts JSON/Timestamp to `::text`
-    /// so they decode as `String`; SQLite stores them as text already, so it just
-    /// pushes the quoted column. (Reading is the inverse of `push_row_value_bind`.)
-    fn push_select_column(builder: &mut QueryBuilder<Self>, column: &TableColumn);
-
-    /// Decode one fetched column into a `RowValue`. The one genuinely dialect-
-    /// specific read: Postgres has a native `BOOLEAN`, SQLite stores booleans as
-    /// `INTEGER` and decodes `value != 0`.
-    fn row_value(row: &Self::Row, column: &TableColumn) -> Result<RowValue, TableStoreError>;
-}
-
-pub(crate) async fn begin_read_model_tx<DB: SqlxReadModelBackend>(
-    pool: &sqlx::Pool<DB>,
-) -> Result<Transaction<'_, DB>, TableStoreError> {
-    pool.begin()
-        .await
-        .map_err(|err| read_model_storage_error(DB::BACKEND, "begin transaction", err))
-}
-
-pub(crate) async fn commit_read_model_tx<DB: SqlxReadModelBackend>(
-    tx: Transaction<'_, DB>,
-) -> Result<(), TableStoreError> {
-    tx.commit()
-        .await
-        .map_err(|err| read_model_storage_error(DB::BACKEND, "commit transaction", err))
-}
-
-pub(crate) async fn commit_read_model_write_plan<DB>(
-    pool: &sqlx::Pool<DB>,
-    plan: TableWritePlan,
-) -> Result<TableCommitOutcome, TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    validate_sql_write_plan(&plan)?;
-    let mut tx = begin_read_model_tx(pool).await?;
-    let outcome = apply_read_model_write_plan_in_tx(&mut tx, plan).await?;
-    commit_read_model_tx(tx).await?;
-    Ok(outcome)
-}
-
-pub(crate) async fn apply_read_model_write_plan_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    plan: TableWritePlan,
-) -> Result<TableCommitOutcome, TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    validate_sql_write_plan(&plan)?;
-
-    for mutation in plan.mutations {
-        match mutation {
-            TableMutation::UpsertRow(mutation) => {
-                upsert_relational_row_in_tx(tx, mutation).await?;
-            }
-            TableMutation::PatchRow(mutation) => {
-                patch_relational_row_in_tx(tx, mutation).await?;
-            }
-            TableMutation::DeleteRow(mutation) => {
-                delete_relational_row_in_tx(tx, mutation).await?;
-            }
-        }
-    }
-
-    Ok(TableCommitOutcome::applied())
-}
-
-pub(crate) async fn upsert_relational_row_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    mutation: TableRowMutation,
-) -> Result<(), TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    validate_key(mutation.schema, &mutation.key)?;
-    validate_row_values(mutation.schema, &mutation.values, true)?;
-    validate_values_match_key(mutation.schema, &mutation.key, &mutation.values)?;
-
-    // The common case — upsert without an optimistic-version check — is a single
-    // `INSERT ... ON CONFLICT (pk) DO UPDATE` round trip. Only version-checked
-    // writes need to observe the current row first.
-    if matches!(mutation.mode, RowWriteMode::Upsert)
-        && matches!(mutation.expected_version, ExpectedVersion::Any)
-    {
-        return upsert_relational_row_on_conflict_in_tx(tx, mutation.schema, &mutation.values)
-            .await;
-    }
-
-    let current_version = row_version_in_tx(tx, mutation.schema, &mutation.key).await?;
-    validate_row_expected_version(
-        mutation.schema,
-        &mutation.key,
-        &mutation.expected_version,
-        current_version,
-    )?;
-    if matches!(mutation.mode, RowWriteMode::Insert) && current_version.is_some() {
-        return Err(row_concurrency_conflict(
-            mutation.schema,
-            &mutation.key,
-            0,
-            current_version.unwrap_or_default(),
-        ));
-    }
-
-    match current_version {
-        Some(expected_version) => {
-            let rows_affected = update_relational_row_values_in_tx(
-                tx,
-                mutation.schema,
-                &mutation.key,
-                &mutation.values,
-                Some(expected_version),
-            )
-            .await?;
-            if rows_affected == 0 {
-                let actual = row_version_in_tx(tx, mutation.schema, &mutation.key)
-                    .await?
-                    .unwrap_or(expected_version);
-                return Err(row_concurrency_conflict(
-                    mutation.schema,
-                    &mutation.key,
-                    expected_version,
-                    actual,
-                ));
-            }
-        }
-        None => {
-            insert_relational_row_in_tx(
-                tx,
-                mutation.schema,
-                &mutation.values,
-                initial_row_version(),
-            )
-            .await?;
-        }
-    }
-
-    Ok(())
-}
-
-pub(crate) async fn patch_relational_row_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    mutation: PatchTableRowMutation,
-) -> Result<(), TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    validate_key(mutation.schema, &mutation.key)?;
-
-    // `NotExists` is the only shape that has to observe the row before writing;
-    // `Any`/`Exact` run the UPDATE directly and only re-read on a miss to tell
-    // "not found" apart from a version conflict.
-    if matches!(mutation.expected_version, ExpectedVersion::NotExists) {
-        let current_version = row_version_in_tx(tx, mutation.schema, &mutation.key).await?;
-        validate_row_expected_version(
-            mutation.schema,
-            &mutation.key,
-            &mutation.expected_version,
-            current_version,
-        )?;
-        if !matches!(mutation.mode, PatchMode::InsertMissing) {
-            return Err(TableStoreError::NotFound {
-                collection: mutation.schema.table_name.clone(),
-                id: key_fingerprint(&mutation.key),
-            });
-        }
-        let values = row_values_from_key_and_patch(mutation.schema, &mutation.key, mutation.patch)?;
-        return insert_relational_row_in_tx(tx, mutation.schema, &values, initial_row_version())
-            .await;
-    }
-
-    let expected_version = match mutation.expected_version {
-        ExpectedVersion::Exact(expected) => Some(expected),
-        _ => None,
-    };
-    let patch_values =
-        patch_values_preserving_key(mutation.schema, &mutation.key, &mutation.patch)?;
-    let rows_affected = update_relational_columns_in_tx(
-        tx,
-        mutation.schema,
-        &mutation.key,
-        patch_values,
-        expected_version,
-    )
-    .await?;
-    if rows_affected == 0 {
-        if let Some(expected_version) = expected_version {
-            return match row_version_in_tx(tx, mutation.schema, &mutation.key).await? {
-                Some(actual) => Err(row_concurrency_conflict(
-                    mutation.schema,
-                    &mutation.key,
-                    expected_version,
-                    actual,
-                )),
-                None => Err(TableStoreError::NotFound {
-                    collection: mutation.schema.table_name.clone(),
-                    id: key_fingerprint(&mutation.key),
-                }),
-            };
-        }
-        if matches!(mutation.mode, PatchMode::InsertMissing) {
-            let values =
-                row_values_from_key_and_patch(mutation.schema, &mutation.key, mutation.patch)?;
-            insert_relational_row_in_tx(tx, mutation.schema, &values, initial_row_version())
-                .await?;
-        } else {
-            return Err(TableStoreError::NotFound {
-                collection: mutation.schema.table_name.clone(),
-                id: key_fingerprint(&mutation.key),
-            });
-        }
-    }
-
-    Ok(())
-}
-
-pub(crate) async fn delete_relational_row_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    mutation: DeleteTableRowMutation,
-) -> Result<(), TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    validate_key(mutation.schema, &mutation.key)?;
-
-    match mutation.expected_version {
-        // The row must not exist: nothing to delete, but surface a conflict if it does.
-        ExpectedVersion::NotExists => {
-            let current_version = row_version_in_tx(tx, mutation.schema, &mutation.key).await?;
-            validate_row_expected_version(
-                mutation.schema,
-                &mutation.key,
-                &mutation.expected_version,
-                current_version,
-            )?;
-            Ok(())
-        }
-        // No version check: one DELETE; deleting a missing row is a no-op.
-        ExpectedVersion::Any => {
-            delete_relational_row_where_version_in_tx(tx, mutation.schema, &mutation.key, None)
-                .await?;
-            Ok(())
-        }
-        // Version-checked delete: only re-read on a miss to tell "not found"
-        // apart from a version conflict.
-        ExpectedVersion::Exact(expected_version) => {
-            let rows_affected = delete_relational_row_where_version_in_tx(
-                tx,
-                mutation.schema,
-                &mutation.key,
-                Some(expected_version),
-            )
-            .await?;
-            if rows_affected == 0 {
-                return match row_version_in_tx(tx, mutation.schema, &mutation.key).await? {
-                    Some(actual) => Err(row_concurrency_conflict(
-                        mutation.schema,
-                        &mutation.key,
-                        expected_version,
-                        actual,
-                    )),
-                    None => Err(TableStoreError::NotFound {
-                        collection: mutation.schema.table_name.clone(),
-                        id: key_fingerprint(&mutation.key),
-                    }),
-                };
-            }
-            Ok(())
-        }
-    }
-}
-
-pub(crate) async fn row_version_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    schema: &TableSchema,
-    key: &RowKey,
-) -> Result<Option<u64>, TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    let version_column = version_column(schema)?;
-    let mut builder = QueryBuilder::<DB>::new("SELECT ");
-    builder.push(quote_identifier(version_column));
-    builder.push(" FROM ");
-    builder.push(quote_identifier(&schema.table_name));
-    push_key_predicates(&mut builder, schema, key)?;
-
-    let row = builder
-        .build()
-        .fetch_optional(&mut **tx)
-        .await
-        .map_err(|err| read_model_storage_error(DB::BACKEND, "load relational row version", err))?;
-
-    row.map(|row| {
-        read_model_u64_from_i64(
-            DB::BACKEND,
-            row.try_get::<i64, _>(version_column).map_err(|err| {
-                read_model_storage_error(DB::BACKEND, "decode relational row version", err)
-            })?,
-            version_column,
-        )
-    })
-    .transpose()
-}
-
-pub(crate) async fn insert_relational_row_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    schema: &TableSchema,
-    values: &RowValues,
-    version: u64,
-) -> Result<(), TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    let version_column = version_column(schema)?;
-    let write_values = row_write_values(schema, values)?;
-    let has_write_values = !write_values.is_empty();
-    let mut builder = QueryBuilder::<DB>::new("INSERT INTO ");
-    builder.push(quote_identifier(&schema.table_name));
-    builder.push(" (");
-    for (index, (column, _)) in write_values.iter().enumerate() {
-        if index > 0 {
-            builder.push(", ");
-        }
-        builder.push(quote_identifier(&column.column_name));
-    }
-    if has_write_values {
-        builder.push(", ");
-    }
-    builder.push(quote_identifier(version_column));
-    builder.push(") VALUES (");
-    for (index, (column, value)) in write_values.into_iter().enumerate() {
-        if index > 0 {
-            builder.push(", ");
-        }
-        DB::push_row_value_bind(&mut builder, value, column)?;
-    }
-    if has_write_values {
-        builder.push(", ");
-    }
-    builder.push_bind(read_model_i64_from_u64(
-        DB::BACKEND,
-        version,
-        version_column,
-        DB::INTEGER_STORAGE,
-    )?);
-    builder.push(")");
-
-    builder
-        .build()
-        .execute(&mut **tx)
-        .await
-        .map_err(|err| read_model_storage_error(DB::BACKEND, "insert relational row", err))?;
-
-    Ok(())
-}
-
-/// Upsert one row in a single statement: `INSERT ... ON CONFLICT (pk) DO UPDATE
-/// SET <non-pk columns> = excluded.<column>, <version> = <version> + 1`.
-///
-/// Both Postgres and SQLite (≥ 3.35) support `ON CONFLICT` with an explicit
-/// column-list target and the `excluded` pseudo-table. New rows start at
-/// version 1; conflicting rows bump their version in-database (an increment
-/// past `i64::MAX` fails as a storage error).
-pub(crate) async fn upsert_relational_row_on_conflict_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    schema: &TableSchema,
-    values: &RowValues,
-) -> Result<(), TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    let version_column = version_column(schema)?;
-    let write_values = row_write_values(schema, values)?;
-    let mut builder = QueryBuilder::<DB>::new("INSERT INTO ");
-    builder.push(quote_identifier(&schema.table_name));
-    builder.push(" (");
-    for (column, _) in &write_values {
-        builder.push(quote_identifier(&column.column_name));
-        builder.push(", ");
-    }
-    builder.push(quote_identifier(version_column));
-    builder.push(") VALUES (");
-    for (column, value) in write_values.iter().cloned() {
-        DB::push_row_value_bind(&mut builder, value, column)?;
-        builder.push(", ");
-    }
-    builder.push_bind(read_model_i64_from_u64(
-        DB::BACKEND,
-        initial_row_version(),
-        version_column,
-        DB::INTEGER_STORAGE,
-    )?);
-    builder.push(") ON CONFLICT (");
-    for (index, column_name) in schema.primary_key.columns.iter().enumerate() {
-        if index > 0 {
-            builder.push(", ");
-        }
-        builder.push(quote_identifier(column_name));
-    }
-    builder.push(") DO UPDATE SET ");
-    for (column, _) in write_values
-        .iter()
-        .filter(|(column, _)| !column.primary_key)
-    {
-        builder.push(quote_identifier(&column.column_name));
-        builder.push(" = excluded.");
-        builder.push(quote_identifier(&column.column_name));
-        builder.push(", ");
-    }
-    // Qualify the existing-row reference with the table name: inside `DO UPDATE`
-    // an unqualified column is ambiguous with `excluded` on Postgres.
-    builder.push(quote_identifier(version_column));
-    builder.push(" = ");
-    builder.push(quote_identifier(&schema.table_name));
-    builder.push(".");
-    builder.push(quote_identifier(version_column));
-    builder.push(" + 1");
-
-    builder
-        .build()
-        .execute(&mut **tx)
-        .await
-        .map_err(|err| read_model_storage_error(DB::BACKEND, "upsert relational row", err))?;
-
-    Ok(())
-}
-
-pub(crate) async fn update_relational_row_values_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    schema: &TableSchema,
-    key: &RowKey,
-    values: &RowValues,
-    expected_version: Option<u64>,
-) -> Result<u64, TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    let mut write_values = row_write_values(schema, values)?;
-    write_values.retain(|(column, _)| !column.primary_key);
-    update_relational_columns_in_tx(tx, schema, key, write_values, expected_version).await
-}
-
-/// `UPDATE <table> SET <columns>, <version> = <version> + 1 WHERE <pk> [AND
-/// <version> = <expected>]`, returning the affected-row count. The version bump
-/// happens in-database; an increment past `i64::MAX` fails as a storage error.
-pub(crate) async fn update_relational_columns_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    schema: &TableSchema,
-    key: &RowKey,
-    write_values: Vec<(&TableColumn, RowValue)>,
-    expected_version: Option<u64>,
-) -> Result<u64, TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    let version_column = version_column(schema)?;
-    let mut builder = QueryBuilder::<DB>::new("UPDATE ");
-    builder.push(quote_identifier(&schema.table_name));
-    builder.push(" SET ");
-    for (column, value) in write_values {
-        builder.push(quote_identifier(&column.column_name));
-        builder.push(" = ");
-        DB::push_row_value_bind(&mut builder, value, column)?;
-        builder.push(", ");
-    }
-    builder.push(quote_identifier(version_column));
-    builder.push(" = ");
-    builder.push(quote_identifier(version_column));
-    builder.push(" + 1");
-    push_key_predicates(&mut builder, schema, key)?;
-    if let Some(expected_version) = expected_version {
-        builder.push(" AND ");
-        builder.push(quote_identifier(version_column));
-        builder.push(" = ");
-        builder.push_bind(read_model_i64_from_u64(
-            DB::BACKEND,
-            expected_version,
-            "expected version",
-            DB::INTEGER_STORAGE,
-        )?);
-    }
-
-    let result = builder
-        .build()
-        .execute(&mut **tx)
-        .await
-        .map_err(|err| read_model_storage_error(DB::BACKEND, "update relational row", err))?;
-    Ok(DB::rows_affected(&result))
-}
-
-pub(crate) async fn delete_relational_row_where_version_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    schema: &TableSchema,
-    key: &RowKey,
-    expected_version: Option<u64>,
-) -> Result<u64, TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    let mut builder = QueryBuilder::<DB>::new("DELETE FROM ");
-    builder.push(quote_identifier(&schema.table_name));
-    push_key_predicates(&mut builder, schema, key)?;
-    if let Some(version) = expected_version {
-        let version_column = version_column(schema)?;
-        builder.push(" AND ");
-        builder.push(quote_identifier(version_column));
-        builder.push(" = ");
-        builder.push_bind(read_model_i64_from_u64(
-            DB::BACKEND,
-            version,
-            "expected version",
-            DB::INTEGER_STORAGE,
-        )?);
-    }
-
-    let result = builder
-        .build()
-        .execute(&mut **tx)
-        .await
-        .map_err(|err| read_model_storage_error(DB::BACKEND, "delete relational row", err))?;
-    Ok(DB::rows_affected(&result))
-}
-
-pub(crate) fn push_key_predicates<DB: SqlxReadModelBackend>(
-    builder: &mut QueryBuilder<DB>,
-    schema: &TableSchema,
-    key: &RowKey,
-) -> Result<(), TableStoreError> {
-    builder.push(" WHERE ");
-    for (index, column_name) in schema.primary_key.columns.iter().enumerate() {
-        if index > 0 {
-            builder.push(" AND ");
-        }
-        let column = column_by_name(schema, column_name)?;
-        let value = key.get(column_name).cloned().ok_or_else(|| {
-            TableStoreError::Metadata(format!(
-                "read model `{}` row key is missing primary-key column `{}`",
-                schema.model_name, column_name
-            ))
-        })?;
-        builder.push(quote_identifier(column_name));
-        builder.push(" = ");
-        DB::push_row_value_bind(builder, value, column)?;
-    }
-    Ok(())
-}
-
-/// Build the shared `SELECT <columns>, <version> FROM <table>` prefix used by every
-/// relational read. Per-column rendering is dialect-specific (`push_select_column`).
-pub(crate) fn relational_row_select<DB: SqlxReadModelBackend>(
-    schema: &TableSchema,
-) -> Result<QueryBuilder<DB>, TableStoreError> {
-    let version_column = version_column(schema)?;
-    let mut builder = QueryBuilder::<DB>::new("SELECT ");
-    for (index, column) in schema.columns.iter().enumerate() {
-        if index > 0 {
-            builder.push(", ");
-        }
-        DB::push_select_column(&mut builder, column);
-    }
-    if !schema.columns.is_empty() {
-        builder.push(", ");
-    }
-    builder.push(quote_identifier(version_column));
-    builder.push(" FROM ");
-    builder.push(quote_identifier(&schema.table_name));
-    Ok(builder)
-}
-
-pub(crate) fn push_order_by_primary_key<DB: SqlxReadModelBackend>(
-    builder: &mut QueryBuilder<DB>,
-    schema: &TableSchema,
-) {
-    if schema.primary_key.columns.is_empty() {
-        return;
-    }
-    builder.push(" ORDER BY ");
-    for (index, column) in schema.primary_key.columns.iter().enumerate() {
-        if index > 0 {
-            builder.push(", ");
-        }
-        builder.push(quote_identifier(column));
-    }
-}
-
-pub(crate) fn row_to_versioned_values<DB>(
-    schema: &TableSchema,
-    row: &DB::Row,
-) -> Result<Versioned<RowValues>, TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    let mut values = RowValues::new();
-    for column in &schema.columns {
-        values.insert(column.column_name.clone(), DB::row_value(row, column)?);
-    }
-    let version_column = version_column(schema)?;
-    let version = read_model_u64_from_i64(
-        DB::BACKEND,
-        row.try_get::<i64, _>(version_column).map_err(|err| {
-            read_model_storage_error(DB::BACKEND, "decode relational row version", err)
-        })?,
-        version_column,
-    )?;
-    Ok(Versioned {
-        data: values,
-        version,
-    })
-}
-
-pub(crate) async fn load_relational_row_by_key<DB>(
-    pool: &sqlx::Pool<DB>,
-    schema: &TableSchema,
-    key: &RowKey,
-) -> Result<Option<Versioned<RowValues>>, TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c sqlx::Pool<DB>: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    validate_key(schema, key)?;
-    let mut builder = relational_row_select::<DB>(schema)?;
-    push_key_predicates(&mut builder, schema, key)?;
-    let row = builder
-        .build()
-        .fetch_optional(pool)
-        .await
-        .map_err(|err| read_model_storage_error(DB::BACKEND, "load relational row", err))?;
-    row.map(|row| row_to_versioned_values::<DB>(schema, &row))
-        .transpose()
-}
-
-pub(crate) async fn load_relationship_rows<DB>(
-    pool: &sqlx::Pool<DB>,
-    root_schema: &TableSchema,
-    root_row: &RowValues,
-    spec: &IncludeSpec,
-) -> Result<Vec<Versioned<RowValues>>, TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c sqlx::Pool<DB>: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    match spec.relationship.kind {
-        RelationshipKind::HasMany => load_has_many_rows(pool, root_schema, root_row, spec).await,
-        RelationshipKind::BelongsTo => {
-            load_belongs_to_rows(pool, root_schema, root_row, spec).await
-        }
-        RelationshipKind::ManyToMany => Err(TableStoreError::Metadata(format!(
-            "many-to-many relationship `{}` includes are not supported yet",
-            spec.relationship.field_name
-        ))),
-    }
-}
-
-pub(crate) async fn load_read_model_graph<DB>(
-    pool: &sqlx::Pool<DB>,
-    schemas: &RwLock<TableSchemaRegistry>,
-    request: ReadModelLoadRequest,
-    capabilities: ReadModelQueryCapabilities,
-) -> Result<ReadModelLoadGraph, TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c sqlx::Pool<DB>: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    request.validate_for_query_capabilities(&capabilities)?;
-
-    let (root_schema, include_specs) = resolve_registered_read_model_schemas(schemas, &request)?;
-    validate_key(&root_schema, &request.key)?;
-
-    let Some(root) = load_relational_row_by_key(pool, &root_schema, &request.key).await? else {
-        return Ok(ReadModelLoadGraph::default());
-    };
-
-    let mut includes = BTreeMap::new();
-    for spec in include_specs {
-        let rows = load_relationship_rows(pool, &root_schema, &root.data, &spec).await?;
-        includes.insert(
-            spec.name,
-            ReadModelIncludeRows {
-                relationship: spec.relationship,
-                target_schema: spec.target_schema,
-                rows,
-            },
-        );
-    }
-
-    Ok(ReadModelLoadGraph {
-        root: Some(root),
-        includes,
-    })
-}
-
-async fn load_has_many_rows<DB>(
-    pool: &sqlx::Pool<DB>,
-    root_schema: &TableSchema,
-    root_row: &RowValues,
-    spec: &IncludeSpec,
-) -> Result<Vec<Versioned<RowValues>>, TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c sqlx::Pool<DB>: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    let foreign_key = spec.relationship.foreign_key.as_deref().ok_or_else(|| {
-        TableStoreError::Metadata(format!(
-            "relationship `{}` must declare a foreign key",
-            spec.relationship.field_name
-        ))
-    })?;
-    let target_column = crate::table::column_name_for(&spec.target_schema, foreign_key)
-        .ok_or_else(|| {
-            TableStoreError::Metadata(format!(
-                "relationship `{}` foreign key `{}` is not a target column",
-                spec.relationship.field_name, foreign_key
-            ))
-        })?;
-    let root_column = crate::table::column_name_for(root_schema, foreign_key)
-        .or_else(|| root_schema.primary_key.columns.first().cloned())
-        .ok_or_else(|| {
-            TableStoreError::Metadata(format!(
-                "relationship `{}` has no root key column",
-                spec.relationship.field_name
-            ))
-        })?;
-    let root_value = root_row.get(&root_column).ok_or_else(|| {
-        TableStoreError::Metadata(format!(
-            "read model `{}` root row is missing relationship key `{}`",
-            root_schema.model_name, root_column
-        ))
-    })?;
-
-    load_rows_matching_column(pool, &spec.target_schema, &target_column, root_value).await
-}
-
-async fn load_belongs_to_rows<DB>(
-    pool: &sqlx::Pool<DB>,
-    root_schema: &TableSchema,
-    root_row: &RowValues,
-    spec: &IncludeSpec,
-) -> Result<Vec<Versioned<RowValues>>, TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c sqlx::Pool<DB>: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    let foreign_key = spec.relationship.foreign_key.as_deref().ok_or_else(|| {
-        TableStoreError::Metadata(format!(
-            "relationship `{}` must declare a foreign key",
-            spec.relationship.field_name
-        ))
-    })?;
-    let source_column =
-        crate::table::column_name_for(root_schema, foreign_key).ok_or_else(|| {
-            TableStoreError::Metadata(format!(
-                "relationship `{}` foreign key `{}` is not a source column",
-                spec.relationship.field_name, foreign_key
-            ))
-        })?;
-    let target_column = belongs_to_target_column(&spec.target_schema, &source_column)?;
-    let source_value = root_row.get(&source_column).ok_or_else(|| {
-        TableStoreError::Metadata(format!(
-            "read model `{}` root row is missing relationship key `{}`",
-            root_schema.model_name, source_column
-        ))
-    })?;
-
-    load_rows_matching_column(pool, &spec.target_schema, &target_column, source_value).await
-}
-
-async fn load_rows_matching_column<DB>(
-    pool: &sqlx::Pool<DB>,
-    schema: &TableSchema,
-    column_name: &str,
-    value: &RowValue,
-) -> Result<Vec<Versioned<RowValues>>, TableStoreError>
-where
-    DB: SqlxReadModelBackend,
-    for<'c> &'c sqlx::Pool<DB>: Executor<'c, Database = DB>,
-    <DB as Database>::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
-{
-    let column = column_by_name(schema, column_name)?;
-    let mut builder = relational_row_select::<DB>(schema)?;
-    builder.push(" WHERE ");
-    builder.push(quote_identifier(column_name));
-    builder.push(" = ");
-    DB::push_row_value_bind(&mut builder, value.clone(), column)?;
-    push_order_by_primary_key(&mut builder, schema);
-
-    let rows = builder
-        .build()
-        .fetch_all(pool)
-        .await
-        .map_err(|err| read_model_storage_error(DB::BACKEND, "load relationship rows", err))?;
-
-    rows.iter()
-        .map(|row| row_to_versioned_values::<DB>(schema, row))
-        .collect()
-}
diff --git a/src/sqlx_repo/read_model/backend.rs b/src/sqlx_repo/read_model/backend.rs
new file mode 100644
index 00000000..085dbc30
--- /dev/null
+++ b/src/sqlx_repo/read_model/backend.rs
@@ -0,0 +1,61 @@
+use sqlx::{Database, Executor, QueryBuilder};
+
+use crate::table::{RowValue, TableColumn, TableStoreError};
+
+/// Dialect surface for the shared relational write path.
+///
+/// The upsert/patch/delete SQL is identical across Postgres and SQLite because
+/// `QueryBuilder<DB>` renders the right placeholder dialect; only two things
+/// genuinely differ: the value-binding for `Bool`/typed-`NULL` (Postgres binds
+/// native `bool` and needs explicit per-type `NULL` casts for `$N` inference;
+/// SQLite stores booleans as `i64` and collapses integer/bool `NULL`s) and the
+/// backend/storage labels used in numeric-conversion error messages. Those —
+/// and nothing else — live behind this trait, implemented once per backend.
+pub trait SqlxReadModelBackend: Database {
+    /// Backend name used in numeric-conversion error messages (`"postgres"`/`"sqlite"`).
+    const BACKEND: &'static str;
+    /// Human-readable storage label for the signed-64-bit version column.
+    const INTEGER_STORAGE: &'static str;
+
+    /// Bind one `RowValue` into the builder (dialect-specific encoding), then push
+    /// any required type cast (Postgres `::jsonb`/`::timestamptz`; SQLite none).
+    fn push_row_value_bind(
+        builder: &mut QueryBuilder<Self>,
+        value: RowValue,
+        column: &TableColumn,
+    ) -> Result<(), TableStoreError>;
+
+    /// Bind a typed `NULL` for the column's type (Postgres needs the concrete
+    /// `Option::<T>::None` per type so `$N` infers correctly).
+    fn push_null_bind(
+        builder: &mut QueryBuilder<Self>,
+        column: &TableColumn,
+    ) -> Result<(), TableStoreError>;
+
+    /// Affected-row count of a write result. `sqlx` exposes `rows_affected` only as
+    /// an inherent method on each backend's `QueryResult`, not via a shared trait,
+    /// so the one-line accessor is delegated here.
+    fn rows_affected(result: &Self::QueryResult) -> u64;
+
+    /// Render one `SELECT`-list column. Postgres casts JSON/Timestamp to `::text`
+    /// so they decode as `String`; SQLite stores them as text already, so it just
+    /// pushes the quoted column. (Reading is the inverse of `push_row_value_bind`.)
+    fn push_select_column(builder: &mut QueryBuilder<Self>, column: &TableColumn);
+
+    /// Decode one fetched column into a `RowValue`. The one genuinely dialect-
+    /// specific read: Postgres has a native `BOOLEAN`, SQLite stores booleans as
+    /// `INTEGER` and decodes `value != 0`.
+    fn row_value(row: &Self::Row, column: &TableColumn) -> Result<RowValue, TableStoreError>;
+
+    /// Emit a dialect-specific change notification inside an open transaction
+    /// (Postgres: `pg_notify`; default: no-op). Delivery happens on commit.
+    fn push_change_notify<'e, E>(
+        _executor: E,
+        _tables: &std::collections::BTreeSet<String>,
+    ) -> impl std::future::Future<Output = Result<(), TableStoreError>> + Send
+    where
+        E: Executor<'e, Database = Self> + Send,
+    {
+        async { Ok(()) }
+    }
+}
diff --git a/src/sqlx_repo/read_model/load.rs b/src/sqlx_repo/read_model/load.rs
new file mode 100644
index 00000000..1d9e6d0b
--- /dev/null
+++ b/src/sqlx_repo/read_model/load.rs
@@ -0,0 +1,222 @@
+use std::collections::BTreeMap;
+use std::sync::RwLock;
+
+use sqlx::{Database, Encode, Executor, IntoArguments, Type};
+
+use super::{
+    belongs_to_target_column, column_by_name, push_key_predicates, push_order_by_primary_key,
+    quote_identifier, relational_row_select, resolve_registered_read_model_schemas,
+    row_to_versioned_values, IncludeSpec, SqlxReadModelBackend,
+};
+use crate::read_model::{
+    ReadModelIncludeRows, ReadModelLoadGraph, ReadModelLoadRequest, ReadModelQueryCapabilities,
+    Versioned,
+};
+use crate::sqlx_repo::read_model_storage_error;
+use crate::table::{
+    validate_key, RelationshipKind, RowKey, RowValue, RowValues, TableSchema, TableSchemaRegistry,
+    TableStoreError,
+};
+
+pub(crate) async fn load_relational_row_by_key<DB>(
+    pool: &sqlx::Pool<DB>,
+    schema: &TableSchema,
+    key: &RowKey,
+) -> Result<Option<Versioned<RowValues>>, TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c sqlx::Pool<DB>: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    validate_key(schema, key)?;
+    let mut builder = relational_row_select::<DB>(schema)?;
+    push_key_predicates(&mut builder, schema, key)?;
+    let row = builder
+        .build()
+        .fetch_optional(pool)
+        .await
+        .map_err(|err| read_model_storage_error(DB::BACKEND, "load relational row", err))?;
+    row.map(|row| row_to_versioned_values::<DB>(schema, &row))
+        .transpose()
+}
+
+pub(crate) async fn load_relationship_rows<DB>(
+    pool: &sqlx::Pool<DB>,
+    root_schema: &TableSchema,
+    root_row: &RowValues,
+    spec: &IncludeSpec,
+) -> Result<Vec<Versioned<RowValues>>, TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c sqlx::Pool<DB>: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    match spec.relationship.kind {
+        RelationshipKind::HasMany => load_has_many_rows(pool, root_schema, root_row, spec).await,
+        RelationshipKind::BelongsTo => {
+            load_belongs_to_rows(pool, root_schema, root_row, spec).await
+        }
+        RelationshipKind::ManyToMany => Err(TableStoreError::Metadata(format!(
+            "many-to-many relationship `{}` includes are not supported yet",
+            spec.relationship.field_name
+        ))),
+    }
+}
+
+pub(crate) async fn load_read_model_graph<DB>(
+    pool: &sqlx::Pool<DB>,
+    schemas: &RwLock<TableSchemaRegistry>,
+    request: ReadModelLoadRequest,
+    capabilities: ReadModelQueryCapabilities,
+) -> Result<ReadModelLoadGraph, TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c sqlx::Pool<DB>: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    request.validate_for_query_capabilities(&capabilities)?;
+
+    let (root_schema, include_specs) = resolve_registered_read_model_schemas(schemas, &request)?;
+    validate_key(&root_schema, &request.key)?;
+
+    let Some(root) = load_relational_row_by_key(pool, &root_schema, &request.key).await? else {
+        return Ok(ReadModelLoadGraph::default());
+    };
+
+    let mut includes = BTreeMap::new();
+    for spec in include_specs {
+        let rows = load_relationship_rows(pool, &root_schema, &root.data, &spec).await?;
+        includes.insert(
+            spec.name,
+            ReadModelIncludeRows {
+                relationship: spec.relationship,
+                target_schema: spec.target_schema,
+                rows,
+            },
+        );
+    }
+
+    Ok(ReadModelLoadGraph {
+        root: Some(root),
+        includes,
+    })
+}
+
+async fn load_has_many_rows<DB>(
+    pool: &sqlx::Pool<DB>,
+    root_schema: &TableSchema,
+    root_row: &RowValues,
+    spec: &IncludeSpec,
+) -> Result<Vec<Versioned<RowValues>>, TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c sqlx::Pool<DB>: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    let foreign_key = spec.relationship.foreign_key.as_deref().ok_or_else(|| {
+        TableStoreError::Metadata(format!(
+            "relationship `{}` must declare a foreign key",
+            spec.relationship.field_name
+        ))
+    })?;
+    let target_column = crate::table::column_name_for(&spec.target_schema, foreign_key)
+        .ok_or_else(|| {
+            TableStoreError::Metadata(format!(
+                "relationship `{}` foreign key `{}` is not a target column",
+                spec.relationship.field_name, foreign_key
+            ))
+        })?;
+    let root_column = crate::table::column_name_for(root_schema, foreign_key)
+        .or_else(|| root_schema.primary_key.columns.first().cloned())
+        .ok_or_else(|| {
+            TableStoreError::Metadata(format!(
+                "relationship `{}` has no root key column",
+                spec.relationship.field_name
+            ))
+        })?;
+    let root_value = root_row.get(&root_column).ok_or_else(|| {
+        TableStoreError::Metadata(format!(
+            "read model `{}` root row is missing relationship key `{}`",
+            root_schema.model_name, root_column
+        ))
+    })?;
+
+    load_rows_matching_column(pool, &spec.target_schema, &target_column, root_value).await
+}
+
+async fn load_belongs_to_rows<DB>(
+    pool: &sqlx::Pool<DB>,
+    root_schema: &TableSchema,
+    root_row: &RowValues,
+    spec: &IncludeSpec,
+) -> Result<Vec<Versioned<RowValues>>, TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c sqlx::Pool<DB>: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    let foreign_key = spec.relationship.foreign_key.as_deref().ok_or_else(|| {
+        TableStoreError::Metadata(format!(
+            "relationship `{}` must declare a foreign key",
+            spec.relationship.field_name
+        ))
+    })?;
+    let source_column =
+        crate::table::column_name_for(root_schema, foreign_key).ok_or_else(|| {
+            TableStoreError::Metadata(format!(
+                "relationship `{}` foreign key `{}` is not a source column",
+                spec.relationship.field_name, foreign_key
+            ))
+        })?;
+    let target_column = belongs_to_target_column(&spec.target_schema, &source_column)?;
+    let source_value = root_row.get(&source_column).ok_or_else(|| {
+        TableStoreError::Metadata(format!(
+            "read model `{}` root row is missing relationship key `{}`",
+            root_schema.model_name, source_column
+        ))
+    })?;
+
+    load_rows_matching_column(pool, &spec.target_schema, &target_column, source_value).await
+}
+
+async fn load_rows_matching_column<DB>(
+    pool: &sqlx::Pool<DB>,
+    schema: &TableSchema,
+    column_name: &str,
+    value: &RowValue,
+) -> Result<Vec<Versioned<RowValues>>, TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c sqlx::Pool<DB>: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    let column = column_by_name(schema, column_name)?;
+    let mut builder = relational_row_select::<DB>(schema)?;
+    builder.push(" WHERE ");
+    builder.push(quote_identifier(column_name));
+    builder.push(" = ");
+    DB::push_row_value_bind(&mut builder, value.clone(), column)?;
+    push_order_by_primary_key(&mut builder, schema);
+
+    let rows = builder
+        .build()
+        .fetch_all(pool)
+        .await
+        .map_err(|err| read_model_storage_error(DB::BACKEND, "load relationship rows", err))?;
+
+    rows.iter()
+        .map(|row| row_to_versioned_values::<DB>(schema, row))
+        .collect()
+}
diff --git a/src/sqlx_repo/read_model/mod.rs b/src/sqlx_repo/read_model/mod.rs
new file mode 100644
index 00000000..7c8b9779
--- /dev/null
+++ b/src/sqlx_repo/read_model/mod.rs
@@ -0,0 +1,39 @@
+//! Backend-agnostic read-model logic shared by the Postgres and SQLite repositories.
+//!
+//! Two layers live here:
+//!
+//! 1. **Pure helpers** (no `sqlx` types): write-plan validation, key/patch
+//!    reconciliation, row-version arithmetic, relationship-include resolution.
+//! 2. **The generic relational write path**: free functions over
+//!    `DB: SqlxReadModelBackend` that build and run the upsert/patch/delete SQL via
+//!    `QueryBuilder<DB>`. Only the value-binding (`Bool`/typed-`NULL`), the
+//!    `rows_affected` accessor, and two label strings differ per dialect; the
+//!    [`SqlxReadModelBackend`] trait carries exactly those — one trait, two
+//!    one-line-per-method impls — so the SQL-building logic exists once rather than
+//!    being mirrored (and risking silent drift) in `postgres_repo`/`sqlite_repo`.
+
+mod backend;
+mod load;
+mod query;
+mod schema_registry;
+mod validation;
+mod write_plan;
+
+pub use backend::SqlxReadModelBackend;
+pub(crate) use load::load_read_model_graph;
+pub(crate) use query::{
+    push_key_predicates, push_order_by_primary_key, relational_row_select, row_to_versioned_values,
+};
+pub(crate) use schema_registry::{
+    remember_read_model_schemas, resolve_registered_read_model_schemas, IncludeSpec,
+};
+pub(crate) use validation::{
+    belongs_to_target_column, column_by_name, empty_string_as_none, initial_row_version,
+    patch_values_preserving_key, quote_identifier, row_concurrency_conflict,
+    row_values_from_key_and_patch, row_write_values, sql_read_model_capabilities,
+    validate_row_expected_version, validate_sql_write_plan, validate_values_match_key,
+    version_column,
+};
+pub(crate) use write_plan::{
+    apply_read_model_write_plan_in_tx, begin_read_model_tx, commit_read_model_tx, row_version_in_tx,
+};
diff --git a/src/sqlx_repo/read_model/query.rs b/src/sqlx_repo/read_model/query.rs
new file mode 100644
index 00000000..0a30bc2b
--- /dev/null
+++ b/src/sqlx_repo/read_model/query.rs
@@ -0,0 +1,96 @@
+use sqlx::{Database, Encode, QueryBuilder, Row, Type};
+
+use crate::read_model::Versioned;
+use crate::sqlx_repo::{read_model_storage_error, read_model_u64_from_i64};
+use crate::table::{RowKey, RowValues, TableSchema, TableStoreError};
+
+use super::{column_by_name, quote_identifier, version_column, SqlxReadModelBackend};
+
+pub(crate) fn push_key_predicates<DB: SqlxReadModelBackend>(
+    builder: &mut QueryBuilder<DB>,
+    schema: &TableSchema,
+    key: &RowKey,
+) -> Result<(), TableStoreError> {
+    builder.push(" WHERE ");
+    for (index, column_name) in schema.primary_key.columns.iter().enumerate() {
+        if index > 0 {
+            builder.push(" AND ");
+        }
+        let column = column_by_name(schema, column_name)?;
+        let value = key.get(column_name).cloned().ok_or_else(|| {
+            TableStoreError::Metadata(format!(
+                "read model `{}` row key is missing primary-key column `{}`",
+                schema.model_name, column_name
+            ))
+        })?;
+        builder.push(quote_identifier(column_name));
+        builder.push(" = ");
+        DB::push_row_value_bind(builder, value, column)?;
+    }
+    Ok(())
+}
+
+/// Build the shared `SELECT <columns>, <version> FROM <table>` prefix used by every
+/// relational read. Per-column rendering is dialect-specific (`push_select_column`).
+pub(crate) fn relational_row_select<DB: SqlxReadModelBackend>(
+    schema: &TableSchema,
+) -> Result<QueryBuilder<DB>, TableStoreError> {
+    let version_column = version_column(schema)?;
+    let mut builder = QueryBuilder::<DB>::new("SELECT ");
+    for (index, column) in schema.columns.iter().enumerate() {
+        if index > 0 {
+            builder.push(", ");
+        }
+        DB::push_select_column(&mut builder, column);
+    }
+    if !schema.columns.is_empty() {
+        builder.push(", ");
+    }
+    builder.push(quote_identifier(version_column));
+    builder.push(" FROM ");
+    builder.push(quote_identifier(&schema.table_name));
+    Ok(builder)
+}
+
+pub(crate) fn push_order_by_primary_key<DB: SqlxReadModelBackend>(
+    builder: &mut QueryBuilder<DB>,
+    schema: &TableSchema,
+) {
+    if schema.primary_key.columns.is_empty() {
+        return;
+    }
+    builder.push(" ORDER BY ");
+    for (index, column) in schema.primary_key.columns.iter().enumerate() {
+        if index > 0 {
+            builder.push(", ");
+        }
+        builder.push(quote_identifier(column));
+    }
+}
+
+pub(crate) fn row_to_versioned_values<DB>(
+    schema: &TableSchema,
+    row: &DB::Row,
+) -> Result<Versioned<RowValues>, TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    let mut values = RowValues::new();
+    for column in &schema.columns {
+        values.insert(column.column_name.clone(), DB::row_value(row, column)?);
+    }
+    let version_column = version_column(schema)?;
+    let version = read_model_u64_from_i64(
+        DB::BACKEND,
+        row.try_get::<i64, _>(version_column).map_err(|err| {
+            read_model_storage_error(DB::BACKEND, "decode relational row version", err)
+        })?,
+        version_column,
+    )?;
+    Ok(Versioned {
+        data: values,
+        version,
+    })
+}
diff --git a/src/sqlx_repo/read_model/schema_registry.rs b/src/sqlx_repo/read_model/schema_registry.rs
new file mode 100644
index 00000000..102464b5
--- /dev/null
+++ b/src/sqlx_repo/read_model/schema_registry.rs
@@ -0,0 +1,103 @@
+use std::sync::RwLock;
+
+use crate::read_model::ReadModelLoadRequest;
+use crate::table::{
+    RelationshipDef, RelationshipKind, TableSchema, TableSchemaRegistry, TableStoreError,
+};
+
+/// A resolved relationship include: the relationship metadata plus the registered
+/// schema of the target model, ready for the relational load path to query.
+#[derive(Clone)]
+pub(crate) struct IncludeSpec {
+    pub(crate) name: String,
+    pub(crate) relationship: RelationshipDef,
+    pub(crate) target_schema: TableSchema,
+}
+
+pub(crate) fn remember_read_model_schemas(
+    stored: &RwLock<TableSchemaRegistry>,
+    registry: &TableSchemaRegistry,
+) -> Result<(), TableStoreError> {
+    let mut stored = stored
+        .write()
+        .map_err(|_| TableStoreError::Storage("read-model schema registry lock poisoned".into()))?;
+
+    for schema in registry.schemas() {
+        if let Some(existing) = stored.schema_for_table(&schema.table_name) {
+            if existing != schema {
+                return Err(TableStoreError::Metadata(format!(
+                    "read-model schema registry already contains table `{}` with different metadata",
+                    schema.table_name
+                )));
+            }
+            continue;
+        }
+        stored.register_schema(schema.clone())?;
+    }
+
+    Ok(())
+}
+
+pub(crate) fn resolve_registered_read_model_schemas(
+    registry: &RwLock<TableSchemaRegistry>,
+    request: &ReadModelLoadRequest,
+) -> Result<(TableSchema, Vec<IncludeSpec>), TableStoreError> {
+    if request.includes.is_empty() {
+        return Ok((request.schema.clone(), Vec::new()));
+    }
+
+    let registry = registry
+        .read()
+        .map_err(|_| TableStoreError::Storage("read-model schema registry lock poisoned".into()))?;
+    let root_schema = registry
+        .schema_for_model(&request.schema.model_name)
+        .cloned()
+        .ok_or_else(|| {
+            TableStoreError::Metadata(format!(
+                "read model `{}` is not registered for relationship includes",
+                request.schema.model_name
+            ))
+        })?;
+    if root_schema != request.schema {
+        return Err(TableStoreError::Metadata(format!(
+            "read model `{}` load request does not match registered schema",
+            request.schema.model_name
+        )));
+    }
+
+    let mut include_specs = Vec::with_capacity(request.includes.len());
+    for include_name in &request.includes {
+        let relationship = root_schema
+            .relationships
+            .iter()
+            .find(|relationship| relationship.field_name == *include_name)
+            .ok_or_else(|| {
+                TableStoreError::Metadata(format!(
+                    "read model `{}` has no relationship `{}`",
+                    root_schema.model_name, include_name
+                ))
+            })?;
+        if matches!(relationship.kind, RelationshipKind::ManyToMany) {
+            return Err(TableStoreError::Metadata(format!(
+                "many-to-many relationship `{}` includes are not supported by the ORM include loader (join metadata may declare source and target keys; the GraphQL engine traverses m2m independently)",
+                relationship.field_name
+            )));
+        }
+        let target_schema = registry
+            .schema_for_model(&relationship.target_model)
+            .ok_or_else(|| {
+                TableStoreError::Metadata(format!(
+                    "read model `{}` relationship `{}` targets unregistered model `{}`",
+                    root_schema.model_name, relationship.field_name, relationship.target_model
+                ))
+            })?;
+
+        include_specs.push(IncludeSpec {
+            name: include_name.clone(),
+            relationship: relationship.clone(),
+            target_schema: target_schema.clone(),
+        });
+    }
+
+    Ok((root_schema, include_specs))
+}
diff --git a/src/sqlx_repo/read_model/validation.rs b/src/sqlx_repo/read_model/validation.rs
new file mode 100644
index 00000000..d4c6c95d
--- /dev/null
+++ b/src/sqlx_repo/read_model/validation.rs
@@ -0,0 +1,210 @@
+use crate::table::{
+    key_fingerprint, validate_row_values, ExpectedVersion, RowKey, RowValue, RowValues,
+    TableAdapterCapabilities, TableColumn, TableSchema, TableStoreError, TableWritePlan,
+};
+
+pub(crate) fn sql_read_model_capabilities() -> TableAdapterCapabilities {
+    TableAdapterCapabilities {
+        relational_rows: true,
+        sparse_patches: true,
+        deletes: true,
+    }
+}
+
+pub(crate) fn validate_sql_write_plan(plan: &TableWritePlan) -> Result<(), TableStoreError> {
+    plan.validate_for(&sql_read_model_capabilities())
+}
+
+pub(crate) fn initial_row_version() -> u64 {
+    1
+}
+
+pub(crate) fn validate_row_expected_version(
+    schema: &TableSchema,
+    key: &RowKey,
+    expected_version: &ExpectedVersion,
+    current_version: Option<u64>,
+) -> Result<(), TableStoreError> {
+    match (expected_version, current_version) {
+        (ExpectedVersion::Any, _) => Ok(()),
+        (ExpectedVersion::Exact(expected), Some(actual)) if expected == &actual => Ok(()),
+        (ExpectedVersion::Exact(expected), Some(actual)) => {
+            Err(row_concurrency_conflict(schema, key, *expected, actual))
+        }
+        (ExpectedVersion::Exact(_), None) => Err(TableStoreError::NotFound {
+            collection: schema.table_name.clone(),
+            id: key_fingerprint(key),
+        }),
+        (ExpectedVersion::NotExists, None) => Ok(()),
+        (ExpectedVersion::NotExists, Some(actual)) => {
+            Err(row_concurrency_conflict(schema, key, 0, actual))
+        }
+    }
+}
+
+pub(crate) fn row_concurrency_conflict(
+    schema: &TableSchema,
+    key: &RowKey,
+    expected: u64,
+    actual: u64,
+) -> TableStoreError {
+    TableStoreError::ConcurrencyConflict {
+        collection: schema.table_name.clone(),
+        id: key_fingerprint(key),
+        expected,
+        actual,
+    }
+}
+
+pub(crate) fn row_values_from_key_and_patch(
+    schema: &TableSchema,
+    key: &RowKey,
+    patch: crate::table::RowPatch,
+) -> Result<RowValues, TableStoreError> {
+    let mut values = RowValues::new();
+    for (column, value) in key.iter() {
+        values.insert(column.to_string(), value.clone());
+    }
+    for (column, value) in patch.into_values() {
+        if schema
+            .primary_key
+            .columns
+            .iter()
+            .any(|primary_key| primary_key == &column)
+        {
+            let key_value = key.get(&column).ok_or_else(|| {
+                TableStoreError::Metadata(format!(
+                    "read model `{}` row key is missing primary-key column `{}`",
+                    schema.model_name, column
+                ))
+            })?;
+            if key_value != &value {
+                return Err(TableStoreError::Metadata(format!(
+                    "read model `{}` patch cannot change primary-key column `{}`",
+                    schema.model_name, column
+                )));
+            }
+        }
+        values.insert(column, value);
+    }
+    validate_row_values(schema, &values, true)?;
+    validate_values_match_key(schema, key, &values)?;
+    Ok(values)
+}
+
+pub(crate) fn patch_values_preserving_key<'schema>(
+    schema: &'schema TableSchema,
+    key: &RowKey,
+    patch: &crate::table::RowPatch,
+) -> Result<Vec<(&'schema TableColumn, RowValue)>, TableStoreError> {
+    let mut values = Vec::new();
+    for (column_name, value) in patch.iter() {
+        let column = column_by_name(schema, column_name)?;
+        if column.primary_key {
+            let key_value = key.get(column_name).ok_or_else(|| {
+                TableStoreError::Metadata(format!(
+                    "read model `{}` row key is missing primary-key column `{}`",
+                    schema.model_name, column_name
+                ))
+            })?;
+            if key_value != value {
+                return Err(TableStoreError::Metadata(format!(
+                    "read model `{}` patch cannot change primary-key column `{}`",
+                    schema.model_name, column_name
+                )));
+            }
+            continue;
+        }
+        values.push((column, value.clone()));
+    }
+    Ok(values)
+}
+
+pub(crate) fn validate_values_match_key(
+    schema: &TableSchema,
+    key: &RowKey,
+    values: &RowValues,
+) -> Result<(), TableStoreError> {
+    for column in &schema.primary_key.columns {
+        let key_value = key.get(column).ok_or_else(|| {
+            TableStoreError::Metadata(format!(
+                "read model `{}` row key is missing primary-key column `{}`",
+                schema.model_name, column
+            ))
+        })?;
+        let row_value = values.get(column).ok_or_else(|| {
+            TableStoreError::Metadata(format!(
+                "read model `{}` row is missing primary-key column `{}`",
+                schema.model_name, column
+            ))
+        })?;
+        if row_value != key_value {
+            return Err(TableStoreError::Metadata(format!(
+                "read model `{}` row values cannot change primary-key column `{}`",
+                schema.model_name, column
+            )));
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn belongs_to_target_column(
+    target_schema: &TableSchema,
+    source_column: &str,
+) -> Result<String, TableStoreError> {
+    if target_schema.primary_key.columns.len() != 1 {
+        return Err(TableStoreError::Metadata(format!(
+            "belongs_to target `{}` must have a single-column primary key to load from `{}`",
+            target_schema.model_name, source_column
+        )));
+    }
+
+    Ok(target_schema.primary_key.columns[0].clone())
+}
+
+pub(crate) fn empty_string_as_none(value: &str) -> Option<&str> {
+    if value.is_empty() {
+        None
+    } else {
+        Some(value)
+    }
+}
+
+pub(crate) fn row_write_values<'schema>(
+    schema: &'schema TableSchema,
+    values: &RowValues,
+) -> Result<Vec<(&'schema TableColumn, RowValue)>, TableStoreError> {
+    values
+        .iter()
+        .map(|(column_name, value)| Ok((column_by_name(schema, column_name)?, value.clone())))
+        .collect()
+}
+
+pub(crate) fn column_by_name<'schema>(
+    schema: &'schema TableSchema,
+    column_name: &str,
+) -> Result<&'schema TableColumn, TableStoreError> {
+    schema
+        .columns
+        .iter()
+        .find(|column| column.column_name == column_name)
+        .ok_or_else(|| {
+            TableStoreError::Metadata(format!(
+                "read model `{}` write references missing column `{}`",
+                schema.model_name, column_name
+            ))
+        })
+}
+
+pub(crate) fn version_column(schema: &TableSchema) -> Result<&str, TableStoreError> {
+    schema.version_column.as_deref().ok_or_else(|| {
+        TableStoreError::Metadata(format!(
+            "read model `{}` requires a version column for SQL write-plan persistence",
+            schema.model_name
+        ))
+    })
+}
+
+pub(crate) fn quote_identifier(value: &str) -> String {
+    format!("\"{}\"", value.replace('"', "\"\""))
+}
diff --git a/src/sqlx_repo/read_model/write_plan.rs b/src/sqlx_repo/read_model/write_plan.rs
new file mode 100644
index 00000000..ea5d99d8
--- /dev/null
+++ b/src/sqlx_repo/read_model/write_plan.rs
@@ -0,0 +1,586 @@
+use sqlx::{Database, Encode, Executor, IntoArguments, QueryBuilder, Row, Transaction, Type};
+
+use super::{
+    initial_row_version, patch_values_preserving_key, push_key_predicates, quote_identifier,
+    row_concurrency_conflict, row_values_from_key_and_patch, row_write_values,
+    validate_row_expected_version, validate_sql_write_plan, validate_values_match_key,
+    version_column, SqlxReadModelBackend,
+};
+use crate::sqlx_repo::{
+    read_model_i64_from_u64, read_model_storage_error, read_model_u64_from_i64,
+};
+use crate::table::{
+    key_fingerprint, validate_key, validate_row_values, DeleteTableRowMutation, ExpectedVersion,
+    PatchMode, PatchTableRowMutation, RowKey, RowValue, RowValues, RowWriteMode, TableColumn,
+    TableCommitOutcome, TableMutation, TableRowMutation, TableSchema, TableStoreError,
+    TableWritePlan,
+};
+
+pub(crate) async fn begin_read_model_tx<DB: SqlxReadModelBackend>(
+    pool: &sqlx::Pool<DB>,
+) -> Result<Transaction<'_, DB>, TableStoreError> {
+    pool.begin()
+        .await
+        .map_err(|err| read_model_storage_error(DB::BACKEND, "begin transaction", err))
+}
+
+pub(crate) async fn commit_read_model_tx<DB: SqlxReadModelBackend>(
+    tx: Transaction<'_, DB>,
+) -> Result<(), TableStoreError> {
+    tx.commit()
+        .await
+        .map_err(|err| read_model_storage_error(DB::BACKEND, "commit transaction", err))
+}
+
+/// Full pool→tx→commit helper kept for adapter authors; production paths use the
+/// split begin/apply/commit helpers above.
+#[allow(dead_code)]
+pub(crate) async fn commit_read_model_write_plan<DB>(
+    pool: &sqlx::Pool<DB>,
+    plan: TableWritePlan,
+    notify_enabled: bool,
+) -> Result<TableCommitOutcome, TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    validate_sql_write_plan(&plan)?;
+    let tables: std::collections::BTreeSet<String> = plan
+        .mutations
+        .iter()
+        .map(|m| m.table_name().to_string())
+        .collect();
+    let mut tx = begin_read_model_tx(pool).await?;
+    let outcome = apply_read_model_write_plan_in_tx(&mut tx, plan).await?;
+    if notify_enabled && !tables.is_empty() {
+        DB::push_change_notify(&mut *tx, &tables).await?;
+    }
+    commit_read_model_tx(tx).await?;
+    Ok(outcome)
+}
+
+pub(crate) async fn apply_read_model_write_plan_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    plan: TableWritePlan,
+) -> Result<TableCommitOutcome, TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    validate_sql_write_plan(&plan)?;
+
+    for mutation in plan.mutations {
+        match mutation {
+            TableMutation::UpsertRow(mutation) => {
+                upsert_relational_row_in_tx(tx, mutation).await?;
+            }
+            TableMutation::PatchRow(mutation) => {
+                patch_relational_row_in_tx(tx, mutation).await?;
+            }
+            TableMutation::DeleteRow(mutation) => {
+                delete_relational_row_in_tx(tx, mutation).await?;
+            }
+        }
+    }
+
+    Ok(TableCommitOutcome::applied())
+}
+
+pub(crate) async fn upsert_relational_row_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    mutation: TableRowMutation,
+) -> Result<(), TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    validate_key(mutation.schema, &mutation.key)?;
+    validate_row_values(mutation.schema, &mutation.values, true)?;
+    validate_values_match_key(mutation.schema, &mutation.key, &mutation.values)?;
+
+    // The common case — upsert without an optimistic-version check — is a single
+    // `INSERT ... ON CONFLICT (pk) DO UPDATE` round trip. Only version-checked
+    // writes need to observe the current row first.
+    if matches!(mutation.mode, RowWriteMode::Upsert)
+        && matches!(mutation.expected_version, ExpectedVersion::Any)
+    {
+        return upsert_relational_row_on_conflict_in_tx(tx, mutation.schema, &mutation.values)
+            .await;
+    }
+
+    let current_version = row_version_in_tx(tx, mutation.schema, &mutation.key).await?;
+    validate_row_expected_version(
+        mutation.schema,
+        &mutation.key,
+        &mutation.expected_version,
+        current_version,
+    )?;
+    if matches!(mutation.mode, RowWriteMode::Insert) && current_version.is_some() {
+        return Err(row_concurrency_conflict(
+            mutation.schema,
+            &mutation.key,
+            0,
+            current_version.unwrap_or_default(),
+        ));
+    }
+
+    match current_version {
+        Some(expected_version) => {
+            let rows_affected = update_relational_row_values_in_tx(
+                tx,
+                mutation.schema,
+                &mutation.key,
+                &mutation.values,
+                Some(expected_version),
+            )
+            .await?;
+            if rows_affected == 0 {
+                let actual = row_version_in_tx(tx, mutation.schema, &mutation.key)
+                    .await?
+                    .unwrap_or(expected_version);
+                return Err(row_concurrency_conflict(
+                    mutation.schema,
+                    &mutation.key,
+                    expected_version,
+                    actual,
+                ));
+            }
+        }
+        None => {
+            insert_relational_row_in_tx(
+                tx,
+                mutation.schema,
+                &mutation.values,
+                initial_row_version(),
+            )
+            .await?;
+        }
+    }
+
+    Ok(())
+}
+
+pub(crate) async fn patch_relational_row_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    mutation: PatchTableRowMutation,
+) -> Result<(), TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    validate_key(mutation.schema, &mutation.key)?;
+
+    // `NotExists` is the only shape that has to observe the row before writing;
+    // `Any`/`Exact` run the UPDATE directly and only re-read on a miss to tell
+    // "not found" apart from a version conflict.
+    if matches!(mutation.expected_version, ExpectedVersion::NotExists) {
+        let current_version = row_version_in_tx(tx, mutation.schema, &mutation.key).await?;
+        validate_row_expected_version(
+            mutation.schema,
+            &mutation.key,
+            &mutation.expected_version,
+            current_version,
+        )?;
+        if !matches!(mutation.mode, PatchMode::InsertMissing) {
+            return Err(TableStoreError::NotFound {
+                collection: mutation.schema.table_name.clone(),
+                id: key_fingerprint(&mutation.key),
+            });
+        }
+        let values = row_values_from_key_and_patch(mutation.schema, &mutation.key, mutation.patch)?;
+        return insert_relational_row_in_tx(tx, mutation.schema, &values, initial_row_version())
+            .await;
+    }
+
+    let expected_version = match mutation.expected_version {
+        ExpectedVersion::Exact(expected) => Some(expected),
+        _ => None,
+    };
+    let patch_values =
+        patch_values_preserving_key(mutation.schema, &mutation.key, &mutation.patch)?;
+    let rows_affected = update_relational_columns_in_tx(
+        tx,
+        mutation.schema,
+        &mutation.key,
+        patch_values,
+        expected_version,
+    )
+    .await?;
+    if rows_affected == 0 {
+        if let Some(expected_version) = expected_version {
+            return match row_version_in_tx(tx, mutation.schema, &mutation.key).await? {
+                Some(actual) => Err(row_concurrency_conflict(
+                    mutation.schema,
+                    &mutation.key,
+                    expected_version,
+                    actual,
+                )),
+                None => Err(TableStoreError::NotFound {
+                    collection: mutation.schema.table_name.clone(),
+                    id: key_fingerprint(&mutation.key),
+                }),
+            };
+        }
+        if matches!(mutation.mode, PatchMode::InsertMissing) {
+            let values =
+                row_values_from_key_and_patch(mutation.schema, &mutation.key, mutation.patch)?;
+            insert_relational_row_in_tx(tx, mutation.schema, &values, initial_row_version())
+                .await?;
+        } else {
+            return Err(TableStoreError::NotFound {
+                collection: mutation.schema.table_name.clone(),
+                id: key_fingerprint(&mutation.key),
+            });
+        }
+    }
+
+    Ok(())
+}
+
+pub(crate) async fn delete_relational_row_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    mutation: DeleteTableRowMutation,
+) -> Result<(), TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    validate_key(mutation.schema, &mutation.key)?;
+
+    match mutation.expected_version {
+        // The row must not exist: nothing to delete, but surface a conflict if it does.
+        ExpectedVersion::NotExists => {
+            let current_version = row_version_in_tx(tx, mutation.schema, &mutation.key).await?;
+            validate_row_expected_version(
+                mutation.schema,
+                &mutation.key,
+                &mutation.expected_version,
+                current_version,
+            )?;
+            Ok(())
+        }
+        // No version check: one DELETE; deleting a missing row is a no-op.
+        ExpectedVersion::Any => {
+            delete_relational_row_where_version_in_tx(tx, mutation.schema, &mutation.key, None)
+                .await?;
+            Ok(())
+        }
+        // Version-checked delete: only re-read on a miss to tell "not found"
+        // apart from a version conflict.
+        ExpectedVersion::Exact(expected_version) => {
+            let rows_affected = delete_relational_row_where_version_in_tx(
+                tx,
+                mutation.schema,
+                &mutation.key,
+                Some(expected_version),
+            )
+            .await?;
+            if rows_affected == 0 {
+                return match row_version_in_tx(tx, mutation.schema, &mutation.key).await? {
+                    Some(actual) => Err(row_concurrency_conflict(
+                        mutation.schema,
+                        &mutation.key,
+                        expected_version,
+                        actual,
+                    )),
+                    None => Err(TableStoreError::NotFound {
+                        collection: mutation.schema.table_name.clone(),
+                        id: key_fingerprint(&mutation.key),
+                    }),
+                };
+            }
+            Ok(())
+        }
+    }
+}
+
+pub(crate) async fn row_version_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    schema: &TableSchema,
+    key: &RowKey,
+) -> Result<Option<u64>, TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    let version_column = version_column(schema)?;
+    let mut builder = QueryBuilder::<DB>::new("SELECT ");
+    builder.push(quote_identifier(version_column));
+    builder.push(" FROM ");
+    builder.push(quote_identifier(&schema.table_name));
+    push_key_predicates(&mut builder, schema, key)?;
+
+    let row = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|err| read_model_storage_error(DB::BACKEND, "load relational row version", err))?;
+
+    row.map(|row| {
+        read_model_u64_from_i64(
+            DB::BACKEND,
+            row.try_get::<i64, _>(version_column).map_err(|err| {
+                read_model_storage_error(DB::BACKEND, "decode relational row version", err)
+            })?,
+            version_column,
+        )
+    })
+    .transpose()
+}
+
+pub(crate) async fn insert_relational_row_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    schema: &TableSchema,
+    values: &RowValues,
+    version: u64,
+) -> Result<(), TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    let version_column = version_column(schema)?;
+    let write_values = row_write_values(schema, values)?;
+    let has_write_values = !write_values.is_empty();
+    let mut builder = QueryBuilder::<DB>::new("INSERT INTO ");
+    builder.push(quote_identifier(&schema.table_name));
+    builder.push(" (");
+    for (index, (column, _)) in write_values.iter().enumerate() {
+        if index > 0 {
+            builder.push(", ");
+        }
+        builder.push(quote_identifier(&column.column_name));
+    }
+    if has_write_values {
+        builder.push(", ");
+    }
+    builder.push(quote_identifier(version_column));
+    builder.push(") VALUES (");
+    for (index, (column, value)) in write_values.into_iter().enumerate() {
+        if index > 0 {
+            builder.push(", ");
+        }
+        DB::push_row_value_bind(&mut builder, value, column)?;
+    }
+    if has_write_values {
+        builder.push(", ");
+    }
+    builder.push_bind(read_model_i64_from_u64(
+        DB::BACKEND,
+        version,
+        version_column,
+        DB::INTEGER_STORAGE,
+    )?);
+    builder.push(")");
+
+    builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|err| read_model_storage_error(DB::BACKEND, "insert relational row", err))?;
+
+    Ok(())
+}
+
+/// Upsert one row in a single statement: `INSERT ... ON CONFLICT (pk) DO UPDATE
+/// SET <non-pk columns> = excluded.<column>, <version> = <version> + 1`.
+///
+/// Both Postgres and SQLite (≥ 3.35) support `ON CONFLICT` with an explicit
+/// column-list target and the `excluded` pseudo-table. New rows start at
+/// version 1; conflicting rows bump their version in-database (an increment
+/// past `i64::MAX` fails as a storage error).
+pub(crate) async fn upsert_relational_row_on_conflict_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    schema: &TableSchema,
+    values: &RowValues,
+) -> Result<(), TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    let version_column = version_column(schema)?;
+    let write_values = row_write_values(schema, values)?;
+    let mut builder = QueryBuilder::<DB>::new("INSERT INTO ");
+    builder.push(quote_identifier(&schema.table_name));
+    builder.push(" (");
+    for (column, _) in &write_values {
+        builder.push(quote_identifier(&column.column_name));
+        builder.push(", ");
+    }
+    builder.push(quote_identifier(version_column));
+    builder.push(") VALUES (");
+    for (column, value) in write_values.iter().cloned() {
+        DB::push_row_value_bind(&mut builder, value, column)?;
+        builder.push(", ");
+    }
+    builder.push_bind(read_model_i64_from_u64(
+        DB::BACKEND,
+        initial_row_version(),
+        version_column,
+        DB::INTEGER_STORAGE,
+    )?);
+    builder.push(") ON CONFLICT (");
+    for (index, column_name) in schema.primary_key.columns.iter().enumerate() {
+        if index > 0 {
+            builder.push(", ");
+        }
+        builder.push(quote_identifier(column_name));
+    }
+    builder.push(") DO UPDATE SET ");
+    for (column, _) in write_values
+        .iter()
+        .filter(|(column, _)| !column.primary_key)
+    {
+        builder.push(quote_identifier(&column.column_name));
+        builder.push(" = excluded.");
+        builder.push(quote_identifier(&column.column_name));
+        builder.push(", ");
+    }
+    // Qualify the existing-row reference with the table name: inside `DO UPDATE`
+    // an unqualified column is ambiguous with `excluded` on Postgres.
+    builder.push(quote_identifier(version_column));
+    builder.push(" = ");
+    builder.push(quote_identifier(&schema.table_name));
+    builder.push(".");
+    builder.push(quote_identifier(version_column));
+    builder.push(" + 1");
+
+    builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|err| read_model_storage_error(DB::BACKEND, "upsert relational row", err))?;
+
+    Ok(())
+}
+
+pub(crate) async fn update_relational_row_values_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    schema: &TableSchema,
+    key: &RowKey,
+    values: &RowValues,
+    expected_version: Option<u64>,
+) -> Result<u64, TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    let mut write_values = row_write_values(schema, values)?;
+    write_values.retain(|(column, _)| !column.primary_key);
+    update_relational_columns_in_tx(tx, schema, key, write_values, expected_version).await
+}
+
+/// `UPDATE <table> SET <columns>, <version> = <version> + 1 WHERE <pk> [AND
+/// <version> = <expected>]`, returning the affected-row count. The version bump
+/// happens in-database; an increment past `i64::MAX` fails as a storage error.
+pub(crate) async fn update_relational_columns_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    schema: &TableSchema,
+    key: &RowKey,
+    write_values: Vec<(&TableColumn, RowValue)>,
+    expected_version: Option<u64>,
+) -> Result<u64, TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    let version_column = version_column(schema)?;
+    let mut builder = QueryBuilder::<DB>::new("UPDATE ");
+    builder.push(quote_identifier(&schema.table_name));
+    builder.push(" SET ");
+    for (column, value) in write_values {
+        builder.push(quote_identifier(&column.column_name));
+        builder.push(" = ");
+        DB::push_row_value_bind(&mut builder, value, column)?;
+        builder.push(", ");
+    }
+    builder.push(quote_identifier(version_column));
+    builder.push(" = ");
+    builder.push(quote_identifier(version_column));
+    builder.push(" + 1");
+    push_key_predicates(&mut builder, schema, key)?;
+    if let Some(expected_version) = expected_version {
+        builder.push(" AND ");
+        builder.push(quote_identifier(version_column));
+        builder.push(" = ");
+        builder.push_bind(read_model_i64_from_u64(
+            DB::BACKEND,
+            expected_version,
+            "expected version",
+            DB::INTEGER_STORAGE,
+        )?);
+    }
+
+    let result = builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|err| read_model_storage_error(DB::BACKEND, "update relational row", err))?;
+    Ok(DB::rows_affected(&result))
+}
+
+pub(crate) async fn delete_relational_row_where_version_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    schema: &TableSchema,
+    key: &RowKey,
+    expected_version: Option<u64>,
+) -> Result<u64, TableStoreError>
+where
+    DB: SqlxReadModelBackend,
+    for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>,
+    <DB as Database>::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<<DB as Database>::Row>,
+{
+    let mut builder = QueryBuilder::<DB>::new("DELETE FROM ");
+    builder.push(quote_identifier(&schema.table_name));
+    push_key_predicates(&mut builder, schema, key)?;
+    if let Some(version) = expected_version {
+        let version_column = version_column(schema)?;
+        builder.push(" AND ");
+        builder.push(quote_identifier(version_column));
+        builder.push(" = ");
+        builder.push_bind(read_model_i64_from_u64(
+            DB::BACKEND,
+            version,
+            "expected version",
+            DB::INTEGER_STORAGE,
+        )?);
+    }
+
+    let result = builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|err| read_model_storage_error(DB::BACKEND, "delete relational row", err))?;
+    Ok(DB::rows_affected(&result))
+}
diff --git a/src/sqlx_repo/repo.rs b/src/sqlx_repo/repo.rs
deleted file mode 100644
index 200f5c60..00000000
--- a/src/sqlx_repo/repo.rs
+++ /dev/null
@@ -1,1862 +0,0 @@
-//! Backend-agnostic event-store, snapshot, outbox, and inbox logic shared by
-//! the Postgres and SQLite repositories.
-//!
-//! This extends the [`SqlxReadModelBackend`](super::read_model::SqlxReadModelBackend)
-//! pattern to the whole repository surface: the SQL statements and row codecs
-//! are identical across the two backends because `QueryBuilder<DB>` renders the
-//! right placeholder dialect. What genuinely differs — schema SQL, bind-param
-//! chunking, the timestamp codec (Postgres epoch-`f64`/`to_timestamp()` vs
-//! SQLite `"secs.nanos"` text), the unique-violation predicate, conflict
-//! recovery (SQLite can re-read in the failed transaction; a failed Postgres
-//! statement aborts it), and the outbox `claim` strategy — lives behind the
-//! [`SqlxRepoBackend`] trait, implemented once per backend.
-
-#![expect(
-    clippy::manual_async_fn,
-    reason = "async trait impls return impl Future + Send to preserve public Send bounds"
-)]
-
-use std::borrow::Cow;
-use std::collections::{BTreeMap, HashMap};
-use std::future::Future;
-use std::sync::{Arc, RwLock};
-use std::time::{Duration, SystemTime, UNIX_EPOCH};
-
-use sqlx::migrate::{Migrate, Migration, MigrationType, Migrator};
-use sqlx::pool::PoolOptions;
-use sqlx::query_builder::Separated;
-use sqlx::{Encode, Executor, IntoArguments, Pool, QueryBuilder, Row, Transaction, Type};
-
-use crate::entity::{Entity, EventRecord, BITCODE_PAYLOAD_CODEC};
-use crate::outbox::{OutboxMessage, OutboxMessageStatus};
-use crate::outbox_worker::{
-    ensure_active_claim, ClaimOutboxMessages, OutboxBacklogStats, OutboxClaimRef, OutboxStore,
-};
-use crate::read_model::{ReadModelLoadGraph, ReadModelLoadRequest, ReadModelQueryCapabilities};
-use crate::repository::{
-    validate_commit_batch, validate_snapshot_identity, validate_supported_event_codec, CommitBatch,
-    GetStream, InboxReceipt, InboxStore, PreparedEventAppend, ReadModelWritePlanStore,
-    RelationalReadModelQueryStore, RepositoryError, SnapshotStore, SnapshotWrite, StreamIdentity,
-    TransactionalCommit,
-};
-use crate::snapshot::SnapshotRecord;
-use crate::sqlx_repo::read_model::{
-    apply_read_model_write_plan_in_tx, commit_read_model_write_plan, empty_string_as_none,
-    load_read_model_graph, remember_read_model_schemas, sql_read_model_capabilities,
-    validate_sql_write_plan, SqlxReadModelBackend,
-};
-use crate::sqlx_repo::{
-    audited_table_schema_sql, deserialize_event_metadata, repository_i64_from_u64,
-    repository_u16_from_i64, repository_u64_from_i64, serialize_event_metadata,
-};
-use crate::table::{
-    generate_table_migration_artifacts, table_schema_bootstrap_result, table_schema_statements,
-    TableMigrationArtifact, TableSchemaBootstrap, TableSchemaRegistry, TableSqlDialect,
-    TableSqlSchemaAdapter, TableStoreError,
-};
-use crate::table::{
-    TableAdapterCapabilities as ReadModelAdapterCapabilities,
-    TableCommitOutcome as ReadModelCommitOutcome, TableStoreError as ReadModelError,
-    TableWritePlan as ReadModelWritePlan,
-};
-
-/// Build an embedded migrator from statically included migration files
-/// (`(version, description, sql)` per file, in order). sqlx's `migrate!`
-/// macro would assemble this at compile time but drags in the whole
-/// proc-macro stack; here the checksums are computed once at first use, so
-/// keep each backend's list in sync with its `migrations/` directory.
-pub(crate) fn embedded_migrator(files: &[(i64, &'static str, &'static str)]) -> Migrator {
-    Migrator::with_migrations(
-        files
-            .iter()
-            .map(|&(version, description, sql)| {
-                Migration::new(
-                    version,
-                    description.into(),
-                    MigrationType::Simple,
-                    sqlx::SqlSafeStr::into_sql_str(sql),
-                    false,
-                )
-            })
-            .collect(),
-    )
-}
-
-/// Group stream identities by aggregate type so each type is one id-list
-/// round trip instead of a query per identity. Callers issue single-type
-/// batches in the common case, so this usually yields one group; the grouping
-/// only exists to keep arbitrary mixed-type inputs correct.
-fn ids_by_type(identities: &[StreamIdentity]) -> BTreeMap<&str, Vec<&str>> {
-    let mut groups: BTreeMap<&str, Vec<&str>> = BTreeMap::new();
-    for identity in identities {
-        groups
-            .entry(identity.aggregate_type())
-            .or_default()
-            .push(identity.aggregate_id());
-    }
-    groups
-}
-
-/// Bound parameters per `aggregate_events` row.
-const EVENT_BIND_COLUMNS: usize = 10;
-
-/// Bound parameters per `outbox_messages` row.
-const OUTBOX_BIND_COLUMNS: usize = 19;
-
-/// Dialect surface for the shared repository path (event store, snapshots,
-/// outbox lifecycle, consumer inbox, schema bootstrap).
-///
-/// Everything the two SQL backends genuinely disagree on is an item here; the
-/// free functions and the [`SqlxRepository`]/[`SqlxOutboxStore`] impls in this
-/// module are the single copy of everything they agree on.
-pub trait SqlxRepoBackend: SqlxReadModelBackend {
-    /// Embedded migrations applied by `migrate_pool`. Runs through
-    /// `sqlx::migrate::Migrator`, which keeps a `_sqlx_migrations` ledger and
-    /// executes each migration file whole (the previous hand-rolled runner
-    /// split files on `;`, which breaks on function bodies and string
-    /// literals, and kept no record of what had been applied).
-    fn migrator() -> &'static Migrator;
-    /// Maximum bound parameters per statement. Multi-row inserts are chunked to
-    /// stay under this; Postgres is effectively unlimited so chunking collapses
-    /// to a single statement and both backends share one code path.
-    const MAX_BIND_PARAMS: usize;
-    /// Whether event-insert conflict recovery re-reads stream versions inside
-    /// the failed transaction. SQLite does not abort a transaction on a
-    /// constraint error, so the re-read can (and must, to see this tx's own
-    /// earlier chunks) happen in-tx. A failed Postgres statement aborts the
-    /// transaction, so the re-read runs on a separate pool connection.
-    const CONFLICT_REREAD_IN_TX: bool;
-    /// SQL expression producing the database's current timestamp, used for
-    /// server-side `updated_at` maintenance.
-    const NOW: &'static str;
-    /// `SELECT` list for `aggregate_events` rows. The recorded-at column must
-    /// surface as `recorded_at` in whatever representation
-    /// [`decode_timestamp`](Self::decode_timestamp) reads.
-    const EVENT_SELECT: &'static str;
-    /// `SELECT` list for `aggregate_snapshots` rows (recorded-at as above).
-    const SNAPSHOT_SELECT: &'static str;
-    /// `SELECT` list for `outbox_messages` rows (`created_at`/`claimed_until`
-    /// in the representation `decode_timestamp` reads).
-    const OUTBOX_SELECT: &'static str;
-    /// ORDER BY expression for outbox `created_at` ordering (SQLite stores
-    /// timestamps as text and must cast for numeric ordering).
-    const ORDER_BY_CREATED_AT: &'static str;
-    /// `SELECT` expression for `MIN(created_at)` surfaced as
-    /// `oldest_created_at` in this backend's timestamp representation.
-    const OUTBOX_OLDEST_CREATED_AT_SELECT: &'static str;
-    /// Dialect for table/read-model schema artifact generation.
-    const TABLE_DIALECT: TableSqlDialect;
-
-    /// Owned bind value for a stored timestamp (Postgres: epoch seconds `f64`;
-    /// SQLite: `"secs.nanos"` text).
-    type TimestampValue: Send + Sync + 'static;
-
-    /// Pool size when connecting from a database URL.
-    fn default_pool_size(database_url: &str) -> u32 {
-        let _ = database_url;
-        5
-    }
-
-    /// Whether a `sqlx::Error` is this backend's unique-violation error.
-    fn is_unique_violation(err: &sqlx::Error) -> bool;
-
-    /// Encode a [`SystemTime`] into this backend's stored representation.
-    fn timestamp_value(timestamp: SystemTime) -> Result<Self::TimestampValue, RepositoryError>;
-
-    /// Push a timestamp value into a separated bind list (Postgres wraps the
-    /// bind in `to_timestamp(...)`).
-    fn push_timestamp(sep: &mut Separated<'_, Self, &'static str>, value: &Self::TimestampValue);
-
-    /// Push an optional timestamp value into a separated bind list, binding a
-    /// typed `NULL` when absent.
-    fn push_optional_timestamp(
-        sep: &mut Separated<'_, Self, &'static str>,
-        value: Option<&Self::TimestampValue>,
-    );
-
-    /// Push `<assignment target> = <timestamp>` right-hand side into a builder.
-    fn push_timestamp_assign(builder: &mut QueryBuilder<Self>, value: &Self::TimestampValue);
-
-    /// Push `<column> <op> <now>` comparing a stored timestamp column against
-    /// epoch seconds (Postgres: `column op to_timestamp($n)`; SQLite:
-    /// `CAST(column AS REAL) op ?`).
-    fn push_timestamp_cmp(
-        builder: &mut QueryBuilder<Self>,
-        column: &'static str,
-        op: &'static str,
-        epoch_secs: f64,
-    );
-
-    /// Decode a stored timestamp column into a [`SystemTime`].
-    fn decode_timestamp(
-        row: &Self::Row,
-        column: &'static str,
-    ) -> Result<SystemTime, RepositoryError>;
-
-    /// Decode a nullable stored timestamp column.
-    fn decode_optional_timestamp(
-        row: &Self::Row,
-        column: &'static str,
-    ) -> Result<Option<SystemTime>, RepositoryError>;
-
-    /// Push a metadata JSON bind (Postgres casts to `::jsonb`).
-    fn push_metadata(sep: &mut Separated<'_, Self, &'static str>, json: &str);
-
-    /// Push an `aggregate_id` filter for an id list (Postgres: `= ANY($n)`
-    /// array bind; SQLite: `IN (?, ?, ...)`).
-    fn push_id_filter(builder: &mut QueryBuilder<Self>, ids: &[&str]);
-
-    /// Build the consumer-inbox retention `DELETE` for a cutoff age, evaluated
-    /// against the database clock.
-    fn inbox_purge_query(age: Duration) -> QueryBuilder<Self>;
-
-    /// Claim up to `batch_size` outbox messages. This is the one genuinely
-    /// divergent operation: Postgres uses a CTE with `FOR UPDATE SKIP LOCKED`;
-    /// SQLite (no row locks) scans candidates and claims them with per-id
-    /// conditional updates.
-    fn claim_outbox<'a>(
-        pool: &'a Pool<Self>,
-        request: ClaimOutboxMessages,
-    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + 'a;
-}
-
-/// SQL-backed async repository generic over the SQLx backend.
-///
-/// Use through the public aliases: [`PostgresRepository`](crate::PostgresRepository)
-/// and [`SqliteRepository`](crate::SqliteRepository).
-pub struct SqlxRepository<DB: sqlx::Database> {
-    pool: Pool<DB>,
-    read_model_schemas: Arc<RwLock<TableSchemaRegistry>>,
-}
-
-impl<DB: sqlx::Database> Clone for SqlxRepository<DB> {
-    fn clone(&self) -> Self {
-        Self {
-            pool: self.pool.clone(),
-            read_model_schemas: Arc::clone(&self.read_model_schemas),
-        }
-    }
-}
-
-/// SQL-backed outbox table store generic over the SQLx backend.
-///
-/// Use through the public aliases: [`PostgresOutboxStore`](crate::PostgresOutboxStore)
-/// and [`SqliteOutboxStore`](crate::SqliteOutboxStore).
-pub struct SqlxOutboxStore<DB: sqlx::Database> {
-    pool: Pool<DB>,
-}
-
-impl<DB: sqlx::Database> Clone for SqlxOutboxStore<DB> {
-    fn clone(&self) -> Self {
-        Self {
-            pool: self.pool.clone(),
-        }
-    }
-}
-
-impl<DB> SqlxRepository<DB>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
-    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-{
-    /// Create a repository from an existing migrated pool.
-    pub fn new(pool: Pool<DB>) -> Self {
-        Self {
-            pool,
-            read_model_schemas: Arc::new(RwLock::new(TableSchemaRegistry::new())),
-        }
-    }
-
-    /// Open a pool without applying migrations.
-    pub async fn connect(database_url: &str) -> Result<Self, RepositoryError> {
-        let pool = PoolOptions::<DB>::new()
-            .max_connections(DB::default_pool_size(database_url))
-            .connect(database_url)
-            .await
-            .map_err(|err| repository_storage_error::<DB>("connect", err))?;
-        Ok(Self::new(pool))
-    }
-
-    /// Open a pool and apply this backend's explicit migrations.
-    pub async fn connect_and_migrate(database_url: &str) -> Result<Self, RepositoryError>
-    where
-        DB::Connection: Migrate,
-    {
-        let repo = Self::connect(database_url).await?;
-        repo.migrate().await?;
-        Ok(repo)
-    }
-
-    /// Apply this backend's migrations to the repository's pool.
-    pub async fn migrate(&self) -> Result<(), RepositoryError>
-    where
-        DB::Connection: Migrate,
-    {
-        Self::migrate_pool(&self.pool).await
-    }
-
-    /// Apply this backend's migrations to an existing pool. Applied versions
-    /// are recorded in the `_sqlx_migrations` ledger, so re-running is a no-op
-    /// and an edited already-applied migration fails its checksum comparison
-    /// instead of silently diverging.
-    pub async fn migrate_pool(pool: &Pool<DB>) -> Result<(), RepositoryError>
-    where
-        DB::Connection: Migrate,
-    {
-        DB::migrator()
-            .run(pool)
-            .await
-            .map_err(|err| RepositoryError::Storage {
-                operation: format!("{} migrate", DB::BACKEND),
-                retryable: false,
-                source: Some(Box::new(err)),
-            })
-    }
-
-    /// Access the underlying SQLx pool for application-specific setup or tests.
-    pub fn pool(&self) -> &Pool<DB> {
-        &self.pool
-    }
-
-    /// SQL artifact adapter for registered table/read-model schemas.
-    pub fn table_schema_adapter(&self) -> TableSqlSchemaAdapter {
-        table_schema_adapter::<DB>()
-    }
-
-    /// Generate SQL statements for registered table/read-model schemas.
-    pub fn generate_table_migration_artifacts(
-        &self,
-        registry: &TableSchemaRegistry,
-    ) -> Result<Vec<TableMigrationArtifact>, TableStoreError> {
-        generate_table_migration_artifacts(registry, DB::TABLE_DIALECT)
-    }
-
-    /// Explicit dev/test bootstrap for registered table/read-model schemas.
-    pub async fn bootstrap_table_schema_for_dev(
-        &self,
-        registry: &TableSchemaRegistry,
-    ) -> Result<TableSchemaBootstrap, TableStoreError> {
-        bootstrap_table_schema(&self.pool, registry).await?;
-        remember_read_model_schemas(&self.read_model_schemas, registry)?;
-        Ok(table_schema_bootstrap_result(registry))
-    }
-
-    /// Access an outbox-store handle backed by this repository's pool.
-    pub fn outbox_store(&self) -> SqlxOutboxStore<DB> {
-        SqlxOutboxStore {
-            pool: self.pool.clone(),
-        }
-    }
-}
-
-impl<DB> SqlxOutboxStore<DB>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-{
-    pub fn new(pool: Pool<DB>) -> Self {
-        Self { pool }
-    }
-
-    pub fn pool(&self) -> &Pool<DB> {
-        &self.pool
-    }
-
-    /// SQL artifact adapter for registered table/read-model schemas.
-    pub fn table_schema_adapter(&self) -> TableSqlSchemaAdapter {
-        table_schema_adapter::<DB>()
-    }
-
-    /// Generate SQL statements for registered table/read-model schemas.
-    pub fn generate_table_migration_artifacts(
-        &self,
-        registry: &TableSchemaRegistry,
-    ) -> Result<Vec<TableMigrationArtifact>, TableStoreError> {
-        generate_table_migration_artifacts(registry, DB::TABLE_DIALECT)
-    }
-
-    /// Explicit dev/test bootstrap for registered table/read-model schemas.
-    pub async fn bootstrap_table_schema_for_dev(
-        &self,
-        registry: &TableSchemaRegistry,
-    ) -> Result<TableSchemaBootstrap, TableStoreError> {
-        bootstrap_table_schema(&self.pool, registry).await?;
-        Ok(table_schema_bootstrap_result(registry))
-    }
-}
-
-fn table_schema_adapter<DB: SqlxRepoBackend>() -> TableSqlSchemaAdapter {
-    match DB::TABLE_DIALECT {
-        TableSqlDialect::Postgres => TableSqlSchemaAdapter::postgres(),
-        TableSqlDialect::Sqlite => TableSqlSchemaAdapter::sqlite(),
-    }
-}
-
-async fn bootstrap_table_schema<DB>(
-    pool: &Pool<DB>,
-    registry: &TableSchemaRegistry,
-) -> Result<(), TableStoreError>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-{
-    for statement in table_schema_statements(registry, DB::TABLE_DIALECT)? {
-        sqlx::query(audited_table_schema_sql(statement))
-            .execute(pool)
-            .await
-            .map_err(|err| {
-                TableStoreError::Storage(format!(
-                    "{} bootstrap table schema failed: {err}",
-                    DB::BACKEND
-                ))
-            })?;
-    }
-    Ok(())
-}
-
-impl<DB> GetStream for SqlxRepository<DB>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
-    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> f64: Encode<'q, DB> + Type<DB>,
-    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    fn get_stream<'a>(
-        &'a self,
-        identity: &'a StreamIdentity,
-    ) -> impl Future<Output = Result<Option<Entity>, RepositoryError>> + Send + 'a {
-        async move {
-            let mut builder = QueryBuilder::<DB>::new("SELECT ");
-            builder.push(DB::EVENT_SELECT);
-            builder.push(" FROM aggregate_events WHERE aggregate_type = ");
-            builder.push_bind(identity.aggregate_type());
-            builder.push(" AND aggregate_id = ");
-            builder.push_bind(identity.aggregate_id());
-            builder.push(" ORDER BY sequence ASC");
-            let rows = builder
-                .build()
-                .fetch_all(&self.pool)
-                .await
-                .map_err(|err| repository_storage_error::<DB>("load stream", err))?;
-
-            if rows.is_empty() {
-                return Ok(None);
-            }
-
-            let mut events = Vec::with_capacity(rows.len());
-            for row in rows {
-                events.push(event_from_row::<DB>(row)?);
-            }
-
-            let mut entity = Entity::new();
-            entity.set_id(identity.aggregate_id());
-            entity.load_from_history(events);
-            Ok(Some(entity))
-        }
-    }
-
-    fn get_streams<'a>(
-        &'a self,
-        identities: &'a [StreamIdentity],
-    ) -> impl Future<Output = Result<Vec<Entity>, RepositoryError>> + Send + 'a {
-        async move {
-            if identities.is_empty() {
-                return Ok(Vec::new());
-            }
-
-            let mut entities = Vec::with_capacity(identities.len());
-            for (aggregate_type, aggregate_ids) in ids_by_type(identities) {
-                // Ordering by aggregate_id then sequence lets us slice the flat
-                // result into per-aggregate entities in one pass. Callers of
-                // `get_all` accept storage-order results.
-                let mut builder = QueryBuilder::<DB>::new("SELECT aggregate_id, ");
-                builder.push(DB::EVENT_SELECT);
-                builder.push(" FROM aggregate_events WHERE aggregate_type = ");
-                builder.push_bind(aggregate_type);
-                builder.push(" AND ");
-                DB::push_id_filter(&mut builder, &aggregate_ids);
-                builder.push(" ORDER BY aggregate_id ASC, sequence ASC");
-
-                let rows = builder
-                    .build()
-                    .fetch_all(&self.pool)
-                    .await
-                    .map_err(|err| repository_storage_error::<DB>("load streams", err))?;
-
-                let mut current_id: Option<String> = None;
-                let mut current_events: Vec<EventRecord> = Vec::new();
-                for row in rows {
-                    let row_id: String = row.try_get("aggregate_id").map_err(|err| {
-                        repository_storage_error::<DB>("decode aggregate id row", err)
-                    })?;
-                    let event = event_from_row::<DB>(row)?;
-                    match &current_id {
-                        Some(id) if id == &row_id => current_events.push(event),
-                        _ => {
-                            if let Some(id) = current_id.take() {
-                                entities.push(entity_from_events(
-                                    id,
-                                    std::mem::take(&mut current_events),
-                                ));
-                            }
-                            current_id = Some(row_id);
-                            current_events.push(event);
-                        }
-                    }
-                }
-                if let Some(id) = current_id.take() {
-                    entities.push(entity_from_events(id, current_events));
-                }
-            }
-
-            Ok(entities)
-        }
-    }
-
-    fn get_stream_tail<'a>(
-        &'a self,
-        identity: &'a StreamIdentity,
-        after_version: u64,
-    ) -> impl Future<Output = Result<Option<Entity>, RepositoryError>> + Send + 'a {
-        async move {
-            // Fetch only the post-snapshot tail. `after_version` is the snapshot
-            // version (an event sequence); `sequence > ?` skips already-folded
-            // rows so a fresh snapshot over a long stream no longer reads and
-            // decodes the entire history.
-            let after = repository_i64_from_u64(
-                DB::BACKEND,
-                after_version,
-                "snapshot tail lower bound",
-                DB::INTEGER_STORAGE,
-            )?;
-            let mut builder = QueryBuilder::<DB>::new("SELECT ");
-            builder.push(DB::EVENT_SELECT);
-            builder.push(" FROM aggregate_events WHERE aggregate_type = ");
-            builder.push_bind(identity.aggregate_type());
-            builder.push(" AND aggregate_id = ");
-            builder.push_bind(identity.aggregate_id());
-            builder.push(" AND sequence > ");
-            builder.push_bind(after);
-            builder.push(" ORDER BY sequence ASC");
-            let rows = builder
-                .build()
-                .fetch_all(&self.pool)
-                .await
-                .map_err(|err| repository_storage_error::<DB>("load stream tail", err))?;
-
-            // An empty tail is ambiguous from this query alone (no rows could
-            // mean "snapshot is current" or "stream does not exist"). The
-            // snapshot hydrate path only calls this after confirming a snapshot
-            // exists for the identity, so an empty tail means the snapshot is
-            // current. Return an entity at exactly `after_version`.
-            let mut events = Vec::with_capacity(rows.len());
-            for row in rows {
-                events.push(event_from_row::<DB>(row)?);
-            }
-
-            let mut entity = Entity::new();
-            entity.set_id(identity.aggregate_id());
-            entity.load_tail_from_history(events, after_version);
-            Ok(Some(entity))
-        }
-    }
-}
-
-impl<DB> TransactionalCommit for SqlxRepository<DB>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
-    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> f64: Encode<'q, DB> + Type<DB>,
-    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
-    for<'q> Option<i64>: Encode<'q, DB> + Type<DB>,
-    for<'q> Option<&'q str>: Encode<'q, DB> + Type<DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    fn commit_batch<'a>(
-        &'a self,
-        batch: CommitBatch<'a>,
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-        async move {
-            let prepared = validate_commit_batch(&batch)?;
-
-            for plan in &batch.read_model_plans {
-                validate_sql_write_plan(plan)?;
-            }
-
-            let mut tx =
-                self.pool.begin().await.map_err(|err| {
-                    repository_storage_error::<DB>("begin commit transaction", err)
-                })?;
-
-            // One grouped round trip for the whole batch's optimistic
-            // concurrency pre-check instead of a MAX(sequence) query per stream.
-            let versions = stream_versions_in_tx(&mut tx, &prepared).await?;
-            for append in &prepared {
-                let actual = versions
-                    .get(&append.identity.storage_key())
-                    .copied()
-                    .unwrap_or(0);
-                if actual != append.expected_version {
-                    return Err(RepositoryError::ConcurrentWrite {
-                        id: append.identity.to_string(),
-                        expected: append.expected_version,
-                        actual,
-                    });
-                }
-            }
-
-            insert_events_in_tx(&self.pool, &mut tx, &prepared).await?;
-
-            insert_outbox_messages_in_tx(&mut tx, &batch.outbox_messages).await?;
-
-            for plan in batch.read_model_plans {
-                apply_read_model_write_plan_in_tx(&mut tx, plan).await?;
-            }
-
-            for write in batch.snapshots {
-                match write {
-                    SnapshotWrite::Save { identity, record } => {
-                        save_snapshot_in_tx(&mut tx, &identity, record).await?;
-                    }
-                }
-            }
-
-            for receipt in &batch.inbox_receipts {
-                insert_inbox_receipt_in_tx(&mut tx, receipt).await?;
-            }
-
-            tx.commit()
-                .await
-                .map_err(|err| repository_storage_error::<DB>("commit transaction", err))?;
-
-            for stream in batch.streams {
-                stream.entity.mark_committed();
-            }
-
-            Ok(())
-        }
-    }
-}
-
-impl<DB> InboxStore for SqlxRepository<DB>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
-    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    fn inbox_contains<'a>(
-        &'a self,
-        consumer: &'a str,
-        message_id: &'a str,
-    ) -> impl Future<Output = Result<bool, RepositoryError>> + Send + 'a {
-        async move {
-            let mut builder =
-                QueryBuilder::<DB>::new("SELECT 1 FROM consumer_inbox WHERE consumer = ");
-            builder.push_bind(consumer);
-            builder.push(" AND message_id = ");
-            builder.push_bind(message_id);
-            builder.push(" LIMIT 1");
-            let row = builder
-                .build()
-                .fetch_optional(&self.pool)
-                .await
-                .map_err(|err| repository_storage_error::<DB>("query consumer inbox", err))?;
-            Ok(row.is_some())
-        }
-    }
-
-    fn purge_inbox_older_than(
-        &self,
-        age: std::time::Duration,
-    ) -> impl Future<Output = Result<u64, RepositoryError>> + Send {
-        async move {
-            // Compare against the database clock to avoid client/server skew;
-            // the backend renders the cutoff expression.
-            let mut builder = DB::inbox_purge_query(age);
-            let result = builder
-                .build()
-                .execute(&self.pool)
-                .await
-                .map_err(|err| repository_storage_error::<DB>("purge consumer inbox", err))?;
-            Ok(DB::rows_affected(&result))
-        }
-    }
-}
-
-impl<DB> ReadModelWritePlanStore for SqlxRepository<DB>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    fn read_model_capabilities(&self) -> ReadModelAdapterCapabilities {
-        sql_read_model_capabilities()
-    }
-
-    fn commit_write_plan(
-        &self,
-        plan: ReadModelWritePlan,
-    ) -> impl Future<Output = Result<ReadModelCommitOutcome, ReadModelError>> + Send + '_ {
-        async move { commit_read_model_write_plan(&self.pool, plan).await }
-    }
-}
-
-impl<DB> RelationalReadModelQueryStore for SqlxRepository<DB>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    fn read_model_query_capabilities(&self) -> ReadModelQueryCapabilities {
-        ReadModelQueryCapabilities::relationship_includes()
-    }
-
-    fn load_graph(
-        &self,
-        request: ReadModelLoadRequest,
-    ) -> impl Future<Output = Result<ReadModelLoadGraph, ReadModelError>> + Send + '_ {
-        async move {
-            load_read_model_graph(
-                &self.pool,
-                &self.read_model_schemas,
-                request,
-                self.read_model_query_capabilities(),
-            )
-            .await
-        }
-    }
-}
-
-impl<DB> SnapshotStore for SqlxRepository<DB>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
-    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    fn get_snapshot<'a>(
-        &'a self,
-        identity: &'a StreamIdentity,
-    ) -> impl Future<Output = Result<Option<SnapshotRecord>, RepositoryError>> + Send + 'a {
-        async move {
-            let mut builder = QueryBuilder::<DB>::new("SELECT ");
-            builder.push(DB::SNAPSHOT_SELECT);
-            builder.push(" FROM aggregate_snapshots WHERE aggregate_type = ");
-            builder.push_bind(identity.aggregate_type());
-            builder.push(" AND aggregate_id = ");
-            builder.push_bind(identity.aggregate_id());
-            let row = builder
-                .build()
-                .fetch_optional(&self.pool)
-                .await
-                .map_err(|err| repository_storage_error::<DB>("load snapshot", err))?;
-
-            let Some(row) = row else {
-                return Ok(None);
-            };
-
-            Ok(Some(snapshot_from_row::<DB>(row)?))
-        }
-    }
-
-    fn get_snapshots<'a>(
-        &'a self,
-        identities: &'a [StreamIdentity],
-    ) -> impl Future<Output = Result<Vec<SnapshotRecord>, RepositoryError>> + Send + 'a {
-        async move {
-            if identities.is_empty() {
-                return Ok(Vec::new());
-            }
-
-            let mut records = Vec::with_capacity(identities.len());
-            for (aggregate_type, aggregate_ids) in ids_by_type(identities) {
-                let mut builder = QueryBuilder::<DB>::new("SELECT ");
-                builder.push(DB::SNAPSHOT_SELECT);
-                builder.push(" FROM aggregate_snapshots WHERE aggregate_type = ");
-                builder.push_bind(aggregate_type);
-                builder.push(" AND ");
-                DB::push_id_filter(&mut builder, &aggregate_ids);
-                let rows = builder
-                    .build()
-                    .fetch_all(&self.pool)
-                    .await
-                    .map_err(|err| repository_storage_error::<DB>("load snapshots", err))?;
-                for row in rows {
-                    records.push(snapshot_from_row::<DB>(row)?);
-                }
-            }
-            Ok(records)
-        }
-    }
-
-    fn save_snapshot<'a>(
-        &'a self,
-        identity: &'a StreamIdentity,
-        record: SnapshotRecord,
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-        async move {
-            let mut tx =
-                self.pool.begin().await.map_err(|err| {
-                    repository_storage_error::<DB>("begin snapshot transaction", err)
-                })?;
-            save_snapshot_in_tx(&mut tx, identity, record).await?;
-            tx.commit().await.map_err(|err| {
-                repository_storage_error::<DB>("commit snapshot transaction", err)
-            })?;
-            Ok(())
-        }
-    }
-
-    fn delete_snapshot<'a>(
-        &'a self,
-        identity: &'a StreamIdentity,
-    ) -> impl Future<Output = Result<bool, RepositoryError>> + Send + 'a {
-        async move {
-            let mut builder =
-                QueryBuilder::<DB>::new("DELETE FROM aggregate_snapshots WHERE aggregate_type = ");
-            builder.push_bind(identity.aggregate_type());
-            builder.push(" AND aggregate_id = ");
-            builder.push_bind(identity.aggregate_id());
-            let result = builder
-                .build()
-                .execute(&self.pool)
-                .await
-                .map_err(|err| repository_storage_error::<DB>("delete snapshot", err))?;
-
-            Ok(DB::rows_affected(&result) > 0)
-        }
-    }
-}
-
-/// One claimed-message lifecycle transition (the `UPDATE` shape is shared; only
-/// the assignments differ).
-enum OutboxTransition<'a> {
-    Complete,
-    Release { error: &'a str },
-    Fail { error: &'a str },
-}
-
-impl OutboxTransition<'_> {
-    fn target_status(&self) -> OutboxMessageStatus {
-        match self {
-            OutboxTransition::Complete => OutboxMessageStatus::Published,
-            OutboxTransition::Release { .. } => OutboxMessageStatus::Pending,
-            OutboxTransition::Fail { .. } => OutboxMessageStatus::Failed,
-        }
-    }
-
-    fn operation(&self) -> &'static str {
-        match self {
-            OutboxTransition::Complete => "complete outbox message",
-            OutboxTransition::Release { .. } => "release outbox message",
-            OutboxTransition::Fail { .. } => "fail outbox message",
-        }
-    }
-}
-
-impl<DB> OutboxStore for SqlxOutboxStore<DB>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
-    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> f64: Encode<'q, DB> + Type<DB>,
-    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
-    for<'q> Option<i64>: Encode<'q, DB> + Type<DB>,
-    for<'q> Option<&'q str>: Encode<'q, DB> + Type<DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    fn messages_by_status(
-        &self,
-        status: OutboxMessageStatus,
-        limit: usize,
-    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + '_ {
-        async move {
-            let mut builder = QueryBuilder::<DB>::new("SELECT ");
-            builder.push(DB::OUTBOX_SELECT);
-            builder.push(" FROM outbox_messages WHERE status = ");
-            builder.push_bind(status.as_str());
-            builder.push(" ORDER BY ");
-            builder.push(DB::ORDER_BY_CREATED_AT);
-            builder.push(" ASC, message_id ASC LIMIT ");
-            // usize::MAX means "no practical bound"; clamp to what the column
-            // type can carry.
-            builder.push_bind(i64::try_from(limit).unwrap_or(i64::MAX));
-            let rows = builder.build().fetch_all(&self.pool).await.map_err(|err| {
-                repository_storage_error::<DB>("load outbox messages by status", err)
-            })?;
-
-            rows.into_iter()
-                .map(outbox_message_from_row::<DB>)
-                .collect()
-        }
-    }
-
-    fn backlog_stats(
-        &self,
-    ) -> impl Future<Output = Result<OutboxBacklogStats, RepositoryError>> + Send + '_ {
-        async move {
-            let mut builder = QueryBuilder::<DB>::new("SELECT COUNT(*) AS pending_count, ");
-            builder.push(DB::OUTBOX_OLDEST_CREATED_AT_SELECT);
-            builder.push(" FROM outbox_messages WHERE status = ");
-            builder.push_bind(OutboxMessageStatus::Pending.as_str());
-            let row =
-                builder.build().fetch_one(&self.pool).await.map_err(|err| {
-                    repository_storage_error::<DB>("load outbox backlog stats", err)
-                })?;
-
-            let pending_count: i64 = row.try_get("pending_count").map_err(|err| {
-                repository_storage_error::<DB>("decode outbox backlog count row", err)
-            })?;
-            let pending =
-                repository_u64_from_i64(DB::BACKEND, pending_count, "outbox backlog count")
-                    .and_then(|value| {
-                        usize::try_from(value).map_err(|_| {
-                            RepositoryError::Model(format!(
-                                "{} outbox backlog count value {value} is invalid",
-                                DB::BACKEND
-                            ))
-                        })
-                    })?;
-            let oldest_created_at = DB::decode_optional_timestamp(&row, "oldest_created_at")?;
-
-            Ok(OutboxBacklogStats {
-                pending,
-                oldest_created_at,
-            })
-        }
-    }
-
-    fn claim<'a>(
-        &'a self,
-        request: ClaimOutboxMessages,
-    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + 'a {
-        DB::claim_outbox(&self.pool, request)
-    }
-
-    fn complete<'a>(
-        &'a self,
-        claim: &'a OutboxClaimRef,
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-        transition_claimed_outbox_message(&self.pool, claim, OutboxTransition::Complete)
-    }
-
-    fn release<'a>(
-        &'a self,
-        claim: &'a OutboxClaimRef,
-        error: &'a str,
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-        transition_claimed_outbox_message(&self.pool, claim, OutboxTransition::Release { error })
-    }
-
-    fn fail<'a>(
-        &'a self,
-        claim: &'a OutboxClaimRef,
-        error: &'a str,
-    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
-        transition_claimed_outbox_message(&self.pool, claim, OutboxTransition::Fail { error })
-    }
-}
-
-/// Apply one claimed-message lifecycle transition (complete / release / fail).
-///
-/// The conditional `UPDATE` only applies while the caller still holds the
-/// active claim (`status`, `claimed_by`, unexpired `claimed_until`, and
-/// matching `attempts`); when no row is updated, the message is re-read to
-/// produce the precise claim error.
-async fn transition_claimed_outbox_message<'a, DB>(
-    pool: &'a Pool<DB>,
-    claim: &'a OutboxClaimRef,
-    transition: OutboxTransition<'a>,
-) -> Result<(), RepositoryError>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> f64: Encode<'q, DB> + Type<DB>,
-    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'q> Option<i64>: Encode<'q, DB> + Type<DB>,
-    for<'q> Option<&'q str>: Encode<'q, DB> + Type<DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    let now = SystemTime::now();
-    let now_epoch = system_time_epoch_secs::<DB>(now)?;
-    let now_value = DB::timestamp_value(now)?;
-
-    let mut builder = QueryBuilder::<DB>::new("UPDATE outbox_messages SET status = ");
-    builder.push_bind(transition.target_status().as_str());
-    builder.push(", claimed_by = NULL, claimed_until = NULL, ");
-    match &transition {
-        OutboxTransition::Complete => {
-            builder.push("published_at = ");
-            DB::push_timestamp_assign(&mut builder, &now_value);
-        }
-        OutboxTransition::Release { error } => {
-            builder.push("next_available_at = ");
-            DB::push_timestamp_assign(&mut builder, &now_value);
-            builder.push(", last_error = ");
-            builder.push_bind(empty_string_as_none(error));
-        }
-        OutboxTransition::Fail { error } => {
-            builder.push("last_error = ");
-            builder.push_bind(empty_string_as_none(error));
-            builder.push(", failed_at = ");
-            DB::push_timestamp_assign(&mut builder, &now_value);
-        }
-    }
-    builder.push(", updated_at = ");
-    builder.push(DB::NOW);
-    builder.push(" WHERE message_id = ");
-    builder.push_bind(claim.message_id.as_str());
-    builder.push(" AND status = ");
-    builder.push_bind(OutboxMessageStatus::InFlight.as_str());
-    builder.push(" AND claimed_by = ");
-    builder.push_bind(claim.worker_id.as_str());
-    builder.push(" AND claimed_until IS NOT NULL AND ");
-    DB::push_timestamp_cmp(&mut builder, "claimed_until", ">", now_epoch);
-    builder.push(" AND attempts = ");
-    builder.push_bind(repository_i64_from_u64(
-        DB::BACKEND,
-        u64::from(claim.attempt),
-        "outbox claim attempt",
-        DB::INTEGER_STORAGE,
-    )?);
-
-    let result = builder
-        .build()
-        .execute(pool)
-        .await
-        .map_err(|err| repository_storage_error::<DB>(transition.operation(), err))?;
-
-    ensure_outbox_update_applied(
-        pool,
-        DB::rows_affected(&result),
-        &claim.message_id,
-        |message| ensure_active_claim(message, Some(claim), now),
-    )
-    .await
-}
-
-/// Load an outbox message by id through any executor (pool or transaction).
-pub(crate) async fn outbox_message_by_id<'e, DB, E>(
-    executor: E,
-    message_id: &str,
-) -> Result<Option<OutboxMessage>, RepositoryError>
-where
-    DB: SqlxRepoBackend,
-    E: Executor<'e, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    let mut builder = QueryBuilder::<DB>::new("SELECT ");
-    builder.push(DB::OUTBOX_SELECT);
-    builder.push(" FROM outbox_messages WHERE message_id = ");
-    builder.push_bind(message_id);
-    let row = builder
-        .build()
-        .fetch_optional(executor)
-        .await
-        .map_err(|err| repository_storage_error::<DB>("load outbox message", err))?;
-    row.map(outbox_message_from_row::<DB>).transpose()
-}
-
-pub(crate) async fn ensure_outbox_update_applied<DB>(
-    pool: &Pool<DB>,
-    rows_affected: u64,
-    message_id: &str,
-    validate: impl FnOnce(&OutboxMessage) -> Result<(), RepositoryError>,
-) -> Result<(), RepositoryError>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    if rows_affected > 0 {
-        return Ok(());
-    }
-
-    let message = outbox_message_by_id(pool, message_id)
-        .await?
-        .ok_or_else(|| RepositoryError::NotFound {
-            id: message_id.to_string(),
-        })?;
-    validate(&message)
-}
-
-/// Record a consumer inbox receipt in the commit transaction. The
-/// `(consumer, message_id)` primary key is the dedupe gate: a unique violation
-/// means the message was already processed, so the whole batch rolls back and
-/// the effects are not double-applied. `processed_at` defaults server-side.
-async fn insert_inbox_receipt_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    receipt: &InboxReceipt,
-) -> Result<(), RepositoryError>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-{
-    receipt.validate()?;
-    let mut builder =
-        QueryBuilder::<DB>::new("INSERT INTO consumer_inbox (consumer, message_id) VALUES (");
-    builder.push_bind(receipt.consumer.as_str());
-    builder.push(", ");
-    builder.push_bind(receipt.message_id.as_str());
-    builder.push(")");
-    let result = builder.build().execute(&mut **tx).await;
-    match result {
-        Ok(_) => Ok(()),
-        Err(err) if DB::is_unique_violation(&err) => Err(RepositoryError::DuplicateInboxReceipt {
-            consumer: receipt.consumer.clone(),
-            message_id: receipt.message_id.clone(),
-        }),
-        Err(err) => Err(repository_storage_error::<DB>(
-            "insert consumer inbox receipt",
-            err,
-        )),
-    }
-}
-
-/// One `aggregate_events` row with pre-validated bind values, built before the
-/// query so any conversion error surfaces before we touch the database. The
-/// stream identity and expected version ride along for conflict recovery.
-struct EventRow<'a, DB: SqlxRepoBackend> {
-    identity: &'a StreamIdentity,
-    expected_version: u64,
-    sequence: i64,
-    event_name: &'a str,
-    event_version: i64,
-    payload: &'a [u8],
-    payload_codec: &'a str,
-    payload_codec_version: i64,
-    metadata: String,
-    recorded_at: DB::TimestampValue,
-}
-
-/// Insert every event across all prepared appends with multi-row INSERTs,
-/// chunked to respect the backend's bound-parameter limit (Postgres is
-/// effectively unlimited, so its chunking collapses to one statement).
-///
-/// Conflict detection is unchanged from the per-row path: the `(aggregate_type,
-/// aggregate_id, sequence)` primary key is the contiguity gate, and a unique
-/// violation still surfaces as `ConcurrentWrite`. Recovery re-reads stream
-/// versions in-tx or over the pool depending on
-/// [`SqlxRepoBackend::CONFLICT_REREAD_IN_TX`].
-async fn insert_events_in_tx<DB>(
-    pool: &Pool<DB>,
-    tx: &mut Transaction<'_, DB>,
-    prepared: &[PreparedEventAppend<'_>],
-) -> Result<(), RepositoryError>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
-    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    let mut rows = Vec::new();
-    for append in prepared {
-        for event in append.events {
-            rows.push(EventRow::<DB> {
-                identity: &append.identity,
-                expected_version: append.expected_version,
-                sequence: repository_i64_from_u64(
-                    DB::BACKEND,
-                    event.sequence,
-                    "sequence",
-                    DB::INTEGER_STORAGE,
-                )?,
-                event_name: &event.event_name,
-                event_version: repository_i64_from_u64(
-                    DB::BACKEND,
-                    event.event_version,
-                    "event_version",
-                    DB::INTEGER_STORAGE,
-                )?,
-                payload: &event.payload,
-                payload_codec: &event.payload_codec,
-                payload_codec_version: i64::from(event.payload_codec_version),
-                metadata: serialize_event_metadata(&event.metadata)?,
-                recorded_at: DB::timestamp_value(event.timestamp)?,
-            });
-        }
-    }
-
-    for chunk in rows.chunks(DB::MAX_BIND_PARAMS / EVENT_BIND_COLUMNS) {
-        let mut builder = QueryBuilder::<DB>::new(
-            "INSERT INTO aggregate_events (\
-             aggregate_type, aggregate_id, sequence, event_name, event_version, \
-             payload, payload_codec, payload_codec_version, metadata, recorded_at) ",
-        );
-        builder.push_values(chunk, |mut row, event| {
-            row.push_bind(event.identity.aggregate_type())
-                .push_bind(event.identity.aggregate_id())
-                .push_bind(event.sequence)
-                .push_bind(event.event_name)
-                .push_bind(event.event_version)
-                .push_bind(event.payload)
-                .push_bind(event.payload_codec)
-                .push_bind(event.payload_codec_version);
-            DB::push_metadata(&mut row, event.metadata.as_str());
-            DB::push_timestamp(&mut row, &event.recorded_at);
-        });
-
-        let result = builder.build().execute(&mut **tx).await;
-        match result {
-            Ok(_) => {}
-            Err(err) if DB::is_unique_violation(&err) => {
-                return Err(if DB::CONFLICT_REREAD_IN_TX {
-                    // The transaction survives the constraint error: re-read in
-                    // the same tx, scoped to this chunk (earlier chunks were
-                    // already inserted in this tx and would skew the versions
-                    // of their streams).
-                    let mut seen = std::collections::HashSet::new();
-                    let candidates: Vec<_> = chunk
-                        .iter()
-                        .filter(|event| seen.insert(event.identity.storage_key()))
-                        .map(|event| (event.identity, event.expected_version))
-                        .collect();
-                    concurrent_write_from_conflict(&mut **tx, &candidates).await
-                } else {
-                    // The failed statement aborted the transaction: re-read the
-                    // conflicting streams' actual versions on a separate
-                    // connection, across the whole batch.
-                    let candidates: Vec<_> = prepared
-                        .iter()
-                        .map(|append| (&append.identity, append.expected_version))
-                        .collect();
-                    match pool.acquire().await {
-                        Ok(mut conn) => {
-                            concurrent_write_from_conflict(&mut conn, &candidates).await
-                        }
-                        Err(err) => repository_storage_error::<DB>(
-                            "acquire conflict re-read connection",
-                            err,
-                        ),
-                    }
-                });
-            }
-            Err(err) => return Err(repository_storage_error::<DB>("insert events", err)),
-        }
-    }
-
-    Ok(())
-}
-
-/// After an event-insert unique violation, find the candidate stream whose
-/// actual version no longer matches its expected version and report it as
-/// `ConcurrentWrite`. Falls back to the first candidate if a concurrent
-/// writer's effect cannot be pinned down (the violation still indicates a
-/// conflicting write). Candidates must be non-empty and deduplicated.
-async fn concurrent_write_from_conflict<DB>(
-    conn: &mut DB::Connection,
-    candidates: &[(&StreamIdentity, u64)],
-) -> RepositoryError
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    for &(identity, expected) in candidates {
-        match stream_version(&mut *conn, identity).await {
-            Ok(actual) if actual != expected => {
-                return RepositoryError::ConcurrentWrite {
-                    id: identity.to_string(),
-                    expected,
-                    actual,
-                };
-            }
-            Ok(_) => {}
-            Err(err) => return err,
-        }
-    }
-
-    let (identity, expected) = candidates[0];
-    match stream_version(&mut *conn, identity).await {
-        Ok(actual) => RepositoryError::ConcurrentWrite {
-            id: identity.to_string(),
-            expected,
-            actual,
-        },
-        Err(err) => err,
-    }
-}
-
-/// Current committed version (`MAX(sequence)`, 0 for a missing stream) through
-/// any executor (pool or transaction).
-async fn stream_version<'e, DB, E>(
-    executor: E,
-    identity: &StreamIdentity,
-) -> Result<u64, RepositoryError>
-where
-    DB: SqlxRepoBackend,
-    E: Executor<'e, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    let mut builder = QueryBuilder::<DB>::new(
-        "SELECT MAX(sequence) AS version FROM aggregate_events WHERE aggregate_type = ",
-    );
-    builder.push_bind(identity.aggregate_type());
-    builder.push(" AND aggregate_id = ");
-    builder.push_bind(identity.aggregate_id());
-    let row = builder
-        .build()
-        .fetch_one(executor)
-        .await
-        .map_err(|err| repository_storage_error::<DB>("load stream version", err))?;
-
-    let version: Option<i64> = row
-        .try_get("version")
-        .map_err(|err| repository_storage_error::<DB>("decode stream version row", err))?;
-    version
-        .map(|value| repository_u64_from_i64(DB::BACKEND, value, "sequence"))
-        .unwrap_or(Ok(0))
-}
-
-/// Current committed versions for every stream in the batch, in one grouped
-/// query (`MAX(sequence)` per stream; missing streams simply have no row and
-/// default to 0 at the call site). Chunked so a very large batch stays under
-/// the backend's bound-parameter limit (two binds per stream).
-async fn stream_versions_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    prepared: &[PreparedEventAppend<'_>],
-) -> Result<HashMap<String, u64>, RepositoryError>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    let mut versions = HashMap::with_capacity(prepared.len());
-    if prepared.is_empty() {
-        return Ok(versions);
-    }
-
-    for chunk in prepared.chunks(DB::MAX_BIND_PARAMS / 2) {
-        let mut builder = QueryBuilder::<DB>::new(
-            "SELECT aggregate_type, aggregate_id, MAX(sequence) AS version \
-             FROM aggregate_events WHERE ",
-        );
-        let mut first = true;
-        for append in chunk {
-            if !first {
-                builder.push(" OR ");
-            }
-            first = false;
-            builder.push("(aggregate_type = ");
-            builder.push_bind(append.identity.aggregate_type());
-            builder.push(" AND aggregate_id = ");
-            builder.push_bind(append.identity.aggregate_id());
-            builder.push(")");
-        }
-        builder.push(" GROUP BY aggregate_type, aggregate_id");
-
-        let rows = builder
-            .build()
-            .fetch_all(&mut **tx)
-            .await
-            .map_err(|err| repository_storage_error::<DB>("load stream versions", err))?;
-
-        for row in rows {
-            let aggregate_type: String = row.try_get("aggregate_type").map_err(|err| {
-                repository_storage_error::<DB>("decode stream version aggregate type row", err)
-            })?;
-            let aggregate_id: String = row.try_get("aggregate_id").map_err(|err| {
-                repository_storage_error::<DB>("decode stream version aggregate id row", err)
-            })?;
-            let version: i64 = row
-                .try_get("version")
-                .map_err(|err| repository_storage_error::<DB>("decode stream version row", err))?;
-            versions.insert(
-                StreamIdentity::new(&aggregate_type, &aggregate_id)?.storage_key(),
-                repository_u64_from_i64(DB::BACKEND, version, "sequence")?,
-            );
-        }
-    }
-
-    Ok(versions)
-}
-
-/// One `outbox_messages` row with pre-validated bind values.
-struct OutboxRow<'a, DB: SqlxRepoBackend> {
-    message_id: &'a str,
-    event_type: &'a str,
-    payload: &'a [u8],
-    payload_codec: &'a str,
-    payload_codec_version: i64,
-    destination: Option<&'a str>,
-    metadata: String,
-    status: &'a str,
-    created_at: DB::TimestampValue,
-    worker_id: Option<&'a str>,
-    leased_until: Option<DB::TimestampValue>,
-    attempts: i64,
-    last_error: Option<&'a str>,
-    source_aggregate_type: Option<&'a str>,
-    source_aggregate_id: Option<&'a str>,
-    source_sequence: Option<i64>,
-    correlation_id: Option<&'a str>,
-    causation_id: Option<&'a str>,
-}
-
-/// Insert every outbox message with multi-row INSERTs (chunked to respect the
-/// backend's bound-parameter limit). A unique violation on `message_id` still
-/// maps to `DuplicateOutboxMessageInBatch`.
-async fn insert_outbox_messages_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    messages: &[OutboxMessage],
-) -> Result<(), RepositoryError>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB>,
-    for<'q> Option<i64>: Encode<'q, DB> + Type<DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'q> Option<&'q str>: Encode<'q, DB> + Type<DB>,
-    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
-{
-    if messages.is_empty() {
-        return Ok(());
-    }
-
-    let mut rows = Vec::with_capacity(messages.len());
-    for message in messages {
-        rows.push(OutboxRow::<DB> {
-            message_id: message.id(),
-            event_type: &message.event_type,
-            payload: &message.payload,
-            payload_codec: &message.payload_codec,
-            payload_codec_version: i64::from(message.payload_codec_version),
-            destination: message.destination.as_deref(),
-            metadata: serialize_event_metadata(&message.metadata)?,
-            status: message.status.as_str(),
-            created_at: DB::timestamp_value(message.created_at)?,
-            worker_id: message.worker_id.as_deref(),
-            leased_until: message.leased_until.map(DB::timestamp_value).transpose()?,
-            attempts: i64::from(message.attempts),
-            last_error: message.last_error.as_deref(),
-            source_aggregate_type: message.source_aggregate_type.as_deref(),
-            source_aggregate_id: message.source_aggregate_id.as_deref(),
-            source_sequence: message
-                .source_sequence
-                .map(|value| {
-                    repository_i64_from_u64(
-                        DB::BACKEND,
-                        value,
-                        "outbox source sequence",
-                        DB::INTEGER_STORAGE,
-                    )
-                })
-                .transpose()?,
-            correlation_id: message.correlation_id(),
-            causation_id: message.causation_id(),
-        });
-    }
-
-    for chunk in rows.chunks(DB::MAX_BIND_PARAMS / OUTBOX_BIND_COLUMNS) {
-        let mut builder = QueryBuilder::<DB>::new(
-            "INSERT INTO outbox_messages (\
-             message_id, event_type, payload, payload_codec, payload_codec_version, \
-             destination, metadata, status, created_at, next_available_at, \
-             claimed_by, claimed_until, attempts, last_error, source_aggregate_type, \
-             source_aggregate_id, source_sequence, correlation_id, causation_id) ",
-        );
-        builder.push_values(chunk, |mut row, message| {
-            row.push_bind(message.message_id)
-                .push_bind(message.event_type)
-                .push_bind(message.payload)
-                .push_bind(message.payload_codec)
-                .push_bind(message.payload_codec_version)
-                .push_bind(message.destination);
-            DB::push_metadata(&mut row, message.metadata.as_str());
-            row.push_bind(message.status);
-            // created_at and next_available_at share the same value.
-            DB::push_timestamp(&mut row, &message.created_at);
-            DB::push_timestamp(&mut row, &message.created_at);
-            row.push_bind(message.worker_id);
-            DB::push_optional_timestamp(&mut row, message.leased_until.as_ref());
-            row.push_bind(message.attempts)
-                .push_bind(message.last_error)
-                .push_bind(message.source_aggregate_type)
-                .push_bind(message.source_aggregate_id)
-                .push_bind(message.source_sequence)
-                .push_bind(message.correlation_id)
-                .push_bind(message.causation_id);
-        });
-
-        let result = builder.build().execute(&mut **tx).await;
-        if let Err(err) = result {
-            if DB::is_unique_violation(&err) {
-                // The batch was already deduped (validate_commit_batch), so a
-                // violation means the id collides with a previously committed
-                // row. Report the first id in the chunk, matching the per-row
-                // path's contract.
-                return Err(RepositoryError::DuplicateOutboxMessageInBatch {
-                    id: chunk[0].message_id.to_string(),
-                });
-            }
-            return Err(repository_storage_error::<DB>(
-                "insert outbox messages",
-                err,
-            ));
-        }
-    }
-
-    Ok(())
-}
-
-async fn save_snapshot_in_tx<DB>(
-    tx: &mut Transaction<'_, DB>,
-    identity: &StreamIdentity,
-    record: SnapshotRecord,
-) -> Result<(), RepositoryError>
-where
-    DB: SqlxRepoBackend,
-    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
-    DB::Arguments: IntoArguments<DB>,
-    for<'q> i64: Encode<'q, DB> + Type<DB>,
-    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
-    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
-{
-    validate_snapshot_identity(identity, &record)?;
-
-    let metadata = serialize_event_metadata(&record.metadata)?;
-    let recorded_at = DB::timestamp_value(record.recorded_at)?;
-    let version = repository_i64_from_u64(
-        DB::BACKEND,
-        record.version,
-        "snapshot version",
-        DB::INTEGER_STORAGE,
-    )?;
-    let snapshot_version = repository_i64_from_u64(
-        DB::BACKEND,
-        record.snapshot_version,
-        "snapshot payload version",
-        DB::INTEGER_STORAGE,
-    )?;
-
-    let mut builder = QueryBuilder::<DB>::new(
-        "INSERT INTO aggregate_snapshots (\
-         aggregate_type, aggregate_id, version, snapshot_version, payload, \
-         payload_codec, payload_codec_version, metadata, recorded_at) VALUES (",
-    );
-    {
-        let mut row = builder.separated(", ");
-        row.push_bind(identity.aggregate_type())
-            .push_bind(identity.aggregate_id())
-            .push_bind(version)
-            .push_bind(snapshot_version)
-            .push_bind(record.payload.as_slice())
-            .push_bind(record.payload_codec.as_str())
-            .push_bind(i64::from(record.payload_codec_version));
-        DB::push_metadata(&mut row, metadata.as_str());
-        DB::push_timestamp(&mut row, &recorded_at);
-    }
-    builder.push(
-        ") ON CONFLICT(aggregate_type, aggregate_id) DO UPDATE SET \
-         version = excluded.version, \
-         snapshot_version = excluded.snapshot_version, \
-         payload = excluded.payload, \
-         payload_codec = excluded.payload_codec, \
-         payload_codec_version = excluded.payload_codec_version, \
-         metadata = excluded.metadata, \
-         recorded_at = excluded.recorded_at, \
-         updated_at = ",
-    );
-    builder.push(DB::NOW);
-
-    builder
-        .build()
-        .execute(&mut **tx)
-        .await
-        .map_err(|err| repository_storage_error::<DB>("save snapshot", err))?;
-
-    Ok(())
-}
-
-fn entity_from_events(aggregate_id: String, events: Vec<EventRecord>) -> Entity {
-    let mut entity = Entity::new();
-    entity.set_id(aggregate_id);
-    entity.load_from_history(events);
-    entity
-}
-
-pub(crate) fn event_from_row<DB>(row: DB::Row) -> Result<EventRecord, RepositoryError>
-where
-    DB: SqlxRepoBackend,
-    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    let payload_codec: String = row
-        .try_get("payload_codec")
-        .map_err(|err| repository_storage_error::<DB>("decode payload codec row", err))?;
-    // Nearly every row carries the crate's own codec constant; borrow it
-    // instead of keeping a per-event allocation.
-    let payload_codec = if payload_codec == BITCODE_PAYLOAD_CODEC {
-        Cow::Borrowed(BITCODE_PAYLOAD_CODEC)
-    } else {
-        Cow::Owned(payload_codec)
-    };
-    let payload_codec_version = repository_u16_from_i64(
-        DB::BACKEND,
-        row.try_get("payload_codec_version").map_err(|err| {
-            repository_storage_error::<DB>("decode payload codec version row", err)
-        })?,
-        "payload_codec_version",
-    )?;
-    let metadata_json: String = row
-        .try_get("metadata")
-        .map_err(|err| repository_storage_error::<DB>("decode metadata row", err))?;
-    let metadata = deserialize_event_metadata(&metadata_json)?;
-    let event = EventRecord {
-        event_name: row
-            .try_get("event_name")
-            .map_err(|err| repository_storage_error::<DB>("decode event name row", err))?,
-        payload_codec,
-        payload_codec_version,
-        payload: row
-            .try_get("payload")
-            .map_err(|err| repository_storage_error::<DB>("decode payload row", err))?,
-        event_version: repository_u64_from_i64(
-            DB::BACKEND,
-            row.try_get("event_version")
-                .map_err(|err| repository_storage_error::<DB>("decode event version row", err))?,
-            "event_version",
-        )?,
-        sequence: repository_u64_from_i64(
-            DB::BACKEND,
-            row.try_get("sequence")
-                .map_err(|err| repository_storage_error::<DB>("decode sequence row", err))?,
-            "sequence",
-        )?,
-        timestamp: DB::decode_timestamp(&row, "recorded_at")?,
-        metadata,
-    };
-    validate_supported_event_codec(&event)?;
-    Ok(event)
-}
-
-fn snapshot_from_row<DB>(row: DB::Row) -> Result<SnapshotRecord, RepositoryError>
-where
-    DB: SqlxRepoBackend,
-    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    let metadata_json: String = row
-        .try_get("metadata")
-        .map_err(|err| repository_storage_error::<DB>("decode snapshot metadata row", err))?;
-    Ok(SnapshotRecord {
-        aggregate_type: row.try_get("aggregate_type").map_err(|err| {
-            repository_storage_error::<DB>("decode snapshot aggregate type row", err)
-        })?,
-        aggregate_id: row.try_get("aggregate_id").map_err(|err| {
-            repository_storage_error::<DB>("decode snapshot aggregate id row", err)
-        })?,
-        version: repository_u64_from_i64(
-            DB::BACKEND,
-            row.try_get("version").map_err(|err| {
-                repository_storage_error::<DB>("decode snapshot version row", err)
-            })?,
-            "snapshot version",
-        )?,
-        snapshot_version: repository_u64_from_i64(
-            DB::BACKEND,
-            row.try_get("snapshot_version").map_err(|err| {
-                repository_storage_error::<DB>("decode snapshot payload version row", err)
-            })?,
-            "snapshot payload version",
-        )?,
-        payload_codec: row.try_get("payload_codec").map_err(|err| {
-            repository_storage_error::<DB>("decode snapshot payload codec row", err)
-        })?,
-        payload_codec_version: repository_u16_from_i64(
-            DB::BACKEND,
-            row.try_get("payload_codec_version").map_err(|err| {
-                repository_storage_error::<DB>("decode snapshot payload codec version row", err)
-            })?,
-            "snapshot payload codec version",
-        )?,
-        payload: row
-            .try_get("payload")
-            .map_err(|err| repository_storage_error::<DB>("decode snapshot payload row", err))?,
-        metadata: deserialize_event_metadata(&metadata_json)?,
-        recorded_at: DB::decode_timestamp(&row, "recorded_at")?,
-    })
-}
-
-pub(crate) fn outbox_message_from_row<DB>(row: DB::Row) -> Result<OutboxMessage, RepositoryError>
-where
-    DB: SqlxRepoBackend,
-    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
-    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
-{
-    let status_text: String = row
-        .try_get("status")
-        .map_err(|err| repository_storage_error::<DB>("decode outbox status row", err))?;
-    let status = status_text.parse::<OutboxMessageStatus>().map_err(|_| {
-        RepositoryError::Model(format!(
-            "{} outbox status `{status_text}` is invalid",
-            DB::BACKEND
-        ))
-    })?;
-    let metadata_json: String = row
-        .try_get("metadata")
-        .map_err(|err| repository_storage_error::<DB>("decode outbox metadata row", err))?;
-    let attempts: i64 = row
-        .try_get("attempts")
-        .map_err(|err| repository_storage_error::<DB>("decode outbox attempts row", err))?;
-    let source_sequence = row
-        .try_get::<Option<i64>, _>("source_sequence")
-        .map_err(|err| repository_storage_error::<DB>("decode outbox source sequence row", err))?
-        .map(|value| repository_u64_from_i64(DB::BACKEND, value, "outbox source sequence"))
-        .transpose()?;
-    let mut metadata = deserialize_event_metadata(&metadata_json)?;
-    if let Some(correlation_id) = row
-        .try_get::<Option<String>, _>("correlation_id")
-        .map_err(|err| repository_storage_error::<DB>("decode outbox correlation_id row", err))?
-    {
-        metadata.insert("correlation_id".into(), correlation_id);
-    }
-    if let Some(causation_id) = row
-        .try_get::<Option<String>, _>("causation_id")
-        .map_err(|err| repository_storage_error::<DB>("decode outbox causation_id row", err))?
-    {
-        metadata.insert("causation_id".into(), causation_id);
-    }
-
-    Ok(OutboxMessage {
-        id: row
-            .try_get("message_id")
-            .map_err(|err| repository_storage_error::<DB>("decode outbox message id row", err))?,
-        event_type: row
-            .try_get("event_type")
-            .map_err(|err| repository_storage_error::<DB>("decode outbox event type row", err))?,
-        payload: row
-            .try_get("payload")
-            .map_err(|err| repository_storage_error::<DB>("decode outbox payload row", err))?,
-        payload_codec: row.try_get("payload_codec").map_err(|err| {
-            repository_storage_error::<DB>("decode outbox payload codec row", err)
-        })?,
-        payload_codec_version: repository_u16_from_i64(
-            DB::BACKEND,
-            row.try_get("payload_codec_version").map_err(|err| {
-                repository_storage_error::<DB>("decode outbox payload codec version row", err)
-            })?,
-            "outbox payload codec version",
-        )?,
-        metadata,
-        status,
-        created_at: DB::decode_timestamp(&row, "created_at")?,
-        worker_id: row
-            .try_get("claimed_by")
-            .map_err(|err| repository_storage_error::<DB>("decode outbox claimed_by row", err))?,
-        leased_until: DB::decode_optional_timestamp(&row, "claimed_until")?,
-        attempts: u32::try_from(attempts).map_err(|_| {
-            RepositoryError::Model(format!(
-                "{} outbox attempts value {attempts} is invalid",
-                DB::BACKEND
-            ))
-        })?,
-        last_error: row
-            .try_get("last_error")
-            .map_err(|err| repository_storage_error::<DB>("decode outbox last_error row", err))?,
-        destination: row
-            .try_get("destination")
-            .map_err(|err| repository_storage_error::<DB>("decode outbox destination row", err))?,
-        source_aggregate_type: row.try_get("source_aggregate_type").map_err(|err| {
-            repository_storage_error::<DB>("decode outbox source aggregate type row", err)
-        })?,
-        source_aggregate_id: row.try_get("source_aggregate_id").map_err(|err| {
-            repository_storage_error::<DB>("decode outbox source aggregate id row", err)
-        })?,
-        source_sequence,
-    })
-}
-
-/// Convert a [`SystemTime`] to epoch seconds for database-side comparisons.
-pub(crate) fn system_time_epoch_secs<DB: SqlxRepoBackend>(
-    timestamp: SystemTime,
-) -> Result<f64, RepositoryError> {
-    let duration = timestamp.duration_since(UNIX_EPOCH).map_err(|err| {
-        RepositoryError::Model(format!(
-            "timestamp before UNIX epoch cannot be stored in {}: {err}",
-            DB::BACKEND
-        ))
-    })?;
-    Ok(duration.as_secs_f64())
-}
-
-pub(crate) fn repository_storage_error<DB: SqlxRepoBackend>(
-    operation: &str,
-    err: sqlx::Error,
-) -> RepositoryError {
-    crate::sqlx_repo::repository_storage_error(DB::BACKEND, operation, err)
-}
diff --git a/src/sqlx_repo/repo/backend.rs b/src/sqlx_repo/repo/backend.rs
new file mode 100644
index 00000000..40e927c1
--- /dev/null
+++ b/src/sqlx_repo/repo/backend.rs
@@ -0,0 +1,185 @@
+use super::*;
+
+/// Build an embedded migrator from statically included migration files
+/// (`(version, description, sql)` per file, in order). sqlx's `migrate!`
+/// macro would assemble this at compile time but drags in the whole
+/// proc-macro stack; here the checksums are computed once at first use, so
+/// keep each backend's list in sync with its `migrations/` directory.
+pub(crate) fn embedded_migrator(files: &[(i64, &'static str, &'static str)]) -> Migrator {
+    Migrator::with_migrations(
+        files
+            .iter()
+            .map(|&(version, description, sql)| {
+                Migration::new(
+                    version,
+                    description.into(),
+                    MigrationType::Simple,
+                    sqlx::SqlSafeStr::into_sql_str(sql),
+                    false,
+                )
+            })
+            .collect(),
+    )
+}
+
+/// Group stream identities by aggregate type so each type is one id-list
+/// round trip instead of a query per identity. Callers issue single-type
+/// batches in the common case, so this usually yields one group; the grouping
+/// only exists to keep arbitrary mixed-type inputs correct.
+pub(super) fn ids_by_type(identities: &[StreamIdentity]) -> BTreeMap<&str, Vec<&str>> {
+    let mut groups: BTreeMap<&str, Vec<&str>> = BTreeMap::new();
+    for identity in identities {
+        groups
+            .entry(identity.aggregate_type())
+            .or_default()
+            .push(identity.aggregate_id());
+    }
+    groups
+}
+
+/// Bound parameters per `aggregate_events` row.
+pub(super) const EVENT_BIND_COLUMNS: usize = 10;
+
+/// Bound parameters per `outbox_messages` row.
+pub(super) const OUTBOX_BIND_COLUMNS: usize = 19;
+
+/// Dialect surface for the shared repository path (event store, snapshots,
+/// outbox lifecycle, consumer inbox, schema bootstrap).
+///
+/// Everything the two SQL backends genuinely disagree on is an item here; the
+/// free functions and the [`SqlxRepository`]/[`SqlxOutboxStore`] impls in this
+/// module are the single copy of everything they agree on.
+pub trait SqlxRepoBackend: SqlxReadModelBackend {
+    /// Embedded migrations applied by `migrate_pool`. Runs through
+    /// `sqlx::migrate::Migrator`, which keeps a `_sqlx_migrations` ledger and
+    /// executes each migration file whole (the previous hand-rolled runner
+    /// split files on `;`, which breaks on function bodies and string
+    /// literals, and kept no record of what had been applied).
+    fn migrator() -> &'static Migrator;
+    /// Maximum bound parameters per statement. Multi-row inserts are chunked to
+    /// stay under this; Postgres is effectively unlimited so chunking collapses
+    /// to a single statement and both backends share one code path.
+    const MAX_BIND_PARAMS: usize;
+    /// Whether event-insert conflict recovery re-reads stream versions inside
+    /// the failed transaction. SQLite does not abort a transaction on a
+    /// constraint error, so the re-read can (and must, to see this tx's own
+    /// earlier chunks) happen in-tx. A failed Postgres statement aborts the
+    /// transaction, so the re-read runs on a separate pool connection.
+    const CONFLICT_REREAD_IN_TX: bool;
+    /// SQL expression producing the database's current timestamp, used for
+    /// server-side `updated_at` maintenance.
+    const NOW: &'static str;
+    /// Command-ledger projection with timestamp columns normalized for
+    /// [`decode_timestamp`](Self::decode_timestamp) and JSON surfaced as text.
+    const COMMAND_LEDGER_SELECT: &'static str;
+    /// Row-lock suffix for a reservation/status transaction.
+    const COMMAND_LEDGER_LOCK_SUFFIX: &'static str;
+    /// Row-lock suffix for a bounded compaction scan.
+    const COMMAND_LEDGER_COMPACTION_LOCK_SUFFIX: &'static str;
+    /// `SELECT` list for `aggregate_events` rows. The recorded-at column must
+    /// surface as `recorded_at` in whatever representation
+    /// [`decode_timestamp`](Self::decode_timestamp) reads.
+    const EVENT_SELECT: &'static str;
+    /// `SELECT` list for `aggregate_snapshots` rows (recorded-at as above).
+    const SNAPSHOT_SELECT: &'static str;
+    /// `SELECT` list for `outbox_messages` rows (`created_at`/`claimed_until`
+    /// in the representation `decode_timestamp` reads).
+    const OUTBOX_SELECT: &'static str;
+    /// ORDER BY expression for outbox `created_at` ordering (SQLite stores
+    /// timestamps as text and must cast for numeric ordering).
+    const ORDER_BY_CREATED_AT: &'static str;
+    /// `SELECT` expression for `MIN(created_at)` surfaced as
+    /// `oldest_created_at` in this backend's timestamp representation.
+    const OUTBOX_OLDEST_CREATED_AT_SELECT: &'static str;
+    /// Dialect for table/read-model schema artifact generation.
+    const TABLE_DIALECT: TableSqlDialect;
+
+    /// Owned bind value for a stored timestamp (Postgres: epoch seconds `f64`;
+    /// SQLite: `"secs.nanos"` text).
+    type TimestampValue: Send + Sync + 'static;
+
+    /// Pool size when connecting from a database URL.
+    fn default_pool_size(database_url: &str) -> u32 {
+        let _ = database_url;
+        5
+    }
+
+    /// Whether a `sqlx::Error` is this backend's unique-violation error.
+    fn is_unique_violation(err: &sqlx::Error) -> bool;
+
+    /// Encode a [`SystemTime`] into this backend's stored representation.
+    fn timestamp_value(timestamp: SystemTime) -> Result<Self::TimestampValue, RepositoryError>;
+
+    /// Push a timestamp value into a separated bind list (Postgres wraps the
+    /// bind in `to_timestamp(...)`).
+    fn push_timestamp(sep: &mut Separated<'_, Self, &'static str>, value: &Self::TimestampValue);
+
+    /// Push an optional timestamp value into a separated bind list, binding a
+    /// typed `NULL` when absent.
+    fn push_optional_timestamp(
+        sep: &mut Separated<'_, Self, &'static str>,
+        value: Option<&Self::TimestampValue>,
+    );
+
+    /// Push `<assignment target> = <timestamp>` right-hand side into a builder.
+    fn push_timestamp_assign(builder: &mut QueryBuilder<Self>, value: &Self::TimestampValue);
+
+    /// Push `<column> <op> <now>` comparing a stored timestamp column against
+    /// epoch seconds (Postgres: `column op to_timestamp($n)`; SQLite:
+    /// `CAST(column AS REAL) op ?`).
+    fn push_timestamp_cmp(
+        builder: &mut QueryBuilder<Self>,
+        column: &'static str,
+        op: &'static str,
+        epoch_secs: f64,
+    );
+
+    /// Push a non-transaction-start database clock expression. PostgreSQL uses
+    /// `clock_timestamp()` so time spent waiting for a row lock counts against
+    /// leases; SQLite uses its subsecond unix epoch clock.
+    fn push_command_ledger_now(builder: &mut QueryBuilder<Self>);
+
+    /// Push the same database clock as epoch seconds for decoding into
+    /// [`SystemTime`]. This is distinct from [`Self::push_command_ledger_now`]
+    /// because PostgreSQL write/comparison expressions require `timestamptz`
+    /// while this framework's portable timestamp decoder consumes `f64`.
+    fn push_command_ledger_now_epoch(builder: &mut QueryBuilder<Self>);
+
+    /// Push database-now plus a caller-validated positive duration.
+    fn push_command_ledger_deadline(builder: &mut QueryBuilder<Self>, duration: Duration);
+
+    /// Push a JSON value bind, adding the backend's native JSON cast if needed.
+    fn push_command_ledger_json(builder: &mut QueryBuilder<Self>, json: &str);
+
+    /// Decode a stored timestamp column into a [`SystemTime`].
+    fn decode_timestamp(
+        row: &Self::Row,
+        column: &'static str,
+    ) -> Result<SystemTime, RepositoryError>;
+
+    /// Decode a nullable stored timestamp column.
+    fn decode_optional_timestamp(
+        row: &Self::Row,
+        column: &'static str,
+    ) -> Result<Option<SystemTime>, RepositoryError>;
+
+    /// Push a metadata JSON bind (Postgres casts to `::jsonb`).
+    fn push_metadata(sep: &mut Separated<'_, Self, &'static str>, json: &str);
+
+    /// Push an `aggregate_id` filter for an id list (Postgres: `= ANY($n)`
+    /// array bind; SQLite: `IN (?, ?, ...)`).
+    fn push_id_filter(builder: &mut QueryBuilder<Self>, ids: &[&str]);
+
+    /// Build the consumer-inbox retention `DELETE` for a cutoff age, evaluated
+    /// against the database clock.
+    fn inbox_purge_query(age: Duration) -> QueryBuilder<Self>;
+
+    /// Claim up to `batch_size` outbox messages. This is the one genuinely
+    /// divergent operation: Postgres uses a CTE with `FOR UPDATE SKIP LOCKED`;
+    /// SQLite (no row locks) scans candidates and claims them with per-id
+    /// conditional updates.
+    fn claim_outbox<'a>(
+        pool: &'a Pool<Self>,
+        request: ClaimOutboxMessages,
+    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + 'a;
+}
diff --git a/src/sqlx_repo/repo/commit.rs b/src/sqlx_repo/repo/commit.rs
new file mode 100644
index 00000000..f0a7786f
--- /dev/null
+++ b/src/sqlx_repo/repo/commit.rs
@@ -0,0 +1,1141 @@
+use super::*;
+
+async fn preflight_command_completion_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    completion: &CommandCompletion,
+) -> Result<(), CommandLedgerError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let fence = completion.attempt_fence();
+
+    // SQLite needs a write statement to reserve the database writer before
+    // the read; PostgreSQL's subsequent SELECT also carries FOR UPDATE. This
+    // establishes one portable lock order before any domain participant is
+    // mutated.
+    let mut lock = QueryBuilder::<DB>::new(
+        "UPDATE command_ledger SET updated_at = updated_at WHERE service_id = ",
+    );
+    lock.push_bind(fence.key().service_id());
+    lock.push(" AND principal_partition = ");
+    lock.push_bind(fence.key().principal_partition());
+    lock.push(" AND command_id = ");
+    lock.push_bind(fence.key().command_id());
+    let result =
+        lock.build().execute(&mut **tx).await.map_err(|error| {
+            repository_storage_error::<DB>("lock command attempt preflight", error)
+        })?;
+    if DB::rows_affected(&result) != 1 {
+        return Err(CommandLedgerError::AttemptFenced {
+            command_id: fence.key().command_id().to_string(),
+        });
+    }
+
+    let record = select_command_ledger_record_in_tx(tx, fence.key(), None)
+        .await?
+        .ok_or_else(|| CommandLedgerError::AttemptFenced {
+            command_id: fence.key().command_id().to_string(),
+        })?;
+    let now = command_ledger_now_in_tx(tx).await?;
+    record.validate_live_attempt(&fence, now)
+}
+
+async fn commit_sqlx_batch<'a, DB>(
+    repository: &'a SqlxRepository<DB>,
+    batch: CommitBatch<'a>,
+    mut completion: Option<CommandCompletion>,
+    direct_projection: Option<SameTransactionProjectionBatch>,
+) -> Result<(), CommandLedgerError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> f64: Encode<'q, DB> + Type<DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'q> Option<i64>: Encode<'q, DB> + Type<DB>,
+    for<'q> Option<&'q str>: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let prepared = validate_commit_batch(&batch)?;
+    for plan in &batch.read_model_plans {
+        validate_sql_write_plan(plan).map_err(RepositoryError::from)?;
+    }
+    if let Some(direct_projection) = &direct_projection {
+        direct_projection.validate().map_err(|error| {
+            CommandLedgerError::Storage(RepositoryError::Model(error.to_string()))
+        })?;
+        let completion = completion.as_ref().ok_or_else(|| {
+            CommandLedgerError::Invalid(
+                "same-transaction direct projection requires a command completion".into(),
+            )
+        })?;
+        if direct_projection.causation_id != completion.attempt().causation_id().as_str() {
+            return Err(CommandLedgerError::Invalid(
+                "direct projection causation differs from its command attempt".into(),
+            ));
+        }
+    }
+
+    let mut tx = repository
+        .pool
+        .begin()
+        .await
+        .map_err(|err| repository_storage_error::<DB>("begin commit transaction", err))?;
+    if let Some(completion) = completion.as_ref() {
+        preflight_command_completion_in_tx(&mut tx, completion).await?;
+    }
+
+    let requested_tables = batch
+        .read_model_plans
+        .iter()
+        .flat_map(|plan| plan.mutations.iter())
+        .map(|mutation| mutation.table_name().to_string())
+        .collect::<std::collections::BTreeSet<_>>();
+    reject_causal_table_writes_in_tx(&mut tx, &requested_tables)
+        .await
+        .map_err(RepositoryError::from)?;
+
+    let versions = stream_versions_in_tx(&mut tx, &prepared).await?;
+    for append in &prepared {
+        let actual = versions
+            .get(&append.identity.storage_key())
+            .copied()
+            .unwrap_or(0);
+        if actual != append.expected_version {
+            return Err(RepositoryError::ConcurrentWrite {
+                id: append.identity.to_string(),
+                expected: append.expected_version,
+                actual,
+            }
+            .into());
+        }
+    }
+
+    insert_events_in_tx(&repository.pool, &mut tx, &prepared).await?;
+    insert_outbox_messages_in_tx(&mut tx, &batch.outbox_messages).await?;
+
+    let mut changed_tables = std::collections::BTreeSet::new();
+    for plan in batch.read_model_plans {
+        for mutation in &plan.mutations {
+            changed_tables.insert(mutation.table_name().to_string());
+        }
+        apply_read_model_write_plan_in_tx(&mut tx, plan)
+            .await
+            .map_err(RepositoryError::from)?;
+    }
+
+    if let Some(direct_projection) = &direct_projection {
+        let evidence = apply_same_transaction_projection_in_tx(
+            &mut tx,
+            direct_projection,
+            repository.projection_change_retention,
+        )
+        .await
+        .map_err(|error| CommandLedgerError::Storage(RepositoryError::Model(error.to_string())))?;
+        let completion = completion
+            .as_mut()
+            .expect("direct projection completion was validated before opening its transaction");
+        completion.attach_direct_projection(&evidence)?;
+        for mutation in &direct_projection.mutations {
+            changed_tables.insert(mutation.mutation.table_name().to_string());
+        }
+        changed_tables.insert(PROJECTION_CHANGE_NOTIFY_TABLE.to_string());
+    }
+
+    for write in batch.snapshots {
+        match write {
+            SnapshotWrite::Save { identity, record } => {
+                save_snapshot_in_tx(&mut tx, &identity, record).await?;
+            }
+        }
+    }
+    for receipt in &batch.inbox_receipts {
+        insert_inbox_receipt_in_tx(&mut tx, receipt).await?;
+    }
+
+    if repository.notify_enabled && !changed_tables.is_empty() {
+        DB::push_change_notify(&mut *tx, &changed_tables)
+            .await
+            .map_err(RepositoryError::from)?;
+    }
+
+    // This fenced terminal update is intentionally the final SQL statement
+    // before COMMIT. A stale/expired generation affects zero rows and rolls
+    // back every domain write above with the surrounding transaction.
+    if let Some(completion) = completion.as_ref() {
+        complete_command_in_tx(&mut tx, completion).await?;
+    }
+
+    tx.commit()
+        .await
+        .map_err(|err| repository_storage_error::<DB>("commit transaction", err))?;
+
+    if !changed_tables.is_empty() {
+        repository.publish_read_model_change(crate::ReadModelChange {
+            tables: changed_tables,
+        });
+    }
+    for stream in batch.streams {
+        stream.entity.mark_committed();
+    }
+    Ok(())
+}
+
+impl<DB> TransactionalCommit for SqlxRepository<DB>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> f64: Encode<'q, DB> + Type<DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'q> Option<i64>: Encode<'q, DB> + Type<DB>,
+    for<'q> Option<&'q str>: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    fn commit_batch<'a>(
+        &'a self,
+        batch: CommitBatch<'a>,
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+        async move {
+            match commit_sqlx_batch(self, batch, None, None).await {
+                Ok(()) => Ok(()),
+                Err(CommandLedgerError::Storage(error)) => Err(error),
+                Err(error) => Err(RepositoryError::Model(format!(
+                    "unexpected command ledger error in ordinary commit: {error}"
+                ))),
+            }
+        }
+    }
+}
+
+impl<DB> CausalTransactionalCommit for SqlxRepository<DB>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> f64: Encode<'q, DB> + Type<DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'q> Option<i64>: Encode<'q, DB> + Type<DB>,
+    for<'q> Option<&'q str>: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    fn commit_causal_batch<'a>(
+        &'a self,
+        batch: CausalCommitBatch<'a>,
+    ) -> impl Future<Output = Result<(), CommandLedgerError>> + Send + 'a {
+        commit_sqlx_batch(
+            self,
+            batch.domain,
+            Some(batch.completion),
+            batch.direct_projection,
+        )
+    }
+}
+
+fn corrupt_ledger_value(error: CommandLedgerError) -> CommandLedgerError {
+    CommandLedgerError::Corrupt(error.to_string())
+}
+
+#[allow(dead_code)]
+fn command_ledger_key_from_row<DB>(row: &DB::Row) -> Result<CommandLedgerKey, CommandLedgerError>
+where
+    DB: SqlxRepoBackend,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let service_id: String = row.try_get("service_id").map_err(|error| {
+        repository_storage_error::<DB>("decode command ledger service ID", error)
+    })?;
+    let principal: String = row.try_get("principal_partition").map_err(|error| {
+        repository_storage_error::<DB>("decode command ledger principal partition", error)
+    })?;
+    let command_id: String = row.try_get("command_id").map_err(|error| {
+        repository_storage_error::<DB>("decode command ledger command ID", error)
+    })?;
+    CommandLedgerKey::new(
+        service_id,
+        PrincipalPartitionId::new(principal).map_err(corrupt_ledger_value)?,
+        CommandId::parse(command_id).map_err(corrupt_ledger_value)?,
+    )
+    .map_err(corrupt_ledger_value)
+}
+
+fn command_ledger_record_from_row<DB>(
+    row: &DB::Row,
+    key: CommandLedgerKey,
+) -> Result<CommandLedgerRecord, CommandLedgerError>
+where
+    DB: SqlxRepoBackend,
+    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let decode = |operation: &'static str, error| repository_storage_error::<DB>(operation, error);
+    let command_name: String = row
+        .try_get("command_name")
+        .map_err(|error| decode("decode command ledger name", error))?;
+    let contract: Vec<u8> = row
+        .try_get("command_contract_hash")
+        .map_err(|error| decode("decode command contract hash", error))?;
+    let input: Vec<u8> = row
+        .try_get("input_hash")
+        .map_err(|error| decode("decode canonical command input hash", error))?;
+    let state: String = row
+        .try_get("state")
+        .map_err(|error| decode("decode command ledger state", error))?;
+    let causation_id: String = row
+        .try_get("causation_id")
+        .map_err(|error| decode("decode command ledger causation ID", error))?;
+    let attempt_token: Option<String> = row
+        .try_get("attempt_token")
+        .map_err(|error| decode("decode command ledger attempt token", error))?;
+    let attempt_number: i64 = row
+        .try_get("attempt_number")
+        .map_err(|error| decode("decode command ledger attempt number", error))?;
+    let outcome_json: Option<String> = row
+        .try_get("outcome")
+        .map_err(|error| decode("decode command ledger outcome", error))?;
+
+    let record = CommandLedgerRecord {
+        key,
+        command_name,
+        contract_fingerprint: CommandContractFingerprint::try_from_slice(&contract)
+            .map_err(corrupt_ledger_value)?,
+        input_hash: CanonicalInputHash::try_from_slice(&input).map_err(corrupt_ledger_value)?,
+        state: CommandLedgerState::parse(&state)?,
+        causation_id: CausationId::parse_stored(causation_id)?,
+        attempt_token: attempt_token.map(AttemptToken::parse_stored).transpose()?,
+        attempt_number: repository_u64_from_i64(
+            DB::BACKEND,
+            attempt_number,
+            "command ledger attempt number",
+        )?,
+        lease_expires_at: DB::decode_optional_timestamp(row, "lease_expires_at")?,
+        outcome_json,
+        created_at: DB::decode_timestamp(row, "created_at")?,
+        updated_at: DB::decode_timestamp(row, "updated_at")?,
+        completed_at: DB::decode_optional_timestamp(row, "completed_at")?,
+        retention_expires_at: DB::decode_timestamp(row, "retention_expires_at")?,
+        compacted_at: DB::decode_optional_timestamp(row, "compacted_at")?,
+    };
+    record.validate_stored_shape()?;
+    Ok(record)
+}
+
+async fn command_ledger_now_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+) -> Result<SystemTime, CommandLedgerError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let mut builder = QueryBuilder::<DB>::new("SELECT ");
+    DB::push_command_ledger_now_epoch(&mut builder);
+    builder.push(" AS ledger_now");
+    let row = builder
+        .build()
+        .fetch_one(&mut **tx)
+        .await
+        .map_err(|error| repository_storage_error::<DB>("read command ledger clock", error))?;
+    Ok(DB::decode_timestamp(&row, "ledger_now")?)
+}
+
+async fn select_command_ledger_record_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    key: &CommandLedgerKey,
+    expected_command_name: Option<&str>,
+) -> Result<Option<CommandLedgerRecord>, CommandLedgerError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let mut builder = QueryBuilder::<DB>::new("SELECT ");
+    builder.push(DB::COMMAND_LEDGER_SELECT);
+    builder.push(" FROM command_ledger WHERE service_id = ");
+    builder.push_bind(key.service_id());
+    builder.push(" AND principal_partition = ");
+    builder.push_bind(key.principal_partition());
+    builder.push(" AND command_id = ");
+    builder.push_bind(key.command_id());
+    if let Some(expected_command_name) = expected_command_name {
+        builder.push(" AND command_name = ");
+        builder.push_bind(expected_command_name);
+    }
+    builder.push(DB::COMMAND_LEDGER_LOCK_SUFFIX);
+    let row = builder
+        .build()
+        .fetch_optional(&mut **tx)
+        .await
+        .map_err(|error| repository_storage_error::<DB>("select command ledger row", error))?;
+    row.map(|row| command_ledger_record_from_row::<DB>(&row, key.clone()))
+        .transpose()
+}
+
+async fn insert_command_reservation_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    reservation: &CommandReservation,
+) -> Result<bool, CommandLedgerError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> f64: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    let mut builder = QueryBuilder::<DB>::new(
+        "INSERT INTO command_ledger (service_id, principal_partition, command_id, \
+         command_name, command_contract_hash, input_hash, state, causation_id, attempt_token, \
+         attempt_number, lease_expires_at, outcome, created_at, updated_at, completed_at, \
+         retention_expires_at, compacted_at) VALUES (",
+    );
+    builder.push_bind(reservation.key().service_id());
+    builder.push(", ");
+    builder.push_bind(reservation.key().principal_partition());
+    builder.push(", ");
+    builder.push_bind(reservation.key().command_id());
+    builder.push(", ");
+    builder.push_bind(reservation.command_name());
+    builder.push(", ");
+    builder.push_bind(reservation.contract_fingerprint_bytes().as_slice());
+    builder.push(", ");
+    builder.push_bind(reservation.input_hash_bytes().as_slice());
+    builder.push(", ");
+    builder.push_bind(CommandLedgerState::InProgress.as_str());
+    builder.push(", ");
+    builder.push_bind(reservation.candidate_causation().as_str());
+    builder.push(", ");
+    builder.push_bind(reservation.candidate_attempt().as_str());
+    builder.push(", ");
+    builder.push_bind(1_i64);
+    builder.push(", ");
+    DB::push_command_ledger_deadline(&mut builder, reservation.lease());
+    builder.push(", NULL, ");
+    DB::push_command_ledger_now(&mut builder);
+    builder.push(", ");
+    DB::push_command_ledger_now(&mut builder);
+    builder.push(", NULL, ");
+    DB::push_command_ledger_deadline(&mut builder, reservation.retention());
+    builder.push(", NULL");
+    builder.push(") ON CONFLICT (service_id, principal_partition, command_id) DO NOTHING");
+    let result = builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|error| repository_storage_error::<DB>("insert command reservation", error))?;
+    Ok(DB::rows_affected(&result) == 1)
+}
+
+async fn expire_command_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    key: &CommandLedgerKey,
+    require_retention_due: bool,
+) -> Result<u64, CommandLedgerError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+{
+    let mut builder = QueryBuilder::<DB>::new(
+        "UPDATE command_ledger SET state = 'expired', attempt_token = NULL, \
+         lease_expires_at = NULL, outcome = NULL, updated_at = ",
+    );
+    DB::push_command_ledger_now(&mut builder);
+    builder.push(", compacted_at = ");
+    DB::push_command_ledger_now(&mut builder);
+    builder.push(" WHERE service_id = ");
+    builder.push_bind(key.service_id());
+    builder.push(" AND principal_partition = ");
+    builder.push_bind(key.principal_partition());
+    builder.push(" AND command_id = ");
+    builder.push_bind(key.command_id());
+    builder.push(" AND state <> 'expired'");
+    if require_retention_due {
+        builder.push(" AND retention_expires_at <= ");
+        DB::push_command_ledger_now(&mut builder);
+    }
+    let result = builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|error| repository_storage_error::<DB>("expire command ledger row", error))?;
+    Ok(DB::rows_affected(&result))
+}
+
+async fn reclaim_command_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    record: &mut CommandLedgerRecord,
+    reservation: &CommandReservation,
+    now: SystemTime,
+) -> Result<(), CommandLedgerError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> f64: Encode<'q, DB> + Type<DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+{
+    record.reclaim(reservation, now)?;
+    let attempt_number = repository_i64_from_u64(
+        DB::BACKEND,
+        record.attempt_number,
+        "command ledger attempt number",
+        DB::INTEGER_STORAGE,
+    )?;
+    let mut builder = QueryBuilder::<DB>::new(
+        "UPDATE command_ledger SET state = 'in_progress', attempt_token = ",
+    );
+    builder.push_bind(reservation.candidate_attempt().as_str());
+    builder.push(", attempt_number = ");
+    builder.push_bind(attempt_number);
+    builder.push(", lease_expires_at = ");
+    DB::push_command_ledger_deadline(&mut builder, reservation.lease());
+    builder.push(", outcome = NULL, updated_at = ");
+    DB::push_command_ledger_now(&mut builder);
+    builder.push(", completed_at = NULL, retention_expires_at = ");
+    DB::push_command_ledger_deadline(&mut builder, reservation.retention());
+    builder.push(", compacted_at = NULL WHERE service_id = ");
+    builder.push_bind(record.key.service_id());
+    builder.push(" AND principal_partition = ");
+    builder.push_bind(record.key.principal_partition());
+    builder.push(" AND command_id = ");
+    builder.push_bind(record.key.command_id());
+    let result = builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|error| repository_storage_error::<DB>("reclaim command attempt", error))?;
+    if DB::rows_affected(&result) != 1 {
+        return Err(CommandLedgerError::AttemptFenced {
+            command_id: record.key.command_id().to_string(),
+        });
+    }
+    Ok(())
+}
+
+async fn complete_command_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    completion: &CommandCompletion,
+) -> Result<(), CommandLedgerError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> f64: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    let fence = completion.attempt_fence();
+    let attempt_number = repository_i64_from_u64(
+        DB::BACKEND,
+        fence.attempt_number(),
+        "command ledger attempt number",
+        DB::INTEGER_STORAGE,
+    )?;
+    let terminal_state = CommandLedgerState::from(completion.state()).as_str();
+    let mut builder = QueryBuilder::<DB>::new("UPDATE command_ledger SET state = ");
+    builder.push_bind(terminal_state);
+    builder.push(", attempt_token = NULL, lease_expires_at = NULL, outcome = ");
+    DB::push_command_ledger_json(&mut builder, completion.replay_json());
+    builder.push(", updated_at = ");
+    DB::push_command_ledger_now(&mut builder);
+    builder.push(", completed_at = ");
+    DB::push_command_ledger_now(&mut builder);
+    builder.push(", retention_expires_at = ");
+    DB::push_command_ledger_deadline(&mut builder, completion.retention());
+    builder.push(", compacted_at = NULL WHERE service_id = ");
+    builder.push_bind(fence.key().service_id());
+    builder.push(" AND principal_partition = ");
+    builder.push_bind(fence.key().principal_partition());
+    builder.push(" AND command_id = ");
+    builder.push_bind(fence.key().command_id());
+    builder.push(" AND command_contract_hash = ");
+    builder.push_bind(fence.contract_fingerprint_bytes().as_slice());
+    builder.push(" AND input_hash = ");
+    builder.push_bind(fence.input_hash_bytes().as_slice());
+    builder.push(" AND state = 'in_progress' AND causation_id = ");
+    builder.push_bind(fence.causation_id().as_str());
+    builder.push(" AND attempt_token = ");
+    builder.push_bind(fence.attempt_token().as_str());
+    builder.push(" AND attempt_number = ");
+    builder.push_bind(attempt_number);
+    builder.push(" AND lease_expires_at > ");
+    DB::push_command_ledger_now(&mut builder);
+    let result =
+        builder.build().execute(&mut **tx).await.map_err(|error| {
+            repository_storage_error::<DB>("complete command ledger row", error)
+        })?;
+    if DB::rows_affected(&result) != 1 {
+        return Err(CommandLedgerError::AttemptFenced {
+            command_id: fence.key().command_id().to_string(),
+        });
+    }
+    Ok(())
+}
+
+impl<DB> CommandLedgerStore for SqlxRepository<DB>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> f64: Encode<'q, DB> + Type<DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    fn reserve_command(
+        &self,
+        reservation: CommandReservation,
+    ) -> impl Future<Output = Result<ReservationOutcome, CommandLedgerError>> + Send + '_ {
+        async move {
+            let mut tx = self.pool.begin().await.map_err(|error| {
+                repository_storage_error::<DB>("begin command reservation", error)
+            })?;
+            if insert_command_reservation_in_tx(&mut tx, &reservation).await? {
+                tx.commit().await.map_err(|error| {
+                    repository_storage_error::<DB>("commit command reservation", error)
+                })?;
+                return Ok(ReservationOutcome::Acquired(
+                    reservation.acquired_candidate_attempt(),
+                ));
+            }
+
+            let mut record = select_command_ledger_record_in_tx(&mut tx, reservation.key(), None)
+                .await?
+                .ok_or_else(|| {
+                    CommandLedgerError::Corrupt(format!(
+                        "conflicting command `{}` disappeared during reservation",
+                        reservation.key().command_id()
+                    ))
+                })?;
+            let now = command_ledger_now_in_tx(&mut tx).await?;
+            let decision = record.classify_reservation(&reservation, now)?;
+            let outcome = match decision {
+                ReservationDecision::Expire => {
+                    expire_command_in_tx(&mut tx, reservation.key(), false).await?;
+                    ReservationOutcome::Expired
+                }
+                ReservationDecision::Reclaim => {
+                    reclaim_command_in_tx(&mut tx, &mut record, &reservation, now).await?;
+                    ReservationOutcome::Acquired(record.acquired_attempt()?)
+                }
+                other => record.reservation_outcome(other)?,
+            };
+            tx.commit().await.map_err(|error| {
+                repository_storage_error::<DB>("commit command reservation decision", error)
+            })?;
+            Ok(outcome)
+        }
+    }
+
+    fn lookup_command<'a>(
+        &'a self,
+        key: &'a CommandLedgerKey,
+        scope: CommandLookupScope<'a>,
+    ) -> impl Future<Output = Result<CommandLookup, CommandLedgerError>> + Send + 'a {
+        async move {
+            let mut tx = self.pool.begin().await.map_err(|error| {
+                repository_storage_error::<DB>("begin command ledger lookup", error)
+            })?;
+
+            // Establish SQLite's single-writer reservation before selecting;
+            // PostgreSQL additionally takes the row lock through its suffix.
+            let mut lock = QueryBuilder::<DB>::new(
+                "UPDATE command_ledger SET updated_at = updated_at WHERE service_id = ",
+            );
+            lock.push_bind(key.service_id());
+            lock.push(" AND principal_partition = ");
+            lock.push_bind(key.principal_partition());
+            lock.push(" AND command_id = ");
+            lock.push_bind(key.command_id());
+            match scope {
+                CommandLookupScope::CommandName(expected_command_name)
+                | CommandLookupScope::CommandContract {
+                    command_name: expected_command_name,
+                    ..
+                } => {
+                    lock.push(" AND command_name = ");
+                    lock.push_bind(expected_command_name);
+                }
+                CommandLookupScope::Attempt(_) => {}
+            }
+            lock.build().execute(&mut *tx).await.map_err(|error| {
+                repository_storage_error::<DB>("lock command ledger lookup", error)
+            })?;
+
+            let expected_command_name = match scope {
+                CommandLookupScope::CommandName(expected) => Some(expected),
+                CommandLookupScope::CommandContract {
+                    command_name: expected,
+                    ..
+                } => Some(expected),
+                CommandLookupScope::Attempt(_) => None,
+            };
+            let Some(mut record) =
+                select_command_ledger_record_in_tx(&mut tx, key, expected_command_name).await?
+            else {
+                tx.commit().await.map_err(|error| {
+                    repository_storage_error::<DB>("commit empty command ledger lookup", error)
+                })?;
+                return Ok(CommandLookup::Unknown);
+            };
+            if !record.matches_lookup_scope(scope) {
+                tx.commit().await.map_err(|error| {
+                    repository_storage_error::<DB>("commit mismatched command ledger lookup", error)
+                })?;
+                return Ok(CommandLookup::Unknown);
+            }
+            let now = command_ledger_now_in_tx(&mut tx).await?;
+            if record.state != CommandLedgerState::Expired && record.retention_expires_at <= now {
+                expire_command_in_tx(&mut tx, key, true).await?;
+                record.expire(now);
+            }
+            let lookup = record.lookup()?;
+            tx.commit().await.map_err(|error| {
+                repository_storage_error::<DB>("commit command ledger lookup", error)
+            })?;
+            Ok(lookup)
+        }
+    }
+
+    fn mark_retryable_unknown(
+        &self,
+        attempt: AttemptFence,
+    ) -> impl Future<Output = Result<(), CommandLedgerError>> + Send + '_ {
+        async move {
+            let attempt_number = repository_i64_from_u64(
+                DB::BACKEND,
+                attempt.attempt_number(),
+                "command ledger attempt number",
+                DB::INTEGER_STORAGE,
+            )?;
+            let mut builder = QueryBuilder::<DB>::new(
+                "UPDATE command_ledger SET state = 'retryable_unknown', attempt_token = NULL, \
+                 lease_expires_at = NULL, updated_at = ",
+            );
+            DB::push_command_ledger_now(&mut builder);
+            builder.push(" WHERE service_id = ");
+            builder.push_bind(attempt.key().service_id());
+            builder.push(" AND principal_partition = ");
+            builder.push_bind(attempt.key().principal_partition());
+            builder.push(" AND command_id = ");
+            builder.push_bind(attempt.key().command_id());
+            builder.push(" AND command_contract_hash = ");
+            builder.push_bind(attempt.contract_fingerprint_bytes().as_slice());
+            builder.push(" AND input_hash = ");
+            builder.push_bind(attempt.input_hash_bytes().as_slice());
+            builder.push(" AND state = 'in_progress' AND causation_id = ");
+            builder.push_bind(attempt.causation_id().as_str());
+            builder.push(" AND attempt_token = ");
+            builder.push_bind(attempt.attempt_token().as_str());
+            builder.push(" AND attempt_number = ");
+            builder.push_bind(attempt_number);
+            let result = builder.build().execute(&self.pool).await.map_err(|error| {
+                repository_storage_error::<DB>("mark command retryable unknown", error)
+            })?;
+            if DB::rows_affected(&result) != 1 {
+                return Err(CommandLedgerError::AttemptFenced {
+                    command_id: attempt.key().command_id().to_string(),
+                });
+            }
+            Ok(())
+        }
+    }
+
+    fn compact_expired_commands(
+        &self,
+        limit: usize,
+    ) -> impl Future<Output = Result<u64, CommandLedgerError>> + Send + '_ {
+        async move {
+            if limit == 0 {
+                return Ok(0);
+            }
+            let limit = i64::try_from(limit).map_err(|_| {
+                CommandLedgerError::Invalid("command compaction limit exceeds i64".into())
+            })?;
+            let mut tx = self.pool.begin().await.map_err(|error| {
+                repository_storage_error::<DB>("begin command ledger compaction", error)
+            })?;
+
+            // A no-op write obtains SQLite's transaction-wide writer lock.
+            // PostgreSQL relies on the per-row SKIP LOCKED suffix below.
+            QueryBuilder::<DB>::new(
+                "UPDATE command_ledger SET updated_at = updated_at WHERE 1 = 0",
+            )
+            .build()
+            .execute(&mut *tx)
+            .await
+            .map_err(|error| {
+                repository_storage_error::<DB>("lock command ledger compaction", error)
+            })?;
+
+            let mut select = QueryBuilder::<DB>::new(
+                "SELECT service_id, principal_partition, command_id FROM command_ledger \
+                 WHERE state <> 'expired' AND retention_expires_at <= ",
+            );
+            DB::push_command_ledger_now(&mut select);
+            select.push(" ORDER BY retention_expires_at, service_id, principal_partition, command_id LIMIT ");
+            select.push_bind(limit);
+            select.push(DB::COMMAND_LEDGER_COMPACTION_LOCK_SUFFIX);
+            let rows = select.build().fetch_all(&mut *tx).await.map_err(|error| {
+                repository_storage_error::<DB>("select command ledger compaction rows", error)
+            })?;
+            let mut compacted = 0;
+            for row in rows {
+                let key = command_ledger_key_from_row::<DB>(&row)?;
+                compacted += expire_command_in_tx(&mut tx, &key, true).await?;
+            }
+            tx.commit().await.map_err(|error| {
+                repository_storage_error::<DB>("commit command ledger compaction", error)
+            })?;
+            Ok(compacted)
+        }
+    }
+}
+/// Record a consumer inbox receipt in the commit transaction. The
+/// `(consumer, message_id)` primary key is the dedupe gate: a unique violation
+/// means the message was already processed, so the whole batch rolls back and
+/// the effects are not double-applied. `processed_at` defaults server-side.
+async fn insert_inbox_receipt_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    receipt: &InboxReceipt,
+) -> Result<(), RepositoryError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+{
+    receipt.validate()?;
+    let mut builder =
+        QueryBuilder::<DB>::new("INSERT INTO consumer_inbox (consumer, message_id) VALUES (");
+    builder.push_bind(receipt.consumer.as_str());
+    builder.push(", ");
+    builder.push_bind(receipt.message_id.as_str());
+    builder.push(")");
+    let result = builder.build().execute(&mut **tx).await;
+    match result {
+        Ok(_) => Ok(()),
+        Err(err) if DB::is_unique_violation(&err) => Err(RepositoryError::DuplicateInboxReceipt {
+            consumer: receipt.consumer.clone(),
+            message_id: receipt.message_id.clone(),
+        }),
+        Err(err) => Err(repository_storage_error::<DB>(
+            "insert consumer inbox receipt",
+            err,
+        )),
+    }
+}
+
+/// One `aggregate_events` row with pre-validated bind values, built before the
+/// query so any conversion error surfaces before we touch the database. The
+/// stream identity and expected version ride along for conflict recovery.
+struct EventRow<'a, DB: SqlxRepoBackend> {
+    identity: &'a StreamIdentity,
+    expected_version: u64,
+    sequence: i64,
+    event_name: &'a str,
+    event_version: i64,
+    payload: &'a [u8],
+    payload_codec: &'a str,
+    payload_codec_version: i64,
+    metadata: String,
+    recorded_at: DB::TimestampValue,
+}
+
+/// Insert every event across all prepared appends with multi-row INSERTs,
+/// chunked to respect the backend's bound-parameter limit (Postgres is
+/// effectively unlimited, so its chunking collapses to one statement).
+///
+/// Conflict detection is unchanged from the per-row path: the `(aggregate_type,
+/// aggregate_id, sequence)` primary key is the contiguity gate, and a unique
+/// violation still surfaces as `ConcurrentWrite`. Recovery re-reads stream
+/// versions in-tx or over the pool depending on
+/// [`SqlxRepoBackend::CONFLICT_REREAD_IN_TX`].
+async fn insert_events_in_tx<DB>(
+    pool: &Pool<DB>,
+    tx: &mut Transaction<'_, DB>,
+    prepared: &[PreparedEventAppend<'_>],
+) -> Result<(), RepositoryError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let mut rows = Vec::new();
+    for append in prepared {
+        for event in append.events {
+            rows.push(EventRow::<DB> {
+                identity: &append.identity,
+                expected_version: append.expected_version,
+                sequence: repository_i64_from_u64(
+                    DB::BACKEND,
+                    event.sequence,
+                    "sequence",
+                    DB::INTEGER_STORAGE,
+                )?,
+                event_name: &event.event_name,
+                event_version: repository_i64_from_u64(
+                    DB::BACKEND,
+                    event.event_version,
+                    "event_version",
+                    DB::INTEGER_STORAGE,
+                )?,
+                payload: &event.payload,
+                payload_codec: &event.payload_codec,
+                payload_codec_version: i64::from(event.payload_codec_version),
+                metadata: serialize_event_metadata(&event.metadata)?,
+                recorded_at: DB::timestamp_value(event.timestamp)?,
+            });
+        }
+    }
+
+    for chunk in rows.chunks(DB::MAX_BIND_PARAMS / EVENT_BIND_COLUMNS) {
+        let mut builder = QueryBuilder::<DB>::new(
+            "INSERT INTO aggregate_events (\
+             aggregate_type, aggregate_id, sequence, event_name, event_version, \
+             payload, payload_codec, payload_codec_version, metadata, recorded_at) ",
+        );
+        builder.push_values(chunk, |mut row, event| {
+            row.push_bind(event.identity.aggregate_type())
+                .push_bind(event.identity.aggregate_id())
+                .push_bind(event.sequence)
+                .push_bind(event.event_name)
+                .push_bind(event.event_version)
+                .push_bind(event.payload)
+                .push_bind(event.payload_codec)
+                .push_bind(event.payload_codec_version);
+            DB::push_metadata(&mut row, event.metadata.as_str());
+            DB::push_timestamp(&mut row, &event.recorded_at);
+        });
+
+        let result = builder.build().execute(&mut **tx).await;
+        match result {
+            Ok(_) => {}
+            Err(err) if DB::is_unique_violation(&err) => {
+                return Err(if DB::CONFLICT_REREAD_IN_TX {
+                    // The transaction survives the constraint error: re-read in
+                    // the same tx, scoped to this chunk (earlier chunks were
+                    // already inserted in this tx and would skew the versions
+                    // of their streams).
+                    let mut seen = std::collections::HashSet::new();
+                    let candidates: Vec<_> = chunk
+                        .iter()
+                        .filter(|event| seen.insert(event.identity.storage_key()))
+                        .map(|event| (event.identity, event.expected_version))
+                        .collect();
+                    concurrent_write_from_conflict(&mut **tx, &candidates).await
+                } else {
+                    // The failed statement aborted the transaction: re-read the
+                    // conflicting streams' actual versions on a separate
+                    // connection, across the whole batch.
+                    let candidates: Vec<_> = prepared
+                        .iter()
+                        .map(|append| (&append.identity, append.expected_version))
+                        .collect();
+                    match pool.acquire().await {
+                        Ok(mut conn) => {
+                            concurrent_write_from_conflict(&mut conn, &candidates).await
+                        }
+                        Err(err) => repository_storage_error::<DB>(
+                            "acquire conflict re-read connection",
+                            err,
+                        ),
+                    }
+                });
+            }
+            Err(err) => return Err(repository_storage_error::<DB>("insert events", err)),
+        }
+    }
+
+    Ok(())
+}
+
+/// After an event-insert unique violation, find the candidate stream whose
+/// actual version no longer matches its expected version and report it as
+/// `ConcurrentWrite`. Falls back to the first candidate if a concurrent
+/// writer's effect cannot be pinned down (the violation still indicates a
+/// conflicting write). Candidates must be non-empty and deduplicated.
+async fn concurrent_write_from_conflict<DB>(
+    conn: &mut DB::Connection,
+    candidates: &[(&StreamIdentity, u64)],
+) -> RepositoryError
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    for &(identity, expected) in candidates {
+        match stream_version(&mut *conn, identity).await {
+            Ok(actual) if actual != expected => {
+                return RepositoryError::ConcurrentWrite {
+                    id: identity.to_string(),
+                    expected,
+                    actual,
+                };
+            }
+            Ok(_) => {}
+            Err(err) => return err,
+        }
+    }
+
+    let (identity, expected) = candidates[0];
+    match stream_version(&mut *conn, identity).await {
+        Ok(actual) => RepositoryError::ConcurrentWrite {
+            id: identity.to_string(),
+            expected,
+            actual,
+        },
+        Err(err) => err,
+    }
+}
+
+/// Current committed version (`MAX(sequence)`, 0 for a missing stream) through
+/// any executor (pool or transaction).
+async fn stream_version<'e, DB, E>(
+    executor: E,
+    identity: &StreamIdentity,
+) -> Result<u64, RepositoryError>
+where
+    DB: SqlxRepoBackend,
+    E: Executor<'e, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let mut builder = QueryBuilder::<DB>::new(
+        "SELECT MAX(sequence) AS version FROM aggregate_events WHERE aggregate_type = ",
+    );
+    builder.push_bind(identity.aggregate_type());
+    builder.push(" AND aggregate_id = ");
+    builder.push_bind(identity.aggregate_id());
+    let row = builder
+        .build()
+        .fetch_one(executor)
+        .await
+        .map_err(|err| repository_storage_error::<DB>("load stream version", err))?;
+
+    let version: Option<i64> = row
+        .try_get("version")
+        .map_err(|err| repository_storage_error::<DB>("decode stream version row", err))?;
+    version
+        .map(|value| repository_u64_from_i64(DB::BACKEND, value, "sequence"))
+        .unwrap_or(Ok(0))
+}
+
+/// Current committed versions for every stream in the batch, in one grouped
+/// query (`MAX(sequence)` per stream; missing streams simply have no row and
+/// default to 0 at the call site). Chunked so a very large batch stays under
+/// the backend's bound-parameter limit (two binds per stream).
+async fn stream_versions_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    prepared: &[PreparedEventAppend<'_>],
+) -> Result<HashMap<String, u64>, RepositoryError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let mut versions = HashMap::with_capacity(prepared.len());
+    if prepared.is_empty() {
+        return Ok(versions);
+    }
+
+    for chunk in prepared.chunks(DB::MAX_BIND_PARAMS / 2) {
+        let mut builder = QueryBuilder::<DB>::new(
+            "SELECT aggregate_type, aggregate_id, MAX(sequence) AS version \
+             FROM aggregate_events WHERE ",
+        );
+        let mut first = true;
+        for append in chunk {
+            if !first {
+                builder.push(" OR ");
+            }
+            first = false;
+            builder.push("(aggregate_type = ");
+            builder.push_bind(append.identity.aggregate_type());
+            builder.push(" AND aggregate_id = ");
+            builder.push_bind(append.identity.aggregate_id());
+            builder.push(")");
+        }
+        builder.push(" GROUP BY aggregate_type, aggregate_id");
+
+        let rows = builder
+            .build()
+            .fetch_all(&mut **tx)
+            .await
+            .map_err(|err| repository_storage_error::<DB>("load stream versions", err))?;
+
+        for row in rows {
+            let aggregate_type: String = row.try_get("aggregate_type").map_err(|err| {
+                repository_storage_error::<DB>("decode stream version aggregate type row", err)
+            })?;
+            let aggregate_id: String = row.try_get("aggregate_id").map_err(|err| {
+                repository_storage_error::<DB>("decode stream version aggregate id row", err)
+            })?;
+            let version: i64 = row
+                .try_get("version")
+                .map_err(|err| repository_storage_error::<DB>("decode stream version row", err))?;
+            versions.insert(
+                StreamIdentity::new(&aggregate_type, &aggregate_id)?.storage_key(),
+                repository_u64_from_i64(DB::BACKEND, version, "sequence")?,
+            );
+        }
+    }
+
+    Ok(versions)
+}
diff --git a/src/sqlx_repo/repo/errors.rs b/src/sqlx_repo/repo/errors.rs
new file mode 100644
index 00000000..707a71f9
--- /dev/null
+++ b/src/sqlx_repo/repo/errors.rs
@@ -0,0 +1,21 @@
+use super::*;
+
+/// Convert a [`SystemTime`] to epoch seconds for database-side comparisons.
+pub(crate) fn system_time_epoch_secs<DB: SqlxRepoBackend>(
+    timestamp: SystemTime,
+) -> Result<f64, RepositoryError> {
+    let duration = timestamp.duration_since(UNIX_EPOCH).map_err(|err| {
+        RepositoryError::Model(format!(
+            "timestamp before UNIX epoch cannot be stored in {}: {err}",
+            DB::BACKEND
+        ))
+    })?;
+    Ok(duration.as_secs_f64())
+}
+
+pub(crate) fn repository_storage_error<DB: SqlxRepoBackend>(
+    operation: &str,
+    err: sqlx::Error,
+) -> RepositoryError {
+    crate::sqlx_repo::repository_storage_error(DB::BACKEND, operation, err)
+}
diff --git a/src/sqlx_repo/repo/events.rs b/src/sqlx_repo/repo/events.rs
new file mode 100644
index 00000000..351ca17b
--- /dev/null
+++ b/src/sqlx_repo/repo/events.rs
@@ -0,0 +1,58 @@
+use super::*;
+
+pub(crate) fn event_from_row<DB>(row: DB::Row) -> Result<EventRecord, RepositoryError>
+where
+    DB: SqlxRepoBackend,
+    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let payload_codec: String = row
+        .try_get("payload_codec")
+        .map_err(|err| repository_storage_error::<DB>("decode payload codec row", err))?;
+    // Nearly every row carries the crate's own codec constant; borrow it
+    // instead of keeping a per-event allocation.
+    let payload_codec = if payload_codec == BITCODE_PAYLOAD_CODEC {
+        Cow::Borrowed(BITCODE_PAYLOAD_CODEC)
+    } else {
+        Cow::Owned(payload_codec)
+    };
+    let payload_codec_version = repository_u16_from_i64(
+        DB::BACKEND,
+        row.try_get("payload_codec_version").map_err(|err| {
+            repository_storage_error::<DB>("decode payload codec version row", err)
+        })?,
+        "payload_codec_version",
+    )?;
+    let metadata_json: String = row
+        .try_get("metadata")
+        .map_err(|err| repository_storage_error::<DB>("decode metadata row", err))?;
+    let metadata = deserialize_event_metadata(&metadata_json)?;
+    let event = EventRecord {
+        event_name: row
+            .try_get("event_name")
+            .map_err(|err| repository_storage_error::<DB>("decode event name row", err))?,
+        payload_codec,
+        payload_codec_version,
+        payload: row
+            .try_get("payload")
+            .map_err(|err| repository_storage_error::<DB>("decode payload row", err))?,
+        event_version: repository_u64_from_i64(
+            DB::BACKEND,
+            row.try_get("event_version")
+                .map_err(|err| repository_storage_error::<DB>("decode event version row", err))?,
+            "event_version",
+        )?,
+        sequence: repository_u64_from_i64(
+            DB::BACKEND,
+            row.try_get("sequence")
+                .map_err(|err| repository_storage_error::<DB>("decode sequence row", err))?,
+            "sequence",
+        )?,
+        timestamp: DB::decode_timestamp(&row, "recorded_at")?,
+        metadata,
+    };
+    validate_supported_event_codec(&event)?;
+    Ok(event)
+}
diff --git a/src/sqlx_repo/repo/inbox.rs b/src/sqlx_repo/repo/inbox.rs
new file mode 100644
index 00000000..66ac62cc
--- /dev/null
+++ b/src/sqlx_repo/repo/inbox.rs
@@ -0,0 +1,51 @@
+use super::*;
+
+impl<DB> InboxStore for SqlxRepository<DB>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    fn inbox_contains<'a>(
+        &'a self,
+        consumer: &'a str,
+        message_id: &'a str,
+    ) -> impl Future<Output = Result<bool, RepositoryError>> + Send + 'a {
+        async move {
+            let mut builder =
+                QueryBuilder::<DB>::new("SELECT 1 FROM consumer_inbox WHERE consumer = ");
+            builder.push_bind(consumer);
+            builder.push(" AND message_id = ");
+            builder.push_bind(message_id);
+            builder.push(" LIMIT 1");
+            let row = builder
+                .build()
+                .fetch_optional(&self.pool)
+                .await
+                .map_err(|err| repository_storage_error::<DB>("query consumer inbox", err))?;
+            Ok(row.is_some())
+        }
+    }
+
+    fn purge_inbox_older_than(
+        &self,
+        age: std::time::Duration,
+    ) -> impl Future<Output = Result<u64, RepositoryError>> + Send {
+        async move {
+            // Compare against the database clock to avoid client/server skew;
+            // the backend renders the cutoff expression.
+            let mut builder = DB::inbox_purge_query(age);
+            let result = builder
+                .build()
+                .execute(&self.pool)
+                .await
+                .map_err(|err| repository_storage_error::<DB>("purge consumer inbox", err))?;
+            Ok(DB::rows_affected(&result))
+        }
+    }
+}
diff --git a/src/sqlx_repo/repo/mod.rs b/src/sqlx_repo/repo/mod.rs
new file mode 100644
index 00000000..3805d093
--- /dev/null
+++ b/src/sqlx_repo/repo/mod.rs
@@ -0,0 +1,98 @@
+//! Backend-agnostic event-store, snapshot, outbox, and inbox logic shared by
+//! the Postgres and SQLite repositories.
+//!
+//! This extends the [`SqlxReadModelBackend`](super::read_model::SqlxReadModelBackend)
+//! pattern to the whole repository surface: the SQL statements and row codecs
+//! are identical across the two backends because `QueryBuilder<DB>` renders the
+//! right placeholder dialect. What genuinely differs — schema SQL, bind-param
+//! chunking, the timestamp codec (Postgres epoch-`f64`/`to_timestamp()` vs
+//! SQLite `"secs.nanos"` text), the unique-violation predicate, conflict
+//! recovery (SQLite can re-read in the failed transaction; a failed Postgres
+//! statement aborts it), and the outbox `claim` strategy — lives behind the
+//! [`SqlxRepoBackend`] trait, implemented once per backend.
+
+#![expect(
+    clippy::manual_async_fn,
+    reason = "async trait impls return impl Future + Send to preserve public Send bounds"
+)]
+
+use std::borrow::Cow;
+use std::collections::{BTreeMap, HashMap};
+use std::future::Future;
+use std::sync::{Arc, RwLock};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use sqlx::migrate::{Migrate, Migration, MigrationType, Migrator};
+use sqlx::pool::PoolOptions;
+use sqlx::query_builder::Separated;
+use sqlx::{Encode, Executor, IntoArguments, Pool, QueryBuilder, Row, Transaction, Type};
+
+use crate::command_ledger::{
+    AttemptFence, AttemptToken, CanonicalInputHash, CausalCommitBatch, CausalGetStream,
+    CausalRepositoryIdentity, CausalStorageIdentity, CausalTransactionalCommit, CausationId,
+    CommandCompletion, CommandContractFingerprint, CommandId, CommandLedgerError, CommandLedgerKey,
+    CommandLedgerRecord, CommandLedgerState, CommandLedgerStore, CommandLookup, CommandLookupScope,
+    CommandReservation, PrincipalPartitionId, ReservationDecision, ReservationOutcome,
+};
+use crate::entity::{Entity, EventRecord, BITCODE_PAYLOAD_CODEC};
+use crate::outbox::{OutboxMessage, OutboxMessageStatus};
+use crate::outbox_worker::{
+    ensure_active_claim, ClaimOutboxMessages, OutboxBacklogStats, OutboxClaimRef, OutboxStore,
+};
+use crate::projection_protocol::{ProjectionChangeRetention, SameTransactionProjectionBatch};
+use crate::read_model::{ReadModelLoadGraph, ReadModelLoadRequest, ReadModelQueryCapabilities};
+use crate::repository::{
+    validate_commit_batch, validate_snapshot_identity, validate_supported_event_codec, CommitBatch,
+    GetStream, InboxReceipt, InboxStore, PreparedEventAppend, ReadModelWritePlanStore,
+    RelationalReadModelQueryStore, RepositoryError, SnapshotStore, SnapshotWrite, StreamIdentity,
+    TransactionalCommit,
+};
+use crate::snapshot::SnapshotRecord;
+use crate::sqlx_repo::projection_protocol::{
+    apply_same_transaction_projection_in_tx, reject_causal_table_writes_in_tx,
+    PROJECTION_CHANGE_NOTIFY_TABLE,
+};
+use crate::sqlx_repo::read_model::{
+    apply_read_model_write_plan_in_tx, begin_read_model_tx, commit_read_model_tx,
+    empty_string_as_none, load_read_model_graph, remember_read_model_schemas,
+    sql_read_model_capabilities, validate_sql_write_plan, SqlxReadModelBackend,
+};
+use crate::sqlx_repo::{
+    audited_table_schema_sql, deserialize_event_metadata, repository_i64_from_u64,
+    repository_u16_from_i64, repository_u64_from_i64, serialize_event_metadata,
+};
+use crate::table::{
+    generate_table_migration_artifacts, table_schema_bootstrap_result, table_schema_statements,
+    TableMigrationArtifact, TableSchemaBootstrap, TableSchemaRegistry, TableSqlDialect,
+    TableSqlSchemaAdapter, TableStoreError,
+};
+use crate::table::{
+    TableAdapterCapabilities as ReadModelAdapterCapabilities,
+    TableCommitOutcome as ReadModelCommitOutcome, TableStoreError as ReadModelError,
+    TableWritePlan as ReadModelWritePlan,
+};
+
+mod backend;
+mod commit;
+mod errors;
+mod events;
+mod inbox;
+mod outbox;
+mod read_models;
+mod snapshots;
+mod streams;
+mod types;
+
+use backend::*;
+use events::*;
+use outbox::*;
+use snapshots::*;
+
+pub(crate) use backend::embedded_migrator;
+pub use backend::SqlxRepoBackend;
+pub(crate) use errors::{repository_storage_error, system_time_epoch_secs};
+#[cfg(feature = "sqlite")]
+pub(crate) use outbox::outbox_message_by_id;
+#[cfg(feature = "postgres")]
+pub(crate) use outbox::outbox_message_from_row;
+pub use types::{SqlxOutboxStore, SqlxRepository};
diff --git a/src/sqlx_repo/repo/outbox.rs b/src/sqlx_repo/repo/outbox.rs
new file mode 100644
index 00000000..95268687
--- /dev/null
+++ b/src/sqlx_repo/repo/outbox.rs
@@ -0,0 +1,490 @@
+use super::*;
+
+/// One claimed-message lifecycle transition (the `UPDATE` shape is shared; only
+/// the assignments differ).
+enum OutboxTransition<'a> {
+    Complete,
+    Release { error: &'a str },
+    Fail { error: &'a str },
+}
+
+impl OutboxTransition<'_> {
+    fn target_status(&self) -> OutboxMessageStatus {
+        match self {
+            OutboxTransition::Complete => OutboxMessageStatus::Published,
+            OutboxTransition::Release { .. } => OutboxMessageStatus::Pending,
+            OutboxTransition::Fail { .. } => OutboxMessageStatus::Failed,
+        }
+    }
+
+    fn operation(&self) -> &'static str {
+        match self {
+            OutboxTransition::Complete => "complete outbox message",
+            OutboxTransition::Release { .. } => "release outbox message",
+            OutboxTransition::Fail { .. } => "fail outbox message",
+        }
+    }
+}
+
+impl<DB> OutboxStore for SqlxOutboxStore<DB>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> f64: Encode<'q, DB> + Type<DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'q> Option<i64>: Encode<'q, DB> + Type<DB>,
+    for<'q> Option<&'q str>: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    fn messages_by_status(
+        &self,
+        status: OutboxMessageStatus,
+        limit: usize,
+    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + '_ {
+        async move {
+            let mut builder = QueryBuilder::<DB>::new("SELECT ");
+            builder.push(DB::OUTBOX_SELECT);
+            builder.push(" FROM outbox_messages WHERE status = ");
+            builder.push_bind(status.as_str());
+            builder.push(" ORDER BY ");
+            builder.push(DB::ORDER_BY_CREATED_AT);
+            builder.push(" ASC, message_id ASC LIMIT ");
+            // usize::MAX means "no practical bound"; clamp to what the column
+            // type can carry.
+            builder.push_bind(i64::try_from(limit).unwrap_or(i64::MAX));
+            let rows = builder.build().fetch_all(&self.pool).await.map_err(|err| {
+                repository_storage_error::<DB>("load outbox messages by status", err)
+            })?;
+
+            rows.into_iter()
+                .map(outbox_message_from_row::<DB>)
+                .collect()
+        }
+    }
+
+    fn backlog_stats(
+        &self,
+    ) -> impl Future<Output = Result<OutboxBacklogStats, RepositoryError>> + Send + '_ {
+        async move {
+            let mut builder = QueryBuilder::<DB>::new("SELECT COUNT(*) AS pending_count, ");
+            builder.push(DB::OUTBOX_OLDEST_CREATED_AT_SELECT);
+            builder.push(" FROM outbox_messages WHERE status = ");
+            builder.push_bind(OutboxMessageStatus::Pending.as_str());
+            let row =
+                builder.build().fetch_one(&self.pool).await.map_err(|err| {
+                    repository_storage_error::<DB>("load outbox backlog stats", err)
+                })?;
+
+            let pending_count: i64 = row.try_get("pending_count").map_err(|err| {
+                repository_storage_error::<DB>("decode outbox backlog count row", err)
+            })?;
+            let pending =
+                repository_u64_from_i64(DB::BACKEND, pending_count, "outbox backlog count")
+                    .and_then(|value| {
+                        usize::try_from(value).map_err(|_| {
+                            RepositoryError::Model(format!(
+                                "{} outbox backlog count value {value} is invalid",
+                                DB::BACKEND
+                            ))
+                        })
+                    })?;
+            let oldest_created_at = DB::decode_optional_timestamp(&row, "oldest_created_at")?;
+
+            Ok(OutboxBacklogStats {
+                pending,
+                oldest_created_at,
+            })
+        }
+    }
+
+    fn claim<'a>(
+        &'a self,
+        request: ClaimOutboxMessages,
+    ) -> impl Future<Output = Result<Vec<OutboxMessage>, RepositoryError>> + Send + 'a {
+        DB::claim_outbox(&self.pool, request)
+    }
+
+    fn complete<'a>(
+        &'a self,
+        claim: &'a OutboxClaimRef,
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+        transition_claimed_outbox_message(&self.pool, claim, OutboxTransition::Complete)
+    }
+
+    fn release<'a>(
+        &'a self,
+        claim: &'a OutboxClaimRef,
+        error: &'a str,
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+        transition_claimed_outbox_message(&self.pool, claim, OutboxTransition::Release { error })
+    }
+
+    fn fail<'a>(
+        &'a self,
+        claim: &'a OutboxClaimRef,
+        error: &'a str,
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+        transition_claimed_outbox_message(&self.pool, claim, OutboxTransition::Fail { error })
+    }
+}
+
+/// Apply one claimed-message lifecycle transition (complete / release / fail).
+///
+/// The conditional `UPDATE` only applies while the caller still holds the
+/// active claim (`status`, `claimed_by`, unexpired `claimed_until`, and
+/// matching `attempts`); when no row is updated, the message is re-read to
+/// produce the precise claim error.
+async fn transition_claimed_outbox_message<'a, DB>(
+    pool: &'a Pool<DB>,
+    claim: &'a OutboxClaimRef,
+    transition: OutboxTransition<'a>,
+) -> Result<(), RepositoryError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> f64: Encode<'q, DB> + Type<DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> Option<i64>: Encode<'q, DB> + Type<DB>,
+    for<'q> Option<&'q str>: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let now = SystemTime::now();
+    let now_epoch = system_time_epoch_secs::<DB>(now)?;
+    let now_value = DB::timestamp_value(now)?;
+
+    let mut builder = QueryBuilder::<DB>::new("UPDATE outbox_messages SET status = ");
+    builder.push_bind(transition.target_status().as_str());
+    builder.push(", claimed_by = NULL, claimed_until = NULL, ");
+    match &transition {
+        OutboxTransition::Complete => {
+            builder.push("published_at = ");
+            DB::push_timestamp_assign(&mut builder, &now_value);
+        }
+        OutboxTransition::Release { error } => {
+            builder.push("next_available_at = ");
+            DB::push_timestamp_assign(&mut builder, &now_value);
+            builder.push(", last_error = ");
+            builder.push_bind(empty_string_as_none(error));
+        }
+        OutboxTransition::Fail { error } => {
+            builder.push("last_error = ");
+            builder.push_bind(empty_string_as_none(error));
+            builder.push(", failed_at = ");
+            DB::push_timestamp_assign(&mut builder, &now_value);
+        }
+    }
+    builder.push(", updated_at = ");
+    builder.push(DB::NOW);
+    builder.push(" WHERE message_id = ");
+    builder.push_bind(claim.message_id.as_str());
+    builder.push(" AND status = ");
+    builder.push_bind(OutboxMessageStatus::InFlight.as_str());
+    builder.push(" AND claimed_by = ");
+    builder.push_bind(claim.worker_id.as_str());
+    builder.push(" AND claimed_until IS NOT NULL AND ");
+    DB::push_timestamp_cmp(&mut builder, "claimed_until", ">", now_epoch);
+    builder.push(" AND attempts = ");
+    builder.push_bind(repository_i64_from_u64(
+        DB::BACKEND,
+        u64::from(claim.attempt),
+        "outbox claim attempt",
+        DB::INTEGER_STORAGE,
+    )?);
+
+    let result = builder
+        .build()
+        .execute(pool)
+        .await
+        .map_err(|err| repository_storage_error::<DB>(transition.operation(), err))?;
+
+    ensure_outbox_update_applied(
+        pool,
+        DB::rows_affected(&result),
+        &claim.message_id,
+        |message| ensure_active_claim(message, Some(claim), now),
+    )
+    .await
+}
+
+/// Load an outbox message by id through any executor (pool or transaction).
+pub(crate) async fn outbox_message_by_id<'e, DB, E>(
+    executor: E,
+    message_id: &str,
+) -> Result<Option<OutboxMessage>, RepositoryError>
+where
+    DB: SqlxRepoBackend,
+    E: Executor<'e, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let mut builder = QueryBuilder::<DB>::new("SELECT ");
+    builder.push(DB::OUTBOX_SELECT);
+    builder.push(" FROM outbox_messages WHERE message_id = ");
+    builder.push_bind(message_id);
+    let row = builder
+        .build()
+        .fetch_optional(executor)
+        .await
+        .map_err(|err| repository_storage_error::<DB>("load outbox message", err))?;
+    row.map(outbox_message_from_row::<DB>).transpose()
+}
+
+pub(crate) async fn ensure_outbox_update_applied<DB>(
+    pool: &Pool<DB>,
+    rows_affected: u64,
+    message_id: &str,
+    validate: impl FnOnce(&OutboxMessage) -> Result<(), RepositoryError>,
+) -> Result<(), RepositoryError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    if rows_affected > 0 {
+        return Ok(());
+    }
+
+    let message = outbox_message_by_id(pool, message_id)
+        .await?
+        .ok_or_else(|| RepositoryError::NotFound {
+            id: message_id.to_string(),
+        })?;
+    validate(&message)
+}
+/// One `outbox_messages` row with pre-validated bind values.
+struct OutboxRow<'a, DB: SqlxRepoBackend> {
+    message_id: &'a str,
+    event_type: &'a str,
+    payload: &'a [u8],
+    payload_codec: &'a str,
+    payload_codec_version: i64,
+    destination: Option<&'a str>,
+    metadata: String,
+    status: &'a str,
+    created_at: DB::TimestampValue,
+    worker_id: Option<&'a str>,
+    leased_until: Option<DB::TimestampValue>,
+    attempts: i64,
+    last_error: Option<&'a str>,
+    source_aggregate_type: Option<&'a str>,
+    source_aggregate_id: Option<&'a str>,
+    source_sequence: Option<i64>,
+    correlation_id: Option<&'a str>,
+    causation_id: Option<&'a str>,
+}
+
+/// Insert every outbox message with multi-row INSERTs (chunked to respect the
+/// backend's bound-parameter limit). A unique violation on `message_id` still
+/// maps to `DuplicateOutboxMessageInBatch`.
+pub(super) async fn insert_outbox_messages_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    messages: &[OutboxMessage],
+) -> Result<(), RepositoryError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> Option<i64>: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> Option<&'q str>: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    if messages.is_empty() {
+        return Ok(());
+    }
+
+    let mut rows = Vec::with_capacity(messages.len());
+    for message in messages {
+        rows.push(OutboxRow::<DB> {
+            message_id: message.id(),
+            event_type: &message.event_type,
+            payload: &message.payload,
+            payload_codec: &message.payload_codec,
+            payload_codec_version: i64::from(message.payload_codec_version),
+            destination: message.destination.as_deref(),
+            metadata: serialize_event_metadata(&message.metadata)?,
+            status: message.status.as_str(),
+            created_at: DB::timestamp_value(message.created_at)?,
+            worker_id: message.worker_id.as_deref(),
+            leased_until: message.leased_until.map(DB::timestamp_value).transpose()?,
+            attempts: i64::from(message.attempts),
+            last_error: message.last_error.as_deref(),
+            source_aggregate_type: message.source_aggregate_type.as_deref(),
+            source_aggregate_id: message.source_aggregate_id.as_deref(),
+            source_sequence: message
+                .source_sequence
+                .map(|value| {
+                    repository_i64_from_u64(
+                        DB::BACKEND,
+                        value,
+                        "outbox source sequence",
+                        DB::INTEGER_STORAGE,
+                    )
+                })
+                .transpose()?,
+            correlation_id: message.correlation_id(),
+            causation_id: message.causation_id(),
+        });
+    }
+
+    for chunk in rows.chunks(DB::MAX_BIND_PARAMS / OUTBOX_BIND_COLUMNS) {
+        let mut builder = QueryBuilder::<DB>::new(
+            "INSERT INTO outbox_messages (\
+             message_id, event_type, payload, payload_codec, payload_codec_version, \
+             destination, metadata, status, created_at, next_available_at, \
+             claimed_by, claimed_until, attempts, last_error, source_aggregate_type, \
+             source_aggregate_id, source_sequence, correlation_id, causation_id) ",
+        );
+        builder.push_values(chunk, |mut row, message| {
+            row.push_bind(message.message_id)
+                .push_bind(message.event_type)
+                .push_bind(message.payload)
+                .push_bind(message.payload_codec)
+                .push_bind(message.payload_codec_version)
+                .push_bind(message.destination);
+            DB::push_metadata(&mut row, message.metadata.as_str());
+            row.push_bind(message.status);
+            // created_at and next_available_at share the same value.
+            DB::push_timestamp(&mut row, &message.created_at);
+            DB::push_timestamp(&mut row, &message.created_at);
+            row.push_bind(message.worker_id);
+            DB::push_optional_timestamp(&mut row, message.leased_until.as_ref());
+            row.push_bind(message.attempts)
+                .push_bind(message.last_error)
+                .push_bind(message.source_aggregate_type)
+                .push_bind(message.source_aggregate_id)
+                .push_bind(message.source_sequence)
+                .push_bind(message.correlation_id)
+                .push_bind(message.causation_id);
+        });
+
+        let result = builder.build().execute(&mut **tx).await;
+        if let Err(err) = result {
+            if DB::is_unique_violation(&err) {
+                // The batch was already deduped (validate_commit_batch), so a
+                // violation means the id collides with a previously committed
+                // row. Report the first id in the chunk, matching the per-row
+                // path's contract.
+                return Err(RepositoryError::DuplicateOutboxMessageInBatch {
+                    id: chunk[0].message_id.to_string(),
+                });
+            }
+            return Err(repository_storage_error::<DB>(
+                "insert outbox messages",
+                err,
+            ));
+        }
+    }
+
+    Ok(())
+}
+pub(crate) fn outbox_message_from_row<DB>(row: DB::Row) -> Result<OutboxMessage, RepositoryError>
+where
+    DB: SqlxRepoBackend,
+    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let status_text: String = row
+        .try_get("status")
+        .map_err(|err| repository_storage_error::<DB>("decode outbox status row", err))?;
+    let status = status_text.parse::<OutboxMessageStatus>().map_err(|_| {
+        RepositoryError::Model(format!(
+            "{} outbox status `{status_text}` is invalid",
+            DB::BACKEND
+        ))
+    })?;
+    let metadata_json: String = row
+        .try_get("metadata")
+        .map_err(|err| repository_storage_error::<DB>("decode outbox metadata row", err))?;
+    let attempts: i64 = row
+        .try_get("attempts")
+        .map_err(|err| repository_storage_error::<DB>("decode outbox attempts row", err))?;
+    let source_sequence = row
+        .try_get::<Option<i64>, _>("source_sequence")
+        .map_err(|err| repository_storage_error::<DB>("decode outbox source sequence row", err))?
+        .map(|value| repository_u64_from_i64(DB::BACKEND, value, "outbox source sequence"))
+        .transpose()?;
+    let mut metadata = deserialize_event_metadata(&metadata_json)?;
+    if let Some(correlation_id) = row
+        .try_get::<Option<String>, _>("correlation_id")
+        .map_err(|err| repository_storage_error::<DB>("decode outbox correlation_id row", err))?
+    {
+        metadata.insert("correlation_id".into(), correlation_id);
+    }
+    if let Some(causation_id) = row
+        .try_get::<Option<String>, _>("causation_id")
+        .map_err(|err| repository_storage_error::<DB>("decode outbox causation_id row", err))?
+    {
+        metadata.insert("causation_id".into(), causation_id);
+    }
+
+    Ok(OutboxMessage {
+        id: row
+            .try_get("message_id")
+            .map_err(|err| repository_storage_error::<DB>("decode outbox message id row", err))?,
+        event_type: row
+            .try_get("event_type")
+            .map_err(|err| repository_storage_error::<DB>("decode outbox event type row", err))?,
+        payload: row
+            .try_get("payload")
+            .map_err(|err| repository_storage_error::<DB>("decode outbox payload row", err))?,
+        payload_codec: row.try_get("payload_codec").map_err(|err| {
+            repository_storage_error::<DB>("decode outbox payload codec row", err)
+        })?,
+        payload_codec_version: repository_u16_from_i64(
+            DB::BACKEND,
+            row.try_get("payload_codec_version").map_err(|err| {
+                repository_storage_error::<DB>("decode outbox payload codec version row", err)
+            })?,
+            "outbox payload codec version",
+        )?,
+        metadata,
+        status,
+        created_at: DB::decode_timestamp(&row, "created_at")?,
+        worker_id: row
+            .try_get("claimed_by")
+            .map_err(|err| repository_storage_error::<DB>("decode outbox claimed_by row", err))?,
+        leased_until: DB::decode_optional_timestamp(&row, "claimed_until")?,
+        attempts: u32::try_from(attempts).map_err(|_| {
+            RepositoryError::Model(format!(
+                "{} outbox attempts value {attempts} is invalid",
+                DB::BACKEND
+            ))
+        })?,
+        last_error: row
+            .try_get("last_error")
+            .map_err(|err| repository_storage_error::<DB>("decode outbox last_error row", err))?,
+        destination: row
+            .try_get("destination")
+            .map_err(|err| repository_storage_error::<DB>("decode outbox destination row", err))?,
+        source_aggregate_type: row.try_get("source_aggregate_type").map_err(|err| {
+            repository_storage_error::<DB>("decode outbox source aggregate type row", err)
+        })?,
+        source_aggregate_id: row.try_get("source_aggregate_id").map_err(|err| {
+            repository_storage_error::<DB>("decode outbox source aggregate id row", err)
+        })?,
+        source_sequence,
+    })
+}
diff --git a/src/sqlx_repo/repo/read_models.rs b/src/sqlx_repo/repo/read_models.rs
new file mode 100644
index 00000000..d32ae226
--- /dev/null
+++ b/src/sqlx_repo/repo/read_models.rs
@@ -0,0 +1,68 @@
+use super::*;
+
+impl<DB> ReadModelWritePlanStore for SqlxRepository<DB>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    fn read_model_capabilities(&self) -> ReadModelAdapterCapabilities {
+        sql_read_model_capabilities()
+    }
+
+    fn commit_write_plan(
+        &self,
+        plan: ReadModelWritePlan,
+    ) -> impl Future<Output = Result<ReadModelCommitOutcome, ReadModelError>> + Send + '_ {
+        async move {
+            let tables: std::collections::BTreeSet<String> = plan
+                .mutations
+                .iter()
+                .map(|m| m.table_name().to_string())
+                .collect();
+            validate_sql_write_plan(&plan)?;
+            let mut tx = begin_read_model_tx(&self.pool).await?;
+            reject_causal_table_writes_in_tx(&mut tx, &tables).await?;
+            let outcome = apply_read_model_write_plan_in_tx(&mut tx, plan).await?;
+            if self.notify_enabled && !tables.is_empty() {
+                DB::push_change_notify(&mut *tx, &tables).await?;
+            }
+            commit_read_model_tx(tx).await?;
+            if outcome.was_applied() && !tables.is_empty() {
+                self.publish_read_model_change(crate::ReadModelChange { tables });
+            }
+            Ok(outcome)
+        }
+    }
+}
+
+impl<DB> RelationalReadModelQueryStore for SqlxRepository<DB>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    fn read_model_query_capabilities(&self) -> ReadModelQueryCapabilities {
+        ReadModelQueryCapabilities::relationship_includes()
+    }
+
+    fn load_graph(
+        &self,
+        request: ReadModelLoadRequest,
+    ) -> impl Future<Output = Result<ReadModelLoadGraph, ReadModelError>> + Send + '_ {
+        async move {
+            load_read_model_graph(
+                &self.pool,
+                &self.read_model_schemas,
+                request,
+                self.read_model_query_capabilities(),
+            )
+            .await
+        }
+    }
+}
diff --git a/src/sqlx_repo/repo/snapshots.rs b/src/sqlx_repo/repo/snapshots.rs
new file mode 100644
index 00000000..5c62c218
--- /dev/null
+++ b/src/sqlx_repo/repo/snapshots.rs
@@ -0,0 +1,225 @@
+use super::*;
+
+impl<DB> SnapshotStore for SqlxRepository<DB>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    fn get_snapshot<'a>(
+        &'a self,
+        identity: &'a StreamIdentity,
+    ) -> impl Future<Output = Result<Option<SnapshotRecord>, RepositoryError>> + Send + 'a {
+        async move {
+            let mut builder = QueryBuilder::<DB>::new("SELECT ");
+            builder.push(DB::SNAPSHOT_SELECT);
+            builder.push(" FROM aggregate_snapshots WHERE aggregate_type = ");
+            builder.push_bind(identity.aggregate_type());
+            builder.push(" AND aggregate_id = ");
+            builder.push_bind(identity.aggregate_id());
+            let row = builder
+                .build()
+                .fetch_optional(&self.pool)
+                .await
+                .map_err(|err| repository_storage_error::<DB>("load snapshot", err))?;
+
+            let Some(row) = row else {
+                return Ok(None);
+            };
+
+            Ok(Some(snapshot_from_row::<DB>(row)?))
+        }
+    }
+
+    fn get_snapshots<'a>(
+        &'a self,
+        identities: &'a [StreamIdentity],
+    ) -> impl Future<Output = Result<Vec<SnapshotRecord>, RepositoryError>> + Send + 'a {
+        async move {
+            if identities.is_empty() {
+                return Ok(Vec::new());
+            }
+
+            let mut records = Vec::with_capacity(identities.len());
+            for (aggregate_type, aggregate_ids) in ids_by_type(identities) {
+                let mut builder = QueryBuilder::<DB>::new("SELECT ");
+                builder.push(DB::SNAPSHOT_SELECT);
+                builder.push(" FROM aggregate_snapshots WHERE aggregate_type = ");
+                builder.push_bind(aggregate_type);
+                builder.push(" AND ");
+                DB::push_id_filter(&mut builder, &aggregate_ids);
+                let rows = builder
+                    .build()
+                    .fetch_all(&self.pool)
+                    .await
+                    .map_err(|err| repository_storage_error::<DB>("load snapshots", err))?;
+                for row in rows {
+                    records.push(snapshot_from_row::<DB>(row)?);
+                }
+            }
+            Ok(records)
+        }
+    }
+
+    fn save_snapshot<'a>(
+        &'a self,
+        identity: &'a StreamIdentity,
+        record: SnapshotRecord,
+    ) -> impl Future<Output = Result<(), RepositoryError>> + Send + 'a {
+        async move {
+            let mut tx =
+                self.pool.begin().await.map_err(|err| {
+                    repository_storage_error::<DB>("begin snapshot transaction", err)
+                })?;
+            save_snapshot_in_tx(&mut tx, identity, record).await?;
+            tx.commit().await.map_err(|err| {
+                repository_storage_error::<DB>("commit snapshot transaction", err)
+            })?;
+            Ok(())
+        }
+    }
+
+    fn delete_snapshot<'a>(
+        &'a self,
+        identity: &'a StreamIdentity,
+    ) -> impl Future<Output = Result<bool, RepositoryError>> + Send + 'a {
+        async move {
+            let mut builder =
+                QueryBuilder::<DB>::new("DELETE FROM aggregate_snapshots WHERE aggregate_type = ");
+            builder.push_bind(identity.aggregate_type());
+            builder.push(" AND aggregate_id = ");
+            builder.push_bind(identity.aggregate_id());
+            let result = builder
+                .build()
+                .execute(&self.pool)
+                .await
+                .map_err(|err| repository_storage_error::<DB>("delete snapshot", err))?;
+
+            Ok(DB::rows_affected(&result) > 0)
+        }
+    }
+}
+pub(super) async fn save_snapshot_in_tx<DB>(
+    tx: &mut Transaction<'_, DB>,
+    identity: &StreamIdentity,
+    record: SnapshotRecord,
+) -> Result<(), RepositoryError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+{
+    validate_snapshot_identity(identity, &record)?;
+
+    let metadata = serialize_event_metadata(&record.metadata)?;
+    let recorded_at = DB::timestamp_value(record.recorded_at)?;
+    let version = repository_i64_from_u64(
+        DB::BACKEND,
+        record.version,
+        "snapshot version",
+        DB::INTEGER_STORAGE,
+    )?;
+    let snapshot_version = repository_i64_from_u64(
+        DB::BACKEND,
+        record.snapshot_version,
+        "snapshot payload version",
+        DB::INTEGER_STORAGE,
+    )?;
+
+    let mut builder = QueryBuilder::<DB>::new(
+        "INSERT INTO aggregate_snapshots (\
+         aggregate_type, aggregate_id, version, snapshot_version, payload, \
+         payload_codec, payload_codec_version, metadata, recorded_at) VALUES (",
+    );
+    {
+        let mut row = builder.separated(", ");
+        row.push_bind(identity.aggregate_type())
+            .push_bind(identity.aggregate_id())
+            .push_bind(version)
+            .push_bind(snapshot_version)
+            .push_bind(record.payload.as_slice())
+            .push_bind(record.payload_codec.as_str())
+            .push_bind(i64::from(record.payload_codec_version));
+        DB::push_metadata(&mut row, metadata.as_str());
+        DB::push_timestamp(&mut row, &recorded_at);
+    }
+    builder.push(
+        ") ON CONFLICT(aggregate_type, aggregate_id) DO UPDATE SET \
+         version = excluded.version, \
+         snapshot_version = excluded.snapshot_version, \
+         payload = excluded.payload, \
+         payload_codec = excluded.payload_codec, \
+         payload_codec_version = excluded.payload_codec_version, \
+         metadata = excluded.metadata, \
+         recorded_at = excluded.recorded_at, \
+         updated_at = ",
+    );
+    builder.push(DB::NOW);
+
+    builder
+        .build()
+        .execute(&mut **tx)
+        .await
+        .map_err(|err| repository_storage_error::<DB>("save snapshot", err))?;
+
+    Ok(())
+}
+pub(super) fn snapshot_from_row<DB>(row: DB::Row) -> Result<SnapshotRecord, RepositoryError>
+where
+    DB: SqlxRepoBackend,
+    for<'q> i64: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> String: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    let metadata_json: String = row
+        .try_get("metadata")
+        .map_err(|err| repository_storage_error::<DB>("decode snapshot metadata row", err))?;
+    Ok(SnapshotRecord {
+        aggregate_type: row.try_get("aggregate_type").map_err(|err| {
+            repository_storage_error::<DB>("decode snapshot aggregate type row", err)
+        })?,
+        aggregate_id: row.try_get("aggregate_id").map_err(|err| {
+            repository_storage_error::<DB>("decode snapshot aggregate id row", err)
+        })?,
+        version: repository_u64_from_i64(
+            DB::BACKEND,
+            row.try_get("version").map_err(|err| {
+                repository_storage_error::<DB>("decode snapshot version row", err)
+            })?,
+            "snapshot version",
+        )?,
+        snapshot_version: repository_u64_from_i64(
+            DB::BACKEND,
+            row.try_get("snapshot_version").map_err(|err| {
+                repository_storage_error::<DB>("decode snapshot payload version row", err)
+            })?,
+            "snapshot payload version",
+        )?,
+        payload_codec: row.try_get("payload_codec").map_err(|err| {
+            repository_storage_error::<DB>("decode snapshot payload codec row", err)
+        })?,
+        payload_codec_version: repository_u16_from_i64(
+            DB::BACKEND,
+            row.try_get("payload_codec_version").map_err(|err| {
+                repository_storage_error::<DB>("decode snapshot payload codec version row", err)
+            })?,
+            "snapshot payload codec version",
+        )?,
+        payload: row
+            .try_get("payload")
+            .map_err(|err| repository_storage_error::<DB>("decode snapshot payload row", err))?,
+        metadata: deserialize_event_metadata(&metadata_json)?,
+        recorded_at: DB::decode_timestamp(&row, "recorded_at")?,
+    })
+}
diff --git a/src/sqlx_repo/repo/streams.rs b/src/sqlx_repo/repo/streams.rs
new file mode 100644
index 00000000..3e437e99
--- /dev/null
+++ b/src/sqlx_repo/repo/streams.rs
@@ -0,0 +1,193 @@
+use super::*;
+
+impl<DB> GetStream for SqlxRepository<DB>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> f64: Encode<'q, DB> + Type<DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    fn get_stream<'a>(
+        &'a self,
+        identity: &'a StreamIdentity,
+    ) -> impl Future<Output = Result<Option<Entity>, RepositoryError>> + Send + 'a {
+        async move {
+            let mut builder = QueryBuilder::<DB>::new("SELECT ");
+            builder.push(DB::EVENT_SELECT);
+            builder.push(" FROM aggregate_events WHERE aggregate_type = ");
+            builder.push_bind(identity.aggregate_type());
+            builder.push(" AND aggregate_id = ");
+            builder.push_bind(identity.aggregate_id());
+            builder.push(" ORDER BY sequence ASC");
+            let rows = builder
+                .build()
+                .fetch_all(&self.pool)
+                .await
+                .map_err(|err| repository_storage_error::<DB>("load stream", err))?;
+
+            if rows.is_empty() {
+                return Ok(None);
+            }
+
+            let mut events = Vec::with_capacity(rows.len());
+            for row in rows {
+                events.push(event_from_row::<DB>(row)?);
+            }
+
+            let mut entity = Entity::new();
+            entity.set_id(identity.aggregate_id());
+            entity.load_from_history(events);
+            Ok(Some(entity))
+        }
+    }
+
+    fn get_streams<'a>(
+        &'a self,
+        identities: &'a [StreamIdentity],
+    ) -> impl Future<Output = Result<Vec<Entity>, RepositoryError>> + Send + 'a {
+        async move {
+            if identities.is_empty() {
+                return Ok(Vec::new());
+            }
+
+            let mut entities = Vec::with_capacity(identities.len());
+            for (aggregate_type, aggregate_ids) in ids_by_type(identities) {
+                // Ordering by aggregate_id then sequence lets us slice the flat
+                // result into per-aggregate entities in one pass. Callers of
+                // `get_all` accept storage-order results.
+                let mut builder = QueryBuilder::<DB>::new("SELECT aggregate_id, ");
+                builder.push(DB::EVENT_SELECT);
+                builder.push(" FROM aggregate_events WHERE aggregate_type = ");
+                builder.push_bind(aggregate_type);
+                builder.push(" AND ");
+                DB::push_id_filter(&mut builder, &aggregate_ids);
+                builder.push(" ORDER BY aggregate_id ASC, sequence ASC");
+
+                let rows = builder
+                    .build()
+                    .fetch_all(&self.pool)
+                    .await
+                    .map_err(|err| repository_storage_error::<DB>("load streams", err))?;
+
+                let mut current_id: Option<String> = None;
+                let mut current_events: Vec<EventRecord> = Vec::new();
+                for row in rows {
+                    let row_id: String = row.try_get("aggregate_id").map_err(|err| {
+                        repository_storage_error::<DB>("decode aggregate id row", err)
+                    })?;
+                    let event = event_from_row::<DB>(row)?;
+                    match &current_id {
+                        Some(id) if id == &row_id => current_events.push(event),
+                        _ => {
+                            if let Some(id) = current_id.take() {
+                                entities.push(entity_from_events(
+                                    id,
+                                    std::mem::take(&mut current_events),
+                                ));
+                            }
+                            current_id = Some(row_id);
+                            current_events.push(event);
+                        }
+                    }
+                }
+                if let Some(id) = current_id.take() {
+                    entities.push(entity_from_events(id, current_events));
+                }
+            }
+
+            Ok(entities)
+        }
+    }
+
+    fn get_stream_tail<'a>(
+        &'a self,
+        identity: &'a StreamIdentity,
+        after_version: u64,
+    ) -> impl Future<Output = Result<Option<Entity>, RepositoryError>> + Send + 'a {
+        async move {
+            // Fetch only the post-snapshot tail. `after_version` is the snapshot
+            // version (an event sequence); `sequence > ?` skips already-folded
+            // rows so a fresh snapshot over a long stream no longer reads and
+            // decodes the entire history.
+            let after = repository_i64_from_u64(
+                DB::BACKEND,
+                after_version,
+                "snapshot tail lower bound",
+                DB::INTEGER_STORAGE,
+            )?;
+            let mut builder = QueryBuilder::<DB>::new("SELECT ");
+            builder.push(DB::EVENT_SELECT);
+            builder.push(" FROM aggregate_events WHERE aggregate_type = ");
+            builder.push_bind(identity.aggregate_type());
+            builder.push(" AND aggregate_id = ");
+            builder.push_bind(identity.aggregate_id());
+            builder.push(" AND sequence > ");
+            builder.push_bind(after);
+            builder.push(" ORDER BY sequence ASC");
+            let rows = builder
+                .build()
+                .fetch_all(&self.pool)
+                .await
+                .map_err(|err| repository_storage_error::<DB>("load stream tail", err))?;
+
+            // An empty tail is ambiguous from this query alone (no rows could
+            // mean "snapshot is current" or "stream does not exist"). The
+            // snapshot hydrate path only calls this after confirming a snapshot
+            // exists for the identity, so an empty tail means the snapshot is
+            // current. Return an entity at exactly `after_version`.
+            let mut events = Vec::with_capacity(rows.len());
+            for row in rows {
+                events.push(event_from_row::<DB>(row)?);
+            }
+
+            let mut entity = Entity::new();
+            entity.set_id(identity.aggregate_id());
+            entity.load_tail_from_history(events, after_version);
+            Ok(Some(entity))
+        }
+    }
+}
+
+impl<DB> CausalGetStream for SqlxRepository<DB>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+    for<'q> i64: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> f64: Encode<'q, DB> + Type<DB>,
+    for<'q> String: Encode<'q, DB> + Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> Vec<u8>: Type<DB> + sqlx::Decode<'q, DB>,
+    for<'q> &'q str: Encode<'q, DB> + Type<DB>,
+    for<'q> &'q [u8]: Encode<'q, DB> + Type<DB>,
+    for<'r> &'r str: sqlx::ColumnIndex<DB::Row>,
+{
+    fn get_causal_stream<'a>(
+        &'a self,
+        identity: &'a StreamIdentity,
+    ) -> impl Future<Output = Result<Option<Entity>, RepositoryError>> + Send + 'a {
+        GetStream::get_stream(self, identity)
+    }
+}
+
+impl<DB> CausalRepositoryIdentity for SqlxRepository<DB>
+where
+    DB: SqlxRepoBackend,
+{
+    fn causal_storage_identity(&self) -> CausalStorageIdentity {
+        self.causal_storage_identity
+    }
+}
+pub(super) fn entity_from_events(aggregate_id: String, events: Vec<EventRecord>) -> Entity {
+    let mut entity = Entity::new();
+    entity.set_id(aggregate_id);
+    entity.load_from_history(events);
+    entity
+}
diff --git a/src/sqlx_repo/repo/types.rs b/src/sqlx_repo/repo/types.rs
new file mode 100644
index 00000000..6bf6bbb3
--- /dev/null
+++ b/src/sqlx_repo/repo/types.rs
@@ -0,0 +1,266 @@
+use super::*;
+
+/// SQL-backed async repository generic over the SQLx backend.
+///
+/// Use through the public aliases: [`PostgresRepository`](crate::PostgresRepository)
+/// and [`SqliteRepository`](crate::SqliteRepository).
+pub struct SqlxRepository<DB: sqlx::Database> {
+    pub(super) pool: Pool<DB>,
+    pub(super) read_model_schemas: Arc<RwLock<TableSchemaRegistry>>,
+    pub(super) read_model_change_tx: tokio::sync::broadcast::Sender<crate::ReadModelChange>,
+    /// When false, skips Postgres `pg_notify` (local broadcast still fires).
+    /// Opt-out via [`SqlxRepository::without_read_model_change_notify`]. Writers
+    /// that opt out silently break cross-process GraphQL subscriptions.
+    pub(super) notify_enabled: bool,
+    pub(super) projection_change_retention: ProjectionChangeRetention,
+    pub(super) causal_storage_identity: CausalStorageIdentity,
+}
+
+impl<DB: sqlx::Database> Clone for SqlxRepository<DB> {
+    fn clone(&self) -> Self {
+        Self {
+            pool: self.pool.clone(),
+            read_model_schemas: Arc::clone(&self.read_model_schemas),
+            read_model_change_tx: self.read_model_change_tx.clone(),
+            notify_enabled: self.notify_enabled,
+            projection_change_retention: self.projection_change_retention,
+            causal_storage_identity: self.causal_storage_identity,
+        }
+    }
+}
+
+/// SQL-backed outbox table store generic over the SQLx backend.
+///
+/// Use through the public aliases: [`PostgresOutboxStore`](crate::PostgresOutboxStore)
+/// and [`SqliteOutboxStore`](crate::SqliteOutboxStore).
+pub struct SqlxOutboxStore<DB: sqlx::Database> {
+    pub(super) pool: Pool<DB>,
+}
+
+impl<DB: sqlx::Database> Clone for SqlxOutboxStore<DB> {
+    fn clone(&self) -> Self {
+        Self {
+            pool: self.pool.clone(),
+        }
+    }
+}
+
+impl<DB> SqlxRepository<DB>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c mut DB::Connection: Executor<'c, Database = DB>,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+{
+    /// Create a repository from an existing migrated pool.
+    pub fn new(pool: Pool<DB>) -> Self {
+        let (read_model_change_tx, _) = tokio::sync::broadcast::channel(256);
+        Self {
+            pool,
+            read_model_schemas: Arc::new(RwLock::new(TableSchemaRegistry::new())),
+            read_model_change_tx,
+            notify_enabled: true,
+            projection_change_retention: ProjectionChangeRetention::default(),
+            causal_storage_identity: CausalStorageIdentity::new(),
+        }
+    }
+
+    #[cfg_attr(not(feature = "graphql"), allow(dead_code))]
+    pub(crate) fn causal_storage_identity(&self) -> CausalStorageIdentity {
+        self.causal_storage_identity
+    }
+
+    /// Subscribe to read-model table changes (fires after successful write-plan commits).
+    ///
+    /// Lagging receivers observe [`tokio::sync::broadcast::error::RecvError::Lagged`]
+    /// and should treat that as all-dirty for subscription invalidation.
+    pub fn read_model_changes(&self) -> tokio::sync::broadcast::Receiver<crate::ReadModelChange> {
+        self.read_model_change_tx.subscribe()
+    }
+
+    /// Disable Postgres `pg_notify` emission on read-model commits (local broadcast
+    /// remains active). Default is ON.
+    ///
+    /// **Failure mode:** writer processes that opt out silently break
+    /// cross-process GraphQL subscriptions that rely on LISTEN/NOTIFY.
+    pub fn without_read_model_change_notify(mut self) -> Self {
+        self.notify_enabled = false;
+        self
+    }
+
+    /// Configure the maximum newest projection changes retained per partition.
+    ///
+    /// Lengthening this value never restores a prefix already represented by
+    /// the durable compacted-through watermark.
+    pub fn with_projection_change_retention(
+        mut self,
+        retention: ProjectionChangeRetention,
+    ) -> Self {
+        self.projection_change_retention = retention;
+        self
+    }
+
+    pub fn publish_read_model_change(&self, change: crate::ReadModelChange) {
+        if change.is_empty() {
+            return;
+        }
+        // Zero receivers is a no-op (broadcast::send returns Err).
+        let _ = self.read_model_change_tx.send(change);
+    }
+
+    pub(crate) fn projection_notify_enabled(&self) -> bool {
+        self.notify_enabled
+    }
+
+    pub(crate) fn projection_change_retention(&self) -> ProjectionChangeRetention {
+        self.projection_change_retention
+    }
+
+    /// Open a pool without applying migrations.
+    pub async fn connect(database_url: &str) -> Result<Self, RepositoryError> {
+        let pool = PoolOptions::<DB>::new()
+            .max_connections(DB::default_pool_size(database_url))
+            .connect(database_url)
+            .await
+            .map_err(|err| repository_storage_error::<DB>("connect", err))?;
+        Ok(Self::new(pool))
+    }
+
+    /// Open a pool and apply this backend's explicit migrations.
+    pub async fn connect_and_migrate(database_url: &str) -> Result<Self, RepositoryError>
+    where
+        DB::Connection: Migrate,
+    {
+        let repo = Self::connect(database_url).await?;
+        repo.migrate().await?;
+        Ok(repo)
+    }
+
+    /// Apply this backend's migrations to the repository's pool.
+    pub async fn migrate(&self) -> Result<(), RepositoryError>
+    where
+        DB::Connection: Migrate,
+    {
+        Self::migrate_pool(&self.pool).await
+    }
+
+    /// Apply this backend's migrations to an existing pool. Applied versions
+    /// are recorded in the `_sqlx_migrations` ledger, so re-running is a no-op
+    /// and an edited already-applied migration fails its checksum comparison
+    /// instead of silently diverging.
+    pub async fn migrate_pool(pool: &Pool<DB>) -> Result<(), RepositoryError>
+    where
+        DB::Connection: Migrate,
+    {
+        DB::migrator()
+            .run(pool)
+            .await
+            .map_err(|err| RepositoryError::Storage {
+                operation: format!("{} migrate", DB::BACKEND),
+                retryable: false,
+                source: Some(Box::new(err)),
+            })
+    }
+
+    /// Access the underlying SQLx pool for application-specific setup or tests.
+    pub fn pool(&self) -> &Pool<DB> {
+        &self.pool
+    }
+
+    /// SQL artifact adapter for registered table/read-model schemas.
+    pub fn table_schema_adapter(&self) -> TableSqlSchemaAdapter {
+        table_schema_adapter::<DB>()
+    }
+
+    /// Generate SQL statements for registered table/read-model schemas.
+    pub fn generate_table_migration_artifacts(
+        &self,
+        registry: &TableSchemaRegistry,
+    ) -> Result<Vec<TableMigrationArtifact>, TableStoreError> {
+        generate_table_migration_artifacts(registry, DB::TABLE_DIALECT)
+    }
+
+    /// Explicit dev/test bootstrap for registered table/read-model schemas.
+    pub async fn bootstrap_table_schema_for_dev(
+        &self,
+        registry: &TableSchemaRegistry,
+    ) -> Result<TableSchemaBootstrap, TableStoreError> {
+        bootstrap_table_schema(&self.pool, registry).await?;
+        remember_read_model_schemas(&self.read_model_schemas, registry)?;
+        Ok(table_schema_bootstrap_result(registry))
+    }
+
+    /// Access an outbox-store handle backed by this repository's pool.
+    pub fn outbox_store(&self) -> SqlxOutboxStore<DB> {
+        SqlxOutboxStore {
+            pool: self.pool.clone(),
+        }
+    }
+}
+
+impl<DB> SqlxOutboxStore<DB>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+{
+    pub fn new(pool: Pool<DB>) -> Self {
+        Self { pool }
+    }
+
+    pub fn pool(&self) -> &Pool<DB> {
+        &self.pool
+    }
+
+    /// SQL artifact adapter for registered table/read-model schemas.
+    pub fn table_schema_adapter(&self) -> TableSqlSchemaAdapter {
+        table_schema_adapter::<DB>()
+    }
+
+    /// Generate SQL statements for registered table/read-model schemas.
+    pub fn generate_table_migration_artifacts(
+        &self,
+        registry: &TableSchemaRegistry,
+    ) -> Result<Vec<TableMigrationArtifact>, TableStoreError> {
+        generate_table_migration_artifacts(registry, DB::TABLE_DIALECT)
+    }
+
+    /// Explicit dev/test bootstrap for registered table/read-model schemas.
+    pub async fn bootstrap_table_schema_for_dev(
+        &self,
+        registry: &TableSchemaRegistry,
+    ) -> Result<TableSchemaBootstrap, TableStoreError> {
+        bootstrap_table_schema(&self.pool, registry).await?;
+        Ok(table_schema_bootstrap_result(registry))
+    }
+}
+
+fn table_schema_adapter<DB: SqlxRepoBackend>() -> TableSqlSchemaAdapter {
+    match DB::TABLE_DIALECT {
+        TableSqlDialect::Postgres => TableSqlSchemaAdapter::postgres(),
+        TableSqlDialect::Sqlite => TableSqlSchemaAdapter::sqlite(),
+    }
+}
+
+async fn bootstrap_table_schema<DB>(
+    pool: &Pool<DB>,
+    registry: &TableSchemaRegistry,
+) -> Result<(), TableStoreError>
+where
+    DB: SqlxRepoBackend,
+    for<'c> &'c Pool<DB>: Executor<'c, Database = DB>,
+    DB::Arguments: IntoArguments<DB>,
+{
+    for statement in table_schema_statements(registry, DB::TABLE_DIALECT)? {
+        sqlx::query(audited_table_schema_sql(statement))
+            .execute(pool)
+            .await
+            .map_err(|err| {
+                TableStoreError::Storage(format!(
+                    "{} bootstrap table schema failed: {err}",
+                    DB::BACKEND
+                ))
+            })?;
+    }
+    Ok(())
+}
diff --git a/src/table/error.rs b/src/table/error.rs
index 3bc3b533..06aefb7a 100644
--- a/src/table/error.rs
+++ b/src/table/error.rs
@@ -17,6 +17,20 @@ pub enum TableStoreError {
     Serde(String),
     /// Storage-level error.
     Storage(String),
+    /// Backend storage failure with its retry classification preserved.
+    ///
+    /// SQL adapters use this instead of flattening a driver error into
+    /// [`Storage`](Self::Storage), because projector runners must distinguish a
+    /// transient busy/deadlock/connection failure from a deterministic fault
+    /// before deciding whether terminal failure evidence may be recorded.
+    BackendStorage {
+        operation: String,
+        retryable: bool,
+        message: String,
+    },
+    /// A raw/legacy write targeted a table registered to the causal projection
+    /// protocol and therefore cannot mint the required revision evidence.
+    CausalWriteRequired { table: String },
     /// Row not found.
     NotFound { collection: String, id: String },
     /// Lock error.
@@ -40,6 +54,21 @@ impl fmt::Display for TableStoreError {
             ),
             TableStoreError::Serde(msg) => write!(f, "table store serialization error: {}", msg),
             TableStoreError::Storage(msg) => write!(f, "table storage error: {}", msg),
+            TableStoreError::BackendStorage {
+                operation,
+                retryable,
+                message,
+            } => {
+                let class = if *retryable { "retryable" } else { "permanent" };
+                write!(
+                    f,
+                    "table backend storage error ({class}) during {operation}: {message}"
+                )
+            }
+            TableStoreError::CausalWriteRequired { table } => write!(
+                f,
+                "table `{table}` is causal-owned and requires the projection commit path"
+            ),
             TableStoreError::NotFound { collection, id } => {
                 write!(f, "table row not found: {}:{}", collection, id)
             }
diff --git a/src/table/metadata.rs b/src/table/metadata.rs
index e15c36bf..88f519ad 100644
--- a/src/table/metadata.rs
+++ b/src/table/metadata.rs
@@ -157,6 +157,29 @@ pub struct RelationshipDef {
     pub target_model: String,
     pub foreign_key: Option<String>,
     pub through: Option<String>,
+    /// Join-table column referencing the TARGET row (many-to-many).
+    ///
+    /// When `None`, resolvers infer the unique join column whose column-level FK
+    /// targets the target model's table, excluding the source-side `foreign_key`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub target_foreign_key: Option<String>,
+}
+
+/// Discriminator for tables owned by the framework vs read-model projections.
+///
+/// Operational tables (outbox, inbox, …) are never exposed on the GraphQL query
+/// surface; `from_manifest` / `graphql_sdl` consume only `ReadModel` entries.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum TableKind {
+    #[default]
+    ReadModel,
+    Operational,
+}
+
+impl TableKind {
+    pub fn is_read_model(&self) -> bool {
+        matches!(self, Self::ReadModel)
+    }
 }
 
 /// Schema metadata for one relational table.
@@ -170,6 +193,10 @@ pub struct TableSchema {
     pub foreign_keys: Vec<ForeignKey>,
     pub indexes: Vec<TableIndex>,
     pub relationships: Vec<RelationshipDef>,
+    /// Defaults to [`TableKind::ReadModel`]; skipped when serializing the default
+    /// so existing describe-JSON artifacts stay byte-identical on upgrade.
+    #[serde(default, skip_serializing_if = "TableKind::is_read_model")]
+    pub kind: TableKind,
 }
 
 impl TableSchema {
@@ -200,6 +227,12 @@ impl TableSchema {
                     self.model_name, column.field_name, type_name
                 )));
             }
+            if column.primary_key && column.nullable {
+                return Err(TableStoreError::Metadata(format!(
+                    "model `{}` primary-key column `{}` must be non-null",
+                    self.model_name, column.column_name
+                )));
+            }
             if let Some(foreign_key) = &column.foreign_key {
                 validate_foreign_key(&self.model_name, foreign_key)?;
             }
@@ -234,6 +267,17 @@ impl TableSchema {
                     self.model_name, column
                 )));
             }
+            if self
+                .columns
+                .iter()
+                .find(|candidate| candidate.column_name == *column)
+                .is_some_and(|candidate| candidate.nullable)
+            {
+                return Err(TableStoreError::Metadata(format!(
+                    "model `{}` primary-key column `{}` must be non-null",
+                    self.model_name, column
+                )));
+            }
         }
 
         for foreign_key in &self.foreign_keys {
@@ -318,6 +362,36 @@ impl RowValue {
         Ok(Self::from_json_value(value))
     }
 
+    /// Serialize a `#[readmodel(text)]` value without allowing structured JSON
+    /// to enter a SQL text column. This is public only for derive output.
+    #[doc(hidden)]
+    pub fn from_text_serde<T: Serialize + ?Sized>(
+        value: &T,
+        nullable: bool,
+        column: &str,
+    ) -> Result<Self, TableStoreError> {
+        match serde_json::to_value(value)
+            .map_err(|error| TableStoreError::Serde(error.to_string()))?
+        {
+            serde_json::Value::String(value) => Ok(Self::String(value)),
+            serde_json::Value::Null if nullable => Ok(Self::Null),
+            serde_json::Value::Null => Err(TableStoreError::Metadata(format!(
+                "#[readmodel(text)] column `{column}` is non-null but its value serialized as null"
+            ))),
+            value => Err(TableStoreError::Metadata(format!(
+                "#[readmodel(text)] column `{column}` must serialize as a JSON string{}; got {}",
+                if nullable { " or null" } else { "" },
+                match value {
+                    serde_json::Value::Bool(_) => "boolean",
+                    serde_json::Value::Number(_) => "number",
+                    serde_json::Value::Array(_) => "array",
+                    serde_json::Value::Object(_) => "object",
+                    serde_json::Value::String(_) | serde_json::Value::Null => unreachable!(),
+                }
+            ))),
+        }
+    }
+
     pub fn into_json(self) -> serde_json::Value {
         match self {
             RowValue::Null => serde_json::Value::Null,
@@ -443,6 +517,52 @@ mod tests {
             foreign_keys: vec![ForeignKey::new("players", "player_id")],
             indexes: vec![TableIndex::new(["player_id"])],
             relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        }
+    }
+
+    #[test]
+    fn table_kind_deserializes_missing_as_read_model() {
+        let json = r#"{
+            "model_name": "PlayerWeapon",
+            "table_name": "player_weapons",
+            "columns": [],
+            "primary_key": { "columns": [] },
+            "version_column": null,
+            "foreign_keys": [],
+            "indexes": [],
+            "relationships": []
+        }"#;
+        let schema: TableSchema = serde_json::from_str(json).unwrap();
+        assert_eq!(schema.kind, TableKind::ReadModel);
+        assert!(schema.target_foreign_key_absent());
+    }
+
+    #[test]
+    fn table_kind_read_model_skipped_from_json() {
+        let schema = valid_schema();
+        let value = serde_json::to_value(&schema).unwrap();
+        assert!(value.get("kind").is_none());
+    }
+
+    #[test]
+    fn relationship_target_foreign_key_defaults_absent() {
+        let json = r#"{
+            "field_name": "tags",
+            "kind": "ManyToMany",
+            "target_model": "Tag",
+            "foreign_key": "post_id",
+            "through": "post_tags"
+        }"#;
+        let rel: RelationshipDef = serde_json::from_str(json).unwrap();
+        assert_eq!(rel.target_foreign_key, None);
+    }
+
+    impl TableSchema {
+        fn target_foreign_key_absent(&self) -> bool {
+            self.relationships
+                .iter()
+                .all(|r| r.target_foreign_key.is_none())
         }
     }
 
@@ -490,6 +610,7 @@ mod tests {
             target_model: "PlayerWeapon".into(),
             foreign_key: None,
             through: None,
+            target_foreign_key: None,
         });
 
         let err = schema.validate().unwrap_err();
@@ -536,4 +657,36 @@ mod tests {
             serde_json::json!({"wins": [1, 2]})
         );
     }
+
+    #[test]
+    fn text_serde_accepts_only_string_shaped_values_and_nullable_null() {
+        #[derive(Serialize)]
+        enum UnitStatus {
+            Open,
+        }
+        #[derive(Serialize)]
+        enum StructuredStatus {
+            Reason { message: String },
+        }
+
+        assert_eq!(
+            RowValue::from_text_serde(&UnitStatus::Open, false, "status").unwrap(),
+            RowValue::String("Open".into())
+        );
+        assert_eq!(
+            RowValue::from_text_serde(&Option::<UnitStatus>::None, true, "status").unwrap(),
+            RowValue::Null
+        );
+        let error = RowValue::from_text_serde(
+            &StructuredStatus::Reason {
+                message: "why".into(),
+            },
+            false,
+            "status",
+        )
+        .unwrap_err();
+        assert!(error
+            .to_string()
+            .contains("must serialize as a JSON string; got object"));
+    }
 }
diff --git a/src/table/mod.rs b/src/table/mod.rs
index 2c0ee5c1..cdf31680 100644
--- a/src/table/mod.rs
+++ b/src/table/mod.rs
@@ -16,7 +16,7 @@ mod sql;
 pub use error::TableStoreError;
 pub use metadata::{
     ColumnType, ForeignKey, PrimaryKey, RelationshipDef, RelationshipKind, RowKey, RowValue,
-    RowValues, TableColumn, TableIndex, TableSchema, DEFAULT_TABLE_VERSION_COLUMN,
+    RowValues, TableColumn, TableIndex, TableKind, TableSchema, DEFAULT_TABLE_VERSION_COLUMN,
 };
 pub(crate) use mutation::{
     column_name_for, key_fingerprint, key_from_row, validate_delete_mutation,
@@ -29,9 +29,9 @@ pub use mutation::{
 };
 pub use plan::{TableAdapterCapabilities, TableCommitOutcome, TableWritePlan};
 pub use registry::{
-    TableMigrationArtifact, TableSchemaAdapter, TableSchemaAdapterCapabilities,
-    TableSchemaBootstrap, TableSchemaIssue, TableSchemaIssueKind, TableSchemaRegistry,
-    TableSchemaVerification,
+    resolve_m2m_target_foreign_key, TableMigrationArtifact, TableSchemaAdapter,
+    TableSchemaAdapterCapabilities, TableSchemaBootstrap, TableSchemaIssue, TableSchemaIssueKind,
+    TableSchemaRegistry, TableSchemaVerification,
 };
 pub use sql::{
     bootstrap_result as table_schema_bootstrap_result, generate_table_migration_artifacts,
diff --git a/src/table/registry.rs b/src/table/registry.rs
index b8828a03..db99c0e5 100644
--- a/src/table/registry.rs
+++ b/src/table/registry.rs
@@ -4,7 +4,7 @@ use std::collections::{BTreeMap, BTreeSet};
 
 use crate::read_model::RelationalReadModel;
 
-use super::{RelationshipKind, TableSchema, TableStoreError};
+use super::{RelationshipDef, RelationshipKind, TableSchema, TableStoreError};
 
 /// Registry of table schemas an adapter should manage.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
@@ -178,22 +178,41 @@ impl TableSchemaRegistry {
                     }
                 }
                 RelationshipKind::ManyToMany => {
-                    if let Some(through) = relationship.through.as_deref() {
-                        let through_schema = self.schema_for_table(through).ok_or_else(|| {
-                            TableStoreError::Metadata(format!(
-                                "model `{}` relationship `{}` references unavailable join table `{}`",
-                                schema.model_name, relationship.field_name, through
-                            ))
-                        })?;
-                        if !schema_has_column_or_field(through_schema, foreign_key) {
-                            return Err(TableStoreError::Metadata(format!(
-                                "model `{}` relationship `{}` foreign key `{}` is not a column on join table `{}`",
-                                schema.model_name,
-                                relationship.field_name,
-                                foreign_key,
-                                through
-                            )));
-                        }
+                    let through = relationship.through.as_deref().ok_or_else(|| {
+                        TableStoreError::Metadata(format!(
+                            "model `{}` relationship `{}` many-to-many must declare `through`",
+                            schema.model_name, relationship.field_name
+                        ))
+                    })?;
+                    let through_schema = self.schema_for_table(through).ok_or_else(|| {
+                        TableStoreError::Metadata(format!(
+                            "model `{}` relationship `{}` references unavailable join table `{}`",
+                            schema.model_name, relationship.field_name, through
+                        ))
+                    })?;
+                    if !schema_has_column_or_field(through_schema, foreign_key) {
+                        return Err(TableStoreError::Metadata(format!(
+                            "model `{}` relationship `{}` foreign key `{}` is not a column on join table `{}`",
+                            schema.model_name,
+                            relationship.field_name,
+                            foreign_key,
+                            through
+                        )));
+                    }
+                    let target_fk = resolve_m2m_target_foreign_key(
+                        schema,
+                        relationship,
+                        through_schema,
+                        target_schema,
+                    )?;
+                    if !schema_has_column_or_field(through_schema, &target_fk) {
+                        return Err(TableStoreError::Metadata(format!(
+                            "model `{}` relationship `{}` target_foreign_key `{}` is not a column on join table `{}`",
+                            schema.model_name,
+                            relationship.field_name,
+                            target_fk,
+                            through
+                        )));
                     }
                 }
             }
@@ -247,6 +266,63 @@ fn schema_has_column_or_field(schema: &TableSchema, name: &str) -> bool {
         .any(|column| column.column_name == name || column.field_name == name)
 }
 
+/// Resolve the join-table column that references the target model for m2m.
+///
+/// When `target_foreign_key` is set, validates non-empty and returns it.
+/// Otherwise infers the unique join column whose FK targets the target table,
+/// excluding the source-side `foreign_key` column from candidacy.
+pub fn resolve_m2m_target_foreign_key(
+    source: &TableSchema,
+    relationship: &RelationshipDef,
+    through_schema: &TableSchema,
+    target_schema: &TableSchema,
+) -> Result<String, TableStoreError> {
+    if let Some(explicit) = relationship.target_foreign_key.as_deref() {
+        if explicit.is_empty() {
+            return Err(TableStoreError::Metadata(format!(
+                "model `{}` relationship `{}` target_foreign_key must not be empty",
+                source.model_name, relationship.field_name
+            )));
+        }
+        return Ok(explicit.to_string());
+    }
+
+    let source_fk = relationship.foreign_key.as_deref().unwrap_or_default();
+    let candidates: Vec<&str> = through_schema
+        .columns
+        .iter()
+        .filter(|column| {
+            column.column_name != source_fk
+                && column.field_name != source_fk
+                && column
+                    .foreign_key
+                    .as_ref()
+                    .is_some_and(|fk| fk.table == target_schema.table_name)
+        })
+        .map(|column| column.column_name.as_str())
+        .collect();
+
+    match candidates.as_slice() {
+        [only] => Ok((*only).to_string()),
+        [] => Err(TableStoreError::Metadata(format!(
+            "model `{}` relationship `{}` cannot infer target_foreign_key on join table `{}` \
+             (no remaining column FK targets `{}`); declare `target_foreign_key` explicitly",
+            source.model_name,
+            relationship.field_name,
+            through_schema.table_name,
+            target_schema.table_name
+        ))),
+        many => Err(TableStoreError::Metadata(format!(
+            "model `{}` relationship `{}` cannot infer target_foreign_key on join table `{}` \
+             (ambiguous candidates: {}); declare `target_foreign_key` explicitly",
+            source.model_name,
+            relationship.field_name,
+            through_schema.table_name,
+            many.join(", ")
+        ))),
+    }
+}
+
 /// Schema lifecycle operations an adapter can support.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct TableSchemaAdapterCapabilities {
diff --git a/src/table/sql.rs b/src/table/sql.rs
index 82e494fa..25455ece 100644
--- a/src/table/sql.rs
+++ b/src/table/sql.rs
@@ -446,6 +446,7 @@ mod tests {
             foreign_keys: Vec::new(),
             indexes: Vec::new(),
             relationships: Vec::new(),
+            kind: crate::table::TableKind::ReadModel,
         };
         let child = TableSchema {
             model_name: "Child".into(),
@@ -462,6 +463,7 @@ mod tests {
             foreign_keys: Vec::new(),
             indexes: Vec::new(),
             relationships: Vec::new(),
+            kind: crate::table::TableKind::ReadModel,
         };
         let mut registry = TableSchemaRegistry::new();
         registry.register_schema(child).expect("child registers");
@@ -544,6 +546,7 @@ mod tests {
             foreign_keys: Vec::new(),
             indexes: Vec::new(),
             relationships: Vec::new(),
+            kind: crate::table::TableKind::ReadModel,
         };
 
         let err = create_table_statement(&schema, TableSqlDialect::Sqlite)
diff --git a/src/telemetry.rs b/src/telemetry.rs
index bff32be1..e538ce15 100644
--- a/src/telemetry.rs
+++ b/src/telemetry.rs
@@ -3,6 +3,7 @@
 //! The constants in this module are framework-owned labels, label values, and
 //! span names. They intentionally avoid request ids, trace ids, payload fields,
 //! aggregate ids, user ids, and other high-cardinality data.
+#![allow(clippy::items_after_test_module)]
 
 use crate::bus::FailureAction;
 
@@ -25,6 +26,9 @@ pub(crate) mod metric_names {
     pub(crate) const OUTBOX_PENDING_MESSAGES: &str = "distributed_outbox_pending_messages";
     pub(crate) const OUTBOX_OLDEST_PENDING_AGE_SECONDS: &str =
         "distributed_outbox_oldest_pending_age_seconds";
+    pub(crate) const GRAPHQL_REQUEST_TOTAL: &str = "distributed_graphql_request_total";
+    pub(crate) const GRAPHQL_REQUEST_DURATION_SECONDS: &str =
+        "distributed_graphql_request_duration_seconds";
 }
 
 #[cfg(feature = "metrics")]
@@ -110,6 +114,8 @@ pub(crate) mod privacy_policy {
         super::metric_labels::FAILURE_CLASS,
         super::metric_labels::ACTION,
         super::metric_labels::LE,
+        // GraphQL query engine (specs/query-service-graphql).
+        "root_field",
     ];
 
     pub(crate) const FORBIDDEN_METRIC_LABELS: &[&str] = &[
@@ -149,7 +155,12 @@ pub(crate) fn handler_error_status(error: &HandlerError) -> &'static str {
         HandlerError::Rejected(_) => dispatch_status::REJECTED,
         HandlerError::NotFound(_) => dispatch_status::NOT_FOUND,
         HandlerError::Unauthorized(_) => dispatch_status::UNAUTHORIZED,
-        HandlerError::Repository(_) => dispatch_status::REPOSITORY_ERROR,
+        HandlerError::Repository(_)
+        | HandlerError::Projection(_)
+        | HandlerError::UnqualifiedProjectionDelivery(_)
+        | HandlerError::ProjectionRepairPending { .. }
+        | HandlerError::ProjectionTerminalRecorded { .. }
+        | HandlerError::ProjectionDeliveryHalted { .. } => dispatch_status::REPOSITORY_ERROR,
         HandlerError::GuardRejected(_) => dispatch_status::GUARD_REJECTED,
         HandlerError::Other(_) => dispatch_status::OTHER_ERROR,
     }
diff --git a/tests/e2e-ui/.gitignore b/tests/e2e-ui/.gitignore
new file mode 100644
index 00000000..0e859a8b
--- /dev/null
+++ b/tests/e2e-ui/.gitignore
@@ -0,0 +1,16 @@
+/target
+**/*.db
+.make-*
+e2e-ui.env
+docker/machinekey/
+docker/web-client.secret
+ui/node_modules
+ui/build
+ui/.svelte-kit
+ui/.vite
+docker/login-client/pat
+node_modules
+e2e/.auth
+playwright-report
+test-results
+blob-report
diff --git a/tests/e2e-ui/Cargo.toml b/tests/e2e-ui/Cargo.toml
new file mode 100644
index 00000000..8f5c0320
--- /dev/null
+++ b/tests/e2e-ui/Cargo.toml
@@ -0,0 +1,36 @@
+# Nested workspace fixture: e2e-ui (todos + live chat subscriptions).
+# Not a member of the main `distributed` workspace — run from this directory:
+#   make
+#   make test
+[workspace]
+resolver = "2"
+members = [
+    "crates/todo-domain",
+    "crates/chat-domain",
+    "crates/blob-domain",
+    "crates/readmodels",
+    "crates/service",
+    "crates/runner",
+    "crates/suite",
+]
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+publish = false
+
+[workspace.dependencies]
+distributed = { path = "../..", features = ["sqlite", "postgres", "http", "graphql", "metrics"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "time", "sync"] }
+thiserror = "1"
+axum = "0.8"
+reqwest = { version = "0.13", default-features = false, features = ["json", "rustls"] }
+sqlx = { version = "0.9", default-features = false, features = ["runtime-tokio", "sqlite", "postgres"] }
+jsonwebtoken = "9"
+rsa = "0.9"
+rand = "0.8"
+base64 = "0.22"
+uuid = { version = "1", features = ["v7"] }
diff --git a/tests/e2e-ui/Makefile b/tests/e2e-ui/Makefile
new file mode 100644
index 00000000..b8499bc8
--- /dev/null
+++ b/tests/e2e-ui/Makefile
@@ -0,0 +1,174 @@
+# e2e-ui template — run from this directory.
+#
+#   make up          # Docker: Postgres + Zitadel + bootstrap env
+#   make run         # API + UI (uses e2e-ui.env if present)
+#   make test         # offline unit/suite/UI structural
+#   make test-live    # against stack (E2E_STACK=1)
+#   make test-browser # Playwright UI e2e (needs make up + make run)
+
+.PHONY: all up down run run-api stop test test-domain test-suite test-live \
+	test-browser test-browser-install js-install js-build ui-install ui-build ui-check ui-test \
+	gen-client check-client check clean help
+
+# Defaults only — do NOT `include e2e-ui.env` (shell-quoted dotenv breaks Make).
+# Recipes `source` the env file so values stay clean.
+BIND         ?= 127.0.0.1:8791
+API_PORT     ?= 8791
+BASE_URL     ?= http://127.0.0.1:8791
+UI_PORT      ?= 5180
+# localhost required for Auth.js cookies over HTTP (SvelteKit Secure default)
+UI_URL       ?= http://localhost:5180
+UI_HOST      ?= localhost
+ENV_FILE     ?= e2e-ui.env
+NPM          ?= npm
+JS_DIR       ?= ../../js
+CARGO_TEST_FLAGS ?= -- --nocapture
+
+DATABASE_URL ?= sqlite:./e2e-ui.db?mode=rwc
+
+all: run
+
+## Docker stack + OIDC bootstrap → e2e-ui.env
+up:
+	chmod +x scripts/up.sh
+	./scripts/up.sh
+
+down:
+	docker compose -f docker/docker-compose.yml down
+
+## API + UI (loads e2e-ui.env when present)
+run: ui-install
+	@set -e; \
+	if [ -f $(ENV_FILE) ]; then set -a; . ./$(ENV_FILE); set +a; fi; \
+	_bind="$${BIND:-127.0.0.1:8791}"; \
+	_api_port="$${_bind##*:}"; \
+	_base="$${E2E_API_ORIGIN:-http://$${_bind}}"; \
+	_ui_port="$(UI_PORT)"; \
+	_ui_host="$(UI_HOST)"; \
+	_ui="$${E2E_UI_ORIGIN:-http://$${_ui_host}:$${_ui_port}}"; \
+	export AUTH_URL="$${_ui}"; \
+	export AUTH_USE_SECURE_COOKIES="false"; \
+	lsof -ti:$${_api_port} 2>/dev/null | xargs kill -9 2>/dev/null || true; \
+	lsof -ti:$${_ui_port} 2>/dev/null | xargs kill -9 2>/dev/null || true; \
+	rm -f .make-runner.pid .make-ui.pid .make-runner.log; \
+	echo "starting API ($${DATABASE_URL:-sqlite}) on $$_base …"; \
+	cargo run -p e2e-runner --bin e2e-ui > .make-runner.log 2>&1 & \
+	echo $$! > .make-runner.pid; \
+	ok=0; \
+	for i in $$(seq 1 80); do \
+		code=$$(curl -s -o /dev/null -w '%{http_code}' -X POST "$${_base}/graphql" \
+			-H 'content-type: application/json' \
+			-d '{"query":"{ __typename }"}' 2>/dev/null || echo 000); \
+		if [ "$$code" = "200" ] || [ "$$code" = "401" ]; then ok=1; break; fi; \
+		sleep 0.25; \
+	done; \
+	if [ "$$ok" != "1" ]; then \
+		echo "API failed:"; tail -80 .make-runner.log; exit 1; \
+	fi; \
+	echo "API ready (HTTP probe $$code). starting UI …"; \
+	cd ui && $(NPM) run dev -- --host $$_ui_host --port $$_ui_port & \
+	echo $$! > ../.make-ui.pid; \
+	cd ..; \
+	cleanup() { \
+		[ -f .make-ui.pid ] && kill $$(cat .make-ui.pid) 2>/dev/null || true; \
+		[ -f .make-runner.pid ] && kill $$(cat .make-runner.pid) 2>/dev/null || true; \
+		lsof -ti:$${_api_port} 2>/dev/null | xargs kill -9 2>/dev/null || true; \
+		lsof -ti:$${_ui_port} 2>/dev/null | xargs kill -9 2>/dev/null || true; \
+		rm -f .make-runner.pid .make-ui.pid; \
+	}; \
+	trap cleanup EXIT INT TERM; \
+	echo ""; \
+	echo "  UI     $$_ui"; \
+	echo "  API    $$_base"; \
+	echo "  GraphiQL $$_base/graphql"; \
+	echo "  WS     $$_base/graphql/ws"; \
+	echo "  Ctrl-C stops both"; \
+	echo ""; \
+	wait $$(cat .make-ui.pid) 2>/dev/null || wait
+
+run-api:
+	@if [ -f $(ENV_FILE) ]; then set -a; . ./$(ENV_FILE); set +a; fi; \
+	cargo run -p e2e-runner
+
+stop:
+	@if [ -f .make-ui.pid ]; then kill $$(cat .make-ui.pid) 2>/dev/null || true; fi
+	@if [ -f .make-runner.pid ]; then kill $$(cat .make-runner.pid) 2>/dev/null || true; fi
+	@lsof -ti:$(API_PORT) 2>/dev/null | xargs kill -9 2>/dev/null || true
+	@lsof -ti:$(UI_PORT) 2>/dev/null | xargs kill -9 2>/dev/null || true
+	@rm -f .make-runner.pid .make-ui.pid
+	@echo stopped
+
+test: test-domain test-suite ui-install ui-build ui-check ui-test
+	@echo "OK — offline domain + suite + UI build + typecheck + structural tests"
+
+test-domain:
+	cargo test -p todo-domain -p chat-domain $(CARGO_TEST_FLAGS)
+
+test-suite:
+	cargo test -p e2e-suite --test behavioral $(CARGO_TEST_FLAGS)
+	cargo test -p e2e-suite --test oidc_pg -- --nocapture
+
+## Live OIDC+Postgres (requires make up + API running with e2e-ui.env)
+test-live:
+	@if [ ! -f $(ENV_FILE) ]; then echo "missing $(ENV_FILE) — run make up"; exit 1; fi
+	set -a; . ./$(ENV_FILE); set +a; \
+	E2E_STACK=1 cargo test -p e2e-suite --test oidc_pg -- --nocapture
+
+## Browser e2e (Playwright). Requires make up + make run (UI :5180, API :8791).
+test-browser-install:
+	$(NPM) install
+	npx playwright install chromium
+
+test-browser: test-browser-install
+	@if [ ! -f $(ENV_FILE) ]; then echo "missing $(ENV_FILE) — run make up"; exit 1; fi
+	@code=$$(curl -s -o /dev/null -w '%{http_code}' "$(UI_URL)/" 2>/dev/null || echo 000); \
+	if [ "$$code" = "000" ]; then echo "UI not reachable at $(UI_URL) — start: make run"; exit 1; fi
+	$(NPM) run test:browser
+
+js-install:
+	cd $(JS_DIR) && $(NPM) install --ignore-scripts
+
+js-build: js-install
+	cd $(JS_DIR) && $(NPM) run build
+
+ui-install: js-build
+	cd ui && $(NPM) install
+
+ui-build: ui-install
+	cd ui && $(NPM) run build
+
+ui-check: ui-install
+	cd ui && $(NPM) run check
+
+ui-test: ui-install
+	cd ui && $(NPM) test
+
+## One app-owned config drives Vite development, explicit generation, and CI drift checks.
+## Manifests remain ephemeral; compiler-owned output remains committed and inspectable.
+gen-client: ui-install
+	cd ui && $(NPM) run client:generate
+
+## Byte/file-set drift check through dctl --check; never repairs generated files.
+check-client: ui-install
+	cd ui && $(NPM) run client:check
+
+check: check-client
+	cargo check --workspace
+	cargo test -p todo-domain -p chat-domain --no-run
+	cargo test -p e2e-suite --test behavioral --no-run
+
+clean: stop
+	cargo clean
+	rm -f .make-runner.log e2e-ui.db
+	rm -rf ui/node_modules ui/build ui/.svelte-kit
+
+help:
+	@echo "e2e-ui"
+	@echo "  make up         Postgres + Zitadel + OIDC bootstrap → e2e-ui.env"
+	@echo "  make run        API + UI (source e2e-ui.env when present)"
+	@echo "  make test       offline suite + UI structural"
+	@echo "  make test-live  OIDC isolation against stack"
+	@echo "  make gen-client      typed Service → generated user/admin clients"
+	@echo "  make check-client    verify generated artifacts byte-for-byte"
+	@echo "  make down       docker compose down"
+	@echo "  GRAPHIQL=0      disable GraphiQL when running the API"
diff --git a/tests/e2e-ui/README.md b/tests/e2e-ui/README.md
new file mode 100644
index 00000000..7c50d4cc
--- /dev/null
+++ b/tests/e2e-ui/README.md
@@ -0,0 +1,272 @@
+# e2e-ui template
+
+Copyable **Distributed** service + SvelteKit UI. This README is the **code
+index**: where each “that feels like a real product” behavior lives, then how
+to run and test it.
+
+```bash
+cd tests/e2e-ui
+make up          # Postgres :5433 + Zitadel :18080 → e2e-ui.env
+set -a && source e2e-ui.env && set +a
+make run         # API :8791 + UI :5180
+```
+
+| URL | What |
+|-----|------|
+| http://127.0.0.1:5180/todos | Owner-scoped todos |
+| http://127.0.0.1:5180/chat | Lobby + live WS |
+| http://127.0.0.1:5180/blob | Projected map game |
+| http://127.0.0.1:5180/admin | Elevated client surface |
+| http://127.0.0.1:5180/login | Custom Login V2 (`alice` / `Password1!`) |
+| http://127.0.0.1:8791/graphql | GraphiQL |
+
+Demo users: `alice` / `bob` / `admin` · password `Password1!`
+
+---
+
+## Code index
+
+### UI — routes that teach the pattern
+
+Pages stay thin: co-located GraphQL for reads, generated commands for writes,
+one replica for SSR + client + live.
+
+| Path | What to notice |
+|------|----------------|
+| [`ui/src/routes/todos/+page.graphql`](ui/src/routes/todos/+page.graphql) | `query Todos @load` — compiler-owned SSR seed; no second client document. |
+| [`ui/src/routes/todos/+page.svelte`](ui/src/routes/todos/+page.svelte) | `Todos.use()` + `commands.todo.*`. Comment at top: no app cache adapter, no hand optimistic recipe. |
+| [`ui/src/routes/chat/+page.graphql`](ui/src/routes/chat/+page.graphql) | `@load @live` on **one** query — SSR, cache, and WS companion from the same declaration. |
+| [`ui/src/routes/chat/+page.svelte`](ui/src/routes/chat/+page.svelte) | `ChatMessages.use()` defaults live because the artifact has a companion; post via `commands.chat.post`. |
+| [`ui/src/routes/blob/[[gameId]]/+page.graphql`](ui/src/routes/blob/[[gameId]]/+page.graphql) | `blob_games` + `owner { … }` join; `@load` seeds the board list. |
+| [`ui/src/routes/blob/[[gameId]]/+page.svelte`](ui/src/routes/blob/[[gameId]]/+page.svelte) | URL selects game; keyboard → `commands.blob.move`; board/`score` from replica (projected payload). |
+| [`ui/src/routes/+layout.server.ts`](ui/src/routes/+layout.server.ts) | `createDistributedSvelteKitServer({ routes: DISTRIBUTED_ROUTE_OPERATIONS, … })` — one loader for all user `@load` ops. |
+| [`ui/src/routes/+layout.svelte`](ui/src/routes/+layout.svelte) | `provideDistributed` + hydrate on navigation; session source shared by HTTP, WS, commands. |
+| [`ui/src/routes/admin/+layout.server.ts`](ui/src/routes/admin/+layout.server.ts) | **Separate** `$distributed/admin` surface; 403 before any elevated GraphQL runs. |
+| [`ui/src/routes/admin/+page.graphql`](ui/src/routes/admin/+page.graphql) | Admin-only document — never imported by the user client tree. |
+| [`ui/src/auth.ts`](ui/src/auth.ts) | Auth.js + Zitadel scopes/groups; access token on session for GraphQL Bearer. |
+| [`ui/src/routes/login/+page.server.ts`](ui/src/routes/login/+page.server.ts) | Custom Login V2 (Session API + CreateCallback), not stock Zitadel login UI. |
+| [`ui/src/lib/server/zitadel-session.ts`](ui/src/lib/server/zitadel-session.ts) | Server-only PAT path for login/signup. |
+| [`ui/src/lib/roles.ts`](ui/src/lib/roles.ts) | IdP groups → engine `user` / `admin`. |
+
+Generated (do not hand-edit; `make gen-client`):
+
+| Path | Role |
+|------|------|
+| [`ui/src/lib/generated/user/`](ui/src/lib/generated/user/) | Ops, commands, route registry, SvelteKit adapter for `e2e-ui` |
+| [`ui/src/lib/generated/admin/`](ui/src/lib/generated/admin/) | Same for `e2e-ui-admin` |
+
+`$distributed` re-exports the user surface; admin layout imports `$distributed/admin`.
+
+### Rust — domain → inventory → edge
+
+| Path | What to notice |
+|------|----------------|
+| [`crates/todo-domain/src/models/todo.rs`](crates/todo-domain/src/models/todo.rs) | Plain struct + `ensure_owner` + `@sourced` command methods. |
+| [`crates/chat-domain/src/models/chat_message.rs`](crates/chat-domain/src/models/chat_message.rs) | Minimal post aggregate. |
+| [`crates/blob-domain/src/models/blob_game.rs`](crates/blob-domain/src/models/blob_game.rs) | Move / level logic; emits facts the projector (or Projected path) maps. |
+| [`crates/readmodels/src/models/todo_view.rs`](crates/readmodels/src/models/todo_view.rs) | `#[table("todos")]` read model. |
+| [`crates/readmodels/src/models/blob_game_view.rs`](crates/readmodels/src/models/blob_game_view.rs) | Projected row + `belongs_to` `AuthUserView` owner join. |
+| [`crates/readmodels/src/models/chat_message_view.rs`](crates/readmodels/src/models/chat_message_view.rs) | Chat row + author join. |
+| [`crates/service/src/service.rs`](crates/service/src/service.rs) | **Center of gravity**: dual client surfaces, projectors vs direct projection, RLS grants, typed commands, OIDC claim map. |
+| [`crates/service/src/handlers/commands/create.rs`](crates/service/src/handlers/commands/create.rs) | `owner_id` from trusted claim — never from client input. |
+| [`crates/service/src/handlers/commands/blob_move.rs`](crates/service/src/handlers/commands/blob_move.rs) | `PreparedCommand<Projected<BlobGameView>>` + `ctx.projected(...)`. |
+| [`crates/service/src/handlers/events/project_todo.rs`](crates/service/src/handlers/events/project_todo.rs) | Eventual projector path (todos). |
+| [`crates/service/src/handlers/events/project_chat.rs`](crates/service/src/handlers/events/project_chat.rs) | Eventual projector path (chat → live). |
+| [`crates/service/src/handlers/ingestors/zitadel/`](crates/service/src/handlers/ingestors/zitadel/) | Ingress + scrape → `auth_users` ([runbook](docs/zitadel-ingestor.md)). |
+| [`crates/runner/src/main.rs`](crates/runner/src/main.rs) | Process wiring: Postgres/SQLite, OidcBearer vs DevHeaders, GraphiQL. |
+
+RLS sketch (from `service.rs` grants):
+
+```text
+user  → TodoView / BlobGameView rows: owner_id = claim(x-user-id)
+admin → all columns / all rows on the elevated surface
+```
+
+Command result shapes:
+
+| Domain | Result | UI effect |
+|--------|--------|-----------|
+| blob | `Projected<BlobGameView>` | Replica writes map/score with the mutation (no dual-write) |
+| todo / chat | Fact + projector | Accept command → projector → optional `@live` push |
+
+### Browser e2e (what CI trusts)
+
+| Spec | Covers |
+|------|--------|
+| [`e2e/todos.user.spec.ts`](e2e/todos.user.spec.ts) | Create / complete / archive as alice |
+| [`e2e/chat.user.spec.ts`](e2e/chat.user.spec.ts) | Post + live list |
+| [`e2e/blob.user.spec.ts`](e2e/blob.user.spec.ts) | Moves, projected board, revalidation races |
+| [`e2e/admin.admin.spec.ts`](e2e/admin.admin.spec.ts) | Elevated surface + force archive |
+| [`e2e/unauth.anon.spec.ts`](e2e/unauth.anon.spec.ts) | Redirects when logged out |
+| [`e2e/helpers/login.ts`](e2e/helpers/login.ts) | Shared OIDC + Login V2 flow |
+
+---
+
+## Patterns (one-liners)
+
+| Pattern | Where |
+|---------|--------|
+| Multi-crate domain | `crates/*-domain`, `readmodels`, `service` |
+| Projectors-only for todos/chat | handlers never dual-write those tables |
+| Atomic `Projected` for blob | `blob_move.rs` / `blob_start*.rs` |
+| GraphQL RLS | `service.rs` `client_grants` + model permissions |
+| Live subscriptions | `@live` + ChangeHub |
+| Two client surfaces | `DISTRIBUTED_CLIENT_SURFACE` / `_ADMIN_` |
+| Real OIDC | Zitadel + Auth.js + custom `/login` |
+| SSR without flash | root layout + `DISTRIBUTED_ROUTE_OPERATIONS` |
+| Causal replica | `@hops-ops/distributed` via `file:../../../js` |
+
+---
+
+## Architecture sketch
+
+```text
+Browser (SSR + client)
+  Auth.js → Zitadel /oauth/v2/authorize
+         → UI /login?authRequest=V2_…  (Session API + CreateCallback)
+         → Auth.js /auth/callback/oidc → access_token
+  GraphQL HTTP  Authorization: Bearer …
+  GraphQL WS    connection_init.authorization
+
+Zitadel edge (:18080)
+  Login V2 baseUri → Todos UI origin
+
+e2e-runner
+  OidcBearer (or DevHeaders offline)
+  Postgres event store + bus + locks
+  Projectors / Projected → ChangeHub → subs
+```
+
+**Auth flow:** Auth.js → Zitadel authorize → **your** `/login?authRequest=V2_…` →
+callback. Needs `ZITADEL_SERVICE_USER_TOKEN` from `make up`. After `make up`,
+restart `make run`.
+
+---
+
+## Typed client generation
+
+Rust `Service` inventory is source of truth. Two pool-free exports:
+
+| Entrypoint | Application | Roles | Used by |
+|------------|-------------|-------|---------|
+| `e2e_service::distributed_client_surface` | `e2e-ui` | `admin`, `user` | App shell + user routes |
+| `e2e_service::distributed_admin_client_surface` | `e2e-ui-admin` | `admin` | Nested `/admin` only |
+
+```bash
+make gen-client      # both surfaces from ui/distributed.config.js
+make check-client    # dctl --check without rewrite
+```
+
+Root layout:
+
+```ts
+const distributed = createDistributedSvelteKitServer({
+  routes: DISTRIBUTED_ROUTE_OPERATIONS,
+  getSession: ({ locals }) => locals.auth(),
+  getRole: (session) => engineRoleFromGroups(session?.user?.groups)
+});
+export const load = distributed.load;
+```
+
+Root shell:
+
+```ts
+import { provideDistributed } from '$distributed';
+
+const client = provideDistributed({
+  session,
+  hydration: data.distributed,
+  authority: data.distributedAuthority
+});
+```
+
+Route:
+
+```ts
+import { Todos, useCommands } from '$distributed';
+
+const todos = Todos.use();
+const commands = useCommands();
+await commands.todo.create({ title });
+```
+
+**Agent rule:** after inventory / command contract / `+page.graphql` changes, run
+`make check-client` and commit generated diffs. Generated trees are outputs.
+
+---
+
+## Tests & CI
+
+```bash
+make test          # domain + behavioral + UI unit (no Docker)
+make test-live     # OIDC isolation (needs make up + API)
+make test-browser  # Playwright (needs make up + make run)
+```
+
+| Project | Specs | Session |
+|---------|--------|---------|
+| `chromium-anon` | `e2e/*.anon.spec.ts` | none |
+| `setup-alice` → `chromium-user` | `e2e/*.user.spec.ts` | alice |
+| `setup-admin` → `chromium-admin` | `e2e/*.admin.spec.ts` | admin |
+
+CI: [`.github/workflows/integration-e2e-ui.yaml`](../../.github/workflows/integration-e2e-ui.yaml)
+— offline `make test`, then browser with `make up` + API/UI + Playwright.
+
+### Identity modes (suite)
+
+| Profile | When | Auth |
+|---------|------|------|
+| **DevHeaders** | `OIDC_*` unset | `x-user-id` / `x-role` (`make test`) |
+| **OidcBearer** | after `source e2e-ui.env` | real Bearer (`make test-live`) |
+
+Always-on units: `cargo test -p e2e-service --lib`, `cargo test -p todo-domain --lib`,
+`cd ui && npm test`. Do not run DevHeaders behavioral against an OIDC-only process.
+
+### WebSocket auth
+
+Browsers cannot set `Authorization` on the upgrade. Production path: unauthenticated
+upgrade, then `connection_init` with `{ "authorization": "Bearer …" }`. Chat page
+uses the session access token. Do not put long-lived tokens in query strings.
+
+---
+
+## Env (`e2e-ui.env` from `make up`)
+
+| Variable | Purpose |
+|----------|---------|
+| `DATABASE_URL` | Postgres (or `sqlite:…` offline) |
+| `OIDC_ISSUER` / `OIDC_AUDIENCE` | JWKS + aud |
+| `OIDC_CLIENT_ID` / `SECRET` | Auth.js |
+| `ZITADEL_SERVICE_USER_TOKEN` | Login V2 Session API (server only) |
+| `AUTH_SECRET` | cookie encryption |
+| `E2E_MACHINE_*` | suite JWT-bearer keys |
+
+Offline without Docker: `cargo run -p e2e-runner` (DevHeaders + SQLite); UI
+`make ui-install && cd ui && npm run dev` (sign-in needs `make up` for real OIDC).
+
+---
+
+## Crate map
+
+| Package | Role |
+|---------|------|
+| `todo-domain` / `chat-domain` / `blob-domain` | Aggregates |
+| `e2e-readmodels` | `todos`, `chat_messages`, `blob_games`, `auth_users` |
+| `e2e-service` | Handlers + GraphQL surface |
+| `e2e-runner` → bin `e2e-ui` | Process |
+| `e2e-suite` | Behavioral + gated OIDC |
+
+## Template usage
+
+Copy this folder: keep domains pure, swap `DATABASE_URL` / OIDC for your IdP,
+extend routes. In-repo fixture uses `@hops-ops/distributed` via
+`file:../../../js`; outside the monorepo, pin a released npm version.
+
+Normative design lives in the Distributed GitKB; this README is the checked-in
+fixture map.
+
+### Security notes
+
+- Set **`GRAPHIQL=0`** outside local dev.
+- Unset `OIDC_ISSUER` / `OIDC_AUDIENCE` → **DevHeaders** (local only).
+- UI `/admin` is convenience; **GraphQL field roles + handler guards** are the boundary.
diff --git a/tests/e2e-ui/crates/blob-domain/Cargo.toml b/tests/e2e-ui/crates/blob-domain/Cargo.toml
new file mode 100644
index 00000000..c6b22f07
--- /dev/null
+++ b/tests/e2e-ui/crates/blob-domain/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "blob-domain"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+
+[dependencies]
+distributed = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+rand = { workspace = true }
+
+[dev-dependencies]
+serde_json = { workspace = true }
diff --git a/tests/e2e-ui/crates/blob-domain/src/levels.rs b/tests/e2e-ui/crates/blob-domain/src/levels.rs
new file mode 100644
index 00000000..e5c0af4e
--- /dev/null
+++ b/tests/e2e-ui/crates/blob-domain/src/levels.rs
@@ -0,0 +1,263 @@
+//! Procedural levels inspired by ig-blob-game-model-service `lib/levels.ts`.
+//!
+//! Holes are placed with spacing heuristics (like the original), then we **prove
+//! passability**: there exists a path that visits every non-hole cell exactly once
+//! starting from the player (Hamiltonian path on the free-cell graph). Small grids
+//! make that check feasible.
+
+use rand::seq::SliceRandom;
+use rand::{Rng, SeedableRng};
+use rand::rngs::StdRng;
+
+use crate::models::tile;
+
+/// Playfield size. Original is 12×12; we use 6×6 so Hamiltonian passability
+/// checks stay fast on the command path while still varying layouts.
+pub const DEFAULT_SIZE: usize = 6;
+/// Holes on level 1 (scales up with level index, capped).
+pub const DEFAULT_HOLES: usize = 2;
+
+/// Fixed map used only in unit tests that need determinism without RNG.
+pub fn demo_map() -> Vec<Vec<u8>> {
+    use tile::*;
+    vec![
+        vec![PLAYER, UNVISITED, UNVISITED, UNVISITED, HOLE],
+        vec![UNVISITED, UNVISITED, UNVISITED, UNVISITED, UNVISITED],
+        vec![UNVISITED, UNVISITED, HOLE, UNVISITED, UNVISITED],
+        vec![UNVISITED, UNVISITED, UNVISITED, UNVISITED, UNVISITED],
+        vec![UNVISITED, UNVISITED, UNVISITED, UNVISITED, UNVISITED],
+    ]
+}
+
+/// Generate a random, **solvable** level. Retries until passable or falls back
+/// to a dense no-hole grid (always solvable).
+pub fn generate_level(level_index: u32) -> Vec<Vec<u8>> {
+    let mut rng = StdRng::from_entropy();
+    generate_level_with(&mut rng, level_index)
+}
+
+/// Same as [`generate_level`] with an injected RNG (tests / seeds).
+pub fn generate_level_with<R: Rng>(rng: &mut R, level_index: u32) -> Vec<Vec<u8>> {
+    let size = DEFAULT_SIZE;
+    // Slightly more holes as levels progress (capped).
+    let holes = (DEFAULT_HOLES + level_index.saturating_sub(1) as usize).min(size / 2);
+
+    for _ in 0..80 {
+        if let Some(map) = try_generate(rng, size, holes) {
+            if is_hamiltonian_passable(&map) {
+                return map;
+            }
+        }
+    }
+
+    // Guaranteed solvable: no holes.
+    empty_playable(size)
+}
+
+fn empty_playable(size: usize) -> Vec<Vec<u8>> {
+    let mut map = vec![vec![tile::UNVISITED; size]; size];
+    map[0][0] = tile::PLAYER;
+    map
+}
+
+fn try_generate<R: Rng>(rng: &mut R, size: usize, hole_count: usize) -> Option<Vec<Vec<u8>>> {
+    let mut map = empty_playable(size);
+    let mut candidates: Vec<(usize, usize)> = Vec::new();
+    for r in 0..size {
+        for c in 0..size {
+            // Keep start clear; avoid corner-trapping start neighbors sometimes
+            if (r, c) == (0, 0) {
+                continue;
+            }
+            // Soft perimeter rule from original: fewer holes on the outer ring
+            // for the first two rings near start.
+            if (r == 0 && c == 1) || (r == 1 && c == 0) {
+                continue;
+            }
+            candidates.push((r, c));
+        }
+    }
+    candidates.shuffle(rng);
+
+    let mut placed: Vec<(usize, usize)> = Vec::new();
+    for (r, c) in candidates {
+        if placed.len() >= hole_count {
+            break;
+        }
+        if hole_ok(&placed, r, c, size) {
+            map[r][c] = tile::HOLE;
+            placed.push((r, c));
+        }
+    }
+
+    // Connectivity of free cells (necessary, not sufficient)
+    if !is_connected_free(&map) {
+        return None;
+    }
+    Some(map)
+}
+
+/// Original-inspired spacing: holes not too close (Manhattan < 3 on small grid).
+fn hole_ok(placed: &[(usize, usize)], r: usize, c: usize, size: usize) -> bool {
+    // Don't block the entire first row/col start corridor
+    if r == 0 && c < 2 {
+        return false;
+    }
+    if c == 0 && r < 2 {
+        return false;
+    }
+    // Prefer not on absolute outer edge for tiny grids (original avoided perimeter)
+    if size >= 6 && (r == size - 1 || c == size - 1) && (r == 0 || c == 0) {
+        // allow but continue checks
+    }
+    for &(pr, pc) in placed {
+        let dist = pr.abs_diff(r) + pc.abs_diff(c);
+        if dist < 3 {
+            return false;
+        }
+        // Reciprocal / diagonal pattern heuristics (simplified from original)
+        if pr == c && pc == r {
+            return false;
+        }
+    }
+    true
+}
+
+fn free_cells(map: &[Vec<u8>]) -> Vec<(usize, usize)> {
+    let mut out = Vec::new();
+    for (r, row) in map.iter().enumerate() {
+        for (c, &t) in row.iter().enumerate() {
+            if t != tile::HOLE {
+                out.push((r, c));
+            }
+        }
+    }
+    out
+}
+
+fn is_connected_free(map: &[Vec<u8>]) -> bool {
+    let free = free_cells(map);
+    if free.is_empty() {
+        return false;
+    }
+    let h = map.len();
+    let w = map[0].len();
+    let mut seen = vec![vec![false; w]; h];
+    let mut stack = vec![(0usize, 0usize)];
+    if map[0][0] == tile::HOLE {
+        return false;
+    }
+    seen[0][0] = true;
+    let mut count = 0usize;
+    while let Some((r, c)) = stack.pop() {
+        count += 1;
+        for (nr, nc) in neighbors(r, c, h, w) {
+            if map[nr][nc] != tile::HOLE && !seen[nr][nc] {
+                seen[nr][nc] = true;
+                stack.push((nr, nc));
+            }
+        }
+    }
+    count == free.len()
+}
+
+fn neighbors(r: usize, c: usize, h: usize, w: usize) -> Vec<(usize, usize)> {
+    let mut n = Vec::with_capacity(4);
+    if r > 0 {
+        n.push((r - 1, c));
+    }
+    if r + 1 < h {
+        n.push((r + 1, c));
+    }
+    if c > 0 {
+        n.push((r, c - 1));
+    }
+    if c + 1 < w {
+        n.push((r, c + 1));
+    }
+    n
+}
+
+/// True if some path visits every non-hole cell exactly once from the player.
+pub fn is_hamiltonian_passable(map: &[Vec<u8>]) -> bool {
+    let free = free_cells(map);
+    let n = free.len();
+    if n == 0 {
+        return false;
+    }
+    let h = map.len();
+    let w = map[0].len();
+    let mut index = vec![vec![None; w]; h];
+    for (i, &(r, c)) in free.iter().enumerate() {
+        index[r][c] = Some(i);
+    }
+    // adjacency list
+    let mut adj = vec![Vec::new(); n];
+    for (i, &(r, c)) in free.iter().enumerate() {
+        for (nr, nc) in neighbors(r, c, h, w) {
+            if let Some(j) = index[nr][nc] {
+                adj[i].push(j);
+            }
+        }
+    }
+    let start = index[0][0].expect("player at 0,0");
+    let mut visited = vec![false; n];
+    visited[start] = true;
+    hamilton_dfs(start, 1, n, &adj, &mut visited)
+}
+
+fn hamilton_dfs(
+    u: usize,
+    depth: usize,
+    n: usize,
+    adj: &[Vec<usize>],
+    visited: &mut [bool],
+) -> bool {
+    if depth == n {
+        return true;
+    }
+    for &v in &adj[u] {
+        if !visited[v] {
+            visited[v] = true;
+            if hamilton_dfs(v, depth + 1, n, adj, visited) {
+                return true;
+            }
+            visited[v] = false;
+        }
+    }
+    false
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use rand::SeedableRng;
+
+    #[test]
+    fn generated_maps_differ_and_are_passable() {
+        let mut rng = StdRng::seed_from_u64(42);
+        let a = generate_level_with(&mut rng, 1);
+        let b = generate_level_with(&mut rng, 1);
+        assert!(is_hamiltonian_passable(&a));
+        assert!(is_hamiltonian_passable(&b));
+        // Same seed stream still progresses — maps should usually differ
+        assert_ne!(a, b, "expected variety across sequential generates");
+        assert_eq!(a[0][0], tile::PLAYER);
+        assert_eq!(b[0][0], tile::PLAYER);
+    }
+
+    #[test]
+    fn empty_grid_passable() {
+        assert!(is_hamiltonian_passable(&empty_playable(5)));
+    }
+
+    #[test]
+    fn disconnected_not_passable() {
+        let mut m = empty_playable(3);
+        // Wall of holes isolating bottom-right
+        m[0][1] = tile::HOLE;
+        m[1][0] = tile::HOLE;
+        m[1][1] = tile::HOLE;
+        assert!(!is_connected_free(&m) || !is_hamiltonian_passable(&m));
+    }
+}
diff --git a/tests/e2e-ui/crates/blob-domain/src/lib.rs b/tests/e2e-ui/crates/blob-domain/src/lib.rs
new file mode 100644
index 00000000..c47e9f86
--- /dev/null
+++ b/tests/e2e-ui/crates/blob-domain/src/lib.rs
@@ -0,0 +1,13 @@
+//! BlobGame aggregate — grid trail game (remake of ig-blob-game-model-service).
+//!
+//! Tile ints match JS `constants.ts` (player=9, hole=0, unvisited=1, visited=2,
+//! dead_by_suicide=3, dead_by_hole=4). Read models update only from emitted facts.
+
+pub mod levels;
+pub mod models;
+
+pub use levels::{demo_map, generate_level, generate_level_with, is_hamiltonian_passable};
+pub use models::tile;
+pub use models::{
+    test_map_no_holes, test_map_with_hole, BlobError, BlobGame, BlobGameFact, Direction,
+};
diff --git a/tests/e2e-ui/crates/blob-domain/src/models/blob_error.rs b/tests/e2e-ui/crates/blob-domain/src/models/blob_error.rs
new file mode 100644
index 00000000..1f83604c
--- /dev/null
+++ b/tests/e2e-ui/crates/blob-domain/src/models/blob_error.rs
@@ -0,0 +1,27 @@
+use thiserror::Error;
+
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum BlobError {
+    #[error("game already exists")]
+    AlreadyExists,
+    #[error("game not found / not created")]
+    NotCreated,
+    #[error("empty game id")]
+    EmptyId,
+    #[error("empty owner id")]
+    EmptyOwner,
+    #[error("not the owner")]
+    NotOwner,
+    #[error("player is dead")]
+    PlayerDead,
+    #[error("current level not completed")]
+    LevelNotComplete,
+    #[error("no active level")]
+    NoActiveLevel,
+    #[error("invalid map: {0}")]
+    InvalidMap(String),
+    #[error("cannot move: {0}")]
+    CannotMove(String),
+    #[error(transparent)]
+    Event(#[from] distributed::EventRecordError),
+}
diff --git a/tests/e2e-ui/crates/blob-domain/src/models/blob_game.rs b/tests/e2e-ui/crates/blob-domain/src/models/blob_game.rs
new file mode 100644
index 00000000..0b13d5cf
--- /dev/null
+++ b/tests/e2e-ui/crates/blob-domain/src/models/blob_game.rs
@@ -0,0 +1,477 @@
+use distributed::{sourced, Entity};
+use serde::{Deserialize, Serialize};
+
+use crate::levels::generate_level;
+
+use super::tile;
+use super::{BlobError, BlobGameFact, Direction};
+
+/// Tiny 3×3 map for unit tests (player top-left, no holes).
+pub fn test_map_no_holes() -> Vec<Vec<u8>> {
+    use tile::*;
+    vec![
+        vec![PLAYER, UNVISITED, UNVISITED],
+        vec![UNVISITED, UNVISITED, UNVISITED],
+        vec![UNVISITED, UNVISITED, UNVISITED],
+    ]
+}
+
+pub fn test_map_with_hole() -> Vec<Vec<u8>> {
+    use tile::*;
+    vec![
+        vec![PLAYER, HOLE, UNVISITED],
+        vec![UNVISITED, UNVISITED, UNVISITED],
+        vec![UNVISITED, UNVISITED, UNVISITED],
+    ]
+}
+
+fn validate_map(map: &[Vec<u8>]) -> Result<(), BlobError> {
+    if map.is_empty() || map[0].is_empty() {
+        return Err(BlobError::InvalidMap("empty map".into()));
+    }
+    let w = map[0].len();
+    let mut players = 0usize;
+    for (r, row) in map.iter().enumerate() {
+        if row.len() != w {
+            return Err(BlobError::InvalidMap(format!("ragged row {r}")));
+        }
+        for &t in row {
+            if t == tile::PLAYER {
+                players += 1;
+            }
+        }
+    }
+    if players != 1 {
+        return Err(BlobError::InvalidMap(format!(
+            "expected exactly one player tile, found {players}"
+        )));
+    }
+    Ok(())
+}
+
+fn map_to_json(map: &[Vec<u8>]) -> String {
+    serde_json::to_string(map).unwrap_or_else(|_| "[]".into())
+}
+
+fn status_of(player_dead: bool, level_complete: bool) -> String {
+    if player_dead {
+        "dead".into()
+    } else if level_complete {
+        "level_complete".into()
+    } else {
+        "active".into()
+    }
+}
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct BlobGame {
+    #[serde(skip, default)]
+    pub entity: Entity,
+    pub game_id: String,
+    pub owner_id: String,
+    pub score: i64,
+    pub player_dead: bool,
+    /// 0 = no level yet; 1+ = active level index (1-based like JS).
+    pub current_level: i64,
+    pub current_level_completed: bool,
+    /// Current level map only (demo keeps one active map in state).
+    pub map: Vec<Vec<u8>>,
+}
+
+impl BlobGame {
+    pub fn is_created(&self) -> bool {
+        !self.game_id.is_empty()
+    }
+
+    pub fn ensure_owner(&self, owner_id: &str) -> Result<(), BlobError> {
+        if !self.is_created() {
+            return Err(BlobError::NotCreated);
+        }
+        if self.owner_id != owner_id {
+            return Err(BlobError::NotOwner);
+        }
+        Ok(())
+    }
+
+    pub fn fact(&self) -> BlobGameFact {
+        BlobGameFact {
+            game_id: self.game_id.clone(),
+            owner_id: self.owner_id.clone(),
+            score: self.score,
+            player_dead: self.player_dead,
+            current_level: self.current_level,
+            current_level_completed: self.current_level_completed,
+            map_json: map_to_json(&self.map),
+            status: status_of(self.player_dead, self.current_level_completed),
+        }
+    }
+
+    fn player_pos(&self) -> Result<(usize, usize), BlobError> {
+        for (r, row) in self.map.iter().enumerate() {
+            for (c, &t) in row.iter().enumerate() {
+                if t == tile::PLAYER {
+                    return Ok((r, c));
+                }
+            }
+        }
+        Err(BlobError::NoActiveLevel)
+    }
+}
+
+#[sourced(entity, events = "BlobGameEvent", aggregate_type = "blob")]
+impl BlobGame {
+    /// Create game shell (no map yet). Level 0 is "completed" so first level can start.
+    pub fn initialize(
+        &mut self,
+        game_id: impl Into<String>,
+        owner_id: impl Into<String>,
+    ) -> Result<(), BlobError> {
+        if self.is_created() {
+            return Err(BlobError::AlreadyExists);
+        }
+        let game_id = game_id.into();
+        let owner_id = owner_id.into();
+        if game_id.trim().is_empty() {
+            return Err(BlobError::EmptyId);
+        }
+        if owner_id.trim().is_empty() {
+            return Err(BlobError::EmptyOwner);
+        }
+        self.record_initialized(game_id, owner_id)?;
+        Ok(())
+    }
+
+    #[event("blob.initialized")]
+    fn record_initialized(&mut self, game_id: String, owner_id: String) {
+        self.entity.set_id(&game_id);
+        self.game_id = game_id;
+        self.owner_id = owner_id;
+        self.score = 0;
+        self.player_dead = false;
+        self.current_level = 0;
+        self.current_level_completed = true;
+        self.map = Vec::new();
+    }
+
+    /// Append/start a level map. Requires current level complete and player alive.
+    pub fn start_level(
+        &mut self,
+        owner_id: &str,
+        map: Vec<Vec<u8>>,
+    ) -> Result<(), BlobError> {
+        self.ensure_owner(owner_id)?;
+        if self.player_dead {
+            return Err(BlobError::PlayerDead);
+        }
+        if !self.current_level_completed {
+            return Err(BlobError::LevelNotComplete);
+        }
+        validate_map(&map)?;
+        let next = self.current_level + 1;
+        self.record_level_started(next, map)?;
+        Ok(())
+    }
+
+    #[event("blob.level_started")]
+    fn record_level_started(&mut self, current_level: i64, map: Vec<Vec<u8>>) {
+        self.current_level = current_level;
+        self.map = map;
+        self.current_level_completed = false;
+        self.player_dead = false;
+    }
+
+    /// Create game and start a **generated** passable level (`blob.started`).
+    pub fn start_with_demo(
+        &mut self,
+        game_id: impl Into<String>,
+        owner_id: impl Into<String>,
+    ) -> Result<(), BlobError> {
+        self.start_with_map(game_id, owner_id, generate_level(1))
+    }
+
+    /// Create game with an explicit map (tests / fixtures).
+    pub fn start_with_map(
+        &mut self,
+        game_id: impl Into<String>,
+        owner_id: impl Into<String>,
+        map: Vec<Vec<u8>>,
+    ) -> Result<(), BlobError> {
+        if self.is_created() {
+            return Err(BlobError::AlreadyExists);
+        }
+        let game_id = game_id.into();
+        let owner_id = owner_id.into();
+        if game_id.trim().is_empty() {
+            return Err(BlobError::EmptyId);
+        }
+        if owner_id.trim().is_empty() {
+            return Err(BlobError::EmptyOwner);
+        }
+        validate_map(&map)?;
+        self.record_started(game_id, owner_id, 1, map)?;
+        Ok(())
+    }
+
+    /// Start next level with a freshly generated passable map.
+    pub fn start_next_generated_level(&mut self, owner_id: &str) -> Result<(), BlobError> {
+        let next = self.current_level + 1;
+        let map = generate_level(next as u32);
+        self.start_level(owner_id, map)
+    }
+
+    #[event("blob.started")]
+    fn record_started(
+        &mut self,
+        game_id: String,
+        owner_id: String,
+        current_level: i64,
+        map: Vec<Vec<u8>>,
+    ) {
+        self.entity.set_id(&game_id);
+        self.game_id = game_id;
+        self.owner_id = owner_id;
+        self.score = 0;
+        self.player_dead = false;
+        self.current_level = current_level;
+        self.current_level_completed = false;
+        self.map = map;
+    }
+
+    pub fn move_dir(&mut self, owner_id: &str, direction: Direction) -> Result<(), BlobError> {
+        self.ensure_owner(owner_id)?;
+        if self.player_dead {
+            return Err(BlobError::PlayerDead);
+        }
+        if self.current_level == 0 || self.map.is_empty() {
+            return Err(BlobError::NoActiveLevel);
+        }
+        let (r, c) = self.player_pos()?;
+        let (nr, nc) = match direction {
+            Direction::Up => {
+                if r == 0 {
+                    return Err(BlobError::CannotMove("row already 0".into()));
+                }
+                (r - 1, c)
+            }
+            Direction::Down => {
+                if r + 1 >= self.map.len() {
+                    return Err(BlobError::CannotMove("already at bottom edge".into()));
+                }
+                (r + 1, c)
+            }
+            Direction::Left => {
+                if c == 0 {
+                    return Err(BlobError::CannotMove("column already 0".into()));
+                }
+                (r, c - 1)
+            }
+            Direction::Right => {
+                if c + 1 >= self.map[r].len() {
+                    return Err(BlobError::CannotMove("already at right edge".into()));
+                }
+                (r, c + 1)
+            }
+        };
+        // Capture post-move snapshot via event recorder.
+        let mut next_map = self.map.clone();
+        let mut score = self.score;
+        let mut player_dead = self.player_dead;
+        let mut level_complete = self.current_level_completed;
+
+        // Simulate on temps then record once.
+        next_map[r][c] = tile::VISITED;
+        match next_map[nr][nc] {
+            tile::HOLE => next_map[nr][nc] = tile::DEAD_BY_HOLE,
+            tile::VISITED => next_map[nr][nc] = tile::DEAD_BY_SUICIDE,
+            tile::UNVISITED | tile::PLAYER => {
+                score += 1;
+                next_map[nr][nc] = tile::PLAYER;
+            }
+            _ => next_map[nr][nc] = tile::DEAD_BY_SUICIDE,
+        }
+        for row in &next_map {
+            if row.contains(&tile::DEAD_BY_HOLE) || row.contains(&tile::DEAD_BY_SUICIDE) {
+                player_dead = true;
+                level_complete = false;
+                break;
+            }
+        }
+        if !player_dead {
+            let any_u = next_map.iter().any(|row| row.contains(&tile::UNVISITED));
+            level_complete = !any_u;
+        }
+
+        self.record_moved(
+            score,
+            player_dead,
+            level_complete,
+            next_map,
+            direction.as_str().to_string(),
+        )?;
+        Ok(())
+    }
+
+    #[event("blob.moved")]
+    fn record_moved(
+        &mut self,
+        score: i64,
+        player_dead: bool,
+        current_level_completed: bool,
+        map: Vec<Vec<u8>>,
+        _direction: String,
+    ) {
+        self.score = score;
+        self.player_dead = player_dead;
+        self.current_level_completed = current_level_completed;
+        self.map = map;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::levels::{demo_map, is_hamiltonian_passable};
+
+    fn game_with_map(map: Vec<Vec<u8>>) -> BlobGame {
+        let mut g = BlobGame::default();
+        g.initialize("g1", "alice").unwrap();
+        g.start_level("alice", map).unwrap();
+        g
+    }
+
+    #[test]
+    fn initialize_and_start_level() {
+        let mut g = BlobGame::default();
+        g.initialize("g1", "alice").unwrap();
+        assert!(g.current_level_completed);
+        assert_eq!(g.current_level, 0);
+        g.start_level("alice", test_map_no_holes()).unwrap();
+        assert_eq!(g.current_level, 1);
+        assert!(!g.current_level_completed);
+        assert_eq!(g.player_pos().unwrap(), (0, 0));
+    }
+
+    #[test]
+    fn start_level_requires_complete() {
+        let mut g = game_with_map(test_map_no_holes());
+        let err = g.start_level("alice", test_map_no_holes()).unwrap_err();
+        assert_eq!(err, BlobError::LevelNotComplete);
+    }
+
+    #[test]
+    fn move_scores_unvisited() {
+        let mut g = game_with_map(test_map_no_holes());
+        g.move_dir("alice", Direction::Right).unwrap();
+        assert_eq!(g.score, 1);
+        assert_eq!(g.player_pos().unwrap(), (0, 1));
+        assert_eq!(g.map[0][0], tile::VISITED);
+    }
+
+    #[test]
+    fn die_on_hole() {
+        let mut g = game_with_map(test_map_with_hole());
+        g.move_dir("alice", Direction::Right).unwrap();
+        assert!(g.player_dead);
+        assert_eq!(g.map[0][1], tile::DEAD_BY_HOLE);
+        assert_eq!(g.score, 0);
+    }
+
+    #[test]
+    fn die_on_revisit() {
+        let mut g = game_with_map(test_map_no_holes());
+        g.move_dir("alice", Direction::Right).unwrap();
+        g.move_dir("alice", Direction::Left).unwrap();
+        assert!(g.player_dead);
+        assert_eq!(g.map[0][0], tile::DEAD_BY_SUICIDE);
+    }
+
+    #[test]
+    fn edge_move_rejected() {
+        let mut g = game_with_map(test_map_no_holes());
+        let err = g.move_dir("alice", Direction::Up).unwrap_err();
+        assert!(matches!(err, BlobError::CannotMove(_)));
+        assert_eq!(g.score, 0);
+        assert_eq!(g.player_pos().unwrap(), (0, 0));
+    }
+
+    #[test]
+    fn complete_level_when_no_unvisited() {
+        // 2×2: player + 3 unvisited
+        use tile::*;
+        let map = vec![
+            vec![PLAYER, UNVISITED],
+            vec![UNVISITED, UNVISITED],
+        ];
+        let mut g = game_with_map(map);
+        g.move_dir("alice", Direction::Right).unwrap();
+        g.move_dir("alice", Direction::Down).unwrap();
+        g.move_dir("alice", Direction::Left).unwrap();
+        assert!(g.current_level_completed);
+        assert!(!g.player_dead);
+        assert_eq!(g.score, 3);
+        assert_eq!(g.fact().status, "level_complete");
+    }
+
+    #[test]
+    fn not_owner_rejected() {
+        let mut g = game_with_map(test_map_no_holes());
+        assert_eq!(
+            g.move_dir("bob", Direction::Right).unwrap_err(),
+            BlobError::NotOwner
+        );
+    }
+
+
+    #[test]
+    fn complete_then_start_next_level() {
+        use tile::*;
+        let map = vec![vec![PLAYER, UNVISITED], vec![UNVISITED, UNVISITED]];
+        let mut g = BlobGame::default();
+        g.initialize("g1", "alice").unwrap();
+        g.start_level("alice", map).unwrap();
+        g.move_dir("alice", Direction::Right).unwrap();
+        g.move_dir("alice", Direction::Down).unwrap();
+        g.move_dir("alice", Direction::Left).unwrap();
+        assert!(g.current_level_completed);
+        assert_eq!(g.current_level, 1);
+        g.start_next_generated_level("alice").unwrap();
+        assert_eq!(g.current_level, 2);
+        assert!(!g.current_level_completed);
+        assert!(!g.map.is_empty());
+        // hydrate round-trip
+        let g2: BlobGame = distributed::hydrate(g.entity.clone()).unwrap();
+        assert_eq!(g2.current_level, 2);
+        assert!(!g2.current_level_completed);
+    }
+
+    #[test]
+    fn hydrate_preserves_level_complete_before_next() {
+        use tile::*;
+        let map = vec![vec![PLAYER, UNVISITED], vec![UNVISITED, UNVISITED]];
+        let mut g = BlobGame::default();
+        g.initialize("g1", "alice").unwrap();
+        g.start_level("alice", map).unwrap();
+        g.move_dir("alice", Direction::Right).unwrap();
+        g.move_dir("alice", Direction::Down).unwrap();
+        g.move_dir("alice", Direction::Left).unwrap();
+        assert!(g.current_level_completed);
+        let mut g2: BlobGame = distributed::hydrate(g.entity.clone()).unwrap();
+        assert!(g2.current_level_completed, "completed flag must survive hydrate");
+        g2.start_next_generated_level("alice").unwrap();
+        assert_eq!(g2.current_level, 2);
+    }
+
+    #[test]
+    fn demo_map_valid() {
+        validate_map(&demo_map()).unwrap();
+    }
+
+    #[test]
+    fn start_with_demo_uses_generated_passable_map() {
+        let mut g = BlobGame::default();
+        g.start_with_demo("g-rand", "alice").unwrap();
+        assert_eq!(g.map[0][0], tile::PLAYER);
+        assert!(is_hamiltonian_passable(&g.map));
+        assert!(g.map.len() >= 5);
+    }
+}
diff --git a/tests/e2e-ui/crates/blob-domain/src/models/blob_game_fact.rs b/tests/e2e-ui/crates/blob-domain/src/models/blob_game_fact.rs
new file mode 100644
index 00000000..33e4f801
--- /dev/null
+++ b/tests/e2e-ui/crates/blob-domain/src/models/blob_game_fact.rs
@@ -0,0 +1,23 @@
+use serde::{Deserialize, Serialize};
+
+use super::BlobGame;
+
+/// Full snapshot fact written on every blob event (projector upsert source).
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct BlobGameFact {
+    pub game_id: String,
+    pub owner_id: String,
+    pub score: i64,
+    pub player_dead: bool,
+    pub current_level: i64,
+    pub current_level_completed: bool,
+    /// JSON-encoded `number[][]` of tile ints.
+    pub map_json: String,
+    pub status: String,
+}
+
+impl BlobGameFact {
+    pub fn from_game(g: &BlobGame) -> Self {
+        g.fact()
+    }
+}
diff --git a/tests/e2e-ui/crates/blob-domain/src/models/direction.rs b/tests/e2e-ui/crates/blob-domain/src/models/direction.rs
new file mode 100644
index 00000000..c2f35d8c
--- /dev/null
+++ b/tests/e2e-ui/crates/blob-domain/src/models/direction.rs
@@ -0,0 +1,31 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Direction {
+    Up,
+    Down,
+    Left,
+    Right,
+}
+
+impl Direction {
+    pub fn parse(s: &str) -> Option<Self> {
+        match s.trim().to_ascii_lowercase().as_str() {
+            "up" => Some(Self::Up),
+            "down" => Some(Self::Down),
+            "left" => Some(Self::Left),
+            "right" => Some(Self::Right),
+            _ => None,
+        }
+    }
+
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Up => "up",
+            Self::Down => "down",
+            Self::Left => "left",
+            Self::Right => "right",
+        }
+    }
+}
diff --git a/tests/e2e-ui/crates/blob-domain/src/models/mod.rs b/tests/e2e-ui/crates/blob-domain/src/models/mod.rs
new file mode 100644
index 00000000..cedf497a
--- /dev/null
+++ b/tests/e2e-ui/crates/blob-domain/src/models/mod.rs
@@ -0,0 +1,12 @@
+//! Blob game domain models.
+
+mod blob_error;
+mod blob_game;
+mod blob_game_fact;
+mod direction;
+pub mod tile;
+
+pub use blob_error::BlobError;
+pub use blob_game::{test_map_no_holes, test_map_with_hole, BlobGame};
+pub use blob_game_fact::BlobGameFact;
+pub use direction::Direction;
diff --git a/tests/e2e-ui/crates/blob-domain/src/models/tile.rs b/tests/e2e-ui/crates/blob-domain/src/models/tile.rs
new file mode 100644
index 00000000..5534c1cb
--- /dev/null
+++ b/tests/e2e-ui/crates/blob-domain/src/models/tile.rs
@@ -0,0 +1,8 @@
+//! Canonical tile values (JS parity).
+
+pub const HOLE: u8 = 0;
+pub const UNVISITED: u8 = 1;
+pub const VISITED: u8 = 2;
+pub const DEAD_BY_SUICIDE: u8 = 3;
+pub const DEAD_BY_HOLE: u8 = 4;
+pub const PLAYER: u8 = 9;
diff --git a/tests/e2e-ui/crates/chat-domain/Cargo.toml b/tests/e2e-ui/crates/chat-domain/Cargo.toml
new file mode 100644
index 00000000..8fa4e97f
--- /dev/null
+++ b/tests/e2e-ui/crates/chat-domain/Cargo.toml
@@ -0,0 +1,14 @@
+[package]
+name = "chat-domain"
+version.workspace = true
+edition.workspace = true
+publish = false
+description = "ChatMessage aggregate for live chat (subscription demo)"
+
+[dependencies]
+distributed = { workspace = true }
+serde = { workspace = true }
+thiserror = { workspace = true }
+
+[dev-dependencies]
+serde_json = { workspace = true }
diff --git a/tests/e2e-ui/crates/chat-domain/src/lib.rs b/tests/e2e-ui/crates/chat-domain/src/lib.rs
new file mode 100644
index 00000000..d95b33d7
--- /dev/null
+++ b/tests/e2e-ui/crates/chat-domain/src/lib.rs
@@ -0,0 +1,5 @@
+//! Chat message aggregate — post to a room; author is the session user.
+
+pub mod models;
+
+pub use models::{ChatError, ChatMessage, ChatMessagePosted};
diff --git a/tests/e2e-ui/crates/chat-domain/src/models/chat_error.rs b/tests/e2e-ui/crates/chat-domain/src/models/chat_error.rs
new file mode 100644
index 00000000..a3e68c81
--- /dev/null
+++ b/tests/e2e-ui/crates/chat-domain/src/models/chat_error.rs
@@ -0,0 +1,17 @@
+use thiserror::Error;
+
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum ChatError {
+    #[error("message already exists")]
+    AlreadyExists,
+    #[error("empty message id")]
+    EmptyId,
+    #[error("empty author id")]
+    EmptyAuthor,
+    #[error("empty room id")]
+    EmptyRoom,
+    #[error("empty body")]
+    EmptyBody,
+    #[error(transparent)]
+    Event(#[from] distributed::EventRecordError),
+}
diff --git a/tests/e2e-ui/crates/chat-domain/src/models/chat_message.rs b/tests/e2e-ui/crates/chat-domain/src/models/chat_message.rs
new file mode 100644
index 00000000..2ab6ae2e
--- /dev/null
+++ b/tests/e2e-ui/crates/chat-domain/src/models/chat_message.rs
@@ -0,0 +1,105 @@
+use distributed::{sourced, Entity};
+use serde::{Deserialize, Serialize};
+
+use super::ChatError;
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct ChatMessage {
+    #[serde(skip, default)]
+    pub entity: Entity,
+    pub message_id: String,
+    pub room_id: String,
+    pub author_id: String,
+    pub body: String,
+    /// RFC3339 timestamp (string for portable projections / SQLite text).
+    pub created_at: String,
+}
+
+impl ChatMessage {
+    pub fn is_posted(&self) -> bool {
+        !self.message_id.is_empty()
+    }
+}
+
+#[sourced(entity, events = "ChatMessageEvent", aggregate_type = "chat_message")]
+impl ChatMessage {
+    pub fn post(
+        &mut self,
+        message_id: impl Into<String>,
+        room_id: impl Into<String>,
+        author_id: impl Into<String>,
+        body: impl Into<String>,
+        created_at: impl Into<String>,
+    ) -> Result<(), ChatError> {
+        if self.is_posted() {
+            return Err(ChatError::AlreadyExists);
+        }
+        let message_id = message_id.into();
+        let room_id = room_id.into();
+        let author_id = author_id.into();
+        let body = body.into();
+        let created_at = created_at.into();
+        if message_id.trim().is_empty() {
+            return Err(ChatError::EmptyId);
+        }
+        if room_id.trim().is_empty() {
+            return Err(ChatError::EmptyRoom);
+        }
+        if author_id.trim().is_empty() {
+            return Err(ChatError::EmptyAuthor);
+        }
+        let body = body.trim();
+        if body.is_empty() {
+            return Err(ChatError::EmptyBody);
+        }
+        self.record_posted(
+            message_id,
+            room_id,
+            author_id,
+            body.to_string(),
+            created_at,
+        )?;
+        Ok(())
+    }
+
+    #[event("chat_message.posted")]
+    fn record_posted(
+        &mut self,
+        message_id: String,
+        room_id: String,
+        author_id: String,
+        body: String,
+        created_at: String,
+    ) {
+        self.entity.set_id(&message_id);
+        self.message_id = message_id;
+        self.room_id = room_id;
+        self.author_id = author_id;
+        self.body = body;
+        self.created_at = created_at;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn post_sets_fields() {
+        let mut m = ChatMessage::default();
+        m.post("m1", "lobby", "alice", "hello", "2026-01-01T00:00:00Z")
+            .unwrap();
+        assert!(m.is_posted());
+        assert_eq!(m.body, "hello");
+        assert_eq!(m.author_id, "alice");
+    }
+
+    #[test]
+    fn rejects_empty_body() {
+        let mut m = ChatMessage::default();
+        assert_eq!(
+            m.post("m1", "lobby", "alice", "  ", "t").unwrap_err(),
+            ChatError::EmptyBody
+        );
+    }
+}
diff --git a/tests/e2e-ui/crates/chat-domain/src/models/chat_message_posted.rs b/tests/e2e-ui/crates/chat-domain/src/models/chat_message_posted.rs
new file mode 100644
index 00000000..fcac0bc9
--- /dev/null
+++ b/tests/e2e-ui/crates/chat-domain/src/models/chat_message_posted.rs
@@ -0,0 +1,24 @@
+use serde::{Deserialize, Serialize};
+
+use super::ChatMessage;
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ChatMessagePosted {
+    pub message_id: String,
+    pub room_id: String,
+    pub author_id: String,
+    pub body: String,
+    pub created_at: String,
+}
+
+impl ChatMessagePosted {
+    pub fn from_message(m: &ChatMessage) -> Self {
+        Self {
+            message_id: m.message_id.clone(),
+            room_id: m.room_id.clone(),
+            author_id: m.author_id.clone(),
+            body: m.body.clone(),
+            created_at: m.created_at.clone(),
+        }
+    }
+}
diff --git a/tests/e2e-ui/crates/chat-domain/src/models/mod.rs b/tests/e2e-ui/crates/chat-domain/src/models/mod.rs
new file mode 100644
index 00000000..6f70110f
--- /dev/null
+++ b/tests/e2e-ui/crates/chat-domain/src/models/mod.rs
@@ -0,0 +1,9 @@
+//! Chat domain models.
+
+mod chat_error;
+mod chat_message;
+mod chat_message_posted;
+
+pub use chat_error::ChatError;
+pub use chat_message::ChatMessage;
+pub use chat_message_posted::ChatMessagePosted;
diff --git a/tests/e2e-ui/crates/readmodels/Cargo.toml b/tests/e2e-ui/crates/readmodels/Cargo.toml
new file mode 100644
index 00000000..33ecdad7
--- /dev/null
+++ b/tests/e2e-ui/crates/readmodels/Cargo.toml
@@ -0,0 +1,14 @@
+[package]
+name = "e2e-readmodels"
+version.workspace = true
+edition.workspace = true
+publish = false
+description = "Todo read models (TodoView) + project manifest"
+
+[dependencies]
+distributed = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+todo-domain = { path = "../todo-domain" }
+chat-domain = { path = "../chat-domain" }
+blob-domain = { path = "../blob-domain" }
diff --git a/tests/e2e-ui/crates/readmodels/src/lib.rs b/tests/e2e-ui/crates/readmodels/src/lib.rs
new file mode 100644
index 00000000..076d18f6
--- /dev/null
+++ b/tests/e2e-ui/crates/readmodels/src/lib.rs
@@ -0,0 +1,55 @@
+//! Read models for the e2e-ui fixture (todos + chat + blob games + auth users).
+//! Projected only from domain / provider events (never from commands).
+
+pub mod models;
+
+pub use models::{
+    map_blob_fact, map_chat_posted, map_todo_fact, map_zitadel_user_status,
+    map_zitadel_user_upsert, AuthUserView, BlobGameView, ChatMessageView, TodoView, ZitadelEmail,
+    ZitadelUserPayload,
+};
+
+pub fn distributed_manifest() -> distributed::DistributedProjectManifest {
+    use distributed::RelationalReadModel;
+    distributed::DistributedProjectManifest::new("e2e-ui")
+        .table_schema(TodoView::schema().clone())
+        .table_schema(ChatMessageView::schema().clone())
+        .table_schema(BlobGameView::schema().clone())
+        .table_schema(AuthUserView::schema().clone())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use blob_domain::{demo_map, BlobGame, BlobGameFact};
+
+    #[test]
+    fn projector_map_reflects_post_move_fact() {
+        let mut g = BlobGame::default();
+        g.start_with_demo("g1", "alice").unwrap();
+        let before = map_blob_fact(&BlobGameFact::from_game(&g));
+        assert_eq!(before.score, 0);
+        assert!(!before.player_dead);
+
+        g.move_dir("alice", blob_domain::Direction::Right).unwrap();
+        let after = map_blob_fact(&BlobGameFact::from_game(&g));
+        assert_eq!(after.score, 1);
+        assert_eq!(after.game_id, "g1");
+        assert_eq!(after.owner_id, "alice");
+        assert!(after.map_json.contains("2")); // visited tile
+                                               // Map JSON must differ from pre-move
+        assert_ne!(before.map_json, after.map_json);
+        // Demo map player moved off origin
+        let map: Vec<Vec<u8>> = serde_json::from_str(&after.map_json).unwrap();
+        assert_eq!(map[0][0], 2); // visited
+        assert_eq!(map[0][1], 9); // player
+    }
+
+    #[test]
+    fn demo_map_json_roundtrip() {
+        let m = demo_map();
+        let s = serde_json::to_string(&m).unwrap();
+        let back: Vec<Vec<u8>> = serde_json::from_str(&s).unwrap();
+        assert_eq!(m, back);
+    }
+}
diff --git a/tests/e2e-ui/crates/readmodels/src/models/auth_user_view.rs b/tests/e2e-ui/crates/readmodels/src/models/auth_user_view.rs
new file mode 100644
index 00000000..848e0bc2
--- /dev/null
+++ b/tests/e2e-ui/crates/readmodels/src/models/auth_user_view.rs
@@ -0,0 +1,141 @@
+//! Auth users imported from Zitadel Action ingress (provider messages → projector).
+
+use distributed::ReadModel;
+use serde::{Deserialize, Serialize};
+
+use super::{BlobGameView, ChatMessageView};
+
+/// Imported IdP user. PK: `user_id` (= Zitadel subject / OIDC `sub` / session `x-user-id`).
+///
+/// Populated only from the Zitadel ingestor projector — never from commands.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, ReadModel)]
+#[table("auth_users")]
+pub struct AuthUserView {
+    #[id("user_id")]
+    pub user_id: String,
+    pub email: String,
+    pub display_name: String,
+    /// `human` | `machine`
+    pub user_kind: String,
+    /// `pending` | `approved` | `rejected`
+    pub approval_status: String,
+    /// `active` | `deactivated`
+    pub status: String,
+    pub updated_at: String,
+    #[readmodel(has_many = "ChatMessageView", foreign_key = "author_id")]
+    pub chat_messages: Vec<ChatMessageView>,
+    #[readmodel(has_many = "BlobGameView", foreign_key = "owner_id")]
+    pub blob_games: Vec<BlobGameView>,
+}
+
+/// Provider envelope published by `zitadel.ingress.v1` (fixture + Action shape).
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ZitadelUserPayload {
+    pub schema_version: u32,
+    pub source: String,
+    pub delivery_id: String,
+    pub provider: String,
+    pub provider_subject: String,
+    pub user_kind: String,
+    pub emails: Vec<ZitadelEmail>,
+    pub display_name: Option<String>,
+    pub approval_status: String,
+    pub ingested_at: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ZitadelEmail {
+    pub address: String,
+    pub primary: bool,
+    pub verified: bool,
+}
+
+/// Map a created/updated provider payload into an upsert row.
+pub fn map_zitadel_user_upsert(event_name: &str, p: &ZitadelUserPayload) -> AuthUserView {
+    let email = p
+        .emails
+        .iter()
+        .find(|e| e.primary)
+        .or_else(|| p.emails.first())
+        .map(|e| e.address.clone())
+        .unwrap_or_default();
+    let display_name = p
+        .display_name
+        .clone()
+        .filter(|s| !s.trim().is_empty())
+        .unwrap_or_else(|| {
+            if email.is_empty() {
+                p.provider_subject.clone()
+            } else {
+                email.clone()
+            }
+        });
+    let status = if event_name.contains("deactivated") {
+        "deactivated".into()
+    } else {
+        "active".into()
+    };
+    AuthUserView {
+        user_id: p.provider_subject.clone(),
+        email,
+        display_name,
+        user_kind: p.user_kind.clone(),
+        approval_status: p.approval_status.clone(),
+        status,
+        updated_at: p.ingested_at.clone(),
+        chat_messages: Vec::new(),
+        blob_games: Vec::new(),
+    }
+}
+
+/// Status-only patch for deactivate / reactivate when no profile fields are present.
+pub fn map_zitadel_user_status(event_name: &str, p: &ZitadelUserPayload) -> AuthUserView {
+    let mut row = map_zitadel_user_upsert(event_name, p);
+    if event_name.contains("reactivated") {
+        row.status = "active".into();
+    } else if event_name.contains("deactivated") {
+        row.status = "deactivated".into();
+    }
+    row
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn payload() -> ZitadelUserPayload {
+        ZitadelUserPayload {
+            schema_version: 1,
+            source: "zitadel".into(),
+            delivery_id: "d1".into(),
+            provider: "zitadel".into(),
+            provider_subject: "user-99".into(),
+            user_kind: "human".into(),
+            emails: vec![ZitadelEmail {
+                address: "ada@example.com".into(),
+                primary: true,
+                verified: true,
+            }],
+            display_name: Some("Ada".into()),
+            approval_status: "pending".into(),
+            ingested_at: "2026-01-01T00:00:00Z".into(),
+        }
+    }
+
+    #[test]
+    fn created_maps_active_user() {
+        let row = map_zitadel_user_upsert("zitadel.user.human.created.v1", &payload());
+        assert_eq!(row.user_id, "user-99");
+        assert_eq!(row.email, "ada@example.com");
+        assert_eq!(row.display_name, "Ada");
+        assert_eq!(row.status, "active");
+        assert_eq!(row.approval_status, "pending");
+    }
+
+    #[test]
+    fn deactivated_sets_status() {
+        let row = map_zitadel_user_status("zitadel.user.human.deactivated.v1", &payload());
+        assert_eq!(row.status, "deactivated");
+        assert_eq!(row.user_id, "user-99");
+    }
+}
diff --git a/tests/e2e-ui/crates/readmodels/src/models/blob_game_view.rs b/tests/e2e-ui/crates/readmodels/src/models/blob_game_view.rs
new file mode 100644
index 00000000..2f1343fd
--- /dev/null
+++ b/tests/e2e-ui/crates/readmodels/src/models/blob_game_view.rs
@@ -0,0 +1,72 @@
+use blob_domain::BlobGameFact;
+use distributed::graphql::{GraphqlOutputType, GraphqlTypeDef, GraphqlTypeField};
+use distributed::ReadModel;
+use serde::{Deserialize, Serialize};
+
+use super::AuthUserView;
+
+/// Blob game row. PK: `game_id`. Isolation key: `owner_id`.
+/// `map_json` is the projected grid (tile ints); updated only from domain events.
+///
+/// `owner` is a GraphQL join onto imported [`AuthUserView`] (`owner_id` = `user_id`).
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, ReadModel)]
+#[table("blob_games")]
+pub struct BlobGameView {
+    #[id("game_id")]
+    pub game_id: String,
+    pub owner_id: String,
+    pub score: i64,
+    pub player_dead: bool,
+    pub current_level: i64,
+    pub current_level_completed: bool,
+    pub map_json: String,
+    /// `active` | `dead` | `level_complete`
+    pub status: String,
+    #[readmodel(belongs_to = "AuthUserView", foreign_key = "owner_id")]
+    pub owner: Option<AuthUserView>,
+}
+
+impl GraphqlOutputType for BlobGameView {
+    fn graphql_type() -> GraphqlTypeDef {
+        let scalar = |name: &str, type_name: &str| GraphqlTypeField {
+            name: name.into(),
+            type_name: type_name.into(),
+            nullable: false,
+            list: false,
+            item_nullable: false,
+            nested: None,
+        };
+        GraphqlTypeDef::new(
+            // `Projected<BlobGameView>` is a direct replica write. Its output
+            // identity must be the retained model identity so the typed
+            // Service binder can prove command/result topology without a
+            // hand-authored alias.
+            "BlobGameView",
+            vec![
+                scalar("game_id", "String"),
+                scalar("owner_id", "String"),
+                scalar("score", "BigInt"),
+                scalar("player_dead", "Boolean"),
+                scalar("current_level", "BigInt"),
+                scalar("current_level_completed", "Boolean"),
+                scalar("map_json", "String"),
+                scalar("status", "String"),
+            ],
+        )
+        .with_type_id(std::any::TypeId::of::<Self>())
+    }
+}
+
+pub fn map_blob_fact(e: &BlobGameFact) -> BlobGameView {
+    BlobGameView {
+        game_id: e.game_id.clone(),
+        owner_id: e.owner_id.clone(),
+        score: e.score,
+        player_dead: e.player_dead,
+        current_level: e.current_level,
+        current_level_completed: e.current_level_completed,
+        map_json: e.map_json.clone(),
+        status: e.status.clone(),
+        owner: None,
+    }
+}
diff --git a/tests/e2e-ui/crates/readmodels/src/models/chat_message_view.rs b/tests/e2e-ui/crates/readmodels/src/models/chat_message_view.rs
new file mode 100644
index 00000000..f733f98d
--- /dev/null
+++ b/tests/e2e-ui/crates/readmodels/src/models/chat_message_view.rs
@@ -0,0 +1,32 @@
+use chat_domain::ChatMessagePosted;
+use distributed::ReadModel;
+use serde::{Deserialize, Serialize};
+
+use super::AuthUserView;
+
+/// Chat message row. PK: `message_id`. Live via GraphQL subscription on `chat_messages`.
+///
+/// `author` is a GraphQL join onto imported [`AuthUserView`] (`author_id` = `user_id`).
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, ReadModel)]
+#[table("chat_messages")]
+pub struct ChatMessageView {
+    #[id("message_id")]
+    pub message_id: String,
+    pub room_id: String,
+    pub author_id: String,
+    pub body: String,
+    pub created_at: String,
+    #[readmodel(belongs_to = "AuthUserView", foreign_key = "author_id")]
+    pub author: Option<AuthUserView>,
+}
+
+pub fn map_chat_posted(e: &ChatMessagePosted) -> ChatMessageView {
+    ChatMessageView {
+        message_id: e.message_id.clone(),
+        room_id: e.room_id.clone(),
+        author_id: e.author_id.clone(),
+        body: e.body.clone(),
+        created_at: e.created_at.clone(),
+        author: None,
+    }
+}
diff --git a/tests/e2e-ui/crates/readmodels/src/models/mod.rs b/tests/e2e-ui/crates/readmodels/src/models/mod.rs
new file mode 100644
index 00000000..07a8e258
--- /dev/null
+++ b/tests/e2e-ui/crates/readmodels/src/models/mod.rs
@@ -0,0 +1,14 @@
+//! Projected read-model views for e2e-ui.
+
+pub mod auth_user_view;
+pub mod blob_game_view;
+pub mod chat_message_view;
+pub mod todo_view;
+
+pub use auth_user_view::{
+    map_zitadel_user_status, map_zitadel_user_upsert, AuthUserView, ZitadelEmail,
+    ZitadelUserPayload,
+};
+pub use blob_game_view::{map_blob_fact, BlobGameView};
+pub use chat_message_view::{map_chat_posted, ChatMessageView};
+pub use todo_view::{map_todo_fact, TodoView};
diff --git a/tests/e2e-ui/crates/readmodels/src/models/todo_view.rs b/tests/e2e-ui/crates/readmodels/src/models/todo_view.rs
new file mode 100644
index 00000000..3e31b76a
--- /dev/null
+++ b/tests/e2e-ui/crates/readmodels/src/models/todo_view.rs
@@ -0,0 +1,24 @@
+use distributed::ReadModel;
+use serde::{Deserialize, Serialize};
+use todo_domain::TodoFact;
+
+/// Personal todo row. PK: `todo_id`. Isolation key: `owner_id`.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, ReadModel)]
+#[table("todos")]
+pub struct TodoView {
+    #[id("todo_id")]
+    pub todo_id: String,
+    pub owner_id: String,
+    pub title: String,
+    /// `open` | `completed` | `archived`
+    pub status: String,
+}
+
+pub fn map_todo_fact(e: &TodoFact) -> TodoView {
+    TodoView {
+        todo_id: e.todo_id.clone(),
+        owner_id: e.owner_id.clone(),
+        title: e.title.clone(),
+        status: e.status.clone(),
+    }
+}
diff --git a/tests/e2e-ui/crates/runner/Cargo.toml b/tests/e2e-ui/crates/runner/Cargo.toml
new file mode 100644
index 00000000..171c99cf
--- /dev/null
+++ b/tests/e2e-ui/crates/runner/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "e2e-runner"
+version.workspace = true
+edition.workspace = true
+publish = false
+description = "Thin runner: SQLite + SqliteBus + HTTP + GraphQL"
+
+[[bin]]
+name = "e2e-ui"
+path = "src/main.rs"
+
+[dependencies]
+distributed = { workspace = true }
+e2e-service = { path = "../service" }
+tokio = { workspace = true }
diff --git a/tests/e2e-ui/crates/runner/src/main.rs b/tests/e2e-ui/crates/runner/src/main.rs
new file mode 100644
index 00000000..50d2abb0
--- /dev/null
+++ b/tests/e2e-ui/crates/runner/src/main.rs
@@ -0,0 +1,203 @@
+//! e2e-ui runner — SQLite (offline) or Postgres (compose stack).
+//!
+//! Env:
+//! - `DATABASE_URL` — `sqlite:…` (default) or `postgres://…`
+//! - `BIND` (default `127.0.0.1:8791`)
+//! - `OIDC_ISSUER` / `OIDC_AUDIENCE` / `OIDC_JWKS_URI` → OidcBearer; else DevHeaders
+//! - `ZITADEL_SERVICE_USER_TOKEN` + `OIDC_ISSUER`/`ZITADEL_API_URL` → periodic user scrape
+//! - `ZITADEL_SCRAPE_INTERVAL_SECS` (default 60; `0` = no background loop)
+
+use std::env;
+use std::sync::Arc;
+use std::time::Duration;
+
+use distributed::bus::{PostgresBus, RunOptions, SqliteBus};
+use distributed::{
+    BusPublisher, OutboxDispatcher, PostgresLockManager, PostgresRepository, SqliteLockManager,
+    SqliteRepository,
+};
+use e2e_service::{
+    build_graphql_engine, build_service, distributed_manifest, identity_from_env, serve_with_oidc,
+    spawn_scrape_loop, ZitadelScrapeConfig,
+};
+
+const BUS_GROUP: &str = "e2e-ui";
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    let database_url =
+        env::var("DATABASE_URL").unwrap_or_else(|_| "sqlite:./e2e-ui.db?mode=rwc".into());
+    let bind = env::var("BIND").unwrap_or_else(|_| "127.0.0.1:8791".into());
+    let identity = identity_from_env();
+
+    if database_url.starts_with("postgres://") || database_url.starts_with("postgresql://") {
+        run_postgres(&database_url, &bind, identity).await
+    } else {
+        run_sqlite(&database_url, &bind, identity).await
+    }
+}
+
+async fn run_sqlite(
+    database_url: &str,
+    bind: &str,
+    identity: distributed::graphql::IdentityConfig,
+) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    let repo = SqliteRepository::connect_and_migrate(database_url).await?;
+    let registry = distributed_manifest()
+        .table_registry()
+        .map_err(|e| format!("manifest: {e}"))?;
+    repo.bootstrap_table_schema_for_dev(&registry).await?;
+    let locks = SqliteLockManager::new(repo.pool().clone());
+
+    let bus = SqliteBus::new(repo.pool().clone()).group(BUS_GROUP);
+    bus.ensure_tables().await?;
+
+    let change_rx = repo.read_model_changes();
+    let service = build_service(repo.clone(), locks.clone(), repo.clone())
+        .with_bus(SqliteBus::new(repo.pool().clone()).group(BUS_GROUP));
+    let gql = build_graphql_engine(&repo, &service, identity.clone(), Some(change_rx))?;
+    let http_service = Arc::new(service.try_with_graphql(gql)?);
+
+    spawn_outbox_sqlite(repo.clone());
+    spawn_consumer_sqlite(repo.clone(), locks);
+    spawn_zitadel_scrape(repo.clone());
+
+    eprintln!("e2e-ui (sqlite) listening on http://{bind}");
+    serve_with_oidc(http_service, identity, bind).await?;
+    Ok(())
+}
+
+async fn run_postgres(
+    database_url: &str,
+    bind: &str,
+    identity: distributed::graphql::IdentityConfig,
+) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    let repo = PostgresRepository::connect_and_migrate(database_url).await?;
+    let registry = distributed_manifest()
+        .table_registry()
+        .map_err(|e| format!("manifest: {e}"))?;
+    repo.bootstrap_table_schema_for_dev(&registry).await?;
+    let locks = PostgresLockManager::new(repo.pool().clone());
+
+    let bus = PostgresBus::new(repo.pool().clone()).group(BUS_GROUP);
+    bus.ensure_tables().await?;
+
+    let change_rx = repo.read_model_changes();
+    let service = build_service(repo.clone(), locks.clone(), repo.clone())
+        .with_bus(PostgresBus::new(repo.pool().clone()).group(BUS_GROUP));
+    let gql = build_graphql_engine(&repo, &service, identity.clone(), Some(change_rx))?;
+    let http_service = Arc::new(service.try_with_graphql(gql)?);
+
+    spawn_outbox_postgres(repo.clone());
+    spawn_consumer_postgres(repo.clone(), locks);
+    spawn_zitadel_scrape(repo.clone());
+
+    eprintln!("e2e-ui (postgres) listening on http://{bind}");
+    serve_with_oidc(http_service, identity, bind).await?;
+    Ok(())
+}
+
+fn spawn_zitadel_scrape<R>(repo: R)
+where
+    R: distributed::TransactionalCommit + Clone + Send + Sync + 'static,
+{
+    match ZitadelScrapeConfig::from_env() {
+        Some(cfg) if cfg.background_enabled() || cfg.on_start => {
+            eprintln!(
+                "zitadel scrape: enabled (api={}, interval={}s, on_start={})",
+                cfg.api_base,
+                cfg.interval.as_secs(),
+                cfg.on_start
+            );
+            spawn_scrape_loop(repo, cfg);
+        }
+        Some(_) => {
+            eprintln!("zitadel scrape: credentials present, background off (interval=0); use POST /zitadel.scrape.v1");
+        }
+        None => {
+            eprintln!(
+                "zitadel scrape: disabled (set ZITADEL_SERVICE_USER_TOKEN + OIDC_ISSUER/ZITADEL_API_URL)"
+            );
+        }
+    }
+}
+
+fn spawn_outbox_sqlite(repo: SqliteRepository) {
+    tokio::spawn(async move {
+        let bus = Arc::new(SqliteBus::new(repo.pool().clone()).group(BUS_GROUP));
+        let dispatcher = OutboxDispatcher::new(
+            repo.outbox_store(),
+            BusPublisher::new(bus),
+            format!("outbox:{}", std::process::id()),
+            Duration::from_secs(30),
+            5,
+        )
+        .with_service("e2e-ui");
+        loop {
+            match dispatcher.dispatch_batch(32).await {
+                Ok(o) if o.published > 0 || o.claimed > 0 => {}
+                Ok(_) => tokio::time::sleep(Duration::from_millis(25)).await,
+                Err(e) => {
+                    eprintln!("outbox: {e}");
+                    tokio::time::sleep(Duration::from_millis(100)).await;
+                }
+            }
+        }
+    });
+}
+
+fn spawn_consumer_sqlite(repo: SqliteRepository, locks: SqliteLockManager) {
+    tokio::spawn(async move {
+        loop {
+            let bus = SqliteBus::new(repo.pool().clone()).group(BUS_GROUP);
+            let service = build_service(repo.clone(), locks.clone(), repo.clone()).with_bus(bus);
+            match service.run(RunOptions::idempotent()).await {
+                Ok(()) => tokio::time::sleep(Duration::from_millis(25)).await,
+                Err(e) => {
+                    eprintln!("consumer: {e}");
+                    tokio::time::sleep(Duration::from_millis(100)).await;
+                }
+            }
+        }
+    });
+}
+
+fn spawn_outbox_postgres(repo: PostgresRepository) {
+    tokio::spawn(async move {
+        let bus = Arc::new(PostgresBus::new(repo.pool().clone()).group(BUS_GROUP));
+        let dispatcher = OutboxDispatcher::new(
+            repo.outbox_store(),
+            BusPublisher::new(bus),
+            format!("outbox:{}", std::process::id()),
+            Duration::from_secs(30),
+            5,
+        )
+        .with_service("e2e-ui");
+        loop {
+            match dispatcher.dispatch_batch(32).await {
+                Ok(o) if o.published > 0 || o.claimed > 0 => {}
+                Ok(_) => tokio::time::sleep(Duration::from_millis(25)).await,
+                Err(e) => {
+                    eprintln!("outbox: {e}");
+                    tokio::time::sleep(Duration::from_millis(100)).await;
+                }
+            }
+        }
+    });
+}
+
+fn spawn_consumer_postgres(repo: PostgresRepository, locks: PostgresLockManager) {
+    tokio::spawn(async move {
+        loop {
+            let bus = PostgresBus::new(repo.pool().clone()).group(BUS_GROUP);
+            let service = build_service(repo.clone(), locks.clone(), repo.clone()).with_bus(bus);
+            match service.run(RunOptions::idempotent()).await {
+                Ok(()) => tokio::time::sleep(Duration::from_millis(25)).await,
+                Err(e) => {
+                    eprintln!("consumer: {e}");
+                    tokio::time::sleep(Duration::from_millis(100)).await;
+                }
+            }
+        }
+    });
+}
diff --git a/tests/e2e-ui/crates/service/Cargo.toml b/tests/e2e-ui/crates/service/Cargo.toml
new file mode 100644
index 00000000..2231c3f0
--- /dev/null
+++ b/tests/e2e-ui/crates/service/Cargo.toml
@@ -0,0 +1,21 @@
+[package]
+name = "e2e-service"
+version.workspace = true
+edition.workspace = true
+publish = false
+description = "Todo service library: commands, projectors, GraphQL"
+
+[dependencies]
+distributed = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+tokio = { workspace = true }
+sqlx = { workspace = true }
+axum = { workspace = true }
+reqwest = { workspace = true }
+tower = "0.5"
+futures-util = "0.3"
+todo-domain = { path = "../todo-domain" }
+chat-domain = { path = "../chat-domain" }
+blob-domain = { path = "../blob-domain" }
+e2e-readmodels = { path = "../readmodels" }
diff --git a/tests/e2e-ui/crates/service/src/bounds.rs b/tests/e2e-ui/crates/service/src/bounds.rs
new file mode 100644
index 00000000..dbaf42fe
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/bounds.rs
@@ -0,0 +1,40 @@
+//! Trait aliases for generic handler storage parameters.
+
+use distributed::microsvc::{CausalProjectionStore, CausalRepositoryBackend};
+use distributed::{
+    GetStream, LockManager, ReadModelWritePlanStore, RelationalReadModelQueryStore,
+    TransactionalCommit,
+};
+
+pub trait EventStore:
+    CausalRepositoryBackend + GetStream + TransactionalCommit + Clone + Send + Sync + 'static
+{
+}
+impl<T> EventStore for T where
+    T: CausalRepositoryBackend + GetStream + TransactionalCommit + Clone + Send + Sync + 'static
+{
+}
+
+pub trait Locks: LockManager + Clone + 'static {}
+impl<T> Locks for T where T: LockManager + Clone + 'static {}
+
+pub trait ReadStore:
+    CausalProjectionStore
+    + ReadModelWritePlanStore
+    + RelationalReadModelQueryStore
+    + Clone
+    + Send
+    + Sync
+    + 'static
+{
+}
+impl<T> ReadStore for T where
+    T: CausalProjectionStore
+        + ReadModelWritePlanStore
+        + RelationalReadModelQueryStore
+        + Clone
+        + Send
+        + Sync
+        + 'static
+{
+}
diff --git a/tests/e2e-ui/crates/service/src/deps.rs b/tests/e2e-ui/crates/service/src/deps.rs
new file mode 100644
index 00000000..64beeedc
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/deps.rs
@@ -0,0 +1,12 @@
+use chat_domain::ChatMessage;
+use distributed::microsvc::RepoReadModelDependencies;
+use distributed::{AggregateRepository, QueuedRepository};
+
+pub type QueuedStore<R, L> = QueuedRepository<R, L>;
+
+pub type ChatRepo<R, L> = AggregateRepository<QueuedStore<R, L>, ChatMessage>;
+pub type ChatDeps<R, L, S> = RepoReadModelDependencies<ChatRepo<R, L>, S>;
+
+/// Zitadel ingress + auth_users projector share the chat aggregate repo for outbox/leaf access
+/// (ingestor is leaf-only; no chat stream is written on ingress).
+pub type AuthDeps<R, L, S> = ChatDeps<R, L, S>;
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/archive.rs b/tests/e2e-ui/crates/service/src/handlers/commands/archive.rs
new file mode 100644
index 00000000..fecf68d2
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/archive.rs
@@ -0,0 +1,34 @@
+//! Command: `todo.archive` — owner-only (aggregate enforces).
+
+use distributed::graphql::{Fact, PreparedCommand};
+use distributed::microsvc::{CausalCommandContext, HandlerError};
+use serde::Deserialize;
+use todo_domain::Todo;
+
+use crate::handlers::commands::payloads::TodoStatusPayload;
+use crate::handlers::commands::todo_cmd::{load_todo, map_domain, stage_todo_event};
+
+pub const COMMAND: &str = "todo.archive";
+
+/// GraphQL output — same shape as complete/reopen (shared type).
+pub type TodoArchivePayload = TodoStatusPayload;
+
+#[derive(Debug, Deserialize, distributed::GraphqlInput)]
+pub struct TodoArchiveInput {
+    pub todo_id: String,
+}
+
+pub async fn handle(
+    ctx: &CausalCommandContext<'_, Todo>,
+    input: TodoArchiveInput,
+) -> Result<PreparedCommand<Fact<TodoArchivePayload>>, HandlerError> {
+    let owner = ctx.user_id()?.to_string();
+    let mut todo = load_todo(ctx, &input.todo_id).await?;
+    todo.archive(&owner).map_err(map_domain)?;
+    let fact = stage_todo_event(ctx, todo, "todo.archived")?;
+    PreparedCommand::<Fact<TodoArchivePayload>>::prepare(TodoArchivePayload {
+        todo_id: fact.todo_id,
+        status: fact.status,
+    })
+    .map_err(|error| HandlerError::Other(Box::new(error)))
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/blob_cmd.rs b/tests/e2e-ui/crates/service/src/handlers/commands/blob_cmd.rs
new file mode 100644
index 00000000..20e1dd48
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/blob_cmd.rs
@@ -0,0 +1,35 @@
+//! Shared load + causal staging path for blob game commands.
+//!
+//! The returned [`BlobGameView`] is staged through
+//! [`CausalCommandContext::projected`], so the aggregate, command ledger, and
+//! exact projected row commit atomically. The canonical game row has no
+//! asynchronous fact consumer or second writer.
+
+use blob_domain::{BlobGame, BlobGameFact};
+use distributed::microsvc::{AggregateCheckout, CausalCommandContext, HandlerError};
+
+use crate::handlers::util::rejected;
+
+pub async fn load_game(
+    ctx: &CausalCommandContext<'_, BlobGame>,
+    game_id: &str,
+) -> Result<AggregateCheckout<BlobGame>, HandlerError> {
+    ctx.load(game_id)
+        .await?
+        .ok_or_else(|| HandlerError::NotFound(game_id.to_string()))
+}
+
+/// Stage the aggregate for the framework-owned causal commit. The caller maps
+/// the returned snapshot into the direct projection.
+pub fn stage_blob(
+    ctx: &CausalCommandContext<'_, BlobGame>,
+    game: AggregateCheckout<BlobGame>,
+) -> Result<BlobGameFact, HandlerError> {
+    let fact = BlobGameFact::from_game(&game);
+    ctx.stage(game)?;
+    Ok(fact)
+}
+
+pub fn map_domain(err: impl std::fmt::Display) -> HandlerError {
+    rejected(err)
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/blob_move.rs b/tests/e2e-ui/crates/service/src/handlers/commands/blob_move.rs
new file mode 100644
index 00000000..5f6aa303
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/blob_move.rs
@@ -0,0 +1,36 @@
+//! Command: `blob.move` — direction up|down|left|right.
+
+use blob_domain::{BlobGame, Direction};
+use distributed::graphql::{PreparedCommand, Projected};
+use distributed::microsvc::{CausalCommandContext, HandlerError};
+use e2e_readmodels::{map_blob_fact, BlobGameView};
+use serde::Deserialize;
+
+use crate::handlers::commands::blob_cmd::{load_game, map_domain, stage_blob};
+
+pub const COMMAND: &str = "blob.move";
+
+#[derive(Debug, Deserialize, distributed::GraphqlInput)]
+pub struct BlobMoveInput {
+    pub game_id: String,
+    pub direction: String,
+}
+
+pub async fn handle(
+    ctx: &CausalCommandContext<'_, BlobGame>,
+    input: BlobMoveInput,
+) -> Result<PreparedCommand<Projected<BlobGameView>>, HandlerError> {
+    let owner = ctx.user_id()?.to_string();
+    let dir = Direction::parse(&input.direction).ok_or_else(|| {
+        HandlerError::Rejected(format!(
+            "invalid direction `{}` (use up|down|left|right)",
+            input.direction
+        ))
+    })?;
+
+    let mut game = load_game(ctx, &input.game_id).await?;
+    game.move_dir(&owner, dir).map_err(map_domain)?;
+
+    let fact = stage_blob(ctx, game)?;
+    ctx.projected(map_blob_fact(&fact))
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/blob_start.rs b/tests/e2e-ui/crates/service/src/handlers/commands/blob_start.rs
new file mode 100644
index 00000000..28e70f2e
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/blob_start.rs
@@ -0,0 +1,39 @@
+//! Command: `blob.start` — create game + demo level. Owner = session user.
+
+use blob_domain::BlobGame;
+use distributed::graphql::{PreparedCommand, Projected};
+use distributed::microsvc::{CausalCommandContext, HandlerError};
+use e2e_readmodels::{map_blob_fact, BlobGameView};
+use serde::Deserialize;
+
+use crate::handlers::commands::blob_cmd::{map_domain, stage_blob};
+
+pub const COMMAND: &str = "blob.start";
+
+#[derive(Debug, Deserialize, distributed::GraphqlInput)]
+pub struct BlobStartInput {
+    pub game_id: String,
+}
+
+pub type BlobGamePayload = BlobGameView;
+
+pub async fn handle(
+    ctx: &CausalCommandContext<'_, BlobGame>,
+    input: BlobStartInput,
+) -> Result<PreparedCommand<Projected<BlobGamePayload>>, HandlerError> {
+    let owner = ctx.user_id()?.to_string();
+
+    if ctx.load(&input.game_id).await?.is_some() {
+        return Err(HandlerError::Rejected(format!(
+            "game {} already exists",
+            input.game_id
+        )));
+    }
+
+    let mut game = ctx.create();
+    game.start_with_demo(&input.game_id, &owner)
+        .map_err(map_domain)?;
+
+    let fact = stage_blob(ctx, game)?;
+    ctx.projected(map_blob_fact(&fact))
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/blob_start_level.rs b/tests/e2e-ui/crates/service/src/handlers/commands/blob_start_level.rs
new file mode 100644
index 00000000..474dd8a1
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/blob_start_level.rs
@@ -0,0 +1,29 @@
+//! Command: `blob.start_level` — next level after complete (new generated map).
+
+use blob_domain::BlobGame;
+use distributed::graphql::{PreparedCommand, Projected};
+use distributed::microsvc::{CausalCommandContext, HandlerError};
+use e2e_readmodels::{map_blob_fact, BlobGameView};
+use serde::Deserialize;
+
+use crate::handlers::commands::blob_cmd::{load_game, map_domain, stage_blob};
+
+pub const COMMAND: &str = "blob.start_level";
+
+#[derive(Debug, Deserialize, distributed::GraphqlInput)]
+pub struct BlobStartLevelInput {
+    pub game_id: String,
+}
+
+pub async fn handle(
+    ctx: &CausalCommandContext<'_, BlobGame>,
+    input: BlobStartLevelInput,
+) -> Result<PreparedCommand<Projected<BlobGameView>>, HandlerError> {
+    let owner = ctx.user_id()?.to_string();
+    let mut game = load_game(ctx, &input.game_id).await?;
+    // Fresh passable layout each level (like original generateLevel)
+    game.start_next_generated_level(&owner)
+        .map_err(map_domain)?;
+    let fact = stage_blob(ctx, game)?;
+    ctx.projected(map_blob_fact(&fact))
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/chat_post.rs b/tests/e2e-ui/crates/service/src/handlers/commands/chat_post.rs
new file mode 100644
index 00000000..f7909467
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/chat_post.rs
@@ -0,0 +1,98 @@
+//! Command: `chat.post` — author is always the authenticated session user.
+
+use chat_domain::{ChatMessage, ChatMessagePosted};
+use distributed::graphql::{Fact, PreparedCommand};
+use distributed::microsvc::{CausalCommandContext, HandlerError};
+use distributed::OutboxMessage;
+use serde::{Deserialize, Serialize};
+
+use crate::handlers::util::rejected;
+
+pub const COMMAND: &str = "chat.post";
+
+#[derive(Debug, Deserialize, distributed::GraphqlInput)]
+pub struct ChatPostInput {
+    pub message_id: String,
+    pub body: String,
+    pub room_id: String,
+    /// Client-generated unix milliseconds used by the optimistic row and
+    /// accepted only when it is close to server time.
+    pub created_at: String,
+}
+
+#[derive(Debug, Serialize, distributed::GraphqlOutput)]
+pub struct ChatPostPayload {
+    pub message_id: String,
+    pub room_id: String,
+    pub author_id: String,
+    pub body: String,
+    pub created_at: String,
+}
+
+pub async fn handle(
+    ctx: &CausalCommandContext<'_, ChatMessage>,
+    input: ChatPostInput,
+) -> Result<PreparedCommand<Fact<ChatPostPayload>>, HandlerError> {
+    let author = ctx.user_id()?.to_string();
+    let created_at = canonical_near_unix_millis(&input.created_at)?;
+
+    if ctx.load(&input.message_id).await?.is_some() {
+        return Err(HandlerError::Rejected(format!(
+            "message {} already exists",
+            input.message_id
+        )));
+    }
+
+    let mut msg = ctx.create();
+    msg.post(
+        &input.message_id,
+        &input.room_id,
+        &author,
+        &input.body,
+        &created_at,
+    )
+    .map_err(rejected)?;
+
+    let fact = ChatMessagePosted::from_message(&msg);
+    let payload =
+        serde_json::to_vec(&fact).map_err(|error| HandlerError::Other(Box::new(error)))?;
+    let outbox = OutboxMessage::create(
+        format!(
+            "{}:chat_message.posted:{}",
+            msg.message_id,
+            msg.entity.version()
+        ),
+        "chat_message.posted",
+        payload,
+    )
+    .map_err(|e| HandlerError::Other(Box::new(e)))?;
+
+    ctx.stage_outbox(outbox)?;
+    ctx.stage(msg)?;
+
+    PreparedCommand::<Fact<ChatPostPayload>>::prepare(ChatPostPayload {
+        message_id: fact.message_id,
+        room_id: fact.room_id,
+        author_id: fact.author_id,
+        body: fact.body,
+        created_at: fact.created_at,
+    })
+    .map_err(|error| HandlerError::Other(Box::new(error)))
+}
+
+fn canonical_near_unix_millis(value: &str) -> Result<String, HandlerError> {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    let now = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis();
+    let millis = value
+        .parse::<u128>()
+        .map_err(|_| rejected("created_at must be canonical unix milliseconds"))?;
+    if millis.to_string() != value || millis.abs_diff(now) > 300_000 {
+        return Err(rejected(
+            "created_at must be canonical unix milliseconds within five minutes of server time",
+        ));
+    }
+    Ok(value.to_string())
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/complete.rs b/tests/e2e-ui/crates/service/src/handlers/commands/complete.rs
new file mode 100644
index 00000000..b2ddfb4f
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/complete.rs
@@ -0,0 +1,31 @@
+//! Command: `todo.complete` — owner-only (aggregate enforces).
+
+use distributed::graphql::{Fact, PreparedCommand};
+use distributed::microsvc::{CausalCommandContext, HandlerError};
+use serde::Deserialize;
+use todo_domain::Todo;
+
+use crate::handlers::commands::payloads::TodoStatusPayload;
+use crate::handlers::commands::todo_cmd::{load_todo, map_domain, stage_todo_event};
+
+pub const COMMAND: &str = "todo.complete";
+
+#[derive(Debug, Deserialize, distributed::GraphqlInput)]
+pub struct TodoCompleteInput {
+    pub todo_id: String,
+}
+
+pub async fn handle(
+    ctx: &CausalCommandContext<'_, Todo>,
+    input: TodoCompleteInput,
+) -> Result<PreparedCommand<Fact<TodoStatusPayload>>, HandlerError> {
+    let owner = ctx.user_id()?.to_string();
+    let mut todo = load_todo(ctx, &input.todo_id).await?;
+    todo.complete(&owner).map_err(map_domain)?;
+    let fact = stage_todo_event(ctx, todo, "todo.completed")?;
+    PreparedCommand::<Fact<TodoStatusPayload>>::prepare(TodoStatusPayload {
+        todo_id: fact.todo_id,
+        status: fact.status,
+    })
+    .map_err(|error| HandlerError::Other(Box::new(error)))
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/create.rs b/tests/e2e-ui/crates/service/src/handlers/commands/create.rs
new file mode 100644
index 00000000..81273c63
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/create.rs
@@ -0,0 +1,58 @@
+//! Command: `todo.create` — owner is always the authenticated session user.
+//!
+//! GraphQL: exposed as mutation field `todos_create` (roles: user, admin).
+//! Owner cannot be spoofed via input — only `require_user(session)` is written.
+
+use distributed::graphql::{Fact, PreparedCommand};
+use distributed::microsvc::{CausalCommandContext, HandlerError};
+use serde::{Deserialize, Serialize};
+use todo_domain::Todo;
+
+use crate::handlers::commands::todo_cmd::{map_domain, stage_todo_event};
+
+pub const COMMAND: &str = "todo.create";
+
+/// Mutation / command input — `owner_id` is never accepted from the client.
+#[derive(Debug, Deserialize, distributed::GraphqlInput)]
+pub struct TodoCreateInput {
+    pub todo_id: String,
+    pub title: String,
+}
+
+/// GraphQL mutation payload for `todos_create`.
+#[derive(Debug, Serialize, distributed::GraphqlOutput)]
+pub struct TodoCreatePayload {
+    pub todo_id: String,
+    pub owner_id: String,
+    pub title: String,
+    pub status: String,
+}
+
+pub async fn handle(
+    ctx: &CausalCommandContext<'_, Todo>,
+    input: TodoCreateInput,
+) -> Result<PreparedCommand<Fact<TodoCreatePayload>>, HandlerError> {
+    // Owner is always the authenticated principal — not client-supplied.
+    let owner = ctx.user_id()?.to_string();
+
+    if ctx.load(&input.todo_id).await?.is_some() {
+        return Err(HandlerError::Rejected(format!(
+            "todo {} already exists",
+            input.todo_id
+        )));
+    }
+
+    let mut todo = ctx.create();
+    todo.create(&input.todo_id, &owner, &input.title)
+        .map_err(map_domain)?;
+
+    let fact = stage_todo_event(ctx, todo, "todo.created")?;
+
+    PreparedCommand::<Fact<TodoCreatePayload>>::prepare(TodoCreatePayload {
+        todo_id: fact.todo_id,
+        owner_id: fact.owner_id,
+        title: fact.title,
+        status: fact.status,
+    })
+    .map_err(|error| HandlerError::Other(Box::new(error)))
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/force_archive.rs b/tests/e2e-ui/crates/service/src/handlers/commands/force_archive.rs
new file mode 100644
index 00000000..21d1a803
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/force_archive.rs
@@ -0,0 +1,52 @@
+//! Command: `todo.force_archive` — **admin-only** GraphQL mutation.
+//!
+//! Emits `todo.force_archived` (distinct from owner `todo.archived`) so audit
+//! trails can tell admin intervention from self-service archive. Projector
+//! still upserts the same read-model shape.
+
+use distributed::graphql::{Fact, PreparedCommand};
+use distributed::microsvc::{CausalCommandContext, HandlerError};
+use serde::{Deserialize, Serialize};
+use todo_domain::Todo;
+
+use crate::handlers::commands::todo_cmd::{load_todo, map_domain, stage_todo_event};
+
+pub const COMMAND: &str = "todo.force_archive";
+
+/// Outbox / projector event name — distinct from owner `todo.archived`.
+pub const FORCE_ARCHIVED_EVENT: &str = "todo.force_archived";
+
+#[derive(Debug, Deserialize, distributed::GraphqlInput)]
+pub struct TodoForceArchiveInput {
+    pub todo_id: String,
+}
+
+#[derive(Debug, Serialize, distributed::GraphqlOutput)]
+pub struct TodoForceArchivePayload {
+    pub todo_id: String,
+    pub owner_id: String,
+    pub status: String,
+    /// Session user id of the admin who forced the archive.
+    pub archived_by: String,
+}
+
+pub async fn handle(
+    ctx: &CausalCommandContext<'_, Todo>,
+    input: TodoForceArchiveInput,
+) -> Result<PreparedCommand<Fact<TodoForceArchivePayload>>, HandlerError> {
+    let admin = ctx.user_id()?.to_string();
+    let mut todo = load_todo(ctx, &input.todo_id).await?;
+
+    // Domain archive is owner-scoped; use the aggregate's real owner (not admin id).
+    let owner = todo.owner_id.clone();
+    todo.archive(&owner).map_err(map_domain)?;
+    let fact = stage_todo_event(ctx, todo, FORCE_ARCHIVED_EVENT)?;
+
+    PreparedCommand::<Fact<TodoForceArchivePayload>>::prepare(TodoForceArchivePayload {
+        todo_id: fact.todo_id,
+        owner_id: fact.owner_id,
+        status: fact.status,
+        archived_by: admin,
+    })
+    .map_err(|error| HandlerError::Other(Box::new(error)))
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/mod.rs b/tests/e2e-ui/crates/service/src/handlers/commands/mod.rs
new file mode 100644
index 00000000..5087dc26
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/mod.rs
@@ -0,0 +1,13 @@
+pub mod archive;
+pub mod blob_cmd;
+pub mod blob_move;
+pub mod blob_start;
+pub mod blob_start_level;
+pub mod chat_post;
+pub mod complete;
+pub mod create;
+pub mod force_archive;
+pub mod payloads;
+pub mod rename;
+pub mod reopen;
+pub mod todo_cmd;
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/payloads.rs b/tests/e2e-ui/crates/service/src/handlers/commands/payloads.rs
new file mode 100644
index 00000000..76698a17
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/payloads.rs
@@ -0,0 +1,10 @@
+//! Shared GraphQL command payload types for todo lifecycle mutations.
+
+use serde::Serialize;
+
+/// Common complete / archive / reopen GraphQL payload.
+#[derive(Debug, Serialize, distributed::GraphqlOutput)]
+pub struct TodoStatusPayload {
+    pub todo_id: String,
+    pub status: String,
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/rename.rs b/tests/e2e-ui/crates/service/src/handlers/commands/rename.rs
new file mode 100644
index 00000000..d42ea774
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/rename.rs
@@ -0,0 +1,39 @@
+//! Command: `todo.rename` — owner-only (aggregate enforces).
+
+use distributed::graphql::{Fact, PreparedCommand};
+use distributed::microsvc::{CausalCommandContext, HandlerError};
+use serde::{Deserialize, Serialize};
+use todo_domain::Todo;
+
+use crate::handlers::commands::todo_cmd::{load_todo, map_domain, stage_todo_event};
+
+pub const COMMAND: &str = "todo.rename";
+
+#[derive(Debug, Deserialize, distributed::GraphqlInput)]
+pub struct TodoRenameInput {
+    pub todo_id: String,
+    pub title: String,
+}
+
+#[derive(Debug, Serialize, distributed::GraphqlOutput)]
+pub struct TodoRenamePayload {
+    pub todo_id: String,
+    pub title: String,
+    pub status: String,
+}
+
+pub async fn handle(
+    ctx: &CausalCommandContext<'_, Todo>,
+    input: TodoRenameInput,
+) -> Result<PreparedCommand<Fact<TodoRenamePayload>>, HandlerError> {
+    let owner = ctx.user_id()?.to_string();
+    let mut todo = load_todo(ctx, &input.todo_id).await?;
+    todo.rename(&owner, &input.title).map_err(map_domain)?;
+    let fact = stage_todo_event(ctx, todo, "todo.renamed")?;
+    PreparedCommand::<Fact<TodoRenamePayload>>::prepare(TodoRenamePayload {
+        todo_id: fact.todo_id,
+        title: fact.title,
+        status: fact.status,
+    })
+    .map_err(|error| HandlerError::Other(Box::new(error)))
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/reopen.rs b/tests/e2e-ui/crates/service/src/handlers/commands/reopen.rs
new file mode 100644
index 00000000..9e245b1a
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/reopen.rs
@@ -0,0 +1,33 @@
+//! Command: `todo.reopen` — owner-only (aggregate enforces).
+
+use distributed::graphql::{Fact, PreparedCommand};
+use distributed::microsvc::{CausalCommandContext, HandlerError};
+use serde::Deserialize;
+use todo_domain::Todo;
+
+use crate::handlers::commands::payloads::TodoStatusPayload;
+use crate::handlers::commands::todo_cmd::{load_todo, map_domain, stage_todo_event};
+
+pub const COMMAND: &str = "todo.reopen";
+
+pub type TodoReopenPayload = TodoStatusPayload;
+
+#[derive(Debug, Deserialize, distributed::GraphqlInput)]
+pub struct TodoReopenInput {
+    pub todo_id: String,
+}
+
+pub async fn handle(
+    ctx: &CausalCommandContext<'_, Todo>,
+    input: TodoReopenInput,
+) -> Result<PreparedCommand<Fact<TodoReopenPayload>>, HandlerError> {
+    let owner = ctx.user_id()?.to_string();
+    let mut todo = load_todo(ctx, &input.todo_id).await?;
+    todo.reopen(&owner).map_err(map_domain)?;
+    let fact = stage_todo_event(ctx, todo, "todo.reopened")?;
+    PreparedCommand::<Fact<TodoReopenPayload>>::prepare(TodoReopenPayload {
+        todo_id: fact.todo_id,
+        status: fact.status,
+    })
+    .map_err(|error| HandlerError::Other(Box::new(error)))
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/commands/todo_cmd.rs b/tests/e2e-ui/crates/service/src/handlers/commands/todo_cmd.rs
new file mode 100644
index 00000000..2bbd94b5
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/commands/todo_cmd.rs
@@ -0,0 +1,43 @@
+//! Shared load + causal staging path for todo command handlers.
+
+use distributed::microsvc::{AggregateCheckout, CausalCommandContext, HandlerError};
+use distributed::OutboxMessage;
+use todo_domain::{Todo, TodoFact};
+
+use crate::handlers::util::rejected;
+
+/// Load aggregate by id or NotFound.
+pub async fn load_todo(
+    ctx: &CausalCommandContext<'_, Todo>,
+    todo_id: &str,
+) -> Result<AggregateCheckout<Todo>, HandlerError> {
+    ctx.load(todo_id)
+        .await?
+        .ok_or_else(|| HandlerError::NotFound(todo_id.to_string()))
+}
+
+/// Encode the domain fact and stage both it and the aggregate for one
+/// framework-owned causal commit.
+pub fn stage_todo_event(
+    ctx: &CausalCommandContext<'_, Todo>,
+    todo: AggregateCheckout<Todo>,
+    event_name: &str,
+) -> Result<TodoFact, HandlerError> {
+    let fact = TodoFact::from_todo(&todo);
+    let payload =
+        serde_json::to_vec(&fact).map_err(|error| HandlerError::Other(Box::new(error)))?;
+    let outbox = OutboxMessage::create(
+        format!("{}:{}:{}", todo.todo_id, event_name, todo.entity.version()),
+        event_name,
+        payload,
+    )
+    .map_err(|e| HandlerError::Other(Box::new(e)))?;
+    ctx.stage_outbox(outbox)?;
+    ctx.stage(todo)?;
+    Ok(fact)
+}
+
+/// Map domain error into HandlerError::Rejected.
+pub fn map_domain(err: impl std::fmt::Display) -> HandlerError {
+    rejected(err)
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/events/mod.rs b/tests/e2e-ui/crates/service/src/handlers/events/mod.rs
new file mode 100644
index 00000000..8e2ad687
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/events/mod.rs
@@ -0,0 +1,3 @@
+pub mod project_auth_user;
+pub mod project_chat;
+pub mod project_todo;
diff --git a/tests/e2e-ui/crates/service/src/handlers/events/project_auth_user.rs b/tests/e2e-ui/crates/service/src/handlers/events/project_auth_user.rs
new file mode 100644
index 00000000..e08ee22e
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/events/project_auth_user.rs
@@ -0,0 +1,53 @@
+//! Project `zitadel.user.*.v1` → `auth_users` (join target for chat + blob games).
+
+use distributed::microsvc::{Context, HandlerError};
+use distributed::ReadModelWritePlanBuilder;
+use e2e_readmodels::{map_zitadel_user_status, map_zitadel_user_upsert, ZitadelUserPayload};
+use serde_json::{json, Value};
+
+use crate::deps::AuthDeps;
+use crate::handlers::util::{decode_payload, read_model_error};
+
+pub const EVENTS: &[&str] = &[
+    "zitadel.user.human.created.v1",
+    "zitadel.user.human.updated.v1",
+    "zitadel.user.human.deactivated.v1",
+    "zitadel.user.human.reactivated.v1",
+    "zitadel.user.machine.created.v1",
+];
+
+pub fn guard<R, L, S>(_ctx: &Context<AuthDeps<R, L, S>>) -> bool
+where
+    R: crate::bounds::EventStore,
+    L: crate::bounds::Locks,
+    S: crate::bounds::ReadStore,
+{
+    true
+}
+
+pub async fn handle<R, L, S>(ctx: &Context<'_, AuthDeps<R, L, S>>) -> Result<Value, HandlerError>
+where
+    R: crate::bounds::EventStore,
+    L: crate::bounds::Locks,
+    S: crate::bounds::ReadStore,
+{
+    let payload: ZitadelUserPayload = decode_payload(ctx.message())?;
+    let name = ctx.message().name();
+    let row = if name.contains("deactivated") || name.contains("reactivated") {
+        map_zitadel_user_status(name, &payload)
+    } else {
+        map_zitadel_user_upsert(name, &payload)
+    };
+
+    let store = ctx.read_model_store();
+    let mut plan = ReadModelWritePlanBuilder::new();
+    plan.upsert(&row).map_err(read_model_error)?;
+    plan.commit(store).await.map_err(read_model_error)?;
+
+    Ok(json!({
+        "event": name,
+        "user_id": row.user_id,
+        "status": row.status,
+        "display_name": row.display_name,
+    }))
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/events/project_chat.rs b/tests/e2e-ui/crates/service/src/handlers/events/project_chat.rs
new file mode 100644
index 00000000..5bdaf3ca
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/events/project_chat.rs
@@ -0,0 +1,16 @@
+//! Causally project `chat_message.posted` → `chat_messages`.
+
+use chat_domain::ChatMessagePosted;
+use distributed::microsvc::{CausalProjectorContext, HandlerError};
+use e2e_readmodels::map_chat_posted;
+
+pub const EVENT: &str = "chat_message.posted";
+
+pub async fn handle(
+    ctx: CausalProjectorContext,
+    fact: ChatMessagePosted,
+) -> Result<(), HandlerError> {
+    let row = map_chat_posted(&fact);
+    ctx.project(&row).await?;
+    Ok(())
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/events/project_todo.rs b/tests/e2e-ui/crates/service/src/handlers/events/project_todo.rs
new file mode 100644
index 00000000..6d50f55e
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/events/project_todo.rs
@@ -0,0 +1,24 @@
+//! Causally project any `todo.*` fact → `todos` read model.
+//!
+//! Commands never write read models. Only these projectors do.
+
+use distributed::microsvc::{CausalProjectorContext, HandlerError};
+use e2e_readmodels::map_todo_fact;
+use todo_domain::TodoFact;
+
+/// Multi-event projector registration name list.
+pub const EVENTS: &[&str] = &[
+    "todo.created",
+    "todo.renamed",
+    "todo.completed",
+    "todo.reopened",
+    "todo.archived",
+    // Admin force-archive (distinct audit event; same RM upsert as archived)
+    "todo.force_archived",
+];
+
+pub async fn handle(ctx: CausalProjectorContext, fact: TodoFact) -> Result<(), HandlerError> {
+    let row = map_todo_fact(&fact);
+    ctx.project(&row).await?;
+    Ok(())
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/ingestors/mod.rs b/tests/e2e-ui/crates/service/src/handlers/ingestors/mod.rs
new file mode 100644
index 00000000..b85b44a6
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/ingestors/mod.rs
@@ -0,0 +1,6 @@
+//! External ingress commands (provider webhooks / Actions / scrapes).
+//!
+//! These publish **provider** bus messages only; projectors map them into read models.
+
+pub mod zitadel;
+pub mod zitadel_scrape;
diff --git a/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/auth.rs b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/auth.rs
new file mode 100644
index 00000000..e748a155
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/auth.rs
@@ -0,0 +1,148 @@
+//! Authenticity for Zitadel Action → HTTP deliveries.
+//!
+//! Paths:
+//! 1. **Shared secret** header `x-zitadel-ingestor-secret` or `Authorization: Bearer`
+//! 2. **Actions v2 event body** when `ZITADEL_INGESTOR_ALLOW_ACTION_EVENTS=1` (local only)
+
+use std::env;
+
+use distributed::microsvc::{HandlerError, Session};
+
+/// Env var for the shared secret (required for fixture/curl path).
+pub const SECRET_ENV: &str = "ZITADEL_INGESTOR_SECRET";
+
+/// Preferred Action/HTTP header (lowercase session keys).
+pub const SECRET_HEADER: &str = "x-zitadel-ingestor-secret";
+
+/// When `1`/`true`, accept native Actions v2 event envelopes without shared secret.
+pub const ALLOW_ACTION_EVENTS_ENV: &str = "ZITADEL_INGESTOR_ALLOW_ACTION_EVENTS";
+
+pub fn configured_secret() -> Option<String> {
+    env::var(SECRET_ENV).ok().filter(|s| !s.trim().is_empty())
+}
+
+pub fn allow_action_events() -> bool {
+    matches!(
+        env::var(ALLOW_ACTION_EVENTS_ENV)
+            .ok()
+            .as_deref()
+            .map(str::trim),
+        Some("1") | Some("true") | Some("TRUE") | Some("yes")
+    )
+}
+
+pub fn presented_secret(session: &Session) -> Option<String> {
+    if let Some(v) = session.get(SECRET_HEADER).filter(|s| !s.is_empty()) {
+        return Some(v.to_string());
+    }
+    if let Some(auth) = session.get("authorization") {
+        if let Some(token) = auth
+            .strip_prefix("Bearer ")
+            .or_else(|| auth.strip_prefix("bearer "))
+        {
+            let token = token.trim();
+            if !token.is_empty() {
+                return Some(token.to_string());
+            }
+        }
+    }
+    None
+}
+
+pub fn verify_authenticity(session: &Session, is_action_event: bool) -> Result<(), HandlerError> {
+    if let Some(presented) = presented_secret(session) {
+        let expected = configured_secret().ok_or_else(|| {
+            HandlerError::Unauthorized(format!(
+                "{SECRET_ENV} is not configured; refusing Zitadel ingress"
+            ))
+        })?;
+        if presented != expected {
+            return Err(HandlerError::Unauthorized(
+                "invalid Zitadel ingestor secret".into(),
+            ));
+        }
+        return Ok(());
+    }
+
+    if is_action_event && allow_action_events() {
+        return Ok(());
+    }
+
+    if is_action_event {
+        return Err(HandlerError::Unauthorized(format!(
+            "Action event rejected: set {ALLOW_ACTION_EVENTS_ENV}=1 (local) or send {SECRET_HEADER}"
+        )));
+    }
+
+    let _expected = configured_secret().ok_or_else(|| {
+        HandlerError::Unauthorized(format!(
+            "{SECRET_ENV} is not configured; refusing Zitadel ingress"
+        ))
+    })?;
+    Err(HandlerError::Unauthorized(format!(
+        "missing Zitadel authenticity ({SECRET_HEADER} or Authorization: Bearer)"
+    )))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::HashMap;
+    use std::sync::Mutex;
+
+    static ENV_LOCK: Mutex<()> = Mutex::new(());
+
+    fn with_env(secret: Option<&str>, allow_actions: bool, f: impl FnOnce()) {
+        let _g = ENV_LOCK.lock().unwrap();
+        let prev_s = env::var(SECRET_ENV).ok();
+        let prev_a = env::var(ALLOW_ACTION_EVENTS_ENV).ok();
+        match secret {
+            Some(s) => env::set_var(SECRET_ENV, s),
+            None => env::remove_var(SECRET_ENV),
+        }
+        if allow_actions {
+            env::set_var(ALLOW_ACTION_EVENTS_ENV, "1");
+        } else {
+            env::remove_var(ALLOW_ACTION_EVENTS_ENV);
+        }
+        f();
+        match prev_s {
+            Some(s) => env::set_var(SECRET_ENV, s),
+            None => env::remove_var(SECRET_ENV),
+        }
+        match prev_a {
+            Some(s) => env::set_var(ALLOW_ACTION_EVENTS_ENV, s),
+            None => env::remove_var(ALLOW_ACTION_EVENTS_ENV),
+        }
+    }
+
+    fn session(pairs: &[(&str, &str)]) -> Session {
+        let mut m = HashMap::new();
+        for (k, v) in pairs {
+            m.insert((*k).to_string(), (*v).to_string());
+        }
+        Session::from_map(m)
+    }
+
+    #[test]
+    fn rejects_when_secret_not_configured() {
+        with_env(None, false, || {
+            let err = verify_authenticity(&session(&[(SECRET_HEADER, "x")]), false).unwrap_err();
+            assert!(matches!(err, HandlerError::Unauthorized(_)));
+        });
+    }
+
+    #[test]
+    fn accepts_matching_header() {
+        with_env(Some("s3cret"), false, || {
+            verify_authenticity(&session(&[(SECRET_HEADER, "s3cret")]), false).unwrap();
+        });
+    }
+
+    #[test]
+    fn accepts_action_event_when_allowed() {
+        with_env(None, true, || {
+            verify_authenticity(&Session::new(), true).unwrap();
+        });
+    }
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/handle.rs b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/handle.rs
new file mode 100644
index 00000000..b37b2b1e
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/handle.rs
@@ -0,0 +1,59 @@
+//! Command: `zitadel.ingress.v1` — verify + map + publish provider message only.
+
+use distributed::microsvc::{Context, HandlerError};
+use serde_json::{json, Value};
+
+use super::auth::verify_authenticity;
+use super::map::{looks_like_action_event, map_action_delivery, normalize_ingress_body};
+use super::publish::publish_mapped_delivery;
+use crate::deps::AuthDeps;
+
+/// Public HTTP command name (POST `/{COMMAND}`).
+pub const COMMAND: &str = "zitadel.ingress.v1";
+
+pub fn guard<R, L, S>(ctx: &Context<AuthDeps<R, L, S>>) -> bool
+where
+    R: crate::bounds::EventStore,
+    L: crate::bounds::Locks,
+    S: Send + Sync + 'static,
+{
+    !ctx.raw_input().is_null()
+}
+
+pub async fn handle<R, L, S>(ctx: &Context<'_, AuthDeps<R, L, S>>) -> Result<Value, HandlerError>
+where
+    R: crate::bounds::EventStore,
+    L: crate::bounds::Locks,
+    S: Send + Sync + 'static,
+{
+    let raw = ctx.raw_input().clone();
+    let is_action_event = looks_like_action_event(&raw);
+    verify_authenticity(ctx.session(), is_action_event)?;
+
+    let input = normalize_ingress_body(&raw);
+    let Some(mapped) = map_action_delivery(&input) else {
+        return Ok(json!({
+            "ok": true,
+            "published": null,
+            "skipped": "unmapped_event_type",
+            "event_type": input.event_type,
+            "action_event": is_action_event,
+        }));
+    };
+
+    // Provider envelope only — projector maps to auth_users.
+    let leaf = ctx.repo().repo();
+    publish_mapped_delivery(leaf, &mapped)
+        .await
+        .map_err(|e| HandlerError::Other(Box::new(std::io::Error::other(e))))?;
+
+    Ok(json!({
+        "ok": true,
+        "published": mapped.message_name,
+        "event_id": mapped.delivery_id,
+        "provider_subject": mapped.payload.provider_subject,
+        "user_kind": mapped.payload.user_kind,
+        "approval_status": mapped.payload.approval_status,
+        "action_event": is_action_event,
+    }))
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/map.rs b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/map.rs
new file mode 100644
index 00000000..dc4c11eb
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/map.rs
@@ -0,0 +1,424 @@
+//! Map Zitadel Action / fixture payloads → provider bus subjects + envelopes.
+
+use e2e_readmodels::{ZitadelEmail, ZitadelUserPayload};
+use serde::Deserialize;
+use serde_json::Value;
+
+pub const HUMAN_CREATED: &str = "zitadel.user.human.created.v1";
+pub const HUMAN_UPDATED: &str = "zitadel.user.human.updated.v1";
+pub const HUMAN_DEACTIVATED: &str = "zitadel.user.human.deactivated.v1";
+pub const HUMAN_REACTIVATED: &str = "zitadel.user.human.reactivated.v1";
+pub const MACHINE_CREATED: &str = "zitadel.user.machine.created.v1";
+
+/// Ingress body accepted from Zitadel Action HTTP or local fixtures.
+#[derive(Debug, Clone, Deserialize)]
+pub struct ActionDelivery {
+    #[serde(default, alias = "event_id", alias = "id")]
+    pub delivery_id: Option<String>,
+    #[serde(default, alias = "event_type", alias = "action_event", alias = "type")]
+    pub event_type: Option<String>,
+    #[serde(default, alias = "user_id", alias = "userId")]
+    pub provider_subject: Option<String>,
+    #[serde(default, alias = "user_kind", alias = "kind")]
+    pub user_kind: Option<String>,
+    #[serde(default)]
+    pub email: Option<String>,
+    #[serde(default)]
+    pub emails: Option<Vec<EmailIn>>,
+    #[serde(default, alias = "display_name", alias = "displayName")]
+    pub display_name: Option<String>,
+    #[serde(default, alias = "approval_status")]
+    pub approval_status: Option<String>,
+    #[serde(default)]
+    pub grants: Option<Vec<String>>,
+    #[serde(default)]
+    pub roles: Option<Vec<String>>,
+    #[serde(default)]
+    pub payload: Option<Value>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct EmailIn {
+    pub address: String,
+    #[serde(default)]
+    pub primary: bool,
+    #[serde(default = "default_true")]
+    pub verified: bool,
+}
+
+fn default_true() -> bool {
+    true
+}
+
+#[derive(Debug, Clone)]
+pub struct MappedDelivery {
+    pub message_name: String,
+    pub delivery_id: String,
+    pub payload: ZitadelUserPayload,
+}
+
+pub fn looks_like_action_event(raw: &Value) -> bool {
+    raw.get("aggregateID").is_some()
+        || raw.get("aggregateId").is_some()
+        || (raw.get("aggregateType").is_some() && raw.get("sequence").is_some())
+}
+
+pub fn normalize_ingress_body(raw: &Value) -> ActionDelivery {
+    if looks_like_action_event(raw) {
+        return action_event_to_delivery(raw);
+    }
+    serde_json::from_value(raw.clone()).unwrap_or(ActionDelivery {
+        delivery_id: None,
+        event_type: None,
+        provider_subject: None,
+        user_kind: None,
+        email: None,
+        emails: None,
+        display_name: None,
+        approval_status: None,
+        grants: None,
+        roles: None,
+        payload: Some(raw.clone()),
+    })
+}
+
+fn action_event_to_delivery(raw: &Value) -> ActionDelivery {
+    let aggregate_id = raw
+        .get("aggregateID")
+        .or_else(|| raw.get("aggregateId"))
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string());
+    let event_type = raw
+        .get("type")
+        .or_else(|| raw.get("eventType"))
+        .or_else(|| raw.get("event_type"))
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string());
+    let sequence = raw
+        .get("sequence")
+        .map(|v| match v {
+            Value::String(s) => s.clone(),
+            Value::Number(n) => n.to_string(),
+            _ => String::new(),
+        })
+        .filter(|s| !s.is_empty());
+    let delivery_id = match (&aggregate_id, &event_type, &sequence) {
+        (Some(a), Some(t), Some(s)) => Some(format!("zitadel-action:{t}:{a}:{s}")),
+        (Some(a), Some(t), None) => Some(format!("zitadel-action:{t}:{a}")),
+        _ => sequence.clone(),
+    };
+
+    let event_payload = raw
+        .get("event_payload")
+        .or_else(|| raw.get("eventPayload"))
+        .or_else(|| raw.get("payload"))
+        .cloned()
+        .unwrap_or(Value::Null);
+
+    let email = event_payload
+        .get("emailAddress")
+        .or_else(|| event_payload.get("email"))
+        .or_else(|| event_payload.pointer("/email/email"))
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string());
+    let display_name = event_payload
+        .get("displayName")
+        .or_else(|| event_payload.get("display_name"))
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string());
+    let user_name = event_payload
+        .get("userName")
+        .or_else(|| event_payload.get("user_name"))
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string());
+
+    let grants = event_payload
+        .get("roleKeys")
+        .or_else(|| event_payload.get("role_keys"))
+        .and_then(|v| v.as_array())
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|x| x.as_str().map(|s| s.to_string()))
+                .collect::<Vec<_>>()
+        })
+        .filter(|v| !v.is_empty());
+
+    let subject = event_payload
+        .get("userId")
+        .or_else(|| event_payload.get("userID"))
+        .or_else(|| event_payload.get("user_id"))
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string())
+        .or(aggregate_id);
+
+    let kind = if event_type
+        .as_deref()
+        .unwrap_or("")
+        .to_ascii_lowercase()
+        .contains("machine")
+    {
+        Some("machine".into())
+    } else {
+        Some("human".into())
+    };
+
+    ActionDelivery {
+        delivery_id,
+        event_type,
+        provider_subject: subject,
+        user_kind: kind,
+        email: email.or(user_name),
+        emails: None,
+        display_name,
+        approval_status: None,
+        grants,
+        roles: None,
+        payload: Some(raw.clone()),
+    }
+}
+
+pub fn map_action_delivery(input: &ActionDelivery) -> Option<MappedDelivery> {
+    let subject = input
+        .provider_subject
+        .as_deref()
+        .map(str::trim)
+        .filter(|s| !s.is_empty())?;
+    let event_type = input
+        .event_type
+        .as_deref()
+        .map(str::trim)
+        .filter(|s| !s.is_empty())?;
+
+    let message_name = resolve_message_name(event_type, input.user_kind.as_deref())?;
+    let user_kind = if message_name == MACHINE_CREATED {
+        "machine".to_string()
+    } else {
+        match input.user_kind.as_deref().map(str::to_ascii_lowercase) {
+            Some(k) if k == "machine" || k == "service" => "machine".into(),
+            _ => "human".into(),
+        }
+    };
+
+    let delivery_id = input
+        .delivery_id
+        .clone()
+        .filter(|s| !s.trim().is_empty())
+        .unwrap_or_else(|| format!("zitadel:{message_name}:{subject}"));
+
+    let emails = normalize_emails(input);
+    let approval_status = derive_approval(input, &user_kind);
+
+    let payload = ZitadelUserPayload {
+        schema_version: 1,
+        source: "zitadel".into(),
+        delivery_id: delivery_id.clone(),
+        provider: "zitadel".into(),
+        provider_subject: subject.to_string(),
+        user_kind,
+        emails,
+        display_name: input.display_name.clone().filter(|s| !s.trim().is_empty()),
+        approval_status,
+        ingested_at: now_rfc3339ish(),
+    };
+
+    Some(MappedDelivery {
+        message_name: message_name.to_string(),
+        delivery_id,
+        payload,
+    })
+}
+
+fn resolve_message_name(event_type: &str, user_kind: Option<&str>) -> Option<&'static str> {
+    let t = event_type.to_ascii_lowercase().replace('_', ".");
+    match t.as_str() {
+        HUMAN_CREATED | "zitadel.user.human.created" => return Some(HUMAN_CREATED),
+        HUMAN_UPDATED | "zitadel.user.human.updated" => return Some(HUMAN_UPDATED),
+        HUMAN_DEACTIVATED | "zitadel.user.human.deactivated" => return Some(HUMAN_DEACTIVATED),
+        HUMAN_REACTIVATED | "zitadel.user.human.reactivated" => return Some(HUMAN_REACTIVATED),
+        MACHINE_CREATED | "zitadel.user.machine.created" => return Some(MACHINE_CREATED),
+        _ => {}
+    }
+
+    let kind_machine = matches!(
+        user_kind.map(str::to_ascii_lowercase).as_deref(),
+        Some("machine") | Some("service")
+    );
+
+    if t.contains("machine") && (t.contains("created") || t.ends_with(".added")) {
+        return Some(MACHINE_CREATED);
+    }
+    if t.contains("deactivat") || t.contains(".locked") || t.ends_with(".locked") {
+        return Some(HUMAN_DEACTIVATED);
+    }
+    if t.contains("reactivat") || t.contains(".unlocked") || t.ends_with(".unlocked") {
+        return Some(HUMAN_REACTIVATED);
+    }
+    if t.contains("human") && (t.contains("added") || t.contains("created")) {
+        return Some(HUMAN_CREATED);
+    }
+    if t.contains("created")
+        || t.contains("create")
+        || (t.ends_with(".added") && !t.contains("grant"))
+    {
+        return if kind_machine {
+            Some(MACHINE_CREATED)
+        } else {
+            Some(HUMAN_CREATED)
+        };
+    }
+    if t.contains("updated")
+        || t.contains("update")
+        || t.contains("changed")
+        || t.contains("grant")
+        || t.contains("role")
+        || t.contains("profile")
+        || t.contains("email")
+    {
+        return Some(HUMAN_UPDATED);
+    }
+    None
+}
+
+fn normalize_emails(input: &ActionDelivery) -> Vec<ZitadelEmail> {
+    if let Some(list) = &input.emails {
+        if !list.is_empty() {
+            return list
+                .iter()
+                .map(|e| ZitadelEmail {
+                    address: e.address.clone(),
+                    primary: e.primary,
+                    verified: e.verified,
+                })
+                .collect();
+        }
+    }
+    if let Some(email) = input.email.as_ref().filter(|s| !s.trim().is_empty()) {
+        return vec![ZitadelEmail {
+            address: email.clone(),
+            primary: true,
+            verified: true,
+        }];
+    }
+    Vec::new()
+}
+
+fn derive_approval(input: &ActionDelivery, user_kind: &str) -> String {
+    if user_kind == "machine" {
+        return "approved".into();
+    }
+    if let Some(status) = input
+        .approval_status
+        .as_deref()
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+    {
+        return status.to_ascii_lowercase();
+    }
+    let has_approved = input
+        .grants
+        .iter()
+        .flatten()
+        .chain(input.roles.iter().flatten())
+        .any(|g| g.eq_ignore_ascii_case("approved"));
+    if has_approved {
+        "approved".into()
+    } else {
+        "pending".into()
+    }
+}
+
+fn now_rfc3339ish() -> String {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    let d = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default();
+    // Sortable timestamp without chrono dependency.
+    format!("{}", d.as_millis())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn maps_human_created_with_waitlist_pending() {
+        let input = ActionDelivery {
+            delivery_id: Some("d1".into()),
+            event_type: Some("user.human.created".into()),
+            provider_subject: Some("sub-1".into()),
+            user_kind: Some("human".into()),
+            email: Some("ada@example.com".into()),
+            emails: None,
+            display_name: Some("Ada".into()),
+            approval_status: None,
+            grants: None,
+            roles: None,
+            payload: None,
+        };
+        let m = map_action_delivery(&input).expect("mapped");
+        assert_eq!(m.message_name, HUMAN_CREATED);
+        assert_eq!(m.delivery_id, "d1");
+        assert_eq!(m.payload.approval_status, "pending");
+        assert_eq!(m.payload.user_kind, "human");
+        assert_eq!(m.payload.emails[0].address, "ada@example.com");
+    }
+
+    #[test]
+    fn maps_updated_with_approved_grant() {
+        let input = ActionDelivery {
+            delivery_id: Some("d2".into()),
+            event_type: Some("user.human.updated".into()),
+            provider_subject: Some("sub-1".into()),
+            user_kind: None,
+            email: Some("ada@example.com".into()),
+            emails: None,
+            display_name: Some("Ada".into()),
+            approval_status: None,
+            grants: Some(vec!["approved".into()]),
+            roles: None,
+            payload: None,
+        };
+        let m = map_action_delivery(&input).unwrap();
+        assert_eq!(m.message_name, HUMAN_UPDATED);
+        assert_eq!(m.payload.approval_status, "approved");
+    }
+
+    #[test]
+    fn unmapped_type_returns_none() {
+        let input = ActionDelivery {
+            delivery_id: Some("d3".into()),
+            event_type: Some("org.metadata.set".into()),
+            provider_subject: Some("sub-1".into()),
+            user_kind: None,
+            email: None,
+            emails: None,
+            display_name: None,
+            approval_status: None,
+            grants: None,
+            roles: None,
+            payload: None,
+        };
+        assert!(map_action_delivery(&input).is_none());
+    }
+
+    #[test]
+    fn maps_native_action_event_human_added() {
+        let raw = json!({
+            "aggregateID": "user-99",
+            "aggregateType": "user",
+            "sequence": 7,
+            "type": "user.human.added",
+            "event_payload": {
+                "userName": "ada@example.com",
+                "emailAddress": "ada@example.com",
+                "displayName": "Ada"
+            }
+        });
+        let d = normalize_ingress_body(&raw);
+        assert_eq!(d.provider_subject.as_deref(), Some("user-99"));
+        let m = map_action_delivery(&d).expect("mapped");
+        assert_eq!(m.message_name, HUMAN_CREATED);
+        assert_eq!(m.payload.provider_subject, "user-99");
+    }
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/mod.rs b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/mod.rs
new file mode 100644
index 00000000..422982ac
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/mod.rs
@@ -0,0 +1,54 @@
+//! Zitadel Action/HTTP ingress + Management API scrape → provider messages only.
+//!
+//! Teaching fixture (simplified from gitkb domain-service):
+//! 1. Authenticity (`auth`) — shared secret header
+//! 2. Map (`map`) — Action payload → typed `zitadel.*.v1` subjects
+//! 3. Publish (`publish`) — outbox provider message only
+//! 4. Projector (`project_auth_user`) — upserts `auth_users` for GraphQL joins
+//! 5. Scrape (`scrape`) — periodic Management API reconcile for missed events
+//!
+//! See `docs/zitadel-ingestor.md`.
+
+mod auth;
+mod handle;
+mod map;
+mod publish;
+pub mod scrape;
+
+pub use auth::{
+    allow_action_events, configured_secret, verify_authenticity, ALLOW_ACTION_EVENTS_ENV,
+    SECRET_ENV, SECRET_HEADER,
+};
+pub use handle::{guard, handle, COMMAND};
+pub use map::{
+    looks_like_action_event, map_action_delivery, normalize_ingress_body, ActionDelivery,
+    MappedDelivery, HUMAN_CREATED, HUMAN_DEACTIVATED, HUMAN_REACTIVATED, HUMAN_UPDATED,
+    MACHINE_CREATED,
+};
+pub use scrape::{
+    scrape_users_to_outbox, spawn_scrape_loop, ScrapeReport, ZitadelScrapeConfig, API_URL_ENV,
+    INTERVAL_ENV, ON_START_ENV, TOKEN_ENV,
+};
+
+/// Provider event names published by this ingestor (never domain forgeries).
+pub fn is_provider_message_name(name: &str) -> bool {
+    name.starts_with("zitadel.")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn provider_names_are_zitadel_prefixed() {
+        for name in [
+            HUMAN_CREATED,
+            HUMAN_UPDATED,
+            HUMAN_DEACTIVATED,
+            HUMAN_REACTIVATED,
+            MACHINE_CREATED,
+        ] {
+            assert!(is_provider_message_name(name), "{name}");
+        }
+    }
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/publish.rs b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/publish.rs
new file mode 100644
index 00000000..cde74935
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/publish.rs
@@ -0,0 +1,22 @@
+//! Shared outbox publish for provider messages (ingress + scrape).
+
+use distributed::{CommitBuilderExt, OutboxMessage, TransactionalCommit};
+
+use super::map::MappedDelivery;
+
+/// Encode + leaf-outbox commit a mapped provider delivery.
+pub async fn publish_mapped_delivery<R: TransactionalCommit>(
+    repo: &R,
+    mapped: &MappedDelivery,
+) -> Result<(), String> {
+    let outbox = OutboxMessage::encode(
+        mapped.delivery_id.clone(),
+        mapped.message_name.as_str(),
+        &mapped.payload,
+    )
+    .map_err(|e| e.to_string())?;
+    CommitBuilderExt::outbox(repo, outbox)
+        .commit_all()
+        .await
+        .map_err(|e| e.to_string())
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/scrape.rs b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/scrape.rs
new file mode 100644
index 00000000..ea3f2afa
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel/scrape.rs
@@ -0,0 +1,484 @@
+//! Periodic / on-demand Zitadel Management API scrape → same provider outbox path.
+//!
+//! Actions cover the happy path. Scrape reconciles users we never got events for
+//! (Action downtime, misconfig, historical backfill).
+
+use std::env;
+use std::time::Duration;
+
+use distributed::TransactionalCommit;
+use e2e_readmodels::{ZitadelEmail, ZitadelUserPayload};
+use serde::Deserialize;
+use serde_json::{json, Value};
+
+use super::map::{MappedDelivery, HUMAN_DEACTIVATED, HUMAN_UPDATED, MACHINE_CREATED};
+use super::publish::publish_mapped_delivery;
+
+/// Env: Management API base (no trailing slash). Falls back to `OIDC_ISSUER`.
+pub const API_URL_ENV: &str = "ZITADEL_API_URL";
+/// Env: PAT / service user token (same as Login V2 `ZITADEL_SERVICE_USER_TOKEN`).
+pub const TOKEN_ENV: &str = "ZITADEL_SERVICE_USER_TOKEN";
+/// Env: scrape interval seconds. `0` or unset with no token → disabled.
+/// Default when token present: `60`.
+pub const INTERVAL_ENV: &str = "ZITADEL_SCRAPE_INTERVAL_SECS";
+/// Env: run one scrape immediately on process start (`1`/`true`). Default on when configured.
+pub const ON_START_ENV: &str = "ZITADEL_SCRAPE_ON_START";
+
+#[derive(Debug, Clone)]
+pub struct ZitadelScrapeConfig {
+    pub api_base: String,
+    pub token: String,
+    pub interval: Duration,
+    pub on_start: bool,
+    pub page_size: u32,
+}
+
+impl ZitadelScrapeConfig {
+    /// Load from env. Returns `None` when token or API base is missing, or interval is 0
+    /// with scrape explicitly disabled.
+    pub fn from_env() -> Option<Self> {
+        let token = env::var(TOKEN_ENV)
+            .or_else(|_| env::var("ZITADEL_MANAGEMENT_PAT"))
+            .ok()
+            .map(|s| s.trim().to_string())
+            .filter(|s| !s.is_empty())?;
+
+        let api_base = env::var(API_URL_ENV)
+            .or_else(|_| env::var("OIDC_ISSUER"))
+            .ok()
+            .map(|s| s.trim().trim_end_matches('/').to_string())
+            .filter(|s| !s.is_empty())?;
+
+        let interval_secs: u64 = env::var(INTERVAL_ENV)
+            .ok()
+            .and_then(|s| s.trim().parse().ok())
+            .unwrap_or(60);
+        if interval_secs == 0 {
+            // Allow on-demand command only; no background loop.
+            return Some(Self {
+                api_base,
+                token,
+                interval: Duration::ZERO,
+                on_start: false,
+                page_size: 100,
+            });
+        }
+
+        let on_start = match env::var(ON_START_ENV).ok().as_deref().map(str::trim) {
+            Some("0") | Some("false") | Some("FALSE") | Some("off") => false,
+            _ => true,
+        };
+
+        Some(Self {
+            api_base,
+            token,
+            interval: Duration::from_secs(interval_secs),
+            on_start,
+            page_size: 100,
+        })
+    }
+
+    pub fn background_enabled(&self) -> bool {
+        !self.interval.is_zero()
+    }
+}
+
+#[derive(Debug, Default, Clone)]
+pub struct ScrapeReport {
+    pub listed: usize,
+    pub published: usize,
+    pub skipped: usize,
+    pub errors: Vec<String>,
+}
+
+/// List users from Zitadel Management API and publish provider messages for each.
+pub async fn scrape_users_to_outbox<R: TransactionalCommit>(
+    repo: &R,
+    cfg: &ZitadelScrapeConfig,
+) -> ScrapeReport {
+    let mut report = ScrapeReport::default();
+    let users = match list_all_users(cfg).await {
+        Ok(u) => u,
+        Err(e) => {
+            report.errors.push(e);
+            return report;
+        }
+    };
+    report.listed = users.len();
+
+    for user in users {
+        let Some(mapped) = map_mgmt_user(&user) else {
+            report.skipped += 1;
+            continue;
+        };
+        match publish_mapped_delivery(repo, &mapped).await {
+            Ok(()) => report.published += 1,
+            Err(e) => {
+                // Duplicate outbox ids (unchanged fingerprint) are expected on re-scrape.
+                if e.contains("UNIQUE") || e.contains("unique") || e.contains("already") {
+                    report.skipped += 1;
+                } else {
+                    report.errors.push(format!(
+                        "user {}: publish failed: {e}",
+                        mapped.payload.provider_subject
+                    ));
+                }
+            }
+        }
+    }
+    report
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct SearchResponse {
+    #[serde(default)]
+    result: Vec<MgmtUser>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct MgmtUser {
+    id: Option<String>,
+    #[serde(default, rename = "userName")]
+    user_name: Option<String>,
+    #[serde(default)]
+    state: Option<String>,
+    #[serde(default)]
+    human: Option<MgmtHuman>,
+    #[serde(default)]
+    machine: Option<MgmtMachine>,
+    #[serde(default, rename = "changeDate")]
+    change_date: Option<String>,
+    #[serde(default, rename = "details")]
+    details: Option<MgmtDetails>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct MgmtDetails {
+    #[serde(default, rename = "changeDate")]
+    change_date: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct MgmtHuman {
+    #[serde(default)]
+    profile: Option<MgmtProfile>,
+    #[serde(default)]
+    email: Option<MgmtEmail>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct MgmtProfile {
+    #[serde(default, rename = "displayName")]
+    display_name: Option<String>,
+    #[serde(default, rename = "firstName")]
+    first_name: Option<String>,
+    #[serde(default, rename = "lastName")]
+    last_name: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct MgmtEmail {
+    #[serde(default)]
+    email: Option<String>,
+    #[serde(default, rename = "isEmailVerified")]
+    is_email_verified: Option<bool>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct MgmtMachine {
+    #[serde(default)]
+    name: Option<String>,
+}
+
+async fn list_all_users(cfg: &ZitadelScrapeConfig) -> Result<Vec<MgmtUser>, String> {
+    let client = reqwest::Client::new();
+    let mut offset: u64 = 0;
+    let mut all = Vec::new();
+
+    loop {
+        let body = json!({
+            "query": {
+                "offset": offset.to_string(),
+                "limit": cfg.page_size,
+                "asc": true
+            },
+            "sortingColumn": "USER_FIELD_NAME_USER_NAME",
+            "queries": []
+        });
+        let url = format!("{}/management/v1/users/_search", cfg.api_base);
+        let resp = client
+            .post(&url)
+            .header("Authorization", format!("Bearer {}", cfg.token))
+            .header("Content-Type", "application/json")
+            .json(&body)
+            .send()
+            .await
+            .map_err(|e| format!("zitadel search request: {e}"))?;
+
+        let status = resp.status();
+        let text = resp
+            .text()
+            .await
+            .map_err(|e| format!("zitadel search body: {e}"))?;
+        if !status.is_success() {
+            return Err(format!("zitadel search HTTP {status}: {text}"));
+        }
+        let page: SearchResponse = serde_json::from_str(&text)
+            .map_err(|e| format!("zitadel search json: {e}; body={text}"))?;
+        let n = page.result.len();
+        all.extend(page.result);
+        if n < cfg.page_size as usize {
+            break;
+        }
+        offset += n as u64;
+        if offset > 10_000 {
+            break; // safety
+        }
+    }
+    Ok(all)
+}
+
+/// Map one Management API user row → provider bus delivery (or None if unusable).
+pub fn map_management_user(raw: &Value) -> Option<MappedDelivery> {
+    let user: MgmtUser = serde_json::from_value(raw.clone()).ok()?;
+    map_mgmt_user(&user)
+}
+
+fn map_mgmt_user(user: &MgmtUser) -> Option<MappedDelivery> {
+    let id = user.id.as_deref()?.trim();
+    if id.is_empty() {
+        return None;
+    }
+    let state = user.state.as_deref().unwrap_or("USER_STATE_ACTIVE");
+    let is_machine = user.machine.is_some() && user.human.is_none();
+    let deactivated = state.contains("INACTIVE")
+        || state.contains("LOCKED")
+        || state.contains("SUSPEND")
+        || state.contains("DELETED");
+
+    let (email, display_name, user_kind) = if is_machine {
+        let name = user
+            .machine
+            .as_ref()
+            .and_then(|m| m.name.clone())
+            .or_else(|| user.user_name.clone())
+            .unwrap_or_else(|| id.to_string());
+        (String::new(), name, "machine".to_string())
+    } else {
+        let human = user.human.as_ref();
+        let email = human
+            .and_then(|h| h.email.as_ref())
+            .and_then(|e| e.email.clone())
+            .unwrap_or_default();
+        let display = human
+            .and_then(|h| h.profile.as_ref())
+            .and_then(|p| {
+                p.display_name
+                    .clone()
+                    .or_else(|| match (&p.first_name, &p.last_name) {
+                        (Some(f), Some(l)) => Some(format!("{f} {l}")),
+                        (Some(f), None) => Some(f.clone()),
+                        _ => None,
+                    })
+            })
+            .or_else(|| user.user_name.clone())
+            .unwrap_or_else(|| {
+                if email.is_empty() {
+                    id.to_string()
+                } else {
+                    email.clone()
+                }
+            });
+        (email, display, "human".to_string())
+    };
+
+    let message_name = if is_machine {
+        MACHINE_CREATED
+    } else if deactivated {
+        HUMAN_DEACTIVATED
+    } else {
+        // Reconcile as update — projector upserts; works for create + change.
+        HUMAN_UPDATED
+    };
+
+    let change = user
+        .change_date
+        .clone()
+        .or_else(|| user.details.as_ref().and_then(|d| d.change_date.clone()))
+        .unwrap_or_else(|| "0".into());
+    // Stable when profile unchanged so re-scrape can skip duplicate outbox ids.
+    let fingerprint = simple_fingerprint(&[&email, &display_name, state, &user_kind, &change]);
+    let delivery_id = format!("zitadel-scrape:{id}:{fingerprint}");
+
+    let emails = if email.is_empty() {
+        Vec::new()
+    } else {
+        vec![ZitadelEmail {
+            address: email,
+            primary: true,
+            verified: user
+                .human
+                .as_ref()
+                .and_then(|h| h.email.as_ref())
+                .and_then(|e| e.is_email_verified)
+                .unwrap_or(true),
+        }]
+    };
+
+    let payload = ZitadelUserPayload {
+        schema_version: 1,
+        source: "zitadel-scrape".into(),
+        delivery_id: delivery_id.clone(),
+        provider: "zitadel".into(),
+        provider_subject: id.to_string(),
+        user_kind,
+        emails,
+        display_name: Some(display_name),
+        approval_status: if is_machine {
+            "approved".into()
+        } else {
+            "approved".into() // scrape treats listed humans as directory members
+        },
+        ingested_at: now_ms(),
+    };
+
+    Some(MappedDelivery {
+        message_name: message_name.to_string(),
+        delivery_id,
+        payload,
+    })
+}
+
+fn simple_fingerprint(parts: &[&str]) -> String {
+    // FNV-1a 64 — stable, no extra deps.
+    let mut hash: u64 = 0xcbf29ce484222325;
+    for p in parts {
+        for b in p.as_bytes() {
+            hash ^= u64::from(*b);
+            hash = hash.wrapping_mul(0x100000001b3);
+        }
+        hash ^= 0xff;
+        hash = hash.wrapping_mul(0x100000001b3);
+    }
+    format!("{hash:016x}")
+}
+
+fn now_ms() -> String {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    let d = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default();
+    format!("{}", d.as_millis())
+}
+
+/// Background loop: optional immediate scrape, then every `cfg.interval`.
+pub fn spawn_scrape_loop<R>(repo: R, cfg: ZitadelScrapeConfig)
+where
+    R: TransactionalCommit + Clone + Send + Sync + 'static,
+{
+    if !cfg.background_enabled() && !cfg.on_start {
+        return;
+    }
+    tokio::spawn(async move {
+        if cfg.on_start {
+            let r = scrape_users_to_outbox(&repo, &cfg).await;
+            eprintln!(
+                "zitadel scrape (start): listed={} published={} skipped={} errors={}",
+                r.listed,
+                r.published,
+                r.skipped,
+                r.errors.len()
+            );
+            for e in &r.errors {
+                eprintln!("zitadel scrape: {e}");
+            }
+        }
+        if !cfg.background_enabled() {
+            return;
+        }
+        loop {
+            tokio::time::sleep(cfg.interval).await;
+            let r = scrape_users_to_outbox(&repo, &cfg).await;
+            if r.published > 0 || !r.errors.is_empty() {
+                eprintln!(
+                    "zitadel scrape: listed={} published={} skipped={} errors={}",
+                    r.listed,
+                    r.published,
+                    r.skipped,
+                    r.errors.len()
+                );
+            }
+            for e in &r.errors {
+                eprintln!("zitadel scrape: {e}");
+            }
+        }
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn maps_active_human() {
+        let raw = json!({
+            "id": "user-1",
+            "userName": "alice",
+            "state": "USER_STATE_ACTIVE",
+            "human": {
+                "profile": { "displayName": "Alice" },
+                "email": { "email": "alice@e2e.local", "isEmailVerified": true }
+            },
+            "changeDate": "2026-01-01T00:00:00Z"
+        });
+        let m = map_management_user(&raw).expect("mapped");
+        assert_eq!(m.message_name, HUMAN_UPDATED);
+        assert_eq!(m.payload.provider_subject, "user-1");
+        assert_eq!(m.payload.display_name.as_deref(), Some("Alice"));
+        assert_eq!(m.payload.emails[0].address, "alice@e2e.local");
+        assert!(m.delivery_id.starts_with("zitadel-scrape:user-1:"));
+    }
+
+    #[test]
+    fn maps_inactive_as_deactivated() {
+        let raw = json!({
+            "id": "user-2",
+            "state": "USER_STATE_INACTIVE",
+            "human": {
+                "profile": { "displayName": "Bob" },
+                "email": { "email": "bob@e2e.local" }
+            }
+        });
+        let m = map_management_user(&raw).unwrap();
+        assert_eq!(m.message_name, HUMAN_DEACTIVATED);
+    }
+
+    #[test]
+    fn maps_machine() {
+        let raw = json!({
+            "id": "svc-1",
+            "state": "USER_STATE_ACTIVE",
+            "machine": { "name": "bot" }
+        });
+        let m = map_management_user(&raw).unwrap();
+        assert_eq!(m.message_name, MACHINE_CREATED);
+        assert_eq!(m.payload.user_kind, "machine");
+    }
+
+    #[test]
+    fn same_profile_same_fingerprint() {
+        let raw = json!({
+            "id": "user-1",
+            "state": "USER_STATE_ACTIVE",
+            "human": {
+                "profile": { "displayName": "Alice" },
+                "email": { "email": "a@x.com" }
+            },
+            "changeDate": "t1"
+        });
+        let a = map_management_user(&raw).unwrap();
+        let b = map_management_user(&raw).unwrap();
+        assert_eq!(a.delivery_id, b.delivery_id);
+    }
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel_scrape.rs b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel_scrape.rs
new file mode 100644
index 00000000..2b24f17d
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/ingestors/zitadel_scrape.rs
@@ -0,0 +1,52 @@
+//! Command: `zitadel.scrape.v1` — on-demand Management API reconciliation scrape.
+//!
+//! Authenticity: same shared secret as Action ingress (`x-zitadel-ingestor-secret`).
+//! Requires `ZITADEL_SERVICE_USER_TOKEN` + `ZITADEL_API_URL` / `OIDC_ISSUER` in env.
+
+use distributed::microsvc::{Context, HandlerError};
+use serde_json::{json, Value};
+
+use super::zitadel::scrape::{scrape_users_to_outbox, ZitadelScrapeConfig};
+use super::zitadel::verify_authenticity;
+use crate::deps::AuthDeps;
+
+pub const COMMAND: &str = "zitadel.scrape.v1";
+
+pub fn guard<R, L, S>(_ctx: &Context<AuthDeps<R, L, S>>) -> bool
+where
+    R: crate::bounds::EventStore,
+    L: crate::bounds::Locks,
+    S: Send + Sync + 'static,
+{
+    // Empty body is fine; authenticity checked in handle.
+    true
+}
+
+pub async fn handle<R, L, S>(ctx: &Context<'_, AuthDeps<R, L, S>>) -> Result<Value, HandlerError>
+where
+    R: crate::bounds::EventStore,
+    L: crate::bounds::Locks,
+    S: Send + Sync + 'static,
+{
+    // Not an Action event envelope — require shared secret.
+    verify_authenticity(ctx.session(), false)?;
+
+    let cfg = ZitadelScrapeConfig::from_env().ok_or_else(|| {
+        HandlerError::Rejected(format!(
+            "scrape not configured: set {} and {} (or OIDC_ISSUER)",
+            super::zitadel::scrape::TOKEN_ENV,
+            super::zitadel::scrape::API_URL_ENV
+        ))
+    })?;
+
+    let leaf = ctx.repo().repo();
+    let report = scrape_users_to_outbox(leaf, &cfg).await;
+
+    Ok(json!({
+        "ok": report.errors.is_empty(),
+        "listed": report.listed,
+        "published": report.published,
+        "skipped": report.skipped,
+        "errors": report.errors,
+    }))
+}
diff --git a/tests/e2e-ui/crates/service/src/handlers/mod.rs b/tests/e2e-ui/crates/service/src/handlers/mod.rs
new file mode 100644
index 00000000..024f6087
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/mod.rs
@@ -0,0 +1,4 @@
+pub mod commands;
+pub mod events;
+pub mod ingestors;
+pub mod util;
diff --git a/tests/e2e-ui/crates/service/src/handlers/util.rs b/tests/e2e-ui/crates/service/src/handlers/util.rs
new file mode 100644
index 00000000..174ff68e
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/handlers/util.rs
@@ -0,0 +1,106 @@
+//! Shared handler helpers.
+
+use distributed::bus::Message;
+use distributed::microsvc::{HandlerError, Session};
+use distributed::{BitcodePayloadCodec, PayloadCodec};
+use serde::de::DeserializeOwned;
+
+/// Decode event payload as JSON (tests) or bitcode (outbox → bus).
+pub fn decode_payload<T: DeserializeOwned>(message: &Message) -> Result<T, HandlerError> {
+    let ct = message.content_type.as_str();
+    if ct.contains("json") || looks_like_json(message.payload()) {
+        return serde_json::from_slice(message.payload())
+            .map_err(|e| HandlerError::DecodeFailed(format!("json payload: {e}")));
+    }
+    BitcodePayloadCodec::decode(message.payload())
+        .map_err(|e| HandlerError::DecodeFailed(format!("bitcode payload: {e}")))
+}
+
+fn looks_like_json(bytes: &[u8]) -> bool {
+    matches!(
+        bytes.iter().find(|b| !b.is_ascii_whitespace()),
+        Some(b'{' | b'[')
+    )
+}
+
+pub fn rejected(err: impl std::fmt::Display) -> HandlerError {
+    HandlerError::Rejected(err.to_string())
+}
+
+pub fn read_model_error(e: impl std::fmt::Display) -> HandlerError {
+    HandlerError::Other(Box::new(std::io::Error::other(e.to_string())))
+}
+
+/// Authenticated user from session (`x-user-id` via DevHeaders or OIDC claim map).
+pub fn require_user(session: &Session) -> Result<String, HandlerError> {
+    session
+        .user_id()
+        .filter(|s| !s.is_empty())
+        .map(|s| s.to_string())
+        .ok_or_else(|| HandlerError::Unauthorized("missing x-user-id".into()))
+}
+
+/// Session has a non-empty user id (for `guard` — bool, not Result).
+pub fn session_has_user(session: &Session) -> bool {
+    session.user_id().is_some_and(|s| !s.is_empty())
+}
+
+/// Engine role is `admin` (`x-role` / OIDC claim map). For `guard`.
+pub fn session_is_admin(session: &Session) -> bool {
+    session.role() == Some("admin")
+}
+
+/// Require engine role `admin` (handler-path Result form).
+pub fn require_admin(session: &Session) -> Result<(), HandlerError> {
+    match session.role() {
+        Some("admin") => Ok(()),
+        Some(other) => Err(HandlerError::Rejected(format!(
+            "admin role required, got `{other}`"
+        ))),
+        None => Err(HandlerError::Unauthorized("missing x-role".into())),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use distributed::microsvc::{Session, ROLE_KEY, USER_ID_KEY};
+
+    #[test]
+    fn session_has_user_requires_nonempty_id() {
+        let mut s = Session::new();
+        assert!(!session_has_user(&s));
+        s.set(USER_ID_KEY, "");
+        assert!(!session_has_user(&s));
+        s.set(USER_ID_KEY, "alice");
+        assert!(session_has_user(&s));
+    }
+
+    #[test]
+    fn session_is_admin_exact_role() {
+        let mut s = Session::new();
+        assert!(!session_is_admin(&s));
+        s.set(ROLE_KEY, "user");
+        assert!(!session_is_admin(&s));
+        s.set(ROLE_KEY, "admin");
+        assert!(session_is_admin(&s));
+    }
+
+    #[test]
+    fn require_admin_errors() {
+        let mut s = Session::new();
+        assert!(require_admin(&s).is_err());
+        s.set(ROLE_KEY, "user");
+        assert!(require_admin(&s).is_err());
+        s.set(ROLE_KEY, "admin");
+        assert!(require_admin(&s).is_ok());
+    }
+
+    #[test]
+    fn require_user_errors_and_returns_id() {
+        let mut s = Session::new();
+        assert!(require_user(&s).is_err());
+        s.set(USER_ID_KEY, "bob");
+        assert_eq!(require_user(&s).unwrap(), "bob");
+    }
+}
diff --git a/tests/e2e-ui/crates/service/src/lib.rs b/tests/e2e-ui/crates/service/src/lib.rs
new file mode 100644
index 00000000..b8a2f0b8
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/lib.rs
@@ -0,0 +1,24 @@
+//! e2e-ui service library — handlers + GraphQL.
+//!
+//! Domain logic lives in `*-domain`. Read models live in `e2e-readmodels`.
+//! This crate wires thin command handlers + event projectors + Zitadel ingress.
+//! **Commands never write read models** — only projectors do (including auth_users
+//! from provider messages published by the Zitadel ingestor).
+
+mod bounds;
+mod deps;
+pub mod handlers;
+mod oidc_layer;
+mod service;
+
+pub use e2e_readmodels::distributed_manifest;
+/// Zitadel Management API scrape (reconcile missed Action events).
+pub use handlers::ingestors::zitadel::{
+    scrape_users_to_outbox, spawn_scrape_loop, ScrapeReport, ZitadelScrapeConfig,
+};
+pub use oidc_layer::serve_with_oidc;
+pub use service::{
+    build_graphql_engine, build_service, dev_identity, distributed_admin_client_surface,
+    distributed_client_surface, identity_from_env, oidc_bearer_config,
+    DISTRIBUTED_ADMIN_CLIENT_SURFACE, DISTRIBUTED_CLIENT_SURFACE,
+};
diff --git a/tests/e2e-ui/crates/service/src/oidc_layer.rs b/tests/e2e-ui/crates/service/src/oidc_layer.rs
new file mode 100644
index 00000000..c42a8203
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/oidc_layer.rs
@@ -0,0 +1,254 @@
+//! Tower layer: under OidcBearer/Hybrid, **require** a valid access token and
+//! inject claim-derived `x-user-id` / `x-role` for command routes.
+//!
+//! Security: client-supplied identity headers are stripped before validation so
+//! spoofed `x-user-id` cannot pass when Bearer is missing or invalid.
+//! GraphQL already uses IdentityConfig; commands only read Session headers —
+//! this layer bridges OIDC → DevHeaders-shaped keys for handlers.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::task::{Context, Poll};
+
+use axum::body::Body;
+use axum::http::{header, HeaderMap, Method, Request, Response, StatusCode};
+use axum::response::IntoResponse;
+use axum::routing::post;
+use axum::Json;
+use distributed::graphql::{
+    AuthError, IdentityConfig, IdentityMode, IdentityResolver, DEFAULT_IDENTITY_STRIP_HEADERS,
+};
+use distributed::microsvc::{HandlerError, Service, Session};
+use futures_util::future::BoxFuture;
+use serde_json::{json, Value};
+use tower::{Layer, Service as TowerService};
+
+#[derive(Clone)]
+pub struct OidcIdentityLayer {
+    resolver: Arc<IdentityResolver>,
+}
+
+impl OidcIdentityLayer {
+    pub fn new(identity: IdentityConfig) -> Self {
+        Self {
+            resolver: Arc::new(IdentityResolver::new(identity)),
+        }
+    }
+}
+
+impl<S> Layer<S> for OidcIdentityLayer {
+    type Service = OidcIdentityService<S>;
+
+    fn layer(&self, inner: S) -> Self::Service {
+        OidcIdentityService {
+            inner,
+            resolver: Arc::clone(&self.resolver),
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct OidcIdentityService<S> {
+    inner: S,
+    resolver: Arc<IdentityResolver>,
+}
+
+fn skip_oidc_gate(method: &Method, path: &str) -> bool {
+    // Public probes + GraphiQL HTML + WS upgrade (auth on connection_init).
+    // Zitadel Action ingress uses shared-secret authenticity (not OIDC bearer).
+    matches!(
+        path,
+        "/health" | "/metrics" | "/graphql/ws" | "/zitadel.ingress.v1" | "/zitadel.scrape.v1"
+    ) || (path == "/graphql" && *method == Method::GET)
+}
+
+fn unauthorized_response() -> Response<Body> {
+    Response::builder()
+        .status(StatusCode::UNAUTHORIZED)
+        .header(header::CONTENT_TYPE, "application/json")
+        .body(Body::from(
+            r#"{"error":"unauthorized","extensions":{"code":"UNAUTHENTICATED"}}"#,
+        ))
+        .expect("401 response")
+}
+
+/// Strip client-supplied identity headers (same list as TrustedProxy defaults).
+fn strip_client_identity(headers: &mut HeaderMap) {
+    for name in DEFAULT_IDENTITY_STRIP_HEADERS {
+        headers.remove(*name);
+    }
+    // Also strip common casing variants axum may have normalized differently.
+    headers.remove("x-user-id");
+    headers.remove("x-role");
+    headers.remove("x-roles");
+}
+
+impl<S> TowerService<Request<Body>> for OidcIdentityService<S>
+where
+    S: TowerService<Request<Body>, Response = Response<Body>> + Clone + Send + 'static,
+    S::Future: Send + 'static,
+{
+    type Response = S::Response;
+    type Error = S::Error;
+    type Future = BoxFuture<'static, Result<Self::Response, Self::Error>>;
+
+    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
+        self.inner.poll_ready(cx)
+    }
+
+    fn call(&mut self, mut req: Request<Body>) -> Self::Future {
+        let mut inner = self.inner.clone();
+        let resolver = Arc::clone(&self.resolver);
+        Box::pin(async move {
+            let path = req.uri().path().to_string();
+            let method = req.method().clone();
+
+            if !matches!(
+                resolver.config().mode,
+                IdentityMode::OidcBearer | IdentityMode::Hybrid
+            ) {
+                // DevHeaders: ambient headers trusted only for local/offline.
+                return inner.call(req).await;
+            }
+
+            if skip_oidc_gate(&method, &path) {
+                return inner.call(req).await;
+            }
+
+            // Fail closed: never trust client identity headers under OidcBearer.
+            strip_client_identity(req.headers_mut());
+
+            match resolver.resolve_session(req.headers()).await {
+                Ok(session) => {
+                    if let Some(uid) = session.user_id() {
+                        if let Ok(v) = axum::http::HeaderValue::from_str(uid) {
+                            req.headers_mut().insert("x-user-id", v);
+                        }
+                    }
+                    if let Some(role) = session.role() {
+                        if let Ok(v) = axum::http::HeaderValue::from_str(role) {
+                            req.headers_mut().insert("x-role", v);
+                        }
+                    } else if session.user_id().is_some() {
+                        // Authenticated but no role claim → default user.
+                        req.headers_mut()
+                            .insert("x-role", axum::http::HeaderValue::from_static("user"));
+                    }
+                    inner.call(req).await
+                }
+                Err(AuthError::Unauthorized) => Ok(unauthorized_response()),
+            }
+        })
+    }
+}
+
+fn session_from_headers(headers: &HeaderMap) -> Session {
+    let mut vars = HashMap::new();
+    for (name, value) in headers.iter() {
+        if let Ok(v) = value.to_str() {
+            vars.insert(name.as_str().to_string(), v.to_string());
+        }
+    }
+    Session::from_map(vars)
+}
+
+fn status_for_error(error: &HandlerError) -> StatusCode {
+    match error {
+        HandlerError::UnknownCommand(_) | HandlerError::NotFound(_) => StatusCode::NOT_FOUND,
+        HandlerError::DecodeFailed(_) | HandlerError::GuardRejected(_) => StatusCode::BAD_REQUEST,
+        HandlerError::Rejected(_) => StatusCode::UNPROCESSABLE_ENTITY,
+        HandlerError::Unauthorized(_) => StatusCode::UNAUTHORIZED,
+        HandlerError::Repository(_) | HandlerError::Other(_) => StatusCode::INTERNAL_SERVER_ERROR,
+        // HandlerError is non_exhaustive.
+        _ => StatusCode::INTERNAL_SERVER_ERROR,
+    }
+}
+
+/// Dispatch a named HTTP command (Zitadel ingress/scrape only).
+async fn dispatch_named(
+    service: Arc<Service>,
+    headers: HeaderMap,
+    input: Value,
+    command: &'static str,
+) -> impl IntoResponse {
+    let session = session_from_headers(&headers);
+    match service.dispatch(command, input, session).await {
+        Ok(value) => (StatusCode::OK, Json(value)).into_response(),
+        Err(err) => {
+            let status = status_for_error(&err);
+            if status.is_server_error() {
+                eprintln!("microsvc command `{command}` failed: {err}");
+            }
+            let body = json!({ "error": err.client_facing_message() });
+            (status, Json(body)).into_response()
+        }
+    }
+}
+
+/// Serve with OIDC identity injection on all routes (commands + GraphQL).
+///
+/// App writes are GraphQL-only (`Service::without_http_command_routes`). Zitadel
+/// Action ingress still needs HTTP, so those two command names are mounted
+/// explicitly — `POST /todo.create` stays 404 (suite T0 / oidc_pg).
+///
+/// Note: `microsvc::router` already applies `.with_state(service)`, so handlers
+/// cannot use `State<Arc<Service>>`. Capture the `Arc` in the route closures.
+pub async fn serve_with_oidc(
+    service: Arc<Service>,
+    identity: IdentityConfig,
+    addr: &str,
+) -> Result<(), std::io::Error> {
+    let ingress = service.clone();
+    let scrape = service.clone();
+    let app = distributed::microsvc::router(service)
+        .route(
+            "/zitadel.ingress.v1",
+            post(move |headers: HeaderMap, Json(input): Json<Value>| {
+                let svc = ingress.clone();
+                async move { dispatch_named(svc, headers, input, "zitadel.ingress.v1").await }
+            }),
+        )
+        .route(
+            "/zitadel.scrape.v1",
+            post(move |headers: HeaderMap, Json(input): Json<Value>| {
+                let svc = scrape.clone();
+                async move { dispatch_named(svc, headers, input, "zitadel.scrape.v1").await }
+            }),
+        )
+        .layer(OidcIdentityLayer::new(identity));
+
+    let listener = tokio::net::TcpListener::bind(addr).await?;
+    axum::serve(listener, app).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn skip_gate_paths() {
+        assert!(skip_oidc_gate(&Method::GET, "/health"));
+        assert!(skip_oidc_gate(&Method::GET, "/graphql/ws"));
+        assert!(skip_oidc_gate(&Method::GET, "/graphql"));
+        assert!(!skip_oidc_gate(&Method::POST, "/graphql"));
+        // Zitadel Action ingress + scrape use shared secret, not OIDC bearer.
+        assert!(skip_oidc_gate(&Method::POST, "/zitadel.ingress.v1"));
+        assert!(skip_oidc_gate(&Method::POST, "/zitadel.scrape.v1"));
+        // Other HTTP command routes still require OIDC under OidcBearer.
+        assert!(!skip_oidc_gate(&Method::POST, "/todo.create"));
+        assert!(!skip_oidc_gate(&Method::POST, "/graphql"));
+    }
+
+    #[test]
+    fn strip_removes_spoof_headers() {
+        let mut h = HeaderMap::new();
+        h.insert("x-user-id", "attacker".parse().unwrap());
+        h.insert("x-role", "admin".parse().unwrap());
+        h.insert("authorization", "Bearer tok".parse().unwrap());
+        strip_client_identity(&mut h);
+        assert!(!h.contains_key("x-user-id"));
+        assert!(!h.contains_key("x-role"));
+        // Authorization must survive for resolve_session
+        assert!(h.contains_key("authorization"));
+    }
+}
diff --git a/tests/e2e-ui/crates/service/src/service.rs b/tests/e2e-ui/crates/service/src/service.rs
new file mode 100644
index 00000000..bc459a41
--- /dev/null
+++ b/tests/e2e-ui/crates/service/src/service.rs
@@ -0,0 +1,654 @@
+//! Route bundles + GraphQL engine for the e2e-ui fixture.
+
+use std::collections::BTreeMap;
+use std::sync::Arc;
+
+use blob_domain::BlobGame;
+use chat_domain::ChatMessage;
+use distributed::graphql::{
+    build_surface, read, surface_for_application, typed_command, DistributedClientSurfaceExport,
+    Fact, GraphqlEngine, GraphqlPoolSource, IdentityConfig, ModelPermissions, OidcConfig,
+    Projected, RoleGrant, SurfaceDirectProjection, SurfaceOptions, SurfaceProjector,
+};
+use distributed::microsvc::{
+    ConfigurableOutboxPublisher, HasOutboxStore, HasRepo, Routes, Service,
+};
+use distributed::{
+    command_confirmations, command_effects, command_input_defaults, AggregateBuilder,
+    AggregateRepository, InMemoryLockManager, InMemoryRepository, LockError, LockManager,
+    Queueable, QueuedRepository,
+};
+use e2e_readmodels::{AuthUserView, BlobGameView, ChatMessageView, TodoView};
+use todo_domain::Todo;
+
+use crate::bounds::{EventStore, Locks, ReadStore};
+use crate::handlers;
+
+// Stable only for this local copyable fixture. Real deployments must inject
+// their own per-deployment key rather than copying this development value.
+const E2E_PROTOCOL_TOKEN_KEY: [u8; 32] = [0xe2; 32];
+
+/// Stable normal-application surface shared by user and admin sessions.
+pub const DISTRIBUTED_CLIENT_SURFACE: &str = "e2e-ui";
+/// Stable elevated surface for routes that intentionally include admin-only fields.
+pub const DISTRIBUTED_ADMIN_CLIENT_SURFACE: &str = "e2e-ui-admin";
+
+#[derive(Clone, Default)]
+struct ClientSurfaceLocks(Arc<InMemoryLockManager>);
+
+impl LockManager for ClientSurfaceLocks {
+    type Lock = distributed::InMemoryLock;
+
+    fn get_lock(&self, id: &str) -> Result<Arc<Self::Lock>, LockError> {
+        self.0.get_lock(id)
+    }
+}
+
+fn todo_projector() -> SurfaceProjector {
+    SurfaceProjector::new("project_todo")
+        .facts(handlers::events::project_todo::EVENTS.iter().copied())
+        .models(["TodoView"])
+        .change_epoch("e2e-ui-todos-v1")
+}
+
+fn chat_projector() -> SurfaceProjector {
+    SurfaceProjector::new("project_chat")
+        .facts([handlers::events::project_chat::EVENT])
+        .models(["ChatMessageView"])
+        .change_epoch("e2e-ui-chat-v1")
+}
+
+fn blob_projection() -> SurfaceDirectProjection {
+    SurfaceDirectProjection::new("project_blob")
+        .model::<BlobGameView>()
+        .change_epoch("e2e-ui-blob-v1")
+}
+
+fn client_grants() -> BTreeMap<String, BTreeMap<String, RoleGrant>> {
+    let all_models = || {
+        BTreeMap::from([
+            ("AuthUserView".into(), RoleGrant::all_columns()),
+            ("BlobGameView".into(), RoleGrant::all_columns()),
+            ("ChatMessageView".into(), RoleGrant::all_columns()),
+            ("TodoView".into(), RoleGrant::all_columns()),
+        ])
+    };
+    let mut user = all_models();
+    user.insert(
+        "TodoView".into(),
+        RoleGrant::all_columns().rows(
+            distributed::graphql::col("owner_id").eq(distributed::graphql::claim("x-user-id")),
+        ),
+    );
+    user.insert(
+        "BlobGameView".into(),
+        RoleGrant::all_columns().rows(
+            distributed::graphql::col("owner_id").eq(distributed::graphql::claim("x-user-id")),
+        ),
+    );
+    BTreeMap::from([("user".into(), user), ("admin".into(), all_models())])
+}
+
+fn pool_free_client_surface(application: &str, roles: &[&str]) -> DistributedClientSurfaceExport {
+    let project = e2e_readmodels::distributed_manifest();
+    let repository = InMemoryRepository::new();
+    let service = build_service(
+        repository.clone(),
+        ClientSurfaceLocks::default(),
+        repository,
+    );
+    let full = build_surface(&project.tables, &SurfaceOptions::sqlite())
+        .expect("e2e-ui client Surface should build")
+        .with_service(&service)
+        .expect("e2e-ui typed Service inventory should bind")
+        .with_projection_owners([
+            todo_projector().into(),
+            chat_projector().into(),
+            blob_projection().into(),
+        ])
+        .expect("e2e-ui projector topology should bind");
+    let roles = roles
+        .iter()
+        .map(|role| (*role).to_string())
+        .collect::<Vec<_>>();
+    let selected = surface_for_application(&full, application, &roles, &client_grants())
+        .expect("e2e-ui application Surface should select");
+    DistributedClientSurfaceExport::from_project(&project, selected)
+        .expect("e2e-ui application Surface should export")
+}
+
+/// Pool-free normal application export consumed by `dctl client-manifest`.
+///
+/// Includes both `user` and `admin`: an admin is still a person using todos/
+/// chat/blob. Elevated-only ops stay on [`distributed_admin_client_surface`].
+/// Differing row policies (owner vs all) become `ServerOnly` on the shared
+/// surface so the server re-checks membership per concrete role.
+pub fn distributed_client_surface() -> DistributedClientSurfaceExport {
+    pool_free_client_surface(DISTRIBUTED_CLIENT_SURFACE, &["admin", "user"])
+}
+
+/// Pool-free elevated application export for admin-only routes.
+pub fn distributed_admin_client_surface() -> DistributedClientSurfaceExport {
+    pool_free_client_surface(DISTRIBUTED_ADMIN_CLIENT_SURFACE, &["admin"])
+}
+
+/// Full service: todo + chat commands and projectors.
+pub fn build_service<R, L, S>(repo: R, locks: L, read_models: S) -> Service
+where
+    R: EventStore,
+    L: Locks,
+    S: ReadStore,
+    QueuedRepository<R, L>: Clone
+        + AggregateBuilder
+        + HasOutboxStore
+        + distributed::TransactionalCommit
+        + Send
+        + Sync
+        + 'static,
+    AggregateRepository<QueuedRepository<R, L>, Todo>:
+        HasRepo + HasOutboxStore + ConfigurableOutboxPublisher + Send + Sync + 'static,
+    AggregateRepository<QueuedRepository<R, L>, ChatMessage>:
+        HasRepo + HasOutboxStore + ConfigurableOutboxPublisher + Send + Sync + 'static,
+    AggregateRepository<QueuedRepository<R, L>, BlobGame>:
+        HasRepo + HasOutboxStore + ConfigurableOutboxPublisher + Send + Sync + 'static,
+{
+    use handlers::commands::{
+        archive, blob_move, blob_start, blob_start_level, chat_post, complete, create,
+        force_archive, payloads, rename, reopen,
+    };
+
+    let app_roles = ["user", "admin"];
+    let todo_projection = todo_projector();
+    let todos = Routes::new()
+        .with_repo(repo.clone().queued_with(locks.clone()).aggregate::<Todo>())
+        .with_read_model_store(read_models.clone())
+        .typed_command(
+            typed_command::<create::TodoCreateInput, Fact<create::TodoCreatePayload>>(
+                create::COMMAND,
+            )
+            .field_name("todos_create")
+            .roles(app_roles)
+            .input_defaults(command_input_defaults! {
+                input: create::TodoCreateInput;
+                default input.todo_id = uuid_v7();
+            })
+            .effects(command_effects! {
+                input: create::TodoCreateInput;
+                upsert e2e_readmodels::models::todo_view::TodoView {
+                    key { todo_id: input.todo_id },
+                    set {
+                        owner_id: trusted("x-user-id"),
+                        title: input.title,
+                        status: "open"
+                    }
+                };
+            })
+            .confirmations(command_confirmations! {
+                input: create::TodoCreateInput;
+                confirm todo_projection -> e2e_readmodels::models::todo_view::TodoView {
+                    key { todo_id: input.todo_id }
+                };
+            }),
+        )
+        .handle(create::handle)
+        .typed_command(
+            typed_command::<rename::TodoRenameInput, Fact<rename::TodoRenamePayload>>(
+                rename::COMMAND,
+            )
+            .field_name("todos_rename")
+            .roles(app_roles)
+            .effects(command_effects! {
+                input: rename::TodoRenameInput;
+                patch e2e_readmodels::models::todo_view::TodoView {
+                    key { todo_id: input.todo_id },
+                    set { title: input.title }
+                };
+            })
+            .confirmations(command_confirmations! {
+                input: rename::TodoRenameInput;
+                confirm todo_projection -> e2e_readmodels::models::todo_view::TodoView {
+                    key { todo_id: input.todo_id }
+                };
+            }),
+        )
+        .handle(rename::handle)
+        .typed_command(
+            typed_command::<complete::TodoCompleteInput, Fact<payloads::TodoStatusPayload>>(
+                complete::COMMAND,
+            )
+            .field_name("todos_complete")
+            .roles(app_roles)
+            .effects(command_effects! {
+                input: complete::TodoCompleteInput;
+                patch e2e_readmodels::models::todo_view::TodoView {
+                    key { todo_id: input.todo_id },
+                    set { status: "completed" }
+                };
+            })
+            .confirmations(command_confirmations! {
+                input: complete::TodoCompleteInput;
+                confirm todo_projection -> e2e_readmodels::models::todo_view::TodoView {
+                    key { todo_id: input.todo_id }
+                };
+            }),
+        )
+        .handle(complete::handle)
+        .typed_command(
+            typed_command::<reopen::TodoReopenInput, Fact<reopen::TodoReopenPayload>>(
+                reopen::COMMAND,
+            )
+            .field_name("todos_reopen")
+            .roles(app_roles)
+            .effects(command_effects! {
+                input: reopen::TodoReopenInput;
+                patch e2e_readmodels::models::todo_view::TodoView {
+                    key { todo_id: input.todo_id },
+                    set { status: "open" }
+                };
+            })
+            .confirmations(command_confirmations! {
+                input: reopen::TodoReopenInput;
+                confirm todo_projection -> e2e_readmodels::models::todo_view::TodoView {
+                    key { todo_id: input.todo_id }
+                };
+            }),
+        )
+        .handle(reopen::handle)
+        .typed_command(
+            typed_command::<archive::TodoArchiveInput, Fact<archive::TodoArchivePayload>>(
+                archive::COMMAND,
+            )
+            .field_name("todos_archive")
+            .roles(app_roles)
+            .effects(command_effects! {
+                input: archive::TodoArchiveInput;
+                patch e2e_readmodels::models::todo_view::TodoView {
+                    key { todo_id: input.todo_id },
+                    set { status: "archived" }
+                };
+            })
+            .confirmations(command_confirmations! {
+                input: archive::TodoArchiveInput;
+                confirm todo_projection -> e2e_readmodels::models::todo_view::TodoView {
+                    key { todo_id: input.todo_id }
+                };
+            }),
+        )
+        .handle(archive::handle)
+        .typed_command(
+            typed_command::<
+                force_archive::TodoForceArchiveInput,
+                Fact<force_archive::TodoForceArchivePayload>,
+            >(force_archive::COMMAND)
+            .field_name("todos_force_archive")
+            .roles(["admin"])
+            .effects(command_effects! {
+                input: force_archive::TodoForceArchiveInput;
+                patch e2e_readmodels::models::todo_view::TodoView {
+                    key { todo_id: input.todo_id },
+                    set { status: "archived" }
+                };
+            })
+            .confirmations(command_confirmations! {
+                input: force_archive::TodoForceArchiveInput;
+                confirm todo_projection -> e2e_readmodels::models::todo_view::TodoView {
+                    key { todo_id: input.todo_id }
+                };
+            }),
+        )
+        .handle(force_archive::handle)
+        .causal_projector::<todo_domain::TodoFact>(todo_projection)
+        .model::<TodoView>()
+        .handle(handlers::events::project_todo::handle);
+
+    let chat_projection = chat_projector();
+    let chat = Routes::new()
+        .with_repo(
+            repo.clone()
+                .queued_with(locks.clone())
+                .aggregate::<ChatMessage>(),
+        )
+        .with_read_model_store(read_models.clone())
+        .typed_command(
+            typed_command::<chat_post::ChatPostInput, Fact<chat_post::ChatPostPayload>>(
+                chat_post::COMMAND,
+            )
+            .field_name("chat_messages_post")
+            .roles(app_roles)
+            .effects(command_effects! {
+                input: chat_post::ChatPostInput;
+                upsert e2e_readmodels::models::chat_message_view::ChatMessageView {
+                    key { message_id: input.message_id },
+                    set {
+                        room_id: input.room_id,
+                        author_id: trusted("x-user-id"),
+                        body: input.body,
+                        created_at: input.created_at
+                    }
+                };
+            })
+            .confirmations(command_confirmations! {
+                input: chat_post::ChatPostInput;
+                confirm chat_projection -> e2e_readmodels::models::chat_message_view::ChatMessageView {
+                    key { message_id: input.message_id }
+                };
+            }),
+        )
+        .handle(chat_post::handle)
+        // Zitadel Action ingress + on-demand scrape remain non-GraphQL
+        // integration commands.
+        .command(handlers::ingestors::zitadel::COMMAND)
+        .guarded(
+            handlers::ingestors::zitadel::guard,
+            handlers::ingestors::zitadel::handle,
+        )
+        .command(handlers::ingestors::zitadel_scrape::COMMAND)
+        .guarded(
+            handlers::ingestors::zitadel_scrape::guard,
+            handlers::ingestors::zitadel_scrape::handle,
+        )
+        .causal_projector::<chat_domain::ChatMessagePosted>(chat_projection)
+        .model::<ChatMessageView>()
+        .handle(handlers::events::project_chat::handle)
+        .events(handlers::events::project_auth_user::EVENTS)
+        .guarded(
+            handlers::events::project_auth_user::guard,
+            handlers::events::project_auth_user::handle,
+        );
+
+    let blob = Routes::new()
+        .with_repo(repo.queued_with(locks).aggregate::<BlobGame>())
+        .with_read_model_store(read_models)
+        .typed_command(
+            typed_command::<blob_start::BlobStartInput, Projected<BlobGameView>>(
+                blob_start::COMMAND,
+            )
+            .field_name("blob_games_start")
+            .roles(app_roles),
+        )
+        .handle(blob_start::handle)
+        .typed_command(
+            typed_command::<blob_move::BlobMoveInput, Projected<BlobGameView>>(blob_move::COMMAND)
+                .field_name("blob_games_move")
+                .roles(app_roles),
+        )
+        .handle(blob_move::handle)
+        .typed_command(
+            typed_command::<blob_start_level::BlobStartLevelInput, Projected<BlobGameView>>(
+                blob_start_level::COMMAND,
+            )
+            .field_name("blob_games_start_level")
+            .roles(app_roles),
+        )
+        .handle(blob_start_level::handle);
+
+    // GraphQL-only public write surface (POST /todo.* must 404 — suite T0 / oidc_pg).
+    // Zitadel Action ingress still needs HTTP: those commands are registered above and
+    // re-mounted explicitly in `serve_with_oidc` when HTTP command wildcards are off.
+    Service::new()
+        .named("e2e-ui")
+        .without_http_command_routes()
+        .routes(todos)
+        .routes(chat)
+        .routes(blob)
+}
+
+/// GraphQL over todos (owner-scoped) + chat_messages (shared room, live subscriptions).
+///
+/// All write paths are **command mutations** (not read-model writes). Owner/author is
+/// always the authenticated session principal. Roles: user, admin.
+///
+/// Works with SQLite or Postgres pools through [`GraphqlPoolSource`].
+pub fn build_graphql_engine(
+    pool: impl Into<GraphqlPoolSource>,
+    service: &Service,
+    identity: IdentityConfig,
+    change_rx: Option<tokio::sync::broadcast::Receiver<distributed::ReadModelChange>>,
+) -> Result<GraphqlEngine, String> {
+    build_graphql_engine_with_graphiql(pool, service, identity, change_rx, graphiql_enabled())
+}
+
+fn build_graphql_engine_with_graphiql(
+    pool: impl Into<GraphqlPoolSource>,
+    service: &Service,
+    identity: IdentityConfig,
+    change_rx: Option<tokio::sync::broadcast::Receiver<distributed::ReadModelChange>>,
+    graphiql: bool,
+) -> Result<GraphqlEngine, String> {
+    let mut b = GraphqlEngine::builder(pool)
+        .protocol_token_key(E2E_PROTOCOL_TOKEN_KEY)
+        .roles(&["user", "admin"])
+        // e2e-ui: everyone who can sign in (admin is a superset of user).
+        // e2e-ui-admin: elevated ops only (/admin).
+        .client_application_surface(DISTRIBUTED_CLIENT_SURFACE, ["admin", "user"])
+        .client_application_surface(DISTRIBUTED_ADMIN_CLIENT_SURFACE, ["admin"])
+        // user: only own rows. admin: all owners (UI: /admin all-notes view).
+        .model::<TodoView>(
+            ModelPermissions::new()
+                .grant(
+                    "user",
+                    read().all_columns().rows(
+                        distributed::graphql::col("owner_id")
+                            .eq(distributed::graphql::claim("x-user-id")),
+                    ),
+                )
+                .grant("admin", read().all_columns()),
+        )
+        .model::<ChatMessageView>(
+            ModelPermissions::new()
+                .grant("user", read().all_columns())
+                .grant("admin", read().all_columns()),
+        )
+        .model::<BlobGameView>(
+            ModelPermissions::new()
+                .grant(
+                    "user",
+                    read().all_columns().rows(
+                        distributed::graphql::col("owner_id")
+                            .eq(distributed::graphql::claim("x-user-id")),
+                    ),
+                )
+                .grant("admin", read().all_columns()),
+        )
+        // Imported IdP directory (join target for chat.author / blob.owner).
+        // Readable by all authenticated roles; writes only via Zitadel projector.
+        .model::<AuthUserView>(
+            ModelPermissions::new()
+                .grant("user", read().all_columns())
+                .grant("admin", read().all_columns()),
+        )
+        .service(service)
+        .client_projection_owners([
+            todo_projector().into(),
+            chat_projector().into(),
+            blob_projection().into(),
+        ])
+        .identity(identity)
+        // GraphiQL is a local template convenience. Disable with GRAPHIQL=0
+        // (never ship a public edge with GraphiQL + DevHeaders).
+        .graphiql(graphiql);
+    if let Some(rx) = change_rx {
+        b = b.change_stream(rx);
+    }
+    b.build().map_err(|e| e.to_string())
+}
+
+pub fn dev_identity() -> IdentityConfig {
+    IdentityConfig::dev_headers()
+}
+
+/// GraphiQL IDE: on by default for the fixture; set `GRAPHIQL=0` to disable.
+pub fn graphiql_enabled() -> bool {
+    match std::env::var("GRAPHIQL") {
+        Ok(v) => {
+            let v = v.trim();
+            !(v == "0" || v.eq_ignore_ascii_case("false") || v.eq_ignore_ascii_case("off"))
+        }
+        Err(_) => true,
+    }
+}
+
+/// Peel accidental outer quotes from env values (Make-include / double-wrap pollution).
+fn env_clean(name: &str) -> String {
+    let mut s = std::env::var(name).unwrap_or_default().trim().to_string();
+    for _ in 0..2 {
+        if s.len() >= 2
+            && ((s.starts_with('\'') && s.ends_with('\''))
+                || (s.starts_with('"') && s.ends_with('"')))
+        {
+            s = s[1..s.len() - 1].trim().to_string();
+        } else {
+            break;
+        }
+    }
+    s
+}
+
+/// Prefer OidcBearer when `OIDC_ISSUER` + `OIDC_AUDIENCE` are set; else DevHeaders.
+pub fn identity_from_env() -> IdentityConfig {
+    let iss = env_clean("OIDC_ISSUER");
+    let aud = env_clean("OIDC_AUDIENCE");
+    if iss.is_empty() || aud.is_empty() {
+        eprintln!("e2e-ui: OIDC_* unset — using DevHeaders (local only)");
+        return dev_identity();
+    }
+    let jwks = env_clean("OIDC_JWKS_URI");
+    eprintln!("e2e-ui: OidcBearer issuer={iss} audience={aud}");
+    oidc_bearer_config(
+        iss,
+        aud,
+        if jwks.is_empty() { None } else { Some(jwks) },
+        None,
+    )
+}
+
+pub fn oidc_bearer_config(
+    issuer: impl Into<String>,
+    audience: impl Into<String>,
+    jwks_uri: Option<String>,
+    static_jwks: Option<String>,
+) -> IdentityConfig {
+    let mut oidc = OidcConfig::new(issuer, audience);
+    if let Some(uri) = jwks_uri.filter(|s| !s.is_empty()) {
+        oidc.jwks_uri = Some(uri);
+    }
+    if let Some(jwks) = static_jwks {
+        oidc = oidc.with_static_jwks(jwks);
+    }
+    // Accept client_id as extra audience when present (human OIDC access tokens).
+    let cid = env_clean("OIDC_CLIENT_ID");
+    if !cid.is_empty() {
+        oidc.extra_audiences = vec![cid];
+    }
+    oidc.claim_map.engine_roles = vec!["user".into(), "admin".into()];
+    oidc.claim_map.role_claims = vec![
+        "groups".into(),
+        "roles".into(),
+        "realm_access.roles".into(),
+        "urn:zitadel:iam:org:project:roles".into(),
+    ];
+    IdentityConfig::oidc_bearer(oidc)
+}
+
+#[cfg(test)]
+mod client_surface_tests {
+    use super::*;
+
+    #[test]
+    fn pool_free_user_and_admin_exports_compile_real_manifests() {
+        distributed_client_surface()
+            .manifest()
+            .expect("normal application client manifest");
+        distributed_admin_client_surface()
+            .manifest()
+            .expect("elevated application client manifest");
+    }
+
+    #[test]
+    fn blob_projection_owner_has_no_async_fact_route() {
+        let manifest = distributed_client_surface().manifest().unwrap();
+        let owner = manifest
+            .projectors
+            .iter()
+            .find(|projector| projector.name == "project_blob")
+            .expect("Blob direct owner should be exported");
+        assert!(owner.facts.is_empty());
+        assert!(!owner.causal_confirmation);
+
+        let repository = InMemoryRepository::new();
+        let service = build_service(
+            repository.clone(),
+            ClientSurfaceLocks::default(),
+            repository,
+        );
+        let plan = service.subscription_plan();
+        for fact in [
+            "blob.started",
+            "blob.initialized",
+            "blob.level_started",
+            "blob.moved",
+        ] {
+            assert!(
+                !plan.events.iter().any(|event| event == fact),
+                "direct-only Blob ownership must not register an async route for {fact}"
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn graphiql_does_not_change_the_postgres_runtime_client_manifest() {
+        let generated = distributed_client_surface().manifest().unwrap();
+        let pool = sqlx::postgres::PgPoolOptions::new()
+            .connect_lazy("postgres://postgres:postgres@localhost/distributed")
+            .unwrap();
+        let repository = distributed::PostgresRepository::new(pool.clone());
+        let service = build_service(
+            repository.clone(),
+            distributed::PostgresLockManager::new(pool),
+            repository.clone(),
+        );
+        let engine =
+            build_graphql_engine_with_graphiql(&repository, &service, dev_identity(), None, true)
+                .expect("engine");
+        let runtime = engine
+            .client_manifest_for_application(DISTRIBUTED_CLIENT_SURFACE, &["user"])
+            .unwrap();
+
+        assert_eq!(generated, runtime);
+
+        let request = serde_json::from_value(serde_json::json!({
+            "query": "{ todos @skip(if: true) { todo_id } }",
+            "extensions": {
+                "distributed": {
+                    "client": {
+                        "surface": {
+                            "kind": "application",
+                            "name": DISTRIBUTED_CLIENT_SURFACE,
+                            "roles": ["user"]
+                        },
+                        "schemaHash": generated.schema_fingerprint
+                    }
+                }
+            }
+        }))
+        .expect("generated application request");
+        let mut session = distributed::microsvc::Session::new();
+        session.set("x-role", "user");
+        session.set("x-user-id", "person-1");
+        let response = engine.execute(&session, request).await;
+        assert!(
+            !response.is_err(),
+            "the runtime must accept the generated application surface: {:?}",
+            response.errors
+        );
+        let envelope = response
+            .extensions
+            .get("distributed")
+            .expect("distributed protocol envelope");
+        let envelope = serde_json::to_value(envelope).expect("serialized protocol envelope");
+        assert_eq!(
+            envelope["schemaHash"], generated.schema_fingerprint,
+            "the authoritative response must attest the generated schema"
+        );
+    }
+}
diff --git a/tests/e2e-ui/crates/suite/Cargo.toml b/tests/e2e-ui/crates/suite/Cargo.toml
new file mode 100644
index 00000000..be9fb8b6
--- /dev/null
+++ b/tests/e2e-ui/crates/suite/Cargo.toml
@@ -0,0 +1,33 @@
+[package]
+name = "e2e-suite"
+version.workspace = true
+edition.workspace = true
+publish = false
+description = "HTTP/GraphQL behavioral suite for e2e-ui"
+
+[[test]]
+name = "behavioral"
+path = "tests/behavioral.rs"
+
+[[test]]
+name = "oidc_pg"
+path = "tests/oidc_pg.rs"
+
+[dependencies]
+distributed = { workspace = true }
+e2e-service = { path = "../service" }
+e2e-readmodels = { path = "../readmodels" }
+todo-domain = { path = "../todo-domain" }
+tokio = { workspace = true }
+serde_json = { workspace = true }
+reqwest = { workspace = true }
+sqlx = { workspace = true }
+uuid = { workspace = true }
+jsonwebtoken = { workspace = true }
+
+[dev-dependencies]
+distributed = { workspace = true }
+e2e-service = { path = "../service" }
+tokio = { workspace = true }
+serde_json = { workspace = true }
+reqwest = { workspace = true }
diff --git a/tests/e2e-ui/crates/suite/src/lib.rs b/tests/e2e-ui/crates/suite/src/lib.rs
new file mode 100644
index 00000000..76e27e22
--- /dev/null
+++ b/tests/e2e-ui/crates/suite/src/lib.rs
@@ -0,0 +1,318 @@
+//! Shared helpers for the e2e-ui suite — GraphQL-only public API.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use jsonwebtoken::{encode, Algorithm, EncodingKey, Header};
+use serde_json::{json, Value};
+
+const OFFLINE_ISSUER: &str = "https://offline-oidc.e2e.invalid";
+const OFFLINE_AUDIENCE: &str = "e2e-ui-offline";
+const OFFLINE_KID: &str = "e2e-ui-offline-es256";
+const OFFLINE_ES256_PRIVATE_KEY: &str = r#"-----BEGIN PRIVATE KEY-----
+MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgWTFfCGljY6aw3Hrt
+kHmPRiazukxPLb6ilpRAewjW8nihRANCAATDskChT+Altkm9X7MI69T3IUmrQU0L
+950IxEzvw/x5BMEINRMrXLBJhqzO9Bm+d6JbqA21YQmd1Kt4RzLJR1W+
+-----END PRIVATE KEY-----"#;
+const OFFLINE_ES256_X: &str = "w7JAoU_gJbZJvV-zCOvU9yFJq0FNC_edCMRM78P8eQQ";
+const OFFLINE_ES256_Y: &str = "wQg1EytcsEmGrM70Gb53oluoDbVhCZ3Uq3hHMslHVb4";
+
+static OFFLINE_OIDC_ENABLED: AtomicBool = AtomicBool::new(false);
+
+/// Configure the in-process suite with a real signature-verified OIDC identity.
+///
+/// Durable commands intentionally reject DevHeaders. This fixture preserves
+/// that production fence while keeping the SQLite behavioral suite offline.
+pub fn offline_oidc_identity() -> distributed::graphql::IdentityConfig {
+    OFFLINE_OIDC_ENABLED.store(true, Ordering::Release);
+    let jwks = json!({
+        "keys": [{
+            "kty": "EC",
+            "kid": OFFLINE_KID,
+            "alg": "ES256",
+            "use": "sig",
+            "crv": "P-256",
+            "x": OFFLINE_ES256_X,
+            "y": OFFLINE_ES256_Y
+        }]
+    })
+    .to_string();
+    e2e_service::oidc_bearer_config(OFFLINE_ISSUER, OFFLINE_AUDIENCE, None, Some(jwks))
+}
+
+fn offline_bearer(subject: &str, role: &str) -> String {
+    let now = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .expect("system clock")
+        .as_secs();
+    let claims = json!({
+        "iss": OFFLINE_ISSUER,
+        "aud": OFFLINE_AUDIENCE,
+        "sub": subject,
+        "iat": now.saturating_sub(1),
+        "nbf": now.saturating_sub(1),
+        "exp": now + 3600,
+        "roles": [role]
+    });
+    let mut header = Header::new(Algorithm::ES256);
+    header.kid = Some(OFFLINE_KID.to_string());
+    let key =
+        EncodingKey::from_ec_pem(OFFLINE_ES256_PRIVATE_KEY.as_bytes()).expect("offline EC key");
+    encode(&header, &claims, &key).expect("sign offline access token")
+}
+
+fn with_identity(
+    request: reqwest::RequestBuilder,
+    user_id: &str,
+    role: &str,
+) -> reqwest::RequestBuilder {
+    if OFFLINE_OIDC_ENABLED.load(Ordering::Acquire) {
+        request.bearer_auth(offline_bearer(user_id, role))
+    } else {
+        request.header("x-user-id", user_id).header("x-role", role)
+    }
+}
+
+pub fn new_command_id() -> String {
+    uuid::Uuid::now_v7().hyphenated().to_string()
+}
+
+pub fn base_url() -> String {
+    std::env::var("E2E_BASE_URL").unwrap_or_else(|_| "http://127.0.0.1:8791".into())
+}
+
+pub async fn wait_ready(base: &str, timeout: Duration) -> bool {
+    let client = reqwest::Client::new();
+    let start = std::time::Instant::now();
+    while start.elapsed() < timeout {
+        let req = with_identity(
+            client
+                .post(format!("{base}/graphql"))
+                .header("content-type", "application/json"),
+            "probe",
+            "admin",
+        )
+        .json(&json!({"query":"{ __typename }"}));
+        if let Ok(resp) = req.send().await {
+            if resp.status().as_u16() < 500 {
+                return true;
+            }
+        }
+        tokio::time::sleep(Duration::from_millis(50)).await;
+    }
+    false
+}
+
+pub async fn graphql(base: &str, query: &str, user_id: &str, role: &str) -> Result<Value, String> {
+    let client = reqwest::Client::builder()
+        .timeout(Duration::from_secs(10))
+        .build()
+        .map_err(|e| e.to_string())?;
+    let resp = with_identity(
+        client
+            .post(format!("{base}/graphql"))
+            .header("content-type", "application/json"),
+        user_id,
+        role,
+    )
+    .json(&json!({ "query": query }))
+    .send()
+    .await
+    .map_err(|e| e.to_string())?;
+    let status = resp.status();
+    let v: Value = resp.json().await.map_err(|e| e.to_string())?;
+    if !status.is_success() {
+        return Err(format!("graphql HTTP {status}: {v}"));
+    }
+    Ok(v)
+}
+
+/// GraphQL document without identity headers (unauthenticated probe).
+pub async fn graphql_raw(base: &str, query: &str) -> Result<(u16, Value), String> {
+    let client = reqwest::Client::new();
+    let resp = client
+        .post(format!("{base}/graphql"))
+        .header("content-type", "application/json")
+        .json(&json!({ "query": query }))
+        .send()
+        .await
+        .map_err(|e| e.to_string())?;
+    let status = resp.status().as_u16();
+    let v: Value = resp.json().await.unwrap_or(json!({}));
+    Ok((status, v))
+}
+
+fn gql_errors(v: &Value) -> Option<String> {
+    let errs = v.get("errors")?.as_array()?;
+    if errs.is_empty() {
+        return None;
+    }
+    Some(
+        errs.iter()
+            .map(|e| e.to_string())
+            .collect::<Vec<_>>()
+            .join("; "),
+    )
+}
+
+/// Run a mutation and return `data.<field>` or Err with GraphQL errors.
+pub async fn mutate(
+    base: &str,
+    field: &str,
+    document: &str,
+    user_id: &str,
+    role: &str,
+) -> Result<Value, String> {
+    let v = graphql(base, document, user_id, role).await?;
+    if let Some(msg) = gql_errors(&v) {
+        return Err(format!("{field} errors: {msg}"));
+    }
+    v["data"][field]
+        .as_object()
+        .cloned()
+        .map(Value::Object)
+        .ok_or_else(|| format!("{field} missing data: {v}"))
+}
+
+pub async fn todos_create(
+    base: &str,
+    todo_id: &str,
+    title: &str,
+    user_id: &str,
+    role: &str,
+) -> Result<Value, String> {
+    let command_id = new_command_id();
+    let doc = format!(
+        r#"mutation {{
+          todos_create(commandId: "{command_id}", input: {{ todo_id: "{todo_id}", title: "{title}" }}) {{
+            todo_id owner_id title status
+          }}
+        }}"#
+    );
+    mutate(base, "todos_create", &doc, user_id, role).await
+}
+
+pub async fn todos_complete(
+    base: &str,
+    todo_id: &str,
+    user_id: &str,
+    role: &str,
+) -> Result<Value, String> {
+    let command_id = new_command_id();
+    let doc = format!(
+        r#"mutation {{
+          todos_complete(commandId: "{command_id}", input: {{ todo_id: "{todo_id}" }}) {{
+            todo_id status
+          }}
+        }}"#
+    );
+    mutate(base, "todos_complete", &doc, user_id, role).await
+}
+
+pub async fn todos_archive(
+    base: &str,
+    todo_id: &str,
+    user_id: &str,
+    role: &str,
+) -> Result<Value, String> {
+    let command_id = new_command_id();
+    let doc = format!(
+        r#"mutation {{
+          todos_archive(commandId: "{command_id}", input: {{ todo_id: "{todo_id}" }}) {{
+            todo_id status
+          }}
+        }}"#
+    );
+    mutate(base, "todos_archive", &doc, user_id, role).await
+}
+
+/// Admin-only mutation (not present on the user role schema).
+pub async fn todos_force_archive(
+    base: &str,
+    todo_id: &str,
+    user_id: &str,
+    role: &str,
+) -> Result<Value, String> {
+    let command_id = new_command_id();
+    let doc = format!(
+        r#"mutation {{
+          todos_force_archive(commandId: "{command_id}", input: {{ todo_id: "{todo_id}" }}) {{
+            todo_id owner_id status archived_by
+          }}
+        }}"#
+    );
+    mutate(base, "todos_force_archive", &doc, user_id, role).await
+}
+
+pub async fn todos_rename(
+    base: &str,
+    todo_id: &str,
+    title: &str,
+    user_id: &str,
+    role: &str,
+) -> Result<Value, String> {
+    let command_id = new_command_id();
+    let doc = format!(
+        r#"mutation {{
+          todos_rename(commandId: "{command_id}", input: {{ todo_id: "{todo_id}", title: "{title}" }}) {{
+            todo_id title status
+          }}
+        }}"#
+    );
+    mutate(base, "todos_rename", &doc, user_id, role).await
+}
+
+pub async fn todos_reopen(
+    base: &str,
+    todo_id: &str,
+    user_id: &str,
+    role: &str,
+) -> Result<Value, String> {
+    let command_id = new_command_id();
+    let doc = format!(
+        r#"mutation {{
+          todos_reopen(commandId: "{command_id}", input: {{ todo_id: "{todo_id}" }}) {{
+            todo_id status
+          }}
+        }}"#
+    );
+    mutate(base, "todos_reopen", &doc, user_id, role).await
+}
+
+/// Assert HTTP command routes are not mounted (GraphQL-only surface).
+pub async fn assert_http_commands_disabled(base: &str) -> Result<(), String> {
+    let client = reqwest::Client::new();
+    let resp = client
+        .post(format!("{base}/todo.create"))
+        .header("content-type", "application/json")
+        .header("x-user-id", "alice")
+        .header("x-role", "user")
+        .json(&json!({ "todo_id": "t-should-404", "title": "nope" }))
+        .send()
+        .await
+        .map_err(|e| e.to_string())?;
+    let status = resp.status().as_u16();
+    // No route → 404 (or 405 if something else matches).
+    if status != 404 && status != 405 {
+        return Err(format!(
+            "expected HTTP command route disabled (404/405), got {status}"
+        ));
+    }
+    Ok(())
+}
+
+pub mod cases {
+    pub const CREATE: &str = "T1_create_todo";
+    pub const OWNER_ISOLATION: &str = "T2_owner_isolation";
+    pub const ADMIN_SEES_ALL: &str = "T2b_admin_sees_all_owners";
+    pub const ADMIN_FORCE_ARCHIVE: &str = "T2c_admin_force_archive";
+    pub const SDL_ROLE_SPLIT: &str = "T2d_sdl_role_split_force_archive";
+    pub const CREATE_OWNER_SESSION: &str = "T1c_create_owner_from_session";
+    pub const COMPLETE: &str = "T3_complete_todo";
+    pub const NOT_OWNER: &str = "T4_not_owner_rejected";
+    pub const NOT_OWNER_MUTATES: &str = "T4b_not_owner_rename_archive_reopen";
+    pub const UNAUTH: &str = "T5_unauthenticated_rejected";
+    pub const LIFECYCLE: &str = "T6_lifecycle_rename_archive";
+    pub const HTTP_OFF: &str = "T0_http_commands_disabled";
+    pub const ADMIN_QUERY_LIMIT: &str = "T2e_admin_todos_limit";
+}
diff --git a/tests/e2e-ui/crates/suite/tests/behavioral.rs b/tests/e2e-ui/crates/suite/tests/behavioral.rs
new file mode 100644
index 00000000..6b7dce07
--- /dev/null
+++ b/tests/e2e-ui/crates/suite/tests/behavioral.rs
@@ -0,0 +1,588 @@
+//! Behavioral suite — GraphQL-only commands + queries, per-user isolation.
+//!
+//! Set `E2E_BASE_URL` to hit an external process, or leave unset to boot
+//! an in-process service (SQLite memory + InMemoryBus + projector loop).
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use distributed::bus::{InMemoryBus, RunOptions};
+use distributed::microsvc::serve;
+use distributed::{SqliteLockManager, SqliteRepository};
+use e2e_service::{build_graphql_engine, build_service, distributed_manifest};
+use e2e_suite::{
+    assert_http_commands_disabled, cases, graphql, graphql_raw, new_command_id,
+    offline_oidc_identity, todos_archive, todos_complete, todos_create, todos_force_archive,
+    todos_rename, todos_reopen, wait_ready,
+};
+
+async fn ensure_target() -> String {
+    if let Ok(url) = std::env::var("E2E_BASE_URL") {
+        if !url.is_empty() {
+            assert!(
+                wait_ready(&url, Duration::from_secs(30)).await,
+                "E2E_BASE_URL={url} not ready"
+            );
+            return url;
+        }
+    }
+
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let addr = listener.local_addr().unwrap();
+    drop(listener);
+    let bind = addr.to_string();
+    let base = format!("http://{bind}");
+
+    // Always in-memory SQLite for offline suite (ignore compose DATABASE_URL=postgres).
+    let repo = SqliteRepository::connect_and_migrate("sqlite::memory:")
+        .await
+        .expect("repo");
+    let registry = distributed_manifest().table_registry().expect("registry");
+    repo.bootstrap_table_schema_for_dev(&registry)
+        .await
+        .expect("bootstrap");
+    let locks = SqliteLockManager::new(repo.pool().clone());
+    let bus = InMemoryBus::new();
+
+    let change_rx = repo.read_model_changes();
+    // Offline suite uses a synthetic signed static-JWKS bearer. Durable command
+    // tests exercise the same VerifiedPrincipal fence as production.
+    let service = build_service(repo.clone(), locks.clone(), repo.clone()).with_bus(bus.clone());
+    let gql = build_graphql_engine(&repo, &service, offline_oidc_identity(), Some(change_rx))
+        .expect("gql");
+    let service = Arc::new(service.try_with_graphql(gql).expect("bind gql"));
+
+    // Projector consumer (eventual consistency path — no command-side dual-write).
+    let consumer_repo = repo.clone();
+    let consumer_locks = locks.clone();
+    let bus_c = bus.clone();
+    tokio::spawn(async move {
+        loop {
+            let service = build_service(
+                consumer_repo.clone(),
+                consumer_locks.clone(),
+                consumer_repo.clone(),
+            )
+            .with_bus(bus_c.clone());
+            if let Err(error) = service.run(RunOptions::idempotent()).await {
+                eprintln!("offline projector loop: {error}");
+                if let Ok(Some((code, detail))) = sqlx::query_as::<_, (String, Vec<u8>)>(
+                    "SELECT failure_code, failure_bytes FROM projection_failures LIMIT 1",
+                )
+                .fetch_optional(consumer_repo.pool())
+                .await
+                {
+                    eprintln!(
+                        "offline projector failure {code}: {}",
+                        String::from_utf8_lossy(&detail)
+                    );
+                }
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(5)).await;
+        }
+    });
+
+    let svc = Arc::clone(&service);
+    let bind_c = bind.clone();
+    tokio::spawn(async move {
+        let _ = serve(svc, &bind_c).await;
+    });
+
+    assert!(
+        wait_ready(&base, Duration::from_secs(10)).await,
+        "in-process todo service not ready at {base}"
+    );
+    base
+}
+
+async fn poll_todo(base: &str, user: &str, todo_id: &str) -> Option<serde_json::Value> {
+    for _ in 0..100 {
+        if let Ok(v) = graphql(
+            base,
+            "{ todos { todo_id owner_id title status } }",
+            user,
+            "user",
+        )
+        .await
+        {
+            if let Some(arr) = v["data"]["todos"].as_array() {
+                if let Some(row) = arr.iter().find(|r| r["todo_id"] == todo_id) {
+                    return Some(row.clone());
+                }
+            }
+        }
+        tokio::time::sleep(Duration::from_millis(30)).await;
+    }
+    None
+}
+
+fn id(prefix: &str) -> String {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    use std::time::{SystemTime, UNIX_EPOCH};
+    static SEQ: AtomicU64 = AtomicU64::new(0);
+    let n = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_nanos();
+    let s = SEQ.fetch_add(1, Ordering::Relaxed);
+    format!("{prefix}-{n:x}-{s:x}")
+}
+
+#[tokio::test]
+async fn t0_http_command_routes_disabled() {
+    let base = ensure_target().await;
+    assert_http_commands_disabled(&base)
+        .await
+        .unwrap_or_else(|e| panic!("{}: {e}", cases::HTTP_OFF));
+    eprintln!("{} ok", cases::HTTP_OFF);
+}
+
+#[tokio::test]
+async fn t1_create_and_project() {
+    let base = ensure_target().await;
+    let tid = id("t");
+    let resp = todos_create(&base, &tid, "Buy milk", "alice", "user")
+        .await
+        .unwrap_or_else(|e| panic!("{}: {e}", cases::CREATE));
+    assert_eq!(resp["todo_id"], tid);
+    assert_eq!(resp["owner_id"], "alice");
+    assert_eq!(resp["status"], "open");
+
+    let row = poll_todo(&base, "alice", &tid)
+        .await
+        .unwrap_or_else(|| panic!("{}: not projected", cases::CREATE));
+    assert_eq!(row["title"], "Buy milk");
+    assert_eq!(row["owner_id"], "alice");
+    eprintln!("{} ok {tid}", cases::CREATE);
+}
+
+/// Create via GraphQL command mutation; owner is always session user.
+#[tokio::test]
+async fn t1b_create_via_graphql_mutation() {
+    let base = ensure_target().await;
+    let tid = id("tgql");
+    let payload = todos_create(&base, &tid, "Via GQL", "alice", "user")
+        .await
+        .unwrap_or_else(|e| panic!("todos_create mutation: {e}"));
+    assert_eq!(payload["todo_id"], tid);
+    assert_eq!(payload["owner_id"], "alice");
+    assert_eq!(payload["title"], "Via GQL");
+
+    let row = poll_todo(&base, "alice", &tid)
+        .await
+        .expect("mutation must project into todos read model");
+    assert_eq!(row["owner_id"], "alice");
+    eprintln!("todos_create ok {tid}");
+}
+
+/// GraphQL create input has no owner_id; session principal is always the owner.
+#[tokio::test]
+async fn t1c_create_owner_from_session_not_input() {
+    let base = ensure_target().await;
+    let tid = id("towner");
+    let command_id = new_command_id();
+    // Extra owner_id field must not be accepted as spoof — schema rejects or ignores.
+    let spoof = format!(
+        r#"mutation {{
+          todos_create(commandId: "{command_id}", input: {{ todo_id: "{tid}", title: "owned", owner_id: "evil" }}) {{
+            todo_id owner_id
+          }}
+        }}"#
+    );
+    let spoof_res = graphql(&base, &spoof, "alice", "user").await;
+    match spoof_res {
+        Ok(v) => {
+            // If engine ignores unknown input fields, owner must still be session.
+            if let Some(owner) = v["data"]["todos_create"]["owner_id"].as_str() {
+                assert_eq!(
+                    owner,
+                    "alice",
+                    "{}: owner spoofed: {v}",
+                    cases::CREATE_OWNER_SESSION
+                );
+            } else {
+                // GraphQL errors (unknown field) also acceptable
+                let errs = v.get("errors").and_then(|e| e.as_array());
+                assert!(
+                    errs.map(|a| !a.is_empty()).unwrap_or(false),
+                    "{}: expected errors or alice owner: {v}",
+                    cases::CREATE_OWNER_SESSION
+                );
+            }
+        }
+        Err(e) => {
+            assert!(
+                e.to_lowercase().contains("error")
+                    || e.contains("400")
+                    || e.contains("field")
+                    || e.contains("owner"),
+                "{}: unexpected: {e}",
+                cases::CREATE_OWNER_SESSION
+            );
+        }
+    }
+
+    let tid2 = id("towner2");
+    let payload = todos_create(&base, &tid2, "session owner", "alice", "user")
+        .await
+        .expect(cases::CREATE_OWNER_SESSION);
+    assert_eq!(payload["owner_id"], "alice");
+    eprintln!("{} ok", cases::CREATE_OWNER_SESSION);
+}
+
+#[tokio::test]
+async fn t2_owner_isolation_graphql() {
+    let base = ensure_target().await;
+    let alice_id = id("ta");
+    let bob_id = id("tb");
+
+    todos_create(&base, &alice_id, "Alice only", "alice", "user")
+        .await
+        .expect(cases::OWNER_ISOLATION);
+    todos_create(&base, &bob_id, "Bob only", "bob", "user")
+        .await
+        .expect(cases::OWNER_ISOLATION);
+
+    assert!(poll_todo(&base, "alice", &alice_id).await.is_some());
+    assert!(poll_todo(&base, "bob", &bob_id).await.is_some());
+
+    let v = graphql(&base, "{ todos { todo_id owner_id } }", "alice", "user")
+        .await
+        .expect(cases::OWNER_ISOLATION);
+    let arr = v["data"]["todos"].as_array().expect("todos array");
+    assert!(
+        arr.iter().all(|r| r["owner_id"] == "alice"),
+        "{}: alice saw foreign todos: {v}",
+        cases::OWNER_ISOLATION
+    );
+    assert!(
+        arr.iter().any(|r| r["todo_id"] == alice_id),
+        "{}: missing alice todo",
+        cases::OWNER_ISOLATION
+    );
+    assert!(
+        !arr.iter().any(|r| r["todo_id"] == bob_id),
+        "{}: alice saw bob's todo",
+        cases::OWNER_ISOLATION
+    );
+    eprintln!("{} ok", cases::OWNER_ISOLATION);
+}
+
+/// Admin role: same `todos` query has no owner filter — sees alice + bob rows.
+#[tokio::test]
+async fn t2b_admin_sees_all_owners() {
+    let base = ensure_target().await;
+    let alice_id = id("taa");
+    let bob_id = id("tbb");
+
+    todos_create(&base, &alice_id, "Alice note", "alice", "user")
+        .await
+        .expect(cases::ADMIN_SEES_ALL);
+    todos_create(&base, &bob_id, "Bob note", "bob", "user")
+        .await
+        .expect(cases::ADMIN_SEES_ALL);
+
+    assert!(poll_todo(&base, "alice", &alice_id).await.is_some());
+    assert!(poll_todo(&base, "bob", &bob_id).await.is_some());
+
+    let v = graphql(
+        &base,
+        "{ todos { todo_id owner_id title } }",
+        "admin-user",
+        "admin",
+    )
+    .await
+    .expect(cases::ADMIN_SEES_ALL);
+    let arr = v["data"]["todos"].as_array().expect("todos array");
+    let owners: Vec<&str> = arr.iter().filter_map(|r| r["owner_id"].as_str()).collect();
+    assert!(
+        arr.iter().any(|r| r["todo_id"] == alice_id),
+        "{}: admin missing alice todo: {v}",
+        cases::ADMIN_SEES_ALL
+    );
+    assert!(
+        arr.iter().any(|r| r["todo_id"] == bob_id),
+        "{}: admin missing bob todo: {v}",
+        cases::ADMIN_SEES_ALL
+    );
+    assert!(
+        owners.contains(&"alice") && owners.contains(&"bob"),
+        "{}: admin should see multiple owners, got {owners:?}",
+        cases::ADMIN_SEES_ALL
+    );
+    eprintln!("{} ok alice={alice_id} bob={bob_id}", cases::ADMIN_SEES_ALL);
+}
+
+/// Admin-only mutation: force-archive another user's todo; user role cannot call it.
+#[tokio::test]
+async fn t2c_admin_force_archive() {
+    let base = ensure_target().await;
+    let tid = id("tfa");
+
+    todos_create(&base, &tid, "Alice will be forced", "alice", "user")
+        .await
+        .expect(cases::ADMIN_FORCE_ARCHIVE);
+    assert!(poll_todo(&base, "alice", &tid).await.is_some());
+
+    // User role must not force-archive (field absent / rejected).
+    let user_attempt = todos_force_archive(&base, &tid, "alice", "user").await;
+    assert!(
+        user_attempt.is_err(),
+        "{}: user role must not force-archive (got ok: {user_attempt:?})",
+        cases::ADMIN_FORCE_ARCHIVE
+    );
+    // Denied call must not archive the row.
+    let after_deny = poll_todo(&base, "alice", &tid)
+        .await
+        .expect("todo exists after denied force-archive");
+    assert_ne!(
+        after_deny["status"],
+        "archived",
+        "{}: user force-archive must not change status",
+        cases::ADMIN_FORCE_ARCHIVE
+    );
+
+    let payload = todos_force_archive(&base, &tid, "admin-user", "admin")
+        .await
+        .unwrap_or_else(|e| panic!("{}: {e}", cases::ADMIN_FORCE_ARCHIVE));
+    assert_eq!(payload["todo_id"], tid);
+    assert_eq!(payload["owner_id"], "alice");
+    assert_eq!(payload["status"], "archived");
+    assert_eq!(payload["archived_by"], "admin-user");
+
+    let mut ok = false;
+    for _ in 0..100 {
+        if let Some(row) = poll_todo(&base, "alice", &tid).await {
+            if row["status"] == "archived" {
+                ok = true;
+                break;
+            }
+        }
+        tokio::time::sleep(Duration::from_millis(30)).await;
+    }
+    assert!(
+        ok,
+        "{}: projected status not archived after admin force",
+        cases::ADMIN_FORCE_ARCHIVE
+    );
+    eprintln!("{} ok {tid}", cases::ADMIN_FORCE_ARCHIVE);
+}
+
+/// Role SDL: force-archive only on admin schema (engine source of truth).
+#[tokio::test]
+async fn t2d_sdl_role_split_force_archive() {
+    let repo = distributed::SqliteRepository::connect_and_migrate("sqlite::memory:")
+        .await
+        .expect("repo");
+    let registry = distributed_manifest().table_registry().expect("registry");
+    repo.bootstrap_table_schema_for_dev(&registry)
+        .await
+        .expect("bootstrap");
+    let locks = distributed::SqliteLockManager::new(repo.pool().clone());
+    let service = build_service(repo.clone(), locks, repo.clone());
+    let engine = build_graphql_engine(&repo, &service, offline_oidc_identity(), None).expect("gql");
+    let user_sdl = engine.sdl_for_role("user").expect("user sdl");
+    let admin_sdl = engine.sdl_for_role("admin").expect("admin sdl");
+    assert!(
+        !user_sdl.contains("todos_force_archive"),
+        "{}: user SDL must not expose force-archive",
+        cases::SDL_ROLE_SPLIT
+    );
+    assert!(
+        admin_sdl.contains("todos_force_archive"),
+        "{}: admin SDL must expose force-archive",
+        cases::SDL_ROLE_SPLIT
+    );
+    assert!(
+        admin_sdl.contains("todo.force_archived")
+            || admin_sdl.contains("TodoForceArchive")
+            || admin_sdl.contains("todos_force_archive"),
+        "{}: admin SDL mutation surface incomplete",
+        cases::SDL_ROLE_SPLIT
+    );
+    eprintln!("{} ok", cases::SDL_ROLE_SPLIT);
+}
+
+/// Admin todos query supports limit (bounded list).
+#[tokio::test]
+async fn t2e_admin_todos_respects_limit() {
+    let base = ensure_target().await;
+    for i in 0..5 {
+        let tid = id(&format!("lim{i}"));
+        todos_create(&base, &tid, &format!("n{i}"), "alice", "user")
+            .await
+            .expect(cases::ADMIN_QUERY_LIMIT);
+        assert!(poll_todo(&base, "alice", &tid).await.is_some());
+    }
+    let v = graphql(
+        &base,
+        "{ todos(limit: 2, order_by: [{ todo_id: asc }]) { todo_id } }",
+        "admin-user",
+        "admin",
+    )
+    .await
+    .expect(cases::ADMIN_QUERY_LIMIT);
+    let arr = v["data"]["todos"].as_array().expect("todos");
+    assert!(
+        arr.len() <= 2,
+        "{}: expected at most 2 rows, got {}: {v}",
+        cases::ADMIN_QUERY_LIMIT,
+        arr.len()
+    );
+    eprintln!("{} ok n={}", cases::ADMIN_QUERY_LIMIT, arr.len());
+}
+
+#[tokio::test]
+async fn t3_complete_projects_status() {
+    let base = ensure_target().await;
+    let tid = id("tc");
+    todos_create(&base, &tid, "Do thing", "alice", "user")
+        .await
+        .expect(cases::COMPLETE);
+    assert!(poll_todo(&base, "alice", &tid).await.is_some());
+
+    todos_complete(&base, &tid, "alice", "user")
+        .await
+        .expect(cases::COMPLETE);
+
+    let mut ok = false;
+    for _ in 0..100 {
+        if let Some(row) = poll_todo(&base, "alice", &tid).await {
+            if row["status"] == "completed" {
+                ok = true;
+                break;
+            }
+        }
+        tokio::time::sleep(Duration::from_millis(30)).await;
+    }
+    assert!(ok, "{}: status not completed in GraphQL", cases::COMPLETE);
+    eprintln!("{} ok {tid}", cases::COMPLETE);
+}
+
+#[tokio::test]
+async fn t4_not_owner_rejected() {
+    let base = ensure_target().await;
+    let tid = id("to");
+    todos_create(&base, &tid, "Alice task", "alice", "user")
+        .await
+        .expect(cases::NOT_OWNER);
+
+    let err = todos_complete(&base, &tid, "bob", "user")
+        .await
+        .expect_err(cases::NOT_OWNER);
+    assert!(
+        err.to_lowercase().contains("reject")
+            || err.to_lowercase().contains("owner")
+            || err.to_lowercase().contains("forbidden")
+            || err.contains("422")
+            || err.contains("UNPROCESSABLE"),
+        "{}: unexpected error: {err}",
+        cases::NOT_OWNER
+    );
+    // Rename/archive/reopen IDOR: bob must not succeed (same domain owner gate as complete).
+    assert!(
+        todos_rename(&base, &tid, "Hijacked", "bob", "user")
+            .await
+            .is_err(),
+        "{}: rename should fail for bob",
+        cases::NOT_OWNER_MUTATES
+    );
+    assert!(
+        todos_archive(&base, &tid, "bob", "user").await.is_err(),
+        "{}: archive should fail for bob",
+        cases::NOT_OWNER_MUTATES
+    );
+    // GraphQL todos_reopen path — real mutation helper, non-owner rejected.
+    assert!(
+        todos_reopen(&base, &tid, "bob", "user").await.is_err(),
+        "{}: reopen should fail for bob",
+        cases::NOT_OWNER_MUTATES
+    );
+    let row = poll_todo(&base, "alice", &tid).await.expect("row");
+    assert_eq!(row["title"], "Alice task");
+    assert_eq!(row["status"], "open");
+    eprintln!("{} + {} ok", cases::NOT_OWNER, cases::NOT_OWNER_MUTATES);
+}
+
+#[tokio::test]
+async fn t5_unauthenticated_rejected() {
+    let base = ensure_target().await;
+    let tid = id("tu");
+    let command_id = new_command_id();
+    let doc = format!(
+        r#"mutation {{
+          todos_create(commandId: "{command_id}", input: {{ todo_id: "{tid}", title: "no user" }}) {{
+            todo_id
+          }}
+        }}"#
+    );
+    // DevHeaders with no identity → mutation fails (require_user).
+    let (status, body) = graphql_raw(&base, &doc).await.expect(cases::UNAUTH);
+    // Prefer GraphQL errors over HTTP 401 depending on identity mode.
+    let has_err = body
+        .get("errors")
+        .and_then(|e| e.as_array())
+        .map(|a| !a.is_empty())
+        .unwrap_or(false);
+    assert!(
+        status == 401 || has_err,
+        "{}: expected 401 or GraphQL errors, got HTTP {status} {body}",
+        cases::UNAUTH
+    );
+    eprintln!("{} ok", cases::UNAUTH);
+}
+
+#[tokio::test]
+async fn t6_lifecycle_rename_and_archive() {
+    let base = ensure_target().await;
+    let tid = id("tl");
+    todos_create(&base, &tid, "Draft", "alice", "user")
+        .await
+        .expect(cases::LIFECYCLE);
+    assert!(poll_todo(&base, "alice", &tid).await.is_some());
+
+    todos_rename(&base, &tid, "Renamed", "alice", "user")
+        .await
+        .expect(cases::LIFECYCLE);
+
+    let mut renamed = false;
+    for _ in 0..100 {
+        if let Some(row) = poll_todo(&base, "alice", &tid).await {
+            if row["title"] == "Renamed" {
+                renamed = true;
+                break;
+            }
+        }
+        tokio::time::sleep(Duration::from_millis(30)).await;
+    }
+    assert!(renamed, "{}: rename not projected", cases::LIFECYCLE);
+
+    todos_archive(&base, &tid, "alice", "user")
+        .await
+        .expect(cases::LIFECYCLE);
+
+    let mut archived = false;
+    for _ in 0..100 {
+        if let Some(row) = poll_todo(&base, "alice", &tid).await {
+            if row["status"] == "archived" {
+                archived = true;
+                break;
+            }
+        }
+        tokio::time::sleep(Duration::from_millis(30)).await;
+    }
+    assert!(archived, "{}: archive not projected", cases::LIFECYCLE);
+
+    let err = todos_complete(&base, &tid, "alice", "user")
+        .await
+        .expect_err("complete after archive");
+    assert!(
+        err.to_lowercase().contains("reject")
+            || err.to_lowercase().contains("archiv")
+            || err.contains("UNPROCESSABLE"),
+        "{}: complete after archive: {err}",
+        cases::LIFECYCLE
+    );
+    eprintln!("{} ok {tid}", cases::LIFECYCLE);
+}
diff --git a/tests/e2e-ui/crates/suite/tests/oidc_pg.rs b/tests/e2e-ui/crates/suite/tests/oidc_pg.rs
new file mode 100644
index 00000000..44f7153e
--- /dev/null
+++ b/tests/e2e-ui/crates/suite/tests/oidc_pg.rs
@@ -0,0 +1,264 @@
+//! Live OIDC cell (gated by `E2E_STACK=1` + env from `scripts/up.sh`).
+//! Soft-skips when unset so offline `make test` stays green.
+
+use std::path::PathBuf;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use e2e_suite::new_command_id;
+use jsonwebtoken::{encode, Algorithm, EncodingKey, Header};
+use serde_json::{json, Value};
+
+fn stack_enabled() -> bool {
+    matches!(
+        std::env::var("E2E_STACK")
+            .unwrap_or_default()
+            .to_ascii_lowercase()
+            .as_str(),
+        "1" | "true" | "yes"
+    )
+}
+
+async fn mint_machine_token(keyfile: &str, uid: &str, issuer: &str, project_id: &str) -> String {
+    let raw = tokio::fs::read_to_string(keyfile).await.expect("keyfile");
+    let v: Value = serde_json::from_str(&raw).expect("json");
+    let kid = v["keyId"]
+        .as_str()
+        .or_else(|| v["key_id"].as_str())
+        .expect("kid");
+    let pem = v["key"].as_str().expect("pem");
+    let now = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_secs() as i64;
+    let claims = json!({
+        "iss": uid,
+        "sub": uid,
+        "aud": [format!("{issuer}/oauth/v2/token"), issuer],
+        "iat": now,
+        "exp": now + 120,
+    });
+    let mut header = Header::new(Algorithm::RS256);
+    header.kid = Some(kid.to_string());
+    let encoding = EncodingKey::from_rsa_pem(pem.as_bytes()).expect("pem");
+    let assertion = encode(&header, &claims, &encoding).expect("sign");
+
+    let body = format!(
+        "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope={}&assertion={}",
+        urlencoding_lite(&format!(
+            "openid profile urn:zitadel:iam:org:project:id:{project_id}:aud urn:zitadel:iam:org:project:roles"
+        )),
+        urlencoding_lite(&assertion)
+    );
+    let client = reqwest::Client::new();
+    let resp = client
+        .post(format!("{issuer}/oauth/v2/token"))
+        .header("content-type", "application/x-www-form-urlencoded")
+        .body(body)
+        .send()
+        .await
+        .expect("token");
+    assert!(resp.status().is_success(), "token mint {}", resp.status());
+    let j: Value = resp.json().await.expect("json");
+    j["access_token"]
+        .as_str()
+        .expect("access_token")
+        .to_string()
+}
+
+fn urlencoding_lite(s: &str) -> String {
+    let mut out = String::new();
+    for b in s.bytes() {
+        match b {
+            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
+                out.push(b as char)
+            }
+            _ => out.push_str(&format!("%{b:02X}")),
+        }
+    }
+    out
+}
+
+#[tokio::test]
+async fn oidc_bearer_graphql_isolation_against_stack() {
+    if !stack_enabled() {
+        eprintln!("E2E_STACK unset — skip live OIDC+Postgres cell");
+        return;
+    }
+    let base = std::env::var("E2E_API_ORIGIN").unwrap_or_else(|_| "http://127.0.0.1:8791".into());
+    let issuer = std::env::var("OIDC_ISSUER").expect("OIDC_ISSUER");
+    let project = std::env::var("ZITADEL_PROJECT_ID").expect("ZITADEL_PROJECT_ID");
+    let user_key = std::env::var("E2E_MACHINE_USER_KEY").expect("E2E_MACHINE_USER_KEY");
+    let admin_key = std::env::var("E2E_MACHINE_ADMIN_KEY").expect("E2E_MACHINE_ADMIN_KEY");
+    let user_uid = std::env::var("E2E_MACHINE_USER_ID").expect("E2E_MACHINE_USER_ID");
+    let admin_uid = std::env::var("E2E_MACHINE_ADMIN_ID").expect("E2E_MACHINE_ADMIN_ID");
+
+    let user_tok = mint_machine_token(&user_key, &user_uid, &issuer, &project).await;
+    let admin_tok = mint_machine_token(&admin_key, &admin_uid, &issuer, &project).await;
+    let client = reqwest::Client::new();
+
+    let unauth = client
+        .post(format!("{base}/graphql"))
+        .header("content-type", "application/json")
+        .json(&json!({"query":"{ todos { todo_id } }"}))
+        .send()
+        .await
+        .expect("http");
+    assert_eq!(
+        unauth.status().as_u16(),
+        401,
+        "unauth GraphQL must 401 under OidcBearer"
+    );
+
+    // HTTP command routes are not mounted (GraphQL-only surface).
+    let http_cmd = client
+        .post(format!("{base}/todo.create"))
+        .header("content-type", "application/json")
+        .header("authorization", format!("Bearer {user_tok}"))
+        .json(&json!({"todo_id": "t-http-off", "title": "nope"}))
+        .send()
+        .await
+        .expect("http cmd");
+    assert!(
+        matches!(http_cmd.status().as_u16(), 404 | 405),
+        "POST /todo.create must not be mounted, got {}",
+        http_cmd.status()
+    );
+
+    // Mutation without Bearer but with spoofed identity headers must 401 (fail closed).
+    let spoof_command_id = new_command_id();
+    let spoof_mut = client
+        .post(format!("{base}/graphql"))
+        .header("content-type", "application/json")
+        .header("x-user-id", "spoofed-attacker")
+        .header("x-role", "admin")
+        .json(&json!({
+            "query": format!(
+                r#"mutation {{ todos_create(commandId: "{spoof_command_id}", input: {{ todo_id: "t-spoof", title: "no" }}) {{ todo_id }} }}"#
+            )
+        }))
+        .send()
+        .await
+        .expect("spoof mut");
+    assert_eq!(
+        spoof_mut.status().as_u16(),
+        401,
+        "mutation with only spoof headers must 401, got body {}",
+        spoof_mut.text().await.unwrap_or_default()
+    );
+
+    let tid = format!(
+        "t-oidc-{}",
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_millis()
+    );
+    let command_id = new_command_id();
+    let create = client
+        .post(format!("{base}/graphql"))
+        .header("content-type", "application/json")
+        .header("authorization", format!("Bearer {user_tok}"))
+        .json(&json!({
+            "query": format!(
+                r#"mutation {{ todos_create(commandId: "{command_id}", input: {{ todo_id: "{tid}", title: "OIDC todo" }}) {{ todo_id owner_id title status }} }}"#
+            )
+        }))
+        .send()
+        .await
+        .expect("create");
+    let create_body: serde_json::Value = create.json().await.expect("create json");
+    assert!(
+        create_body
+            .get("errors")
+            .and_then(|e| e.as_array())
+            .map(|a| a.is_empty())
+            .unwrap_or(true),
+        "create mutation errors: {create_body}"
+    );
+    assert_eq!(
+        create_body["data"]["todos_create"]["todo_id"], tid,
+        "{create_body}"
+    );
+
+    // Poll as the same user (owner-scoped) — proves projector + Bearer GraphQL.
+    let mut seen = false;
+    let mut last = String::new();
+    for _ in 0..60 {
+        let gql = client
+            .post(format!("{base}/graphql"))
+            .header("content-type", "application/json")
+            .header("authorization", format!("Bearer {user_tok}"))
+            .json(&json!({"query":"{ todos { todo_id owner_id title } }"}))
+            .send()
+            .await
+            .expect("gql");
+        assert!(gql.status().is_success(), "user gql HTTP {}", gql.status());
+        let body: Value = gql.json().await.unwrap();
+        last = body.to_string();
+        if let Some(arr) = body["data"]["todos"].as_array() {
+            if arr.iter().any(|r| r["todo_id"] == tid) {
+                seen = true;
+                // owner is JWT sub, not spoofable
+                for r in arr {
+                    if r["todo_id"] == tid {
+                        assert_eq!(r["owner_id"], user_uid);
+                    }
+                }
+                break;
+            }
+        }
+        tokio::time::sleep(Duration::from_millis(100)).await;
+    }
+    assert!(seen, "user should see projected todo; last={last}");
+
+    // Spoof headers must not override Bearer subject.
+    let spoof = client
+        .post(format!("{base}/graphql"))
+        .header("content-type", "application/json")
+        .header("authorization", format!("Bearer {user_tok}"))
+        .header("x-user-id", "evil")
+        .header("x-role", "admin")
+        .json(&json!({"query":"{ todos { todo_id owner_id } }"}))
+        .send()
+        .await
+        .expect("spoof");
+    assert!(spoof.status().is_success());
+    let body: Value = spoof.json().await.unwrap();
+    if let Some(arr) = body["data"]["todos"].as_array() {
+        for r in arr {
+            assert_ne!(r["owner_id"], "evil", "Bearer must win over spoof headers");
+        }
+    }
+
+    // Admin token must authenticate (GraphQL 200), even if role claims default to user.
+    let admin_gql = client
+        .post(format!("{base}/graphql"))
+        .header("content-type", "application/json")
+        .header("authorization", format!("Bearer {admin_tok}"))
+        .json(&json!({"query":"{ todos { todo_id } }"}))
+        .send()
+        .await
+        .expect("admin");
+    assert!(
+        admin_gql.status().is_success(),
+        "admin bearer must auth GraphQL"
+    );
+
+    eprintln!("oidc_pg isolation ok todo={tid}");
+}
+
+#[test]
+fn compose_and_bootstrap_scripts_present() {
+    let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..");
+    assert!(
+        root.join("docker/docker-compose.yml").is_file(),
+        "docker-compose.yml"
+    );
+    assert!(root.join("scripts/up.sh").is_file(), "scripts/up.sh");
+    let up = std::fs::read_to_string(root.join("scripts/up.sh")).unwrap();
+    assert!(up.contains("OIDC_ISSUER"), "bootstrap exports OIDC_ISSUER");
+    assert!(
+        up.contains("DATABASE_URL"),
+        "bootstrap exports DATABASE_URL"
+    );
+}
diff --git a/tests/e2e-ui/crates/todo-domain/Cargo.toml b/tests/e2e-ui/crates/todo-domain/Cargo.toml
new file mode 100644
index 00000000..fb7c5ce6
--- /dev/null
+++ b/tests/e2e-ui/crates/todo-domain/Cargo.toml
@@ -0,0 +1,14 @@
+[package]
+name = "todo-domain"
+version.workspace = true
+edition.workspace = true
+publish = false
+description = "Todo aggregate: create, rename, complete, reopen, archive (owner-scoped)"
+
+[dependencies]
+distributed = { workspace = true }
+serde = { workspace = true }
+thiserror = { workspace = true }
+
+[dev-dependencies]
+serde_json = { workspace = true }
diff --git a/tests/e2e-ui/crates/todo-domain/src/lib.rs b/tests/e2e-ui/crates/todo-domain/src/lib.rs
new file mode 100644
index 00000000..0e6754a3
--- /dev/null
+++ b/tests/e2e-ui/crates/todo-domain/src/lib.rs
@@ -0,0 +1,11 @@
+//! Todo aggregate — personal task list item owned by one user.
+//!
+//! Invariants (enforced here, not only in handlers):
+//! - every todo has a non-empty id, owner, and title
+//! - owner is fixed at create time
+//! - complete/reopen/rename only while not archived
+//! - archive is terminal for mutations (except re-open is not allowed after archive)
+
+pub mod models;
+
+pub use models::{Todo, TodoError, TodoFact, TodoStatus};
diff --git a/tests/e2e-ui/crates/todo-domain/src/models/mod.rs b/tests/e2e-ui/crates/todo-domain/src/models/mod.rs
new file mode 100644
index 00000000..2d11a05b
--- /dev/null
+++ b/tests/e2e-ui/crates/todo-domain/src/models/mod.rs
@@ -0,0 +1,11 @@
+//! Todo domain models.
+
+mod todo;
+mod todo_error;
+mod todo_fact;
+mod todo_status;
+
+pub use todo::Todo;
+pub use todo_error::TodoError;
+pub use todo_fact::TodoFact;
+pub use todo_status::TodoStatus;
diff --git a/tests/e2e-ui/crates/todo-domain/src/models/todo.rs b/tests/e2e-ui/crates/todo-domain/src/models/todo.rs
new file mode 100644
index 00000000..29eb8f7e
--- /dev/null
+++ b/tests/e2e-ui/crates/todo-domain/src/models/todo.rs
@@ -0,0 +1,227 @@
+use distributed::{sourced, Entity};
+use serde::{Deserialize, Serialize};
+
+use super::{TodoError, TodoStatus};
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct Todo {
+    #[serde(skip, default)]
+    pub entity: Entity,
+    pub todo_id: String,
+    pub owner_id: String,
+    pub title: String,
+    pub status: TodoStatus,
+}
+
+impl Todo {
+    pub fn is_created(&self) -> bool {
+        !self.todo_id.is_empty()
+    }
+
+    pub fn ensure_owner(&self, owner_id: &str) -> Result<(), TodoError> {
+        if !self.is_created() {
+            return Err(TodoError::NotCreated);
+        }
+        if self.owner_id != owner_id {
+            return Err(TodoError::NotOwner);
+        }
+        Ok(())
+    }
+
+    fn require_mutable(&self) -> Result<(), TodoError> {
+        if !self.is_created() {
+            return Err(TodoError::NotCreated);
+        }
+        if matches!(self.status, TodoStatus::Archived) {
+            return Err(TodoError::Archived);
+        }
+        Ok(())
+    }
+}
+
+#[sourced(entity, events = "TodoEvent", aggregate_type = "todo")]
+impl Todo {
+    /// Create a new open todo. `owner_id` is the authenticated user (never trusted from peers).
+    pub fn create(
+        &mut self,
+        todo_id: impl Into<String>,
+        owner_id: impl Into<String>,
+        title: impl Into<String>,
+    ) -> Result<(), TodoError> {
+        if self.is_created() {
+            return Err(TodoError::AlreadyExists);
+        }
+        let todo_id = todo_id.into();
+        let owner_id = owner_id.into();
+        let title = title.into();
+        if todo_id.trim().is_empty() {
+            return Err(TodoError::EmptyId);
+        }
+        if owner_id.trim().is_empty() {
+            return Err(TodoError::EmptyOwner);
+        }
+        let title = title.trim();
+        if title.is_empty() {
+            return Err(TodoError::EmptyTitle);
+        }
+        self.record_created(todo_id, owner_id, title.to_string())?;
+        Ok(())
+    }
+
+    #[event("todo.created")]
+    fn record_created(&mut self, todo_id: String, owner_id: String, title: String) {
+        self.entity.set_id(&todo_id);
+        self.todo_id = todo_id;
+        self.owner_id = owner_id;
+        self.title = title;
+        self.status = TodoStatus::Open;
+    }
+
+    pub fn rename(&mut self, owner_id: &str, title: impl Into<String>) -> Result<(), TodoError> {
+        self.ensure_owner(owner_id)?;
+        self.require_mutable()?;
+        let title = title.into();
+        let title = title.trim();
+        if title.is_empty() {
+            return Err(TodoError::EmptyTitle);
+        }
+        if title == self.title {
+            return Ok(()); // no-op: same title
+        }
+        self.record_renamed(title.to_string())?;
+        Ok(())
+    }
+
+    #[event("todo.renamed")]
+    fn record_renamed(&mut self, title: String) {
+        self.title = title;
+    }
+
+    pub fn complete(&mut self, owner_id: &str) -> Result<(), TodoError> {
+        self.ensure_owner(owner_id)?;
+        self.require_mutable()?;
+        if matches!(self.status, TodoStatus::Completed) {
+            return Err(TodoError::AlreadyCompleted);
+        }
+        self.record_completed()?;
+        Ok(())
+    }
+
+    #[event("todo.completed")]
+    fn record_completed(&mut self) {
+        self.status = TodoStatus::Completed;
+    }
+
+    pub fn reopen(&mut self, owner_id: &str) -> Result<(), TodoError> {
+        self.ensure_owner(owner_id)?;
+        self.require_mutable()?;
+        if !matches!(self.status, TodoStatus::Completed) {
+            return Err(TodoError::NotCompleted);
+        }
+        self.record_reopened()?;
+        Ok(())
+    }
+
+    #[event("todo.reopened")]
+    fn record_reopened(&mut self) {
+        self.status = TodoStatus::Open;
+    }
+
+    pub fn archive(&mut self, owner_id: &str) -> Result<(), TodoError> {
+        self.ensure_owner(owner_id)?;
+        if !self.is_created() {
+            return Err(TodoError::NotCreated);
+        }
+        if matches!(self.status, TodoStatus::Archived) {
+            return Ok(()); // idempotent archive
+        }
+        self.record_archived()?;
+        Ok(())
+    }
+
+    #[event("todo.archived")]
+    fn record_archived(&mut self) {
+        self.status = TodoStatus::Archived;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn open_todo() -> Todo {
+        let mut t = Todo::default();
+        t.create("t1", "alice", "Buy milk").unwrap();
+        t
+    }
+
+    #[test]
+    fn create_sets_owner_and_open_status() {
+        let t = open_todo();
+        assert!(t.is_created());
+        assert_eq!(t.owner_id, "alice");
+        assert_eq!(t.title, "Buy milk");
+        assert_eq!(t.status, TodoStatus::Open);
+        assert_eq!(t.entity.id(), "t1");
+        assert_eq!(t.entity.version(), 1);
+    }
+
+    #[test]
+    fn rejects_empty_title_and_double_create() {
+        let mut t = Todo::default();
+        assert_eq!(t.create("t1", "alice", "  ").unwrap_err(), TodoError::EmptyTitle);
+        t.create("t1", "alice", "ok").unwrap();
+        assert_eq!(
+            t.create("t1", "alice", "again").unwrap_err(),
+            TodoError::AlreadyExists
+        );
+    }
+
+    #[test]
+    fn only_owner_can_mutate() {
+        let mut t = open_todo();
+        assert_eq!(t.complete("bob").unwrap_err(), TodoError::NotOwner);
+        t.complete("alice").unwrap();
+        assert_eq!(t.status, TodoStatus::Completed);
+    }
+
+    #[test]
+    fn complete_reopen_cycle() {
+        let mut t = open_todo();
+        t.complete("alice").unwrap();
+        assert_eq!(
+            t.complete("alice").unwrap_err(),
+            TodoError::AlreadyCompleted
+        );
+        t.reopen("alice").unwrap();
+        assert_eq!(t.status, TodoStatus::Open);
+        assert_eq!(t.reopen("alice").unwrap_err(), TodoError::NotCompleted);
+    }
+
+    #[test]
+    fn rename_trims_and_rejects_empty() {
+        let mut t = open_todo();
+        t.rename("alice", "  Eggs  ").unwrap();
+        assert_eq!(t.title, "Eggs");
+        assert_eq!(
+            t.rename("alice", "   ").unwrap_err(),
+            TodoError::EmptyTitle
+        );
+        // same title is no-op (no extra version if no event — check version stays)
+        let v = t.entity.version();
+        t.rename("alice", "Eggs").unwrap();
+        assert_eq!(t.entity.version(), v);
+    }
+
+    #[test]
+    fn archive_is_terminal_for_mutations() {
+        let mut t = open_todo();
+        t.archive("alice").unwrap();
+        assert_eq!(t.status, TodoStatus::Archived);
+        assert_eq!(t.complete("alice").unwrap_err(), TodoError::Archived);
+        assert_eq!(t.rename("alice", "x").unwrap_err(), TodoError::Archived);
+        // second archive is idempotent
+        t.archive("alice").unwrap();
+        assert_eq!(t.status, TodoStatus::Archived);
+    }
+}
diff --git a/tests/e2e-ui/crates/todo-domain/src/models/todo_error.rs b/tests/e2e-ui/crates/todo-domain/src/models/todo_error.rs
new file mode 100644
index 00000000..e8dd3561
--- /dev/null
+++ b/tests/e2e-ui/crates/todo-domain/src/models/todo_error.rs
@@ -0,0 +1,25 @@
+use thiserror::Error;
+
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum TodoError {
+    #[error("todo already exists")]
+    AlreadyExists,
+    #[error("todo not found / not created")]
+    NotCreated,
+    #[error("todo is archived")]
+    Archived,
+    #[error("todo is already completed")]
+    AlreadyCompleted,
+    #[error("todo is not completed")]
+    NotCompleted,
+    #[error("empty todo id")]
+    EmptyId,
+    #[error("empty owner id")]
+    EmptyOwner,
+    #[error("empty title")]
+    EmptyTitle,
+    #[error("not the owner")]
+    NotOwner,
+    #[error(transparent)]
+    Event(#[from] distributed::EventRecordError),
+}
diff --git a/tests/e2e-ui/crates/todo-domain/src/models/todo_fact.rs b/tests/e2e-ui/crates/todo-domain/src/models/todo_fact.rs
new file mode 100644
index 00000000..3abd1f4d
--- /dev/null
+++ b/tests/e2e-ui/crates/todo-domain/src/models/todo_fact.rs
@@ -0,0 +1,29 @@
+use serde::{Deserialize, Serialize};
+
+use super::{Todo, TodoStatus};
+
+/// Portable outbox / projection DTO.
+/// Full snapshot fields so projectors can upsert without loading prior rows.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct TodoFact {
+    pub todo_id: String,
+    pub owner_id: String,
+    pub title: String,
+    /// `open` | `completed` | `archived`
+    pub status: String,
+}
+
+impl TodoFact {
+    pub fn from_todo(t: &Todo) -> Self {
+        Self {
+            todo_id: t.todo_id.clone(),
+            owner_id: t.owner_id.clone(),
+            title: t.title.clone(),
+            status: match t.status {
+                TodoStatus::Open => "open".into(),
+                TodoStatus::Completed => "completed".into(),
+                TodoStatus::Archived => "archived".into(),
+            },
+        }
+    }
+}
diff --git a/tests/e2e-ui/crates/todo-domain/src/models/todo_status.rs b/tests/e2e-ui/crates/todo-domain/src/models/todo_status.rs
new file mode 100644
index 00000000..ca30b867
--- /dev/null
+++ b/tests/e2e-ui/crates/todo-domain/src/models/todo_status.rs
@@ -0,0 +1,10 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum TodoStatus {
+    #[default]
+    Open,
+    Completed,
+    Archived,
+}
diff --git a/tests/e2e-ui/docker/Caddyfile b/tests/e2e-ui/docker/Caddyfile
new file mode 100644
index 00000000..2cae7727
--- /dev/null
+++ b/tests/e2e-ui/docker/Caddyfile
@@ -0,0 +1,20 @@
+# Host port 18080 (ExternalPort). Self-hosted Login V2 is on the same edge as
+# OIDC: authorize → /ui/v2/login/login?authRequest=V2_…  Auth.js keeps using
+# /oauth/v2/* on this host. (Official login image bakes basePath=/ui/v2/login.)
+:8080 {
+	# Login V2 Next.js (Session + User/Auth v2). Pages: /login, /register,
+	# /password, … under this base path.
+	handle /ui/v2/login* {
+		reverse_proxy zitadel-login:3000
+	}
+
+	# Console, management/auth APIs, OIDC, .well-known, /idps/callback, etc.
+	# Pin Host to ExternalDomain so internal callers hit the same instance
+	# the browser hits (Host=localhost:18080).
+	handle {
+		reverse_proxy zitadel:8080 {
+			header_up Host localhost:18080
+			header_up X-Forwarded-Host localhost:18080
+		}
+	}
+}
diff --git a/tests/e2e-ui/docker/docker-compose.yml b/tests/e2e-ui/docker/docker-compose.yml
new file mode 100644
index 00000000..aae9e6f8
--- /dev/null
+++ b/tests/e2e-ui/docker/docker-compose.yml
@@ -0,0 +1,100 @@
+# e2e-ui full stack: app Postgres + Zitadel (OIDC + Login V2 UI).
+# Zitadel API + self-hosted Login V2 (Session / User v2) + Caddy edge.
+# Auth.js still uses OIDC (/oauth/v2/*); authorize lands on /ui/v2/login/login.
+#
+#   cd tests/e2e-ui && make up
+#
+# Ports:
+#   5433  app Postgres (event store, read models, bus)
+#   18080 Zitadel via proxy (OIDC + Login V2 /ui/v2/login + console)
+services:
+  app-db:
+    image: docker.io/library/postgres:16-alpine
+    environment:
+      POSTGRES_USER: e2e
+      POSTGRES_PASSWORD: e2e
+      POSTGRES_DB: e2e_ui
+    ports:
+      - "5433:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U e2e -d e2e_ui"]
+      interval: 3s
+      timeout: 5s
+      retries: 20
+      start_period: 5s
+    networks: [e2e]
+
+  zitadel-db:
+    image: docker.io/library/postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: zitadel
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 15
+      start_period: 10s
+    networks: [e2e]
+
+  zitadel:
+    image: ghcr.io/zitadel/zitadel:v4.6.1
+    user: "0:0"
+    command: >-
+      start-from-init
+      --masterkey "MasterkeyNeedsToHave32Characters"
+      --tlsMode disabled
+      --config /init/zitadel.yaml
+      --steps /init/steps.yaml
+    depends_on:
+      zitadel-db:
+        condition: service_healthy
+    # No host ports — browsers hit zitadel-proxy (same as the-website).
+    volumes:
+      - ./zitadel-init:/init:ro
+      - ./machinekey:/machinekey
+    networks: [e2e]
+
+  # Self-hosted Login V2 (Next.js). Session API + User/Auth v2 against Zitadel.
+  # Official image bakes basePath=/ui/v2/login (pages: …/login, …/register, …).
+  # PAT written by scripts/up.sh after Zitadel boots.
+  zitadel-login:
+    image: ghcr.io/zitadel/login:v3.0.1
+    restart: unless-stopped
+    environment:
+      ZITADEL_API_URL: http://zitadel-proxy:8080
+      # Must match the baked Next.js basePath in ghcr.io/zitadel/login.
+      NEXT_PUBLIC_BASE_PATH: /ui/v2/login
+      CUSTOM_REQUEST_HEADERS: "Host:localhost:18080,X-Forwarded-Proto:http,X-Forwarded-Host:localhost:18080"
+    command:
+      - /bin/sh
+      - -c
+      - |
+        set -e
+        if [ ! -s /login-client/pat ]; then
+          echo "Waiting for PAT at /login-client/pat — run make up / scripts/up.sh" >&2
+          exit 1
+        fi
+        export ZITADEL_SERVICE_USER_TOKEN="$$(cat /login-client/pat)"
+        exec node apps/login/server.js
+    depends_on:
+      zitadel:
+        condition: service_started
+    volumes:
+      - ./login-client:/login-client:ro
+    networks: [e2e]
+
+  zitadel-proxy:
+    image: caddy:2-alpine
+    ports:
+      - "18080:8080"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+    depends_on:
+      - zitadel
+      - zitadel-login
+    networks: [e2e]
+
+networks:
+  e2e:
diff --git a/tests/e2e-ui/docker/login-client/.gitkeep b/tests/e2e-ui/docker/login-client/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/e2e-ui/docker/zitadel-init/steps.yaml b/tests/e2e-ui/docker/zitadel-init/steps.yaml
new file mode 100644
index 00000000..0fd652cf
--- /dev/null
+++ b/tests/e2e-ui/docker/zitadel-init/steps.yaml
@@ -0,0 +1,21 @@
+FirstInstance:
+  MachineKeyPath: /machinekey/zitadel-admin-sa.json
+  Org:
+    Name: distributed-graphql-e2e
+    Human:
+      UserName: admin
+      FirstName: CI
+      LastName: Admin
+      Email:
+        Address: admin@localhost
+        Verified: true
+      Password: "Admin1234!"
+      PasswordChangeRequired: false
+    Machine:
+      Machine:
+        Username: zitadel-admin-sa
+        Name: Admin Service Account
+        Description: Bootstrap SA for GraphQL OIDC e2e
+      MachineKey:
+        Type: 1
+        ExpirationDate: "2029-01-01T00:00:00Z"
diff --git a/tests/e2e-ui/docker/zitadel-init/zitadel.yaml b/tests/e2e-ui/docker/zitadel-init/zitadel.yaml
new file mode 100644
index 00000000..6bbc6702
--- /dev/null
+++ b/tests/e2e-ui/docker/zitadel-init/zitadel.yaml
@@ -0,0 +1,29 @@
+ExternalDomain: localhost
+ExternalPort: 18080
+ExternalSecure: false
+
+TLS:
+  Enabled: false
+
+Database:
+  postgres:
+    Host: zitadel-db
+    Port: 5432
+    Database: zitadel
+    MaxOpenConns: 20
+    MaxIdleConns: 10
+    MaxConnLifetime: 30m
+    MaxConnIdleTime: 5m
+    User:
+      Username: zitadel
+      Password: zitadel
+      SSL:
+        Mode: disable
+    Admin:
+      Username: postgres
+      Password: postgres
+      SSL:
+        Mode: disable
+
+# Listen on all interfaces so host CI can reach :8080.
+Port: 8080
diff --git a/tests/e2e-ui/docs/zitadel-ingestor.md b/tests/e2e-ui/docs/zitadel-ingestor.md
new file mode 100644
index 00000000..aec760fd
--- /dev/null
+++ b/tests/e2e-ui/docs/zitadel-ingestor.md
@@ -0,0 +1,117 @@
+# Zitadel ingestor local runbook
+
+Normative architecture, authenticity, reconciliation, identity, and projection
+design lives in the Distributed GitKB at
+`specs/e2e-ui/zitadel-ingestor`. This file intentionally contains only the
+commands needed to operate and verify the in-repository teaching fixture.
+
+## Configuration
+
+| Environment variable | Purpose |
+|---|---|
+| `ZITADEL_INGESTOR_SECRET` | shared secret required by Action ingress and the on-demand scrape command |
+| `ZITADEL_INGESTOR_ALLOW_ACTION_EVENTS` | local-only exception for native Actions v2 bodies |
+| `ZITADEL_SERVICE_USER_TOKEN` | PAT used to list users through the Management API |
+| `ZITADEL_API_URL` or `OIDC_ISSUER` | Zitadel API base |
+| `ZITADEL_SCRAPE_INTERVAL_SECS` | background reconciliation interval; `0` disables it |
+| `ZITADEL_SCRAPE_ON_START` | run one reconciliation at process start |
+
+The fixture accepts the ingress secret through
+`x-zitadel-ingestor-secret: <secret>` or
+`Authorization: Bearer <secret>`. A missing or invalid secret returns HTTP 401.
+
+## Start the fixture
+
+```bash
+cd tests/e2e-ui
+export ZITADEL_INGESTOR_SECRET=dev-secret-change-me
+# The same value may instead be placed in e2e-ui.env before make run.
+make run
+```
+
+The `e2e-runner` process starts the outbox dispatcher and bus consumers.
+
+## Run an on-demand scrape
+
+```bash
+curl -sS -X POST "http://127.0.0.1:8791/zitadel.scrape.v1" \
+  -H "content-type: application/json" \
+  -H "x-zitadel-ingestor-secret: $ZITADEL_INGESTOR_SECRET" \
+  -d '{}'
+```
+
+The response reports `{ listed, published, skipped, errors }`.
+
+## Verify ingress authentication
+
+```bash
+BASE=http://127.0.0.1:8791
+
+curl -sS -o /dev/null -w "%{http_code}\n" \
+  -X POST "$BASE/zitadel.ingress.v1" \
+  -H 'content-type: application/json' \
+  -d '{"event_type":"user.human.created","provider_subject":"u1","delivery_id":"d0"}'
+```
+
+The unauthenticated request must return `401`.
+
+## Import one human
+
+Run this after `make up` has produced `e2e-ui.env`:
+
+```bash
+set -a && source e2e-ui.env && set +a
+BASE=http://127.0.0.1:8791
+SECRET="${ZITADEL_INGESTOR_SECRET:-e2e-zitadel-ingestor-secret}"
+
+curl -sS -X POST "$BASE/zitadel.ingress.v1" \
+  -H "content-type: application/json" \
+  -H "x-zitadel-ingestor-secret: $SECRET" \
+  -d "{
+    \"delivery_id\": \"local-create-alice\",
+    \"event_type\": \"user.human.created\",
+    \"provider_subject\": \"$E2E_HUMAN_ALICE_UID\",
+    \"email\": \"alice@e2e.local\",
+    \"display_name\": \"Alice\",
+    \"approval_status\": \"approved\"
+  }"
+```
+
+The request publishes `zitadel.user.human.created.v1`. After the outbox drains,
+the corresponding `auth_users` row supplies chat-author and Blob Game owner
+display data.
+
+## Verify GraphQL joins
+
+```graphql
+query DirectoryJoins {
+  chat_messages(where: { room_id: { _eq: "lobby" } }) {
+    body
+    author_id
+    author { display_name email status }
+  }
+  blob_games {
+    game_id
+    owner_id
+    owner { display_name email }
+  }
+  auth_users {
+    user_id
+    display_name
+    chat_messages { body }
+    blob_games { score }
+  }
+}
+```
+
+`auth_users.user_id` is the Zitadel subject. Chat `author_id` and Blob Game
+`owner_id` are the OIDC `sub`, so the relationships resolve after that subject
+has been ingested.
+
+## Tests
+
+```bash
+cd tests/e2e-ui
+cargo test -p e2e-service --lib
+cargo test -p e2e-readmodels --lib
+```
diff --git a/tests/e2e-ui/e2e/.gitignore b/tests/e2e-ui/e2e/.gitignore
new file mode 100644
index 00000000..01238d88
--- /dev/null
+++ b/tests/e2e-ui/e2e/.gitignore
@@ -0,0 +1,5 @@
+.auth/
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
diff --git a/tests/e2e-ui/e2e/admin.admin.spec.ts b/tests/e2e-ui/e2e/admin.admin.spec.ts
new file mode 100644
index 00000000..c292f1ba
--- /dev/null
+++ b/tests/e2e-ui/e2e/admin.admin.spec.ts
@@ -0,0 +1,124 @@
+import { test, expect } from '@playwright/test';
+
+async function openAdmin(page: import('@playwright/test').Page) {
+	const res = await page.goto('/admin', { waitUntil: 'domcontentloaded' });
+	const status = res?.status() ?? 0;
+	const body = await page.locator('body').innerText();
+	const denied =
+		status === 403 ||
+		/admin role required/i.test(body) ||
+		(/403/.test(body) && /lost in the cluster/i.test(body));
+	return { status, body, denied };
+}
+
+test.describe('admin (admin user)', () => {
+	test('admin session can hit /admin (role-gated)', async ({ page }) => {
+		const { denied, body } = await openAdmin(page);
+		if (denied) {
+			// Authenticated but engineRole is not admin in this Zitadel bootstrap.
+			test.info().annotations.push({
+				type: 'note',
+				description:
+					'admin human lacks engineRole=admin claims — grant Zitadel project role `admin` to exercise force-archive'
+			});
+			expect(body.length).toBeGreaterThan(10);
+			return;
+		}
+
+		await expect(page.getByRole('heading', { name: /all todos/i })).toBeVisible({
+			timeout: 20_000
+		});
+		await expect(page.getByText(/force archive/i).first()).toBeVisible();
+	});
+
+	test('force archive when rows exist and role is admin', async ({ page }) => {
+		const { denied } = await openAdmin(page);
+		if (denied) {
+			test.skip(true, 'admin engine role not granted in this environment');
+		}
+
+		await expect(page.getByRole('heading', { name: /all todos/i })).toBeVisible({
+			timeout: 20_000
+		});
+		// Wait for the nested e2e-ui-admin client to hydrate before invoking
+		// elevated commands (SSR markup alone has no Svelte handlers).
+		await page.waitForLoadState('networkidle');
+		const forceButtons = page.getByRole('button', { name: /force archive/i });
+		await expect(forceButtons.first()).toBeEnabled({ timeout: 20_000 });
+
+		const targetRow = page
+			.locator('.ad-table tbody tr')
+			.filter({ has: page.getByRole('button', { name: /force archive/i }) })
+			.first();
+		if ((await targetRow.count()) === 0) {
+			test.skip(true, 'no non-archived todos to force-archive');
+		}
+
+		const todoId = await targetRow.getAttribute('data-todo-id');
+		expect(todoId, 'admin row must expose data-todo-id').toBeTruthy();
+		const forceBtn = targetRow.getByRole('button', { name: /force archive/i });
+
+		const navigations: string[] = [];
+		page.on('framenavigated', (frame) => {
+			if (frame === page.mainFrame()) navigations.push(frame.url());
+		});
+		await page.evaluate(() => {
+			const samples = [document.querySelectorAll('.ad-table tbody tr').length];
+			const observer = new MutationObserver(() => {
+				samples.push(document.querySelectorAll('.ad-table tbody tr').length);
+			});
+			const wrap = document.querySelector('.ad-table-wrap');
+			if (wrap === null) {
+				throw new Error('admin table wrap missing before force archive');
+			}
+			observer.observe(wrap, {
+				childList: true,
+				subtree: true,
+				characterData: true
+			});
+			Object.assign(globalThis, {
+				__distributedAdminContinuitySamples: samples,
+				__distributedAdminContinuityObserver: observer
+			});
+		});
+
+		const forceResponse = page.waitForResponse(
+			(response) =>
+				response.url().includes('graphql') &&
+				(response.request().postData() ?? '').includes('todos_force_archive'),
+			{ timeout: 20_000 }
+		);
+		await forceBtn.click();
+		const response = await forceResponse;
+		const responseBody = await response.text();
+		expect(
+			response.ok(),
+			`todos_force_archive HTTP ${response.status()}: ${responseBody.slice(0, 400)}`
+		).toBeTruthy();
+		expect(
+			responseBody,
+			`todos_force_archive GraphQL errors: ${responseBody.slice(0, 600)}`
+		).not.toMatch(/"errors"\s*:\s*\[/);
+
+		// Scope to the clicked row: other rows may still show Force archive.
+		const archivedRow = page.locator(`.ad-table tbody tr[data-todo-id="${todoId}"]`);
+		await expect(archivedRow.locator('[data-status="archived"]')).toBeVisible({
+			timeout: 15_000
+		});
+		await expect(archivedRow.getByRole('button', { name: /force archive/i })).toHaveCount(0);
+
+		const samples = await page.evaluate(() => {
+			const state = globalThis as typeof globalThis & {
+				__distributedAdminContinuitySamples: number[];
+				__distributedAdminContinuityObserver: MutationObserver;
+			};
+			state.__distributedAdminContinuityObserver.disconnect();
+			return state.__distributedAdminContinuitySamples;
+		});
+		expect(navigations, 'force archive must not navigate or reload the page').toEqual([]);
+		expect(
+			Math.min(...samples),
+			'stale-while-revalidate must never replace known admin rows with an empty view'
+		).toBeGreaterThan(0);
+	});
+});
diff --git a/tests/e2e-ui/e2e/auth.admin.setup.ts b/tests/e2e-ui/e2e/auth.admin.setup.ts
new file mode 100644
index 00000000..1908977d
--- /dev/null
+++ b/tests/e2e-ui/e2e/auth.admin.setup.ts
@@ -0,0 +1,19 @@
+import { test as setup, expect } from '@playwright/test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loginAs } from './helpers/login';
+
+const authDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '.auth');
+const adminFile = path.join(authDir, 'admin.json');
+
+setup('authenticate as admin', async ({ page }) => {
+	fs.mkdirSync(authDir, { recursive: true });
+	// Land on todos first so login always has a real destination; admin role is checked on /admin.
+	await loginAs(page, 'admin', process.env.E2E_HUMAN_PASSWORD || 'Password1!', '/todos');
+	await page.waitForURL(/\/todos/, { timeout: 30_000 });
+	await expect(page.getByRole('heading', { name: /todos/i })).toBeVisible({
+		timeout: 20_000
+	});
+	await page.context().storageState({ path: adminFile });
+});
diff --git a/tests/e2e-ui/e2e/auth.alice.setup.ts b/tests/e2e-ui/e2e/auth.alice.setup.ts
new file mode 100644
index 00000000..e96cac24
--- /dev/null
+++ b/tests/e2e-ui/e2e/auth.alice.setup.ts
@@ -0,0 +1,17 @@
+import { test as setup } from '@playwright/test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loginAs } from './helpers/login';
+
+const authDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '.auth');
+const aliceFile = path.join(authDir, 'alice.json');
+
+setup('authenticate as alice', async ({ page }) => {
+	fs.mkdirSync(authDir, { recursive: true });
+	const user = process.env.E2E_HUMAN_ALICE || 'alice';
+	await loginAs(page, user, process.env.E2E_HUMAN_PASSWORD || 'Password1!', '/todos');
+	await page.waitForURL(/\/todos/, { timeout: 30_000 });
+	await page.getByRole('heading', { name: /todos/i }).waitFor({ timeout: 20_000 });
+	await page.context().storageState({ path: aliceFile });
+});
diff --git a/tests/e2e-ui/e2e/blob.user.spec.ts b/tests/e2e-ui/e2e/blob.user.spec.ts
new file mode 100644
index 00000000..75157fce
--- /dev/null
+++ b/tests/e2e-ui/e2e/blob.user.spec.ts
@@ -0,0 +1,368 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('blob game (alice)', () => {
+	test('start a game, paint board, move, show in history', async ({ page }) => {
+		await page.goto('/blob');
+		await expect(page.getByRole('heading', { name: /blob game/i })).toBeVisible();
+
+		// Wait for client hydration so Start/New game handlers are attached.
+		await expect(page.locator('[data-blob-hydrated="1"]')).toBeVisible({ timeout: 15_000 });
+		await expect(page.getByTestId('blob-start-game')).toBeEnabled({ timeout: 10_000 });
+
+		// Empty state — no fake grid pretending to be a game
+		await expect(page.getByText(/no game selected/i)).toBeVisible();
+		await expect(page.locator('.blob-board')).toHaveCount(0);
+
+		const start = page.getByTestId('blob-start-game');
+		const [resp] = await Promise.all([
+			page.waitForResponse(
+				(r) =>
+					r.url().includes('/graphql') &&
+					r.request().method() === 'POST' &&
+					(r.request().postData() ?? '').includes('blob_games_start'),
+				{ timeout: 20_000 }
+			),
+			start.click()
+		]);
+		expect(resp.ok(), `blob_games_start HTTP ${resp.status()}`).toBeTruthy();
+
+		// Real board from command payload
+		const board = page.locator('.blob-board');
+		await expect(board).toBeVisible({ timeout: 15_000 });
+		await expect(page).toHaveURL(/\/blob\/[^/]+$/);
+		await expect(board.locator('.cell').first()).toBeVisible();
+		await expect(page.locator('.hud-value').first()).toBeVisible();
+
+		// Score starts at 0
+		await expect(page.locator('.blob-hud')).toContainText(/score/i);
+
+		// Generated levels start at the top-left. A known boundary is a local
+		// no-op: no rejected command and no framework error should escape.
+		let wallMoveRequests = 0;
+		const countWallMoves = (request: import('@playwright/test').Request) => {
+			if (
+				request.url().includes('/graphql') &&
+				(request.postData() ?? '').includes('blob_games_move')
+			) {
+				wallMoveRequests += 1;
+			}
+		};
+		page.on('request', countWallMoves);
+		await page.keyboard.press('ArrowUp');
+		await page.waitForTimeout(250);
+		page.off('request', countWallMoves);
+		expect(wallMoveRequests, 'a board-edge move should not reach GraphQL').toBe(0);
+		await expect(page.locator('.inline-alert')).toHaveCount(0);
+
+		const navigations: string[] = [];
+		page.on('framenavigated', (frame) => {
+			if (frame === page.mainFrame()) navigations.push(frame.url());
+		});
+		await page.evaluate(() => {
+			const samples = [document.querySelectorAll('.blob-board').length];
+			const observer = new MutationObserver(() => {
+				samples.push(document.querySelectorAll('.blob-board').length);
+			});
+			observer.observe(document.querySelector('.blob-page')!, {
+				childList: true,
+				subtree: true,
+				characterData: true
+			});
+			Object.assign(globalThis, {
+				__distributedBlobContinuitySamples: samples,
+				__distributedBlobContinuityObserver: observer
+			});
+		});
+
+		let releaseMove!: () => void;
+		const releaseMovePromise = new Promise<void>((resolve) => {
+			releaseMove = resolve;
+		});
+		let moveReachedServer!: () => void;
+		const moveReachedServerPromise = new Promise<void>((resolve) => {
+			moveReachedServer = resolve;
+		});
+		await page.route('**/graphql', async (route) => {
+			if (!(route.request().postData() ?? '').includes('blob_games_move')) {
+				await route.continue();
+				return;
+			}
+			const response = await route.fetch();
+			moveReachedServer();
+			await releaseMovePromise;
+			await route.fulfill({ response });
+		});
+
+		// Move right (pad or keyboard). Either score increments or stays at an
+		// edge/wall, but the cached board must remain mounted throughout.
+		const moveResponsePromise = page.waitForResponse(
+			(r) =>
+				r.url().includes('/graphql') &&
+				r.request().method() === 'POST' &&
+				(r.request().postData() ?? '').includes('blob_games_move'),
+			{ timeout: 20_000 }
+		);
+		await page.keyboard.press('ArrowRight');
+		await moveReachedServerPromise;
+		await expect(page.getByTestId('blob-new-game')).toBeEnabled();
+		for (const button of await page.locator('.pad-btn').all()) {
+			await expect(button).toBeEnabled();
+		}
+		releaseMove();
+		const moveResp = await moveResponsePromise;
+		expect(moveResp.ok(), `blob_games_move HTTP ${moveResp.status()}`).toBeTruthy();
+		await page.unrouteAll({ behavior: 'wait' });
+		await expect(board).toBeVisible();
+		await expect(page.locator('.inline-alert, .blob-empty')).toHaveCount(0);
+
+		// History lists this game
+		await expect(page.getByRole('heading', { name: /your games/i })).toBeVisible({
+			timeout: 15_000
+		});
+		await expect(page.locator('.history-item').first()).toBeVisible({ timeout: 15_000 });
+
+		// Soft URL may include game id (replaceState) or stay /blob
+		await page.waitForTimeout(300);
+		expect(page.url()).toMatch(/\/blob/);
+		const samples = await page.evaluate(() => {
+			const state = globalThis as typeof globalThis & {
+				__distributedBlobContinuitySamples: number[];
+				__distributedBlobContinuityObserver: MutationObserver;
+			};
+			state.__distributedBlobContinuityObserver.disconnect();
+			return state.__distributedBlobContinuitySamples;
+		});
+		expect(navigations, 'move commands must not navigate or reload the page').toEqual([]);
+		expect(
+			Math.min(...samples),
+			'stale-while-revalidate must never replace the known board with an empty view'
+		).toBeGreaterThan(0);
+	});
+
+	test('new game from header when already on empty state', async ({ page }) => {
+		await page.goto('/blob');
+		await expect(page.locator('[data-blob-hydrated="1"]')).toBeVisible({ timeout: 15_000 });
+		const neu = page.getByTestId('blob-new-game');
+		await expect(neu).toBeEnabled({ timeout: 10_000 });
+
+		const [resp] = await Promise.all([
+			page.waitForResponse(
+				(r) =>
+					r.url().includes('/graphql') &&
+					r.request().method() === 'POST' &&
+					(r.request().postData() ?? '').includes('blob_games_start'),
+				{ timeout: 20_000 }
+			),
+			neu.click()
+		]);
+		expect(resp.ok(), `blob_games_start HTTP ${resp.status()}`).toBeTruthy();
+
+		await expect(page.locator('.blob-board')).toBeVisible({ timeout: 15_000 });
+		const cells = page.locator('.blob-board .cell');
+		await expect(cells.first()).toBeVisible();
+		// 6×6 generated maps → at least 16 cells
+		expect(await cells.count()).toBeGreaterThanOrEqual(16);
+	});
+
+	test('a revalidation started before a projected move cannot roll it back with later evidence', async ({ page }) => {
+		await page.goto('/blob');
+		await expect(page.locator('[data-blob-hydrated="1"]')).toBeVisible({ timeout: 15_000 });
+		const start = page.getByTestId('blob-start-game');
+		await expect(start).toBeEnabled({ timeout: 10_000 });
+		const [startResponse] = await Promise.all([
+			page.waitForResponse(
+				(response) =>
+					response.url().includes('/graphql') &&
+					(response.request().postData() ?? '').includes('blob_games_start'),
+				{ timeout: 20_000 }
+			),
+			start.click()
+		]);
+		expect(startResponse.ok()).toBeTruthy();
+		await expect(page.locator('.blob-board .tile-player')).toHaveAttribute(
+			'aria-label',
+			'r0 c0'
+		);
+		const gameId = decodeURIComponent(new URL(page.url()).pathname.split('/').at(-1)!);
+
+		let releaseHeldQuery!: () => void;
+		const heldQueryRelease = new Promise<void>((resolve) => {
+			releaseHeldQuery = resolve;
+		});
+		let heldQueryReady!: () => void;
+		const heldQuery = new Promise<void>((resolve) => {
+			heldQueryReady = resolve;
+		});
+		let newerQueryReady!: () => void;
+		const newerQuery = new Promise<void>((resolve) => {
+			newerQueryReady = resolve;
+		});
+		let held = false;
+		let released = false;
+		let raisedHeldRevision = false;
+		let newerPlayerLabel: string | null = null;
+
+		await page.route('**/graphql', async (route) => {
+			const requestBody = route.request().postData() ?? '';
+			if (!requestBody.includes('query BlobGames')) {
+				await route.continue();
+				return;
+			}
+			const response = await route.fetch();
+			const payload = (await response.json()) as {
+				data?: {
+					blob_games?: Array<{ game_id: string; map_json: string }>;
+				};
+				extensions?: {
+					distributed?: {
+						snapshot?: {
+							records?: Array<{
+								path?: Array<string | number>;
+								revision: string;
+							}>;
+						};
+					};
+				};
+			};
+			const gameIndex =
+				payload.data?.blob_games?.findIndex((row) => row.game_id === gameId) ?? -1;
+			const game = gameIndex < 0 ? undefined : payload.data?.blob_games?.[gameIndex];
+			let playerLabel: string | null = null;
+			if (game !== undefined) {
+				const rows = JSON.parse(game.map_json) as number[][];
+				for (const [rowIndex, row] of rows.entries()) {
+					const columnIndex = row.indexOf(9);
+					if (columnIndex >= 0) {
+						playerLabel = `r${rowIndex} c${columnIndex}`;
+						break;
+					}
+				}
+			}
+			if (!held && playerLabel === 'r0 c1') {
+				held = true;
+				const gameRecord = payload.extensions?.distributed?.snapshot?.records?.find(
+					(record) =>
+						record.path?.[0] === 'blob_games' &&
+						Number(record.path[1]) === gameIndex
+				);
+				if (gameRecord !== undefined) {
+					/*
+					 * Reproduce the server race: this SQL body was read before
+					 * the next command, but response evidence was issued after
+					 * it and is therefore numerically newer.
+					 */
+					gameRecord.revision = '999999999999999999';
+					raisedHeldRevision = true;
+				}
+				heldQueryReady();
+				await heldQueryRelease;
+			} else if (
+				released &&
+				newerPlayerLabel !== null &&
+				playerLabel === newerPlayerLabel
+			) {
+				newerQueryReady();
+			}
+			await route.fulfill({
+				response,
+				body: JSON.stringify(payload),
+				headers: {
+					...response.headers(),
+					'content-type': 'application/json'
+				}
+			});
+		});
+
+		await page.evaluate(() => {
+			const samples: string[] = [];
+			const sample = () => {
+				const label = document
+					.querySelector('.blob-board .tile-player')
+					?.getAttribute('aria-label');
+				samples.push(label ?? 'missing');
+			};
+			sample();
+			const observer = new MutationObserver(sample);
+			observer.observe(document.querySelector('.blob-page')!, {
+				attributes: true,
+				childList: true,
+				subtree: true,
+				characterData: true
+			});
+			Object.assign(globalThis, {
+				__distributedBlobRaceSamples: samples,
+				__distributedBlobRaceObserver: observer
+			});
+		});
+
+		const move = async (key: 'ArrowRight' | 'ArrowDown', expectedLabel: string) => {
+			const response = page.waitForResponse(
+				(candidate) =>
+					candidate.url().includes('/graphql') &&
+					(candidate.request().postData() ?? '').includes('blob_games_move'),
+				{ timeout: 20_000 }
+			);
+			await page.keyboard.press(key);
+			expect((await response).ok()).toBeTruthy();
+			await expect(page.locator('.blob-board .tile-player')).toHaveAttribute(
+				'aria-label',
+				expectedLabel
+			);
+		};
+
+		await move('ArrowRight', 'r0 c1');
+		await heldQuery;
+		expect(
+			raisedHeldRevision,
+			'the held response must carry deliberately later record evidence'
+		).toBe(true);
+		const rightClass =
+			(await page
+				.locator('.blob-board .cell[aria-label="r0 c2"]')
+				.getAttribute('class')) ?? '';
+		const nextMove = rightClass.includes('tile-hole')
+			? ({ key: 'ArrowDown', label: 'r1 c1' } as const)
+			: ({ key: 'ArrowRight', label: 'r0 c2' } as const);
+		await expect(
+			page.locator(`.blob-board .cell[aria-label="${nextMove.label}"]`)
+		).not.toHaveClass(/tile-hole/);
+		newerPlayerLabel = nextMove.label;
+		await move(nextMove.key, nextMove.label);
+		const releaseSampleIndex = await page.evaluate(
+			() =>
+				(
+					globalThis as typeof globalThis & {
+						__distributedBlobRaceSamples: string[];
+					}
+				).__distributedBlobRaceSamples.length
+		);
+		released = true;
+		releaseHeldQuery();
+		await newerQuery;
+		await expect(page.locator('.blob-board .tile-player')).toHaveAttribute(
+			'aria-label',
+			nextMove.label
+		);
+
+		const postReleaseSamples = await page.evaluate((startIndex) => {
+			const state = globalThis as typeof globalThis & {
+				__distributedBlobRaceSamples: string[];
+				__distributedBlobRaceObserver: MutationObserver;
+			};
+			state.__distributedBlobRaceObserver.disconnect();
+			return state.__distributedBlobRaceSamples.slice(startIndex);
+		}, releaseSampleIndex);
+		expect(
+			postReleaseSamples,
+			'an older query response must never hide or move the projected player'
+		).not.toContain('missing');
+		expect(postReleaseSamples).not.toContain('r0 c1');
+
+		await page.reload();
+		await expect(page.locator('.blob-board .tile-player')).toHaveAttribute(
+			'aria-label',
+			nextMove.label
+		);
+		await page.unrouteAll({ behavior: 'wait' });
+	});
+});
diff --git a/tests/e2e-ui/e2e/chat.user.spec.ts b/tests/e2e-ui/e2e/chat.user.spec.ts
new file mode 100644
index 00000000..5e9f76ee
--- /dev/null
+++ b/tests/e2e-ui/e2e/chat.user.spec.ts
@@ -0,0 +1,101 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('chat (alice)', () => {
+	test('post a lobby message and see it in the log', async ({ page }) => {
+		const body = `e2e chat ${Date.now()}`;
+
+		await page.goto('/chat');
+		await expect(page.getByRole('heading', { name: /lobby/i })).toBeVisible({
+			timeout: 20_000
+		});
+
+		await page.locator('#chat-body').fill(body);
+		await page.getByRole('button', { name: /send/i }).click();
+
+		const msg = page.locator('.ch-msg', { hasText: body });
+		await expect(msg).toBeVisible({ timeout: 20_000 });
+		await expect(msg.locator('.ch-body')).toHaveText(body);
+
+		// Reload — message should still be there (RM + SSR)
+		await page.reload();
+		await expect(page.locator('.ch-msg', { hasText: body })).toBeVisible({
+			timeout: 20_000
+		});
+	});
+
+	test('sending preserves the rendered log while revalidating', async ({ page }) => {
+		await page.goto('/chat');
+		await expect(page.getByRole('heading', { name: /lobby/i })).toBeVisible({
+			timeout: 20_000
+		});
+
+		const baseline = `continuity baseline ${Date.now()}`;
+		await page.locator('#chat-body').fill(baseline);
+		const baselineResponse = page.waitForResponse(
+			(response) =>
+				(response.request().postData() ?? '').includes('chat_messages_post')
+		);
+		await page.getByRole('button', { name: /send/i }).click();
+		await expect(page.locator('.ch-msg', { hasText: baseline })).toBeVisible({
+			timeout: 20_000
+		});
+		await baselineResponse;
+
+		const navigations: string[] = [];
+		page.on('framenavigated', (frame) => {
+			if (frame === page.mainFrame()) navigations.push(frame.url());
+		});
+		await page.evaluate(() => {
+			const samples = [document.querySelectorAll('.ch-msg').length];
+			const observer = new MutationObserver(() => {
+				samples.push(document.querySelectorAll('.ch-msg').length);
+			});
+			observer.observe(document.querySelector('.ch-log')!, {
+				childList: true,
+				subtree: true,
+				characterData: true
+			});
+			Object.assign(globalThis, {
+				__distributedChatContinuitySamples: samples,
+				__distributedChatContinuityObserver: observer
+			});
+		});
+
+		await page.route('**/graphql', async (route) => {
+			if (!(route.request().postData() ?? '').includes('chat_messages_post')) {
+				await route.continue();
+				return;
+			}
+			const response = await route.fetch();
+			await new Promise((resolve) => setTimeout(resolve, 700));
+			await route.fulfill({ response });
+		});
+
+		const body = `continuity message ${Date.now()}`;
+		await page.locator('#chat-body').fill(body);
+		const commandResponse = page.waitForResponse(
+			(response) =>
+				(response.request().postData() ?? '').includes('chat_messages_post')
+		);
+		await page.getByRole('button', { name: /send/i }).click();
+		await expect(page.locator('.ch-msg', { hasText: body })).toBeVisible({
+			timeout: 400
+		});
+		await commandResponse;
+		await page.unrouteAll({ behavior: 'wait' });
+
+		const samples = await page.evaluate(() => {
+			const state = globalThis as typeof globalThis & {
+				__distributedChatContinuitySamples: number[];
+				__distributedChatContinuityObserver: MutationObserver;
+			};
+			state.__distributedChatContinuityObserver.disconnect();
+			return state.__distributedChatContinuitySamples;
+		});
+		expect(navigations, 'commands must not navigate or reload the page').toEqual([]);
+		expect(
+			Math.min(...samples),
+			'stale-while-revalidate must never replace the known log with an empty view'
+		).toBeGreaterThan(0);
+	});
+});
diff --git a/tests/e2e-ui/e2e/helpers/login.ts b/tests/e2e-ui/e2e/helpers/login.ts
new file mode 100644
index 00000000..d7e03b7c
--- /dev/null
+++ b/tests/e2e-ui/e2e/helpers/login.ts
@@ -0,0 +1,36 @@
+import type { Page } from '@playwright/test';
+
+export const DEMO_PASSWORD = process.env.E2E_HUMAN_PASSWORD || 'Password1!';
+
+/**
+ * Full OIDC path through e2e-ui custom Login V2:
+ * protected route → /login → Auth.js → Zitadel authorize → /login?authRequest=…
+ * → password form → Auth.js callback → destination.
+ */
+export async function loginAs(
+	page: Page,
+	username: string,
+	password: string = DEMO_PASSWORD,
+	destination = '/todos'
+) {
+	await page.goto(destination, { waitUntil: 'domcontentloaded' });
+
+	// May bounce through OIDC; land on custom login with username field.
+	await page.waitForURL(/\/login/, { timeout: 45_000 });
+	await page.waitForSelector('#loginName', { timeout: 45_000 });
+
+	await page.locator('#loginName').fill(username);
+	await page.locator('#password').fill(password);
+	await page.getByRole('button', { name: /continue/i }).click();
+
+	// After success we leave /login (callback then app route).
+	await page.waitForURL((url) => !url.pathname.startsWith('/login'), {
+		timeout: 60_000
+	});
+}
+
+export async function expectLoggedInNav(page: Page) {
+	// Home / layout usually shows session or product chrome once authed.
+	// Destination-specific checks live in each suite.
+	await page.waitForLoadState('networkidle').catch(() => {});
+}
diff --git a/tests/e2e-ui/e2e/session.user.spec.ts b/tests/e2e-ui/e2e/session.user.spec.ts
new file mode 100644
index 00000000..477287da
--- /dev/null
+++ b/tests/e2e-ui/e2e/session.user.spec.ts
@@ -0,0 +1,13 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('session (alice)', () => {
+	test('session page shows signed-in identity', async ({ page }) => {
+		await page.goto('/session');
+		// Should not bounce to login
+		await expect(page).not.toHaveURL(/\/login/, { timeout: 15_000 });
+		await expect(page.getByRole('heading').first()).toBeVisible({ timeout: 20_000 });
+		// Token / identity chrome
+		const body = await page.locator('body').innerText();
+		expect(body.length).toBeGreaterThan(20);
+	});
+});
diff --git a/tests/e2e-ui/e2e/todos.user.spec.ts b/tests/e2e-ui/e2e/todos.user.spec.ts
new file mode 100644
index 00000000..e080b9bf
--- /dev/null
+++ b/tests/e2e-ui/e2e/todos.user.spec.ts
@@ -0,0 +1,388 @@
+import { test, expect } from '@playwright/test';
+
+async function visibleTodoOrders(page: import('@playwright/test').Page) {
+	return page.locator('.list').evaluateAll((lists) =>
+		lists.map((list) =>
+			[...list.querySelectorAll<HTMLElement>('[data-todo-id]')].map(
+				(item) => item.dataset.todoId ?? ''
+			)
+		)
+	);
+}
+
+async function todoOrderInPanel(
+	page: import('@playwright/test').Page,
+	heading: RegExp
+) {
+	return page
+		.locator('.panel')
+		.filter({ has: page.getByRole('heading', { name: heading }) })
+		.locator('[data-todo-id]')
+		.evaluateAll((items) =>
+			items.map((item) => (item as HTMLElement).dataset.todoId ?? '')
+		);
+}
+
+type TodoOrderFrame = {
+	open: string[];
+	done: string[];
+};
+
+async function startTodoOrderTrace(page: import('@playwright/test').Page) {
+	await page.evaluate(() => {
+		const state = globalThis as typeof globalThis & {
+			__todoOrderTrace?: {
+				frames: TodoOrderFrame[];
+				frame: number;
+			};
+		};
+		const frames: TodoOrderFrame[] = [];
+		const orderFor = (name: string) => {
+			const panel = [...document.querySelectorAll<HTMLElement>('.panel')].find(
+				(candidate) =>
+					candidate.querySelector('h2')?.textContent?.trim().toLowerCase() ===
+					name
+			);
+			return panel
+				? [...panel.querySelectorAll<HTMLElement>('[data-todo-id]')].map(
+						(item) => item.dataset.todoId ?? ''
+					)
+				: [];
+		};
+		const sample = () => {
+			const order = { open: orderFor('open'), done: orderFor('done') };
+			const previous = frames.at(-1);
+			if (
+				previous === undefined ||
+				JSON.stringify(previous) !== JSON.stringify(order)
+			) {
+				frames.push(order);
+			}
+			state.__todoOrderTrace!.frame = requestAnimationFrame(sample);
+		};
+		state.__todoOrderTrace = {
+			frames,
+			frame: requestAnimationFrame(sample)
+		};
+	});
+}
+
+async function stopTodoOrderTrace(page: import('@playwright/test').Page) {
+	return page.evaluate(() => {
+		const state = globalThis as typeof globalThis & {
+			__todoOrderTrace?: {
+				frames: TodoOrderFrame[];
+				frame: number;
+			};
+		};
+		const trace = state.__todoOrderTrace;
+		if (trace === undefined) return [];
+		cancelAnimationFrame(trace.frame);
+		delete state.__todoOrderTrace;
+		return trace.frames;
+	});
+}
+
+function expectBinarySorted(orders: string[][]) {
+	for (const ids of orders) {
+		expect(ids, `todo ids must stay in generated binary order: ${ids.join(', ')}`).toEqual(
+			[...ids].sort()
+		);
+	}
+}
+
+function sameTodoOrder(left: TodoOrderFrame, right: TodoOrderFrame) {
+	return (
+		JSON.stringify(left.open) === JSON.stringify(right.open) &&
+		JSON.stringify(left.done) === JSON.stringify(right.done)
+	);
+}
+
+test.describe('todos (alice)', () => {
+	test('create, complete, reopen, archive', async ({ page }) => {
+		const title = `e2e todo ${Date.now()}`;
+
+		await page.goto('/todos');
+		await expect(page.getByRole('heading', { name: /todos/i })).toBeVisible();
+
+		// Create
+		await page.locator('#todo-title').fill(title);
+		await page.getByRole('button', { name: /^add$/i }).click();
+		const openItem = page
+			.locator('.panel')
+			.filter({ has: page.getByRole('heading', { name: /^open$/i }) })
+			.locator('.item', { hasText: title });
+		await expect(openItem).toBeVisible({ timeout: 15_000 });
+
+		// Complete
+		await openItem.getByRole('button', { name: /^done$/i }).click();
+		const doneItem = page
+			.locator('.panel')
+			.filter({ has: page.getByRole('heading', { name: /^done$/i }) })
+			.locator('.item', { hasText: title });
+		await expect(doneItem).toBeVisible({ timeout: 15_000 });
+
+		// Reopen (prefer the text button; wait until not busy)
+		const reopen = doneItem.getByRole('button', { name: 'Reopen', exact: true });
+		await expect(reopen).toBeEnabled({ timeout: 10_000 });
+		await reopen.click();
+		const openAgain = page
+			.locator('.panel')
+			.filter({ has: page.getByRole('heading', { name: /^open$/i }) })
+			.locator('.item', { hasText: title });
+		await expect(openAgain).toBeVisible({ timeout: 15_000 });
+
+		// Archive
+		const archive = openAgain.getByRole('button', { name: 'Archive', exact: true });
+		await expect(archive).toBeEnabled({ timeout: 10_000 });
+		await archive.click();
+		const archiveDetails = page.locator('details.archive');
+		await expect(archiveDetails).toBeVisible({ timeout: 15_000 });
+		await archiveDetails.locator('summary').click();
+		await expect(archiveDetails.locator('.item', { hasText: title })).toBeVisible({
+			timeout: 10_000
+		});
+
+		// Persist across navigation (async projectors may lag a beat)
+		await expect
+			.poll(
+				async () => {
+					await page.goto('/todos');
+					const again = page.locator('details.archive');
+					if (!(await again.isVisible().catch(() => false))) return false;
+					await again.locator('summary').click();
+					return again.locator('.item', { hasText: title }).isVisible();
+				},
+				{ timeout: 25_000 }
+			)
+			.toBeTruthy();
+	});
+
+	test('empty title cannot submit', async ({ page }) => {
+		await page.goto('/todos');
+		const add = page.getByRole('button', { name: /^add$/i });
+		await expect(add).toBeDisabled();
+	});
+
+	test('commands preserve rendered cache while revalidating', async ({ page }) => {
+		await page.goto('/todos');
+		await expect(page.getByRole('heading', { name: /todos/i })).toBeVisible();
+
+		// Establish one row that must remain visible while later commands update.
+		const baseline = `continuity baseline ${Date.now()}`;
+		await page.locator('#todo-title').fill(baseline);
+		await page.getByRole('button', { name: /^add$/i }).click();
+		await expect(page.locator('.item', { hasText: baseline })).toBeVisible();
+
+		const navigations: string[] = [];
+		page.on('framenavigated', (frame) => {
+			if (frame === page.mainFrame()) navigations.push(frame.url());
+		});
+		await page.evaluate(() => {
+			const samples = [document.querySelectorAll('.item').length];
+			const observer = new MutationObserver(() => {
+				samples.push(document.querySelectorAll('.item').length);
+			});
+			observer.observe(document.querySelector('.board')!, {
+				childList: true,
+				subtree: true,
+				characterData: true
+			});
+			Object.assign(globalThis, {
+				__distributedContinuitySamples: samples,
+				__distributedContinuityObserver: observer
+			});
+		});
+
+		const changed = `continuity changed ${Date.now()}`;
+		await page.locator('#todo-title').fill(changed);
+		await page.getByRole('button', { name: /^add$/i }).click();
+		const openItem = page
+			.locator('.panel')
+			.filter({ has: page.getByRole('heading', { name: /^open$/i }) })
+			.locator('.item', { hasText: changed });
+		await expect(openItem).toBeVisible();
+		await openItem.getByRole('button', { name: /^done$/i }).click();
+		await expect(
+			page
+				.locator('.panel')
+				.filter({ has: page.getByRole('heading', { name: /^done$/i }) })
+				.locator('.item', { hasText: changed })
+		).toBeVisible();
+
+		const samples = await page.evaluate(() => {
+			const state = globalThis as typeof globalThis & {
+				__distributedContinuitySamples: number[];
+				__distributedContinuityObserver: MutationObserver;
+			};
+			state.__distributedContinuityObserver.disconnect();
+			return state.__distributedContinuitySamples;
+		});
+		expect(navigations, 'commands must not navigate or reload the page').toEqual([]);
+		expect(
+			Math.min(...samples),
+			'stale-while-revalidate must never replace known rows with an empty view'
+		).toBeGreaterThan(0);
+	});
+
+	test('optimistic and authoritative states keep the same generated order', async ({
+		page
+	}) => {
+		await page.goto('/todos');
+		await expect(page.getByRole('heading', { name: /todos/i })).toBeVisible();
+
+		await page.route('**/graphql', async (route) => {
+			const body = route.request().postData() ?? '';
+			if (
+				!body.includes('todos_create') &&
+				!body.includes('todos_complete') &&
+				!body.includes('todos_reopen')
+			) {
+				await route.continue();
+				return;
+			}
+			const response = await route.fetch();
+			await new Promise((resolve) => setTimeout(resolve, 700));
+			await route.fulfill({ response });
+		});
+		let completeRequests = 0;
+		page.on('request', (request) => {
+			if ((request.postData() ?? '').includes('todos_complete')) {
+				completeRequests += 1;
+			}
+		});
+
+		const title = `ordered optimism ${Date.now()}`;
+		await page.locator('#todo-title').fill(title);
+		const createResponse = page.waitForResponse(
+			(response) =>
+				(response.request().postData() ?? '').includes('todos_create')
+		);
+		await page.getByRole('button', { name: /^add$/i }).click();
+		const openItem = page
+			.locator('.panel')
+			.filter({ has: page.getByRole('heading', { name: /^open$/i }) })
+			.locator('.item', { hasText: title });
+		// Create upserts the record optimistically but list membership is
+		// authoritative (index write); the delayed route proves later complete/
+		// reopen transitions paint from the optimistic layer before the wire.
+		await createResponse;
+		await expect(openItem).toBeVisible({ timeout: 5_000 });
+		expect(
+			await page.locator('.board button:disabled').count(),
+			'routine command concurrency guards must not flash Todo row controls disabled'
+		).toBe(0);
+		expectBinarySorted(await visibleTodoOrders(page));
+		const todoId = await openItem.getAttribute('data-todo-id');
+		expect(todoId).not.toBeNull();
+		const beforeComplete = {
+			open: await todoOrderInPanel(page, /^open$/i),
+			done: await todoOrderInPanel(page, /^done$/i)
+		};
+		const afterComplete = {
+			open: beforeComplete.open.filter((id) => id !== todoId),
+			done: [...beforeComplete.done, todoId!].sort()
+		};
+		await startTodoOrderTrace(page);
+		const completeResponse = page.waitForResponse(
+			(response) =>
+				(response.request().postData() ?? '').includes('todos_complete')
+		);
+		await openItem.getByRole('button', { name: /^done$/i }).evaluate((button) => {
+			button.click();
+			button.click();
+		});
+		const doneItem = page
+			.locator('.panel')
+			.filter({ has: page.getByRole('heading', { name: /^done$/i }) })
+			.locator('.item', { hasText: title });
+		await expect(doneItem).toBeVisible({ timeout: 400 });
+		expect(
+			await page.locator('.board button:disabled').count(),
+			'routine command concurrency guards must not flash Todo row controls disabled'
+		).toBe(0);
+		expectBinarySorted(await visibleTodoOrders(page));
+		await completeResponse;
+		expect(
+			completeRequests,
+			'optimistic state must suppress a duplicate action without disabling controls'
+		).toBe(1);
+		await expect(doneItem).toBeVisible();
+		expectBinarySorted(await visibleTodoOrders(page));
+		await page.waitForTimeout(750);
+		const completeOrderFrames = await stopTodoOrderTrace(page);
+		expect(
+			completeOrderFrames.every(
+				(order) =>
+					sameTodoOrder(order, beforeComplete) ||
+					sameTodoOrder(order, afterComplete)
+			),
+			`complete rendered an intermediate non-generated order: ${JSON.stringify(completeOrderFrames)}`
+		).toBe(true);
+
+		await startTodoOrderTrace(page);
+		const reopenResponse = page.waitForResponse((response) =>
+			(response.request().postData() ?? '').includes('todos_reopen')
+		);
+		await doneItem.getByRole('button', { name: /^reopen$/i }).click();
+		const reopenedItem = page
+			.locator('.panel')
+			.filter({ has: page.getByRole('heading', { name: /^open$/i }) })
+			.locator('.item', { hasText: title });
+		// Reopen must paint the row back into Open before the delayed wire returns.
+		await expect(reopenedItem).toBeVisible({ timeout: 400 });
+		expect(
+			await page.locator('.board button:disabled').count(),
+			'routine command concurrency guards must not flash Todo row controls disabled'
+		).toBe(0);
+		await reopenResponse;
+		await page.waitForTimeout(750);
+		const reopenOrderFrames = await stopTodoOrderTrace(page);
+		// Authoritative membership order is binary by todo_id; optimistic reopen may
+		// temporarily prepend before the index reconciles on the wire response.
+		expect(
+			reopenOrderFrames.some((order) => sameTodoOrder(order, beforeComplete)),
+			`reopen never settled on generated open order: ${JSON.stringify(reopenOrderFrames)}`
+		).toBe(true);
+		await expect(reopenedItem).toBeVisible();
+		expect(
+			await todoOrderInPanel(page, /^open$/i),
+			'reopen must restore generated open order after command convergence'
+		).toEqual(beforeComplete.open);
+
+		// Repeat after both earlier commands have converged so the invariant also
+		// covers a row that is fully authoritative before the next transition.
+		await startTodoOrderTrace(page);
+		const authoritativeCompleteResponse = page.waitForResponse((response) =>
+			(response.request().postData() ?? '').includes('todos_complete')
+		);
+		await reopenedItem.getByRole('button', { name: /^done$/i }).click();
+		await authoritativeCompleteResponse;
+		await page.waitForTimeout(750);
+		const authoritativeCompleteFrames = await stopTodoOrderTrace(page);
+		expect(
+			authoritativeCompleteFrames.every(
+				(order) =>
+					sameTodoOrder(order, beforeComplete) ||
+					sameTodoOrder(order, afterComplete)
+			),
+			`authoritative complete rendered an intermediate order: ${JSON.stringify(authoritativeCompleteFrames)}`
+		).toBe(true);
+
+		await startTodoOrderTrace(page);
+		const authoritativeReopenResponse = page.waitForResponse((response) =>
+			(response.request().postData() ?? '').includes('todos_reopen')
+		);
+		await doneItem.getByRole('button', { name: /^reopen$/i }).click();
+		await authoritativeReopenResponse;
+		await page.waitForTimeout(750);
+		const authoritativeReopenFrames = await stopTodoOrderTrace(page);
+		expect(
+			authoritativeReopenFrames.some((order) => sameTodoOrder(order, beforeComplete)),
+			`authoritative reopen never settled on generated open order: ${JSON.stringify(authoritativeReopenFrames)}`
+		).toBe(true);
+		await expect(reopenedItem).toBeVisible();
+		expect(await todoOrderInPanel(page, /^open$/i)).toEqual(beforeComplete.open);
+		await page.unrouteAll({ behavior: 'wait' });
+	});
+});
diff --git a/tests/e2e-ui/e2e/unauth.anon.spec.ts b/tests/e2e-ui/e2e/unauth.anon.spec.ts
new file mode 100644
index 00000000..f04ff733
--- /dev/null
+++ b/tests/e2e-ui/e2e/unauth.anon.spec.ts
@@ -0,0 +1,26 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('unauthenticated access', () => {
+	test('protected routes redirect toward login / OIDC', async ({ page }) => {
+		for (const path of ['/todos', '/chat', '/blob', '/admin', '/session']) {
+			await page.goto(path, { waitUntil: 'domcontentloaded' });
+			// hooks → /login?callbackUrl=… → may immediately start OIDC
+			await page.waitForURL(
+				(url) =>
+					url.pathname.includes('/login') ||
+					url.pathname.includes('/signin') ||
+					url.pathname.includes('/auth') ||
+					url.hostname.includes('18080') ||
+					url.pathname.includes('/oauth'),
+				{ timeout: 45_000 }
+			);
+		}
+	});
+
+	test('home page is reachable without a session', async ({ page }) => {
+		await page.goto('/');
+		await expect(page.getByRole('heading', { level: 1 }).first()).toBeVisible({
+			timeout: 20_000
+		});
+	});
+});
diff --git a/tests/e2e-ui/package-lock.json b/tests/e2e-ui/package-lock.json
new file mode 100644
index 00000000..095a5a7a
--- /dev/null
+++ b/tests/e2e-ui/package-lock.json
@@ -0,0 +1,76 @@
+{
+  "name": "e2e-ui-browser",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "e2e-ui-browser",
+      "devDependencies": {
+        "@playwright/test": "^1.51.0"
+      }
+    },
+    "node_modules/@playwright/test": {
+      "version": "1.61.1",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.61.1.tgz",
+      "integrity": "sha512-8nKv6+0RJSL9FE4jYOEGXnPeM/Hg12qZpmqzZjRh3qM0Y7c3z1mrOTfFLids72RDQYVh9WpLEfR5WdpNX4fkig==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright": "1.61.1"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/playwright": {
+      "version": "1.61.1",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.61.1.tgz",
+      "integrity": "sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.61.1"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.61.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.61.1.tgz",
+      "integrity": "sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    }
+  }
+}
diff --git a/tests/e2e-ui/package.json b/tests/e2e-ui/package.json
new file mode 100644
index 00000000..4c63088d
--- /dev/null
+++ b/tests/e2e-ui/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "e2e-ui-browser",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test:browser": "playwright test",
+    "test:browser:ui": "playwright test --ui",
+    "test:browser:headed": "playwright test --headed",
+    "test:browser:report": "playwright show-report"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.51.0"
+  }
+}
diff --git a/tests/e2e-ui/playwright.config.ts b/tests/e2e-ui/playwright.config.ts
new file mode 100644
index 00000000..4882bc60
--- /dev/null
+++ b/tests/e2e-ui/playwright.config.ts
@@ -0,0 +1,91 @@
+import { defineConfig, devices } from '@playwright/test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+
+/** Load KEY=VALUE from e2e-ui.env without treating values as shell. */
+function loadEnvFile(file: string) {
+	if (!fs.existsSync(file)) return;
+	for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+		const t = line.trim();
+		if (!t || t.startsWith('#')) continue;
+		const eq = t.indexOf('=');
+		if (eq < 0) continue;
+		const key = t.slice(0, eq).trim();
+		let val = t.slice(eq + 1).trim();
+		if (
+			(val.startsWith('"') && val.endsWith('"')) ||
+			(val.startsWith("'") && val.endsWith("'"))
+		) {
+			val = val.slice(1, -1);
+		}
+		if (process.env[key] === undefined) process.env[key] = val;
+	}
+}
+
+loadEnvFile(path.join(root, 'e2e-ui.env'));
+
+const baseURL = process.env.E2E_UI_ORIGIN || process.env.UI_URL || 'http://localhost:5180';
+
+/**
+ * Browser tests for e2e-ui.
+ *
+ * Requires a live stack (Postgres + Zitadel + API + UI):
+ *   make up && make run
+ * Then:
+ *   npm install && npx playwright install chromium
+ *   npm run test:browser
+ */
+export default defineConfig({
+	testDir: './e2e',
+	fullyParallel: false,
+	forbidOnly: !!process.env.CI,
+	retries: process.env.CI ? 1 : 0,
+	workers: 1,
+	timeout: 90_000,
+	expect: { timeout: 20_000 },
+	reporter: [['list'], ['html', { open: 'never', outputFolder: 'playwright-report' }]],
+	use: {
+		baseURL,
+		trace: 'on-first-retry',
+		screenshot: 'only-on-failure',
+		video: 'retain-on-failure',
+		// Local Auth.js cookies over HTTP
+		ignoreHTTPSErrors: true
+	},
+	projects: [
+		{
+			name: 'setup-alice',
+			testMatch: /auth\.alice\.setup\.ts/
+		},
+		{
+			name: 'setup-admin',
+			testMatch: /auth\.admin\.setup\.ts/
+		},
+		{
+			name: 'chromium-user',
+			dependencies: ['setup-alice'],
+			testMatch: /.*\.user\.spec\.ts/,
+			use: {
+				...devices['Desktop Chrome'],
+				storageState: path.join(root, 'e2e/.auth/alice.json')
+			}
+		},
+		{
+			name: 'chromium-admin',
+			dependencies: ['setup-admin'],
+			testMatch: /.*\.admin\.spec\.ts/,
+			use: {
+				...devices['Desktop Chrome'],
+				storageState: path.join(root, 'e2e/.auth/admin.json')
+			}
+		},
+		{
+			name: 'chromium-anon',
+			testMatch: /.*\.anon\.spec\.ts/,
+			use: { ...devices['Desktop Chrome'] }
+		}
+	]
+});
diff --git a/tests/e2e-ui/scripts/up.sh b/tests/e2e-ui/scripts/up.sh
new file mode 100755
index 00000000..a0014ece
--- /dev/null
+++ b/tests/e2e-ui/scripts/up.sh
@@ -0,0 +1,615 @@
+#!/usr/bin/env bash
+# Bring up e2e-ui Docker stack (app Postgres + Zitadel) and bootstrap OIDC.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+DIST_ROOT="$(cd "$ROOT/../.." && pwd)"
+COMPOSE="$ROOT/docker/docker-compose.yml"
+MACHINEKEY_DIR="$ROOT/docker/machinekey"
+ZITADEL_HOST="${ZITADEL_HOST:-http://localhost:18080}"
+OUT="${E2E_UI_ENV:-$ROOT/e2e-ui.env}"
+# Prefer localhost (not 127.0.0.1): SvelteKit only skips Secure cookies for
+# hostname === "localhost" over http. 127.0.0.1 forces Secure and breaks OIDC.
+UI_ORIGIN="${E2E_UI_ORIGIN:-http://localhost:5180}"
+API_ORIGIN="${E2E_API_ORIGIN:-http://127.0.0.1:8791}"
+PROJECT_NAME="${E2E_OIDC_PROJECT:-e2e-ui}"
+APP_NAME="${E2E_OIDC_APP:-e2e-ui-web}"
+API_APP_NAME="${E2E_OIDC_API_APP:-e2e-ui-api}"
+
+need() { command -v "$1" >/dev/null 2>&1 || { echo "ERROR: $1 required"; exit 1; }; }
+need docker
+need jq
+need curl
+need openssl
+
+b64url() { openssl base64 -e -A | tr '+/' '-_' | tr -d '='; }
+
+echo "==> machinekey dir"
+mkdir -p "$MACHINEKEY_DIR/e2e"
+chmod 777 "$MACHINEKEY_DIR" "$MACHINEKEY_DIR/e2e"
+# Preserve FirstInstance admin key; clear only e2e keys
+find "$MACHINEKEY_DIR" -mindepth 1 -maxdepth 1 ! -name 'e2e' ! -name '*.json' -exec rm -rf {} + 2>/dev/null || true
+rm -rf "$MACHINEKEY_DIR/e2e"
+mkdir -p "$MACHINEKEY_DIR/e2e"
+chmod 777 "$MACHINEKEY_DIR" "$MACHINEKEY_DIR/e2e"
+
+echo "==> docker compose up"
+docker compose -f "$COMPOSE" up -d --remove-orphans
+
+# Heartbeat while waiting (stderr so command substitutions stay clean).
+wait_tick() {
+  local label="$1" n="$2" every="${3:-5}"
+  if (( n == 1 || n % every == 0 )); then
+    echo "    … $label (try $n)" >&2
+  fi
+}
+
+echo "==> Wait for app Postgres"
+for i in $(seq 1 60); do
+  if docker compose -f "$COMPOSE" exec -T app-db pg_isready -U e2e -d e2e_ui >/dev/null 2>&1; then
+    echo "    app-db ready (${i}s)"
+    break
+  fi
+  wait_tick "app-db" "$i" 10
+  sleep 1
+  if [[ $i -eq 60 ]]; then
+    echo "ERROR: app-db not ready"
+    docker compose -f "$COMPOSE" logs --tail=40 app-db || true
+    exit 1
+  fi
+done
+
+echo "==> Wait for Zitadel (API via proxy; first boot can take ~30–90s)"
+for i in $(seq 1 90); do
+  if curl -fsS --max-time 2 "$ZITADEL_HOST/debug/healthz" >/dev/null 2>&1 \
+    || curl -fsS --max-time 2 "$ZITADEL_HOST/debug/ready" >/dev/null 2>&1; then
+    echo "    zitadel probe ok (${i} tries)"
+    break
+  fi
+  if ! docker compose -f "$COMPOSE" ps --status running --services 2>/dev/null | grep -q '^zitadel$'; then
+    echo "ERROR: zitadel not running"
+    docker compose -f "$COMPOSE" logs --tail=80 zitadel || true
+    exit 1
+  fi
+  wait_tick "zitadel health" "$i" 5
+  sleep 2
+  if [[ $i -eq 90 ]]; then
+    echo "ERROR: Zitadel unreachable"
+    docker compose -f "$COMPOSE" logs --tail=100 zitadel || true
+    exit 1
+  fi
+done
+
+echo "==> Wait for FirstInstance machine key"
+KEYFILE=""
+for i in $(seq 1 60); do
+  shopt -s nullglob
+  keys=("$MACHINEKEY_DIR"/*.json)
+  shopt -u nullglob
+  if [[ ${#keys[@]} -gt 0 && -s "${keys[0]}" ]]; then
+    KEYFILE="${keys[0]}"
+    echo "    found $KEYFILE"
+    break
+  fi
+  wait_tick "machine key" "$i" 5
+  sleep 2
+  if [[ $i -eq 60 ]]; then
+    echo "    recreating stack for FirstInstance key"
+    docker compose -f "$COMPOSE" down -v || true
+    mkdir -p "$MACHINEKEY_DIR/e2e" && chmod 777 "$MACHINEKEY_DIR" "$MACHINEKEY_DIR/e2e"
+    docker compose -f "$COMPOSE" up -d --remove-orphans
+    for j in $(seq 1 90); do
+      shopt -s nullglob
+      keys=("$MACHINEKEY_DIR"/*.json)
+      shopt -u nullglob
+      if [[ ${#keys[@]} -gt 0 && -s "${keys[0]}" ]]; then
+        KEYFILE="${keys[0]}"
+        break 2
+      fi
+      wait_tick "machine key (after recreate)" "$j" 5
+      sleep 2
+    done
+  fi
+done
+if [[ -z "$KEYFILE" || ! -s "$KEYFILE" ]]; then
+  echo "ERROR: no admin SA key"
+  ls -la "$MACHINEKEY_DIR" || true
+  exit 1
+fi
+
+USER_ID=$(jq -r .userId "$KEYFILE")
+KEY_ID=$(jq -r .keyId "$KEYFILE")
+KEY_PEM=$(jq -r .key "$KEYFILE")
+
+mint_admin() {
+  local now exp header payload sig jwt
+  now=$(date +%s); exp=$((now + 60))
+  header=$(printf '{"alg":"RS256","typ":"JWT","kid":"%s"}' "$KEY_ID" | b64url)
+  payload=$(printf '{"iss":"%s","sub":"%s","aud":"%s","iat":%s,"exp":%s}' \
+    "$USER_ID" "$USER_ID" "$ZITADEL_HOST" "$now" "$exp" | b64url)
+  local tmp; tmp=$(mktemp)
+  printf '%s\n' "$KEY_PEM" > "$tmp"
+  sig=$(printf '%s' "${header}.${payload}" | openssl dgst -sha256 -sign "$tmp" | b64url)
+  rm -f "$tmp"
+  jwt="${header}.${payload}.${sig}"
+  curl -sS --max-time 10 -X POST "$ZITADEL_HOST/oauth/v2/token" \
+    -H 'Content-Type: application/x-www-form-urlencoded' \
+    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
+    --data-urlencode "scope=openid urn:zitadel:iam:org:project:id:zitadel:aud" \
+    --data-urlencode "assertion=$jwt" 2>/dev/null | jq -r '.access_token // empty'
+}
+
+echo "==> Admin token (JWT-bearer mint)"
+ACCESS_TOKEN=""
+for i in $(seq 1 45); do
+  ACCESS_TOKEN=$(mint_admin)
+  if [[ -n "$ACCESS_TOKEN" && "$ACCESS_TOKEN" != "null" ]]; then
+    echo "    ok (try $i)"
+    break
+  fi
+  wait_tick "admin token" "$i" 3
+  sleep 2
+done
+if [[ -z "$ACCESS_TOKEN" || "$ACCESS_TOKEN" == "null" ]]; then
+  echo "ERROR: admin token mint failed"
+  exit 1
+fi
+
+# Management API helper.
+# - Retries transient 5xx / empty with progress.
+# - Treats 409 as success (idempotent re-bootstrap: role/user already exists).
+# - Does NOT silently spin for 90s on permanent client errors.
+api() {
+  local method="$1" path="$2" body="${3:-}" out http_code attempt
+  local max_attempts=30
+  for attempt in $(seq 1 "$max_attempts"); do
+    if [[ -n "$body" ]]; then
+      out=$(curl -sS --max-time 15 -w '\n%{http_code}' -X "$method" "$ZITADEL_HOST$path" \
+        -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -d "$body" || true)
+    else
+      out=$(curl -sS --max-time 15 -w '\n%{http_code}' -X "$method" "$ZITADEL_HOST$path" \
+        -H "Authorization: Bearer $ACCESS_TOKEN" || true)
+    fi
+    http_code=$(echo "$out" | tail -n1)
+    out=$(echo "$out" | sed '$d')
+    if [[ "$http_code" == "200" || "$http_code" == "201" ]]; then
+      printf '%s' "$out"; return 0
+    fi
+    # Already exists / conflict — fine for re-runs of make up
+    if [[ "$http_code" == "409" ]]; then
+      printf '%s' "$out"; return 0
+    fi
+    if [[ "$http_code" == "401" || "$http_code" == "403" ]]; then
+      echo "ERROR: $method $path → $http_code" >&2; echo "$out" >&2; return 1
+    fi
+    # Permanent-ish client errors: fail fast (don't burn ~minutes)
+    if [[ "$http_code" =~ ^4[0-9][0-9]$ ]]; then
+      echo "ERROR: $method $path → HTTP $http_code" >&2
+      echo "$out" >&2
+      return 1
+    fi
+    wait_tick "$method $path (HTTP ${http_code:-?})" "$attempt" 3
+    sleep 2
+  done
+  echo "ERROR: $method $path not ready (HTTP $http_code)" >&2; return 1
+}
+
+echo "==> Management API ready"
+api POST /management/v1/projects/_search '{}' >/dev/null
+echo "    ok"
+
+# Login V2 base URI: Fieldnote UI origin (custom /login pages), NOT Zitadel's
+# stock Next.js login image. Authorize redirects to:
+#   ${LOGIN_V2_BASE_URI}/login?authRequest=V2_…
+# Auth.js still owns OIDC (PKCE + code exchange); Session API finalizes on the app.
+LOGIN_V2_BASE_URI="${LOGIN_V2_BASE_URI:-$UI_ORIGIN}"
+LOGIN_V2_BASE_URI="${LOGIN_V2_BASE_URI%/}"
+
+# Instance-wide Login V2. required=true → all apps use Login V2 + baseUri.
+echo "==> Instance features: Login V2 custom UI (baseUri=$LOGIN_V2_BASE_URI)"
+FEAT_BODY=$(jq -n --arg base "$LOGIN_V2_BASE_URI" '{
+  loginV2: { required: true, baseUri: $base },
+  consoleUseV2UserApi: true
+}')
+FEAT_RESP=$(curl -sS --max-time 15 -w '\n%{http_code}' -X PUT "$ZITADEL_HOST/v2/features/instance" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
+  -d "$FEAT_BODY" || true)
+FEAT_CODE=$(echo "$FEAT_RESP" | tail -n1)
+FEAT_OUT=$(echo "$FEAT_RESP" | sed '$d')
+if [[ "$FEAT_CODE" == "200" || "$FEAT_CODE" == "201" ]]; then
+  echo "    loginV2 feature set (HTTP $FEAT_CODE)"
+else
+  echo "    WARN: set instance features HTTP $FEAT_CODE — $FEAT_OUT"
+fi
+
+# ---- login-client PAT ----
+# IAM_LOGIN_CLIENT PAT for the e2e-ui custom login pages (Session + User v2 +
+# OIDC CreateCallback). Also kept for optional stock zitadel-login container.
+# Always mint a fresh PAT: after compose recreate the DB, an old pat is invalid.
+LOGIN_CLIENT_DIR="$ROOT/docker/login-client"
+LOGIN_CLIENT_PAT_FILE="$LOGIN_CLIENT_DIR/pat"
+LOGIN_CLIENT_USERNAME="login-client"
+mkdir -p "$LOGIN_CLIENT_DIR"
+echo "==> login-client machine user + fresh PAT (custom Login V2 pages)"
+USER_SEARCH=$(api POST /management/v1/users/_search "$(jq -n --arg n "$LOGIN_CLIENT_USERNAME" \
+  '{queries: [{userNameQuery: {userName: $n, method: "TEXT_QUERY_METHOD_EQUALS"}}]}')")
+LOGIN_USER_ID=$(echo "$USER_SEARCH" | jq -r '.result[0].id // empty')
+if [[ -z "$LOGIN_USER_ID" ]]; then
+  LOGIN_USER_RESP=$(api POST /management/v1/users/machine "$(jq -n \
+    --arg u "$LOGIN_CLIENT_USERNAME" \
+    '{userName: $u, name: "Login Client", description: "Service user for custom Login V2 UI (Session API)", accessTokenType: "ACCESS_TOKEN_TYPE_BEARER"}')")
+  LOGIN_USER_ID=$(echo "$LOGIN_USER_RESP" | jq -r .userId)
+  [[ -n "$LOGIN_USER_ID" && "$LOGIN_USER_ID" != "null" ]] || {
+    echo "ERROR: login-client create failed"; echo "$LOGIN_USER_RESP"; exit 1
+  }
+  api POST /admin/v1/members "$(jq -n --arg uid "$LOGIN_USER_ID" \
+    '{userId: $uid, roles: ["IAM_LOGIN_CLIENT"]}')" >/dev/null
+  echo "    created login-client user $LOGIN_USER_ID"
+else
+  echo "    existing login-client user $LOGIN_USER_ID"
+fi
+PAT_RESP=$(api POST "/management/v1/users/$LOGIN_USER_ID/pats" \
+  "$(jq -n '{expirationDate: "2029-01-01T00:00:00Z"}')")
+LOGIN_PAT=$(echo "$PAT_RESP" | jq -r .token)
+[[ -n "$LOGIN_PAT" && "$LOGIN_PAT" != "null" ]] || {
+  echo "ERROR: login-client PAT create failed"; echo "$PAT_RESP"; exit 1
+}
+umask 077
+printf '%s' "$LOGIN_PAT" > "$LOGIN_CLIENT_PAT_FILE"
+chmod 600 "$LOGIN_CLIENT_PAT_FILE" 2>/dev/null || true
+echo "    wrote $LOGIN_CLIENT_PAT_FILE (also exported as ZITADEL_SERVICE_USER_TOKEN)"
+# Optional stock login container still mounts the PAT (not used when baseUri is the app).
+docker compose -f "$COMPOSE" up -d --force-recreate zitadel-login >/dev/null 2>&1 \
+  || docker compose -f "$COMPOSE" restart zitadel-login >/dev/null 2>&1 || true
+
+echo "==> Project $PROJECT_NAME"
+PROJECT_SEARCH=$(api POST /management/v1/projects/_search '{}')
+PROJECT_ID=$(echo "$PROJECT_SEARCH" | jq -r --arg n "$PROJECT_NAME" \
+  '.result[]? | select(.name == $n) | .id' | head -n1)
+if [[ -z "$PROJECT_ID" ]]; then
+  PROJECT_ID=$(api POST /management/v1/projects "$(jq -n --arg n "$PROJECT_NAME" '{name: $n}')" | jq -r .id)
+fi
+echo "    project=$PROJECT_ID"
+
+echo "==> Roles user + admin (409 = already exists, ok)"
+for role in user admin; do
+  # api treats 409 as success so re-runs don't spin for minutes
+  if api POST "/management/v1/projects/$PROJECT_ID/roles" \
+    "$(jq -n --arg k "$role" --arg d "$role" '{roleKey: $k, displayName: $d}')" >/dev/null; then
+    echo "    role $role ok"
+  else
+    echo "    role $role skipped/failed (continuing)"
+  fi
+done
+
+# OIDC app: Login V2 baseUri = Fieldnote UI (custom /login). Auth.js keeps PKCE.
+echo "==> Web OIDC app $APP_NAME (Auth.js → authorize → custom /login)"
+APP_SEARCH=$(api POST "/management/v1/projects/$PROJECT_ID/apps/_search" '{}')
+APP_ID=$(echo "$APP_SEARCH" | jq -r --arg n "$APP_NAME" '.result[]? | select(.name == $n) | .id' | head -n1)
+CLIENT_ID=""
+CLIENT_SECRET=""
+if [[ -z "$APP_ID" ]]; then
+  APP_RESP=$(api POST "/management/v1/projects/$PROJECT_ID/apps/oidc" "$(jq -n \
+    --arg name "$APP_NAME" \
+    --arg ui "$UI_ORIGIN" \
+    --arg base "$LOGIN_V2_BASE_URI" \
+    '{
+      name: $name,
+      redirectUris: [
+        ($ui + "/auth/callback/oidc"),
+        ($ui + "/auth/callback"),
+        "http://127.0.0.1:5180/auth/callback/oidc",
+        "http://localhost:5180/auth/callback/oidc"
+      ],
+      responseTypes: ["OIDC_RESPONSE_TYPE_CODE"],
+      grantTypes: [
+        "OIDC_GRANT_TYPE_AUTHORIZATION_CODE",
+        "OIDC_GRANT_TYPE_REFRESH_TOKEN"
+      ],
+      appType: "OIDC_APP_TYPE_WEB",
+      authMethodType: "OIDC_AUTH_METHOD_TYPE_BASIC",
+      postLogoutRedirectUris: [
+        ($ui + "/"),
+        $ui,
+        "http://127.0.0.1:5180/",
+        "http://127.0.0.1:5180",
+        "http://localhost:5180/",
+        "http://localhost:5180"
+      ],
+      version: "OIDC_VERSION_1_0",
+      devMode: true,
+      accessTokenType: "OIDC_TOKEN_TYPE_JWT",
+      accessTokenRoleAssertion: true,
+      idTokenRoleAssertion: true,
+      idTokenUserinfoAssertion: true,
+      loginVersion: { loginV2: { baseUri: $base } }
+    }')")
+  CLIENT_ID=$(echo "$APP_RESP" | jq -r '.clientId // empty')
+  CLIENT_SECRET=$(echo "$APP_RESP" | jq -r '.clientSecret // empty')
+  APP_ID=$(echo "$APP_RESP" | jq -r '.appId // .id // empty')
+  echo "    created web app clientId=$CLIENT_ID (Login V2)"
+else
+  CLIENT_ID=$(echo "$APP_SEARCH" | jq -r --arg n "$APP_NAME" \
+    '.result[]? | select(.name == $n) | .oidcConfig.clientId // empty' | head -n1)
+  echo "    existing web app clientId=$CLIENT_ID (secret only on create — re-create stack if missing)"
+  # Pin Login V2 base URI on re-bootstrap (idempotent).
+  if [[ -n "$APP_ID" && "$APP_ID" != "null" ]]; then
+    UPD=$(curl -sS --max-time 15 -w '\n%{http_code}' -X PUT \
+      "$ZITADEL_HOST/management/v1/projects/$PROJECT_ID/apps/$APP_ID/oidc_config" \
+      -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
+      -d "$(jq -n --arg base "$LOGIN_V2_BASE_URI" --arg ui "$UI_ORIGIN" '{
+        redirectUris: [
+          ($ui + "/auth/callback/oidc"),
+          ($ui + "/auth/callback"),
+          "http://127.0.0.1:5180/auth/callback/oidc",
+          "http://localhost:5180/auth/callback/oidc"
+        ],
+        responseTypes: ["OIDC_RESPONSE_TYPE_CODE"],
+        grantTypes: [
+          "OIDC_GRANT_TYPE_AUTHORIZATION_CODE",
+          "OIDC_GRANT_TYPE_REFRESH_TOKEN"
+        ],
+        appType: "OIDC_APP_TYPE_WEB",
+        authMethodType: "OIDC_AUTH_METHOD_TYPE_BASIC",
+        postLogoutRedirectUris: [
+          ($ui + "/"),
+          $ui,
+          "http://127.0.0.1:5180/",
+          "http://127.0.0.1:5180",
+          "http://localhost:5180/",
+          "http://localhost:5180"
+        ],
+        devMode: true,
+        accessTokenType: "OIDC_TOKEN_TYPE_JWT",
+        accessTokenRoleAssertion: true,
+        idTokenRoleAssertion: true,
+        idTokenUserinfoAssertion: true,
+        loginVersion: { loginV2: { baseUri: $base } }
+      }')" || true)
+    UPD_CODE=$(echo "$UPD" | tail -n1)
+    if [[ "$UPD_CODE" == "200" ]]; then
+      echo "    updated OIDC app → Login V2 baseUri=$LOGIN_V2_BASE_URI"
+    else
+      echo "    WARN: UpdateOIDCAppConfig HTTP $UPD_CODE — $(echo "$UPD" | sed '$d' | head -c 200)"
+    fi
+  fi
+fi
+if [[ -z "$CLIENT_ID" || "$CLIENT_ID" == "null" ]]; then
+  echo "ERROR: web client id missing"; exit 1
+fi
+
+# Store secret if we got one
+SECRET_FILE="$ROOT/docker/web-client.secret"
+if [[ -n "$CLIENT_SECRET" && "$CLIENT_SECRET" != "null" ]]; then
+  umask 077
+  printf '%s' "$CLIENT_SECRET" > "$SECRET_FILE"
+  echo "    wrote $SECRET_FILE"
+elif [[ -f "$SECRET_FILE" ]]; then
+  CLIENT_SECRET=$(cat "$SECRET_FILE")
+fi
+
+# Humans MUST be created via human/_import with a flat password string.
+# Nested password objects leave users in USER_STATE_INITIAL with no password
+# (account picker shows a red dot; login never works).
+create_human() {
+  local username="$1" password="$2" role="$3" email="$4"
+  local search uid state
+  search=$(api POST /management/v1/users/_search "$(jq -n --arg n "$username" \
+    '{queries: [{userNameQuery: {userName: $n, method: "TEXT_QUERY_METHOD_EQUALS"}}]}')")
+  uid=$(echo "$search" | jq -r '.result[0].id // empty')
+  state=$(echo "$search" | jq -r '.result[0].state // empty')
+
+  # Drop broken INITIAL users (no password) so we can re-import.
+  if [[ -n "$uid" && "$state" == "USER_STATE_INITIAL" ]]; then
+    echo "    removing uninitialized $username ($uid)"
+    curl -sS -o /dev/null -X DELETE "$ZITADEL_HOST/management/v1/users/$uid" \
+      -H "Authorization: Bearer $ACCESS_TOKEN" || true
+    uid=""
+  fi
+
+  if [[ -z "$uid" ]]; then
+    echo "==> Human user $username (import + password)"
+    uid=$(api POST /management/v1/users/human/_import "$(jq -n \
+      --arg u "$username" --arg e "$email" --arg p "$password" \
+      '{
+        userName: $u,
+        profile: { firstName: $u, lastName: "E2E", displayName: $u },
+        email: { email: $e, isEmailVerified: true },
+        password: $p,
+        passwordChangeRequired: false
+      }')" | jq -r '.userId // empty')
+  else
+    echo "    reusing human $username ($uid, $state)"
+  fi
+  [[ -n "$uid" && "$uid" != "null" ]] || { echo "ERROR: human $username"; exit 1; }
+
+  # Grant project role
+  grants=$(api POST /management/v1/users/grants/_search "$(jq -n --arg uid "$uid" \
+    '{queries: [{userIdQuery: {userId: $uid}}]}')" 2>/dev/null || echo '{}')
+  existing=$(echo "$grants" | jq -r --arg pid "$PROJECT_ID" \
+    '.result[]? | select(.projectId == $pid) | .id // empty' | head -n1)
+  if [[ -n "$existing" ]]; then
+    curl -sS -o /dev/null -X PUT \
+      "$ZITADEL_HOST/management/v1/users/$uid/grants/$existing" \
+      -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
+      -d "$(jq -n --arg r "$role" '{roleKeys: [$r]}')" || true
+  else
+    api POST "/management/v1/users/$uid/grants" \
+      "$(jq -n --arg pid "$PROJECT_ID" --arg r "$role" '{projectId: $pid, roleKeys: [$r]}')" >/dev/null
+  fi
+  printf '%s' "$uid"
+}
+
+# Self-registration for "Create account" (hosted login Register button).
+echo "==> Login policy: ensure allowRegister"
+POL=$(curl -sS "$ZITADEL_HOST/management/v1/policies/login" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" || echo '{}')
+ALLOW=$(echo "$POL" | jq -r '.policy.allowRegister // empty')
+IS_DEFAULT=$(echo "$POL" | jq -r '.isDefault // .policy.isDefault // empty')
+echo "    current allowRegister=$ALLOW isDefault=$IS_DEFAULT"
+if [[ "$ALLOW" != "true" ]]; then
+  # Create org custom policy (required before update when still on IAM default).
+  # Field set matches Zitadel management UpdateCustomLoginPolicy / AddCustomLoginPolicy.
+  REG_BODY=$(jq -n '{
+    allowRegister: true,
+    allowUsernamePassword: true,
+    allowExternalIdp: true,
+    forceMfa: false,
+    passwordCheckLifetime: "864000s",
+    externalLoginCheckLifetime: "864000s",
+    multiFactorCheckLifetime: "43200s",
+    secondFactorCheckLifetime: "64800s",
+    mfaInitSkipLifetime: "2592000s",
+    passwordlessType: "PASSWORDLESS_TYPE_ALLOWED",
+    allowDomainDiscovery: true,
+    ignoreUnknownUsernames: false,
+    defaultRedirectUri: "",
+    passwordlessType: "PASSWORDLESS_TYPE_ALLOWED"
+  }')
+  if [[ "$IS_DEFAULT" == "true" ]]; then
+    code=$(curl -sS -o /tmp/e2e-login-pol.out -w '%{http_code}' -X POST \
+      "$ZITADEL_HOST/management/v1/policies/login" \
+      -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
+      -d "$REG_BODY" || true)
+  else
+    code=$(curl -sS -o /tmp/e2e-login-pol.out -w '%{http_code}' -X PUT \
+      "$ZITADEL_HOST/management/v1/policies/login" \
+      -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
+      -d "$REG_BODY" || true)
+  fi
+  echo "    policy write HTTP $code ($(head -c 160 /tmp/e2e-login-pol.out 2>/dev/null || true))"
+else
+  echo "    allowRegister already true — ok for Create account"
+fi
+
+echo "==> Human users (browser login: alice, bob, admin)"
+ALICE_UID=$(create_human "alice" "Password1!" "user" "alice@e2e.local")
+echo "    alice → $ALICE_UID"
+BOB_UID=$(create_human "bob" "Password1!" "user" "bob@e2e.local")
+echo "    bob → $BOB_UID"
+ADMIN_HUMAN_UID=$(create_human "admin" "Password1!" "admin" "admin@e2e.local")
+echo "    admin → $ADMIN_HUMAN_UID"
+
+create_machine() {
+  local username="$1" role="$2" key_out="$3"
+  local search uid key_resp
+  search=$(api POST /management/v1/users/_search "$(jq -n --arg n "$username" \
+    '{queries: [{userNameQuery: {userName: $n, method: "TEXT_QUERY_METHOD_EQUALS"}}]}')")
+  uid=$(echo "$search" | jq -r '.result[0].id // empty')
+  if [[ -z "$uid" ]]; then
+    uid=$(api POST /management/v1/users/machine "$(jq -n --arg u "$username" \
+      '{userName: $u, name: $u, description: "e2e-ui suite", accessTokenType: "ACCESS_TOKEN_TYPE_JWT"}')" \
+      | jq -r '.userId // empty')
+  fi
+  grants=$(api POST /management/v1/users/grants/_search "$(jq -n --arg uid "$uid" \
+    '{queries: [{userIdQuery: {userId: $uid}}]}')" 2>/dev/null || echo '{}')
+  existing=$(echo "$grants" | jq -r --arg pid "$PROJECT_ID" \
+    '.result[]? | select(.projectId == $pid) | .id // empty' | head -n1)
+  if [[ -n "$existing" ]]; then
+    curl -sS -o /dev/null -X PUT \
+      "$ZITADEL_HOST/management/v1/users/$uid/grants/$existing" \
+      -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
+      -d "$(jq -n --arg r "$role" '{roleKeys: [$r]}')" || true
+  else
+    api POST "/management/v1/users/$uid/grants" \
+      "$(jq -n --arg pid "$PROJECT_ID" --arg r "$role" '{projectId: $pid, roleKeys: [$r]}')" >/dev/null
+  fi
+  key_resp=$(api POST "/management/v1/users/$uid/keys" \
+    "$(jq -n '{type: "KEY_TYPE_JSON", expirationDate: "2029-01-01T00:00:00Z"}')")
+  if echo "$key_resp" | jq -e '.keyId and .key' >/dev/null 2>&1; then
+    echo "$key_resp" | jq -c --arg uid "$uid" '{keyId: .keyId, key: .key, userId: $uid}' > "$key_out"
+  elif echo "$key_resp" | jq -e '.keyDetails' >/dev/null 2>&1; then
+    key_json=$(echo "$key_resp" | jq -r '.keyDetails' | base64 -d 2>/dev/null || true)
+    echo "$key_json" | jq -c --arg uid "$uid" '. + {userId: (.userId // $uid)}' > "$key_out"
+  else
+    echo "ERROR: machine key for $username"; echo "$key_resp"; exit 1
+  fi
+  printf '%s' "$uid"
+}
+
+echo "==> Machine users (suite JWT-bearer)"
+USER_M_KEY="$MACHINEKEY_DIR/e2e/user-machine.json"
+ADMIN_M_KEY="$MACHINEKEY_DIR/e2e/admin-machine.json"
+USER_M_UID=$(create_machine "e2e-ui-user-m" "user" "$USER_M_KEY")
+echo "    e2e-ui-user-m → $USER_M_UID"
+ADMIN_M_UID=$(create_machine "e2e-ui-admin-m" "admin" "$ADMIN_M_KEY")
+echo "    e2e-ui-admin-m → $ADMIN_M_UID"
+
+# OIDC audience for JWT validation: project id (Zitadel project-scoped aud)
+DATABASE_URL="postgres://e2e:e2e@127.0.0.1:5433/e2e_ui"
+# Keep Auth.js session cookie decryption stable across re-bootstrap.
+# Rotating AUTH_SECRET → JWTSessionError: no matching decryption secret.
+if [[ -z "${AUTH_SECRET:-}" && -f "$OUT" ]]; then
+  _prev=$(grep -E '^AUTH_SECRET=' "$OUT" 2>/dev/null | head -1 | cut -d= -f2- || true)
+  _prev="${_prev%\"}"
+  _prev="${_prev#\"}"
+  _prev="${_prev%\'}"
+  _prev="${_prev#\'}"
+  if [[ -n "$_prev" ]]; then
+    AUTH_SECRET="$_prev"
+    echo "==> Reusing AUTH_SECRET from existing $OUT (session cookies stay valid)"
+  fi
+fi
+AUTH_SECRET="${AUTH_SECRET:-$(openssl rand -hex 32)}"
+
+umask 077
+# Dotenv-style values: double-quote so both `source e2e-ui.env` and Make
+# `include` keep the same unquoted semantics (shell single-quotes break Make).
+# Strip any accidental outer quotes from prior env pollution before writing.
+_dq() {
+  local v="$1"
+  # peel one layer of wrapping '…' or "…"
+  if [[ "$v" =~ ^\'.*\'$ || "$v" =~ ^\".*\"$ ]]; then
+    v="${v:1:${#v}-2}"
+  fi
+  # escape for double-quoted dotenv
+  v="${v//\\/\\\\}"
+  v="${v//\"/\\\"}"
+  printf '%s' "$v"
+}
+
+cat > "$OUT" <<EOF
+# Generated by scripts/up.sh — source before make run / make test-live
+# Format: KEY="value" (Make-include safe; do not use shell single-quotes)
+E2E_STACK=1
+DATABASE_URL="$(_dq "$DATABASE_URL")"
+OIDC_ISSUER="$(_dq "$ZITADEL_HOST")"
+OIDC_AUDIENCE="$(_dq "$PROJECT_ID")"
+OIDC_JWKS_URI="$(_dq "$ZITADEL_HOST/oauth/v2/keys")"
+OIDC_CLIENT_ID="$(_dq "$CLIENT_ID")"
+OIDC_CLIENT_SECRET="$(_dq "${CLIENT_SECRET:-}")"
+AUTH_SECRET="$(_dq "$AUTH_SECRET")"
+AUTH_TRUST_HOST=true
+OIDC_SCOPES="openid profile email offline_access urn:zitadel:iam:org:project:id:${PROJECT_ID}:aud urn:zitadel:iam:org:project:roles"
+ZITADEL_PROJECT_ID="$(_dq "$PROJECT_ID")"
+# Server-only: custom /login uses Session API + CreateCallback (never expose to browser).
+ZITADEL_SERVICE_USER_TOKEN="$(_dq "$LOGIN_PAT")"
+LOGIN_V2_BASE_URI="$(_dq "$LOGIN_V2_BASE_URI")"
+E2E_UI_ORIGIN="$(_dq "$UI_ORIGIN")"
+E2E_API_ORIGIN="$(_dq "$API_ORIGIN")"
+E2E_MACHINE_USER_KEY="$(_dq "$USER_M_KEY")"
+E2E_MACHINE_ADMIN_KEY="$(_dq "$ADMIN_M_KEY")"
+E2E_MACHINE_USER_ID="$(_dq "$USER_M_UID")"
+E2E_MACHINE_ADMIN_ID="$(_dq "$ADMIN_M_UID")"
+E2E_HUMAN_ALICE=alice
+E2E_HUMAN_BOB=bob
+E2E_HUMAN_PASSWORD="Password1!"
+# Zitadel user ids (OIDC sub) — use as provider_subject for auth_users joins
+E2E_HUMAN_ALICE_UID="$(_dq "$ALICE_UID")"
+E2E_HUMAN_BOB_UID="$(_dq "$BOB_UID")"
+E2E_HUMAN_ADMIN_UID="$(_dq "$ADMIN_HUMAN_UID")"
+# Shared secret for POST /zitadel.ingress.v1 (import IdP users → auth_users RM)
+ZITADEL_INGESTOR_SECRET="$(_dq "e2e-zitadel-ingestor-secret")"
+BIND="127.0.0.1:8791"
+EOF
+
+echo "==> Wrote $OUT"
+# Avoid dumping service PAT in terminal (still in file).
+grep -v 'ZITADEL_SERVICE_USER_TOKEN\|OIDC_CLIENT_SECRET\|AUTH_SECRET' "$OUT" || true
+echo "  … secrets redacted in console (present in file)"
+echo ""
+echo "Next:"
+echo "  set -a && source $OUT && set +a"
+echo "  make run   # restart so UI loads OIDC_* + ZITADEL_SERVICE_USER_TOKEN"
+echo "  Custom login: $LOGIN_V2_BASE_URI/login  (Auth.js authorize → your pages → callback)"
+echo "  Demo users: alice / bob / admin · Password1!"
diff --git a/tests/e2e-ui/ui/distributed.config.js b/tests/e2e-ui/ui/distributed.config.js
new file mode 100644
index 00000000..917e20d8
--- /dev/null
+++ b/tests/e2e-ui/ui/distributed.config.js
@@ -0,0 +1,61 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const uiRoot = dirname(fileURLToPath(import.meta.url));
+const e2eRoot = resolve(uiRoot, '..');
+const distributedRoot = resolve(uiRoot, '../../..');
+
+const manifestArgs = [
+	'client-manifest',
+	'--manifest-path',
+	resolve(e2eRoot, 'Cargo.toml'),
+	'--package',
+	'e2e-service',
+	'--distributed-path',
+	distributedRoot
+];
+
+/** App-owned service/surface configuration; all generated behavior is package-owned. */
+export const distributedClients = Object.freeze([
+	Object.freeze({
+		module: '$distributed',
+		manifest: Object.freeze({ args: Object.freeze(manifestArgs) }),
+		surface: 'e2e-ui',
+		documents: Object.freeze([
+			'src/routes/todos/+page.graphql',
+			'src/routes/chat/+page.graphql',
+			'src/routes/blob/*/+page.graphql'
+		]),
+		out: 'src/lib/generated/user'
+	}),
+	Object.freeze({
+		module: '$distributed/admin',
+		manifest: Object.freeze({
+			args: Object.freeze([
+				...manifestArgs,
+				'--entrypoint',
+				'e2e_service::distributed_admin_client_surface'
+			])
+		}),
+		surface: 'e2e-ui-admin',
+		documents: Object.freeze(['src/routes/admin/+page.graphql']),
+		out: 'src/lib/generated/admin'
+	})
+]);
+
+export const distributedViteOptions = Object.freeze({
+	cwd: uiRoot,
+	command: 'cargo',
+	commandArgs: Object.freeze([
+		'run',
+		'--quiet',
+		'--manifest-path',
+		resolve(distributedRoot, 'Cargo.toml'),
+		'-p',
+		'distributed_cli',
+		'--bin',
+		'dctl',
+		'--'
+	]),
+	clients: distributedClients
+});
diff --git a/tests/e2e-ui/ui/package-lock.json b/tests/e2e-ui/ui/package-lock.json
new file mode 100644
index 00000000..d9b8b10f
--- /dev/null
+++ b/tests/e2e-ui/ui/package-lock.json
@@ -0,0 +1,4474 @@
+{
+  "name": "e2e-ui-app",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "e2e-ui-app",
+      "version": "0.1.0",
+      "dependencies": {
+        "@auth/core": "^0.41.3",
+        "@auth/sveltekit": "^1.11.3",
+        "@hops-ops/distributed": "file:../../../js"
+      },
+      "devDependencies": {
+        "@csstools/postcss-global-data": "^4.0.0",
+        "@lucide/svelte": "0.577.0",
+        "@sveltejs/adapter-node": "5.2.12",
+        "@sveltejs/kit": "2.70.1",
+        "@sveltejs/vite-plugin-svelte": "5.1.1",
+        "@types/node": "^24.7.0",
+        "postcss-preset-env": "^11.1.1",
+        "svelte": "5.56.7",
+        "svelte-check": "4.1.7",
+        "typescript": "5.8.3",
+        "vite": "6.4.3"
+      }
+    },
+    "../../../js": {
+      "name": "@hops-ops/distributed",
+      "version": "0.1.0",
+      "license": "UNLICENSED",
+      "dependencies": {
+        "@graphql-typed-document-node/core": "^3.2.0",
+        "graphql": "^16.14.0"
+      },
+      "devDependencies": {
+        "@apollo/client": "^4.2.7",
+        "@types/node": "^20.0.0",
+        "@types/react": "19.2.17",
+        "esbuild": "^0.25.12",
+        "publint": "^0.3.22",
+        "react": "19.2.8",
+        "react-dom": "19.2.8",
+        "react-test-renderer": "19.2.8",
+        "svelte": "5.56.7",
+        "typescript": "5.8.3"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      },
+      "peerDependencies": {
+        "react": "^18.2.0 || ^19.0.0",
+        "svelte": "^5.0.0"
+      },
+      "peerDependenciesMeta": {
+        "react": {
+          "optional": true
+        },
+        "svelte": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@auth/core": {
+      "version": "0.41.3",
+      "resolved": "https://registry.npmjs.org/@auth/core/-/core-0.41.3.tgz",
+      "integrity": "sha512-sJ3JMHHkXMD3aOjopv7mOBTO1Ocw4b0fAEXJBz6k7YHLpYQI6C40jCUPc5fNvUKxXRXNE1/sRISA15UrwWJBTw==",
+      "license": "ISC",
+      "dependencies": {
+        "@panva/hkdf": "^1.2.1",
+        "jose": "^6.0.6",
+        "oauth4webapi": "^3.3.0",
+        "preact": "10.24.3",
+        "preact-render-to-string": "6.5.11"
+      },
+      "peerDependencies": {
+        "@simplewebauthn/browser": "^9.0.1",
+        "@simplewebauthn/server": "^9.0.2",
+        "nodemailer": "^7.0.7 || ^8.0.5"
+      },
+      "peerDependenciesMeta": {
+        "@simplewebauthn/browser": {
+          "optional": true
+        },
+        "@simplewebauthn/server": {
+          "optional": true
+        },
+        "nodemailer": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@auth/sveltekit": {
+      "version": "1.11.3",
+      "resolved": "https://registry.npmjs.org/@auth/sveltekit/-/sveltekit-1.11.3.tgz",
+      "integrity": "sha512-nfI/CFHD9hpJG4W+u+xtMrw9XSrA1k6kbgbGc9PvbiEf67oPMuzLAvLDj6/3yd98kFz+51Rq04JLBckKp8T5Kg==",
+      "license": "ISC",
+      "dependencies": {
+        "@auth/core": "0.41.3",
+        "set-cookie-parser": "^2.7.0"
+      },
+      "peerDependencies": {
+        "@simplewebauthn/browser": "^9.0.1",
+        "@simplewebauthn/server": "^9.0.3",
+        "@sveltejs/kit": "^1.0.0 || ^2.0.0",
+        "nodemailer": "^7.0.7 || ^8.0.5",
+        "svelte": "^3.54.0 || ^4.0.0 || ^5.0.0-0"
+      },
+      "peerDependenciesMeta": {
+        "@simplewebauthn/browser": {
+          "optional": true
+        },
+        "@simplewebauthn/server": {
+          "optional": true
+        },
+        "nodemailer": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@auth/sveltekit/node_modules/set-cookie-parser": {
+      "version": "2.7.2",
+      "resolved": "https://registry.npmjs.org/set-cookie-parser/-/set-cookie-parser-2.7.2.tgz",
+      "integrity": "sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==",
+      "license": "MIT"
+    },
+    "node_modules/@csstools/cascade-layer-name-parser": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/cascade-layer-name-parser/-/cascade-layer-name-parser-3.0.0.tgz",
+      "integrity": "sha512-/3iksyevwRfSJx5yH0RkcrcYXwuhMQx3Juqf40t97PeEy2/Mz2TItZ/z/216qpe4GgOyFBP8MKIwVvytzHmfIQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/color-helpers": {
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-6.1.0.tgz",
+      "integrity": "sha512-064IFJdjTfUqnjpCVpMOdbr8FLQBhinbZj6yRv2An2E41O/pLEXqfFRWqGq/SxlE5PEUYTlvWsG2r8MswAVvkg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
+    "node_modules/@csstools/css-calc": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-3.2.1.tgz",
+      "integrity": "sha512-DtdHlgXh5ZkA43cwBcAm+huzgJiwx3ZTWVjBs94kwz2xKqSimDA3lBgCjphYgwgVUMWatSM0pDd8TILB1yrVVg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-color-parser": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-4.1.9.tgz",
+      "integrity": "sha512-paQcIaOO53Rk5+YrBaBjm/SgrV4INImjo2BT1DtQRYr+XeTRbeAYlS+jxXp9drqvKmtFnWRJKIalDLhZZDu42A==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/color-helpers": "^6.1.0",
+        "@csstools/css-calc": "^3.2.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-parser-algorithms": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-4.0.0.tgz",
+      "integrity": "sha512-+B87qS7fIG3L5h3qwJ/IFbjoVoOe/bpOdh9hAjXbvx0o8ImEmUsGXN0inFOnk2ChCFgqkkGFQ+TpM5rbhkKe4w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-tokenizer": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-4.0.0.tgz",
+      "integrity": "sha512-QxULHAm7cNu72w97JUNCBFODFaXpbDg+dP8b/oWFAZ2MTRppA3U00Y2L1HqaS4J6yBqxwa/Y3nMBaxVKbB/NsA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
+    "node_modules/@csstools/media-query-list-parser": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/media-query-list-parser/-/media-query-list-parser-5.0.0.tgz",
+      "integrity": "sha512-T9lXmZOfnam3eMERPsszjY5NK0jX8RmThmmm99FZ8b7z8yMaFZWKwLWGZuTwdO3ddRY5fy13GmmEYZXB4I98Eg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/postcss-alpha-function": {
+      "version": "2.0.7",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-alpha-function/-/postcss-alpha-function-2.0.7.tgz",
+      "integrity": "sha512-ueQMpNJfsIUqyOd38Kjc3c7rTaXDLKn0qr9krteAFx3fsSuawXQePAQ02AI5+RbMpdibv+Mfcs4d0AUl/SULsQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-cascade-layers": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-cascade-layers/-/postcss-cascade-layers-6.0.0.tgz",
+      "integrity": "sha512-WhsECqmrEZQGqaPlBA7JkmF/CJ2/+wetL4fkL9sOPccKd32PQ1qToFM6gqSI5rkpmYqubvbxjEJhyMTHYK0vZQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/selector-specificity": "^6.0.0",
+        "postcss-selector-parser": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-color-function": {
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-color-function/-/postcss-color-function-5.0.6.tgz",
+      "integrity": "sha512-CHWuCfTg7afbSFMgVajmF1WU/bJ1rGBKGCj3L3tolDXZpQG2ZCQRu10ozfk1I10By9aRqQ43FTnAiDwBnbC+Hg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-color-function-display-p3-linear": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-color-function-display-p3-linear/-/postcss-color-function-display-p3-linear-2.0.6.tgz",
+      "integrity": "sha512-65C1CF/d9/ULr7dwmE5TBrRYZVa5sWLZX7mlR7WcBl1YwSYA8ntOvAhEEZmq8B2rBgosrOjZcDLnvFQuGaoRcA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-color-mix-function": {
+      "version": "4.0.6",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-color-mix-function/-/postcss-color-mix-function-4.0.6.tgz",
+      "integrity": "sha512-gWXS+Qx4GnIq4lRvBcabAcGF5IBkfcbZ7uoUvQw/3+JYDQVkD8SoKIFRoYhwKAOm+zTDJRYLMsjxWieBh9xOZw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-color-mix-variadic-function-arguments": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-color-mix-variadic-function-arguments/-/postcss-color-mix-variadic-function-arguments-2.0.6.tgz",
+      "integrity": "sha512-+bL0RlSDLM/02Z2JgxMK2AIas8IIL4fQkFsjETmMIXFSmOH+iRx1YEKyMbc3SogmiR8zJ41Eid7Q8+bxj7+2Dg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-container-rule-prelude-list": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-container-rule-prelude-list/-/postcss-container-rule-prelude-list-1.0.1.tgz",
+      "integrity": "sha512-c5qlevVGKHU+zDbVoUGSZl1Mw7Vl1gVRKv6cdIYnaoyM+9Ou23Ian0H5Gr2ZF+lsDWovPK03hOSAbkw6HS8aTg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-content-alt-text": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-content-alt-text/-/postcss-content-alt-text-3.0.2.tgz",
+      "integrity": "sha512-LUT1eKBzb71pmky0ke2OHJHdcqHl1vtl++qzJei5FioMVWDzxVApElTZsoFwbqV8Et+UmxzieOuhwomuyRullw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-contrast-color-function": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-contrast-color-function/-/postcss-contrast-color-function-3.0.6.tgz",
+      "integrity": "sha512-7H+LLv2+A5q/l9TdWLnLB7ZgMT92aOVImzVpYSHg9pCEHSeskbqssn05rKb+ysouRM8rbg649Q2g2kIKFqLYvQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-exponential-functions": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-exponential-functions/-/postcss-exponential-functions-3.0.3.tgz",
+      "integrity": "sha512-mB/NoeHLBHh0LZiVSrFdRDA/NxSfmg4tSN9117IJH9bdC2BzSTVgc82h3Gu/sdBXay6kDH2sA7fbkTigMiEi2A==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-calc": "^3.2.1",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-font-format-keywords": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-font-format-keywords/-/postcss-font-format-keywords-5.0.0.tgz",
+      "integrity": "sha512-M1EjCe/J3u8fFhOZgRci74cQhJ7R0UFBX6T+WqoEvjrr8hVfMiV+HTYrzxLY5OW8YllvXYr5Q5t5OvJbsUSeDg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/utilities": "^3.0.0",
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-font-width-property": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-font-width-property/-/postcss-font-width-property-1.0.0.tgz",
+      "integrity": "sha512-AvmySApdijbjYQuXXh95tb7iVnqZBbJrv3oajO927ksE/mDmJBiszm+psW8orL2lRGR8j6ZU5Uv9/ou2Z5KRKA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-gamut-mapping": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-gamut-mapping/-/postcss-gamut-mapping-3.0.6.tgz",
+      "integrity": "sha512-lopCMFvN6ohy33lLmOY46matUrpL1ymVGOyebflzMb44pXoGy+f27glXCXz0PfQmfv8On3a8eVTIQfkX7nf6gQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-global-data": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-global-data/-/postcss-global-data-4.0.0.tgz",
+      "integrity": "sha512-mPKrL3Tzt8k1V+hTkU8XTH6JKRekB97oKHv/MekC9nfmRa+gMf1swlHRt8YK722sYN4xOipl17FZst99jsScLA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-gradients-interpolation-method": {
+      "version": "6.0.6",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-gradients-interpolation-method/-/postcss-gradients-interpolation-method-6.0.6.tgz",
+      "integrity": "sha512-n23eZrwg8/XT6Ml42AAMd1PqRSm1LlrcGL+cbflpjL84xVZcWsXtHeKVzufg2uxICGnB4/t/iGa4XnOfySusEA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-hwb-function": {
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-hwb-function/-/postcss-hwb-function-5.0.6.tgz",
+      "integrity": "sha512-KO1PBdiyzsxVOnripQbdMF8jXlBym3CtwEWHGQWfjRB2Q7BIU6sE9GGv2OrgG3TyqPOz5BgAwackYlYlVeHWvA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-ic-unit": {
+      "version": "5.0.2",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-ic-unit/-/postcss-ic-unit-5.0.2.tgz",
+      "integrity": "sha512-1Wcp0ACoGKImCL9mYm6EIdqtT2JuJoeFp/06Efa6pRT0y3elLgF3jYer+c3+qUoBhV/2uDKtfWrCwAkHJ0CB9w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0",
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-image-function": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-image-function/-/postcss-image-function-1.0.1.tgz",
+      "integrity": "sha512-6V7+8npoBxVgO3JbIdKqI6eo1NAIQtO0oNSfLSgH439WYB43/kM+GneG4elkgglRo1ppgVhjXxmNqhI+K4pEzg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-initial": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-initial/-/postcss-initial-3.0.0.tgz",
+      "integrity": "sha512-UVUrFmrTQyLomVepnjWlbBg7GoscLmXLwYFyjbcEnmpeGW7wde6lNpx5eM3eVwZI2M+7hCE3ykYnAsEPLcLa+Q==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-is-pseudo-class": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-is-pseudo-class/-/postcss-is-pseudo-class-6.0.0.tgz",
+      "integrity": "sha512-1Hdy/ykg9RDo8vU8RiM2o+RaXO39WpFPaIkHxlAEJFofle/lc33tdQMKhBk3jR/Fe+uZNLOs3HlowFafyFptVw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/selector-specificity": "^6.0.0",
+        "postcss-selector-parser": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-light-dark-function": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-light-dark-function/-/postcss-light-dark-function-3.0.2.tgz",
+      "integrity": "sha512-Fu6si5QhRrT5lP7nmXxfowR8zNkYrqoolsWOZxPZBZpVTdoEKazN6v+K53vPcy1EM4Mlj6tSaEjMu4gAwC8yqw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-logical-float-and-clear": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-logical-float-and-clear/-/postcss-logical-float-and-clear-4.0.0.tgz",
+      "integrity": "sha512-NGzdIRVj/VxOa/TjVdkHeyiJoDihONV0+uB0csUdgWbFFr8xndtfqK8iIGP9IKJzco+w0hvBF2SSk2sDSTAnOQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-logical-overflow": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-logical-overflow/-/postcss-logical-overflow-3.0.0.tgz",
+      "integrity": "sha512-5cRg93QXVskM0MNepHpPcL0WLSf5Hncky0DrFDQY/4ozbH5lH7SX5ejayVpNTGSX7IpOvu7ykQDLOdMMGYzwpA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-logical-overscroll-behavior": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-logical-overscroll-behavior/-/postcss-logical-overscroll-behavior-3.0.0.tgz",
+      "integrity": "sha512-82Jnl/5Wi5jb19nQE1XlBHrZcNL3PzOgcj268cDkfwf+xi10HBqufGo1Unwf5n8bbbEFhEKgyQW+vFsc9iY1jw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-logical-resize": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-logical-resize/-/postcss-logical-resize-4.0.0.tgz",
+      "integrity": "sha512-L0T3q0gei/tGetCGZU0c7VN77VTivRpz1YZRNxjXYmW+85PKeI6U9YnSvDqLU2vBT2uN4kLEzfgZ0ThIZpN18A==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-logical-viewport-units": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-logical-viewport-units/-/postcss-logical-viewport-units-4.0.0.tgz",
+      "integrity": "sha512-TA3AqVN/1IH3dKRC2UUWvprvwyOs2IeD7FDZk5Hz20w4q33yIuSg0i0gjyTUkcn90g8A4n7QpyZ2AgBrnYPnnA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-media-minmax": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-media-minmax/-/postcss-media-minmax-3.0.3.tgz",
+      "integrity": "sha512-ch1tNS+1QayiHTGsyc53zv3AzrSd0zigjbkfLxoeuzzJyn32+P3V7em3u5vLVnqLMzBbEZK//GI13EVTIPRdDA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/css-calc": "^3.2.1",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/media-query-list-parser": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-media-queries-aspect-ratio-number-values": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-media-queries-aspect-ratio-number-values/-/postcss-media-queries-aspect-ratio-number-values-4.0.0.tgz",
+      "integrity": "sha512-FDdC3lbrj8Vr0SkGIcSLTcRB7ApG6nlJFxOxkEF2C5hIZC1jtgjISFSGn/WjFdVkn8Dqe+Vx9QXI3axS2w1XHw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/media-query-list-parser": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-mixins": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-mixins/-/postcss-mixins-1.0.0.tgz",
+      "integrity": "sha512-rz6qjT2w9L3k65jGc2dX+3oGiSrYQ70EZPDrINSmSVoVys7lLBFH0tvEa8DW2sr9cbRVD/W+1sy8+7bfu0JUfg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-nested-calc": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-nested-calc/-/postcss-nested-calc-5.0.0.tgz",
+      "integrity": "sha512-aPSw8P60e/i9BEfugauhikBqgjiwXcw3I9o4vXs+hktl4NSTgZRI0QHimxk9mst8N01A2TKDBxOln3mssRxiHQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/utilities": "^3.0.0",
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-normalize-display-values": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-normalize-display-values/-/postcss-normalize-display-values-5.0.1.tgz",
+      "integrity": "sha512-FcbEmoxDEGYvm2W3rQzVzcuo66+dDJjzzVDs+QwRmZLHYofGmMGwIKPqzF86/YW+euMDa7sh1xjWDvz/fzByZQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-oklab-function": {
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-oklab-function/-/postcss-oklab-function-5.0.6.tgz",
+      "integrity": "sha512-6yZ+OySSaBybv12OfgKFBgCK1Se2mBbhh9eIDbUdWGHJUXZPQoLbtPj8S6Wg0lqe0nTqKgY/l8Ir9lHrm2TUBQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-position-area-property": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-position-area-property/-/postcss-position-area-property-2.0.0.tgz",
+      "integrity": "sha512-TeEfzsJGB23Syv7yCm8AHCD2XTFujdjr9YYu9ebH64vnfCEvY4BG319jXAYSlNlf3Yc9PNJ6WnkDkUF5XVgSKQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-progressive-custom-properties": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-progressive-custom-properties/-/postcss-progressive-custom-properties-5.1.1.tgz",
+      "integrity": "sha512-b9+lusgVDTHXRBgYKE9s0RKUyEn6Q/knmMDmYmSrkZjtpb0Nd71pBtgVMf9tSpOIb0K8hyzeyy6JyKFqg5rBJw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-property-rule-prelude-list": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-property-rule-prelude-list/-/postcss-property-rule-prelude-list-2.0.0.tgz",
+      "integrity": "sha512-qcMAkc9AhpzHgmQCD8hoJgGYifcOAxd1exXjjxilMM6euwRE619xDa4UsKBCv/v4g+sS63sd6c29LPM8s2ylSQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-random-function": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-random-function/-/postcss-random-function-3.0.3.tgz",
+      "integrity": "sha512-0EScyKxscGonwpi30Hj9DEAr0X8D2eDhOqqayQXE91gIqGli9UT+deLYqoogZLOy5GT+ncqltMqztc/q+0UkhA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-calc": "^3.2.1",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-relative-color-syntax": {
+      "version": "4.0.6",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-relative-color-syntax/-/postcss-relative-color-syntax-4.0.6.tgz",
+      "integrity": "sha512-4SUC+qfJE/8sV62oo/fcxNKSBgiSVqE8c7f9TBwvNY3WnD0YHJyEM3eIjXn1CxbMNl7gR6uBVuLuJB3xgr/O1w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-scope-pseudo-class": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-scope-pseudo-class/-/postcss-scope-pseudo-class-5.0.0.tgz",
+      "integrity": "sha512-kBrBFJcAji3MSHS4qQIihPvJfJC5xCabXLbejqDMiQi+86HD4eMBiTayAo46Urg7tlEmZZQFymFiJt+GH6nvXw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "postcss-selector-parser": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-sign-functions": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-sign-functions/-/postcss-sign-functions-2.0.3.tgz",
+      "integrity": "sha512-2BCPwlpeQweTC/8S8oQFYhYD5kxYkiroLf3AUJV2kVoKkSZ+4WM4rSwySXlKrqXL8HfCryAwVrJg7B0jr/RnOw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-calc": "^3.2.1",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-stepped-value-functions": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-stepped-value-functions/-/postcss-stepped-value-functions-5.0.3.tgz",
+      "integrity": "sha512-nXMFQBz5Pi2LLG02iqm2k+scrqwtqJT9ta/gN8S79oBZ23M0E7O3wDJ20//3z5Q6HU5e+K0n+SmmxN6iWtbm6w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-calc": "^3.2.1",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-syntax-descriptor-syntax-production": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-syntax-descriptor-syntax-production/-/postcss-syntax-descriptor-syntax-production-2.0.0.tgz",
+      "integrity": "sha512-elYcbdiBXAkPqvojB9kIBRuHY6htUhjSITtFQ+XiXnt6SvZCbNGxQmaaw6uZ7SPHu/+i/XVjzIt09/1k3SIerQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-system-ui-font-family": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-system-ui-font-family/-/postcss-system-ui-font-family-2.0.0.tgz",
+      "integrity": "sha512-FyGZCgchFImFyiHS2x3rD5trAqatf/x23veBLTIgbaqyFfna6RNBD+Qf8HRSjt6HGMXOLhAjxJ3OoZg0bbn7Qw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-text-decoration-shorthand": {
+      "version": "5.0.4",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-text-decoration-shorthand/-/postcss-text-decoration-shorthand-5.0.4.tgz",
+      "integrity": "sha512-LHQL1a0CW0j3oBEivwgp1Gqv+VUppWpEyedM9GBzE6yIT6tnZqY9v0ADX1jO6IptTZTdrnBwM+dveDIuUP+pTA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/color-helpers": "^6.1.0",
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-trigonometric-functions": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-trigonometric-functions/-/postcss-trigonometric-functions-5.0.3.tgz",
+      "integrity": "sha512-p9LTvLj+DFpl5RHbG/X9QGwg7BoMOBsRBZqsUAKKVvCw7MRCsk1P1llTUR/MW5nyZ4IsjFGDtDwTTj1reJjxvg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-calc": "^3.2.1",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/postcss-unset-value": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/postcss-unset-value/-/postcss-unset-value-5.0.0.tgz",
+      "integrity": "sha512-EoO54sS2KCIfesvHyFYAW99RtzwHdgaJzhl7cqKZSaMYKZv3fXSOehDjAQx8WZBKn1JrMd7xJJI1T1BxPF7/jA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@csstools/selector-resolve-nested": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/selector-resolve-nested/-/selector-resolve-nested-4.0.0.tgz",
+      "integrity": "sha512-9vAPxmp+Dx3wQBIUwc1v7Mdisw1kbbaGqXUM8QLTgWg7SoPGYtXBsMXvsFs/0Bn5yoFhcktzxNZGNaUt0VjgjA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss-selector-parser": "^7.1.1"
+      }
+    },
+    "node_modules/@csstools/selector-specificity": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/selector-specificity/-/selector-specificity-6.0.0.tgz",
+      "integrity": "sha512-4sSgl78OtOXEX/2d++8A83zHNTgwCJMaR24FvsYL7Uf/VS8HZk9PTwR51elTbGqMuwH3szLvvOXEaVnqn0Z3zA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss-selector-parser": "^7.1.1"
+      }
+    },
+    "node_modules/@csstools/utilities": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/utilities/-/utilities-3.0.0.tgz",
+      "integrity": "sha512-etDqA/4jYvOGBM6yfKCOsEXfH96BKztZdgGmGqKi2xHnDe0ILIBraRspwgYatJH9JsCZ5HCGoCst8w18EKOAdg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz",
+      "integrity": "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.12.tgz",
+      "integrity": "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.12.tgz",
+      "integrity": "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.12.tgz",
+      "integrity": "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.12.tgz",
+      "integrity": "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.12.tgz",
+      "integrity": "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.12.tgz",
+      "integrity": "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.12.tgz",
+      "integrity": "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.12.tgz",
+      "integrity": "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.12.tgz",
+      "integrity": "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.12.tgz",
+      "integrity": "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==",
+      "cpu": [
+        "loong64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.12.tgz",
+      "integrity": "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.12.tgz",
+      "integrity": "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.12.tgz",
+      "integrity": "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.12.tgz",
+      "integrity": "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==",
+      "cpu": [
+        "s390x"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.12.tgz",
+      "integrity": "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.12.tgz",
+      "integrity": "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.12.tgz",
+      "integrity": "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.12.tgz",
+      "integrity": "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.12.tgz",
+      "integrity": "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.12.tgz",
+      "integrity": "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.12.tgz",
+      "integrity": "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.12.tgz",
+      "integrity": "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@hops-ops/distributed": {
+      "resolved": "../../../js",
+      "link": true
+    },
+    "node_modules/@jridgewell/gen-mapping": {
+      "version": "0.3.13",
+      "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
+      "integrity": "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==",
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.0",
+        "@jridgewell/trace-mapping": "^0.3.24"
+      }
+    },
+    "node_modules/@jridgewell/remapping": {
+      "version": "2.3.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/remapping/-/remapping-2.3.5.tgz",
+      "integrity": "sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/gen-mapping": "^0.3.5",
+        "@jridgewell/trace-mapping": "^0.3.24"
+      }
+    },
+    "node_modules/@jridgewell/resolve-uri": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+      "license": "MIT"
+    },
+    "node_modules/@jridgewell/trace-mapping": {
+      "version": "0.3.31",
+      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz",
+      "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==",
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/resolve-uri": "^3.1.0",
+        "@jridgewell/sourcemap-codec": "^1.4.14"
+      }
+    },
+    "node_modules/@lucide/svelte": {
+      "version": "0.577.0",
+      "resolved": "https://registry.npmjs.org/@lucide/svelte/-/svelte-0.577.0.tgz",
+      "integrity": "sha512-0P6mkySd2MapIEgq08tADPmcN4DHndC/02PWwaLkOerXlx5Sv9aT4BxyXLIY+eccr0g/nEyCYiJesqS61YdBZQ==",
+      "dev": true,
+      "license": "ISC",
+      "peerDependencies": {
+        "svelte": "^5"
+      }
+    },
+    "node_modules/@panva/hkdf": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/@panva/hkdf/-/hkdf-1.2.1.tgz",
+      "integrity": "sha512-6oclG6Y3PiDFcoyk8srjLfVKyMfVCKJ27JwNPViuXziFpmdz+MZnZN/aKY0JGXgYuO/VghU0jcOAZgWXZ1Dmrw==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/panva"
+      }
+    },
+    "node_modules/@polka/url": {
+      "version": "1.0.0-next.29",
+      "resolved": "https://registry.npmjs.org/@polka/url/-/url-1.0.0-next.29.tgz",
+      "integrity": "sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==",
+      "license": "MIT"
+    },
+    "node_modules/@rollup/plugin-commonjs": {
+      "version": "28.0.9",
+      "resolved": "https://registry.npmjs.org/@rollup/plugin-commonjs/-/plugin-commonjs-28.0.9.tgz",
+      "integrity": "sha512-PIR4/OHZ79romx0BVVll/PkwWpJ7e5lsqFa3gFfcrFPWwLXLV39JVUzQV9RKjWerE7B845Hqjj9VYlQeieZ2dA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@rollup/pluginutils": "^5.0.1",
+        "commondir": "^1.0.1",
+        "estree-walker": "^2.0.2",
+        "fdir": "^6.2.0",
+        "is-reference": "1.2.1",
+        "magic-string": "^0.30.3",
+        "picomatch": "^4.0.2"
+      },
+      "engines": {
+        "node": ">=16.0.0 || 14 >= 14.17"
+      },
+      "peerDependencies": {
+        "rollup": "^2.68.0||^3.0.0||^4.0.0"
+      },
+      "peerDependenciesMeta": {
+        "rollup": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@rollup/plugin-commonjs/node_modules/is-reference": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/is-reference/-/is-reference-1.2.1.tgz",
+      "integrity": "sha512-U82MsXXiFIrjCK4otLT+o2NA2Cd2g5MLoOVXUZjIOhLurrRxpEXzI8O0KZHr3IjLvlAH1kTPYSuqer5T9ZVBKQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "*"
+      }
+    },
+    "node_modules/@rollup/plugin-json": {
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/@rollup/plugin-json/-/plugin-json-6.1.0.tgz",
+      "integrity": "sha512-EGI2te5ENk1coGeADSIwZ7G2Q8CJS2sF120T7jLw4xFw9n7wIOXHo+kIYRAoVpJAN+kmqZSoO3Fp4JtoNF4ReA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@rollup/pluginutils": "^5.1.0"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "peerDependencies": {
+        "rollup": "^1.20.0||^2.0.0||^3.0.0||^4.0.0"
+      },
+      "peerDependenciesMeta": {
+        "rollup": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@rollup/plugin-node-resolve": {
+      "version": "16.0.3",
+      "resolved": "https://registry.npmjs.org/@rollup/plugin-node-resolve/-/plugin-node-resolve-16.0.3.tgz",
+      "integrity": "sha512-lUYM3UBGuM93CnMPG1YocWu7X802BrNF3jW2zny5gQyLQgRFJhV1Sq0Zi74+dh/6NBx1DxFC4b4GXg9wUCG5Qg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@rollup/pluginutils": "^5.0.1",
+        "@types/resolve": "1.20.2",
+        "deepmerge": "^4.2.2",
+        "is-module": "^1.0.0",
+        "resolve": "^1.22.1"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "peerDependencies": {
+        "rollup": "^2.78.0||^3.0.0||^4.0.0"
+      },
+      "peerDependenciesMeta": {
+        "rollup": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@rollup/pluginutils": {
+      "version": "5.4.0",
+      "resolved": "https://registry.npmjs.org/@rollup/pluginutils/-/pluginutils-5.4.0.tgz",
+      "integrity": "sha512-MfPp06CjRLfXQ3wY0R8vJDYBy/MvVcc9OulEfR0B8Iv9ko+GCNaRZ+EpJYFl27LhKsZK0o420sYCRHCjfCgeUg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "estree-walker": "^2.0.2",
+        "picomatch": "^4.0.2"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "peerDependencies": {
+        "rollup": "^1.20.0||^2.0.0||^3.0.0||^4.0.0"
+      },
+      "peerDependenciesMeta": {
+        "rollup": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@rollup/rollup-android-arm-eabi": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.62.2.tgz",
+      "integrity": "sha512-6o7ZLZK+BeenkZCFNDXqpbjw9bD6nuWonvS/lwQJp7NoVVxm6p3qE7qQ5jGuBjiFsgvqjD8mZAU5oWxTmbOeOg==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-android-arm64": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.62.2.tgz",
+      "integrity": "sha512-BaH7BllCACHoH1LguOU56UItGfUWjujlO65kS9LAodViaN4bwIKd7oeW/ZHJ/4ljr/7MIiENnNy3HJ0zXv8Zkw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-arm64": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.62.2.tgz",
+      "integrity": "sha512-v39RCCvj4He82I9sFmk+M1VZ0PLM9sfsLVikjfx2hYBNALhrrOR2D3JjQA6AhlaSOgcR+RzrKY7e1+bT6SUO/A==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-x64": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.62.2.tgz",
+      "integrity": "sha512-yl0y2vq3S3lHeuXhEdss6TWfKW8vkujImO12tn4ZkG/4oghr09LvdYm2RElVjokTQiUvDUGXLGsYeLqUMCKpGA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-arm64": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.62.2.tgz",
+      "integrity": "sha512-tT4pvt4qXD+vEoezupCWi+a1F0vvDiksiHc+PxRlYTOH1I6/X4id9jPxTP+Fg+545euaFT1jJVs4CEdHZAU1vw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-x64": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.62.2.tgz",
+      "integrity": "sha512-6nU5F2wCW+qvCBhTn1pdIU3bzsIoF7EUwsCDRxilWGprQR6yd508YnH9+OKFCwpfS8pjZqDUmnCAr7exax0XCg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.62.2.tgz",
+      "integrity": "sha512-n1GJHPOvpIfhi3TmrCeh6S6URt9BFCt0KQE3qvexyGCTAKpR4Lg+eWvNZEqu7epxwus/8ElT3hacYEucm49SZg==",
+      "cpu": [
+        "arm"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.62.2.tgz",
+      "integrity": "sha512-JqgflS8wEB+UXV/vS1RpRbifGBeN4D5lz8D8oOFbFZw4vedvdOgCFAjfBmIMdW3yL10XpQQ0Ambepw6MXrhOnA==",
+      "cpu": [
+        "arm"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.62.2.tgz",
+      "integrity": "sha512-wnFJkogWvN4jm/hQRF2UBaeUmk20j5+DmHvoyWii2b8HJDyvz1MF2OU/6ynXt2KR63rbZLWkFpoytpdc/yBuSA==",
+      "cpu": [
+        "arm64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-musl": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.62.2.tgz",
+      "integrity": "sha512-HVu2bp0zhvJ8xHEV9+UUs7S90VadmBSY3LcIMvozbPo4AuMGDWlz3ymHLHZPX4hR67TKTt8Qp5PJ5RBg/i+RMQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.62.2.tgz",
+      "integrity": "sha512-mQqqAV8QaoSgr9I2fKDLY2BAVvmKjWoGiu/cSYQonsLvtqwEn1E4QYfnCOcp5zoEqNhsDYin1s6jx/VJmrxlZg==",
+      "cpu": [
+        "loong64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.62.2.tgz",
+      "integrity": "sha512-IxKLoxCQ2IWi6bT2akyDUBGsOImDKB+sPp4EsTmwFQ/fMwpCKm8uLSSgP/Kx/QYUgKis6SEZ5/Nlhup0DIA0PQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.62.2.tgz",
+      "integrity": "sha512-Mk5ha2RQSgyFfmYYLkBpPnUk8D8FriBxesO1u9O75X0mHgXL1UQcH5Itl2lurWL2tj0RxV9b9tJgipac0hRY9A==",
+      "cpu": [
+        "ppc64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.62.2.tgz",
+      "integrity": "sha512-CjvEnqJL/0/TQ3TXX3OPIJ/kmBellrWd4heXUmHeJlTnmwjKpSJzoehLaL6Xk0ZnMHBu9dZuFADNOrtjF4v+2w==",
+      "cpu": [
+        "ppc64"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.62.2.tgz",
+      "integrity": "sha512-1SiZbzwdkaDURsew/tSOrooKiYy7EQGT6m8ufavAi9NEyQb/6VuIxFXAL1fqa4iZe3g4NbNk4P7J32z2tw5Mgg==",
+      "cpu": [
+        "riscv64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-musl": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.62.2.tgz",
+      "integrity": "sha512-nQts12zJ3NQRoE6uYljOH89v7szzLDvG2JD/vsX+vGXU8w/At1GowTZ5/7qeFQ8m7L55rpR8Okugnuo5bgjy2Q==",
+      "cpu": [
+        "riscv64"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-s390x-gnu": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.62.2.tgz",
+      "integrity": "sha512-E9/ll019jhPIJgpzfZoIkBGhcz+kKNgVWYRY0zr9srBdPPFVpvOKW8VaJKUbeK+eZXyQF9ltME+Kk6affeaPgg==",
+      "cpu": [
+        "s390x"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-gnu": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.62.2.tgz",
+      "integrity": "sha512-5BqxR/pshjey51iliyzTD5Xi3EN0aLmQ2lZ3lvefVV9c82BvrLo2/6OT55iifpWBufs6kdwWbuOKS841DrmK9A==",
+      "cpu": [
+        "x64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-musl": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.62.2.tgz",
+      "integrity": "sha512-uNN83XxQrRAh/w0/pmAfibcwyb6YWt4gP+dpnQKPVJshAloQ785ii8CT8ZCIxkGg9opVsvAlGhFitSm6D1Jjpg==",
+      "cpu": [
+        "x64"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-openbsd-x64": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.62.2.tgz",
+      "integrity": "sha512-srjEIxSH3LRnJN6THczDHWQplqEMFiAJrTab0msUryh9kwNpkICf3Ea6q6MN/2cZwRFUNx5w+h6Hpi4QuHS6Zg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-openharmony-arm64": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.62.2.tgz",
+      "integrity": "sha512-8hOJnxgbyObnCm5AlRA3A931xX19xq80RjVTKgJOvEKWqJruP/Uf12IbAOaDjjEXYRewwHLfmF0YRIdK3OwKWA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-arm64-msvc": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.62.2.tgz",
+      "integrity": "sha512-mmF4AY1i0hG/bLWUctUq59gtmgaSIRa3cu/A3JFRp/sCNEme2bgDEiDS22P9FbnJB8NJNF4jPJiSP5RHQpUTDg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-ia32-msvc": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.62.2.tgz",
+      "integrity": "sha512-DZgkknc6jhHrk46V25vbAM0zZkyP0nSDkJB8/dRkLTxv470dOmWDqGoEJl/9A0dFfS7yE3REOwNDxpHwSLSt0Q==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-gnu": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.62.2.tgz",
+      "integrity": "sha512-T6xr6ucWSFto+VGajA8YH26LdpHRuP4YLHEKAtCWvJDOlnmWcDZVCI2Jmjr+IFHDlt2zRaTAKE4tfjTaWLgJBg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-msvc": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.62.2.tgz",
+      "integrity": "sha512-BfzEnDJOt9T8M989/lA37EcJgat01wLRnoi5dQf3QzOH7jzpqTAzdDbVfRljVr5r+jzKqpbHeyOfAaXxAd0PAA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@standard-schema/spec": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
+      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+      "license": "MIT"
+    },
+    "node_modules/@sveltejs/acorn-typescript": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/@sveltejs/acorn-typescript/-/acorn-typescript-1.0.11.tgz",
+      "integrity": "sha512-LFuZUkjJ9iF7JZye/aG5XM0SFcQ5VyL0oVX4WJ9dc0Va3R3s0OauX1BESVCb+YN/ol8TAfqGDDAQsTG627Y5kw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "acorn": "^8.9.0"
+      }
+    },
+    "node_modules/@sveltejs/adapter-node": {
+      "version": "5.2.12",
+      "resolved": "https://registry.npmjs.org/@sveltejs/adapter-node/-/adapter-node-5.2.12.tgz",
+      "integrity": "sha512-0bp4Yb3jKIEcZWVcJC/L1xXp9zzJS4hDwfb4VITAkfT4OVdkspSHsx7YhqJDbb2hgLl6R9Vs7VQR+fqIVOxPUQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@rollup/plugin-commonjs": "^28.0.1",
+        "@rollup/plugin-json": "^6.1.0",
+        "@rollup/plugin-node-resolve": "^16.0.0",
+        "rollup": "^4.9.5"
+      },
+      "peerDependencies": {
+        "@sveltejs/kit": "^2.4.0"
+      }
+    },
+    "node_modules/@sveltejs/kit": {
+      "version": "2.70.1",
+      "resolved": "https://registry.npmjs.org/@sveltejs/kit/-/kit-2.70.1.tgz",
+      "integrity": "sha512-nY9SPHGOZro3doud9vZXDBwl9tCZIouuJztjgSHs6PAIrv9M/z5O7eOhPV5xU7CgVHA976Jwu3BA1hIFvXztkA==",
+      "license": "MIT",
+      "dependencies": {
+        "@standard-schema/spec": "^1.0.0",
+        "@sveltejs/acorn-typescript": "^1.0.9",
+        "@types/cookie": "^0.6.0",
+        "acorn": "^8.16.0",
+        "cookie": "^0.6.0",
+        "devalue": "^5.8.1",
+        "esm-env": "^1.2.2",
+        "kleur": "^4.1.5",
+        "magic-string": "^0.30.5",
+        "mrmime": "^2.0.0",
+        "set-cookie-parser": "^3.0.0",
+        "sirv": "^3.0.0"
+      },
+      "bin": {
+        "svelte-kit": "svelte-kit.js"
+      },
+      "engines": {
+        "node": ">=18.13"
+      },
+      "peerDependencies": {
+        "@opentelemetry/api": "^1.0.0",
+        "@sveltejs/vite-plugin-svelte": "^3.0.0 || ^4.0.0-next.1 || ^5.0.0 || ^6.0.0-next.0 || ^7.0.0",
+        "svelte": "^4.0.0 || ^5.0.0-next.0",
+        "typescript": "^5.3.3 || ^6.0.0",
+        "vite": "^5.0.3 || ^6.0.0 || ^7.0.0-beta.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@opentelemetry/api": {
+          "optional": true
+        },
+        "typescript": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@sveltejs/vite-plugin-svelte": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/@sveltejs/vite-plugin-svelte/-/vite-plugin-svelte-5.1.1.tgz",
+      "integrity": "sha512-Y1Cs7hhTc+a5E9Va/xwKlAJoariQyHY+5zBgCZg4PFWNYQ1nMN9sjK1zhw1gK69DuqVP++sht/1GZg1aRwmAXQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@sveltejs/vite-plugin-svelte-inspector": "^4.0.1",
+        "debug": "^4.4.1",
+        "deepmerge": "^4.3.1",
+        "kleur": "^4.1.5",
+        "magic-string": "^0.30.17",
+        "vitefu": "^1.0.6"
+      },
+      "engines": {
+        "node": "^18.0.0 || ^20.0.0 || >=22"
+      },
+      "peerDependencies": {
+        "svelte": "^5.0.0",
+        "vite": "^6.0.0"
+      }
+    },
+    "node_modules/@sveltejs/vite-plugin-svelte-inspector": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/@sveltejs/vite-plugin-svelte-inspector/-/vite-plugin-svelte-inspector-4.0.1.tgz",
+      "integrity": "sha512-J/Nmb2Q2y7mck2hyCX4ckVHcR5tu2J+MtBEQqpDrrgELZ2uvraQcK/ioCV61AqkdXFgriksOKIceDcQmqnGhVw==",
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^4.3.7"
+      },
+      "engines": {
+        "node": "^18.0.0 || ^20.0.0 || >=22"
+      },
+      "peerDependencies": {
+        "@sveltejs/vite-plugin-svelte": "^5.0.0",
+        "svelte": "^5.0.0",
+        "vite": "^6.0.0"
+      }
+    },
+    "node_modules/@types/cookie": {
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/@types/cookie/-/cookie-0.6.0.tgz",
+      "integrity": "sha512-4Kh9a6B2bQciAhf7FSuMRRkUWecJgJu9nPnx3yzpsfXX/c50REIqpHY4C82bXP90qrLtXtkDxTZosYO3UpOwlA==",
+      "license": "MIT"
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
+      "license": "MIT"
+    },
+    "node_modules/@types/node": {
+      "version": "24.13.3",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.13.3.tgz",
+      "integrity": "sha512-Dh8vAsV36ig5wa9OX4pXvMc9D3Veibfw2wix0CUwYODLD8nkj9UsLjASr49nPg+2eKzxhBV+v7L8pXvT4e639Q==",
+      "devOptional": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~7.18.0"
+      }
+    },
+    "node_modules/@types/resolve": {
+      "version": "1.20.2",
+      "resolved": "https://registry.npmjs.org/@types/resolve/-/resolve-1.20.2.tgz",
+      "integrity": "sha512-60BCwRFOZCQhDncwQdxxeOEEkbc5dIMccYLwbxsS4TUNeVECQ/pBJ0j09mrHOl/JJvpRPGwO9SvE4nR2Nb/a4Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/trusted-types": {
+      "version": "2.0.7",
+      "resolved": "https://registry.npmjs.org/@types/trusted-types/-/trusted-types-2.0.7.tgz",
+      "integrity": "sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==",
+      "license": "MIT"
+    },
+    "node_modules/acorn": {
+      "version": "8.17.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.17.0.tgz",
+      "integrity": "sha512-xRQbDb9BnwDafYNn6Vwl839DYVjqXYb1XVGtWAZ1kcDc6iwAL4hg3B1dZlRiuENFeO2H53gFG3in621AdERVAg==",
+      "license": "MIT",
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/aria-query": {
+      "version": "5.3.1",
+      "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.1.tgz",
+      "integrity": "sha512-Z/ZeOgVl7bcSYZ/u/rh0fOpvEpq//LZmdbkXyc7syVzjPAhfOa9ebsdTSjEBDU4vs5nC98Kfduj1uFo0qyET3g==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/autoprefixer": {
+      "version": "10.5.2",
+      "resolved": "https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.5.2.tgz",
+      "integrity": "sha512-rD5t5DwOjJdmSORcTq64j8MawTC+tbQ+HHqjR4NDumamy/ambn1UJrlKL+KdwujWxMkFjPM3pPHOEA9tl4767Q==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/autoprefixer"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "browserslist": "^4.28.4",
+        "caniuse-lite": "^1.0.30001799",
+        "fraction.js": "^5.3.4",
+        "picocolors": "^1.1.1",
+        "postcss-value-parser": "^4.2.0"
+      },
+      "bin": {
+        "autoprefixer": "bin/autoprefixer"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      },
+      "peerDependencies": {
+        "postcss": "^8.1.0"
+      }
+    },
+    "node_modules/axobject-query": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/axobject-query/-/axobject-query-4.1.0.tgz",
+      "integrity": "sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/baseline-browser-mapping": {
+      "version": "2.10.43",
+      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.43.tgz",
+      "integrity": "sha512-AjYpR78kDWAY3Efj+cDTFH9t9SCoL7OoTp1BOb0mQV7S+6CiLwnWM3FyxhJtdPufDFKzmCSFoUncKjWgJEZTCQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "baseline-browser-mapping": "dist/cli.cjs"
+      },
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/browserslist": {
+      "version": "4.28.6",
+      "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.6.tgz",
+      "integrity": "sha512-FQBYNK15VMslhLHpA7+n+n1GOlF1kId2xcCg7/j95f24AOF6VDYMNH4mFxF7KuaTdv627faazpOAjFzMrfJOUw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/browserslist"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "baseline-browser-mapping": "^2.10.42",
+        "caniuse-lite": "^1.0.30001803",
+        "electron-to-chromium": "^1.5.389",
+        "node-releases": "^2.0.51",
+        "update-browserslist-db": "^1.2.3"
+      },
+      "bin": {
+        "browserslist": "cli.js"
+      },
+      "engines": {
+        "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
+      }
+    },
+    "node_modules/caniuse-lite": {
+      "version": "1.0.30001805",
+      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001805.tgz",
+      "integrity": "sha512-52noaS3DubycKSXaU30TwPGIp+POyQSUVa5jBEq3vkRkY0kjyb3LQgvhU6WGyCcyXqVLWO0Cw0Q6BSdD0kUfVA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/caniuse-lite"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "CC-BY-4.0"
+    },
+    "node_modules/chokidar": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
+      "integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "readdirp": "^4.0.1"
+      },
+      "engines": {
+        "node": ">= 14.16.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/clsx": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
+      "integrity": "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/commondir": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/commondir/-/commondir-1.0.1.tgz",
+      "integrity": "sha512-W9pAhw0ja1Edb5GVdIF1mjZw/ASI0AlShXM83UUGe2DVr5TdAPEA1OA8m/g8zWp9x6On7gqufY+FatDbC3MDQg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/cookie": {
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz",
+      "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/css-blank-pseudo": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/css-blank-pseudo/-/css-blank-pseudo-8.0.1.tgz",
+      "integrity": "sha512-C5B2e5hCM4llrQkUms+KnWEMVW8K1n2XvX9G7ppfMZJQ7KAS/4rNnkP1Cs+HhWriOz1mWWTMFD4j1J7s31Dgug==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "postcss-selector-parser": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/css-has-pseudo": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/css-has-pseudo/-/css-has-pseudo-8.0.0.tgz",
+      "integrity": "sha512-Uz/bsHRbOeir/5Oeuz85tq/yLJLxX+3dpoRdjNTshs6jjqwUg8XaEZGDd0ci3fw7l53Srw0EkJ8mYan0eW5uGQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/selector-specificity": "^6.0.0",
+        "postcss-selector-parser": "^7.1.1",
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/css-prefers-color-scheme": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/css-prefers-color-scheme/-/css-prefers-color-scheme-11.0.0.tgz",
+      "integrity": "sha512-fv0mgtwUhh2m9iio3Kxc2CkrogjIaRdMFaaqyzSFdii17JF4cfPyMNX72B15ZW2Nrr/NZUpxI4dec1VMHYJvdw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/cssdb": {
+      "version": "8.9.0",
+      "resolved": "https://registry.npmjs.org/cssdb/-/cssdb-8.9.0.tgz",
+      "integrity": "sha512-J8jOU/hLjaXcO1LldOLraJSQpfLXRKof0I7mtbRyOy2AAXgqst0x9rlgi2qXeD6d0ou3ZLqcPAMqYVbpCbrxEw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        }
+      ],
+      "license": "MIT-0"
+    },
+    "node_modules/cssesc": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/cssesc/-/cssesc-3.0.0.tgz",
+      "integrity": "sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "cssesc": "bin/cssesc"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/debug": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/deepmerge": {
+      "version": "4.3.1",
+      "resolved": "https://registry.npmjs.org/deepmerge/-/deepmerge-4.3.1.tgz",
+      "integrity": "sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/devalue": {
+      "version": "5.8.1",
+      "resolved": "https://registry.npmjs.org/devalue/-/devalue-5.8.1.tgz",
+      "integrity": "sha512-4CXDYRBGqN+57wVJkuXBYmpAVUSg3L6JAQa/DFqm238G73E1wuyc/JhGQJzN7vUf/CMphYau2zXbfWzDR5aTEw==",
+      "license": "MIT"
+    },
+    "node_modules/electron-to-chromium": {
+      "version": "1.5.389",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.389.tgz",
+      "integrity": "sha512-cEto7aeOqBfU1D+c5py5pE+ooscKE75JifxLBdFUZsqAxRS6y7kebtxAZvICszSl05gPjYHDTjY+lXpyGvpJbg==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/es-errors": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
+      "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/esbuild": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz",
+      "integrity": "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.25.12",
+        "@esbuild/android-arm": "0.25.12",
+        "@esbuild/android-arm64": "0.25.12",
+        "@esbuild/android-x64": "0.25.12",
+        "@esbuild/darwin-arm64": "0.25.12",
+        "@esbuild/darwin-x64": "0.25.12",
+        "@esbuild/freebsd-arm64": "0.25.12",
+        "@esbuild/freebsd-x64": "0.25.12",
+        "@esbuild/linux-arm": "0.25.12",
+        "@esbuild/linux-arm64": "0.25.12",
+        "@esbuild/linux-ia32": "0.25.12",
+        "@esbuild/linux-loong64": "0.25.12",
+        "@esbuild/linux-mips64el": "0.25.12",
+        "@esbuild/linux-ppc64": "0.25.12",
+        "@esbuild/linux-riscv64": "0.25.12",
+        "@esbuild/linux-s390x": "0.25.12",
+        "@esbuild/linux-x64": "0.25.12",
+        "@esbuild/netbsd-arm64": "0.25.12",
+        "@esbuild/netbsd-x64": "0.25.12",
+        "@esbuild/openbsd-arm64": "0.25.12",
+        "@esbuild/openbsd-x64": "0.25.12",
+        "@esbuild/openharmony-arm64": "0.25.12",
+        "@esbuild/sunos-x64": "0.25.12",
+        "@esbuild/win32-arm64": "0.25.12",
+        "@esbuild/win32-ia32": "0.25.12",
+        "@esbuild/win32-x64": "0.25.12"
+      }
+    },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/esm-env": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/esm-env/-/esm-env-1.2.2.tgz",
+      "integrity": "sha512-Epxrv+Nr/CaL4ZcFGPJIYLWFom+YeV1DqMLHJoEd9SYRxNbaFruBwfEX/kkHUJf55j2+TUbmDcmuilbP1TmXHA==",
+      "license": "MIT"
+    },
+    "node_modules/esrap": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/esrap/-/esrap-2.3.0.tgz",
+      "integrity": "sha512-GQ/7RN8uOtEfNpzZzBMTzW9JBcX42oaSVtPzdF+6cEL8pqIL094iUpr9jzYGn4O4P/1S60dJ6izyT8F4LYARng==",
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.4.15"
+      },
+      "peerDependencies": {
+        "@typescript-eslint/types": "^8.2.0"
+      },
+      "peerDependenciesMeta": {
+        "@typescript-eslint/types": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/estree-walker": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-2.0.2.tgz",
+      "integrity": "sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/fdir": {
+      "version": "6.5.0",
+      "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+      "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "peerDependencies": {
+        "picomatch": "^3 || ^4"
+      },
+      "peerDependenciesMeta": {
+        "picomatch": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/fraction.js": {
+      "version": "5.3.4",
+      "resolved": "https://registry.npmjs.org/fraction.js/-/fraction.js-5.3.4.tgz",
+      "integrity": "sha512-1X1NTtiJphryn/uLQz3whtY6jK3fTqoE3ohKs0tT+Ujr1W59oopxmoEh7Lu5p6vBaPbgoM0bzveAW4Qi5RyWDQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/rawify"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/function-bind": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
+      "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/hasown": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.4.tgz",
+      "integrity": "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "function-bind": "^1.1.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/is-core-module": {
+      "version": "2.16.2",
+      "resolved": "https://registry.npmjs.org/is-core-module/-/is-core-module-2.16.2.tgz",
+      "integrity": "sha512-evOr8xfXKxE6qSR0hSXL2r3sd7ALj8+7jQEUvPYcm5sgZFdJ+AYzT6yNmJenvIYQBgIGwfwz08sL8zoL7yq2BA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "hasown": "^2.0.3"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/is-module": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/is-module/-/is-module-1.0.0.tgz",
+      "integrity": "sha512-51ypPSPCoTEIN9dy5Oy+h4pShgJmPCygKfyRCISBI+JoWT/2oJvK8QPxmwv7b/p239jXrm9M1mlQbyKJ5A152g==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/is-reference": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/is-reference/-/is-reference-3.0.3.tgz",
+      "integrity": "sha512-ixkJoqQvAP88E6wLydLGGqCJsrFUnqoH6HnaczB8XmDH1oaWU+xxdptvikTgaEhtZ53Ky6YXiBuUI2WXLMCwjw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.6"
+      }
+    },
+    "node_modules/jose": {
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.3.tgz",
+      "integrity": "sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/panva"
+      }
+    },
+    "node_modules/kleur": {
+      "version": "4.1.5",
+      "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz",
+      "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/locate-character": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/locate-character/-/locate-character-3.0.0.tgz",
+      "integrity": "sha512-SW13ws7BjaeJ6p7Q6CO2nchbYEc3X3J6WrmTTDto7yMPqVSZTUyY5Tjbid+Ab8gLnATtygYtiDIJGQRRn2ZOiA==",
+      "license": "MIT"
+    },
+    "node_modules/magic-string": {
+      "version": "0.30.21",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
+      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.5"
+      }
+    },
+    "node_modules/mri": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/mri/-/mri-1.2.0.tgz",
+      "integrity": "sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/mrmime": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/mrmime/-/mrmime-2.0.1.tgz",
+      "integrity": "sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "license": "MIT"
+    },
+    "node_modules/nanoid": {
+      "version": "3.3.16",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.16.tgz",
+      "integrity": "sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
+    "node_modules/node-releases": {
+      "version": "2.0.51",
+      "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.51.tgz",
+      "integrity": "sha512-wRNIrw4DmVLKQlbgOMdkMx27Wrpzes2hh5Jtbi2bjPd+4wJstWIqP5A+lscnqbm0xxmT5Bpg8Lec5ItEBwx6BQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/oauth4webapi": {
+      "version": "3.8.6",
+      "resolved": "https://registry.npmjs.org/oauth4webapi/-/oauth4webapi-3.8.6.tgz",
+      "integrity": "sha512-iwemM91xz8nryHti2yTmg5fhyEMVOkOXwHNqbvcATjyajb5oQxCQzrNOA6uElRHuMhQQTKUyFKV9y/CNyg25BQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/panva"
+      }
+    },
+    "node_modules/path-parse": {
+      "version": "1.0.7",
+      "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz",
+      "integrity": "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "license": "ISC"
+    },
+    "node_modules/picomatch": {
+      "version": "4.0.5",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.5.tgz",
+      "integrity": "sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/postcss": {
+      "version": "8.5.19",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.19.tgz",
+      "integrity": "sha512-Mz8SaolMd8nB+G13WkORcxQKHZ/NE4xXevtkJHVuG+guo9/wYKlIMTKAqGdEmYOXR2ijPjTYNHssizdaVSUNdQ==",
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.12",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
+    "node_modules/postcss-attribute-case-insensitive": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-attribute-case-insensitive/-/postcss-attribute-case-insensitive-8.0.0.tgz",
+      "integrity": "sha512-fovIPEV35c2JzVXdmP+sp2xirbBMt54J+upU8u6TSj410kUU5+axgEzvBBSAX8KCybze8CFCelzFAw/FfWg2TA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "postcss-selector-parser": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-clamp": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/postcss-clamp/-/postcss-clamp-4.1.0.tgz",
+      "integrity": "sha512-ry4b1Llo/9zz+PKC+030KUnPITTJAHeOwjfAyyB60eT0AorGLdzp52s31OsPRHRf8NchkgFoG2y6fCfn1IV1Ow==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=7.6.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4.6"
+      }
+    },
+    "node_modules/postcss-color-functional-notation": {
+      "version": "8.0.6",
+      "resolved": "https://registry.npmjs.org/postcss-color-functional-notation/-/postcss-color-functional-notation-8.0.6.tgz",
+      "integrity": "sha512-JwHsQNb/zzjRN/RFdhWWb3bk6WiNs7KW85+vYtLP1YVL6MgPQn/2qNMgFrjD8Ymg+wfP3XlwtSrYUI+K4zPvHA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-color-hex-alpha": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-color-hex-alpha/-/postcss-color-hex-alpha-11.0.0.tgz",
+      "integrity": "sha512-NCGa6vjIyrjosz9GqRxVKbONBklz5TeipYqTJp3IqbnBWlBq5e5EMtG6MaX4vqk9LzocPfMQkuRK9tfk+OQuKg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/utilities": "^3.0.0",
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-color-rebeccapurple": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-color-rebeccapurple/-/postcss-color-rebeccapurple-11.0.0.tgz",
+      "integrity": "sha512-g9561mx7cbdqx7XeO/L+lJzVlzu7bICyXr72efBVKZGxIhvBBJf9fGXn3Cb6U4Bwh3LbzQO2e9NWBLVYdX5Eag==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/utilities": "^3.0.0",
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-custom-media": {
+      "version": "12.0.1",
+      "resolved": "https://registry.npmjs.org/postcss-custom-media/-/postcss-custom-media-12.0.1.tgz",
+      "integrity": "sha512-66syE14+VeqkUf0rRX0bvbTCbNRJF132jD+ceo8th1dap2YJEAqpdh5uG98CE3IbgHT7m9XM0GIlOazNWqQdeA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/cascade-layer-name-parser": "^3.0.0",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/media-query-list-parser": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-custom-properties": {
+      "version": "15.0.1",
+      "resolved": "https://registry.npmjs.org/postcss-custom-properties/-/postcss-custom-properties-15.0.1.tgz",
+      "integrity": "sha512-cuyq8sd8dLY0GLbelz1KB8IMIoDECo6RVXMeHeXY2Uw3Q05k/d1GVITdaKLsheqrHbnxlwxzSRZQQ5u+rNtbMg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/cascade-layer-name-parser": "^3.0.0",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/utilities": "^3.0.0",
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-custom-selectors": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/postcss-custom-selectors/-/postcss-custom-selectors-9.0.1.tgz",
+      "integrity": "sha512-2XBELy4DmdVKimChfaZ2id9u9CSGYQhiJ53SvlfBvMTzLMW2VxuMb9rHsMSQw9kRq/zSbhT5x13EaK8JSmK8KQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/cascade-layer-name-parser": "^3.0.0",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "postcss-selector-parser": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-dir-pseudo-class": {
+      "version": "10.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-dir-pseudo-class/-/postcss-dir-pseudo-class-10.0.0.tgz",
+      "integrity": "sha512-DmtIzULpyC8XaH4b5AaUgt4Jic4QmrECqidNCdR7u7naQFdnxX80YI06u238a+ZVRXwURDxVzy0s/UQnWmpVeg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "postcss-selector-parser": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-double-position-gradients": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/postcss-double-position-gradients/-/postcss-double-position-gradients-7.0.2.tgz",
+      "integrity": "sha512-X62YBNOxoCVvoUpV3uxdg5h86nbzJwF0ogLrgHUL73YsX8FJ5pGeOxRuaUcqhHxQ4wcoKY+O55lJAyCGsxZLJA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0",
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-focus-visible": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-focus-visible/-/postcss-focus-visible-11.0.0.tgz",
+      "integrity": "sha512-VG1a9kBKizUBWS66t5xyB4uLONBnvZLCmZXxT40FALu8EF0QgVZBYy5ApC0KhmpHsv+pvHMJHB3agKHwmocWjw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "postcss-selector-parser": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-focus-within": {
+      "version": "10.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-focus-within/-/postcss-focus-within-10.0.0.tgz",
+      "integrity": "sha512-dvql0fzUTG+gcJYp+KTbag5vAjuo94LDYZHkqDV1rnf5gPGer1v/SrmIZBdvKU8moep3HbcbujqGjzSb3DL53Q==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "postcss-selector-parser": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-font-variant": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-font-variant/-/postcss-font-variant-5.0.0.tgz",
+      "integrity": "sha512-1fmkBaCALD72CK2a9i468mA/+tr9/1cBxRRMXOUaZqO43oWPR5imcyPjXwuv7PXbCid4ndlP5zWhidQVVa3hmA==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "postcss": "^8.1.0"
+      }
+    },
+    "node_modules/postcss-gap-properties": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-gap-properties/-/postcss-gap-properties-7.0.0.tgz",
+      "integrity": "sha512-PSDF2QoZMRUbsINvXObQgxx4HExRP85QTT8qS/YN9fBsCPWCqUuwqAD6E6PNp0BqL/jU1eyWUBORaOK/J/9LDA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-image-set-function": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-image-set-function/-/postcss-image-set-function-8.0.0.tgz",
+      "integrity": "sha512-rEGNkOkNusf4+IuMmfEoIdLuVmvbExGbmG+MIsyV6jR5UaWSoyPcAYHV/PxzVDCmudyF+2Nh/o6Ub2saqUdnuA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/utilities": "^3.0.0",
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-lab-function": {
+      "version": "8.0.6",
+      "resolved": "https://registry.npmjs.org/postcss-lab-function/-/postcss-lab-function-8.0.6.tgz",
+      "integrity": "sha512-zFU65d+uKFTdkvJWPpEMgRwY0gh7RN5FD4aWfLxbeXeAkITSpODG6nH2GKAdbnA4jWjyPac1lw8osw+1ATMcWg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/utilities": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-logical": {
+      "version": "9.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-logical/-/postcss-logical-9.0.0.tgz",
+      "integrity": "sha512-A4LNd9dk3q/juEUA9Gd8ALhBO3TeOeYurnyHLlf2aAToD94VHR8c5Uv7KNmf8YVRhTxvWsyug4c5fKtARzyIRQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-nesting": {
+      "version": "14.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-nesting/-/postcss-nesting-14.0.0.tgz",
+      "integrity": "sha512-YGFOfVrjxYfeGTS5XctP1WCI5hu8Lr9SmntjfRC+iX5hCihEO+QZl9Ra+pkjqkgoVdDKvb2JccpElcowhZtzpw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/selector-resolve-nested": "^4.0.0",
+        "@csstools/selector-specificity": "^6.0.0",
+        "postcss-selector-parser": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-opacity-percentage": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-opacity-percentage/-/postcss-opacity-percentage-3.0.0.tgz",
+      "integrity": "sha512-K6HGVzyxUxd/VgZdX04DCtdwWJ4NGLG212US4/LA1TLAbHgmAsTWVR86o+gGIbFtnTkfOpb9sCRBx8K7HO66qQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "kofi",
+          "url": "https://ko-fi.com/mrcgrtz"
+        },
+        {
+          "type": "liberapay",
+          "url": "https://liberapay.com/mrcgrtz"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-overflow-shorthand": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-overflow-shorthand/-/postcss-overflow-shorthand-7.0.0.tgz",
+      "integrity": "sha512-9SLpjoUdGRoRrzoOdX66HbUs0+uDwfIAiXsRa7piKGOqPd6F4ZlON9oaDSP5r1Qpgmzw5L9Ht0undIK6igJPMA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-page-break": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/postcss-page-break/-/postcss-page-break-3.0.4.tgz",
+      "integrity": "sha512-1JGu8oCjVXLa9q9rFTo4MbeeA5FMe00/9C7lN4va606Rdb+HkxXtXsmEDrIraQ11fGz/WvKWa8gMuCKkrXpTsQ==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "postcss": "^8"
+      }
+    },
+    "node_modules/postcss-place": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-place/-/postcss-place-11.0.0.tgz",
+      "integrity": "sha512-fAifpyjQ+fuDRp2nmF95WbotqbpjdazebedahXdfBxy5sHembOLpBQ1cHveZD9ZmjK26tYM8tikeNaUlp/KfHA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "postcss-value-parser": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-preset-env": {
+      "version": "11.3.2",
+      "resolved": "https://registry.npmjs.org/postcss-preset-env/-/postcss-preset-env-11.3.2.tgz",
+      "integrity": "sha512-O7aA42UBH/89RkGy1YXgJqb+LxZ2+zvR8bHn9qyYcYc+lOo4g9TuIpb75nZT1tN77Bd6pX3DMZ+eYohS4MfKQg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "@csstools/postcss-alpha-function": "^2.0.7",
+        "@csstools/postcss-cascade-layers": "^6.0.0",
+        "@csstools/postcss-color-function": "^5.0.6",
+        "@csstools/postcss-color-function-display-p3-linear": "^2.0.6",
+        "@csstools/postcss-color-mix-function": "^4.0.6",
+        "@csstools/postcss-color-mix-variadic-function-arguments": "^2.0.6",
+        "@csstools/postcss-container-rule-prelude-list": "^1.0.1",
+        "@csstools/postcss-content-alt-text": "^3.0.2",
+        "@csstools/postcss-contrast-color-function": "^3.0.6",
+        "@csstools/postcss-exponential-functions": "^3.0.3",
+        "@csstools/postcss-font-format-keywords": "^5.0.0",
+        "@csstools/postcss-font-width-property": "^1.0.0",
+        "@csstools/postcss-gamut-mapping": "^3.0.6",
+        "@csstools/postcss-gradients-interpolation-method": "^6.0.6",
+        "@csstools/postcss-hwb-function": "^5.0.6",
+        "@csstools/postcss-ic-unit": "^5.0.2",
+        "@csstools/postcss-image-function": "^1.0.1",
+        "@csstools/postcss-initial": "^3.0.0",
+        "@csstools/postcss-is-pseudo-class": "^6.0.0",
+        "@csstools/postcss-light-dark-function": "^3.0.2",
+        "@csstools/postcss-logical-float-and-clear": "^4.0.0",
+        "@csstools/postcss-logical-overflow": "^3.0.0",
+        "@csstools/postcss-logical-overscroll-behavior": "^3.0.0",
+        "@csstools/postcss-logical-resize": "^4.0.0",
+        "@csstools/postcss-logical-viewport-units": "^4.0.0",
+        "@csstools/postcss-media-minmax": "^3.0.3",
+        "@csstools/postcss-media-queries-aspect-ratio-number-values": "^4.0.0",
+        "@csstools/postcss-mixins": "^1.0.0",
+        "@csstools/postcss-nested-calc": "^5.0.0",
+        "@csstools/postcss-normalize-display-values": "^5.0.1",
+        "@csstools/postcss-oklab-function": "^5.0.6",
+        "@csstools/postcss-position-area-property": "^2.0.0",
+        "@csstools/postcss-progressive-custom-properties": "^5.1.1",
+        "@csstools/postcss-property-rule-prelude-list": "^2.0.0",
+        "@csstools/postcss-random-function": "^3.0.3",
+        "@csstools/postcss-relative-color-syntax": "^4.0.6",
+        "@csstools/postcss-scope-pseudo-class": "^5.0.0",
+        "@csstools/postcss-sign-functions": "^2.0.3",
+        "@csstools/postcss-stepped-value-functions": "^5.0.3",
+        "@csstools/postcss-syntax-descriptor-syntax-production": "^2.0.0",
+        "@csstools/postcss-system-ui-font-family": "^2.0.0",
+        "@csstools/postcss-text-decoration-shorthand": "^5.0.4",
+        "@csstools/postcss-trigonometric-functions": "^5.0.3",
+        "@csstools/postcss-unset-value": "^5.0.0",
+        "autoprefixer": "^10.5.0",
+        "browserslist": "^4.28.1",
+        "css-blank-pseudo": "^8.0.1",
+        "css-has-pseudo": "^8.0.0",
+        "css-prefers-color-scheme": "^11.0.0",
+        "cssdb": "^8.9.0",
+        "postcss-attribute-case-insensitive": "^8.0.0",
+        "postcss-clamp": "^4.1.0",
+        "postcss-color-functional-notation": "^8.0.6",
+        "postcss-color-hex-alpha": "^11.0.0",
+        "postcss-color-rebeccapurple": "^11.0.0",
+        "postcss-custom-media": "^12.0.1",
+        "postcss-custom-properties": "^15.0.1",
+        "postcss-custom-selectors": "^9.0.1",
+        "postcss-dir-pseudo-class": "^10.0.0",
+        "postcss-double-position-gradients": "^7.0.2",
+        "postcss-focus-visible": "^11.0.0",
+        "postcss-focus-within": "^10.0.0",
+        "postcss-font-variant": "^5.0.0",
+        "postcss-gap-properties": "^7.0.0",
+        "postcss-image-set-function": "^8.0.0",
+        "postcss-lab-function": "^8.0.6",
+        "postcss-logical": "^9.0.0",
+        "postcss-nesting": "^14.0.0",
+        "postcss-opacity-percentage": "^3.0.0",
+        "postcss-overflow-shorthand": "^7.0.0",
+        "postcss-page-break": "^3.0.4",
+        "postcss-place": "^11.0.0",
+        "postcss-pseudo-class-any-link": "^11.0.0",
+        "postcss-replace-overflow-wrap": "^4.0.0",
+        "postcss-selector-not": "^9.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-pseudo-class-any-link": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-pseudo-class-any-link/-/postcss-pseudo-class-any-link-11.0.0.tgz",
+      "integrity": "sha512-DNFZ4GMa3C3pU5dM+UCTG1CEeLtS1ZqV5DKSqCTJQMn1G5jnd/30fS8+A7H4o5bSD3MOcnx+VgI+xPE9Z5Wvig==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "dependencies": {
+        "postcss-selector-parser": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-replace-overflow-wrap": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-replace-overflow-wrap/-/postcss-replace-overflow-wrap-4.0.0.tgz",
+      "integrity": "sha512-KmF7SBPphT4gPPcKZc7aDkweHiKEEO8cla/GjcBK+ckKxiZslIu3C4GCRW3DNfL0o7yW7kMQu9xlZ1kXRXLXtw==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "postcss": "^8.0.3"
+      }
+    },
+    "node_modules/postcss-selector-not": {
+      "version": "9.0.0",
+      "resolved": "https://registry.npmjs.org/postcss-selector-not/-/postcss-selector-not-9.0.0.tgz",
+      "integrity": "sha512-xhAtTdHnVU2M/CrpYOPyRUvg3njhVlKmn2GNYXDaRJV9Ygx4d5OkSkc7NINzjUqnbDFtaKXlISOBeyMXU/zyFQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "postcss-selector-parser": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4"
+      }
+    },
+    "node_modules/postcss-selector-parser": {
+      "version": "7.1.4",
+      "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.4.tgz",
+      "integrity": "sha512-HeP7D2wyhkR+XaK6v4W8oRF62Dsz4flyuczALJp61GckGm42u1saSSJ/0auvcBqxs3jMRFEcPK34At/0JBKdOg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cssesc": "^3.0.0",
+        "util-deprecate": "^1.0.2"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/postcss-value-parser": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz",
+      "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/preact": {
+      "version": "10.24.3",
+      "resolved": "https://registry.npmjs.org/preact/-/preact-10.24.3.tgz",
+      "integrity": "sha512-Z2dPnBnMUfyQfSQ+GBdsGa16hz35YmLmtTLhM169uW944hYL6xzTYkJjC07j+Wosz733pMWx0fgON3JNw1jJQA==",
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/preact"
+      }
+    },
+    "node_modules/preact-render-to-string": {
+      "version": "6.5.11",
+      "resolved": "https://registry.npmjs.org/preact-render-to-string/-/preact-render-to-string-6.5.11.tgz",
+      "integrity": "sha512-ubnauqoGczeGISiOh6RjX0/cdaF8v/oDXIjO85XALCQjwQP+SB4RDXXtvZ6yTYSjG+PC1QRP2AhPgCEsM2EvUw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "preact": ">=10"
+      }
+    },
+    "node_modules/readdirp": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
+      "integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14.18.0"
+      },
+      "funding": {
+        "type": "individual",
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/resolve": {
+      "version": "1.22.12",
+      "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.12.tgz",
+      "integrity": "sha512-TyeJ1zif53BPfHootBGwPRYT1RUt6oGWsaQr8UyZW/eAm9bKoijtvruSDEmZHm92CwS9nj7/fWttqPCgzep8CA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "es-errors": "^1.3.0",
+        "is-core-module": "^2.16.1",
+        "path-parse": "^1.0.7",
+        "supports-preserve-symlinks-flag": "^1.0.0"
+      },
+      "bin": {
+        "resolve": "bin/resolve"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/rollup": {
+      "version": "4.62.2",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.62.2.tgz",
+      "integrity": "sha512-RFnrW4lhXA3s3eqHDZvN654g8OTjzRfqpIRJYczCGB6HzphckVAi/Qh4tbPUbRuDi7s1Llv8g/NspLkttY3gTA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "1.0.9"
+      },
+      "bin": {
+        "rollup": "dist/bin/rollup"
+      },
+      "engines": {
+        "node": ">=18.0.0",
+        "npm": ">=8.0.0"
+      },
+      "optionalDependencies": {
+        "@rollup/rollup-android-arm-eabi": "4.62.2",
+        "@rollup/rollup-android-arm64": "4.62.2",
+        "@rollup/rollup-darwin-arm64": "4.62.2",
+        "@rollup/rollup-darwin-x64": "4.62.2",
+        "@rollup/rollup-freebsd-arm64": "4.62.2",
+        "@rollup/rollup-freebsd-x64": "4.62.2",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.62.2",
+        "@rollup/rollup-linux-arm-musleabihf": "4.62.2",
+        "@rollup/rollup-linux-arm64-gnu": "4.62.2",
+        "@rollup/rollup-linux-arm64-musl": "4.62.2",
+        "@rollup/rollup-linux-loong64-gnu": "4.62.2",
+        "@rollup/rollup-linux-loong64-musl": "4.62.2",
+        "@rollup/rollup-linux-ppc64-gnu": "4.62.2",
+        "@rollup/rollup-linux-ppc64-musl": "4.62.2",
+        "@rollup/rollup-linux-riscv64-gnu": "4.62.2",
+        "@rollup/rollup-linux-riscv64-musl": "4.62.2",
+        "@rollup/rollup-linux-s390x-gnu": "4.62.2",
+        "@rollup/rollup-linux-x64-gnu": "4.62.2",
+        "@rollup/rollup-linux-x64-musl": "4.62.2",
+        "@rollup/rollup-openbsd-x64": "4.62.2",
+        "@rollup/rollup-openharmony-arm64": "4.62.2",
+        "@rollup/rollup-win32-arm64-msvc": "4.62.2",
+        "@rollup/rollup-win32-ia32-msvc": "4.62.2",
+        "@rollup/rollup-win32-x64-gnu": "4.62.2",
+        "@rollup/rollup-win32-x64-msvc": "4.62.2",
+        "fsevents": "~2.3.2"
+      }
+    },
+    "node_modules/sade": {
+      "version": "1.8.1",
+      "resolved": "https://registry.npmjs.org/sade/-/sade-1.8.1.tgz",
+      "integrity": "sha512-xal3CZX1Xlo/k4ApwCFrHVACi9fBqJ7V+mwhBsuf/1IOKbBy098Fex+Wa/5QMubw09pSZ/u8EY8PWgevJsXp1A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mri": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/set-cookie-parser": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/set-cookie-parser/-/set-cookie-parser-3.1.2.tgz",
+      "integrity": "sha512-5/r/lTwbJ3zQ+qwdUFZYeRNqda7P5HD8zQKqlSjdGt1/S0cjLAphHusj4Y58ahDtWn/g32xrIS58/ikOvwl0Lw==",
+      "license": "MIT"
+    },
+    "node_modules/sirv": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/sirv/-/sirv-3.0.2.tgz",
+      "integrity": "sha512-2wcC/oGxHis/BoHkkPwldgiPSYcpZK3JU28WoMVv55yHJgcZ8rlXvuG9iZggz+sU1d4bRgIGASwyWqjxu3FM0g==",
+      "license": "MIT",
+      "dependencies": {
+        "@polka/url": "^1.0.0-next.24",
+        "mrmime": "^2.0.0",
+        "totalist": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/supports-preserve-symlinks-flag": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz",
+      "integrity": "sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/svelte": {
+      "version": "5.56.7",
+      "resolved": "https://registry.npmjs.org/svelte/-/svelte-5.56.7.tgz",
+      "integrity": "sha512-5qERUZX80oQj6XrDMUmD2Uhd/cIpCPDWWKBK3ZHmyRUC9apPyamWM8xMo31mbWsIQxwG2hVoSnOJ/EcnhVkkzQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/remapping": "^2.3.4",
+        "@jridgewell/sourcemap-codec": "^1.5.0",
+        "@sveltejs/acorn-typescript": "^1.0.10",
+        "@types/estree": "^1.0.5",
+        "@types/trusted-types": "^2.0.7",
+        "acorn": "^8.12.1",
+        "aria-query": "5.3.1",
+        "axobject-query": "^4.1.0",
+        "clsx": "^2.1.1",
+        "devalue": "^5.8.1",
+        "esm-env": "^1.2.1",
+        "esrap": "^2.2.12",
+        "is-reference": "^3.0.3",
+        "locate-character": "^3.0.0",
+        "magic-string": "^0.30.11",
+        "zimmerframe": "^1.1.2"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/svelte-check": {
+      "version": "4.1.7",
+      "resolved": "https://registry.npmjs.org/svelte-check/-/svelte-check-4.1.7.tgz",
+      "integrity": "sha512-1jX4BzXrQJhC/Jt3SqYf6Ntu//vmfc6VWp07JkRfK2nn+22yIblspVUo96gzMkg0Zov8lQicxhxsMzOctwcMQQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/trace-mapping": "^0.3.25",
+        "chokidar": "^4.0.1",
+        "fdir": "^6.2.0",
+        "picocolors": "^1.0.0",
+        "sade": "^1.7.4"
+      },
+      "bin": {
+        "svelte-check": "bin/svelte-check"
+      },
+      "engines": {
+        "node": ">= 18.0.0"
+      },
+      "peerDependencies": {
+        "svelte": "^4.0.0 || ^5.0.0-next.0",
+        "typescript": ">=5.0.0"
+      }
+    },
+    "node_modules/tinyglobby": {
+      "version": "0.2.17",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
+      "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==",
+      "license": "MIT",
+      "dependencies": {
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/SuperchupuDev"
+      }
+    },
+    "node_modules/totalist": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/totalist/-/totalist-3.0.1.tgz",
+      "integrity": "sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.8.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.8.3.tgz",
+      "integrity": "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ==",
+      "devOptional": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "7.18.2",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz",
+      "integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==",
+      "devOptional": true,
+      "license": "MIT"
+    },
+    "node_modules/update-browserslist-db": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
+      "integrity": "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/browserslist"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "escalade": "^3.2.0",
+        "picocolors": "^1.1.1"
+      },
+      "bin": {
+        "update-browserslist-db": "cli.js"
+      },
+      "peerDependencies": {
+        "browserslist": ">= 4.21.0"
+      }
+    },
+    "node_modules/util-deprecate": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
+      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/vite": {
+      "version": "6.4.3",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.3.tgz",
+      "integrity": "sha512-NTKlcQjlAK7MlQoyb6LgaqHc8sso/pVyUJYWMws3jg21uTJw/LddqIFPcPqP6PzpgbIcZyKI85sFE4HBrQDA8A==",
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "^0.25.0",
+        "fdir": "^6.4.4",
+        "picomatch": "^4.0.2",
+        "postcss": "^8.5.3",
+        "rollup": "^4.34.9",
+        "tinyglobby": "^0.2.13"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^18.0.0 || ^20.0.0 || >=22.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0",
+        "jiti": ">=1.21.0",
+        "less": "*",
+        "lightningcss": "^1.21.0",
+        "sass": "*",
+        "sass-embedded": "*",
+        "stylus": "*",
+        "sugarss": "*",
+        "terser": "^5.16.0",
+        "tsx": "^4.8.1",
+        "yaml": "^2.4.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "jiti": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        },
+        "tsx": {
+          "optional": true
+        },
+        "yaml": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vitefu": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/vitefu/-/vitefu-1.1.3.tgz",
+      "integrity": "sha512-ub4okH7Z5KLjb6hDyjqrGXqWtWvoYdU3IGm/NorpgHncKoLTCfRIbvlhBm7r0YstIaQRYlp4yEbFqDcKSzXSSg==",
+      "license": "MIT",
+      "workspaces": [
+        "tests/deps/*",
+        "tests/projects/*",
+        "tests/projects/workspace/packages/*"
+      ],
+      "peerDependencies": {
+        "vite": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/zimmerframe": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/zimmerframe/-/zimmerframe-1.1.4.tgz",
+      "integrity": "sha512-B58NGBEoc8Y9MWWCQGl/gq9xBCe4IiKM0a2x7GZdQKOW5Exr8S1W24J6OgM1njK8xCRGvAJIL/MxXHf6SkmQKQ==",
+      "license": "MIT"
+    }
+  }
+}
diff --git a/tests/e2e-ui/ui/package.json b/tests/e2e-ui/ui/package.json
new file mode 100644
index 00000000..20e4d10e
--- /dev/null
+++ b/tests/e2e-ui/ui/package.json
@@ -0,0 +1,39 @@
+{
+  "name": "e2e-ui-app",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "prepare": "svelte-kit sync || echo \"\"",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "client:generate": "node scripts/distributed-client.mjs generate",
+    "client:check": "node scripts/distributed-client.mjs check",
+    "gen": "make -C .. gen-client",
+    "gen:check": "make -C .. check-client",
+    "test": "node --test tests/*.test.mjs"
+  },
+  "dependencies": {
+    "@auth/core": "^0.41.3",
+    "@auth/sveltekit": "^1.11.3",
+    "@hops-ops/distributed": "file:../../../js"
+  },
+  "overrides": {
+    "cookie": "0.7.2"
+  },
+  "devDependencies": {
+    "@csstools/postcss-global-data": "^4.0.0",
+    "@lucide/svelte": "0.577.0",
+    "@sveltejs/adapter-node": "5.2.12",
+    "@sveltejs/kit": "2.70.1",
+    "@sveltejs/vite-plugin-svelte": "5.1.1",
+    "@types/node": "^24.7.0",
+    "postcss-preset-env": "^11.1.1",
+    "svelte": "5.56.7",
+    "svelte-check": "4.1.7",
+    "typescript": "5.8.3",
+    "vite": "6.4.3"
+  }
+}
diff --git a/tests/e2e-ui/ui/postcss.config.js b/tests/e2e-ui/ui/postcss.config.js
new file mode 100644
index 00000000..f3cb078c
--- /dev/null
+++ b/tests/e2e-ui/ui/postcss.config.js
@@ -0,0 +1,15 @@
+export default {
+	plugins: {
+		'@csstools/postcss-global-data': {
+			files: ['./src/custom-media.css']
+		},
+		'postcss-preset-env': {
+			stage: 2,
+			features: {
+				'nesting-rules': true,
+				'custom-media-queries': true,
+				'media-query-ranges': true
+			}
+		}
+	}
+};
diff --git a/tests/e2e-ui/ui/scripts/distributed-client.mjs b/tests/e2e-ui/ui/scripts/distributed-client.mjs
new file mode 100644
index 00000000..87783da5
--- /dev/null
+++ b/tests/e2e-ui/ui/scripts/distributed-client.mjs
@@ -0,0 +1,17 @@
+import {
+	checkDistributedSvelteKit,
+	generateDistributedSvelteKit
+} from '@hops-ops/distributed/sveltekit/vite';
+
+import { distributedViteOptions } from '../distributed.config.js';
+
+const mode = process.argv[2];
+if (mode === 'generate') {
+	await generateDistributedSvelteKit(distributedViteOptions);
+	console.log('Generated Distributed user/admin clients from distributed.config.js');
+} else if (mode === 'check') {
+	await checkDistributedSvelteKit(distributedViteOptions);
+	console.log('Distributed user/admin clients are current');
+} else {
+	throw new Error('usage: node scripts/distributed-client.mjs <generate|check>');
+}
diff --git a/tests/e2e-ui/ui/src/app.css b/tests/e2e-ui/ui/src/app.css
new file mode 100644
index 00000000..3dc5b926
--- /dev/null
+++ b/tests/e2e-ui/ui/src/app.css
@@ -0,0 +1,136 @@
+/* ==========================================================================
+   e2e-ui — Neutral wireframe
+   Soft paper ground, graphite ink, quiet blue accent. Calm type for product vision.
+   ========================================================================== */
+
+@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=Inter:wght@400;500;600&family=Newsreader:opsz,wght@6..72,400;6..72,500&display=swap');
+
+@custom-media --tablet-up (width >= 768px);
+@custom-media --desktop-up (width >= 1024px);
+
+:root {
+	/* Wireframe palette */
+	--wf-bg: #f6f5f2;
+	--wf-bg-elevated: #ffffff;
+	--wf-ink: #1c1c1a;
+	--wf-ink-soft: #5c5c56;
+	--wf-ink-muted: #8a8a82;
+	--wf-line: #e2e0d9;
+	--wf-line-strong: #cdcabe;
+	--wf-accent: #3d5a80;
+	--wf-accent-soft: rgba(61, 90, 128, 0.08);
+	--wf-code-bg: #1c1c1a;
+	--wf-code-fg: #e8e6e0;
+	--wf-code-muted: #8a9088;
+	--wf-code-kw: #9ec5e8;
+	--wf-danger: #b33a3a;
+	--wf-success: #2f6f4e;
+
+	--wf-sans: 'Inter', system-ui, -apple-system, 'Segoe UI', sans-serif;
+	--wf-serif: 'Newsreader', 'Iowan Old Style', Georgia, serif;
+	--wf-mono: 'IBM Plex Mono', ui-monospace, 'SF Mono', Menlo, monospace;
+
+	--wf-max: 68rem;
+	--wf-gutter: clamp(1.5rem, 5vw, 3rem);
+	--wf-section-y: clamp(4.5rem, 10vw, 7.5rem);
+	--wf-radius: 6px;
+	--ease: cubic-bezier(0.22, 1, 0.36, 1);
+
+	/* Fixture page compat (todos/chat light surfaces) */
+	--df-ink: var(--wf-ink);
+	--df-ink-soft: var(--wf-ink-soft);
+	--df-ink-muted: var(--wf-ink-muted);
+	--df-surface: var(--wf-bg);
+	--df-surface-raised: var(--wf-bg-elevated);
+	--df-surface-dark: var(--wf-ink);
+	--df-surface-code: var(--wf-code-bg);
+	--df-border: var(--wf-line);
+	--df-border-strong: var(--wf-line-strong);
+	--df-accent: var(--wf-accent);
+	--df-accent-bright: #5a7a9e;
+	--df-accent-dim: var(--wf-accent-soft);
+	--df-danger: var(--wf-danger);
+	--df-success: var(--wf-success);
+	--df-font: var(--wf-sans);
+	--df-mono: var(--wf-mono);
+	--df-max: var(--wf-max);
+	--df-radius: var(--wf-radius);
+	--df-radius-lg: 10px;
+	--df-shadow-sm: 0 1px 2px rgba(28, 28, 26, 0.04);
+	--df-shadow-md: 0 8px 24px rgba(28, 28, 26, 0.06);
+	--df-shadow-lg: 0 16px 40px rgba(28, 28, 26, 0.08);
+
+	--hops-navy: var(--wf-ink);
+	--hops-navy-deep: #111110;
+	--hops-navy-light: #2a2a28;
+	--hops-orange: var(--wf-accent);
+	--hops-orange-light: #5a7a9e;
+	--hops-orange-dark: #2c4563;
+	--hops-bg-light: var(--wf-bg);
+	--hops-bg-cream: #f0efe9;
+	--hops-bg-white: var(--wf-bg-elevated);
+	--hops-text-primary: var(--wf-ink);
+	--hops-text-secondary: var(--wf-ink-soft);
+	--hops-text-muted: var(--wf-ink-muted);
+	--hops-text-inverse: #f6f5f2;
+	--hops-success: var(--wf-success);
+	--hops-warning: #9a7420;
+	--hops-danger: var(--wf-danger);
+	--hops-border: var(--wf-line);
+	--hops-border-strong: var(--wf-line-strong);
+	--font-display: var(--wf-sans);
+	--font-body: var(--wf-sans);
+	--font-mono: var(--wf-mono);
+	--shadow-sm: var(--df-shadow-sm);
+	--shadow-md: var(--df-shadow-md);
+	--shadow-lg: var(--df-shadow-lg);
+	--shadow-orange: 0 8px 24px rgba(61, 90, 128, 0.12);
+	--container-max: var(--wf-max);
+	--section-padding: var(--wf-section-y);
+	--ease-out-expo: var(--ease);
+}
+
+*,
+*::before,
+*::after {
+	box-sizing: border-box;
+}
+
+html {
+	scroll-behavior: smooth;
+}
+
+body {
+	margin: 0;
+	min-height: 100vh;
+	font-family: var(--wf-sans);
+	font-size: 1rem;
+	line-height: 1.6;
+	color: var(--wf-ink);
+	background: var(--wf-bg);
+	-webkit-font-smoothing: antialiased;
+}
+
+/* No global transparent overlay — solid page ground only.
+   Hero may use a local soft grid (see .wf-hero). */
+
+a {
+	color: var(--wf-accent);
+}
+
+code,
+pre {
+	font-family: var(--wf-mono);
+}
+
+main {
+	position: relative;
+	z-index: 1;
+	min-height: 100vh;
+}
+
+/* Chrome / home / product page skins live in:
+   - $lib/styles/chrome.css (root layout)
+   - $lib/styles/home.css (home route only)
+   - $lib/components/product/* (scoped)
+*/
diff --git a/tests/e2e-ui/ui/src/app.d.ts b/tests/e2e-ui/ui/src/app.d.ts
new file mode 100644
index 00000000..da08e6da
--- /dev/null
+++ b/tests/e2e-ui/ui/src/app.d.ts
@@ -0,0 +1,13 @@
+// See https://svelte.dev/docs/kit/types#app.d.ts
+// for information about these interfaces
+declare global {
+	namespace App {
+		// interface Error {}
+		// interface Locals {}
+		// interface PageData {}
+		// interface PageState {}
+		// interface Platform {}
+	}
+}
+
+export {};
diff --git a/tests/e2e-ui/ui/src/app.html b/tests/e2e-ui/ui/src/app.html
new file mode 100644
index 00000000..b9190fa8
--- /dev/null
+++ b/tests/e2e-ui/ui/src/app.html
@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" href="%sveltekit.assets%/favicon.png" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<meta
+			name="description"
+			content="e2e-ui — Distributed framework template: CQRS, OIDC, SSR GraphQL, live subscriptions."
+		/>
+		<title>e2e-ui · Distributed template</title>
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>
diff --git a/tests/e2e-ui/ui/src/auth.ts b/tests/e2e-ui/ui/src/auth.ts
new file mode 100644
index 00000000..4ff76323
--- /dev/null
+++ b/tests/e2e-ui/ui/src/auth.ts
@@ -0,0 +1,476 @@
+import { SvelteKitAuth } from '@auth/sveltekit';
+import { env } from '$env/dynamic/private';
+import { cleanEnvValue } from '$lib/clean-env';
+import { oidcAudience, oidcScopes } from '$lib/server/oidc-scopes';
+
+declare module '@auth/sveltekit' {
+	interface Session {
+		accessToken?: string;
+		idToken?: string;
+		expiresAt?: number;
+		refreshAfter?: number;
+		hasAccessToken?: boolean;
+		hasRefreshToken?: boolean;
+		hasIdToken?: boolean;
+		error?: string;
+	}
+
+	interface User {
+		id?: string;
+		groups?: string[];
+		username?: string;
+		emailVerified?: boolean;
+	}
+}
+
+/**
+ * Where we look for role keys after Zitadel asserts them on the token.
+ * Zitadel term is **project roles** (role keys), not IdP "groups" — we map those
+ * keys into `session.user.groups` for the rest of the app.
+ *
+ * Claims (object whose keys are role names, e.g. `{ "admin": { "<orgId>": "…" } }`):
+ * - `urn:zitadel:iam:org:project:roles` — current project
+ * - `urn:zitadel:iam:org:project:{projectId}:roles` — explicit project id
+ * - `urn:zitadel:iam:org:projects:roles` — all projects
+ */
+const DEFAULT_GROUP_CLAIMS = [
+	'groups',
+	'roles',
+	'urn:zitadel:iam:org:project:roles',
+	'urn:zitadel:iam:org:projects:roles'
+];
+const ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 60;
+const TOKEN_AUTH_BASIC = 'client_secret_basic';
+const TOKEN_AUTH_POST = 'client_secret_post';
+const TOKEN_AUTH_NONE = 'none';
+
+type TokenRecord = Record<string, unknown>;
+type SessionCookieSameSite = 'lax' | 'strict';
+const DEFAULT_SESSION_COOKIE_SAME_SITE: SessionCookieSameSite = 'lax';
+
+function envFirst(names: string[], fallback = '') {
+	for (const name of names) {
+		const value = cleanEnvValue(env[name]);
+		if (value) return value;
+	}
+
+	return fallback;
+}
+
+function envCsv(name: string, fallback: string[]) {
+	const value = env[name]?.trim();
+	if (!value) return fallback;
+
+	const items = value
+		.split(',')
+		.map((item) => item.trim())
+		.filter(Boolean);
+
+	return items.length ? items : fallback;
+}
+
+function oidcIssuer() {
+	return envFirst(['OIDC_ISSUER', 'ZITADEL_ISSUER']).replace(/\/+$/, '');
+}
+
+function oidcClientId() {
+	return envFirst(['OIDC_CLIENT_ID', 'ZITADEL_CLIENT_ID']);
+}
+
+function oidcClientSecret() {
+	return envFirst(['OIDC_CLIENT_SECRET', 'ZITADEL_CLIENT_SECRET']);
+}
+
+function oidcTokenAuthMethod() {
+	return envFirst(['OIDC_TOKEN_AUTH_METHOD'], TOKEN_AUTH_BASIC).toLowerCase();
+}
+
+function authSessionCookieSameSite(): SessionCookieSameSite {
+	const value = env.AUTH_SESSION_COOKIE_SAME_SITE?.trim().toLowerCase();
+	if (value === 'lax' || value === 'strict') return value;
+
+	if (value) {
+		console.warn('AUTH_SESSION_COOKIE_SAME_SITE must be lax or strict; defaulting to lax');
+	}
+
+	// Lax (not strict): OIDC return from Zitadel is a top-level nav; lax is enough
+	// and avoids edge cases with local multi-origin setups.
+	return 'lax';
+}
+
+/**
+ * Local e2e is plain http://127.0.0.1 — Secure cookies are dropped by the browser
+ * and login/session silently fails (every protected page looks "broken").
+ * Only enable Secure when AUTH_URL / AUTH_TRUST_SECURE explicitly says https.
+ */
+function useSecureCookies(): boolean {
+	const forced = env.AUTH_USE_SECURE_COOKIES?.trim().toLowerCase();
+	if (forced === '1' || forced === 'true' || forced === 'yes') return true;
+	if (forced === '0' || forced === 'false' || forced === 'no') return false;
+
+	const authUrl = envFirst(['AUTH_URL', 'ORIGIN', 'PUBLIC_ORIGIN']);
+	if (authUrl.startsWith('https://')) return true;
+	// Default: local fixture is HTTP
+	return false;
+}
+
+function providerName() {
+	if (env.AUTH_PROVIDER?.trim()) return env.AUTH_PROVIDER.trim();
+	if (env.ZITADEL_ISSUER?.trim()) return 'Zitadel';
+	return 'OIDC';
+}
+
+function decodeJwtPayload(jwt: unknown): Record<string, unknown> | null {
+	if (typeof jwt !== 'string') return null;
+
+	const payload = jwt.split('.')[1];
+	if (!payload) return null;
+
+	try {
+		const normalized = payload.replace(/-/g, '+').replace(/_/g, '/');
+		const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, '=');
+		const binary = globalThis.atob(padded);
+		const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+		return JSON.parse(new TextDecoder().decode(bytes)) as Record<string, unknown>;
+	} catch {
+		return null;
+	}
+}
+
+function claimString(claims: Record<string, unknown>, key: string) {
+	const value = claims[key];
+	return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function claimBool(claims: Record<string, unknown>, key: string) {
+	const value = claims[key];
+	return typeof value === 'boolean' ? value : undefined;
+}
+
+function claimValue(claims: Record<string, unknown>, path: string): unknown {
+	if (path in claims) return claims[path];
+
+	return path.split('.').reduce<unknown>((current, segment) => {
+		if (current && typeof current === 'object' && segment in current) {
+			return (current as Record<string, unknown>)[segment];
+		}
+
+		return undefined;
+	}, claims);
+}
+
+function extractGroups(claims: Record<string, unknown>, groupClaims: string[]) {
+	const groups = new Set<string>();
+
+	for (const claim of groupClaims) {
+		const value = claimValue(claims, claim);
+
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				if (typeof item === 'string' && item.trim()) groups.add(item);
+			}
+		} else if (typeof value === 'string' && value.trim()) {
+			groups.add(value);
+		} else if (value && typeof value === 'object') {
+			// Zitadel project roles: { "admin": { "<projectId>": "..." }, ... }
+			for (const key of Object.keys(value)) groups.add(key);
+		}
+	}
+
+	return [...groups].sort();
+}
+
+function groupClaimPaths() {
+	const paths = envCsv('OIDC_GROUP_CLAIMS', DEFAULT_GROUP_CLAIMS);
+	const aud = oidcAudience() || envFirst(['OIDC_AUDIENCE', 'ZITADEL_PROJECT_ID']);
+	if (aud) {
+		const projectClaim = `urn:zitadel:iam:org:project:${aud}:roles`;
+		const projectIdClaim = `urn:zitadel:iam:org:project:id:${aud}:roles`;
+		if (!paths.includes(projectClaim)) paths.push(projectClaim);
+		if (!paths.includes(projectIdClaim)) paths.push(projectIdClaim);
+	}
+	return paths;
+}
+
+/**
+ * Roles often live on the **access** token (Zitadel `urn:zitadel:iam:org:project:roles`)
+ * while the id_token only has profile claims. Merge both payloads so admin grants
+ * are not dropped when an id_token is present.
+ */
+function groupsFromTokens(token: TokenRecord): string[] {
+	const paths = groupClaimPaths();
+	const groups = new Set<string>();
+
+	for (const jwt of [token.idToken, token.accessToken, token.id_token, token.access_token]) {
+		const claims = decodeJwtPayload(jwt);
+		if (!claims) continue;
+		for (const g of extractGroups(claims, paths)) groups.add(g);
+	}
+
+	// Auth.js may have stored profile groups on the JWT cookie (first sign-in).
+	const stored = token.groups;
+	if (Array.isArray(stored)) {
+		for (const item of stored) {
+			if (typeof item === 'string' && item.trim()) groups.add(item);
+		}
+	}
+
+	return [...groups].sort();
+}
+
+function userClaims(token: TokenRecord) {
+	// Profile fields: prefer id_token, fall back to access token.
+	return decodeJwtPayload(token.idToken) ?? decodeJwtPayload(token.accessToken) ?? {};
+}
+
+export const { handle, signIn, signOut } = SvelteKitAuth({
+	providers: [
+		{
+			id: 'oidc',
+			name: providerName(),
+			type: 'oidc',
+			issuer: oidcIssuer(),
+			clientId: oidcClientId(),
+			clientSecret: oidcClientSecret(),
+			// Scope is resolved when this module loads (UI process must have OIDC_* env
+			// from `make run` / sourced e2e-ui.env). oidcScopes() always merges Zitadel
+			// project audience + roles scopes so bare OIDC_SCOPES=openid still works.
+			authorization: {
+				params: {
+					scope: oidcScopes()
+				}
+			},
+			checks: ['pkce', 'state'],
+			profile(profile: Record<string, unknown>) {
+				const groupClaims = envCsv('OIDC_GROUP_CLAIMS', DEFAULT_GROUP_CLAIMS);
+				const name =
+					claimString(profile, 'name') ??
+					claimString(profile, 'preferred_username') ??
+					claimString(profile, 'email');
+
+				return {
+					id: claimString(profile, 'sub') ?? '',
+					name,
+					email: claimString(profile, 'email'),
+					image: claimString(profile, 'picture'),
+					groups: extractGroups(profile, groupClaims),
+					username: claimString(profile, 'preferred_username'),
+					emailVerified: claimBool(profile, 'email_verified')
+				};
+			}
+		} as any
+	],
+	callbacks: {
+		async jwt({ token, account, user, profile }) {
+			if (account) {
+				token.accessToken = account.access_token;
+				token.refreshToken = account.refresh_token;
+				token.idToken = account.id_token;
+				token.expiresAt =
+					(account.expires_at as number | undefined) ??
+					Math.floor(Date.now() / 1000) + ((account.expires_in as number | undefined) ?? 3600);
+			}
+
+			// Profile/userinfo may carry groups even when tokens are still empty.
+			const profileGroups = extractGroups(
+				(profile as Record<string, unknown> | undefined) ?? {},
+				groupClaimPaths()
+			);
+			if (profileGroups.length) token.groups = profileGroups;
+			if (user && Array.isArray(user.groups) && user.groups.length) {
+				token.groups = user.groups;
+			}
+
+			const expiresAt = typeof token.expiresAt === 'number' ? token.expiresAt : 0;
+			const stillFresh =
+				expiresAt && Date.now() < (expiresAt - ACCESS_TOKEN_REFRESH_SKEW_SECONDS) * 1000;
+
+			if (!stillFresh && token.refreshToken) {
+				try {
+					const refreshed = (await refreshAccessToken(token as TokenRecord)) as TokenRecord;
+					// Re-extract roles from the new access token.
+					const groups = groupsFromTokens(refreshed);
+					if (groups.length) refreshed.groups = groups;
+					return refreshed;
+				} catch (error) {
+					console.error('Token refresh failed:', error);
+					token.error = 'RefreshAccessTokenError';
+					return token;
+				}
+			}
+
+			// Always refresh groups from current tokens (access token has Zitadel roles).
+			const groups = groupsFromTokens(token as TokenRecord);
+			if (groups.length) token.groups = groups;
+
+			return token;
+		},
+		async session({ session, token }) {
+			session.accessToken = token.accessToken as string | undefined;
+			session.idToken = token.idToken as string | undefined;
+			session.expiresAt = token.expiresAt as number | undefined;
+			session.refreshAfter = Math.max(
+				0,
+				((token.expiresAt as number | undefined) ?? 0) - ACCESS_TOKEN_REFRESH_SKEW_SECONDS
+			);
+			session.hasAccessToken = typeof token.accessToken === 'string' && token.accessToken.length > 0;
+			session.hasRefreshToken =
+				typeof token.refreshToken === 'string' && token.refreshToken.length > 0;
+			session.hasIdToken = typeof token.idToken === 'string' && token.idToken.length > 0;
+			session.error = token.error as string | undefined;
+			session.user = {
+				...session.user,
+				id: token.sub as string
+			};
+
+			const claims = userClaims(token as TokenRecord);
+			// Merge id + access token role claims (Zitadel puts project roles on access).
+			session.user.groups = groupsFromTokens(token as TokenRecord);
+
+			const username = claimString(claims, 'preferred_username');
+			if (username) session.user.username = username;
+
+			const emailVerified = claimBool(claims, 'email_verified');
+			if (emailVerified !== undefined) {
+				(session.user as unknown as { emailVerified?: boolean }).emailVerified = emailVerified;
+			}
+
+			return session;
+		},
+		async redirect({ url, baseUrl }) {
+			if (url.startsWith('/')) return `${baseUrl}${url}`;
+			if (new URL(url).origin === baseUrl) return url;
+			return baseUrl;
+		}
+	},
+	pages: {
+		signIn: '/',
+		error: '/'
+	},
+	// HARD false for this local fixture. Auth.js defaults secure from request
+	// protocol / AUTH_URL; on plain http://127.0.0.1 Secure cookies are dropped
+	// by the browser and every protected page looks broken (session never sticks).
+	// Production HTTPS deploys must set AUTH_USE_SECURE_COOKIES=true (or AUTH_URL=https…).
+	useSecureCookies: useSecureCookies(),
+	cookies: {
+		sessionToken: {
+			name: 'authjs.session-token',
+			options: {
+				httpOnly: true,
+				sameSite: authSessionCookieSameSite(),
+				path: '/',
+				secure: false
+			}
+		},
+		callbackUrl: {
+			name: 'authjs.callback-url',
+			options: {
+				httpOnly: true,
+				sameSite: authSessionCookieSameSite(),
+				path: '/',
+				secure: false
+			}
+		},
+		csrfToken: {
+			name: 'authjs.csrf-token',
+			options: {
+				httpOnly: true,
+				sameSite: authSessionCookieSameSite(),
+				path: '/',
+				secure: false
+			}
+		},
+		pkceCodeVerifier: {
+			name: 'authjs.pkce.code_verifier',
+			options: {
+				httpOnly: true,
+				sameSite: authSessionCookieSameSite(),
+				path: '/',
+				secure: false,
+				maxAge: 60 * 15
+			}
+		},
+		state: {
+			name: 'authjs.state',
+			options: {
+				httpOnly: true,
+				sameSite: authSessionCookieSameSite(),
+				path: '/',
+				secure: false,
+				maxAge: 60 * 15
+			}
+		}
+	},
+	jwt: {
+		maxAge: 60 * 60
+	},
+	trustHost: true
+});
+
+async function refreshAccessToken(token: TokenRecord) {
+	const tokenEndpoint = await oidcTokenEndpoint();
+	const tokenAuthMethod = oidcTokenAuthMethod();
+	const body = new URLSearchParams({
+		grant_type: 'refresh_token',
+		refresh_token: String(token.refreshToken)
+	});
+	const headers: Record<string, string> = {
+		'Content-Type': 'application/x-www-form-urlencoded'
+	};
+
+	if (tokenAuthMethod === TOKEN_AUTH_BASIC) {
+		headers.Authorization = `Basic ${btoa(`${oidcClientId()}:${oidcClientSecret()}`)}`;
+	} else if (tokenAuthMethod === TOKEN_AUTH_POST) {
+		body.set('client_id', oidcClientId());
+		body.set('client_secret', oidcClientSecret());
+	} else if (tokenAuthMethod === TOKEN_AUTH_NONE) {
+		body.set('client_id', oidcClientId());
+	} else {
+		throw new Error('OIDC_TOKEN_AUTH_METHOD must be client_secret_basic, client_secret_post, or none');
+	}
+
+	const response = await fetch(tokenEndpoint, {
+		method: 'POST',
+		headers,
+		body
+	});
+
+	const refreshedTokens = (await response.json()) as {
+		access_token?: string;
+		refresh_token?: string;
+		id_token?: string;
+		expires_in?: number;
+	};
+	if (!response.ok) throw refreshedTokens;
+
+	const expiresIn = typeof refreshedTokens.expires_in === 'number' ? refreshedTokens.expires_in : 3600;
+
+	return {
+		...token,
+		accessToken: refreshedTokens.access_token,
+		refreshToken: refreshedTokens.refresh_token ?? token.refreshToken,
+		idToken: refreshedTokens.id_token ?? token.idToken,
+		expiresAt: Math.floor(Date.now() / 1000) + expiresIn,
+		error: undefined
+	};
+}
+
+async function oidcTokenEndpoint() {
+	const override = envFirst(['OIDC_TOKEN_ENDPOINT']);
+	if (override) return override;
+
+	const issuer = oidcIssuer();
+	const response = await fetch(`${issuer}/.well-known/openid-configuration`);
+	if (!response.ok) {
+		throw new Error(`OIDC discovery failed with ${response.status}`);
+	}
+
+	const metadata = (await response.json()) as { token_endpoint?: string };
+	if (!metadata.token_endpoint) {
+		throw new Error('OIDC discovery did not include token_endpoint');
+	}
+
+	return metadata.token_endpoint;
+}
+
+export { engineRoleFromGroups } from './lib/roles';
diff --git a/tests/e2e-ui/ui/src/custom-media.css b/tests/e2e-ui/ui/src/custom-media.css
new file mode 100644
index 00000000..12e86df4
--- /dev/null
+++ b/tests/e2e-ui/ui/src/custom-media.css
@@ -0,0 +1,10 @@
+/* Custom media queries - injected globally via postcss-global-data */
+@custom-media --mobile (width < 480px);
+@custom-media --mobile-up (width >= 480px);
+@custom-media --tablet (width < 768px);
+@custom-media --tablet-up (width >= 768px);
+@custom-media --desktop (width < 1024px);
+@custom-media --desktop-up (width >= 1024px);
+@custom-media --wide (width < 1280px);
+@custom-media --wide-up (width >= 1280px);
+@custom-media --ultrawide (width >= 1600px);
diff --git a/tests/e2e-ui/ui/src/hooks.server.ts b/tests/e2e-ui/ui/src/hooks.server.ts
new file mode 100644
index 00000000..85660b3d
--- /dev/null
+++ b/tests/e2e-ui/ui/src/hooks.server.ts
@@ -0,0 +1,31 @@
+import { redirect, type Handle, type RequestEvent } from '@sveltejs/kit';
+import { handle as authHandle } from './auth';
+import { sequence } from '@sveltejs/kit/hooks';
+
+async function authorizationHandle({ event, resolve }: { event: RequestEvent; resolve: (event: RequestEvent) => Response | Promise<Response>; }) {
+  // Protect admin (website) + fixture app routes
+  const path = event.url.pathname;
+  const protectedPrefix =
+    path.startsWith('/admin') ||
+    path === '/todos' ||
+    path.startsWith('/todos/') ||
+    path === '/blob' ||
+    path.startsWith('/blob/') ||
+    path === '/chat' ||
+    path.startsWith('/chat/') ||
+    path === '/session' ||
+    path.startsWith('/session/');
+
+  if (protectedPrefix) {
+    const session = await event.locals.auth();
+    if (!session?.user) {
+      const callbackUrl = encodeURIComponent(event.url.pathname + event.url.search);
+      // Custom Login V2 pages at /login (not Zitadel-hosted UI)
+      throw redirect(303, `/login?callbackUrl=${callbackUrl}`);
+    }
+  }
+
+  return resolve(event);
+}
+
+export const handle: Handle = sequence(authHandle, authorizationHandle);
diff --git a/tests/e2e-ui/ui/src/lib/clean-env.ts b/tests/e2e-ui/ui/src/lib/clean-env.ts
new file mode 100644
index 00000000..db173a59
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/clean-env.ts
@@ -0,0 +1,18 @@
+/**
+ * Peel accidental outer quotes from env values (Make-include / double-wrap pollution).
+ * Shared by Auth.js config and server GraphQL base URL resolution.
+ */
+export function cleanEnvValue(raw: string | undefined | null): string {
+	let s = (raw ?? '').trim();
+	for (let i = 0; i < 2; i++) {
+		if (
+			s.length >= 2 &&
+			((s.startsWith("'") && s.endsWith("'")) || (s.startsWith('"') && s.endsWith('"')))
+		) {
+			s = s.slice(1, -1).trim();
+		} else {
+			break;
+		}
+	}
+	return s;
+}
diff --git a/tests/e2e-ui/ui/src/lib/components/dashboard/CodeBlock.svelte b/tests/e2e-ui/ui/src/lib/components/dashboard/CodeBlock.svelte
new file mode 100644
index 00000000..055b7ea0
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/dashboard/CodeBlock.svelte
@@ -0,0 +1,180 @@
+<script lang="ts">
+	interface Props {
+		/** Code content */
+		code: string;
+		/** Optional title */
+		title?: string;
+		/** Make it collapsible */
+		collapsible?: boolean;
+		/** Max height before scroll */
+		maxHeight?: string;
+	}
+
+	let { code, title, collapsible = false, maxHeight = '300px' }: Props = $props();
+
+	let copied = $state(false);
+
+	async function copyCode() {
+		try {
+			await navigator.clipboard.writeText(code);
+			copied = true;
+			setTimeout(() => copied = false, 2000);
+		} catch (err) {
+			console.error('Failed to copy:', err);
+		}
+	}
+</script>
+
+{#if collapsible}
+	<details class="code-block collapsible">
+		<summary class="code-header">
+			<span class="code-title">{title || 'Code'}</span>
+			<svg class="chevron" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+				<polyline points="6 9 12 15 18 9"></polyline>
+			</svg>
+		</summary>
+		<div class="code-content">
+			<button class="copy-btn" onclick={copyCode} class:copied>
+				{#if copied}
+					<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+						<polyline points="20 6 9 17 4 12"></polyline>
+					</svg>
+					<span>Copied</span>
+				{:else}
+					<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+						<rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+						<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+					</svg>
+					<span>Copy</span>
+				{/if}
+			</button>
+			<pre style="max-height: {maxHeight}">{code}</pre>
+		</div>
+	</details>
+{:else}
+	<div class="code-block">
+		{#if title}
+			<div class="code-header static">
+				<span class="code-title">{title}</span>
+				<button class="copy-btn" onclick={copyCode} class:copied>
+					{#if copied}
+						<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+							<polyline points="20 6 9 17 4 12"></polyline>
+						</svg>
+						<span>Copied</span>
+					{:else}
+						<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+							<rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+							<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+						</svg>
+						<span>Copy</span>
+					{/if}
+				</button>
+			</div>
+		{/if}
+		<pre style="max-height: {maxHeight}">{code}</pre>
+	</div>
+{/if}
+
+<style>
+.code-block {
+	border: 1px solid var(--hops-border);
+	border-radius: 8px;
+	overflow: hidden;
+	background: var(--hops-bg-white);
+}
+
+.code-header {
+	display: flex;
+	justify-content: space-between;
+	align-items: center;
+	padding: 0.75rem 1rem;
+	background: var(--hops-bg-light);
+	border-bottom: 1px solid var(--hops-border);
+}
+
+.code-header.static {
+	cursor: default;
+}
+
+.collapsible > .code-header {
+	cursor: pointer;
+	user-select: none;
+}
+
+.collapsible > .code-header:hover {
+	background: var(--hops-bg-cream);
+}
+
+.code-title {
+	font-family: var(--font-display);
+	font-size: 0.8rem;
+	font-weight: 600;
+	color: var(--hops-text-secondary);
+	text-transform: uppercase;
+	letter-spacing: 0.04em;
+}
+
+.chevron {
+	color: var(--hops-text-muted);
+	transition: transform 0.2s ease;
+}
+
+.collapsible[open] .chevron {
+	transform: rotate(180deg);
+}
+
+.collapsible::-webkit-details-marker {
+	display: none;
+}
+
+.code-content {
+	position: relative;
+}
+
+.copy-btn {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.35rem;
+	padding: 0.35rem 0.6rem;
+	background: var(--hops-bg-white);
+	border: 1px solid var(--hops-border);
+	border-radius: 6px;
+	cursor: pointer;
+	color: var(--hops-text-muted);
+	font-size: 0.7rem;
+	font-weight: 500;
+	transition: all 0.15s ease;
+}
+
+.collapsible .copy-btn {
+	position: absolute;
+	top: 0.75rem;
+	right: 0.75rem;
+	z-index: 1;
+}
+
+.copy-btn:hover {
+	border-color: var(--hops-navy);
+	color: var(--hops-navy);
+}
+
+.copy-btn.copied {
+	background: var(--hops-success);
+	border-color: var(--hops-success);
+	color: white;
+}
+
+pre {
+	font-family: var(--font-mono);
+	font-size: 0.7rem;
+	color: #a0aec0;
+	background: var(--hops-navy-deep);
+	padding: 1rem;
+	margin: 0;
+	overflow: auto;
+	white-space: pre-wrap;
+	word-break: break-word;
+	line-height: 1.6;
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/dashboard/DashboardCard.svelte b/tests/e2e-ui/ui/src/lib/components/dashboard/DashboardCard.svelte
new file mode 100644
index 00000000..d31fb374
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/dashboard/DashboardCard.svelte
@@ -0,0 +1,52 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Card title */
+		title?: string;
+		/** Card content */
+		children: Snippet;
+	}
+
+	let { title, children }: Props = $props();
+</script>
+
+<div class="dashboard-card">
+	{#if title}
+		<header class="card-header">
+			<h3>{title}</h3>
+		</header>
+	{/if}
+	<div class="card-body">
+		{@render children()}
+	</div>
+</div>
+
+<style>
+.dashboard-card {
+	background: var(--hops-bg-white);
+	border: 1px solid var(--hops-border);
+	border-radius: 12px;
+	overflow: hidden;
+}
+
+.card-header {
+	padding: 0.875rem 1.25rem;
+	border-bottom: 1px solid var(--hops-border);
+	background: var(--hops-bg-light);
+}
+
+.card-header h3 {
+	margin: 0;
+	font-family: var(--font-display);
+	font-size: 0.8rem;
+	font-weight: 600;
+	color: var(--hops-text-secondary);
+	text-transform: uppercase;
+	letter-spacing: 0.06em;
+}
+
+.card-body {
+	padding: 0;
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/dashboard/DataRow.svelte b/tests/e2e-ui/ui/src/lib/components/dashboard/DataRow.svelte
new file mode 100644
index 00000000..4d36c872
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/dashboard/DataRow.svelte
@@ -0,0 +1,63 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Row label */
+		label: string;
+		/** Use monospace font for value */
+		mono?: boolean;
+		/** Row value - can be string or snippet for custom content */
+		value?: string;
+		/** Custom content slot */
+		children?: Snippet;
+	}
+
+	let { label, mono = false, value, children }: Props = $props();
+</script>
+
+<div class="data-row">
+	<dt class="label">{label}</dt>
+	<dd class="value" class:mono>
+		{#if children}
+			{@render children()}
+		{:else}
+			{value || '—'}
+		{/if}
+	</dd>
+</div>
+
+<style>
+.data-row {
+	display: flex;
+	justify-content: space-between;
+	align-items: center;
+	padding: 1rem 1.25rem;
+	border-bottom: 1px solid var(--hops-border);
+	gap: 1rem;
+}
+
+.data-row:last-child {
+	border-bottom: none;
+}
+
+.label {
+	font-size: 0.875rem;
+	color: var(--hops-text-muted);
+	flex-shrink: 0;
+}
+
+.value {
+	font-size: 0.875rem;
+	font-weight: 500;
+	color: var(--hops-text-primary);
+	text-align: right;
+	word-break: break-word;
+	margin: 0;
+}
+
+.value.mono {
+	font-family: var(--font-mono);
+	font-size: 0.8rem;
+	font-weight: 400;
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/dashboard/GroupBadge.svelte b/tests/e2e-ui/ui/src/lib/components/dashboard/GroupBadge.svelte
new file mode 100644
index 00000000..ccf8a912
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/dashboard/GroupBadge.svelte
@@ -0,0 +1,23 @@
+<script lang="ts">
+	interface Props {
+		/** Group name */
+		name: string;
+	}
+
+	let { name }: Props = $props();
+</script>
+
+<span class="group-badge">{name}</span>
+
+<style>
+.group-badge {
+	display: inline-block;
+	padding: 0.25rem 0.6rem;
+	background: rgba(26, 39, 68, 0.08);
+	border-radius: 5px;
+	font-size: 0.7rem;
+	font-weight: 600;
+	color: var(--hops-navy);
+	text-transform: lowercase;
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/dashboard/StatusBadge.svelte b/tests/e2e-ui/ui/src/lib/components/dashboard/StatusBadge.svelte
new file mode 100644
index 00000000..8bc27d0f
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/dashboard/StatusBadge.svelte
@@ -0,0 +1,64 @@
+<script lang="ts">
+	interface Props {
+		/** Status variant */
+		status: 'success' | 'warning' | 'error' | 'neutral';
+		/** Badge text */
+		label: string;
+	}
+
+	let { status, label }: Props = $props();
+</script>
+
+<span class="status-badge {status}">
+	{#if status === 'success'}
+		<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round">
+			<polyline points="20 6 9 17 4 12"></polyline>
+		</svg>
+	{:else if status === 'warning'}
+		<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+			<circle cx="12" cy="12" r="10"></circle>
+			<line x1="12" y1="8" x2="12" y2="12"></line>
+			<line x1="12" y1="16" x2="12.01" y2="16"></line>
+		</svg>
+	{:else if status === 'error'}
+		<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round">
+			<line x1="18" y1="6" x2="6" y2="18"></line>
+			<line x1="6" y1="6" x2="18" y2="18"></line>
+		</svg>
+	{/if}
+	<span>{label}</span>
+</span>
+
+<style>
+.status-badge {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.35rem;
+	padding: 0.3rem 0.65rem;
+	border-radius: 6px;
+	font-size: 0.7rem;
+	font-weight: 600;
+	text-transform: uppercase;
+	letter-spacing: 0.03em;
+}
+
+.success {
+	background: rgba(56, 161, 105, 0.12);
+	color: var(--hops-success);
+}
+
+.warning {
+	background: rgba(221, 107, 32, 0.12);
+	color: var(--hops-warning);
+}
+
+.error {
+	background: rgba(229, 62, 62, 0.12);
+	color: var(--hops-danger);
+}
+
+.neutral {
+	background: var(--hops-bg-light);
+	color: var(--hops-text-muted);
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/dashboard/TokenBlock.svelte b/tests/e2e-ui/ui/src/lib/components/dashboard/TokenBlock.svelte
new file mode 100644
index 00000000..3caa954b
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/dashboard/TokenBlock.svelte
@@ -0,0 +1,129 @@
+<script lang="ts">
+	interface Props {
+		/** Token label */
+		label: string;
+		/** Token type hint */
+		hint?: string;
+		/** Token value */
+		value: string;
+	}
+
+	let { label, hint, value }: Props = $props();
+
+	let copied = $state(false);
+
+	async function copyToken() {
+		try {
+			await navigator.clipboard.writeText(value);
+			copied = true;
+			setTimeout(() => copied = false, 2000);
+		} catch (err) {
+			console.error('Failed to copy:', err);
+		}
+	}
+</script>
+
+<div class="token-block">
+	<div class="token-header">
+		<span class="token-label">{label}</span>
+		<div class="token-actions">
+			{#if hint}
+				<span class="token-hint">{hint}</span>
+			{/if}
+			<button class="copy-btn" onclick={copyToken} class:copied>
+				{#if copied}
+					<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+						<polyline points="20 6 9 17 4 12"></polyline>
+					</svg>
+				{:else}
+					<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+						<rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+						<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+					</svg>
+				{/if}
+			</button>
+		</div>
+	</div>
+	<pre class="token-value">{value}</pre>
+</div>
+
+<style>
+.token-block {
+	border: 1px solid var(--hops-border);
+	border-radius: 8px;
+	overflow: hidden;
+}
+
+.token-header {
+	display: flex;
+	justify-content: space-between;
+	align-items: center;
+	padding: 0.6rem 0.875rem;
+	background: var(--hops-bg-light);
+	border-bottom: 1px solid var(--hops-border);
+}
+
+.token-label {
+	font-size: 0.75rem;
+	font-weight: 600;
+	color: var(--hops-text-secondary);
+	text-transform: uppercase;
+	letter-spacing: 0.04em;
+}
+
+.token-actions {
+	display: flex;
+	align-items: center;
+	gap: 0.5rem;
+}
+
+.token-hint {
+	font-size: 0.65rem;
+	font-family: var(--font-mono);
+	color: var(--hops-text-muted);
+	background: var(--hops-bg-white);
+	padding: 0.2rem 0.4rem;
+	border-radius: 4px;
+	border: 1px solid var(--hops-border);
+}
+
+.copy-btn {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	width: 28px;
+	height: 28px;
+	background: var(--hops-bg-white);
+	border: 1px solid var(--hops-border);
+	border-radius: 6px;
+	cursor: pointer;
+	color: var(--hops-text-muted);
+	transition: all 0.15s ease;
+}
+
+.copy-btn:hover {
+	background: var(--hops-bg-white);
+	border-color: var(--hops-navy);
+	color: var(--hops-navy);
+}
+
+.copy-btn.copied {
+	background: var(--hops-success);
+	border-color: var(--hops-success);
+	color: white;
+}
+
+.token-value {
+	font-family: var(--font-mono);
+	font-size: 0.7rem;
+	color: #a0aec0;
+	background: var(--hops-navy-deep);
+	padding: 0.875rem;
+	margin: 0;
+	word-break: break-all;
+	white-space: pre-wrap;
+	line-height: 1.6;
+	max-height: 88px;
+	overflow-y: auto;
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/dashboard/UserAvatar.svelte b/tests/e2e-ui/ui/src/lib/components/dashboard/UserAvatar.svelte
new file mode 100644
index 00000000..e4d2bb7c
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/dashboard/UserAvatar.svelte
@@ -0,0 +1,89 @@
+<script lang="ts">
+	interface Props {
+		/** User's name for initials */
+		name?: string | null;
+		/** User's email as fallback */
+		email?: string | null;
+		/** Avatar image URL */
+		image?: string | null;
+		/** Size variant */
+		size?: 'sm' | 'md' | 'lg';
+	}
+
+	let { name, email, image, size = 'md' }: Props = $props();
+
+	const initials = $derived(
+		name
+			? name.split(' ').map(n => n[0]).join('').toUpperCase().slice(0, 2)
+			: email
+				? email[0].toUpperCase()
+				: null
+	);
+</script>
+
+<div class="avatar size-{size}">
+	{#if image}
+		<img src={image} alt={name || 'User avatar'} />
+	{:else if initials}
+		<span class="initials">{initials}</span>
+	{:else}
+		<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+			<path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2"></path>
+			<circle cx="12" cy="7" r="4"></circle>
+		</svg>
+	{/if}
+</div>
+
+<style>
+.avatar {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	background: linear-gradient(135deg, var(--hops-navy) 0%, var(--hops-navy-light) 100%);
+	border-radius: 12px;
+	flex-shrink: 0;
+	overflow: hidden;
+}
+
+.size-sm {
+	width: 40px;
+	height: 40px;
+	border-radius: 10px;
+}
+
+.size-md {
+	width: 56px;
+	height: 56px;
+}
+
+.size-lg {
+	width: 72px;
+	height: 72px;
+	border-radius: 16px;
+}
+
+.avatar img {
+	width: 100%;
+	height: 100%;
+	object-fit: cover;
+}
+
+.initials {
+	font-family: var(--font-display);
+	font-weight: 700;
+	color: var(--hops-text-inverse);
+	letter-spacing: 0.02em;
+}
+
+.size-sm .initials { font-size: 0.875rem; }
+.size-md .initials { font-size: 1.125rem; }
+.size-lg .initials { font-size: 1.5rem; }
+
+.icon {
+	color: rgba(255, 255, 255, 0.7);
+}
+
+.size-sm .icon { width: 20px; height: 20px; }
+.size-md .icon { width: 28px; height: 28px; }
+.size-lg .icon { width: 36px; height: 36px; }
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/dashboard/index.ts b/tests/e2e-ui/ui/src/lib/components/dashboard/index.ts
new file mode 100644
index 00000000..5914c101
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/dashboard/index.ts
@@ -0,0 +1,7 @@
+export { default as CodeBlock } from './CodeBlock.svelte';
+export { default as DashboardCard } from './DashboardCard.svelte';
+export { default as DataRow } from './DataRow.svelte';
+export { default as GroupBadge } from './GroupBadge.svelte';
+export { default as StatusBadge } from './StatusBadge.svelte';
+export { default as TokenBlock } from './TokenBlock.svelte';
+export { default as UserAvatar } from './UserAvatar.svelte';
diff --git a/tests/e2e-ui/ui/src/lib/components/product/AppPage.svelte b/tests/e2e-ui/ui/src/lib/components/product/AppPage.svelte
new file mode 100644
index 00000000..ab454ab8
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/product/AppPage.svelte
@@ -0,0 +1,44 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Constrain width (default product measure) */
+		width?: 'default' | 'narrow' | 'wide';
+		children: Snippet;
+	}
+
+	let { width = 'default', children }: Props = $props();
+</script>
+
+<section class="app-page width-{width}">
+	{@render children()}
+</section>
+
+<style>
+	.app-page {
+		--surface: var(--wf-bg-elevated, #fff);
+		--surface-edge: var(--wf-line, #e2e0d9);
+		--ink: var(--wf-ink, #1c1c1a);
+		--ink-soft: var(--wf-ink-soft, #5c5c56);
+		--accent: var(--wf-accent, #3d5a80);
+		--shadow: var(--df-shadow-sm, 0 1px 2px rgba(28, 28, 26, 0.04));
+
+		position: relative;
+		margin: 0 auto;
+		padding: 6.5rem 1.25rem 4rem;
+		font-family: var(--wf-sans, var(--font-body, system-ui, sans-serif));
+		color: var(--ink);
+	}
+
+	.width-default {
+		max-width: 52rem;
+	}
+
+	.width-narrow {
+		max-width: 40rem;
+	}
+
+	.width-wide {
+		max-width: 68rem;
+	}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/product/InlineAlert.svelte b/tests/e2e-ui/ui/src/lib/components/product/InlineAlert.svelte
new file mode 100644
index 00000000..57288829
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/product/InlineAlert.svelte
@@ -0,0 +1,62 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Short uppercase label (e.g. Mutation, SSR GraphQL) */
+		label?: string;
+		/** Visual tone */
+		tone?: 'danger' | 'info';
+		children: Snippet;
+	}
+
+	let { label, tone = 'danger', children }: Props = $props();
+</script>
+
+<div class="inline-alert tone-{tone}" role="alert">
+	{#if label}
+		<span class="label">{label}</span>
+	{/if}
+	<div class="body">
+		{@render children()}
+	</div>
+</div>
+
+<style>
+	.inline-alert {
+		display: flex;
+		gap: 0.75rem;
+		align-items: flex-start;
+		padding: 0.85rem 1rem;
+		margin-bottom: 1rem;
+		border-radius: var(--wf-radius, 6px);
+		font-size: 0.92rem;
+		line-height: 1.45;
+	}
+
+	.tone-danger {
+		background: rgba(179, 58, 58, 0.08);
+		border: 1px solid rgba(179, 58, 58, 0.22);
+		color: var(--wf-danger, #b33a3a);
+	}
+
+	.tone-info {
+		background: var(--wf-accent-soft, rgba(61, 90, 128, 0.08));
+		border: 1px solid var(--wf-line, #e2e0d9);
+		color: var(--wf-ink-soft, #5c5c56);
+	}
+
+	.label {
+		font-weight: 700;
+		font-size: 0.7rem;
+		letter-spacing: 0.08em;
+		text-transform: uppercase;
+		opacity: 0.8;
+		padding-top: 0.15rem;
+		flex-shrink: 0;
+	}
+
+	.body {
+		min-width: 0;
+		flex: 1;
+	}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/product/PageHeader.svelte b/tests/e2e-ui/ui/src/lib/components/product/PageHeader.svelte
new file mode 100644
index 00000000..872d3d9c
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/product/PageHeader.svelte
@@ -0,0 +1,108 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Small uppercase kicker above the title */
+		kicker?: string;
+		/** Page title */
+		title: string;
+		/** Optional status / meta slot (e.g. live indicator) */
+		meta?: Snippet;
+		/** Lede / description */
+		children?: Snippet;
+	}
+
+	let { kicker, title, meta, children }: Props = $props();
+</script>
+
+<header class="page-header">
+	<div class="title-row">
+		<div class="titles">
+			{#if kicker}
+				<div class="kicker">
+					<span class="dot" aria-hidden="true"></span>
+					{kicker}
+				</div>
+			{/if}
+			<h1 class="title">{title}</h1>
+		</div>
+		{#if meta}
+			<div class="meta">
+				{@render meta()}
+			</div>
+		{/if}
+	</div>
+	{#if children}
+		<p class="lede">
+			{@render children()}
+		</p>
+	{/if}
+</header>
+
+<style>
+	.page-header {
+		margin-bottom: 1.75rem;
+	}
+
+	.title-row {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: flex-start;
+		justify-content: space-between;
+		gap: 1rem;
+	}
+
+	.kicker {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.45rem;
+		font-size: 0.72rem;
+		font-weight: 600;
+		letter-spacing: 0.1em;
+		text-transform: uppercase;
+		color: var(--wf-ink-soft, #5c5c56);
+		margin-bottom: 0.65rem;
+	}
+
+	.dot {
+		width: 0.4rem;
+		height: 0.4rem;
+		border-radius: 50%;
+		background: var(--wf-accent, #3d5a80);
+	}
+
+	.title {
+		font-family: var(--wf-serif, Georgia, serif);
+		font-size: clamp(1.65rem, 4vw, 2.15rem);
+		font-weight: 500;
+		letter-spacing: -0.02em;
+		line-height: 1.1;
+		margin: 0 0 0.65rem;
+		color: var(--wf-ink, #1c1c1a);
+	}
+
+	.lede {
+		margin: 0;
+		max-width: 36rem;
+		font-size: 1rem;
+		line-height: 1.55;
+		color: var(--wf-ink-soft, #5c5c56);
+	}
+
+	.lede :global(code) {
+		font-family: var(--wf-mono, var(--font-mono, ui-monospace, monospace));
+		font-size: 0.88em;
+		padding: 0.1em 0.35em;
+		border-radius: 4px;
+		background: var(--wf-accent-soft, rgba(61, 90, 128, 0.08));
+	}
+
+	.lede :global(strong) {
+		color: var(--wf-ink, #1c1c1a);
+		font-weight: 600;
+	}
+
+	.meta {
+		flex-shrink: 0;
+	}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/product/Panel.svelte b/tests/e2e-ui/ui/src/lib/components/product/Panel.svelte
new file mode 100644
index 00000000..1e14db84
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/product/Panel.svelte
@@ -0,0 +1,70 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Optional panel title */
+		title?: string;
+		/** Count badge next to title */
+		count?: number | string;
+		/** Muted surface */
+		muted?: boolean;
+		children: Snippet;
+	}
+
+	let { title, count, muted = false, children }: Props = $props();
+</script>
+
+<section class="panel" class:muted>
+	{#if title !== undefined}
+		<div class="head">
+			<h2>{title}</h2>
+			{#if count !== undefined}
+				<span class="count">{count}</span>
+			{/if}
+		</div>
+	{/if}
+	{@render children()}
+</section>
+
+<style>
+	.panel {
+		background: var(--wf-bg-elevated, #fff);
+		border: 1px solid var(--wf-line, #e2e0d9);
+		border-radius: var(--df-radius-lg, 10px);
+		padding: 1rem 1.05rem 0.75rem;
+	}
+
+	.panel.muted {
+		background: var(--wf-bg-elevated, #fff);
+	}
+
+	.head {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		margin-bottom: 0.65rem;
+		padding-bottom: 0.5rem;
+		border-bottom: 1px solid var(--wf-line, #e2e0d9);
+	}
+
+	.head h2 {
+		margin: 0;
+		font-size: 0.72rem;
+		font-weight: 700;
+		letter-spacing: 0.1em;
+		text-transform: uppercase;
+		color: var(--wf-ink-soft, #5c5c56);
+	}
+
+	.count {
+		font-variant-numeric: tabular-nums;
+		font-weight: 600;
+		font-size: 0.75rem;
+		min-width: 1.4rem;
+		text-align: center;
+		padding: 0.1rem 0.4rem;
+		border-radius: 999px;
+		background: var(--wf-ink, #1c1c1a);
+		color: #fff;
+	}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/product/StatRow.svelte b/tests/e2e-ui/ui/src/lib/components/product/StatRow.svelte
new file mode 100644
index 00000000..c64bab4f
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/product/StatRow.svelte
@@ -0,0 +1,51 @@
+<script lang="ts">
+	export type Stat = { value: number | string; label: string };
+
+	interface Props {
+		stats: Stat[];
+	}
+
+	let { stats }: Props = $props();
+</script>
+
+<div class="stats">
+	{#each stats as s}
+		<div class="stat">
+			<span class="n">{s.value}</span>
+			<span class="l">{s.label}</span>
+		</div>
+	{/each}
+</div>
+
+<style>
+	.stats {
+		display: flex;
+		gap: 0.5rem;
+		margin-bottom: 1.25rem;
+		flex-wrap: wrap;
+	}
+
+	.stat {
+		display: flex;
+		align-items: baseline;
+		gap: 0.35rem;
+		padding: 0.35rem 0.7rem;
+		border-radius: 999px;
+		border: 1px solid var(--wf-line, #e2e0d9);
+	}
+
+	.n {
+		font-weight: 700;
+		font-size: 0.95rem;
+		font-variant-numeric: tabular-nums;
+		color: var(--wf-ink, #1c1c1a);
+	}
+
+	.l {
+		font-size: 0.72rem;
+		font-weight: 500;
+		letter-spacing: 0.03em;
+		text-transform: uppercase;
+		color: var(--wf-ink-soft, #5c5c56);
+	}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/product/index.ts b/tests/e2e-ui/ui/src/lib/components/product/index.ts
new file mode 100644
index 00000000..7b956e92
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/product/index.ts
@@ -0,0 +1,5 @@
+export { default as AppPage } from './AppPage.svelte';
+export { default as PageHeader } from './PageHeader.svelte';
+export { default as InlineAlert } from './InlineAlert.svelte';
+export { default as Panel } from './Panel.svelte';
+export { default as StatRow } from './StatRow.svelte';
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/AuthRefresh.svelte b/tests/e2e-ui/ui/src/lib/components/shared/AuthRefresh.svelte
new file mode 100644
index 00000000..274b05be
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/AuthRefresh.svelte
@@ -0,0 +1,59 @@
+<script lang="ts">
+	import { browser } from '$app/environment';
+	import { invalidateAll } from '$app/navigation';
+	import { page } from '$app/state';
+
+	const MIN_REFRESH_DELAY_MS = 5_000;
+	const RETRY_DELAY_MS = 30_000;
+	const FALLBACK_REFRESH_SKEW_MS = 60_000;
+
+	let refreshTimer: number | undefined;
+	let retryTimer: number | undefined;
+
+	function clearTimers() {
+		if (refreshTimer !== undefined) window.clearTimeout(refreshTimer);
+		if (retryTimer !== undefined) window.clearTimeout(retryTimer);
+		refreshTimer = undefined;
+		retryTimer = undefined;
+	}
+
+	async function refreshSession() {
+		try {
+			const response = await fetch('/api/auth/refresh', {
+				method: 'POST',
+				credentials: 'same-origin',
+				headers: {
+					accept: 'application/json'
+				}
+			});
+
+			if (response.ok || response.status === 401) {
+				await invalidateAll();
+				return;
+			}
+		} catch (error) {
+			console.error('Background auth refresh failed:', error);
+		}
+
+		retryTimer = window.setTimeout(refreshSession, RETRY_DELAY_MS);
+	}
+
+	$effect(() => {
+		if (!browser) return;
+
+		clearTimers();
+
+		const session = page.data.session;
+		if (!session?.user || !session.hasRefreshToken) return;
+
+		const refreshAt =
+			typeof session.refreshAfter === 'number'
+				? session.refreshAfter * 1000
+				: new Date(session.expires ?? 0).getTime() - FALLBACK_REFRESH_SKEW_MS;
+		const delay = Math.max(MIN_REFRESH_DELAY_MS, refreshAt - Date.now());
+
+		refreshTimer = window.setTimeout(refreshSession, delay);
+
+		return clearTimers;
+	});
+</script>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/Footer.svelte b/tests/e2e-ui/ui/src/lib/components/shared/Footer.svelte
new file mode 100644
index 00000000..0fb4a432
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/Footer.svelte
@@ -0,0 +1,28 @@
+<footer class="lab-footer">
+	<div class="lab-footer-inner">
+		<div>
+			<div class="lab-footer-brand">e2e-ui · Distributed template</div>
+			<p class="lab-footer-tag">
+				Framework fixture: multi-crate CQRS, OIDC, SSR GraphQL, and live subscriptions — run as e2e
+				and kept current with the library.
+			</p>
+		</div>
+		<div>
+			<h4>Demos</h4>
+			<ul>
+				<li><a href="/todos">Todos</a></li>
+				<li><a href="/chat">Chat</a></li>
+				<li><a href="/session">Session</a></li>
+			</ul>
+		</div>
+		<div>
+			<h4>Template</h4>
+			<ul>
+				<li><a href="/#story">Why this exists</a></li>
+				<li><a href="/#architecture">Architecture</a></li>
+				<li><a href="/#run">How to run</a></li>
+				<li><a href="/signin?callbackUrl=/todos">Sign in</a></li>
+			</ul>
+		</div>
+	</div>
+</footer>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/header/Auth.svelte b/tests/e2e-ui/ui/src/lib/components/shared/header/Auth.svelte
new file mode 100644
index 00000000..643bb027
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/header/Auth.svelte
@@ -0,0 +1,54 @@
+<script lang="ts">
+	import { browser } from '$app/environment';
+	import { page } from '$app/state';
+	import type { Snippet } from 'svelte';
+
+	const {
+		children,
+		onToggle
+	}: {
+		children?: Snippet;
+		onToggle: () => void;
+	} = $props();
+
+	const isAuthenticated = $derived(!!page.data.session?.user);
+	const user = $derived(page.data.session?.user);
+	// /login starts Auth.js OIDC then shows our password form (Login V2 custom base URI).
+	const signInHref = $derived(
+		`/login?callbackUrl=${encodeURIComponent(page.url.pathname + (browser ? page.url.search : ''))}`
+	);
+
+	const toggleMenu = () => {
+		onToggle();
+	};
+
+	const getInitials = (name: string | null | undefined, email: string | null | undefined): string => {
+		if (name) {
+			return name
+				.split(' ')
+				.map((n) => n[0])
+				.join('')
+				.toUpperCase()
+				.slice(0, 2);
+		}
+		return email ? email.charAt(0).toUpperCase() : 'U';
+	};
+</script>
+
+{#if isAuthenticated}
+	<button type="button" onclick={toggleMenu} class="auth-avatar" aria-label="User menu">
+		{#if user?.image}
+			<img src={user.image} alt="Avatar" class="auth-avatar-img" />
+		{:else}
+			<span class="auth-avatar-initials">
+				{getInitials(user?.name, user?.email)}
+			</span>
+		{/if}
+	</button>
+{:else}
+	<a href={signInHref} class="cta-button">Sign in</a>
+{/if}
+
+{#if children}
+	{@render children()}
+{/if}
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/header/Navbar.svelte b/tests/e2e-ui/ui/src/lib/components/shared/header/Navbar.svelte
new file mode 100644
index 00000000..fcc79086
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/header/Navbar.svelte
@@ -0,0 +1,127 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import Auth from '$lib/components/shared/header/Auth.svelte';
+	import AccountMenu from '$lib/components/shared/menus/AccountMenu.svelte';
+	import { engineRoleFromGroups, isAdminEngineRole } from '$lib/roles';
+
+	let isMenuOpen = $state(false);
+	let scrolled = $state(false);
+	let accountMenuOpen = $state(false);
+
+	const isAuthenticated = $derived(!!page.data.session?.user);
+	/** Prefer layout `engineRole`; fall back to session groups (Zitadel project roles). */
+	const isAdmin = $derived(
+		isAdminEngineRole(page.data.engineRole) ||
+			isAdminEngineRole(
+				engineRoleFromGroups(
+					(page.data.session?.user as { groups?: string[] } | undefined)?.groups
+				)
+			)
+	);
+	const currentPath = $derived(page.url.pathname);
+
+	const isActive = (path: string) => {
+		if (path === '/') return currentPath === '/';
+		return currentPath.startsWith(path);
+	};
+
+	const toggleAccountMenu = () => {
+		accountMenuOpen = !accountMenuOpen;
+	};
+
+	const toggleMenu = () => {
+		isMenuOpen = !isMenuOpen;
+	};
+
+	$effect(() => {
+		const handleScroll = () => {
+			scrolled = window.scrollY > 50;
+		};
+		if (typeof window !== 'undefined') {
+			window.addEventListener('scroll', handleScroll);
+			return () => window.removeEventListener('scroll', handleScroll);
+		}
+	});
+</script>
+
+<nav class="navbar" class:scrolled aria-label="main navigation">
+	<div class="navbar-container">
+		<div class="navbar-brand">
+			<a href="/" class="brand-link">
+				<span class="brand-mark" aria-hidden="true">df</span>
+				e2e-ui
+			</a>
+		</div>
+
+		<button
+			class="navbar-burger"
+			class:is-active={isMenuOpen}
+			aria-label="menu"
+			aria-expanded={isMenuOpen}
+			onclick={toggleMenu}
+		>
+			<span></span>
+			<span></span>
+			<span></span>
+		</button>
+
+		<div class="navbar-menu" class:is-active={isMenuOpen}>
+			<div class="navbar-links">
+				<a href="/" class="nav-link" class:active={isActive('/')} onclick={() => (isMenuOpen = false)}
+					>Home</a
+				>
+				{#if isAuthenticated}
+					<a
+						href="/todos"
+						class="nav-link"
+						class:active={isActive('/todos')}
+						onclick={() => (isMenuOpen = false)}>Todos</a
+					>
+					<a
+						href="/blob"
+						class="nav-link"
+						class:active={isActive('/blob')}
+						onclick={() => (isMenuOpen = false)}>Blob</a
+					>
+					<a
+						href="/chat"
+						class="nav-link"
+						class:active={isActive('/chat')}
+						onclick={() => (isMenuOpen = false)}>Chat</a
+					>
+					<a
+						href="/session"
+						class="nav-link"
+						class:active={isActive('/session')}
+						onclick={() => (isMenuOpen = false)}>Session</a
+					>
+					{#if isAdmin}
+						<a
+							href="/admin"
+							class="nav-link nav-link-admin"
+							class:active={isActive('/admin')}
+							onclick={() => (isMenuOpen = false)}>Admin</a
+						>
+					{/if}
+				{/if}
+			</div>
+
+			<div class="navbar-cta">
+				{#if !isAuthenticated}
+					<a
+						href="/signup?callbackUrl=/todos"
+						class="cta-button-outline"
+						onclick={() => (isMenuOpen = false)}
+					>
+						Create account
+					</a>
+				{/if}
+				<Auth onToggle={toggleAccountMenu} />
+			</div>
+		</div>
+	</div>
+</nav>
+
+{#if accountMenuOpen}
+	<AccountMenu bind:accountMenuOpen />
+{/if}
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/menus/AccountMenu.svelte b/tests/e2e-ui/ui/src/lib/components/shared/menus/AccountMenu.svelte
new file mode 100644
index 00000000..893f3b71
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/menus/AccountMenu.svelte
@@ -0,0 +1,178 @@
+<script lang="ts">
+  import { page } from '$app/state';
+
+  let { accountMenuOpen = $bindable(false) } = $props();
+
+  const user = $derived(page.data.session?.user);
+  const displayName = $derived(user?.name || user?.email || user?.username || 'Signed in');
+</script>
+
+<div class="account-menu-overlay">
+    <div class="account-menu-modal">
+      <h2 class="account-menu-title">Account Actions</h2>
+      {#if user}
+        <div class="account-menu-user">
+          <strong>{displayName}</strong>
+          {#if user.email}
+            <span>{user.email}</span>
+          {/if}
+        </div>
+      {/if}
+      <a
+        href="/todos"
+        class="account-menu-btn account-menu-btn-primary"
+        onclick={() => accountMenuOpen = false}
+      >
+        Todos
+      </a>
+      <a
+        href="/chat"
+        class="account-menu-btn account-menu-btn-secondary"
+        onclick={() => accountMenuOpen = false}
+      >
+        Chat
+      </a>
+      <a
+        href="/session"
+        class="account-menu-btn account-menu-btn-secondary"
+        onclick={() => accountMenuOpen = false}
+      >
+        Session Info
+      </a>
+      <a
+        href="/signout"
+        class="account-menu-btn account-menu-btn-danger"
+      >
+        Sign Out
+      </a>
+      <button
+        onclick={() => accountMenuOpen = false}
+        class="account-menu-btn account-menu-btn-neutral"
+      >
+        Close
+      </button>
+    </div>
+  </div>
+
+<style>
+/* Mobile-first */
+.account-menu-overlay {
+	position: fixed;
+	top: 5rem;
+	right: 0.5rem;
+	left: 0.5rem;
+	z-index: 1100;
+	animation: fadeIn 0.2s var(--ease-out-expo);
+
+	@media (--mobile-up) {
+		right: 1rem;
+		left: auto;
+	}
+}
+
+.account-menu-modal {
+	background: var(--hops-bg-white);
+	border: 1px solid var(--hops-border-strong);
+	border-radius: 12px;
+	box-shadow: var(--shadow-lg);
+	padding: 1.25rem;
+	min-width: auto;
+	display: flex;
+	flex-direction: column;
+	gap: 0.5rem;
+
+	@media (--mobile-up) {
+		min-width: 200px;
+	}
+}
+
+.account-menu-title {
+	font-family: var(--font-display);
+	font-size: 0.875rem;
+	font-weight: 700;
+	color: var(--hops-text-muted);
+	text-transform: uppercase;
+	letter-spacing: 0;
+	margin: 0 0 0.5rem 0;
+	padding-bottom: 0.5rem;
+	border-bottom: 1px solid var(--hops-border);
+}
+
+.account-menu-user {
+	display: flex;
+	flex-direction: column;
+	gap: 0.15rem;
+	padding: 0.25rem 0 0.75rem;
+	border-bottom: 1px solid var(--hops-border);
+	margin-bottom: 0.25rem;
+}
+
+.account-menu-user strong {
+	font-family: var(--font-display);
+	font-size: 0.95rem;
+	color: var(--hops-navy);
+}
+
+.account-menu-user span {
+	font-size: 0.82rem;
+	color: var(--hops-text-muted);
+	overflow-wrap: anywhere;
+}
+
+.account-menu-btn {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	font-family: var(--font-body);
+	font-size: 0.9rem;
+	font-weight: 600;
+	padding: 0.75rem 1rem;
+	border-radius: 8px;
+	border: none;
+	cursor: pointer;
+	text-decoration: none;
+	transition: all 0.2s var(--ease-out-expo);
+	text-align: center;
+
+	&.account-menu-btn-primary {
+		background: var(--hops-orange);
+		color: var(--hops-text-inverse);
+
+		&:hover {
+			background: var(--hops-orange-light);
+			transform: translateY(-1px);
+		}
+	}
+
+	&.account-menu-btn-secondary {
+		background: var(--hops-navy);
+		color: var(--hops-text-inverse);
+
+		&:hover {
+			background: var(--hops-navy-light);
+			transform: translateY(-1px);
+		}
+	}
+
+	&.account-menu-btn-danger {
+		background: var(--hops-danger);
+		color: var(--hops-text-inverse);
+
+		&:hover {
+			background: #c53030;
+			transform: translateY(-1px);
+		}
+	}
+
+	&.account-menu-btn-neutral {
+		background: transparent;
+		color: var(--hops-text-secondary);
+		border: 1px solid var(--hops-border-strong);
+
+		&:hover {
+			background: var(--hops-bg-light);
+			color: var(--hops-text-primary);
+		}
+	}
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/Alert.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/Alert.svelte
new file mode 100644
index 00000000..3c005c9c
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/Alert.svelte
@@ -0,0 +1,133 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Alert variant */
+		variant?: 'warning' | 'success' | 'error' | 'info';
+		/** Optional title */
+		title?: string;
+		/** Alert content */
+		children: Snippet;
+	}
+
+	let {
+		variant = 'info',
+		title,
+		children
+	}: Props = $props();
+</script>
+
+<div class="alert variant-{variant}">
+	{#if title}
+		<h2 class="alert-title">{title}</h2>
+	{/if}
+	<div class="alert-content">
+		{@render children()}
+	</div>
+</div>
+
+<style>
+.alert {
+	border-radius: 12px;
+	padding: 1.5rem;
+	text-align: center;
+
+	@media (--tablet-up) {
+		padding: 2rem;
+	}
+}
+
+.alert-title {
+	font-family: var(--font-display);
+	font-size: 1.5rem;
+	font-weight: 700;
+	margin: 0 0 0.75rem;
+}
+
+.alert-content {
+	& :global(p) {
+		margin: 0 0 1rem;
+	}
+
+	& :global(p:last-child) {
+		margin-bottom: 0;
+	}
+}
+
+/* Variants */
+.variant-warning {
+	background: rgba(221, 107, 32, 0.1);
+	border: 1px solid rgba(221, 107, 32, 0.3);
+
+	& .alert-title {
+		color: var(--hops-warning);
+	}
+
+	& .alert-content {
+		color: var(--hops-text-secondary);
+	}
+}
+
+.variant-success {
+	background: rgba(76, 175, 80, 0.15);
+	border: 1px solid rgba(76, 175, 80, 0.3);
+
+	& .alert-title {
+		color: #4caf50;
+	}
+
+	& .alert-content {
+		color: var(--hops-text-secondary);
+	}
+}
+
+.variant-error {
+	background: rgba(244, 67, 54, 0.15);
+	border: 1px solid rgba(244, 67, 54, 0.3);
+
+	& .alert-title {
+		color: #f44336;
+	}
+
+	& .alert-content {
+		color: #f44336;
+	}
+}
+
+.variant-info {
+	background: rgba(26, 39, 68, 0.05);
+	border: 1px solid var(--hops-border);
+
+	& .alert-title {
+		color: var(--hops-navy);
+	}
+
+	& .alert-content {
+		color: var(--hops-text-secondary);
+	}
+}
+
+/* Dark background variants */
+:global(.bg-navy) .variant-warning,
+:global([data-theme="dark"]) .variant-warning {
+	background: rgba(221, 107, 32, 0.2);
+
+	& .alert-content {
+		color: rgba(255, 255, 255, 0.7);
+	}
+}
+
+:global(.bg-navy) .variant-success,
+:global([data-theme="dark"]) .variant-success {
+	& .alert-content {
+		color: var(--hops-text-inverse);
+	}
+}
+
+:global(.bg-navy) .variant-error,
+:global([data-theme="dark"]) .variant-error {
+	& .alert-content {
+		color: #ff6b6b;
+	}
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/Badge.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/Badge.svelte
new file mode 100644
index 00000000..2cd1a9df
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/Badge.svelte
@@ -0,0 +1,87 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Show pulsing status dot */
+		dot?: boolean;
+		/** Badge variant */
+		variant?: 'navy' | 'light' | 'outline';
+		/** Add border to badge */
+		bordered?: boolean;
+		/** Custom icon snippet (alternative to dot) */
+		icon?: Snippet;
+		/** Badge content */
+		children: Snippet;
+	}
+
+	let { dot = false, variant = 'navy', bordered = false, icon, children }: Props = $props();
+</script>
+
+<span class="badge badge-{variant}" class:bordered>
+	{#if dot}
+		<span class="badge-dot"></span>
+	{:else if icon}
+		<span class="badge-icon">{@render icon()}</span>
+	{/if}
+	{@render children()}
+</span>
+
+<style>
+.badge {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.5rem;
+	padding: 0.5rem 1rem;
+	border-radius: 100px;
+	font-size: 0.875rem;
+	font-weight: 600;
+	letter-spacing: 0.02em;
+}
+
+.badge-navy {
+	background: var(--hops-navy);
+	color: var(--hops-text-inverse);
+}
+
+.badge-light {
+	background: rgba(230, 154, 45, 0.15);
+	color: var(--hops-orange);
+}
+
+.badge-outline {
+	background: transparent;
+	border: 1px solid var(--hops-border);
+	color: var(--hops-text-primary);
+}
+
+.badge.bordered {
+	border: 1px solid currentColor;
+	border-color: rgba(230, 154, 45, 0.3);
+}
+
+.badge-dot {
+	width: 8px;
+	height: 8px;
+	background: var(--hops-orange);
+	border-radius: 50%;
+	animation: pulse 2s ease-in-out infinite;
+}
+
+.badge-icon {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	font-size: 0.875em;
+}
+
+@keyframes pulse {
+	0%, 100% {
+		opacity: 1;
+		transform: scale(1);
+	}
+	50% {
+		opacity: 0.6;
+		transform: scale(0.9);
+	}
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/Button.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/Button.svelte
new file mode 100644
index 00000000..a0918045
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/Button.svelte
@@ -0,0 +1,197 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLButtonAttributes, HTMLAnchorAttributes } from 'svelte/elements';
+
+	interface Props {
+		/** Button variant — ink is product primary (dark); ghost/quiet are compact actions */
+		variant?: 'primary' | 'secondary' | 'outlined' | 'ink' | 'ghost' | 'quiet';
+		/** Button size */
+		size?: 'sm' | 'md' | 'lg';
+		/** Light mode for outlined on dark backgrounds */
+		light?: boolean;
+		/** Link href - renders as <a> when provided */
+		href?: string;
+		/** Button type (when not a link) */
+		type?: 'button' | 'submit' | 'reset';
+		/** Disabled state */
+		disabled?: boolean;
+		/** Accessible name when children are icon-only */
+		title?: string;
+		/** Click handler */
+		onclick?: (e: MouseEvent) => void;
+		/** Test id (Playwright / fixtures) */
+		'data-testid'?: string;
+		/** Button content */
+		children: Snippet;
+	}
+
+	let {
+		variant = 'primary',
+		size = 'md',
+		light = false,
+		href,
+		type = 'button',
+		disabled = false,
+		title,
+		onclick,
+		'data-testid': dataTestId,
+		children
+	}: Props = $props();
+
+	const isLink = $derived(!!href);
+</script>
+
+{#if isLink}
+	<a
+		{href}
+		class="button button-{variant} button-{size}"
+		class:light
+		{title}
+		data-testid={dataTestId}
+		{onclick}
+	>
+		{@render children()}
+	</a>
+{:else}
+	<button
+		{type}
+		{disabled}
+		class="button button-{variant} button-{size}"
+		class:light
+		{title}
+		data-testid={dataTestId}
+		{onclick}
+	>
+		{@render children()}
+	</button>
+{/if}
+
+<style>
+.button {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	gap: 0.5rem;
+	font-family: var(--wf-sans, var(--font-body));
+	font-weight: 600;
+	font-size: 0.95rem;
+	padding: 0.7rem 1.25rem;
+	border-radius: var(--wf-radius, 6px);
+	border: none;
+	cursor: pointer;
+	text-decoration: none;
+	transition: background 0.15s ease, border-color 0.15s ease, color 0.15s ease;
+	position: relative;
+
+	&:disabled {
+		opacity: 0.55;
+		cursor: not-allowed;
+	}
+}
+
+/* Sizes */
+.button-sm {
+	padding: 0.35rem 0.7rem;
+	font-size: 0.8rem;
+	font-weight: 600;
+}
+
+.button-lg {
+	padding: 0.85rem 1.5rem;
+	font-size: 1rem;
+
+	@media (--tablet) {
+		padding: 0.75rem 1.25rem;
+		font-size: 0.95rem;
+	}
+
+	@media (--mobile) {
+		padding: 0.75rem 1.1rem;
+		font-size: 0.95rem;
+		width: 100%;
+	}
+}
+
+/* Primary variant — accent */
+.button-primary {
+	background: var(--wf-accent, var(--hops-orange));
+	color: #fff;
+
+	&:hover:not(:disabled) {
+		background: var(--hops-orange-light, #5a7a9e);
+	}
+}
+
+/* Ink — product default (dark fill) */
+.button-ink {
+	background: var(--wf-ink, #1c1c1a);
+	color: #fff;
+	border: 1px solid var(--wf-ink, #1c1c1a);
+
+	&:hover:not(:disabled) {
+		background: var(--hops-navy-light, #2a2a28);
+	}
+}
+
+/* Secondary variant */
+.button-secondary {
+	background: var(--wf-ink, var(--hops-navy));
+	color: var(--wf-bg, #f6f5f2);
+
+	&:hover:not(:disabled) {
+		background: var(--hops-navy-light, #2a2a28);
+	}
+}
+
+/* Outlined variant */
+.button-outlined {
+	background: transparent;
+	border: 1px solid var(--wf-line-strong, var(--hops-navy));
+	color: var(--wf-ink, var(--hops-navy));
+
+	&:hover:not(:disabled) {
+		background: var(--wf-ink, var(--hops-navy));
+		border-color: var(--wf-ink, var(--hops-navy));
+		color: var(--wf-bg, #f6f5f2);
+	}
+
+	/* Light mode for dark backgrounds */
+	&.light {
+		border-color: rgba(255, 255, 255, 0.45);
+		color: var(--hops-text-inverse, #f6f5f2);
+
+		&:hover:not(:disabled) {
+			background: rgba(255, 255, 255, 0.12);
+			border-color: rgba(255, 255, 255, 0.75);
+			color: var(--hops-text-inverse, #f6f5f2);
+		}
+	}
+}
+
+.button-ghost {
+	background: var(--wf-accent-soft, rgba(61, 90, 128, 0.08));
+	color: var(--wf-accent, #3d5a80);
+
+	&:hover:not(:disabled) {
+		background: rgba(61, 90, 128, 0.14);
+	}
+}
+
+.button-quiet {
+	background: transparent;
+	color: var(--wf-ink-soft, #5c5c56);
+	font-weight: 500;
+
+	&:hover:not(:disabled) {
+		background: rgba(28, 28, 26, 0.05);
+		color: var(--wf-ink, #1c1c1a);
+	}
+}
+
+/* Touch target for mobile */
+@media (--mobile) {
+	.button {
+		min-height: 44px;
+	}
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/Card.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/Card.svelte
new file mode 100644
index 00000000..77248c90
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/Card.svelte
@@ -0,0 +1,207 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Color theme */
+		theme?: 'light' | 'dark' | 'glass';
+		/** Padding size */
+		padding?: 'sm' | 'md' | 'lg' | 'none';
+		/** Enable hover lift and border accent */
+		hover?: boolean;
+		/** Animation delay in seconds */
+		delay?: number;
+		/** Optional: show streak animation on hover (dark theme) */
+		streak?: boolean;
+		/** Featured/highlighted state (orange border + accent bar) */
+		featured?: boolean;
+		/** Optional header title (creates a navy header bar) */
+		headerTitle?: string;
+		/** Card content */
+		children: Snippet;
+	}
+
+	let {
+		theme = 'light',
+		padding = 'md',
+		hover = true,
+		delay = 0,
+		streak = false,
+		featured = false,
+		headerTitle,
+		children
+	}: Props = $props();
+</script>
+
+<div
+	class="card theme-{theme}"
+	class:padding-sm={padding === 'sm' && !headerTitle}
+	class:padding-md={padding === 'md' && !headerTitle}
+	class:padding-lg={padding === 'lg' && !headerTitle}
+	class:has-hover={hover}
+	class:has-streak={streak}
+	class:is-featured={featured}
+	class:has-header={!!headerTitle}
+	style:--delay="{delay}s"
+>
+	{#if headerTitle}
+		<header class="card-header">
+			<p class="card-header-title">{headerTitle}</p>
+		</header>
+		<div class="card-body padding-{padding}">
+			{@render children()}
+		</div>
+	{:else}
+		{@render children()}
+	{/if}
+	{#if streak}
+		<div class="card-streak"></div>
+	{/if}
+	{#if featured}
+		<div class="card-accent"></div>
+	{/if}
+</div>
+
+<style>
+.card {
+	position: relative;
+	border-radius: 20px;
+	overflow: hidden;
+	animation: fadeInUp 0.5s var(--ease-out-expo) both;
+	animation-delay: var(--delay);
+	transition: all 0.4s var(--ease-out-expo);
+}
+
+.card.has-header {
+	border-radius: 16px;
+}
+
+/* Padding variants */
+.padding-sm {
+	padding: 1.25rem;
+
+	@media (--tablet-up) {
+		padding: 1.5rem;
+	}
+}
+
+.padding-md {
+	padding: 1.5rem;
+
+	@media (--tablet-up) {
+		padding: 2rem;
+	}
+}
+
+.padding-lg {
+	padding: 2rem;
+
+	@media (--tablet-up) {
+		padding: 2.5rem;
+	}
+}
+
+.padding-none {
+	padding: 0;
+}
+
+/* Header styles */
+.card-header {
+	background: var(--hops-navy);
+	padding: 1rem 1.5rem;
+}
+
+.card-header-title {
+	font-family: var(--font-display);
+	font-size: 1rem;
+	font-weight: 700;
+	color: var(--hops-text-inverse);
+	margin: 0;
+	text-transform: uppercase;
+	letter-spacing: 0.05em;
+}
+
+/* Light theme */
+.theme-light {
+	background: var(--hops-bg-white);
+	border: 2px solid var(--hops-border);
+
+	&.has-hover:hover {
+		border-color: var(--hops-orange);
+		transform: translateY(-4px);
+		box-shadow: var(--shadow-lg);
+	}
+
+	&.is-featured {
+		border-color: var(--hops-orange);
+		background: linear-gradient(180deg, rgba(230, 154, 45, 0.05) 0%, var(--hops-bg-white) 100%);
+	}
+
+	&.has-header {
+		border: 1px solid var(--hops-border);
+		box-shadow: var(--shadow-sm);
+	}
+}
+
+/* Dark theme */
+.theme-dark {
+	background: rgba(255, 255, 255, 0.05);
+	border: 1px solid rgba(255, 255, 255, 0.1);
+
+	&.has-hover:hover {
+		transform: translateY(-8px);
+		border-color: rgba(230, 154, 45, 0.3);
+		background: rgba(255, 255, 255, 0.08);
+	}
+
+	&.is-featured {
+		border-color: var(--hops-orange);
+		background: rgba(230, 154, 45, 0.08);
+
+		&.has-hover:hover {
+			background: rgba(230, 154, 45, 0.12);
+		}
+	}
+}
+
+/* Glass theme (for nested cards in dark sections) */
+.theme-glass {
+	background: rgba(0, 0, 0, 0.25);
+	border: 1px solid rgba(255, 255, 255, 0.08);
+	border-radius: 16px;
+
+	&.has-hover:hover {
+		background: rgba(230, 154, 45, 0.1);
+		border-color: rgba(230, 154, 45, 0.25);
+		transform: translateY(-4px);
+	}
+}
+
+/* Featured accent bar */
+.card-accent {
+	position: absolute;
+	top: 0;
+	left: 0;
+	right: 0;
+	height: 4px;
+	background: linear-gradient(90deg, var(--hops-orange), var(--hops-orange-light));
+}
+
+/* Streak animation (dark theme only) */
+.card-streak {
+	position: absolute;
+	top: 0;
+	left: -100px;
+	width: 100px;
+	height: 100%;
+	background: linear-gradient(90deg, transparent, rgba(230, 154, 45, 0.1), transparent);
+	transform: skewX(-15deg) translateX(-100px);
+	opacity: 0;
+	transition: all 0.6s ease;
+	pointer-events: none;
+}
+
+.has-streak:hover .card-streak {
+	opacity: 1;
+	transform: skewX(-15deg) translateX(400px);
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/CodeWindow.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/CodeWindow.svelte
new file mode 100644
index 00000000..74aade17
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/CodeWindow.svelte
@@ -0,0 +1,168 @@
+<script lang="ts">
+	interface Props {
+		/** Filename or label shown in header */
+		filename?: string;
+		/** Code content to display */
+		code: string;
+		/** Size variant */
+		size?: 'sm' | 'md' | 'lg';
+		/** Enable hover lift effect */
+		hover?: boolean;
+		/** Enable 3D perspective tilt on desktop */
+		perspective?: boolean;
+	}
+
+	let {
+		filename = '',
+		code,
+		size = 'md',
+		hover = false,
+		perspective = false
+	}: Props = $props();
+</script>
+
+<div
+	class="code-window size-{size}"
+	class:has-hover={hover}
+	class:has-perspective={perspective}
+>
+	<div class="code-header">
+		<div class="code-dots">
+			<span></span>
+			<span></span>
+			<span></span>
+		</div>
+		{#if filename}
+			<span class="code-filename">{filename}</span>
+		{/if}
+	</div>
+	<pre class="code-content"><code>{code}</code></pre>
+</div>
+
+<style>
+.code-window {
+	background: var(--hops-navy-deep);
+	border-radius: 12px;
+	overflow: hidden;
+	box-shadow: 0 10px 40px rgba(26, 39, 68, 0.2), 0 0 0 1px rgba(26, 39, 68, 0.1);
+	transition: transform 0.4s var(--ease-out-expo), box-shadow 0.4s var(--ease-out-expo);
+
+	&.size-lg {
+		border-radius: 16px;
+		box-shadow: 0 20px 60px rgba(26, 39, 68, 0.25), 0 0 0 1px rgba(26, 39, 68, 0.1);
+	}
+
+	&.has-hover:hover {
+		transform: translateY(-4px);
+		box-shadow: 0 20px 60px rgba(26, 39, 68, 0.3), 0 0 0 1px rgba(26, 39, 68, 0.1);
+	}
+
+	&.has-perspective {
+		@media (--desktop-up) {
+			transform: perspective(1000px) rotateY(-2deg) rotateX(2deg);
+
+			&:hover {
+				transform: perspective(1000px) rotateY(0deg) rotateX(0deg);
+			}
+		}
+	}
+}
+
+.code-header {
+	display: flex;
+	align-items: center;
+	gap: 0.75rem;
+	padding: 0.75rem 1rem;
+	background: rgba(0, 0, 0, 0.3);
+	border-bottom: 1px solid rgba(255, 255, 255, 0.05);
+
+	.size-lg & {
+		gap: 1rem;
+		padding: 1rem 1.25rem;
+	}
+}
+
+.code-dots {
+	display: flex;
+	gap: 6px;
+
+	& span {
+		width: 10px;
+		height: 10px;
+		border-radius: 50%;
+		background: var(--hops-orange);
+		opacity: 0.8;
+
+		&:nth-child(2) {
+			opacity: 0.5;
+		}
+
+		&:nth-child(3) {
+			opacity: 0.3;
+		}
+	}
+
+	.size-lg & span {
+		width: 12px;
+		height: 12px;
+	}
+
+	.size-lg & {
+		gap: 8px;
+	}
+}
+
+.code-filename {
+	font-family: var(--font-mono);
+	font-size: 0.75rem;
+	color: rgba(255, 255, 255, 0.5);
+
+	.size-lg & {
+		font-size: 0.8rem;
+	}
+}
+
+.code-content {
+	margin: 0;
+	padding: 1rem;
+	overflow-x: auto;
+	background: transparent;
+
+	& code {
+		display: block;
+		font-family: var(--font-mono);
+		font-size: 0.8rem;
+		line-height: 1.5;
+		color: #e2e8f0;
+		background: transparent;
+		white-space: pre;
+		text-align: left;
+	}
+
+	.size-sm & {
+		padding: 0.75rem;
+
+		& code {
+			font-size: 0.75rem;
+		}
+	}
+
+	.size-lg & {
+		padding: 1rem;
+
+		& code {
+			font-size: 0.75rem;
+			line-height: 1.7;
+
+			@media (--tablet-up) {
+				font-size: 0.85rem;
+				padding: 0.5rem;
+			}
+		}
+
+		@media (--tablet-up) {
+			padding: 1.5rem;
+		}
+	}
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/FeatureList.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/FeatureList.svelte
new file mode 100644
index 00000000..7016d085
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/FeatureList.svelte
@@ -0,0 +1,117 @@
+<script lang="ts">
+	type Item = string | { icon?: string; text: string };
+
+	interface Props {
+		/** List items - strings or objects with icon and text */
+		items: Item[];
+		/** Color theme */
+		theme?: 'light' | 'dark';
+		/** Indicator shown at end of each item */
+		indicator?: 'check' | 'x' | 'none';
+		/** Additional CSS class */
+		class?: string;
+	}
+
+	let {
+		items,
+		theme = 'light',
+		indicator = 'check',
+		class: className = ''
+	}: Props = $props();
+
+	function getText(item: Item): string {
+		return typeof item === 'string' ? item : item.text;
+	}
+
+	function getIcon(item: Item): string | undefined {
+		return typeof item === 'string' ? undefined : item.icon;
+	}
+</script>
+
+<ul class="feature-list theme-{theme} {className}">
+	{#each items as item, i (i)}
+		<li>
+			{#if getIcon(item)}
+				<span class="item-icon">{getIcon(item)}</span>
+			{/if}
+			<span class="item-text">{getText(item)}</span>
+			{#if indicator === 'check'}
+				<span class="item-indicator check">✓</span>
+			{:else if indicator === 'x'}
+				<span class="item-indicator x">✕</span>
+			{/if}
+		</li>
+	{/each}
+</ul>
+
+<style>
+.feature-list {
+	list-style: none;
+	padding: 0;
+	margin: 0;
+}
+
+.feature-list li {
+	display: flex;
+	align-items: center;
+	gap: 0.75rem;
+	padding: 0.75rem 0;
+}
+
+.feature-list li:last-child {
+	border-bottom: none;
+}
+
+.item-icon {
+	font-size: 1.25rem;
+	flex-shrink: 0;
+}
+
+.item-text {
+	flex: 1;
+}
+
+.item-indicator {
+	font-weight: 700;
+	font-size: 1.125rem;
+	flex-shrink: 0;
+}
+
+/* Light theme */
+.theme-light {
+	& li {
+		border-bottom: 1px solid var(--hops-border);
+	}
+
+	& .item-text {
+		color: var(--hops-text-secondary);
+	}
+
+	& .item-indicator.check {
+		color: var(--hops-success);
+	}
+
+	& .item-indicator.x {
+		color: #dc2626;
+	}
+}
+
+/* Dark theme */
+.theme-dark {
+	& li {
+		border-bottom: 1px solid rgba(255, 255, 255, 0.08);
+	}
+
+	& .item-text {
+		color: rgba(255, 255, 255, 0.8);
+	}
+
+	& .item-indicator.check {
+		color: var(--hops-orange);
+	}
+
+	& .item-indicator.x {
+		color: #f87171;
+	}
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/IconBox.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/IconBox.svelte
new file mode 100644
index 00000000..0d7f5c1b
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/IconBox.svelte
@@ -0,0 +1,63 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Size variant */
+		size?: 'sm' | 'md' | 'lg';
+		/** Style variant */
+		variant?: 'gradient' | 'navy' | 'light';
+		/** Icon content */
+		children: Snippet;
+	}
+
+	let { size = 'md', variant = 'gradient', children }: Props = $props();
+</script>
+
+<div class="icon-box icon-box-{size} icon-box-{variant}">
+	{@render children()}
+</div>
+
+<style>
+.icon-box {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	border-radius: 16px;
+	color: var(--hops-text-inverse);
+}
+
+/* Sizes */
+.icon-box-sm {
+	width: 48px;
+	height: 48px;
+	border-radius: 12px;
+}
+
+.icon-box-md {
+	width: 64px;
+	height: 64px;
+}
+
+.icon-box-lg {
+	width: 80px;
+	height: 80px;
+	border-radius: 20px;
+}
+
+/* Variants */
+.icon-box-gradient {
+	background: linear-gradient(135deg, var(--hops-orange) 0%, var(--hops-orange-dark) 100%);
+	box-shadow: var(--shadow-orange);
+}
+
+.icon-box-navy {
+	background: var(--hops-navy);
+	box-shadow: var(--shadow-md);
+}
+
+.icon-box-light {
+	background: var(--hops-bg-light);
+	color: var(--hops-orange);
+	box-shadow: var(--shadow-sm);
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/MarketingSection.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/MarketingSection.svelte
new file mode 100644
index 00000000..8641d2a3
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/MarketingSection.svelte
@@ -0,0 +1,162 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Section id for anchor links */
+		id?: string;
+		/** Color scheme - controls background and text colors */
+		theme?: 'light-primary' | 'light-secondary' | 'dark' | 'transparent-light' | 'transparent-dark';
+		/** Visual shape effect */
+		effect?: 'callout-right' | 'callout-left';
+		/** Show scroll arrow indicator */
+		arrow?: boolean;
+		/** Section content */
+		children: Snippet;
+	}
+
+	let {
+		id,
+		theme = 'light-primary',
+		effect,
+		arrow = false,
+		children
+	}: Props = $props();
+
+	// Arrow is automatically light on dark themes
+	const isLightArrow = $derived(
+		theme === 'dark' || theme === 'transparent-dark'
+	);
+</script>
+
+<section
+	{id}
+	class="marketing-section theme-{theme}"
+	class:has-arrow={arrow}
+	class:has-effect={effect}
+	class:effect-callout-right={effect === 'callout-right'}
+	class:effect-callout-left={effect === 'callout-left'}
+>
+	<div class="container">
+		{@render children()}
+	</div>
+
+	{#if arrow}
+		<div class="scroll-indicator" class:is-light={isLightArrow}>
+			<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+				<path d="M7 10l5 5 5-5" />
+			</svg>
+		</div>
+	{/if}
+</section>
+
+<style>
+.marketing-section {
+	padding: var(--section-padding) 0;
+	position: relative;
+}
+
+/* Themes - color schemes */
+.theme-light-primary {
+	background: var(--hops-bg-white);
+	color: var(--hops-text-primary);
+}
+
+.theme-light-secondary {
+	background: var(--hops-bg-light);
+	color: var(--hops-text-primary);
+}
+
+.theme-dark {
+	background: var(--hops-navy);
+	color: var(--hops-text-inverse);
+}
+
+.theme-transparent-light {
+	background: transparent;
+	color: var(--hops-text-primary);
+}
+
+.theme-transparent-dark {
+	background: transparent;
+	color: var(--hops-text-inverse);
+}
+
+/* Section with scroll indicator */
+.has-arrow {
+	padding-bottom: calc(var(--section-padding) + 4rem);
+}
+
+.scroll-indicator {
+	position: absolute;
+	bottom: calc(var(--section-padding) / 2);
+	left: 50%;
+	transform: translateX(-50%);
+	color: var(--hops-orange);
+
+	& svg {
+		width: 44px;
+		height: 44px;
+		animation: bounce 2s ease-in-out infinite;
+	}
+
+	&.is-light {
+		color: rgba(255, 255, 255, 0.7);
+	}
+}
+
+@keyframes bounce {
+	0%, 100% {
+		transform: translateY(0);
+		opacity: 0.6;
+	}
+	50% {
+		transform: translateY(10px);
+		opacity: 1;
+	}
+}
+
+/* Dark theme title overrides */
+.theme-dark :global(.section-title) {
+	color: var(--hops-text-inverse);
+}
+
+.theme-dark :global(.section-subtitle) {
+	color: rgba(255, 255, 255, 0.7);
+}
+
+/* Effect: Callout diagonal transitions */
+.has-effect {
+	--diagonal-height: 4rem;
+	position: relative;
+	z-index: 1;
+	margin-top: calc(-1 * var(--diagonal-height));
+	margin-bottom: calc(-1 * var(--diagonal-height));
+	padding-top: calc(var(--section-padding) + var(--diagonal-height));
+	padding-bottom: calc(var(--section-padding) + var(--diagonal-height));
+}
+
+/* Callout right: grows left to right (top angles down-left, bottom angles down-right) */
+.effect-callout-right {
+	clip-path: polygon(
+		0 var(--diagonal-height),
+		100% 0,
+		100% 100%,
+		0 calc(100% - var(--diagonal-height))
+	);
+}
+
+/* Callout left: grows right to left (mirrored) */
+.effect-callout-left {
+	clip-path: polygon(
+		0 0,
+		100% var(--diagonal-height),
+		100% calc(100% - var(--diagonal-height)),
+		0 100%
+	);
+}
+
+/* When effect has arrow, add extra padding */
+.has-effect.has-arrow {
+	padding-bottom: calc(var(--section-padding) + var(--diagonal-height) + 4rem);
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/Page.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/Page.svelte
new file mode 100644
index 00000000..c707cf0c
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/Page.svelte
@@ -0,0 +1,33 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Page title for <title> tag */
+		title?: string;
+		/** Meta description */
+		description?: string;
+		/** Page content */
+		children: Snippet;
+	}
+
+	let { title, description, children }: Props = $props();
+
+	const fullTitle = $derived(title ? `${title} | Hops` : 'Hops');
+</script>
+
+<svelte:head>
+	<title>{fullTitle}</title>
+	{#if description}
+		<meta name="description" content={description} />
+	{/if}
+</svelte:head>
+
+<div class="page">
+	{@render children()}
+</div>
+
+<style>
+.page {
+	min-height: 100vh;
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/ResponsiveGrid.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/ResponsiveGrid.svelte
new file mode 100644
index 00000000..0c9846c2
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/ResponsiveGrid.svelte
@@ -0,0 +1,98 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Number of columns at full width, or 'auto' for auto-fit */
+		columns: 2 | 3 | 4 | 'auto';
+		/** Gap between items */
+		gap?: 'sm' | 'md' | 'lg';
+		/** Maximum width of the grid container */
+		maxWidth?: string;
+		/** Minimum item width for auto columns */
+		minItemWidth?: string;
+		/** Bottom margin */
+		marginBottom?: 'none' | 'md' | 'lg';
+		/** Additional CSS class for styling hooks */
+		class?: string;
+		/** Grid content */
+		children: Snippet;
+	}
+
+	let {
+		columns,
+		gap = 'md',
+		maxWidth,
+		minItemWidth = '280px',
+		marginBottom = 'none',
+		class: className = '',
+		children
+	}: Props = $props();
+
+	const gapValues = {
+		sm: '1rem',
+		md: '1.5rem',
+		lg: '2rem'
+	};
+
+	const marginValues = {
+		none: '0',
+		md: '3rem',
+		lg: '4rem'
+	};
+</script>
+
+<div
+	class="responsive-grid cols-{columns} gap-{gap} mb-{marginBottom} {className}"
+	style:--grid-gap={gapValues[gap]}
+	style:--grid-max-width={maxWidth}
+	style:--grid-min-item={minItemWidth}
+	style:--grid-margin-bottom={marginValues[marginBottom]}
+>
+	{@render children()}
+</div>
+
+<style>
+.responsive-grid {
+	display: grid;
+	grid-template-columns: 1fr;
+	gap: var(--grid-gap);
+	max-width: var(--grid-max-width, none);
+	margin: 0 auto var(--grid-margin-bottom, 0);
+}
+
+/* 2 columns: 1 → 2 */
+.cols-2 {
+	@media (--tablet-up) {
+		grid-template-columns: repeat(2, 1fr);
+	}
+}
+
+/* 3 columns: 1 → 2 → 3 */
+.cols-3 {
+	@media (--mobile-up) {
+		grid-template-columns: repeat(2, 1fr);
+	}
+
+	@media (width >= 900px) {
+		grid-template-columns: repeat(3, 1fr);
+	}
+}
+
+/* 4 columns: 1 → 2 → 4 */
+.cols-4 {
+	@media (--mobile-up) {
+		grid-template-columns: repeat(2, 1fr);
+	}
+
+	@media (--desktop-up) {
+		grid-template-columns: repeat(4, 1fr);
+	}
+}
+
+/* Auto columns: responsive auto-fit */
+.cols-auto {
+	@media (--tablet-up) {
+		grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--grid-min-item, 280px)), 1fr));
+	}
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/Section.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/Section.svelte
new file mode 100644
index 00000000..9a59879c
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/Section.svelte
@@ -0,0 +1,31 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Section id for anchor links */
+		id?: string;
+		/** Include container wrapper */
+		container?: boolean;
+		/** Section content */
+		children: Snippet;
+	}
+
+	let { id, container = false, children }: Props = $props();
+</script>
+
+<section {id} class="section">
+	{#if container}
+		<div class="container">
+			{@render children()}
+		</div>
+	{:else}
+		{@render children()}
+	{/if}
+</section>
+
+<style>
+.section {
+	padding: var(--section-padding) 0;
+	position: relative;
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/SectionHeader.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/SectionHeader.svelte
new file mode 100644
index 00000000..ca7ce894
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/SectionHeader.svelte
@@ -0,0 +1,91 @@
+<script lang="ts">
+	import { SectionLabel } from '$lib/components/shared/ui';
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Text for the section label */
+		label: string;
+		/** Optional subtitle text */
+		subtitle?: string;
+		/** Theme for dark backgrounds */
+		theme?: 'light' | 'dark';
+		/** Text alignment */
+		align?: 'left' | 'center';
+		/** Title content as snippet (allows <br />, <span class="title-accent">, etc.) */
+		title: Snippet;
+	}
+
+	let {
+		label,
+		subtitle,
+		theme = 'light',
+		align = 'center',
+		title
+	}: Props = $props();
+</script>
+
+<div class="section-header theme-{theme} align-{align}">
+	<SectionLabel onDark={theme === 'dark'}>{label}</SectionLabel>
+	<h2 class="section-title">
+		{@render title()}
+	</h2>
+	{#if subtitle}
+		<p class="section-subtitle">{subtitle}</p>
+	{/if}
+</div>
+
+<style>
+.section-header {
+	margin-bottom: 3rem;
+}
+
+.align-center {
+	text-align: center;
+}
+
+.align-left {
+	text-align: left;
+}
+
+.section-title {
+	font-family: var(--font-display);
+	font-size: clamp(1.75rem, 5vw, 3rem);
+	font-weight: 800;
+	line-height: 1.15;
+	margin-bottom: 0.75rem;
+	letter-spacing: -0.02em;
+}
+
+.section-subtitle {
+	font-size: 1.125rem;
+	line-height: 1.6;
+	max-width: 600px;
+	margin: 0;
+}
+
+.align-center .section-subtitle {
+	margin: 0 auto;
+}
+
+/* Light theme */
+.theme-light {
+	& .section-title {
+		color: var(--hops-navy);
+	}
+
+	& .section-subtitle {
+		color: var(--hops-text-secondary);
+	}
+}
+
+/* Dark theme */
+.theme-dark {
+	& .section-title {
+		color: var(--hops-text-inverse);
+	}
+
+	& .section-subtitle {
+		color: rgba(255, 255, 255, 0.7);
+	}
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/SectionLabel.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/SectionLabel.svelte
new file mode 100644
index 00000000..e3c12638
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/SectionLabel.svelte
@@ -0,0 +1,36 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Adapts to dark backgrounds when true */
+		onDark?: boolean;
+		/** Label content */
+		children: Snippet;
+	}
+
+	let { onDark = false, children }: Props = $props();
+</script>
+
+<span class="section-label" class:on-dark={onDark}>
+	{@render children()}
+</span>
+
+<style>
+.section-label {
+	display: inline-block;
+	font-family: var(--font-body);
+	font-size: 0.75rem;
+	font-weight: 700;
+	text-transform: uppercase;
+	letter-spacing: 0.15em;
+	color: var(--hops-orange);
+	background: rgba(230, 154, 45, 0.1);
+	padding: 0.5rem 1rem;
+	border-radius: 100px;
+	margin-bottom: 1rem;
+}
+
+.section-label.on-dark {
+	background: rgba(230, 154, 45, 0.15);
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/SimplePage.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/SimplePage.svelte
new file mode 100644
index 00000000..5b6a5fe2
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/SimplePage.svelte
@@ -0,0 +1,90 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import Page from './Page.svelte';
+
+	interface Props {
+		/** Page title for <title> tag */
+		title?: string;
+		/** Meta description */
+		description?: string;
+		/** Maximum container width */
+		maxWidth?: 'sm' | 'md' | 'lg';
+		/** Page content */
+		children: Snippet;
+	}
+
+	let {
+		title,
+		description,
+		maxWidth = 'sm',
+		children
+	}: Props = $props();
+</script>
+
+<Page {title} {description}>
+	<div class="simple-page">
+		<div class="simple-page-container max-{maxWidth}">
+			{@render children()}
+		</div>
+	</div>
+</Page>
+
+<style>
+.simple-page {
+	padding: 7rem 0 4rem;
+	min-height: 100vh;
+	background: var(--wf-bg, var(--hops-bg-light));
+}
+
+.simple-page-container {
+	width: 100%;
+	margin: 0 auto;
+	padding: 0 2rem;
+	text-align: center;
+
+	@media (--tablet) {
+		padding: 0 1.5rem;
+	}
+
+	@media (--mobile) {
+		padding: 0 1rem;
+	}
+}
+
+.max-sm {
+	max-width: 600px;
+}
+
+.max-md {
+	max-width: 900px;
+}
+
+.max-lg {
+	max-width: 1100px;
+}
+
+/* Typography defaults for simple pages */
+.simple-page-container :global(h1) {
+	font-family: var(--wf-serif, var(--font-display));
+	font-size: clamp(1.65rem, 4vw, 2.15rem);
+	font-weight: 500;
+	letter-spacing: -0.02em;
+	color: var(--wf-ink, var(--hops-navy));
+	margin-bottom: 0.85rem;
+}
+
+.simple-page-container :global(p) {
+	font-size: 1.02rem;
+	color: var(--wf-ink-soft, var(--hops-text-secondary));
+	margin-bottom: 1.75rem;
+}
+
+.simple-page-container :global(code) {
+	font-family: var(--wf-mono, var(--font-mono));
+	font-size: 0.88em;
+	background: var(--wf-accent-soft, rgba(61, 90, 128, 0.08));
+	color: var(--wf-ink, #1c1c1a);
+	padding: 0.15em 0.4em;
+	border-radius: 4px;
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/StatBlock.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/StatBlock.svelte
new file mode 100644
index 00000000..8912d5a7
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/StatBlock.svelte
@@ -0,0 +1,142 @@
+<script lang="ts">
+	interface Props {
+		/** The main value to display */
+		value: string;
+		/** Optional unit suffix (e.g., "%", "months") */
+		unit?: string;
+		/** Description label */
+		label: string;
+		/** Color theme */
+		theme?: 'light' | 'dark';
+		/** Size variant */
+		size?: 'sm' | 'md' | 'lg';
+		/** Animation delay in seconds */
+		delay?: number;
+	}
+
+	let {
+		value,
+		unit = '',
+		label,
+		theme = 'light',
+		size = 'md',
+		delay = 0
+	}: Props = $props();
+</script>
+
+<div
+	class="stat-block theme-{theme} size-{size}"
+	style:--delay="{delay}s"
+>
+	<div class="stat-value">
+		{value}{#if unit}<span class="stat-unit">{unit}</span>{/if}
+	</div>
+	<div class="stat-label">{label}</div>
+</div>
+
+<style>
+.stat-block {
+	text-align: center;
+	animation: fadeInUp 0.5s var(--ease-out-expo) both;
+	animation-delay: var(--delay);
+}
+
+/* Size variants */
+.size-sm .stat-value {
+	font-size: 2rem;
+
+	@media (--tablet-up) {
+		font-size: 2.5rem;
+	}
+}
+
+.size-md .stat-value {
+	font-size: 2.5rem;
+
+	@media (--tablet-up) {
+		font-size: 3rem;
+	}
+}
+
+.size-lg .stat-value {
+	font-size: 3rem;
+
+	@media (--tablet-up) {
+		font-size: 3.5rem;
+	}
+}
+
+.stat-value {
+	font-family: var(--font-display);
+	font-weight: 900;
+	line-height: 1;
+	margin-bottom: 0.5rem;
+	letter-spacing: -0.02em;
+}
+
+.stat-unit {
+	font-weight: 800;
+	margin-left: 0.125rem;
+}
+
+.size-sm .stat-unit {
+	font-size: 1rem;
+
+	@media (--tablet-up) {
+		font-size: 1.25rem;
+	}
+}
+
+.size-md .stat-unit {
+	font-size: 1.25rem;
+
+	@media (--tablet-up) {
+		font-size: 1.5rem;
+	}
+}
+
+.size-lg .stat-unit {
+	font-size: 1.5rem;
+
+	@media (--tablet-up) {
+		font-size: 1.75rem;
+	}
+}
+
+.stat-label {
+	font-size: 0.875rem;
+	line-height: 1.4;
+}
+
+/* Light theme */
+.theme-light {
+	& .stat-value {
+		color: var(--hops-navy);
+	}
+
+	& .stat-unit {
+		color: var(--hops-orange);
+	}
+
+	& .stat-label {
+		color: var(--hops-text-muted);
+		text-transform: uppercase;
+		letter-spacing: 0.1em;
+	}
+}
+
+/* Dark theme */
+.theme-dark {
+	& .stat-value {
+		color: var(--hops-orange);
+	}
+
+	& .stat-unit {
+		color: rgba(255, 255, 255, 0.5);
+	}
+
+	& .stat-label {
+		color: rgba(255, 255, 255, 0.7);
+	}
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/TabNav.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/TabNav.svelte
new file mode 100644
index 00000000..452f3da8
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/TabNav.svelte
@@ -0,0 +1,136 @@
+<script lang="ts">
+	interface Tab {
+		icon?: string;
+		label: string;
+	}
+
+	interface Props {
+		/** Tab items */
+		tabs: Tab[];
+		/** Currently active tab index */
+		activeIndex?: number;
+		/** Color theme */
+		theme?: 'light' | 'dark';
+		/** Callback when tab changes */
+		onChange?: (index: number) => void;
+	}
+
+	let {
+		tabs,
+		activeIndex = $bindable(0),
+		theme = 'dark',
+		onChange
+	}: Props = $props();
+
+	function selectTab(index: number) {
+		activeIndex = index;
+		onChange?.(index);
+	}
+</script>
+
+<div class="tab-nav theme-{theme}">
+	{#each tabs as tab, i (i)}
+		<button
+			class="tab"
+			class:active={activeIndex === i}
+			onclick={() => selectTab(i)}
+		>
+			{#if tab.icon}
+				<span class="tab-icon">{tab.icon}</span>
+			{/if}
+			<span class="tab-label">{tab.label}</span>
+		</button>
+	{/each}
+</div>
+
+<style>
+.tab-nav {
+	display: flex;
+	justify-content: center;
+	gap: 0.5rem;
+	margin-bottom: 2.5rem;
+	flex-wrap: wrap;
+}
+
+.tab {
+	display: flex;
+	align-items: center;
+	gap: 0.5rem;
+	padding: 0.625rem 1rem;
+	border-radius: 100px;
+	font-family: var(--font-body);
+	font-size: 0.8rem;
+	font-weight: 600;
+	cursor: pointer;
+	transition: all 0.3s var(--ease-out-expo);
+}
+
+.tab-icon {
+	font-size: 1.25rem;
+	line-height: 1;
+}
+
+.tab-label {
+	display: none;
+	white-space: nowrap;
+
+	@media (--tablet-up) {
+		display: inline;
+	}
+}
+
+@media (--tablet-up) {
+	.tab {
+		padding: 0.75rem 1.25rem;
+		font-size: 0.9rem;
+	}
+
+	.tab-icon {
+		font-size: 1.1rem;
+	}
+}
+
+/* Dark theme */
+.theme-dark {
+	& .tab {
+		background: rgba(255, 255, 255, 0.05);
+		border: 1px solid rgba(255, 255, 255, 0.1);
+		color: rgba(255, 255, 255, 0.7);
+
+		&:hover {
+			background: rgba(255, 255, 255, 0.1);
+			border-color: rgba(255, 255, 255, 0.2);
+			color: var(--hops-text-inverse);
+		}
+
+		&.active {
+			background: var(--hops-orange);
+			border-color: var(--hops-orange);
+			color: var(--hops-text-inverse);
+			box-shadow: 0 4px 20px rgba(230, 154, 45, 0.4);
+		}
+	}
+}
+
+/* Light theme */
+.theme-light {
+	& .tab {
+		background: var(--hops-bg-white);
+		border: 1px solid var(--hops-border);
+		color: var(--hops-text-secondary);
+
+		&:hover {
+			background: var(--hops-bg-cream);
+			border-color: var(--hops-border-strong);
+			color: var(--hops-navy);
+		}
+
+		&.active {
+			background: var(--hops-orange);
+			border-color: var(--hops-orange);
+			color: var(--hops-text-inverse);
+			box-shadow: 0 4px 20px rgba(230, 154, 45, 0.3);
+		}
+	}
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/TransitionWrapper.svelte b/tests/e2e-ui/ui/src/lib/components/shared/ui/TransitionWrapper.svelte
new file mode 100644
index 00000000..77a96e9a
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/TransitionWrapper.svelte
@@ -0,0 +1,33 @@
+<script lang="ts">
+	import { fly } from 'svelte/transition';
+	import { cubicOut } from 'svelte/easing';
+	import { page } from '$app/state';
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Page content */
+		children: Snippet;
+	}
+
+	let { children }: Props = $props();
+
+	// Use pathname as key for transitions
+	const key = $derived(page.url.pathname);
+</script>
+
+{#key key}
+	<div
+		class="page"
+		in:fly={{ y: 20, duration: 300, delay: 150, easing: cubicOut }}
+		out:fly={{ y: -10, duration: 150, easing: cubicOut }}
+	>
+		{@render children()}
+	</div>
+{/key}
+
+<style>
+.page {
+	min-height: 100vh;
+	will-change: transform, opacity;
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/lib/components/shared/ui/index.ts b/tests/e2e-ui/ui/src/lib/components/shared/ui/index.ts
new file mode 100644
index 00000000..f238c8ba
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/components/shared/ui/index.ts
@@ -0,0 +1,17 @@
+export { default as Alert } from './Alert.svelte';
+export { default as Badge } from './Badge.svelte';
+export { default as Button } from './Button.svelte';
+export { default as Card } from './Card.svelte';
+export { default as CodeWindow } from './CodeWindow.svelte';
+export { default as FeatureList } from './FeatureList.svelte';
+export { default as IconBox } from './IconBox.svelte';
+export { default as MarketingSection } from './MarketingSection.svelte';
+export { default as Page } from './Page.svelte';
+export { default as ResponsiveGrid } from './ResponsiveGrid.svelte';
+export { default as Section } from './Section.svelte';
+export { default as SectionHeader } from './SectionHeader.svelte';
+export { default as SectionLabel } from './SectionLabel.svelte';
+export { default as SimplePage } from './SimplePage.svelte';
+export { default as StatBlock } from './StatBlock.svelte';
+export { default as TabNav } from './TabNav.svelte';
+export { default as TransitionWrapper } from './TransitionWrapper.svelte';
diff --git a/tests/e2e-ui/ui/src/lib/generated/admin/commands.ts b/tests/e2e-ui/ui/src/lib/generated/admin/commands.ts
new file mode 100644
index 00000000..a25b5c54
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/admin/commands.ts
@@ -0,0 +1,1869 @@
+/** GENERATED by dctl client. Do not edit. */
+
+import {
+  createReplicaCommandRuntime,
+  prepareReplicaCommand
+} from '@hops-ops/distributed/replica';
+
+import type {
+  DistributedReplica,
+  PrepareReplicaCommandOptions,
+  ReplicaCommandArtifact,
+  ReplicaCommandRuntime,
+  ReplicaCommandRuntimeOptions,
+  ReplicaCommandTransport,
+  ReplicaPreparedCommand,
+  ReplicaValue
+} from '@hops-ops/distributed/replica';
+
+import { COMMAND_STATUS } from './protocol.js';
+
+export type Command_blob_games_move_Input = {
+  readonly "direction": string;
+  readonly "game_id": string;
+};
+
+export type Command_blob_games_move_Output = {
+  readonly "current_level": number;
+  readonly "current_level_completed": boolean;
+  readonly "game_id": string;
+  readonly "map_json": string;
+  readonly "owner_id": string;
+  readonly "player_dead": boolean;
+  readonly "score": number;
+  readonly "status": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_blob_games_move: ReplicaCommandArtifact<Command_blob_games_move_Input, Command_blob_games_move_Output> = {
+  "consistency": "projected",
+  "directProjection": {
+    "changeEpoch": "e2e-ui-blob-v1",
+    "identityFields": [
+      "game_id"
+    ],
+    "model": "BlobGameView",
+    "topology": {
+      "digest": "sha256:259f4c8941653467b4ff9bbfcf7b4d1dcf490be96fc60499e7debf78a3beeef0",
+      "name": "project_blob",
+      "version": 1
+    }
+  },
+  "document": "mutation Client_blob_games_move($commandId: ID!, $input: BlobMoveInput!) { blob_games_move(commandId: $commandId, input: $input) { current_level current_level_completed game_id map_json owner_id player_dead score status } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "direction",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "game_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "BlobMoveInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "blob_games_move",
+  "name": "blob.move",
+  "operationHash": "sha256:6e3c6c00474e126a3fce6b671cd8a06eed988546f161793d39a08cc784ae49c7",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "json_number_precision_limited",
+          "itemNullable": false,
+          "list": false,
+          "name": "current_level",
+          "nullable": false,
+          "typeName": "BigInt"
+        },
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "current_level_completed",
+          "nullable": false,
+          "typeName": "Boolean"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "game_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "map_json",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "owner_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "player_dead",
+          "nullable": false,
+          "typeName": "Boolean"
+        },
+        {
+          "codec": "json_number_precision_limited",
+          "itemNullable": false,
+          "list": false,
+          "name": "score",
+          "nullable": false,
+          "typeName": "BigInt"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "BlobGameView"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:6e3c6c00474e126a3fce6b671cd8a06eed988546f161793d39a08cc784ae49c7",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui-admin",
+      "roles": [
+        "admin"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "blob_games"
+    ],
+    "models": [
+      "BlobGameView"
+    ],
+    "relationships": [],
+    "required": true,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_blob_games_move(
+  input: Command_blob_games_move_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_blob_games_move_Input, Command_blob_games_move_Output> {
+  return prepareReplicaCommand(Command_blob_games_move, input, options);
+}
+
+export type Command_blob_games_start_Input = {
+  readonly "game_id": string;
+};
+
+export type Command_blob_games_start_Output = {
+  readonly "current_level": number;
+  readonly "current_level_completed": boolean;
+  readonly "game_id": string;
+  readonly "map_json": string;
+  readonly "owner_id": string;
+  readonly "player_dead": boolean;
+  readonly "score": number;
+  readonly "status": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_blob_games_start: ReplicaCommandArtifact<Command_blob_games_start_Input, Command_blob_games_start_Output> = {
+  "consistency": "projected",
+  "directProjection": {
+    "changeEpoch": "e2e-ui-blob-v1",
+    "identityFields": [
+      "game_id"
+    ],
+    "model": "BlobGameView",
+    "topology": {
+      "digest": "sha256:259f4c8941653467b4ff9bbfcf7b4d1dcf490be96fc60499e7debf78a3beeef0",
+      "name": "project_blob",
+      "version": 1
+    }
+  },
+  "document": "mutation Client_blob_games_start($commandId: ID!, $input: BlobStartInput!) { blob_games_start(commandId: $commandId, input: $input) { current_level current_level_completed game_id map_json owner_id player_dead score status } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "game_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "BlobStartInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "blob_games_start",
+  "name": "blob.start",
+  "operationHash": "sha256:4b7ab56a38aec41d21809801ecefc5d7039a09e53a350187152c72a305de1567",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "json_number_precision_limited",
+          "itemNullable": false,
+          "list": false,
+          "name": "current_level",
+          "nullable": false,
+          "typeName": "BigInt"
+        },
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "current_level_completed",
+          "nullable": false,
+          "typeName": "Boolean"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "game_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "map_json",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "owner_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "player_dead",
+          "nullable": false,
+          "typeName": "Boolean"
+        },
+        {
+          "codec": "json_number_precision_limited",
+          "itemNullable": false,
+          "list": false,
+          "name": "score",
+          "nullable": false,
+          "typeName": "BigInt"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "BlobGameView"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:4b7ab56a38aec41d21809801ecefc5d7039a09e53a350187152c72a305de1567",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui-admin",
+      "roles": [
+        "admin"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "blob_games"
+    ],
+    "models": [
+      "BlobGameView"
+    ],
+    "relationships": [],
+    "required": true,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_blob_games_start(
+  input: Command_blob_games_start_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_blob_games_start_Input, Command_blob_games_start_Output> {
+  return prepareReplicaCommand(Command_blob_games_start, input, options);
+}
+
+export type Command_blob_games_start_level_Input = {
+  readonly "game_id": string;
+};
+
+export type Command_blob_games_start_level_Output = {
+  readonly "current_level": number;
+  readonly "current_level_completed": boolean;
+  readonly "game_id": string;
+  readonly "map_json": string;
+  readonly "owner_id": string;
+  readonly "player_dead": boolean;
+  readonly "score": number;
+  readonly "status": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_blob_games_start_level: ReplicaCommandArtifact<Command_blob_games_start_level_Input, Command_blob_games_start_level_Output> = {
+  "consistency": "projected",
+  "directProjection": {
+    "changeEpoch": "e2e-ui-blob-v1",
+    "identityFields": [
+      "game_id"
+    ],
+    "model": "BlobGameView",
+    "topology": {
+      "digest": "sha256:259f4c8941653467b4ff9bbfcf7b4d1dcf490be96fc60499e7debf78a3beeef0",
+      "name": "project_blob",
+      "version": 1
+    }
+  },
+  "document": "mutation Client_blob_games_start_level($commandId: ID!, $input: BlobStartLevelInput!) { blob_games_start_level(commandId: $commandId, input: $input) { current_level current_level_completed game_id map_json owner_id player_dead score status } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "game_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "BlobStartLevelInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "blob_games_start_level",
+  "name": "blob.start_level",
+  "operationHash": "sha256:37c108a568f62e7391a03728555d7013bb717f14d1957a5c3527151fd70093bf",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "json_number_precision_limited",
+          "itemNullable": false,
+          "list": false,
+          "name": "current_level",
+          "nullable": false,
+          "typeName": "BigInt"
+        },
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "current_level_completed",
+          "nullable": false,
+          "typeName": "Boolean"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "game_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "map_json",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "owner_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "player_dead",
+          "nullable": false,
+          "typeName": "Boolean"
+        },
+        {
+          "codec": "json_number_precision_limited",
+          "itemNullable": false,
+          "list": false,
+          "name": "score",
+          "nullable": false,
+          "typeName": "BigInt"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "BlobGameView"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:37c108a568f62e7391a03728555d7013bb717f14d1957a5c3527151fd70093bf",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui-admin",
+      "roles": [
+        "admin"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "blob_games"
+    ],
+    "models": [
+      "BlobGameView"
+    ],
+    "relationships": [],
+    "required": true,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_blob_games_start_level(
+  input: Command_blob_games_start_level_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_blob_games_start_level_Input, Command_blob_games_start_level_Output> {
+  return prepareReplicaCommand(Command_blob_games_start_level, input, options);
+}
+
+export type Command_chat_messages_post_Input = {
+  readonly "body": string;
+  readonly "created_at": string;
+  readonly "message_id": string;
+  readonly "room_id": string;
+};
+
+export type Command_chat_messages_post_Output = {
+  readonly "author_id": string;
+  readonly "body": string;
+  readonly "created_at": string;
+  readonly "message_id": string;
+  readonly "room_id": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_chat_messages_post: ReplicaCommandArtifact<Command_chat_messages_post_Input, Command_chat_messages_post_Output> = {
+  "confirmations": {
+    "expected": [
+      {
+        "key": {
+          "fields": [
+            {
+              "field": "message_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "message_id"
+                ]
+              }
+            }
+          ]
+        },
+        "model": "ChatMessageView",
+        "projector": "project_chat"
+      }
+    ],
+    "fallback": "revalidate",
+    "kind": "finite",
+    "version": 1
+  },
+  "consistency": "fact",
+  "document": "mutation Client_chat_messages_post($commandId: ID!, $input: ChatPostInput!) { chat_messages_post(commandId: $commandId, input: $input) { author_id body created_at message_id room_id } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [
+      {
+        "fields": [
+          {
+            "field": "author_id",
+            "value": {
+              "kind": "trusted_preset",
+              "name": "x-user-id"
+            }
+          },
+          {
+            "field": "body",
+            "value": {
+              "kind": "input",
+              "path": [
+                "body"
+              ]
+            }
+          },
+          {
+            "field": "created_at",
+            "value": {
+              "kind": "input",
+              "path": [
+                "created_at"
+              ]
+            }
+          },
+          {
+            "field": "room_id",
+            "value": {
+              "kind": "input",
+              "path": [
+                "room_id"
+              ]
+            }
+          }
+        ],
+        "key": {
+          "fields": [
+            {
+              "field": "message_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "message_id"
+                ]
+              }
+            }
+          ]
+        },
+        "kind": "upsert",
+        "model": "ChatMessageView"
+      }
+    ],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "body",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "created_at",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "message_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "room_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "ChatPostInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "chat_messages_post",
+  "name": "chat.post",
+  "operationHash": "sha256:838e5ccb79daebb523ea3c634bea27077bcea191feabb86e45923470a7b9373d",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "author_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "body",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "created_at",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "message_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "room_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "ChatPostPayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:838e5ccb79daebb523ea3c634bea27077bcea191feabb86e45923470a7b9373d",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui-admin",
+      "roles": [
+        "admin"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "chat_messages"
+    ],
+    "models": [
+      "ChatMessageView"
+    ],
+    "relationships": [],
+    "required": false,
+    "version": 1
+  },
+  "trustedPresets": [
+    {
+      "codec": "string",
+      "name": "x-user-id"
+    }
+  ],
+  "version": 1
+};
+
+export function prepareCommand_chat_messages_post(
+  input: Command_chat_messages_post_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_chat_messages_post_Input, Command_chat_messages_post_Output> {
+  return prepareReplicaCommand(Command_chat_messages_post, input, options);
+}
+
+export type Command_todos_archive_Input = {
+  readonly "todo_id": string;
+};
+
+export type Command_todos_archive_Output = {
+  readonly "status": string;
+  readonly "todo_id": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_todos_archive: ReplicaCommandArtifact<Command_todos_archive_Input, Command_todos_archive_Output> = {
+  "confirmations": {
+    "expected": [
+      {
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "model": "TodoView",
+        "projector": "project_todo"
+      }
+    ],
+    "fallback": "revalidate",
+    "kind": "finite",
+    "version": 1
+  },
+  "consistency": "fact",
+  "document": "mutation Client_todos_archive($commandId: ID!, $input: TodoArchiveInput!) { todos_archive(commandId: $commandId, input: $input) { status todo_id } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [
+      {
+        "fields": [
+          {
+            "field": "status",
+            "value": {
+              "kind": "constant",
+              "value": "archived"
+            }
+          }
+        ],
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "kind": "patch",
+        "model": "TodoView"
+      }
+    ],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoArchiveInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "todos_archive",
+  "name": "todo.archive",
+  "operationHash": "sha256:fb2d3a14933841a966836ced65263a9ba2413d5aed8c582d31165aaee6e632ab",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoStatusPayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:fb2d3a14933841a966836ced65263a9ba2413d5aed8c582d31165aaee6e632ab",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui-admin",
+      "roles": [
+        "admin"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todos"
+    ],
+    "models": [
+      "TodoView"
+    ],
+    "relationships": [],
+    "required": false,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_todos_archive(
+  input: Command_todos_archive_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_todos_archive_Input, Command_todos_archive_Output> {
+  return prepareReplicaCommand(Command_todos_archive, input, options);
+}
+
+export type Command_todos_complete_Input = {
+  readonly "todo_id": string;
+};
+
+export type Command_todos_complete_Output = {
+  readonly "status": string;
+  readonly "todo_id": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_todos_complete: ReplicaCommandArtifact<Command_todos_complete_Input, Command_todos_complete_Output> = {
+  "confirmations": {
+    "expected": [
+      {
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "model": "TodoView",
+        "projector": "project_todo"
+      }
+    ],
+    "fallback": "revalidate",
+    "kind": "finite",
+    "version": 1
+  },
+  "consistency": "fact",
+  "document": "mutation Client_todos_complete($commandId: ID!, $input: TodoCompleteInput!) { todos_complete(commandId: $commandId, input: $input) { status todo_id } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [
+      {
+        "fields": [
+          {
+            "field": "status",
+            "value": {
+              "kind": "constant",
+              "value": "completed"
+            }
+          }
+        ],
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "kind": "patch",
+        "model": "TodoView"
+      }
+    ],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoCompleteInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "todos_complete",
+  "name": "todo.complete",
+  "operationHash": "sha256:9b8185c835d3308bda308593486767731acaf4b084a7962b4b17e3e2e319922c",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoStatusPayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:9b8185c835d3308bda308593486767731acaf4b084a7962b4b17e3e2e319922c",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui-admin",
+      "roles": [
+        "admin"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todos"
+    ],
+    "models": [
+      "TodoView"
+    ],
+    "relationships": [],
+    "required": false,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_todos_complete(
+  input: Command_todos_complete_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_todos_complete_Input, Command_todos_complete_Output> {
+  return prepareReplicaCommand(Command_todos_complete, input, options);
+}
+
+export type Command_todos_create_Input = {
+  readonly "title": string;
+  readonly "todo_id"?: string;
+};
+
+export type Command_todos_create_Output = {
+  readonly "owner_id": string;
+  readonly "status": string;
+  readonly "title": string;
+  readonly "todo_id": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_todos_create: ReplicaCommandArtifact<Command_todos_create_Input, Command_todos_create_Output> = {
+  "confirmations": {
+    "expected": [
+      {
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "model": "TodoView",
+        "projector": "project_todo"
+      }
+    ],
+    "fallback": "revalidate",
+    "kind": "finite",
+    "version": 1
+  },
+  "consistency": "fact",
+  "document": "mutation Client_todos_create($commandId: ID!, $input: TodoCreateInput!) { todos_create(commandId: $commandId, input: $input) { owner_id status title todo_id } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [
+      {
+        "fields": [
+          {
+            "field": "owner_id",
+            "value": {
+              "kind": "trusted_preset",
+              "name": "x-user-id"
+            }
+          },
+          {
+            "field": "status",
+            "value": {
+              "kind": "constant",
+              "value": "open"
+            }
+          },
+          {
+            "field": "title",
+            "value": {
+              "kind": "input",
+              "path": [
+                "title"
+              ]
+            }
+          }
+        ],
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "kind": "upsert",
+        "model": "TodoView"
+      }
+    ],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "title",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoCreateInput"
+    },
+    "kind": "object"
+  },
+  "inputDefaults": {
+    "defaults": [
+      {
+        "generator": "uuid_v7",
+        "path": [
+          "todo_id"
+        ]
+      }
+    ],
+    "version": 1
+  },
+  "mutationField": "todos_create",
+  "name": "todo.create",
+  "operationHash": "sha256:187e72cd747aaa13ac0362942d73085a5166401f8cc3a188badeb3e7fa50cacb",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "owner_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "title",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoCreatePayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:187e72cd747aaa13ac0362942d73085a5166401f8cc3a188badeb3e7fa50cacb",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui-admin",
+      "roles": [
+        "admin"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todos"
+    ],
+    "models": [
+      "TodoView"
+    ],
+    "relationships": [],
+    "required": false,
+    "version": 1
+  },
+  "trustedPresets": [
+    {
+      "codec": "string",
+      "name": "x-user-id"
+    }
+  ],
+  "version": 1
+};
+
+export function prepareCommand_todos_create(
+  input: Command_todos_create_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_todos_create_Input, Command_todos_create_Output> {
+  return prepareReplicaCommand(Command_todos_create, input, options);
+}
+
+export type Command_todos_force_archive_Input = {
+  readonly "todo_id": string;
+};
+
+export type Command_todos_force_archive_Output = {
+  readonly "archived_by": string;
+  readonly "owner_id": string;
+  readonly "status": string;
+  readonly "todo_id": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_todos_force_archive: ReplicaCommandArtifact<Command_todos_force_archive_Input, Command_todos_force_archive_Output> = {
+  "confirmations": {
+    "expected": [
+      {
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "model": "TodoView",
+        "projector": "project_todo"
+      }
+    ],
+    "fallback": "revalidate",
+    "kind": "finite",
+    "version": 1
+  },
+  "consistency": "fact",
+  "document": "mutation Client_todos_force_archive($commandId: ID!, $input: TodoForceArchiveInput!) { todos_force_archive(commandId: $commandId, input: $input) { archived_by owner_id status todo_id } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [
+      {
+        "fields": [
+          {
+            "field": "status",
+            "value": {
+              "kind": "constant",
+              "value": "archived"
+            }
+          }
+        ],
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "kind": "patch",
+        "model": "TodoView"
+      }
+    ],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoForceArchiveInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "todos_force_archive",
+  "name": "todo.force_archive",
+  "operationHash": "sha256:50d0d05ce63148fd7c4041478b57656e927f500f938798df61bf7ade6b53ccbf",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "archived_by",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "owner_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoForceArchivePayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:50d0d05ce63148fd7c4041478b57656e927f500f938798df61bf7ade6b53ccbf",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui-admin",
+      "roles": [
+        "admin"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todos"
+    ],
+    "models": [
+      "TodoView"
+    ],
+    "relationships": [],
+    "required": false,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_todos_force_archive(
+  input: Command_todos_force_archive_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_todos_force_archive_Input, Command_todos_force_archive_Output> {
+  return prepareReplicaCommand(Command_todos_force_archive, input, options);
+}
+
+export type Command_todos_rename_Input = {
+  readonly "title": string;
+  readonly "todo_id": string;
+};
+
+export type Command_todos_rename_Output = {
+  readonly "status": string;
+  readonly "title": string;
+  readonly "todo_id": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_todos_rename: ReplicaCommandArtifact<Command_todos_rename_Input, Command_todos_rename_Output> = {
+  "confirmations": {
+    "expected": [
+      {
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "model": "TodoView",
+        "projector": "project_todo"
+      }
+    ],
+    "fallback": "revalidate",
+    "kind": "finite",
+    "version": 1
+  },
+  "consistency": "fact",
+  "document": "mutation Client_todos_rename($commandId: ID!, $input: TodoRenameInput!) { todos_rename(commandId: $commandId, input: $input) { status title todo_id } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [
+      {
+        "fields": [
+          {
+            "field": "title",
+            "value": {
+              "kind": "input",
+              "path": [
+                "title"
+              ]
+            }
+          }
+        ],
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "kind": "patch",
+        "model": "TodoView"
+      }
+    ],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "title",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoRenameInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "todos_rename",
+  "name": "todo.rename",
+  "operationHash": "sha256:a3e8a5ceae1a0f2c33863a4f2bf377a95b79da2157a619eb7823aa845ef681c3",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "title",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoRenamePayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:a3e8a5ceae1a0f2c33863a4f2bf377a95b79da2157a619eb7823aa845ef681c3",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui-admin",
+      "roles": [
+        "admin"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todos"
+    ],
+    "models": [
+      "TodoView"
+    ],
+    "relationships": [],
+    "required": false,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_todos_rename(
+  input: Command_todos_rename_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_todos_rename_Input, Command_todos_rename_Output> {
+  return prepareReplicaCommand(Command_todos_rename, input, options);
+}
+
+export type Command_todos_reopen_Input = {
+  readonly "todo_id": string;
+};
+
+export type Command_todos_reopen_Output = {
+  readonly "status": string;
+  readonly "todo_id": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_todos_reopen: ReplicaCommandArtifact<Command_todos_reopen_Input, Command_todos_reopen_Output> = {
+  "confirmations": {
+    "expected": [
+      {
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "model": "TodoView",
+        "projector": "project_todo"
+      }
+    ],
+    "fallback": "revalidate",
+    "kind": "finite",
+    "version": 1
+  },
+  "consistency": "fact",
+  "document": "mutation Client_todos_reopen($commandId: ID!, $input: TodoReopenInput!) { todos_reopen(commandId: $commandId, input: $input) { status todo_id } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [
+      {
+        "fields": [
+          {
+            "field": "status",
+            "value": {
+              "kind": "constant",
+              "value": "open"
+            }
+          }
+        ],
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "kind": "patch",
+        "model": "TodoView"
+      }
+    ],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoReopenInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "todos_reopen",
+  "name": "todo.reopen",
+  "operationHash": "sha256:04531ace98fd3ee5e652761abbcb6ebd745d5ff6ed0ad100030f935335c5a35e",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoStatusPayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:04531ace98fd3ee5e652761abbcb6ebd745d5ff6ed0ad100030f935335c5a35e",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui-admin",
+      "roles": [
+        "admin"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todos"
+    ],
+    "models": [
+      "TodoView"
+    ],
+    "relationships": [],
+    "required": false,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_todos_reopen(
+  input: Command_todos_reopen_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_todos_reopen_Input, Command_todos_reopen_Output> {
+  return prepareReplicaCommand(Command_todos_reopen, input, options);
+}
+
+export const COMMAND_ARTIFACTS = [Command_blob_games_move, Command_blob_games_start, Command_blob_games_start_level, Command_chat_messages_post, Command_todos_archive, Command_todos_complete, Command_todos_create, Command_todos_force_archive, Command_todos_rename, Command_todos_reopen] as const;
+
+/** Inspectable command inventory consumed by the generated binding factory. */
+export const COMMANDS = {
+  "blob.move": Command_blob_games_move,
+  "blob.start": Command_blob_games_start,
+  "blob.start_level": Command_blob_games_start_level,
+  "chat.post": Command_chat_messages_post,
+  "todo.archive": Command_todos_archive,
+  "todo.complete": Command_todos_complete,
+  "todo.create": Command_todos_create,
+  "todo.force_archive": Command_todos_force_archive,
+  "todo.rename": Command_todos_rename,
+  "todo.reopen": Command_todos_reopen
+} as const;
+
+/** Runtime owning the generated callable command surface and its causal lifecycle. */
+export type GeneratedCommandRuntime = ReplicaCommandRuntime<typeof COMMANDS>;
+
+/** Callable `commands.x(input)` surface exposed by GeneratedCommandRuntime. */
+export type GeneratedCommands = GeneratedCommandRuntime['commands'];
+
+/** Runtime options excluding compiler-owned protocol authority. */
+export type GeneratedCommandRuntimeOptions = Omit<ReplicaCommandRuntimeOptions, 'status'>;
+
+/**
+ * Bind this generated command inventory to a replica and transport.
+ * Keep the returned runtime when `observeResult` or `dispose` is needed.
+ */
+export function createCommands(
+  replica: DistributedReplica,
+  transport: ReplicaCommandTransport,
+  options?: GeneratedCommandRuntimeOptions
+): GeneratedCommandRuntime {
+  return createReplicaCommandRuntime(replica, transport, COMMANDS, {
+    ...options,
+    status: COMMAND_STATUS
+  });
+}
+
+/** Projector topology used by command confirmation/effect runtimes. */
+export const PROJECTOR_ARTIFACTS = [
+  {
+    "version": 1,
+    "name": "project_blob",
+    "facts": [],
+    "models": [
+      "BlobGameView"
+    ],
+    "dependencies": [
+      "blob_games"
+    ],
+    "causal_confirmation": false
+  },
+  {
+    "version": 1,
+    "name": "project_chat",
+    "facts": [
+      "chat_message.posted"
+    ],
+    "models": [
+      "ChatMessageView"
+    ],
+    "dependencies": [
+      "chat_messages"
+    ],
+    "causal_confirmation": true
+  },
+  {
+    "version": 1,
+    "name": "project_todo",
+    "facts": [
+      "todo.archived",
+      "todo.completed",
+      "todo.created",
+      "todo.force_archived",
+      "todo.renamed",
+      "todo.reopened"
+    ],
+    "models": [
+      "TodoView"
+    ],
+    "dependencies": [
+      "todos"
+    ],
+    "causal_confirmation": true
+  }
+] as const;
+
+export type GeneratedCommandArtifact = (typeof COMMAND_ARTIFACTS)[number];
diff --git a/tests/e2e-ui/ui/src/lib/generated/admin/index.ts b/tests/e2e-ui/ui/src/lib/generated/admin/index.ts
new file mode 100644
index 00000000..9668ec33
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/admin/index.ts
@@ -0,0 +1,5 @@
+/** GENERATED public entrypoint. */
+export * from './commands.js';
+export * from './protocol.js';
+export * from './routes.js';
+export * from './operations/admin-all-todos.js';
diff --git a/tests/e2e-ui/ui/src/lib/generated/admin/manifest.json b/tests/e2e-ui/ui/src/lib/generated/admin/manifest.json
new file mode 100644
index 00000000..e422c18e
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/admin/manifest.json
@@ -0,0 +1,48 @@
+{
+  "compiler_manifest_version": 1,
+  "distributed_manifest_version": 1,
+  "protocol_version": 1,
+  "service_id": "e2e-ui",
+  "surface": {
+    "kind": "application",
+    "name": "e2e-ui-admin",
+    "roles": [
+      "admin"
+    ]
+  },
+  "schema_fingerprint": "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+  "protocol_fingerprint": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+  "scalar_codecs": {
+    "BigInt": "json_number_precision_limited",
+    "Boolean": "boolean",
+    "Bytea": "base64",
+    "Float": "float64",
+    "ID": "string",
+    "Int": "int32",
+    "JSON": "json",
+    "String": "string",
+    "Timestamptz": "string_unvalidated_timestamp"
+  },
+  "commands_requiring_revalidation": [
+    "blob.move",
+    "blob.start",
+    "blob.start_level"
+  ],
+  "operations": [
+    {
+      "name": "AdminAllTodos",
+      "source_path": "src/routes/admin/+page.graphql",
+      "module_path": "operations/admin-all-todos.ts",
+      "export_name": "Operation_AdminAllTodos",
+      "operation_hash": "sha256:3436d01402748d8c4f2f5d2ff5f1173fea89786c8e902de09a24bd03596eaf27"
+    }
+  ],
+  "routes": [
+    {
+      "operation": "AdminAllTodos",
+      "route": "/admin",
+      "source_path": "src/routes/admin/+page.graphql",
+      "discovery": "convention"
+    }
+  ]
+}
diff --git a/tests/e2e-ui/ui/src/lib/generated/admin/operations/admin-all-todos.ts b/tests/e2e-ui/ui/src/lib/generated/admin/operations/admin-all-todos.ts
new file mode 100644
index 00000000..ddea0925
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/admin/operations/admin-all-todos.ts
@@ -0,0 +1,282 @@
+/** GENERATED by dctl client. Do not edit. */
+import type { ReplicaOperationArtifact } from '@hops-ops/distributed/replica';
+
+export type Operation_AdminAllTodos_Variables = Record<string, never>;
+
+export type Operation_AdminAllTodos_Data = {
+  readonly "todos": readonly {
+    readonly "todo_id": string;
+    readonly "owner_id": string;
+    readonly "title": string;
+    readonly "status": string;
+  }[];
+};
+
+/** Exact canonical query bytes sent to the server. */
+export const Operation_AdminAllTodosDocument = "query AdminAllTodos {\n  todos(limit: 100, order_by: [{status: asc}, {owner_id: asc}, {todo_id: asc}]) {\n    todo_id\n    owner_id\n    title\n    status\n    _distributed_typename: __typename\n  }\n}\n";
+
+/** Typed normalized-replica operation descriptor. */
+export const Operation_AdminAllTodos: ReplicaOperationArtifact<Operation_AdminAllTodos_Data, Operation_AdminAllTodos_Variables> = {
+  "id": "sha256:3436d01402748d8c4f2f5d2ff5f1173fea89786c8e902de09a24bd03596eaf27",
+  "document": "query AdminAllTodos {\n  todos(limit: 100, order_by: [{status: asc}, {owner_id: asc}, {todo_id: asc}]) {\n    todo_id\n    owner_id\n    title\n    status\n    _distributed_typename: __typename\n  }\n}\n",
+  "source": {
+    "path": "src/routes/admin/+page.graphql",
+    "line": 2,
+    "column": 1
+  },
+  "variableCodec": {
+    "version": 1,
+    "limits": {
+      "maxDepth": 8,
+      "maxBoolWidth": 256,
+      "maxInList": 1000
+    },
+    "variables": {},
+    "inputs": {}
+  },
+  "roots": [
+    {
+      "responseKey": "todos",
+      "field": "todos",
+      "cardinality": "many",
+      "nullable": false,
+      "arguments": {
+        "limit": {
+          "kind": "literal",
+          "value": 100
+        },
+        "order_by": {
+          "kind": "literal",
+          "value": [
+            {
+              "status": "asc"
+            },
+            {
+              "owner_id": "asc"
+            },
+            {
+              "todo_id": "asc"
+            }
+          ]
+        }
+      },
+      "dependencies": [
+        "todos"
+      ],
+      "coverage": {
+        "kind": "offset",
+        "offsetArgument": "offset",
+        "limitArgument": "limit",
+        "defaultLimit": 100,
+        "maxLimit": 1000
+      },
+      "filter": {
+        "fields": [
+          {
+            "field": "owner_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "status",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "title",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "todo_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          }
+        ],
+        "relationships": [],
+        "rowPolicy": {
+          "kind": "unrestricted"
+        }
+      },
+      "order": {
+        "input": {
+          "kind": "literal",
+          "value": [
+            {
+              "status": "asc"
+            },
+            {
+              "owner_id": "asc"
+            },
+            {
+              "todo_id": "asc"
+            }
+          ]
+        },
+        "fields": [
+          {
+            "field": "owner_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "status",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "title",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "todo_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          }
+        ],
+        "tieBreakers": [
+          {
+            "field": "todo_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          }
+        ]
+      },
+      "pagination": {
+        "kind": "offset",
+        "insert": "local",
+        "delete": "local",
+        "reorder": "local",
+        "stableUpdate": "local"
+      },
+      "selection": {
+        "typename": "TodoView",
+        "storage": {
+          "kind": "normalized",
+          "model": "TodoView",
+          "identityFields": [
+            "todo_id"
+          ]
+        },
+        "members": [
+          {
+            "kind": "scalar",
+            "responseKey": "todo_id",
+            "field": "todo_id",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "owner_id",
+            "field": "owner_id",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "title",
+            "field": "title",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "status",
+            "field": "status",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_typename",
+            "field": "__typename",
+            "codec": "string",
+            "nullable": false,
+            "expose": false
+          }
+        ]
+      }
+    }
+  ],
+  "protocol": {
+    "version": 1,
+    "schemaHash": "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui-admin",
+      "roles": [
+        "admin"
+      ]
+    },
+    "operation": "sha256:3436d01402748d8c4f2f5d2ff5f1173fea89786c8e902de09a24bd03596eaf27",
+    "trustedPresets": [
+      {
+        "name": "x-user-id",
+        "codec": "string"
+      }
+    ]
+  }
+};
diff --git a/tests/e2e-ui/ui/src/lib/generated/admin/protocol.ts b/tests/e2e-ui/ui/src/lib/generated/admin/protocol.ts
new file mode 100644
index 00000000..399735a9
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/admin/protocol.ts
@@ -0,0 +1,51 @@
+/** GENERATED by dctl client. Exact framework-owned operation bytes. */
+
+import type { ReplicaCommandStatusArtifact } from '@hops-ops/distributed/replica';
+
+export const CLIENT_PROTOCOL = {
+	version: 1,
+	serviceId: "e2e-ui",
+	schemaHash: "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+	protocolHash: "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+	surface: {"kind":"application","name":"e2e-ui-admin","roles":["admin"]},
+	trustedPresets: [
+  {
+    "name": "x-user-id",
+    "codec": "string"
+  }
+],
+	operations: {
+  "version": 1,
+  "command_status": {
+    "name": "Distributed_CommandStatus",
+    "operation": "query Distributed_CommandStatus($commandId: ID!) { commandStatus(commandId: $commandId) { state } }",
+    "operation_hash": "sha256:eb3ce6a8b306d935fc9f3d6f071804ce3ec415d209594c04015fa35b080282ef"
+  }
+}
+} as const;
+
+/** Exact compiler-owned operation used to recover ambiguous command outcomes. */
+export const COMMAND_STATUS: ReplicaCommandStatusArtifact = {
+  "document": "query Distributed_CommandStatus($commandId: ID!) { commandStatus(commandId: $commandId) { state } }",
+  "name": "Distributed_CommandStatus",
+  "operationHash": "sha256:eb3ce6a8b306d935fc9f3d6f071804ce3ec415d209594c04015fa35b080282ef",
+  "protocol": {
+    "operation": "sha256:eb3ce6a8b306d935fc9f3d6f071804ce3ec415d209594c04015fa35b080282ef",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:d68acc1bf021f40b10fe434ce06c22bfb97f23352ab500376adc2aab6b61385e",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui-admin",
+      "roles": [
+        "admin"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  }
+};
diff --git a/tests/e2e-ui/ui/src/lib/generated/admin/routes.ts b/tests/e2e-ui/ui/src/lib/generated/admin/routes.ts
new file mode 100644
index 00000000..e0085fd9
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/admin/routes.ts
@@ -0,0 +1,19 @@
+import { Operation_AdminAllTodos } from './operations/admin-all-todos.js';
+
+/** GENERATED framework-neutral `@load` ownership plan. */
+export const DISTRIBUTED_ROUTES = [
+  {
+    "operation": "AdminAllTodos",
+    "route": "/admin",
+    "source_path": "src/routes/admin/+page.graphql",
+    "discovery": "convention"
+  }
+] as const;
+
+/** Static route-to-artifact bindings consumed by framework SSR adapters. */
+export const DISTRIBUTED_ROUTE_OPERATIONS = [
+  { plan: DISTRIBUTED_ROUTES[0], artifact: Operation_AdminAllTodos }
+] as const;
+
+export type DistributedRoutePlan = (typeof DISTRIBUTED_ROUTES)[number];
+export type DistributedRouteOperation = (typeof DISTRIBUTED_ROUTE_OPERATIONS)[number];
diff --git a/tests/e2e-ui/ui/src/lib/generated/admin/sveltekit.ts b/tests/e2e-ui/ui/src/lib/generated/admin/sveltekit.ts
new file mode 100644
index 00000000..32bf6fa3
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/admin/sveltekit.ts
@@ -0,0 +1,46 @@
+/** GENERATED by dctl client. Do not edit. */
+
+import {
+  createDistributedSvelteKit,
+  defineDistributedSvelteKitOperation,
+  provideDistributedSvelteKitClient,
+  useDistributedSvelteKitCommands
+} from '@hops-ops/distributed/sveltekit';
+
+import type {
+  CreateDistributedSvelteKitOptions,
+  DistributedSvelteKitClient
+} from '@hops-ops/distributed/sveltekit';
+
+import { createCommands as createGeneratedCommands } from './commands.js';
+import type { GeneratedCommands as ServiceGeneratedCommands } from './commands.js';
+
+export type GeneratedCommands = ServiceGeneratedCommands;
+
+import { Operation_AdminAllTodos as DistributedOperation_0 } from './operations/admin-all-todos.js';
+
+/** Inspectable framework-neutral artifacts remain available here. */
+export * from './index.js';
+
+/** Tree-local Svelte binding for the generated `AdminAllTodos` artifact. */
+export const AdminAllTodos = defineDistributedSvelteKitOperation(DistributedOperation_0);
+
+/**
+ * Create and install one component-tree/request-local generated client.
+ * No client or command proxy is retained by this module.
+ */
+export function provideDistributed(
+  options: Omit<CreateDistributedSvelteKitOptions<GeneratedCommands>, 'createCommands'>
+): DistributedSvelteKitClient<GeneratedCommands> {
+  return provideDistributedSvelteKitClient(
+    createDistributedSvelteKit<GeneratedCommands>({
+      ...options,
+      createCommands: createGeneratedCommands
+    })
+  );
+}
+
+/** Resolve the nearest generated command surface during component initialization. */
+export function useCommands(): GeneratedCommands {
+  return useDistributedSvelteKitCommands<GeneratedCommands>();
+}
diff --git a/tests/e2e-ui/ui/src/lib/generated/user/commands.ts b/tests/e2e-ui/ui/src/lib/generated/user/commands.ts
new file mode 100644
index 00000000..40647ad8
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/user/commands.ts
@@ -0,0 +1,1707 @@
+/** GENERATED by dctl client. Do not edit. */
+
+import {
+  createReplicaCommandRuntime,
+  prepareReplicaCommand
+} from '@hops-ops/distributed/replica';
+
+import type {
+  DistributedReplica,
+  PrepareReplicaCommandOptions,
+  ReplicaCommandArtifact,
+  ReplicaCommandRuntime,
+  ReplicaCommandRuntimeOptions,
+  ReplicaCommandTransport,
+  ReplicaPreparedCommand,
+  ReplicaValue
+} from '@hops-ops/distributed/replica';
+
+import { COMMAND_STATUS } from './protocol.js';
+
+export type Command_blob_games_move_Input = {
+  readonly "direction": string;
+  readonly "game_id": string;
+};
+
+export type Command_blob_games_move_Output = {
+  readonly "current_level": number;
+  readonly "current_level_completed": boolean;
+  readonly "game_id": string;
+  readonly "map_json": string;
+  readonly "owner_id": string;
+  readonly "player_dead": boolean;
+  readonly "score": number;
+  readonly "status": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_blob_games_move: ReplicaCommandArtifact<Command_blob_games_move_Input, Command_blob_games_move_Output> = {
+  "consistency": "projected",
+  "directProjection": {
+    "changeEpoch": "e2e-ui-blob-v1",
+    "identityFields": [
+      "game_id"
+    ],
+    "model": "BlobGameView",
+    "topology": {
+      "digest": "sha256:259f4c8941653467b4ff9bbfcf7b4d1dcf490be96fc60499e7debf78a3beeef0",
+      "name": "project_blob",
+      "version": 1
+    }
+  },
+  "document": "mutation Client_blob_games_move($commandId: ID!, $input: BlobMoveInput!) { blob_games_move(commandId: $commandId, input: $input) { current_level current_level_completed game_id map_json owner_id player_dead score status } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "direction",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "game_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "BlobMoveInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "blob_games_move",
+  "name": "blob.move",
+  "operationHash": "sha256:6e3c6c00474e126a3fce6b671cd8a06eed988546f161793d39a08cc784ae49c7",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "json_number_precision_limited",
+          "itemNullable": false,
+          "list": false,
+          "name": "current_level",
+          "nullable": false,
+          "typeName": "BigInt"
+        },
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "current_level_completed",
+          "nullable": false,
+          "typeName": "Boolean"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "game_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "map_json",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "owner_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "player_dead",
+          "nullable": false,
+          "typeName": "Boolean"
+        },
+        {
+          "codec": "json_number_precision_limited",
+          "itemNullable": false,
+          "list": false,
+          "name": "score",
+          "nullable": false,
+          "typeName": "BigInt"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "BlobGameView"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:6e3c6c00474e126a3fce6b671cd8a06eed988546f161793d39a08cc784ae49c7",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui",
+      "roles": [
+        "admin",
+        "user"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "blob_games"
+    ],
+    "models": [
+      "BlobGameView"
+    ],
+    "relationships": [],
+    "required": true,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_blob_games_move(
+  input: Command_blob_games_move_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_blob_games_move_Input, Command_blob_games_move_Output> {
+  return prepareReplicaCommand(Command_blob_games_move, input, options);
+}
+
+export type Command_blob_games_start_Input = {
+  readonly "game_id": string;
+};
+
+export type Command_blob_games_start_Output = {
+  readonly "current_level": number;
+  readonly "current_level_completed": boolean;
+  readonly "game_id": string;
+  readonly "map_json": string;
+  readonly "owner_id": string;
+  readonly "player_dead": boolean;
+  readonly "score": number;
+  readonly "status": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_blob_games_start: ReplicaCommandArtifact<Command_blob_games_start_Input, Command_blob_games_start_Output> = {
+  "consistency": "projected",
+  "directProjection": {
+    "changeEpoch": "e2e-ui-blob-v1",
+    "identityFields": [
+      "game_id"
+    ],
+    "model": "BlobGameView",
+    "topology": {
+      "digest": "sha256:259f4c8941653467b4ff9bbfcf7b4d1dcf490be96fc60499e7debf78a3beeef0",
+      "name": "project_blob",
+      "version": 1
+    }
+  },
+  "document": "mutation Client_blob_games_start($commandId: ID!, $input: BlobStartInput!) { blob_games_start(commandId: $commandId, input: $input) { current_level current_level_completed game_id map_json owner_id player_dead score status } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "game_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "BlobStartInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "blob_games_start",
+  "name": "blob.start",
+  "operationHash": "sha256:4b7ab56a38aec41d21809801ecefc5d7039a09e53a350187152c72a305de1567",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "json_number_precision_limited",
+          "itemNullable": false,
+          "list": false,
+          "name": "current_level",
+          "nullable": false,
+          "typeName": "BigInt"
+        },
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "current_level_completed",
+          "nullable": false,
+          "typeName": "Boolean"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "game_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "map_json",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "owner_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "player_dead",
+          "nullable": false,
+          "typeName": "Boolean"
+        },
+        {
+          "codec": "json_number_precision_limited",
+          "itemNullable": false,
+          "list": false,
+          "name": "score",
+          "nullable": false,
+          "typeName": "BigInt"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "BlobGameView"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:4b7ab56a38aec41d21809801ecefc5d7039a09e53a350187152c72a305de1567",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui",
+      "roles": [
+        "admin",
+        "user"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "blob_games"
+    ],
+    "models": [
+      "BlobGameView"
+    ],
+    "relationships": [],
+    "required": true,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_blob_games_start(
+  input: Command_blob_games_start_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_blob_games_start_Input, Command_blob_games_start_Output> {
+  return prepareReplicaCommand(Command_blob_games_start, input, options);
+}
+
+export type Command_blob_games_start_level_Input = {
+  readonly "game_id": string;
+};
+
+export type Command_blob_games_start_level_Output = {
+  readonly "current_level": number;
+  readonly "current_level_completed": boolean;
+  readonly "game_id": string;
+  readonly "map_json": string;
+  readonly "owner_id": string;
+  readonly "player_dead": boolean;
+  readonly "score": number;
+  readonly "status": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_blob_games_start_level: ReplicaCommandArtifact<Command_blob_games_start_level_Input, Command_blob_games_start_level_Output> = {
+  "consistency": "projected",
+  "directProjection": {
+    "changeEpoch": "e2e-ui-blob-v1",
+    "identityFields": [
+      "game_id"
+    ],
+    "model": "BlobGameView",
+    "topology": {
+      "digest": "sha256:259f4c8941653467b4ff9bbfcf7b4d1dcf490be96fc60499e7debf78a3beeef0",
+      "name": "project_blob",
+      "version": 1
+    }
+  },
+  "document": "mutation Client_blob_games_start_level($commandId: ID!, $input: BlobStartLevelInput!) { blob_games_start_level(commandId: $commandId, input: $input) { current_level current_level_completed game_id map_json owner_id player_dead score status } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "game_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "BlobStartLevelInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "blob_games_start_level",
+  "name": "blob.start_level",
+  "operationHash": "sha256:37c108a568f62e7391a03728555d7013bb717f14d1957a5c3527151fd70093bf",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "json_number_precision_limited",
+          "itemNullable": false,
+          "list": false,
+          "name": "current_level",
+          "nullable": false,
+          "typeName": "BigInt"
+        },
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "current_level_completed",
+          "nullable": false,
+          "typeName": "Boolean"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "game_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "map_json",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "owner_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "boolean",
+          "itemNullable": false,
+          "list": false,
+          "name": "player_dead",
+          "nullable": false,
+          "typeName": "Boolean"
+        },
+        {
+          "codec": "json_number_precision_limited",
+          "itemNullable": false,
+          "list": false,
+          "name": "score",
+          "nullable": false,
+          "typeName": "BigInt"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "BlobGameView"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:37c108a568f62e7391a03728555d7013bb717f14d1957a5c3527151fd70093bf",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui",
+      "roles": [
+        "admin",
+        "user"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "blob_games"
+    ],
+    "models": [
+      "BlobGameView"
+    ],
+    "relationships": [],
+    "required": true,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_blob_games_start_level(
+  input: Command_blob_games_start_level_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_blob_games_start_level_Input, Command_blob_games_start_level_Output> {
+  return prepareReplicaCommand(Command_blob_games_start_level, input, options);
+}
+
+export type Command_chat_messages_post_Input = {
+  readonly "body": string;
+  readonly "created_at": string;
+  readonly "message_id": string;
+  readonly "room_id": string;
+};
+
+export type Command_chat_messages_post_Output = {
+  readonly "author_id": string;
+  readonly "body": string;
+  readonly "created_at": string;
+  readonly "message_id": string;
+  readonly "room_id": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_chat_messages_post: ReplicaCommandArtifact<Command_chat_messages_post_Input, Command_chat_messages_post_Output> = {
+  "confirmations": {
+    "expected": [
+      {
+        "key": {
+          "fields": [
+            {
+              "field": "message_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "message_id"
+                ]
+              }
+            }
+          ]
+        },
+        "model": "ChatMessageView",
+        "projector": "project_chat"
+      }
+    ],
+    "fallback": "revalidate",
+    "kind": "finite",
+    "version": 1
+  },
+  "consistency": "fact",
+  "document": "mutation Client_chat_messages_post($commandId: ID!, $input: ChatPostInput!) { chat_messages_post(commandId: $commandId, input: $input) { author_id body created_at message_id room_id } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [
+      {
+        "fields": [
+          {
+            "field": "author_id",
+            "value": {
+              "kind": "trusted_preset",
+              "name": "x-user-id"
+            }
+          },
+          {
+            "field": "body",
+            "value": {
+              "kind": "input",
+              "path": [
+                "body"
+              ]
+            }
+          },
+          {
+            "field": "created_at",
+            "value": {
+              "kind": "input",
+              "path": [
+                "created_at"
+              ]
+            }
+          },
+          {
+            "field": "room_id",
+            "value": {
+              "kind": "input",
+              "path": [
+                "room_id"
+              ]
+            }
+          }
+        ],
+        "key": {
+          "fields": [
+            {
+              "field": "message_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "message_id"
+                ]
+              }
+            }
+          ]
+        },
+        "kind": "upsert",
+        "model": "ChatMessageView"
+      }
+    ],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "body",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "created_at",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "message_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "room_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "ChatPostInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "chat_messages_post",
+  "name": "chat.post",
+  "operationHash": "sha256:838e5ccb79daebb523ea3c634bea27077bcea191feabb86e45923470a7b9373d",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "author_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "body",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "created_at",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "message_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "room_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "ChatPostPayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:838e5ccb79daebb523ea3c634bea27077bcea191feabb86e45923470a7b9373d",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui",
+      "roles": [
+        "admin",
+        "user"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "chat_messages"
+    ],
+    "models": [
+      "ChatMessageView"
+    ],
+    "relationships": [],
+    "required": false,
+    "version": 1
+  },
+  "trustedPresets": [
+    {
+      "codec": "string",
+      "name": "x-user-id"
+    }
+  ],
+  "version": 1
+};
+
+export function prepareCommand_chat_messages_post(
+  input: Command_chat_messages_post_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_chat_messages_post_Input, Command_chat_messages_post_Output> {
+  return prepareReplicaCommand(Command_chat_messages_post, input, options);
+}
+
+export type Command_todos_archive_Input = {
+  readonly "todo_id": string;
+};
+
+export type Command_todos_archive_Output = {
+  readonly "status": string;
+  readonly "todo_id": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_todos_archive: ReplicaCommandArtifact<Command_todos_archive_Input, Command_todos_archive_Output> = {
+  "confirmations": {
+    "expected": [
+      {
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "model": "TodoView",
+        "projector": "project_todo"
+      }
+    ],
+    "fallback": "revalidate",
+    "kind": "finite",
+    "version": 1
+  },
+  "consistency": "fact",
+  "document": "mutation Client_todos_archive($commandId: ID!, $input: TodoArchiveInput!) { todos_archive(commandId: $commandId, input: $input) { status todo_id } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [
+      {
+        "fields": [
+          {
+            "field": "status",
+            "value": {
+              "kind": "constant",
+              "value": "archived"
+            }
+          }
+        ],
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "kind": "patch",
+        "model": "TodoView"
+      }
+    ],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoArchiveInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "todos_archive",
+  "name": "todo.archive",
+  "operationHash": "sha256:fb2d3a14933841a966836ced65263a9ba2413d5aed8c582d31165aaee6e632ab",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoStatusPayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:fb2d3a14933841a966836ced65263a9ba2413d5aed8c582d31165aaee6e632ab",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui",
+      "roles": [
+        "admin",
+        "user"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todos"
+    ],
+    "models": [
+      "TodoView"
+    ],
+    "relationships": [],
+    "required": false,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_todos_archive(
+  input: Command_todos_archive_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_todos_archive_Input, Command_todos_archive_Output> {
+  return prepareReplicaCommand(Command_todos_archive, input, options);
+}
+
+export type Command_todos_complete_Input = {
+  readonly "todo_id": string;
+};
+
+export type Command_todos_complete_Output = {
+  readonly "status": string;
+  readonly "todo_id": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_todos_complete: ReplicaCommandArtifact<Command_todos_complete_Input, Command_todos_complete_Output> = {
+  "confirmations": {
+    "expected": [
+      {
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "model": "TodoView",
+        "projector": "project_todo"
+      }
+    ],
+    "fallback": "revalidate",
+    "kind": "finite",
+    "version": 1
+  },
+  "consistency": "fact",
+  "document": "mutation Client_todos_complete($commandId: ID!, $input: TodoCompleteInput!) { todos_complete(commandId: $commandId, input: $input) { status todo_id } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [
+      {
+        "fields": [
+          {
+            "field": "status",
+            "value": {
+              "kind": "constant",
+              "value": "completed"
+            }
+          }
+        ],
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "kind": "patch",
+        "model": "TodoView"
+      }
+    ],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoCompleteInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "todos_complete",
+  "name": "todo.complete",
+  "operationHash": "sha256:9b8185c835d3308bda308593486767731acaf4b084a7962b4b17e3e2e319922c",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoStatusPayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:9b8185c835d3308bda308593486767731acaf4b084a7962b4b17e3e2e319922c",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui",
+      "roles": [
+        "admin",
+        "user"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todos"
+    ],
+    "models": [
+      "TodoView"
+    ],
+    "relationships": [],
+    "required": false,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_todos_complete(
+  input: Command_todos_complete_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_todos_complete_Input, Command_todos_complete_Output> {
+  return prepareReplicaCommand(Command_todos_complete, input, options);
+}
+
+export type Command_todos_create_Input = {
+  readonly "title": string;
+  readonly "todo_id"?: string;
+};
+
+export type Command_todos_create_Output = {
+  readonly "owner_id": string;
+  readonly "status": string;
+  readonly "title": string;
+  readonly "todo_id": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_todos_create: ReplicaCommandArtifact<Command_todos_create_Input, Command_todos_create_Output> = {
+  "confirmations": {
+    "expected": [
+      {
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "model": "TodoView",
+        "projector": "project_todo"
+      }
+    ],
+    "fallback": "revalidate",
+    "kind": "finite",
+    "version": 1
+  },
+  "consistency": "fact",
+  "document": "mutation Client_todos_create($commandId: ID!, $input: TodoCreateInput!) { todos_create(commandId: $commandId, input: $input) { owner_id status title todo_id } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [
+      {
+        "fields": [
+          {
+            "field": "owner_id",
+            "value": {
+              "kind": "trusted_preset",
+              "name": "x-user-id"
+            }
+          },
+          {
+            "field": "status",
+            "value": {
+              "kind": "constant",
+              "value": "open"
+            }
+          },
+          {
+            "field": "title",
+            "value": {
+              "kind": "input",
+              "path": [
+                "title"
+              ]
+            }
+          }
+        ],
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "kind": "upsert",
+        "model": "TodoView"
+      }
+    ],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "title",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoCreateInput"
+    },
+    "kind": "object"
+  },
+  "inputDefaults": {
+    "defaults": [
+      {
+        "generator": "uuid_v7",
+        "path": [
+          "todo_id"
+        ]
+      }
+    ],
+    "version": 1
+  },
+  "mutationField": "todos_create",
+  "name": "todo.create",
+  "operationHash": "sha256:187e72cd747aaa13ac0362942d73085a5166401f8cc3a188badeb3e7fa50cacb",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "owner_id",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "title",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoCreatePayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:187e72cd747aaa13ac0362942d73085a5166401f8cc3a188badeb3e7fa50cacb",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui",
+      "roles": [
+        "admin",
+        "user"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todos"
+    ],
+    "models": [
+      "TodoView"
+    ],
+    "relationships": [],
+    "required": false,
+    "version": 1
+  },
+  "trustedPresets": [
+    {
+      "codec": "string",
+      "name": "x-user-id"
+    }
+  ],
+  "version": 1
+};
+
+export function prepareCommand_todos_create(
+  input: Command_todos_create_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_todos_create_Input, Command_todos_create_Output> {
+  return prepareReplicaCommand(Command_todos_create, input, options);
+}
+
+export type Command_todos_rename_Input = {
+  readonly "title": string;
+  readonly "todo_id": string;
+};
+
+export type Command_todos_rename_Output = {
+  readonly "status": string;
+  readonly "title": string;
+  readonly "todo_id": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_todos_rename: ReplicaCommandArtifact<Command_todos_rename_Input, Command_todos_rename_Output> = {
+  "confirmations": {
+    "expected": [
+      {
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "model": "TodoView",
+        "projector": "project_todo"
+      }
+    ],
+    "fallback": "revalidate",
+    "kind": "finite",
+    "version": 1
+  },
+  "consistency": "fact",
+  "document": "mutation Client_todos_rename($commandId: ID!, $input: TodoRenameInput!) { todos_rename(commandId: $commandId, input: $input) { status title todo_id } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [
+      {
+        "fields": [
+          {
+            "field": "title",
+            "value": {
+              "kind": "input",
+              "path": [
+                "title"
+              ]
+            }
+          }
+        ],
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "kind": "patch",
+        "model": "TodoView"
+      }
+    ],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "title",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoRenameInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "todos_rename",
+  "name": "todo.rename",
+  "operationHash": "sha256:a3e8a5ceae1a0f2c33863a4f2bf377a95b79da2157a619eb7823aa845ef681c3",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "title",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoRenamePayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:a3e8a5ceae1a0f2c33863a4f2bf377a95b79da2157a619eb7823aa845ef681c3",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui",
+      "roles": [
+        "admin",
+        "user"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todos"
+    ],
+    "models": [
+      "TodoView"
+    ],
+    "relationships": [],
+    "required": false,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_todos_rename(
+  input: Command_todos_rename_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_todos_rename_Input, Command_todos_rename_Output> {
+  return prepareReplicaCommand(Command_todos_rename, input, options);
+}
+
+export type Command_todos_reopen_Input = {
+  readonly "todo_id": string;
+};
+
+export type Command_todos_reopen_Output = {
+  readonly "status": string;
+  readonly "todo_id": string;
+};
+
+/** Exact typed causal command descriptor and full mutation bytes. */
+export const Command_todos_reopen: ReplicaCommandArtifact<Command_todos_reopen_Input, Command_todos_reopen_Output> = {
+  "confirmations": {
+    "expected": [
+      {
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "model": "TodoView",
+        "projector": "project_todo"
+      }
+    ],
+    "fallback": "revalidate",
+    "kind": "finite",
+    "version": 1
+  },
+  "consistency": "fact",
+  "document": "mutation Client_todos_reopen($commandId: ID!, $input: TodoReopenInput!) { todos_reopen(commandId: $commandId, input: $input) { status todo_id } }",
+  "effects": {
+    "fallback": "revalidate",
+    "operations": [
+      {
+        "fields": [
+          {
+            "field": "status",
+            "value": {
+              "kind": "constant",
+              "value": "open"
+            }
+          }
+        ],
+        "key": {
+          "fields": [
+            {
+              "field": "todo_id",
+              "value": {
+                "kind": "input",
+                "path": [
+                  "todo_id"
+                ]
+              }
+            }
+          ]
+        },
+        "kind": "patch",
+        "model": "TodoView"
+      }
+    ],
+    "version": 1
+  },
+  "input": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoReopenInput"
+    },
+    "kind": "object"
+  },
+  "mutationField": "todos_reopen",
+  "name": "todo.reopen",
+  "operationHash": "sha256:04531ace98fd3ee5e652761abbcb6ebd745d5ff6ed0ad100030f935335c5a35e",
+  "output": {
+    "definition": {
+      "fields": [
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "status",
+          "nullable": false,
+          "typeName": "String"
+        },
+        {
+          "codec": "string",
+          "itemNullable": false,
+          "list": false,
+          "name": "todo_id",
+          "nullable": false,
+          "typeName": "String"
+        }
+      ],
+      "name": "TodoStatusPayload"
+    },
+    "kind": "object"
+  },
+  "protocol": {
+    "operation": "sha256:04531ace98fd3ee5e652761abbcb6ebd745d5ff6ed0ad100030f935335c5a35e",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui",
+      "roles": [
+        "admin",
+        "user"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  },
+  "revalidation": {
+    "dependencies": [
+      "todos"
+    ],
+    "models": [
+      "TodoView"
+    ],
+    "relationships": [],
+    "required": false,
+    "version": 1
+  },
+  "version": 1
+};
+
+export function prepareCommand_todos_reopen(
+  input: Command_todos_reopen_Input,
+  options?: PrepareReplicaCommandOptions
+): ReplicaPreparedCommand<Command_todos_reopen_Input, Command_todos_reopen_Output> {
+  return prepareReplicaCommand(Command_todos_reopen, input, options);
+}
+
+export const COMMAND_ARTIFACTS = [Command_blob_games_move, Command_blob_games_start, Command_blob_games_start_level, Command_chat_messages_post, Command_todos_archive, Command_todos_complete, Command_todos_create, Command_todos_rename, Command_todos_reopen] as const;
+
+/** Inspectable command inventory consumed by the generated binding factory. */
+export const COMMANDS = {
+  "blob.move": Command_blob_games_move,
+  "blob.start": Command_blob_games_start,
+  "blob.start_level": Command_blob_games_start_level,
+  "chat.post": Command_chat_messages_post,
+  "todo.archive": Command_todos_archive,
+  "todo.complete": Command_todos_complete,
+  "todo.create": Command_todos_create,
+  "todo.rename": Command_todos_rename,
+  "todo.reopen": Command_todos_reopen
+} as const;
+
+/** Runtime owning the generated callable command surface and its causal lifecycle. */
+export type GeneratedCommandRuntime = ReplicaCommandRuntime<typeof COMMANDS>;
+
+/** Callable `commands.x(input)` surface exposed by GeneratedCommandRuntime. */
+export type GeneratedCommands = GeneratedCommandRuntime['commands'];
+
+/** Runtime options excluding compiler-owned protocol authority. */
+export type GeneratedCommandRuntimeOptions = Omit<ReplicaCommandRuntimeOptions, 'status'>;
+
+/**
+ * Bind this generated command inventory to a replica and transport.
+ * Keep the returned runtime when `observeResult` or `dispose` is needed.
+ */
+export function createCommands(
+  replica: DistributedReplica,
+  transport: ReplicaCommandTransport,
+  options?: GeneratedCommandRuntimeOptions
+): GeneratedCommandRuntime {
+  return createReplicaCommandRuntime(replica, transport, COMMANDS, {
+    ...options,
+    status: COMMAND_STATUS
+  });
+}
+
+/** Projector topology used by command confirmation/effect runtimes. */
+export const PROJECTOR_ARTIFACTS = [
+  {
+    "version": 1,
+    "name": "project_blob",
+    "facts": [],
+    "models": [
+      "BlobGameView"
+    ],
+    "dependencies": [
+      "blob_games"
+    ],
+    "causal_confirmation": false
+  },
+  {
+    "version": 1,
+    "name": "project_chat",
+    "facts": [
+      "chat_message.posted"
+    ],
+    "models": [
+      "ChatMessageView"
+    ],
+    "dependencies": [
+      "chat_messages"
+    ],
+    "causal_confirmation": true
+  },
+  {
+    "version": 1,
+    "name": "project_todo",
+    "facts": [
+      "todo.archived",
+      "todo.completed",
+      "todo.created",
+      "todo.force_archived",
+      "todo.renamed",
+      "todo.reopened"
+    ],
+    "models": [
+      "TodoView"
+    ],
+    "dependencies": [
+      "todos"
+    ],
+    "causal_confirmation": true
+  }
+] as const;
+
+export type GeneratedCommandArtifact = (typeof COMMAND_ARTIFACTS)[number];
diff --git a/tests/e2e-ui/ui/src/lib/generated/user/index.ts b/tests/e2e-ui/ui/src/lib/generated/user/index.ts
new file mode 100644
index 00000000..d57c86b6
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/user/index.ts
@@ -0,0 +1,7 @@
+/** GENERATED public entrypoint. */
+export * from './commands.js';
+export * from './protocol.js';
+export * from './routes.js';
+export * from './operations/blob-games.js';
+export * from './operations/chat-messages.js';
+export * from './operations/todos.js';
diff --git a/tests/e2e-ui/ui/src/lib/generated/user/manifest.json b/tests/e2e-ui/ui/src/lib/generated/user/manifest.json
new file mode 100644
index 00000000..08b932b2
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/user/manifest.json
@@ -0,0 +1,76 @@
+{
+  "compiler_manifest_version": 1,
+  "distributed_manifest_version": 1,
+  "protocol_version": 1,
+  "service_id": "e2e-ui",
+  "surface": {
+    "kind": "application",
+    "name": "e2e-ui",
+    "roles": [
+      "admin",
+      "user"
+    ]
+  },
+  "schema_fingerprint": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+  "protocol_fingerprint": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+  "scalar_codecs": {
+    "BigInt": "json_number_precision_limited",
+    "Boolean": "boolean",
+    "Bytea": "base64",
+    "Float": "float64",
+    "ID": "string",
+    "Int": "int32",
+    "JSON": "json",
+    "String": "string",
+    "Timestamptz": "string_unvalidated_timestamp"
+  },
+  "commands_requiring_revalidation": [
+    "blob.move",
+    "blob.start",
+    "blob.start_level"
+  ],
+  "operations": [
+    {
+      "name": "BlobGames",
+      "source_path": "src/routes/blob/[[gameId]]/+page.graphql",
+      "module_path": "operations/blob-games.ts",
+      "export_name": "Operation_BlobGames",
+      "operation_hash": "sha256:a4fa7bd07cd0202f399c6d82a9ee79e67586c5a65ee3a4098b2d84e8ef6ed4fa"
+    },
+    {
+      "name": "ChatMessages",
+      "source_path": "src/routes/chat/+page.graphql",
+      "module_path": "operations/chat-messages.ts",
+      "export_name": "Operation_ChatMessages",
+      "operation_hash": "sha256:54dd3bd2142cf20a0bcc28d632fbd6cfc69f1d6d9ff94268a90865fd5a56a552",
+      "live_operation_hash": "sha256:3d894c6412e9408d178ad11030c0ed1f8db0066216e70131dae3f61fb1be81b4"
+    },
+    {
+      "name": "Todos",
+      "source_path": "src/routes/todos/+page.graphql",
+      "module_path": "operations/todos.ts",
+      "export_name": "Operation_Todos",
+      "operation_hash": "sha256:df906cbf75f2d5c11256c816a3a3726f34689e5d1a57f198484396c8c3803030"
+    }
+  ],
+  "routes": [
+    {
+      "operation": "BlobGames",
+      "route": "/blob/[[gameId]]",
+      "source_path": "src/routes/blob/[[gameId]]/+page.graphql",
+      "discovery": "convention"
+    },
+    {
+      "operation": "ChatMessages",
+      "route": "/chat",
+      "source_path": "src/routes/chat/+page.graphql",
+      "discovery": "convention"
+    },
+    {
+      "operation": "Todos",
+      "route": "/todos",
+      "source_path": "src/routes/todos/+page.graphql",
+      "discovery": "convention"
+    }
+  ]
+}
diff --git a/tests/e2e-ui/ui/src/lib/generated/user/operations/blob-games.ts b/tests/e2e-ui/ui/src/lib/generated/user/operations/blob-games.ts
new file mode 100644
index 00000000..602cacf7
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/user/operations/blob-games.ts
@@ -0,0 +1,499 @@
+/** GENERATED by dctl client. Do not edit. */
+import type { ReplicaOperationArtifact } from '@hops-ops/distributed/replica';
+
+export type Operation_BlobGames_Variables = Record<string, never>;
+
+export type Operation_BlobGames_Data = {
+  readonly "blob_games": readonly {
+    readonly "game_id": string;
+    readonly "owner_id": string;
+    readonly "score": number;
+    readonly "player_dead": boolean;
+    readonly "current_level": number;
+    readonly "current_level_completed": boolean;
+    readonly "map_json": string;
+    readonly "status": string;
+    readonly "owner": {
+      readonly "user_id": string;
+      readonly "display_name": string;
+      readonly "email": string;
+      readonly "status": string;
+    };
+  }[];
+};
+
+/** Exact canonical query bytes sent to the server. */
+export const Operation_BlobGamesDocument = "query BlobGames {\n  blob_games(order_by: [{game_id: asc}]) {\n    game_id\n    owner_id\n    score\n    player_dead\n    current_level\n    current_level_completed\n    map_json\n    status\n    owner {\n      user_id\n      display_name\n      email\n      status\n      _distributed_typename: __typename\n    }\n    _distributed_typename: __typename\n  }\n}\n";
+
+/** Typed normalized-replica operation descriptor. */
+export const Operation_BlobGames: ReplicaOperationArtifact<Operation_BlobGames_Data, Operation_BlobGames_Variables> = {
+  "id": "sha256:a4fa7bd07cd0202f399c6d82a9ee79e67586c5a65ee3a4098b2d84e8ef6ed4fa",
+  "document": "query BlobGames {\n  blob_games(order_by: [{game_id: asc}]) {\n    game_id\n    owner_id\n    score\n    player_dead\n    current_level\n    current_level_completed\n    map_json\n    status\n    owner {\n      user_id\n      display_name\n      email\n      status\n      _distributed_typename: __typename\n    }\n    _distributed_typename: __typename\n  }\n}\n",
+  "source": {
+    "path": "src/routes/blob/[[gameId]]/+page.graphql",
+    "line": 2,
+    "column": 1
+  },
+  "variableCodec": {
+    "version": 1,
+    "limits": {
+      "maxDepth": 8,
+      "maxBoolWidth": 256,
+      "maxInList": 1000
+    },
+    "variables": {},
+    "inputs": {}
+  },
+  "roots": [
+    {
+      "responseKey": "blob_games",
+      "field": "blob_games",
+      "cardinality": "many",
+      "nullable": false,
+      "arguments": {
+        "order_by": {
+          "kind": "literal",
+          "value": [
+            {
+              "game_id": "asc"
+            }
+          ]
+        }
+      },
+      "dependencies": [
+        "blob_games"
+      ],
+      "coverage": {
+        "kind": "offset",
+        "offsetArgument": "offset",
+        "limitArgument": "limit",
+        "defaultLimit": 100,
+        "maxLimit": 1000
+      },
+      "filter": {
+        "fields": [
+          {
+            "field": "current_level",
+            "scalar": "BigInt",
+            "codec": "json_number_precision_limited",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_in",
+              "_is_null",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "current_level_completed",
+            "scalar": "Boolean",
+            "codec": "boolean",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_in",
+              "_is_null",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "game_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "map_json",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "owner_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "player_dead",
+            "scalar": "Boolean",
+            "codec": "boolean",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_in",
+              "_is_null",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "score",
+            "scalar": "BigInt",
+            "codec": "json_number_precision_limited",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_in",
+              "_is_null",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "status",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          }
+        ],
+        "relationships": [
+          {
+            "field": "owner",
+            "targetModel": "AuthUserView",
+            "kind": "belongs_to",
+            "keyMapping": {
+              "kind": "direct",
+              "local": [
+                "owner_id"
+              ],
+              "remote": [
+                "user_id"
+              ]
+            },
+            "maintenance": "local",
+            "dependencies": [
+              "auth_users",
+              "blob_games"
+            ]
+          }
+        ],
+        "rowPolicy": {
+          "kind": "server_only"
+        }
+      },
+      "order": {
+        "input": {
+          "kind": "literal",
+          "value": [
+            {
+              "game_id": "asc"
+            }
+          ]
+        },
+        "fields": [
+          {
+            "field": "current_level",
+            "scalar": "BigInt",
+            "codec": "json_number_precision_limited",
+            "nullable": false
+          },
+          {
+            "field": "current_level_completed",
+            "scalar": "Boolean",
+            "codec": "boolean",
+            "nullable": false
+          },
+          {
+            "field": "game_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "map_json",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "owner_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "player_dead",
+            "scalar": "Boolean",
+            "codec": "boolean",
+            "nullable": false
+          },
+          {
+            "field": "score",
+            "scalar": "BigInt",
+            "codec": "json_number_precision_limited",
+            "nullable": false
+          },
+          {
+            "field": "status",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          }
+        ],
+        "tieBreakers": [
+          {
+            "field": "game_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          }
+        ]
+      },
+      "pagination": {
+        "kind": "offset",
+        "insert": "local",
+        "delete": "local",
+        "reorder": "local",
+        "stableUpdate": "local"
+      },
+      "selection": {
+        "typename": "BlobGameView",
+        "storage": {
+          "kind": "normalized",
+          "model": "BlobGameView",
+          "identityFields": [
+            "game_id"
+          ]
+        },
+        "members": [
+          {
+            "kind": "scalar",
+            "responseKey": "game_id",
+            "field": "game_id",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "owner_id",
+            "field": "owner_id",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "score",
+            "field": "score",
+            "codec": "json_number_precision_limited",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "player_dead",
+            "field": "player_dead",
+            "codec": "boolean",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "current_level",
+            "field": "current_level",
+            "codec": "json_number_precision_limited",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "current_level_completed",
+            "field": "current_level_completed",
+            "codec": "boolean",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "map_json",
+            "field": "map_json",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "status",
+            "field": "status",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "branch",
+            "semantic": "relationship",
+            "responseKey": "owner",
+            "field": "owner",
+            "cardinality": "one",
+            "nullable": false,
+            "dependencies": [
+              "auth_users",
+              "blob_games"
+            ],
+            "coverage": {
+              "kind": "complete"
+            },
+            "relationship": {
+              "field": "owner",
+              "targetModel": "AuthUserView",
+              "kind": "belongs_to",
+              "keyMapping": {
+                "kind": "direct",
+                "local": [
+                  "owner_id"
+                ],
+                "remote": [
+                  "user_id"
+                ]
+              },
+              "maintenance": "local",
+              "dependencies": [
+                "auth_users",
+                "blob_games"
+              ]
+            },
+            "selection": {
+              "typename": "AuthUserView",
+              "storage": {
+                "kind": "normalized",
+                "model": "AuthUserView",
+                "identityFields": [
+                  "user_id"
+                ]
+              },
+              "members": [
+                {
+                  "kind": "scalar",
+                  "responseKey": "user_id",
+                  "field": "user_id",
+                  "codec": "string",
+                  "nullable": false
+                },
+                {
+                  "kind": "scalar",
+                  "responseKey": "display_name",
+                  "field": "display_name",
+                  "codec": "string",
+                  "nullable": false
+                },
+                {
+                  "kind": "scalar",
+                  "responseKey": "email",
+                  "field": "email",
+                  "codec": "string",
+                  "nullable": false
+                },
+                {
+                  "kind": "scalar",
+                  "responseKey": "status",
+                  "field": "status",
+                  "codec": "string",
+                  "nullable": false
+                },
+                {
+                  "kind": "scalar",
+                  "responseKey": "_distributed_typename",
+                  "field": "__typename",
+                  "codec": "string",
+                  "nullable": false,
+                  "expose": false
+                }
+              ]
+            }
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_typename",
+            "field": "__typename",
+            "codec": "string",
+            "nullable": false,
+            "expose": false
+          }
+        ]
+      }
+    }
+  ],
+  "protocol": {
+    "version": 1,
+    "schemaHash": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui",
+      "roles": [
+        "admin",
+        "user"
+      ]
+    },
+    "operation": "sha256:a4fa7bd07cd0202f399c6d82a9ee79e67586c5a65ee3a4098b2d84e8ef6ed4fa",
+    "trustedPresets": [
+      {
+        "name": "x-user-id",
+        "codec": "string"
+      }
+    ]
+  }
+};
diff --git a/tests/e2e-ui/ui/src/lib/generated/user/operations/chat-messages.ts b/tests/e2e-ui/ui/src/lib/generated/user/operations/chat-messages.ts
new file mode 100644
index 00000000..1dc551c3
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/user/operations/chat-messages.ts
@@ -0,0 +1,324 @@
+/** GENERATED by dctl client. Do not edit. */
+import type { ReplicaOperationArtifact } from '@hops-ops/distributed/replica';
+
+export type Operation_ChatMessages_Variables = Record<string, never>;
+
+export type Operation_ChatMessages_Data = {
+  readonly "chat_messages": readonly {
+    readonly "message_id": string;
+    readonly "room_id": string;
+    readonly "author_id": string;
+    readonly "body": string;
+    readonly "created_at": string;
+  }[];
+};
+
+/** Exact canonical query bytes sent to the server. */
+export const Operation_ChatMessagesDocument = "query ChatMessages {\n  chat_messages(where: {room_id: {_eq: \"lobby\"}}) {\n    message_id\n    room_id\n    author_id\n    body\n    created_at\n    _distributed_typename: __typename\n  }\n}\n";
+
+/** Typed normalized-replica operation descriptor. */
+export const Operation_ChatMessages: ReplicaOperationArtifact<Operation_ChatMessages_Data, Operation_ChatMessages_Variables> = {
+  "id": "sha256:54dd3bd2142cf20a0bcc28d632fbd6cfc69f1d6d9ff94268a90865fd5a56a552",
+  "document": "query ChatMessages {\n  chat_messages(where: {room_id: {_eq: \"lobby\"}}) {\n    message_id\n    room_id\n    author_id\n    body\n    created_at\n    _distributed_typename: __typename\n  }\n}\n",
+  "source": {
+    "path": "src/routes/chat/+page.graphql",
+    "line": 3,
+    "column": 1
+  },
+  "variableCodec": {
+    "version": 1,
+    "limits": {
+      "maxDepth": 8,
+      "maxBoolWidth": 256,
+      "maxInList": 1000
+    },
+    "variables": {},
+    "inputs": {}
+  },
+  "roots": [
+    {
+      "responseKey": "chat_messages",
+      "field": "chat_messages",
+      "cardinality": "many",
+      "nullable": false,
+      "arguments": {
+        "where": {
+          "kind": "literal",
+          "value": {
+            "room_id": {
+              "_eq": "lobby"
+            }
+          }
+        }
+      },
+      "dependencies": [
+        "chat_messages"
+      ],
+      "coverage": {
+        "kind": "offset",
+        "offsetArgument": "offset",
+        "limitArgument": "limit",
+        "defaultLimit": 100,
+        "maxLimit": 1000
+      },
+      "filter": {
+        "input": {
+          "kind": "literal",
+          "value": {
+            "room_id": {
+              "_eq": "lobby"
+            }
+          }
+        },
+        "fields": [
+          {
+            "field": "author_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "body",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "created_at",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "message_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "room_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          }
+        ],
+        "relationships": [
+          {
+            "field": "author",
+            "targetModel": "AuthUserView",
+            "kind": "belongs_to",
+            "keyMapping": {
+              "kind": "direct",
+              "local": [
+                "author_id"
+              ],
+              "remote": [
+                "user_id"
+              ]
+            },
+            "maintenance": "local",
+            "dependencies": [
+              "auth_users",
+              "chat_messages"
+            ]
+          }
+        ],
+        "rowPolicy": {
+          "kind": "unrestricted"
+        }
+      },
+      "order": {
+        "fields": [
+          {
+            "field": "author_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "body",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "created_at",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "message_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "room_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          }
+        ],
+        "tieBreakers": [
+          {
+            "field": "message_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          }
+        ]
+      },
+      "pagination": {
+        "kind": "offset",
+        "insert": "local",
+        "delete": "local",
+        "reorder": "local",
+        "stableUpdate": "local"
+      },
+      "selection": {
+        "typename": "ChatMessageView",
+        "storage": {
+          "kind": "normalized",
+          "model": "ChatMessageView",
+          "identityFields": [
+            "message_id"
+          ]
+        },
+        "members": [
+          {
+            "kind": "scalar",
+            "responseKey": "message_id",
+            "field": "message_id",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "room_id",
+            "field": "room_id",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "author_id",
+            "field": "author_id",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "body",
+            "field": "body",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "created_at",
+            "field": "created_at",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_typename",
+            "field": "__typename",
+            "codec": "string",
+            "nullable": false,
+            "expose": false
+          }
+        ]
+      }
+    }
+  ],
+  "protocol": {
+    "version": 1,
+    "schemaHash": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui",
+      "roles": [
+        "admin",
+        "user"
+      ]
+    },
+    "operation": "sha256:54dd3bd2142cf20a0bcc28d632fbd6cfc69f1d6d9ff94268a90865fd5a56a552",
+    "trustedPresets": [
+      {
+        "name": "x-user-id",
+        "codec": "string"
+      }
+    ]
+  },
+  "live": {
+    "id": "sha256:3d894c6412e9408d178ad11030c0ed1f8db0066216e70131dae3f61fb1be81b4",
+    "document": "subscription ChatMessages_Live {\n  chat_messages(where: {room_id: {_eq: \"lobby\"}}) {\n    message_id\n    room_id\n    author_id\n    body\n    created_at\n    _distributed_typename: __typename\n  }\n}\n"
+  }
+};
diff --git a/tests/e2e-ui/ui/src/lib/generated/user/operations/todos.ts b/tests/e2e-ui/ui/src/lib/generated/user/operations/todos.ts
new file mode 100644
index 00000000..266d4392
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/user/operations/todos.ts
@@ -0,0 +1,273 @@
+/** GENERATED by dctl client. Do not edit. */
+import type { ReplicaOperationArtifact } from '@hops-ops/distributed/replica';
+
+export type Operation_Todos_Variables = Record<string, never>;
+
+export type Operation_Todos_Data = {
+  readonly "todos": readonly {
+    readonly "todo_id": string;
+    readonly "owner_id": string;
+    readonly "title": string;
+    readonly "status": string;
+  }[];
+};
+
+/** Exact canonical query bytes sent to the server. */
+export const Operation_TodosDocument = "query Todos {\n  todos(order_by: [{status: asc}, {todo_id: asc}]) {\n    todo_id\n    owner_id\n    title\n    status\n    _distributed_typename: __typename\n  }\n}\n";
+
+/** Typed normalized-replica operation descriptor. */
+export const Operation_Todos: ReplicaOperationArtifact<Operation_Todos_Data, Operation_Todos_Variables> = {
+  "id": "sha256:df906cbf75f2d5c11256c816a3a3726f34689e5d1a57f198484396c8c3803030",
+  "document": "query Todos {\n  todos(order_by: [{status: asc}, {todo_id: asc}]) {\n    todo_id\n    owner_id\n    title\n    status\n    _distributed_typename: __typename\n  }\n}\n",
+  "source": {
+    "path": "src/routes/todos/+page.graphql",
+    "line": 2,
+    "column": 1
+  },
+  "variableCodec": {
+    "version": 1,
+    "limits": {
+      "maxDepth": 8,
+      "maxBoolWidth": 256,
+      "maxInList": 1000
+    },
+    "variables": {},
+    "inputs": {}
+  },
+  "roots": [
+    {
+      "responseKey": "todos",
+      "field": "todos",
+      "cardinality": "many",
+      "nullable": false,
+      "arguments": {
+        "order_by": {
+          "kind": "literal",
+          "value": [
+            {
+              "status": "asc"
+            },
+            {
+              "todo_id": "asc"
+            }
+          ]
+        }
+      },
+      "dependencies": [
+        "todos"
+      ],
+      "coverage": {
+        "kind": "offset",
+        "offsetArgument": "offset",
+        "limitArgument": "limit",
+        "defaultLimit": 100,
+        "maxLimit": 1000
+      },
+      "filter": {
+        "fields": [
+          {
+            "field": "owner_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "status",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "title",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          },
+          {
+            "field": "todo_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false,
+            "operators": [
+              "_eq",
+              "_gt",
+              "_gte",
+              "_ilike",
+              "_in",
+              "_is_null",
+              "_like",
+              "_lt",
+              "_lte",
+              "_neq",
+              "_nin"
+            ]
+          }
+        ],
+        "relationships": [],
+        "rowPolicy": {
+          "kind": "server_only"
+        }
+      },
+      "order": {
+        "input": {
+          "kind": "literal",
+          "value": [
+            {
+              "status": "asc"
+            },
+            {
+              "todo_id": "asc"
+            }
+          ]
+        },
+        "fields": [
+          {
+            "field": "owner_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "status",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "title",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "field": "todo_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          }
+        ],
+        "tieBreakers": [
+          {
+            "field": "todo_id",
+            "scalar": "String",
+            "codec": "string",
+            "nullable": false
+          }
+        ]
+      },
+      "pagination": {
+        "kind": "offset",
+        "insert": "local",
+        "delete": "local",
+        "reorder": "local",
+        "stableUpdate": "local"
+      },
+      "selection": {
+        "typename": "TodoView",
+        "storage": {
+          "kind": "normalized",
+          "model": "TodoView",
+          "identityFields": [
+            "todo_id"
+          ]
+        },
+        "members": [
+          {
+            "kind": "scalar",
+            "responseKey": "todo_id",
+            "field": "todo_id",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "owner_id",
+            "field": "owner_id",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "title",
+            "field": "title",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "status",
+            "field": "status",
+            "codec": "string",
+            "nullable": false
+          },
+          {
+            "kind": "scalar",
+            "responseKey": "_distributed_typename",
+            "field": "__typename",
+            "codec": "string",
+            "nullable": false,
+            "expose": false
+          }
+        ]
+      }
+    }
+  ],
+  "protocol": {
+    "version": 1,
+    "schemaHash": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui",
+      "roles": [
+        "admin",
+        "user"
+      ]
+    },
+    "operation": "sha256:df906cbf75f2d5c11256c816a3a3726f34689e5d1a57f198484396c8c3803030",
+    "trustedPresets": [
+      {
+        "name": "x-user-id",
+        "codec": "string"
+      }
+    ]
+  }
+};
diff --git a/tests/e2e-ui/ui/src/lib/generated/user/protocol.ts b/tests/e2e-ui/ui/src/lib/generated/user/protocol.ts
new file mode 100644
index 00000000..23b7f8c1
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/user/protocol.ts
@@ -0,0 +1,52 @@
+/** GENERATED by dctl client. Exact framework-owned operation bytes. */
+
+import type { ReplicaCommandStatusArtifact } from '@hops-ops/distributed/replica';
+
+export const CLIENT_PROTOCOL = {
+	version: 1,
+	serviceId: "e2e-ui",
+	schemaHash: "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+	protocolHash: "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+	surface: {"kind":"application","name":"e2e-ui","roles":["admin","user"]},
+	trustedPresets: [
+  {
+    "name": "x-user-id",
+    "codec": "string"
+  }
+],
+	operations: {
+  "version": 1,
+  "command_status": {
+    "name": "Distributed_CommandStatus",
+    "operation": "query Distributed_CommandStatus($commandId: ID!) { commandStatus(commandId: $commandId) { state } }",
+    "operation_hash": "sha256:eb3ce6a8b306d935fc9f3d6f071804ce3ec415d209594c04015fa35b080282ef"
+  }
+}
+} as const;
+
+/** Exact compiler-owned operation used to recover ambiguous command outcomes. */
+export const COMMAND_STATUS: ReplicaCommandStatusArtifact = {
+  "document": "query Distributed_CommandStatus($commandId: ID!) { commandStatus(commandId: $commandId) { state } }",
+  "name": "Distributed_CommandStatus",
+  "operationHash": "sha256:eb3ce6a8b306d935fc9f3d6f071804ce3ec415d209594c04015fa35b080282ef",
+  "protocol": {
+    "operation": "sha256:eb3ce6a8b306d935fc9f3d6f071804ce3ec415d209594c04015fa35b080282ef",
+    "protocolHash": "sha256:30f19c9f4d29280a02ddf67c4df62cdc92c4e8090792f43d6b1bdafea3e31273",
+    "schemaHash": "sha256:9be67c0b4e41678de4d594780fc3124c7d2ee7ba21b2a237f137051adcf8a08c",
+    "surface": {
+      "kind": "application",
+      "name": "e2e-ui",
+      "roles": [
+        "admin",
+        "user"
+      ]
+    },
+    "trustedPresets": [
+      {
+        "codec": "string",
+        "name": "x-user-id"
+      }
+    ],
+    "version": 1
+  }
+};
diff --git a/tests/e2e-ui/ui/src/lib/generated/user/routes.ts b/tests/e2e-ui/ui/src/lib/generated/user/routes.ts
new file mode 100644
index 00000000..ca3a058b
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/user/routes.ts
@@ -0,0 +1,35 @@
+import { Operation_BlobGames } from './operations/blob-games.js';
+import { Operation_ChatMessages } from './operations/chat-messages.js';
+import { Operation_Todos } from './operations/todos.js';
+
+/** GENERATED framework-neutral `@load` ownership plan. */
+export const DISTRIBUTED_ROUTES = [
+  {
+    "operation": "BlobGames",
+    "route": "/blob/[[gameId]]",
+    "source_path": "src/routes/blob/[[gameId]]/+page.graphql",
+    "discovery": "convention"
+  },
+  {
+    "operation": "ChatMessages",
+    "route": "/chat",
+    "source_path": "src/routes/chat/+page.graphql",
+    "discovery": "convention"
+  },
+  {
+    "operation": "Todos",
+    "route": "/todos",
+    "source_path": "src/routes/todos/+page.graphql",
+    "discovery": "convention"
+  }
+] as const;
+
+/** Static route-to-artifact bindings consumed by framework SSR adapters. */
+export const DISTRIBUTED_ROUTE_OPERATIONS = [
+  { plan: DISTRIBUTED_ROUTES[0], artifact: Operation_BlobGames },
+  { plan: DISTRIBUTED_ROUTES[1], artifact: Operation_ChatMessages },
+  { plan: DISTRIBUTED_ROUTES[2], artifact: Operation_Todos }
+] as const;
+
+export type DistributedRoutePlan = (typeof DISTRIBUTED_ROUTES)[number];
+export type DistributedRouteOperation = (typeof DISTRIBUTED_ROUTE_OPERATIONS)[number];
diff --git a/tests/e2e-ui/ui/src/lib/generated/user/sveltekit.ts b/tests/e2e-ui/ui/src/lib/generated/user/sveltekit.ts
new file mode 100644
index 00000000..7515b1cc
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/generated/user/sveltekit.ts
@@ -0,0 +1,56 @@
+/** GENERATED by dctl client. Do not edit. */
+
+import {
+  createDistributedSvelteKit,
+  defineDistributedSvelteKitOperation,
+  provideDistributedSvelteKitClient,
+  useDistributedSvelteKitCommands
+} from '@hops-ops/distributed/sveltekit';
+
+import type {
+  CreateDistributedSvelteKitOptions,
+  DistributedSvelteKitClient
+} from '@hops-ops/distributed/sveltekit';
+
+import { createCommands as createGeneratedCommands } from './commands.js';
+import type { GeneratedCommands as ServiceGeneratedCommands } from './commands.js';
+
+export type GeneratedCommands = ServiceGeneratedCommands;
+
+import { Operation_BlobGames as DistributedOperation_0 } from './operations/blob-games.js';
+
+import { Operation_ChatMessages as DistributedOperation_1 } from './operations/chat-messages.js';
+
+import { Operation_Todos as DistributedOperation_2 } from './operations/todos.js';
+
+/** Inspectable framework-neutral artifacts remain available here. */
+export * from './index.js';
+
+/** Tree-local Svelte binding for the generated `BlobGames` artifact. */
+export const BlobGames = defineDistributedSvelteKitOperation(DistributedOperation_0);
+
+/** Tree-local Svelte binding for the generated `ChatMessages` artifact. */
+export const ChatMessages = defineDistributedSvelteKitOperation(DistributedOperation_1);
+
+/** Tree-local Svelte binding for the generated `Todos` artifact. */
+export const Todos = defineDistributedSvelteKitOperation(DistributedOperation_2);
+
+/**
+ * Create and install one component-tree/request-local generated client.
+ * No client or command proxy is retained by this module.
+ */
+export function provideDistributed(
+  options: Omit<CreateDistributedSvelteKitOptions<GeneratedCommands>, 'createCommands'>
+): DistributedSvelteKitClient<GeneratedCommands> {
+  return provideDistributedSvelteKitClient(
+    createDistributedSvelteKit<GeneratedCommands>({
+      ...options,
+      createCommands: createGeneratedCommands
+    })
+  );
+}
+
+/** Resolve the nearest generated command surface during component initialization. */
+export function useCommands(): GeneratedCommands {
+  return useDistributedSvelteKitCommands<GeneratedCommands>();
+}
diff --git a/tests/e2e-ui/ui/src/lib/index.ts b/tests/e2e-ui/ui/src/lib/index.ts
new file mode 100644
index 00000000..856f2b6c
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/index.ts
@@ -0,0 +1 @@
+// place files you want to import through the `$lib` alias in this folder.
diff --git a/tests/e2e-ui/ui/src/lib/roles.ts b/tests/e2e-ui/ui/src/lib/roles.ts
new file mode 100644
index 00000000..4057871f
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/roles.ts
@@ -0,0 +1,21 @@
+/**
+ * Pure role helper — safe for browser and server (no $env).
+ * Do not import from auth.ts in client components.
+ *
+ * Exact group key membership only (not substring). "administrator" is NOT admin.
+ * Matches Zitadel project role keys `admin` / `admins` used in e2e bootstrap.
+ */
+export function engineRoleFromGroups(groups: string[] | undefined): 'admin' | 'user' {
+	if (!groups?.length) return 'user';
+	if (groups.includes('admin') || groups.includes('admins')) return 'admin';
+	return 'user';
+}
+
+export function roleFromGroups(groups: string[] | undefined): 'admin' | 'user' {
+	return engineRoleFromGroups(groups);
+}
+
+/** UI / load gate: engine role must be admin (after engineRoleFromGroups). */
+export function isAdminEngineRole(role: string | null | undefined): boolean {
+	return role === 'admin';
+}
diff --git a/tests/e2e-ui/ui/src/lib/server/graphql.ts b/tests/e2e-ui/ui/src/lib/server/graphql.ts
new file mode 100644
index 00000000..b1c75f23
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/server/graphql.ts
@@ -0,0 +1,17 @@
+/** Private API origin used by the package-owned SvelteKit SSR transport. */
+import { env } from '$env/dynamic/private';
+import { env as publicEnv } from '$env/dynamic/public';
+import { cleanEnvValue } from '$lib/clean-env';
+
+export function apiBase(): string {
+	return (
+		cleanEnvValue(env.E2E_API_ORIGIN) ||
+		cleanEnvValue(env.E2E_BASE_URL) ||
+		cleanEnvValue(publicEnv.PUBLIC_E2E_API_ORIGIN) ||
+		'http://127.0.0.1:8791'
+	);
+}
+
+export function graphqlHttpUrl(): string {
+	return `${apiBase()}/graphql`;
+}
diff --git a/tests/e2e-ui/ui/src/lib/server/oidc-scopes.ts b/tests/e2e-ui/ui/src/lib/server/oidc-scopes.ts
new file mode 100644
index 00000000..a1d7847c
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/server/oidc-scopes.ts
@@ -0,0 +1,55 @@
+/**
+ * OIDC authorize scopes for Zitadel (shared by Auth.js config + /signin start).
+ *
+ * Zitadel uses **project role keys** (not LDAP-style "groups"). When the right
+ * reserved scopes are requested, those roles appear on the access/id token as
+ * object claims whose keys are the role names (e.g. `admin`).
+ */
+import { env } from '$env/dynamic/private';
+import { cleanEnvValue } from '$lib/clean-env';
+
+const DEFAULT_OIDC_SCOPES = 'openid profile email offline_access';
+
+function envFirst(names: string[], fallback = '') {
+	for (const name of names) {
+		const value = cleanEnvValue(env[name]);
+		if (value) return value;
+		// process.env (make run / shell) — same keys, in case kit env is incomplete
+		if (typeof process !== 'undefined') {
+			const fromProc = cleanEnvValue(process.env[name]);
+			if (fromProc) return fromProc;
+		}
+	}
+	return fallback;
+}
+
+/**
+ * Always merge required Zitadel reserved scopes even if OIDC_SCOPES is incomplete
+ * (e.g. bare `openid`). Without project audience + roles scopes, tokens have no
+ * role claims even when the human has a project grant and the app has
+ * accessTokenRoleAssertion / idTokenRoleAssertion enabled.
+ */
+export function oidcScopes(): string {
+	const fromEnv = envFirst(['OIDC_SCOPES']);
+	const aud = envFirst(['OIDC_AUDIENCE', 'ZITADEL_PROJECT_ID']);
+	const parts = new Set<string>();
+
+	for (const piece of `${fromEnv || DEFAULT_OIDC_SCOPES}`.split(/\s+/)) {
+		if (piece) parts.add(piece);
+	}
+
+	for (const s of DEFAULT_OIDC_SCOPES.split(/\s+/)) parts.add(s);
+
+	if (aud) {
+		parts.add(`urn:zitadel:iam:org:project:id:${aud}:aud`);
+		parts.add('urn:zitadel:iam:org:project:roles');
+		parts.add('urn:zitadel:iam:org:projects:roles');
+		parts.add(`urn:zitadel:iam:org:project:id:${aud}:roles`);
+	}
+
+	return [...parts].join(' ');
+}
+
+export function oidcAudience(): string {
+	return envFirst(['OIDC_AUDIENCE', 'ZITADEL_PROJECT_ID']);
+}
diff --git a/tests/e2e-ui/ui/src/lib/server/oidc-start.ts b/tests/e2e-ui/ui/src/lib/server/oidc-start.ts
new file mode 100644
index 00000000..4a29ee12
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/server/oidc-start.ts
@@ -0,0 +1,100 @@
+/**
+ * Shared OIDC start for /login, /signin, /signup.
+ * Probes the IdP before Auth.js so we never bounce to `/?error=Configuration`
+ * with no explanation (common when Zitadel / Docker is down).
+ *
+ * Uses `redirect()` (throws) so it works from page `load`, form actions, and
+ * +server handlers. Returning a raw Response from `load` is invalid in SvelteKit.
+ */
+import { error, redirect } from '@sveltejs/kit';
+import { env } from '$env/dynamic/private';
+import { cleanEnvValue } from '$lib/clean-env';
+import { oidcScopes } from '$lib/server/oidc-scopes';
+
+export function safeCallbackUrl(url: URL) {
+	const callbackUrl = url.searchParams.get('callbackUrl');
+	if (!callbackUrl) return url.origin;
+
+	try {
+		const parsed = new URL(callbackUrl, url.origin);
+		if (parsed.origin !== url.origin) return url.origin;
+		return parsed.toString();
+	} catch {
+		return url.origin;
+	}
+}
+
+function oidcIssuer(): string {
+	const raw =
+		cleanEnvValue(env.OIDC_ISSUER) ||
+		cleanEnvValue(env.ZITADEL_ISSUER) ||
+		'';
+	return raw.replace(/\/+$/, '');
+}
+
+/**
+ * Fail fast with a actionable message if OIDC is not configured or the IdP
+ * (Zitadel on :18080) is unreachable.
+ */
+export async function assertOidcReady(): Promise<void> {
+	const issuer = oidcIssuer();
+	const clientId = cleanEnvValue(env.OIDC_CLIENT_ID) || cleanEnvValue(env.ZITADEL_CLIENT_ID);
+
+	if (!issuer || !clientId) {
+		error(
+			503,
+			'OIDC is not configured. From tests/e2e-ui run: make up  (writes e2e-ui.env with OIDC_*). Then restart the UI with that env sourced.'
+		);
+	}
+
+	const discovery = `${issuer}/.well-known/openid-configuration`;
+	try {
+		const res = await fetch(discovery, {
+			signal: AbortSignal.timeout(2500)
+		});
+		if (!res.ok) {
+			error(
+				503,
+				`Identity provider at ${issuer} returned HTTP ${res.status}. Start Zitadel: cd tests/e2e-ui && make up  (needs Docker/Colima). Demo logins after up: alice / bob / admin · Password1!`
+			);
+		}
+	} catch {
+		error(
+			503,
+			`Cannot reach identity provider at ${issuer} (Docker/Zitadel not running). Start it with: cd tests/e2e-ui && make up  Then source e2e-ui.env and restart make run / the UI. Until then use demo users after the stack is up — self-registration is enabled by bootstrap when Zitadel is healthy.`
+		);
+	}
+}
+
+export async function startOidcSignIn(
+	event: { fetch: typeof fetch; url: URL },
+	label: 'sign-in' | 'sign-up' = 'sign-in'
+): Promise<never> {
+	await assertOidcReady();
+
+	const callbackUrl = safeCallbackUrl(event.url);
+	// Pass scope explicitly so Auth.js authorization params include Zitadel role
+	// scopes even if the provider config was frozen with a bare openid default.
+	const response = await event.fetch('/auth/signin/oidc', {
+		method: 'POST',
+		headers: {
+			'Content-Type': 'application/x-www-form-urlencoded',
+			'X-Auth-Return-Redirect': '1'
+		},
+		body: new URLSearchParams({
+			callbackUrl,
+			scope: oidcScopes()
+		})
+	});
+
+	const payload = (await response.json().catch(() => null)) as { url?: unknown } | null;
+	if (!response.ok || typeof payload?.url !== 'string') {
+		error(
+			502,
+			`Unable to start Zitadel ${label}. Check OIDC_CLIENT_ID / OIDC_CLIENT_SECRET in e2e-ui.env (re-run make up if the secret file is missing).`
+		);
+	}
+
+	// Throws — valid from load / actions / +server
+	redirect(302, payload.url);
+}
diff --git a/tests/e2e-ui/ui/src/lib/server/zitadel-session.ts b/tests/e2e-ui/ui/src/lib/server/zitadel-session.ts
new file mode 100644
index 00000000..726a8c3c
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/server/zitadel-session.ts
@@ -0,0 +1,271 @@
+/**
+ * Zitadel Login V2 helpers for custom auth pages.
+ *
+ * Auth.js still starts OIDC (PKCE). After authorize, Zitadel redirects to our
+ * /login?authRequest=V2_…  We authenticate via Session API v2, then
+ * CreateCallback to get the OIDC code URL back to Auth.js.
+ *
+ * Requires server-only ZITADEL_SERVICE_USER_TOKEN (IAM_LOGIN_CLIENT PAT from make up).
+ */
+import { env } from '$env/dynamic/private';
+import { cleanEnvValue } from '$lib/clean-env';
+
+export class ZitadelAuthError extends Error {
+	constructor(
+		message: string,
+		public readonly status = 400,
+		public readonly code?: string
+	) {
+		super(message);
+		this.name = 'ZitadelAuthError';
+	}
+}
+
+function issuer(): string {
+	const raw =
+		cleanEnvValue(env.OIDC_ISSUER) ||
+		cleanEnvValue(env.ZITADEL_ISSUER) ||
+		'';
+	return raw.replace(/\/+$/, '');
+}
+
+function serviceToken(): string {
+	return (
+		cleanEnvValue(env.ZITADEL_SERVICE_USER_TOKEN) ||
+		cleanEnvValue(env.ZITADEL_LOGIN_CLIENT_TOKEN) ||
+		''
+	);
+}
+
+function projectId(): string {
+	return cleanEnvValue(env.OIDC_AUDIENCE) || cleanEnvValue(env.ZITADEL_PROJECT_ID) || '';
+}
+
+export function assertLoginClientConfigured(): void {
+	if (!issuer()) {
+		throw new ZitadelAuthError(
+			'OIDC_ISSUER is not set. Run make up and source e2e-ui.env.',
+			503
+		);
+	}
+	if (!serviceToken()) {
+		throw new ZitadelAuthError(
+			'ZITADEL_SERVICE_USER_TOKEN missing. Re-run make up (writes login-client PAT) and restart the UI.',
+			503
+		);
+	}
+}
+
+async function zitadelFetch(
+	path: string,
+	init: RequestInit & { method?: string } = {}
+): Promise<{ ok: boolean; status: number; body: Record<string, unknown> }> {
+	const base = issuer();
+	const token = serviceToken();
+	const res = await fetch(`${base}${path}`, {
+		...init,
+		headers: {
+			Authorization: `Bearer ${token}`,
+			'Content-Type': 'application/json',
+			Accept: 'application/json',
+			...(init.headers ?? {})
+		},
+		signal: AbortSignal.timeout(12_000)
+	});
+	const text = await res.text();
+	let body: Record<string, unknown> = {};
+	if (text) {
+		try {
+			body = JSON.parse(text) as Record<string, unknown>;
+		} catch {
+			body = { message: text.slice(0, 400) };
+		}
+	}
+	return { ok: res.ok, status: res.status, body };
+}
+
+function apiErrorMessage(body: Record<string, unknown>, fallback: string): string {
+	const msg = body.message ?? body.error_description ?? body.error;
+	if (typeof msg === 'string' && msg.trim()) return msg.trim();
+	return fallback;
+}
+
+export type PasswordSession = {
+	sessionId: string;
+	sessionToken: string;
+};
+
+/** Create a Zitadel session with login name + password checks (Session API v2). */
+export async function createPasswordSession(
+	loginName: string,
+	password: string
+): Promise<PasswordSession> {
+	assertLoginClientConfigured();
+	const name = loginName.trim();
+	if (!name || !password) {
+		throw new ZitadelAuthError('Username and password are required.');
+	}
+
+	const { ok, status, body } = await zitadelFetch('/v2/sessions', {
+		method: 'POST',
+		body: JSON.stringify({
+			checks: {
+				user: { loginName: name },
+				password: { password }
+			}
+		})
+	});
+
+	if (!ok) {
+		// Wrong password / unknown user often 400 or 404
+		const hint =
+			status === 404 || status === 400
+				? 'Invalid username or password.'
+				: apiErrorMessage(body, `Sign-in failed (HTTP ${status}).`);
+		throw new ZitadelAuthError(hint, status === 401 || status === 403 ? status : 400);
+	}
+
+	const sessionId = body.sessionId;
+	const sessionToken = body.sessionToken;
+	if (typeof sessionId !== 'string' || typeof sessionToken !== 'string') {
+		throw new ZitadelAuthError('Session response missing id/token.', 502);
+	}
+	return { sessionId, sessionToken };
+}
+
+/**
+ * Finalize OIDC auth request with the session → callback URL including code
+ * for Auth.js (/auth/callback/oidc?code=…&state=…).
+ */
+export async function finalizeAuthRequest(
+	authRequestId: string,
+	session: PasswordSession
+): Promise<string> {
+	assertLoginClientConfigured();
+	const id = authRequestId.trim();
+	if (!id) {
+		throw new ZitadelAuthError('Missing authRequest. Start sign-in again.');
+	}
+
+	const { ok, status, body } = await zitadelFetch(
+		`/v2/oidc/auth_requests/${encodeURIComponent(id)}`,
+		{
+			method: 'POST',
+			body: JSON.stringify({
+				session: {
+					sessionId: session.sessionId,
+					sessionToken: session.sessionToken
+				}
+			})
+		}
+	);
+
+	if (!ok) {
+		throw new ZitadelAuthError(
+			apiErrorMessage(body, `Could not complete sign-in (HTTP ${status}).`),
+			status >= 500 ? 502 : 400
+		);
+	}
+
+	const callbackUrl = body.callbackUrl;
+	if (typeof callbackUrl !== 'string' || !callbackUrl) {
+		throw new ZitadelAuthError('OIDC callback URL missing from Zitadel response.', 502);
+	}
+	return callbackUrl;
+}
+
+export type RegisterInput = {
+	username: string;
+	email: string;
+	password: string;
+	givenName?: string;
+	familyName?: string;
+};
+
+/** Create a human user (User v2) and grant the project `user` role. */
+export async function registerHuman(input: RegisterInput): Promise<{ userId: string }> {
+	assertLoginClientConfigured();
+	const username = input.username.trim();
+	const email = input.email.trim();
+	const password = input.password;
+	if (!username || !email || !password) {
+		throw new ZitadelAuthError('Username, email, and password are required.');
+	}
+	if (password.length < 8) {
+		throw new ZitadelAuthError('Password must be at least 8 characters.');
+	}
+
+	const given = (input.givenName?.trim() || username).slice(0, 200);
+	const family = (input.familyName?.trim() || 'User').slice(0, 200);
+
+	const create = await zitadelFetch('/v2/users/human', {
+		method: 'POST',
+		body: JSON.stringify({
+			username,
+			profile: {
+				givenName: given,
+				familyName: family,
+				displayName: username
+			},
+			email: {
+				email,
+				isVerified: true
+			},
+			password: {
+				password,
+				changeRequired: false
+			}
+		})
+	});
+
+	if (!create.ok) {
+		const msg = apiErrorMessage(create.body, `Registration failed (HTTP ${create.status}).`);
+		// Duplicate username/email
+		throw new ZitadelAuthError(msg, create.status === 409 ? 409 : 400);
+	}
+
+	const userId = create.body.userId;
+	if (typeof userId !== 'string' || !userId) {
+		throw new ZitadelAuthError('Registration response missing userId.', 502);
+	}
+
+	const pid = projectId();
+	if (pid) {
+		const grant = await zitadelFetch(`/management/v1/users/${userId}/grants`, {
+			method: 'POST',
+			body: JSON.stringify({
+				projectId: pid,
+				roleKeys: ['user']
+			})
+		});
+		// 409 already granted is fine; other errors are soft (user can still log in)
+		if (!grant.ok && grant.status !== 409) {
+			console.warn(
+				'[zitadel-session] project grant failed',
+				grant.status,
+				apiErrorMessage(grant.body, '')
+			);
+		}
+	}
+
+	return { userId };
+}
+
+/** Password login + OIDC finalize in one step. */
+export async function loginWithPassword(
+	authRequestId: string,
+	loginName: string,
+	password: string
+): Promise<string> {
+	const session = await createPasswordSession(loginName, password);
+	return finalizeAuthRequest(authRequestId, session);
+}
+
+/** Register, then password-login into the pending auth request. */
+export async function registerAndLogin(
+	authRequestId: string,
+	input: RegisterInput
+): Promise<string> {
+	await registerHuman(input);
+	return loginWithPassword(authRequestId, input.username, input.password);
+}
diff --git a/tests/e2e-ui/ui/src/lib/session.ts b/tests/e2e-ui/ui/src/lib/session.ts
new file mode 100644
index 00000000..b207e83d
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/session.ts
@@ -0,0 +1,67 @@
+export { engineRoleFromGroups, roleFromGroups } from './roles';
+
+type SessionLike = {
+	user?: {
+		id?: string | null;
+		username?: string | null;
+		name?: string | null;
+		email?: string | null;
+	} | null;
+	accessToken?: string | null;
+} | null | undefined;
+
+/** Display label for UI chrome (username → name → email → fallback). */
+export function sessionDisplayName(session: SessionLike, fallback = 'you'): string {
+	return (
+		session?.user?.username ?? session?.user?.name ?? session?.user?.email ?? fallback
+	);
+}
+
+/**
+ * Decode JWT `sub` without verification (UI identity only).
+ * Prefer this over `session.user.id` when matching server `author_id` /
+ * `owner_id` — commands use the access-token principal, which can diverge
+ * from Auth.js `token.sub` after refresh or IdP claim quirks.
+ */
+export function accessTokenSub(accessToken: string | null | undefined): string | null {
+	if (!accessToken) return null;
+	const parts = accessToken.split('.');
+	if (parts.length < 2) return null;
+	try {
+		const b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+		const pad = b64.length % 4 === 0 ? '' : '='.repeat(4 - (b64.length % 4));
+		const json = JSON.parse(atob(b64 + pad)) as { sub?: unknown };
+		return typeof json.sub === 'string' && json.sub.length > 0 ? json.sub : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Principal id used for “is this message mine?” (access token sub → session id). */
+export function sessionPrincipalId(
+	session: SessionLike,
+	accessToken?: string | null
+): string {
+	return (
+		accessTokenSub(accessToken ?? session?.accessToken) ??
+		session?.user?.id?.trim() ??
+		''
+	);
+}
+
+/** True when a message/game row belongs to the signed-in principal. */
+export function isOwnAuthor(
+	authorId: string | null | undefined,
+	principalId: string,
+	opts?: { authorUserId?: string | null; username?: string | null; displayName?: string | null }
+): boolean {
+	const me = principalId.trim();
+	if (!me) return false;
+	if (authorId && authorId === me) return true;
+	if (opts?.authorUserId && opts.authorUserId === me) return true;
+	// Soft match: joined display name equals preferred_username (scrape / IdP label).
+	const uname = opts?.username?.trim().toLowerCase();
+	const label = opts?.displayName?.trim().toLowerCase();
+	if (uname && label && uname === label) return true;
+	return false;
+}
diff --git a/tests/e2e-ui/ui/src/lib/styles/chrome.css b/tests/e2e-ui/ui/src/lib/styles/chrome.css
new file mode 100644
index 00000000..5d3d1e82
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/styles/chrome.css
@@ -0,0 +1,381 @@
+/* App chrome — root layout only (navbar, account menu, footer) */
+/* —— Chrome —— */
+.navbar {
+	position: fixed;
+	top: 0;
+	left: 0;
+	right: 0;
+	z-index: 1000;
+	background: rgba(246, 245, 242, 0.86);
+	backdrop-filter: blur(12px);
+	border-bottom: 1px solid transparent;
+	transition: border-color 0.2s ease, background 0.2s ease;
+}
+
+.navbar.scrolled {
+	border-bottom-color: var(--wf-line);
+	background: rgba(246, 245, 242, 0.95);
+}
+
+.navbar-container {
+	max-width: var(--wf-max);
+	margin: 0 auto;
+	padding: 1rem var(--wf-gutter);
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: 1rem;
+}
+
+.brand-link {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.6rem;
+	text-decoration: none;
+	color: var(--wf-ink);
+	font-weight: 600;
+	font-size: 0.95rem;
+	letter-spacing: -0.02em;
+}
+
+.brand-mark {
+	display: inline-grid;
+	place-items: center;
+	width: 1.65rem;
+	height: 1.65rem;
+	border: 1px solid var(--wf-ink);
+	border-radius: 3px;
+	font-family: var(--wf-mono);
+	font-size: 0.62rem;
+	font-weight: 500;
+	letter-spacing: 0.02em;
+	color: var(--wf-ink);
+}
+
+.navbar-burger {
+	display: flex;
+	flex-direction: column;
+	gap: 5px;
+	background: none;
+	border: none;
+	cursor: pointer;
+	padding: 0.45rem;
+}
+
+.navbar-burger span {
+	display: block;
+	width: 20px;
+	height: 1.5px;
+	background: var(--wf-ink);
+}
+
+.navbar-menu {
+	display: none;
+	width: 100%;
+	flex-direction: column;
+	gap: 0.85rem;
+	padding-top: 0.65rem;
+}
+
+.navbar-menu.is-active {
+	display: flex;
+}
+
+.navbar-links {
+	display: flex;
+	flex-direction: column;
+	gap: 0.1rem;
+}
+
+.nav-link {
+	color: var(--wf-ink-soft);
+	text-decoration: none;
+	padding: 0.45rem 0.55rem;
+	font-weight: 500;
+	font-size: 0.9rem;
+	background: none;
+	border: none;
+	cursor: pointer;
+	text-align: left;
+	border-radius: 4px;
+}
+
+.nav-link.active,
+.nav-link:hover {
+	color: var(--wf-ink);
+	background: rgba(28, 28, 26, 0.04);
+}
+
+.navbar-cta {
+	display: flex;
+	align-items: center;
+	gap: 0.65rem;
+}
+
+.cta-button {
+	display: inline-flex;
+	align-items: center;
+	padding: 0.5rem 0.95rem;
+	font-weight: 600;
+	font-size: 0.875rem;
+	text-decoration: none;
+	color: #f6f5f2 !important;
+	background: var(--wf-ink);
+	border: 1px solid var(--wf-ink);
+	border-radius: 5px;
+}
+
+.cta-button:hover {
+	background: #2a2a28;
+}
+
+/* Secondary nav CTA — next to primary Sign in */
+.cta-button-outline {
+	display: inline-flex;
+	align-items: center;
+	padding: 0.48rem 0.9rem;
+	font-weight: 600;
+	font-size: 0.875rem;
+	text-decoration: none;
+	color: var(--wf-ink);
+	background: transparent;
+	border: 1px solid var(--wf-line-strong);
+	border-radius: 5px;
+}
+
+.cta-button-outline:hover {
+	border-color: var(--wf-ink-muted);
+	background: rgba(28, 28, 26, 0.04);
+}
+
+@media (min-width: 768px) {
+	.navbar-burger {
+		display: none;
+	}
+	.navbar-menu {
+		display: flex;
+		flex-direction: row;
+		align-items: center;
+		width: auto;
+		padding-top: 0;
+		flex: 1;
+		justify-content: flex-end;
+		gap: 1.25rem;
+	}
+	.navbar-links {
+		flex-direction: row;
+		align-items: center;
+	}
+}
+
+.auth-signin-btn {
+	display: inline-flex;
+	align-items: center;
+	font-size: 0.875rem;
+	font-weight: 500;
+	color: var(--wf-ink);
+	background: transparent;
+	border: 1px solid var(--wf-line-strong);
+	padding: 0.48rem 0.9rem;
+	border-radius: 5px;
+	text-decoration: none;
+}
+
+.auth-signin-btn:hover {
+	border-color: var(--wf-ink-muted);
+}
+
+.auth-avatar {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	width: 2.15rem;
+	height: 2.15rem;
+	border-radius: 50%;
+	border: 1px solid var(--wf-line-strong);
+	padding: 0;
+	cursor: pointer;
+	overflow: hidden;
+	background: var(--wf-ink);
+	color: #f6f5f2;
+}
+
+.auth-avatar-initials {
+	font-family: var(--wf-mono);
+	font-size: 0.7rem;
+	font-weight: 500;
+}
+
+.auth-avatar-img {
+	width: 100%;
+	height: 100%;
+	object-fit: cover;
+}
+
+.account-menu-overlay {
+	position: fixed;
+	top: 4.25rem;
+	right: 0.75rem;
+	left: 0.75rem;
+	z-index: 1100;
+}
+
+@media (min-width: 768px) {
+	.account-menu-overlay {
+		left: auto;
+		width: 16.5rem;
+		right: var(--wf-gutter);
+	}
+}
+
+.account-menu-modal {
+	background: var(--wf-bg-elevated);
+	border: 1px solid var(--wf-line-strong);
+	border-radius: 8px;
+	padding: 1rem;
+	display: flex;
+	flex-direction: column;
+	gap: 0.35rem;
+	box-shadow: var(--df-shadow-md);
+}
+
+.account-menu-title {
+	margin: 0 0 0.35rem;
+	font-family: var(--wf-mono);
+	font-size: 0.65rem;
+	font-weight: 500;
+	letter-spacing: 0.1em;
+	text-transform: uppercase;
+	color: var(--wf-ink-muted);
+}
+
+.account-menu-user {
+	display: flex;
+	flex-direction: column;
+	gap: 0.1rem;
+	margin-bottom: 0.4rem;
+	font-size: 0.9rem;
+	color: var(--wf-ink);
+}
+
+.account-menu-btn {
+	display: block;
+	text-align: left;
+	padding: 0.55rem 0.65rem;
+	text-decoration: none;
+	font-weight: 500;
+	font-size: 0.9rem;
+	border: none;
+	border-radius: 5px;
+	cursor: pointer;
+	background: transparent;
+	color: var(--wf-ink);
+	font-family: inherit;
+}
+
+.account-menu-btn:hover {
+	background: rgba(28, 28, 26, 0.04);
+}
+
+.account-menu-btn-primary {
+	background: var(--wf-ink);
+	color: #f6f5f2;
+}
+
+.account-menu-btn-primary:hover {
+	background: #2a2a28;
+	color: #f6f5f2;
+}
+
+.account-menu-btn-secondary {
+	color: var(--wf-ink);
+}
+
+.account-menu-btn-danger {
+	color: var(--wf-danger);
+}
+
+.account-menu-btn-neutral {
+	color: var(--wf-ink-muted);
+}
+
+
+/* Footer */
+.lab-footer,
+.df-footer {
+	border-top: 1px solid var(--wf-line);
+	background: var(--wf-bg-elevated);
+	color: var(--wf-ink-soft);
+	padding: 3.5rem var(--wf-gutter) 2.75rem;
+	position: relative;
+	z-index: 1;
+}
+
+.lab-footer-inner,
+.df-footer-inner {
+	max-width: var(--wf-max);
+	margin: 0 auto;
+	display: grid;
+	gap: 2.5rem;
+}
+
+@media (min-width: 768px) {
+	.lab-footer-inner,
+	.df-footer-inner {
+		grid-template-columns: 1.4fr 1fr 1fr;
+		gap: 3rem;
+	}
+}
+
+.lab-footer a,
+.df-footer a {
+	color: var(--wf-ink-soft);
+	text-decoration: none;
+	font-size: 0.9rem;
+	font-weight: 500;
+}
+
+.lab-footer a:hover,
+.df-footer a:hover {
+	color: var(--wf-accent);
+}
+
+.lab-footer-brand,
+.df-footer-brand {
+	font-weight: 600;
+	font-size: 1rem;
+	letter-spacing: -0.015em;
+	color: var(--wf-ink);
+}
+
+.lab-footer-tag,
+.df-footer-tag {
+	margin: 0.5rem 0 0;
+	font-size: 0.9rem;
+	line-height: 1.55;
+	max-width: 22rem;
+	color: var(--wf-ink-muted);
+}
+
+.lab-footer h4,
+.df-footer h4 {
+	margin: 0 0 0.85rem;
+	font-family: var(--wf-mono);
+	font-size: 0.65rem;
+	letter-spacing: 0.1em;
+	text-transform: uppercase;
+	color: var(--wf-ink-muted);
+	font-weight: 500;
+}
+
+.lab-footer ul,
+.df-footer ul {
+	list-style: none;
+	margin: 0;
+	padding: 0;
+	display: flex;
+	flex-direction: column;
+	gap: 0.5rem;
+}
+
+/* Todos light-paper override on wireframe site */
diff --git a/tests/e2e-ui/ui/src/lib/styles/home.css b/tests/e2e-ui/ui/src/lib/styles/home.css
new file mode 100644
index 00000000..af2cb46e
--- /dev/null
+++ b/tests/e2e-ui/ui/src/lib/styles/home.css
@@ -0,0 +1,1060 @@
+/* Fieldnote home — imported by routes/+page.svelte only */
+/* —— Home: solid alternating bands ——
+   Shared horizontal rhythm: hero + every band use the same gutter + --wf-max column.
+   Dark tokens are slightly lifted from pure ink so cream headings never match the ground. */
+.wf-home {
+	--wf-band-dark-bg: #262624;
+	--wf-band-dark-ink: #f4f2ec;
+	--wf-band-dark-soft: rgba(244, 242, 236, 0.72);
+	--wf-band-dark-muted: rgba(244, 242, 236, 0.48);
+	--wf-band-dark-line: rgba(244, 242, 236, 0.1);
+	--wf-band-dark-elev: #30302c;
+	--wf-measure: 38rem;
+
+	padding-top: 4.75rem;
+	background: var(--wf-bg);
+}
+
+.wf-band {
+	padding: var(--wf-section-y) var(--wf-gutter);
+}
+
+.wf-band-inner {
+	/* Same content column as hero-inner — continuous left edge */
+	max-width: var(--wf-max);
+	margin: 0 auto;
+}
+
+.wf-band-light {
+	background: var(--wf-bg);
+	color: var(--wf-ink);
+	border-bottom: 1px solid var(--wf-line);
+}
+
+.wf-band-dark {
+	background: var(--wf-band-dark-bg);
+	color: var(--wf-band-dark-ink);
+	border-bottom: 1px solid var(--wf-band-dark-line);
+}
+
+/* Hero: light + local soft grid; left-aligned to the shared band column */
+.wf-hero {
+	position: relative;
+	padding: calc(var(--wf-section-y) * 0.85) var(--wf-gutter) calc(var(--wf-section-y) * 0.95);
+	background: var(--wf-bg);
+	/* Soft bridge into the first dark band — no hard hairline snap */
+	border-bottom: none;
+	overflow: hidden;
+}
+
+.wf-hero::before {
+	content: '';
+	position: absolute;
+	inset: 0;
+	pointer-events: none;
+	background-image:
+		linear-gradient(var(--wf-line) 1px, transparent 1px),
+		linear-gradient(90deg, var(--wf-line) 1px, transparent 1px);
+	background-size: 48px 48px;
+	opacity: 0.4;
+	mask-image: linear-gradient(180deg, #000 30%, transparent 92%);
+}
+
+.wf-hero-inner {
+	position: relative;
+	/* Match .wf-band-inner width so copy shares the left edge with sections below */
+	max-width: var(--wf-max);
+	margin: 0 auto;
+	text-align: left;
+}
+
+.wf-hero-inner > .wf-lede,
+.wf-hero-inner > h1 {
+	max-width: var(--wf-measure);
+}
+
+.wf-kicker {
+	display: inline-block;
+	font-family: var(--wf-mono);
+	font-size: 0.72rem;
+	font-weight: 500;
+	letter-spacing: 0.08em;
+	text-transform: uppercase;
+	color: var(--wf-ink-muted);
+	margin-bottom: 1.35rem;
+	padding-bottom: 0.35rem;
+	border-bottom: 1px solid var(--wf-line-strong);
+}
+
+.wf-hero h1 {
+	margin: 0 0 1.2rem;
+	font-family: var(--wf-serif);
+	font-size: clamp(2.05rem, 4.6vw, 2.85rem);
+	font-weight: 500;
+	letter-spacing: -0.025em;
+	line-height: 1.16;
+	color: var(--wf-ink);
+}
+
+.wf-hero h1 em {
+	font-style: italic;
+	font-weight: 400;
+	color: var(--wf-ink-soft);
+}
+
+.wf-lede {
+	margin: 0 0 1.85rem;
+	font-size: 1.06rem;
+	line-height: 1.65;
+	color: var(--wf-ink-soft);
+}
+
+.wf-lede code {
+	font-size: 0.88em;
+	background: rgba(28, 28, 26, 0.05);
+	padding: 0.12em 0.35em;
+	border-radius: 3px;
+	border: 1px solid var(--wf-line);
+	color: var(--wf-ink);
+}
+
+.wf-actions {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.75rem;
+	margin-bottom: 1.85rem;
+}
+
+.wf-btn {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	padding: 0.7rem 1.15rem;
+	font-family: var(--wf-sans);
+	font-weight: 600;
+	font-size: 0.9rem;
+	text-decoration: none;
+	border-radius: 5px;
+	border: 1px solid transparent;
+	cursor: pointer;
+	transition:
+		background 0.18s var(--ease),
+		border-color 0.18s var(--ease),
+		color 0.18s var(--ease);
+}
+
+.wf-btn-primary {
+	background: var(--wf-ink);
+	color: #f6f5f2;
+	border-color: var(--wf-ink);
+}
+
+.wf-btn-primary:hover {
+	background: #2a2a28;
+}
+
+.wf-btn-ghost {
+	background: transparent;
+	color: var(--wf-ink);
+	border-color: var(--wf-line-strong);
+}
+
+.wf-btn-ghost:hover {
+	border-color: var(--wf-ink-muted);
+	background: rgba(28, 28, 26, 0.03);
+}
+
+.wf-meta {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.55rem 1.25rem;
+	font-family: var(--wf-mono);
+	font-size: 0.72rem;
+	color: var(--wf-ink-muted);
+	letter-spacing: 0.02em;
+}
+
+/* Sections / heads — light defaults (dark overrides follow with higher specificity) */
+.wf-section {
+	padding: var(--wf-section-y) var(--wf-gutter);
+	max-width: var(--wf-max);
+	margin: 0 auto;
+	border-bottom: 1px solid var(--wf-line);
+}
+
+.wf-section-head {
+	margin-bottom: 2.5rem;
+	max-width: var(--wf-measure);
+}
+
+.wf-label {
+	display: block;
+	font-family: var(--wf-mono);
+	font-size: 0.7rem;
+	font-weight: 500;
+	letter-spacing: 0.1em;
+	text-transform: uppercase;
+	color: var(--wf-ink-muted);
+	margin-bottom: 0.8rem;
+}
+
+.wf-section-head h2 {
+	margin: 0 0 0.8rem;
+	font-family: var(--wf-serif);
+	font-size: clamp(1.5rem, 2.8vw, 1.95rem);
+	font-weight: 500;
+	letter-spacing: -0.02em;
+	line-height: 1.22;
+	color: var(--wf-ink);
+}
+
+.wf-section-head p {
+	margin: 0;
+	font-size: 1.02rem;
+	line-height: 1.65;
+	color: var(--wf-ink-soft);
+}
+
+.wf-section-head code {
+	font-size: 0.88em;
+	background: rgba(28, 28, 26, 0.05);
+	padding: 0.1em 0.3em;
+	border-radius: 3px;
+}
+
+.wf-flow-map {
+	margin: 0;
+	padding-left: 1.25rem;
+	display: grid;
+	gap: 0.6rem;
+	font-size: 0.97rem;
+	line-height: 1.45;
+	max-width: 40rem;
+	color: var(--wf-ink-soft);
+}
+
+@media (min-width: 768px) {
+	.wf-flow-map {
+		grid-template-columns: 1fr 1fr;
+		column-gap: 2.25rem;
+		row-gap: 0.7rem;
+	}
+}
+
+.wf-story-step {
+	display: grid;
+	gap: 1.75rem;
+}
+
+@media (min-width: 960px) {
+	.wf-story-step {
+		grid-template-columns: minmax(15rem, 0.9fr) 1.4fr;
+		gap: 2.75rem;
+		align-items: start;
+	}
+}
+
+.wf-story-copy h2 {
+	margin: 0 0 0.9rem;
+	font-family: var(--wf-serif);
+	font-size: clamp(1.4rem, 2.6vw, 1.8rem);
+	font-weight: 500;
+	letter-spacing: -0.02em;
+	line-height: 1.22;
+	color: var(--wf-ink);
+}
+
+.wf-why {
+	margin: 0 0 1.15rem;
+	font-size: 1.01rem;
+	line-height: 1.65;
+	color: var(--wf-ink-soft);
+}
+
+.wf-sample-path {
+	font-family: var(--wf-mono);
+	font-size: 0.72rem;
+	color: var(--wf-ink-muted);
+	display: block;
+	line-height: 1.45;
+}
+
+.wf-cta-band .wf-cta {
+	text-align: left;
+	max-width: var(--wf-measure);
+	margin: 0;
+}
+
+.wf-cta-band h2 {
+	margin: 0 0 0.75rem;
+	font-family: var(--wf-serif);
+	font-size: clamp(1.5rem, 3vw, 1.9rem);
+	font-weight: 500;
+	color: var(--wf-band-dark-ink);
+}
+
+.wf-cta-band p {
+	margin: 0 0 1.65rem;
+	color: var(--wf-band-dark-soft);
+}
+
+.wf-cta-band .wf-actions {
+	justify-content: flex-start;
+	margin-bottom: 0;
+}
+
+/* Story cards — airy */
+.wf-cards {
+	display: grid;
+	gap: 1.25rem;
+}
+
+@media (min-width: 768px) {
+	.wf-cards {
+		grid-template-columns: repeat(3, 1fr);
+		gap: 1.5rem;
+	}
+}
+
+.wf-card {
+	background: var(--wf-bg-elevated);
+	border: 1px solid var(--wf-line);
+	border-radius: var(--wf-radius);
+	padding: 1.75rem 1.5rem;
+}
+
+.wf-card h3 {
+	margin: 0 0 0.65rem;
+	font-size: 1rem;
+	font-weight: 600;
+	letter-spacing: -0.015em;
+}
+
+.wf-card p {
+	margin: 0;
+	font-size: 0.94rem;
+	line-height: 1.6;
+	color: var(--wf-ink-soft);
+}
+
+.wf-card code {
+	font-size: 0.86em;
+	background: rgba(28, 28, 26, 0.05);
+	padding: 0.08em 0.28em;
+	border-radius: 3px;
+}
+
+.wf-card-list {
+	margin: 0;
+	padding-left: 1.1rem;
+	display: grid;
+	gap: 0.45rem;
+	font-size: 0.9rem;
+	line-height: 1.5;
+	color: var(--wf-ink-soft);
+}
+
+.wf-card-list li::marker {
+	color: var(--wf-ink-muted);
+}
+
+/* —— Home field guide (long-form index) —— */
+.wf-toc {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.35rem 0.15rem;
+	margin-top: 2.25rem;
+	padding-top: 1.35rem;
+	border-top: 1px solid var(--wf-line);
+	max-width: none;
+}
+
+.wf-toc a {
+	font-family: var(--wf-mono);
+	font-size: 0.68rem;
+	font-weight: 500;
+	letter-spacing: 0.04em;
+	text-transform: uppercase;
+	text-decoration: none;
+	color: var(--wf-ink-muted);
+	padding: 0.35rem 0.55rem;
+	border-radius: 4px;
+	border: 1px solid transparent;
+	transition:
+		color 0.15s var(--ease),
+		background 0.15s var(--ease),
+		border-color 0.15s var(--ease);
+}
+
+.wf-toc a:hover {
+	color: var(--wf-ink);
+	background: rgba(28, 28, 26, 0.04);
+	border-color: var(--wf-line);
+}
+
+.wf-section-head-wide {
+	max-width: min(48rem, 100%);
+}
+
+.wf-principles {
+	list-style: none;
+	margin: 0;
+	padding: 0;
+	display: flex;
+	flex-direction: column;
+	border-top: 1px solid var(--wf-line);
+}
+
+.wf-principle {
+	display: grid;
+	grid-template-columns: 2.5rem minmax(0, 1fr);
+	gap: 0.85rem 1.25rem;
+	padding: 1.35rem 0;
+	border-bottom: 1px solid var(--wf-line);
+}
+
+@media (min-width: 768px) {
+	.wf-principle {
+		grid-template-columns: 3rem minmax(0, 1fr);
+		gap: 1rem 1.75rem;
+		padding: 1.55rem 0;
+	}
+}
+
+.wf-principle-n {
+	font-family: var(--wf-mono);
+	font-size: 0.72rem;
+	font-weight: 500;
+	letter-spacing: 0.06em;
+	color: var(--wf-ink-muted);
+	padding-top: 0.2rem;
+}
+
+.wf-principle h3 {
+	margin: 0 0 0.4rem;
+	font-family: var(--wf-serif);
+	font-size: 1.12rem;
+	font-weight: 500;
+	letter-spacing: -0.02em;
+	line-height: 1.25;
+	color: var(--wf-ink);
+}
+
+.wf-principle p {
+	margin: 0;
+	max-width: 44rem;
+	font-size: 0.95rem;
+	line-height: 1.6;
+	color: var(--wf-ink-soft);
+}
+
+.wf-subhead {
+	margin: 3.25rem 0 1.35rem;
+	max-width: var(--wf-measure);
+	padding-top: 0.25rem;
+	border-top: 1px solid var(--wf-line);
+	padding-top: 1.75rem;
+}
+
+.wf-subhead h3 {
+	margin: 0 0 0.55rem;
+	font-family: var(--wf-serif);
+	font-size: clamp(1.2rem, 2.2vw, 1.45rem);
+	font-weight: 500;
+	letter-spacing: -0.02em;
+	line-height: 1.25;
+	color: var(--wf-ink);
+}
+
+.wf-subhead p {
+	margin: 0;
+	font-size: 0.98rem;
+	line-height: 1.6;
+	color: var(--wf-ink-soft);
+}
+
+.wf-subhead code {
+	font-size: 0.88em;
+	background: rgba(28, 28, 26, 0.05);
+	padding: 0.1em 0.3em;
+	border-radius: 3px;
+}
+
+.wf-layers {
+	display: grid;
+	gap: 1rem;
+}
+
+@media (min-width: 900px) {
+	.wf-layers {
+		grid-template-columns: repeat(3, 1fr);
+		gap: 1.15rem;
+	}
+}
+
+.wf-layer {
+	position: relative;
+	padding: 1.35rem 1.25rem 1.4rem;
+	background: var(--wf-bg-elevated);
+	border: 1px solid var(--wf-line);
+	border-radius: var(--wf-radius);
+	border-top: 2px solid var(--wf-ink);
+}
+
+.wf-layer-n {
+	display: block;
+	font-family: var(--wf-mono);
+	font-size: 0.68rem;
+	letter-spacing: 0.1em;
+	color: var(--wf-ink-muted);
+	margin-bottom: 0.65rem;
+}
+
+.wf-layer h4 {
+	margin: 0 0 0.75rem;
+	font-size: 1.02rem;
+	font-weight: 600;
+	letter-spacing: -0.015em;
+	line-height: 1.3;
+	color: var(--wf-ink);
+}
+
+.wf-layer-body {
+	margin: 0;
+	font-size: 0.92rem;
+	line-height: 1.6;
+	color: var(--wf-ink-soft);
+}
+
+.wf-cards-tight {
+	gap: 1rem;
+}
+
+.wf-card-kicker {
+	display: block;
+	font-family: var(--wf-mono);
+	font-size: 0.65rem;
+	font-weight: 500;
+	letter-spacing: 0.1em;
+	text-transform: uppercase;
+	color: var(--wf-ink-muted);
+	margin-bottom: 0.55rem;
+}
+
+.wf-card-accent {
+	border-top: 2px solid var(--wf-accent);
+}
+
+.wf-code-lead {
+	margin-bottom: 0.25rem;
+}
+
+.wf-code-follow {
+	margin-top: 1.5rem;
+}
+
+.wf-crate-map {
+	margin: 0;
+	padding: 0;
+	border-top: 1px solid var(--wf-line);
+}
+
+.wf-crate {
+	display: grid;
+	gap: 0.25rem;
+	padding: 0.95rem 0;
+	border-bottom: 1px solid var(--wf-line);
+}
+
+@media (min-width: 720px) {
+	.wf-crate {
+		grid-template-columns: minmax(12rem, 0.42fr) minmax(0, 1fr);
+		gap: 1.25rem 2rem;
+		align-items: baseline;
+		padding: 1.05rem 0;
+	}
+}
+
+.wf-crate dt {
+	margin: 0;
+	font-family: var(--wf-mono);
+	font-size: 0.78rem;
+	font-weight: 500;
+	letter-spacing: 0.02em;
+	color: var(--wf-ink);
+}
+
+.wf-crate dd {
+	margin: 0;
+	font-size: 0.92rem;
+	line-height: 1.5;
+	color: var(--wf-ink-soft);
+}
+
+.wf-chapter {
+	margin-top: 2.75rem;
+	display: flex;
+	flex-direction: column;
+	gap: 0;
+	border-top: 1px solid var(--wf-line);
+}
+
+.wf-chapter .wf-story-step {
+	padding: 2.25rem 0;
+	border-bottom: 1px solid var(--wf-line);
+}
+
+.wf-chapter .wf-story-step:last-child {
+	border-bottom: none;
+	padding-bottom: 0.5rem;
+}
+
+.wf-step-title {
+	margin: 0 0 0.85rem;
+	font-family: var(--wf-serif);
+	font-size: clamp(1.25rem, 2.4vw, 1.55rem);
+	font-weight: 500;
+	letter-spacing: -0.02em;
+	line-height: 1.22;
+	color: var(--wf-ink);
+}
+
+/* Run steps */
+.wf-run {
+	background: var(--wf-bg-elevated);
+	border-top: 1px solid var(--wf-line);
+	border-bottom: 1px solid var(--wf-line);
+	padding: var(--wf-section-y) var(--wf-gutter);
+}
+
+.wf-run-inner {
+	max-width: var(--wf-max);
+	margin: 0 auto;
+}
+
+.wf-run .wf-section-head {
+	margin-bottom: 2.5rem;
+}
+
+.wf-steps {
+	display: grid;
+	gap: 1.5rem;
+	counter-reset: step;
+}
+
+@media (min-width: 768px) {
+	.wf-steps {
+		grid-template-columns: repeat(3, 1fr);
+		gap: 2rem;
+	}
+}
+
+.wf-step {
+	counter-increment: step;
+	padding-top: 0.25rem;
+	border-top: 1px solid var(--wf-line-strong);
+}
+
+.wf-step::before {
+	content: '0' counter(step);
+	display: block;
+	font-family: var(--wf-mono);
+	font-size: 0.7rem;
+	letter-spacing: 0.08em;
+	color: var(--wf-ink-muted);
+	margin: 1rem 0 0.85rem;
+}
+
+.wf-step h3 {
+	margin: 0 0 0.5rem;
+	font-size: 1rem;
+	font-weight: 600;
+}
+
+.wf-step p {
+	margin: 0;
+	font-size: 0.92rem;
+	line-height: 1.6;
+	color: var(--wf-ink-soft);
+}
+
+.wf-step code {
+	font-size: 0.86em;
+	background: rgba(28, 28, 26, 0.05);
+	padding: 0.08em 0.28em;
+	border-radius: 3px;
+}
+
+/* Demo list */
+.wf-demos {
+	display: flex;
+	flex-direction: column;
+	gap: 0;
+}
+
+.wf-demo {
+	display: grid;
+	gap: 0.5rem 1.5rem;
+	padding: 1.75rem 0;
+	border-bottom: 1px solid var(--wf-line);
+	text-decoration: none;
+	color: inherit;
+}
+
+.wf-demo:first-child {
+	border-top: 1px solid var(--wf-line);
+}
+
+.wf-demo:hover h3 {
+	color: var(--wf-accent);
+}
+
+@media (min-width: 768px) {
+	.wf-demo {
+		grid-template-columns: 2.5rem 1fr auto;
+		align-items: start;
+		padding: 2rem 0;
+		gap: 1.5rem 2rem;
+	}
+}
+
+.wf-demo-i {
+	font-family: var(--wf-mono);
+	font-size: 0.75rem;
+	color: var(--wf-ink-muted);
+	padding-top: 0.2rem;
+}
+
+.wf-demo h3 {
+	margin: 0 0 0.4rem;
+	font-size: 1.05rem;
+	font-weight: 600;
+	letter-spacing: -0.015em;
+	color: var(--wf-ink);
+	transition: color 0.15s ease;
+}
+
+.wf-demo p {
+	margin: 0 0 0.5rem;
+	font-size: 0.94rem;
+	line-height: 1.55;
+	color: var(--wf-ink-soft);
+	max-width: 38rem;
+}
+
+.wf-demo-where {
+	font-family: var(--wf-mono);
+	font-size: 0.7rem;
+	color: var(--wf-ink-muted);
+}
+
+.wf-demo-go {
+	font-size: 0.875rem;
+	font-weight: 600;
+	color: var(--wf-accent);
+	white-space: nowrap;
+	padding-top: 0.15rem;
+}
+
+/* Architecture code samples */
+.wf-arch {
+	display: flex;
+	flex-direction: column;
+	gap: 2.75rem;
+}
+
+.wf-sample {
+	display: grid;
+	gap: 1rem;
+}
+
+@media (min-width: 900px) {
+	.wf-sample {
+		grid-template-columns: minmax(12rem, 0.85fr) 1.4fr;
+		gap: 2.5rem;
+		align-items: start;
+	}
+}
+
+.wf-sample-meta h3 {
+	margin: 0 0 0.5rem;
+	font-size: 1.05rem;
+	font-weight: 600;
+	letter-spacing: -0.015em;
+}
+
+.wf-sample-meta p {
+	margin: 0 0 0.75rem;
+	font-size: 0.92rem;
+	line-height: 1.55;
+	color: var(--wf-ink-soft);
+}
+
+.wf-sample-path {
+	font-family: var(--wf-mono);
+	font-size: 0.7rem;
+	color: var(--wf-ink-muted);
+	display: block;
+	line-height: 1.45;
+}
+
+/* Stack of single-file samples (one concept per block) */
+.wf-code-stack {
+	display: flex;
+	flex-direction: column;
+	gap: 1rem;
+	min-width: 0;
+}
+
+.wf-code {
+	background: var(--wf-code-bg);
+	border: 1px solid #2a2a28;
+	border-radius: var(--wf-radius);
+	overflow: hidden;
+}
+
+.wf-code-bar {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	padding: 0.5rem 0.9rem;
+	border-bottom: 1px solid #2a2a28;
+	background: #141412;
+}
+
+.wf-code-bar span {
+	font-family: var(--wf-mono);
+	font-size: 0.68rem;
+	color: var(--wf-code-muted);
+}
+
+.wf-code-bar em {
+	font-style: normal;
+	font-family: var(--wf-mono);
+	font-size: 0.62rem;
+	letter-spacing: 0.08em;
+	text-transform: uppercase;
+	color: #9ec5e8;
+}
+
+.wf-code pre {
+	margin: 0;
+	padding: 1.15rem 1.1rem 1.25rem;
+	overflow-x: auto;
+	font-size: 0.78rem;
+	line-height: 1.6;
+	color: var(--wf-code-fg);
+	background: transparent;
+	tab-size: 2;
+}
+
+/* No pill/highlight on block samples — only the .wf-code surface */
+.wf-code code {
+	background: transparent;
+	border: none;
+	padding: 0;
+	border-radius: 0;
+	color: inherit;
+	font-size: inherit;
+}
+
+/* CTA (standalone light-page variant; band CTA uses .wf-cta-band overrides) */
+.wf-cta:not(.wf-band-inner) {
+	padding: var(--wf-section-y) var(--wf-gutter);
+	text-align: center;
+	max-width: var(--wf-max);
+	margin: 0 auto;
+}
+
+.wf-cta:not(.wf-band-inner) h2 {
+	margin: 0 0 0.75rem;
+	font-family: var(--wf-serif);
+	font-size: clamp(1.5rem, 3vw, 1.9rem);
+	font-weight: 500;
+	letter-spacing: -0.02em;
+}
+
+.wf-cta:not(.wf-band-inner) p {
+	margin: 0 auto 1.75rem;
+	max-width: 28rem;
+	color: var(--wf-ink-soft);
+	font-size: 1rem;
+	line-height: 1.6;
+}
+
+.wf-cta:not(.wf-band-inner) .wf-actions {
+	justify-content: center;
+	margin-bottom: 0;
+}
+
+/*
+ * Dark-band type cascade — LAST among home rules so it beats later light defaults
+ * (.wf-section-head h2, .wf-demo h3, .wf-story-copy h2, etc.).
+ * Headings use cream ink on lifted charcoal ground — never same as band bg.
+ */
+.wf-band-dark .wf-label {
+	color: var(--wf-band-dark-muted);
+}
+
+/* Triple-class selectors outrank any later single-class h2 ink rules */
+.wf-home .wf-band-dark h2,
+.wf-home .wf-band-dark .wf-section-head h2,
+.wf-home .wf-band-dark .wf-story-copy h2,
+.wf-home .wf-band-dark .wf-cta h2,
+.wf-home .wf-band-dark.wf-cta-band h2 {
+	color: var(--wf-band-dark-ink);
+}
+
+.wf-band-dark .wf-section-head p,
+.wf-band-dark .wf-why,
+.wf-band-dark .wf-step p,
+.wf-band-dark .wf-demo p,
+.wf-band-dark .wf-card p,
+.wf-band-dark .wf-card-list,
+.wf-band-dark .wf-layer-body,
+.wf-band-dark .wf-flow-map,
+.wf-band-dark .wf-cta p,
+.wf-band-dark .wf-principle p,
+.wf-band-dark .wf-subhead p,
+.wf-band-dark .wf-crate dd,
+.wf-band-dark .wf-why {
+	color: var(--wf-band-dark-soft);
+}
+
+.wf-band-dark .wf-demo-where,
+.wf-band-dark .wf-sample-path,
+.wf-band-dark .wf-demo-i,
+.wf-band-dark .wf-meta,
+.wf-band-dark .wf-step::before,
+.wf-band-dark .wf-principle-n,
+.wf-band-dark .wf-layer-n,
+.wf-band-dark .wf-card-kicker,
+.wf-band-dark .wf-toc a {
+	color: var(--wf-band-dark-muted);
+}
+
+.wf-band-dark .wf-card,
+.wf-band-dark .wf-layer {
+	background: var(--wf-band-dark-elev);
+	border-color: var(--wf-band-dark-line);
+}
+
+.wf-band-dark .wf-layer {
+	border-top-color: var(--wf-band-dark-ink);
+}
+
+.wf-band-dark .wf-card-accent {
+	border-top-color: #9ec5e8;
+}
+
+.wf-band-dark .wf-card h3,
+.wf-band-dark .wf-step h3,
+.wf-band-dark .wf-demo h3,
+.wf-band-dark .wf-principle h3,
+.wf-band-dark .wf-subhead h3,
+.wf-band-dark .wf-layer h4,
+.wf-band-dark .wf-step-title,
+.wf-band-dark .wf-crate dt {
+	color: var(--wf-band-dark-ink);
+}
+
+.wf-band-dark .wf-principles,
+.wf-band-dark .wf-principle,
+.wf-band-dark .wf-crate-map,
+.wf-band-dark .wf-crate,
+.wf-band-dark .wf-subhead,
+.wf-band-dark .wf-chapter,
+.wf-band-dark .wf-chapter .wf-story-step {
+	border-color: var(--wf-band-dark-line);
+}
+
+.wf-band-dark .wf-toc {
+	border-top-color: var(--wf-band-dark-line);
+}
+
+.wf-band-dark .wf-toc a:hover {
+	color: var(--wf-band-dark-ink);
+	background: rgba(255, 255, 255, 0.05);
+	border-color: var(--wf-band-dark-line);
+}
+
+.wf-band-dark .wf-subhead code {
+	background: rgba(255, 255, 255, 0.07);
+	border: 1px solid var(--wf-band-dark-line);
+	color: var(--wf-band-dark-ink);
+}
+
+.wf-band-dark .wf-step {
+	border-top-color: var(--wf-band-dark-line);
+}
+
+.wf-band-dark .wf-demo {
+	border-bottom-color: var(--wf-band-dark-line);
+}
+
+.wf-band-dark .wf-demo:first-child {
+	border-top-color: var(--wf-band-dark-line);
+}
+
+.wf-band-dark .wf-demo:hover h3 {
+	color: #b8d4ef;
+}
+
+.wf-band-dark .wf-demo-go {
+	color: #b8d4ef;
+}
+
+.wf-band-dark .wf-btn-ghost {
+	color: var(--wf-band-dark-ink);
+	border-color: rgba(244, 242, 236, 0.28);
+}
+
+.wf-band-dark .wf-btn-ghost:hover {
+	border-color: rgba(244, 242, 236, 0.55);
+	background: rgba(255, 255, 255, 0.05);
+}
+
+.wf-band-dark .wf-btn-primary {
+	background: var(--wf-band-dark-ink);
+	color: var(--wf-band-dark-bg);
+	border-color: var(--wf-band-dark-ink);
+}
+
+.wf-band-dark .wf-btn-primary:hover {
+	background: #fff;
+	border-color: #fff;
+}
+
+/* Inline code only — never paint a second bg on .wf-code pre > code */
+.wf-band-dark :not(pre) > code,
+.wf-band-dark .wf-section-head code,
+.wf-band-dark .wf-step code,
+.wf-band-dark .wf-card code,
+.wf-band-dark .wf-why code,
+.wf-band-dark .wf-story-copy code {
+	background: rgba(255, 255, 255, 0.07);
+	border: 1px solid var(--wf-band-dark-line);
+	color: var(--wf-band-dark-ink);
+}
+
+.wf-band-dark .wf-flow-map li::marker {
+	color: #9ec5e8;
+}
+
+.wf-band-light .wf-code {
+	box-shadow: 0 12px 32px rgba(28, 28, 26, 0.08);
+}
+
+.wf-band-dark .wf-code {
+	border-color: #1a1a18;
+	box-shadow: 0 16px 40px rgba(0, 0, 0, 0.28);
+}
+
+/* Keep block samples free of dark-band inline-code chrome */
+.wf-band-dark .wf-code code,
+.wf-band-dark .wf-code pre {
+	background: transparent;
+	border: none;
+	color: var(--wf-code-fg);
+}
+
diff --git a/tests/e2e-ui/ui/src/routes/+error.svelte b/tests/e2e-ui/ui/src/routes/+error.svelte
new file mode 100644
index 00000000..b6da2586
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/+error.svelte
@@ -0,0 +1,692 @@
+<script lang="ts">
+	import { browser } from '$app/environment';
+	import { page } from '$app/state';
+	import { Button } from '$lib/components/shared/ui';
+
+	let mounted = $state(false);
+	let glitchActive = $state(false);
+	let terminalLines = $state<string[]>([]);
+
+	const errorMessages = [
+		'kubectl get page --namespace=internet',
+		'Error: resource "page" not found',
+		'Checking alternate dimensions...',
+		'Querying the multiverse...',
+		'404: The requested resource has yeeted itself into the void',
+		'',
+		'SUGGESTION: Did you mean /home?'
+	];
+
+	// Svelte 5: prefer $effect over onMount for client-only setup.
+	$effect(() => {
+		if (!browser) return;
+
+		mounted = true;
+		let lineIndex = 0;
+		let typeTimer: ReturnType<typeof setTimeout> | undefined;
+		const typeNextLine = () => {
+			if (lineIndex < errorMessages.length) {
+				terminalLines = [...terminalLines, errorMessages[lineIndex]!];
+				lineIndex++;
+				typeTimer = setTimeout(typeNextLine, lineIndex === 1 ? 800 : 400);
+			}
+		};
+		const startTimer = setTimeout(typeNextLine, 600);
+
+		const glitchInterval = setInterval(() => {
+			glitchActive = true;
+			setTimeout(() => (glitchActive = false), 150);
+		}, 3000 + Math.random() * 2000);
+
+		return () => {
+			clearTimeout(startTimer);
+			if (typeTimer) clearTimeout(typeTimer);
+			clearInterval(glitchInterval);
+		};
+	});
+
+	const status = $derived(page.status);
+	const message = $derived(page.error?.message || 'Page not found');
+</script>
+
+<svelte:head>
+	<title>{status} | Hops</title>
+</svelte:head>
+
+<div class="error-page" class:mounted class:glitch={glitchActive}>
+	<!-- Scan lines overlay -->
+	<div class="scanlines"></div>
+
+	<!-- Floating particles -->
+	<div class="particles">
+		{#each Array(12) as _, i (i)}
+			<div
+				class="particle"
+				style="--delay: {i * 0.3}s; --x: {Math.random() * 100}%; --duration: {8 + Math.random() * 6}s"
+			></div>
+		{/each}
+	</div>
+
+	<div class="error-content">
+		<!-- ASCII Art 404 -->
+		<div class="ascii-block">
+			<pre class="ascii-art" aria-hidden="true">{`
+    ██╗  ██╗ ██████╗ ██╗  ██╗
+    ██║  ██║██╔═████╗██║  ██║
+    ███████║██║██╔██║███████║
+    ╚════██║████╔╝██║╚════██║
+         ██║╚██████╔╝     ██║
+         ╚═╝ ╚═════╝      ╚═╝
+`}</pre>
+			<div class="glitch-layers" aria-hidden="true">
+				<pre class="ascii-art glitch-1">{`
+    ██╗  ██╗ ██████╗ ██╗  ██╗
+    ██║  ██║██╔═████╗██║  ██║
+    ███████║██║██╔██║███████║
+    ╚════██║████╔╝██║╚════██║
+         ██║╚██████╔╝     ██║
+         ╚═╝ ╚═════╝      ╚═╝
+`}</pre>
+				<pre class="ascii-art glitch-2">{`
+    ██╗  ██╗ ██████╗ ██╗  ██╗
+    ██║  ██║██╔═████╗██║  ██║
+    ███████║██║██╔██║███████║
+    ╚════██║████╔╝██║╚════██║
+         ██║╚██████╔╝     ██║
+         ╚═╝ ╚═════╝      ╚═╝
+`}</pre>
+			</div>
+		</div>
+
+		<!-- Hop character -->
+		<div class="hop-character">
+			<div class="hop-body">
+				<div class="hop-leaf hop-leaf-1"></div>
+				<div class="hop-leaf hop-leaf-2"></div>
+				<div class="hop-leaf hop-leaf-3"></div>
+				<div class="hop-cone"></div>
+				<div class="hop-face">
+					<div class="hop-eye hop-eye-left"></div>
+					<div class="hop-eye hop-eye-right"></div>
+					<div class="hop-mouth"></div>
+				</div>
+			</div>
+			<div class="hop-shadow"></div>
+		</div>
+
+		<!-- Terminal window -->
+		<div class="terminal">
+			<div class="terminal-header">
+				<div class="terminal-dots">
+					<span class="dot dot-red"></span>
+					<span class="dot dot-yellow"></span>
+					<span class="dot dot-green"></span>
+				</div>
+				<span class="terminal-title">hops-cluster ~ lost-pod</span>
+			</div>
+			<div class="terminal-body">
+				{#each terminalLines as line, i (i)}
+					<div class="terminal-line" style="--line-delay: {i * 0.1}s">
+						{#if i === 0}
+							<span class="prompt">$</span>
+						{/if}
+						<span class:error-text={line.includes('Error') || line.includes('404')} class:suggestion={line.includes('SUGGESTION')}>
+							{line}
+						</span>
+						{#if i === terminalLines.length - 1 && terminalLines.length < errorMessages.length}
+							<span class="cursor"></span>
+						{/if}
+					</div>
+				{/each}
+				{#if terminalLines.length === 0}
+					<div class="terminal-line">
+						<span class="prompt">$</span>
+						<span class="cursor"></span>
+					</div>
+				{/if}
+			</div>
+		</div>
+
+		<!-- Message and CTA -->
+		<div class="error-message">
+			<h1 class="error-title">
+				Lost in the Cluster
+			</h1>
+			<p class="error-subtitle">
+				This page doesn't exist in any namespace we control.
+				<br />
+				Maybe it was never deployed, or perhaps it drifted into the void.
+			</p>
+		</div>
+
+		<div class="error-actions">
+			<Button href="/" variant="primary" size="lg">
+				<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+					<path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/>
+					<polyline points="9 22 9 12 15 12 15 22"/>
+				</svg>
+				Back to Home
+			</Button>
+			<Button href="/launch" variant="outlined" size="lg">
+				Launch a Platform Instead
+			</Button>
+		</div>
+
+		<!-- Fun stats -->
+		<div class="fun-stats">
+			<div class="stat">
+				<span class="stat-value">0</span>
+				<span class="stat-label">pods found</span>
+			</div>
+			<div class="stat">
+				<span class="stat-value">{status}</span>
+				<span class="stat-label">status code</span>
+			</div>
+			<div class="stat">
+				<span class="stat-value">100%</span>
+				<span class="stat-label">confusion</span>
+			</div>
+		</div>
+	</div>
+</div>
+
+<style>
+/* Base layout */
+.error-page {
+	min-height: 100vh;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	background: var(--hops-navy-deep);
+	position: relative;
+	overflow: hidden;
+	padding: 2rem;
+	padding-top: 7rem; /* Account for navbar (5rem) + breathing room */
+}
+
+/* Scanline effect */
+.scanlines {
+	position: absolute;
+	inset: 0;
+	background: repeating-linear-gradient(
+		0deg,
+		transparent,
+		transparent 2px,
+		rgba(0, 0, 0, 0.1) 2px,
+		rgba(0, 0, 0, 0.1) 4px
+	);
+	pointer-events: none;
+	z-index: 100;
+}
+
+/* Floating particles */
+.particles {
+	position: absolute;
+	inset: 0;
+	overflow: hidden;
+	pointer-events: none;
+}
+
+.particle {
+	position: absolute;
+	width: 4px;
+	height: 4px;
+	background: var(--hops-orange);
+	border-radius: 50%;
+	left: var(--x);
+	bottom: -20px;
+	opacity: 0.3;
+	animation: floatUp var(--duration) ease-in-out infinite;
+	animation-delay: var(--delay);
+}
+
+@keyframes floatUp {
+	0% {
+		transform: translateY(0) rotate(0deg);
+		opacity: 0;
+	}
+	10% {
+		opacity: 0.4;
+	}
+	90% {
+		opacity: 0.4;
+	}
+	100% {
+		transform: translateY(-100vh) rotate(360deg);
+		opacity: 0;
+	}
+}
+
+/* Content container */
+.error-content {
+	position: relative;
+	z-index: 10;
+	text-align: center;
+	max-width: 700px;
+	width: 100%;
+	opacity: 0;
+	transform: translateY(30px);
+	transition: all 0.8s var(--ease-out-expo);
+}
+
+.mounted .error-content {
+	opacity: 1;
+	transform: translateY(0);
+}
+
+/* ASCII Art Block */
+.ascii-block {
+	position: relative;
+	margin-bottom: 2rem;
+}
+
+.ascii-art {
+	font-family: var(--font-mono);
+	font-size: clamp(0.4rem, 2vw, 0.7rem);
+	line-height: 1.1;
+	color: var(--hops-orange);
+	margin: 0;
+	white-space: pre;
+	text-shadow: 0 0 20px rgba(230, 154, 45, 0.5);
+}
+
+.glitch-layers {
+	position: absolute;
+	inset: 0;
+	pointer-events: none;
+}
+
+.glitch-1,
+.glitch-2 {
+	position: absolute;
+	top: 0;
+	left: 0;
+	opacity: 0;
+}
+
+.glitch .glitch-1 {
+	opacity: 0.8;
+	transform: translateX(-3px);
+	color: #ff6b6b;
+	animation: glitchShift1 0.15s steps(2) infinite;
+}
+
+.glitch .glitch-2 {
+	opacity: 0.8;
+	transform: translateX(3px);
+	color: #4ecdc4;
+	animation: glitchShift2 0.15s steps(2) infinite;
+}
+
+@keyframes glitchShift1 {
+	0%, 100% { clip-path: inset(40% 0 20% 0); transform: translateX(-3px); }
+	50% { clip-path: inset(10% 0 60% 0); transform: translateX(3px); }
+}
+
+@keyframes glitchShift2 {
+	0%, 100% { clip-path: inset(20% 0 40% 0); transform: translateX(3px); }
+	50% { clip-path: inset(60% 0 10% 0); transform: translateX(-3px); }
+}
+
+/* Hop Character */
+.hop-character {
+	position: relative;
+	width: 80px;
+	height: 100px;
+	margin: 0 auto 2rem;
+	animation: hopBounce 2s ease-in-out infinite;
+}
+
+@keyframes hopBounce {
+	0%, 100% { transform: translateY(0); }
+	50% { transform: translateY(-15px); }
+}
+
+.hop-body {
+	position: relative;
+	width: 60px;
+	height: 80px;
+	margin: 0 auto;
+}
+
+.hop-cone {
+	position: absolute;
+	bottom: 0;
+	left: 50%;
+	transform: translateX(-50%);
+	width: 50px;
+	height: 65px;
+	background: linear-gradient(135deg, #7cb342 0%, #558b2f 50%, #33691e 100%);
+	border-radius: 50% 50% 45% 45% / 60% 60% 40% 40%;
+	box-shadow: inset -8px -8px 20px rgba(0, 0, 0, 0.2),
+	            inset 5px 5px 15px rgba(255, 255, 255, 0.1);
+}
+
+.hop-cone::before {
+	content: '';
+	position: absolute;
+	top: 10%;
+	left: 15%;
+	right: 15%;
+	bottom: 20%;
+	background: repeating-linear-gradient(
+		-30deg,
+		transparent,
+		transparent 3px,
+		rgba(255, 255, 255, 0.1) 3px,
+		rgba(255, 255, 255, 0.1) 6px
+	);
+	border-radius: inherit;
+}
+
+.hop-leaf {
+	position: absolute;
+	width: 20px;
+	height: 30px;
+	background: linear-gradient(135deg, #8bc34a 0%, #689f38 100%);
+	border-radius: 50% 50% 50% 50% / 60% 60% 40% 40%;
+}
+
+.hop-leaf-1 {
+	top: -5px;
+	left: 50%;
+	transform: translateX(-50%) rotate(-10deg);
+	animation: leafWave1 3s ease-in-out infinite;
+}
+
+.hop-leaf-2 {
+	top: 5px;
+	left: -5px;
+	transform: rotate(-40deg);
+	animation: leafWave2 3s ease-in-out infinite 0.5s;
+}
+
+.hop-leaf-3 {
+	top: 5px;
+	right: -5px;
+	transform: rotate(40deg);
+	animation: leafWave3 3s ease-in-out infinite 1s;
+}
+
+@keyframes leafWave1 {
+	0%, 100% { transform: translateX(-50%) rotate(-10deg); }
+	50% { transform: translateX(-50%) rotate(10deg); }
+}
+
+@keyframes leafWave2 {
+	0%, 100% { transform: rotate(-40deg); }
+	50% { transform: rotate(-30deg); }
+}
+
+@keyframes leafWave3 {
+	0%, 100% { transform: rotate(40deg); }
+	50% { transform: rotate(30deg); }
+}
+
+.hop-face {
+	position: absolute;
+	top: 35%;
+	left: 50%;
+	transform: translateX(-50%);
+	width: 35px;
+	height: 25px;
+}
+
+.hop-eye {
+	position: absolute;
+	top: 0;
+	width: 8px;
+	height: 10px;
+	background: #1a2744;
+	border-radius: 50%;
+	animation: blink 4s ease-in-out infinite;
+}
+
+.hop-eye-left {
+	left: 5px;
+}
+
+.hop-eye-right {
+	right: 5px;
+}
+
+.hop-eye::after {
+	content: '';
+	position: absolute;
+	top: 2px;
+	right: 1px;
+	width: 3px;
+	height: 3px;
+	background: white;
+	border-radius: 50%;
+}
+
+@keyframes blink {
+	0%, 45%, 55%, 100% { transform: scaleY(1); }
+	50% { transform: scaleY(0.1); }
+}
+
+.hop-mouth {
+	position: absolute;
+	bottom: 0;
+	left: 50%;
+	transform: translateX(-50%);
+	width: 12px;
+	height: 6px;
+	border: 2px solid #1a2744;
+	border-top: none;
+	border-radius: 0 0 12px 12px;
+}
+
+.hop-shadow {
+	position: absolute;
+	bottom: -10px;
+	left: 50%;
+	transform: translateX(-50%);
+	width: 40px;
+	height: 10px;
+	background: rgba(0, 0, 0, 0.3);
+	border-radius: 50%;
+	animation: shadowPulse 2s ease-in-out infinite;
+}
+
+@keyframes shadowPulse {
+	0%, 100% { transform: translateX(-50%) scale(1); opacity: 0.3; }
+	50% { transform: translateX(-50%) scale(0.7); opacity: 0.5; }
+}
+
+/* Terminal */
+.terminal {
+	background: rgba(15, 24, 41, 0.9);
+	border: 1px solid rgba(230, 154, 45, 0.3);
+	border-radius: 12px;
+	overflow: hidden;
+	text-align: left;
+	margin-bottom: 2.5rem;
+	box-shadow: 0 20px 60px rgba(0, 0, 0, 0.4),
+	            0 0 40px rgba(230, 154, 45, 0.1);
+}
+
+.terminal-header {
+	display: flex;
+	align-items: center;
+	gap: 1rem;
+	padding: 0.75rem 1rem;
+	background: rgba(26, 39, 68, 0.8);
+	border-bottom: 1px solid rgba(255, 255, 255, 0.1);
+}
+
+.terminal-dots {
+	display: flex;
+	gap: 6px;
+}
+
+.dot {
+	width: 12px;
+	height: 12px;
+	border-radius: 50%;
+}
+
+.dot-red { background: #ff5f56; }
+.dot-yellow { background: #ffbd2e; }
+.dot-green { background: #27ca40; }
+
+.terminal-title {
+	font-family: var(--font-mono);
+	font-size: 0.75rem;
+	color: rgba(255, 255, 255, 0.5);
+}
+
+.terminal-body {
+	padding: 1.25rem;
+	min-height: 160px;
+}
+
+.terminal-line {
+	font-family: var(--font-mono);
+	font-size: 0.85rem;
+	color: rgba(255, 255, 255, 0.8);
+	line-height: 1.8;
+	animation: lineAppear 0.3s ease-out both;
+	animation-delay: var(--line-delay);
+}
+
+@keyframes lineAppear {
+	from {
+		opacity: 0;
+		transform: translateY(5px);
+	}
+	to {
+		opacity: 1;
+		transform: translateY(0);
+	}
+}
+
+.prompt {
+	color: var(--hops-orange);
+	margin-right: 0.5rem;
+}
+
+.error-text {
+	color: #ff6b6b;
+}
+
+.suggestion {
+	color: #4ecdc4;
+}
+
+.cursor {
+	display: inline-block;
+	width: 8px;
+	height: 16px;
+	background: var(--hops-orange);
+	margin-left: 2px;
+	animation: cursorBlink 1s steps(1) infinite;
+	vertical-align: text-bottom;
+}
+
+@keyframes cursorBlink {
+	0%, 50% { opacity: 1; }
+	51%, 100% { opacity: 0; }
+}
+
+/* Message */
+.error-message {
+	margin-bottom: 2rem;
+}
+
+.error-title {
+	font-family: var(--font-display);
+	font-size: clamp(1.75rem, 5vw, 2.5rem);
+	font-weight: 800;
+	color: var(--hops-text-inverse);
+	margin-bottom: 1rem;
+	letter-spacing: -0.02em;
+}
+
+.error-subtitle {
+	font-size: 1rem;
+	color: rgba(255, 255, 255, 0.6);
+	line-height: 1.7;
+	margin: 0;
+}
+
+/* Actions */
+.error-actions {
+	display: flex;
+	gap: 1rem;
+	justify-content: center;
+	flex-wrap: wrap;
+	margin-bottom: 3rem;
+}
+
+:global(.error-actions .button) {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.5rem;
+}
+
+/* Fun stats */
+.fun-stats {
+	display: flex;
+	justify-content: center;
+	gap: 3rem;
+	padding-top: 2rem;
+	border-top: 1px solid rgba(255, 255, 255, 0.1);
+}
+
+.stat {
+	text-align: center;
+}
+
+.stat-value {
+	display: block;
+	font-family: var(--font-mono);
+	font-size: 1.5rem;
+	font-weight: 700;
+	color: var(--hops-orange);
+}
+
+.stat-label {
+	font-size: 0.75rem;
+	color: rgba(255, 255, 255, 0.4);
+	text-transform: uppercase;
+	letter-spacing: 0.1em;
+}
+
+/* Mobile adjustments */
+@media (--tablet) {
+	.ascii-art {
+		font-size: 0.35rem;
+	}
+
+	.hop-character {
+		transform: scale(0.8);
+		margin-bottom: 1rem;
+	}
+
+	.terminal-body {
+		padding: 1rem;
+		min-height: 140px;
+	}
+
+	.terminal-line {
+		font-size: 0.75rem;
+	}
+
+	.fun-stats {
+		gap: 1.5rem;
+	}
+}
+
+@media (--mobile) {
+	.ascii-art {
+		font-size: 0.28rem;
+	}
+
+	.fun-stats {
+		flex-direction: column;
+		gap: 1rem;
+	}
+}
+</style>
diff --git a/tests/e2e-ui/ui/src/routes/+layout.server.ts b/tests/e2e-ui/ui/src/routes/+layout.server.ts
new file mode 100644
index 00000000..ed7232cc
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/+layout.server.ts
@@ -0,0 +1,31 @@
+import {
+	createDistributedSvelteKitServer,
+	type SveltekitDistributedPageData
+} from '@hops-ops/distributed/sveltekit';
+
+import { DISTRIBUTED_ROUTE_OPERATIONS } from '$distributed';
+import { engineRoleFromGroups } from '$lib/roles';
+import { graphqlHttpUrl } from '$lib/server/graphql';
+
+import type { LayoutServerLoad } from './$types';
+
+type LoadEvent = Parameters<LayoutServerLoad>[0];
+type Session = NonNullable<
+	Awaited<ReturnType<LoadEvent['locals']['auth']>>
+>;
+
+/**
+ * One root loader owns every compiler-discovered user-safe `@load` operation.
+ * A fresh replica is created per request and no GraphQL work runs for routes
+ * absent from the generated registry.
+ */
+const distributed = createDistributedSvelteKitServer<Session, LoadEvent>({
+	routes: DISTRIBUTED_ROUTE_OPERATIONS,
+	getSession: (event) => event.locals.auth(),
+	getRole: (session) => engineRoleFromGroups(session?.user?.groups),
+	getUrl: graphqlHttpUrl
+});
+
+export const load: LayoutServerLoad = distributed.load satisfies (
+	event: LoadEvent
+) => Promise<SveltekitDistributedPageData>;
diff --git a/tests/e2e-ui/ui/src/routes/+layout.svelte b/tests/e2e-ui/ui/src/routes/+layout.svelte
new file mode 100644
index 00000000..abc8bebe
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/+layout.svelte
@@ -0,0 +1,75 @@
+<script lang="ts">
+	import '../app.css';
+	import '$lib/styles/chrome.css';
+	import { browser } from '$app/environment';
+	import { onDestroy, untrack } from 'svelte';
+	import type { Snippet } from 'svelte';
+	import {
+		createPageDataSessionSource,
+		type SveltekitReplicaHydration
+	} from '@hops-ops/distributed/sveltekit';
+	import { provideDistributed } from '$distributed';
+
+	import AuthRefresh from '$lib/components/shared/AuthRefresh.svelte';
+	import Navbar from '$lib/components/shared/header/Navbar.svelte';
+
+	import type { LayoutData } from './$types';
+
+	let { data, children }: { data: LayoutData; children: Snippet } = $props();
+
+	const initialData = untrack(() => data);
+	const pageData = createPageDataSessionSource(initialData);
+	let appliedHydration: SveltekitReplicaHydration | undefined =
+		initialData.distributed;
+	let hydrationTimer: ReturnType<typeof setTimeout> | undefined;
+
+	const client = provideDistributed({
+		session: pageData.session,
+		browser,
+		...(initialData.distributed !== undefined &&
+		initialData.distributedAuthority !== undefined
+			? {
+					hydration: initialData.distributed,
+					authority: initialData.distributedAuthority
+				}
+			: {})
+	});
+
+	$effect(() => {
+		pageData.set(data);
+		if (
+			data.distributed === undefined ||
+			data.distributedAuthority === undefined ||
+			data.distributed === appliedHydration
+		) {
+			return;
+		}
+
+		appliedHydration = data.distributed;
+		if (hydrationTimer !== undefined) clearTimeout(hydrationTimer);
+		// Session listeners fence an old credential in the microtask queue.
+		// Apply the separately-authorized navigation seed after that fence.
+		hydrationTimer = setTimeout(() => {
+			hydrationTimer = undefined;
+			client.hydrate(data.distributed!, data.distributedAuthority!);
+		}, 0);
+	});
+
+	onDestroy(() => {
+		if (hydrationTimer !== undefined) clearTimeout(hydrationTimer);
+		client.destroy();
+	});
+</script>
+
+<AuthRefresh />
+<Navbar />
+<main>
+	{@render children()}
+</main>
+
+<style>
+	main {
+		position: relative;
+		min-height: 100vh;
+	}
+</style>
diff --git a/tests/e2e-ui/ui/src/routes/+page.server.ts b/tests/e2e-ui/ui/src/routes/+page.server.ts
new file mode 100644
index 00000000..8718c7f1
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/+page.server.ts
@@ -0,0 +1,6 @@
+import type { PageServerLoad } from './$types';
+
+/** Home is static template content; session comes from layout. */
+export const load: PageServerLoad = async () => {
+	return {};
+};
diff --git a/tests/e2e-ui/ui/src/routes/+page.svelte b/tests/e2e-ui/ui/src/routes/+page.svelte
new file mode 100644
index 00000000..5ba52ce5
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/+page.svelte
@@ -0,0 +1,1304 @@
+<script lang="ts">
+	/**
+	 * e2e-ui home — living walkthrough of how e2e-ui actually works.
+	 *
+	 * Keep samples honest: one file / one concept per code block, and match the
+	 * checked-in handlers, GraphQL docs, and dual client surfaces.
+	 */
+	import '$lib/styles/home.css';
+	import { page } from '$app/state';
+	import Footer from '$lib/components/shared/Footer.svelte';
+
+	const session = $derived(page.data.session);
+	const signedIn = $derived(!!session?.user);
+	/** Auth.js bounce when OIDC/IdP is misconfigured or Zitadel is down. */
+	const authConfigError = $derived(page.url.searchParams.get('error') === 'Configuration');
+
+	/** One file / one concept per code block — never merge paths in a single sample. */
+	type CodeBlock = { file: string; label: string; code: string };
+
+	const demos = [
+		{
+			href: '/todos',
+			title: 'Todos — owner-scoped list',
+			blurb:
+				'Create, complete, reopen, archive. UI paints from generated optimistic effects; a projector confirms the row. You only see your own todos unless you are admin.',
+			where: '/todos · Fact + effects · personal RLS',
+			label: 'Open todos'
+		},
+		{
+			href: '/chat',
+			title: 'Lobby chat — one doc for SSR and live',
+			blurb:
+				'One @load @live query seeds HTML and continues over GraphQL WebSocket. Post is a command; everyone else arrives as live frames — not a second chat stack.',
+			where: '/chat · @load @live · shared room',
+			label: 'Open chat'
+		},
+		{
+			href: '/blob',
+			title: 'Blob game — Projected board in the response',
+			blurb:
+				'Each move is an aggregate command that returns Projected<BlobGameView>. Map and score commit with the event; the replica applies the payload before the call resolves.',
+			where: '/blob · Projected · no dual-write',
+			label: 'Play blob'
+		},
+		{
+			href: '/admin',
+			title: 'Admin — separate generated surface',
+			blurb:
+				'e2e-ui-admin is a second client (nested layout + role gate). Elevated ops are not discoverable from the user $distributed tree.',
+			where: '/admin · e2e-ui-admin · force-archive',
+			label: 'Open admin'
+		},
+		{
+			href: '/session',
+			title: 'Session — who am I to the API?',
+			blurb:
+				'User, groups → engine role, and the tokens the browser actually holds. Start here when GraphQL is empty or 401.',
+			where: '/session · identity · tokens',
+			label: 'Inspect session'
+		}
+	];
+
+	/** Framework-wide principles (Distributed as a whole). */
+	const frameworkPrinciples = [
+		{
+			title: 'Simplest DX is the goal',
+			body: 'Event sourcing and CQRS are easy to overbuild. Distributed’s job is the opposite: plain domain intent and ordinary UI, while the library carries history, projection, GraphQL, and the browser replica. Ceremony without clarity is the wrong path.'
+		},
+		{
+			title: 'Start with the domain, not the database',
+			body: 'Model a todo or game as a plain Rust type with methods and unit tests. No HTTP, no SQL, no handler context to prove the rules. Infrastructure plugs in after the behavior is solid.'
+		},
+		{
+			title: 'Know which side of the fence you are on',
+			body: 'Writes produce durable history. Reads use query-shaped tables. Publish goes through an outbox on purpose. Handlers stay thin; projectors or Projected materialize reads; the UI observes. Confusion usually means those lines blurred.'
+		},
+		{
+			title: 'You keep the interesting code',
+			body: 'Macros own recording facts and replaying history so methods stay readable. You still own “only the owner can complete this.” Scaffolding disappears; decisions do not.'
+		},
+		{
+			title: 'Register once, ship everywhere',
+			body: 'Commands and read models live once in the typed Service inventory. Generation fans out GraphQL fields, operation artifacts, optimistic effects, confirmations, and dual application surfaces. Drift fails CI on purpose.'
+		},
+		{
+			title: 'Familiar patterns, short handles',
+			body: 'Load aggregate → apply command → stage events (+ outbox) → Fact or Projected result. Swap memory for Postgres without rewriting the domain.'
+		},
+		{
+			title: 'Grow without rewriting what you proved',
+			body: 'Start as one process on a laptop. Later split services or change brokers. Domain types and facts you already tested should not need a rewrite.'
+		}
+	];
+
+	/** Three teaching cards — prose first, not API dumps. */
+	const dxStack = [
+		{
+			title: 'You write plain domain code',
+			body: 'Ordinary methods and tests. Public command methods enforce rules; private #[event] helpers record history. You own the behavior — the scaffolding gets out of the way.'
+		},
+		{
+			title: 'One inventory, many surfaces',
+			body: 'Describe commands and readable tables once. Application surfaces (e2e-ui vs e2e-ui-admin) select roles and fields. Generation turns that into GraphQL, typed UI helpers, optimistic effects, and drift checks.'
+		},
+		{
+			title: 'Patterns as short, swappable verbs',
+			body: 'CausalCommandContext: load / create / stage / projected. Real design patterns, thin handles, backends you can swap when you grow.'
+		}
+	];
+
+	/** e2e-ui template success rules (apply the framework here). */
+	const principles = [
+		{
+			title: 'Commands change the world; tables are for reading',
+			body: 'Do not dual-write query tables from the UI. Send a command. Todos/chat return Fact and project eventually; blob returns Projected in the same transaction as the event.'
+		},
+		{
+			title: 'Trust the signed-in person, not the request body',
+			body: 'Owner and author come from the session (ctx.user_id()). Clients never pass “I am alice” as free-form input.'
+		},
+		{
+			title: 'One replica story for user data',
+			body: 'Root layout creates one client. SSR hydration, HTTP reads, @live frames, command results, and optimistic effects all update that same replica. Admin is a second nested client on purpose.'
+		},
+		{
+			title: 'Let the Service declare how the UI catches up',
+			body: 'command_effects + command_confirmations (Fact) vs Projected payload (blob). Screens do not invent reconciliation. Revalidation may lag; fences keep your own write from rolling back.'
+		},
+		{
+			title: 'Roles and surfaces are real',
+			body: 'Engine RLS filters rows. Elevated mutations live only on e2e-ui-admin. A type name in a bundle is not authorization.'
+		},
+		{
+			title: 'Regenerate after you change the contract',
+			body: 'Inventory, command contract, or +page.graphql change → make gen-client / check-client and commit artifacts. Hand-editing generated files is how drift wins.'
+		}
+	];
+
+	const crates = [
+		{
+			name: 'todo-domain / chat-domain / blob-domain',
+			role: 'Pure rules — methods + unit tests, no network'
+		},
+		{
+			name: 'e2e-readmodels',
+			role: 'Query tables, joins (author / owner → auth_users)'
+		},
+		{
+			name: 'e2e-service',
+			role: 'Handlers, projectors, Projected blob, dual client surfaces, GraphQL'
+		},
+		{
+			name: 'e2e-runner → e2e-ui',
+			role: 'Process on :8791 (Postgres + OidcBearer or SQLite + DevHeaders)'
+		},
+		{
+			name: 'e2e-suite',
+			role: 'Behavioral + gated OIDC proof'
+		},
+		{
+			name: 'ui/',
+			role: 'SvelteKit: OIDC, SSR @load, live chat, blob, admin surface'
+		}
+	];
+
+	const clientSteps: Array<{
+		n: string;
+		title: string;
+		why: string;
+		path: string;
+		label: string;
+		blocks: CodeBlock[];
+	}> = [
+		{
+			n: 'C1',
+			title: 'Declare reads beside the route',
+			why: 'A page owns a small GraphQL document. @load seeds SSR; @live continues the same operation over WebSocket. The compiler emits the typed op and the static route registry — no second loader list.',
+			path: 'routes/**/+page.graphql · generated/user/',
+			label: '@load + @live',
+			blocks: [
+				{
+					file: 'routes/chat/+page.graphql',
+					label: 'Co-located read',
+					code: `// One declaration owns SSR, cache reads, and the live companion.
+query ChatMessages @load @live {
+  chat_messages(where: { room_id: { _eq: "lobby" } }) {
+    message_id
+    room_id
+    author_id
+    body
+    created_at
+  }
+}`
+				},
+				{
+					file: 'routes/blob/[[gameId]]/+page.graphql',
+					label: 'Join on load',
+					code: `query BlobGames @load {
+  blob_games(order_by: [{ game_id: asc }]) {
+    game_id
+    score
+    map_json
+    owner { user_id display_name }
+  }
+}`
+				}
+			]
+		},
+		{
+			n: 'C2',
+			title: 'The root layout owns SSR',
+			why: 'createDistributedSvelteKitServer matches the route against DISTRIBUTED_ROUTE_OPERATIONS, runs each declared read once, and returns replica hydration plus a separate authority proof. Routes with no @load do no GraphQL work.',
+			path: 'routes/+layout.server.ts',
+			label: 'Static route loader',
+			blocks: [
+				{
+					file: 'routes/+layout.server.ts',
+					label: 'createDistributedSvelteKitServer',
+					code: `const distributed = createDistributedSvelteKitServer({
+  routes: DISTRIBUTED_ROUTE_OPERATIONS,
+  getSession: (event) => event.locals.auth(),
+  getRole: (session) =>
+    engineRoleFromGroups(session?.user?.groups),
+  getUrl: graphqlHttpUrl
+});
+
+export const load = distributed.load;
+// → data.distributed + data.distributedAuthority`
+				}
+			]
+		},
+		{
+			n: 'C3',
+			title: 'Hydrate one browser replica',
+			why: 'provideDistributed wires one client for HTTP, WebSocket connection_init, commands, and auth-scope invalidation. SSR state is the first snapshot so subscribing does not re-fetch the same HTTP read.',
+			path: 'routes/+layout.svelte · $distributed',
+			label: 'One client',
+			blocks: [
+				{
+					file: 'routes/+layout.svelte',
+					label: 'provideDistributed',
+					code: `const pageData = createPageDataSessionSource(data);
+const client = provideDistributed({
+  session: pageData.session,
+  browser,
+  hydration: data.distributed,
+  authority: data.distributedAuthority
+});
+// Navigation: client.hydrate(…) after the session fence`
+				},
+				{
+					file: 'WS auth',
+					label: 'connection_init',
+					code: `// Same session source for HTTP, WS, and commands.
+// Token goes in the first WS message — not the upgrade URL:
+{ type: 'connection_init',
+  payload: { authorization: \`Bearer \${accessToken}\` } }`
+				}
+			]
+		},
+		{
+			n: 'C4',
+			title: 'Read and write through generated artifacts',
+			why: 'Todos.use() / ChatMessages.use() / BlobGames.use() bind the tree-local replica. useCommands() carries optimistic effects and Projected/Fact metadata so every mounted view observes the change without page-specific cache surgery.',
+			path: 'routes/todos/+page.svelte · $distributed',
+			label: 'Operation + commands',
+			blocks: [
+				{
+					file: 'todos/+page.svelte',
+					label: 'Replica read + command',
+					code: `import { Todos, useCommands } from '$distributed';
+
+const list = Todos.use();
+const commands = useCommands();
+const rows = $derived($list.complete ? $list.data.todos : []);
+
+await commands.todo.create({ title });
+// todo_id defaults to uuid_v7() from the inventory
+await commands.todo.complete({ todo_id });
+// Optimism already visible; projector confirms later`
+				},
+				{
+					file: 'blob/[[gameId]]/+page.svelte',
+					label: 'Projected move',
+					code: `const list = BlobGames.use();
+const commands = useCommands();
+
+const receipt = await commands.blob.move({
+  game_id,
+  direction: 'up'
+});
+// consistency: "projected" — board hits the replica
+// from the mutation payload before this resolves`
+				}
+			]
+		},
+		{
+			n: 'C5',
+			title: 'Elevated work is a second surface',
+			why: 'e2e-ui-admin is generated separately. The nested /admin layout role-gates before any GraphQL, then provides its own client. User pages cannot import force_archive through $distributed.',
+			path: 'routes/admin/+layout.server.ts · $distributed/admin',
+			label: 'Dual surface',
+			blocks: [
+				{
+					file: 'admin/+layout.server.ts',
+					label: 'Role gate + admin registry',
+					code: `import { DISTRIBUTED_ROUTE_OPERATIONS } from '$distributed/admin';
+
+const distributed = createDistributedSvelteKitServer({
+  routes: DISTRIBUTED_ROUTE_OPERATIONS,
+  getRole: (session) => {
+    const role = engineRoleFromGroups(session?.user?.groups);
+    if (!isAdminEngineRole(role)) error(403, 'Admin role required');
+    return role;
+  },
+  // …
+});`
+				},
+				{
+					file: 'admin page',
+					label: 'Elevated commands only',
+					code: `import { useCommands } from '$distributed/admin';
+const commands = useCommands();
+await commands.todo.force_archive({ todo_id });
+// Not present on the user command tree`
+				}
+			]
+		}
+	];
+
+	const serverSteps: Array<{
+		n: string;
+		title: string;
+		why: string;
+		path: string;
+		label: string;
+		blocks: CodeBlock[];
+	}> = [
+		{
+			n: '01',
+			title: 'Sign in — your form, IdP tokens',
+			why: 'Custom Login V2 hosts the password form; Zitadel issues OIDC tokens; Auth.js keeps them in an encrypted cookie. SSR and GraphQL use the access token as Bearer. Groups map to engine roles.',
+			path: 'ui/src/auth.ts · routes/login · zitadel-session.ts',
+			label: 'Auth session',
+			blocks: [
+				{
+					file: 'ui/src/auth.ts',
+					label: 'Session callbacks',
+					code: `// Auth.js OIDC (Zitadel) — PKCE + state
+// Tokens in encrypted JWT session cookie (httpOnly)
+callbacks: {
+  async jwt({ token, account }) {
+    if (account) {
+      token.accessToken = account.access_token;
+      token.refreshToken = account.refresh_token;
+      token.expiresAt = account.expires_at ?? …;
+    }
+    // silent refresh before expiry when refresh_token present
+    return token;
+  },
+  async session({ session, token }) {
+    session.accessToken = token.accessToken; // API Bearer
+    session.user.id = token.sub;
+    session.user.groups = /* from IdP claims */;
+    return session;
+  }
+}`
+				}
+			]
+		},
+		{
+			n: '02',
+			title: 'SSR GraphQL is deny-by-default RLS',
+			why: 'The root loader calls GraphQL with your token. OidcBearer maps JWT → x-user-id + roles. Model permissions filter rows — alice never sees bob’s todos or blob games.',
+			path: 'crates/service/src/service.rs · +page.graphql',
+			label: 'SSR + RLS',
+			blocks: [
+				{
+					file: 'crates/service/src/service.rs',
+					label: 'Row-level grants',
+					code: `// OidcBearer → x-user-id (sub) + engine roles
+.model::<TodoView>(
+  ModelPermissions::new()
+    .grant(
+      "user",
+      read().all_columns().rows(
+        col("owner_id").eq(claim("x-user-id")),
+      ),
+    )
+    .grant("admin", read().all_columns()),
+)
+// Same pattern for BlobGameView; ChatMessageView is room-shared`
+				},
+				{
+					file: 'todos/+page.graphql',
+					label: 'Co-located query',
+					code: `query Todos @load {
+  todos(order_by: [{ status: asc }, { todo_id: asc }]) {
+    todo_id
+    owner_id
+    title
+    status
+  }
+}`
+				}
+			]
+		},
+		{
+			n: '03',
+			title: 'Mutations are commands — Fact or Projected',
+			why: 'The typed Service inventory declares input, result shape, roles, optimistic effects, and projector confirmations. Handlers never accept owner_id from the client.',
+			path: 'service.rs · handlers/commands/*',
+			label: 'Commands',
+			blocks: [
+				{
+					file: 'handlers/commands/create.rs',
+					label: 'Fact + session owner',
+					code: `pub async fn handle(
+  ctx: &CausalCommandContext<'_, Todo>,
+  input: TodoCreateInput,
+) -> Result<PreparedCommand<Fact<TodoCreatePayload>>, HandlerError> {
+  let owner = ctx.user_id()?.to_string(); // never from input
+  let mut todo = ctx.create();
+  todo.create(&input.todo_id, &owner, &input.title)?;
+  let fact = stage_todo_event(ctx, todo, "todo.created")?;
+  PreparedCommand::<Fact<TodoCreatePayload>>::prepare(/* … */)
+}`
+				},
+				{
+					file: 'service.rs · typed_command',
+					label: 'Effects + confirmations',
+					code: `typed_command::<TodoCreateInput, Fact<TodoCreatePayload>>(…)
+  .effects(command_effects! {
+    upsert TodoView {
+      key { todo_id: input.todo_id },
+      set {
+        owner_id: trusted("x-user-id"),
+        title: input.title,
+        status: "open"
+      }
+    };
+  })
+  .confirmations(command_confirmations! {
+    confirm todo_projection -> TodoView {
+      key { todo_id: input.todo_id }
+    };
+  })`
+				}
+			]
+		},
+		{
+			n: '04',
+			title: 'Eventual path: history first, then projector',
+			why: 'Todos and chat stage events (+ outbox). A projector upserts the query row and ChangeHub wakes @live subscribers. The UI already applied optimistic effects from the inventory.',
+			path: 'handlers/events/project_todo.rs · project_chat.rs',
+			label: 'Projector',
+			blocks: [
+				{
+					file: 'handlers/events/project_todo.rs',
+					label: 'Only RM write for todos',
+					code: `pub const EVENTS: &[&str] = &[
+  "todo.created", "todo.renamed", "todo.completed",
+  "todo.reopened", "todo.archived", // + force_archived
+];
+// decode fact → TodoView → ReadModelWritePlanBuilder upsert
+// ChangeHub notifies open subscriptions`
+				}
+			]
+		},
+		{
+			n: '05',
+			title: 'Strong path: Projected in the same transaction',
+			why: 'Blob maps must not lag. The handler returns PreparedCommand<Projected<BlobGameView>> and stages the row with ctx.projected — aggregate, ledger, and query row commit together. No second writer, no dual-write from the UI.',
+			path: 'handlers/commands/blob_move.rs · blob_cmd.rs',
+			label: 'Projected',
+			blocks: [
+				{
+					file: 'handlers/commands/blob_move.rs',
+					label: 'Projected result',
+					code: `pub async fn handle(
+  ctx: &CausalCommandContext<'_, BlobGame>,
+  input: BlobMoveInput,
+) -> Result<PreparedCommand<Projected<BlobGameView>>, HandlerError> {
+  let owner = ctx.user_id()?.to_string();
+  let mut game = load_game(ctx, &input.game_id).await?;
+  game.move_dir(&owner, dir).map_err(map_domain)?;
+  let fact = stage_blob(ctx, game)?;
+  ctx.projected(map_blob_fact(&fact))
+}`
+				},
+				{
+					file: 'service.rs · SurfaceDirectProjection',
+					label: 'Client topology',
+					code: `fn blob_projection() -> SurfaceDirectProjection {
+  SurfaceDirectProjection::new("project_blob")
+    .model::<BlobGameView>()
+    .change_epoch("e2e-ui-blob-v1")
+}
+// typed_command::<…, Projected<BlobGameView>>(…)`
+				}
+			]
+		},
+		{
+			n: '06',
+			title: 'People have names — join the identity directory',
+			why: 'Import users from Zitadel into auth_users; join from chat.author and blob.owner. Fix missing people at ingest/scrape — do not copy display names onto every aggregate.',
+			path: 'handlers/ingestors/zitadel · AuthUserView',
+			label: 'Joins',
+			blocks: [
+				{
+					file: 'readmodels/…/blob_game_view.rs',
+					label: 'belongs_to',
+					code: `#[readmodel(belongs_to = "AuthUserView", foreign_key = "owner_id")]
+pub owner: Option<AuthUserView>,
+// GraphQL: owner { user_id display_name email status }`
+				},
+				{
+					file: 'readmodels/…/chat_message_view.rs',
+					label: 'author join ready',
+					code: `#[readmodel(belongs_to = "AuthUserView", foreign_key = "author_id")]
+pub author: Option<AuthUserView>,
+// Select author { … } when the route needs labels`
+				}
+			]
+		}
+	];
+</script>
+
+<div class="wf-home">
+	<section class="wf-hero">
+		<div class="wf-hero-inner">
+			{#if authConfigError}
+				<div class="wf-auth-banner" role="alert">
+					<strong>Identity provider unavailable</strong>
+					<p>
+						Sign-in / create-account need Zitadel. Docker was not reachable (or OIDC env is
+						missing), so Auth.js returned <code>error=Configuration</code>.
+					</p>
+					<ol>
+						<li>Start Docker / Colima</li>
+						<li>
+							<code>cd tests/e2e-ui && make up</code> — boots Postgres + Zitadel and enables
+							self-registration
+						</li>
+						<li>
+							<code>source e2e-ui.env && make run</code> — API + UI with OIDC
+						</li>
+						<li>
+							Demo logins: <code>alice</code> / <code>bob</code> / <code>admin</code> ·
+							<code>Password1!</code>
+						</li>
+					</ol>
+				</div>
+			{/if}
+			<span class="wf-kicker">Distributed · e2e-ui template</span>
+			<h1>
+				A <em>framework template</em> you run as full e2e tests — a map you can learn from.
+			</h1>
+			<p class="wf-lede">
+				<strong>Simplest DX is the goal.</strong> Plain domains, deny-by-default GraphQL with
+				first-class OIDC, dual generated clients, and a causal browser replica. Click through todos
+				(<code>Fact</code> + projector), chat (<code>@load @live</code>), blob
+				(<code>Projected</code>), and admin (separate surface) — proved by
+				<code>make test</code> offline and Playwright with real OIDC.
+			</p>
+			<div class="wf-actions">
+				{#if signedIn}
+					<a class="wf-btn wf-btn-primary" href="/todos">Open todos</a>
+					<a class="wf-btn wf-btn-ghost" href="/blob">Blob game</a>
+					<a class="wf-btn wf-btn-ghost" href="#framework">Framework principles</a>
+				{:else}
+					<a class="wf-btn wf-btn-primary" href="/signin?callbackUrl=/todos">Sign in with OIDC</a>
+					<a class="wf-btn wf-btn-ghost" href="#framework">Framework principles</a>
+				{/if}
+			</div>
+			<div class="wf-meta">
+				<span>tests/e2e-ui</span>
+				<span>API :8791</span>
+				<span>UI :5180</span>
+				<span>Zitadel :18080</span>
+			</div>
+			<nav class="wf-toc" aria-label="On this page">
+				<a href="#framework">Principles</a>
+				<a href="#run">Run</a>
+				<a href="#demos">Demos</a>
+				<a href="#architecture">Architecture</a>
+				<a href="#client-dx">Client DX</a>
+				<a href="#cap">Fact vs Projected</a>
+				<a href="#server-flow">Server</a>
+				<a href="#codegen">Codegen</a>
+			</nav>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-dark" id="story">
+		<div class="wf-band-inner">
+			<div class="wf-section-head">
+				<span class="wf-label">Why this exists</span>
+				<h2>Template first. Product later.</h2>
+				<p>
+					This is not a product marketing site. It is the face of a fixture that ships with
+					Distributed — so when the library’s recommended patterns change, you can see and test them
+					here. Copy the folder when you start a service; keep the boundaries that keep you sane.
+				</p>
+			</div>
+			<div class="wf-cards">
+				<div class="wf-card">
+					<h3>Something you can actually run</h3>
+					<p>
+						<code>make up</code> starts the database and identity provider.
+						<code>make run</code> starts API and UI. Log in as alice, bob, or admin and click
+						around.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>Kept honest by tests</h3>
+					<p>
+						Domain tests, behavioral suite, gated OIDC, and Playwright browser flows. The demos are
+						not slides — they break if the library lies.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>A map you can extend</h3>
+					<p>
+						Domain crates, read models, thin handlers, dual client surfaces, Svelte UI. Point env at
+						your database and IdP; the shape of command → history → query stays the same.
+					</p>
+				</div>
+			</div>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-light" id="framework">
+		<div class="wf-band-inner">
+			<div class="wf-section-head wf-section-head-wide">
+				<span class="wf-label">Distributed · framework principles</span>
+				<h2>What we are optimizing for</h2>
+				<p>
+					Distributed is a CQRS and event-sourcing framework for Rust people who still want to ship.
+					The north star is not “more infrastructure.” It is the
+					<strong>simplest developer experience</strong> that keeps write history, queries, and
+					published messages honest — so you can grow later without rewriting the domain you already
+					proved.
+				</p>
+			</div>
+			<ol class="wf-principles">
+				{#each frameworkPrinciples as p, i}
+					<li class="wf-principle">
+						<span class="wf-principle-n" aria-hidden="true">{String(i + 1).padStart(2, '0')}</span>
+						<div>
+							<h3>{p.title}</h3>
+							<p>{p.body}</p>
+						</div>
+					</li>
+				{/each}
+			</ol>
+
+			<div class="wf-subhead" id="dx-stack">
+				<span class="wf-label">How DX stays simple</span>
+				<h3>Three ways the stack carries weight for you</h3>
+				<p>
+					You should not re-implement “save history,” “sync parallel inventories,” or “build a mini
+					framework” for every feature. Three layers share that work. You write intent; the stack
+					expands it.
+				</p>
+			</div>
+			<div class="wf-layers">
+				{#each dxStack as col, i}
+					<div class="wf-layer">
+						<span class="wf-layer-n" aria-hidden="true">{String(i + 1).padStart(2, '0')}</span>
+						<h4>{col.title}</h4>
+						<p class="wf-layer-body">{col.body}</p>
+					</div>
+				{/each}
+			</div>
+
+			<div class="wf-subhead" id="macros">
+				<span class="wf-label">When you are ready for the code</span>
+				<h3>Domain first — macros fill the seams</h3>
+				<p>
+					Public methods enforce rules; private <code>#[event]</code> helpers record history. Unit
+					tests call the domain directly — red/green before any handler exists.
+				</p>
+			</div>
+			<div class="wf-code-stack">
+				<div class="wf-code">
+					<div class="wf-code-bar">
+						<span>todo-domain · models/todo.rs</span>
+						<em>rules then record</em>
+					</div>
+					<pre><code>{`pub fn complete(&mut self, owner_id: &str) -> Result<(), TodoError> {
+  self.ensure_owner(owner_id)?;
+  self.require_mutable()?;
+  if matches!(self.status, TodoStatus::Completed) {
+    return Err(TodoError::AlreadyCompleted);
+  }
+  self.record_completed()?;
+  Ok(())
+}
+
+#[event("todo.completed")]
+fn record_completed(&mut self) {
+  self.status = TodoStatus::Completed;
+}
+// Unit tests call complete() directly — no handler required.`}</code></pre>
+				</div>
+				<div class="wf-code">
+					<div class="wf-code-bar">
+						<span>e2e-readmodels · TodoView</span>
+						<em>#[derive(ReadModel)]</em>
+					</div>
+					<pre><code>{`#[derive(Clone, Debug, Default, Serialize, Deserialize, ReadModel)]
+#[table("todos")]
+pub struct TodoView {
+  #[id("todo_id")]
+  pub todo_id: String,
+  pub owner_id: String,
+  pub title: String,
+  pub status: String,
+}
+// GraphQL lists/filters this table — you did not hand-write resolvers.`}</code></pre>
+				</div>
+				<div class="wf-code">
+					<div class="wf-code-bar">
+						<span>handlers · command input</span>
+						<em>GraphqlInput</em>
+					</div>
+					<pre><code>{`#[derive(Debug, Deserialize, distributed::GraphqlInput)]
+pub struct TodoCreateInput {
+  pub todo_id: String,
+  pub title: String,
+}
+// owner_id is NOT an input — handler uses ctx.user_id().
+// Same type for GraphQL input and the handler.`}</code></pre>
+				</div>
+			</div>
+
+			<div class="wf-subhead" id="pattern-apis">
+				<span class="wf-label">Patterns you already know</span>
+				<h3>Short verbs you can swap under the hood</h3>
+				<p>
+					Load from history, apply a command, stage events (and outbox), return
+					<code>Fact</code> or <code>Projected</code>. Same ideas as textbooks — thin APIs, backends
+					you can change later.
+				</p>
+			</div>
+			<div class="wf-code-stack">
+				<div class="wf-code">
+					<div class="wf-code-bar">
+						<span>Load → decide → stage history</span>
+						<em>CausalCommandContext</em>
+					</div>
+					<pre><code>{`let mut todo = load_todo(ctx, &input.todo_id).await?;
+todo.complete(&owner).map_err(map_domain)?;
+let fact = stage_todo_event(ctx, todo, "todo.completed")?;
+// stage_todo_event: OutboxMessage + ctx.stage(aggregate)
+// Framework commits event store + outbox together
+PreparedCommand::<Fact<TodoStatusPayload>>::prepare(/* from fact */)`}</code></pre>
+				</div>
+				<div class="wf-code">
+					<div class="wf-code-bar">
+						<span>Projected — same transaction</span>
+						<em>blob</em>
+					</div>
+					<pre><code>{`let fact = stage_blob(ctx, game)?;
+ctx.projected(map_blob_fact(&fact))
+// → PreparedCommand<Projected<BlobGameView>>
+// Aggregate + command ledger + query row commit atomically.
+// No manual ReadModelWritePlan in the handler.`}</code></pre>
+				</div>
+				<div class="wf-code">
+					<div class="wf-code-bar">
+						<span>One handler inventory, GraphQL door</span>
+						<em>service</em>
+					</div>
+					<pre><code>{`// This fixture exposes commands over GraphQL only
+// (POST /todo.* must 404 — suite proves it)
+Service::new()
+  .named("e2e-ui")
+  .without_http_command_routes()
+  .routes(todos)
+  .routes(chat)
+  .routes(blob);
+// Later: bus / gRPC without rewriting Todo::complete`}</code></pre>
+				</div>
+			</div>
+
+			<div class="wf-subhead">
+				<span class="wf-label">A calm order of work</span>
+				<h3>Prove the domain before the plumbing</h3>
+			</div>
+			<ol class="wf-flow-map">
+				<li>Write tests for what the model should allow and refuse</li>
+				<li>Implement the plain type until those tests pass</li>
+				<li>Thin handler: session → load/create → domain → stage (+ Fact or Projected)</li>
+				<li>Projector for eventual models; SurfaceDirectProjection for Projected</li>
+				<li>Permissions + client application surface(s)</li>
+				<li>Co-located <code>+page.graphql</code>, <code>make gen-client</code>, thin UI</li>
+				<li>Swap storage or messaging when you outgrow the laptop setup</li>
+			</ol>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-light" id="run">
+		<div class="wf-band-inner">
+			<div class="wf-section-head">
+				<span class="wf-label">Run</span>
+				<h2>Three commands. Full stack.</h2>
+				<p>
+					From <code>tests/e2e-ui</code>. Demo password: <code>Password1!</code> (alice / bob /
+					admin). After <code>make up</code>, always restart <code>make run</code> so the process
+					picks up <code>e2e-ui.env</code>.
+				</p>
+			</div>
+			<div class="wf-steps">
+				<div class="wf-step">
+					<h3>Bootstrap IdP + DB</h3>
+					<p><code>make up</code> writes <code>e2e-ui.env</code>.</p>
+				</div>
+				<div class="wf-step">
+					<h3>API + UI</h3>
+					<p>
+						<code>set -a && source e2e-ui.env && set +a && make run</code> — GraphQL :8791,
+						SvelteKit :5180.
+					</p>
+				</div>
+				<div class="wf-step">
+					<h3>Prove it</h3>
+					<p>
+						<code>make test</code> · <code>make test-live</code> ·
+						<code>make test-browser</code> · <code>make check-client</code>
+					</p>
+				</div>
+			</div>
+			<div class="wf-subhead">
+				<span class="wf-label">Two ways the API knows who you are</span>
+				<h3>Pick the profile that matches how you started the process</h3>
+			</div>
+			<div class="wf-cards wf-cards-tight">
+				<div class="wf-card">
+					<h3>Local tests (headers)</h3>
+					<p>
+						When OIDC env is unset, the suite can send simple identity headers. Fast offline
+						behavioral tests — that is what <code>make test</code> expects.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>Real login (Bearer tokens)</h3>
+					<p>
+						After <code>make up</code> and sourcing env, the API wants real tokens. Browser sessions
+						and <code>make test-live</code> use this path. Ambient “I am alice” headers are ignored.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>Do not mix them</h3>
+					<p>
+						Hitting an OIDC-only process with header-style tests looks like a wall of 401s. That is
+						usually the wrong profile — not a broken product.
+					</p>
+				</div>
+			</div>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-dark" id="demos">
+		<div class="wf-band-inner">
+			<div class="wf-section-head">
+				<span class="wf-label">Live demos</span>
+				<h2>Practice arenas, not slides</h2>
+				<p>
+					After <code>make up && make run</code>, sign in and click. Each route is a small story about
+					one way the stack behaves — personal data, live rooms, Projected returns, elevated surface,
+					identity.
+				</p>
+			</div>
+			<div class="wf-demos">
+				{#each demos as d, i}
+					<a class="wf-demo" href={d.href}>
+						<span class="wf-demo-i">{String(i + 1).padStart(2, '0')}</span>
+						<div>
+							<h3>{d.title}</h3>
+							<p>{d.blurb}</p>
+							<div class="wf-demo-where">{d.where}</div>
+						</div>
+						<span class="wf-demo-go">{d.label} →</span>
+					</a>
+				{/each}
+			</div>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-light" id="architecture">
+		<div class="wf-band-inner">
+			<div class="wf-section-head">
+				<span class="wf-label">Architecture</span>
+				<h2>One direction — two result shapes</h2>
+				<p>
+					The UI never “updates the todos table” as if GraphQL were a database. It asks for work
+					(commands) and reads query-shaped data. Most features return a <code>Fact</code> and let
+					projectors catch up; blob returns <code>Projected</code> so the board is in the mutation
+					payload.
+				</p>
+			</div>
+			<div class="wf-code wf-code-lead">
+				<div class="wf-code-bar">
+					<span>Mental model</span>
+					<em>system</em>
+				</div>
+				<pre><code>{`You (browser)
+  Sign in → cookie with access token
+  @load pages → GraphQL (Bearer) → SSR hydrate replica
+  @live rooms → WebSocket (token in connection_init)
+  commands.* → same replica (effects / Projected payload)
+
+Service
+  OidcBearer → x-user-id + roles · deny-by-default RLS
+  typed Service inventory → GraphQL mutations + client surfaces
+       ├─ todos / chat: Fact + projector (+ @live)     (eventual)
+       └─ blob:         Projected<BlobGameView>         (atomic)
+  e2e-ui vs e2e-ui-admin application surfaces
+  auth_users imported from Zitadel for joins`}</code></pre>
+			</div>
+			<div class="wf-subhead">
+				<span class="wf-label">Crate map</span>
+				<h3>Where to look when you open the folder</h3>
+			</div>
+			<dl class="wf-crate-map">
+				{#each crates as c}
+					<div class="wf-crate">
+						<dt>{c.name}</dt>
+						<dd>{c.role}</dd>
+					</div>
+				{/each}
+			</dl>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-dark" id="principles">
+		<div class="wf-band-inner">
+			<div class="wf-section-head wf-section-head-wide">
+				<span class="wf-label">Template success rules</span>
+				<h2>Habits that keep this demo (and your copy of it) healthy</h2>
+				<p>
+					The principles above are Distributed as a whole. These are the extra habits
+					<strong>this fixture</strong> teaches for GraphQL, sign-in, dual surfaces, and the Svelte
+					client. Follow them and the demos feel calm; fight them and you spend the day on thrash and
+					spoofing.
+				</p>
+			</div>
+			<ol class="wf-principles">
+				{#each principles as p, i}
+					<li class="wf-principle">
+						<span class="wf-principle-n" aria-hidden="true">{String(i + 1).padStart(2, '0')}</span>
+						<div>
+							<h3>{p.title}</h3>
+							<p>{p.body}</p>
+						</div>
+					</li>
+				{/each}
+			</ol>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-light" id="client-dx">
+		<div class="wf-band-inner">
+			<div class="wf-section-head">
+				<span class="wf-label">Client GraphQL DX</span>
+				<h2>How the browser is supposed to feel</h2>
+				<p>
+					You should not wire a new HTTP client per page. The root layout creates one replica from
+					one session source; the server hydrates it, <code>@live</code> operations continue it, and
+					typed commands update it (optimistic effects or Projected payload). Query documents live
+					next to routes; command contracts come from the same typed Rust inventory the API runs.
+					Admin is a second generated surface under <code>/admin</code>.
+				</p>
+			</div>
+			<ol class="wf-flow-map">
+				<li>Declare route reads with <code>@load</code> and <code>@live</code></li>
+				<li>Let the generated static registry drive SSR</li>
+				<li>Hydrate one browser replica with separate authority proof</li>
+				<li>Read with generated <code>Todos.use()</code> / <code>BlobGames.use()</code></li>
+				<li>Write through generated nested commands</li>
+				<li>Elevated ops only via <code>$distributed/admin</code></li>
+			</ol>
+
+			<div class="wf-chapter">
+				{#each clientSteps as step}
+					<article class="wf-story-step" id="client-{step.n}" data-sample={step.label}>
+						<div class="wf-story-copy">
+							<span class="wf-label">Client {step.n}</span>
+							<h3 class="wf-step-title">{step.title}</h3>
+							<p class="wf-why">{step.why}</p>
+							<span class="wf-sample-path">{step.path}</span>
+						</div>
+						<div class="wf-code-stack">
+							{#each step.blocks as block}
+								<div class="wf-code">
+									<div class="wf-code-bar">
+										<span>{block.file}</span>
+										<em>{block.label}</em>
+									</div>
+									<pre><code>{block.code}</code></pre>
+								</div>
+							{/each}
+						</div>
+					</article>
+				{/each}
+			</div>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-dark" id="cap">
+		<div class="wf-band-inner">
+			<div class="wf-section-head">
+				<span class="wf-label">Result shapes</span>
+				<h2>Fact vs Projected — pick per feature</h2>
+				<p>
+					Not every screen needs the same consistency story. This fixture shows both on purpose so
+					you can feel the tradeoff instead of arguing in the abstract.
+				</p>
+			</div>
+			<div class="wf-cards">
+				<div class="wf-card wf-card-accent">
+					<span class="wf-card-kicker">Projected</span>
+					<h3>Blob — row commits with the command</h3>
+					<p>
+						<code>PreparedCommand&lt;Projected&lt;BlobGameView&gt;&gt;</code> +
+						<code>ctx.projected</code>. Map/score are in the mutation payload; the replica applies
+						them before the call resolves. Revalidation may still race — fences keep your own write
+						from rolling back under a lagging stamp.
+					</p>
+				</div>
+				<div class="wf-card">
+					<span class="wf-card-kicker">Fact + effects</span>
+					<h3>Todos — paint now, confirm later</h3>
+					<p>
+						Command returns a fact. Inventory <code>command_effects</code> paint the replica;
+						<code>command_confirmations</code> wait for the projector epoch. History is still the
+						source of truth — the query table catches up.
+					</p>
+				</div>
+				<div class="wf-card">
+					<span class="wf-card-kicker">Fact + live</span>
+					<h3>Chat — other people are the clock</h3>
+					<p>
+						Your post can show immediately; everyone else’s posts arrive over the
+						<code>@live</code> companion. That open connection is how the room converges — not a
+						poll loop.
+					</p>
+				</div>
+			</div>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-light" id="server-flow">
+		<div class="wf-band-inner">
+			<div class="wf-section-head">
+				<span class="wf-label">Server path</span>
+				<h2>From “I signed in” to “I can see my data”</h2>
+				<p>
+					Walk this when you are implementing a new feature. The client steps above are how the UI
+					consumes the same loop.
+				</p>
+			</div>
+			<ol class="wf-flow-map">
+				<li>Person signs in; session holds a token</li>
+				<li>Page load queries with that token (RLS-filtered rows)</li>
+				<li>UI sends a typed command, not a free-form table update</li>
+				<li>Handler: session → load/create → domain → stage</li>
+				<li>Return Fact (projector later) or Projected (same transaction)</li>
+				<li>Display names join from the identity directory</li>
+				<li>Queries and @live rooms show the new world</li>
+			</ol>
+
+			<div class="wf-chapter">
+				{#each serverSteps as step}
+					<article class="wf-story-step" id="step-{step.n}" data-sample={step.label}>
+						<div class="wf-story-copy">
+							<span class="wf-label">Server {step.n}</span>
+							<h3 class="wf-step-title">{step.title}</h3>
+							<p class="wf-why">{step.why}</p>
+							<span class="wf-sample-path">{step.path}</span>
+						</div>
+						<div class="wf-code-stack">
+							{#each step.blocks as block}
+								<div class="wf-code">
+									<div class="wf-code-bar">
+										<span>{block.file}</span>
+										<em>{block.label}</em>
+									</div>
+									<pre><code>{block.code}</code></pre>
+								</div>
+							{/each}
+						</div>
+					</article>
+				{/each}
+			</div>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-dark" id="codegen">
+		<div class="wf-band-inner">
+			<div class="wf-section-head">
+				<span class="wf-label">Keeping the UI honest</span>
+				<h2>One inventory in, complete clients out</h2>
+				<p>
+					The typed Rust Service inventory defines readable models, commands, permissions, results,
+					effects, and confirmations. <code>dctl client-manifest</code> extracts a selected
+					application surface without a database; <code>dctl client</code> combines it with
+					co-located route reads. Drift fails a check instead of becoming a production surprise.
+				</p>
+			</div>
+			<div class="wf-cards wf-cards-tight">
+				<div class="wf-card">
+					<h3>Application surfaces are capabilities</h3>
+					<p>
+						<code>distributed_client_surface</code> → <code>e2e-ui</code> (user + admin roles for
+						the normal shell). <code>distributed_admin_client_surface</code> →
+						<code>e2e-ui-admin</code>, consumed only by the nested admin layout.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>Routes declare reads, Rust declares writes</h3>
+					<p>
+						Use <code>+page.graphql</code> with <code>@load</code> / <code>@live</code>. Generation
+						emits operations, command tree, static route registry, and SvelteKit adapter.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>After you change the contract</h3>
+					<p>
+						Run <code>make gen-client</code>, inspect and commit artifacts, let
+						<code>make check-client</code> enforce drift. Durable design belongs in the Distributed
+						GitKB; this fixture stays executable.
+					</p>
+				</div>
+			</div>
+			<div class="wf-code wf-code-follow">
+				<div class="wf-code-bar">
+					<span>What a day-to-day write looks like</span>
+					<em>UI</em>
+				</div>
+				<pre><code>{`import { Todos, useCommands } from '$distributed';
+
+const todos = Todos.use();
+const commands = useCommands();
+
+await commands.todo.create({ title }); // todo_id defaults to uuid_v7()
+await commands.todo.reopen({ todo_id });
+await commands.chat.post({ message_id, body, room_id, created_at });
+await commands.blob.move({ game_id, direction: 'up' });
+
+// Inside the nested admin tree only:
+import { useCommands as useAdminCommands } from '$distributed/admin';
+await useAdminCommands().todo.force_archive({ todo_id });`}</code></pre>
+			</div>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-light" id="auth-joins">
+		<div class="wf-band-inner">
+			<div class="wf-section-head">
+				<span class="wf-label">People have names</span>
+				<h2>Import identity once, join everywhere</h2>
+				<p>
+					Do not stamp a free-form display name onto every chat message forever. Import people from
+					the IdP into a directory table, then join. Fix missing people at the source (ingest /
+					scrape), not by inventing a second source of truth on each aggregate.
+				</p>
+			</div>
+			<div class="wf-cards">
+				<div class="wf-card">
+					<h3>Bring users in</h3>
+					<p>
+						Zitadel can push or you can scrape; either way facts land as directory rows. See
+						<code>docs/zitadel-ingestor.md</code> when you need the exact endpoints.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>Join for labels</h3>
+					<p>
+						Blob’s <code>+page.graphql</code> selects the owner join on load. Chat’s
+						<code>author</code> relationship is on the read model — add it to the query when a route
+						needs labels.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>Roles in practice</h3>
+					<p>
+						alice and bob are normal users (their own todos). admin sees everyone and can
+						force-archive via the elevated surface. Groups on the session map into engine roles.
+					</p>
+				</div>
+			</div>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-dark" id="anti-patterns">
+		<div class="wf-band-inner">
+			<div class="wf-section-head">
+				<span class="wf-label">Traps</span>
+				<h2>Things that feel clever and then hurt</h2>
+			</div>
+			<div class="wf-cards">
+				<div class="wf-card">
+					<h3>GraphQL as a free-form table editor</h3>
+					<p>
+						If the UI can UPDATE the todos table directly, you have two write paths and no single
+						history. Prefer commands that go through the domain.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>Two lists for the same data</h3>
+					<p>
+						A local array “for convenience” plus the shared cache for the same list is how board and
+						history disagree. Use one replica-backed operation view.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>Hard refetch that yanks the optimistic UI</h3>
+					<p>
+						Blasting a full reload the instant a command returns can flash or erase the row you just
+						painted. Let effects / Projected payload stand until the replica observes confirmation
+						or a live frame — and respect causal fences on revalidation.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>Believing the client about who they are</h3>
+					<p>
+						Owner and author come from the session. Client-supplied “I am alice” fields are how
+						multi-tenant bugs are born.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>Elevated ops in the user client</h3>
+					<p>
+						Do not smuggle force-archive into the normal <code>e2e-ui</code> surface “for
+						convenience.” Dual surfaces exist so capability matches generation.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>Hand-editing generated files</h3>
+					<p>
+						Change the real source (Rust inventory or co-located query), regenerate, commit. CI
+						checks exist so drift does not wait for a human on-call.
+					</p>
+				</div>
+				<div class="wf-card">
+					<h3>Tokens in the wrong place on WebSockets</h3>
+					<p>
+						Browsers cannot set Authorization on the upgrade the way they do on HTTP. Put the token
+						in the first connection message — never in a long-lived URL query string.
+					</p>
+				</div>
+			</div>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-light" id="extend">
+		<div class="wf-band-inner">
+			<div class="wf-section-head">
+				<span class="wf-label">Extend the template</span>
+				<h2>Adding a feature without losing the plot</h2>
+			</div>
+			<ol class="wf-flow-map">
+				<li>Model the rules in a pure domain crate with tests</li>
+				<li>Describe how those facts look when queried (and any joins)</li>
+				<li>
+					Thin command handler + register typed result (<code>Fact</code> or
+					<code>Projected</code>) + effects/confirmations as needed
+				</li>
+				<li>Projector — or SurfaceDirectProjection for Projected models</li>
+				<li>Permissions + which application surface exports the op</li>
+				<li>Add a co-located <code>+page.graphql</code> and regenerate client artifacts</li>
+				<li>Small UI path: generated <code>View.use()</code> + generated command</li>
+				<li>A test that would fail if you regressed the story</li>
+			</ol>
+		</div>
+	</section>
+
+	<section class="wf-band wf-band-dark wf-cta-band">
+		<div class="wf-band-inner wf-cta">
+			<h2>Go click around</h2>
+			<p>
+				Sign in (alice / bob / admin · Password1!). Feel todos settle after a moment, blob answer in
+				the Projected payload, chat fill from others, admin use a separate surface, session explain
+				who you are.
+			</p>
+			<div class="wf-actions">
+				{#if signedIn}
+					<a class="wf-btn wf-btn-primary" href="/todos">Todos</a>
+					<a class="wf-btn wf-btn-ghost" href="/blob">Blob</a>
+					<a class="wf-btn wf-btn-ghost" href="/chat">Chat</a>
+					<a class="wf-btn wf-btn-ghost" href="/session">Session</a>
+				{:else}
+					<a class="wf-btn wf-btn-primary" href="/signin?callbackUrl=/todos">Sign in</a>
+					<a class="wf-btn wf-btn-ghost" href="#principles">Success rules</a>
+				{/if}
+			</div>
+		</div>
+	</section>
+
+	<Footer />
+</div>
diff --git a/tests/e2e-ui/ui/src/routes/admin/+layout.server.ts b/tests/e2e-ui/ui/src/routes/admin/+layout.server.ts
new file mode 100644
index 00000000..364ba3d1
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/admin/+layout.server.ts
@@ -0,0 +1,40 @@
+import { error } from '@sveltejs/kit';
+import {
+	createDistributedSvelteKitServer,
+	type SveltekitDistributedPageData
+} from '@hops-ops/distributed/sveltekit';
+
+import { DISTRIBUTED_ROUTE_OPERATIONS } from '$distributed/admin';
+import { engineRoleFromGroups, isAdminEngineRole } from '$lib/roles';
+import { graphqlHttpUrl } from '$lib/server/graphql';
+
+import type { LayoutServerLoad } from './$types';
+
+type LoadEvent = Parameters<LayoutServerLoad>[0];
+type Session = NonNullable<
+	Awaited<ReturnType<LoadEvent['locals']['auth']>>
+>;
+
+/**
+ * Elevated GraphQL is a separate generated surface and nested client boundary.
+ * Role failure happens before the server adapter can issue any GraphQL request.
+ */
+const distributed = createDistributedSvelteKitServer<Session, LoadEvent>({
+	routes: DISTRIBUTED_ROUTE_OPERATIONS,
+	getSession: (event) => event.locals.auth(),
+	getRole: (session) => {
+		const role = engineRoleFromGroups(session?.user?.groups);
+		if (!isAdminEngineRole(role)) {
+			error(
+				403,
+				'Admin role required — sign in as admin (Zitadel: admin / Password1!)'
+			);
+		}
+		return role;
+	},
+	getUrl: graphqlHttpUrl
+});
+
+export const load: LayoutServerLoad = distributed.load satisfies (
+	event: LoadEvent
+) => Promise<SveltekitDistributedPageData>;
diff --git a/tests/e2e-ui/ui/src/routes/admin/+layout.svelte b/tests/e2e-ui/ui/src/routes/admin/+layout.svelte
new file mode 100644
index 00000000..6c2bb1cb
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/admin/+layout.svelte
@@ -0,0 +1,57 @@
+<script lang="ts">
+	import { browser } from '$app/environment';
+	import { onDestroy, untrack } from 'svelte';
+	import type { Snippet } from 'svelte';
+	import {
+		createPageDataSessionSource,
+		type SveltekitReplicaHydration
+	} from '@hops-ops/distributed/sveltekit';
+	import { provideDistributed } from '$distributed/admin';
+
+	import type { LayoutData } from './$types';
+
+	let { data, children }: { data: LayoutData; children: Snippet } = $props();
+
+	const initialData = untrack(() => data);
+	const pageData = createPageDataSessionSource(initialData);
+	let appliedHydration: SveltekitReplicaHydration | undefined =
+		initialData.distributed;
+	let hydrationTimer: ReturnType<typeof setTimeout> | undefined;
+
+	const client = provideDistributed({
+		session: pageData.session,
+		browser,
+		...(initialData.distributed !== undefined &&
+		initialData.distributedAuthority !== undefined
+			? {
+					hydration: initialData.distributed,
+					authority: initialData.distributedAuthority
+				}
+			: {})
+	});
+
+	$effect(() => {
+		pageData.set(data);
+		if (
+			data.distributed === undefined ||
+			data.distributedAuthority === undefined ||
+			data.distributed === appliedHydration
+		) {
+			return;
+		}
+
+		appliedHydration = data.distributed;
+		if (hydrationTimer !== undefined) clearTimeout(hydrationTimer);
+		hydrationTimer = setTimeout(() => {
+			hydrationTimer = undefined;
+			client.hydrate(data.distributed!, data.distributedAuthority!);
+		}, 0);
+	});
+
+	onDestroy(() => {
+		if (hydrationTimer !== undefined) clearTimeout(hydrationTimer);
+		client.destroy();
+	});
+</script>
+
+{@render children()}
diff --git a/tests/e2e-ui/ui/src/routes/admin/+page.graphql b/tests/e2e-ui/ui/src/routes/admin/+page.graphql
new file mode 100644
index 00000000..b3b53160
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/admin/+page.graphql
@@ -0,0 +1,9 @@
+# Elevated surface: deterministic and bounded all-owner view.
+query AdminAllTodos @load {
+  todos(limit: 100, order_by: [{ status: asc }, { owner_id: asc }, { todo_id: asc }]) {
+    todo_id
+    owner_id
+    title
+    status
+  }
+}
diff --git a/tests/e2e-ui/ui/src/routes/admin/+page.svelte b/tests/e2e-ui/ui/src/routes/admin/+page.svelte
new file mode 100644
index 00000000..040bf770
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/admin/+page.svelte
@@ -0,0 +1,229 @@
+<script lang="ts">
+	/**
+	 * Admin: separate elevated generated surface + causal command runtime.
+	 */
+	import { AdminAllTodos, useCommands } from '$distributed/admin';
+	import { Button } from '$lib/components/shared/ui';
+	import {
+		AppPage,
+		InlineAlert,
+		PageHeader,
+		StatRow
+	} from '$lib/components/product';
+	import { sessionDisplayName } from '$lib/session';
+
+	let { data } = $props();
+	let actionError = $state<string | null>(null);
+	let busy = $state(false);
+
+	const who = $derived(sessionDisplayName(data.session));
+	const listLimit = 100;
+
+	const list = AdminAllTodos.use();
+	const commands = useCommands();
+
+	// The generated query/index plan owns collection order.
+	const rows = $derived($list.complete ? $list.data.todos : []);
+	const owners = $derived([...new Set(rows.map((todo) => todo.owner_id))].sort());
+	const open = $derived(rows.filter((todo) => todo.status !== 'archived'));
+	const atCap = $derived(rows.length >= listLimit);
+
+	async function forceArchive(todo_id: string) {
+		if (busy) return;
+		const target = rows.find((todo) => todo.todo_id === todo_id);
+		if (!target || target.status === 'archived') return;
+
+		actionError = null;
+		busy = true;
+		try {
+			await commands.todo.force_archive({ todo_id });
+		} catch (error) {
+			actionError = error instanceof Error ? error.message : 'force archive failed';
+		} finally {
+			busy = false;
+		}
+	}
+</script>
+
+<AppPage width="wide">
+	<PageHeader kicker="admin · Role-scoped GraphQL" title="All todos">
+		Signed in as <strong>{who}</strong> with engine role
+		<code>{data.engineRole}</code>. This nested layout installs a separate
+		<code>e2e-ui-admin</code> client, so elevated query and command artifacts cannot leak
+		into the normal application bundle.
+	</PageHeader>
+
+	{#if data.gqlError}
+		<InlineAlert label="SSR GraphQL">{data.gqlError}</InlineAlert>
+	{/if}
+	{#if actionError}
+		<InlineAlert label="Mutation">{actionError}</InlineAlert>
+	{/if}
+
+	<StatRow
+		stats={[
+			{ value: rows.length, label: 'notes' },
+			{ value: owners.length, label: 'owners' },
+			{ value: open.length, label: 'active' }
+		]}
+	/>
+
+	{#if atCap}
+		<p class="ad-cap" role="status">
+			Showing first {listLimit} notes (bounded admin query). Refine filters or raise limit in
+			<code>+page.graphql</code> if needed.
+		</p>
+	{/if}
+
+	{#if rows.length === 0}
+		<p class="ad-empty">No todos in the read model yet. Create some as alice/bob on /todos.</p>
+	{:else}
+		<div class="ad-table-wrap">
+			<table class="ad-table">
+				<thead>
+					<tr>
+						<th>Owner</th>
+						<th>Title</th>
+						<th>Status</th>
+						<th>Id</th>
+						<th></th>
+					</tr>
+				</thead>
+				<tbody>
+					{#each rows as t (t.todo_id)}
+						<tr data-todo-id={t.todo_id}>
+							<td class="ad-owner">{t.owner_id}</td>
+							<td>{t.title}</td>
+							<td><span class="ad-status" data-status={t.status}>{t.status}</span></td>
+							<td class="ad-id">{t.todo_id}</td>
+							<td class="ad-actions">
+								{#if t.status !== 'archived'}
+									<Button
+										type="button"
+										variant="ghost"
+										size="sm"
+										disabled={busy}
+										onclick={() => forceArchive(t.todo_id)}
+									>
+										Force archive
+									</Button>
+								{:else}
+									<span class="ad-muted">—</span>
+								{/if}
+							</td>
+						</tr>
+					{/each}
+				</tbody>
+			</table>
+		</div>
+	{/if}
+
+	<p class="ad-foot">
+		The normal <code>e2e-ui</code> surface cannot even name
+		<code>todo.force_archive</code>. The elevated artifact is generated only for this
+		admin-gated component tree.
+	</p>
+</AppPage>
+
+<style>
+	/* Route-local table surface */
+	.ad-table-wrap {
+		--ink: var(--wf-ink, #1c1c1a);
+		--ink-soft: var(--wf-ink-soft, #5c5c56);
+		--edge: var(--wf-line, #e2e0d9);
+		--surface: var(--wf-bg-elevated, #fff);
+		overflow-x: auto;
+		border-radius: var(--df-radius-lg, 10px);
+		border: 1px solid var(--edge);
+		background: var(--surface);
+	}
+
+	.ad-table {
+		width: 100%;
+		border-collapse: collapse;
+		font-size: 0.9rem;
+		color: var(--ink);
+	}
+
+	.ad-table th,
+	.ad-table td {
+		text-align: left;
+		padding: 0.65rem 0.85rem;
+		border-bottom: 1px solid var(--edge);
+		vertical-align: middle;
+	}
+
+	.ad-table th {
+		font-size: 0.68rem;
+		font-weight: 700;
+		letter-spacing: 0.08em;
+		text-transform: uppercase;
+		color: var(--ink-soft);
+		background: rgba(28, 28, 26, 0.02);
+	}
+
+	.ad-table tr:last-child td {
+		border-bottom: none;
+	}
+
+	.ad-owner,
+	.ad-id {
+		font-family: var(--wf-mono, ui-monospace, monospace);
+		font-size: 0.78rem;
+	}
+
+	.ad-status {
+		font-size: 0.75rem;
+		font-weight: 600;
+		text-transform: uppercase;
+		letter-spacing: 0.04em;
+	}
+
+	.ad-status[data-status='open'] {
+		color: var(--wf-accent, #3d5a80);
+	}
+
+	.ad-status[data-status='completed'] {
+		color: var(--wf-success, #2f6f4e);
+	}
+
+	.ad-status[data-status='archived'] {
+		color: var(--ink-soft);
+	}
+
+	.ad-actions {
+		white-space: nowrap;
+	}
+
+	.ad-muted {
+		color: var(--ink-soft);
+		font-size: 0.85rem;
+	}
+
+	.ad-empty {
+		color: var(--ink-soft);
+	}
+
+	.ad-cap {
+		font-size: 0.88rem;
+		color: var(--ink-soft);
+		margin: 0 0 1rem;
+		padding: 0.65rem 0.85rem;
+		border-radius: var(--wf-radius, 6px);
+		background: var(--wf-accent-soft, rgba(61, 90, 128, 0.08));
+		border: 1px solid var(--edge, var(--wf-line, #e2e0d9));
+	}
+
+	.ad-cap code,
+	.ad-foot code {
+		font-family: var(--wf-mono, ui-monospace, monospace);
+		font-size: 0.9em;
+	}
+
+	.ad-foot {
+		margin-top: 1.5rem;
+		font-size: 0.88rem;
+		line-height: 1.5;
+		color: var(--ink-soft, var(--wf-ink-soft, #5c5c56));
+	}
+</style>
diff --git a/tests/e2e-ui/ui/src/routes/api/auth/refresh/+server.ts b/tests/e2e-ui/ui/src/routes/api/auth/refresh/+server.ts
new file mode 100644
index 00000000..33ef13f0
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/api/auth/refresh/+server.ts
@@ -0,0 +1,21 @@
+import { json } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+
+export const POST: RequestHandler = async ({ locals }) => {
+	const session = await locals.auth();
+
+	if (!session?.user) {
+		return json({ authenticated: false }, { status: 401 });
+	}
+
+	return json({
+		authenticated: true,
+		expires: session.expires,
+		expiresAt: session.expiresAt,
+		refreshAfter: session.refreshAfter,
+		hasAccessToken: session.hasAccessToken,
+		hasRefreshToken: session.hasRefreshToken,
+		hasIdToken: session.hasIdToken,
+		error: session.error
+	});
+};
diff --git a/tests/e2e-ui/ui/src/routes/blob/[[gameId]]/+page.graphql b/tests/e2e-ui/ui/src/routes/blob/[[gameId]]/+page.graphql
new file mode 100644
index 00000000..5cbc2c79
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/blob/[[gameId]]/+page.graphql
@@ -0,0 +1,19 @@
+# Blob games join their imported owner records and are seeded on route load.
+query BlobGames @load {
+  blob_games(order_by: [{ game_id: asc }]) {
+    game_id
+    owner_id
+    score
+    player_dead
+    current_level
+    current_level_completed
+    map_json
+    status
+    owner {
+      user_id
+      display_name
+      email
+      status
+    }
+  }
+}
diff --git a/tests/e2e-ui/ui/src/routes/blob/[[gameId]]/+page.svelte b/tests/e2e-ui/ui/src/routes/blob/[[gameId]]/+page.svelte
new file mode 100644
index 00000000..4faf00e6
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/blob/[[gameId]]/+page.svelte
@@ -0,0 +1,600 @@
+<script lang="ts">
+	/**
+	 * Blob Game — URL-routed selection from one generated replica operation.
+	 *
+	 * - URL (`/blob` | `/blob/{gameId}`) selects which game is active.
+	 * - Board and history derive directly from `BlobGames.use()`.
+	 * - Projected command payloads enter that same replica before calls resolve.
+	 */
+	import { onMount } from 'svelte';
+	import { goto } from '$app/navigation';
+	import { page } from '$app/state';
+	import { BlobGames, useCommands } from '$distributed';
+	import { Button } from '$lib/components/shared/ui';
+	import { AppPage, InlineAlert, PageHeader } from '$lib/components/product';
+
+	const TILE = {
+		player: 9,
+		hole: 0,
+		unvisited: 1,
+		visited: 2,
+		deadBySuicide: 3,
+		deadByHole: 4
+	} as const;
+	type Direction = 'up' | 'down' | 'left' | 'right';
+
+	let { data } = $props();
+	let actionError = $state<string | null>(null);
+	let commandPending = $state(false);
+	let hydrated = $state(false);
+
+	const routeGameId = $derived(page.params.gameId ?? null);
+
+	function gamePath(gameId: string) {
+		return `/blob/${encodeURIComponent(gameId)}`;
+	}
+
+	function navigateToGame(gameId: string, replace = false) {
+		if (routeGameId === gameId) return;
+		void goto(gamePath(gameId), { replaceState: replace, noScroll: true, keepFocus: true });
+	}
+
+	const list = BlobGames.use();
+	const commands = useCommands();
+	const games = $derived($list.complete ? $list.data.blob_games : []);
+	const selected = $derived(
+		routeGameId ? (games.find((game) => game.game_id === routeGameId) ?? null) : null
+	);
+	const board = $derived.by(() => {
+		if (!selected) return [];
+		try {
+			const value = JSON.parse(selected.map_json || '[]') as unknown;
+			return Array.isArray(value) &&
+				value.every(
+					(row) => Array.isArray(row) && row.every((cell) => typeof cell === 'number')
+				)
+				? (value as number[][])
+				: [];
+		} catch {
+			return [];
+		}
+	});
+
+	const cols = $derived(board[0]?.length ?? 0);
+	const hasBoard = $derived(board.length > 0 && cols > 0);
+	const score = $derived(Number(selected?.score ?? 0));
+	const playerDead = $derived(!!selected?.player_dead);
+	const levelComplete = $derived(!!selected?.current_level_completed);
+	const currentLevel = $derived(Number(selected?.current_level ?? 0));
+	const status = $derived(selected?.status ?? 'active');
+
+	function newGameId() {
+		const rand =
+			typeof crypto !== 'undefined' && 'randomUUID' in crypto
+				? crypto.randomUUID().replace(/-/g, '').slice(0, 12)
+				: `${Date.now().toString(16)}${Math.random().toString(16).slice(2, 8)}`;
+		return `blob-${rand}`;
+	}
+
+	function tileClass(t: number): string {
+		switch (t) {
+			case TILE.player:
+				return 'tile-player';
+			case TILE.hole:
+				return 'tile-hole';
+			case TILE.unvisited:
+				return 'tile-unvisited';
+			case TILE.visited:
+				return 'tile-visited';
+			case TILE.deadBySuicide:
+				return 'tile-dead-suicide';
+			case TILE.deadByHole:
+				return 'tile-dead-hole';
+			default:
+				return 'tile-unknown';
+		}
+	}
+
+	function tileLabel(t: number): string {
+		if (t === TILE.player) return '●';
+		if (t === TILE.deadByHole || t === TILE.deadBySuicide) return '✕';
+		return '';
+	}
+
+	async function startGame() {
+		if (commandPending) return;
+		commandPending = true;
+		actionError = null;
+		const game_id = newGameId();
+		try {
+			const receipt = await commands.blob.start({ game_id });
+			navigateToGame(receipt.result.game_id, true);
+		} catch (e) {
+			actionError = e instanceof Error ? e.message : 'Start failed';
+		} finally {
+			commandPending = false;
+		}
+	}
+
+	function canMove(direction: Direction): boolean {
+		let playerRow = -1;
+		let playerCol = -1;
+		for (const [rowIndex, row] of board.entries()) {
+			const colIndex = row.indexOf(TILE.player);
+			if (colIndex >= 0) {
+				playerRow = rowIndex;
+				playerCol = colIndex;
+				break;
+			}
+		}
+		if (playerRow < 0 || playerCol < 0) return true;
+		return (
+			(direction !== 'up' || playerRow > 0) &&
+			(direction !== 'down' || playerRow < board.length - 1) &&
+			(direction !== 'left' || playerCol > 0) &&
+			(direction !== 'right' || playerCol < cols - 1)
+		);
+	}
+
+	async function move(direction: Direction) {
+		if (!selected || playerDead || levelComplete || !hasBoard || commandPending) return;
+		// The replica already contains enough board state to recognize an edge.
+		// Treat it as a game no-op instead of dispatching a predictably rejected command.
+		if (!canMove(direction)) {
+			actionError = null;
+			return;
+		}
+		commandPending = true;
+		actionError = null;
+		try {
+			await commands.blob.move({ game_id: selected.game_id, direction });
+		} catch (error) {
+			actionError = error instanceof Error ? error.message : 'Move failed';
+		} finally {
+			commandPending = false;
+		}
+	}
+
+	async function nextLevel() {
+		if (!selected || playerDead || !levelComplete || commandPending) return;
+		commandPending = true;
+		actionError = null;
+		try {
+			await commands.blob.start_level({ game_id: selected.game_id });
+		} catch (error) {
+			actionError = error instanceof Error ? error.message : 'Next level failed';
+		} finally {
+			commandPending = false;
+		}
+	}
+
+	function selectGame(id: string) {
+		if (id === routeGameId) return;
+		actionError = null;
+		navigateToGame(id);
+	}
+
+	function onKey(e: KeyboardEvent) {
+		const map: Record<string, Direction> = {
+			ArrowUp: 'up',
+			ArrowDown: 'down',
+			ArrowLeft: 'left',
+			ArrowRight: 'right',
+			w: 'up',
+			s: 'down',
+			a: 'left',
+			d: 'right',
+			W: 'up',
+			S: 'down',
+			A: 'left',
+			D: 'right'
+		};
+		const dir = map[e.key];
+		if (dir) {
+			e.preventDefault();
+			void move(dir);
+		}
+	}
+
+	onMount(() => {
+		hydrated = true;
+		window.addEventListener('keydown', onKey);
+		return () => window.removeEventListener('keydown', onKey);
+	});
+</script>
+
+<svelte:head>
+	<title>Blob Game · e2e-ui</title>
+</svelte:head>
+
+<AppPage>
+	<div class="blob-page" data-blob-hydrated={hydrated ? '1' : '0'}>
+		<div class="blob-title-row">
+			<PageHeader
+				kicker="URL select · generated replica · projected commands"
+				title="Blob Game"
+			>
+				Board and history render from the same generated <code>BlobGames</code>
+				operation. Typed projected commands update that replica before they resolve.
+			</PageHeader>
+			<Button
+				type="button"
+				variant="ink"
+				data-testid="blob-new-game"
+				onclick={() => void startGame()}
+				disabled={!hydrated}
+			>
+				New game
+			</Button>
+		</div>
+
+		{#if data.gqlError}
+			<InlineAlert label="SSR GraphQL">{data.gqlError}</InlineAlert>
+		{/if}
+		{#if actionError}
+			<InlineAlert label="Command">{actionError}</InlineAlert>
+		{/if}
+
+		{#if routeGameId && $list.loading && !selected && !data.gqlError}
+			<div class="blob-empty">
+				<p class="blob-empty-copy">Loading game…</p>
+			</div>
+		{:else if routeGameId && !hasBoard && !data.gqlError}
+			<div class="blob-empty">
+				<p class="blob-empty-copy">
+					Game <code>{routeGameId}</code> not found (or not yours).
+				</p>
+				<Button href="/blob" variant="ink">All games</Button>
+			</div>
+		{:else if !hasBoard}
+			<div class="blob-empty">
+				<p class="blob-empty-copy">No game selected. Start one to play.</p>
+				<Button
+					type="button"
+					variant="ink"
+					data-testid="blob-start-game"
+					onclick={() => void startGame()}
+					disabled={commandPending || !hydrated}
+				>
+					Start game
+				</Button>
+			</div>
+		{:else}
+			<div class="blob-stage">
+				<div class="blob-hud">
+					<div class="hud-stat">
+						<span class="hud-label">Score</span>
+						<strong class="hud-value">{score}</strong>
+					</div>
+					<div class="hud-stat">
+						<span class="hud-label">Level</span>
+						<strong class="hud-value">{currentLevel}</strong>
+					</div>
+					<div class="hud-stat">
+						<span class="hud-label">Status</span>
+						<strong class="hud-value hud-status-{status}">{status}</strong>
+					</div>
+					{#if playerDead}
+						<span class="hud-banner dead">You died — start a new game</span>
+					{:else if levelComplete}
+						<span class="hud-banner win">Level complete</span>
+						<Button
+							type="button"
+							variant="ink"
+							onclick={() => void nextLevel()}
+							disabled={commandPending}
+						>
+							Next level
+						</Button>
+					{/if}
+				</div>
+
+				<div class="blob-board" style="--cols: {cols}" role="grid" aria-label="Blob game board">
+					{#each board as row, r}
+						{#each row as cell, c}
+							<div class="cell {tileClass(cell)}" role="gridcell" aria-label="r{r} c{c}">
+								{tileLabel(cell)}
+							</div>
+						{/each}
+					{/each}
+				</div>
+
+				<div class="blob-legend" aria-hidden="true">
+					<span><i class="swatch tile-player"></i> You</span>
+					<span><i class="swatch tile-unvisited"></i> Unvisited</span>
+					<span><i class="swatch tile-visited"></i> Visited</span>
+					<span><i class="swatch tile-hole"></i> Hole</span>
+					<span><i class="swatch tile-dead-hole"></i> Death</span>
+				</div>
+
+				<div class="blob-pad" aria-label="Move controls">
+					<button
+						type="button"
+						class="pad-btn"
+						onclick={() => void move('up')}
+						disabled={playerDead || levelComplete}>↑</button
+					>
+					<div class="pad-row">
+						<button
+							type="button"
+							class="pad-btn"
+							onclick={() => void move('left')}
+							disabled={playerDead || levelComplete}>←</button
+						>
+						<button
+							type="button"
+							class="pad-btn"
+							onclick={() => void move('down')}
+							disabled={playerDead || levelComplete}>↓</button
+						>
+						<button
+							type="button"
+							class="pad-btn"
+							onclick={() => void move('right')}
+							disabled={playerDead || levelComplete}>→</button
+						>
+					</div>
+				</div>
+			</div>
+		{/if}
+
+		{#if games.length > 0}
+			<section class="blob-history">
+				<h2>Your games</h2>
+				<ul>
+					{#each games as g (g.game_id)}
+						<li>
+							<a
+								href={gamePath(g.game_id)}
+								class="history-item"
+								class:active={g.game_id === routeGameId}
+								onclick={(e) => {
+									e.preventDefault();
+									selectGame(g.game_id);
+								}}
+							>
+								<span class="history-id">{g.game_id.slice(0, 14)}…</span>
+								<span>score {g.score}</span>
+								<span class="hud-status-{g.status}">{g.status}</span>
+							</a>
+						</li>
+					{/each}
+				</ul>
+			</section>
+		{/if}
+	</div>
+</AppPage>
+
+<style>
+	.blob-page {
+		position: relative;
+	}
+	.blob-title-row {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: flex-start;
+		justify-content: space-between;
+		gap: 1rem;
+	}
+	.blob-empty {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		text-align: center;
+		gap: 1rem;
+		padding: 2rem 1rem 2.5rem;
+		border: 1px dashed var(--wf-line-strong, #cdcabe);
+		border-radius: 12px;
+		background: var(--wf-bg-elevated, #fff);
+	}
+	.blob-empty-copy {
+		margin: 0;
+		max-width: 28rem;
+		font-size: 0.92rem;
+		color: var(--wf-ink-soft, #5c5c56);
+		line-height: 1.45;
+	}
+	.blob-stage {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		gap: 1.1rem;
+	}
+	.blob-hud {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		justify-content: center;
+		gap: 0.75rem 1.25rem;
+		width: 100%;
+		padding: 0.85rem 1rem;
+		border-radius: 10px;
+		background: var(--wf-bg-elevated, #fff);
+		border: 1px solid var(--wf-line, #e2e0d9);
+	}
+	.hud-stat {
+		display: flex;
+		flex-direction: column;
+		gap: 0.1rem;
+		min-width: 4.5rem;
+	}
+	.hud-label {
+		font-size: 0.68rem;
+		font-weight: 700;
+		letter-spacing: 0.1em;
+		text-transform: uppercase;
+		color: var(--wf-ink-muted, #8a8a82);
+	}
+	.hud-value {
+		font-size: 1.15rem;
+		font-variant-numeric: tabular-nums;
+	}
+	.hud-status-active {
+		color: var(--wf-accent, #3d5a80);
+	}
+	.hud-status-dead {
+		color: var(--wf-danger, #b33a3a);
+	}
+	.hud-status-level_complete {
+		color: var(--wf-success, #2f6f4e);
+	}
+	.hud-banner {
+		font-weight: 700;
+		font-size: 0.9rem;
+		padding: 0.35rem 0.65rem;
+		border-radius: 6px;
+	}
+	.hud-banner.dead {
+		background: rgba(179, 58, 58, 0.12);
+		color: var(--wf-danger, #b33a3a);
+	}
+	.hud-banner.win {
+		background: rgba(47, 111, 78, 0.12);
+		color: var(--wf-success, #2f6f4e);
+	}
+	.blob-board {
+		display: grid;
+		grid-template-columns: repeat(var(--cols), minmax(2.5rem, 3rem));
+		gap: 4px;
+		padding: 0.65rem;
+		background: #141412;
+		border-radius: 12px;
+		box-shadow: 0 16px 40px rgba(0, 0, 0, 0.18);
+		width: max-content;
+		max-width: 100%;
+		contain: layout style;
+	}
+	.cell {
+		aspect-ratio: 1;
+		min-width: 2.5rem;
+		min-height: 2.5rem;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		border-radius: 5px;
+		font-size: 1rem;
+		font-weight: 700;
+	}
+	.tile-player {
+		background: linear-gradient(145deg, #7eb6ff, #4a8fe0);
+		color: #0a1628;
+		box-shadow: 0 0 0 2px rgba(126, 182, 255, 0.45);
+	}
+	.tile-hole {
+		background: radial-gradient(circle at 40% 35%, #2a2a28 0%, #0a0a09 70%);
+		box-shadow: inset 0 2px 6px rgba(0, 0, 0, 0.6);
+	}
+	.tile-unvisited {
+		background: #3f6b45;
+	}
+	.tile-visited {
+		background: #243528;
+	}
+	.tile-dead-suicide,
+	.tile-dead-hole {
+		background: #a33a3a;
+		color: #fff;
+	}
+	.tile-unknown {
+		background: #444;
+	}
+	.blob-legend {
+		display: flex;
+		flex-wrap: wrap;
+		justify-content: center;
+		gap: 0.75rem 1.1rem;
+		font-size: 0.78rem;
+		color: var(--wf-ink-soft, #5c5c56);
+	}
+	.blob-legend span {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.35rem;
+	}
+	.swatch {
+		display: inline-block;
+		width: 0.85rem;
+		height: 0.85rem;
+		border-radius: 3px;
+	}
+	.blob-pad {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		gap: 0.4rem;
+	}
+	.pad-row {
+		display: flex;
+		gap: 0.4rem;
+	}
+	.pad-btn {
+		width: 3rem;
+		height: 3rem;
+		border-radius: 8px;
+		border: 1px solid var(--wf-line-strong, #cdcabe);
+		background: #fff;
+		font-size: 1.2rem;
+		cursor: pointer;
+		touch-action: manipulation;
+	}
+	.pad-btn:active:not(:disabled) {
+		transform: scale(0.96);
+	}
+	.pad-btn:disabled {
+		opacity: 0.45;
+		cursor: not-allowed;
+	}
+	.blob-history {
+		margin-top: 2.5rem;
+		padding-top: 1.5rem;
+		border-top: 1px solid var(--wf-line, #e2e0d9);
+	}
+	.blob-history h2 {
+		margin: 0 0 0.75rem;
+		font-size: 0.95rem;
+	}
+	.blob-history ul {
+		list-style: none;
+		margin: 0;
+		padding: 0;
+		display: flex;
+		flex-direction: column;
+		gap: 0.35rem;
+	}
+	.history-item {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 0.5rem 1rem;
+		width: 100%;
+		text-align: left;
+		appearance: none;
+		border: 1px solid var(--wf-line, #e2e0d9);
+		background: #fff;
+		border-radius: 8px;
+		padding: 0.55rem 0.75rem;
+		font: inherit;
+		font-size: 0.85rem;
+		cursor: pointer;
+		text-decoration: none;
+		color: inherit;
+	}
+	.history-item.active {
+		border-color: var(--wf-accent, #3d5a80);
+		background: var(--wf-accent-soft, rgba(61, 90, 128, 0.08));
+		font-weight: 600;
+	}
+	.history-id {
+		font-family: var(--wf-mono, ui-monospace, monospace);
+		font-size: 0.8rem;
+	}
+	@media (max-width: 480px) {
+		.blob-board {
+			grid-template-columns: repeat(var(--cols), minmax(2rem, 1fr));
+			width: 100%;
+		}
+		.cell {
+			min-width: 0;
+			min-height: 0;
+		}
+	}
+</style>
diff --git a/tests/e2e-ui/ui/src/routes/chat/+page.graphql b/tests/e2e-ui/ui/src/routes/chat/+page.graphql
new file mode 100644
index 00000000..4f84e948
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/chat/+page.graphql
@@ -0,0 +1,11 @@
+# One query declaration owns SSR, normalized cache reads, and its generated
+# live companion. The page never maintains a second subscription document.
+query ChatMessages @load @live {
+  chat_messages(where: { room_id: { _eq: "lobby" } }) {
+    message_id
+    room_id
+    author_id
+    body
+    created_at
+  }
+}
diff --git a/tests/e2e-ui/ui/src/routes/chat/+page.svelte b/tests/e2e-ui/ui/src/routes/chat/+page.svelte
new file mode 100644
index 00000000..b53796ee
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/chat/+page.svelte
@@ -0,0 +1,373 @@
+<script lang="ts">
+	/**
+	 * Lobby chat — one generated `@load @live` operation.
+	 *
+	 * SSR, normalized reads, reconnect, and command facts converge through the
+	 * package replica. The page declares no cache keys or subscription document.
+	 */
+	import { tick } from 'svelte';
+
+	import {
+		ChatMessages,
+		useCommands,
+		type Operation_ChatMessages_Data
+	} from '$distributed';
+	import { Button } from '$lib/components/shared/ui';
+	import { AppPage, InlineAlert, PageHeader } from '$lib/components/product';
+	import { isOwnAuthor, sessionDisplayName, sessionPrincipalId } from '$lib/session';
+
+	type ChatMsg = Operation_ChatMessages_Data['chat_messages'][number];
+
+	const LOBBY_ROOM = 'lobby';
+
+	let { data } = $props();
+	let sendError = $state<string | null>(null);
+	let logEl: HTMLDivElement | undefined = $state();
+	let draft = $state('');
+	let busy = $state(false);
+
+	/** Same principal the API stamps as author_id (access-token sub). */
+	const me = $derived(
+		sessionPrincipalId(data.session, data.accessToken ?? data.session?.accessToken)
+	);
+	const displayName = $derived(sessionDisplayName(data.session));
+
+	/** `use()` defaults live because the artifact has a generated companion. */
+	const lobby = ChatMessages.use();
+	const commands = useCommands();
+	const messages = $derived($lobby.complete ? $lobby.data.chat_messages : []);
+
+	async function scrollBottom() {
+		await tick();
+		if (logEl) logEl.scrollTop = logEl.scrollHeight;
+	}
+
+	$effect(() => {
+		messages;
+		void scrollBottom();
+	});
+
+	function shortId(id: string) {
+		if (!id) return '?';
+		if (id.length <= 10) return id;
+		return id.slice(0, 6) + '…';
+	}
+
+	function formatWhen(raw: string) {
+		if (!raw) return '';
+		// Server may emit unix millis as a decimal string (no chrono in fixture).
+		const asNum = /^\d{11,16}$/.test(raw.trim()) ? Number(raw) : NaN;
+		const d = Number.isFinite(asNum) ? new Date(asNum) : new Date(raw);
+		if (Number.isNaN(d.getTime())) return raw;
+		return d.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' });
+	}
+
+	function messageIsMine(m: ChatMsg): boolean {
+		return isOwnAuthor(m.author_id, me);
+	}
+
+	async function onSend(e: Event) {
+		e.preventDefault();
+		const body = draft.trim();
+		if (!body || busy) return;
+		const now = Date.now();
+		const message_id = `m-${now.toString(16)}`;
+		sendError = null;
+		busy = true;
+		// Clear only the submitted draft. Anything typed while this command is
+		// pending belongs to the next message and must survive its completion.
+		draft = '';
+		try {
+			await commands.chat.post({
+				message_id,
+				body,
+				room_id: LOBBY_ROOM,
+				created_at: String(now)
+			});
+		} catch (error) {
+			if (!draft.trim()) draft = body;
+			sendError = error instanceof Error ? error.message : 'send failed';
+		} finally {
+			busy = false;
+		}
+	}
+</script>
+
+<AppPage>
+	<PageHeader kicker="Room · {LOBBY_ROOM}" title="Lobby">
+		{#snippet meta()}
+			<div class="ch-status" data-state={$lobby.live}>
+				<span class="ch-pulse" aria-hidden="true"></span>
+				{#if $lobby.live === 'active'}
+					Live
+				{:else if $lobby.live === 'connecting'}
+					Connecting…
+				{:else if $lobby.live === 'error'}
+					Offline
+				{:else}
+					Idle
+				{/if}
+			</div>
+		{/snippet}
+		The generated <code>@load @live</code> artifact owns SSR and reconnect. A typed
+		<code>chat.post</code> command updates the same normalized state. Signed in as
+		<strong>{displayName}</strong>.
+	</PageHeader>
+
+	{#if data.gqlError}
+		<InlineAlert label="SSR GraphQL">{data.gqlError}</InlineAlert>
+	{/if}
+	{#if $lobby.error}
+		<InlineAlert label="Subscription">
+			{$lobby.error.message}
+			<button type="button" class="ch-link-btn" onclick={() => void lobby.refetch()}>Retry</button>
+		</InlineAlert>
+	{/if}
+	{#if sendError}
+		<InlineAlert label="Mutation">{sendError}</InlineAlert>
+	{/if}
+
+	<div class="ch-shell">
+		<div class="ch-log" bind:this={logEl} role="log" aria-live="polite" aria-relevant="additions">
+			{#if messages.length === 0}
+				<div class="ch-empty">
+					<div class="ch-empty-icon" aria-hidden="true">◇</div>
+					<p>No messages yet. Say hello to the lobby.</p>
+				</div>
+			{:else}
+				{#each messages as m, i (m.message_id)}
+					{@const mine = messageIsMine(m)}
+					{@const authorLabel = mine ? 'You' : shortId(m.author_id)}
+					<article class="ch-msg" class:mine style="--i: {i}">
+						<header class="ch-msg-meta">
+							<span class="ch-author" title={m.author_id}>{authorLabel}</span>
+							<time class="ch-when" datetime={m.created_at}>{formatWhen(m.created_at)}</time>
+						</header>
+						<p class="ch-body">{m.body}</p>
+					</article>
+				{/each}
+			{/if}
+		</div>
+
+		<form class="ch-composer" onsubmit={onSend}>
+			<label class="ch-sr" for="chat-body">Message</label>
+			<input
+				id="chat-body"
+				class="ch-input"
+				name="body"
+				placeholder="Message the lobby…"
+				required
+				autocomplete="off"
+				bind:value={draft}
+			/>
+			<Button type="submit" variant="ink" disabled={!draft.trim() || busy}>
+				Send
+				<svg width="16" height="16" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+					<path
+						d="M5 12h14M13 6l6 6-6 6"
+						stroke="currentColor"
+						stroke-width="2.4"
+						stroke-linecap="round"
+						stroke-linejoin="round"
+					/>
+				</svg>
+			</Button>
+		</form>
+	</div>
+</AppPage>
+
+<style>
+	/* Lobby shell + messages — page-local only */
+	.ch-shell {
+		--edge: var(--wf-line, #e2e0d9);
+		--ink: var(--wf-ink, #1c1c1a);
+		--ink-soft: var(--wf-ink-soft, #5c5c56);
+		--accent: var(--wf-accent, #3d5a80);
+		--surface: var(--wf-bg-elevated, #fff);
+		--bubble: #f0efe9;
+		--bubble-mine: var(--wf-ink, #1c1c1a);
+
+		display: flex;
+		flex-direction: column;
+		min-height: min(62vh, 34rem);
+		border-radius: var(--df-radius-lg, 10px);
+		border: 1px solid var(--edge);
+		background: var(--surface);
+		overflow: hidden;
+	}
+
+	.ch-status {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.4rem;
+		padding: 0.35rem 0.7rem;
+		border-radius: 999px;
+		font-size: 0.72rem;
+		font-weight: 600;
+		letter-spacing: 0.04em;
+		text-transform: uppercase;
+		background: transparent;
+		border: 1px solid var(--wf-line, #e2e0d9);
+		color: var(--wf-ink-soft, #5c5c56);
+	}
+
+	.ch-status[data-state='active'] {
+		color: var(--wf-success, #2f6f4e);
+		background: rgba(47, 111, 78, 0.1);
+		border-color: rgba(47, 111, 78, 0.22);
+	}
+
+	.ch-status[data-state='error'] {
+		color: var(--wf-danger, #b33a3a);
+		background: rgba(179, 58, 58, 0.08);
+		border-color: rgba(179, 58, 58, 0.22);
+	}
+
+	.ch-status[data-state='connecting'] {
+		color: var(--wf-accent, #3d5a80);
+		background: var(--wf-accent-soft, rgba(61, 90, 128, 0.08));
+		border-color: var(--wf-line, #e2e0d9);
+	}
+
+	.ch-pulse {
+		width: 0.45rem;
+		height: 0.45rem;
+		border-radius: 50%;
+		background: currentColor;
+	}
+
+	.ch-status[data-state='active'] .ch-pulse {
+		box-shadow: 0 0 0 0 rgba(47, 111, 78, 0.45);
+		animation: ch-pulse 1.6s ease infinite;
+	}
+
+	@keyframes ch-pulse {
+		70% {
+			box-shadow: 0 0 0 7px transparent;
+		}
+		100% {
+			box-shadow: 0 0 0 0 transparent;
+		}
+	}
+
+	.ch-link-btn {
+		margin-left: 0.75rem;
+		border: none;
+		background: transparent;
+		color: inherit;
+		font: inherit;
+		font-weight: 600;
+		text-decoration: underline;
+		cursor: pointer;
+	}
+
+	.ch-log {
+		flex: 1;
+		overflow-y: auto;
+		padding: 1.1rem 1rem 0.75rem;
+		display: flex;
+		flex-direction: column;
+		gap: 0.55rem;
+		scroll-behavior: smooth;
+	}
+
+	.ch-empty {
+		margin: auto;
+		text-align: center;
+		color: var(--ink-soft);
+		padding: 2rem 1rem;
+	}
+
+	.ch-empty-icon {
+		font-size: 1.35rem;
+		opacity: 0.35;
+		margin-bottom: 0.5rem;
+	}
+
+	.ch-msg {
+		max-width: min(88%, 28rem);
+		align-self: flex-start;
+		padding: 0.6rem 0.8rem 0.7rem;
+		border-radius: 10px 10px 10px 4px;
+		background: var(--bubble);
+		border: 1px solid var(--edge);
+	}
+
+	.ch-msg.mine {
+		align-self: flex-end;
+		border-radius: 10px 10px 4px 10px;
+		background: var(--bubble-mine);
+		border-color: transparent;
+		color: #f6f5f2;
+	}
+
+	.ch-msg-meta {
+		display: flex;
+		align-items: baseline;
+		justify-content: space-between;
+		gap: 0.75rem;
+		margin-bottom: 0.2rem;
+	}
+
+	.ch-author {
+		font-size: 0.7rem;
+		font-weight: 600;
+		letter-spacing: 0.04em;
+		text-transform: uppercase;
+		opacity: 0.65;
+	}
+
+	.ch-when {
+		font-size: 0.68rem;
+		font-variant-numeric: tabular-nums;
+		opacity: 0.5;
+	}
+
+	.ch-body {
+		margin: 0;
+		font-size: 0.95rem;
+		line-height: 1.45;
+		white-space: pre-wrap;
+		word-break: break-word;
+	}
+
+	.ch-composer {
+		display: flex;
+		gap: 0.5rem;
+		padding: 0.75rem;
+		border-top: 1px solid var(--edge);
+		background: rgba(28, 28, 26, 0.02);
+	}
+
+	.ch-input {
+		flex: 1;
+		min-width: 0;
+		border: 1px solid var(--edge);
+		border-radius: var(--wf-radius, 6px);
+		padding: 0.65rem 0.85rem;
+		font: inherit;
+		font-size: 0.95rem;
+		background: #fff;
+		color: var(--ink);
+		outline: none;
+		transition:
+			border-color 0.15s ease,
+			box-shadow 0.15s ease;
+	}
+
+	.ch-input:focus {
+		border-color: var(--accent);
+		box-shadow: 0 0 0 3px var(--wf-accent-soft, rgba(61, 90, 128, 0.12));
+	}
+
+	.ch-sr {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		padding: 0;
+		margin: -1px;
+		overflow: hidden;
+		clip: rect(0, 0, 0, 0);
+		border: 0;
+	}
+</style>
diff --git a/tests/e2e-ui/ui/src/routes/login/+page.server.ts b/tests/e2e-ui/ui/src/routes/login/+page.server.ts
new file mode 100644
index 00000000..f42eb1bf
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/login/+page.server.ts
@@ -0,0 +1,56 @@
+import { fail, redirect } from '@sveltejs/kit';
+import type { Actions, PageServerLoad } from './$types';
+import { loginWithPassword, ZitadelAuthError } from '$lib/server/zitadel-session';
+import { startOidcSignIn } from '$lib/server/oidc-start';
+
+export const load: PageServerLoad = async (event) => {
+	const session = await event.locals.auth();
+	if (session?.user) {
+		redirect(303, '/todos');
+	}
+
+	const authRequest = event.url.searchParams.get('authRequest')?.trim() ?? '';
+	// No pending OIDC auth request → start Auth.js authorize (redirects; lands back with authRequest).
+	if (!authRequest) {
+		await startOidcSignIn(event, 'sign-in');
+	}
+
+	return {
+		authRequest,
+		demoHint: 'Demo: alice / bob / admin · Password1!'
+	};
+};
+
+export const actions: Actions = {
+	default: async (event) => {
+		const form = await event.request.formData();
+		const authRequest = String(form.get('authRequest') ?? '').trim();
+		const loginName = String(form.get('loginName') ?? '').trim();
+		const password = String(form.get('password') ?? '');
+
+		if (!authRequest) {
+			return fail(400, {
+				error: 'Sign-in session expired. Click Sign in again.',
+				loginName
+			});
+		}
+		if (!loginName || !password) {
+			return fail(400, { error: 'Username and password are required.', loginName });
+		}
+
+		try {
+			const callbackUrl = await loginWithPassword(authRequest, loginName, password);
+			redirect(303, callbackUrl);
+		} catch (e) {
+			// SvelteKit redirect throws a Response-like object
+			if (e && typeof e === 'object' && 'status' in e && 'location' in e) {
+				throw e;
+			}
+			const err = e instanceof ZitadelAuthError ? e : null;
+			return fail(err?.status && err.status < 500 ? err.status : 400, {
+				error: err?.message ?? 'Sign-in failed. Check credentials and try again.',
+				loginName
+			});
+		}
+	}
+};
diff --git a/tests/e2e-ui/ui/src/routes/login/+page.svelte b/tests/e2e-ui/ui/src/routes/login/+page.svelte
new file mode 100644
index 00000000..6a93b767
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/login/+page.svelte
@@ -0,0 +1,207 @@
+<script lang="ts">
+	import type { ActionData, PageData } from './$types';
+
+	let { data, form }: { data: PageData; form: ActionData } = $props();
+
+	const error = $derived(form?.error);
+	const loginName = $derived(form?.loginName ?? '');
+	const signupHref = $derived(
+		`/signup?authRequest=${encodeURIComponent(data.authRequest ?? '')}`
+	);
+</script>
+
+<svelte:head>
+	<title>Sign in · e2e-ui</title>
+</svelte:head>
+
+<main class="auth-page">
+	<div class="auth-card">
+		<div class="auth-brand">
+			<span class="auth-mark" aria-hidden="true">df</span>
+			<span class="auth-product">e2e-ui</span>
+		</div>
+		<h1 class="auth-title">Sign in</h1>
+		<p class="auth-lead">
+			Your credentials stay on these pages. Zitadel only issues the OIDC tokens after Auth.js
+			completes the code flow.
+		</p>
+
+		{#if error}
+			<p class="auth-error" role="alert">{error}</p>
+		{/if}
+
+		<form method="POST" class="auth-form">
+			<input type="hidden" name="authRequest" value={data.authRequest} />
+
+			<label class="auth-label" for="loginName">Username</label>
+			<input
+				id="loginName"
+				name="loginName"
+				type="text"
+				autocomplete="username"
+				required
+				class="auth-input"
+				value={loginName}
+				placeholder="alice"
+			/>
+
+			<label class="auth-label" for="password">Password</label>
+			<input
+				id="password"
+				name="password"
+				type="password"
+				autocomplete="current-password"
+				required
+				class="auth-input"
+				placeholder="••••••••"
+			/>
+
+			<button type="submit" class="auth-submit">Continue</button>
+		</form>
+
+		<p class="auth-meta">
+			<a href={signupHref}>Create an account</a>
+			<span class="auth-dot" aria-hidden="true">·</span>
+			<a href="/">Back home</a>
+		</p>
+		{#if data.demoHint}
+			<p class="auth-demo">{data.demoHint}</p>
+		{/if}
+	</div>
+</main>
+
+<style>
+	.auth-page {
+		min-height: calc(100vh - 4rem);
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		padding: 2rem var(--wf-gutter, 1.5rem);
+		background: var(--wf-bg, #f6f5f2);
+	}
+	.auth-card {
+		width: min(100%, 24rem);
+		background: var(--wf-bg-elevated, #fff);
+		border: 1px solid var(--wf-line, #e2e0d9);
+		border-radius: 10px;
+		padding: 2rem 1.75rem 1.75rem;
+		box-shadow: 0 12px 32px rgba(28, 28, 26, 0.06);
+	}
+	.auth-brand {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		margin-bottom: 1.25rem;
+	}
+	.auth-mark {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		width: 1.75rem;
+		height: 1.75rem;
+		border-radius: 5px;
+		background: var(--wf-ink, #1c1c1a);
+		color: #f6f5f2;
+		font-family: var(--wf-mono, ui-monospace, monospace);
+		font-size: 0.7rem;
+		font-weight: 500;
+	}
+	.auth-product {
+		font-weight: 600;
+		font-size: 0.95rem;
+		color: var(--wf-ink, #1c1c1a);
+	}
+	.auth-title {
+		margin: 0 0 0.35rem;
+		font-family: var(--wf-serif, Georgia, serif);
+		font-size: 1.65rem;
+		font-weight: 500;
+		letter-spacing: -0.02em;
+		color: var(--wf-ink, #1c1c1a);
+	}
+	.auth-lead {
+		margin: 0 0 1.25rem;
+		font-size: 0.875rem;
+		line-height: 1.45;
+		color: var(--wf-ink-soft, #5c5c56);
+	}
+	.auth-error {
+		margin: 0 0 1rem;
+		padding: 0.65rem 0.75rem;
+		border-radius: 6px;
+		background: rgba(179, 58, 58, 0.08);
+		border: 1px solid rgba(179, 58, 58, 0.25);
+		color: var(--wf-danger, #b33a3a);
+		font-size: 0.875rem;
+	}
+	.auth-form {
+		display: flex;
+		flex-direction: column;
+		gap: 0.35rem;
+	}
+	.auth-label {
+		font-size: 0.8rem;
+		font-weight: 500;
+		color: var(--wf-ink-soft, #5c5c56);
+		margin-top: 0.5rem;
+	}
+	.auth-input {
+		appearance: none;
+		border: 1px solid var(--wf-line-strong, #cdcabe);
+		border-radius: 6px;
+		padding: 0.6rem 0.75rem;
+		font: inherit;
+		font-size: 0.95rem;
+		background: #fff;
+		color: var(--wf-ink, #1c1c1a);
+	}
+	.auth-input:focus {
+		outline: 2px solid var(--wf-accent, #3d5a80);
+		outline-offset: 1px;
+	}
+	.auth-submit {
+		margin-top: 1.15rem;
+		appearance: none;
+		border: none;
+		border-radius: 6px;
+		padding: 0.7rem 1rem;
+		font: inherit;
+		font-weight: 600;
+		font-size: 0.95rem;
+		background: var(--wf-accent, #3d5a80);
+		color: #fff;
+		cursor: pointer;
+	}
+	.auth-submit:hover {
+		filter: brightness(1.06);
+	}
+	.auth-submit:active {
+		transform: translateY(0.5px);
+	}
+	.auth-meta {
+		margin: 1.25rem 0 0;
+		font-size: 0.85rem;
+		color: var(--wf-ink-soft, #5c5c56);
+		display: flex;
+		flex-wrap: wrap;
+		gap: 0.35rem;
+		align-items: center;
+	}
+	.auth-meta a {
+		color: var(--wf-accent, #3d5a80);
+		text-decoration: none;
+		font-weight: 500;
+	}
+	.auth-meta a:hover {
+		text-decoration: underline;
+	}
+	.auth-dot {
+		opacity: 0.5;
+	}
+	.auth-demo {
+		margin: 1rem 0 0;
+		font-size: 0.75rem;
+		font-family: var(--wf-mono, ui-monospace, monospace);
+		color: var(--wf-ink-muted, #8a8a82);
+	}
+</style>
diff --git a/tests/e2e-ui/ui/src/routes/session/+page.server.ts b/tests/e2e-ui/ui/src/routes/session/+page.server.ts
new file mode 100644
index 00000000..0510e6d1
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/session/+page.server.ts
@@ -0,0 +1,8 @@
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async ({ locals }) => {
+  const session = await locals.auth();
+  return {
+    session
+  };
+};
diff --git a/tests/e2e-ui/ui/src/routes/session/+page.svelte b/tests/e2e-ui/ui/src/routes/session/+page.svelte
new file mode 100644
index 00000000..5fb8c2c4
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/session/+page.svelte
@@ -0,0 +1,452 @@
+<script lang="ts">
+	import { browser } from '$app/environment';
+	import { BadgeCheck, LockKeyhole, LogOut, UserRound } from '@lucide/svelte';
+	import { Button, SimplePage } from '$lib/components/shared/ui';
+	import { engineRoleFromGroups, isAdminEngineRole } from '$lib/roles';
+	import TokenInspector from './TokenInspector.svelte';
+	import type { PageData } from './$types';
+
+	interface SessionUser {
+		id?: string | null;
+		name?: string | null;
+		email?: string | null;
+		image?: string | null;
+		username?: string | null;
+		emailVerified?: boolean | null;
+		groups?: string[] | null;
+	}
+
+	interface SessionLike {
+		user?: SessionUser | null;
+		accessToken?: string | null;
+		idToken?: string | null;
+		expires?: string | null;
+		expiresAt?: number | null;
+		hasAccessToken?: boolean | null;
+		hasRefreshToken?: boolean | null;
+		hasIdToken?: boolean | null;
+		error?: string | null;
+	}
+
+	let { data }: { data: PageData } = $props();
+
+	let now = $state(currentUnixSeconds());
+	const session = $derived(data.session as SessionLike | null | undefined);
+	const user = $derived(session?.user);
+	const expiresAt = $derived(resolveExpiresAt(session));
+	const expiresAtLabel = $derived(formatExpiresAt(expiresAt, session?.expires));
+	const expiresIn = $derived(formatCountdown(expiresAt, now));
+	const isExpired = $derived(expiresAt !== undefined && expiresAt <= now);
+	const engineRole = $derived(
+		(data as { engineRole?: string | null }).engineRole ??
+			engineRoleFromGroups(user?.groups ?? undefined)
+	);
+	const isAdmin = $derived(isAdminEngineRole(engineRole));
+
+	$effect(() => {
+		if (!browser) return;
+
+		const timer = window.setInterval(() => {
+			now = currentUnixSeconds();
+		}, 1_000);
+
+		return () => window.clearInterval(timer);
+	});
+
+	function currentUnixSeconds() {
+		return Math.floor(Date.now() / 1_000);
+	}
+
+	function displayName(value: SessionUser | null | undefined) {
+		return value?.name || value?.email || value?.username || 'User';
+	}
+
+	function initials(value: SessionUser | null | undefined) {
+		const nameInitials = value?.name
+			?.split(/\s+/)
+			.filter(Boolean)
+			.map((part) => part[0])
+			.join('')
+			.slice(0, 2);
+
+		if (nameInitials) return nameInitials.toUpperCase();
+
+		const fallback = value?.email || value?.username || 'U';
+		return fallback[0]?.toUpperCase() ?? 'U';
+	}
+
+	function resolveExpiresAt(value: SessionLike | null | undefined) {
+		if (typeof value?.expiresAt === 'number' && Number.isFinite(value.expiresAt)) {
+			return value.expiresAt;
+		}
+
+		const expires = value?.expires ? Date.parse(value.expires) : Number.NaN;
+		if (Number.isFinite(expires)) return Math.floor(expires / 1_000);
+
+		return undefined;
+	}
+
+	function formatExpiresAt(expiresAt: number | undefined, expires: string | null | undefined) {
+		const date = expiresAt ? new Date(expiresAt * 1_000) : expires ? new Date(expires) : undefined;
+		if (!date || Number.isNaN(date.getTime())) return 'Unavailable';
+
+		return date.toLocaleString(undefined, {
+			year: 'numeric',
+			month: 'short',
+			day: 'numeric',
+			hour: 'numeric',
+			minute: '2-digit'
+		});
+	}
+
+	function formatCountdown(expiresAt: number | undefined, current: number) {
+		if (!expiresAt) return 'Unavailable';
+		if (expiresAt <= current) return 'Expired';
+
+		const remaining = expiresAt - current;
+		const days = Math.floor(remaining / 86_400);
+		const hours = Math.floor((remaining % 86_400) / 3_600);
+		const minutes = Math.floor((remaining % 3_600) / 60);
+		const seconds = remaining % 60;
+
+		if (days > 0) return `${days}d ${hours.toString().padStart(2, '0')}h`;
+		if (hours > 0) return `${hours}h ${minutes.toString().padStart(2, '0')}m`;
+		if (minutes > 0) return `${minutes}m ${seconds.toString().padStart(2, '0')}s`;
+		return `${seconds}s`;
+	}
+</script>
+
+<SimplePage title="Session" maxWidth="lg">
+	{#if user}
+		<div class="session-view">
+			<section class="session-profile" aria-label="Signed-in account">
+				<div class="session-avatar" aria-hidden="true">{initials(user)}</div>
+				<div class="session-identity">
+					<h1>Session</h1>
+					<h2>{displayName(user)}</h2>
+					{#if user.email}
+						<p class="muted">{user.email}</p>
+					{/if}
+					{#if user.groups?.length}
+						<div class="pill-row" aria-label="Groups">
+							{#each user.groups as group (group)}
+								<span class="group-pill">{group}</span>
+							{/each}
+						</div>
+					{/if}
+				</div>
+			</section>
+
+			{#if session?.error}
+				<p class="session-alert">Token refresh reported: {session.error}</p>
+			{/if}
+
+			<section class="session-grid" aria-label="Session details">
+				<div class="session-row">
+					<span>User ID</span>
+					<strong class="mono">{user.id || 'Unavailable'}</strong>
+				</div>
+				{#if user.username}
+					<div class="session-row">
+						<span>Username</span>
+						<strong>{user.username}</strong>
+					</div>
+				{/if}
+				{#if typeof user.emailVerified === 'boolean'}
+					<div class="session-row">
+						<span>Email Verified</span>
+						<strong class:verified={user.emailVerified}>
+							{#if user.emailVerified}
+								<BadgeCheck size={17} strokeWidth={2.2} aria-hidden="true" />
+							{/if}
+							{user.emailVerified ? 'Verified' : 'Unverified'}
+						</strong>
+					</div>
+				{/if}
+				<div class="session-row">
+					<span>Expires At</span>
+					<strong>{expiresAtLabel}</strong>
+				</div>
+				<div class="session-row">
+					<span>Expires In</span>
+					<strong class="session-countdown" class:expired={isExpired}>{expiresIn}</strong>
+				</div>
+			</section>
+
+			<section class="token-inspector-list" aria-label="Session tokens">
+				<TokenInspector
+					label="Access Token"
+					token={session?.accessToken}
+					present={Boolean(session?.hasAccessToken)}
+					statusLabel="Available to app"
+				/>
+				<TokenInspector
+					label="ID Token"
+					token={session?.idToken}
+					present={Boolean(session?.hasIdToken)}
+					statusLabel="Available to app"
+				/>
+				<TokenInspector
+					label="Refresh Token"
+					present={Boolean(session?.hasRefreshToken)}
+					protectedMessage="Stored in an HttpOnly cookie and unavailable to page scripts."
+				/>
+			</section>
+
+			<div class="button-row center">
+				{#if isAdmin}
+					<Button variant="secondary" href="/admin">
+						<UserRound size={18} strokeWidth={2.2} aria-hidden="true" />
+						Admin Panel
+					</Button>
+				{/if}
+				<Button variant="primary" href="/signout">
+					<LogOut size={18} strokeWidth={2.2} aria-hidden="true" />
+					Sign Out
+				</Button>
+			</div>
+		</div>
+	{:else}
+		<div class="empty-state">
+			<div class="empty-icon" aria-hidden="true">
+				<LockKeyhole size={42} strokeWidth={1.7} />
+			</div>
+			<h1 class="empty-title">Not signed in</h1>
+			<p class="empty-text">Sign in to view your session information and account details.</p>
+			<Button variant="primary" href="/signin?callbackUrl=/session">Sign In</Button>
+		</div>
+	{/if}
+</SimplePage>
+
+<style>
+	.session-view {
+		width: 100%;
+		text-align: left;
+	}
+
+	.session-profile {
+		display: grid;
+		grid-template-columns: auto minmax(0, 1fr);
+		align-items: center;
+		gap: 1.15rem;
+		padding: 1.35rem 1.4rem;
+		background: var(--wf-bg-elevated, #fff);
+		border: 1px solid var(--wf-line, #e2e0d9);
+		border-radius: var(--df-radius-lg, 10px);
+	}
+
+	.session-avatar {
+		width: 68px;
+		height: 68px;
+		border-radius: 12px;
+		display: grid;
+		place-items: center;
+		background: var(--wf-ink, #1c1c1a);
+		color: var(--wf-bg, #f6f5f2);
+		font-family: var(--wf-sans, system-ui, sans-serif);
+		font-size: 1.2rem;
+		font-weight: 600;
+		letter-spacing: 0.02em;
+	}
+
+	.session-identity {
+		min-width: 0;
+	}
+
+	.session-identity h1 {
+		margin: 0 0 0.2rem;
+		font-family: var(--wf-serif, Georgia, serif);
+		font-size: clamp(1.5rem, 3vw, 1.85rem);
+		font-weight: 500;
+		letter-spacing: -0.02em;
+		line-height: 1.1;
+		color: var(--wf-ink, #1c1c1a);
+	}
+
+	.session-identity h2 {
+		margin: 0;
+		color: var(--wf-ink, #1c1c1a);
+		font-family: var(--wf-sans, system-ui, sans-serif);
+		font-size: 1.15rem;
+		font-weight: 600;
+		line-height: 1.25;
+		overflow-wrap: anywhere;
+	}
+
+	.muted {
+		margin: 0.3rem 0 0;
+		color: var(--wf-ink-muted, #8a8a82);
+		font-size: 0.95rem;
+		overflow-wrap: anywhere;
+	}
+
+	.pill-row {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 0.4rem;
+		margin-top: 0.75rem;
+	}
+
+	.group-pill {
+		display: inline-flex;
+		align-items: center;
+		max-width: 100%;
+		min-height: 26px;
+		padding: 0.2rem 0.55rem;
+		border-radius: 999px;
+		background: var(--wf-accent-soft, rgba(61, 90, 128, 0.08));
+		border: 1px solid var(--wf-line, #e2e0d9);
+		color: var(--wf-accent, #3d5a80);
+		font-size: 0.75rem;
+		font-weight: 600;
+		overflow-wrap: anywhere;
+	}
+
+	.session-alert {
+		margin: 1rem 0 0;
+		padding: 0.75rem 0.95rem;
+		border-radius: var(--wf-radius, 6px);
+		border: 1px solid var(--wf-line, #e2e0d9);
+		background: var(--wf-accent-soft, rgba(61, 90, 128, 0.08));
+		color: var(--wf-ink, #1c1c1a);
+		font-size: 0.92rem;
+		font-weight: 500;
+	}
+
+	.session-grid {
+		display: grid;
+		grid-template-columns: repeat(2, minmax(0, 1fr));
+		gap: 0.65rem;
+		margin-top: 1rem;
+	}
+
+	.session-row {
+		display: grid;
+		grid-template-columns: minmax(7.5rem, 0.4fr) minmax(0, 1fr);
+		align-items: center;
+		gap: 0.85rem;
+		min-height: 56px;
+		padding: 0.75rem 0.95rem;
+		background: var(--wf-bg-elevated, #fff);
+		border: 1px solid var(--wf-line, #e2e0d9);
+		border-radius: var(--wf-radius, 6px);
+	}
+
+	.session-row span {
+		color: var(--wf-ink-muted, #8a8a82);
+		font-size: 0.72rem;
+		font-weight: 600;
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+	}
+
+	.session-row strong {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.35rem;
+		min-width: 0;
+		color: var(--wf-ink, #1c1c1a);
+		font-size: 0.95rem;
+		font-weight: 600;
+		line-height: 1.35;
+		overflow-wrap: anywhere;
+	}
+
+	.session-row .mono {
+		font-family: var(--wf-mono, ui-monospace, monospace);
+		font-size: 0.85rem;
+		font-weight: 500;
+	}
+
+	.session-row .verified,
+	.session-countdown {
+		color: var(--wf-success, #2f6f4e);
+	}
+
+	.session-countdown.expired {
+		color: var(--wf-danger, #b33a3a);
+	}
+
+	.token-inspector-list {
+		display: flex;
+		flex-direction: column;
+		gap: 0.75rem;
+		margin-top: 1rem;
+	}
+
+	.button-row {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 0.65rem;
+		margin-top: 1.25rem;
+	}
+
+	.button-row.center {
+		justify-content: center;
+	}
+
+	.empty-state {
+		text-align: center;
+		padding: 3.5rem 1.5rem;
+	}
+
+	.empty-icon {
+		width: 72px;
+		height: 72px;
+		margin: 0 auto 1.25rem;
+		background: var(--wf-bg-elevated, #fff);
+		border: 1px solid var(--wf-line, #e2e0d9);
+		border-radius: 14px;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		color: var(--wf-ink, #1c1c1a);
+	}
+
+	.empty-title {
+		margin: 0 0 0.45rem;
+		color: var(--wf-ink, #1c1c1a);
+		font-family: var(--wf-serif, Georgia, serif);
+		font-size: clamp(1.5rem, 4vw, 2rem);
+		font-weight: 500;
+		letter-spacing: -0.02em;
+	}
+
+	.empty-text {
+		max-width: 320px;
+		margin: 0 auto 1.75rem;
+		color: var(--wf-ink-soft, #5c5c56);
+		font-size: 0.98rem;
+	}
+
+	@media (--tablet) {
+		.session-grid {
+			grid-template-columns: 1fr;
+		}
+	}
+
+	@media (--mobile) {
+		.session-profile {
+			grid-template-columns: 1fr;
+			justify-items: center;
+			text-align: center;
+		}
+
+		.session-identity h2 {
+			font-size: 1.05rem;
+		}
+
+		.pill-row {
+			justify-content: center;
+		}
+
+		.session-row {
+			grid-template-columns: 1fr;
+			gap: 0.3rem;
+		}
+
+		.button-row {
+			align-items: stretch;
+		}
+	}
+</style>
diff --git a/tests/e2e-ui/ui/src/routes/session/TokenInspector.svelte b/tests/e2e-ui/ui/src/routes/session/TokenInspector.svelte
new file mode 100644
index 00000000..f27a5dbb
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/session/TokenInspector.svelte
@@ -0,0 +1,422 @@
+<script lang="ts">
+	import { Code2, Eye, EyeOff } from '@lucide/svelte';
+
+	interface Props {
+		label: string;
+		token?: string | null;
+		present?: boolean;
+		statusLabel?: string;
+		hiddenMessage?: string;
+		protectedMessage?: string;
+	}
+
+	interface DecodedJwt {
+		header: string;
+		payload: string;
+		signatureSummary: string;
+	}
+
+	type DecodeResult =
+		| { ok: true; decoded: DecodedJwt }
+		| { ok: false; message: string };
+	type JsonPartResult =
+		| { ok: true; json: string }
+		| { ok: false; message: string };
+
+	let {
+		label,
+		token = '',
+		present = false,
+		statusLabel,
+		hiddenMessage = 'Available to the app. Hidden in the UI until revealed.',
+		protectedMessage = ''
+	}: Props = $props();
+
+	let revealed = $state(false);
+	let decodedOpen = $state(false);
+
+	const tokenValue = $derived(typeof token === 'string' ? token.trim() : '');
+	const hasToken = $derived(tokenValue.length > 0);
+	const status = $derived(statusLabel ?? (hasToken ? 'Present' : present ? 'Protected' : 'Missing'));
+	const statusClass = $derived(hasToken || present ? 'present' : 'missing');
+	const revealLabel = $derived(revealed ? 'Hide token' : 'Show token');
+	const decodeLabel = $derived(decodedOpen ? 'Hide decoded' : 'Decode');
+	const decoded = $derived(
+		hasToken && revealed && decodedOpen ? decodeJwt(tokenValue) : null
+	);
+
+	function toggleRevealed() {
+		revealed = !revealed;
+		if (!revealed) decodedOpen = false;
+	}
+
+	function decodeJwt(value: string): DecodeResult {
+		const parts = value.split('.');
+		if (parts.length !== 3) {
+			return {
+				ok: false,
+				message: 'Expected a JWT with header, payload, and signature.'
+			};
+		}
+
+		const header = decodeJwtJsonPart(parts[0], 'header');
+		if (!header.ok) return header;
+
+		const payload = decodeJwtJsonPart(parts[1], 'payload');
+		if (!payload.ok) return payload;
+
+		return {
+			ok: true,
+			decoded: {
+				header: header.json,
+				payload: payload.json,
+				signatureSummary: parts[2]
+					? `Signature: ${parts[2].length} base64url characters`
+					: 'Signature: empty'
+			}
+		};
+	}
+
+	function decodeJwtJsonPart(part: string, name: string): JsonPartResult {
+		const decoded = decodeBase64Url(part);
+		if (!decoded.ok) {
+			return {
+				ok: false,
+				message: `Could not decode JWT ${name}: ${decoded.message}`
+			};
+		}
+
+		try {
+			const json = JSON.parse(new TextDecoder().decode(decoded.bytes));
+			return { ok: true, json: JSON.stringify(json, null, 2) };
+		} catch {
+			return {
+				ok: false,
+				message: `JWT ${name} is not valid JSON.`
+			};
+		}
+	}
+
+	function decodeBase64Url(input: string):
+		| { ok: true; bytes: Uint8Array }
+		| { ok: false; message: string } {
+		const unpadded = input.trimEnd().replace(/=+$/, '');
+
+		if (/=/.test(unpadded)) {
+			return { ok: false, message: 'padding must be at the end' };
+		}
+
+		if (!/^[A-Za-z0-9_-]*$/.test(unpadded)) {
+			return { ok: false, message: 'invalid base64url character' };
+		}
+
+		if (unpadded.length % 4 === 1) {
+			return { ok: false, message: 'invalid base64url length' };
+		}
+
+		const normalized = unpadded.replace(/-/g, '+').replace(/_/g, '/');
+		const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, '=');
+
+		try {
+			const binary = globalThis.atob(padded);
+			return {
+				ok: true,
+				bytes: Uint8Array.from(binary, (char) => char.charCodeAt(0))
+			};
+		} catch {
+			return { ok: false, message: 'invalid base64url data' };
+		}
+	}
+</script>
+
+<article class="token-card">
+	<div class="token-card-header">
+		<div class="token-title-block">
+			<span class="token-label">{label}</span>
+			<strong class="token-status {statusClass}">{status}</strong>
+		</div>
+
+		<div class="token-actions">
+			{#if hasToken}
+				<button
+					class="token-icon-button"
+					type="button"
+					aria-label={revealLabel}
+					title={revealLabel}
+					onclick={toggleRevealed}
+				>
+					{#if revealed}
+						<EyeOff size={18} strokeWidth={2.2} aria-hidden="true" />
+					{:else}
+						<Eye size={18} strokeWidth={2.2} aria-hidden="true" />
+					{/if}
+				</button>
+
+				{#if revealed}
+					<button
+						class="token-decode-button"
+						type="button"
+						onclick={() => {
+							decodedOpen = !decodedOpen;
+						}}
+					>
+						<Code2 size={17} strokeWidth={2.2} aria-hidden="true" />
+						<span>{decodeLabel}</span>
+					</button>
+				{/if}
+			{/if}
+		</div>
+	</div>
+
+	{#if hasToken && revealed}
+		<div class="token-reveal">
+			<pre class="token-code"><code>{tokenValue}</code></pre>
+		</div>
+
+		{#if decoded}
+			{#if decoded.ok}
+				<div class="token-decoded">
+					<div class="token-decoded-grid">
+						<div>
+							<span class="token-json-label">Header</span>
+							<pre class="token-json"><code>{decoded.decoded.header}</code></pre>
+						</div>
+						<div>
+							<span class="token-json-label">Payload</span>
+							<pre class="token-json"><code>{decoded.decoded.payload}</code></pre>
+						</div>
+					</div>
+					<p class="token-meta">{decoded.decoded.signatureSummary}</p>
+				</div>
+			{:else}
+				<p class="token-decode-error">{decoded.message}</p>
+			{/if}
+		{/if}
+	{:else if present && protectedMessage}
+		<p class="token-unavailable">{protectedMessage}</p>
+	{:else if !hasToken}
+		<p class="token-unavailable">Token is not present in the current session.</p>
+	{:else}
+		<p class="token-unavailable">{hiddenMessage}</p>
+	{/if}
+</article>
+
+<style>
+	.token-card {
+		background: var(--wf-bg-elevated, #fff);
+		border: 1px solid var(--wf-line, #e2e0d9);
+		border-radius: var(--df-radius-lg, 10px);
+		overflow: hidden;
+	}
+
+	.token-card-header {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: 1rem;
+		min-height: 60px;
+		padding: 0.85rem 1rem;
+	}
+
+	.token-title-block {
+		display: flex;
+		align-items: center;
+		flex-wrap: wrap;
+		gap: 0.55rem;
+		min-width: 0;
+	}
+
+	.token-label {
+		color: var(--wf-ink, #1c1c1a);
+		font-size: 0.95rem;
+		font-weight: 600;
+	}
+
+	.token-status {
+		display: inline-flex;
+		align-items: center;
+		min-height: 24px;
+		padding: 0.15rem 0.5rem;
+		border-radius: 999px;
+		font-size: 0.7rem;
+		font-weight: 600;
+		text-transform: uppercase;
+		letter-spacing: 0.04em;
+	}
+
+	.token-status.present {
+		background: rgba(47, 111, 78, 0.1);
+		border: 1px solid rgba(47, 111, 78, 0.22);
+		color: var(--wf-success, #2f6f4e);
+	}
+
+	.token-status.missing {
+		background: rgba(179, 58, 58, 0.08);
+		border: 1px solid rgba(179, 58, 58, 0.2);
+		color: var(--wf-danger, #b33a3a);
+	}
+
+	.token-actions {
+		display: flex;
+		align-items: center;
+		justify-content: flex-end;
+		flex-wrap: wrap;
+		gap: 0.4rem;
+	}
+
+	.token-icon-button,
+	.token-decode-button {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		border: 1px solid var(--wf-line, #e2e0d9);
+		background: transparent;
+		color: var(--wf-ink, #1c1c1a);
+		cursor: pointer;
+		transition:
+			background 0.15s ease,
+			border-color 0.15s ease,
+			color 0.15s ease;
+	}
+
+	.token-icon-button {
+		width: 34px;
+		height: 34px;
+		border-radius: var(--wf-radius, 6px);
+	}
+
+	.token-decode-button {
+		min-height: 34px;
+		gap: 0.4rem;
+		padding: 0 0.7rem;
+		border-radius: var(--wf-radius, 6px);
+		font-weight: 600;
+		font-size: 0.85rem;
+	}
+
+	.token-icon-button:hover,
+	.token-decode-button:hover {
+		background: var(--wf-ink, #1c1c1a);
+		border-color: var(--wf-ink, #1c1c1a);
+		color: var(--wf-bg, #f6f5f2);
+	}
+
+	.token-reveal,
+	.token-decoded {
+		border-top: 1px solid var(--wf-line, #e2e0d9);
+	}
+
+	.token-reveal {
+		padding: 0.85rem 1rem;
+		background: var(--wf-code-bg, #1c1c1a);
+	}
+
+	.token-code,
+	.token-json {
+		margin: 0;
+		overflow-x: auto;
+		white-space: pre-wrap;
+		font-family: var(--wf-mono, ui-monospace, monospace);
+		font-size: 0.82rem;
+		line-height: 1.65;
+		overflow-wrap: anywhere;
+	}
+
+	.token-code :global(code),
+	.token-json :global(code) {
+		display: block;
+		padding: 0 !important;
+		background: transparent !important;
+		color: inherit !important;
+		border-radius: 0 !important;
+		font: inherit;
+	}
+
+	.token-code {
+		background: transparent !important;
+		border-radius: 0 !important;
+		color: var(--wf-code-fg, #e8e6e0);
+		overflow: visible;
+		word-break: break-all;
+	}
+
+	.token-code::after,
+	.token-json::after {
+		display: none !important;
+	}
+
+	.token-decoded {
+		padding: 0.95rem 1rem;
+		background: rgba(28, 28, 26, 0.02);
+	}
+
+	.token-decoded-grid {
+		display: grid;
+		grid-template-columns: repeat(2, minmax(0, 1fr));
+		gap: 0.75rem;
+	}
+
+	.token-json-label {
+		display: block;
+		margin-bottom: 0.4rem;
+		color: var(--wf-ink-muted, #8a8a82);
+		font-size: 0.7rem;
+		font-weight: 600;
+		text-transform: uppercase;
+		letter-spacing: 0.06em;
+	}
+
+	.token-json {
+		padding: 0.75rem;
+		max-height: none;
+		overflow-x: auto;
+		overflow-y: visible;
+		border: 1px solid var(--wf-line, #e2e0d9);
+		border-radius: var(--wf-radius, 6px);
+		background: var(--wf-code-bg, #1c1c1a);
+		color: var(--wf-code-fg, #e8e6e0);
+	}
+
+	.token-meta,
+	.token-unavailable,
+	.token-decode-error {
+		margin: 0;
+		color: var(--wf-ink-soft, #5c5c56);
+		font-size: 0.88rem;
+		line-height: 1.5;
+	}
+
+	.token-meta {
+		margin-top: 0.7rem;
+		font-family: var(--wf-mono, ui-monospace, monospace);
+	}
+
+	.token-unavailable {
+		padding: 0 1rem 0.95rem;
+	}
+
+	.token-decode-error {
+		padding: 0.85rem 1rem 0.95rem;
+		border-top: 1px solid var(--wf-line, #e2e0d9);
+		color: var(--wf-danger, #b33a3a);
+		font-weight: 600;
+	}
+
+	@media (--tablet) {
+		.token-decoded-grid {
+			grid-template-columns: 1fr;
+		}
+	}
+
+	@media (--mobile) {
+		.token-card-header {
+			align-items: flex-start;
+			flex-direction: column;
+		}
+
+		.token-actions {
+			width: 100%;
+			justify-content: flex-start;
+		}
+	}
+</style>
diff --git a/tests/e2e-ui/ui/src/routes/signin/+server.ts b/tests/e2e-ui/ui/src/routes/signin/+server.ts
new file mode 100644
index 00000000..a84594e8
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/signin/+server.ts
@@ -0,0 +1,8 @@
+/**
+ * Legacy entry: start OIDC authorize. Prefer /login (custom Login V2 pages).
+ * Kept so old links and docs still work.
+ */
+import type { RequestHandler } from './$types';
+import { startOidcSignIn } from '$lib/server/oidc-start';
+
+export const GET: RequestHandler = async (event) => startOidcSignIn(event, 'sign-in');
diff --git a/tests/e2e-ui/ui/src/routes/signout/+server.ts b/tests/e2e-ui/ui/src/routes/signout/+server.ts
new file mode 100644
index 00000000..dea12134
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/signout/+server.ts
@@ -0,0 +1,60 @@
+import { redirect } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+import { env } from '$env/dynamic/private';
+
+function envFirst(names: string[]) {
+	for (const name of names) {
+		const value = env[name]?.trim();
+		if (value) return value;
+	}
+
+	return undefined;
+}
+
+function oidcIssuer() {
+	return envFirst(['OIDC_ISSUER', 'ZITADEL_ISSUER'])?.replace(/\/+$/, '');
+}
+
+async function endSessionEndpoint() {
+	const override = envFirst(['OIDC_END_SESSION_ENDPOINT']);
+	if (override) return override;
+
+	const issuer = oidcIssuer();
+	if (!issuer) return undefined;
+
+	try {
+		const response = await fetch(`${issuer}/.well-known/openid-configuration`);
+		if (!response.ok) return undefined;
+
+		const metadata = (await response.json()) as { end_session_endpoint?: string };
+		return metadata.end_session_endpoint;
+	} catch {
+		return undefined;
+	}
+}
+
+export const GET: RequestHandler = async (event) => {
+	const session = await event.locals.auth();
+	const idToken = session?.idToken;
+
+	event.cookies.delete('authjs.session-token', { path: '/' });
+	event.cookies.delete('authjs.callback-url', { path: '/' });
+	event.cookies.delete('authjs.csrf-token', { path: '/' });
+	event.cookies.delete('__Secure-authjs.session-token', { path: '/' });
+	event.cookies.delete('__Secure-authjs.callback-url', { path: '/' });
+	event.cookies.delete('__Secure-authjs.csrf-token', { path: '/' });
+
+	const logoutEndpoint = await endSessionEndpoint();
+	if (!logoutEndpoint) {
+		redirect(303, '/');
+	}
+
+	const endSessionUrl = new URL(logoutEndpoint);
+	if (idToken) endSessionUrl.searchParams.set('id_token_hint', idToken);
+	// Zitadel exact-matches post_logout_redirect_uri against app allowlist
+	// (bootstrap registers origin + trailing slash, e.g. http://127.0.0.1:5180/).
+	// event.url.origin has no path/slash — bare origin is rejected as invalid.
+	endSessionUrl.searchParams.set('post_logout_redirect_uri', `${event.url.origin}/`);
+
+	redirect(303, endSessionUrl.toString());
+};
diff --git a/tests/e2e-ui/ui/src/routes/signup/+page.server.ts b/tests/e2e-ui/ui/src/routes/signup/+page.server.ts
new file mode 100644
index 00000000..85362e0e
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/signup/+page.server.ts
@@ -0,0 +1,78 @@
+import { fail, redirect } from '@sveltejs/kit';
+import type { Actions, PageServerLoad } from './$types';
+import {
+	registerAndLogin,
+	registerHuman,
+	ZitadelAuthError
+} from '$lib/server/zitadel-session';
+import { startOidcSignIn } from '$lib/server/oidc-start';
+
+export const load: PageServerLoad = async (event) => {
+	const session = await event.locals.auth();
+	if (session?.user) {
+		redirect(303, '/todos');
+	}
+
+	// Optional: when coming from /login mid-OIDC, preserve authRequest to finalize without a second password entry.
+	const authRequest = event.url.searchParams.get('authRequest')?.trim() ?? '';
+	return { authRequest };
+};
+
+export const actions: Actions = {
+	default: async (event) => {
+		const form = await event.request.formData();
+		const authRequest = String(form.get('authRequest') ?? '').trim();
+		const username = String(form.get('username') ?? '').trim();
+		const email = String(form.get('email') ?? '').trim();
+		const password = String(form.get('password') ?? '');
+		const givenName = String(form.get('givenName') ?? '').trim();
+		const familyName = String(form.get('familyName') ?? '').trim();
+
+		const fields = { username, email, givenName, familyName };
+
+		if (!username || !email || !password) {
+			return fail(400, {
+				error: 'Username, email, and password are required.',
+				...fields
+			});
+		}
+
+		try {
+			if (authRequest) {
+				const callbackUrl = await registerAndLogin(authRequest, {
+					username,
+					email,
+					password,
+					givenName: givenName || undefined,
+					familyName: familyName || undefined
+				});
+				redirect(303, callbackUrl);
+			}
+
+			// Cold signup: create user, then start OIDC → custom /login for password + tokens.
+			await registerHuman({
+				username,
+				email,
+				password,
+				givenName: givenName || undefined,
+				familyName: familyName || undefined
+			});
+			// Point callback at todos after Auth.js completes.
+			const url = new URL(event.url);
+			if (!url.searchParams.get('callbackUrl')) {
+				url.searchParams.set('callbackUrl', '/todos');
+			}
+			await startOidcSignIn({ fetch: event.fetch, url }, 'sign-up');
+		} catch (e) {
+			// redirect() throws; rethrow so SvelteKit handles it
+			if (e && typeof e === 'object' && 'status' in e && 'location' in e) {
+				throw e;
+			}
+			const err = e instanceof ZitadelAuthError ? e : null;
+			return fail(err?.status && err.status < 500 ? err.status : 400, {
+				error: err?.message ?? 'Could not create account.',
+				...fields
+			});
+		}
+	}
+};
diff --git a/tests/e2e-ui/ui/src/routes/signup/+page.svelte b/tests/e2e-ui/ui/src/routes/signup/+page.svelte
new file mode 100644
index 00000000..112979af
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/signup/+page.svelte
@@ -0,0 +1,251 @@
+<script lang="ts">
+	import type { ActionData, PageData } from './$types';
+
+	let { data, form }: { data: PageData; form: ActionData } = $props();
+
+	const error = $derived(form?.error);
+	const username = $derived(form?.username ?? '');
+	const email = $derived(form?.email ?? '');
+	const givenName = $derived(form?.givenName ?? '');
+	const familyName = $derived(form?.familyName ?? '');
+	const loginHref = $derived(
+		`/login?authRequest=${encodeURIComponent(data.authRequest ?? '')}`
+	);
+</script>
+
+<svelte:head>
+	<title>Create account · e2e-ui</title>
+</svelte:head>
+
+<main class="auth-page">
+	<div class="auth-card">
+		<div class="auth-brand">
+			<span class="auth-mark" aria-hidden="true">df</span>
+			<span class="auth-product">e2e-ui</span>
+		</div>
+		<h1 class="auth-title">Create account</h1>
+		<p class="auth-lead">
+			Register in this demo. Your password is verified via Zitadel Session API; Auth.js still
+			holds the OIDC session cookie.
+		</p>
+
+		{#if error}
+			<p class="auth-error" role="alert">{error}</p>
+		{/if}
+
+		<form method="POST" class="auth-form">
+			<input type="hidden" name="authRequest" value={data.authRequest} />
+
+			<label class="auth-label" for="username">Username</label>
+			<input
+				id="username"
+				name="username"
+				type="text"
+				autocomplete="username"
+				required
+				class="auth-input"
+				value={username}
+				placeholder="carol"
+			/>
+
+			<label class="auth-label" for="email">Email</label>
+			<input
+				id="email"
+				name="email"
+				type="email"
+				autocomplete="email"
+				required
+				class="auth-input"
+				value={email}
+				placeholder="carol@example.com"
+			/>
+
+			<div class="auth-row">
+				<div class="auth-col">
+					<label class="auth-label" for="givenName">First name</label>
+					<input
+						id="givenName"
+						name="givenName"
+						type="text"
+						autocomplete="given-name"
+						class="auth-input"
+						value={givenName}
+					/>
+				</div>
+				<div class="auth-col">
+					<label class="auth-label" for="familyName">Last name</label>
+					<input
+						id="familyName"
+						name="familyName"
+						type="text"
+						autocomplete="family-name"
+						class="auth-input"
+						value={familyName}
+					/>
+				</div>
+			</div>
+
+			<label class="auth-label" for="password">Password</label>
+			<input
+				id="password"
+				name="password"
+				type="password"
+				autocomplete="new-password"
+				required
+				minlength="8"
+				class="auth-input"
+				placeholder="At least 8 characters"
+			/>
+
+			<button type="submit" class="auth-submit">Create account</button>
+		</form>
+
+		<p class="auth-meta">
+			<a href={loginHref}>Already have an account?</a>
+			<span class="auth-dot" aria-hidden="true">·</span>
+			<a href="/">Back home</a>
+		</p>
+	</div>
+</main>
+
+<style>
+	.auth-page {
+		min-height: calc(100vh - 4rem);
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		padding: 2rem var(--wf-gutter, 1.5rem);
+		background: var(--wf-bg, #f6f5f2);
+	}
+	.auth-card {
+		width: min(100%, 26rem);
+		background: var(--wf-bg-elevated, #fff);
+		border: 1px solid var(--wf-line, #e2e0d9);
+		border-radius: 10px;
+		padding: 2rem 1.75rem 1.75rem;
+		box-shadow: 0 12px 32px rgba(28, 28, 26, 0.06);
+	}
+	.auth-brand {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		margin-bottom: 1.25rem;
+	}
+	.auth-mark {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		width: 1.75rem;
+		height: 1.75rem;
+		border-radius: 5px;
+		background: var(--wf-ink, #1c1c1a);
+		color: #f6f5f2;
+		font-family: var(--wf-mono, ui-monospace, monospace);
+		font-size: 0.7rem;
+		font-weight: 500;
+	}
+	.auth-product {
+		font-weight: 600;
+		font-size: 0.95rem;
+		color: var(--wf-ink, #1c1c1a);
+	}
+	.auth-title {
+		margin: 0 0 0.35rem;
+		font-family: var(--wf-serif, Georgia, serif);
+		font-size: 1.65rem;
+		font-weight: 500;
+		letter-spacing: -0.02em;
+		color: var(--wf-ink, #1c1c1a);
+	}
+	.auth-lead {
+		margin: 0 0 1.25rem;
+		font-size: 0.875rem;
+		line-height: 1.45;
+		color: var(--wf-ink-soft, #5c5c56);
+	}
+	.auth-error {
+		margin: 0 0 1rem;
+		padding: 0.65rem 0.75rem;
+		border-radius: 6px;
+		background: rgba(179, 58, 58, 0.08);
+		border: 1px solid rgba(179, 58, 58, 0.25);
+		color: var(--wf-danger, #b33a3a);
+		font-size: 0.875rem;
+	}
+	.auth-form {
+		display: flex;
+		flex-direction: column;
+		gap: 0.35rem;
+	}
+	.auth-row {
+		display: grid;
+		grid-template-columns: 1fr 1fr;
+		gap: 0.75rem;
+	}
+	.auth-col {
+		display: flex;
+		flex-direction: column;
+		gap: 0.35rem;
+	}
+	.auth-label {
+		font-size: 0.8rem;
+		font-weight: 500;
+		color: var(--wf-ink-soft, #5c5c56);
+		margin-top: 0.5rem;
+	}
+	.auth-input {
+		appearance: none;
+		border: 1px solid var(--wf-line-strong, #cdcabe);
+		border-radius: 6px;
+		padding: 0.6rem 0.75rem;
+		font: inherit;
+		font-size: 0.95rem;
+		background: #fff;
+		color: var(--wf-ink, #1c1c1a);
+		width: 100%;
+		box-sizing: border-box;
+	}
+	.auth-input:focus {
+		outline: 2px solid var(--wf-accent, #3d5a80);
+		outline-offset: 1px;
+	}
+	.auth-submit {
+		margin-top: 1.15rem;
+		appearance: none;
+		border: none;
+		border-radius: 6px;
+		padding: 0.7rem 1rem;
+		font: inherit;
+		font-weight: 600;
+		font-size: 0.95rem;
+		background: var(--wf-accent, #3d5a80);
+		color: #fff;
+		cursor: pointer;
+	}
+	.auth-submit:hover {
+		filter: brightness(1.06);
+	}
+	.auth-submit:active {
+		transform: translateY(0.5px);
+	}
+	.auth-meta {
+		margin: 1.25rem 0 0;
+		font-size: 0.85rem;
+		color: var(--wf-ink-soft, #5c5c56);
+		display: flex;
+		flex-wrap: wrap;
+		gap: 0.35rem;
+		align-items: center;
+	}
+	.auth-meta a {
+		color: var(--wf-accent, #3d5a80);
+		text-decoration: none;
+		font-weight: 500;
+	}
+	.auth-meta a:hover {
+		text-decoration: underline;
+	}
+	.auth-dot {
+		opacity: 0.5;
+	}
+</style>
diff --git a/tests/e2e-ui/ui/src/routes/todos/+page.graphql b/tests/e2e-ui/ui/src/routes/todos/+page.graphql
new file mode 100644
index 00000000..ec105855
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/todos/+page.graphql
@@ -0,0 +1,9 @@
+# Compiler-owned SSR seed for the owner-scoped user surface.
+query Todos @load {
+  todos(order_by: [{ status: asc }, { todo_id: asc }]) {
+    todo_id
+    owner_id
+    title
+    status
+  }
+}
diff --git a/tests/e2e-ui/ui/src/routes/todos/+page.svelte b/tests/e2e-ui/ui/src/routes/todos/+page.svelte
new file mode 100644
index 00000000..f4acc172
--- /dev/null
+++ b/tests/e2e-ui/ui/src/routes/todos/+page.svelte
@@ -0,0 +1,423 @@
+<script lang="ts">
+	/**
+	 * Todos — generated operation state + generated causal commands.
+	 *
+	 * There is no app cache adapter or manual optimistic recipe here. The
+	 * compiler artifact tells the replica how command facts affect this query.
+	 */
+	import { Todos, useCommands } from '$distributed';
+	import { Button } from '$lib/components/shared/ui';
+	import {
+		AppPage,
+		InlineAlert,
+		PageHeader,
+		Panel,
+		StatRow
+	} from '$lib/components/product';
+	import { sessionDisplayName } from '$lib/session';
+
+	let { data } = $props();
+
+	let title = $state('');
+	let actionError = $state<string | null>(null);
+
+	const who = $derived(sessionDisplayName(data.session));
+
+	const list = Todos.use();
+	const commands = useCommands();
+
+	const rows = $derived($list.complete ? $list.data.todos : []);
+	const open = $derived(rows.filter((todo) => todo.status === 'open'));
+	const done = $derived(rows.filter((todo) => todo.status === 'completed'));
+	const archived = $derived(rows.filter((todo) => todo.status === 'archived'));
+
+	async function onCreate(e: Event) {
+		e.preventDefault();
+		const text = title.trim();
+		if (!text) return;
+
+		actionError = null;
+		title = '';
+		try {
+			await commands.todo.create({ title: text });
+		} catch (error) {
+			actionError = error instanceof Error ? error.message : 'create failed';
+		}
+	}
+
+	async function onComplete(todo_id: string) {
+		const target = rows.find((todo) => todo.todo_id === todo_id);
+		if (!target || target.status !== 'open') return;
+
+		actionError = null;
+		try {
+			await commands.todo.complete({ todo_id });
+		} catch (error) {
+			actionError = error instanceof Error ? error.message : 'complete failed';
+		}
+	}
+
+	async function onReopen(todo_id: string) {
+		const target = rows.find((todo) => todo.todo_id === todo_id);
+		if (!target || target.status !== 'completed') return;
+
+		actionError = null;
+		try {
+			await commands.todo.reopen({ todo_id });
+		} catch (error) {
+			actionError = error instanceof Error ? error.message : 'reopen failed';
+		}
+	}
+
+	async function onArchive(todo_id: string) {
+		const target = rows.find((todo) => todo.todo_id === todo_id);
+		if (!target || target.status === 'archived') return;
+
+		actionError = null;
+		try {
+			await commands.todo.archive({ todo_id });
+		} catch (error) {
+			actionError = error instanceof Error ? error.message : 'archive failed';
+		}
+	}
+</script>
+
+<AppPage>
+	<PageHeader kicker="Personal · owner-scoped" title="Todos">
+		Tasks for <strong>{who}</strong>. One generated <code>@load</code> operation feeds SSR,
+		navigation, and cache reads; typed commands update that same state optimistically and
+		retire it when projection catches up.
+	</PageHeader>
+
+	{#if data.gqlError}
+		<InlineAlert label="SSR GraphQL">{data.gqlError}</InlineAlert>
+	{/if}
+	{#if actionError}
+		<InlineAlert label="Mutation">{actionError}</InlineAlert>
+	{/if}
+
+	<form class="composer" onsubmit={onCreate}>
+		<label class="sr" for="todo-title">New task</label>
+		<input
+			id="todo-title"
+			class="input"
+			name="title"
+			placeholder="Capture something that needs doing…"
+			required
+			autocomplete="off"
+			bind:value={title}
+		/>
+		<Button type="submit" variant="ink" disabled={!title.trim()}>
+			<span>Add</span>
+			<svg width="16" height="16" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+				<path
+					d="M12 5v14M5 12h14"
+					stroke="currentColor"
+					stroke-width="2.5"
+					stroke-linecap="round"
+				/>
+			</svg>
+		</Button>
+	</form>
+
+	<StatRow
+		stats={[
+			{ value: open.length, label: 'open' },
+			{ value: done.length, label: 'done' },
+			{ value: archived.length, label: 'archived' }
+		]}
+	/>
+
+	<div class="board">
+		<Panel title="Open" count={open.length}>
+			{#if open.length === 0}
+				<p class="empty">Nothing open — write one above.</p>
+			{:else}
+				<ul class="list">
+					{#each open as t, i (t.todo_id)}
+						<li class="item" style="--i: {i}" data-todo-id={t.todo_id}>
+							<div class="item-main">
+								<button
+									class="check"
+									type="button"
+									title="Mark done"
+									aria-label="Mark done: {t.title}"
+									onclick={() => onComplete(t.todo_id)}
+								></button>
+								<span class="item-title">{t.title}</span>
+							</div>
+							<div class="item-actions">
+								<Button
+									variant="ghost"
+									size="sm"
+									type="button"
+									title="Mark done"
+									onclick={() => onComplete(t.todo_id)}>Done</Button
+								>
+								<Button
+									variant="quiet"
+									size="sm"
+									type="button"
+									title="Archive"
+									onclick={() => onArchive(t.todo_id)}>Archive</Button
+								>
+							</div>
+						</li>
+					{/each}
+				</ul>
+			{/if}
+		</Panel>
+
+		<Panel title="Done" count={done.length} muted>
+			{#if done.length === 0}
+				<p class="empty">Completed tasks land here.</p>
+			{:else}
+				<ul class="list">
+					{#each done as t, i (t.todo_id)}
+						<li class="item item-done" style="--i: {i}" data-todo-id={t.todo_id}>
+							<div class="item-main">
+								<button
+									class="check check-on"
+									type="button"
+									title="Reopen"
+									aria-label="Reopen: {t.title}"
+									onclick={() => onReopen(t.todo_id)}
+								>
+									<svg width="12" height="12" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+										<path
+											d="M5 12l5 5L20 7"
+											stroke="currentColor"
+											stroke-width="3"
+											stroke-linecap="round"
+											stroke-linejoin="round"
+										/>
+									</svg>
+								</button>
+								<span class="item-title">{t.title}</span>
+							</div>
+							<div class="item-actions">
+								<Button
+									variant="ghost"
+									size="sm"
+									type="button"
+									title="Reopen"
+									onclick={() => onReopen(t.todo_id)}>Reopen</Button
+								>
+								<Button
+									variant="quiet"
+									size="sm"
+									type="button"
+									onclick={() => onArchive(t.todo_id)}>Archive</Button
+								>
+							</div>
+						</li>
+					{/each}
+				</ul>
+			{/if}
+		</Panel>
+	</div>
+
+	{#if archived.length}
+		<details class="archive">
+			<summary>Archived ({archived.length})</summary>
+			<ul class="list list-compact">
+				{#each archived as t (t.todo_id)}
+					<li class="item item-archived" data-todo-id={t.todo_id}>
+						<span class="item-title">{t.title}</span>
+						<span class="badge">archived</span>
+					</li>
+				{/each}
+			</ul>
+		</details>
+	{/if}
+</AppPage>
+
+<style>
+	/* Route-local: composer + task list interaction (not shared chrome) */
+	.composer {
+		display: flex;
+		gap: 0.65rem;
+		flex-wrap: wrap;
+		padding: 0.65rem 0.75rem;
+		margin-bottom: 1.25rem;
+		background: var(--wf-bg-elevated, #fff);
+		border: 1px solid var(--wf-line, #e2e0d9);
+		border-radius: var(--df-radius-lg, 10px);
+		box-shadow: var(--df-shadow-sm, 0 1px 2px rgba(28, 28, 26, 0.04));
+	}
+
+	.input {
+		flex: 1;
+		min-width: 12rem;
+		border: none;
+		background: transparent;
+		padding: 0.55rem 0.65rem;
+		font: inherit;
+		font-size: 1rem;
+		color: var(--wf-ink, #1c1c1a);
+		outline: none;
+	}
+
+	.input::placeholder {
+		color: var(--wf-ink-muted, #8a8a82);
+	}
+
+	.board {
+		display: grid;
+		gap: 1rem;
+	}
+
+	@media (min-width: 768px) {
+		.board {
+			grid-template-columns: 1fr 1fr;
+			align-items: start;
+		}
+	}
+
+	.empty {
+		margin: 0.5rem 0 0.75rem;
+		font-size: 0.9rem;
+		color: var(--wf-ink-soft, #5c5c56);
+	}
+
+	.list {
+		list-style: none;
+		margin: 0;
+		padding: 0;
+		display: flex;
+		flex-direction: column;
+		gap: 0.15rem;
+	}
+
+	.item {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		justify-content: space-between;
+		gap: 0.5rem 0.75rem;
+		padding: 0.5rem 0.3rem;
+		border-radius: var(--wf-radius, 6px);
+		transition: background 0.12s ease;
+	}
+
+	.item:hover {
+		background: rgba(28, 28, 26, 0.04);
+	}
+
+	.item-main {
+		display: flex;
+		align-items: flex-start;
+		gap: 0.6rem;
+		flex: 1;
+		min-width: 0;
+	}
+
+	.check {
+		flex-shrink: 0;
+		display: grid;
+		place-items: center;
+		width: 1.15rem;
+		height: 1.15rem;
+		margin-top: 0.1rem;
+		padding: 0;
+		border-radius: 4px;
+		border: 1.5px solid var(--wf-line-strong, #cdcabe);
+		background: var(--wf-bg-elevated, #fff);
+		color: inherit;
+		cursor: pointer;
+		appearance: none;
+		transition:
+			border-color 0.12s ease,
+			background 0.12s ease;
+	}
+
+	.check:hover:not(:disabled) {
+		border-color: var(--wf-accent, #3d5a80);
+		background: var(--wf-accent-soft, rgba(61, 90, 128, 0.08));
+	}
+
+	.check-on {
+		border-color: var(--wf-success, #2f6f4e);
+		background: rgba(47, 111, 78, 0.1);
+		color: var(--wf-success, #2f6f4e);
+	}
+
+	.check-on:hover:not(:disabled) {
+		border-color: var(--wf-ink-soft, #5c5c56);
+		background: rgba(28, 28, 26, 0.06);
+		color: var(--wf-ink-soft, #5c5c56);
+	}
+
+	.item-title {
+		font-size: 0.95rem;
+		font-weight: 450;
+		line-height: 1.4;
+		word-break: break-word;
+	}
+
+	.item-done .item-title {
+		text-decoration: line-through;
+		text-decoration-thickness: 1px;
+		color: var(--wf-ink-soft, #5c5c56);
+	}
+
+	.item-actions {
+		display: flex;
+		gap: 0.2rem;
+		flex-shrink: 0;
+	}
+
+	.archive {
+		margin-top: 1.25rem;
+		padding: 0.75rem 0.95rem;
+		border-radius: var(--df-radius-lg, 10px);
+		border: 1px solid var(--wf-line, #e2e0d9);
+		background: var(--wf-bg-elevated, #fff);
+	}
+
+	.archive summary {
+		cursor: pointer;
+		font-weight: 600;
+		font-size: 0.8rem;
+		letter-spacing: 0.03em;
+		text-transform: uppercase;
+		color: var(--wf-ink-soft, #5c5c56);
+		list-style: none;
+	}
+
+	.archive summary::-webkit-details-marker {
+		display: none;
+	}
+
+	.list-compact {
+		margin-top: 0.65rem;
+	}
+
+	.item-archived {
+		opacity: 0.7;
+		justify-content: flex-start;
+		gap: 0.75rem;
+	}
+
+	.badge {
+		font-size: 0.65rem;
+		font-weight: 600;
+		letter-spacing: 0.05em;
+		text-transform: uppercase;
+		padding: 0.12rem 0.4rem;
+		border-radius: 999px;
+		background: rgba(28, 28, 26, 0.06);
+		color: var(--wf-ink-soft, #5c5c56);
+	}
+
+	.sr {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		padding: 0;
+		margin: -1px;
+		overflow: hidden;
+		clip: rect(0, 0, 0, 0);
+		border: 0;
+	}
+</style>
diff --git a/tests/e2e-ui/ui/static/favicon.png b/tests/e2e-ui/ui/static/favicon.png
new file mode 100644
index 00000000..38d58659
Binary files /dev/null and b/tests/e2e-ui/ui/static/favicon.png differ
diff --git a/tests/e2e-ui/ui/static/logo-icon.svg b/tests/e2e-ui/ui/static/logo-icon.svg
new file mode 100644
index 00000000..4bb629c7
--- /dev/null
+++ b/tests/e2e-ui/ui/static/logo-icon.svg
@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 754 688">
+  <defs>
+    <style>
+      .st0 { fill: #e69a2d; fill-rule: evenodd; }
+      .st1 { fill: #1a2744; fill-rule: evenodd; }
+    </style>
+  </defs>
+  <g id="navy">
+    <path class="st1" d="M412,593.6c-.2-1-1.1-2.2-2-3-5.7-4.9-19.8-23.9-25.7-17.7-27.4,22.6-60.3,55.7-86.2,81.2-7.5,7.9,6.3.8,9-.5,27.1-15,54.3-29.6,81.7-45,5.9-3.3,11.6-6.4,17.5-9.6,2.1-1.1,6-3,5.7-5.3h0Z"/>
+    <path class="st1" d="M341.9,528.6c-.2-5-5.1-8.4-10.1-13.6-3.1-3-6.3-6.1-9.4-9-3.2-2.9-6.6-6.5-11-6.8-3.7-.3-8,3-11.1,5.7-3.4,3-6.7,6.1-10,9.2-45.1,43.7-88,91.3-127.1,139.9-1.6,1.9-4.6,5.9-4.4,7.2,0,1,1.8.5,4.6-1,3.8-2.1,7.8-4.9,11.4-7.4,45.1-31.1,91.2-65,135.8-97.1,3.9-2.8,7.6-5.6,11.5-8.5,4-3,8.5-6.1,12.6-9.2,3-2.2,7.1-5.9,7-9.2h0Z"/>
+    <path class="st1" d="M264.2,448.5c0-3-2.7-5.7-5-7.7-6.9-6.1-14.1-12.2-21.4-17.7-5.5-4.3-10.8-5.1-16.4,0-10.7,9.8-20.4,22.2-30.4,32.9-40.3,43.2-77,89-112.3,136.4-13.5,18-26.2,34.8-38.7,53.5-4.9,7.6-11.2,17.1-1.7,9.1,78-61.5,149.5-132.2,222.3-200,2.1-2.1,3.5-4.3,3.5-6.4h0Z"/>
+    <path class="st1" d="M177.6,370.1c-7.5-5.1-22.7-23.1-30.7-23-1.6.2-3,1.4-4.3,3.1-4.2,5.3-8.7,11.1-12.4,16.8-24.5,31.7-47,66-70.7,98.2-14.5,21.5-29.2,43.5-43.3,65.2-3.1,5.3-7.3,10.8-10.9,15.6-.8,1.1-2.4,3.9-1.9,4.3.3.5,1.5,0,2.9-1.2,50.2-44,102.6-93,147.6-143,7.9-7.8,15.6-17.3,23.9-24.5,5-3.7,4.9-7.3,0-11.4h-.1Z"/>
+    <path class="st1" d="M97.5,282.5c-15.1,10.3-109.7,138.6-85,117,33.8-26.3,68.1-56.9,101.5-84.5,17.8-9.1-10.6-23.8-16.5-32.5Z"/>
+    <path class="st1" d="M629,263.5c-2.2-4.1-9.7-31-14-15-6,12.1-14.5,21.3-27.5,24.5-35,3-49.5-43.1-47-12,3.1,15.3,9.6,27.8,24.5,36,27.2,14.8,68.8,3.5,64-33.5Z"/>
+    <path class="st1" d="M365.9,5.5c-32.2,15.1-25.9,59.9-51.6,81.2-29,25.9-67.8,41.9-88.2,76.1-3.4,5.1-5.8,11.5-11.2,14.1-18.8,4.1-45.7-15.5-67.9,9.7-63.4,125.1,104.5,219.7,204,301.9,47.9,36.4,76.3,82.7,120,121.4,57.6,48.5,158.4,93.2,237.1,66.6,39.2-14.1,51.7-67.9,32.2-102.8-22.4-39.8-55-75.3-72.3-118.4-7-16.9-7.4-36.5-18.9-51.3-2.5-3.8-17.1-18.3-21.4-12.9-1.2,3.5-.2,7.8-2.5,11-19.9,17.9-76.9-3.1-17.7-16.1,28.3-9.4,38-51.3,9-58.1-15.1-1.8-32,4-46.5-3.4-5.5-1.1-16.4-15.9-19.2-6.3-3.6,15.9,4.7,29.2,15.2,40.2,3.9,4.7,1.5,10.2-1.2,14.9-13.8,25.7-12.9,60.4,21.3,68.4,24.2,5.8,36.2,37.9,59.4,38.8,9.5.2,14.2,8.3,16.6,16.7,9.6,26.2,28.6,49.5,46,71.7,4.7,7,20.9,24,9.6,28.4-35.8,2.5-67.7-8.6-92.8-33-17.4-15.5-34-41.8-53-58.5-66.6-57.1-121.1-122.2-155.9-201.2-11.7-18.2-23.8-36.2-25.2-57.7-.1-19.8,1.5-31.8-14.1-46.9-15-17.7-83.9-57-103.4-39.7-7,5.3-7.6,13.5.6,17.4,30.4,11.5,75.5,17.5,89.6,48.8,5.1,11.6,3.4,23.8,1.8,36.2-1.3,9.1-2.4,19.4-5.7,25.7-3.7,6.1-9.3.7-20.7-10.2-13.2-12.8-26.5-24.5-40.6-36.5-14.9-12.3-41.8-28.7-51.6-42.4-6-7.6-.3-16.8,5-23.3,26.1-32,72.2-65.1,111.2-76.5,10.2.4,13.6,19.6,20.9,27.4,16.7,23.4,46.4,31.4,73.1,37.8,15.7,3.9,37.8,3.5,45.3,14.1,5.4,7.1,1.7,17.5-7,19.4-11.4,2.4-23.3,1.6-34.8,3.3-15.8,2.4-33.7,3.7-44.6,16.5-28.7,41.9,32.6,76.8,54.1,113.4,5.5,9.5,9.6,19.2,12.3,30.1,2.6,7.1,3,27.6,9,30.6,2.2-.5,3.2-5.3,3.8-7.9,5.1-27.1.2-56.3-14.8-79.6-15.3-25-84.6-72.8-14.6-74.5,14.4-.6,29.4-2.5,43.3-.2,16.6,3.7,23.6,8.4,18-12.2-3.4-13.4-19.3-22.5-15.8-37.3,2.8-7.7,12.4-5.1,19.5-6.3,7.2-.8,14.6-2.6,21.3-5.7,44.1-20,2.3-88.3,42.1-107.2,8.4-3.7,19.9-3.2,26.3,3.7,13.2,16.5,3.6,38.7-2.7,56.4-2.5,4.9-3.7,15.6-9.7,16.8-9.8-4.6-8.8-6-16.7,3.4-18.4,22.6-60.2,42.1-52.5,76.7,2.8,10.4,11.1,18.9,20.6,23.8,42.3,21.8,71.3-26.3,72.9-70.3.3-10.7,1.9-21.1,6.2-30.9,16.3-36.3,25.7-90.8-18.7-107.7-20-6.9-39.4,2.9-54,16.6-3.2,3-6.1,6.2-9,9.5-33.7,47-126.6,28-143.5-23.1-3.3-8.9-7.2-18-14.8-24.2-8.8-7.6-21.6-11-32.4-6.2h-.2ZM618,430.3c1.1-4.1,15.1-3.9,19-3.6,6,.4,9.1,4.7,10.3,10.1,1.1,4.8,2.7,9.2,1.9,13.2-2.2,5.4-13.6-3.5-16.7-5.4-3.9-3.1-14.8-9.9-14.5-14.2h0ZM615.3,347.1c1.2,1.6.1,4-1.1,5.6-2,2.7-5.3,4.1-8.6,4-4.5-.3-10.2-2.2-11.9-5.5-.4-2.9,6.7-3.5,9-4.1,3.7-.5,9.9-2.6,12.5,0h0ZM381.5,301.7c6-.2,10.9,10.6,14.2,15.3,2.3,3.9,4.9,8,6.1,12.2,1.4,6.2-6.1-.6-10.1-4-2.5-2.2-5-4.3-7.5-6.5-3.2-2.8-6.9-5.9-7.6-10.2-.8-3.4,1.6-6.6,4.7-6.7h.2ZM165.3,203.9c20.7-32.4,136.9,75.5,162.7,96.4,17.2,15.1,27.5,22.4,42.9,35.6,92,80.2,158,198.6,269.5,253.9,4.9,2.1,9.9,3.8,15,5.2,12.5,3.4,25.1,6.4,37.9,9,6.5,1.3,12.9,2.6,19.2,4.4,5.4,1.4,12.1,5.3,11.2,11.4-.4,3.2-2.4,6-4.8,8-5.4,4.7-14.1,4.8-21.2,3.3-5.6-1.1-11.1-2.7-16.6-4.1-13.2-3-26.5-6.9-39.3-11.4-115.7-33.9-201.9-128-278.6-217.5-45.2-47.5-95.6-92-145.9-134-14.5-12.2-56.4-39.6-51.8-60.2h0ZM607.3,174c3.1,3.5-1.6,15.5-3.1,19.8-3.9,9.7-11,19.4-21.5,22.4-6.8,2.2-21,2.2-20.5-7.7,1.2-6.3,8.1-10.4,14.8-15,5-3.3,10.2-6.3,14.8-10.1,3.5-2.3,11.6-11.7,15.3-9.5h0ZM456.4,110.4c5.3-3.6,13.9.6,19.8,1.4,5.9,1.3,12.2,2.1,16.7,5.6,5.7,4.5,7.9,12.6,7.3,19.6-1.2,12.1-15.6,6.6-23.4,5.2-7.7-1.9-17.1-3.2-21.2-10.5-2.8-5.4-4.2-16.8.6-21.2h.1ZM550,106.5c5.2,2.5,3.7,12.1,2.4,17.1-3.8,14.5-16.4,24.3-31.3,24.1-13.4.2-14.4-5.3-16.8-17.3-.7-3.8-2.8-8.3-.6-11.9,3.5-4.1,9.7-3.4,15.6-4.4,2.1-.3,4.1-.6,6.1-1,3-.7,5.9-1.5,8.8-2.4,5.9-1.7,10.6-5.6,15.6-4.3h.1ZM396,87.7c5.9-10.9,20.2,2,27.5,5.5,2.5,1.4,5.1,2.7,7.6,4.1,5.8,3.1,12.2,5.1,15.6,10.1,4.2,5.5,3,24.3-6.1,23.8-4.2,0-8.5-2.3-12.4-4.1-12.9-6.2-23.6-15.4-30.3-28.1-1.8-3.3-3.3-7.6-2-11.1h0ZM384.7,29.6c3.8,2.8,6.1,8.5,7.4,13.4,1.7,6.1,3.2,13.1.5,17-4.3,5.5-12.8,4.4-19,5.8-5.5.7-10.7,3.6-15.5,2.8-3.9-1.3-1.4-7.1-.6-10.1,1.8-5.3,3.7-10.7,6.1-15.8,3.7-8.5,11.7-19.6,21-13.2h.1Z"/>
+  </g>
+  <g id="orange">
+    <path class="st0" d="M578.1,510.4c-.2.3.6,1.4,1.9,3,24.8,26.9,46.8,61.4,80.9,75,5.1,2,10.2,3.7,15.3,5.6,7.1,2.7,16.4,5.7,23.6,4.7,6.9-.8,11.5-6.4,5.6-11.7-13.5-11.9-32.9-19.5-47.4-30-16.9-12.2-32.6-26.7-51.6-35.6-7.7-3.5-16-6.3-23.6-9.7-1.3-.6-4.6-1.9-4.6-1.4h0Z"/>
+    <path class="st0" d="M436.4,235c-1.3,3.5,9.4,12.9,12.3,16.4,14,14.4,27.5,28.7,34.3,47.3,1.4,3.5,3.1,7.7,3.9,10.8,1.2,4.4.7,7,2.3,11.4,7.5,18.6,12,44.7,5.9,65.1-.9,4.1-3.6,9.7-4.2,12.9-.4,3.3.4,6.7.9,10.4,1.5,10.3,2.1,19.7,10,27.7,5,5.7,10.7,11.1,16.1,16.4,3.1,2.5,9.6,10.7,12.2,9.5.9-.6,1.2-2.7,1.4-5.6.7-40.1-.2-86.1-9.2-125-6-27.9-16.2-55.9-34.9-77.8-4.6-5.4-8.8-10.3-14.4-14.8-3-2.8-7.9-5.5-8.8-9.4-.1-.6,0-1-.3-1.3-.5-.2-1.1,0-1.6,0-1.6.2-4.9.6-8.2,1.1-1.8.3-3.7.6-5.5.9-4.6,1.1-9.7.7-12,3.8h0Z"/>
+    <path class="st0" d="M281.6,181.4c-3.9,2.1-5,8.7-5.3,13.1-.8,7,1.1,14,2.8,20.8,1.6,7.6,2.9,12.7,8.2,17.8,14.2,14,30,26.7,44.8,40,2.2,1.8,6.1,5.9,8.2,4.5,2.4-2.4,2.1-8.1,2.3-14.2,0-8.8-.6-18.4-.9-27.1-.2-5.1-.6-10-2.6-14.7-4.6-11.7-16.6-21.8-25.8-30.4-4.4-3.8-9.4-6.6-14.9-8.4-5.2-1.5-11.6-4.2-16.7-1.6h-.1Z"/>
+  </g>
+</svg>
diff --git a/tests/e2e-ui/ui/static/logo.svg b/tests/e2e-ui/ui/static/logo.svg
new file mode 100644
index 00000000..58e449f7
--- /dev/null
+++ b/tests/e2e-ui/ui/static/logo.svg
@@ -0,0 +1,77 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 240" fill="none">
+  <defs>
+    <style>
+      .navy { fill: #1a2744; }
+      .orange { fill: #e69a2d; }
+      .white { fill: #ffffff; }
+      .navy-stroke { stroke: #1a2744; fill: none; stroke-width: 4; stroke-linecap: round; stroke-linejoin: round; }
+      .orange-stroke { stroke: #e69a2d; fill: none; stroke-width: 4; stroke-linecap: round; }
+    </style>
+  </defs>
+
+  <!-- Motion lines (speed streaks) -->
+  <g class="navy">
+    <polygon points="45,95 20,115 23,120 50,98"/>
+    <polygon points="38,105 8,130 12,136 43,109"/>
+    <polygon points="33,117 0,147 5,153 38,121"/>
+    <polygon points="30,130 5,158 10,163 35,134"/>
+  </g>
+
+  <!-- Shoe sole outline -->
+  <path class="navy" d="M40,130 Q60,145 90,148 Q130,150 160,130 Q175,118 170,105 Q165,95 145,95 L50,105 Q35,110 40,130 Z"/>
+
+  <!-- Shoe body (white fill) -->
+  <path class="white" d="M55,100 Q70,75 95,60 Q115,50 135,55 Q155,62 165,80 Q170,95 160,105 L145,95 Q140,85 125,80 Q105,75 85,85 Q70,92 60,105 Z"/>
+
+  <!-- Shoe body outline -->
+  <path class="navy-stroke" d="M55,100 Q70,75 95,60 Q115,50 135,55 Q155,62 165,80 Q170,95 160,105"/>
+
+  <!-- Midsole stripe -->
+  <path class="navy" d="M48,115 Q75,125 110,125 Q145,125 165,115 L162,108 Q140,118 110,118 Q80,118 52,108 Z"/>
+
+  <!-- Orange accent on shoe side -->
+  <path class="orange" d="M75,85 Q90,78 110,80 Q125,82 135,90 L130,95 Q120,88 105,86 Q90,85 78,90 Z"/>
+
+  <!-- Tongue -->
+  <path class="white" d="M120,55 Q125,40 135,30 Q140,25 145,28 Q150,32 148,42 Q145,55 140,65 Z"/>
+  <path class="navy-stroke" d="M120,55 Q125,40 135,30 Q140,25 145,28 Q150,32 148,42 Q145,55 140,65"/>
+
+  <!-- Tongue detail lines -->
+  <path stroke="#1a2744" fill="none" stroke-width="2" d="M128,40 Q133,38 137,40"/>
+  <path stroke="#1a2744" fill="none" stroke-width="2" d="M126,48 Q132,45 138,48"/>
+
+  <!-- Collar/ankle area -->
+  <path class="navy-stroke" d="M135,55 Q150,50 160,60 Q168,70 165,80"/>
+
+  <!-- Laces - curvy lines -->
+  <g stroke="#1a2744" fill="none" stroke-width="3" stroke-linecap="round">
+    <path d="M105,62 Q115,58 125,62"/>
+    <path d="M100,70 Q112,65 122,70"/>
+    <path d="M95,78 Q108,72 118,78"/>
+  </g>
+
+  <!-- Lace loops at top -->
+  <g stroke="#1a2744" fill="none" stroke-width="2.5" stroke-linecap="round">
+    <path d="M130,58 Q138,52 145,58 Q148,62 145,68"/>
+    <path d="M148,42 Q155,38 160,45 Q162,52 158,58"/>
+  </g>
+
+  <!-- Heel counter -->
+  <path class="orange" d="M160,85 Q165,92 163,102 L158,100 Q160,92 157,87 Z"/>
+
+  <!-- "hops" text -->
+  <g class="navy">
+    <!-- h -->
+    <path d="M32,175 L32,210 L38,210 L38,195 Q38,188 45,188 L50,188 L50,210 L56,210 L56,182 Q56,175 48,175 L45,175 Q38,175 38,182 L38,175 Z"/>
+    <!-- o -->
+    <path d="M62,182 Q62,175 72,175 L78,175 Q88,175 88,182 L88,203 Q88,210 78,210 L72,210 Q62,210 62,203 Z M68,183 L68,202 Q68,205 72,205 L78,205 Q82,205 82,202 L82,183 Q82,180 78,180 L72,180 Q68,180 68,183 Z"/>
+    <!-- p -->
+    <path d="M94,175 L94,225 L100,225 L100,210 L108,210 Q118,210 118,203 L118,182 Q118,175 108,175 Z M100,180 L106,180 Q112,180 112,183 L112,202 Q112,205 106,205 L100,205 Z"/>
+    <!-- s -->
+    <path d="M124,175 L124,180 L140,180 Q144,180 144,183 L144,188 Q144,191 140,191 L130,191 Q124,191 124,198 L124,203 Q124,210 130,210 L148,210 L148,205 L132,205 Q128,205 128,202 L128,198 Q128,195 132,195 L142,195 Q148,195 148,188 L148,183 Q148,175 140,175 Z"/>
+  </g>
+
+  <!-- Orange swoosh under text -->
+  <path class="orange-stroke" stroke-width="5" d="M28,218 Q80,225 140,215 Q160,212 168,215"/>
+
+</svg>
diff --git a/tests/e2e-ui/ui/svelte.config.js b/tests/e2e-ui/ui/svelte.config.js
new file mode 100644
index 00000000..d7738202
--- /dev/null
+++ b/tests/e2e-ui/ui/svelte.config.js
@@ -0,0 +1,22 @@
+import adapter from '@sveltejs/adapter-node';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+import { distributedSvelteKitAliases } from '@hops-ops/distributed/sveltekit/vite';
+
+import {
+	distributedClients,
+	distributedViteOptions
+} from './distributed.config.js';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	preprocess: vitePreprocess(),
+	kit: {
+		adapter: adapter({ out: 'build' }),
+		alias: distributedSvelteKitAliases({
+			cwd: distributedViteOptions.cwd,
+			clients: distributedClients
+		})
+	}
+};
+
+export default config;
diff --git a/tests/e2e-ui/ui/tests/generated-client.test.mjs b/tests/e2e-ui/ui/tests/generated-client.test.mjs
new file mode 100644
index 00000000..99ff7dc7
--- /dev/null
+++ b/tests/e2e-ui/ui/tests/generated-client.test.mjs
@@ -0,0 +1,194 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const uiRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const fixtureRoot = path.resolve(uiRoot, '..');
+const read = (...segments) =>
+	fs.readFileSync(path.join(uiRoot, ...segments), 'utf8');
+
+test('co-located operations are the only app-authored GraphQL documents', () => {
+	const documents = [
+		['src/routes/todos/+page.graphql', /query Todos @load/],
+		['src/routes/chat/+page.graphql', /query ChatMessages @load @live/],
+		['src/routes/blob/[[gameId]]/+page.graphql', /query BlobGames @load/],
+		['src/routes/admin/+page.graphql', /query AdminAllTodos @load/]
+	];
+	for (const [relative, declaration] of documents) {
+		assert.match(read(relative), declaration, relative);
+	}
+
+	const authored = fs
+		.readdirSync(path.join(uiRoot, 'src/routes'), { recursive: true })
+		.filter((entry) => typeof entry === 'string' && /\.(gql|graphql)$/.test(entry))
+		.sort();
+	assert.deepEqual(authored, [
+		'admin/+page.graphql',
+		'blob/[[gameId]]/+page.graphql',
+		'chat/+page.graphql',
+		'todos/+page.graphql'
+	]);
+});
+
+test('generated route registries bind static @load ownership to artifacts', () => {
+	const userRoutes = read('src/lib/generated/user/routes.ts');
+	assert.match(userRoutes, /Operation_Todos/);
+	assert.match(userRoutes, /Operation_ChatMessages/);
+	assert.match(userRoutes, /Operation_BlobGames/);
+	assert.ok(userRoutes.includes('"route": "/todos"'));
+	assert.ok(userRoutes.includes('"route": "/chat"'));
+	assert.ok(userRoutes.includes('"route": "/blob/[[gameId]]"'));
+	assert.match(userRoutes, /DISTRIBUTED_ROUTE_OPERATIONS/);
+	assert.doesNotMatch(userRoutes, /AdminAllTodos/);
+
+	const adminRoutes = read('src/lib/generated/admin/routes.ts');
+	assert.match(adminRoutes, /Operation_AdminAllTodos/);
+	assert.ok(adminRoutes.includes('"route": "/admin"'));
+	assert.doesNotMatch(adminRoutes, /Operation_Todos/);
+});
+
+test('normal and elevated command inventories cannot be mixed', () => {
+	const user = read('src/lib/generated/user/commands.ts');
+	const admin = read('src/lib/generated/admin/commands.ts');
+
+	assert.match(user, /"name": "todo\.create"/);
+	assert.match(user, /"name": "chat\.post"/);
+	assert.match(user, /"name": "blob\.start"/);
+	assert.match(user, /"name": "blob\.move"/);
+	assert.doesNotMatch(user, /"name": "todo\.force_archive"/);
+	assert.match(user, /"kind": "application"/);
+	assert.match(user, /"name": "e2e-ui"/);
+
+	assert.match(admin, /"name": "todo\.force_archive"/);
+	assert.match(admin, /"name": "e2e-ui-admin"/);
+	assert.match(admin, /"roles": \[\s*"admin"\s*\]/);
+});
+
+test('SvelteKit composition uses one generated replica and a nested elevated boundary', () => {
+	const rootServer = read('src/routes/+layout.server.ts');
+	const rootLayout = read('src/routes/+layout.svelte');
+	const adminServer = read('src/routes/admin/+layout.server.ts');
+	const adminLayout = read('src/routes/admin/+layout.svelte');
+
+	assert.match(rootServer, /createDistributedSvelteKitServer/);
+	assert.match(rootServer, /DISTRIBUTED_ROUTE_OPERATIONS/);
+	assert.match(rootServer, /from '\$distributed'/);
+	assert.match(rootLayout, /createPageDataSessionSource/);
+	assert.match(rootLayout, /provideDistributed/);
+	assert.match(rootLayout, /from '\$distributed'/);
+	assert.doesNotMatch(rootLayout, /\$lib\/distributed/);
+
+	assert.match(adminServer, /isAdminEngineRole/);
+	assert.match(adminServer, /error\(\s*403/);
+	assert.match(adminServer, /from '\$distributed\/admin'/);
+	assert.match(adminLayout, /from '\$distributed\/admin'/);
+	assert.match(adminLayout, /provideDistributed/);
+
+	const localHelpers = path.join(uiRoot, 'src/lib/distributed');
+	assert.deepEqual(
+		fs.existsSync(localHelpers) ? fs.readdirSync(localHelpers) : [],
+		[],
+		'the fixture must not retain generic Svelte context/session helpers'
+	);
+});
+
+test('pages consume generated operation state and causal commands only', () => {
+	const expectations = [
+		[
+			'src/routes/todos/+page.svelte',
+			/Todos\.use\(\)/,
+			/commands\.todo\.create/
+		],
+		[
+			'src/routes/chat/+page.svelte',
+			/ChatMessages\.use\(\)/,
+			/commands\.chat\.post/
+		],
+		[
+			'src/routes/blob/[[gameId]]/+page.svelte',
+			/BlobGames\.use\(\)/,
+			/commands\.blob\.move/
+		],
+		[
+			'src/routes/admin/+page.svelte',
+			/AdminAllTodos\.use\(\)/,
+			/commands\.todo\.force_archive/
+		]
+	];
+
+	for (const [relative, operation, command] of expectations) {
+		const source = read(relative);
+		assert.match(source, operation, relative);
+		assert.match(source, command, relative);
+		assert.doesNotMatch(
+			source,
+			/useGraphql|useDistributedClient|gql\.(?:store|live)|list\.(?:seed|target|scheduleCatchUp)|optimistic:\s*\{|rememberedRows|seedList|applyRow|optimisticMove|pendingConfirms|lastConfirmed|sort(?:Admin)?Todos|sortChatMessages/,
+			relative
+		);
+		assert.doesNotMatch(source, /\.resource|commands\.generated/, relative);
+	}
+});
+
+test('Vite owns user/admin compiler entrypoints and generated modules stay state-free', () => {
+	const config = read('distributed.config.js');
+	const vite = read('vite.config.ts');
+	const svelte = read('svelte.config.js');
+	const user = read('src/lib/generated/user/sveltekit.ts');
+	const admin = read('src/lib/generated/admin/sveltekit.ts');
+
+	assert.match(config, /module: '\$distributed'/);
+	assert.match(config, /module: '\$distributed\/admin'/);
+	assert.match(config, /client-manifest/);
+	assert.match(config, /distributed_admin_client_surface/);
+	assert.match(vite, /distributedSvelteKit\(distributedViteOptions\)/);
+	assert.match(svelte, /distributedSvelteKitAliases/);
+
+	for (const generated of [user, admin]) {
+		assert.match(generated, /defineDistributedSvelteKitOperation/);
+		assert.match(generated, /export function provideDistributed/);
+		assert.match(generated, /export function useCommands/);
+		assert.doesNotMatch(
+			generated,
+			/^(?:const|let|var) (?:client|commands)\b/m,
+			'generated module must retain only static artifacts'
+		);
+	}
+});
+
+test('fixture generation is one dctl pipeline over typed Service inventory', () => {
+	const makefile = fs.readFileSync(path.join(fixtureRoot, 'Makefile'), 'utf8');
+	const config = read('distributed.config.js');
+	const runner = read('scripts/distributed-client.mjs');
+	const service = fs.readFileSync(
+		path.join(fixtureRoot, 'crates/service/src/service.rs'),
+		'utf8'
+	);
+
+	assert.match(makefile, /^gen-client:/m);
+	assert.match(makefile, /^check-client:/m);
+	assert.match(makefile, /client:generate/);
+	assert.match(makefile, /client:check/);
+	assert.doesNotMatch(
+		makefile,
+		/client-manifest|--documents|--surface|src\/lib\/generated\/(?:user|admin)/,
+		'Make must not duplicate distributed.config.js'
+	);
+	assert.match(config, /client-manifest/);
+	assert.match(config, /surface: 'e2e-ui'/);
+	assert.match(config, /surface: 'e2e-ui-admin'/);
+	assert.match(runner, /generateDistributedSvelteKit/);
+	assert.match(runner, /checkDistributedSvelteKit/);
+	assert.doesNotMatch(
+		makefile,
+		/export-commands|gen-commands|check-commands|gen-gql|check-gql/
+	);
+
+	assert.match(service, /\.typed_command\(/);
+	assert.match(service, /distributed_client_surface/);
+	assert.match(service, /distributed_admin_client_surface/);
+	assert.match(service, /surface_for_application\(/);
+	assert.match(service, /default input\.todo_id = uuid_v7\(\)/);
+	assert.doesNotMatch(service, /pub fn graphql_commands/);
+});
diff --git a/tests/e2e-ui/ui/tsconfig.json b/tests/e2e-ui/ui/tsconfig.json
new file mode 100644
index 00000000..a4fee1e4
--- /dev/null
+++ b/tests/e2e-ui/ui/tsconfig.json
@@ -0,0 +1,22 @@
+{
+	"extends": "./.svelte-kit/tsconfig.json",
+	"compilerOptions": {
+		"allowJs": true,
+		"checkJs": true,
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"sourceMap": true,
+		"strict": true,
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"noEmit": true,
+		"verbatimModuleSyntax": true
+	}
+	// Path aliases are handled by https://svelte.dev/docs/kit/configuration#alias
+	// except $lib which is handled by https://svelte.dev/docs/kit/configuration#files
+	//
+	// If you want to overwrite includes/excludes, make sure to copy over the relevant includes/excludes
+	// from the referenced tsconfig.json - TypeScript does not merge them in
+}
diff --git a/tests/e2e-ui/ui/vite.config.ts b/tests/e2e-ui/ui/vite.config.ts
new file mode 100644
index 00000000..9c4010a4
--- /dev/null
+++ b/tests/e2e-ui/ui/vite.config.ts
@@ -0,0 +1,20 @@
+import { sveltekit } from '@sveltejs/kit/vite';
+import {
+	distributedGraphqlProxy,
+	distributedSvelteKit
+} from '@hops-ops/distributed/sveltekit/vite';
+import { defineConfig } from 'vite';
+
+import { distributedViteOptions } from './distributed.config.js';
+
+const api = process.env.E2E_API_ORIGIN || process.env.E2E_BASE_URL || 'http://127.0.0.1:8791';
+
+export default defineConfig({
+	plugins: [distributedSvelteKit(distributedViteOptions), sveltekit()],
+	css: { devSourcemap: true },
+	server: {
+		port: 5180,
+		// GraphQL-only public API (commands are mutations, not POST /todo.*).
+		proxy: distributedGraphqlProxy(api)
+	}
+});
diff --git a/tests/fixtures/client-query-plan-corpus.json b/tests/fixtures/client-query-plan-corpus.json
new file mode 100644
index 00000000..d2d067bc
--- /dev/null
+++ b/tests/fixtures/client-query-plan-corpus.json
@@ -0,0 +1,53 @@
+{
+  "records": [
+    { "id": "1", "priority": 2, "completed": false },
+    { "id": "2", "priority": 5, "completed": true },
+    { "id": "3", "priority": 3, "completed": true },
+    { "id": "4", "priority": 1, "completed": false },
+    { "id": "5", "priority": 4, "completed": true }
+  ],
+  "cases": [
+    {
+      "name": "numeric-range",
+      "where": { "priority": { "_gte": 2, "_lt": 5 } },
+      "orderBy": [{ "priority": "asc" }],
+      "limit": 25,
+      "offset": 0,
+      "expected": ["1", "3", "5"]
+    },
+    {
+      "name": "boolean-and-in",
+      "where": {
+        "_and": [
+          { "completed": { "_eq": true } },
+          { "priority": { "_in": [3, 4, 5] } }
+        ]
+      },
+      "orderBy": [{ "priority": "desc" }],
+      "limit": 2,
+      "offset": 0,
+      "expected": ["2", "5"]
+    },
+    {
+      "name": "or-not-offset-window",
+      "where": {
+        "_or": [
+          { "priority": { "_lte": 2 } },
+          { "_not": { "completed": { "_eq": false } } }
+        ]
+      },
+      "orderBy": [{ "completed": "desc" }, { "priority": "asc" }],
+      "limit": 2,
+      "offset": 1,
+      "expected": ["5", "2"]
+    },
+    {
+      "name": "empty-in-is-false",
+      "where": { "priority": { "_in": [] } },
+      "orderBy": [{ "priority": "asc" }],
+      "limit": 25,
+      "offset": 0,
+      "expected": []
+    }
+  ]
+}
diff --git a/tests/graphql_causal_transport/main.rs b/tests/graphql_causal_transport/main.rs
new file mode 100644
index 00000000..a0fa2a6b
--- /dev/null
+++ b/tests/graphql_causal_transport/main.rs
@@ -0,0 +1,576 @@
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+
+use std::sync::Arc;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use base64::Engine as _;
+use distributed::graphql::{
+    typed_command, Accepted, GraphqlEngine, IdentityConfig, OidcConfig, PreparedCommand,
+};
+use distributed::microsvc::{CausalCommandContext, HandlerError, Routes, Service};
+use distributed::{
+    Aggregate, AggregateRepository, Entity, EventRecord, GraphqlInput, GraphqlOutput,
+    InMemoryRepository,
+};
+use futures_util::{SinkExt, StreamExt};
+use jsonwebtoken::{encode, Algorithm, EncodingKey, Header};
+use rand::thread_rng;
+use rsa::pkcs1::EncodeRsaPrivateKey;
+use rsa::traits::PublicKeyParts;
+use rsa::{RsaPrivateKey, RsaPublicKey};
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use tokio::net::TcpStream;
+use tokio::task::JoinHandle;
+use tokio_tungstenite::tungstenite::client::IntoClientRequest;
+use tokio_tungstenite::tungstenite::http::header::SEC_WEBSOCKET_PROTOCOL;
+use tokio_tungstenite::tungstenite::Message;
+use tokio_tungstenite::{MaybeTlsStream, WebSocketStream};
+
+const SERVICE_ID: &str = "causal-transport";
+const ISSUER: &str = "https://issuer.causal-transport.example";
+const AUDIENCE: &str = SERVICE_ID;
+const TEST_PROTOCOL_TOKEN_KEY: [u8; 32] = [0x5a; 32];
+const TARGET_COMMAND_ID: &str = "0190a000-0000-7000-8000-000000000101";
+const GUESSED_COMMAND_ID: &str = "0190a000-0000-7000-8000-000000000102";
+const EXPIRED_COMMAND_ID: &str = "0190a000-0000-7000-8000-000000000103";
+const MUTATION: &str = r#"
+mutation CausalTransportMutation($commandId: ID!) {
+  todo_create(commandId: $commandId, input: { id: "todo-1" }) {
+    id
+  }
+}
+"#;
+const STATUS_QUERY: &str = r#"
+query CausalTransportStatus($commandId: ID!) {
+  commandStatus(commandId: $commandId) {
+    state
+  }
+}
+"#;
+const RAW_QUERY: &str = "query RawQuery { __typename }";
+const AMBIGUOUS_QUERY: &str = "query First { __typename } query Second { __typename }";
+
+#[derive(Default)]
+struct TransportAggregate {
+    entity: Entity,
+}
+
+impl Aggregate for TransportAggregate {
+    type ReplayError = String;
+
+    fn aggregate_type() -> &'static str {
+        "causal-transport-fixture"
+    }
+
+    fn entity(&self) -> &Entity {
+        &self.entity
+    }
+
+    fn entity_mut(&mut self) -> &mut Entity {
+        &mut self.entity
+    }
+
+    fn replay_event(&mut self, _event: &EventRecord) -> Result<(), Self::ReplayError> {
+        Ok(())
+    }
+}
+
+#[derive(Deserialize, GraphqlInput)]
+struct TransportCommandInput {
+    id: String,
+}
+
+#[derive(Serialize, GraphqlOutput)]
+struct TransportCommandOutput {
+    id: String,
+}
+
+async fn accept_command(
+    _context: &CausalCommandContext<'_, TransportAggregate>,
+    input: TransportCommandInput,
+) -> Result<PreparedCommand<Accepted<TransportCommandOutput>>, HandlerError> {
+    Ok(
+        PreparedCommand::<Accepted<TransportCommandOutput>>::prepare(TransportCommandOutput {
+            id: input.id,
+        })
+        .expect("the fixture output is JSON-serializable"),
+    )
+}
+
+fn causal_service() -> Service {
+    let routes: Routes<AggregateRepository<InMemoryRepository, TransportAggregate>> = Routes::new()
+        .with_repo(AggregateRepository::new(InMemoryRepository::new()))
+        .typed_command(
+            typed_command::<TransportCommandInput, Accepted<TransportCommandOutput>>("todo.create")
+                .roles(["writer"]),
+        )
+        .handle(accept_command)
+        // Keep commandStatus present on the downgraded role's schema while
+        // withholding the target command's current grant.
+        .typed_command(
+            typed_command::<TransportCommandInput, Accepted<TransportCommandOutput>>("reader.ping")
+                .roles(["reader"]),
+        )
+        .handle(accept_command);
+    Service::new().named(SERVICE_ID).routes(routes)
+}
+
+struct TestKeys {
+    encoding: EncodingKey,
+    jwks: String,
+    kid: String,
+}
+
+impl TestKeys {
+    fn new() -> Self {
+        let private = RsaPrivateKey::new(&mut thread_rng(), 2048).expect("test RSA key");
+        let public = RsaPublicKey::from(&private);
+        let pem = private
+            .to_pkcs1_pem(rsa::pkcs8::LineEnding::LF)
+            .expect("test RSA PEM");
+        let encoding = EncodingKey::from_rsa_pem(pem.as_bytes()).expect("test RSA encoding key");
+        let kid = "causal-transport-test-key".to_string();
+        let modulus =
+            base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(public.n().to_bytes_be());
+        let exponent =
+            base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(public.e().to_bytes_be());
+        let jwks = json!({
+            "keys": [{
+                "kty": "RSA",
+                "kid": kid,
+                "alg": "RS256",
+                "use": "sig",
+                "n": modulus,
+                "e": exponent
+            }]
+        })
+        .to_string();
+        Self {
+            encoding,
+            jwks,
+            kid,
+        }
+    }
+
+    fn token(&self, subject: &str, role: &str) -> String {
+        self.token_for_tenant(subject, role, "tenant-a")
+    }
+
+    fn token_for_tenant(&self, subject: &str, role: &str, tenant: &str) -> String {
+        let now = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("system clock")
+            .as_secs();
+        let claims = json!({
+            "iss": ISSUER,
+            "aud": AUDIENCE,
+            "sub": subject,
+            "iat": now.saturating_sub(1),
+            "nbf": now.saturating_sub(1),
+            "exp": now + 3600,
+            "roles": [role],
+            "tenant": tenant
+        });
+        let mut header = Header::new(Algorithm::RS256);
+        header.kid = Some(self.kid.clone());
+        encode(&header, &claims, &self.encoding).expect("sign test access token")
+    }
+}
+
+struct TestServer {
+    http_url: String,
+    ws_url: String,
+    task: JoinHandle<()>,
+}
+
+impl Drop for TestServer {
+    fn drop(&mut self) {
+        self.task.abort();
+    }
+}
+
+async fn spawn_server(service: Arc<Service>) -> TestServer {
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("bind test server");
+    let address = listener.local_addr().expect("test server address");
+    let app = distributed::microsvc::router(service);
+    let task = tokio::spawn(async move {
+        axum::serve(listener, app)
+            .await
+            .expect("causal transport server");
+    });
+    TestServer {
+        http_url: format!("http://{address}/graphql"),
+        ws_url: format!("ws://{address}/graphql/ws"),
+        task,
+    }
+}
+
+async fn http_graphql(
+    server: &TestServer,
+    bearer: Option<&str>,
+    query: &str,
+    variables: Value,
+) -> Value {
+    let client = reqwest::Client::new();
+    let mut request = client
+        .post(&server.http_url)
+        .json(&json!({ "query": query, "variables": variables }));
+    if let Some(token) = bearer {
+        request = request.bearer_auth(token);
+    }
+    let response = request.send().await.expect("HTTP GraphQL response");
+    assert_eq!(
+        response.status(),
+        reqwest::StatusCode::OK,
+        "GraphQL HTTP status"
+    );
+    response.json().await.expect("GraphQL HTTP JSON")
+}
+
+type TestWebSocket = WebSocketStream<MaybeTlsStream<TcpStream>>;
+
+async fn next_ws_json(socket: &mut TestWebSocket) -> Value {
+    loop {
+        match socket
+            .next()
+            .await
+            .expect("GraphQL WS frame")
+            .expect("valid GraphQL WS frame")
+        {
+            Message::Text(text) => {
+                return serde_json::from_str(text.as_ref()).expect("GraphQL WS JSON");
+            }
+            Message::Ping(payload) => {
+                socket
+                    .send(Message::Pong(payload))
+                    .await
+                    .expect("GraphQL WS pong");
+            }
+            Message::Close(frame) => panic!("GraphQL WS closed early: {frame:?}"),
+            _ => {}
+        }
+    }
+}
+
+async fn ws_graphql(
+    server: &TestServer,
+    connection_init: Value,
+    query: &str,
+    variables: Value,
+) -> Value {
+    let mut request = server
+        .ws_url
+        .as_str()
+        .into_client_request()
+        .expect("GraphQL WS request");
+    request.headers_mut().insert(
+        SEC_WEBSOCKET_PROTOCOL,
+        "graphql-transport-ws"
+            .parse()
+            .expect("GraphQL WS protocol header"),
+    );
+    let (mut socket, response) = tokio_tungstenite::connect_async(request)
+        .await
+        .expect("GraphQL WS connect");
+    assert_eq!(
+        response
+            .headers()
+            .get(SEC_WEBSOCKET_PROTOCOL)
+            .and_then(|value| value.to_str().ok()),
+        Some("graphql-transport-ws")
+    );
+
+    socket
+        .send(Message::Text(
+            json!({ "type": "connection_init", "payload": connection_init })
+                .to_string()
+                .into(),
+        ))
+        .await
+        .expect("GraphQL WS connection_init");
+    let acknowledgement = next_ws_json(&mut socket).await;
+    assert_eq!(
+        acknowledgement,
+        json!({ "type": "connection_ack" }),
+        "GraphQL WS acknowledgement"
+    );
+
+    socket
+        .send(Message::Text(
+            json!({
+                "id": "operation-1",
+                "type": "subscribe",
+                "payload": { "query": query, "variables": variables }
+            })
+            .to_string()
+            .into(),
+        ))
+        .await
+        .expect("GraphQL WS subscribe");
+    let next = next_ws_json(&mut socket).await;
+    assert_eq!(next["id"], "operation-1");
+    assert_eq!(next["type"], "next", "GraphQL WS operation result: {next}");
+    let payload = next["payload"].clone();
+    let complete = next_ws_json(&mut socket).await;
+    assert_eq!(
+        complete,
+        json!({ "id": "operation-1", "type": "complete" }),
+        "GraphQL WS completion"
+    );
+    socket.close(None).await.expect("close GraphQL WS");
+    payload
+}
+
+fn bearer_init(token: &str) -> Value {
+    json!({ "authorization": format!("Bearer {token}") })
+}
+
+fn distributed_envelope(response: &Value) -> &Value {
+    response
+        .get("extensions")
+        .and_then(|extensions| extensions.get("distributed"))
+        .unwrap_or_else(|| panic!("missing extensions.distributed: {response}"))
+}
+
+fn assert_unknown_status(response: &Value, hidden_command_id: &str) {
+    assert_eq!(
+        response["data"],
+        json!({ "commandStatus": { "state": "unknown" } })
+    );
+    assert!(
+        distributed_envelope(response).get("command").is_none(),
+        "unknown status must not fabricate or disclose receipt metadata: {response}"
+    );
+    assert!(
+        !response.to_string().contains(hidden_command_id),
+        "non-enumerating status echoed a command ID: {response}"
+    );
+}
+
+async fn assert_http_ws_status_pair(
+    server: &TestServer,
+    token: &str,
+    command_id: &str,
+) -> (Value, Value) {
+    let variables = json!({ "commandId": command_id });
+    let http = http_graphql(server, Some(token), STATUS_QUERY, variables.clone()).await;
+    let websocket = ws_graphql(server, bearer_init(token), STATUS_QUERY, variables).await;
+    assert_eq!(
+        distributed_envelope(&http),
+        distributed_envelope(&websocket),
+        "HTTP and GraphQL-WS must serialize one canonical distributed envelope"
+    );
+    assert_eq!(http["data"], websocket["data"]);
+    (http, websocket)
+}
+
+#[tokio::test]
+async fn causal_receipt_status_replay_and_nonenumeration_match_http_and_ws() {
+    let keys = TestKeys::new();
+    let mut oidc = OidcConfig::new(ISSUER, AUDIENCE)
+        .with_static_jwks(keys.jwks.clone())
+        .principal_tenant_claims(["tenant"])
+        .engine_roles(&["writer", "reader"]);
+    oidc.require_role = true;
+    oidc.claim_map.role_priority = vec!["writer".into(), "reader".into()];
+
+    let service = causal_service();
+    let pool = sqlx::sqlite::SqlitePoolOptions::new()
+        .connect_lazy("sqlite::memory:")
+        .expect("GraphQL SQLite pool");
+    let engine = GraphqlEngine::builder(pool)
+        .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+        .roles(&["writer", "reader"])
+        .identity(IdentityConfig::oidc_bearer(oidc))
+        .service(&service)
+        .build()
+        .expect("causal transport GraphQL engine");
+    let service = Arc::new(
+        service
+            .try_with_graphql(engine)
+            .expect("causal transport GraphQL attachment"),
+    );
+    let server = spawn_server(service).await;
+
+    let writer_a = keys.token("subject-a", "writer");
+    let writer_b = keys.token("subject-b", "writer");
+    let writer_a_other_tenant = keys.token_for_tenant("subject-a", "writer", "tenant-b");
+    let reader_a = keys.token("subject-a", "reader");
+    let mutation_variables = json!({ "commandId": TARGET_COMMAND_ID });
+
+    // HTTP accepts the command; GraphQL-WS repeats the exact same command ID
+    // and input. The durable replay must yield byte-for-byte equivalent public
+    // data and receipt metadata on both transports.
+    let http_mutation = http_graphql(
+        &server,
+        Some(&writer_a),
+        MUTATION,
+        mutation_variables.clone(),
+    )
+    .await;
+    let ws_replay = ws_graphql(
+        &server,
+        bearer_init(&writer_a),
+        MUTATION,
+        mutation_variables,
+    )
+    .await;
+    assert_eq!(
+        http_mutation["data"],
+        json!({ "todo_create": { "id": "todo-1" } }),
+        "domain data must not contain receipt metadata"
+    );
+    assert_eq!(
+        http_mutation["data"], ws_replay["data"],
+        "GraphQL-WS replay response: {ws_replay}"
+    );
+    assert_eq!(
+        distributed_envelope(&http_mutation),
+        distributed_envelope(&ws_replay),
+        "same-ID replay must retain the exact transport-independent envelope"
+    );
+    let receipt = &distributed_envelope(&http_mutation)["command"];
+    assert_eq!(receipt["commandId"], TARGET_COMMAND_ID);
+    assert_eq!(receipt["state"], "accepted");
+    assert_eq!(receipt["consistency"], "accepted");
+    assert_eq!(receipt["expects"], json!([]));
+    assert!(
+        receipt["causationId"]
+            .as_str()
+            .is_some_and(|id| !id.is_empty()),
+        "receipt must include its durable causation identity: {receipt}"
+    );
+
+    // The current principal and current writer grant see the same sanitized
+    // status and receipt metadata through HTTP and GraphQL-WS.
+    let (http_status, ws_status) =
+        assert_http_ws_status_pair(&server, &writer_a, TARGET_COMMAND_ID).await;
+    assert_eq!(
+        http_status["data"],
+        json!({ "commandStatus": { "state": "accepted" } }),
+        "status data stays intentionally minimal"
+    );
+    assert_eq!(http_status["data"], ws_status["data"]);
+    assert_eq!(
+        distributed_envelope(&http_status)["command"],
+        distributed_envelope(&http_mutation)["command"],
+        "status must expose the same durable receipt, not reconstructed state"
+    );
+
+    // A guessed ID, a different verified subject, and the same subject after a
+    // role downgrade all collapse to the identical public `unknown` shape.
+    let (guessed_http, guessed_ws) =
+        assert_http_ws_status_pair(&server, &writer_a, GUESSED_COMMAND_ID).await;
+    assert_unknown_status(&guessed_http, GUESSED_COMMAND_ID);
+    assert_unknown_status(&guessed_ws, GUESSED_COMMAND_ID);
+
+    let (wrong_principal_http, wrong_principal_ws) =
+        assert_http_ws_status_pair(&server, &writer_b, TARGET_COMMAND_ID).await;
+    assert_unknown_status(&wrong_principal_http, TARGET_COMMAND_ID);
+    assert_unknown_status(&wrong_principal_ws, TARGET_COMMAND_ID);
+
+    let (wrong_tenant_http, wrong_tenant_ws) =
+        assert_http_ws_status_pair(&server, &writer_a_other_tenant, TARGET_COMMAND_ID).await;
+    assert_unknown_status(&wrong_tenant_http, TARGET_COMMAND_ID);
+    assert_unknown_status(&wrong_tenant_ws, TARGET_COMMAND_ID);
+
+    let (downgraded_http, downgraded_ws) =
+        assert_http_ws_status_pair(&server, &reader_a, TARGET_COMMAND_ID).await;
+    assert_unknown_status(&downgraded_http, TARGET_COMMAND_ID);
+    assert_unknown_status(&downgraded_ws, TARGET_COMMAND_ID);
+}
+
+#[tokio::test]
+async fn expired_command_status_is_typed_and_transport_independent() {
+    let keys = TestKeys::new();
+    let mut oidc = OidcConfig::new(ISSUER, AUDIENCE)
+        .with_static_jwks(keys.jwks.clone())
+        .principal_tenant_claims(["tenant"])
+        .engine_roles(&["writer", "reader"]);
+    oidc.require_role = true;
+    oidc.claim_map.role_priority = vec!["writer".into(), "reader".into()];
+
+    let service = causal_service()
+        .causal_command_timing(Duration::from_millis(25), Duration::from_millis(100));
+    let pool = sqlx::sqlite::SqlitePoolOptions::new()
+        .connect_lazy("sqlite::memory:")
+        .expect("GraphQL SQLite pool");
+    let engine = GraphqlEngine::builder(pool)
+        .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+        .roles(&["writer", "reader"])
+        .identity(IdentityConfig::oidc_bearer(oidc))
+        .service(&service)
+        .build()
+        .expect("expiring causal transport GraphQL engine");
+    let service = Arc::new(
+        service
+            .try_with_graphql(engine)
+            .expect("expiring causal transport GraphQL attachment"),
+    );
+    let server = spawn_server(service).await;
+    let writer = keys.token("expiring-subject", "writer");
+
+    let accepted = http_graphql(
+        &server,
+        Some(&writer),
+        MUTATION,
+        json!({ "commandId": EXPIRED_COMMAND_ID }),
+    )
+    .await;
+    assert_eq!(
+        distributed_envelope(&accepted)["command"]["state"],
+        "accepted"
+    );
+
+    tokio::time::sleep(Duration::from_millis(150)).await;
+    let (http, websocket) = assert_http_ws_status_pair(&server, &writer, EXPIRED_COMMAND_ID).await;
+    assert_eq!(
+        http["data"],
+        json!({ "commandStatus": { "state": "expired" } })
+    );
+    assert_eq!(http["data"], websocket["data"]);
+    assert!(
+        distributed_envelope(&http).get("command").is_none(),
+        "expired status must not revive stale receipt evidence: {http}"
+    );
+}
+
+#[tokio::test]
+async fn query_only_keyless_service_remains_envelope_free_over_http_and_ws() {
+    let service = Service::new().named("raw-query-only");
+    let pool = sqlx::sqlite::SqlitePoolOptions::new()
+        .connect_lazy("sqlite::memory:")
+        .expect("GraphQL SQLite pool");
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .service(&service)
+        .build()
+        .expect("keyless query-only engine");
+    let service = Arc::new(
+        service
+            .try_with_graphql(engine)
+            .expect("keyless query-only attachment"),
+    );
+    let server = spawn_server(service).await;
+
+    let http = http_graphql(&server, None, RAW_QUERY, json!({})).await;
+    let websocket = ws_graphql(&server, json!({}), RAW_QUERY, json!({})).await;
+    assert_eq!(http["data"], json!({ "__typename": "Query" }));
+    assert_eq!(http, websocket);
+    assert!(
+        http.get("extensions")
+            .and_then(|extensions| extensions.get("distributed"))
+            .is_none(),
+        "keyless query-only fallback must not fabricate protocol evidence: {http}"
+    );
+
+    let ambiguous = ws_graphql(&server, json!({}), AMBIGUOUS_QUERY, json!({})).await;
+    assert_eq!(ambiguous["data"], Value::Null);
+    assert_eq!(
+        ambiguous["errors"][0]["message"],
+        "GraphQL operation name is required for multi-operation documents"
+    );
+}
diff --git a/tests/graphql_commands/main.rs b/tests/graphql_commands/main.rs
new file mode 100644
index 00000000..aa478b9d
--- /dev/null
+++ b/tests/graphql_commands/main.rs
@@ -0,0 +1,156 @@
+//! GraphQL command type metadata remains exact for typed causal commands.
+
+#![cfg(feature = "graphql")]
+
+use distributed::graphql::{GraphqlTypeDef, GraphqlTypeField};
+
+#[test]
+fn graphql_type_def_mapping_golden() {
+    let input = GraphqlTypeDef::new(
+        "CreateItemInput",
+        vec![
+            GraphqlTypeField {
+                name: "id".into(),
+                type_name: "String".into(),
+                nullable: false,
+                list: false,
+                item_nullable: false,
+                nested: None,
+            },
+            GraphqlTypeField {
+                name: "tags".into(),
+                type_name: "String".into(),
+                nullable: true,
+                list: true,
+                item_nullable: false,
+                nested: None,
+            },
+        ],
+    );
+    assert_eq!(input.name, "CreateItemInput");
+    assert_eq!(input.fields.len(), 2);
+    assert!(!input.fields[0].nullable);
+    assert!(input.fields[1].list);
+}
+
+#[derive(distributed::GraphqlInput)]
+#[allow(dead_code)]
+struct DerivedInput {
+    id: String,
+    count: i64,
+    tags: Option<Vec<String>>,
+}
+
+#[derive(distributed::GraphqlOutput)]
+#[allow(dead_code)]
+struct DerivedOutput {
+    ok: bool,
+    id: String,
+}
+
+#[derive(distributed::GraphqlInput, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+#[allow(dead_code)]
+struct ScalarMatrixInput {
+    #[serde(rename = "wireRequired")]
+    required: String,
+    optional: Option<String>,
+    required_items: Vec<String>,
+    optional_items: Option<Vec<String>>,
+    nullable_items: Vec<Option<String>>,
+    optional_nullable_items: Option<Vec<Option<String>>>,
+}
+
+#[derive(distributed::GraphqlOutput, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+#[allow(dead_code)]
+struct ScalarMatrixOutput {
+    #[serde(rename = "wireRequired")]
+    required: String,
+    optional: Option<String>,
+    required_items: Vec<String>,
+    optional_items: Option<Vec<String>>,
+    nullable_items: Vec<Option<String>>,
+    optional_nullable_items: Option<Vec<Option<String>>>,
+}
+
+#[derive(distributed::GraphqlInput)]
+#[serde(rename_all(deserialize = "camelCase", serialize = "SCREAMING_SNAKE_CASE"))]
+#[allow(dead_code)]
+struct DirectionalInputNames {
+    regular_field: String,
+    #[serde(rename(deserialize = "inputID", serialize = "OUTPUT_ID"))]
+    custom_id: String,
+}
+
+#[derive(distributed::GraphqlOutput)]
+#[serde(rename_all(deserialize = "camelCase", serialize = "SCREAMING_SNAKE_CASE"))]
+#[allow(dead_code)]
+struct DirectionalOutputNames {
+    regular_field: String,
+    #[serde(rename(deserialize = "inputID", serialize = "OUTPUT_ID"))]
+    custom_id: String,
+}
+
+#[test]
+fn derive_mapping_golden() {
+    use distributed::graphql::{GraphqlInputType, GraphqlOutputType};
+
+    let input = DerivedInput::graphql_type();
+    assert_eq!(input.name, "DerivedInput");
+    assert_eq!(input.fields.len(), 3);
+    assert_eq!(input.fields[0].type_name, "String");
+    assert!(!input.fields[0].nullable);
+    assert_eq!(input.fields[1].type_name, "BigInt");
+    assert!(input.fields[2].list);
+    assert!(input.fields[2].nullable);
+
+    let output = DerivedOutput::graphql_type();
+    assert_eq!(output.name, "DerivedOutput");
+    assert_eq!(output.fields[0].type_name, "Boolean");
+    assert_eq!(output.fields[1].type_name, "String");
+}
+
+#[test]
+fn derive_preserves_outer_and_item_nullability_and_serde_names() {
+    use distributed::graphql::{GraphqlInputType, GraphqlOutputType};
+
+    let expected = [
+        ("wireRequired", false, false, false),
+        ("optional", true, false, false),
+        ("requiredItems", false, true, false),
+        ("optionalItems", true, true, false),
+        ("nullableItems", false, true, true),
+        ("optionalNullableItems", true, true, true),
+    ];
+    for definition in [
+        ScalarMatrixInput::graphql_type(),
+        ScalarMatrixOutput::graphql_type(),
+    ] {
+        for (name, nullable, list, item_nullable) in expected {
+            let field = definition
+                .fields
+                .iter()
+                .find(|field| field.name == name)
+                .unwrap_or_else(|| panic!("missing {name} on {}", definition.name));
+            assert_eq!(field.type_name, "String", "{name}");
+            assert_eq!(field.nullable, nullable, "{name}");
+            assert_eq!(field.list, list, "{name}");
+            assert_eq!(field.item_nullable, item_nullable, "{name}");
+        }
+    }
+
+    let input_names: Vec<_> = DirectionalInputNames::graphql_type()
+        .fields
+        .into_iter()
+        .map(|field| field.name)
+        .collect();
+    assert_eq!(input_names, ["regularField", "inputID"]);
+
+    let output_names: Vec<_> = DirectionalOutputNames::graphql_type()
+        .fields
+        .into_iter()
+        .map(|field| field.name)
+        .collect();
+    assert_eq!(output_names, ["REGULAR_FIELD", "OUTPUT_ID"]);
+}
diff --git a/tests/graphql_compile/main.rs b/tests/graphql_compile/main.rs
new file mode 100644
index 00000000..2b9dbe3b
--- /dev/null
+++ b/tests/graphql_compile/main.rs
@@ -0,0 +1,205 @@
+//! Production compile-path behavioral goldens (via GraphqlEngine::execute).
+//! Empty placeholder removed — suite drives shipped compile_root through execute.
+
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+
+use async_graphql::Request;
+use distributed::graphql::{read, GraphqlEngine, ModelPermissions};
+use distributed::microsvc::{Session, ROLE_KEY};
+use distributed::ReadModel;
+use serde::{Deserialize, Serialize};
+use serde_json::Value as JsonValue;
+use sqlx::sqlite::SqlitePoolOptions;
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[table("items")]
+struct ItemView {
+    #[id("id")]
+    id: String,
+    name: String,
+}
+
+fn user() -> Session {
+    let mut s = Session::new();
+    s.set(ROLE_KEY, "user");
+    s
+}
+
+async fn engine() -> GraphqlEngine {
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query("CREATE TABLE items (id TEXT PRIMARY KEY, name TEXT NOT NULL)")
+        .execute(&pool)
+        .await
+        .unwrap();
+    sqlx::query("INSERT INTO items VALUES ('1', 'a'), ('2', 'b'), ('3', 'c')")
+        .execute(&pool)
+        .await
+        .unwrap();
+    GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<ItemView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .build()
+        .unwrap()
+}
+
+#[tokio::test]
+async fn list_and_by_pk_compile_and_execute() {
+    let engine = engine().await;
+    let resp = engine
+        .execute(&user(), Request::new("{ items { id name } }"))
+        .await;
+    assert!(!resp.is_err(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    assert_eq!(data["items"].as_array().unwrap().len(), 3);
+
+    let resp = engine
+        .execute(
+            &user(),
+            Request::new(r#"{ items_by_pk(id: "2") { name } }"#),
+        )
+        .await;
+    assert!(!resp.is_err(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    assert_eq!(data["items_by_pk"]["name"], "b");
+}
+
+#[tokio::test]
+async fn where_eq_uses_production_compiler() {
+    let engine = engine().await;
+    let resp = engine
+        .execute(
+            &user(),
+            Request::new(r#"{ items(where: { name: { _eq: "a" } }) { id } }"#),
+        )
+        .await;
+    assert!(!resp.is_err(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    assert_eq!(data["items"].as_array().unwrap().len(), 1);
+    assert_eq!(data["items"][0]["id"], "1");
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[table("client_plan_rows")]
+struct ClientPlanRow {
+    #[id("id")]
+    id: String,
+    priority: i32,
+    completed: bool,
+}
+
+#[derive(Deserialize)]
+struct ClientPlanCorpus {
+    records: Vec<ClientPlanRow>,
+    cases: Vec<ClientPlanCase>,
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct ClientPlanCase {
+    name: String,
+    #[serde(rename = "where")]
+    where_: JsonValue,
+    order_by: JsonValue,
+    limit: i32,
+    offset: i32,
+    expected: Vec<String>,
+}
+
+fn graphql_input(value: &JsonValue) -> String {
+    match value {
+        JsonValue::Null => "null".into(),
+        JsonValue::Bool(value) => value.to_string(),
+        JsonValue::Number(value) => value.to_string(),
+        JsonValue::String(value) => serde_json::to_string(value).expect("serialize string"),
+        JsonValue::Array(values) => format!(
+            "[{}]",
+            values
+                .iter()
+                .map(graphql_input)
+                .collect::<Vec<_>>()
+                .join(", ")
+        ),
+        JsonValue::Object(values) => format!(
+            "{{{}}}",
+            values
+                .iter()
+                .map(|(name, value)| format!("{name}: {}", graphql_input(value)))
+                .collect::<Vec<_>>()
+                .join(", ")
+        ),
+    }
+}
+
+fn graphql_order(value: &JsonValue) -> String {
+    let entries = value.as_array().expect("orderBy array");
+    format!(
+        "[{}]",
+        entries
+            .iter()
+            .map(|entry| {
+                let object = entry.as_object().expect("orderBy object");
+                let (field, direction) = object.iter().next().expect("orderBy field");
+                assert_eq!(object.len(), 1, "orderBy entry must be unambiguous");
+                format!(
+                    "{{{field}: {}}}",
+                    direction.as_str().expect("orderBy direction")
+                )
+            })
+            .collect::<Vec<_>>()
+            .join(", ")
+    )
+}
+
+#[tokio::test]
+async fn portable_query_plan_corpus_matches_sqlite_server_semantics() {
+    let corpus: ClientPlanCorpus =
+        serde_json::from_str(include_str!("../fixtures/client-query-plan-corpus.json"))
+            .expect("parse shared client query-plan corpus");
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE client_plan_rows (id TEXT PRIMARY KEY, priority INTEGER NOT NULL, completed INTEGER NOT NULL)",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+    for record in &corpus.records {
+        sqlx::query("INSERT INTO client_plan_rows (id, priority, completed) VALUES (?, ?, ?)")
+            .bind(&record.id)
+            .bind(record.priority)
+            .bind(record.completed)
+            .execute(&pool)
+            .await
+            .unwrap();
+    }
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<ClientPlanRow>(ModelPermissions::new().grant("user", read().all_columns()))
+        .build()
+        .unwrap();
+
+    for case in corpus.cases {
+        let query = format!(
+            "{{ client_plan_rows(where: {}, order_by: {}, limit: {}, offset: {}) {{ id }} }}",
+            graphql_input(&case.where_),
+            graphql_order(&case.order_by),
+            case.limit,
+            case.offset
+        );
+        let response = engine.execute(&user(), Request::new(query)).await;
+        assert!(!response.is_err(), "{}: {:?}", case.name, response.errors);
+        let data = serde_json::to_value(response.data).unwrap();
+        let actual = data["client_plan_rows"]
+            .as_array()
+            .expect("rows")
+            .iter()
+            .map(|row| row["id"].as_str().expect("string id").to_string())
+            .collect::<Vec<_>>();
+        assert_eq!(actual, case.expected, "{}", case.name);
+    }
+}
diff --git a/tests/graphql_engine/main.rs b/tests/graphql_engine/main.rs
new file mode 100644
index 00000000..4b3fa1fe
--- /dev/null
+++ b/tests/graphql_engine/main.rs
@@ -0,0 +1,195 @@
+//! GraphqlEngine builder validation tests.
+
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+
+use distributed::{
+    graphql::GraphqlEngine, ColumnType, PrimaryKey, RelationshipDef, RelationshipKind, TableColumn,
+    TableKind, TableSchema,
+};
+use sqlx::sqlite::SqlitePoolOptions;
+
+fn simple_schema(model: &str, table: &str) -> TableSchema {
+    TableSchema {
+        model_name: model.into(),
+        table_name: table.into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("id", "id", ColumnType::Text)
+            },
+            TableColumn::new("owner_id", "owner_id", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    }
+}
+
+fn bidirectional_parent_schema() -> TableSchema {
+    TableSchema {
+        model_name: "Parent".into(),
+        table_name: "parents".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("id", "id", ColumnType::Text)
+            },
+            TableColumn::new("name", "name", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "children".into(),
+            kind: RelationshipKind::HasMany,
+            target_model: "Child".into(),
+            foreign_key: Some("parent_id".into()),
+            through: None,
+            target_foreign_key: None,
+        }],
+        kind: TableKind::ReadModel,
+    }
+}
+
+fn bidirectional_child_schema() -> TableSchema {
+    TableSchema {
+        model_name: "Child".into(),
+        table_name: "children".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("id", "id", ColumnType::Text)
+            },
+            TableColumn::new("parent_id", "parent_id", ColumnType::Text),
+            TableColumn::new("name", "name", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "parent".into(),
+            kind: RelationshipKind::BelongsTo,
+            target_model: "Parent".into(),
+            foreign_key: Some("parent_id".into()),
+            through: None,
+            target_foreign_key: None,
+        }],
+        kind: TableKind::ReadModel,
+    }
+}
+
+async fn pool() -> sqlx::SqlitePool {
+    SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap()
+}
+
+#[tokio::test]
+async fn isolated_multi_column_primary_key_builds_with_full_by_pk_tuple() {
+    let schema = TableSchema {
+        model_name: "Composite".into(),
+        table_name: "composites".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("a", "a", ColumnType::Text)
+            },
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("b", "b", ColumnType::Text)
+            },
+        ],
+        primary_key: PrimaryKey::new(["a", "b"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    };
+    let manifest = distributed::DistributedProjectManifest::new("t").table_schema(schema);
+    let engine = GraphqlEngine::from_manifest(&manifest, pool().await)
+        .unwrap()
+        .roles(&["user"])
+        .grant_all("user")
+        .build()
+        .expect("isolated composite-key roots are supported");
+    let sdl = engine.sdl_for_role("user").unwrap();
+    assert!(
+        sdl.contains("composites_by_pk(a: String!, b: String!): Composite"),
+        "composite by-PK root must require the complete key tuple:\n{sdl}"
+    );
+}
+
+#[tokio::test]
+async fn grant_all_builds_and_sdl_for_role() {
+    let schema = simple_schema("Item", "items");
+    let manifest = distributed::DistributedProjectManifest::new("t").table_schema(schema);
+    let engine = GraphqlEngine::from_manifest(&manifest, pool().await)
+        .unwrap()
+        .roles(&["user", "anonymous"])
+        .grant_all("user")
+        .build()
+        .unwrap();
+    let sdl = engine.sdl_for_role("user").expect("role sdl");
+    assert!(sdl.contains("items") || sdl.contains("Item"));
+}
+
+#[tokio::test]
+async fn duplicate_table_name_errors() {
+    let a = simple_schema("A", "items");
+    let b = simple_schema("B", "items");
+    let result = GraphqlEngine::builder(pool().await)
+        .table_schema(a)
+        .table_schema(b)
+        .build();
+    let err = match result {
+        Ok(_) => panic!("expected duplicate table_name error"),
+        Err(e) => e,
+    };
+    assert!(
+        err.to_string().contains("duplicate table_name") || err.to_string().contains("items"),
+        "{err}"
+    );
+}
+
+#[tokio::test]
+async fn unknown_column_in_permission_via_grant_ok() {
+    // grant_all uses all_columns — valid
+    let schema = simple_schema("Item", "items");
+    let manifest = distributed::DistributedProjectManifest::new("t").table_schema(schema);
+    GraphqlEngine::from_manifest(&manifest, pool().await)
+        .unwrap()
+        .grant_all("user")
+        .build()
+        .unwrap();
+}
+
+#[tokio::test]
+async fn build_handles_bidirectional_relationship_schemas() {
+    let manifest = distributed::DistributedProjectManifest::new("t")
+        .table_schema(bidirectional_parent_schema())
+        .table_schema(bidirectional_child_schema());
+    let engine = GraphqlEngine::from_manifest(&manifest, pool().await)
+        .unwrap()
+        .grant_all("user")
+        .build()
+        .unwrap();
+    let sdl = engine.sdl_for_role("user").expect("role sdl");
+    assert!(sdl.contains("children"));
+    assert!(sdl.contains("parent"));
+}
+
+#[tokio::test]
+async fn pure_sql_compile_helper() {
+    use distributed::graphql::naming::root_list_field;
+    let schema = simple_schema("Item", "items");
+    assert_eq!(root_list_field(&schema), "items");
+    let sql = distributed::graphql::sdl::graphql_sdl_for_tables(&[schema]).unwrap();
+    assert!(sql.contains("type Item"));
+}
diff --git a/tests/graphql_harden/authz.rs b/tests/graphql_harden/authz.rs
new file mode 100644
index 00000000..07772775
--- /dev/null
+++ b/tests/graphql_harden/authz.rs
@@ -0,0 +1,344 @@
+//! A* Authorization red-team + related AuthZ e2e.
+//! Drives shipped `GraphqlEngine::execute`.
+
+use async_graphql::Request;
+use distributed::graphql::{claim, col, read, GraphqlEngine, ModelPermissions};
+use distributed::{
+    DistributedProjectManifest, RelationalReadModel, RelationshipDef, RelationshipKind,
+};
+
+use super::common::{
+    engine_all_columns, error_messages, exec_json, seed_orders, session, ChildView, OrderView,
+    ParentView,
+};
+
+/// A1: claim row filter on list (existing harden case).
+#[tokio::test]
+async fn claim_row_filter_isolates_tenants() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user", "anonymous"])
+        .model::<OrderView>(
+            ModelPermissions::new().grant(
+                "user",
+                read()
+                    .all_columns()
+                    .rows(col("customer_id").eq(claim("x-user-id"))),
+            ),
+        )
+        .build()
+        .unwrap();
+
+    let a = session("user", "tenant-a");
+    let data = exec_json(&engine, &a, "{ orders { order_id customer_id } }").await;
+    let orders = data["orders"].as_array().unwrap();
+    assert_eq!(orders.len(), 2);
+    assert!(orders.iter().all(|o| o["customer_id"] == "tenant-a"));
+
+    let b = session("user", "tenant-b");
+    let data = exec_json(&engine, &b, "{ orders { order_id } }").await;
+    assert_eq!(data["orders"].as_array().unwrap().len(), 1);
+
+    // A2: by_pk cross-tenant → null
+    let resp = engine
+        .execute(
+            &b,
+            Request::new(r#"{ orders_by_pk(order_id: "o1") { order_id } }"#),
+        )
+        .await;
+    assert!(resp.errors.is_empty(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    assert!(
+        data["orders_by_pk"].is_null() || data.get("orders_by_pk").is_none(),
+        "cross-tenant by_pk must not leak: {data}"
+    );
+}
+
+/// A2 focused: claim filter on by_pk of own vs other tenant.
+#[tokio::test]
+async fn a2_claim_filter_on_by_pk_isolates_tenants() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(
+            ModelPermissions::new().grant(
+                "user",
+                read()
+                    .all_columns()
+                    .rows(col("customer_id").eq(claim("x-user-id"))),
+            ),
+        )
+        .build()
+        .unwrap();
+
+    let a = session("user", "tenant-a");
+    let data = exec_json(
+        &engine,
+        &a,
+        r#"{ orders_by_pk(order_id: "o1") { order_id customer_id } }"#,
+    )
+    .await;
+    assert_eq!(data["orders_by_pk"]["order_id"], "o1");
+    assert_eq!(data["orders_by_pk"]["customer_id"], "tenant-a");
+
+    let b = session("user", "tenant-b");
+    let data = exec_json(
+        &engine,
+        &b,
+        r#"{ orders_by_pk(order_id: "o1") { order_id } }"#,
+    )
+    .await;
+    assert!(
+        data["orders_by_pk"].is_null(),
+        "tenant-b must not read tenant-a by_pk: {data}"
+    );
+}
+
+/// A3: claim filter on aggregate count.
+#[tokio::test]
+async fn a3_claim_filter_on_aggregate_count() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(
+            ModelPermissions::new().grant(
+                "user",
+                read()
+                    .all_columns()
+                    .aggregations()
+                    .rows(col("customer_id").eq(claim("x-user-id"))),
+            ),
+        )
+        .build()
+        .unwrap();
+
+    let a = session("user", "tenant-a");
+    let data = exec_json(&engine, &a, "{ orders_aggregate { aggregate { count } } }").await;
+    assert_eq!(
+        data["orders_aggregate"]["aggregate"]["count"], 2,
+        "tenant-a has 2 orders: {data}"
+    );
+
+    let b = session("user", "tenant-b");
+    let data = exec_json(&engine, &b, "{ orders_aggregate { aggregate { count } } }").await;
+    assert_eq!(
+        data["orders_aggregate"]["aggregate"]["count"], 1,
+        "tenant-b has 1 order: {data}"
+    );
+}
+
+/// Column allowlist on root list (existing).
+#[tokio::test]
+async fn column_allowlist_denies_ungranted_fields() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["restricted", "user"])
+        .model::<OrderView>(
+            ModelPermissions::new()
+                .grant("restricted", read().columns(["order_id", "status"]))
+                .grant("user", read().all_columns()),
+        )
+        .build()
+        .unwrap();
+
+    let restricted = session("restricted", "tenant-a");
+    let resp = engine
+        .execute(
+            &restricted,
+            Request::new("{ orders { order_id status customer_id } }"),
+        )
+        .await;
+    assert!(
+        !resp.errors.is_empty(),
+        "customer_id must be unknown for restricted role: {:?}",
+        resp.errors
+    );
+    let msgs = error_messages(&resp);
+    assert!(
+        msgs.contains("customer_id") || msgs.contains("unknown field"),
+        "expected unknown field for denied column, got {msgs}"
+    );
+
+    let data = exec_json(&engine, &restricted, "{ orders { order_id status } }").await;
+    let row = &data["orders"][0];
+    assert!(row.get("order_id").is_some());
+    assert!(row.get("customer_id").is_none());
+    assert!(row.get("total_cents").is_none());
+}
+
+/// A5: nested relationship cannot project ungranted child columns.
+#[tokio::test]
+async fn a5_nested_relationship_column_allowlist_denies() {
+    let pool = sqlx::sqlite::SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE parents (parent_id TEXT PRIMARY KEY, name TEXT NOT NULL);
+         CREATE TABLE children (
+            child_id TEXT PRIMARY KEY,
+            parent_id TEXT NOT NULL,
+            name TEXT NOT NULL
+         );
+         INSERT INTO parents VALUES ('p1', 'P');
+         INSERT INTO children VALUES ('c1', 'p1', 'secret-name');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+
+    let mut parent = ParentView::schema().clone();
+    parent.relationships = vec![RelationshipDef {
+        field_name: "children".into(),
+        kind: RelationshipKind::HasMany,
+        target_model: "ChildView".into(),
+        foreign_key: Some("parent_id".into()),
+        through: None,
+        target_foreign_key: None,
+    }];
+    let child = ChildView::schema().clone();
+    let manifest = DistributedProjectManifest::new("rel-authz")
+        .table_schema(parent)
+        .table_schema(child);
+
+    // Parent: all columns; child: only child_id (not name).
+    let engine = GraphqlEngine::from_manifest(&manifest, pool)
+        .unwrap()
+        .roles(&["user"])
+        .permission::<ParentView>("user", read().all_columns())
+        .permission::<ChildView>("user", read().columns(["child_id", "parent_id"]))
+        .build()
+        .expect("build");
+
+    let s = session("user", "u");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new("{ parents { parent_id children { child_id name } } }"),
+        )
+        .await;
+    assert!(
+        !resp.errors.is_empty(),
+        "child.name must be denied for restricted child grants: {:?}",
+        resp.errors
+    );
+    let msgs = error_messages(&resp);
+    assert!(
+        msgs.contains("name") || msgs.contains("unknown field"),
+        "expected unknown field for nested denied column, got {msgs}"
+    );
+
+    // Allowed nested selection still works.
+    let data = exec_json(
+        &engine,
+        &s,
+        "{ parents { parent_id children { child_id } } }",
+    )
+    .await;
+    let children = data["parents"][0]["children"].as_array().unwrap();
+    assert_eq!(children.len(), 1);
+    assert_eq!(children[0]["child_id"], "c1");
+    assert!(children[0].get("name").is_none());
+}
+
+fn parent_child_engine(pool: sqlx::SqlitePool) -> GraphqlEngine {
+    let mut parent = ParentView::schema().clone();
+    parent.relationships = vec![RelationshipDef {
+        field_name: "children".into(),
+        kind: RelationshipKind::HasMany,
+        target_model: "ChildView".into(),
+        foreign_key: Some("parent_id".into()),
+        through: None,
+        target_foreign_key: None,
+    }];
+    let child = ChildView::schema().clone();
+    let manifest = DistributedProjectManifest::new("rel")
+        .table_schema(parent)
+        .table_schema(child);
+
+    GraphqlEngine::from_manifest(&manifest, pool)
+        .unwrap()
+        .roles(&["user"])
+        .grant_all("user")
+        .build()
+        .expect("build")
+}
+
+async fn seed_parents_children() -> sqlx::SqlitePool {
+    let pool = sqlx::sqlite::SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE parents (parent_id TEXT PRIMARY KEY, name TEXT NOT NULL);
+         CREATE TABLE children (
+            child_id TEXT PRIMARY KEY,
+            parent_id TEXT NOT NULL,
+            name TEXT NOT NULL
+         );
+         INSERT INTO parents VALUES ('p1', 'P');
+         INSERT INTO children VALUES ('c1', 'p1', 'C1'), ('c2', 'p1', 'C2');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+    pool
+}
+
+#[tokio::test]
+async fn nested_has_many_relationship_e2e() {
+    let pool = seed_parents_children().await;
+    let engine = parent_child_engine(pool);
+    let s = session("user", "u");
+    let data = exec_json(
+        &engine,
+        &s,
+        "{ parents { parent_id children { child_id name } } }",
+    )
+    .await;
+    let children = data["parents"][0]["children"].as_array().unwrap();
+    assert_eq!(children.len(), 2);
+}
+
+/// Regression: by_pk with nested has_many must keep SQLite `?` binds aligned
+/// (projection subquery LIMIT/OFFSET appear before outer WHERE in SQL text).
+#[tokio::test]
+async fn by_pk_with_nested_children_returns_row() {
+    let pool = seed_parents_children().await;
+    let engine = parent_child_engine(pool);
+    let s = session("user", "u");
+    let data = exec_json(
+        &engine,
+        &s,
+        r#"{ parents_by_pk(parent_id: "p1") { parent_id name children { child_id name } } }"#,
+    )
+    .await;
+    let row = &data["parents_by_pk"];
+    assert!(
+        !row.is_null(),
+        "parents_by_pk must return a row with nested children, got {data}"
+    );
+    assert_eq!(row["parent_id"], "p1");
+    assert_eq!(row["name"], "P");
+    let children = row["children"].as_array().expect("children array");
+    assert_eq!(children.len(), 2, "{data}");
+    let ids: Vec<_> = children
+        .iter()
+        .map(|c| c["child_id"].as_str().unwrap())
+        .collect();
+    assert!(ids.contains(&"c1") && ids.contains(&"c2"), "{data}");
+}
+
+#[tokio::test]
+async fn json_looking_string_column_stays_string() {
+    let pool = seed_orders().await;
+    let engine = engine_all_columns(pool);
+    let s = session("user", "tenant-a");
+    let data = exec_json(&engine, &s, r#"{ orders_by_pk(order_id: "o1") { note } }"#).await;
+    assert!(
+        data["orders_by_pk"]["note"].is_string(),
+        "note must remain string, got {:?}",
+        data["orders_by_pk"]["note"]
+    );
+    assert_eq!(data["orders_by_pk"]["note"], "{\"looks\":\"json\"}");
+}
diff --git a/tests/graphql_harden/common.rs b/tests/graphql_harden/common.rs
new file mode 100644
index 00000000..af87b300
--- /dev/null
+++ b/tests/graphql_harden/common.rs
@@ -0,0 +1,7 @@
+//! Shared fixtures for GraphQL harden / red-team suites.
+//! Re-exports `tests/support/graphql.rs` so existing modules keep `super::common::*`.
+
+#[path = "../support/graphql.rs"]
+mod graphql_support;
+
+pub use graphql_support::*;
diff --git a/tests/graphql_harden/dialect.rs b/tests/graphql_harden/dialect.rs
new file mode 100644
index 00000000..3109d8ef
--- /dev/null
+++ b/tests/graphql_harden/dialect.rs
@@ -0,0 +1,141 @@
+//! Dialect-honest comparison surface (ship-dialect-1).
+//!
+//! SQLite engines must not expose Postgres jsonb operators on
+//! `JSON_comparison_exp`. Failure is GraphQL unknown-field (type honesty),
+//! with compile-time reject remaining as defense-in-depth.
+
+use async_graphql::Request;
+use distributed::graphql::{
+    comparison_op_fields, include_postgres_json_comparison_ops, read, GraphqlEngine,
+    ModelPermissions, POSTGRES_JSON_COMPARISON_OPS,
+};
+use distributed::ReadModel;
+use serde::{Deserialize, Serialize};
+use sqlx::sqlite::SqlitePoolOptions;
+
+use super::common::{assert_no_sql_leak, error_messages, session};
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[table("docs")]
+struct DocView {
+    #[id("doc_id")]
+    doc_id: String,
+    /// JSON column → GraphQL JSON scalar → JSON_comparison_exp.
+    payload: serde_json::Value,
+}
+
+async fn seed_docs() -> sqlx::SqlitePool {
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE docs (doc_id TEXT PRIMARY KEY, payload TEXT NOT NULL);
+         INSERT INTO docs VALUES ('d1', '{\"a\":1}');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+    pool
+}
+
+fn engine(pool: sqlx::SqlitePool) -> GraphqlEngine {
+    GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<DocView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .build()
+        .unwrap()
+}
+
+/// Matrix helper: shared naming policy says SQLite omits PG JSON ops.
+#[test]
+fn naming_matrix_sqlite_omits_pg_json_ops() {
+    assert!(!include_postgres_json_comparison_ops(false));
+    let fields = comparison_op_fields("JSON", false);
+    for op in POSTGRES_JSON_COMPARISON_OPS {
+        assert!(!fields.contains(op), "unexpected {op} in SQLite JSON ops");
+    }
+}
+
+/// SQLite runtime: `_contains` is not a field on JSON_comparison_exp.
+#[tokio::test]
+async fn sqlite_json_contains_is_unknown_field() {
+    let engine = engine(seed_docs().await);
+    let s = session("user", "u");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(r#"{ docs(where: { payload: { _contains: { a: 1 } } }) { doc_id } }"#),
+        )
+        .await;
+    assert!(
+        !resp.errors.is_empty(),
+        "SQLite must not accept _contains on JSON: {:?}",
+        resp.data
+    );
+    assert_no_sql_leak(&resp);
+    let msgs = error_messages(&resp);
+    assert!(
+        msgs.contains("_contains") || msgs.contains("unknown field") || msgs.contains("invalid"),
+        "expected unknown/invalid field for _contains, got {msgs}"
+    );
+}
+
+#[tokio::test]
+async fn sqlite_json_has_key_is_unknown_field() {
+    let engine = engine(seed_docs().await);
+    let s = session("user", "u");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(r#"{ docs(where: { payload: { _has_key: "a" } }) { doc_id } }"#),
+        )
+        .await;
+    assert!(!resp.errors.is_empty());
+    assert_no_sql_leak(&resp);
+    let msgs = error_messages(&resp);
+    assert!(
+        msgs.contains("_has_key") || msgs.contains("unknown field") || msgs.contains("invalid"),
+        "{msgs}"
+    );
+}
+
+#[tokio::test]
+async fn sqlite_json_contained_in_is_unknown_field() {
+    let engine = engine(seed_docs().await);
+    let s = session("user", "u");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(
+                r#"{ docs(where: { payload: { _contained_in: { a: 1, b: 2 } } }) { doc_id } }"#,
+            ),
+        )
+        .await;
+    assert!(!resp.errors.is_empty());
+    assert_no_sql_leak(&resp);
+}
+
+/// Portable `_eq` is a known field on JSON_comparison_exp (SQLite).
+#[tokio::test]
+async fn sqlite_json_eq_is_known_field() {
+    let engine = engine(seed_docs().await);
+    let s = session("user", "u");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(r#"{ docs(where: { payload: { _eq: { a: 1 } } }) { doc_id } }"#),
+        )
+        .await;
+    if !resp.errors.is_empty() {
+        let msgs = error_messages(&resp);
+        assert!(
+            !msgs.contains("unknown field"),
+            "portable _eq must be a known field on JSON_comparison_exp: {msgs}"
+        );
+        assert_no_sql_leak(&resp);
+    } else {
+        let data = serde_json::to_value(&resp.data).unwrap();
+        assert!(data["docs"].as_array().is_some());
+    }
+}
diff --git a/tests/graphql_harden/dos.rs b/tests/graphql_harden/dos.rs
new file mode 100644
index 00000000..7a25cda4
--- /dev/null
+++ b/tests/graphql_harden/dos.rs
@@ -0,0 +1,523 @@
+//! D* Resource-exhaustion red-team suite.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_graphql::Request;
+use distributed::graphql::{read, GraphqlEngine, ModelPermissions};
+
+use super::common::{
+    assert_no_sql_leak, engine_all_columns, error_messages, seed_orders, session, OrderView,
+};
+
+#[tokio::test]
+async fn where_max_depth_rejected() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .max_depth(2)
+        .build()
+        .unwrap();
+    let s = session("user", "tenant-a");
+    let q = r#"{
+      orders(where: { _and: [{ _and: [{ _and: [{ status: { _eq: "open" } }] }] }] }) {
+        order_id
+      }
+    }"#;
+    let resp = engine.execute(&s, Request::new(q)).await;
+    assert!(!resp.errors.is_empty(), "expected max depth error");
+    let msgs = error_messages(&resp);
+    assert!(
+        msgs.contains("depth") || msgs.contains("bad request"),
+        "expected depth-related client error, got {msgs}"
+    );
+    assert_no_sql_leak(&resp);
+}
+
+#[tokio::test]
+async fn graphql_depth_counts_root_and_leaf_fields() {
+    let pool = seed_orders().await;
+    let too_shallow = GraphqlEngine::builder(pool.clone())
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .max_depth(1)
+        .build()
+        .unwrap();
+    let exact = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .max_depth(2)
+        .build()
+        .unwrap();
+    let s = session("user", "tenant-a");
+    let rejected = too_shallow
+        .execute(&s, Request::new("{ orders { order_id } }"))
+        .await;
+    assert!(!rejected.errors.is_empty(), "root plus leaf has depth two");
+    assert_no_sql_leak(&rejected);
+
+    let accepted = exact
+        .execute(&s, Request::new("{ orders { order_id } }"))
+        .await;
+    assert!(accepted.errors.is_empty(), "{accepted:?}");
+}
+
+#[tokio::test]
+async fn max_in_list_rejected() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .max_in_list(3)
+        .build()
+        .unwrap();
+    let s = session("user", "x");
+    let q = r#"{ orders(where: { order_id: { _in: ["a","b","c","d"] } }) { order_id } }"#;
+    let resp = engine.execute(&s, Request::new(q)).await;
+    assert!(
+        !resp.errors.is_empty(),
+        "expected list-too-long style error"
+    );
+    assert_no_sql_leak(&resp);
+}
+
+#[tokio::test]
+async fn limit_clamped_by_max_limit() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .max_limit(1)
+        .default_limit(1)
+        .build()
+        .unwrap();
+    let s = session("user", "x");
+    let resp = engine
+        .execute(&s, Request::new("{ orders(limit: 100) { order_id } }"))
+        .await;
+    assert!(resp.errors.is_empty(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    assert_eq!(data["orders"].as_array().unwrap().len(), 1);
+}
+
+/// D5: wide `_or` list rejected by `max_bool_width`.
+#[tokio::test]
+async fn d5_wide_or_list_rejected_by_max_bool_width() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .max_bool_width(3)
+        .build()
+        .unwrap();
+    let s = session("user", "x");
+    // 4 disjuncts > max_bool_width 3
+    let q = r#"{
+      orders(where: { _or: [
+        { status: { _eq: "open" } },
+        { status: { _eq: "shipped" } },
+        { status: { _eq: "closed" } },
+        { status: { _eq: "x" } }
+      ] }) { order_id }
+    }"#;
+    let resp = engine.execute(&s, Request::new(q)).await;
+    assert!(
+        !resp.errors.is_empty(),
+        "expected breadth limit error for wide _or"
+    );
+    let msgs = error_messages(&resp);
+    assert!(
+        msgs.contains("list too long") || msgs.contains("bad request"),
+        "expected list-too-long style message, got {msgs}"
+    );
+    assert_no_sql_leak(&resp);
+}
+
+/// D5 complementary: `_and` width bound.
+#[tokio::test]
+async fn d5_wide_and_list_rejected_by_max_bool_width() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .max_bool_width(2)
+        .build()
+        .unwrap();
+    let s = session("user", "x");
+    let q = r#"{
+      orders(where: { _and: [
+        { status: { _eq: "open" } },
+        { total_cents: { _gt: 0 } },
+        { order_id: { _neq: "" } }
+      ] }) { order_id }
+    }"#;
+    let resp = engine.execute(&s, Request::new(q)).await;
+    assert!(!resp.errors.is_empty(), "expected _and breadth error");
+    assert_no_sql_leak(&resp);
+}
+
+/// D7: concurrent executes complete without hang; short timeouts map cleanly.
+#[tokio::test]
+async fn d7_concurrent_queries_complete() {
+    let pool = seed_orders().await;
+    let engine = Arc::new(engine_all_columns(pool));
+    let mut handles = Vec::new();
+    for i in 0..8 {
+        let engine = Arc::clone(&engine);
+        handles.push(tokio::spawn(async move {
+            let s = session("user", "x");
+            let q = if i % 2 == 0 {
+                "{ orders { order_id } }"
+            } else {
+                r#"{ orders(where: { status: { _eq: "open" } }) { order_id status } }"#
+            };
+            let resp = engine.execute(&s, Request::new(q)).await;
+            assert_no_sql_leak(&resp);
+            resp.errors.is_empty()
+        }));
+    }
+    for h in handles {
+        assert!(h.await.expect("join"), "concurrent query should succeed");
+    }
+}
+
+/// D7b: concurrent queries under tight statement_timeout still terminate.
+#[tokio::test]
+async fn d7_concurrent_with_timeout_bound_terminates() {
+    use std::path::PathBuf;
+
+    let dir = PathBuf::from(env!("CARGO_TARGET_TMPDIR")).join("graphql_harden_concurrent_to");
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).unwrap();
+    let db = dir.join("orders.db");
+    let url = format!("sqlite:{}?mode=rwc", db.display());
+
+    let pool = sqlx::sqlite::SqlitePoolOptions::new()
+        .max_connections(8)
+        .connect(&url)
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE orders (
+            order_id TEXT PRIMARY KEY,
+            customer_id TEXT NOT NULL,
+            status TEXT NOT NULL,
+            total_cents INTEGER NOT NULL,
+            note TEXT NOT NULL
+        );
+        INSERT INTO orders VALUES ('o1', 't', 'open', 1, 'n');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+
+    let engine = Arc::new(
+        GraphqlEngine::builder(pool)
+            .roles(&["user"])
+            .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+            .statement_timeout(Duration::from_secs(2))
+            .build()
+            .unwrap(),
+    );
+
+    let mut handles = Vec::new();
+    for _ in 0..6 {
+        let engine = Arc::clone(&engine);
+        handles.push(tokio::spawn(async move {
+            let s = session("user", "x");
+            let resp = engine
+                .execute(&s, Request::new("{ orders { order_id } }"))
+                .await;
+            assert_no_sql_leak(&resp);
+            // Success or timeout — both terminate.
+            true
+        }));
+    }
+    let result = tokio::time::timeout(Duration::from_secs(10), async {
+        for h in handles {
+            assert!(h.await.expect("join"));
+        }
+    })
+    .await;
+    assert!(result.is_ok(), "concurrent suite must not hang");
+}
+
+/// Nested has_many fan-out exceeds relationship-aware complexity budget while
+/// staying under max_depth (proves weights, not only depth).
+#[tokio::test]
+async fn d8_nested_has_many_exceeds_complexity_budget() {
+    use distributed::graphql::{read, GraphqlEngine};
+    use distributed::ReadModel;
+    use distributed::{
+        DistributedProjectManifest, RelationalReadModel, RelationshipDef, RelationshipKind,
+    };
+    use serde::{Deserialize, Serialize};
+
+    #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+    #[table("parents")]
+    struct ParentView {
+        #[id("parent_id")]
+        parent_id: String,
+        name: String,
+    }
+    #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+    #[table("children")]
+    struct ChildView {
+        #[id("child_id")]
+        child_id: String,
+        parent_id: String,
+        name: String,
+    }
+    #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+    #[table("grandchildren")]
+    struct GrandView {
+        #[id("grand_id")]
+        grand_id: String,
+        child_id: String,
+        name: String,
+    }
+
+    let pool = sqlx::sqlite::SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE parents (parent_id TEXT PRIMARY KEY, name TEXT NOT NULL);
+         CREATE TABLE children (
+            child_id TEXT PRIMARY KEY, parent_id TEXT NOT NULL, name TEXT NOT NULL
+         );
+         CREATE TABLE grandchildren (
+            grand_id TEXT PRIMARY KEY, child_id TEXT NOT NULL, name TEXT NOT NULL
+         );
+         INSERT INTO parents VALUES ('p1', 'P');
+         INSERT INTO children VALUES ('c1', 'p1', 'C');
+         INSERT INTO grandchildren VALUES ('g1', 'c1', 'G');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+
+    let mut parent = ParentView::schema().clone();
+    parent.relationships = vec![RelationshipDef {
+        field_name: "children".into(),
+        kind: RelationshipKind::HasMany,
+        target_model: "ChildView".into(),
+        foreign_key: Some("parent_id".into()),
+        through: None,
+        target_foreign_key: None,
+    }];
+    let mut child = ChildView::schema().clone();
+    child.relationships = vec![RelationshipDef {
+        field_name: "grandchildren".into(),
+        kind: RelationshipKind::HasMany,
+        target_model: "GrandView".into(),
+        foreign_key: Some("child_id".into()),
+        through: None,
+        target_foreign_key: None,
+    }];
+    let grand = GrandView::schema().clone();
+    let manifest = DistributedProjectManifest::new("cx")
+        .table_schema(parent)
+        .table_schema(child)
+        .table_schema(grand);
+
+    // Default max_complexity (500) + max_depth high enough that depth is not the limit.
+    let engine = GraphqlEngine::from_manifest(&manifest, pool)
+        .unwrap()
+        .roles(&["user"])
+        .max_depth(8)
+        .permission::<ParentView>("user", read().all_columns())
+        .permission::<ChildView>("user", read().all_columns())
+        .permission::<GrandView>("user", read().all_columns())
+        .build()
+        .expect("build");
+
+    let s = session("user", "u");
+    // 3-level has_many: relationship weights push estimated cost above 500.
+    let q = r#"{
+      parents {
+        parent_id
+        children {
+          child_id
+          name
+          grandchildren {
+            grand_id
+            name
+          }
+        }
+      }
+    }"#;
+    let resp = engine.execute(&s, Request::new(q)).await;
+    assert!(
+        !resp.errors.is_empty(),
+        "3-level nested has_many must exceed complexity budget"
+    );
+    assert_no_sql_leak(&resp);
+    let msgs = error_messages(&resp);
+    assert!(
+        msgs.contains("complex") || msgs.contains("bad request"),
+        "expected complexity client error, got {msgs}"
+    );
+}
+
+/// Shallow nest stays under default complexity budget.
+#[tokio::test]
+async fn d8_shallow_nested_has_many_within_budget() {
+    use distributed::graphql::{read, GraphqlEngine};
+    use distributed::ReadModel;
+    use distributed::{
+        DistributedProjectManifest, RelationalReadModel, RelationshipDef, RelationshipKind,
+    };
+    use serde::{Deserialize, Serialize};
+
+    #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+    #[table("parents")]
+    struct ParentView {
+        #[id("parent_id")]
+        parent_id: String,
+        name: String,
+    }
+    #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+    #[table("children")]
+    struct ChildView {
+        #[id("child_id")]
+        child_id: String,
+        parent_id: String,
+        name: String,
+    }
+
+    let pool = sqlx::sqlite::SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE parents (parent_id TEXT PRIMARY KEY, name TEXT NOT NULL);
+         CREATE TABLE children (
+            child_id TEXT PRIMARY KEY, parent_id TEXT NOT NULL, name TEXT NOT NULL
+         );
+         INSERT INTO parents VALUES ('p1', 'P');
+         INSERT INTO children VALUES ('c1', 'p1', 'C');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+
+    let mut parent = ParentView::schema().clone();
+    parent.relationships = vec![RelationshipDef {
+        field_name: "children".into(),
+        kind: RelationshipKind::HasMany,
+        target_model: "ChildView".into(),
+        foreign_key: Some("parent_id".into()),
+        through: None,
+        target_foreign_key: None,
+    }];
+    let child = ChildView::schema().clone();
+    let manifest = DistributedProjectManifest::new("cx2")
+        .table_schema(parent)
+        .table_schema(child);
+    let engine = GraphqlEngine::from_manifest(&manifest, pool)
+        .unwrap()
+        .roles(&["user"])
+        .permission::<ParentView>("user", read().all_columns())
+        .permission::<ChildView>("user", read().all_columns())
+        .build()
+        .expect("build");
+
+    let s = session("user", "u");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new("{ parents { parent_id children { child_id name } } }"),
+        )
+        .await;
+    assert!(
+        resp.errors.is_empty(),
+        "1-level nest must succeed under default budget: {:?}",
+        resp.errors
+    );
+}
+
+/// Explicit low max_complexity rejects modest nests (budget knob works).
+#[tokio::test]
+async fn d8_low_max_complexity_rejects_single_nest() {
+    use distributed::graphql::{read, GraphqlEngine};
+    use distributed::ReadModel;
+    use distributed::{
+        DistributedProjectManifest, RelationalReadModel, RelationshipDef, RelationshipKind,
+    };
+    use serde::{Deserialize, Serialize};
+
+    #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+    #[table("parents")]
+    struct ParentView {
+        #[id("parent_id")]
+        parent_id: String,
+        name: String,
+    }
+    #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+    #[table("children")]
+    struct ChildView {
+        #[id("child_id")]
+        child_id: String,
+        parent_id: String,
+        name: String,
+    }
+
+    let pool = sqlx::sqlite::SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE parents (parent_id TEXT PRIMARY KEY, name TEXT NOT NULL);
+         CREATE TABLE children (
+            child_id TEXT PRIMARY KEY, parent_id TEXT NOT NULL, name TEXT NOT NULL
+         );
+         INSERT INTO parents VALUES ('p1', 'P');
+         INSERT INTO children VALUES ('c1', 'p1', 'C');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+
+    let mut parent = ParentView::schema().clone();
+    parent.relationships = vec![RelationshipDef {
+        field_name: "children".into(),
+        kind: RelationshipKind::HasMany,
+        target_model: "ChildView".into(),
+        foreign_key: Some("parent_id".into()),
+        through: None,
+        target_foreign_key: None,
+    }];
+    let child = ChildView::schema().clone();
+    let manifest = DistributedProjectManifest::new("cx3")
+        .table_schema(parent)
+        .table_schema(child);
+    let engine = GraphqlEngine::from_manifest(&manifest, pool)
+        .unwrap()
+        .roles(&["user"])
+        .max_complexity(20)
+        .max_depth(8)
+        .permission::<ParentView>("user", read().all_columns())
+        .permission::<ChildView>("user", read().all_columns())
+        .build()
+        .expect("build");
+
+    let s = session("user", "u");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new("{ parents { parent_id children { child_id name } } }"),
+        )
+        .await;
+    assert!(
+        !resp.errors.is_empty(),
+        "low budget must reject 1-level nest"
+    );
+    assert_no_sql_leak(&resp);
+    let msgs = error_messages(&resp);
+    assert!(
+        msgs.contains("complex") || msgs.contains("bad request"),
+        "{msgs}"
+    );
+}
diff --git a/tests/graphql_harden/errors.rs b/tests/graphql_harden/errors.rs
new file mode 100644
index 00000000..4e4dea4d
--- /dev/null
+++ b/tests/graphql_harden/errors.rs
@@ -0,0 +1,151 @@
+//! E* Error-leakage red-team suite.
+
+use std::path::PathBuf;
+use std::time::Duration;
+
+use async_graphql::Request;
+use distributed::graphql::{read, GraphqlEngine, ModelPermissions};
+
+use super::common::{
+    assert_no_sql_leak, engine_all_columns, error_messages, extension_code, seed_orders, session,
+    OrderView,
+};
+
+/// Compile errors must not leak SQL.
+#[tokio::test]
+async fn compile_errors_do_not_leak_sql() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .max_in_list(1)
+        .build()
+        .unwrap();
+    let s = session("user", "x");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(r#"{ orders(where: { order_id: { _in: ["a","b"] } }) { order_id } }"#),
+        )
+        .await;
+    assert!(!resp.errors.is_empty());
+    assert_no_sql_leak(&resp);
+}
+
+/// E3: statement timeout → stable TIMEOUT code (existing harden-13 path).
+#[tokio::test]
+async fn e3_sqlite_statement_timeout_returns_timeout_code() {
+    let dir = PathBuf::from(env!("CARGO_TARGET_TMPDIR")).join("graphql_harden_timeout_e3");
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).unwrap();
+    let db = dir.join("orders.db");
+    let url = format!("sqlite:{}?mode=rwc", db.display());
+
+    let pool = sqlx::sqlite::SqlitePoolOptions::new()
+        .max_connections(4)
+        .connect(&url)
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE orders (
+            order_id TEXT PRIMARY KEY,
+            customer_id TEXT NOT NULL,
+            status TEXT NOT NULL,
+            total_cents INTEGER NOT NULL,
+            note TEXT NOT NULL
+        );
+        INSERT INTO orders VALUES
+            ('o1', 'tenant-a', 'open', 100, 'n');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+
+    let mut hold = pool.acquire().await.unwrap();
+    sqlx::query("BEGIN EXCLUSIVE")
+        .execute(&mut *hold)
+        .await
+        .unwrap();
+
+    let engine = GraphqlEngine::builder(pool.clone())
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .statement_timeout(Duration::from_millis(80))
+        .build()
+        .unwrap();
+
+    let resp = engine
+        .execute(
+            &session("user", "x"),
+            Request::new("{ orders { order_id } }"),
+        )
+        .await;
+
+    let _ = sqlx::query("ROLLBACK").execute(&mut *hold).await;
+    drop(hold);
+
+    assert!(
+        !resp.errors.is_empty(),
+        "expected timeout; data={:?}",
+        resp.data
+    );
+    let err = &resp.errors[0];
+    assert!(
+        err.message.to_ascii_lowercase().contains("timeout"),
+        "message should mention timeout: {}",
+        err.message
+    );
+    let code = extension_code(err);
+    assert!(
+        code.as_deref()
+            .map(|c| c.contains("TIMEOUT"))
+            .unwrap_or(false),
+        "expected extensions.code=TIMEOUT, got {code:?}"
+    );
+    assert_no_sql_leak(&resp);
+}
+
+/// E2: execute failure (missing table) maps to INTERNAL without SQL/schema leak.
+#[tokio::test]
+async fn e2_execute_failure_is_internal_without_sql_leak() {
+    let pool = seed_orders().await;
+    let engine = engine_all_columns(pool.clone());
+    // Drop table so the compiler-produced SELECT fails at execute time.
+    sqlx::query("DROP TABLE orders")
+        .execute(&pool)
+        .await
+        .unwrap();
+
+    let s = session("user", "x");
+    let resp = engine
+        .execute(&s, Request::new("{ orders { order_id } }"))
+        .await;
+    assert!(
+        !resp.errors.is_empty(),
+        "expected execute error after drop table"
+    );
+    assert_no_sql_leak(&resp);
+    for e in &resp.errors {
+        let m = e.message.to_ascii_lowercase();
+        assert!(
+            !m.contains("no such table") && !m.contains("orders"),
+            "must not leak table/schema detail: {}",
+            e.message
+        );
+        if let Some(code) = extension_code(e) {
+            assert!(
+                code.contains("INTERNAL") || code.contains("BAD_REQUEST"),
+                "expected INTERNAL (or safe code), got {code}"
+            );
+        }
+    }
+    // Prefer INTERNAL when extensions present.
+    let codes: Vec<_> = resp.errors.iter().filter_map(extension_code).collect();
+    if !codes.is_empty() {
+        assert!(
+            codes.iter().any(|c| c.contains("INTERNAL")),
+            "expected at least one INTERNAL code, got {codes:?}; msgs={}",
+            error_messages(&resp)
+        );
+    }
+}
diff --git a/tests/graphql_harden/inject.rs b/tests/graphql_harden/inject.rs
new file mode 100644
index 00000000..28d2bc15
--- /dev/null
+++ b/tests/graphql_harden/inject.rs
@@ -0,0 +1,166 @@
+//! S* Injection red-team suite — real `GraphqlEngine::execute` only.
+
+use async_graphql::Request;
+use distributed::graphql::{read, GraphqlEngine, ModelPermissions};
+
+use super::common::{
+    assert_no_sql_leak, engine_all_columns, exec_json, seed_orders, session, OrderView,
+};
+
+/// S1: response keys are GraphQL Names; free-form injection cannot reach SQL keys.
+#[tokio::test]
+async fn s1_response_key_field_selection_safe_roundtrip() {
+    let pool = seed_orders().await;
+    let engine = engine_all_columns(pool);
+    let s = session("user", "x");
+    let data = exec_json(&engine, &s, "{ orders { order_id status } }").await;
+    let row = &data["orders"][0];
+    assert!(row.get("order_id").is_some(), "{data}");
+    assert!(row.get("status").is_some(), "{data}");
+    // Where value with quote/SQL metacharacters is bound, not concatenated.
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(r#"{ orders(where: { status: { _eq: "x' OR '1'='1" } }) { order_id } }"#),
+        )
+        .await;
+    assert_no_sql_leak(&resp);
+    // Table still intact and queryable.
+    let data = exec_json(&engine, &s, "{ orders { order_id } }").await;
+    assert_eq!(data["orders"].as_array().unwrap().len(), 3);
+}
+
+/// S2: unknown where keys fail closed under default strict_where (no silent ignore).
+#[tokio::test]
+async fn s2_unknown_where_key_fails_closed_without_sql_leak() {
+    let pool = seed_orders().await;
+    let engine = engine_all_columns(pool);
+    let s = session("user", "x");
+    assert!(engine.strict_where());
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(
+                r#"{ orders(where: { not_a_column: { _eq: "x" }, status: { _eq: "open" } }) { order_id status } }"#,
+            ),
+        )
+        .await;
+    assert_no_sql_leak(&resp);
+    assert!(
+        !resp.errors.is_empty(),
+        "unknown where key must not soft-skip under strict default"
+    );
+}
+
+/// S3: `_like` wildcards are bound parameters, not SQL concatenation.
+#[tokio::test]
+async fn s3_like_wildcards_are_bound_and_safe() {
+    let pool = seed_orders().await;
+    let engine = engine_all_columns(pool);
+    let s = session("user", "x");
+    let data = exec_json(
+        &engine,
+        &s,
+        r#"{ orders(where: { status: { _like: "%pen" } }) { order_id status } }"#,
+    )
+    .await;
+    let orders = data["orders"].as_array().unwrap();
+    assert!(
+        orders
+            .iter()
+            .all(|o| o["status"].as_str().unwrap().contains("pen") || o["status"] == "open"),
+        "{data}"
+    );
+    // Malicious-looking pattern must not cause SQL error leak.
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(
+                r#"{ orders(where: { status: { _like: "'; DROP TABLE orders; --" } }) { order_id } }"#,
+            ),
+        )
+        .await;
+    assert_no_sql_leak(&resp);
+    // Table still queryable.
+    let _ = exec_json(&engine, &s, "{ orders { order_id } }").await;
+}
+
+/// S4: JSON-looking text column stays a GraphQL String (not re-typed).
+#[tokio::test]
+async fn s4_json_looking_string_stays_string() {
+    let pool = seed_orders().await;
+    let engine = engine_all_columns(pool);
+    let s = session("user", "tenant-a");
+    let data = exec_json(&engine, &s, r#"{ orders_by_pk(order_id: "o1") { note } }"#).await;
+    assert!(data["orders_by_pk"]["note"].is_string());
+    assert_eq!(data["orders_by_pk"]["note"], "{\"looks\":\"json\"}");
+}
+
+/// S5: garbage order_by direction coerces safely (no raw SQL direction).
+#[tokio::test]
+async fn s5_order_by_junk_direction_is_safe() {
+    let pool = seed_orders().await;
+    let engine = engine_all_columns(pool);
+    let s = session("user", "x");
+    // Unknown enum may fail GraphQL validation or coerce — either way no SQL leak.
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(
+                r#"{ orders(order_by: [{ status: totally_bogus_direction }]) { order_id status } }"#,
+            ),
+        )
+        .await;
+    assert_no_sql_leak(&resp);
+    if resp.errors.is_empty() {
+        let data = serde_json::to_value(&resp.data).unwrap();
+        assert!(!data["orders"].as_array().unwrap().is_empty());
+    }
+}
+
+/// S6: PK type confusion — wrong type yields error or empty without SQL leak.
+#[tokio::test]
+async fn s6_pk_type_confusion_does_not_leak_sql() {
+    let pool = seed_orders().await;
+    let engine = engine_all_columns(pool);
+    let s = session("user", "x");
+    // order_id is Text; pass a non-string via variable-less int if schema allows —
+    // GraphQL may reject at validation. Use a string that is still safe.
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(r#"{ orders_by_pk(order_id: "'; DROP TABLE orders; --") { order_id } }"#),
+        )
+        .await;
+    assert_no_sql_leak(&resp);
+    // Table intact.
+    let data = exec_json(&engine, &s, "{ orders { order_id } }").await;
+    assert_eq!(data["orders"].as_array().unwrap().len(), 3);
+}
+
+/// S2b: denied where column fails closed under default strict_where.
+#[tokio::test]
+async fn s2_denied_where_column_fails_closed() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["restricted"])
+        .model::<OrderView>(
+            ModelPermissions::new().grant("restricted", read().columns(["order_id", "status"])),
+        )
+        .build()
+        .unwrap();
+    let s = session("restricted", "x");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(
+                r#"{ orders(where: { total_cents: { _eq: 100 }, status: { _eq: "open" } }) { order_id status } }"#,
+            ),
+        )
+        .await;
+    assert_no_sql_leak(&resp);
+    assert!(
+        !resp.errors.is_empty(),
+        "denied where column must not soft-skip under strict default"
+    );
+}
diff --git a/tests/graphql_harden/main.rs b/tests/graphql_harden/main.rs
new file mode 100644
index 00000000..1f6b8c6a
--- /dev/null
+++ b/tests/graphql_harden/main.rs
@@ -0,0 +1,27 @@
+//! GraphQL harden / red-team suite.
+//!
+//! Modules map to threat categories (S/A/D/E/T). Every test drives shipped
+//! `GraphqlEngine::execute` and/or microsvc HTTP — no SQL reimplementation.
+//!
+//! | Module | Coverage |
+//! |---|---|
+//! | `authz` | A* AuthZ (claim list/by_pk/aggregate, column allowlists, nested deny) |
+//! | `inject` | S* injection / key safety |
+//! | `dos` | D* depth, in-list, bool-width, concurrency |
+//! | `errors` | E* leak + TIMEOUT |
+//! | `transport` | T* introspection HTTP, mutation grants, GraphiQL policy |
+//! | `softskip` | Fail-closed where/order contracts (strict_where default) |
+//! | `residual` | A8/A12/S9/E4 residual post-quality-1 review |
+//! | `dialect` | Dialect-honest comparison ops (no PG JSON ops on SQLite) |
+
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+
+mod authz;
+mod common;
+mod dialect;
+mod dos;
+mod errors;
+mod inject;
+mod residual;
+mod softskip;
+mod transport;
diff --git a/tests/graphql_harden/residual.rs b/tests/graphql_harden/residual.rs
new file mode 100644
index 00000000..4fd3f47c
--- /dev/null
+++ b/tests/graphql_harden/residual.rs
@@ -0,0 +1,223 @@
+//! Residual red-team cases from post-quality-1 review (A8/A12/S9/E4/E6).
+
+use async_graphql::Request;
+use distributed::graphql::{claim, col, read, GraphqlEngine, ModelPermissions};
+use distributed::{
+    DistributedProjectManifest, RelationalReadModel, RelationshipDef, RelationshipKind,
+};
+
+use super::common::{
+    assert_no_sql_leak, engine_all_columns, error_messages, extension_code, seed_orders, session,
+    ChildView, OrderView, ParentView,
+};
+
+/// A8: nested has_many without grant on child model → relationship field absent.
+#[tokio::test]
+async fn a8_nested_has_many_without_child_grant_is_unknown_field() {
+    let pool = sqlx::sqlite::SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE parents (parent_id TEXT PRIMARY KEY, name TEXT NOT NULL);
+         CREATE TABLE children (
+            child_id TEXT PRIMARY KEY,
+            parent_id TEXT NOT NULL,
+            name TEXT NOT NULL
+         );
+         INSERT INTO parents VALUES ('p1', 'P');
+         INSERT INTO children VALUES ('c1', 'p1', 'secret');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+
+    let mut parent = ParentView::schema().clone();
+    parent.relationships = vec![RelationshipDef {
+        field_name: "children".into(),
+        kind: RelationshipKind::HasMany,
+        target_model: "ChildView".into(),
+        foreign_key: Some("parent_id".into()),
+        through: None,
+        target_foreign_key: None,
+    }];
+    let child = ChildView::schema().clone();
+    let manifest = DistributedProjectManifest::new("a8")
+        .table_schema(parent)
+        .table_schema(child);
+
+    // Parent granted; child model has **no** permission for this role.
+    let engine = GraphqlEngine::from_manifest(&manifest, pool)
+        .unwrap()
+        .roles(&["user"])
+        .permission::<ParentView>("user", read().all_columns())
+        .build()
+        .expect("build");
+
+    let s = session("user", "u");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new("{ parents { parent_id children { child_id } } }"),
+        )
+        .await;
+    assert!(
+        !resp.errors.is_empty(),
+        "children must be unknown without child grant: {:?}",
+        resp.errors
+    );
+    let msgs = error_messages(&resp);
+    assert!(
+        msgs.contains("children") || msgs.contains("unknown field"),
+        "expected unknown field for ungranted nested rel, got {msgs}"
+    );
+    assert_no_sql_leak(&resp);
+
+    // Parent columns still queryable.
+    let resp = engine
+        .execute(&s, Request::new("{ parents { parent_id name } }"))
+        .await;
+    assert!(resp.errors.is_empty(), "{:?}", resp.errors);
+}
+
+/// A12: relationship where on ungranted target — schema omits rel key from bool_exp
+/// when target has no permission, so GraphQL rejects unknown field (not silent SQL).
+#[tokio::test]
+async fn a12_rel_where_without_target_grant_is_unknown_field() {
+    let pool = sqlx::sqlite::SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE parents (parent_id TEXT PRIMARY KEY, name TEXT NOT NULL);
+         CREATE TABLE children (
+            child_id TEXT PRIMARY KEY,
+            parent_id TEXT NOT NULL,
+            name TEXT NOT NULL
+         );
+         INSERT INTO parents VALUES ('p1', 'P');
+         INSERT INTO children VALUES ('c1', 'p1', 'n');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+
+    let mut parent = ParentView::schema().clone();
+    parent.relationships = vec![RelationshipDef {
+        field_name: "children".into(),
+        kind: RelationshipKind::HasMany,
+        target_model: "ChildView".into(),
+        foreign_key: Some("parent_id".into()),
+        through: None,
+        target_foreign_key: None,
+    }];
+    let child = ChildView::schema().clone();
+    let manifest = DistributedProjectManifest::new("a12")
+        .table_schema(parent)
+        .table_schema(child);
+
+    let engine = GraphqlEngine::from_manifest(&manifest, pool)
+        .unwrap()
+        .roles(&["user"])
+        .permission::<ParentView>("user", read().all_columns())
+        // no ChildView permission
+        .build()
+        .expect("build");
+
+    let s = session("user", "u");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(
+                r#"{ parents(where: { children: { name: { _eq: "n" } } }) { parent_id } }"#,
+            ),
+        )
+        .await;
+    assert!(
+        !resp.errors.is_empty(),
+        "rel where without grant must error"
+    );
+    assert_no_sql_leak(&resp);
+    let msgs = error_messages(&resp);
+    assert!(
+        msgs.contains("children") || msgs.contains("unknown") || msgs.contains("field"),
+        "expected unknown field for ungranted rel where, got {msgs}"
+    );
+}
+
+/// S9 / E6: PG JSON ops on SQLite → BAD_REQUEST / invalid filter, no SQL leak.
+#[tokio::test]
+async fn s9_json_contains_on_sqlite_is_bad_request_without_sql_leak() {
+    let pool = seed_orders().await;
+    // note is a String column; _contains still hits client op path if typed as object
+    // Use a Json column if available — OrderView note is Text. Build engine with all columns
+    // and use _has_key which is only valid for jsonb ops on comparison exp for JSON scalars.
+    // Our comparison_exp for String may still accept _contains in dynamic schema.
+    let engine = engine_all_columns(pool);
+    let s = session("user", "x");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(r#"{ orders(where: { note: { _contains: { a: 1 } } }) { order_id } }"#),
+        )
+        .await;
+    assert!(!resp.errors.is_empty(), "sqlite must reject _contains");
+    assert_no_sql_leak(&resp);
+    let msgs = error_messages(&resp);
+    // sanitize → invalid filter or bad request — never raw SQL operators in client message
+    assert!(
+        !msgs.contains("@>") && !msgs.contains("jsonb"),
+        "must not leak PG operator text: {msgs}"
+    );
+    if let Some(err) = resp.errors.first() {
+        if let Some(code) = extension_code(err) {
+            assert!(
+                code.contains("BAD_REQUEST") || code.contains("bad"),
+                "expected BAD_REQUEST code, got {code}"
+            );
+        }
+    }
+}
+
+/// E4: missing claim header on permission filter → stable client error, no leak.
+#[tokio::test]
+async fn e4_missing_claim_header_is_stable_without_sql_leak() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(
+            ModelPermissions::new().grant(
+                "user",
+                read()
+                    .all_columns()
+                    .rows(col("customer_id").eq(claim("x-user-id"))),
+            ),
+        )
+        .build()
+        .unwrap();
+
+    // Role present but claim header absent.
+    let mut s = distributed::microsvc::Session::new();
+    s.set(distributed::microsvc::ROLE_KEY, "user");
+    // no USER_ID_KEY
+
+    let resp = engine
+        .execute(&s, Request::new("{ orders { order_id } }"))
+        .await;
+    assert!(!resp.errors.is_empty(), "missing claim must fail closed");
+    assert_no_sql_leak(&resp);
+    let msgs = error_messages(&resp);
+    assert!(
+        !msgs.contains("select ") && !msgs.contains("customer_id ="),
+        "must not leak SQL/claim internals: {msgs}"
+    );
+    // Prefer BAD_REQUEST from sanitize path
+    if let Some(err) = resp.errors.first() {
+        if let Some(code) = extension_code(err) {
+            assert!(
+                code.contains("BAD_REQUEST") || code.contains("INTERNAL"),
+                "stable code expected, got {code}"
+            );
+        }
+    }
+}
diff --git a/tests/graphql_harden/softskip.rs b/tests/graphql_harden/softskip.rs
new file mode 100644
index 00000000..1cdfaf0f
--- /dev/null
+++ b/tests/graphql_harden/softskip.rs
@@ -0,0 +1,166 @@
+//! Fail-closed filter/order contracts (strict_where default true).
+//!
+//! **Default (strict):** unknown or ungranted client `where` / `order_by` keys
+//! fail the operation. Failure may come from GraphQL schema validation and/or
+//! compile-time checks — never silent success that ignores the key.
+//!
+//! **Opt-out:** `.strict_where(false)` restores compile-path soft-skip for keys
+//! that reach the walker (not production-recommended). Typed GraphQL may still
+//! reject keys absent from `*_bool_exp` / `*_order_by` before compile runs.
+
+use async_graphql::Request;
+use distributed::graphql::{read, GraphqlEngine, ModelPermissions};
+
+use super::common::{
+    assert_no_sql_leak, engine_all_columns, error_messages, extension_code, seed_orders, session,
+    OrderView,
+};
+
+/// Default builder is fail-closed.
+#[tokio::test]
+async fn default_engine_has_strict_where_on() {
+    let pool = seed_orders().await;
+    let engine = engine_all_columns(pool);
+    assert!(
+        engine.strict_where(),
+        "strict_where must default to true for ship API"
+    );
+}
+
+/// Unknown where key → error under default settings (not silent success).
+#[tokio::test]
+async fn strict_unknown_where_key_errors() {
+    let pool = seed_orders().await;
+    let engine = engine_all_columns(pool);
+    let s = session("user", "x");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(
+                r#"{ orders(where: { not_a_real_column: { _eq: "x" }, status: { _eq: "open" } }) { order_id status } }"#,
+            ),
+        )
+        .await;
+    assert!(
+        !resp.errors.is_empty(),
+        "unknown where key must fail under strict default, got data {:?}",
+        resp.data
+    );
+    assert_no_sql_leak(&resp);
+    let msgs = error_messages(&resp);
+    assert!(
+        msgs.contains("unknown") || msgs.contains("not_a_real_column") || msgs.contains("invalid"),
+        "expected client-safe unknown/invalid error, got {msgs}"
+    );
+}
+
+/// Denied where column → error under default settings.
+#[tokio::test]
+async fn strict_denied_where_column_errors() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["restricted"])
+        .model::<OrderView>(
+            ModelPermissions::new().grant("restricted", read().columns(["order_id", "status"])),
+        )
+        .build()
+        .unwrap();
+    assert!(engine.strict_where());
+    let s = session("restricted", "x");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(
+                r#"{ orders(where: { total_cents: { _eq: 100 }, status: { _eq: "open" } }) { order_id status } }"#,
+            ),
+        )
+        .await;
+    assert!(
+        !resp.errors.is_empty(),
+        "denied where column must fail under strict default"
+    );
+    assert_no_sql_leak(&resp);
+    let msgs = error_messages(&resp);
+    assert!(
+        msgs.contains("total_cents") || msgs.contains("unknown") || msgs.contains("invalid"),
+        "expected unknown/denied field error, got {msgs}"
+    );
+}
+
+/// Junk order_by column → error under default settings.
+#[tokio::test]
+async fn strict_junk_order_by_column_errors() {
+    let pool = seed_orders().await;
+    let engine = engine_all_columns(pool);
+    let s = session("user", "x");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(
+                r#"{ orders(order_by: [{ totally_fake: asc }, { status: desc }]) { order_id status } }"#,
+            ),
+        )
+        .await;
+    assert!(
+        !resp.errors.is_empty(),
+        "junk order_by must fail under strict default"
+    );
+    assert_no_sql_leak(&resp);
+    let msgs = error_messages(&resp);
+    assert!(
+        msgs.contains("totally_fake") || msgs.contains("unknown") || msgs.contains("invalid"),
+        "expected unknown order field error, got {msgs}"
+    );
+}
+
+/// Valid where + order_by still work under strict defaults.
+#[tokio::test]
+async fn strict_valid_where_and_order_still_work() {
+    let pool = seed_orders().await;
+    let engine = engine_all_columns(pool);
+    let s = session("user", "x");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(
+                r#"{ orders(where: { status: { _eq: "open" } }, order_by: [{ status: asc }]) { order_id status } }"#,
+            ),
+        )
+        .await;
+    assert!(resp.errors.is_empty(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    let orders = data["orders"].as_array().unwrap();
+    assert!(!orders.is_empty());
+    assert!(orders.iter().all(|o| o["status"] == "open"), "{data}");
+}
+
+/// Escape hatch: strict_where(false) is opt-in and recorded on the engine.
+#[tokio::test]
+async fn soft_skip_mode_is_opt_in_only() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .strict_where(false)
+        .build()
+        .unwrap();
+    assert!(
+        !engine.strict_where(),
+        "escape hatch must turn strict_where off"
+    );
+    // Typed GraphQL may still reject keys absent from the input type before
+    // compile soft-skip runs; the flag is proven above + pure compile_order_by tests.
+    let s = session("user", "x");
+    let resp = engine
+        .execute(
+            &s,
+            Request::new(r#"{ orders(where: { status: { _eq: "open" } }) { order_id } }"#),
+        )
+        .await;
+    assert!(
+        resp.errors.is_empty(),
+        "valid query still works: {:?}",
+        resp.errors
+    );
+    let _ = extension_code;
+}
diff --git a/tests/graphql_harden/transport.rs b/tests/graphql_harden/transport.rs
new file mode 100644
index 00000000..29fb040e
--- /dev/null
+++ b/tests/graphql_harden/transport.rs
@@ -0,0 +1,353 @@
+//! T* Transport / surface red-team (engine + HTTP).
+
+use std::sync::Arc;
+
+use async_graphql::Request;
+use distributed::graphql::{
+    graphiql_enabled_from_env_vars, read, typed_command, Accepted, GraphqlEngine, ModelPermissions,
+    PreparedCommand,
+};
+use distributed::microsvc::{router, CausalCommandContext, HandlerError, Routes, Service, Session};
+use distributed::{
+    Aggregate, AggregateRepository, Entity, EventRecord, InMemoryRepository, ReadModel,
+};
+use serde::{Deserialize, Serialize};
+use sqlx::sqlite::SqlitePoolOptions;
+use tower::util::ServiceExt;
+
+use super::common::{seed_orders, session, OrderView};
+
+#[derive(Default)]
+struct T4Aggregate {
+    entity: Entity,
+}
+
+impl Aggregate for T4Aggregate {
+    type ReplayError = String;
+
+    fn aggregate_type() -> &'static str {
+        "graphql-harden-t4"
+    }
+
+    fn entity(&self) -> &Entity {
+        &self.entity
+    }
+
+    fn entity_mut(&mut self) -> &mut Entity {
+        &mut self.entity
+    }
+
+    fn replay_event(&mut self, _event: &EventRecord) -> Result<(), Self::ReplayError> {
+        Ok(())
+    }
+}
+
+#[derive(Deserialize, distributed::GraphqlInput)]
+struct T4CommandInput {
+    id: String,
+    name: String,
+}
+
+#[derive(Serialize, distributed::GraphqlOutput)]
+struct T4CommandOutput {
+    id: String,
+    name: String,
+}
+
+async fn t4_command_handler(
+    _context: &CausalCommandContext<'_, T4Aggregate>,
+    input: T4CommandInput,
+) -> Result<PreparedCommand<Accepted<T4CommandOutput>>, HandlerError> {
+    Ok(
+        PreparedCommand::<Accepted<T4CommandOutput>>::prepare(T4CommandOutput {
+            id: input.id,
+            name: input.name,
+        })
+        .expect("fixture output is serializable"),
+    )
+}
+
+/// T3a: anonymous introspection disabled at engine level (existing harden-12).
+#[tokio::test]
+async fn anonymous_introspection_disabled_when_flag_false() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user", "anonymous"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .introspection_for_anonymous(false)
+        .build()
+        .unwrap();
+
+    let anon = Session::new();
+    let resp = engine
+        .execute(&anon, Request::new("{ __schema { queryType { name } } }"))
+        .await;
+    assert!(
+        !resp.errors.is_empty(),
+        "anonymous introspection should fail when flag is false"
+    );
+
+    let user = session("user", "u1");
+    let resp = engine
+        .execute(&user, Request::new("{ __schema { queryType { name } } }"))
+        .await;
+    assert!(
+        resp.errors.is_empty(),
+        "user introspection: {:?}",
+        resp.errors
+    );
+    let data = resp.data.into_json().unwrap();
+    assert_eq!(
+        data["__schema"]["queryType"]["name"].as_str(),
+        Some("Query")
+    );
+}
+
+#[tokio::test]
+async fn anonymous_introspection_allowed_when_flag_true() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user", "anonymous"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .introspection_for_anonymous(true)
+        .build()
+        .unwrap();
+    let resp = engine
+        .execute(
+            &Session::new(),
+            Request::new("{ __schema { queryType { name } } }"),
+        )
+        .await;
+    assert!(resp.errors.is_empty(), "{:?}", resp.errors);
+}
+
+/// T3b: introspection over HTTP with role headers.
+#[tokio::test]
+async fn t3_introspection_over_http_respects_role() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .service_id("rt-http")
+        .roles(&["user", "anonymous"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .introspection_for_anonymous(false)
+        .graphiql(false)
+        .build()
+        .unwrap();
+    let svc = Arc::new(Service::new().named("rt-http").with_graphql(engine));
+    let app = router(svc);
+
+    // Anonymous POST introspection → error
+    let res = app
+        .clone()
+        .oneshot(
+            axum::http::Request::builder()
+                .method("POST")
+                .uri("/graphql")
+                .header("content-type", "application/json")
+                .body(axum::body::Body::from(
+                    r#"{"query":"{ __schema { queryType { name } } }"}"#,
+                ))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(res.status(), axum::http::StatusCode::OK);
+    let bytes = axum::body::to_bytes(res.into_body(), 1024 * 1024)
+        .await
+        .unwrap();
+    let v: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
+    assert!(
+        v.get("errors")
+            .map(|e| !e.as_array().unwrap().is_empty())
+            .unwrap_or(false),
+        "anon HTTP introspection should error: {v}"
+    );
+
+    // Authenticated role can introspect
+    let res = app
+        .oneshot(
+            axum::http::Request::builder()
+                .method("POST")
+                .uri("/graphql")
+                .header("content-type", "application/json")
+                .header("x-role", "user")
+                .body(axum::body::Body::from(
+                    r#"{"query":"{ __schema { queryType { name } } }"}"#,
+                ))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    let bytes = axum::body::to_bytes(res.into_body(), 1024 * 1024)
+        .await
+        .unwrap();
+    let v: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
+    assert!(
+        v.get("errors")
+            .map(|e| e.as_array().unwrap().is_empty())
+            .unwrap_or(true),
+        "user HTTP introspection should succeed: {v}"
+    );
+    assert_eq!(v["data"]["__schema"]["queryType"]["name"], "Query");
+}
+
+/// T4: mutation field absent for role without command grant.
+#[tokio::test]
+async fn t4_mutation_absent_without_command_grant() {
+    #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+    #[table("t4_items")]
+    struct Item {
+        #[id("id")]
+        id: String,
+        name: String,
+    }
+
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE t4_items (id TEXT PRIMARY KEY, name TEXT NOT NULL);
+         INSERT INTO t4_items VALUES ('1', 'n');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+
+    let routes: Routes<AggregateRepository<InMemoryRepository, T4Aggregate>> = Routes::new()
+        .with_repo(AggregateRepository::new(InMemoryRepository::new()))
+        .typed_command(
+            typed_command::<T4CommandInput, Accepted<T4CommandOutput>>("item.create")
+                .field_name("createItem")
+                .roles(["admin"]),
+        )
+        .handle(t4_command_handler);
+    let service = Service::new().named("graphql-harden-t4").routes(routes);
+
+    let engine = GraphqlEngine::builder(pool)
+        .service(&service)
+        .protocol_token_key([0x44; 32])
+        .roles(&["user", "admin"])
+        .model::<Item>(
+            ModelPermissions::new()
+                .grant("user", read().all_columns())
+                .grant("admin", read().all_columns()),
+        )
+        .build()
+        .unwrap();
+
+    // user: mutation createItem must not be available
+    let user = session("user", "u");
+    let resp = engine
+        .execute(
+            &user,
+            Request::new(
+                r#"mutation { createItem(commandId: "019bde25-03a7-7cc5-a8f0-627d2f540001", input: { id: "2", name: "x" }) { id } }"#,
+            ),
+        )
+        .await;
+    assert!(
+        !resp.errors.is_empty(),
+        "user must not invoke admin-only mutation: {:?}",
+        resp.data
+    );
+    let msgs = resp
+        .errors
+        .iter()
+        .map(|e| e.message.to_ascii_lowercase())
+        .collect::<Vec<_>>()
+        .join(" ");
+    assert!(
+        msgs.contains("createitem")
+            || msgs.contains("mutation")
+            || msgs.contains("unknown")
+            || msgs.contains("field"),
+        "expected unknown mutation field for ungranted role, got {msgs}"
+    );
+}
+
+/// Production GraphiQL policy still drives HTTP 405 when off.
+#[tokio::test]
+async fn production_env_policy_disables_graphiql_http_get() {
+    let graphiql = graphiql_enabled_from_env_vars(None, Some("production"), None, None);
+    assert!(!graphiql);
+
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .service_id("prod-gql")
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .graphiql(graphiql)
+        .build()
+        .unwrap();
+    let svc = Arc::new(Service::new().named("prod-gql").with_graphql(engine));
+    let app = router(svc);
+    let res = app
+        .oneshot(
+            axum::http::Request::builder()
+                .method("GET")
+                .uri("/graphql")
+                .body(axum::body::Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(res.status(), axum::http::StatusCode::METHOD_NOT_ALLOWED);
+}
+
+#[cfg(feature = "metrics")]
+#[tokio::test]
+async fn graphql_metrics_increment_on_execute() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .build()
+        .unwrap();
+    let s = session("user", "x");
+    let _ = engine
+        .execute(&s, Request::new("{ orders { order_id } }"))
+        .await;
+    let text = distributed::metrics::prometheus_text();
+    assert!(
+        text.contains("distributed_graphql_request_total"),
+        "metrics text missing graphql series: {text}"
+    );
+    assert!(
+        text.contains("status=\"ok\"") || text.contains("status=\\\"ok\\\""),
+        "ok path should label status=ok: {text}"
+    );
+}
+
+/// BAD_REQUEST from max_bool_width should label metrics status=bad_request (when code present).
+#[cfg(feature = "metrics")]
+#[tokio::test]
+async fn graphql_metrics_bad_request_status_label() {
+    let pool = seed_orders().await;
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .max_bool_width(2)
+        .build()
+        .unwrap();
+    let s = session("user", "x");
+    let wide = (0..5)
+        .map(|i| format!(r#"{{ status: {{ _eq: "open{i}" }} }}"#))
+        .collect::<Vec<_>>()
+        .join(", ");
+    let q = format!(r#"{{ orders(where: {{ _or: [{wide}] }}) {{ order_id }} }}"#);
+    let resp = engine.execute(&s, Request::new(q)).await;
+    assert!(!resp.errors.is_empty(), "expected bool width rejection");
+    let text = distributed::metrics::prometheus_text();
+    assert!(
+        text.contains("status=\"bad_request\"")
+            || text.contains("bad_request")
+            || text.contains("status=\"error\""),
+        "expected bad_request (or error fallback) metric status, got excerpt: {}",
+        text.lines()
+            .filter(|l| l.contains("graphql"))
+            .take(8)
+            .collect::<Vec<_>>()
+            .join("\n")
+    );
+}
diff --git a/tests/graphql_http/main.rs b/tests/graphql_http/main.rs
new file mode 100644
index 00000000..64f41165
--- /dev/null
+++ b/tests/graphql_http/main.rs
@@ -0,0 +1,148 @@
+//! HTTP GraphiQL on/off + session role integration tests.
+
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+
+use std::sync::Arc;
+
+use distributed::graphql::{graphiql_enabled_from_env_vars, read, GraphqlEngine, ModelPermissions};
+use distributed::microsvc::{router, Service};
+use distributed::ReadModel;
+use serde::{Deserialize, Serialize};
+use sqlx::sqlite::SqlitePoolOptions;
+use tower::util::ServiceExt;
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[table("http_items")]
+struct HttpItem {
+    #[id("id")]
+    id: String,
+    name: String,
+}
+
+async fn service_with_graphiql(on: bool) -> Arc<Service> {
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE http_items (id TEXT PRIMARY KEY, name TEXT NOT NULL);
+         INSERT INTO http_items VALUES ('1', 'n');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+    let engine = GraphqlEngine::builder(pool)
+        .service_id("http-gql")
+        .roles(&["user"])
+        .model::<HttpItem>(ModelPermissions::new().grant("user", read().all_columns()))
+        .graphiql(on)
+        .build()
+        .unwrap();
+    Arc::new(Service::new().named("http-gql").with_graphql(engine))
+}
+
+#[tokio::test]
+async fn graphiql_get_200_when_enabled() {
+    let svc = service_with_graphiql(true).await;
+    let app = router(svc);
+    let res = app
+        .oneshot(
+            axum::http::Request::builder()
+                .method("GET")
+                .uri("/graphql")
+                .body(axum::body::Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(res.status(), axum::http::StatusCode::OK);
+    let bytes = axum::body::to_bytes(res.into_body(), 1024 * 1024)
+        .await
+        .unwrap();
+    let body = String::from_utf8_lossy(&bytes);
+    assert!(
+        body.contains("GraphiQL") || body.contains("graphiql") || body.contains("/graphql"),
+        "unexpected body: {body}"
+    );
+}
+
+#[tokio::test]
+async fn graphiql_get_405_when_disabled() {
+    let svc = service_with_graphiql(false).await;
+    let app = router(svc);
+    let res = app
+        .oneshot(
+            axum::http::Request::builder()
+                .method("GET")
+                .uri("/graphql")
+                .body(axum::body::Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(res.status(), axum::http::StatusCode::METHOD_NOT_ALLOWED);
+}
+
+#[tokio::test]
+async fn post_graphql_with_role_returns_data() {
+    let svc = service_with_graphiql(false).await;
+    let app = router(svc);
+    let res = app
+        .oneshot(
+            axum::http::Request::builder()
+                .method("POST")
+                .uri("/graphql")
+                .header("content-type", "application/json")
+                .header("x-role", "user")
+                .body(axum::body::Body::from(
+                    r#"{"query":"{ http_items { id name } }"}"#,
+                ))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(res.status(), axum::http::StatusCode::OK);
+    let bytes = axum::body::to_bytes(res.into_body(), 1024 * 1024)
+        .await
+        .unwrap();
+    let v: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
+    assert!(
+        v["data"]["http_items"]
+            .as_array()
+            .map(|a| !a.is_empty())
+            .unwrap_or(false),
+        "response: {v}"
+    );
+}
+
+/// harden-11: production-like env policy disables GraphiQL on the real HTTP path.
+///
+/// Drives shipped `graphiql_enabled_from_env_vars` (same function scaffold calls via
+/// `graphiql_enabled_from_env`) then mounts the engine with that boolean.
+#[tokio::test]
+async fn production_env_policy_disables_graphiql_http_get() {
+    // Pure policy (no process-env mutation): RUST_ENV=production → graphiql false.
+    let graphiql = graphiql_enabled_from_env_vars(None, Some("production"), None, None);
+    assert!(
+        !graphiql,
+        "RUST_ENV=production must disable GraphiQL in shipped policy"
+    );
+
+    let svc = service_with_graphiql(graphiql).await;
+    let app = router(svc);
+    let res = app
+        .oneshot(
+            axum::http::Request::builder()
+                .method("GET")
+                .uri("/graphql")
+                .body(axum::body::Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        res.status(),
+        axum::http::StatusCode::METHOD_NOT_ALLOWED,
+        "production policy must yield GET /graphql 405 (GraphiQL off)"
+    );
+}
diff --git a/tests/graphql_identity/main.rs b/tests/graphql_identity/main.rs
new file mode 100644
index 00000000..28a48282
--- /dev/null
+++ b/tests/graphql_identity/main.rs
@@ -0,0 +1,886 @@
+//! Always-on identity suite: fixtures F1–F10 against shipped identity path.
+//!
+//! No network / no Zitadel. Synthetic RSA JWKS + JWT via jsonwebtoken.
+
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::{Arc, RwLock};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use axum::http::{HeaderMap, HeaderValue};
+use base64::Engine;
+use distributed::graphql::{
+    extract_bearer, graphql_router, map_claims_to_session, read, resolve_session_sync,
+    strip_identity_headers, AuthError, ClaimMapConfig, GraphqlEngine, IdentityConfig, IdentityMode,
+    IdentityResolver, ModelPermissions, OidcConfig, OidcValidator, DEFAULT_IDENTITY_STRIP_HEADERS,
+};
+use distributed::ReadModel;
+use jsonwebtoken::{encode, Algorithm, EncodingKey, Header};
+use rsa::pkcs1::EncodeRsaPrivateKey;
+use rsa::traits::PublicKeyParts;
+use rsa::{RsaPrivateKey, RsaPublicKey};
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use sqlx::sqlite::SqlitePoolOptions;
+use tower::util::ServiceExt;
+
+// ── RSA fixture helpers ─────────────────────────────────────────────────────
+
+struct TestKeys {
+    encoding: EncodingKey,
+    jwks_json: String,
+    #[allow(dead_code)]
+    kid: String,
+}
+
+fn b64url(data: &[u8]) -> String {
+    base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(data)
+}
+
+fn mint_keys() -> TestKeys {
+    mint_keys_with_kid("test-kid-1")
+}
+
+fn mint_keys_with_kid(kid: &str) -> TestKeys {
+    let mut rng = rand::thread_rng();
+    let private = RsaPrivateKey::new(&mut rng, 2048).expect("rsa key");
+    let public = RsaPublicKey::from(&private);
+    let pem = private.to_pkcs1_pem(rsa::pkcs8::LineEnding::LF).unwrap();
+    let encoding = EncodingKey::from_rsa_pem(pem.as_bytes()).unwrap();
+    let kid = kid.to_string();
+    let n = b64url(&public.n().to_bytes_be());
+    let e = b64url(&public.e().to_bytes_be());
+    let jwks_json = json!({
+        "keys": [{
+            "kty": "RSA",
+            "kid": kid,
+            "alg": "RS256",
+            "use": "sig",
+            "n": n,
+            "e": e
+        }]
+    })
+    .to_string();
+    TestKeys {
+        encoding,
+        jwks_json,
+        kid,
+    }
+}
+
+fn now() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_secs()
+}
+
+fn sign_claims(keys: &TestKeys, claims: Value) -> String {
+    let mut header = Header::new(Algorithm::RS256);
+    header.kid = Some(keys.kid.clone());
+    // jsonwebtoken wants a serializable claims struct — use Map via Value
+    encode(&header, &claims, &keys.encoding).expect("sign")
+}
+
+fn oidc_cfg(keys: &TestKeys) -> OidcConfig {
+    OidcConfig::new("http://localhost:8080", "graphql-api")
+        .with_static_jwks(&keys.jwks_json)
+        .engine_roles(&["admin", "customer", "user"])
+}
+
+const ES256_PRIVATE_KEY: &str = r#"-----BEGIN PRIVATE KEY-----
+MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgWTFfCGljY6aw3Hrt
+kHmPRiazukxPLb6ilpRAewjW8nihRANCAATDskChT+Altkm9X7MI69T3IUmrQU0L
+950IxEzvw/x5BMEINRMrXLBJhqzO9Bm+d6JbqA21YQmd1Kt4RzLJR1W+
+-----END PRIVATE KEY-----"#;
+
+const ES256_X: &str = "w7JAoU_gJbZJvV-zCOvU9yFJq0FNC_edCMRM78P8eQQ";
+const ES256_Y: &str = "wQg1EytcsEmGrM70Gb53oluoDbVhCZ3Uq3hHMslHVb4";
+
+fn headers_from(pairs: &[(&str, &str)]) -> HeaderMap {
+    let mut h = HeaderMap::new();
+    for (k, v) in pairs {
+        h.insert(
+            axum::http::HeaderName::from_bytes(k.as_bytes()).unwrap(),
+            HeaderValue::from_str(v).unwrap(),
+        );
+    }
+    h
+}
+
+fn bearer_headers(token: &str) -> HeaderMap {
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        axum::http::header::AUTHORIZATION,
+        HeaderValue::from_str(&format!("Bearer {token}")).expect("bearer header"),
+    );
+    headers
+}
+
+// ── F1 / F2 claim map (shipped map_claims_to_session) ───────────────────────
+
+#[test]
+fn f1_zitadel_project_roles_session() {
+    let claims = json!({
+        "iss": "http://localhost:8080",
+        "aud": ["graphql-api", "123@graphql"],
+        "sub": "user-a-001",
+        "exp": 4102444800_i64,
+        "urn:zitadel:iam:org:project:roles": {
+            "customer": { "280664559058878577": "zitadel.localhost" },
+            "admin": { "280664559058878577": "zitadel.localhost" }
+        }
+    });
+    let cfg = ClaimMapConfig {
+        engine_roles: vec!["admin".into(), "customer".into(), "user".into()],
+        ..Default::default()
+    };
+    let session = map_claims_to_session(&claims, &cfg).unwrap();
+    assert_eq!(session.user_id(), Some("user-a-001"));
+    assert_eq!(session.role(), Some("admin"));
+    assert_eq!(session.get("x-roles"), Some("admin,customer"));
+}
+
+#[test]
+fn f2_groups_array_session() {
+    let claims = json!({
+        "iss": "http://localhost:8080",
+        "aud": "graphql-api",
+        "sub": "user-b-002",
+        "exp": 4102444800_i64,
+        "groups": ["customer", "other-unmapped"]
+    });
+    let cfg = ClaimMapConfig {
+        engine_roles: vec!["admin".into(), "customer".into(), "user".into()],
+        ..Default::default()
+    };
+    let session = map_claims_to_session(&claims, &cfg).unwrap();
+    assert_eq!(session.user_id(), Some("user-b-002"));
+    assert_eq!(session.role(), Some("customer"));
+    assert_eq!(session.get("x-roles"), Some("customer"));
+}
+
+#[test]
+fn require_role_rejects_signed_token_without_role_claims() {
+    let keys = mint_keys();
+    let token = sign_claims(
+        &keys,
+        json!({
+            "iss": "http://localhost:8080",
+            "aud": "graphql-api",
+            "sub": "user-without-roles",
+            "exp": now() + 3600,
+            "iat": now()
+        }),
+    );
+    let mut cfg = oidc_cfg(&keys);
+    cfg.require_role = true;
+
+    let error = OidcValidator::new(cfg)
+        .validate_and_map(&token)
+        .expect_err("strict role mode must reject the user fallback");
+
+    assert_eq!(error.to_string(), "require_role: no asserted engine role");
+}
+
+#[test]
+fn require_role_rejects_signed_token_with_only_nonmatching_roles() {
+    let keys = mint_keys();
+    let token = sign_claims(
+        &keys,
+        json!({
+            "iss": "http://localhost:8080",
+            "aud": "graphql-api",
+            "sub": "user-with-nonmatching-role",
+            "exp": now() + 3600,
+            "iat": now(),
+            "groups": ["external-role"]
+        }),
+    );
+    let mut cfg = oidc_cfg(&keys);
+    cfg.require_role = true;
+
+    let error = OidcValidator::new(cfg)
+        .validate_and_map(&token)
+        .expect_err("strict role mode must reject non-allowlisted claims");
+
+    assert_eq!(error.to_string(), "require_role: no asserted engine role");
+}
+
+// ── F3–F5 JWT validation rejects ────────────────────────────────────────────
+
+#[test]
+fn f3_alg_none_rejected() {
+    let keys = mint_keys();
+    let validator = OidcValidator::new(oidc_cfg(&keys));
+    // Compact JWT with alg=none (unsigned)
+    let header = b64url(br#"{"alg":"none","typ":"JWT"}"#);
+    let payload = b64url(
+        br#"{"iss":"http://localhost:8080","aud":"graphql-api","sub":"x","exp":4102444800}"#,
+    );
+    let token = format!("{header}.{payload}.");
+    let err = validator.validate_token(&token).unwrap_err();
+    assert!(
+        matches!(
+            err,
+            distributed::graphql::ValidationError::AlgNone
+                | distributed::graphql::ValidationError::AlgNotAllowed
+                | distributed::graphql::ValidationError::Malformed
+                | distributed::graphql::ValidationError::Signature
+        ),
+        "expected alg reject, got {err:?}"
+    );
+}
+
+#[test]
+fn f4_wrong_aud_rejected() {
+    let keys = mint_keys();
+    let claims = json!({
+        "iss": "http://localhost:8080",
+        "aud": "other-api",
+        "sub": "user-a-001",
+        "exp": now() + 3600,
+        "iat": now(),
+        "groups": ["customer"]
+    });
+    let token = sign_claims(&keys, claims);
+    let err = OidcValidator::new(oidc_cfg(&keys))
+        .validate_token(&token)
+        .unwrap_err();
+    assert!(
+        matches!(err, distributed::graphql::ValidationError::Audience)
+            || err.to_string().contains("aud"),
+        "got {err:?}"
+    );
+}
+
+#[test]
+fn f5_expired_rejected() {
+    let keys = mint_keys();
+    let claims = json!({
+        "iss": "http://localhost:8080",
+        "aud": "graphql-api",
+        "sub": "user-a-001",
+        "exp": 1_000_000_000_i64,
+        "iat": 999_999_000_i64,
+        "groups": ["customer"]
+    });
+    let token = sign_claims(&keys, claims);
+    let err = OidcValidator::new(oidc_cfg(&keys))
+        .validate_token(&token)
+        .unwrap_err();
+    assert!(
+        matches!(err, distributed::graphql::ValidationError::Expired),
+        "got {err:?}"
+    );
+}
+
+#[test]
+fn es256_jwks_key_validates_token_when_allowed_by_default() {
+    let kid = "ec-test-kid-1";
+    let jwks_json = json!({
+        "keys": [{
+            "kty": "EC",
+            "kid": kid,
+            "alg": "ES256",
+            "use": "sig",
+            "crv": "P-256",
+            "x": ES256_X,
+            "y": ES256_Y
+        }]
+    })
+    .to_string();
+    let cfg = OidcConfig::new("http://localhost:8080", "graphql-api")
+        .with_static_jwks(jwks_json)
+        .engine_roles(&["admin", "customer", "user"]);
+    let claims = json!({
+        "iss": "http://localhost:8080",
+        "aud": "graphql-api",
+        "sub": "user-ec-001",
+        "exp": now() + 3600,
+        "iat": now(),
+        "groups": ["customer"]
+    });
+    let mut header = Header::new(Algorithm::ES256);
+    header.kid = Some(kid.to_string());
+    let token = encode(
+        &header,
+        &claims,
+        &EncodingKey::from_ec_pem(ES256_PRIVATE_KEY.as_bytes()).unwrap(),
+    )
+    .unwrap();
+
+    let session = OidcValidator::new(cfg).validate_and_map(&token).unwrap();
+    assert_eq!(session.user_id(), Some("user-ec-001"));
+    assert_eq!(session.role(), Some("customer"));
+}
+
+// ── F1 success via full validate_and_map + spoof headers ignored ────────────
+
+#[test]
+fn f1_valid_jwt_maps_session_spoof_headers_ignored() {
+    let keys = mint_keys();
+    let claims = json!({
+        "iss": "http://localhost:8080",
+        "aud": "graphql-api",
+        "sub": "user-a-001",
+        "exp": now() + 3600,
+        "iat": now(),
+        "urn:zitadel:iam:org:project:roles": {
+            "customer": { "1": "x" },
+            "admin": { "1": "x" }
+        }
+    });
+    let token = sign_claims(&keys, claims);
+    let mut cfg = IdentityConfig::oidc_bearer(oidc_cfg(&keys));
+    let headers = headers_from(&[
+        ("authorization", &format!("Bearer {token}")),
+        ("x-user-id", "evil"),
+        ("x-role", "admin"),
+    ]);
+    let session = resolve_session_sync(&headers, &cfg).unwrap();
+    assert_eq!(session.user_id(), Some("user-a-001"));
+    assert_eq!(session.role(), Some("admin"));
+    // Client spoof must not replace sub
+    assert_ne!(session.user_id(), Some("evil"));
+    let _ = &mut cfg;
+}
+
+// ── F6 Hybrid missing Bearer → trust gateway headers ────────────────────────
+
+#[test]
+fn f6_hybrid_missing_bearer_trusts_proxy_headers() {
+    let keys = mint_keys();
+    let cfg = IdentityConfig::hybrid(oidc_cfg(&keys));
+    let headers = headers_from(&[("x-user-id", "gateway-user-9"), ("x-role", "customer")]);
+    let session = resolve_session_sync(&headers, &cfg).unwrap();
+    assert_eq!(session.user_id(), Some("gateway-user-9"));
+    assert_eq!(session.role(), Some("customer"));
+}
+
+// ── F7 Hybrid invalid Bearer → 401, no fallthrough ──────────────────────────
+
+#[test]
+fn f7_hybrid_invalid_bearer_no_proxy_fallthrough() {
+    let keys = mint_keys();
+    let cfg = IdentityConfig::hybrid(oidc_cfg(&keys));
+    let header = b64url(br#"{"alg":"none"}"#);
+    let payload = b64url(br#"{}"#);
+    let bad = format!("{header}.{payload}.");
+    let headers = headers_from(&[
+        ("authorization", &format!("Bearer {bad}")),
+        ("x-user-id", "gateway-user-9"),
+        ("x-role", "admin"),
+    ]);
+    let err = resolve_session_sync(&headers, &cfg).unwrap_err();
+    assert_eq!(err, AuthError::Unauthorized);
+}
+
+// ── F8 / F9 require_auth ────────────────────────────────────────────────────
+
+#[test]
+fn f8_oidc_missing_require_auth_unauthorized() {
+    let keys = mint_keys();
+    let cfg = IdentityConfig::oidc_bearer(oidc_cfg(&keys)); // require_auth true
+    let headers = HeaderMap::new();
+    assert_eq!(
+        resolve_session_sync(&headers, &cfg).unwrap_err(),
+        AuthError::Unauthorized
+    );
+}
+
+#[test]
+fn f9_oidc_missing_require_auth_false_anonymous() {
+    let keys = mint_keys();
+    let mut oidc = oidc_cfg(&keys);
+    oidc.require_auth = false;
+    let cfg = IdentityConfig::oidc_bearer(oidc);
+    let headers = HeaderMap::new();
+    let session = resolve_session_sync(&headers, &cfg).unwrap();
+    assert!(session.user_id().is_none());
+    assert!(session.role().is_none());
+}
+
+// ── F10 TrustedProxy strip ──────────────────────────────────────────────────
+
+#[test]
+fn f10_trusted_proxy_strips_client_identity() {
+    let cfg = IdentityConfig::trusted_proxy();
+    let headers = headers_from(&[
+        ("x-user-id", "attacker"),
+        ("x-role", "admin"),
+        ("x-request-id", "req-1"),
+    ]);
+    let session = resolve_session_sync(&headers, &cfg).unwrap();
+    assert!(session.user_id().is_none(), "x-user-id must be stripped");
+    assert!(session.role().is_none(), "x-role must be stripped");
+    assert_eq!(session.get("x-request-id"), Some("req-1"));
+
+    // Also exercise strip helper directly
+    let stripped = strip_identity_headers(
+        &headers,
+        &DEFAULT_IDENTITY_STRIP_HEADERS
+            .iter()
+            .map(|s| (*s).to_string())
+            .collect::<Vec<_>>(),
+    );
+    assert!(stripped.user_id().is_none());
+}
+
+#[test]
+fn extract_bearer_empty_is_invalid() {
+    let headers = headers_from(&[("authorization", "Bearer ")]);
+    assert_eq!(
+        extract_bearer(&headers).unwrap_err(),
+        AuthError::Unauthorized
+    );
+}
+
+// ── HTTP 401 on real GraphQL router (OidcBearer) ─────────────────────────────
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[table("id_items")]
+struct IdItem {
+    #[id("id")]
+    id: String,
+    owner: String,
+}
+
+async fn engine_with_identity(identity: IdentityConfig) -> Arc<GraphqlEngine> {
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE id_items (id TEXT PRIMARY KEY, owner TEXT NOT NULL);
+         INSERT INTO id_items VALUES ('1', 'user-a-001');
+         INSERT INTO id_items VALUES ('2', 'other');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["customer", "admin", "user"])
+        .model::<IdItem>(
+            ModelPermissions::new()
+                .grant(
+                    "customer",
+                    read().all_columns().rows(
+                        distributed::graphql::col("owner")
+                            .eq(distributed::graphql::claim("x-user-id")),
+                    ),
+                )
+                .grant("admin", read().all_columns())
+                .grant("user", read().all_columns()),
+        )
+        .identity(identity)
+        .graphiql(false)
+        .build()
+        .unwrap();
+    Arc::new(engine)
+}
+
+#[derive(Clone)]
+struct RotatingJwks {
+    body: Arc<RwLock<String>>,
+    fetches: Arc<AtomicUsize>,
+}
+
+async fn serve_rotating_jwks(
+    axum::extract::State(state): axum::extract::State<RotatingJwks>,
+) -> String {
+    state.fetches.fetch_add(1, Ordering::SeqCst);
+    state.body.read().expect("read JWKS response").clone()
+}
+
+async fn authenticated_graphql_status(app: axum::Router, token: &str) -> axum::http::StatusCode {
+    app.oneshot(
+        axum::http::Request::builder()
+            .method("POST")
+            .uri("/graphql")
+            .header("content-type", "application/json")
+            .header("authorization", format!("Bearer {token}"))
+            .body(axum::body::Body::from(r#"{"query":"{ __typename }"}"#))
+            .unwrap(),
+    )
+    .await
+    .unwrap()
+    .status()
+}
+
+#[tokio::test]
+async fn engine_reuses_expires_and_singleflights_rotated_jwks() {
+    let first_keys = mint_keys_with_kid("rotation-kid-1");
+    let rotated_keys = mint_keys_with_kid("rotation-kid-2");
+    let jwks = RotatingJwks {
+        body: Arc::new(RwLock::new(first_keys.jwks_json.clone())),
+        fetches: Arc::new(AtomicUsize::new(0)),
+    };
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("bind JWKS server");
+    let address = listener.local_addr().expect("JWKS server address");
+    let jwks_server = axum::Router::new()
+        .route("/jwks", axum::routing::get(serve_rotating_jwks))
+        .with_state(jwks.clone());
+    let server = tokio::spawn(async move {
+        axum::serve(listener, jwks_server)
+            .await
+            .expect("serve JWKS");
+    });
+
+    let claims = |subject: &str| {
+        json!({
+            "iss": "http://localhost:8080",
+            "aud": "graphql-api",
+            "sub": subject,
+            "exp": now() + 3600,
+            "iat": now(),
+            "groups": ["customer"]
+        })
+    };
+    let first_token = sign_claims(&first_keys, claims("first-key-user"));
+    let rotated_token = sign_claims(&rotated_keys, claims("rotated-key-user"));
+    let mut oidc =
+        OidcConfig::new("http://localhost:8080", "graphql-api").engine_roles(&["customer"]);
+    oidc.jwks_uri = Some(format!("http://{address}/jwks"));
+    let engine = engine_with_identity(IdentityConfig::oidc_bearer(oidc)).await;
+    let app = graphql_router(engine);
+
+    assert_eq!(
+        authenticated_graphql_status(app.clone(), &first_token).await,
+        axum::http::StatusCode::OK
+    );
+    assert_eq!(
+        authenticated_graphql_status(app.clone(), &first_token).await,
+        axum::http::StatusCode::OK
+    );
+    assert_eq!(
+        jwks.fetches.load(Ordering::SeqCst),
+        1,
+        "repeated engine requests must reuse the JWKS cache"
+    );
+
+    *jwks.body.write().expect("rotate JWKS response") = rotated_keys.jwks_json.clone();
+    let (left, right) = tokio::join!(
+        authenticated_graphql_status(app.clone(), &rotated_token),
+        authenticated_graphql_status(app.clone(), &rotated_token),
+    );
+    assert_eq!(left, axum::http::StatusCode::OK);
+    assert_eq!(right, axum::http::StatusCode::OK);
+    assert_eq!(
+        jwks.fetches.load(Ordering::SeqCst),
+        2,
+        "concurrent unknown-kid requests must trigger one refresh"
+    );
+    assert_eq!(
+        authenticated_graphql_status(app, &rotated_token).await,
+        axum::http::StatusCode::OK
+    );
+    assert_eq!(jwks.fetches.load(Ordering::SeqCst), 2);
+
+    jwks.fetches.store(0, Ordering::SeqCst);
+    let mut expiring_oidc =
+        OidcConfig::new("http://localhost:8080", "graphql-api").engine_roles(&["customer"]);
+    expiring_oidc.jwks_uri = Some(format!("http://{address}/jwks"));
+    expiring_oidc.jwks_cache_ttl = std::time::Duration::ZERO;
+    let expiring_engine = engine_with_identity(IdentityConfig::oidc_bearer(expiring_oidc)).await;
+    let expiring_app = graphql_router(expiring_engine);
+    assert_eq!(
+        authenticated_graphql_status(expiring_app.clone(), &rotated_token).await,
+        axum::http::StatusCode::OK
+    );
+    assert_eq!(
+        authenticated_graphql_status(expiring_app, &rotated_token).await,
+        axum::http::StatusCode::OK
+    );
+    assert_eq!(
+        jwks.fetches.load(Ordering::SeqCst),
+        2,
+        "expired JWKS must refresh before the next authenticated request"
+    );
+
+    server.abort();
+}
+
+#[tokio::test]
+async fn identity_resolver_reuses_live_jwks_for_repeated_valid_requests() {
+    let keys = mint_keys_with_kid("resolver-kid");
+    let jwks = RotatingJwks {
+        body: Arc::new(RwLock::new(keys.jwks_json.clone())),
+        fetches: Arc::new(AtomicUsize::new(0)),
+    };
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("bind JWKS server");
+    let address = listener.local_addr().expect("JWKS server address");
+    let server = tokio::spawn({
+        let jwks = jwks.clone();
+        async move {
+            axum::serve(
+                listener,
+                axum::Router::new()
+                    .route("/jwks", axum::routing::get(serve_rotating_jwks))
+                    .with_state(jwks),
+            )
+            .await
+            .expect("serve JWKS");
+        }
+    });
+    let token = sign_claims(
+        &keys,
+        json!({
+            "iss": "http://localhost:8080",
+            "aud": "graphql-api",
+            "sub": "resolver-user",
+            "exp": now() + 3600,
+            "iat": now(),
+            "groups": ["customer"]
+        }),
+    );
+    let mut oidc =
+        OidcConfig::new("http://localhost:8080", "graphql-api").engine_roles(&["customer"]);
+    oidc.jwks_uri = Some(format!("http://{address}/jwks"));
+    let resolver = IdentityResolver::new(IdentityConfig::oidc_bearer(oidc));
+    let headers = bearer_headers(&token);
+
+    resolver
+        .resolve_session(&headers)
+        .await
+        .expect("first resolve");
+    resolver
+        .resolve_session(&headers)
+        .await
+        .expect("second resolve");
+
+    assert_eq!(
+        jwks.fetches.load(Ordering::SeqCst),
+        1,
+        "a reusable resolver must retain its JWKS cache"
+    );
+    server.abort();
+}
+
+#[tokio::test]
+async fn unknown_kid_refreshes_are_cooled_down_until_rotation_can_be_retried() {
+    let first_keys = mint_keys_with_kid("cooldown-current");
+    let unknown_keys = mint_keys_with_kid("cooldown-unknown");
+    let rotated_keys = mint_keys_with_kid("cooldown-rotated");
+    let jwks = RotatingJwks {
+        body: Arc::new(RwLock::new(first_keys.jwks_json.clone())),
+        fetches: Arc::new(AtomicUsize::new(0)),
+    };
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("bind JWKS server");
+    let address = listener.local_addr().expect("JWKS server address");
+    let server = tokio::spawn({
+        let jwks = jwks.clone();
+        async move {
+            axum::serve(
+                listener,
+                axum::Router::new()
+                    .route("/jwks", axum::routing::get(serve_rotating_jwks))
+                    .with_state(jwks),
+            )
+            .await
+            .expect("serve JWKS");
+        }
+    });
+    let claims = |subject: &str| {
+        json!({
+            "iss": "http://localhost:8080",
+            "aud": "graphql-api",
+            "sub": subject,
+            "exp": now() + 3600,
+            "iat": now(),
+            "groups": ["customer"]
+        })
+    };
+    let first_token = sign_claims(&first_keys, claims("current-user"));
+    let unknown_token = sign_claims(&unknown_keys, claims("unknown-user"));
+    let rotated_token = sign_claims(&rotated_keys, claims("rotated-user"));
+    let mut oidc =
+        OidcConfig::new("http://localhost:8080", "graphql-api").engine_roles(&["customer"]);
+    oidc.jwks_uri = Some(format!("http://{address}/jwks"));
+    oidc.jwks_forced_refresh_cooldown = std::time::Duration::from_millis(200);
+    let resolver = IdentityResolver::new(IdentityConfig::oidc_bearer(oidc));
+
+    resolver
+        .resolve_session(&bearer_headers(&first_token))
+        .await
+        .expect("load initial JWKS");
+    assert_eq!(jwks.fetches.load(Ordering::SeqCst), 1);
+
+    assert_eq!(
+        resolver
+            .resolve_session(&bearer_headers(&unknown_token))
+            .await
+            .unwrap_err(),
+        AuthError::Unauthorized
+    );
+    assert_eq!(jwks.fetches.load(Ordering::SeqCst), 2);
+
+    assert_eq!(
+        resolver
+            .resolve_session(&bearer_headers(&rotated_token))
+            .await
+            .unwrap_err(),
+        AuthError::Unauthorized
+    );
+    assert_eq!(
+        jwks.fetches.load(Ordering::SeqCst),
+        2,
+        "a distinct unknown kid must not bypass the forced-refresh cooldown"
+    );
+
+    *jwks.body.write().expect("rotate JWKS response") = rotated_keys.jwks_json.clone();
+    assert_eq!(
+        resolver
+            .resolve_session(&bearer_headers(&rotated_token))
+            .await
+            .unwrap_err(),
+        AuthError::Unauthorized
+    );
+    assert_eq!(jwks.fetches.load(Ordering::SeqCst), 2);
+
+    tokio::time::sleep(std::time::Duration::from_millis(225)).await;
+    resolver
+        .resolve_session(&bearer_headers(&rotated_token))
+        .await
+        .expect("rotation refresh after cooldown");
+    assert_eq!(jwks.fetches.load(Ordering::SeqCst), 3);
+
+    server.abort();
+}
+
+#[tokio::test]
+async fn http_oidc_missing_bearer_returns_401() {
+    let keys = mint_keys();
+    let engine = engine_with_identity(IdentityConfig::oidc_bearer(oidc_cfg(&keys))).await;
+    let app = graphql_router(engine);
+    let res = app
+        .oneshot(
+            axum::http::Request::builder()
+                .method("POST")
+                .uri("/graphql")
+                .header("content-type", "application/json")
+                .body(axum::body::Body::from(r#"{"query":"{ id_items { id } }"}"#))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(res.status(), axum::http::StatusCode::UNAUTHORIZED);
+}
+
+#[tokio::test]
+async fn http_oidc_valid_bearer_isolation() {
+    let keys = mint_keys();
+    let claims = json!({
+        "iss": "http://localhost:8080",
+        "aud": "graphql-api",
+        "sub": "user-a-001",
+        "exp": now() + 3600,
+        "iat": now(),
+        "groups": ["customer"]
+    });
+    let token = sign_claims(&keys, claims);
+    let engine = engine_with_identity(IdentityConfig::oidc_bearer(oidc_cfg(&keys))).await;
+    let app = graphql_router(engine);
+    let res = app
+        .oneshot(
+            axum::http::Request::builder()
+                .method("POST")
+                .uri("/graphql")
+                .header("content-type", "application/json")
+                .header("authorization", format!("Bearer {token}"))
+                .header("x-user-id", "evil") // spoof ignored
+                .body(axum::body::Body::from(
+                    r#"{"query":"{ id_items { id owner } }"}"#,
+                ))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(res.status(), axum::http::StatusCode::OK);
+    let bytes = axum::body::to_bytes(res.into_body(), 1024 * 1024)
+        .await
+        .unwrap();
+    let v: Value = serde_json::from_slice(&bytes).unwrap();
+    let rows = v["data"]["id_items"].as_array().expect("data");
+    assert_eq!(rows.len(), 1, "isolation: only owner rows: {v}");
+    assert_eq!(rows[0]["owner"], "user-a-001");
+}
+
+#[tokio::test]
+async fn http_hybrid_invalid_bearer_401() {
+    let keys = mint_keys();
+    let engine = engine_with_identity(IdentityConfig::hybrid(oidc_cfg(&keys))).await;
+    let app = graphql_router(engine);
+    let res = app
+        .oneshot(
+            axum::http::Request::builder()
+                .method("POST")
+                .uri("/graphql")
+                .header("content-type", "application/json")
+                .header("authorization", "Bearer eyJhbGciOiJub25lIn0.e30.")
+                .header("x-role", "admin")
+                .body(axum::body::Body::from(r#"{"query":"{ id_items { id } }"}"#))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(res.status(), axum::http::StatusCode::UNAUTHORIZED);
+}
+
+#[test]
+fn public_scaffold_default_is_oidc_bearer_not_dev() {
+    // Drives shipped `public_oidc_identity_from_env_vars` (same function scaffold
+    // calls via `public_oidc_identity_from_env`) — D6 never DevHeaders.
+    use distributed::graphql::{
+        public_oidc_identity_from_env_vars, UNSET_OIDC_AUDIENCE, UNSET_OIDC_ISSUER,
+    };
+
+    let unset = public_oidc_identity_from_env_vars(None, None, None, None);
+    assert_eq!(unset.mode, IdentityMode::OidcBearer);
+    assert_ne!(unset.mode, IdentityMode::DevHeaders);
+    assert!(unset.oidc.as_ref().unwrap().require_auth);
+    assert_eq!(unset.oidc.as_ref().unwrap().issuer, UNSET_OIDC_ISSUER);
+    assert_eq!(unset.oidc.as_ref().unwrap().audience, UNSET_OIDC_AUDIENCE);
+
+    // Ambient headers alone must not authenticate under public default.
+    let headers = headers_from(&[("x-user-id", "attacker"), ("x-role", "admin")]);
+    assert_eq!(
+        resolve_session_sync(&headers, &unset).unwrap_err(),
+        AuthError::Unauthorized
+    );
+
+    let configured = public_oidc_identity_from_env_vars(
+        Some("http://localhost:8080"),
+        Some("graphql-api"),
+        None,
+        None,
+    );
+    assert_eq!(configured.mode, IdentityMode::OidcBearer);
+    assert!(configured.oidc.as_ref().unwrap().require_auth);
+    assert_eq!(
+        configured.oidc.as_ref().unwrap().issuer,
+        "http://localhost:8080"
+    );
+}
+
+#[test]
+fn gateway_secret_wrong_is_401() {
+    let mut cfg = IdentityConfig::trusted_proxy();
+    cfg.trusted_proxy.gateway_secret_header = Some(("x-gateway-secret".into(), "s3cret".into()));
+    let headers = headers_from(&[
+        ("x-gateway-secret", "wrong"),
+        ("x-user-id", "u"),
+        ("x-role", "admin"),
+    ]);
+    assert_eq!(
+        resolve_session_sync(&headers, &cfg).unwrap_err(),
+        AuthError::Unauthorized
+    );
+}
diff --git a/tests/graphql_oidc_authentik/docker-compose.yml b/tests/graphql_oidc_authentik/docker-compose.yml
new file mode 100644
index 00000000..36fdb3d5
--- /dev/null
+++ b/tests/graphql_oidc_authentik/docker-compose.yml
@@ -0,0 +1,68 @@
+# Authentik for GraphQL OIDC e2e (local + CI).
+# Bootstrap creates provider/app via API after first boot.
+#   ./scripts/oidc-authentik-up.sh
+services:
+  postgresql:
+    image: docker.io/library/postgres:16-alpine
+    environment:
+      POSTGRES_PASSWORD: authentik
+      POSTGRES_USER: authentik
+      POSTGRES_DB: authentik
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U authentik"]
+      interval: 5s
+      timeout: 5s
+      retries: 15
+    networks: [authentik]
+
+  redis:
+    image: docker.io/library/redis:alpine
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [authentik]
+
+  server:
+    image: ghcr.io/goauthentik/server:2024.10.4
+    command: server
+    environment:
+      AUTHENTIK_SECRET_KEY: "graphqlE2eSecretKeyChangeMe0123456789"
+      AUTHENTIK_REDIS__HOST: redis
+      AUTHENTIK_POSTGRESQL__HOST: postgresql
+      AUTHENTIK_POSTGRESQL__USER: authentik
+      AUTHENTIK_POSTGRESQL__NAME: authentik
+      AUTHENTIK_POSTGRESQL__PASSWORD: authentik
+      AUTHENTIK_BOOTSTRAP_PASSWORD: "akadmin-e2e-pass"
+      AUTHENTIK_BOOTSTRAP_EMAIL: "akadmin@localhost"
+    ports:
+      - "9000:9000"
+    depends_on:
+      postgresql:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    networks: [authentik]
+
+  worker:
+    image: ghcr.io/goauthentik/server:2024.10.4
+    command: worker
+    environment:
+      AUTHENTIK_SECRET_KEY: "graphqlE2eSecretKeyChangeMe0123456789"
+      AUTHENTIK_REDIS__HOST: redis
+      AUTHENTIK_POSTGRESQL__HOST: postgresql
+      AUTHENTIK_POSTGRESQL__USER: authentik
+      AUTHENTIK_POSTGRESQL__NAME: authentik
+      AUTHENTIK_POSTGRESQL__PASSWORD: authentik
+      AUTHENTIK_BOOTSTRAP_PASSWORD: "akadmin-e2e-pass"
+      AUTHENTIK_BOOTSTRAP_EMAIL: "akadmin@localhost"
+    depends_on:
+      postgresql:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    networks: [authentik]
+
+networks:
+  authentik:
diff --git a/tests/graphql_oidc_authentik/main.rs b/tests/graphql_oidc_authentik/main.rs
new file mode 100644
index 00000000..6a9964de
--- /dev/null
+++ b/tests/graphql_oidc_authentik/main.rs
@@ -0,0 +1,167 @@
+//! Authentik live e2e — E1–E8. Gate: `AUTHENTIK_E2E=1`.
+//! Mint: client_credentials ([[specs/query-layer/oidc-authentik]]).
+
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+
+#[path = "../graphql_oidc_common/mod.rs"]
+mod common;
+
+use distributed::graphql::OidcConfig;
+use serde_json::Value;
+
+fn e2e_enabled() -> bool {
+    common::gate_enabled("AUTHENTIK_E2E")
+}
+
+#[tokio::test]
+async fn e0_skips_when_not_gated() {
+    if e2e_enabled() {
+        return;
+    }
+    eprintln!("AUTHENTIK_E2E not set — skip live E1–E8");
+}
+
+#[tokio::test]
+async fn e1_through_e8_live() {
+    if !e2e_enabled() {
+        eprintln!("AUTHENTIK_E2E not set — skip");
+        return;
+    }
+    let iss = std::env::var("OIDC_ISSUER").unwrap_or_default();
+    if iss.is_empty() {
+        panic!(
+            "AUTHENTIK_E2E=1 requires OIDC_ISSUER (run ./scripts/oidc-authentik-up.sh to bootstrap)"
+        );
+    }
+    let jwks_uri = std::env::var("OIDC_JWKS_URI").unwrap_or_default();
+    // GLOBAL issuer mode puts iss at origin; discovery/JWKS live under application slug.
+    let discovery_ok = common::discovery_ready(&iss).await
+        || (!jwks_uri.is_empty() && jwks_reachable(&jwks_uri).await)
+        || common::discovery_ready(&format!(
+            "{}/application/o/graphql-e2e-customer/",
+            iss.trim_end_matches('/')
+        ))
+        .await;
+    assert!(
+        discovery_ok,
+        "Authentik discovery/JWKS not ready (issuer={iss}, jwks={jwks_uri})"
+    );
+    let audience = std::env::var("OIDC_AUDIENCE").expect("OIDC_AUDIENCE");
+    let token_url = std::env::var("AUTHENTIK_TOKEN_URL").unwrap_or_else(|_| {
+        let base = iss.trim_end_matches('/');
+        // Token endpoint is always under /application/o/token/ for Authentik
+        if base.contains("/application/o/") {
+            format!("{base}/../token/").replace(
+                "/application/o/graphql-e2e-customer/../token/",
+                "/application/o/token/",
+            )
+        } else {
+            format!("{base}/application/o/token/")
+        }
+    });
+    let c_id = std::env::var("AUTHENTIK_E2E_CUSTOMER_CLIENT_ID").expect("customer client");
+    let c_sec = std::env::var("AUTHENTIK_E2E_CUSTOMER_CLIENT_SECRET").expect("customer secret");
+    let a_id = std::env::var("AUTHENTIK_E2E_ADMIN_CLIENT_ID").expect("admin client");
+    let a_sec = std::env::var("AUTHENTIK_E2E_ADMIN_CLIENT_SECRET").expect("admin secret");
+
+    if c_sec.is_empty() || a_sec.is_empty() {
+        panic!("AUTHENTIK_E2E=1 requires client secrets from bootstrap");
+    }
+
+    let mut oidc = OidcConfig::new(&iss, &audience).with_extra_audiences([a_id.as_str()]);
+    if audience != c_id {
+        oidc.extra_audiences.push(c_id.clone());
+    }
+    if !jwks_uri.is_empty() {
+        oidc.jwks_uri = Some(jwks_uri);
+    }
+    oidc.claim_map.role_claims = vec!["groups".into(), "roles".into()];
+
+    common::run_e1_through_e8(
+        oidc,
+        async { mint_client_credentials(&token_url, &c_id, &c_sec).await },
+        async { mint_client_credentials(&token_url, &a_id, &a_sec).await },
+    )
+    .await;
+}
+
+async fn jwks_reachable(url: &str) -> bool {
+    let client = match reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(3))
+        .build()
+    {
+        Ok(c) => c,
+        Err(_) => return false,
+    };
+    match client.get(url).send().await {
+        Ok(r) if r.status().is_success() => {
+            let v: Value = r.json().await.unwrap_or(Value::Null);
+            v.get("keys")
+                .and_then(|k| k.as_array())
+                .map(|a| !a.is_empty())
+                .unwrap_or(false)
+        }
+        _ => false,
+    }
+}
+
+async fn mint_client_credentials(
+    token_url: &str,
+    client_id: &str,
+    client_secret: &str,
+) -> Result<(String, String), String> {
+    // Request `groups` so ScopeMapping injects customer/admin for E1 isolation.
+    let body = format!(
+        "grant_type=client_credentials&client_id={}&client_secret={}&scope={}",
+        urlencoding(client_id),
+        urlencoding(client_secret),
+        urlencoding("openid groups profile")
+    );
+    let resp = reqwest::Client::new()
+        .post(token_url)
+        .header("content-type", "application/x-www-form-urlencoded")
+        .body(body)
+        .send()
+        .await
+        .map_err(|e| format!("token: {e}"))?;
+    if !resp.status().is_success() {
+        return Err(format!(
+            "token HTTP {}: {}",
+            resp.status(),
+            resp.text().await.unwrap_or_default()
+        ));
+    }
+    let v: Value = resp.json().await.map_err(|e| e.to_string())?;
+    let token = v
+        .get("access_token")
+        .and_then(|t| t.as_str())
+        .ok_or("no access_token")?
+        .to_string();
+    let sub = decode_sub(&token).ok_or("no sub")?;
+    Ok((token, sub))
+}
+
+fn decode_sub(token: &str) -> Option<String> {
+    let payload = token.split('.').nth(1)?;
+    let mut s = payload.replace('-', "+").replace('_', "/");
+    while s.len() % 4 != 0 {
+        s.push('=');
+    }
+    let bytes =
+        base64::Engine::decode(&base64::engine::general_purpose::STANDARD, s.as_bytes()).ok()?;
+    let v: Value = serde_json::from_slice(&bytes).ok()?;
+    v.get("sub")?.as_str().map(|s| s.to_string())
+}
+
+fn urlencoding(s: &str) -> String {
+    let mut out = String::new();
+    for b in s.bytes() {
+        match b {
+            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
+                out.push(b as char)
+            }
+            _ => out.push_str(&format!("%{b:02X}")),
+        }
+    }
+    out
+}
diff --git a/tests/graphql_oidc_common/mod.rs b/tests/graphql_oidc_common/mod.rs
new file mode 100644
index 00000000..f4088ced
--- /dev/null
+++ b/tests/graphql_oidc_common/mod.rs
@@ -0,0 +1,448 @@
+//! Shared helpers for multi-provider GraphQL OIDC live e2e (E1–E8).
+//! Included via `#[path = "../graphql_oidc_common/mod.rs"] mod common;`
+
+#![allow(dead_code)]
+
+use std::sync::Arc;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use axum::http::{HeaderMap, HeaderValue, StatusCode};
+use base64::Engine as _;
+use distributed::graphql::{
+    graphql_router, read, resolve_session, AuthError, GraphqlEngine, IdentityConfig, IdentityMode,
+    ModelPermissions, OidcConfig, OidcValidator, ValidationError,
+};
+use distributed::ReadModel;
+use jsonwebtoken::{encode, Algorithm, EncodingKey, Header};
+use rsa::pkcs1::EncodeRsaPrivateKey;
+use rsa::traits::PublicKeyParts;
+use rsa::{RsaPrivateKey, RsaPublicKey};
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use sqlx::sqlite::SqlitePoolOptions;
+use tower::util::ServiceExt;
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[table("oidc_e2e_items")]
+pub struct OidcE2eItem {
+    #[id("id")]
+    pub id: String,
+    pub owner: String,
+}
+
+pub fn gate_enabled(name: &str) -> bool {
+    matches!(
+        std::env::var(name)
+            .unwrap_or_default()
+            .to_ascii_lowercase()
+            .as_str(),
+        "1" | "true" | "yes"
+    )
+}
+
+pub async fn discovery_ready(issuer: &str) -> bool {
+    let base = issuer.trim_end_matches('/');
+    let url = format!("{base}/.well-known/openid-configuration");
+    let client = match reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(3))
+        .build()
+    {
+        Ok(c) => c,
+        Err(_) => return false,
+    };
+    client
+        .get(&url)
+        .send()
+        .await
+        .map(|r| r.status().is_success())
+        .unwrap_or(false)
+}
+
+pub async fn engine_oidc(oidc: OidcConfig) -> Arc<GraphqlEngine> {
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE oidc_e2e_items (id TEXT PRIMARY KEY, owner TEXT NOT NULL);
+         INSERT INTO oidc_e2e_items VALUES ('1', 'subject-a');
+         INSERT INTO oidc_e2e_items VALUES ('2', 'subject-b');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+    let mut oidc = oidc;
+    oidc.require_auth = true;
+    oidc.claim_map.engine_roles = vec!["admin".into(), "customer".into(), "user".into()];
+    Arc::new(
+        GraphqlEngine::builder(pool)
+            .roles(&["customer", "admin", "user"])
+            .model::<OidcE2eItem>(
+                ModelPermissions::new()
+                    .grant(
+                        "customer",
+                        read().all_columns().rows(
+                            distributed::graphql::col("owner")
+                                .eq(distributed::graphql::claim("x-user-id")),
+                        ),
+                    )
+                    .grant("admin", read().all_columns())
+                    .grant("user", read().all_columns()),
+            )
+            .identity(IdentityConfig::oidc_bearer(oidc))
+            .graphiql(false)
+            .build()
+            .unwrap(),
+    )
+}
+
+async fn post_graphql(
+    engine: Arc<GraphqlEngine>,
+    headers: HeaderMap,
+    body: &str,
+) -> (StatusCode, Value) {
+    let app = graphql_router(engine);
+    let mut req = axum::http::Request::builder()
+        .method("POST")
+        .uri("/graphql")
+        .header("content-type", "application/json");
+    for (k, v) in headers.iter() {
+        req = req.header(k, v);
+    }
+    let res = app
+        .oneshot(req.body(axum::body::Body::from(body.to_string())).unwrap())
+        .await
+        .unwrap();
+    let status = res.status();
+    let bytes = axum::body::to_bytes(res.into_body(), 1024 * 1024)
+        .await
+        .unwrap();
+    let v: Value = serde_json::from_slice(&bytes).unwrap_or(json_null());
+    (status, v)
+}
+
+fn json_null() -> Value {
+    Value::Null
+}
+
+fn bearer_headers(token: &str) -> HeaderMap {
+    let mut h = HeaderMap::new();
+    h.insert(
+        axum::http::header::AUTHORIZATION,
+        HeaderValue::from_str(&format!("Bearer {token}")).unwrap(),
+    );
+    h
+}
+
+/// Shared E1–E8 against shipped GraphQL HTTP + OidcBearer.
+///
+/// `mint_a` / `mint_b` return access tokens for two distinct subjects (E1/E7).
+/// `oidc` is issuer+audience (+ optional role claim defaults) for validation.
+pub async fn run_e1_through_e8(
+    oidc: OidcConfig,
+    mint_a: impl std::future::Future<Output = Result<(String, String), String>>,
+    mint_b: impl std::future::Future<Output = Result<(String, String), String>>,
+) {
+    let (token_a, sub_a) = mint_a.await.expect("mint A");
+    let (token_b, sub_b) = mint_b.await.expect("mint B");
+    assert_ne!(sub_a, sub_b, "E7 needs two distinct subjects");
+    assert!(!token_a.is_empty() && !token_b.is_empty());
+
+    // Seed DB owners to match minted subjects.
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query("CREATE TABLE oidc_e2e_items (id TEXT PRIMARY KEY, owner TEXT NOT NULL);")
+        .execute(&pool)
+        .await
+        .unwrap();
+    sqlx::query("INSERT INTO oidc_e2e_items VALUES (?1, ?2), (?3, ?4)")
+        .bind("1")
+        .bind(&sub_a)
+        .bind("2")
+        .bind(&sub_b)
+        .execute(&pool)
+        .await
+        .unwrap();
+
+    let mut oidc_cfg = oidc.clone();
+    oidc_cfg.require_auth = true;
+    oidc_cfg.claim_map.engine_roles = vec!["admin".into(), "customer".into(), "user".into()];
+    // Prefer user role schema if IdP omits roles — grant user for isolation tests.
+    let engine = Arc::new(
+        GraphqlEngine::builder(pool)
+            .roles(&["customer", "admin", "user"])
+            .model::<OidcE2eItem>(
+                ModelPermissions::new()
+                    .grant(
+                        "customer",
+                        read().all_columns().rows(
+                            distributed::graphql::col("owner")
+                                .eq(distributed::graphql::claim("x-user-id")),
+                        ),
+                    )
+                    .grant(
+                        "user",
+                        read().all_columns().rows(
+                            distributed::graphql::col("owner")
+                                .eq(distributed::graphql::claim("x-user-id")),
+                        ),
+                    )
+                    .grant("admin", read().all_columns()),
+            )
+            .identity(IdentityConfig::oidc_bearer(oidc_cfg.clone()))
+            .graphiql(false)
+            .build()
+            .unwrap(),
+    );
+
+    // E1 — valid token isolation (must map an engine role + own-row filter)
+    {
+        let session = OidcValidator::new(oidc_cfg.clone())
+            .validate_and_map_async(&token_a)
+            .await
+            .expect("E1 validate");
+        assert_eq!(session.user_id(), Some(sub_a.as_str()), "E1 sub");
+        let role = session.role().map(|s| s.to_string());
+        assert!(
+            role.as_deref() == Some("customer")
+                || role.as_deref() == Some("user")
+                || role.as_deref() == Some("admin"),
+            "E1 token A must map an engine role (customer|user|admin), got {role:?}. \
+             Fix IdP bootstrap so access token carries roles/groups/realm_access.roles \
+             (or Zitadel project roles)."
+        );
+        let (status, v) = post_graphql(
+            Arc::clone(&engine),
+            bearer_headers(&token_a),
+            r#"{"query":"{ oidc_e2e_items { id owner } }"}"#,
+        )
+        .await;
+        assert_eq!(status, StatusCode::OK, "E1 status: {v}");
+        assert!(
+            v.get("errors")
+                .and_then(|e| e.as_array())
+                .map(|a| a.is_empty())
+                .unwrap_or(true),
+            "E1 GraphQL errors (role surface empty?): {v}"
+        );
+        let arr = v["data"]["oidc_e2e_items"]
+            .as_array()
+            .unwrap_or_else(|| panic!("E1 missing data.oidc_e2e_items: {v}"));
+        if role.as_deref() == Some("admin") {
+            // Admin sees all rows; still must execute successfully.
+            assert!(!arr.is_empty(), "E1 admin must see rows: {v}");
+        } else {
+            // customer/user: row isolation to subject A only
+            assert_eq!(arr.len(), 1, "E1 isolation row count: {v}");
+            assert_eq!(
+                arr[0]["owner"].as_str(),
+                Some(sub_a.as_str()),
+                "E1 isolation owner: {v}"
+            );
+        }
+        eprintln!("E1 ok sub={sub_a} role={role:?}");
+    }
+
+    // E2 — spoof headers ignored
+    {
+        let mut h = bearer_headers(&token_a);
+        h.insert("x-user-id", HeaderValue::from_static("evil-spoof"));
+        h.insert("x-role", HeaderValue::from_static("admin"));
+        let session = resolve_session(&h, engine.identity_config())
+            .await
+            .expect("E2 resolve");
+        assert_eq!(session.user_id(), Some(sub_a.as_str()), "E2 spoof ignored");
+        assert_ne!(session.user_id(), Some("evil-spoof"));
+        eprintln!("E2 ok");
+    }
+
+    // E3 — missing Bearer → 401
+    {
+        let (status, _) = post_graphql(
+            Arc::clone(&engine),
+            HeaderMap::new(),
+            r#"{"query":"{ oidc_e2e_items { id } }"}"#,
+        )
+        .await;
+        assert_eq!(status, StatusCode::UNAUTHORIZED, "E3");
+        eprintln!("E3 ok");
+    }
+
+    // E4 — malformed / alg=none → 401
+    {
+        let mut h = HeaderMap::new();
+        h.insert(
+            axum::http::header::AUTHORIZATION,
+            HeaderValue::from_static("Bearer eyJhbGciOiJub25lIn0.e30."),
+        );
+        let (status, _) = post_graphql(
+            Arc::clone(&engine),
+            h,
+            r#"{"query":"{ oidc_e2e_items { id } }"}"#,
+        )
+        .await;
+        assert_eq!(status, StatusCode::UNAUTHORIZED, "E4");
+        eprintln!("E4 ok");
+    }
+
+    // E5 — expired access token → ValidationError::Expired (signed JWT, exp in past).
+    // Uses static JWKS on the shipped validator so failure is expiry, not signature.
+    {
+        let keys = mint_e5_rsa_keys();
+        let now = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_secs() as i64;
+        let claims = json!({
+            "iss": oidc_cfg.issuer,
+            "aud": oidc_cfg.audience,
+            "sub": "expired-subject",
+            "exp": now - 120,
+            "iat": now - 3600,
+            "nbf": now - 3600,
+        });
+        let mut header = Header::new(Algorithm::RS256);
+        header.kid = Some(keys.kid.clone());
+        let expired_token = encode(&header, &claims, &keys.encoding).expect("E5 sign");
+        let mut exp_cfg =
+            OidcConfig::new(&oidc_cfg.issuer, &oidc_cfg.audience).with_static_jwks(&keys.jwks_json);
+        exp_cfg.clock_skew = std::time::Duration::from_secs(0);
+        let err = OidcValidator::new(exp_cfg)
+            .validate_token(&expired_token)
+            .expect_err("E5 must reject expired token");
+        assert!(
+            matches!(err, ValidationError::Expired),
+            "E5 must be Expired (not signature/malformed), got {err:?}"
+        );
+        // HTTP path with engine wired to the same static JWKS → 401
+        let pool = SqlitePoolOptions::new()
+            .connect("sqlite::memory:")
+            .await
+            .unwrap();
+        sqlx::query("CREATE TABLE oidc_e2e_items (id TEXT PRIMARY KEY, owner TEXT NOT NULL);")
+            .execute(&pool)
+            .await
+            .unwrap();
+        let mut http_cfg =
+            OidcConfig::new(&oidc_cfg.issuer, &oidc_cfg.audience).with_static_jwks(&keys.jwks_json);
+        http_cfg.require_auth = true;
+        http_cfg.clock_skew = std::time::Duration::from_secs(0);
+        http_cfg.claim_map.engine_roles = vec!["admin".into(), "customer".into(), "user".into()];
+        let exp_engine = Arc::new(
+            GraphqlEngine::builder(pool)
+                .roles(&["customer", "admin", "user"])
+                .model::<OidcE2eItem>(
+                    ModelPermissions::new().grant("customer", read().all_columns()),
+                )
+                .identity(IdentityConfig::oidc_bearer(http_cfg))
+                .graphiql(false)
+                .build()
+                .unwrap(),
+        );
+        let (status, _) = post_graphql(
+            exp_engine,
+            bearer_headers(&expired_token),
+            r#"{"query":"{ oidc_e2e_items { id } }"}"#,
+        )
+        .await;
+        assert_eq!(status, StatusCode::UNAUTHORIZED, "E5 HTTP");
+        eprintln!("E5 ok (Expired + HTTP 401)");
+    }
+
+    // E6 — wrong audience config rejects valid token
+    {
+        let mut bad = oidc_cfg.clone();
+        bad.audience = "definitely-wrong-audience-xyz".into();
+        // Multi-client configs carry extra_audiences (azp) — clear them so E6 is honest.
+        bad.extra_audiences.clear();
+        let err = OidcValidator::new(bad)
+            .validate_and_map_async(&token_a)
+            .await;
+        assert!(err.is_err(), "E6 wrong aud must fail");
+        assert!(
+            matches!(err, Err(ValidationError::Audience))
+                || err
+                    .as_ref()
+                    .err()
+                    .map(|e| e.to_string().contains("audience"))
+                    .unwrap_or(false),
+            "E6 expected Audience error, got {err:?}"
+        );
+        eprintln!("E6 ok");
+    }
+
+    // E7 — second subject distinct session
+    {
+        let session_b = OidcValidator::new(oidc_cfg.clone())
+            .validate_and_map_async(&token_b)
+            .await
+            .expect("E7 validate B");
+        assert_eq!(session_b.user_id(), Some(sub_b.as_str()), "E7");
+        assert_ne!(session_b.user_id(), Some(sub_a.as_str()));
+        eprintln!("E7 ok sub_b={sub_b}");
+    }
+
+    // E8 — no token material in error bodies for auth failures
+    {
+        let mut h = HeaderMap::new();
+        let secret = format!("Bearer {token_a}");
+        h.insert(
+            axum::http::header::AUTHORIZATION,
+            HeaderValue::from_str("Bearer not-a-jwt").unwrap(),
+        );
+        let (status, v) = post_graphql(
+            Arc::clone(&engine),
+            h,
+            r#"{"query":"{ oidc_e2e_items { id } }"}"#,
+        )
+        .await;
+        assert_eq!(status, StatusCode::UNAUTHORIZED, "E8 status");
+        let body = v.to_string();
+        assert!(
+            !body.contains(token_a.as_str())
+                && !body.contains(secret.trim_start_matches("Bearer ")),
+            "E8 must not echo tokens: {body}"
+        );
+        eprintln!("E8 ok");
+    }
+
+    let _ = IdentityMode::OidcBearer;
+    let _ = AuthError::Unauthorized;
+}
+
+// ── E5 helpers: signed expired JWT against static JWKS (shipped validate path) ─
+
+struct E5Keys {
+    encoding: EncodingKey,
+    jwks_json: String,
+    kid: String,
+}
+
+fn mint_e5_rsa_keys() -> E5Keys {
+    let mut rng = rand::thread_rng();
+    let private = RsaPrivateKey::new(&mut rng, 2048).expect("rsa");
+    let public = RsaPublicKey::from(&private);
+    let pem = private.to_pkcs1_pem(rsa::pkcs8::LineEnding::LF).unwrap();
+    let encoding = EncodingKey::from_rsa_pem(pem.as_bytes()).unwrap();
+    let kid = "e5-expired-kid".to_string();
+    let n = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(public.n().to_bytes_be());
+    let e = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(public.e().to_bytes_be());
+    let jwks_json = json!({
+        "keys": [{
+            "kty": "RSA",
+            "kid": kid,
+            "alg": "RS256",
+            "use": "sig",
+            "n": n,
+            "e": e
+        }]
+    })
+    .to_string();
+    E5Keys {
+        encoding,
+        jwks_json,
+        kid,
+    }
+}
diff --git a/tests/graphql_oidc_keycloak/docker-compose.yml b/tests/graphql_oidc_keycloak/docker-compose.yml
new file mode 100644
index 00000000..861927d9
--- /dev/null
+++ b/tests/graphql_oidc_keycloak/docker-compose.yml
@@ -0,0 +1,18 @@
+# Keycloak for GraphQL OIDC e2e (local + CI).
+#   ./scripts/oidc-keycloak-up.sh
+#   set -a && source graphql-oidc-keycloak.env && set +a
+#   cargo test --test graphql_oidc_keycloak --features graphql,sqlite,metrics
+services:
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.0
+    command: ["start-dev", "--import-realm", "--http-port=8080"]
+    environment:
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+      KC_HTTP_ENABLED: "true"
+      KC_HOSTNAME_STRICT: "false"
+      KC_HEALTH_ENABLED: "true"
+    ports:
+      - "8081:8080"
+    volumes:
+      - ./realm-export.json:/opt/keycloak/data/import/realm-export.json:ro
diff --git a/tests/graphql_oidc_keycloak/main.rs b/tests/graphql_oidc_keycloak/main.rs
new file mode 100644
index 00000000..357edf90
--- /dev/null
+++ b/tests/graphql_oidc_keycloak/main.rs
@@ -0,0 +1,125 @@
+//! Keycloak live e2e — E1–E8. Gate: `KEYCLOAK_E2E=1`.
+//! Mint: client_credentials ([[specs/query-layer/oidc-keycloak]]).
+
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+
+#[path = "../graphql_oidc_common/mod.rs"]
+mod common;
+
+use distributed::graphql::OidcConfig;
+use serde_json::Value;
+
+fn e2e_enabled() -> bool {
+    common::gate_enabled("KEYCLOAK_E2E")
+}
+
+#[tokio::test]
+async fn e0_skips_when_not_gated() {
+    if e2e_enabled() {
+        return;
+    }
+    eprintln!("KEYCLOAK_E2E not set — skip live E1–E8");
+}
+
+#[tokio::test]
+async fn e1_through_e8_live() {
+    if !e2e_enabled() {
+        eprintln!("KEYCLOAK_E2E not set — skip");
+        return;
+    }
+    let iss = std::env::var("OIDC_ISSUER").expect("OIDC_ISSUER");
+    assert!(
+        common::discovery_ready(&iss).await,
+        "Keycloak discovery not ready at {iss}"
+    );
+    let audience = std::env::var("OIDC_AUDIENCE").expect("OIDC_AUDIENCE");
+
+    let cust_id = std::env::var("KEYCLOAK_E2E_CUSTOMER_CLIENT_ID").expect("customer client");
+    let cust_sec = std::env::var("KEYCLOAK_E2E_CUSTOMER_CLIENT_SECRET").expect("customer secret");
+    let adm_id = std::env::var("KEYCLOAK_E2E_ADMIN_CLIENT_ID").expect("admin client");
+    let adm_sec = std::env::var("KEYCLOAK_E2E_ADMIN_CLIENT_SECRET").expect("admin secret");
+
+    // Keycloak client_credentials tokens typically omit `aud` and set `azp` to the
+    // client id — accept both customer and admin clients for E1–E8 multi-subject.
+    let mut oidc = OidcConfig::new(&iss, &audience).with_extra_audiences([adm_id.as_str()]);
+    if audience != cust_id {
+        oidc.extra_audiences.push(cust_id.clone());
+    }
+    oidc.claim_map.role_claims = vec!["realm_access.roles".into(), "groups".into(), "roles".into()];
+
+    common::run_e1_through_e8(
+        oidc,
+        async {
+            let (t, sub) = mint_client_credentials(&iss, &cust_id, &cust_sec).await?;
+            Ok((t, sub))
+        },
+        async {
+            let (t, sub) = mint_client_credentials(&iss, &adm_id, &adm_sec).await?;
+            Ok((t, sub))
+        },
+    )
+    .await;
+}
+
+async fn mint_client_credentials(
+    issuer: &str,
+    client_id: &str,
+    client_secret: &str,
+) -> Result<(String, String), String> {
+    let token_url = format!(
+        "{}/protocol/openid-connect/token",
+        issuer.trim_end_matches('/')
+    );
+    let body = format!(
+        "grant_type=client_credentials&client_id={}&client_secret={}",
+        urlencoding(client_id),
+        urlencoding(client_secret)
+    );
+    let resp = reqwest::Client::new()
+        .post(&token_url)
+        .header("content-type", "application/x-www-form-urlencoded")
+        .body(body)
+        .send()
+        .await
+        .map_err(|e| format!("token: {e}"))?;
+    if !resp.status().is_success() {
+        return Err(format!(
+            "token HTTP {}: {}",
+            resp.status(),
+            resp.text().await.unwrap_or_default()
+        ));
+    }
+    let v: Value = resp.json().await.map_err(|e| e.to_string())?;
+    let token = v
+        .get("access_token")
+        .and_then(|t| t.as_str())
+        .ok_or("no access_token")?
+        .to_string();
+    let sub = decode_sub(&token).ok_or("no sub in token")?;
+    Ok((token, sub))
+}
+
+fn decode_sub(token: &str) -> Option<String> {
+    let payload = token.split('.').nth(1)?;
+    let mut s = payload.replace('-', "+").replace('_', "/");
+    while s.len() % 4 != 0 {
+        s.push('=');
+    }
+    let bytes =
+        base64::Engine::decode(&base64::engine::general_purpose::STANDARD, s.as_bytes()).ok()?;
+    let v: Value = serde_json::from_slice(&bytes).ok()?;
+    v.get("sub")?.as_str().map(|s| s.to_string())
+}
+
+fn urlencoding(s: &str) -> String {
+    let mut out = String::new();
+    for b in s.bytes() {
+        match b {
+            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
+                out.push(b as char)
+            }
+            _ => out.push_str(&format!("%{b:02X}")),
+        }
+    }
+    out
+}
diff --git a/tests/graphql_oidc_keycloak/realm-export.json b/tests/graphql_oidc_keycloak/realm-export.json
new file mode 100644
index 00000000..3d9d4c37
--- /dev/null
+++ b/tests/graphql_oidc_keycloak/realm-export.json
@@ -0,0 +1,83 @@
+{
+  "realm": "graphql",
+  "enabled": true,
+  "sslRequired": "none",
+  "registrationAllowed": false,
+  "roles": {
+    "realm": [
+      { "name": "customer", "description": "GraphQL customer" },
+      { "name": "admin", "description": "GraphQL admin" },
+      { "name": "user", "description": "GraphQL user" }
+    ]
+  },
+  "clients": [
+    {
+      "clientId": "graphql-e2e-customer",
+      "name": "graphql-e2e-customer",
+      "enabled": true,
+      "protocol": "openid-connect",
+      "publicClient": false,
+      "secret": "customer-secret-e2e",
+      "serviceAccountsEnabled": true,
+      "directAccessGrantsEnabled": false,
+      "standardFlowEnabled": false,
+      "fullScopeAllowed": true,
+      "protocolMappers": [
+        {
+          "name": "realm-roles",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-realm-role-mapper",
+          "consentRequired": false,
+          "config": {
+            "multivalued": "true",
+            "user.attribute": "foo",
+            "access.token.claim": "true",
+            "claim.name": "realm_access.roles",
+            "jsonType.label": "String"
+          }
+        }
+      ]
+    },
+    {
+      "clientId": "graphql-e2e-admin",
+      "name": "graphql-e2e-admin",
+      "enabled": true,
+      "protocol": "openid-connect",
+      "publicClient": false,
+      "secret": "admin-secret-e2e",
+      "serviceAccountsEnabled": true,
+      "directAccessGrantsEnabled": false,
+      "standardFlowEnabled": false,
+      "fullScopeAllowed": true,
+      "protocolMappers": [
+        {
+          "name": "realm-roles",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-realm-role-mapper",
+          "consentRequired": false,
+          "config": {
+            "multivalued": "true",
+            "user.attribute": "foo",
+            "access.token.claim": "true",
+            "claim.name": "realm_access.roles",
+            "jsonType.label": "String"
+          }
+        }
+      ]
+    }
+  ],
+  "users": [
+    {
+      "username": "service-account-graphql-e2e-customer",
+      "enabled": true,
+      "serviceAccountClientId": "graphql-e2e-customer",
+      "realmRoles": ["customer"]
+    },
+    {
+      "username": "service-account-graphql-e2e-admin",
+      "enabled": true,
+      "serviceAccountClientId": "graphql-e2e-admin",
+      "realmRoles": ["admin"]
+    }
+  ]
+}
diff --git a/tests/graphql_oidc_zitadel/docker-compose.yml b/tests/graphql_oidc_zitadel/docker-compose.yml
new file mode 100644
index 00000000..190cc173
--- /dev/null
+++ b/tests/graphql_oidc_zitadel/docker-compose.yml
@@ -0,0 +1,53 @@
+# Minimal Zitadel stack for GraphQL OIDC e2e (CI + local).
+# No login UI / Caddy — machine-user JWT-bearer mint only.
+#
+# Prefer the helper (handles machinekey perms + wait + bootstrap):
+#   ./scripts/oidc-zitadel-up.sh
+#   set -a && source graphql-oidc.env && set +a
+#   cargo test --test graphql_oidc_zitadel --features graphql,sqlite,metrics
+#
+# Or manually:
+#   mkdir -p tests/graphql_oidc_zitadel/machinekey && chmod 777 tests/graphql_oidc_zitadel/machinekey
+#   docker compose -f tests/graphql_oidc_zitadel/docker-compose.yml up -d --wait
+#   ./scripts/ci-bootstrap-graphql-oidc.sh
+services:
+  zitadel-db:
+    image: docker.io/library/postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: zitadel
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 15
+      start_period: 10s
+    networks: [zitadel]
+
+  zitadel:
+    image: ghcr.io/zitadel/zitadel:v4.6.1
+    user: "0:0"
+    command: >-
+      start-from-init
+      --masterkey "MasterkeyNeedsToHave32Characters"
+      --tlsMode disabled
+      --config /init/zitadel.yaml
+      --steps /init/steps.yaml
+    depends_on:
+      zitadel-db:
+        condition: service_healthy
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./init:/init:ro
+      # Bind mount must be world-writable on host (chmod 777) so FirstInstance
+      # can write zitadel-admin-sa.json. CI/local helper scripts enforce this.
+      # Service also runs as root (user 0:0) for GHA bind-mount reliability.
+      - ./machinekey:/machinekey
+    # No in-container healthcheck: image may lack curl/bash. Host-side wait on
+    # http://localhost:8080/debug/ready is in scripts/oidc-zitadel-up.sh.
+    networks: [zitadel]
+
+networks:
+  zitadel:
diff --git a/tests/graphql_oidc_zitadel/init/steps.yaml b/tests/graphql_oidc_zitadel/init/steps.yaml
new file mode 100644
index 00000000..0fd652cf
--- /dev/null
+++ b/tests/graphql_oidc_zitadel/init/steps.yaml
@@ -0,0 +1,21 @@
+FirstInstance:
+  MachineKeyPath: /machinekey/zitadel-admin-sa.json
+  Org:
+    Name: distributed-graphql-e2e
+    Human:
+      UserName: admin
+      FirstName: CI
+      LastName: Admin
+      Email:
+        Address: admin@localhost
+        Verified: true
+      Password: "Admin1234!"
+      PasswordChangeRequired: false
+    Machine:
+      Machine:
+        Username: zitadel-admin-sa
+        Name: Admin Service Account
+        Description: Bootstrap SA for GraphQL OIDC e2e
+      MachineKey:
+        Type: 1
+        ExpirationDate: "2029-01-01T00:00:00Z"
diff --git a/tests/graphql_oidc_zitadel/init/zitadel.yaml b/tests/graphql_oidc_zitadel/init/zitadel.yaml
new file mode 100644
index 00000000..852fd0e2
--- /dev/null
+++ b/tests/graphql_oidc_zitadel/init/zitadel.yaml
@@ -0,0 +1,29 @@
+ExternalDomain: localhost
+ExternalPort: 8080
+ExternalSecure: false
+
+TLS:
+  Enabled: false
+
+Database:
+  postgres:
+    Host: zitadel-db
+    Port: 5432
+    Database: zitadel
+    MaxOpenConns: 20
+    MaxIdleConns: 10
+    MaxConnLifetime: 30m
+    MaxConnIdleTime: 5m
+    User:
+      Username: zitadel
+      Password: zitadel
+      SSL:
+        Mode: disable
+    Admin:
+      Username: postgres
+      Password: postgres
+      SSL:
+        Mode: disable
+
+# Listen on all interfaces so host CI can reach :8080.
+Port: 8080
diff --git a/tests/graphql_oidc_zitadel/machinekey/.gitignore b/tests/graphql_oidc_zitadel/machinekey/.gitignore
new file mode 100644
index 00000000..d6b7ef32
--- /dev/null
+++ b/tests/graphql_oidc_zitadel/machinekey/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/tests/graphql_oidc_zitadel/main.rs b/tests/graphql_oidc_zitadel/main.rs
new file mode 100644
index 00000000..62e60ecc
--- /dev/null
+++ b/tests/graphql_oidc_zitadel/main.rs
@@ -0,0 +1,159 @@
+//! Zitadel live e2e — reference provider for [[specs/query-layer/oidc-e2e]] E1–E8.
+//! Gate: `ZITADEL_E2E=1`. Mint: JWT-bearer (adapter [[specs/query-layer/oidc-zitadel]]).
+
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+
+#[path = "../graphql_oidc_common/mod.rs"]
+mod common;
+
+use std::path::PathBuf;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use distributed::graphql::OidcConfig;
+use serde_json::{json, Value};
+
+fn e2e_enabled() -> bool {
+    common::gate_enabled("ZITADEL_E2E")
+}
+
+/// E0 offline: binary runs without gate.
+#[tokio::test]
+async fn e0_skips_when_not_gated() {
+    if e2e_enabled() {
+        return;
+    }
+    eprintln!("ZITADEL_E2E not set — skip live E1–E8 (D12)");
+}
+
+/// Live E1–E8 against real Zitadel issuer + shipped OidcBearer HTTP path.
+#[tokio::test]
+async fn e1_through_e8_live() {
+    if !e2e_enabled() {
+        eprintln!("ZITADEL_E2E not set — skip live E1–E8");
+        return;
+    }
+    let iss = std::env::var("OIDC_ISSUER").expect("OIDC_ISSUER");
+    assert!(
+        common::discovery_ready(&iss).await || issuer_ready_debug(&iss).await,
+        "issuer not ready: {iss}"
+    );
+    let audience = std::env::var("OIDC_AUDIENCE")
+        .or_else(|_| std::env::var("OIDC_CLIENT_ID"))
+        .expect("OIDC_AUDIENCE");
+
+    let customer_key = std::env::var("GRAPHQL_E2E_CUSTOMER_KEY").expect("CUSTOMER_KEY");
+    let customer_uid = std::env::var("GRAPHQL_E2E_CUSTOMER_USER_ID").expect("CUSTOMER_USER_ID");
+    let admin_key = std::env::var("GRAPHQL_E2E_ADMIN_KEY").expect("ADMIN_KEY");
+    let admin_uid = std::env::var("GRAPHQL_E2E_ADMIN_USER_ID").expect("ADMIN_USER_ID");
+
+    let oidc = OidcConfig::new(&iss, &audience);
+    common::run_e1_through_e8(
+        oidc,
+        async {
+            let t = mint_jwt_bearer(&iss, &customer_key, &customer_uid).await?;
+            Ok((t, customer_uid.clone()))
+        },
+        async {
+            let t = mint_jwt_bearer(&iss, &admin_key, &admin_uid).await?;
+            Ok((t, admin_uid.clone()))
+        },
+    )
+    .await;
+}
+
+async fn issuer_ready_debug(iss: &str) -> bool {
+    let url = format!("{}/debug/ready", iss.trim_end_matches('/'));
+    reqwest::Client::new()
+        .get(url)
+        .send()
+        .await
+        .map(|r| r.status().is_success())
+        .unwrap_or(false)
+}
+
+async fn mint_jwt_bearer(issuer: &str, key_path: &str, user_id: &str) -> Result<String, String> {
+    let raw =
+        std::fs::read_to_string(PathBuf::from(key_path)).map_err(|e| format!("read key: {e}"))?;
+    let key_json: Value = serde_json::from_str(&raw).map_err(|e| format!("parse key: {e}"))?;
+    let key_id = key_json
+        .get("keyId")
+        .or_else(|| key_json.get("key_id"))
+        .and_then(|v| v.as_str())
+        .ok_or("keyId missing")?;
+    let private_pem = key_json
+        .get("key")
+        .and_then(|v| v.as_str())
+        .ok_or("key PEM missing")?;
+
+    let iss = issuer.trim_end_matches('/');
+    let token_url = format!("{iss}/oauth/v2/token");
+    let now = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_secs() as i64;
+    let assertion_claims = json!({
+        "iss": user_id,
+        "sub": user_id,
+        "aud": [token_url.clone(), iss],
+        "iat": now,
+        "exp": now + 60,
+    });
+    let encoding = jsonwebtoken::EncodingKey::from_rsa_pem(private_pem.as_bytes())
+        .map_err(|e| format!("pem: {e}"))?;
+    let mut header = jsonwebtoken::Header::new(jsonwebtoken::Algorithm::RS256);
+    header.kid = Some(key_id.to_string());
+    let assertion = jsonwebtoken::encode(&header, &assertion_claims, &encoding)
+        .map_err(|e| format!("sign: {e}"))?;
+
+    let project_id = std::env::var("ZITADEL_PROJECT_ID")
+        .or_else(|_| std::env::var("OIDC_AUDIENCE"))
+        .unwrap_or_default();
+    // `projects:roles` (plural) yields `urn:zitadel:iam:org:project:{id}:roles` on tokens.
+    let scope = if project_id.is_empty() {
+        "openid profile urn:zitadel:iam:org:project:roles urn:zitadel:iam:org:projects:roles"
+            .to_string()
+    } else {
+        format!(
+            "openid profile urn:zitadel:iam:org:project:id:{project_id}:aud urn:zitadel:iam:org:project:roles urn:zitadel:iam:org:projects:roles"
+        )
+    };
+
+    let body = format!(
+        "grant_type={}&scope={}&assertion={}",
+        urlencoding("urn:ietf:params:oauth:grant-type:jwt-bearer"),
+        urlencoding(&scope),
+        urlencoding(&assertion),
+    );
+    let resp = reqwest::Client::new()
+        .post(&token_url)
+        .header("content-type", "application/x-www-form-urlencoded")
+        .body(body)
+        .send()
+        .await
+        .map_err(|e| format!("token request: {e}"))?;
+    if !resp.status().is_success() {
+        return Err(format!(
+            "token endpoint error: {}",
+            resp.text().await.unwrap_or_default()
+        ));
+    }
+    let body: Value = resp.json().await.map_err(|e| format!("json: {e}"))?;
+    body.get("access_token")
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string())
+        .ok_or_else(|| "no access_token".into())
+}
+
+fn urlencoding(s: &str) -> String {
+    let mut out = String::new();
+    for b in s.bytes() {
+        match b {
+            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
+                out.push(b as char)
+            }
+            b' ' => out.push('+'),
+            _ => out.push_str(&format!("%{b:02X}")),
+        }
+    }
+    out
+}
diff --git a/tests/graphql_postgres/main.rs b/tests/graphql_postgres/main.rs
new file mode 100644
index 00000000..239b91f6
--- /dev/null
+++ b/tests/graphql_postgres/main.rs
@@ -0,0 +1,63 @@
+//! Env-gated Postgres GraphQL smoke suite.
+//! Skips cleanly when DATABASE_URL is unset (CI without Postgres).
+
+#![cfg(all(feature = "graphql", feature = "postgres"))]
+
+use async_graphql::Request;
+use distributed::graphql::{read, GraphqlEngine, ModelPermissions};
+use distributed::microsvc::{Session, ROLE_KEY};
+use distributed::ReadModel;
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[table("gql_pg_smoke")]
+struct SmokeView {
+    #[id("id")]
+    id: String,
+    label: String,
+}
+
+#[tokio::test]
+async fn postgres_list_query_when_database_url_set() {
+    let url = match std::env::var("DATABASE_URL") {
+        Ok(u) if !u.is_empty() => u,
+        _ => {
+            eprintln!("skip: DATABASE_URL unset");
+            return;
+        }
+    };
+
+    let pool = sqlx::postgres::PgPoolOptions::new()
+        .max_connections(2)
+        .connect(&url)
+        .await
+        .expect("connect postgres");
+
+    sqlx::query("DROP TABLE IF EXISTS gql_pg_smoke")
+        .execute(&pool)
+        .await
+        .ok();
+    sqlx::query("CREATE TABLE gql_pg_smoke (id TEXT PRIMARY KEY, label TEXT NOT NULL)")
+        .execute(&pool)
+        .await
+        .expect("seed");
+    sqlx::query("INSERT INTO gql_pg_smoke VALUES ('1', 'hello')")
+        .execute(&pool)
+        .await
+        .expect("seed");
+
+    let engine = GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<SmokeView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .build()
+        .expect("build");
+
+    let mut session = Session::new();
+    session.set(ROLE_KEY, "user");
+    let resp = engine
+        .execute(&session, Request::new("{ gql_pg_smoke { id label } }"))
+        .await;
+    assert!(!resp.is_err(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    assert_eq!(data["gql_pg_smoke"][0]["label"], "hello");
+}
diff --git a/tests/graphql_query_protocol/main.rs b/tests/graphql_query_protocol/main.rs
new file mode 100644
index 00000000..b69370e3
--- /dev/null
+++ b/tests/graphql_query_protocol/main.rs
@@ -0,0 +1,1298 @@
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_graphql::Request;
+use base64::Engine as _;
+use distributed::bus::{Bus, InMemoryBus, Message, MessageKind, RunOptions};
+use distributed::graphql::{
+    col, read, GraphqlEngine, ModelNormalization, ModelPermissions, SurfaceProjector,
+};
+use distributed::microsvc::{
+    CausalProjectorContext, HandlerError, Routes, Service, Session, ROLE_KEY,
+};
+use distributed::projection_protocol::ProjectionChangeRetention;
+use distributed::{DistributedProjectManifest, ReadModel, RelationalReadModel, SqliteRepository};
+use futures_util::{stream::BoxStream, SinkExt, StreamExt};
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use tokio_tungstenite::tungstenite::client::IntoClientRequest;
+use tokio_tungstenite::tungstenite::http::header::SEC_WEBSOCKET_PROTOCOL;
+use tokio_tungstenite::tungstenite::Message as WsMessage;
+
+const SERVICE_ID: &str = "query-protocol-fixture";
+const FACT_NAME: &str = "query_protocol.item_changed";
+const PROJECTOR_NAME: &str = "project_query_protocol_items";
+const CHANGE_EPOCH: &str = "query-protocol-items-v1";
+const ROW_ID: &str = "row-private-9007199254740993";
+const LEGACY_ROW_ID: &str = "legacy-private-9007199254740995";
+const HIDDEN_ALIAS_PREFIX: &str = "0__distributed_evidence_pk_";
+const TEST_PROTOCOL_TOKEN_KEY: [u8; 32] = [0x7b; 32];
+const LIVE_SUBSCRIPTION: &str = "subscription WatchCausalRows { causal_query_views { title } }";
+const FILTERED_LIVE_SUBSCRIPTION: &str = r#"
+subscription WatchFilteredRows {
+  causal_query_views(where: { title: { _eq: "causal row" } }) { title }
+}
+"#;
+const EMBEDDED_SERVICE_ID: &str = "embedded-query-protocol-fixture";
+const EMBEDDED_FACT_NAME: &str = "query_protocol.embedded_item_changed";
+const EMBEDDED_PROJECTOR_NAME: &str = "project_embedded_query_protocol_items";
+const EMBEDDED_CHANGE_EPOCH: &str = "embedded-query-protocol-items-v1";
+
+#[derive(Clone, Debug, Deserialize)]
+struct ItemChanged {
+    id: String,
+    title: String,
+    #[serde(default)]
+    delete: bool,
+    #[serde(default)]
+    recreate: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "causal_query_views", primary_key = ["id"])]
+struct CausalQueryView {
+    id: String,
+    title: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "legacy_query_views", primary_key = ["id"])]
+struct LegacyQueryView {
+    id: String,
+    title: String,
+}
+
+#[derive(Clone, Debug, Deserialize)]
+struct EmbeddedItemChanged {
+    key: i64,
+    title: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "embedded_query_views", primary_key = ["key"])]
+struct EmbeddedQueryView {
+    id: String,
+    key: i64,
+    title: String,
+}
+
+fn projector() -> SurfaceProjector {
+    SurfaceProjector::new(PROJECTOR_NAME)
+        .facts([FACT_NAME])
+        .models(["CausalQueryView"])
+        .change_epoch(CHANGE_EPOCH)
+}
+
+fn embedded_projector() -> SurfaceProjector {
+    SurfaceProjector::new(EMBEDDED_PROJECTOR_NAME)
+        .facts([EMBEDDED_FACT_NAME])
+        .models(["EmbeddedQueryView"])
+        .change_epoch(EMBEDDED_CHANGE_EPOCH)
+}
+
+fn user_session() -> Session {
+    let mut session = Session::new();
+    session.set(ROLE_KEY, "user");
+    session
+}
+
+struct ProtocolFixture {
+    repository: SqliteRepository,
+    bus: InMemoryBus,
+    engine: GraphqlEngine,
+}
+
+fn projection_service(repository: &SqliteRepository, bus: &InMemoryBus) -> Service {
+    let declaration = projector();
+    let routes = Routes::new()
+        .with_read_model_store(repository.clone())
+        .causal_projector::<ItemChanged>(declaration)
+        .model::<CausalQueryView>()
+        .handle(
+            |context: CausalProjectorContext, fact: ItemChanged| async move {
+                let view = CausalQueryView {
+                    id: fact.id,
+                    title: fact.title,
+                };
+                if fact.recreate {
+                    let tombstone = context
+                        .tombstone_revision::<CausalQueryView>(view.primary_key()?)
+                        .await?
+                        .expect("recreate fixture requires its durable tombstone");
+                    context.recreate(&view, &tombstone)?;
+                } else if fact.delete {
+                    let loaded = context
+                        .load::<CausalQueryView>(view.primary_key()?)
+                        .await?
+                        .expect("delete fixture requires its projected row");
+                    context
+                        .delete::<CausalQueryView>(loaded.model.primary_key()?, &loaded.revision)?;
+                } else {
+                    context.project(&view).await?;
+                }
+                Ok::<(), HandlerError>(())
+            },
+        );
+    Service::new()
+        .named(SERVICE_ID)
+        .routes(routes)
+        .with_bus(bus.clone())
+}
+
+fn embedded_projection_service(repository: &SqliteRepository, bus: &InMemoryBus) -> Service {
+    let declaration = embedded_projector();
+    let routes = Routes::new()
+        .with_read_model_store(repository.clone())
+        .causal_projector::<EmbeddedItemChanged>(declaration)
+        .model::<EmbeddedQueryView>()
+        .handle(
+            |context: CausalProjectorContext, fact: EmbeddedItemChanged| async move {
+                context
+                    .project(&EmbeddedQueryView {
+                        id: format!("embedded-{}", fact.key),
+                        key: fact.key,
+                        title: fact.title,
+                    })
+                    .await?;
+                Ok::<(), HandlerError>(())
+            },
+        );
+    Service::new()
+        .named(EMBEDDED_SERVICE_ID)
+        .routes(routes)
+        .with_bus(bus.clone())
+}
+
+async fn project_item(
+    repository: &SqliteRepository,
+    bus: &InMemoryBus,
+    sequence: u64,
+    title: &str,
+) {
+    project_item_with_id(repository, bus, sequence, ROW_ID, title).await;
+}
+
+async fn project_item_with_id(
+    repository: &SqliteRepository,
+    bus: &InMemoryBus,
+    sequence: u64,
+    id: &str,
+    title: &str,
+) {
+    bus.publish_message(
+        Message::new(
+            FACT_NAME,
+            MessageKind::Event,
+            serde_json::to_vec(&json!({
+                "id": id,
+                "title": title
+            }))
+            .expect("fixture fact"),
+        )
+        .with_id(format!("query-protocol-fact-{sequence}"))
+        .with_metadata(
+            distributed::trace_context::CAUSATION_ID,
+            format!("query-protocol-command-{sequence}"),
+        ),
+    )
+    .await
+    .expect("publish query protocol fact");
+    projection_service(repository, bus)
+        .run(RunOptions::idempotent())
+        .await
+        .expect("project query protocol fact");
+}
+
+async fn delete_item(repository: &SqliteRepository, bus: &InMemoryBus, sequence: u64) {
+    bus.publish_message(
+        Message::new(
+            FACT_NAME,
+            MessageKind::Event,
+            serde_json::to_vec(&json!({
+                "id": ROW_ID,
+                "title": "deleted row",
+                "delete": true
+            }))
+            .expect("fixture delete fact"),
+        )
+        .with_id(format!("query-protocol-fact-{sequence}"))
+        .with_metadata(
+            distributed::trace_context::CAUSATION_ID,
+            format!("query-protocol-command-{sequence}"),
+        ),
+    )
+    .await
+    .expect("publish query protocol delete fact");
+    projection_service(repository, bus)
+        .run(RunOptions::idempotent())
+        .await
+        .expect("delete query protocol row");
+}
+
+async fn recreate_item(
+    repository: &SqliteRepository,
+    bus: &InMemoryBus,
+    sequence: u64,
+    title: &str,
+) {
+    bus.publish_message(
+        Message::new(
+            FACT_NAME,
+            MessageKind::Event,
+            serde_json::to_vec(&json!({
+                "id": ROW_ID,
+                "title": title,
+                "recreate": true
+            }))
+            .expect("fixture recreate fact"),
+        )
+        .with_id(format!("query-protocol-fact-{sequence}"))
+        .with_metadata(
+            distributed::trace_context::CAUSATION_ID,
+            format!("query-protocol-command-{sequence}"),
+        ),
+    )
+    .await
+    .expect("publish query protocol recreate fact");
+    projection_service(repository, bus)
+        .run(RunOptions::idempotent())
+        .await
+        .expect("recreate query protocol row");
+}
+
+async fn protocol_fixture_with_rows() -> ProtocolFixture {
+    protocol_fixture_with_retention(1).await
+}
+
+async fn protocol_fixture_with_retention(retention: u64) -> ProtocolFixture {
+    let repository = SqliteRepository::connect_and_migrate("sqlite::memory:")
+        .await
+        .expect("migrated SQLite repository")
+        .with_projection_change_retention(
+            ProjectionChangeRetention::new(retention)
+                .expect("positive retained projection change count"),
+        );
+    let manifest = DistributedProjectManifest::new(SERVICE_ID)
+        .read_model::<CausalQueryView>()
+        .read_model::<LegacyQueryView>();
+    repository
+        .bootstrap_table_schema_for_dev(
+            &manifest
+                .table_registry()
+                .expect("query protocol table registry"),
+        )
+        .await
+        .expect("query protocol read-model tables");
+
+    sqlx::query("INSERT INTO legacy_query_views (id, title) VALUES (?, ?)")
+        .bind(LEGACY_ROW_ID)
+        .bind("legacy row")
+        .execute(repository.pool())
+        .await
+        .expect("legacy row");
+
+    let bus = InMemoryBus::new();
+    let declaration = projector();
+    project_item(&repository, &bus, 1, "causal row").await;
+
+    let engine = GraphqlEngine::builder(&repository)
+        .service_id(SERVICE_ID)
+        .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+        .roles(&["user"])
+        .model::<CausalQueryView>(
+            ModelPermissions::new().grant("user", read().all_columns().aggregations()),
+        )
+        .model::<LegacyQueryView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .client_projectors([declaration])
+        .change_stream(repository.read_model_changes())
+        .build()
+        .expect("query protocol GraphQL engine");
+    ProtocolFixture {
+        repository,
+        bus,
+        engine,
+    }
+}
+
+async fn protocol_engine_with_rows() -> GraphqlEngine {
+    protocol_fixture_with_rows().await.engine
+}
+
+fn wire_response(response: async_graphql::Response) -> Value {
+    assert!(
+        !response.is_err(),
+        "unexpected GraphQL errors: {:?}",
+        response.errors
+    );
+    serde_json::to_value(response).expect("GraphQL wire response")
+}
+
+fn distributed_envelope(response: &Value) -> &Value {
+    response
+        .get("extensions")
+        .and_then(|extensions| extensions.get("distributed"))
+        .unwrap_or_else(|| panic!("missing extensions.distributed: {response}"))
+}
+
+fn assert_opaque_token(token: &Value, purpose: &str) {
+    let token = token
+        .as_str()
+        .unwrap_or_else(|| panic!("missing {purpose} token: {token}"));
+    let segments = token.split('.').collect::<Vec<_>>();
+    assert_eq!(segments.len(), 3, "bounded opaque token: {token}");
+    assert_eq!(segments[0], "v1");
+    assert_eq!(segments[1], purpose);
+    let mac = base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .decode(segments[2])
+        .unwrap_or_else(|error| panic!("invalid opaque token MAC `{token}`: {error}"));
+    assert_eq!(mac.len(), 32, "HMAC-SHA256 token: {token}");
+    assert_eq!(
+        base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(mac),
+        segments[2],
+        "token MAC must use canonical unpadded base64url"
+    );
+    for private in [ROW_ID, LEGACY_ROW_ID, CHANGE_EPOCH] {
+        assert!(
+            !token.contains(private),
+            "opaque token disclosed private scope material `{private}`: {token}"
+        );
+    }
+}
+
+async fn next_wire_frame(stream: &mut BoxStream<'static, async_graphql::Response>) -> Value {
+    let response = tokio::time::timeout(Duration::from_secs(2), stream.next())
+        .await
+        .expect("timeout waiting for GraphQL subscription frame")
+        .expect("GraphQL subscription ended");
+    wire_response(response)
+}
+
+fn request_with_resume(document: &str, cursors: Value) -> Request {
+    serde_json::from_value(json!({
+        "query": document,
+        "extensions": {
+            "distributed": {
+                "resume": {
+                    "cursors": cursors
+                }
+            }
+        }
+    }))
+    .expect("valid GraphQL request with distributed resume extension")
+}
+
+fn assert_live_frame(
+    response: &Value,
+    root_field: &str,
+    expected_title: &str,
+    expected_position: &str,
+    expected_reset: bool,
+) -> Value {
+    assert_eq!(
+        response["data"][root_field],
+        json!([{ "title": expected_title }]),
+        "{response}"
+    );
+    let distributed = distributed_envelope(response);
+    let snapshot = &distributed["snapshot"];
+    assert_eq!(snapshot["recordsComplete"], true, "{response}");
+    assert_eq!(snapshot["indexesComparable"], true, "{response}");
+    assert_eq!(snapshot["indexes"].as_array().map(Vec::len), Some(1));
+    assert_eq!(snapshot["indexes"][0]["projection"], PROJECTOR_NAME);
+    assert_eq!(snapshot["indexes"][0]["position"], expected_position);
+
+    let live = &distributed["live"];
+    assert_eq!(live["supported"], true, "{response}");
+    assert_eq!(live["reset"], expected_reset, "{response}");
+    assert_eq!(live["cursors"].as_array().map(Vec::len), Some(1));
+    assert_eq!(live["cursors"][0]["projection"], PROJECTOR_NAME);
+    assert_eq!(live["cursors"][0]["position"], expected_position);
+    assert_eq!(
+        live["cursors"][0], snapshot["indexes"][0]["resume"],
+        "the live cursor and authoritative snapshot index must describe one position"
+    );
+    live["cursors"].clone()
+}
+
+fn tamper_first_cursor_token(mut cursors: Value) -> Value {
+    let token = cursors[0]["token"]
+        .as_str()
+        .expect("live cursor token")
+        .to_string();
+    let mut bytes = token.into_bytes();
+    let mac_start = bytes
+        .iter()
+        .rposition(|byte| *byte == b'.')
+        .expect("token purpose separator")
+        + 1;
+    bytes[mac_start] = if bytes[mac_start] == b'A' { b'B' } else { b'A' };
+    cursors[0]["token"] =
+        Value::String(String::from_utf8(bytes).expect("opaque token remains ASCII"));
+    cursors
+}
+
+#[tokio::test]
+async fn projected_query_emits_exact_record_and_index_revisions_without_key_leaks() {
+    let engine = protocol_engine_with_rows().await;
+    let response = wire_response(
+        engine
+            .execute(
+                &user_session(),
+                Request::new("query QuerySnapshot { aliasedRows: causal_query_views { title } }"),
+            )
+            .await,
+    );
+
+    assert_eq!(
+        response["data"],
+        json!({ "aliasedRows": [{ "title": "causal row" }] })
+    );
+    let serialized = response.to_string();
+    assert!(
+        !serialized.contains(HIDDEN_ALIAS_PREFIX),
+        "compiler evidence alias leaked into GraphQL: {response}"
+    );
+    assert!(
+        !serialized.contains(ROW_ID),
+        "an omitted primary key leaked through protocol metadata: {response}"
+    );
+
+    let distributed = distributed_envelope(&response);
+    assert_eq!(distributed["protocolVersion"], 1);
+    assert!(distributed.get("command").is_none());
+    assert!(distributed.get("live").is_none());
+    assert_opaque_token(&distributed["cacheScope"], "cache-scope");
+
+    let snapshot = &distributed["snapshot"];
+    assert_eq!(snapshot["recordsComplete"], true);
+    assert_eq!(snapshot["indexesComparable"], true);
+    assert!(snapshot.get("complete").is_none());
+    assert_eq!(snapshot["observations"], json!([]));
+    assert_opaque_token(&snapshot["scopeToken"], "query-snapshot");
+
+    let records = snapshot["records"].as_array().expect("record revisions");
+    assert_eq!(records.len(), 1, "{snapshot}");
+    let record = &records[0];
+    assert_eq!(record["path"], json!(["aliasedRows", "0"]));
+    assert_eq!(record["model"], "CausalQueryView");
+    assert_eq!(record["incarnation"], "1");
+    assert_eq!(record["revision"], "1");
+    assert_eq!(record["tombstone"], false);
+    assert_opaque_token(&record["scopeToken"], "record-revision");
+
+    let indexes = snapshot["indexes"].as_array().expect("index revisions");
+    assert_eq!(indexes.len(), 1, "{snapshot}");
+    let index = &indexes[0];
+    assert_eq!(index["projection"], PROJECTOR_NAME);
+    assert_eq!(index["position"], "1");
+    assert_opaque_token(&index["scopeToken"], "query-index");
+    assert_eq!(index["resume"]["projection"], PROJECTOR_NAME);
+    assert_eq!(index["resume"]["position"], "1");
+    assert_opaque_token(&index["resume"]["token"], "live-resume");
+
+    let tokens = [
+        snapshot["scopeToken"].as_str().unwrap(),
+        record["scopeToken"].as_str().unwrap(),
+        index["scopeToken"].as_str().unwrap(),
+        index["resume"]["token"].as_str().unwrap(),
+    ];
+    for (offset, token) in tokens.iter().enumerate() {
+        assert!(
+            !tokens[..offset].contains(token),
+            "purpose-separated protocol tokens must not alias: {tokens:?}"
+        );
+    }
+}
+
+#[tokio::test]
+async fn count_only_aggregate_emits_no_unselected_node_record_evidence() {
+    let engine = protocol_engine_with_rows().await;
+    let response = wire_response(
+        engine
+            .execute(
+                &user_session(),
+                Request::new(
+                    "query CountOnly {
+                        stats: causal_query_views_aggregate {
+                            __typename
+                            totals: aggregate {
+                                __typename
+                                total: count
+                            }
+                        }
+                    }",
+                ),
+            )
+            .await,
+    );
+
+    assert_eq!(
+        response["data"],
+        json!({
+            "stats": {
+                "__typename": "causal_query_views_aggregate",
+                "totals": {
+                    "__typename": "causal_query_views_aggregate_fields",
+                    "total": 1
+                }
+            }
+        }),
+        "{response}"
+    );
+    let snapshot = &distributed_envelope(&response)["snapshot"];
+    assert_eq!(snapshot["recordsComplete"], true, "{snapshot}");
+    assert_eq!(snapshot["indexesComparable"], true, "{snapshot}");
+    assert_eq!(snapshot["records"], json!([]), "{snapshot}");
+    assert_eq!(snapshot["indexes"].as_array().map(Vec::len), Some(1));
+    assert_eq!(snapshot["indexes"][0]["projection"], PROJECTOR_NAME);
+}
+
+#[tokio::test]
+async fn aggregate_node_aliases_drive_data_and_exact_record_paths() {
+    let engine = protocol_engine_with_rows().await;
+    let response = wire_response(
+        engine
+            .execute(
+                &user_session(),
+                Request::new(
+                    "query AliasedAggregateNodes {
+                        stats: causal_query_views_aggregate {
+                            firstTotals: aggregate { firstCount: count }
+                            secondTotals: aggregate { secondCount: count }
+                            rowsAlias: nodes { heading: title }
+                            otherRowsAlias: nodes { alternateHeading: title }
+                        }
+                    }",
+                ),
+            )
+            .await,
+    );
+
+    assert_eq!(
+        response["data"],
+        json!({
+            "stats": {
+                "firstTotals": { "firstCount": 1 },
+                "secondTotals": { "secondCount": 1 },
+                "rowsAlias": [{ "heading": "causal row" }],
+                "otherRowsAlias": [{ "alternateHeading": "causal row" }]
+            }
+        }),
+        "{response}"
+    );
+    let snapshot = &distributed_envelope(&response)["snapshot"];
+    let records = snapshot["records"].as_array().expect("record revisions");
+    assert_eq!(records.len(), 2, "{snapshot}");
+    assert_eq!(records[0]["path"], json!(["stats", "rowsAlias", "0"]));
+    assert_eq!(records[0]["model"], "CausalQueryView");
+    assert_eq!(records[1]["path"], json!(["stats", "otherRowsAlias", "0"]));
+    assert_eq!(records[1]["model"], "CausalQueryView");
+}
+
+#[tokio::test]
+async fn embedded_models_emit_index_evidence_without_record_evidence() {
+    let repository = SqliteRepository::connect_and_migrate("sqlite::memory:")
+        .await
+        .expect("migrated embedded SQLite repository");
+    let manifest =
+        DistributedProjectManifest::new(EMBEDDED_SERVICE_ID).read_model::<EmbeddedQueryView>();
+    repository
+        .bootstrap_table_schema_for_dev(
+            &manifest
+                .table_registry()
+                .expect("embedded query protocol table registry"),
+        )
+        .await
+        .expect("embedded query protocol read-model table");
+
+    let bus = InMemoryBus::new();
+    bus.publish_message(
+        Message::new(
+            EMBEDDED_FACT_NAME,
+            MessageKind::Event,
+            serde_json::to_vec(&json!({
+                "key": 42,
+                "title": "embedded row"
+            }))
+            .expect("embedded fixture fact"),
+        )
+        .with_id("embedded-query-protocol-fact-1")
+        .with_metadata(
+            distributed::trace_context::CAUSATION_ID,
+            "embedded-query-protocol-command-1",
+        ),
+    )
+    .await
+    .expect("publish embedded query protocol fact");
+    embedded_projection_service(&repository, &bus)
+        .run(RunOptions::idempotent())
+        .await
+        .expect("project embedded query protocol fact");
+
+    let engine = GraphqlEngine::builder(&repository)
+        .service_id(EMBEDDED_SERVICE_ID)
+        .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+        .roles(&["user"])
+        .model::<EmbeddedQueryView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .client_projectors([embedded_projector()])
+        .change_stream(repository.read_model_changes())
+        .build()
+        .expect("embedded query protocol GraphQL engine");
+    let client_manifest = engine
+        .client_manifest_for_role("user")
+        .expect("embedded client manifest");
+    assert!(matches!(
+        &client_manifest.models[0].normalization,
+        ModelNormalization::Embedded
+    ));
+
+    let response = wire_response(
+        engine
+            .execute(
+                &user_session(),
+                Request::new(
+                    "query EmbeddedSnapshot {
+                        embeddedRows: embedded_query_views { heading: title }
+                    }",
+                ),
+            )
+            .await,
+    );
+    assert_eq!(
+        response["data"],
+        json!({ "embeddedRows": [{ "heading": "embedded row" }] }),
+        "{response}"
+    );
+    let serialized = response.to_string();
+    assert!(!serialized.contains(HIDDEN_ALIAS_PREFIX), "{response}");
+    let snapshot = &distributed_envelope(&response)["snapshot"];
+    assert_eq!(snapshot["recordsComplete"], true, "{snapshot}");
+    assert_eq!(snapshot["indexesComparable"], true, "{snapshot}");
+    assert_eq!(snapshot["records"], json!([]), "{snapshot}");
+    assert_eq!(snapshot["indexes"].as_array().map(Vec::len), Some(1));
+    assert_eq!(
+        snapshot["indexes"][0]["projection"],
+        EMBEDDED_PROJECTOR_NAME
+    );
+    assert_eq!(snapshot["indexes"][0]["position"], "1");
+}
+
+#[tokio::test]
+async fn query_evidence_chunks_129_unique_rows_inside_one_snapshot() {
+    let fixture = protocol_fixture_with_retention(10).await;
+    for sequence in 2_u64..=129 {
+        fixture
+            .bus
+            .publish_message(
+                Message::new(
+                    FACT_NAME,
+                    MessageKind::Event,
+                    serde_json::to_vec(&json!({
+                        "id": format!("bulk-row-{sequence:03}"),
+                        "title": format!("bulk title {sequence}")
+                    }))
+                    .expect("bulk fixture fact"),
+                )
+                .with_id(format!("query-protocol-bulk-fact-{sequence}"))
+                .with_metadata(
+                    distributed::trace_context::CAUSATION_ID,
+                    format!("query-protocol-bulk-command-{sequence}"),
+                ),
+            )
+            .await
+            .expect("publish bulk query protocol fact");
+    }
+    projection_service(&fixture.repository, &fixture.bus)
+        .run(RunOptions::idempotent())
+        .await
+        .expect("project bulk query protocol facts");
+
+    let response = wire_response(
+        fixture
+            .engine
+            .execute(
+                &user_session(),
+                Request::new(
+                    "query QueryEvidenceBatchBoundary { causal_query_views(limit: 129) { title } }",
+                ),
+            )
+            .await,
+    );
+    assert_eq!(
+        response["data"]["causal_query_views"]
+            .as_array()
+            .map(Vec::len),
+        Some(129),
+        "{response}"
+    );
+    let snapshot = &distributed_envelope(&response)["snapshot"];
+    assert_eq!(snapshot["recordsComplete"], true, "{snapshot}");
+    assert_eq!(snapshot["indexesComparable"], true, "{snapshot}");
+    assert_eq!(snapshot["records"].as_array().map(Vec::len), Some(129));
+}
+
+#[tokio::test]
+async fn matching_query_and_live_plans_share_snapshot_scope_not_operation_hash() {
+    let fixture = protocol_fixture_with_rows().await;
+    let query = wire_response(
+        fixture
+            .engine
+            .execute(
+                &user_session(),
+                Request::new("query ReadCausalRows { causal_query_views { title } }"),
+            )
+            .await,
+    );
+    let mut live_stream = fixture
+        .engine
+        .execute_stream(&user_session(), Request::new(LIVE_SUBSCRIPTION));
+    let live = next_wire_frame(&mut live_stream).await;
+    let query_protocol = distributed_envelope(&query);
+    let live_protocol = distributed_envelope(&live);
+
+    assert_ne!(
+        query_protocol["operation"], live_protocol["operation"],
+        "transport operation hashes remain exact document drift fences"
+    );
+    assert_eq!(
+        query_protocol["snapshot"]["scopeToken"], live_protocol["snapshot"]["scopeToken"],
+        "matching compiler plans must share one comparable query/live snapshot scope"
+    );
+    assert_eq!(
+        query_protocol["snapshot"]["indexes"], live_protocol["snapshot"]["indexes"],
+        "matching plans at one head must carry identical index evidence"
+    );
+}
+
+#[tokio::test]
+async fn live_subscription_accepts_an_exact_resume_without_reset() {
+    let fixture = protocol_fixture_with_rows().await;
+    let mut initial_stream = fixture
+        .engine
+        .execute_stream(&user_session(), Request::new(LIVE_SUBSCRIPTION));
+    let initial = next_wire_frame(&mut initial_stream).await;
+    let initial_cursors =
+        assert_live_frame(&initial, "causal_query_views", "causal row", "1", false);
+    drop(initial_stream);
+
+    let mut resumed_stream = fixture.engine.execute_stream(
+        &user_session(),
+        request_with_resume(LIVE_SUBSCRIPTION, initial_cursors.clone()),
+    );
+    let resumed = next_wire_frame(&mut resumed_stream).await;
+    let resumed_cursors =
+        assert_live_frame(&resumed, "causal_query_views", "causal row", "1", false);
+    assert_eq!(
+        resumed_cursors, initial_cursors,
+        "an exact reconnect must remain in the same operation and projection scope"
+    );
+}
+
+#[tokio::test]
+async fn live_subscription_tampering_and_wrong_scope_reset_without_errors() {
+    let fixture = protocol_fixture_with_rows().await;
+    let mut initial_stream = fixture
+        .engine
+        .execute_stream(&user_session(), Request::new(LIVE_SUBSCRIPTION));
+    let initial = next_wire_frame(&mut initial_stream).await;
+    let initial_cursors =
+        assert_live_frame(&initial, "causal_query_views", "causal row", "1", false);
+    let initial_snapshot_scope = distributed_envelope(&initial)["snapshot"]["scopeToken"].clone();
+    drop(initial_stream);
+
+    let tampered_cursors = tamper_first_cursor_token(initial_cursors.clone());
+    let mut tampered_stream = fixture.engine.execute_stream(
+        &user_session(),
+        request_with_resume(LIVE_SUBSCRIPTION, tampered_cursors.clone()),
+    );
+    let tampered = next_wire_frame(&mut tampered_stream).await;
+    let tampered_fallback_cursors =
+        assert_live_frame(&tampered, "causal_query_views", "causal row", "1", true);
+    assert_eq!(
+        tampered_fallback_cursors, initial_cursors,
+        "fallback must issue the authoritative current cursor, not echo tampered metadata"
+    );
+    assert_ne!(tampered_fallback_cursors, tampered_cursors);
+    drop(tampered_stream);
+
+    let mut wrong_scope_stream = fixture.engine.execute_stream(
+        &user_session(),
+        request_with_resume(FILTERED_LIVE_SUBSCRIPTION, initial_cursors.clone()),
+    );
+    let wrong_scope = next_wire_frame(&mut wrong_scope_stream).await;
+    let wrong_scope_cursors =
+        assert_live_frame(&wrong_scope, "causal_query_views", "causal row", "1", true);
+    assert_ne!(
+        distributed_envelope(&wrong_scope)["snapshot"]["scopeToken"],
+        initial_snapshot_scope,
+        "a different logical filter must receive its own authoritative snapshot scope"
+    );
+    assert_ne!(
+        wrong_scope_cursors, initial_cursors,
+        "a cursor must never cross operation-instance scopes"
+    );
+}
+
+#[tokio::test]
+async fn live_subscription_out_of_window_resume_resets_to_current_snapshot() {
+    let fixture = protocol_fixture_with_rows().await;
+    let mut initial_stream = fixture
+        .engine
+        .execute_stream(&user_session(), Request::new(LIVE_SUBSCRIPTION));
+    let initial = next_wire_frame(&mut initial_stream).await;
+    let stale_cursors = assert_live_frame(&initial, "causal_query_views", "causal row", "1", false);
+    drop(initial_stream);
+
+    project_item(&fixture.repository, &fixture.bus, 2, "causal row 2").await;
+    project_item(&fixture.repository, &fixture.bus, 3, "causal row 3").await;
+    let compacted_through: i64 =
+        sqlx::query_scalar("SELECT compacted_through FROM projection_partitions")
+            .fetch_one(fixture.repository.pool())
+            .await
+            .expect("projection compaction watermark");
+    assert_eq!(
+        compacted_through, 2,
+        "position 1 must be strictly outside the retained resume window"
+    );
+
+    let mut resumed_stream = fixture.engine.execute_stream(
+        &user_session(),
+        request_with_resume(LIVE_SUBSCRIPTION, stale_cursors.clone()),
+    );
+    let resumed = next_wire_frame(&mut resumed_stream).await;
+    let current_cursors =
+        assert_live_frame(&resumed, "causal_query_views", "causal row 3", "3", true);
+    assert_ne!(
+        current_cursors, stale_cursors,
+        "the reset frame must carry only the current authoritative cursor"
+    );
+}
+
+#[tokio::test]
+async fn live_subscription_frames_keep_data_and_metadata_in_fifo_order() {
+    let fixture = protocol_fixture_with_rows().await;
+    let mut stream = fixture
+        .engine
+        .execute_stream(&user_session(), Request::new(LIVE_SUBSCRIPTION));
+
+    let first = next_wire_frame(&mut stream).await;
+    let first_cursors = assert_live_frame(&first, "causal_query_views", "causal row", "1", false);
+
+    fixture
+        .repository
+        .publish_read_model_change(distributed::ReadModelChange::new(["causal_query_views"]));
+    assert!(
+        tokio::time::timeout(Duration::from_millis(350), stream.next())
+            .await
+            .is_err(),
+        "a redundant invalidation must be hash-gated without queuing orphaned frame metadata"
+    );
+
+    project_item(&fixture.repository, &fixture.bus, 2, "causal row 2").await;
+    let second = next_wire_frame(&mut stream).await;
+    let second_cursors =
+        assert_live_frame(&second, "causal_query_views", "causal row 2", "2", false);
+
+    project_item(&fixture.repository, &fixture.bus, 3, "causal row 3").await;
+    let third = next_wire_frame(&mut stream).await;
+    let third_cursors = assert_live_frame(&third, "causal_query_views", "causal row 3", "3", false);
+
+    assert_ne!(first_cursors, second_cursors);
+    assert_ne!(second_cursors, third_cursors);
+    let second_snapshot = &distributed_envelope(&second)["snapshot"];
+    assert_eq!(
+        second_snapshot["observations"],
+        json!([{
+            "causationId": "query-protocol-command-2",
+            "projection": PROJECTOR_NAME,
+            "model": "CausalQueryView",
+            "scopeToken": second_snapshot["observations"][0]["scopeToken"].clone()
+        }]),
+        "the live suffix must carry exact causation evidence"
+    );
+    assert_opaque_token(
+        &second_snapshot["observations"][0]["scopeToken"],
+        "projection-obligation",
+    );
+    assert!(
+        second_snapshot["records"]
+            .as_array()
+            .expect("second frame record revisions")
+            .iter()
+            .any(|record| {
+                record["path"] == json!(["causal_query_views", "0"])
+                    && record["incarnation"] == "1"
+                    && record["revision"] == "2"
+                    && record["tombstone"] == false
+            }),
+        "the current row path must carry the final record fence: {second}"
+    );
+    assert_eq!(
+        distributed_envelope(&first)["snapshot"]["indexes"][0]["position"],
+        "1",
+        "later metadata must not bleed into the first emitted response"
+    );
+    assert_eq!(
+        distributed_envelope(&second)["snapshot"]["indexes"][0]["position"],
+        "2",
+        "the second response must retain its own immutable frame metadata"
+    );
+}
+
+#[tokio::test]
+async fn live_subscription_replays_delete_tombstone_and_observation() {
+    let fixture = protocol_fixture_with_rows().await;
+    let mut stream = fixture
+        .engine
+        .execute_stream(&user_session(), Request::new(LIVE_SUBSCRIPTION));
+    let initial = next_wire_frame(&mut stream).await;
+    assert_live_frame(&initial, "causal_query_views", "causal row", "1", false);
+
+    delete_item(&fixture.repository, &fixture.bus, 2).await;
+    let deleted = next_wire_frame(&mut stream).await;
+    assert_eq!(
+        deleted["data"]["causal_query_views"],
+        json!([]),
+        "{deleted}"
+    );
+    let distributed = distributed_envelope(&deleted);
+    assert_eq!(distributed["live"]["supported"], true);
+    assert_eq!(distributed["live"]["reset"], false);
+    assert_eq!(distributed["live"]["cursors"][0]["position"], "2");
+    assert_eq!(distributed["snapshot"]["indexes"][0]["position"], "2");
+
+    let tombstone = distributed["snapshot"]["records"]
+        .as_array()
+        .expect("delete record metadata")
+        .iter()
+        .find(|record| record["tombstone"] == true)
+        .unwrap_or_else(|| panic!("delete frame omitted its tombstone: {deleted}"));
+    assert!(tombstone.get("path").is_none(), "{tombstone}");
+    assert_eq!(tombstone["model"], "CausalQueryView");
+    assert_eq!(tombstone["incarnation"], "1");
+    assert_eq!(tombstone["revision"], "2");
+    assert_opaque_token(&tombstone["scopeToken"], "record-revision");
+
+    let observation = &distributed["snapshot"]["observations"][0];
+    assert_eq!(observation["causationId"], "query-protocol-command-2");
+    assert_eq!(observation["projection"], PROJECTOR_NAME);
+    assert_eq!(observation["model"], "CausalQueryView");
+    assert_opaque_token(&observation["scopeToken"], "projection-obligation");
+}
+
+#[tokio::test]
+async fn live_subscription_emits_pathless_fence_when_a_record_leaves_the_result() {
+    let fixture = protocol_fixture_with_retention(10).await;
+    let mut stream = fixture
+        .engine
+        .execute_stream(&user_session(), Request::new(FILTERED_LIVE_SUBSCRIPTION));
+    let initial = next_wire_frame(&mut stream).await;
+    assert_eq!(
+        initial["data"]["causal_query_views"],
+        json!([{ "title": "causal row" }])
+    );
+
+    project_item(&fixture.repository, &fixture.bus, 2, "outside filter").await;
+    let excluded = next_wire_frame(&mut stream).await;
+    assert_eq!(excluded["data"]["causal_query_views"], json!([]));
+    let distributed = distributed_envelope(&excluded);
+    assert_eq!(distributed["snapshot"]["indexes"][0]["position"], "2");
+    let records = distributed["snapshot"]["records"]
+        .as_array()
+        .expect("pathless live fence");
+    assert_eq!(records.len(), 1, "{excluded}");
+    assert!(records[0].get("path").is_none(), "{excluded}");
+    assert_eq!(records[0]["incarnation"], "1");
+    assert_eq!(records[0]["revision"], "2");
+    assert_eq!(records[0]["tombstone"], false);
+    assert_opaque_token(&records[0]["scopeToken"], "record-revision");
+    assert_eq!(
+        distributed["snapshot"]["observations"][0]["causationId"],
+        "query-protocol-command-2"
+    );
+}
+
+#[tokio::test]
+async fn resumed_suffix_coalesces_delete_recreate_and_repeated_upserts() {
+    let fixture = protocol_fixture_with_retention(10).await;
+    let mut initial_stream = fixture
+        .engine
+        .execute_stream(&user_session(), Request::new(LIVE_SUBSCRIPTION));
+    let initial = next_wire_frame(&mut initial_stream).await;
+    let cursors = assert_live_frame(&initial, "causal_query_views", "causal row", "1", false);
+    drop(initial_stream);
+
+    delete_item(&fixture.repository, &fixture.bus, 2).await;
+    recreate_item(&fixture.repository, &fixture.bus, 3, "recreated").await;
+    project_item(&fixture.repository, &fixture.bus, 4, "recreated 2").await;
+    project_item(&fixture.repository, &fixture.bus, 5, "recreated 3").await;
+
+    let mut resumed_stream = fixture.engine.execute_stream(
+        &user_session(),
+        request_with_resume(LIVE_SUBSCRIPTION, cursors),
+    );
+    let resumed = next_wire_frame(&mut resumed_stream).await;
+    assert_live_frame(&resumed, "causal_query_views", "recreated 3", "5", false);
+    let snapshot = &distributed_envelope(&resumed)["snapshot"];
+    let records = snapshot["records"].as_array().expect("coalesced records");
+    assert_eq!(records.len(), 1, "{resumed}");
+    assert_eq!(records[0]["path"], json!(["causal_query_views", "0"]));
+    assert_eq!(records[0]["incarnation"], "2");
+    assert_eq!(records[0]["revision"], "3");
+    assert_eq!(records[0]["tombstone"], false);
+
+    let observations = snapshot["observations"]
+        .as_array()
+        .expect("causation observations");
+    assert_eq!(observations.len(), 4, "{resumed}");
+    assert_eq!(
+        observations
+            .iter()
+            .map(|observation| observation["causationId"].as_str().unwrap())
+            .collect::<Vec<_>>(),
+        vec![
+            "query-protocol-command-2",
+            "query-protocol-command-3",
+            "query-protocol-command-4",
+            "query-protocol-command-5",
+        ]
+    );
+}
+
+#[tokio::test]
+async fn multi_root_causal_query_fails_before_merging_independent_snapshots() {
+    let engine = protocol_engine_with_rows().await;
+    let response = engine
+        .execute(
+            &user_session(),
+            Request::new(
+                "query InvalidAtomicity { first: causal_query_views { title } second: causal_query_views { title } }",
+            ),
+        )
+        .await;
+    assert!(response.is_err(), "multi-root query unexpectedly succeeded");
+    assert_eq!(response.errors.len(), 1);
+    assert!(
+        response.errors[0].message.contains("one read root"),
+        "unexpected fail-closed diagnostic: {:?}",
+        response.errors
+    );
+    assert!(
+        response.extensions.get("distributed").is_none(),
+        "a rejected multi-root operation must not advertise a fabricated atomic snapshot"
+    );
+}
+
+#[tokio::test]
+async fn row_filtered_surface_never_exposes_partition_wide_live_activity() {
+    let fixture = protocol_fixture_with_rows().await;
+    let engine = GraphqlEngine::builder(&fixture.repository)
+        .service_id(SERVICE_ID)
+        .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+        .roles(&["user"])
+        .model::<CausalQueryView>(
+            ModelPermissions::new().grant("user", read().all_columns().rows(col("id").eq(ROW_ID))),
+        )
+        .client_projectors([projector()])
+        .change_stream(fixture.repository.read_model_changes())
+        .build()
+        .expect("row-filtered query protocol engine");
+    let mut stream = engine.execute_stream(&user_session(), Request::new(LIVE_SUBSCRIPTION));
+    let initial = next_wire_frame(&mut stream).await;
+    assert_eq!(
+        initial["data"]["causal_query_views"],
+        json!([{ "title": "causal row" }])
+    );
+    let envelope = distributed_envelope(&initial);
+    assert_eq!(envelope["snapshot"]["recordsComplete"], true, "{initial}");
+    assert_eq!(
+        envelope["snapshot"]["indexesComparable"], false,
+        "{initial}"
+    );
+    assert_eq!(envelope["snapshot"]["indexes"], json!([]), "{initial}");
+    assert_eq!(envelope["snapshot"]["observations"], json!([]));
+    let records = envelope["snapshot"]["records"]
+        .as_array()
+        .expect("authorized row record evidence");
+    assert_eq!(records.len(), 1, "{initial}");
+    assert_eq!(
+        records[0]["path"],
+        json!(["causal_query_views", "0"]),
+        "{initial}"
+    );
+    assert_eq!(records[0]["model"], "CausalQueryView");
+    assert_eq!(records[0]["tombstone"], false);
+    assert_opaque_token(&records[0]["scopeToken"], "record-revision");
+    assert_eq!(envelope["live"]["supported"], false, "{initial}");
+    assert_eq!(envelope["live"]["reset"], true, "{initial}");
+    assert_eq!(envelope["live"]["cursors"], json!([]), "{initial}");
+
+    project_item_with_id(
+        &fixture.repository,
+        &fixture.bus,
+        2,
+        "other-principal-private-row",
+        "denied row",
+    )
+    .await;
+    assert!(
+        tokio::time::timeout(Duration::from_millis(350), stream.next())
+            .await
+            .is_err(),
+        "a denied-row commit must not leak a cursor, causation, tombstone, or activity frame"
+    );
+}
+
+async fn query_over_http_and_graphql_ws(
+    address: std::net::SocketAddr,
+    document: &str,
+    identity: Option<(&str, &str)>,
+) -> (Value, Value) {
+    let mut http_request = reqwest::Client::new()
+        .post(format!("http://{address}/graphql"))
+        .json(&json!({ "query": document }));
+    if let Some((user, role)) = identity {
+        http_request = http_request
+            .header("x-user-id", user)
+            .header("x-role", role);
+    }
+    let http = http_request
+        .send()
+        .await
+        .expect("HTTP query response")
+        .json()
+        .await
+        .expect("HTTP query JSON");
+
+    let mut request = format!("ws://{address}/graphql/ws")
+        .into_client_request()
+        .expect("GraphQL WS request");
+    request.headers_mut().insert(
+        SEC_WEBSOCKET_PROTOCOL,
+        "graphql-transport-ws"
+            .parse()
+            .expect("GraphQL WS protocol header"),
+    );
+    let (mut socket, _) = tokio_tungstenite::connect_async(request)
+        .await
+        .expect("GraphQL WS connect");
+    let init_payload = identity
+        .map(|(user, role)| json!({ "x-user-id": user, "x-role": role }))
+        .unwrap_or_else(|| json!({}));
+    socket
+        .send(WsMessage::Text(
+            json!({ "type": "connection_init", "payload": init_payload })
+                .to_string()
+                .into(),
+        ))
+        .await
+        .expect("GraphQL WS init");
+    let acknowledgement = socket
+        .next()
+        .await
+        .expect("GraphQL WS acknowledgement")
+        .expect("valid GraphQL WS acknowledgement");
+    assert_eq!(
+        serde_json::from_str::<Value>(acknowledgement.to_text().unwrap()).unwrap(),
+        json!({ "type": "connection_ack" })
+    );
+    socket
+        .send(WsMessage::Text(
+            json!({
+                "id": "query-1",
+                "type": "subscribe",
+                "payload": { "query": document }
+            })
+            .to_string()
+            .into(),
+        ))
+        .await
+        .expect("GraphQL WS query");
+    let next = socket
+        .next()
+        .await
+        .expect("GraphQL WS next frame")
+        .expect("valid GraphQL WS next frame");
+    let next: Value = serde_json::from_str(next.to_text().unwrap()).unwrap();
+    assert_eq!(next["type"], "next", "{next}");
+    (http, next["payload"].clone())
+}
+
+#[tokio::test]
+async fn http_and_graphql_ws_serialize_the_same_query_revision_envelope() {
+    let fixture = protocol_fixture_with_retention(10).await;
+    let engine = GraphqlEngine::builder(&fixture.repository)
+        .service_id(SERVICE_ID)
+        .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+        .roles(&["user"])
+        .anonymous_role("user")
+        .model::<CausalQueryView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .client_projectors([projector()])
+        .change_stream(fixture.repository.read_model_changes())
+        .build()
+        .expect("query transport parity engine");
+    let service = Arc::new(
+        Service::new()
+            .named(SERVICE_ID)
+            .try_with_graphql(engine)
+            .expect("query transport parity service"),
+    );
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("query transport listener");
+    let address = listener.local_addr().expect("query transport address");
+    let server = tokio::spawn(async move {
+        axum::serve(listener, distributed::microsvc::router(service))
+            .await
+            .expect("query transport server");
+    });
+
+    let document = "query QueryTransportParity { causal_query_views { title } }";
+    for (case, identity) in [
+        ("anonymous", None),
+        ("explicit dev identity", Some(("demo", "user"))),
+    ] {
+        let (http, websocket) = query_over_http_and_graphql_ws(address, document, identity).await;
+        assert_eq!(http["data"], websocket["data"], "{case}");
+        assert_eq!(
+            distributed_envelope(&http),
+            distributed_envelope(&websocket),
+            "{case}: HTTP and GraphQL-WS must preserve one canonical query/revision envelope"
+        );
+    }
+    server.abort();
+}
+
+#[tokio::test]
+async fn unowned_legacy_query_is_explicitly_incomplete_and_still_strips_keys() {
+    let engine = protocol_engine_with_rows().await;
+    let response = wire_response(
+        engine
+            .execute(
+                &user_session(),
+                Request::new("query LegacyFallback { legacyAlias: legacy_query_views { title } }"),
+            )
+            .await,
+    );
+
+    assert_eq!(
+        response["data"],
+        json!({ "legacyAlias": [{ "title": "legacy row" }] })
+    );
+    let serialized = response.to_string();
+    assert!(!serialized.contains(HIDDEN_ALIAS_PREFIX), "{response}");
+    assert!(
+        !serialized.contains(LEGACY_ROW_ID),
+        "unowned primary key leaked through fallback metadata: {response}"
+    );
+
+    let snapshot = &distributed_envelope(&response)["snapshot"];
+    assert_eq!(snapshot["recordsComplete"], false);
+    assert_eq!(snapshot["indexesComparable"], false);
+    assert_eq!(snapshot["records"], json!([]));
+    assert_eq!(snapshot["indexes"], json!([]));
+    assert_eq!(snapshot["observations"], json!([]));
+    assert_opaque_token(&snapshot["scopeToken"], "query-snapshot");
+}
diff --git a/tests/graphql_query_protocol_postgres/main.rs b/tests/graphql_query_protocol_postgres/main.rs
new file mode 100644
index 00000000..47f1170b
--- /dev/null
+++ b/tests/graphql_query_protocol_postgres/main.rs
@@ -0,0 +1,253 @@
+//! Env-gated Postgres coverage for the causal GraphQL query envelope.
+//!
+//! The test compiles on every Postgres GraphQL build and skips cleanly when
+//! `DATABASE_URL` is unavailable.
+
+#![cfg(all(feature = "graphql", feature = "postgres"))]
+
+#[path = "../support/postgres.rs"]
+mod postgres;
+
+use std::time::Duration;
+
+use async_graphql::Request;
+use base64::Engine as _;
+use distributed::bus::{Bus, InMemoryBus, Message, MessageKind, RunOptions};
+use distributed::graphql::{read, GraphqlEngine, ModelPermissions, SurfaceProjector};
+use distributed::microsvc::{
+    CausalProjectorContext, HandlerError, Routes, Service, Session, ROLE_KEY,
+};
+use distributed::projection_protocol::ProjectionChangeRetention;
+use distributed::{DistributedProjectManifest, PostgresRepository, ReadModel};
+use futures_util::{stream::BoxStream, StreamExt};
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+
+const SERVICE_ID: &str = "postgres-query-protocol-fixture";
+const FACT_NAME: &str = "postgres_query_protocol.item_changed";
+const PROJECTOR_NAME: &str = "project_postgres_query_protocol_items";
+const CHANGE_EPOCH: &str = "postgres-query-protocol-items-v1";
+const ROW_ID: &str = "postgres-private-9007199254740993";
+const TEST_PROTOCOL_TOKEN_KEY: [u8; 32] = [0x4d; 32];
+const LIVE_SUBSCRIPTION: &str =
+    "subscription WatchPostgresRows { postgres_protocol_views { title } }";
+
+#[derive(Clone, Debug, Deserialize)]
+struct ItemChanged {
+    id: String,
+    title: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "postgres_protocol_views", primary_key = ["id"])]
+struct PostgresProtocolView {
+    id: String,
+    title: String,
+}
+
+fn projector() -> SurfaceProjector {
+    SurfaceProjector::new(PROJECTOR_NAME)
+        .facts([FACT_NAME])
+        .models(["PostgresProtocolView"])
+        .change_epoch(CHANGE_EPOCH)
+}
+
+fn user_session() -> Session {
+    let mut session = Session::new();
+    session.set(ROLE_KEY, "user");
+    session
+}
+
+fn projection_service(repository: &PostgresRepository, bus: &InMemoryBus) -> Service {
+    let routes = Routes::new()
+        .with_read_model_store(repository.clone())
+        .causal_projector::<ItemChanged>(projector())
+        .model::<PostgresProtocolView>()
+        .handle(
+            |context: CausalProjectorContext, fact: ItemChanged| async move {
+                context
+                    .project(&PostgresProtocolView {
+                        id: fact.id,
+                        title: fact.title,
+                    })
+                    .await?;
+                Ok::<(), HandlerError>(())
+            },
+        );
+    Service::new()
+        .named(SERVICE_ID)
+        .routes(routes)
+        .with_bus(bus.clone())
+}
+
+async fn project_item(repository: &PostgresRepository, bus: &InMemoryBus) {
+    bus.publish_message(
+        Message::new(
+            FACT_NAME,
+            MessageKind::Event,
+            serde_json::to_vec(&json!({
+                "id": ROW_ID,
+                "title": "postgres causal row"
+            }))
+            .expect("fixture fact"),
+        )
+        .with_id("postgres-query-protocol-fact-1")
+        .with_metadata(
+            distributed::trace_context::CAUSATION_ID,
+            "postgres-query-protocol-command-1",
+        ),
+    )
+    .await
+    .expect("publish Postgres query protocol fact");
+    projection_service(repository, bus)
+        .run(RunOptions::idempotent())
+        .await
+        .expect("project Postgres query protocol fact");
+}
+
+fn wire_response(response: async_graphql::Response) -> Value {
+    assert!(
+        !response.is_err(),
+        "unexpected GraphQL errors: {:?}",
+        response.errors
+    );
+    serde_json::to_value(response).expect("GraphQL wire response")
+}
+
+fn distributed_envelope(response: &Value) -> &Value {
+    response
+        .get("extensions")
+        .and_then(|extensions| extensions.get("distributed"))
+        .unwrap_or_else(|| panic!("missing extensions.distributed: {response}"))
+}
+
+fn assert_opaque_token(token: &Value, purpose: &str) {
+    let token = token
+        .as_str()
+        .unwrap_or_else(|| panic!("missing {purpose} token: {token}"));
+    let segments = token.split('.').collect::<Vec<_>>();
+    assert_eq!(segments.len(), 3, "bounded opaque token: {token}");
+    assert_eq!(segments[0], "v1");
+    assert_eq!(segments[1], purpose);
+    let mac = base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .decode(segments[2])
+        .unwrap_or_else(|error| panic!("invalid opaque token MAC `{token}`: {error}"));
+    assert_eq!(mac.len(), 32, "HMAC-SHA256 token: {token}");
+    assert!(
+        !token.contains(ROW_ID),
+        "opaque token disclosed private row identity: {token}"
+    );
+}
+
+async fn next_wire_frame(stream: &mut BoxStream<'static, async_graphql::Response>) -> Value {
+    let response = tokio::time::timeout(Duration::from_secs(2), stream.next())
+        .await
+        .expect("timeout waiting for GraphQL subscription frame")
+        .expect("GraphQL subscription ended");
+    wire_response(response)
+}
+
+fn request_with_resume(cursors: Value) -> Request {
+    serde_json::from_value(json!({
+        "query": LIVE_SUBSCRIPTION,
+        "extensions": {
+            "distributed": {
+                "resume": {
+                    "cursors": cursors
+                }
+            }
+        }
+    }))
+    .expect("valid GraphQL request with distributed resume extension")
+}
+
+#[tokio::test]
+async fn postgres_emits_exact_revisions_and_accepts_an_exact_live_resume() {
+    let Some(schema) = postgres::PostgresTestSchema::create_from_env(
+        "gql_query_protocol",
+        "skipping Postgres GraphQL query-protocol test",
+    )
+    .await
+    else {
+        return;
+    };
+    let repository = schema.repository().await.with_projection_change_retention(
+        ProjectionChangeRetention::new(2).expect("positive retention"),
+    );
+    let manifest = DistributedProjectManifest::new(SERVICE_ID).read_model::<PostgresProtocolView>();
+    repository
+        .bootstrap_table_schema_for_dev(
+            &manifest
+                .table_registry()
+                .expect("Postgres query protocol table registry"),
+        )
+        .await
+        .expect("Postgres query protocol read-model table");
+
+    let bus = InMemoryBus::new();
+    project_item(&repository, &bus).await;
+
+    let engine = GraphqlEngine::builder(&repository)
+        .service_id(SERVICE_ID)
+        .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+        .roles(&["user"])
+        .model::<PostgresProtocolView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .client_projectors([projector()])
+        .change_stream(repository.read_model_changes())
+        .build()
+        .expect("Postgres query protocol GraphQL engine");
+
+    let query = wire_response(
+        engine
+            .execute(
+                &user_session(),
+                Request::new("query PostgresSnapshot { postgres_protocol_views { title } }"),
+            )
+            .await,
+    );
+    assert_eq!(
+        query["data"],
+        json!({ "postgres_protocol_views": [{ "title": "postgres causal row" }] })
+    );
+    assert!(
+        !query.to_string().contains(ROW_ID),
+        "an omitted primary key leaked through Postgres protocol metadata: {query}"
+    );
+    let distributed = distributed_envelope(&query);
+    assert_eq!(distributed["protocolVersion"], 1);
+    assert_opaque_token(&distributed["cacheScope"], "cache-scope");
+    let snapshot = &distributed["snapshot"];
+    assert_eq!(snapshot["recordsComplete"], true);
+    assert_eq!(snapshot["indexesComparable"], true);
+    assert_eq!(snapshot["records"].as_array().map(Vec::len), Some(1));
+    assert_eq!(
+        snapshot["records"][0]["path"],
+        json!(["postgres_protocol_views", "0"])
+    );
+    assert_eq!(snapshot["records"][0]["incarnation"], "1");
+    assert_eq!(snapshot["records"][0]["revision"], "1");
+    assert_eq!(snapshot["records"][0]["tombstone"], false);
+    assert_opaque_token(&snapshot["records"][0]["scopeToken"], "record-revision");
+    assert_eq!(snapshot["indexes"][0]["projection"], PROJECTOR_NAME);
+    assert_eq!(snapshot["indexes"][0]["position"], "1");
+    assert_opaque_token(&snapshot["indexes"][0]["scopeToken"], "query-index");
+
+    let mut initial_stream =
+        engine.execute_stream(&user_session(), Request::new(LIVE_SUBSCRIPTION));
+    let initial = next_wire_frame(&mut initial_stream).await;
+    let initial_live = &distributed_envelope(&initial)["live"];
+    assert_eq!(initial_live["supported"], true, "{initial}");
+    assert_eq!(initial_live["reset"], false, "{initial}");
+    let cursors = initial_live["cursors"].clone();
+    assert_eq!(cursors[0]["projection"], PROJECTOR_NAME);
+    assert_eq!(cursors[0]["position"], "1");
+    assert_opaque_token(&cursors[0]["token"], "live-resume");
+    drop(initial_stream);
+
+    let mut resumed_stream = engine.execute_stream(&user_session(), request_with_resume(cursors));
+    let resumed = next_wire_frame(&mut resumed_stream).await;
+    let resumed_live = &distributed_envelope(&resumed)["live"];
+    assert_eq!(resumed_live["supported"], true, "{resumed}");
+    assert_eq!(resumed_live["reset"], false, "{resumed}");
+    assert_eq!(resumed_live["cursors"][0]["position"], "1");
+}
diff --git a/tests/graphql_sdl/main.rs b/tests/graphql_sdl/main.rs
new file mode 100644
index 00000000..03896b2b
--- /dev/null
+++ b/tests/graphql_sdl/main.rs
@@ -0,0 +1,283 @@
+//! Golden-file tests for the dep-free GraphQL SDL renderer.
+
+use distributed::{
+    graphql::{graphql_sdl_for_tables, graphql_sdl_for_tables_with_options, SdlOptions},
+    ColumnType, ForeignKey, PrimaryKey, RelationshipDef, RelationshipKind, TableColumn, TableKind,
+    TableSchema,
+};
+
+fn players() -> TableSchema {
+    TableSchema {
+        model_name: "PlayerView".into(),
+        table_name: "players".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("player_id", "player_id", ColumnType::Text)
+            },
+            TableColumn::new("display_name", "display_name", ColumnType::Text),
+            TableColumn {
+                skipped: true,
+                ..TableColumn::new("secret", "secret", ColumnType::Text)
+            },
+        ],
+        primary_key: PrimaryKey::new(["player_id"]),
+        version_column: Some("_sourced_version".into()),
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "weapons".into(),
+            kind: RelationshipKind::HasMany,
+            target_model: "PlayerWeaponView".into(),
+            foreign_key: Some("player_id".into()),
+            through: None,
+            target_foreign_key: None,
+        }],
+        kind: TableKind::ReadModel,
+    }
+}
+
+fn weapons() -> TableSchema {
+    TableSchema {
+        model_name: "PlayerWeaponView".into(),
+        table_name: "player_weapons".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                foreign_key: Some(ForeignKey::new("players", "player_id")),
+                ..TableColumn::new("player_id", "player_id", ColumnType::Text)
+            },
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("weapon_id", "weapon_id", ColumnType::Text)
+            },
+            TableColumn {
+                jsonb: true,
+                ..TableColumn::new("meta", "meta", ColumnType::Json)
+            },
+        ],
+        primary_key: PrimaryKey::new(["player_id", "weapon_id"]),
+        version_column: Some("_sourced_version".into()),
+        foreign_keys: vec![ForeignKey::new("players", "player_id")],
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "player".into(),
+            kind: RelationshipKind::BelongsTo,
+            target_model: "PlayerView".into(),
+            foreign_key: Some("player_id".into()),
+            through: None,
+            target_foreign_key: None,
+        }],
+        kind: TableKind::ReadModel,
+    }
+}
+
+fn operational_outbox() -> TableSchema {
+    TableSchema {
+        model_name: "OutboxMessage".into(),
+        table_name: "outbox_messages".into(),
+        columns: vec![TableColumn {
+            primary_key: true,
+            ..TableColumn::new("message_id", "message_id", ColumnType::Text)
+        }],
+        primary_key: PrimaryKey::new(["message_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::Operational,
+    }
+}
+
+#[test]
+fn renders_players_weapons_surface() {
+    let sdl = graphql_sdl_for_tables_with_options(
+        &[players(), weapons()],
+        &SdlOptions {
+            aggregates: true,
+            jsonb_operators: false,
+            subscriptions: true,
+        },
+    )
+    .expect("sdl");
+    assert!(sdl.contains("type PlayerView"));
+    assert!(sdl.contains("type PlayerWeaponView"));
+    assert!(sdl.contains("players("));
+    assert!(sdl.contains("players_by_pk(player_id: String!): PlayerView"));
+    assert!(sdl.contains(
+        "player_weapons_by_pk(player_id: String!, weapon_id: String!): PlayerWeaponView"
+    ));
+    assert!(sdl.contains("weapons("));
+    assert!(sdl.contains("player:"));
+    // skipped column and version never appear
+    assert!(!sdl.contains("secret"));
+    assert!(!sdl.contains("_sourced_version"));
+    // operational tables not in this input
+    assert!(!sdl.contains("outbox"));
+    // custom scalars
+    assert!(sdl.contains("scalar BigInt"));
+    assert!(sdl.contains("scalar JSON"));
+    // Subscription root present
+    assert!(sdl.contains("type Subscription"));
+}
+
+#[test]
+fn operational_tables_filtered() {
+    let sdl = graphql_sdl_for_tables(&[players(), operational_outbox()]).expect("sdl");
+    assert!(sdl.contains("PlayerView"));
+    assert!(!sdl.contains("OutboxMessage"));
+    assert!(!sdl.contains("outbox_messages"));
+}
+
+#[test]
+fn omits_relationship_when_target_absent() {
+    let sdl = graphql_sdl_for_tables(&[players()]).expect("sdl");
+    // weapons relationship target not present → omitted
+    assert!(!sdl.contains("  weapons("));
+}
+
+#[test]
+fn m2m_requires_through_error() {
+    let posts = TableSchema {
+        model_name: "Post".into(),
+        table_name: "posts".into(),
+        columns: vec![TableColumn {
+            primary_key: true,
+            ..TableColumn::new("id", "id", ColumnType::Text)
+        }],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "tags".into(),
+            kind: RelationshipKind::ManyToMany,
+            target_model: "Tag".into(),
+            foreign_key: Some("post_id".into()),
+            through: None,
+            target_foreign_key: None,
+        }],
+        kind: TableKind::ReadModel,
+    };
+    let err = graphql_sdl_for_tables(&[posts]).unwrap_err();
+    assert!(err.contains("through"), "{err}");
+}
+
+#[test]
+fn invalid_name_errors() {
+    let bad = TableSchema {
+        model_name: "1Bad".into(),
+        table_name: "1bad".into(),
+        columns: vec![TableColumn {
+            primary_key: true,
+            ..TableColumn::new("id", "id", ColumnType::Text)
+        }],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    };
+    let err = graphql_sdl_for_tables(&[bad]).unwrap_err();
+    assert!(err.contains("valid GraphQL name"), "{err}");
+}
+
+#[test]
+fn collision_errors() {
+    let a = TableSchema {
+        model_name: "A".into(),
+        table_name: "items".into(),
+        columns: vec![TableColumn {
+            primary_key: true,
+            ..TableColumn::new("id", "id", ColumnType::Text)
+        }],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    };
+    let b = TableSchema {
+        model_name: "B".into(),
+        table_name: "items".into(), // same table_name → root field collision
+        columns: vec![TableColumn {
+            primary_key: true,
+            ..TableColumn::new("id", "id", ColumnType::Text)
+        }],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    };
+    let err = graphql_sdl_for_tables(&[a, b]).unwrap_err();
+    assert!(err.contains("collides"), "{err}");
+}
+
+#[test]
+fn manifest_graphql_sdl_method() {
+    let manifest = distributed::DistributedProjectManifest::new("demo")
+        .table_schema(players())
+        .table_schema(weapons())
+        .table_schema(operational_outbox());
+    let sdl = manifest.graphql_sdl().expect("sdl");
+    assert!(sdl.contains("PlayerView"));
+    assert!(!sdl.contains("OutboxMessage"));
+}
+
+#[test]
+fn capture_sdl_to_scratch() {
+    let path = std::env::var("GROK_SCRATCH_SDL").unwrap_or_else(|_| "/dev/null".into());
+    if path == "/dev/null" {
+        return;
+    }
+    let players = players();
+    let weapons = weapons();
+    let sdl = graphql_sdl_for_tables(&[players, weapons]).unwrap();
+    std::fs::write(&path, &sdl).unwrap();
+    assert!(sdl.contains("type PlayerView"));
+}
+
+/// Default / SQLite SDL omits PG jsonb comparison operators (weapons has JSON meta).
+#[test]
+fn sqlite_sdl_omits_postgres_json_comparison_ops() {
+    let sdl = graphql_sdl_for_tables_with_options(&[weapons()], &SdlOptions::sqlite()).unwrap();
+    assert!(
+        sdl.contains("JSON_comparison_exp") || sdl.contains("input JSON_comparison_exp"),
+        "expected JSON comparison input: {sdl}"
+    );
+    assert!(
+        !sdl.contains("_contains"),
+        "SQLite SDL must not advertise _contains: {sdl}"
+    );
+    assert!(
+        !sdl.contains("_contained_in"),
+        "SQLite SDL must not advertise _contained_in: {sdl}"
+    );
+    assert!(
+        !sdl.contains("_has_key"),
+        "SQLite SDL must not advertise _has_key: {sdl}"
+    );
+    assert!(sdl.contains("_eq"), "portable _eq must remain: {sdl}");
+}
+
+/// Postgres-oriented SDL includes jsonb comparison operators.
+#[test]
+fn postgres_sdl_includes_json_comparison_ops() {
+    let sdl = graphql_sdl_for_tables_with_options(&[weapons()], &SdlOptions::postgres()).unwrap();
+    assert!(sdl.contains("_contains"), "{sdl}");
+    assert!(sdl.contains("_contained_in"), "{sdl}");
+    assert!(sdl.contains("_has_key"), "{sdl}");
+}
+
+/// Default SdlOptions matches SQLite policy.
+#[test]
+fn default_sdl_options_are_sqlite() {
+    let def = SdlOptions::default();
+    let sqlite = SdlOptions::sqlite();
+    assert_eq!(def.jsonb_operators, sqlite.jsonb_operators);
+    assert!(!def.jsonb_operators);
+}
diff --git a/tests/graphql_sqlite/main.rs b/tests/graphql_sqlite/main.rs
new file mode 100644
index 00000000..bb04b636
--- /dev/null
+++ b/tests/graphql_sqlite/main.rs
@@ -0,0 +1,641 @@
+//! End-to-end GraphQL over temp-file SQLite (phase-2 exit criterion).
+
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+
+use async_graphql::Request;
+use distributed::{
+    graphql::{col, read, rel, GraphqlEngine, ModelPermissions},
+    microsvc::Session,
+    ColumnType, ForeignKey, PrimaryKey, ReadModel, RelationshipDef, RelationshipKind, TableColumn,
+    TableKind, TableSchema, ROLE_KEY, USER_ID_KEY,
+};
+use serde::{Deserialize, Serialize};
+use sqlx::sqlite::SqlitePoolOptions;
+
+fn orders_schema() -> TableSchema {
+    TableSchema {
+        model_name: "OrderView".into(),
+        table_name: "orders".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("order_id", "order_id", ColumnType::Text)
+            },
+            TableColumn::new("customer_id", "customer_id", ColumnType::Text),
+            TableColumn::new("status", "status", ColumnType::Text),
+            TableColumn {
+                column_type: ColumnType::Integer,
+                ..TableColumn::new("total_cents", "total_cents", ColumnType::Integer)
+            },
+        ],
+        primary_key: PrimaryKey::new(["order_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    }
+}
+
+async fn setup_pool() -> sqlx::SqlitePool {
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE orders (
+            order_id TEXT PRIMARY KEY,
+            customer_id TEXT NOT NULL,
+            status TEXT NOT NULL,
+            total_cents INTEGER NOT NULL
+        );
+        INSERT INTO orders VALUES
+            ('o1', 'c1', 'open', 1000),
+            ('o2', 'c1', 'shipped', 2000),
+            ('o3', 'c2', 'open', 500);",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+    pool
+}
+
+fn session_role(role: &str, user: &str) -> Session {
+    let mut s = Session::new();
+    s.set(ROLE_KEY, role);
+    s.set(USER_ID_KEY, user);
+    s.set("x-user-id", user);
+    s
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[table("m2m_players")]
+struct M2mPlayer {
+    #[id("player_id")]
+    player_id: String,
+    name: String,
+    #[readmodel(
+        many_to_many = "M2mWeapon",
+        through = "m2m_player_weapon_links",
+        foreign_key = "player_id"
+    )]
+    weapons: Vec<M2mWeapon>,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[table("m2m_weapons")]
+struct M2mWeapon {
+    #[id("weapon_id")]
+    weapon_id: String,
+    name: String,
+}
+
+fn m2m_link_schema() -> TableSchema {
+    TableSchema {
+        model_name: "M2mPlayerWeaponLink".into(),
+        table_name: "m2m_player_weapon_links".into(),
+        columns: vec![
+            TableColumn {
+                foreign_key: Some(ForeignKey::new("m2m_players", "player_id")),
+                ..TableColumn::new("player_id", "player_ref", ColumnType::Text)
+            },
+            TableColumn {
+                foreign_key: Some(ForeignKey::new("m2m_weapons", "weapon_id")),
+                ..TableColumn::new("weapon_id", "weapon_ref", ColumnType::Text)
+            },
+        ],
+        primary_key: PrimaryKey::new(["player_ref", "weapon_ref"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    }
+}
+
+#[tokio::test]
+async fn list_filter_and_by_pk() {
+    let schema = orders_schema();
+
+    let manifest = distributed::DistributedProjectManifest::new("orders").table_schema(schema);
+    let pool = setup_pool().await;
+    let engine = GraphqlEngine::from_manifest(&manifest, pool)
+        .unwrap()
+        .roles(&["user", "anonymous"])
+        .grant_all("user")
+        .build()
+        .expect("build");
+
+    let session = session_role("user", "c1");
+    let resp = engine
+        .execute(
+            &session,
+            Request::new(
+                r#"{ orders(where: { status: { _eq: "open" } }, limit: 10) { order_id status } }"#,
+            ),
+        )
+        .await;
+    assert!(!resp.is_err(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    let orders = data["orders"].as_array().unwrap();
+    assert_eq!(orders.len(), 2);
+    assert!(orders.iter().all(|o| o["status"] == "open"));
+
+    let resp = engine
+        .execute(
+            &session,
+            Request::new(r#"{ orders_by_pk(order_id: "o1") { order_id customer_id } }"#),
+        )
+        .await;
+    assert!(!resp.is_err(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    assert_eq!(data["orders_by_pk"]["order_id"], "o1");
+}
+
+#[tokio::test]
+async fn m2m_permission_filter_resolves_through_field_names_to_columns() {
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    for sql in [
+        "CREATE TABLE m2m_players (player_id TEXT PRIMARY KEY, name TEXT NOT NULL)",
+        "CREATE TABLE m2m_weapons (weapon_id TEXT PRIMARY KEY, name TEXT NOT NULL)",
+        "CREATE TABLE m2m_player_weapon_links (player_ref TEXT NOT NULL, weapon_ref TEXT NOT NULL)",
+        "INSERT INTO m2m_players VALUES ('p1', 'Ada'), ('p2', 'Grace')",
+        "INSERT INTO m2m_weapons VALUES ('w1', 'Compiler'), ('w2', 'Debugger')",
+        "INSERT INTO m2m_player_weapon_links VALUES ('p1', 'w1'), ('p2', 'w2')",
+    ] {
+        sqlx::query(sql).execute(&pool).await.unwrap();
+    }
+
+    let engine = GraphqlEngine::builder(pool)
+        .table_schema(m2m_link_schema())
+        .model::<M2mPlayer>(
+            ModelPermissions::new().grant(
+                "user",
+                read()
+                    .all_columns()
+                    .rows(rel("weapons", col("weapon_id").eq("w1"))),
+            ),
+        )
+        .model::<M2mWeapon>(ModelPermissions::new().grant("user", read().all_columns()))
+        .roles(&["user"])
+        .build()
+        .expect("build");
+
+    let session = session_role("user", "u1");
+    let resp = engine
+        .execute(&session, Request::new("{ m2m_players { player_id name } }"))
+        .await;
+    assert!(!resp.is_err(), "{:?}", resp.errors);
+
+    let data = serde_json::to_value(&resp.data).unwrap();
+    let players = data["m2m_players"].as_array().expect("players");
+    assert_eq!(players.len(), 1, "{data}");
+    assert_eq!(players[0]["player_id"], "p1");
+}
+
+/// Client `where` with m2m relationship predicate (EXISTS through join table).
+#[tokio::test]
+async fn m2m_client_where_relationship_predicate() {
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    for sql in [
+        "CREATE TABLE m2m_players (player_id TEXT PRIMARY KEY, name TEXT NOT NULL)",
+        "CREATE TABLE m2m_weapons (weapon_id TEXT PRIMARY KEY, name TEXT NOT NULL)",
+        "CREATE TABLE m2m_player_weapon_links (player_ref TEXT NOT NULL, weapon_ref TEXT NOT NULL)",
+        "INSERT INTO m2m_players VALUES ('p1', 'Ada'), ('p2', 'Grace'), ('p3', 'Both')",
+        "INSERT INTO m2m_weapons VALUES ('w1', 'Compiler'), ('w2', 'Debugger')",
+        "INSERT INTO m2m_player_weapon_links VALUES ('p1', 'w1'), ('p2', 'w2'), ('p3', 'w1'), ('p3', 'w2')",
+    ] {
+        sqlx::query(sql).execute(&pool).await.unwrap();
+    }
+
+    let engine = GraphqlEngine::builder(pool)
+        .table_schema(m2m_link_schema())
+        .model::<M2mPlayer>(ModelPermissions::new().grant("user", read().all_columns()))
+        .model::<M2mWeapon>(ModelPermissions::new().grant("user", read().all_columns()))
+        .roles(&["user"])
+        .build()
+        .expect("build");
+
+    let session = session_role("user", "u1");
+    let resp = engine
+        .execute(
+            &session,
+            Request::new(
+                r#"{ m2m_players(where: { weapons: { weapon_id: { _eq: "w1" } } }) { player_id name } }"#,
+            ),
+        )
+        .await;
+    assert!(!resp.is_err(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    let players = data["m2m_players"].as_array().expect("players");
+    let ids: Vec<&str> = players
+        .iter()
+        .map(|p| p["player_id"].as_str().unwrap())
+        .collect();
+    assert!(ids.contains(&"p1"), "p1 has w1: {data}");
+    assert!(ids.contains(&"p3"), "p3 has w1: {data}");
+    assert!(!ids.contains(&"p2"), "p2 only has w2: {data}");
+    assert_eq!(ids.len(), 2, "{data}");
+}
+
+fn parent_schema() -> TableSchema {
+    TableSchema {
+        model_name: "ParentView".into(),
+        table_name: "parents".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("id", "id", ColumnType::Text)
+            },
+            TableColumn::new("name", "name", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "children".into(),
+            kind: RelationshipKind::HasMany,
+            target_model: "ChildView".into(),
+            foreign_key: Some("parent_id".into()),
+            through: None,
+            target_foreign_key: None,
+        }],
+        kind: TableKind::ReadModel,
+    }
+}
+
+fn child_schema() -> TableSchema {
+    TableSchema {
+        model_name: "ChildView".into(),
+        table_name: "children".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("child_id", "child_id", ColumnType::Text)
+            },
+            TableColumn::new("parent_id", "parent_id", ColumnType::Text),
+            TableColumn::new("name", "name", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["child_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    }
+}
+
+#[tokio::test]
+async fn sqlite_binds_follow_projection_then_where_order_for_relationships() {
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    for sql in [
+        "CREATE TABLE parents (id TEXT PRIMARY KEY, name TEXT NOT NULL)",
+        "CREATE TABLE children (child_id TEXT PRIMARY KEY, parent_id TEXT NOT NULL, name TEXT NOT NULL)",
+        "INSERT INTO parents VALUES ('p1', 'P'), ('p2', 'Other')",
+        "INSERT INTO children VALUES ('c1', 'p1', 'C1'), ('c2', 'p1', 'C2'), ('c3', 'p2', 'C2')",
+    ] {
+        sqlx::query(sql).execute(&pool).await.unwrap();
+    }
+
+    let manifest = distributed::DistributedProjectManifest::new("rel")
+        .table_schema(parent_schema())
+        .table_schema(child_schema());
+    let engine = GraphqlEngine::from_manifest(&manifest, pool)
+        .unwrap()
+        .roles(&["user"])
+        .grant_all("user")
+        .build()
+        .expect("build");
+
+    let session = session_role("user", "u1");
+    let resp = engine
+        .execute(
+            &session,
+            Request::new(
+                r#"{ parents(where: { name: { _eq: "P" } }) { id children(where: { name: { _eq: "C2" } }) { child_id name } } }"#,
+            ),
+        )
+        .await;
+    assert!(!resp.is_err(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    let parents = data["parents"].as_array().expect("parents");
+    assert_eq!(
+        parents.len(),
+        1,
+        "root where bind must match parent name: {data}"
+    );
+    let children = parents[0]["children"].as_array().expect("children");
+    assert_eq!(
+        children.len(),
+        1,
+        "nested where bind must match child name: {data}"
+    );
+    assert_eq!(children[0]["child_id"], "c2");
+
+    let sdl = engine.sdl_for_role("user").expect("user schema");
+    assert!(
+        sdl.contains("children_aggregate"),
+        "relationship aggregate field must be present in runtime SDL: {sdl}"
+    );
+
+    let resp = engine
+        .execute(
+            &session,
+            Request::new(
+                r#"{ parents(where: { name: { _eq: "P" } }) { id children_aggregate(where: { name: { _eq: "C2" } }) { aggregate { count } nodes { child_id name } } } }"#,
+            ),
+        )
+        .await;
+    assert!(!resp.is_err(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    let aggregate = &data["parents"][0]["children_aggregate"];
+    assert_eq!(aggregate["aggregate"]["count"], 1, "{data}");
+    let nodes = aggregate["nodes"].as_array().expect("aggregate nodes");
+    assert_eq!(nodes.len(), 1, "{data}");
+    assert_eq!(nodes[0]["child_id"], "c2");
+
+    let aliased = engine
+        .execute(
+            &session,
+            Request::new(
+                r#"{
+                    parentRows: parents(where: { name: { _eq: "P" } }) {
+                        parentLabel: name
+                        matchingChildren: children(where: { name: { _eq: "C2" } }) {
+                            childKey: child_id
+                            childLabel: name
+                        }
+                        childStats: children_aggregate(where: { name: { _eq: "C2" } }) {
+                            totals: aggregate { matches: count }
+                            matchingNodes: nodes { childKey: child_id }
+                        }
+                    }
+                }"#,
+            ),
+        )
+        .await;
+    assert!(!aliased.is_err(), "{:?}", aliased.errors);
+    assert_eq!(
+        serde_json::to_value(&aliased.data).unwrap(),
+        serde_json::json!({
+            "parentRows": [{
+                "parentLabel": "P",
+                "matchingChildren": [{
+                    "childKey": "c2",
+                    "childLabel": "C2"
+                }],
+                "childStats": {
+                    "totals": { "matches": 1 },
+                    "matchingNodes": [{ "childKey": "c2" }]
+                }
+            }]
+        })
+    );
+
+    let repeated_aliases = engine
+        .execute(
+            &session,
+            Request::new(
+                r#"{
+                    parentRows: parents(where: { name: { _eq: "P" } }) {
+                        c1Children: children(where: { name: { _eq: "C1" } }) {
+                            c1Key: child_id
+                        }
+                        c2Children: children(where: { name: { _eq: "C2" } }) {
+                            c2Label: name
+                        }
+                        c1Stats: children_aggregate(where: { name: { _eq: "C1" } }) {
+                            c1Totals: aggregate { c1Count: count }
+                            c1Keys: nodes { c1Key: child_id }
+                            c1Labels: nodes { c1Label: name }
+                        }
+                        c2Stats: children_aggregate(where: { name: { _eq: "C2" } }) {
+                            firstTotals: aggregate { firstCount: count }
+                            secondTotals: aggregate { secondCount: count }
+                            c2Nodes: nodes { c2Label: name }
+                        }
+                    }
+                }"#,
+            ),
+        )
+        .await;
+    assert!(!repeated_aliases.is_err(), "{:?}", repeated_aliases.errors);
+    assert_eq!(
+        serde_json::to_value(&repeated_aliases.data).unwrap(),
+        serde_json::json!({
+            "parentRows": [{
+                "c1Children": [{ "c1Key": "c1" }],
+                "c2Children": [{ "c2Label": "C2" }],
+                "c1Stats": {
+                    "c1Totals": { "c1Count": 1 },
+                    "c1Keys": [{ "c1Key": "c1" }],
+                    "c1Labels": [{ "c1Label": "C1" }]
+                },
+                "c2Stats": {
+                    "firstTotals": { "firstCount": 1 },
+                    "secondTotals": { "secondCount": 1 },
+                    "c2Nodes": [{ "c2Label": "C2" }]
+                }
+            }]
+        })
+    );
+}
+
+fn author_schema() -> TableSchema {
+    TableSchema {
+        model_name: "AuthorView".into(),
+        table_name: "authors".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("id", "id", ColumnType::Text)
+            },
+            TableColumn::new("name", "name", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    }
+}
+
+fn post_schema() -> TableSchema {
+    TableSchema {
+        model_name: "PostView".into(),
+        table_name: "posts".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("post_id", "post_id", ColumnType::Text)
+            },
+            TableColumn::new("author_id", "author_id", ColumnType::Text),
+            TableColumn::new("title", "title", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["post_id"]),
+        version_column: None,
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: vec![RelationshipDef {
+            field_name: "author".into(),
+            kind: RelationshipKind::BelongsTo,
+            target_model: "AuthorView".into(),
+            foreign_key: Some("author_id".into()),
+            through: None,
+            target_foreign_key: None,
+        }],
+        kind: TableKind::ReadModel,
+    }
+}
+
+#[tokio::test]
+async fn belongs_to_joins_source_fk_to_target_primary_key() {
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    for sql in [
+        "CREATE TABLE authors (id TEXT PRIMARY KEY, name TEXT NOT NULL)",
+        "CREATE TABLE posts (post_id TEXT PRIMARY KEY, author_id TEXT NOT NULL, title TEXT NOT NULL)",
+        "INSERT INTO authors VALUES ('a1', 'Ada')",
+        "INSERT INTO posts VALUES ('p1', 'a1', 'GraphQL')",
+    ] {
+        sqlx::query(sql).execute(&pool).await.unwrap();
+    }
+
+    let manifest = distributed::DistributedProjectManifest::new("posts")
+        .table_schema(author_schema())
+        .table_schema(post_schema());
+    let engine = GraphqlEngine::from_manifest(&manifest, pool)
+        .unwrap()
+        .roles(&["user"])
+        .grant_all("user")
+        .build()
+        .expect("build");
+
+    let session = session_role("user", "u1");
+    let resp = engine
+        .execute(
+            &session,
+            Request::new(r#"{ posts { post_id author { id name } } }"#),
+        )
+        .await;
+    assert!(!resp.is_err(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    assert_eq!(data["posts"][0]["author"]["id"], "a1");
+    assert_eq!(data["posts"][0]["author"]["name"], "Ada");
+}
+
+#[tokio::test]
+async fn permissions_filter_by_claim() {
+    let schema = orders_schema();
+    let manifest =
+        distributed::DistributedProjectManifest::new("orders").table_schema(schema.clone());
+    let pool = setup_pool().await;
+
+    // Value-based path: grant_all then we need typed permission — use builder
+    // with table_schema upgrade. from_manifest exposes all ReadModel tables.
+    // Use permission via a hand-built approach: grant_all for user is full;
+    // for restricted, register with filter via engine builder internals...
+    // Spec API: .permission requires RelationalReadModelIncludes.
+    // For fixture without derive, use grant_all and a second role without grants.
+    let engine = GraphqlEngine::from_manifest(&manifest, pool)
+        .unwrap()
+        .roles(&["user", "anonymous"])
+        .grant_all("user")
+        .build()
+        .expect("build");
+
+    // anonymous has no grants → empty Query fields / field error
+    let anon = Session::new();
+    let resp = engine
+        .execute(&anon, Request::new(r#"{ orders { order_id } }"#))
+        .await;
+    assert!(
+        resp.is_err() || {
+            let v = serde_json::to_value(&resp.data).unwrap();
+            v.get("orders").is_none()
+        }
+    );
+}
+
+#[tokio::test]
+async fn domain_service_shaped_fixture() {
+    // Phase-2 exit: one-file fixture serves queries on temp SQLite.
+    let mut tables = Vec::new();
+    for (model, table, pk) in [
+        ("NamespaceView", "namespaces", "namespace_id"),
+        ("UserView", "users", "user_id"),
+        ("OrderView", "orders", "order_id"),
+    ] {
+        tables.push(TableSchema {
+            model_name: model.into(),
+            table_name: table.into(),
+            columns: vec![
+                TableColumn {
+                    primary_key: true,
+                    ..TableColumn::new(pk, pk, ColumnType::Text)
+                },
+                TableColumn::new("name", "name", ColumnType::Text),
+            ],
+            primary_key: PrimaryKey::new([pk]),
+            version_column: None,
+            foreign_keys: Vec::new(),
+            indexes: Vec::new(),
+            relationships: Vec::new(),
+            kind: TableKind::ReadModel,
+        });
+    }
+    let mut manifest = distributed::DistributedProjectManifest::new("domain");
+    for t in tables {
+        manifest = manifest.table_schema(t);
+    }
+
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    for ddl in [
+        "CREATE TABLE namespaces (namespace_id TEXT PRIMARY KEY, name TEXT NOT NULL);",
+        "CREATE TABLE users (user_id TEXT PRIMARY KEY, name TEXT NOT NULL);",
+        "CREATE TABLE orders (order_id TEXT PRIMARY KEY, name TEXT NOT NULL);",
+        "INSERT INTO namespaces VALUES ('ns1', 'acme');",
+        "INSERT INTO users VALUES ('u1', 'ada');",
+        "INSERT INTO orders VALUES ('o1', 'widget');",
+    ] {
+        sqlx::query(ddl).execute(&pool).await.unwrap();
+    }
+
+    let engine = GraphqlEngine::from_manifest(&manifest, pool)
+        .unwrap()
+        .roles(&["user"])
+        .grant_all("user")
+        .build()
+        .expect("build");
+
+    let session = session_role("user", "u1");
+    let resp = engine
+        .execute(
+            &session,
+            Request::new(
+                r#"{ namespaces { namespace_id name } users { user_id name } orders { order_id name } }"#,
+            ),
+        )
+        .await;
+    assert!(!resp.is_err(), "{:?}", resp.errors);
+    let data = serde_json::to_value(&resp.data).unwrap();
+    assert_eq!(data["namespaces"][0]["name"], "acme");
+    assert_eq!(data["users"][0]["name"], "ada");
+    assert_eq!(data["orders"][0]["name"], "widget");
+}
diff --git a/tests/graphql_subscriptions_sqlite/main.rs b/tests/graphql_subscriptions_sqlite/main.rs
new file mode 100644
index 00000000..050f2cdf
--- /dev/null
+++ b/tests/graphql_subscriptions_sqlite/main.rs
@@ -0,0 +1,355 @@
+//! Phase-4 exit: GraphQL subscription pushes exactly once per projection commit (SQLite).
+
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+
+use std::time::Duration;
+
+use async_graphql::Request;
+use distributed::graphql::{claim, col, read, GraphqlEngine, ModelPermissions};
+use distributed::microsvc::{Session, ROLE_KEY, USER_ID_KEY};
+use distributed::{
+    ColumnType, ExpectedVersion, PrimaryKey, ReadModelChange, ReadModelWritePlanStore, RowKey,
+    RowValue, RowValues, RowWriteMode, TableColumn, TableKind, TableMutation, TableRowMutation,
+    TableSchema, TableWritePlan,
+};
+use futures_util::StreamExt;
+use sqlx::sqlite::SqlitePoolOptions;
+
+fn items_schema() -> TableSchema {
+    TableSchema {
+        model_name: "ItemView".into(),
+        table_name: "items".into(),
+        columns: vec![
+            TableColumn {
+                primary_key: true,
+                ..TableColumn::new("id", "id", ColumnType::Text)
+            },
+            TableColumn::new("name", "name", ColumnType::Text),
+            TableColumn::new("status", "status", ColumnType::Text),
+        ],
+        primary_key: PrimaryKey::new(["id"]),
+        version_column: Some("_sourced_version".into()),
+        foreign_keys: Vec::new(),
+        indexes: Vec::new(),
+        relationships: Vec::new(),
+        kind: TableKind::ReadModel,
+    }
+}
+
+async fn setup_fixed() -> (
+    distributed::SqliteRepository,
+    GraphqlEngine,
+    sqlx::SqlitePool,
+) {
+    let repo = distributed::SqliteRepository::connect_and_migrate("sqlite::memory:")
+        .await
+        .unwrap();
+    let pool = repo.pool().clone();
+    sqlx::query(
+        "CREATE TABLE items (
+            id TEXT PRIMARY KEY,
+            name TEXT NOT NULL,
+            status TEXT NOT NULL,
+            _sourced_version INTEGER NOT NULL DEFAULT 0
+        );
+        INSERT INTO items (id, name, status, _sourced_version) VALUES
+            ('i1', 'alpha', 'open', 1),
+            ('i2', 'beta', 'closed', 1);",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+
+    let change_rx = repo.read_model_changes();
+
+    let manifest =
+        distributed::DistributedProjectManifest::new("items").table_schema(items_schema());
+    let engine = GraphqlEngine::from_manifest(&manifest, pool.clone())
+        .unwrap()
+        .roles(&["user"])
+        .grant_all("user")
+        .change_stream(change_rx)
+        .build()
+        .expect("build");
+
+    (repo, engine, pool)
+}
+
+fn user_session() -> Session {
+    let mut s = Session::new();
+    s.set(ROLE_KEY, "user");
+    s
+}
+
+fn static_schema() -> &'static TableSchema {
+    Box::leak(Box::new(items_schema()))
+}
+
+async fn upsert_item(repo: &distributed::SqliteRepository, id: &str, name: &str, status: &str) {
+    let schema = static_schema();
+    let mut values = RowValues::new();
+    values.insert("id", RowValue::String(id.into()));
+    values.insert("name", RowValue::String(name.into()));
+    values.insert("status", RowValue::String(status.into()));
+    let plan = TableWritePlan::new(vec![TableMutation::UpsertRow(TableRowMutation {
+        schema,
+        key: RowKey::new([("id", RowValue::String(id.into()))]),
+        values,
+        expected_version: ExpectedVersion::Any,
+        mode: RowWriteMode::Upsert,
+    })]);
+    repo.commit_write_plan(plan).await.unwrap();
+}
+
+#[tokio::test]
+async fn subscription_pushes_exactly_once_per_commit() {
+    let (repo, engine, _pool) = setup_fixed().await;
+    let session = user_session();
+
+    // Filtered subscription: only open items (nested selection of fields).
+    let request = Request::new(
+        r#"subscription { items(where: { status: { _eq: "open" } }) { id name status } }"#,
+    );
+    let mut stream = Box::pin(engine.execute_stream(&session, request));
+
+    // Initial push
+    let first = tokio::time::timeout(Duration::from_secs(2), stream.next())
+        .await
+        .expect("timeout waiting initial")
+        .expect("stream ended");
+    assert!(!first.is_err(), "initial errors: {:?}", first.errors);
+    let data = serde_json::to_value(&first.data).unwrap();
+    let items = data["items"].as_array().expect("items array");
+    assert_eq!(items.len(), 1, "only i1 is open: {data}");
+    assert_eq!(items[0]["id"], "i1");
+
+    // Commit a projection that changes the filtered set (i2 becomes open).
+    upsert_item(&repo, "i2", "beta", "open").await;
+
+    // Exactly one push after debounce
+    let second = tokio::time::timeout(Duration::from_secs(2), stream.next())
+        .await
+        .expect("timeout waiting push")
+        .expect("stream ended");
+    assert!(!second.is_err(), "push errors: {:?}", second.errors);
+    let data = serde_json::to_value(&second.data).unwrap();
+    let items = data["items"].as_array().unwrap();
+    assert_eq!(items.len(), 2, "both open after commit: {data}");
+
+    // No third push without another commit (debounce + idle).
+    let third = tokio::time::timeout(Duration::from_millis(300), stream.next()).await;
+    assert!(
+        third.is_err(),
+        "idle subscription must not push without a commit; got {:?}",
+        third
+    );
+}
+
+#[tokio::test]
+async fn hash_gate_no_push_when_result_unchanged() {
+    let (repo, engine, _pool) = setup_fixed().await;
+    let session = user_session();
+
+    let request = Request::new(r#"subscription { items { id name status } }"#);
+    let mut stream = Box::pin(engine.execute_stream(&session, request));
+
+    let _initial = stream.next().await.expect("initial");
+
+    // Upsert same values for i1 — projection commit fires, result unchanged → no push.
+    upsert_item(&repo, "i1", "alpha", "open").await;
+
+    let next = tokio::time::timeout(Duration::from_millis(400), stream.next()).await;
+    assert!(
+        next.is_err(),
+        "hash gate must suppress push when payload unchanged"
+    );
+}
+
+#[tokio::test]
+async fn subscription_unknown_role_returns_error_response() {
+    let (_repo, engine, _pool) = setup_fixed().await;
+    let mut session = user_session();
+    session.set(ROLE_KEY, "ghost");
+
+    let request = Request::new(r#"subscription { items { id name status } }"#);
+    let mut stream = Box::pin(engine.execute_stream(&session, request));
+
+    let response = tokio::time::timeout(Duration::from_secs(2), stream.next())
+        .await
+        .expect("timeout waiting error")
+        .expect("stream ended");
+    assert!(
+        response.is_err(),
+        "unknown role must return an error response"
+    );
+    assert_eq!(
+        response.errors[0].message,
+        "role `ghost` is not configured for GraphQL"
+    );
+}
+
+#[tokio::test]
+async fn broadcast_fires_on_write_plan_commit() {
+    let (repo, _engine, _pool) = setup_fixed().await;
+    let mut rx = repo.read_model_changes();
+    upsert_item(&repo, "i3", "gamma", "open").await;
+    let change = tokio::time::timeout(Duration::from_secs(2), rx.recv())
+        .await
+        .expect("timeout")
+        .expect("recv");
+    assert!(change.tables.contains("items"), "{change:?}");
+}
+
+#[tokio::test]
+async fn zero_receiver_send_is_noop() {
+    let pool = SqlitePoolOptions::new()
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    let repo = distributed::SqliteRepository::new(pool);
+    repo.publish_read_model_change(ReadModelChange::new(["items"]));
+}
+
+#[test]
+fn response_hash_stable() {
+    use async_graphql::Value;
+    let a = Value::from(1);
+    let b = Value::from(1);
+    let c = Value::from(2);
+    assert_eq!(
+        distributed::graphql::subscribe::response_hash(&a),
+        distributed::graphql::subscribe::response_hash(&b)
+    );
+    assert_ne!(
+        distributed::graphql::subscribe::response_hash(&a),
+        distributed::graphql::subscribe::response_hash(&c)
+    );
+}
+
+/// Live stream re-exec must AND claim row filters (same as query path).
+/// Two tenants subscribe with the same document; each only ever sees own rows
+/// on the initial push and after a cross-tenant write.
+#[tokio::test]
+async fn subscription_claim_isolation_across_tenants() {
+    use distributed::{ReadModel, RelationalReadModel};
+    use serde::{Deserialize, Serialize};
+
+    #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+    #[table("notes")]
+    struct NoteView {
+        #[id("note_id")]
+        note_id: String,
+        owner_id: String,
+        body: String,
+    }
+
+    let repo = distributed::SqliteRepository::connect_and_migrate("sqlite::memory:")
+        .await
+        .unwrap();
+    let pool = repo.pool().clone();
+    sqlx::query(
+        "CREATE TABLE notes (
+            note_id TEXT PRIMARY KEY,
+            owner_id TEXT NOT NULL,
+            body TEXT NOT NULL,
+            _sourced_version INTEGER NOT NULL DEFAULT 0
+        );
+        INSERT INTO notes (note_id, owner_id, body, _sourced_version) VALUES
+            ('n-a1', 'tenant-a', 'a1', 1),
+            ('n-b1', 'tenant-b', 'b1', 1);",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+
+    let change_rx = repo.read_model_changes();
+
+    let engine = GraphqlEngine::builder(pool.clone())
+        .roles(&["user"])
+        .model::<NoteView>(
+            ModelPermissions::new().grant(
+                "user",
+                read()
+                    .all_columns()
+                    .rows(col("owner_id").eq(claim("x-user-id"))),
+            ),
+        )
+        .change_stream(change_rx)
+        .build()
+        .expect("build");
+
+    fn tenant_session(tenant: &str) -> Session {
+        let mut s = Session::new();
+        s.set(ROLE_KEY, "user");
+        s.set(USER_ID_KEY, tenant);
+        s
+    }
+
+    let sub_doc = r#"subscription { notes { note_id owner_id body } }"#;
+
+    let mut stream_a =
+        Box::pin(engine.execute_stream(&tenant_session("tenant-a"), Request::new(sub_doc)));
+    let mut stream_b =
+        Box::pin(engine.execute_stream(&tenant_session("tenant-b"), Request::new(sub_doc)));
+
+    let first_a = tokio::time::timeout(Duration::from_secs(2), stream_a.next())
+        .await
+        .expect("timeout A")
+        .expect("stream A ended");
+    assert!(!first_a.is_err(), "{:?}", first_a.errors);
+    let data_a = serde_json::to_value(&first_a.data).unwrap();
+    let notes_a = data_a["notes"].as_array().expect("notes A");
+    assert_eq!(notes_a.len(), 1, "A must only see own row: {data_a}");
+    assert_eq!(notes_a[0]["owner_id"], "tenant-a");
+    assert_eq!(notes_a[0]["note_id"], "n-a1");
+
+    let first_b = tokio::time::timeout(Duration::from_secs(2), stream_b.next())
+        .await
+        .expect("timeout B")
+        .expect("stream B ended");
+    assert!(!first_b.is_err(), "{:?}", first_b.errors);
+    let data_b = serde_json::to_value(&first_b.data).unwrap();
+    let notes_b = data_b["notes"].as_array().expect("notes B");
+    assert_eq!(notes_b.len(), 1, "B must only see own row: {data_b}");
+    assert_eq!(notes_b[0]["owner_id"], "tenant-b");
+
+    // Commit a new row for A — only stream A may receive it.
+    let schema = NoteView::schema();
+    let mut values = RowValues::new();
+    values.insert("note_id", RowValue::String("n-a2".into()));
+    values.insert("owner_id", RowValue::String("tenant-a".into()));
+    values.insert("body", RowValue::String("a2".into()));
+    let plan = TableWritePlan::new(vec![TableMutation::UpsertRow(TableRowMutation {
+        schema,
+        key: RowKey::new([("note_id", RowValue::String("n-a2".into()))]),
+        values,
+        expected_version: ExpectedVersion::Any,
+        mode: RowWriteMode::Upsert,
+    })]);
+    repo.commit_write_plan(plan).await.unwrap();
+
+    let push_a = tokio::time::timeout(Duration::from_secs(2), stream_a.next())
+        .await
+        .expect("timeout A push")
+        .expect("stream A ended");
+    assert!(!push_a.is_err(), "{:?}", push_a.errors);
+    let data_a2 = serde_json::to_value(&push_a.data).unwrap();
+    let notes_a2 = data_a2["notes"].as_array().unwrap();
+    assert_eq!(notes_a2.len(), 2, "A sees both own notes: {data_a2}");
+    assert!(
+        notes_a2.iter().all(|n| n["owner_id"] == "tenant-a"),
+        "A stream leaked foreign owner: {data_a2}"
+    );
+
+    // B's payload is unchanged (still one row) — hash gate may suppress a push.
+    // If a push arrives, it must still be only tenant-b.
+    if let Ok(Some(push_b)) =
+        tokio::time::timeout(Duration::from_millis(500), stream_b.next()).await
+    {
+        assert!(!push_b.is_err(), "{:?}", push_b.errors);
+        let data_b2 = serde_json::to_value(&push_b.data).unwrap();
+        let notes_b2 = data_b2["notes"].as_array().unwrap();
+        assert_eq!(notes_b2.len(), 1, "B must not see A's insert: {data_b2}");
+        assert_eq!(notes_b2[0]["owner_id"], "tenant-b");
+    }
+}
diff --git a/tests/microsvc/transport_grpc.rs b/tests/microsvc/transport_grpc.rs
index ef90bb6d..c849b0ea 100644
--- a/tests/microsvc/transport_grpc.rs
+++ b/tests/microsvc/transport_grpc.rs
@@ -214,10 +214,7 @@ async fn grpc_payload_session_variables_apply_when_metadata_absent() {
     let mut client = start_server(service).await;
 
     let mut payload_vars = std::collections::HashMap::new();
-    payload_vars.insert(
-        "x-user-id".to_string(),
-        "user-from-payload".to_string(),
-    );
+    payload_vars.insert("x-user-id".to_string(), "user-from-payload".to_string());
 
     let resp = client
         .dispatch(GrpcRequest {
diff --git a/tests/postgres_transport/main.rs b/tests/postgres_transport/main.rs
index 6f4beead..42767411 100644
--- a/tests/postgres_transport/main.rs
+++ b/tests/postgres_transport/main.rs
@@ -19,14 +19,15 @@ use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
 use distributed::bus::{
-    run_source, Bus, BusConsumer, Handlers, MessageSource, PostgresBus, ReceivedMessage,
-    RunOptions, TransportError,
+    run_source, Bus, BusConsumer, Handlers, MessageRouter, MessageSource, OrderedDelivery,
+    PostgresBus, ReceivedMessage, RunOptions, SubscriptionPlan, TransportError,
 };
 use distributed::microsvc::{Context, Message, MessageKind, Routes, Service};
+use distributed::projection_protocol::ProjectionEpoch;
 use distributed::OutboxSource;
 use distributed::{
     CommitBatch, OutboxMessage, OutboxMessageStatus, PostgresOutboxStore, PostgresRepository,
-    TransactionalCommit,
+    TransactionalCommit, CAUSATION_ID, TRACEPARENT,
 };
 use serde_json::json;
 use tokio::sync::Notify;
@@ -200,6 +201,84 @@ async fn pg_bus(pool: &sqlx::PgPool, group: &str) -> PostgresBus {
     bus
 }
 
+#[derive(Default)]
+struct OrderedEvidenceRecorder {
+    observed: Mutex<Vec<(String, u64)>>,
+}
+
+impl MessageRouter for OrderedEvidenceRecorder {
+    fn handles(&self, kind: MessageKind, name: &str) -> bool {
+        kind == MessageKind::Event && name == "order.initialized"
+    }
+
+    fn subscription_plan(&self) -> SubscriptionPlan {
+        SubscriptionPlan {
+            commands: Vec::new(),
+            events: vec!["order.initialized".to_string()],
+        }
+    }
+
+    async fn dispatch(&self, _message: &Message) -> Result<(), TransportError> {
+        Ok(())
+    }
+
+    async fn dispatch_ordered(
+        &self,
+        _message: &Message,
+        ordered: Option<&OrderedDelivery>,
+    ) -> Result<(), TransportError> {
+        let ordered =
+            ordered.ok_or_else(|| TransportError::permanent("missing SQL ordering evidence"))?;
+        self.observed
+            .lock()
+            .unwrap()
+            .push((ordered.epoch().as_str().to_string(), ordered.position()));
+        Ok(())
+    }
+}
+
+#[derive(Default)]
+struct RotationRouter {
+    attempts: AtomicUsize,
+    seen: Mutex<Vec<String>>,
+    first_started: Notify,
+    release_first: Notify,
+}
+
+impl MessageRouter for RotationRouter {
+    fn handles(&self, kind: MessageKind, name: &str) -> bool {
+        kind == MessageKind::Event && name == "order.initialized"
+    }
+
+    fn subscription_plan(&self) -> SubscriptionPlan {
+        SubscriptionPlan {
+            commands: Vec::new(),
+            events: vec!["order.initialized".to_string()],
+        }
+    }
+
+    async fn dispatch(&self, _message: &Message) -> Result<(), TransportError> {
+        Ok(())
+    }
+
+    async fn dispatch_ordered(
+        &self,
+        message: &Message,
+        ordered: Option<&OrderedDelivery>,
+    ) -> Result<(), TransportError> {
+        ordered.ok_or_else(|| TransportError::permanent("missing SQL ordering evidence"))?;
+        self.seen
+            .lock()
+            .unwrap()
+            .push(message.id().unwrap_or_default().to_string());
+        if self.attempts.fetch_add(1, Ordering::SeqCst) == 0 {
+            self.first_started.notify_one();
+            self.release_first.notified().await;
+        }
+        Ok(())
+    }
+}
+
 /// `send` + `listen`: the work queue is claimed `FOR UPDATE SKIP LOCKED`, so two
 /// replicas sharing a `group` compete — each command handled exactly once.
 #[tokio::test]
@@ -302,6 +381,13 @@ async fn recreate_permissive_log_table(pool: &sqlx::PgPool) {
         .execute(pool)
         .await
         .expect("create log index");
+    sqlx::query(
+        "CREATE UNIQUE INDEX bus_log_message_id_unique_idx \
+         ON bus_log (message_id) WHERE message_id IS NOT NULL",
+    )
+    .execute(pool)
+    .await
+    .expect("create stable message ID index");
 }
 
 async fn corrupt_latest_queue_name(pool: &sqlx::PgPool) {
@@ -561,6 +647,588 @@ async fn bus_subscribe_dead_letters_corrupt_log_row_not_silently() {
     );
 }
 
+#[tokio::test]
+async fn stable_log_retry_keeps_the_original_cursor_and_rejects_conflicts() {
+    let Some(schema) = postgres::PostgresTestSchema::create_from_env("bus_log_dedupe", SKIP).await
+    else {
+        return;
+    };
+    let repo = schema.repository().await;
+    let pool = repo.pool().clone();
+    let bus = PostgresBus::new(pool.clone());
+    bus.ensure_tables().await.expect("ensure tables");
+
+    let first = Message::new("order.initialized", MessageKind::Event, b"{}".to_vec())
+        .with_id("stable-event")
+        .with_metadata(CAUSATION_ID, "command-1")
+        .with_metadata(TRACEPARENT, "first-attempt");
+    bus.publish_message(first)
+        .await
+        .expect("first append commits");
+
+    let original_seq: i64 =
+        sqlx::query_scalar("SELECT seq FROM bus_log WHERE message_id = 'stable-event'")
+            .fetch_one(&pool)
+            .await
+            .expect("read original cursor");
+    let retry = Message::new("order.initialized", MessageKind::Event, b"{}".to_vec())
+        .with_id("stable-event")
+        .with_metadata(CAUSATION_ID, "command-1")
+        .with_metadata(TRACEPARENT, "retry-attempt");
+    bus.publish_message(retry)
+        .await
+        .expect("same causal envelope is an idempotent retry");
+
+    let rows: i64 =
+        sqlx::query_scalar("SELECT count(*) FROM bus_log WHERE message_id = 'stable-event'")
+            .fetch_one(&pool)
+            .await
+            .expect("count stable ID rows");
+    let retained_seq: i64 =
+        sqlx::query_scalar("SELECT seq FROM bus_log WHERE message_id = 'stable-event'")
+            .fetch_one(&pool)
+            .await
+            .expect("read retained cursor");
+    let retained_metadata: String =
+        sqlx::query_scalar("SELECT metadata FROM bus_log WHERE message_id = 'stable-event'")
+            .fetch_one(&pool)
+            .await
+            .expect("read authoritative metadata");
+    assert_eq!(rows, 1, "ambiguous retry did not append a second row");
+    assert_eq!(
+        retained_seq, original_seq,
+        "ambiguous retry retained the original ordered cursor"
+    );
+    assert!(
+        retained_metadata.contains("first-attempt"),
+        "the first committed envelope remains authoritative"
+    );
+    assert!(!retained_metadata.contains("retry-attempt"));
+
+    let payload_conflict = Message::new(
+        "order.initialized",
+        MessageKind::Event,
+        br#"{"different":true}"#.to_vec(),
+    )
+    .with_id("stable-event")
+    .with_metadata(CAUSATION_ID, "command-1");
+    let error = bus
+        .publish_message(payload_conflict)
+        .await
+        .expect_err("same stable ID cannot identify a different payload");
+    assert!(error.is_permanent(), "conflict is deterministic corruption");
+
+    let causation_conflict = Message::new("order.initialized", MessageKind::Event, b"{}".to_vec())
+        .with_id("stable-event")
+        .with_metadata(CAUSATION_ID, "different-command");
+    let error = bus
+        .publish_message(causation_conflict)
+        .await
+        .expect_err("same stable ID cannot identify a different causation");
+    assert!(error.is_permanent(), "causation conflict is permanent");
+
+    let rows_after_conflicts: i64 =
+        sqlx::query_scalar("SELECT count(*) FROM bus_log WHERE message_id = 'stable-event'")
+            .fetch_one(&pool)
+            .await
+            .expect("count rows after conflicts");
+    assert_eq!(rows_after_conflicts, 1, "conflicts leave the log unchanged");
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn concurrent_stable_log_retries_share_one_original_cursor() {
+    let Some(schema) = postgres::PostgresTestSchema::create_from_env("bus_log_race", SKIP).await
+    else {
+        return;
+    };
+    let repo = schema.repository().await;
+    let pool = repo.pool().clone();
+    let bus = PostgresBus::new(pool.clone());
+    bus.ensure_tables().await.expect("ensure tables");
+    let first = Message::new("order.initialized", MessageKind::Event, b"{}".to_vec())
+        .with_id("concurrent-stable")
+        .with_metadata(CAUSATION_ID, "command-concurrent")
+        .with_metadata(TRACEPARENT, "attempt-a");
+    let retry = Message::new("order.initialized", MessageKind::Event, b"{}".to_vec())
+        .with_id("concurrent-stable")
+        .with_metadata(CAUSATION_ID, "command-concurrent")
+        .with_metadata(TRACEPARENT, "attempt-b");
+
+    let (first_result, retry_result) =
+        tokio::join!(bus.publish_message(first), bus.publish_message(retry));
+    first_result.expect("one concurrent append wins");
+    retry_result.expect("the equivalent concurrent append is idempotent");
+
+    let rows: i64 =
+        sqlx::query_scalar("SELECT count(*) FROM bus_log WHERE message_id = 'concurrent-stable'")
+            .fetch_one(&pool)
+            .await
+            .expect("count concurrent stable ID rows");
+    let seq: i64 =
+        sqlx::query_scalar("SELECT seq FROM bus_log WHERE message_id = 'concurrent-stable'")
+            .fetch_one(&pool)
+            .await
+            .expect("read stable cursor");
+    assert_eq!(rows, 1);
+    assert_eq!(seq, 1, "the only allocated cursor remains authoritative");
+}
+
+#[tokio::test]
+async fn legacy_equivalent_stable_id_duplicates_retain_the_minimum_cursor() {
+    let Some(schema) =
+        postgres::PostgresTestSchema::create_from_env("bus_log_legacy_ok", SKIP).await
+    else {
+        return;
+    };
+    let repo = schema.repository().await;
+    let pool = repo.pool().clone();
+    let bus = PostgresBus::new(pool.clone());
+    bus.ensure_tables().await.expect("ensure tables");
+    sqlx::query("DROP INDEX bus_log_message_id_unique_idx")
+        .execute(&pool)
+        .await
+        .expect("simulate legacy schema without uniqueness");
+    let first_metadata = serde_json::to_string(&vec![
+        (CAUSATION_ID, "legacy-command"),
+        (TRACEPARENT, "legacy-first"),
+    ])
+    .unwrap();
+    let retry_metadata = serde_json::to_string(&vec![
+        (CAUSATION_ID, "legacy-command"),
+        (TRACEPARENT, "legacy-retry"),
+    ])
+    .unwrap();
+    for metadata in [&first_metadata, &retry_metadata] {
+        sqlx::query(
+            "INSERT INTO bus_log \
+                 (name, message_id, kind, payload, content_type, metadata) \
+             VALUES ('order.initialized', 'legacy-stable', 'event', $1, \
+                     'application/json', $2)",
+        )
+        .bind(b"{}".as_slice())
+        .bind(metadata)
+        .execute(&pool)
+        .await
+        .expect("seed equivalent legacy duplicate");
+    }
+
+    bus.ensure_tables()
+        .await
+        .expect("equivalent duplicates are migrated safely");
+    let retained: (i64, String, i64) = sqlx::query_as(
+        "SELECT MIN(seq), MIN(metadata), COUNT(*) \
+         FROM bus_log WHERE message_id = 'legacy-stable'",
+    )
+    .fetch_one(&pool)
+    .await
+    .expect("read migrated legacy row");
+    assert_eq!(retained.0, 1, "the minimum legacy cursor is authoritative");
+    assert_eq!(retained.2, 1);
+    assert!(
+        retained.1.contains("legacy-first"),
+        "the first committed envelope is retained"
+    );
+    let unique_index: bool =
+        sqlx::query_scalar("SELECT to_regclass('bus_log_message_id_unique_idx') IS NOT NULL")
+            .fetch_one(&pool)
+            .await
+            .expect("inspect stable ID index");
+    assert!(unique_index);
+}
+
+#[tokio::test]
+async fn legacy_conflicting_stable_id_duplicates_fail_preflight_without_mutation() {
+    let Some(schema) =
+        postgres::PostgresTestSchema::create_from_env("bus_log_legacy_bad", SKIP).await
+    else {
+        return;
+    };
+    let repo = schema.repository().await;
+    let pool = repo.pool().clone();
+    let bus = PostgresBus::new(pool.clone());
+    bus.ensure_tables().await.expect("ensure tables");
+    sqlx::query("DROP INDEX bus_log_message_id_unique_idx")
+        .execute(&pool)
+        .await
+        .expect("simulate legacy schema without uniqueness");
+    for payload in [br#"{}"#.as_slice(), br#"{"different":true}"#.as_slice()] {
+        sqlx::query(
+            "INSERT INTO bus_log \
+                 (name, message_id, kind, payload, content_type, metadata) \
+             VALUES ('order.initialized', 'legacy-conflict', 'event', $1, \
+                     'application/json', '[]')",
+        )
+        .bind(payload)
+        .execute(&pool)
+        .await
+        .expect("seed conflicting legacy duplicate");
+    }
+
+    let error = bus
+        .ensure_tables()
+        .await
+        .expect_err("conflicting legacy duplicates fail closed");
+    assert!(error.is_permanent());
+    let rows: i64 =
+        sqlx::query_scalar("SELECT COUNT(*) FROM bus_log WHERE message_id = 'legacy-conflict'")
+            .fetch_one(&pool)
+            .await
+            .expect("count untouched conflicting rows");
+    let unique_index: bool =
+        sqlx::query_scalar("SELECT to_regclass('bus_log_message_id_unique_idx') IS NOT NULL")
+            .fetch_one(&pool)
+            .await
+            .expect("inspect absent stable ID index");
+    assert_eq!(rows, 2, "failed preflight rolls back deduplication");
+    assert!(!unique_index, "no unsafe uniqueness fence was installed");
+}
+
+#[tokio::test]
+async fn nonempty_log_identity_adoption_must_be_explicit_and_retires_offsets() {
+    let Some(schema) =
+        postgres::PostgresTestSchema::create_from_env("bus_identity_loss", SKIP).await
+    else {
+        return;
+    };
+    let repo = schema.repository().await;
+    let pool = repo.pool().clone();
+    let bus = PostgresBus::new(pool.clone());
+    bus.ensure_tables().await.expect("ensure tables");
+    bus.publish_message(
+        Message::new("order.initialized", MessageKind::Event, b"{}".to_vec())
+            .with_id("identity-loss"),
+    )
+    .await
+    .expect("append before identity loss");
+    let retired_epoch: String =
+        sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+            .fetch_one(&pool)
+            .await
+            .expect("read retired epoch");
+    sqlx::query(
+        "INSERT INTO bus_offset (consumer, source_epoch, last_seq) \
+         VALUES ('stale-consumer', $1, 1)",
+    )
+    .bind(&retired_epoch)
+    .execute(&pool)
+    .await
+    .expect("seed stale bound offset");
+    sqlx::query("DROP TABLE bus_log_identity")
+        .execute(&pool)
+        .await
+        .expect("simulate independently lost identity");
+
+    let error = bus
+        .ensure_tables()
+        .await
+        .expect_err("a retained log cannot receive a random replacement epoch");
+    assert!(error.is_permanent());
+    let identities: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM bus_log_identity")
+        .fetch_one(&pool)
+        .await
+        .expect("count rolled-back identity");
+    let offsets_before_adoption: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM bus_offset")
+        .fetch_one(&pool)
+        .await
+        .expect("count still-bound offsets");
+    assert_eq!(
+        identities, 0,
+        "failed default adoption installs no identity"
+    );
+    assert_eq!(
+        offsets_before_adoption, 1,
+        "failed default adoption does not clear offsets"
+    );
+
+    let adopted_epoch = ProjectionEpoch::new("operator-adopted-retained-log").unwrap();
+    PostgresBus::new(pool.clone())
+        .with_source_epoch(adopted_epoch.clone())
+        .ensure_tables()
+        .await
+        .expect("explicitly adopt the retained log");
+    let replacement_epoch: String =
+        sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+            .fetch_one(&pool)
+            .await
+            .expect("read replacement epoch");
+    let offsets: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM bus_offset")
+        .fetch_one(&pool)
+        .await
+        .expect("count retired offsets");
+    assert_ne!(replacement_epoch, retired_epoch);
+    assert_eq!(replacement_epoch, adopted_epoch.as_str());
+    assert_eq!(
+        offsets, 0,
+        "identity creation and offset invalidation commit together"
+    );
+}
+
+#[tokio::test]
+async fn configured_epoch_initializes_but_cannot_relabel_an_existing_log() {
+    let Some(schema) =
+        postgres::PostgresTestSchema::create_from_env("bus_epoch_override", SKIP).await
+    else {
+        return;
+    };
+    let repo = schema.repository().await;
+    let pool = repo.pool().clone();
+    let initial_epoch = ProjectionEpoch::new("operator-generation-1").unwrap();
+    let bus = PostgresBus::new(pool.clone())
+        .group("epoch-observer")
+        .with_source_epoch(initial_epoch.clone());
+    bus.ensure_tables()
+        .await
+        .expect("configured epoch initializes a new log");
+    let persisted: String =
+        sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+            .fetch_one(&pool)
+            .await
+            .expect("read initialized epoch");
+    assert_eq!(persisted, initial_epoch.as_str());
+    bus.publish_message(
+        Message::new("order.initialized", MessageKind::Event, b"{}".to_vec())
+            .with_id("delivered-epoch"),
+    )
+    .await
+    .expect("append under configured epoch");
+    let recorder = Arc::new(OrderedEvidenceRecorder::default());
+    bus.subscribe(recorder.clone(), RunOptions::idempotent())
+        .await
+        .expect("deliver ordered row");
+    assert_eq!(
+        *recorder.observed.lock().unwrap(),
+        vec![(persisted.clone(), 1)],
+        "delivery exposes the durable row's epoch and original SQL position"
+    );
+
+    let mismatched = PostgresBus::new(pool.clone())
+        .with_source_epoch(ProjectionEpoch::new("operator-generation-2").unwrap());
+    let error = mismatched
+        .ensure_tables()
+        .await
+        .expect_err("a builder override cannot relabel existing positions");
+    assert!(error.is_permanent());
+    let error = mismatched
+        .publish_message(
+            Message::new("order.initialized", MessageKind::Event, b"{}".to_vec())
+                .with_id("must-not-append"),
+        )
+        .await
+        .expect_err("producer mismatch fails before append");
+    assert!(error.is_permanent());
+    let rows: i64 = sqlx::query_scalar("SELECT count(*) FROM bus_log")
+        .fetch_one(&pool)
+        .await
+        .expect("count log rows");
+    let still_persisted: String =
+        sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+            .fetch_one(&pool)
+            .await
+            .expect("read unchanged epoch");
+    assert_eq!(rows, 1, "mismatched producer did not append");
+    assert_eq!(still_persisted, initial_epoch.as_str());
+}
+
+#[tokio::test]
+async fn log_rewind_requires_an_explicit_fenced_reset() {
+    let Some(schema) = postgres::PostgresTestSchema::create_from_env("bus_log_epoch", SKIP).await
+    else {
+        return;
+    };
+    let repo = schema.repository().await;
+    let pool = repo.pool().clone();
+    let bus = PostgresBus::new(pool.clone());
+    bus.ensure_tables().await.expect("ensure tables");
+    bus.publish_message(
+        Message::new("order.initialized", MessageKind::Event, b"{}".to_vec())
+            .with_id("before-reset"),
+    )
+    .await
+    .expect("append before reset");
+    let (before_epoch, before_generation, before_high_water): (String, i64, i64) = sqlx::query_as(
+        "SELECT source_epoch, generation, high_water \
+             FROM bus_log_identity WHERE singleton = 1",
+    )
+    .fetch_one(&pool)
+    .await
+    .expect("read initial log identity");
+    assert_eq!(before_generation, 1);
+    assert_eq!(before_high_water, 1);
+    sqlx::query(
+        "INSERT INTO bus_offset (consumer, source_epoch, last_seq) \
+         VALUES ('projector', $1, 1)",
+    )
+    .bind(&before_epoch)
+    .execute(&pool)
+    .await
+    .expect("seed old generation offset");
+
+    sqlx::query("DROP TABLE bus_log")
+        .execute(&pool)
+        .await
+        .expect("simulate independently rebuilt log");
+    let error = PostgresBus::new(pool.clone())
+        .ensure_tables()
+        .await
+        .expect_err("ordinary startup cannot authorize cursor-domain reuse");
+    assert!(error.is_permanent());
+    let error = bus
+        .publish_message(
+            Message::new("order.initialized", MessageKind::Event, b"{}".to_vec())
+                .with_id("must-not-rotate"),
+        )
+        .await
+        .expect_err("ordinary publish cannot authorize cursor-domain reuse");
+    assert!(error.is_permanent());
+    let replacement_rows: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM bus_log")
+        .fetch_one(&pool)
+        .await
+        .expect("count replacement rows before reset");
+    assert_eq!(replacement_rows, 0);
+    let unchanged: (String, i64, i64) = sqlx::query_as(
+        "SELECT source_epoch, generation, high_water \
+         FROM bus_log_identity WHERE singleton = 1",
+    )
+    .fetch_one(&pool)
+    .await
+    .expect("read unchanged rewind fence");
+    assert_eq!(
+        unchanged,
+        (before_epoch.clone(), before_generation, before_high_water)
+    );
+    let offsets_before_reset: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM bus_offset")
+        .fetch_one(&pool)
+        .await
+        .expect("count fenced offsets");
+    assert_eq!(offsets_before_reset, 1);
+
+    let expected_epoch = ProjectionEpoch::new(before_epoch.clone()).unwrap();
+    let wrong_epoch = ProjectionEpoch::new("wrong-current-generation").unwrap();
+    let next_epoch = ProjectionEpoch::new("operator-reset-generation-2").unwrap();
+    let error = bus
+        .reset_ordered_log(&wrong_epoch, &next_epoch)
+        .await
+        .expect_err("compare-and-swap reset rejects a stale expected epoch");
+    assert!(error.is_permanent());
+    let error = bus
+        .reset_ordered_log(&expected_epoch, &expected_epoch)
+        .await
+        .expect_err("a reset cannot reuse the retired epoch");
+    assert!(error.is_permanent());
+    bus.reset_ordered_log(&expected_epoch, &next_epoch)
+        .await
+        .expect("operator-authorized reset");
+
+    let (after_epoch, after_generation, after_high_water): (String, i64, i64) = sqlx::query_as(
+        "SELECT source_epoch, generation, high_water \
+             FROM bus_log_identity WHERE singleton = 1",
+    )
+    .fetch_one(&pool)
+    .await
+    .expect("read rotated log identity");
+    assert_eq!(after_epoch, next_epoch.as_str());
+    assert_eq!(after_generation, before_generation + 1);
+    assert_eq!(after_high_water, 0);
+    let offsets: i64 = sqlx::query_scalar("SELECT count(*) FROM bus_offset")
+        .fetch_one(&pool)
+        .await
+        .expect("count retired offsets");
+    assert_eq!(offsets, 0, "old-generation offsets cannot skip the new log");
+
+    let rebuilt = PostgresBus::new(pool.clone());
+    rebuilt
+        .publish_message(
+            Message::new("order.initialized", MessageKind::Event, b"{}".to_vec())
+                .with_id("after-reset"),
+        )
+        .await
+        .expect("append in new generation");
+    let new_seq: i64 =
+        sqlx::query_scalar("SELECT seq FROM bus_log WHERE message_id = 'after-reset'")
+            .fetch_one(&pool)
+            .await
+            .expect("read rebuilt cursor");
+    let persisted_epoch: String =
+        sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+            .fetch_one(&pool)
+            .await
+            .expect("read persisted epoch");
+    assert_eq!(new_seq, 1, "the rebuilt log reused a numeric position");
+    assert_eq!(
+        persisted_epoch, after_epoch,
+        "ordinary appends retain the rotated epoch"
+    );
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn running_subscriber_stops_before_cached_rows_after_epoch_rotation() {
+    let Some(schema) =
+        postgres::PostgresTestSchema::create_from_env("bus_live_rotation", SKIP).await
+    else {
+        return;
+    };
+    let repo = schema.repository().await;
+    let pool = repo.pool().clone();
+    let producer = PostgresBus::new(pool.clone());
+    producer.ensure_tables().await.expect("ensure tables");
+    for index in 0..17 {
+        producer
+            .publish_message(
+                Message::new("order.initialized", MessageKind::Event, b"{}".to_vec())
+                    .with_id(format!("old-{index}")),
+            )
+            .await
+            .expect("append old-generation event");
+    }
+    let router = Arc::new(RotationRouter::default());
+    let subscriber = PostgresBus::new(pool.clone()).group("rotation-observer");
+    let running = tokio::spawn({
+        let router = router.clone();
+        async move { subscriber.subscribe(router, RunOptions::idempotent()).await }
+    });
+    tokio::time::timeout(Duration::from_secs(2), router.first_started.notified())
+        .await
+        .expect("first buffered delivery started");
+
+    let current_epoch: String =
+        sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+            .fetch_one(&pool)
+            .await
+            .expect("read current epoch");
+    let current_epoch = ProjectionEpoch::new(current_epoch).unwrap();
+    let next_epoch = ProjectionEpoch::new("live-reset-generation-2").unwrap();
+    producer
+        .reset_ordered_log(&current_epoch, &next_epoch)
+        .await
+        .expect("reset log while a handler is in flight");
+    let replacement = PostgresBus::new(pool.clone());
+    replacement
+        .publish_message(
+            Message::new("order.initialized", MessageKind::Event, b"{}".to_vec()).with_id("new-0"),
+        )
+        .await
+        .expect("append replacement-generation event");
+    router.release_first.notify_one();
+
+    let error = tokio::time::timeout(Duration::from_secs(2), running)
+        .await
+        .expect("subscriber stopped")
+        .expect("subscriber task joined")
+        .expect_err("retired subscriber fails closed");
+    assert!(error.is_permanent(), "epoch mismatch is not retryable");
+    assert_eq!(
+        *router.seen.lock().unwrap(),
+        vec!["old-0".to_string()],
+        "cached old rows and replacement rows were never dispatched"
+    );
+    let offsets: i64 =
+        sqlx::query_scalar("SELECT count(*) FROM bus_offset WHERE consumer = 'rotation-observer'")
+            .fetch_one(&pool)
+            .await
+            .expect("count stale offsets");
+    assert_eq!(offsets, 0, "retired delivery did not settle into new epoch");
+}
+
 /// Claim-token fencing: after a lease expires and the command is reclaimed by a
 /// second worker (new claim token), the stale first worker's ack must not settle
 /// the row out from under the newer claim. Mirrors the sqlite_transport test.
@@ -585,23 +1253,26 @@ async fn expired_queue_claim_cannot_be_settled_by_stale_worker() {
     let attempts = Arc::new(AtomicUsize::new(0));
     let first_claimed = Arc::new(Notify::new());
     let second_claimed = Arc::new(Notify::new());
+    let allow_first_finish = Arc::new(Notify::new());
     let allow_second_finish = Arc::new(Notify::new());
 
     let handlers = Arc::new({
         let attempts = attempts.clone();
         let first_claimed = first_claimed.clone();
         let second_claimed = second_claimed.clone();
+        let allow_first_finish = allow_first_finish.clone();
         let allow_second_finish = allow_second_finish.clone();
         Handlers::new().on_command("order.initialize", move |_: &distributed::bus::Message| {
             let attempt = attempts.fetch_add(1, Ordering::SeqCst);
             let first_claimed = first_claimed.clone();
             let second_claimed = second_claimed.clone();
+            let allow_first_finish = allow_first_finish.clone();
             let allow_second_finish = allow_second_finish.clone();
             async move {
                 match attempt {
                     0 => {
                         first_claimed.notify_one();
-                        tokio::time::sleep(Duration::from_millis(420)).await;
+                        allow_first_finish.notified().await;
                         Ok(())
                     }
                     1 => {
@@ -634,6 +1305,7 @@ async fn expired_queue_claim_cannot_be_settled_by_stale_worker() {
         .await
         .expect("second worker reclaimed the expired lease");
 
+    allow_first_finish.notify_one();
     tokio::time::timeout(Duration::from_secs(2), first)
         .await
         .expect("stale first worker finished")
diff --git a/tests/sqlite_transport/main.rs b/tests/sqlite_transport/main.rs
index b4c1a70c..b7b920a8 100644
--- a/tests/sqlite_transport/main.rs
+++ b/tests/sqlite_transport/main.rs
@@ -17,8 +17,11 @@ use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
 use distributed::bus::{
-    Bus, BusConsumer, Handlers, Message, MessageKind, RunOptions, SqliteBus, TransportError,
+    Bus, BusConsumer, Handlers, Message, MessageKind, MessageRouter, OrderedDelivery, RunOptions,
+    SqliteBus, SubscriptionPlan, TransportError,
 };
+use distributed::projection_protocol::ProjectionEpoch;
+use distributed::{CAUSATION_ID, TRACEPARENT};
 use sqlx::SqlitePool;
 use tokio::sync::Notify;
 
@@ -41,6 +44,84 @@ fn sqlite_bus(pool: &SqlitePool, group: &str) -> SqliteBus {
     }
 }
 
+#[derive(Default)]
+struct OrderedEvidenceRecorder {
+    observed: Mutex<Vec<(String, u64)>>,
+}
+
+impl MessageRouter for OrderedEvidenceRecorder {
+    fn handles(&self, kind: MessageKind, name: &str) -> bool {
+        kind == MessageKind::Event && name == EVENT_NAME
+    }
+
+    fn subscription_plan(&self) -> SubscriptionPlan {
+        SubscriptionPlan {
+            commands: Vec::new(),
+            events: vec![EVENT_NAME.to_string()],
+        }
+    }
+
+    async fn dispatch(&self, _message: &Message) -> Result<(), TransportError> {
+        Ok(())
+    }
+
+    async fn dispatch_ordered(
+        &self,
+        _message: &Message,
+        ordered: Option<&OrderedDelivery>,
+    ) -> Result<(), TransportError> {
+        let ordered =
+            ordered.ok_or_else(|| TransportError::permanent("missing SQL ordering evidence"))?;
+        self.observed
+            .lock()
+            .unwrap()
+            .push((ordered.epoch().as_str().to_string(), ordered.position()));
+        Ok(())
+    }
+}
+
+#[derive(Default)]
+struct RotationRouter {
+    attempts: AtomicUsize,
+    seen: Mutex<Vec<String>>,
+    first_started: Notify,
+    release_first: Notify,
+}
+
+impl MessageRouter for RotationRouter {
+    fn handles(&self, kind: MessageKind, name: &str) -> bool {
+        kind == MessageKind::Event && name == EVENT_NAME
+    }
+
+    fn subscription_plan(&self) -> SubscriptionPlan {
+        SubscriptionPlan {
+            commands: Vec::new(),
+            events: vec![EVENT_NAME.to_string()],
+        }
+    }
+
+    async fn dispatch(&self, _message: &Message) -> Result<(), TransportError> {
+        Ok(())
+    }
+
+    async fn dispatch_ordered(
+        &self,
+        message: &Message,
+        ordered: Option<&OrderedDelivery>,
+    ) -> Result<(), TransportError> {
+        ordered.ok_or_else(|| TransportError::permanent("missing SQL ordering evidence"))?;
+        self.seen
+            .lock()
+            .unwrap()
+            .push(message.id().unwrap_or_default().to_string());
+        if self.attempts.fetch_add(1, Ordering::SeqCst) == 0 {
+            self.first_started.notify_one();
+            self.release_first.notified().await;
+        }
+        Ok(())
+    }
+}
+
 async fn recreate_nullable_queue_table(pool: &SqlitePool) {
     sqlx::query("DROP TABLE IF EXISTS bus_queue")
         .execute(pool)
@@ -100,6 +181,13 @@ async fn recreate_nullable_log_table(pool: &SqlitePool) {
         .execute(pool)
         .await
         .expect("create log index");
+    sqlx::query(
+        "CREATE UNIQUE INDEX bus_log_message_id_unique_idx \
+         ON bus_log (message_id) WHERE message_id IS NOT NULL",
+    )
+    .execute(pool)
+    .await
+    .expect("create stable message ID index");
 }
 
 async fn corrupt_latest_queue_name(pool: &SqlitePool) {
@@ -417,6 +505,505 @@ async fn bus_subscribe_dead_letters_corrupt_log_row_not_silently() {
     );
 }
 
+#[tokio::test]
+async fn stable_log_retry_keeps_the_original_cursor_and_rejects_conflicts() {
+    let (_db, pool, bus) = bus().await;
+    let first = event("stable-event")
+        .with_metadata(CAUSATION_ID, "command-1")
+        .with_metadata(TRACEPARENT, "first-attempt");
+    bus.publish_message(first)
+        .await
+        .expect("first append commits");
+
+    let original_seq: i64 =
+        sqlx::query_scalar("SELECT seq FROM bus_log WHERE message_id = 'stable-event'")
+            .fetch_one(&pool)
+            .await
+            .expect("read original cursor");
+    let retry = event("stable-event")
+        .with_metadata(CAUSATION_ID, "command-1")
+        .with_metadata(TRACEPARENT, "retry-attempt");
+    bus.publish_message(retry)
+        .await
+        .expect("same causal envelope is an idempotent retry");
+
+    let rows: i64 =
+        sqlx::query_scalar("SELECT count(*) FROM bus_log WHERE message_id = 'stable-event'")
+            .fetch_one(&pool)
+            .await
+            .expect("count stable ID rows");
+    let retained_seq: i64 =
+        sqlx::query_scalar("SELECT seq FROM bus_log WHERE message_id = 'stable-event'")
+            .fetch_one(&pool)
+            .await
+            .expect("read retained cursor");
+    let retained_metadata: String =
+        sqlx::query_scalar("SELECT metadata FROM bus_log WHERE message_id = 'stable-event'")
+            .fetch_one(&pool)
+            .await
+            .expect("read authoritative metadata");
+    assert_eq!(rows, 1, "ambiguous retry did not append a second row");
+    assert_eq!(
+        retained_seq, original_seq,
+        "ambiguous retry retained the original ordered cursor"
+    );
+    assert!(
+        retained_metadata.contains("first-attempt"),
+        "the first committed envelope remains authoritative"
+    );
+    assert!(!retained_metadata.contains("retry-attempt"));
+
+    let payload_conflict = Message::new(
+        EVENT_NAME,
+        MessageKind::Event,
+        br#"{"different":true}"#.to_vec(),
+    )
+    .with_id("stable-event")
+    .with_metadata(CAUSATION_ID, "command-1");
+    let error = bus
+        .publish_message(payload_conflict)
+        .await
+        .expect_err("same stable ID cannot identify a different payload");
+    assert!(error.is_permanent(), "conflict is deterministic corruption");
+
+    let causation_conflict = event("stable-event").with_metadata(CAUSATION_ID, "different-command");
+    let error = bus
+        .publish_message(causation_conflict)
+        .await
+        .expect_err("same stable ID cannot identify a different causation");
+    assert!(error.is_permanent(), "causation conflict is permanent");
+
+    let rows_after_conflicts: i64 =
+        sqlx::query_scalar("SELECT count(*) FROM bus_log WHERE message_id = 'stable-event'")
+            .fetch_one(&pool)
+            .await
+            .expect("count rows after conflicts");
+    assert_eq!(rows_after_conflicts, 1, "conflicts leave the log unchanged");
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn concurrent_stable_log_retries_share_one_original_cursor() {
+    let (_db, pool, bus) = bus().await;
+    let first = event("concurrent-stable")
+        .with_metadata(CAUSATION_ID, "command-concurrent")
+        .with_metadata(TRACEPARENT, "attempt-a");
+    let retry = event("concurrent-stable")
+        .with_metadata(CAUSATION_ID, "command-concurrent")
+        .with_metadata(TRACEPARENT, "attempt-b");
+
+    let (first_result, retry_result) =
+        tokio::join!(bus.publish_message(first), bus.publish_message(retry));
+    first_result.expect("one concurrent append wins");
+    retry_result.expect("the equivalent concurrent append is idempotent");
+
+    let rows: i64 =
+        sqlx::query_scalar("SELECT count(*) FROM bus_log WHERE message_id = 'concurrent-stable'")
+            .fetch_one(&pool)
+            .await
+            .expect("count concurrent stable ID rows");
+    let seq: i64 =
+        sqlx::query_scalar("SELECT seq FROM bus_log WHERE message_id = 'concurrent-stable'")
+            .fetch_one(&pool)
+            .await
+            .expect("read stable cursor");
+    assert_eq!(rows, 1);
+    assert_eq!(seq, 1, "the only allocated cursor remains authoritative");
+}
+
+#[tokio::test]
+async fn legacy_equivalent_stable_id_duplicates_retain_the_minimum_cursor() {
+    let (_db, pool, bus) = bus().await;
+    sqlx::query("DROP INDEX bus_log_message_id_unique_idx")
+        .execute(&pool)
+        .await
+        .expect("simulate legacy schema without uniqueness");
+    let first_metadata = serde_json::to_string(&vec![
+        (CAUSATION_ID, "legacy-command"),
+        (TRACEPARENT, "legacy-first"),
+    ])
+    .unwrap();
+    let retry_metadata = serde_json::to_string(&vec![
+        (CAUSATION_ID, "legacy-command"),
+        (TRACEPARENT, "legacy-retry"),
+    ])
+    .unwrap();
+    for metadata in [&first_metadata, &retry_metadata] {
+        sqlx::query(
+            "INSERT INTO bus_log \
+                 (name, message_id, kind, payload, content_type, metadata) \
+             VALUES (?, 'legacy-stable', 'event', ?, 'application/json', ?)",
+        )
+        .bind(EVENT_NAME)
+        .bind(PAYLOAD)
+        .bind(metadata)
+        .execute(&pool)
+        .await
+        .expect("seed equivalent legacy duplicate");
+    }
+
+    bus.ensure_tables()
+        .await
+        .expect("equivalent duplicates are migrated safely");
+    let retained: (i64, String, i64) = sqlx::query_as(
+        "SELECT MIN(seq), MIN(metadata), COUNT(*) \
+         FROM bus_log WHERE message_id = 'legacy-stable'",
+    )
+    .fetch_one(&pool)
+    .await
+    .expect("read migrated legacy row");
+    assert_eq!(retained.0, 1, "the minimum legacy cursor is authoritative");
+    assert_eq!(retained.2, 1);
+    assert!(
+        retained.1.contains("legacy-first"),
+        "the first committed envelope is retained"
+    );
+    let unique_index: i64 = sqlx::query_scalar(
+        "SELECT COUNT(*) FROM sqlite_master \
+         WHERE type = 'index' AND name = 'bus_log_message_id_unique_idx'",
+    )
+    .fetch_one(&pool)
+    .await
+    .expect("inspect stable ID index");
+    assert_eq!(unique_index, 1);
+}
+
+#[tokio::test]
+async fn legacy_conflicting_stable_id_duplicates_fail_preflight_without_mutation() {
+    let (_db, pool, bus) = bus().await;
+    sqlx::query("DROP INDEX bus_log_message_id_unique_idx")
+        .execute(&pool)
+        .await
+        .expect("simulate legacy schema without uniqueness");
+    for payload in [br#"{}"#.as_slice(), br#"{"different":true}"#.as_slice()] {
+        sqlx::query(
+            "INSERT INTO bus_log \
+                 (name, message_id, kind, payload, content_type, metadata) \
+             VALUES (?, 'legacy-conflict', 'event', ?, 'application/json', '[]')",
+        )
+        .bind(EVENT_NAME)
+        .bind(payload)
+        .execute(&pool)
+        .await
+        .expect("seed conflicting legacy duplicate");
+    }
+
+    let error = bus
+        .ensure_tables()
+        .await
+        .expect_err("conflicting legacy duplicates fail closed");
+    assert!(error.is_permanent());
+    let rows: i64 =
+        sqlx::query_scalar("SELECT COUNT(*) FROM bus_log WHERE message_id = 'legacy-conflict'")
+            .fetch_one(&pool)
+            .await
+            .expect("count untouched conflicting rows");
+    let unique_index: i64 = sqlx::query_scalar(
+        "SELECT COUNT(*) FROM sqlite_master \
+         WHERE type = 'index' AND name = 'bus_log_message_id_unique_idx'",
+    )
+    .fetch_one(&pool)
+    .await
+    .expect("inspect absent stable ID index");
+    assert_eq!(rows, 2, "failed preflight rolls back deduplication");
+    assert_eq!(unique_index, 0, "no unsafe uniqueness fence was installed");
+}
+
+#[tokio::test]
+async fn nonempty_log_identity_adoption_must_be_explicit_and_retires_offsets() {
+    let (_db, pool, bus) = bus().await;
+    bus.publish_message(event("identity-loss"))
+        .await
+        .expect("append before identity loss");
+    let retired_epoch: String =
+        sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+            .fetch_one(&pool)
+            .await
+            .expect("read retired epoch");
+    sqlx::query(
+        "INSERT INTO bus_offset (consumer, source_epoch, last_seq) \
+         VALUES ('stale-consumer', ?, 1)",
+    )
+    .bind(&retired_epoch)
+    .execute(&pool)
+    .await
+    .expect("seed stale bound offset");
+    sqlx::query("DROP TABLE bus_log_identity")
+        .execute(&pool)
+        .await
+        .expect("simulate independently lost identity");
+
+    let error = bus
+        .ensure_tables()
+        .await
+        .expect_err("a retained log cannot receive a random replacement epoch");
+    assert!(error.is_permanent());
+    let identities: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM bus_log_identity")
+        .fetch_one(&pool)
+        .await
+        .expect("count rolled-back identity");
+    let offsets_before_adoption: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM bus_offset")
+        .fetch_one(&pool)
+        .await
+        .expect("count still-bound offsets");
+    assert_eq!(
+        identities, 0,
+        "failed default adoption installs no identity"
+    );
+    assert_eq!(
+        offsets_before_adoption, 1,
+        "failed default adoption does not clear offsets"
+    );
+
+    let adopted_epoch = ProjectionEpoch::new("operator-adopted-retained-log").unwrap();
+    SqliteBus::new(pool.clone())
+        .with_source_epoch(adopted_epoch.clone())
+        .ensure_tables()
+        .await
+        .expect("explicitly adopt the retained log");
+    let replacement_epoch: String =
+        sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+            .fetch_one(&pool)
+            .await
+            .expect("read replacement epoch");
+    let offsets: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM bus_offset")
+        .fetch_one(&pool)
+        .await
+        .expect("count retired offsets");
+    assert_ne!(replacement_epoch, retired_epoch);
+    assert_eq!(replacement_epoch, adopted_epoch.as_str());
+    assert_eq!(
+        offsets, 0,
+        "identity creation and offset invalidation commit together"
+    );
+}
+
+#[tokio::test]
+async fn configured_epoch_initializes_but_cannot_relabel_an_existing_log() {
+    let db = TempDb::new("distributed_sqlite_bus_epoch_override");
+    let pool = db.pool().await;
+    let initial_epoch = ProjectionEpoch::new("operator-generation-1").unwrap();
+    let bus = SqliteBus::new(pool.clone())
+        .group("epoch-observer")
+        .with_source_epoch(initial_epoch.clone());
+    bus.ensure_tables()
+        .await
+        .expect("configured epoch initializes a new log");
+    let persisted: String =
+        sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+            .fetch_one(&pool)
+            .await
+            .expect("read initialized epoch");
+    assert_eq!(persisted, initial_epoch.as_str());
+    bus.publish_message(event("delivered-epoch"))
+        .await
+        .expect("append under configured epoch");
+    let recorder = Arc::new(OrderedEvidenceRecorder::default());
+    bus.subscribe(recorder.clone(), RunOptions::idempotent())
+        .await
+        .expect("deliver ordered row");
+    assert_eq!(
+        *recorder.observed.lock().unwrap(),
+        vec![(persisted.clone(), 1)],
+        "delivery exposes the durable row's epoch and original SQL position"
+    );
+
+    let mismatched = SqliteBus::new(pool.clone())
+        .with_source_epoch(ProjectionEpoch::new("operator-generation-2").unwrap());
+    let error = mismatched
+        .ensure_tables()
+        .await
+        .expect_err("a builder override cannot relabel existing positions");
+    assert!(error.is_permanent());
+    let error = mismatched
+        .publish_message(event("must-not-append"))
+        .await
+        .expect_err("producer mismatch fails before append");
+    assert!(error.is_permanent());
+    let rows: i64 = sqlx::query_scalar("SELECT count(*) FROM bus_log")
+        .fetch_one(&pool)
+        .await
+        .expect("count log rows");
+    let still_persisted: String =
+        sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+            .fetch_one(&pool)
+            .await
+            .expect("read unchanged epoch");
+    assert_eq!(rows, 1, "mismatched producer did not append");
+    assert_eq!(still_persisted, initial_epoch.as_str());
+}
+
+#[tokio::test]
+async fn log_rewind_requires_an_explicit_fenced_reset() {
+    let (_db, pool, bus) = bus().await;
+    bus.publish_message(event("before-reset"))
+        .await
+        .expect("append before reset");
+
+    let (before_epoch, before_generation, before_high_water): (String, i64, i64) = sqlx::query_as(
+        "SELECT source_epoch, generation, high_water \
+             FROM bus_log_identity WHERE singleton = 1",
+    )
+    .fetch_one(&pool)
+    .await
+    .expect("read initial log identity");
+    assert_eq!(before_generation, 1);
+    assert_eq!(before_high_water, 1);
+    sqlx::query(
+        "INSERT INTO bus_offset (consumer, source_epoch, last_seq) \
+         VALUES ('projector', ?, 1)",
+    )
+    .bind(&before_epoch)
+    .execute(&pool)
+    .await
+    .expect("seed old generation offset");
+
+    sqlx::query("DROP TABLE bus_log")
+        .execute(&pool)
+        .await
+        .expect("simulate independently rebuilt log");
+    let error = SqliteBus::new(pool.clone())
+        .ensure_tables()
+        .await
+        .expect_err("ordinary startup cannot authorize cursor-domain reuse");
+    assert!(error.is_permanent());
+    let error = bus
+        .publish_message(event("must-not-rotate"))
+        .await
+        .expect_err("ordinary publish cannot authorize cursor-domain reuse");
+    assert!(error.is_permanent());
+    let replacement_rows: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM bus_log")
+        .fetch_one(&pool)
+        .await
+        .expect("count replacement rows before reset");
+    assert_eq!(replacement_rows, 0);
+    let unchanged: (String, i64, i64) = sqlx::query_as(
+        "SELECT source_epoch, generation, high_water \
+         FROM bus_log_identity WHERE singleton = 1",
+    )
+    .fetch_one(&pool)
+    .await
+    .expect("read unchanged rewind fence");
+    assert_eq!(
+        unchanged,
+        (before_epoch.clone(), before_generation, before_high_water)
+    );
+    let offsets_before_reset: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM bus_offset")
+        .fetch_one(&pool)
+        .await
+        .expect("count fenced offsets");
+    assert_eq!(offsets_before_reset, 1);
+
+    let expected_epoch = ProjectionEpoch::new(before_epoch.clone()).unwrap();
+    let wrong_epoch = ProjectionEpoch::new("wrong-current-generation").unwrap();
+    let next_epoch = ProjectionEpoch::new("operator-reset-generation-2").unwrap();
+    let error = bus
+        .reset_ordered_log(&wrong_epoch, &next_epoch)
+        .await
+        .expect_err("compare-and-swap reset rejects a stale expected epoch");
+    assert!(error.is_permanent());
+    let error = bus
+        .reset_ordered_log(&expected_epoch, &expected_epoch)
+        .await
+        .expect_err("a reset cannot reuse the retired epoch");
+    assert!(error.is_permanent());
+    bus.reset_ordered_log(&expected_epoch, &next_epoch)
+        .await
+        .expect("operator-authorized reset");
+
+    let (after_epoch, after_generation, after_high_water): (String, i64, i64) = sqlx::query_as(
+        "SELECT source_epoch, generation, high_water \
+             FROM bus_log_identity WHERE singleton = 1",
+    )
+    .fetch_one(&pool)
+    .await
+    .expect("read rotated log identity");
+    assert_eq!(after_epoch, next_epoch.as_str());
+    assert_eq!(after_generation, before_generation + 1);
+    assert_eq!(after_high_water, 0);
+    let offsets: i64 = sqlx::query_scalar("SELECT count(*) FROM bus_offset")
+        .fetch_one(&pool)
+        .await
+        .expect("count retired offsets");
+    assert_eq!(offsets, 0, "old-generation offsets cannot skip the new log");
+
+    let rebuilt = SqliteBus::new(pool.clone());
+    rebuilt
+        .publish_message(event("after-reset"))
+        .await
+        .expect("append in new generation");
+    let new_seq: i64 =
+        sqlx::query_scalar("SELECT seq FROM bus_log WHERE message_id = 'after-reset'")
+            .fetch_one(&pool)
+            .await
+            .expect("read rebuilt cursor");
+    let persisted_epoch: String =
+        sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+            .fetch_one(&pool)
+            .await
+            .expect("read persisted epoch");
+    assert_eq!(new_seq, 1, "the rebuilt log reused a numeric position");
+    assert_eq!(
+        persisted_epoch, after_epoch,
+        "ordinary appends retain the rotated epoch"
+    );
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn running_subscriber_stops_before_cached_rows_after_epoch_rotation() {
+    let (_db, pool, producer) = bus().await;
+    for index in 0..17 {
+        producer
+            .publish_message(event(format!("old-{index}")))
+            .await
+            .expect("append old-generation event");
+    }
+    let router = Arc::new(RotationRouter::default());
+    let subscriber = SqliteBus::new(pool.clone()).group("rotation-observer");
+    let running = tokio::spawn({
+        let router = router.clone();
+        async move { subscriber.subscribe(router, RunOptions::idempotent()).await }
+    });
+    tokio::time::timeout(Duration::from_secs(2), router.first_started.notified())
+        .await
+        .expect("first buffered delivery started");
+
+    let current_epoch: String =
+        sqlx::query_scalar("SELECT source_epoch FROM bus_log_identity WHERE singleton = 1")
+            .fetch_one(&pool)
+            .await
+            .expect("read current epoch");
+    let current_epoch = ProjectionEpoch::new(current_epoch).unwrap();
+    let next_epoch = ProjectionEpoch::new("live-reset-generation-2").unwrap();
+    producer
+        .reset_ordered_log(&current_epoch, &next_epoch)
+        .await
+        .expect("reset log while a handler is in flight");
+    let replacement = SqliteBus::new(pool.clone());
+    replacement
+        .publish_message(event("new-0"))
+        .await
+        .expect("append replacement-generation event");
+    router.release_first.notify_one();
+
+    let error = tokio::time::timeout(Duration::from_secs(2), running)
+        .await
+        .expect("subscriber stopped")
+        .expect("subscriber task joined")
+        .expect_err("retired subscriber fails closed");
+    assert!(error.is_permanent(), "epoch mismatch is not retryable");
+    assert_eq!(
+        *router.seen.lock().unwrap(),
+        vec!["old-0".to_string()],
+        "cached old rows and replacement rows were never dispatched"
+    );
+    let offsets: i64 =
+        sqlx::query_scalar("SELECT count(*) FROM bus_offset WHERE consumer = 'rotation-observer'")
+            .fetch_one(&pool)
+            .await
+            .expect("count stale offsets");
+    assert_eq!(offsets, 0, "retired delivery did not settle into new epoch");
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
 async fn expired_queue_claim_cannot_be_settled_by_stale_worker() {
     let (_db, pool, bus) = bus().await;
@@ -426,23 +1013,26 @@ async fn expired_queue_claim_cannot_be_settled_by_stale_worker() {
     let attempts = Arc::new(AtomicUsize::new(0));
     let first_claimed = Arc::new(Notify::new());
     let second_claimed = Arc::new(Notify::new());
+    let allow_first_finish = Arc::new(Notify::new());
     let allow_second_finish = Arc::new(Notify::new());
 
     let handlers = Arc::new({
         let attempts = attempts.clone();
         let first_claimed = first_claimed.clone();
         let second_claimed = second_claimed.clone();
+        let allow_first_finish = allow_first_finish.clone();
         let allow_second_finish = allow_second_finish.clone();
         Handlers::new().on_command(COMMAND_NAME, move |_: &Message| {
             let attempt = attempts.fetch_add(1, Ordering::SeqCst);
             let first_claimed = first_claimed.clone();
             let second_claimed = second_claimed.clone();
+            let allow_first_finish = allow_first_finish.clone();
             let allow_second_finish = allow_second_finish.clone();
             async move {
                 match attempt {
                     0 => {
                         first_claimed.notify_one();
-                        tokio::time::sleep(Duration::from_millis(420)).await;
+                        allow_first_finish.notified().await;
                         Ok(())
                     }
                     1 => {
@@ -475,6 +1065,7 @@ async fn expired_queue_claim_cannot_be_settled_by_stale_worker() {
         .await
         .expect("second worker reclaimed the expired lease");
 
+    allow_first_finish.notify_one();
     tokio::time::timeout(Duration::from_secs(2), first)
         .await
         .expect("stale first worker finished")
diff --git a/tests/support/graphql.rs b/tests/support/graphql.rs
new file mode 100644
index 00000000..64410f4c
--- /dev/null
+++ b/tests/support/graphql.rs
@@ -0,0 +1,122 @@
+//! Shared GraphQL test helpers for integration crates via
+//! `#[path = "../support/graphql.rs"]`.
+//!
+//! Prefer driving shipped `GraphqlEngine` / HTTP only — no SQL reimplementation.
+#![allow(dead_code)] // each including target uses a subset
+
+use async_graphql::Request;
+use distributed::graphql::{read, GraphqlEngine, ModelPermissions};
+use distributed::microsvc::{Session, ROLE_KEY, USER_ID_KEY};
+use distributed::ReadModel;
+use serde::{Deserialize, Serialize};
+use sqlx::sqlite::SqlitePoolOptions;
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[table("orders")]
+pub struct OrderView {
+    #[id("order_id")]
+    pub order_id: String,
+    pub customer_id: String,
+    pub status: String,
+    pub total_cents: i64,
+    /// May look like JSON; must remain a GraphQL String.
+    pub note: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[table("parents")]
+pub struct ParentView {
+    #[id("parent_id")]
+    pub parent_id: String,
+    pub name: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ReadModel)]
+#[table("children")]
+pub struct ChildView {
+    #[id("child_id")]
+    pub child_id: String,
+    pub parent_id: String,
+    pub name: String,
+}
+
+pub fn session(role: &str, user: &str) -> Session {
+    let mut s = Session::new();
+    s.set(ROLE_KEY, role);
+    s.set(USER_ID_KEY, user);
+    s
+}
+
+pub async fn seed_orders() -> sqlx::SqlitePool {
+    let pool = SqlitePoolOptions::new()
+        .max_connections(1)
+        .connect("sqlite::memory:")
+        .await
+        .unwrap();
+    sqlx::query(
+        "CREATE TABLE orders (
+            order_id TEXT PRIMARY KEY,
+            customer_id TEXT NOT NULL,
+            status TEXT NOT NULL,
+            total_cents INTEGER NOT NULL,
+            note TEXT NOT NULL
+        );
+        INSERT INTO orders VALUES
+            ('o1', 'tenant-a', 'open', 100, '{\"looks\":\"json\"}'),
+            ('o2', 'tenant-a', 'shipped', 200, 'plain'),
+            ('o3', 'tenant-b', 'open', 50, 'x');",
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+    pool
+}
+
+pub fn engine_all_columns(pool: sqlx::SqlitePool) -> GraphqlEngine {
+    GraphqlEngine::builder(pool)
+        .roles(&["user"])
+        .model::<OrderView>(ModelPermissions::new().grant("user", read().all_columns()))
+        .build()
+        .unwrap()
+}
+
+pub fn assert_no_sql_leak(resp: &async_graphql::Response) {
+    for e in &resp.errors {
+        let m = e.message.to_ascii_lowercase();
+        assert!(
+            !m.contains("select ") && !m.contains(" from ") && !m.contains(" where "),
+            "must not leak SQL: {}",
+            e.message
+        );
+    }
+}
+
+pub fn error_messages(resp: &async_graphql::Response) -> String {
+    resp.errors
+        .iter()
+        .map(|e| e.message.to_ascii_lowercase())
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+pub fn extension_code(err: &async_graphql::ServerError) -> Option<String> {
+    err.extensions
+        .as_ref()
+        .and_then(|ext| ext.get("code"))
+        .map(|v| format!("{v:?}"))
+}
+
+/// Helper: execute and return JSON data (panics if GraphQL errors).
+pub async fn exec_json(
+    engine: &GraphqlEngine,
+    session: &Session,
+    query: &str,
+) -> serde_json::Value {
+    let resp = engine.execute(session, Request::new(query)).await;
+    assert!(
+        resp.errors.is_empty(),
+        "unexpected errors: {:?}",
+        resp.errors
+    );
+    serde_json::to_value(&resp.data).unwrap()
+}
diff --git a/tests/typed_commands/main.rs b/tests/typed_commands/main.rs
new file mode 100644
index 00000000..7df4341e
--- /dev/null
+++ b/tests/typed_commands/main.rs
@@ -0,0 +1,2031 @@
+#![cfg(all(feature = "graphql", feature = "sqlite"))]
+#![allow(dead_code)]
+
+use std::any::TypeId;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use async_graphql::futures_util::StreamExt;
+use async_graphql::Request;
+use axum::body::Body;
+use axum::http::Request as HttpRequest;
+use distributed::graphql::{
+    build_surface, graphql_router_with_service, read, surface_for_role, typed_command, Accepted,
+    DistributedClientSurfaceExport, EffectInputFieldMarker, EffectModelFieldMarker, Fact,
+    GraphqlEngine, GraphqlInputType, GraphqlOutputType, GraphqlTypeDef, GraphqlTypeField,
+    ModelPermissions, PreparedCommand, Projected, RoleGrant, SurfaceDirectProjection,
+    SurfaceOptions, SurfaceProjector,
+};
+use distributed::microsvc::{CausalCommandContext, HandlerError, Routes, Service};
+use distributed::microsvc::{Context, Session};
+use distributed::{
+    command_confirmations, command_effects, command_input_defaults, Aggregate, AggregateRepository,
+    DistributedProjectManifest, Entity, EventRecord, GraphqlInput, GraphqlOutput,
+    InMemoryRepository, ReadModel, RelationalReadModel, SqliteRepository,
+};
+use serde::{Deserialize, Serialize};
+use tower::util::ServiceExt;
+
+static GRAPHQL_TYPED_GUARD_INVOKED: AtomicBool = AtomicBool::new(false);
+static GRAPHQL_TYPED_HANDLER_INVOKED: AtomicBool = AtomicBool::new(false);
+const TEST_PROTOCOL_TOKEN_KEY: [u8; 32] = [0x5a; 32];
+
+#[derive(Default)]
+struct FixtureAggregate {
+    entity: Entity,
+}
+
+impl Aggregate for FixtureAggregate {
+    type ReplayError = String;
+
+    fn aggregate_type() -> &'static str {
+        "typed-command-fixture"
+    }
+
+    fn entity(&self) -> &Entity {
+        &self.entity
+    }
+
+    fn entity_mut(&mut self) -> &mut Entity {
+        &mut self.entity
+    }
+
+    fn replay_event(&mut self, _event: &EventRecord) -> Result<(), Self::ReplayError> {
+        Ok(())
+    }
+}
+
+fn causal_routes() -> Routes<AggregateRepository<InMemoryRepository, FixtureAggregate>> {
+    Routes::new().with_repo(AggregateRepository::new(InMemoryRepository::new()))
+}
+
+#[derive(Deserialize)]
+struct InputA {
+    id: String,
+}
+
+#[derive(Serialize)]
+struct OutputA {
+    id: String,
+}
+
+#[derive(Deserialize)]
+struct InputB {
+    id: String,
+}
+
+#[derive(Serialize)]
+struct OutputB {
+    id: String,
+}
+
+#[derive(Clone, Deserialize, GraphqlInput)]
+struct PlanInput {
+    id: String,
+    title: String,
+}
+
+#[derive(Clone, Deserialize, GraphqlInput)]
+struct RenamedDefaultInput {
+    #[serde(rename = "todoId")]
+    id: String,
+}
+
+#[derive(Serialize, GraphqlOutput)]
+struct PlanOutput {
+    id: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "plan_views", primary_key = ["id"])]
+struct PlanView {
+    id: String,
+    title: String,
+    count: i64,
+    #[readmodel(text)]
+    status: PlanStatus,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+enum PlanStatus {
+    Open,
+    Closed,
+}
+
+impl GraphqlOutputType for PlanView {
+    fn graphql_type() -> GraphqlTypeDef {
+        GraphqlTypeDef::new(
+            "PlanView",
+            vec![
+                GraphqlTypeField {
+                    name: "id".into(),
+                    type_name: "String".into(),
+                    nullable: false,
+                    list: false,
+                    item_nullable: false,
+                    nested: None,
+                },
+                GraphqlTypeField {
+                    name: "title".into(),
+                    type_name: "String".into(),
+                    nullable: false,
+                    list: false,
+                    item_nullable: false,
+                    nested: None,
+                },
+                GraphqlTypeField {
+                    name: "count".into(),
+                    type_name: "BigInt".into(),
+                    nullable: false,
+                    list: false,
+                    item_nullable: false,
+                    nested: None,
+                },
+                GraphqlTypeField {
+                    name: "status".into(),
+                    type_name: "String".into(),
+                    nullable: false,
+                    list: false,
+                    item_nullable: false,
+                    nested: None,
+                },
+            ],
+        )
+        .with_type_id(TypeId::of::<Self>())
+    }
+}
+
+#[derive(Clone, Deserialize, GraphqlInput)]
+struct ForgedInput {
+    id: String,
+    title: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "forged_views", primary_key = ["id"])]
+struct ForgedView {
+    id: String,
+    count: i64,
+}
+
+#[derive(Clone, Serialize, Deserialize, GraphqlInput)]
+struct JsonDocument {
+    label: String,
+}
+
+#[derive(Clone, Deserialize, GraphqlInput)]
+struct JsonPatchInput {
+    id: String,
+    tags: Vec<String>,
+    details: JsonDocument,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "json_views", primary_key = ["id"])]
+struct JsonView {
+    id: String,
+    #[readmodel(jsonb)]
+    tags: Vec<String>,
+    #[readmodel(jsonb)]
+    details: JsonDocument,
+}
+
+#[derive(Clone, Deserialize, GraphqlInput)]
+struct BigIntKeyInput {
+    key: i64,
+    title: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "bigint_key_views", primary_key = ["key"])]
+struct BigIntKeyView {
+    id: String,
+    key: i64,
+    title: String,
+}
+
+#[derive(Clone, Deserialize, GraphqlInput)]
+struct BigIntRelationshipInput {
+    source_key: i64,
+    target_id: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "bigint_relation_targets", primary_key = ["id"])]
+struct BigIntRelationshipTarget {
+    id: String,
+    #[readmodel(
+        foreign_key = "bigint_relation_sources.key",
+        delegated_from = "BigIntRelationshipSource.key"
+    )]
+    source_key: i64,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "bigint_relation_sources", primary_key = ["key"])]
+struct BigIntRelationshipSource {
+    id: String,
+    key: i64,
+    #[readmodel(has_many = "BigIntRelationshipTarget", foreign_key = "source_key")]
+    targets: Vec<BigIntRelationshipTarget>,
+}
+
+#[derive(Clone, Deserialize, GraphqlInput)]
+struct NullableKeyInput {
+    key: Option<String>,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "nullable_key_views", primary_key = ["key"])]
+struct NullableKeyView {
+    id: String,
+    key: Option<String>,
+    title: String,
+}
+
+#[derive(Clone, Deserialize, GraphqlInput)]
+struct CompositeKeyInput {
+    tenant_id: String,
+    id: String,
+    title: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(
+    table = "composite_key_views",
+    primary_key = ["tenant_id", "id"]
+)]
+struct CompositeKeyView {
+    tenant_id: String,
+    id: String,
+    title: String,
+}
+
+#[derive(Clone, Deserialize, GraphqlInput)]
+struct FloatEffectInput {
+    id: String,
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "float_effect_views", primary_key = ["id"])]
+struct FloatEffectView {
+    id: String,
+    value: Option<f64>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+struct NestedJsonFloat {
+    value: f64,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+struct NestedJsonDocument {
+    nested: NestedJsonFloat,
+}
+
+const NONFINITE_JSON_DOCUMENT: NestedJsonDocument = NestedJsonDocument {
+    nested: NestedJsonFloat {
+        value: f64::NEG_INFINITY,
+    },
+};
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "json_float_effect_views", primary_key = ["id"])]
+struct JsonFloatEffectView {
+    id: String,
+    #[readmodel(jsonb)]
+    value_f32: f32,
+    #[readmodel(jsonb)]
+    value_f64: f64,
+    #[readmodel(jsonb)]
+    document: serde_json::Value,
+    #[readmodel(jsonb)]
+    nested_document: NestedJsonDocument,
+}
+
+#[derive(Clone, Debug)]
+struct BrokenText;
+
+impl Serialize for BrokenText {
+    fn serialize<S>(&self, _serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        Err(serde::ser::Error::custom("broken constant serializer"))
+    }
+}
+
+impl<'de> Deserialize<'de> for BrokenText {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let _ = serde::de::IgnoredAny::deserialize(deserializer)?;
+        Ok(Self)
+    }
+}
+
+#[derive(Clone, Serialize, Deserialize, ReadModel)]
+#[readmodel(table = "broken_constant_views", primary_key = ["id"])]
+struct BrokenConstantView {
+    id: String,
+    #[readmodel(text)]
+    value: BrokenText,
+}
+
+struct ForgedTitleMarker;
+
+impl EffectInputFieldMarker for ForgedTitleMarker {
+    type Input = ForgedInput;
+    type Value = String;
+    type NonNullValue = String;
+    type Nullability = distributed::graphql::EffectRequired;
+    type PathKind = distributed::graphql::EffectInputTerminalKind;
+    type Wire = distributed::graphql::EffectWireString;
+    type Nested = String;
+
+    fn path() -> Vec<&'static str> {
+        vec!["title"]
+    }
+}
+
+struct ForgedCountMarker;
+
+impl EffectModelFieldMarker for ForgedCountMarker {
+    type Model = ForgedView;
+    // Deliberately lies about the independently-derived SQL/GraphQL field.
+    type Value = String;
+    type Wire = distributed::graphql::EffectWireString;
+    const FIELD: &'static str = "count";
+}
+
+struct ForgedDefaultMarker;
+
+impl EffectInputFieldMarker for ForgedDefaultMarker {
+    type Input = PlanInput;
+    type Value = String;
+    type NonNullValue = String;
+    type Nullability = distributed::graphql::EffectRequired;
+    type PathKind = distributed::graphql::EffectInputTerminalKind;
+    type Wire = distributed::graphql::EffectWireString;
+    type Nested = String;
+
+    fn path() -> Vec<&'static str> {
+        vec!["missing"]
+    }
+}
+
+fn object_type<T: 'static>(name: &str) -> GraphqlTypeDef {
+    GraphqlTypeDef::new(
+        name,
+        vec![GraphqlTypeField {
+            name: "id".into(),
+            type_name: "String".into(),
+            nullable: false,
+            list: false,
+            item_nullable: false,
+            nested: None,
+        }],
+    )
+    .with_type_id(TypeId::of::<T>())
+}
+
+impl GraphqlInputType for InputA {
+    fn graphql_type() -> GraphqlTypeDef {
+        object_type::<Self>("CommandInput")
+    }
+}
+
+impl GraphqlOutputType for OutputA {
+    fn graphql_type() -> GraphqlTypeDef {
+        object_type::<Self>("CommandOutput")
+    }
+}
+
+impl GraphqlInputType for InputB {
+    fn graphql_type() -> GraphqlTypeDef {
+        object_type::<Self>("CommandInput")
+    }
+}
+
+impl GraphqlOutputType for OutputB {
+    fn graphql_type() -> GraphqlTypeDef {
+        object_type::<Self>("CommandOutput")
+    }
+}
+
+async fn handler_a(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    input: InputA,
+) -> Result<PreparedCommand<Accepted<OutputA>>, HandlerError> {
+    Ok(PreparedCommand::prepare(OutputA { id: input.id }).unwrap())
+}
+
+async fn guarded_handler_a(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    input: InputA,
+) -> Result<PreparedCommand<Accepted<OutputA>>, HandlerError> {
+    GRAPHQL_TYPED_HANDLER_INVOKED.store(true, Ordering::SeqCst);
+    Ok(PreparedCommand::<Accepted<OutputA>>::prepare(OutputA { id: input.id }).unwrap())
+}
+
+async fn handler_b(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    input: InputB,
+) -> Result<PreparedCommand<Accepted<OutputB>>, HandlerError> {
+    Ok(PreparedCommand::<Accepted<OutputB>>::prepare(OutputB { id: input.id }).unwrap())
+}
+
+async fn accepted_plan_handler(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    input: PlanInput,
+) -> Result<PreparedCommand<Accepted<PlanOutput>>, HandlerError> {
+    Ok(PreparedCommand::<Accepted<PlanOutput>>::prepare(PlanOutput { id: input.id }).unwrap())
+}
+
+async fn renamed_default_handler(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    input: RenamedDefaultInput,
+) -> Result<PreparedCommand<Accepted<PlanOutput>>, HandlerError> {
+    Ok(PreparedCommand::<Accepted<PlanOutput>>::prepare(PlanOutput { id: input.id }).unwrap())
+}
+
+async fn fact_plan_handler(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    input: PlanInput,
+) -> Result<PreparedCommand<Fact<PlanOutput>>, HandlerError> {
+    Ok(PreparedCommand::<Fact<PlanOutput>>::prepare(PlanOutput { id: input.id }).unwrap())
+}
+
+async fn projected_plan_handler(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    _input: PlanInput,
+) -> Result<PreparedCommand<Projected<PlanView>>, HandlerError> {
+    Err(HandlerError::Rejected(
+        "projected preparation requires CausalCommandContext::projected".into(),
+    ))
+}
+
+async fn forged_handler(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    input: ForgedInput,
+) -> Result<PreparedCommand<Accepted<PlanOutput>>, HandlerError> {
+    Ok(PreparedCommand::<Accepted<PlanOutput>>::prepare(PlanOutput { id: input.id }).unwrap())
+}
+
+async fn json_patch_handler(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    input: JsonPatchInput,
+) -> Result<PreparedCommand<Accepted<PlanOutput>>, HandlerError> {
+    Ok(PreparedCommand::<Accepted<PlanOutput>>::prepare(PlanOutput { id: input.id }).unwrap())
+}
+
+async fn bigint_key_handler(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    input: BigIntKeyInput,
+) -> Result<PreparedCommand<Accepted<PlanOutput>>, HandlerError> {
+    Ok(
+        PreparedCommand::<Accepted<PlanOutput>>::prepare(PlanOutput {
+            id: input.key.to_string(),
+        })
+        .unwrap(),
+    )
+}
+
+async fn nullable_key_handler(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    input: NullableKeyInput,
+) -> Result<PreparedCommand<Accepted<PlanOutput>>, HandlerError> {
+    Ok(
+        PreparedCommand::<Accepted<PlanOutput>>::prepare(PlanOutput {
+            id: input.key.unwrap_or_default(),
+        })
+        .unwrap(),
+    )
+}
+
+async fn bigint_relationship_handler(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    input: BigIntRelationshipInput,
+) -> Result<PreparedCommand<Accepted<PlanOutput>>, HandlerError> {
+    Ok(
+        PreparedCommand::<Accepted<PlanOutput>>::prepare(PlanOutput {
+            id: input.target_id,
+        })
+        .unwrap(),
+    )
+}
+
+async fn composite_key_handler(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    input: CompositeKeyInput,
+) -> Result<PreparedCommand<Accepted<PlanOutput>>, HandlerError> {
+    Ok(PreparedCommand::<Accepted<PlanOutput>>::prepare(PlanOutput { id: input.id }).unwrap())
+}
+
+async fn float_effect_handler(
+    _context: &CausalCommandContext<'_, FixtureAggregate>,
+    input: FloatEffectInput,
+) -> Result<PreparedCommand<Accepted<PlanOutput>>, HandlerError> {
+    Ok(PreparedCommand::<Accepted<PlanOutput>>::prepare(PlanOutput { id: input.id }).unwrap())
+}
+
+fn plan_projector() -> SurfaceProjector {
+    SurfaceProjector::new("project_plan")
+        .facts(["plan.changed"])
+        .models(["PlanView"])
+        .partition_by(["id"])
+}
+
+fn direct_plan_projection() -> SurfaceDirectProjection {
+    SurfaceDirectProjection::new("project_plan")
+        .model::<PlanView>()
+        .change_epoch("plan-direct-v1")
+}
+
+fn plan_confirmations() -> distributed::graphql::CompiledConfirmationPlan<PlanInput> {
+    let projector = plan_projector();
+    confirmations_for(&projector)
+}
+
+fn plan_input_defaults() -> distributed::graphql::CompiledInputDefaults<PlanInput> {
+    command_input_defaults! {
+        input: PlanInput;
+        default input.id = uuid_v7();
+    }
+}
+
+fn forged_input_defaults() -> distributed::graphql::CompiledInputDefaults<PlanInput> {
+    distributed::graphql::__command_input_defaults::<PlanInput>([
+        distributed::graphql::__input_default_uuid_v7::<PlanInput, ForgedDefaultMarker>(),
+    ])
+}
+
+fn confirmations_for(
+    projector: &SurfaceProjector,
+) -> distributed::graphql::CompiledConfirmationPlan<PlanInput> {
+    command_confirmations! {
+        input: PlanInput;
+        confirm projector -> PlanView {
+            key { id: input.id },
+            partition: input.id
+        };
+    }
+}
+
+fn plan_permissions(role: &str) -> ModelPermissions<PlanView> {
+    ModelPermissions::new().grant(role, read().all_columns())
+}
+
+fn forged_effects() -> distributed::graphql::CompiledCommandEffects<ForgedInput> {
+    let key: distributed::graphql::TypedEffectKey<ForgedView> = __DistributedForgedViewEffectKey {
+        id: distributed::graphql::__effect_key_assignment::<
+            __DistributedForgedViewEffectModelField_id,
+            _,
+        >(distributed::graphql::__effect_input::<
+            ForgedInput,
+            __DistributedForgedInputEffectInputField_id,
+        >()),
+    }
+    .into();
+    distributed::graphql::__command_effects::<ForgedInput>([
+        distributed::graphql::__effect_patch::<ForgedView>(
+            key,
+            vec![distributed::graphql::__effect_assignment::<
+                ForgedCountMarker,
+                _,
+            >(distributed::graphql::__effect_input::<
+                ForgedInput,
+                ForgedTitleMarker,
+            >())],
+        ),
+    ])
+}
+
+fn forged_primary_key_assignment_effects() -> distributed::graphql::CompiledCommandEffects<PlanInput>
+{
+    let key: distributed::graphql::TypedEffectKey<PlanView> = __DistributedPlanViewEffectKey {
+        id: distributed::graphql::__effect_key_assignment::<
+            __DistributedPlanViewEffectModelField_id,
+            _,
+        >(distributed::graphql::__effect_input::<
+            PlanInput,
+            __DistributedPlanInputEffectInputField_id,
+        >()),
+    }
+    .into();
+    distributed::graphql::__command_effects::<PlanInput>([distributed::graphql::__effect_patch::<
+        PlanView,
+    >(
+        key,
+        vec![distributed::graphql::__effect_assignment::<
+            __DistributedPlanViewEffectModelField_id,
+            _,
+        >(distributed::graphql::__effect_input::<
+            PlanInput,
+            __DistributedPlanInputEffectInputField_id,
+        >())],
+    )])
+}
+
+fn two_confirmation_plan(
+    reverse: bool,
+) -> distributed::graphql::CompiledConfirmationPlan<PlanInput> {
+    let first = SurfaceProjector::new("project_a")
+        .facts(["plan.changed"])
+        .models(["PlanView"]);
+    let second = SurfaceProjector::new("project_b")
+        .facts(["plan.changed"])
+        .models(["ForgedView"]);
+    if reverse {
+        command_confirmations! {
+            input: PlanInput;
+            confirm second -> ForgedView { key { id: input.id } };
+            confirm first -> PlanView { key { id: input.id } };
+        }
+    } else {
+        command_confirmations! {
+            input: PlanInput;
+            confirm first -> PlanView { key { id: input.id } };
+            confirm second -> ForgedView { key { id: input.id } };
+        }
+    }
+}
+
+fn service_a(service_id: &str) -> Service {
+    Service::new().named(service_id).routes(
+        causal_routes()
+            .typed_command(typed_command::<InputA, Accepted<OutputA>>("todo.create"))
+            .handle(handler_a),
+    )
+}
+
+fn service_b(service_id: &str) -> Service {
+    Service::new().named(service_id).routes(
+        causal_routes()
+            .typed_command(typed_command::<InputB, Accepted<OutputB>>("todo.create"))
+            .handle(handler_b),
+    )
+}
+
+fn guarded_service_a(service_id: &str) -> Service {
+    Service::new().named(service_id).routes(
+        causal_routes()
+            .typed_command(typed_command::<InputA, Accepted<OutputA>>("todo.create"))
+            .guarded(
+                |_| {
+                    GRAPHQL_TYPED_GUARD_INVOKED.store(true, Ordering::SeqCst);
+                    true
+                },
+                guarded_handler_a,
+            ),
+    )
+}
+
+fn projected_service(service_id: &str, repository: SqliteRepository) -> Service {
+    Service::new().named(service_id).routes(
+        Routes::new()
+            .with_repo(AggregateRepository::<_, FixtureAggregate>::new(repository))
+            .typed_command(typed_command::<PlanInput, Projected<PlanView>>(
+                "plan.projected",
+            ))
+            .handle(projected_plan_handler),
+    )
+}
+
+fn pool() -> sqlx::SqlitePool {
+    sqlx::SqlitePool::connect_lazy("sqlite::memory:").unwrap()
+}
+
+#[tokio::test]
+async fn service_id_mismatch_fails_in_both_builder_call_orders() {
+    let service = service_a("todos");
+
+    let before = GraphqlEngine::builder(pool())
+        .service_id("wrong")
+        .service(&service)
+        .build()
+        .err()
+        .expect("service ID mismatch must fail");
+    assert!(before
+        .to_string()
+        .contains("does not match executable service ID"));
+
+    let after = GraphqlEngine::builder(pool())
+        .service(&service)
+        .service_id("wrong")
+        .build()
+        .err()
+        .expect("service ID overwrite must fail");
+    assert!(after
+        .to_string()
+        .contains("does not match bound executable service ID"));
+}
+
+#[tokio::test]
+async fn attachment_checks_exact_rust_types_after_structural_parity() {
+    let engine_source = service_a("todos");
+    let engine = GraphqlEngine::builder(pool())
+        .service(&engine_source)
+        .build()
+        .unwrap();
+    let executable = service_b("todos");
+
+    let error = executable
+        .try_with_graphql(engine)
+        .err()
+        .expect("lookalike Rust types must not bind");
+    assert!(error.to_string().contains("TypeId mismatch"));
+}
+
+#[tokio::test]
+async fn attachment_checks_full_structure_and_service_identity() {
+    let engine_source = service_a("todos");
+    let engine = GraphqlEngine::builder(pool())
+        .service(&engine_source)
+        .build()
+        .unwrap();
+    let structurally_different = Service::new().named("todos").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<InputA, Accepted<OutputA>>("todo.create")
+                    .field_name("createSomethingElse"),
+            )
+            .handle(handler_a),
+    );
+    let error = structurally_different
+        .try_with_graphql(engine)
+        .err()
+        .expect("structural drift must not bind");
+    assert!(error
+        .to_string()
+        .contains("structural fingerprint mismatch"));
+
+    let engine_source = service_a("todos-a");
+    let engine = GraphqlEngine::builder(pool())
+        .service(&engine_source)
+        .build()
+        .unwrap();
+    let wrong_service = service_a("todos-b");
+    let error = wrong_service
+        .try_with_graphql(engine)
+        .err()
+        .expect("service identity drift must not bind");
+    assert!(error.to_string().contains("service ID mismatch"));
+}
+
+#[tokio::test]
+async fn projected_command_binding_rejects_a_raw_pool_source() {
+    let shared_pool = pool();
+    let route_repository = SqliteRepository::new(shared_pool.clone());
+    let service = projected_service("plans", route_repository);
+    let engine = GraphqlEngine::builder(shared_pool)
+        .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+        .model::<PlanView>(plan_permissions("anonymous"))
+        .service(&service)
+        .client_projection_owners([direct_plan_projection().into()])
+        .build()
+        .expect("a raw pool may build an engine before repository identity validation");
+
+    let error = service
+        .try_with_graphql(engine)
+        .err()
+        .expect("Projected commands must reject a raw GraphQL pool");
+    assert!(
+        error
+            .to_string()
+            .contains("require a GraphQL pool derived from the same repository handle"),
+        "{error}"
+    );
+}
+
+#[tokio::test]
+async fn projected_command_binding_rejects_an_independent_repository_over_the_same_pool() {
+    let shared_pool = pool();
+    let route_repository = SqliteRepository::new(shared_pool.clone());
+    let graphql_repository = SqliteRepository::new(shared_pool);
+    let service = projected_service("plans", route_repository);
+    let engine = GraphqlEngine::builder(&graphql_repository)
+        .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+        .model::<PlanView>(plan_permissions("anonymous"))
+        .service(&service)
+        .client_projection_owners([direct_plan_projection().into()])
+        .build()
+        .expect("the independently constructed repository still provides a valid pool");
+
+    let error = service
+        .try_with_graphql(engine)
+        .err()
+        .expect("Projected commands must reject a different repository identity");
+    assert!(
+        error
+            .to_string()
+            .contains("repository and GraphQL query pool storage identities differ"),
+        "{error}"
+    );
+}
+
+#[tokio::test]
+async fn projected_command_binding_accepts_a_clone_of_the_same_repository_handle() {
+    let shared_pool = pool();
+    let repository = SqliteRepository::new(shared_pool);
+    let service = projected_service("plans", repository.clone());
+    let engine = GraphqlEngine::builder(&repository)
+        .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+        .model::<PlanView>(plan_permissions("anonymous"))
+        .service(&service)
+        .client_projection_owners([direct_plan_projection().into()])
+        .build()
+        .expect("the repository-derived GraphQL pool should build");
+
+    service
+        .try_with_graphql(engine)
+        .expect("a repository clone must preserve the Projected storage identity");
+}
+
+#[tokio::test]
+async fn projector_topology_identity_drift_changes_service_binding_fingerprint() {
+    let declared = SurfaceProjector::new("project_plan")
+        .facts(["plan.changed"])
+        .models(["PlanView"])
+        .partition_by(["id"]);
+    let engine_source = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<PlanInput, Accepted<PlanOutput>>("plan.create")
+                    .confirmations(confirmations_for(&declared)),
+            )
+            .handle(accepted_plan_handler),
+    );
+    let engine = GraphqlEngine::builder(pool())
+        .model::<PlanView>(plan_permissions("anonymous"))
+        .service(&engine_source)
+        .client_projectors([declared])
+        .build()
+        .unwrap();
+
+    let drifted = SurfaceProjector::new("project_plan")
+        .facts(["plan.renamed"])
+        .models(["PlanView"])
+        .partition_by(["id"]);
+    let executable = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<PlanInput, Accepted<PlanOutput>>("plan.create")
+                    .confirmations(confirmations_for(&drifted)),
+            )
+            .handle(accepted_plan_handler),
+    );
+    let error = executable
+        .try_with_graphql(engine)
+        .err()
+        .expect("captured projector topology drift must change service identity");
+    assert!(error
+        .to_string()
+        .contains("structural fingerprint mismatch"));
+}
+
+#[tokio::test]
+async fn matched_typed_inventory_rejects_attachment_without_protocol_tokens() {
+    let service = service_a("todos");
+    let engine = GraphqlEngine::builder(pool())
+        .service(&service)
+        .build()
+        .expect("typed inventory can be compiled before deployment protocol configuration");
+
+    let error = service
+        .try_with_graphql(engine)
+        .err()
+        .expect("causal mutations must not be served without opaque protocol tokens");
+    assert!(
+        error
+            .to_string()
+            .contains("require a configured GraphQL protocol token key"),
+        "{error}"
+    );
+}
+
+#[tokio::test]
+async fn matched_typed_inventory_attaches_while_unverified_mutations_fail_closed() {
+    let service = service_a("todos");
+    let engine = GraphqlEngine::builder(pool())
+        .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+        .service(&service)
+        .build()
+        .unwrap();
+    let service = Arc::new(
+        service
+            .try_with_graphql(engine)
+            .expect("validated causal inventory may attach to GraphQL"),
+    );
+    let engine = service.graphql_engine().unwrap();
+    let query = engine
+        .execute(&Session::new(), Request::new("{ __typename }"))
+        .await;
+    assert!(query.errors.is_empty(), "{query:?}");
+    let mutation = engine
+        .execute(
+            &Session::new(),
+            Request::new(
+                "mutation { todo_create(commandId: \"0190a000-0000-7000-8000-000000000001\", input: { id: \"todo-1\" }) { id } }",
+            )
+            .data(Arc::clone(&service)),
+        )
+        .await;
+    assert_eq!(mutation.errors.len(), 1, "{mutation:?}");
+    assert!(
+        mutation.errors[0]
+            .message
+            .contains("durable commands require a verified OIDC bearer"),
+        "{mutation:?}"
+    );
+}
+
+#[tokio::test]
+async fn every_graphql_dispatch_path_fences_before_typed_guards_and_handlers() {
+    GRAPHQL_TYPED_GUARD_INVOKED.store(false, Ordering::SeqCst);
+    GRAPHQL_TYPED_HANDLER_INVOKED.store(false, Ordering::SeqCst);
+    let service = Arc::new(guarded_service_a("todos"));
+    let engine = Arc::new(
+        GraphqlEngine::builder(pool())
+            .protocol_token_key(TEST_PROTOCOL_TOKEN_KEY)
+            .service(&service)
+            .build()
+            .unwrap(),
+    );
+    let mutation = "mutation { todo_create(commandId: \"0190a000-0000-7000-8000-000000000002\", input: { id: \"todo-1\" }) { id } }";
+
+    let response = engine
+        .execute(&Session::new(), Request::new(mutation))
+        .await;
+    assert_eq!(response.errors.len(), 1, "{response:?}");
+
+    let streamed = engine
+        .execute_stream(&Session::new(), Request::new(mutation))
+        .next()
+        .await
+        .expect("mutation stream emits one fail-closed response");
+    assert_eq!(streamed.errors.len(), 1, "{streamed:?}");
+
+    let router = graphql_router_with_service(Arc::clone(&engine), Arc::clone(&service));
+    let response = router
+        .oneshot(
+            HttpRequest::post("/graphql")
+                .header("content-type", "application/json")
+                .body(Body::from(
+                    serde_json::json!({ "query": mutation }).to_string(),
+                ))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert!(response.status().is_success());
+    assert!(!GRAPHQL_TYPED_GUARD_INVOKED.load(Ordering::SeqCst));
+    assert!(!GRAPHQL_TYPED_HANDLER_INVOKED.load(Ordering::SeqCst));
+}
+
+#[tokio::test]
+async fn router_construction_runs_full_binding_validation() {
+    let engine_source = service_a("todos");
+    let engine = Arc::new(
+        GraphqlEngine::builder(pool())
+            .service(&engine_source)
+            .build()
+            .unwrap(),
+    );
+    let executable = Arc::new(service_b("todos"));
+
+    let panic = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+        graphql_router_with_service(engine, executable)
+    }))
+    .expect_err("router must not serve a mismatched typed inventory");
+    let message = panic
+        .downcast_ref::<String>()
+        .map(String::as_str)
+        .or_else(|| panic.downcast_ref::<&str>().copied())
+        .unwrap_or("unknown panic");
+    assert!(
+        message.contains("TypeId mismatch"),
+        "unexpected panic: {message}"
+    );
+}
+
+#[tokio::test]
+async fn query_only_service_binding_executes_without_a_command_committer() {
+    let service = Service::new().named("query-only");
+    let engine = GraphqlEngine::builder(pool())
+        .service(&service)
+        .build()
+        .unwrap();
+    let response = engine
+        .execute(&Session::new(), Request::new("{ __typename }"))
+        .await;
+    assert!(response.errors.is_empty(), "{response:?}");
+    service
+        .try_with_graphql(engine)
+        .expect("query-only identity binding must attach without causal routes");
+}
+
+#[test]
+fn pool_free_typed_export_preserves_service_provenance_and_rejects_relabeling() {
+    let service = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(typed_command::<PlanInput, Accepted<PlanOutput>>(
+                "plan.create",
+            ))
+            .handle(accepted_plan_handler),
+    );
+    let catalog = build_surface(&[PlanView::schema().clone()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_service(&service)
+        .unwrap();
+    let selected = surface_for_role(
+        &catalog,
+        "anonymous",
+        &std::collections::BTreeMap::from([("PlanView".into(), RoleGrant::all_columns())]),
+    )
+    .unwrap();
+    let project = DistributedProjectManifest::new("plans").table_schema(PlanView::schema().clone());
+    let manifest = DistributedClientSurfaceExport::from_project(&project, selected.clone())
+        .unwrap()
+        .manifest()
+        .unwrap();
+    assert_eq!(manifest.service_id, "plans");
+    assert_eq!(manifest.commands[0].name, "plan.create");
+
+    let relabeled =
+        DistributedProjectManifest::new("other-plans").table_schema(PlanView::schema().clone());
+    let error = DistributedClientSurfaceExport::from_project(&relabeled, selected).unwrap_err();
+    assert!(error
+        .to_string()
+        .contains("does not match typed Surface provenance"));
+}
+
+#[test]
+fn pool_free_service_and_projector_topology_validate_in_both_call_orders() {
+    let make_service = || {
+        Service::new().named("plans").routes(
+            causal_routes()
+                .typed_command(
+                    typed_command::<PlanInput, Accepted<PlanOutput>>("plan.create")
+                        .confirmations(plan_confirmations()),
+                )
+                .handle(accepted_plan_handler),
+        )
+    };
+    let tables = [PlanView::schema().clone()];
+
+    build_surface(&tables, &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_service(&make_service())
+        .unwrap()
+        .with_projectors([plan_projector()])
+        .unwrap();
+    build_surface(&tables, &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_projectors([plan_projector()])
+        .unwrap()
+        .with_service(&make_service())
+        .unwrap();
+
+    let unknown = build_surface(&tables, &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_service(&make_service())
+        .unwrap()
+        .with_projectors([SurfaceProjector::new("some_other_projector")
+            .facts(["plan.changed"])
+            .models(["PlanView"])
+            .partition_by(["id"])])
+        .unwrap_err();
+    assert!(unknown.contains("expects unknown projector `project_plan`"));
+
+    let wrong_model = build_surface(
+        &[PlanView::schema().clone(), ForgedView::schema().clone()],
+        &SurfaceOptions::sqlite(),
+    )
+    .unwrap()
+    .with_projectors([SurfaceProjector::new("project_plan")
+        .facts(["plan.changed"])
+        .models(["ForgedView"])
+        .partition_by(["id"])])
+    .unwrap()
+    .with_service(&make_service())
+    .unwrap_err();
+    assert!(
+        wrong_model.contains("topology identity does not match"),
+        "{wrong_model}"
+    );
+
+    let wrong_facts = build_surface(&tables, &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_service(&make_service())
+        .unwrap()
+        .with_projectors([SurfaceProjector::new("project_plan")
+            .facts(["some.other.fact"])
+            .models(["PlanView"])
+            .partition_by(["id"])])
+        .unwrap_err();
+    assert!(wrong_facts.contains("topology identity does not match"));
+
+    let changed_model_set = build_surface(
+        &[PlanView::schema().clone(), ForgedView::schema().clone()],
+        &SurfaceOptions::sqlite(),
+    )
+    .unwrap()
+    .with_service(&make_service())
+    .unwrap()
+    .with_projectors([SurfaceProjector::new("project_plan")
+        .facts(["plan.changed"])
+        .models(["PlanView", "ForgedView"])
+        .partition_by(["id"])])
+    .unwrap_err();
+    assert!(changed_model_set.contains("topology identity does not match"));
+
+    let captured_reordered = SurfaceProjector::new("project_plan")
+        .facts(["plan.changed", "plan.created", "plan.changed"])
+        .models(["ForgedView", "PlanView", "PlanView"])
+        .partition_by(["id"]);
+    let service = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<PlanInput, Accepted<PlanOutput>>("plan.create")
+                    .confirmations(confirmations_for(&captured_reordered)),
+            )
+            .handle(accepted_plan_handler),
+    );
+    build_surface(
+        &[PlanView::schema().clone(), ForgedView::schema().clone()],
+        &SurfaceOptions::sqlite(),
+    )
+    .unwrap()
+    .with_service(&service)
+    .unwrap()
+    .with_projectors([SurfaceProjector::new("project_plan")
+        .facts(["plan.created", "plan.changed"])
+        .models(["PlanView", "ForgedView"])
+        .partition_by(["id"])])
+    .expect("fact/model ordering and duplicates are not topology identity drift");
+}
+
+#[test]
+fn pool_free_selection_rejects_omitted_confirmation_topology() {
+    let service = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<PlanInput, Fact<PlanOutput>>("plan.fact")
+                    .confirmations(plan_confirmations()),
+            )
+            .handle(fact_plan_handler),
+    );
+    let catalog = build_surface(&[PlanView::schema().clone()], &SurfaceOptions::sqlite())
+        .unwrap()
+        .with_service(&service)
+        .unwrap();
+    let error = surface_for_role(
+        &catalog,
+        "anonymous",
+        &std::collections::BTreeMap::from([("PlanView".into(), RoleGrant::all_columns())]),
+    )
+    .unwrap_err();
+    assert!(error.contains("expects unknown projector `project_plan`"));
+}
+
+#[tokio::test]
+async fn execute_stream_cannot_dispatch_through_an_injected_legacy_service() {
+    let typed = service_a("todos");
+    let engine = GraphqlEngine::builder(pool())
+        .service(&typed)
+        .build()
+        .unwrap();
+    let invoked = Arc::new(AtomicBool::new(false));
+    let handler_flag = Arc::clone(&invoked);
+    let raw_service = Arc::new(
+        Service::new()
+            .named("unrelated")
+            .routes(
+                Routes::new()
+                    .command("todo.create")
+                    .handle(move |_: &Context<()>| {
+                        let handler_flag = Arc::clone(&handler_flag);
+                        async move {
+                            handler_flag.store(true, Ordering::SeqCst);
+                            Ok(serde_json::json!({ "id": "forged" }))
+                        }
+                    }),
+            ),
+    );
+    let request = Request::new(
+        "mutation { todo_create(commandId: \"0190a000-0000-7000-8000-000000000003\", input: { id: \"todo-1\" }) { id } }",
+    )
+    .data(raw_service);
+    let response = engine
+        .execute_stream(&Session::new(), request)
+        .next()
+        .await
+        .expect("fail-closed stream emits one response");
+    assert_eq!(response.errors.len(), 1, "{response:?}");
+    assert!(!response.errors.is_empty(), "{response:?}");
+    assert!(!invoked.load(Ordering::SeqCst));
+}
+
+#[tokio::test]
+async fn manifest_populates_typed_consistency_and_revalidation_effects() {
+    let service = service_a("todos");
+    let engine = GraphqlEngine::builder(pool())
+        .service(&service)
+        .build()
+        .unwrap();
+    let manifest = engine.client_manifest_for_role("anonymous").unwrap();
+    let command = manifest
+        .commands
+        .iter()
+        .find(|command| command.name == "todo.create")
+        .unwrap();
+
+    assert_eq!(command.extensions.consistency.kind, "accepted");
+    let effects = command.extensions.effects.as_ref().unwrap();
+    assert!(effects.operations.is_empty());
+    assert_eq!(effects.fallback, "revalidate");
+    assert!(manifest.capabilities.causal_receipts);
+    assert!(!manifest.capabilities.confirmed_persistence);
+}
+
+#[tokio::test]
+async fn generated_input_default_is_reused_as_the_effect_key_and_fingerprinted() {
+    let command_with_default = || {
+        typed_command::<PlanInput, Accepted<PlanOutput>>("plan.create")
+            .input_defaults(plan_input_defaults())
+            .confirmations(plan_confirmations())
+            .effects(command_effects! {
+                input: PlanInput;
+                upsert PlanView {
+                    key { id: input.id },
+                    set { title: input.title, count: 0 }
+                };
+            })
+    };
+    let service_with_default = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(command_with_default())
+            .handle(accepted_plan_handler),
+    );
+    let engine = GraphqlEngine::builder(pool())
+        .model::<PlanView>(plan_permissions("anonymous"))
+        .service(&service_with_default)
+        .client_projectors([plan_projector()])
+        .build()
+        .unwrap();
+    let manifest = engine.client_manifest_for_role("anonymous").unwrap();
+    let command = &manifest.commands[0];
+    let defaults = command.extensions.input_defaults.as_ref().unwrap();
+    assert_eq!(defaults.version, 1);
+    assert_eq!(defaults.defaults.len(), 1);
+    assert_eq!(defaults.defaults[0]["path"], serde_json::json!(["id"]));
+    assert_eq!(defaults.defaults[0]["generator"], "uuid_v7");
+    let effect = &command.extensions.effects.as_ref().unwrap().operations[0];
+    assert_eq!(
+        effect["key"]["fields"][0]["value"]["path"],
+        serde_json::json!(["id"])
+    );
+    let confirmation = &command.extensions.confirmations.as_ref().unwrap().expected[0];
+    assert_eq!(
+        confirmation["key"]["fields"][0]["value"]["path"],
+        serde_json::json!(["id"])
+    );
+    assert_eq!(confirmation["partition"]["path"], serde_json::json!(["id"]));
+
+    let without_default = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<PlanInput, Accepted<PlanOutput>>("plan.create")
+                    .confirmations(plan_confirmations())
+                    .effects(command_effects! {
+                        input: PlanInput;
+                        upsert PlanView {
+                            key { id: input.id },
+                            set { title: input.title, count: 0 }
+                        };
+                    }),
+            )
+            .handle(accepted_plan_handler),
+    );
+    let manifest_without_default = GraphqlEngine::builder(pool())
+        .model::<PlanView>(plan_permissions("anonymous"))
+        .service(&without_default)
+        .client_projectors([plan_projector()])
+        .build()
+        .unwrap()
+        .client_manifest_for_role("anonymous")
+        .unwrap();
+    assert_ne!(
+        manifest.schema_fingerprint,
+        manifest_without_default.schema_fingerprint
+    );
+    let error = without_default
+        .try_with_graphql(engine)
+        .err()
+        .expect("input-default drift must change the service binding fingerprint");
+    assert!(error
+        .to_string()
+        .contains("structural fingerprint mismatch"));
+}
+
+#[tokio::test]
+async fn forged_input_default_marker_is_revalidated_against_wire_shape() {
+    let service = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<PlanInput, Accepted<PlanOutput>>("plan.create")
+                    .input_defaults(forged_input_defaults()),
+            )
+            .handle(accepted_plan_handler),
+    );
+    let error = GraphqlEngine::builder(pool())
+        .service(&service)
+        .build()
+        .err()
+        .expect("forged default markers must not bypass Surface validation");
+    assert!(error
+        .to_string()
+        .contains("references unknown field `missing`"));
+}
+
+#[tokio::test]
+async fn generated_input_default_uses_the_canonical_renamed_wire_path() {
+    let service = Service::new().named("todos").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<RenamedDefaultInput, Accepted<PlanOutput>>("todo.create")
+                    .input_defaults(command_input_defaults! {
+                        input: RenamedDefaultInput;
+                        default input.id = uuid_v7();
+                    }),
+            )
+            .handle(renamed_default_handler),
+    );
+    let manifest = GraphqlEngine::builder(pool())
+        .service(&service)
+        .build()
+        .unwrap()
+        .client_manifest_for_role("anonymous")
+        .unwrap();
+    let defaults = manifest.commands[0]
+        .extensions
+        .input_defaults
+        .as_ref()
+        .unwrap();
+    assert_eq!(defaults.defaults[0]["path"], serde_json::json!(["todoId"]));
+}
+
+#[tokio::test]
+async fn json_container_leaves_reach_the_manifest() {
+    let json_service = Service::new().named("json").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<JsonPatchInput, Accepted<PlanOutput>>("json.patch").effects(
+                    command_effects! {
+                        input: JsonPatchInput;
+                        patch JsonView {
+                            key { id: input.id },
+                            set { tags: input.tags, details: input.details }
+                        };
+                    },
+                ),
+            )
+            .handle(json_patch_handler),
+    );
+    let manifest = GraphqlEngine::builder(pool())
+        .model::<JsonView>(ModelPermissions::new().grant("anonymous", read().all_columns()))
+        .service(&json_service)
+        .build()
+        .unwrap()
+        .client_manifest_for_role("anonymous")
+        .unwrap();
+    let effects = manifest.commands[0].extensions.effects.as_ref().unwrap();
+    assert_eq!(effects.operations.len(), 1);
+    let effects_json = serde_json::to_string(&effects.operations).unwrap();
+    assert!(effects_json.contains("tags"), "{effects_json}");
+    assert!(effects_json.contains("details"), "{effects_json}");
+}
+
+#[tokio::test]
+async fn embedded_primary_keys_reject_keyed_effects_while_composite_keys_remain_normalized() {
+    let bigint_manifest = GraphqlEngine::builder(pool())
+        .service_id("bigint-read")
+        .model::<BigIntKeyView>(ModelPermissions::new().grant("anonymous", read().all_columns()))
+        .build()
+        .unwrap()
+        .client_manifest_for_role("anonymous")
+        .unwrap();
+    assert_eq!(
+        bigint_manifest.models[0].normalization,
+        distributed::graphql::ModelNormalization::Embedded
+    );
+    let bigint_service = Service::new().named("bigint").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<BigIntKeyInput, Accepted<PlanOutput>>("bigint.upsert").effects(
+                    command_effects! {
+                        input: BigIntKeyInput;
+                        upsert BigIntKeyView {
+                            key { key: input.key },
+                            set { title: input.title }
+                        };
+                    },
+                ),
+            )
+            .handle(bigint_key_handler),
+    );
+    let error = GraphqlEngine::builder(pool())
+        .model::<BigIntKeyView>(ModelPermissions::new().grant("anonymous", read().all_columns()))
+        .service(&bigint_service)
+        .build()
+        .err()
+        .expect("BigInt identities must not accept keyed optimistic effects");
+    assert!(error.to_string().contains("embedded model `BigIntKeyView`"));
+
+    let relationship_service = Service::new().named("bigint-relationship").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<BigIntRelationshipInput, Accepted<PlanOutput>>("bigint.link")
+                    .effects(command_effects! {
+                        input: BigIntRelationshipInput;
+                        link BigIntRelationshipSource.targets -> BigIntRelationshipTarget {
+                            source { key: input.source_key },
+                            target { id: input.target_id }
+                        };
+                    }),
+            )
+            .handle(bigint_relationship_handler),
+    );
+    let error = GraphqlEngine::builder(pool())
+        .model::<BigIntRelationshipSource>(
+            ModelPermissions::new().grant("anonymous", read().all_columns()),
+        )
+        .model::<BigIntRelationshipTarget>(
+            ModelPermissions::new().grant("anonymous", read().all_columns()),
+        )
+        .service(&relationship_service)
+        .build()
+        .err()
+        .expect("relationship effects must reject embedded source identities");
+    assert!(error
+        .to_string()
+        .contains("embedded model `BigIntRelationshipSource`"));
+
+    let schema_error = NullableKeyView::schema()
+        .validate()
+        .expect_err("relational primary keys cannot be nullable");
+    assert!(schema_error
+        .to_string()
+        .contains("primary-key column `key` must be non-null"));
+    let nullable_service = Service::new().named("nullable").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<NullableKeyInput, Accepted<PlanOutput>>("nullable.delete").effects(
+                    command_effects! {
+                        input: NullableKeyInput;
+                        delete NullableKeyView { key { key: input.key } };
+                    },
+                ),
+            )
+            .handle(nullable_key_handler),
+    );
+    let error = GraphqlEngine::builder(pool())
+        .model::<NullableKeyView>(ModelPermissions::new().grant("anonymous", read().all_columns()))
+        .service(&nullable_service)
+        .build()
+        .err()
+        .expect("nullable identities must be rejected before keyed optimistic effects");
+    assert!(error
+        .to_string()
+        .contains("primary-key column `key` must be non-null"));
+
+    let composite_service = Service::new().named("composite").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<CompositeKeyInput, Accepted<PlanOutput>>("composite.patch")
+                    .effects(command_effects! {
+                        input: CompositeKeyInput;
+                        patch CompositeKeyView {
+                            key { tenant_id: input.tenant_id, id: input.id },
+                            set { title: input.title }
+                        };
+                    }),
+            )
+            .handle(composite_key_handler),
+    );
+    let composite_manifest = GraphqlEngine::builder(pool())
+        .model::<CompositeKeyView>(ModelPermissions::new().grant("anonymous", read().all_columns()))
+        .service(&composite_service)
+        .build()
+        .unwrap()
+        .client_manifest_for_role("anonymous")
+        .unwrap();
+    let distributed::graphql::ModelNormalization::Normalized { fields, .. } =
+        &composite_manifest.models[0].normalization
+    else {
+        panic!("ordinary non-null composite identity must remain normalized");
+    };
+    assert_eq!(
+        fields
+            .iter()
+            .map(|field| field.name.as_str())
+            .collect::<Vec<_>>(),
+        ["tenant_id", "id"]
+    );
+    assert_eq!(
+        composite_manifest.commands[0]
+            .extensions
+            .effects
+            .as_ref()
+            .unwrap()
+            .operations
+            .len(),
+        1
+    );
+}
+
+#[tokio::test]
+async fn embedded_models_retain_global_invalidation_and_server_resolved_confirmations() {
+    let projector = SurfaceProjector::new("project_bigint")
+        .facts(["bigint.changed"])
+        .models(["BigIntKeyView"]);
+    let confirmations = command_confirmations! {
+        input: BigIntKeyInput;
+        confirm projector -> BigIntKeyView { key { key: input.key } };
+    };
+    let service = Service::new().named("bigint").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<BigIntKeyInput, Accepted<PlanOutput>>("bigint.invalidate")
+                    .confirmations(confirmations)
+                    .effects(command_effects! {
+                        input: BigIntKeyInput;
+                        invalidate BigIntKeyView;
+                    }),
+            )
+            .handle(bigint_key_handler),
+    );
+    let manifest = GraphqlEngine::builder(pool())
+        .model::<BigIntKeyView>(ModelPermissions::new().grant("anonymous", read().all_columns()))
+        .service(&service)
+        .client_projectors([projector])
+        .build()
+        .unwrap()
+        .client_manifest_for_role("anonymous")
+        .unwrap();
+
+    assert_eq!(
+        manifest.models[0].normalization,
+        distributed::graphql::ModelNormalization::Embedded
+    );
+    let command = &manifest.commands[0];
+    assert_eq!(
+        command.extensions.effects.as_ref().unwrap().operations[0]["kind"],
+        "invalidate_model"
+    );
+    let confirmations = command.extensions.confirmations.as_ref().unwrap();
+    assert_eq!(confirmations.kind, "finite");
+    assert_eq!(confirmations.expected[0]["model"], "BigIntKeyView");
+    assert_eq!(
+        confirmations.expected[0]["key"]["fields"][0]["value"]["path"],
+        serde_json::json!(["key"])
+    );
+}
+
+#[tokio::test]
+async fn upsert_and_patch_effects_cannot_assign_primary_key_fields() {
+    let service = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<PlanInput, Accepted<PlanOutput>>("plan.bad_patch")
+                    .effects(forged_primary_key_assignment_effects()),
+            )
+            .handle(accepted_plan_handler),
+    );
+    let error = GraphqlEngine::builder(pool())
+        .model::<PlanView>(plan_permissions("anonymous"))
+        .service(&service)
+        .build()
+        .err()
+        .expect("forged primary-key assignments must fail Surface validation");
+    assert!(error
+        .to_string()
+        .contains("cannot assign primary-key field"));
+}
+
+#[tokio::test]
+async fn accepted_finite_confirmation_is_exported_and_marks_the_projector_causal() {
+    let command = typed_command::<PlanInput, Accepted<PlanOutput>>("plan.create")
+        .input_defaults(plan_input_defaults())
+        .confirmations(plan_confirmations())
+        .effects(command_effects! {
+            input: PlanInput;
+            upsert PlanView {
+                key { id: input.id },
+                set { title: input.title, count: 0 }
+            };
+        });
+    let service = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(command)
+            .handle(accepted_plan_handler),
+    );
+    let engine = GraphqlEngine::builder(pool())
+        .model::<PlanView>(plan_permissions("anonymous"))
+        .service(&service)
+        .client_projectors([plan_projector()])
+        .build()
+        .unwrap();
+    let manifest = engine.client_manifest_for_role("anonymous").unwrap();
+    let command = manifest
+        .commands
+        .iter()
+        .find(|command| command.name == "plan.create")
+        .unwrap();
+    let confirmations = command.extensions.confirmations.as_ref().unwrap();
+    assert_eq!(confirmations.kind, "finite");
+    assert_eq!(confirmations.expected.len(), 1);
+    assert_eq!(confirmations.expected[0]["projector"], "project_plan");
+    assert_eq!(confirmations.expected[0]["model"], "PlanView");
+    assert!(confirmations.expected[0]
+        .get("projector_topology")
+        .is_none());
+    assert!(confirmations.expected[0].get("facts").is_none());
+    assert_eq!(confirmations.fallback, "revalidate");
+    assert!(
+        manifest
+            .projectors
+            .iter()
+            .find(|projector| projector.name == "project_plan")
+            .unwrap()
+            .causal_confirmation
+    );
+}
+
+#[tokio::test]
+async fn text_backed_enum_constant_reaches_a_valid_client_manifest() {
+    let command =
+        typed_command::<PlanInput, Accepted<PlanOutput>>("plan.close").effects(command_effects! {
+            input: PlanInput;
+            patch PlanView {
+                key { id: input.id },
+                set { status: constant(PlanStatus::Closed) }
+            };
+        });
+    let service = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(command)
+            .handle(accepted_plan_handler),
+    );
+    let engine = GraphqlEngine::builder(pool())
+        .model::<PlanView>(plan_permissions("anonymous"))
+        .service(&service)
+        .build()
+        .unwrap();
+    let manifest = engine.client_manifest_for_role("anonymous").unwrap();
+    let operations = &manifest.commands[0]
+        .extensions
+        .effects
+        .as_ref()
+        .unwrap()
+        .operations;
+    assert_eq!(operations[0]["fields"][0]["field"], "status");
+    assert_eq!(operations[0]["fields"][0]["value"]["value"], "Closed");
+}
+
+#[tokio::test]
+async fn fallible_constant_serialization_returns_a_build_error_without_panicking() {
+    let result = std::panic::catch_unwind(|| {
+        let service = Service::new().named("broken").routes(
+            causal_routes()
+                .typed_command(
+                    typed_command::<PlanInput, Accepted<PlanOutput>>("broken.patch").effects(
+                        command_effects! {
+                            input: PlanInput;
+                            patch BrokenConstantView {
+                                key { id: input.id },
+                                set { value: constant(BrokenText) }
+                            };
+                        },
+                    ),
+                )
+                .handle(accepted_plan_handler),
+        );
+        GraphqlEngine::builder(pool())
+            .model::<BrokenConstantView>(
+                ModelPermissions::new().grant("anonymous", read().all_columns()),
+            )
+            .service(&service)
+            .build()
+            .err()
+            .expect("invalid constant serialization must be a configuration error")
+            .to_string()
+    });
+    let error = result.expect("constant construction and registry build must not panic");
+    assert!(error.contains("constant effect value failed to serialize"));
+    assert!(error.contains("broken constant serializer"));
+}
+
+#[tokio::test]
+async fn nonfinite_float_constant_is_rejected_but_explicit_null_is_portable() {
+    let nonfinite = Service::new().named("floats").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<FloatEffectInput, Accepted<PlanOutput>>("float.nan").effects(
+                    command_effects! {
+                        input: FloatEffectInput;
+                        patch FloatEffectView {
+                            key { id: input.id },
+                            set { value: constant(f64::NAN) }
+                        };
+                    },
+                ),
+            )
+            .handle(float_effect_handler),
+    );
+    let error = GraphqlEngine::builder(pool())
+        .model::<FloatEffectView>(ModelPermissions::new().grant("anonymous", read().all_columns()))
+        .service(&nonfinite)
+        .build()
+        .err()
+        .expect("non-finite Float constants must not become implicit SQL null");
+    assert!(error
+        .to_string()
+        .contains("non-finite f32/f64 constants cannot be represented"));
+
+    let explicit_null = Service::new().named("floats").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<FloatEffectInput, Accepted<PlanOutput>>("float.clear").effects(
+                    command_effects! {
+                        input: FloatEffectInput;
+                        patch FloatEffectView {
+                            key { id: input.id },
+                            set { value: null() }
+                        };
+                    },
+                ),
+            )
+            .handle(float_effect_handler),
+    );
+    let manifest = GraphqlEngine::builder(pool())
+        .model::<FloatEffectView>(ModelPermissions::new().grant("anonymous", read().all_columns()))
+        .service(&explicit_null)
+        .build()
+        .unwrap()
+        .client_manifest_for_role("anonymous")
+        .unwrap();
+    assert_eq!(
+        manifest.commands[0]
+            .extensions
+            .effects
+            .as_ref()
+            .unwrap()
+            .operations[0]["fields"][0]["value"]["kind"],
+        "null"
+    );
+}
+
+#[tokio::test]
+async fn json_backed_constants_reject_nonfinite_floats_but_preserve_json_null() {
+    let nonfinite_f32 = Service::new().named("json-floats").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<FloatEffectInput, Accepted<PlanOutput>>("json-float.infinity")
+                    .effects(command_effects! {
+                        input: FloatEffectInput;
+                        patch JsonFloatEffectView {
+                            key { id: input.id },
+                            set { value_f32: constant(f32::INFINITY) }
+                        };
+                    }),
+            )
+            .handle(float_effect_handler),
+    );
+    let error = GraphqlEngine::builder(pool())
+        .model::<JsonFloatEffectView>(
+            ModelPermissions::new().grant("anonymous", read().all_columns()),
+        )
+        .service(&nonfinite_f32)
+        .build()
+        .err()
+        .expect("non-finite f32 JSON constants must fail before serialization");
+    assert!(error
+        .to_string()
+        .contains("non-finite f32/f64 constants cannot be represented"));
+
+    let nonfinite_f64 = Service::new().named("json-floats").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<FloatEffectInput, Accepted<PlanOutput>>("json-float.nan").effects(
+                    command_effects! {
+                        input: FloatEffectInput;
+                        patch JsonFloatEffectView {
+                            key { id: input.id },
+                            set { value_f64: constant(f64::NAN) }
+                        };
+                    },
+                ),
+            )
+            .handle(float_effect_handler),
+    );
+    let error = GraphqlEngine::builder(pool())
+        .model::<JsonFloatEffectView>(
+            ModelPermissions::new().grant("anonymous", read().all_columns()),
+        )
+        .service(&nonfinite_f64)
+        .build()
+        .err()
+        .expect("non-finite f64 JSON constants must fail before serialization");
+    assert!(error
+        .to_string()
+        .contains("non-finite f32/f64 constants cannot be represented"));
+
+    let nested_nonfinite = Service::new().named("json-floats").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<FloatEffectInput, Accepted<PlanOutput>>("json-float.nested")
+                    .effects(command_effects! {
+                        input: FloatEffectInput;
+                        patch JsonFloatEffectView {
+                            key { id: input.id },
+                            set { nested_document: constant(NONFINITE_JSON_DOCUMENT) }
+                        };
+                    }),
+            )
+            .handle(float_effect_handler),
+    );
+    let error = GraphqlEngine::builder(pool())
+        .model::<JsonFloatEffectView>(
+            ModelPermissions::new().grant("anonymous", read().all_columns()),
+        )
+        .service(&nested_nonfinite)
+        .build()
+        .err()
+        .expect("nested non-finite JSON constants must fail before serialization");
+    assert!(error
+        .to_string()
+        .contains("non-finite f32/f64 constants cannot be represented"));
+
+    let json_null = Service::new().named("json-floats").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<FloatEffectInput, Accepted<PlanOutput>>("json.clear").effects(
+                    command_effects! {
+                        input: FloatEffectInput;
+                        patch JsonFloatEffectView {
+                            key { id: input.id },
+                            set { document: constant(serde_json::Value::Null) }
+                        };
+                    },
+                ),
+            )
+            .handle(float_effect_handler),
+    );
+    let manifest = GraphqlEngine::builder(pool())
+        .model::<JsonFloatEffectView>(
+            ModelPermissions::new().grant("anonymous", read().all_columns()),
+        )
+        .service(&json_null)
+        .build()
+        .unwrap()
+        .client_manifest_for_role("anonymous")
+        .unwrap();
+    let value = &manifest.commands[0]
+        .extensions
+        .effects
+        .as_ref()
+        .unwrap()
+        .operations[0]["fields"][0]["value"];
+    assert_eq!(value["kind"], "constant");
+    assert!(value["value"].is_null());
+}
+
+#[tokio::test]
+async fn consistency_confirmation_matrix_fails_closed() {
+    let missing_fact = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(typed_command::<PlanInput, Fact<PlanOutput>>("plan.fact"))
+            .handle(fact_plan_handler),
+    );
+    let error = GraphqlEngine::builder(pool())
+        .service(&missing_fact)
+        .build()
+        .err()
+        .expect("fact without a finite plan must fail");
+    assert!(error
+        .to_string()
+        .contains("must declare at least one expected projector confirmation"));
+
+    let projected = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<PlanInput, Projected<PlanView>>("plan.projected")
+                    .confirmations(plan_confirmations()),
+            )
+            .handle(projected_plan_handler),
+    );
+    let error = GraphqlEngine::builder(pool())
+        .service(&projected)
+        .build()
+        .err()
+        .expect("projected with async confirmation must fail");
+    assert!(error
+        .to_string()
+        .contains("cannot declare asynchronous projector confirmations"));
+}
+
+#[tokio::test]
+async fn role_redaction_erases_the_whole_confirmation_and_optimistic_plan() {
+    let command = typed_command::<PlanInput, Accepted<PlanOutput>>("plan.create")
+        .input_defaults(plan_input_defaults())
+        .confirmations(plan_confirmations())
+        .effects(command_effects! {
+            input: PlanInput;
+            patch PlanView {
+                key { id: input.id },
+                set { title: input.title }
+            };
+        });
+    let service = Service::new().named("plans").routes(
+        causal_routes()
+            .typed_command(command)
+            .handle(accepted_plan_handler),
+    );
+    let engine = GraphqlEngine::builder(pool())
+        .model::<PlanView>(ModelPermissions::new().grant("user", read().columns(["title"])))
+        .service(&service)
+        .client_projectors([plan_projector()])
+        .build()
+        .unwrap();
+    let manifest = engine.client_manifest_for_role("user").unwrap();
+    let command = &manifest.commands[0];
+    assert!(command.extensions.input_defaults.is_some());
+    let confirmations = command.extensions.confirmations.as_ref().unwrap();
+    assert_eq!(confirmations.kind, "unavailable");
+    assert!(confirmations.expected.is_empty());
+    assert_eq!(confirmations.fallback, "revalidate");
+    let effects = command.extensions.effects.as_ref().unwrap();
+    assert!(effects.operations.is_empty());
+    assert_eq!(effects.fallback, "revalidate");
+    assert!(manifest
+        .projectors
+        .iter()
+        .all(|projector| !projector.causal_confirmation));
+}
+
+#[tokio::test]
+async fn forged_name_valid_marker_types_are_rejected_from_wire_metadata() {
+    let service = Service::new().named("forged").routes(
+        causal_routes()
+            .typed_command(
+                typed_command::<ForgedInput, Accepted<PlanOutput>>("forged.patch")
+                    .effects(forged_effects()),
+            )
+            .handle(forged_handler),
+    );
+    let error = GraphqlEngine::builder(pool())
+        .model::<ForgedView>(ModelPermissions::new().grant("anonymous", read().all_columns()))
+        .service(&service)
+        .build()
+        .err()
+        .expect("wire String -> BigInt must fail despite forged marker Value types");
+    assert!(error.to_string().contains("has GraphQL type `String`"));
+    assert!(error.to_string().contains("requires `BigInt`"));
+}
+
+#[tokio::test]
+async fn confirmation_set_order_does_not_change_manifest_fingerprint() {
+    let build = |reverse| {
+        let service = Service::new().named("plans").routes(
+            causal_routes()
+                .typed_command(
+                    typed_command::<PlanInput, Accepted<PlanOutput>>("plan.create")
+                        .confirmations(two_confirmation_plan(reverse)),
+                )
+                .handle(accepted_plan_handler),
+        );
+        GraphqlEngine::builder(pool())
+            .model::<PlanView>(plan_permissions("anonymous"))
+            .model::<ForgedView>(ModelPermissions::new().grant("anonymous", read().all_columns()))
+            .service(&service)
+            .client_projectors([
+                SurfaceProjector::new("project_a")
+                    .facts(["plan.changed"])
+                    .models(["PlanView"]),
+                SurfaceProjector::new("project_b")
+                    .facts(["plan.changed"])
+                    .models(["ForgedView"]),
+            ])
+            .build()
+            .unwrap()
+            .client_manifest_for_role("anonymous")
+            .unwrap()
+    };
+    let first = build(false);
+    let second = build(true);
+    assert_eq!(first.schema_fingerprint, second.schema_fingerprint);
+    assert_eq!(first.commands, second.commands);
+}