cursedbelt-core 1.0.0

package/src/core/palette/hotkeys.ts

@@ -0,0 +1,132 @@
+// Platform-portable keyboard-shortcut parsing, matching, and display formatting.
+// React-free (pure functions + DOM event/`navigator` reads, no React) so the
+// ShortcutRegistry, the `useHotkeys` hook, and the palette badge all share one
+// source of truth for "what does `$mod+k` mean and how is it drawn?".
+//
+// Binding syntax is the tinykeys format — `'+'`-separated modifiers then a key:
+//   `$mod+k`   → ⌘K on macOS, Ctrl K elsewhere   (the portable command modifier)
+//   `alt+b`    → ⌥B on macOS, Alt B elsewhere
+//   `shift+?`  → ⇧?
+// `$mod` is the whole point: one binding, correct on every platform.
+
+/** The four modifier flags a binding can require. */
+interface HotkeyMods {
+  meta: boolean;
+  ctrl: boolean;
+  alt: boolean;
+  shift: boolean;
+}
+
+/** A parsed binding: the required modifier set + the final (lower-cased) key. */
+export interface ParsedHotkey extends HotkeyMods {
+  key: string;
+}
+
+/**
+ * Is this an Apple platform (macOS / iOS)? Decides whether `$mod` means ⌘ (Meta) or
+ * Ctrl, and which glyphs the badge draws. Guarded for non-DOM (SSR / unit) hosts —
+ * returns `false` when there's no `navigator`.
+ */
+export function isApplePlatform(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  // `navigator.platform` is the most reliable signal but is being deprecated, so fall
+  // back to the UA string. Covers Mac, iPhone, iPad, iPod (incl. iPadOS desktop-UA).
+  const probe = `${navigator.platform ?? ''} ${navigator.userAgent ?? ''}`;
+  return /mac|iphone|ipad|ipod/i.test(probe);
+}
+
+/** Split a `'+'`-separated binding into its required modifiers + final key. */
+export function parseHotkey(binding: string, isApple = isApplePlatform()): ParsedHotkey {
+  const parts = binding
+    .toLowerCase()
+    .split('+')
+    .map((p) => p.trim())
+    .filter(Boolean);
+  const key = parts.pop() ?? '';
+  const tokens = new Set(parts);
+  const mod = tokens.has('$mod');
+  return {
+    key,
+    meta: tokens.has('meta') || tokens.has('cmd') || tokens.has('command') || (mod && isApple),
+    ctrl: tokens.has('ctrl') || tokens.has('control') || (mod && !isApple),
+    alt: tokens.has('alt') || tokens.has('option') || tokens.has('opt'),
+    shift: tokens.has('shift'),
+  };
+}
+
+/** Does a keyboard event satisfy `binding` — exact modifier set + the key? */
+export function matchHotkey(
+  e: KeyboardEvent,
+  binding: string,
+  isApple = isApplePlatform(),
+): boolean {
+  const want = parseHotkey(binding, isApple);
+  // Exact modifier match (not "at least") so `$mod+k` never fires on ⌘⇧K.
+  if (e.metaKey !== want.meta) return false;
+  if (e.ctrlKey !== want.ctrl) return false;
+  if (e.altKey !== want.alt) return false;
+  if (e.shiftKey !== want.shift) return false;
+  return eventMatchesKey(e, want.key);
+}
+
+/**
+ * Match the produced `key`, falling back to the physical `code` — because on macOS a
+ * held Option mutates `event.key` (⌥B yields "∫"), so an `alt+b` binding must match on
+ * `KeyB` too. Letters + digits are covered (the practical shortcut surface).
+ */
+function eventMatchesKey(e: KeyboardEvent, key: string): boolean {
+  if (!key) return false;
+  if (e.key.toLowerCase() === key) return true;
+  if (key.length === 1 && key >= 'a' && key <= 'z' && e.code === `Key${key.toUpperCase()}`) {
+    return true;
+  }
+  if (key.length === 1 && key >= '0' && key <= '9' && e.code === `Digit${key}`) return true;
+  return false;
+}
+
+const MAC_GLYPH: Record<keyof HotkeyMods, string> = {
+  meta: '⌘',
+  ctrl: '⌃',
+  alt: '⌥',
+  shift: '⇧',
+};
+const PC_WORD: Record<keyof HotkeyMods, string> = {
+  meta: 'Win',
+  ctrl: 'Ctrl',
+  alt: 'Alt',
+  shift: 'Shift',
+};
+
+/** Pretty-print a key token for display: a letter/digit upper-cases, named keys title-case. */
+function displayKey(key: string): string {
+  if (key.length === 1) return key.toUpperCase();
+  const named: Record<string, string> = {
+    arrowup: '↑',
+    arrowdown: '↓',
+    arrowleft: '←',
+    arrowright: '→',
+    enter: '↵',
+    escape: 'Esc',
+    backspace: '⌫',
+    delete: 'Del',
+    ' ': 'Space',
+    space: 'Space',
+  };
+  return named[key] ?? key.charAt(0).toUpperCase() + key.slice(1);
+}
+
+/**
+ * Render a binding as a human badge for the platform: macOS draws glyphs with no
+ * separator (`⌘K`, `⌥B`, `⌃⇧P`); elsewhere words joined with a thin space (`Ctrl K`,
+ * `Alt B`). The palette input badge + the per-row shortcut labels both use this.
+ */
+export function formatHotkey(binding: string, isApple = isApplePlatform()): string {
+  const p = parseHotkey(binding, isApple);
+  const order: (keyof HotkeyMods)[] = isApple
+    ? ['ctrl', 'alt', 'shift', 'meta'] // Apple convention: ⌃⌥⇧⌘ then key
+    : ['ctrl', 'meta', 'alt', 'shift'];
+  const mods = order.filter((m) => p[m]).map((m) => (isApple ? MAC_GLYPH[m] : PC_WORD[m]));
+  const key = displayKey(p.key);
+  if (isApple) return [...mods, key].join('');
+  return [...mods, key].join(' ');
+}

