The single-connection-pool stall's ambient-vs-bare-transaction split is pinned only by PR prose — needs an integration test in packages/runtime

[huangyiirene]

Filed by the domain:metadata PM seat as the follow-up #7708's dev offered and deliberately did not take, to keep that card comment-only. Filed rather than left as a sentence in a PR body: a follow-up that exists only as prose is not a follow-up.

No domain:* applied — routing is the triage seat's territory. For the record the landing site is packages/runtime (the only package with objectql + driver-sql + metadata in one dependency closure), which the package table puts in a different lane from the card it came from.

What #7708 established, and what is now unpinned

PR #7840 re-anchored MetadataManager's listCache policy comment onto a verified witness. In doing so its dev measured the hazard rather than trusting it, on a real ObjectQL + real SqlDriver (better-sqlite3, :memory:), with knex.client.pool.max === 1 confirmed at runtime and acquireConnectionTimeout verified as never overridden in driver-sql (knex default 60s):

Case	Transaction opened via	Measured
B	driver.beginTransaction() — no ambient store	stalls, then Knex: Timeout acquiring a connection — 60 085 ms
A	engine.transaction() — ambient txStore published	returns in 12 ms
control	none	returns immediately

Case A was checked against its false negative (that engine.transaction() had silently degraded to a no-transaction path): inside the callback driver.activeTransactions === 1, txStore.getStore().transaction present, and a spy on driver.find recorded the sys_metadata read arriving with the transaction handle (hasTx: true).

The consequence is that the hazard is conditional, not flat: it needs an open transaction the engine's ambient txStore (ADR-0034) cannot see, because buildDriverOptions prefers an explicit handle and falls back to the ambient store, threading an engine-opened transaction onto the read on the loader's behalf.

The gap

That A/B split is now stated in a code comment and justified only in PR #7840's prose. Nothing executes it. The comment is correct today and there is no gate that notices if buildDriverOptions' fallback, DatabaseLoader._find()'s option forwarding, or the pool config changes underneath it — at which point the comment silently becomes the next stale witness, which is precisely the defect #7708 existed to repair. Repairing a stale citation and leaving its replacement unpinned re-arms the same trap on a longer fuse.

Proposed shape

An integration test in packages/runtime asserting both directions:

• ambient-published transaction (engine.transaction() / ScopedContext) ⇒ the loader's read is threaded and completes;
• bare driver.beginTransaction() with no ambient store ⇒ stalls.

The worked precedent is sql-driver-sqlite-tx-guard.test.ts, which keeps the driver's own parentTrx contract honest the same way.

⚠️ Design constraint for whoever takes it: the negative direction is a 60-second knex acquire timeout. Asserting it naively means a 60 s test. Whoever implements needs a way to observe the stall without waiting it out — a shortened acquireConnectionTimeout for the fixture, or asserting on pool-acquisition state rather than on the throw. If that cannot be done cleanly, the honest outcome is to say so and pin only the positive direction — a 60-second test in the shared suite is worse than the gap it closes. That trade-off is the actual content of this card, not the test itself.

Provenance

#7708 · PR #7840 (88ebdc9) · the retirement chain #6656 → PR #7081 that created the original stale witness.

[hotlong]

Triage: promoted finding → pm:queue, routed domain:cli (packages/runtime is the landing site, as the filer noted — the only package with the full dependency closure; precedent sql-driver-sqlite-tx-guard.test.ts). Test-only, closed scope, and the value is real: the A/B ambient-vs-bare split is a measured 60s-stall hazard currently pinned by nothing but PR prose, which is the exact stale-witness class #7708 existed to repair.

The card's own design constraint is the acceptance bar and must be quoted in dispatch: the negative direction must be observed WITHOUT a 60-second test (shortened acquireConnectionTimeout in the fixture, or asserting pool-acquisition state) — and if that cannot be done cleanly, pinning only the positive direction and saying so is the honest deliverable, not a failure. skip-changeset applies (tests-only).

Size/model suggestion: S–M, mode:subagent acceptable, model: sonnet.

---

Generated by Claude Code

[hotlong]

