continuo-python-runtime 0.7.0__tar.gz → 0.8.0__tar.gz

continuo_python_runtime-0.8.0/.claude/agents/ddd-architecture-auditor.md

@@ -0,0 +1,117 @@
+---
+name: ddd-architecture-auditor
+description: >-
+  Use to audit code for DDD and Clean Architecture compliance in this repo's
+  engine adapters: layer dependency direction, domain purity, port placement,
+  thin use cases, SQL/identifier discipline, and repo conventions (changelog,
+  pins, test naming). Dispatch before merging a branch or whenever asked to
+  review architecture. Read-only: it writes a findings document the main agent
+  can act on; it never edits source.
+tools: Read, Grep, Glob, Bash, Write
+model: inherit
+---
+
+# Role
+
+You are a Domain-Driven Design and Clean Architecture auditor for the
+`continuo-python-runtime` repo. You inspect code, find architecture violations,
+and write a structured report so the main agent can fix them. You do not modify
+source code. Your only output artifact is the report.
+
+# Scope
+
+Default to the current branch's diff against `main`:
+
+```
+git diff main...HEAD --name-only
+git diff main...HEAD
+```
+
+Audit the whole tree only when the caller asks for a full sweep. State the
+scope you chose at the top of the report.
+
+# What to check
+
+Report a finding only when you can point at a real `file:line` you have opened
+and confirmed. Do not flag hypotheticals.
+
+## Layer 1: generic DDD / Clean Architecture
+
+- **Dependency direction.** The arrow runs infrastructure -> application ->
+  domain. Flag any inward-pointing import.
+- **Domain purity.** Domain code has no infrastructure concerns: no database,
+  object-store or dataframe clients, no serialization or framework types.
+- **Ports and adapters.** A port is declared by the layer that consumes it;
+  implementations live outside it. Flag an implementation that leaks
+  engine-specific types through the port.
+- **Thin use cases.** Use cases validate, then orchestrate through ports. Flag
+  business rules hiding in infrastructure, or SQL/engine detail in use cases.
+- **SOLID.** Flag a class with more than one reason to change, a use case that
+  switches on engine type instead of depending on an abstraction, and an
+  interface too wide for its consumers.
+
+## Layer 2: rules for `adapters/duckdb` (and any new adapter)
+
+1. **Layering by import.** `domain/` imports none of `duckdb`, `psycopg2`,
+   `pyarrow`, `boto3`, `application`, `infrastructure`. `application/` imports
+   neither `infrastructure` nor `duckdb`. `infrastructure/` imports only
+   `domain` and `application.ports`. Only the top-level `adapter.py`
+   (composition root) may import every layer. Verify with grep over each
+   layer's files.
+2. **Port placement.** The `LakeGateway` port and `LakeConflictError` live in
+   `application/ports.py`. `infrastructure` only implements them.
+3. **Validate before acting.** Every public use case validates its inputs
+   (types, layout, single-read gate) before the first gateway call.
+4. **SQL discipline.** Identifiers go through `quote_identifier`, strings
+   through `sql_literal`, in `infrastructure/ddl.py` only. Flag any SQL built
+   by string formatting elsewhere, and any author-supplied text that reaches
+   SQL unquoted.
+5. **Logging.** Standard `logging` only, never `print`; no SQL that can carry
+   a secret is logged (the ATTACH and secret statements).
+6. **Repo conventions (CLAUDE.md).** `CHANGELOG.md` has an `[Unreleased]`
+   entry for user-facing change; in-repo and third-party pins are exact; the
+   package is registered in the workspace, `scripts/check_version_bumps.py`,
+   `tests/test_image_requirements_sync.py` and the CI/image workflows; test
+   module basenames are unique across the repo.
+7. **Doc currency.** `docs/boundary-contract.md` documents every `config` key
+   the adapter accepts.
+
+# Report
+
+Write to `docs/ddd-violations/<YYYY-MM-DD-HHMM>-ddd-violations.md` (create the
+directory; timestamp from `date +%Y-%m-%d-%H%M`).
+
+```markdown
+# DDD / Clean Architecture Audit: <YYYY-MM-DD HH:MM>
+
+**Scope:** <branch diff vs main | full tree>
+**Branch / commit:** <branch> @ <short-sha>
+**Summary:** <N> blockers, <N> should-fix, <N> nits
+
+## Findings
+
+### [BLOCKER] <short title>
+- **Where:** `path/to/file.py:123`
+- **Rule:** <Layer 1 principle or Layer 2 rule number>
+- **Problem:** <what is wrong and why>
+- **Suggested fix:** <concrete change>
+
+### [SHOULD-FIX] ...
+### [NIT] ...
+
+## Clean
+- <checks that passed, so their absence above is explicit>
+```
+
+Severity: **BLOCKER** = breaks the dependency arrow, domain purity, or a
+CI-enforced rule; **SHOULD-FIX** = boundary erosion or convention drift that
+will bite later; **NIT** = stylistic.
+
+# Hard constraints
+
+- Never edit, create, or scaffold source code. The report is your only write.
+- Never claim a violation is fixed; you only diagnose.
+- Every finding cites a real `file:line` you have opened and confirmed.
+- If you find nothing, still write the report with an empty Findings section and
+  a populated Clean list.
+- End your reply with the report's path and the summary counts.

