From 4b0f349709a922155b77ded88a38d8133762e1d3 Mon Sep 17 00:00:00 2001
From: Jimmy Angelakos <jimmy@pgedge.com>
Date: Fri, 25 Sep 2026 18:27:13 +0100
Subject: [PATCH 1/5] build: compute TIMESTAMPTZ partition transforms in UTC

---
 DUCKDB_1.5_PATCHED.md                         | 44 ++++++++++++-----
 DUCKDB_1.5_UNPATCHED.md                       | 16 ++++++-
 docker/Dockerfile.duckdb15-base               | 11 ++++-
 ...eberg-timestamptz-utc-transforms-v15.patch | 48 +++++++++++++++++++
 .../build-extensions.sh                       |  5 +-
 .../coldfront-duckdb-extensions/common.sh     |  2 +-
 6 files changed, 108 insertions(+), 18 deletions(-)
 create mode 100644 docker/iceberg-timestamptz-utc-transforms-v15.patch

diff --git a/DUCKDB_1.5_PATCHED.md b/DUCKDB_1.5_PATCHED.md
index c293c32..73f26d3 100644
--- a/DUCKDB_1.5_PATCHED.md
+++ b/DUCKDB_1.5_PATCHED.md
@@ -12,14 +12,15 @@ and verified*. The cold-tier compactor's own story lives in
 > `abfss://` Iceberg **reads** (`read_avro` on `abfss`); the base then layers
 > ColdFront's patches on top.
 
-## The two patch families the base carries
+## The patch families the base carries
 
 | Patch family | Files | Purpose | Without it |
 |---|---|---|---|
 | **Bakery-aware commit-refresh** | `docker/iceberg-bakery-aware-commit-refresh-v15.patch` | makes the async parquet-upload ordering safe → the **no-409** guarantee for concurrent cold writers, at contended-upload throughput | cold writes still work and still never 409 — they fall back to serialized (claim-first) uploads (see [DUCKDB_1.5_UNPATCHED.md](DUCKDB_1.5_UNPATCHED.md)) |
 | **Strict-reader interop** (upstreamable) | `docker/iceberg-manifest-list-format-version-v15.patch`, `docker/iceberg-data-file-format-v15.patch` | make the manifests duckdb-iceberg *writes* readable by strict Apache readers (apache/iceberg-go) | the cold-tier **compactor cannot read the table** - see [docs/compaction.md](docs/compaction.md). pg_duckdb's own reads/writes are unaffected. |
+| **TIMESTAMPTZ transforms in UTC** (port of upstream d3c3348271) | `docker/iceberg-timestamptz-utc-transforms-v15.patch` | year/month/day/hour of a TIMESTAMPTZ partition column are computed on the UTC instant, as the Iceberg spec, duckdb-iceberg's own pruning and iceberg-go take them | a session outside UTC files rows within the zone offset of a boundary in the neighbouring partition, and a UTC-bounded read on the column **prunes them away** |
 
-All three patches apply cleanly to a **pristine** `duckdb-iceberg` @ `5edc45f0`
+All four patches apply cleanly to a **pristine** `duckdb-iceberg` @ `5edc45f0`
 (branch `v1.5-variegata`); `docker/Dockerfile.duckdb15-base` `git apply --check`s
 each before applying, failing the build loudly on patch rot.
 
@@ -144,7 +145,26 @@ The compactor itself (usage, backends, maintenance steps) is documented in
 [docs/compaction.md](docs/compaction.md). The interop patches are independent of
 the bakery patch.
 
-## 4. NOT shipped — no `Commit(ClientContext&)` rewrite
+## 4. TIMESTAMPTZ partition transforms in UTC (one patch, a port)
+
+`iceberg-timestamptz-utc-transforms-v15.patch` ports upstream duckdb-iceberg
+d3c3348271 (PR #1361, on `main` only: neither `v1.5-variegata` up to `890b78a9`
+nor the duckdb-iceberg that DuckDB v1.5.5 ships, `45163a28`, carries it). At the
+pinned ref a partitioned write computes `year/month/day/hour` of a TIMESTAMPTZ
+column as `date_diff` on the TIMESTAMPTZ itself, which ICU evaluates in the
+session's time zone, and pg_duckdb sets that zone from PostgreSQL's `TimeZone`.
+The Iceberg spec, duckdb-iceberg's own read-side pruning
+(`iceberg_transform.hpp`) and iceberg-go all take the UTC instant, so from a
+session outside UTC a row within the zone offset of a boundary lands in the
+neighbouring partition and a UTC-bounded predicate on the column prunes it
+away (reproduced: from `America/New_York`, 2026-04-01 02:00 UTC was filed under
+March and `ts >= '2026-04-01 00:00+00'` did not return it). The patch binds a
+TIMESTAMPTZ source as TIMESTAMP through DuckDB's default cast, which
+reinterprets the stored UTC microseconds without ICU, before `date_diff`.
+`ci/journey.sh` TC-186 fails without it. Dropped when `ICEBERG_REF` reaches a
+ref that carries the fix.
+
+## 5. NOT shipped — no `Commit(ClientContext&)` rewrite
 
 v1.5's `IcebergTransaction::Commit` already copies the caller's `ClientConfig`
 into its commit-time connection, so `s3_access_key_id` etc. are available; a
@@ -157,19 +177,19 @@ patches only.
 
 ---
 
-## 5. Version pins (do not drift)
+## 6. Version pins (do not drift)
 
 | Component | Pin | Notes |
 |---|---|---|
 | pg_duckdb | **merged PR #1025** (`c04e6a2`) | no released tag carries 1.5.x; `git checkout c04e6a2`. Its duckdb submodule is the v1.5.4 tag (`08e34c4`). |
 | DuckDB | **v1.5.4 tag** (`08e34c4`) | pinned by pg_duckdb @ `c04e6a2`; the iceberg build re-pins ITS duckdb submodule to the same tag so the extension ABI matches the engine. The `duckdb.*` GUCs + PRE_COMMIT iceberg-commit deferral ColdFront relies on are unchanged. |
-| duckdb-iceberg | **`v1.5-variegata` @ `5edc45f0`** | extension code the three patches target — kept fixed, so the patches apply unchanged. The build re-pins its duckdb submodule to the v1.5.4 tag (the branch tracks duckdb `main`, which drifts off the release; verified: `5edc45f0` compiles clean against v1.5.4). Transaction code lives in `src/catalog/rest/transaction/`. |
+| duckdb-iceberg | **`v1.5-variegata` @ `5edc45f0`** | extension code the four patches target — kept fixed, so the patches apply unchanged. The build re-pins its duckdb submodule to the v1.5.4 tag (the branch tracks duckdb `main`, which drifts off the release; verified: `5edc45f0` compiles clean against v1.5.4). Transaction code lives in `src/catalog/rest/transaction/`. |
 | avro | **`7f423d69`** | the pin `v1.5-variegata` uses. |
 | azure | **`v1.5-variegata` @ `563589b2`** | the ABI-matched sibling of iceberg's branch. **NOT `main`** — azure `main` collides at link (`multiple definition of duckdb::FileFlags::FILE_FLAGS_NULL_IF_NOT_EXISTS`). |
 | postgres_scanner | duckdb-postgres **`6b2b12ca`** | the `postgres` ext; built bundled (ABI-matched, stamped v1.5.4), **shipped** in the image (never downloaded). Its vcpkg `libpq` build needs **flex** + **bison**. |
 | libcurl | **build 8.12.0** (≥ 7.77) | **REQUIRED** — DuckDB 1.5.4 httpfs uses `CURLSSLOPT_AUTO_CLIENT_CERT` (≥ 7.77); the pgEdge base ships 7.76.1. 8.12.0 fixes CVE-2025-0665 (the 8.11.1 resolver SIGABRT); runtime still pins httplib regardless. |
 
-## 6. Build — `docker/Dockerfile.duckdb15-base`
+## 7. Build — `docker/Dockerfile.duckdb15-base`
 
 The base build *is* the recipe; read it as the source of truth. Its non-obvious
 requirements (each a real build failure if missing):
@@ -193,7 +213,7 @@ requirements (each a real build failure if missing):
 Cold base build is ~30–60 min (vcpkg compiles the Azure SDK + libpq from source);
 incremental rebuilds after a patch change recompile only the iceberg extension.
 
-## 7. Install / GUCs / image wiring (base/app split)
+## 8. Install / GUCs / image wiring (base/app split)
 
 The expensive, **stable** compiles live in the **base** image, published to
 `ghcr.io/pgedge/coldfront-duckdb-base:pg{16,17,18}`. The thin **app** image layers
@@ -235,7 +255,7 @@ Building the app locally pulls the published base
 `ghcr.io/pgedge/coldfront-duckdb-base:pg<major>`, or uses a locally-built
 base tagged the same.
 
-## 8. v1.5 architecture notes (verified against source)
+## 9. v1.5 architecture notes (verified against source)
 
 - `IcebergTransaction::Commit()` opens a fresh `temp_con` but **copies the
   caller's config** (settings like `s3_access_key_id`, not the secret catalog).
@@ -251,7 +271,7 @@ base tagged the same.
   works by refreshing metadata at commit time rather than re-stamping fields,
   and why its no-409 correctness is proven by the 3-node bench, not assumed.
 
-## 9. Azure secret (`TYPE azure`)
+## 10. Azure secret (`TYPE azure`)
 
 Verified against duckdb-azure `src/azure_secret.cpp` + the built extension. There
 is **no `ACCOUNT_KEY` parameter** — a shared-key account key is supplied only in
@@ -273,7 +293,7 @@ One secret serves both `abfss://` (ADLS Gen2 / dfs) and `az://` (blob).
 live `CREATE PERSISTENT SECRET` is exercised only on the 1.5.x image, not in
 pg_regress — a green regress run does **not** prove azure I/O).
 
-## 10. CI coverage — why azure is creds-gated, not hermetic
+## 11. CI coverage — why azure is creds-gated, not hermetic
 
 `ci/matrix.sh` runs the same storage-agnostic journey under s3 (hermetic,
 SeaweedFS, always) and under azure (creds-gated) across the full grid: both
@@ -286,7 +306,7 @@ PENDING — never silently skipped); the storage-divergent code (secret renderin
 config selection) is covered with no creds by the unit + pg_regress layer on
 every PR.
 
-## 11. Cutover vs cold-write serialization
+## 12. Cutover vs cold-write serialization
 
 `coldfront.cutover_archive` acquires the **same bakery** the cold-write path
 takes (same `v_armed` gate, same `coldfront_iceberg:<ref>` key) on its
@@ -306,7 +326,7 @@ inversion forms, the **cutover** yields first (100 ms), frees the bakery, the
 writer commits, and the harness retries the cutover; the writer is never the
 victim.
 
-## 12. Reverting to UNPATCHED
+## 13. Reverting to UNPATCHED
 
 No code change — flip to stock by unsetting `coldfront.iceberg_bakery_patch`
 (the gate goes false → claim-first even if the async flag stays on). To run a
diff --git a/DUCKDB_1.5_UNPATCHED.md b/DUCKDB_1.5_UNPATCHED.md
index e063b90..f67b492 100644
--- a/DUCKDB_1.5_UNPATCHED.md
+++ b/DUCKDB_1.5_UNPATCHED.md
@@ -15,11 +15,12 @@ It is still a locally-built (unsigned) extension; there is no signed upstream
 ## The build delta (vs the patched base)
 
 In `docker/Dockerfile.duckdb15-base`, drop the `COPY` + `git apply --check` +
-`git apply` of all three patches:
+`git apply` of all four patches:
 
 - `iceberg-bakery-aware-commit-refresh-v15.patch`
 - `iceberg-manifest-list-format-version-v15.patch`
 - `iceberg-data-file-format-v15.patch`
+- `iceberg-timestamptz-utc-transforms-v15.patch`
 
 Everything else — libcurl, vcpkg deps, the pins, the extension config, the
 runtime stage — is identical. In `docker/entrypoint.sh`, leave
@@ -67,6 +68,19 @@ version/content/format from table metadata, never from the Avro keys iceberg-go
 checks. So an unpatched cold tier reads and writes fine through PostgreSQL; it
 just can't be compacted by the go-native compactor.
 
+## Consequence 3: partitioned cold tables are only correct from UTC sessions
+
+Every tiered cold table, and a decoupled one created with `p_partition_cols`,
+is partitioned by `month(ts)` or `day(ts)`. Stock duckdb-iceberg at the pinned
+ref computes that transform with `date_diff` on the TIMESTAMPTZ itself, which
+ICU evaluates in the session's time zone (pg_duckdb sets it from PostgreSQL's
+`TimeZone`), while its own read-side pruning and iceberg-go take the UTC
+instant. From a session outside UTC, a row within the zone offset of a month
+boundary is filed in the neighbouring partition, and a UTC month-bounded read
+prunes it away. The fourth patch, a port of upstream d3c3348271, binds the
+column as the UTC TIMESTAMP it holds before the transform. Unpatched, every
+cold writer, the archiver included, has to run with `TimeZone = 'UTC'`.
+
 ## When unpatched is acceptable
 
 - You don't run the compactor (low cold-write volume, or you compact externally
diff --git a/docker/Dockerfile.duckdb15-base b/docker/Dockerfile.duckdb15-base
index b5a0b4c..8be89a7 100644
--- a/docker/Dockerfile.duckdb15-base
+++ b/docker/Dockerfile.duckdb15-base
@@ -105,7 +105,7 @@ RUN dnf install -y --setopt=install_weak_deps=False \
         flex bison \
     && dnf clean all
 WORKDIR /build
-# ICEBERG_REF is the extension code the three patches target (kept fixed so they
+# ICEBERG_REF is the extension code the four patches target (kept fixed so they
 # apply unchanged). Its duckdb submodule tracks duckdb main, which drifts off the
 # release, so after init we pin that submodule to the v1.5.4 TAG — the same engine
 # pg_duckdb links — and build the extension against it.
@@ -140,13 +140,20 @@ COPY docker/iceberg-manifest-list-format-version-v15.patch /tmp/iceberg-mlist-fm
 # (iceberg-go's compaction scan) match it case-sensitively. Inert to pg_duckdb
 # reads (reader stores verbatim; ducklake lowercases). See the patch header.
 COPY docker/iceberg-data-file-format-v15.patch /tmp/iceberg-fileformat-v15.patch
