turbine-core 1.0.0__tar.gz

turbine_core-1.0.0/.gitignore

@@ -0,0 +1,56 @@
+# Local system and Python files
+.DS_Store
+__pycache__/
+*.py[cod]
+.env
+.venv/
+
+# Builds and package metadata
+/build/
+dist/
+*.egg-info/
+target/
+
+# Test and quality-tool output
+.coverage
+.coverage.*
+htmlcov/
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+/tests/
+
+# Local package credentials
+.netrc
+.pypirc
+.beads/
+ai-docs/
+
+# Documentation build output
+public/
+
+# mutmut copies the sources here to mutate them
+mutants/
+
+# Generated tool/agent artifacts (graphify graphs, Pi subagent transcripts).
+# These are machine output, not source, and must not be committed.
+graphify-out/
+outputs/
+.serena/
+*.lit.*
+packages/turbine-serve/turbine-serve.pdf
+.pi/
+.pi-subagents/
+.claude/settings.local.json
+packages/turbine-core/.complexipy_cache/
+
+# Impeccable design context and scratch work
+.impeccable/
+/DESIGN.md
+/PRODUCT.md
+scratch/
+.cache/
+.delta/
+docs/assets/diagrams/turbine-extension-interface.html
+.complexipy_cache/
+.claude/

turbine_core-1.0.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: turbine-core
+Version: 1.0.0
+Summary: Turbine kernel: project snapshots, check-run pipeline, extension registry, and entrypoints
+Requires-Python: >=3.12
+Requires-Dist: annotated-types>=0.8.0
+Requires-Dist: asgiref>=3.12.1
+Requires-Dist: cyclopts>=5.1.0
+Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: prompt-toolkit>=3.0.53
+Requires-Dist: pydantic-core>=2.46.4
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: python-dotenv>=1.2.3
+Requires-Dist: referencing>=0.37.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: ruamel-yaml>=0.18.16
+Requires-Dist: semver>=3.0.4
+Requires-Dist: sqlglot>=30.16.0
+Requires-Dist: tree-sitter-yaml>=0.7.2
+Requires-Dist: tree-sitter>=0.26.0
+Requires-Dist: typing-extensions>=4.16.0
+Requires-Dist: typing-inspection>=0.4.4
+Requires-Dist: tzdata>=2026.3
+Provides-Extra: editor
+Requires-Dist: lsprotocol>=2023.0.1; extra == 'editor'
+Requires-Dist: pygls>=2; extra == 'editor'
+Provides-Extra: serve
+Requires-Dist: anyio>=4; extra == 'serve'
+Requires-Dist: asgi-lifespan>=2.1.0; extra == 'serve'
+Requires-Dist: litestar>=2.15; extra == 'serve'
+Requires-Dist: uvicorn>=0.34; extra == 'serve'
+Description-Content-Type: text/markdown
+
+# turbine-core
+
+Turbine checks that your data agrees with its Data Contract. You describe a table in a YAML
+file, and Turbine compares the file with the live table and tests the data against the rules
+in the file.
+
+`turbine-core` is the kernel. It gives the `turbine` command, the Project model, and the
+check run. It has no formats, check types, or database drivers of its own. Those come from
+an Extension, such as `turbine-data`.
+
+## Install
+
+Install `turbine-data` with the driver of your database. It installs `turbine-core` too:
+
+```console
+uv add "turbine-data[duckdb]"
+uv run turbine --help
+```
+
+`turbine-core` has two extras:
+
+| Extra | What it adds |
+| --- | --- |
+| `serve` | The `turbine serve` command and the Management API |
+| `editor` | `turbine-lsp`, the language server for an editor |

turbine_core-1.0.0/README.md

@@ -0,0 +1,25 @@
+# turbine-core
+
+Turbine checks that your data agrees with its Data Contract. You describe a table in a YAML
+file, and Turbine compares the file with the live table and tests the data against the rules
+in the file.
+
+`turbine-core` is the kernel. It gives the `turbine` command, the Project model, and the
+check run. It has no formats, check types, or database drivers of its own. Those come from
+an Extension, such as `turbine-data`.
+
+## Install
+
+Install `turbine-data` with the driver of your database. It installs `turbine-core` too:
+
+```console
+uv add "turbine-data[duckdb]"
+uv run turbine --help
+```
+
+`turbine-core` has two extras:
+
+| Extra | What it adds |
+| --- | --- |
+| `serve` | The `turbine serve` command and the Management API |
+| `editor` | `turbine-lsp`, the language server for an editor |

turbine_core-1.0.0/formal/product_line.dfy

