fix(metadata-protocol): a seed that stores many seedFile values no longer starves sign-ins (yield per row, 20-row batches) - #26822

Fixes #26670

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么:种子加载器在每一行种子文件的存储与认领之后各让出一次事件循环;携带种子文件的数据集改为每批 20 行插入(原为 200 行)。无种子文件的数据集行为不变。
• 为什么改:实测证伪了卡上「连接池被占用」的推测——连接池最长持有 44 ms;真正被占住的是事件循环:同步的 sqlite 驱动让每个 await 都成了微任务,一批 200 行的认领连成一条不间断的链,开机种子期间的登录请求要等 3–5 秒才被读到。
• 风险与回滚:风险低,只改变种子文件工作的调度顺序,不改写入内容与结果;回滚即撤销本 PR 的两个 fix 提交。
• 先看:packages/metadata-protocol/src/seed-files.ts(yieldToEventLoop 及两处调用点,settleRow 的 finally);packages/metadata-protocol/src/seed-loader.ts(insertBatchSize)。
• 两分钟验证:pnpm --filter @objectstack/metadata-protocol exec vitest run src/seed-loader-seed-files.test.ts,预期 19 passed,其中「a seed of many files yields to waiting requests (A seed that stores many seedFile files holds the sqlite pool: sign-ins during the boot seed time out (Knex: Timeout acquiring a connection) #26670)」三条全绿。
• 需要你做的:无,席位落地。

What changes

The reading first: which call holds what. The card's seam ("the seed loader holds a pooled connection or a transaction") was marked unverified, so the first measurement was the pool itself. No call on the seed-file path opens a transaction: none in seed-loader.ts, seed-files.ts or field-file-service.ts, nor in the boot runner (app-plugin.ts runInlineSeed). Every step is sequential, and there is no Promise.all. Measured on the real composition (os serve --dev, file-backed sqlite, 1,500 rows each holding one 20 KB seedFile, sign-in every 250 ms while the background seed runs). A preload patched tarn's Pool (acquire, release) and sampled event-loop lag with a 100 ms timer:

The pool was never starved. The event loop was. On a synchronous driver (better-sqlite3) every await of a seed file's roughly 25 engine calls (the pending sys_file row, the bytes, then claimFiles: describe, ownedBySlot, release, commit, each with its write hooks and audit rows) resolves as a microtask. The loader buffers inserts into 200-row batches, and after each flush settleSeedFiles claims the batch's rows back to back. Those claims involve no I/O at all, so a whole batch ran as one unbroken microtask chain, and a sign-in arriving meanwhile was not even read off the socket until it ended. The stalls landed once per batch (about 8 for 1,500 rows), and a CPU profile put the time in better-sqlite3's synchronous _query and prepare. Control on the same boot without file values: 1,500 rows and also 30,000 rows finish inside the 8 s inline budget, with about 2,140 acquires in all, so the cost is the per-row file work and not row count.

The fix, in the producer (packages/metadata-protocol, inside the claim's file surface):

1. seed-files.ts gets yieldToEventLoop(), one setImmediate turn. This is the cure @objectstack/core's import runner already applies to the same trap. prepareRow ends with it when the row stored or kept files, and settleRow ends with it (in a finally) after every row's claim. A request now waits behind one row's files, never behind a batch's.
2. seed-loader.ts writes a dataset that carries seed files (SeedDatasetFiles.carriesFiles, the bundled files map is non-empty) in insert batches of SEED_FILE_BATCH_SIZE = 20 instead of 200. With the settle loop broken up, the remaining stall was the single insertMany of 200 file-bearing rows: about 1.5 s, since each row's file-reference hooks cost about 7 ms on sqlite. At 20 rows that is about 150 ms. Datasets without seed files keep the 200-row batch.

⛔ No pool size or timeout was raised. The seed's wall time is unchanged within boot noise (about 25–30 s of seed in each 1,500-file run).

packages/metadata-protocol/src/protocol.ts and packages/services/service-storage/src/field-file-service.ts are untouched: neither holds anything.

Tests

New describe in packages/metadata-protocol/src/seed-loader-seed-files.test.ts. It seeds 60 files on an object with no self-reference, so the loader takes the batched-insert path the stall was measured on. The suite's fake engine and field-file service resolve purely in microtasks, which is the property of better-sqlite3 that matters, so the pin is deterministic without a driver:

• stores at most one row's files and settles at most one row's claim between two macrotask turns: samples progress on every setImmediate turn while the load runs.
• serves an unrelated read issued during the seed within one row's file work: a sys_user read issued from a macrotask, standing in for the sign-in's user lookup.
• writes a dataset that carries seed files in insert batches of at most 20 rows.

Ablations (each mutation landed and restored by scripts/ablation-replace.mjs, which checks the anchor and blob counts and proves the restore against the HEAD blob; the test imports source, so no dist/ is involved):

• A: yieldToEventLoop resolves at once. Pins 1 and 2 red: no macrotask turn ran while the seed ran: expected 0 to be greater than 1, the read never completed: expected undefined to be defined. 2 failed, 17 passed.
• B: SEED_FILE_BATCH_SIZE = 200. Pin 3 red: expected 60 to be less than or equal to 20. 1 failed, 18 passed.
• C: only the settle-side yield removed. Pin 1 red: expected { maxStored: 1, maxClaims: 20 } to deeply equal { maxStored: 1, maxClaims: 1 }, which is a whole batch's claims settled with no turn, the measured shape. The first attempt at C was a no-op (the tool refused: the replacement was a substring of its anchor, so the test never ran); it was re-run with a distinct replacement.
• A first version of the pins seeded clm_version, whose self-lookup sends the loader down the sequential per-record path. Leg B stayed green against it, which exposed the pins as vacuous for the batched path. They were moved to clm_doc before the legs above.

Runs on the final head 4bf7600183 unless noted:

Acceptance notes

• Not reproduced here: the card's Knex: Timeout acquiring a connection refusal. The measured pool waits never exceeded 21 ms, so this run shows the sign-in slowdown (5.2 s at worst on 1,500 small files) and its cause, not the refusal. hotclm's 28 s sign-in and its refusals are consistent with longer per-batch stalls (bigger files, more write hooks), but that is inference, not a reading.
• A residual stall at the end of the seed, outside this diff: one 3.3 s event-loop stall as the seed settles (a sign-in took 3,548 ms then). The profile slice shows emitSeedSettled, then claimSeedOwnershipOnSettle, then claimSeedOwnership (@objectstack/plugin-security, the ADR-0138 hand-over on app:seeded), with a driver updateMany and per-row insert and audit frames. It re-owns the seeded rows in one unbroken chain, scales with rows rather than files, and runs for any seed that overruns the inline budget. Reported to the seat, not fixed here.
• The boot measurement used scratch scripts (pool tracer, sign-in probe) that are not committed.

Verification

Gate families derived for this diff by node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at 4bf7600183 (59 commands), each run on 4bf7600183 with its exit code captured before any pipe. --ran reconciliation: 59 derived, 59 run, 0 NOT-MEASURED, 0 UNRUN (a derived zero: every line records its exit code).

• The first union (on d294c889) caught one real red: check:query-options-erasure, where the test surface grew 236 to 237 through a stand-in read's as any. It was fixed in 4bf7600183 by typing the literal. That union also read check-plugin-teardown-shape --self-test as a prerequisite miss (shallow clone; its pinned fixture commit was fetched) and check:dual-build-cjs-loads as PREREQUISITE NOT MET. Both are green above on a real measurement.
• Declared to CI, not run locally: test:repo (the vitest repo project; the diff touches none of its tests), the repo-wide pnpm lint, the type-check lanes, and the artifact-roster and wide-population families the derivation lists outside its 59.
• Dogfood battery: not owed (no ! in the title, Clause-②: no with no arm).

Generated by Claude Code