+# TIMESTAMPTZ transform patch, a port of upstream d3c3348271 (on main only):
+# year/month/day/hour of a TIMESTAMPTZ partition column are computed on the UTC
+# instant, as the Iceberg spec, duckdb-iceberg's own pruning and iceberg-go take
+# them, not in the session's time zone. See the patch header.
+COPY docker/iceberg-timestamptz-utc-transforms-v15.patch /tmp/iceberg-tstz-utc-v15.patch
 RUN cd /build/duckdb-iceberg \
  && git apply --check /tmp/iceberg-bakery-v15.patch \
  && git apply        /tmp/iceberg-bakery-v15.patch \
  && git apply --check /tmp/iceberg-mlist-fmtver-v15.patch \
  && git apply        /tmp/iceberg-mlist-fmtver-v15.patch \
  && git apply --check /tmp/iceberg-fileformat-v15.patch \
- && git apply        /tmp/iceberg-fileformat-v15.patch
+ && git apply        /tmp/iceberg-fileformat-v15.patch \
+ && git apply --check /tmp/iceberg-tstz-utc-v15.patch \
+ && git apply        /tmp/iceberg-tstz-utc-v15.patch
 # vcpkg triplet is derived from the build arch (uname -m): x86_64→x64-linux,
 # aarch64→arm64-linux. Host and target match here (the stage runs on the target
 # arch, native or emulated), so HOST and TARGET triplets are the same value.
diff --git a/docker/iceberg-timestamptz-utc-transforms-v15.patch b/docker/iceberg-timestamptz-utc-transforms-v15.patch
new file mode 100644
index 0000000..f2eb660
--- /dev/null
+++ b/docker/iceberg-timestamptz-utc-transforms-v15.patch
@@ -0,0 +1,48 @@
+# iceberg-timestamptz-utc-transforms-v15.patch
+#
+# Applies to: duckdb-iceberg @ 5edc45f0 (branch v1.5-variegata), DuckDB v1.5.x.
+#
+# A port of upstream duckdb-iceberg d3c3348271 ("fix: use UTC semantics for Iceberg
+# TIMESTAMPTZ transforms", PR #1361), which is on main only: v1.5-variegata does not
+# carry it (checked up to 890b78a9), nor does the duckdb-iceberg that DuckDB v1.5.5
+# ships (45163a28).
+#
+# Problem: a partitioned write computes year/month/day/hour of a TIMESTAMPTZ column
+# as date_diff on the TIMESTAMPTZ itself, which ICU counts in the session's time
+# zone, and pg_duckdb sets that zone from PostgreSQL's TimeZone. The Iceberg spec,
+# duckdb-iceberg's own partition pruning (iceberg_transform.hpp) and iceberg-go all
+# take the UTC instant. So from a session outside UTC, a row within the zone offset
+# of a boundary is filed in the neighbouring partition, and a predicate on the
+# column prunes it away: from an America/New_York session, 2026-04-01 02:00 UTC is
+# filed under March, and "ts >= '2026-04-01 00:00+00'" does not return it.
+#
+# Fix: bind a TIMESTAMPTZ source as TIMESTAMP through DuckDB's default cast, which
+# reinterprets the stored UTC microseconds and never consults ICU, before date_diff.
+# Upstream also covers TIMESTAMP_TZ_NS, a type DuckDB 1.5 does not have.
+#
+# ci/journey.sh's New York-session write (TC-186) fails without this patch. Drop the
+# patch when ICEBERG_REF moves to a ref that carries the fix: git apply --check then
+# fails on the changed lines.
+#
+diff --git a/src/execution/operator/iceberg_insert.cpp b/src/execution/operator/iceberg_insert.cpp
+index 1fcba7803..3fb0502f8 100644
+--- a/src/execution/operator/iceberg_insert.cpp
++++ b/src/execution/operator/iceberg_insert.cpp
+@@ -574,8 +574,15 @@ static unique_ptr<Expression> GetDateDiffFunction(ClientContext &context, const
+ 	} else {
+ 		children.push_back(make_uniq<BoundConstantExpression>(Value::DATE(Date::FromDate(1970, 1, 1))));
+ 	}
+-	// Third argument: the source column
+-	children.push_back(CreateColumnReference(copy_input, col_type, col_idx));
++	// Third argument: the source column. A TIMESTAMPTZ source is bound as the UTC
++	// TIMESTAMP it holds: the default cast reinterprets it without consulting ICU,
++	// where date_diff on a TIMESTAMPTZ counts in the session's time zone. Iceberg
++	// defines the temporal transforms on the UTC instant.
++	auto source = CreateColumnReference(copy_input, col_type, col_idx);
++	if (col_type.id() == LogicalTypeId::TIMESTAMP_TZ) {
++		source = BoundCastExpression::AddDefaultCastToType(std::move(source), LogicalType::TIMESTAMP);
++	}
++	children.push_back(std::move(source));
+ 
+ 	ErrorData error;
+ 	FunctionBinder binder(context);
diff --git a/packaging/coldfront-duckdb-extensions/build-extensions.sh b/packaging/coldfront-duckdb-extensions/build-extensions.sh
index a05877e..aa8846c 100644
--- a/packaging/coldfront-duckdb-extensions/build-extensions.sh
+++ b/packaging/coldfront-duckdb-extensions/build-extensions.sh
@@ -45,12 +45,13 @@ git clone --depth 1 --branch "v${DUCKDB_VERSION}" --recurse-submodules "${DUCKDB
 git clone "${VCPKG_REPO}" "${BUILD_ROOT}/vcpkg"
 "${BUILD_ROOT}/vcpkg/bootstrap-vcpkg.sh" -disableMetrics
 
-# extension set (avro/azure/postgres_scanner refs) + the 3 ColdFront patches live
+# extension set (avro/azure/postgres_scanner refs) + the 4 ColdFront patches live
 # in the repo's docker/ dir; git apply --check fails loudly on patch rot.
 cp "${CWD}/docker/iceberg-azure-extension-config-v15.cmake" "$ICE/extension_config.cmake"
 for p in iceberg-bakery-aware-commit-refresh-v15 \
          iceberg-manifest-list-format-version-v15 \
-         iceberg-data-file-format-v15; do
+         iceberg-data-file-format-v15 \
+         iceberg-timestamptz-utc-transforms-v15; do
     git -C "$ICE" apply --check "${CWD}/docker/${p}.patch"
     git -C "$ICE" apply         "${CWD}/docker/${p}.patch"
 done
diff --git a/packaging/coldfront-duckdb-extensions/common.sh b/packaging/coldfront-duckdb-extensions/common.sh
index 2045dd9..0f52e82 100644
--- a/packaging/coldfront-duckdb-extensions/common.sh
+++ b/packaging/coldfront-duckdb-extensions/common.sh
@@ -23,7 +23,7 @@ export DUCKDB_EXT_VERSION="$DUCKDB_VERSION"
 export DUCKDB_EXT_BUILDNUM="${COMPONENT_BUILDNUM:-1}"
 
 # --- Build pins -------------------------------------------------------------------
-# duckdb-iceberg: the 3 patches target ICEBERG_REF (branch fetched first so the
+# duckdb-iceberg: the 4 patches target ICEBERG_REF (branch fetched first so the
 # ref resolves). avro/azure/postgres_scanner refs live in the extension_config
 # cmake (packaging copies docker/iceberg-azure-extension-config-v15.cmake).
 # ICEBERG_REF is read from the base-image Dockerfile — the single source of truth,

From ffaa589bf0c104e8d7a2a9eca4925042e53c6d95 Mon Sep 17 00:00:00 2001
From: Jimmy Angelakos <jimmy@pgedge.com>
Date: Fri, 25 Sep 2026 18:27:13 +0100
Subject: [PATCH 2/5] fix: scope a data file's position deletes to its
 partition in the compactor

---
 cmd/compactor/compact.go      | 31 +++++++++++++++++++++++++++
 cmd/compactor/compact_test.go | 40 +++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)

diff --git a/cmd/compactor/compact.go b/cmd/compactor/compact.go
index dac619d..3db50c8 100644
--- a/cmd/compactor/compact.go
+++ b/cmd/compactor/compact.go
@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"iter"
+	"reflect"
 	"strings"
 
 	"github.com/apache/arrow-go/v18/arrow"
