continuo-python-runtime 0.1.0__tar.gz

continuo_python_runtime-0.1.0/.dockerignore

@@ -0,0 +1,14 @@
+.venv/
+.git/
+.superpowers/
+.idea/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+docs/
+template/
+tests/
+python-runtime-*/tests/

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

@@ -0,0 +1,25 @@
+name: ci
+on:
+  push: { branches: [main] }
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      # continuo-validation-contract resolves from PyPI (==0.3.0).
+      - name: Sync
+        run: uv sync --all-packages --all-groups
+      - name: Lint
+        run: uv run ruff check .
+      - name: Types (runtime)
+        run: uv run mypy continuo_python_runtime
+      - name: Types (postgres adapter)
+        run: uv run --package continuo-python-runtime-postgres mypy python-runtime-postgres/continuo_python_runtime_postgres
+      - name: Types (trino adapter)
+        run: uv run --package continuo-python-runtime-trino mypy python-runtime-trino/continuo_python_runtime_trino
+      - name: Tests (runtime)
+        run: uv run pytest --cov=continuo_python_runtime -v
+      - name: Tests (adapter units)
+        run: uv run pytest python-runtime-postgres/tests python-runtime-trino/tests -m "not integration" -v

continuo_python_runtime-0.1.0/.github/workflows/images.yml

@@ -0,0 +1,164 @@
+name: images
+on:
+  pull_request:
+    paths:
+      - "Dockerfile.*"
+      - "tests/smoke/**"
+      - "continuo_python_runtime/**"
+      - "python-runtime-postgres/**"
+      - "python-runtime-trino/**"
+      - "pyproject.toml"
+      - ".github/workflows/images.yml"
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        engine: [postgres, trino]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build ${{ matrix.engine }} image
+        run: docker build -f Dockerfile.${{ matrix.engine }} -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
+        with:
+          name: cpr-smoke-${{ matrix.engine }}-image
+          path: /tmp/cpr-smoke-${{ matrix.engine }}.tar
+          retention-days: 1
+
+  smoke-postgres:
+    needs: build
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: continuo
+          POSTGRES_PASSWORD: continuo
+          POSTGRES_DB: warehouse
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U continuo -d warehouse"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: cpr-smoke-postgres-image
+          path: /tmp
+      - name: Load image
+        run: docker load -i /tmp/cpr-smoke-postgres.tar
+      - name: Install psql client
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends postgresql-client
+      - name: Seed source table
+        env:
+          PGPASSWORD: continuo
+        run: |
+          psql -h localhost -U continuo -d warehouse -c \
+            "CREATE SCHEMA analytics; CREATE TABLE analytics.src(id int); INSERT INTO analytics.src VALUES (1),(2),(3);"
+      - name: Run smoke node
+        run: |
+          docker run --rm --network host \
+            -v "$PWD/tests/smoke/node_smoke:/app" \
+            -e NODE_ID=python-model.smoke.analytics.smoke \
+            -e TABLE_NAME=smoke \
+            -e TARGET_SCHEMA=analytics \
+            -e POSTGRES_HOST=localhost \
+            -e POSTGRES_PORT=5432 \
+            -e POSTGRES_DB=warehouse \
+            -e POSTGRES_USER=continuo \
+            -e POSTGRES_PASSWORD=continuo \
+            cpr-smoke-postgres | tee /tmp/smoke.out
+          test "${PIPESTATUS[0]}" -eq 0
+        shell: bash
+      - name: Assert success sentinel
+        run: grep -q '"status":"success"' /tmp/smoke.out
+      - name: Assert row count
+        env:
+          PGPASSWORD: continuo
+        run: |
+          count=$(psql -h localhost -U continuo -d warehouse -t -c "select count(*) from analytics.smoke" | tr -d '[:space:]')
+          test "$count" = "3"
+
+  smoke-trino:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: cpr-smoke-trino-image
+          path: /tmp
+      - name: Load image
+        run: docker load -i /tmp/cpr-smoke-trino.tar
+      - name: Start trino stack
+        run: docker compose -f tests/smoke/trino-stack/docker-compose.yml up -d --wait
+      - name: Seed source table
+        run: |
+          docker exec "$(docker compose -f tests/smoke/trino-stack/docker-compose.yml ps -q trino)" \
+            trino --execute "CREATE SCHEMA IF NOT EXISTS iceberg.analytics; CREATE TABLE iceberg.analytics.src(id int); INSERT INTO iceberg.analytics.src VALUES 1,2,3"
+      - name: Run smoke node
+        run: |
+          docker run --rm \
+            -v "$PWD/tests/smoke/node_smoke:/app" \
+            -e NODE_ID=python-model.smoke.analytics.smoke \
+            -e TABLE_NAME=smoke \
+            -e TARGET_SCHEMA=analytics \
+            -e TRINO_HOST=host.docker.internal \
+            -e TRINO_PORT=18080 \
+            -e TRINO_CATALOG=iceberg \
+            -e TRINO_USER=continuo \
+            --add-host=host.docker.internal:host-gateway \
+            cpr-smoke-trino | tee /tmp/smoke-trino.out
+          test "${PIPESTATUS[0]}" -eq 0
+        shell: bash
+      - name: Assert success sentinel
+        run: grep -q '"status":"success"' /tmp/smoke-trino.out
+      - name: Assert row count
+        run: |
+          count=$(docker exec "$(docker compose -f tests/smoke/trino-stack/docker-compose.yml ps -q trino)" \
+            trino --execute "select count(*) from iceberg.analytics.smoke" | tr -d '[:space:]"')
+          test "$count" = "3"
+      - name: Tear down trino stack
+        if: always()
+        run: docker compose -f tests/smoke/trino-stack/docker-compose.yml down -v
+
+  # On tag push: log in to ghcr.io and push ghcr.io/${{ github.repository }}:<tag>-postgres
+  # and :<tag>-trino. continuo-validation-contract, continuo-python-runtime-postgres,
+  # and continuo-python-runtime-trino are all installed from the build context /
+  # PyPI already (see Dockerfile.postgres / Dockerfile.trino and
+  # publish-pypi.yml) — nothing pending here.
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [smoke-postgres, smoke-trino]
+    strategy:
+      matrix:
+        engine: [postgres, trino]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Log in to ghcr.io
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build and push ${{ matrix.engine }} image
+        run: |
+          tag="${GITHUB_REF_NAME}"
+          image="ghcr.io/${{ github.repository }}:${tag}-${{ matrix.engine }}"
+          docker build -f Dockerfile.${{ matrix.engine }} -t "$image" .
+          docker push "$image"

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

