Hilbert curve clustering: a second key kind for cluster and recluster (1.0-alpha4)

[jdatcmd]

Alpha4's first item, from design/RELEASE_PLAN_1.0.md:96. Target 2026-09-15.

Why it is this release or 2.0. Clustering by a new key kind is user-visible surface, and the
plan's governing rule is that beta 1 takes no new surface. There is no later alpha to catch it.

Everything below marked verified was read or run against main 9628414 today. The surface
probes were run on PostgreSQL 18.4. Nothing here restates the release plan as fact.

What already exists, and exactly where Hilbert would attach

Verified. Z-order clustering ships and the whole mechanism is four steps in
src/columnar_vacuum.c:

1. cluster_type_ordinal(value, typid) maps one column value to an order-preserving uint64.
2. cluster_zorder_key() (:1046) interleaves the per-column ordinals MSB-first into an
   ncols * 8-byte bytea, so that memcmp order over the bytea equals Z-order.
3. The rewrite sorts on that bytea as an appended __zorder attribute (:687, :714).
4. record_sorted_extent(..., "zorder") (:772, :1564) records the key kind in the storage
   catalog (Anum_native_storage_sorted_kind, src/columnar_metadata.c:80).

So the swap point is step 2 alone. A Hilbert build takes the same ord[] array and produces
a different bytea whose memcmp order is Hilbert order. Steps 1, 3 and 4 are untouched apart
from the recorded kind string. The release plan's "the same machinery" is accurate, and this is
the line that makes it so.

Verified — the supported key types are fixed by step 1 and Hilbert inherits them exactly:
bool, int2, int4, int8, date, timestamp, timestamptz, float4, float8
(cluster_type_supported, src/columnar_vacuum.c:1020). Anything else already raises 0A000 with a hint
naming Z-order, and that hint's wording will need to stop being Z-order-specific.

The surface question is not a matter of taste, and two of the three options are already ruled out by measurement

pgcolumnar.cluster and pgcolumnar.recluster both take (tablename regclass, VARIADIC columns name[])
(pgcolumnar--1.0-alpha3.sql:939, :976). Neither takes a key kind. Verified: that signature
cannot be extended in either direction. Run on 18.4:

CREATE FUNCTION probe_a(t regclass, kind text DEFAULT 'z', VARIADIC cols name[]) ...
ERROR:  input parameters after one with a default value must also have defaults

CREATE FUNCTION probe_b(t regclass, VARIADIC cols name[], kind text DEFAULT 'z') ...
ERROR:  VARIADIC parameter must be the last input parameter

Verified: adding an array-plus-kind overload beside the variadic one breaks the existing call
style. With both pc(regclass, VARIADIC name[]) and pc(regclass, name[], text DEFAULT ...)
defined, the call every current user writes stops resolving:

SELECT pc('probe_t','a','b');
ERROR:  function pc(unknown, unknown, unknown) is not unique
HINT:  Could not choose a best candidate function.

The array forms still resolve; the bare-name form does not. So overloading is not the
backward-compatible option it looks like.

That leaves three real choices, and this issue should not pick one silently:

option	cost
separate pgcolumnar.cluster_hilbert / recluster_hilbert	doubles the clustering surface; no ambiguity, no break
a GUC, e.g. pgcolumnar.cluster_kind	no signature change, but makes the key kind ambient state for something we record per storage as sorted_kind
replace the variadic signature with (regclass, name[], text DEFAULT 'zorder')	one clean surface; breaks every existing cluster('t','a','b') call, in an alpha

My recommendation is the first, on the grounds that the key kind is a property of the rewrite
being asked for and not of the session, but the owner should rule. Nothing else in this issue
depends on which is chosen, so the implementation can start on the key function while the
surface is decided.

Build it test-first

Write each arm, run it, and confirm it fails for the intended reason before writing the
production code.

Arm 1 — correctness before locality. A Hilbert-clustered table returns exactly the rows a
heap oracle returns, full-table and under range predicates on each key column. This is the arm
that must exist before any locality claim, because a key function that is merely a permutation
of the rows will pass every locality measurement and lose data. Red first with 42883
(function does not exist), asserted as SQLSTATE, not as error text.

Arm 2 — the property the feature is for, measured as work and not as intent. Hilbert exists
because it gives better locality than Z-order on the same machinery. The instrument must be
chunk groups touched by a range query, read from the skipping counters, not wall clock and
not a timing ratio — this box is not idle and a millisecond count here would measure the load,
not the layout. Compare Hilbert against Z-order on the same fixture, same key columns, same row
count.