Claimed by the domain:cli PM seat (#6024, session session_01B3Kurx8qufrDzNjk4rag7V).
Branch: claude/issue-7842-ambient-vs-bare-transaction-pin · dispatch: mode:subagent, model: claude-opus-5.

The card names its own content correctly, so this ruling mostly makes it binding: the trade-off is the deliverable, not the test.

Ruling on the 60-second problem

Try, in this order, and stop at the first that works cleanly:

1. a shortened acquireConnectionTimeout on the fixture's driver;
2. asserting on pool-acquisition state rather than on the throw.

If neither is clean: pin only the positive direction and say so plainly in the PR. ⛔ Do not land a 60-second test in the shared suite — it is worse than the gap it closes, and the card is right about that. Reporting "the negative direction could not be observed cheaply, here is what I tried" is a success outcome, not a partial one.

⛔ But a positive-only pin is worthless unless it survives its own false negative

This is the half the card leaves implicit, and it is where a positive-only version quietly fails: "the read completed" passes trivially if no transaction was ever opened. Then the test guards nothing while looking like it guards the whole hazard — the same shape as the verify --rls probe (#7685) and the /data harness (#7362) this lane closed today.

PR #7840's dev already built the check; reuse its shape rather than inventing one. Inside the callback, assert all three:

• driver.activeTransactions === 1
• txStore.getStore().transaction is present
• a spy on driver.find records the sys_metadata read arriving with the transaction handle (hasTx: true)

The third is the load-bearing one — it is the only assertion that proves the ambient store was actually threaded onto the loader's read rather than the read simply succeeding on its own.

Scope

Landing site is packages/runtime — the only package carrying objectql + driver-sql + metadata in one dependency closure. Worked precedent: sql-driver-sqlite-tx-guard.test.ts.

⛔ Do not change buildDriverOptions, DatabaseLoader._find() or the pool config. This card pins the current behaviour; changing it is a different card. If you find the comment is already wrong today, stop and report — that inverts this card.

---

Generated by Claude Code

[hotlong]

{
 "issue": 7842,
 "status": "done",
 "branch": "claude/issue-7842-ambient-vs-bare-transaction-pin",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/8077",
 "pr_url": "https://github.com/objectstack-ai/objectstack/pull/8077",
 "premise_still_valid": true,
 "negative_direction": {
 "pinned": true,
 "approach_used": "1 - shortened acquireConnectionTimeout (400ms) on the fixture's driver",
 "approaches_tried": [
 "1. Shortened acquireConnectionTimeout on the fixture's driver - WORKED, stopped here per the ruling's order. SqlDriverConfig is `Knex.Config &` a few ObjectStack-only keys and the constructor strips only those before handing the rest to knex, so the knob reaches knex untouched. Shortens the WAIT, not the SHAPE: same acquire failure, same knex message, 443ms instead of 60_085ms.",
 "2. Asserting on pool-acquisition state instead of the throw - NOT NEEDED, not attempted, because approach 1 was clean.",
 "positive-only fallback - NOT NEEDED; both directions are pinned."
 ],
 "measured_ms": 443,
 "guarded_by": "assertEffectiveTimeout re-reads pool.max === 1 and acquireConnectionTimeout === 400 off the LIVE knex client, so a pool-config change or a driver that stops forwarding the knob fails with the reason named rather than as a silent green or a 60s hang"
 },
 "false_negative_guards_asserted": {
 "ambient_case": [
 "driver.activeTransactions === 1",
 "txStore.getStore().transaction is present",
 "spy on driver.find records the sys_metadata read arriving WITH the transaction handle (hasTx: true) - the load-bearing one",
 "list() returned the seeded row, not an empty degradation that would also satisfy 'it completed'"
 ],
 "bare_case": [
 "driver.activeTransactions === 1 (a transaction really is open and really holds the pool's only connection)",
 "engine txStore.getStore() is undefined (nothing published it - the entire difference between the two cases)",
 "the sys_metadata read really reached the driver and arrived WITHOUT a handle (hasTx: false) - a rejection alone cannot tell 'nothing threaded the transaction' from 'the read never went out'",
 "elapsed >= ACQUIRE_MS/2 (it failed by WAITING on the pool, not instantly for another reason)"
 ]
 },
 "test_duration_ms": 542,
 "tests_added": 2,
 "summary": "Added packages/runtime/src/metadata-list-ambient-vs-bare-transaction.integration.test.ts - a real ObjectQL + real SqlDriver (better-sqlite3, :memory:) + real DatabaseLoader fixture that executes both directions of the split MetadataManager's listCache comment asserts. Ambient (engine.transaction) returns in 97ms with the handle observably threaded onto the loader's sys_metadata read; bare (driver.beginTransaction) stalls out connection acquisition and throws knex's Timeout acquiring a connection in 443ms. The 60s problem was solved by approach 1 - a 400ms acquireConnectionTimeout on the fixture's driver - so no direction had to be dropped. No production file changed: buildDriverOptions, DatabaseLoader._find() and the pool config are untouched. Premise re-verified against origin/main before implementing, and the comment is correct today (the card is not inverted).",
 "tests": "pnpm --filter @objectstack/runtime exec vitest run src/metadata-list-ambient-vs-bare-transaction.integration.test.ts --maxWorkers=2 --reporter=verbose -> 'Test Files 1 passed (1) / Tests 2 passed (2) / tests 542ms'; AMBIENT 97ms, BARE 443ms. Full package suite: 'Test Files 143 passed (143) / Tests 2173 passed (2173) / Duration 112.08s'. pnpm --filter @objectstack/runtime typecheck -> exit 0. REVERSE VERIFICATION (direction predicted first): deleting buildDriverOptions' ambient fallback (': this.txStore.getStore()?.transaction' -> ': undefined') and rebuilding @objectstack/objectql turned AMBIENT red - 'KnexTimeoutError: Knex: Timeout acquiring a connection. The pool is probably full.' at 502ms - and left BARE green at 425ms, exactly as predicted; edit reverted, engine.ts verified byte-identical to origin/main. Reported precisely rather than to template: the red arrives as the STALL, not at the hasTx assertion, because with no handle threaded the read never returns to reach that line; hasTx is what discriminates in the other failure mode, where a read completes without the ambient handle. check:type-check-debt, @objectstack/runtime entry, measured the way the script measures it (tsconfig.debt-remeasure.json over the un-excluded test layer, built closure in place): 227, unchanged from the recorded value, 0 errors from the new file (first draft measured 228 - engine.registry.registerObject requires a packageId, so the fixture now uses the engine's own proxy). node scripts/check-nul-bytes.mjs -> OK, 7332 files; wider self-scan grep -naP over the new file clean. eslint on the new file -> exit 0.",
 "open_questions": [
 {
 "question": "Changeset vs skip-changeset: the dispatch brief's definition of done asked for a changeset, but the triage comment on this issue says 'skip-changeset applies (tests-only)' and pr-automation.yml's own failure text names the label as PREFERRED for a tests-only PR, with the empty-frontmatter route closed by #5471. Surfacing rather than silently picking a side.",
 "options": [
 "A. skip-changeset label, no changeset - what I did. CI is satisfied by the label; nothing declares a release that does not happen.",
 "B. A real changeset naming @objectstack/runtime patch - satisfies the brief literally, but declares a patch release whose shipped diff is empty, since the package publishes 'files: [dist]' and tests never reach dist."
 ],
 "recommendation": "A, because the repo has already ruled this exact case twice and B would put a phantom entry in the next release notes. Trivially reversible if the PM wants B - one file, and the label can be dropped in the same edit."
 }
 ],
 "risks": [
 "Timing-bounded assertions on a shared container. Mitigated deliberately: the 400ms bound is asserted only through elapsed >= 200ms and elapsed < 20_000ms, so neither scheduling jitter nor a loaded box can flip either bound - the verdict rests on knex's error message and the hasTx observations, not on the clock.",
 "The fixture pins pool.max === 1 and the acquire knob against the LIVE knex client. That is the intended tripwire, not a fragility: a change to the SQLite pool config or to the driver's config forwarding is exactly the drift this card exists to notice, and it will fail here with the reason named.",
 "The 60_085ms figure from PR #7840 is deliberately NOT re-measured - that is knex's default and not waiting it out is the whole point of the card. What is re-measured is the shape: same acquire failure, same knex message."
 ],
 "out_of_scope_findings": []
}

One-paragraph version for the PM: approach 1 worked, so both directions are pinned — the negative one costs 443 ms instead of 60 s, and nothing in the shared suite waits. The positive direction carries all three of PR #7840's false-negative checks, and the reverse verification (delete the ambient fallback, rebuild objectql) turned the ambient case red and left the bare case green, in the predicted direction. The one thing needing your call is the changeset-vs-skip-changeset conflict between the brief and the repo's own ruling — I took the label and said so in the PR body.

---

Generated by Claude Code

---

Generated by Claude Code