@gafj/gafj 0.1.1

package/store/ingest.js

@@ -0,0 +1,140 @@
+"use strict";
+
+/**
+ * ingest_document: the only path onto the document table. Resolves the run,
+ * counts the attempt, extracts JSON, validates the schema, runs provenance
+ * and the validators, and writes the document, the attempt, and the events
+ * in one transaction. The fourth attempt writes nothing and returns stop.
+ */
+
+const crypto = require("crypto");
+const { ulid } = require("../core/ulid");
+const { extractJson } = require("../core/extract");
+const { SCHEMAS, SCHEMA_VERSION, KIND_OF, validate, walk } = require("../core/schemas");
+const { checkClaims } = require("../core/provenance");
+const { runAll } = require("../core/validators");
+const { rulesVersion } = require("../core/rules");
+const { buildContext } = require("./context");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+
+const MAX_ATTEMPTS = 3;
+
+function sha(s) {
+  return crypto.createHash("sha256").update(s).digest("hex");
+}
+
+function targetFor(db, op, { interview_id, posting_id }) {
+  if (["resume", "cover", "categories"].includes(op)) {
+    if (!posting_id) throw new Error(`${op} needs a posting_id`);
+    const p = db.prepare("SELECT id, candidate_id, status FROM posting WHERE id = ?").get(posting_id);
+    if (!p) throw new Error("unknown posting");
+    if (p.status !== "accepted") throw new Error("posting is not accepted");
+    return { candidate_id: p.candidate_id, posting_id, interview_id: null, application_id: null };
+  }
+  if (!interview_id) throw new Error(`${op} needs an interview_id`);
+  const iv = db.prepare(`SELECT i.id, i.application_id, p.candidate_id FROM interview i JOIN application a ON a.id = i.application_id
+    JOIN posting p ON p.id = a.posting_id WHERE i.id = ?`).get(interview_id);
+  if (!iv) throw new Error("unknown interview");
+  return { candidate_id: iv.candidate_id, posting_id: null, interview_id, application_id: iv.application_id };
+}
+
+/** Find or create the run this ingest belongs to. Never guesses from "latest pending". */
+function resolveRun(db, args, now) {
+  if (args.run_id) {
+    const run = db.prepare("SELECT * FROM ai_run WHERE id = ?").get(args.run_id);
+    if (!run) throw new Error("unknown run_id");
+    return run;
+  }
+  const t = targetFor(db, args.op, args);
+  const id = ulid(Date.parse(now));
+  db.prepare(`INSERT INTO ai_run (id, candidate_id, route, operation, interview_id, posting_id, rules_version, schema_version, packet_version, kb_revision, packet_hash, kb_ids_json, started_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'none', ?, 'manual', '[]', ?)`)
+    .run(id, t.candidate_id, args.route || "manual", args.op, t.interview_id, t.posting_id, rulesVersion(), SCHEMA_VERSION,
+      db.prepare("SELECT kb_revision FROM candidate WHERE id = ?").get(t.candidate_id).kb_revision, now);
+  return db.prepare("SELECT * FROM ai_run WHERE id = ?").get(id);
+}
+
+function resumeParts(content) {
+  return {
+    highlights: (content.careerHighlights || []).map((h) => `${h.leadIn} ${h.proof && h.proof.text || ""}`),
+    bullets: (content.experience || []).flatMap((e) => (e.bullets || []).map((b) => b.text && b.text.text || "")),
+  };
+}
+
+/**
+ * @param {object} args { run_id? | op + interview_id|posting_id, content (text or object), route, actor:{type,ref}, now, provider?, model?, tokens_in?, tokens_out?, latency_ms? }
+ */
+function ingestDocument(db, args) {
+  const now = args.now;
+  const actor = args.actor || { type: "system", ref: "ingest" };
+  return withTx(db, (d) => {
+    const run = resolveRun(d, args, now);
+    const op = run.operation;
+    const kind = KIND_OF[op];
+    if (!kind) throw new Error(`operation ${op} does not produce a document`);
+    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, blocks: [{ rule: "attempts", path: "$", span: "", hint: "three attempts used; hand this to the user" }], warnings: [] };
+    }
+    const attemptNo = attempts + 1;
+    const startedAt = now;
+    const blocks = [];
+    const warnings = [];
+    let content = null;
+    const ex = extractJson(args.content);
+    if (ex.error) blocks.push({ rule: "schema", path: "$", span: "", hint: ex.error });
+    else {
+      content = ex.value;
+      for (const e of validate(content, SCHEMAS[op])) blocks.push({ rule: "schema", path: e.path, span: "", hint: e.message });
+    }
+    let provenance = {};
+    if (!blocks.length) {
+      const ctx = buildContext(d, { candidate_id: run.candidate_id, kind, mode: "ingest", application_id: run.interview_id
+        ? d.prepare("SELECT application_id FROM interview WHERE id = ?").get(run.interview_id).application_id : null,
+        kb_ids: JSON.parse(run.kb_ids_json || "[]") });
+      if (kind === "resume") ctx.resume = resumeParts(content);
+      const fields = walk(content, SCHEMAS[op]);
+      const prov = checkClaims(fields, ctx);
+      blocks.push(...prov.blocks);
+      warnings.push(...prov.warnings);
+      const v = runAll(fields, ctx);
+      blocks.push(...v.blocks);
+      warnings.push(...v.warnings);
+      for (const f of fields) if (f.claimed && f.claims.length) provenance[f.path] = f.claims.filter((c) => c.source_id).map((c) => c.source_id);
+    }
+    const status = blocks.length ? "blocked" : "passed";
+    const attemptId = ulid(Date.parse(now) + attemptNo);
+    const outputHash = content ? sha(JSON.stringify(content)) : null;
+    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, args.provider || null, args.model || null, args.tokens_in ?? null, args.tokens_out ?? null, args.latency_ms ?? null,
+        outputHash, status, blocks.length ? blocks[0].rule : null, startedAt, now);
+    let document_id = null;
+    if (content) {
+      document_id = ulid(Date.parse(now) + 10 + attemptNo);
+      const applicationId = kind === "email" ? d.prepare("SELECT application_id FROM interview WHERE id = ?").get(run.interview_id).application_id : null;
+      d.prepare(`INSERT INTO document (id, candidate_id, kind, posting_id, application_id, interview_id, content_json, provenance_json, gate_result_json, status, warnings_json, route, rules_version, schema_version, ai_attempt_id, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(document_id, run.candidate_id, kind, run.posting_id, applicationId, kind === "email" ? run.interview_id : (run.interview_id || null),
+          JSON.stringify(content), JSON.stringify(provenance), JSON.stringify({ status: status === "passed" ? "PASS" : "BLOCKED", blocks }), status,
+          JSON.stringify(warnings), args.route || run.route || "manual", run.rules_version, run.schema_version, attemptId, now);
+    }
+    const final = status === "passed" ? "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: "document", entity_id: document_id || run.id, event: status === "passed" ? "ingested" : "blocked",
+      actor_type: actor.type, actor_ref: actor.ref, payload: { run_id: run.id, attempt: attemptNo, kind, blocks: blocks.length, warnings: warnings.length }, at: now });
+    return { run_id: run.id, document_id, status, attempt: attemptNo, stop: attemptNo >= MAX_ATTEMPTS && status !== "passed", blocks, warnings };
+  });
+}
+
+/** Lint mode: plain text through the validators with no provenance, for calibration and for pasted drafts. */
+function lintText(db, { candidate_id, kind, text, application_id, include_review = false }) {
+  const { lintFields } = require("../core/validators");
+  const ctx = buildContext(db, { candidate_id, kind, mode: "lint", application_id });
+  ctx.include_review = include_review;
+  const fields = lintFields(text);
+  return runAll(fields, ctx);
+}
+
+module.exports = { ingestDocument, lintText, MAX_ATTEMPTS, targetFor };

package/store/kb.js

@@ -0,0 +1,202 @@
+"use strict";
+
+/**
+ * Knowledge base writes the human owns (screen 5): answer a gap, confirm or
+ * dismiss a pending accomplishment, and the summaries the screen reads.
+ * Confirming a pending row is the only path that creates an accomplishment
+ * after import; every dimension on it lands confirmed because the human
+ * just reviewed each one, and kb_revision bumps.
+ */
+
+const { ulid } = require("../core/ulid");
+const { normalizeMetrics, extractClaims, extractVerbs } = require("../core/kb_import");
+const { tier } = require("../core/verbs");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+const { TransitionError, NotFound } = require("./transitions");
+
+const slug = (s) => String(s || "").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "").slice(0, 60) || "record";
+
+function summary(db, candidate_id) {
+  return {
+    confirmed: db.prepare("SELECT count(*) c FROM accomplishment WHERE candidate_id = ?").get(candidate_id).c,
+    gaps: db.prepare("SELECT count(*) c FROM kb_gap WHERE candidate_id = ? AND resolved_at IS NULL").get(candidate_id).c,
+    pending: db.prepare("SELECT count(*) c FROM pending_accomplishment WHERE candidate_id = ?").get(candidate_id).c,
+    kb_revision: db.prepare("SELECT kb_revision FROM candidate WHERE id = ?").get(candidate_id).kb_revision,
+  };
+}
+
+function listGaps(db, candidate_id, { open = true } = {}) {
+  return db.prepare(`SELECT g.id AS gap_id, g.posting_id, g.requirement_text, g.question, g.created_at, g.resolved_at, p.company, p.title
+    FROM kb_gap g JOIN posting p ON p.id = g.posting_id WHERE g.candidate_id = ? ${open ? "AND g.resolved_at IS NULL" : ""} ORDER BY g.created_at DESC`).all(candidate_id);
+}
+
+function listPending(db, candidate_id) {
+  return db.prepare("SELECT id AS pending_id, draft_json, source, gap_id, dedup_group_id, proposed_at FROM pending_accomplishment WHERE candidate_id = ? ORDER BY proposed_at DESC").all(candidate_id)
+    .map((r) => ({ ...r, draft: JSON.parse(r.draft_json), draft_json: undefined }));
+}
+
+function cleanDraft(draft) {
+  if (!draft || typeof draft !== "object") throw new TransitionError("draft is required");
+  const need = (k, max) => { const v = String(draft[k] || "").trim(); if (!v) throw new TransitionError(`draft.${k} is required`); return v.slice(0, max); };
+  return {
+    ...(draft.replaces ? { replaces: String(draft.replaces).slice(0, 80) } : {}),
+    ...(draft.tenure ? { tenure: String(draft.tenure).trim().slice(0, 80) } : {}),
+    title: need("title", 200), company: need("company", 200), role: need("role", 200),
+    dates: String(draft.dates || "").slice(0, 60), summary: String(draft.summary || "").slice(0, 1200),
+    metrics: (Array.isArray(draft.metrics) ? draft.metrics : []).map((m) => String(m).trim()).filter(Boolean).slice(0, 12),
+    verbs: (Array.isArray(draft.verbs) ? draft.verbs : []).map((v) => String(v).trim().toLowerCase()).filter(Boolean).slice(0, 8),
+    wordings: (Array.isArray(draft.wordings) ? draft.wordings : []).map((w) => String(w).trim()).filter(Boolean).slice(0, 6),
+    tags: (Array.isArray(draft.tags) ? draft.tags : []).map((t) => String(t).trim()).filter(Boolean).slice(0, 10),
+  };
+}
+
+/** The candidate answers a gap in their own words: a pending row linked to the gap, the gap resolved. */
+function answerGap(db, { candidate_id, gap_id, draft, now, actor }) {
+  const clean = cleanDraft(draft);
+  return withTx(db, (d) => {
+    const g = d.prepare("SELECT * FROM kb_gap WHERE id = ? AND candidate_id = ?").get(gap_id, candidate_id);
+    if (!g) throw new NotFound("gap");
+    if (g.resolved_at) throw new TransitionError("this gap is already answered");
+    const id = ulid(Date.parse(now));
+    d.prepare("INSERT INTO pending_accomplishment (id, candidate_id, draft_json, source, gap_id, proposed_at) VALUES (?, ?, ?, 'gap_answer', ?, ?)").run(id, candidate_id, JSON.stringify(clean), g.id, now);
+    d.prepare("UPDATE kb_gap SET resolved_at = ? WHERE id = ?").run(now, g.id);
+    appendEvent(d, { candidate_id, entity: "kb_gap", entity_id: g.id, event: "answered", actor_type: actor.type, actor_ref: actor.ref, payload: { pending_id: id }, at: now });
+    return { pending_id: id, gap_id: g.id };
+  });
+}
+
+/** A record the candidate writes by hand lands pending too; nothing skips the confirm step. */
+function proposeManual(db, { candidate_id, draft, now, actor }) {
+  const clean = cleanDraft(draft);
+  return withTx(db, (d) => {
+    const id = ulid(Date.parse(now));
+    d.prepare("INSERT INTO pending_accomplishment (id, candidate_id, draft_json, source, proposed_at) VALUES (?, ?, ?, 'manual', ?)").run(id, candidate_id, JSON.stringify(clean), now);
+    appendEvent(d, { candidate_id, entity: "pending_accomplishment", entity_id: id, event: "proposed", actor_type: actor.type, actor_ref: actor.ref, payload: { title: clean.title }, at: now });
+    return { pending_id: id };
+  });
+}
+
+function dismissPending(db, { candidate_id, pending_id, now, actor }) {
+  return withTx(db, (d) => {
+    const p = d.prepare("SELECT id FROM pending_accomplishment WHERE id = ? AND candidate_id = ?").get(pending_id, candidate_id);
+    if (!p) throw new NotFound("pending row");
+    d.prepare("DELETE FROM pending_accomplishment WHERE id = ?").run(p.id);
+    appendEvent(d, { candidate_id, entity: "pending_accomplishment", entity_id: p.id, event: "dismissed", actor_type: actor.type, actor_ref: actor.ref, at: now });
+    return { pending_id: p.id, dismissed: true };
+  });
+}
+
+/**
+ * Confirm: the reviewed draft (edits applied) becomes an accomplishment with
+ * every dimension confirmed, the pending row is deleted, kb_revision bumps.
+ * A draft that answers a hole carries replaces: the existing record gains
+ * the new metrics, verbs, and wordings as confirmed dimensions instead of a
+ * second record with the same title appearing beside it.
+ */
+function confirmPending(db, { candidate_id, pending_id, edits, now, actor }) {
+  return withTx(db, (d) => {
+    const p = d.prepare("SELECT * FROM pending_accomplishment WHERE id = ? AND candidate_id = ?").get(pending_id, candidate_id);
+    if (!p) throw new NotFound("pending row");
+    const draft = cleanDraft({ ...JSON.parse(p.draft_json), ...(edits || {}) });
+    if (draft.replaces) return extendRecord(d, { candidate_id, pending: p, draft, now, actor });
+    const base = `acc-${slug(draft.company).slice(0, 12)}-${slug(draft.title).slice(0, 24)}`;
+    let id = base;
+    for (let n = 2; d.prepare("SELECT 1 FROM accomplishment WHERE id = ?").get(id); n++) id = `${base}-${n}`;
+    const wordings = draft.wordings.map((text, i) => ({ id: `${id}-w${i + 1}`, text, recommended: i === 0, score: 0 }));
+    const outcome = { key: slug(draft.title), text: draft.title };
+    const metrics = normalizeMetrics(draft.metrics.map((value) => ({ value })), outcome).map((m) => ({ ...m, review_state: "confirmed" }));
+    const claims = extractClaims(wordings).map((c) => ({ ...c, review_state: "confirmed" }));
+    if (draft.tenure) claims.push({ text: draft.tenure, type: "tenure", source_variation_ids: [], review_state: "confirmed" });
+    const verbSet = new Map(extractVerbs(wordings).map((v) => [v.verb, { ...v, review_state: "confirmed" }]));
+    for (const v of draft.verbs) if (!verbSet.has(v)) verbSet.set(v, { verb: v, tier: tier(v), source_variation_ids: [], review_state: "confirmed" });
+    const [ds, de] = draft.dates.split(/\s+(?:to|-|–)\s+/).map((x) => x && x.trim());
+    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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, '[]', ?, ?, NULL, 'confirmed_pending', ?)`)
+      .run(id, candidate_id, draft.title, draft.company, draft.role, ds || null, de || null, draft.summary || null, JSON.stringify(metrics), JSON.stringify(claims), JSON.stringify([...verbSet.values()]), JSON.stringify(wordings), JSON.stringify(draft.tags), now);
+    d.prepare("DELETE FROM pending_accomplishment WHERE id = ?").run(p.id);
+    d.prepare("UPDATE candidate SET kb_revision = kb_revision + 1 WHERE id = ?").run(candidate_id);
+    appendEvent(d, { candidate_id, entity: "accomplishment", entity_id: id, event: "confirmed", actor_type: actor.type, actor_ref: actor.ref, payload: { pending_id: p.id, source: p.source, metrics: metrics.length, verbs: verbSet.size }, at: now });
+    return { accomplishment_id: id, metrics: metrics.length, verbs: verbSet.size };
+  });
+}
+
+/** The replaces path of confirmPending: merge the answered dimensions onto the existing record. */
+function extendRecord(d, { candidate_id, pending, draft, now, actor }) {
+  const a = d.prepare("SELECT * FROM accomplishment WHERE id = ? AND candidate_id = ?").get(draft.replaces, candidate_id);
+  if (!a) throw new NotFound("the record this answer extends");
+  const metrics = JSON.parse(a.metrics_json || "[]");
+  const outcome = { key: slug(a.title), text: a.title };
+  const have = new Set(metrics.map((m) => String(m.value)));
+  const added = normalizeMetrics(draft.metrics.filter((v) => !have.has(v)).map((value) => ({ value })), outcome).map((m) => ({ ...m, review_state: "confirmed" }));
+  const wordings = JSON.parse(a.wordings_json || "[]");
+  const haveW = new Set(wordings.map((w) => w.text));
+  const newW = draft.wordings.filter((t) => !haveW.has(t)).map((text, i) => ({ id: `${a.id}-w${wordings.length + i + 1}`, text, recommended: false, score: 0 }));
+  const verbs = JSON.parse(a.verbs_json || "[]");
+  const haveV = new Set(verbs.map((v) => v.verb));
+  const newV = [...extractVerbs(newW).map((v) => ({ ...v, review_state: "confirmed" })), ...draft.verbs.map((verb) => ({ verb, tier: tier(verb), source_variation_ids: [], review_state: "confirmed" }))].filter((v) => !haveV.has(v.verb) && haveV.add(v.verb));
+  const summary = a.summary && a.summary.trim() ? a.summary : (draft.summary || null);
+  const claims = JSON.parse(a.verbatim_claims_json || "[]");
+  const normT = (t) => String(t).toLowerCase().replace(/\s+/g, " ").trim();
+  const newC = extractClaims(newW).map((c) => ({ ...c, review_state: "confirmed" }));
+  if (draft.tenure) newC.push({ text: draft.tenure, type: "tenure", source_variation_ids: [], review_state: "confirmed" });
+  const haveC = new Set(claims.map((c) => c.type + ":" + normT(c.text)));
+  const addedC = newC.filter((c) => !haveC.has(c.type + ":" + normT(c.text)) && haveC.add(c.type + ":" + normT(c.text)));
+  d.prepare("UPDATE accomplishment SET metrics_json = ?, wordings_json = ?, verbs_json = ?, verbatim_claims_json = ?, summary = ? WHERE id = ?")
+    .run(JSON.stringify([...metrics, ...added]), JSON.stringify([...wordings, ...newW]), JSON.stringify([...verbs, ...newV]), JSON.stringify([...claims, ...addedC]), summary, a.id);
+  d.prepare("DELETE FROM pending_accomplishment WHERE id = ?").run(pending.id);
+  d.prepare("UPDATE candidate SET kb_revision = kb_revision + 1 WHERE id = ?").run(candidate_id);
+  appendEvent(d, { candidate_id, entity: "accomplishment", entity_id: a.id, event: "extended", actor_type: actor.type, actor_ref: actor.ref, payload: { pending_id: pending.id, source: pending.source, metrics: added.length, verbs: newV.length, wordings: newW.length, claims: addedC.length }, at: now });
+  return { accomplishment_id: a.id, extended: true, metrics: added.length, verbs: newV.length, wordings: newW.length, claims: addedC.length };
+}
+
+// ----- holes (plan section U): the questions the records themselves raise -----
+
+const SCOPE = /\b(?:team of \d+|\d[\d,.]*\s*(?:\+|plus)?\s*(?:person|people|members?|teams?|direct reports?|reports|staff|employees|associates|drivers|sites?|locations?|warehouses?|stores?|facilities|countries|regions?|markets?|fte)s?\b|p&l|budget)/i;
+
+/**
+ * A hole is a record with no confirmed figure, or a record whose confirmed
+ * ownership verb is on the top tier with no scope figure anywhere on it.
+ * Each carries the question to ask and a prefilled draft that, confirmed,
+ * extends that record rather than adding a twin. Computed on read; nothing
+ * is stored until the candidate answers.
+ */
+function listHoles(db, candidate_id, { limit = 20, now = new Date().toISOString() } = {}) {
+  const rows = db.prepare("SELECT id, title, company, role, date_start, date_end, summary, metrics_json, verbs_json, wordings_json, verbatim_claims_json FROM accomplishment WHERE candidate_id = ? ORDER BY confirmed_at DESC, id").all(candidate_id);
+  const holes = [];
+  // tenure: the dates add up to something the resume is not allowed to say until the candidate claims it in words
+  const year = (s) => { const m = String(s || "").match(/^(\d{4})/); return m ? Number(m[1]) : null; };
+  const starts = rows.map((a) => year(a.date_start)).filter(Boolean);
+  const ends = rows.map((a) => (a.date_end && !/present|current|now/i.test(a.date_end) ? year(a.date_end) : year(now))).filter(Boolean);
+  const hasTenure = rows.some((a) => JSON.parse(a.verbatim_claims_json || "[]").some((c) => c.type === "tenure" && c.review_state === "confirmed"));
+  if (starts.length && !hasTenure) {
+    const span = Math.max(...ends) - Math.min(...starts);
+    if (span >= 2) {
+      const anchor = rows.find((a) => year(a.date_start) === Math.min(...starts)) || rows[0];
+      holes.push({ accomplishment_id: anchor.id, title: anchor.title, company: anchor.company, role: anchor.role, dates: [anchor.date_start, anchor.date_end].filter(Boolean).join(" to "), hole_id: `${anchor.id}:tenure`, kind: "tenure", years: span,
+        question: `Your dates add up to about ${span} years. The resume is not allowed to say "${span}+ years" until you claim it in your own words. If you want it, put the exact phrase you would put on a resume in the tenure box, for example "${span}+ years in fulfillment". Leave it blank and the dates speak for themselves.`,
+        draft: { replaces: anchor.id, title: anchor.title, company: anchor.company, role: anchor.role, dates: [anchor.date_start, anchor.date_end].filter(Boolean).join(" to "), summary: "", metrics: [], verbs: [], wordings: [], tags: [], tenure: `${span}+ years` } });
+    }
+  }
+  for (const a of rows) {
+    const allMetrics = JSON.parse(a.metrics_json || "[]");
+    const metrics = allMetrics.filter((m) => m.review_state === "confirmed");
+    const waiting = allMetrics.filter((m) => m.review_state !== "confirmed").map((m) => m.value);
+    const verbs = JSON.parse(a.verbs_json || "[]").filter((v) => v.review_state === "confirmed");
+    const wordings = JSON.parse(a.wordings_json || "[]").map((w) => w.text);
+    const dates = [a.date_start, a.date_end].filter(Boolean).join(" to ");
+    const draft = { replaces: a.id, title: a.title, company: a.company, role: a.role, dates, summary: "", metrics: [], verbs: [], wordings: [], tags: [] };
+    const base = { accomplishment_id: a.id, title: a.title, company: a.company, role: a.role, dates };
+    if (!metrics.length) holes.push({ ...base, hole_id: `${a.id}:no_metric`, kind: "no_metric", waiting,
+      question: waiting.length
+        ? `No confirmed figure yet. ${waiting.join(", ")} came in with the import and is waiting under Review below: confirm it there if you can stand behind it, or put the number you can in the metrics box.`
+        : `What number moved? A percent, a dollar figure, a count, or time saved. Put it in the metrics box; it lands on this record as a confirmed figure.`, draft });
+    const lead = verbs.find((v) => (v.tier || tier(v.verb)) >= 3);
+    if (lead && !SCOPE.test([a.summary || "", ...wordings, ...metrics.map((m) => String(m.value))].join(" "))) holes.push({ ...base, hole_id: `${a.id}:no_scope`, kind: "no_scope", verb: lead.verb,
+      question: `"${lead.verb}" is an ownership claim with no scope on the record. How big was it: people, sites, dollars? Put the figure in the metrics box (for example "team of 6" or "$2.1M budget").`, draft });
+    if (holes.length >= limit) break;
+  }
+  return holes.slice(0, limit);
+}
+
+module.exports = { summary, listGaps, listPending, answerGap, proposeManual, dismissPending, confirmPending, cleanDraft, listHoles };

