From ee39d9e1b2523b409632b9f6cd616f64e6579711 Mon Sep 17 00:00:00 2001
From: wjduenow <wjduenow@gmail.com>
Date: Wed, 27 May 2026 09:34:20 -0700
Subject: [PATCH 01/10] Add super plan for #139: Snowflake projection-subquery
 sample shape

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plans/super/139-snowflake-sample-shape.md | 234 ++++++++++++++++++++++
 1 file changed, 234 insertions(+)
 create mode 100644 plans/super/139-snowflake-sample-shape.md

diff --git a/plans/super/139-snowflake-sample-shape.md b/plans/super/139-snowflake-sample-shape.md
new file mode 100644
index 00000000..7102e675
--- /dev/null
+++ b/plans/super/139-snowflake-sample-shape.md
@@ -0,0 +1,234 @@
+# Super Plan — #139: Snowflake sample-mode prune — projection-subquery sample shape
+
+## Meta
+
+- **Ticket:** [#139](https://github.com/wjduenow/SignalForge/issues/139) — `Snowflake sample-mode prune: HASH(*) invalid in WHERE/ORDER BY — needs projection-subquery sample shape`
+- **Type:** bug · **Priority:** P2
+- **Milestone:** v0.2 (Snowflake adapter epic #118; scope of #121/#122; discovered by #124's live harness)
+- **Beads ref:** `bd_1-scaffolding-cdp`
+- **Phase:** detailing (awaiting approval)
+- **Branch:** `feature/139-snowflake-sample-shape` (based on `dev`)
+- **Sessions:** 1 (2026-05-27)
+
+---
+
+## Phase 1 — Discovery
+
+### What / Why / Who
+
+**What.** The deterministic-sample SQL emitted for Snowflake places the dialect's row-hash expression (`ABS(HASH(*))`) inline in `WHERE` / `ORDER BY`:
+
+```sql
+... WHERE MOD(ABS(HASH(*)), <bucket>) < 1 ... ORDER BY ABS(HASH(*)) ...
+```
+
+Snowflake rejects this — `002079 (42601): Use of * as a function argument`. `HASH(*)` is valid **only in the SELECT projection**, never in a `WHERE`/`ORDER BY` predicate (verified live: `SELECT ABS(HASH(*))` works; the predicate form fails). BigQuery's `ABS(FARM_FINGERPRINT(TO_JSON_STRING(t)))` is valid inline everywhere, so the architectural gap was invisible until a live Snowflake run.
+
+**Why.** Until fixed, Snowflake prune works only with `prune.scope: full` (no sampling), and `safety: sample` is broken (it calls `sample_rows`). The whole point of the prune step (Architectural Commitment #1, signal over volume) leans on cheap sampling; full-scan-only is a cost regression for Snowflake users.
+
+**Who.** Operators running SignalForge against a Snowflake profile with `prune.scope: sample` (the default-ish cheap path) or `safety: sample`.
+
+### Root cause
+
+A single **inline `sample_row_hash_expr` string** in the #121 `Dialect` design cannot express the **projection-subquery shape** Snowflake needs: compute the hash in an inner `SELECT`, reference the computed column by alias in the outer `WHERE`/`ORDER BY`. The `Dialect` field is a *string*, but the fix needs a *structural* abstraction.
+
+### Codebase findings (Scout)
+
+`sample_row_hash_expr` is consumed in exactly **two** SQL-building sites; a third (BigQuery adapter) hardcodes its hash and is independent.
+
+| Surface | Location | Reads `sample_row_hash_expr`? | Notes |
+|---|---|---|---|
+| `Dialect` definition | `src/signalforge/warehouse/models.py:57-164` | — | frozen `@dataclass`; `BIGQUERY_DIALECT`, `SNOWFLAKE_DIALECT` (sets `sample_row_hash_expr="ABS(HASH(*))"`, `sample_cte_alias='"sample"'`), `POSTGRES_DIALECT`. |
+| Prune compiler sample CTE | `src/signalforge/prune/compiler.py:180-218` (`_render_sample_cte`) | **yes** — line 210 `MOD({dialect.sample_row_hash_expr}, {bucket}) < 1` | Used for **both** dialects. CTE has **no ORDER BY** (only `WHERE MOD(...)<1 LIMIT n`). Outer queries select **specific** columns from the CTE alias (line 362/402/449/558), and `custom_sql` rewrites its `FROM` to the alias (line 749). |
+| `SnowflakeAdapter.sample_rows` | `src/signalforge/warehouse/adapters/snowflake.py:577-624` | **yes** — line 616 reads it; 618 (WHERE) + 622 (`ORDER BY {hash_expr}`) | `SELECT * FROM <quoted> AS t WHERE ... ORDER BY ... LIMIT n`; returns dict rows. |
+| `SnowflakeAdapter.materialise_sample` | `src/signalforge/warehouse/adapters/snowflake.py:631-759` | **yes** — line 706 reads it; 713 (WHERE) + 721 (`ORDER BY`) | `CREATE TEMPORARY TABLE <quoted_temp> AS SELECT * FROM <src> AS t WHERE ... ORDER BY ... LIMIT n`. |
+| BigQuery adapter (reference) | `src/signalforge/warehouse/adapters/bigquery.py:517,529,661,676` | **no** — hardcodes `ABS(FARM_FINGERPRINT(TO_JSON_STRING(t)))` inline | Works because `FARM_FINGERPRINT` is valid in any clause. **Out of scope** — keep untouched. |
+| Shared sample-id seam | `src/signalforge/warehouse/_sample_id.py:29-99` | — | naming recipe only; **builds no SQL**. |
+
+**Import-guard note:** `tests/prune/test_compiler_import_guard.py` forbids only `snowflake` / `google.cloud` imports under `prune/`. A new helper in the **warehouse** layer is importable by the compiler (it already imports `signalforge.warehouse.models` + `signalforge.warehouse._sql_safety`).
+
+**Fixtures & guards:**
+- Snowflake compiled-SQL snapshots: `tests/fixtures/prune/compiled_sql/snowflake/*.sql` — the five `*_sample.sql` files carry the buggy `MOD(ABS(HASH(*)), n)` form. BigQuery equivalents under `tests/fixtures/prune/compiled_sql/*.sql` **must stay byte-identical**.
+- `tests/prune/test_compiler_fakesnow.py:315-330` — parses every Snowflake fixture through `sqlglot.parse_one(sql, dialect="snowflake")` (gated `@pytest.mark.snowflake`). (sqlglot currently parses `HASH(*)`-in-WHERE without complaint — snapshot/parse equality certifies *shape*, not Snowflake *acceptance*; only live execution does.)
+- `tests/warehouse/test_snowflake_adapter_fakesnow.py:342-401` — asserts the adapter emits `MOD(ABS(HASH(*)), 10) < 1` + `ORDER BY ABS(HASH(*))` and sqlglot-parses them.
+- `tests/warehouse/test_snowflake_prune_live.py:286` — live e2e currently pinned to `scope="full"` to dodge this bug.
+
+### Convention constraints (Convention Checker)
+
+- **Dialect-driven, never name-branched** (`prune-engine.md` DEC-025): compiler reads `Dialect` fields; never `if dialect.name ==`. Enforced by `test_compiler_import_guard.py`.
+- **BigQuery byte-identity is the regression gate**: new `Dialect` fields default to BigQuery-shaped values so the 11 BQ snapshot fixtures + every `Dialect(...)` construction site stay byte-identical.
+- **3-tier validation** (`prune-engine.md` DEC-005 / `warehouse-adapters.md` #124): byte-exact snapshots → gated fakesnow-execute + sqlglot-parse → gated **live** Snowflake. "A new dialect's SQL needs a parser/executor in the loop — snapshot equality certifies shape, not validity." This bug is the canonical example: snapshots + sqlglot both passed the invalid form; only live caught it.
+- **Reuse `_sample_id`** for `run_id` (already in place); reuse `Dialect` fields, never hardcode `HASH(*)` in the adapter (`warehouse-adapters.md` #122).
+- **5-surface graduation** when a reserved/declarative field changes meaning: rule file + ops doc + CLAUDE.md + test + plan DEC in lockstep.
+- **Gated marker**: `uv run pytest -m snowflake --no-cov`; live tier gated on `SF_RUN_SNOWFLAKE=1` + conn vars + writable schema.
+- No `workflow-project.md`; conventions live in `CLAUDE.md` + `.claude/rules/`.
+
+### Scoping answers
+
+1. **Shape abstraction → structural flag + alias fields.** Add `sample_hash_in_projection: bool = False` and `sample_hash_alias: str = "_sf_sample_hash"` to `Dialect`. BigQuery keeps the default (`False` → inline); Snowflake sets `True`.
+2. **Renderer location → shared warehouse-layer helper, leave BigQuery adapter alone.** New `src/signalforge/warehouse/_sample_sql.py` consumed by the prune compiler + `SnowflakeAdapter`. BigQuery's adapter keeps its hardcoded inline form (out of scope).
+3. **Hash-column leak → `SELECT * EXCLUDE (<alias>)`.** The projection path wraps the hash in an inner `SELECT t.*, <hash> AS <alias>` and the outer `SELECT * EXCLUDE (<alias>)` strips it, so returned rows and the materialised temp table carry only original columns.
+
+---
+
+## Phase 2 — Architecture Review
+
+| Area | Rating | Finding |
+|---|---|---|
+| Security | **pass** | The hash alias `_sf_sample_hash` and `EXCLUDE` token are hardcoded constants — no new injection surface. Table/identifier validation (`_sql_safety`) and typed `PartitionFilter` rendering are unchanged; the helper takes a pre-rendered partition predicate from each caller's existing `_render_partition_filter`. |
+| Performance | **pass** | Projection-subquery computes `HASH(*)` once per row in an inner projection — equivalent cost to the inline form; `EXCLUDE` is a planner-level column prune (no runtime cost). Materialised sample stays bounded by `LIMIT n` + `maximum_bytes_billed`. |
+| Data model | **pass (improvement)** | `SELECT * EXCLUDE (alias)` guarantees the materialised temp table's schema equals the source schema — strictly *more* correct than the risk of an extra column leaking into the temp table that downstream prune queries. |
+| API design | **pass** | Two new `Dialect` fields with BigQuery-safe defaults → backward compatible. `Dialect` is a frozen dataclass (no Pydantic `extra="forbid"` drift detector); fields appended at the end with defaults keep all 4 construction sites (`models.py`, `test_models.py`, `_fake_adapter.py`, `test_compiler.py`) valid. `POSTGRES_DIALECT` keeps defaults (correct — Postgres stub never invokes the compiler). |
+| Observability | **pass** | No logging changes. The existing adapter INFO/WARNING surfaces are unaffected. |
+| Testing | **concern → addressed** | The live tier is the only true certifier (`HASH(*)` cannot run under fakesnow). **Risk:** can `ORDER BY` reference a column that `SELECT * EXCLUDE` removes from output? Addressed in DEC-004 with a fallback. The offline guards (snapshots + sqlglot) prove shape; the maintainer's live run is the merge-gating certification. |
+
+**No blockers.** One concern (live-cert ownership + the `ORDER BY` / `EXCLUDE` interaction) carried into the decisions below.
+
+---
+
+## Phase 3 — Refinement Log
+
+### DEC-001 — `Dialect` gains a structural sample-shape flag, not a richer template
+
+Add two declarative fields to `Dialect` (frozen dataclass, `src/signalforge/warehouse/models.py`):
+
+```python
+sample_hash_in_projection: bool = False   # BigQuery inline; Snowflake True
+sample_hash_alias: str = "_sf_sample_hash"
+```
+
+`SNOWFLAKE_DIALECT` sets `sample_hash_in_projection=True`. BigQuery/Postgres keep defaults. **Rationale:** the chosen option (structural flag) matches the existing "declarative SQL-fragment field" pattern from #121 (`quote_qualified_per_component`, `sample_cte_alias`, …) — a boolean + alias is the minimum that distinguishes the two shapes without a new type or drift mirror. A `SampleShape` enum (rejected) is heavier for two states; full template strings (rejected) are byte-fragile.
+
+### DEC-002 — Single shared renderer `warehouse/_sample_sql.py`, name-agnostic
+
+New module `src/signalforge/warehouse/_sample_sql.py`:
+
+```python
+def render_sample_select(
+    table_sql: str,          # already-quoted FROM target
+    *,
+    dialect: Dialect,
+    sample_bucket: int,
+    sample_size: int,
+    extra_where: str | None = None,   # pre-rendered partition predicate (caller owns it)
+    order_by_hash: bool,              # compiler CTE: False; adapters: True
+) -> str: ...
+```
+
+Reads `dialect.sample_row_hash_expr`, `dialect.sample_hash_in_projection`, `dialect.sample_hash_alias`. Two branches, switched on the **boolean** (never `dialect.name`):
+
+- **Inline (BigQuery, `sample_hash_in_projection=False`)** — byte-identical to today's compiler CTE body / would-be adapter form:
+  ```
+  SELECT * FROM <table_sql> AS t WHERE MOD(<hash_expr>, <bucket>) < 1[ AND <extra_where>][ ORDER BY <hash_expr>] LIMIT <n>
+  ```
+- **Projection-subquery (Snowflake, `sample_hash_in_projection=True`)**:
+  ```
+  SELECT * EXCLUDE (<alias>) FROM (SELECT t.*, <hash_expr> AS <alias> FROM <table_sql> AS t) WHERE MOD(<alias>, <bucket>) < 1[ AND <extra_where>][ ORDER BY <alias>] LIMIT <n>
+  ```
+
+Consumers: prune compiler `_render_sample_cte` and `SnowflakeAdapter.sample_rows` / `materialise_sample`. **BigQuery adapter is NOT wired** (out of scope — keeps its hardcoded inline form and its own tests). The compiler's import guard is satisfied (warehouse-layer import, no SDK/name branch).
+
+**Rationale:** one place owns the shape so the compiler CTE and the adapter sample SELECT stay byte-consistent (Architectural Commitment #5). Caller owns partition-filter rendering (each already has a dialect-correct `_render_partition_filter`), so the helper stays purely about sample shape and avoids re-plumbing partition logic.
+
+### DEC-003 — BigQuery byte-identity is the load-bearing regression gate
+
+The inline branch must reproduce the **exact** current bytes, including spacing: `MOD(<expr>, <bucket>) < 1` (space after comma, spaces around `<`). The compiler CTE has **no `ORDER BY`** today, so `_render_sample_cte` calls the helper with `order_by_hash=False`; the BQ compiler `*_sample.sql` fixtures are the gate. (The BigQuery *adapter* sample SQL — which *does* carry `ORDER BY` — is untouched, so its form is irrelevant to this helper.)
+
+### DEC-004 — `SELECT * EXCLUDE (alias)` with the filter/order at the outer level; live-cert the `ORDER BY`-of-excluded-column interaction
+
+The projection shape puts `WHERE`/`ORDER BY` at the **outer** level (where `<alias>` is a real column of the derived table), and `EXCLUDE` on the outer projection. The one genuine uncertainty is whether Snowflake's `ORDER BY <alias>` is legal when `<alias>` is `EXCLUDE`-d from the output. **Primary form** (assumed legal — Snowflake resolves `ORDER BY` against input columns):
+
+```sql
+SELECT * EXCLUDE (_sf_sample_hash) FROM (
+  SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash FROM <src> AS t
+) WHERE MOD(_sf_sample_hash, <bucket>) < 1 ORDER BY _sf_sample_hash LIMIT <n>
+```
+
+**Fallback (if live rejects ORDER-BY-of-excluded-column):** drop the outer `ORDER BY` from the emitted SQL and rely on the deterministic `MOD` filter for sample membership (matches the compiler CTE, which already has no `ORDER BY`); determinism of *which* rows under `LIMIT` is a pre-existing property, not a regression of this fix. The live test (US-004) is the decision point; the implementer picks primary-or-fallback based on what live Snowflake accepts and pins the chosen form in the fixtures.
+
+The `_sf_sample_hash` alias is emitted **unquoted**; Snowflake folds it to `_SF_SAMPLE_HASH` consistently in both the projection and the `EXCLUDE`, so they resolve to the same identifier. (If live shows a mismatch, quote both consistently — implementer detail, live-certified.)
+
+### DEC-005 — 5-surface graduation for the new `Dialect` fields
+
+`sample_hash_in_projection` / `sample_hash_alias` are new load-bearing fields. Update in lockstep: (1) `warehouse-adapters.md` `Dialect`-fields section + the live-harness-findings note (mark `bd_1-scaffolding-cdp` fixed); (2) `prune-engine.md` "Compiler is dialect-driven" field list; (3) `docs/warehouse-adapter-ops.md` "Known limitations on live Snowflake" (remove the HASH(*) limitation, document sample-mode now works); (4) tests pin the active behaviour; (5) this plan's DECs.
+
+### DEC-006 — Re-enable the live materialised prune e2e at `scope="sample"`
+
+`tests/warehouse/test_snowflake_prune_live.py` moves from `scope="full"` to a sample-mode run (`PruneConfig(scope="sample", sample_strategy="materialised")`) against the engineered writable table, asserting the always-passes `not_null` drop. This is the AC's live certification. Gated `@pytest.mark.snowflake` + `SF_RUN_SNOWFLAKE=1`; maintainer-run before merge.
+
+---
+
+## Phase 4 — Detailed Breakdown
+
+> Validation command (every story): `uv sync --dev && uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run pytest`. Snowflake-gated tiers: `uv run pytest -m snowflake --no-cov` (offline fakesnow/sqlglot always; live requires `SF_RUN_SNOWFLAKE=1` + conn vars + writable `SNOWFLAKE_DATABASE`/`SCHEMA`).
+
+### US-001 — `Dialect` shape fields + shared `render_sample_select` helper
+
+**Description.** Add `sample_hash_in_projection` / `sample_hash_alias` to `Dialect`; set them on `SNOWFLAKE_DIALECT`. Create `warehouse/_sample_sql.py::render_sample_select` with the inline + projection-subquery branches.
+**Traces to:** DEC-001, DEC-002, DEC-003, DEC-004.
+**Files:** `src/signalforge/warehouse/models.py` (fields + `SNOWFLAKE_DIALECT`), `src/signalforge/warehouse/_sample_sql.py` (new), `tests/warehouse/test_sample_sql.py` (new), `tests/warehouse/test_models.py` (Dialect construction stays valid).
+**TDD:**
+- Inline branch with `order_by_hash=False`, no `extra_where` → byte-exact current BQ compiler-CTE body.
+- Inline branch with `order_by_hash=True` + `extra_where` → `... AND <pf> ORDER BY <expr> LIMIT n`.
+- Projection branch (Snowflake dialect) → exact `SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash FROM <t> AS t) WHERE MOD(_sf_sample_hash, b) < 1 ORDER BY _sf_sample_hash LIMIT n`.
+- Projection branch with `extra_where` places it as `AND <pf>` at the outer level.
+- Helper never references `dialect.name` (assert via reading the source / behaviour with a synthetic dialect).
+**Done when:** helper unit tests pass; `Dialect` constructs with new defaults; BQ default reproduces inline bytes; full validation green.
+**Depends on:** none.
+
+### US-002 — Wire the prune compiler sample CTE to the shared helper + regenerate Snowflake compiler snapshots
+
+**Description.** Replace the inline string-building in `_render_sample_cte` with a call to `render_sample_select(..., order_by_hash=False)`. Regenerate the five Snowflake `*_sample.sql` fixtures to the projection-subquery form; confirm BQ `*_sample.sql` fixtures are **byte-unchanged**.
+**Traces to:** DEC-002, DEC-003, DEC-004.
+**Files:** `src/signalforge/prune/compiler.py` (`_render_sample_cte`), `tests/fixtures/prune/compiled_sql/snowflake/{not_null,unique,accepted_values,relationships,custom_sql}_sample.sql`, `tests/prune/test_compiler.py` (sample-mode assertions), `tests/prune/test_compiler_fakesnow.py` (sqlglot parse guard now certifies the new form), `tests/prune/test_compiler_import_guard.py` (still green — sanity).
+**Done when:** Snowflake sample fixtures show `SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash ...)`; BQ fixtures unchanged (`git diff` empty for `compiled_sql/*.sql`); `uv run pytest -m snowflake --no-cov` sqlglot parse passes; full validation green.
+**Depends on:** US-001.
+
+### US-003 — Wire `SnowflakeAdapter.sample_rows` + `materialise_sample` to the shared helper
+
+**Description.** Replace the inline WHERE/ORDER BY hash building in both methods with `render_sample_select(..., order_by_hash=True)`. `materialise_sample` wraps the result as `CREATE TEMPORARY TABLE <temp> AS <select>`. Update the fakesnow/sqlglot adapter tests to assert the new SQL.
+**Traces to:** DEC-002, DEC-004.
+**Files:** `src/signalforge/warehouse/adapters/snowflake.py` (`sample_rows`, `materialise_sample`), `tests/warehouse/test_snowflake_adapter_fakesnow.py` (assert `SELECT * EXCLUDE`, `SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash`, sqlglot-parse the new forms), `tests/warehouse/test_snowflake_adapter.py` if present.
+**Done when:** adapter emits the projection-subquery form for both methods; CTAS wraps it; fakesnow/sqlglot guards updated and `uv run pytest -m snowflake --no-cov` green; full validation green.
+**Depends on:** US-002.
+
+### US-004 — Re-enable live materialised prune e2e at `scope="sample"` + docs/5-surface graduation
+
+**Description.** Flip `test_snowflake_prune_live.py` to a materialised sample-mode run asserting the always-passes drop. Update the three doc surfaces (DEC-005) and confirm the live run is documented as the certification step. Pick primary-vs-fallback `ORDER BY` form (DEC-004) per what live Snowflake accepts and pin fixtures accordingly.
+**Traces to:** DEC-004, DEC-005, DEC-006.
+**Files:** `tests/warehouse/test_snowflake_prune_live.py` (scope=sample, materialised; module docstring), `docs/warehouse-adapter-ops.md` (§ Known limitations — remove HASH(*) limitation), `.claude/rules/warehouse-adapters.md` (Dialect fields + live-harness note: `bd_1-scaffolding-cdp` fixed), `.claude/rules/prune-engine.md` (compiler dialect field list).
+**Done when:** live test runs sample-mode and drops an always-passes test (maintainer-certified with `SF_RUN_SNOWFLAKE=1`); docs/rules updated; if live forced the fallback form, US-002/US-003 fixtures + this plan's DEC-004 note are updated to match. Full validation green.
+**Depends on:** US-003.
+
+### US-005 — Quality Gate (code review ×4 + CodeRabbit)
+
+**Description.** Run the code reviewer 4 times across the full changeset, fixing every real bug each pass; run CodeRabbit if available. Validation must pass after fixes.
+**Done when:** 4 review passes complete, all real findings fixed, `uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run pytest` green, `uv run pytest -m snowflake --no-cov` (offline) green, live tier certified by maintainer.
+**Depends on:** US-004.
+
+### US-006 — Patterns & Memory (priority 99)
+
+**Description.** Record the durable lesson: the #121 lesson generalised — a single inline SQL-fragment string can't express every dialect's clause-position constraints; structural shape needs a structural field. Confirm rule updates from US-004 landed; add a memory entry if the live-cert workflow surfaced anything new.
+**Done when:** `.claude/rules/` + `docs/` consistent with shipped behaviour; plan DECs final; memory updated if warranted.
+**Depends on:** US-005.
+
+---
+
+## Rules compliance gate
+
+- ✅ Compiler stays name-agnostic — helper switches on a boolean `Dialect` field, not `dialect.name` (import-guard green).
+- ✅ BigQuery byte-identity — inline branch reproduces current bytes; BQ fixtures are the regression gate (US-002 done-when).
+- ✅ 3-tier validation — snapshots (US-002) + fakesnow/sqlglot (US-002/US-003) + live (US-004).
+- ✅ Reuse `_sample_id` (unchanged) + `Dialect` fields (no hardcoded `HASH(*)` left in the adapter).
+- ✅ 5-surface graduation (DEC-005 / US-004).
+- ✅ Gated marker discipline (`-m snowflake --no-cov`).
+
+---
+
+## Phase 5 — Beads Manifest
+
+_(filled on devolve)_
+
+- Epic: —
+- Tasks: US-001 … US-006 + Quality Gate + Patterns & Memory
+- Worktree: `../worktrees/SignalForge/139-snowflake-sample-shape`

From a640ca41728857746965f13e9dc31c0a933a9543 Mon Sep 17 00:00:00 2001
From: wjduenow <wjduenow@gmail.com>
Date: Wed, 27 May 2026 09:56:25 -0700
Subject: [PATCH 02/10] #139: devolve plan to beads (epic bd_1-scaffolding-kay)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plans/super/139-snowflake-sample-shape.md | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/plans/super/139-snowflake-sample-shape.md b/plans/super/139-snowflake-sample-shape.md
index 7102e675..58bbb832 100644
--- a/plans/super/139-snowflake-sample-shape.md
+++ b/plans/super/139-snowflake-sample-shape.md
@@ -6,7 +6,7 @@
 - **Type:** bug · **Priority:** P2
 - **Milestone:** v0.2 (Snowflake adapter epic #118; scope of #121/#122; discovered by #124's live harness)
 - **Beads ref:** `bd_1-scaffolding-cdp`
-- **Phase:** detailing (awaiting approval)
+- **Phase:** devolved
 - **Branch:** `feature/139-snowflake-sample-shape` (based on `dev`)
 - **Sessions:** 1 (2026-05-27)
 
@@ -227,8 +227,12 @@ The `_sf_sample_hash` alias is emitted **unquoted**; Snowflake folds it to `_SF_
 
 ## Phase 5 — Beads Manifest
 
-_(filled on devolve)_
-
-- Epic: —
-- Tasks: US-001 … US-006 + Quality Gate + Patterns & Memory
-- Worktree: `../worktrees/SignalForge/139-snowflake-sample-shape`
+- **Epic:** `bd_1-scaffolding-kay`
+- **Tasks (linear dependency chain):**
+  - `bd_1-scaffolding-kay.1` — US-001 Dialect shape fields + shared helper *(ready)*
+  - `bd_1-scaffolding-kay.2` — US-002 compiler sample CTE + Snowflake snapshots *(blocked on .1)*
+  - `bd_1-scaffolding-kay.3` — US-003 SnowflakeAdapter sample_rows + materialise_sample *(blocked on .2)*
+  - `bd_1-scaffolding-kay.4` — US-004 live e2e at scope=sample + 5-surface docs *(blocked on .3)*
+  - `bd_1-scaffolding-kay.5` — Quality Gate *(blocked on .4)*
+  - `bd_1-scaffolding-kay.6` — Patterns & Memory *(blocked on .5)*
+- **Worktree:** `../worktrees/SignalForge/139-snowflake-sample-shape`

From 07532fae3dc84fd50ddbb629b21e073ec9be48dc Mon Sep 17 00:00:00 2001
From: wjduenow <wjduenow@gmail.com>
Date: Wed, 27 May 2026 10:01:55 -0700
Subject: [PATCH 03/10] bd_1-scaffolding-kay.1: #139 US-001 Dialect
 sample-shape fields + render_sample_select helper

Add sample_hash_in_projection / sample_hash_alias to the Dialect frozen
dataclass (BigQuery/Postgres keep inline defaults; SNOWFLAKE_DIALECT sets
projection=True). New stateless warehouse-layer helper
render_sample_select switches inline-vs-projection on the boolean flag
only (never dialect.name): inline reproduces the prune compiler's current
sample-CTE body byte-for-byte; projection-subquery computes HASH(*) in an
inner projection and references the alias in WHERE/ORDER BY with
SELECT * EXCLUDE.

Traces to DEC-001/002/003/004.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/signalforge/warehouse/_sample_sql.py |  89 +++++++++++++++
 src/signalforge/warehouse/models.py      |  26 ++++-
 tests/warehouse/test_models.py           |  10 ++
 tests/warehouse/test_sample_sql.py       | 133 +++++++++++++++++++++++
 4 files changed, 257 insertions(+), 1 deletion(-)
 create mode 100644 src/signalforge/warehouse/_sample_sql.py
 create mode 100644 tests/warehouse/test_sample_sql.py

diff --git a/src/signalforge/warehouse/_sample_sql.py b/src/signalforge/warehouse/_sample_sql.py
new file mode 100644
index 00000000..e405fdf3
--- /dev/null
+++ b/src/signalforge/warehouse/_sample_sql.py
@@ -0,0 +1,89 @@
+"""Shared deterministic-sample SELECT builder (issue #139, DEC-002/DEC-004).
+
+A single stateless string-builder owns the two warehouse sample SHAPES so the
+prune compiler's sample CTE and the Snowflake adapter's ``sample_rows`` /
+``materialise_sample`` stay byte-consistent (Architectural Commitment #5).
+
+The two shapes are switched ONLY on the boolean
+:attr:`signalforge.warehouse.models.Dialect.sample_hash_in_projection` — never
+on ``dialect.name`` (``prune-engine.md`` DEC-025; the prune compiler imports
+this helper and must stay name-agnostic):
+
+* **Inline** (``sample_hash_in_projection=False``, BigQuery) — the row-hash
+  expression sits directly in ``WHERE``/``ORDER BY``::
+
+      SELECT * FROM <table_sql> AS t
+      WHERE MOD(<hash_expr>, <bucket>) < 1[ AND <extra_where>]
+      [ORDER BY <hash_expr>] LIMIT <n>
+
+  This reproduces the prune compiler's current sample-CTE body byte-for-byte
+  (DEC-003), the load-bearing BigQuery regression gate.
+
+* **Projection-subquery** (``sample_hash_in_projection=True``, Snowflake) —
+  Snowflake's ``HASH(*)`` is rejected as a predicate (``002079``) and is legal
+  only in the SELECT projection, so the hash is computed once in an inner
+  projection bound to ``<alias>`` (``dialect.sample_hash_alias``) and the outer
+  ``WHERE``/``ORDER BY`` reference that alias; ``SELECT * EXCLUDE (<alias>)``
+  strips the helper column so returned rows carry only original columns::
+
+      SELECT * EXCLUDE (<alias>) FROM
+      (SELECT t.*, <hash_expr> AS <alias> FROM <table_sql> AS t)
+      WHERE MOD(<alias>, <bucket>) < 1[ AND <extra_where>]
+      [ORDER BY <alias>] LIMIT <n>
+
+``extra_where`` is a **pre-rendered** partition predicate fragment supplied by
+the caller (each consumer owns its dialect-correct ``_render_partition_filter``);
+this helper never renders partition filters. No logging.
+"""
+
+from __future__ import annotations
+
+from signalforge.warehouse.models import Dialect
+
+__all__ = ["render_sample_select"]
+
+
+def render_sample_select(
+    table_sql: str,
+    *,
+    dialect: Dialect,
+    sample_bucket: int,
+    sample_size: int,
+    extra_where: str | None = None,
+    order_by_hash: bool,
+) -> str:
+    """Render a deterministic hash-mod sample ``SELECT`` for ``table_sql``.
+
+    Args:
+        table_sql: An already-quoted ``FROM`` target (e.g. ``` `p.d.t` ``` or
+            ``"DB"."SCH"."T"``). Aliased to ``t`` in the emitted SQL.
+        dialect: Drives the hash expression and the inline-vs-projection shape.
+        sample_bucket: The ``MOD(<hash>, <bucket>) < 1`` bucket size.
+        sample_size: The trailing ``LIMIT`` value.
+        extra_where: A pre-rendered partition predicate; appended as
+            ``AND <extra_where>`` to the (outer) ``WHERE`` when provided.
+        order_by_hash: When ``True`` an ``ORDER BY`` on the hash is emitted
+            (the adapters want it; the compiler CTE passes ``False``).
+
+    Returns:
+        A single ``SELECT`` statement (no trailing semicolon, no CTE wrapper).
+    """
+    expr = dialect.sample_row_hash_expr
+
+    if dialect.sample_hash_in_projection:
+        alias = dialect.sample_hash_alias
+        where_sql = f"MOD({alias}, {sample_bucket}) < 1"
+        if extra_where is not None:
+            where_sql += f" AND {extra_where}"
+        order_sql = f" ORDER BY {alias}" if order_by_hash else ""
+        return (
+            f"SELECT * EXCLUDE ({alias}) FROM "
+            f"(SELECT t.*, {expr} AS {alias} FROM {table_sql} AS t) "
+            f"WHERE {where_sql}{order_sql} LIMIT {sample_size}"
+        )
+
+    where_sql = f"MOD({expr}, {sample_bucket}) < 1"
+    if extra_where is not None:
+        where_sql += f" AND {extra_where}"
+    order_sql = f" ORDER BY {expr}" if order_by_hash else ""
+    return f"SELECT * FROM {table_sql} AS t WHERE {where_sql}{order_sql} LIMIT {sample_size}"
diff --git a/src/signalforge/warehouse/models.py b/src/signalforge/warehouse/models.py
index 06db4a66..1c504ddc 100644
--- a/src/signalforge/warehouse/models.py
+++ b/src/signalforge/warehouse/models.py
@@ -87,8 +87,24 @@ class Dialect:
       unquoted CTE named ``sample`` is a syntax error there. Quoting bypasses
       the keyword interpretation while keeping the recognisable name.
 
+    Two further fields (issue #139) describe **where** the row-hash expression
+    is legal so the deterministic-sample SELECT builder
+    (``signalforge.warehouse._sample_sql.render_sample_select``) can switch
+    shape without name-branching:
+
+    * ``sample_hash_in_projection`` — when ``False`` (BigQuery default) the
+      hash expression is placed inline in ``WHERE``/``ORDER BY``; when ``True``
+      (Snowflake) the hash is computed once in an inner ``SELECT`` projection
+      and referenced by alias in the outer ``WHERE``/``ORDER BY``. Snowflake's
+      ``HASH(*)`` is rejected as a predicate (``002079: Use of * as a function
+      argument``) and is legal **only** in the SELECT projection.
+    * ``sample_hash_alias`` — the column alias the projected hash binds to in
+      the projection-subquery shape (emitted unquoted; Snowflake folds it
+      consistently in both the projection and the ``EXCLUDE`` clause).
+
     The defaults reproduce BigQuery's SQL byte-for-byte so every existing
-    construction site stays valid unedited (DEC-001 of issue #121).
+    construction site stays valid unedited (DEC-001 of issue #121; DEC-001 of
+    issue #139).
     """
 
     name: str
@@ -101,6 +117,8 @@ class Dialect:
     date_literal_template: str = "DATE('{value}')"
     quote_qualified_per_component: bool = False
     sample_cte_alias: str = "sample"
+    sample_hash_in_projection: bool = False
+    sample_hash_alias: str = "_sf_sample_hash"
 
 
 BIGQUERY_DIALECT = Dialect(
@@ -161,6 +179,7 @@ class Dialect:
     timestamp_literal_template="'{value}'::TIMESTAMP",
     date_literal_template="'{value}'::DATE",
     quote_qualified_per_component=True,
+    sample_hash_in_projection=True,
 )
 """Snowflake-flavoured :class:`Dialect` for the v0.2 adapter (issue #119, DEC-004).
 
@@ -183,6 +202,11 @@ class Dialect:
 * ``quote_qualified_per_component=True`` — Snowflake reads a single quoted
   string spanning dots as one literal identifier named ``db.schema.table``,
   so each component is quoted separately (``"DB"."SCH"."T"``).
+* ``sample_hash_in_projection=True`` — Snowflake's ``HASH(*)`` is rejected as
+  a ``WHERE``/``ORDER BY`` predicate (``002079``) and is legal only in the
+  SELECT projection, so the deterministic-sample SELECT computes the hash in
+  an inner projection and references the ``sample_hash_alias`` column in the
+  outer clauses (issue #139, DEC-001/DEC-004).
 
 Lives alongside :data:`BIGQUERY_DIALECT` / :data:`POSTGRES_DIALECT` per
 DEC-003 so every dialect-aware consumer imports each flavour from one place
diff --git a/tests/warehouse/test_models.py b/tests/warehouse/test_models.py
index 2cecc233..a15e448f 100644
--- a/tests/warehouse/test_models.py
+++ b/tests/warehouse/test_models.py
@@ -88,6 +88,10 @@ def test_snowflake_dialect_sql_fragment_fields() -> None:
     # CTE alias is the QUOTED ``"sample"`` (an unquoted ``WITH sample AS`` is a
     # syntax error on Snowflake).
     assert SNOWFLAKE_DIALECT.sample_cte_alias == '"sample"'
+    # issue #139: HASH(*) is projection-only on Snowflake, so the sample SELECT
+    # computes it in an inner projection and references the alias.
+    assert SNOWFLAKE_DIALECT.sample_hash_in_projection is True
+    assert SNOWFLAKE_DIALECT.sample_hash_alias == "_sf_sample_hash"
 
 
 @pytest.mark.unit
@@ -102,6 +106,10 @@ def test_bigquery_dialect_sql_fragment_field_defaults() -> None:
     # BigQuery's sample-CTE alias is the bare ``sample`` (not a reserved word
     # there) — keeps the existing BigQuery snapshots byte-identical.
     assert BIGQUERY_DIALECT.sample_cte_alias == "sample"
+    # issue #139: BigQuery's FARM_FINGERPRINT hash is valid inline, so the
+    # sample SELECT keeps the inline (non-projection) shape.
+    assert BIGQUERY_DIALECT.sample_hash_in_projection is False
+    assert BIGQUERY_DIALECT.sample_hash_alias == "_sf_sample_hash"
 
 
 @pytest.mark.unit
@@ -125,6 +133,8 @@ def test_dialect_constructs_without_new_field_args() -> None:
     assert d.date_literal_template == "DATE('{value}')"
     assert d.quote_qualified_per_component is False
     assert d.sample_cte_alias == "sample"
+    assert d.sample_hash_in_projection is False
+    assert d.sample_hash_alias == "_sf_sample_hash"
 
 
 @pytest.mark.unit
diff --git a/tests/warehouse/test_sample_sql.py b/tests/warehouse/test_sample_sql.py
new file mode 100644
index 00000000..befa4e73
--- /dev/null
+++ b/tests/warehouse/test_sample_sql.py
@@ -0,0 +1,133 @@
+"""Unit tests for ``signalforge.warehouse._sample_sql.render_sample_select``.
+
+The shared deterministic-sample SELECT builder (issue #139, US-001) emits
+two shapes switched ONLY on the boolean ``Dialect.sample_hash_in_projection``
+flag — never on ``dialect.name`` (DEC-002/DEC-004). The inline branch must
+reproduce the prune compiler's current BigQuery sample-CTE body byte-for-byte
+(DEC-003); the projection-subquery branch is the Snowflake fix where
+``HASH(*)`` is computed once in an inner projection and the WHERE/ORDER BY
+reference the resulting alias.
+
+Every test is capable of failing (``testing-signal.md`` — no
+``assert True``-shaped placeholders).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from signalforge.warehouse._sample_sql import render_sample_select
+from signalforge.warehouse.models import (
+    BIGQUERY_DIALECT,
+    SNOWFLAKE_DIALECT,
+    Dialect,
+)
+
+_TBL = "`p.d.t`"
+
+
+@pytest.mark.unit
+def test_inline_no_order_no_extra_where_matches_compiler_cte_body() -> None:
+    """Inline branch (BigQuery default) with ``order_by_hash=False`` and no
+    ``extra_where`` reproduces the prune compiler's current sample-CTE body
+    byte-for-byte (DEC-003)."""
+    sql = render_sample_select(
+        _TBL,
+        dialect=BIGQUERY_DIALECT,
+        sample_bucket=10,
+        sample_size=100000,
+        order_by_hash=False,
+    )
+    assert sql == (
+        "SELECT * FROM `p.d.t` AS t "
+        "WHERE MOD(ABS(FARM_FINGERPRINT(TO_JSON_STRING(t))), 10) < 1 "
+        "LIMIT 100000"
+    )
+
+
+@pytest.mark.unit
+def test_inline_with_order_and_extra_where() -> None:
+    """Inline branch with ``order_by_hash=True`` and an ``extra_where``
+    predicate appends ``AND <pf>`` to the WHERE and ``ORDER BY <expr>``."""
+    sql = render_sample_select(
+        _TBL,
+        dialect=BIGQUERY_DIALECT,
+        sample_bucket=10,
+        sample_size=500,
+        extra_where="ts >= TIMESTAMP('2020-01-01')",
+        order_by_hash=True,
+    )
+    expr = "ABS(FARM_FINGERPRINT(TO_JSON_STRING(t)))"
+    assert sql == (
+        f"SELECT * FROM `p.d.t` AS t "
+        f"WHERE MOD({expr}, 10) < 1 AND ts >= TIMESTAMP('2020-01-01') "
+        f"ORDER BY {expr} LIMIT 500"
+    )
+
+
+@pytest.mark.unit
+def test_projection_with_order_no_extra_where() -> None:
+    """Projection-subquery branch (Snowflake) computes the hash in an inner
+    projection and references the alias in WHERE/ORDER BY; the outer
+    projection ``EXCLUDE``s the alias so returned rows carry only original
+    columns (DEC-004)."""
+    sql = render_sample_select(
+        '"D"."T"',
+        dialect=SNOWFLAKE_DIALECT,
+        sample_bucket=10,
+        sample_size=500,
+        order_by_hash=True,
+    )
+    assert sql == (
+        "SELECT * EXCLUDE (_sf_sample_hash) FROM "
+        '(SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash FROM "D"."T" AS t) '
+        "WHERE MOD(_sf_sample_hash, 10) < 1 "
+        "ORDER BY _sf_sample_hash LIMIT 500"
+    )
+
+
+@pytest.mark.unit
+def test_projection_extra_where_lands_at_outer_level() -> None:
+    """Projection branch places ``AND <pf>`` at the OUTER WHERE level (after
+    the ``MOD(_sf_sample_hash, ...) < 1`` predicate), not inside the inner
+    subquery."""
+    sql = render_sample_select(
+        '"D"."T"',
+        dialect=SNOWFLAKE_DIALECT,
+        sample_bucket=7,
+        sample_size=42,
+        extra_where="ts >= '2020-01-01'::TIMESTAMP",
+        order_by_hash=False,
+    )
+    assert sql == (
+        "SELECT * EXCLUDE (_sf_sample_hash) FROM "
+        '(SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash FROM "D"."T" AS t) '
+        "WHERE MOD(_sf_sample_hash, 7) < 1 AND ts >= '2020-01-01'::TIMESTAMP "
+        "LIMIT 42"
+    )
+
+
+@pytest.mark.unit
+def test_branch_switches_on_flag_not_dialect_name() -> None:
+    """A synthetic dialect with an unrecognised ``name`` but
+    ``sample_hash_in_projection=True`` STILL renders the projection form —
+    proving the helper never branches on ``dialect.name`` (DEC-002)."""
+    madeup = Dialect(
+        name="madeup",
+        supports_tablesample=True,
+        supports_qualify=False,
+        quote_char='"',
+        identifier_case="preserve",
+        sample_row_hash_expr="ABS(HASH(*))",
+        sample_hash_in_projection=True,
+    )
+    sql = render_sample_select(
+        '"X"',
+        dialect=madeup,
+        sample_bucket=3,
+        sample_size=9,
+        order_by_hash=True,
+    )
+    assert sql.startswith("SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ")
+    assert "MOD(_sf_sample_hash, 3) < 1" in sql
+    assert "ORDER BY _sf_sample_hash" in sql

From 7429a9b370973fd7af2d9e80597f017e1e365c5a Mon Sep 17 00:00:00 2001
From: wjduenow <wjduenow@gmail.com>
Date: Wed, 27 May 2026 10:05:56 -0700
Subject: [PATCH 04/10] bd_1-scaffolding-kay.2: #139 US-002 wire compiler
 sample CTE to render_sample_select + regen Snowflake snapshots
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace _render_sample_cte's inline hash-mod string-building with a call to
the shared signalforge.warehouse._sample_sql.render_sample_select helper
(order_by_hash=False; the compiler CTE has no ORDER BY). Partition predicate
stays rendered by the compiler's own _render_partition_filter and is passed as
extra_where. Switches on the boolean Dialect.sample_hash_in_projection — no
dialect.name branch, no warehouse-SDK import (import-guard green).

BigQuery (inline) output is byte-identical — top-level compiled_sql/*.sql
fixtures unchanged (the regression gate). The five Snowflake *_sample.sql
fixtures regenerated to the projection-subquery form
(SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ABS(HASH(*)) AS
_sf_sample_hash ...) WHERE MOD(_sf_sample_hash, n) < 1) so HASH(*) is computed
in the projection, never a predicate. sqlglot snowflake-dialect parse guard
passes on the new form.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/signalforge/prune/compiler.py             | 31 +++++++++++++------
 .../snowflake/accepted_values_sample.sql      |  2 +-
 .../snowflake/custom_sql_sample.sql           |  2 +-
 .../snowflake/not_null_sample.sql             |  2 +-
 .../snowflake/relationships_sample.sql        |  2 +-
 .../compiled_sql/snowflake/unique_sample.sql  |  2 +-
 tests/prune/test_compiler.py                  | 29 ++++++++++++-----
 7 files changed, 49 insertions(+), 21 deletions(-)

diff --git a/src/signalforge/prune/compiler.py b/src/signalforge/prune/compiler.py
index ab0eca43..6fe21f77 100644
--- a/src/signalforge/prune/compiler.py
+++ b/src/signalforge/prune/compiler.py
@@ -71,6 +71,7 @@
     TemplateResolutionError,
 )
 from signalforge.manifest.template import resolve_template_refs
+from signalforge.warehouse._sample_sql import render_sample_select
 from signalforge.warehouse._sql_safety import (
     escape_bq_string_literal,
     validate_identifier,
@@ -205,17 +206,29 @@ def _render_sample_cte(
     ``ABS(HASH(*))``) so sampling decisions stay consistent between the
     adapter's internal samples and the prune engine's wrapped tests
     (DEC-006 of issue #3; DEC-002 of issue #121).
+
+    The CTE body is built by the shared
+    :func:`signalforge.warehouse._sample_sql.render_sample_select` so the
+    compiler's sample CTE and the warehouse adapter's sample ``SELECT``
+    stay byte-consistent (issue #139, DEC-002). The compiler CTE carries
+    **no** ``ORDER BY`` (``order_by_hash=False``); the partition predicate
+    is rendered by the compiler's own dialect-correct
+    :func:`_render_partition_filter` and passed as ``extra_where``.
     """
-    where_clauses = [
-        f"MOD({dialect.sample_row_hash_expr}, {sample_bucket}) < 1",
-    ]
-    if partition_filter is not None:
-        where_clauses.append(_render_partition_filter(partition_filter, dialect))
-    where_sql = " AND ".join(where_clauses)
-    return (
-        f"WITH {dialect.sample_cte_alias} AS "
-        f"(SELECT * FROM {table} AS t WHERE {where_sql} LIMIT {sample_size})"
+    extra_where = (
+        _render_partition_filter(partition_filter, dialect)
+        if partition_filter is not None
+        else None
+    )
+    body = render_sample_select(
+        table,
+        dialect=dialect,
+        sample_bucket=sample_bucket,
+        sample_size=sample_size,
+        extra_where=extra_where,
+        order_by_hash=False,
     )
+    return f"WITH {dialect.sample_cte_alias} AS ({body})"
 
 
 def _quote(identifier: str, dialect: Dialect) -> str:
diff --git a/tests/fixtures/prune/compiled_sql/snowflake/accepted_values_sample.sql b/tests/fixtures/prune/compiled_sql/snowflake/accepted_values_sample.sql
index 0c548282..dc45320f 100644
--- a/tests/fixtures/prune/compiled_sql/snowflake/accepted_values_sample.sql
+++ b/tests/fixtures/prune/compiled_sql/snowflake/accepted_values_sample.sql
@@ -1 +1 @@
-WITH "sample" AS (SELECT * FROM "FAKE_PROJECT"."DATASET"."ORDERS" AS t WHERE MOD(ABS(HASH(*)), 10) < 1 LIMIT 100000) SELECT "STATUS" FROM "sample" WHERE "STATUS" IS NOT NULL AND "STATUS" NOT IN ('placed', 'shipped', 'cancelled')
\ No newline at end of file
+WITH "sample" AS (SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash FROM "FAKE_PROJECT"."DATASET"."ORDERS" AS t) WHERE MOD(_sf_sample_hash, 10) < 1 LIMIT 100000) SELECT "STATUS" FROM "sample" WHERE "STATUS" IS NOT NULL AND "STATUS" NOT IN ('placed', 'shipped', 'cancelled')
\ No newline at end of file
diff --git a/tests/fixtures/prune/compiled_sql/snowflake/custom_sql_sample.sql b/tests/fixtures/prune/compiled_sql/snowflake/custom_sql_sample.sql
index 9806e9ca..a6230922 100644
--- a/tests/fixtures/prune/compiled_sql/snowflake/custom_sql_sample.sql
+++ b/tests/fixtures/prune/compiled_sql/snowflake/custom_sql_sample.sql
@@ -1 +1 @@
-WITH "sample" AS (SELECT * FROM "FAKE_PROJECT"."DATASET"."ORDERS" AS t WHERE MOD(ABS(HASH(*)), 10) < 1 LIMIT 100000) select order_id from "sample" where total < 0
\ No newline at end of file
+WITH "sample" AS (SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash FROM "FAKE_PROJECT"."DATASET"."ORDERS" AS t) WHERE MOD(_sf_sample_hash, 10) < 1 LIMIT 100000) select order_id from "sample" where total < 0
\ No newline at end of file
diff --git a/tests/fixtures/prune/compiled_sql/snowflake/not_null_sample.sql b/tests/fixtures/prune/compiled_sql/snowflake/not_null_sample.sql
index 5daf56d9..e98989c7 100644
--- a/tests/fixtures/prune/compiled_sql/snowflake/not_null_sample.sql
+++ b/tests/fixtures/prune/compiled_sql/snowflake/not_null_sample.sql
@@ -1 +1 @@
-WITH "sample" AS (SELECT * FROM "FAKE_PROJECT"."DATASET"."ORDERS" AS t WHERE MOD(ABS(HASH(*)), 10) < 1 LIMIT 100000) SELECT "CUSTOMER_ID" FROM "sample" WHERE "CUSTOMER_ID" IS NULL
\ No newline at end of file
+WITH "sample" AS (SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash FROM "FAKE_PROJECT"."DATASET"."ORDERS" AS t) WHERE MOD(_sf_sample_hash, 10) < 1 LIMIT 100000) SELECT "CUSTOMER_ID" FROM "sample" WHERE "CUSTOMER_ID" IS NULL
\ No newline at end of file
diff --git a/tests/fixtures/prune/compiled_sql/snowflake/relationships_sample.sql b/tests/fixtures/prune/compiled_sql/snowflake/relationships_sample.sql
index e4e95a9e..8e384f5d 100644
--- a/tests/fixtures/prune/compiled_sql/snowflake/relationships_sample.sql
+++ b/tests/fixtures/prune/compiled_sql/snowflake/relationships_sample.sql
@@ -1 +1 @@
-WITH "sample" AS (SELECT * FROM "FAKE_PROJECT"."DATASET"."ORDERS" AS t WHERE MOD(ABS(HASH(*)), 10) < 1 LIMIT 100000) SELECT child."CUSTOMER_ID" FROM "sample" AS child LEFT JOIN "FAKE_PROJECT"."DATASET"."CUSTOMERS" AS parent ON child."CUSTOMER_ID" = parent."ID" WHERE child."CUSTOMER_ID" IS NOT NULL AND parent."ID" IS NULL
\ No newline at end of file
+WITH "sample" AS (SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash FROM "FAKE_PROJECT"."DATASET"."ORDERS" AS t) WHERE MOD(_sf_sample_hash, 10) < 1 LIMIT 100000) SELECT child."CUSTOMER_ID" FROM "sample" AS child LEFT JOIN "FAKE_PROJECT"."DATASET"."CUSTOMERS" AS parent ON child."CUSTOMER_ID" = parent."ID" WHERE child."CUSTOMER_ID" IS NOT NULL AND parent."ID" IS NULL
\ No newline at end of file
diff --git a/tests/fixtures/prune/compiled_sql/snowflake/unique_sample.sql b/tests/fixtures/prune/compiled_sql/snowflake/unique_sample.sql
index 5c61b5db..ca9c2dd6 100644
--- a/tests/fixtures/prune/compiled_sql/snowflake/unique_sample.sql
+++ b/tests/fixtures/prune/compiled_sql/snowflake/unique_sample.sql
@@ -1 +1 @@
-WITH "sample" AS (SELECT * FROM "FAKE_PROJECT"."DATASET"."ORDERS" AS t WHERE MOD(ABS(HASH(*)), 10) < 1 LIMIT 100000) SELECT "CUSTOMER_ID" FROM "sample" WHERE "CUSTOMER_ID" IS NOT NULL GROUP BY "CUSTOMER_ID" HAVING COUNT(*) > 1
\ No newline at end of file
+WITH "sample" AS (SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash FROM "FAKE_PROJECT"."DATASET"."ORDERS" AS t) WHERE MOD(_sf_sample_hash, 10) < 1 LIMIT 100000) SELECT "CUSTOMER_ID" FROM "sample" WHERE "CUSTOMER_ID" IS NOT NULL GROUP BY "CUSTOMER_ID" HAVING COUNT(*) > 1
\ No newline at end of file
diff --git a/tests/prune/test_compiler.py b/tests/prune/test_compiler.py
index 8baba7d1..2b2b0a2f 100644
--- a/tests/prune/test_compiler.py
+++ b/tests/prune/test_compiler.py
@@ -1104,9 +1104,12 @@ def test_qualified_table_name_whole_path_for_bigquery_unchanged() -> None:
 
 
 def test_snowflake_sample_cte_uses_hash_not_farm_fingerprint() -> None:
-    """The Snowflake sample predicate is rendered from
-    ``sample_row_hash_expr`` → ``MOD(ABS(HASH(*)), <bucket>) < 1``; the
-    BigQuery ``FARM_FINGERPRINT`` form never appears (DEC-002)."""
+    """The Snowflake sample CTE uses the projection-subquery shape (issue
+    #139): ``ABS(HASH(*))`` is computed once in an inner projection bound
+    to ``_sf_sample_hash`` and the outer ``WHERE`` references that alias
+    (``HASH(*)`` is rejected as a predicate by Snowflake), while
+    ``SELECT * EXCLUDE (_sf_sample_hash)`` strips the helper column. The
+    BigQuery ``FARM_FINGERPRINT`` form never appears (DEC-002/DEC-004)."""
     test = CandidateTestNotNull(column="customer_id")
     sql = _compile_test(
         test,
@@ -1118,7 +1121,13 @@ def test_snowflake_sample_cte_uses_hash_not_farm_fingerprint() -> None:
         sample_bucket=10,
     )
     assert isinstance(sql, str)
-    assert "MOD(ABS(HASH(*)), 10) < 1" in sql
+    # The hash is computed in the inner projection, referenced by alias in
+    # the outer WHERE, and excluded from the output.
+    assert "SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash" in sql
+    assert "MOD(_sf_sample_hash, 10) < 1" in sql
+    assert "SELECT * EXCLUDE (_sf_sample_hash) FROM (" in sql
+    # The raw HASH(*)-in-predicate form (rejected live by Snowflake) is gone.
+    assert "MOD(ABS(HASH(*)), 10) < 1" not in sql
     assert "FARM_FINGERPRINT" not in sql
     # Folded + per-component quoted identifiers throughout; no backticks.
     assert '"CUSTOMER_ID"' in sql
@@ -1400,8 +1409,14 @@ def test_snowflake_fixtures_use_double_quote_never_backtick(fixture_name: str) -
     ],
 )
 def test_snowflake_sample_fixtures_use_hash_never_farm_fingerprint(fixture_name: str) -> None:
-    """Guard: every Snowflake sample fixture renders the ``HASH(*)`` row-hash
-    predicate and never BigQuery's ``FARM_FINGERPRINT`` (DEC-002)."""
+    """Guard: every Snowflake sample fixture computes the ``HASH(*)`` row-hash
+    once in an inner projection (the projection-subquery shape, issue #139),
+    references it by alias in the outer ``WHERE``, excludes it from the output,
+    and never uses BigQuery's ``FARM_FINGERPRINT`` (DEC-002/DEC-004)."""
     text = _read_snowflake_fixture(fixture_name)
-    assert "MOD(ABS(HASH(*)), 10) < 1" in text
+    assert "SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash" in text
+    assert "MOD(_sf_sample_hash, 10) < 1" in text
+    assert "SELECT * EXCLUDE (_sf_sample_hash) FROM (" in text
+    # The HASH(*)-in-predicate form (rejected live by Snowflake) must be gone.
+    assert "MOD(ABS(HASH(*)), 10) < 1" not in text
     assert "FARM_FINGERPRINT" not in text

From 63ceae656a3ed9dc104f3a1143a35e70c9fdcc40 Mon Sep 17 00:00:00 2001
From: wjduenow <wjduenow@gmail.com>
Date: Wed, 27 May 2026 10:11:16 -0700
Subject: [PATCH 05/10] bd_1-scaffolding-kay.3: #139 US-003 Snowflake adapter
 sample_rows + materialise_sample use projection-subquery shape

Replace the inline MOD(ABS(HASH(*)), n) < 1 + ORDER BY ABS(HASH(*)) building
in SnowflakeAdapter.sample_rows and materialise_sample with the shared
render_sample_select(..., order_by_hash=True) helper (US-001). Snowflake's
HASH(*) is invalid in a WHERE/ORDER BY predicate (002079); the helper's
projection-subquery branch computes the hash once in an inner
SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash and the outer clauses reference
the alias, with SELECT * EXCLUDE (_sf_sample_hash) stripping the helper column
so returned rows / the materialised temp table carry only source columns.

Partition filters stay rendered by the adapter's own _render_partition_filter
and pass to the helper as extra_where (no name branch, no hard-coded HASH(*)).
Update the fakesnow/sqlglot adapter guards plus the test_snowflake_sampling
and test_snowflake_materialise unit assertions to the new shape.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../warehouse/adapters/snowflake.py           | 107 ++++++++++++------
 .../test_snowflake_adapter_fakesnow.py        |  38 +++++--
 tests/warehouse/test_snowflake_materialise.py |  23 +++-
 tests/warehouse/test_snowflake_sampling.py    |  33 ++++--
 4 files changed, 137 insertions(+), 64 deletions(-)

diff --git a/src/signalforge/warehouse/adapters/snowflake.py b/src/signalforge/warehouse/adapters/snowflake.py
index bb0b69d6..f36c1335 100644
--- a/src/signalforge/warehouse/adapters/snowflake.py
+++ b/src/signalforge/warehouse/adapters/snowflake.py
@@ -73,6 +73,7 @@
 from typing import TYPE_CHECKING, Any
 
 from signalforge.warehouse._sample_id import _compute_run_id, _hash_session_id
+from signalforge.warehouse._sample_sql import render_sample_select
 from signalforge.warehouse._sql_safety import validate_identifier, validate_test_sql
 from signalforge.warehouse.base import WarehouseAdapter
 from signalforge.warehouse.errors import (
@@ -595,31 +596,53 @@ def sample_rows(
            * ``num_rows >= _LARGE_TABLE_THRESHOLD`` + no ``partition_filter`` →
              :class:`SamplingRequiresPartitionFilterError`.
            * else → ``bucket = max(num_rows // n, 1)``.
-        3. Issue ``SELECT * FROM <quoted> AS t WHERE
-           MOD(<dialect.sample_row_hash_expr>, <bucket>) < 1
-           [AND <partition_filter>] ORDER BY <dialect.sample_row_hash_expr>
-           LIMIT n``.
-
-        The hash-mod approach (``MOD(ABS(HASH(*)), bucket)``) is deterministic
-        across runs (same input → same prune decision) and works on views /
-        MVs / CTEs where ``TABLESAMPLE`` does not. The hash expression is read
-        from :data:`SNOWFLAKE_DIALECT` (NOT hard-coded) so the adapter's sample
-        SQL is byte-consistent with the prune compiler's sample CTE. The
+        3. Emit the deterministic sample SELECT via the shared
+           :func:`signalforge.warehouse._sample_sql.render_sample_select`
+           helper (``order_by_hash=True``). For Snowflake
+           (``sample_hash_in_projection=True``) this is the projection-subquery
+           form (issue #139)::
+
+               SELECT * EXCLUDE (_sf_sample_hash) FROM
+               (SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash FROM <quoted> AS t)
+               WHERE MOD(_sf_sample_hash, <bucket>) < 1[ AND <partition_filter>]
+               ORDER BY _sf_sample_hash LIMIT n
+
+           ``HASH(*)`` is invalid in a Snowflake ``WHERE``/``ORDER BY``
+           predicate (``002079``); it is legal only in the SELECT projection,
+           so the hash is computed once in an inner projection bound to
+           ``_sf_sample_hash`` and the outer clauses reference that alias.
+           ``SELECT * EXCLUDE (_sf_sample_hash)`` strips the helper column so
+           returned dict rows carry only the source columns.
+
+        The hash-mod approach is deterministic across runs (same input → same
+        prune decision) and works on views / MVs / CTEs where ``TABLESAMPLE``
+        does not. The hash expression and sample SHAPE are read from
+        :data:`SNOWFLAKE_DIALECT` (NOT hard-coded) so the adapter's sample SQL
+        is byte-consistent with the prune compiler's sample CTE. The
         ``ORDER BY`` makes ``LIMIT`` truncation deterministic when the WHERE
-        filter retains more than ``n`` rows.
+        filter retains more than ``n`` rows. The partition filter is rendered
+        by the adapter's own :meth:`_render_partition_filter` and passed to the
+        helper as ``extra_where`` — the helper never renders partition filters.
         """
         if n <= 0:
             raise ValueError(f"sample_rows requires n > 0; got n={n}")
 
         bucket = self._resolve_sample_bucket(table, n, partition_filter=partition_filter)
 
-        hash_expr = SNOWFLAKE_DIALECT.sample_row_hash_expr
         quoted = self._quote(table)
-        where_clauses = [f"MOD({hash_expr}, {bucket}) < 1"]
-        if partition_filter is not None:
-            where_clauses.append(self._render_partition_filter(partition_filter))
-        where_sql = " AND ".join(where_clauses)
-        sql = f"SELECT * FROM {quoted} AS t WHERE {where_sql} ORDER BY {hash_expr} LIMIT {n}"
+        extra_where = (
+            self._render_partition_filter(partition_filter)
+            if partition_filter is not None
+            else None
+        )
+        sql = render_sample_select(
+            quoted,
+            dialect=SNOWFLAKE_DIALECT,
+            sample_bucket=bucket,
+            sample_size=n,
+            extra_where=extra_where,
+            order_by_hash=True,
+        )
 
         return self._execute_to_dicts(sql, table=table)
 
@@ -651,13 +674,22 @@ def materialise_sample(
         :meth:`run_test_sql` on the same connection reaches the temp table (no
         ``connection_properties`` routing needed, unlike BigQuery).
 
-        DEC-006 — the deterministic ``MOD(<dialect.sample_row_hash_expr>,
-        <bucket>) < 1`` predicate + ``ORDER BY <dialect.sample_row_hash_expr>``
-        are read from :data:`SNOWFLAKE_DIALECT` (NOT hard-coded) so the CTAS
-        bytes stay consistent with :meth:`sample_rows` and the prune compiler's
-        sample CTE (Architectural Commitment #5). ``partition_filter`` lands
-        ONCE here, in the CTAS ``WHERE``; per-test queries against the temp
-        table do not re-apply it.
+        DEC-006 — the deterministic sample SELECT body is built by the shared
+        :func:`signalforge.warehouse._sample_sql.render_sample_select` helper
+        (``order_by_hash=True``), which for Snowflake emits the
+        projection-subquery shape (issue #139): the hash is computed once in an
+        inner ``SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash`` and the outer
+        ``WHERE``/``ORDER BY`` reference the alias, with
+        ``SELECT * EXCLUDE (_sf_sample_hash)`` stripping the helper column so
+        the temp table's schema equals the SOURCE schema (load-bearing —
+        downstream prune queries the temp table by its real columns). The hash
+        expression and shape are read from :data:`SNOWFLAKE_DIALECT` (NOT
+        hard-coded) so the CTAS bytes stay consistent with :meth:`sample_rows`
+        and the prune compiler's sample CTE (Architectural Commitment #5).
+        ``partition_filter`` lands ONCE here, in the CTAS ``WHERE`` (rendered by
+        :meth:`_render_partition_filter` and passed to the helper as
+        ``extra_where``); per-test queries against the temp table do not
+        re-apply it.
 
         DEC-007 — the ``TEMP TABLE`` is colocated with the SOURCE (created as
         ``<source db>.<source schema>._sf_sample_<run_id>``) and the returned
@@ -703,24 +735,29 @@ def materialise_sample(
         # Shared fail-loud sizing pathway (same as sample_rows; DEC-005).
         bucket = self._resolve_sample_bucket(table, n, partition_filter=partition_filter)
 
-        hash_expr = SNOWFLAKE_DIALECT.sample_row_hash_expr
         quoted_source = self._quote(table)
         # The TEMP TABLE is colocated with the source (DEC-007): same DB /
         # schema, per-component quoted, with the deterministic temp name.
         temp_ref = TableRef(project=table.project, dataset=table.dataset, name=temp_name)
         quoted_temp = self._quote(temp_ref)
 
-        where_clauses = [f"MOD({hash_expr}, {bucket}) < 1"]
-        if partition_filter is not None:
-            where_clauses.append(self._render_partition_filter(partition_filter))
-        where_sql = " AND ".join(where_clauses)
-        sql = (
-            f"CREATE TEMPORARY TABLE {quoted_temp} AS "
-            f"SELECT * FROM {quoted_source} AS t "
-            f"WHERE {where_sql} "
-            f"ORDER BY {hash_expr} "
-            f"LIMIT {n}"
+        extra_where = (
+            self._render_partition_filter(partition_filter)
+            if partition_filter is not None
+            else None
+        )
+        # The projection-subquery SELECT body (issue #139): SELECT * EXCLUDE
+        # (_sf_sample_hash) so the CTAS temp table's schema equals the source
+        # schema — no extra hash column leaks into the materialised sample.
+        select_body = render_sample_select(
+            quoted_source,
+            dialect=SNOWFLAKE_DIALECT,
+            sample_bucket=bucket,
+            sample_size=n,
+            extra_where=extra_where,
+            order_by_hash=True,
         )
+        sql = f"CREATE TEMPORARY TABLE {quoted_temp} AS {select_body}"
 
         # Open / reuse the connection (also sets self._active_session) and stamp
         # the session-open time as run provenance (NOT consumed by the cleanup
diff --git a/tests/warehouse/test_snowflake_adapter_fakesnow.py b/tests/warehouse/test_snowflake_adapter_fakesnow.py
index 36db94df..f85f426a 100644
--- a/tests/warehouse/test_snowflake_adapter_fakesnow.py
+++ b/tests/warehouse/test_snowflake_adapter_fakesnow.py
@@ -340,30 +340,39 @@ def test_get_num_rows_returns_none_for_absent_table() -> None:
 
 
 def test_sample_rows_emitted_sql_parses_under_snowflake_dialect() -> None:
-    """``sample_rows`` emits ``MOD(ABS(HASH(*)), <bucket>) < 1`` + ``ORDER BY
-    ABS(HASH(*))`` — fakesnow's DuckDB ``HASH`` cannot RUN it (variadic
-    ``HASH(*)``; DEC-005 of #121), so this is parse-only. The SQL MUST parse as
-    valid Snowflake."""
+    """``sample_rows`` emits the projection-subquery shape (issue #139): an
+    inner ``SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash`` with the outer
+    ``WHERE MOD(_sf_sample_hash, <bucket>) < 1`` + ``ORDER BY _sf_sample_hash``
+    + ``SELECT * EXCLUDE (_sf_sample_hash)``. ``HASH(*)`` is invalid in a
+    Snowflake WHERE/ORDER BY predicate, so the old inline form is GONE.
+    fakesnow's DuckDB ``HASH`` cannot RUN variadic ``HASH(*)`` (DEC-005 of
+    #121), so this is parse-only. The SQL MUST parse as valid Snowflake."""
     conn = _RecordingConnection()
     # num_rows=1000, n=100 → bucket = max(1000 // 100, 1) = 10.
     conn.expect_execute(matching=r"INFORMATION_SCHEMA", returns=[(1000,)])
-    conn.expect_execute(matching=r"MOD\(ABS\(HASH", returns=[], description=[])
+    conn.expect_execute(matching=r"_sf_sample_hash", returns=[], description=[])
     adapter = SnowflakeAdapter(connection=conn)
 
     adapter.sample_rows(_TABLE, 100)
 
     sample_sql = conn.executed[1]
-    assert "MOD(ABS(HASH(*)), 10) < 1" in sample_sql
-    assert "ORDER BY ABS(HASH(*))" in sample_sql
+    assert "SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash" in sample_sql
+    assert "SELECT * EXCLUDE (_sf_sample_hash)" in sample_sql
+    assert "MOD(_sf_sample_hash, 10) < 1" in sample_sql
+    assert "ORDER BY _sf_sample_hash" in sample_sql
+    # The old inline predicate / order-by forms are GONE.
+    assert "MOD(ABS(HASH(*)), 10)" not in sample_sql
+    assert "ORDER BY ABS(HASH(*))" not in sample_sql
     _parse_snowflake(sample_sql)
 
 
 def test_materialise_ctas_emitted_sql_parses_under_snowflake_dialect() -> None:
     """The ``materialise_sample`` CTAS emits ``CREATE TEMPORARY TABLE
-    "<db>"."<schema>"."_sf_sample_<run_id>" AS SELECT ... HASH(*) ...`` —
-    fakesnow rejects a qualified temp-table name ("TEMPORARY table names can
-    *only* use the 'temp' catalog") AND cannot run ``HASH(*)``, so this is
-    parse-only. The SQL MUST parse as valid Snowflake."""
+    "<db>"."<schema>"."_sf_sample_<run_id>" AS <projection-subquery SELECT>``
+    (issue #139). fakesnow rejects a qualified temp-table name ("TEMPORARY
+    table names can *only* use the 'temp' catalog") AND cannot run variadic
+    ``HASH(*)``, so this is parse-only. The SQL MUST parse as valid
+    Snowflake."""
     conn = _RecordingConnection()
     conn.expect_execute(matching=r"INFORMATION_SCHEMA", returns=[(1000,)])
     conn.expect_execute(matching=r"CREATE TEMPORARY TABLE", returns=[])
@@ -373,7 +382,12 @@ def test_materialise_ctas_emitted_sql_parses_under_snowflake_dialect() -> None:
 
     ctas = conn.executed[1]
     assert ctas.startswith("CREATE TEMPORARY TABLE")
-    assert "MOD(ABS(HASH(*)), 10) < 1" in ctas
+    assert "SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash" in ctas
+    assert "SELECT * EXCLUDE (_sf_sample_hash)" in ctas
+    assert "MOD(_sf_sample_hash, 10) < 1" in ctas
+    assert "ORDER BY _sf_sample_hash" in ctas
+    # The old inline predicate form is GONE.
+    assert "MOD(ABS(HASH(*)), 10)" not in ctas
     _parse_snowflake(ctas)
 
 
diff --git a/tests/warehouse/test_snowflake_materialise.py b/tests/warehouse/test_snowflake_materialise.py
index 5d170ffa..bb5693c1 100644
--- a/tests/warehouse/test_snowflake_materialise.py
+++ b/tests/warehouse/test_snowflake_materialise.py
@@ -75,8 +75,11 @@ def _expected_run_id() -> str:
 def test_materialise_ctas_sql_shape_and_temp_name() -> None:
     """The CTAS contains ``CREATE TEMPORARY TABLE``, the deterministic
     ``_sf_sample_<run_id>`` name (run_id byte-identical to the shared recipe),
-    the ``MOD(ABS(HASH(*)), <bucket>) < 1`` predicate, ``ORDER BY
-    ABS(HASH(*))``, ``LIMIT n``; the source is per-component quoted."""
+    the projection-subquery sample body (#139) — inner
+    ``SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash`` with outer
+    ``MOD(_sf_sample_hash, <bucket>) < 1`` + ``ORDER BY _sf_sample_hash`` +
+    ``SELECT * EXCLUDE (_sf_sample_hash)``, ``LIMIT n``; the source is
+    per-component quoted."""
     conn = _RecordingConnection()
     # num_rows=1000, n=100 → bucket = max(1000//100, 1) = 10.
     conn.expect_execute(matching=_SIZE_QUERY, returns=[(1000,)])
@@ -94,9 +97,15 @@ def test_materialise_ctas_sql_shape_and_temp_name() -> None:
     # upper-cased in the emitted SQL (the returned TableRef.name stays the
     # lowercase recipe output — folding happens only at quote time).
     assert temp_name.upper() in ctas
-    # Deterministic hash-mod predicate (read from the dialect, not hard-coded).
-    assert "MOD(ABS(HASH(*)), 10) < 1" in ctas
-    assert "ORDER BY ABS(HASH(*))" in ctas
+    # Projection-subquery shape (#139): hash in the inner projection, alias in
+    # the outer predicate / order-by; EXCLUDE strips the helper column so the
+    # temp table's schema equals the source schema. Read from the dialect, not
+    # hard-coded. The old inline HASH(*)-in-WHERE form is GONE.
+    assert "SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash" in ctas
+    assert "SELECT * EXCLUDE (_sf_sample_hash)" in ctas
+    assert "MOD(_sf_sample_hash, 10) < 1" in ctas
+    assert "ORDER BY _sf_sample_hash" in ctas
+    assert "MOD(ABS(HASH(*)), 10)" not in ctas
     assert ctas.rstrip().endswith("LIMIT 100")
     # Source is per-component quoted + fold-to-UPPER: "MYDATABASE"."SCH"."ORDERS".
     assert '"MYDATABASE"."SCH"."ORDERS"' in ctas
@@ -384,7 +393,9 @@ def test_materialise_applies_partition_filter_in_ctas() -> None:
     adapter.materialise_sample(_TABLE, 100, partition_filter=pf)
 
     ctas = conn.executed[1]
-    assert "MOD(ABS(HASH(*)), 10) < 1" in ctas
+    # Projection-subquery shape (#139): the partition predicate is ANDed at the
+    # OUTER level alongside the alias-based hash-mod predicate.
+    assert "MOD(_sf_sample_hash, 10) < 1 AND " in ctas
     # Rendered via SNOWFLAKE_DIALECT.date_literal_template: '{value}'::DATE.
     assert "'2026-01-01'::DATE" in ctas
     assert ctas.count("'2026-01-01'::DATE") == 1
diff --git a/tests/warehouse/test_snowflake_sampling.py b/tests/warehouse/test_snowflake_sampling.py
index 9e889c9d..7512d853 100644
--- a/tests/warehouse/test_snowflake_sampling.py
+++ b/tests/warehouse/test_snowflake_sampling.py
@@ -1,8 +1,13 @@
 """Tests for ``SnowflakeAdapter.sample_rows`` (issue #122, US-003).
 
 Deterministic hash-mod sampling, the Snowflake analog of BigQuery's
-``MOD(ABS(FARM_FINGERPRINT(TO_JSON_STRING(t))), bucket)`` →
-``MOD(ABS(HASH(*)), bucket)`` (DEC-006). Same fail-loud sizing guards as
+``MOD(ABS(FARM_FINGERPRINT(TO_JSON_STRING(t))), bucket)``. Since issue #139 the
+Snowflake form is the projection-subquery shape — ``HASH(*)`` is invalid in a
+Snowflake ``WHERE``/``ORDER BY`` predicate, so the hash is computed once in an
+inner ``SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash`` and the outer
+``MOD(_sf_sample_hash, bucket) < 1`` references the alias, with
+``SELECT * EXCLUDE (_sf_sample_hash)`` stripping the helper column (DEC-006 of
+#122 + #139). Same fail-loud sizing guards as
 BigQuery (:class:`UnknownTableSizeError`,
 :class:`SamplingRequiresPartitionFilterError`; DEC-005). Tuple ``fetchall()``
 results are shaped into dicts via ``cursor.description`` (DEC-010); SDK
@@ -32,8 +37,10 @@
 # A regex that matches the INFORMATION_SCHEMA size lookup but NOT the sample
 # query, so the two expectations can't accidentally cross-match.
 _SIZE_QUERY = r"INFORMATION_SCHEMA\.TABLES"
-# The sample query starts with SELECT * and never touches INFORMATION_SCHEMA.
-_SAMPLE_QUERY = r"SELECT \* FROM"
+# The sample query carries the projection-subquery hash alias (issue #139) and
+# never touches INFORMATION_SCHEMA, so this distinguishes it from the size
+# lookup without cross-matching.
+_SAMPLE_QUERY = r"_sf_sample_hash"
 
 # ``project`` is the database; it follows :class:`TableRef`'s GCP-style
 # project-id grammar (lowercase start, >= 6 chars), but Snowflake quotes it
@@ -87,9 +94,13 @@ def test_sample_sql_is_byte_identical_across_two_calls() -> None:
 
     assert sample_sqls[0] == sample_sqls[1]
     sql = sample_sqls[0]
-    # num_rows=1000, n=100 → bucket = max(1000//100, 1) = 10.
-    assert "MOD(ABS(HASH(*)), 10) < 1" in sql
-    assert "ORDER BY ABS(HASH(*))" in sql
+    # num_rows=1000, n=100 → bucket = max(1000//100, 1) = 10. Projection-
+    # subquery shape (#139): hash in the inner projection, alias in the outer
+    # predicate / order-by.
+    assert "SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash" in sql
+    assert "SELECT * EXCLUDE (_sf_sample_hash)" in sql
+    assert "MOD(_sf_sample_hash, 10) < 1" in sql
+    assert "ORDER BY _sf_sample_hash" in sql
     assert "LIMIT 100" in sql
     # Per-component double-quoting, fold-to-UPPER first (#124): lowercase
     # project "mydatabase" folds to "MYDATABASE" so it resolves against the
@@ -145,7 +156,7 @@ def test_null_row_count_with_filter_uses_bucket_1000() -> None:
     adapter.sample_rows(_TABLE, 100, partition_filter=pf)
 
     sample_sql = conn.executed[1]
-    assert "MOD(ABS(HASH(*)), 1000) < 1" in sample_sql
+    assert "MOD(_sf_sample_hash, 1000) < 1" in sample_sql
 
 
 def test_huge_row_count_no_filter_raises_requires_partition_filter() -> None:
@@ -169,7 +180,7 @@ def test_huge_row_count_with_filter_proceeds() -> None:
     adapter.sample_rows(_TABLE, 100, partition_filter=pf)
 
     # bucket = max(200_000_000 // 100, 1) = 2_000_000.
-    assert "MOD(ABS(HASH(*)), 2000000) < 1" in conn.executed[1]
+    assert "MOD(_sf_sample_hash, 2000000) < 1" in conn.executed[1]
 
 
 def test_normal_row_count_buckets_num_rows_over_n() -> None:
@@ -182,7 +193,7 @@ def test_normal_row_count_buckets_num_rows_over_n() -> None:
     adapter.sample_rows(_TABLE, 100)
 
     # bucket = max(5000 // 100, 1) = 50.
-    assert "MOD(ABS(HASH(*)), 50) < 1" in conn.executed[1]
+    assert "MOD(_sf_sample_hash, 50) < 1" in conn.executed[1]
 
 
 def test_tiny_table_buckets_floor_at_one() -> None:
@@ -194,7 +205,7 @@ def test_tiny_table_buckets_floor_at_one() -> None:
 
     adapter.sample_rows(_TABLE, 100)
 
-    assert "MOD(ABS(HASH(*)), 1) < 1" in conn.executed[1]
+    assert "MOD(_sf_sample_hash, 1) < 1" in conn.executed[1]
 
 
 # ---------------------------------------------------------------------------

From 70c257d81f9c681bdad5f329c00e9c5fc9aa7d07 Mon Sep 17 00:00:00 2001
From: wjduenow <wjduenow@gmail.com>
Date: Wed, 27 May 2026 10:17:09 -0700
Subject: [PATCH 06/10] bd_1-scaffolding-kay.4: #139 US-004 re-enable live
 materialised prune e2e at scope=sample + 5-surface docs

Flip test_snowflake_prune_live.py to scope=sample + sample_strategy=materialised
(exercising the #139 projection-subquery CTAS); rename to
test_prune_drops_always_passes_not_null_live_materialised_sample. Two-gate
discipline (marker + runtime _skip_reason) preserved; self-skips cleanly offline.
DEC-004 primary/fallback note added to the module docstring. 5-surface graduation:
warehouse-adapter-ops.md (remove HASH(*)-in-predicate limitation; materialised
sample-mode now works), .claude/rules/warehouse-adapters.md (new Dialect fields +
mark bd_1-scaffolding-cdp FIXED), .claude/rules/prune-engine.md (compiler dialect
field list + render_sample_select delegation).

Live certification still pending (maintainer-run with SF_RUN_SNOWFLAKE=1).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .claude/rules/prune-engine.md                |   1 +
 .claude/rules/warehouse-adapters.md          |   6 +-
 docs/warehouse-adapter-ops.md                |  79 ++++++++-----
 tests/warehouse/test_snowflake_prune_live.py | 118 ++++++++++++-------
 4 files changed, 129 insertions(+), 75 deletions(-)

diff --git a/.claude/rules/prune-engine.md b/.claude/rules/prune-engine.md
index 22bff88c..fa087760 100644
--- a/.claude/rules/prune-engine.md
+++ b/.claude/rules/prune-engine.md
@@ -64,6 +64,7 @@ Issue #121 made the compiler emit valid **Snowflake** SQL by extending `Dialect`
 - `identifier_case` — **graduated from declared-but-unused to load-bearing in #121.** `_fold_identifier`/`_quote` fold every identifier (columns AND each qualified-name component) per `"upper"`/`"lower"`/`"preserve"` BEFORE quoting. Snowflake folds to UPPER (a conventional `CREATE TABLE(customer_id)` stores `CUSTOMER_ID`, so emitting `"customer_id"` would fail); BigQuery `"preserve"` is a no-op so its snapshots stay byte-identical. Folding runs on an already-`validate_identifier`'d ASCII token, so it cannot introduce a quote-breaking char (DEC-024 still gates).
 - `quote_qualified_per_component` — `True` quotes each component separately (`"DB"."SCH"."T"` — Snowflake/Postgres); `False` wraps the whole dotted path in one quote pair (BigQuery `` `p.d.t` ``). A single quoted string spanning dots would read as one identifier literally named `db.schema.table`.
 - `sample_row_hash_expr` — the deterministic-sample row-hash expression dropped into `MOD(<expr>, <bucket>) < 1`. BigQuery `ABS(FARM_FINGERPRINT(TO_JSON_STRING(t)))`; Snowflake `ABS(HASH(*))`.
+- `sample_hash_in_projection` + `sample_hash_alias` (issue #139) — the structural sample SHAPE switch. `sample_hash_in_projection=False` (BigQuery) emits the row hash inline in `WHERE`/`ORDER BY`; `True` (Snowflake) emits the **projection-subquery** form — `SELECT * EXCLUDE (<alias>) FROM (SELECT t.*, <hash_expr> AS <alias> FROM <src> AS t) WHERE MOD(<alias>, b) < 1 …` — because Snowflake rejects `HASH(*)` as a predicate (`002079`) and accepts it only in the SELECT projection. `sample_hash_alias` defaults to `"_sf_sample_hash"`. **The compiler's sample CTE delegates to `signalforge.warehouse._sample_sql.render_sample_select` (shared with the `SnowflakeAdapter` sample methods, calling it with `order_by_hash=False`)**, so the CTE body and the adapter sample SELECT stay byte-consistent; the helper switches on the boolean field, never `dialect.name`, so the import-guard stays green. BigQuery's emitted bytes are unchanged (default `False` reproduces the prior inline CTE body).
 - `timestamp_literal_template` / `date_literal_template` — `str.format(value=…)` templates for partition-filter literals. BigQuery `TIMESTAMP('{value}')` / `DATE('{value}')`; Snowflake `'{value}'::TIMESTAMP` / `'{value}'::DATE`. Only the `datetime`/`date` branches format; the `str` branch routes through `escape_bq_string_literal` (no `.format`).
 - `sample_cte_alias` — the identifier the sample CTE is bound to (`WITH <alias> AS (...) ... FROM <alias>`). BigQuery bare `sample`; **Snowflake quoted `"sample"`** because `SAMPLE` is a Snowflake reserved keyword (`TABLESAMPLE`) and an unquoted `WITH sample AS` is a syntax error there. This bug was caught in #121's Quality Gate by the gated `sqlglot`-parse guard, NOT by snapshots — a snapshot can pin invalid SQL byte-for-byte. **Lesson: a new dialect's SQL needs a parser/executor in the loop, not just snapshot equality.**
 
diff --git a/.claude/rules/warehouse-adapters.md b/.claude/rules/warehouse-adapters.md
index 80252efe..0d47a316 100644
--- a/.claude/rules/warehouse-adapters.md
+++ b/.claude/rules/warehouse-adapters.md
@@ -29,14 +29,14 @@ The ABC is warehouse-agnostic. v0.2 Snowflake/Postgres slot under `adapters/` wi
 **Snowflake sampling + connection-bound session (issue #122).** `SnowflakeAdapter` implements the sampling surface — `sample_rows`, `materialise_sample`, `run_test_sql` (`column_stats` stays `NotImplementedError`; `estimate_query_bytes` was the ABC degrade pending #123 at the time of #122, then graduated to a real `EXPLAIN USING JSON` override in #130 — see the `estimate_query_bytes` graduation note below). Five load-bearing conventions, most diverging from BigQuery because Snowflake's session model differs:
 
 - **The connection IS the session (no `session_id` string).** BigQuery threads a server-side `session_id` via `connection_properties` on every query (§ "Session/connection state"); Snowflake's *connection* holds the session, so `self._active_session` stores the **connection object** itself and every op runs on the one connection. A `connection=` injection seam on `__init__` (mirrors BigQuery's `client=`) + lazy `_get_connection()` (builds via the shim's `make_real_client` on first use) is the testability seam. `_get_connection()` sets `_active_session` on first open.
-- **Reuse the `SNOWFLAKE_DIALECT` SQL-fragment fields — never hard-code `HASH(*)`.** `sample_rows` and the `materialise_sample` CTAS build `MOD(<dialect.sample_row_hash_expr>, <bucket>) < 1` + `ORDER BY <…>` and render partition filters via `dialect.timestamp_literal_template` / `date_literal_template`. Reading the dialect (not hard-coding) keeps the adapter's sample SQL byte-consistent with the prune compiler's sample CTE (Architectural Commitment #5).
+- **Reuse the `SNOWFLAKE_DIALECT` SQL-fragment fields — never hard-code `HASH(*)`.** `sample_rows` and the `materialise_sample` CTAS delegate to `signalforge.warehouse._sample_sql.render_sample_select(..., order_by_hash=True)` (shared with the prune compiler's sample CTE — issue #139), which reads `dialect.sample_row_hash_expr`, `dialect.sample_hash_in_projection`, `dialect.sample_hash_alias`; partition filters are rendered by the caller via `dialect.timestamp_literal_template` / `date_literal_template` and passed in as `extra_where`. Reading the dialect (not hard-coding) keeps the adapter's sample SQL byte-consistent with the prune compiler's sample CTE (Architectural Commitment #5). **Since #139 Snowflake emits the projection-subquery shape** — `SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash FROM <src> AS t) WHERE MOD(_sf_sample_hash, b) < 1 [AND <pf>] ORDER BY _sf_sample_hash LIMIT n` — because `HASH(*)` is rejected as a `WHERE`/`ORDER BY` predicate (`002079`); BigQuery keeps the inline form (`sample_hash_in_projection=False`).
 - **Table size via `INFORMATION_SCHEMA.TABLES.ROW_COUNT`, case-insensitive.** `_get_num_rows` queries `SELECT ROW_COUNT FROM <db>.INFORMATION_SCHEMA.TABLES WHERE UPPER(TABLE_SCHEMA)=UPPER('…') AND UPPER(TABLE_NAME)=UPPER('…')` (schema/name embedded as escaped string literals via `escape_bq_string_literal` — Snowflake uses backslash escaping too; when `project is None` the query is left **unqualified** — `INFORMATION_SCHEMA.TABLES`, resolved against the session's current database — NOT `CURRENT_DATABASE().INFORMATION_SCHEMA`, which is invalid Snowflake since `CURRENT_DATABASE()` is a scalar function, not a namespace qualifier). `ROW_COUNT` is NULL for views/MVs → routes through the *same* fail-loud sizing decision BigQuery uses (unknown+no-filter → `UnknownTableSizeError`; unknown+filter → `bucket=1000`; `>= _LARGE_TABLE_THRESHOLD` (100M, re-declared not imported) + no-filter → `SamplingRequiresPartitionFilterError`; else `max(num_rows//n, 1)`). `num_rows == 0` follows the unknown pathway (pin a test — easy to split from `None` by accident).
 - **`materialise_sample` returns a fully-qualified temp `TableRef`; reuse the shared `run_id` recipe.** `CREATE TEMPORARY TABLE "<src db>"."<src schema>"."_sf_sample_<run_id>" AS SELECT …` colocated with the source; returns `TableRef(project=table.project, dataset=table.dataset, name="_sf_sample_<run_id>")`. `run_id` comes from `signalforge.warehouse._sample_id` (`_compute_run_id` / `_canonical_partition_filter` / `_hash_session_id` were **hoisted there from `adapters/bigquery.py` in #122** so the recipe is byte-identical across vendors — both adapters import it; relocation is a pure move, BigQuery snapshots unchanged). The #116 materialised-sample-substitution gotcha (`prune-engine.md`) is pinned with a **`custom_sql` `{{ this }}`** test at `scope="full"` — NOT `not_null`, which trivially `FROM`s `table_ref` and so can never bypass substitution.
 - **Cleanup-boundary fail-soft, reshaped for Snowflake (no manual command).** `__exit__` → `_cleanup_active_session()` closes the connection (reaping its session-scoped temp tables), swallows failure, emits ONE operator-actionable WARNING. Unlike BigQuery's `bq query … CALL BQ.ABORT_SESSION()` remediation, **there is no manual drop command** — a temp table is unreachable outside its owning session, so the honest durable fallback is Snowflake's server-side idle-session reap. The WARNING quotes **no `auto-expire in <N>s` countdown** (the timeout is server-side/account-config; `ttl_seconds` is accepted for ABC parity but ignored; `_session_started_at` is provenance only). Raw `session_id` appears only in the failure WARNING (DEC-014 narrow exception); the success INFO uses `_hash_session_id`. State resets in `finally` for idempotency — but **do NOT null `self._connection`** there: idempotency comes from the `_active_session is None` early-return, and nulling an injected connection would silently route a re-entry into a real lazy-build (mirrors BigQuery, which never nulls its client).
 
 Minimal `map_snowflake_exception` (in the shim, lazy SDK-error import) maps auth → `WarehouseAuthError`, programming → `QuerySyntaxError`, else passthrough; the full taxonomy + fakesnow harness + gated live e2e + ops docs are #124.
 
-**`Dialect` now carries prune-compiler SQL-fragment templates (issue #121).** The `Dialect` value object (`warehouse/models.py`) graduated from pure capability flags to also carrying the declarative SQL fragments the prune compiler reads so it can emit warehouse-correct SQL without branching on `dialect.name`: `sample_row_hash_expr`, `timestamp_literal_template`, `date_literal_template`, `quote_qualified_per_component`, and `sample_cte_alias` (all BigQuery-defaulted so existing constants/snapshots are byte-unchanged). `SNOWFLAKE_DIALECT` sets them to Snowflake forms (`ABS(HASH(*))`, `'{value}'::TIMESTAMP/::DATE`, per-component quoting, the quoted `"sample"` CTE alias — `SAMPLE` is reserved in Snowflake). When a future vendor adapter ships its own `Dialect`, populate these fields too — the compiler is the consumer and it never name-branches (see `prune-engine.md` § "Compiler is dialect-driven"). `identifier_case` graduated from declared-but-unused to load-bearing in the same change (the compiler folds identifiers per it before quoting). `POSTGRES_DIALECT` keeps BigQuery defaults for the new fields with a docstring note — the Postgres stub never invokes the compiler, so they're corrected when its ops land.
+**`Dialect` now carries prune-compiler SQL-fragment templates (issue #121, extended #139).** The `Dialect` value object (`warehouse/models.py`) graduated from pure capability flags to also carrying the declarative SQL fragments the prune compiler reads so it can emit warehouse-correct SQL without branching on `dialect.name`: `sample_row_hash_expr`, `timestamp_literal_template`, `date_literal_template`, `quote_qualified_per_component`, `sample_cte_alias`, and (issue #139) `sample_hash_in_projection: bool` + `sample_hash_alias: str` (all BigQuery-defaulted so existing constants/snapshots are byte-unchanged). `SNOWFLAKE_DIALECT` sets them to Snowflake forms (`ABS(HASH(*))`, `'{value}'::TIMESTAMP/::DATE`, per-component quoting, the quoted `"sample"` CTE alias — `SAMPLE` is reserved in Snowflake — and `sample_hash_in_projection=True` + `sample_hash_alias="_sf_sample_hash"` so the shared `_sample_sql.render_sample_select` emits the projection-subquery sample shape rather than an inline `HASH(*)` predicate). When a future vendor adapter ships its own `Dialect`, populate these fields too — the compiler is the consumer and it never name-branches (see `prune-engine.md` § "Compiler is dialect-driven"). `identifier_case` graduated from declared-but-unused to load-bearing in the same change (the compiler folds identifiers per it before quoting). `POSTGRES_DIALECT` keeps BigQuery defaults for the new fields with a docstring note — the Postgres stub never invokes the compiler, so they're corrected when its ops land.
 
 ## Unified multi-warehouse `DbtProfileTarget` + per-type cross-field validator (issue #120)
 
@@ -235,7 +235,7 @@ When introducing a new fail-soft cleanup boundary (Postgres temp-table cleanup,
 
 The gated `snowflake` marker now spans offline (`fakesnow`/`sqlglot`, run with no env vars) AND live (`SF_RUN_SNOWFLAKE=1` + conn vars, +`SNOWFLAKE_DATABASE`/`SCHEMA` writable for the engineered prune-live table, +`ANTHROPIC_API_KEY` for the full pipeline) tests under one `uv run pytest -m snowflake --no-cov`. The `docs/warehouse-adapter-ops.md` § "Snowflake adapter (v0.2)" carries the consolidated operator story incl. the **cost guidance** (resource monitor FIRST, XS warehouse, aggressive auto-suspend) that any live Snowflake test must surface in its module docstring.
 
-**Live-harness findings — fakesnow/fakes hid multiple live-only adapter bugs (the #124 payoff).** Running the gated suite against a real warehouse surfaced bugs that the offline `fakesnow` + hand-fakes could not, because fakesnow's DuckDB cursor/result shapes diverge from the real connector's. The lesson generalises the #121 "parser/executor in the loop" rule: a vendor adapter is NOT certified until a live run exercises every path; fakes prove behaviour-against-a-contract, not behaviour-against-the-vendor. Concretely #124's live run found, in order: (1) **`_quote` case-folding** (fixed here — the adapter must fold-then-quote identically to the compiler, else CREATE-vs-REFERENCE diverge); (2) **`ARRAY_AGG(OBJECT_CONSTRUCT(*))` capture-failures samples come back as a JSON *string*** (a VARIANT), not a Python list — `run_test_sql` must `json.loads` it before iterating (fakesnow returned a list, so offline passed); (3) **`HASH(*)` is invalid in WHERE/ORDER BY** on Snowflake → all sample-mode SQL is rejected (bead `bd_1-scaffolding-cdp`); (4) **oneshot sample-bucket row-count routes through a BigQuery-only `_get_client`** the engine never made vendor-neutral (bead `bd_1-scaffolding-tft`). Net operator contract: **live Snowflake works today only with `safety: schema-only` + `prune.scope: full`** — both sample strategies + `safety: sample` + `aggregate-only` are deferred/beaded. When the next vendor adapter ships, budget a live-debugging pass; expect VARIANT/array columns as JSON strings and identifier case-folding mismatches as the first two things to break.
+**Live-harness findings — fakesnow/fakes hid multiple live-only adapter bugs (the #124 payoff).** Running the gated suite against a real warehouse surfaced bugs that the offline `fakesnow` + hand-fakes could not, because fakesnow's DuckDB cursor/result shapes diverge from the real connector's. The lesson generalises the #121 "parser/executor in the loop" rule: a vendor adapter is NOT certified until a live run exercises every path; fakes prove behaviour-against-a-contract, not behaviour-against-the-vendor. Concretely #124's live run found, in order: (1) **`_quote` case-folding** (fixed here — the adapter must fold-then-quote identically to the compiler, else CREATE-vs-REFERENCE diverge); (2) **`ARRAY_AGG(OBJECT_CONSTRUCT(*))` capture-failures samples come back as a JSON *string*** (a VARIANT), not a Python list — `run_test_sql` must `json.loads` it before iterating (fakesnow returned a list, so offline passed); (3) **`HASH(*)` is invalid in WHERE/ORDER BY** on Snowflake → all sample-mode SQL was rejected (bead `bd_1-scaffolding-cdp`) — **FIXED by #139**: the shared `_sample_sql.render_sample_select` now emits the projection-subquery shape (`SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash …)`) driven by `Dialect.sample_hash_in_projection`, so `materialise_sample` / `sample_rows` / the compiler sample CTE all compute the hash in the SELECT projection rather than the rejected predicate position; (4) **oneshot sample-bucket row-count routes through a BigQuery-only `_get_client`** the engine never made vendor-neutral (bead `bd_1-scaffolding-tft`, still open). Net operator contract: **live Snowflake works today with `safety: schema-only` + `prune.scope: full` OR `prune.scope: sample` + `prune.sample_strategy: materialised`** (the #139 projection-subquery fix) — `prune.sample_strategy: oneshot` (bead `bd_1-scaffolding-tft`) + `aggregate-only` (`column_stats`) remain deferred/beaded. When the next vendor adapter ships, budget a live-debugging pass; expect VARIANT/array columns as JSON strings, identifier case-folding mismatches, AND vendor clause-position constraints (a SQL fragment legal in one clause may be rejected in another — the #139 `HASH(*)` lesson) as the first things to break.
 
 ## Reference
 
diff --git a/docs/warehouse-adapter-ops.md b/docs/warehouse-adapter-ops.md
index 4f7a564c..2d83792c 100644
--- a/docs/warehouse-adapter-ops.md
+++ b/docs/warehouse-adapter-ops.md
@@ -360,14 +360,15 @@ non-BigQuery adapter then ships its own session-equivalent in v0.3
 `CREATE TEMP TABLE` inside a transaction). The ABC default-raise is
 the v0.2 stop-gap, not a permanent surface.
 
-> **Snowflake update (#122/#124):** Snowflake no longer inherits the
+> **Snowflake update (#122/#124/#139):** Snowflake no longer inherits the
 > `MaterialisationNotSupportedError` default — `materialise_sample` is
-> implemented. However, neither sample strategy is functional against a
-> *live* Snowflake yet (the `HASH(*)` sample SQL is rejected in
-> `WHERE`/`ORDER BY`, and oneshot's row-count routes through a BigQuery-only
-> seam). On Snowflake use **`prune.scope: full`**, NOT
-> `prune.sample_strategy: oneshot`; see "Known limitations on live Snowflake"
-> below.
+> implemented, and (since #139) emits a **projection-subquery** sample shape
+> (`SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ABS(HASH(*)) AS
+> _sf_sample_hash …)`) so the `HASH(*)` row-hash sits in the SELECT projection
+> rather than the rejected `WHERE`/`ORDER BY` position. **`materialised`
+> sample-mode prune now works on live Snowflake.** The `oneshot` strategy
+> remains blocked at a separate engine seam (its row-count routes through a
+> BigQuery-only `_get_client`); see "Known limitations on live Snowflake" below.
 
 ## Query-bytes estimation (v0.2, issue #36)
 
@@ -591,7 +592,16 @@ quoted `"sample"` CTE alias (`SAMPLE` is a Snowflake reserved word, so an
 unquoted `WITH sample AS …` is a syntax error). `HASH()` is deterministic
 only *within a Snowflake release* — sufficient for within-run prune
 determinism, not cross-time stable (mirrors the EXPLAIN planner-estimate
-caveat).
+caveat). Since #139 `SNOWFLAKE_DIALECT` also sets
+`sample_hash_in_projection=True` + `sample_hash_alias="_sf_sample_hash"`:
+`HASH(*)` is rejected as a `WHERE`/`ORDER BY` predicate (`002079`), so the
+shared `render_sample_select` helper computes the hash once in an inner
+`SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash` projection and references the
+`_sf_sample_hash` alias in the outer `WHERE MOD(…)`/`ORDER BY`, with
+`SELECT * EXCLUDE (_sf_sample_hash)` stripping the helper column so sampled
+rows carry only original columns. BigQuery keeps the default
+(`sample_hash_in_projection=False`) — its `FARM_FINGERPRINT` row hash is legal
+inline, so its emitted bytes are unchanged.
 
 **Connection-bound session.** Unlike BigQuery (which threads a server-side
 `session_id` on every query), the Snowflake *connection* holds the session
@@ -601,9 +611,12 @@ colocated with the source (each component fold-to-UPPER then quoted, per
 `_quote`), and `__exit__` closes the connection (reaping its temp tables).
 **Cost-relevant consequence:** the source table must be **writable** —
 materialised sampling against a read-only shared database (e.g.
-`SNOWFLAKE_SAMPLE_DATA`) fails the CTAS. Note that *all* sample-mode prune
-is currently non-functional on live Snowflake regardless (see "Known
-limitations" below); use `prune.scope: full` today.
+`SNOWFLAKE_SAMPLE_DATA`) fails the CTAS. The materialised-sample CTAS uses the
+#139 projection-subquery shape (`SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT
+t.*, ABS(HASH(*)) AS _sf_sample_hash …)`), so `prune.scope: sample` +
+`prune.sample_strategy: materialised` works on live Snowflake (against a
+writable source). The `oneshot` strategy is still blocked at a separate engine
+seam — see "Known limitations" below.
 
 **Session cleanup is fail-soft with no manual command.** A Snowflake temp
 table is unreachable outside its owning session, so there is no
@@ -631,30 +644,36 @@ passes through unchanged. No `BytesBilledExceededError` equivalent —
 Snowflake has no bytes-billed cap (cost is governed by warehouse size +
 auto-suspend, see below).
 
-**Known limitations on live Snowflake (v0.2) — use `safety: schema-only` +
-`prune.scope: full`.** Three deferred/defective paths mean a live Snowflake
-run today must stick to schema-only drafting and full-scope prune (the
-combination certified green by the gated live e2e). Each is tracked for a
-later fix:
+**Known limitations on live Snowflake (v0.2) — use `safety: schema-only`; for
+sampling prefer `prune.sample_strategy: materialised`.** Two
+deferred/defective paths remain after #139 fixed the `HASH(*)`-in-predicate bug.
+The combination certified green by the gated live e2e is `safety: schema-only` +
+`prune.scope: sample` + `prune.sample_strategy: materialised` (or
+`prune.scope: full`):
 
 - **`safety: aggregate-only` — unsupported.** Profiles columns via
   `adapter.column_stats`, which `SnowflakeAdapter` leaves as a deferred
   `NotImplementedError` (the one v0.2 method not yet implemented).
   `generate` with `safety.mode: aggregate-only` fails (exit 1).
-- **`safety: sample` and `prune.sample_strategy` (oneshot / materialised) —
-  unsupported.** All sampling emits the deterministic row-hash predicate
-  `MOD(ABS(HASH(*)), n) < 1` in `WHERE` / `ORDER BY`, which Snowflake rejects
-  (`002079`: `HASH(*)` is valid only in the `SELECT` projection). Needs a
-  projection-subquery sample shape (a Snowflake dialect-design gap).
-- **`prune.scope: sample` (oneshot) — also blocked** at the engine seam: the
-  sample row-count is fetched through a BigQuery-only `_get_client`;
-  `SnowflakeAdapter` exposes `_get_num_rows` instead. Needs a vendor-neutral
-  `WarehouseAdapter.get_table_metadata` seam.
-
-`schema-only` (redacted column names/types to the LLM) + `prune.scope: full`
-runs the full draft → prune → grade → diff pipeline against Snowflake today;
-`run_test_sql` (full-scope test execution) and `estimate_query_bytes` are
-implemented and certified live.
+- **`prune.scope: sample` with `prune.sample_strategy: oneshot` — blocked** at
+  the engine seam: the sample row-count is fetched through a BigQuery-only
+  `_get_client`; `SnowflakeAdapter` exposes `_get_num_rows` instead. Needs a
+  vendor-neutral `WarehouseAdapter.get_table_metadata` seam (bead
+  `bd_1-scaffolding-tft`). Use `materialised` (the default) instead.
+
+**Fixed by #139:** the deterministic row-hash sampling SQL no longer emits
+`MOD(ABS(HASH(*)), n) < 1` in `WHERE`/`ORDER BY` (which Snowflake rejected with
+`002079`). The shared `render_sample_select` helper now emits the
+projection-subquery form (`SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*,
+ABS(HASH(*)) AS _sf_sample_hash …)`), so `safety: sample` and
+`prune.scope: sample` + `prune.sample_strategy: materialised` work on live
+Snowflake (against a writable source — `materialise_sample` colocates its temp
+table in the source db/schema).
+
+`schema-only` (redacted column names/types to the LLM) runs the full
+draft → prune → grade → diff pipeline against Snowflake today; `run_test_sql`
+(test execution), `materialise_sample` (materialised sampling), and
+`estimate_query_bytes` are implemented and certified live.
 
 **Cost guidance — read before running any live Snowflake test.** Snowflake
 bills compute by warehouse-second, so an unbounded or forgotten run costs
diff --git a/tests/warehouse/test_snowflake_prune_live.py b/tests/warehouse/test_snowflake_prune_live.py
index 571a839e..ff8b50a2 100644
--- a/tests/warehouse/test_snowflake_prune_live.py
+++ b/tests/warehouse/test_snowflake_prune_live.py
@@ -1,26 +1,47 @@
-"""Gated live warehouse + prune-only e2e against a real Snowflake (#124 US-004).
-
-The offline `fakesnow` / `sqlglot` suite (`tests/prune/test_compiler_fakesnow.py`)
-pins the compiled Snowflake SQL's *shape* and parse-validity, and the sampling
-adapter is exercised via injected fakes in the default suite. Neither can
-certify the full prune-against-a-real-table path: create an engineered table,
-run a hand-crafted candidate test against it under ``prune.scope: full``, and
-watch the engine drop a `not_null` over a guaranteed-non-null column as
+"""Gated live materialised-sample prune e2e against a real Snowflake (#139 US-004).
+
+This is the **live certification for the projection-subquery sample shape** —
+the #139 fix for Snowflake's ``HASH(*)``-in-predicate rejection. The offline
+``fakesnow`` / ``sqlglot`` suite (``tests/prune/test_compiler_fakesnow.py``,
+``tests/warehouse/test_snowflake_adapter_fakesnow.py``) pins the compiled
+Snowflake SQL's *shape* and ``sqlglot`` parse-validity, but neither certifies
+that a **real** Snowflake accepts the new sample SQL: ``fakesnow``'s DuckDB
+backend cannot execute the variadic ``HASH(*)``, and ``sqlglot`` parses the
+*old* (invalid) inline form without complaint. Only a live run certifies the
+projection-subquery shape — create an engineered writable table, run a
+hand-crafted candidate test against it under
+``prune.scope: sample`` + ``prune.sample_strategy: materialised`` (which
+exercises ``materialise_sample``'s ``CREATE TEMPORARY TABLE … AS SELECT * EXCLUDE
+(_sf_sample_hash) FROM (SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash …)`` CTAS),
+and watch the engine drop a ``not_null`` over a guaranteed-non-null column as
 ``always-passes``.
 
-``scope: full`` (not a sample strategy) is load-bearing: live Snowflake
-sample-mode prune is NOT yet functional — ``oneshot`` needs the not-yet-built
-``WarehouseAdapter.get_table_metadata`` seam (the engine routes the sample
-row-count through a BigQuery-only ``_get_client``), and ``materialised`` emits
-``MOD(ABS(HASH(*)), n)`` in WHERE / ORDER BY, which Snowflake rejects
-(``HASH(*)`` is valid only in the SELECT projection). Both are tracked as
-separate #121/#122 bug beads; this test certifies the ``scope: full`` path that
-DOES work today. This module is the belt-and-suspenders half — a
-``@pytest.mark.snowflake``-gated test that drives a **real**
+Before #139, ``materialised`` sample-mode emitted ``MOD(ABS(HASH(*)), n)`` in
+WHERE / ORDER BY, which Snowflake rejects (``002079``: ``HASH(*)`` is valid only
+in the SELECT projection); that bug (bead ``bd_1-scaffolding-cdp``) is fixed by
+the projection-subquery shape + ``render_sample_select``. (A *separate*,
+still-open bug — ``oneshot`` routes the sample row-count through a BigQuery-only
+``_get_client`` / the not-yet-built ``WarehouseAdapter.get_table_metadata`` seam,
+bead ``bd_1-scaffolding-tft`` — is NOT in scope here; this test exercises the
+``materialised`` path, which colocates its temp table via the connection-bound
+session and does not hit that seam.) This module is the belt-and-suspenders half
+— a ``@pytest.mark.snowflake``-gated test that drives a **real**
 :class:`SnowflakeAdapter` through :func:`signalforge.prune.prune_tests` end to
 end against a live warehouse and asserts the v0.1 differentiator (Architectural
 Commitment #1: an always-pass test is dropped, not shipped).
 
+**DEC-004 primary/fallback note.** The emitted SQL uses the PRIMARY form:
+``ORDER BY _sf_sample_hash`` at the outer level where ``_sf_sample_hash`` is
+``SELECT * EXCLUDE``-d from the output projection. There is a genuine open
+question — resolvable only by this live run — whether Snowflake accepts
+``ORDER BY <col>`` when that column is ``SELECT * EXCLUDE``-d. If live Snowflake
+rejects ``ORDER BY`` of an EXCLUDE-d column, the fallback (DEC-004) is to drop
+the outer ``ORDER BY`` in ``render_sample_select`` + the fixtures; the
+deterministic ``MOD`` filter alone defines sample membership (matches the
+prune compiler CTE, which already emits no ``ORDER BY``). The fallback is NOT
+implemented here — the code ships the primary form; this docstring records the
+decision point the maintainer's live run resolves.
+
 NO LLM, NO ``generate`` CLI: this test builds the :class:`Model`,
 :class:`Manifest`, the :class:`CandidateSchema` (one
 :class:`CandidateTestNotNull`), and the :class:`PruneConfig` in-process and calls
@@ -47,8 +68,9 @@
   ``1``/``true``/``yes``/``on``).
 * ``SNOWFLAKE_ACCOUNT`` / ``SNOWFLAKE_USER`` / ``SNOWFLAKE_PASSWORD`` — the
   minimal password-auth connection triple.
-* ``SNOWFLAKE_WAREHOUSE`` — compute context for the engineered ``CREATE TABLE``
-  + the full-scope per-test ``COUNT(*)``.
+* ``SNOWFLAKE_WAREHOUSE`` — compute context for the engineered ``CREATE TABLE``,
+  the materialised-sample ``CREATE TEMPORARY TABLE … AS SELECT`` CTAS, and the
+  per-test ``COUNT(*)``.
 * ``SNOWFLAKE_DATABASE`` + ``SNOWFLAKE_SCHEMA`` — the **WRITABLE** target where
   the engineered table is created. The read-only ``SNOWFLAKE_SAMPLE_DATA`` share
   cannot accept a ``CREATE TABLE``, so a writable namespace is required; the
@@ -83,7 +105,9 @@
 rows on any sample → the prune engine routes it to ``always-passes`` (drop)
 mathematically, not probabilistically.
 
-Traces to: #124 US-004 (warehouse + prune-only gated live e2e).
+Traces to: #139 US-004 (live certification of the projection-subquery sample
+shape via materialised sample-mode prune); originally #124 US-004 (warehouse +
+prune-only gated live e2e, then pinned to ``scope=full``).
 """
 
 from __future__ import annotations
@@ -136,9 +160,9 @@ def _skip_reason() -> str | None:
 
     Returns ``None`` only when the opt-in flag AND every connection env var is
     present — the test then proceeds to make real Snowflake calls (CREATE TABLE,
-    a full-scope per-test ``COUNT(*)``, DROP TABLE). Each missing prerequisite
-    yields its own distinct reason so a maintainer running ``pytest -m
-    snowflake`` sees exactly what to set.
+    a materialised-sample CTAS, a per-test ``COUNT(*)``, DROP TABLE). Each
+    missing prerequisite yields its own distinct reason so a maintainer running
+    ``pytest -m snowflake`` sees exactly what to set.
     """
     if not _snowflake_runs_enabled():
         return "SF_RUN_SNOWFLAKE=1 required (live test talks to a real Snowflake warehouse)"
@@ -184,29 +208,36 @@ def _quoted_table(database: str, schema: str, name: str) -> str:
 
 
 @pytest.mark.snowflake
-def test_prune_drops_always_passes_not_null_live_full_scope() -> None:
-    """Prune a hand-crafted ``not_null`` against a live engineered table.
+def test_prune_drops_always_passes_not_null_live_materialised_sample() -> None:
+    """Prune a hand-crafted ``not_null`` against a live engineered table in
+    materialised sample-mode (the #139 projection-subquery sample shape).
 
     Skips cleanly under ``pytest -m snowflake`` when any prerequisite is
     missing. With credentials present:
 
     1. Creates a tiny engineered table in the writable
        ``SNOWFLAKE_DATABASE.SNOWFLAKE_SCHEMA`` — two columns where ``region`` is
-       the literal ``'austin'`` on every row (guaranteed non-null).
+       the literal ``'austin'`` on every row (guaranteed non-null). The table
+       MUST be in a writable schema: ``materialise_sample`` colocates its
+       ``CREATE TEMPORARY TABLE`` in the source db/schema, so read-only shared
+       data (``SNOWFLAKE_SAMPLE_DATA``) cannot be the source.
     2. Builds an in-process :class:`Model` / :class:`Manifest` /
        :class:`CandidateSchema` carrying ONE :class:`CandidateTestNotNull` over
        the guaranteed-non-null ``region`` column.
-    3. Calls :func:`prune_tests` with ``scope="full"`` — the engine runs the
-       compiled ``not_null`` against the full engineered table directly (no
-       sampling, no temp table). ``scope: full`` is required because live
-       Snowflake sample-mode prune is not yet functional (see module docstring
-       + #121/#122 bug beads); the engineered table is tiny so a full scan is
-       cheap.
+    3. Calls :func:`prune_tests` with ``scope="sample"`` +
+       ``sample_strategy="materialised"`` — the engine materialises a temp-table
+       sample via the projection-subquery CTAS (``CREATE TEMPORARY TABLE … AS
+       SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ABS(HASH(*)) AS
+       _sf_sample_hash …)``) and runs the compiled ``not_null`` against it. This
+       is the #139 fix: pre-fix, the ``MOD(ABS(HASH(*)), n)``-in-WHERE/ORDER-BY
+       form was rejected by Snowflake (``002079``).
     4. Asserts at least one :class:`PruneDecision` is
        ``decision == "dropped"`` with ``reason == "always-passes"`` — the v0.1
        differentiator (Architectural Commitment #1).
     5. Tears the engineered table down with ``DROP TABLE IF EXISTS`` in a
-       ``finally`` (idempotent; tolerates a partial-setup failure).
+       ``finally`` (idempotent; tolerates a partial-setup failure). The
+       materialised temp table is session-scoped and reaped when ``prune_tests``
+       closes the prune adapter's connection.
     """
     if reason := _skip_reason():
         pytest.skip(reason)
@@ -218,10 +249,11 @@ def test_prune_drops_always_passes_not_null_live_full_scope() -> None:
     quoted = _quoted_table(database, schema, table_name)
 
     # --- Setup: create the engineered table (own short-lived adapter). --------
-    # ``prune_tests`` (scope=full) runs the compiled ``not_null`` against this
-    # table on its OWN adapter/connection, so the table must persist beyond the
-    # setup session — a regular (non-temp) table created here, dropped in
-    # teardown.
+    # ``prune_tests`` (scope=sample, materialised) materialises a temp-table
+    # sample FROM this source table on its OWN adapter/connection, so the source
+    # must persist beyond the setup session — a regular (non-temp) table created
+    # here, dropped in teardown. (The materialised sample temp table is
+    # session-scoped and reaped when the prune adapter closes its connection.)
     setup_adapter = _make_adapter()
     with setup_adapter:
         cursor = setup_adapter._get_connection().cursor()
@@ -279,11 +311,13 @@ def test_prune_drops_always_passes_not_null_live_full_scope() -> None:
             ),
         )
 
-        # ``scope="full"`` — run the test against the full (tiny) engineered
-        # table. Sample-mode (oneshot / materialised) is not yet functional on
-        # live Snowflake (#121/#122 bug beads), and a full scan of a handful of
-        # rows is cheap.
-        config = PruneConfig(scope="full")
+        # ``scope="sample"`` + ``sample_strategy="materialised"`` — the engine
+        # materialises a temp-table sample via the #139 projection-subquery CTAS,
+        # then runs the compiled ``not_null`` against it. This exercises the
+        # exact path the #139 fix repairs (``HASH(*)`` moved into an inner
+        # SELECT projection + ``SELECT * EXCLUDE``). The engineered table is a
+        # handful of rows, so the CTAS + COUNT(*) are cheap.
+        config = PruneConfig(scope="sample", sample_strategy="materialised")
 
         # ``prune_tests`` owns the ``with adapter:`` block — pass a NOT-entered
         # adapter and do not wrap this call in our own ``with``.

From 91d979e5288e390c6d5f4d5b4ebcebdc4a3e3951 Mon Sep 17 00:00:00 2001
From: wjduenow <wjduenow@gmail.com>
Date: Wed, 27 May 2026 10:26:49 -0700
Subject: [PATCH 07/10] =?UTF-8?q?bd=5F1-scaffolding-kay.5:=20#139=20Qualit?=
 =?UTF-8?q?y=20gate=20=E2=80=94=20fix=20bugs=20from=20code=20review?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- harden the name-agnostic helper test with a symmetric inline-direction
  assertion (pins both branches against a dialect.name-based dispatch)
- correct stale docstring/comment in test_e2e_snowflake_smoke.py: the
  HASH(*)-in-WHERE/ORDER-BY shape bug is FIXED by #139 for both sample
  strategies; the remaining scope=full requirement here is the read-only
  SNOWFLAKE_SAMPLE_DATA share (materialised) + oneshot's open row-count
  seam (bd_1-scaffolding-tft), not the shape bug

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 tests/cli/test_e2e_snowflake_smoke.py | 48 +++++++++++++++------------
 tests/warehouse/test_sample_sql.py    | 27 +++++++++++++++
 2 files changed, 53 insertions(+), 22 deletions(-)

diff --git a/tests/cli/test_e2e_snowflake_smoke.py b/tests/cli/test_e2e_snowflake_smoke.py
index ecff18d0..1a08a36d 100644
--- a/tests/cli/test_e2e_snowflake_smoke.py
+++ b/tests/cli/test_e2e_snowflake_smoke.py
@@ -10,19 +10,21 @@
 
 ``safety: schema-only`` + ``prune.scope: full`` is MANDATORY here, not a
 tuning choice — it is the only configuration that works against live
-Snowflake today. Both sample strategies are non-functional on a real
-warehouse: ``materialised`` issues a ``CREATE TEMPORARY TABLE`` colocated
-with the source (rejected by the read-only ``SNOWFLAKE_SAMPLE_DATA`` share),
-and BOTH ``oneshot`` and ``materialised`` emit ``MOD(ABS(HASH(*)), n)`` in
-``WHERE`` / ``ORDER BY``, which Snowflake rejects (``HASH(*)`` is valid only
-in the ``SELECT`` projection); ``oneshot`` additionally routes the sample
-row-count through a BigQuery-only ``_get_client`` seam. ``safety:
-aggregate-only`` would invoke the deferred ``column_stats``. ``scope: full``
-runs each test against the full (tiny) ``TPCH_SF1.CUSTOMER`` table directly —
-no sampling, no temp table — and still drives the full draft -> prune ->
-grade -> diff pipeline. The sample-mode bugs are tracked as separate
-#121/#122 follow-ups; the per-run ``signalforge.yml`` (written into
-``tmp_path`` below) pins ``prune.scope: full`` for exactly this reason.
+Snowflake today against THIS dataset, for distinct reasons: ``materialised``
+issues a ``CREATE TEMPORARY TABLE`` colocated with the source, which the
+read-only ``SNOWFLAKE_SAMPLE_DATA`` share rejects; ``oneshot`` routes the
+sample row-count through a BigQuery-only ``_get_client`` seam (tracked as
+``bd_1-scaffolding-tft``). The earlier ``MOD(ABS(HASH(*)), n)``-in-``WHERE`` /
+``ORDER BY`` shape bug (``HASH(*)`` is valid only in the ``SELECT``
+projection) was FIXED in #139 — every Snowflake sample path now emits the
+projection-subquery ``SELECT * EXCLUDE`` form — so it is no longer a reason to
+avoid sampling. ``safety: aggregate-only`` would invoke the deferred
+``column_stats``. ``scope: full`` runs each test against the full (tiny)
+``TPCH_SF1.CUSTOMER`` table directly — no sampling, no temp table — and still
+drives the full draft -> prune -> grade -> diff pipeline. The per-run
+``signalforge.yml`` (written into ``tmp_path`` below) pins ``prune.scope:
+full`` because the shared sample dataset is read-only (materialised) and
+oneshot's row-count seam is still open (``bd_1-scaffolding-tft``).
 
 Gated by FIVE prerequisites — this is a FULL-STACK test (warehouse + LLM):
 
@@ -201,15 +203,17 @@ def test_e2e_signalforge_generate_against_tpch_sf1(
 
     # The seed ships no ``signalforge.yml``; write one into the per-run copy
     # pinning ``prune.scope: full``. ``scope: full`` is REQUIRED on Snowflake
-    # today: both sample strategies are non-functional against a live warehouse
-    # (oneshot needs the not-yet-built ``WarehouseAdapter.get_table_metadata``
-    # seam — engine.py routes the sample row-count through a BigQuery-only
-    # ``_get_client``; materialised emits ``MOD(ABS(HASH(*)), n)`` in WHERE /
-    # ORDER BY, which Snowflake rejects — ``HASH(*)`` is only valid in the
-    # SELECT projection). Tracked as separate #121/#122 bug beads. ``scope:
-    # full`` runs each test against the full source table (TPCH_SF1.CUSTOMER is
-    # small) and still exercises the full draft → prune → grade → diff path +
-    # the always-passes drop this test certifies.
+    # today against THIS dataset: both sample strategies are non-functional for
+    # distinct reasons (oneshot needs the not-yet-built
+    # ``WarehouseAdapter.get_table_metadata`` seam — engine.py routes the sample
+    # row-count through a BigQuery-only ``_get_client``, tracked as
+    # ``bd_1-scaffolding-tft``; materialised's ``CREATE TEMPORARY TABLE`` is
+    # rejected by the read-only ``SNOWFLAKE_SAMPLE_DATA`` share). The earlier
+    # ``MOD(ABS(HASH(*)), n)``-in-WHERE/ORDER-BY shape bug was FIXED in #139
+    # (projection-subquery ``SELECT * EXCLUDE`` form), so it is no longer a
+    # blocker. ``scope: full`` runs each test against the full source table
+    # (TPCH_SF1.CUSTOMER is small) and still exercises the full draft → prune →
+    # grade → diff path + the always-passes drop this test certifies.
     #
     # ``safety: schema-only`` is REQUIRED on Snowflake: ``aggregate-only``
     # invokes ``adapter.column_stats``, which SnowflakeAdapter leaves as a
diff --git a/tests/warehouse/test_sample_sql.py b/tests/warehouse/test_sample_sql.py
index befa4e73..dd82c1ab 100644
--- a/tests/warehouse/test_sample_sql.py
+++ b/tests/warehouse/test_sample_sql.py
@@ -131,3 +131,30 @@ def test_branch_switches_on_flag_not_dialect_name() -> None:
     assert sql.startswith("SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT t.*, ")
     assert "MOD(_sf_sample_hash, 3) < 1" in sql
     assert "ORDER BY _sf_sample_hash" in sql
+
+    # Symmetric direction: a synthetic dialect with a likewise-unrecognised
+    # ``name`` but ``sample_hash_in_projection=False`` renders the INLINE form,
+    # never the projection one — defeating a ``dialect.name``-based dispatch in
+    # both directions, not just the projection arm.
+    madeup_inline = Dialect(
+        name="madeup",
+        supports_tablesample=True,
+        supports_qualify=False,
+        quote_char='"',
+        identifier_case="preserve",
+        sample_row_hash_expr="ABS(HASH(*))",
+        sample_hash_in_projection=False,
+    )
+    inline_sql = render_sample_select(
+        '"X"',
+        dialect=madeup_inline,
+        sample_bucket=3,
+        sample_size=9,
+        order_by_hash=True,
+    )
+    assert (
+        inline_sql
+        == 'SELECT * FROM "X" AS t WHERE MOD(ABS(HASH(*)), 3) < 1 ORDER BY ABS(HASH(*)) LIMIT 9'
+    )
+    assert "EXCLUDE" not in inline_sql
+    assert "_sf_sample_hash" not in inline_sql

From 5b4be14c3867122f7bb5176db25c379cba67216f Mon Sep 17 00:00:00 2001
From: wjduenow <wjduenow@gmail.com>
Date: Wed, 27 May 2026 10:29:10 -0700
Subject: [PATCH 08/10] =?UTF-8?q?bd=5F1-scaffolding-kay.6:=20#139=20Patter?=
 =?UTF-8?q?ns=20&=20Memory=20=E2=80=94=20finalise=20plan=20+=20capture=20d?=
 =?UTF-8?q?ialect-shape=20lesson?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- prune-engine.md § "Adding a new vendor dialect": capture the generalised
  #139 lesson (a single inline SQL-fragment string can't express a clause-
  POSITION constraint; when the SQL *shape* differs, add a structural Dialect
  field + shared renderer; sqlglot parses but cannot certify warehouse
  acceptance, so the live-gated test is the real merge gate)
- plans/super/139: add Outcome note (6 stories landed; QG 4 passes fixed
  E501 + stale e2e docstring; offline green 2394 passed / pyright 0 /
  -m snowflake 33 passed,4 live-skipped; DEC-006 live cert PENDING/maintainer)
- verified US-004's rule/doc graduation already complete + coherent (no
  re-edit needed there)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .claude/rules/prune-engine.md             |  2 ++
 plans/super/139-snowflake-sample-shape.md | 17 +++++++++++++++++
 2 files changed, 19 insertions(+)

diff --git a/.claude/rules/prune-engine.md b/.claude/rules/prune-engine.md
index fa087760..812c0ce5 100644
--- a/.claude/rules/prune-engine.md
+++ b/.claude/rules/prune-engine.md
@@ -72,6 +72,8 @@ Issue #121 made the compiler emit valid **Snowflake** SQL by extending `Dialect`
 
 **Adding a new vendor dialect:** extend the `Dialect` value object with a declarative field and read it in the compiler — never `if dialect.name == …`. Keep BigQuery-shaped defaults on new fields so existing construction sites + the 11 BigQuery snapshot fixtures stay byte-identical (the load-bearing regression gate). Validate the emitted SQL through a real parser (`sqlglot`) or executor (`fakesnow`/live), gated behind a maintainer-only marker — snapshot equality alone certifies shape, not validity.
 
+**A single inline SQL-fragment STRING can't express a clause-POSITION constraint (issue #139, generalising #121).** `sample_row_hash_expr` was a string, but Snowflake's `HASH(*)` is projection-only — legal in `SELECT`, rejected (`002079`) in `WHERE`/`ORDER BY`. When a vendor needs a different SQL *shape* (not just a different expression in the same slot), add a **structural** `Dialect` field (here `sample_hash_in_projection: bool`) + a **shared renderer** (`warehouse/_sample_sql.render_sample_select`) so every emitter agrees on the shape — don't try to encode the shape inside a richer template string. And note the cert gap: `sqlglot` *parses* `SELECT * EXCLUDE (col) … ORDER BY col` happily but cannot certify Snowflake *accepts* it, so a shape this subtle is only truly validated by the live-gated (`@pytest.mark.snowflake` + `SF_RUN_SNOWFLAKE=1`) test — that live run is the real merge gate, not the snapshot/sqlglot tier.
+
 NULL-exclusion pattern matches dbt-core verbatim (DEC-023): `unique` adds `WHERE col IS NOT NULL`; `accepted_values` adds `WHERE col IS NOT NULL AND col NOT IN (...)`; `relationships` adds child-side `WHERE child.col IS NOT NULL`. Snapshot fixtures pin the exact SQL bytes.
 
 ## Total-budget semantics (DEC-011)
diff --git a/plans/super/139-snowflake-sample-shape.md b/plans/super/139-snowflake-sample-shape.md
index 58bbb832..9feefd0c 100644
--- a/plans/super/139-snowflake-sample-shape.md
+++ b/plans/super/139-snowflake-sample-shape.md
@@ -236,3 +236,20 @@ The `_sf_sample_hash` alias is emitted **unquoted**; Snowflake folds it to `_SF_
   - `bd_1-scaffolding-kay.5` — Quality Gate *(blocked on .4)*
   - `bd_1-scaffolding-kay.6` — Patterns & Memory *(blocked on .5)*
 - **Worktree:** `../worktrees/SignalForge/139-snowflake-sample-shape`
+
+---
+
+## Outcome (2026-05-27)
+
+All 6 stories landed on `feature/139-snowflake-sample-shape`:
+
+- **US-001 … US-003** — `Dialect.sample_hash_in_projection` / `sample_hash_alias` + the shared `warehouse/_sample_sql.render_sample_select` helper; the prune compiler sample CTE and both `SnowflakeAdapter` sample methods (`sample_rows`, `materialise_sample`) wired to it; Snowflake `*_sample.sql` snapshots regenerated to the projection-subquery form; BigQuery compiled-SQL fixtures verified byte-unchanged.
+- **US-004** — live materialised prune e2e flipped to `scope="sample"` + the 5-surface graduation (DEC-005): `warehouse-adapters.md` (`Dialect` fields + live-harness note marking `bd_1-scaffolding-cdp` **FIXED**), `prune-engine.md` (compiler-dialect field list + `render_sample_select` delegation), `docs/warehouse-adapter-ops.md` (Known limitations now reflect HASH(*) fixed, materialised sample-mode works, oneshot's row-count seam `bd_1-scaffolding-tft` still open).
+- **US-005 (Quality Gate)** — code reviewer ran **4 passes**; real findings fixed, notably a self-introduced lint **E501** and a **stale `test_e2e_snowflake_smoke.py` docstring** that still claimed materialised sampling emits the buggy `HASH(*)`-in-`WHERE`/`ORDER BY` form (the shape bug is fixed for *both* strategies; that test's remaining `scope=full` reason is the read-only `SNOWFLAKE_SAMPLE_DATA` share + oneshot's open row-count seam, not the shape bug). The name-agnostic helper test was also hardened with a symmetric inline-direction assertion.
+- **US-006 (Patterns & Memory, this story)** — verified the US-004 rule/doc graduation is coherent and complete (no re-edit needed there); added the generalised engineering lesson to `prune-engine.md` § "Adding a new vendor dialect" (a single inline SQL-fragment *string* can't express a clause-POSITION constraint — when the SQL *shape* differs, add a structural `Dialect` field + shared renderer; sqlglot parses but cannot certify Snowflake acceptance, so the live-gated test is the real merge gate).
+
+**Offline validation green:** `2394 passed`, `pyright` 0 errors, offline `-m snowflake` `33 passed / 4 live-skipped`, `ruff check`/`ruff format --check` clean.
+
+**Live Snowflake certification (DEC-006) is PENDING — maintainer-run.** `uv run pytest -m snowflake --no-cov` with `SF_RUN_SNOWFLAKE=1` + conn vars + a writable `SNOWFLAKE_DATABASE`/`SCHEMA` is the **merge gate**: it certifies the projection-subquery shape actually executes on live Snowflake and resolves DEC-004's open question — whether the **primary** form (`ORDER BY <alias>` of an `EXCLUDE`-d column) is accepted, or the **fallback** (drop the outer `ORDER BY`) must be pinned in the fixtures. The offline tiers (snapshots + sqlglot) certify shape only; only the live run certifies Snowflake acceptance.
+
+The DECs above are unchanged.

From 09ac8ccdbadea5ebc57a7cf0ba38afed34631810 Mon Sep 17 00:00:00 2001
From: wjduenow <wjduenow@gmail.com>
Date: Wed, 27 May 2026 10:51:49 -0700
Subject: [PATCH 09/10] =?UTF-8?q?#139:=20record=20live=20Snowflake=20certi?=
 =?UTF-8?q?fication=20(DEC-006=20=E2=9C=85,=20DEC-004=20primary=20form=20c?=
 =?UTF-8?q?onfirmed)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

test_prune_drops_always_passes_not_null_live_materialised_sample passed
against a real Snowflake warehouse (1 passed in 14.78s) — the materialised
scope=sample path executes the SELECT * EXCLUDE projection-subquery CTAS and
drops the always-passes test. Snowflake accepts ORDER BY of an EXCLUDE-d
column, so the primary form stands (no DEC-004 fallback needed).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plans/super/139-snowflake-sample-shape.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plans/super/139-snowflake-sample-shape.md b/plans/super/139-snowflake-sample-shape.md
index 9feefd0c..22a73700 100644
--- a/plans/super/139-snowflake-sample-shape.md
+++ b/plans/super/139-snowflake-sample-shape.md
@@ -250,6 +250,6 @@ All 6 stories landed on `feature/139-snowflake-sample-shape`:
 
 **Offline validation green:** `2394 passed`, `pyright` 0 errors, offline `-m snowflake` `33 passed / 4 live-skipped`, `ruff check`/`ruff format --check` clean.
 
-**Live Snowflake certification (DEC-006) is PENDING — maintainer-run.** `uv run pytest -m snowflake --no-cov` with `SF_RUN_SNOWFLAKE=1` + conn vars + a writable `SNOWFLAKE_DATABASE`/`SCHEMA` is the **merge gate**: it certifies the projection-subquery shape actually executes on live Snowflake and resolves DEC-004's open question — whether the **primary** form (`ORDER BY <alias>` of an `EXCLUDE`-d column) is accepted, or the **fallback** (drop the outer `ORDER BY`) must be pinned in the fixtures. The offline tiers (snapshots + sqlglot) certify shape only; only the live run certifies Snowflake acceptance.
+**Live Snowflake certification (DEC-006) — CERTIFIED 2026-05-27 ✅.** `test_snowflake_prune_live.py::test_prune_drops_always_passes_not_null_live_materialised_sample` ran green against a real Snowflake warehouse (password auth, writable schema; `SF_RUN_SNOWFLAKE=1`, `1 passed in 14.78s`): the `scope="sample"` + `materialised` path executed the `CREATE TEMPORARY TABLE … AS SELECT * EXCLUDE (_sf_sample_hash) …` CTAS and the always-passes `not_null` was dropped. This **resolves DEC-004 in favour of the PRIMARY form** — Snowflake accepts `ORDER BY _sf_sample_hash` even though that column is `SELECT * EXCLUDE`-d, so the documented fallback (drop the outer `ORDER BY`) is **not** needed and the shipped fixtures stand. The offline tiers (snapshots + sqlglot) certified shape; this live run certified Snowflake acceptance — the merge gate is satisfied.
 
 The DECs above are unchanged.

From 2bdc6f4a182206d67e56d2a7b0c2bec52f968089 Mon Sep 17 00:00:00 2001
From: wjduenow <wjduenow@gmail.com>
Date: Wed, 27 May 2026 11:03:36 -0700
Subject: [PATCH 10/10] =?UTF-8?q?#139:=20address=20PR=20review=20=E2=80=94?=
 =?UTF-8?q?=20live-cert=20docstring=20+=20markdownlint=20fixes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- test_snowflake_prune_live.py: DEC-004 note now records the live cert
  RESOLVED the ORDER-BY-of-EXCLUDE-d-column question in favour of the
  primary form (Copilot: stale "unresolved decision point" docstring)
- docs/warehouse-adapter-ops.md: reword so the line no longer starts with
  "#139" (CodeRabbit/markdownlint MD heading false-trigger)
- plans/super/139: add `sql` language tags to two fenced blocks (CodeRabbit)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/warehouse-adapter-ops.md                |  4 ++--
 plans/super/139-snowflake-sample-shape.md    |  4 ++--
 tests/warehouse/test_snowflake_prune_live.py | 22 ++++++++++----------
 3 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/docs/warehouse-adapter-ops.md b/docs/warehouse-adapter-ops.md
index 2d83792c..10de91d4 100644
--- a/docs/warehouse-adapter-ops.md
+++ b/docs/warehouse-adapter-ops.md
@@ -612,8 +612,8 @@ colocated with the source (each component fold-to-UPPER then quoted, per
 **Cost-relevant consequence:** the source table must be **writable** —
 materialised sampling against a read-only shared database (e.g.
 `SNOWFLAKE_SAMPLE_DATA`) fails the CTAS. The materialised-sample CTAS uses the
-#139 projection-subquery shape (`SELECT * EXCLUDE (_sf_sample_hash) FROM (SELECT
-t.*, ABS(HASH(*)) AS _sf_sample_hash …)`), so `prune.scope: sample` +
+projection-subquery shape from #139 (`SELECT * EXCLUDE (_sf_sample_hash) FROM
+(SELECT t.*, ABS(HASH(*)) AS _sf_sample_hash …)`), so `prune.scope: sample` +
 `prune.sample_strategy: materialised` works on live Snowflake (against a
 writable source). The `oneshot` strategy is still blocked at a separate engine
 seam — see "Known limitations" below.
diff --git a/plans/super/139-snowflake-sample-shape.md b/plans/super/139-snowflake-sample-shape.md
index 22a73700..c8042bdb 100644
--- a/plans/super/139-snowflake-sample-shape.md
+++ b/plans/super/139-snowflake-sample-shape.md
@@ -118,11 +118,11 @@ def render_sample_select(
 Reads `dialect.sample_row_hash_expr`, `dialect.sample_hash_in_projection`, `dialect.sample_hash_alias`. Two branches, switched on the **boolean** (never `dialect.name`):
 
 - **Inline (BigQuery, `sample_hash_in_projection=False`)** — byte-identical to today's compiler CTE body / would-be adapter form:
-  ```
+  ```sql
   SELECT * FROM <table_sql> AS t WHERE MOD(<hash_expr>, <bucket>) < 1[ AND <extra_where>][ ORDER BY <hash_expr>] LIMIT <n>
   ```
 - **Projection-subquery (Snowflake, `sample_hash_in_projection=True`)**:
-  ```
+  ```sql
   SELECT * EXCLUDE (<alias>) FROM (SELECT t.*, <hash_expr> AS <alias> FROM <table_sql> AS t) WHERE MOD(<alias>, <bucket>) < 1[ AND <extra_where>][ ORDER BY <alias>] LIMIT <n>
   ```
 
diff --git a/tests/warehouse/test_snowflake_prune_live.py b/tests/warehouse/test_snowflake_prune_live.py
index ff8b50a2..0e22d6b1 100644
--- a/tests/warehouse/test_snowflake_prune_live.py
+++ b/tests/warehouse/test_snowflake_prune_live.py
@@ -30,17 +30,17 @@
 end against a live warehouse and asserts the v0.1 differentiator (Architectural
 Commitment #1: an always-pass test is dropped, not shipped).
 
-**DEC-004 primary/fallback note.** The emitted SQL uses the PRIMARY form:
-``ORDER BY _sf_sample_hash`` at the outer level where ``_sf_sample_hash`` is
-``SELECT * EXCLUDE``-d from the output projection. There is a genuine open
-question — resolvable only by this live run — whether Snowflake accepts
-``ORDER BY <col>`` when that column is ``SELECT * EXCLUDE``-d. If live Snowflake
-rejects ``ORDER BY`` of an EXCLUDE-d column, the fallback (DEC-004) is to drop
-the outer ``ORDER BY`` in ``render_sample_select`` + the fixtures; the
-deterministic ``MOD`` filter alone defines sample membership (matches the
-prune compiler CTE, which already emits no ``ORDER BY``). The fallback is NOT
-implemented here — the code ships the primary form; this docstring records the
-decision point the maintainer's live run resolves.
+**DEC-004 — RESOLVED in favour of the PRIMARY form (live-certified 2026-05-27).**
+The emitted SQL uses the primary form: ``ORDER BY _sf_sample_hash`` at the outer
+level where ``_sf_sample_hash`` is ``SELECT * EXCLUDE``-d from the output
+projection. The open question — whether Snowflake accepts ``ORDER BY <col>`` when
+that column is ``SELECT * EXCLUDE``-d — was answered by this test's live run:
+Snowflake **accepts** it, so the primary form ships and the shipped fixtures
+stand. The documented fallback (drop the outer ``ORDER BY`` in
+``render_sample_select`` + the fixtures, leaning on the deterministic ``MOD``
+filter alone, matching the prune compiler CTE which emits no ``ORDER BY``) was
+therefore **not** needed; it remains on record only as the contingency had live
+rejected the primary form.
 
 NO LLM, NO ``generate`` CLI: this test builds the :class:`Model`,
 :class:`Manifest`, the :class:`CandidateSchema` (one