rememberstack 0.4.0__tar.gz → 0.4.2__tar.gz

rememberstack-0.4.2/.github/ci/path-filters.yml

@@ -0,0 +1,75 @@
+# Maps source areas to integration test directories / compose.
+# Shared-core paths expand to a broader pack (see ci.yml).
+quality:
+  - 'src/**'
+  - 'benchmarks/**'
+  - 'pyproject.toml'
+  - 'uv.lock'
+  - '.github/workflows/**'
+  - '.github/ci/**'
+  - 'ruff.toml'
+  - 'alembic.ini'
+
+unit:
+  - 'src/**'
+  - 'benchmarks/**'
+  - 'pyproject.toml'
+  - 'uv.lock'
+  - '.github/ci/unit-paths.txt'
+
+contract:
+  - 'src/**'
+  - 'pyproject.toml'
+  - 'uv.lock'
+  - 'alembic.ini'
+  - 'src/rememberstack/spine/migrations/**'
+  - '.github/ci/contract-smoke-paths.txt'
+
+workers:
+  - 'src/rememberstack/workers/**'
+  - 'src/rememberstack/spine/**'
+  - 'src/rememberstack/model/**'
+  - 'src/tests/workers/**'
+  - 'src/tests/spine/**'
+
+surfaces:
+  - 'src/rememberstack/surfaces/**'
+  - 'src/rememberstack/spine/query_space/**'
+  - 'src/rememberstack/spine/projection.py'
+  - 'src/rememberstack/spine/resolver.py'
+  - 'src/rememberstack/core/**'
+  - 'src/tests/surfaces/**'
+  - 'src/tests/eval/**'
+
+adapters:
+  - 'src/rememberstack/adapters/**'
+  - 'src/rememberstack/profiles/**'
+  - 'src/tests/adapters/**'
+  - 'src/tests/profiles/**'
+  - 'src/tests/spikes/**'
+  - 'src/tests/test_*.py'
+
+compose:
+  - 'compose.yaml'
+  - 'Dockerfile'
+  - 'Dockerfile.postgres'
+  - '.github/compose/**'
+  - '.env.example'
+  - 'src/rememberstack/profiles/**'
+  - 'src/rememberstack/adapters/selfhost/**'
+  - 'pyproject.toml'
+  - 'uv.lock'
+
+# Touching these forces the broad integration pack on PRs.
+shared_core:
+  - 'src/rememberstack/model/**'
+  - 'src/rememberstack/ports/**'
+  - 'src/rememberstack/spine/**'
+  - 'src/rememberstack/workers/base.py'
+  - 'src/rememberstack/profiles/**'
+
+# CI control plane changes must exercise soft lanes on their own PR.
+ci_control:
+  - '.github/workflows/ci.yml'
+  - '.github/workflows/ci-nightly.yml'
+  - '.github/ci/**'

rememberstack-0.4.2/.github/ci/start-postgres.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+image_name="rememberstack-postgres:ci"
+container_name="rememberstack-postgres-ci"
+
+docker build --file Dockerfile.postgres --tag "${image_name}" .
+docker rm --force "${container_name}" >/dev/null 2>&1 || true
+docker run --detach --name "${container_name}" \
+  --env POSTGRES_USER=rememberstack \
+  --env POSTGRES_PASSWORD=rememberstack_test \
+  --env POSTGRES_DB=rememberstack_test \
+  --publish 5432:5432 \
+  "${image_name}" \
+  postgres \
+  -c shared_preload_libraries=pg_textsearch,pg_partman_bgw \
+  -c pg_partman_bgw.dbname=rememberstack_test \
+  -c pg_partman_bgw.role=rememberstack
+
+for attempt in $(seq 1 60); do
+  if docker exec "${container_name}" \
+    psql --username rememberstack --dbname rememberstack_test \
+      --tuples-only --command 'SELECT 1' >/dev/null 2>&1; then
+    exit 0
+  fi
+  sleep 1
+done
+
+docker logs "${container_name}"
+exit 1

rememberstack-0.4.2/.github/ci/unit-paths.txt