@@ -0,0 +1,129 @@
+name: publish-pypi
+
+# Publishes the continuo-python-runtime package (and, in the two adapter jobs
+# below, the continuo-python-runtime-postgres / continuo-python-runtime-trino
+# packages) via PyPI Trusted Publishing (OIDC, no stored token).
+#
+# Tag glob note: "python-runtime-v*" requires a literal "v" immediately after
+# the dash, so it matches only the harness tag (python-runtime-v1.2.3[-testN])
+# and never "python-runtime-postgres-v*" / "python-runtime-trino-v*" (whose
+# char after the shared "python-runtime-" prefix is "p"/"t", not "v") — the
+# three globs are disjoint, so none of the three jobs below shadows another.
+# Tag `<pkg>-v<ver>-test<n>` publishes to TestPyPI; `<pkg>-v<ver>` publishes to
+# real PyPI. The GitHub environment name is what each PyPI "pending publisher"
+# is registered against.
+#
+# Ordering: continuo-validation-contract==0.3.0 must exist on the target index
+# before publishing here — consumers of the wheel resolve it from that index
+# ([tool.uv.sources] is dev-only and not embedded in the wheel).
+on:
+  push:
+    tags:
+      - "python-runtime-v*"
+      - "python-runtime-postgres-v*"
+      - "python-runtime-trino-v*"
+
+permissions: {}
+
+jobs:
+  publish-runtime:
+    if: startsWith(github.ref_name, 'python-runtime-v')
+    runs-on: ubuntu-latest
+    environment: ${{ contains(github.ref_name, '-test') && 'testpypi' || 'pypi' }}
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing
+      contents: read # actions/checkout needs read access to the repo
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Test before publishing
+        run: |
+          uv sync --all-groups
+          uv run pytest -q
+      - name: Build the sdist + wheel
+        run: uv build -o dist
+      - name: Publish to TestPyPI
+        if: contains(github.ref_name, '-test')
+        # Pinned to a commit SHA. release/v1 is a moving branch, and this job
+        # holds id-token: write for PyPI Trusted Publishing — a compromised
+        # revision could mint a token and publish under this project's name.
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist
+      - name: Publish to PyPI
+        if: ${{ !contains(github.ref_name, '-test') }}
+        # Pinned to a commit SHA. release/v1 is a moving branch, and this job
+        # holds id-token: write for PyPI Trusted Publishing — a compromised
+        # revision could mint a token and publish under this project's name.
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: dist
+
+  publish-runtime-postgres:
+    if: startsWith(github.ref_name, 'python-runtime-postgres-v')
+    runs-on: ubuntu-latest
+    environment: ${{ contains(github.ref_name, '-test') && 'testpypi-postgres' || 'pypi-postgres' }}
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing
+      contents: read # actions/checkout needs read access to the repo
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Test before publishing
+        run: |
+          uv sync --all-packages --all-groups
+          uv run pytest python-runtime-postgres/tests -m "not integration" -q
+      - name: Build the sdist + wheel
+        run: uv build --package continuo-python-runtime-postgres python-runtime-postgres -o dist
+      - name: Publish to TestPyPI
+        if: contains(github.ref_name, '-test')
+        # Pinned to a commit SHA. release/v1 is a moving branch, and this job
+        # holds id-token: write for PyPI Trusted Publishing — a compromised
+        # revision could mint a token and publish under this project's name.
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist
+      - name: Publish to PyPI
+        if: ${{ !contains(github.ref_name, '-test') }}
+        # Pinned to a commit SHA. release/v1 is a moving branch, and this job
+        # holds id-token: write for PyPI Trusted Publishing — a compromised
+        # revision could mint a token and publish under this project's name.
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: dist
+
+  publish-runtime-trino:
+    if: startsWith(github.ref_name, 'python-runtime-trino-v')
+    runs-on: ubuntu-latest
+    environment: ${{ contains(github.ref_name, '-test') && 'testpypi-trino' || 'pypi-trino' }}
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing
+      contents: read # actions/checkout needs read access to the repo
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Test before publishing
+        run: |
+          uv sync --all-packages --all-groups
+          uv run pytest python-runtime-trino/tests -m "not integration" -q
+      - name: Build the sdist + wheel
+        run: uv build --package continuo-python-runtime-trino python-runtime-trino -o dist
+      - name: Publish to TestPyPI
+        if: contains(github.ref_name, '-test')
+        # Pinned to a commit SHA. release/v1 is a moving branch, and this job
+        # holds id-token: write for PyPI Trusted Publishing — a compromised
+        # revision could mint a token and publish under this project's name.
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist
+      - name: Publish to PyPI
+        if: ${{ !contains(github.ref_name, '-test') }}
+        # Pinned to a commit SHA. release/v1 is a moving branch, and this job
+        # holds id-token: write for PyPI Trusted Publishing — a compromised
+        # revision could mint a token and publish under this project's name.
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: dist

