@proteinjs/db 1.43.0 → 1.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.43.0",
+  "version": "1.45.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": "135045a9e4b16a75ea11f610a82fa7ff60751e8d"
 }

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/auth/TableAuth.ts

@@ -67,27 +67,19 @@ export class TableAuth {
     }
   }
 
-  private canAccess(
-    table: Table<any>,
-    api: 'db' | 'service',
-    operation: 'query' | 'insert' | 'update' | 'delete'
-  ): boolean {
-    const tableAuth = table.auth ? table.auth[api] : undefined;
-    if (!tableAuth || Object.keys(tableAuth).length == 0) {
-      return UserAuth.hasRole('admin');
+  /**
+   * Non-throwing read of ONE declared identity against the CURRENT user — the same grammar the
+   * table doors speak (`'public' | 'authenticated' | roles[] | { permission }`), for declared
+   * UI affordances that carry their own grant (a record form's declared panels, `Table.auth.ui`).
+   * An UNDECLARED identity is the default-deny made explicit: admin only. Fails closed (false)
+   * when no user can be resolved, like `canPerform`.
+   */
+  identityAllows(identity: Identity | undefined): boolean {
+    try {
+      return identity === undefined ? UserAuth.hasRole('admin') : this.allows(identity);
+    } catch {
+      return false;
     }
-
-    return (
-      tableAuth.all === 'public' ||
-      tableAuth[operation] === 'public' ||
-      (tableAuth.all === 'authenticated' && UserAuth.isLoggedIn()) ||
-      (tableAuth[operation] === 'authenticated' && UserAuth.isLoggedIn()) ||
-      (Array.isArray(tableAuth.all) && UserAuth.hasRoles(tableAuth.all, 'at least one')) ||
-      (Array.isArray(tableAuth[operation]) && UserAuth.hasRoles(tableAuth[operation] as string[], 'at least one')) ||
-      (isPermissionIdentity(tableAuth.all) && UserAuth.hasPermission(tableAuth.all.permission)) ||
-      (isPermissionIdentity(tableAuth[operation]) &&
-        UserAuth.hasPermission((tableAuth[operation] as PermissionIdentity).permission))
-    );
   }
 
   canQuery(table: Table<any>, api: 'db' | 'service' = 'db'): void {
@@ -113,4 +105,37 @@ export class TableAuth {
       throw new TableAuthError(`User is not authorized to delete records from table: ${table.name}`);
     }
   }
+
+  private canAccess(
+    table: Table<any>,
+    api: 'db' | 'service',
+    operation: 'query' | 'insert' | 'update' | 'delete'
+  ): boolean {
+    const tableAuth = table.auth ? table.auth[api] : undefined;
+    if (!tableAuth || Object.keys(tableAuth).length == 0) {
+      return UserAuth.hasRole('admin');
+    }
+
+    // Within a declared block an undeclared operation stays closed to everyone (the block is
+    // the whole declaration) — `allows` reads undefined as false, so the two doors are exactly
+    // the ones the table wrote down.
+    return this.allows(tableAuth.all) || this.allows(tableAuth[operation]);
+  }
+
+  /** One identity against the current user; undefined (nothing declared) is not a grant. */
+  private allows(identity: Identity | undefined): boolean {
+    if (identity === 'public') {
+      return true;
+    }
+    if (identity === 'authenticated') {
+      return UserAuth.isLoggedIn();
+    }
+    if (Array.isArray(identity)) {
+      return UserAuth.hasRoles(identity, 'at least one');
+    }
+    if (isPermissionIdentity(identity)) {
+      return UserAuth.hasPermission(identity.permission);
+    }
+    return false;
+  }
 }

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/TableAuthIdentity.test.ts

@@ -0,0 +1,115 @@
+import { UserAuth } from '@proteinjs/user-auth';
+import { Table } from '../src/Table';
+import { withRecordColumns, Record } from '../src/Record';
+import { StringColumn } from '../src/Columns';
+import { TableAuth } from '../src/auth/TableAuth';
+
+/**
+ * `TableAuth.identityAllows` — the one identity grammar (`'public' | 'authenticated' | roles[] |
+ * { permission }`) read for a DECLARED UI affordance that carries its own grant (a record form's
+ * declared panels, `Table.auth.ui`). Outcomes pinned:
+ * - each identity form resolves against the current user; 'admin' is break-glass throughout;
+ * - an UNDECLARED identity is admin-only (default-deny made explicit), never open;
+ * - it fails CLOSED when no user can be resolved;
+ * - the operation doors (`canPerform`) are byte-for-byte the pre-refactor semantics: within a
+ *   declared block an undeclared operation stays closed to everyone, admin included.
+ *
+ * `UserAuth` reads from a static repo; tests stub it directly per identity — no server needed.
+ */
+
+interface Doc extends Record {
+  title: string;
+}
+
+class QueryOnlyTable extends Table<Doc> {
+  public name = 'identity_query_only_test';
+  public auth: Table<Doc>['auth'] = {
+    db: { query: 'authenticated' },
+  };
+  public columns = withRecordColumns<Doc>({ title: new StringColumn('title') });
+}
+
+const setUser = (roles: string[], email = 'user@test.local') => {
+  (UserAuth as any).userRepo = { getUser: () => ({ email, roles }) };
+};
+const setGuest = () => {
+  (UserAuth as any).userRepo = { getUser: () => ({ email: 'guest', roles: [] }) };
+};
+const setMapping = (mapping: { [permission: string]: string[] }) => {
+  (UserAuth as any).permissionRolesMapping = { getRoles: (permission: string) => mapping[permission] };
+};
+
+describe('TableAuth.identityAllows', () => {
+  beforeEach(() => {
+    setMapping({ usage: ['usage'] });
+  });
+
+  afterEach(() => {
+    (UserAuth as any).userRepo = undefined;
+    (UserAuth as any).permissionRolesMapping = undefined;
+  });
+
+  test("'public' admits anyone, including a guest", () => {
+    setGuest();
+    expect(new TableAuth().identityAllows('public')).toBe(true);
+  });
+
+  test("'authenticated' admits a signed-in user and refuses a guest", () => {
+    setUser([]);
+    expect(new TableAuth().identityAllows('authenticated')).toBe(true);
+    setGuest();
+    expect(new TableAuth().identityAllows('authenticated')).toBe(false);
+  });
+
+  test('a roles list admits a holder of at least one role', () => {
+    setUser(['ops']);
+    expect(new TableAuth().identityAllows(['users', 'ops'])).toBe(true);
+    setUser(['dev']);
+    expect(new TableAuth().identityAllows(['users', 'ops'])).toBe(false);
+  });
+
+  test('a permission identity resolves through the consumer mapping; admin is break-glass', () => {
+    setUser(['usage']);
+    expect(new TableAuth().identityAllows({ permission: 'usage' })).toBe(true);
+    setUser(['users']);
+    expect(new TableAuth().identityAllows({ permission: 'usage' })).toBe(false);
+    setUser(['admin']);
+    expect(new TableAuth().identityAllows({ permission: 'usage' })).toBe(true);
+  });
+
+  test('an undeclared identity is admin-only, never open', () => {
+    setUser(['usage', 'users', 'ops']);
+    expect(new TableAuth().identityAllows(undefined)).toBe(false);
+    setUser(['admin']);
+    expect(new TableAuth().identityAllows(undefined)).toBe(true);
+  });
+
+  test('fails closed when no user can be resolved', () => {
+    (UserAuth as any).userRepo = {
+      getUser: () => {
+        throw new Error('no session');
+      },
+    };
+    expect(new TableAuth().identityAllows('authenticated')).toBe(false);
+    expect(new TableAuth().identityAllows({ permission: 'usage' })).toBe(false);
+  });
+});
+
+describe('TableAuth operation doors keep their declared-block semantics', () => {
+  afterEach(() => {
+    (UserAuth as any).userRepo = undefined;
+    (UserAuth as any).permissionRolesMapping = undefined;
+  });
+
+  test('a declared operation opens to its identity', () => {
+    setUser([]);
+    expect(new TableAuth().canPerform(new QueryOnlyTable(), 'query')).toBe(true);
+  });
+
+  test('within a declared block an undeclared operation stays closed — admin included', () => {
+    setUser(['admin']);
+    expect(new TableAuth().canPerform(new QueryOnlyTable(), 'insert')).toBe(false);
+    setUser([]);
+    expect(new TableAuth().canPerform(new QueryOnlyTable(), 'insert')).toBe(false);
+  });
+});