@@ -0,0 +1,68 @@
+src/tests/adapters/test_codex_writer.py
+src/tests/adapters/test_postgres_p1.py
+src/tests/adapters/test_minio_store.py
+src/tests/adapters/test_openrouter.py
+src/tests/adapters/test_selfhost_forget.py
+src/tests/adapters/test_selfhost_git.py
+src/tests/adapters/test_selfhost_purge.py
+src/tests/adapters/test_selfhost_stores.py
+src/tests/adapters/test_sentry.py
+src/tests/adapters/test_telemetry.py
+src/tests/benchmarks/test_beam_answer_agent.py
+src/tests/benchmarks/test_beam_official_score.py
+src/tests/benchmarks/test_locomo_dataset.py
+src/tests/benchmarks/test_locomo_protocol.py
+src/tests/benchmarks/test_locomo_retrieval.py
+src/tests/benchmarks/test_locomo_runner.py
+src/tests/benchmarks/test_locomo_sharding.py
+src/tests/benchmarks/test_locomo_store_backup.py
+src/tests/core/test_blockizer_corpus.py
+src/tests/core/test_chunker.py
+src/tests/core/test_consumption_skill.py
+src/tests/core/test_conversion.py
+src/tests/core/test_core_manifest.py
+src/tests/core/test_d80_recovery_and_hydration.py
+src/tests/core/test_embedding_input_policy.py
+src/tests/core/test_forget_identity.py
+src/tests/core/test_knowledge_authored.py
+src/tests/core/test_knowledge_compile.py
+src/tests/core/test_knowledge_fact_sheet.py
+src/tests/core/test_knowledge_hashing.py
+src/tests/core/test_knowledge_planner.py
+src/tests/core/test_knowledge_writer.py
+src/tests/core/test_section_snap.py
+src/tests/core/test_structure_skeleton.py
+src/tests/eval/test_s55_hard_forget.py
+src/tests/eval/test_s55_selfhost_restore.py
+src/tests/model/test_component_version.py
+src/tests/model/test_deployment.py
+src/tests/model/test_forget.py
+src/tests/packaging/test_client_wheel.py
+src/tests/packaging/test_release_contract.py
+src/tests/spine/test_catalog_lanes.py
+src/tests/spine/test_query_space_manifest.py
+src/tests/spine/test_rank_embed_cache.py
+src/tests/surfaces/test_assured_operation_authorities.py
+src/tests/surfaces/test_client_sdk.py
+src/tests/surfaces/test_cost_export_contract.py
+src/tests/surfaces/test_forget_admission.py
+src/tests/surfaces/test_login.py
+src/tests/surfaces/test_mcp_memory_tools.py
+src/tests/test_forget_port_contract.py
+src/tests/test_port_inventory_and_conformance.py
+src/tests/test_port_model_values.py
+src/tests/test_queue_port_contract.py
+src/tests/test_smoke.py
+src/tests/workers/test_chunk_level_extract.py
+src/tests/workers/test_claim_valid_time.py
+src/tests/workers/test_claimify_loss_ledger.py
+src/tests/workers/test_d79_structure_route.py
+src/tests/workers/test_d79_summaries.py
+src/tests/workers/test_d79_summary_consumption.py
+src/tests/workers/test_e3_claim_normalize_fanout.py
+src/tests/workers/test_e3_entity_obs_flush_fanout.py
+src/tests/workers/test_e3_unknown_entity_type_gate.py
+src/tests/workers/test_extraction_temperature.py
+src/tests/workers/test_hard_forget_handler.py
+src/tests/workers/test_hard_forget_service.py
+src/tests/workers/test_ingest_admission.py

rememberstack-0.4.2/.github/workflows/ci-nightly.yml

