@gafj/gafj 0.1.1

package/store/discover.js

@@ -0,0 +1,120 @@
+"use strict";
+
+/**
+ * Discovery (plan section U, the shakedown): a candidate-level run whose
+ * reply is questions, not a document. saveDiscovery counts the attempt,
+ * validates the schema, refuses any question whose record id is outside
+ * the packet's slice, and stores the rest as open questions. The candidate
+ * answers on the knowledge base screen: the answer is a pending row with
+ * replaces, so confirming it extends the record. Three attempts per run;
+ * a new run is refused while open questions remain, so questions never pile.
+ */
+
+const { ulid } = require("../core/ulid");
+const { extractJson } = require("../core/extract");
+const { SCHEMAS, validate } = require("../core/schemas");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+const { TransitionError, NotFound } = require("./transitions");
+const kb = require("./kb");
+
+const MAX_ATTEMPTS = 3;
+const MAX_OPEN = 12;
+
+function status(q) {
+  return q.answered_at ? "answered" : q.dismissed_at ? "dismissed" : "open";
+}
+
+function listQuestions(db, candidate_id, { all = false } = {}) {
+  return db.prepare(`SELECT q.id AS question_id, q.ai_run_id, q.accomplishment_id, q.kind, q.question, q.why, q.asked_at, q.answered_at, q.dismissed_at, q.pending_id,
+      a.title, a.company, a.role, a.date_start, a.date_end FROM kb_question q JOIN accomplishment a ON a.id = q.accomplishment_id
+    WHERE q.candidate_id = ? ${all ? "" : "AND q.answered_at IS NULL AND q.dismissed_at IS NULL"} ORDER BY q.asked_at DESC, q.id`).all(candidate_id)
+    .map((q) => ({ ...q, status: status(q), dates: [q.date_start, q.date_end].filter(Boolean).join(" to "), date_start: undefined, date_end: undefined,
+      draft: { replaces: q.accomplishment_id, title: q.title, company: q.company, role: q.role, dates: [q.date_start, q.date_end].filter(Boolean).join(" to "), summary: "", metrics: [], verbs: [], wordings: [], tags: [] } }));
+}
+
+function openCount(db, candidate_id) {
+  return db.prepare("SELECT count(*) c FROM kb_question WHERE candidate_id = ? AND answered_at IS NULL AND dismissed_at IS NULL").get(candidate_id).c;
+}
+
+/** Refuse a new round while the last one is unanswered. Called by openRun's gather through the api. */
+function assertCanOpen(db, candidate_id) {
+  const open = openCount(db, candidate_id);
+  if (open) throw new TransitionError(`${open} discovery question${open === 1 ? " is" : "s are"} still open; answer or dismiss them before asking for more`);
+}
+
+/** The discovery door: questions in, open questions out. Never touches the record. */
+function saveDiscovery(db, { run_id, content, route, actor, now, provider, model, tokens_in, tokens_out, latency_ms }) {
+  return withTx(db, (d) => {
+    const run = d.prepare("SELECT * FROM ai_run WHERE id = ?").get(run_id);
+    if (!run) throw new NotFound("run");
+    if (run.operation !== "discover") throw new TransitionError("this run is not a discovery; use the document door");
+    const attempts = d.prepare("SELECT count(*) c FROM ai_attempt WHERE ai_run_id = ?").get(run.id).c;
+    if (attempts >= MAX_ATTEMPTS) return { run_id: run.id, status: "blocked", attempt: attempts, stop: true, errors: ["three attempts used; open a fresh packet"], question_ids: [] };
+    const attemptNo = attempts + 1;
+    const ex = extractJson(content);
+    const errors = [];
+    let parsed = null;
+    if (ex.error) errors.push("schema: " + ex.error);
+    else {
+      parsed = ex.value;
+      for (const e of validate(parsed, SCHEMAS.discover)) errors.push(`${e.path}: ${e.message}`);
+    }
+    const allowed = new Set(JSON.parse(run.kb_ids_json || "[]"));
+    const seen = new Set();
+    const accepted = [];
+    if (parsed && !errors.length) {
+      parsed.questions.forEach((q, i) => {
+        if (!allowed.has(q.accomplishment_id)) { errors.push(`questions[${i}]: record ${q.accomplishment_id} is not in this packet's slice`); return; }
+        const key = q.accomplishment_id + "|" + q.question.toLowerCase().replace(/\s+/g, " ").trim();
+        if (seen.has(key)) return;
+        seen.add(key);
+        accepted.push(q);
+      });
+    }
+    const attemptId = ulid(Date.parse(now) + 100 + attemptNo);
+    const ok = !errors.length && accepted.length > 0;
+    d.prepare(`INSERT INTO ai_attempt (id, ai_run_id, attempt_no, provider, model, tokens_in, tokens_out, latency_ms, output_hash, result, error_code, started_at, finished_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(attemptId, run.id, attemptNo, provider || null, model || null, tokens_in ?? null, tokens_out ?? null, latency_ms ?? null, null, ok ? "passed" : "blocked", ok ? null : (ex.error ? "schema" : "slice"), now, now);
+    const ids = [];
+    if (ok) {
+      const room = Math.max(0, MAX_OPEN - openCount(d, run.candidate_id));
+      for (const q of accepted.slice(0, room)) {
+        const id = ulid(Date.parse(now) + ids.length);
+        d.prepare("INSERT INTO kb_question (id, candidate_id, ai_run_id, accomplishment_id, kind, question, why, asked_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
+          .run(id, run.candidate_id, run.id, q.accomplishment_id, q.kind, q.question.trim(), (q.why || "").trim() || null, now);
+        ids.push(id);
+      }
+    }
+    const final = ok ? "passed" : attemptNo >= MAX_ATTEMPTS ? "blocked" : "pending";
+    d.prepare("UPDATE ai_run SET final_result = ?, finished_at = CASE WHEN ? = 'pending' THEN finished_at ELSE ? END WHERE id = ?").run(final, final, now, run.id);
+    appendEvent(d, { candidate_id: run.candidate_id, entity: "ai_run", entity_id: run.id, event: ok ? "discovery_saved" : "discovery_blocked", actor_type: actor.type, actor_ref: actor.ref, payload: { attempt: attemptNo, questions: ids.length, errors: errors.length, route }, at: now });
+    return { run_id: run.id, status: ok ? "passed" : "blocked", attempt: attemptNo, stop: attemptNo >= MAX_ATTEMPTS && !ok, errors, question_ids: ids, notes: parsed && ok ? parsed.notes || null : null };
+  });
+}
+
+/** The candidate answers in their own words: a pending row that extends the record; the question closes when it lands. */
+function answerQuestion(db, { candidate_id, question_id, draft, now, actor }) {
+  return withTx(db, (d) => {
+    const q = d.prepare("SELECT * FROM kb_question WHERE id = ? AND candidate_id = ?").get(question_id, candidate_id);
+    if (!q) throw new NotFound("question");
+    if (q.answered_at || q.dismissed_at) throw new TransitionError("this question is closed");
+    const r = kb.proposeManual(d, { candidate_id, draft: { ...(draft || {}), replaces: q.accomplishment_id }, now, actor });
+    d.prepare("UPDATE kb_question SET answered_at = ?, pending_id = ? WHERE id = ?").run(now, r.pending_id, q.id);
+    appendEvent(d, { candidate_id, entity: "kb_question", entity_id: q.id, event: "answered", actor_type: actor.type, actor_ref: actor.ref, payload: { pending_id: r.pending_id, kind: q.kind }, at: now });
+    return { question_id: q.id, pending_id: r.pending_id };
+  });
+}
+
+function dismissQuestion(db, { candidate_id, question_id, now, actor }) {
+  return withTx(db, (d) => {
+    const q = d.prepare("SELECT * FROM kb_question WHERE id = ? AND candidate_id = ?").get(question_id, candidate_id);
+    if (!q) throw new NotFound("question");
+    if (q.answered_at || q.dismissed_at) throw new TransitionError("this question is closed");
+    d.prepare("UPDATE kb_question SET dismissed_at = ? WHERE id = ?").run(now, q.id);
+    appendEvent(d, { candidate_id, entity: "kb_question", entity_id: q.id, event: "dismissed", actor_type: actor.type, actor_ref: actor.ref, at: now });
+    return { question_id: q.id, dismissed: true };
+  });
+}
+
+module.exports = { saveDiscovery, listQuestions, answerQuestion, dismissQuestion, openCount, assertCanOpen, MAX_ATTEMPTS, MAX_OPEN };

package/store/events.js

@@ -0,0 +1,28 @@
+"use strict";
+
+/**
+ * Append-only event log. Every important mutation calls this inside the
+ * same transaction as the mutation. actor_type says who did it; prior holds
+ * the values an edit replaced so corrections are recoverable.
+ */
+
+const ACTORS = new Set(["ui", "cli", "mcp", "bridge", "import", "system"]);
+
+function appendEvent(db, e) {
+  if (!ACTORS.has(e.actor_type)) throw new Error(`bad actor_type ${e.actor_type}`);
+  const stmt = db.prepare(
+    `INSERT INTO event_log (candidate_id, entity, entity_id, event, actor_type, actor_ref, payload_json, prior_json, at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  );
+  const r = stmt.run(
+    e.candidate_id, e.entity, e.entity_id, e.event, e.actor_type, e.actor_ref ?? null,
+    JSON.stringify(e.payload ?? {}), e.prior == null ? null : JSON.stringify(e.prior), e.at
+  );
+  return Number(r.lastInsertRowid);
+}
+
+function eventsSince(db, cursor, limit = 200) {
+  return db.prepare("SELECT * FROM event_log WHERE id > ? ORDER BY id LIMIT ?").all(cursor, limit);
+}
+
+module.exports = { appendEvent, eventsSince, ACTORS };

package/store/export_xlsx.js

@@ -0,0 +1,62 @@
+"use strict";
+
+/**
+ * The xlsx tracker as an export view (decision 3): same fifteen columns,
+ * same status fills, a dated file in the export folder, never the live
+ * tracker path. The five equivalence criteria: same rows, same columns and
+ * order, same displayed values, status fills preserved, opens cleanly.
+ */
+
+const path = require("path");
+
+const COLUMNS = ["Company", "Role / Title", "Location", "Date Applied", "Source", "Contact Name", "Contact Email", "Status",
+  "Follow-Up Date", "Interview Date", "Offer ($)", "Notes", "Tailored Resume", "Stage", "Fit Score"];
+const FILL = { applied: "FFBDD7EE", to_apply: "FFC6EFCE", pass: "FFFFC7CE", rejected: "FFFFC7CE", closed: "FFFFC7CE", offer: "FFBDD7EE" };
+const STATUS_LABEL = { applied: "Applied", to_apply: "To Apply", pass: "Pass", rejected: "Rejected", closed: "Closed", offer: "Offer" };
+
+function rowsFor(db, candidate_id) {
+  const apps = db.prepare(`
+    SELECT a.id, a.status, a.applied_at, a.notes, p.company, p.title, p.location, p.source_url, s.fit_score
+    FROM application a JOIN posting p ON p.id = a.posting_id LEFT JOIN scoring s ON s.id = a.scoring_id
+    WHERE p.candidate_id = ? ORDER BY COALESCE(a.applied_at, '') , p.company`).all(candidate_id);
+  const nextInterview = db.prepare(`SELECT scheduled_at FROM interview WHERE application_id = ? AND status IN ('scheduled','completed') ORDER BY scheduled_at DESC LIMIT 1`);
+  const contact = db.prepare(`SELECT pe.name, pe.title, pe.links_json FROM application_person ap JOIN person pe ON pe.id = ap.person_id
+    WHERE ap.application_id = ? ORDER BY CASE ap.role WHEN 'interviewer' THEN 0 WHEN 'recruiter' THEN 1 ELSE 2 END LIMIT 1`);
+  return apps.map((a) => {
+    const iv = nextInterview.get(a.id);
+    const c = contact.get(a.id);
+    const email = c ? (JSON.parse(c.links_json).find((l) => l.kind === "email") || {}).value : null;
+    const notes = a.notes || "";
+    const stage = (notes.match(/^Stage: (.*)$/m) || [])[1] || "";
+    const resume = (notes.match(/^Resume file: (.*)$/m) || [])[1] || "";
+    const plainNotes = notes.split("\n").filter((l) => !/^(Stage|Resume file): /.test(l)).join("\n");
+    return {
+      status: a.status,
+      values: [a.company, a.title, a.location || "", a.applied_at ? a.applied_at.slice(0, 10) : "", a.source_url || "",
+        c ? [c.name, c.title].filter(Boolean).join(", ") : "", email || "", STATUS_LABEL[a.status] || a.status, "",
+        iv ? iv.scheduled_at.slice(0, 10) : "", "", plainNotes, resume, stage, a.fit_score == null ? "" : a.fit_score],
+    };
+  });
+}
+
+async function exportTracker(db, { candidate_id, outDir, now }) {
+  const ExcelJS = require("exceljs");
+  const wb = new ExcelJS.Workbook();
+  const ws = wb.addWorksheet("Tracker");
+  ws.addRow(["Job Application Tracker"]);
+  ws.addRow([]);
+  const header = ws.addRow(COLUMNS);
+  header.font = { bold: true };
+  for (const r of rowsFor(db, candidate_id)) {
+    const row = ws.addRow(r.values);
+    const fill = FILL[r.status];
+    if (fill) row.eachCell({ includeEmpty: true }, (cell) => { cell.fill = { type: "pattern", pattern: "solid", fgColor: { argb: fill } }; });
+  }
+  ws.columns.forEach((col, i) => { col.width = i === 11 ? 60 : 22; });
+  const stamp = String(now).replace(/[-:]/g, "").slice(0, 13).replace("T", "-");
+  const file = path.join(outDir, `tracker-${stamp}.xlsx`);
+  await wb.xlsx.writeFile(file);
+  return { file, rows: ws.rowCount - 3 };
+}
+
+module.exports = { exportTracker, rowsFor, COLUMNS, FILL };

package/store/home.js

@@ -0,0 +1,36 @@
+"use strict";
+
+/**
+ * Where the store lives. GAFJ_HOME overrides; otherwise the OS app-data
+ * folder. Never Documents: sync clients corrupt a live SQLite file, so a
+ * home under a known sync folder produces a warning the CLI prints.
+ */
+
+const os = require("os");
+const path = require("path");
+const fs = require("fs");
+
+const SYNC_FOLDER_MARKERS = ["OneDrive", "Dropbox", "Google Drive", "GoogleDrive", "iCloud", "Box"];
+
+function defaultHome(env, platform) {
+  if (platform === "win32") {
+    return path.join(env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), "GAFJ");
+  }
+  if (platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support", "GAFJ");
+  }
+  return path.join(env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share"), "gafj");
+}
+
+function syncWarning(dir) {
+  const hit = SYNC_FOLDER_MARKERS.find((m) => dir.split(/[\\/]/).some((seg) => seg.toLowerCase() === m.toLowerCase()));
+  return hit ? `${dir} is under ${hit}; a synced folder can corrupt a live SQLite file. Set GAFJ_HOME elsewhere.` : null;
+}
+
+function resolveHome(env = process.env, platform = process.platform, { create = true } = {}) {
+  const dir = env.GAFJ_HOME ? path.resolve(env.GAFJ_HOME) : defaultHome(env, platform);
+  if (create) fs.mkdirSync(dir, { recursive: true });
+  return { dir, warning: syncWarning(dir) };
+}
+
+module.exports = { resolveHome, defaultHome, syncWarning };

package/store/import_kb.js

@@ -0,0 +1,88 @@
+"use strict";
+
+/**
+ * Loads accomplishment rows into the store. Idempotent by id: a re-import
+ * refreshes wordings and metrics but never demotes a dimension the candidate
+ * has already confirmed. Every record logs one import event.
+ */
+
+const { buildAccomplishmentRows, reviewList } = require("../core/kb_import");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+
+const DIMS = ["metrics_json", "verbs_json", "verbatim_claims_json"];
+const keyOf = { metrics_json: (m) => m.key + "|" + m.outcome_key, verbs_json: (v) => v.verb, verbatim_claims_json: (c) => c.type + "|" + c.text.toLowerCase() };
+
+function mergeConfirmed(existing, incoming) {
+  for (const dim of DIMS) {
+    const prior = new Map((JSON.parse(existing[dim] || "[]")).map((x) => [keyOf[dim](x), x]));
+    for (const item of incoming[dim]) {
+      const p = prior.get(keyOf[dim](item));
+      if (p && p.review_state === "confirmed") item.review_state = "confirmed";
+    }
+  }
+  return incoming;
+}
+
+function ensureCandidate(db, candidate, now) {
+  const row = db.prepare("SELECT id FROM candidate WHERE id = ?").get(candidate.id);
+  if (!row) {
+    db.prepare("INSERT INTO candidate (id, name, contact_json, created_at) VALUES (?, ?, ?, ?)")
+      .run(candidate.id, candidate.name, JSON.stringify(candidate.contact || {}), now);
+  }
+}
+
+/**
+ * @param {object} args { candidate: {id, name}, accomplishments, variations, fixtureTexts, now, actor: {type, ref} }
+ */
+function importKb(db, args) {
+  const { candidate, accomplishments, variations, fixtureTexts = [], now } = args;
+  const actor = args.actor || { type: "import", ref: "kb" };
+  const rows = buildAccomplishmentRows(accomplishments, variations, fixtureTexts);
+  const result = { inserted: 0, updated: 0, review: [] };
+  withTx(db, (d) => {
+    ensureCandidate(d, candidate, now);
+    const get = d.prepare("SELECT * FROM accomplishment WHERE id = ?");
+    const ins = d.prepare(`INSERT INTO accomplishment (id, candidate_id, title, company, role, date_start, date_end, summary,
+      metrics_json, verbatim_claims_json, verbs_json, subjects_json, wordings_json, tags_json, strength_score, source, confirmed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'import', ?)`);
+    const upd = d.prepare(`UPDATE accomplishment SET title = ?, company = ?, role = ?, date_start = ?, date_end = ?, summary = ?,
+      metrics_json = ?, verbatim_claims_json = ?, verbs_json = ?, wordings_json = ?, tags_json = ?, strength_score = ? WHERE id = ?`);
+    for (const r of rows) {
+      const existing = get.get(r.id);
+      const row = existing ? mergeConfirmed(existing, r) : r;
+      const j = (x) => JSON.stringify(x);
+      if (existing) {
+        upd.run(row.title, row.company, row.role, row.date_start, row.date_end, row.summary,
+          j(row.metrics_json), j(row.verbatim_claims_json), j(row.verbs_json), j(row.wordings_json), j(row.tags_json), row.strength_score, row.id);
+        result.updated++;
+      } else {
+        ins.run(row.id, candidate.id, row.title, row.company, row.role, row.date_start, row.date_end, row.summary,
+          j(row.metrics_json), j(row.verbatim_claims_json), j(row.verbs_json), j(row.subjects_json), j(row.wordings_json),
+          j(row.tags_json), row.strength_score, now);
+        result.inserted++;
+      }
+      appendEvent(d, { candidate_id: candidate.id, entity: "accomplishment", entity_id: row.id, event: existing ? "reimported" : "imported",
+        actor_type: actor.type, actor_ref: actor.ref, payload: { metrics: row.metrics_json.length, verbs: row.verbs_json.length }, at: now });
+    }
+    result.review = reviewList(rows.map((r) => {
+      const stored = get.get(r.id);
+      return { ...r, metrics_json: JSON.parse(stored.metrics_json), verbs_json: JSON.parse(stored.verbs_json), verbatim_claims_json: JSON.parse(stored.verbatim_claims_json) };
+    }));
+  });
+  return result;
+}
+
+/** Store the candidate profile (employment skeleton, header, framing notes). Candidate data lives here, never in core/rules. */
+function setProfile(db, { candidate_id, profile, now, actor }) {
+  return withTx(db, (d) => {
+    const prior = d.prepare("SELECT profile_json FROM candidate WHERE id = ?").get(candidate_id);
+    if (!prior) throw new Error("unknown candidate");
+    d.prepare("UPDATE candidate SET profile_json = ? WHERE id = ?").run(JSON.stringify(profile), candidate_id);
+    appendEvent(d, { candidate_id, entity: "candidate", entity_id: candidate_id, event: "profile_set", actor_type: actor.type, actor_ref: actor.ref,
+      payload: { keys: Object.keys(profile) }, prior: { profile_json: prior.profile_json }, at: now });
+    return { ok: true };
+  });
+}
+
+module.exports = { importKb, setProfile };

package/store/import_tracker.js

@@ -0,0 +1,195 @@
+"use strict";
+
+/**
+ * Reads the xlsx tracker and a rounds manifest into postings, applications,
+ * frozen scores, interviews, people, and communications. Idempotent: rows
+ * are keyed by (company, title, applied date); interviews by round label;
+ * people by name; communications by kind and sent_at.
+ *
+ * The rounds manifest holds what the tracker keeps only as prose:
+ *   { "rounds": [ { "company", "title", "round_label", "scheduled_at", "tz", "format", "status",
+ *                   "completed_at", "outcome", "people": [ { "name", "title", "org", "email" } ] } ],
+ *     "people": [ { "company", "title", "name", "title_text", "org", "role", "email", "intel" } ],
+ *     "communications": [ { "company", "title", "kind", "sent_at", "to", "round_label", "note" } ],
+ *     "overrides": [ { "company", "title", "status", "decision_expected_at", "taken_down_at", "posting_text_file" } ] }
+ */
+
+const fs = require("fs");
+const crypto = require("crypto");
+const { mapHeaders, mapRow, naturalKey } = require("../core/tracker_map");
+const { ulid } = require("../core/ulid");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+const { assertIanaZone } = require("./tz");
+
+const ENGINE_VERSION = "tracker-import-1";
+
+async function readTracker(file) {
+  const ExcelJS = require("exceljs");
+  const wb = new ExcelJS.Workbook();
+  await wb.xlsx.readFile(file);
+  const ws = wb.worksheets[0];
+  let cols = null;
+  const rows = [];
+  ws.eachRow((row, n) => {
+    const cells = {};
+    let fill = null;
+    row.eachCell({ includeEmpty: false }, (cell) => {
+      const col = cell.address.replace(/\d+/g, "");
+      let v = cell.value;
+      if (v && typeof v === "object" && "richText" in v) v = v.richText.map((t) => t.text).join("");
+      if (v && typeof v === "object" && "text" in v) v = v.text;
+      if (v && typeof v === "object" && "result" in v) v = v.result;
+      cells[col] = v instanceof Date ? v.toISOString().slice(0, 10) : v;
+      if (!fill && cell.fill && cell.fill.fgColor && cell.fill.fgColor.argb && cell.fill.pattern === "solid") fill = cell.fill.fgColor.argb;
+    });
+    if (!cols) {
+      const m = mapHeaders(cells);
+      if (m.company && m.title && m.status) cols = m;
+      return;
+    }
+    rows.push({ n, cells, fill });
+  });
+  if (!cols) throw new Error("no header row with Company, Role / Title, and Status found");
+  return { cols, rows };
+}
+
+function sha(text) {
+  return crypto.createHash("sha256").update(text).digest("hex");
+}
+
+function stubPosting(r) {
+  return `Posting text not captured for ${r.company}, ${r.title}. Source: ${r.source_text || "tracker"}.`;
+}
+
+function findRow(rows, ref) {
+  const hit = rows.find((r) => r.company.toLowerCase() === ref.company.toLowerCase() && r.title.toLowerCase() === ref.title.toLowerCase());
+  if (!hit) throw new Error(`manifest refers to ${ref.company} / ${ref.title}, which is not in the tracker`);
+  return hit;
+}
+
+function upsertPerson(d, candidateId, p, now) {
+  const existing = d.prepare("SELECT id FROM person WHERE candidate_id = ? AND lower(name) = lower(?) AND merged_into_id IS NULL").get(candidateId, p.name);
+  const links = p.email ? [{ kind: "email", value: p.email }] : [];
+  if (existing) {
+    d.prepare("UPDATE person SET title = COALESCE(?, title), org = COALESCE(?, org), intel_text = COALESCE(?, intel_text) WHERE id = ?")
+      .run(p.title_text || p.title || null, p.org || null, p.intel || null, existing.id);
+    return existing.id;
+  }
+  const id = ulid(Date.parse(now));
+  d.prepare("INSERT INTO person (id, candidate_id, name, title, org, intel_text, links_json, first_seen_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
+    .run(id, candidateId, p.name, p.title_text || p.title || null, p.org || null, p.intel || null, JSON.stringify(links), now);
+  return id;
+}
+
+/**
+ * @param {object} args { candidate_id, tracker: {cols, rows}, manifest, postingTexts: {[file]: text}, now, actor }
+ */
+function importTracker(db, args) {
+  const { candidate_id, tracker, manifest = {}, postingTexts = {}, now } = args;
+  const actor = args.actor || { type: "import", ref: "tracker" };
+  const mapped = tracker.rows.map((r) => ({ ...mapRow(r, tracker.cols), n: r.n })).filter(Boolean);
+  const result = { postings: 0, applications: 0, interviews: 0, people: 0, communications: 0, warnings: [], skipped: [] };
+  const overrides = new Map((manifest.overrides || []).map((o) => [o.company.toLowerCase() + "|" + o.title.toLowerCase(), o]));
+
+  withTx(db, (d) => {
+    const appByKey = new Map();
+    for (const r of mapped) {
+      for (const w of r.warnings) result.warnings.push(`row ${r.n}: ${w}`);
+      const ov = overrides.get(r.company.toLowerCase() + "|" + r.title.toLowerCase()) || {};
+      const rawText = ov.posting_text_file && postingTexts[ov.posting_text_file] ? postingTexts[ov.posting_text_file] : stubPosting(r);
+      const hash = sha(rawText);
+      let posting = d.prepare("SELECT id FROM posting WHERE candidate_id = ? AND company = ? AND title = ? AND content_hash = ?")
+        .get(candidate_id, r.company, r.title, hash);
+      if (!posting) {
+        const id = ulid(Date.parse(now));
+        d.prepare(`INSERT INTO posting (id, candidate_id, company, title, raw_text, content_hash, status, source_url, comp_text, location, captured_at, taken_down_at)
+                   VALUES (?, ?, ?, ?, ?, ?, 'accepted', ?, ?, ?, ?, ?)`)
+          .run(id, candidate_id, r.company, r.title, rawText, hash, r.source_url, ov.comp_text || null, r.location, r.applied_at ? r.applied_at + "T00:00:00Z" : now, ov.taken_down_at || null);
+        posting = { id };
+        result.postings++;
+        appendEvent(d, { candidate_id, entity: "posting", entity_id: id, event: "imported", actor_type: actor.type, actor_ref: actor.ref, payload: { row: r.n }, at: now });
+      }
+      let scoring = d.prepare("SELECT id FROM scoring WHERE posting_id = ? AND status = 'frozen' ORDER BY scored_at DESC LIMIT 1").get(posting.id);
+      if (!scoring && r.fit != null) {
+        const id = ulid(Date.parse(now));
+        d.prepare(`INSERT INTO scoring (id, posting_id, categories_json, status, fit_score, verdict, verdict_reason, engine_version, rubric_version, kb_revision, scoring_evidence_hash, scored_at)
+                   VALUES (?, ?, '[]', 'frozen', ?, ?, ?, ?, 'tracker', 0, ?, ?)`)
+          .run(id, posting.id, r.fit, ["pass", "rejected", "closed"].includes(r.status) && r.fit < 5 ? "pass" : "pursue",
+            r.stage || null, ENGINE_VERSION, sha("tracker:" + r.fit), now);
+        scoring = { id };
+      }
+      const status = ov.status || r.status;
+      let app = d.prepare("SELECT id, status FROM application WHERE posting_id = ?").get(posting.id);
+      if (!app) {
+        const id = ulid(Date.parse(now));
+        d.prepare(`INSERT INTO application (id, posting_id, status, applied_at, scoring_id, decision_expected_at, notes)
+                   VALUES (?, ?, ?, ?, ?, ?, ?)`)
+          .run(id, posting.id, status, r.applied_at ? r.applied_at + "T00:00:00Z" : null, scoring ? scoring.id : null, ov.decision_expected_at || null,
+            [r.notes, r.stage && `Stage: ${r.stage}`, r.resume_file && `Resume file: ${r.resume_file}`].filter(Boolean).join("\n"));
+        app = { id, status };
+        result.applications++;
+        appendEvent(d, { candidate_id, entity: "application", entity_id: id, event: "imported", actor_type: actor.type, actor_ref: actor.ref, payload: { status, row: r.n }, at: now });
+      } else if (app.status !== status) {
+        d.prepare("UPDATE application SET status = ?, decision_expected_at = COALESCE(?, decision_expected_at) WHERE id = ?").run(status, ov.decision_expected_at || null, app.id);
+        appendEvent(d, { candidate_id, entity: "application", entity_id: app.id, event: "status", actor_type: actor.type, actor_ref: actor.ref,
+          payload: { status }, prior: { status: app.status }, at: now });
+      }
+      appByKey.set(naturalKey(r), { app: app.id, posting: posting.id, row: r });
+      if (r.contact && !manifest.people) result.warnings.push(`row ${r.n}: contact "${r.contact}" not imported; list it in the manifest people[]`);
+    }
+
+    const lookup = (ref) => {
+      const r = findRow(mapped, ref);
+      return appByKey.get(naturalKey(r));
+    };
+
+    for (const p of manifest.people || []) {
+      const { app } = lookup(p);
+      const before = d.prepare("SELECT count(*) c FROM person").get().c;
+      const pid = upsertPerson(d, candidate_id, p, now);
+      d.prepare("INSERT OR IGNORE INTO application_person (application_id, person_id, role) VALUES (?, ?, ?)").run(app, pid, p.role || "other");
+      if (d.prepare("SELECT count(*) c FROM person").get().c > before) result.people++;
+    }
+
+    for (const iv of manifest.rounds || []) {
+      const { app } = lookup(iv);
+      assertIanaZone(iv.tz);
+      let row = d.prepare("SELECT id FROM interview WHERE application_id = ? AND round_label = ? AND status IN ('scheduled','completed') ORDER BY scheduled_at DESC LIMIT 1")
+        .get(app, iv.round_label);
+      if (!row) {
+        const id = ulid(Date.parse(now));
+        d.prepare(`INSERT INTO interview (id, application_id, round_label, scheduled_at, tz, format, status, completed_at, invite_received_at, outcome)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+          .run(id, app, iv.round_label, iv.scheduled_at, iv.tz, iv.format, iv.status || "scheduled", iv.completed_at || null, iv.invite_received_at || null, iv.outcome || "pending");
+        row = { id };
+        result.interviews++;
+        appendEvent(d, { candidate_id, entity: "interview", entity_id: id, event: "imported", actor_type: actor.type, actor_ref: actor.ref, payload: { round: iv.round_label }, at: now });
+      } else {
+        d.prepare("UPDATE interview SET status = ?, completed_at = COALESCE(?, completed_at), outcome = ? WHERE id = ?")
+          .run(iv.status || "scheduled", iv.completed_at || null, iv.outcome || "pending", row.id);
+      }
+      for (const p of iv.people || []) {
+        const pid = upsertPerson(d, candidate_id, p, now);
+        d.prepare("INSERT OR IGNORE INTO interview_person (interview_id, person_id) VALUES (?, ?)").run(row.id, pid);
+        d.prepare("INSERT OR IGNORE INTO application_person (application_id, person_id, role) VALUES (?, ?, 'interviewer')").run(app, pid);
+      }
+    }
+
+    for (const c of manifest.communications || []) {
+      const { app } = lookup(c);
+      const iv = c.round_label
+        ? d.prepare("SELECT id FROM interview WHERE application_id = ? AND round_label = ? ORDER BY scheduled_at DESC LIMIT 1").get(app, c.round_label)
+        : null;
+      const exists = d.prepare("SELECT id FROM communication WHERE application_id = ? AND kind = ? AND sent_at = ?").get(app, c.kind, c.sent_at);
+      if (exists) continue;
+      const id = ulid(Date.parse(now));
+      d.prepare("INSERT INTO communication (id, application_id, interview_id, kind, to_addr, sent_at, sent_body_text) VALUES (?, ?, ?, ?, ?, ?, ?)")
+        .run(id, app, iv ? iv.id : null, c.kind, c.to || null, c.sent_at, c.note || null);
+      result.communications++;
+    }
+  });
+  return result;
+}
+
+module.exports = { readTracker, importTracker, ENGINE_VERSION };