@proteinjs/db 1.34.1 → 1.34.3

package/index.ts

@@ -1,5 +1,6 @@
 export * from './src/Db';
 export * from './src/Table';
+export * from './src/RecordAccessError';
 export * from './src/auth/TableAuth';
 export * from './src/auth/TableServiceAuth';
 export * from './src/Columns';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.34.1",
+  "version": "1.34.3",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -41,9 +41,9 @@
     "test": "jest --passWithNoTests"
   },
   "dependencies": {
-    "@proteinjs/db-query": "^1.7.0",
+    "@proteinjs/db-query": "^1.7.1",
     "@proteinjs/logger": "^1.0.21",
-    "@proteinjs/reflection": "^1.1.12",
+    "@proteinjs/reflection": "^1.1.14",
     "@proteinjs/serializer": "^1.1.10",
     "@proteinjs/server-api": "^3.0.11",
     "@proteinjs/service": "^1.5.1",
@@ -53,7 +53,7 @@
     "uuid": "8.3.0"
   },
   "devDependencies": {
-    "@proteinjs/reflection-build": "^1.4.10",
+    "@proteinjs/reflection-build": "^2.0.1",
     "@types/jest": "29.5.5",
     "@types/node": "14.0.27",
     "@types/uuid": "8.3.0",
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "a5a56218a5757e47576cbe79858c9aacc6026816"
+  "gitHead": "d3a98c4cf7140cc2d93e588d89011037b3b8987c"
 }

package/src/Db.ts