@@ -180,6 +181,7 @@ func planCompaction(ctx context.Context, cat *rest.Catalog, ns, name string, tar
 	if err != nil {
 		return nil, nil, fmt.Errorf("plan files for %s.%s: %w", ns, name, err)
 	}
+	tasks = scopeDeletes(tasks)
 
 	cfg := compaction.DefaultConfig()
 	if targetSize > 0 {
@@ -206,6 +208,35 @@ func planCompaction(ctx context.Context, cat *rest.Catalog, ns, name string, tar
 	return tbl, &planResult{groups: groups, plan: plan, sorted: sorted, sortKey: sortKey}, nil
 }
 
+// scopeDeletes keeps, for each data file, only the position-delete files that can
+// reference its rows under the Iceberg spec: those of its own partition, and
+// those of no partition. iceberg-go v0.6.0 attaches position deletes by sequence
+// number and the delete file's file_path bounds alone (table/scanner.go,
+// matchDeletesToData), never by partition, and duckdb-iceberg 5edc45f0 writes
+// those bounds under DuckDB's FILENAME_FIELD_ID (2147483646) rather than the
+// spec's file_path field (2147483546), so every delete file is attached to every
+// data file: one delete file then sits in several partition groups, which
+// ReplaceFiles refuses, and rewriting one partition would remove the delete
+// files of a partition the planner skipped, resurrecting its deleted rows.
+// TC-190 in ci/journey.sh asserts the engine's bound key; when it moves to the
+// spec's field, or iceberg-go matches by partition, this keeps what iceberg-go
+// already kept and can go.
+func scopeDeletes(tasks []table.FileScanTask) []table.FileScanTask {
+	out := make([]table.FileScanTask, 0, len(tasks))
+	for _, task := range tasks {
+		own := task.File.Partition()
+		kept := make([]iceberg.DataFile, 0, len(task.DeleteFiles))
+		for _, df := range task.DeleteFiles {
+			if len(df.Partition()) == 0 || reflect.DeepEqual(df.Partition(), own) {
+				kept = append(kept, df)
+			}
+		}
+		task.DeleteFiles = kept
+		out = append(out, task)
+	}
+	return out
+}
+
 // rewrite executes the planned compaction as a single atomic rewrite snapshot
 // and commits it to the catalog.
 //
diff --git a/cmd/compactor/compact_test.go b/cmd/compactor/compact_test.go
index 93789f0..5e3befb 100644
--- a/cmd/compactor/compact_test.go
+++ b/cmd/compactor/compact_test.go
@@ -5,6 +5,7 @@ import (
 	"testing"
 
 	"github.com/apache/iceberg-go"
+	"github.com/apache/iceberg-go/table"
 )
 
 func testSchema() *iceberg.Schema {
@@ -63,3 +64,42 @@ func TestLoadTableErr_OtherErrorsPassThrough(t *testing.T) {
 		t.Error("non-404 error was reported as a missing table")
 	}
 }
+
+// deleteFile builds a position-delete manifest entry in the given partition.
+func deleteFile(t *testing.T, spec iceberg.PartitionSpec, path string, partition map[int]any) iceberg.DataFile {
+	t.Helper()
+	b, err := iceberg.NewDataFileBuilder(spec, iceberg.EntryContentPosDeletes, path, iceberg.ParquetFile,
+		partition, nil, nil, 1, 100)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return b.Build()
+}
+
+// A data file keeps only the position-delete files that can reference its rows:
+// those of its own partition, and those of no partition at all. Every other
+// delete file is one iceberg-go attached by sequence number alone.
+func TestScopeDeletes(t *testing.T) {
+	spec := iceberg.NewPartitionSpec(iceberg.PartitionField{
+		SourceIDs: []int{2}, FieldID: 1000, Name: "month_ts_2", Transform: iceberg.MonthTransform{}})
+	march, april := map[int]any{1000: int32(674)}, map[int]any{1000: int32(675)}
+	data, err := iceberg.NewDataFileBuilder(spec, iceberg.EntryContentData, "data/month_ts_2=674/d.parquet",
+		iceberg.ParquetFile, march, nil, nil, 10, 1000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	own := deleteFile(t, spec, "data/month_ts_2=674/own-deletes.parquet", march)
+	other := deleteFile(t, spec, "data/month_ts_2=675/other-deletes.parquet", april)
+	global := deleteFile(t, spec, "data/global-deletes.parquet", map[int]any{})
+
+	tasks := scopeDeletes([]table.FileScanTask{{File: data.Build(), DeleteFiles: []iceberg.DataFile{other, own, global}}})
+
+	got := make([]string, 0, 2)
+	for _, df := range tasks[0].DeleteFiles {
+		got = append(got, df.FilePath())
+	}
+	want := []string{"data/month_ts_2=674/own-deletes.parquet", "data/global-deletes.parquet"}
+	if len(got) != len(want) || got[0] != want[0] || got[1] != want[1] {
+		t.Fatalf("kept %v, want %v", got, want)
+	}
+}

From 6c3bd71001eb00cdd2823bf568e31fca054e583d Mon Sep 17 00:00:00 2001
From: Jimmy Angelakos <jimmy@pgedge.com>
Date: Fri, 25 Sep 2026 18:27:13 +0100
Subject: [PATCH 3/5] feat: partition cold tables the way the hot tier is

---
 README.md                                     |   5 +-
 ci/journey.sh                                 | 154 +++++++++++++++++-
 cmd/archiver/main.go                          |  64 +++++---
 cmd/archiver/main_test.go                     |  25 +++
 docs/architecture.md                          |  22 +--
 docs/architecture_decoupled.md                |  20 ++-
 docs/architecture_tiered.md                   |  40 +++--
 docs/architecture_vectors.md                  |  13 +-
 docs/changelog.md                             |  11 ++
 docs/compaction.md                            |  23 ++-
 docs/index.md                                 |   3 +-
 docs/installation.md                          |  28 ++--
 docs/object_store.md                          |   3 +-
 docs/usage.md                                 |  16 +-
 docs/usage_vectors.md                         |   7 +
 extension/coldfront/Makefile                  |   3 +-
 extension/coldfront/coldfront--1.0.sql        |  82 ++++++++--
 .../test/expected/partition_clause.out        |  89 ++++++++++
 .../coldfront/test/sql/partition_clause.sql   |  46 ++++++
 19 files changed, 547 insertions(+), 107 deletions(-)
 create mode 100644 extension/coldfront/test/expected/partition_clause.out
 create mode 100644 extension/coldfront/test/sql/partition_clause.sql

diff --git a/README.md b/README.md
index ce15487..f49c88e 100644
--- a/README.md
+++ b/README.md
@@ -100,7 +100,8 @@ SELECT coldfront.set_storage_secret('admin', 'adminsecret', 'seaweedfs:8333');
 
 -- Decoupled (iceberg-only) table, stored entirely in Iceberg on S3:
 SELECT coldfront.create_iceberg_table('public', 'events',
-  '[{"name":"id","type":"bigint"},{"name":"ts","type":"timestamptz"},{"name":"note","type":"text"}]'::jsonb);
+  '[{"name":"id","type":"bigint"},{"name":"ts","type":"timestamptz"},{"name":"note","type":"text"}]'::jsonb,
+  '{month(ts)}');
 INSERT INTO events VALUES (1, now(), 'hello');
 SELECT count(*) FROM events;
 ```
@@ -233,7 +234,7 @@ against:
 |-----------|---------|---------|
 | PostgreSQL | 16, 17, or 18 | Database with native partitioning (stock upstream; no fork) |
 | pg_duckdb | 1.5.4 (PR #1025) | Iceberg reads + writes via DuckDB in-process |
-| duckdb-iceberg | `v1.5-variegata` @ `5edc45f0`, patched | Iceberg catalog/IO for DuckDB; carries ColdFront's three patches (see [DUCKDB_1.5_PATCHED.md](DUCKDB_1.5_PATCHED.md)) |
+| duckdb-iceberg | `v1.5-variegata` @ `5edc45f0`, patched | Iceberg catalog/IO for DuckDB; carries ColdFront's four patches (see [DUCKDB_1.5_PATCHED.md](DUCKDB_1.5_PATCHED.md)) |
 | Lakekeeper | latest | Iceberg REST catalog (Rust binary) |
 | S3-compatible store | any | SeaweedFS, MinIO, GCS, Azure Blob, etc. |
 
diff --git a/ci/journey.sh b/ci/journey.sh
index 4064d09..5896a35 100755
--- a/ci/journey.sh
+++ b/ci/journey.sh
@@ -128,6 +128,22 @@ vended_creds() { [ "$BACKEND" = vended ] || [ "$BACKEND" = azure-vended ]; }
 # rather than inventing a literal.
 hot_days() { echo $(( ( $(date -u +%s) - $(date -u -d "$(date -u +%Y-%m-01) -1 month" +%s) ) / 86400 )); }
 
+# ice_files <ice_ref> <regex>: live data files (delete files and entries a later
+# snapshot removed excluded) whose path matches the regex, counted through the
+# table's own metadata scan. Addressed as the attached catalog table, which
+# reads identically on static and vended credentials: a bare object-store path
+# cannot authenticate under vending.
+ice_files() {
+    q "$HOST" "SELECT coldfront.ensure_attached(); SELECT r['n'] FROM duckdb.query('SELECT count(*) AS n FROM iceberg_metadata(''$1'') WHERE status <> ''DELETED'' AND content NOT LIKE ''%DELETES'' AND regexp_matches(file_path, ''$2'')') AS t(r);" | tail -1
+}
+
+# ice_spec <ice_ref>: the table's partition spec as transform:column terms in
+# field order (e.g. "identity:region,month:ts"), empty for an unpartitioned
+# table or one that has no data yet.
+ice_spec() {
+    q "$HOST" "SELECT coldfront.ensure_attached(); SELECT r['s'] FROM duckdb.query('SELECT string_agg(t || '':'' || c, '','' ORDER BY id) AS s FROM (SELECT DISTINCT partition_field_id AS id, partition_field_transform AS t, partition_source_columns[1] AS c FROM iceberg_partition_stats(''$1''))') AS t(r);" | tail -1
+}
+
 # assert_register_rejected <label> <table> <needle>: `archiver register` must
 # fail on <table> and say why. Passing a needle rather than only checking the
 # exit code keeps the assertion attributable to the rule under test.
@@ -269,6 +285,14 @@ EOF
     assert_eq "events is now a view" "v" "$relkind"
     local wm; wm=$(q "$HOST" "SELECT count(*) FROM coldfront.archive_watermark WHERE table_name='events';")
     assert_eq "watermark registered" "1" "$wm"
+
+    # The cold table mirrors the hot partitioning, month(ts): each archived month
+    # is a data file under its own month directory, and none sits outside one.
+    assert_eq "cold spec mirrors the hot partitioning" "month:ts" "$(ice_spec ice.public.events)"
+    local n_all n_month
+    n_all=$(ice_files ice.public.events '\.parquet'); n_month=$(ice_files ice.public.events '/data/month_ts_[0-9]+=')
+    assert_gt "archived months landed as partition files" 2 "$n_month"
+    assert_eq "every cold data file sits in a month directory" "$n_all" "$n_month"
 }
 
 # ───────────────────────────────────────────────────────────────────────────
@@ -337,9 +361,11 @@ story_provision_decoupled() {
     # references a namespace not yet committed). With the namespace already
     # committed, its in-txn CREATE SCHEMA IF NOT EXISTS no-ops and CREATE TABLE
     # succeeds. The loop is a thin safety net in case seeding raced the warehouse.
+    # Partitioned by month(ts), so every decoupled story writes and reads a
+    # partitioned table.
     local i
     for i in 1 2 3 4 5; do
-        q_may "$HOST" "SELECT coldfront.create_iceberg_table('public','iceonly','[{\"name\":\"id\",\"type\":\"bigint\"},{\"name\":\"ts\",\"type\":\"timestamptz\"},{\"name\":\"status\",\"type\":\"text\"},{\"name\":\"data\",\"type\":\"jsonb\"}]'::jsonb);" >/dev/null 2>&1
+        q_may "$HOST" "SELECT coldfront.create_iceberg_table('public','iceonly','[{\"name\":\"id\",\"type\":\"bigint\"},{\"name\":\"ts\",\"type\":\"timestamptz\"},{\"name\":\"status\",\"type\":\"text\"},{\"name\":\"data\",\"type\":\"jsonb\"}]'::jsonb, '{month(ts)}');" >/dev/null 2>&1
         [ "$(q "$HOST" "SELECT count(*) FROM pg_class WHERE relname='iceonly' AND relkind='v' AND relnamespace='public'::regnamespace;")" = "1" ] && break
         sleep 2
     done
@@ -559,10 +585,8 @@ EOSQL
 
     # The fixture's partition spec is real, and writes through the adopted view
     # honour it: each customer's files land under its own partition directory.
-    # Counted through the table's own metadata scan, which runs with the table's
-    # credentials, so it works under credential vending as well as static keys.
     assert_gt "TC-167: data files land under partition directories" 0 \
-        "$(q "$HOST" "SELECT coldfront.ensure_attached(); SELECT r['n'] FROM duckdb.query('SELECT count(*) AS n FROM iceberg_metadata(''ice.lake.orders'') WHERE file_path LIKE ''%/data/customer=initech/%''') AS t(r);" | tail -1)"
+        "$(ice_files ice.lake.orders '/data/customer=initech/')"
 
     # TC-169: p_types restores a type Iceberg cannot record, and only where the
     # override matches what the catalog actually stores. Both go through a fresh
@@ -889,6 +913,10 @@ EOF
     else
         fail "vector archive — see $TMPD/chunks.log"; tail -5 $TMPD/chunks.log; return
     fi
+    # A clustered table is partitioned like every tiered table, and is created
+    # without the file-size target DuckDB refuses on a partitioned table: the
+    # export above is the write that would have failed with it.
+    assert_gt "clustered table's export sits in a month directory" 0 "$(ice_files ice.public.chunks '/data/month_ts_[0-9]+=')"
 
     # Verify what landed in Iceberg, read straight from the cold table. Equality
     # against a real[] literal is the whole assertion: a stringified write could
@@ -1606,6 +1634,9 @@ EOSQL
         fail "TC-128: files still below target after compaction: $after"
     fi
     assert_eq "TC-130: compaction preserved all rows" "$rows_before" "$(q "$HOST" "SELECT count(*) FROM events;")"
+    # iceberg-go rewrites each partition's group on its own and writes the result
+    # back under that partition's directory.
+    assert_eq "TC-130: rewritten files sit in month directories" "$(ice_files ice.public.events '\.parquet')" "$(ice_files ice.public.events '/data/month_ts_[0-9]+=')"
 }
 
 # ───────────────────────────────────────────────────────────────────────────
@@ -2928,6 +2959,12 @@ EOF
     # Cold side is region-usable: a region-filtered cold read returns that region only.
     assert_eq "eu cold rows (m4-m2) present"      "240" "$(q "$HOST" "SELECT count(*) FROM regional WHERE region='eu' AND ts < date_trunc('month',now()) - interval '1 month';")"
     assert_eq "old eu m4 leaf rows live in cold"  "100" "$(q "$HOST" "SELECT count(*) FROM regional WHERE region='eu' AND ts >= date_trunc('month',now()) - interval '4 months' AND ts < date_trunc('month',now()) - interval '3 months';")"
+    # The cold table mirrors the two-level hot partitioning: region, then month(ts).
+    # Beside a transform, the engine files the identity term under its spec field
+    # name, identity_region_<id>, not the bare column.
+    assert_eq "2-level cold spec is (region, month(ts))" "identity:region,month:ts" "$(ice_spec ice.public.regional)"
+    assert_gt "eu files sit under identity_region_N=eu/month_ts_" 0 "$(ice_files ice.public.regional '/data/identity_region_[0-9]+=eu/month_ts_')"
+    assert_gt "us files sit under identity_region_N=us/month_ts_" 0 "$(ice_files ice.public.regional '/data/identity_region_[0-9]+=us/month_ts_')"
 
     # Idempotency / cross-region wipe guard: a second run must NOT lose cold rows
     # (a region-blind Phase-0 wipe would under-count here).
@@ -4144,7 +4181,7 @@ story_iceberg_metadata() {
     # PrepareIcebergScanFromEntry, which creates that table's secret, so this reads
     # identically on static and vended credentials and needs no backend branch.
     # De-quoted because the archiver stores the reference quoted.
-    cnt=$(q "$HOST" "SELECT coldfront.ensure_attached(); SELECT r['n'] FROM duckdb.query('SELECT count(*) AS n FROM iceberg_metadata(''${ice_ref}'') WHERE file_path LIKE ''%.parquet''') AS t(r);" | tail -1)
+    cnt=$(ice_files "$ice_ref" '\.parquet')
     assert_gt "TC-043: Parquet data files registered in the events snapshot" "0" "$cnt"
 }
 
@@ -5631,6 +5668,112 @@ EOSQL
     q "$HOST" "DROP SCHEMA qtn CASCADE;" >/dev/null 2>&1
 }
 
+# ───────────────────────────────────────────────────────────────────────────
+# Story TC-186..TC-189: partitioned cold tables. create_iceberg_table takes
+# the partitioning as DuckDB's own PARTITIONED BY terms; one write fans out into
+# one data file per partition value; the month of a TIMESTAMPTZ is its UTC
+# month whatever the session's time zone (the iceberg-timestamptz-utc-
+# transforms-v15 patch: without it a New York session files the row under the
+# previous month and a UTC month-bounded read prunes it away); a bad term is
+# refused before the table exists; and a month-bounded read skips the other
+# months' manifests. Both modes, on its own throwaway tables.
+# ───────────────────────────────────────────────────────────────────────────
+story_partitioned_cold_tables() {
+    step "TC-186..TC-189: partitioned cold tables (fan-out, UTC months, refusals, pruning)"
+    local cols='[{"name":"id","type":"bigint"},{"name":"ts","type":"timestamptz"},{"name":"status","type":"text"}]'
+    # The UTC start of the month two months back, whatever the session's zone.
+    local m="(date_trunc('month', now() AT TIME ZONE 'UTC') AT TIME ZONE 'UTC') - interval '2 months'"
+    q "$HOST" "SELECT coldfront.create_iceberg_table('public','tcpart','$cols'::jsonb, '{month(ts)}');" >/dev/null 2>&1
+
+    # TC-187: one statement, three rows in three consecutive UTC months. The hook
+    # hands the row expressions to DuckDB, so only functions both engines have.
+    q "$HOST" "INSERT INTO public.tcpart VALUES (1, ($m) + interval '1 month' + interval '10 days', 'm1'), (2, ($m) + interval '10 days', 'm2'), (3, ($m) - interval '1 month' + interval '10 days', 'm3');" >/dev/null 2>&1
+    assert_eq "TC-187: the spec is month(ts)" "month:ts" "$(ice_spec ice.public.tcpart)"
+    assert_eq "TC-187: one bulk write lands one file per month" "3" "$(ice_files ice.public.tcpart '/data/month_ts_[0-9]+=')"
+    assert_eq "TC-187: no data file outside a month directory" "3" "$(ice_files ice.public.tcpart '\.parquet')"
+    assert_eq "TC-187: a month-bounded read returns that month only" "m2" \
+        "$(q "$HOST" "SELECT status FROM public.tcpart WHERE ts >= $m AND ts < ($m) + interval '1 month';")"
+
+    # TC-186: a row two hours into that UTC month, written from a New York session,
+    # where the local clock still shows the previous month.
+    q "$HOST" "SET TimeZone = 'America/New_York'; INSERT INTO public.tcpart VALUES (10, ($m) + interval '2 hours', 'tz');" >/dev/null 2>&1
+    assert_eq "TC-186: a boundary write from a non-UTC session reads back in its UTC month" "1" \
+        "$(q "$HOST" "SELECT count(*) FROM public.tcpart WHERE status = 'tz' AND ts >= $m;")"
+    local n; n=$(q "$HOST" "SELECT ((extract(year FROM $m) - 1970) * 12 + extract(month FROM $m) - 1)::int;")
+    assert_eq "TC-186: its file sits in the UTC month's directory" "2" "$(ice_files ice.public.tcpart "/data/month_ts_[0-9]+=${n}/")"
+
+    # TC-189: a read bounded to the oldest month skips the manifest whose months
+    # all lie outside it (the New York write's), which duckdb-iceberg logs. The
+    # upper bound sits inside the month: the pruner compares months, so a bound
+    # exactly on the next month's start keeps that month's manifests.
+    assert_gt "TC-189: a month-bounded read skips out-of-range manifests" 0 \
+        "$(q "$HOST" "SELECT coldfront.ensure_attached(); SELECT duckdb.raw_query('CALL enable_logging(''Iceberg'')'); SELECT count(*) FROM public.tcpart WHERE ts >= ($m) - interval '1 month' AND ts < ($m) - interval '1 month' + interval '20 days'; SELECT r['n'] FROM duckdb.query('SELECT count(*) AS n FROM duckdb_logs() WHERE type = ''Iceberg'' AND message LIKE ''%skipped%manifest_file%''') AS t(r);" | tail -1)"
+
+    # TC-188: a time transform on a text column is refused by ColdFront before
+    # anything is created, an unknown transform by the engine, and a table created
+    # without p_partition_cols is not partitioned at all.
+    local out
+    out=$(q_may "$HOST" "SELECT coldfront.create_iceberg_table('public','tcbad','$cols'::jsonb, '{month(status)}');")
+    if echo "$out" | grep "needs a timestamp or date column" >/dev/null; then
+        pass "TC-188: a time transform on a text column is refused"
+    else
+        fail "TC-188: expected the type refusal, got: $out"
+    fi
+    out=$(q_may "$HOST" "SELECT coldfront.create_iceberg_table('public','tcbad','$cols'::jsonb, '{bogus(ts)}');")
+    if echo "$out" | grep -i "unrecognized transform" >/dev/null; then
+        pass "TC-188: an unknown transform is refused by the engine"
+    else
+        fail "TC-188: expected the engine's refusal, got: $out"
+    fi
+    assert_eq "TC-188: a refused create registers nothing" "0" "$(q "$HOST" "SELECT count(*) FROM coldfront.tiered_views WHERE relname = 'tcbad';")"
+    q "$HOST" "SELECT coldfront.create_iceberg_table('public','tcflat','$cols'::jsonb);" >/dev/null 2>&1
+    q "$HOST" "INSERT INTO public.tcflat VALUES (1, now(), 'a'), (2, now() - interval '1 month', 'b');" >/dev/null 2>&1
+    assert_eq "TC-188: without p_partition_cols two months share one file" "1" "$(ice_files ice.public.tcflat '\.parquet')"
+    assert_eq "TC-188: and the table has no partition spec" "" "$(ice_spec ice.public.tcflat)"
+
+    # TC-190: compaction of a partitioned table with deletes. Month A holds six
+    # small files and month B two, each month with deleted rows. The compactor
+    # rewrites A alone (B is under MinInputFiles) and must leave B's delete file
+    # where it is. iceberg-go attaches a delete file to a data file by the file's
+    # file_path bounds, and the engine writes those under DuckDB's own field id,
+    # so without the compactor scoping deletes to their partition (compact.go,
+    # scopeDeletes) B's delete file would ride along with A's rewrite and its
+    # deleted row would come back. The last assertion is the engine fact itself:
+    # when it stops holding, the scoping can go.
+    require_compactor || return
+    q "$HOST" "SELECT coldfront.create_iceberg_table('public','tccomp','$cols'::jsonb, '{month(ts)}');" >/dev/null 2>&1
+    local i
+    for i in 1 2 3 4 5 6; do q "$HOST" "INSERT INTO public.tccomp VALUES ($i, ($m) + interval '$i days', 'a');" >/dev/null 2>&1; done
+    for i in 7 8; do q "$HOST" "INSERT INTO public.tccomp VALUES ($i, ($m) + interval '1 month' + interval '$i days', 'b');" >/dev/null 2>&1; done
+    q "$HOST" "DELETE FROM public.tccomp WHERE id IN (1, 2, 7);" >/dev/null 2>&1
+    assert_eq "TC-190: eight rows written, three deleted" "5" "$(q "$HOST" "SELECT count(*) FROM public.tccomp;")"
+    cat > $TMPD/tccomp.yaml <<EOF
+postgres: { dsn: "host=${DB_IP} port=5432 dbname=coldfront user=coldfront password=coldfront sslmode=disable" }
+iceberg:  { warehouse: "${WAREHOUSE}", lakekeeper_endpoint: "http://${LK_IP}:8181/catalog" }
+$(storage_yaml)
+EOF
+    if "$COMPACTOR" --config $TMPD/tccomp.yaml --table tccomp >$TMPD/tccomp.log 2>&1; then
+        pass "TC-190: compaction of a partitioned table with deletes succeeds"
+    else
+        fail "TC-190: compaction failed, see $TMPD/tccomp.log"; tail -3 $TMPD/tccomp.log
+    fi
+    assert_eq "TC-190: month A merged into one file, month B left alone" "3" "$(ice_files ice.public.tccomp '\.parquet')"
+    assert_eq "TC-190: deleted rows stay deleted after compaction" "5" "$(q "$HOST" "SELECT count(*) FROM public.tccomp;")"
+    assert_eq "TC-190: the skipped month keeps its delete file" "1" \
+        "$(q "$HOST" "SELECT coldfront.ensure_attached(); SELECT r['n'] FROM duckdb.query('SELECT count(*) AS n FROM iceberg_metadata(''ice.public.tccomp'') WHERE status <> ''DELETED'' AND content = ''POSITION_DELETES''') AS t(r);" | tail -1)"
+    if vended_creds; then
+        note "TC-190: delete-manifest bound key not read under vended credentials (a path read cannot authenticate)"
+    else
+        local mf; mf=$(q "$HOST" "SELECT coldfront.ensure_attached(); SELECT r['p'] FROM duckdb.query('SELECT DISTINCT manifest_path AS p FROM iceberg_metadata(''ice.public.tccomp'') WHERE status <> ''DELETED'' AND content = ''POSITION_DELETES''') AS t(r);" | tail -1)
+        assert_eq "TC-190: the engine keys delete-file bounds by DuckDB's FILENAME_FIELD_ID (scopeDeletes stays)" "2147483646" \
+            "$(q "$HOST" "SELECT coldfront.ensure_attached(); SELECT r['k'] FROM duckdb.query('SELECT string_agg(DISTINCT k::VARCHAR, '','') AS k FROM (SELECT unnest(map_keys(data_file.lower_bounds)) AS k FROM read_avro(''$mf''))') AS t(r);" | tail -1)"
+    fi
+
+    q "$HOST" "SELECT coldfront.drop_iceberg_table('public','tcpart', true);" >/dev/null 2>&1
+    q "$HOST" "SELECT coldfront.drop_iceberg_table('public','tcflat', true);" >/dev/null 2>&1
+    q "$HOST" "SELECT coldfront.drop_iceberg_table('public','tccomp', true);" >/dev/null 2>&1
+}
+
 # ── orchestrate ────────────────────────────────────────────────────────────
 # Setup is shared. The story set then branches on mode: tiered exercises the
 # hot+cold partitioned path; decoupled exercises the all-Iceberg wrapper. (The
@@ -5722,6 +5865,7 @@ else
 fi
 story_duckdb_temp_dirs     # TC-152: per-backend spill dir; departed backends' spills reclaimed
 story_duckdb_spill_concurrency  # TC-153: four sessions spilling at once stay isolated and correct
+story_partitioned_cold_tables  # TC-186..TC-189: partition fan-out, UTC months, refusals, manifest skipping
 story_drop_iceberg_table   # both modes, purge and keep-files (own throwaway tables)
 [ "$MESH" = 1 ] && [ "$MODE" = decoupled ] && story_mesh   # tiered+mesh runs story_mesh_tiered (above)
 [ "$MESH" = 1 ] && story_mesh_multiwriter   # >1 cold writer/node cross-node (tiered: events, decoupled: iceonly)
diff --git a/cmd/archiver/main.go b/cmd/archiver/main.go
index fa67f9a..f2dd44f 100644
--- a/cmd/archiver/main.go
+++ b/cmd/archiver/main.go
@@ -405,6 +405,10 @@ type archiveCycle struct {
 	iceTable         string
 	now              time.Time
 	debugExportDelay time.Duration
+	// listCol is the LIST (level-1) column of a two-level table, empty for a flat
+	// one: the cold table is partitioned by it, and the Phase-0 wipe is scoped to
+	// its value.
+	listCol string
 	// The archive watermark as it stood when this cycle's tiering pass began,
 	// captured by bootstrapTieredView before the per-partition loop and held
 	// fixed for the whole pass. Each cutover advances the stored watermark to
@@ -495,7 +499,7 @@ func (ac *archiveCycle) attachAndEnsureTable(ctx context.Context) error {
 	if err := attachIceberg(ctx, ac.conn, ac.cfg); err != nil {
 		return err
 	}
-	if err := ensureIcebergTable(ctx, ac.conn, ac.t, ac.iceTable); err != nil {
+	if err := ensureIcebergTable(ctx, ac.conn, ac.t, ac.iceTable, ac.listCol); err != nil {
 		return fmt.Errorf("ensure iceberg table: %w", err)
 	}
 	return nil
@@ -758,6 +762,13 @@ func runCycleTwoLevel(ctx context.Context, cfg *config.Config, t *config.TableCo
 		return fmt.Errorf("values_source: %w", err)
 	}
 	parent := partition.ResolveSourceTable(ctx, conn, t.SourceSchema, t.SourceTable) // physical top (_events after swap)
+	// The LIST column is read before the tiering preamble renames the hot table,
+	// though detectPartitionColumns resolves either name.
+	listCols, err := detectPartitionColumns(ctx, conn, t.SourceSchema, t.SourceTable)
+	if err != nil {
+		return fmt.Errorf("detect list column: %w", err)
+	}
+	ac.listCol = listCols[0]
 
 	// 1. Premake per LIST value: ensure the LIST child exists (attached to the
 	//    physical top, named by the stable source name) and its forward window.
@@ -863,19 +874,8 @@ func (ac *archiveCycle) findExpiredLeaves(ctx context.Context, children []childR
 }
 
 // tierLeavesByPeriod is step 4 of the 2-level cycle: run the shared tiering
-// preamble, detect the LIST column, then group the leaves by ts period and tier
-// them oldest-first.
+// preamble, then group the leaves by ts period and tier them oldest-first.
 func (ac *archiveCycle) tierLeavesByPeriod(ctx context.Context, leaves []leafRef) error {
-	t := ac.t
-	// The LIST (level-1) column, for the LIST-value-scoped Phase-0 wipe. Read
-	// before the preamble renames the hot table, though detectPartitionColumns
-	// resolves either name.
-	listCols, err := detectPartitionColumns(ctx, ac.conn, t.SourceSchema, t.SourceTable)
-	if err != nil {
-		return fmt.Errorf("detect list column: %w", err)
-	}
-	listCol := listCols[0]
-
 	columns, err := ac.prepareTiering(ctx)
 	if err != nil {
 		return err
@@ -886,7 +886,7 @@ func (ac *archiveCycle) tierLeavesByPeriod(ctx context.Context, leaves []leafRef
 		if err := ctx.Err(); err != nil {
 			return err
 		}
-		if err := ac.tierOnePeriod(ctx, columns, listCol, grp); err != nil {
+		if err := ac.tierOnePeriod(ctx, columns, ac.listCol, grp); err != nil {
 			return err
 		}
 	}
@@ -1219,7 +1219,8 @@ func vecCompanion(col string) string { return "_cf_vec_" + col }
 // vecLayoutProps asks the extension for the CREATE TABLE properties a clustered
 // table needs, or "" when the table has no vector. The values live in the
 // extension so both modes create the same layout; the primary key rides along as
-// the sort key's tiebreak, which only this side knows.
+// the sort key's tiebreak, which only this side knows. Every table the archiver
+// creates is partitioned, which the extension's property set depends on.
 func vecLayoutProps(ctx context.Context, conn *pgx.Conn, columns []view.Column) (string, error) {
 	if len(vectorColumns(columns)) == 0 {
 		return "", nil
@@ -1232,7 +1233,7 @@ func vecLayoutProps(ctx context.Context, conn *pgx.Conn, columns []view.Column)
 	}
 	var props string
 	if err := conn.QueryRow(ctx,
-		"SELECT coldfront._vec_layout_props(coldfront._vec_sort_key($1, $2))",
+		"SELECT coldfront._vec_layout_props(coldfront._vec_sort_key($1, $2), true)",
 		vectorColumns(columns)[0], pk).Scan(&props); err != nil {
 		return "", fmt.Errorf("layout properties: %w", err)
 	}
@@ -1421,9 +1422,28 @@ func icebergRef(schema, table string) string {
 	return pgx.Identifier{"ice", schema, table}.Sanitize()
 }
 
+// coldPartitionClause is the PARTITIONED BY clause the cold table is created
+// with, mirroring the hot partitioning: the period's transform on the time
+// column, led by the LIST column of a two-level table (listCol, empty for a flat
+// one). One export is then exactly one partition, a leaf wipe covers exactly one,
+// and a predicate on either column skips whole manifests.
+func coldPartitionClause(period, tsCol, listCol string) (string, error) {
+	transform := map[string]string{partition.PeriodMonthly: "month", partition.PeriodDaily: "day"}[period]
+	if transform == "" {
+		return "", fmt.Errorf("partition_period %q has no Iceberg transform", period)
+	}
+	var terms []string
+	if listCol != "" {
+		terms = append(terms, pgx.Identifier{listCol}.Sanitize())
+	}
+	terms = append(terms, transform+"("+pgx.Identifier{tsCol}.Sanitize()+")")
+	return " PARTITIONED BY (" + strings.Join(terms, ", ") + ")", nil
+}
+
 // ensureIcebergTable creates the Iceberg namespace and table (matching the
-// PG source schema) if they don't already exist. Safe to call every run.
-func ensureIcebergTable(ctx context.Context, conn *pgx.Conn, t *config.TableConfig, iceTable string) error {
+// PG source schema) if they don't already exist. Safe to call every run. The
+// partition spec is set at creation and stays with the table.
+func ensureIcebergTable(ctx context.Context, conn *pgx.Conn, t *config.TableConfig, iceTable, listCol string) error {
 	if err := execDuckDB(ctx, conn, fmt.Sprintf("CREATE SCHEMA IF NOT EXISTS %s",
 		pgx.Identifier{"ice", t.SourceSchema}.Sanitize())); err != nil {
 		return fmt.Errorf("create namespace: %w", err)
@@ -1444,12 +1464,16 @@ func ensureIcebergTable(ctx context.Context, conn *pgx.Conn, t *config.TableConf
 	}
 	colDefs := strings.Join(defs, ", ")
 
+	part, err := coldPartitionClause(t.PartitionPeriod, t.PartitionColumn, listCol)
+	if err != nil {
+		return err
+	}
 	props, err := vecLayoutProps(ctx, conn, columns)
 	if err != nil {
 		return err
 	}
-	if err := execDuckDB(ctx, conn, fmt.Sprintf("CREATE TABLE IF NOT EXISTS %s (%s)%s",
-		iceTable, colDefs, props)); err != nil {
+	if err := execDuckDB(ctx, conn, fmt.Sprintf("CREATE TABLE IF NOT EXISTS %s (%s)%s%s",
+		iceTable, colDefs, part, props)); err != nil {
 		return fmt.Errorf("create iceberg table: %w", err)
 	}
 	return nil
diff --git a/cmd/archiver/main_test.go b/cmd/archiver/main_test.go
index a376695..2e2b8aa 100644
--- a/cmd/archiver/main_test.go
+++ b/cmd/archiver/main_test.go
@@ -622,3 +622,28 @@ func TestIcebergRef_QuotesEveryPart(t *testing.T) {
 	assert.Equal(t, `"ice"."lake"."orders"`, icebergRef("lake", "orders"))
 	assert.Equal(t, `"ice"."Lake-EU"."say ""hi"""`, icebergRef("Lake-EU", `say "hi"`))
 }
+
+// The cold table is partitioned the way the hot one is: the period's transform on
+// the time column, led by the LIST column of a two-level table.
+func TestColdPartitionClause(t *testing.T) {
+	cases := []struct{ name, period, ts, list, want string }{
+		{"monthly", partition.PeriodMonthly, "ts", "", ` PARTITIONED BY (month("ts"))`},
+		{"daily", partition.PeriodDaily, "ts", "", ` PARTITIONED BY (day("ts"))`},
+		{"two-level leads with the LIST column", partition.PeriodMonthly, "ts", "region",
+			` PARTITIONED BY ("region", month("ts"))`},
+		{"every name is quoted", partition.PeriodDaily, "Event Time", `say "hi"`,
+			` PARTITIONED BY ("say ""hi""", day("Event Time"))`},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			got, err := coldPartitionClause(c.period, c.ts, c.list)
+			require.NoError(t, err)
+			assert.Equal(t, c.want, got)
+		})
+	}
+}
+
+func TestColdPartitionClause_UnknownPeriod(t *testing.T) {
+	_, err := coldPartitionClause("weekly", "ts", "")
+	assert.ErrorContains(t, err, "weekly")
+}
diff --git a/docs/architecture.md b/docs/architecture.md
index 30a9e4a..3ec51fc 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -522,8 +522,7 @@ in [usage.md](usage.md#managing-partitioned-tables-cli).
 
 These apply to both storage modes. Tiered-only limitations (cold
 RETURNING, dual-tier command tag, crash-safety of permissive writes,
-partition-scheme constraints, the empty cold-tier partition spec,
-autovacuum-vs-cutover) are in
+partition-scheme constraints, autovacuum-vs-cutover) are in
 [architecture_tiered.md → Tiered-specific limitations](architecture_tiered.md#tiered-specific-limitations).
 
 The cross-cutting limitations are:
@@ -771,25 +770,6 @@ so the secret sits at a committed timestamp before a consumer's fresh
 transaction looks it up. Either would let a per-session synthesized
 secret work without relying on the persistent-secret mechanism.
 
-### duckdb-iceberg: INSERT into a table with a partition spec
-
-duckdb-iceberg refuses to INSERT into an Iceberg table that has a
-non-empty partition spec (*"INSERT into a partitioned table is not
-supported yet"*), so setting `month(ts)` to make predicate pruning
-structural rather than statistical is not possible.
-
-**Workaround today:** none - Iceberg tables created by coldfront have an
-empty partition spec; cold-tier pruning relies on per-file manifest
-min/max stats. See
-[architecture_tiered.md → Tiered-specific limitations](architecture_tiered.md#tiered-specific-limitations).
-
-**Desired end-state.** INSERT/MERGE into a partitioned Iceberg table -
-DuckDB writes data files into the appropriate partition directories based
-on the catalog's current spec, with no new SQL surface (existing
-`INSERT INTO ice.x VALUES ...` would route rows through the partition
-transform). Until then the spec stays empty and pruning relies on
-manifest statistics.
-
 ### duckdb-iceberg: append to the manifest list instead of rebuilding it
 
 At commit, duckdb-iceberg (v1.5) rebuilds the new snapshot's manifest
diff --git a/docs/architecture_decoupled.md b/docs/architecture_decoupled.md
index 67dfaab..19117a1 100644
--- a/docs/architecture_decoupled.md
+++ b/docs/architecture_decoupled.md
@@ -172,7 +172,8 @@ SELECT coldfront.create_iceberg_table(
       {"name":"ts",     "type":"timestamptz"},
       {"name":"status", "type":"text"},
       {"name":"data",   "type":"jsonb"}
-    ]'::jsonb
+    ]'::jsonb,
+    '{month(ts)}'
 );
 
 INSERT INTO events VALUES (1, now(), 'ok', '{"k":1}');
@@ -181,12 +182,23 @@ UPDATE events SET status = 'done' WHERE id = 1;
 DELETE FROM events WHERE id = 1;
 ```
 
+The fourth argument, `p_partition_cols`, is the table's Iceberg
+partitioning as a `text[]` of `PARTITIONED BY` terms, passed to DuckDB as
+written; the terms, and how a term with a comma or a quoted name is
+written in the array literal, are in
+[usage.md → Mode 2](usage.md#mode-2-decoupled-iceberg-only). DuckDB
+refuses an unknown transform, a bad argument or a column outside the
+schema at `CREATE TABLE`. The one check DuckDB leaves to the first
+INSERT, a time transform on a column that is not a timestamp or date
+(for `hour`, not a timestamp), `coldfront._partition_clause()` makes at
+the same point, while no table exists yet.
+
 What the helper does:
 
 1. `duckdb.raw_query('CREATE SCHEMA IF NOT EXISTS ice."public"')` -
    idempotent namespace creation against Lakekeeper.
 2. `duckdb.raw_query('CREATE TABLE ice.public.<name> (col1
-   STORAGE_TYPE, …)')` - column types are validated by
+   STORAGE_TYPE, …) PARTITIONED BY (…)')` - column types are validated by
    `coldfront._iceberg_storage_type()`, which mirrors the canonical
    map in `cmd/archiver/main.go pgFormatTypeToDuckDB`. Anything outside
    the supported set (see "Supported column types" above) raises before
@@ -223,10 +235,6 @@ Write semantics through the wrapper view:
 
 Limits the helper inherits from the platform:
 
-- **No partition spec at CREATE.** `p_partition_cols` is accepted as a
-  parameter but currently ignored - pg_duckdb and duckdb-iceberg do not
-  expose Iceberg partition specs at CREATE TABLE time. Predicate
-  pushdown still works via Parquet row-group statistics.
 - **Mixed-write guard relaxed.** The helper sets
   `duckdb.unsafe_allow_mixed_transactions = on` LOCAL during
   provisioning (Iceberg DDL + coldfront registry row both happen). The
diff --git a/docs/architecture_tiered.md b/docs/architecture_tiered.md
index b9dbc2c..25e7637 100644
--- a/docs/architecture_tiered.md
+++ b/docs/architecture_tiered.md
@@ -502,6 +502,34 @@ SELECT * FROM _events WHERE ts = '2026-04-15';
 
 This is a read-path detail; writes are unaffected.
 
+## Cold-tier partitioning
+
+The archiver creates the Iceberg table partitioned the way the hot table
+is: `month(ts)` or `day(ts)` on the time column, following
+`partition_period`, and for a two-level LIST→RANGE table the LIST column
+first, so `regional` becomes `PARTITIONED BY (region, month(ts))`. The
+spec is set at `CREATE TABLE IF NOT EXISTS` and stays with the table.
+Each export then writes exactly one partition, the Phase-0 wipe of a leaf
+covers exactly one, and a predicate on `ts` or on the LIST column skips
+whole manifests before any data file is opened: the manifest list carries
+each manifest's partition-value bounds, and duckdb-iceberg applies the
+transform to the predicate's constant to compare them. The comparison is
+by month, so an upper bound that falls exactly on a month's start keeps
+that month's manifests (`ts < '2026-07-01'` reads as "up to and including
+July"); the files inside them are still skipped on their own
+statistics. The `month` or
+`day` of a `timestamptz` is its UTC month or day, on write and on read,
+whatever the session's time zone. Data files sit under
+`data/month_ts_<n>=<months since 1970>/`, or
+`data/identity_region_<n>=<value>/month_ts_<n>=…/` for a two-level table
+(beside a transform, the engine names the identity term by its spec field
+rather than the bare column); the path is
+opaque to readers, and iceberg-go's rewrites use the same field name with
+its own value format. Within a partition, each file's `min(ts)/max(ts)`
+statistics prune as well. Retention DELETEs and the wipe are position
+deletes, so partitioning makes reads skip months; it does not make
+deletes cheaper.
+
 ## Tiered-specific limitations
 
 These are specific to the dual-tier model. Cross-cutting limitations
@@ -539,17 +567,7 @@ The dual-tier model carries the following limitations:
 5. **Partitioned tables only** - the source table must already be
    range-partitioned.
 
-6. **No Iceberg partition spec on the cold tier** - Iceberg tables
-   are created without a `partition-spec`
-   (`partition-specs[0].fields = []`), because duckdb-iceberg rejects
-   writes to a partitioned table. Cold-tier predicate pruning therefore
-   relies on **per-file manifest min/max statistics**, which
-   DuckDB-iceberg uses to skip data files whose range doesn't intersect
-   a query's WHERE clause. Writing one Iceberg snapshot per source
-   partition keeps each file's `min(ts)/max(ts)` tight, which is what
-   makes that pruning effective.
-
-7. **Cutover blocked by autovacuum on freshly-loaded partitions** -
+6. **Cutover blocked by autovacuum on freshly-loaded partitions** -
    Phase 4 of `archivePartition` takes `ACCESS EXCLUSIVE` on the
    partition under a 100 ms `lock_timeout` circuit breaker. Autovacuum's
    `SHARE UPDATE EXCLUSIVE` on the partition conflicts with that
diff --git a/docs/architecture_vectors.md b/docs/architecture_vectors.md
index 7a41515..98dbeaa 100644
--- a/docs/architecture_vectors.md
+++ b/docs/architecture_vectors.md
@@ -258,7 +258,7 @@ Three properties, set at `CREATE TABLE`:
 | Property | Value | Read by |
 |---|---|---|
 | `write.parquet.row-group-limit` | `2048` | iceberg-go |
-| `write.target-file-size-bytes` | `536870912` | both |
+| `write.target-file-size-bytes` | `536870912`, unpartitioned only | both |
 | `coldfront.sort-key` | the cluster column, then the key | the compactor |
 
 Row groups are the pruning granularity: the Parquet reader skips a row group
@@ -270,7 +270,10 @@ does not work while preserving insertion order`), so it is not set. A DuckDB
 write therefore emits one row group per file and compaction is what cuts them.
 
 The file target is large because on object storage every file a query touches is
-a billed round trip.
+a billed round trip. A partitioned table (every tiered table, and a decoupled
+one created with `p_partition_cols`) is created without it: DuckDB refuses the
+property on a partitioned table and does not split a partitioned write by size
+anyway, and the compactor takes its target from `--target-size-mb`.
 
 The sort key's leading column is what a compaction orders its inputs by. The key
 after it is a tiebreak for determinism, not a pruning aid: sorting by cluster
@@ -296,6 +299,12 @@ What that would cost is a run count: a probe reads at least one row group per
 sorted run, so bounding file count without merging the runs bounds the wrong
 thing.
 
+**A partition is a run boundary.** Compaction merges within a partition, never
+across, so a table partitioned by month holds at least one sorted run per month.
+A search with a time filter skips the months outside it at the manifest level; a
+search over all of history reads about one row group per probed cluster per
+month instead of one.
+
 The two halves are iceberg-go's own, which is what makes the merge safe rather
 than merely correct on a good day. Reading through the scan applies the position
 deletes a cold UPDATE or DELETE left behind; writing through `WriteRecords`
diff --git a/docs/changelog.md b/docs/changelog.md
index 6426e0a..782d261 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -11,6 +11,17 @@ and this project adheres to
 
 ### Added
 
+- Cold tables are partitioned. The archiver creates a tiered table's
+  Iceberg table partitioned the way the hot table is, `month(ts)` or
+  `day(ts)` on the time column, led by the LIST column of a two-level
+  table, so each export is one partition and a query with a time filter
+  skips the months outside it before reading anything.
+- `coldfront.create_iceberg_table()` takes `p_partition_cols`, the
+  partitioning as DuckDB's own `PARTITIONED BY` terms: `'{month(ts)}'`,
+  `'{month(ts), region}'`, `'{"bucket(16, id)"}'`.
+- The base image carries a fourth duckdb-iceberg patch, a port of upstream
+  d3c3348271, so the month of a `timestamptz` partition column is its UTC
+  month whatever the session's time zone.
 - `coldfront.adopt_iceberg_table()` gives a table that already exists in
   the Iceberg catalog a PostgreSQL wrapper view and a registry row, so it
   reads like one ColdFront created. The schema comes from the catalog, and
diff --git a/docs/compaction.md b/docs/compaction.md
index e42b840..a577048 100644
--- a/docs/compaction.md
+++ b/docs/compaction.md
@@ -1,11 +1,11 @@
 # COMPACTOR - cold-tier table maintenance
 
 `cmd/compactor` keeps a cold-tier Iceberg table healthy: it compacts
-small Parquet files into fewer large ones, expires old snapshots, and
-removes orphan files. ColdFront's cold tier writes one Parquet file per
-append and nothing else reclaims the resulting bloat, so without
-maintenance a busy table accumulates tens of thousands of tiny files and
-an unbounded snapshot history.
+each partition's small Parquet files into fewer large ones, expires old
+snapshots, and removes orphan files. ColdFront's cold tier writes one
+Parquet file per append and nothing else reclaims the resulting bloat, so
+without maintenance a busy table accumulates tens of thousands of tiny
+files and an unbounded snapshot history.
 
 It is a standalone static binary built on [apache/iceberg-go], separate
 from the archiver. Every operation that mutates a table is serialized
@@ -69,9 +69,16 @@ One binary serves every ColdFront cold store; configure exactly one:
 The compactor loads the table from the Lakekeeper catalog and runs the
 requested steps, each under a bakery claim on that table:
 
-- **Compaction** bin-packs below-target data files and rewrites each
-  group into one larger file, preserving every row (existing deletes are
-  applied). If nothing is below target it does nothing.
+- **Compaction** bin-packs below-target data files, partition by
+  partition, and rewrites each group into one larger file under its
+  partition, preserving every row (existing deletes are applied). If
+  nothing is below target it does nothing. Before planning, each data
+  file's position-delete files are scoped to its own partition, the only
+  ones that can reference its rows: iceberg-go attaches them by the
+  delete file's `file_path` bounds, which duckdb-iceberg writes under
+  DuckDB's own field id, so it would otherwise attach every delete file
+  to every data file and remove a skipped partition's delete files along
+  with a rewritten one.
 - **Snapshot expiry** is age-driven: it drops snapshots older than
   `--expire-older-than` (always keeping the current snapshot and at least
   `--expire-retain-last`) and, by default, deletes the data and manifest
diff --git a/docs/index.md b/docs/index.md
index 1847522..d2f5a92 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -84,7 +84,8 @@ SELECT coldfront.set_storage_secret('admin', 'adminsecret', 'seaweedfs:8333');
 
 -- Decoupled (iceberg-only) table, stored entirely in Iceberg on S3:
 SELECT coldfront.create_iceberg_table('public', 'events',
-  '[{"name":"id","type":"bigint"},{"name":"ts","type":"timestamptz"},{"name":"note","type":"text"}]'::jsonb);
+  '[{"name":"id","type":"bigint"},{"name":"ts","type":"timestamptz"},{"name":"note","type":"text"}]'::jsonb,
+  '{month(ts)}');
 INSERT INTO events VALUES (1, now(), 'hello');
 SELECT count(*) FROM events;
 ```
diff --git a/docs/installation.md b/docs/installation.md
index 40b1cf8..7a90c07 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -7,10 +7,12 @@
 
 ColdFront runs on a **DuckDB 1.5.x** stack: PostgreSQL + pg_duckdb
 (DuckDB 1.5.4) and a **patched** duckdb-iceberg that carries ColdFront's
-three patches - the bakery-aware commit-refresh patch (the no-409
-guarantee for concurrent cold-tier writers) and two strict-reader
+four patches - the bakery-aware commit-refresh patch (the no-409
+guarantee for concurrent cold-tier writers), two strict-reader
 interop patches (so apache/iceberg-go, the cold-tier compactor, can read
-the manifests duckdb-iceberg writes). The patch internals are in
+the manifests duckdb-iceberg writes) and a port of an upstream fix that
+computes the time partitions of a `timestamptz` column in UTC. The patch
+internals are in
 [DUCKDB_1.5_PATCHED.md](https://github.com/pgEdge/ColdFront/blob/main/DUCKDB_1.5_PATCHED.md).
 No released pg_duckdb tag carries DuckDB 1.5.x yet, so the stack is built
 from a pinned upstream PR plus our patches - all from sources you can
@@ -31,13 +33,13 @@ components:
 
 The base build runs as three Docker stages: the first builds libcurl and
 pg_duckdb; the second clones duckdb-iceberg at the pinned ref, applies
-ColdFront's three patches, and compiles the iceberg, avro, azure, and
+ColdFront's four patches, and compiles the iceberg, avro, azure, and
 postgres_scanner extensions under vcpkg; the third assembles the runtime.
 The build `git apply --check`s each patch before applying it, so it fails
 loudly on patch rot rather than silently shipping stock iceberg (which
 409s under concurrency and writes manifests strict Apache readers reject).
 
-ColdFront applies the following three patches to duckdb-iceberg; the full
+ColdFront applies the following four patches to duckdb-iceberg; the full
 rationale is in
 [DUCKDB_1.5_PATCHED.md](https://github.com/pgEdge/ColdFront/blob/main/DUCKDB_1.5_PATCHED.md):
 
@@ -46,11 +48,14 @@ rationale is in
 | `iceberg-bakery-aware-commit-refresh-v15` | Refreshes the table head at the commit POST (and re-creates the table's storage secret in the commit context, needed under catalog credential vending) so concurrent cold writers never get a Lakekeeper 409 (the no-409 guarantee). |
 | `iceberg-manifest-list-format-version-v15` | Adds the spec-optional `format-version` key to the manifest-list metadata so strict Apache readers parse the entries as v2. |
 | `iceberg-data-file-format-v15` | Upper-cases the data-file format in the manifest to match the spec enum strict readers check case-sensitively. |
-
-The bakery patch is mandatory for the no-409 guarantee. The other two
-are interop patches so the manifests duckdb-iceberg writes are readable
-by strict Apache readers such as apache/iceberg-go, the cold-tier
-compactor; they are inert to pg_duckdb's own reads. The canonical recipe
+| `iceberg-timestamptz-utc-transforms-v15` | Computes the year/month/day/hour partition of a `timestamptz` column on the UTC instant rather than in the session's time zone (a port of upstream duckdb-iceberg d3c3348271). |
+
+The bakery patch is mandatory for the no-409 guarantee. The two interop
+patches make the manifests duckdb-iceberg writes readable by strict
+Apache readers such as apache/iceberg-go, the cold-tier compactor; they
+are inert to pg_duckdb's own reads. The fourth is what makes a
+partitioned cold table correct when written from a session whose time
+zone is not UTC. The canonical recipe
 - every source pin and compile step - is
 [`docker/Dockerfile.duckdb15-base`](https://github.com/pgEdge/ColdFront/blob/main/docker/Dockerfile.duckdb15-base) itself.
 
@@ -143,7 +148,8 @@ CREATE EXTENSION IF NOT EXISTS pg_duckdb;
 CREATE EXTENSION IF NOT EXISTS coldfront;
 SELECT coldfront.set_storage_secret('admin', 'adminsecret', 'seaweedfs:8333');
 SELECT coldfront.create_iceberg_table('public', 'events',
-  '[{"name":"id","type":"bigint"},{"name":"ts","type":"timestamptz"},{"name":"note","type":"text"}]'::jsonb);
+  '[{"name":"id","type":"bigint"},{"name":"ts","type":"timestamptz"},{"name":"note","type":"text"}]'::jsonb,
+  '{month(ts)}');
 INSERT INTO events VALUES (1, now(), 'hello');
 SELECT count(*) FROM events;
 SQL
diff --git a/docs/object_store.md b/docs/object_store.md
index d6b1931..377ae5d 100644
--- a/docs/object_store.md
+++ b/docs/object_store.md
@@ -280,7 +280,8 @@ SELECT coldfront.create_iceberg_table(
     {"name": "id",   "type": "bigint"},
     {"name": "ts",   "type": "timestamptz"},
     {"name": "note", "type": "text"}
-  ]'::jsonb);
+  ]'::jsonb,
+  '{month(ts)}');
 
 INSERT INTO public.s3_demo VALUES (1, now(), 'hello from S3');
 INSERT INTO public.s3_demo VALUES (2, now(), 'second row');
diff --git a/docs/usage.md b/docs/usage.md
index 6edf595..e93e1de 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -197,10 +197,24 @@ SELECT coldfront.create_iceberg_table(
       {"name":"ts",     "type":"timestamptz"},
       {"name":"status", "type":"text"},
       {"name":"data",   "type":"jsonb"}
-    ]'::jsonb
+    ]'::jsonb,
+    p_partition_cols => '{month(ts)}'
 );
 ```
 
+`p_partition_cols` partitions the Iceberg table, here by the month of
+`ts`: each month's rows land in their own data files, and a query with a
+time filter skips the months outside it before reading anything. Each
+element is one term as DuckDB's `PARTITIONED BY` takes it: a column name,
+`year(col)`, `month(col)`, `day(col)` or `hour(col)` on a timestamp or
+date column, `bucket(N, col)` or `truncate(W, col)`; `'{month(ts),
+region}'` partitions by both. The argument is a PostgreSQL array
+literal, so a term that contains a comma is double-quoted inside it, the
+comma being the array's delimiter: `'{"bucket(16, id)"}'`. A column name
+that itself needs double quotes carries them backslashed inside such an
+element: `'{"month(\"Event Time\")"}'`. Leave the argument out for an
+unpartitioned table.
+
 That single statement provisions:
 
 - `ice.public.events` on the attached Iceberg catalog
