continuo-python-runtime 0.1.0__tar.gz → 0.3.0__tar.gz

{continuo_python_runtime-0.1.0 → continuo_python_runtime-0.3.0}/.dockerignore

@@ -11,4 +11,5 @@ dist/
 docs/
 template/
 tests/
-python-runtime-*/tests/
+adapters/*/tests/
+contract/tests/

continuo_python_runtime-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: ci
+on:
+  push: { branches: [main] }
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Sync
+        run: uv sync --all-packages --all-groups
+      - name: Lint
+        run: uv run ruff check .
+      - name: Lint (contract)
+        run: uv run ruff check contract
+      - name: Types (runtime)
+        run: uv run mypy continuo_python_runtime
+      - name: Types (contract)
+        run: uv run mypy contract/continuo_engine_contract
+      - name: Types (postgres adapter)
+        run: uv run --package continuo-python-runtime-postgres mypy adapters/postgres/continuo_python_runtime_postgres
+      - name: Types (trino adapter)
+        run: uv run --package continuo-python-runtime-trino mypy adapters/trino/continuo_python_runtime_trino
+      # `-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.
+      - name: Tests (runtime)
+        run: uv run pytest --cov=continuo_python_runtime -m "not image" -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
+
+  integration-postgres:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --all-packages --all-groups
+      - name: Start postgres stack
+        run: docker compose -f tests/smoke/postgres-stack/docker-compose.yml up -d --wait
+      - name: Tests (postgres integration)
+        run: uv run pytest adapters/postgres/tests -m integration -v
+      - name: Tear down postgres stack
+        if: always()
+        run: docker compose -f tests/smoke/postgres-stack/docker-compose.yml down -v
+
+  integration-trino:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --all-packages --all-groups
+      - name: Start trino stack
+        run: docker compose -f tests/smoke/trino-stack/docker-compose.yml up -d --wait
+      - name: Tests (trino integration)
+        run: uv run pytest adapters/trino/tests -m integration -v
+      - name: Tear down trino stack
+        if: always()
+        run: docker compose -f tests/smoke/trino-stack/docker-compose.yml down -v

{continuo_python_runtime-0.1.0 → continuo_python_runtime-0.3.0}/.github/workflows/images.yml

@@ -5,8 +5,8 @@ on:
       - "Dockerfile.*"
       - "tests/smoke/**"
       - "continuo_python_runtime/**"
-      - "python-runtime-postgres/**"
-      - "python-runtime-trino/**"
+      - "contract/**"
+      - "adapters/**"
       - "pyproject.toml"
       - ".github/workflows/images.yml"
   push:
@@ -56,6 +56,16 @@ jobs:
           path: /tmp
       - name: Load image
         run: docker load -i /tmp/cpr-smoke-postgres.tar
+      - uses: astral-sh/setup-uv@v5
+      - name: Sync
+        run: uv sync --all-packages --all-groups
+      - name: Image smoke tests (postgres)
+        env:
+          VALIDATION_IMAGE_UNDER_TEST: cpr-smoke-postgres
+          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: Install psql client
         run: |
           sudo apt-get update
@@ -101,6 +111,16 @@ jobs:
           path: /tmp
       - name: Load image
         run: docker load -i /tmp/cpr-smoke-trino.tar
+      - uses: astral-sh/setup-uv@v5
+      - name: Sync
+        run: uv sync --all-packages --all-groups
+      - name: Image smoke tests (trino)
+        env:
+          VALIDATION_IMAGE_UNDER_TEST: cpr-smoke-trino
+          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
         run: docker compose -f tests/smoke/trino-stack/docker-compose.yml up -d --wait
       - name: Seed source table
@@ -133,13 +153,20 @@ jobs:
         if: always()
         run: docker compose -f tests/smoke/trino-stack/docker-compose.yml down -v
 
-  # On tag push: log in to ghcr.io and push ghcr.io/${{ github.repository }}:<tag>-postgres
-  # and :<tag>-trino. continuo-validation-contract, continuo-python-runtime-postgres,
-  # and continuo-python-runtime-trino are all installed from the build context /
-  # PyPI already (see Dockerfile.postgres / Dockerfile.trino and
-  # publish-pypi.yml) — nothing pending here.
+  # On tag push: build both engine images for linux/amd64 and linux/arm64 and
+  # push them to ghcr.io/<owner>/continuo-python-runtime-<engine>:<tag>. The
+  # engine belongs in the image NAME, not the tag: Continuo's Helm chart pins an
+  # image as `<name>:vX.Y.Z@sha256:<digest>`, so the tag must be the bare
+  # version. Both platforms are required: domain repos build their own images
+  # FROM these, and Continuo's e2e runs them in a kind cluster on aarch64
+  # developer machines as well as on amd64 CI runners, so a single-arch publish
+  # is unusable off amd64. The smoke jobs above stay single-arch — they load a
+  # `docker save` tarball, which has no multi-platform equivalent.
+  # continuo-engine-contract and the two engine adapters are installed from the
+  # build context (see Dockerfile.postgres / Dockerfile.trino) — nothing pending
+  # here.
   publish:
-    if: startsWith(github.ref, 'refs/tags/v')
+    if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-test')
     needs: [smoke-postgres, smoke-trino]
     strategy:
       matrix:
@@ -150,6 +177,8 @@ jobs:
       packages: write
     steps:
       - uses: actions/checkout@v4
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
       - name: Log in to ghcr.io
         uses: docker/login-action@v3
         with:
@@ -157,8 +186,10 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
       - name: Build and push ${{ matrix.engine }} image
-        run: |
-          tag="${GITHUB_REF_NAME}"
-          image="ghcr.io/${{ github.repository }}:${tag}-${{ matrix.engine }}"
-          docker build -f Dockerfile.${{ matrix.engine }} -t "$image" .
-          docker push "$image"
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: Dockerfile.${{ matrix.engine }}
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ghcr.io/${{ github.repository_owner }}/continuo-python-runtime-${{ matrix.engine }}:${{ github.ref_name }}

continuo_python_runtime-0.3.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,74 @@
+name: publish-pypi
+
+# Publishes both PyPI distributions this repo owns — continuo-python-runtime
+# (the harness) and continuo-engine-contract (the port, result-block format,
+# and shared guards) — via PyPI Trusted Publishing (OIDC, no stored token).
+#
+# The two engine adapters (continuo-python-runtime-postgres /
+# continuo-python-runtime-trino) are deliberately NOT published here. Nothing
+# installs them from an index: the engine images build them from the build
+# context (see Dockerfile.postgres / Dockerfile.trino and images.yml), and the
+# harness package does not depend on them — adapters are found at run time
+# through the `continuo_engine.adapters` entry-point group, inside the image
+# that installed exactly one. Publishing them would only add releases with no
+# consumer. They remain uv workspace members and are still built, typed, and
+# tested by ci.yml.
+#
+# Tag glob note: `v*` is the repository's single release pattern — the same tag
+# that images.yml builds and pushes both engine images from, so one tag ships
+# the whole release. GitHub Actions tag globs anchor at character 1, so `v*`
+# claims every tag beginning with "v"; no other pattern may be introduced.
+# Tag `v<ver>-test<n>` publishes to TestPyPI; `v<ver>` publishes to real PyPI.
+# The GitHub environment name is what the PyPI "pending publisher" is
+# registered against — both project names need one on each index.
+#
+# Both distributions are built into a single `dist/` and uploaded in one
+# publish call, so there is no ordering constraint between them. The runtime
+# wheel declares continuo-engine-contract as a dependency and resolves it from
+# the index at install time ([tool.uv.sources] is dev-only and is not embedded
+# in the wheel).
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions: {}
+
+jobs:
+  publish-packages:
+    if: startsWith(github.ref_name, 'v')
+    runs-on: ubuntu-latest
+    environment: ${{ contains(github.ref_name, '-test') && 'testpypi' || 'pypi' }}
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing
+      contents: read # actions/checkout needs read access to the repo
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Test before publishing
+        # `-m "not image"` deselects the image smoke tests; images.yml runs
+        # those against a built engine image.
+        run: |
+          uv sync --all-packages --all-groups
+          uv run pytest tests contract/tests -m "not image" -q
+      - name: Build the contract sdist + wheel
+        run: uv build --package continuo-engine-contract -o dist
+      - name: Build the runtime sdist + wheel
+        run: uv build -o dist
+      - name: Publish to TestPyPI
+        if: contains(github.ref_name, '-test')
+        # Pinned to a commit SHA. release/v1 is a moving branch, and this job
+        # holds id-token: write for PyPI Trusted Publishing — a compromised
+        # revision could mint a token and publish under this project's name.
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist
+      - name: Publish to PyPI
+        if: ${{ !contains(github.ref_name, '-test') }}
+        # Pinned to a commit SHA. release/v1 is a moving branch, and this job
+        # holds id-token: write for PyPI Trusted Publishing — a compromised
+        # revision could mint a token and publish under this project's name.
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: dist

{continuo_python_runtime-0.1.0 → continuo_python_runtime-0.3.0}/.gitignore

@@ -7,3 +7,5 @@ dist/
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/
+.coverage
+.worktrees/

continuo_python_runtime-0.3.0/Dockerfile.postgres

@@ -0,0 +1,22 @@
+FROM python:3.14-slim
+# One dual-role image per engine: the python-node runtime harness (default
+# command `run`, domain repos build FROM this) and the blue/green validation
+# runner (`validation-op`, continuo's executor sets it as the container
+# command). Everything installs from this repo's own workspace paths in one
+# pip transaction — no PyPI propagation lag; images always build from repo head.
+#   docker build -f Dockerfile.postgres .
+COPY pyproject.toml README.md /src/
+COPY contract /src/contract
+COPY continuo_python_runtime /src/continuo_python_runtime
+COPY adapters/postgres /src/adapters/postgres
+RUN pip install --no-cache-dir /src/contract /src/adapters/postgres /src \
+    && rm -rf /src
+# PYTHONPATH is belt-and-braces: the harness also inserts APP_ROOT and the
+# node script's own directory at the front of sys.path before executing it.
+ENV CONTRACT_DIR=/app/contracts APP_ROOT=/app PYTHONPATH=/app
+WORKDIR /app
+# uid 65532 matches continuo's executor securityContext expectation.
+RUN useradd --uid 65532 --no-create-home --shell /usr/sbin/nologin nonroot
+USER 65532:65532
+ENTRYPOINT ["continuo-runtime"]
+CMD ["run"]

continuo_python_runtime-0.3.0/Dockerfile.trino

@@ -0,0 +1,22 @@
+FROM python:3.14-slim
+# One dual-role image per engine: the python-node runtime harness (default
+# command `run`, domain repos build FROM this) and the blue/green validation
+# runner (`validation-op`, continuo's executor sets it as the container
+# command). Everything installs from this repo's own workspace paths in one
+# pip transaction — no PyPI propagation lag; images always build from repo head.
+#   docker build -f Dockerfile.trino .
+COPY pyproject.toml README.md /src/
+COPY contract /src/contract
+COPY continuo_python_runtime /src/continuo_python_runtime
+COPY adapters/trino /src/adapters/trino
+RUN pip install --no-cache-dir /src/contract /src/adapters/trino /src \
+    && rm -rf /src
+# PYTHONPATH is belt-and-braces: the harness also inserts APP_ROOT and the
+# node script's own directory at the front of sys.path before executing it.
+ENV CONTRACT_DIR=/app/contracts APP_ROOT=/app PYTHONPATH=/app
+WORKDIR /app
+# uid 65532 matches continuo's executor securityContext expectation.
+RUN useradd --uid 65532 --no-create-home --shell /usr/sbin/nologin nonroot
+USER 65532:65532
+ENTRYPOINT ["continuo-runtime"]
+CMD ["run"]

{continuo_python_runtime-0.1.0 → continuo_python_runtime-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: continuo-python-runtime
-Version: 0.1.0
+Version: 0.3.0
 Summary: Runtime harness, contract tooling, and CI lint for Continuo python nodes.
 Author: Simone Carolini
 Maintainer: Simone Carolini
@@ -8,9 +8,11 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.14
-Requires-Dist: continuo-validation-contract==0.3.0
+Requires-Dist: boto3==1.43.59
+Requires-Dist: continuo-engine-contract==0.7.0
 Requires-Dist: pyarrow==25.0.0
 Requires-Dist: pyyaml==6.0.3
+Requires-Dist: sqlglot==30.15.0
 Description-Content-Type: text/markdown
 
 # Continuo Python Runtime
@@ -23,44 +25,69 @@ and register the release with Continuo.
 
 ## What this repo is
 
-Three artifacts come out of this repository:
+Four artifacts come out of this repository:
 
 - **The `continuo-python-runtime` PyPI package** — the `continuo-runtime` CLI
-  (`validate` / `merge` / `hash` / `lint` / `run`) and the harness library
-  (`conform()`, `RunContext`, the error taxonomy) that domain repos install.
-- **Per-engine base images**, one per warehouse engine (`...-postgres`,
-  `...-trino`), that domain repos build `FROM`. Each image bakes in the
-  runtime, a single `RuntimeAdapter` for that engine, and the
-  `continuo-runtime run` entrypoint.
+  (`validate` / `merge` / `hash` / `lint` / `run` / `validation-op`) and the
+  harness library (`conform()`, `RunContext`, the error taxonomy) that domain
+  repos install.
+- **The `continuo-engine-contract` PyPI package** — the `WarehouseAdapter`
+  port, the contract schema, the shared SQL/type/config guards, and the
+  sentinel result-block format. Adapter authors outside this repo pin it.
+- **Per-engine base images**, one per warehouse engine
+  (`continuo-python-runtime-postgres`, `continuo-python-runtime-trino`), that
+  domain repos build `FROM`. Each image bakes in the runtime and a single
+  `WarehouseAdapter` for that engine, and serves both roles that adapter has:
+  the node harness (`ENTRYPOINT ["continuo-runtime"]`, `CMD ["run"]`) and the
+  validation runner (`continuo-runtime validation-op`).
 - **`template/`** — a copy-ready domain repo: `Dockerfile`, `contracts/`,
   `scripts/`, and the `release.yml` CI/CD workflow.
 
-Base images and the PyPI publication of this package land with this repo's
-PR 9 (the image pipeline); until then, install the runtime from git as noted
-in `template/.github/workflows/release.yml`.
+One `vX.Y.Z` git tag releases all of it: `publish-pypi.yml` builds both
+distributions into a single `dist/` and publishes them together, and
+`images.yml` builds and pushes both engine images multi-arch under the same
+tag.
 
-### Package map
+### What this repo owns
 
-Each per-engine base image bakes together three PyPI packages: the harness,
-the engine adapter, and the published contract. The harness and both engine
-adapters live in *this* repo (`continuo-python-runtime`) as a uv workspace;
-`continuo-validation-runners` owns the *validation-side* (offline lint/merge)
-counterparts of the same engines, which is a separate concern from the
-data-plane adapters here.
+This repository owns the entire python-node surface: the engine contract, both
+engine adapters, the validation runner, and the node harness. The former
+`continuo-validation` repository was merged in — there is no longer a separate
+validation-side port, adapter class, entry-point group, or image. One
+`WarehouseAdapter` per engine serves both the data plane (`fetch` /
+`ensure_table` / `load`) and validation (`ensure_schema` / `drop_schema` /
+`build_empty_from_sql` / `build_empty_from_columns` / `clone_empty_from_prod` /
+`check_binds`), and one image per engine runs both roles.
 
 | Package (distribution name) | Module | Lives in | Role |
 | --- | --- | --- | --- |
-| `continuo-python-runtime` | `continuo_python_runtime` | this repo (root) | Harness: CLI, `conform()`, `RunContext`, error taxonomy. |
-| `continuo-python-runtime-postgres` | `continuo_python_runtime_postgres` | this repo, `python-runtime-postgres/` | Data-plane `RuntimeAdapter` for Postgres (`fetch`/`ensure_table`/`load`). |
-| `continuo-python-runtime-trino` | `continuo_python_runtime_trino` | this repo, `python-runtime-trino/` | Data-plane `RuntimeAdapter` for Trino/Iceberg. |
-| `continuo-validation-contract` | `continuo_validation_contract` | `continuo-validation-runners` | The published contract (schema, `RuntimeAdapter` port, result-block format) both sides depend on. |
-| `continuo-validation-postgres` / `continuo-validation-trino` | `continuo_validation_postgres` / `continuo_validation_trino` | `continuo-validation-runners` | Validation-side (lint/merge, no live warehouse I/O) adapters — not to be confused with the data-plane adapters above. |
-
-All three packages built in this repo resolve `continuo-validation-contract`
-from PyPI (`==0.3.0`); the two adapter packages are uv workspace members
-(`[tool.uv.workspace]` in the root `pyproject.toml`), so `uv sync
---all-packages --all-groups` at the repo root installs everything for local
-development.
+| `continuo-python-runtime` | `continuo_python_runtime` | this repo (root) | Harness (CLI, `conform()`, `RunContext`, error taxonomy) **and** the validation runner (`continuo-runtime validation-op`). Published to PyPI. |
+| `continuo-engine-contract` | `continuo_engine_contract` | this repo, `contract/` | The `WarehouseAdapter` port, contract schema, the SQL/type/config guards adapters must run, and the result-block format. Published to PyPI. |
+| `continuo-python-runtime-postgres` | `continuo_python_runtime_postgres` | this repo, `adapters/postgres/` | `PostgresAdapter` — one class, both roles. **Not published to PyPI** — built from source into the image. |
+| `continuo-python-runtime-trino` | `continuo_python_runtime_trino` | this repo, `adapters/trino/` | `TrinoAdapter` — one class, both roles, for Trino/Iceberg. **Not published to PyPI** — built from source into the image. |
+
+All four are uv workspace members (`[tool.uv.workspace]` in the root
+`pyproject.toml`), so `uv sync --all-packages --all-groups` at the repo root
+installs everything for local development.
+
+**Only `continuo-python-runtime` and `continuo-engine-contract` are published
+to PyPI.** The two engine adapters are built **from source into the engine
+images**: `Dockerfile.postgres` and `Dockerfile.trino` install them out of the
+build context, so each image ships exactly one adapter and the runtime
+discovers it through the `continuo_engine.adapters` entry-point group at run
+time. Nothing installs them from an index — the harness package does not
+depend on them, and domain repos get their adapter by building `FROM` a
+published base image. They are still built, type-checked, and tested by CI on
+every change.
+
+### The result block is a frozen wire contract
+
+`continuo_engine_contract.result` writes a sentinel-framed JSON block as the
+last line of stdout, and Continuo's Go side parses it byte-for-byte
+(`pkg/validationresult` in the `continuo` repository). That wire format — the
+sentinel markers, the framing, and the field names inside the block — is
+**frozen**. Reuse it; never change it from this side alone. A change here that
+the Go parser has not been taught is a production outage, not a refactor.
 
 ## Quickstart for domain teams
 
@@ -85,6 +112,28 @@ development.
    and merges the contracts, builds and pushes the image, uploads the merged
    contract to S3, and POSTs the release.
 
+### Upgrading an existing domain repo
+
+`validate` / `merge` / `hash` now hand every declared read to a real SQL
+parser (sqlglot, via `continuo_engine_contract.sql.ensure_single_read`)
+instead of scanning it for a leading `SELECT`/`WITH`. Two things follow for a
+repo written before this, on its next release: SQL a driver would accept but
+a parser will not — most commonly a driver-specific bind placeholder like
+psycopg2's `%(name)s`, which `ctx.read(name)` could never have used anyway —
+now fails validation, and engine-specific syntax (postgres `~`, `@>`, …)
+needs `--dialect <engine>`, which a repo should be passing regardless since
+Continuo bind-checks every read in the install's own warehouse dialect. Run
+the pre-flight check once before your next release; it reports every affected
+read at once:
+
+```bash
+continuo-runtime validate contracts/ --dialect postgres   # or trino
+```
+
+The runtime image does not re-run this gate, so a read that passes here is
+not re-judged under a different grammar in production. See
+`docs/boundary-contract.md` §13.1.
+
 ## The script API
 
 A node script is a Python file with exactly one required entry point:
@@ -106,9 +155,13 @@ def run(ctx):
   example a polars DataFrame. Returning anything else raises `ScriptError`.
 - The dataframe library is your choice. No dataframe library is baked into
   the base image — the package's own runtime dependencies are `pyarrow`,
-  `PyYAML`, and `continuo-validation-contract`. Add whatever you script
+  `PyYAML`, and `continuo-engine-contract`. Add whatever you script
   against (pandas, polars, …) as a `RUN pip install` line in your own
-  `Dockerfile`, on top of the base image.
+  `Dockerfile`, on top of the base image. The base image runs as non-root
+  (uid 65532), which pip cannot install under, so switch to root for the
+  install and back afterward — `USER root`, then the `RUN pip install`
+  line, then `USER 65532:65532` — since the executor's pod spec expects
+  the image to end at uid 65532. See `template/Dockerfile` for the pattern.
 - Scripts do not import warehouse drivers, write raw SQL literals, or call
   data-access methods directly — `continuo-runtime lint` rejects those:
   - forbidden driver imports (`psycopg2`/`sqlalchemy`/`trino`/etc.),
@@ -125,6 +178,17 @@ def run(ctx):
   are the driver-import and data-access-call rules, together with the fact
   that `RunContext` only exposes `ctx.read()` — all warehouse access goes
   through it.
+- Scripts may import shared in-repo helpers. Before executing a script the
+  harness puts the repo root (`APP_ROOT`) and the script's own directory on
+  `sys.path`, so both `import helpers` (a sibling of the script) and
+  `from lib.shared import ...` (anywhere under the repo root) work, including
+  from inside `run()`. Every helper a script reaches transitively is folded
+  into `shared_code_hash`, so editing one re-fingerprints the node — but the
+  hash does not put the file in the image: **`COPY` every directory your
+  scripts import from in your `Dockerfile`**, or the release is valid and the
+  node dies with `ModuleNotFoundError` on its first run. Because the repo root
+  precedes the standard library on `sys.path`, avoid naming a top-level module
+  after a stdlib one (`types.py`, `json.py`, `logging.py`, …).
 - The harness — not the script — performs the write. It calls `conform()`
   on whatever `run()` returned and issues the only INSERT; the script never
   writes directly.
@@ -165,19 +229,20 @@ A domain repo picks its warehouse engine by which base image it builds
 `FROM`:
 
 ```dockerfile
-FROM ghcr.io/carolsimone/continuo-python-runtime:v0.1.0-postgres
+FROM ghcr.io/carolsimone/continuo-python-runtime-postgres:v0.3.0
 # or
-FROM ghcr.io/carolsimone/continuo-python-runtime:v0.1.0-trino
+FROM ghcr.io/carolsimone/continuo-python-runtime-trino:v0.3.0
 ```
 
-Each image bakes in exactly one `RuntimeAdapter` for that engine — installed
-from this repo's `python-runtime-postgres/` or `python-runtime-trino/`
-package (see the package map above; both adapters live in this repo, not
-`continuo-validation-runners`) — registered under the
-`continuo_runtime.adapters` entry-point group (entry names `postgres` /
-`trino`). The harness discovers it via `discover_runtime_adapter()` at run
-time, so a single image serves every node in the service. The executor
-injects the
+The engine is part of the image **name**; the tag is the bare version, so
+Continuo's Helm chart can pin an image as `<name>:vX.Y.Z@sha256:<digest>`.
+
+Each image bakes in exactly one `WarehouseAdapter` for that engine — installed
+from this repo's `adapters/postgres/` or `adapters/trino/` package (see the
+table above) — registered under the `continuo_engine.adapters` entry-point
+group (entry names `postgres` / `trino`). The runtime discovers it via
+`discover_adapter()` at run time, so a single image serves every node in the
+service and the release-time validation Job for it. The executor injects the
 warehouse connection as environment variables (engine-native, e.g.
 `POSTGRES_HOST`/`POSTGRES_DB`/`POSTGRES_USER`) plus the node-selection
 environment (`NODE_ID`, `TABLE_NAME`, `TARGET_SCHEMA`, and optionally