@@ -0,0 +1,176 @@
+// Formal model of `ProductLine.latest`
+// (turbine.core.application.load_project.product_line) over `ProductKey` order
+// (turbine.core.domain.product.key).
+//
+// The rule: the highest SemVer whose contract is not dying, else the highest
+// version with a warning. A product without a version sorts below every
+// versioned one and never counts as the latest while a versioned one exists.
+//
+// Model gap: SemVer is abstracted to a `nat` rank that `ProductKey.sort_key`
+// supplies; `lines_of` sorts by that key, so `versions` is ascending here.
+
+datatype Product = Product(versioned: bool, rank: nat, dying: bool)
+
+// `ProductKey.sort_key` order restricted to one id: unversioned first, then rank.
+predicate Leq(a: Product, b: Product) {
+  (!a.versioned && b.versioned) ||
+  (a.versioned == b.versioned && a.rank <= b.rank)
+}
+
+predicate Ascending(s: seq<Product>) {
+  forall i, j :: 0 <= i < j < |s| ==> Leq(s[i], s[j])
+}
+
+// The two filters in `ProductLine.latest`, written out so Z3 can unfold them.
+function Versioned(s: seq<Product>): seq<Product> {
+  if |s| == 0 then []
+  else if s[0].versioned then [s[0]] + Versioned(s[1..])
+  else Versioned(s[1..])
+}
+
+function Live(s: seq<Product>): seq<Product> {
+  if |s| == 0 then []
+  else if !s[0].dying then [s[0]] + Live(s[1..])
+  else Live(s[1..])
+}
+
+// `ProductLine.latest`, line for line.
+function Latest(versions: seq<Product>): Product
+  requires |versions| > 0
+{
+  var versioned := Versioned(versions);
+  var candidates := if |versioned| > 0 then versioned else versions;
+  var live := Live(candidates);
+  var pool := if |live| > 0 then live else candidates;
+  pool[|pool| - 1]
+}
+
+// --- Facts about the filters -------------------------------------------------
+
+lemma VersionedFacts(s: seq<Product>)
+  ensures forall p :: p in Versioned(s) <==> (p in s && p.versioned)
+  ensures Ascending(s) ==> Ascending(Versioned(s))
+{
+  if |s| > 0 {
+    VersionedFacts(s[1..]);
+    if Ascending(s) {
+      assert Ascending(s[1..]);
+      var v := Versioned(s);
+      forall i, j | 0 <= i < j < |v| ensures Leq(v[i], v[j]) {
+        assert v[j] in s[1..];
+        if s[0].versioned && i == 0 {
+          var k :| 0 <= k < |s[1..]| && s[1..][k] == v[j];
+          assert Leq(s[0], s[k + 1]);
+        } else {
+          var v1 := Versioned(s[1..]);
+          var off := if s[0].versioned then 1 else 0;
+          assert v[i] == v1[i - off] && v[j] == v1[j - off];
+        }
+      }
+    }
+  }
+}
+
+lemma LiveFacts(s: seq<Product>)
+  ensures forall p :: p in Live(s) <==> (p in s && !p.dying)
+  ensures Ascending(s) ==> Ascending(Live(s))
+{
+  if |s| > 0 {
+    LiveFacts(s[1..]);
+    if Ascending(s) {
+      assert Ascending(s[1..]);
+      var v := Live(s);
+      forall i, j | 0 <= i < j < |v| ensures Leq(v[i], v[j]) {
+        assert v[j] in s[1..];
+        if !s[0].dying && i == 0 {
+          var k :| 0 <= k < |s[1..]| && s[1..][k] == v[j];
+          assert Leq(s[0], s[k + 1]);
+        } else {
+          var v1 := Live(s[1..]);
+          var off := if !s[0].dying then 1 else 0;
+          assert v[i] == v1[i - off] && v[j] == v1[j - off];
+        }
+      }
+    }
+  }
+}
+
+lemma LastIsMax(s: seq<Product>)
+  requires Ascending(s) && |s| > 0
+  ensures forall p :: p in s ==> Leq(p, s[|s| - 1])
+{
+  forall p | p in s ensures Leq(p, s[|s| - 1]) {
+    var i :| 0 <= i < |s| && s[i] == p;
+    if i < |s| - 1 { assert Leq(s[i], s[|s| - 1]); }
+  }
+}
+
+// --- Properties (tests/application/load_project/test_product_line.py) -------
+
+// latest is one of the versions.
+lemma LatestIsMember(versions: seq<Product>)
+  requires |versions| > 0
+  ensures Latest(versions) in versions
+{
+  VersionedFacts(versions);
+  var candidates := if |Versioned(versions)| > 0 then Versioned(versions) else versions;
+  LiveFacts(candidates);
+}
+
+// "none-never-wins": while a versioned product exists, latest is versioned.
+lemma LatestIsVersionedWhenAnyIs(versions: seq<Product>)
+  requires |versions| > 0
+  requires exists p :: p in versions && p.versioned
+  ensures Latest(versions).versioned
+{
+  VersionedFacts(versions);
+  var versioned := Versioned(versions);
+  assert |versioned| > 0;
+  LiveFacts(versioned);
+}
+
+// "skips-dying": while a live versioned product exists, latest is live.
+lemma LatestIsLiveWhenAnyIs(versions: seq<Product>)
+  requires |versions| > 0
+  requires exists p :: p in versions && p.versioned && !p.dying
+  ensures !Latest(versions).dying
+{
+  VersionedFacts(versions);
+  var versioned := Versioned(versions);
+  assert |versioned| > 0;
+  LiveFacts(versioned);
+  assert |Live(versioned)| > 0;
+}
+
+// "highest-live": latest is the maximum of every eligible product.
+lemma LatestIsHighestEligible(versions: seq<Product>)
+  requires |versions| > 0 && Ascending(versions)
+  requires exists p :: p in versions && p.versioned && !p.dying
+  ensures forall p :: p in versions && p.versioned && !p.dying ==> Leq(p, Latest(versions))
+{
+  VersionedFacts(versions);
+  var versioned := Versioned(versions);
+  assert |versioned| > 0;
+  LiveFacts(versioned);
+  var live := Live(versioned);
+  assert |live| > 0;
+  LastIsMax(live);
+}
+
+// "all-dying-takes-highest": with no live versioned product, latest is the
+// highest versioned one.
+lemma LatestIsHighestWhenAllDying(versions: seq<Product>)
+  requires |versions| > 0 && Ascending(versions)
+  requires exists p :: p in versions && p.versioned
+  requires forall p :: p in versions && p.versioned ==> p.dying
+  ensures forall p :: p in versions && p.versioned ==> Leq(p, Latest(versions))
+{
+  VersionedFacts(versions);
+  var versioned := Versioned(versions);
+  assert |versioned| > 0;
+  LiveFacts(versioned);
+  assert |Live(versioned)| == 0 by {
+    if |Live(versioned)| > 0 { assert Live(versioned)[0] in Live(versioned); }
+  }
+  LastIsMax(versioned);
+}

