@askexenow/exe-os 0.9.279 → 0.9.281

package/dist/backfill-metadata-GHUTESVD.js

@@ -0,0 +1,599 @@
+#!/usr/bin/env node
+import {
+  disposeStore,
+  initStore
+} from "./chunk-O25CS3BH.js";
+import "./chunk-CHCA3ZM2.js";
+import "./chunk-OTVEIJUQ.js";
+import "./chunk-CLBCRQWU.js";
+import "./chunk-Y25OJWOQ.js";
+import "./chunk-MP2AFCGL.js";
+import {
+  getClient,
+  getEmployeeNamesByRole,
+  loadEmployeesSync
+} from "./chunk-ZJP3ZONM.js";
+import "./chunk-2I23RPSI.js";
+import "./chunk-K26DLCUP.js";
+import "./chunk-5DNJPRDW.js";
+import "./chunk-FXU7JOXK.js";
+import "./chunk-Z42MXYWW.js";
+import "./chunk-T3B5RK4H.js";
+import "./chunk-LYH5HE24.js";
+import {
+  isMainModule
+} from "./chunk-6Y4B3QF6.js";
+import "./chunk-MLKGABMK.js";
+
+// src/bin/backfill-metadata.ts
+var VALID_INTENTS = /* @__PURE__ */ new Set(["decision", "question", "correction", "report", "discovery", "implementation"]);
+var VALID_OUTCOMES = /* @__PURE__ */ new Set(["success", "failure", "partial", "superseded"]);
+var VALID_DOMAINS = /* @__PURE__ */ new Set(["code", "architecture", "marketing", "operations", "customer", "research"]);
+var VALID_AUDIENCES = /* @__PURE__ */ new Set(["founder", "team", "self"]);
+var VALID_LANGUAGE_TYPES = /* @__PURE__ */ new Set(["code", "prose", "mixed", "json", "sql"]);
+var MAX_TEXT_LENGTH = 2e3;
+var BATCH_SLEEP_MS = 1e3;
+function roleAgentMarkers(role) {
+  try {
+    const employees = loadEmployeesSync();
+    const names = getEmployeeNamesByRole(employees, role).map((n) => n.toLowerCase().trim()).filter(Boolean);
+    if (names.length > 0) return names;
+  } catch {
+  }
+  return [];
+}
+var MARKETING_AGENT_MARKERS = roleAgentMarkers("CMO");
+var RESEARCH_AGENT_MARKERS = roleAgentMarkers("AI Product Lead");
+function mentionsAgentMarker(text, markers) {
+  return markers.some(
+    (marker) => text.includes(`/${marker}/`) || text.includes(`agent_id: ${marker}`)
+  );
+}
+function classifyMemoryHeuristic(rawText, toolName) {
+  const t = rawText.toLowerCase();
+  let intent;
+  if (toolName === "store_decision" || t.includes("decided") || t.includes("decision:")) {
+    intent = "decision";
+  } else if (toolName === "store_memory" || toolName === "commit_to_long_term_memory" || toolName === "update_task" || toolName === "store_behavior" || t.startsWith("stored memory") || t.startsWith("task updated") || t.startsWith("auto-summary")) {
+    intent = "report";
+  } else if (t.includes("fix ") || t.includes("fixed") || t.includes("correction") || t.includes("bug") || t.includes("revert") || t.includes("hotfix")) {
+    intent = "correction";
+  } else if (toolName === "Edit" || toolName === "Write" || toolName === "NotebookEdit" || toolName === "Bash" && (t.includes("npm run build") || t.includes("git commit") || t.includes("npm install") || t.includes("npx "))) {
+    intent = "implementation";
+  } else if (toolName === "Read" || toolName === "Grep" || toolName === "Glob" || toolName === "Agent" || t.includes("?") || t.includes("search")) {
+    intent = "question";
+  } else if (t.includes("found") || t.includes("discovered") || t.includes("noticed") || t.includes("interesting") || t.includes("realized")) {
+    intent = "discovery";
+  } else if (toolName === "Bash") {
+    intent = "implementation";
+  } else {
+    intent = "report";
+  }
+  let outcome;
+  if (t.includes("error") || t.includes("failed") || t.includes("failure") || t.includes("exit code 1") || t.includes("exception") || t.includes("crash") || t.includes("rejected") || t.includes("\u274C")) {
+    outcome = "failure";
+  } else if (t.includes("success") || t.includes("passed") || t.includes("\u2713") || t.includes("complete") || t.includes("done") || t.includes("shipped") || t.includes("merged") || t.includes("build success")) {
+    outcome = "success";
+  } else if (t.includes("superseded") || t.includes("deprecated") || t.includes("replaced by") || t.includes("archived")) {
+    outcome = "superseded";
+  } else {
+    outcome = "partial";
+  }
+  let domain;
+  if (t.includes("marketing") || t.includes("campaign") || t.includes("brand") || t.includes("carousel") || t.includes("seo") || t.includes("content strategy") || mentionsAgentMarker(t, MARKETING_AGENT_MARKERS)) {
+    domain = "marketing";
+  } else if (t.includes("architecture") || t.includes("adr") || t.includes("design doc") || t.includes("system design") || t.includes("ARCHITECTURE.md") || t.includes("schema") && t.includes("migration")) {
+    domain = "architecture";
+  } else if (t.includes("customer") || t.includes("onboarding") || t.includes("install") || t.includes("setup wizard") || t.includes("license") || t.includes("stripe") || t.includes("user feedback")) {
+    domain = "customer";
+  } else if (t.includes("deploy") || t.includes("ci/cd") || t.includes("docker") || t.includes("nginx") || t.includes("cron") || t.includes("schedule") || t.includes("task management") || t.includes("roster") || toolName === "update_task" || toolName === "create_task") {
+    domain = "operations";
+  } else if (t.includes("research") || t.includes("competitor") || t.includes("benchmark") || t.includes("comparison") || t.includes("analysis") || t.includes("evaluate") || mentionsAgentMarker(t, RESEARCH_AGENT_MARKERS)) {
+    domain = "research";
+  } else {
+    domain = "code";
+  }
+  let audience;
+  if (toolName === "send_message" || toolName === "ask_team_memory" || toolName === "create_task" || toolName === "update_task" || t.includes("dispatched") || t.includes("assigned to")) {
+    audience = "team";
+  } else if (toolName === "store_memory" || toolName === "commit_to_long_term_memory" || toolName === "store_decision" || toolName === "store_behavior" || t.includes("summary") || t.includes("report") || t.includes("audit") || t.startsWith("stored memory")) {
+    audience = "founder";
+  } else {
+    audience = "self";
+  }
+  let languageType;
+  const jsonIndicators = (t.match(/[{}[\]]/g) || []).length;
+  const codeIndicators = (t.match(/\b(function|const|let|var|import|export|return|if|else|class|async|await)\b/g) || []).length;
+  const sqlIndicators = (t.match(/\b(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|FROM|WHERE|JOIN)\b/gi) || []).length;
+  if (sqlIndicators >= 2) {
+    languageType = "sql";
+  } else if (jsonIndicators > 6 && jsonIndicators > codeIndicators) {
+    languageType = "json";
+  } else if (codeIndicators >= 3) {
+    languageType = codeIndicators > 5 ? "code" : "mixed";
+  } else if (jsonIndicators > 3) {
+    languageType = "mixed";
+  } else {
+    languageType = "prose";
+  }
+  return { intent, outcome, domain, audience, language_type: languageType };
+}
+async function classifyMemory(_anthropic, rawText) {
+  const truncated = rawText.length > MAX_TEXT_LENGTH ? rawText.slice(0, MAX_TEXT_LENGTH) : rawText;
+  const baseUrl = process.env.ANTHROPIC_BASE_URL ?? "https://api.anthropic.com";
+  const apiKey = process.env.ANTHROPIC_API_KEY ?? "";
+  const model = process.env.BACKFILL_MODEL ?? "claude-haiku-4-5-20251001";
+  try {
+    const res = await fetch(`${baseUrl}/v1/messages`, {
+      method: "POST",
+      headers: {
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: 100,
+        system: "You are a JSON classifier. Output ONLY valid JSON. No explanation, no markdown, no text before or after the JSON object.",
+        messages: [
+          {
+            role: "user",
+            content: `{"task":"classify","categories":{"intent":["decision","question","correction","report","discovery","implementation"],"outcome":["success","failure","partial","superseded"],"domain":["code","architecture","marketing","operations","customer","research"],"audience":["founder","team","self"],"language_type":["code","prose","mixed","json","sql"]},"text":"${truncated.replace(/"/g, '\\"').replace(/\n/g, " ").slice(0, 500)}"}`
+          },
+          {
+            role: "assistant",
+            content: "{"
+          }
+        ]
+      })
+    });
+    if (!res.ok) {
+      const errText = await res.text();
+      throw new Error(`${res.status} ${errText.slice(0, 200)}`);
+    }
+    const data = await res.json();
+    const textBlock = data.content.find((b) => b.type === "text");
+    if (!textBlock?.text) return null;
+    const jsonText = "{" + textBlock.text.trim();
+    const parsed = JSON.parse(jsonText);
+    if (!VALID_INTENTS.has(parsed.intent)) return null;
+    if (!VALID_OUTCOMES.has(parsed.outcome)) return null;
+    if (!VALID_DOMAINS.has(parsed.domain)) return null;
+    if (!VALID_AUDIENCES.has(parsed.audience)) return null;
+    if (!VALID_LANGUAGE_TYPES.has(parsed.language_type)) return null;
+    return parsed;
+  } catch (err) {
+    process.stderr.write(
+      `[backfill-metadata] LLM error: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return null;
+  }
+}
+async function backfillHeuristic(options) {
+  const client = getClient();
+  const countResult = await client.execute({
+    sql: "SELECT COUNT(*) as cnt FROM memories WHERE intent IS NULL AND outcome IS NULL AND domain IS NULL",
+    args: []
+  });
+  const totalUnclassified = Number(countResult.rows[0]?.cnt ?? 0);
+  if (totalUnclassified === 0) {
+    process.stderr.write("[backfill-metadata] All memories already classified.\n");
+    return { classified: 0, skipped: 0, remaining: 0 };
+  }
+  const toProcess = options.limit > 0 ? Math.min(options.limit, totalUnclassified) : totalUnclassified;
+  process.stderr.write(`[backfill-metadata] ${totalUnclassified} unclassified. Heuristic-classifying ${toProcess}.
+`);
+  if (options.dryRun) {
+    process.stderr.write("[backfill-metadata] Dry run \u2014 would classify " + toProcess + " memories.\n");
+    return { classified: 0, skipped: 0, remaining: totalUnclassified };
+  }
+  let classified = 0;
+  let skipped = 0;
+  while (classified + skipped < toProcess) {
+    const batch = await client.execute({
+      sql: `SELECT id, raw_text, tool_name FROM memories
+            WHERE intent IS NULL AND outcome IS NULL AND domain IS NULL
+            ORDER BY rowid LIMIT ?`,
+      args: [options.batchSize]
+    });
+    if (batch.rows.length === 0) break;
+    for (const row of batch.rows) {
+      const rawText = row.raw_text;
+      const toolName = row.tool_name;
+      if (!rawText || rawText.length < 10) {
+        await client.execute({
+          sql: "UPDATE memories SET intent = 'report', outcome = 'partial', domain = 'code', audience = 'self', language_type = 'prose' WHERE id = ?",
+          args: [row.id]
+        });
+        skipped++;
+        continue;
+      }
+      const result = classifyMemoryHeuristic(rawText, toolName);
+      await client.execute({
+        sql: "UPDATE memories SET intent = ?, outcome = ?, domain = ?, audience = ?, language_type = ? WHERE id = ?",
+        args: [result.intent, result.outcome, result.domain, result.audience, result.language_type, row.id]
+      });
+      classified++;
+    }
+    if (classified % 5e3 < options.batchSize) {
+      process.stderr.write(`[backfill-metadata] Heuristic progress: ${classified} classified, ${skipped} skipped
+`);
+    }
+  }
+  const remainResult = await client.execute({
+    sql: "SELECT COUNT(*) as cnt FROM memories WHERE intent IS NULL AND outcome IS NULL AND domain IS NULL",
+    args: []
+  });
+  const remaining = Number(remainResult.rows[0]?.cnt ?? 0);
+  process.stderr.write(
+    `[backfill-metadata] Heuristic complete. Classified: ${classified}, Skipped: ${skipped}, Remaining: ${remaining}
+`
+  );
+  return { classified, skipped, remaining };
+}
+async function backfillClassifications(options) {
+  const Anthropic = (await import("@anthropic-ai/sdk")).default;
+  const client = getClient();
+  const anthropic = new Anthropic();
+  let classified = 0;
+  let skipped = 0;
+  let failed = 0;
+  const countResult = await client.execute({
+    sql: "SELECT COUNT(*) as cnt FROM memories WHERE intent IS NULL AND outcome IS NULL AND domain IS NULL",
+    args: []
+  });
+  const totalUnclassified = Number(countResult.rows[0]?.cnt ?? 0);
+  if (totalUnclassified === 0) {
+    process.stderr.write("[backfill-metadata] All memories already classified.\n");
+    return { classified: 0, skipped: 0, failed: 0, remaining: 0 };
+  }
+  const toProcess = options.limit > 0 ? Math.min(options.limit, totalUnclassified) : totalUnclassified;
+  process.stderr.write(`[backfill-metadata] ${totalUnclassified} unclassified memories. Processing ${toProcess}.
+`);
+  if (options.dryRun) {
+    const sample = await client.execute({
+      sql: "SELECT id, SUBSTR(raw_text, 1, 80) as preview FROM memories WHERE intent IS NULL AND outcome IS NULL AND domain IS NULL ORDER BY timestamp DESC LIMIT 10",
+      args: []
+    });
+    process.stderr.write("[backfill-metadata] Dry run \u2014 sample of unclassified memories:\n");
+    for (const row of sample.rows) {
+      process.stderr.write(`  ${row.id} \u2014 ${row.preview}...
+`);
+    }
+    return { classified: 0, skipped: 0, failed: 0, remaining: totalUnclassified };
+  }
+  while (classified + skipped + failed < toProcess) {
+    const batch = await client.execute({
+      sql: "SELECT id, raw_text FROM memories WHERE intent IS NULL AND outcome IS NULL AND domain IS NULL ORDER BY timestamp DESC LIMIT ?",
+      args: [options.batchSize]
+    });
+    if (batch.rows.length === 0) break;
+    for (const row of batch.rows) {
+      const id = row.id;
+      const rawText = row.raw_text;
+      if (!rawText || rawText.length < 10) {
+        skipped++;
+        continue;
+      }
+      const result = await classifyMemory(anthropic, rawText);
+      if (!result) {
+        failed++;
+        process.stderr.write(`[backfill-metadata] Failed to classify ${id}
+`);
+        await client.execute({
+          sql: "UPDATE memories SET intent = 'unknown' WHERE id = ?",
+          args: [id]
+        });
+        continue;
+      }
+      await client.execute({
+        sql: "UPDATE memories SET intent = ?, outcome = ?, domain = ?, audience = ?, language_type = ? WHERE id = ?",
+        args: [result.intent, result.outcome, result.domain, result.audience, result.language_type, id]
+      });
+      classified++;
+    }
+    const total = classified + skipped + failed;
+    if (total % 100 < options.batchSize) {
+      process.stderr.write(`[backfill-metadata] Progress: ${classified} classified, ${failed} failed, ${skipped} skipped (${total}/${toProcess})
+`);
+    }
+    if (classified + skipped + failed < toProcess) {
+      await new Promise((resolve) => setTimeout(resolve, BATCH_SLEEP_MS));
+    }
+  }
+  const remainResult = await client.execute({
+    sql: "SELECT COUNT(*) as cnt FROM memories WHERE intent IS NULL AND outcome IS NULL AND domain IS NULL",
+    args: []
+  });
+  const remaining = Number(remainResult.rows[0]?.cnt ?? 0);
+  process.stderr.write(
+    `[backfill-metadata] Classification complete. Classified: ${classified}, Failed: ${failed}, Skipped: ${skipped}, Remaining: ${remaining}
+`
+  );
+  return { classified, skipped, failed, remaining };
+}
+async function backfillEntities(options) {
+  const client = getClient();
+  let populated = 0;
+  const countResult = await client.execute({
+    sql: "SELECT COUNT(*) as cnt FROM memories WHERE referenced_entities IS NULL",
+    args: []
+  });
+  const totalNull = Number(countResult.rows[0]?.cnt ?? 0);
+  if (totalNull === 0) {
+    process.stderr.write("[backfill-metadata] All memories already have referenced_entities.\n");
+    return 0;
+  }
+  const toProcess = options.limit > 0 ? Math.min(options.limit, totalNull) : totalNull;
+  process.stderr.write(`[backfill-metadata] ${totalNull} memories without referenced_entities. Processing ${toProcess}.
+`);
+  if (options.dryRun) {
+    process.stderr.write("[backfill-metadata] Dry run \u2014 would populate referenced_entities for up to " + toProcess + " memories.\n");
+    return 0;
+  }
+  const entityRows = await client.execute({
+    sql: "SELECT DISTINCT name FROM entities",
+    args: []
+  });
+  const knownEntities = new Set(entityRows.rows.map((r) => r.name));
+  let processed = 0;
+  while (processed < toProcess) {
+    const batch = await client.execute({
+      sql: `SELECT m.id, m.raw_text, GROUP_CONCAT(e.name) as entities
+            FROM memories m
+            LEFT JOIN entity_memories em ON em.memory_id = m.id
+            LEFT JOIN entities e ON e.id = em.entity_id
+            WHERE m.referenced_entities IS NULL
+            GROUP BY m.id
+            LIMIT ?`,
+      args: [options.batchSize]
+    });
+    if (batch.rows.length === 0) break;
+    for (const row of batch.rows) {
+      const id = row.id;
+      const rawText = row.raw_text;
+      const graphEntities = row.entities;
+      let entityList;
+      if (graphEntities) {
+        entityList = graphEntities.split(",").filter(Boolean);
+      } else {
+        entityList = extractEntitiesHeuristic(rawText, knownEntities);
+      }
+      const jsonArray = JSON.stringify(entityList);
+      await client.execute({
+        sql: "UPDATE memories SET referenced_entities = ? WHERE id = ?",
+        args: [jsonArray, id]
+      });
+      populated++;
+    }
+    processed += batch.rows.length;
+    if (processed % 100 < options.batchSize) {
+      process.stderr.write(`[backfill-metadata] Entity progress: ${populated} populated (${processed}/${toProcess})
+`);
+    }
+  }
+  process.stderr.write(`[backfill-metadata] Entity extraction complete. Populated: ${populated}
+`);
+  return populated;
+}
+function extractEntitiesHeuristic(rawText, knownEntities) {
+  const entities = /* @__PURE__ */ new Set();
+  for (const name of knownEntities) {
+    if (name.length >= 3 && rawText.toLowerCase().includes(name.toLowerCase())) {
+      entities.add(name);
+    }
+  }
+  const filePathPattern = /(?:\/[\w.-]+){2,}/g;
+  const paths = rawText.match(filePathPattern);
+  if (paths) {
+    for (const p of paths.slice(0, 5)) {
+      entities.add(p);
+    }
+  }
+  const toolPattern = /\b(Read|Write|Edit|Bash|Grep|Glob|Agent|mcp__\w+)\b/g;
+  const tools = rawText.match(toolPattern);
+  if (tools) {
+    for (const t of new Set(tools)) {
+      entities.add(t);
+    }
+  }
+  return [...entities];
+}
+async function showStats() {
+  const client = getClient();
+  const fields = ["intent", "outcome", "domain", "audience", "language_type"];
+  const totalResult = await client.execute({ sql: "SELECT COUNT(*) as cnt FROM memories", args: [] });
+  const total = Number(totalResult.rows[0]?.cnt ?? 0);
+  const unclassResult = await client.execute({
+    sql: "SELECT COUNT(*) as cnt FROM memories WHERE intent IS NULL",
+    args: []
+  });
+  const unclassified = Number(unclassResult.rows[0]?.cnt ?? 0);
+  process.stdout.write(`Total memories: ${total}
+Classified: ${total - unclassified}
+Unclassified: ${unclassified}
+
+`);
+  for (const field of fields) {
+    const dist = await client.execute({
+      sql: `SELECT ${field} as val, COUNT(*) as cnt FROM memories WHERE ${field} IS NOT NULL GROUP BY ${field} ORDER BY cnt DESC`,
+      args: []
+    });
+    process.stdout.write(`${field}:
+`);
+    for (const row of dist.rows) {
+      const pct = (Number(row.cnt) / (total - unclassified) * 100).toFixed(1);
+      process.stdout.write(`  ${String(row.val).padEnd(20)} ${String(row.cnt).padStart(7)}  (${pct}%)
+`);
+    }
+    process.stdout.write("\n");
+  }
+}
+async function exportBatches(options) {
+  const fs = await import("fs");
+  const path = await import("path");
+  const client = getClient();
+  const outDir = path.join(process.cwd(), "exe/output/classifications/input");
+  fs.mkdirSync(outDir, { recursive: true });
+  const countResult = await client.execute({
+    sql: "SELECT COUNT(*) as cnt FROM memories WHERE intent IS NULL AND outcome IS NULL AND domain IS NULL",
+    args: []
+  });
+  const total = Number(countResult.rows[0]?.cnt ?? 0);
+  process.stderr.write(`[backfill-metadata] ${total} unclassified memories to export.
+`);
+  if (total === 0) return 0;
+  const toProcess = options.limit > 0 ? Math.min(options.limit, total) : total;
+  let offset = 0;
+  let batchNum = 1;
+  let exported = 0;
+  while (offset < toProcess) {
+    const batch = await client.execute({
+      sql: "SELECT id, SUBSTR(raw_text, 1, 500) as text FROM memories WHERE intent IS NULL AND outcome IS NULL AND domain IS NULL ORDER BY rowid LIMIT ? OFFSET ?",
+      args: [options.batchSize, offset]
+    });
+    if (batch.rows.length === 0) break;
+    const lines = batch.rows.map((row) => {
+      const text = String(row.text || "").replace(/\n/g, " ");
+      return JSON.stringify({ id: row.id, text });
+    });
+    const batchFile = path.join(outDir, `batch-${String(batchNum).padStart(4, "0")}.jsonl`);
+    fs.writeFileSync(batchFile, lines.join("\n") + "\n");
+    exported += batch.rows.length;
+    offset += options.batchSize;
+    batchNum++;
+    if ((batchNum - 1) % 50 === 0) {
+      process.stderr.write(`[backfill-metadata] Exported ${exported}/${toProcess}
+`);
+    }
+  }
+  process.stderr.write(`[backfill-metadata] Export complete: ${batchNum - 1} batch files, ${exported} memories.
+`);
+  return exported;
+}
+async function importClassifications(importDir) {
+  const fs = await import("fs");
+  const path = await import("path");
+  const client = getClient();
+  const files = fs.readdirSync(importDir).filter((f) => f.endsWith(".jsonl")).sort();
+  process.stderr.write(`[backfill-metadata] Found ${files.length} JSONL files to import from ${importDir}
+`);
+  let imported = 0;
+  let invalid = 0;
+  for (const file of files) {
+    const lines = fs.readFileSync(path.join(importDir, file), "utf-8").split("\n").filter(Boolean);
+    for (const line of lines) {
+      try {
+        const rec = JSON.parse(line);
+        if (!rec.id || !VALID_INTENTS.has(rec.intent) || !VALID_OUTCOMES.has(rec.outcome) || !VALID_DOMAINS.has(rec.domain) || !VALID_AUDIENCES.has(rec.audience) || !VALID_LANGUAGE_TYPES.has(rec.language_type)) {
+          invalid++;
+          continue;
+        }
+        await client.execute({
+          sql: "UPDATE memories SET intent = ?, outcome = ?, domain = ?, audience = ?, language_type = ? WHERE id = ?",
+          args: [rec.intent, rec.outcome, rec.domain, rec.audience, rec.language_type, rec.id]
+        });
+        imported++;
+      } catch {
+        invalid++;
+      }
+    }
+    if (imported % 1e3 < 200) {
+      process.stderr.write(`[backfill-metadata] Imported ${imported} (${invalid} invalid)
+`);
+    }
+  }
+  process.stderr.write(`[backfill-metadata] Import complete: ${imported} updated, ${invalid} invalid.
+`);
+  return { imported, invalid };
+}
+function parseArgs(argv) {
+  let batchSize = 50;
+  let limit = 0;
+  let dryRun = false;
+  let entities = false;
+  let exportBatchesFlag = false;
+  let importDir = "";
+  let heuristic = false;
+  let stats = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--batch-size=")) {
+      batchSize = parseInt(arg.split("=")[1], 10) || 50;
+    } else if (arg === "--batch-size" && argv[i + 1]) {
+      batchSize = parseInt(argv[++i], 10) || 50;
+    } else if (arg.startsWith("--limit=")) {
+      limit = parseInt(arg.split("=")[1], 10) || 0;
+    } else if (arg === "--limit" && argv[i + 1]) {
+      limit = parseInt(argv[++i], 10) || 0;
+    } else if (arg === "--dry-run") {
+      dryRun = true;
+    } else if (arg === "--entities") {
+      entities = true;
+    } else if (arg === "--heuristic") {
+      heuristic = true;
+    } else if (arg === "--stats") {
+      stats = true;
+    } else if (arg === "--export") {
+      exportBatchesFlag = true;
+    } else if (arg.startsWith("--import=")) {
+      importDir = arg.split("=")[1];
+    } else if (arg === "--import" && argv[i + 1]) {
+      importDir = argv[++i];
+    }
+  }
+  return { batchSize, limit, dryRun, entities, exportBatches: exportBatchesFlag, importDir, heuristic, stats };
+}
+async function backfillMetadata(options) {
+  await initStore();
+  let classified = 0;
+  let skipped = 0;
+  let failed = 0;
+  let remaining = 0;
+  let entitiesPopulated = 0;
+  if (options.stats) {
+    await showStats();
+    await disposeStore();
+    return { classified: 0, skipped: 0, failed: 0, entitiesPopulated: 0, remaining: 0 };
+  }
+  if (options.exportBatches) {
+    const exported = await exportBatches(options);
+    await disposeStore();
+    return { classified: 0, skipped: 0, failed: 0, entitiesPopulated: 0, remaining: exported };
+  }
+  if (options.importDir) {
+    const { imported, invalid } = await importClassifications(options.importDir);
+    await disposeStore();
+    return { classified: imported, skipped: 0, failed: invalid, entitiesPopulated: 0, remaining: 0 };
+  }
+  if (options.heuristic) {
+    const result = await backfillHeuristic(options);
+    await disposeStore();
+    return { classified: result.classified, skipped: result.skipped, failed: 0, entitiesPopulated: 0, remaining: result.remaining };
+  }
+  if (options.entities) {
+    entitiesPopulated = await backfillEntities(options);
+  } else {
+    const result = await backfillClassifications(options);
+    classified = result.classified;
+    skipped = result.skipped;
+    failed = result.failed;
+    remaining = result.remaining;
+  }
+  await disposeStore();
+  return { classified, skipped, failed, entitiesPopulated, remaining };
+}
+if (isMainModule(import.meta.url)) {
+  const options = parseArgs(process.argv.slice(2));
+  backfillMetadata(options).then((result) => {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.failed > 0 ? 1 : 0);
+  }).catch((err) => {
+    console.error("[backfill-metadata] Fatal:", err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });
+}
+export {
+  backfillMetadata
+};