continuo-python-runtime 0.4.0__tar.gz → 0.4.1__tar.gz

{continuo_python_runtime-0.4.0 → continuo_python_runtime-0.4.1}/.github/workflows/ci.yml

@@ -6,7 +6,7 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
       - name: Sync
         run: uv sync --all-packages --all-groups
@@ -19,9 +19,9 @@ jobs:
       - 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
+        run: uv run --package continuo-postgres-adapter mypy adapters/postgres/continuo_postgres_adapter
       - name: Types (trino adapter)
-        run: uv run --package continuo-python-runtime-trino mypy adapters/trino/continuo_python_runtime_trino
+        run: uv run --package continuo-trino-adapter mypy adapters/trino/continuo_trino_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
@@ -41,7 +41,7 @@ jobs:
   integration-postgres:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
       - run: uv sync --all-packages --all-groups
       - name: Start postgres stack
@@ -55,7 +55,7 @@ jobs:
   integration-trino:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
       - run: uv sync --all-packages --all-groups
       - name: Start trino stack

{continuo_python_runtime-0.4.0 → continuo_python_runtime-0.4.1}/.github/workflows/dco.yml

@@ -14,7 +14,7 @@ jobs:
   dco:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           # The whole PR commit range has to be walkable, not just the merge commit.
           fetch-depth: 0

{continuo_python_runtime-0.4.0 → continuo_python_runtime-0.4.1}/.github/workflows/images.yml

@@ -20,12 +20,15 @@ jobs:
         engine: [postgres, trino]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - name: Build wheels into a wheelhouse
+        run: uv build --all-packages -o wheelhouse
       - name: Build ${{ matrix.engine }} image
-        run: docker build -f Dockerfile.${{ matrix.engine }} -t cpr-smoke-${{ matrix.engine }} .
+        run: docker build -f Dockerfile.${{ matrix.engine }} --build-arg WHEEL_SOURCE=wheelhouse -t cpr-smoke-${{ matrix.engine }} .
       - name: Save image
         run: docker save cpr-smoke-${{ matrix.engine }} -o /tmp/cpr-smoke-${{ matrix.engine }}.tar
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: cpr-smoke-${{ matrix.engine }}-image
           path: /tmp/cpr-smoke-${{ matrix.engine }}.tar
@@ -49,8 +52,8 @@ jobs:
           --health-timeout 5s
           --health-retries 10
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/download-artifact@v4
+      - uses: actions/checkout@v7
+      - uses: actions/download-artifact@v8
         with:
           name: cpr-smoke-postgres-image
           path: /tmp
@@ -104,8 +107,8 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/download-artifact@v4
+      - uses: actions/checkout@v7
+      - uses: actions/download-artifact@v8
         with:
           name: cpr-smoke-trino-image
           path: /tmp
@@ -153,21 +156,31 @@ jobs:
         if: always()
         run: docker compose -f tests/smoke/trino-stack/docker-compose.yml down -v
 
-  # 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
+  # Runs on this same tag push, after the smoke jobs above pass. It builds both
+  # engine images for linux/amd64 and linux/arm64 installing the pinned
+  # versions FROM PyPI (WHEEL_SOURCE=pypi, the Dockerfile default), then
+  # pushes 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.
+  # 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.
+  #
+  # publish-pypi.yml runs in parallel on this same tag push, not before this
+  # job: there is no cross-workflow `needs:`, so this job cannot wait on that
+  # workflow directly. Instead the wait-until-installable step below polls
+  # PyPI until the pinned versions this tag just published are actually
+  # installable, which is what orders this build after publish-pypi.yml
+  # completes without a cross-workflow dependency.
+  # -test tags publish to TestPyPI only (see publish-pypi.yml), so this job
+  # skips them: there is no real-PyPI installable version to build an image
+  # from for those.
   publish:
-    if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-test')
     needs: [smoke-postgres, smoke-trino]
+    if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-test')
     strategy:
       matrix:
         engine: [postgres, trino]
@@ -176,8 +189,8 @@ jobs:
       contents: read
       packages: write
     steps:
-      - uses: actions/checkout@v4
-      - uses: docker/setup-qemu-action@v3
+      - uses: actions/checkout@v7
+      - uses: docker/setup-qemu-action@v4
       - uses: docker/setup-buildx-action@v4
       - name: Log in to ghcr.io
         uses: docker/login-action@v4
