continuo-python-runtime 0.10.0__tar.gz → 0.12.0__tar.gz

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.12.0}/.github/workflows/image-build.yml

@@ -89,7 +89,13 @@ jobs:
           # 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
+      # publish-pypi.yml, but an index can lag its own upload, so poll. A
+      # probe that succeeds does not guarantee the build's own request the
+      # same answer (two requests seconds apart can be served different
+      # copies of the index page), so the image build's install
+      # (scripts/install_image_pins.py) also retries while a pin is not
+      # served yet. This probe is the fast pre-check, and in a rehearsal it
+      # fetches the files compared byte for byte below. 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

continuo_python_runtime-0.12.0/.python-version

@@ -0,0 +1 @@
+3.14.8

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.12.0}/CHANGELOG.md

@@ -5,6 +5,219 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-11-11
+
+**TL;DR**
+
+- Hashes now come from continuo-contracts 0.1.0, the library continuo uses.
+  Every Python node's `content_hash` changes once, on its first release with
+  this version.
+- A node can list the files its script reads in `assets`, and the lint refuses
+  five kinds of code the hash cannot see.
+- The harness checks, when a node starts, that the image holds what the
+  release hashed.
+- The validation runner has two new read-only ops, `seed_preflight` and
+  `probe_views`.
+- Adapter authors: every adapter must now declare `drop_semantics`.
+
+**Upgrade**
+
+1. Build your domain image `FROM` the `v0.12.0` engine image and install
+   `continuo-python-runtime==0.12.0` in CI. The template's "Pin the runtime to
+   the image" step does this from the `FROM` line. A `Dockerfile.pip`
+   repository replaces that step as the template README says.
+2. Move each Python service with continuo's rebaseline release, not an
+   ordinary one: its `content_hash` changes once.
+3. `COPY` into the image every file a node lists in `assets`.
+4. Bring-your-own adapter: declare `drop_semantics`. You may also implement
+   `DependentsIntrospection` and run `DependentsConformance`.
+
+Versions: runtime 0.12.0 (pins continuo-contracts 0.1.0), engine contract 0.10.0, postgres adapter 0.4.0, trino adapter 0.5.0, duckdb adapter 0.3.0.
+
+### Added
+
+- Every engine adapter declares `drop_semantics`, what dropping a table does
+  to the objects that read it: `"cascade"` (they are destroyed) or
+  `"late_binding"` (they survive and fail on their next read). The postgres
+  adapter declares `cascade`, the trino and duckdb adapters `late_binding`.
+  `StartupConformance` has a new case, `test_declares_a_drop_semantics`.
+- `continuo_engine_contract.port` has an opt-in capability,
+  `DependentsIntrospection`, with `Dependent` and `Dependents` and the
+  vocabularies `DROP_SEMANTICS`, `COMPLETENESS` and `DEPENDENT_KINDS`. Its one
+  method, `dependents(schema, table)`, lists every object a drop of the table
+  would destroy or leave reading a missing table, and gives none for a missing
+  table or schema. The conformance class `DependentsConformance` checks it,
+  with an overridable `create_view` hook.
+- `PostgresAdapter.dependents(schema, table)` lists, with `completeness="exact"`,
+  every object a `DROP TABLE ... CASCADE` of the table destroys or changes: views
+  and materialized views to any depth, SQL-standard functions and procedures,
+  foreign keys and policies on other tables, rules, inheriting tables, tables
+  with a column of the table's row type or of an array of it, the types built
+  on the table (a domain, a range, a composite type) and what reads them, and
+  what reads a partition of the table or a sequence of it (owned or identity).
+  Each object is listed once, at its shallowest depth, and the walk follows at
+  most 32 dependency levels. It reads `pg_depend`, so it sees what
+  `information_schema.view_table_usage` misses, and finds the table
+  case-insensitively. `TestPostgresDependents` plus a guard that snapshots the
+  schemas around a rolled-back cascade check it. The adapter's README lists
+  every kind.
+- `TrinoAdapter.dependents(schema, table)` lists, with
+  `completeness="best_effort"`, the views whose SQL reads the table. It reads
+  `information_schema.views` of the adapter's catalog in one query and parses
+  each definition with sqlglot: an unqualified name is in the view's own
+  schema, a name without a catalog is in the adapter's, and a CTE of the same
+  statement is not the table. A definition that does not parse is matched by
+  the table's name as a whole identifier, with a WARNING naming the view. It
+  misses dynamic SQL, views in other catalogs, and views that read the table
+  only through another view. The adapter pins `sqlglot==30.23.0`, as the
+  engine contract does, and `TestTrinoDependents` runs the conformance cases
+  against Trino and the Iceberg REST catalog.
+- The validation runner has two read-only ops, `seed_preflight` and `probe_views`
+  (`VALIDATION_OP`), which need no `DBT_TARGET_SCHEMA`. `seed_preflight` lists the
+  objects a reload of a seed's production table would destroy or leave reading
+  a missing table, compares them with `SEED_PREFLIGHT_ALLOWED` and
+  `SEED_PREFLIGHT_ACKNOWLEDGED`, and in `check` mode exits 1 with `reason`
+  `unowned_dependents`, `engine_mismatch` or `warehouse_unreachable` when the
+  reload must not run; `report` mode prints the same `reason` and exits 0.
+  `probe_views` reads each view of `PROBE_VIEWS` with a zero-row `SELECT` and
+  reports which no longer bind, without failing. Both print one result block
+  with their own keys after `reason`; `result_block` takes them as a keyword-only
+  `fields` mapping and refuses a key that shadows a standard one. The README
+  section "Seed preflight and view probe" has the inputs, the block and the
+  decision table.
+- `continuo-runtime --version` prints `continuo-runtime <version>` to stdout and
+  exits 0. The template's `release.yml` has a "Pin the runtime to the image"
+  step that reads the version from the Dockerfile's
+  `FROM ghcr.io/carolsimone/continuo-python-runtime-<engine>:vX.Y.Z` line
+  (failing with an `::error::` when none matches), installs exactly that
+  runtime, and fails when the version `uv tool list` reports differs, so CI hashes
+  with the runtime the image runs.
+- The harness checks, before it builds the adapter, that the image holds what
+  the release hashed. When `CONTENT_HASH` is set it recomputes the node's
+  `content_hash` from the files in the image, with the helpers `merge` uses,
+  and a difference, or a hashed file missing from the image, fails the node
+  with `ImageContractMismatch` (a `ContractError`) and exit 1. The message
+  names both hashes, the three parts, the unit paths and the runtime version.
+  An unset or empty `CONTENT_HASH` logs a warning and runs. The result block
+  carries an optional `reason` key after `unique_id`
+  (`image_contract_mismatch`); a block without one keeps its bytes, and
+  `continuo_engine_contract.result.result_block` takes it as a keyword-only
+  `reason`.
+- `assets:` on a `python-node` or `python-api` node lists the repository files
+  its script reads. `merge` folds their bytes into `shared_code_hash`, so
+  editing one changes the node's `content_hash`, and writes `assets` on the
+  wire entry when a node declares any. A missing path, a non-file or a path
+  that resolves outside the repository fails `merge`; `python-csv` refuses the
+  key. The image must `COPY` the files.
+- `lint` and `merge` refuse code the content hash cannot see: `runpy`, a change
+  to `sys.path`, a `sitecustomize` or `usercustomize` module, `compile()` and
+  `types.FunctionType`, and `pickle.load`, `pickle.loads` and
+  `pickle.Unpickler`. `merge` also refuses a `sitecustomize.py` or
+  `usercustomize.py` at the repository root. A file a script reads belongs in
+  `assets`.
+
+### Changed
+
+- **Breaking for adapter authors.** `WarehouseAdapter.drop_semantics` is a
+  required declaration with no default: an adapter that does not set it cannot
+  pass the new conformance case.
+- A node's hashes come from continuo-contracts 0.1.0, the library
+  continuo's topology-controller uses too, so CI and continuo compute the
+  same values. `config_hash` hashes the node's code projection: `owner`,
+  `description`, `criticality` and `schedule` no longer move a node's hash,
+  a column type's spelling does not (`INT` and `INTEGER` hash alike), and a
+  read's SQL is hashed as written, apart from LF line endings and the
+  whitespace around it. `shared_code_hash` folds each import closure file
+  with its repo-relative path, so two files that swap their contents change
+  it. Every Python node's `content_hash` changes once, on the first release
+  built with this version. The wire entry keeps its keys and the fold.
+- A node whose `config` holds a value the hash cannot write (an integer
+  beyond 2**53 - 1, NaN or an infinity, nesting deeper than 99 levels, a
+  lone surrogate) fails `merge` with a `ContractError` naming the node.
+- The package gate no longer counts `continuo-contracts` as a first-party
+  distribution.
+
+### Fixed
+
+- A release's image build no longer fails when PyPI still serves an index
+  page from before the upload. The engine images install their pins through
+  `scripts/install_image_pins.py`, which retries an install while pip says a
+  pinned version is not served yet (up to 10 minutes) and fails any other
+  error at once. The v0.11.0 trino amd64 build hit this 40 s after the upload,
+  although the runner's own probe had seen the new version. No package
+  changes.
+
+## [0.11.0] - 2026-11-04
+
+**TL;DR**
+
+- A failed python node's log now says why it failed.
+- Every engine adapter waits up to about 10 s for a warehouse that refuses
+  the first connections, as a new Kubernetes pod sees until the cluster's
+  network policy admits it. That used to fail the attempt at once.
+- The trino adapter now connects when it is created, so a wrong Trino
+  password fails at start-up instead of at the first read.
+- Adapter authors: `StartupConformance` is a new conformance class every
+  adapter's integration suite runs.
+
+**Upgrade**
+
+1. Build your domain image `FROM` the `v0.11.0` engine image (or pin
+   `continuo-python-runtime==0.11.0` and your adapter's new version).
+2. Bring-your-own adapter: subclass `StartupConformance` in your integration
+   suite and provide the `warehouse_address` and `adapter_from_env` fixtures.
+
+Versions: runtime 0.11.0, engine contract 0.9.0, postgres adapter 0.3.2,
+trino adapter 0.4.0, duckdb adapter 0.2.2.
+
+### Fixed
+
+- A failed python node's stored log names its failure. The harness logs every
+  runtime error at ERROR on stderr, with the traceback of the exception it
+  wraps, as well as printing it in the result block. Continuo cuts the result
+  block out of the pod log before storing it, so a failure only printed there,
+  such as `LoadError: adapter construction failed: … Connection refused`, was
+  missing from the stored log.
+- Every adapter's `from_env` waits out a warehouse that refuses connections
+  for the first few seconds. A Job pod's first connection can be refused until
+  the cluster's NetworkPolicy engine (k3s's kube-router rejects) has admitted
+  the pod; that cost a task retry and a failed Job. A connection that no server
+  answered (every address refused, had no route or sat on an unreachable
+  network) is tried up to 5 times, 2 s apart, each retry logged. An
+  authentication failure, a timeout on any address and every other failure are
+  raised at once.
+  - postgres: around `psycopg2.connect`.
+  - duckdb: around the catalog attach.
+  - trino: `from_env` now sends `SELECT 1`, since the trino DBAPI opens no
+    connection until the first request. A refusal is retried only if it failed
+    within 5 s: urllib3 reports only the last address it tried, so a slower
+    one hides an address that timed out. A failed authentication now fails
+    `from_env` (a harness `LoadError`) rather than the first read or write.
+
+### Added
+
+- `StartupConformance` in `continuo_engine_contract.testing.conformance`: every
+  adapter's integration suite runs it. It puts the real engine behind a
+  loopback port that refuses connections for 3 s (`LateOpeningPort`), then
+  checks that `from_env` returns an adapter that answers `SELECT 1`. The new
+  fixtures are `warehouse_address` and `adapter_from_env`.
+
+### Changed
+
+- The python-node env contract in `docs/boundary-contract.md` lists
+  `TASK_ATTEMPT`, the 0-based number of the task's attempt, which the executor
+  sets on every production Job. The harness does not read it; a node script
+  may. Documentation only: no package changes.
+- The engine images build on `python:3.14.8-slim` (was `3.14.2`), and
+  `.python-version` and the `template/` Dockerfile follow.
+- `pyarrow` is pinned at `26.0.0` (was `25.0.1`) in the runtime, the engine
+  contract's `testing` extra and the three adapters, so they keep resolving
+  together.
+- Dependency pins move together across the workspace: `ruff` 0.17.1, `mypy`
+  2.4.0, `boto3` 1.43.114, `sqlglot` 30.23.0 (runtime and engine contract),
+  `trino` 0.340.0 and `psycopg2-binary` 2.9.13. `urllib3` moves to 2.8.0 in
+  `uv.lock` (CVE-2026-97687, CVE-2026-97689).
+
 ## [0.10.0] - 2026-10-22
 
 ### Added

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.12.0}/CLAUDE.md

