feat!: merge Python node folders into python/ (#850)

* feat!: merge Python node folders into python/

Discover loaders, tasks, assets, checks, factories, and audit factories
anywhere under a single python/ root. The decorator defines each node
kind, so folder-based kind validation is gone and undecorated helper
modules under python/ are importable without becoming nodes.

Remove the tasks/, assets/, checks/, loaders/, factories/, libs/,
dagster/, and rivers_pipeline/ Python roots and the root definitions.py
allowance. The Dagster and Rivers playgrounds now generate an
orchestrator directory with definitions.py next to a nested waffle_shop/
SQLBuild project. Path selectors for Python nodes use the python/ root.

BREAKING CHANGE: Python nodes and their helper modules must live under
python/ (for example python/tasks/orders.py, imported as
python.tasks.orders). Python under tasks/, assets/, checks/, loaders/,
factories/, libs/, dagster/, rivers_pipeline/, or a root definitions.py
now fails compilation with D016. Python path selectors use python/...
instead of tasks/, assets/, checks/, or loaders/.

* docs: document the python/ node root and external orchestrator layout

Update the Python nodes, project Python, selector, init, playground, quickstart, dlt, Dagster, and Rivers pages for the single python/ root and for orchestrator definitions that live outside the SQLBuild project, then regenerate the bundled skill references.

* docs: regenerate bundled skill references

* fix: import python/ modules under their package names

Discovery imports every python/ module as python.<dotted.path> through the normal import system, so helper packages can use relative imports and each module initializes once per discovery pass. python.* entries are evicted at the start of each pass so sequential projects and edited files are imported afresh.

* fix: register factory-returned module nodes once

A factory may return a decorated node that direct discovery already registers from its own python/ module. Skip that identical callable in factory output while keeping the duplicate-name error for distinct nodes.

* fix: install wrapper playground skills in the SQLBuild project

Dagster and Rivers playgrounds nest the SQLBuild project under waffle_shop/. Install the scaffolded agent skills there, where sqb skills and stale-skill maintenance resolve them, and document the location.

* test: align python/ discovery regressions with fensu rules

Check node decorators directly when de-duplicating factory output, split the factory E2E into success and conflict tests, and use expected_ fields and the shared repo-file fixture in the new regressions.

* fix: bind python/ to the project and de-duplicate factory nodes by identity

Discovery installs an explicit python package whose __path__ is the
project's python/ folder, so project imports never resolve to an
unrelated python package elsewhere on sys.path. Unrelated python.*
modules displaced during discovery are restored afterwards.

Discovery now imports every python/ module and registers direct nodes
before running factories, then skips factory results that are the same
callable direct discovery registered. A factory that binds a generated
node to a module global registers it once instead of dropping it.

* test: resolve the project root from python/ node fixtures

Author: kvlonge

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/compile.md

@@ -46,7 +46,9 @@ sqb --project-dir <path> compile [flags]
 3. **SQL validation** - validates SQL syntax (when SQL analysis is enabled)
 4. **Column lineage** - analyzes column-level dependencies across models (fast mode by default)
 5. **Contract validation** - checks declared column contracts against inferred query output
-6. **Rules** - evaluates selected native built-ins, then selected custom Python Rules
+6. **Rules** - evaluates selected native built-ins, then selected custom Python Rules. Rules that
+   need inferred type proofs, such as `SQBRCONTRACT105`, are skipped when SQL analysis is disabled,
+   and compile prints one note naming them
 7. **Artifact write** - writes compiled SQL to `target/compiled/` when Rules pass
 
 ## Focused compilation

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/init.md

@@ -30,10 +30,7 @@ my-project/
   schemas/
   sources/
   seeds/
-  loaders/
-  tasks/
-  assets/
-  checks/
+  python/
   hooks/
     sql/
     python/

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/playground.md

@@ -21,8 +21,8 @@ The positional argument is the directory to create (default `sqlbuild-playground
 | Template | Description |
 |----------|-------------|
 | `waffle_shop` | Default. DuckDB-backed project with models, tests, scenarios, and macros. |
-| `dagster` | Waffle shop project plus a `dagster/` directory with a ready-to-run `definitions.py`. |
-| `rivers` | Waffle shop project plus a `rivers_pipeline/` directory with a Rivers repository definition. |
+| `dagster` | A Dagster code location: a ready-to-run `definitions.py` next to the waffle shop SQLBuild project in `waffle_shop/`. |
+| `rivers` | A Rivers code repository: a `definitions.py` repository definition next to the waffle shop SQLBuild project in `waffle_shop/`. |
 | `python_nodes` | A small DuckDB project demonstrating [Python nodes](../concepts/python-nodes/overview.md): a task feeding a loader, a model read by a Python asset through `ctx.relation(model(...))`, a soft-skip fan-in, `materialized=False`, and a Python check. |
 
 ## What it creates
@@ -31,21 +31,28 @@ A complete DuckDB-backed project with:
 
 - Staging views, fact/dimension tables, and incremental models
 - Sources with inline expression data (no external setup)
+- Python source loaders in `python/loaders/`
 - Seeds, SQL functions, and a custom materialization
 - Built-in and custom audits
 - SQL unit tests and multi-model tests
 - E2E scenario tests
 - Python macros
 - AI agent skill files (auto-installed for OpenCode, Claude Code, and other agents)
 
-The `dagster` template adds:
+The `dagster` and `rivers` templates keep orchestrator code outside the SQLBuild project:
 
-- `dagster/definitions.py` - Dagster definitions with `sqlbuild_assets`, `sqlbuild_scenario_checks`, and `SqlBuildCliResource`
-- `dagster/README.md` - Setup instructions
+```text
+sqlbuild-playground/
+  definitions.py     # Dagster or Rivers definitions pointing at waffle_shop/
+  README.md          # setup instructions
+  waffle_shop/       # the waffle shop SQLBuild project, including agent skill files
+```
+
+The Dagster `definitions.py` uses `sqlbuild_assets`, `sqlbuild_scenario_checks`, and `SqlBuildCliResource`; the Rivers `definitions.py` defines a `waffle_shop` job. Run `sqb` commands from `waffle_shop/` and the orchestrator from the top-level directory. Agent skill files are installed in `waffle_shop/`, where `sqb skills` and stale-skill checks maintain them.
 
 The `python_nodes` template instead creates a focused Python-nodes project:
 
-- `tasks/orders.py`, `loaders/orders.py`, `assets/orders_export.py`, `checks/orders_export.py`
+- `python/tasks/orders.py`, `python/loaders/orders.py`, `python/assets/orders_export.py`, `python/checks/orders_export.py`
 - A `fact_orders` SQL model over a managed `raw_orders` source
 - Examples of the SQL boundary, `ctx.relation(model(...))`, soft-skip fan-in, and a Python check
 
@@ -61,13 +68,13 @@ sqb build
 sqb playground --template dagster
 cd sqlbuild-playground
 uv pip install 'sqlbuild[dagster]'
-dagster dev -f dagster/definitions.py
+dagster dev -f definitions.py
 
 # With Rivers integration
 sqb playground --template rivers
 cd sqlbuild-playground
 uv pip install 'sqlbuild[rivers]'
-uv run rivers dev rivers_pipeline.definitions
+uv run rivers dev definitions
 
 # With Python nodes
 sqb playground --template python_nodes

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/query.md

@@ -83,6 +83,13 @@ order_id,customer_id,status
 2,200,completed
 ```
 
+## Errors
+
+When the warehouse rejects the SQL, `sqb query` prints the warehouse message as
+`error[C108]: ...` on stderr and exits with code `2`. Nothing is written to stdout, so
+redirected `json` or `csv` output is never partial. Invalid command input, such as a missing
+query file, exits with code `1`.
+
 ## Examples
 
 ```bash

src/sqlbuild/.agents/skills/sqlbuild/references/docs/concepts/project-configuration.md

@@ -531,16 +531,32 @@ See [skills CLI reference](../cli/skills.md) for usage details.
 
 ## Project Python
 
-Project-owned Python must live in a supported extension location such as `factories/`, `libs/`,
-`macros/`, `providers/`, or another documented Python resource root. Factory locations contain
-normal Python: constants, classes, undecorated helper functions, and modules such as `_helpers.py`
-are allowed, while decorators determine which functions become SQLBuild resources. Compilation
-rejects Python under unsupported project roots, so indirectly importable modules cannot create an
-unofficial project structure.
+Project-owned Python lives in a small set of roots. Anything that runs as part of the pipeline graph
+goes in `python/`: loaders, tasks, assets, checks, factories, and the helper modules they import.
+Modules under `python/` are normal Python: constants, classes, undecorated helper functions, and
+helper-only modules such as `python/_helpers.py` are allowed, while decorators determine which
+functions become graph nodes. See [Python nodes](python-nodes/overview.md#the-python-folder).
+
+Code that extends SQLBuild itself keeps its own root:
+
+| Location | Holds |
+|----------|-------|
+| `rules/` | Custom project rules |
+| `materializations/` | Custom materializations |
+| `adapters/`, `adapter.py` | Custom adapters |
+| `providers/` | Runtime providers |
+| `sinks/` | Lifecycle event and command output sinks |
+| `hooks/python/` | Python model lifecycle hooks |
+| `functions/python/` | Python UDFs |
+| `macros/`, `enums/`, `constants/` and scoped `_macros/`, `_enums/`, `_constants/` | Python macros and declarations |
+
+Compilation rejects Python anywhere else with `D016`, so indirectly importable modules cannot create
+an unofficial project structure.
 
 Keep repository pytest tests outside the SQLBuild project's `tests/` directory, which is reserved for
-SQLBuild SQL tests and scenarios. Documented integration paths such as `dagster/`,
-`rivers_pipeline/`, and their `definitions.py` modules are also supported.
+SQLBuild SQL tests and scenarios. Orchestrator code such as Dagster or Rivers definitions lives outside
+the SQLBuild project directory and points at it; see [Dagster](../integrations/dagster.md) and
+[Rivers](../integrations/rivers.md).
 
 ## sqlbuild_local.toml
 

src/sqlbuild/.agents/skills/sqlbuild/references/docs/concepts/python-nodes/assets.md

@@ -20,10 +20,10 @@ Assets are Python nodes that produce or observe an external artifact - an export
 
 ## Defining an asset
 
-Place Python files under `assets/` and decorate functions with `@asset`:
+Place Python files under `python/` (the playgrounds use `python/assets/`) and decorate functions with `@asset`:
 
 ```python
-# assets/exports.py
+# python/assets/exports.py
 from sqlbuild.assets import asset, AssetContext
 
 @asset
@@ -57,7 +57,7 @@ Assets declare dependencies with `depends_on` (a single function, tuple, or list
 
 ```python
 from sqlbuild.assets import asset
-from tasks.orders import export_orders
+from python.tasks.orders import export_orders
 
 @asset(depends_on=export_orders)
 def orders_dashboard(ctx):

src/sqlbuild/.agents/skills/sqlbuild/references/docs/concepts/python-nodes/checks.md

@@ -22,12 +22,12 @@ Checks are separate graph nodes, not callbacks embedded in a task or asset. A ch
 
 ## Defining a check
 
-Place Python files under `checks/` and decorate functions with `@check`. `depends_on` is required:
+Place Python files under `python/` (the playgrounds use `python/checks/`) and decorate functions with `@check`. `depends_on` is required:
 
 ```python
-# checks/orders.py
+# python/checks/orders.py
 from sqlbuild.checks import check, CheckContext
-from tasks.orders import export_orders
+from python.tasks.orders import export_orders
 
 @check(depends_on=export_orders)
 def check_orders_exported(ctx: CheckContext):
@@ -121,7 +121,7 @@ sqb check --select tag:exports
 | | Checks | Audits |
 |---|--------|--------|
 | Validates | Python tasks, assets, loaders | SQL relations |
-| Authored in | `checks/` (Python) | `MODEL()` headers / `audits/` (SQL) |
+| Authored in | `python/` (Python) | `MODEL()` headers / `audits/` (SQL) |
 | Run by | `sqb build`, `sqb check` | `sqb build`, `sqb audit` |
 | Severity | `error`, `warn` | `error`, `warn` |
 

src/sqlbuild/.agents/skills/sqlbuild/references/docs/concepts/python-nodes/factories.md

@@ -15,7 +15,7 @@ Factories are an advanced feature. Most projects author nodes directly; reach fo
 A `@factory` function takes **no arguments** and returns one or more decorated node functions:
 
 ```python
-# factories/exports.py
+# python/factories/exports.py
 from sqlbuild.factories import factory
 from sqlbuild.assets import asset
 
@@ -36,38 +36,18 @@ The returned nodes are discovered and added to the graph exactly as if you had w
 
 A factory may return a single node or a list, tuple, or set of nodes. Every returned item must be a decorated `@task`, `@asset`, `@loader`, or `@check` function.
 
-## Folder rules
+## Where factories live
 
-Where a factory lives determines what it is allowed to emit:
+Factories live anywhere under `python/`, like every other Python node. The decorators on the returned functions decide each node's kind, so a factory may emit a single kind or a mix, and it can sit next to hand-written nodes in the same file. The playgrounds keep factories in `python/factories/`.
 
-| Location | May emit |
-|----------|----------|
-| `loaders/` | loaders only |
-| `tasks/` | tasks only |
-| `assets/` | assets only |
-| `checks/` | checks only |
-| `factories/` | any kind, including a mix |
-
-- A **single-kind** factory can live in that kind's folder (e.g. an asset-only factory in `assets/`), keeping it next to the nodes it generates. It can also live in `factories/`.
-- A factory that emits **more than one kind** must live in `factories/`.
-
-This keeps each kind folder honest: everything in `assets/`, whether hand-written or factory-generated, is an asset.
-
-SQLBuild enforces this at discovery time. A factory in a kind folder that returns a foreign kind raises an error pointing you to `factories/`:
-
-```
-Factory export_pipeline in assets/ returned a loader 'raw_orders';
-mixed-kind factories must live in factories/.
-```
-
-The `factories/` folder is not created by `sqb init` - add it when you need it.
+Factory modules are normal Python: constants, classes, and undecorated helpers are allowed, and shared helpers can live in their own modules, for example `python/factories/_helpers.py` imported as `from python.factories._helpers import TABLES`.
 
 ## Mixed-kind factories
 
-A factory in `factories/` can generate a whole related pipeline at once - a loader, the asset that reads it, and a check on the result:
+A single factory can generate a whole related pipeline at once - a loader, the asset that reads it, and a check on the result:
 
 ```python
-# factories/orders.py
+# python/factories/orders.py
 from sqlbuild.factories import factory
 from sqlbuild.loaders import loader
 from sqlbuild.assets import asset

src/sqlbuild/.agents/skills/sqlbuild/references/docs/concepts/python-nodes/loaders.md

@@ -26,18 +26,18 @@ Loaders are Python functions that load data into source tables. They replace exp
 
 ## How it works
 
-1. Write a Python function under `loaders/` decorated with `@loader`
+1. Write a Python function under `python/` decorated with `@loader`
 2. Declare a managed source in `sources/*.yml` with `managed: true` and **the same name as the loader function**
 3. SQLBuild calls the function, writes returned rows to a staging table, then applies the configured write strategy to the target
 
 Loaders participate in the build lifecycle. When `sqb build` runs, managed sources are loaded before any dependent model is materialized.
 
 ## Defining a loader
 
-Place Python files under `loaders/` in your project directory. Each file can contain one or more loader functions:
+Place Python files under `python/` in your project directory (the playgrounds use `python/loaders/`). Each file can contain one or more loader functions:
 
 ```python
-# loaders/raw_sources.py
+# python/loaders/raw_sources.py
 from sqlbuild.loaders import loader
 from sqlbuild.executor.load.models import LoaderContext
 
@@ -357,17 +357,18 @@ When a loader returns rows with columns not present in the existing target table
 
 ```
 my-project/
-  loaders/
-    raw_sources.py          # loader functions
-    api_sources.py           # more loader functions
+  python/
+    loaders/
+      raw_sources.py         # loader functions
+      api_sources.py         # more loader functions
   sources/
     raw.yml                  # managed source declarations (managed: true)
   models/
     staging/
       stg_customers.sql      # __source("raw_customers")
 ```
 
-SQLBuild discovers all `.py` files under `loaders/` recursively (excluding `__init__.py` and files starting with `_`). Each file is scanned for functions decorated with `@loader`.
+SQLBuild imports all `.py` files under `python/` recursively (excluding `__init__.py`). Functions decorated with `@loader` become loaders; undecorated helpers do not become nodes.
 
 ## Config reference
 

src/sqlbuild/.agents/skills/sqlbuild/references/docs/concepts/python-nodes/overview.md

@@ -8,6 +8,7 @@ Online: https://sqlbuild.com/docs/concepts/python-nodes/overview/
 
 ## Contents
 
+- The `python/` folder
 - The SQL boundary
 - Decorators
 - Identity tracking
@@ -20,14 +21,14 @@ Online: https://sqlbuild.com/docs/concepts/python-nodes/overview/
 
 Python nodes let your project grow beyond warehouse-only SQL while keeping the SQL graph clean. They are ordinary Python functions, decorated to become nodes in the same DAG as your SQL models, and they run as part of `sqb build`.
 
-There are four kinds, authored in dedicated top-level folders:
+There are four kinds. The decorator says what each function is, so all of them live under one `python/` folder:
 
-| Kind | Decorator | Folder | Purpose |
-|------|-----------|--------|---------|
-| Loader | `@loader` | `loaders/` | Load external data into a managed source |
-| Task | `@task` | `tasks/` | Run Python computation or side effects |
-| Asset | `@asset` | `assets/` | Produce or observe an external artifact |
-| Check | `@check` | `checks/` | Validate tasks, assets, and loaders |
+| Kind | Decorator | Purpose |
+|------|-----------|---------|
+| Loader | `@loader` | Load external data into a managed source |
+| Task | `@task` | Run Python computation or side effects |
+| Asset | `@asset` | Produce or observe an external artifact |
+| Check | `@check` | Validate tasks, assets, and loaders |
 
 All four share the same decorator conventions, dependency model, selection syntax, and runtime context helpers. The pages for each kind cover their specifics:
 
@@ -40,6 +41,26 @@ All four share the same decorator conventions, dependency model, selection synta
 
 Nodes can also be generated programmatically with [`@factory`](factories.md) instead of authored one at a time.
 
+## The `python/` folder
+
+Anything that runs as part of the pipeline graph goes in `python/`: loaders, tasks, assets, checks, [factories](factories.md), and the helper modules they import. SQLBuild imports every `.py` file under `python/` recursively (except `__init__.py`) and registers each decorated function by its decorator. Undecorated functions and helper-only modules are allowed and never become nodes.
+
+How you organize files inside `python/` is up to you. The playgrounds group nodes by kind:
+
+```
+python/
+  _helpers.py          # shared helpers, not nodes
+  loaders/orders.py
+  tasks/orders.py
+  assets/orders_export.py
+  checks/orders_export.py
+  factories/regional.py
+```
+
+Grouping by domain (`python/orders/`, `python/customers/`) works just as well, and a single file may mix kinds. Import other project modules through the `python` package, for example `from python.tasks.orders import export_orders` or `from python._helpers import normalize_status`.
+
+Code that extends SQLBuild itself keeps its own folder, such as `rules/`, `materializations/`, `adapters/`, `providers/`, `sinks/`, `hooks/python/`, `functions/python/`, and `macros/`. Python outside the supported locations fails compilation with `D016`; see [Project Python](../project-configuration.md#project-python) for the full list.
+
 ## The SQL boundary
 
 The most important rule: **SQL models never depend on Python nodes.** The dependency direction is strictly one way.