@@ -185,6 +198,26 @@ jobs:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
+      # The pinned distributions declare Requires-Python >= 3.14, so the
+      # availability probe must resolve them under a 3.14 interpreter — the
+      # runner's default python is older and pip would reject them even after
+      # they are published, spinning out every retry. (The image build itself
+      # installs inside python:3.14-slim, so it is unaffected; this is only for
+      # the host-side probe below.)
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - name: Wait until the pinned versions are installable from PyPI
+        run: |
+          set -eu
+          req="image-requirements-${{ matrix.engine }}.txt"
+          for i in $(seq 1 30); do
+            if python -m pip download --dest /tmp/probe -r "$req" >/tmp/probe.log 2>&1; then
+              echo "installable"; exit 0
+            fi
+            echo "attempt $i: not yet on index; sleeping"; sleep 20
+          done
+          echo "pinned versions never became installable"; cat /tmp/probe.log; exit 1
       - name: Build and push ${{ matrix.engine }} image
         uses: docker/build-push-action@v7
         with:

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

@@ -0,0 +1,99 @@
+name: publish-pypi
+
+# Publishes all four PyPI distributions this repo owns — continuo-python-runtime
+# (the harness), continuo-engine-contract (the port, result-block format, and
+# shared guards), and the two engine adapters (continuo-postgres-adapter,
+# continuo-trino-adapter) — via PyPI Trusted Publishing (OIDC, no stored
+# token). They publish together on a single v* tag, each at its own
+# pyproject version, so a tag that only bumps the runtime still carries an
+# unchanged adapter version along for the ride; skip-existing (below) makes
+# that a no-op rather than a duplicate-upload failure. A release-time guard
+# (scripts/check_version_bumps.py) refuses a tag that changed a package's
+# source without bumping its version, so skip-existing can never silently
+# ship stale adapter code under an unchanged version number.
+#
+# 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 — all four project names need one on each index.
+#
+# All four 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@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+      - name: Refuse a tag that changed a package without bumping its version
+        run: python scripts/check_version_bumps.py
+      - name: Test before publishing
+        # Gate all four published projects, including both adapter suites — an
+        # adapter regression must block its own immutable PyPI upload, and
+        # images.yml runs in parallel so its smoke failure cannot. Each suite is
+        # a SEPARATE pytest invocation: every workspace member's tests/ is its
+        # own `tests` package (with __init__.py + conftest.py), so running two
+        # of them in one process collides on the `tests.conftest` module name
+        # (see the [tool.pytest.ini_options] note in pyproject.toml). `not image
+        # and not integration` deselects the tests needing a built engine image
+        # or a live warehouse (images.yml / the smoke jobs cover those). The
+        # step's default `set -e` fails the gate if any invocation fails.
+        run: |
+          uv sync --all-packages --all-groups
+          uv run pytest tests contract/tests -m "not image and not integration" -q
+          uv run pytest adapters/postgres/tests -m "not image and not integration" -q
+          uv run pytest adapters/trino/tests -m "not image and not integration" -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: Build the postgres adapter sdist + wheel
+        run: uv build --package continuo-postgres-adapter -o dist
+      - name: Build the trino adapter sdist + wheel
+        run: uv build --package continuo-trino-adapter -o dist
+      # Adapters change rarely, so most v* tags carry an unchanged adapter
+      # version alongside a bumped runtime/contract version. Without
+      # skip-existing, re-uploading that unchanged version 400s and fails the
+      # whole publish. Trade-off: a changed package published without a
+      # version bump is then silently skipped too — the
+      # check_version_bumps.py guard above is what catches that case, before
+      # this job's build/publish steps ever run.
+      - 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
+          skip-existing: true
+      - 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
+          skip-existing: true

{continuo_python_runtime-0.4.0 → continuo_python_runtime-0.4.1}/.github/workflows/release.yml

@@ -53,7 +53,7 @@ jobs:
       # other source of the repo's files. Its absence went unnoticed through
       # review because this job only triggers on push:tags, never on
       # pull_request, so no PR's CI ever actually executes it.
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Wait for publish-pypi.yml and images.yml to finish on this commit
         run: |

{continuo_python_runtime-0.4.0 → continuo_python_runtime-0.4.1}/.github/workflows/security.yml