diff --git a/docs/usage_vectors.md b/docs/usage_vectors.md
index 6c678ef..dd90f92 100644
--- a/docs/usage_vectors.md
+++ b/docs/usage_vectors.md
@@ -129,6 +129,13 @@ Choosing `nlist` is a floor rather than a formula: aim for at least one row
 group's worth of rows per cluster, roughly 2048. Below that, extra clusters stop
 reducing the data read. Above it there is a wide plateau.
 
+**Time partitioning.** A tiered vector table is partitioned by time, because
+its hot table is; a decoupled one only if it was created with time partitioning
+(`p_partition_cols`). On such a table a search with a time filter skips the
+months outside it, and a search over all of history reads one row group of each
+probed cluster per month rather than one, roughly the number of months more
+data. A decoupled vector table created without time partitioning is unaffected.
+
 ### Choosing `nprobe`
 
 `nprobe` is how many clusters a search reads, and it is the dial between recall and
diff --git a/extension/coldfront/Makefile b/extension/coldfront/Makefile
index 8fcec17..2c413fd 100644
--- a/extension/coldfront/Makefile
+++ b/extension/coldfront/Makefile
@@ -28,7 +28,8 @@ REGRESS     = load_order update_unregistered_view update_heap_table \
               read_date_bin read_json_builders read_param_fold registry_snapshot \
               adopt_type_map adopt_read_only adopt_iceberg_table \
               cold_write_json_agg duckdb_temp_dir \