continuo_python_runtime-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.idea/
+.DS_Store
+__pycache__/
+.venv/
+dist/
+.superpowers/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

continuo_python_runtime-0.1.0/Dockerfile.postgres

@@ -0,0 +1,13 @@
+FROM python:3.14-slim
+# Until the runtime and adapter packages publish to (Test)PyPI, install both
+# from the build context; the contract from PyPI.
+COPY pyproject.toml README.md /src/
+COPY continuo_python_runtime /src/continuo_python_runtime
+COPY python-runtime-postgres /src/python-runtime-postgres
+RUN pip install --no-cache-dir \
+      "continuo-validation-contract==0.3.0" \
+      /src/python-runtime-postgres \
+      /src
+ENV CONTRACT_DIR=/app/contracts APP_ROOT=/app
+WORKDIR /app
+ENTRYPOINT ["continuo-runtime", "run"]

continuo_python_runtime-0.1.0/Dockerfile.trino

@@ -0,0 +1,13 @@
+FROM python:3.14-slim
+# Until the runtime and adapter packages publish to (Test)PyPI, install both
+# from the build context; the contract from PyPI.
+COPY pyproject.toml README.md /src/
+COPY continuo_python_runtime /src/continuo_python_runtime
+COPY python-runtime-trino /src/python-runtime-trino
+RUN pip install --no-cache-dir \
+      "continuo-validation-contract==0.3.0" \
+      /src/python-runtime-trino \
+      /src
+ENV CONTRACT_DIR=/app/contracts APP_ROOT=/app
+WORKDIR /app
+ENTRYPOINT ["continuo-runtime", "run"]

