test(devx): gate the module-top load of a dist-resolved workspace dep (clocked-window rule) (#10135)

* test(devx): gate the module-top load of a dist-resolved workspace dep

Extends `check:test-source-alias` with the clocked-window rule (#10126): a test
file that loads one of its package's unaliased specifiers through a dynamic
`import()` / `require()` inside a function body — an `it()` body, a hook, or any
nested function — with no module-scope load of the same specifier is a finding.

vitest clocks hooks and test bodies only; collection is clocked against nothing,
so a module-top side-effect import moves a cold transform OUT of every budget
rather than into a bigger one. #10115 / PR #10120 paid for that reading with 30
ejected merge-queue builds in one night.

Baseline sweep: 31 violations across 21 files in 9 packages, all fixed here the
PR #10120 way (module-top `import '<specifier>'`), none quarantined or
registry-exempted.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URCaKuNTuK3BKJvwqM74QU

* test(devx): count the clocked-window fixture's findings on its full path

`packages/clocked-load` is also a prefix of `packages/clocked-load-paid`, so the
count assertion read the compliant fixture's findings as the violating one's.
Found by ablating the compliance leg: the count moved to 3 for a reason that was
in the assertion rather than in the gate.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URCaKuNTuK3BKJvwqM74QU

* fix(devx): read a `}): Promise< { … } > {` signature as a function body

The classifier's backward walk bailed on the braces, the semicolon and the
newlines a multi-line signature puts between the parameter list and the body,
so a module-level helper called from test bodies read as "not a function" and
its file was exempted SILENTLY. Surfaced by ablating the classifier, not by the
sweep: `serve-marketplace-offline-runtime-config.test.ts` sat green through it.

Balanced groups are now jumped through the forward pass's `openOf` map, `=>`
inside a function type is not counted as a generic closer, and the shape is
pinned as its own self-test fixture. One more real violation follows, fixed the
same way.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URCaKuNTuK3BKJvwqM74QU

* docs(devx): state the clocked-window convention where an author meets it

#10126's layer 4 asked for the sentence in AGENTS.md's testing conventions.
That file sits exactly on its shrink-only line ceiling (958, headroom 0,
`scripts/pm/check-skill-line-ratchet.mjs`); the sentence costs three lines and
its own section has two lines of lossless rewrap headroom. Raising a ceiling
takes a maintainer ruling, and truncating a maintainer-specified sentence to fit
one is not this gate's call — so the doc placement stays open and is reported.

Meanwhile the sentence is stated verbatim in the gate header AND in the failure
text, pinned by its own self-test assertion so it cannot decay into a comment.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URCaKuNTuK3BKJvwqM74QU

* docs(devx): land the clocked-window convention in AGENTS.md (ceiling 958 -> 961)

Layer 4 of #10126, unblocked by a maintainer ruling. AGENTS.md sat exactly on its
shrink-only line ceiling with the mandated sentence costing three lines and its
section carrying two lines of lossless rewrap headroom, so it could not be paid
for in place. Ruling 2026-08-20, verbatim and untranslated:

  「A — 抬上限到 961 (Recommended)」

The raise is exactly +3 and nothing more; headroom is 0 again by construction, so
the next author needing a line is back to compressing. The sentence lands beside
the sibling test-gate conventions in § Build & Test, unedited, and the gate
header's note about why it was NOT there is corrected.

The ratchet's self-test pins coverage and shape, never a ceiling's numeric value,
so it needed no extension; re-run green at 19 cases.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URCaKuNTuK3BKJvwqM74QU

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

AGENTS.md

@@ -118,6 +118,9 @@ judged on the **shallowest** point a path reaches, not where it ends — a liter
 climbs past the package root and then descends into a sibling ends at a positive depth
 while addressing another package entirely.
 
+Clocked windows measure behaviour, never loading — a test that boots a real plugin chain
+pays its first load at module top; `pnpm check:test-source-alias` gates it.
+
 ### Running the dev server
 
 | Scenario | Command | Notes |

examples/app-crm/test/smoke.test.ts

@@ -4,6 +4,13 @@ import { describe, it, expect } from 'vitest';
 import stack from '../objectstack.config.js';
 import { PipelineDashboard } from '../src/dashboards/pipeline.dashboard.js';
 
+// [#10126] Pay the first transform of these dist-resolved workspace deps at MODULE
+// LOAD. Each is reached below through a dynamic `import()` inside an `it()` body or a
+// hook -- both of which vitest clocks, while collection is clocked against nothing. See
+// `scripts/check-test-source-alias.mjs` (the clocked-window rule) and #10115 / PR #10120,
+// where the same shape cost 30 ejected merge-queue builds in one night.
+import '@objectstack/spec/ui';
+
 describe('app-crm minimal metadata bundle', () => {
   it('exposes the expected manifest', () => {
     // `manifest` is optional on the stack bundle type; this example always

examples/embed-objectql/test/embed.test.ts

@@ -3,6 +3,13 @@
 import { describe, it, expect } from 'vitest';
 import { runEmbeddedEngine } from '../src/index.js';
 
+// [#10126] Pay the first transform of these dist-resolved workspace deps at MODULE
+// LOAD. Each is reached below through a dynamic `import()` inside an `it()` body or a
+// hook -- both of which vitest clocks, while collection is clocked against nothing. See
+// `scripts/check-test-source-alias.mjs` (the clocked-window rule) and #10115 / PR #10120,
+// where the same shape cost 30 ejected merge-queue builds in one night.
+import '@objectstack/objectql/core';
+
 describe('embed @objectstack/objectql/core (ADR-0076)', () => {
   it('runs the engine standalone and round-trips CRUD via the lean entry', async () => {
     const active = await runEmbeddedEngine();

packages/cli/src/commands/dev-default-db.test.ts

@@ -12,16 +12,21 @@
  * cross-command agreement is pinned by `unified-db-resolution.pin.test.ts`.
  */
 
-import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'path';
 import { resolveDevDatabase } from './dev.js';
 
-// The dev seam lazy-imports @objectstack/runtime (oclif startup weight, #5726);
-// the FIRST import cold-loads that graph and can exceed vitest's 5s default on
-// a cold worker — warm it once, like standalone-stack.test.ts's BOOT_TIMEOUT.
-beforeAll(async () => { await import('@objectstack/runtime'); }, 60_000);
+// [#10126] The dev seam lazy-imports @objectstack/runtime (oclif startup weight,
+// #5726), and the FIRST import cold-loads that whole graph. This file used to warm
+// it in a `beforeAll` with a 60s budget; a hook is still a CLOCKED window, and any
+// budget the cost is moved INTO can be exhausted by a heavier shard — which is how
+// #10115 / PR #10120 ejected a file from the merge queue four times in one night.
+// A module-top side-effect import pays the transform during COLLECTION instead, and
+// vitest clocks hooks and test bodies only. See `scripts/check-test-source-alias.mjs`
+// (the clocked-window rule), which now gates this shape.
+import '@objectstack/runtime';
 
 let cwd: string;
 beforeEach(() => { cwd = mkdtempSync(path.join(tmpdir(), 'os-dev-db-')); });

packages/cli/src/commands/doctor-ledger-dir-authority.test.ts

@@ -55,6 +55,13 @@ import Doctor, {
   installedPackageLedgerSkippedEntriesCheck,
 } from './doctor.js';
 
+// [#10126] Pay the first transform of these dist-resolved workspace deps at MODULE
+// LOAD. Each is reached below through a dynamic `import()` inside an `it()` body or a
+// hook -- both of which vitest clocks, while collection is clocked against nothing. See
+// `scripts/check-test-source-alias.mjs` (the clocked-window rule) and #10115 / PR #10120,
+// where the same shape cost 30 ejected merge-queue builds in one night.
+import '@objectstack/cloud-connection';
+
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 /** `packages/cli` — the oclif root the real command is loaded against below. */
 const CLI_ROOT = path.resolve(HERE, '..', '..');

packages/cli/src/commands/doctor-ledger-posture-independence.test.ts

@@ -69,6 +69,13 @@ import { fileURLToPath } from 'node:url';
 
 import Doctor from './doctor.js';
 
+// [#10126] Pay the first transform of these dist-resolved workspace deps at MODULE
+// LOAD. Each is reached below through a dynamic `import()` inside an `it()` body or a
+// hook -- both of which vitest clocks, while collection is clocked against nothing. See
+// `scripts/check-test-source-alias.mjs` (the clocked-window rule) and #10115 / PR #10120,
+// where the same shape cost 30 ejected merge-queue builds in one night.
+import '@objectstack/cloud-connection';
+
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 /** `packages/cli` — the oclif root the real command is loaded against below. */
 const CLI_ROOT = path.resolve(HERE, '..', '..');

packages/cli/src/commands/doctor-ledger-read-failure.test.ts

@@ -93,6 +93,13 @@ import Doctor, {
   installedPackageLedgerReaderFailureCheck,
 } from './doctor.js';
 
+// [#10126] Pay the first transform of these dist-resolved workspace deps at MODULE
+// LOAD. Each is reached below through a dynamic `import()` inside an `it()` body or a
+// hook -- both of which vitest clocks, while collection is clocked against nothing. See
+// `scripts/check-test-source-alias.mjs` (the clocked-window rule) and #10115 / PR #10120,
+// where the same shape cost 30 ejected merge-queue builds in one night.
+import '@objectstack/cloud-connection';
+
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 /** `packages/cli` — the oclif root the real command is loaded against below. */
 const CLI_ROOT = path.resolve(HERE, '..', '..');

packages/cli/src/utils/platform-migrations-arming.integration.test.ts

@@ -47,6 +47,14 @@ import { SqlDriver } from '@objectstack/driver-sql';
 import { GLOBAL_TENANT, SEQUENCES_TABLE, ORGANIZATION_TABLE } from '@objectstack/metadata-protocol';
 import { bootSchemaStack } from './schema-migrate.js';
 
+// [#10126] Pay the first transform of these dist-resolved workspace deps at MODULE
+// LOAD. Each is reached below through a dynamic `import()` inside an `it()` body or a
+// hook -- both of which vitest clocks, while collection is clocked against nothing. See
+// `scripts/check-test-source-alias.mjs` (the clocked-window rule) and #10115 / PR #10120,
+// where the same shape cost 30 ejected merge-queue builds in one night.
+import '@objectstack/objectql';
+import '@objectstack/runtime';
+
 const ORG_ID = 'org_x';
 /** The `__global__` counter the seed loader ran ahead to before the org existed. */
 const SEEDED_LAST_VALUE = 38;

packages/cli/test/serve-marketplace-offline-install.test.ts

@@ -31,6 +31,13 @@
 import { describe, expect, it } from 'vitest';
 import Serve from '../src/commands/serve.js';
 
+// [#10126] Pay the first transform of these dist-resolved workspace deps at MODULE
+// LOAD. Each is reached below through a dynamic `import()` inside an `it()` body or a
+// hook -- both of which vitest clocks, while collection is clocked against nothing. See
+// `scripts/check-test-source-alias.mjs` (the clocked-window rule) and #10115 / PR #10120,
+// where the same shape cost 30 ejected merge-queue builds in one night.
+import '@objectstack/cloud-connection';
+
 /** Minimal stand-in for a loaded plugin: what the resolver actually reads. */
 function plugin(name: string, ctorName: string): { name: string } {
   const Ctor = { [ctorName]: class { name: string; constructor(n: string) { this.name = n; } } }[ctorName]!;

packages/cli/test/serve-marketplace-offline-runtime-config.test.ts

@@ -61,6 +61,13 @@ import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import Serve from '../src/commands/serve.js';
 
+// [#10126] Pay the first transform of these dist-resolved workspace deps at MODULE
+// LOAD. Each is reached below through a dynamic `import()` inside an `it()` body or a
+// hook -- both of which vitest clocks, while collection is clocked against nothing. See
+// `scripts/check-test-source-alias.mjs` (the clocked-window rule) and #10115 / PR #10120,
+// where the same shape cost 30 ejected merge-queue builds in one night.
+import '@objectstack/cloud-connection';
+
 interface RouteRecord { method: string; path: string }
 
 interface HonoShapedApp {