-              vector_centroids vector_type_map vector_cold_render vector_param_render vector_ops vector_probe vector_status vector_assign vector_multicolumn
+              vector_centroids vector_type_map vector_cold_render vector_param_render vector_ops vector_probe vector_status vector_assign vector_multicolumn \
+              partition_clause
 REGRESS_OPTS = --inputdir=test --outputdir=test
 
 PG_CONFIG  ?= pg_config
diff --git a/extension/coldfront/coldfront--1.0.sql b/extension/coldfront/coldfront--1.0.sql
index b3ee1c8..6fa5f98 100644
--- a/extension/coldfront/coldfront--1.0.sql
+++ b/extension/coldfront/coldfront--1.0.sql
@@ -2336,19 +2336,23 @@ $$;
 -- the compactor already has: it creates nothing, it preserves what it finds.
 --
 -- The file target is large because on object storage every file a query touches is
--- a billed round trip. The sort key is what lets a compaction concatenate a
--- group's files in key order rather than scrambling them.
+-- a billed round trip. A partitioned table is created without it: DuckDB refuses
+-- the property on a partitioned table, and would not split its files by size
+-- there anyway; the compactor takes its target from --target-size-mb. The sort
+-- key is what lets a compaction concatenate a group's files in key order rather
+-- than scrambling them.
 --
 -- Set at CREATE TABLE: the catalog takes properties there, and this build has no
 -- ALTER for them, so a table that predates its vector column keeps the defaults.
