@vellumai/assistant 0.3.4 → 0.3.6

package/src/util/platform.ts

@@ -1,18 +1,14 @@
-import { mkdirSync, existsSync, statSync, unlinkSync, renameSync, readFileSync, writeFileSync, readdirSync, chmodSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { mkdirSync, existsSync, statSync, unlinkSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
 import { homedir } from 'node:os';
-/**
- * Stderr-only logger for migration code. Using the pino logger during
- * migration is unsafe because pino initialization calls ensureDataDir(),
- * which pre-creates workspace destination directories and causes migration
- * moves to no-op.
- */
-function migrationLog(level: 'info' | 'warn' | 'debug', msg: string, data?: Record<string, unknown>): void {
-  if (level === 'debug') return; // suppress debug-level migration noise
-  const prefix = level === 'warn' ? 'WARN' : 'INFO';
-  const extra = data ? ' ' + JSON.stringify(data) : '';
-  process.stderr.write(`[migration] ${prefix}: ${msg}${extra}\n`);
-}
+import {
+  getBaseDataDir,
+  getDaemonSocket,
+  getDaemonTcpPort,
+  getDaemonTcpEnabled,
+  getDaemonTcpHost,
+  getDaemonIosPairing,
+} from '../config/env-registry.js';
 
 export function isMacOS(): boolean {
   return process.platform === 'darwin';
@@ -45,12 +41,75 @@ export function getClipboardCommand(): string | null {
   return null;
 }
 
+/**
+ * Read and parse the lockfile, trying the primary path (~/.vellum.lock.json)
+ * first, then falling back to the legacy path (~/.vellum.lockfile.json).
+ * Respects BASE_DATA_DIR for non-standard home directories.
+ * Returns null if neither file exists or both are malformed.
+ */
+export function readLockfile(): Record<string, unknown> | null {
+  const base = getBaseDataDir() || homedir();
+  const candidates = [
+    join(base, '.vellum.lock.json'),
+    join(base, '.vellum.lockfile.json'),
+  ];
+  for (const lockPath of candidates) {
+    if (!existsSync(lockPath)) continue;
+    try {
+      const raw = JSON.parse(readFileSync(lockPath, 'utf-8'));
+      if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        return raw as Record<string, unknown>;
+      }
+    } catch {
+      // malformed JSON — try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Normalize an assistant ID to its canonical form for DB operations.
+ *
+ * The system uses "self" as the canonical single-tenant identifier
+ * (see migration 007-assistant-id-to-self). However, the desktop UI
+ * sends the real assistant ID (e.g., "vellum-true-eel") while the
+ * inbound call path resolves phone numbers to config keys (typically
+ * "self"). This function maps any known lockfile assistant ID to "self"
+ * so both sides use a consistent DB key.
+ */
+export function normalizeAssistantId(assistantId: string): string {
+  if (assistantId === 'self') return 'self';
+
+  try {
+    const lockData = readLockfile();
+    const assistants = lockData?.assistants as Array<Record<string, unknown>> | undefined;
+    if (assistants) {
+      for (const entry of assistants) {
+        if (entry.assistantId === assistantId) return 'self';
+      }
+    }
+  } catch {
+    // lockfile unreadable — return as-is
+  }
+
+  return assistantId;
+}
+
+/**
+ * Write data to the primary lockfile (~/.vellum.lock.json).
+ * Respects BASE_DATA_DIR for non-standard home directories.
+ */
+export function writeLockfile(data: Record<string, unknown>): void {
+  const base = getBaseDataDir() || homedir();
+  writeFileSync(join(base, '.vellum.lock.json'), JSON.stringify(data, null, 2) + '\n');
+}
+
 /**
  * Returns the root ~/.vellum directory. User-facing files (config, prompt
  * files, skills) and runtime files (socket, PID) live here.
  */
 export function getRootDir(): string {
-  return join(process.env.BASE_DATA_DIR?.trim() || homedir(), '.vellum');
+  return join(getBaseDataDir() || homedir(), '.vellum');
 }
 
 /**
@@ -91,7 +150,7 @@ export function getInterfacesDir(): string {
 }
 
 export function getSocketPath(): string {
-  const override = process.env.VELLUM_DAEMON_SOCKET?.trim();
+  const override = getDaemonSocket();
   if (override) {
     return expandHomePath(override);
   }
@@ -107,12 +166,7 @@ export function getSessionTokenPath(): string {
  * Reads VELLUM_DAEMON_TCP_PORT env var; defaults to 8765.
  */
 export function getTCPPort(): number {
-  const override = process.env.VELLUM_DAEMON_TCP_PORT?.trim();
-  if (override) {
-    const port = parseInt(override, 10);
-    if (!isNaN(port) && port > 0 && port <= 65535) return port;
-  }
-  return 8765;
+  return getDaemonTcpPort();
 }
 
 /**
@@ -127,9 +181,8 @@ export function getTCPPort(): number {
  * The macOS CLI (AssistantCli) also sets the env var for bundled-binary deployments.
  */
 export function isTCPEnabled(): boolean {
-  const override = process.env.VELLUM_DAEMON_TCP_ENABLED?.trim();
-  if (override === 'true' || override === '1') return true;
-  if (override === 'false' || override === '0') return false;
+  const envValue = getDaemonTcpEnabled();
+  if (envValue !== undefined) return envValue;
   return existsSync(join(getRootDir(), 'tcp-enabled'));
 }
 
@@ -141,7 +194,7 @@ export function isTCPEnabled(): boolean {
  *   3. Default: '127.0.0.1' (localhost only)
  */
 export function getTCPHost(): string {
-  const override = process.env.VELLUM_DAEMON_TCP_HOST?.trim();
+  const override = getDaemonTcpHost();
   if (override) return override;
   if (isIOSPairingEnabled()) return '0.0.0.0';
   return '127.0.0.1';
@@ -162,9 +215,8 @@ export function getTCPHost(): string {
  * access without exposing the daemon to the LAN.
  */
 export function isIOSPairingEnabled(): boolean {
-  const override = process.env.VELLUM_DAEMON_IOS_PAIRING?.trim();
-  if (override === 'true' || override === '1') return true;
-  if (override === 'false' || override === '0') return false;
+  const envValue = getDaemonIosPairing();
+  if (envValue !== undefined) return envValue;
   return existsSync(join(getRootDir(), 'ios-pairing-enabled'));
 }
 
@@ -172,6 +224,27 @@ export function getHttpTokenPath(): string {
   return join(getRootDir(), 'http-token');
 }
 
+/**
+ * Returns the path to the platform API token file (~/.vellum/platform-token).
+ * This token is the X-Session-Token used to authenticate with the Vellum
+ * Platform API (e.g. assistant.vellum.ai).
+ */
+export function getPlatformTokenPath(): string {
+  return join(getRootDir(), 'platform-token');
+}
+
+/**
+ * Read the platform API token from disk. Returns null if the file
+ * doesn't exist or can't be read.
+ */
+export function readPlatformToken(): string | null {
+  try {
+    return readFileSync(getPlatformTokenPath(), 'utf-8').trim();
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Read the daemon session token from disk. Returns null if the file
  * doesn't exist or can't be read (daemon not running).
@@ -267,276 +340,9 @@ export function getWorkspacePromptPath(file: string): string {
   return join(getWorkspaceDir(), file);
 }
 
-/**
- * Idempotent move: relocates source to destination for migration.
- * - No-op if source is missing (already migrated or never existed).
- * - No-op if destination already exists (avoids clobbering).
- * - Creates destination parent directories as needed.
- * - Logs warning on failure instead of throwing.
- *
- * Exported for testing; not intended for general use outside migrations.
- */
-export function migratePath(source: string, destination: string): void {
-  if (!existsSync(source)) return;
-  if (existsSync(destination)) {
-    migrationLog('debug', 'Migration skipped: destination already exists', { source, destination });
-    return;
-  }
-  try {
-    const destDir = dirname(destination);
-    if (!existsSync(destDir)) {
-      mkdirSync(destDir, { recursive: true });
-    }
-    renameSync(source, destination);
-    migrationLog('info', 'Migrated path', { from: source, to: destination });
-  } catch (err) {
-    migrationLog('warn', 'Failed to migrate path', { err: String(err), from: source, to: destination });
-  }
-}
-
-/**
- * When migratePath skips config.json because the workspace copy already
- * exists, the legacy root config may still contain keys (e.g. slackWebhookUrl)
- * that were never written to the workspace config. This merges any missing
- * top-level keys from the legacy file into the workspace file so they are
- * not silently lost during upgrade.
- */
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return v !== null && typeof v === 'object' && !Array.isArray(v);
-}
-
-function mergeSkippedConfigKeys(legacyPath: string, workspacePath: string): void {
-  if (!existsSync(legacyPath) || !existsSync(workspacePath)) return;
-
-  let legacy: Record<string, unknown>;
-  let workspace: Record<string, unknown>;
-  try {
-    const legacyRaw = JSON.parse(readFileSync(legacyPath, 'utf-8'));
-    const workspaceRaw = JSON.parse(readFileSync(workspacePath, 'utf-8'));
-    if (!isPlainObject(legacyRaw) || !isPlainObject(workspaceRaw)) return;
-    legacy = legacyRaw;
-    workspace = workspaceRaw;
-  } catch {
-    return; // malformed JSON — skip silently
-  }
-
-  const merged: string[] = [];
-  for (const key of Object.keys(legacy)) {
-    if (!(key in workspace)) {
-      workspace[key] = legacy[key];
-      merged.push(key);
-    }
-  }
-
-  if (merged.length > 0) {
-    try {
-      writeFileSync(workspacePath, JSON.stringify(workspace, null, 2) + '\n');
-      // Remove merged keys from legacy config so they are not resurrected
-      // if a user later deletes them from the workspace config.
-      for (const key of merged) {
-        delete legacy[key];
-      }
-      if (Object.keys(legacy).length === 0) {
-        unlinkSync(legacyPath);
-      } else {
-        writeFileSync(legacyPath, JSON.stringify(legacy, null, 2) + '\n');
-      }
-      migrationLog('info', 'Merged legacy config keys into workspace config', { keys: merged });
-    } catch (err) {
-      migrationLog('warn', 'Failed to merge legacy config keys', { err: String(err), keys: merged });
-    }
-  }
-}
-
-/**
- * When migratePath skips the hooks directory because the workspace copy
- * already exists (e.g. pre-created by ensureDataDir), the legacy hooks
- * directory may still contain individual hook files/subdirectories that
- * were never moved. This merges any missing entries from the legacy
- * path into the workspace hooks path so they are not silently lost.
- */
-function mergeLegacyHooks(legacyDir: string, workspaceDir: string): void {
-  if (!existsSync(legacyDir) || !existsSync(workspaceDir)) return;
-
-  let entries: import('node:fs').Dirent[];
-  try {
-    entries = readdirSync(legacyDir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-
-  for (const entry of entries) {
-    const src = join(legacyDir, entry.name);
-    const dest = join(workspaceDir, entry.name);
-    if (existsSync(dest)) {
-      // config.json needs a merge rather than a skip — the legacy file may
-      // contain hook enabled/settings entries that the workspace copy lacks.
-      if (entry.name === 'config.json') {
-        mergeHooksConfig(src, dest);
-      }
-      continue;
-    }
-    try {
-      renameSync(src, dest);
-      migrationLog('info', 'Merged legacy hook into workspace', { from: src, to: dest });
-    } catch (err) {
-      migrationLog('warn', 'Failed to merge legacy hook', { err: String(err), from: src, to: dest });
-    }
-  }
-}
-
-/**
- * Merge missing hook entries from a legacy hooks/config.json into the
- * workspace hooks/config.json. Only adds hooks that don't already exist
- * in the workspace config so user changes are never overwritten.
- */
-function mergeHooksConfig(legacyPath: string, workspacePath: string): void {
-  let legacy: Record<string, unknown>;
-  let workspace: Record<string, unknown>;
-  try {
-    const legacyRaw = JSON.parse(readFileSync(legacyPath, 'utf-8'));
-    const workspaceRaw = JSON.parse(readFileSync(workspacePath, 'utf-8'));
-    if (!isPlainObject(legacyRaw) || !isPlainObject(workspaceRaw)) return;
-    legacy = legacyRaw;
-    workspace = workspaceRaw;
-  } catch {
-    return;
-  }
-
-  const legacyHooks = legacy.hooks;
-  const wsHooks = workspace.hooks;
-  if (!isPlainObject(legacyHooks) || !isPlainObject(wsHooks)) return;
-
-  const merged: string[] = [];
-  for (const hookName of Object.keys(legacyHooks)) {
-    if (!(hookName in wsHooks)) {
-      wsHooks[hookName] = legacyHooks[hookName];
-      merged.push(hookName);
-    }
-  }
-
-  if (merged.length > 0) {
-    try {
-      writeFileSync(workspacePath, JSON.stringify(workspace, null, 2) + '\n');
-      // Remove merged hooks from legacy config to prevent resurrection
-      for (const hookName of merged) {
-        delete legacyHooks[hookName];
-      }
-      if (Object.keys(legacyHooks).length === 0) {
-        unlinkSync(legacyPath);
-      } else {
-        writeFileSync(legacyPath, JSON.stringify(legacy, null, 2) + '\n');
-      }
-      migrationLog('info', 'Merged legacy hooks config entries into workspace', { hooks: merged });
-    } catch (err) {
-      migrationLog('warn', 'Failed to merge legacy hooks config', { err: String(err), hooks: merged });
-    }
-  }
-}
-
-/**
- * When migratePath skips the skills directory because the workspace copy
- * already exists (e.g. pre-created by ensureDataDir), the legacy skills
- * directory may still contain individual skill subdirectories that were
- * never moved. This merges any missing skill subdirectories from the
- * legacy path into the workspace skills path so they are not stranded.
- */
-function mergeLegacySkills(legacyDir: string, workspaceDir: string): void {
-  if (!existsSync(legacyDir) || !existsSync(workspaceDir)) return;
-
-  let entries: import('node:fs').Dirent[];
-  try {
-    entries = readdirSync(legacyDir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-
-  for (const entry of entries) {
-    const src = join(legacyDir, entry.name);
-    const dest = join(workspaceDir, entry.name);
-    if (existsSync(dest)) continue; // already present in workspace
-    try {
-      renameSync(src, dest);
-      migrationLog('info', 'Merged legacy skill into workspace', { from: src, to: dest });
-    } catch (err) {
-      migrationLog('warn', 'Failed to merge legacy skill', { err: String(err), from: src, to: dest });
-    }
-  }
-}
-
-/**
- * When migratePath skips the data directory because workspace/data already
- * exists (e.g. the user's project had a data/ folder that was extracted from
- * sandbox/fs), the legacy data directory may still contain internal state
- * subdirectories (db/, logs/, sandbox/, etc.) that need to be preserved.
- * This merges any missing entries from the legacy data path into workspace/data.
- */
-function mergeLegacyDataEntries(legacyDir: string, workspaceDir: string): void {
-  if (!existsSync(legacyDir) || !existsSync(workspaceDir)) return;
-
-  let entries: import('node:fs').Dirent[];
-  try {
-    entries = readdirSync(legacyDir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-
-  for (const entry of entries) {
-    const src = join(legacyDir, entry.name);
-    const dest = join(workspaceDir, entry.name);
-    if (existsSync(dest)) continue; // already present in workspace
-    try {
-      renameSync(src, dest);
-      migrationLog('info', 'Merged legacy data entry into workspace', { from: src, to: dest });
-    } catch (err) {
-      migrationLog('warn', 'Failed to merge legacy data entry', { err: String(err), from: src, to: dest });
-    }
-  }
-}
-
-/**
- * Migrate from the flat ~/.vellum layout to the workspace-based layout.
- *
- * Step (a) is special: if the workspace dir doesn't exist yet but the old
- * sandbox working dir (data/sandbox/fs) does, its contents are "extracted"
- * to become the new workspace root via rename. All subsequent moves then
- * land inside that workspace directory.
- *
- * Idempotent: safe to call on every startup — already-migrated items are
- * skipped, and a second run is a no-op.
- */
-export function migrateToWorkspaceLayout(): void {
-  const root = getRootDir();
-  if (!existsSync(root)) return;
-
-  const ws = getWorkspaceDir();
-
-  // (a) Extract data/sandbox/fs -> workspace (only when workspace doesn't exist yet)
-  if (!existsSync(ws)) {
-    const sandboxFs = join(root, 'data', 'sandbox', 'fs');
-    if (existsSync(sandboxFs)) {
-      try {
-        renameSync(sandboxFs, ws);
-        migrationLog('info', 'Extracted sandbox/fs as workspace root', { from: sandboxFs, to: ws });
-      } catch (err) {
-        migrationLog('warn', 'Failed to extract sandbox/fs', { err: String(err), from: sandboxFs, to: ws });
-      }
-    }
-  }
-
-  // (b)-(h) Move legacy root-level items into workspace
-  migratePath(join(root, 'config.json'), join(ws, 'config.json'));
-  mergeSkippedConfigKeys(join(root, 'config.json'), join(ws, 'config.json'));
-  migratePath(join(root, 'data'), join(ws, 'data'));
-  mergeLegacyDataEntries(join(root, 'data'), join(ws, 'data'));
-  migratePath(join(root, 'hooks'), join(ws, 'hooks'));
-  mergeLegacyHooks(join(root, 'hooks'), join(ws, 'hooks'));
-  migratePath(join(root, 'IDENTITY.md'), join(ws, 'IDENTITY.md'));
-  migratePath(join(root, 'skills'), join(ws, 'skills'));
-  mergeLegacySkills(join(root, 'skills'), join(ws, 'skills'));
-  migratePath(join(root, 'SOUL.md'), join(ws, 'SOUL.md'));
-  migratePath(join(root, 'USER.md'), join(ws, 'USER.md'));
-}
+// Re-export migration functions so existing consumers don't break.
+export { migratePath, migrateToWorkspaceLayout } from '../migrations/workspace-layout.js';
+export { migrateToDataLayout } from '../migrations/data-layout.js';
 
 export function ensureDataDir(): void {
   const root = getRootDir();
@@ -573,67 +379,3 @@ export function ensureDataDir(): void {
     // Non-fatal: some filesystems don't support Unix permissions
   }
 }
-
-/**
- * Migrate files from the old flat ~/.vellum layout to the new structured
- * layout with data/ and protected/ subdirectories.
- *
- * Idempotent: skips items that have already been migrated.
- * Uses renameSync for atomic moves (same filesystem).
- */
-export function migrateToDataLayout(): void {
-  const root = getRootDir();
-  const data = join(root, 'data');
-
-  if (!existsSync(root)) return;
-
-  function migrateItem(oldPath: string, newPath: string): void {
-    if (!existsSync(oldPath)) return;
-    if (existsSync(newPath)) return;
-    try {
-      const newDir = dirname(newPath);
-      if (!existsSync(newDir)) {
-        mkdirSync(newDir, { recursive: true });
-      }
-      renameSync(oldPath, newPath);
-      migrationLog('info', 'Migrated path', { from: oldPath, to: newPath });
-    } catch (err) {
-      migrationLog('warn', 'Failed to migrate path', { err: String(err), from: oldPath, to: newPath });
-    }
-  }
-
-  // DB: ~/.vellum/data/assistant.db → ~/.vellum/data/db/assistant.db
-  migrateItem(join(data, 'assistant.db'), join(data, 'db', 'assistant.db'));
-  migrateItem(join(data, 'assistant.db-wal'), join(data, 'db', 'assistant.db-wal'));
-  migrateItem(join(data, 'assistant.db-shm'), join(data, 'db', 'assistant.db-shm'));
-
-  // Qdrant PID: ~/.vellum/qdrant.pid → ~/.vellum/data/qdrant/qdrant.pid
-  migrateItem(join(root, 'qdrant.pid'), join(data, 'qdrant', 'qdrant.pid'));
-
-  // Qdrant binary: ~/.vellum/bin/ → ~/.vellum/data/qdrant/bin/
-  migrateItem(join(root, 'bin'), join(data, 'qdrant', 'bin'));
-
-  // Logs: ~/.vellum/logs/ → ~/.vellum/data/logs/
-  migrateItem(join(root, 'logs'), join(data, 'logs'));
-
-  // Memory: ~/.vellum/memory/ → ~/.vellum/data/memory/
-  migrateItem(join(root, 'memory'), join(data, 'memory'));
-
-  // Apps: ~/.vellum/apps/ → ~/.vellum/data/apps/
-  migrateItem(join(root, 'apps'), join(data, 'apps'));
-
-  // Browser auth: ~/.vellum/browser-auth/ → ~/.vellum/data/browser-auth/
-  migrateItem(join(root, 'browser-auth'), join(data, 'browser-auth'));
-
-  // Browser profile: ~/.vellum/browser-profile/ → ~/.vellum/data/browser-profile/
-  migrateItem(join(root, 'browser-profile'), join(data, 'browser-profile'));
-
-  // History: ~/.vellum/history → ~/.vellum/data/history
-  migrateItem(join(root, 'history'), join(data, 'history'));
-
-  // Protected files: ~/.vellum/X → ~/.vellum/protected/X
-  const protectedDir = join(root, 'protected');
-  migrateItem(join(root, 'trust.json'), join(protectedDir, 'trust.json'));
-  migrateItem(join(root, 'keys.enc'), join(protectedDir, 'keys.enc'));
-  migrateItem(join(root, 'secret-allowlist.json'), join(protectedDir, 'secret-allowlist.json'));
-}

package/src/util/pricing.ts

@@ -143,7 +143,7 @@ export function estimateCost(
   provider: string,
 ): number {
   const result = resolvePricing(provider, model, inputTokens, outputTokens);
-  if (result.pricingStatus === 'priced' && result.estimatedCostUsd !== null) {
+  if (result.pricingStatus === 'priced' && result.estimatedCostUsd != null) {
     return result.estimatedCostUsd;
   }
   return 0;

package/src/util/promise-guard.ts

@@ -8,7 +8,7 @@ export class PromiseGuard<T> {
 
   /** Whether a promise is currently in-flight. */
   get active(): boolean {
-    return this.promise !== null;
+    return this.promise != null;
   }
 
   /**

package/src/util/retry.ts

@@ -95,4 +95,23 @@ export function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * Like `sleep` but resolves early when an AbortSignal fires.
+ * Resolves (not rejects) on abort so callers can check the signal
+ * themselves and decide what to do.
+ */
+export function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (!signal) return sleep(ms);
+  if (signal.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(onDone, ms);
+    signal.addEventListener('abort', onDone, { once: true });
+    function onDone() {
+      clearTimeout(timer);
+      signal!.removeEventListener('abort', onDone);
+      resolve();
+    }
+  });
+}
+
 export { DEFAULT_MAX_RETRIES, DEFAULT_BASE_DELAY_MS };

package/src/util/row-mapper.ts

@@ -0,0 +1,79 @@
+/**
+ * Generic DB row mapper — replaces repetitive parse* functions across store files.
+ *
+ * Each field in the schema is described by either a source column name (passthrough)
+ * or a transform descriptor. The mapper produces a function that converts a raw
+ * Drizzle row into a typed domain object.
+ */
+
+// A field descriptor is either a key of the source row (passthrough) or a transform.
+type FieldDescriptor<TRow, TOut> =
+  | (keyof TRow & string)
+  | { from: keyof TRow & string; transform: (value: TRow[keyof TRow]) => TOut };
+
+// The schema maps each output field to a field descriptor.
+type MapperSchema<TRow, TDomain> = {
+  [K in keyof TDomain]: FieldDescriptor<TRow, TDomain[K]>;
+};
+
+/**
+ * Create a row-to-domain mapper from a declarative schema.
+ *
+ * Usage:
+ * ```ts
+ * const parseReminder = createRowMapper<typeof reminders.$inferSelect, ReminderRow>({
+ *   id: 'id',
+ *   label: 'label',
+ *   mode: { from: 'mode', transform: (v) => v as ReminderRow['mode'] },
+ * });
+ * ```
+ */
+export function createRowMapper<TRow, TDomain>(
+  schema: MapperSchema<TRow, TDomain>,
+): (row: TRow) => TDomain {
+  const entries = Object.entries(schema) as Array<
+    [string, FieldDescriptor<TRow, unknown>]
+  >;
+
+  return (row: TRow): TDomain => {
+    const result = {} as Record<string, unknown>;
+    for (const [key, descriptor] of entries) {
+      if (typeof descriptor === 'string') {
+        result[key] = row[descriptor as keyof TRow];
+      } else {
+        const d = descriptor as { from: keyof TRow & string; transform: (value: TRow[keyof TRow]) => unknown };
+        result[key] = d.transform(row[d.from]);
+      }
+    }
+    return result as TDomain;
+  };
+}
+
+/** Convenience: cast a value to a narrower type (for string union columns). */
+export function cast<T>() {
+  return (value: unknown) => value as T;
+}
+
+/** Convenience: parse a JSON string column with a fallback value on parse failure. */
+export function parseJson<T>(fallback: T): (value: unknown) => T {
+  return (value: unknown): T => {
+    if (typeof value !== 'string' || !value) return fallback;
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      return fallback;
+    }
+  };
+}
+
+/** Convenience: parse a JSON string column, returning null on parse failure. */
+export function parseJsonNullable<T>(): (value: unknown) => T | null {
+  return (value: unknown): T | null => {
+    if (typeof value !== 'string' || !value) return null;
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      return null;
+    }
+  };
+}

package/src/util/silently.ts

@@ -0,0 +1,21 @@
+import { getLogger } from './logger.js';
+
+const log = getLogger('silently');
+
+/**
+ * Attaches a `.catch()` to `promise` that emits a debug-level log instead of
+ * swallowing the rejection completely.  Use this in place of bare
+ * `.catch(() => {})` when you need fire-and-forget semantics but still want
+ * visibility into unexpected errors during debugging.
+ *
+ * The original promise is returned unchanged so callers can still chain it.
+ *
+ * @example
+ *   silentlyWithLog(stopSession(id), 'idle session cleanup');
+ */
+export function silentlyWithLog<T>(promise: Promise<T>, context: string): Promise<T> {
+  promise.catch((err: unknown) => {
+    log.debug({ err, context }, 'Suppressed async error');
+  });
+  return promise;
+}