test(client): pay four auth suites' cold start at module scope, outside every clocked window

[objectstack-fleet]

Fixes #20327

Clause-②: no

Four packages/client suites paid the worker's one-time cold start inside their first clocked test window: better-auth's lazily imported module graph, the sql.js WASM compile, and the first-use costs of the sync and the sign-up. One of them, auth-get-session-envelope.test.ts, timed out at 5000 ms on the required Test Core (5/6) shard of PR #20325, whose diff does not reach the package. This PR ports PR #20272's shape to all four: each file pays its own arrangement once at module scope, during collection, which no vitest clock covers, and pins that placement. auth-rotated-session-token.test.ts also loses its seven explicit 60_000 per-case timeouts. No other number is raised, and there is no retry, skip or quarantine. The diff is four test files.

This card carries the family (triage note 2): the census below covers all 50 packages/client/src/*.test.ts files.

Premise check (on origin/main at c74de10a9)

Holds. In auth-get-session-envelope.test.ts, the first case calls await signedIn() inside its it (:262-:264), and every case builds a fresh SqliteWasmDriver engine, a real AuthManager, and five of the seven perform a real sign-up. premise_still_valid: true.

The red CI run itself (job 108717176436) shows the same shape in two more files of the family:

suite, in the red Test Core (5/6) run	first case	later cases doing the same arrangement
auth-get-session-envelope	timed out at 5000 ms	583-1255 ms
organization-invitation-resend-team-placement	3599 ms	486-820 ms
organization-invite-role-default	2849 ms	497-820 ms

Census: every packages/client/src/*.test.ts (50 files)

The criterion (dispatch, Zone 2): a suite that boots an engine (a SqliteWasmDriver engine, a real AuthManager, or a real sign-up) inside its first clocked it, or in a beforeAll/beforeEach.

files	shape	verdict
auth-get-session-envelope	7 cases, all through signedIn()/anonymous(): fresh engine + real AuthManager; default 5000 ms; the first case paid the cold start	included
auth-rotated-session-token	7 cases, all through signedIn(); an explicit 60_000 on all 7 cases, which widened the first case's window instead of moving the cost out	included; the 60_000s removed
organization-invitation-resend-team-placement	5 of 11 cases through arrange() (fresh engine, real AuthManager, real sign-up, an org and a team); default 5000 ms; ① paid the cold start	included
organization-invite-role-default	3 of 6 cases through arrange(); default 5000 ms; ① paid the cold start	included
auth-login-register-envelope	same shape	already fixed by PR #20272 (80c29a14); not edited
client.hono, client.batch-transaction, client.data-prefix, client.environment-scoping, client.metadata-prefix	a LiteKernel + ObjectQL + SqliteWasmDriver REST/Hono server booted ONCE per file (per describe in the two *-prefix files) as a shared fixture in a beforeAll with an explicit 30_000 hookTimeout; no AuthManager, no sign-up	excluded: the claim's file surface is suites that boot inside their first clocked it, and a hook-booted shared fixture is a different shape (the boot IS the fixture). Reach: in the red CI run all five passed; under 24 busy loops on this box all five passed (1 run). Their hook duration is NOT MEASURED: vitest's JSON file span does not include it. Noted, not filed.
meta-delete-item-carriers	a SqliteWasmDriver engine + the real protocol + RestServer booted inside it, but only from the 14th case on (Part 2); its first 13 cases are mock-fetch; an explicit 60_000 on all 7 engine cases; no AuthManager, no sign-up	excluded: its first clocked it is a mock case, so it is outside the claim's file surface as written. Its first engine case is not where a cold start sits heavily: 137 ms idle against 38-194 ms for the later engine cases, and 810 ms against 312-1204 ms under 24 busy loops. Its 60_000s widen windows that measured under 1.3 s. Noted, not filed.
i18n-wire-dialect	a LiteKernel + HonoServerPlugin in a beforeAll, no driver, no auth	excluded: boots no engine
the other 38	mock fetch, source-text reads, or type-level assertions; client.test.ts's sign-up cases are fetch-level; oauth-applications-* and organization-get-active-member-addressing drive doubles	excluded: no engine

Count: 4 included, 1 already fixed, 45 excluded.

What changed

Per file, the same three moves as PR #20272:

• A module-scope warm-up that runs the file's OWN arrangement, not a list of loads:
  • auth-get-session-envelope: await signedIn(); await closeEngines();
  • auth-rotated-session-token: await signedIn(); await closeEngines();
  • the two organization suites: process.env.OS_TENANCY_POSTURE = 'isolated'; then await arrange().finally(restorePosture);. arrange() needs the posture the file's beforeAll sets for its cases, and the module scope runs before any hook, so the warm-up holds the posture itself and .finally puts back what it found, even if it throws.
• The teardown the warm-up reuses is extracted without changing it: closeEngines is the old afterEach loop byte for byte (in auth-rotated-session-token the afterEach keeps its vi.restoreAllMocks() and calls closeEngines); restorePosture is the old afterAll body byte for byte.
• A placement pin per file (⑥, or ④ in auth-rotated-session-token), read off the file's own text:
  • exactly one column-0 warm-up line, so it sits in no function body;
  • in auth-get-session-envelope, no before* hook at all (as in PR test(client): pay the auth-envelope suite's cold start at module scope, outside every clocked window #20272's ⑦);
  • in the three files that keep a legitimate hook (the console-spy beforeEach, the posture beforeAll), exactly one hook, and no hook body calls the arrangement. A hook indented inside a describe is read on to that block's column-0 close, so it cannot hide one;
  • in auth-rotated-session-token, also no }, N); per-case timeout, so the widened posture cannot come back.
• A header section per file with that file's own readings.

No assertion in an existing case changed. The warm-up shares nothing a case asserts on: every case still builds a fresh engine, a fresh AuthManager and a fresh sign-up. What it leaves warm is process-level (the module registry, sql.js's compiled WASM, the JIT), which the first case used to leave to every later case. In the two organization suites the warm-up's engine stays open, as every case's does there (arrange() hands none back and those files close none), so no case runs in a state no case ran in before.

Why module scope and not a hook or a timeout: @vitest/runner@4.1.11, as installed here, wraps hooks and test bodies in withTimeout(...) (dist/chunk-artifact.js:672, :724, :1787) and awaits runner.importFile(filepath, "collect") bare (:2457). The repo's rule is "clocked windows measure behaviour, never loading" (AGENTS.md, Build & Test; check:test-source-alias).

Before / after, at CI's own 5000 ms budget

Idle (4 vCPU, the box otherwise quiet), first case against the later cases of the same file:

suite	base c74de10a9	fix 49bd6fdfa
auth-get-session-envelope	1035 vs 110-330 ms	316 vs 90-277 ms
auth-rotated-session-token	1713 vs 302-665 ms	809 vs 278-581 ms
organization-invitation-resend-team-placement	1245 vs 307-411 ms	332 vs 284-399 ms
organization-invite-role-default	968 vs 310-336 ms	382 vs 329-340 ms

Under load, PR #20272's method: CPU-bound node -e 'for(;;){}' loops on 4 vCPU, PIDs recorded and killed by trap. One vitest run per leg over the four files, --maxWorkers=2. On the base tree, 24 loops gave CI's exact signature, Test timed out in 5000ms on the first case, in all three default-budget suites (1 run); auth-rotated-session-token's first case took 10314 ms there, green only because of its 60_000.

Measured as interleaved pairs: an ABLATED leg (the four warm-ups deleted from the committed files) and a FIX leg (the committed files), same command, same load, order alternated between pairs. The box is shared, so interleaving puts its drift on both sides.

./node_modules/.bin/vitest run --maxWorkers=2 --reporter=verbose --reporter=json --outputFile.json=RUN.json FOUR_FILES

24 busy loops, N = 4 pairs	ablated: first-case timeouts	fix: first-case timeouts	fix: first case	fix: heaviest other case
auth-get-session-envelope	4 / 4	0 / 4	1969-2536 ms	1979-2751 ms
auth-rotated-session-token	4 / 4	4 / 4 (see below)	5034-5319 ms	3440-4771 ms
organization-invitation-resend-team-placement	4 / 4	0 / 4	1577-3095 ms	2523-3086 ms
organization-invite-role-default	4 / 4	0 / 4	2359-2575 ms	2056-2271 ms

16 busy loops, N = 2 pairs	ablated: first-case timeouts	fix: first-case timeouts	fix: first case
auth-get-session-envelope	1 / 2 (4816, 5134 ms)	0 / 2	1320-1523 ms
auth-rotated-session-token	2 / 2 (5053, 5229 ms)	0 / 2	4125-4185 ms
organization-invitation-resend-team-placement	1 / 2 (4752, 5113 ms)	0 / 2	1853-1904 ms
organization-invite-role-default	0 / 2 (4663, 4903 ms)	0 / 2	1429-1611 ms

Every ablated leg also reddened all four placement pins (4 of 4, in all 6 ablated legs). Every fix leg's pins passed. In one ablated leg, organization-invitation-resend-team-placement's second case also timed out (5121 ms): vitest does not cancel a timed-out body, so the first case's orphaned body was still running beside it. No fix leg showed that.

auth-rotated-session-token: the 60_000s are gone, and its first case is heavy by its own work

Triage note 3 and the dispatch both rule out a raised timeout, so all seven 60_000s are removed. With the cold start moved out, six of the seven cases fit the default budget at both loads. The first case (①) does not fit at 24 busy loops, and that is its own behaviour, not loading:

• ① is the card's whole probe: a sign-up plus five more calls that each check a password or a TOTP code (login, enable, verifyTotp, disable, deleteUser).
• A throwaway variant whose module-scope warm-up ran that WHOLE probe left ① no faster: 637-716 ms against 690-709 ms for the committed warm-up (3 runs each, idle, the file alone). So no loading is left in its window.

basis	①	margin to 5000 ms
idle, fix	690-809 ms	6.2-7.2x
the red CI run's own slowdown on warm cases (auth-get-session-envelope's same-work cases ran 2.9-5.9x their idle time)	about 2.0-4.8 s (inferred, not measured)	about 1.0-2.5x
16 busy loops, fix (2 runs)	4125-4185 ms	1.2x
24 busy loops, fix (4 runs)	5034-5319 ms	reached, 4 of 4

Before this PR the same case held a 10.3 s window at 24 busy loops (cold start plus this work) under its 60_000. The file's header records this residual and names the lever: the case's own work, not a timeout. The open question in the report asks the seat whether to accept it as is.

Ablation (fix committed first, restore proven)

The fix was committed (49bd6fdfa) before any mutation. Each ablated leg nested four node scripts/ablation-replace.mjs --file ABS_PATH --anchor ANCHOR --delete -- ... calls (WRAP mode, restore armed on EXIT, INT and TERM), one per file:

• auth-get-session-envelope, auth-rotated-session-token: the anchor await signedIn(); + newline + await closeEngines(); + newline;
• the two organization suites: the posture line + newline + await arrange().finally(restorePosture); + newline.

In every leg the tool reported, per file, anchor x1 to x0, a changed blob, and "ok mutation landed" (24 of 24), and the leg printed warm-up lines=0 (of 4 files) read off the disk before vitest started. After every leg the tool proved each restore by blob hash against HEAD and an empty git diff HEAD (24 of 24), and a second check after each leg read 4/4 blob == HEAD blob, git diff HEAD = 0 bytes (12 of 12 legs). The files run from source, so no dist/ preflight applies.

Verification

All at 220735eb3: the fix 49bd6fdfa, two commits that only edit header comments, and a merge of origin/main at d498113b5. The branch delta against it is exactly the four test files, +321 / -23. Every exit code was captured before any pipe. The union below was first run at 5a9a01d00 and then run again in full at 220735eb3, after the last commit corrected a count in a comment. Both runs gave the same verdicts.

• After the merge: pnpm install --frozen-lockfile, then the dependency closure pnpm turbo run build --filter='@objectstack/client...' --concurrency=2, 33 of 33 tasks.
• pnpm --filter @objectstack/client exec vitest run --maxWorkers=2: Test Files 50 passed (50), Tests 641 passed (641) (637 before, plus the 4 pins), exit 0.
• pnpm --filter @objectstack/client typecheck: exit 0, check:test-typecheck: OK, 0 files / 0 errors. tsc -p tsconfig.test.json --listFilesOnly compiles all four files (4 hits), so that green covers them.
• node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran RAN_LIST (every line with its recorded exit code): 53 derived famil(ies) accounted for — 51 run, 2 NOT-MEASURED, 0 UNRUN, and each of the 51 run exited 0.
  • NOT MEASURED: check:dual-build-cjs-loads and check:type-check-debt. Both exited 3 (PREREQUISITE NOT MET): they need every package's dist/, the whole ./packages/* build. A declared narrowing; CI runs both. This diff is four test files, which no build emits (the dist/ check is under Changeset), and @objectstack/client's test-layer debt ledger is empty and re-measured just above at 0 errors.
  • check:skill-examples exited 3 until its prerequisite was met: first packages/client-react/dist was absent, then packages/client/dist was older than an edited src/ file. After pnpm turbo run build --filter=@objectstack/client-react and pnpm --filter @objectstack/client build, the same command exited 0: 259 prose examples across 3 surfaces.
• node scripts/check-issue-citations.mjs --base origin/main: exit 0. It judged 0 files: test files are on its deferred list.
• pnpm lint (eslint . --no-inline-config, the whole repo, not a narrowing): exit 0.
• Control-byte self-scan of the four files: no hits (check:nul-bytes also exit 0).

Changeset

skip-changeset. The diff is four *.test.ts files. @objectstack/client's files[] is dist, README.md, CHANGELOG.md. After pnpm --filter @objectstack/client build at 220735eb3, strings unique to these test files (closeEngines, restorePosture, cold start stays outside, OS_TENANCY_POSTURE) have 0 hits under packages/client/dist/, while the positive control ObjectStackClient hits all 4 emitted artifacts (index.js, index.mjs, index.d.ts, index.d.mts). No published byte changes.

Acceptance notes

• auth-rotated-session-token.test.ts ① residual (section above): at 24 busy loops it reaches the 5000 ms budget on its own work, 4 of 4 runs; at 16 loops it fits with 1.2x. CI has not run it on the default budget before this PR. If CI reds it, the lever is that case's own work (for example splitting the probe, which would change the card's own probe and needs a ruling), not a timeout. Its second-heaviest cases (changePassword with revokeOtherSessions, and twoFactor.disable) reached 4.7-4.8 s at 24 loops.
• meta-delete-item-carriers.test.ts carries an explicit 60_000 on all 7 of its engine cases, the posture the clocked-window rule warns relocates a cliff. Measured, those windows are small (under 1.3 s at 24 busy loops) and its first engine case holds little one-time cost, so it is no timeout risk today. Outside this card's surface. Noted, not filed.
• The five hook-booted client.* suites boot a shared server in a beforeAll with an explicit 30_000 hookTimeout. They passed in the red CI run and under 24 busy loops here. Their hook time is not measured. Outside this card's surface. Noted, not filed.
• The two organization suites never close their engines, before or after this PR (arrange() hands none back). The warm-up adds one more open in-memory engine per file, as each of their cases does. Noted, not filed.
• The measurement box was shared: the verify lock serialises locked runs only, and other worktrees' work ran beside some legs (the one-minute load average read 2.1-26 at pair starts). The interleaved pairs, with the order alternated, are what keep the before/after comparison fair under that drift.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 0 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 29720975b6775390d7c54cb3e51f0d70d36c6cd7 → packageMentionDocs.