LLP 0261 corrects LLP 0032's absent-column parenthetical: the pad value is per read path

[philcunliffe]

Closes deferred item 1 of #823: llp/0032-github-llm-graph-bridge.decision.md:104-106 says the gateway data source exposes its declared schema columns "(padding absent physical columns to null)". Verified against the tree, that is one pad value where the code has two:

• Column-stream path: null. withSchemaColumns in hypaware-core/plugins-workspace/ai-gateway/src/dataset.js rewrites undefined chunk holes to null in its scanColumn wrapper, pinned by test/core/ai-gateway-dataset.test.js:323 ("absent column streams null, not undefined").
• Row path: undefined. Post LLP 0241 §alignment, absentCell in src/core/query/union-source.js pads a declared-but-absent column with a cell resolving to undefined, and the resolved map is left alone. Pinned by test/core/star-expansion-drifted-union.test.js and test/core/union-source.test.js.

LLP 0032 is Status: Active, so per repo convention this is not an in-place rewrite. The PR:

1. mints LLP 0261 (llp/0261-absent-column-pad-value-per-path.decision.md) recording what 0032's sentence compresses, what each path does with code and test evidence, and that the null/undefined split remains an open question (LLP 0241's explicit non-decision; Follow-up: deferred review findings from PR #821 #823 item 5). It deliberately settles nothing about the split.
2. adds an **Extended-by:** LLP 0261 (...) forward-ref to 0032's metadata header, an explicitly permitted mechanical edit; nothing else in 0032 changes.

Number 0261 was verified unclaimed across every remote branch; 0260 is deliberately left free for the unresolved LLP 0245 duplicate claim between #815 and #818.

Why the other four deferred items of #823 are not closable here