-CREATE OR REPLACE FUNCTION coldfront._vec_layout_props(p_sort_key text)
+CREATE OR REPLACE FUNCTION coldfront._vec_layout_props(p_sort_key text, p_partitioned boolean)
 RETURNS text
 LANGUAGE sql IMMUTABLE PARALLEL SAFE AS $$
     SELECT CASE WHEN p_sort_key IS NULL OR p_sort_key = '' THEN ''
                 ELSE format(
-                    ' WITH (%L=%L, %L=%L, %L=%L)',
+                    ' WITH (%L=%L, %s%L=%L)',
                     'write.parquet.row-group-limit',      coldfront._vec_row_group_limit()::text,
-                    'write.target-file-size-bytes',       '536870912',
+                    CASE WHEN p_partitioned THEN ''
+                         ELSE format('%L=%L, ', 'write.target-file-size-bytes', '536870912') END,
                     'coldfront.sort-key',                 p_sort_key)
            END;
 $$;
@@ -3096,6 +3100,51 @@ BEGIN
 END;
 $$;
 
+-- The PARTITIONED BY clause a decoupled table is created with, or '' for none.
+-- Each element of p_partition_cols is one term as DuckDB takes it: a column name,
+-- year|month|day|hour(col), bucket(N, col) or truncate(W, col), joined as given.
+-- The engine judges them at CREATE TABLE: an unknown transform, a bad argument or
+-- a column not in the schema is refused there. The one check it leaves to the
+-- first INSERT is made here instead, while the table does not exist yet: a time
+-- transform on a column that is not a timestamp or date (for hour, a timestamp)
+-- binds against the wrong type and fails every write to the table. The column is
+-- matched the way the engine matches it, case-insensitively, quoted or not.
+CREATE OR REPLACE FUNCTION coldfront._partition_clause(p_columns jsonb, p_partition_cols text[])
+RETURNS text
+LANGUAGE plpgsql IMMUTABLE AS $$
+DECLARE
+    term      text;
+    m         text[];
+    transform text;
+    col_name  text;
+    col_type  text;
+    storage   text;
+BEGIN
+    IF p_partition_cols IS NULL OR cardinality(p_partition_cols) = 0 THEN
+        RETURN '';
+    END IF;
+    FOREACH term IN ARRAY p_partition_cols LOOP
+        m := regexp_match(term, '^\s*(year|month|day|hour)\s*\(\s*("(?:[^"]|"")*"|[^\s()"]+)\s*\)\s*$', 'i');
+        CONTINUE WHEN m IS NULL;
+        transform := lower(m[1]);
+        col_name  := CASE WHEN m[2] LIKE '"%'
+                          THEN replace(substr(m[2], 2, length(m[2]) - 2), '""', '"')
+                          ELSE m[2] END;
+        SELECT c->>'type' INTO col_type
+          FROM jsonb_array_elements(p_columns) AS c
+         WHERE lower(c->>'name') = lower(col_name);
+        CONTINUE WHEN col_type IS NULL;
+        storage := coldfront._iceberg_storage_type(col_type);
+        IF NOT (storage IN ('TIMESTAMPTZ', 'TIMESTAMP') OR (storage = 'DATE' AND transform <> 'hour')) THEN
+            RAISE EXCEPTION 'coldfront.create_iceberg_table: p_partition_cols term % needs a % column; "%" is %',
+                term, CASE WHEN transform = 'hour' THEN 'timestamp' ELSE 'timestamp or date' END,
+                col_name, col_type;
+        END IF;
+    END LOOP;
+    RETURN ' PARTITIONED BY (' || array_to_string(p_partition_cols, ', ') || ')';
+END;
+$$;
+
 -- create_iceberg_table: provision an iceberg-only table end-to-end.
 --
 --   p_schema         PG schema for the wrapper view (e.g. 'public').