@@ -28,15 +28,19 @@ merged PRs before adding anything new.
 conformance suite for engine adapter authors. Its dependencies are installed
 with `continuo-engine-contract[testing]`.
 
-- Every adapter MUST satisfy the engine contract and pass the shared
-  conformance classes for every capability it declares: `IntrospectionConformance`
-  for `TableIntrospection`, `AppendConformance` for `AppendCapable`, and
-  `UpsertConformance` for `UpsertCapable`. Append and upsert adapters must also
-  run the introspection class. An adapter need not declare capabilities its
-  engine cannot support.
+- Every adapter MUST satisfy the engine contract, declare a `drop_semantics`,
+  and pass `StartupConformance` (`from_env` waits out a warehouse that refuses
+  connections at first, and `drop_semantics` is declared) and the
+  shared conformance classes for every capability it declares:
+  `IntrospectionConformance` for `TableIntrospection`, `AppendConformance` for
+  `AppendCapable`, `UpsertConformance` for `UpsertCapable`, and
+  `DependentsConformance` for `DependentsIntrospection`. Append and
+  upsert adapters must also run the introspection class. An adapter need not
+  declare capabilities its engine cannot support.
 - Each adapter's integration suite MUST subclass the applicable classes,
-  supply connected `adapter` and temporary `schema` fixtures, and run them
-  against its real warehouse in CI. In-memory reference tests alone do not
+  supply connected `adapter` and temporary `schema` fixtures (and, for
+  `StartupConformance`, `warehouse_address` and `adapter_from_env`), and run
+  them against its real warehouse in CI. In-memory reference tests alone do not
   establish an adapter's conformance. Do not skip or weaken shared checks to
   accommodate an adapter that violates the contract.
 - Every new or changed engine-independent contract requirement, including

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.12.0}/CONTRIBUTING.md