Arm 3 — the negative control that makes arm 2 mean something. On a one-column key, Hilbert
and Z-order are the same curve and must touch the same number of groups. An arm 2 that reports
an improvement there is measuring something other than the curve.

Arm 4 — the kind is recorded and is not confusable with Z-order.
src/columnar_vacuum.c:646 reuses a recorded sorted run only when
strcmp(skind, "zorder") == 0. A Hilbert run must record 'hilbert' and must not satisfy
that test, or a Hilbert-ordered extent will be reused as if it were Z-ordered. Assert both
directions: the kind is 'hilbert' in pgcolumnar.stats, and a Hilbert extent does not take
the Z-order reuse path.

The removal proof for all of it. Delete the Hilbert key construction and keep the
Z-order one; arms 1, 2 and 4 must go red. If arm 2 stays green with the curve gone, it was
measuring the sort and not the curve, which is the failure mode this project keeps rediscovering.

State of knowledge

• Verified: the Z-order mechanism, the swap point, the supported key types, the recorded
  kind, the two signature refusals, and the overload ambiguity.
• Assumed: that a Hilbert index over ncols 64-bit ordinals is practical at this key width.
  A d-dimensional Hilbert index over 64-bit-per-dimension coordinates is a well-understood
  construction, but the ordinals here are full-width uint64 and the output must stay a
  memcmp-ordered bytea. Confirm the bit width before writing the loop.
• Unknown: how much better the locality actually is on our fixtures. The release plan says
  "better locality" and cites no measurement of ours. Arm 2 is what turns that into a number,
  and if the number is not an improvement, that is a result and this item should be reported
  rather than shipped quietly.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Unuuvh3fRR67SceiGpfeeK

[jdatcmd]

Taking this one. Lane declared so we do not collide: I am the jdatcmd session, container
pgcolumnar-dev, prefix /usr/local/pg18_assert. @OffgridwithJD is on #887 in
pgcolumnar-audit with /usr/local/pg{15..19}a. Separate containers, so no shared pkglibdir.

Surface decision, taken rather than deferred, since the owner asked for autonomous progress
and the issue records the evidence for it. Going with option 1: separate
pgcolumnar.cluster_hilbert and pgcolumnar.recluster_hilbert functions.

The reasoning, restated from the measurements in the issue body so it is not relitigated:

• Extending the existing signature is refused by PostgreSQL in both directions — a defaulted
  parameter cannot precede VARIADIC, and VARIADIC must be last.
• The array-plus-kind overload silently breaks cluster('t','a','b'), which is the documented
  call style, with function ... is not unique.
• A GUC would make the key kind ambient session state for something we record per storage as
  sorted_kind, so two identical calls in two sessions would produce differently ordered
  extents with nothing in the call to say so.

Separate functions cost surface area and nothing else. If the owner prefers a different option
the key-construction work is unaffected — only the SQL wrapper changes.

Order of work, test-first. The arms go in before the key function, and I will post the red
run here before any production code. Arm 2 (locality) will be measured as chunk groups touched,
never wall clock, for the reason recorded throughout this tracker: this box is not idle and a
second agent is building on the same host.

[jdatcmd]

Design pass done. Two findings change the shape of this issue, and one of them needs a ruling
before the feature can be called finished. No production code written yet — this is the
design record, and the test arms go in red next.

Method: four readers over the tree, three independent key constructions, each attacked by two
adversarial judges (mathematical correctness, implementability), then a synthesis. Where a number
below came from an agent's standalone C run rather than from this tree, it says so.

1. The blocker: a curve is not just a key, it is a gate, and the daemon will destroy it

pgcolumnar_recluster_online self-gates on strcmp(skind, "zorder") == 0
(src/columnar_vacuum.c:646), and "zorder" is written at :772 and :1564. That literal now
has to mean a curve, and every consumer of it has to learn there is a second one. I read these
sites myself. Three consequences, in descending severity:

• src/columnar_autovacuum.c:286-290 hard-codes SELECT pgcolumnar.recluster(%s, VARIADIC ...)
  over SPI. On a Hilbert-marked table that call falls through the 'zorder'-only gate, takes
  ShareUpdateExclusiveLock, does a full rewrite, and relabels the storage 'zorder'. The
  user's Hilbert layout is silently destroyed by a background daemon, with no error and no
  notice. This is the finding that matters most, and it is not fixed by adding a key function.