continuo_python_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: continuo-python-runtime
+Version: 0.1.0
+Summary: Runtime harness, contract tooling, and CI lint for Continuo python nodes.
+Author: Simone Carolini
+Maintainer: Simone Carolini
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: continuo-validation-contract==0.3.0
+Requires-Dist: pyarrow==25.0.0
+Requires-Dist: pyyaml==6.0.3
+Description-Content-Type: text/markdown
+
+# Continuo Python Runtime
+
+Runtime harness, contract tooling, and CI lint for Continuo python nodes.
+This repo is what domain data teams (marketing, finance, …) template from to
+ship a python node into Continuo: write a contract + a `run(ctx)` script,
+push to `main`, and CI does the rest — lint, validate, merge, build, publish,
+and register the release with Continuo.
+
+## What this repo is
+
+Three artifacts come out of this repository:
+
+- **The `continuo-python-runtime` PyPI package** — the `continuo-runtime` CLI
+  (`validate` / `merge` / `hash` / `lint` / `run`) and the harness library
+  (`conform()`, `RunContext`, the error taxonomy) that domain repos install.
+- **Per-engine base images**, one per warehouse engine (`...-postgres`,
+  `...-trino`), that domain repos build `FROM`. Each image bakes in the
+  runtime, a single `RuntimeAdapter` for that engine, and the
+  `continuo-runtime run` entrypoint.
+- **`template/`** — a copy-ready domain repo: `Dockerfile`, `contracts/`,
+  `scripts/`, and the `release.yml` CI/CD workflow.
+
+Base images and the PyPI publication of this package land with this repo's
+PR 9 (the image pipeline); until then, install the runtime from git as noted
+in `template/.github/workflows/release.yml`.
+
+### Package map
+
+Each per-engine base image bakes together three PyPI packages: the harness,
+the engine adapter, and the published contract. The harness and both engine
+adapters live in *this* repo (`continuo-python-runtime`) as a uv workspace;
+`continuo-validation-runners` owns the *validation-side* (offline lint/merge)
+counterparts of the same engines, which is a separate concern from the
+data-plane adapters here.
+
+| Package (distribution name) | Module | Lives in | Role |
+| --- | --- | --- | --- |
+| `continuo-python-runtime` | `continuo_python_runtime` | this repo (root) | Harness: CLI, `conform()`, `RunContext`, error taxonomy. |
+| `continuo-python-runtime-postgres` | `continuo_python_runtime_postgres` | this repo, `python-runtime-postgres/` | Data-plane `RuntimeAdapter` for Postgres (`fetch`/`ensure_table`/`load`). |
+| `continuo-python-runtime-trino` | `continuo_python_runtime_trino` | this repo, `python-runtime-trino/` | Data-plane `RuntimeAdapter` for Trino/Iceberg. |
+| `continuo-validation-contract` | `continuo_validation_contract` | `continuo-validation-runners` | The published contract (schema, `RuntimeAdapter` port, result-block format) both sides depend on. |
+| `continuo-validation-postgres` / `continuo-validation-trino` | `continuo_validation_postgres` / `continuo_validation_trino` | `continuo-validation-runners` | Validation-side (lint/merge, no live warehouse I/O) adapters — not to be confused with the data-plane adapters above. |
+
+All three packages built in this repo resolve `continuo-validation-contract`
+from PyPI (`==0.3.0`); the two adapter packages are uv workspace members
+(`[tool.uv.workspace]` in the root `pyproject.toml`), so `uv sync
+--all-packages --all-groups` at the repo root installs everything for local
+development.
+
+## Quickstart for domain teams
+
+1. Copy `template/` into a new repository.
+2. Edit `template/.github/workflows/release.yml` and set `SERVICE` to your
+   service name (one service name per domain repo).
+3. Configure repository variables in GitHub (Settings → Secrets and
+   variables → Actions): `REGISTRY` (your Docker registry), `BUCKET` (your
+   S3 bucket for contract artifacts), `RELEASE_ENDPOINT` (the release
+   webhook endpoint). `RELEASE_ENDPOINT` is the **base URL** of the Continuo
+   API (no `/releases` suffix) — the workflow appends `/releases` itself.
+4. Configure repository secrets: `AWS_ACCESS_KEY_ID` and
+   `AWS_SECRET_ACCESS_KEY` for the S3 upload. The template workflow pushes
+   the built image to GHCR using the workflow's own `GITHUB_TOKEN` (granted
+   `packages: write`) — no registry secret is needed for that. If you point
+   `REGISTRY` at a different or private registry, add your own `docker
+   login` step to `release.yml`.
+5. Write a contract file under `contracts/` (see
+   `template/contracts/example.yml`) and a script under `scripts/` that
+   implements `run(ctx)` (see `template/scripts/example.py`).
+6. Push to `main`. The `release.yml` workflow lints the scripts, validates
+   and merges the contracts, builds and pushes the image, uploads the merged
+   contract to S3, and POSTs the release.
+
+## The script API
+
+A node script is a Python file with exactly one required entry point:
+
+```python
+def run(ctx):
+    ...
+```
+
+- `ctx` is a `RunContext` (`continuo_python_runtime.context.RunContext`).
+  Its only method is `ctx.read(name)`, where `name` is one of the read
+  names declared under the node's `reads:` map in the contract — reading
+  anything else raises `ReadError`. Each declared read is fetched once and
+  memoized; `ctx.read(name)` returns a `pyarrow.Table`.
+- `run(ctx)` can return anything Arrow-convertible: a `pyarrow.Table`
+  as-is, a pandas `DataFrame` (converted via
+  `pa.Table.from_pandas(..., preserve_index=False)`), or any object
+  implementing the Arrow C stream protocol (`__arrow_c_stream__`) — for
+  example a polars DataFrame. Returning anything else raises `ScriptError`.
+- The dataframe library is your choice. No dataframe library is baked into
+  the base image — the package's own runtime dependencies are `pyarrow`,
+  `PyYAML`, and `continuo-validation-contract`. Add whatever you script
+  against (pandas, polars, …) as a `RUN pip install` line in your own
+  `Dockerfile`, on top of the base image.
+- Scripts do not import warehouse drivers, write raw SQL literals, or call
+  data-access methods directly — `continuo-runtime lint` rejects those:
+  - forbidden driver imports (`psycopg2`/`sqlalchemy`/`trino`/etc.),
+  - SQL string literals (in plain strings, f-strings, and `+` concatenation),
+  - forbidden data-access calls (`execute`/`read_sql`/etc.), including ones
+    reached via a `from ... import` alias (e.g. `from pandas import
+    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.
+
+  The SQL-literal rule is best-effort: docstrings are exempt, but other
+  prose may still occasionally match. The hard guarantees enforced by lint
+  are the driver-import and data-access-call rules, together with the fact
+  that `RunContext` only exposes `ctx.read()` — all warehouse access goes
+  through it.
+- The harness — not the script — performs the write. It calls `conform()`
+  on whatever `run()` returned and issues the only INSERT; the script never
+  writes directly.
+
+## Conform rules
+
+`conform()` (`continuo_python_runtime/conform.py`) enforces the node's
+declared `output_columns` on the table `run()` returned, in this order:
+
+| Check | Behavior |
+| --- | --- |
+| Duplicate columns | Any duplicate column name in the returned table always raises `ConformError`. |
+| Extra columns | Governed by the node's `extra_columns` policy: `raise` (default) fails the run; `warn` drops the undeclared column(s) and logs a warning. |
+| Missing columns | Any declared column absent from the returned table always raises `ConformError`. |
+| Column order | The table is reselected into the declared column order. |
+| Strict cast | Each column is cast to its declared Arrow type with `safe=True`. Casts pyarrow's `safe=True` would silently accept but that are not value-lossless are rejected before the cast even runs: floating → decimal (rounds to scale), non-boolean → boolean (coerces truthiness), timestamp → date (drops time-of-day). Any other cast failure also raises `ConformError`. |
+| Not-null | A column declared `nullable: false` that contains any null raises `ConformError`. |
+| VARCHAR/CHAR length | A column declared `VARCHAR(n)`/`CHAR(n)` whose longest value exceeds `n` raises `ConformError`. |
+
+## Error taxonomy
+
+Every runtime failure is one of five `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.
+
+| 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. |
+| `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, or a VARCHAR/CHAR overflow. | The script's output shape, or the `output_columns` declaration. |
+| `LoadError` | Adapter construction failed, or the DDL/INSERT failed at the warehouse during the write. | Warehouse connectivity/permissions, or the target table. |
+
+## Engine selection
+
+A domain repo picks its warehouse engine by which base image it builds
+`FROM`:
+
+```dockerfile
+FROM ghcr.io/carolsimone/continuo-python-runtime:v0.1.0-postgres
+# or
+FROM ghcr.io/carolsimone/continuo-python-runtime:v0.1.0-trino
+```
+
+Each image bakes in exactly one `RuntimeAdapter` for that engine — installed
+from this repo's `python-runtime-postgres/` or `python-runtime-trino/`
+package (see the package map above; both adapters live in this repo, not
+`continuo-validation-runners`) — registered under the
+`continuo_runtime.adapters` entry-point group (entry names `postgres` /
+`trino`). The harness discovers it via `discover_runtime_adapter()` at run
+time, so a single image serves every node in the service. The executor
+injects the
+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.
+
+## Further reading
+
+- `docs/superpowers/specs/2026-07-31-python-runtime-design.md` — this
+  repo's design.
+- `docs/boundary-contract.md` — the parent design's boundary contract (§13):
+  the five surfaces (S3 artifact, `content_hash`, the release call, the
+  runtime image, and the domain repo's CI/CD) that this repo implements.