@gafj/gafj 0.1.1

package/store/onboarding.js

@@ -0,0 +1,267 @@
+"use strict";
+
+/**
+ * Onboarding (plan section U): batches of source documents, extraction
+ * runs through the same routes as any op, and propose_from_source, the
+ * onboarding kind of ingest_proposal. It writes pending rows only: every
+ * factual atom must be an excerpt of its source text or the draft is
+ * rejected whole. Dedup suggests groups; the candidate merges by a click.
+ * Nothing here touches ingest_document or the document ledger.
+ */
+
+const { ulid } = require("../core/ulid");
+const { extractSource } = require("../core/parsers");
+const { extractJson } = require("../core/extract");
+const { SCHEMAS, validate } = require("../core/schemas");
+const { figureKey } = require("../core/text");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+const { TransitionError, NotFound } = require("./transitions");
+
+const MAX_ATTEMPTS = 3;
+
+// ----- batches and sources -----
+
+function openBatch(db, { candidate_id, now, actor }) {
+  return withTx(db, (d) => {
+    const existing = d.prepare("SELECT id FROM onboarding_batch WHERE candidate_id = ? AND status IN ('open', 'review') ORDER BY created_at DESC LIMIT 1").get(candidate_id);
+    if (existing) return { batch_id: existing.id, created: false };
+    const id = ulid(Date.parse(now));
+    d.prepare("INSERT INTO onboarding_batch (id, candidate_id, status, created_at) VALUES (?, ?, 'open', ?)").run(id, candidate_id, now);
+    appendEvent(d, { candidate_id, entity: "onboarding_batch", entity_id: id, event: "opened", actor_type: actor.type, actor_ref: actor.ref, at: now });
+    return { batch_id: id, created: true };
+  });
+}
+
+function setBatchStatus(db, { candidate_id, batch_id, status, now, actor }) {
+  if (!["open", "review", "completed", "abandoned"].includes(status)) throw new TransitionError("bad batch status");
+  return withTx(db, (d) => {
+    const b = d.prepare("SELECT * FROM onboarding_batch WHERE id = ?").get(batch_id);
+    if (!b || (candidate_id && b.candidate_id !== candidate_id)) throw new NotFound("batch");
+    d.prepare("UPDATE onboarding_batch SET status = ?, completed_at = CASE WHEN ? IN ('completed', 'abandoned') THEN ? ELSE completed_at END WHERE id = ?").run(status, status, now, b.id);
+    appendEvent(d, { candidate_id: b.candidate_id, entity: "onboarding_batch", entity_id: b.id, event: status, actor_type: actor.type, actor_ref: actor.ref, prior: { status: b.status }, at: now });
+    return { batch_id: b.id, status };
+  });
+}
+
+/** Upload one file: extract under the caps, store immutable text, dedupe by file hash. */
+async function addSource(db, { candidate_id, batch_id, filename, buffer, now, actor, limits }) {
+  const r = await extractSource(filename, buffer, limits);
+  return withTx(db, (d) => {
+    const b = d.prepare("SELECT id, status, candidate_id FROM onboarding_batch WHERE id = ?").get(batch_id);
+    if (!b || b.candidate_id !== candidate_id) throw new NotFound("batch");
+    if (b.status !== "open") throw new TransitionError(`batch is ${b.status}; open a new one`);
+    const dup = d.prepare("SELECT id, batch_id FROM source_document WHERE candidate_id = ? AND file_hash = ?").get(candidate_id, r.file_hash);
+    if (dup) return { source_document_id: dup.id, created: false, empty: false, failure: null, chars: null };
+    const id = ulid(Date.parse(now));
+    d.prepare(`INSERT INTO source_document (id, candidate_id, batch_id, filename, kind, file_hash, text_hash, extractor, extractor_version, text, uploaded_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, candidate_id, b.id, String(filename).slice(0, 200), r.kind, r.file_hash, r.text_hash, r.extractor, r.extractor_version, r.text, now);
+    appendEvent(d, { candidate_id, entity: "source_document", entity_id: id, event: r.empty ? "extraction_failed" : "uploaded", actor_type: actor.type, actor_ref: actor.ref,
+      payload: { kind: r.kind, chars: r.text.length, pages: r.pages, failure: r.failure }, at: now });
+    return { source_document_id: id, created: true, empty: r.empty, failure: r.failure, chars: r.text.length, kind: r.kind };
+  });
+}
+
+function listSources(db, candidate_id, batch_id) {
+  return db.prepare(`SELECT s.id AS source_document_id, s.batch_id, s.filename, s.kind, s.extractor, s.extractor_version, length(s.text) AS chars, s.uploaded_at,
+      (SELECT count(*) FROM pending_accomplishment p WHERE p.source_document_id = s.id) AS pending,
+      (SELECT count(*) FROM ai_run r WHERE r.source_document_id = s.id) AS runs
+    FROM source_document s WHERE s.candidate_id = ? AND (? IS NULL OR s.batch_id = ?) ORDER BY s.uploaded_at DESC`).all(candidate_id, batch_id || null, batch_id || null)
+    .map((s) => ({ ...s, empty: s.chars < 20 }));
+}
+
+function sourceText(db, source_document_id) {
+  const s = db.prepare("SELECT * FROM source_document WHERE id = ?").get(source_document_id);
+  if (!s) throw new NotFound("source document");
+  return s;
+}
+
+// ----- propose_from_source -----
+
+function checkAtom(atom, text, label, errors) {
+  if (!atom) return;
+  const { value, start, end } = atom;
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end > text.length || end <= start) { errors.push(`${label}: span [${start}, ${end}) is not inside the source`); return; }
+  if (text.slice(start, end) !== value) errors.push(`${label}: "${String(value).slice(0, 40)}" is not the source text at [${start}, ${end})`);
+}
+
+/** Validate a draft against its source: every atom cited and verbatim, else the whole draft is rejected. */
+function checkDraft(content, text) {
+  const errors = validate(content, SCHEMAS.extract).map((e) => `${e.path}: ${e.message}`);
+  if (errors.length) return errors;
+  content.accomplishments.forEach((a, i) => {
+    const p = `accomplishments[${i}]`;
+    checkAtom(a.company, text, `${p}.company`, errors);
+    checkAtom(a.role, text, `${p}.role`, errors);
+    if (a.dates) checkAtom(a.dates, text, `${p}.dates`, errors);
+    if (a.scope) checkAtom(a.scope, text, `${p}.scope`, errors);
+    (a.metrics || []).forEach((m, j) => checkAtom(m, text, `${p}.metrics[${j}]`, errors));
+    (a.verbs || []).forEach((v, j) => checkAtom(v, text, `${p}.verbs[${j}]`, errors));
+    (a.wordings || []).forEach((w, j) => checkAtom(w, text, `${p}.wordings[${j}]`, errors));
+  });
+  return errors;
+}
+
+/** The onboarding kind of ingest_proposal: pending rows with batch, source, attempt, and excerpts. */
+function proposeFromSource(db, { candidate_id, source_document_id, content, ai_attempt_id, now, actor }) {
+  const s = sourceText(db, source_document_id);
+  if (s.candidate_id !== candidate_id) throw new NotFound("source document");
+  const errors = checkDraft(content, s.text);
+  if (errors.length) return { accepted: false, errors, pending_ids: [] };
+  return withTx(db, (d) => {
+    const ids = [];
+    for (const a of content.accomplishments) {
+      const id = ulid(Date.parse(now) + ids.length);
+      const draft = {
+        title: a.title, company: a.company.value, role: a.role.value, dates: a.dates ? a.dates.value : "", summary: a.summary || "",
+        metrics: (a.metrics || []).map((m) => m.value), metric_outcomes: (a.metrics || []).map((m) => m.outcome || ""),
+        verbs: (a.verbs || []).map((v) => v.value), wordings: (a.wordings || []).map((w) => w.value), scope: a.scope ? a.scope.value : "", tags: a.tags || [],
+        excerpts: { company: span(a.company), role: span(a.role), dates: span(a.dates), scope: span(a.scope), metrics: (a.metrics || []).map(span), verbs: (a.verbs || []).map(span), wordings: (a.wordings || []).map(span) },
+        source_document_id: s.id,
+      };
+      try {
+        d.prepare("INSERT INTO pending_accomplishment (id, candidate_id, draft_json, source, batch_id, source_document_id, ai_attempt_id, proposed_at) VALUES (?, ?, ?, 'onboarding', ?, ?, ?, ?)")
+          .run(id, candidate_id, JSON.stringify(draft), s.batch_id, s.id, ai_attempt_id || null, now);
+      } catch (e) {
+        throw new TransitionError(/proposals per/.test(e.message) ? e.message : e.message);
+      }
+      ids.push(id);
+    }
+    appendEvent(d, { candidate_id, entity: "source_document", entity_id: s.id, event: "proposed", actor_type: actor.type, actor_ref: actor.ref, payload: { pending: ids.length, style: content.style_observed || null }, at: now });
+    return { accepted: true, errors: [], pending_ids: ids, style_observed: content.style_observed || null };
+  });
+}
+const span = (a) => (a ? { start: a.start, end: a.end } : null);
+
+/** Save the model's extraction for a run: counts the attempt, then propose_from_source. Three attempts then stop. */
+function saveExtraction(db, { run_id, content, route, actor, now, provider, model, tokens_in, tokens_out, latency_ms }) {
+  return withTx(db, (d) => {
+    const run = d.prepare("SELECT * FROM ai_run WHERE id = ?").get(run_id);
+    if (!run) throw new NotFound("run");
+    if (run.operation !== "extract") throw new TransitionError("this run is not an extraction; use the document door");
+    const attempts = d.prepare("SELECT count(*) c FROM ai_attempt WHERE ai_run_id = ?").get(run.id).c;
+    if (attempts >= MAX_ATTEMPTS) return { run_id: run.id, status: "blocked", attempt: attempts, stop: true, errors: ["three attempts used; open a fresh packet"], pending_ids: [] };
+    const attemptNo = attempts + 1;
+    const ex = extractJson(content);
+    let result;
+    let parsed = null;
+    if (ex.error) result = { accepted: false, errors: ["schema: " + ex.error], pending_ids: [] };
+    else { parsed = ex.value; result = { accepted: false, errors: [], pending_ids: [] }; }
+    const attemptId = ulid(Date.parse(now) + 100 + attemptNo);
+    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 (?, ?, ?, ?, ?, ?, ?, ?, ?, 'blocked', ?, ?, ?)`).run(attemptId, run.id, attemptNo, provider || null, model || null, tokens_in ?? null, tokens_out ?? null, latency_ms ?? null, null, ex.error ? "schema" : null, now, now);
+    if (parsed) result = proposeFromSource(d, { candidate_id: run.candidate_id, source_document_id: run.source_document_id, content: parsed, ai_attempt_id: attemptId, now, actor: { type: actor.type, ref: actor.ref } });
+    const status = result.accepted ? "passed" : "blocked";
+    d.prepare("UPDATE ai_attempt SET result = ?, error_code = ? WHERE id = ?").run(status, result.accepted ? null : (ex.error ? "schema" : "excerpt"), attemptId);
+    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: "ai_run", entity_id: run.id, event: status === "passed" ? "extraction_saved" : "extraction_blocked", actor_type: actor.type, actor_ref: actor.ref, payload: { attempt: attemptNo, pending: result.pending_ids.length, errors: result.errors.length, route }, at: now });
+    return { run_id: run.id, status, attempt: attemptNo, stop: attemptNo >= MAX_ATTEMPTS && status !== "passed", errors: result.errors, pending_ids: result.pending_ids, style_observed: result.style_observed || null };
+  });
+}
+
+// ----- dedup -----
+
+function monthRange(dates) {
+  const m = String(dates || "").match(/(\d{4})(?:-(\d{2}))?/g);
+  if (!m || !m.length) return null;
+  const a = m[0], b = m[m.length - 1];
+  const to = (s) => { const [y, mo] = s.split("-"); return Number(y) * 12 + (mo ? Number(mo) - 1 : 0); };
+  return [to(a), to(b) + (m.length === 1 ? 11 : 0)];
+}
+const overlaps = (x, y) => x && y && x[0] <= y[1] && y[0] <= x[1];
+const normCo = (s) => String(s || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").replace(/\b(inc|llc|corp|corporation|ltd|co)\b/g, "").trim();
+
+/** Cluster pending onboarding rows in a batch: same company, overlapping dates, and a shared metric key make a strong group; company and dates alone a weak one. */
+function suggestDedup(db, { candidate_id, batch_id, now, actor }) {
+  const owner = db.prepare("SELECT candidate_id FROM onboarding_batch WHERE id = ?").get(batch_id);
+  if (!owner || owner.candidate_id !== candidate_id) throw new NotFound("batch");
+  const rows = db.prepare("SELECT id, draft_json FROM pending_accomplishment WHERE candidate_id = ? AND batch_id = ? AND source = 'onboarding' ORDER BY proposed_at").all(candidate_id, batch_id)
+    .map((r) => { const d = JSON.parse(r.draft_json); return { id: r.id, company: normCo(d.company), range: monthRange(d.dates), keys: new Set((d.metrics || []).map(figureKey)), source: d.source_document_id }; });
+  const groups = [];
+  const assigned = new Map();
+  for (let i = 0; i < rows.length; i++) {
+    for (let j = i + 1; j < rows.length; j++) {
+      const a = rows[i], b = rows[j];
+      if (a.source === b.source || !a.company || a.company !== b.company) continue;
+      const shared = [...a.keys].filter((k) => b.keys.has(k));
+      const dates = overlaps(a.range, b.range);
+      // a weak link (company and dates only) is offered only when neither row carries a figure; otherwise every bullet at one employer would chain into one group
+      const strength = shared.length && dates ? "strong" : shared.length ? "shared_metric" : dates && !a.keys.size && !b.keys.size ? "weak" : null;
+      if (!strength) continue;
+      let g = assigned.get(a.id) || assigned.get(b.id);
+      if (!g) { g = { dedup_group_id: ulid(Date.parse(now) + groups.length), ids: new Set(), strength }; groups.push(g); }
+      g.ids.add(a.id); g.ids.add(b.id);
+      if (strength === "strong") g.strength = "strong";
+      assigned.set(a.id, g); assigned.set(b.id, g);
+    }
+  }
+  withTx(db, (d) => {
+    d.prepare("UPDATE pending_accomplishment SET dedup_group_id = NULL WHERE candidate_id = ? AND batch_id = ?").run(candidate_id, batch_id);
+    for (const g of groups) for (const id of g.ids) d.prepare("UPDATE pending_accomplishment SET dedup_group_id = ? WHERE id = ?").run(g.dedup_group_id, id);
+    appendEvent(d, { candidate_id, entity: "onboarding_batch", entity_id: batch_id, event: "dedup_suggested", actor_type: actor.type, actor_ref: actor.ref, payload: { groups: groups.length }, at: now });
+  });
+  return groups.map((g) => ({ dedup_group_id: g.dedup_group_id, strength: g.strength, pending_ids: [...g.ids] }));
+}
+
+/** The click: merge a group into its first row (wordings and metrics unioned, excerpts kept per source); the rest are deleted. */
+function mergeGroup(db, { candidate_id, dedup_group_id, keep_id, now, actor }) {
+  return withTx(db, (d) => {
+    const rows = d.prepare("SELECT id, draft_json FROM pending_accomplishment WHERE candidate_id = ? AND dedup_group_id = ? ORDER BY proposed_at").all(candidate_id, dedup_group_id);
+    if (rows.length < 2) throw new TransitionError("nothing to merge");
+    const keep = rows.find((r) => r.id === keep_id) || rows[0];
+    const base = JSON.parse(keep.draft_json);
+    base.sources = [{ source_document_id: base.source_document_id, excerpts: base.excerpts }];
+    for (const r of rows) {
+      if (r.id === keep.id) continue;
+      const o = JSON.parse(r.draft_json);
+      for (const [i, w] of (o.wordings || []).entries()) if (!base.wordings.includes(w)) { base.wordings.push(w); base.excerpts.wordings.push(null); }
+      for (const [i, m] of (o.metrics || []).entries()) if (!base.metrics.some((x) => figureKey(x) === figureKey(m))) { base.metrics.push(m); base.metric_outcomes.push((o.metric_outcomes || [])[i] || ""); base.excerpts.metrics.push(null); }
+      for (const v of o.verbs || []) if (!base.verbs.includes(v)) { base.verbs.push(v); base.excerpts.verbs.push(null); }
+      base.sources.push({ source_document_id: o.source_document_id, excerpts: o.excerpts });
+      d.prepare("DELETE FROM pending_accomplishment WHERE id = ?").run(r.id);
+    }
+    d.prepare("UPDATE pending_accomplishment SET draft_json = ?, dedup_group_id = NULL WHERE id = ?").run(JSON.stringify(base), keep.id);
+    appendEvent(d, { candidate_id, entity: "pending_accomplishment", entity_id: keep.id, event: "merged", actor_type: actor.type, actor_ref: actor.ref, payload: { from: rows.filter((r) => r.id !== keep.id).map((r) => r.id) }, at: now });
+    return { pending_id: keep.id, merged: rows.length - 1 };
+  });
+}
+
+function keepSeparate(db, { candidate_id, dedup_group_id, now, actor }) {
+  return withTx(db, (d) => {
+    const n = d.prepare("UPDATE pending_accomplishment SET dedup_group_id = NULL WHERE candidate_id = ? AND dedup_group_id = ?").run(candidate_id, dedup_group_id).changes;
+    if (!n) throw new NotFound("duplicate group");
+    appendEvent(d, { candidate_id, entity: "pending_accomplishment", entity_id: dedup_group_id, event: "kept_separate", actor_type: actor.type, actor_ref: actor.ref, payload: { rows: n }, at: now });
+    return { rows: n };
+  });
+}
+
+// ----- style proposal -----
+
+/** Scan the candidate's own sources for style; proposed for confirmation, never imposed. */
+function proposeStyle(db, candidate_id) {
+  const texts = db.prepare("SELECT text FROM source_document WHERE candidate_id = ?").all(candidate_id).map((r) => r.text).join("\n");
+  const count = (re) => (texts.match(re) || []).length;
+  const em = count(/[–—]/g), hy = count(/\b\w+-\w+\b/g);
+  const ecom = count(/\becommerce\b/gi), ecomH = count(/\be-commerce\b/gi);
+  const pctSym = count(/\d\s?%/g), pctWord = count(/\d\s+percent\b/gi);
+  return {
+    observed: { em_dashes: em, hyphen_compounds: hy, ecommerce: ecom, e_commerce: ecomH, percent_symbol: pctSym, percent_word: pctWord, chars: texts.length },
+    proposed: {
+      no_dashes: em ? { resume: "warn", cover: "warn", onepager: "warn", email: "warn" } : {},
+      vocabulary: ecomH > ecom ? [{ pattern: "\\becommerce\\b", flags: "i", message: 'this candidate writes "e-commerce"' }] : undefined,
+      note: "A new candidate defaults to warn until they choose; the sources may themselves have been machine-written.",
+    },
+  };
+}
+
+function batchView(db, candidate_id) {
+  const batch = db.prepare("SELECT * FROM onboarding_batch WHERE candidate_id = ? ORDER BY created_at DESC LIMIT 1").get(candidate_id);
+  if (!batch) return null;
+  const sources = listSources(db, candidate_id, batch.id);
+  const pending = db.prepare("SELECT id AS pending_id, draft_json, dedup_group_id, source_document_id, proposed_at FROM pending_accomplishment WHERE candidate_id = ? AND batch_id = ? ORDER BY dedup_group_id, proposed_at").all(candidate_id, batch.id)
+    .map((r) => ({ ...r, draft: JSON.parse(r.draft_json), draft_json: undefined }));
+  return { batch_id: batch.id, status: batch.status, created_at: batch.created_at, sources, pending, groups: [...new Set(pending.map((p) => p.dedup_group_id).filter(Boolean))] };
+}
+
+module.exports = { openBatch, setBatchStatus, addSource, listSources, sourceText, checkDraft, proposeFromSource, saveExtraction, suggestDedup, mergeGroup, keepSeparate, proposeStyle, batchView, MAX_ATTEMPTS };

package/store/packets.js

@@ -0,0 +1,110 @@
+"use strict";
+
+/**
+ * Gathers one operation's facts from the store, builds the packet, and
+ * records the run: an ai_run row in pending with the packet hash and the
+ * selected kb ids, which ingest later uses as the slice. Nothing else is
+ * written. The comp floor lives in config, which this module never reads.
+ */
+
+const { ulid } = require("../core/ulid");
+const { buildPacket, PACKET_VERSION, POSTING_OPS } = require("../core/generators/packet");
+const { rulesVersion } = require("../core/rules");
+const { SCHEMA_VERSION } = require("../core/schemas");
+const { loadSlice } = require("./context");
+const { targetFor } = require("./ingest");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+const { houseFor } = require("../core/house_rules");
+
+function latestFrozenScoring(db, posting_id, preferred_id) {
+  const row = (preferred_id && db.prepare("SELECT * FROM scoring WHERE id = ? AND status = 'frozen'").get(preferred_id))
+    || db.prepare("SELECT * FROM scoring WHERE posting_id = ? AND status = 'frozen' ORDER BY scored_at DESC, rowid DESC LIMIT 1").get(posting_id)
+    || db.prepare("SELECT * FROM scoring WHERE posting_id = ? ORDER BY scored_at DESC, rowid DESC LIMIT 1").get(posting_id);
+  if (!row) return null;
+  return { ...row, categories: JSON.parse(row.categories_json || "[]") };
+}
+
+function peopleFor(db, application_id) {
+  return db.prepare(`SELECT pe.id, pe.name, pe.title, pe.org, pe.intel_text, ap.role FROM application_person ap
+    JOIN person pe ON pe.id = ap.person_id WHERE ap.application_id = ? AND pe.merged_into_id IS NULL ORDER BY pe.name`).all(application_id);
+}
+
+function interviewPeople(db, interview_id) {
+  return db.prepare(`SELECT pe.id, pe.name, pe.title, pe.org, pe.intel_text, 'interviewer' AS role FROM interview_person ip
+    JOIN person pe ON pe.id = ip.person_id WHERE ip.interview_id = ? AND pe.merged_into_id IS NULL ORDER BY pe.name`).all(interview_id);
+}
+
+/** Everything the builder needs for one target, read in one place. */
+function gather(db, op, { interview_id, posting_id, source_document_id, candidate_id }) {
+  if (op === "extract") {
+    if (!source_document_id) throw new Error("extract needs a source_document_id");
+    const src = db.prepare("SELECT * FROM source_document WHERE id = ?").get(source_document_id);
+    if (!src) throw new Error("unknown source document");
+    const cand = db.prepare("SELECT id, name, kb_revision FROM candidate WHERE id = ?").get(src.candidate_id);
+    return { op, target: { candidate_id: cand.id, interview_id: null, posting_id: null, source_document_id: src.id }, candidate: { id: cand.id, name: cand.name, profile: {}, kb_revision: cand.kb_revision },
+      source: src, posting: null, scoring: null, application: null, pinned_ids: [], records: [] };
+  }
+  if (op === "discover") {
+    const cand = db.prepare("SELECT id, name, kb_revision FROM candidate WHERE id = ?").get(candidate_id);
+    if (!cand) throw new Error("discover needs a candidate_id");
+    const kb = require("./kb");
+    const { listQuestions } = require("./discover");
+    return { op, target: { candidate_id: cand.id, interview_id: null, posting_id: null, source_document_id: null }, candidate: { id: cand.id, name: cand.name, profile: {}, kb_revision: cand.kb_revision },
+      holes: kb.listHoles(db, cand.id, { limit: 40 }), prior_questions: listQuestions(db, cand.id, { all: true }).map((q) => ({ accomplishment_id: q.accomplishment_id, kind: q.kind, question: q.question, status: q.status })),
+      records: [...loadSlice(db, cand.id).values()], posting: null, scoring: null, application: null, pinned_ids: [] };
+  }
+  const t = targetFor(db, op, { interview_id, posting_id });
+  const cand = db.prepare("SELECT id, name, profile_json, kb_revision, style_config_json FROM candidate WHERE id = ?").get(t.candidate_id);
+  let posting;
+  let application = null;
+  let scoring = null;
+  let pinned = [];
+  if (POSTING_OPS.has(op)) {
+    posting = db.prepare("SELECT * FROM posting WHERE id = ?").get(t.posting_id);
+    const app = db.prepare("SELECT scoring_id FROM application WHERE posting_id = ?").get(posting.id);
+    scoring = latestFrozenScoring(db, posting.id, app && app.scoring_id);
+  } else {
+    const app = db.prepare(`SELECT a.*, p.company, p.title FROM application a JOIN posting p ON p.id = a.posting_id WHERE a.id = ?`).get(t.application_id);
+    posting = db.prepare("SELECT * FROM posting WHERE id = ?").get(app.posting_id);
+    scoring = latestFrozenScoring(db, posting.id, app.scoring_id);
+    const interviews = db.prepare("SELECT * FROM interview WHERE application_id = ? ORDER BY scheduled_at").all(app.id)
+      .map((i) => ({ ...i, people: interviewPeople(db, i.id) }));
+    const documents = db.prepare(`SELECT d.id, d.kind, d.status, d.interview_id, d.content_json, d.created_at 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 = ? ORDER BY d.created_at`).all(app.id, app.id, posting.id);
+    const me = interviews.find((i) => i.id === t.interview_id);
+    pinned = JSON.parse((me && me.pinned_ids_json) || "[]");
+    const prepRow = documents.filter((d) => d.kind === "prep" && d.status === "passed" && d.interview_id === t.interview_id).pop();
+    application = { id: app.id, company: app.company, title: app.title, status: app.status, interview_id: t.interview_id,
+      interviews, people: peopleFor(db, app.id), documents, prep: prepRow ? JSON.parse(prepRow.content_json) : null };
+  }
+  return {
+    op, target: t,
+    candidate: { id: cand.id, name: cand.name, profile: JSON.parse(cand.profile_json || "{}"), kb_revision: cand.kb_revision },
+    house: houseFor(JSON.parse(cand.style_config_json || "{}")),
+    posting, scoring, application, pinned_ids: pinned,
+    records: [...loadSlice(db, cand.id).values()],
+  };
+}
+
+/**
+ * Build the packet and open the run. Returns { run_id, packet }.
+ * @param {object} a { op, interview_id?, posting_id?, route, actor, now, budgets? }
+ */
+function openRun(db, a) {
+  const g = gather(db, a.op, a);
+  const packet = buildPacket({ ...g, budgets: a.budgets });
+  return withTx(db, (d) => {
+    const id = ulid(Date.parse(a.now));
+    d.prepare(`INSERT INTO ai_run (id, candidate_id, route, operation, interview_id, posting_id, source_document_id, rules_version, schema_version, packet_version, kb_revision, packet_hash, kb_ids_json, started_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+      .run(id, g.candidate.id, a.route || "paste", a.op, g.target.interview_id, g.target.posting_id, g.target.source_document_id || null, rulesVersion(), SCHEMA_VERSION, PACKET_VERSION,
+        g.candidate.kb_revision, packet.packet_hash, JSON.stringify(packet.kb_ids), a.now);
+    appendEvent(d, { candidate_id: g.candidate.id, entity: "ai_run", entity_id: id, event: "packet_built", actor_type: a.actor.type, actor_ref: a.actor.ref,
+      payload: { operation: a.op, route: a.route || "paste", kb_ids: packet.kb_ids.length, packet_hash: packet.packet_hash }, at: a.now });
+    return { run_id: id, packet };
+  });
+}
+
+module.exports = { openRun, gather, latestFrozenScoring };

package/store/practice.js

@@ -0,0 +1,52 @@
+"use strict";
+
+/** Writes the practice workbook with exceljs from a passed practice document; the manifest stays on the row. */
+
+const fs = require("fs");
+const path = require("path");
+const { buildWorkbook } = require("../core/practice");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+
+async function writeWorkbook(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.kind !== "practice") throw new Error("only a practice document becomes a workbook");
+  if (doc.status !== "passed") throw new Error("only a passed document renders; this one is blocked");
+  const ExcelJS = require("exceljs");
+  const wb = buildWorkbook(JSON.parse(doc.content_json), doc.id);
+  const book = new ExcelJS.Workbook();
+  const brief = book.addWorksheet("Brief");
+  const content = JSON.parse(doc.content_json);
+  brief.addRow(["Scenario"]); brief.addRow([content.scenario]); brief.addRow([]);
+  brief.addRow(["Tasks", "Minutes"]);
+  for (const t of wb.tasks) brief.addRow([t.text, t.minutes]);
+  brief.getColumn(1).width = 90;
+  for (const s of wb.sheets) {
+    const ws = book.addWorksheet(s.name);
+    ws.addRow(s.columns);
+    ws.getRow(1).font = { bold: true };
+    for (const row of s.rows) ws.addRow(row);
+    ws.columns.forEach((c) => { c.width = 16; });
+  }
+  const key = book.addWorksheet("AnswerKey");
+  key.addRow(["Task", "Formula (as text)", "Expected"]);
+  for (const k of wb.answerKey) key.addRow([k.task, k.formula, k.expected]);
+  key.getColumn(2).width = 60;
+  const sol = book.addWorksheet("Solution");
+  sol.addRow(["Sheet", "Row", "Kind", "Column", "Was", "Now", "Description"]);
+  for (const p of wb.planted) sol.addRow([p.sheet, p.row, p.kind, p.column || "", p.was == null ? "" : String(p.was), p.now == null ? "" : String(p.now), p.note ? `${p.description} (${p.note})` : p.description]);
+  sol.getColumn(7).width = 70;
+  if (wb.lesson) { sol.addRow([]); sol.addRow(["Lesson", wb.lesson]); }
+  fs.mkdirSync(outDir, { recursive: true });
+  const file = path.join(outDir, `practice-${doc.id.slice(-6).toLowerCase()}.xlsx`);
+  await book.xlsx.writeFile(file);
+  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, planted: wb.planted.length }, at: now });
+  });
+  return { file, rel, planted: wb.planted.length };
+}
+
+module.exports = { writeWorkbook };

package/store/proposals.js

@@ -0,0 +1,119 @@
+"use strict";
+
+/**
+ * ingest_proposal: the typed gateway for model proposals. It can only create
+ * proposed or pending rows: a posting in proposed, a scoring row in
+ * proposed, a gap question, a pending accomplishment. It never runs the
+ * document ledger and never touches trusted state. Every row carries the
+ * actor that proposed it. Budgets are the store's triggers.
+ */
+
+const crypto = require("crypto");
+const { ulid } = require("../core/ulid");
+const { SCHEMAS, validate } = require("../core/schemas");
+const { rulesVersion } = require("../core/rules");
+const { checkCategories, ENGINE_VERSION } = require("./scoring");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+
+const sha = (s) => crypto.createHash("sha256").update(s).digest("hex");
+
+function need(v, name, max = 4000) {
+  const s = typeof v === "string" ? v.trim() : "";
+  if (!s) throw new Error(`${name} is required`);
+  if (s.length > max) throw new Error(`${name} is longer than ${max} characters`);
+  return s;
+}
+
+/** store_posting: idempotent on (candidate, company, title, hash of raw_text); lands proposed. */
+function storePosting(db, { candidate_id, company, title, raw_text, source_url, comp_text, location, now, actor }) {
+  company = need(company, "company", 200);
+  title = need(title, "title", 200);
+  raw_text = need(raw_text, "raw_text", 262144);
+  const hash = sha(raw_text);
+  return withTx(db, (d) => {
+    const existing = d.prepare("SELECT id, status FROM posting WHERE candidate_id = ? AND company = ? AND title = ? AND content_hash = ?").get(candidate_id, company, title, hash);
+    if (existing) return { posting_id: existing.id, status: existing.status, created: false };
+    const id = ulid(Date.parse(now));
+    d.prepare(`INSERT INTO posting (id, candidate_id, company, title, raw_text, content_hash, status, source_url, comp_text, location, captured_at)
+      VALUES (?, ?, ?, ?, ?, ?, 'proposed', ?, ?, ?, ?)`).run(id, candidate_id, company, title, raw_text, hash, source_url || null, comp_text || null, location || null, now);
+    appendEvent(d, { candidate_id, entity: "posting", entity_id: id, event: "proposed", actor_type: actor.type, actor_ref: actor.ref, payload: { company, title, bytes: raw_text.length }, at: now });
+    return { posting_id: id, status: "proposed", created: true };
+  });
+}
+
+/** propose_categories: a scoring row in proposed; every evidence line verbatim or the whole proposal is rejected. */
+function proposeCategories(db, { candidate_id, posting_id, categories, now, actor }) {
+  const p = db.prepare("SELECT id, candidate_id, raw_text FROM posting WHERE id = ?").get(posting_id);
+  if (!p || p.candidate_id !== candidate_id) throw new Error("unknown posting");
+  if (!Array.isArray(categories)) throw new Error("categories must be an array");
+  const cats = categories.map((c) => ({ category: c.category, weight: c.weight, jd_evidence: c.jd_evidence, is_hard_gate: !!c.is_hard_gate }));
+  const errors = checkCategories(cats, p.raw_text);
+  if (errors.length) throw new Error("proposal rejected: " + errors.join("; "));
+  return withTx(db, (d) => {
+    const id = ulid(Date.parse(now));
+    const kb = d.prepare("SELECT kb_revision FROM candidate WHERE id = ?").get(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, entity: "scoring", entity_id: id, event: "proposed", actor_type: actor.type, actor_ref: actor.ref, payload: { posting_id: p.id, categories: cats.length, from: actor.type }, at: now });
+    return { scoring_id: id, status: "proposed", categories: cats.length };
+  });
+}
+
+/** kb_gap_request: a question derived from a posting requirement, for the human to answer. */
+function requestGap(db, { candidate_id, posting_id, requirement_text, question, now, actor }) {
+  const p = db.prepare("SELECT id, candidate_id, raw_text FROM posting WHERE id = ?").get(posting_id);
+  if (!p || p.candidate_id !== candidate_id) throw new Error("unknown posting");
+  requirement_text = need(requirement_text, "requirement_text", 400);
+  question = need(question, "question", 600);
+  if (!p.raw_text.includes(requirement_text)) throw new Error("requirement_text must be a verbatim substring of the posting");
+  return withTx(db, (d) => {
+    const dup = d.prepare("SELECT id FROM kb_gap WHERE posting_id = ? AND requirement_text = ? AND resolved_at IS NULL").get(p.id, requirement_text);
+    if (dup) return { gap_id: dup.id, created: false };
+    const id = ulid(Date.parse(now));
+    d.prepare("INSERT INTO kb_gap (id, candidate_id, posting_id, requirement_text, question, created_at) VALUES (?, ?, ?, ?, ?, ?)").run(id, candidate_id, p.id, requirement_text, question, now);
+    appendEvent(d, { candidate_id, entity: "kb_gap", entity_id: id, event: "requested", actor_type: actor.type, actor_ref: actor.ref, payload: { posting_id: p.id }, at: now });
+    return { gap_id: id, created: true };
+  });
+}
+
+/** propose_accomplishment: a pending row the human confirms on the review screen; 20 open per candidate. */
+function proposeAccomplishment(db, { candidate_id, draft, gap_id, now, actor }) {
+  if (!draft || typeof draft !== "object") throw new Error("draft is required");
+  const clean = {
+    title: need(draft.title, "draft.title", 200), company: need(draft.company, "draft.company", 200), role: need(draft.role, "draft.role", 200),
+    dates: typeof draft.dates === "string" ? draft.dates.slice(0, 60) : "", summary: typeof draft.summary === "string" ? draft.summary.slice(0, 1200) : "",
+    metrics: Array.isArray(draft.metrics) ? draft.metrics.slice(0, 12).map((m) => String(m).slice(0, 80)) : [],
+    verbs: Array.isArray(draft.verbs) ? draft.verbs.slice(0, 8).map((v) => String(v).slice(0, 40)) : [],
+    wordings: Array.isArray(draft.wordings) ? draft.wordings.slice(0, 6).map((w) => String(w).slice(0, 400)) : [],
+  };
+  return withTx(db, (d) => {
+    if (gap_id) {
+      const g = d.prepare("SELECT id FROM kb_gap WHERE id = ? AND candidate_id = ?").get(gap_id, candidate_id);
+      if (!g) throw new Error("unknown gap_id");
+    }
+    const id = ulid(Date.parse(now));
+    try {
+      d.prepare("INSERT INTO pending_accomplishment (id, candidate_id, draft_json, source, gap_id, proposed_at) VALUES (?, ?, ?, ?, ?, ?)")
+        .run(id, candidate_id, JSON.stringify(clean), gap_id ? "gap_answer" : "proposal", gap_id || null, now);
+    } catch (e) {
+      throw new Error(/pending queue is full/.test(e.message) ? "pending queue is full (20 open); the candidate confirms or dismisses first" : e.message);
+    }
+    appendEvent(d, { candidate_id, entity: "pending_accomplishment", entity_id: id, event: "proposed", actor_type: actor.type, actor_ref: actor.ref, payload: { title: clean.title, gap_id: gap_id || null }, at: now });
+    const open = d.prepare("SELECT count(*) c FROM pending_accomplishment WHERE candidate_id = ? AND source <> 'onboarding'").get(candidate_id).c;
+    return { pending_id: id, open, status: "pending" };
+  });
+}
+
+/** The one gateway: kind names the proposal; nothing here can create trusted state. */
+function ingestProposal(db, kind, args) {
+  switch (kind) {
+    case "posting": return storePosting(db, args);
+    case "categories": return proposeCategories(db, args);
+    case "gap": return requestGap(db, args);
+    case "accomplishment": return proposeAccomplishment(db, args);
+    default: throw new Error(`unknown proposal kind ${kind}`);
+  }
+}
+
+module.exports = { ingestProposal, storePosting, proposeCategories, requestGap, proposeAccomplishment };