• vacuum_sorted_gate_is_noop (:1699) refuses anything that is not exactly 'lexicographic',
  so vacuum_sorted on a Hilbert table also does a full rewrite and relabels it. Same shape.
• If a Hilbert rewrite instead recorded 'zorder', a later recluster() over the same columns
  would match the gate and return 0, so the curve switch would silently never happen. The
  file's own comment at :1676-1679 says a re-sort by a new key must fall through; a different
  curve over the same columns is a new key and this gate cannot see it.

This needs a ruling and I am not taking it silently, because every option is user-visible:
refuse recluster() on a Hilbert table, warn and proceed, make the daemon curve-aware and
preserve the kind, or make the kind part of the daemon's stored intent. My recommendation is the
third — the daemon should re-apply the curve the table was clustered with — but that is a
behaviour decision for the owner.

Pre-existing hazard found alongside it: sorted_kind has no CHECK constraint
(pgcolumnar--1.0-alpha3.sql:210) and the literals are open-coded at five sites with no shared
#define. A typo is written silently and both self-gates then refuse forever, invisibly.

2. The locality claim may not be measurable, and the obvious fixture proves nothing

The instrument exists — Columnar Chunk Groups Read / Total / Removed by Filter
(src/columnar_customscan.c:3524-3530), consumed by 25 suites via the explain_num idiom. I
verified that independently. What does not exist is a fair comparison, and a judge measured
why:

• On a dense, power-of-two-aligned grid whose group size is a perfect dyadic sub-cube, Hilbert
  and Z-order produce the IDENTICAL row-to-group partition. Group-membership hashes matched
  256/256, 64/64 and 64/64. Only the order of groups differs, and chunk-group skipping does not
  depend on order, so the measured skip ratio was 1.0000 at every query box size.
  test/native_cluster.sh's fixture — 40960 rows, ((g*7919)%200, (g*104729)%200) on a dense
  200x200 grid, stripe_row_limit 2048, 20 dyadic groups — is close to exactly that degenerate
  case.
• Where a difference does appear: 200k sparse skewed rows with non-dyadic group sizes gave
  Z-order touching 1.40x / 1.70x / 1.73x as many groups as Hilbert at 2 / 3 / 4 columns.
• The untouched ordinal layer caps the benefit: matched int4 x int4 gives mean contiguous run
  7.14 vs 12.67 (1.8x), but bool x int4 gives 8.07 vs 8.10 — no win at all, because
  cluster_type_ordinal maps bool to bit 0 while integers centre on 2^63.

So a locality arm cannot be written first and cannot carry a threshold until a pilot runs on a
sparse, skewed, non-dyadic fixture. The pilot must assert, as a premise, that the two curves
produce a different group partition on that fixture — otherwise the comparison is arithmetic
on two identical numbers. If the pilot cannot separate them, "not measurable on our fixtures"
is the result I will report, not a threshold to lower. design/RELEASE_PLAN_1.0.md:96-97
asserts Hilbert "gives better locality" citing no measurement, and no absolute Z-order locality
figure is recorded anywhere in the repo, so there is no baseline either.

3. Also worth fixing: the existing locality arm's denominator is not fair

*groupsTotal = readState->groupsRead + readState->groupsSkipped
(src/columnar_reader.c:4470) — Total is a derived accounting identity, not the relation's group
count. An early-exiting query therefore gets a different denominator per arm, so a curve that
merely changes where the scan stops reads as a locality win. test/native_cluster.sh:79 also
retypes the denominator into prose ("of 20") instead of reading it from the plan. Pre-existing;
flagged rather than smuggled into this change.

The chosen construction

Skilling's AxesToTranspose transform feeding the existing packer, unchanged, in a new
src/columnar_curve.c / .h exposing two pure uint64-only functions:

void cluster_hilbert_transpose(uint64 *X, int ncols);   /* in place */
void cluster_pack_interleave(const uint64 *ord, int ncols, unsigned char *out);

cluster_pack_interleave is src/columnar_vacuum.c:1069-1077 moved verbatim. Skilling's
observation is that the Hilbert index is the MSB-round-first interleave of the transposed
ordinals — bit for bit the loop already in the tree. So:

cluster_zorder_key  = ordinals + pack
cluster_hilbert_key = ordinals + transpose + pack

Width is unchanged (8*ncols payload, 4+8*ncols varlena), so the bytea, the augmented
TupleDesc, byteaLt, tuplesort_begin_heap and PgColumnarWriteRow's natts loop are all
untouched. The shared ordinal prologue is extracted so cluster_type_ordinal and the NULL-to-0
rule stay single-sourced.