{continuo_python_runtime-0.7.0 → continuo_python_runtime-0.8.0}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -36,6 +36,7 @@ body:
         - contract (continuo-engine-contract)
         - adapters/postgres
         - adapters/trino
+        - adapters/duckdb
         - template
         - CI (.github/workflows)
         - Not sure

{continuo_python_runtime-0.7.0 → continuo_python_runtime-0.8.0}/.github/dependabot.yml

@@ -7,8 +7,8 @@
 version: 2
 
 updates:
-  # The uv workspace: this package (root), contract/, and the two adapters. All
-  # four share one lockfile, but Dependabot still needs one entry per pyproject.toml
+  # The uv workspace: this package (root), contract/, and the three adapters. All
+  # five share one lockfile, but Dependabot still needs one entry per pyproject.toml
   # directory to see each package's own dependency declarations.
   - package-ecosystem: uv
     directories:
@@ -16,6 +16,7 @@ updates:
       - /contract
       - /adapters/postgres
       - /adapters/trino
+      - /adapters/duckdb
     schedule:
       interval: weekly
     open-pull-requests-limit: 5
@@ -46,7 +47,7 @@ updates:
     commit-message:
       prefix: chore(ci)
 
-  # Dockerfile.postgres and Dockerfile.trino, the published engine images. Most
+  # Dockerfile.postgres, Dockerfile.trino and Dockerfile.duckdb, the published engine images. Most
   # base-image CVEs are fixed by moving to a newer tag.
   - package-ecosystem: docker
     directory: /

{continuo_python_runtime-0.7.0 → continuo_python_runtime-0.8.0}/.github/workflows/ci.yml

@@ -22,6 +22,8 @@ jobs:
         run: uv run --package continuo-postgres-adapter mypy adapters/postgres/continuo_postgres_adapter
       - name: Types (trino adapter)
         run: uv run --package continuo-trino-adapter mypy adapters/trino/continuo_trino_adapter
+      - name: Types (duckdb adapter)
+        run: uv run --package continuo-duckdb-adapter mypy adapters/duckdb/continuo_duckdb_adapter
       # `-m "not image"` deselects tests/test_image_smoke_validation.py, which
       # needs a built engine image and the env naming it. Those tests run in
       # images.yml's smoke jobs, where an image actually exists. `and not
@@ -29,14 +31,19 @@ jobs:
       # need a real minio backend (started via `docker run` by the
       # `minio_container` fixture, not docker-compose) -- those run in the
       # dedicated step below, on the same runner, where docker is available.
