@gafj/gafj 0.1.1

package/mcp/tools.js

@@ -0,0 +1,237 @@
+"use strict";
+
+/**
+ * The tiered tool set (plan, section on tiers). Read tools, one door
+ * (save_document), proposed-row tools through ingest_proposal. Nothing here
+ * confirms, schedules, sends, applies, or changes a setting; those are
+ * human clicks in the UI. Every write carries actor mcp.
+ */
+
+const path = require("path");
+const { z } = require("zod");
+const { snapshot } = require("../store/snapshot");
+const { openRun } = require("../store/packets");
+const { ingestDocument, MAX_ATTEMPTS } = require("../store/ingest");
+const { ingestProposal } = require("../store/proposals");
+const { loadSlice } = require("../store/context");
+const { latestFrozenScoring } = require("../store/packets");
+const { serializeRecord, toScoringShape } = require("../core/generators/serialize");
+const { rankEvidence } = require("../core/scoring");
+const { PacketError } = require("../core/generators/packet");
+const { SliceError } = require("../core/generators/slice");
+
+const PACKET_OPS = ["resume", "cover", "prep", "onepager", "deep_answers", "followup", "practice"];
+const INTERVIEW_OPS = new Set(["prep", "onepager", "deep_answers", "followup", "practice"]);
+
+const text = (o) => ({ content: [{ type: "text", text: typeof o === "string" ? o : JSON.stringify(o, null, 1) }] });
+const fail = (msg, extra) => ({ content: [{ type: "text", text: JSON.stringify({ error: msg, ...(extra || {}) }, null, 1) }], isError: true });
+
+function guarded(fn) {
+  return async (args, ctx) => {
+    try { return await fn(args || {}, ctx); } catch (e) {
+      if (e instanceof PacketError || e instanceof SliceError) return fail(e.message, e.detail ? { detail: e.detail } : undefined);
+      return fail(e.message);
+    }
+  };
+}
+
+const CATEGORY = z.object({ category: z.string(), weight: z.number(), jd_evidence: z.array(z.string()), is_hard_gate: z.boolean().optional() });
+
+/**
+ * @param {object} deps { db, candidate_id, thresholds, exportDir, now: () => iso, actor: (ref) => {type, ref} }
+ */
+function registerTools(server, deps) {
+  const { db, candidate_id } = deps;
+  const now = deps.now || (() => new Date().toISOString());
+  const actor = (ref) => ({ type: "mcp", ref });
+
+  server.registerTool("campaign_snapshot", {
+    title: "Campaign snapshot",
+    description: "The dashboard: what needs the candidate now, upcoming interviews with ids, active and closed applications, aging applications. Read only.",
+    inputSchema: z.object({}),
+  }, guarded(() => text(snapshot(db, { candidate_id, now: now(), thresholds: deps.thresholds }))));
+
+  server.registerTool("list_interviews", {
+    title: "List interviews",
+    description: "Interviews with ids, round, format, status, time and zone, company, and people. Optional ISO bounds. Read only.",
+    inputSchema: z.object({ from: z.string().optional(), to: z.string().optional(), include_completed: z.boolean().optional() }),
+  }, guarded(({ from, to, include_completed }) => {
+    const rows = db.prepare(`SELECT i.id AS interview_id, i.application_id, i.round_label, i.format, i.status, i.scheduled_at, i.tz, i.outcome, i.invite_received_at IS NOT NULL AS invite_received,
+        p.company, p.title, p.id AS posting_id FROM interview i JOIN application a ON a.id = i.application_id JOIN posting p ON p.id = a.posting_id
+        WHERE p.candidate_id = ? AND i.status <> 'superseded' AND (? IS NULL OR i.scheduled_at >= ?) AND (? IS NULL OR i.scheduled_at <= ?) AND (? OR i.status = 'scheduled') ORDER BY i.scheduled_at`)
+      .all(candidate_id, from || null, from || null, to || null, to || null, include_completed ? 1 : 0);
+    const people = db.prepare("SELECT ip.interview_id, pe.id, pe.name, pe.title FROM interview_person ip JOIN person pe ON pe.id = ip.person_id").all();
+    return text(rows.map((r) => ({ ...r, invite_received: !!r.invite_received, people: people.filter((p) => p.interview_id === r.interview_id).map(({ id, name, title }) => ({ person_id: id, name, title })) })));
+  }));
+
+  server.registerTool("list_postings", {
+    title: "List postings",
+    description: "Postings with ids, status (proposed, accepted, archived), whether scoring is frozen, and the application status if any. Read only.",
+    inputSchema: z.object({ status: z.enum(["proposed", "accepted", "archived"]).optional() }),
+  }, guarded(({ status }) => text(db.prepare(`SELECT p.id AS posting_id, p.status, p.company, p.title, p.location, p.comp_text, p.captured_at,
+      (SELECT count(*) FROM scoring s WHERE s.posting_id = p.id AND s.status = 'frozen') > 0 AS scoring_frozen, a.id AS application_id, a.status AS application_status
+      FROM posting p LEFT JOIN application a ON a.posting_id = p.id WHERE p.candidate_id = ? AND (? IS NULL OR p.status = ?) ORDER BY p.captured_at DESC`)
+    .all(candidate_id, status || null, status || null).map((r) => ({ ...r, scoring_frozen: !!r.scoring_frozen })))));
+
+  server.registerTool("get_posting", {
+    title: "Get posting",
+    description: "One posting: status, company, title, location, comp, source, and the text (bounded to 12000 characters). Read only.",
+    inputSchema: z.object({ posting_id: z.string() }),
+  }, guarded(({ posting_id }) => {
+    const p = db.prepare("SELECT id AS posting_id, status, company, title, location, comp_text, source_url, captured_at, taken_down_at, length(raw_text) AS raw_length, substr(raw_text, 1, 12000) AS text FROM posting WHERE id = ? AND candidate_id = ?").get(posting_id, candidate_id);
+    return p ? text(p) : fail("unknown posting");
+  }));
+
+  server.registerTool("get_scoring", {
+    title: "Get scoring",
+    description: "The frozen scoring for a posting (categories, weights, evidence, fit, verdict) and the latest proposal if one is waiting. Read only.",
+    inputSchema: z.object({ posting_id: z.string() }),
+  }, guarded(({ posting_id }) => {
+    const p = db.prepare("SELECT id FROM posting WHERE id = ? AND candidate_id = ?").get(posting_id, candidate_id);
+    if (!p) return fail("unknown posting");
+    const frozen = latestFrozenScoring(db, posting_id);
+    const proposed = db.prepare("SELECT id, categories_json, scored_at FROM scoring WHERE posting_id = ? AND status = 'proposed' ORDER BY scored_at DESC, rowid DESC LIMIT 1").get(posting_id);
+    const strip = (s) => s && { scoring_id: s.id, status: s.status, fit_score: s.fit_score, verdict: s.verdict, verdict_reason: s.verdict_reason, categories: s.categories, scored_at: s.scored_at };
+    return text({ frozen: frozen && frozen.status === "frozen" ? strip(frozen) : null, proposed: proposed ? { scoring_id: proposed.id, categories: JSON.parse(proposed.categories_json), scored_at: proposed.scored_at } : null });
+  }));
+
+  server.registerTool("list_accomplishments", {
+    title: "List accomplishments",
+    description: "Knowledge base records with ids and confirmed dimensions only. With a query, the records ranked by evidence for it. Read only.",
+    inputSchema: z.object({ query: z.string().optional(), limit: z.number().int().min(1).max(100).optional() }),
+  }, guarded(({ query, limit }) => {
+    const records = [...loadSlice(db, candidate_id).values()];
+    let chosen = records;
+    if (query) {
+      const ranked = rankEvidence(query, records.map(toScoringShape), limit || 10);
+      const byId = new Map(records.map((r) => [r.id, r]));
+      chosen = ranked.map((e) => byId.get(e.accomplishmentId));
+    } else if (limit) chosen = records.slice(0, limit);
+    return text(chosen.map((r) => serializeRecord(r)));
+  }));
+
+  server.registerTool("get_person", {
+    title: "Get person",
+    description: "A person by id or by name match, resolved through merges, with the applications and interviews they sit on. Read only.",
+    inputSchema: z.object({ person_id: z.string().optional(), name: z.string().optional() }),
+  }, guarded(({ person_id, name }) => {
+    if (!person_id && !name) return fail("person_id or name is required");
+    let rows = person_id
+      ? db.prepare("SELECT * FROM person WHERE id = ? AND candidate_id = ?").all(person_id, candidate_id)
+      : db.prepare("SELECT * FROM person WHERE candidate_id = ? AND lower(name) LIKE lower(?)").all(candidate_id, "%" + name + "%");
+    rows = rows.map((r) => (r.merged_into_id ? db.prepare("SELECT * FROM person WHERE id = ?").get(r.merged_into_id) : r));
+    return text(rows.map((r) => ({
+      person_id: r.id, name: r.name, title: r.title, org: r.org, intel: r.intel_text, links: JSON.parse(r.links_json || "[]"),
+      applications: db.prepare("SELECT ap.application_id, ap.role, p.company FROM application_person ap JOIN application a ON a.id = ap.application_id JOIN posting p ON p.id = a.posting_id WHERE ap.person_id = ?").all(r.id),
+      interviews: db.prepare("SELECT ip.interview_id, i.round_label, i.scheduled_at FROM interview_person ip JOIN interview i ON i.id = ip.interview_id WHERE ip.person_id = ?").all(r.id),
+    })));
+  }));
+
+  for (const op of PACKET_OPS) {
+    const byInterview = INTERVIEW_OPS.has(op);
+    server.registerTool(`get_${op}_packet`, {
+      title: `${op} packet`,
+      description: `Build the ${op} packet: rules, context, the knowledge base slice with ids, and the output schema. Opens a run and returns run_id; write the document and call save_document with that run_id. ${byInterview ? "Needs an interview_id." : "Needs an accepted posting_id."} Refuses without frozen scoring where scoring applies.`,
+      inputSchema: byInterview ? z.object({ interview_id: z.string() }) : z.object({ posting_id: z.string() }),
+    }, guarded((args) => {
+      const r = openRun(db, { op, interview_id: args.interview_id, posting_id: args.posting_id, route: "mcp", actor: actor(`get_${op}_packet`), now: now() });
+      return text({ run_id: r.run_id, attempts_allowed: MAX_ATTEMPTS, instruction: `Produce JSON matching output_schema, then call save_document with run_id ${r.run_id} and the JSON as content_json. Cite kb_slice ids in claims.`, packet: r.packet });
+    }));
+  }
+
+  server.registerTool("save_document", {
+    title: "Save document",
+    description: "The one door onto the document table. Runs the schema, provenance, and the failure ledger on content_json for the run the packet opened. Blocked returns isError with every block (field path, span, hint, nearest records). Three attempts per run, then stop.",
+    inputSchema: z.object({ run_id: z.string(), content_json: z.union([z.string(), z.record(z.string(), z.unknown())]) }),
+  }, guarded(({ run_id, content_json }) => {
+    const r = ingestDocument(db, { run_id, content: content_json, route: "mcp", actor: actor("save_document"), now: now() });
+    const body = { run_id: r.run_id, status: r.status, attempt: r.attempt, document_id: r.document_id || null, stop: !!r.stop, blocks: r.blocks, warnings: r.warnings };
+    return r.status === "passed" ? text(body) : { ...text(body), isError: true };
+  }));
+
+  server.registerTool("store_posting", {
+    title: "Store posting",
+    description: "Store a posting as proposed (the candidate accepts it in the UI). Idempotent on company, title, and the text hash. Never accepted from here.",
+    inputSchema: z.object({ company: z.string(), title: z.string(), raw_text: z.string(), source_url: z.string().optional(), comp_text: z.string().optional(), location: z.string().optional() }),
+  }, guarded((a) => text(ingestProposal(db, "posting", { candidate_id, ...a, now: now(), actor: actor("store_posting") }))));
+
+  server.registerTool("propose_categories", {
+    title: "Propose scoring categories",
+    description: "Propose Part K categories for a posting: five to eight, weights 1 to 10 from the employer's emphasis, each with one to six verbatim jd_evidence lines from the posting text. Rejected whole if any line is not verbatim. The candidate edits and freezes.",
+    inputSchema: z.object({ posting_id: z.string(), categories: z.array(CATEGORY).min(5).max(8) }),
+  }, guarded((a) => text(ingestProposal(db, "categories", { candidate_id, ...a, now: now(), actor: actor("propose_categories") }))));
+
+  server.registerTool("kb_gap_request", {
+    title: "Request a knowledge base gap answer",
+    description: "Ask the candidate a question about a requirement (verbatim from the posting) the knowledge base cannot answer. Creates a gap the candidate answers later.",
+    inputSchema: z.object({ posting_id: z.string(), requirement_text: z.string(), question: z.string() }),
+  }, guarded((a) => text(ingestProposal(db, "gap", { candidate_id, ...a, now: now(), actor: actor("kb_gap_request") }))));
+
+  server.registerTool("propose_accomplishment", {
+    title: "Propose an accomplishment",
+    description: "Propose a knowledge base record from something the candidate told you. Lands pending; the candidate confirms every metric and verb before it is citable. Twenty open at a time.",
+    inputSchema: z.object({ draft: z.object({ title: z.string(), company: z.string(), role: z.string(), dates: z.string().optional(), summary: z.string().optional(),
+      metrics: z.array(z.string()).optional(), verbs: z.array(z.string()).optional(), wordings: z.array(z.string()).optional() }), gap_id: z.string().optional() }),
+  }, guarded((a) => text(ingestProposal(db, "accomplishment", { candidate_id, ...a, now: now(), actor: actor("propose_accomplishment") }))));
+
+  // onboarding tier: propose_from_source, never the document door
+  const onboarding = require("../store/onboarding");
+  server.registerTool("list_sources", {
+    title: "List source documents",
+    description: "The candidate's uploaded resumes and records for onboarding, with ids and whether text extraction succeeded. Read only.",
+    inputSchema: z.object({}),
+  }, guarded(() => text(onboarding.listSources(db, candidate_id))));
+  server.registerTool("get_extract_packet", {
+    title: "Extraction packet",
+    description: "Build the onboarding extraction packet for one source document: rules, the source text, and the output schema. Every proposed atom must be a verbatim excerpt with its character span. Returns run_id for save_extraction.",
+    inputSchema: z.object({ source_document_id: z.string() }),
+  }, guarded(({ source_document_id }) => {
+    const r = openRun(db, { op: "extract", source_document_id, route: "mcp", actor: actor("get_extract_packet"), now: now() });
+    return text({ run_id: r.run_id, attempts_allowed: MAX_ATTEMPTS, instruction: `Produce JSON matching output_schema with verbatim excerpts and spans, then call save_extraction with run_id ${r.run_id}.`, packet: r.packet });
+  }));
+  server.registerTool("save_extraction", {
+    title: "Save extraction",
+    description: "propose_from_source: the proposed accomplishments land as pending rows the candidate confirms on the knowledge base screen. Rejected whole, with isError, if any atom is not a verbatim excerpt of the source at its span. Three attempts per run.",
+    inputSchema: z.object({ run_id: z.string(), content_json: z.union([z.string(), z.record(z.string(), z.unknown())]) }),
+  }, guarded(({ run_id, content_json }) => {
+    const r = onboarding.saveExtraction(db, { run_id, content: content_json, route: "mcp", actor: actor("save_extraction"), now: now() });
+    return r.status === "passed" ? text(r) : { ...text(r), isError: true };
+  }));
+
+  // discovery tier: questions in, pending answers out; never the document door
+  const discover = require("../store/discover");
+  server.registerTool("get_discover_packet", {
+    title: "Discovery packet",
+    description: "Build the discovery packet: the candidate's confirmed records (thinnest first), the holes the engine sees, and every prior question. Reply with questions only, each tied to a record id in the slice; the candidate answers them on the knowledge base screen. Refused while questions are still open. Returns run_id for save_discovery.",
+    inputSchema: z.object({}),
+  }, guarded(() => {
+    discover.assertCanOpen(db, candidate_id);
+    const r = openRun(db, { op: "discover", candidate_id, route: "mcp", actor: actor("get_discover_packet"), now: now() });
+    return text({ run_id: r.run_id, attempts_allowed: discover.MAX_ATTEMPTS, instruction: `Produce JSON matching output_schema (questions about records in the slice, by id), then call save_discovery with run_id ${r.run_id}.`, packet: r.packet });
+  }));
+  server.registerTool("save_discovery", {
+    title: "Save discovery questions",
+    description: "Stores the questions as open items on the knowledge base screen. Rejected whole, with isError, if the JSON misses the schema or any question names a record outside the packet's slice. Three attempts per run. Never writes to a record.",
+    inputSchema: z.object({ run_id: z.string(), content_json: z.union([z.string(), z.record(z.string(), z.unknown())]) }),
+  }, guarded(({ run_id, content_json }) => {
+    const r = discover.saveDiscovery(db, { run_id, content: content_json, route: "mcp", actor: actor("save_discovery"), now: now() });
+    return r.status === "passed" ? text(r) : { ...text(r), isError: true };
+  }));
+  server.registerTool("list_questions", {
+    title: "List open discovery questions",
+    description: "The discovery questions the candidate has not yet answered or dismissed, each with the record it is about. Read only; answers are written by the candidate.",
+    inputSchema: z.object({}),
+  }, guarded(() => text(discover.listQuestions(db, candidate_id))));
+
+  server.registerTool("export_tracker_xlsx", {
+    title: "Export the tracker",
+    description: "Write a dated tracker xlsx to the export folder and return its path.",
+    inputSchema: z.object({}),
+  }, guarded(async () => {
+    const { exportTracker } = require("../store/export_xlsx");
+    const r = await exportTracker(db, { candidate_id, outDir: deps.exportDir, now: now() });
+    return text({ file: path.resolve(r.file), rows: r.rows });
+  }));
+}
+
+module.exports = { registerTools, PACKET_OPS };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@gafj/gafj",
+  "version": "0.1.1",
+  "description": "GAF-J: a local campaign engine for job search. One SQLite file, one ingest door, your own AI subscription.",
+  "homepage": "https://gaf-j.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MVHProvGrd/resume-generator.git",
+    "directory": "gafj"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "resume",
+    "job-search",
+    "interview",
+    "local-first",
+    "sqlite"
+  ],
+  "license": "UNLICENSED",
+  "bin": {
+    "gafj": "bin/cli.js"
+  },
+  "main": "store/index.js",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "bin",
+    "core",
+    "store",
+    "http",
+    "mcp",
+    "bridge",
+    "ui",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test --no-warnings \"test/*.test.js\"",
+    "test:private": "node --test --no-warnings \"test/private/*.test.js\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "exceljs": "4.4.0",
+    "htm": "3.1.1",
+    "mammoth": "1.12.2",
+    "preact": "10.29.8",
+    "unpdf": "1.8.1",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
+    "jsqr": "1.4.0"
+  },
+  "overrides": {
+    "uuid": "^11.1.1"
+  }
+}

