fix(seed-loader): count reference fields dropped from written rows (#3932)

The loader had two failure outcomes and counted one. A record it cannot write
lands in `errored`. But an unusable reference VALUE (an object where a natural
key belongs, an array on a single-value field) is removed from the record —
never written as NULL, which would sever an existing link on upsert replay —
and the row is written without it. Nothing counted that.

So a load that quietly severed N associations reported `totalErrored: 0` and
every count-driven surface read clean. The boot banner — the one seed signal
that survives `os dev`'s boot-quiet window and the default warn level — printed
`showcase 42 rows`, and the warn line said "0 dropped record(s)": true, and
useless. That reporting gap is why #3911 was reported as silent.

Adds `SeedLoadResult.referencesDropped` + `SeedLoaderSummary
.totalReferencesDropped`, deliberately NOT folded into `errored`: the row WAS
written, so that would break the `inserted + updated + skipped` reconciliation
against `total`. Threaded through both seed-summary producers (AppPlugin's
inline seed, the marketplace heal) to the banner, which now names it:

  ⚠ Seeds:   showcase 42 ok / 3 lost links ⚠

and to the app-plugin warn line, which no longer reports "0 dropped record(s)"
over a load that lost associations.

Both counters are additive with a 0 default, so existing producers and
consumers of `SeedLoaderResult` are unaffected.

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

Author: claude

.changeset/seed-loader-dropped-reference-counter.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+"@objectstack/metadata-protocol": patch
+"@objectstack/runtime": patch
+"@objectstack/cli": patch
+"@objectstack/cloud-connection": patch
+---
+
+fix(seed-loader): count reference fields dropped from rows that were still written
+
+The loader had two failure outcomes and only counted one. A record it cannot
+write is counted in `errored`. But an unusable **reference value** (an object
+where a natural key belongs, an array on a single-value field) is removed from
+the record — never written as NULL, which would sever an existing link on
+upsert replay — and the row is written **without it**. Nothing counted that.
+
+So a load that quietly severed N associations reported `totalErrored: 0`, and
+every count-driven surface read clean. The CLI boot banner — the one seed signal
+that survives `os dev`'s boot-quiet window and the default `warn` level — printed
+`showcase 42 rows`, and the warn line said `0 dropped record(s)`: true, and
+useless ([#3932](https://github.com/objectstack-ai/objectstack/issues/3932)).
+
+`SeedLoadResult.referencesDropped` and `SeedLoaderSummary.totalReferencesDropped`
+now count it. It is deliberately **not** folded into `errored` — the row *was*
+written, so that would break the `inserted + updated + skipped` reconciliation
+against `total`. The banner names it separately:
+
+```
+⚠ Seeds:   showcase 42 ok / 3 lost links ⚠
+```
+
+Both counters are additive with a `0` default, so an existing producer or
+consumer of `SeedLoaderResult` is unaffected.

content/docs/references/data/seed-loader.mdx

@@ -150,6 +150,7 @@ Result of loading a single dataset
 | **total** | `integer` | ✅ | Total records in dataset |
 | **referencesResolved** | `integer` | ✅ | References resolved via externalId |
 | **referencesDeferred** | `integer` | ✅ | References deferred to second pass |
+| **referencesDropped** | `integer` | ✅ | Reference fields dropped from records that were still written |
 | **errors** | `{ sourceObject: string; field: string; targetObject: string; targetField: string; … }[]` | ✅ | Reference resolution errors |
 
 

packages/cli/src/utils/format.seed-summary.test.ts

@@ -47,6 +47,28 @@ describe('printServerReady seed summary (#3415/#3430)', () => {
     expect(lines.some((l) => l.includes('OS_LOG_LEVEL=info'))).toBe(true);
   });
 
+  it('screams about lost links even when every row landed (#3932)', () => {
+    // The "wrote the row, lost the link" case: nothing rejected, the row counts
+    // look perfect, an association is silently missing. This line used to read
+    // `showcase 42 rows` — clean, and wrong.
+    printServerReady({ ...base, seeds: [s({ source: 'showcase', inserted: 42, droppedRefs: 3 })] });
+    expect(seedLines()).toHaveLength(1);
+    expect(seedLines()[0]).toContain('showcase 42 ok / 3 lost links ⚠');
+    expect(lines.some((l) => l.includes('OS_LOG_LEVEL=info'))).toBe(true);
+  });
+
+  it('reports rejected records and lost links together, singular-aware', () => {
+    printServerReady({ ...base, seeds: [s({ source: 'showcase', inserted: 20, rejected: 1, droppedRefs: 1 })] });
+    expect(seedLines()[0]).toContain('showcase 20 ok / 1 error / 1 lost link ⚠');
+  });
+
+  it('stays quiet when no reference was dropped', () => {
+    printServerReady({ ...base, seeds: [s({ source: 'showcase', inserted: 42, droppedRefs: 0 })] });
+    expect(seedLines()[0]).toContain('showcase 42 rows');
+    expect(seedLines()[0]).not.toContain('lost link');
+    expect(seedLines()[0]).not.toContain('⚠');
+  });
+
   it('labels a marketplace package and marks a fresh-DB heal', () => {
     printServerReady({
       ...base,

packages/cli/src/utils/format.ts

@@ -331,6 +331,12 @@ export interface SeedSourceSummary {
   skipped: number;
   /** Records dropped by validation/reference errors — the silent-loss case. */
   rejected: number;
+  /**
+   * Reference FIELDS dropped from rows that WERE written (#3932). The row
+   * count stays healthy — the association is what went missing — so unless
+   * this is said out loud, nothing on this line hints at it.
+   */
+  droppedRefs?: number;
   /**
    * Rows were (re)seeded onto a fresh/empty database during rehydrate — the
    * "swap the DB out from under an installed package" self-heal (#3430).
@@ -460,20 +466,26 @@ function printSeedSummary(sources: SeedSourceSummary[]) {
   const shown = sources.filter((s) => {
     // Empty installs and rejections are ALWAYS shown (they're the whole point);
     // a source that touched no rows and had no problem is noise — drop it.
-    if (s.emptyInstall || s.rejected > 0) return true;
+    if (s.emptyInstall || s.rejected > 0 || (s.droppedRefs ?? 0) > 0) return true;
     return s.inserted + s.updated + s.skipped > 0;
   });
   if (shown.length === 0) return;
 
-  const anyProblem = shown.some((s) => s.rejected > 0 || s.emptyInstall);
+  const anyProblem = shown.some((s) => s.rejected > 0 || (s.droppedRefs ?? 0) > 0 || s.emptyInstall);
 
   const fragment = (s: SeedSourceSummary): string => {
     const label = s.marketplace ? `${s.source}(marketplace)` : s.source;
     if (s.emptyInstall) return `${label} installed but 0 rows ⚠`;
     const ok = s.inserted + s.updated + s.skipped;
+    // A dropped reference leaves the row in place, so it never shows up in the
+    // row counts — name it separately or the line reads clean over a severed
+    // association (#3932).
+    const dropped = s.droppedRefs ?? 0;
+    const lostLinks = dropped > 0 ? ` / ${dropped} lost link${dropped === 1 ? '' : 's'}` : '';
     if (s.rejected > 0) {
-      return `${label} ${ok} ok / ${s.rejected} error${s.rejected === 1 ? '' : 's'} ⚠`;
+      return `${label} ${ok} ok / ${s.rejected} error${s.rejected === 1 ? '' : 's'}${lostLinks} ⚠`;
     }
+    if (dropped > 0) return `${label} ${ok} ok${lostLinks} ⚠`;
     return `${label} ${ok} rows${s.healed ? ' (healed on fresh db)' : ''}`;
   };
 

packages/cloud-connection/src/marketplace-install-local-plugin.ts

@@ -263,6 +263,7 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
                     updated: summary.updated ?? 0,
                     skipped: summary.skipped ?? 0,
                     rejected: summary.errors ?? 0,
+                    droppedRefs: summary.droppedRefs ?? 0,
                     healed: true,
                 });
             } else {
@@ -310,6 +311,7 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
             updated: number;
             skipped: number;
             rejected: number;
+            droppedRefs?: number;
             healed?: boolean;
             emptyInstall?: boolean;
         },
@@ -1014,7 +1016,7 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
         ctx: PluginContext,
         datasets: any[],
         organizationId?: string,
-    ): Promise<{ inserted: number; updated: number; skipped: number; errors: number; errorSample?: string }> => {
+    ): Promise<{ inserted: number; updated: number; skipped: number; errors: number; droppedRefs: number; errorSample?: string }> => {
         const ql: any = ctx.getService('objectql');
         let metadata: any;
         try { metadata = ctx.getService('metadata'); } catch { /* none */ }
@@ -1040,6 +1042,9 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
             updated: result.summary.totalUpdated,
             skipped: result.summary.totalSkipped ?? 0,
             errors: result.errors.length,
+            // Reference fields dropped from rows that WERE written (#3932) —
+            // invisible in every row count, so carried explicitly.
+            droppedRefs: result.summary.totalReferencesDropped ?? 0,
             // Surface the first write/resolution failure so the caller can
             // report WHY nothing landed (e.g. a locked DB, a missing table,
             // a failed validation) instead of a bare "0 rows".

packages/metadata-protocol/src/seed-loader-multi-value-reference.test.ts

@@ -277,6 +277,48 @@ describe('seed reference resolution — multi-value lookup (multiple: true)', ()
     expect(store.book[0].reviewer).toBeUndefined();
     expect(store.book[0].name).toBe('Refactoring');
     expect(logger.warn).toHaveBeenCalled();
+
+    // framework#3932: the row WAS written, so `errored` stays 0 and the row
+    // counters all look healthy — the loss only shows up here.
+    expect(result.summary.totalErrored).toBe(0);
+    expect(result.summary.totalReferencesDropped).toBe(1);
+    expect(result.results.find((r) => r.object === 'book')!.referencesDropped).toBe(1);
+  });
+
+  it('counts a dropped reference field without disturbing the row counters (#3932)', async () => {
+    const { engine, store } = createEngine(SCHEMAS);
+
+    const result = await new SeedLoaderService(engine, createEmptyMetadata(), createLogger()).load({
+      seeds: [AUTHOR_SEED, bookSeed([
+        { name: 'Refactoring', authors: [{ externalId: 'Alice' }] },
+        { name: 'Clean Code', authors: ['Alice'] },
+      ])] as any,
+      config: CONFIG,
+    });
+
+    const book = result.results.find((r) => r.object === 'book')!;
+    // Both rows were written — one just lost its association.
+    expect(store.book).toHaveLength(2);
+    expect(book.inserted).toBe(2);
+    expect(book.errored).toBe(0);
+    expect(book.referencesDropped).toBe(1);
+    // The reconciliation `errored` must not break: inserted + updated + skipped
+    // still accounts for every record in the dataset.
+    expect(book.inserted + book.updated + book.skipped + book.errored).toBe(book.total);
+    // Still a failed load — the counter reports damage, it does not excuse it.
+    expect(result.success).toBe(false);
+  });
+
+  it('reports zero dropped references on a clean load', async () => {
+    const { engine } = createEngine(SCHEMAS);
+
+    const result = await new SeedLoaderService(engine, createEmptyMetadata(), createLogger()).load({
+      seeds: [AUTHOR_SEED, bookSeed([{ name: 'Refactoring', authors: ['Alice', 'Bob'] }])] as any,
+      config: CONFIG,
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.summary.totalReferencesDropped).toBe(0);
   });
 
   it('still rejects a wrapper object inside a multi-value array', async () => {

packages/metadata-protocol/src/seed-loader.ts

@@ -251,6 +251,13 @@ export class SeedLoaderService implements ISeedLoaderService {
     let errored = 0;
     let referencesResolved = 0;
     let referencesDeferred = 0;
+    /**
+     * Reference FIELDS dropped from records that were still written — the
+     * "wrote the row, lost the link" outcome. Kept apart from `errored` (which
+     * counts dropped RECORDS) so `inserted + updated + skipped + errored`
+     * still reconciles against `total`. See framework#3932.
+     */
+    let referencesDropped = 0;
     const errors: ReferenceResolutionError[] = [];
 
     // Ensure the object's record map exists
@@ -507,8 +514,12 @@ export class SeedLoaderService implements ISeedLoaderService {
           this.logger.warn(`[SeedLoader] ${error.message}`, { recordIndex: i });
           // Drop the unwritable value so it never reaches the driver. Removing
           // the key (not writing null) matters on the upsert UPDATE path — see
-          // the deferred-reference note below.
+          // the deferred-reference note below. The row itself still gets
+          // written, so this is a dropped FIELD, not a dropped record — counted
+          // separately (framework#3932) or every count-driven surface, notably
+          // the CLI boot banner, reads clean over a severed association.
           delete record[ref.field];
+          referencesDropped++;
           continue;
         }
 
@@ -558,7 +569,9 @@ export class SeedLoaderService implements ISeedLoaderService {
           // Removing the key (not writing null) matters on the upsert UPDATE
           // path: an explicit null would overwrite the existing row's valid
           // reference, silently severing the link on every seed replay.
+          // Counted as a dropped FIELD (see the array branch above).
           delete record[ref.field];
+          referencesDropped++;
           continue;
         }
 
@@ -720,6 +733,7 @@ export class SeedLoaderService implements ISeedLoaderService {
       total: dataset.records.length,
       referencesResolved,
       referencesDeferred,
+      referencesDropped,
       errors,
     };
   }
@@ -1458,6 +1472,7 @@ export class SeedLoaderService implements ISeedLoaderService {
         totalErrored: 0,
         totalReferencesResolved: 0,
         totalReferencesDeferred: 0,
+        totalReferencesDropped: 0,
         circularDependencyCount: 0,
         durationMs,
       },
@@ -1480,6 +1495,7 @@ export class SeedLoaderService implements ISeedLoaderService {
       totalErrored: results.reduce((sum, r) => sum + r.errored, 0),
       totalReferencesResolved: results.reduce((sum, r) => sum + r.referencesResolved, 0),
       totalReferencesDeferred: results.reduce((sum, r) => sum + r.referencesDeferred, 0),
+      totalReferencesDropped: results.reduce((sum, r) => sum + (r.referencesDropped ?? 0), 0),
       circularDependencyCount: graph.circularDependencies.length,
       durationMs,
     };

packages/runtime/src/app-plugin.ts

@@ -911,6 +911,11 @@ export class AppPlugin implements Plugin {
                       });
                       const result = await seedLoader.load(request);
                       const { totalInserted, totalUpdated, totalSkipped, totalErrored } = result.summary;
+                      // "Wrote the row, lost the link" (#3932): a reference field
+                      // dropped from a row that WAS written moves none of the row
+                      // counters, so it needs carrying separately or the banner
+                      // reads clean over a severed association.
+                      const totalRefsDropped = result.summary.totalReferencesDropped ?? 0;
                       // #3415/#3430: stash a per-source outcome on the kernel so
                       // the CLI boot banner can print a Seeds line. The logs below
                       // never reach `os dev` output — info is under the default
@@ -923,6 +928,7 @@ export class AppPlugin implements Plugin {
                           updated: totalUpdated,
                           skipped: totalSkipped,
                           rejected: totalErrored,
+                          droppedRefs: totalRefsDropped,
                       });
                       if (result.success) {
                           ctx.logger.info('[Seeder] Seed loading complete', {
@@ -936,13 +942,20 @@ export class AppPlugin implements Plugin {
                           // invisible (the summary only logged errors.length and
                           // omitted totalErrored). Report the count AND each
                           // actionable reason so broken seeds can't pass silently.
+                          // Dropped reference FIELDS are named separately — the
+                          // old line said "0 dropped record(s)" over a load that
+                          // had severed associations, which is true and useless.
+                          const lostLinks = totalRefsDropped > 0
+                              ? `, ${totalRefsDropped} dropped reference field(s) on written rows,`
+                              : '';
                           ctx.logger.warn(
-                              `[Seeder] Seed loading completed with ${totalErrored} dropped record(s) and ${result.errors.length} error(s) for ${appId}`,
+                              `[Seeder] Seed loading completed with ${totalErrored} dropped record(s)${lostLinks} and ${result.errors.length} error(s) for ${appId}`,
                               {
                                   inserted: totalInserted,
                                   updated: totalUpdated,
                                   skipped: totalSkipped,
                                   errored: totalErrored,
+                                  referencesDropped: totalRefsDropped,
                               },
                           );
                           for (const e of result.errors.slice(0, 20)) {

packages/runtime/src/seed-summary.ts

@@ -31,6 +31,13 @@ export interface SeedSourceOutcome {
     skipped: number;
     /** Rows dropped by validation/reference errors — the silent-loss case. */
     rejected: number;
+    /**
+     * Reference FIELDS dropped from rows that were still written — "wrote the
+     * row, lost the link" (framework#3932). A distinct loss from `rejected`:
+     * the row is there, so a row count looks healthy while an association is
+     * silently missing. Surfaced separately so the banner can say so.
+     */
+    droppedRefs?: number;
     /**
      * The rows were (re)seeded onto a fresh/empty database during rehydrate —
      * the "swap the DB out from under an installed package" self-heal. Surfaced
@@ -91,6 +98,7 @@ export function recordSeedOutcome(ctx: unknown, outcome: SeedSourceOutcome): voi
             existing.updated += outcome.updated;
             existing.skipped += outcome.skipped;
             existing.rejected += outcome.rejected;
+            existing.droppedRefs = (existing.droppedRefs ?? 0) + (outcome.droppedRefs ?? 0);
             existing.healed = existing.healed || outcome.healed;
             existing.emptyInstall = existing.emptyInstall || outcome.emptyInstall;
         } else {

packages/spec/authorable-surface.json

@@ -3752,6 +3752,7 @@
     "data/SeedLoadResult:mode",
     "data/SeedLoadResult:object",
     "data/SeedLoadResult:referencesDeferred",
+    "data/SeedLoadResult:referencesDropped",
     "data/SeedLoadResult:referencesResolved",
     "data/SeedLoadResult:skipped",
     "data/SeedLoadResult:total",