package/src/core/palette/index.ts

@@ -0,0 +1,22 @@
+// `cursedbelt-core/palette` — the React-free command-palette core: the uFuzzy ranking
+// layer, the shortcut registry, and the portable hotkey utilities. No React, no
+// browser dependency beyond optional `navigator`/event reads — usable in a startup
+// module, a server test, or the React layer alike. The `CommandPalette` component +
+// its hooks live in `cursedbelt/react` and build on exactly this.
+
+export {
+  fuzzyRankItems,
+  searchInitials,
+} from './fuzzyRank';
+export {
+  formatHotkey,
+  isApplePlatform,
+  matchHotkey,
+  type ParsedHotkey,
+  parseHotkey,
+} from './hotkeys';
+export {
+  type ShortcutEntry,
+  ShortcutRegistry,
+  shortcutRegistry,
+} from './ShortcutRegistry';

package/src/core/palette/palette.spec.ts

@@ -0,0 +1,160 @@
+import { describe, expect, mock, test } from 'bun:test';
+import type { NavItem } from '../navigation';
+import { fuzzyRankItems, searchInitials } from './fuzzyRank';
+import { formatHotkey, matchHotkey, parseHotkey } from './hotkeys';
+import { ShortcutRegistry } from './ShortcutRegistry';
+
+// ── fuzzyRank ────────────────────────────────────────────────────────────────
+
+const item = (label: string, keywords?: string[]): NavItem => ({
+  id: label.toLowerCase().replace(/\s+/g, '-'),
+  path: `/${label.toLowerCase().replace(/\s+/g, '-')}`,
+  label,
+  keywords,
+});
+
+const ITEMS: NavItem[] = [
+  item('Fractal', ['mandelbrot', 'zoom']),
+  item('Format Lab'),
+  item('Query Builder'),
+  item('Contacts'),
+  item('Env Sets', ['environment', 'variables']),
+  item('Shell Aliases'),
+  item('System Health'),
+  item('Calendar'),
+];
+
+const labels = (xs: NavItem[]) => xs.map((x) => x.label);
+
+describe('searchInitials', () => {
+  test('multi-word labels yield their initials; single-word yield ""', () => {
+    expect(searchInitials('Query Builder')).toBe('qb');
+    expect(searchInitials('System Health')).toBe('sh');
+    expect(searchInitials('Env Sets')).toBe('es');
+    expect(searchInitials('Fractal')).toBe('');
+  });
+});
+
+describe('fuzzyRankItems', () => {
+  test('contiguous prefix ranks first: "frac" → Fractal', () => {
+    expect(labels(fuzzyRankItems('frac', ITEMS))[0]).toBe('Fractal');
+  });
+
+  test('"frac" ranks Fractal above the also-matching Format Lab', () => {
+    const ranked = labels(fuzzyRankItems('frac', ITEMS));
+    expect(ranked).toContain('Fractal');
+    if (ranked.includes('Format Lab')) {
+      expect(ranked.indexOf('Fractal')).toBeLessThan(ranked.indexOf('Format Lab'));
+    }
+  });
+
+  test('initialism matching: "qb" surfaces Query Builder (was a search gap)', () => {
+    expect(labels(fuzzyRankItems('qb', ITEMS))).toContain('Query Builder');
+  });
+
+  test('full-word: "query" surfaces Query Builder', () => {
+    expect(labels(fuzzyRankItems('query', ITEMS))[0]).toBe('Query Builder');
+  });
+
+  test('keyword matching: "environment" finds Env Sets', () => {
+    expect(labels(fuzzyRankItems('environment', ITEMS))).toContain('Env Sets');
+  });
+
+  test('blank / non-matching queries return []', () => {
+    expect(fuzzyRankItems('', ITEMS)).toEqual([]);
+    expect(fuzzyRankItems('   ', ITEMS)).toEqual([]);
+    expect(fuzzyRankItems('zzqzzx', ITEMS)).toEqual([]);
+  });
+
+  test('carries through extra fields on richer entry types (domain tags)', () => {
+    type Tagged = NavItem & { domainId: string };
+    const tagged: Tagged[] = [{ ...item('Fractal'), domainId: 'play' }];
+    const out = fuzzyRankItems('frac', tagged);
+    expect(out[0]?.domainId).toBe('play');
+  });
+});
+
+// ── hotkeys ──────────────────────────────────────────────────────────────────
+
+const kd = (init: KeyboardEventInit) => new KeyboardEvent('keydown', init);
+
+describe('parseHotkey', () => {
+  test('$mod resolves to Meta on Apple, Control elsewhere', () => {
+    expect(parseHotkey('$mod+k', true)).toMatchObject({ meta: true, ctrl: false, key: 'k' });
+    expect(parseHotkey('$mod+k', false)).toMatchObject({ meta: false, ctrl: true, key: 'k' });
+  });
+  test('named modifiers + final key', () => {
+    expect(parseHotkey('alt+shift+b')).toMatchObject({ alt: true, shift: true, key: 'b' });
+  });
+});
+
+describe('matchHotkey', () => {
+  test('$mod+k matches Ctrl-K off Apple, Cmd-K on Apple', () => {
+    expect(matchHotkey(kd({ key: 'k', ctrlKey: true }), '$mod+k', false)).toBe(true);
+    expect(matchHotkey(kd({ key: 'k', metaKey: true }), '$mod+k', true)).toBe(true);
+  });
+  test('exact modifier set — ⌘⇧K does not satisfy $mod+k', () => {
+    expect(matchHotkey(kd({ key: 'k', metaKey: true, shiftKey: true }), '$mod+k', true)).toBe(
+      false,
+    );
+  });
+  test('wrong platform modifier does not match', () => {
+    // Cmd-K on a non-Apple host (where $mod means Ctrl) must not fire.
+    expect(matchHotkey(kd({ key: 'k', metaKey: true }), '$mod+k', false)).toBe(false);
+  });
+  test('falls back to physical code (macOS Option mutates event.key)', () => {
+    // ⌥B yields key "∫" on macOS — matching must still recognize it via code KeyB.
+    expect(matchHotkey(kd({ key: '∫', code: 'KeyB', altKey: true }), 'alt+b', true)).toBe(true);
+  });
+});
+
+describe('formatHotkey', () => {
+  test('Apple draws glyphs with no separator; PC draws words', () => {
+    expect(formatHotkey('$mod+k', true)).toBe('⌘K');
+    expect(formatHotkey('$mod+k', false)).toBe('Ctrl K');
+    expect(formatHotkey('alt+b', true)).toBe('⌥B');
+    expect(formatHotkey('alt+b', false)).toBe('Alt B');
+  });
+  test('multiple modifiers order Apple-style (⌃⌥⇧⌘)', () => {
+    expect(formatHotkey('$mod+shift+p', true)).toBe('⇧⌘P');
+  });
+});
+
+// ── ShortcutRegistry ──────────────────────────────────────────────────────────
+
+describe('ShortcutRegistry', () => {
+  test('register / getAll / replace-by-keys / unregister', () => {
+    const reg = new ShortcutRegistry();
+    reg.register({ label: 'Board', keys: 'alt+b', action: 'Open the board' });
+    reg.register({ label: 'Notes', keys: 'alt+n', action: 'Open notes' });
+    expect(reg.getAll()).toHaveLength(2);
+
+    // Same keys → replace, not duplicate.
+    reg.register({ label: 'Board v2', keys: 'alt+b', action: 'Open the board' });
+    expect(reg.getAll()).toHaveLength(2);
+    expect(reg.getAll().find((s) => s.keys === 'alt+b')?.label).toBe('Board v2');
+
+    reg.unregister('alt+n');
+    expect(reg.getAll().map((s) => s.keys)).toEqual(['alt+b']);
+  });
+
+  test('getAll snapshot is stable between mutations (for useSyncExternalStore)', () => {
+    const reg = new ShortcutRegistry();
+    reg.register({ label: 'A', keys: 'alt+a', action: 'a' });
+    expect(reg.getAll()).toBe(reg.getAll());
+    reg.register({ label: 'B', keys: 'alt+b', action: 'b' });
+    // A new snapshot after a mutation.
+    expect(reg.getAll()).toHaveLength(2);
+  });
+
+  test('subscribe fires on change and unsubscribes', () => {
+    const reg = new ShortcutRegistry();
+    const listener = mock(() => {});
+    const off = reg.subscribe(listener);
+    reg.register({ label: 'A', keys: 'alt+a', action: 'a' });
+    expect(listener).toHaveBeenCalledTimes(1);
+    off();
+    reg.register({ label: 'B', keys: 'alt+b', action: 'b' });
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+});

package/src/core/schema/projection.spec.ts

@@ -0,0 +1,122 @@
+/**
+ * Dynamic Schema Projection (02 §7.2) — the guarantee is that user structure
+ * never becomes DDL, and that a value that will not cast is preserved rather
+ * than dropped.
+ */
+import { describe, expect, it } from 'bun:test';
+import {
+  castValue,
+  mapExternalType,
+  type ProjectedColumn,
+  projectColumn,
+  projectRow,
+  STORAGE_COLUMN,
+} from './projection';
+
+const column = (over: Partial<ProjectedColumn> & Pick<ProjectedColumn, 'colType'>): ProjectedColumn => ({
+  id: 'col_1',
+  name: 'Column',
+  position: 0,
+  ...over,
+});
+
+describe('castValue — typed storage columns', () => {
+  it('lands each type in the column its storage class owns', () => {
+    expect(castValue(column({ colType: 'number' }), '42').row.v_num).toBe(42);
+    expect(castValue(column({ colType: 'text' }), 'hi').row.v_text).toBe('hi');
+    expect(castValue(column({ colType: 'bool' }), 'yes').row.v_bool).toBe(1);
+    expect(castValue(column({ colType: 'date' }), '2026-07-22').row.v_date).toBe('2026-07-22T00:00:00.000Z');
+  });
+
+  it('sorts numerically because numbers live in a numeric column', () => {
+    // The bug this design kills: in a single TEXT column, '10' sorts before '9'.
+    const values = ['10', '9', '100'].map((v) => castValue(column({ colType: 'number' }), v).row.v_num);
+    expect([...values].sort((a, b) => (a ?? 0) - (b ?? 0))).toEqual([9, 10, 100]);
+    expect(STORAGE_COLUMN.number).toBe('v_num');
+  });
+
+  it('preserves an uncastable value as json with a lossy-cast diagnostic', () => {
+    const result = castValue(column({ colType: 'number' }), 'not a number');
+    // Dropping is what silently loses a user's imported data.
+    expect(result.row.v_num).toBeNull();
+    expect(result.row.v_json).toBe('"not a number"');
+    expect(result.diagnostics[0]?.code).toBe('projection-lossy-cast');
+  });
+
+  it('refuses a select value outside its declared choices, keeping the data', () => {
+    const result = castValue(column({ colType: 'select', options: { choices: ['a', 'b'] } }), 'c');
+    expect(result.row.v_text).toBeNull();
+    expect(result.diagnostics[0]?.code).toBe('projection-lossy-cast');
+  });
+
+  it('anchors dates to UTC so the same CSV imports identically in any timezone', () => {
+    expect(castValue(column({ colType: 'date' }), '2026-01-01').row.v_date).toBe('2026-01-01T00:00:00.000Z');
+  });
+
+  it('treats empty and null as absent rather than as a failed cast', () => {
+    for (const empty of [null, undefined, '']) {
+      const result = castValue(column({ colType: 'number' }), empty);
+      expect(result.diagnostics).toEqual([]);
+      expect(result.row.v_num).toBeNull();
+    }
+  });
+});
+
+describe('projectColumn — the unified layout object', () => {
+  it('reads only the slot the declared type owns, ignoring a stale slot', () => {
+    // A leftover value from before the column's type changed must not resurface.
+    const field = projectColumn(column({ colType: 'number' }), {
+      v_text: 'stale',
+      v_num: 7,
+      v_bool: null,
+      v_date: null,
+      v_json: null,
+    });
+    expect(field.value).toBe(7);
+  });
+
+  it('turns SQLite 0/1 into a real boolean', () => {
+    const field = projectColumn(column({ colType: 'bool' }), {
+      v_text: null,
+      v_num: null,
+      v_bool: 0,
+      v_date: null,
+      v_json: null,
+    });
+    expect(field.value).toBe(false);
+  });
+
+  it('surfaces malformed json as raw text rather than throwing', () => {
+    const field = projectColumn(column({ colType: 'json' }), {
+      v_text: null,
+      v_num: null,
+      v_bool: null,
+      v_date: null,
+      v_json: '{ broken',
+    });
+    // One bad cell must not blank an entire table render.
+    expect(field.value).toBe('{ broken');
+    expect(field.json).toBeUndefined();
+  });
+
+  it('projects a whole row in position order', () => {
+    const columns = [
+      column({ id: 'b', colType: 'text', position: 2, name: 'Second' }),
+      column({ id: 'a', colType: 'text', position: 1, name: 'First' }),
+    ];
+    const values = new Map([
+      ['a', { v_text: '1', v_num: null, v_bool: null, v_date: null, v_json: null }],
+      ['b', { v_text: '2', v_num: null, v_bool: null, v_date: null, v_json: null }],
+    ]);
+    expect(projectRow(columns, values).map((f) => f.name)).toEqual(['First', 'Second']);
+  });
+});
+
+describe('mapExternalType', () => {
+  it('maps known external types and falls back to lossless json', () => {
+    expect(mapExternalType('VARCHAR')).toBe('text');
+    expect(mapExternalType('integer')).toBe('number');
+    expect(mapExternalType('timestamp')).toBe('date');
+    expect(mapExternalType('some-vendor-blob')).toBe('json');
+  });
+});

package/src/core/schema/projection.ts

@@ -0,0 +1,225 @@
+/**
+ * Dynamic Schema Projection — the Virtual Schema Adapter (02 §7.2).
+ *
+ * User-defined structure (imported CSVs, external tables, custom columns)
+ * projects through `l_columns` typed metadata (01 §2.1). Components read a
+ * unified layout object and **no user action ever generates DDL**.
+ *
+ * That last rule is the whole design. The obvious implementation — `ALTER TABLE`
+ * per user column — makes every import a schema migration: it needs a write lock
+ * on a live DB, it cannot be rolled back cleanly mid-import, and a tenant with
+ * 300 custom columns produces a 300-column table that no index helps. Projecting
+ * instead means the physical schema is fixed (`l_values` with one typed column
+ * per storage class) and the *logical* schema is data.
+ *
+ * Typed value columns also fix a real SQLite failure: a single `value TEXT`
+ * column holding mixed storage classes sorts `10` before `9`, and a date next to
+ * a number compares by its type tag first. Landing each value in the column
+ * matching its declared type keeps `ORDER BY` single-storage-class correct.
+ */
+
+/** The column types `l_columns.col_type` admits (01 §2.1). */
+export const PROJECTED_COLUMN_TYPES = ['text', 'number', 'bool', 'date', 'select', 'json'] as const;
+export type ProjectedColumnType = (typeof PROJECTED_COLUMN_TYPES)[number];
+
+/** One user-defined column's metadata — a row of `l_columns`. */
+export interface ProjectedColumn {
+  id: string;
+  name: string;
+  colType: ProjectedColumnType;
+  position: number;
+  /** Type-specific options — `select` choices, number precision, date format. */
+  options?: Record<string, unknown>;
+}
+
+/** The physical `l_values` slots. Exactly one is non-null per (row, column). */
+export interface ProjectedValueRow {
+  v_text: string | null;
+  v_num: number | null;
+  v_bool: number | null;
+  v_date: string | null;
+  v_json: string | null;
+}
+
+/** Which physical column a logical type lands in. */
+export const STORAGE_COLUMN: Readonly<Record<ProjectedColumnType, keyof ProjectedValueRow>> = {
+  text: 'v_text',
+  number: 'v_num',
+  bool: 'v_bool',
+  date: 'v_date',
+  // A `select` is a constrained string, so it sorts and indexes as text.
+  select: 'v_text',
+  json: 'v_json',
+};
+
+/** What a component sees — never the physical row. */
+export interface ProjectedField {
+  columnId: string;
+  name: string;
+  type: ProjectedColumnType;
+  value: string | number | boolean | null;
+  /** Parsed `json` payload; undefined for every other type. */
+  json?: unknown;
+}
+
+export interface ProjectionDiagnostic {
+  code: 'projection-lossy-cast';
+  columnId: string;
+  message: string;
+}
+
+/**
+ * Project a stored row into the unified layout object components read.
+ *
+ * Reads only the slot the column's declared type owns. Deliberately: a row whose
+ * `v_text` still holds a value from before a column's type was changed must not
+ * resurface — the declared type is the truth, and a stale slot is stale data.
+ */
+export function projectColumn(column: ProjectedColumn, row: ProjectedValueRow | null): ProjectedField {
+  const base = { columnId: column.id, name: column.name, type: column.colType };
+  if (row === null) return { ...base, value: null };
+
+  switch (column.colType) {
+    case 'number':
+      return { ...base, value: row.v_num };
+    case 'bool':
+      // SQLite has no boolean storage class; 0/1 becomes a real boolean here so
+      // components never write `=== 1`.
+      return { ...base, value: row.v_bool === null ? null : row.v_bool !== 0 };
+    case 'date':
+      return { ...base, value: row.v_date };
+    case 'json': {
+      if (row.v_json === null) return { ...base, value: null };
+      try {
+        return { ...base, value: row.v_json, json: JSON.parse(row.v_json) };
+      } catch {
+        // Malformed JSON surfaces as raw text rather than throwing — one bad
+        // cell must not blank an entire table render.
+        return { ...base, value: row.v_json };
+      }
+    }
+    default:
+      return { ...base, value: row.v_text };
+  }
+}
+
+export interface CastResult {
+  row: ProjectedValueRow;
+  diagnostics: readonly ProjectionDiagnostic[];
+}
+
+const EMPTY_ROW: ProjectedValueRow = { v_text: null, v_num: null, v_bool: null, v_date: null, v_json: null };
+
+/**
+ * Cast an incoming value into the slot its column's type owns.
+ *
+ * A value that cannot be cast is preserved as `json` with a WARNING
+ * `projection-lossy-cast` rather than being dropped. Dropping is the behavior
+ * that loses a user's imported data silently; keeping it means the cell is
+ * visibly wrong and recoverable.
+ */
+export function castValue(column: ProjectedColumn, value: unknown): CastResult {
+  const row: ProjectedValueRow = { ...EMPTY_ROW };
+  const diagnostics: ProjectionDiagnostic[] = [];
+
+  if (value === null || value === undefined || value === '') return { row, diagnostics };
+
+  const lossy = (message: string): void => {
+    diagnostics.push({ code: 'projection-lossy-cast', columnId: column.id, message });
+    row.v_json = JSON.stringify(value);
+  };
+
+  switch (column.colType) {
+    case 'number': {
+      const numeric = typeof value === 'number' ? value : Number(String(value).replace(/[,\s]/g, ''));
+      if (Number.isFinite(numeric)) row.v_num = numeric;
+      else lossy(`'${String(value)}' is not a number; stored as json.`);
+      break;
+    }
+    case 'bool': {
+      const text = String(value).trim().toLowerCase();
+      if (typeof value === 'boolean') row.v_bool = value ? 1 : 0;
+      else if (['true', 'yes', 'y', '1'].includes(text)) row.v_bool = 1;
+      else if (['false', 'no', 'n', '0'].includes(text)) row.v_bool = 0;
+      else lossy(`'${String(value)}' is not a boolean; stored as json.`);
+      break;
+    }
+    case 'date': {
+      const iso = toIsoDate(value);
+      if (iso !== null) row.v_date = iso;
+      else lossy(`'${String(value)}' is not a recognizable date; stored as json.`);
+      break;
+    }
+    case 'select': {
+      const choices = Array.isArray(column.options?.choices) ? (column.options.choices as unknown[]) : null;
+      const text = String(value);
+      if (choices === null || choices.map(String).includes(text)) row.v_text = text;
+      else lossy(`'${text}' is not one of the declared choices; stored as json.`);
+      break;
+    }
+    case 'json':
+      row.v_json = typeof value === 'string' ? value : JSON.stringify(value);
+      break;
+    default:
+      row.v_text = typeof value === 'string' ? value : String(value);
+  }
+
+  return { row, diagnostics };
+}
+
+/**
+ * ISO-8601 date, or null. Anchored to UTC so the same CSV imported in two
+ * timezones produces the same stored day — the off-by-one-day class of import
+ * bug.
+ */
+function toIsoDate(value: unknown): string | null {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value.toISOString();
+  const text = String(value).trim();
+  if (/^\d{4}-\d{2}-\d{2}$/.test(text)) return `${text}T00:00:00.000Z`;
+  const parsed = Date.parse(text);
+  return Number.isNaN(parsed) ? null : new Date(parsed).toISOString();
+}
+
+/**
+ * Map an external field type (CSV sniff, sheet cell type, API schema) onto a
+ * projected column type. Anything unrecognized becomes `json` — the lossless
+ * default, per 02 §7.2.
+ */
+export function mapExternalType(externalType: string): ProjectedColumnType {
+  switch (externalType.toLowerCase()) {
+    case 'string':
+    case 'text':
+    case 'varchar':
+      return 'text';
+    case 'number':
+    case 'numeric':
+    case 'int':
+    case 'integer':
+    case 'float':
+    case 'double':
+    case 'decimal':
+      return 'number';
+    case 'bool':
+    case 'boolean':
+      return 'bool';
+    case 'date':
+    case 'datetime':
+    case 'timestamp':
+      return 'date';
+    case 'enum':
+    case 'select':
+      return 'select';
+    default:
+      return 'json';
+  }
+}
+
+/** Project a whole row: every declared column, in `position` order. */
+export function projectRow(
+  columns: readonly ProjectedColumn[],
+  values: ReadonlyMap<string, ProjectedValueRow>,
+): readonly ProjectedField[] {
+  return [...columns]
+    .sort((a, b) => a.position - b.position)
+    .map((column) => projectColumn(column, values.get(column.id) ?? null));
+}