@gafj/gafj 0.1.1

package/store/reads.js

@@ -0,0 +1,110 @@
+"use strict";
+
+/**
+ * Read models for the screens. Plain queries, no clock, no writes. Every
+ * read of a person goes through canonical_person so a merged id resolves.
+ */
+
+const { canonicalPerson } = require("./transitions");
+const { serializeRecord } = require("../core/generators/serialize");
+const { loadSlice } = require("./context");
+
+function person(db, id) {
+  const p = canonicalPerson(db, id);
+  return p ? { person_id: p.id, name: p.name, title: p.title, org: p.org, intel_text: p.intel_text, links: JSON.parse(p.links_json || "[]") } : null;
+}
+
+function docRow(d) {
+  const gate = JSON.parse(d.gate_result_json || "{}");
+  return { document_id: d.id, kind: d.kind, status: d.status, route: d.route, created_at: d.created_at, rendered_rel_path: d.rendered_rel_path,
+    interview_id: d.interview_id, posting_id: d.posting_id, application_id: d.application_id,
+    blocks: gate.blocks || [], warnings: JSON.parse(d.warnings_json || "[]"), ai_attempt_id: d.ai_attempt_id };
+}
+
+function documentsFor(db, { posting_id, application_id, interview_id }) {
+  const rows = db.prepare(`SELECT d.* FROM document d LEFT JOIN interview i ON i.id = d.interview_id
+    WHERE (? IS NOT NULL AND d.posting_id = ?) OR (? IS NOT NULL AND (d.application_id = ? OR i.application_id = ?)) OR (? IS NOT NULL AND d.interview_id = ?)
+    ORDER BY d.created_at DESC`).all(posting_id || null, posting_id || null, application_id || null, application_id || null, application_id || null, interview_id || null, interview_id || null);
+  return rows.map(docRow);
+}
+
+function listApplications(db, candidate_id) {
+  return db.prepare(`SELECT a.id AS application_id, a.status, a.applied_at, a.decision_expected_at, p.id AS posting_id, p.company, p.title, p.taken_down_at, s.fit_score, s.verdict,
+      (SELECT count(*) FROM interview i WHERE i.application_id = a.id AND i.status = 'scheduled') AS scheduled
+    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 a.applied_at DESC, p.captured_at DESC`).all(candidate_id);
+}
+
+function interviewRow(db, i) {
+  const people = db.prepare("SELECT person_id FROM interview_person WHERE interview_id = ?").all(i.id).map((r) => person(db, r.person_id)).filter(Boolean);
+  return { interview_id: i.id, application_id: i.application_id, round_label: i.round_label, format: i.format, status: i.status, scheduled_at: i.scheduled_at, tz: i.tz,
+    completed_at: i.completed_at, invite_received_at: i.invite_received_at, outcome: i.outcome, supersedes_id: i.supersedes_id,
+    debrief_text: i.debrief_text, debrief_captured_at: i.debrief_captured_at, pinned_ids: JSON.parse(i.pinned_ids_json || "[]"), people };
+}
+
+function applicationDetail(db, application_id) {
+  const a = db.prepare(`SELECT a.*, p.candidate_id, p.company, p.title, p.location, p.comp_text, p.source_url, p.taken_down_at, p.status AS posting_status,
+    s.fit_score, s.verdict, s.verdict_reason, s.categories_json, s.rubric_version FROM application a JOIN posting p ON p.id = a.posting_id LEFT JOIN scoring s ON s.id = a.scoring_id WHERE a.id = ?`).get(application_id);
+  if (!a) return null;
+  const interviews = db.prepare("SELECT * FROM interview WHERE application_id = ? AND status <> 'superseded' ORDER BY scheduled_at").all(a.id).map((i) => interviewRow(db, i));
+  const people = db.prepare("SELECT person_id, role FROM application_person WHERE application_id = ?").all(a.id).map((r) => ({ ...person(db, r.person_id), role: r.role })).filter((p) => p.person_id);
+  const comms = db.prepare(`SELECT c.*, i.round_label FROM communication c LEFT JOIN interview i ON i.id = c.interview_id WHERE c.application_id = ? ORDER BY c.sent_at DESC`).all(a.id)
+    .map((c) => ({ communication_id: c.id, kind: c.kind, interview_id: c.interview_id, round_label: c.round_label, document_id: c.document_id, to_addr: c.to_addr, sent_at: c.sent_at, changed_body: !!c.sent_body_text }));
+  return {
+    application_id: a.id, posting_id: a.posting_id, status: a.status, applied_at: a.applied_at, decision_expected_at: a.decision_expected_at, notes: a.notes,
+    resume_doc_id: a.resume_doc_id, cover_doc_id: a.cover_doc_id,
+    posting: { posting_id: a.posting_id, company: a.company, title: a.title, location: a.location, comp_text: a.comp_text, source_url: a.source_url, taken_down_at: a.taken_down_at, status: a.posting_status },
+    scoring: a.scoring_id ? { scoring_id: a.scoring_id, fit_score: a.fit_score, verdict: a.verdict, verdict_reason: a.verdict_reason, rubric_version: a.rubric_version, categories: JSON.parse(a.categories_json || "[]") } : null,
+    documents: documentsFor(db, { posting_id: a.posting_id, application_id: a.id }),
+    interviews, people, communications: comms,
+  };
+}
+
+function interviewDetail(db, interview_id) {
+  const i = db.prepare(`SELECT i.*, p.candidate_id, p.company, p.title, p.id AS posting_id, a.status AS application_status 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 (!i) return null;
+  const row = interviewRow(db, i);
+  const prior = db.prepare("SELECT * FROM interview WHERE application_id = ? AND id <> ? AND status <> 'superseded' AND scheduled_at < ? ORDER BY scheduled_at").all(i.application_id, i.id, i.scheduled_at)
+    .map((x) => interviewRow(db, x));
+  const later = db.prepare("SELECT * FROM interview WHERE application_id = ? AND id <> ? AND status <> 'superseded' AND scheduled_at >= ? ORDER BY scheduled_at").all(i.application_id, i.id, i.scheduled_at)
+    .map((x) => interviewRow(db, x));
+  const slice = row.pinned_ids.length ? loadSlice(db, i.candidate_id, row.pinned_ids) : new Map();
+  const runs = db.prepare(`SELECT r.id AS run_id, r.operation, r.route, r.final_result, r.started_at, (SELECT count(*) FROM ai_attempt t WHERE t.ai_run_id = r.id) AS attempts
+    FROM ai_run r WHERE r.interview_id = ? ORDER BY r.started_at DESC LIMIT 30`).all(i.id);
+  return {
+    ...row, company: i.company, title: i.title, posting_id: i.posting_id, application_status: i.application_status,
+    prior_rounds: prior, later_rounds: later,
+    pinned: [...slice.values()].map((r) => ({ id: r.id, title: r.title, company: r.company })),
+    documents: documentsFor(db, { interview_id: i.id }),
+    communications: db.prepare("SELECT id AS communication_id, kind, sent_at, to_addr FROM communication WHERE interview_id = ? ORDER BY sent_at DESC").all(i.id),
+    runs,
+  };
+}
+
+function documentDetail(db, document_id) {
+  const d = db.prepare("SELECT * FROM document WHERE id = ?").get(document_id);
+  if (!d) return null;
+  const run = d.ai_attempt_id ? db.prepare("SELECT r.id AS run_id, r.operation, r.interview_id, r.posting_id FROM ai_attempt t JOIN ai_run r ON r.id = t.ai_run_id WHERE t.id = ?").get(d.ai_attempt_id) : null;
+  let header = null;
+  if (d.interview_id) {
+    const i = db.prepare("SELECT i.round_label, i.format, i.scheduled_at, i.tz, p.company, p.title 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(d.interview_id);
+    header = { ...i, people: db.prepare("SELECT person_id FROM interview_person WHERE interview_id = ?").all(d.interview_id).map((r) => person(db, r.person_id)).filter(Boolean) };
+  } else if (d.posting_id) header = db.prepare("SELECT company, title FROM posting WHERE id = ?").get(d.posting_id);
+  else if (d.application_id) header = db.prepare("SELECT p.company, p.title FROM application a JOIN posting p ON p.id = a.posting_id WHERE a.id = ?").get(d.application_id);
+  return { ...docRow(d), content: JSON.parse(d.content_json), provenance: JSON.parse(d.provenance_json || "{}"), run, header, candidate_id: d.candidate_id };
+}
+
+function searchAccomplishments(db, candidate_id, q, limit = 20) {
+  const records = [...loadSlice(db, candidate_id).values()];
+  let chosen = records;
+  if (q && q.trim()) {
+    const { rankEvidence } = require("../core/scoring");
+    const { toScoringShape } = require("../core/generators/serialize");
+    const ranked = rankEvidence(q, records.map(toScoringShape), limit);
+    const byId = new Map(records.map((r) => [r.id, r]));
+    chosen = ranked.map((e) => byId.get(e.accomplishmentId));
+  }
+  return chosen.slice(0, limit).map((r) => serializeRecord(r));
+}
+
+module.exports = { listApplications, applicationDetail, interviewDetail, documentDetail, documentsFor, searchAccomplishments, person };

package/store/render.js

@@ -0,0 +1,111 @@
+"use strict";
+
+/**
+ * Markdown export of a passed document: a readable file on disk, the
+ * store remembering where it went (rendered_rel_path). Round, people, and
+ * datetime come from the store at render time; the model never wrote them.
+ * Claims are dropped from the rendering; provenance stays on the row.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { SCHEMAS } = require("../core/schemas");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+
+const SCHEMA_FOR_KIND = { resume: "resume", cover: "cover", prep: "prep", onepager: "onepager", deep_answers: "deep_answers", practice: "practice", email: "followup" };
+
+const label = (k) => k.replace(/_/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").replace(/^\w/, (c) => c.toUpperCase());
+
+function renderNode(value, node, depth, out) {
+  if (node.claimed) { if (value && value.text) out.push(value.text, ""); return; }
+  if (node.t === "object") {
+    for (const [k, sub] of Object.entries(node.fields)) {
+      if (!(k in value)) continue;
+      const v = value[k];
+      if (sub.t === "string" || sub.claimed || sub.t === "number" || sub.t === "boolean") {
+        if (v === "" || v == null) continue;
+        out.push(`**${label(k)}:** ${sub.claimed ? v.text : v}`, "");
+      } else {
+        out.push(`${"#".repeat(Math.min(6, depth))} ${label(k)}`, "");
+        renderNode(v, sub, depth + 1, out);
+      }
+    }
+  } else if (node.t === "array") {
+    const items = node.items;
+    if (items.t === "string") for (const v of value) out.push(`- ${v}`);
+    else if (items.claimed) for (const v of value) out.push(`- ${v.text}`);
+    else value.forEach((v, i) => { out.push(`${i + 1}.`); const inner = []; renderNode(v, items, depth + 1, inner); out.push(...inner.map((l) => (l ? "   " + l : l))); });
+    out.push("");
+  }
+}
+
+function renderResume(c, out) {
+  out.push(`# ${c.headline}`, "", (c.specialties || []).join(" · "), "");
+  if (c.headerLinks && c.headerLinks.length) out.push(c.headerLinks.join(" | "), "");
+  out.push("## Career Highlights", "");
+  for (const h of c.careerHighlights || []) out.push(`- **${h.leadIn}** ${h.proof && h.proof.text || ""}`);
+  out.push("", `## ${c.experienceSectionTitle || "Experience"}`, "");
+  for (const e of c.experience || []) {
+    out.push(`### ${e.role}, ${e.company} (${e.dates})${e.section === "concurrent" ? " · concurrent" : ""}`, "");
+    if (e.scope) out.push(`*${e.scope}*`, "");
+    for (const b of e.bullets || []) out.push(`- ${b.text && b.text.text || ""}`);
+    out.push("");
+  }
+  if (c.skills && c.skills.length) out.push("## Skills", "", c.skills.join(" · "), "");
+}
+
+function header(db, doc) {
+  const lines = [];
+  if (doc.interview_id) {
+    const iv = db.prepare(`SELECT i.round_label, i.format, i.scheduled_at, i.tz, p.company, p.title 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(doc.interview_id);
+    const people = db.prepare("SELECT pe.name, pe.title FROM interview_person ip JOIN person pe ON pe.id = ip.person_id WHERE ip.interview_id = ?").all(doc.interview_id);
+    lines.push(`${iv.company}: ${iv.title}`, `${iv.round_label} ${iv.format}, ${iv.scheduled_at} ${iv.tz}`);
+    if (people.length) lines.push("With " + people.map((p) => p.title ? `${p.name} (${p.title})` : p.name).join(", "));
+  } else if (doc.posting_id) {
+    const p = db.prepare("SELECT company, title FROM posting WHERE id = ?").get(doc.posting_id);
+    lines.push(`${p.company}: ${p.title}`);
+  } else if (doc.application_id) {
+    const p = db.prepare("SELECT p.company, p.title FROM application a JOIN posting p ON p.id = a.posting_id WHERE a.id = ?").get(doc.application_id);
+    lines.push(`${p.company}: ${p.title}`);
+  }
+  return lines;
+}
+
+function renderMarkdown(db, doc) {
+  const content = JSON.parse(doc.content_json);
+  const out = [];
+  const head = header(db, doc);
+  if (doc.kind === "resume") renderResume(content, out);
+  else if (doc.kind === "email") out.push(`**Subject:** ${content.subject}`, "", content.body && content.body.text || "", "");
+  else {
+    out.push(`# ${label(doc.kind)}${head.length ? ": " + head[0] : ""}`, "");
+    for (const h of head.slice(1)) out.push(h);
+    if (head.length > 1) out.push("");
+    renderNode(content, SCHEMAS[SCHEMA_FOR_KIND[doc.kind]], 2, out);
+  }
+  return out.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
+}
+
+function slug(s) { return String(s || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40); }
+
+/** Render a passed document to <outDir>; record the path relative to homeDir on the row. */
+function renderDocument(db, { document_id, outDir, homeDir, now, actor }) {
+  const doc = db.prepare("SELECT * FROM document WHERE id = ?").get(document_id);
+  if (!doc) throw new Error("unknown document");
+  if (doc.status !== "passed") throw new Error("only a passed document renders; this one is blocked");
+  const head = header(db, doc);
+  const md = renderMarkdown(db, doc);
+  fs.mkdirSync(outDir, { recursive: true });
+  const file = path.join(outDir, `${doc.kind}-${slug(head[0] || "document")}-${doc.id.slice(-6).toLowerCase()}.md`);
+  fs.writeFileSync(file, md, "utf8");
+  const rel = homeDir ? path.relative(homeDir, file) : file;
+  withTx(db, (d) => {
+    d.prepare("UPDATE document SET rendered_rel_path = ? WHERE id = ?").run(rel, doc.id);
+    appendEvent(d, { candidate_id: doc.candidate_id, entity: "document", entity_id: doc.id, event: "rendered", actor_type: actor.type, actor_ref: actor.ref, payload: { path: rel }, at: now });
+  });
+  return { file, rel, bytes: Buffer.byteLength(md) };
+}
+
+module.exports = { renderMarkdown, renderDocument };

package/store/reply.js

@@ -0,0 +1,19 @@
+"use strict";
+
+/**
+ * One entry for "the AI replied to run X": the run's operation picks the
+ * door. Documents go through ingest_document; an extraction through
+ * propose_from_source; a discovery through the question door. Nothing
+ * here decides on content, only on the run row.
+ */
+
+const { ingestDocument } = require("./ingest");
+
+function saveReply(db, a) {
+  const run = a.run_id ? db.prepare("SELECT operation FROM ai_run WHERE id = ?").get(a.run_id) : null;
+  if (run && run.operation === "extract") return require("./onboarding").saveExtraction(db, a);
+  if (run && run.operation === "discover") return require("./discover").saveDiscovery(db, a);
+  return ingestDocument(db, a);
+}
+
+module.exports = { saveReply };

package/store/review.js

@@ -0,0 +1,64 @@
+"use strict";
+
+/**
+ * The review queue: every dimension still in review state, and the three
+ * human actions on it: confirm, edit, drop. Each action bumps kb_revision
+ * and logs an event with the actor. This is the only path that promotes a
+ * dimension to confirmed; no model route reaches it.
+ */
+
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+
+const DIMS = { metric: "metrics_json", verb: "verbs_json", claim: "verbatim_claims_json" };
+
+function keyOf(dim, item) {
+  return dim === "metric" ? item.value : dim === "verb" ? item.verb : item.text;
+}
+
+function listReview(db, candidate_id, { record } = {}) {
+  const rows = record
+    ? [db.prepare("SELECT id, title, company, metrics_json, verbs_json, verbatim_claims_json FROM accomplishment WHERE candidate_id = ? AND id = ?").get(candidate_id, record)].filter(Boolean)
+    : db.prepare("SELECT id, title, company, metrics_json, verbs_json, verbatim_claims_json FROM accomplishment WHERE candidate_id = ? ORDER BY id").all(candidate_id);
+  const out = [];
+  for (const r of rows) {
+    for (const [dim, col] of Object.entries(DIMS)) {
+      for (const item of JSON.parse(r[col])) {
+        if (item.review_state === "confirmed") continue;
+        out.push({ id: r.id, title: r.title, company: r.company, dimension: dim, value: keyOf(dim, item),
+          detail: dim === "metric" ? item.outcome_key : dim === "claim" ? item.type : `tier ${item.tier}` });
+      }
+    }
+  }
+  return out;
+}
+
+function mutate(db, { candidate_id, record, dimension, value, action, edits = {}, now, actor }) {
+  const col = DIMS[dimension];
+  if (!col) throw new Error(`dimension must be one of ${Object.keys(DIMS).join(", ")}`);
+  return withTx(db, (d) => {
+    const row = d.prepare(`SELECT ${col} AS items FROM accomplishment WHERE id = ? AND candidate_id = ?`).get(record, candidate_id);
+    if (!row) throw new Error(`unknown record ${record}`);
+    const items = JSON.parse(row.items);
+    const idx = value === "*" ? -1 : items.findIndex((it) => keyOf(dimension, it).toLowerCase() === String(value).toLowerCase());
+    if (idx < 0 && value !== "*") throw new Error(`no ${dimension} "${value}" on ${record}`);
+    const targets = value === "*" ? items.map((_, i) => i) : [idx];
+    const prior = JSON.parse(JSON.stringify(items));
+    let changed = 0;
+    for (const i of targets.slice().reverse()) {
+      const it = items[i];
+      if (action === "confirm") { if (it.review_state !== "confirmed") { it.review_state = "confirmed"; changed++; } }
+      else if (action === "drop") { items.splice(i, 1); changed++; }
+      else if (action === "edit") { Object.assign(it, edits, { review_state: "confirmed" }); changed++; }
+      else throw new Error("action must be confirm, edit, or drop");
+    }
+    if (!changed) return { changed: 0 };
+    d.prepare(`UPDATE accomplishment SET ${col} = ? WHERE id = ?`).run(JSON.stringify(items), record);
+    d.prepare("UPDATE candidate SET kb_revision = kb_revision + 1 WHERE id = ?").run(candidate_id);
+    appendEvent(d, { candidate_id, entity: "accomplishment", entity_id: record, event: `review_${action}`, actor_type: actor.type, actor_ref: actor.ref,
+      payload: { dimension, value, edits }, prior: { [col]: prior }, at: now });
+    return { changed, remaining: items.filter((it) => it.review_state !== "confirmed").length };
+  });
+}
+
+module.exports = { listReview, mutate, DIMS };

package/store/scoring.js

@@ -0,0 +1,134 @@
+"use strict";
+
+/**
+ * Scoring contract (plan): categories are proposed, you edit, you freeze.
+ * Every jd_evidence line must be a verbatim substring of raw_text or the
+ * proposal is rejected. Freeze ranks evidence per category with scoring.js
+ * unchanged, computes the weighted mean on the 10 scale, records verdict
+ * and verdict_reason, hashes the evidence inputs, and supersedes the prior
+ * row. Packets and applications use frozen rows only.
+ */
+
+const crypto = require("crypto");
+const { ulid } = require("../core/ulid");
+const { scanJobDescription, rankEvidence, evaluateGate } = require("../core/scoring");
+const { SCHEMAS, validate } = require("../core/schemas");
+const { rulesVersion } = require("../core/rules");
+const { toScoringShape } = require("../core/generators/serialize");
+const { loadSlice } = require("./context");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+
+const ENGINE_VERSION = "scan-1";
+const STRENGTH_SCORE = { Strong: 8, Moderate: 6, Weak: 4 };
+const DEFAULT_PURSUE_MIN = 6;
+
+function sha(s) { return crypto.createHash("sha256").update(s).digest("hex"); }
+
+function postingOf(db, posting_id) {
+  const p = db.prepare("SELECT * FROM posting WHERE id = ?").get(posting_id);
+  if (!p) throw new Error("unknown posting");
+  return p;
+}
+
+/** Reject any category whose evidence is not verbatim in the posting; return schema errors too. */
+function checkCategories(categories, raw_text) {
+  const errors = validate({ categories }, SCHEMAS.categories).map((e) => `${e.path}: ${e.message}`);
+  categories.forEach((c, i) => {
+    for (const [j, e] of (c.jd_evidence || []).entries()) {
+      if (!raw_text.includes(e)) errors.push(`$.categories[${i}].jd_evidence[${j}]: not a verbatim substring of the posting`);
+    }
+  });
+  return errors;
+}
+
+/** Deterministic proposal from the scan: hard gates first, then minimum, responsibilities, preferred. */
+function proposeFromScan(db, { posting_id, now, actor }) {
+  const p = postingOf(db, posting_id);
+  const scan = scanJobDescription(p.raw_text);
+  const cats = [];
+  const seen = new Set();
+  const META = /^(?:\*\*)?(?:source|status|company|title|location|url|link|posted|applied|captured|comp|compensation|salary|pay|date)\b/i;
+  const HEADING = /^(?:(?:minimum|basic|required|preferred|key|core|essential)\s+)?(?:requirements?|qualifications?|preferred|nice to haves?|bonus|responsibilities|duties|what you.?ll do|the role|about (?:us|the role|you|the team)|benefits|compensation)\b[^a-z]*$/i;
+  const title = String(p.title || "").toLowerCase();
+  const add = (line, weight, hard) => {
+    const l = String(line).trim();
+    const name = l.replace(/^[-*•\u2022\d.)\s]+/, "").replace(/[^\w&/ ,'()+%$-]+/g, " ").replace(/\s+/g, " ").trim();
+    if (!l || l.length < 12 || seen.has(l) || cats.length >= 8 || HEADING.test(name) || name.split(/\s+/).length < 3) return;
+    if (title && name.toLowerCase().includes(title)) return; // the posting's own title line is not a requirement
+    seen.add(l);
+    cats.push({ category: name.slice(0, 80), weight, jd_evidence: [l.slice(0, 400)], is_hard_gate: hard });
+  };
+  for (const l of scan.hardGateLines) add(l, 10, true);
+  for (const l of scan.sectionText.minimum || []) add(l, 9, false);
+  for (const l of scan.sectionText.responsibilities || []) add(l, 7, false);
+  for (const l of scan.sectionText.preferred || []) add(l, 5, false);
+  for (const l of scan.sectionText.body || []) if (cats.length < 5 && !META.test(String(l).trim())) add(l, 6, false);
+  // A short posting still needs five rows to edit: pad from the remaining lines, shortest requirement last, at a low weight.
+  if (cats.length < 5) {
+    const all = [...(scan.sectionText.minimum || []), ...(scan.sectionText.responsibilities || []), ...(scan.sectionText.preferred || []), ...(scan.sectionText.body || [])];
+    for (const l of all) {
+      if (cats.length >= 5) break;
+      const t = String(l).trim();
+      const name = t.replace(/^[-*•\u2022\d.)\s]+/, "").replace(/\s+/g, " ").trim();
+      if (t.length < 8 || seen.has(t) || HEADING.test(name) || META.test(t)) continue;
+      seen.add(t);
+      cats.push({ category: name.slice(0, 80), weight: 5, jd_evidence: [t.slice(0, 400)], is_hard_gate: false });
+    }
+  }
+  const errors = checkCategories(cats, p.raw_text);
+  if (errors.length) throw new Error("scan produced too few usable categories; propose them by hand or through a model: " + errors.join("; "));
+  return withTx(db, (d) => {
+    const id = ulid(Date.parse(now));
+    const kb = d.prepare("SELECT kb_revision FROM candidate WHERE id = ?").get(p.candidate_id).kb_revision;
+    d.prepare(`INSERT INTO scoring (id, posting_id, categories_json, status, engine_version, rubric_version, kb_revision, scored_at)
+      VALUES (?, ?, ?, 'proposed', ?, ?, ?, ?)`).run(id, p.id, JSON.stringify(cats), ENGINE_VERSION, rulesVersion(), kb, now);
+    appendEvent(d, { candidate_id: p.candidate_id, entity: "scoring", entity_id: id, event: "proposed", actor_type: actor.type, actor_ref: actor.ref,
+      payload: { posting_id: p.id, categories: cats.length, from: "scan" }, at: now });
+    return { scoring_id: id, categories: cats };
+  });
+}
+
+/**
+ * Freeze. categories: the edited list (or the latest proposal when omitted). scores: optional
+ * [{category, score}] from the human; otherwise the mechanical score from evidence strength.
+ */
+function freezeScoring(db, { posting_id, categories, scores, now, actor, thresholds = {} }) {
+  const p = postingOf(db, posting_id);
+  const prior = db.prepare("SELECT * FROM scoring WHERE posting_id = ? ORDER BY scored_at DESC, rowid DESC LIMIT 1").get(p.id);
+  // Omitted categories means re-freeze the latest row's categories (edited scores, a new kb revision).
+  const bare = (c) => ({ category: c.category, weight: c.weight, jd_evidence: c.jd_evidence, is_hard_gate: !!c.is_hard_gate });
+  const cats = (categories || (prior ? JSON.parse(prior.categories_json) : [])).map(bare);
+  if (!cats.length) throw new Error("no categories to freeze; run score-freeze --from-scan or pass --categories");
+  const errors = checkCategories(cats, p.raw_text);
+  if (errors.length) throw new Error("categories rejected: " + errors.join("; "));
+  const records = [...loadSlice(db, p.candidate_id).values()];
+  const KB = records.map(toScoringShape);
+  const byName = new Map((scores || []).map((s) => [String(s.category), Number(s.score)]));
+  const frozen = cats.map((c) => {
+    const ev = rankEvidence([c.category, ...(c.jd_evidence || [])].join(" "), KB, 5);
+    const mechanical = ev.length ? STRENGTH_SCORE[ev[0].evidence_strength] : 2;
+    const score = byName.has(c.category) && isFinite(byName.get(c.category)) ? byName.get(c.category) : mechanical;
+    return { ...c, score, evidence_ids: ev.map((e) => e.accomplishmentId), evidence_strength: ev.length ? ev[0].evidence_strength : "None" };
+  });
+  const gate = evaluateGate([], frozen.map((c) => ({ category: c.category, weight: c.weight, score: c.score })));
+  const pursueMin = thresholds.pursue_min ?? DEFAULT_PURSUE_MIN;
+  const verdict = gate.gate === "BLOCKED" || gate.overall == null || gate.overall < pursueMin ? "pass" : "pursue";
+  const reason = gate.blocking.length
+    ? "hard gate: " + gate.blocking.map((b) => `${b.category} (weight ${b.weight}, score ${b.score})`).join("; ")
+    : `weighted mean ${gate.overall} against a ${pursueMin} floor`;
+  return withTx(db, (d) => {
+    const id = ulid(Date.parse(now));
+    const kb = d.prepare("SELECT kb_revision FROM candidate WHERE id = ?").get(p.candidate_id).kb_revision;
+    const evidenceHash = sha(JSON.stringify(frozen.map((c) => [c.category, c.weight, c.jd_evidence, c.score, c.evidence_ids])) + "|kb" + kb);
+    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, supersedes_id, scored_at)
+      VALUES (?, ?, ?, 'frozen', ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+      .run(id, p.id, JSON.stringify(frozen), gate.overall ?? 0, verdict, reason, ENGINE_VERSION, rulesVersion(), kb, evidenceHash, prior ? prior.id : null, now);
+    d.prepare("UPDATE application SET scoring_id = ? WHERE posting_id = ?").run(id, p.id);
+    appendEvent(d, { candidate_id: p.candidate_id, entity: "scoring", entity_id: id, event: "frozen", actor_type: actor.type, actor_ref: actor.ref,
+      payload: { posting_id: p.id, fit_score: gate.overall, verdict, supersedes: prior ? prior.id : null }, at: now });
+    return { scoring_id: id, fit_score: gate.overall, verdict, verdict_reason: reason, categories: frozen };
+  });
+}
+
+module.exports = { proposeFromScan, freezeScoring, checkCategories, ENGINE_VERSION };

package/store/settings.js

@@ -0,0 +1,142 @@
+"use strict";
+
+/**
+ * Settings (screen 6): the route, thresholds, export folder, house rules on the candidate row, and the
+ * provider registry. Keys are write-only: a read returns a mask and the
+ * last four characters; a write with an empty key keeps the stored one.
+ * Nothing here is ever logged with a body.
+ */
+
+const crypto = require("crypto");
+const { readConfig, writeConfig } = require("./config");
+const { DEFAULT_STYLE, REGISTERS, houseFor } = require("../core/house_rules");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+
+const ROUTES = ["paste", "mcp", "byo_key", "credits"];
+const KINDS = ["anthropic", "openai_compatible", "gemini"];
+
+function mask(key) {
+  if (!key) return null;
+  const s = String(key);
+  return "••••" + s.slice(-4);
+}
+
+function providerView(p) {
+  return { id: p.id, kind: p.kind, label: p.label, model: p.model, base_url: p.base_url || null, key: mask(p.api_key), has_key: !!p.api_key, last_test: p.last_test || null };
+}
+
+function creditsView(c) {
+  c = c || {};
+  return { relay_url: c.relay_url || null, token: mask(c.id_token), has_token: !!c.id_token, last_balance: c.last_balance || null };
+}
+
+function getSettings(db, homeDir, candidate_id) {
+  const cfg = readConfig(homeDir);
+  const cand = db.prepare("SELECT style_config_json, name FROM candidate WHERE id = ?").get(candidate_id);
+  const style = JSON.parse((cand && cand.style_config_json) || "{}");
+  return {
+    route: cfg.route || "paste", active_provider_id: cfg.active_provider_id || null, providers: (cfg.providers || []).map(providerView), credits: creditsView(cfg.credits),
+    thresholds: cfg.thresholds, export_dir: cfg.export_dir || null, backup_dir: cfg.backup_dir || null, last_backup: cfg.last_backup || null, port: cfg.port || null, home: homeDir, candidate: { id: candidate_id, name: cand && cand.name },
+    house_rules: { ...houseFor(style), defaults: DEFAULT_STYLE },
+  };
+}
+
+function putSettings(db, homeDir, candidate_id, patch, { now, actor }) {
+  const cfg = readConfig(homeDir);
+  const changed = [];
+  if (patch.route !== undefined) { if (!ROUTES.includes(patch.route)) throw Object.assign(new Error(`route must be one of ${ROUTES.join(", ")}`), { status: 400 }); cfg.route = patch.route; changed.push("route"); }
+  if (patch.active_provider_id !== undefined) { cfg.active_provider_id = patch.active_provider_id || null; changed.push("active_provider_id"); }
+  if (patch.export_dir !== undefined) { cfg.export_dir = patch.export_dir ? String(patch.export_dir) : undefined; changed.push("export_dir"); }
+  if (patch.backup_dir !== undefined) {
+    const dir = patch.backup_dir ? String(patch.backup_dir).trim() : "";
+    if (dir && require("path").resolve(dir) === require("path").resolve(homeDir)) throw Object.assign(new Error("the backup folder cannot be the data folder itself; pick a folder a sync client may watch, the live store never goes there"), { status: 400 });
+    cfg.backup_dir = dir || undefined;
+    changed.push("backup_dir");
+  }
+  if (patch.credits && typeof patch.credits === "object") {
+    const c = cfg.credits || {};
+    if (patch.credits.relay_url !== undefined) {
+      const u = String(patch.credits.relay_url || "").trim().replace(/\/+$/, "");
+      if (u && !/^https:\/\//i.test(u) && !/^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?/i.test(u)) throw Object.assign(new Error("relay url must be https, or http on loopback"), { status: 400 });
+      c.relay_url = u || null;
+    }
+    if (patch.credits.id_token) c.id_token = String(patch.credits.id_token).trim();
+    if (patch.credits.id_token === null) delete c.id_token;
+    cfg.credits = c;
+    changed.push("credits");
+  }
+  if (patch.thresholds && typeof patch.thresholds === "object") {
+    for (const [k, v] of Object.entries(patch.thresholds)) {
+      if (v == null || v === "") delete cfg.thresholds[k];
+      else if (isFinite(Number(v))) cfg.thresholds[k] = Number(v);
+    }
+    changed.push("thresholds");
+  }
+  writeConfig(homeDir, cfg);
+  if (patch.house_rules && typeof patch.house_rules === "object") {
+    const h = patch.house_rules;
+    const clean = {};
+    for (const rule of ["no_dashes", "style_config"]) if (h[rule] && typeof h[rule] === "object") {
+      clean[rule] = {};
+      for (const [kind, sev] of Object.entries(h[rule])) if (["block", "warn", "off"].includes(sev)) clean[rule][kind] = sev;
+    }
+    if (Array.isArray(h.hyphen_allow)) clean.hyphen_allow = h.hyphen_allow.map(String).filter(Boolean).slice(0, 50);
+    if (h.bullet_register !== undefined) { if (!REGISTERS.includes(h.bullet_register)) throw Object.assign(new Error(`bullet_register must be one of ${REGISTERS.join(", ")}`), { status: 400 }); clean.bullet_register = h.bullet_register; }
+    if (Array.isArray(h.vocabulary)) clean.vocabulary = h.vocabulary.filter((v) => v && v.pattern && v.message).map((v) => ({ pattern: String(v.pattern), flags: String(v.flags || ""), message: String(v.message) })).slice(0, 50);
+    withTx(db, (d) => {
+      const prior = d.prepare("SELECT style_config_json FROM candidate WHERE id = ?").get(candidate_id);
+      d.prepare("UPDATE candidate SET style_config_json = ? WHERE id = ?").run(JSON.stringify(clean), candidate_id);
+      appendEvent(d, { candidate_id, entity: "candidate", entity_id: candidate_id, event: "house_rules", actor_type: actor.type, actor_ref: actor.ref, payload: { keys: Object.keys(clean) }, prior: { style_config_json: prior.style_config_json }, at: now });
+    });
+    changed.push("house_rules");
+  }
+  if (changed.length) withTx(db, (d) => appendEvent(d, { candidate_id, entity: "settings", entity_id: candidate_id, event: "updated", actor_type: actor.type, actor_ref: actor.ref, payload: { changed }, at: now }));
+  return getSettings(db, homeDir, candidate_id);
+}
+
+/** Add or update a provider. Only the key of the named provider changes; an empty key keeps the old one. */
+function putProvider(homeDir, id, body) {
+  const cfg = readConfig(homeDir);
+  cfg.providers = cfg.providers || [];
+  if (!KINDS.includes(body.kind)) throw Object.assign(new Error(`kind must be one of ${KINDS.join(", ")}`), { status: 400 });
+  const base = body.base_url ? String(body.base_url).trim() : "";
+  if (base && !/^https:\/\//i.test(base) && !/^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?/i.test(base)) throw Object.assign(new Error("base_url must be https, or http on loopback"), { status: 400 });
+  let p = cfg.providers.find((x) => x.id === id);
+  if (!p) { p = { id: id || crypto.randomBytes(4).toString("hex"), api_key: "" }; cfg.providers.push(p); }
+  p.kind = body.kind;
+  p.label = String(body.label || p.label || body.kind).slice(0, 60);
+  p.model = String(body.model || p.model || "").slice(0, 120);
+  p.base_url = base || null;
+  if (body.api_key) p.api_key = String(body.api_key);
+  writeConfig(homeDir, cfg);
+  return providerView(p);
+}
+
+function deleteProvider(homeDir, id) {
+  const cfg = readConfig(homeDir);
+  cfg.providers = (cfg.providers || []).filter((p) => p.id !== id);
+  if (cfg.active_provider_id === id) cfg.active_provider_id = null;
+  writeConfig(homeDir, cfg);
+  return { deleted: id };
+}
+
+function recordBalance(homeDir, result) {
+  const cfg = readConfig(homeDir);
+  cfg.credits = { ...(cfg.credits || {}), last_balance: result };
+  writeConfig(homeDir, cfg);
+}
+
+function recordBackup(homeDir, result) {
+  const cfg = readConfig(homeDir);
+  cfg.last_backup = result;
+  writeConfig(homeDir, cfg);
+}
+
+function recordTest(homeDir, id, result) {
+  const cfg = readConfig(homeDir);
+  const p = (cfg.providers || []).find((x) => x.id === id);
+  if (p) { p.last_test = result; writeConfig(homeDir, cfg); }
+}
+
+module.exports = { getSettings, putSettings, putProvider, deleteProvider, recordTest, recordBalance, recordBackup, mask, ROUTES, KINDS };