• Item 2 (LLP 0015 #740 correction-note hedge): the hedged wording ("when it was written") exists only on PR Union absent-column tests pin the pre-LLP-0241 contract, so master is red (#820) #821's unmerged branch; master's 0015 still carries the original flat note, so there is nothing reachable from master to tighten.
• Item 3 (round-1 review record misattributes coverage to test 17): review records are immutable; the issue note is itself the correction. Nothing in the tree to change.
• Item 4 (fix/issue-778 needs a post-0241 rebase read): advisory to whoever lands PR Pin the icebird absent-column contract at the SQL surface (#778) #787/Follow-up: document the icebird-backed absent-column contract deferred from PR #740 #778, not a change to this tree.
• Item 5 (the null/undefined split between scanColumn and the row path): an open design question LLP 0241 explicitly declined to settle; settling it needs its own deliberate LLP. LLP 0261 names it as open and settles nothing.

Verification

• Baseline origin/master (4adfdb7): 4253 pass / 4 fail / 1 skipped; the 4 failures are the expected master is red: four union-source absent-column tests fail, blocking every open PR #820 union-source absent-column tests (fix held on PR Union absent-column tests pin the pre-LLP-0241 contract, so master is red (#820) #821).
• This branch: identical result, same 4 failures, no new failures.
• npm run typecheck: clean.
• test/core/llp-ref-hygiene.test.js: 11/11 pass.
• All anchors referenced by the new doc resolve (0032#capture, 0241#alignment, 0241's non-decision heading, 0015 Multi-partition union).

Do not merge item 5 semantics from this doc into code; it is doc-only with no runtime effect.

🤖 Generated with Claude Code

Fixes #823

[philcunliffe]

Round 1 review, PR #824 (87c4123)

Verdict: approve. The document is factually correct on both halves of its central claim, it stays out of the open design question it names, the llp/0032 edit is add-only, every anchor resolves, and the number is unclaimed. One Low finding, in the PR body's justification rather than in the diff, and one informational note. Nothing changed in the tree; nothing pushed.

Method: worktree off origin/fix/issue-823, independent verification against the tree at that SHA, plus /code-review low 824 as a second input. The skill targeted the right diff this time (it reported "docs-only diff, LLP 0261 plus a forward-ref on 0032; no runtime code changed" and returned no findings), which matches my own reading.

Factual claim, verified independently

Column-stream half: true. hypaware-core/plugins-workspace/ai-gateway/src/dataset.js:219-238 forwards scanColumn and rewrites holes in place: if (chunk[i] === undefined) chunk[i] = null (line 231). Pinned at test/core/ai-gateway-dataset.test.js:296-326, whose per-value assertion is assert.strictEqual(v, null, 'absent column streams null, not undefined') (line 323). 0032's "pads to null" is literally true here, as 0261 §column-stream says.

Row half: true. src/core/query/union-source.js:16 defines absentCell as () => Promise.resolve(undefined); alignRowColumns (line 51) fills every advertised-but-missing name with it and line 55 passes row.resolved through untouched, so the padded column is absent from resolved. The gateway's row path reaches this same code: dataset.js:8 imports alignRows from hypaware/core/query and dataset.js:195 applies it to withSchemaColumns.scan's rows, which is exactly the second application site LLP 0241 §alignment names. So on the row path 0032's "pads to null" is false, as 0261 §row-path says.

The two supporting claims in §row-path also check out: the IS NULL claim is pinned at test/core/star-expansion-drifted-union.test.js:192-193 (SELECT * FROM t WHERE git_remote IS NULL matches only the drifted partition), and the undefined-not-null projection at test/core/union-source.test.js:487 and :632. The quoted withSchemaColumns doc comment is verbatim: dataset.js:168-169 reads "the exact value a read of it yields depends on the read path (LLP 0015#multi-partition-union)".

Stays in its lane

Confirmed. §"Not settled here" quotes LLP 0241's own non-decision verbatim (llp/0241-...:112, "should be collapsed remains an open design question, not settled here") and adds no preference of its own. The §Decision section restates 0032's parenthetical as addressable and never throws, value depends on the path - which is the union of the two measured behaviours, not a choice between them - and closes with "Nothing 0032 decided changes". It also repeats the consumer constraint (must not branch on which of the two values they read) that the scanColumn comment already carries. No quiet settlement.

LLP immutability

llp/0032-github-llm-graph-bridge.decision.md is +4 / -0: four lines of **Extended-by:** appended to the metadata header at line 9, immediately after **Related:**. Nothing 0032 settled is rewritten; §Capture's paragraph at lines 105-110 is byte-identical. That matches the permitted forward-ref pattern and the surrounding corpus (19 other docs carry **Extended-by:** in the same position).

Anchors, numbering, conventions

• Every anchor resolves: 0032#capture -> ## Capture (llp/0032-...:79); 0241#alignment -> explicit <a id="alignment"> (llp/0241-...:78); 0241#the-padded-cell-reads-undefined-and-this-decides-nothing-new -> ### The padded cell reads \undefined`, and this decides nothing new (llp/0241-...:104), which is the anchor GitHub generates for that heading; 0015#multi-partition-union->## Multi-partition union (llp/0015-...:51). Both relative file links exist. test/core/llp-ref-hygiene.test.js` is 11/11.
• 0261 is unclaimed. Swept all 52 remote branches: 0248-0259 and 0262 are already taken on unmerged branches, 0261 appears only on fix/issue-823, and 0260 is free everywhere - consistent with the PR body's note that it is being held for the 0245 duplicate claim. So 0261 is the correct next free number, not a gratuitous skip.
• Header matches Decision convention exactly (Type / Status / Systems / Author / Date / Related, then a blockquote abstract), compared against LLP 0241. Systems: Query, Sources are both in the corpus vocabulary. Filename follows NNNN-slug.type.md. **Extends:** mirrors the one prior use at llp/0243-...:9.
• No em dash in either file. The only non-ASCII is §, used as the corpus already uses it.
• Tests: npm test on this branch is 4196 pass / 22 fail / 1 skipped; origin/master (a14246d9) is identical, 4196 / 22 / 1. Zero delta, as expected for a doc-only diff. (The 22 are pre-existing and environmental in this sandbox, not the 4 the PR body describes - see below.)

Findings

1. Low - the PR body's reason for deferring item 2 is stale; item 2 is reachable from master now.
The body says the llp/0015 #740 hedge "exists only on PR #821's unmerged branch; master's 0015 still carries the original flat note". PR #821 has since merged (a14246d9), and this branch's own HEAD is a merge of that master. The hedged wording is in the tree at llp/0015-query-and-datasets.spec.md:103-104: "That was never true of the code when it was written". The body's baseline line ("origin/master (4adfdb7) ... 4 failures, fix held on PR #821") dates the reasoning to before that merge.

Round 1 of #821 was right on the substance: the original claim was the conjunction "reads as null, never throws", and post-0241 the row path still reads undefined, so the conjunction is false now too and the flat "That was never true of the code" needed no qualifier.

Left unfixed, deliberately. Issue #823 item 2 designates it optional in terms ("whoever next touches 0015 can tighten or leave it"), llp/0015 is Status: Active and this is its settled correction record, and this PR's whole contract with the reader is that it changes exactly two files for exactly item 1. Widening it to edit a third Active doc on my own authority is worse than leaving a one-clause hedge. The correct home is whoever next has business in 0015. The finding is against the stated rationale, which no longer holds, not against the outcome, which is still defensible. I have not edited the PR body.

2. Info - llp/0241:118-121 also still quotes the corrected form.
0241 says the new behaviour "is that LLP 0015 already required of a union ("projecting an absent column reads as null, never throws")" - a quote of exactly the claim #740 retracted. It qualifies 0261's "last remaining prose asserting sameness" slightly. Not actionable: 0241 is Accepted, the sentence is scoped to the never-throws consequence rather than to the pad value, and 0261 inherits the "last remaining prose" phrasing straight from issue #823 item 5. Recorded so a later reader is not surprised.

Items 3-5 deferrals: sound

• Item 3 (round-1 record misattributes coverage to test 17): review records are immutable and there is nothing in the tree to change. Correct to defer; the issue note is the correction.
• Item 4 (fix/issue-778 wants a post-0241 rebase read): the branch exists at 36c77e18 and is unmerged, carrying llp/0240-icebird-absent-column-contract.decision.md, which is not on master. Advisory to whoever lands Follow-up: document the icebird-backed absent-column contract deferred from PR #740 #778, not a change to this tree. Correct to defer.
• Item 5 (the null/undefined split): genuinely open, llp/0241:112 declines it in those words, and LLP 0261 names it as open without settling it. Correct to defer, and correctly handled by this PR.

Only item 2 is reachable from master, and for the reasons above I judge it right to leave it there rather than annex it into this PR.

[philcunliffe]

Round 2 review, PR #824 (87c4123)

Verdict: approve, clean. I agree with round 1 on both observations and on its decision to leave both. Nothing actionable remains; nothing changed in the tree, nothing pushed. Head is still 87c4123.

This round checked round 1's reasoning rather than repeating its sweep, but re-derived the load-bearing facts from the tree independently.

Round 1 observation 1 (item 2 deferral rationale is stale): confirmed, and leaving it is right

Confirmed the hedge is on master. git show origin/master:llp/0015-query-and-datasets.spec.md at llp/0015-query-and-datasets.spec.md:102-105 carries the #731 / PR #740 correction note reading "That was never true of the / code when it was written" (the phrase straddles lines 103-104, which is why a naive single-line grep misses it). origin/master is a14246d9, the #821 merge, and this branch's HEAD is a merge of exactly that. So the PR body's "exists only on PR #821's unmerged branch; master's 0015 still carries the original flat note" is factually stale, as round 1 said. Its baseline line (origin/master (4adfdb7b)) dates the body to before the merge.

Agree it should stay unfixed here. Three independent reasons, and I checked each rather than inheriting them:

• Follow-up: deferred review findings from PR #821 #823 item 2 is optional in its own terms ("whoever next touches 0015 can tighten or leave it").
• llp/0015 is Status: Active and the #731 / PR #740 block is a settled correction record. Retracting a qualifier inside it changes what that record says it retracted, which is not the typo/link/status class CLAUDE.md permits on a settled doc.
• The PR's contract with a reader is two files for item 1 only. Annexing a third Active doc on review authority is worse than a one-clause hedge whose only defect is implying the retraction might be time-scoped. The substance still points the right way: the retracted claim was the conjunction "reads as null, never throws", and post-0241 the row path still reads undefined, so it is false now too.

The finding is against the body's rationale, not its outcome, and I have not edited the body.

Round 1 observation 2 (0241 still quotes the retracted phrase): confirmed, and it does not make 0261 inaccurate

llp/0241-scan-rows-carry-advertised-columns.decision.md:118-121 does quote "projecting an absent column reads as null, never throws" as what LLP 0015 "already required of a union". But that sentence is scoped to the never-throws consequence (it explains why clauses evaluated above the scan now answer instead of raising ColumnNotFoundError), and it sits two paragraphs below llp/0241-...:104-112, where 0241 states the split explicitly and declines to settle it. 0241 therefore does not assert the two paths read the same value; it asserts the opposite. 0261's "last remaining prose asserting the two paths read the same value" survives intact. Info only, exactly as round 1 filed it.

Independent re-verification of the load-bearing facts

• Column stream normalizes to null. hypaware-core/plugins-workspace/ai-gateway/src/dataset.js:230-232: inside wrapped.scanColumn's chunks(), if (chunk[i] === undefined) chunk[i] = null. Pinned at test/core/ai-gateway-dataset.test.js:323, assert.strictEqual(v, null, 'absent column streams null, not undefined'). True.
• Row path pads with a cell resolving to undefined. src/core/query/union-source.js:16, absentCell = () => Promise.resolve(undefined); alignRowColumns fills every advertised-but-missing name with it (:50) and passes row.resolved through untouched (:55), so the padded column is absent from resolved. The gateway reaches it: dataset.js:195 wraps source.scan(...).rows() in alignRows(..., scanColumns). True. Supporting pins check out too: test/core/star-expansion-drifted-union.test.js:192-193 (WHERE git_remote IS NULL matches only the drifted partition) and test/core/union-source.test.js:487 ("a projected column one partition lacks reads as undefined, never null").
• llp/0032 got only the forward-ref. git diff --name-status is M llp/0032 + A llp/0261; the 0032 hunk is +4 / -0 appended after **Related:** at line 9. §Capture's paragraph (llp/0032-...:105-110) is byte-identical. Nothing it settled is rewritten.
• 0261 names the split as open, settles nothing. §"Not settled here" (llp/0261-...:96-106) quotes 0241's non-decision verbatim and adds no preference; §Decision restates 0032's parenthetical as the union of the two measured behaviours ("addressable and never throw; the value a read yields depends on the read path") and closes "Nothing 0032 decided changes".
• Number, anchors, conventions. Re-swept all 52 remote branches after a --prune fetch: llp/0261-* exists only on fix/issue-823. All four anchors resolve (0032#capture -> ## Capture at :79; 0241#alignment -> <a id="alignment">; the 0241 non-decision heading slugifies to the anchor used; 0015#multi-partition-union). test/core/llp-ref-hygiene.test.js is 11/11 on this branch. Zero U+2014 in the diff.

The #787 cross-check: 0261 does not repeat that error

origin/fix/issue-778 carries llp/0240-icebird-absent-column-contract.decision.md, which states at :82-85 and :99 that "the parquet union throws" / icebird does "not throw where parquet does" - the claim post-#821 master contradicts, and the reason #787 is parked.

LLP 0261 contains four uses of "throw" (:15, :32, :87, plus the quoted 0015 phrase at :38) and none of them assert a throw on the current tree. All four are the never-throws direction, scoped to the withSchemaColumns-wrapped gateway source that 0032 is about: without the wrapper validateScan would raise ColumnNotFoundError over a pre-v7 partition; with it, the column stays addressable on both paths. That matches master's 0015, which records that padding made clauses evaluated above the scan "answer instead of throwing", and matches the wrapper's own where-stripping comment (dataset.js:206-215). 0261 is consistent with post-#821 master; the #787 defect is not present here.

Left unchanged

Both round-1 items, for the reasons above. One cosmetic note, not actionable and not worth a push on a doc-only PR: llp/0261-...:37-40's "and that PR #821 uncompressed again after LLP 0241" reads awkwardly, though it describes the #820 correction accurately.