@proteinjs/db 1.54.1 → 1.54.3

package/test/HydrationBenchmark.test.ts

@@ -0,0 +1,209 @@
+import { createHook } from 'async_hooks';
+import { SourceRepository } from '@proteinjs/reflection';
+import { Db, DbDriver } from '../src/Db';
+import { TableWatcherRunner } from '../src/TableWatcherRunner';
+import { Table } from '../src/Table';
+import { Record, SerializedRecord, withRecordColumns } from '../src/Record';
+import { DateTimeColumn, IntegerColumn, ObjectColumn, StringColumn } from '../src/Columns';
+import { DefaultTransactionContextFactory, TransactionContextData } from '../src/transaction/TransactionContextFactory';
+import type { Moment } from 'moment';
+
+/**
+ * A MEASURE, never a gate: hydrating 1,000 rows with ten DateTime columns through `Db.query`, read
+ * as wall time, promises created (async_hooks) and microtask rounds — the numbers are printed for
+ * the person reading the run and nothing here asserts a threshold (CI's machines vary). The one
+ * assertion is that the rows came back.
+ */
+
+interface Wide extends Record {
+  title: string;
+  body: string;
+  count: number;
+  payload: { tags: string[]; n: number } | null;
+  t0: Moment | null;
+  t1: Moment | null;
+  t2: Moment | null;
+  t3: Moment | null;
+  t4: Moment | null;
+  t5: Moment | null;
+  t6: Moment | null;
+  t7: Moment | null;
+  t8: Moment | null;
+  t9: Moment | null;
+}
+
+class WideTable extends Table<Wide> {
+  public name = 'hydration_wide';
+  public columns = withRecordColumns<Wide>({
+    title: new StringColumn('title'),
+    body: new StringColumn('body', undefined, 'MAX'),
+    count: new IntegerColumn('count'),
+    payload: new ObjectColumn('payload'),
+    t0: new DateTimeColumn('t0'),
+    t1: new DateTimeColumn('t1'),
+    t2: new DateTimeColumn('t2'),
+    t3: new DateTimeColumn('t3'),
+    t4: new DateTimeColumn('t4'),
+    t5: new DateTimeColumn('t5'),
+    t6: new DateTimeColumn('t6'),
+    t7: new DateTimeColumn('t7'),
+    t8: new DateTimeColumn('t8'),
+    t9: new DateTimeColumn('t9'),
+  });
+}
+
+const wideTable = new WideTable() as Table<Wide>;
+
+class TestTransactionContextFactory implements DefaultTransactionContextFactory {
+  private context: TransactionContextData = {};
+
+  getTransactionContext(): TransactionContextData {
+    return this.context;
+  }
+
+  async runInContext<T>(context: TransactionContextData, fn: () => Promise<T>): Promise<T> {
+    const previous = this.context;
+    this.context = context;
+    try {
+      return await fn();
+    } finally {
+      this.context = previous;
+    }
+  }
+}
+
+class RowsDriver implements DbDriver {
+  constructor(private readonly rows: SerializedRecord[]) {}
+
+  getDbName(): string {
+    return 'test';
+  }
+
+  async createDbIfNotExists(): Promise<void> {}
+
+  async createDb(): Promise<void> {}
+
+  async dropDb(): Promise<void> {}
+
+  getTableManager(): never {
+    throw new Error('not used by this measure');
+  }
+
+  async runQuery(): Promise<SerializedRecord[]> {
+    return this.rows;
+  }
+
+  async runDml(): Promise<number> {
+    return 0;
+  }
+
+  async runTransaction<T>(fn: (transaction: unknown) => Promise<T>): Promise<T> {
+    return await fn({ id: 'transaction' });
+  }
+
+  getOperationDeadlineMs(): number {
+    return 1000;
+  }
+}
+
+type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+type TableWatcherRunnerStatics = { tableWatcherMap?: unknown };
+const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+let originalWatchers: unknown[] | undefined;
+
+// No reflection graph in a unit test: the watcher registry is empty by declaration.
+beforeAll(() => {
+  originalWatchers = objectCache()['@proteinjs/db/TableWatcher'];
+  objectCache()['@proteinjs/db/TableWatcher'] = [];
+  (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+});
+
+afterAll(() => {
+  if (originalWatchers) {
+    objectCache()['@proteinjs/db/TableWatcher'] = originalWatchers;
+  } else {
+    delete objectCache()['@proteinjs/db/TableWatcher'];
+  }
+  (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+});
+
+const storedRows = (count: number): SerializedRecord[] =>
+  Array.from({ length: count }, (_, row) => {
+    const stored: SerializedRecord = {
+      id: `row-${row}`,
+      created: new Date(1_600_000_000_000 + row),
+      updated: new Date(1_600_000_000_000 + row),
+      title: `title ${row}`,
+      body: 'x'.repeat(400),
+      count: row,
+      payload: JSON.stringify({ tags: ['a', 'b', 'c'], n: row }),
+    };
+    for (let i = 0; i < 10; i++) {
+      stored[`t${i}`] = new Date(1_700_000_000_000 + row * 100 + i);
+    }
+    return stored;
+  });
+
+type Measure = { ms: number; promises: number; microtaskRounds: number };
+
+/** Wall time, promises created and microtask rounds while `act` runs. */
+const measure = async (act: () => Promise<unknown>): Promise<Measure> => {
+  let promises = 0;
+  const hook = createHook({
+    init(_asyncId, type) {
+      if (type === 'PROMISE') {
+        promises++;
+      }
+    },
+  });
+  let microtaskRounds = 0;
+  let running = true;
+  const round = () => {
+    if (!running) {
+      return;
+    }
+    microtaskRounds++;
+    queueMicrotask(round);
+  };
+  hook.enable();
+  const started = process.hrtime.bigint();
+  queueMicrotask(round);
+  await act();
+  running = false;
+  const ms = Number(process.hrtime.bigint() - started) / 1_000_000;
+  hook.disable();
+  return { ms: Math.round(ms * 10) / 10, promises, microtaskRounds };
+};
+
+describe('hydration measure', () => {
+  it('reports 1,000 rows with ten DateTime columns through Db.query (wall ms, promises, microtask rounds)', async () => {
+    const rows = storedRows(1000);
+    const db = new Db(new RowsDriver(rows), () => wideTable, new TestTransactionContextFactory(), true);
+    // one warm-up pass, then the measured passes
+    await db.query(wideTable, {});
+
+    const passes: Measure[] = [];
+    let records: Wide[] = [];
+    for (let i = 0; i < 5; i++) {
+      passes.push(await measure(async () => (records = await db.query(wideTable, {}))));
+    }
+    const readAll = await measure(async () => {
+      for (const record of records) {
+        record.t0!.valueOf();
+        record.created.valueOf();
+      }
+    });
+
+    process.stdout.write(
+      `hydration measure — 1,000 rows × (10 DateTime + created/updated + 4 plain columns), Db.query, 5 passes:\n` +
+        passes
+          .map(
+            (pass, i) =>
+              `  pass ${i + 1}: ${pass.ms} ms · ${pass.promises} promises · ${pass.microtaskRounds} microtask rounds`
+          )
+          .join('\n') +
+        `\n  then reading t0 + created on every record: ${readAll.ms} ms · ${readAll.promises} promises\n`
+    );
+    expect(records).toHaveLength(1000);
+  });
+});

package/test/LegacyCellHydration.test.ts

@@ -0,0 +1,234 @@
+import { SourceRepository } from '@proteinjs/reflection';
+import { Db, DbDriver } from '../src/Db';
+import { TableWatcherRunner } from '../src/TableWatcherRunner';
+import { Column, Table } from '../src/Table';
+import { Record, RecordSerializer, SerializedRecord, withRecordColumns } from '../src/Record';
+import { ArrayColumn, ObjectColumn, StringColumn } from '../src/Columns';
+import { DefaultTransactionContextFactory, TransactionContextData } from '../src/transaction/TransactionContextFactory';
+
+/**
+ * A stored cell a column cannot deserialize — a legacy value written outside the serializer, say a
+ * bare word in a column that stores JSON — never takes the row, the result set or the process with
+ * it. The law the per-row hydration held (`try { deserialize } catch { omit }`) and the one-pass
+ * hydration dropped: the field is OMITTED from the record, every other field lands, the query's
+ * promise resolves, and ONE warning per table and column per process names the table, the column
+ * and the first row seen — never the stored value (the parser's own message quotes it).
+ */
+
+interface Doc extends Record {
+  title: string;
+  tags: string[];
+  settings: { theme: string };
+  after: string;
+}
+
+class DocTable extends Table<Doc> {
+  public name = 'legacy_cell_doc';
+  public columns = withRecordColumns<Doc>({
+    title: new StringColumn('title'),
+    tags: new ArrayColumn<string>('tag_list'),
+    settings: new ObjectColumn<{ theme: string }>('settings'),
+    after: new StringColumn('after'),
+  });
+}
+
+const docTable = new DocTable() as Table<Doc>;
+
+class TestTransactionContextFactory implements DefaultTransactionContextFactory {
+  private context: TransactionContextData = {};
+
+  getTransactionContext(): TransactionContextData {
+    return this.context;
+  }
+
+  async runInContext<T>(context: TransactionContextData, fn: () => Promise<T>): Promise<T> {
+    const previous = this.context;
+    this.context = context;
+    try {
+      return await fn();
+    } finally {
+      this.context = previous;
+    }
+  }
+}
+
+/** A driver that answers every query with the rows it was handed — the stored cells as the database holds them. */
+class RowsDriver implements DbDriver {
+  constructor(private readonly rows: SerializedRecord[]) {}
+
+  getDbName(): string {
+    return 'test';
+  }
+
+  async createDbIfNotExists(): Promise<void> {}
+
+  async createDb(): Promise<void> {}
+
+  async dropDb(): Promise<void> {}
+
+  getTableManager(): never {
+    throw new Error('not used by these tests');
+  }
+
+  async runQuery(): Promise<SerializedRecord[]> {
+    return this.rows;
+  }
+
+  async runDml(): Promise<number> {
+    return 0;
+  }
+
+  async runTransaction<T>(fn: (transaction: unknown) => Promise<T>): Promise<T> {
+    return await fn({ id: 'transaction' });
+  }
+
+  getOperationDeadlineMs(): number {
+    return 1000;
+  }
+}
+
+const dbOver = (table: Table<any>, rows: SerializedRecord[]) =>
+  new Db(new RowsDriver(rows), () => table, new TestTransactionContextFactory(), true);
+
+const storedRow = (id: string, cells: Partial<SerializedRecord>): SerializedRecord => ({
+  id,
+  created: new Date(1_700_000_000_000),
+  updated: new Date(1_700_000_000_000),
+  title: `title ${id}`,
+  tag_list: '["a","b"]',
+  settings: '{"theme":"dark"}',
+  after: `after ${id}`,
+  ...cells,
+});
+
+/** The stored value no warning may ever carry — distinctive, so a leak is unmistakable. */
+const LEGACY_WORD = 'legacyword7';
+
+type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+type TableWatcherRunnerStatics = { tableWatcherMap?: unknown };
+type SerializerInternals = { logger: { warn: (...args: unknown[]) => void; debug: (...args: unknown[]) => void } };
+/** The process-wide once-per-table-and-column registry behind the warning (reset per test). */
+type SerializerStatics = { legacyCellsWarned: Set<string> };
+const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+let originalWatchers: unknown[] | undefined;
+
+beforeEach(() => {
+  (RecordSerializer as unknown as SerializerStatics).legacyCellsWarned?.clear();
+});
+
+// No reflection graph in a unit test: the watcher registry is empty by declaration.
+beforeAll(() => {
+  originalWatchers = objectCache()['@proteinjs/db/TableWatcher'];
+  objectCache()['@proteinjs/db/TableWatcher'] = [];
+  (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+});
+
+afterAll(() => {
+  if (originalWatchers) {
+    objectCache()['@proteinjs/db/TableWatcher'] = originalWatchers;
+  } else {
+    delete objectCache()['@proteinjs/db/TableWatcher'];
+  }
+  (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+});
+
+/** Every warning a serializer logs, as the logger received it. */
+const warningsOf = (serializer: RecordSerializer<any>): unknown[][] => {
+  const calls: unknown[][] = [];
+  const logger = (serializer as unknown as SerializerInternals).logger;
+  logger.warn = (...args: unknown[]) => {
+    calls.push(args);
+  };
+  return calls;
+};
+
+describe('a stored cell a column cannot deserialize', () => {
+  it('a query over a row holding a legacy value resolves: the field is omitted, every other field lands', async () => {
+    const rows = [storedRow('r1', {}), storedRow('r2', { tag_list: LEGACY_WORD }), storedRow('r3', {})];
+
+    const records = await dbOver(docTable, rows).query(docTable, {});
+
+    expect(records.map((record) => record.id)).toEqual(['r1', 'r2', 'r3']);
+    expect(records[0].tags).toEqual(['a', 'b']);
+    expect(records[2].tags).toEqual(['a', 'b']);
+    expect(records[1]).not.toHaveProperty('tags');
+    expect(records[1]).toMatchObject({
+      id: 'r2',
+      title: 'title r2',
+      settings: { theme: 'dark' },
+      after: 'after r2',
+    });
+  });
+
+  it('a get of the row answers the record, not a rejection', async () => {
+    const rows = [storedRow('r2', { settings: LEGACY_WORD })];
+
+    const record = await dbOver(docTable, rows).get(docTable, { id: 'r2' });
+
+    expect(record).toMatchObject({ id: 'r2', title: 'title r2', tags: ['a', 'b'], after: 'after r2' });
+    expect(record).not.toHaveProperty('settings');
+  });
+
+  it('warns once per table and column per process, naming the table, the column and the first row — never the value', () => {
+    const serializer = new RecordSerializer<Doc>(docTable);
+    const warnings = warningsOf(serializer);
+    const rows = [
+      storedRow('r1', { tag_list: LEGACY_WORD }),
+      storedRow('r2', { tag_list: LEGACY_WORD }),
+      storedRow('r3', { settings: LEGACY_WORD }),
+    ];
+
+    const records = serializer.deserializeAll(rows) as Doc[];
+
+    expect(Array.isArray(records)).toBe(true);
+    expect(records.map((record) => record.id)).toEqual(['r1', 'r2', 'r3']);
+    expect(warnings).toHaveLength(2);
+    expect(warnings[0][0]).toMatchObject({
+      obj: { table: 'legacy_cell_doc', column: 'tag_list', id: 'r1', error: 'SyntaxError' },
+    });
+    expect(warnings[1][0]).toMatchObject({
+      obj: { table: 'legacy_cell_doc', column: 'settings', id: 'r3', error: 'SyntaxError' },
+    });
+    expect(JSON.stringify(warnings)).not.toContain(LEGACY_WORD);
+  });
+
+  it('a column whose deserialize answers with a rejecting promise is omitted the same way', async () => {
+    class LaterColumn implements Column<number, number> {
+      constructor(public name: string) {}
+
+      deserialize(storedValue: number | null): Promise<number | null> {
+        return storedValue === -1 ? Promise.reject(new RangeError('unreadable')) : Promise.resolve(storedValue);
+      }
+    }
+    interface Later extends Record {
+      title: string;
+      later: number;
+      after: string;
+    }
+    class LaterTable extends Table<Later> {
+      public name = 'legacy_cell_later';
+      public columns = withRecordColumns<Later>({
+        title: new StringColumn('title'),
+        later: new LaterColumn('later'),
+        after: new StringColumn('after'),
+      });
+    }
+    const laterTable = new LaterTable() as Table<Later>;
+    const serializer = new RecordSerializer<Later>(laterTable);
+    const warnings = warningsOf(serializer);
+    const rows: SerializedRecord[] = [
+      { id: 'l1', title: 'one', later: 1, after: 'x' },
+      { id: 'l2', title: 'two', later: -1, after: 'y' },
+    ];
+
+    const records = await serializer.deserializeAll(rows);
+
+    expect(records[0]).toMatchObject({ id: 'l1', title: 'one', later: 1, after: 'x' });
+    expect(records[1]).toMatchObject({ id: 'l2', title: 'two', after: 'y' });
+    expect(records[1]).not.toHaveProperty('later');
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0][0]).toMatchObject({
+      obj: { table: 'legacy_cell_later', column: 'later', id: 'l2', error: 'RangeError' },
+    });
+  });
+});

package/test/SyncRowHydration.test.ts

@@ -0,0 +1,249 @@
+import { randomBytes } from 'crypto';
+import { SourceRepository } from '@proteinjs/reflection';
+import { Db, DbDriver } from '../src/Db';
+import { TableWatcherRunner } from '../src/TableWatcherRunner';
+import { Column, Table } from '../src/Table';
+import { Record, RecordSerializer, SerializedRecord, withRecordColumns } from '../src/Record';
+import { IntegerColumn, StringColumn } from '../src/Columns';
+import { DefaultTransactionContextFactory, TransactionContextData } from '../src/transaction/TransactionContextFactory';
+import { DataKeyMaterial, DataKeyStore } from '../src/encryption/DataKeyStore';
+import { EncryptionEnvelope } from '../src/encryption/EncryptionEnvelope';
+
+/**
+ * How a result set becomes records: in ONE synchronous pass when no row needs an await — no promise
+ * per row, no yield of the event loop between rows (the per-row async chain was the loop's holder
+ * under a large read: one awaited generator per row, per hook and per column) — while a row that
+ * does need an await (a ciphertext envelope whose key is read asynchronously, a column whose
+ * `deserialize` answers with a promise) still settles, through one promise for the set.
+ */
+
+interface Doc extends Record {
+  title: string;
+  first: number;
+  second: number;
+}
+
+/** Where the loop stood when each cell was read: the row, and whether the sentinel had fired by then. */
+const cellsRead: { column: string; row: number; sentinelFired: boolean }[] = [];
+let sentinelFired = false;
+
+/**
+ * A column that notes, at each read, whether a microtask armed by the FIRST cell read has fired yet:
+ * a hydration that yields the loop between rows lets it fire mid-way; a synchronous one never does.
+ */
+class ObservingColumn implements Column<number, number> {
+  constructor(public name: string) {}
+
+  deserialize(storedValue: number | null): number | null {
+    if (cellsRead.length === 0) {
+      queueMicrotask(() => {
+        sentinelFired = true;
+      });
+    }
+
+    cellsRead.push({ column: this.name, row: storedValue as number, sentinelFired });
+    return storedValue;
+  }
+}
+
+class DocTable extends Table<Doc> {
+  public name = 'hydration_doc';
+  public columns = withRecordColumns<Doc>({
+    title: new StringColumn('title'),
+    first: new ObservingColumn('first'),
+    second: new ObservingColumn('second'),
+  });
+}
+
+const docTable = new DocTable() as Table<Doc>;
+
+class TestTransactionContextFactory implements DefaultTransactionContextFactory {
+  private context: TransactionContextData = {};
+
+  getTransactionContext(): TransactionContextData {
+    return this.context;
+  }
+
+  async runInContext<T>(context: TransactionContextData, fn: () => Promise<T>): Promise<T> {
+    const previous = this.context;
+    this.context = context;
+    try {
+      return await fn();
+    } finally {
+      this.context = previous;
+    }
+  }
+}
+
+/** A driver that answers every query with the rows it was handed. */
+class RowsDriver implements DbDriver {
+  constructor(private readonly rows: SerializedRecord[]) {}
+
+  getDbName(): string {
+    return 'test';
+  }
+
+  async createDbIfNotExists(): Promise<void> {}
+
+  async createDb(): Promise<void> {}
+
+  async dropDb(): Promise<void> {}
+
+  getTableManager(): never {
+    throw new Error('not used by these tests');
+  }
+
+  async runQuery(): Promise<SerializedRecord[]> {
+    return this.rows;
+  }
+
+  async runDml(): Promise<number> {
+    return 0;
+  }
+
+  async runTransaction<T>(fn: (transaction: unknown) => Promise<T>): Promise<T> {
+    return await fn({ id: 'transaction' });
+  }
+
+  getOperationDeadlineMs(): number {
+    return 1000;
+  }
+}
+
+const dbOver = (rows: SerializedRecord[]) =>
+  new Db(new RowsDriver(rows), () => docTable, new TestTransactionContextFactory(), true);
+
+const storedRows = (count: number): SerializedRecord[] =>
+  Array.from({ length: count }, (_, i) => ({
+    id: `row-${i}`,
+    created: new Date(1_700_000_000_000 + i),
+    updated: new Date(1_700_000_000_000 + i),
+    title: `title ${i}`,
+    first: i,
+    second: i,
+  }));
+
+type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+type TableWatcherRunnerStatics = { tableWatcherMap?: unknown };
+const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+let originalWatchers: unknown[] | undefined;
+
+// No reflection graph in a unit test: the watcher registry is empty by declaration.
+beforeAll(() => {
+  originalWatchers = objectCache()['@proteinjs/db/TableWatcher'];
+  objectCache()['@proteinjs/db/TableWatcher'] = [];
+  (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+});
+
+afterAll(() => {
+  if (originalWatchers) {
+    objectCache()['@proteinjs/db/TableWatcher'] = originalWatchers;
+  } else {
+    delete objectCache()['@proteinjs/db/TableWatcher'];
+  }
+  (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+});
+
+const keyFor = (owner: string, version: number): DataKeyMaterial => ({
+  owner,
+  version,
+  cipherKey: randomBytes(32),
+  indexKey: randomBytes(32),
+});
+
+describe('a result set hydrates in one synchronous pass when no row needs an await', () => {
+  beforeEach(() => {
+    cellsRead.length = 0;
+    sentinelFired = false;
+  });
+
+  it('a query over plain rows never yields the event loop between rows', async () => {
+    const rows = storedRows(200);
+
+    const records = await dbOver(rows).query(docTable, {});
+
+    expect(records).toHaveLength(200);
+    expect(records[199]).toMatchObject({ id: 'row-199', title: 'title 199', first: 199, second: 199 });
+    // Every cell of every row was read before the microtask armed by the first cell could fire.
+    expect(cellsRead).toHaveLength(400);
+    expect(cellsRead.filter((cell) => cell.sentinelFired).map((cell) => `${cell.column}:${cell.row}`)).toEqual([]);
+    expect(sentinelFired).toBe(true);
+  });
+
+  it('the serializer answers a plain result set with the array itself, not a promise', () => {
+    const rows = storedRows(3);
+
+    const records = new RecordSerializer<Doc>(docTable).deserializeAll(rows);
+
+    expect(Array.isArray(records)).toBe(true);
+    expect((records as Doc[]).map((record) => record.title)).toEqual(['title 0', 'title 1', 'title 2']);
+  });
+
+  it('a column whose deserialize answers with a promise still settles, in column order', async () => {
+    class LaterColumn implements Column<number, number> {
+      constructor(public name: string) {}
+
+      deserialize(storedValue: number | null): Promise<number | null> {
+        return Promise.resolve(storedValue === null ? null : storedValue * 2);
+      }
+    }
+    interface Later extends Record {
+      title: string;
+      later: number;
+      after: string;
+    }
+    class LaterTable extends Table<Later> {
+      public name = 'hydration_later';
+      public columns = withRecordColumns<Later>({
+        title: new StringColumn('title'),
+        later: new LaterColumn('later'),
+        after: new StringColumn('after'),
+      });
+    }
+    const laterTable = new LaterTable() as Table<Later>;
+    const rows: SerializedRecord[] = [
+      { id: 'a', created: new Date(), updated: new Date(), title: 'one', later: 21, after: 'x' },
+      { id: 'b', created: new Date(), updated: new Date(), title: 'two', later: null, after: 'y' },
+    ];
+
+    const settling = new RecordSerializer<Later>(laterTable).deserializeAll(rows);
+
+    expect(Array.isArray(settling)).toBe(false);
+    const records = await settling;
+    expect(records.map((record) => record.later)).toEqual([42, null]);
+    expect(Object.keys(records[0])).toEqual(['id', 'created', 'updated', 'title', 'later', 'after']);
+  });
+
+  it('a row holding a ciphertext envelope takes the async road and decrypts; its plain neighbors ride along', async () => {
+    const key = keyFor('owner-1', 4);
+    const envelope = new EncryptionEnvelope();
+    const keyRead = jest.spyOn(DataKeyStore.prototype, 'getKeyByVersion').mockResolvedValue(key);
+    try {
+      const rows = storedRows(3);
+      rows[1].title = envelope.encrypt('the plaintext', key);
+
+      const settling = new RecordSerializer<Doc>(docTable).deserializeAll(rows);
+
+      expect(Array.isArray(settling)).toBe(false);
+      const records = await settling;
+      expect(records.map((record) => record.title)).toEqual(['title 0', 'the plaintext', 'title 2']);
+      expect(keyRead).toHaveBeenCalledTimes(1);
+      expect(keyRead).toHaveBeenCalledWith('owner-1', 4);
+      // The plain rows were hydrated in the one pass; the envelope row landed when its key read settled.
+      expect(cellsRead.map((cell) => cell.row)).toEqual([0, 0, 2, 2, 1, 1]);
+    } finally {
+      keyRead.mockRestore();
+    }
+  });
+
+  it('a stored column the table no longer declares is omitted; a column without deserialize passes its value through', async () => {
+    const rows: SerializedRecord[] = [
+      { id: 'a', created: new Date(), updated: new Date(), title: 'one', first: 1, second: 1, retired: 'gone' },
+    ];
+
+    const [record] = (await new RecordSerializer<Doc>(docTable).deserializeAll(rows)) as Doc[];
+
+    expect(record).toMatchObject({ id: 'a', title: 'one', first: 1, second: 1 });
+    expect('retired' in record).toBe(false);
+  });
+});