+      # That step selects BY MARKER, never by file name: an explicit file list
+      # would silently drop every new integration test added elsewhere in
+      # tests/ (tests/test_ci_test_coverage.py enforces this).
       - name: Tests (runtime)
         run: uv run pytest --cov=continuo_python_runtime -m "not image and not integration" -v
       - name: Tests (runtime, integration)
-        run: uv run pytest tests/test_csv_readers_integration.py tests/test_validation_runner.py -m integration -v
+        run: uv run pytest tests -m integration -v
       - name: Tests (contract)
         run: uv run pytest contract/tests -v
       - name: Tests (adapter units)
         run: uv run pytest adapters/postgres/tests adapters/trino/tests -m "not integration" -v
+      - name: Tests (duckdb adapter units)
+        run: uv run pytest adapters/duckdb/tests -m "not integration" -v
 
   integration-postgres:
     runs-on: ubuntu-latest
@@ -65,3 +72,17 @@ jobs:
       - name: Tear down trino stack
         if: always()
         run: docker compose -f tests/smoke/trino-stack/docker-compose.yml down -v
+
+  integration-duckdb:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --all-packages --all-groups
+      - name: Start duckdb stack
+        run: docker compose -f tests/smoke/duckdb-stack/docker-compose.yml up -d --wait
+      - name: Tests (duckdb integration)
+        run: uv run pytest adapters/duckdb/tests -m integration -v
+      - name: Tear down duckdb stack
+        if: always()
+        run: docker compose -f tests/smoke/duckdb-stack/docker-compose.yml down -v

continuo_python_runtime-0.8.0/.github/workflows/image-build.yml

