@gafj/gafj 0.1.1

package/store/snapshot.js

@@ -0,0 +1,88 @@
+"use strict";
+
+/**
+ * campaign_snapshot: the dashboard as a query. now is a parameter; nothing
+ * here reads the clock. Thresholds come from config (plan section O).
+ */
+
+const DEFAULT_THRESHOLDS = {
+  thankyou_due_h: 12, thankyou_overdue_h: 36, default_interview_min: 45,
+  register_switch_window_h: 3, invite_alert_h: 24, aging_days: 7,
+};
+
+const H = 3600 * 1000;
+
+function snapshot(db, { candidate_id, now, thresholds = {} }) {
+  const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  const nowMs = Date.parse(now);
+  const apps = db.prepare(`
+    SELECT a.id, a.status, a.applied_at, a.decision_expected_at, a.notes, p.company, p.title, p.taken_down_at, s.fit_score
+    FROM application a JOIN posting p ON p.id = a.posting_id LEFT JOIN scoring s ON s.id = a.scoring_id
+    WHERE p.candidate_id = ? ORDER BY a.applied_at DESC`).all(candidate_id);
+  const interviews = db.prepare(`
+    SELECT i.*, p.company, p.title, a.status AS app_status
+    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 IN ('scheduled', 'completed') ORDER BY i.scheduled_at`).all(candidate_id);
+  const people = db.prepare(`
+    SELECT ip.interview_id, pe.name FROM interview_person ip JOIN person pe ON pe.id = ip.person_id`).all();
+  const peopleByInterview = new Map();
+  for (const p of people) peopleByInterview.set(p.interview_id, [...(peopleByInterview.get(p.interview_id) || []), p.name]);
+  const passedPrep = new Set(db.prepare("SELECT interview_id FROM document WHERE kind = 'prep' AND status = 'passed'").all().map((r) => r.interview_id));
+  const thanked = new Set(db.prepare("SELECT interview_id FROM communication WHERE kind = 'thankyou' AND interview_id IS NOT NULL").all().map((r) => r.interview_id));
+
+  const needs_you = [];
+  const upcoming = [];
+  for (const iv of interviews) {
+    const at = Date.parse(iv.scheduled_at);
+    const label = `${iv.company} ${iv.round_label}`;
+    if (iv.status === "scheduled" && at >= nowMs) {
+      upcoming.push({ interview_id: iv.id, company: iv.company, title: iv.title, round: iv.round_label, scheduled_at: iv.scheduled_at, tz: iv.tz,
+        format: iv.format, people: peopleByInterview.get(iv.id) || [] });
+      if (!passedPrep.has(iv.id)) needs_you.push({ kind: "prep_not_built", interview_id: iv.id, text: `Prep not built: ${label}` });
+      if (!iv.invite_received_at && at - nowMs <= t.invite_alert_h * H) needs_you.push({ kind: "invite_missing", interview_id: iv.id, text: `Invite not received: ${label}` });
+    }
+    if (iv.status === "completed" && !thanked.has(iv.id)) {
+      const end = Date.parse(iv.completed_at || iv.scheduled_at) + (iv.completed_at ? 0 : t.default_interview_min * 60000);
+      const hours = (nowMs - end) / H;
+      if (hours >= t.thankyou_overdue_h) needs_you.push({ kind: "thankyou_overdue", interview_id: iv.id, text: `Thank-you overdue: ${label} (${Math.floor(hours)}h)` });
+      else if (hours >= t.thankyou_due_h) needs_you.push({ kind: "thankyou_due", interview_id: iv.id, text: `Thank-you due: ${label}` });
+    }
+  }
+  // register switch: two scheduled interviews within the window, different companies or formats
+  const sched = interviews.filter((i) => i.status === "scheduled" && Date.parse(i.scheduled_at) >= nowMs);
+  for (let i = 0; i < sched.length; i++) {
+    for (let j = i + 1; j < sched.length; j++) {
+      const a = sched[i], b = sched[j];
+      const gap = Math.abs(Date.parse(a.scheduled_at) - Date.parse(b.scheduled_at));
+      if (gap <= t.register_switch_window_h * H && (a.company !== b.company || a.format !== b.format)) {
+        needs_you.push({ kind: "register_switch", interview_ids: [a.id, b.id], text: `Register switch: ${a.company} ${a.round_label} then ${b.company} ${b.round_label}` });
+      }
+    }
+  }
+  const review = db.prepare("SELECT metrics_json, verbs_json, verbatim_claims_json FROM accomplishment WHERE candidate_id = ?").all(candidate_id)
+    .reduce((n, r) => n + [...JSON.parse(r.metrics_json), ...JSON.parse(r.verbs_json), ...JSON.parse(r.verbatim_claims_json)]
+      .filter((x) => x.review_state !== "confirmed").length, 0);
+  if (review) needs_you.push({ kind: "review", count: review, text: `Imported dimensions to review: ${review}` });
+
+  const active = [], closed = [], aging = [];
+  for (const a of apps) {
+    const item = { application_id: a.id, company: a.company, title: a.title, status: a.status, fit: a.fit_score, applied_at: a.applied_at,
+      decision_expected_at: a.decision_expected_at, taken_down: !!a.taken_down_at };
+    if (["to_apply", "applied", "offer"].includes(a.status)) {
+      active.push(item);
+      if (a.decision_expected_at && Date.parse(a.decision_expected_at) > nowMs) {
+        aging.push({ ...item, text: `${a.company}: decision expected ${a.decision_expected_at.slice(0, 10)}, do not nudge` });
+      } else if (a.status === "applied" && a.applied_at && (nowMs - Date.parse(a.applied_at)) / (24 * H) >= t.aging_days
+        && !interviews.some((i) => i.application_id === a.id)) {
+        aging.push({ ...item, text: `${a.company}: applied ${Math.floor((nowMs - Date.parse(a.applied_at)) / (24 * H))}d, no reply, nudge?` });
+      } else if (a.status === "to_apply") {
+        aging.push({ ...item, text: `${a.company} ${a.title}: to apply, held` });
+      }
+    } else {
+      closed.push(item);
+    }
+  }
+  return { now, needs_you, upcoming, active, closed, aging, review_count: review };
+}
+
+module.exports = { snapshot, DEFAULT_THRESHOLDS };