@@ -151,7 +151,7 @@ gh workflow run publish-pypi.yml --ref <branch> -f dry_run=true
 |---|---|---|---|---|
 | `prepare`, `verify-packages`, `preflight-*` | nothing | nothing | none | Fix, delete the tag (`git push --delete origin vX.Y.Z`), re-tag. |
 | `publish-packages` | maybe some of the five files | nothing | none | Re-run failed jobs (`skip-existing` makes it resumable), or fix forward. |
-| `candidate-build` | published | maybe untagged digests | none | Transient (index lag, runner): re-run failed jobs. Real defect: yank the files on pypi.org and **fix forward** with a new version. |
+| `candidate-build` | published | maybe untagged digests | none | The build waits up to 10 minutes on its own for the index to serve the new pins. Transient (a runner, a longer index lag): re-run failed jobs. Real defect: yank the files on pypi.org and **fix forward** with a new version. |
 | `candidate-verify` | published | untagged candidates | none | Same: an image defect means yank and fix forward. |
 | `promote` | published | verified digests, maybe some engines tagged | none | Re-run failed jobs; tagging is idempotent and refuses to move an existing tag to different content. |
 

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.12.0}/Dockerfile.duckdb

@@ -1,4 +1,4 @@
-FROM python:3.14.2-slim
+FROM python:3.14.8-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:
@@ -12,30 +12,17 @@ FROM python:3.14.2-slim
 #                           package names, so it is never an extra index.
 #                           Any other value fails the build.
 # The pinned versions live in image-requirements-duckdb.txt, kept equal to the
