@proteinjs/db 1.43.0 → 1.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.43.0",
+  "version": "1.44.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "b9fcfe6efb85e76f68876f7b1f2c38e5fdab7932"
+  "gitHead": "e58dd79705692df4325dc68b766aa2c9f7073881"
 }

package/src/Table.ts

@@ -2,7 +2,7 @@ import { Loadable, SourceRepository } from '@proteinjs/reflection';
 import { CustomSerializableObject } from '@proteinjs/serializer';
 import { isRecordColumn, Record } from './Record';
 import { TableSerializerId } from './serializers/TableSerializer';
-import { ColumnQueryTransform, QueryBuilder } from '@proteinjs/db-query';
+import { ColumnQueryTransform, QueryBuilder, SortCriteria } from '@proteinjs/db-query';
 import { Identity, TableOperationsAuth } from './auth/TableAuth';
 import { Db } from './Db';
 import { EncryptionDerivedTableRegistry } from './encryption/EncryptionDerivedTableRegistry';
@@ -132,6 +132,13 @@ export abstract class Table<T extends Record> implements Loadable, CustomSeriali
        * form still carries the full record).
        */
       columns?: (keyof T & string)[];
+      /**
+       * The record table's default ordering (the sort its default loader applies before any
+       * user interaction). Undeclared tables keep the generic `updated` descending. Declare
+       * when the rows have a natural reading order the shared face can't know — e.g. the
+       * migration ledger reads most-recently-run first, never-run rows last.
+       */
+      sort?: SortCriteria<T>[];
     };
   };
   public auth?: {
@@ -330,6 +337,14 @@ export type ColumnOptions = {
   ) => Promise<void>;
   ui?: {
     hidden?: boolean;
+    /**
+     * The column's display label on the generic record surfaces (table header, form field,
+     * phone card label). Undeclared, the surfaces humanize the property name (`startTime` →
+     * "Start time"); declare when the property name is not how a human reads the value
+     * (the migration ledger's `startTime` reads as "Ran at"). One owner: both surfaces derive
+     * from it, so a label can never differ between the table and the form.
+     */
+    label?: string;
     /**
      * Which section of the record form this column belongs to. The form derives a sane
      * section from the column's type and name (identity strings up top, long text and
@@ -342,7 +357,29 @@ export type ColumnOptions = {
   };
 };
 
+/**
+ * The identity of one source-record declaration (a `SourceRecordLoader` in a build): the
+ * package that owns it, the reflection qualified name, and the declaration's own name — the
+ * loader's class name (or variable name), the part of the qualified name after the package.
+ * See `SourceRecordLoaderDeclaration` for the identity paired with the loader itself.
+ */
+export type SourceRecordDeclarationIdentity = {
+  source: string;
+  qualifiedName: string;
+  name: string;
+};
+
 export type SourceRecordOptions<T = any> = {
+  /**
+   * Fields the sync derives from the DECLARATION ITSELF rather than from its record — for
+   * tables whose rows carry facts about their declaration: the migration ledger's `name` is
+   * the declaring loader's class name, which no migration author should have to type twice.
+   * Called once per declaration per boot; the result is merged over the declared record
+   * BEFORE the drift comparison, so the derivation owns those fields (a value typed into the
+   * record does not survive it), an existing row missing a derived field is backfilled by the
+   * next boot exactly once, and an unchanged derivation never rewrites a row.
+   */
+  fromDeclaration?: (declaration: SourceRecordDeclarationIdentity) => Partial<T>;
   /**
    * What the source-record sync does with rows it previously loaded from source
    * (`is_loaded_from_source = true`) whose declaration no longer exists:

package/src/source/SourceRecord.ts

@@ -1,5 +1,5 @@
 import { Loadable, SourceRepository } from '@proteinjs/reflection';
-import { Columns, Table, getTables } from '../Table';
+import { Columns, SourceRecordDeclarationIdentity, Table, getTables } from '../Table';
 import { Record as DbRecord, withRecordColumns } from '../Record';
 import { BooleanColumn, StringColumn } from '../Columns';
 
@@ -10,15 +10,28 @@ import { BooleanColumn, StringColumn } from '../Columns';
  * and prunes only within it, so servers running different builds against one shared database
  * never delete each other's rows.
  */
-export type SourceRecordLoaderDeclaration<T extends SourceRecord = SourceRecord> = {
-  source: string;
+export type SourceRecordLoaderDeclaration<T extends SourceRecord = SourceRecord> = SourceRecordDeclarationIdentity & {
   loader: SourceRecordLoader<T>;
 };
 
 export const getSourceRecordLoaders = <T extends SourceRecord = SourceRecord>(): SourceRecordLoaderDeclaration<T>[] =>
   SourceRepository.get()
     .objectsWithNames<SourceRecordLoader<T>>('@proteinjs/db/SourceRecordLoader')
-    .map(({ packageName, object }) => ({ source: packageName, loader: object }));
+    .map(({ packageName, qualifiedName, object }) => ({
+      source: packageName,
+      qualifiedName,
+      name: declarationName(qualifiedName, packageName),
+      loader: object,
+    }));
+
+/**
+ * The declaration's own name from its reflection qualified name (`<package>/<name>`): the
+ * loader's class name for a class declaration, the variable name for a variable one.
+ */
+const declarationName = (qualifiedName: string, packageName: string) =>
+  qualifiedName.startsWith(`${packageName}/`)
+    ? qualifiedName.slice(packageName.length + 1)
+    : qualifiedName.slice(qualifiedName.lastIndexOf('/') + 1);
 
 export function getSourceRecordTables() {
   const tables = getTables();

package/src/source/SourceRecordLoader.ts

@@ -9,6 +9,9 @@ import { RecordSerializer } from '../Record';
 type DeclaredRecord = {
   /** The owning package (the declaring loader's package) — the grain the sync prunes within. */
   source: string;
+  /** The declaration's reflection qualified name and its own name (the loader's class name). */
+  qualifiedName: string;
+  name: string;
   record: Omit<SourceRecord, 'created' | 'updated'>;
 };
 
@@ -56,6 +59,10 @@ export class SourceRecordLoader {
    *   tables it no longer declares anything for: dropping the last declaration is a removal.
    * - Rows with no owner stamp (written before `source_package` existed) are claimed by the
    *   declaration that still matches them; the rest are reported as unowned and left alone.
+   * - The version stamp records the version that last WROTE the row (its insert or its last
+   *   redefinition). A newer version whose declaration is unchanged writes nothing — it neither
+   *   re-stamps the version nor bumps `updated` — so a release that touches no declaration
+   *   leaves every row byte-identical (see {@link hasChanges}).
    *
    * Accepted residuals: a package removed from every build leaves its rows behind (no surviving
    * boot carries its authority — clean up explicitly); two builds of one package at the SAME
@@ -94,9 +101,16 @@ export class SourceRecordLoader {
       let unchangedCount = 0;
       let adoptedCount = 0;
       let skippedNewer = removed.skippedNewer;
-      for (const { source, record } of records) {
+      for (const { source, qualifiedName, name, record } of records) {
         let sourceRecord = record;
         sourceRecord.isLoadedFromSource = true;
+        // Fields derived from the declaration itself (e.g. the migration ledger's `name` = the
+        // loader's class name) — merged before the drift comparison, so they backfill existing
+        // rows exactly once and the derivation, not the declared record, owns them.
+        const derived = table.sourceRecordOptions.fromDeclaration?.({ source, qualifiedName, name });
+        if (derived) {
+          Object.assign(sourceRecord, derived);
+        }
         // Ownership stamp: the declaring package (and its version) claims the row. Stamped
         // before the drift comparison so pre-existing rows (including pre-source_package legacy
         // rows and rows whose declaration moved packages) converge to the current owner on
@@ -408,16 +422,29 @@ export class SourceRecordLoader {
    * Object-valued fields (e.g. `JsonColumn` blobs) are treated as source-authoritative:
    * any structural drift, including extra keys left behind by earlier source versions,
    * triggers a rewrite. Primitive columns retain their existing semantics.
+   *
+   * The version stamp (`source_package_version`) is bookkeeping, not definition: it names the
+   * version that last WROTE the row and rides every source record (every release bumps the
+   * declaring package), so comparing it would rewrite every row on every release — the churn
+   * that bumped `updated` on migration ledger rows nobody had touched. A stamped row's version
+   * is therefore never drift by itself; it moves only when a genuine change rewrites the row.
+   * A row with NO stamp (written before versions existed, or by a build that could not resolve
+   * its version) still gets one — once — so version ordering can protect it from then on.
    */
   private async hasChanges(table: Table<any>, sourceRecord: any, existingRecord: any): Promise<boolean> {
     const serializer = new RecordSerializer(table);
     const serializedSource = await serializer.serialize(sourceRecord);
     const serializedExisting = await serializer.serialize(existingRecord);
+    const versionStampColumn: string | undefined = (table.columns as any).sourcePackageVersion?.name;
     for (const columnName in serializedSource) {
       if (columnName === 'id' || columnName === 'created' || columnName === 'updated') {
         continue;
       }
 
+      if (columnName === versionStampColumn && serializedExisting[columnName] != null) {
+        continue;
+      }
+
       const sourceValue = serializedSource[columnName];
       const existingValue = serializedExisting[columnName];
       if (this.findMismatchPath(sourceValue, existingValue, columnName)) {
@@ -439,13 +466,13 @@ export class SourceRecordLoader {
     }
 
     const buildSources = new Set<string>();
-    for (const { source, loader } of getSourceRecordLoaders()) {
+    for (const { source, qualifiedName, name, loader } of getSourceRecordLoaders()) {
       buildSources.add(source);
       if (!tables[loader.table.name]) {
         tables[loader.table.name] = { table: loader.table, records: [] };
       }
 
-      tables[loader.table.name].records.push({ source, record: loader.record });
+      tables[loader.table.name].records.push({ source, qualifiedName, name, record: loader.record });
     }
 
     return { tables, buildSources };

package/src/tables/MigrationTable.ts

@@ -4,6 +4,14 @@ import { Table } from '../Table';
 import { SourceRecord, withSourceRecordColumns } from '../source/SourceRecord';
 
 export interface Migration extends SourceRecord {
+  /**
+   * The declaring loader's class name (`BackfillOnboardingStateForExistingAccounts`) — the
+   * ledger's human handle, leading the Migrations table. Derived by the source-record sync from
+   * the declaration itself ({@link MigrationTable.sourceRecordOptions} `fromDeclaration`), never
+   * typed into a migration's record: existing rows are backfilled by the first boot after this
+   * column ships and left alone from then on (a derived field is drift-compared like any other).
+   */
+  name?: string;
   description: string;
   /**
    * The explicit non-automatable class (plans/POST_RELEASE_QUEUE.md 27f): destructive
@@ -71,32 +79,51 @@ export class MigrationTable extends Table<Migration> {
     service: { query: { permission: 'dev' }, update: { permission: 'dev' }, delete: { permission: 'dev' } },
   };
   /**
-   * The row scan the founder actually reads: what ran, how it went, HOW LONG it took
-   * (duration — stamped by the runner at completion; the default pick's five-column cap
-   * dropped it), then the declaration flags. Failure detail and timestamps stay on the
-   * record form.
+   * The row scan the founder actually reads (ruled 2026-09-02): WHICH migration (name — the
+   * loader's class name), what it does, how the run went, WHEN it ran ("Ran at" = start_time,
+   * the one timestamp that answers "when did it land"), how long, when it finished, and a
+   * glimpse of its output (the mono JSON snippet; the record form carries the full value).
+   * The declaration flags and the failure detail stay on the record form. Most recent run
+   * first; never-run rows last — GoogleSQL orders NULL as the least value, so start_time DESC
+   * places rows without a run after every real timestamp; ledger order (created) breaks ties.
    */
   public ui: Table<Migration>['ui'] = {
     recordTable: {
-      columns: ['description', 'status', 'duration', 'manual', 'preSchemaSync', 'retired'],
+      columns: ['name', 'description', 'status', 'startTime', 'duration', 'endTime', 'output'],
+      sort: [
+        { field: 'startTime', desc: true },
+        { field: 'created', desc: false },
+      ],
     },
   };
+  /**
+   * Declared in the order the record form reads them (within a section the form keeps schema
+   * order): the migration's identity and flags up top (unlabeled), then its Run — status, ran
+   * at, duration, end time, the full output, failure message and stack — then the System meta.
+   * Column order carries no DDL weight on an existing table.
+   */
   public columns = withSourceRecordColumns<Migration>({
-    description: new StringColumn('description', {}, 4000),
-    manual: new BooleanColumn('manual'),
-    preSchemaSync: new BooleanColumn('pre_schema_sync'),
-    retired: new BooleanColumn('retired'),
-    status: new StringColumn('status', { defaultValue: async () => 'proposed' }),
-    failureMessage: new StringColumn('failure_message', {}, 4000),
-    failureStack: new StringColumn('failure_stack', {}, 'MAX'),
-    startTime: new DateTimeColumn('start_time'),
-    endTime: new DateTimeColumn('end_time'),
-    duration: new StringColumn('duration'),
-    output: new ObjectColumn('output'),
+    name: new StringColumn('name'),
+    description: new StringColumn('description', { ui: { formGroup: 'identity' } }, 4000),
+    manual: new BooleanColumn('manual', { ui: { formGroup: 'identity' } }),
+    preSchemaSync: new BooleanColumn('pre_schema_sync', { ui: { formGroup: 'identity' } }),
+    retired: new BooleanColumn('retired', { ui: { formGroup: 'identity' } }),
+    status: new StringColumn('status', { defaultValue: async () => 'proposed', ui: { formGroup: 'run' } }),
+    startTime: new DateTimeColumn('start_time', { ui: { label: 'Ran at', formGroup: 'run' } }),
+    duration: new StringColumn('duration', { ui: { formGroup: 'run' } }),
+    endTime: new DateTimeColumn('end_time', { ui: { formGroup: 'run' } }),
+    // Opted visible: an ObjectColumn hides by default, but a run's output is exactly what the
+    // ledger is opened to read (snippet on the row, full JSON on the form).
+    output: new ObjectColumn('output', { ui: { hidden: false, formGroup: 'run' } }),
+    failureMessage: new StringColumn('failure_message', { ui: { formGroup: 'run' } }, 4000),
+    failureStack: new StringColumn('failure_stack', { ui: { formGroup: 'run' } }, 'MAX'),
   });
   public sourceRecordOptions: Table<Migration>['sourceRecordOptions'] = {
     // The ledger outlives the migration class: run history stays when the source is deleted.
     onSourceRemoved: 'keep',
+    // The ledger's `name` is the declaring loader's class name — derived from the declaration
+    // by the sync (backfilled once onto existing rows), never typed into each migration.
+    fromDeclaration: ({ name }) => ({ name }),
     ui: {
       hideColumns: true,
     },

package/test/SourceRecordLoader.test.ts

@@ -152,3 +152,93 @@ describe('SourceRecordLoader.findMismatchPath', () => {
     });
   });
 });
+
+/**
+ * Stamp hygiene on the real migration-ledger shape: `hasChanges` decides whether a boot
+ * rewrites a row (bumping `updated`). The ownership stamps ride the declared record, so the
+ * comparison must know which of them mean "the definition changed" and which are bookkeeping.
+ */
+describe('SourceRecordLoader.hasChanges — stamp hygiene on the migration ledger', () => {
+  type HasChangesInternals = { hasChanges: (table: any, source: any, existing: any) => Promise<boolean> };
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { MigrationTable } = require('../src/tables/MigrationTable');
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const moment = require('moment');
+  const loader = () => new SourceRecordLoader() as unknown as HasChangesInternals;
+  const table = new MigrationTable();
+
+  /** What a build declares for a migration (the run function rides along, as it does at boot). */
+  const declared = (overrides: Record<string, unknown> = {}) => ({
+    id: 'bee7a15c-369f-4e77-abf7-ccd5dc3ae60c',
+    description: 'Marks every existing account onboarded',
+    run: async () => undefined,
+    isLoadedFromSource: true,
+    sourcePackage: '@n3xa/app-server',
+    sourcePackageVersion: '1.24.0',
+    ...overrides,
+  });
+
+  /** The ledger row a previous release wrote and later ran. */
+  const stored = (overrides: Record<string, unknown> = {}) => ({
+    id: 'bee7a15c-369f-4e77-abf7-ccd5dc3ae60c',
+    description: 'Marks every existing account onboarded',
+    isLoadedFromSource: true,
+    sourcePackage: '@n3xa/app-server',
+    sourcePackageVersion: '1.23.0',
+    status: 'success',
+    startTime: moment('2026-08-30T10:00:00Z'),
+    endTime: moment('2026-08-30T10:00:02Z'),
+    duration: '2 secs',
+    output: { rowsInserted: 12 },
+    created: moment('2026-08-30T09:00:00Z'),
+    updated: moment('2026-08-30T10:00:02Z'),
+    ...overrides,
+  });
+
+  it('a newer package version alone is NOT a change — the every-release re-stamp', async () => {
+    expect(await loader().hasChanges(table, declared(), stored())).toBe(false);
+  });
+
+  it('a row with no version stamp gets one (once)', async () => {
+    const unstamped = stored();
+    delete (unstamped as Partial<typeof unstamped>).sourcePackageVersion;
+    expect(await loader().hasChanges(table, declared(), unstamped)).toBe(true);
+  });
+
+  it('a redefined description is still a change', async () => {
+    expect(await loader().hasChanges(table, declared({ description: 'Reworded' }), stored())).toBe(true);
+  });
+
+  it('ledger-owned run state (status, times, output) never reads as drift', async () => {
+    expect(await loader().hasChanges(table, declared({ sourcePackageVersion: '1.23.0' }), stored())).toBe(false);
+  });
+});
+
+describe('getSourceRecordLoaders — declaration identity', () => {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { SourceRepository } = require('@proteinjs/reflection');
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { getSourceRecordLoaders } = require('../src/source/SourceRecord');
+  const namedObjectCache = () => (SourceRepository.get() as any).namedObjectCache;
+
+  afterEach(() => {
+    delete namedObjectCache()['@proteinjs/db/SourceRecordLoader'];
+  });
+
+  it("carries the declaration's own name (the loader class) beside its package and qualified name", () => {
+    namedObjectCache()['@proteinjs/db/SourceRecordLoader'] = [
+      {
+        qualifiedName: '@n3xa/app-server/BackfillOnboardingStateForExistingAccounts',
+        packageName: '@n3xa/app-server',
+        object: { table: {}, record: {} },
+      },
+    ];
+
+    const [declaration] = getSourceRecordLoaders() as any[];
+    expect(declaration).toMatchObject({
+      source: '@n3xa/app-server',
+      qualifiedName: '@n3xa/app-server/BackfillOnboardingStateForExistingAccounts',
+      name: 'BackfillOnboardingStateForExistingAccounts',
+    });
+  });
+});

package/test/reusable/SourceRecordSyncTests.ts

@@ -149,6 +149,7 @@ export const sourceRecordSyncTests = (
       await db.delete(machineTable, {});
       await db.delete(defaultPolicyTable, {});
       await db.delete(sourceRecordSyncTestTables.InheritedStamp, {});
+      await db.delete(sourceRecordSyncTestTables.SyncDerivedName, {});
       RecordingMachineAccountWatcher.updates = [];
     });
 
@@ -729,6 +730,77 @@ export const sourceRecordSyncTests = (
       });
     });
 
+    describe('stamp hygiene: an unchanged declaration is never rewritten', () => {
+      const versioned = (displayName: string) => ({
+        table: defaultPolicyTable,
+        record: { id: 'v-1', email: 'v1@test.local', displayName },
+      });
+
+      test('a version bump alone re-stamps nothing: the next release leaves unchanged rows (and their updated stamp) alone', async () => {
+        const db = getDbAsSystem();
+        await bootAsSource('@test/pkg-a', [versioned('same')], '1.23.0');
+        const stamped = await db.get(defaultPolicyTable, { id: 'v-1' });
+        expect(stamped.sourcePackageVersion).toBe('1.23.0');
+
+        // The next release: the SAME declaration under a newer package version (every release
+        // bumps the declaring package). Pre-fix this counted the version stamp as drift and
+        // rewrote every row on every boot — `updated` churned on rows nobody changed.
+        const summary = await bootAsSource('@test/pkg-a', [versioned('same')], '1.24.0');
+        expect(summary[defaultPolicyTable.name]).toMatchObject({ updates: 0, unchanged: 1 });
+        const idle = await db.get(defaultPolicyTable, { id: 'v-1' });
+        expect(idle.updated.valueOf()).toBe(stamped.updated.valueOf());
+        // The stamp records the version that last WROTE the row's definition.
+        expect(idle.sourcePackageVersion).toBe('1.23.0');
+
+        // A genuine redefinition still lands, and moves the stamp with it.
+        const redefined = await bootAsSource('@test/pkg-a', [versioned('changed')], '1.24.0');
+        expect(redefined[defaultPolicyTable.name].updates).toBe(1);
+        const rewritten = await db.get(defaultPolicyTable, { id: 'v-1' });
+        expect(rewritten).toMatchObject({ displayName: 'changed', sourcePackageVersion: '1.24.0' });
+      });
+
+      test('a row with no version stamp is stamped exactly once', async () => {
+        const db = getDbAsSystem();
+        // Written before versions existed (or by a build that could not resolve its version).
+        await bootAsSource('@test/pkg-a', [versioned('same')]);
+        expect((await db.get(defaultPolicyTable, { id: 'v-1' })).sourcePackageVersion).toBeFalsy();
+
+        const first = await bootAsSource('@test/pkg-a', [versioned('same')], '2.0.0');
+        expect(first[defaultPolicyTable.name].updates).toBe(1);
+        expect((await db.get(defaultPolicyTable, { id: 'v-1' })).sourcePackageVersion).toBe('2.0.0');
+
+        const second = await bootAsSource('@test/pkg-a', [versioned('same')], '2.0.0');
+        expect(second[defaultPolicyTable.name]).toMatchObject({ updates: 0, unchanged: 1 });
+      });
+
+      test('fromDeclaration: derived fields land on insert, backfill existing rows exactly once, and never re-stamp', async () => {
+        const db = getDbAsSystem();
+        const derivedTable = sourceRecordSyncTestTables.SyncDerivedName;
+        // bootBuild names each seeded loader `${source}/SeededLoader${i}` — the declaration's
+        // own name is the part after the package, exactly what a migration's class name is.
+        const declaration = { table: derivedTable, record: { id: 'd-1', email: 'd1@test.local' } };
+
+        await boot([declaration]);
+        expect(await db.get(derivedTable, { id: 'd-1' })).toMatchObject({ name: 'SeededLoader0' });
+
+        // A row written before the derived field existed: backfilled ONCE by the next boot…
+        await db.update(derivedTable, { id: 'd-1', name: null });
+        const backfill = await boot([declaration]);
+        expect(backfill[derivedTable.name].updates).toBe(1);
+        const backfilled = await db.get(derivedTable, { id: 'd-1' });
+        expect(backfilled.name).toBe('SeededLoader0');
+
+        // …and never again: the derived value is part of the drift comparison like any field.
+        const idle = await boot([declaration]);
+        expect(idle[derivedTable.name]).toMatchObject({ updates: 0, unchanged: 1 });
+        expect((await db.get(derivedTable, { id: 'd-1' })).updated.valueOf()).toBe(backfilled.updated.valueOf());
+
+        // The derivation owns the field: a value typed into the record does not survive it.
+        await boot([{ table: derivedTable, record: { id: 'd-1', email: 'd1@test.local', name: 'typed-by-hand' } }]);
+        expect((await db.get(derivedTable, { id: 'd-1' })).name).toBe('SeededLoader0');
+      });
+    });
+
     test('a natural key without a unique guarantee fails boot loudly', async () => {
       // Local (unregistered, never created) on purpose: a registered table with an invalid
       // naturalKey would poison every loader run in the process — validation fires before any

package/test/util/tables/sourceRecordSyncTestTables.ts

@@ -97,8 +97,33 @@ export class InheritedStampTable extends Table<InheritedStampRecord> {
   });
 }
 
+export interface SyncDerivedNameRecord extends SourceRecord {
+  /** Derived by the sync from the DECLARATION (its loader's name) — never typed into the record. */
+  name?: string | null;
+  email: string;
+}
+
+/**
+ * The migration-ledger shape: a `name` column the sync fills from the declaration itself
+ * (`sourceRecordOptions.fromDeclaration` — the declaring loader's class name), kept on removal
+ * like the ledger. The options literal is cast so the suite compiles red-first against a
+ * loader that does not yet know the option.
+ */
+export class SyncDerivedNameTable extends Table<SyncDerivedNameRecord> {
+  name = 'db_test_sync_derived_name';
+  columns: Table<SyncDerivedNameRecord>['columns'] = withSourceRecordColumns<SyncDerivedNameRecord>({
+    name: new StringColumn('name'),
+    email: new StringColumn('email'),
+  });
+  sourceRecordOptions = {
+    onSourceRemoved: 'keep',
+    fromDeclaration: (declaration: { name: string }) => ({ name: declaration.name }),
+  } as Table<SyncDerivedNameRecord>['sourceRecordOptions'];
+}
+
 export const sourceRecordSyncTestTables = {
   SyncMachineAccount: new SyncMachineAccountTable() as Table<SyncMachineAccount>,
   SyncDefaultPolicy: new SyncDefaultPolicyTable() as Table<SyncDefaultPolicyRecord>,
   InheritedStamp: new InheritedStampTable() as Table<InheritedStampRecord>,
+  SyncDerivedName: new SyncDerivedNameTable() as Table<SyncDerivedNameRecord>,
 };