perf(datasource): size the primary SQL pool from OS_DATABASE_POOL_MAX

[claude]

Fixes#14176

Adds OS_DATABASE_POOL_MAX, the operator-facing ceiling for a postgres / mysql datasource's knex pool, read in buildSqlPool.

The card's root cause is falsified; the defect is real

The card blames SqlDriver.withConnectBound for setting no pool size, so knex's {min:2,max:10} default applies. Measured on origin/main, that is not what the primary datasource runs:

• buildSqlPool (packages/services/service-datasource/src/default-datasource-driver-factory.ts) hands everypostgres / mysql datasource an explicit {min: 0, max: 5} unless it declares its own pool block.
• The primary datasource — the one behind OS_DATABASE_URL — is composed by the CLI as config: { url, ...autoMigrate } with no pool (packages/cli/src/utils/storage-driver.ts, the postgres arm).

So the effective per-replica ceiling was 5, not 10, and SqlDriver never sees an "unspecified" pool from this path — an env read in the driver would have been dead code behind the factory's explicit object. The card's own connection counts corroborate 5 over 10: 3 replicas x 5 + admin/sampler is about the ~21 observed; three pools saturated at 10 would have shown ~30.

This matches the correction already recorded on the issue and the maintainer ruling of 2026-09-02 (option A).

What changed

buildSqlPool now resolves max as declared pool.max > OS_DATABASE_POOL_MAX > 5. It is the only site that decides the unspecified case, so the precedence is expressed once, and the driver needs no knowledge of the factory's choice.

• Unset changes nothing.{min: 0, max: 5}, byte-identical to today — that is the upgrade path for every existing deployment, and it is pinned by a test whose job is to go red if it ever drifts. A blank value reads as unset, so a declared-but-unfilled compose variable also keeps today's behaviour.
• A bad value refuses the boot, naming the variable, the value it rejected and the sizing rule — instead of the lenient Number(process.env.X ?? default) shape, where a typo becomes NaN and the operator trying to raise the ceiling silently keeps the one they meant to leave. A pool ceiling is only ever measured in production.
• OS_DATABASE_POOL_MIN is not exposed (ruling: this path already runs min: 0; a later patch if ever needed).
• Named OS_DATABASE_* per AGENTS.md Prime Directive 9 — DATABASE is the existing family (OS_DATABASE_URL, OS_DATABASE_DRIVER, OS_DATABASE_SQLITE_JOURNAL_MODE); OS_DB_* has zero hits in the repo.

What I measured, and what I did not

⚠️The cluster throughput numbers are the reporter's, not mine. The ~25 rps plateau, the ~9-21 of 200 Postgres connections and the 77.8% 503 rate come from a live 3-replica EE cluster on 2026-09-01. There is no cluster and no live database here, and a fabricated local rerun would be evidence of nothing. I did not re-measure them. What is pinned instead is the mechanism those numbers rest on: which pool size actually reaches knex.

Measured here:

