sqlbuild 0.4.0__tar.gz → 0.8.0__tar.gz

sqlbuild-0.8.0/.gitignore

@@ -0,0 +1,58 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Python packaging
+build/
+!src/sqlbuild/**/build/
+!tests/**/build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test and coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Type checkers and tooling
+.mypy_cache/
+.ruff_cache/
+.pyre/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Editors and OS files
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Logs
+*.log
+
+# Local databases and data
+*.db
+*.duckdb
+*.duckdb.wal
+*.sqlite
+*.sqlite3
+data/
+
+# Local artifacts
+target/
+
+# Local SQLBuild overrides
+sqlbuild_local.yml
+**/sqlbuild_local.yml
+sqlbuild_local.toml
+**/sqlbuild_local.toml

sqlbuild-0.8.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.8.0"
+}

sqlbuild-0.8.0/CHANGELOG.md

@@ -0,0 +1,292 @@
+# Changelog
+
+## [0.8.0](https://github.com/chio-labs/sqlbuild/compare/v0.7.0...v0.8.0) (2026-05-09)
+
+
+### Features
+
+* add scenario test CLI ([8ff989a](https://github.com/chio-labs/sqlbuild/commit/8ff989a4bc98fbf095b39106bf6b73f88aec071e))
+* add SQL unit test assertions ([640fbcb](https://github.com/chio-labs/sqlbuild/commit/640fbcb2fdcb090bba221524af32d665427a557e))
+* add waffle shop playground ([a91f805](https://github.com/chio-labs/sqlbuild/commit/a91f805ac8a0eeaf5bf830a2dfdfe0d22c85f2e0))
+* clean scenario artifacts ([2293a8a](https://github.com/chio-labs/sqlbuild/commit/2293a8a97098c3fa5a90ae7314dc06f1a89875bd))
+* clean scenario artifacts with janitor ([19df620](https://github.com/chio-labs/sqlbuild/commit/19df620850dee53bf09724f91a3f3469d2468e13))
+* discover SQL scenarios ([d280dff](https://github.com/chio-labs/sqlbuild/commit/d280dff043714a7f48dc1b5de0c63291b06bdd68))
+* execute scenario checks ([a32ad16](https://github.com/chio-labs/sqlbuild/commit/a32ad16e2607fa02c6678c4582167c8ce0118cc0))
+* execute scenario model graph ([8cba144](https://github.com/chio-labs/sqlbuild/commit/8cba1444d1fa3fd0dadcdae989a69fc810206960))
+* extract scenario CTE roles ([0ecbabf](https://github.com/chio-labs/sqlbuild/commit/0ecbabfba117c7eca1d3e4635e5117ac508f47b5))
+* infer scenario graph requirements ([555d545](https://github.com/chio-labs/sqlbuild/commit/555d54514cb6e0e4f664040c573901dcc0ed15b6))
+* load scenario project seeds ([0b52756](https://github.com/chio-labs/sqlbuild/commit/0b52756863816e7aa1d15af273619b607ea73293))
+* materialize scenario fixtures ([b49179a](https://github.com/chio-labs/sqlbuild/commit/b49179a2990aeb9b6cb7fe2c48bdd2c83b7a3784))
+* name scenario artifacts ([93e0cb6](https://github.com/chio-labs/sqlbuild/commit/93e0cb6de5eddafbc6b7969fce90069ddba1d63f))
+* plan scenario fixture SQL ([8fd0a69](https://github.com/chio-labs/sqlbuild/commit/8fd0a69e732d03620d4fa6cc2b50e83b77a8ceb0))
+* plan scenario relation overrides ([1dfb94b](https://github.com/chio-labs/sqlbuild/commit/1dfb94bc8797cf0250f517eedc91015e7040306b))
+* show nested SQL unit test checks ([b096564](https://github.com/chio-labs/sqlbuild/commit/b0965646820fc96e27e4576b37e9e25bf00f7eb8))
+* write scenario runtime artifacts ([8add531](https://github.com/chio-labs/sqlbuild/commit/8add531783f03dc348368f6547e61da941f0ec16))
+
+
+### Bug Fixes
+
+* keep playground install minimal ([e67a144](https://github.com/chio-labs/sqlbuild/commit/e67a14464c90653373eddd4bdfef46855802a6fc))
+
+## [0.7.0](https://github.com/chio-labs/sqlbuild/compare/v0.6.0...v0.7.0) (2026-05-07)
+
+
+### Features
+
+* add accepted values and relationships audits ([7a12fd3](https://github.com/chio-labs/sqlbuild/commit/7a12fd3098dfe885a73f7a8922daa28e3893a1e0))
+* add nullable contracts and built-in audits ([611f99a](https://github.com/chio-labs/sqlbuild/commit/611f99a689440b29af5ebe835e27de6967c60d8d))
+* add spinner based CLI progress ([9cce465](https://github.com/chio-labs/sqlbuild/commit/9cce465c454895bc79a35e9bee3cadbcd2ca34b3))
+* add spinner based CLI progress ([9664cd9](https://github.com/chio-labs/sqlbuild/commit/9664cd9eb608819806cc2d7f9d59d57ecedbf987))
+* align config and table function names ([b011ead](https://github.com/chio-labs/sqlbuild/commit/b011eadb0b9d3991dcdf53f522bb8d6f73682974))
+* align config and table function names ([ec77895](https://github.com/chio-labs/sqlbuild/commit/ec7789511c095bd1d572a570e73a5a8e5867598d))
+* show progress errors below rows ([cbe4a2a](https://github.com/chio-labs/sqlbuild/commit/cbe4a2a76232c0b854a369e5af02f5ebb0fbc5d8))
+* show progress errors below rows ([4908b24](https://github.com/chio-labs/sqlbuild/commit/4908b24ef7e9d627d5c354dc5ebebdc255a38991))
+* unify authored SQL interpolation ([c1d7e77](https://github.com/chio-labs/sqlbuild/commit/c1d7e77ec2545877949d59288d7c942afe031de3))
+* unify CLI progress output ([0695eea](https://github.com/chio-labs/sqlbuild/commit/0695eeaca6b49e15152bead00e578c1f647c4936))
+
+
+### Bug Fixes
+
+* align plan output columns ([8af7b74](https://github.com/chio-labs/sqlbuild/commit/8af7b740be77138b773fb44a4366a14bbad5d828))
+* narrow function change fingerprints ([5bc5896](https://github.com/chio-labs/sqlbuild/commit/5bc58967bfa26e6330a78d4657f19a2bb4fd13ee))
+* narrow function change fingerprints ([a0bf9bf](https://github.com/chio-labs/sqlbuild/commit/a0bf9bf4a020a84066078d798b9b9fc76af7b591))
+* respect disabled sqlglot setting ([11ca558](https://github.com/chio-labs/sqlbuild/commit/11ca55858ac91a9be060f22b100fca4a938c80ac))
+
+
+### Documentation
+
+* add contributing guide and update logo ([4e3ce74](https://github.com/chio-labs/sqlbuild/commit/4e3ce748497d3eec80b85387f9f9e261ee715c30))
+* use relative README logo path ([0203ad8](https://github.com/chio-labs/sqlbuild/commit/0203ad8ca827f8d9c23309432601ce27b27b4b82))
+
+## [0.6.0](https://github.com/chio-labs/sqlbuild/compare/v0.5.0...v0.6.0) (2026-05-07)
+
+
+### Features
+
+* add column lineage analyzer ([f60c65d](https://github.com/chio-labs/sqlbuild/commit/f60c65d1b4fd7d7d9512d75023f829888e555fb6))
+* add column lineage CLI traces ([83977a0](https://github.com/chio-labs/sqlbuild/commit/83977a048fe6dc978909b85ddbf1c619ba39468f))
+* add compile contract diagnostics ([0ba4d65](https://github.com/chio-labs/sqlbuild/commit/0ba4d65e66a1df8b519ac62a6b9e2941f0998b83))
+* add conservative nullability inference ([74b6bb2](https://github.com/chio-labs/sqlbuild/commit/74b6bb22a614fae5c106a48032e54107b0b8a479))
+* add fast compile lineage mode ([19fb926](https://github.com/chio-labs/sqlbuild/commit/19fb9261d13bb1947b990fe35a5363957cca2bc7))
+* add lineage mode metadata ([726ebb0](https://github.com/chio-labs/sqlbuild/commit/726ebb04fa08178dbf323ad1632e03c341272af4))
+* improve compile output ([8bb26f9](https://github.com/chio-labs/sqlbuild/commit/8bb26f97e5770895ea472dea27f06cda3d50ff9c))
+* make compile offline ([0099e0d](https://github.com/chio-labs/sqlbuild/commit/0099e0d61f458f68ba14b53531826a5ac77c9fa6))
+* scope rich column lineage ([521e47a](https://github.com/chio-labs/sqlbuild/commit/521e47adfde3f6cdb42cc8b5772553df4ca20e91))
+
+## [0.5.0](https://github.com/chio-labs/sqlbuild/compare/v0.4.0...v0.5.0) (2026-05-06)
+
+
+### Features
+
+* switch project config to TOML ([e7127b0](https://github.com/chio-labs/sqlbuild/commit/e7127b00663b4773d1897500ebc1492b25dff285))
+* switch project config to TOML ([b6f208d](https://github.com/chio-labs/sqlbuild/commit/b6f208d7ca8f39a7bf9bce15c9d964a2df90f941))
+
+## [0.4.0](https://github.com/chio-labs/sqlbuild/compare/v0.3.0...v0.4.0) (2026-05-05)
+
+
+### Features
+
+* add debug command ([b7a67f5](https://github.com/chio-labs/sqlbuild/commit/b7a67f5fbc4bcb963ac36988f6a18a9127742d91))
+* add debug command ([1193f75](https://github.com/chio-labs/sqlbuild/commit/1193f75149787bac84f3907ef166409020a64814))
+
+## [0.3.0](https://github.com/chio-labs/sqlbuild/compare/v0.2.1...v0.3.0) (2026-05-05)
+
+
+### Features
+
+* add lineage command ([9aef7d6](https://github.com/chio-labs/sqlbuild/commit/9aef7d69ad556a2ef0ec568f1aed4492a119dfff))
+* add lineage command ([a0af73a](https://github.com/chio-labs/sqlbuild/commit/a0af73adfd5dba1870ff5b3b7293a78967a578c8))
+
+## [0.2.1](https://github.com/chio-labs/sqlbuild/compare/v0.2.0...v0.2.1) (2026-05-05)
+
+
+### Bug Fixes
+
+* render README correctly on PyPI ([8abf270](https://github.com/chio-labs/sqlbuild/commit/8abf270a77aabd1040ce223fc9f377eb168bfe39))
+* render README correctly on PyPI ([8251c0d](https://github.com/chio-labs/sqlbuild/commit/8251c0d6bf5b8277d36a7756c1fa95b04d1df698))
+
+## [0.2.0](https://github.com/chio-labs/sqlbuild/compare/v0.1.0...v0.2.0) (2026-05-05)
+
+
+### Features
+
+* add --defer-to support with deferred target resolution, buildability checks, and SC026 limit fix ([2097d80](https://github.com/chio-labs/sqlbuild/commit/2097d8020b3c0aa970ab7b7b038ab2aa2534fe09))
+* add --json output flag for sqb compile and sqb plan commands ([008d938](https://github.com/chio-labs/sqlbuild/commit/008d938ca6dfc53a4dbeab9aa63c5b9024a97596))
+* add --verbose flag to build/run showing full model DDL and audit SQL inline ([3f3cfe0](https://github.com/chio-labs/sqlbuild/commit/3f3cfe01dd256effdf71d24200b425cd10660337))
+* add adapter spine with base/strict adapters and compile assembly ([b72fbff](https://github.com/chio-labs/sqlbuild/commit/b72fbff3b15680b795ddaa864c867b451cfb9f7f))
+* add append cursor boundary control ([796af13](https://github.com/chio-labs/sqlbuild/commit/796af130cfa2fa79e595023187a950043bc34336))
+* add audit scheduling with attachment resolution, graph validation, and effective run scope degradation ([587d51e](https://github.com/chio-labs/sqlbuild/commit/587d51ebd44a28b8d64c5cb1413443710a52e4ec))
+* add audit/test plan entries with chained test resolution and unresolved ref validation ([b1e0be7](https://github.com/chio-labs/sqlbuild/commit/b1e0be74183a454e34662c1ca675e44fcce1c3fb))
+* add backfill cascade propagation with duration comparison, root cause attribution, and cross-type rules ([f27eb09](https://github.com/chio-labs/sqlbuild/commit/f27eb09435bff1a53b9eb27393271e7cb815193e))
+* add BigQuery adapter support ([f79ff90](https://github.com/chio-labs/sqlbuild/commit/f79ff90b813cf751d5a5313416eb9a0be3ff60e7))
+* add BigQuery warehouse parity ([1415f8e](https://github.com/chio-labs/sqlbuild/commit/1415f8e7ba8e48457d5ed0691a486212a85dee3a))
+* add build executor with topo execution, failure propagation, source/end audits, and direct/staged mode support ([d31466d](https://github.com/chio-labs/sqlbuild/commit/d31466d51d55234f4a73c66dd6b59e9a49f853b2))
+* add build output formatter with live progress, color support, and duration tracking ([42d1218](https://github.com/chio-labs/sqlbuild/commit/42d12183b2c3dd012f541d5cc8d753ae634bf09e))
+* add buildability checks validating upstream deps exist in scope or warehouse ([00f8c99](https://github.com/chio-labs/sqlbuild/commit/00f8c9946be85cb3e79416caa86e854fb3ea2230))
+* add change detection with query/schema comparison, backfill policy resolution, and SC033 cross-package import rule ([97e4582](https://github.com/chio-labs/sqlbuild/commit/97e45826398882c381f936ebf15cbf271a11c885))
+* add clone command support ([350a94b](https://github.com/chio-labs/sqlbuild/commit/350a94bd2698ee6ced0bd5b3604c0597b6de6c1f))
+* add compile input attachment layer ([724c936](https://github.com/chio-labs/sqlbuild/commit/724c9364d565623537a974effff6723966c4adcf))
+* add compile-time sql macro expansion ([1e78559](https://github.com/chio-labs/sqlbuild/commit/1e78559591edf9c081c358760a0474206e4494a4))
+* add compile-time SQL syntax validation with project, model, and CLI escape hatches ([02b16f5](https://github.com/chio-labs/sqlbuild/commit/02b16f55655936d5d706a9fbcf0878915be8c02b))
+* add concurrent build scheduler with ready-queue DAG dispatch ([92ad4c4](https://github.com/chio-labs/sqlbuild/commit/92ad4c48342ee94df59e288838e5f4a20c7e2d87))
+* add ctx.execute_sql() for custom materializations and require statement_recorder on adapter write methods ([353b1ea](https://github.com/chio-labs/sqlbuild/commit/353b1eaf995ee7c47c2fa1c27b8d59be2c479ca9))
+* add cursor start floors ([a47cfa5](https://github.com/chio-labs/sqlbuild/commit/a47cfa5be7cf7a85718dbc46fe79c599ec56fb54))
+* add cursor_type/validation/typed overrides/sql vars with StrEnum enforcement ([418925c](https://github.com/chio-labs/sqlbuild/commit/418925c3b5d9eefe33ed3303b09e647c6354810a))
+* add custom materializations with @[@placeholder](https://github.com/placeholder) support and user-callable audits ([d9e1592](https://github.com/chio-labs/sqlbuild/commit/d9e1592560f6fbb31d210046f3f9c84e5fbb43e7))
+* add Databricks adapter support ([e692ce6](https://github.com/chio-labs/sqlbuild/commit/e692ce64e19a7156d5c1a6ff7a41b9401107e2e7))
+* add Databricks Python UDF support ([849e759](https://github.com/chio-labs/sqlbuild/commit/849e759b5aa95c26c65e733d704e3f7057f7cf3a))
+* add DuckDB adapter with full method coverage and remove unused ResolutionMixin ([57ec8d9](https://github.com/chio-labs/sqlbuild/commit/57ec8d97ad5a12d254c492c8ceccadde2797eb18))
+* add e2e tests for all CLI commands and fix --project-dir relative database path resolution ([170b4b5](https://github.com/chio-labs/sqlbuild/commit/170b4b564c2e61462f12917b6a7b82fb37d4fbca))
+* add environment diff command support ([c46fdca](https://github.com/chio-labs/sqlbuild/commit/c46fdca731bcfef3d30242c14337e7c76afd47b9))
+* add executor build runtime stage 1 spec and validation enums, settings, audit severity/run_scope resolution, and non-incremental config guards ([70172f1](https://github.com/chio-labs/sqlbuild/commit/70172f160f3da29b9b7aa1ef882743e70f006d0f))
+* add fingerprint storage with per-schema read/write and hash computation ([727b2d5](https://github.com/chio-labs/sqlbuild/commit/727b2d5857fa804035f5b9ff5ae815b911807278))
+* add incremental executor with delta/DML lifecycle, schema change handling, and adapter DDL methods ([cf20aec](https://github.com/chio-labs/sqlbuild/commit/cf20aec008dd817599c313f6163a939dad10f203))
+* add Layer 5 ref resolution with cursor bounds, source CAST wrapping, and batched snapshot gathering ([4bf9975](https://github.com/chio-labs/sqlbuild/commit/4bf9975a22c95845b4d864770f4f962802df9daf))
+* add Layer 6 materialization strategy, plan output, and execution plan orchestration ([4061622](https://github.com/chio-labs/sqlbuild/commit/4061622247faced889fd5504264a54013f2c3672))
+* add manifest writer module with dbt v12-compatible serialization ([32f20f2](https://github.com/chio-labs/sqlbuild/commit/32f20f2581edf2c72f8e99bfc7f33c5159059814))
+* add max concurrency project setting ([43b3ab5](https://github.com/chio-labs/sqlbuild/commit/43b3ab5d598876d59774217a5b8eea53845cae24))
+* add microbatch executor with sentinel substitution, cursor-range delete_insert, and batch splitting ([d1eb879](https://github.com/chio-labs/sqlbuild/commit/d1eb87987412ddb5ef3c42539514b2dcd6d2321c))
+* add model target context to compile templates ([45db2e9](https://github.com/chio-labs/sqlbuild/commit/45db2e99ab8f41ab23c3d395d87259e9d55caedd))
+* add on_progress callback to custom materialization context ([e717ff5](https://github.com/chio-labs/sqlbuild/commit/e717ff5a6b7b45808953ee12b7112866ff467fba))
+* add optional sqlglot test projection parsing ([b75f9d7](https://github.com/chio-labs/sqlbuild/commit/b75f9d7581686b351fcc941c9e23f780ba0aaaa3))
+* add path:folder selector resolution and --no-sql-validation CLI flag ([d6b3951](https://github.com/chio-labs/sqlbuild/commit/d6b39515e734d9cf699b3ee2071c881745b42959))
+* add plan display before build execution and use_color support on plan formatter ([752bbad](https://github.com/chio-labs/sqlbuild/commit/752bbad4f6ee7a525f7cd41d540ea7846a85bba7))
+* add planner graph helpers with topo sort, expansion, and path finding ([3fcab8e](https://github.com/chio-labs/sqlbuild/commit/3fcab8eb25de793c96dfc26d13a42246a6b62493))
+* add planner-ready compiled resource models and dependency helpers ([fee76a9](https://github.com/chio-labs/sqlbuild/commit/fee76a97888988a0ec9e6c5ec11f1f098c003459))
+* add project-local adapter discovery ([ea7d06d](https://github.com/chio-labs/sqlbuild/commit/ea7d06d45a4dc446ce8190f2f3a6cc6a4ffc2b58))
+* add Python UDF support ([e9c8e22](https://github.com/chio-labs/sqlbuild/commit/e9c8e224b152653071a1f653501f1b9ba654cbe2))
+* add query command ([c80a508](https://github.com/chio-labs/sqlbuild/commit/c80a508fcaec051a7aaff9a54f0002a090bba239))
+* add query command ([ffe1435](https://github.com/chio-labs/sqlbuild/commit/ffe143545ffb0d8dab2ff77ef496601dc99d7ff3))
+* add raw schema metadata discovery ([22811f8](https://github.com/chio-labs/sqlbuild/commit/22811f8eba52a603901025e82d11bfcca5e437e1))
+* add raw source discovery parsing ([0ff1185](https://github.com/chio-labs/sqlbuild/commit/0ff11850d0d0184c8906f096f668b46eb15792b8))
+* add raw sql audit discovery parsing ([e62b123](https://github.com/chio-labs/sqlbuild/commit/e62b1233d2f1cc66c513c3a07395cd4d72b1420a))
+* add rich diff summary output ([9743b7b](https://github.com/chio-labs/sqlbuild/commit/9743b7b4fe06579d9a649979ef8a0b22b58a8fda))
+* add runtime audit rendering with relation overrides, AuditOutcome enum, and AuditExecutionResult model ([8272844](https://github.com/chio-labs/sqlbuild/commit/82728445a5582a8d3270b6927d081a316027cc4b))
+* add runtime SQL statement recorder ([f3e943e](https://github.com/chio-labs/sqlbuild/commit/f3e943ed33ca9697a042970b001d3fa7a224cbae))
+* add safe janitor cleanup command ([ec1e02c](https://github.com/chio-labs/sqlbuild/commit/ec1e02ccfb89681a7ffa9b0820b50b8c2d125409))
+* add seed target overrides ([4c89d0c](https://github.com/chio-labs/sqlbuild/commit/4c89d0ca21dcc0031a9047a5402090f4fea40689))
+* add selector parsing and scope resolution with union, intersection, and exclude ([fe8a17b](https://github.com/chio-labs/sqlbuild/commit/fe8a17b6e13627335ecbe5e3b6d0a43f8aac4b76))
+* add shared type normalization ([3a3103a](https://github.com/chio-labs/sqlbuild/commit/3a3103a22072686f10bf688b24328191dcbd6c18))
+* add shared type normalization ([ac7d895](https://github.com/chio-labs/sqlbuild/commit/ac7d89533bdd0a0e873ebce77496fa626553c5fd))
+* add snowflake adapter support ([0da4ecf](https://github.com/chio-labs/sqlbuild/commit/0da4ecf94528212b59262d640b40cfe23f5aac9a))
+* add source quality metadata parsing ([6ec1e1e](https://github.com/chio-labs/sqlbuild/commit/6ec1e1e76834998e47fe83c094d580b5a59c1dd8))
+* add sqb compile command with pipeline orchestration, target writer, and adapter defaults ([2446785](https://github.com/chio-labs/sqlbuild/commit/2446785ad6861c2286d027db6125f9aedc2def09))
+* add sqb plan command with compact/verbose output, waffle_shop example, and seed ref fixes ([038314b](https://github.com/chio-labs/sqlbuild/commit/038314b788a5da3d15616cfc9d57a75d0ebfaf47))
+* add SQL table functions ([52aaadd](https://github.com/chio-labs/sqlbuild/commit/52aaaddbc11b7017a0790f4742f70af789a41667))
+* add SQL table functions ([d6e9a04](https://github.com/chio-labs/sqlbuild/commit/d6e9a0468bc8195e2117a1d8409614910b6d667f))
+* add SQL UDF resources ([24149b0](https://github.com/chio-labs/sqlbuild/commit/24149b001c7cbe565fda2b66f521932a68f04158))
+* add sql-style model headers ([7a80177](https://github.com/chio-labs/sqlbuild/commit/7a801779042dbd5ed18e2729ed695b4b123760de))
+* add sqlbuild as an alias for sqb CLI entry point ([d69535e](https://github.com/chio-labs/sqlbuild/commit/d69535ed71738dc9150e60d8e3df089e43d6bf81))
+* add sqlglot column inference for schema change detection with source attribution ([c68ef74](https://github.com/chio-labs/sqlbuild/commit/c68ef743c843ac144bd4494012d36043a530229d))
+* add table executor with staged/direct lifecycle, type enforcement, audit execution, hooks, and fingerprint write ([36de9f2](https://github.com/chio-labs/sqlbuild/commit/36de9f27361b75138e7f294a65d9abc3de6bc1ca))
+* add template expression helpers ([23b3a2b](https://github.com/chio-labs/sqlbuild/commit/23b3a2be6b4ffa18f1d71c18494f9c8042b33496))
+* add transaction() context manager and transactional atomicity tests ([497b613](https://github.com/chio-labs/sqlbuild/commit/497b613d5349038b1079da919095cbc895c59af2))
+* add type_enforcement flag to schema change detection for yml vs inferred precedence ([c97e8d3](https://github.com/chio-labs/sqlbuild/commit/c97e8d36638024694c15d5d57cebb17e8c7bc45e))
+* add view executor, SQL unit test executor, and planner test ordering for Stage 8 ([38890d8](https://github.com/chio-labs/sqlbuild/commit/38890d89fce9b06baeff2087e09ec33815d353b3))
+* add warehouse cursor type consistency check with heuristic and sqlglot classification ([0726216](https://github.com/chio-labs/sqlbuild/commit/0726216864c2707c61ced52ad077afaacb35896c))
+* add warehouse snapshot gathering with bulk relation, column, and fingerprint reads ([c09e764](https://github.com/chio-labs/sqlbuild/commit/c09e764ae609e6ae7fe9963b02251d7583c16044))
+* attach defaults and path defaults to compile model inputs ([8aec92c](https://github.com/chio-labs/sqlbuild/commit/8aec92c7fcbc0cd61e747efea1ce4abb366c0461))
+* bootstrap repo and port convention checkers ([4967f63](https://github.com/chio-labs/sqlbuild/commit/4967f63fde8d68b1947f03988b63346ef9a73280))
+* compile attached generic audits ([b619e53](https://github.com/chio-labs/sqlbuild/commit/b619e539e061f7d4df5b7a6b5af1dc0176b8f1c2))
+* compile test and audit sql surfaces ([9482476](https://github.com/chio-labs/sqlbuild/commit/9482476fd72e54daf06e9fd027ce76e6b4c50272))
+* default audits to delta and final ([25099c2](https://github.com/chio-labs/sqlbuild/commit/25099c2669679b683ad5fb1b0cba605504343a79))
+* enforce typed source columns by default ([6d80f38](https://github.com/chio-labs/sqlbuild/commit/6d80f3898148b7667e6c388e0194e8fe440aae9e))
+* enforce typed source columns by default ([4fd4e9b](https://github.com/chio-labs/sqlbuild/commit/4fd4e9b2d2fe03dc0017b435d9e1bc220ec85be6))
+* expand compile templates in config layers ([f21b124](https://github.com/chio-labs/sqlbuild/commit/f21b124a2f1f7c822b4607fc41556180c47af97c))
+* expand diff examples and samples ([884693f](https://github.com/chio-labs/sqlbuild/commit/884693f0c35da2ded25542dd797940870a516b71))
+* expand discovery parsing and cli error handling ([69f23e2](https://github.com/chio-labs/sqlbuild/commit/69f23e2d34a029fa536e1b21047b8027ea756442))
+* expand path selector endpoint syntax ([938ec22](https://github.com/chio-labs/sqlbuild/commit/938ec22979fdb9899b89450ddfc1e00bbb67db49))
+* expand SQL UDF compile inputs ([9d6f2df](https://github.com/chio-labs/sqlbuild/commit/9d6f2df51a58c2f3b2209608af1c567548ed9242))
+* extract logical sql references during compile ([01517e6](https://github.com/chio-labs/sqlbuild/commit/01517e6e8fee2c43cc735d5889b0b3c5990260d5))
+* extract sql test cte semantics during compile ([65b789a](https://github.com/chio-labs/sqlbuild/commit/65b789a3290f842e616f40502c0e62d5eb9c6712))
+* filter warehouse metadata by selected scope ([e10cd8a](https://github.com/chio-labs/sqlbuild/commit/e10cd8a3c26aab5c40bc8a32c522e7884a54663d))
+* finish lifecycle event logging ([d907eb5](https://github.com/chio-labs/sqlbuild/commit/d907eb551b26b55df768716a9488246552bd97a7))
+* guard unit test sql length ([7af7856](https://github.com/chio-labs/sqlbuild/commit/7af7856d0bd02cafc3f1d0cd4278abb6664fcdbc))
+* improve chained sql test output ([2732950](https://github.com/chio-labs/sqlbuild/commit/273295085e52d4775bd879e53f5774edf1186625))
+* make seed resources explicit ([f635894](https://github.com/chio-labs/sqlbuild/commit/f635894b5ea598b6271c8aaa9dcbabde50033e69))
+* move model metadata into headers ([18d5481](https://github.com/chio-labs/sqlbuild/commit/18d54813b09d22c04112a19934041fc6920e619e))
+* move model metadata into headers ([dd7f980](https://github.com/chio-labs/sqlbuild/commit/dd7f9808e37feef27585341fb8862ea4aff478dc))
+* move statement recording into adapter write methods ([e2c6625](https://github.com/chio-labs/sqlbuild/commit/e2c66250bcc7c1f9665ab79d8eafddce0741e194))
+* redesign plan formatter with grouped output, cascade display, microbatch labels, and enum-only domain strings ([08004cc](https://github.com/chio-labs/sqlbuild/commit/08004cc13f8986d9763724586c1b170acf203920))
+* refine debug diagnostics output ([306506b](https://github.com/chio-labs/sqlbuild/commit/306506bcfac4635ed8de5d0bafc944395812217c))
+* resolve compile environment and vars layering ([67931de](https://github.com/chio-labs/sqlbuild/commit/67931de95e403a175af5f64aedc203f97d6772b0))
+* show delta/final audit phases with batch counts and aggregate microbatch audit results ([30bfde1](https://github.com/chio-labs/sqlbuild/commit/30bfde146d30bad70e3b976312d4f485d6e7f33c))
+* show executed lifecycle SQL in verbose output ([509cc03](https://github.com/chio-labs/sqlbuild/commit/509cc039bc63d797b46efbcd67a78cd2147e2e7d))
+* split early run context from target templates ([9b30f31](https://github.com/chio-labs/sqlbuild/commit/9b30f31572b489e1b08e72aa7e0fa9cae0229fe6))
+* support double quoted model header strings ([5212d40](https://github.com/chio-labs/sqlbuild/commit/5212d40b299f26c5834d5dfb4d980fb0e1d714e6))
+* support expression-backed sources ([2d8a693](https://github.com/chio-labs/sqlbuild/commit/2d8a69355a18ea48905568704e2af417fcf7f860))
+* support local connection settings ([fa900cd](https://github.com/chio-labs/sqlbuild/commit/fa900cdcb08d24d8cf8ba3d34dba494596983c7a))
+* support local environment overrides ([fd84b1e](https://github.com/chio-labs/sqlbuild/commit/fd84b1eced7b8f0e8a2dd8fe27b9bad4187a477c))
+* support local environment overrides ([deeb521](https://github.com/chio-labs/sqlbuild/commit/deeb521993167a472480dd8a8080e178d4835d67))
+* support seed mocks in SQL tests ([ddeea1c](https://github.com/chio-labs/sqlbuild/commit/ddeea1cc327375858604475146e6d1809ea794aa))
+* support sql test macro mocks ([d4b7c84](https://github.com/chio-labs/sqlbuild/commit/d4b7c84c0990db71e2ec35b29f0beead1aa70e66))
+* UNFINISHED (trying to introduce lifecycle events) ([aafbdba](https://github.com/chio-labs/sqlbuild/commit/aafbdba89b0130cafb3af4f8719c782fda1c08e1))
+* use environment range for diff ([7abe590](https://github.com/chio-labs/sqlbuild/commit/7abe5901418580d732b461ac3dc63ea06718c917))
+* use environment range for diff ([12b76ef](https://github.com/chio-labs/sqlbuild/commit/12b76ef00f3ff2a33eb4544a072f98410928368a))
+* validate discovery conflicts and seed metadata ([9dd6622](https://github.com/chio-labs/sqlbuild/commit/9dd6622abe1ffb79ce7f226066e5b2e0438e3fbf))
+* validate seed csv headers in discovery ([e2357a5](https://github.com/chio-labs/sqlbuild/commit/e2357a51d3fd2c80a6e33061445648ffadd808e8))
+* wire CLI commands for build, run, test, audit, and seed ([4d82460](https://github.com/chio-labs/sqlbuild/commit/4d82460bfe9a8522c57321f674bda4145b539688))
+* wire custom materialization loading through compile pipeline and add waffle shop example with e2e coverage ([dad1f75](https://github.com/chio-labs/sqlbuild/commit/dad1f75d79883e397431c3e786f8de89a8abc25d))
+* write runtime SQL artifacts after build and run ([293a29c](https://github.com/chio-labs/sqlbuild/commit/293a29ce3b3d351d7cee60d84416487d6f24da78))
+
+
+### Bug Fixes
+
+* align query fingerprint tracking ([a3307bc](https://github.com/chio-labs/sqlbuild/commit/a3307bc30885c0e1a43600b140b9d76ba502bb22))
+* clarify audit failure messaging ([4c2a090](https://github.com/chio-labs/sqlbuild/commit/4c2a0909540111b9c67827f611b189f7419937e3))
+* clarify CLI errors and DuckDB UDF fingerprints ([82921f9](https://github.com/chio-labs/sqlbuild/commit/82921f9423f975b0fd34d20601ee1a2648052d35))
+* clarify CLI errors and DuckDB UDF fingerprints ([4d5801e](https://github.com/chio-labs/sqlbuild/commit/4d5801eeb1c99dc97044268dafef78b43959512a))
+* coarsen mixed timestamp cursor replay ([a53901e](https://github.com/chio-labs/sqlbuild/commit/a53901eed994d2dc030c67e11b6c1848fe78b0e9))
+* consolidate duplicate _get_materialization_type and add advanced custom materialization tests ([b9d3f9d](https://github.com/chio-labs/sqlbuild/commit/b9d3f9d987122484f26782060e167d0f999a1454))
+* correct SKIP semantics, enforce incremental strategy, fix deferred cursor resolution ([bc7c344](https://github.com/chio-labs/sqlbuild/commit/bc7c3448b94618082ab0625bd4bd0eccd6a5de19))
+* enforce cascade backfill planning ([fa18cbb](https://github.com/chio-labs/sqlbuild/commit/fa18cbbc9e03ac7ed33502d94dbb32f7e5050653))
+* enforce cascade backfill planning ([214e294](https://github.com/chio-labs/sqlbuild/commit/214e29441ab972ab146475b8112de789f4eb7a29))
+* handle runtime-owned cursor filters on first build ([e7b9202](https://github.com/chio-labs/sqlbuild/commit/e7b9202175cc0145735a9306237b8c041cfb4ad6))
+* harden microbatch full-refresh execution ([43aa3fc](https://github.com/chio-labs/sqlbuild/commit/43aa3fca70b26fc6878f03040a5ccad52d7e4ef9))
+* improve CLI output formatting and add Execution section header ([f3a67f3](https://github.com/chio-labs/sqlbuild/commit/f3a67f33864cddb4673a02b35cde9ee4a645cb49))
+* improve plan/execution CLI output visual hierarchy and spacing ([eb1b0ed](https://github.com/chio-labs/sqlbuild/commit/eb1b0edcff08543328b22a7a135460870900d87f))
+* improve standalone audit and test output with model grouping and consistent header styling ([c0475ae](https://github.com/chio-labs/sqlbuild/commit/c0475aec81f58e29592e5254e7c28f179512dc16))
+* improve warehouse planning feedback ([70fc2a4](https://github.com/chio-labs/sqlbuild/commit/70fc2a46a0f3d2ebdd62611a87741142a1ef43a5))
+* improve warehouse planning feedback ([17dd900](https://github.com/chio-labs/sqlbuild/commit/17dd90029a297d4d5df5e7518e7f22ffeb9897fb))
+* indent audit and test sub-lines for clearer visual nesting under parent model ([bf2a2c7](https://github.com/chio-labs/sqlbuild/commit/bf2a2c7814fae9aa2e7a10b83964a81412e81db7))
+* polish plan selectors and runtime artifacts ([f2f0633](https://github.com/chio-labs/sqlbuild/commit/f2f0633da597634a6a33863635adcc1a2f76345e))
+* propagate UDF definition changes ([5e87a9c](https://github.com/chio-labs/sqlbuild/commit/5e87a9c08d105d47f44bf226f81497d7c3d77470))
+* propagate UDF definition changes ([12e2125](https://github.com/chio-labs/sqlbuild/commit/12e2125296dff4cf009a1e3af86424f7e194b591))
+* refine query change warning behavior ([6c2a193](https://github.com/chio-labs/sqlbuild/commit/6c2a19383ae04847fad1586cf6797d6eb4f5f736))
+* refresh latest tracked partition ([9ff283e](https://github.com/chio-labs/sqlbuild/commit/9ff283e60faff82878098f690c4c7d46b883a630))
+* reject unsupported dbt refs ([4717d3b](https://github.com/chio-labs/sqlbuild/commit/4717d3ba301af8079b08e04bf4b863a412b1789b))
+* remove dead test helpers, deduplicate write_repo_files into shared fixture, and strengthen ast hash test ([e5daeb2](https://github.com/chio-labs/sqlbuild/commit/e5daeb245b0f1233270153cf1e0a035389940f87))
+* resolve model-backed cursor inputs at runtime ([423f9ff](https://github.com/chio-labs/sqlbuild/commit/423f9ff442457e51095dbec98f1580b9c2f7cbb7))
+* scope snowflake test markers ([9ee43c2](https://github.com/chio-labs/sqlbuild/commit/9ee43c2ff0b71b74df887337ff6853c3c64d3ce5))
+* show incremental strategy annotation on full-refresh build output ([288d8c2](https://github.com/chio-labs/sqlbuild/commit/288d8c2788a1007fb64397cd1113f0c98b38f9f2))
+* show model count in audit and test command headers ([f528515](https://github.com/chio-labs/sqlbuild/commit/f528515ba1fe0562e2ef0a662594fb2d68d4b927))
+* show seed failures and default quotechar ([cabd72c](https://github.com/chio-labs/sqlbuild/commit/cabd72c6dc78320d1dfe8546633d9c1f55704bcd))
+* stabilize SQL tests with Snowflake UDFs ([239fa16](https://github.com/chio-labs/sqlbuild/commit/239fa16786dc45737b15e637e824d2d74e0cbf87))
+* tighten config validation ([6adc4c2](https://github.com/chio-labs/sqlbuild/commit/6adc4c23ade8cc1613701866badbb41e0c26ab6b))
+* use BigQuery copy promotion ([a4ccff9](https://github.com/chio-labs/sqlbuild/commit/a4ccff94258dbd7503ecb1b4039045e74e3d8c50))
+* use BigQuery copy promotion ([386deb4](https://github.com/chio-labs/sqlbuild/commit/386deb49ebbbf625f55847dac0ca63b48240ae3f))
+* use BigQuery MERGE for delete insert ([a0d1283](https://github.com/chio-labs/sqlbuild/commit/a0d12838dfc8165279b83e4103939e4e648c23dd))
+* use BigQuery MERGE for delete insert ([da62a51](https://github.com/chio-labs/sqlbuild/commit/da62a51af74dc93ab8c5679572b663b56039a94b))
+* use dynamic column widths in build progress output for better terminal usage ([0c89ad0](https://github.com/chio-labs/sqlbuild/commit/0c89ad002a596d174c3125b66296f277e326dee0))
+* validate cursor input names ([ec1a97a](https://github.com/chio-labs/sqlbuild/commit/ec1a97ab2d284eba42dbce91a6418970d9e31e48))
+* validate declared inline source columns ([6969e03](https://github.com/chio-labs/sqlbuild/commit/6969e039d202bbab76fd6ed2267bf94f55bcb528))
+* validate declared inline source columns ([da58065](https://github.com/chio-labs/sqlbuild/commit/da58065da0bbb6b6de5fa225772fca1f9978246e))
+* validate hook sql at compile time ([6c370d1](https://github.com/chio-labs/sqlbuild/commit/6c370d1f51a5702295c5be7a3f7e59c877baee09))
+* validate relation source metadata columns ([a0ed2c0](https://github.com/chio-labs/sqlbuild/commit/a0ed2c015421db8641143cb6761b70ab5c7941d2))
+* wrap multi-statement DML in transactions for atomicity ([884bfbc](https://github.com/chio-labs/sqlbuild/commit/884bfbcfbf2cc7e639b1e8dc58cb960baefc567e))
+
+
+### Documentation
+
+* add project logo ([5e629c7](https://github.com/chio-labs/sqlbuild/commit/5e629c726fd637937800a0533f3959a04471e724))
+* capture runtime SQL recording plan ([935e2d3](https://github.com/chio-labs/sqlbuild/commit/935e2d3cd557b9bd68fd0830d3c1fb5a802b8c36))
+* enlarge README logo ([e6daafb](https://github.com/chio-labs/sqlbuild/commit/e6daafbc78cfb4306514760bd99cd0f50dfba27b))
+* expand project README ([968b5f9](https://github.com/chio-labs/sqlbuild/commit/968b5f9bb905c9554af777d8a2312b67f5f00b2c))
+* update feature overview ([607da90](https://github.com/chio-labs/sqlbuild/commit/607da901837f0dccbb5060f294b14d487da2408b))
+* update README logo asset ([cce1d12](https://github.com/chio-labs/sqlbuild/commit/cce1d12df7289fcde8a7da42ae1f606ea206a0cd))
+* update README positioning ([89fea65](https://github.com/chio-labs/sqlbuild/commit/89fea658c15dbd84450b554fed6bea163dfbbbfc))
+* update README positioning ([832153e](https://github.com/chio-labs/sqlbuild/commit/832153e0bebbdbcade455c8d45a628a3f9bee923))
+
+## Changelog
+
+Release notes are managed by release-please.

sqlbuild-0.8.0/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing
+
+Thanks for helping improve SQLBuild. Keep changes focused, tested, and easy to review.
+
+## Setup
+
+SQLBuild requires Python 3.12 or newer.
+
+Install dependencies with:
+
+```bash
+uv sync
+```
+
+## Development Workflow
+
+- Create a branch for your change.
+- Keep pull requests focused on one behavior change or cleanup.
+- Add or update tests for behavior changes.
+- Prefer small, direct changes over broad rewrites.
+- Do not commit secrets, credentials, machine-local config, or generated scratch files.
+
+## Checks
+
+Before opening a pull request, run:
+
+```bash
+make check
+```
+
+For broader validation, run:
+
+```bash
+make verify
+```
+
+For focused iteration, run the narrowest relevant pytest target, for example:
+
+```bash
+pytest tests/unit/src/sqlbuild/compiler/compile/test_main.py
+```
+
+## Tests
+
+- Mirror source layout under `tests/<scope>/src/sqlbuild/...`.
+- Prefer dataclass-backed test cases for non-trivial scenarios.
+- Use clear Given-When-Then test names.
+- Prefer real parsing, filesystem, compile, and planner behavior over mocks when practical.
+- For substantive behavior changes, validate test strength with a small semantic mutation and confirm the relevant test fails before reverting it.
+
+## Project Conventions
+
+- Keep `sqb compile` offline and static unless intentionally changing that contract.
+- Keep examples reproducible and avoid environment-specific assumptions.
+- Use project-local config files for local overrides, and do not commit credentials or personal settings.
+- Follow existing code style and module organization before introducing new patterns.
+
+## Commits And Pull Requests
+
+- Use concise conventional commit messages, such as `fix: ...`, `feat: ...`, `test: ...`, or `docs: ...`.
+- In pull requests, summarize the behavior change and list the checks you ran.
+- Call out breaking changes, migrations, or compatibility decisions explicitly.

sqlbuild-0.8.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: sqlbuild
+Version: 0.8.0
+Summary: Batch SQL transformation framework
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: duckdb>=1.3.2
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=15.0.0
+Provides-Extra: bigquery
+Requires-Dist: google-cloud-bigquery>=3.37.0; extra == 'bigquery'
+Provides-Extra: databricks
+Requires-Dist: databricks-sql-connector[pyarrow]>=4.1.2; extra == 'databricks'
+Provides-Extra: performance
+Requires-Dist: sqlglot[c]>=30.7.0; extra == 'performance'
+Provides-Extra: snowflake
+Requires-Dist: snowflake-connector-python>=3.17.3; extra == 'snowflake'
+Provides-Extra: sqlglot
+Requires-Dist: sqlglot>=27.13.2; extra == 'sqlglot'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src=".github/sqlbuild-logo-clean.png" alt="SQLBuild" width="100%">
+</p>
+
+<p align="center">
+  Typed, test-first SQL pipelines with change-aware incremental rebuilds.
+</p>
+
+SQLBuild is a framework for building batch SQL transformation pipelines where correctness and extensibility are first-class concerns.
+
+## Key features
+
+- **SQL unit tests that chain across models** - Mock your sources, assert on the model you care about, and SQLBuild resolves every intermediate model automatically. One test file can be a full integration test across your pipeline.
+- **End-to-end scenarios with local replay** - Define coherent fixture worlds, run the real project graph in an isolated warehouse slice, capture JSONL snapshots, and replay them locally through DuckDB for fast CI feedback.
+- **Audits that block bad data** - Audits run before data reaches the target table. For full table builds, SQLBuild materializes into a staging table and only promotes if audits pass. For incremental models, delta-phase audits validate each batch before DML.
+- **Python macros, not Jinja** - Macros are real Python functions. Testable, debuggable, and composable with standard tooling.
+- **Change-aware incremental rebuilds** - Fingerprint-based query change detection, schema diff tracking, and configurable backfill policies with automatic cascade through the DAG.
+- **Cursor-based incremental processing** - Automatic gap detection and resume. If a model fails for several runs, the next build replays from where it left off. Microbatch mode splits large ranges into configurable batches.
+- **User-defined functions** - SQL and Python UDFs managed as project resources, with table functions for predicate-pushdown-friendly alternatives to final-layer views.
+- **Environment diffs** - Compare schemas and row-level data between environments with `sqb diff prod:dev`.
+- **Zero-copy cloning** - Branch environments instantly with `sqb clone` without duplicating data. No `manifest.json` required.
+- **Custom materializations** - Write materialization logic in Python with full framework integration, including audit hooks, schema change signals, and query change detection.
+- **Path-between selectors** - `--select fact_orders~daily_activity_rollup` selects every model on the shortest path between two nodes.
+
+## Quick start
+
+```bash
+pip install sqlbuild
+# or
+uv add sqlbuild
+```
+
+Clone the repo and run the waffle shop example:
+
+```bash
+git clone https://github.com/chio-labs/sqlbuild.git
+cd sqlbuild
+uv sync
+sqb --project-dir examples/waffle_shop plan
+sqb --project-dir examples/waffle_shop build
+```
+
+
+## How it works
+
+1. **Define** your models as SQL files with `MODEL()` headers that declare configuration, schema, and audits inline
+2. **Compile** to resolve references, validate SQL (with SQLGlot), and expand Python macros
+3. **Plan** what needs to change based on fingerprints, schema diffs, and backfill policies
+4. **Build** by executing the plan: materializing models, validating data before promotion, and ensuring bad data never reaches production
+5. **Iterate** with first-class support for chained unit tests, zero-copy cloning, and deferred builds - fast feedback without rebuilding the world
+
+## Example
+
+A simple staging model:
+
+```sql
+MODEL (
+  materialized view,
+  tags [staging],
+);
+
+SELECT
+  id AS order_id,
+  customer_id,
+  ordered_at,
+  status
+FROM __source("raw_orders")
+```
+
+An incremental model with microbatch processing:
+
+```sql
+MODEL (
+  materialized incremental,
+  incremental_strategy delete_insert,
+  cursor activity_hour,
+  cursor_type timestamp,
+  cursor_grain hour,
+  cursor_inputs (
+    fact_orders ordered_at,
+  ),
+  incremental_mode microbatch,
+  batch_size 1d,
+  tags [marts],
+);
+
+SELECT
+  DATE_TRUNC('hour', o.ordered_at) AS activity_hour,
+  COUNT(*) AS orders_placed,
+  SUM(o.quantity) AS waffles_ordered
+FROM __ref("fact_orders") o
+GROUP BY DATE_TRUNC('hour', o.ordered_at)
+```
+
+A chained unit test:
+
+```sql
+TEST();
+
+WITH
+__source__raw_orders AS (
+  @mock_orders()
+),
+__source__raw_payments AS (
+  SELECT 1 AS payment_id, 1 AS order_id, 1500 AS amount_cents, 'credit_card' AS method
+),
+__expected__fact_orders AS (
+  SELECT 1 AS order_id, 100 AS customer_id, 1500 AS total_cents,
+         'credit_card' AS payment_method
+)
+SELECT 1
+```
+
+An end-to-end scenario:
+
+```sql
+SCENARIO (
+  description "Customer refund updates daily revenue correctly",
+  tags [revenue, refund],
+);
+
+WITH
+__source__raw_orders AS (
+  SELECT 1 AS order_id, DATE '2026-01-01' AS order_date, 100.00 AS amount
+),
+__source__raw_refunds AS (
+  SELECT 1 AS refund_id, 1 AS order_id, DATE '2026-01-01' AS refund_date, 25.00 AS amount
+),
+__expected__daily_revenue AS (
+  SELECT DATE '2026-01-01' AS order_date, 75.00 AS revenue
+),
+__assert__no_negative_revenue AS (
+  SELECT * FROM __ref("daily_revenue") WHERE revenue < 0
+)
+SELECT 1
+```
+
+Scenario files live under `tests/scenarios/**/*.sql`. Run them in the target warehouse with:
+
+```bash
+sqb scenario test
+sqb scenario test revenue__customer_refund --retain
+```
+
+Capture local replay snapshots as JSONL under `tests/_scenario_snapshots/<scenario_name>/`:
+
+```bash
+sqb scenario capture revenue__customer_refund
+sqb scenario test revenue__customer_refund --local
+sqb scenario test --local --sync-snapshots
+sqb scenario test --local --refresh
+```
+
+Snapshots are committable test data, so review them for sensitive warehouse values before committing. Capture safety limits can be set in config and overridden on the CLI:
+
+```toml
+[scenario.snapshot_limits]
+max_rows_per_relation = 10000
+max_total_rows = 50000
+max_bytes_per_relation = 5000000
+max_total_bytes = 25000000
+```
+
+Use `--force` to bypass snapshot size limits when you intentionally want a larger capture.
+
+## Documentation
+
+Full documentation is available at [docs.sqlbuild.com](https://docs.sqlbuild.com).
+
+## Contributing
+
+We welcome contributions. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+SQLBuild is licensed under the [Apache License 2.0](LICENSE).