turbine_core-1.0.0/formal/thresholds.dfy

@@ -0,0 +1,119 @@
+// Formal model of `turbine.core.domain.product.quality.threshold_holds`.
+//
+// The Python decides pass/fail of every Check Definition. This file states
+// the same rule over reals and proves the properties the Hypothesis tests in
+// tests/domain/test_thresholds.py sample. Verify with `dafny verify`.
+//
+// Model gap: Python measures with `Decimal(str(float))`; this model uses
+// `real`. The Hypothesis tests cover that seam; the lemmas cover the logic.
+
+datatype Option<T> = None | Some(value: T)
+
+datatype Bound = Bound(value: real, exclusive: bool)
+
+datatype Op = LT | LTE | GTE | GT
+
+datatype Threshold =
+  | Exact(v: real)
+  | NotExact(v: real)
+  | Cmp(op: Op, v: real)
+  | Range(min: Option<Bound>, max: Option<Bound>)
+  | NotRange(lo: Bound, hi: Bound)
+
+// `RangeThreshold.__post_init__`: at least one bound.
+predicate WellFormed(t: Threshold) {
+  t.Range? ==> (t.min.Some? || t.max.Some?)
+}
+
+function Compare(op: Op, m: real, v: real): bool {
+  match op
+  case LT  => m < v
+  case LTE => m <= v
+  case GT  => m > v
+  case GTE => m >= v
+}
+
+// `_above`
+function Above(m: real, b: Option<Bound>): bool {
+  match b
+  case None => true
+  case Some(bound) => if bound.exclusive then m > bound.value else m >= bound.value
+}
+
+// `_below`
+function Below(m: real, b: Option<Bound>): bool {
+  match b
+  case None => true
+  case Some(bound) => if bound.exclusive then m < bound.value else m <= bound.value
+}
+
+// `threshold_holds` for a present threshold and a present measurement.
+function Holds(t: Threshold, m: real): bool {
+  match t
+  case Exact(v) => m == v
+  case NotExact(v) => m != v
+  case Cmp(op, v) => Compare(op, m, v)
+  case Range(lo, hi) => Above(m, lo) && Below(m, hi)
+  case NotRange(lo, hi) => !(Above(m, Some(lo)) && Below(m, Some(hi)))
+}
+
+// `threshold_holds` including the two absent cases.
+function HoldsOpt(t: Option<Threshold>, m: Option<real>): bool {
+  match t
+  case None => true
+  case Some(threshold) =>
+    match m
+    case None => false
+    case Some(measured) => Holds(threshold, measured)
+}
+
+// --- Properties -------------------------------------------------------------
+
+// tests: test_not_range_is_the_complement_of_range
+lemma NotRangeIsComplementOfRange(lo: Bound, hi: Bound, m: real)
+  ensures Holds(NotRange(lo, hi), m) == !Holds(Range(Some(lo), Some(hi)), m)
+{}
+
+// tests: test_an_exclusive_end_rejects_its_own_value
+lemma InclusiveEndAcceptsItself(x: real)
+  ensures Holds(Range(Some(Bound(x, false)), None), x)
+  ensures Holds(Range(None, Some(Bound(x, false))), x)
+{}
+
+lemma ExclusiveEndRejectsItself(x: real)
+  ensures !Holds(Range(Some(Bound(x, true)), None), x)
+  ensures !Holds(Range(None, Some(Bound(x, true))), x)
+{}
+
+// Exact and NotExact are complements.
+lemma ExactIsComplementOfNotExact(v: real, m: real)
+  ensures Holds(Exact(v), m) == !Holds(NotExact(v), m)
+{}
+
+// LT/GTE and LTE/GT are complements: no measurement is undecided.
+lemma ComparisonsAreComplements(v: real, m: real)
+  ensures Holds(Cmp(LT, v), m) == !Holds(Cmp(GTE, v), m)
+  ensures Holds(Cmp(LTE, v), m) == !Holds(Cmp(GT, v), m)
+{}
+
+// A one-sided range is the matching comparison.
+lemma OneSidedRangeIsComparison(v: real, m: real)
+  ensures Holds(Range(Some(Bound(v, false)), None), m) == Holds(Cmp(GTE, v), m)
+  ensures Holds(Range(Some(Bound(v, true)), None), m) == Holds(Cmp(GT, v), m)
+  ensures Holds(Range(None, Some(Bound(v, false))), m) == Holds(Cmp(LTE, v), m)
+  ensures Holds(Range(None, Some(Bound(v, true))), m) == Holds(Cmp(LT, v), m)
+{}
+
+// Tightening a bound never accepts more.
+lemma ExclusiveIsStricter(lo: Bound, hi: Bound, m: real)
+  requires !lo.exclusive && !hi.exclusive
+  ensures Holds(Range(Some(Bound(lo.value, true)), Some(Bound(hi.value, true))), m)
+          ==> Holds(Range(Some(lo), Some(hi)), m)
+{}
+
+// tests: test_threshold_holds_decision_table_at_the_edges
+lemma AbsentCases(t: Threshold, m: real)
+  ensures HoldsOpt(None, Some(m))
+  ensures HoldsOpt(None, None)
+  ensures !HoldsOpt(Some(t), None)
+{}

