@gafj/gafj 0.1.15 → 0.1.17

package/bridge/byo_key.js

@@ -70,7 +70,7 @@ async function runPacket(homeDir, id, { packet, fetchImpl }) {
   const started = Date.now();
   try {
     const op = packet.operation || packet.op;
-    const r = await adapter.complete({ provider: p, system: "You are a careful writing engine. Reply with exactly one fenced json block matching OUTPUT SCHEMA and nothing else. Write the JSON compact, on one line, with no indentation and no spaces after commas or colons.", user: renderPasteText(packet), max_tokens: MAX_OUT[op] || 16000, effort: EFFORT[op], fetch: fetchImpl });
+    const r = await adapter.complete({ provider: p, system: "You are a careful writing engine. Reply with exactly one fenced json block matching OUTPUT SCHEMA and nothing else. Write the JSON compact, on one line, with no indentation and no spaces after commas or colons.", user: renderPasteText(packet), max_tokens: MAX_OUT[op] || 16000, effort: EFFORT[op], schema: packet.output_schema, fetch: fetchImpl });
     return { content: r.text, provider: p.kind, model: r.model || p.model, tokens_in: r.tokens_in, tokens_out: r.tokens_out, latency_ms: Date.now() - started, stop_reason: r.stop_reason || null };
   } catch (e) {
     throw Object.assign(new Error(scrub(e.message, p.api_key)), { status: 502 });

package/bridge/providers/anthropic.js

@@ -9,12 +9,31 @@ const DEFAULT_MODEL = "claude-sonnet-5";
  * passes effort ("low" for extraction) and it goes out as output_config.effort; the thinking
  * parameter itself is never sent, which is the setting every current model accepts.
  */
-async function complete({ provider, system, user, max_tokens = 4000, effort, fetch }) {
+/**
+ * The API's structured-output mode accepts a subset of JSON Schema: no length, range, or count
+ * limits, no vendor keys. This strips those so the schema the store validates against can be
+ * handed to the model as the shape it must produce. Enums, required, and additionalProperties
+ * stay, which is what makes the reply valid by construction.
+ */
+const DROP = new Set(["maxLength", "minLength", "minimum", "maximum", "minItems", "maxItems", "multipleOf", "pattern", "format"]);
+function strictSchema(node) {
+  if (Array.isArray(node)) return node.map(strictSchema);
+  if (!node || typeof node !== "object") return node;
+  const out = {};
+  for (const [k, v] of Object.entries(node)) {
+    if (DROP.has(k) || k.startsWith("x-")) continue;
+    out[k] = k === "properties" ? Object.fromEntries(Object.entries(v).map(([pk, pv]) => [pk, strictSchema(pv)])) : strictSchema(v);
+  }
+  return out;
+}
+
+async function complete({ provider, system, user, max_tokens = 4000, effort, schema, fetch }) {
   const { post } = require("./index");
   const base = (provider.base_url || DEFAULT_URL).replace(/\/$/, "");
   const model = provider.model || DEFAULT_MODEL;
   const body = { model, max_tokens, system, messages: [{ role: "user", content: user }] };
-  if (effort) body.output_config = { effort };
+  const usable = schema && typeof schema === "object" && schema.type === "object" && schema.properties && Object.keys(schema.properties).length;
+  if (effort || usable) body.output_config = { ...(effort ? { effort } : {}), ...(usable ? { format: { type: "json_schema", schema: strictSchema(schema) } } : {}) };
   const data = await post(fetch, `${base}/v1/messages`, { "x-api-key": provider.api_key || "", "anthropic-version": "2023-06-01" }, body);
   if (data.stop_reason === "refusal") throw new Error(`the model declined this request${data.stop_details && data.stop_details.category ? ` (${data.stop_details.category})` : ""}`);
   const text = (data.content || []).filter((c) => c.type === "text").map((c) => c.text).join("\n");
@@ -29,4 +48,4 @@ async function listModels({ provider, fetch }) {
   return (data.data || []).map((m) => ({ id: m.id, name: m.display_name || m.id, created: m.created_at || null }));
 }
 
-module.exports = { complete, listModels, DEFAULT_URL, DEFAULT_MODEL };
+module.exports = { complete, listModels, strictSchema, DEFAULT_URL, DEFAULT_MODEL };

package/core/migrations/004-position.sql

@@ -0,0 +1,24 @@
+-- v4: positions. One row per job (employer and role), and likewise per school, volunteer role,
+-- award, certification, or affiliation, proposed from what the model quoted and confirmed once;
+-- the records under a job inherit its company, role, and dates, so a tenure is corrected in one
+-- place instead of on thirty bullets. The other kinds carry no records; they are the resume's
+-- own sections, kept as facts the candidate confirmed.
+CREATE TABLE position (
+  id TEXT PRIMARY KEY,
+  candidate_id TEXT NOT NULL REFERENCES candidate(id),
+  kind TEXT NOT NULL DEFAULT 'employment' CHECK (kind IN ('employment', 'education', 'volunteer', 'award', 'certification', 'affiliation')),
+  company TEXT NOT NULL,
+  role TEXT NOT NULL,
+  location TEXT,
+  date_start TEXT,
+  date_end TEXT,
+  dates_text TEXT,
+  detail TEXT,
+  status TEXT NOT NULL CHECK (status IN ('proposed', 'confirmed')),
+  source_document_id TEXT REFERENCES source_document(id) ON DELETE SET NULL,
+  created_at TEXT NOT NULL,
+  confirmed_at TEXT
+);
+CREATE INDEX position_candidate ON position(candidate_id);
+ALTER TABLE pending_accomplishment ADD COLUMN position_id TEXT REFERENCES position(id) ON DELETE SET NULL;
+ALTER TABLE accomplishment ADD COLUMN position_id TEXT REFERENCES position(id) ON DELETE SET NULL;

package/core/rules/extract.md

@@ -22,6 +22,10 @@ The ownership verb is the lead verb of the wording, in the form the source uses.
 
 The bullet or sentence that states the result, verbatim; usually one, at most three when the source states the same result more than once. The first wording is the one you would recommend. Never repeat a wording across records. Keep the source's punctuation.
 
+## The other sections
+
+Education, volunteer and community work, awards, certifications and licences, memberships and affiliations go in `entries`, one each, never as accomplishments. `org` is the school, organisation, or issuer as written; `title` the degree, role, award, or credential as written; `dates` as written; `detail` one quoted line if the source gives one (honours, GPA, a description). Quote each; leave out what the source does not state. Employment itself is not an entry: it is carried by the accomplishments' company, role, and dates.
+
 ## Style observed
 
 Report what the source does: dashes (none, hyphens, em dashes, mixed), how it spells ecommerce, whether percent is a symbol or a word. Observations only; the candidate chooses their house rules.

package/core/schemas/extract.js

@@ -25,6 +25,14 @@ module.exports = obj({
     scope: ATOM,
     tags: arr(str("identifier", { max: 40 }), 0, 8),
   }, ["title", "company", "role", "wordings"]), 1, 40),
+  // the resume's other sections, each an org, a title, dates, and one line of detail, all quoted
+  entries: arr(obj({
+    kind: str("identifier", { enum: ["education", "volunteer", "award", "certification", "affiliation"] }),
+    org: ATOM,
+    title: ATOM,
+    dates: ATOM,
+    detail: ATOM,
+  }, ["kind", "org", "title"]), 0, 30),
   style_observed: obj({
     dashes: str("identifier", { enum: ["none", "hyphens", "em_dashes", "mixed"] }),
     ecommerce_spelling: str("identifier", { max: 20 }),

package/http/api.js

@@ -143,6 +143,13 @@ route("POST", "/api/postings/:id/freeze", (c, p, b) => freezeScoring(c.db, { pos
 const kb = require("../store/kb");
 route("GET", "/api/kb", (c) => ({ ...kb.summary(c.db, c.candidate_id), gaps: kb.listGaps(c.db, c.candidate_id), holes: kb.listHoles(c.db, c.candidate_id), questions: require("../store/discover").listQuestions(c.db, c.candidate_id), pending: kb.listPending(c.db, c.candidate_id), review: listReview(c.db, c.candidate_id, {}) }));
 route("POST", "/api/kb/gaps/:id/answer", (c, p, b) => kb.answerGap(c.db, { candidate_id: c.candidate_id, gap_id: p.id, draft: need(b, "draft"), now: c.now(), actor: ACTOR("answer_gap") }));
+const positions = require("../store/positions");
+route("GET", "/api/kb/positions", (c) => positions.list(c.db, c.candidate_id, { now: c.now() }));
+route("POST", "/api/kb/positions", (c, p, b) => positions.create(c.db, { candidate_id: c.candidate_id, kind: b.kind || "employment", edits: b.edits || b, now: c.now(), actor: ACTOR("write_position") }));
+route("POST", "/api/kb/positions/merge", (c, p, b) => positions.merge(c.db, { candidate_id: c.candidate_id, keep_id: need(b, "keep_id"), drop_id: need(b, "drop_id"), now: c.now(), actor: ACTOR("merge_position") }));
+route("POST", "/api/kb/positions/:id", (c, p, b) => positions.update(c.db, { candidate_id: c.candidate_id, position_id: p.id, edits: b.edits || b, confirm: !!b.confirm, now: c.now(), actor: ACTOR("edit_position") }));
+route("POST", "/api/kb/positions/:id/confirm", (c, p, b) => positions.update(c.db, { candidate_id: c.candidate_id, position_id: p.id, edits: b.edits || {}, confirm: true, now: c.now(), actor: ACTOR("confirm_position") }));
+route("DELETE", "/api/kb/positions/:id", (c, p) => positions.remove(c.db, { candidate_id: c.candidate_id, position_id: p.id, now: c.now(), actor: ACTOR("remove_position") }));
 route("POST", "/api/kb/pending", (c, p, b) => kb.proposeManual(c.db, { candidate_id: c.candidate_id, draft: need(b, "draft"), now: c.now(), actor: ACTOR("propose_manual") }));
 route("POST", "/api/kb/pending/:id/confirm", (c, p, b) => kb.confirmPending(c.db, { candidate_id: c.candidate_id, pending_id: p.id, edits: b.edits || {}, now: c.now(), actor: ACTOR("confirm_accomplishment") }));
 route("POST", "/api/kb/pending/:id/dismiss", (c, p) => kb.dismissPending(c.db, { candidate_id: c.candidate_id, pending_id: p.id, now: c.now(), actor: ACTOR("dismiss_pending") }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gafj/gafj",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "GAF-J: a local campaign engine for job search. One SQLite file, one ingest door, your own AI subscription.",
   "homepage": "https://gaf-j.com",
   "repository": {

package/store/kb.js

@@ -111,9 +111,9 @@ function confirmPending(db, { candidate_id, pending_id, edits, now, actor }) {
     const verbSet = new Map(extractVerbs(wordings).map((v) => [v.verb, { ...v, review_state: "confirmed" }]));
     for (const v of draft.verbs) if (!verbSet.has(v)) verbSet.set(v, { verb: v, tier: tier(v), source_variation_ids: [], review_state: "confirmed" });
     const [ds, de] = draft.dates.split(/\s+(?:to|-|–)\s+/).map((x) => x && x.trim());
-    d.prepare(`INSERT INTO accomplishment (id, candidate_id, title, company, role, date_start, date_end, summary, metrics_json, verbatim_claims_json, verbs_json, subjects_json, wordings_json, tags_json, strength_score, source, confirmed_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, '[]', ?, ?, NULL, 'confirmed_pending', ?)`)
-      .run(id, candidate_id, draft.title, draft.company, draft.role, ds || null, de || null, draft.summary || null, JSON.stringify(metrics), JSON.stringify(claims), JSON.stringify([...verbSet.values()]), JSON.stringify(wordings), JSON.stringify(draft.tags), now);
+    d.prepare(`INSERT INTO accomplishment (id, candidate_id, title, company, role, date_start, date_end, summary, metrics_json, verbatim_claims_json, verbs_json, subjects_json, wordings_json, tags_json, strength_score, source, confirmed_at, position_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, '[]', ?, ?, NULL, 'confirmed_pending', ?, ?)`)
+      .run(id, candidate_id, draft.title, draft.company, draft.role, ds || null, de || null, draft.summary || null, JSON.stringify(metrics), JSON.stringify(claims), JSON.stringify([...verbSet.values()]), JSON.stringify(wordings), JSON.stringify(draft.tags), now, p.position_id || null);
     d.prepare("DELETE FROM pending_accomplishment WHERE id = ?").run(p.id);
     d.prepare("UPDATE candidate SET kb_revision = kb_revision + 1 WHERE id = ?").run(candidate_id);
     appendEvent(d, { candidate_id, entity: "accomplishment", entity_id: id, event: "confirmed", actor_type: actor.type, actor_ref: actor.ref, payload: { pending_id: p.id, source: p.source, metrics: metrics.length, verbs: verbSet.size }, at: now });

package/store/migrate.js

@@ -15,6 +15,7 @@ const MIGRATIONS = [
   { version: 1, file: path.join(__dirname, "..", "core", "schema.sql") },
   { version: 2, file: path.join(__dirname, "..", "core", "migrations", "002-profile.sql") },
   { version: 3, file: path.join(__dirname, "..", "core", "migrations", "003-discover.sql") },
+  { version: 4, file: path.join(__dirname, "..", "core", "migrations", "004-position.sql") },
 ];
 
 const CURRENT_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;

package/store/onboarding.js

@@ -111,7 +111,9 @@ function checkAtom(atom, text, label, errors) {
   let hits = [];
   if (v.length) for (let i = text.indexOf(v); i !== -1; i = text.indexOf(v, i + 1)) hits.push([i, i + v.length]);
   if (!hits.length && v.trim()) {
-    const re = new RegExp(v.trim().split(/\s+/).map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("\\s+"), "g");
+    // the model tends to straighten quotes and dashes; match either form in the source
+    const cls = (ch) => (/['\u2018\u2019]/.test(ch) ? "['\u2018\u2019]" : /["\u201c\u201d]/.test(ch) ? "[\"\u201c\u201d]" : /[-\u2013\u2014]/.test(ch) ? "[-\u2013\u2014]" : ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    const re = new RegExp(v.trim().split(/\s+/).map((w) => Array.from(w).map(cls).join("")).join("\\s+"), "g");
     for (let m = re.exec(text); m; m = re.exec(text)) { hits.push([m.index, m.index + m[0].length]); if (!m[0].length) break; }
   }
   if (!hits.length) { errors.push(`${label}: "${v.slice(0, 40)}" is not the source text at [${start}, ${end})`); return; }
@@ -130,6 +132,7 @@ function normalizeAtoms(content) {
     if (Array.isArray(a.wordings)) a.wordings = a.wordings.map(q);
     if (Array.isArray(a.metrics)) a.metrics = a.metrics.map((m) => (m && typeof m === "object" ? { value: String(m.value), ...(m.outcome !== undefined ? { outcome: m.outcome } : {}) } : m));
   }
+  if (Array.isArray(content.entries)) for (const e of content.entries) { if (e && typeof e === "object") for (const k of ["org", "title", "dates", "detail"]) if (k in e) e[k] = q(e[k]); }
   return content;
 }
 
@@ -145,6 +148,14 @@ function checkDraft(content, text) {
     a.wordings = (a.wordings || []).map((w) => (typeof w === "string" ? { value: w, start: -1, end: -1 } : w));
     a.metrics = (a.metrics || []).map((m) => ({ ...m, start: -1, end: -1 }));
   }
+  for (const e of content.entries || []) for (const k of ["org", "title", "dates", "detail"]) if (typeof e[k] === "string") e[k] = { value: e[k], start: -1, end: -1 };
+  (content.entries || []).forEach((e, i) => {
+    const p = `entries[${i}]`;
+    checkAtom(e.org, text, `${p}.org`, errors);
+    checkAtom(e.title, text, `${p}.title`, errors);
+    if (e.dates) checkAtom(e.dates, text, `${p}.dates`, errors);
+    if (e.detail) checkAtom(e.detail, text, `${p}.detail`, errors);
+  });
   content.accomplishments.forEach((a, i) => {
     const p = `accomplishments[${i}]`;
     checkAtom(a.company, text, `${p}.company`, errors);
@@ -183,8 +194,11 @@ function proposeFromSource(db, { candidate_id, source_document_id, content, ai_a
       }
       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 positions = require("./positions");
+    positions.derive(d, { candidate_id, now });
+    const entries = positions.addEntries(d, { candidate_id, source_document_id: s.id, entries: (content.entries || []).map((e) => ({ kind: e.kind, org: e.org.value, title: e.title.value, dates: e.dates ? e.dates.value : "", detail: e.detail ? e.detail.value : "" })), now });
+    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, entries, style: content.style_observed || null }, at: now });
+    return { accepted: true, errors: [], pending_ids: ids, entries, style_observed: content.style_observed || null };
   });
 }
 const span = (a) => (a ? { start: a.start, end: a.end } : null);

package/store/positions.js

@@ -0,0 +1,210 @@
+"use strict";
+
+/**
+ * Employment positions: one row per employer and role. Proposed from the company, role, and
+ * dates the model quoted on each pending record, confirmed once by the candidate, and the
+ * records under a position inherit its company, role, and dates whenever it is edited. The
+ * link is by a normalised (company, role) key, so a record proposed later, or written by hand,
+ * attaches to the position it belongs to the next time the list is read.
+ */
+
+const { ulid } = require("../core/ulid");
+const { withTx } = require("./tx");
+const { appendEvent } = require("./events");
+const { TransitionError, NotFound } = require("./transitions");
+
+const MONTHS = { jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6, jul: 7, aug: 8, sep: 9, sept: 9, oct: 10, nov: 11, dec: 12 };
+const norm = (s) => String(s || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").replace(/\b(inc|llc|corp|corporation|ltd|co|company)\b/g, "").replace(/\s+/g, " ").trim();
+const keyOf = (company, role, kind = "employment") => kind + "|" + norm(company) + "|" + norm(role);
+const KINDS = ["employment", "education", "volunteer", "award", "certification", "affiliation"];
+
+/** "Nov 2022 – Oct 2023", "2019-2021", "March 2020 to Present", "2018" → { start: "2022-11", end: "2023-10" | null }. Unreadable text gives nulls. */
+function parseDates(text) {
+  const s = String(text || "").toLowerCase();
+  const points = [];
+  const re = /\b(?:(jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\.?\s+(\d{4})|(\d{4})-(\d{2})\b|(\d{1,2})\/(\d{4})|(\d{4}))\b/g;
+  for (let m = re.exec(s); m; m = re.exec(s)) {
+    if (m[1]) points.push(`${m[2]}-${String(MONTHS[m[1]]).padStart(2, "0")}`);
+    else if (m[3]) points.push(`${m[3]}-${m[4]}`);
+    else if (m[5]) points.push(`${m[6]}-${m[5].padStart(2, "0")}`);
+    else points.push(m[7]);
+  }
+  const present = /\b(present|current|now|today)\b/.test(s);
+  if (!points.length) return { start: null, end: null, present };
+  if (points.length === 1) return { start: points[0], end: present ? null : points[0], present };
+  return { start: points[0], end: present ? null : points[points.length - 1], present };
+}
+
+const datesText = (start, end) => (start ? `${start} to ${end || "present"}` : "");
+
+/** Attach every unlinked record (pending or confirmed) to a position, creating proposed positions where none matches. Returns the number linked. */
+function derive(db, { candidate_id, now }) {
+  return withTx(db, (d) => {
+    const have = d.prepare("SELECT * FROM position WHERE candidate_id = ? AND kind = 'employment'").all(candidate_id);
+    const byKey = new Map(have.map((p) => [keyOf(p.company, p.role), p]));
+    let linked = 0;
+    const attach = (company, role, dates, source_document_id, link) => {
+      const key = keyOf(company, role);
+      if (!norm(company) && !norm(role)) return;
+      let pos = byKey.get(key);
+      const parsed = parseDates(dates);
+      if (!pos) {
+        pos = { id: ulid(Date.parse(now) + have.length + byKey.size), candidate_id, company: String(company).trim(), role: String(role).trim(), location: null, date_start: parsed.start, date_end: parsed.end, dates_text: dates || null, status: "proposed", source_document_id: source_document_id || null, created_at: now, confirmed_at: null };
+        d.prepare("INSERT INTO position (id, candidate_id, company, role, location, date_start, date_end, dates_text, status, source_document_id, created_at) VALUES (?, ?, ?, ?, NULL, ?, ?, ?, 'proposed', ?, ?)")
+          .run(pos.id, candidate_id, pos.company, pos.role, pos.date_start, pos.date_end, pos.dates_text, pos.source_document_id, now);
+        byKey.set(key, pos);
+      } else if (pos.status === "proposed" && !pos.date_start && parsed.start) {
+        // a proposed position with no dates takes the first dated record's
+        d.prepare("UPDATE position SET date_start = ?, date_end = ?, dates_text = ? WHERE id = ?").run(parsed.start, parsed.end, dates || null, pos.id);
+        Object.assign(pos, { date_start: parsed.start, date_end: parsed.end, dates_text: dates || null });
+      }
+      link(pos.id);
+      linked++;
+    };
+    for (const r of d.prepare("SELECT id, draft_json, source_document_id FROM pending_accomplishment WHERE candidate_id = ? AND position_id IS NULL ORDER BY proposed_at").all(candidate_id)) {
+      const draft = JSON.parse(r.draft_json);
+      if (draft.replaces) continue; // an answer extends a record; it follows that record's position
+      attach(draft.company, draft.role, draft.dates, r.source_document_id, (pid) => d.prepare("UPDATE pending_accomplishment SET position_id = ? WHERE id = ?").run(pid, r.id));
+    }
+    for (const a of d.prepare("SELECT id, company, role, date_start, date_end FROM accomplishment WHERE candidate_id = ? AND position_id IS NULL ORDER BY confirmed_at").all(candidate_id)) {
+      attach(a.company, a.role, [a.date_start, a.date_end].filter(Boolean).join(" to "), null, (pid) => d.prepare("UPDATE accomplishment SET position_id = ? WHERE id = ?").run(pid, a.id));
+    }
+    // a proposed position that nothing points at any more (its records were removed with their source) goes away
+    d.prepare("DELETE FROM position WHERE candidate_id = ? AND kind = 'employment' AND status = 'proposed' AND id NOT IN (SELECT position_id FROM pending_accomplishment WHERE position_id IS NOT NULL UNION SELECT position_id FROM accomplishment WHERE position_id IS NOT NULL)").run(candidate_id);
+    return linked;
+  });
+}
+
+/** The resume's other sections, quoted by the model: one position per (kind, org, title); a repeat from another resume is skipped. Returns the number added. */
+function addEntries(db, { candidate_id, source_document_id, entries, now }) {
+  return withTx(db, (d) => {
+    const have = new Set(d.prepare("SELECT kind, company, role FROM position WHERE candidate_id = ? AND kind <> 'employment'").all(candidate_id).map((p) => keyOf(p.company, p.role, p.kind)));
+    let added = 0;
+    for (const e of entries || []) {
+      if (!KINDS.includes(e.kind) || e.kind === "employment" || !norm(e.org) || !norm(e.title)) continue;
+      const key = keyOf(e.org, e.title, e.kind);
+      if (have.has(key)) continue;
+      const parsed = parseDates(e.dates);
+      d.prepare("INSERT INTO position (id, candidate_id, kind, company, role, location, date_start, date_end, dates_text, detail, status, source_document_id, created_at) VALUES (?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, 'proposed', ?, ?)")
+        .run(ulid(Date.parse(now) + 500 + added), candidate_id, e.kind, String(e.org).trim().slice(0, 120), String(e.title).trim().slice(0, 160), parsed.start, parsed.end, e.dates || null, String(e.detail || "").trim().slice(0, 300) || null, source_document_id || null, now);
+      have.add(key);
+      added++;
+    }
+    return added;
+  });
+}
+
+/** Positions newest first, each with its record counts. Reads derive first, so the list is never behind the records. */
+function list(db, candidate_id, { now = new Date().toISOString() } = {}) {
+  derive(db, { candidate_id, now });
+  return db.prepare(`SELECT p.*,
+      (SELECT count(*) FROM pending_accomplishment x WHERE x.position_id = p.id) AS pending,
+      (SELECT count(*) FROM accomplishment a WHERE a.position_id = p.id) AS confirmed
+    FROM position p WHERE p.candidate_id = ? ORDER BY p.kind = 'employment' DESC, p.kind, p.date_start IS NULL, p.date_start DESC, p.created_at`).all(candidate_id);
+}
+
+const DATE_RE = /^\d{4}(-\d{2})?$/;
+function cleanEdits(edits, current) {
+  const out = { ...current };
+  const str = (k, max) => { if (edits[k] === undefined) return; out[k] = String(edits[k] || "").trim().slice(0, max) || null; };
+  str("company", 120); str("role", 160); str("location", 120); str("detail", 300);
+  if (!out.company) throw new TransitionError("company is required");
+  if (!out.role) throw new TransitionError("role is required");
+  for (const k of ["date_start", "date_end"]) {
+    if (edits[k] === undefined) continue;
+    const v = String(edits[k] || "").trim();
+    if (v && !DATE_RE.test(v)) {
+      const p = parseDates(v);
+      if (!p.start) throw new TransitionError(`${k}: write a year or year-month, like 2022 or 2022-11`);
+      out[k] = p.start;
+    } else out[k] = v || null;
+  }
+  if (out.date_start && out.date_end && out.date_end < out.date_start) throw new TransitionError("the end date is before the start");
+  return out;
+}
+
+/** Push a position's company, role, and dates onto every record under it. */
+function propagate(d, pos) {
+  const dates = datesText(pos.date_start, pos.date_end);
+  let changed = 0;
+  for (const r of d.prepare("SELECT id, draft_json FROM pending_accomplishment WHERE position_id = ?").all(pos.id)) {
+    const draft = JSON.parse(r.draft_json);
+    if (draft.company === pos.company && draft.role === pos.role && (draft.dates || "") === dates) continue;
+    d.prepare("UPDATE pending_accomplishment SET draft_json = ? WHERE id = ?").run(JSON.stringify({ ...draft, company: pos.company, role: pos.role, dates }), r.id);
+    changed++;
+  }
+  const r = d.prepare("UPDATE accomplishment SET company = ?, role = ?, date_start = ?, date_end = ? WHERE position_id = ? AND (company <> ? OR role <> ? OR date_start IS NOT ? OR date_end IS NOT ?)")
+    .run(pos.company, pos.role, pos.date_start, pos.date_end, pos.id, pos.company, pos.role, pos.date_start, pos.date_end);
+  if (r.changes) d.prepare("UPDATE candidate SET kb_revision = kb_revision + 1 WHERE id = ?").run(pos.candidate_id);
+  return changed + r.changes;
+}
+
+function get(d, candidate_id, position_id) {
+  const p = d.prepare("SELECT * FROM position WHERE id = ? AND candidate_id = ?").get(position_id, candidate_id);
+  if (!p) throw new NotFound("position");
+  return p;
+}
+
+/** Edit a position; the records under it follow. With confirm, it is marked confirmed as well. */
+function update(db, { candidate_id, position_id, edits = {}, confirm = false, now, actor }) {
+  return withTx(db, (d) => {
+    const cur = get(d, candidate_id, position_id);
+    const next = cleanEdits(edits, cur);
+    if (confirm) { next.status = "confirmed"; next.confirmed_at = now; }
+    d.prepare("UPDATE position SET company = ?, role = ?, location = ?, date_start = ?, date_end = ?, detail = ?, status = ?, confirmed_at = ? WHERE id = ?")
+      .run(next.company, next.role, next.location, next.date_start, next.date_end, next.detail, next.status, next.confirmed_at, position_id);
+    const records = propagate(d, next);
+    appendEvent(d, { candidate_id, entity: "position", entity_id: position_id, event: confirm ? "confirmed" : "edited", actor_type: actor.type, actor_ref: actor.ref, payload: { records }, at: now });
+    return { position_id, status: next.status, records };
+  });
+}
+
+/** Two spellings of one job: the records under drop move to keep and take its details; drop goes away. */
+function merge(db, { candidate_id, keep_id, drop_id, now, actor }) {
+  return withTx(db, (d) => {
+    if (keep_id === drop_id) throw new TransitionError("pick a different position to merge into");
+    const keep = get(d, candidate_id, keep_id);
+    const drop = get(d, candidate_id, drop_id);
+    if (keep.kind !== drop.kind) throw new TransitionError("these are different kinds of entry");
+    d.prepare("UPDATE pending_accomplishment SET position_id = ? WHERE position_id = ?").run(keep_id, drop_id);
+    d.prepare("UPDATE accomplishment SET position_id = ? WHERE position_id = ?").run(keep_id, drop_id);
+    d.prepare("DELETE FROM position WHERE id = ?").run(drop_id);
+    const records = propagate(d, keep);
+    appendEvent(d, { candidate_id, entity: "position", entity_id: keep_id, event: "merged", actor_type: actor.type, actor_ref: actor.ref, payload: { dropped: drop_id, records }, at: now });
+    return { position_id: keep_id, records };
+  });
+}
+
+/** One written by hand: confirmed on arrival, since the candidate typed it. */
+function create(db, { candidate_id, kind = "employment", edits = {}, now, actor }) {
+  if (!KINDS.includes(kind)) throw new TransitionError("unknown kind");
+  return withTx(db, (d) => {
+    const next = cleanEdits(edits, { company: null, role: null, location: null, date_start: null, date_end: null, detail: null });
+    const id = ulid(Date.parse(now) + 900);
+    d.prepare("INSERT INTO position (id, candidate_id, kind, company, role, location, date_start, date_end, dates_text, detail, status, source_document_id, created_at, confirmed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, 'confirmed', NULL, ?, ?)")
+      .run(id, candidate_id, kind, next.company, next.role, next.location, next.date_start, next.date_end, next.detail, now, now);
+    appendEvent(d, { candidate_id, entity: "position", entity_id: id, event: "written", actor_type: actor.type, actor_ref: actor.ref, payload: { kind }, at: now });
+    return { position_id: id, status: "confirmed" };
+  });
+}
+
+/** Remove a position nothing points at. */
+function remove(db, { candidate_id, position_id, now, actor }) {
+  return withTx(db, (d) => {
+    get(d, candidate_id, position_id);
+    const n = d.prepare("SELECT (SELECT count(*) FROM pending_accomplishment WHERE position_id = ?) + (SELECT count(*) FROM accomplishment WHERE position_id = ?) AS c").get(position_id, position_id).c;
+    if (n) throw new TransitionError(`${n} record${n === 1 ? "" : "s"} still under this position; merge it into another instead`);
+    d.prepare("DELETE FROM position WHERE id = ?").run(position_id);
+    appendEvent(d, { candidate_id, entity: "position", entity_id: position_id, event: "removed", actor_type: actor.type, actor_ref: actor.ref, payload: {}, at: now });
+    return { removed: true };
+  });
+}
+
+/** Counts for the setup card: how many positions, how many still proposed. */
+function counts(db, candidate_id, { now } = {}) {
+  derive(db, { candidate_id, now: now || new Date().toISOString() });
+  const r = db.prepare("SELECT count(*) AS total, sum(status = 'proposed') AS proposed FROM position WHERE candidate_id = ?").get(candidate_id);
+  return { total: r.total, proposed: r.proposed || 0 };
+}
+
+module.exports = { derive, addEntries, list, update, merge, remove, create, counts, parseDates, keyOf, KINDS };

package/store/setup.js

@@ -1,7 +1,7 @@
 "use strict";
 
 /**
- * The guided setup (first run): six steps in the order they must happen,
+ * The guided setup (first run): seven steps in the order they must happen,
  * each computed from the store, so the checklist is never out of date and
  * nothing is stored except two flags in config: which AI route the user
  * chose on purpose (the default is paste, which says nothing), and whether
@@ -25,10 +25,13 @@ function setupView(db, homeDir, candidate_id) {
   const providers = cfg.providers || [];
   const usable = cfg.route !== "byo_key" || !!(cfg.active_provider_id && providers.some((x) => x.id === cfg.active_provider_id)) || providers.length === 1;
   const aiChosen = !!(cfg.setup && cfg.setup.ai_chosen) && usable;
+  const pos = require("./positions").counts(db, candidate_id);
+  const posDone = pos.total > 0 && pos.proposed === 0;
   const steps = [
     { key: "ai", title: "Tell GAF-J which AI you use", done: aiChosen, detail: aiChosen ? `Using ${ROUTE_LABEL[cfg.route] || cfg.route}` : null },
     { key: "upload", title: "Upload your resumes", done: sources > 0, detail: sources ? `${sources} file${sources === 1 ? "" : "s"} uploaded` : null },
     { key: "extract", title: "Extract records from them", done: extracted > 0 || pending > 0 || confirmed > 0, detail: extracted ? `${extracted} extraction${extracted === 1 ? "" : "s"} saved` : null },
+    { key: "positions", title: "Confirm your jobs, schools, and awards", done: posDone, detail: pos.total ? (posDone ? `${pos.total} position${pos.total === 1 ? "" : "s"} confirmed` : `${pos.proposed} of ${pos.total} to confirm`) : null },
     { key: "confirm", title: "Confirm the records you stand behind", done: confirmed > 0, detail: confirmed ? `${confirmed} confirmed${pending ? `, ${pending} still pending` : ""}` : (pending ? `${pending} waiting for you` : null) },
     { key: "discover", title: "Answer what's missing", done: questions > 0, detail: questions ? `${questions} question${questions === 1 ? "" : "s"} asked` : null },
     { key: "posting", title: "Paste your first job posting", done: postings > 0, detail: postings ? `${postings} posting${postings === 1 ? "" : "s"}` : null },

package/ui/screens/kb.js

@@ -90,6 +90,63 @@ function Excerpt({ text, span }) {
 const EMPTY = { title: "", company: "", role: "", dates: "", summary: "", metrics: "", verbs: "", wordings: "", tenure: "" };
 const toDraft = (f) => ({ title: f.title, company: f.company, role: f.role, dates: f.dates, summary: f.summary,
   metrics: f.metrics.split(/[;,]/).map((s) => s.trim()).filter(Boolean), verbs: f.verbs.split(/[;,]/).map((s) => s.trim()).filter(Boolean), wordings: f.wordings.split(/\n/).map((s) => s.trim()).filter(Boolean), ...(f.tenure && f.tenure.trim() ? { tenure: f.tenure.trim() } : {}) });
+/** Positions: jobs, schools, volunteer roles, awards, certifications, affiliations. One row each, confirmed once; a job's records inherit its company, role, and dates. */
+const KIND = {
+  employment: { heading: "Jobs", org: "company", title: "title", records: true, where: true },
+  education: { heading: "Education", org: "school", title: "degree or program", where: true, detail: "honors, GPA, focus" },
+  volunteer: { heading: "Volunteer and community", org: "organization", title: "role", where: true, detail: "what you did" },
+  award: { heading: "Awards", org: "issuer", title: "award", detail: "for what" },
+  certification: { heading: "Certifications and licenses", org: "issuer", title: "credential", detail: "number or scope" },
+  affiliation: { heading: "Affiliations and memberships", org: "organization", title: "role or membership", detail: "" },
+};
+export function Positions({ reload, setErr, compact }) {
+  const [rows, setRows] = useState(null);
+  const [edits, setEdits] = useState({});
+  const [busy, setBusy] = useState("");
+  const [adding, setAdding] = useState(null); // a kind being written by hand
+  const load = () => api.get("/api/kb/positions").then((r) => { setRows(r); setEdits({}); }).catch((e) => setErr(e.message));
+  useEffect(() => { load(); }, []);
+  if (!rows) return html`<p class="muted">loading</p>`;
+  const val = (p, k) => (edits[p.id] && edits[p.id][k] !== undefined ? edits[p.id][k] : (p[k] || ""));
+  const set = (p, k, v) => setEdits({ ...edits, [p.id]: { ...(edits[p.id] || {}), [k]: v } });
+  const dirty = (p) => !!edits[p.id] && Object.keys(edits[p.id]).some((k) => (edits[p.id][k] || "") !== (p[k] || ""));
+  const act = async (label, fn) => { setBusy(label); try { setErr(""); await fn(); await load(); if (reload) await reload(); } catch (e) { setErr(e.message); } setBusy(""); };
+  const save = (p, confirm) => act(p.id, () => api.post(`/api/kb/positions/${p.id}${confirm ? "/confirm" : ""}`, { edits: edits[p.id] || {} }));
+  const proposed = rows.filter((p) => p.status === "proposed");
+  const fmt = (p) => (p.date_start && p.date_end === p.date_start ? p.date_start : [p.date_start, p.date_end || (p.date_start ? "present" : "")].filter(Boolean).join(" to "));
+  const kinds = Object.keys(KIND).filter((k) => k === "employment" || rows.some((p) => p.kind === k) || adding === k);
+  const fields = (p, k) => html`
+    <input placeholder=${k.org} value=${val(p, "company")} onInput=${(e) => set(p, "company", e.target.value)} />
+    <input placeholder=${k.title} value=${val(p, "role")} onInput=${(e) => set(p, "role", e.target.value)} />
+    ${k.where ? html`<input placeholder="city, state" value=${val(p, "location")} onInput=${(e) => set(p, "location", e.target.value)} />` : ""}
+    <input class="narrow" placeholder=${k.records ? "2022-11" : "2022"} title="start or date, year or year-month" value=${val(p, "date_start")} onInput=${(e) => set(p, "date_start", e.target.value)} />
+    <input class="narrow" placeholder=${k.records ? "present" : "end"} title="end, year or year-month; blank means present or none" value=${val(p, "date_end")} onInput=${(e) => set(p, "date_end", e.target.value)} />
+    ${k.detail !== undefined ? html`<input placeholder=${k.detail || "detail"} value=${val(p, "detail")} onInput=${(e) => set(p, "detail", e.target.value)} />` : ""}`;
+  return html`<div>
+    ${compact ? "" : html`<p class="small muted">Your AI quoted an employer, a title, and dates on every record, and read the education, volunteer, award, and certification lines. Here each appears once. Fix a name or a date here and every record under a job follows; confirm each once.</p>`}
+    ${kinds.map((kind) => { const k = KIND[kind]; const mine = rows.filter((p) => p.kind === kind); return html`<div key=${kind}>
+      <div class="small muted" style="margin:14px 0 4px;text-transform:uppercase;letter-spacing:.04em">${k.heading}</div>
+      <ul class="list">${mine.map((p) => html`<li key=${p.id}><div style="flex:1">
+        <div class="row"><b>${p.company}</b><span class="muted">${p.role}</span><span class="small muted">${fmt(p) || "no dates"}${p.location ? " · " + p.location : ""}${p.detail ? " · " + p.detail : ""}</span>
+          <span class="tag">${p.status === "confirmed" ? "confirmed" : "proposed"}</span>${k.records ? html`<span class="small muted">${p.pending + p.confirmed} record${p.pending + p.confirmed === 1 ? "" : "s"}${p.pending ? ` (${p.pending} pending)` : ""}</span>` : ""}</div>
+        <form class="inline" onSubmit=${(e) => { e.preventDefault(); save(p, p.status !== "confirmed"); }}>
+          ${fields(p, k)}
+          ${p.status === "confirmed" ? html`<button class="small" disabled=${!dirty(p) || !!busy}>Save</button>` : html`<button class="primary small" disabled=${!!busy}>${busy === p.id ? "saving" : "Confirm"}</button>`}
+          ${mine.length > 1 ? html`<select title="this is the same as another row" value="" onChange=${(e) => { const keep = e.target.value; if (keep) act(p.id, () => api.post("/api/kb/positions/merge", { keep_id: keep, drop_id: p.id })); }}>
+            <option value="">same as…</option>${mine.filter((o) => o.id !== p.id).map((o) => html`<option key=${o.id} value=${o.id}>${o.company}, ${o.role}</option>`)}</select>` : ""}
+          ${p.pending + p.confirmed === 0 ? html`<button type="button" class="small danger" onClick=${() => act(p.id, () => api.del(`/api/kb/positions/${p.id}`))}>Remove</button>` : ""}
+        </form></div></li>`)}
+        ${mine.length ? "" : html`<li class="muted small">${kind === "employment" ? "no jobs yet; extract a resume first, or add one" : "none yet"}</li>`}</ul>
+      ${adding === kind ? html`<form class="inline" onSubmit=${(e) => { e.preventDefault(); act("new", () => api.post("/api/kb/positions", { kind, edits: edits.new || {} })); setAdding(null); }}>
+        ${fields({ id: "new" }, k)}<button class="primary small" disabled=${!!busy}>Add</button><button type="button" class="small" onClick=${() => setAdding(null)}>cancel</button></form>` : ""}
+    </div>`; })}
+    <div class="row" style="margin-top:10px">
+      ${proposed.length > 1 ? html`<button disabled=${!!busy} onClick=${() => act("all", async () => { for (const p of proposed) await api.post(`/api/kb/positions/${p.id}/confirm`, { edits: edits[p.id] || {} }); })}>Confirm all ${proposed.length}</button><span class="small muted">only if the names and dates are right</span>` : ""}
+      <select value="" onChange=${(e) => { if (e.target.value) { setEdits({ ...edits, new: {} }); setAdding(e.target.value); } e.target.value = ""; }}><option value="">+ add by hand…</option>${Object.keys(KIND).map((kd) => html`<option key=${kd} value=${kd}>${KIND[kd].heading}</option>`)}</select>
+    </div>
+  </div>`;
+}
+
 export const fromDraft = (d) => ({ title: d.title || "", company: d.company || "", role: d.role || "", dates: d.dates || "", summary: d.summary || "", metrics: (d.metrics || []).join(", "), verbs: (d.verbs || []).join(", "), wordings: (d.wordings || []).join("\n"), tenure: d.tenure || "" });
 
 export function DraftForm({ initial, onSubmit, label }) {
@@ -149,6 +206,8 @@ export function KB({ live }) {
     <div class="card"><p class="small muted">A record with no confirmed figure, or an ownership verb with no scope. An answer extends that record; nothing is stored until you confirm it under Pending.</p><ul class="list">${(d.holes || []).map((h) => html`<li key=${h.hole_id}><div><b>?</b> <b>${h.title}</b> <span class="muted">${h.company}, ${h.role}</span><br />${h.question}
       ${answering === h.hole_id ? html`<${DraftForm} label="Add answer as pending" initial=${fromDraft(h.draft)} onSubmit=${(draft) => { post("/api/kb/pending", { draft: { ...draft, replaces: h.draft.replaces } }); setAnswering(null); }} />` : html`<button class="small" onClick=${() => setAnswering(h.hole_id)}>Answer</button>`}</div></li>`)}
       ${(d.holes || []).length ? "" : html`<li class="muted">no holes: every record carries a confirmed figure and every ownership claim a scope</li>`}</ul></div>
+    <h2>Jobs, education, and the rest (confirm each once)</h2>
+    <div class="card"><${Positions} reload=${load} setErr=${setErr} /></div>
     <h2>Pending (written, not yet confirmed)</h2>
     <div class="card"><ul class="list">${d.pending.map((p) => html`<li key=${p.pending_id}><div><b>${p.draft.title}</b> <span class="muted">${p.draft.company}, ${p.draft.role}</span> <span class="tag">${p.source}</span>${p.draft.replaces ? html` <span class="tag">extends an existing record</span>` : ""}
       <div class="small muted">metrics: ${(p.draft.metrics || []).join(", ") || "none"} · verbs: ${(p.draft.verbs || []).join(", ") || "none"}${p.draft.dates ? " · " + p.draft.dates : ""}</div>

package/ui/screens/welcome.js

@@ -1,12 +1,12 @@
 import { html, useState, useEffect } from "../vendor/preact.mjs";
 import { api } from "../lib.js";
-import { Onboarding, DraftForm, fromDraft } from "./kb.js";
+import { Onboarding, DraftForm, fromDraft, Positions } from "./kb.js";
 import { PacketModal } from "./packet.js";
 
 /**
  * The first run, before the app: one step at a time, everything done on this
  * screen. The order is the order the data needs: an AI to read with, files to
- * read, records to confirm, questions to answer, a posting to aim at. Each
+ * read, jobs and records to confirm, questions to answer, a posting to aim at. Each
  * step flips when the store says so; "skip for now" opens the app anyway.
  */
 
@@ -101,6 +101,7 @@ export function Welcome({ live, onDone }) {
     ai: html`<${StepAi} s=${setup} reload=${load} />`,
     upload: html`<div><p>Your resumes: Word, PDF, Markdown, or plain text. Five to ten of your most different versions is plenty; near-identical copies only add duplicates to merge. The text is read on this PC. Nothing is uploaded anywhere.</p><${Onboarding} d=${ob} reload=${load} setErr=${setErr} route=${me.route} compact=${true} /></div>`,
     extract: html`<div><p>${direct ? "Your AI reads each file and proposes records where every number and phrase is quoted from the file; anything it cannot quote is refused. One click runs the whole pile." : "For each file, Extract opens a packet: copy it into your chat, paste the JSON reply back. Your AI proposes records where every number and phrase is quoted from the file."}</p><${Onboarding} d=${ob} reload=${load} setErr=${setErr} route=${me.route} compact=${true} /></div>`,
+    positions: html`<div><p>Before the records: the jobs, schools, volunteer roles, awards, and certifications themselves, each once. Your AI quoted them from your resumes. Fix a name, add a city, correct a date, then confirm. Every record under a job follows it.</p><${Positions} reload=${load} setErr=${setErr} compact=${true} /></div>`,
     confirm: html`<div><p>These are the records your AI proposed. Confirm the ones you can stand behind in an interview, edit what is off, dismiss the rest. Only confirmed records can ever appear in a document.</p>
       <ul class="list">${kb.pending.map((p) => html`<li key=${p.pending_id}><div><b>${p.draft.title}</b> <span class="muted">${p.draft.company}, ${p.draft.role}</span>
         <div class="small muted">metrics: ${(p.draft.metrics || []).join(", ") || "none"} · verbs: ${(p.draft.verbs || []).join(", ") || "none"}${p.draft.dates ? " · " + p.draft.dates : ""}</div>
@@ -115,7 +116,7 @@ export function Welcome({ live, onDone }) {
     posting: html`<${StepPosting} reload=${load} />`,
   };
   return html`<div class="welcome">
-    <div class="welcome-head"><img src="/icon-192.png" alt="" width="40" height="40" /><div><b>Welcome to GAF-J${me.name ? ", " + me.name : ""}</b><div class="small muted">Six short steps, then the app is yours.</div></div>
+    <div class="welcome-head"><img src="/icon-192.png" alt="" width="40" height="40" /><div><b>Welcome to GAF-J${me.name ? ", " + me.name : ""}</b><div class="small muted">Seven short steps, then the app is yours.</div></div>
       <span class="links"><a class="small" href="#/settings">Settings</a><a class="small" href="#/" onClick=${async (e) => { e.preventDefault(); await api.post("/api/setup/dismiss", {}); onDone(); }}>skip for now</a></span></div>
     <ol class="stepper">${setup.steps.map((st, i) => html`<li key=${st.key} class=${(st.done ? "done" : "") + (i === idx ? " now" : "") + (i <= nextIdx ? " can" : "")} onClick=${() => { if (i <= nextIdx) setView(i); }} title=${i <= nextIdx ? "open this step" : ""}><span class="n mono">${st.done ? "✓" : i + 1}</span>${st.title}</li>`)}</ol>
     ${err ? html`<p class="error">${err}</p>` : ""}