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

{continuo_python_runtime-0.1.0 → continuo_python_runtime-0.2.0}/.github/workflows/ci.yml

@@ -8,7 +8,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v5
-      # continuo-validation-contract resolves from PyPI (==0.3.0).
+      # continuo-validation-contract resolves from PyPI (==0.4.0).
       - name: Sync
         run: uv sync --all-packages --all-groups
       - name: Lint

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

@@ -0,0 +1,65 @@
+name: publish-pypi
+
+# Publishes the continuo-python-runtime package via PyPI Trusted Publishing
+# (OIDC, no stored token).
+#
+# The two engine adapters (continuo-python-runtime-postgres /
+# continuo-python-runtime-trino) are deliberately NOT published here. Nothing
+# installs them from an index: the runtime images build them from the build
+# context (see Dockerfile.postgres / Dockerfile.trino and images.yml), and the
+# harness package does not depend on them — adapters are found at run time
+# through the `continuo_runtime.adapters` entry-point group, inside the image
+# that installed exactly one. Publishing them would only add releases with no
+# consumer. They remain uv workspace members and are still built, typed, and
+# tested by ci.yml.
+#
+# Tag glob note: "python-runtime-v*" requires a literal "v" immediately after
+# the dash, so it matches only the harness tag (python-runtime-v1.2.3[-testN]).
+# Tag `<pkg>-v<ver>-test<n>` publishes to TestPyPI; `<pkg>-v<ver>` publishes to
+# real PyPI. The GitHub environment name is what the PyPI "pending publisher"
+# is registered against.
+#
+# Ordering: continuo-validation-contract==0.4.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*"
+
+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

{continuo_python_runtime-0.1.0 → continuo_python_runtime-0.2.0}/Dockerfile.postgres

@@ -5,9 +5,13 @@ 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" \
+      "continuo-validation-contract==0.4.0" \
       /src/python-runtime-postgres \
       /src
-ENV CONTRACT_DIR=/app/contracts APP_ROOT=/app
+# 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,
+# so a script's in-repo helper imports resolve. Neither WORKDIR nor the
+# console-script entrypoint puts /app on sys.path by itself.
+ENV CONTRACT_DIR=/app/contracts APP_ROOT=/app PYTHONPATH=/app
 WORKDIR /app
 ENTRYPOINT ["continuo-runtime", "run"]

{continuo_python_runtime-0.1.0 → continuo_python_runtime-0.2.0}/Dockerfile.trino

@@ -5,9 +5,13 @@ 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" \
+      "continuo-validation-contract==0.4.0" \
       /src/python-runtime-trino \
       /src
-ENV CONTRACT_DIR=/app/contracts APP_ROOT=/app
+# 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,
+# so a script's in-repo helper imports resolve. Neither WORKDIR nor the
+# console-script entrypoint puts /app on sys.path by itself.
+ENV CONTRACT_DIR=/app/contracts APP_ROOT=/app PYTHONPATH=/app
 WORKDIR /app
 ENTRYPOINT ["continuo-runtime", "run"]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: continuo-python-runtime
-Version: 0.1.0
+Version: 0.2.0
 Summary: Runtime harness, contract tooling, and CI lint for Continuo python nodes.
 Author: Simone Carolini
 Maintainer: Simone Carolini
@@ -8,9 +8,10 @@ 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: continuo-validation-contract==0.4.0
 Requires-Dist: pyarrow==25.0.0
 Requires-Dist: pyyaml==6.0.3
+Requires-Dist: sqlglot==30.15.0
 Description-Content-Type: text/markdown
 
 # Continuo Python Runtime
@@ -51,17 +52,26 @@ 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-python-runtime-postgres` | `continuo_python_runtime_postgres` | this repo, `python-runtime-postgres/` | Data-plane `RuntimeAdapter` for Postgres (`fetch`/`ensure_table`/`load`). **Not published to PyPI** — built from source into the image. |
+| `continuo-python-runtime-trino` | `continuo_python_runtime_trino` | this repo, `python-runtime-trino/` | Data-plane `RuntimeAdapter` for Trino/Iceberg. **Not published to PyPI** — built from source into the image. |
 | `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