package/store/backup.js

@@ -0,0 +1,63 @@
+"use strict";
+
+/**
+ * Backups use SQLite's online backup API when the runtime exposes it, and
+ * VACUUM INTO otherwise. Never a file copy of a live WAL database. Restore
+ * goes into a fresh home by default; restoring over a live store requires an
+ * explicit flag and takes a backup first. Every restore is verified with
+ * integrity_check and a migration pass.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { open } = require("./db");
+const { migrate } = require("./migrate");
+
+async function backup(db, destFile) {
+  fs.mkdirSync(path.dirname(destFile), { recursive: true });
+  const sqlite = require("node:sqlite");
+  if (typeof sqlite.backup === "function") {
+    await sqlite.backup(db, destFile);
+    return { file: destFile, method: "online-backup" };
+  }
+  db.exec(`VACUUM INTO '${destFile.replace(/'/g, "''")}'`);
+  return { file: destFile, method: "vacuum-into" };
+}
+
+function backupName(now) {
+  return `gafj-${String(now).replace(/[-:]/g, "").slice(0, 13).replace("T", "-")}.db`;
+}
+
+function verify(file) {
+  const db = open(file);
+  try {
+    const check = db.prepare("PRAGMA integrity_check").get();
+    if (check.integrity_check !== "ok") throw new Error(`integrity_check: ${check.integrity_check}`);
+    const version = migrate(db);
+    return { version };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * @param {string} backupFile
+ * @param {string} homeDir      target home; must not already hold a store unless intoLive
+ */
+async function restore(backupFile, homeDir, { intoLive = false, now } = {}) {
+  const target = path.join(homeDir, "gafj.db");
+  fs.mkdirSync(homeDir, { recursive: true });
+  if (fs.existsSync(target)) {
+    if (!intoLive) throw new Error(`${target} exists; restore into a fresh home, or pass intoLive to replace it after a backup`);
+    const live = open(target);
+    try { await backup(live, path.join(homeDir, "backups", "pre-restore-" + backupName(now || new Date().toISOString()))); }
+    finally { live.close(); }
+    for (const suffix of ["", "-wal", "-shm"]) fs.rmSync(target + suffix, { force: true });
+  }
+  verify(backupFile);
+  fs.copyFileSync(backupFile, target);
+  const v = verify(target);
+  return { file: target, version: v.version };
+}
+
+module.exports = { backup, restore, verify, backupName };