@@ -47,7 +47,7 @@ jobs:
       # range (below), and this repository is small enough (a few hundred KB,
       # well under a second to scan) that fetch-depth: 0 costs nothing on every
       # trigger rather than only on the schedule.
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
@@ -106,7 +106,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 20
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       # Advisory: reports HIGH/CRITICAL and always exits 0. Base-image and
       # transitive CVEs are often unfixable upstream, so gating on them would

{continuo_python_runtime-0.4.0 → continuo_python_runtime-0.4.1}/CONTRIBUTING.md

@@ -57,8 +57,8 @@ uv run ruff check .
 uv run ruff check contract
 uv run mypy continuo_python_runtime
 uv run mypy contract/continuo_engine_contract
-uv run --package continuo-python-runtime-postgres mypy adapters/postgres/continuo_python_runtime_postgres
-uv run --package continuo-python-runtime-trino mypy adapters/trino/continuo_python_runtime_trino
+uv run --package continuo-postgres-adapter mypy adapters/postgres/continuo_postgres_adapter
+uv run --package continuo-trino-adapter mypy adapters/trino/continuo_trino_adapter
 uv run pytest --cov=continuo_python_runtime -m "not image and not integration" -v
 uv run pytest tests/test_csv_readers_integration.py tests/test_validation_runner.py -m integration -v
 uv run pytest contract/tests -v

continuo_python_runtime-0.4.1/Dockerfile.postgres

@@ -0,0 +1,56 @@
+FROM python:3.14-slim
+# One dual-role image per engine — the python-node runtime harness (default
+# command `run`) and the blue/green validation runner (`validation-op`). It
+# installs the PUBLISHED, versioned libraries, never the repo source:
+#   WHEEL_SOURCE=pypi       (release) installs the pins from PyPI. PyPI versions
+#                           are immutable and the image is consumed
+#                           digest-pinned, so no hash lock is needed here.
+#   WHEEL_SOURCE=wheelhouse (CI/PR)   installs the same pins from ./wheelhouse
+#                           (built by CI) so an unreleased change is testable.
+# The wheelhouse holds only this repo's own first-party wheels (built via
+# `uv build --all-packages`); third-party dependencies always resolve from
+# PyPI in both branches, so the wheelhouse branch never passes --no-index to
+# the requirements install below.
+# The pinned versions live in image-requirements-postgres.txt, kept equal to the
+# repo's pyproject versions by tests/test_image_requirements_sync.py.
+#
+# The wheelhouse branch installs its three first-party wheels (contract,
+# runtime, adapter) by exact local file first, with --no-index --no-deps: a
+# plain `--find-links=/tmp/wheelhouse -r req.txt` is not enough, because pip
+# does not prefer a find-links wheel over an index match at the same
+# name+version, and continuo-python-runtime / continuo-engine-contract are
+# already published on PyPI under the version this repo's HEAD currently
+# carries (a routine dependency bump lands between releases without a version
+# bump). Left unpinned-by-file, pip silently installs the last PyPI release's
+# transitive pins instead of the wheel this build just produced, defeating
+# the point of testing an unreleased change. Installing the exact local files
+# first (no index contacted at all for this step) is unambiguous; the second
+# install then only has PyPI-only third-party deps left to resolve, and finds
+# the three first-party packages already satisfied.
+ARG WHEEL_SOURCE=pypi
+COPY image-requirements-postgres.txt /tmp/req.txt
+# Optional COPY: the bracket glob matches ./wheelhouse when it exists (the CI/PR
+# WHEEL_SOURCE=wheelhouse path builds it) and no-ops when it is absent, so a
+# release build or a plain `docker build -f Dockerfile.postgres .` needs no
+# pre-created directory. Only the wheelhouse branch below reads its contents.
+COPY wheelhous[e] /tmp/wheelhouse
+RUN set -eu; \
+    if [ "$WHEEL_SOURCE" = "wheelhouse" ]; then \
+      pip install --no-cache-dir --no-index --no-deps \
+        /tmp/wheelhouse/continuo_engine_contract-*.whl \
+        /tmp/wheelhouse/continuo_python_runtime-*.whl \
+        /tmp/wheelhouse/continuo_postgres_adapter-*.whl; \
+      pip install --no-cache-dir -r /tmp/req.txt; \
+    else \
+      pip install --no-cache-dir -r /tmp/req.txt; \
+    fi; \
+    rm -rf /tmp/req.txt /tmp/wheelhouse
+# 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.4.1/Dockerfile.trino