+from PyPI (`==0.4.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.
 
+**Only `continuo-python-runtime` is published to PyPI.** The two engine
+adapters are built **from source into the runtime images**: `Dockerfile.postgres`
+and `Dockerfile.trino` `pip install` them out of the build context, so each
+image ships exactly one adapter and the harness discovers it through the
+`continuo_runtime.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.
+
 ## Quickstart for domain teams
 
 1. Copy `template/` into a new repository.
@@ -85,6 +95,28 @@ development.
    and merges the contracts, builds and pushes the image, uploads the merged
    contract to S3, and POSTs the release.
 
+### Upgrading an existing domain repo
+
+`validate` / `merge` / `hash` now hand every declared read to a real SQL
+parser (sqlglot, via `continuo_validation_contract.sql.ensure_single_read`)
+instead of scanning it for a leading `SELECT`/`WITH`. Two things follow for a
+repo written before this, on its next release: SQL a driver would accept but
+a parser will not — most commonly a driver-specific bind placeholder like
+psycopg2's `%(name)s`, which `ctx.read(name)` could never have used anyway —
+now fails validation, and engine-specific syntax (postgres `~`, `@>`, …)
+needs `--dialect <engine>`, which a repo should be passing regardless since
+Continuo bind-checks every read in the install's own warehouse dialect. Run
+the pre-flight check once before your next release; it reports every affected
+read at once:
+
+```bash
+continuo-runtime validate contracts/ --dialect postgres   # or trino
+```
+
+The runtime image does not re-run this gate, so a read that passes here is
+not re-judged under a different grammar in production. See
+`docs/boundary-contract.md` §13.1.
+
 ## The script API
 
 A node script is a Python file with exactly one required entry point:
@@ -125,6 +157,17 @@ def run(ctx):
   are the driver-import and data-access-call rules, together with the fact
   that `RunContext` only exposes `ctx.read()` — all warehouse access goes
   through it.
+- Scripts may import shared in-repo helpers. Before executing a script the
+  harness puts the repo root (`APP_ROOT`) and the script's own directory on
+  `sys.path`, so both `import helpers` (a sibling of the script) and
+  `from lib.shared import ...` (anywhere under the repo root) work, including
+  from inside `run()`. Every helper a script reaches transitively is folded
+  into `shared_code_hash`, so editing one re-fingerprints the node — but the
+  hash does not put the file in the image: **`COPY` every directory your
+  scripts import from in your `Dockerfile`**, or the release is valid and the
+  node dies with `ModuleNotFoundError` on its first run. Because the repo root
+  precedes the standard library on `sys.path`, avoid naming a top-level module
+  after a stdlib one (`types.py`, `json.py`, `logging.py`, …).
 - The harness — not the script — performs the write. It calls `conform()`
   on whatever `run()` returned and issues the only INSERT; the script never
   writes directly.
@@ -165,9 +208,9 @@ A domain repo picks its warehouse engine by which base image it builds
 `FROM`:
 
 ```dockerfile
-FROM ghcr.io/carolsimone/continuo-python-runtime:v0.1.0-postgres
+FROM ghcr.io/carolsimone/continuo-python-runtime:v0.2.0-postgres
 # or
-FROM ghcr.io/carolsimone/continuo-python-runtime:v0.1.0-trino
+FROM ghcr.io/carolsimone/continuo-python-runtime:v0.2.0-trino
 ```
 
 Each image bakes in exactly one `RuntimeAdapter` for that engine — installed

{continuo_python_runtime-0.1.0 → continuo_python_runtime-0.2.0}/README.md

@@ -36,17 +36,26 @@ 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-python-runtime-postgres` | `continuo_python_runtime_postgres` | this repo, `python-runtime-postgres/` | Data-plane `RuntimeAdapter` for Postgres (`fetch`/`ensure_table`/`load`). **Not published to PyPI** — built from source into the image. |
+| `continuo-python-runtime-trino` | `continuo_python_runtime_trino` | this repo, `python-runtime-trino/` | Data-plane `RuntimeAdapter` for Trino/Iceberg. **Not published to PyPI** — built from source into the image. |
 | `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
+from PyPI (`==0.4.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.
 
+**Only `continuo-python-runtime` is published to PyPI.** The two engine
+adapters are built **from source into the runtime images**: `Dockerfile.postgres`
+and `Dockerfile.trino` `pip install` them out of the build context, so each
+image ships exactly one adapter and the harness discovers it through the
+`continuo_runtime.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.
+
 ## Quickstart for domain teams
 
 1. Copy `template/` into a new repository.
@@ -70,6 +79,28 @@ development.
    and merges the contracts, builds and pushes the image, uploads the merged
    contract to S3, and POSTs the release.
 
+### Upgrading an existing domain repo
+
+`validate` / `merge` / `hash` now hand every declared read to a real SQL
+parser (sqlglot, via `continuo_validation_contract.sql.ensure_single_read`)
+instead of scanning it for a leading `SELECT`/`WITH`. Two things follow for a
+repo written before this, on its next release: SQL a driver would accept but
+a parser will not — most commonly a driver-specific bind placeholder like
+psycopg2's `%(name)s`, which `ctx.read(name)` could never have used anyway —
+now fails validation, and engine-specific syntax (postgres `~`, `@>`, …)
+needs `--dialect <engine>`, which a repo should be passing regardless since
+Continuo bind-checks every read in the install's own warehouse dialect. Run
+the pre-flight check once before your next release; it reports every affected
+read at once:
+
+```bash
+continuo-runtime validate contracts/ --dialect postgres   # or trino
+```
+
+The runtime image does not re-run this gate, so a read that passes here is
+not re-judged under a different grammar in production. See
+`docs/boundary-contract.md` §13.1.
+
 ## The script API
 
 A node script is a Python file with exactly one required entry point:
@@ -110,6 +141,17 @@ def run(ctx):
   are the driver-import and data-access-call rules, together with the fact
   that `RunContext` only exposes `ctx.read()` — all warehouse access goes
   through it.
+- Scripts may import shared in-repo helpers. Before executing a script the
+  harness puts the repo root (`APP_ROOT`) and the script's own directory on
+  `sys.path`, so both `import helpers` (a sibling of the script) and
+  `from lib.shared import ...` (anywhere under the repo root) work, including
+  from inside `run()`. Every helper a script reaches transitively is folded
+  into `shared_code_hash`, so editing one re-fingerprints the node — but the
+  hash does not put the file in the image: **`COPY` every directory your
+  scripts import from in your `Dockerfile`**, or the release is valid and the
+  node dies with `ModuleNotFoundError` on its first run. Because the repo root
+  precedes the standard library on `sys.path`, avoid naming a top-level module
+  after a stdlib one (`types.py`, `json.py`, `logging.py`, …).
 - The harness — not the script — performs the write. It calls `conform()`
   on whatever `run()` returned and issues the only INSERT; the script never
   writes directly.
@@ -150,9 +192,9 @@ A domain repo picks its warehouse engine by which base image it builds
 `FROM`:
 
 ```dockerfile
-FROM ghcr.io/carolsimone/continuo-python-runtime:v0.1.0-postgres
+FROM ghcr.io/carolsimone/continuo-python-runtime:v0.2.0-postgres
 # or
-FROM ghcr.io/carolsimone/continuo-python-runtime:v0.1.0-trino
+FROM ghcr.io/carolsimone/continuo-python-runtime:v0.2.0-trino
 ```
 
 Each image bakes in exactly one `RuntimeAdapter` for that engine — installed

{continuo_python_runtime-0.1.0 → continuo_python_runtime-0.2.0}/continuo_python_runtime/cli.py

@@ -30,11 +30,17 @@ def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="continuo-runtime")
     subparsers = parser.add_subparsers(dest="command", required=True)
 
+    dialect_help = (
+        "sqlglot dialect the reads are authored in (e.g. postgres, trino); "
+        "defaults to sqlglot's dialect-neutral parser."
+    )
+
     # validate subcommand
     validate_parser = subparsers.add_parser(
         "validate", help="Validate contract directory"
     )
     validate_parser.add_argument("contract_dir", help="Path to contract directory")
+    validate_parser.add_argument("--dialect", default=None, help=dialect_help)
 
     # merge subcommand
     merge_parser = subparsers.add_parser(
@@ -44,6 +50,7 @@ def main(argv: list[str] | None = None) -> int:
     merge_parser.add_argument("--service", required=True, help="Service name")
     merge_parser.add_argument("--repo-root", required=True, help="Repository root path")
     merge_parser.add_argument("--out", required=True, help="Output file path")
+    merge_parser.add_argument("--dialect", default=None, help=dialect_help)
 
     # hash subcommand
     hash_parser = subparsers.add_parser(
@@ -53,6 +60,7 @@ def main(argv: list[str] | None = None) -> int:
     hash_parser.add_argument(
         "--repo-root", required=True, help="Repository root path"
     )
+    hash_parser.add_argument("--dialect", default=None, help=dialect_help)
 
     # lint subcommand
     lint_parser = subparsers.add_parser(
@@ -69,11 +77,13 @@ def main(argv: list[str] | None = None) -> int:
 
     try:
         if args.command == "validate":
-            return cmd_validate(args.contract_dir)
+            return cmd_validate(args.contract_dir, args.dialect)
         elif args.command == "merge":
-            return cmd_merge(args.contract_dir, args.service, args.repo_root, args.out)
+            return cmd_merge(
+                args.contract_dir, args.service, args.repo_root, args.out, args.dialect
+            )
         elif args.command == "hash":
-            return cmd_hash(args.contract_dir, args.repo_root)
+            return cmd_hash(args.contract_dir, args.repo_root, args.dialect)
         elif args.command == "lint":
             return cmd_lint(args.path)
         elif args.command == "run":
@@ -88,27 +98,35 @@ def main(argv: list[str] | None = None) -> int:
     return 0
 
 
-def cmd_validate(contract_dir: str) -> int:
+def cmd_validate(contract_dir: str, dialect: str | None = None) -> int:
     """Validate contracts in a directory."""
-    load_contract_dir(Path(contract_dir))
+    load_contract_dir(Path(contract_dir), dialect=dialect)
     return 0
 
 
-def cmd_merge(contract_dir: str, service: str, repo_root: str, out: str) -> int:
+def cmd_merge(
+    contract_dir: str,
+    service: str,
+    repo_root: str,
+    out: str,
+    dialect: str | None = None,
+) -> int:
     """Merge contracts into a wire contract file."""
-    doc = build_wire_contract(Path(contract_dir), Path(repo_root), service)
+    doc = build_wire_contract(Path(contract_dir), Path(repo_root), service, dialect=dialect)
     write_wire_contract(doc, Path(out))
     return 0
 
 
-def cmd_hash(contract_dir: str, repo_root: str) -> int:
+def cmd_hash(contract_dir: str, repo_root: str, dialect: str | None = None) -> int:
     """Print relation and content hash for each node.
 
     Reuses build_wire_contract for consistent hashing and error handling.
     Service value is irrelevant to per-node hashes since entries don't include it.
     """
     # Reuse build_wire_contract for consistent hashing and error handling
-    doc = build_wire_contract(Path(contract_dir), Path(repo_root), service="_hash")
+    doc = build_wire_contract(
+        Path(contract_dir), Path(repo_root), service="_hash", dialect=dialect
+    )
 
     # Print relation\thash from wire contract nodes (already sorted by relation)
     for node_entry in doc["nodes"]:

continuo_python_runtime-0.2.0/continuo_python_runtime/closure.py

@@ -0,0 +1,268 @@
+"""Static in-repo import-closure resolver.
+
+CI's ``content_hash`` is the sole change detector Continuo uses to decide
+whether a node needs revalidation. Until this module existed, that hash
+covered only the node's own script file, so a byte edit to a shared helper
+module the script imports changed nothing — the node kept running against a
+stale fingerprint in production. ``resolve_closure`` closes that gap: it
+returns the transitive set of in-repo Python files a script reaches through
+its ``import`` statements, so a later stage can fold their bytes into the
+hash too.
+
+That framing decides every ambiguous call in the algorithm below:
+under-inclusion is a correctness bug (a stale node silently running in
+production), while over-inclusion is merely a spurious revalidation.
+
+- Search roots (rule 4) are the fixed, ordered pair ``(repo_root,
+  script_dir)`` — ``script_dir`` computed once from the seed script and
+  reused, unchanged, for every resolution in the traversal, never the
+  current file's own directory. This mirrors
+  :func:`continuo_python_runtime.harness.ensure_import_paths` exactly, which
+  puts that same pair on ``sys.path`` for the process lifetime: the static
+  model and the runtime model are provably the same list. A module importing
+  a sibling that is on neither root (e.g. ``lib/shared.py`` doing ``import
+  sibling`` for a file at ``lib/sibling.py``, when the script itself lives
+  elsewhere) raises ``ImportError`` at run time, so excluding that sibling
+  from the closure cannot hide a stale-node bug — that node cannot run at
+  all. When the script lives at ``repo_root`` itself, the pair collapses to
+  a single root so the same candidate is not probed twice.
+- Within a search root, the package form (``<root>/a/b/c/__init__.py``) is
+  tried before the module-file form (``<root>/a/b/c.py``), matching
+  Python's own lookup order: when both exist, ``import a.b.c`` binds the
+  package, and the module file of the same name is never executed.
+- ``from pkg import name`` (rule 3) is expanded to include both ``pkg`` and
+  ``pkg.name`` as candidate dotted names, because ``name`` may be a
+  submodule (a file) rather than an attribute of ``pkg`` — the two are
+  indistinguishable from the import statement's syntax alone. The same
+  applies to relative imports: ``from . import name`` always includes the
+  bare enclosing package as a candidate too, not only when the import also
+  names a submodule (``from .mod import name``) — real Python executes the
+  package's ``__init__.py`` either way, so treating the two forms
+  asymmetrically would under-include exactly the file this module exists to
+  stop missing. This choice leans deliberately toward over-inclusion:
+  ``name`` may turn out to be a plain attribute rather than a submodule, in
+  which case the extra candidate simply fails to resolve.
+
+Dynamic-import constructs (``importlib``, ``builtins``, ``__builtins__``,
+``__import__``, ``exec``, ``eval``, ``.import_module``) are rejected outright
+rather than degrading to "resolve what we can": whatever a script imports
+through one of those, this static analysis cannot see, so the hash could
+never be trusted to reflect it.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections import deque
+from pathlib import Path
+
+from continuo_python_runtime.errors import ContractError
+
+_DYNAMIC_IMPORT_MODULES = frozenset({"importlib", "builtins"})
+_DYNAMIC_IMPORT_NAMES = frozenset({"__import__", "exec", "eval", "__builtins__"})
+_DYNAMIC_IMPORT_ATTRS = frozenset({"import_module", "__import__"})
+
+
+def dynamic_import_violations(tree: ast.AST) -> list[tuple[int, str]]:
+    """Return `(lineno, construct)` for every dynamic-import construct in *tree*.
+
+    Flags, per AST node type:
+
+    - `ast.Import`: any alias whose root module (`name.split(".")[0]`) is
+      `importlib` or `builtins` — e.g. `import importlib.util`, `import
+      builtins`. `construct` is that root module name.
+    - `ast.ImportFrom`: if the root module is `importlib` or `builtins`,
+      one violation naming that module — and nothing else from the same
+      statement (one statement, one violation; its aliases are not also
+      inspected). Otherwise, any `alias.name` in `{"__import__", "exec",
+      "eval"}` is a violation named for that alias — this catches
+      re-exports of those names from a module that is neither `importlib`
+      nor `builtins` (e.g. `from somewhere import exec as e`), which no
+      other rule here would see.
+    - `ast.Name`: `id` in `{"__import__", "exec", "eval", "__builtins__"}` (a
+      bare reference or call). `__builtins__` is included because it is
+      injected into every module's globals by the harness's own loader
+      (`spec_from_file_location` + `exec_module`, see `harness.py`) as the
+      builtins *dict* — so `__builtins__['exec'](...)` and
+      `__builtins__['__import__'](...)` need no preceding `import builtins`
+      at all, and flagging the bare name catches every subscript form in one
+      rule.
+    - `ast.Attribute`: `attr` in `{"import_module", "__import__"}`.
+      Deliberately NOT `exec`/`eval`: those are legitimate method names on
+      arbitrary objects (pandas `DataFrame.eval`/`DataFrame.query`, used in
+      ordinary node scripts that return a dataframe), and flagging them here
+      would reject that legitimate user code. `builtins.exec` /
+      `builtins.eval` (attribute access on the `builtins` module after an
+      explicit `import builtins`) are still caught, because that `import` is
+      itself an `ast.Import` violation above — but `__builtins__['exec']`
+      needs no such import, which is exactly what the `ast.Name` rule above
+      exists to close.
+
+    `construct` is the offending name as written: "importlib", "builtins",
+    "__import__", "exec", "eval", "__builtins__", or "import_module". Sorted
+    by lineno, then construct.
+    """
+    violations: list[tuple[int, str]] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                root = alias.name.split(".")[0]
+                if root in _DYNAMIC_IMPORT_MODULES:
+                    violations.append((node.lineno, root))
+        elif isinstance(node, ast.ImportFrom):
+            from_root = node.module.split(".")[0] if node.module is not None else None
+            if from_root in _DYNAMIC_IMPORT_MODULES:
+                violations.append((node.lineno, from_root))
+                continue  # one statement, one violation - aliases not also checked
+            for alias in node.names:
+                if alias.name in _DYNAMIC_IMPORT_NAMES:
+                    violations.append((node.lineno, alias.name))
+        elif isinstance(node, ast.Name):
+            if node.id in _DYNAMIC_IMPORT_NAMES:
+                violations.append((node.lineno, node.id))
+        elif isinstance(node, ast.Attribute):
+            if node.attr in _DYNAMIC_IMPORT_ATTRS:
+                violations.append((node.lineno, node.attr))
+    return sorted(violations)
+
+
+def _package_components(importing_file: Path, repo_root: Path) -> tuple[str, ...]:
+    """Dotted-path components of *importing_file*'s parent directory,
+    relative to *repo_root* (empty tuple when the file lives at the root)."""
+    rel_parent = importing_file.parent.relative_to(repo_root)
+    if rel_parent == Path("."):
+        return ()
+    return rel_parent.parts
+
+
+def _names_from_import(node: ast.Import) -> list[str]:
+    return [alias.name for alias in node.names]
+
+
+def _names_from_import_from(
+    node: ast.ImportFrom, importing_file: Path, repo_root: Path
+) -> list[str]:
+    if node.level == 0:
+        # level == 0 always carries a module per the grammar (`from X import Y`).
+        base = node.module
+        assert base is not None
+        return [base] + [f"{base}.{alias.name}" for alias in node.names]
+
+    components = _package_components(importing_file, repo_root)
+    walk_up = node.level - 1
+    if walk_up > len(components):
+        return []  # would escape repo_root - cannot name an in-repo file
+
+    prefix_parts = components[: len(components) - walk_up]
+    prefix = ".".join(prefix_parts)
+    base = ".".join(part for part in (prefix, node.module) if part)
+
+    # Real Python executes the package's __init__.py for `from . import name`
+    # regardless of whether `name` is a submodule file or just an attribute
+    # defined inside __init__.py - the two are indistinguishable from the
+    # import statement's syntax alone, so the bare prefix/base is always a
+    # candidate (symmetric with the level == 0 branch above), not only when
+    # node.module is also present. Missing __init__.py here would be
+    # under-inclusion (a stale node in production); including it when it was
+    # already reachable is a no-op, and including it spuriously costs at
+    # most one revalidation - see the module docstring.
+    names = [base] if base else []
+    names.extend(f"{base}.{alias.name}" if base else alias.name for alias in node.names)
+    return names
+
+
+def _collect_import_names(tree: ast.AST, importing_file: Path, repo_root: Path) -> list[str]:
+    names: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            names.extend(_names_from_import(node))
+        elif isinstance(node, ast.ImportFrom):
+            names.extend(_names_from_import_from(node, importing_file, repo_root))
+    return names
+
+
+def _resolve_name(
+    name: str, search_roots: tuple[Path, ...]
+) -> tuple[Path, Path, tuple[str, ...]] | None:
+    """Resolve a dotted module name to (root, resolved file, name parts).
+
+    Tries each root in *search_roots*, in order, and for each, the package
+    form `<root>/a/b/c/__init__.py` before the module-file form
+    `<root>/a/b/c.py` - matching Python's own package-before-module lookup
+    order (when both exist, `import a.b.c` binds the package and the module
+    file of the same name is never executed). Returns None when the name
+    resolves under no root (it's external).
+    """
+    parts = tuple(name.split("."))
+    for root in search_roots:
+        package_init = root.joinpath(*parts, "__init__.py")
+        if package_init.is_file():
+            return root, package_init.resolve(), parts
+        module_file = root.joinpath(*parts).with_suffix(".py")
+        if module_file.is_file():
+            return root, module_file.resolve(), parts
+    return None
+
+
+def resolve_closure(script_path: Path, repo_root: Path) -> list[Path]:
+    """Return the transitive in-repo import closure of *script_path*.
+
+    Absolute, resolved paths, sorted, with *script_path* itself EXCLUDED (it is
+    `source_hash`). Files that do not resolve under *repo_root* — stdlib,
+    site-packages, anything installed — are not closure members: external deps
+    are the image's concern (`image_tag`), not the hash's.
+
+    Search roots are the fixed, ordered pair `(repo_root, script_dir)` -
+    `script_dir` is *script_path*'s own directory, computed once here and
+    reused for every resolution in the traversal, matching what
+    `harness.ensure_import_paths` puts on `sys.path` for the whole process.
+    When the script lives at *repo_root* itself the pair collapses to a
+    single root, so it is not probed twice.
+    """
+    repo_root = repo_root.resolve()
+    script_resolved = script_path.resolve()
+    script_dir = script_resolved.parent
+    search_roots = (repo_root,) if script_dir == repo_root else (repo_root, script_dir)
+
+    seen: set[Path] = {script_resolved}
+    queue: deque[Path] = deque([script_resolved])
+
+    while queue:
+        current = queue.popleft()
+        rel = current.relative_to(repo_root)
+
+        source = current.read_bytes()
+        try:
+            tree = ast.parse(source)
+        except SyntaxError as exc:
+            raise ContractError(f"{rel}: syntax error: {exc.msg}") from exc
+
+        violations = dynamic_import_violations(tree)
+        if violations:
+            lineno, construct = violations[0]
+            raise ContractError(
+                f"{rel}:{lineno}: dynamic import construct {construct!r} is not "
+                "allowed — the content hash cannot see it"
+            )
+
+        for name in _collect_import_names(tree, current, repo_root):
+            match = _resolve_name(name, search_roots)
+            if match is None:
+                continue
+            root, resolved_file, parts = match
+
+            candidates = [resolved_file]
+            for depth in range(1, len(parts)):
+                init_candidate = root.joinpath(*parts[:depth], "__init__.py")
+                if init_candidate.is_file():
+                    candidates.append(init_candidate.resolve())
+
+            for candidate in candidates:
+                if not candidate.is_relative_to(repo_root):
+                    continue  # symlink escape
+                if candidate in seen:
+                    continue
+                seen.add(candidate)
+                queue.append(candidate)
+
+    return sorted(seen - {script_resolved})