continuo-engine-contract 0.7.0__tar.gz

continuo_engine_contract-0.7.0/.gitignore

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

continuo_engine_contract-0.7.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: continuo-engine-contract
+Version: 0.7.0
+Summary: The contract a Continuo warehouse engine must satisfy: the WarehouseAdapter port and the result-block wire format.
+Author: Simone Carolini
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: sqlglot==30.15.0
+Description-Content-Type: text/markdown
+
+# continuo-engine-contract
+
+The contract shared by the Continuo python runtime — the node harness and the
+validation runner alike — and every engine adapter library. Five modules:
+
+| Module | What it holds |
+|---|---|
+| `continuo_engine_contract.port` | The `WarehouseAdapter` port — one port covering both the data plane (`fetch`/`ensure_table`/`load`) and validation (engine-specific empty-table DDL) — plus entry-point discovery |
+| `continuo_engine_contract.types` | The SQL column-type grammar that DDL-emitting methods validate against |
+| `continuo_engine_contract.sql` | `ensure_single_read`, the parse-backed gate `check_binds` runs before it lets a declared read near an engine |
+| `continuo_engine_contract.config` | `ensure_known_keys`, the fail-closed gate `build_empty_from_columns` runs before it lets a node's physical-layout `config` block reach DDL |
+| `continuo_engine_contract.result` | The sentinel-framed result-block wire format the runner emits and the k8s-controller parses |
+
+Each `continuo-python-runtime-<engine>` library depends on this package and
+implements the port.
+
+`ensure_single_read` is why this package has a runtime dependency —
+[sqlglot](https://pypi.org/project/sqlglot/), pinned exactly — where it
+previously had none. Deciding "is this one read query?" means parsing it, and
+that rule is engine-independent: every adapter needs the same one, so it lives
+here rather than being reimplemented per engine. Adapters call it with their
+own dialect (`"postgres"`, `"trino"`, …) and it raises `ValueError` on
+anything that is not exactly one query — no sqlglot exception escapes, so
+callers never import sqlglot to handle a rejected read.
+
+## A contract, not a service
+
+This package runs nothing of its own — it isn't a service and it isn't the Job
+either. It's the interface both callers agree on: `continuo-python-runtime`
+(the node harness and the validation runner that call it) and every
+`continuo-python-runtime-<engine>` adapter package (which implements it). The
+whole contract is the twelve `WarehouseAdapter` methods (`required_env`,
+`from_env`, `ensure_schema`, `drop_schema`, `build_empty_from_sql`,
+`clone_empty_from_prod`, `build_empty_from_columns`, `check_binds`, `fetch`,
+`ensure_table`, `load`, `close`) plus the sentinel result-block format, both
+reached through the single `continuo_engine.adapters` entry-point group that
+`discover_adapter` resolves against — and the three shared guards
+implementations are required to run rather than reinvent:
+`types.validate_column_type` before interpolating a type into DDL,
+`sql.ensure_single_read` before letting a declared read reach an engine, and
+`config.ensure_known_keys` before building any DDL from a node's
+physical-layout `config` block, to reject keys this engine doesn't recognize.
+
+Because the port *is* the contract, this package is very unlikely to need
+changes — new warehouse support is a new adapter package implementing the
+existing methods, not a change here. Touching this file means bumping a
+version that the co-located runtime and adapters in this workspace consume
+immediately, and that external adapter authors pin from PyPI, so treat it as
+a deliberate, coordinated change. The `result` module is stricter still: its
+wire format is frozen against Continuo's Go parser (`pkg/validationresult`)
+and must not change from this side at all.

continuo_engine_contract-0.7.0/README.md

@@ -0,0 +1,51 @@
+# continuo-engine-contract
+
+The contract shared by the Continuo python runtime — the node harness and the
+validation runner alike — and every engine adapter library. Five modules:
+
+| Module | What it holds |
+|---|---|
+| `continuo_engine_contract.port` | The `WarehouseAdapter` port — one port covering both the data plane (`fetch`/`ensure_table`/`load`) and validation (engine-specific empty-table DDL) — plus entry-point discovery |
+| `continuo_engine_contract.types` | The SQL column-type grammar that DDL-emitting methods validate against |
+| `continuo_engine_contract.sql` | `ensure_single_read`, the parse-backed gate `check_binds` runs before it lets a declared read near an engine |
+| `continuo_engine_contract.config` | `ensure_known_keys`, the fail-closed gate `build_empty_from_columns` runs before it lets a node's physical-layout `config` block reach DDL |
+| `continuo_engine_contract.result` | The sentinel-framed result-block wire format the runner emits and the k8s-controller parses |
+
+Each `continuo-python-runtime-<engine>` library depends on this package and
+implements the port.
+
+`ensure_single_read` is why this package has a runtime dependency —
+[sqlglot](https://pypi.org/project/sqlglot/), pinned exactly — where it
+previously had none. Deciding "is this one read query?" means parsing it, and
+that rule is engine-independent: every adapter needs the same one, so it lives
+here rather than being reimplemented per engine. Adapters call it with their
+own dialect (`"postgres"`, `"trino"`, …) and it raises `ValueError` on
+anything that is not exactly one query — no sqlglot exception escapes, so
+callers never import sqlglot to handle a rejected read.
+
+## A contract, not a service
+
+This package runs nothing of its own — it isn't a service and it isn't the Job
+either. It's the interface both callers agree on: `continuo-python-runtime`
+(the node harness and the validation runner that call it) and every
+`continuo-python-runtime-<engine>` adapter package (which implements it). The
+whole contract is the twelve `WarehouseAdapter` methods (`required_env`,
+`from_env`, `ensure_schema`, `drop_schema`, `build_empty_from_sql`,
+`clone_empty_from_prod`, `build_empty_from_columns`, `check_binds`, `fetch`,
+`ensure_table`, `load`, `close`) plus the sentinel result-block format, both
+reached through the single `continuo_engine.adapters` entry-point group that
+`discover_adapter` resolves against — and the three shared guards
+implementations are required to run rather than reinvent:
+`types.validate_column_type` before interpolating a type into DDL,
+`sql.ensure_single_read` before letting a declared read reach an engine, and
+`config.ensure_known_keys` before building any DDL from a node's
+physical-layout `config` block, to reject keys this engine doesn't recognize.
+
+Because the port *is* the contract, this package is very unlikely to need
+changes — new warehouse support is a new adapter package implementing the
+existing methods, not a change here. Touching this file means bumping a
+version that the co-located runtime and adapters in this workspace consume
+immediately, and that external adapter authors pin from PyPI, so treat it as
+a deliberate, coordinated change. The `result` module is stricter still: its
+wire format is frozen against Continuo's Go parser (`pkg/validationresult`)
+and must not change from this side at all.

continuo_engine_contract-0.7.0/continuo_engine_contract/__init__.py

@@ -0,0 +1 @@
+"""Contract for the Continuo warehouse engines: the WarehouseAdapter port and the result-block wire format."""

continuo_engine_contract-0.7.0/continuo_engine_contract/config.py

@@ -0,0 +1,50 @@
+"""The contract's physical-layout ``config`` guard.
+
+A node's ``config`` block is written in the ACTIVE ENGINE's own vocabulary
+(postgres: ``indexes``; trino: ``partitioning``/``sorted_by``/…) rather than
+under an engine namespace: the contract is engine-bound anyway, so there is no
+"someone else's namespace" to excuse a key the engine does not know. An
+unrecognized key is therefore an authoring error and must reject the node — a
+config the author believes is applied but is silently dropped would ship an
+unindexed, unpartitioned table to production behind a green release gate.
+
+Adapters call :func:`ensure_known_keys` before building any DDL.
+"""
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+
+def ensure_known_keys(
+    config: object, known: Iterable[str], engine: str, where: str = "config"
+) -> None:
+    """Raise ValueError unless *config* is a mapping whose keys all lie in *known*.
+
+    Parameters
+    ----------
+    config
+        The physical-layout block as it arrived from the validation spec.
+        Anything that is not a mapping is rejected rather than coerced.
+    known
+        The keys this engine's adapter recognizes. May be empty.
+    engine
+        Engine name, quoted into the message so an author reading a failed
+        release gate knows which vocabulary was expected.
+    where
+        Label for the block under inspection, so a nested caller (an index
+        entry, say) can point the message at the right part of the config.
+
+    Raises
+    ------
+    ValueError
+        If *config* is not a mapping, or carries any key outside *known*.
+    """
+    if not isinstance(config, Mapping):
+        raise ValueError(f"{where} must be a mapping, got {type(config).__name__}")
+    known_set = set(known)
+    unknown = sorted(repr(key) for key in config if key not in known_set)
+    if unknown:
+        raise ValueError(
+            f"unrecognized {where} key(s) {', '.join(unknown)} for engine {engine!r}; "
+            f"known keys: {', '.join(sorted(known_set)) or '(none)'}"
+        )

continuo_engine_contract-0.7.0/continuo_engine_contract/port.py

@@ -0,0 +1,189 @@
+"""The warehouse-engine adapter port and entry-point discovery.
+
+One port covers both roles an engine plays in Continuo:
+
+* **validation DDL** — a release gate builds each node as an EMPTY table in the
+  candidate schema and bind-checks its compiled SQL (``ensure_schema``,
+  ``drop_schema``, ``build_empty_from_sql``, ``build_empty_from_columns``,
+  ``clone_empty_from_prod``, ``check_binds``);
+* **python-node data-plane I/O** — the runtime harness reads declared inputs and
+  writes a node's result (``fetch``, ``ensure_table``, ``load``).
+
+Both roles are served by the same connection to the same warehouse, so they are
+one implementation per engine rather than two. Engine packages register a single
+``continuo_engine.adapters`` entry point; each image installs exactly one, so
+discovery — not configuration — selects the adapter.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from importlib.metadata import entry_points
+from typing import TYPE_CHECKING
+
+ENTRY_POINT_GROUP = "continuo_engine.adapters"
+
+if TYPE_CHECKING:  # pragma: no cover
+    import pyarrow  # type: ignore[import-untyped]
+
+
+class AdapterDiscoveryError(Exception):
+    """Installed adapter plugins do not resolve to exactly one usable engine."""
+
+
+class WarehouseAdapter(ABC):
+    """Port for everything Continuo asks of one warehouse engine.
+
+    stdout is a parsed channel: the caller prints one sentinel-framed result
+    block (see ``result.py``) as its last stdout line. Adapters must log
+    diagnostics via the stdlib ``logging`` module (captured from the pod log)
+    rather than printing them, must never write to stdout, and must never emit
+    the ``===CONTINUO_VALIDATION_RESULT_BEGIN/END===`` marker strings
+    themselves.
+    """
+
+    @classmethod
+    @abstractmethod
+    def required_env(cls) -> list[str]:
+        """Names of env vars that must be non-empty before connecting."""
+
+    @classmethod
+    @abstractmethod
+    def from_env(cls) -> "WarehouseAdapter":
+        """Construct a connected adapter from environment variables."""
+
+    @abstractmethod
+    def ensure_schema(self, schema: str) -> None:
+        """Idempotently create *schema*; safe under concurrent callers."""
+
+    @abstractmethod
+    def drop_schema(self, schema: str) -> None:
+        """Idempotently drop *schema* and everything in it; no-op if absent.
+
+        Symmetric teardown for :meth:`ensure_schema`. The executor schedules this
+        as a one-shot engine-image op once a validation reaches its terminal result,
+        so the control plane never connects to the warehouse itself. *schema* is
+        opaque and mapped to the engine's own dialect.
+        """
+
+    @abstractmethod
+    def build_empty_from_sql(self, schema: str, table: str, compiled_sql: str) -> None:
+        """Create ``schema.table`` empty, shaped by the compiled SELECT."""
+
+    @abstractmethod
+    def clone_empty_from_prod(self, candidate_schema: str, prod_schema: str, table: str) -> None:
+        """Create ``candidate_schema.table`` empty, shaped like ``prod_schema.table``."""
+
+    @abstractmethod
+    def build_empty_from_columns(
+        self, schema: str, table: str, columns: list[dict], config: dict
+    ) -> None:
+        """Create ``schema.table`` empty from declared typed columns.
+
+        Rebuild semantics (drop-then-create), matching the other build ops.
+        Each column dict carries ``name`` (an identifier — implementations
+        MUST quote it with their engine's identifier escaping, never
+        interpolate it raw), ``type`` (a string from the contract's type
+        grammar — see :mod:`continuo_engine_contract.types`;
+        implementations MUST validate before interpolating into DDL), and
+        optional ``nullable`` (default True). Bare typed CREATE TABLE is
+        engine-portable by design — no dialect families.
+
+        *config* is the node's physical-layout block — indexes, sort keys,
+        partitioning — written in THIS engine's own vocabulary and applied to
+        the created table (postgres: ``indexes``; trino: ``partitioning``,
+        ``sorted_by``, ``format``, ``format_version``). It is deliberately not
+        engine-namespaced, so implementations MUST fail closed on any key they
+        do not recognize: call
+        :func:`continuo_engine_contract.config.ensure_known_keys` with
+        this engine's known-key set, and validate every value, BEFORE emitting
+        any DDL — a malformed config must never leave a half-built table
+        behind. Identifiers and property values taken from *config* MUST be
+        escaped or allowlisted before interpolation, exactly as the column
+        path already does. An empty *config* MUST emit the same bare
+        ``CREATE TABLE`` as contract 0.4.0 — no trailing clause, no property
+        list, no index statements.
+        """
+
+    @abstractmethod
+    def check_binds(self, sql: str) -> None:
+        """Verify *sql* binds against the current schema state without scanning data.
+
+        EXPLAIN/prepare-class mechanism per engine. Raises on missing
+        tables/columns or type errors; returns None when the query binds.
+
+        *sql* is a single read query, and implementations MUST establish that
+        by calling :func:`continuo_engine_contract.sql.ensure_single_read`
+        with their engine's dialect **before** building anything to send.
+        Wrapping the read in a subquery is not a substitute: a read that closes
+        the wrap's own parenthesis and reopens it after an injected statement
+        leaves the wrap balanced, and a driver that batches ``;``-separated
+        statements then executes the injected statement for real.
+        """
+
+    @abstractmethod
+    def fetch(self, sql: str) -> "pyarrow.Table":
+        """Execute one declared read and return the result as Arrow."""
+
+    @abstractmethod
+    def ensure_table(
+        self, schema: str, table: str, columns: list[dict], *, config: dict
+    ) -> None:
+        """CREATE TABLE IF NOT EXISTS with the typed DDL compiled from columns.
+
+        Each column dict carries ``name`` (an identifier — implementations
+        MUST quote it with their engine's identifier escaping, never
+        interpolate it raw), ``type`` (a string from the contract's type
+        grammar — see :mod:`continuo_engine_contract.types`;
+        implementations MUST validate before interpolating into DDL), and
+        ``nullable`` (bool).
+
+        *config* is the node's physical-layout block in this engine's own
+        vocabulary (e.g. ``indexes``), applied when the table is created;
+        callers pass ``{}`` for none. It is keyword-only: the harness passes
+        it as ``config=`` unconditionally, and a positional-friendly
+        signature would let a caller regress to positional passing unnoticed.
+        Implementations MUST fail closed on any config key they do not
+        recognize, and MUST validate config values before interpolating
+        anything into DDL — the same discipline
+        :meth:`build_empty_from_columns` follows.
+        """
+
+    @abstractmethod
+    def load(self, schema: str, table: str, data: "pyarrow.Table") -> None:
+        """Atomically replace the table's contents with *data*."""
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release the underlying connection."""
+
+
+def discover_adapter() -> tuple[str, type[WarehouseAdapter]]:
+    """Return ``(engine_name, adapter_class)`` from the single installed plugin.
+
+    Raises
+    ------
+    AdapterDiscoveryError
+        If zero or multiple adapters are installed, if the entry point fails to
+        import, or if it does not resolve to a WarehouseAdapter subclass.
+    """
+    eps = list(entry_points(group=ENTRY_POINT_GROUP))
+    if not eps:
+        raise AdapterDiscoveryError(
+            f"no engine adapter installed (entry-point group {ENTRY_POINT_GROUP!r} is "
+            f"empty); install exactly one engine package"
+        )
+    if len(eps) > 1:
+        names = ", ".join(sorted(ep.name for ep in eps))
+        raise AdapterDiscoveryError(
+            f"multiple engine adapters installed ({names}); an image must install exactly one"
+        )
+    ep = eps[0]
+    try:
+        cls = ep.load()
+    except Exception as exc:
+        raise AdapterDiscoveryError(f"failed to load adapter entry point {ep.name!r}: {exc}") from exc
+    if not (isinstance(cls, type) and issubclass(cls, WarehouseAdapter)):
+        raise AdapterDiscoveryError(
+            f"entry point {ep.name!r} does not resolve to a WarehouseAdapter subclass"
+        )
+    return ep.name, cls

continuo_engine_contract-0.7.0/continuo_engine_contract/result.py

@@ -0,0 +1,34 @@
+"""Cross-language contract for one validation node's structured result.
+
+validation_runner.py prints exactly one sentinel-framed block on stdout as its LAST
+output. The k8s-controller extracts the block from the pod log, uploads the JSON to
+S3, and surfaces it as run_results_uri. The remediation classifier reads status +
+message deterministically, falling back to the text log when the block is absent.
+
+status uses dbt's RunStatus vocabulary (success | error | fail | skipped).
+"""
+import json
+
+SENTINEL_BEGIN = "===CONTINUO_VALIDATION_RESULT_BEGIN==="
+SENTINEL_END = "===CONTINUO_VALIDATION_RESULT_END==="
+
+SCHEMA_VERSION = 1
+
+
+def result_block(status: str, message: str = "", failures: int = 0, unique_id: str = "") -> str:
+    """Return the sentinel-framed, single-line-JSON block for one node.
+
+    The JSON is compact (no embedded newlines) so the consumer can split the
+    block out of a multi-line pod log by marker lines alone.
+    """
+    body = json.dumps(
+        {
+            "schema_version": SCHEMA_VERSION,
+            "status": status,
+            "message": message or "",
+            "failures": int(failures or 0),
+            "unique_id": unique_id or "",
+        },
+        separators=(",", ":"),
+    )
+    return f"{SENTINEL_BEGIN}\n{body}\n{SENTINEL_END}"

continuo_engine_contract-0.7.0/continuo_engine_contract/sql.py

@@ -0,0 +1,86 @@
+"""The contract's single-read gate for :meth:`WarehouseAdapter.check_binds`.
+
+``check_binds`` accepts a single read query, raises on any bind failure, and
+scans zero data. Enforcing "a single read" by wrapping the text in a subquery
+and letting the engine's parser object is not enough: a read that closes the
+wrap's own parenthesis and reopens it after an injected statement leaves the
+wrap balanced, and an engine whose driver batches ``;``-separated statements
+(psycopg2's simple-query protocol does) then executes the injected statement
+for real. So the shape is decided here, by parsing, before any text reaches an
+engine.
+
+This lives in the contract rather than in each adapter because the rule is
+engine-independent and every adapter — including third-party ones — needs the
+same one.
+"""
+import logging
+
+import sqlglot
+
+from sqlglot import exp
+
+logger = logging.getLogger(__name__)
+
+# The expression types a legitimate read parses to. Validated against the full
+# set of read shapes a spec may declare (plain/star selects, WHERE/ORDER
+# BY/LIMIT, CTEs, UNION ALL, GROUP BY, joins, FROM-less selects, VALUES,
+# duplicate output names, trailing semicolons, trailing line comments). Narrow
+# it further and legitimate reads start getting rejected.
+_READ_TYPES = (exp.Select, exp.Union, exp.Values, exp.Subquery)
+
+# Rejection messages quote the offending read, and ride back to the controller
+# inside the runner's result block — so bound every variable-length part of
+# them, both the read itself and any parser detail appended to it.
+_MAX_EXCERPT = 200
+
+
+def _excerpt(text: str) -> str:
+    """Render *text* for an error message: whitespace collapsed, length bounded."""
+    collapsed = " ".join(text.split())
+    if len(collapsed) > _MAX_EXCERPT:
+        return f"{collapsed[:_MAX_EXCERPT]}... (truncated)"
+    return collapsed
+
+
+def ensure_single_read(sql: str, dialect: str | None = None) -> None:
+    """Raise ValueError unless *sql* is exactly one read query.
+
+    Parameters
+    ----------
+    sql
+        The declared read, as written in the spec.
+    dialect
+        A sqlglot dialect name (e.g. ``"postgres"``, ``"trino"``). Adapters
+        pass their engine's dialect; ``None`` parses with sqlglot's default.
+
+    Raises
+    ------
+    ValueError
+        If *sql* does not parse, parses to anything other than exactly one
+        statement, or parses to a statement that is not a query. Every
+        rejection is a ValueError — a sqlglot ``ParseError`` never escapes, so
+        callers need not import sqlglot to handle a rejected read.
+    """
+    try:
+        parsed = sqlglot.parse(sql, dialect=dialect)
+    except sqlglot.ParseError as exc:
+        raise ValueError(
+            f"check_binds accepts a single read query, and this read does not parse "
+            f"as {dialect or 'SQL'}: {_excerpt(sql)} [{_excerpt(str(exc))}]"
+        ) from exc
+
+    statements = [statement for statement in parsed if statement is not None]
+    if len(statements) != 1:
+        raise ValueError(
+            f"check_binds accepts exactly one read query, but this read parses as "
+            f"{len(statements)} statements: {_excerpt(sql)}"
+        )
+
+    statement = statements[0]
+    if not isinstance(statement, _READ_TYPES):
+        raise ValueError(
+            f"check_binds accepts a single read query, but this read is a "
+            f"{statement.key.upper()} statement: {_excerpt(sql)}"
+        )
+
+    logger.debug("read accepted as a single query by the %s gate", dialect or "default")

continuo_engine_contract-0.7.0/continuo_engine_contract/types.py

@@ -0,0 +1,23 @@
+"""The contract's SQL column-type grammar.
+
+The matched text is interpolated directly into engine DDL by the adapters, so
+this is an injection guard, not just validation — anything outside this shape
+is rejected outright. Kept byte-identical to the runtime adapters' grammar in
+continuo-python-runtime so both planes accept the same type set.
+"""
+import re
+
+TYPE_RE = re.compile(
+    r"^("
+    r"BIGINT|INT|INTEGER|DOUBLE PRECISION|TEXT|TIMESTAMP|DATE|BOOLEAN|"
+    r"(NUMERIC|DECIMAL)\(\d+,\s*\d+\)|"
+    r"(VARCHAR|CHAR)\(\d+\)"
+    r")\Z",
+    re.IGNORECASE | re.ASCII,
+)
+
+
+def validate_column_type(type_str: str) -> None:
+    """Raise ValueError unless *type_str* matches the contract's SQL type grammar."""
+    if not TYPE_RE.match(type_str):
+        raise ValueError(f"unsupported or invalid SQL type: {type_str!r}")

continuo_engine_contract-0.7.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+version = "0.7.0"
+name = "continuo-engine-contract"
+description = "The contract a Continuo warehouse engine must satisfy: the WarehouseAdapter port and the result-block wire format."
+authors = [{ name = "Simone Carolini" }]
+readme = "README.md"
+requires-python = ">= 3.14"
+dependencies = ["sqlglot==30.15.0"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3.14",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["continuo_engine_contract"]

continuo_engine_contract-0.7.0/tests/test_config.py

@@ -0,0 +1,55 @@
+"""Unit tests for the physical-layout config guard."""
+import pytest
+
+from continuo_engine_contract.config import ensure_known_keys
+
+
+def test_empty_config_is_accepted_even_with_no_known_keys():
+    """An absent layout block is the common case and must never raise."""
+    ensure_known_keys({}, (), "postgres")
+
+
+def test_known_keys_are_accepted():
+    """Every key inside the engine's vocabulary passes."""
+    ensure_known_keys({"indexes": [], "extra": 1}, ("indexes", "extra"), "postgres")
+
+
+def test_unknown_key_is_rejected_naming_key_engine_and_vocabulary():
+    """The message must tell the author what they wrote and what the engine knows."""
+    with pytest.raises(ValueError) as exc:
+        ensure_known_keys({"sortkey": ["id"]}, ("indexes",), "postgres")
+    message = str(exc.value)
+    assert "'sortkey'" in message
+    assert "'postgres'" in message
+    assert "indexes" in message
+
+
+def test_multiple_unknown_keys_are_reported_together_and_sorted():
+    """All authoring errors surface in one gate failure, deterministically ordered."""
+    with pytest.raises(ValueError) as exc:
+        ensure_known_keys({"zeta": 1, "alpha": 2}, ("indexes",), "postgres")
+    message = str(exc.value)
+    assert message.index("'alpha'") < message.index("'zeta'")
+
+
+def test_empty_known_set_renders_as_none():
+    """An engine with no vocabulary yet still produces a readable message."""
+    with pytest.raises(ValueError, match=r"\(none\)"):
+        ensure_known_keys({"indexes": []}, (), "trino")
+
+
+@pytest.mark.parametrize(
+    "bad", [[], "indexes", 3, None, True], ids=["list", "str", "int", "none", "bool"]
+)
+def test_non_mapping_config_is_rejected(bad):
+    """Config must be a mapping; a list or scalar is an authoring error, not a default."""
+    with pytest.raises(ValueError, match="must be a mapping"):
+        ensure_known_keys(bad, ("indexes",), "postgres")
+
+
+def test_where_label_appears_in_both_messages():
+    """Nested callers relabel the subject so the error points at the right block."""
+    with pytest.raises(ValueError, match="index entry must be a mapping"):
+        ensure_known_keys([], ("columns",), "postgres", where="index entry")
+    with pytest.raises(ValueError, match="unrecognized index entry key"):
+        ensure_known_keys({"nope": 1}, ("columns",), "postgres", where="index entry")

continuo_engine_contract-0.7.0/tests/test_contract_types.py

@@ -0,0 +1,25 @@
+"""Unit tests for the SQL column-type grammar contract."""
+import pytest
+
+from continuo_engine_contract.types import validate_column_type
+
+
+@pytest.mark.parametrize("ok", [
+    "BIGINT", "INT", "INTEGER", "DOUBLE PRECISION", "TEXT",
+    "TIMESTAMP", "DATE", "BOOLEAN",
+    "NUMERIC(10,2)", "DECIMAL(38, 0)", "VARCHAR(255)", "CHAR(1)",
+    "bigint", "varchar(9)",  # case-insensitive
+])
+def test_supported_types_pass(ok: str) -> None:
+    """Supported types must not raise."""
+    validate_column_type(ok)  # must not raise
+
+
+@pytest.mark.parametrize("bad", [
+    "", "FLOAT", "VARCHAR", "NUMERIC", "NUMERIC(10)", "VARCHAR(255); DROP TABLE x",
+    "TEXT )", "INTEGER--", "SERIAL", "JSONB", "TIMESTAMP WITH TIME ZONE",
+])
+def test_unsupported_or_malformed_types_raise(bad: str) -> None:
+    """Unsupported or malformed types must raise ValueError."""
+    with pytest.raises(ValueError):
+        validate_column_type(bad)

continuo_engine_contract-0.7.0/tests/test_port.py

@@ -0,0 +1,349 @@
+"""Discovery tests for the WarehouseAdapter port.
+
+These install REAL adapter packages (with genuine ``continuo_engine.adapters``
+entry points) into throwaway virtualenvs and run ``discover_adapter`` against the
+real ``importlib.metadata`` machinery — no monkeypatching of ``entry_points``, so the
+tests exercise actual entry-point loading rather than an assumed return shape.
+"""
+import subprocess
+import textwrap
+
+from pathlib import Path
+
+import pytest
+
+from continuo_engine_contract.port import ENTRY_POINT_GROUP, WarehouseAdapter
+
+CONTRACT_ROOT = Path(__file__).resolve().parent.parent  # contract/
+
+
+def test_warehouse_adapter_cannot_be_instantiated():
+    """The port is abstract — a concrete adapter must implement every method."""
+    with pytest.raises(TypeError):
+        WarehouseAdapter()  # type: ignore[abstract]
+
+
+def test_warehouse_adapter_requires_drop_schema():
+    """drop_schema is part of the contract: omitting it blocks instantiation.
+
+    A concrete adapter that implements every method except the teardown one must
+    still be abstract, so the executor can rely on drop_schema existing on every
+    installed engine.
+    """
+
+    class MissingDrop(WarehouseAdapter):
+        @classmethod
+        def required_env(cls):
+            return []
+
+        @classmethod
+        def from_env(cls):
+            return cls()
+
+        def ensure_schema(self, schema):
+            ...
+
+        def build_empty_from_sql(self, schema, table, compiled_sql):
+            ...
+
+        def clone_empty_from_prod(self, candidate_schema, prod_schema, table):
+            ...
+
+        def build_empty_from_columns(self, schema, table, columns, config):
+            ...
+
+        def check_binds(self, sql):
+            ...
+
+        def fetch(self, sql):
+            ...
+
+        def ensure_table(self, schema, table, columns, *, config):
+            ...
+
+        def load(self, schema, table, data):
+            ...
+
+        def close(self):
+            ...
+
+    with pytest.raises(TypeError, match="drop_schema"):
+        MissingDrop()  # type: ignore[abstract]
+
+
+def test_warehouse_adapter_requires_columns_and_binds_methods():
+    """A subclass missing the 0.4.0 methods cannot be instantiated.
+
+    Adapters implementing only the 0.3.0 surface (required_env, from_env,
+    ensure_schema, drop_schema, build_empty_from_sql, clone_empty_from_prod,
+    close) must still be abstract, so callers can rely on build_empty_from_columns
+    and check_binds existing on every installed engine.
+    """
+
+    class Partial(WarehouseAdapter):
+        @classmethod
+        def required_env(cls):
+            return []
+
+        @classmethod
+        def from_env(cls):
+            return cls()
+
+        def ensure_schema(self, schema):
+            ...
+
+        def drop_schema(self, schema):
+            ...
+
+        def build_empty_from_sql(self, schema, table, compiled_sql):
+            ...
+
+        def clone_empty_from_prod(self, candidate_schema, prod_schema, table):
+            ...
+
+        def close(self):
+            ...
+
+    with pytest.raises(TypeError, match="build_empty_from_columns|check_binds"):
+        Partial()  # type: ignore[abstract]
+
+
+def test_partial_engine_cannot_be_instantiated():
+    """A class implementing only the validation half must fail at construction.
+
+    One port means one class per engine covering both roles: an adapter that
+    still only speaks validation DDL is abstract, so a half-migrated engine
+    package cannot be constructed and silently fail later, at the first
+    python-node read.
+    """
+
+    class HalfEngine(WarehouseAdapter):
+        @classmethod
+        def required_env(cls):
+            return []
+
+        @classmethod
+        def from_env(cls):
+            return cls()
+
+        def ensure_schema(self, schema):
+            ...
+
+        def drop_schema(self, schema):
+            ...
+
+        def build_empty_from_sql(self, schema, table, compiled_sql):
+            ...
+
+        def build_empty_from_columns(self, schema, table, columns, config):
+            ...
+
+        def clone_empty_from_prod(self, schema, prod_schema, table):
+            ...
+
+        def check_binds(self, sql):
+            ...
+
+        def close(self):
+            ...
+
+        # fetch / ensure_table / load deliberately missing
+
+    with pytest.raises(TypeError):
+        HalfEngine()  # type: ignore[abstract]
+
+
+def test_single_entry_point_group_and_single_discovery():
+    """One port, one entry-point group, one discovery function — no second half left."""
+    from continuo_engine_contract import port
+
+    assert port.ENTRY_POINT_GROUP == "continuo_engine.adapters"
+    public = {name for name in dir(port) if not name.startswith("_")}
+    # Asserted as exhaustive sets rather than as absent legacy spellings: the
+    # merge left exactly one entry-point group, one discovery function, and
+    # one port class, so a second of any of them fails here whatever it is
+    # called. (tests/test_no_legacy_names.py owns the old spellings.)
+    assert {n for n in public if n.endswith("ENTRY_POINT_GROUP")} == {"ENTRY_POINT_GROUP"}
+    assert {n for n in public if n.startswith("discover")} == {"discover_adapter"}
+    assert {n for n in public if n.endswith("Adapter")} == {"WarehouseAdapter"}
+
+
+def test_ensure_table_signature_declares_config_keyword_only():
+    """The port itself declares the physical-layout config parameter.
+
+    Adapters receive the node's config through the abstract signature — they
+    must never have to extend beyond the ABC to accept it. It is required and
+    keyword-only: the harness passes ``config=`` unconditionally, and a
+    positional-friendly signature would let callers regress to positional
+    passing unnoticed.
+    """
+    import inspect
+
+    sig = inspect.signature(WarehouseAdapter.ensure_table)
+    params = list(sig.parameters)
+    assert params == ["self", "schema", "table", "columns", "config"]
+    config = sig.parameters["config"]
+    assert config.kind is inspect.Parameter.KEYWORD_ONLY
+    assert config.default is inspect.Parameter.empty
+
+
+# --- Real installed-adapter discovery via throwaway venvs --------------------
+
+_FIXTURE_MODULE = '''\
+from continuo_engine_contract.port import WarehouseAdapter
+
+
+class OneAdapter(WarehouseAdapter):
+    @classmethod
+    def required_env(cls):
+        return []
+
+    @classmethod
+    def from_env(cls):
+        return cls()
+
+    def ensure_schema(self, schema):
+        ...
+
+    def drop_schema(self, schema):
+        ...
+
+    def build_empty_from_sql(self, schema, table, compiled_sql):
+        ...
+
+    def clone_empty_from_prod(self, candidate_schema, prod_schema, table):
+        ...
+
+    def build_empty_from_columns(self, schema, table, columns, config):
+        ...
+
+    def check_binds(self, sql):
+        ...
+
+    def fetch(self, sql):
+        ...
+
+    def ensure_table(self, schema, table, columns, *, config):
+        ...
+
+    def load(self, schema, table, data):
+        ...
+
+    def close(self):
+        ...
+
+
+class TwoAdapter(OneAdapter):
+    ...
+
+
+not_an_adapter = object()
+'''
+
+_DISCOVER_SCRIPT = textwrap.dedent(
+    """
+    from continuo_engine_contract.port import discover_adapter, AdapterDiscoveryError
+    try:
+        name, cls = discover_adapter()
+        print("OK", name, cls.__name__)
+    except AdapterDiscoveryError as exc:
+        print("ERR", exc)
+    """
+)
+
+
+def _run_discovery(
+    tmp_path: Path,
+    entry_points: dict,
+    module_body: str = _FIXTURE_MODULE,
+    group: str = ENTRY_POINT_GROUP,
+    script: str = _DISCOVER_SCRIPT,
+) -> str:
+    """Run discovery in a fresh venv holding the contract + a fixture adapter.
+
+    Installs a generated fixture package declaring *entry_points* under *group*
+    with *module_body* as its module source, then runs *script* (which calls
+    ``discover_adapter``) and returns its stdout.
+    """
+    fixture = tmp_path / "fixture"
+    (fixture / "cvfixtureadapters").mkdir(parents=True)
+    (fixture / "cvfixtureadapters" / "__init__.py").write_text(module_body)
+    eps = "\n".join(f'{name} = "cvfixtureadapters:{target}"' for name, target in entry_points.items())
+    (fixture / "pyproject.toml").write_text(
+        textwrap.dedent(
+            f"""
+            [project]
+            name = "cvfixtureadapters"
+            version = "0.0.0"
+            requires-python = ">= 3.14"
+
+            [project.entry-points."{group}"]
+            {eps}
+
+            [build-system]
+            requires = ["hatchling"]
+            build-backend = "hatchling.build"
+
+            [tool.hatch.build.targets.wheel]
+            packages = ["cvfixtureadapters"]
+            """
+        )
+    )
+    venv = tmp_path / "venv"
+    subprocess.run(["uv", "venv", str(venv), "-p", "3.14"], check=True, capture_output=True)
+    subprocess.run(
+        ["uv", "pip", "install", "--python", str(venv), str(CONTRACT_ROOT), str(fixture)],
+        check=True,
+        capture_output=True,
+    )
+    py = venv / "bin" / "python"
+    proc = subprocess.run([str(py), "-c", script], capture_output=True, text=True)
+    return proc.stdout
+
+
+def test_discover_adapter_raises_when_none_installed(tmp_path):
+    """With no adapter package installed, discovery raises cleanly.
+
+    This runs in a throwaway venv rather than the ambient one: the ambient
+    environment in this workspace also has other, unrelated adapter packages
+    installed alongside the contract, so it can never exercise the genuine
+    zero-adapter path.
+    """
+    out = _run_discovery(tmp_path, {})
+    assert out.startswith("ERR")
+    assert "no engine adapter installed" in out
+
+
+def test_discover_single_installed_adapter_is_found(tmp_path):
+    """One installed adapter package → discovery returns its name and class."""
+    out = _run_discovery(tmp_path, {"one": "OneAdapter"})
+    assert out.strip() == "OK one OneAdapter"
+
+
+def test_discover_multiple_installed_adapters_raises_naming_them(tmp_path):
+    """Two installed adapters → discovery refuses and names both."""
+    out = _run_discovery(tmp_path, {"one": "OneAdapter", "two": "TwoAdapter"})
+    assert out.startswith("ERR")
+    assert "one, two" in out
+
+
+def test_discover_non_adapter_entry_point_raises(tmp_path):
+    """An entry point that is not a WarehouseAdapter subclass is rejected."""
+    out = _run_discovery(tmp_path, {"broken": "not_an_adapter"})
+    assert out.startswith("ERR")
+    assert "WarehouseAdapter subclass" in out
+
+
+def test_discover_wraps_adapter_import_failure(tmp_path):
+    """A failing adapter import surfaces as AdapterDiscoveryError, not a raw ImportError.
+
+    That lets the runner still emit a structured result block for a malformed engine
+    image rather than crashing with a traceback.
+    """
+    out = _run_discovery(
+        tmp_path,
+        {"one": "OneAdapter"},
+        module_body="import definitely_missing_pkg_zzz  # noqa: F401\n",
+    )
+    assert out.startswith("ERR")
+    assert "failed to load adapter entry point" in out

continuo_engine_contract-0.7.0/tests/test_result.py

@@ -0,0 +1,40 @@
+"""Unit tests for the validation-result contract helper."""
+import json
+
+from continuo_engine_contract import result
+
+
+def test_sentinel_markers_are_the_wire_contract():
+    """Pin the sentinel strings to their literal wire values.
+
+    The Go side (pkg/validationresult) pins the same literals independently, so an
+    edit to either marker on either side fails its own suite — the cross-language
+    guard cannot be silently defeated by editing only the Python constant.
+    """
+    assert result.SENTINEL_BEGIN == "===CONTINUO_VALIDATION_RESULT_BEGIN==="
+    assert result.SENTINEL_END == "===CONTINUO_VALIDATION_RESULT_END==="
+
+
+def _extract(block: str) -> dict:
+    lines = block.splitlines()
+    assert lines[0] == result.SENTINEL_BEGIN
+    assert lines[-1] == result.SENTINEL_END
+    return json.loads(lines[1])
+
+
+def test_result_block_is_sentinel_framed_single_line_json():
+    """A populated block round-trips through the sentinel framing intact."""
+    block = result.result_block(status="error", message="boom", unique_id="model.svc.x")
+    assert _extract(block) == {
+        "schema_version": 1, "status": "error", "message": "boom",
+        "failures": 0, "unique_id": "model.svc.x",
+    }
+    assert len(block.splitlines()) == 3
+
+
+def test_result_block_success_defaults():
+    """Omitted message/failures default to empty string and zero."""
+    doc = _extract(result.result_block(status="success"))
+    assert doc["status"] == "success"
+    assert doc["message"] == ""
+    assert doc["failures"] == 0

continuo_engine_contract-0.7.0/tests/test_sql.py

@@ -0,0 +1,103 @@
+"""Unit tests for the single-read gate every adapter runs before EXPLAIN."""
+import pytest
+
+from continuo_engine_contract.sql import ensure_single_read
+
+DIALECTS = ["postgres", "trino", None]
+
+# The read shapes a legitimate spec is allowed to declare. Every one of these
+# must survive the gate on every dialect — this list is the regression surface.
+LEGIT_READS = [
+    "select a, b from s.up",
+    "select * from s.up",
+    "select a from s.up where b = 'x;y' order by a limit 10",
+    "with c as (select a from s.up) select a from c",
+    "select a from s.up union all select a from s.up2",
+    "select a, count(*) from s.up group by a",
+    "select l.a from s.up l join s.up2 r on l.a = r.a",
+    "select 1",
+    "VALUES (1), (2)",
+    "select a as x, b as x from s.up",
+    "select a from s.up;",
+    "select a from s.up -- trailing comment",
+]
+
+# The paren-balanced escapes: the wrap alone lets these through, because the
+# read closes the wrap's own paren and reopens it after the injected statement.
+PAREN_ESCAPE_DELETE = "select 1) AS x; DELETE FROM s.target; SELECT * FROM (SELECT 1"
+PAREN_ESCAPE_DROP = "select 1) AS x; DROP TABLE s.target; SELECT * FROM (SELECT 1"
+
+STACKED = "select a from s.up; delete from s.up"
+
+BARE_DML = [
+    "delete from s.up",
+    "insert into s.up values (1)",
+    "update s.up set a = 1",
+    "drop table s.up",
+    "create table s.x (a int)",
+    "truncate table s.up",
+]
+
+
+@pytest.mark.parametrize("dialect", DIALECTS)
+@pytest.mark.parametrize("sql", LEGIT_READS)
+def test_legitimate_reads_pass(sql: str, dialect: str | None) -> None:
+    """Every legitimate read shape must survive the gate unchanged."""
+    ensure_single_read(sql, dialect=dialect)  # must not raise
+
+
+@pytest.mark.parametrize("dialect", DIALECTS)
+@pytest.mark.parametrize("sql", [PAREN_ESCAPE_DELETE, PAREN_ESCAPE_DROP])
+def test_paren_balanced_escape_is_rejected(sql: str, dialect: str | None) -> None:
+    """A read that balances the subquery wrap's parens must not reach the engine."""
+    with pytest.raises(ValueError):
+        ensure_single_read(sql, dialect=dialect)
+
+
+@pytest.mark.parametrize("dialect", DIALECTS)
+def test_stacked_statement_is_rejected(dialect: str | None) -> None:
+    """A naively stacked second statement is rejected as more than one statement."""
+    with pytest.raises(ValueError, match="exactly one"):
+        ensure_single_read(STACKED, dialect=dialect)
+
+
+@pytest.mark.parametrize("dialect", DIALECTS)
+@pytest.mark.parametrize("sql", BARE_DML)
+def test_bare_non_query_statements_are_rejected(sql: str, dialect: str | None) -> None:
+    """A single statement that is not a read is rejected as not a query."""
+    with pytest.raises(ValueError, match="read query"):
+        ensure_single_read(sql, dialect=dialect)
+
+
+@pytest.mark.parametrize("sql", [PAREN_ESCAPE_DELETE, STACKED, "delete from s.up"])
+def test_rejection_message_names_the_offending_read(sql: str) -> None:
+    """Every rejection must be actionable: it quotes the read that was rejected."""
+    with pytest.raises(ValueError) as excinfo:
+        ensure_single_read(sql, dialect="postgres")
+    message = str(excinfo.value)
+    assert "read" in message
+    assert sql[:30] in message
+
+
+def test_unparseable_read_is_rejected_as_valueerror_not_a_sqlglot_error() -> None:
+    """Callers catch ValueError; a sqlglot ParseError must never escape the gate."""
+    with pytest.raises(ValueError):
+        ensure_single_read("select from from where", dialect="postgres")
+
+
+def test_empty_read_is_rejected() -> None:
+    """An empty read parses to zero statements, which is not exactly one."""
+    with pytest.raises(ValueError, match="exactly one"):
+        ensure_single_read("   ", dialect="postgres")
+
+
+@pytest.mark.parametrize("sql", [
+    "delete from s.up where a in (" + ", ".join(str(i) for i in range(500)) + ")",
+    "select from from where " + ", ".join(str(i) for i in range(500)),  # ParseError path
+    "select a from s.up; " * 200,  # many-statements path
+])
+def test_long_read_is_truncated_in_the_message(sql: str) -> None:
+    """Every rejection message is bounded: it rides the result block to the controller."""
+    with pytest.raises(ValueError) as excinfo:
+        ensure_single_read(sql, dialect="postgres")
+    assert len(str(excinfo.value)) < 600