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

{continuo_python_runtime-0.11.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.11.0 → continuo_python_runtime-0.12.0}/CHANGELOG.md

@@ -5,6 +5,148 @@ 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**

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

@@ -28,11 +28,13 @@ 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 `StartupConformance`
-  (`from_env` waits out a warehouse that refuses connections at first) and the
+- 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`, and `UpsertConformance` for `UpsertCapable`. Append and
+  `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,

{continuo_python_runtime-0.11.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.11.0 → continuo_python_runtime-0.12.0}/Dockerfile.duckdb

@@ -12,30 +12,17 @@ FROM python:3.14.8-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.11.0 → continuo_python_runtime-0.12.0}/Dockerfile.postgres

@@ -15,48 +15,25 @@ FROM python:3.14.8-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.11.0 → continuo_python_runtime-0.12.0}/Dockerfile.trino

@@ -15,48 +15,25 @@ FROM python:3.14.8-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

{continuo_python_runtime-0.11.0 → continuo_python_runtime-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: continuo-python-runtime
-Version: 0.11.0
+Version: 0.12.0
 Summary: Runtime harness, contract tooling, and CI lint for Continuo python nodes.
 Author: Simone Carolini
 Maintainer: Simone Carolini
@@ -12,7 +12,8 @@ Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.14
 Requires-Dist: boto3==1.43.114
-Requires-Dist: continuo-engine-contract==0.9.0
+Requires-Dist: continuo-contracts==0.1.0
+Requires-Dist: continuo-engine-contract==0.10.0
 Requires-Dist: pyarrow==26.0.0
 Requires-Dist: pyyaml==6.0.3
 Requires-Dist: sqlglot==30.23.0
@@ -112,7 +113,12 @@ on every change.
 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
+**frozen**. The additions are an optional `reason` key, written after
+`unique_id` only when an outcome has a machine-readable code (for example
+`image_contract_mismatch`), and the op's own keys that the `seed_preflight` and
+`probe_views` ops write after `reason`; a block without either keeps its bytes,
+and the sentinels, `schema_version` and the five standard keys do not change. 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
@@ -196,14 +202,37 @@ produced, never how it is checked or written.
   script reads with `os.environ[...]`. The contract never holds a secret value
   or env var name; the Secret itself is created in the cluster by the operator.
 
+### Files a script reads (`assets`)
+
+A `python-node` or `python-api` script that reads a file from the repository
+(a model, a lookup table, a JSON config) lists it under `assets:`, one path
+relative to the repository root per entry, written with forward slashes and
+without a `..` segment:
+
+```yaml
+- schema: analytics
+  table: scored_orders
+  kind: python-node
+  script: scripts/scored_orders.py
+  assets: [data/rates.json, models/scorer.bin]
+```
+
+`merge` reads each listed file and folds its bytes into `shared_code_hash`
+under its path, so editing one changes the node's `content_hash` and starts a
+validation. A path that is also an import of the script is one unit. `merge`
+fails with a `ContractError` for a path that is missing, is not a file or
+resolves outside the repository, and a path listed twice is refused. The image
+must `COPY` the files, because `assets` only tells the hash about them. A
+`python-csv` node has no script, so `assets` is refused on it.
+
 ### Task timeout
 
 Any node may set `timeout_minutes:` — an integer from 1 to 10,080 (one week) —
 to declare how long its task may run before continuo gives up on it. A value
 outside that range, or one that is not an integer, fails
-`continuo-runtime validate`/`merge`/`lint`. It is the one key that is not part
-of `config_hash`, so changing only the timeout never changes the node's
-`content_hash`.
+`continuo-runtime validate`/`merge`/`lint`. Like `owner`, `schedule`,
+`criticality` and `description`, it is outside the code projection that
+`config_hash` hashes, so changing it never changes the node's `content_hash`.
 
 ## Write modes
 
@@ -282,7 +311,7 @@ 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-engine-contract`. Add whatever you script
+  `PyYAML`, `continuo-engine-contract` and `continuo-contracts`. Add whatever you script
   against (pandas, polars, …) as a `RUN pip install` line in your own
   `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
@@ -298,7 +327,18 @@ def run(ctx):
     read_sql as rs` then calling `rs(...)`),
   - private/protected attribute access (`obj._x`) — except on `self`/`cls`,
     so a script's own class-private helpers (`self._helper()`) aren't
-    flagged.
+    flagged,
+  - code the content hash cannot see. The hash folds the script and the files
+    it imports, found by reading imports, so a node that runs anything else
+    can change without its `content_hash` changing. Lint refuses `runpy`, a
+    change to `sys.path` (`append`, `insert`, assignment, `del`, and
+    `site.addsitedir`), a `sitecustomize` or `usercustomize` module (and a file
+    of that name), `compile()` and `types.FunctionType`, and `pickle.load`,
+    `pickle.loads` and `pickle.Unpickler`. `merge` applies the same rules to
+    every file in a node's import closure, and refuses a `sitecustomize.py` or
+    `usercustomize.py` at the repository root, which Python imports before the
+    harness starts. A file a script reads, such as a model or a lookup table,
+    belongs in the node's `assets`, where its bytes are hashed.
 
   The SQL-literal rule is best-effort: docstrings are exempt, but other
   prose may still occasionally match. The hard guarantees enforced by lint
@@ -337,7 +377,7 @@ declared `output_columns` on the table `run()` returned, in this order:
 
 ## Error taxonomy
 
-Every runtime failure is one of five `HarnessError` subclasses
+Every runtime failure is one of six `HarnessError` subclasses
 (`continuo_python_runtime/errors.py`). The sentinel result block's message
 is prefixed `<ErrorClass>: ` so failures can be triaged without parsing free
 text. The harness also logs the same message at ERROR on stderr, with the
@@ -348,6 +388,7 @@ the result block out of the log before storing it.
 | Class | Meaning | Typical fix target |
 | --- | --- | --- |
 | `ContractError` | Contract missing or invalid, node not found for `NODE_ID`, or the declared script is missing/unreachable. | The contract yaml or the `script:` path. |
+| `ImageContractMismatch` (a `ContractError`) | The image does not hold the contract, script, imports or assets the release hashed: the `content_hash` in `CONTENT_HASH` differs from the one the image's files give, or a file the release hashed is missing from the image. The block also carries `"reason":"image_contract_mismatch"`. | Rebuild the image from the released commit, with CI and the image on the same runtime. |
 | `ReadError` | `ctx.read()` was called with an undeclared name, or a declared read failed at the warehouse. | The `reads:` map, or the upstream query/warehouse access. |
 | `ScriptError` | `run()` raised, has no callable `run`, or returned a value that isn't Arrow-convertible. | The node script. |
 | `ConformError` | Structural mismatch (extra/missing/duplicate columns), a strict-cast failure, a not-null violation, a VARCHAR/CHAR overflow, or an `upsert` run whose rows repeat a primary key. | The script's output shape, or the `output_columns` declaration. |
@@ -359,11 +400,11 @@ A domain repo picks its warehouse engine by which base image it builds
 `FROM`:
 
 ```dockerfile
-FROM ghcr.io/carolsimone/continuo-python-runtime-postgres:v0.11.0
+FROM ghcr.io/carolsimone/continuo-python-runtime-postgres:v0.12.0
 # or
-FROM ghcr.io/carolsimone/continuo-python-runtime-trino:v0.11.0
+FROM ghcr.io/carolsimone/continuo-python-runtime-trino:v0.12.0
 # or
-FROM ghcr.io/carolsimone/continuo-python-runtime-duckdb:v0.11.0
+FROM ghcr.io/carolsimone/continuo-python-runtime-duckdb:v0.12.0
 ```
 
 The engine is part of the image **name**; the tag is the bare version, so
@@ -402,6 +443,82 @@ 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.
 
+## Seed preflight and view probe
+
+Two validation ops read the warehouse and change nothing. They run through the
+same runner image as the other validation ops (`VALIDATION_OP`), need no
+`DBT_TARGET_SCHEMA`, and print one result block as the last line of stdout.
+
+A seed reload drops and recreates the seed's production table. On an engine where
+a drop destroys the objects that read the table (`drop_semantics` `cascade`,
+postgres) that takes every view, function and constraint built on the seed with
+it, including objects continuo does not own. On an engine where those objects
+survive and fail on their next read (`late_binding`, trino and duckdb) they
+may go stale. `seed_preflight` lists what a reload would touch and compares it
+with what the operator has allowed or acknowledged; `probe_views` tries named
+views after a reload and says which no longer bind.
+
+`seed_preflight` runs in two places. `check` runs in the seed task's own pod just
+before dbt and stops the reload with exit 1 when the check concludes it must.
+`report` runs in the release's seed-build Job and only reports what a `check`
+would conclude; it exits 0 whatever it finds.
+
+### `seed_preflight` inputs
+
+| Variable | Meaning |
+|---|---|
+| `SEED_PREFLIGHT_MODE` | `check` or `report`. |
+| `SEED_PREFLIGHT_ENGINE_FAMILY` | `schema_bound` or `late_binding`, the family the release plan expects of the engine. |
+| `PROD_SCHEMA`, `TABLE_NAME` | The seed's production relation. |
+| `SEED_PREFLIGHT_ALLOWED`, `SEED_PREFLIGHT_ACKNOWLEDGED` | JSON arrays of `"<schema>.<name>"`, default `[]`. An object is allowed when `<schema>.<name>`, in lower case, is in either list (entries are trimmed and lower-cased). |
+| `NODE_ID` | Optional; the block's `unique_id`. Default `<PROD_SCHEMA>.<TABLE_NAME>`. |
+
+The adapter's own variables (`POSTGRES_*`, `TRINO_*`, ...) are needed as for any
+other op. An adapter's family is `schema_bound` when its `drop_semantics` is
+`cascade`, and `late_binding` when it is `late_binding`.
+
+### `seed_preflight` block
+
+After the standard keys (and `reason` when one applies): `op` (`seed_preflight`),
+`mode`, `checked` (the warehouse was asked and its listing came back), `engine_family` (as given),
+`drop_semantics` (the adapter's), `completeness` (`exact`, `best_effort`, or
+`none` when nothing was listed) and `dependents`, a list of
+`{schema, name, kind, owner, depth, allowed}` sorted by depth, schema and name.
+`status` is `error` for exit codes 1 and 2, and `failures` is 1 then.
+
+`reason` is what a `check` concludes. `report` prints the same `reason` on a
+`success` block.
+
+| Situation | `reason` | `check` | `report` |
+|---|---|---|---|
+| a missing or malformed input, no adapter, missing adapter env | none | exit 2 | exit 2 |
+| the adapter's family differs from `SEED_PREFLIGHT_ENGINE_FAMILY`, or it declares none | `engine_mismatch` | exit 1 | exit 0 |
+| the adapter cannot list dependents, `schema_bound` | `unowned_dependents` | exit 1 | exit 0 |
+| the adapter cannot list dependents, `late_binding` | none | exit 0 | exit 0 |
+| the connection fails | `warehouse_unreachable` | exit 1 | exit 0 |
+| the listing fails, `schema_bound` | none | exit 1 | exit 0 |
+| the listing fails, `late_binding` | none | exit 0 | exit 0 |
+| listed, `schema_bound`, an object is not allowed | `unowned_dependents` | exit 1 | exit 0 |
+| anything else listed (on `late_binding` the objects not allowed are external views that may go stale, named in `message`) | none | exit 0 | exit 0 |
+
+A seed table that does not exist yet has no dependents and passes. A stop's
+`message` starts with its `reason` and names each object outside the set as
+`<schema>.<name> (<kind>, owner <owner>)`.
+
+### `probe_views`
+
+`PROBE_VIEWS` is a JSON array of `"<schema>.<name>"`, split on the first dot;
+`NODE_ID` is optional (default `probe_views`). Each view is read with
+`SELECT * FROM "<schema>"."<name>" LIMIT 0`. The block has `op`
+(`probe_views`), `checked` (the warehouse was reachable) and `views`, a list of
+`{schema, name, ok, error}` in the order given, where `error` is the first line
+of the failure, at most 500 characters, and empty when `ok`. A view that fails
+its probe never fails the op: the exit code is 0, and `message` reads
+`<n> of <total> views failed: <names>`. A warehouse that cannot be reached gives
+exit 0, `checked` false, `views` empty and `reason` `warehouse_unreachable`.
+Only a missing or malformed input, no adapter, missing adapter env or an
+unexpected error is exit 2.
+
 ## Further reading
 
 - `docs/superpowers/specs/2026-07-31-python-runtime-design.md` — this