@vellumai/assistant 0.3.28 → 0.4.1

package/src/memory/embedding-runtime-manager.ts

@@ -0,0 +1,471 @@
+/**
+ * Downloads and manages the local embedding runtime post-hatch.
+ *
+ * Instead of shipping heavy native + JS dependencies inside the .app bundle,
+ * we download them from npm and run embeddings in a **separate bun process**.
+ * The compiled daemon binary cannot resolve bare specifiers in dynamically
+ * imported files, so we spawn a standalone bun process that runs an embed
+ * worker script communicating via JSON-lines over stdin/stdout.
+ *
+ * The runtime is stored in ~/.vellum/workspace/embedding-models/ and used
+ * by embedding-local.ts on demand.
+ *
+ * Follows the same download/install pattern as qdrant-manager.ts.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { arch, platform } from 'node:os';
+import { join } from 'node:path';
+
+import { getLogger } from '../util/logger.js';
+import { getEmbeddingModelsDir } from '../util/platform.js';
+import { PromiseGuard } from '../util/promise-guard.js';
+
+const log = getLogger('embedding-runtime-manager');
+
+// Pinned versions matching assistant/bun.lock
+const ONNXRUNTIME_NODE_VERSION = '1.21.0';
+const ONNXRUNTIME_COMMON_VERSION = '1.21.0';
+const TRANSFORMERS_VERSION = '3.8.1';
+
+/** Bun version to download when system bun is not available. */
+const BUN_VERSION = '1.2.0';
+
+/** Composite version string for cache invalidation. */
+const RUNTIME_VERSION = `ort-${ONNXRUNTIME_NODE_VERSION}_hf-${TRANSFORMERS_VERSION}`;
+
+const WORKER_FILENAME = 'embed-worker.mjs';
+
+/** Module-level guard so concurrent in-process calls share one download. */
+const installGuard = new PromiseGuard<void>();
+
+interface VersionManifest {
+  runtimeVersion: string;
+  onnxruntimeNodeVersion: string;
+  onnxruntimeCommonVersion: string;
+  transformersVersion: string;
+  platform: string;
+  arch: string;
+  installedAt: string;
+}
+
+// ── npm tarball helpers ─────────────────────────────────────────────
+
+function npmTarballUrl(pkg: string, version: string): string {
+  // Scoped packages encode the scope in the URL
+  const encoded = pkg.replace('/', '%2f');
+  const basename = pkg.startsWith('@') ? pkg.split('/')[1] : pkg;
+  return `https://registry.npmjs.org/${encoded}/-/${basename}-${version}.tgz`;
+}
+
+async function downloadAndExtract(
+  url: string,
+  targetDir: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  log.info({ url, targetDir }, 'Downloading npm package');
+
+  const response = await fetch(url, { signal });
+  if (!response.ok) {
+    throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
+  }
+
+  const tarball = await response.arrayBuffer();
+
+  // npm tarballs extract to package/, we need to redirect to targetDir
+  mkdirSync(targetDir, { recursive: true });
+
+  const tmpTar = join(targetDir, `download-${Date.now()}.tgz`);
+  writeFileSync(tmpTar, Buffer.from(tarball));
+
+  try {
+    // Extract tarball, stripping the leading "package/" directory
+    const proc = Bun.spawn({
+      cmd: ['tar', 'xzf', tmpTar, '-C', targetDir, '--strip-components=1'],
+      stdout: 'ignore',
+      stderr: 'pipe',
+    });
+    await proc.exited;
+    if (proc.exitCode !== 0) {
+      const stderr = await new Response(proc.stderr).text();
+      throw new Error(`Failed to extract ${url}: ${stderr}`);
+    }
+  } finally {
+    try { rmSync(tmpTar); } catch { /* ignore */ }
+  }
+}
+
+// ── Worker script content ───────────────────────────────────────────
+
+function generateWorkerScript(): string {
+  // This script is run by a standalone bun process (not the compiled daemon).
+  // Because it runs in a real bun runtime, bare specifier resolution works
+  // normally — node_modules/ in the same directory is found automatically.
+  return `\
+// embed-worker.mjs — Auto-generated by EmbeddingRuntimeManager
+// Runs in a separate bun process, communicates via JSON-lines over stdin/stdout.
+import { pipeline, env } from '@huggingface/transformers';
+
+const model = process.argv[2];
+const cacheDir = process.argv[3];
+if (cacheDir && env) env.cacheDir = cacheDir;
+
+let extractor;
+try {
+  extractor = await pipeline('feature-extraction', model, { dtype: 'fp32' });
+  process.stdout.write(JSON.stringify({ type: 'ready' }) + '\\n');
+} catch (err) {
+  process.stdout.write(JSON.stringify({ type: 'error', error: err.message || String(err) }) + '\\n');
+  process.exit(1);
+}
+
+// Sequential request queue to avoid concurrent ONNX inference
+const decoder = new TextDecoder();
+let buffer = '';
+let processing = false;
+const queue = [];
+
+process.stdin.on('data', (chunk) => {
+  buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+  let idx;
+  while ((idx = buffer.indexOf('\\n')) !== -1) {
+    const line = buffer.slice(0, idx);
+    buffer = buffer.slice(idx + 1);
+    if (line.trim()) queue.push(line);
+  }
+  if (!processing) processQueue();
+});
+
+async function processQueue() {
+  processing = true;
+  while (queue.length > 0) {
+    const line = queue.shift();
+    let req;
+    try { req = JSON.parse(line); } catch { continue; }
+    try {
+      const output = await extractor(req.texts, { pooling: 'cls', normalize: true });
+      const vectors = output.tolist();
+      process.stdout.write(JSON.stringify({ id: req.id, vectors }) + '\\n');
+    } catch (err) {
+      process.stdout.write(JSON.stringify({ id: req.id, error: err.message || String(err) }) + '\\n');
+    }
+  }
+  processing = false;
+}
+
+process.stdin.on('end', () => process.exit(0));
+`;
+}
+
+// ── Main manager ────────────────────────────────────────────────────
+
+export class EmbeddingRuntimeManager {
+  private readonly baseDir: string;
+
+  constructor(baseDir?: string) {
+    this.baseDir = baseDir ?? getEmbeddingModelsDir();
+  }
+
+  /** Check if the embedding runtime is installed and up-to-date. */
+  isReady(): boolean {
+    const manifest = this.readManifest();
+    if (!manifest) return false;
+    if (manifest.runtimeVersion !== RUNTIME_VERSION) return false;
+
+    // Verify the worker script exists and a bun binary is available
+    return existsSync(this.getWorkerPath()) && this.getBunPath() !== undefined;
+  }
+
+  /** Path to the embed worker script. */
+  getWorkerPath(): string {
+    return join(this.baseDir, WORKER_FILENAME);
+  }
+
+  /**
+   * Find a usable bun binary.
+   * Checks: downloaded copy → common install locations.
+   */
+  getBunPath(): string | undefined {
+    // 1. Downloaded bun
+    const downloadedBun = join(this.baseDir, 'bin', 'bun');
+    if (existsSync(downloadedBun)) return downloadedBun;
+
+    // 2. Common installation paths — the compiled daemon inherits a
+    //    restricted PATH, so we check well-known prefixes directly.
+    const home = process.env.HOME ?? '';
+    for (const p of [
+      join(home, '.bun', 'bin', 'bun'),
+      '/opt/homebrew/bin/bun',
+      '/usr/local/bin/bun',
+    ]) {
+      if (existsSync(p)) return p;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Download and install the embedding runtime if not already present.
+   * Safe to call concurrently — in-process calls share one promise via
+   * PromiseGuard, and cross-process calls are serialized via a lock file.
+   */
+  async ensureInstalled(signal?: AbortSignal): Promise<void> {
+    if (this.isReady()) return;
+
+    // Deduplicate concurrent in-process calls
+    await installGuard.run(() => this.acquireLockAndInstall(signal));
+
+    // If another process was downloading and we skipped, or if the download
+    // somehow failed silently, reset the guard so we can retry next time.
+    if (!this.isReady()) {
+      installGuard.reset();
+    }
+  }
+
+  private async acquireLockAndInstall(signal?: AbortSignal): Promise<void> {
+    // Re-check after acquiring the in-process guard
+    if (this.isReady()) return;
+
+    // Cross-process lock to prevent duplicate downloads
+    const lockPath = join(this.baseDir, '.downloading');
+    if (existsSync(lockPath)) {
+      try {
+        const lockContent = readFileSync(lockPath, 'utf-8').trim();
+        const lockPid = parseInt(lockContent, 10);
+        if (!isNaN(lockPid) && lockPid !== process.pid) {
+          try {
+            process.kill(lockPid, 0);
+            log.info({ lockPid }, 'Another process is downloading the embedding runtime, skipping');
+            return;
+          } catch {
+            log.info({ lockPid }, 'Cleaning up stale download lock');
+          }
+        }
+      } catch {
+        // Can't read lock file, proceed
+      }
+    }
+
+    mkdirSync(this.baseDir, { recursive: true });
+
+    // Write a .gitignore so the workspace git repo ignores this directory
+    const gitignorePath = join(this.baseDir, '.gitignore');
+    if (!existsSync(gitignorePath)) {
+      writeFileSync(gitignorePath, '*\n!.gitignore\n');
+    }
+
+    writeFileSync(lockPath, String(process.pid));
+
+    try {
+      await this.install(signal);
+    } finally {
+      try { rmSync(lockPath); } catch { /* ignore */ }
+    }
+  }
+
+  private async install(signal?: AbortSignal): Promise<void> {
+    const os = platform();
+    const cpu = arch();
+    log.info({ os, cpu, runtimeVersion: RUNTIME_VERSION }, 'Installing embedding runtime');
+
+    // Work in a temp directory for atomic install
+    const tmpDir = join(this.baseDir, `.installing-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true });
+
+    try {
+      // Step 1: Download npm packages (and bun if needed) in parallel
+      const nodeModules = join(tmpDir, 'node_modules');
+      const downloads: Promise<void>[] = [
+        downloadAndExtract(
+          npmTarballUrl('onnxruntime-node', ONNXRUNTIME_NODE_VERSION),
+          join(nodeModules, 'onnxruntime-node'),
+          signal,
+        ),
+        downloadAndExtract(
+          npmTarballUrl('onnxruntime-common', ONNXRUNTIME_COMMON_VERSION),
+          join(nodeModules, 'onnxruntime-common'),
+          signal,
+        ),
+        downloadAndExtract(
+          npmTarballUrl('@huggingface/transformers', TRANSFORMERS_VERSION),
+          join(nodeModules, '@huggingface', 'transformers'),
+          signal,
+        ),
+      ];
+
+      // Download bun binary if not already available on the system
+      if (!this.getBunPath()) {
+        downloads.push(this.downloadBunBinary(tmpDir, signal));
+      }
+
+      await Promise.all(downloads);
+
+      if (signal?.aborted) throw new DOMException('Aborted', 'AbortError');
+
+      log.info('npm packages downloaded, stripping non-platform binaries');
+
+      // Step 2: Strip non-platform native binaries
+      const onnxBinDir = join(nodeModules, 'onnxruntime-node', 'bin', 'napi-v3');
+      if (existsSync(onnxBinDir)) {
+        const entries = readdirSync(onnxBinDir);
+        for (const entry of entries) {
+          // Keep all darwin architectures (arm64 and x86_64) since uname -m
+          // is unreliable under Rosetta (returns x86_64 on Apple Silicon)
+          if (entry !== os) {
+            rmSync(join(onnxBinDir, entry), { recursive: true, force: true });
+          }
+        }
+      }
+
+      // Strip non-runtime files to reduce disk usage.
+      // Keep lib/ directories — they contain JS entry points needed for bare
+      // specifier imports in the worker subprocess.
+      const onnxNodeDir = join(nodeModules, 'onnxruntime-node');
+      rmSync(join(onnxNodeDir, 'script'), { recursive: true, force: true });
+      rmSync(join(onnxNodeDir, 'README.md'), { force: true });
+      rmSync(join(nodeModules, 'onnxruntime-common', 'README.md'), { force: true });
+
+      // Step 3: Create a stub "sharp" package so that the pre-built
+      // transformers.node.mjs can import it without error. The bundle checks
+      // `if (sharp)` at module initialization time — the stub must be truthy.
+      // We only use text embeddings, never image processing.
+      const sharpDir = join(nodeModules, 'sharp');
+      mkdirSync(sharpDir, { recursive: true });
+      writeFileSync(join(sharpDir, 'package.json'), '{"name":"sharp","version":"0.0.0","main":"index.js"}\n');
+      writeFileSync(join(sharpDir, 'index.js'), [
+        '// Stub: only text embeddings are used, no image processing.',
+        '// Must be a truthy function so transformers.node.mjs initialization passes.',
+        'function sharp() { throw new Error("sharp stub: image processing not available"); }',
+        'sharp.format = {};',
+        'module.exports = sharp;',
+        '',
+      ].join('\n'));
+
+      // Step 4: Write embed worker script
+      writeFileSync(join(tmpDir, WORKER_FILENAME), generateWorkerScript());
+
+      // Step 5: Write version manifest
+      const manifest: VersionManifest = {
+        runtimeVersion: RUNTIME_VERSION,
+        onnxruntimeNodeVersion: ONNXRUNTIME_NODE_VERSION,
+        onnxruntimeCommonVersion: ONNXRUNTIME_COMMON_VERSION,
+        transformersVersion: TRANSFORMERS_VERSION,
+        platform: os,
+        arch: cpu,
+        installedAt: new Date().toISOString(),
+      };
+      writeFileSync(join(tmpDir, 'version.json'), JSON.stringify(manifest, null, 2) + '\n');
+
+      // Step 6: Atomic swap — remove old install and rename temp to final
+      // Preserve model-cache/, bin/ (downloaded bun), and .gitignore
+      const modelCacheDir = join(this.baseDir, 'model-cache');
+      const hadModelCache = existsSync(modelCacheDir);
+      let tmpModelCache: string | null = null;
+      if (hadModelCache) {
+        tmpModelCache = join(this.baseDir, `.model-cache-preserve-${Date.now()}`);
+        renameSync(modelCacheDir, tmpModelCache);
+      }
+
+      // Preserve downloaded bun binary if it exists and we didn't just download a new one
+      const existingBinDir = join(this.baseDir, 'bin');
+      const newBinDir = join(tmpDir, 'bin');
+      const hadBinDir = existsSync(existingBinDir) && !existsSync(newBinDir);
+      let tmpBinDir: string | null = null;
+      if (hadBinDir) {
+        tmpBinDir = join(this.baseDir, `.bin-preserve-${Date.now()}`);
+        renameSync(existingBinDir, tmpBinDir);
+      }
+
+      // Remove old install (preserving dotfiles like .gitignore, .downloading, temp dirs)
+      for (const entry of readdirSync(this.baseDir)) {
+        if (entry.startsWith('.') || entry === tmpDir.split('/').pop()) continue;
+        rmSync(join(this.baseDir, entry), { recursive: true, force: true });
+      }
+
+      // Move new files into place
+      for (const entry of readdirSync(tmpDir)) {
+        renameSync(join(tmpDir, entry), join(this.baseDir, entry));
+      }
+
+      // Restore model cache
+      if (tmpModelCache && existsSync(tmpModelCache)) {
+        renameSync(tmpModelCache, modelCacheDir);
+      }
+
+      // Restore bun binary
+      if (tmpBinDir && existsSync(tmpBinDir)) {
+        renameSync(tmpBinDir, existingBinDir);
+      }
+
+      log.info({ runtimeVersion: RUNTIME_VERSION }, 'Embedding runtime installed successfully');
+    } catch (err) {
+      log.error({ err }, 'Failed to install embedding runtime');
+      throw err;
+    } finally {
+      // Clean up temp directory
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  }
+
+  private async downloadBunBinary(installDir: string, signal?: AbortSignal): Promise<void> {
+    const os = platform();
+    const cpu = arch() === 'arm64' ? 'aarch64' : arch();
+    const target = `${os}-${cpu}`;
+    const url = `https://github.com/oven-sh/bun/releases/download/bun-v${BUN_VERSION}/bun-${target}.zip`;
+
+    log.info({ url, target, bunVersion: BUN_VERSION }, 'Downloading bun binary');
+
+    const response = await fetch(url, {
+      signal,
+      redirect: 'follow',
+    });
+    if (!response.ok) {
+      throw new Error(`Failed to download bun: ${response.status} ${response.statusText}`);
+    }
+
+    const zipData = await response.arrayBuffer();
+    const binDir = join(installDir, 'bin');
+    mkdirSync(binDir, { recursive: true });
+
+    const tmpZip = join(binDir, `bun-download-${Date.now()}.zip`);
+    writeFileSync(tmpZip, Buffer.from(zipData));
+
+    try {
+      // Extract zip
+      const proc = Bun.spawn({
+        cmd: ['unzip', '-o', tmpZip, '-d', binDir],
+        stdout: 'ignore',
+        stderr: 'pipe',
+      });
+      await proc.exited;
+      if (proc.exitCode !== 0) {
+        const stderr = await new Response(proc.stderr).text();
+        throw new Error(`Failed to extract bun zip: ${stderr}`);
+      }
+
+      // Move binary from bun-{target}/bun to bin/bun
+      const extractedBun = join(binDir, `bun-${target}`, 'bun');
+      if (existsSync(extractedBun)) {
+        renameSync(extractedBun, join(binDir, 'bun'));
+        rmSync(join(binDir, `bun-${target}`), { recursive: true, force: true });
+      }
+
+      // Make executable
+      chmodSync(join(binDir, 'bun'), 0o755);
+    } finally {
+      try { rmSync(tmpZip); } catch { /* ignore */ }
+    }
+
+    log.info('Bun binary downloaded successfully');
+  }
+
+  private readManifest(): VersionManifest | null {
+    const manifestPath = join(this.baseDir, 'version.json');
+    if (!existsSync(manifestPath)) return null;
+    try {
+      return JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    } catch {
+      return null;
+    }
+  }
+}

package/src/memory/guardian-bindings.ts

@@ -5,7 +5,7 @@
  * for a given (assistantId, channel) pair.
  */
 
-import { and, eq } from 'drizzle-orm';
+import { and, asc, desc, eq } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 
 import { getDb } from './db.js';
@@ -103,6 +103,30 @@ export function getActiveBinding(assistantId: string, channel: string): Guardian
   return row ? rowToBinding(row) : null;
 }
 
+/**
+ * List all active guardian bindings for an assistant across all channels.
+ * Deterministic ordering: verifiedAt DESC (most recently verified first),
+ * then channel ASC (alphabetical tiebreaker).
+ */
+export function listActiveBindingsByAssistant(assistantId: string): GuardianBinding[] {
+  const db = getDb();
+  return db
+    .select()
+    .from(channelGuardianBindings)
+    .where(
+      and(
+        eq(channelGuardianBindings.assistantId, assistantId),
+        eq(channelGuardianBindings.status, 'active'),
+      ),
+    )
+    .orderBy(
+      desc(channelGuardianBindings.verifiedAt),
+      asc(channelGuardianBindings.channel),
+    )
+    .all()
+    .map(rowToBinding);
+}
+
 export function revokeBinding(assistantId: string, channel: string): boolean {
   const db = getDb();
   const now = Date.now();

package/src/memory/indexer.ts

@@ -23,7 +23,7 @@ export interface IndexMessageInput {
   createdAt: number;
   scopeId?: string;
   // Provenance for trust-aware extraction gating (M3)
-  provenanceActorRole?: 'guardian' | 'non-guardian' | 'unverified_channel';
+  provenanceTrustClass?: 'guardian' | 'trusted_contact' | 'unknown';
 }
 
 export interface IndexMessageResult {
@@ -39,7 +39,7 @@ export function indexMessageNow(
 
   // Provenance-based trust gating: only guardian and legacy (undefined) actors
   // are trusted for extraction and conflict resolution.
-  const isTrustedActor = input.provenanceActorRole === 'guardian' || input.provenanceActorRole === undefined;
+  const isTrustedActor = input.provenanceTrustClass === 'guardian' || input.provenanceTrustClass === undefined;
 
   const text = extractTextFromStoredMessageContent(input.content);
   if (text.length === 0) {
@@ -123,7 +123,7 @@ export function indexMessageNow(
   }
 
   if (!isTrustedActor && (shouldExtract || shouldResolveConflicts)) {
-    log.info(`Skipping extraction/conflict jobs for untrusted actor (role=${input.provenanceActorRole})`);
+    log.info(`Skipping extraction/conflict jobs for untrusted actor (trustClass=${input.provenanceTrustClass})`);
   }
 
   enqueueSummaryRollupJobsIfDue();

package/src/memory/ingress-invite-store.ts

@@ -33,6 +33,10 @@ export interface IngressInvite {
   redeemedByExternalUserId: string | null;
   redeemedByExternalChatId: string | null;
   redeemedAt: number | null;
+  // Voice invite fields (null for non-voice invites)
+  expectedExternalUserId: string | null;
+  voiceCodeHash: string | null;
+  voiceCodeDigits: number | null;
   createdAt: number;
   updatedAt: number;
 }
@@ -90,6 +94,9 @@ function rowToInvite(row: typeof assistantIngressInvites.$inferSelect): IngressI
     redeemedByExternalUserId: row.redeemedByExternalUserId,
     redeemedByExternalChatId: row.redeemedByExternalChatId,
     redeemedAt: row.redeemedAt,
+    expectedExternalUserId: row.expectedExternalUserId,
+    voiceCodeHash: row.voiceCodeHash,
+    voiceCodeDigits: row.voiceCodeDigits,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
   };
@@ -127,6 +134,10 @@ export function createInvite(params: {
   note?: string;
   maxUses?: number;
   expiresInMs?: number;
+  // Voice invite metadata (all optional — omitted for non-voice invites)
+  expectedExternalUserId?: string;
+  voiceCodeHash?: string;
+  voiceCodeDigits?: number;
 }): { invite: IngressInvite; rawToken: string } {
   const db = getDb();
   const now = Date.now();
@@ -148,6 +159,9 @@ export function createInvite(params: {
     redeemedByExternalUserId: null,
     redeemedByExternalChatId: null,
     redeemedAt: null,
+    expectedExternalUserId: params.expectedExternalUserId ?? null,
+    voiceCodeHash: params.voiceCodeHash ?? null,
+    voiceCodeDigits: params.voiceCodeDigits ?? null,
     createdAt: now,
     updatedAt: now,
   };
@@ -432,3 +446,34 @@ export function findByTokenHash(tokenHash: string): IngressInvite | null {
 
   return row ? rowToInvite(row) : null;
 }
+
+// ---------------------------------------------------------------------------
+// findActiveVoiceInvites
+// ---------------------------------------------------------------------------
+
+/**
+ * Find all active voice invites bound to a specific caller identity.
+ * Used by the voice invite redemption flow to locate candidate invites
+ * before code hash matching.
+ */
+export function findActiveVoiceInvites(params: {
+  assistantId: string;
+  expectedExternalUserId: string;
+}): IngressInvite[] {
+  const db = getDb();
+
+  const rows = db
+    .select()
+    .from(assistantIngressInvites)
+    .where(
+      and(
+        eq(assistantIngressInvites.assistantId, params.assistantId),
+        eq(assistantIngressInvites.sourceChannel, 'voice'),
+        eq(assistantIngressInvites.status, 'active'),
+        eq(assistantIngressInvites.expectedExternalUserId, params.expectedExternalUserId),
+      ),
+    )
+    .all();
+
+  return rows.map(rowToInvite);
+}

package/src/memory/job-handlers/backfill.ts

@@ -24,21 +24,28 @@ const BACKFILL_CHECKPOINT_ID_KEY = 'memory:backfill:last_message_id';
 const RELATION_BACKFILL_CHECKPOINT_KEY = 'memory:relation_backfill:last_created_at';
 const RELATION_BACKFILL_CHECKPOINT_ID_KEY = 'memory:relation_backfill:last_message_id';
 
-type ProvenanceActorRole = 'guardian' | 'non-guardian' | 'unverified_channel';
+type ProvenanceTrustClass = 'guardian' | 'trusted_contact' | 'unknown';
 
-function parseProvenanceActorRole(rawMetadata: string | null): ProvenanceActorRole | undefined {
+function parseProvenanceTrustClass(rawMetadata: string | null): ProvenanceTrustClass | undefined {
   if (!rawMetadata) return undefined;
   try {
     const parsedJson: unknown = JSON.parse(rawMetadata);
     const parsed = messageMetadataSchema.safeParse(parsedJson);
-    return parsed.success ? parsed.data.provenanceActorRole : undefined;
+    if (!parsed.success) return undefined;
+    if (parsed.data.provenanceTrustClass) return parsed.data.provenanceTrustClass;
+    // Legacy fallback for rows written before provenanceTrustClass existed.
+    const legacyRole = (parsedJson as { provenanceActorRole?: unknown }).provenanceActorRole;
+    if (legacyRole === 'guardian') return 'guardian';
+    if (legacyRole === 'non-guardian') return 'trusted_contact';
+    if (legacyRole === 'unverified_channel') return 'unknown';
+    return undefined;
   } catch {
     return undefined;
   }
 }
 
-function isTrustedActorRole(actorRole: ProvenanceActorRole | undefined): boolean {
-  return actorRole === 'guardian' || actorRole === undefined;
+function isTrustedTrustClass(trustClass: ProvenanceTrustClass | undefined): boolean {
+  return trustClass === 'guardian' || trustClass === undefined;
 }
 
 export function backfillJob(job: MemoryJob, config: AssistantConfig): void {
@@ -68,7 +75,7 @@ export function backfillJob(job: MemoryJob, config: AssistantConfig): void {
         scopeId = getConversationMemoryScopeId(message.conversationId);
         scopeCache.set(message.conversationId, scopeId);
       }
-      const provenanceActorRole = parseProvenanceActorRole(message.metadata ?? null);
+      const provenanceTrustClass = parseProvenanceTrustClass(message.metadata ?? null);
       indexMessageNow({
         messageId: message.id,
         conversationId: message.conversationId,
@@ -76,7 +83,7 @@ export function backfillJob(job: MemoryJob, config: AssistantConfig): void {
         content: message.content,
         createdAt: message.createdAt,
         scopeId,
-        provenanceActorRole,
+        provenanceTrustClass,
       }, config.memory);
     }
     const lastMessage = batch[batch.length - 1];
@@ -139,8 +146,8 @@ export function backfillEntityRelationsJob(job: MemoryJob, config: AssistantConf
   let queuedExtractEntityJobs = 0;
   let skippedUntrusted = 0;
   for (const message of batch) {
-    const provenanceActorRole = parseProvenanceActorRole(message.metadata ?? null);
-    if (!isTrustedActorRole(provenanceActorRole)) {
+    const provenanceTrustClass = parseProvenanceTrustClass(message.metadata ?? null);
+    if (!isTrustedTrustClass(provenanceTrustClass)) {
       skippedUntrusted += 1;
       continue;
     }

package/src/memory/migrations/037-voice-invite-columns.ts

@@ -0,0 +1,16 @@
+import type { DrizzleDb } from '../db-connection.js';
+
+/**
+ * Add voice invite columns to assistant_ingress_invites for guardian-initiated
+ * voice invite codes. All columns are nullable to keep existing invite rows
+ * compatible.
+ *
+ * - expected_external_user_id: E.164 phone number for identity binding
+ * - voice_code_hash: SHA-256 hash of the short numeric code
+ * - voice_code_digits: configurable digit count (nullable — NULL for non-voice invites)
+ */
+export function migrateVoiceInviteColumns(database: DrizzleDb): void {
+  try { database.run(/*sql*/ `ALTER TABLE assistant_ingress_invites ADD COLUMN expected_external_user_id TEXT`); } catch { /* already exists */ }
+  try { database.run(/*sql*/ `ALTER TABLE assistant_ingress_invites ADD COLUMN voice_code_hash TEXT`); } catch { /* already exists */ }
+  try { database.run(/*sql*/ `ALTER TABLE assistant_ingress_invites ADD COLUMN voice_code_digits INTEGER`); } catch { /* already exists */ }
+}