continuo-engine-contract 0.7.0__py3-none-any.whl

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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+continuo_engine_contract/__init__.py,sha256=mXee3I24TblD9SlhBH3nV3NaYqY4J3rxXPUsgoY1YT8,111
+continuo_engine_contract/config.py,sha256=qhin-NIydq-jufSOc4wQ-77DrdHHPawamsqW910XZhc,2059
+continuo_engine_contract/port.py,sha256=FnKHyVSyJyGlKsncsd9xWJxmL2v1BxQQFVJmJGe2_os,8560
+continuo_engine_contract/result.py,sha256=yuRRJIsyt76PYsnkmMt_RHbh0bs79qZHafy77y3IBFo,1284
+continuo_engine_contract/sql.py,sha256=WaZvxvZCQPiPV4pN5Hjk4neMlSAwm9z1RLwKHjxSAi0,3515
+continuo_engine_contract/types.py,sha256=WrFIZugxap0R6KqazV9EBJ_-JMCw3jeS0QtrjiT1BV0,825
+continuo_engine_contract-0.7.0.dist-info/METADATA,sha256=F0o3SkMmA3YU6bSS1fXg5bDOMTKYZAjFviFdSTepcd0,3788
+continuo_engine_contract-0.7.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+continuo_engine_contract-0.7.0.dist-info/RECORD,,

continuo_engine_contract-0.7.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any