It won on evidence, not elegance: its ordering argument was checked by exhaustive all-pairs
memcmp-vs-index agreement (523,776 pairs at d=2 b=5; 8,386,560 each at d=3 b=4 and d=4 b=3; zero
disagreements), and it is the only candidate whose full-64-bit claim is an induction rather
than sampling — the frozen-prefix argument, that at level Q the loop reads only bit Q and writes
only bits below Q. The two state-machine alternatives left m -> 64 as an admitted unwritten
induction.

What is honestly unresolved

• Full-width correctness is an induction plus an exhaustive base case, not a machine-checked
  proof. At d=8 only the top 2 of 63 levels are exhaustively exercised.
• The curve is convention-dependent. Skilling's differs from Butz/Hamilton for ncols >= 3
  and both are valid — Hilbert curves are not unique above two dimensions. So the key bytes are
  an on-disk format commitment, and disagreement with another library is not evidence of a
  bug. It gets golden byte vectors, not a cross-implementation check.
• Per-row cost: two standalone A/Bs put the Hilbert key build at 3x to 4x the Z-order one.
  Wall clock is not fair on this host, so that number needs backend instruction counts inside
  PostgreSQL before it is quoted anywhere.
• Inherited ordinal defects are not fixed here: -0.0 and 0.0 get different ordinals though
  PostgreSQL treats them equal, a negative NaN sorts below -inf, and ordinal 0 is overloaded
  across NULL, false and INT64_MIN.
• "NULL sorts first" stops being true per-column under Hilbert, because the index is not monotone
  in any single coordinate.

Next

14 arms, each carrying a written analysis of how it could be vacuous. Seven are standalone C over
the curve itself (permutation, unit-step adjacency, dyadic self-similarity, the production-width
bridge, golden vectors, the ncols == 1 identity, and a proof that the Z-order refactor is
byte-for-byte inert), and seven are SQL. Two negative controls are compiled deliberately wrong —
a serpentine that passes adjacency and must fail self-similarity, and Z-order which must fail
adjacency — because adjacency alone certifies a serpentine and contiguity alone certifies
Z-order. They are only non-vacuous as a pair.

Arms first, red run posted here, then the curve.

[jdatcmd]

Red run, as promised, before any curve code. Committed as eb45776 on
feat/889-hilbert-clustering. The suite is deliberately not registered in
run_all_versions.sh — a red suite in the matrix is everyone's problem, so it joins in the commit
that adds src/columnar_curve.c.

== pgColumnar test: hilbert_curve.sh ==
-- no cluster is started; this battery is pure C
-- controls: built and ran
-- serpentine: C1 violations=0 C2 violations=0 C3 violations=621870 in 25 of 25 nested cases
-- Z-order:    C1 violations=0 C2 violations=2123558 in 32 of 32 multi-column cases, C3 violations=0
PASS  INSTRUMENT C0 premise: the control battery encoded every case and every point
...
FAIL  C7 the Z-order pack is byte-for-byte what it was: ncols=8 lowbit: the code under test is absent
-- arm split: 10 instrument (10 passed), 174 battery (0 passed)

checks run: 184
accounting: 10 passed + 174 failed + 0 unrunnable = 184
hilbert_curve.sh: FAILED

Red for the right reason — every battery arm reports the code under test is absent: src/columnar_curve.c src/columnar_curve.h, not a compile error and not an unset variable. The 10
INSTRUMENT arms pass because they need nothing from src/; check_unrunnable is reserved for an
absent compiler, which is the only state where the question cannot be asked at all.

The controls are the reason to believe any of it

serpentine: passes C2 (unit-step adjacency), fails C3 (dyadic contiguity), 25 of 25 cases
Z-order:    fails C2 (2,123,558 violations, 32 of 32), passes C3

That pair is the whole design. Unit-step adjacency alone certifies a serpentine, which is not
a Hilbert curve. Dyadic contiguity alone certifies Z-order, which is the curve that already
ships. The battery is non-vacuous only as C2 and C3 together, and each control is pinned to an
exact count rather than a bound, so a checker stuck at pass and a checker stuck at fail both
redden the suite.

The first version was worse than it looked, and that is the useful part of this report

Before trusting the arms I had three adversarial passes compile wrong encoders against them.
Thirteen mutants were built and run. Two of them passed 138 of 138 — one differing from the
correct key on 95.3% of random 8-column inputs. A battery that green-lights an encoder wrong
on 95% of inputs is not a gate.