@@ -0,0 +1,188 @@
+name: image-build
+
+# Reusable: build ONE engine image for ONE architecture on a native runner (no
+# QEMU), in one of two shapes:
+#
+#   push: false   `docker save` tarball uploaded as artifact
+#                 `<prefix>-<engine>-<arch>` (file image.tar). Nothing leaves
+#                 the run. PR smoke and dry runs.
+#   push: true    pushed to ghcr BY DIGEST ONLY: no tag of any kind, so the
+#                 candidate cannot be mistaken for a release. The digest is
+#                 uploaded as artifact `<prefix>-<engine>-<arch>` (file
+#                 `digest`, content `sha256:...`) for the verify and promote
+#                 jobs. Candidates that never get promoted are garbage.
+#
+# wheel_source feeds the Dockerfile's WHEEL_SOURCE:
+#   wheelhouse  the `dist` artifact's wheels (PR, dry run, pre-upload gate)
+#   pypi        the pins from real PyPI (a real release)
+#   testpypi    the pins from TestPyPI, first-party only (a -test rehearsal)
+#
+# version_suffix re-applies the rehearsal version rewrite to this job's own
+# checkout so image-requirements-<engine>.txt names the versions in `dist`
+# (see scripts/apply_rehearsal_version.py). Empty for a real release.
+on:
+  workflow_call:
+    inputs:
+      engine:
+        type: string
+        required: true
+      arch:
+        description: amd64 | arm64
+        type: string
+        required: true
+      wheel_source:
+        description: wheelhouse | pypi | testpypi
+        type: string
+        required: true
+      push:
+        type: boolean
+        default: false
+      version_suffix:
+        type: string
+        default: ""
+      artifact_prefix:
+        description: artifact name prefix, e.g. pr, preflight, candidate
+        type: string
+        required: true
+      dist_artifact:
+        type: string
+        default: dist
+    outputs:
+      artifact:
+        description: name of the artifact holding image.tar or digest
+        value: ${{ jobs.build.outputs.artifact }}
+
+# No `permissions:` here on purpose: a called workflow can only NARROW the
+# caller's token, so the caller grants `contents: read` (+ `packages: write`
+# when push is true).
+
+jobs:
+  build:
+    name: image ${{ inputs.engine }} ${{ inputs.arch }}
+    runs-on: ${{ inputs.arch == 'arm64' && 'ubuntu-24.04-arm' || 'ubuntu-latest' }}
+    outputs:
+      artifact: ${{ inputs.artifact_prefix }}-${{ inputs.engine }}-${{ inputs.arch }}
+    env:
+      ARTIFACT: ${{ inputs.artifact_prefix }}-${{ inputs.engine }}-${{ inputs.arch }}
+      IMAGE_NAME: ghcr.io/${{ github.repository_owner }}/continuo-python-runtime-${{ inputs.engine }}
+      REQ: image-requirements-${{ inputs.engine }}.txt
+    steps:
+      - uses: actions/checkout@v7
+      - name: Assert the runner architecture
+        run: |
+          want="${{ inputs.arch == 'arm64' && 'aarch64' || 'x86_64' }}"
+          test "$(uname -m)" = "$want" || { echo "::error::runner is $(uname -m), expected $want"; exit 1; }
+      - name: Apply the rehearsal version
+        if: inputs.version_suffix != ''
+        run: python3 scripts/apply_rehearsal_version.py --suffix "${{ inputs.version_suffix }}"
+      - name: Fetch the built wheels into the wheelhouse
+        if: inputs.wheel_source == 'wheelhouse'
+        uses: actions/download-artifact@v8
+        with:
+          name: ${{ inputs.dist_artifact }}
+          path: wheelhouse
+      - uses: actions/setup-python@v7
+        if: inputs.wheel_source != 'wheelhouse'
+        with:
+          # The pinned distributions declare Requires-Python >= 3.14, so the
+          # host-side probe below must run under 3.14 or pip rejects them even
+          # once published. (The image build itself runs inside python:3.14-slim.)
+          python-version: "3.14"
+      # Ordering between the upload and this build is a `needs:` edge in
+      # publish-pypi.yml, but an index can lag its own upload, so poll. The
+      # probe runs with --no-cache-dir: the simple index is served with
+      # `Cache-Control: max-age=600`, which pip's HTTP cache honours, so one
+      # early stale fetch would otherwise be replayed for 10 minutes, exactly
+      # this loop's whole budget (seen in the first TestPyPI rehearsal).
+      - name: Wait until the pinned versions are installable
+        if: inputs.wheel_source != 'wheelhouse'
+        run: |
+          set -eu
+          if [ "${{ inputs.wheel_source }}" = "testpypi" ]; then
+            # First-party only, from TestPyPI: it hosts junk copies of real names.
+            pull() { python -m pip download --no-cache-dir --no-deps --only-binary=:all: --index-url https://test.pypi.org/simple/ \
+                       --dest /tmp/probe -r "$REQ"; }
+          else
+            pull() { python -m pip download --no-cache-dir --dest /tmp/probe -r "$REQ"; }
+          fi
+          for i in $(seq 1 30); do
+            if pull >/tmp/probe.log 2>&1; then
+              echo "installable"; exit 0
+            fi
+            echo "attempt $i: not yet on the index; sleeping"; sleep 20
+          done
+          echo "pinned versions never became installable"; cat /tmp/probe.log; exit 1
+      # TestPyPI versions are unique per run, so the files served must be the
+      # files this run built. Compare them byte for byte.
+      - name: Fetch dist to compare with the index
+        if: inputs.wheel_source == 'testpypi'
+        uses: actions/download-artifact@v8
+        with:
+          name: ${{ inputs.dist_artifact }}
+          path: dist
+      - name: Index bytes equal the bytes built in this run
+        if: inputs.wheel_source == 'testpypi'
+        run: |
+          set -eu
+          n=0
+          for f in /tmp/probe/*.whl; do
+            b="$(basename "$f")"
+            test -f "dist/$b" || { echo "::error::$b is on the index but was not built in this run"; exit 1; }
+            cmp "$f" "dist/$b" || { echo "::error::$b on the index differs from this run's build"; exit 1; }
+            n=$((n + 1))
+          done
+          test "$n" -eq 3 || { echo "::error::expected 3 first-party wheels, compared $n"; exit 1; }
+          echo "compared $n wheels: identical"
+      - uses: docker/setup-buildx-action@v4
+      - name: Log in to ghcr.io
+        if: inputs.push
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build the image (tarball)
+        if: "!inputs.push"
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: Dockerfile.${{ inputs.engine }}
+          platforms: linux/${{ inputs.arch }}
+          build-args: WHEEL_SOURCE=${{ inputs.wheel_source }}
+          load: true
+          tags: cpr-smoke-${{ inputs.engine }}
+      - name: Save the image
+        if: "!inputs.push"
+        run: |
+          mkdir -p out
+          docker save cpr-smoke-${{ inputs.engine }} -o out/image.tar
+      # provenance/sbom off: with them on, a pushed digest is an index that
+      # also holds an attestation manifest, and merging two of those into one
+      # multi-arch tag nests indexes. Off, the digest IS the single-platform
+      # image manifest, which is exactly what the verify job pulls.
+      - name: Build and push by digest
+        id: push
+        if: inputs.push
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: Dockerfile.${{ inputs.engine }}
+          platforms: linux/${{ inputs.arch }}
+          build-args: WHEEL_SOURCE=${{ inputs.wheel_source }}
+          provenance: false
+          sbom: false
+          outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
+      - name: Record the digest
+        if: inputs.push
+        run: |
+          mkdir -p out
+          digest="${{ steps.push.outputs.digest }}"
+          case "$digest" in sha256:*) ;; *) echo "::error::no digest from the push"; exit 1;; esac
+          printf '%s' "$digest" > out/digest
+          echo "pushed ${IMAGE_NAME}@${digest} (candidate, untagged)" >> "$GITHUB_STEP_SUMMARY"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: ${{ env.ARTIFACT }}
+          path: out/
+          retention-days: 3
+          overwrite: true

continuo_python_runtime-0.8.0/.github/workflows/image-smoke.yml

@@ -0,0 +1,255 @@
+name: image-smoke
+
+# Reusable: run the engine image smoke checks against ONE image on a native
+# runner of the matching architecture. This is the single definition of "the
+# image works", used by images.yml (PR, tarball built from the commit) and by
+# publish-pypi.yml (pre-upload gate, and the verification of the candidate
+# digests actually pushed to ghcr), so the PR path and the release path cannot
+# drift. Per engine it runs:
+#
+#   1. tests/test_image_smoke_validation.py -m image  (3 tests)
+#   2. the smoke node tests/smoke/node_smoke against a REAL warehouse stack
+#      (tests/smoke/<engine>-stack), asserting the success sentinel and 3 rows
+#   3. duckdb only: the baked extensions load offline as uid 65532
+#
+# mode=tar     the image is `image.tar` in artifact `image_artifact`
+# mode=digest  the image is `<registry_image>@<digest>`, the digest being the
+#              content of file `digest` in artifact `image_artifact`; it is
+#              pulled from ghcr, so what is tested is what was pushed.
+#
+# A cell that cannot run must fail loudly: the image's architecture is asserted
+# against the runner's before anything else is tested.
+#
+# No `permissions:` here on purpose (see image-build.yml): the caller grants
+# `contents: read`, plus `packages: read` for mode=digest.
+on:
+  workflow_call:
+    inputs:
+      engine:
+        description: postgres | trino | duckdb
+        type: string
+        required: true
+      arch:
+        description: amd64 | arm64
+        type: string
+        required: true
+      mode:
+        description: tar | digest
+        type: string
+        required: true
+      image_artifact:
+        type: string
+        required: true
+      registry_image:
+        description: ghcr.io/<owner>/continuo-python-runtime-<engine> (mode=digest)
+        type: string
+        default: ""
+
+jobs:
+  smoke:
+    name: smoke ${{ inputs.engine }} ${{ inputs.arch }}
+    runs-on: ${{ inputs.arch == 'arm64' && 'ubuntu-24.04-arm' || 'ubuntu-latest' }}
+    env:
+      DUCKDB_CATALOG_HOST: localhost
+      DUCKDB_CATALOG_PORT: "15599"
+      DUCKDB_CATALOG_DB: catalog
+      DUCKDB_CATALOG_USER: continuo
+      DUCKDB_CATALOG_PASSWORD: continuo
+      DUCKDB_DATA_PATH: s3://warehouse/lake/
+      DUCKDB_S3_ENDPOINT: localhost:19100
+      DUCKDB_S3_ACCESS_KEY_ID: minioadmin
+      DUCKDB_S3_SECRET_ACCESS_KEY: minioadmin
+      DUCKDB_S3_URL_STYLE: path
+      DUCKDB_S3_USE_SSL: "false"
+    steps:
+      - uses: actions/checkout@v7
+      - name: Assert the runner architecture
+        run: |
+          want="${{ inputs.arch == 'arm64' && 'aarch64' || 'x86_64' }}"
+          test "$(uname -m)" = "$want" || { echo "::error::runner is $(uname -m), expected $want"; exit 1; }
+      - uses: actions/download-artifact@v8
+        with:
+          name: ${{ inputs.image_artifact }}
+          path: ${{ runner.temp }}/img
+      - name: Log in to ghcr.io
+        if: inputs.mode == 'digest'
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Load or pull the image under test
+        run: |
+          set -eu
+          case "${{ inputs.mode }}" in
+            tar)
+              docker load -i "$RUNNER_TEMP/img/image.tar"
+              image="cpr-smoke-${{ inputs.engine }}"
+              ;;
+            digest)
+              digest="$(cat "$RUNNER_TEMP/img/digest")"
+              case "$digest" in sha256:*) ;; *) echo "::error::bad digest file"; exit 1;; esac
+              image="${{ inputs.registry_image }}@${digest}"
+              docker pull "$image"
+              ;;
+            *) echo "::error::mode must be tar or digest"; exit 1;;
+          esac
+          echo "IMAGE=$image" >> "$GITHUB_ENV"
+          echo "testing $image" >> "$GITHUB_STEP_SUMMARY"
+      - name: Assert the image architecture
+        run: |
+          got="$(docker image inspect "$IMAGE" --format '{{.Os}}/{{.Architecture}}')"
+          test "$got" = "linux/${{ inputs.arch }}" || { echo "::error::image is $got, expected linux/${{ inputs.arch }}"; exit 1; }
+      - uses: astral-sh/setup-uv@v7
+      - name: Sync
+        run: uv sync --all-packages --all-groups
+
+      # ---- postgres -------------------------------------------------------
+      - name: Image smoke tests (postgres)
+        if: inputs.engine == 'postgres'
+        env:
+          VALIDATION_IMAGE_UNDER_TEST: ${{ env.IMAGE }}
+          VALIDATION_IMAGE_ENGINE: postgres
+          # PostgresAdapter.required_env()[0]
+          VALIDATION_IMAGE_REQUIRED_ENV: POSTGRES_HOST
+        run: uv run pytest tests/test_image_smoke_validation.py -m image -v
+      - name: Start postgres stack
+        if: inputs.engine == 'postgres'
+        run: docker compose -f tests/smoke/postgres-stack/docker-compose.yml up -d --wait
+      - name: Seed source table (postgres)
+        if: inputs.engine == 'postgres'
+        run: |
+          docker compose -f tests/smoke/postgres-stack/docker-compose.yml exec -T postgres \
+            psql -U continuo -d warehouse -c \
+            "CREATE SCHEMA analytics; CREATE TABLE analytics.src(id int); INSERT INTO analytics.src VALUES (1),(2),(3);"
+      - name: Run smoke node (postgres)
+        if: inputs.engine == 'postgres'
+        run: |
+          docker run --rm --network host \
+            -v "$PWD/tests/smoke/node_smoke:/app" \
+            -e NODE_ID=python-node.smoke.analytics.smoke \
+            -e TABLE_NAME=smoke \
+            -e TARGET_SCHEMA=analytics \
+            -e POSTGRES_HOST=localhost \
+            -e POSTGRES_PORT=15499 \
+            -e POSTGRES_DB=warehouse \
+            -e POSTGRES_USER=continuo \
+            -e POSTGRES_PASSWORD=continuo \
+            "$IMAGE" | tee "$RUNNER_TEMP/smoke.out"
+          test "${PIPESTATUS[0]}" -eq 0
+        shell: bash
+      - name: Assert success sentinel and row count (postgres)
+        if: inputs.engine == 'postgres'
+        run: |
+          grep -q '"status":"success"' "$RUNNER_TEMP/smoke.out"
+          count=$(docker compose -f tests/smoke/postgres-stack/docker-compose.yml exec -T postgres \
+            psql -U continuo -d warehouse -t -c "select count(*) from analytics.smoke" | tr -d '[:space:]')
+          test "$count" = "3"
+      - name: Tear down postgres stack
+        if: inputs.engine == 'postgres' && always()
+        run: docker compose -f tests/smoke/postgres-stack/docker-compose.yml down -v
+
+      # ---- trino ----------------------------------------------------------
+      - name: Image smoke tests (trino)
+        if: inputs.engine == 'trino'
+        env:
+          VALIDATION_IMAGE_UNDER_TEST: ${{ env.IMAGE }}
+          VALIDATION_IMAGE_ENGINE: trino
+          # TrinoAdapter.required_env()[0]
+          VALIDATION_IMAGE_REQUIRED_ENV: TRINO_HOST
+        run: uv run pytest tests/test_image_smoke_validation.py -m image -v
+      - name: Start trino stack
+        if: inputs.engine == 'trino'
+        run: docker compose -f tests/smoke/trino-stack/docker-compose.yml up -d --wait
+      - name: Seed source table (trino)
+        if: inputs.engine == 'trino'
+        run: |
+          docker exec "$(docker compose -f tests/smoke/trino-stack/docker-compose.yml ps -q trino)" \
+            trino --execute "CREATE SCHEMA IF NOT EXISTS iceberg.analytics; CREATE TABLE iceberg.analytics.src(id int); INSERT INTO iceberg.analytics.src VALUES 1,2,3"
+      - name: Run smoke node (trino)
+        if: inputs.engine == 'trino'
+        run: |
+          docker run --rm \
+            -v "$PWD/tests/smoke/node_smoke:/app" \
+            -e NODE_ID=python-node.smoke.analytics.smoke \
+            -e TABLE_NAME=smoke \
+            -e TARGET_SCHEMA=analytics \
+            -e TRINO_HOST=host.docker.internal \
+            -e TRINO_PORT=18080 \
+            -e TRINO_CATALOG=iceberg \
+            -e TRINO_USER=continuo \
+            --add-host=host.docker.internal:host-gateway \
+            "$IMAGE" | tee "$RUNNER_TEMP/smoke.out"
+          test "${PIPESTATUS[0]}" -eq 0
+        shell: bash
+      - name: Assert success sentinel and row count (trino)
+        if: inputs.engine == 'trino'
+        run: |
+          grep -q '"status":"success"' "$RUNNER_TEMP/smoke.out"
+          count=$(docker exec "$(docker compose -f tests/smoke/trino-stack/docker-compose.yml ps -q trino)" \
+            trino --execute "select count(*) from iceberg.analytics.smoke" | tr -d '[:space:]"')
+          test "$count" = "3"
+      - name: Tear down trino stack
+        if: inputs.engine == 'trino' && always()
+        run: docker compose -f tests/smoke/trino-stack/docker-compose.yml down -v
+
+      # ---- duckdb ---------------------------------------------------------
+      - name: Image smoke tests (duckdb)
+        if: inputs.engine == 'duckdb'
+        env:
+          VALIDATION_IMAGE_UNDER_TEST: ${{ env.IMAGE }}
+          VALIDATION_IMAGE_ENGINE: duckdb
+          # DuckDBAdapter.required_env()[0]
+          VALIDATION_IMAGE_REQUIRED_ENV: DUCKDB_CATALOG_HOST
+        run: uv run pytest tests/test_image_smoke_validation.py -m image -v
+      # The extensions are native binaries per architecture, baked at build
+      # time. No network, the non-root user: exactly how the executor runs it.
+      - name: Extensions load offline as the non-root user (duckdb)
+        if: inputs.engine == 'duckdb'
+        run: |
+          docker run --rm --network none --user 65532:65532 --entrypoint python "$IMAGE" -c \
+            "import os; from continuo_duckdb_adapter.infrastructure.extensions import check_offline; check_offline(os.environ['DUCKDB_EXTENSION_DIRECTORY'])"
+      - name: Start duckdb stack
+        if: inputs.engine == 'duckdb'
+        run: docker compose -f tests/smoke/duckdb-stack/docker-compose.yml up -d --wait
+      - name: Seed source table (duckdb)
+        if: inputs.engine == 'duckdb'
+        run: |
+          uv run python - <<'PY'
+          import pyarrow as pa
+          from continuo_duckdb_adapter.adapter import DuckDBAdapter
+
+          a = DuckDBAdapter.from_env()
+          a.ensure_table("analytics", "src", [{"name": "id", "type": "INTEGER", "nullable": True}], config={})
+          a.load("analytics", "src", pa.table({"id": pa.array([1, 2, 3], pa.int32())}))
+          a.close()
+          PY
+      - name: Run smoke node (duckdb)
+        if: inputs.engine == 'duckdb'
+        run: |
+          docker run --rm --network host \
+            -v "$PWD/tests/smoke/node_smoke:/app" \
+            -e NODE_ID=python-node.smoke.analytics.smoke \
+            -e TABLE_NAME=smoke \
+            -e TARGET_SCHEMA=analytics \
+            -e DUCKDB_CATALOG_HOST -e DUCKDB_CATALOG_PORT -e DUCKDB_CATALOG_DB \
+            -e DUCKDB_CATALOG_USER -e DUCKDB_CATALOG_PASSWORD -e DUCKDB_DATA_PATH \
+            -e DUCKDB_S3_ENDPOINT -e DUCKDB_S3_ACCESS_KEY_ID -e DUCKDB_S3_SECRET_ACCESS_KEY \
+            -e DUCKDB_S3_URL_STYLE -e DUCKDB_S3_USE_SSL \
+            "$IMAGE" | tee "$RUNNER_TEMP/smoke.out"
+          test "${PIPESTATUS[0]}" -eq 0
+        shell: bash
+      - name: Assert success sentinel and row count (duckdb)
+        if: inputs.engine == 'duckdb'
+        run: |
+          grep -q '"status":"success"' "$RUNNER_TEMP/smoke.out"
+          uv run python - <<'PY'
+          from continuo_duckdb_adapter.adapter import DuckDBAdapter
+
+          a = DuckDBAdapter.from_env()
+          assert a.fetch("SELECT count(*) AS n FROM analytics.smoke").to_pylist() == [{"n": 3}]
+          a.close()
+          PY
+      - name: Tear down duckdb stack
+        if: inputs.engine == 'duckdb' && always()
+        run: docker compose -f tests/smoke/duckdb-stack/docker-compose.yml down -v