@@ -0,0 +1,107 @@
+name: Nightly CI
+
+# Full multi-Python suite + coverage. Not required for PR merge.
+# See design/operations/pr-ci-fast-gate.md
+
+on:
+  schedule:
+    # 05:17 UTC daily — offset from hour to avoid schedule storms
+    - cron: "17 5 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: nightly-ci
+  cancel-in-progress: false
+
+jobs:
+  compose-quickstart:
+    name: Compose quickstart
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    permissions:
+      contents: read
+    env:
+      QUICKSTART_TARGET_SECONDS: "600"
+      REMEMBERSTACK_BUILD_REVISION: ${{ github.sha }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate Compose model
+        run: docker compose --env-file .env.example config --quiet
+      - name: Start fresh self-host deployment
+        run: |
+          started_at="$(date +%s)"
+          docker compose --env-file .env.example up --build --detach --wait
+          curl --fail http://localhost:8000/operations
+          served_revision="$(curl --fail --silent http://localhost:8000/deployment \
+            | python3 -c 'import json,sys; print(json.load(sys.stdin)["build_revision"])')"
+          test "$served_revision" = "${REMEMBERSTACK_BUILD_REVISION}"
+          elapsed_seconds="$(($(date +%s) - started_at))"
+          echo "Quickstart cold start to first query: ${elapsed_seconds}s / ${QUICKSTART_TARGET_SECONDS}s target" \
+            | tee -a "$GITHUB_STEP_SUMMARY"
+          test "$elapsed_seconds" -le "$QUICKSTART_TARGET_SECONDS"
+      - name: Remove quickstart deployment
+        if: always()
+        run: docker compose --env-file .env.example down --volumes
+
+  checks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    permissions:
+      contents: read
+    env:
+      REMEMBERSTACK_DATABASE_URL: postgresql+psycopg://rememberstack:rememberstack_test@localhost:5432/rememberstack_test
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Start PostgreSQL 18 with required extensions
+        run: .github/ci/start-postgres.sh
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies (locked)
+        run: uv sync --locked --python ${{ matrix.python-version }}
+      - name: Architecture dependency check
+        run: uv run lint-imports
+      - name: Ruff lint
+        run: uv run ruff check src/ benchmarks/
+      - name: Ruff format check
+        run: uv run ruff format --check src/ benchmarks/
+      - name: Pyright type check
+        run: uv run pyright src/ benchmarks/ --pythonversion ${{ matrix.python-version }}
+      - name: Real PostgreSQL Alembic lifecycle
+        run: uv run pytest src/tests/spine/test_migrations.py -v --tb=short
+      - name: Full tests (with coverage)
+        run: uv run pytest src/tests -v --tb=short --cov --cov-report=term
+        env:
+          COVERAGE_FILE: .coverage.${{ matrix.python-version }}
+      - name: Upload coverage data
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-nightly-${{ matrix.python-version }}
+          path: .coverage.${{ matrix.python-version }}
+          include-hidden-files: true
+
+  coverage:
+    name: Coverage report
+    runs-on: ubuntu-latest
+    needs: checks
+    permissions:
+      pull-requests: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download coverage data
+        uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-nightly-*
+          merge-multiple: true
+      - name: Coverage comment + badge
+        uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ github.token }}
+          MERGE_COVERAGE_FILES: true

rememberstack-0.4.2/.github/workflows/ci.yml