-# repo's pyproject versions by tests/test_image_requirements_sync.py. See
-# Dockerfile.postgres for the full reasoning behind the two-step wheelhouse
-# install (exact local files first, --no-index --no-deps, then PyPI for the
-# third-party dependencies).
+# repo's pyproject versions by tests/test_image_requirements_sync.py.
+# scripts/install_image_pins.py runs the installs for each WHEEL_SOURCE (and
+# says why the wheelhouse wheels are installed by exact file first). It
+# retries an index install while the index does not serve a just-uploaded
+# pin yet: a release builds its images right after the upload.
 ARG WHEEL_SOURCE=pypi
 COPY image-requirements-duckdb.txt /tmp/req.txt
 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_duckdb_adapter-*.whl; \
-      pip install --no-cache-dir -r /tmp/req.txt; \
-    elif [ "$WHEEL_SOURCE" = "testpypi" ]; then \
-      pip install --no-cache-dir --no-deps --only-binary=:all: --index-url https://test.pypi.org/simple/ \
-        -r /tmp/req.txt; \
-      pip install --no-cache-dir -r /tmp/req.txt; \
-    elif [ "$WHEEL_SOURCE" = "pypi" ]; then \
-      pip install --no-cache-dir -r /tmp/req.txt; \
-    else \
-      echo "unknown WHEEL_SOURCE=$WHEEL_SOURCE (pypi|testpypi|wheelhouse)" >&2; exit 1; \
-    fi; \
-    rm -rf /tmp/req.txt /tmp/wheelhouse
+COPY scripts/install_image_pins.py /tmp/install_image_pins.py
+RUN python /tmp/install_image_pins.py --source "$WHEEL_SOURCE" --adapter duckdb --requirements /tmp/req.txt --wheelhouse /tmp/wheelhouse \
+    && rm -rf /tmp/req.txt /tmp/wheelhouse /tmp/install_image_pins.py
 # The adapter LOADs ducklake/postgres/httpfs/aws from this directory. They are
 # installed now, as root, because the runtime user below has no home directory
 # and the container may have no network. HOME=/tmp gives DuckDB a writable

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.12.0}/Dockerfile.postgres