package/store/backup_dir.js

@@ -0,0 +1,60 @@
+"use strict";
+
+/**
+ * Where backups go: config.backup_dir when set (a folder a sync client may
+ * watch: Drive, OneDrive, Dropbox), else <export dir>/backups. The live
+ * store never goes to the backup folder; only consistent copies do. A
+ * daily copy is taken at serve start when the newest one is older than a
+ * day, and the settings screen records the last one.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { backup, backupName } = require("./backup");
+
+const DAY_MS = 24 * 3600 * 1000;
+const KEEP = 14;
+
+function backupDir(cfg, exportDir) {
+  return cfg.backup_dir || path.join(exportDir, "backups");
+}
+
+function newest(dir) {
+  try {
+    return fs.readdirSync(dir).filter((f) => /^gafj-\d{8}-\d{4}\.db$/.test(f)).sort().pop() || null;
+  } catch (_) { return null; }
+}
+
+/** Keep the newest KEEP dated copies; older ones go. Pre-restore copies are never touched. */
+function prune(dir, keep = KEEP) {
+  let files;
+  try { files = fs.readdirSync(dir).filter((f) => /^gafj-\d{8}-\d{4}\.db$/.test(f)).sort(); } catch (_) { return []; }
+  const gone = files.slice(0, Math.max(0, files.length - keep));
+  for (const f of gone) fs.rmSync(path.join(dir, f), { force: true });
+  return gone;
+}
+
+async function backupTo(db, dir, now) {
+  const r = await backup(db, path.join(dir, backupName(now)));
+  const pruned = prune(dir);
+  return { ...r, dir, pruned: pruned.length };
+}
+
+/** At serve start: a copy if the newest in the folder is older than a day. Never throws; a bad folder is reported, not fatal. */
+async function dailyBackup(db, dir, now) {
+  const last = newest(dir);
+  const stamp = backupName(now).slice(5, 18); // YYYYMMDD-HHMM
+  if (last) {
+    const m = last.match(/^gafj-(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})\.db$/);
+    const at = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]), Number(m[4]), Number(m[5]));
+    if (Date.parse(now) - at < DAY_MS) return { skipped: true, last, dir };
+  }
+  try {
+    const r = await backupTo(db, dir, now);
+    return { skipped: false, file: r.file, dir, stamp, pruned: r.pruned };
+  } catch (e) {
+    return { skipped: true, error: e.message, dir };
+  }
+}
+
+module.exports = { backupDir, backupTo, dailyBackup, prune, newest, KEEP, DAY_MS };