@@ -1,4 +1,4 @@
-import { DbService, Query, QueryOptions, getDbService } from './services/DbService';
+import { DbService, ObjectQuery, Query, QueryOptions, getDbService } from './services/DbService';
 import { Service } from '@proteinjs/service';
 import { Loadable, SourceRepository } from '@proteinjs/reflection';
 import {
@@ -41,6 +41,19 @@ export const getDbAsSystem = <R extends Record = Record>() => new Db<R>(undefine
 const getEnvVar = (key: string): string | undefined =>
   typeof process !== 'undefined' && process.env ? process.env[key] : undefined;
 
+/**
+ * The lazily-resolved default driver lives on the global object (window in browser, globalThis
+ * elsewhere) rather than on a class static: per-package installs can put multiple live copies of
+ * @proteinjs/db in one process (each sibling package's nested node_modules hosts its own copy),
+ * and a per-copy static means every copy asks the DefaultDbDriverFactory for its own driver —
+ * multiple live db clients per process (two Spanner clients holding gRPC channels open was the
+ * 2026-08-14 thought-ui jest-never-exits incident). Anchoring on the global gives every copy the
+ * one driver — same pattern as reflection's SourceRepository and this package's ReferenceCache.
+ */
+const DEFAULT_DB_DRIVER_GLOBAL_KEY = '__proteinjs_db_defaultDbDriver';
+
+const getGlobal = (): any => (typeof window !== 'undefined' ? window : globalThis);
+
 export type DbDriverQueryStatementConfig = ParameterizationConfig & {
   prefixTablesWithDb?: boolean;
   getDriverColumnType?: (tableName: string, columnName: string) => string;
@@ -79,7 +92,6 @@ export interface DbDriver {
 }
 
 export class Db<R extends Record = Record> implements DbService<R> {
-  private static defaultDbDriver: DbDriver;
   private dbDriver: DbDriver;
   private getTable: (tableName: string) => Table<any>;
   private logger = new Logger({ name: this.constructor.name, logLevel: getEnvVar('DB_LOG_LEVEL') as any });
@@ -108,7 +120,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
   }
 
   static getDefaultDbDriver(): DbDriver {
-    if (!Db.defaultDbDriver) {
+    if (!getGlobal()[DEFAULT_DB_DRIVER_GLOBAL_KEY]) {
       const defaultDbDriverFactory = SourceRepository.get().object<DefaultDbDriverFactory>(
         '@proteinjs/db/DefaultDbDriverFactory'
       );
@@ -118,10 +130,10 @@ export class Db<R extends Record = Record> implements DbService<R> {
         );
       }
 
-      Db.defaultDbDriver = defaultDbDriverFactory.getDbDriver();
+      getGlobal()[DEFAULT_DB_DRIVER_GLOBAL_KEY] = defaultDbDriverFactory.getDbDriver();
     }
 
-    return Db.defaultDbDriver;
+    return getGlobal()[DEFAULT_DB_DRIVER_GLOBAL_KEY];
   }
 
   private getDefaultTransactionContextFactory(): DefaultTransactionContextFactory {
@@ -165,6 +177,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
         this.statementConfigFactory.getStatementConfig(config)
       );
     await this.dbDriver.runDml(generateInsert, this.transactionForDriver());
+    await this.runColumnAfterInsertHooks(table, recordCopy);
     await this.tableWatcherRunner.runAfterInsertTableWatchers(table, recordCopy as T);
     return recordCopy as T;
   }
@@ -208,6 +221,12 @@ export class Db<R extends Record = Record> implements DbService<R> {
         this.statementConfigFactory.getStatementConfig(config)
       );
     const recordUpdateCount = await this.dbDriver.runDml(generateUpdate, this.transactionForDriver());
+    if (!this.runAsSystem && recordUpdateCount === 0) {
+      const id = this.singleRowIdTarget(record, query);
+      if (id !== undefined) {
+        await this.runZeroRowFilteredWriteHooks(table, id, 'write');
+      }
+    }
     await this.tableWatcherRunner.runAfterUpdateTableWatchers(table, recordUpdateCount, recordCopy, qb);
     return recordUpdateCount;
   }
@@ -242,6 +261,13 @@ export class Db<R extends Record = Record> implements DbService<R> {
     qb.condition({ field: 'id', operator: '=', value: update.recordId as T[keyof T] });
     const rows = await this._query(table, qb);
     if (rows.length === 0) {
+      // Same id-targeted single-row refusal path as `update`/`delete`: 0 rows for a non-system
+      // caller can mean "row filtered out because the caller lacks write" — surface that as a
+      // typed refusal rather than a silent 0 (an existence-honest no-op still returns 0, since the
+      // hook only throws when the row exists AND the caller lacks write on its permission source).
+      if (!this.runAsSystem && typeof update.recordId === 'string') {
+        await this.runZeroRowFilteredWriteHooks(table, update.recordId, 'write');
+      }
       return 0;
     }
 
@@ -286,6 +312,11 @@ export class Db<R extends Record = Record> implements DbService<R> {
     qb.condition({ field: 'id', operator: '=', value: record.id as T[keyof T] });
     const rows = await this._query(table, qb);
     if (rows.length === 0) {
+      // See `updateArrayMembership`: fire the id-targeted zero-row refusal so a capability-denied
+      // preserving write surfaces a typed error instead of a silent 0.
+      if (!this.runAsSystem && typeof record.id === 'string') {
+        await this.runZeroRowFilteredWriteHooks(table, record.id, 'write');
+      }
       return 0;
     }
 
@@ -311,6 +342,12 @@ export class Db<R extends Record = Record> implements DbService<R> {
     await this.addColumnQueries(table, qb, 'delete');
     const recordsToDelete = await this._query(table, qb);
     if (recordsToDelete.length == 0) {
+      if (!this.runAsSystem) {
+        const id = this.singleRowIdTarget(undefined, query);
+        if (id !== undefined) {
+          await this.runZeroRowFilteredWriteHooks(table, id, 'delete');
+        }
+      }
       return 0;
     }
 
@@ -651,7 +688,45 @@ export class Db<R extends Record = Record> implements DbService<R> {
     for (const columnPropertyName in table.columns) {
       const column = (table.columns as any)[columnPropertyName] as Column<any, any>;
       if (column.options?.onBeforeInsert) {
-        await column.options.onBeforeInsert(record, this.runAsSystem);
+        await column.options.onBeforeInsert(table, record, this.runAsSystem);
+      }
+    }
+  }
+
+  /** Post-DML mirror of {@link addColumnInsertHooks} — see `ColumnOptions.onAfterInsert`. */
+  private async runColumnAfterInsertHooks(table: Table<any>, record: any) {
+    for (const columnPropertyName in table.columns) {
+      const column = (table.columns as any)[columnPropertyName] as Column<any, any>;
+      if (column.options?.onAfterInsert) {
+        await column.options.onAfterInsert(table, record, this.runAsSystem);
+      }
+    }
+  }
+
+  /**
+   * The single-row id a filtered write targets, or undefined when the write is not a single-row
+   * id target. Only these qualify for the `onZeroRowFilteredWrite` hook, so a multi-row filtered
+   * write that matches nothing is never mistaken for a capability denial. An arbitrary
+   * `QueryBuilder` is deliberately NOT introspected (returns undefined) — the id-target paths that
+   * matter (`update(table, { id, ... })` and `delete(table, { id })`) come through `record.id` or
+   * an `ObjectQuery`.
+   */
+  private singleRowIdTarget<T extends R>(record?: Partial<T>, query?: Query<T>): string | undefined {
+    if (query === undefined) {
+      return typeof record?.id === 'string' ? record.id : undefined;
+    }
+    if (isInstanceOf(query, QueryBuilder)) {
+      return undefined;
+    }
+    const objectQuery = query as ObjectQuery<T>;
+    return typeof objectQuery.id === 'string' ? objectQuery.id : undefined;
+  }
+
+  private async runZeroRowFilteredWriteHooks(table: Table<any>, id: string, operation: 'write' | 'delete') {
+    for (const columnPropertyName in table.columns) {
+      const column = (table.columns as any)[columnPropertyName] as Column<any, any>;
+      if (column.options?.onZeroRowFilteredWrite) {
+        await column.options.onZeroRowFilteredWrite(table, id, operation, this.runAsSystem);
       }
     }
   }

package/src/RecordAccessError.ts

@@ -0,0 +1,22 @@
+/**
+ * A ROW-LEVEL capability denial (distinct from `TableAuthError`, which denies at the table door).
+ *
+ * Raised when a caller passes the table's door auth but lacks the per-row capability a
+ * capability-scoped column enforces (e.g. a `SharedRecord`'s permission grants): inserting into a
+ * permission scope the caller cannot write, or an id-targeted single-row write that matched zero
+ * rows purely because the caller's grant level is insufficient. The point is to turn what used to
+ * be a SILENT zero-row result — which a caller (and an agent tool acting for them) cannot tell
+ * apart from a genuine no-op — into a signal a client can surface as "you don't have access".
+ *
+ * Name-tagged rather than relying on `instanceof`: the prototype chain is unreliable across
+ * package compile targets (same reason `TableAuthError` / `ServiceError` check `name`).
+ */
+export class RecordAccessError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RecordAccessError';
+  }
+}
+
+export const isRecordAccessError = (error: unknown): error is RecordAccessError =>
+  !!error && typeof error === 'object' && (error as { name?: string }).name === 'RecordAccessError';

package/src/Table.ts

@@ -169,7 +169,39 @@ export type ColumnOptions = {
   immutable?: boolean | ((runAsSystem: boolean) => boolean);
   /** Add conditions to query; called on every query of this table */
   addToQuery?: (qb: QueryBuilder, runAsSystem: boolean, operation: 'read' | 'write' | 'delete') => Promise<void>;
-  onBeforeInsert?: (insertObj: any & Record, runAsSystem: boolean) => Promise<void>;
+  /**
+   * Called before the row's insert DML runs, after defaults and before-insert table watchers.
+   * Runs where inserts execute (`Db.insert` — the server; a browser only ever proxies or queues),
+   * so guards here hold regardless of where column DEFAULTS were applied (the client `Transaction`
+   * path applies them in the browser). Throw to refuse the insert.
+   */
+  onBeforeInsert?: (table: Table<any>, insertObj: any & Record, runAsSystem: boolean) => Promise<void>;
+  /**
+   * Called after the row's insert DML SUCCEEDS, before after-insert table watchers. The seam for
+   * side-effect writes that are part of the row's birth (e.g. `SharedRecord`'s platform-conferred
+   * owner grant): running server-side keeps column defaults pure enough for driverless client
+   * contexts, and running after the DML means a failed insert (duplicate id, refused guard) can
+   * never leave the side effect behind.
+   */
+  onAfterInsert?: (table: Table<any>, insertObj: any & Record, runAsSystem: boolean) => Promise<void>;
+  /**
+   * Called after an id-targeted SINGLE-ROW filtered write (update or delete) on this table matched
+   * ZERO rows in a NON-system context. A column that narrows row visibility by capability (e.g.
+   * `SharedRecord`'s permission subquery) implements this to turn a silent 0 — which the caller
+   * cannot distinguish from a genuine capability denial — into a typed error. Return normally to
+   * leave the 0 as a legitimate no-op (row genuinely absent, or value unchanged for a caller who
+   * DOES hold the capability); throw (a `RecordAccessError`) to surface the refusal.
+   *
+   * Scope is deliberately narrow: only single-row id targets fire it, so a legitimate multi-row
+   * filtered write that matches nothing is never mis-flagged, and system-context maintenance
+   * writes never reach it.
+   */
+  onZeroRowFilteredWrite?: (
+    table: Table<any>,
+    id: string,
+    operation: 'write' | 'delete',
+    runAsSystem: boolean
+  ) => Promise<void>;
   ui?: {
     hidden?: boolean;
   };

package/test/DbDefaultDriverDuplicateModuleState.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Duplicate-module-instance guard for the default db driver (task #36).
+ *
+ * Per-package installs can put two live copies of @proteinjs/db in one process (each sibling
+ * package's nested node_modules hosts its own registry copy). `Db.defaultDbDriver` as a class
+ * static then splits per copy: every copy that lazily initializes asks the (globally converged,
+ * reflection-routed) DefaultDbDriverFactory for a driver, and the factory mints a fresh one per
+ * call — two live Spanner clients holding two gRPC channel sets. That is the 2026-08-14
+ * thought-ui incident: jest finished green and then never exited, the second universe's Spanner
+ * client keeping the process alive.
+ *
+ * `jest.isolateModules` reproduces the split semantics exactly: each isolated registry gets its
+ * own module instance of Db with its own statics, the same way two nested install paths do. The
+ * guard asserts every live copy resolves the SAME driver instance and the factory is consulted
+ * once — which only holds when the resolved driver is anchored on the process global, not on a
+ * per-copy class static.
+ */
+import { SourceRepository } from '@proteinjs/reflection';
+
+type DbModule = typeof import('../src/Db');
+
+const loadIsolatedCopy = (): DbModule => {
+  let copy: DbModule | undefined;
+  jest.isolateModules(() => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    copy = require('../src/Db');
+  });
+
+  if (!copy) {
+    throw new Error('Failed to load an isolated copy of Db');
+  }
+
+  return copy;
+};
+
+describe('Db default driver under duplicate module instances', () => {
+  let driversMinted: number;
+
+  beforeEach(() => {
+    driversMinted = 0;
+    // House test pattern: seed the (globalThis-anchored, therefore converged) SourceRepository
+    // object cache directly. The factory mints a fresh driver object per call, mirroring real
+    // DefaultDbDriverFactory implementations (e.g. the app's SpannerDriver factory).
+    (SourceRepository.get() as any).objectCache['@proteinjs/db/DefaultDbDriverFactory'] = [
+      {
+        getDbDriver: () => {
+          driversMinted++;
+          return { minted: driversMinted };
+        },
+      },
+    ];
+  });
+
+  afterEach(() => {
+    delete (SourceRepository.get() as any).objectCache['@proteinjs/db/DefaultDbDriverFactory'];
+    delete (globalThis as any).__proteinjs_db_defaultDbDriver;
+  });
+
+  test('every live copy of Db resolves the same default driver instance', () => {
+    const copyA = loadIsolatedCopy();
+    const copyB = loadIsolatedCopy();
+    expect(copyA).not.toBe(copyB); // two distinct module instances, as under per-package installs
+
+    const driverA = copyA.Db.getDefaultDbDriver();
+    const driverB = copyB.Db.getDefaultDbDriver();
+
+    expect(driverB).toBe(driverA); // one process, one driver — one live client
+    expect(driversMinted).toBe(1); // the factory is consulted exactly once per process
+  });
+});

package/test/util/tables/cascadeDeleteTestTables.ts

@@ -118,13 +118,13 @@ const MISSION_TABLE = 'db_test_cd_missions';
 // Cascade: ReferenceColumn
 export class MemberRefTable extends Table<MemberRef> {
   name = MEMBER_REF_TABLE;
-  columns = withRecordColumns<MemberRef>({
+  columns: Table<MemberRef>['columns'] = withRecordColumns<MemberRef>({
     name: new StringColumn('name'),
   });
 }
 export class GroupRefTable extends Table<GroupRef> {
   name = GROUP_REF_TABLE;
-  columns = withRecordColumns<GroupRef>({
+  columns: Table<GroupRef>['columns'] = withRecordColumns<GroupRef>({
     groupName: new StringColumn('group_name'),
     memberRef: new ReferenceColumn<MemberRef>(
       'member_id',
@@ -137,13 +137,13 @@ export class GroupRefTable extends Table<GroupRef> {
 // Cascade: ReferenceArrayColumn
 export class MemberArrTable extends Table<MemberArr> {
   name = MEMBER_ARR_TABLE;
-  columns = withRecordColumns<MemberArr>({
+  columns: Table<MemberArr>['columns'] = withRecordColumns<MemberArr>({
     name: new StringColumn('name'),
   });
 }
 export class GroupArrTable extends Table<GroupArr> {
   name = GROUP_ARR_TABLE;
-  columns = withRecordColumns<GroupArr>({
+  columns: Table<GroupArr>['columns'] = withRecordColumns<GroupArr>({
     groupName: new StringColumn('group_name'),
     memberRefs: new ReferenceArrayColumn<MemberArr>(
       'member_ids',
@@ -156,13 +156,13 @@ export class GroupArrTable extends Table<GroupArr> {
 // Cascade: DynamicReferenceColumn
 export class MemberDynTable extends Table<MemberDyn> {
   name = MEMBER_DYN_TABLE;
-  columns = withRecordColumns<MemberDyn>({
+  columns: Table<MemberDyn>['columns'] = withRecordColumns<MemberDyn>({
     name: new StringColumn('name'),
   });
 }
 export class GroupDynTable extends Table<GroupDyn> {
   name = GROUP_DYN_TABLE;
-  columns = withRecordColumns<GroupDyn>({
+  columns: Table<GroupDyn>['columns'] = withRecordColumns<GroupDyn>({
     groupName: new StringColumn('group_name'),
     memberDynTableName: new DynamicReferenceTableNameColumn('member_dyn_table_name', 'member_dyn_ref'),
     memberDynRef: new DynamicReferenceColumn<MemberDyn>(
@@ -176,13 +176,13 @@ export class GroupDynTable extends Table<GroupDyn> {
 // Reverse: ReferenceColumn
 export class PostTable extends Table<Post> {
   name = POST_TABLE;
-  columns = withRecordColumns<Post>({
+  columns: Table<Post>['columns'] = withRecordColumns<Post>({
     title: new StringColumn('title'),
   });
 }
 export class CommentTable extends Table<Comment> {
   name = COMMENT_TABLE;
-  columns = withRecordColumns<Comment>({
+  columns: Table<Comment>['columns'] = withRecordColumns<Comment>({
     text: new StringColumn('text'),
     postRef: new ReferenceColumn<Post>(
       'post_id',
@@ -196,13 +196,13 @@ export class CommentTable extends Table<Comment> {
 // Reverse: ReferenceArrayColumn
 export class MemberArrRevTable extends Table<MemberArrRev> {
   name = MEMBER_ARR_REV_TABLE;
-  columns = withRecordColumns<MemberArrRev>({
+  columns: Table<MemberArrRev>['columns'] = withRecordColumns<MemberArrRev>({
     name: new StringColumn('name'),
   });
 }
 export class GroupArrRevTable extends Table<GroupArrRev> {
   name = GROUP_ARR_REV_TABLE;
-  columns = withRecordColumns<GroupArrRev>({
+  columns: Table<GroupArrRev>['columns'] = withRecordColumns<GroupArrRev>({
     groupName: new StringColumn('group_name'),
     memberRefs: new ReferenceArrayColumn<MemberArrRev>(
       'member_ids',
@@ -216,13 +216,13 @@ export class GroupArrRevTable extends Table<GroupArrRev> {
 // Reverse: DynamicReferenceColumn
 export class WorkerTable extends Table<Worker> {
   name = WORKER_TABLE;
-  columns = withRecordColumns<Worker>({
+  columns: Table<Worker>['columns'] = withRecordColumns<Worker>({
     name: new StringColumn('name'),
   });
 }
 export class TaskTable extends Table<Task> {
   name = TASK_TABLE;
-  columns = withRecordColumns<Task>({
+  columns: Table<Task>['columns'] = withRecordColumns<Task>({
     title: new StringColumn('title'),
     assigneeTableName: new DynamicReferenceTableNameColumn('assignee_table_name', 'assignee_ref'),
     assigneeRef: new DynamicReferenceColumn<Worker>(
@@ -237,19 +237,19 @@ export class TaskTable extends Table<Task> {
 // Reverse: DynamicReferenceColumn across multiple target tables
 export class PilotTable extends Table<Pilot> {
   name = PILOT_TABLE;
-  columns = withRecordColumns<Pilot>({
+  columns: Table<Pilot>['columns'] = withRecordColumns<Pilot>({
     name: new StringColumn('name'),
   });
 }
 export class RobotTable extends Table<Robot> {
   name = ROBOT_TABLE;
-  columns = withRecordColumns<Robot>({
+  columns: Table<Robot>['columns'] = withRecordColumns<Robot>({
     name: new StringColumn('name'),
   });
 }
 export class MissionTable extends Table<Mission> {
   name = MISSION_TABLE;
-  columns = withRecordColumns<Mission>({
+  columns: Table<Mission>['columns'] = withRecordColumns<Mission>({
     title: new StringColumn('title'),
     assigneeTableName: new DynamicReferenceTableNameColumn('assignee_table_name', 'assignee_ref'),
     assigneeRef: new DynamicReferenceColumn<Pilot | Robot>(

package/test/util/tables/crudTestTables.ts

@@ -11,7 +11,7 @@ export interface Employee extends Record {
 
 export class EmployeeTestTable extends Table<Employee> {
   name = 'db_test_employee';
-  columns = withRecordColumns<Employee>({
+  columns: Table<Employee>['columns'] = withRecordColumns<Employee>({
     name: new StringColumn('name'),
     department: new StringColumn('department'),
     isRemote: new BooleanColumn('is_remote'),
@@ -30,7 +30,7 @@ export interface ReservedWordTest extends Record {
 
 export class ReservedWordTestTable extends Table<ReservedWordTest> {
   name = 'db_test_reserved_word';
-  columns = withRecordColumns<ReservedWordTest>({
+  columns: Table<ReservedWordTest>['columns'] = withRecordColumns<ReservedWordTest>({
     name: new StringColumn('name'),
     order: new StringColumn('order'),
     select: new StringColumn('select'),

package/test/util/tables/dynamicReferenceColumnTestTables.ts

@@ -34,7 +34,7 @@ export interface ProjectManager extends Record {
 
 export class ProjectAssignmentTable extends Table<ProjectAssignment> {
   name = 'db_test_dr_project_assignments';
-  columns = withRecordColumns<ProjectAssignment>({
+  columns: Table<ProjectAssignment>['columns'] = withRecordColumns<ProjectAssignment>({
     projectName: new StringColumn('project_name'),
     employeeTableName: new DynamicReferenceTableNameColumn('employee_table_name', 'employee_ref'),
     employeeRef: new DynamicReferenceColumn<Engineer | Designer | ProjectManager>(
@@ -57,7 +57,7 @@ export class ProjectAssignmentTable extends Table<ProjectAssignment> {
 
 export class EngineerTable extends Table<Engineer> {
   name = 'db_test_dr_engineers';
-  columns = withRecordColumns<Engineer>({
+  columns: Table<Engineer>['columns'] = withRecordColumns<Engineer>({
     name: new StringColumn('name'),
     yearsOfExperience: new StringColumn('years_of_experience'),
   });
@@ -65,7 +65,7 @@ export class EngineerTable extends Table<Engineer> {
 
 export class DesignerTable extends Table<Designer> {
   name = 'db_test_dr_designers';
-  columns = withRecordColumns<Designer>({
+  columns: Table<Designer>['columns'] = withRecordColumns<Designer>({
     name: new StringColumn('name'),
     specialization: new StringColumn('specialization'),
   });
@@ -73,7 +73,7 @@ export class DesignerTable extends Table<Designer> {
 
 export class ProjectManagerTable extends Table<ProjectManager> {
   name = 'db_test_dr_project_managers';
-  columns = withRecordColumns<ProjectManager>({
+  columns: Table<ProjectManager>['columns'] = withRecordColumns<ProjectManager>({
     name: new StringColumn('name'),
     certificate: new StringColumn('certificate'),
   });

package/test/util/tables/sourceRecordSyncTestTables.ts

@@ -30,7 +30,7 @@ export interface SyncMachineAccount extends SourceRecord {
 /** The machine-account shape: natural-key adoption by email, removed rows flagged not deleted. */
 export class SyncMachineAccountTable extends Table<SyncMachineAccount> {
   name = 'db_test_sync_machine_account';
-  columns = withSourceRecordColumns<SyncMachineAccount>({
+  columns: Table<SyncMachineAccount>['columns'] = withSourceRecordColumns<SyncMachineAccount>({
     email: new StringColumn('email', {
       unique: { unique: true, indexName: 'db_test_sync_machine_account_email_unique' },
     }),
@@ -52,7 +52,7 @@ export interface SyncDefaultPolicyRecord extends SourceRecord {
 /** Default options: id-keyed, removed source rows are deleted (today's behavior). */
 export class SyncDefaultPolicyTable extends Table<SyncDefaultPolicyRecord> {
   name = 'db_test_sync_default_policy';
-  columns = withSourceRecordColumns<SyncDefaultPolicyRecord>({
+  columns: Table<SyncDefaultPolicyRecord>['columns'] = withSourceRecordColumns<SyncDefaultPolicyRecord>({
     email: new StringColumn('email'),
     displayName: new StringColumn('display_name'),
   });
@@ -65,7 +65,7 @@ export interface DupePreflightRecord extends DbRecord {
 /** Generation 1: no uniqueness — the table under which duplicate rows accumulate. */
 export class DupePreflightTable extends Table<DupePreflightRecord> {
   name = 'db_test_dupe_preflight';
-  columns = withRecordColumns<DupePreflightRecord>({
+  columns: Table<DupePreflightRecord>['columns'] = withRecordColumns<DupePreflightRecord>({
     email: new StringColumn('email'),
   });
 }
@@ -73,7 +73,7 @@ export class DupePreflightTable extends Table<DupePreflightRecord> {
 /** Generation 2: same table, email now unique — loading it runs the alter-path preflight. */
 export class DupePreflightUniqueEmailTable extends Table<DupePreflightRecord> {
   name = 'db_test_dupe_preflight';
-  columns = withRecordColumns<DupePreflightRecord>({
+  columns: Table<DupePreflightRecord>['columns'] = withRecordColumns<DupePreflightRecord>({
     email: new StringColumn('email', { unique: { unique: true, indexName: 'db_test_dupe_preflight_email_unique' } }),
   });
 }

package/test/util/tables/tableManagerTestTables.ts

@@ -22,7 +22,7 @@ export interface User extends Record {
 
 export class UserTestTable extends Table<User> {
   name = 'db_test_user';
-  columns = withRecordColumns<User>({
+  columns: Table<User>['columns'] = withRecordColumns<User>({
     name: new StringColumn('name'),
     email: new StringColumn('email'),
     active: new BooleanColumn('active'),
@@ -41,7 +41,7 @@ export interface MappedIndexUser extends Record {
 
 export class MappedIndexUserTable extends Table<MappedIndexUser> {
   name = 'db_test_tm_mapped_index_user';
-  columns = withRecordColumns<MappedIndexUser>({
+  columns: Table<MappedIndexUser>['columns'] = withRecordColumns<MappedIndexUser>({
     emailAddress: new StringColumn('email_address'),
     accountStatus: new StringColumn('account_status'),
     createdOn: new DateColumn('created_on'),
@@ -75,7 +75,7 @@ export interface ColumnTypes extends Record {
 
 export class ColumnTypesTable extends Table<ColumnTypes> {
   name = 'db_test_tm_column_types';
-  columns = withRecordColumns<ColumnTypes>({
+  columns: Table<ColumnTypes>['columns'] = withRecordColumns<ColumnTypes>({
     integer: new IntegerColumn('integer', { nullable: true }),
     bigInteger: new IntegerColumn('big_integer', { nullable: false }, true),
     string: new StringColumn('string', { references: { table: 'db_test_user' } }),

package/test/util/tables/transactionTestTables.ts

@@ -11,7 +11,7 @@ export interface TransactionEmployee extends Record {
 
 export class TransactionEmployeeTestTable extends Table<TransactionEmployee> {
   name = 'db_test_transaction_employee';
-  columns = withRecordColumns<TransactionEmployee>({
+  columns: Table<TransactionEmployee>['columns'] = withRecordColumns<TransactionEmployee>({
     name: new StringColumn('name'),
     department: new StringColumn('department'),
     isRemote: new BooleanColumn('is_remote'),
@@ -30,7 +30,7 @@ export interface TransactionReservedWordTest extends Record {
 
 export class TransactionReservedWordTestTable extends Table<TransactionReservedWordTest> {
   name = 'db_test_transaction_reserved_word';
-  columns = withRecordColumns<TransactionReservedWordTest>({
+  columns: Table<TransactionReservedWordTest>['columns'] = withRecordColumns<TransactionReservedWordTest>({
     name: new StringColumn('name'),
     order: new StringColumn('order'),
     select: new StringColumn('select'),

package/test.d.ts

@@ -0,0 +1,2 @@
+// Types counterpart of test.js — see that file for why this stub exists.
+export * from './dist/generated/test/index';

package/test.js

@@ -0,0 +1,4 @@
+// Node10/classic-resolution stub for the `./test` subpath, owned by reflection-build.
+// Consumers that bypass the exports map (node10 resolution, tsconfig paths mappings) resolve
+// this file path first, so every install shape loads the built dist — never sources.
+module.exports = require('./dist/generated/test/index.js');

package/tsconfig.json

@@ -22,5 +22,6 @@
       "@proteinjs/db/*": ["src/*"],
       "@proteinjs/db/test": ["test/index.ts"]
     }
-  }
+  },
+  "exclude": ["node_modules", "test.js", "test.d.ts"]
 }