package/store/log.js

@@ -0,0 +1,88 @@
+"use strict";
+
+/**
+ * Operational log (plan section O): HOME/logs/gafj.jsonl, one JSON object
+ * per line, and only ever these keys:
+ *
+ *   { ts, level, event, entity, entity_id, actor, ms, status }
+ *
+ * The shape is the guarantee. There is no free-text field, so a request
+ * body, a provider key, an error message carrying either, or the comp
+ * floor cannot reach the file: every value is coerced to a short token
+ * (200 characters) or a number, and unknown keys are dropped. The file
+ * rotates past 10 MB, keeping three older files. Writes are synchronous
+ * appends and never throw: a log that cannot be written is a log that is
+ * skipped, never a request that fails.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const KEYS = ["entity", "entity_id", "actor", "ms", "status"];
+const LEVELS = new Set(["info", "warn", "error"]);
+const MAX_BYTES = 10 * 1024 * 1024;
+const KEEP = 3;
+const FILE = "gafj.jsonl";
+
+function token(v) {
+  if (v === undefined || v === null) return undefined;
+  if (typeof v === "number") return Number.isFinite(v) ? v : undefined;
+  if (typeof v === "boolean") return v;
+  return String(v).replace(/[\r\n\t]/g, " ").slice(0, 200);
+}
+
+class Log {
+  constructor({ dir, maxBytes = MAX_BYTES, now = () => new Date().toISOString(), stderr = false } = {}) {
+    this.dir = dir;
+    this.file = dir ? path.join(dir, FILE) : null;
+    this.maxBytes = maxBytes;
+    this.now = now;
+    this.stderr = stderr;
+    this.size = null;
+  }
+
+  /** Build the line with the whitelisted keys only. Exposed so a test can check the shape without a file. */
+  line(level, event, fields = {}) {
+    const out = { ts: this.now(), level: LEVELS.has(level) ? level : "info", event: token(event) || "event" };
+    for (const k of KEYS) { const v = token(fields[k]); if (v !== undefined) out[k] = v; }
+    return out;
+  }
+
+  write(level, event, fields) {
+    const text = JSON.stringify(this.line(level, event, fields)) + "\n";
+    if (this.stderr) process.stderr.write(text);
+    if (!this.file) return;
+    try {
+      if (this.size === null) this.size = fs.existsSync(this.file) ? fs.statSync(this.file).size : 0;
+      if (this.size + text.length > this.maxBytes) this.rotate();
+      fs.mkdirSync(this.dir, { recursive: true });
+      fs.appendFileSync(this.file, text);
+      this.size += text.length;
+    } catch (_) { /* a log that cannot be written is skipped */ }
+  }
+
+  info(event, fields) { this.write("info", event, fields); }
+  warn(event, fields) { this.write("warn", event, fields); }
+  error(event, fields) { this.write("error", event, fields); }
+
+  /** Rotate when the live file is past the cap (also called once at serve start). Keeps KEEP older files. */
+  rotate(force = false) {
+    if (!this.file) return false;
+    try {
+      if (!fs.existsSync(this.file)) { this.size = 0; return false; }
+      const size = fs.statSync(this.file).size;
+      if (!force && size < this.maxBytes) { this.size = size; return false; }
+      const stamp = this.now().replace(/[:.]/g, "-");
+      fs.renameSync(this.file, path.join(this.dir, `gafj.${stamp}.jsonl`));
+      this.size = 0;
+      const old = fs.readdirSync(this.dir).filter((f) => /^gafj\..+\.jsonl$/.test(f)).sort();
+      for (const f of old.slice(0, Math.max(0, old.length - KEEP))) fs.unlinkSync(path.join(this.dir, f));
+      return true;
+    } catch (_) { return false; }
+  }
+}
+
+/** A log that writes nowhere, for tests and for commands that do not serve. */
+const silent = () => new Log({});
+
+module.exports = { Log, silent, KEYS, MAX_BYTES, KEEP, FILE };

