docs(adr-0053): amend D-F1 — findWithWindowFunctions is a covered read door

[os-musk]

Fixes #16782

Governed surface (docs/adr/**) ⇒ this PR is draft-only, terminal four-step, human merge. ⛔ No seat readies it, enqueues it, or arms auto-merge. Its terminal state is a draft awaiting the maintainer's own merge.

Clause-②: no

An ADR prose amendment adds no exported symbol and no key on any published payload. The diff is one .md file under docs/adr/; check-widening-tells' four tells (a schema key, a closed-set member, a published export, a registry entry) are each zero here, so the measurement agrees with the seat's declaration.

What changed — one file, prose only

PR #16716 (card #16609) routed findWithWindowFunctions through the same formatOutput pass find() runs. Three ADR-0053 statements became false on the tree at that merge. All three are amended, and nothing else in the file moves.

⭐ The card body listed two sites. There are three — the third is :3, the Status line, which is the sentence a reader takes as the ADR's summary without opening the addendum.

Carrier 1 — :3, the Status line

Before

… every @objectstack/driver-sql record read door but findWithWindowFunctions (#16609) presents Field.datetime values and the builtin created_at / updated_at audit stamps as the canonical YYYY-MM-DDTHH:MM:SS.sssZ text on every dialect … save an Invalid Date, which has no canonical text and passes through unchanged (#13973, maintainer ruling B1 narrow, 2026-09-02).

After — the exception phrase struck, the correction clause appended:

… every @objectstack/driver-sql record read door but findWithWindowFunctions (#16609) presents … save an Invalid Date, which has no canonical text and passes through unchanged (#13973, maintainer ruling B1 narrow, 2026-09-02). Corrected 2026-09-08 (#16609 / PR #16716): that exception is gone — findWithWindowFunctions now routes each row through the same formatOutput pass, so those two column classes present as the same canonical text there, with the window ALIAS columns carved out (a computed alias wins the key and its value stays raw). D-F1 rules those two classes and no more: the other presentations that pass applies at that door are #16609's contract, not this ADR's.

Carrier 2 — :1081, D-F1's body

Before

findWithWindowFunctions is not one of these doors (see Consequences; #16609). Declared = enforced: …

After — struck, corrected, and the door's full move separated from what D-F1 governs:

findWithWindowFunctions is not one of these doors (see Consequences; #16609). — corrected 2026-09-08 (#16609 / PR #16716): it is one of them now, for these two column classes. It routes each row through the same formatOutput pass find() runs, minus the window ALIAS columns: a computed alias wins the key and its value stays raw (select * plus an ... as ok window projection yields two ok columns and the row object keeps the LAST), so no declared field's presentation rule is ever applied to a computed value. That pass moves more than this addendum rules — the external.columnMap row-KEY rename, Field.object/JSON, numeric strings, Field.boolean, Field.date and Field.time — and D-F1 governs, at that door exactly as at the doors listed above, ONLY the two instant classes named here; the rest of that pass is #16609's contract, pinned by sql-driver-window-function-output.test.ts (door-to-door agreement with find() on SQLite; the Postgres and MySQL cells under Temporal Conformance (live PG + MySQL)). Declared = enforced: …

Carrier 3 — :1157, the Consequences bullet

Before

• Not covered: findWithWindowFunctions, which applies no read presentation of any kind today (booleans, dates and JSON included) — a pre-existing gap of its own, recorded rather than folded in.

After

• Not covered: findWithWindowFunctions, which applies no read presentation of any kind today (booleans, dates and JSON included) — a pre-existing gap of its own, recorded rather than folded in. — corrected 2026-09-08 (driver-sql: findWithWindowFunctions returns storage forms — a declared boolean answers 1 and an object field answers JSON text where find() answers true and the parsed object #16609 / PR fix(driver-sql)!: findWithWindowFunctions presents its rows like every other read door (#16609) #16716): that gap was a card of its own and it landed. The door now runs each row through the same formatOutput pass find() runs, so it presents the two instant classes D-F1 rules exactly as the doors listed above do — and also the classes D-F1 does NOT rule (the external.columnMap row-KEY rename, Field.object/JSON, numeric strings, Field.boolean, Field.date, Field.time), which are driver-sql: findWithWindowFunctions returns storage forms — a declared boolean answers 1 and an object field answers JSON text where find() answers true and the parsed object #16609's contract rather than this ADR's. Carved out at that door: the window ALIAS columns — a computed alias wins the key and its value stays raw.

The two things this deliberately does not flatten

(a) The door moves many classes; D-F1 rules two. Read off formatOutput (packages/drivers/driver-sql/src/sql-driver.ts:16923), the pass applies, in order: the ADR-0015 external.columnMap row-KEY rename; Field.object/JSON parse (SQLite); numeric-string coercion (SQLite); presentAuditTimestampOutput over created_at / updated_at; normalizeSqliteDatetimeOutput over Field.datetime; Field.boolean (SQLite and MySQL); Field.date; Field.time. D-F1 rules the two instant classes and nothing else. Every one of the three amendments enumerates the pass and names the two separately, so none of them can be read as the ADR annexing the other six.

⚠️ The amendments enumerate rather than count. The dispatch and the card comments say SEVEN classes; the enumeration above has eight entries, and reconciles to seven only if the two instant classes are counted as one fold. Printing a numeral that resolves two ways is exactly the kind of new false statement this card exists to avoid, so the ADR names the moves instead of counting them. Flagged rather than silently chosen.

(b) The D-F3 Invalid-Date carve-out survives, verbatim, at both sites that carry it. Measured on the committed tree after the edit: the Status-line spelling (save an Invalid \Date`, which has no canonical text and passes through unchanged) occurs once, D-F1's body spelling (save the one shape D-F3 names: …`) occurs once, and D-F3's own section is byte-identical. Dropping it would re-introduce the overstatement PR #16619's contract review returned a finding for.

(c) The alias carve-out, now pinned in code, is recorded at all three sites: the alias wins the key and its value stays raw.

Precondition — re-derived by symbol, not inherited

findWithWindowFunctions at packages/drivers/driver-sql/src/sql-driver.ts:9097 on this branch's base d4401f75bb. Read in the method body, not grepped: the [#16609] comment block, the aliases snapshot, this.formatOutput(object, row), and the per-alias restore that follows it. sql-driver-window-function-output.test.ts is on the tree with its SQLite agreement arm and its DIALECT_CELLS live arm.

Firing control for the prose reading (all three carriers are prose, so they were read): Status**: Accepted on :3 matched 1; findWithWindowFunctionsZZZ is not one of these doors matched 0; findWithWindowFunctionsZZZ in sql-driver.ts matched 0.

Fossil check, before moving any sentence

Read first: the addendum's own header and Provenance (maintainer ruling on #13973 — 「同意」 to B1 narrow, 2026-09-02, comment 5507803003), D-F1, D-F2, D-F3, Consequences and Options not taken. No fossil records the "not covered" line as a deliberate standing decision — its own words are "a pre-existing gap of its own, recorded rather than folded in", i.e. scoped out at the time and since landed by its own card. The one fossil that does bind is D-F3's carve-out, and it is untouched. ⛔ Nothing here reverses a recorded ruling; the ADR is being brought level with an enforcement that moved.

Not touched — already discharged elsewhere

packages/drivers/driver-sql/src/sql-driver-13973-canonical-iso-read-door.test.ts was corrected inside PR #16716 and already points forward to this card. It is not in this diff, and including it would also have made this PR non-docs-only. Verified: git diff --stat is one file.

Changeset — route 2, and the text I rejected

Governing text: .github/workflows/pr-automation.yml, the Require a changeset (or the skip-changeset label) step, the WHICH LEVEL block (around lines 660–690 on this tree).

• Rejected — route 1 ("It releases something → run pnpm changeset"): it does not apply, on a measurement rather than an assumption. Of the 82 tracked manifests, 70 are non-private (publishable) and all 70 declare a files field; zero of those entries escape their package directory (no .. prefix) and zero name a docs path. The root manifest is private: true. docs/adr/** sits at the repository root, outside every package directory ⇒ it reaches no published package's shipped files. This is the same premise the workflow itself records for skills/**: "skills/ is not a workspace member and no package's 'files' field includes it."
• Rejected — route 3, the empty-frontmatter changeset: "(CLOSED) … the step below now REJECTS any that a PR newly adds (空 frontmatter changeset 相对 skip-changeset 标签零收益、单向风险 —— 「禁止空 changeset 进 .changeset/」的决策证据(#5292 结案后无处存放) #5471) … it names no package, so its body reaches no CHANGELOG, and it buys nothing the label does not."
• Taken — route 2: docs/ is named on the workflow's own releases-nothing list and the label is marked <<< PREFERRED. The skip-changeset label is applied to this PR.

AGENTS.md's floor against none — "A bug fix in a released package takes a patch changeset — never none, and ⛔ never skip-changeset: that label is for a diff that publishes nothing from any released package" — is a floor, not a ceiling, and the measurement above is exactly the predicate it names.

Gates

Derived and reconciled with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, then --ran. Reconciliation line, verbatim:

Run reconciliation — 17 derived, 17 run, 0 NOT-MEASURED, 0 UNRUN.
✓ dispatch-gates --ran: 17 derived famil(ies) accounted for — 17 run, 0 NOT-MEASURED.

⚠️ That line accounts for coverage, not verdicts. Verdicts, stated separately: 17 of 17 exited 0. One of them — pnpm --filter @objectstack/lint run check:doc-formula-expressions — first returned exit 3 = PREREQUISITE NOT MET (@objectstack/formula and @objectstack/lint not built), which is NOT MEASURED, never a pass. It was cleared by building both packages under the shared verify lock and re-run to a real exit 0; the reported 17/17 is the post-build reading. Exit codes were captured before any pipe.

Governed Surface Queue Guard — read, not assumed. scripts/pm/check-governed-queue-guard.mjs splits by event: on merge_group a governed diff without an authorized pinned approval is a refusal; on pull_request the same finding is an early warning that exits 0, deliberately, because "a governed PR sitting as a draft awaiting the maintainer's own merge is the CORRECT terminal state of the regime" and a check red on the healthy case is the poison the 2026-08-18 ruling named. So on this PR it will report the governed finding and stay green — not a no-op, and not a red to repair. pnpm check:pm-governed-merges (the detection half) ran green locally.

Also green here and worth naming: check-adr-links (680 relative link destinations under docs/adr/ resolve), check-adr-symbol-anchors (2068 anchors across 139 records), check:adr-anchors, check:nul-bytes, and check-closing-keyword-parity. A control-character sweep beyond the gate (grep -naP over the edited file for the non-NUL control range) found none.

Repo-wide scans (pnpm lint and the rest of the farm) are CI's run, not owed here.

验收备注

• Noted, not filed: the "SEVEN classes" count carried by this card's comments resolves to eight enumerated formatOutput passes unless the two instant classes are counted as one fold. It is a counting convention in card prose, not a defect in the tree or in the ADR, so no card was filed; the amendment sidesteps it by enumerating.
• Noted, not filed: docs/adr/0053 now carries three struck-and-corrected passages across two addenda (D-A2's, the mongo coverage note's, and these three). That is the file's own established convention, not drift.

维护者速读(草稿)

改了什么 —— 只改了一个文件 docs/adr/0053-date-and-datetime-semantics.md,纯散文,三处。ADR 里三句话说「findWithWindowFunctions 这扇读门不做任何读表现」,PR #16716 合并之后这三句话在树上已经为假。三处都用本文件自己的「划掉原文 + 加一句 corrected」惯例改成事实,其余一个字不动。

为什么改 —— 其中一处是 ADR 第 3 行的 Status 行,也就是读者不打开附录就当成 ADR 摘要的那一句。卡面原本只点了附录里的两处;第三处是本轮补上的,不补就会留下一句最显眼的假话。这张卡的排序也是对的:先让代码落地、再改声明,声明窄于执行可以容忍一个窗口期,声明宽于执行正是 D-F 附录要防的方向。

风险与代价(含回滚) —— 无运行时面,无发布面:70 个可发布包的 files 字段没有一个够得着 docs/。风险只有一个方向 —— 用一句新的过度陈述换掉旧的假话。为此两件事写死了:① 那扇门搬动的类别被逐条列出,并单独说明 D-F1 只管其中两类(两个 instant 类),避免读成 ADR 从此管布尔、JSON、数字串、date、time 和 columnMap 行键重命名;② D-F3 的 Invalid Date 豁免原文原样保留 —— 三天前 PR #16619 的合约评审正是因为丢掉它开过一个 finding。回滚成本是一次 git revert,单文件、无依赖。

席位意见 ——

你要做的 —— 这是治理面(docs/adr/**),按 Prime Directive #14,只能由你本人手动合并。⛔ 不要把它 ready、不要进合并队列、不要开 auto-merge。请核对两点:三处改写是否都把「门做了什么」与「D-F1 管其中哪些」分开写了;D-F3 的 Invalid Date 豁免是否原样还在。

---

Generated by Claude Code