package/store/config.js

@@ -0,0 +1,32 @@
+"use strict";
+
+/**
+ * config.json beside the store. Holds the active candidate, ports, tokens,
+ * providers, and thresholds. Never backed up with the store. Secrets are
+ * masked by callers that display it; this module only reads and writes.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { DEFAULT_THRESHOLDS } = require("./snapshot");
+
+function configPath(homeDir) {
+  return path.join(homeDir, "config.json");
+}
+
+function readConfig(homeDir) {
+  const p = configPath(homeDir);
+  if (!fs.existsSync(p)) return { route: "paste", providers: [], thresholds: { ...DEFAULT_THRESHOLDS } };
+  const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
+  cfg.thresholds = { ...DEFAULT_THRESHOLDS, ...(cfg.thresholds || {}) };
+  return cfg;
+}
+
+function writeConfig(homeDir, cfg) {
+  const p = configPath(homeDir);
+  fs.writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+  try { fs.chmodSync(p, 0o600); } catch (_) { /* Windows */ }
+  return p;
+}
+
+module.exports = { readConfig, writeConfig, configPath };

package/store/context.js

@@ -0,0 +1,74 @@
+"use strict";
+
+/**
+ * Builds the validator context from the store: the KB slice (all confirmed
+ * dimensions of the candidate, or the packet's kb_ids), this application's
+ * universe, the candidate's full universe, and the house rules.
+ */
+
+const { houseFor } = require("../core/house_rules");
+
+function parseRecord(row) {
+  return {
+    id: row.id, title: row.title, company: row.company, role: row.role, summary: row.summary,
+    metrics_json: JSON.parse(row.metrics_json), verbs_json: JSON.parse(row.verbs_json),
+    verbatim_claims_json: JSON.parse(row.verbatim_claims_json), wordings_json: JSON.parse(row.wordings_json || "[]"),
+    tags_json: JSON.parse(row.tags_json || "[]"), strength_score: row.strength_score,
+  };
+}
+
+function loadSlice(db, candidate_id, ids) {
+  const rows = ids && ids.length
+    ? ids.map((id) => db.prepare("SELECT * FROM accomplishment WHERE id = ? AND candidate_id = ?").get(id, candidate_id)).filter(Boolean)
+    : db.prepare("SELECT * FROM accomplishment WHERE candidate_id = ?").all(candidate_id);
+  return new Map(rows.map((r) => [r.id, parseRecord(r)]));
+}
+
+function applicationUniverse(db, application_id) {
+  if (!application_id) return { interview_ids: new Set(), document_ids: new Set(), person_ids: new Set(), debriefs: new Map(), rounds: [], formats: [], people: [], document_kinds: [], company: null };
+  const app = db.prepare("SELECT a.id, p.company FROM application a JOIN posting p ON p.id = a.posting_id WHERE a.id = ?").get(application_id);
+  const interviews = db.prepare("SELECT id, round_label, format, debrief_text FROM interview WHERE application_id = ?").all(application_id);
+  const docs = db.prepare(`SELECT d.id, d.kind FROM document d LEFT JOIN interview i ON i.id = d.interview_id
+    WHERE d.application_id = ? OR i.application_id = ? OR d.posting_id = (SELECT posting_id FROM application WHERE id = ?)`).all(application_id, application_id, application_id);
+  const people = db.prepare(`SELECT DISTINCT pe.id, pe.name FROM person pe
+    LEFT JOIN application_person ap ON ap.person_id = pe.id
+    LEFT JOIN interview_person ip ON ip.person_id = pe.id LEFT JOIN interview i ON i.id = ip.interview_id
+    WHERE ap.application_id = ? OR i.application_id = ?`).all(application_id, application_id);
+  return {
+    interview_ids: new Set(interviews.map((i) => i.id)),
+    document_ids: new Set(docs.map((d) => d.id)),
+    person_ids: new Set(people.map((p) => p.id)),
+    debriefs: new Map(interviews.filter((i) => i.debrief_text).map((i) => [i.id, i.debrief_text])),
+    rounds: interviews.map((i) => i.round_label),
+    formats: interviews.map((i) => i.format),
+    people: people.map((p) => p.name),
+    document_kinds: docs.map((d) => d.kind),
+    company: app ? app.company : null,
+  };
+}
+
+function candidateUniverse(db, candidate_id, thisCompany) {
+  const companies = db.prepare("SELECT DISTINCT p.company FROM posting p JOIN application a ON a.posting_id = p.id WHERE p.candidate_id = ?").all(candidate_id).map((r) => r.company);
+  const kbCompanies = db.prepare("SELECT DISTINCT company FROM accomplishment WHERE candidate_id = ?").all(candidate_id).map((r) => r.company);
+  const cand = db.prepare("SELECT company_aliases_json FROM candidate WHERE id = ?").get(candidate_id);
+  const aliases = cand ? JSON.parse(cand.company_aliases_json || "{}") : {};
+  return {
+    other_companies: companies.filter((c) => c !== thisCompany),
+    known_entities: [...kbCompanies, ...companies],
+    aliases,
+  };
+}
+
+function buildContext(db, { candidate_id, kind, mode, application_id, kb_ids }) {
+  const cand = db.prepare("SELECT style_config_json FROM candidate WHERE id = ?").get(candidate_id);
+  const application = applicationUniverse(db, application_id);
+  return {
+    kind, mode,
+    slice: loadSlice(db, candidate_id, kb_ids),
+    application,
+    universe: candidateUniverse(db, candidate_id, application.company),
+    house: houseFor(cand ? JSON.parse(cand.style_config_json || "{}") : {}),
+  };
+}
+
+module.exports = { buildContext, loadSlice, applicationUniverse, candidateUniverse, parseRecord };