package/store/migrate.js

@@ -0,0 +1,55 @@
+"use strict";
+
+/**
+ * Schema versioning by PRAGMA user_version. Migrations run inside one
+ * BEGIN IMMEDIATE transaction, which is also the migration lock: a second
+ * process opening the same file blocks on busy_timeout until the first
+ * commits, then re-reads user_version and finds nothing to do.
+ * There is no migrate-down. Restore from a backup instead.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const MIGRATIONS = [
+  { version: 1, file: path.join(__dirname, "..", "core", "schema.sql") },
+  { version: 2, file: path.join(__dirname, "..", "core", "migrations", "002-profile.sql") },
+  { version: 3, file: path.join(__dirname, "..", "core", "migrations", "003-discover.sql") },
+];
+
+const CURRENT_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;
+
+function userVersion(db) {
+  return Number(db.prepare("PRAGMA user_version").get().user_version);
+}
+
+/**
+ * The documented SQLite recipe for a migration that rebuilds a table: foreign keys off for the
+ * transaction (the pragma is a no-op inside one, so it is set before BEGIN), foreign_key_check
+ * before COMMIT so a rebuild that orphaned a row fails the whole migration, keys back on after.
+ */
+function migrate(db) {
+  if (userVersion(db) >= CURRENT_VERSION) return userVersion(db);
+  db.exec("PRAGMA foreign_keys = OFF");
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    let v = userVersion(db); // re-read under the lock
+    for (const m of MIGRATIONS) {
+      if (m.version <= v) continue;
+      db.exec(fs.readFileSync(m.file, "utf8"));
+      db.exec(`PRAGMA user_version = ${m.version}`);
+      v = m.version;
+    }
+    const orphans = db.prepare("PRAGMA foreign_key_check").all();
+    if (orphans.length) throw new Error(`migration left ${orphans.length} dangling foreign key rows (${orphans[0].table})`);
+    db.exec("COMMIT");
+    return v;
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  } finally {
+    db.exec("PRAGMA foreign_keys = ON");
+  }
+}
+
+module.exports = { migrate, userVersion, CURRENT_VERSION, MIGRATIONS };