turbine_core-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "turbine-core"
+version = "1.0.0"
+description = "Turbine kernel: project snapshots, check-run pipeline, extension registry, and entrypoints"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+  "annotated-types>=0.8.0",
+  "asgiref>=3.12.1",
+  "cyclopts>=5.1.0",
+  "jsonschema>=4.26.0",
+  "prompt-toolkit>=3.0.53",
+  "pydantic>=2.13.4",
+  "pydantic-core>=2.46.4",
+  "python-dotenv>=1.2.3",
+  "referencing>=0.37.0",
+  "rich>=15.0.0",
+  "ruamel-yaml>=0.18.16",
+  "semver>=3.0.4",
+  "sqlglot>=30.16.0",
+  "tree-sitter>=0.26.0",
+  "tree-sitter-yaml>=0.7.2",
+  "typing-extensions>=4.16.0",
+  "typing-inspection>=0.4.4",
+  "tzdata>=2026.3",
+]
+
+[project.optional-dependencies]
+editor = ["lsprotocol>=2023.0.1", "pygls>=2"]
+serve = ["anyio>=4", "asgi-lifespan>=2.1.0", "litestar>=2.15", "uvicorn>=0.34"]
+
+[project.scripts]
+turbine = "turbine.core.hosts.cli.__main__:main"
+turbine-lsp = "turbine.core.hosts.editor.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/turbine"]
+
+[dependency-groups]
+dev = ["duckdb>=1.5.5", "pyarrow>=25.0.1", "pytest>=9.1.1"]
+
+[tool.mutmut]
+source_paths = ["src/turbine"]
+# format_model.py is excluded because mutmut breaks its metaclass generator.
+do_not_mutate = ["src/turbine/core/authoring/format/declare/format_model.py"]
+pytest_add_cli_args = ["-p", "no:tach", "tests"]