package/store/transitions.js

@@ -0,0 +1,391 @@
+"use strict";
+
+/**
+ * UI-only writes (plan sections G and M): the state machines for postings,
+ * applications, interviews, people, and communications. Every unlisted
+ * transition throws a TransitionError carrying the allowed set, which the
+ * API turns into a 409. Every write is one transaction with its event.
+ * The actor is always ui or cli; no model route reaches this file.
+ */
+
+const { ulid } = require("../core/ulid");
+const { assertIanaZone } = require("./tz");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+
+class TransitionError extends Error {
+  constructor(message, allowed) { super(message); this.name = "TransitionError"; this.allowed = allowed || []; this.status = 409; }
+}
+class NotFound extends Error {
+  constructor(what) { super(`unknown ${what}`); this.name = "NotFound"; this.status = 404; }
+}
+
+const APP_NEXT = {
+  to_apply: ["applied", "pass"],
+  applied: ["rejected", "closed", "offer", "pass"],
+  offer: ["closed", "rejected"],
+  rejected: [], closed: [], pass: [],
+};
+const CORRECTIONS = ["applied", "to_apply", "offer"];
+const INTERVIEW_FORMATS = ["screen", "hm", "panel", "technical", "onsite"];
+const OUTCOMES = ["advanced", "rejected", "ghosted"];
+
+function candidateOfApplication(db, id) {
+  const r = db.prepare("SELECT a.*, p.candidate_id, p.company, p.title FROM application a JOIN posting p ON p.id = a.posting_id WHERE a.id = ?").get(id);
+  if (!r) throw new NotFound("application");
+  return r;
+}
+function candidateOfInterview(db, id) {
+  const r = db.prepare("SELECT i.*, p.candidate_id, p.company 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(id);
+  if (!r) throw new NotFound("interview");
+  return r;
+}
+const iso = (s, name) => {
+  if (typeof s !== "string" || !isFinite(Date.parse(s))) throw new TransitionError(`${name} must be an ISO timestamp`);
+  return new Date(Date.parse(s)).toISOString();
+};
+
+// ----- postings -----
+
+function acceptPosting(db, { posting_id, now, actor }) {
+  return withTx(db, (d) => {
+    const p = d.prepare("SELECT id, candidate_id, status FROM posting WHERE id = ?").get(posting_id);
+    if (!p) throw new NotFound("posting");
+    if (p.status !== "proposed") throw new TransitionError(`posting is ${p.status}; only a proposed posting is accepted`, ["proposed"]);
+    d.prepare("UPDATE posting SET status = 'accepted' WHERE id = ?").run(p.id);
+    appendEvent(d, { candidate_id: p.candidate_id, entity: "posting", entity_id: p.id, event: "accepted", actor_type: actor.type, actor_ref: actor.ref, prior: { status: p.status }, at: now });
+    return { posting_id: p.id, status: "accepted" };
+  });
+}
+
+function archivePosting(db, { posting_id, now, actor }) {
+  return withTx(db, (d) => {
+    const p = d.prepare("SELECT id, candidate_id, status FROM posting WHERE id = ?").get(posting_id);
+    if (!p) throw new NotFound("posting");
+    if (p.status === "archived") return { posting_id: p.id, status: "archived" };
+    if (d.prepare("SELECT 1 FROM application WHERE posting_id = ?").get(p.id)) throw new TransitionError("a posting with an application is closed through the application, not archived");
+    d.prepare("UPDATE posting SET status = 'archived' WHERE id = ?").run(p.id);
+    appendEvent(d, { candidate_id: p.candidate_id, entity: "posting", entity_id: p.id, event: "archived", actor_type: actor.type, actor_ref: actor.ref, prior: { status: p.status }, at: now });
+    return { posting_id: p.id, status: "archived" };
+  });
+}
+
+function postingTakenDown(db, { posting_id, now, actor }) {
+  return withTx(db, (d) => {
+    const p = d.prepare("SELECT id, candidate_id, taken_down_at FROM posting WHERE id = ?").get(posting_id);
+    if (!p) throw new NotFound("posting");
+    if (p.taken_down_at) return { posting_id: p.id, taken_down_at: p.taken_down_at };
+    d.prepare("UPDATE posting SET taken_down_at = ? WHERE id = ?").run(now, p.id);
+    appendEvent(d, { candidate_id: p.candidate_id, entity: "posting", entity_id: p.id, event: "taken_down", actor_type: actor.type, actor_ref: actor.ref, at: now });
+    return { posting_id: p.id, taken_down_at: now };
+  });
+}
+
+// ----- applications -----
+
+/** Log an application for an accepted posting with frozen scoring. */
+function logApplication(db, { posting_id, status = "to_apply", now, actor }) {
+  return withTx(db, (d) => {
+    const p = d.prepare("SELECT id, candidate_id, status FROM posting WHERE id = ?").get(posting_id);
+    if (!p) throw new NotFound("posting");
+    if (p.status !== "accepted") throw new TransitionError("applications require an accepted posting", ["accepted"]);
+    if (d.prepare("SELECT id FROM application WHERE posting_id = ?").get(p.id)) throw new TransitionError("this posting already has an application");
+    const scoring = d.prepare("SELECT id FROM scoring WHERE posting_id = ? AND status = 'frozen' ORDER BY scored_at DESC, rowid DESC LIMIT 1").get(p.id);
+    if (!scoring) throw new TransitionError("freeze the scoring before logging an application");
+    if (!["to_apply", "applied"].includes(status)) throw new TransitionError("a new application is to_apply or applied", ["to_apply", "applied"]);
+    const id = ulid(Date.parse(now));
+    d.prepare("INSERT INTO application (id, posting_id, status, applied_at, scoring_id) VALUES (?, ?, ?, ?, ?)").run(id, p.id, status, status === "applied" ? now : null, scoring.id);
+    appendEvent(d, { candidate_id: p.candidate_id, entity: "application", entity_id: id, event: "logged", actor_type: actor.type, actor_ref: actor.ref, payload: { status }, at: now });
+    return { application_id: id, status };
+  });
+}
+
+/** Forward transitions per section M. applied requires a passed resume for this posting. */
+function updateStatus(db, { application_id, status, resume_doc_id, cover_doc_id, now, actor }) {
+  return withTx(db, (d) => {
+    const a = candidateOfApplication(d, application_id);
+    const allowed = APP_NEXT[a.status] || [];
+    if (!allowed.includes(status)) throw new TransitionError(`${a.status} cannot move to ${status}`, allowed);
+    if (status === "applied") {
+      const doc = resume_doc_id || a.resume_doc_id;
+      if (!doc) throw new TransitionError("applied needs a passed resume (resume_doc_id) for this posting");
+      const ok = d.prepare("SELECT 1 FROM document WHERE id = ? AND kind = 'resume' AND status = 'passed' AND posting_id = ?").get(doc, a.posting_id);
+      if (!ok) throw new TransitionError("resume_doc_id must be a passed resume for this posting");
+      const scoring = d.prepare("SELECT id FROM scoring WHERE posting_id = ? AND status = 'frozen' ORDER BY scored_at DESC, rowid DESC LIMIT 1").get(a.posting_id);
+      d.prepare("UPDATE application SET status = 'applied', applied_at = ?, resume_doc_id = ?, cover_doc_id = coalesce(?, cover_doc_id), scoring_id = ? WHERE id = ?")
+        .run(now, doc, cover_doc_id || null, scoring ? scoring.id : a.scoring_id, a.id);
+    } else {
+      d.prepare("UPDATE application SET status = ? WHERE id = ?").run(status, a.id);
+      if (status === "closed" || status === "rejected" || status === "pass") {
+        for (const iv of d.prepare("SELECT id FROM interview WHERE application_id = ? AND status = 'scheduled'").all(a.id)) {
+          d.prepare("UPDATE interview SET status = 'cancelled' WHERE id = ?").run(iv.id);
+          appendEvent(d, { candidate_id: a.candidate_id, entity: "interview", entity_id: iv.id, event: "cancelled", actor_type: actor.type, actor_ref: actor.ref, payload: { reason: "application " + status }, at: now });
+        }
+      }
+    }
+    appendEvent(d, { candidate_id: a.candidate_id, entity: "application", entity_id: a.id, event: "status", actor_type: actor.type, actor_ref: actor.ref, payload: { status }, prior: { status: a.status }, at: now });
+    return { application_id: a.id, status };
+  });
+}
+
+/** A named correction with a reason; the prior state is on the event. */
+function correctStatus(db, { application_id, status, reason, now, actor }) {
+  if (!reason || !String(reason).trim()) throw new TransitionError("a correction needs a reason");
+  if (!CORRECTIONS.includes(status)) throw new TransitionError(`a correction moves to one of ${CORRECTIONS.join(", ")}`, CORRECTIONS);
+  return withTx(db, (d) => {
+    const a = candidateOfApplication(d, application_id);
+    d.prepare("UPDATE application SET status = ? WHERE id = ?").run(status, a.id);
+    appendEvent(d, { candidate_id: a.candidate_id, entity: "application", entity_id: a.id, event: "corrected", actor_type: actor.type, actor_ref: actor.ref, payload: { status, reason }, prior: { status: a.status }, at: now });
+    return { application_id: a.id, status };
+  });
+}
+
+function setDecisionExpected(db, { application_id, at, now, actor }) {
+  return withTx(db, (d) => {
+    const a = candidateOfApplication(d, application_id);
+    const when = at ? iso(at, "decision_expected_at") : null;
+    d.prepare("UPDATE application SET decision_expected_at = ? WHERE id = ?").run(when, a.id);
+    appendEvent(d, { candidate_id: a.candidate_id, entity: "application", entity_id: a.id, event: "decision_expected", actor_type: actor.type, actor_ref: actor.ref, payload: { at: when }, prior: { decision_expected_at: a.decision_expected_at }, at: now });
+    return { application_id: a.id, decision_expected_at: when };
+  });
+}
+
+function setNotes(db, { application_id, notes, now, actor }) {
+  return withTx(db, (d) => {
+    const a = candidateOfApplication(d, application_id);
+    d.prepare("UPDATE application SET notes = ? WHERE id = ?").run(String(notes || "").slice(0, 4000), a.id);
+    appendEvent(d, { candidate_id: a.candidate_id, entity: "application", entity_id: a.id, event: "notes", actor_type: actor.type, actor_ref: actor.ref, prior: { notes: a.notes }, at: now });
+    return { application_id: a.id };
+  });
+}
+
+// ----- interviews -----
+
+function scheduleInterview(db, { application_id, round_label, scheduled_at, tz, format, invite_received_at, people = [], now, actor }) {
+  if (!round_label || !String(round_label).trim()) throw new TransitionError("round_label is required");
+  if (!INTERVIEW_FORMATS.includes(format)) throw new TransitionError(`format must be one of ${INTERVIEW_FORMATS.join(", ")}`, INTERVIEW_FORMATS);
+  assertIanaZone(tz);
+  const at = iso(scheduled_at, "scheduled_at");
+  return withTx(db, (d) => {
+    const a = candidateOfApplication(d, application_id);
+    if (!["to_apply", "applied", "offer"].includes(a.status)) throw new TransitionError(`no interviews on a ${a.status} application`);
+    if (d.prepare("SELECT 1 FROM interview WHERE application_id = ? AND round_label = ? AND status = 'scheduled'").get(a.id, round_label)) {
+      throw new TransitionError(`${round_label} is already scheduled; reschedule it instead`);
+    }
+    const id = ulid(Date.parse(now));
+    d.prepare("INSERT INTO interview (id, application_id, round_label, scheduled_at, tz, format, status, invite_received_at) VALUES (?, ?, ?, ?, ?, ?, 'scheduled', ?)")
+      .run(id, a.id, String(round_label).trim(), at, tz, format, invite_received_at ? iso(invite_received_at, "invite_received_at") : null);
+    appendEvent(d, { candidate_id: a.candidate_id, entity: "interview", entity_id: id, event: "scheduled", actor_type: actor.type, actor_ref: actor.ref, payload: { round_label, scheduled_at: at, tz, format }, at: now });
+    for (const p of people) attachPersonToInterview(d, { interview_id: id, person: p, now, actor });
+    return { interview_id: id };
+  });
+}
+
+/** Reschedule inserts a superseding row; the old row becomes superseded and keeps its history. */
+function rescheduleInterview(db, { interview_id, scheduled_at, tz, format, now, actor }) {
+  const at = iso(scheduled_at, "scheduled_at");
+  if (tz) assertIanaZone(tz);
+  return withTx(db, (d) => {
+    const i = candidateOfInterview(d, interview_id);
+    if (i.status !== "scheduled") throw new TransitionError(`only a scheduled interview reschedules; this one is ${i.status}`, ["scheduled"]);
+    d.prepare("UPDATE interview SET status = 'superseded' WHERE id = ?").run(i.id);
+    const id = ulid(Date.parse(now));
+    d.prepare(`INSERT INTO interview (id, application_id, round_label, scheduled_at, tz, format, status, invite_received_at, supersedes_id, pinned_ids_json)
+      VALUES (?, ?, ?, ?, ?, ?, 'scheduled', ?, ?, ?)`).run(id, i.application_id, i.round_label, at, tz || i.tz, format || i.format, i.invite_received_at, i.id, i.pinned_ids_json);
+    for (const p of d.prepare("SELECT person_id FROM interview_person WHERE interview_id = ?").all(i.id)) d.prepare("INSERT INTO interview_person (interview_id, person_id) VALUES (?, ?)").run(id, p.person_id);
+    appendEvent(d, { candidate_id: i.candidate_id, entity: "interview", entity_id: id, event: "rescheduled", actor_type: actor.type, actor_ref: actor.ref, payload: { supersedes: i.id, scheduled_at: at, tz: tz || i.tz }, prior: { scheduled_at: i.scheduled_at, tz: i.tz }, at: now });
+    return { interview_id: id, supersedes: i.id };
+  });
+}
+
+function completeInterview(db, { interview_id, completed_at, outcome, now, actor }) {
+  return withTx(db, (d) => {
+    const i = candidateOfInterview(d, interview_id);
+    if (i.status !== "scheduled") throw new TransitionError(`only a scheduled interview completes; this one is ${i.status}`, ["scheduled"]);
+    const at = completed_at ? iso(completed_at, "completed_at") : now;
+    if (outcome && !OUTCOMES.includes(outcome)) throw new TransitionError(`outcome must be one of ${OUTCOMES.join(", ")}`, OUTCOMES);
+    d.prepare("UPDATE interview SET status = 'completed', completed_at = ?, outcome = coalesce(?, outcome) WHERE id = ?").run(at, outcome || null, i.id);
+    appendEvent(d, { candidate_id: i.candidate_id, entity: "interview", entity_id: i.id, event: "completed", actor_type: actor.type, actor_ref: actor.ref, payload: { completed_at: at, outcome: outcome || null }, at: now });
+    return { interview_id: i.id, status: "completed", completed_at: at };
+  });
+}
+
+function setOutcome(db, { interview_id, outcome, now, actor }) {
+  if (!OUTCOMES.includes(outcome)) throw new TransitionError(`outcome must be one of ${OUTCOMES.join(", ")}`, OUTCOMES);
+  return withTx(db, (d) => {
+    const i = candidateOfInterview(d, interview_id);
+    if (i.status !== "completed") throw new TransitionError("an outcome is set only after the interview is completed", ["completed"]);
+    d.prepare("UPDATE interview SET outcome = ? WHERE id = ?").run(outcome, i.id);
+    appendEvent(d, { candidate_id: i.candidate_id, entity: "interview", entity_id: i.id, event: "outcome", actor_type: actor.type, actor_ref: actor.ref, payload: { outcome }, prior: { outcome: i.outcome }, at: now });
+    return { interview_id: i.id, outcome };
+  });
+}
+
+function cancelInterview(db, { interview_id, now, actor }) {
+  return withTx(db, (d) => {
+    const i = candidateOfInterview(d, interview_id);
+    if (i.status !== "scheduled") throw new TransitionError(`only a scheduled interview cancels; this one is ${i.status}`, ["scheduled"]);
+    d.prepare("UPDATE interview SET status = 'cancelled' WHERE id = ?").run(i.id);
+    appendEvent(d, { candidate_id: i.candidate_id, entity: "interview", entity_id: i.id, event: "cancelled", actor_type: actor.type, actor_ref: actor.ref, at: now });
+    return { interview_id: i.id, status: "cancelled" };
+  });
+}
+
+function inviteReceived(db, { interview_id, at, now, actor }) {
+  return withTx(db, (d) => {
+    const i = candidateOfInterview(d, interview_id);
+    const when = at ? iso(at, "invite_received_at") : now;
+    d.prepare("UPDATE interview SET invite_received_at = ? WHERE id = ?").run(when, i.id);
+    appendEvent(d, { candidate_id: i.candidate_id, entity: "interview", entity_id: i.id, event: "invite_received", actor_type: actor.type, actor_ref: actor.ref, payload: { at: when }, at: now });
+    return { interview_id: i.id, invite_received_at: when };
+  });
+}
+
+/** Debrief text is ground truth for later packets; capped at 64 KB by the store. */
+function captureDebrief(db, { interview_id, text, now, actor }) {
+  const t = String(text || "").trim();
+  if (!t) throw new TransitionError("debrief text is required");
+  if (t.length > 65536) throw new TransitionError("debrief is longer than 64 KB");
+  return withTx(db, (d) => {
+    const i = candidateOfInterview(d, interview_id);
+    if (i.status !== "completed") throw new TransitionError("a debrief is captured after the interview is marked completed", ["completed"]);
+    d.prepare("UPDATE interview SET debrief_text = ?, debrief_captured_at = ? WHERE id = ?").run(t, now, i.id);
+    appendEvent(d, { candidate_id: i.candidate_id, entity: "interview", entity_id: i.id, event: "debrief", actor_type: actor.type, actor_ref: actor.ref, payload: { chars: t.length }, prior: { debrief_text: i.debrief_text }, at: now });
+    return { interview_id: i.id, debrief_captured_at: now };
+  });
+}
+
+function pinStories(db, { interview_id, ids, now, actor }) {
+  if (!Array.isArray(ids)) throw new TransitionError("ids must be an array of record ids");
+  return withTx(db, (d) => {
+    const i = candidateOfInterview(d, interview_id);
+    const known = new Set(d.prepare("SELECT id FROM accomplishment WHERE candidate_id = ?").all(i.candidate_id).map((r) => r.id));
+    const bad = ids.filter((x) => !known.has(x));
+    if (bad.length) throw new TransitionError(`unknown record ids: ${bad.join(", ")}`);
+    const clean = [...new Set(ids)].slice(0, 12);
+    d.prepare("UPDATE interview SET pinned_ids_json = ? WHERE id = ?").run(JSON.stringify(clean), i.id);
+    appendEvent(d, { candidate_id: i.candidate_id, entity: "interview", entity_id: i.id, event: "pinned", actor_type: actor.type, actor_ref: actor.ref, payload: { ids: clean }, prior: { pinned_ids_json: i.pinned_ids_json }, at: now });
+    return { interview_id: i.id, pinned_ids: clean };
+  });
+}
+
+// ----- people -----
+
+function canonicalPerson(d, id) {
+  let p = d.prepare("SELECT * FROM person WHERE id = ?").get(id);
+  let hops = 0;
+  while (p && p.merged_into_id && hops++ < 10) p = d.prepare("SELECT * FROM person WHERE id = ?").get(p.merged_into_id);
+  return p;
+}
+
+/** Partial identity is allowed: a first name alone creates a row; merge later when the surname lands. */
+function addPerson(db, { candidate_id, name, title, org, intel_text, links, now, actor }) {
+  const n = String(name || "").trim();
+  if (!n) throw new TransitionError("name is required");
+  return withTx(db, (d) => {
+    const id = ulid(Date.parse(now));
+    d.prepare("INSERT INTO person (id, candidate_id, name, title, org, intel_text, links_json, first_seen_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
+      .run(id, candidate_id, n.slice(0, 200), title ? String(title).slice(0, 200) : null, org ? String(org).slice(0, 200) : null, intel_text ? String(intel_text).slice(0, 8000) : null, JSON.stringify(Array.isArray(links) ? links.slice(0, 10) : []), now);
+    appendEvent(d, { candidate_id, entity: "person", entity_id: id, event: "added", actor_type: actor.type, actor_ref: actor.ref, payload: { name: n }, at: now });
+    return { person_id: id };
+  });
+}
+
+function updatePerson(db, { person_id, title, org, intel_text, now, actor }) {
+  return withTx(db, (d) => {
+    const p = canonicalPerson(d, person_id);
+    if (!p) throw new NotFound("person");
+    d.prepare("UPDATE person SET title = coalesce(?, title), org = coalesce(?, org), intel_text = coalesce(?, intel_text) WHERE id = ?")
+      .run(title != null ? String(title).slice(0, 200) : null, org != null ? String(org).slice(0, 200) : null, intel_text != null ? String(intel_text).slice(0, 8000) : null, p.id);
+    appendEvent(d, { candidate_id: p.candidate_id, entity: "person", entity_id: p.id, event: "updated", actor_type: actor.type, actor_ref: actor.ref, prior: { title: p.title, org: p.org, intel_text: p.intel_text }, at: now });
+    return { person_id: p.id };
+  });
+}
+
+/** person: { person_id } or { name, title?, org?, intel_text? } (created on the spot). */
+function resolvePerson(d, candidate_id, person, now, actor) {
+  if (person && person.person_id) {
+    const p = canonicalPerson(d, person.person_id);
+    if (!p || p.candidate_id !== candidate_id) throw new NotFound("person");
+    return p.id;
+  }
+  return addPerson(d, { candidate_id, ...person, now, actor }).person_id;
+}
+
+function attachPersonToInterview(db, { interview_id, person, now, actor }) {
+  return withTx(db, (d) => {
+    const i = candidateOfInterview(d, interview_id);
+    const pid = resolvePerson(d, i.candidate_id, person, now, actor);
+    d.prepare("INSERT OR IGNORE INTO interview_person (interview_id, person_id) VALUES (?, ?)").run(i.id, pid);
+    d.prepare("INSERT OR IGNORE INTO application_person (application_id, person_id, role) VALUES (?, ?, 'interviewer')").run(i.application_id, pid);
+    appendEvent(d, { candidate_id: i.candidate_id, entity: "interview", entity_id: i.id, event: "person_attached", actor_type: actor.type, actor_ref: actor.ref, payload: { person_id: pid }, at: now });
+    return { interview_id: i.id, person_id: pid };
+  });
+}
+
+function attachPersonToApplication(db, { application_id, person, role = "other", now, actor }) {
+  if (!["interviewer", "recruiter", "referral", "other"].includes(role)) throw new TransitionError("role must be interviewer, recruiter, referral, or other");
+  return withTx(db, (d) => {
+    const a = candidateOfApplication(d, application_id);
+    const pid = resolvePerson(d, a.candidate_id, person, now, actor);
+    d.prepare("INSERT OR IGNORE INTO application_person (application_id, person_id, role) VALUES (?, ?, ?)").run(a.id, pid, role);
+    appendEvent(d, { candidate_id: a.candidate_id, entity: "application", entity_id: a.id, event: "person_attached", actor_type: actor.type, actor_ref: actor.ref, payload: { person_id: pid, role }, at: now });
+    return { application_id: a.id, person_id: pid };
+  });
+}
+
+/** Merge sets merged_into_id and repoints every join in one transaction; old ids keep resolving through canonical_person. */
+function mergePerson(db, { person_id, into_id, now, actor }) {
+  if (person_id === into_id) throw new TransitionError("a person cannot merge into itself");
+  return withTx(db, (d) => {
+    const from = d.prepare("SELECT * FROM person WHERE id = ?").get(person_id);
+    const into = canonicalPerson(d, into_id);
+    if (!from || !into) throw new NotFound("person");
+    if (from.candidate_id !== into.candidate_id) throw new TransitionError("people belong to different candidates");
+    if (from.merged_into_id) throw new TransitionError("already merged");
+    for (const r of d.prepare("SELECT interview_id FROM interview_person WHERE person_id = ?").all(from.id)) {
+      d.prepare("INSERT OR IGNORE INTO interview_person (interview_id, person_id) VALUES (?, ?)").run(r.interview_id, into.id);
+    }
+    d.prepare("DELETE FROM interview_person WHERE person_id = ?").run(from.id);
+    for (const r of d.prepare("SELECT application_id, role FROM application_person WHERE person_id = ?").all(from.id)) {
+      d.prepare("INSERT OR IGNORE INTO application_person (application_id, person_id, role) VALUES (?, ?, ?)").run(r.application_id, into.id, r.role);
+    }
+    d.prepare("DELETE FROM application_person WHERE person_id = ?").run(from.id);
+    d.prepare("UPDATE person SET merged_into_id = ?, title = coalesce(title, ?), org = coalesce(org, ?) WHERE id = ?").run(into.id, from.title, from.org, from.id);
+    d.prepare("UPDATE person SET title = coalesce(title, ?), org = coalesce(org, ?), intel_text = CASE WHEN intel_text IS NULL THEN ? ELSE intel_text END WHERE id = ?").run(from.title, from.org, from.intel_text, into.id);
+    appendEvent(d, { candidate_id: from.candidate_id, entity: "person", entity_id: from.id, event: "merged", actor_type: actor.type, actor_ref: actor.ref, payload: { into: into.id }, prior: { name: from.name }, at: now });
+    return { person_id: from.id, into_id: into.id };
+  });
+}
+
+// ----- communications -----
+
+/** "Mark sent": the communication row against a passed draft, body only when it changed. */
+function markSent(db, { application_id, interview_id, kind, document_id, to_addr, sent_body_text, sent_at, now, actor }) {
+  if (!["thankyou", "nudge", "negotiation", "other"].includes(kind)) throw new TransitionError("kind must be thankyou, nudge, negotiation, or other");
+  return withTx(db, (d) => {
+    const a = candidateOfApplication(d, application_id);
+    if (interview_id) {
+      const i = d.prepare("SELECT application_id FROM interview WHERE id = ?").get(interview_id);
+      if (!i || i.application_id !== a.id) throw new TransitionError("the interview is not on this application");
+    }
+    if (document_id) {
+      const doc = d.prepare("SELECT status, kind FROM document WHERE id = ?").get(document_id);
+      if (!doc || doc.status !== "passed" || doc.kind !== "email") throw new TransitionError("document_id must be a passed email draft");
+    }
+    const id = ulid(Date.parse(now));
+    d.prepare("INSERT INTO communication (id, application_id, interview_id, kind, document_id, to_addr, sent_at, sent_body_text) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
+      .run(id, a.id, interview_id || null, kind, document_id || null, to_addr ? String(to_addr).slice(0, 300) : null, sent_at ? iso(sent_at, "sent_at") : now, sent_body_text ? String(sent_body_text).slice(0, 20000) : null);
+    appendEvent(d, { candidate_id: a.candidate_id, entity: "communication", entity_id: id, event: "sent", actor_type: actor.type, actor_ref: actor.ref, payload: { kind, interview_id: interview_id || null, document_id: document_id || null }, at: now });
+    return { communication_id: id };
+  });
+}
+
+module.exports = {
+  TransitionError, NotFound, APP_NEXT, INTERVIEW_FORMATS, OUTCOMES,
+  acceptPosting, archivePosting, postingTakenDown,
+  logApplication, updateStatus, correctStatus, setDecisionExpected, setNotes,
+  scheduleInterview, rescheduleInterview, completeInterview, setOutcome, cancelInterview, inviteReceived, captureDebrief, pinStories,
+  addPerson, updatePerson, attachPersonToInterview, attachPersonToApplication, mergePerson, canonicalPerson,
+  markSent,
+};

package/store/tx.js

@@ -0,0 +1,71 @@
+"use strict";
+
+/**
+ * withTx(db, fn): BEGIN IMMEDIATE, fn(db), COMMIT. On SQLITE_BUSY or
+ * SQLITE_LOCKED the transaction is rolled back and retried with backoff, up
+ * to a cap. A lock failure is never surfaced as a tool error a model could
+ * narrate; after the cap it becomes a plain Error naming the cause.
+ *
+ * DatabaseSync is synchronous, so the backoff is a synchronous wait on a
+ * SharedArrayBuffer. That is deliberate: there is nothing else this process
+ * could usefully do while it holds no lock.
+ */
+
+const SQLITE_BUSY = 5;
+const SQLITE_LOCKED = 6;
+const RETRIES = 5;
+
+function isLockError(e) {
+  const code = e && (e.errcode ?? e.code);
+  return code === SQLITE_BUSY || code === SQLITE_LOCKED ||
+    /database is locked|database table is locked/i.test(String(e && e.message));
+}
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+const IN_TX = new WeakSet();
+
+function withTx(db, fn, opts = {}) {
+  if (IN_TX.has(db)) return fn(db);
+  IN_TX.add(db);
+  try {
+    return withTxInner(db, fn, opts);
+  } finally { IN_TX.delete(db); }
+}
+
+function withTxInner(db, fn, opts = {}) {
+  const retries = opts.retries ?? RETRIES;
+  const log = opts.log || (() => {});
+  let attempt = 0;
+  for (;;) {
+    try {
+      db.exec("BEGIN IMMEDIATE");
+    } catch (e) {
+      if (isLockError(e) && attempt < retries) {
+        attempt++;
+        log({ event: "tx_busy", attempt });
+        sleepSync(25 * 2 ** attempt);
+        continue;
+      }
+      throw new Error(`store busy after ${attempt} retries: ${e.message}`);
+    }
+    try {
+      const out = fn(db);
+      db.exec("COMMIT");
+      return out;
+    } catch (e) {
+      try { db.exec("ROLLBACK"); } catch (_) { /* already rolled back */ }
+      if (isLockError(e) && attempt < retries) {
+        attempt++;
+        log({ event: "tx_busy", attempt });
+        sleepSync(25 * 2 ** attempt);
+        continue;
+      }
+      throw e;
+    }
+  }
+}
+
+module.exports = { withTx, isLockError, RETRIES };

package/store/tz.js

@@ -0,0 +1,24 @@
+"use strict";
+
+/**
+ * Interview time zones are IANA names or nothing. "CET", "EST", "CT", "PT"
+ * are labels, not zones, and a label entered as a zone is how a 1 PM Eastern
+ * invite becomes a missed noon Central call. Display code may derive a label
+ * from the zone; the store only stores the zone.
+ */
+
+const ZONES = new Set(Intl.supportedValuesOf("timeZone"));
+ZONES.add("UTC");
+
+function isIanaZone(name) {
+  return typeof name === "string" && ZONES.has(name);
+}
+
+function assertIanaZone(name) {
+  if (!isIanaZone(name)) {
+    throw new Error(`tz must be an IANA zone such as America/Chicago, not ${JSON.stringify(name)}`);
+  }
+  return name;
+}
+
+module.exports = { isIanaZone, assertIanaZone };