@@ -3103,7 +3152,10 @@ $$;
 --                    created at ice.<p_schema>.<p_table>.
 --   p_columns        jsonb array of {name, type} entries. Type is a PG type
 --                    name from the supported set; see _iceberg_storage_type.
---   p_partition_cols array of column names for Iceberg partitioning, or NULL.
+--   p_partition_cols Iceberg partitioning, one PARTITIONED BY term per element as
+--                    DuckDB takes it (a column name, year|month|day|hour(col),
+--                    bucket(N, col), truncate(W, col)); see _partition_clause.
+--                    NULL or empty creates the table unpartitioned.
 --
 -- Effects:
 --   1. Creates the Iceberg table via duckdb.raw_query('CREATE TABLE ice...').
@@ -3123,6 +3175,7 @@ DECLARE
     v_view_cols      jsonb := '[]'::jsonb;
     v_vec_cols       text[] := '{}';
     v_cluster_cols   text;
+    v_part           text;
     v_props          text := '';
     n                int  := 0;
     col              jsonb;
@@ -3173,6 +3226,8 @@ BEGIN
                                             storage_type));
     END LOOP;
 
+    v_part := coldfront._partition_clause(p_columns, p_partition_cols);
+
     -- The cluster columns lead the Iceberg schema, one per vector column and in the
     -- order they were declared; the view projection deliberately skips them. A
     -- decoupled INSERT is rewritten in C, which is where their values come from.
@@ -3185,26 +3240,19 @@ BEGIN
         iceberg_cols := v_cluster_cols || iceberg_cols;
         -- No primary key is declared in this mode, so the cluster column alone.
         v_props := coldfront._vec_layout_props(
-                       coldfront._vec_sort_key(v_vec_cols[1], NULL));
-    END IF;
-
-    -- p_partition_cols is accepted and ignored: this helper declares no partition
-    -- spec, so the table is unpartitioned and predicate pushdown comes from
-    -- Parquet row-group min/max statistics alone. A table that needs a spec is
-    -- created with one on the catalog and brought in with adopt_iceberg_table.
-    IF p_partition_cols IS NOT NULL AND array_length(p_partition_cols, 1) > 0 THEN
-        RAISE NOTICE 'coldfront.create_iceberg_table: p_partition_cols=% accepted but ignored; the table is created unpartitioned', p_partition_cols;
+                       coldfront._vec_sort_key(v_vec_cols[1], NULL), v_part <> '');
     END IF;
 
     -- 1. Iceberg table on the attached catalog (create namespace first;
     -- CREATE SCHEMA IF NOT EXISTS is idempotent and cheap on Lakekeeper).
     -- IF NOT EXISTS on the table itself makes the helper safe to call again
     -- against an existing table — useful for distributed setups where each
-    -- node registers the same shared Iceberg table independently.
+    -- node registers the same shared Iceberg table independently. PARTITIONED BY
+    -- precedes WITH, as DuckDB parses the statement.
     PERFORM coldfront.ensure_attached();
     PERFORM duckdb.raw_query(format('CREATE SCHEMA IF NOT EXISTS ice.%I', p_schema));
     PERFORM duckdb.raw_query(format(
-        'CREATE TABLE IF NOT EXISTS %s (%s)%s', ice_ref, iceberg_cols, v_props));
+        'CREATE TABLE IF NOT EXISTS %s (%s)%s%s', ice_ref, iceberg_cols, v_part, v_props));
 
     -- 2. PG wrapper view + registry row. From here the C post_parse_analyze hook
     --    intercepts INSERT INTO the view (see coldfront.c emit_cold /
diff --git a/extension/coldfront/test/expected/partition_clause.out b/extension/coldfront/test/expected/partition_clause.out
new file mode 100644
index 0000000..a9284d8
--- /dev/null
+++ b/extension/coldfront/test/expected/partition_clause.out
@@ -0,0 +1,89 @@
+-- The PARTITIONED BY clause a decoupled table is created with, and the vector
+-- layout properties beside it. Both are text the CREATE TABLE is built from, so they
+-- are asserted here; the tables themselves are asserted in ci/journey.sh against a
+-- real catalog, which pg_regress does not have.
+--
+-- Suppress the run-order-dependent "already exists" NOTICE: in the shared regress
+-- db an earlier test may have created the extensions, standalone not.
+SET client_min_messages = warning;
+CREATE EXTENSION IF NOT EXISTS pg_duckdb;
+CREATE EXTENSION IF NOT EXISTS coldfront;
+RESET client_min_messages;
+-- Each element is one DuckDB PARTITIONED BY term, joined as given.
+SELECT coldfront._partition_clause(
+           '[{"name":"ts","type":"timestamptz"},{"name":"region","type":"text"}]',
+           '{month(ts), region}') AS clause;
+               clause                
+-------------------------------------
+  PARTITIONED BY (month(ts), region)
+(1 row)
+
+-- No terms, no clause: the table is created unpartitioned.
+SELECT coldfront._partition_clause('[{"name":"ts","type":"timestamptz"}]', NULL) = ''
+    AS null_terms;
+ null_terms 
+------------
+ t
+(1 row)
+
+SELECT coldfront._partition_clause('[{"name":"ts","type":"timestamptz"}]', '{}') = ''
+    AS empty_terms;
+ empty_terms 
+-------------
+ t
+(1 row)
+
+-- A time transform takes a timestamp or date column. The engine finds the column
+-- whatever its case, quoted or not, and so does the check. An element that holds
+-- double quotes is itself double-quoted in the array literal, with the inner
+-- quotes backslashed, as PostgreSQL reads array literals.
+SELECT coldfront._partition_clause('[{"name":"d","type":"date"}]', '{DAY(d)}') AS on_date;
+         on_date          
+--------------------------
+  PARTITIONED BY (DAY(d))
+(1 row)
+
+SELECT coldfront._partition_clause('[{"name":"Ts","type":"timestamp"}]', '{"hour(\"Ts\")"}')
+    AS on_timestamp;
+         on_timestamp         
+------------------------------
+  PARTITIONED BY (hour("Ts"))
+(1 row)
+
+-- Anything else is refused while the table does not exist yet: the engine accepts
+-- the term at CREATE and then fails every write. hour needs a time of day.
+SELECT coldfront._partition_clause('[{"name":"Status","type":"text"}]', '{"month(\"Status\")"}');
+ERROR:  coldfront.create_iceberg_table: p_partition_cols term month("Status") needs a timestamp or date column; "Status" is text
+CONTEXT:  PL/pgSQL function _partition_clause(jsonb,text[]) line 26 at RAISE
+SELECT coldfront._partition_clause('[{"name":"d","type":"date"}]', '{hour(d)}');
+ERROR:  coldfront.create_iceberg_table: p_partition_cols term hour(d) needs a timestamp column; "d" is date
+CONTEXT:  PL/pgSQL function _partition_clause(jsonb,text[]) line 26 at RAISE
+-- Every other term reaches the engine as written, which judges it. An element with
+-- a comma in it is double-quoted, or the comma splits it.
+SELECT coldfront._partition_clause('[{"name":"id","type":"bigint"}]',
+                                   '{"bucket(16, id)", bogus(id)}') AS passed_through;
+               passed_through                
+---------------------------------------------
+  PARTITIONED BY (bucket(16, id), bogus(id))
+(1 row)
+
+-- A clustered table's layout properties. The file-size target goes only on an
+-- unpartitioned table: the engine refuses it on a partitioned one.
+SELECT coldfront._vec_layout_props('_cf_vec_list_e,id', false) AS unpartitioned;
+                                                            unpartitioned                                                             
+--------------------------------------------------------------------------------------------------------------------------------------
+  WITH ('write.parquet.row-group-limit'='2048', 'write.target-file-size-bytes'='536870912', 'coldfront.sort-key'='_cf_vec_list_e,id')
+(1 row)
+
+SELECT coldfront._vec_layout_props('_cf_vec_list_e,id', true) AS partitioned;
+                                       partitioned                                        
+------------------------------------------------------------------------------------------
+  WITH ('write.parquet.row-group-limit'='2048', 'coldfront.sort-key'='_cf_vec_list_e,id')
+(1 row)
+
+SELECT coldfront._vec_layout_props(NULL, true) = '' AS no_vector;
+ no_vector 
+-----------
+ t
+(1 row)
+
diff --git a/extension/coldfront/test/sql/partition_clause.sql b/extension/coldfront/test/sql/partition_clause.sql
new file mode 100644
index 0000000..4d68499
--- /dev/null
+++ b/extension/coldfront/test/sql/partition_clause.sql
@@ -0,0 +1,46 @@
+-- The PARTITIONED BY clause a decoupled table is created with, and the vector
+-- layout properties beside it. Both are text the CREATE TABLE is built from, so they
+-- are asserted here; the tables themselves are asserted in ci/journey.sh against a
+-- real catalog, which pg_regress does not have.
+--
+-- Suppress the run-order-dependent "already exists" NOTICE: in the shared regress
+-- db an earlier test may have created the extensions, standalone not.
+SET client_min_messages = warning;
+CREATE EXTENSION IF NOT EXISTS pg_duckdb;
+CREATE EXTENSION IF NOT EXISTS coldfront;
+RESET client_min_messages;
+
+-- Each element is one DuckDB PARTITIONED BY term, joined as given.
+SELECT coldfront._partition_clause(
+           '[{"name":"ts","type":"timestamptz"},{"name":"region","type":"text"}]',
+           '{month(ts), region}') AS clause;
+
+-- No terms, no clause: the table is created unpartitioned.
+SELECT coldfront._partition_clause('[{"name":"ts","type":"timestamptz"}]', NULL) = ''
+    AS null_terms;
+SELECT coldfront._partition_clause('[{"name":"ts","type":"timestamptz"}]', '{}') = ''
+    AS empty_terms;
+
+-- A time transform takes a timestamp or date column. The engine finds the column
+-- whatever its case, quoted or not, and so does the check. An element that holds
+-- double quotes is itself double-quoted in the array literal, with the inner
+-- quotes backslashed, as PostgreSQL reads array literals.
+SELECT coldfront._partition_clause('[{"name":"d","type":"date"}]', '{DAY(d)}') AS on_date;
+SELECT coldfront._partition_clause('[{"name":"Ts","type":"timestamp"}]', '{"hour(\"Ts\")"}')
+    AS on_timestamp;
+
+-- Anything else is refused while the table does not exist yet: the engine accepts
+-- the term at CREATE and then fails every write. hour needs a time of day.
+SELECT coldfront._partition_clause('[{"name":"Status","type":"text"}]', '{"month(\"Status\")"}');
+SELECT coldfront._partition_clause('[{"name":"d","type":"date"}]', '{hour(d)}');
+
+-- Every other term reaches the engine as written, which judges it. An element with
+-- a comma in it is double-quoted, or the comma splits it.
+SELECT coldfront._partition_clause('[{"name":"id","type":"bigint"}]',
+                                   '{"bucket(16, id)", bogus(id)}') AS passed_through;
+
+-- A clustered table's layout properties. The file-size target goes only on an
+-- unpartitioned table: the engine refuses it on a partitioned one.
+SELECT coldfront._vec_layout_props('_cf_vec_list_e,id', false) AS unpartitioned;
+SELECT coldfront._vec_layout_props('_cf_vec_list_e,id', true) AS partitioned;
+SELECT coldfront._vec_layout_props(NULL, true) = '' AS no_vector;

From 7144d5df44b1104b730e75cb259134b3db4a416e Mon Sep 17 00:00:00 2001
From: Jimmy Angelakos <jimmy@pgedge.com>
Date: Fri, 25 Sep 2026 19:28:02 +0100
Subject: [PATCH 4/5] fix: match a position delete on spec id and partition
 values

---
 DUCKDB_1.5_PATCHED.md         |  4 +--
 DUCKDB_1.5_UNPATCHED.md       |  5 ++-
 cmd/compactor/compact.go      | 44 ++++++++++++++++---------
 cmd/compactor/compact_test.go | 61 ++++++++++++++++++++++++-----------
 4 files changed, 78 insertions(+), 36 deletions(-)

diff --git a/DUCKDB_1.5_PATCHED.md b/DUCKDB_1.5_PATCHED.md
index 73f26d3..1353d4e 100644
--- a/DUCKDB_1.5_PATCHED.md
+++ b/DUCKDB_1.5_PATCHED.md
@@ -172,8 +172,8 @@ commit-time 403 from missing storage credentials on the commit connection does
 not arise in v1.5. Do
 **not** rewrite `Commit` to run under the caller's `ClientContext`: on the
 deferred `PRE_COMMIT` callback that context has no active transaction and throws
-`ActiveTransaction called without active transaction`. Build the bakery + interop
-patches only.
+`ActiveTransaction called without active transaction`. Build the four carried
+patches (bakery, the two interop patches, the UTC transform port) only.
 
 ---
 
diff --git a/DUCKDB_1.5_UNPATCHED.md b/DUCKDB_1.5_UNPATCHED.md
index f67b492..cca0516 100644
--- a/DUCKDB_1.5_UNPATCHED.md
+++ b/DUCKDB_1.5_UNPATCHED.md
@@ -86,7 +86,10 @@ cold writer, the archiver included, has to run with `TimeZone = 'UTC'`.
 - You don't run the compactor (low cold-write volume, or you compact externally
   with Spark/Trino/PyIceberg — which *may* tolerate stock duckdb-iceberg
   manifests), **and**