• @objectstack/service-datasource suite: 0 failed | 635 passed without the new pin file, 0 failed | 643 passed (31 files) with it, at f82e7ada1.
• tsc --noEmit exit 0, with --listFiles confirming both the changed source and the new test are in the program (this package's tsconfig includes src, tests and all).
• Derived gate family (scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack): 59 commands, 55 exit 0. The 4 non-zero are all NOT MEASURED by their own verdict text, from unbuilt packages outside this diff's closure — check-test-completeness ("PREREQUISITE NOT MET ... ⛔ It is not a red"), check:dual-build-cjs-loads ("⛔ This is NOT a pass: nothing was measured"), check:type-check-debt ("⛔ This is NOT a pass and NOT a finding"), and check:skill-examples, which refuses because packages/client-react/dist is unbuilt and never reaches the docs surface.
• Repo-wide pnpm lint (eslint . --no-inline-config): exit 0, full population, no narrowing.

Ablation — the knob is load-bearing. With the change committed, buildSqlPool was mutated to drop the env read (marker injected as a globalThis property, not a comment). The mutation was confirmed on disk before running: deleted-text occurrences 1 to 0, injected marker 1, blob 5efad548 to 47abe72b. The pins then read 4 failed | 4 passed: the four knob pins went red, while the unset-default pin, the blank-value pin, the declared-pool-wins pin and the unsupported-arm pin stayed green — the predicted direction, since none of those four depends on the env wiring. Restore proved by blob equality with HEAD (5efad548), empty git diff HEAD, and zero leftover markers.

Resolution path: the tests import the factory by relative path, so they read TypeScript source, not dist — no rebuild leg applies, and the ablation moving the result with no rebuild in between demonstrates it.

Not touched, deliberately

• ⛔ POOL_UNSUPPORTED_DRIVER_IDS and the authoring-rejection path are untouched. memory / sqlite / sqlite-wasm / turso reject a declared pool under three maintainer rulings, and knex's better-sqlite3 dialect pins {min:1,max:1} on purpose. The env is read insidebuildSqlPool, which only the postgres / mysql arms call, so those arms structurally cannot see it — pinned by a test rather than asserted.
• ⛔ packages/drivers/** and packages/spec/** are untouched (read only).
• ⛔ The card's secondary observation — 503-shedding at conc>=150 and a bounded acquire-queue (availability: a datasource whose driver fails to start pins /api/v1/ready to 503 cluster-wide and is not evicted on delete — one bad tenant datasource drains every LB upstream #13408) — is out of scope and is not folded in.

Clause-2: yes

Derived from the diff, not recalled: git diff -U0 origin/main...HEAD | grep -E '^\+\s*export ' returns nothing (zero new exported symbols), and no declared spec key is added (packages/spec/** untouched). The change reads env inside an existing non-exported function.

Those mechanical indicators point no, and I am reporting them because they are real information for the reviewer — but the grading is still yes: the widening is the documented operator-facing environment variable itself, a permanent public configuration obligation, which is exactly what the maintainer already graded yes when ruling option A. A mechanical export-grep should not argue down a ruling that considered this precise change, and no would have been the convenient answer here rather than the right one.

Changeset: minor on @objectstack/service-datasource — a new operator capability, backward-compatible, no default moved.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-datasource, touching 7 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/environment-variables.mdx(via OS_DATABASE_POOL_MAX (literal, a string literal in POOL_MAX_ENV))

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 1 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 — the merge of head f82e7ada1f054467656ed84dfed9af37fc9a2012 into base df657d9df1fac5a2222f183008532613a1df585f, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 && git checkout d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f f82e7ada1f054467656ed84dfed9af37fc9a2012 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff f82e7ada1f054467656ed84dfed9af37fc9a2012
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs df657d9df1fac5a2222f183008532613a1df585f → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14176

Adds OS_DATABASE_POOL_MAX, the operator-facing ceiling for a postgres / mysql datasource's knex pool, read in buildSqlPool.

The card's root cause is falsified; the defect is real

The card blames SqlDriver.withConnectBound for setting no pool size, so knex's {min:2,max:10} default applies. Measured on origin/main, that is not what the primary datasource runs:

• buildSqlPool (packages/services/service-datasource/src/default-datasource-driver-factory.ts) hands everypostgres / mysql datasource an explicit {min: 0, max: 5} unless it declares its own pool block.
• The primary datasource — the one behind OS_DATABASE_URL — is composed by the CLI as config: { url, ...autoMigrate } with no pool (packages/cli/src/utils/storage-driver.ts, the postgres arm).

So the effective per-replica ceiling was 5, not 10, and SqlDriver never sees an "unspecified" pool from this path — an env read in the driver would have been dead code behind the factory's explicit object. The card's own connection counts corroborate 5 over 10: 3 replicas x 5 + admin/sampler is about the ~21 observed; three pools saturated at 10 would have shown ~30.

This matches the correction already recorded on the issue and the maintainer ruling of 2026-09-02 (option A).

What changed

buildSqlPool now resolves max as declared pool.max > OS_DATABASE_POOL_MAX > 5. It is the only site that decides the unspecified case, so the precedence is expressed once, and the driver needs no knowledge of the factory's choice.

• Unset changes nothing.{min: 0, max: 5}, byte-identical to today — that is the upgrade path for every existing deployment, and it is pinned by a test whose job is to go red if it ever drifts. A blank value reads as unset, so a declared-but-unfilled compose variable also keeps today's behaviour.
• A bad value refuses the boot, naming the variable, the value it rejected and the sizing rule — instead of the lenient Number(process.env.X ?? default) shape, where a typo becomes NaN and the operator trying to raise the ceiling silently keeps the one they meant to leave. A pool ceiling is only ever measured in production.
• OS_DATABASE_POOL_MIN is not exposed (ruling: this path already runs min: 0; a later patch if ever needed).
• Named OS_DATABASE_* per AGENTS.md Prime Directive 9 — DATABASE is the existing family (OS_DATABASE_URL, OS_DATABASE_DRIVER, OS_DATABASE_SQLITE_JOURNAL_MODE); OS_DB_* has zero hits in the repo.

What I measured, and what I did not

⚠️The cluster throughput numbers are the reporter's, not mine. The ~25 rps plateau, the ~9-21 of 200 Postgres connections and the 77.8% 503 rate come from a live 3-replica EE cluster on 2026-09-01. There is no cluster and no live database here, and a fabricated local rerun would be evidence of nothing. I did not re-measure them. What is pinned instead is the mechanism those numbers rest on: which pool size actually reaches knex.

Measured here:

• @objectstack/service-datasource suite: 0 failed | 635 passed without the new pin file, 0 failed | 643 passed (31 files) with it, at f82e7ada1.
• tsc --noEmit exit 0, with --listFiles confirming both the changed source and the new test are in the program (this package's tsconfig includes src, tests and all).
• Derived gate family (scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack): 59 commands, 55 exit 0. The 4 non-zero are all NOT MEASURED by their own verdict text, from unbuilt packages outside this diff's closure — check-test-completeness ("PREREQUISITE NOT MET ... ⛔ It is not a red"), check:dual-build-cjs-loads ("⛔ This is NOT a pass: nothing was measured"), check:type-check-debt ("⛔ This is NOT a pass and NOT a finding"), and check:skill-examples, which refuses because packages/client-react/dist is unbuilt and never reaches the docs surface.
• Repo-wide pnpm lint (eslint . --no-inline-config): exit 0, full population, no narrowing.

Ablation — the knob is load-bearing. With the change committed, buildSqlPool was mutated to drop the env read (marker injected as a globalThis property, not a comment). The mutation was confirmed on disk before running: deleted-text occurrences 1 to 0, injected marker 1, blob 5efad548 to 47abe72b. The pins then read 4 failed | 4 passed: the four knob pins went red, while the unset-default pin, the blank-value pin, the declared-pool-wins pin and the unsupported-arm pin stayed green — the predicted direction, since none of those four depends on the env wiring. Restore proved by blob equality with HEAD (5efad548), empty git diff HEAD, and zero leftover markers.

Resolution path: the tests import the factory by relative path, so they read TypeScript source, not dist — no rebuild leg applies, and the ablation moving the result with no rebuild in between demonstrates it.

Not touched, deliberately

• ⛔ POOL_UNSUPPORTED_DRIVER_IDS and the authoring-rejection path are untouched. memory / sqlite / sqlite-wasm / turso reject a declared pool under three maintainer rulings, and knex's better-sqlite3 dialect pins {min:1,max:1} on purpose. The env is read insidebuildSqlPool, which only the postgres / mysql arms call, so those arms structurally cannot see it — pinned by a test rather than asserted.
• ⛔ packages/drivers/** and packages/spec/** are untouched (read only).
• ⛔ The card's secondary observation — 503-shedding at conc>=150 and a bounded acquire-queue (availability: a datasource whose driver fails to start pins /api/v1/ready to 503 cluster-wide and is not evicted on delete — one bad tenant datasource drains every LB upstream #13408) — is out of scope and is not folded in.

Clause-2: yes

Derived from the diff, not recalled: git diff -U0 origin/main...HEAD | grep -E '^\+\s*export ' returns nothing (zero new exported symbols), and no declared spec key is added (packages/spec/** untouched). The change reads env inside an existing non-exported function.

Those mechanical indicators point no, and I am reporting them because they are real information for the reviewer — but the grading is still yes: the widening is the documented operator-facing environment variable itself, a permanent public configuration obligation, which is exactly what the maintainer already graded yes when ruling option A. A mechanical export-grep should not argue down a ruling that considered this precise change, and no would have been the convenient answer here rather than the right one.

Changeset: minor on @objectstack/service-datasource — a new operator capability, backward-compatible, no default moved.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-datasource, touching 7 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/environment-variables.mdx(via OS_DATABASE_POOL_MAX (literal, a string literal in POOL_MAX_ENV))

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 1 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 — the merge of head f82e7ada1f054467656ed84dfed9af37fc9a2012 into base df657d9df1fac5a2222f183008532613a1df585f, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 && git checkout d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f f82e7ada1f054467656ed84dfed9af37fc9a2012 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff f82e7ada1f054467656ed84dfed9af37fc9a2012
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs df657d9df1fac5a2222f183008532613a1df585f → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14176

Adds OS_DATABASE_POOL_MAX, the operator-facing ceiling for a postgres / mysql datasource's knex pool, read in buildSqlPool.

The card's root cause is falsified; the defect is real

The card blames SqlDriver.withConnectBound for setting no pool size, so knex's {min:2,max:10} default applies. Measured on origin/main, that is not what the primary datasource runs:

• buildSqlPool (packages/services/service-datasource/src/default-datasource-driver-factory.ts) hands everypostgres / mysql datasource an explicit {min: 0, max: 5} unless it declares its own pool block.
• The primary datasource — the one behind OS_DATABASE_URL — is composed by the CLI as config: { url, ...autoMigrate } with no pool (packages/cli/src/utils/storage-driver.ts, the postgres arm).

So the effective per-replica ceiling was 5, not 10, and SqlDriver never sees an "unspecified" pool from this path — an env read in the driver would have been dead code behind the factory's explicit object. The card's own connection counts corroborate 5 over 10: 3 replicas x 5 + admin/sampler is about the ~21 observed; three pools saturated at 10 would have shown ~30.

This matches the correction already recorded on the issue and the maintainer ruling of 2026-09-02 (option A).

What changed

buildSqlPool now resolves max as declared pool.max > OS_DATABASE_POOL_MAX > 5. It is the only site that decides the unspecified case, so the precedence is expressed once, and the driver needs no knowledge of the factory's choice.

• Unset changes nothing.{min: 0, max: 5}, byte-identical to today — that is the upgrade path for every existing deployment, and it is pinned by a test whose job is to go red if it ever drifts. A blank value reads as unset, so a declared-but-unfilled compose variable also keeps today's behaviour.
• A bad value refuses the boot, naming the variable, the value it rejected and the sizing rule — instead of the lenient Number(process.env.X ?? default) shape, where a typo becomes NaN and the operator trying to raise the ceiling silently keeps the one they meant to leave. A pool ceiling is only ever measured in production.
• OS_DATABASE_POOL_MIN is not exposed (ruling: this path already runs min: 0; a later patch if ever needed).
• Named OS_DATABASE_* per AGENTS.md Prime Directive 9 — DATABASE is the existing family (OS_DATABASE_URL, OS_DATABASE_DRIVER, OS_DATABASE_SQLITE_JOURNAL_MODE); OS_DB_* has zero hits in the repo.

What I measured, and what I did not

⚠️The cluster throughput numbers are the reporter's, not mine. The ~25 rps plateau, the ~9-21 of 200 Postgres connections and the 77.8% 503 rate come from a live 3-replica EE cluster on 2026-09-01. There is no cluster and no live database here, and a fabricated local rerun would be evidence of nothing. I did not re-measure them. What is pinned instead is the mechanism those numbers rest on: which pool size actually reaches knex.

Measured here:

• @objectstack/service-datasource suite: 0 failed | 635 passed without the new pin file, 0 failed | 643 passed (31 files) with it, at f82e7ada1.
• tsc --noEmit exit 0, with --listFiles confirming both the changed source and the new test are in the program (this package's tsconfig includes src, tests and all).
• Derived gate family (scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack): 59 commands, 55 exit 0. The 4 non-zero are all NOT MEASURED by their own verdict text, from unbuilt packages outside this diff's closure — check-test-completeness ("PREREQUISITE NOT MET ... ⛔ It is not a red"), check:dual-build-cjs-loads ("⛔ This is NOT a pass: nothing was measured"), check:type-check-debt ("⛔ This is NOT a pass and NOT a finding"), and check:skill-examples, which refuses because packages/client-react/dist is unbuilt and never reaches the docs surface.
• Repo-wide pnpm lint (eslint . --no-inline-config): exit 0, full population, no narrowing.

Ablation — the knob is load-bearing. With the change committed, buildSqlPool was mutated to drop the env read (marker injected as a globalThis property, not a comment). The mutation was confirmed on disk before running: deleted-text occurrences 1 to 0, injected marker 1, blob 5efad548 to 47abe72b. The pins then read 4 failed | 4 passed: the four knob pins went red, while the unset-default pin, the blank-value pin, the declared-pool-wins pin and the unsupported-arm pin stayed green — the predicted direction, since none of those four depends on the env wiring. Restore proved by blob equality with HEAD (5efad548), empty git diff HEAD, and zero leftover markers.

Resolution path: the tests import the factory by relative path, so they read TypeScript source, not dist — no rebuild leg applies, and the ablation moving the result with no rebuild in between demonstrates it.

Not touched, deliberately

• ⛔ POOL_UNSUPPORTED_DRIVER_IDS and the authoring-rejection path are untouched. memory / sqlite / sqlite-wasm / turso reject a declared pool under three maintainer rulings, and knex's better-sqlite3 dialect pins {min:1,max:1} on purpose. The env is read insidebuildSqlPool, which only the postgres / mysql arms call, so those arms structurally cannot see it — pinned by a test rather than asserted.
• ⛔ packages/drivers/** and packages/spec/** are untouched (read only).
• ⛔ The card's secondary observation — 503-shedding at conc>=150 and a bounded acquire-queue (availability: a datasource whose driver fails to start pins /api/v1/ready to 503 cluster-wide and is not evicted on delete — one bad tenant datasource drains every LB upstream #13408) — is out of scope and is not folded in.

Clause-2: yes

Derived from the diff, not recalled: git diff -U0 origin/main...HEAD | grep -E '^\+\s*export ' returns nothing (zero new exported symbols), and no declared spec key is added (packages/spec/** untouched). The change reads env inside an existing non-exported function.

Those mechanical indicators point no, and I am reporting them because they are real information for the reviewer — but the grading is still yes: the widening is the documented operator-facing environment variable itself, a permanent public configuration obligation, which is exactly what the maintainer already graded yes when ruling option A. A mechanical export-grep should not argue down a ruling that considered this precise change, and no would have been the convenient answer here rather than the right one.

Changeset: minor on @objectstack/service-datasource — a new operator capability, backward-compatible, no default moved.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-datasource, touching 7 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/environment-variables.mdx(via OS_DATABASE_POOL_MAX (literal, a string literal in POOL_MAX_ENV))

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 1 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 — the merge of head f82e7ada1f054467656ed84dfed9af37fc9a2012 into base df657d9df1fac5a2222f183008532613a1df585f, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 && git checkout d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f f82e7ada1f054467656ed84dfed9af37fc9a2012 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff f82e7ada1f054467656ed84dfed9af37fc9a2012
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs df657d9df1fac5a2222f183008532613a1df585f → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14176

Adds OS_DATABASE_POOL_MAX, the operator-facing ceiling for a postgres / mysql datasource's knex pool, read in buildSqlPool.

The card's root cause is falsified; the defect is real

The card blames SqlDriver.withConnectBound for setting no pool size, so knex's {min:2,max:10} default applies. Measured on origin/main, that is not what the primary datasource runs:

• buildSqlPool (packages/services/service-datasource/src/default-datasource-driver-factory.ts) hands everypostgres / mysql datasource an explicit {min: 0, max: 5} unless it declares its own pool block.
• The primary datasource — the one behind OS_DATABASE_URL — is composed by the CLI as config: { url, ...autoMigrate } with no pool (packages/cli/src/utils/storage-driver.ts, the postgres arm).

So the effective per-replica ceiling was 5, not 10, and SqlDriver never sees an "unspecified" pool from this path — an env read in the driver would have been dead code behind the factory's explicit object. The card's own connection counts corroborate 5 over 10: 3 replicas x 5 + admin/sampler is about the ~21 observed; three pools saturated at 10 would have shown ~30.

This matches the correction already recorded on the issue and the maintainer ruling of 2026-09-02 (option A).

What changed

buildSqlPool now resolves max as declared pool.max > OS_DATABASE_POOL_MAX > 5. It is the only site that decides the unspecified case, so the precedence is expressed once, and the driver needs no knowledge of the factory's choice.

• Unset changes nothing.{min: 0, max: 5}, byte-identical to today — that is the upgrade path for every existing deployment, and it is pinned by a test whose job is to go red if it ever drifts. A blank value reads as unset, so a declared-but-unfilled compose variable also keeps today's behaviour.
• A bad value refuses the boot, naming the variable, the value it rejected and the sizing rule — instead of the lenient Number(process.env.X ?? default) shape, where a typo becomes NaN and the operator trying to raise the ceiling silently keeps the one they meant to leave. A pool ceiling is only ever measured in production.
• OS_DATABASE_POOL_MIN is not exposed (ruling: this path already runs min: 0; a later patch if ever needed).
• Named OS_DATABASE_* per AGENTS.md Prime Directive 9 — DATABASE is the existing family (OS_DATABASE_URL, OS_DATABASE_DRIVER, OS_DATABASE_SQLITE_JOURNAL_MODE); OS_DB_* has zero hits in the repo.

What I measured, and what I did not

⚠️The cluster throughput numbers are the reporter's, not mine. The ~25 rps plateau, the ~9-21 of 200 Postgres connections and the 77.8% 503 rate come from a live 3-replica EE cluster on 2026-09-01. There is no cluster and no live database here, and a fabricated local rerun would be evidence of nothing. I did not re-measure them. What is pinned instead is the mechanism those numbers rest on: which pool size actually reaches knex.

Measured here:

• @objectstack/service-datasource suite: 0 failed | 635 passed without the new pin file, 0 failed | 643 passed (31 files) with it, at f82e7ada1.
• tsc --noEmit exit 0, with --listFiles confirming both the changed source and the new test are in the program (this package's tsconfig includes src, tests and all).
• Derived gate family (scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack): 59 commands, 55 exit 0. The 4 non-zero are all NOT MEASURED by their own verdict text, from unbuilt packages outside this diff's closure — check-test-completeness ("PREREQUISITE NOT MET ... ⛔ It is not a red"), check:dual-build-cjs-loads ("⛔ This is NOT a pass: nothing was measured"), check:type-check-debt ("⛔ This is NOT a pass and NOT a finding"), and check:skill-examples, which refuses because packages/client-react/dist is unbuilt and never reaches the docs surface.
• Repo-wide pnpm lint (eslint . --no-inline-config): exit 0, full population, no narrowing.

Ablation — the knob is load-bearing. With the change committed, buildSqlPool was mutated to drop the env read (marker injected as a globalThis property, not a comment). The mutation was confirmed on disk before running: deleted-text occurrences 1 to 0, injected marker 1, blob 5efad548 to 47abe72b. The pins then read 4 failed | 4 passed: the four knob pins went red, while the unset-default pin, the blank-value pin, the declared-pool-wins pin and the unsupported-arm pin stayed green — the predicted direction, since none of those four depends on the env wiring. Restore proved by blob equality with HEAD (5efad548), empty git diff HEAD, and zero leftover markers.

Resolution path: the tests import the factory by relative path, so they read TypeScript source, not dist — no rebuild leg applies, and the ablation moving the result with no rebuild in between demonstrates it.

Not touched, deliberately

• ⛔ POOL_UNSUPPORTED_DRIVER_IDS and the authoring-rejection path are untouched. memory / sqlite / sqlite-wasm / turso reject a declared pool under three maintainer rulings, and knex's better-sqlite3 dialect pins {min:1,max:1} on purpose. The env is read insidebuildSqlPool, which only the postgres / mysql arms call, so those arms structurally cannot see it — pinned by a test rather than asserted.
• ⛔ packages/drivers/** and packages/spec/** are untouched (read only).
• ⛔ The card's secondary observation — 503-shedding at conc>=150 and a bounded acquire-queue (availability: a datasource whose driver fails to start pins /api/v1/ready to 503 cluster-wide and is not evicted on delete — one bad tenant datasource drains every LB upstream #13408) — is out of scope and is not folded in.

Clause-2: yes

Derived from the diff, not recalled: git diff -U0 origin/main...HEAD | grep -E '^\+\s*export ' returns nothing (zero new exported symbols), and no declared spec key is added (packages/spec/** untouched). The change reads env inside an existing non-exported function.

Those mechanical indicators point no, and I am reporting them because they are real information for the reviewer — but the grading is still yes: the widening is the documented operator-facing environment variable itself, a permanent public configuration obligation, which is exactly what the maintainer already graded yes when ruling option A. A mechanical export-grep should not argue down a ruling that considered this precise change, and no would have been the convenient answer here rather than the right one.

Changeset: minor on @objectstack/service-datasource — a new operator capability, backward-compatible, no default moved.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-datasource, touching 7 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/environment-variables.mdx(via OS_DATABASE_POOL_MAX (literal, a string literal in POOL_MAX_ENV))

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 1 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 — the merge of head f82e7ada1f054467656ed84dfed9af37fc9a2012 into base df657d9df1fac5a2222f183008532613a1df585f, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 && git checkout d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f f82e7ada1f054467656ed84dfed9af37fc9a2012 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff f82e7ada1f054467656ed84dfed9af37fc9a2012
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs df657d9df1fac5a2222f183008532613a1df585f → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14176

Adds OS_DATABASE_POOL_MAX, the operator-facing ceiling for a postgres / mysql datasource's knex pool, read in buildSqlPool.

The card's root cause is falsified; the defect is real

The card blames SqlDriver.withConnectBound for setting no pool size, so knex's {min:2,max:10} default applies. Measured on origin/main, that is not what the primary datasource runs:

• buildSqlPool (packages/services/service-datasource/src/default-datasource-driver-factory.ts) hands everypostgres / mysql datasource an explicit {min: 0, max: 5} unless it declares its own pool block.
• The primary datasource — the one behind OS_DATABASE_URL — is composed by the CLI as config: { url, ...autoMigrate } with no pool (packages/cli/src/utils/storage-driver.ts, the postgres arm).

So the effective per-replica ceiling was 5, not 10, and SqlDriver never sees an "unspecified" pool from this path — an env read in the driver would have been dead code behind the factory's explicit object. The card's own connection counts corroborate 5 over 10: 3 replicas x 5 + admin/sampler is about the ~21 observed; three pools saturated at 10 would have shown ~30.

This matches the correction already recorded on the issue and the maintainer ruling of 2026-09-02 (option A).

What changed

buildSqlPool now resolves max as declared pool.max > OS_DATABASE_POOL_MAX > 5. It is the only site that decides the unspecified case, so the precedence is expressed once, and the driver needs no knowledge of the factory's choice.

• Unset changes nothing.{min: 0, max: 5}, byte-identical to today — that is the upgrade path for every existing deployment, and it is pinned by a test whose job is to go red if it ever drifts. A blank value reads as unset, so a declared-but-unfilled compose variable also keeps today's behaviour.
• A bad value refuses the boot, naming the variable, the value it rejected and the sizing rule — instead of the lenient Number(process.env.X ?? default) shape, where a typo becomes NaN and the operator trying to raise the ceiling silently keeps the one they meant to leave. A pool ceiling is only ever measured in production.
• OS_DATABASE_POOL_MIN is not exposed (ruling: this path already runs min: 0; a later patch if ever needed).
• Named OS_DATABASE_* per AGENTS.md Prime Directive 9 — DATABASE is the existing family (OS_DATABASE_URL, OS_DATABASE_DRIVER, OS_DATABASE_SQLITE_JOURNAL_MODE); OS_DB_* has zero hits in the repo.

What I measured, and what I did not

⚠️The cluster throughput numbers are the reporter's, not mine. The ~25 rps plateau, the ~9-21 of 200 Postgres connections and the 77.8% 503 rate come from a live 3-replica EE cluster on 2026-09-01. There is no cluster and no live database here, and a fabricated local rerun would be evidence of nothing. I did not re-measure them. What is pinned instead is the mechanism those numbers rest on: which pool size actually reaches knex.

Measured here:

• @objectstack/service-datasource suite: 0 failed | 635 passed without the new pin file, 0 failed | 643 passed (31 files) with it, at f82e7ada1.
• tsc --noEmit exit 0, with --listFiles confirming both the changed source and the new test are in the program (this package's tsconfig includes src, tests and all).
• Derived gate family (scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack): 59 commands, 55 exit 0. The 4 non-zero are all NOT MEASURED by their own verdict text, from unbuilt packages outside this diff's closure — check-test-completeness ("PREREQUISITE NOT MET ... ⛔ It is not a red"), check:dual-build-cjs-loads ("⛔ This is NOT a pass: nothing was measured"), check:type-check-debt ("⛔ This is NOT a pass and NOT a finding"), and check:skill-examples, which refuses because packages/client-react/dist is unbuilt and never reaches the docs surface.
• Repo-wide pnpm lint (eslint . --no-inline-config): exit 0, full population, no narrowing.

Ablation — the knob is load-bearing. With the change committed, buildSqlPool was mutated to drop the env read (marker injected as a globalThis property, not a comment). The mutation was confirmed on disk before running: deleted-text occurrences 1 to 0, injected marker 1, blob 5efad548 to 47abe72b. The pins then read 4 failed | 4 passed: the four knob pins went red, while the unset-default pin, the blank-value pin, the declared-pool-wins pin and the unsupported-arm pin stayed green — the predicted direction, since none of those four depends on the env wiring. Restore proved by blob equality with HEAD (5efad548), empty git diff HEAD, and zero leftover markers.

Resolution path: the tests import the factory by relative path, so they read TypeScript source, not dist — no rebuild leg applies, and the ablation moving the result with no rebuild in between demonstrates it.

Not touched, deliberately

• ⛔ POOL_UNSUPPORTED_DRIVER_IDS and the authoring-rejection path are untouched. memory / sqlite / sqlite-wasm / turso reject a declared pool under three maintainer rulings, and knex's better-sqlite3 dialect pins {min:1,max:1} on purpose. The env is read insidebuildSqlPool, which only the postgres / mysql arms call, so those arms structurally cannot see it — pinned by a test rather than asserted.
• ⛔ packages/drivers/** and packages/spec/** are untouched (read only).
• ⛔ The card's secondary observation — 503-shedding at conc>=150 and a bounded acquire-queue (availability: a datasource whose driver fails to start pins /api/v1/ready to 503 cluster-wide and is not evicted on delete — one bad tenant datasource drains every LB upstream #13408) — is out of scope and is not folded in.

Clause-2: yes

Derived from the diff, not recalled: git diff -U0 origin/main...HEAD | grep -E '^\+\s*export ' returns nothing (zero new exported symbols), and no declared spec key is added (packages/spec/** untouched). The change reads env inside an existing non-exported function.

Those mechanical indicators point no, and I am reporting them because they are real information for the reviewer — but the grading is still yes: the widening is the documented operator-facing environment variable itself, a permanent public configuration obligation, which is exactly what the maintainer already graded yes when ruling option A. A mechanical export-grep should not argue down a ruling that considered this precise change, and no would have been the convenient answer here rather than the right one.

Changeset: minor on @objectstack/service-datasource — a new operator capability, backward-compatible, no default moved.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-datasource, touching 7 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/environment-variables.mdx(via OS_DATABASE_POOL_MAX (literal, a string literal in POOL_MAX_ENV))

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 1 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 — the merge of head f82e7ada1f054467656ed84dfed9af37fc9a2012 into base df657d9df1fac5a2222f183008532613a1df585f, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 && git checkout d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f f82e7ada1f054467656ed84dfed9af37fc9a2012 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff f82e7ada1f054467656ed84dfed9af37fc9a2012
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs df657d9df1fac5a2222f183008532613a1df585f → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14176

Adds OS_DATABASE_POOL_MAX, the operator-facing ceiling for a postgres / mysql datasource's knex pool, read in buildSqlPool.

The card's root cause is falsified; the defect is real

The card blames SqlDriver.withConnectBound for setting no pool size, so knex's {min:2,max:10} default applies. Measured on origin/main, that is not what the primary datasource runs:

• buildSqlPool (packages/services/service-datasource/src/default-datasource-driver-factory.ts) hands everypostgres / mysql datasource an explicit {min: 0, max: 5} unless it declares its own pool block.
• The primary datasource — the one behind OS_DATABASE_URL — is composed by the CLI as config: { url, ...autoMigrate } with no pool (packages/cli/src/utils/storage-driver.ts, the postgres arm).

So the effective per-replica ceiling was 5, not 10, and SqlDriver never sees an "unspecified" pool from this path — an env read in the driver would have been dead code behind the factory's explicit object. The card's own connection counts corroborate 5 over 10: 3 replicas x 5 + admin/sampler is about the ~21 observed; three pools saturated at 10 would have shown ~30.

This matches the correction already recorded on the issue and the maintainer ruling of 2026-09-02 (option A).

What changed

buildSqlPool now resolves max as declared pool.max > OS_DATABASE_POOL_MAX > 5. It is the only site that decides the unspecified case, so the precedence is expressed once, and the driver needs no knowledge of the factory's choice.

• Unset changes nothing.{min: 0, max: 5}, byte-identical to today — that is the upgrade path for every existing deployment, and it is pinned by a test whose job is to go red if it ever drifts. A blank value reads as unset, so a declared-but-unfilled compose variable also keeps today's behaviour.
• A bad value refuses the boot, naming the variable, the value it rejected and the sizing rule — instead of the lenient Number(process.env.X ?? default) shape, where a typo becomes NaN and the operator trying to raise the ceiling silently keeps the one they meant to leave. A pool ceiling is only ever measured in production.
• OS_DATABASE_POOL_MIN is not exposed (ruling: this path already runs min: 0; a later patch if ever needed).
• Named OS_DATABASE_* per AGENTS.md Prime Directive 9 — DATABASE is the existing family (OS_DATABASE_URL, OS_DATABASE_DRIVER, OS_DATABASE_SQLITE_JOURNAL_MODE); OS_DB_* has zero hits in the repo.

What I measured, and what I did not

⚠️The cluster throughput numbers are the reporter's, not mine. The ~25 rps plateau, the ~9-21 of 200 Postgres connections and the 77.8% 503 rate come from a live 3-replica EE cluster on 2026-09-01. There is no cluster and no live database here, and a fabricated local rerun would be evidence of nothing. I did not re-measure them. What is pinned instead is the mechanism those numbers rest on: which pool size actually reaches knex.

Measured here:

• @objectstack/service-datasource suite: 0 failed | 635 passed without the new pin file, 0 failed | 643 passed (31 files) with it, at f82e7ada1.
• tsc --noEmit exit 0, with --listFiles confirming both the changed source and the new test are in the program (this package's tsconfig includes src, tests and all).
• Derived gate family (scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack): 59 commands, 55 exit 0. The 4 non-zero are all NOT MEASURED by their own verdict text, from unbuilt packages outside this diff's closure — check-test-completeness ("PREREQUISITE NOT MET ... ⛔ It is not a red"), check:dual-build-cjs-loads ("⛔ This is NOT a pass: nothing was measured"), check:type-check-debt ("⛔ This is NOT a pass and NOT a finding"), and check:skill-examples, which refuses because packages/client-react/dist is unbuilt and never reaches the docs surface.
• Repo-wide pnpm lint (eslint . --no-inline-config): exit 0, full population, no narrowing.

Ablation — the knob is load-bearing. With the change committed, buildSqlPool was mutated to drop the env read (marker injected as a globalThis property, not a comment). The mutation was confirmed on disk before running: deleted-text occurrences 1 to 0, injected marker 1, blob 5efad548 to 47abe72b. The pins then read 4 failed | 4 passed: the four knob pins went red, while the unset-default pin, the blank-value pin, the declared-pool-wins pin and the unsupported-arm pin stayed green — the predicted direction, since none of those four depends on the env wiring. Restore proved by blob equality with HEAD (5efad548), empty git diff HEAD, and zero leftover markers.

Resolution path: the tests import the factory by relative path, so they read TypeScript source, not dist — no rebuild leg applies, and the ablation moving the result with no rebuild in between demonstrates it.

Not touched, deliberately

• ⛔ POOL_UNSUPPORTED_DRIVER_IDS and the authoring-rejection path are untouched. memory / sqlite / sqlite-wasm / turso reject a declared pool under three maintainer rulings, and knex's better-sqlite3 dialect pins {min:1,max:1} on purpose. The env is read insidebuildSqlPool, which only the postgres / mysql arms call, so those arms structurally cannot see it — pinned by a test rather than asserted.
• ⛔ packages/drivers/** and packages/spec/** are untouched (read only).
• ⛔ The card's secondary observation — 503-shedding at conc>=150 and a bounded acquire-queue (availability: a datasource whose driver fails to start pins /api/v1/ready to 503 cluster-wide and is not evicted on delete — one bad tenant datasource drains every LB upstream #13408) — is out of scope and is not folded in.

Clause-2: yes

Derived from the diff, not recalled: git diff -U0 origin/main...HEAD | grep -E '^\+\s*export ' returns nothing (zero new exported symbols), and no declared spec key is added (packages/spec/** untouched). The change reads env inside an existing non-exported function.

Those mechanical indicators point no, and I am reporting them because they are real information for the reviewer — but the grading is still yes: the widening is the documented operator-facing environment variable itself, a permanent public configuration obligation, which is exactly what the maintainer already graded yes when ruling option A. A mechanical export-grep should not argue down a ruling that considered this precise change, and no would have been the convenient answer here rather than the right one.

Changeset: minor on @objectstack/service-datasource — a new operator capability, backward-compatible, no default moved.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-datasource, touching 7 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/environment-variables.mdx(via OS_DATABASE_POOL_MAX (literal, a string literal in POOL_MAX_ENV))

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 1 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 — the merge of head f82e7ada1f054467656ed84dfed9af37fc9a2012 into base df657d9df1fac5a2222f183008532613a1df585f, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 && git checkout d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f f82e7ada1f054467656ed84dfed9af37fc9a2012 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff f82e7ada1f054467656ed84dfed9af37fc9a2012
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs df657d9df1fac5a2222f183008532613a1df585f → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14176

Adds OS_DATABASE_POOL_MAX, the operator-facing ceiling for a postgres / mysql datasource's knex pool, read in buildSqlPool.

The card's root cause is falsified; the defect is real

The card blames SqlDriver.withConnectBound for setting no pool size, so knex's {min:2,max:10} default applies. Measured on origin/main, that is not what the primary datasource runs:

• buildSqlPool (packages/services/service-datasource/src/default-datasource-driver-factory.ts) hands everypostgres / mysql datasource an explicit {min: 0, max: 5} unless it declares its own pool block.
• The primary datasource — the one behind OS_DATABASE_URL — is composed by the CLI as config: { url, ...autoMigrate } with no pool (packages/cli/src/utils/storage-driver.ts, the postgres arm).

So the effective per-replica ceiling was 5, not 10, and SqlDriver never sees an "unspecified" pool from this path — an env read in the driver would have been dead code behind the factory's explicit object. The card's own connection counts corroborate 5 over 10: 3 replicas x 5 + admin/sampler is about the ~21 observed; three pools saturated at 10 would have shown ~30.

This matches the correction already recorded on the issue and the maintainer ruling of 2026-09-02 (option A).

What changed

buildSqlPool now resolves max as declared pool.max > OS_DATABASE_POOL_MAX > 5. It is the only site that decides the unspecified case, so the precedence is expressed once, and the driver needs no knowledge of the factory's choice.

• Unset changes nothing.{min: 0, max: 5}, byte-identical to today — that is the upgrade path for every existing deployment, and it is pinned by a test whose job is to go red if it ever drifts. A blank value reads as unset, so a declared-but-unfilled compose variable also keeps today's behaviour.
• A bad value refuses the boot, naming the variable, the value it rejected and the sizing rule — instead of the lenient Number(process.env.X ?? default) shape, where a typo becomes NaN and the operator trying to raise the ceiling silently keeps the one they meant to leave. A pool ceiling is only ever measured in production.
• OS_DATABASE_POOL_MIN is not exposed (ruling: this path already runs min: 0; a later patch if ever needed).
• Named OS_DATABASE_* per AGENTS.md Prime Directive 9 — DATABASE is the existing family (OS_DATABASE_URL, OS_DATABASE_DRIVER, OS_DATABASE_SQLITE_JOURNAL_MODE); OS_DB_* has zero hits in the repo.

What I measured, and what I did not

⚠️The cluster throughput numbers are the reporter's, not mine. The ~25 rps plateau, the ~9-21 of 200 Postgres connections and the 77.8% 503 rate come from a live 3-replica EE cluster on 2026-09-01. There is no cluster and no live database here, and a fabricated local rerun would be evidence of nothing. I did not re-measure them. What is pinned instead is the mechanism those numbers rest on: which pool size actually reaches knex.

Measured here:

• @objectstack/service-datasource suite: 0 failed | 635 passed without the new pin file, 0 failed | 643 passed (31 files) with it, at f82e7ada1.
• tsc --noEmit exit 0, with --listFiles confirming both the changed source and the new test are in the program (this package's tsconfig includes src, tests and all).
• Derived gate family (scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack): 59 commands, 55 exit 0. The 4 non-zero are all NOT MEASURED by their own verdict text, from unbuilt packages outside this diff's closure — check-test-completeness ("PREREQUISITE NOT MET ... ⛔ It is not a red"), check:dual-build-cjs-loads ("⛔ This is NOT a pass: nothing was measured"), check:type-check-debt ("⛔ This is NOT a pass and NOT a finding"), and check:skill-examples, which refuses because packages/client-react/dist is unbuilt and never reaches the docs surface.
• Repo-wide pnpm lint (eslint . --no-inline-config): exit 0, full population, no narrowing.

Ablation — the knob is load-bearing. With the change committed, buildSqlPool was mutated to drop the env read (marker injected as a globalThis property, not a comment). The mutation was confirmed on disk before running: deleted-text occurrences 1 to 0, injected marker 1, blob 5efad548 to 47abe72b. The pins then read 4 failed | 4 passed: the four knob pins went red, while the unset-default pin, the blank-value pin, the declared-pool-wins pin and the unsupported-arm pin stayed green — the predicted direction, since none of those four depends on the env wiring. Restore proved by blob equality with HEAD (5efad548), empty git diff HEAD, and zero leftover markers.

Resolution path: the tests import the factory by relative path, so they read TypeScript source, not dist — no rebuild leg applies, and the ablation moving the result with no rebuild in between demonstrates it.

Not touched, deliberately

• ⛔ POOL_UNSUPPORTED_DRIVER_IDS and the authoring-rejection path are untouched. memory / sqlite / sqlite-wasm / turso reject a declared pool under three maintainer rulings, and knex's better-sqlite3 dialect pins {min:1,max:1} on purpose. The env is read insidebuildSqlPool, which only the postgres / mysql arms call, so those arms structurally cannot see it — pinned by a test rather than asserted.
• ⛔ packages/drivers/** and packages/spec/** are untouched (read only).
• ⛔ The card's secondary observation — 503-shedding at conc>=150 and a bounded acquire-queue (availability: a datasource whose driver fails to start pins /api/v1/ready to 503 cluster-wide and is not evicted on delete — one bad tenant datasource drains every LB upstream #13408) — is out of scope and is not folded in.

Clause-2: yes

Derived from the diff, not recalled: git diff -U0 origin/main...HEAD | grep -E '^\+\s*export ' returns nothing (zero new exported symbols), and no declared spec key is added (packages/spec/** untouched). The change reads env inside an existing non-exported function.

Those mechanical indicators point no, and I am reporting them because they are real information for the reviewer — but the grading is still yes: the widening is the documented operator-facing environment variable itself, a permanent public configuration obligation, which is exactly what the maintainer already graded yes when ruling option A. A mechanical export-grep should not argue down a ruling that considered this precise change, and no would have been the convenient answer here rather than the right one.

Changeset: minor on @objectstack/service-datasource — a new operator capability, backward-compatible, no default moved.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-datasource, touching 7 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/environment-variables.mdx(via OS_DATABASE_POOL_MAX (literal, a string literal in POOL_MAX_ENV))

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 1 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 — the merge of head f82e7ada1f054467656ed84dfed9af37fc9a2012 into base df657d9df1fac5a2222f183008532613a1df585f, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 && git checkout d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f f82e7ada1f054467656ed84dfed9af37fc9a2012 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff f82e7ada1f054467656ed84dfed9af37fc9a2012
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs df657d9df1fac5a2222f183008532613a1df585f → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14176

Adds OS_DATABASE_POOL_MAX, the operator-facing ceiling for a postgres / mysql datasource's knex pool, read in buildSqlPool.

The card's root cause is falsified; the defect is real

The card blames SqlDriver.withConnectBound for setting no pool size, so knex's {min:2,max:10} default applies. Measured on origin/main, that is not what the primary datasource runs:

• buildSqlPool (packages/services/service-datasource/src/default-datasource-driver-factory.ts) hands everypostgres / mysql datasource an explicit {min: 0, max: 5} unless it declares its own pool block.
• The primary datasource — the one behind OS_DATABASE_URL — is composed by the CLI as config: { url, ...autoMigrate } with no pool (packages/cli/src/utils/storage-driver.ts, the postgres arm).

So the effective per-replica ceiling was 5, not 10, and SqlDriver never sees an "unspecified" pool from this path — an env read in the driver would have been dead code behind the factory's explicit object. The card's own connection counts corroborate 5 over 10: 3 replicas x 5 + admin/sampler is about the ~21 observed; three pools saturated at 10 would have shown ~30.

This matches the correction already recorded on the issue and the maintainer ruling of 2026-09-02 (option A).

What changed

buildSqlPool now resolves max as declared pool.max > OS_DATABASE_POOL_MAX > 5. It is the only site that decides the unspecified case, so the precedence is expressed once, and the driver needs no knowledge of the factory's choice.

• Unset changes nothing.{min: 0, max: 5}, byte-identical to today — that is the upgrade path for every existing deployment, and it is pinned by a test whose job is to go red if it ever drifts. A blank value reads as unset, so a declared-but-unfilled compose variable also keeps today's behaviour.
• A bad value refuses the boot, naming the variable, the value it rejected and the sizing rule — instead of the lenient Number(process.env.X ?? default) shape, where a typo becomes NaN and the operator trying to raise the ceiling silently keeps the one they meant to leave. A pool ceiling is only ever measured in production.
• OS_DATABASE_POOL_MIN is not exposed (ruling: this path already runs min: 0; a later patch if ever needed).
• Named OS_DATABASE_* per AGENTS.md Prime Directive 9 — DATABASE is the existing family (OS_DATABASE_URL, OS_DATABASE_DRIVER, OS_DATABASE_SQLITE_JOURNAL_MODE); OS_DB_* has zero hits in the repo.

What I measured, and what I did not

⚠️The cluster throughput numbers are the reporter's, not mine. The ~25 rps plateau, the ~9-21 of 200 Postgres connections and the 77.8% 503 rate come from a live 3-replica EE cluster on 2026-09-01. There is no cluster and no live database here, and a fabricated local rerun would be evidence of nothing. I did not re-measure them. What is pinned instead is the mechanism those numbers rest on: which pool size actually reaches knex.

Measured here:

• @objectstack/service-datasource suite: 0 failed | 635 passed without the new pin file, 0 failed | 643 passed (31 files) with it, at f82e7ada1.
• tsc --noEmit exit 0, with --listFiles confirming both the changed source and the new test are in the program (this package's tsconfig includes src, tests and all).
• Derived gate family (scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack): 59 commands, 55 exit 0. The 4 non-zero are all NOT MEASURED by their own verdict text, from unbuilt packages outside this diff's closure — check-test-completeness ("PREREQUISITE NOT MET ... ⛔ It is not a red"), check:dual-build-cjs-loads ("⛔ This is NOT a pass: nothing was measured"), check:type-check-debt ("⛔ This is NOT a pass and NOT a finding"), and check:skill-examples, which refuses because packages/client-react/dist is unbuilt and never reaches the docs surface.
• Repo-wide pnpm lint (eslint . --no-inline-config): exit 0, full population, no narrowing.

Ablation — the knob is load-bearing. With the change committed, buildSqlPool was mutated to drop the env read (marker injected as a globalThis property, not a comment). The mutation was confirmed on disk before running: deleted-text occurrences 1 to 0, injected marker 1, blob 5efad548 to 47abe72b. The pins then read 4 failed | 4 passed: the four knob pins went red, while the unset-default pin, the blank-value pin, the declared-pool-wins pin and the unsupported-arm pin stayed green — the predicted direction, since none of those four depends on the env wiring. Restore proved by blob equality with HEAD (5efad548), empty git diff HEAD, and zero leftover markers.

Resolution path: the tests import the factory by relative path, so they read TypeScript source, not dist — no rebuild leg applies, and the ablation moving the result with no rebuild in between demonstrates it.

Not touched, deliberately

• ⛔ POOL_UNSUPPORTED_DRIVER_IDS and the authoring-rejection path are untouched. memory / sqlite / sqlite-wasm / turso reject a declared pool under three maintainer rulings, and knex's better-sqlite3 dialect pins {min:1,max:1} on purpose. The env is read insidebuildSqlPool, which only the postgres / mysql arms call, so those arms structurally cannot see it — pinned by a test rather than asserted.
• ⛔ packages/drivers/** and packages/spec/** are untouched (read only).
• ⛔ The card's secondary observation — 503-shedding at conc>=150 and a bounded acquire-queue (availability: a datasource whose driver fails to start pins /api/v1/ready to 503 cluster-wide and is not evicted on delete — one bad tenant datasource drains every LB upstream #13408) — is out of scope and is not folded in.

Clause-2: yes

Derived from the diff, not recalled: git diff -U0 origin/main...HEAD | grep -E '^\+\s*export ' returns nothing (zero new exported symbols), and no declared spec key is added (packages/spec/** untouched). The change reads env inside an existing non-exported function.

Those mechanical indicators point no, and I am reporting them because they are real information for the reviewer — but the grading is still yes: the widening is the documented operator-facing environment variable itself, a permanent public configuration obligation, which is exactly what the maintainer already graded yes when ruling option A. A mechanical export-grep should not argue down a ruling that considered this precise change, and no would have been the convenient answer here rather than the right one.

Changeset: minor on @objectstack/service-datasource — a new operator capability, backward-compatible, no default moved.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-datasource, touching 7 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/environment-variables.mdx(via OS_DATABASE_POOL_MAX (literal, a string literal in POOL_MAX_ENV))

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 1 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 — the merge of head f82e7ada1f054467656ed84dfed9af37fc9a2012 into base df657d9df1fac5a2222f183008532613a1df585f, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3 && git checkout d3d5c70ab838c5a0cf444f6b6a7cd77e247124e3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f f82e7ada1f054467656ed84dfed9af37fc9a2012 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff f82e7ada1f054467656ed84dfed9af37fc9a2012
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs df657d9df1fac5a2222f183008532613a1df585f → pass the list as
args.docs, on the commit named under Which tree this was computed on.