Repository navigation
Commit 645ede5
Part of #25521
Clause-②: no
Metadata-protocol: none
Ruling-ref: 6270097840
Ruling-ref: 6348891160
Cut 3 of the `sql-driver.ts` split (#24586 ruling A, recorded in
`6270097840`). The claim is `6384369018`. Six `SqlDriver` method bodies
move unedited into a new module,
`packages/drivers/driver-sql/src/sql-driver-transactions.ts`: the public
`beginTransaction`, `commit` and `rollback`, the deprecated aliases
`commitTransaction` and `rollbackTransaction`, and the protected SQLite
single-connection guard `assertBareKnexSafe`. `releaseTransaction` stays
in the class whole.
It is move-only, and the card stays open for the later cuts. Branch
`claude/issue-25521-sql-driver-cut-3`, cut from `origin/main` at
`451bf61d0` (cut 2 merged as `b694e56e9` before it).
**Serial with the file's in-flight PRs.** At claim the PM read no open
PR touching `sql-driver.ts`, `driver-turso/src` or
`driver-sqlite-wasm/src`. Re-measured at my start (18 open PRs) and
again just before this PR was opened (16 open; #25632 had merged and
#25619 had left the list), each PR's file list read in full. No PR
touches `packages/drivers/driver-sql/**`,
`packages/drivers/driver-turso/**` or
`packages/drivers/driver-sqlite-wasm/**`, except the Version Packages PR
#25640, which touches only those packages' `CHANGELOG.md` and
`package.json` (its 183 files read page by page). `origin/main` moved
one commit past the base meanwhile (#25632, now `49653f918`). It touches
only `packages/spec` and its tests, none of the three driver packages
and no gate script this diff derives, so `main` is not merged in.
## Seam table (fresh, at `451bf61d0`)
`sql-driver.ts` is 21,651 lines. 30-day lines are `git blame
--line-porcelain` lines whose committer time is on or after
2026-09-24T12:16:02Z, 30 days before the base commit. The clone's
history floor is 2026-09-15, and `scripts/pm/git-history.mjs count`
proves 69 commits on the file in that window (20 in the last 7 days). In
all, 3,882 lines (17.9%) are from the last 30 days. The class
`SqlDriver` spans lines 5487-21576 with 347 members: 251 methods (49
public), 32 statics. No public method has an inferred return type; the
one inferred public member is the getter `supports`, in the class head.
Sections are the class's own banner comments, cut by contiguous line
range. "Public" counts public methods, plus public accessors where there
are any:
| Lines | Section | Lines | 30-day lines | Members (public) |
|:--|:--|--:|--:|:--|
| 1-5486 | Module preamble: imports, types, top-level helpers (199
statements) | 5,486 | 1,416 | - |
| 5487-7078 | Class head: fields, statics, constructor, capability
getters (`supports`) | 1,592 | 290 | 88 (1 + 2 accessors) |
| 7079-7510 | Lifecycle | 432 | 155 | 15 (3) |
| 7511-10189 | CRUD (IDataDriver core) | 2,679 | 691 | 45 (7) |
| 10190-10801 | Bulk and batch operations | 612 | 140 | 9 (6) |
| 10802-10898 | Raw execution (cut 2's three stubs and the
`runtimeCreatedIndexes` field) | 97 | 28 | 4 (1) |
| **10899-10976** | **Transactions (this cut, less
`releaseTransaction`)** | **78** | **0** | **7 (5)** |
| 10977-11508 | Aggregation | 532 | 61 | 5 (1) |
| 11509-11796 | Distinct | 288 | 20 | 3 (1) |
| 11797-11912 | Window functions | 116 | 4 | 1 (1) |
| 11913-12011 | Query plan analysis | 99 | 1 | 2 (2) |
| 12012-15766 | Schema sync (syncSchema / init) | 3,755 | 373 | 62 (14 +
3 accessors) |
| 15767-15902 | Schema introspection (`listPhysicalColumns`,
`introspectSchema`) | 136 | 65 | 2 (2) |
| 15903-21576 | Internal helpers, including cut 1's five introspection
stubs | 5,674 | 638 | 104 (5) |
| 21577-21651 | After the class: `UniqueConstraintMember`,
`singleColumnUniqueColumns` | 75 | 0 | - |
The limits per area are cut 1's (PR #25614), re-read on this tree:
- **`getBuilder` builders.** Aggregation, Distinct, Window functions,
Query plan analysis, CRUD and Bulk build through `getBuilder`, so a cut
of any of them must first carry the new module into
`check:tenant-chokepoint`'s `SCAN_FILES`, or the gate goes silently
narrower. None of them is cut here.
- **Protected statics.** The hash-shadow family and the row-size
explainers (Internal helpers) read protected statics, so those bodies
stay.
- **`this.FIELD.delete/insert/update(`.** Transactions has one,
`releaseTransaction` (`this.openTransactions.delete(key)`), and Schema
sync has three. Those bodies stay. The six bodies moved here have none:
`beginTransaction` calls `.add(` on `openTransactions`, and the other
five read no field method at all.
- `insertOnlyUpsertColumns` stays in `sql-driver.ts`, because #8740's
restart line names that symbol in that file. This cut does not touch it.
**Proposed cut 4: Schema introspection** (15767-15902, 136 lines, 65
from the last 30 days): the public `listPhysicalColumns` and
`introspectSchema`, both with annotated return types. Neither builds
through `getBuilder` (the word appears only in a docblock), neither
reads a static, and neither has a `this.FIELD.delete/insert/update(`
site. It is warmer than this cut, and its dev should price three things
first: the two module-level helpers the bodies call
(`suggestFieldTypeForSqlType`, `postgresTableNameCollisionError`), which
may need cut 2's leading-`export` shape; `TursoDriver`'s overrides of
both members (the `'remote'` and `'refused'` rows of its door table);
and whether `check:tenant-chokepoint`'s raw-fragment read covers the
`knex.raw(` calls in those bodies, since a move out of `SCAN_FILES`
would narrow it. Every cold area left after that builds through
`getBuilder`.
## Why this area for cut 3
Cut 2 proposed it, and it re-measures clean: 78 lines, none from the
last 30 days. All five public members (`beginTransaction`, `commit`,
`rollback`, `commitTransaction`, `rollbackTransaction`) have annotated
return types. The section reads no static and no `getBuilder`. Its one
`this.FIELD.delete(` site is `releaseTransaction`, which stays. Between
them, the six moved bodies read `knex`, `openTransactions`,
`activeTransactions`, `isSqlite`, `isProductionEnv`,
`releaseTransaction`, `commit` and `rollback`, and nothing else. They
read no module-level declaration of `sql-driver.ts`, so unlike cut 2 no
`export` was added.
**Overrides and spies, measured before the move.**
- `TursoDriver` overrides `beginTransaction`, `commit` and `rollback`,
and each override calls `super` after its remote-mode refusal. Its door
table lists `commitTransaction` and `rollbackTransaction` as
`'inherited'`, because they call `this.commit` / `this.rollback`, which
refuse. So both aliases must keep reaching the subclass's `commit` /
`rollback`, and they do: they reach them through late-bound closures.
- `SqliteWasmDriver` overrides the getter `isSqlite`, which
`assertBareKnexSafe` reads. The host reads it through a getter that
reads the driver, so the override is the one the guard sees.
- `vi.spyOn(driver, 'beginTransaction')` in `service-storage` and
`plugin-auth` tests spies on the class method, which is still there.
- A scratch probe against the built `dist` checked every moved member's
late binding at base and at head: the counter and the open set after
`beginTransaction`, an instance spy on `isProductionEnv` (reached by
`assertBareKnexSafe`), on `releaseTransaction` (reached by `commit`), on
`commit` and `rollback` (reached by the aliases), a subclass override of
`isSqlite`, a subclass `commit` that refuses (reached by
`commitTransaction`), and a rejecting `commit` that still releases. Its
14 readings are identical at base and head. The probe is not committed.
## The shape (#23050 shape B, as cuts 1 and 2 apply it)
- The class keeps each method with its name, signature, docblock and
position, because tsup emits members with their JSDoc into the `.d.ts`.
Each body is now one host literal plus `fn.call(host, ...)`, marked
`[#25521 cut 3]`. The five `async` methods drop `async` and return the
moved function's promise. `assertBareKnexSafe` was never `async`.
- `TransactionHost` is new. It types every member as the class member
itself (an indexed access on `SqlDriver`). Each moved function types its
`this` as the `Pick` of the host over exactly the members its body
reads. The generator measures those reads from the AST (`this.NAME`
property accesses) and asserts them, so the string `this.knex.` inside
the guard's error text is not counted as a read. Each stub annotates its
literal as the `ThisParameterType` of the moved function. There is no
cast, and no member becomes public.
- `knex`, `openTransactions`, `activeTransactions` and the getter
`isSqlite` go as getters, so each read happens when the body makes it.
`commit`, `rollback`, `releaseTransaction` and `isProductionEnv` go as
late-bound closures.
- **One field is written.** `beginTransaction` runs
`this.activeTransactions++`, so its literal carries a setter beside the
getter, which writes the field on the driver. The generator measures
writes (`++`, `--` and assignment on `this.NAME`) and asserts them, and
the interface marks `activeTransactions` as the one non-`readonly`
field. This is the accessor pair `auth-manager.ts` uses for
`jwtSigningFailureReported` (#25224 cut 6). Both fields stay on the
class: `releaseTransaction`, `ensureSequencesTable`'s guard call and the
tests read them.
- `this.knex.transaction()` keeps its receiver: the getter hands back
the class's knex, and `.transaction` is called on it.
- The move was produced by a script from the source text, not retyped:
each method's parameter list, return type and body lines, re-indented
two columns. The guard's error message is five single-line template
literals joined by `+`, so no line continues a template literal.
## The published `.d.ts` does not change
Under the series bar (ruling `6348891160`, letter A), measured on base
`451bf61d0` and on head `59d63a8d1`. Both were built against the same
dependency tree: `turbo run build --filter=@objectstack/driver-turso...
--filter=@objectstack/driver-sqlite-wasm...` at base, 9/9 tasks
(driver-sql a cache miss). Then `pnpm --filter @objectstack/driver-sql
build` at head.
- This package emits `dist/index.d.ts` and `dist/index.d.mts` (there is
no `.d.cts`). The two are identical to each other at both ends.
- Raw sha256 of both files, base and head, all four the same:
`93da45168e82136b7613944525e47402d5dc6f9f8daa9efa4bdceeaa11b52a89` (cuts
1 and 2's hash, unchanged). The raw diff is 0 lines.
- Normalised with the ruling's one-liner verbatim (double-quoted
unions), base = head =
`93da45168e82136b7613944525e47402d5dc6f9f8daa9efa4bdceeaa11b52a89`. This
file has 0 double-quoted unions, so that normaliser rewrites nothing.
- Normalised with the same one-liner, with the quote character swapped
to a single quote (31 single-quoted unions match), base = head =
`118e992ad8aad590044eb31509dca65e6b321e3410ce846e1e5f5dd34b956e95`. With
a raw diff of 0 lines, the proof rests on raw identity, and neither
normaliser is relied on.
- Positive control on a copy of the head `dist/index.d.ts`: line 4282,
`protected assertBareKnexSafe(op: string): void;`, made public. That
gives raw and double-quote-normalised
`f492eb1c19c6832b1e13aee2f02596041b34c0252971720a0472a266c44eb7cc` and
single-quote-normalised
`8337de653b61ff24a59c29934ce1783051ba7c056523aa2e700107e9c69c6216`, each
different from the real hash.
- Export tables: the ESM and CJS bundles each export the same 56 names
at base and head, loaded at runtime (`import()` and `require` of the
built bundles). The sorted list hashes to
`d61a9dd3a02661602b1bb2dbe18152ac43986148f36b2746f40c0884bd8ffdec` on
all four.
- The head build carries the move: `dist/index.mjs` and `dist/index.js`
each contain 14 host `.call(` sites (8 at base, plus these 6).
No changeset: `skip-changeset`, per ruling `6348891160` item 4.
## Proof of move-only
- **Bodies, by AST token** (recursive `getChildren` leaves). Each moved
function's parameters (less the added `this`), return type and body have
the same token sequence as the base method, and `async` matches on all
six. 218 tokens compared, 0 differ.
- **Lines**: 38 lines compared, from each method's name to its closing
brace. Each one is the base line with two leading spaces removed (the
first line, less the added `this` parameter, is byte-identical).
- **Negative control**: changing one character inside a template literal
of `assertBareKnexSafe` in a copy of the module makes the check report 1
token and 1 line different, and it exits `PROOF FAILED`, exit 1.
- **Class side**: 347 members at base and head. The 341 members that did
not move are byte-identical to base, leading trivia included. Each of
the 6 stubs keeps its docblock and signature byte-identical, less
`async` on the five that had it.
- **Top level of `sql-driver.ts`**: all 201 base statements other than
the class are byte-identical, in order. The one new statement is the
import of the new module.
- **Size**: +177 / -31 over 2 files, far under the 3,000-line
manual-merge line. `sql-driver.ts` goes from 21,651 to 21,678 lines, and
`sql-driver-transactions.ts` has 119. See the acceptance notes on why
the file grows.
## Readers of `sql-driver.ts` by path, checked against the moved text
None needed an edit. Each was read against the moved region
(10899-10976) and run at both ends where it is a gate or test:
- **ADR anchors.**
`scripts/adr-anchors/packages__drivers__driver-sql__src__sql-driver.ts.json`
carries ADR-0053 (`formatOutput`, `presentReadValue`) and ADR-0120 D4.
Neither paragraph describes a moved body, so per card ask 3 the new
module gets no entry of its own. The moved bodies cite no ADR.
`check:adr-anchors`: 85 anchored files at base and head. Decision-letter
citations on the anchored surface: 1,849 at base and 1,849 at head.
- **Symbol anchors.** ADR-0119 anchors
`packages/drivers/driver-sql/src/sql-driver.ts#beginTransaction`. The
stub keeps that declaration in `sql-driver.ts`, so the anchor still
resolves. No other anchor names a moved member.
`check:adr-symbol-anchors`: 2,384 anchors resolve at both ends.
- **`check:tenant-chokepoint`** reads `sql-driver.ts` for `getBuilder`
bindings and for `IS NULL` arms in raw fragments. The moved text has
neither, so the gate still covers the same population: 24 `getBuilder()`
bindings across 3 files at both ends.
- **Logger receivers.** The moved text reads no logger.
`check:logger-receiver-detach`: 0 detaches at both ends (3,681 files
walked at head, one more than base: the new module).
- **Other source scans**, none of whose patterns occurs in the moved
text: `logger-receiver-detach.test.ts` ③,
`sql-driver-compile-refusal-seam.test.ts`, the five `packages/cli`
`generate-*.pin.test.ts` files, `check-keyed-text-bounds`
(`varcharColumnChars`), `check-object-def-param-keys` (the `initObjects`
parameter keys).
- **Path lists and comment citations** that name the file (`turbo.json`,
`scripts/cross-package-test-inputs.mjs`,
`scripts/pm/check-half-states.mjs`,
`scripts/check-changeset-no-major.mjs`, `packages/spec/liveness/*.json`
evidence, prose citations in `objectql`, `spec`, `driver-turso`). None
names a moved member.
- **`driver-turso`** and **`driver-sqlite-wasm`**: their readers of
moved members reach the stubs unchanged. Both suites ran at both ends
(below).
- `check:driver-conformance` at base and head: 55 covered, 0 in the DEBT
ledger, 0 exempt, both times.
## Verification
- `tsc --noEmit` (driver-sql) exit 0. `eslint --no-inline-config` on
both source files exit 0.
- `packages/drivers/driver-sql` suite: base 3,999 tests (3,787 passed, 0
failed, 212 skipped; 247 files), head the same. Compared per test name
and status from vitest's JSON reporter: no test lost, none changed
status, none added.
- `packages/drivers/driver-turso` suite, run against the rebuilt head
`dist`: base 2,526 tests (2,492 passed, 0 failed, 34 skipped; 95 files),
head the same. Per test name and status there is no difference (2,513
distinct names; 13 names repeat).
- `packages/drivers/driver-sqlite-wasm` suite, against the rebuilt head
`dist`: base 704 tests (704 passed; 39 files), head the same, per test
name no difference.
- `dispatch-gates --commands` on this diff, at head `59d63a8d1`: 55
derived commands, each run with its exit code. `--ran` reconciles 55
derived, 54 run, 1 NOT MEASURED, 0 unrun. The NOT MEASURED one is
`check:dual-build-cjs-loads` (exit 3, PREREQUISITE NOT MET: it needs
every package's `dist`), which CI runs. `check:lean-entry-closure` ran
after `objectql`'s closure was built.
- No reverse verification or ablation: the diff changes no tested
behaviour.
## Acceptance notes
- **The file grows by 27 lines.** The six bodies are short (the two
deprecated aliases are one line each), and each stub's host literal is
longer than the body it replaced. The cut moves the transaction logic
into its own module rather than shrinking the file. Every remaining cut
is larger than this one.
- `assertBareKnexSafe` now builds its host literal before the production
early return. Its docblock calls the guard zero-overhead on the hot
path. Its one caller is `ensureSequencesTable`'s lazy fallback (a write
that reaches the sequences table before `initObjects` created it), and
only when the runner is the bare `knex`, so this is not a hot path
today. The docblock is unchanged, because this cut is move-only.
- `TursoDriver`'s three overrides still call `super`, which now returns
the moved function's promise instead of an `async` method's promise. A
caller awaits the same settlement.
- ADR-0119 still says driver-sql implements `beginTransaction` at
`sql-driver.ts#beginTransaction`. That declaration is still there, and
the body is one module over. No `docs/adr/**` edit is made here.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01JVTd3PprStGa26aez5omLB)_
Co-authored-by: Claude <noreply@anthropic.com>
1 parent 5aafc82 commit 645ede5
2 files changed
Lines changed: 177 additions & 31 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
175 | 175 | | |
176 | 176 | | |
177 | 177 | | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
178 | 190 | | |
179 | 191 | | |
180 | 192 | | |
| |||
10900 | 10912 | | |
10901 | 10913 | | |
10902 | 10914 | | |
10903 | | - | |
10904 | | - | |
10905 | | - | |
10906 | | - | |
10907 | | - | |
| 10915 | + | |
| 10916 | + | |
| 10917 | + | |
| 10918 | + | |
| 10919 | + | |
| 10920 | + | |
| 10921 | + | |
| 10922 | + | |
| 10923 | + | |
| 10924 | + | |
| 10925 | + | |
| 10926 | + | |
| 10927 | + | |
10908 | 10928 | | |
10909 | 10929 | | |
10910 | 10930 | | |
| |||
10934 | 10954 | | |
10935 | 10955 | | |
10936 | 10956 | | |
10937 | | - | |
10938 | | - | |
10939 | | - | |
10940 | | - | |
10941 | | - | |
10942 | | - | |
10943 | | - | |
10944 | | - | |
10945 | | - | |
10946 | | - | |
| 10957 | + | |
| 10958 | + | |
| 10959 | + | |
| 10960 | + | |
| 10961 | + | |
| 10962 | + | |
| 10963 | + | |
| 10964 | + | |
| 10965 | + | |
10947 | 10966 | | |
10948 | 10967 | | |
10949 | 10968 | | |
10950 | | - | |
10951 | | - | |
10952 | | - | |
10953 | | - | |
10954 | | - | |
10955 | | - | |
| 10969 | + | |
| 10970 | + | |
| 10971 | + | |
| 10972 | + | |
| 10973 | + | |
| 10974 | + | |
10956 | 10975 | | |
10957 | 10976 | | |
10958 | 10977 | | |
10959 | | - | |
10960 | | - | |
10961 | | - | |
10962 | | - | |
10963 | | - | |
10964 | | - | |
| 10978 | + | |
| 10979 | + | |
| 10980 | + | |
| 10981 | + | |
| 10982 | + | |
| 10983 | + | |
10965 | 10984 | | |
10966 | 10985 | | |
10967 | 10986 | | |
10968 | | - | |
10969 | | - | |
| 10987 | + | |
| 10988 | + | |
| 10989 | + | |
| 10990 | + | |
| 10991 | + | |
| 10992 | + | |
10970 | 10993 | | |
10971 | 10994 | | |
10972 | 10995 | | |
10973 | | - | |
10974 | | - | |
| 10996 | + | |
| 10997 | + | |
| 10998 | + | |
| 10999 | + | |
| 11000 | + | |
| 11001 | + | |
10975 | 11002 | | |
10976 | 11003 | | |
10977 | 11004 | | |
| |||
0 commit comments