@@ -1,4 +1,4 @@
-FROM python:3.14.2-slim
+FROM python:3.14.8-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:
@@ -15,48 +15,25 @@ FROM python:3.14.2-slim
 #                           Any other value fails the build.
 # 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.
+# PyPI in both branches, so the wheelhouse install never passes --no-index to
+# the requirements install.
 # 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.
+# scripts/install_image_pins.py runs the installs for each WHEEL_SOURCE (and
+# says why the wheelhouse wheels are installed by exact file first). It
+# retries an index install while the index does not serve a just-uploaded
+# pin yet: a release builds its images right after the upload.
 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.
+# pre-created directory. Only the wheelhouse install 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; \
-    elif [ "$WHEEL_SOURCE" = "testpypi" ]; then \
-      pip install --no-cache-dir --no-deps --only-binary=:all: --index-url https://test.pypi.org/simple/ \
-        -r /tmp/req.txt; \
-      pip install --no-cache-dir -r /tmp/req.txt; \
-    elif [ "$WHEEL_SOURCE" = "pypi" ]; then \
-      pip install --no-cache-dir -r /tmp/req.txt; \
-    else \
-      echo "unknown WHEEL_SOURCE=$WHEEL_SOURCE (pypi|testpypi|wheelhouse)" >&2; exit 1; \
-    fi; \
-    rm -rf /tmp/req.txt /tmp/wheelhouse
+COPY scripts/install_image_pins.py /tmp/install_image_pins.py
+RUN python /tmp/install_image_pins.py --source "$WHEEL_SOURCE" --adapter postgres --requirements /tmp/req.txt --wheelhouse /tmp/wheelhouse \
+    && rm -rf /tmp/req.txt /tmp/wheelhouse /tmp/install_image_pins.py
 # 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

{continuo_python_runtime-0.10.0 → continuo_python_runtime-0.12.0}/Dockerfile.trino

@@ -1,4 +1,4 @@
-FROM python:3.14.2-slim
+FROM python:3.14.8-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:
@@ -15,48 +15,25 @@ FROM python:3.14.2-slim
 #                           Any other value fails the build.
 # 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.
+# PyPI in both branches, so the wheelhouse install never passes --no-index to
+# the requirements install.
 # 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.
+# scripts/install_image_pins.py runs the installs for each WHEEL_SOURCE (and
+# says why the wheelhouse wheels are installed by exact file first). It
+# retries an index install while the index does not serve a just-uploaded
+# pin yet: a release builds its images right after the upload.
 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.
+# pre-created directory. Only the wheelhouse install 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; \
-    elif [ "$WHEEL_SOURCE" = "testpypi" ]; then \
-      pip install --no-cache-dir --no-deps --only-binary=:all: --index-url https://test.pypi.org/simple/ \
-        -r /tmp/req.txt; \
-      pip install --no-cache-dir -r /tmp/req.txt; \
-    elif [ "$WHEEL_SOURCE" = "pypi" ]; then \
-      pip install --no-cache-dir -r /tmp/req.txt; \
-    else \
-      echo "unknown WHEEL_SOURCE=$WHEEL_SOURCE (pypi|testpypi|wheelhouse)" >&2; exit 1; \
-    fi; \
-    rm -rf /tmp/req.txt /tmp/wheelhouse
+COPY scripts/install_image_pins.py /tmp/install_image_pins.py
+RUN python /tmp/install_image_pins.py --source "$WHEEL_SOURCE" --adapter trino --requirements /tmp/req.txt --wheelhouse /tmp/wheelhouse \
+    && rm -rf /tmp/req.txt /tmp/wheelhouse /tmp/install_image_pins.py
 # 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