@@ -0,0 +1,56 @@
+FROM python:3.14-slim
+# One dual-role image per engine — the python-node runtime harness (default
+# command `run`) and the blue/green validation runner (`validation-op`). It
+# installs the PUBLISHED, versioned libraries, never the repo source:
+#   WHEEL_SOURCE=pypi       (release) installs the pins from PyPI. PyPI versions
+#                           are immutable and the image is consumed
+#                           digest-pinned, so no hash lock is needed here.
+#   WHEEL_SOURCE=wheelhouse (CI/PR)   installs the same pins from ./wheelhouse
+#                           (built by CI) so an unreleased change is testable.
+# The wheelhouse holds only this repo's own first-party wheels (built via
+# `uv build --all-packages`); third-party dependencies always resolve from
+# PyPI in both branches, so the wheelhouse branch never passes --no-index to
+# the requirements install below.
+# The pinned versions live in image-requirements-trino.txt, kept equal to the
+# repo's pyproject versions by tests/test_image_requirements_sync.py.
+#
+# The wheelhouse branch installs its three first-party wheels (contract,
+# runtime, adapter) by exact local file first, with --no-index --no-deps: a
+# plain `--find-links=/tmp/wheelhouse -r req.txt` is not enough, because pip
+# does not prefer a find-links wheel over an index match at the same
+# name+version, and continuo-python-runtime / continuo-engine-contract are
+# already published on PyPI under the version this repo's HEAD currently
+# carries (a routine dependency bump lands between releases without a version
+# bump). Left unpinned-by-file, pip silently installs the last PyPI release's
+# transitive pins instead of the wheel this build just produced, defeating
+# the point of testing an unreleased change. Installing the exact local files
+# first (no index contacted at all for this step) is unambiguous; the second
+# install then only has PyPI-only third-party deps left to resolve, and finds
+# the three first-party packages already satisfied.
+ARG WHEEL_SOURCE=pypi
+COPY image-requirements-trino.txt /tmp/req.txt
+# Optional COPY: the bracket glob matches ./wheelhouse when it exists (the CI/PR
+# WHEEL_SOURCE=wheelhouse path builds it) and no-ops when it is absent, so a
+# release build or a plain `docker build -f Dockerfile.trino .` needs no
+# pre-created directory. Only the wheelhouse branch below reads its contents.
+COPY wheelhous[e] /tmp/wheelhouse
+RUN set -eu; \
+    if [ "$WHEEL_SOURCE" = "wheelhouse" ]; then \
+      pip install --no-cache-dir --no-index --no-deps \
+        /tmp/wheelhouse/continuo_engine_contract-*.whl \
+        /tmp/wheelhouse/continuo_python_runtime-*.whl \
+        /tmp/wheelhouse/continuo_trino_adapter-*.whl; \
+      pip install --no-cache-dir -r /tmp/req.txt; \
+    else \
+      pip install --no-cache-dir -r /tmp/req.txt; \
+    fi; \
+    rm -rf /tmp/req.txt /tmp/wheelhouse
+# 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.4.0/README.md → continuo_python_runtime-0.4.1/PKG-INFO

