@proteinjs/db 1.42.0 → 1.44.0

package/jest.config.js

@@ -5,5 +5,13 @@ module.exports = {
   },
   testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$',
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  moduleNameMapper: {
+    // One copy per process in symlinked-workspace estates (the second-copy class —
+    // user-server/app-ui precedent, TRAIN_MANIFEST_5 §6.15): ServiceAuth and the suites must
+    // share ONE UserAuth class object for the static-stub idiom to reach the real gate, and
+    // reflection's SourceRepository is a process singleton. CI's npm dedupe makes these no-ops.
+    '^@proteinjs/reflection$': '<rootDir>/node_modules/@proteinjs/reflection',
+    '^@proteinjs/user-auth$': '<rootDir>/node_modules/@proteinjs/user-auth',
+  },
   testEnvironment: 'node',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.42.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": "bbbbd77251d6c48bd4dd31331c2bbb8113337597"
+  "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:
@@ -355,6 +392,19 @@ export type SourceRecordOptions<T = any> = {
    *   `Db.update`, so table watchers observe the write. Re-declaring the record reverts the
    *   patch via normal drift reversion — removal is reversible in source.
    *
+   * THE SOFT-REMOVAL CONTRACT: a source-record table that soft-removes (keeps rows on removal —
+   * the `{ update }` policy) must adopt its soft-removed rows on re-declaration and re-derive
+   * their state from the declaration. Under the default (delete) lifecycle, re-declaration is a
+   * plain re-insert and naturally idempotent; a kept row instead still holds the declared id, so
+   * a re-declaration whose natural key no longer matches it (renamed while removed) would INSERT
+   * into a primary-key collision and fail the boot. The sync therefore widens adoption for these
+   * tables: a declaration whose natural key matches nothing re-claims the soft-removed row
+   * holding its declared id (same owning package only), reactivating it by re-deriving every
+   * declared field — declaration is the source of truth, so no removed-era state (grants,
+   * status, natural key) survives re-adoption, while runtime-owned fields the declaration never
+   * emits are preserved. Any future soft-removal table inherits this requirement; machine
+   * accounts (the `@proteinjs/user` user table) are the first implementer.
+   *
    * Rows never loaded from source are structurally untouchable by every policy: the removed
    * reconcile only ever matches `is_loaded_from_source = true`.
    */

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
@@ -106,7 +120,20 @@ export class SourceRecordLoader {
         if (sourceVersion !== undefined) {
           sourceRecord.sourcePackageVersion = sourceVersion;
         }
-        const existingRecord = await db.get(table, { [keyProperty]: (sourceRecord as any)[keyProperty] });
+        let existingRecord = await db.get(table, { [keyProperty]: (sourceRecord as any)[keyProperty] });
+        let reclaimedSoftRemoved = false;
+        if (!existingRecord) {
+          existingRecord = await this.softRemovedRecordHoldingDeclaredId(
+            db,
+            table,
+            keyProperty,
+            sourceRecord.id,
+            source,
+            allDeclaredKeys
+          );
+          reclaimedSoftRemoved = existingRecord !== undefined;
+        }
+
         if (existingRecord) {
           if (
             existingRecord.sourcePackage === source &&
@@ -133,6 +160,18 @@ export class SourceRecordLoader {
               message: `(${table.name}) Adopting existing record into source ownership`,
               obj: { [keyProperty]: (sourceRecord as any)[keyProperty], id: existingRecord.id },
             });
+          } else if (reclaimedSoftRemoved) {
+            // A soft-removed row re-claimed by its declaration under a changed natural key:
+            // adopted in place and reactivated from the declaration by the update below.
+            adoptedCount += 1;
+            this.logger.info({
+              message: `(${table.name}) Adopting soft-removed record re-declared under a changed ${keyProperty}`,
+              obj: {
+                id: existingRecord.id,
+                [`removed_${keyProperty}`]: (existingRecord as any)[keyProperty],
+                [keyProperty]: (sourceRecord as any)[keyProperty],
+              },
+            });
           }
 
           if (await this.hasChanges(table, sourceRecord, existingRecord)) {
@@ -240,6 +279,60 @@ export class SourceRecordLoader {
     return { deleteCount: 0, removedUpdateCount, skippedNewer };
   }
 
+  /**
+   * The widened adoption match for tables that SOFT-remove (keep rows on removal via the
+   * `onSourceRemoved` update policy): a declaration whose natural key matched nothing may still
+   * be a RE-declaration of a removed-and-kept row — the same stable declared id under a changed
+   * natural key (e.g. a machine account renamed while decommissioned). Without this, the insert
+   * leg collides with the kept row's primary key and the boot fails.
+   *
+   * Returns the soft-removed row the declaration re-claims, or undefined. The match is
+   * deliberately strict — all of:
+   * - the table keeps removed rows (`onSourceRemoved` is an update patch — soft removal);
+   * - a row holds the DECLARED id;
+   * - that row is source-owned (`is_loaded_from_source = true`) by THIS declaration's package
+   *   (never adopt a human/runtime row, or another package's row, by id);
+   * - no declaration in this build claims the row by natural key (it is a removed row, not a
+   *   duplicate-id declaration — that case still fails the boot loudly at insert).
+   *
+   * The caller then reactivates the row by re-deriving every declared field from the current
+   * declaration (natural key included) through the normal drift-reversion update — declaration
+   * is the source of truth, so nothing removed-era (grants, status, natural key) survives
+   * re-adoption; runtime-owned fields the declaration never emits are untouched. The version
+   * guard is the caller's existing stamped-newer branch, which applies to the returned row
+   * verbatim (same package by construction).
+   *
+   * This is the one-off form of a future generic `softRemoval` hook (adopt-including-removed +
+   * reactivate-from-declaration): graduating it means lifting this method behind a table-level
+   * seam, not rewriting the semantics. The contract lives on
+   * {@link SourceRecordOptions.onSourceRemoved}.
+   */
+  private async softRemovedRecordHoldingDeclaredId(
+    db: Db,
+    table: Table<any>,
+    keyProperty: string,
+    declaredId: string,
+    source: string,
+    allDeclaredKeys: unknown[]
+  ): Promise<SourceRecord | undefined> {
+    const policy = table.sourceRecordOptions.onSourceRemoved;
+    if (typeof policy !== 'object') {
+      return undefined;
+    }
+
+    const holder: SourceRecord | undefined = await db.get(table, { id: declaredId });
+    if (
+      !holder ||
+      holder.isLoadedFromSource !== true ||
+      holder.sourcePackage !== source ||
+      allDeclaredKeys.includes((holder as any)[keyProperty])
+    ) {
+      return undefined;
+    }
+
+    return holder;
+  }
+
   /**
    * Source-loaded rows with no owner stamp that no declaration in this build claimed on this
    * boot (the stamp leg has already run). They predate `source_package`, or their declaring
@@ -329,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)) {
@@ -360,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',
+    });
+  });
+});