turbine_core-1.0.0/src/turbine/core/__init__.py

@@ -0,0 +1,9 @@
+"""Turbine kernel: define, check, and serve Data Products from their contracts."""
+
+import logging
+
+# A library does not choose where its log goes. Without a handler, Python
+# prints each warning and error to stderr, and that would put driver text in
+# the normal command output. `--debug` and the editor server add their own
+# handler.
+logging.getLogger("turbine").addHandler(logging.NullHandler())

turbine_core-1.0.0/src/turbine/core/app/CONTRACTS

@@ -0,0 +1,29 @@
+@cc [owner:Yassimba] profile.measures-are-check-types
+Applies only to `profile_table` in `profile.py`.
+
+Each number in `measures` is the measurement that a Check Engine gives for an installed Check
+Type. The profile holds no SQL for such a number, and it names no Check Type.
+
+@cc [owner:Yassimba] profile.values-count-the-profiled-rows
+Applies only to `profile_table` in `profile.py`.
+
+The most frequent values and the histogram of a column read rows as the measures do: the rows
+of the filter of the Dataset and of the time window, and at most `sample` of them.
+
+@cc [owner:Yassimba] profile.read-only
+Applies only to `profile_table` in `profile.py`.
+
+A profile writes nothing: no table, no file, and no Run History.
+
+@cc [owner:Yassimba] profile.sample-is-a-limit
+Applies only to `profile_table` in `profile.py`.
+
+No query of a profile sorts the rows of the table. `sample` is a row limit, so the database
+stops when it has that many rows, in no order. `sample` 0 reads each row.
+
+@cc [owner:Yassimba] profile.window-is-the-event-time
+Applies only to `profile_table` in `profile.py`.
+
+`since` and `until` keep the rows with `since <= event time < until`, by the event time of the
+Dataset, as the Check Window of a Check Run does. A time for a table that has no event time
+raises ProfileRefusedError before a query runs.

turbine_core-1.0.0/src/turbine/core/app/__init__.py

@@ -0,0 +1,31 @@
+"""The application: `Turbine`, the composition root that a host holds, and its verb families.
+
+A host imports an `app` name from the module that defines it, for example
+`turbine.core.app.turbine`. This module names only the kernel values that a
+host needs but cannot import from their own context. The tach rules do not
+let the CLI and serve hosts import `runs`, `project`, `catalog`, `flags`, or
+`plugins`. The editor cannot import `runs`.
+"""
+
+from turbine.core.catalog.datasources.connections import ConnectionOpener as ConnectionOpener
+from turbine.core.catalog.datasources.connections import OpenableDatasource as OpenableDatasource
+from turbine.core.catalog.datasources.declarations import TableIdentifier as TableIdentifier
+from turbine.core.flags.model import UnknownFlaggedTableError as UnknownFlaggedTableError
+from turbine.core.plugins.discovery import ExtensionDiscovery as ExtensionDiscovery
+from turbine.core.project.layout import DEFAULT_MAX_CONCURRENCY as DEFAULT_MAX_CONCURRENCY
+from turbine.core.project.layout import ProjectConfigError as ProjectConfigError
+from turbine.core.project.layout import ProjectLayout as ProjectLayout
+from turbine.core.project.request_errors import CheckRunError as CheckRunError
+from turbine.core.project.request_errors import UnknownChoiceError as UnknownChoiceError
+from turbine.core.project.rules.project_rules import LintRunError as LintRunError
+from turbine.core.project.server_binder import ServerRequest as ServerRequest
+from turbine.core.project.snapshot import ProjectSnapshot as ProjectSnapshot
+from turbine.core.runs.history.store import RunHistoryPreparationError as RunHistoryPreparationError
+from turbine.core.runs.plan import CheckRunRequest as CheckRunRequest
+from turbine.core.runs.plan import CheckSelection as CheckSelection
+from turbine.core.runs.plan import PlannedDataset as PlannedDataset
+from turbine.core.runs.plan import RunId as RunId
+from turbine.core.runs.plan import RunKind as RunKind
+from turbine.core.runs.plan import RunPlan as RunPlan
+from turbine.core.runs.ports import RunHistoryUnavailableError as RunHistoryUnavailableError
+from turbine.core.runs.window import parse_time as parse_time