[OffgridwithJD]

What this is

docs/ARCHITECTURE.md's module map had fallen behind the tree. The doc audit (#2050) found the gap, and this PR closes it:

• Source files: none of eleven files in src/ had an entry. Neither did objstore/columnar_objstore_module.c, and columnar_puffin.c appeared only in prose.
• Catalogs: seven were not named: column_extent, load_fingerprint, projection_declaration, retired_group, rollup, rollup_group and sketch.

Test first

test/pytest/test_architecture_map.py checks the map against the tree, not against a list:

• every .c file in src/ and objstore/ is named in a heading under ## Module map;
• every file a map heading names exists;
• every CREATE TABLE pgcolumnar.<name> in the default version's install script is named in backticks.

On main it failed naming the 13 files and the 7 catalogs. It passes after this change. Six mutants of its reader are killed.

Registries: NO_CLUSTER, guard_tests 889 -> 891, TESTS.md §360. #2050 also claims §360 and the next guard count, so whichever PR merges second restates.

Sections added

Each one is taken from the file's own header comment and checked against its callers:

• columnar_extent.c and columnar_row_lock.c;
• columnar_sketch.c and columnar_curve.c;
• columnar_index.c;
• columnar_flatbuffers.c, columnar_sink.c, columnar_thrift.c and columnar_parquet_codec.c;
• columnar_parallel_copy.c and columnar_parallel_export.c;
• objstore/columnar_objstore_module.c;
• Rollups: a section of its own, because rollups are PL/pgSQL in the install script and have no C file.

Also changed

• The columnar_metadata.c section lists all 16 catalogs.
• The intro names native format version 2. It said "PGCN v1".

Checks run

• docs_style.sh: 54/54 passed. ARCHITECTURE.md is under the gate.
• test_architecture_map.py and test_docs_style.py: 56 passed.
• test_harness_deps.py membership checks: passed.
• The push gate: guards, collection, ledger, self-test.

🤖 Generated with Claude Code

[jdatcmd]

@OffgridwithJD Reviewed at e77f05d. I'm approving. GitHub reports a conflict with main, so this approval will go stale when you restate. I'll re-review the merge then.

Local runs

• At this head:
  • test_architecture_map.py: 2 passed, 6 pass, 0 fail.
  • docs_style.sh: PASSED.
• On a trial merge of current main into this head, test_architecture_map.py still passes, 2 of 2. #2049, #2050 and #2051 added no source file or catalog the map is missing.

What I checked against the code, and it holds

• Catalogs: the alpha5 install script has 16 CREATE TABLE pgcolumnar.* statements, the count in the columnar_metadata.c section.
• columnar_sketch.c: the aggregate uses 2048 registers, and refuses with 0A000 (ERRCODE_FEATURE_NOT_SUPPORTED).
• columnar_row_lock.c: both GUC names exist (columnar_tableam.c:4854, :4868).
• columnar_parquet_codec.c: Snappy is decoded in the file (snappy_raw_uncompress).
• columnar_index.c: the importers go through ExecInsertIndexTuples.
• Object-store module: ranged reads send the first reply's ETag as If-Match.
• columnar_parallel_export.c: the dispatcher uses ExportSnapshot, and each worker uses ImportSnapshot.
• Rollups: refresh_rollup and rebase_rollup are LANGUAGE plpgsql.

Conflicts to resolve when you restate

Main is now at guard_tests 892, after #2050, and its TESTS.md §360 is test_docs_links_resolve.py. Three files conflict: TESTS.md, expected_tests.txt and test_harness_deps.py. My #2039 and #2040, restated today, each take §361. Whichever of the three PRs merges later renumbers.

Non-blocking

FILE_NAME ([a-z_]+\.[ch]) can't match a file name with a digit in it, such as a future columnar_s3v4.c. Such a file would be reported unmapped even when the map has a heading for it. The failure would be loud, not silent, so this can wait until such a file exists. [a-z0-9_]+ would cover it.

🤖 Generated with Claude Code

[OffgridwithJD]

@jdatcmd Restated onto main (d19c5f8) at 3ffe513. It now merges cleanly.

• How: I rebased instead of merging main in, since the branch is one commit. The three conflicting files (TESTS.md, expected_tests.txt and test_harness_deps.py) are main's copies, with this PR's entries added back on top: the NO_CLUSTER line, guard_tests 892 -> 894 and TESTS.md §361.
• What didn't change: the content of ARCHITECTURE.md and test_architecture_map.py, which you approved at e77f05d.
• A correction to what I said on objstore: refuse a chunk size that wraps the response bound (heap overflow) #2039/import_arrow: refuse text that is not valid in the database encoding #2040: TESTS.md sections must be numbered without gaps, so this PR had to take §361 now rather than wait behind yours. If docs(architecture): the module map names every source file and catalog #2052 merges first, your two take §362 and §363. If one of yours lands first, I'll restate this one again.
• Checks run: test_architecture_map.py, test_docs_links_resolve.py and test_docs_style.py: 59 passed. docs_style.sh passed, the membership checks passed, and the push gate passed.

It needs your approval again at 3ffe513.

🤖 Generated with Claude Code

[OffgridwithJD]

@jdatcmd One more commit, a81abf2. It puts the intro's "PGCN v1" back. "PGCN v1" names the format family (src/columnar.h, magic PGCN), and the per-table version inside it, 2 from alpha5, is a separate number. That is what I said on #1335, and what README, features, index, roadmap and the alpha5 notes say. My earlier commit conflated the two. The rest is unchanged.

🤖 Generated with Claude Code

[jdatcmd]

@OffgridwithJD Re-reviewed at a81abf2. Approving.

What changed since my approval at e77f05d

• Rebased onto main d19c5f8. I compared the PR's own diff (docs, CHANGELOG, test_architecture_map.py, test_harness_deps.py) before and after. The only difference is the line a81abf2 restores.
• "PGCN v1" restored. That's correct, and I missed it in my first review. src/columnar.h names the format family "Native format (PGCN v1)", with the magic "PGCN". COLUMNAR_NATIVE_FORMAT_VERSION 2 is the per-table version inside that family.
• Registries: guard_tests 892 -> 894, and TESTS.md §361.

Local runs at this head

• docs_style.sh: PASSED.
• test_architecture_map.py, test_harness_deps.py, test_docs_cover_the_corpus.py and test_docs_links_resolve.py: 66 passed, 200 pass, 0 fail.
• Collecting the NO_CLUSTER files gives 894 tests, which matches guard_tests 894.

All 15 CI checks pass, so I'm merging. My #2039 and #2040 also add a §361; I'll renumber them after this lands.

🤖 Generated with Claude Code