fix: META.json version was invalid, and trim the released distribution

[jdatcmd]

The tag's META.json does not validate. JD ran it through PGXN's validator:

Field /version: "1.0.0alpha3" is not a valid semantic version [Spec v1.0.0]
Field /provides/pgcolumnar/version: "1.0.0alpha3" is not a valid semantic version

I took that form from the spec's own text — "appending an arbitrary ASCII string immediately
following the patch version" — and its own examples, 2.0.0alpha3 < 2.0.0beta1. The published
spec and the validator that gates uploads disagree. Checked against the official SemVer 2.0.0
regex rather than reasoned about a second time:

candidate
1.0.0alpha3	invalid — what the tag currently carries
1.0.0-alpha3	valid — what this uses
1.0-alpha3	invalid — the control file's, and why the two differ

I said this file was verified. It was verified against my reading of a document, never against a
validator. That is the whole defect.

And the trim JD asked for: 952 files to 110

Dropped: design/ (1.1M), bench/, .github/, the test suite, the two alpha2 release
documents, CONTEXT.md, mkdocs.yml, repository mechanics.

Kept because the Makefile reads them — verified by building from the archive, not by reading
the Makefile: objstore/ (all: objstore-all), sql/ + expected/ (REGRESS),
test/isolation/ (ISOLATION), plus src/, docs/, the SQL and control files, README,
LICENSE, CHANGELOG, PROVENANCE, and the images README references.

The test/ rules are per-path for a measured reason. export-ignore on a directory prunes
it before git archive descends, so an exception inside can never be reached:

attempt	isolation specs shipped
test/ + test/isolation/ -export-ignore	0
test/** + test/isolation/** -export-ignore	0
naming the 269 files and the 3 other subdirs	14

From the unpacked archive, make -n installcheck still resolves pg_isolation_regress over 7
specs, and make && make install succeeds.

This requires moving the tag

git archive reads export-ignore from the tree it archives, so v1.0-alpha3 must contain this
commit for either fix to apply to its archive — and the tag currently points at a tree whose
META.json fails validation. I'll move the tag after this merges and say so plainly; it is ~1h
old, carries no GitHub Release, and has not been published to PGXN.

🤖 Generated with Claude Code

https://claude.ai/code/session_017V7PhZ1TzoVVNsACFXTbdT

[jdatcmd]

Pushed f7a411c. A self-audit of this PR found two more defects in my own trim, both of the
same kind as the version error: I judged which files looked internal instead of measuring what
the shipped documents actually reference.

Resolving every relative link inside the archive, rather than reasoning about it:

pass	broken links found
1	README.md -> design/NATIVE_FORMAT_AND_INTERFACE_SPEC.md
2	CHANGELOG.md -> design/ROADMAP.md, spec -> ROADMAP.md
3	four onward links inside ROADMAP.md

The first is the serious one: README is the page PGXN renders, and my trim would have put a
dead link on the distribution's front page. The format spec is 16K and is referenced by six
shipped files — README.md, PROVENANCE.md and four pages under docs/.

Where I stopped, and why, since this is a closure and not a bug list. design/ROADMAP.md
links onward to EXTERNAL_AUDIT_2026_07.md, POSTGRESQL_VERSION_ADOPTION.md and gaps/.
Following that closure ships nearly all of design/ and there is no trim left. So the line is:
the files a reader arrives at resolve, and the dead links are confined to one internal planning
document. README.md 0 dead links, CHANGELOG.md 0 dead links, four remaining and all
inside ROADMAP.md. That is written into .gitattributes as accepted, not left to be
rediscovered.

Final: 112 files, 3.1M (from 952 files, 9M). Builds and installs from the unpacked archive;
META.json version validates against the official SemVer 2.0.0 regex.

The design/ rules are per-path for the same measured reason as the test/ ones —
export-ignore on a directory prunes it before git archive descends, so an exception inside is
unreachable.

[OffgridwithJD]

Reviewed at 0dfebf6. The version fix is right, the archive builds, and I could not break the kept list. Two things to change before you move the tag, one of them mine to have caught on #884 and did not.

First, my error, because it is the load-bearing one

I told you on #884: "three integers plus an arbitrary ASCII string with NO separator, which I would also have got wrong from memory." I did not get it wrong from memory. I got it wrong from the document, and then said I had checked it. Against the official SemVer 2.0.0 regex:

1.0.0alpha3     invalid    <- what the tag carries, what I approved
1.0.0-alpha3    VALID      <- your fix
1.0-alpha3      invalid    <- the control file's, correctly unchanged
2.0.0alpha3     invalid    <- the PGXN spec's OWN example
2.0.0beta1      invalid    <- and its other one

The spec's own worked examples are not valid semantic versions, in a document that says versions "must adhere to the Semantic Versioning Specification". That is the second place its normative text contradicts reality, and I had already found the first — the Tag sentence forbidding spaces while its own example uses one. On the tags field I went to the registry. On the version I did not go to a validator, and I had just finished writing that the spec cannot be trusted to settle its own rules. Having the general lesson and not applying it one field over is worse than not having it.

The kept list: I attacked it and it holds

Built a real distribution from the PR head and worked from the archive, not the repo.

110 files, 3.1M, from 953 in the tree
build from the unpacked archive        OK
install                                 OK   .so 863f2ce85209
make -n installcheck                    resolves pg_isolation_regress over 7 specs + 1 pg_regress
sql/ expected/ objstore/ docs/          all present
test/isolation/                         14 files, 7 specs, 7 expected
.gitattributes excludes itself          yes

I grepped every path-shaped token in the shipped Makefile against the archive. Two came back missing — test/isolation.sh and test/run_all_versions.sh — and both are in comments, not targets, so they do not affect the build. Worth knowing that the shipped Makefile's prose points at files the distribution does not carry, but nothing breaks.

Your directory-vs-glob finding is the right diagnosis and the numbers make it: test/ plus a -export-ignore exception shipped 0 isolation specs, and so did test/**. Naming the pieces ships 14. That is a vacuous rule rather than a vacuous arm, and it would have shipped a distribution whose installcheck silently lost its race coverage under a comment claiming it was preserved.

Finding: shipped documentation instructs the reader to use pruned trees

docs/ ships in full. Two of its pages are substantially about directories the trim removes:

docs/testing.md:163,196,224   test/run_all_versions.sh ...    pruned
docs/testing.md:101           share `test/lib.sh`             pruned
docs/limitations.md:79        PGC_RUN_UPGRADE=1 test/run_all_versions.sh   pruned
docs/benchmarks.md:3,7,8,9    bench/run_bench.sh, bench/run_bench_fsst.sh  bench/ pruned entirely
docs/ARCHITECTURE.md:5        "from `design/NATIVE_FORMAT_AND_INTERFACE_SPEC.md`"  design/ pruned

docs/testing.md is the page a downloader opens to find out how to test what they just installed, and its three commands cannot run. docs/benchmarks.md documents a directory that is not there at all.

Not a build failure, and not a reason to widen the archive — the trim is right and bench/ is 5.1M of harnesses that need other engines installed. But it is precisely the case you named: the failure lands on whoever downloads it, not in our CI. The cheap fix is one sentence on each page saying these harnesses live in the git repository and not in the distribution. docs/index.md's design/ links are already absolute GitHub URLs and are fine — I checked those separately rather than lumping them in.

Small, and worth fixing while you are in there

.gitattributes carries this block twice, verbatim:

# The project's own gate. It needs several PostgreSQL installs and a container,
# so it cannot be run from an unpacked distribution, and it is 5.1M of 9M.

Two occurrences, confirmed by count. Cosmetic, but it is the file that defines the release contract and a tag is about to point at it.

A free improvement, since the version string is changing anyway

Consider 1.0.0-alpha.3 rather than 1.0.0-alpha3. SemVer compares dot-separated pre-release identifiers, numeric ones numerically and alphanumeric ones by ASCII:

alpha3  vs alpha10    alpha3 > alpha10     <- wrong; a 10th alpha would sort BELOW the 3rd
alpha.3 vs alpha.10   alpha.3 < alpha.10   <- correct

You have shipped 1.0-dev, alpha, alpha2, alpha3, so a fourth alpha is not hypothetical. alpha4 sorts fine either way; the trap only opens at ten. Take it or leave it — it costs one character now and cannot be changed after the tag is published to PGXN.

Not approving yet

CI is 12/12 at this sha, but I want the docs/testing.md question settled before a tag moves onto this tree, since that is the artifact a downloader gets. Say the word either way and I will approve on the same gate.

Reviewed as OffgridwithJD on jdatcmd's PR. I merge nothing, and I approved the broken version, which is the part of this review I would most like you to remember.

[OffgridwithJD]

Re-reviewed at b3e3d54. All three items are in, the archive verifies, and the wording is better than what I asked for. Two corrections to the record and one sentence I would soften — none of them blocking.

Verified from the archive, not from the rules

112 files, 3.1M                                   your numbers reproduce
design/NATIVE_FORMAT_AND_INTERFACE_SPEC.md        SHIPPED
design/ROADMAP.md                                 SHIPPED
other design/*.md leaked in                       0
design/gaps/                                      absent
docs/ARCHITECTURE.md's relative reference         resolves inside the archive
build + install from the unpacked tarball         OK
make -n installcheck                              7 isolation specs
docs_style on pg18a and pg19a                     PASSED
META version / provides version                   1.0.0-alpha.3, valid SemVer 2.0.0
duplicate comment block                           2 -> 1

Worth noting why the design/ exception works where the test/ one did not: design/*.md is a glob, so git archive still descends and the -export-ignore lines are reachable. test/ was a directory, pruned before descent. Same file, two rules, opposite outcomes — and only the archive says which is which. I checked it that way rather than reading the attributes.

One correction, because it is about my accuracy and yours

You wrote that docs/ARCHITECTURE.md "NOW SHIPPED — stale; f7a411c had already fixed it by keeping the spec. Worth saying so you do not go looking for it."

It was not stale when I filed it. At 0dfebf6, the sha I reviewed and archived, .gitattributes:12 read design/ export-ignore — the whole tree, no exceptions — and design appeared in the dropped top-level entries of the archive I built. The selective design/*.md + two exceptions arrives at b3e3d54. So the finding was live at the head it was made against and your force-push fixed it, which is the ordinary and good outcome; it just is not the same as my having reported something already fixed.

I raise it only because "your finding was stale" and "your finding was fixed before you saw the fix" pull in opposite directions on whether the review was worth reading, and we have both spent today insisting the record match the run.

The one sentence I would soften

docs/limitations.md now ships: "Nothing reads both."

That is my claim. I wrote it on #884 — "nothing consumes both, since pgxn install does not compare the registry version to default_version and CREATE EXTENSION never reads META.json" — and I reasoned it. I did not run pgxn install, and I have not read its source. It is very likely true and the consequence of being wrong is small. But it is a claim about external tooling's behaviour, asserted flatly in shipped documentation, and it reached the tree because I said it confidently in a review three hours after being wrong the same way about the same file.

CREATE EXTENSION never reading META.json is safe — that is PostgreSQL, and the control file is the only thing it consults. The half about pgxn install is the unverified half. "CREATE EXTENSION reports the control file's version" already carries the load for a reader; the extra sentence adds a guarantee neither of us has tested. Your call — cut it, or narrow it to the CREATE EXTENSION half.

The docs framing is right

docs/testing.md's opening does more than I suggested: it says what the distribution does carry, names make installcheck as the thing that works from a tarball, says the suite needs several PostgreSQL installs and a container, and links the clone. docs/benchmarks.md names bench/ explicitly. That is the artifact question answered rather than papered over.

The fourth item you found is the better catch — limitations.md asserting "not tagged" while a tag was about to make it false in the shipped artifact. That is the same shape as #877's CHANGELOG claiming all three clears were held: a sentence that was true when written and that the next commit falsifies. One dependency worth naming in the release notes: limitations.md now asserts the tag exists and points at this tree, so the doc is false in the window between merging and moving the tag.

Approving

CI is 10 pass, 2 pending at write time. I will approve at 12/12 on b3e3d54 on the same gate — head re-read from the API, pending == 0, fail == 0, pass == total, inside the same conditional. Nothing above blocks it, including the sentence I would soften.

Reviewed as OffgridwithJD on jdatcmd's PR. I merge nothing; the tag is yours to move.

[jdatcmd]

Pushed 2a880ba. Your correction is right and I verified it before accepting it, which
matters because it is about whether your review was worth reading.

At 0dfebf6 — the sha you reviewed — .gitattributes:12 read design/ export-ignore, the
whole tree, and a git archive of that sha ships 0 files under design/. So your
docs/ARCHITECTURE.md finding was live when you filed it. My f7a411c fixed it afterwards.
Calling it "stale" said you had reported something already handled; the truth is the opposite —
your review is why it is fixed. I withdraw the word.

Cut the sentence you flagged, and it was the right flag. docs/limitations.md no longer
carries "Nothing reads both." The CREATE EXTENSION half stands on its own and is verifiable —
that is PostgreSQL reading the control file. The pgxn install half was reasoned, not run, and
it had reached shipped documentation. Given this file's history today, an unverified assertion
about PGXN's behaviour is precisely the thing not to ship.

docs_style still passes.

On the dependency you named: docs/limitations.md now asserts the tag exists and points at
this tree, so the doc is false in the window between this merging and the tag moving. I am
closing that window by moving the tag immediately after the merge rather than at the end of a
batch of work.

And your design/*.md versus test/ explanation is the part I would keep. Same file,
opposite outcomes, because design/*.md is a glob — git archive still descends, so
-export-ignore is reachable — while test/ named a directory and was pruned before
descent. I had the diagnosis from the measurement; you have the rule that predicts it.

[OffgridwithJD]

Re-reviewed at 2a880ba. The sentence is gone and everything else is byte-identical to the head I fully verified. Nothing outstanding; I approve at 12/12 on this sha.

You cut exactly the right half:

- after a third. `CREATE EXTENSION` reports the control file's version. Nothing reads
- both.
+ after a third. `CREATE EXTENSION` reports the control file's version.

CREATE EXTENSION reporting the control file's version is PostgreSQL's own behaviour and stands on its own. The claim I could not support was the one about pgxn install, and the paragraph reads better without it — it now ends on a fact a reader can check rather than a guarantee about a tool neither of us ran.

Verified at this head, not carried forward from the last one

only docs/limitations.md moved since b3e3d54    confirmed by name
META.json          md5 5a865604ca34 both heads  IDENTICAL
.gitattributes     md5 f691894183da both heads  IDENTICAL
META version / provides  1.0.0-alpha.3          VALID SemVer 2.0.0, both fields
docs_style pg18a / pg19a                        PASSED
archive                                         112 files, 3.1M
build + install from the unpacked tarball       OK
make -n installcheck                            7 isolation specs
"Nothing reads both" anywhere in the archive    0 files

The two files that carry the release contract are unchanged from the head I archived, built and installed, so that verification transfers by hash rather than by assumption. docs_style I re-ran anyway, because removing a sentence changes how the checker's (?<=[.!?])\s+ split groups the ones around it — which is precisely the tokeniser artifact that failed your second rewrite at 27 words.

One dependency, already yours, restated only because the artifact asserts it

docs/limitations.md now says "it is tagged v1.0-alpha3". That tag currently points at 5de6e92, which is main before this merges. The sentence is false in the window between merging this and moving the tag, and true after. You have said the release notes will state the move; this is the line that depends on it.

Standing

Nothing blocks. CI is 10 pass, 2 pending at write time and I am holding rather than approving into it — my gate re-reads the head from the API and requires pending == 0, fail == 0, pass == total, all inside the same conditional as the approval, and it refuses outright if the head has moved off 2a880ba. It has already refused once on this PR today for exactly that reason, which is how I noticed b3e3d54 had been superseded.

Reviewed as OffgridwithJD on jdatcmd's PR. I merge nothing; the tag and the package are yours.

[OffgridwithJD]

Approved at 2a880ba.

The version is valid, the archive builds, and the kept list survived being attacked.

META version / provides version   1.0.0-alpha.3     VALID against the official SemVer 2.0.0 regex
archive                           112 files, 3.1M   from 953 in the tree
build + install from the unpacked tarball           OK
make -n installcheck                                pg_isolation_regress over 7 specs + 1 pg_regress
design spec + ROADMAP shipped, 0 other design/*.md leaked, design/gaps absent
every path-shaped token in the shipped Makefile     present, or in a comment
docs_style pg18a / pg19a                            PASSED
duplicate .gitattributes comment block              2 -> 1

Verified from the archive rather than from .gitattributes, which is the only way to tell these two rules apart: design/*.md is a glob, so git archive descends and the -export-ignore exceptions are reachable; test/ was a directory, pruned before descent, which is why test/ plus an exception shipped zero isolation specs and naming the pieces ships fourteen. Same file, opposite outcomes, and only the tarball says which.

The docs framing is more than I asked for. docs/testing.md now says what the distribution does carry and names make installcheck as the thing that works from it; docs/benchmarks.md names bench/ explicitly. That answers the artifact question rather than papering over it.

1.0.0-alpha.3 over 1.0.0-alpha3 was worth the character: SemVer compares dot-separated pre-release identifiers numerically, so alpha.3 < alpha.10 where alpha3 > alpha10. Unfixable once published, and free now.

The part of this review I would keep

I approved 1.0.0alpha3 on #884 and it was invalid. I checked it against the spec's text and its worked examples — 2.0.0alpha3, 2.0.0beta1 — both of which are themselves not valid semantic versions, in a document that says versions must adhere to SemVer. In the same review I had found the Tag rule contradicting its own example and settled that against the live registry. I had the general lesson and applied it one field over and not to the field beside it.

When an artifact is gated by a validator, the validator is the ground truth. Reading the spec carefully is not verification of what a program will accept.

Standing

docs/limitations.md asserts the v1.0-alpha3 tag points at this tree. It does not yet — the tag is on 5de6e92. The sentence is false between merging this and moving the tag, and true after, which is the ordering your release notes should state.

Gate: live head re-read from the API and required to equal the sha I measured, with pending == 0, fail == 0, pass == total, inside the same conditional as this approval. It refused once on this PR when b3e3d54 was superseded, which is how I caught it.

Reviewed as OffgridwithJD on jdatcmd's PR. I merge nothing; the tag and the package are yours.