The causes were specific, measured, and are fixed:

• C4b claimed 24,000 round trips per ncols and performed 8 to 64 distinct keys. It drew key
  bytes from the low byte of a 32-bit LCG, whose period there is 512, so the byte stream repeated
  at lag 512 — at ncols=8 the same 8 keys were round-tripped 375 times each. Now splitmix64, and
  the premise arm asserts the distinct keys the program counted, not the iteration count.
  Reverting only the draw makes it report got [344] want [24000]. This is the project's own
  "measure the work, never the intent" failure, inside a test written to enforce it.
• Four arms never called the code under test at all and stayed green with both product
  functions destroyed. The C4b adjacency arm decoded through the suite's own inverse and compared
  against itself; src/columnar_curve.c could have been deleted from the link. Each is now
  composed with the encoder.
• C1 had no negative control, though the header claimed every property had one — so nothing in
  the file could make the permutation checker report a violation, on the arm the header sells
  hardest. A truncating control now does.

The golden vectors, and why they carry more weight than the properties

96 frozen byte vectors are the only arms that pin which Hilbert curve this is. Skilling's
differs from Butz/Hamilton for ncols >= 3 and both are valid — Hilbert curves are not unique
above two dimensions — so no property arm can distinguish them and the bytes are an on-disk format
commitment. They were derived from the published AxestoTranspose, independently reproduced
byte-for-byte by two auditors from their own transcriptions, and the small cases hand-checked
(ncols==1 is the identity, so the key is the big-endian ordinal; at ncols==2, max ->
aaaa..., topbit0 -> eaaa...). The code under test does not exist in the tree, so they could
not have been generated from it — which is the only reason a golden table is worth anything.

What I am not claiming

That the battery catches every wrong encoder. It catches the three blind spots that were
measured, and the mutant matrix moved from 138/0 to 181/3 on the worst of them. That number is
the reviser's and I have not reproduced it — checking it needs a correct encoder to run against,
which arrives with the implementation. I will verify it then rather than assert it now.

Also still open and unchanged from the design comment: 16 zero golden arms are structural
invariants that discriminate nothing (kept for the zero edge, documented as not coverage), and
test/selftest/070 correctly reports UNREGISTERED: hilbert_curve until the suite joins the
matrix.

Next: src/columnar_curve.c, then the same mutants run against it by me.

[jdatcmd]

Owner ruling: the curve is sticky, and the daemon preserves it

Decided by the owner on 2026-09-09, in answer to the blocker raised above. Recording it here
rather than in a commit message so it is not relitigated by whoever touches the gate next.

sorted_kind is the table's declared intent, not a property of each call. A table clustered
with Hilbert stays Hilbert until someone explicitly asks for something else.

What that decides, concretely

1. The daemon dispatches on the recorded kind. src/columnar_autovacuum.c:283-291 currently
   hard-codes SELECT pgcolumnar.recluster(%s, VARIADIC ...). It must read sorted_kind and call
   the verb that matches it, so a Hilbert table is re-clustered with Hilbert. Today it would
   convert the layout to Z-order and relabel the storage 'zorder', silently, on its own
   schedule.
2. Plain recluster() on a Hilbert table with a matching key is a no-op. The self-gate at
   src/columnar_vacuum.c:646 compares strcmp(skind, "zorder") == 0 and so cannot see a curve
   change. It becomes a comparison of the recorded kind against the kind the calling verb
   implements. Matching kind plus matching key means already clustered; either differing means
   rewrite.
3. Switching curves requires naming the other verb. recluster() will not quietly convert a
   Hilbert table to Z-order; recluster_hilbert() will convert a Z-ordered one, because that is
   an explicit request.
4. vacuum_sorted needs the same treatment. vacuum_sorted_gate_is_noop
   (src/columnar_vacuum.c:1699) refuses anything that is not exactly 'lexicographic', so on a
   Hilbert table it does a full rewrite and relabels it. That is the same defect facing the other
   way and it is in scope here, not a follow-up.

What this rules out, said plainly so the alternatives are on the record

• Refusing recluster() on a Hilbert table was rejected: the daemon would then raise on that
  table every cycle, which is log noise and risks stalling its other maintenance.
• Warning and converting was rejected: a daemon's WARNING reaches only the server log, so in
  practice the layout would still disappear unnoticed. That is the status quo with a message
  attached.

Consequence for the arms