@@ -0,0 +1,408 @@
+name: CI
+
+# PR-oriented fast gate (target wall time under ~10 minutes). Full multi-Python
+# coverage stays on the Nightly workflow. Design/rationale:
+# design/operations/pr-ci-fast-gate.md
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  UV_PYTHON: "3.13"
+
+jobs:
+  changes:
+    name: Path filters
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      workers: ${{ steps.filter.outputs.workers }}
+      surfaces: ${{ steps.filter.outputs.surfaces }}
+      adapters: ${{ steps.filter.outputs.adapters }}
+      compose: ${{ steps.filter.outputs.compose }}
+      shared_core: ${{ steps.filter.outputs.shared_core }}
+      ci_control: ${{ steps.filter.outputs.ci_control }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: .github/ci/path-filters.yml
+
+  quality:
+    name: Quality
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+      - name: Install dependencies (locked)
+        run: uv sync --locked --python 3.13
+      - name: Test inventory drift check
+        run: python3 .github/ci/check_test_inventory.py
+      - name: Architecture dependency check
+        run: uv run lint-imports
+      - name: Ruff lint
+        run: uv run ruff check src/ benchmarks/
+      - name: Ruff format check
+        run: uv run ruff format --check src/ benchmarks/
+      - name: Pyright type check
+        run: uv run pyright src/ benchmarks/ --pythonversion 3.13
+
+  unit:
+    name: Unit
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+      - name: Install dependencies (locked)
+        run: uv sync --locked --python 3.13
+      - name: Unit pack (no Postgres service)
+        run: |
+          mapfile -t paths < .github/ci/unit-paths.txt
+          if [ "${#paths[@]}" -eq 0 ]; then
+            echo "unit-paths.txt is empty" >&2
+            exit 1
+          fi
+          uv run pytest "${paths[@]}" -q --tb=short
+
+  contract-smoke:
+    name: Contract smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+    env:
+      REMEMBERSTACK_DATABASE_URL: postgresql+psycopg://rememberstack:rememberstack_test@localhost:5432/rememberstack_test
+    steps:
+      - uses: actions/checkout@v4
+      - name: Start PostgreSQL 18 with required extensions
+        run: .github/ci/start-postgres.sh
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+      - name: Install dependencies (locked)
+        run: uv sync --locked --python 3.13
+      - name: Contract smoke pack
+        run: |
+          mapfile -t paths < .github/ci/contract-smoke-paths.txt
+          uv run pytest "${paths[@]}" -v --tb=short
+
+  integration-workers:
+    name: Integration (workers)
+    needs: changes
+    if: >-
+      github.event_name == 'push'
+      || needs.changes.outputs.workers == 'true'
+      || needs.changes.outputs.shared_core == 'true'
+      || needs.changes.outputs.ci_control == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    permissions:
+      contents: read
+    env:
+      REMEMBERSTACK_DATABASE_URL: postgresql+psycopg://rememberstack:rememberstack_test@localhost:5432/rememberstack_test
+    steps:
+      - uses: actions/checkout@v4
+      - name: Start PostgreSQL 18 with required extensions
+        run: .github/ci/start-postgres.sh
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+      - name: Install dependencies (locked)
+        run: uv sync --locked --python 3.13
+      - name: Workers + spine integration
+        run: uv run pytest src/tests/workers src/tests/spine -q --tb=short
+
+  integration-surfaces:
+    name: Integration (surfaces)
+    needs: changes
+    if: >-
+      github.event_name == 'push'
+      || needs.changes.outputs.surfaces == 'true'
+      || needs.changes.outputs.shared_core == 'true'
+      || needs.changes.outputs.ci_control == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 50
+    permissions:
+      contents: read
+    env:
+      REMEMBERSTACK_DATABASE_URL: postgresql+psycopg://rememberstack:rememberstack_test@localhost:5432/rememberstack_test
+    steps:
+      - uses: actions/checkout@v4
+      - name: Start PostgreSQL 18 with required extensions
+        run: .github/ci/start-postgres.sh
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+      - name: Install dependencies (locked)
+        run: uv sync --locked --python 3.13
+      - name: Surfaces + eval integration
+        run: uv run pytest src/tests/surfaces src/tests/eval -q --tb=short
+
+  integration-adapters:
+    name: Integration (adapters)
+    needs: changes
+    if: >-
+      github.event_name == 'push'
+      || needs.changes.outputs.adapters == 'true'
+      || needs.changes.outputs.shared_core == 'true'
+      || needs.changes.outputs.ci_control == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    env:
+      REMEMBERSTACK_DATABASE_URL: postgresql+psycopg://rememberstack:rememberstack_test@localhost:5432/rememberstack_test
+    steps:
+      - uses: actions/checkout@v4
+      - name: Start PostgreSQL 18 with required extensions
+        run: .github/ci/start-postgres.sh
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+      - name: Install dependencies (locked)
+        run: uv sync --locked --python 3.13
+      - name: Adapters + profiles + spikes integration
+        run: |
+          uv run pytest src/tests/adapters src/tests/profiles src/tests/spikes -q --tb=short
+
+  compose-quickstart:
+    name: Compose quickstart
+    needs: changes
+    if: >-
+      github.event_name == 'push'
+      || needs.changes.outputs.compose == 'true'
+      || needs.changes.outputs.ci_control == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    permissions:
+      contents: read
+    env:
+      QUICKSTART_TARGET_SECONDS: "600"
+      REMEMBERSTACK_BUILD_REVISION: ${{ github.sha }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate Compose model
+        run: docker compose --env-file .env.example config --quiet
+
+      - name: Start fresh self-host deployment
+        run: |
+          started_at="$(date +%s)"
+          docker compose --env-file .env.example up --build --detach --wait
+          curl --fail http://localhost:8000/operations
+          served_revision="$(curl --fail --silent http://localhost:8000/deployment \
+            | python3 -c 'import json,sys; print(json.load(sys.stdin)["build_revision"])')"
+          test "$served_revision" = "${REMEMBERSTACK_BUILD_REVISION}"
+          query_result="$(curl --fail --silent \
+            --header 'Content-Type: application/json' \
+            --data '{"sql":"SELECT count(*) AS document_count FROM documents_live","parameters":[],"max_rows":1}' \
+            http://localhost:8000/query/sql)"
+          printf '%s' "$query_result" | python3 -c \
+            'import json,sys; result=json.load(sys.stdin); assert result["termination_reason"] == "completed", result'
+          elapsed_seconds="$(($(date +%s) - started_at))"
+          echo "Quickstart cold start to first query: ${elapsed_seconds}s / ${QUICKSTART_TARGET_SECONDS}s target" \
+            | tee -a "$GITHUB_STEP_SUMMARY"
+          test "$elapsed_seconds" -le "$QUICKSTART_TARGET_SECONDS"
+
+      - name: Prove MinIO conditional create
+        run: |
+          docker compose --env-file .env.example exec -T api python - <<'PY'
+          from rememberstack.adapters.selfhost import MinIOObjectStore, MinIOSettings
+          from rememberstack.model import ObjectAlreadyExistsError, ObjectKey
+
+          store = MinIOObjectStore(
+              bucket="remember-raw", settings=MinIOSettings.model_validate({})
+          )
+          key = ObjectKey("ci/immutable-object")
+          store.write_bytes(key=key, content=b"first")
+          try:
+              store.write_bytes(key=key, content=b"replacement")
+          except ObjectAlreadyExistsError:
+              pass
+          else:
+              raise RuntimeError("MinIO replaced an immutable object key")
+          PY
+
+      - name: Prove the zero-cost full pipeline
+        run: |
+          running_services="$(
+            docker compose --env-file .env.example ps --status running --services
+          )"
+          for service in \
+            api worker-convert worker-structure worker-chunk worker-embed-chunk \
+            worker-extract-claims worker-normalize-relations \
+            worker-adjudicate-observations worker-adjudicate-supersession \
+            worker-embed-claim worker-reconcile worker-label-relation; do
+            printf '%s\n' "$running_services" | grep -qx "$service"
+          done
+          ingested="$(
+            curl --fail --header 'Content-Type: application/octet-stream' \
+              --data-binary ' ' \
+              'http://localhost:8000/ingest?filename=empty.md&mime=text%2Fmarkdown'
+          )"
+          version_id="$(
+            printf '%s' "$ingested" |
+              docker compose --env-file .env.example exec -T api \
+                python -c 'import json, sys; print(json.load(sys.stdin)["version_id"])'
+          )"
+          # D84/D88/D90: extract is chunk-scoped; empty input skips claim
+          # normalize and takes durable empty_complete (no document_version
+          # adjudicate_observations row at the entity-fanout generation).
+          # Version-level ledger stages:
+          # convert→structure→chunk→embed_chunk→adjudicate_supersession→
+          # embed_claim→label→reconcile (8).
+          observed=''
+          for attempt in {1..60}; do
+            observed="$(docker compose --env-file .env.example exec -T postgres \
+              psql -U rememberstack -d rememberstack -Atc \
+              "SELECT count(*), count(*) FILTER (WHERE status='succeeded'), count(DISTINCT stage) FROM processing_state WHERE target_id='$version_id'")"
+            if [ "$observed" = '8|8|8' ]; then
+              break
+            fi
+            sleep 1
+          done
+          test "$observed" = '8|8|8'
+          test "$(docker compose --env-file .env.example exec -T postgres \
+            psql -U rememberstack -d rememberstack -Atc \
+            'SELECT count(*) FROM cost_ledger')" = '0'
+          docker compose --env-file .env.example --profile operations \
+            run --rm projections
+          readiness="$(
+            curl --fail --header 'Content-Type: application/json' \
+              --data "[\"$version_id\"]" \
+              'http://localhost:8000/readiness?require_projections=true'
+          )"
+          printf '%s' "$readiness" |
+            docker compose --env-file .env.example exec -T api python -c \
+              'import json, sys; report = json.load(sys.stdin); assert report["ready"]; assert all(item["ready"] for item in report["projections"])'
+
+      - name: Stage an upgrade from the prior schema
+        run: |
+          docker compose --env-file .env.example stop \
+            api worker-convert worker-structure worker-chunk worker-embed-chunk \
+            worker-extract-claims worker-normalize-relations \
+            worker-adjudicate-observations worker-adjudicate-supersession \
+            worker-embed-claim worker-reconcile worker-label-relation
+          docker compose --env-file .env.example run --rm --no-deps \
+            --entrypoint alembic setup downgrade p7_02_0016
+          test "$(docker compose --env-file .env.example exec -T postgres \
+            psql -U rememberstack -d rememberstack -Atc \
+            'SELECT version_num FROM alembic_version')" = 'p7_02_0016'
+          test "$(docker compose --env-file .env.example exec -T postgres \
+            psql -U rememberstack -d rememberstack -Atc \
+            'SELECT count(*) FROM deployments')" = '1'
+          docker compose --env-file .env.example rm --force setup
+
+      - name: Run migrations before application processes restart
+        run: |
+          compose_args=(
+            --env-file .env.example
+            --file compose.yaml
+            --file .github/compose/upgrade-gate.yaml
+          )
+          docker compose "${compose_args[@]}" up --detach --wait &
+          compose_pid="$!"
+          release_gate() {
+            docker compose "${compose_args[@]}" exec -T setup \
+              touch /tmp/rememberstack-upgrade-release
+          }
+          trap 'release_gate || true' EXIT
+
+          setup_running=''
+          for attempt in {1..30}; do
+            setup_running="$(
+              docker compose "${compose_args[@]}" ps --status running --services setup
+            )"
+            if [ "$setup_running" = 'setup' ]; then
+              break
+            fi
+            sleep 1
+          done
+          test "$setup_running" = 'setup'
+
+          running_services="$(
+            docker compose "${compose_args[@]}" ps --status running --services
+          )"
+          test -z "$(printf '%s\n' "$running_services" \
+            | grep -E '^(api|worker-(convert|structure|chunk|embed-chunk|extract-claims|normalize-relations|adjudicate-observations|adjudicate-supersession|embed-claim|reconcile|label-relation))$' || true)"
+          test "$(docker compose "${compose_args[@]}" exec -T postgres \
+            psql -U rememberstack -d rememberstack -Atc \
+            'SELECT version_num FROM alembic_version')" = 'p7_02_0016'
+
+          release_gate
+          wait "$compose_pid"
+          trap - EXIT
+          test "$(docker compose --env-file .env.example exec -T postgres \
+            psql -U rememberstack -d rememberstack -Atc \
+            'SELECT version_num FROM alembic_version')" = 'p9_13_0034'
+          test "$(docker compose --env-file .env.example exec -T postgres \
+            psql -U rememberstack -d rememberstack -Atc \
+            'SELECT count(*) FROM deployments')" = '1'
+          running_services="$(
+            docker compose "${compose_args[@]}" ps --status running --services
+          )"
+          for service in \
+            api worker-convert worker-structure worker-chunk worker-embed-chunk \
+            worker-extract-claims worker-normalize-relations \
+            worker-adjudicate-observations worker-adjudicate-supersession \
+            worker-embed-claim worker-reconcile worker-label-relation; do
+            printf '%s\n' "$running_services" | grep -qx "$service"
+          done
+          curl --fail http://localhost:8000/healthz
+
+      - name: Show service logs after failure
+        if: failure()
+        run: docker compose --env-file .env.example logs --no-color
+
+      - name: Remove quickstart deployment
+        if: always()
+        run: docker compose --env-file .env.example down --volumes
+
+  # Single always-present required check. Integration path jobs are soft.
+  pr-gate:
+    name: PR gate
+    runs-on: ubuntu-latest
+    needs: [changes, quality, unit, contract-smoke]
+    if: always()
+    steps:
+      - name: Require hard lanes (incl. path selector)
+        run: |
+          echo "changes=${{ needs.changes.result }}"
+          echo "quality=${{ needs.quality.result }}"
+          echo "unit=${{ needs.unit.result }}"
+          echo "contract-smoke=${{ needs.contract-smoke.result }}"
+          test "${{ needs.changes.result }}" = "success"
+          test "${{ needs.quality.result }}" = "success"
+          test "${{ needs.unit.result }}" = "success"
+          test "${{ needs.contract-smoke.result }}" = "success"