-- you don't need the contended-upload throughput (low write concurrency).
+- you don't need the contended-upload throughput (low write concurrency),
+  **and**
+- every cold writer, the archiver included, runs with `TimeZone = 'UTC'`
+  (Consequence 3: every tiered cold table is partitioned by time).
 
 Otherwise run the patched base ([DUCKDB_1.5_PATCHED.md](DUCKDB_1.5_PATCHED.md)) —
 the default.
diff --git a/cmd/compactor/compact.go b/cmd/compactor/compact.go
index 3db50c8..37deb89 100644
--- a/cmd/compactor/compact.go
+++ b/cmd/compactor/compact.go
@@ -208,26 +208,26 @@ func planCompaction(ctx context.Context, cat *rest.Catalog, ns, name string, tar
 	return tbl, &planResult{groups: groups, plan: plan, sorted: sorted, sortKey: sortKey}, nil
 }
 
-// scopeDeletes keeps, for each data file, only the position-delete files that can
-// reference its rows under the Iceberg spec: those of its own partition, and
-// those of no partition. iceberg-go v0.6.0 attaches position deletes by sequence
-// number and the delete file's file_path bounds alone (table/scanner.go,
-// matchDeletesToData), never by partition, and duckdb-iceberg 5edc45f0 writes
-// those bounds under DuckDB's FILENAME_FIELD_ID (2147483646) rather than the
-// spec's file_path field (2147483546), so every delete file is attached to every
-// data file: one delete file then sits in several partition groups, which
-// ReplaceFiles refuses, and rewriting one partition would remove the delete
-// files of a partition the planner skipped, resurrecting its deleted rows.
-// TC-190 in ci/journey.sh asserts the engine's bound key; when it moves to the
-// spec's field, or iceberg-go matches by partition, this keeps what iceberg-go
-// already kept and can go.
+// scopeDeletes keeps, for each data file, only the position-delete files of its
+// own partition, spec id and partition values both, which is the scope the
+// Iceberg spec gives a position delete (only an equality delete with an
+// unpartitioned spec is global). iceberg-go v0.6.0 attaches position deletes by
+// sequence number and the delete file's file_path bounds alone
+// (table/scanner.go, matchDeletesToData), never by partition, and duckdb-iceberg
+// 5edc45f0 writes those bounds under DuckDB's FILENAME_FIELD_ID (2147483646)
+// rather than the spec's file_path field (2147483546), so every delete file is
+// attached to every data file: one delete file then sits in several partition
+// groups, which ReplaceFiles refuses, and rewriting one partition would remove
+// the delete files of a partition the planner skipped, resurrecting its deleted
+// rows. TC-190 in ci/journey.sh asserts the engine's bound key; when it moves to
+// the spec's field, or iceberg-go matches by partition, this keeps what
+// iceberg-go already kept and can go.
 func scopeDeletes(tasks []table.FileScanTask) []table.FileScanTask {
 	out := make([]table.FileScanTask, 0, len(tasks))
 	for _, task := range tasks {
-		own := task.File.Partition()
 		kept := make([]iceberg.DataFile, 0, len(task.DeleteFiles))
 		for _, df := range task.DeleteFiles {
-			if len(df.Partition()) == 0 || reflect.DeepEqual(df.Partition(), own) {
+			if df.SpecID() == task.File.SpecID() && samePartition(df.Partition(), task.File.Partition()) {
 				kept = append(kept, df)
 			}
 		}
@@ -237,6 +237,20 @@ func scopeDeletes(tasks []table.FileScanTask) []table.FileScanTask {
 	return out
 }
 
+// samePartition compares two partition tuples by field id and value; a nil map
+// and an empty one are the same unpartitioned tuple.
+func samePartition(a, b map[int]any) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for k, v := range a {
+		if w, ok := b[k]; !ok || !reflect.DeepEqual(v, w) {
+			return false
+		}
+	}
+	return true
+}
+
 // rewrite executes the planned compaction as a single atomic rewrite snapshot
 // and commits it to the catalog.
 //
diff --git a/cmd/compactor/compact_test.go b/cmd/compactor/compact_test.go
index 5e3befb..622b281 100644
--- a/cmd/compactor/compact_test.go
+++ b/cmd/compactor/compact_test.go
@@ -76,30 +76,55 @@ func deleteFile(t *testing.T, spec iceberg.PartitionSpec, path string, partition
 	return b.Build()
 }
 
-// A data file keeps only the position-delete files that can reference its rows:
-// those of its own partition, and those of no partition at all. Every other
-// delete file is one iceberg-go attached by sequence number alone.
-func TestScopeDeletes(t *testing.T) {
-	spec := iceberg.NewPartitionSpec(iceberg.PartitionField{
-		SourceIDs: []int{2}, FieldID: 1000, Name: "month_ts_2", Transform: iceberg.MonthTransform{}})
-	march, april := map[int]any{1000: int32(674)}, map[int]any{1000: int32(675)}
-	data, err := iceberg.NewDataFileBuilder(spec, iceberg.EntryContentData, "data/month_ts_2=674/d.parquet",
-		iceberg.ParquetFile, march, nil, nil, 10, 1000)
+// dataFile builds a data-file manifest entry in the given partition.
+func dataFile(t *testing.T, spec iceberg.PartitionSpec, path string, partition map[int]any) iceberg.DataFile {
+	t.Helper()
+	b, err := iceberg.NewDataFileBuilder(spec, iceberg.EntryContentData, path, iceberg.ParquetFile,
+		partition, nil, nil, 10, 1000)
 	if err != nil {
 		t.Fatal(err)
 	}
-	own := deleteFile(t, spec, "data/month_ts_2=674/own-deletes.parquet", march)
-	other := deleteFile(t, spec, "data/month_ts_2=675/other-deletes.parquet", april)
-	global := deleteFile(t, spec, "data/global-deletes.parquet", map[int]any{})
-
-	tasks := scopeDeletes([]table.FileScanTask{{File: data.Build(), DeleteFiles: []iceberg.DataFile{other, own, global}}})
+	return b.Build()
+}
 
-	got := make([]string, 0, 2)
+// keptPaths runs scopeDeletes over one data file and returns the paths of the
+// delete files it kept.
+func keptPaths(data iceberg.DataFile, deletes ...iceberg.DataFile) []string {
+	tasks := scopeDeletes([]table.FileScanTask{{File: data, DeleteFiles: deletes}})
+	got := make([]string, 0, len(deletes))
 	for _, df := range tasks[0].DeleteFiles {
 		got = append(got, df.FilePath())
 	}
-	want := []string{"data/month_ts_2=674/own-deletes.parquet", "data/global-deletes.parquet"}
-	if len(got) != len(want) || got[0] != want[0] || got[1] != want[1] {
-		t.Fatalf("kept %v, want %v", got, want)
+	return got
+}
+
+// A data file keeps only the position-delete files of its own partition, spec
+// id and values both, as the Iceberg spec scopes them. Every other delete file is
+// one iceberg-go attached by sequence number alone.
+func TestScopeDeletes(t *testing.T) {
+	month := iceberg.PartitionField{SourceIDs: []int{2}, FieldID: 1000, Name: "month_ts_2",
+		Transform: iceberg.MonthTransform{}}
+	spec, later := iceberg.NewPartitionSpecID(1, month), iceberg.NewPartitionSpecID(2, month)
+	march, april := map[int]any{1000: int32(674)}, map[int]any{1000: int32(675)}
+	data := dataFile(t, spec, "data/month_ts_2=674/d.parquet", march)
+
+	got := keptPaths(data,
+		deleteFile(t, spec, "data/month_ts_2=675/other-month.parquet", april),
+		deleteFile(t, spec, "data/month_ts_2=674/own.parquet", march),
+		deleteFile(t, spec, "data/no-partition.parquet", map[int]any{}),
+		deleteFile(t, later, "data/month_ts_2=674/other-spec.parquet", march))
+	if len(got) != 1 || got[0] != "data/month_ts_2=674/own.parquet" {
+		t.Fatalf("kept %v, want the own-partition delete file alone", got)
+	}
+}
+
+// An unpartitioned table is one partition: its delete files apply to its data
+// files whether the partition map is nil or empty.
+func TestScopeDeletes_Unpartitioned(t *testing.T) {
+	spec := iceberg.NewPartitionSpecID(0)
+	got := keptPaths(dataFile(t, spec, "data/d.parquet", nil),
+		deleteFile(t, spec, "data/deletes.parquet", map[int]any{}))
+	if len(got) != 1 {
+		t.Fatalf("kept %v, want the delete file", got)
 	}
 }

From cbfe2a9255a8a8acb82dcadb9f2fb9aa14e157b9 Mon Sep 17 00:00:00 2001
From: Jimmy Angelakos <jimmy@pgedge.com>
Date: Fri, 25 Sep 2026 20:19:20 +0100
Subject: [PATCH 5/5] test: assert a time band skips the row groups outside it

---
 ci/journey.sh | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/ci/journey.sh b/ci/journey.sh
index 5896a35..f38537f 100755
--- a/ci/journey.sh
+++ b/ci/journey.sh
@@ -5774,6 +5774,33 @@ EOF
     q "$HOST" "SELECT coldfront.drop_iceberg_table('public','tccomp', true);" >/dev/null 2>&1
 }
 
+# ───────────────────────────────────────────────────────────────────────────
+# Story TC-192: row-group skipping. A time band over a cold table reads only the
+# Parquet row groups whose statistics can match it. Every cold-read speedup
+# inside a file rests on DuckDB core handing the filter to the Parquet reader,
+# which nothing upstream states as a contract, so the counters DuckDB keeps for
+# it are asserted here, from the JSON profile of a read through the view. Both
+# modes, on its own throwaway table.
+# ───────────────────────────────────────────────────────────────────────────
+story_row_group_pruning() {
+    step "TC-192: a time band skips the row groups outside it"
+    local m="(date_trunc('month', now() AT TIME ZONE 'UTC') AT TIME ZONE 'UTC') - interval '2 months'"
+    q "$HOST" "SELECT coldfront.create_iceberg_table('public','tcrg','[{\"name\":\"id\",\"type\":\"bigint\"},{\"name\":\"ts\",\"type\":\"timestamptz\"},{\"name\":\"v\",\"type\":\"integer\"}]'::jsonb, '{month(ts)}');" >/dev/null 2>&1
+    # 300,000 rows one second apart, three and a half days inside one month: one
+    # file, several row groups, each covering its own span of ts.
+    q "$HOST" "INSERT INTO public.tcrg SELECT i, ($m) + (i * interval '1 second'), i FROM generate_series(1, 300000) i;" >/dev/null 2>&1
+    assert_eq "TC-192: 300,000 rows in one file" "1" "$(ice_files ice.public.tcrg '\.parquet')"
+    # One session: the profile settings, the read, and the profile it wrote. The
+    # ICEBERG_SCAN node carries the row-group counters.
+    local counters
+    counters=$(q "$HOST" "SELECT duckdb.raw_query('SET custom_profiling_settings = ''{\"OPERATOR_TYPE\": \"true\", \"OPERATOR_ROW_GROUPS_SCANNED\": \"true\", \"OPERATOR_TOTAL_ROW_GROUPS_TO_SCAN\": \"true\"}'''); SELECT duckdb.raw_query('SET enable_profiling = ''json'''); SELECT duckdb.raw_query('SET profiling_output = ''/tmp/tc192.json'''); SELECT count(*) FROM public.tcrg WHERE ts >= ($m) + interval '1 hour' AND ts < ($m) + interval '2 hours'; SELECT duckdb.raw_query('SET enable_profiling = ''no_output'''); SELECT (j->>'operator_row_groups_scanned') || ' ' || (j->>'operator_total_row_groups_to_scan') FROM jsonb_path_query_first(pg_read_file('/tmp/tc192.json')::jsonb, '\$.** ? (@.operator_name == \"ICEBERG_SCAN\")') AS j;" | tail -1)
+    local scanned=${counters% *} total=${counters#* }
+    assert_gt "TC-192: the file holds more than one row group" 1 "$total"
+    assert_gt "TC-192: the band read at least one row group" 0 "$scanned"
+    assert_gt "TC-192: the band skipped the row groups outside it" "$scanned" "$total"
+    q "$HOST" "SELECT coldfront.drop_iceberg_table('public','tcrg', true);" >/dev/null 2>&1
+}
+
 # ── orchestrate ────────────────────────────────────────────────────────────
 # Setup is shared. The story set then branches on mode: tiered exercises the
 # hot+cold partitioned path; decoupled exercises the all-Iceberg wrapper. (The
@@ -5866,6 +5893,7 @@ fi
 story_duckdb_temp_dirs     # TC-152: per-backend spill dir; departed backends' spills reclaimed
 story_duckdb_spill_concurrency  # TC-153: four sessions spilling at once stay isolated and correct
 story_partitioned_cold_tables  # TC-186..TC-189: partition fan-out, UTC months, refusals, manifest skipping
+story_row_group_pruning        # TC-192: a time band skips the row groups outside it
 story_drop_iceberg_table   # both modes, purge and keep-files (own throwaway tables)
 [ "$MESH" = 1 ] && [ "$MODE" = decoupled ] && story_mesh   # tiered+mesh runs story_mesh_tiered (above)
 [ "$MESH" = 1 ] && story_mesh_multiwriter   # >1 cold writer/node cross-node (tiered: events, decoupled: iceonly)