@@ -0,0 +1,247 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #20308 — a BLANK on a non-string-typed column reaches the driver as `null`,
+ * on every engine write door.
+ *
+ * ## The defect
+ *
+ * `validateOne` reads `''` (and whitespace) as missing and returns before its
+ * type checks, and nothing rewrote the value, so the driver received it as
+ * sent. Measured on `origin/main` de091b50e6 through the real engine: memory
+ * and SQLite stored `''` in number, currency, percent, rating, slider,
+ * progress, summary, boolean, toggle, date, datetime and time columns on every
+ * door (insert, insert[], insertMany, update by id, update by predicate), and
+ * PostgreSQL refused the statement (`22P02` / `22007`; `500 DATABASE_ERROR` at
+ * REST). One clear, three outcomes.
+ *
+ * ## What this file pins
+ *
+ * What the DRIVER receives, on each door — the one thing every backend then
+ * stores (memory and MongoDB store it verbatim; the SQL physical column is
+ * `packages/rest/src/rest-data-blank-typed-value.test.ts`). And the four
+ * interactions the door's placement decides:
+ *
+ *  - `required` refuses a blank exactly as it refuses `null` (same code);
+ *  - on insert a blank takes a declared `defaultValue` exactly as `null` does
+ *    (#2706) — the door runs BEFORE the defaults;
+ *  - a `readonlyWhen` lock still holds against a caller's blank — the door
+ *    runs BEFORE the caller-value snapshot the lock judges against;
+ *  - the dry run (`validate()`) agrees with the write.
+ *
+ * The string-stored controls (`text`, `lookup`, `select`) keep their `''` —
+ * the spec's `str_empty` side of the line.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { NON_TEXT_STORED_VALUE_TYPES } from '@objectstack/spec/data';
+import { ObjectQL } from './engine.js';
+import { ValidationError } from './validation/record-validator.js';
+
+const TYPED = [...NON_TEXT_STORED_VALUE_TYPES];
+const f = (t: string) => `f_${t}`;
+
+interface Call { fn: string; data: Record<string, unknown> }
+
+function makeStubDriver() {
+  const calls: Call[] = [];
+  const rows = new Map<string, Record<string, unknown>>();
+  const idOf = (q: any): string | undefined => {
+    const w = q?.where ?? q?.filter ?? q;
+    const id = w?.id;
+    return typeof id === 'string' ? id : undefined;
+  };
+  let n = 0;
+  const driver: any = {
+    name: 'stub', version: '0.0.0', supports: {},
+    async connect() {}, async disconnect() {}, async checkHealth() { return true; }, async execute() { return null; },
+    async find(_o: string, q: any) {
+      const id = idOf(q);
+      const inIds = q?.where?.id?.$in as string[] | undefined;
+      const all = [...rows.values()];
+      if (id) return all.filter((r) => r.id === id);
+      if (inIds) return all.filter((r) => inIds.includes(r.id as string));
+      return all;
+    },
+    async findOne(_o: string, q: any) {
+      const id = idOf(q);
+      return (id ? rows.get(id) : rows.values().next().value) ?? null;
+    },
+    async count() { return rows.size; },
+    async create(_o: string, data: Record<string, unknown>) {
+      calls.push({ fn: 'create', data: { ...data } });
+      const row = { ...data, id: (data.id as string) ?? `r${++n}` };
+      rows.set(row.id as string, row);
+      return row;
+    },
+    async bulkCreate(o: string, list: Record<string, unknown>[]) {
+      calls.push({ fn: 'bulkCreate', data: { rows: list.map((r) => ({ ...r })) } });
+      const out: Record<string, unknown>[] = [];
+      for (const r of list) {
+        const row = { ...r, id: (r.id as string) ?? `r${++n}` };
+        rows.set(row.id as string, row);
+        out.push(row);
+      }
+      return out;
+    },
+    async update(_o: string, id: string, data: Record<string, unknown>) {
+      calls.push({ fn: 'update', data: { ...data } });
+      const row = { ...(rows.get(id) ?? {}), ...data, id };
+      rows.set(id, row);
+      return row;
+    },
+    async updateMany(_o: string, _ast: unknown, data: Record<string, unknown>) {
+      calls.push({ fn: 'updateMany', data: { ...data } });
+      return rows.size;
+    },
+    async upsert(o: string, data: Record<string, unknown>) { return this.create(o, data); },
+    async delete() { return true; },
+    async bulkUpdate() { return []; }, async bulkDelete() {},
+    async beginTransaction() { return { commit: async () => {}, rollback: async () => {} }; },
+    async commit() {}, async rollback() {},
+  };
+  return { driver, calls, rows };
+}
+
+const OBJ = {
+  name: 'blank_door',
+  label: 'Blank door',
+  fields: {
+    id: { name: 'id', type: 'text' as const, primaryKey: true },
+    c_text: { name: 'c_text', type: 'text' as const },
+    c_lookup: { name: 'c_lookup', type: 'lookup' as const, reference: 'blank_door' },
+    c_select: { name: 'c_select', type: 'select' as const, options: [{ value: 'a', label: 'A' }] },
+    ...Object.fromEntries(TYPED.map((t) => [f(t), { name: f(t), type: t }])),
+  },
+};
+
+const REQ = {
+  name: 'blank_req',
+  label: 'Blank required',
+  fields: {
+    id: { name: 'id', type: 'text' as const, primaryKey: true },
+    status: { name: 'status', type: 'text' as const },
+    r_number: { name: 'r_number', type: 'number' as const, required: true },
+    rd_number: { name: 'rd_number', type: 'number' as const, required: true, defaultValue: 5 },
+    od_date: { name: 'od_date', type: 'date' as const, defaultValue: '2020-01-01' },
+    locked_amount: { name: 'locked_amount', type: 'number' as const, readonlyWhen: "record.status == 'closed'" },
+  },
+};
+
+const VALID: Record<string, unknown> = {
+  f_number: 0, f_currency: 9.5, f_percent: 0.25, f_rating: 3, f_slider: 10, f_progress: 50, f_summary: 7,
+  f_boolean: false, f_toggle: true, f_date: '2026-09-27', f_datetime: '2026-09-27T10:00:00.000Z', f_time: '14:30:00',
+};
+
+const blankTyped = (v: string) => Object.fromEntries(TYPED.map((t) => [f(t), v]));
+const STR_BLANK = { c_text: '', c_lookup: '', c_select: '' };
+
+function expectTypedNull(data: Record<string, unknown>) {
+  for (const t of TYPED) expect(data[f(t)], t).toBeNull();
+}
+
+describe('engine write doors: a blank on a non-string-typed column reaches the driver as null (#20308)', () => {
+  let engine: ObjectQL;
+  let stub: ReturnType<typeof makeStubDriver>;
+
+  beforeEach(async () => {
+    stub = makeStubDriver();
+    engine = new ObjectQL();
+    engine.registerDriver(stub.driver, true);
+    await engine.init();
+    engine.registry.registerObject(OBJ as any);
+    engine.registry.registerObject(REQ as any);
+  });
+
+  const last = (fn: string) => [...stub.calls].reverse().find((c) => c.fn === fn)!.data;
+
+  it.each([[''], ['  ']])('insert, one row: %j → null; the string-stored controls keep their blank', async (blank) => {
+    const payload = { id: 'a', ...blankTyped(blank), ...STR_BLANK };
+    await engine.insert('blank_door', payload);
+    const sent = last('create');
+    expectTypedNull(sent);
+    expect([sent.c_text, sent.c_lookup, sent.c_select]).toEqual(['', '', '']);
+    // The caller's own object is never rewritten.
+    expect(payload.f_number).toBe(blank);
+  });
+
+  it('insert, an array of rows and insertMany: every row', async () => {
+    await engine.insert('blank_door', [{ id: 'b1', ...blankTyped('') }, { id: 'b2', ...blankTyped('') }]);
+    const sent = [...stub.calls].filter((c) => c.fn === 'create' || c.fn === 'bulkCreate');
+    const written = sent.flatMap((c) => (c.fn === 'bulkCreate' ? (c.data.rows as Record<string, unknown>[]) : [c.data]));
+    expect(written.map((r) => r.id)).toEqual(['b1', 'b2']);
+    for (const r of written) expectTypedNull(r);
+
+    stub.calls.length = 0;
+    const outcomes = await engine.insertMany('blank_door', [{ id: 'm1', ...blankTyped('') }]);
+    expect(outcomes.map((o) => o.ok)).toEqual([true]);
+    const many = [...stub.calls].filter((c) => c.fn === 'create' || c.fn === 'bulkCreate')
+      .flatMap((c) => (c.fn === 'bulkCreate' ? (c.data.rows as Record<string, unknown>[]) : [c.data]));
+    expect(many).toHaveLength(1);
+    expectTypedNull(many[0]!);
+  });
+
+  it('update by id and update by predicate', async () => {
+    await engine.insert('blank_door', { id: 'u1', ...VALID });
+    await engine.update('blank_door', { id: 'u1', ...blankTyped(''), ...STR_BLANK });
+    const byId = last('update');
+    expectTypedNull(byId);
+    expect([byId.c_text, byId.c_lookup, byId.c_select]).toEqual(['', '', '']);
+
+    await engine.update('blank_door', blankTyped(''), { where: { id: { $in: ['u1'] } }, multi: true } as any);
+    expectTypedNull(last('updateMany'));
+  });
+
+  it('a valid value on every typed column — falsy ones included — is unchanged', async () => {
+    await engine.insert('blank_door', { id: 'v1', ...VALID });
+    const sent = last('create');
+    for (const [k, v] of Object.entries(VALID)) expect(sent[k], k).toStrictEqual(v);
+  });
+
+  it('required refuses a blank exactly as it refuses null — insert and update', async () => {
+    const codes = async (fn: () => Promise<unknown>) => {
+      try { await fn(); return null; } catch (e) {
+        expect(e).toBeInstanceOf(ValidationError);
+        return { code: (e as ValidationError).code, fields: (e as ValidationError).fields.map((x) => [x.field, x.code]) };
+      }
+    };
+    const blank = await codes(() => engine.insert('blank_req', { id: 'q1', r_number: '' }));
+    const nul = await codes(() => engine.insert('blank_req', { id: 'q2', r_number: null }));
+    expect(blank).toEqual({ code: 'VALIDATION_FAILED', fields: [['r_number', 'required']] });
+    expect(blank).toEqual(nul);
+
+    await engine.insert('blank_req', { id: 'q3', r_number: 1 });
+    const cleared = await codes(() => engine.update('blank_req', { id: 'q3', r_number: '' }));
+    expect(cleared).toEqual({ code: 'VALIDATION_FAILED', fields: [['r_number', 'required']] });
+  });
+
+  it('on insert a blank takes the declared defaultValue exactly as null does — required or not', async () => {
+    await engine.insert('blank_req', { id: 'd1', r_number: 1, rd_number: '', od_date: '' });
+    const blank = last('create');
+    await engine.insert('blank_req', { id: 'd2', r_number: 1, rd_number: null, od_date: null });
+    const nul = last('create');
+    expect([blank.rd_number, blank.od_date]).toEqual([5, '2020-01-01']);
+    expect([nul.rd_number, nul.od_date]).toEqual([5, '2020-01-01']);
+  });
+
+  it('the dry run agrees with the write on the same blank', async () => {
+    const preview = await engine.validate('blank_req', { id: 'p1', r_number: 1, rd_number: '' });
+    expect(preview.valid).toBe(true);
+    const refused = await engine.validate('blank_req', { id: 'p2', r_number: '' });
+    expect(refused.valid).toBe(false);
+    expect(refused.results?.[0]?.errors.map((e: any) => [e.field, e.code])).toEqual([['r_number', 'required']]);
+  });
+
+  it('a readonlyWhen lock still holds against a caller blank — the snapshot it judges is the normalised one', async () => {
+    await engine.insert('blank_req', { id: 'l1', r_number: 1, status: 'closed', locked_amount: 10 });
+    await engine.update('blank_req', { id: 'l1', locked_amount: '' });
+    const sent = last('update');
+    expect('locked_amount' in sent).toBe(false);
+    expect(stub.rows.get('l1')?.locked_amount).toBe(10);
+
+    // Unlocked, the same blank clears the column to null.
+    await engine.insert('blank_req', { id: 'l2', r_number: 1, status: 'open', locked_amount: 10 });
+    await engine.update('blank_req', { id: 'l2', locked_amount: '' });
+    expect(last('update').locked_amount).toBeNull();
+  });
+});
@@ -0,0 +1,141 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #20308 — the write door's reading of a BLANK string, and the numeric type
+ * door, at the validator module.
+ *
+ * `normalizeBlankTypedValues` rewrites `''` / whitespace on a non-string-typed
+ * column to `null` and leaves everything else alone. Both populations are read
+ * from the spec's own sets, so a type joining `NON_TEXT_STORED_VALUE_TYPES` or
+ * `NUMERIC_VALUE_TYPES` tomorrow is covered here without an edit — and a type
+ * leaving the string side would turn the control half red.
+ *
+ * The engine-level half (what reaches the driver on every door) is
+ * `../engine-blank-typed-value-door.test.ts`; the physical-column half, through
+ * REST on SQLite, is `packages/rest/src/rest-data-blank-typed-value.test.ts`.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  NON_TEXT_STORED_VALUE_TYPES,
+  NUMERIC_VALUE_TYPES,
+  STRING_VALUE_TYPES,
+} from '@objectstack/spec/data';
+import { normalizeBlankTypedValues, validateRecord, ValidationError } from './record-validator.js';
+
+const typed = [...NON_TEXT_STORED_VALUE_TYPES];
+// The string-stored controls: the whole string class, plus the other types
+// whose stored value is a string (`str_empty`'s side of the line).
+const stringStored = [...STRING_VALUE_TYPES, 'select', 'radio', 'lookup', 'master_detail', 'user', 'autonumber'];
+
+function schemaOf(types: readonly string[]) {
+  const fields: Record<string, { name: string; type: string; reference?: string; options?: unknown[] }> = {};
+  for (const t of types) {
+    fields[`f_${t}`] = {
+      name: `f_${t}`,
+      type: t,
+      ...(t === 'lookup' || t === 'master_detail' ? { reference: 'other' } : {}),
+      ...(t === 'select' || t === 'radio' ? { options: [{ value: 'a', label: 'A' }] } : {}),
+    };
+  }
+  return { fields } as any;
+}
+
+function rowOf(types: readonly string[], value: unknown) {
+  return Object.fromEntries(types.map((t) => [`f_${t}`, value]));
+}
+
+describe('normalizeBlankTypedValues (#20308)', () => {
+  it('the population is the spec set, and it is the one the card names', () => {
+    // A control on the set itself: if it ever emptied, every case below would
+    // pass over nothing.
+    expect(typed.sort()).toEqual(
+      ['boolean', 'currency', 'date', 'datetime', 'number', 'percent', 'progress', 'rating', 'slider', 'summary', 'time', 'toggle'],
+    );
+    for (const t of stringStored) expect(NON_TEXT_STORED_VALUE_TYPES.has(t)).toBe(false);
+  });
+
+  it.each([[''], ['   '], ['\t\n']])('a blank %j on every non-string-typed column becomes null', (blank) => {
+    const out = normalizeBlankTypedValues(schemaOf(typed), rowOf(typed, blank)) as Record<string, unknown>;
+    for (const t of typed) expect(out[`f_${t}`], t).toBeNull();
+  });
+
+  it("a string-stored column's blank is untouched — the str_empty side", () => {
+    for (const blank of ['', '  ']) {
+      const row = rowOf(stringStored, blank);
+      const out = normalizeBlankTypedValues(schemaOf(stringStored), row);
+      expect(out).toBe(row);
+      for (const t of stringStored) expect((out as Record<string, unknown>)[`f_${t}`], t).toBe(blank);
+    }
+  });
+
+  it('a non-blank value of any kind passes through untouched — falsy is not blank', () => {
+    for (const v of [null, undefined, 0, false, 'abc', ' x ', '0', 'false', '2026-09-27', 42, true]) {
+      const row = rowOf(typed, v);
+      expect(normalizeBlankTypedValues(schemaOf(typed), row), String(v)).toBe(row);
+    }
+  });
+
+  it('never mutates the caller: a copy comes back only when something changed', () => {
+    const schema = schemaOf(['number', 'text']);
+    const row = { f_number: '', f_text: '', extra: 1 };
+    const out = normalizeBlankTypedValues(schema, row) as Record<string, unknown>;
+    expect(out).not.toBe(row);
+    expect(row).toEqual({ f_number: '', f_text: '', extra: 1 });
+    expect(out).toEqual({ f_number: null, f_text: '', extra: 1 });
+  });
+
+  it('an array: rows copied only where they changed, the array only when a row did', () => {
+    const schema = schemaOf(['date', 'text']);
+    const clean = { f_date: '2026-01-01' };
+    const blank = { f_date: '' };
+    const rows = [clean, blank];
+    const out = normalizeBlankTypedValues(schema, rows) as Array<Record<string, unknown>>;
+    expect(out).not.toBe(rows);
+    expect(out[0]).toBe(clean);
+    expect(out[1]).toEqual({ f_date: null });
+    expect(rows[1]).toBe(blank);
+    expect(blank.f_date).toBe('');
+    const untouched = [clean, { f_text: '' }];
+    expect(normalizeBlankTypedValues(schema, untouched)).toBe(untouched);
+  });
+
+  it('an undeclared key, an inherited name and a schema without fields are left alone', () => {
+    const schema = schemaOf(['number']);
+    const row = { nope: '', constructor: '' };
+    expect(normalizeBlankTypedValues(schema, row)).toBe(row);
+    expect(normalizeBlankTypedValues({} as any, { f_number: '' })).toEqual({ f_number: '' });
+    expect(normalizeBlankTypedValues(null, { f_number: '' })).toEqual({ f_number: '' });
+  });
+});
+
+describe('the numeric type door is NUMERIC_VALUE_TYPES (#20308)', () => {
+  function refusal(type: string, value: unknown) {
+    try {
+      validateRecord(schemaOf([type]), { [`f_${type}`]: value }, 'insert');
+      return null;
+    } catch (e) {
+      expect(e).toBeInstanceOf(ValidationError);
+      return e as ValidationError;
+    }
+  }
+
+  it.each([...NUMERIC_VALUE_TYPES])('%s refuses a non-numeric string with invalid_number', (type) => {
+    const e = refusal(type, 'abc');
+    expect(e?.code).toBe('VALIDATION_FAILED');
+    expect(e?.fields.map((f) => [f.field, f.code])).toEqual([[`f_${type}`, 'invalid_number']]);
+  });
+
+  it.each([...NUMERIC_VALUE_TYPES])('%s still accepts a finite number', (type) => {
+    expect(refusal(type, 7)).toBeNull();
+  });
+
+  it('progress and summary take the type check only — no bound or scale is newly enforced', () => {
+    // The boundary the branch states: a declared `max` / `scale` on these two
+    // was never enforced, and this change does not start (a separate decision).
+    for (const type of ['progress', 'summary']) {
+      const fields = { [`f_${type}`]: { name: `f_${type}`, type, max: 100, scale: 0 } } as any;
+      expect(() => validateRecord({ fields }, { [`f_${type}`]: 150.5 }, 'insert'), type).not.toThrow();
+    }
+  });
+});