package/store/db.js

@@ -0,0 +1,37 @@
+"use strict";
+
+/**
+ * The only file that knows which SQLite driver is in use. Everything else
+ * receives the handle this returns and calls exec / prepare / close on it.
+ *
+ * Open order matters on a cold start with two processes (plan section O):
+ * the constructor timeout first, then busy_timeout, then WAL, then foreign
+ * keys, then synchronous. Setting the PRAGMA after journal_mode, or setting
+ * only one of the two timeouts, is the documented way to get SQLITE_BUSY on
+ * the second process's first statement.
+ */
+
+const BUSY_TIMEOUT_MS = 5000;
+
+function openNodeSqlite(file) {
+  const { DatabaseSync } = require("node:sqlite");
+  const db = new DatabaseSync(file, { timeout: BUSY_TIMEOUT_MS });
+  db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+  if (file !== ":memory:") db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA foreign_keys = ON");
+  db.exec("PRAGMA synchronous = NORMAL");
+  return db;
+}
+
+/**
+ * @param {string} file  absolute path, or ":memory:" for tests
+ * @param {{driver?: "node:sqlite"}} [opts]
+ */
+function open(file, opts = {}) {
+  const driver = opts.driver || "node:sqlite";
+  if (driver === "node:sqlite") return openNodeSqlite(file);
+  // The seam: a better-sqlite3 adapter drops in here without touching callers.
+  throw new Error(`unknown sqlite driver: ${driver}`);
+}
+
+module.exports = { open, BUSY_TIMEOUT_MS };