@@ -1,3 +1,23 @@
+Metadata-Version: 2.5
+Name: continuo-python-runtime
+Version: 0.4.1
+Summary: Runtime harness, contract tooling, and CI lint for Continuo python nodes.
+Author: Simone Carolini
+Maintainer: Simone Carolini
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: boto3==1.43.74
+Requires-Dist: continuo-engine-contract==0.7.3
+Requires-Dist: pyarrow==25.0.1
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: sqlglot==30.17.0
+Description-Content-Type: text/markdown
+
 # Continuo Python Runtime
 
 [![CI](https://github.com/carolsimone/continuo-python-runtime/actions/workflows/ci.yml/badge.svg)](https://github.com/carolsimone/continuo-python-runtime/actions/workflows/ci.yml)
@@ -12,7 +32,7 @@ and register the release with Continuo.
 
 ## What this repo is
 
-Four artifacts come out of this repository:
+Five artifacts come out of this repository:
 
 - **The `continuo-python-runtime` PyPI package** — the `continuo-runtime` CLI
   (`validate` / `merge` / `hash` / `lint` / `run` / `validation-op`) and the
@@ -21,6 +41,13 @@ Four artifacts come out of this repository:
 - **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.
+- **The two engine-adapter PyPI packages** (`continuo-postgres-adapter`,
+  `continuo-trino-adapter`) — one `WarehouseAdapter` implementation per
+  warehouse engine, each published independently under the same tag. A
+  domain repo normally never installs these directly (the engine image
+  already has the matching one baked in); they exist as standalone PyPI
+  packages for the "build your own container" shape (see below) and for
+  third-party adapter authors to reference.
 - **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
@@ -30,10 +57,11 @@ Four artifacts come out of this repository:
 - **`template/`** — a copy-ready domain repo: `Dockerfile`, `contracts/`,
   `scripts/`, and the `release.yml` CI/CD workflow.
 
-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.
+One `vX.Y.Z` git tag releases all of it: `publish-pypi.yml` builds all four
+PyPI distributions into a single `dist/` and publishes them together, and
+`images.yml` builds and pushes both engine images — each installing its
+matching pinned adapter version from that same release — multi-arch under
+the same tag.
 
 ### What this repo owns
 
@@ -50,22 +78,27 @@ validation-side port, adapter class, entry-point group, or image. One
 | --- | --- | --- | --- |
 | `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. |
+| `continuo-postgres-adapter` | `continuo_postgres_adapter` | this repo, `adapters/postgres/` | `PostgresAdapter` — one class, both roles. Published to PyPI. |
+| `continuo-trino-adapter` | `continuo_trino_adapter` | this repo, `adapters/trino/` | `TrinoAdapter` — one class, both roles, for Trino/Iceberg. Published to PyPI. |
 
 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.
+**All four packages in the table above are published to PyPI**, under the
+same `vX.Y.Z` tag. The two engine images then **install the matching pinned
+adapter version from PyPI** — `Dockerfile.postgres` installs
+`continuo-postgres-adapter==X.Y.Z`, `Dockerfile.trino` installs
+`continuo-trino-adapter==X.Y.Z` — rather than building it from this repo's
+source tree, so each image still ships exactly one adapter and the runtime
+still discovers it through the `continuo_engine.adapters` entry-point group
+at run time. The image **name** (`continuo-python-runtime-<engine>`) and the
+adapter's pip **distribution** name (`continuo-<engine>-adapter`) are two
+different artifacts of the same adapter — same engine, same version, same
+runtime behavior, different packaging; see "Build your own container" below
+for a build shape that installs the pip package directly instead of `FROM`
+the image. All four packages are still built, type-checked, and tested by CI
+on every change.
 
 ### The result block is a frozen wire contract
 
@@ -242,26 +275,46 @@ A domain repo picks its warehouse engine by which base image it builds
 `FROM`:
 
 ```dockerfile
-FROM ghcr.io/carolsimone/continuo-python-runtime-postgres:v0.4.0
+FROM ghcr.io/carolsimone/continuo-python-runtime-postgres:v0.4.1
 # or
-FROM ghcr.io/carolsimone/continuo-python-runtime-trino:v0.4.0
+FROM ghcr.io/carolsimone/continuo-python-runtime-trino:v0.4.1
 ```
 
 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.
+Each image bakes in exactly one `WarehouseAdapter` for that engine — the
+pinned PyPI version of the `continuo-postgres-adapter` or
+`continuo-trino-adapter` package built from this repo's `adapters/postgres/`
+or `adapters/trino/` source (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
 `CONTRACT_DIR`/`APP_ROOT`) that `continuo-runtime run` reads to dispatch the
 right node's script.
 
+### Build your own container
+
+A domain repo does not have to build `FROM` the published engine image.
+`template/` ships two Dockerfiles for the two build shapes (see
+`template/README.md` § "Choosing a base" for the full comparison):
+
+- **Shape 1 — `template/Dockerfile`** — `FROM` the published engine image
+  (`continuo-python-runtime-<engine>`), as shown above. Simplest; the image
+  already has the runtime and adapter installed and pinned.
+- **Shape 2 — `template/Dockerfile.pip`** — your own base image, installing
+  `continuo-python-runtime` and one `continuo-<engine>-adapter` from PyPI
+  via a hash-locked `requirements.lock` (`template/requirements.lock`). Use
+  this when you must control the base image yourself.
+
+Both shapes end up running the same runtime and the same adapter version;
+which one you pick only changes who controls the base OS layer underneath
+them.
+
 ## Further reading
 
 - `docs/superpowers/specs/2026-07-31-python-runtime-design.md` — this