test/projection_rewrite.sh is not the suite for this; the Hilbert arms are. Arm S4 in the plan
already covers the self-gate in four directions and now has a fifth obligation: a Hilbert table
survives a daemon-issued recluster. That arm must assert the recorded kind is still 'hilbert'
AND that the physical layout did not move, because a return value of 0 is not evidence the gate
fired -- an empty relation, a single group and an unrelated early return all return 0.
test/eager_ordering_record.sh:100 records that trap verbatim.

The daemon arm has to drive the daemon rather than call recluster() and reason about it, or it
measures the neighbouring question.

Status

Unblocked. The red battery is committed at eb45776; src/columnar_curve.c is next, then the
gate and daemon work this ruling defines, then the locality pilot.

[jdatcmd]

The curve is in and the battery is green. Three commits on feat/889-hilbert-clustering,
red then green then an inert refactor.

eb45776  test: the battery, red before the curve exists      174 failed
4557930  feat: the Hilbert curve key                         184 passed, 0 failed
d89ae7d  refactor: the key's two halves become shareable     inert, measured

The removal proof, run here rather than inherited

I said in the red commit that the claim "the battery catches subtly-wrong encoders" was the
reviser's and that I would check it myself once there was an encoder to run against. Five mutants,
each asserted to have applied — the patch raises if its anchor is missing, and a mutation whose
md5 matches the original is refused as a no-op — each restored afterwards, file verified back at
bf5f7e07105f:

unmutated                    bf5f7e07105f   184 passed    0 failed
M1 transpose is identity     916c58ad8bd9   133 passed   51 failed
M2 no Gray encode            b9f72ca2c94d   133 passed   51 failed
M3 no final t fold           9881723ebde0   145 passed   39 failed
M4 invert/exchange swapped   a1deb7f2cef1   122 passed   62 failed
M5 pack LSB-first in byte    57dacde80b1e    69 passed  115 failed

M1 is the one that matters. Making the transpose a no-op turns this back into Z-order — the
curve that already ships — and 51 arms notice. That is the evidence the battery distinguishes the
new curve from the old one rather than merely approving of whatever it is given.

The 96 golden byte vectors passing is the strongest single signal, because they could not have
been generated from this file: they were derived from Skilling's published AxestoTranspose and
independently reproduced byte-for-byte by two reviewers at eb45776, when src/columnar_curve.c
did not exist. They are also the only arms that pin which Hilbert curve this is — Skilling's
differs from Butz/Hamilton for ncols >= 3 and both are valid, so the property arms cannot tell
them apart and the bytes are an on-disk format commitment.

The refactor is checked against a record, not against itself

cluster_zorder_key now calls the shared cluster_pack_interleave, and cluster_key_ordinals is
extracted so the type gate, the NULL rule and cluster_type_ordinal have one implementation rather
than one per curve. A refactor validated by "the tests still pass" is validated against itself when
the tests call the refactored code on both sides; the C7 arms instead hold the moved interleave
against hex captured from the old loop before it moved.

COPT=-Werror, PG 18.4, 0 warnings, every count identical to the pre-change baseline:

native_cluster       11    sorted_pathkeys      113
native_recluster     12    sorted_mark_rename    46
recluster_extent     17    vacuum_sorted_gate    34
recluster_gate       13    hilbert_curve        184

Three instrument corrections worth recording

• I checked the suite list with plain sort and got a failure. The project asserts C
  collation, not the locale's, and the array was never plain-sorted. harness_selftest — 261
  checks, 0 failed, including "the suite list is sorted in C order" — is the right instrument.
• I checked the new symbols with nm -D --defined-only and got zero. PostgreSQL builds extensions
  with -fvisibility=hidden, so an internal helper is a local t, not an exported T. Wrong
  instrument for a non-exported function.
• cluster_hilbert_key was written and removed again: a static function with no caller is
  -Werror=unused-function and the build fails outright. So on this project a new static helper
  cannot land ahead of its caller, and the key arrives with its entry points.

Next

The SQL half: cluster_hilbert / recluster_hilbert, the curve-aware gate, vacuum_sorted not
clobbering a Hilbert table, and the daemon dispatching on the recorded kind — per the ruling above.
Those arms are being written now, red first, and the daemon arm has to drive the daemon rather
than call recluster() and reason about it.

Still open and unchanged: the locality pilot. Nothing here measures locality, and the design
comment records why the obvious fixture cannot — on a dense dyadic grid both curves produce the
identical row-to-group partition and the skip ratio is 1.0000.