@@ -0,0 +1,10 @@
+---
+'@objectstack/metadata-protocol': patch
+---
+
+fix(metadata-protocol): a seed that stores many `seedFile` values no longer starves sign-ins and other requests while it runs
+
+Clause-②: no
+Metadata-protocol: none
+
+A seed that stores many `seedFile(path)` values no longer starves the requests that arrive while it runs. On a synchronous driver (better-sqlite3, the wasm fallback) every step of a seed file's work — the `sys_file` row, the bytes, the claim that commits it — resolves as a microtask, so the claims the seed loader settled after each 200-row insert batch ran as one unbroken chain and a sign-in during a background boot seed waited seconds unread behind it. The connection pool was never the bottleneck; the event loop was. The loader now hands the event loop one turn after each row's files are stored and after each row's claim, and writes a dataset that carries seed files in insert batches of 20 rows instead of 200. Datasets without seed files are unchanged.
@@ -61,6 +61,32 @@ const PROVENANCE_SHA256 = 'sha256';
 /** How many file ids one `describeFiles` read names. */
 const DESCRIBE_CHUNK = 500;
 
+/**
+ * [#26670] Hand the event loop one macrotask turn.
+ *
+ * A seed file costs its row about two dozen sequential engine calls: the
+ * `sys_file` row written `pending`, the bytes, then the claim (the files read
+ * again, the slot's held files read and released, the row committed), each
+ * with the write hooks they run. On a synchronous driver (better-sqlite3,
+ * the wasm fallback) every one of those `await`s resolves as a microtask, so
+ * a run of rows never reaches the event loop's I/O phase at all: the claims
+ * the loader settles after each 200-row insert batch ran as one unbroken
+ * microtask chain, measured at 3–5 s per batch on a boot seeding 1,500 files,
+ * and every request that arrived meanwhile — a sign-in — waited unread for
+ * the whole chain. The connection pool was never the bottleneck (no hold
+ * over 44 ms); the event loop was.
+ *
+ * So each row's file work ends here, and a request waits behind one row's
+ * files, never behind a dataset's. The same cure as the import runner's
+ * row loop (`@objectstack/core`, `import-runner.ts`), for the same cause.
+ */
+function yieldToEventLoop(): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (typeof setImmediate === 'function') setImmediate(resolve);
+    else setTimeout(resolve, 0);
+  });
+}
+
 /** The file-class fields of an object definition, by name. */
 function fileFieldsOf(definition: unknown): Map<string, FileField> {
   const found = new Map<string, FileField>();
@@ -117,6 +143,11 @@ export class SeedDatasetFiles {
     private readonly service: IFieldFileService | null,
   ) {}
 
+  /** Whether the dataset carries seed-file bytes: some record names `seedFile(path)`. */
+  get carriesFiles(): boolean {
+    return Object.keys(this.files).length > 0;
+  }
+
   /**
    * The dataset's file handling, or `null` when the seeded object declares no
    * file-class field — nothing below runs for such an object.
@@ -297,6 +328,8 @@ export class SeedDatasetFiles {
       args.record[field] = def.multiple ? fileIds : fileIds[0];
       claims.push({ field, fileIds });
     }
+    // [#26670] The row's files are stored (or kept): let a waiting request in.
+    if (planned.length > 0) await yieldToEventLoop();
     return { ok: true, claims };
   }
 
@@ -308,6 +341,18 @@ export class SeedDatasetFiles {
    */
   async settleRow(recordId: string, claims: SeedFileClaims, organizationId: string | null): Promise<string | null> {
     if (!this.service || claims.length === 0) return null;
+    try {
+      return await this.settleClaims(recordId, claims, organizationId);
+    } finally {
+      // [#26670] The loader settles a whole insert batch's rows back to back;
+      // each row's claim ends with a turn for whatever request is waiting.
+      await yieldToEventLoop();
+    }
+  }
+
+  /** {@link settleRow}'s claims, field by field; the first failure ends it. */
+  private async settleClaims(recordId: string, claims: SeedFileClaims, organizationId: string | null): Promise<string | null> {
+    const service = this.service!;
     for (const { field, fileIds } of claims) {
       const known = await this.describe(fileIds, organizationId);
       const settled = fileIds.every((id) => {
@@ -319,7 +364,7 @@ export class SeedDatasetFiles {
       });
       if (settled) continue;
       try {
-        await this.service.claimFiles({ object: this.objectName, recordId, field }, fileIds, organizationId);
+        await service.claimFiles({ object: this.objectName, recordId, field }, fileIds, organizationId);
         this.forget(fileIds, organizationId);
       } catch (err) {
         return `${this.objectName}/${recordId}.${field} was written, but its seed file(s) ${fileIds.join(', ')} could ` +
 
@@ -427,3 +427,94 @@ describe('seed files: refusals, by row, before the row is written (#25779)', ()
     expect(service.describeFiles).not.toHaveBeenCalled();
   });
 });
+
+/**
+ * [#26670] A seed that stores many files must leave the event loop to the
+ * requests that arrive while it runs.
+ *
+ * On a synchronous driver (better-sqlite3) every `await` of the seed's
+ * per-row file work resolves as a microtask, and the fakes here resolve the
+ * same way, which is the property that matters: without a macrotask turn the
+ * whole load runs as one unbroken microtask chain, and a request that
+ * arrives meanwhile (a sign-in, read on the I/O phase) is not even read until
+ * the seed is done. Measured on `os serve --dev` over sqlite before the fix:
+ * the event loop stalled 3–5 s per 200-row insert batch while the connection
+ * pool never held a connection longer than 44 ms.
+ */
+describe('a seed of many files yields to waiting requests (#26670)', () => {
+  const ROWS = 60;
+  // No self-reference, unlike `clm_version`: the loader buffers this object's
+  // inserts and flushes them in batches, then settles each landed row's claim
+  // back to back — the path the stall was measured on.
+  const manyFiles = () => {
+    const files: Record<string, unknown> = {};
+    const records = [];
+    for (let i = 0; i < ROWS; i++) {
+      files[`fixtures/f${i}.pdf`] = bundled(`%PDF ${i}`);
+      records.push({ code: `D${i}`, file: seedFile(`fixtures/f${i}.pdf`) });
+    }
+    return dataset(records, files, { object: 'clm_doc' });
+  };
+  const batchedLoader = (engine: IDataEngine, service: IFieldFileService) => {
+    const metadata = createMetadata();
+    (metadata.getObject as any).mockImplementation(async (name: string) =>
+      name === 'clm_doc' ? { name: 'clm_doc', fields: { code: { type: 'text' }, file: { type: 'file' } } } : undefined);
+    return new SeedLoaderService(engine, metadata, createLogger(), { getFieldFiles: () => service });
+  };
+
+  it('stores at most one row\'s files and settles at most one row\'s claim between two macrotask turns', async () => {
+    const { engine } = createEngine();
+    const { service, stored, claims } = createFieldFiles();
+    const turns: Array<{ stored: number; claims: number }> = [];
+    let done = false;
+    const sample = () => {
+      turns.push({ stored: stored.length, claims: claims.length });
+      if (!done) setImmediate(sample);
+    };
+    setImmediate(sample);
+    const result = await batchedLoader(engine, service).load({ seeds: [manyFiles()], config: CONFIG });
+    done = true;
+
+    expect(result.success).toBe(true);
+    expect(stored).toHaveLength(ROWS);
+    expect(claims).toHaveLength(ROWS);
+    let maxStored = 0;
+    let maxClaims = 0;
+    for (let t = 1; t < turns.length; t++) {
+      maxStored = Math.max(maxStored, turns[t].stored - turns[t - 1].stored);
+      maxClaims = Math.max(maxClaims, turns[t].claims - turns[t - 1].claims);
+    }
+    // A turn ran while the load did, and the first one landed before the last
+    // file was stored: the load did not run through in one chain.
+    expect(turns.length, 'no macrotask turn ran while the seed ran').toBeGreaterThan(1);
+    expect(turns[0].stored,'the first macrotask turn came only after the seed stored every file').toBeLessThan(ROWS);
+    expect({ maxStored, maxClaims }).toEqual({ maxStored: 1, maxClaims: 1 });
+  });
+
+  it('serves an unrelated read issued during the seed within one row\'s file work', async () => {
+    const { engine } = createEngine();
+    const { service, stored, claims } = createFieldFiles();
+    let readAt: { stored: number; claims: number } | undefined;
+    // A request read on the I/O phase, as a sign-in's user lookup is.
+    setImmediate(() => {
+      const issuedAt = { stored: stored.length, claims: claims.length };
+      void engine.find('sys_user', { where: { email: 'admin@example.com' } }).then(() => {
+        readAt = { stored: stored.length - issuedAt.stored, claims: claims.length - issuedAt.claims };
+      });
+    });
+    await batchedLoader(engine, service).load({ seeds: [manyFiles()], config: CONFIG });
+    expect(readAt, 'the read never completed').toBeDefined();
+    expect(readAt!.stored + readAt!.claims, 'files stored or claimed while the read waited').toBeLessThanOrEqual(1);
+  });
+
+  it('writes a dataset that carries seed files in insert batches of at most 20 rows', async () => {
+    const { engine } = createEngine();
+    const { service } = createFieldFiles();
+    await batchedLoader(engine, service).load({ seeds: [manyFiles()], config: CONFIG });
+    const sizes = (engine.insert as any).mock.calls
+      .filter(([object]: [string]) => object === 'clm_doc')
+      .map(([, data]: [string, unknown]) => (Array.isArray(data) ? data.length : 1));
+    expect(sizes.reduce((a: number, b: number) => a + b, 0)).toBe(ROWS);
+    expect(Math.max(...sizes)).toBeLessThanOrEqual(20);
+  });
+});
@@ -1279,7 +1279,7 @@ export class SeedLoaderService implements ISeedLoaderService {
       const writeResults: BulkWriteRowResult[] = await bulkWrite(
         batch.map(b => b.record),
         {
-          batchSize: SeedLoaderService.BULK_BATCH_SIZE,
+          batchSize: insertBatchSize,
           writeBatchPartial: async (rows, { attempt }) => {
             let toInsert = rows;
             let existing = new Map<string, any>();
@@ -1399,6 +1399,18 @@ export class SeedLoaderService implements ISeedLoaderService {
       organizationId: config.organizationId ?? this.fallbackOrgId ?? null,
       dryRun: config.dryRun === true,
     });
+    /**
+     * [#26670] Rows per buffered-insert batch. A row holding seed files costs
+     * its insert the file-reference hooks, about 7 ms a row on sqlite against
+     * well under 1 ms for a plain row, and one `insertMany` is one unbroken
+     * run on a synchronous driver: 200 such rows held the event loop for about
+     * 1.5 s, and a sign-in waited behind it. A dataset that carries seed files
+     * is written in small batches instead, so a request waits behind a few
+     * rows; every other dataset keeps the full batch.
+     */
+    const insertBatchSize = datasetFiles?.carriesFiles
+      ? SeedLoaderService.SEED_FILE_BATCH_SIZE
+      : SeedLoaderService.BULK_BATCH_SIZE;
     /** Record index → the files that row's slots must own once it lands. */
     const fileClaimsByRecordIndex = new Map<number, { claims: SeedFileClaims; organizationId: string | null }>();
     /**
@@ -2119,7 +2131,7 @@ export class SeedLoaderService implements ISeedLoaderService {
           } else {
             // Insert: buffer for the batched flush rather than writing now.
             pendingInserts.push({ recordIndex: i, externalIdValue, record });
-            if (pendingInserts.length >= SeedLoaderService.BULK_BATCH_SIZE) {
+            if (pendingInserts.length >= insertBatchSize) {
               await flushPendingInserts();
             }
           }
@@ -2938,6 +2950,9 @@ export class SeedLoaderService implements ISeedLoaderService {
   /** Rows per batch for the buffered-insert flush. See framework#2678. */
   private static readonly BULK_BATCH_SIZE = 200;
 
+  /** [#26670] Rows per buffered-insert batch for a dataset that carries seed files (see `insertBatchSize`). */
+  private static readonly SEED_FILE_BATCH_SIZE = 20;
+
   /**
    * Decide what {@link loadDataset}'s non-self-referencing (batched) path
    * should do with a record — mirrors {@link writeRecord}'s mode/existing