@gafj/gafj 0.1.1

package/core/generators/slice.js

@@ -0,0 +1,61 @@
+"use strict";
+
+/**
+ * KB slice precedence (plan, packet contract): every record cited by the
+ * frozen scoring evidence and every pinned id is required and serialized
+ * first, pinned ahead of evidence; the top five by rankEvidence for each
+ * category at weight 7 or above fill the rest under a byte budget. If the
+ * required set alone exceeds the budget the build fails with a
+ * deterministic error rather than dropping evidence. When the frozen
+ * scoring carries no categories (a tracker import), the fill ranks against
+ * the posting's title and opening text instead, so the slice is never empty.
+ */
+
+const { rankEvidence } = require("../scoring");
+const { serializeRecord, toScoringShape, bytesOf } = require("./serialize");
+
+const DEFAULT_SLICE_BYTES = 24000;
+const FILL_WEIGHT = 7;
+const PER_CATEGORY = 5;
+
+class SliceError extends Error {
+  constructor(message, detail) { super(message); this.name = "SliceError"; this.detail = detail; }
+}
+
+function selectSlice({ records, categories = [], pinned_ids = [], posting = null, budget = DEFAULT_SLICE_BYTES, recordBytes }) {
+  const byId = new Map(records.map((r) => [r.id, r]));
+  const order = [];
+  const seen = new Set();
+  const add = (id, why) => { if (id && byId.has(id) && !seen.has(id)) { seen.add(id); order.push({ id, why }); } };
+
+  for (const id of pinned_ids) add(id, "pinned");
+  for (const c of categories) for (const id of c.evidence_ids || []) add(id, "evidence");
+  const required = order.map((o) => ({ ...o, json: serializeRecord(byId.get(o.id), recordBytes) }));
+  let bytes = required.reduce((n, o) => n + bytesOf(o.json) + 1, 0);
+  if (bytes > budget) {
+    throw new SliceError(`required slice is ${bytes} bytes against a ${budget} byte budget; raise the budget or unpin`, {
+      required_ids: required.map((o) => o.id), bytes, budget });
+  }
+
+  const KB = records.map(toScoringShape);
+  const queries = categories.filter((c) => Number(c.weight) >= FILL_WEIGHT)
+    .sort((a, b) => Number(b.weight) - Number(a.weight))
+    .map((c) => [c.category, ...(c.jd_evidence || [])].join(" "));
+  if (!queries.length && posting) queries.push([posting.title, String(posting.raw_text || "").slice(0, 2000)].join(" "));
+  const fill = [];
+  for (const q of queries) {
+    for (const e of rankEvidence(q, KB, PER_CATEGORY)) {
+      if (seen.has(e.accomplishmentId)) continue;
+      const json = serializeRecord(byId.get(e.accomplishmentId), recordBytes);
+      const size = bytesOf(json) + 1;
+      if (bytes + size > budget) continue;
+      seen.add(e.accomplishmentId);
+      bytes += size;
+      fill.push({ id: e.accomplishmentId, why: "ranked", json });
+    }
+  }
+  const all = [...required, ...fill];
+  return { records: all.map((o) => o.json), ids: all.map((o) => o.id), reasons: Object.fromEntries(all.map((o) => [o.id, o.why])), bytes, budget };
+}
+
+module.exports = { selectSlice, SliceError, DEFAULT_SLICE_BYTES, FILL_WEIGHT };

package/core/house_rules.js

@@ -0,0 +1,49 @@
+"use strict";
+
+/**
+ * Severity of each style validator per document kind (decision 9). Integrity
+ * validators have no switch. A candidate's style_config may override any
+ * cell with block, warn, or off; these are the engine defaults, which are
+ * the operator's house rules: outbound kinds block, internal kinds warn.
+ */
+
+const OUTBOUND = ["resume", "cover", "onepager", "email"];
+const INTERNAL = ["prep", "deep_answers", "practice", "cheatsheet"];
+
+const STYLE_RULES = ["no_dashes", "style_config"];
+/** Bullet shape on the resume: result first (the RAS default), action first (verb leads), or let the posting decide. */
+const REGISTERS = ["result_first", "action_first", "posting"];
+const INTEGRITY_RULES = ["provenance", "no_derived_tenure", "metric_pairing", "verb_ladder", "highlight_body_match", "no_confabulated_history", "schema"];
+
+const DEFAULT_STYLE = {
+  no_dashes: Object.fromEntries([...OUTBOUND.map((k) => [k, "block"]), ...INTERNAL.map((k) => [k, "warn"])]),
+  style_config: Object.fromEntries([...OUTBOUND.map((k) => [k, "block"]), ...INTERNAL.map((k) => [k, "warn"])]),
+  hyphen_allow: [],
+  bullet_register: "result_first",
+  vocabulary: [
+    { pattern: "\\be-commerce\\b", flags: "i", message: 'write "ecommerce"' },
+    { pattern: "\\b(\\d+)\\s+plus\\b", flags: "i", message: 'write "N+"' },
+    { pattern: "\\b(\\d+(?:\\.\\d+)?)\\s*percent\\b", flags: "i", message: 'write "N%"' },
+    { pattern: "\\bP and L\\b", flags: "", message: 'write "P&L"' },
+    { pattern: "\\butili[sz]e\\b", flags: "i", message: 'write "use"' },
+  ],
+};
+
+function severity(house, rule, kind) {
+  if (INTEGRITY_RULES.includes(rule)) return "block";
+  const table = (house && house[rule]) || DEFAULT_STYLE[rule] || {};
+  return table[kind] || (OUTBOUND.includes(kind) ? "block" : "warn");
+}
+
+function houseFor(styleConfig) {
+  const cfg = styleConfig || {};
+  return {
+    no_dashes: { ...DEFAULT_STYLE.no_dashes, ...(cfg.no_dashes || {}) },
+    style_config: { ...DEFAULT_STYLE.style_config, ...(cfg.style_config || {}) },
+    hyphen_allow: [...DEFAULT_STYLE.hyphen_allow, ...(cfg.hyphen_allow || [])],
+    bullet_register: REGISTERS.includes(cfg.bullet_register) ? cfg.bullet_register : DEFAULT_STYLE.bullet_register,
+    vocabulary: cfg.vocabulary ? cfg.vocabulary : DEFAULT_STYLE.vocabulary,
+  };
+}
+
+module.exports = { DEFAULT_STYLE, STYLE_RULES, INTEGRITY_RULES, REGISTERS, OUTBOUND, INTERNAL, severity, houseFor };

package/core/kb_import.js

@@ -0,0 +1,257 @@
+"use strict";
+
+/**
+ * Turns the legacy knowledge base (accomplishments.json + bullet-variations.json)
+ * into accomplishment rows with per-dimension review state (plan principle 9).
+ *
+ * The rule for review state at import: a metric, outcome key, verb, or
+ * verbatim claim is confirmed only if a must-pass fixture exercises it on that
+ * record, because the candidate shipped those documents. Everything else is
+ * review state and no integrity validator may rely on it until the candidate
+ * confirms it. With no fixtures every dimension is review.
+ *
+ * Metric cleanup: tokenization fragments are dropped ("000 returns"), values
+ * that share digits are folded into one entry with aliases ("$1M" and "1M";
+ * "1900 cases" and "1900 returns"), and each metric gets an outcome key
+ * derived from the record it belongs to.
+ *
+ * Pure: no I/O, no clock.
+ */
+
+const { metricKey, words } = require("./scoring");
+const { extractFigures, figureKey } = require("./text");
+const { leadVerb, tier } = require("./verbs");
+
+const NUMBER_WORDS = "one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve";
+const DURATION_RE = new RegExp(
+  `\\b(?:(?:over|in|within|nearly|almost|about|roughly|under)\\s+)?(?:the\\s+first\\s+)?(?:\\d+\\+?|${NUMBER_WORDS})\\s*(?:years?|months?|weeks?|days?)\\b`, "gi");
+const TENURE_RE = /\b(?:since\s+(?:19|20)\d{2}|\d+\+?\s*years?\s+(?:of\s+)?(?:experience|tenure|in\s+sales|selling|career))\b/gi;
+
+function norm(s) {
+  return String(s || "").toLowerCase().replace(/[^a-z0-9%$+.]+/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function slug(text) {
+  return words(text).join("_") || "record";
+}
+
+const NUMBER_WORD_VALUES = { one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10, eleven: 11, twelve: 12, dozen: 12 };
+
+function digitsOf(value) {
+  const m = String(value).match(/\d[\d,]*(?:\.\d+)?/);
+  if (m) return m[0].replace(/,/g, "");
+  const w = String(value).toLowerCase().match(/^(?:roughly|about|approximately|~)?\s*(one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|dozen)\b/);
+  return w ? String(NUMBER_WORD_VALUES[w[1]]) : "";
+}
+
+function isFragment(value) {
+  const v = String(value).trim();
+  if (/^0\d/.test(v) || /^000\b/.test(v)) return true;
+  const d = digitsOf(v);
+  return d === "" || (Number(d) === 0 && !/^\$?0(\.0+)?%?$/.test(v));
+}
+
+function hasUnit(value) {
+  return /[$%]/.test(String(value)) || /\b(?:person|member|people|clients?|employees?|staff|years?|months?|weeks?|days?|cases|returns|products|repositories|lines|tests|countries)\b/i.test(String(value));
+}
+
+/** Fold a record's raw metrics into canonical entries with aliases. */
+function normalizeMetrics(rawMetrics, outcome) {
+  const groups = new Map();
+  for (const m of rawMetrics || []) {
+    const value = String(m.value || "").trim();
+    if (!value || isFragment(value)) continue;
+    const d = digitsOf(value);
+    const scale = /k\b/i.test(value) ? 1e3 : /m\b/i.test(value) ? 1e6 : 1;
+    const groupKey = String(Math.round(parseFloat(d) * scale));
+    const entry = { value, key: /\d/.test(value) ? metricKey(value) : d, type: m.type || "count", source_variation_ids: m.sourceVariationIds || [] };
+    const g = groups.get(groupKey);
+    if (!g) { groups.set(groupKey, { canonical: entry, aliases: [] }); continue; }
+    // prefer the entry with a currency or percent symbol or a noun as canonical
+    if (!hasUnit(g.canonical.value) && hasUnit(value)) {
+      g.aliases.push(g.canonical.value);
+      g.canonical = { ...entry, source_variation_ids: [...new Set([...g.canonical.source_variation_ids, ...entry.source_variation_ids])] };
+    } else {
+      g.aliases.push(value);
+      g.canonical.source_variation_ids = [...new Set([...g.canonical.source_variation_ids, ...entry.source_variation_ids])];
+    }
+  }
+  return [...groups.values()].map(({ canonical, aliases }) => ({
+    value: canonical.value, key: canonical.key, type: canonical.type,
+    keys: [...new Set([canonical.key, ...extractFigures(canonical.value).map((f) => f.key), ...aliases.map(figureKey)])],
+    outcome_key: outcome.key, outcome: outcome.text,
+    aliases, source_variation_ids: canonical.source_variation_ids, review_state: "review",
+  }));
+}
+
+function extractClaims(wordings) {
+  const claims = new Map();
+  for (const w of wordings) {
+    for (const re of [DURATION_RE, TENURE_RE]) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(w.text))) {
+        const text = m[0].replace(/\s+/g, " ").trim();
+        const type = re === TENURE_RE ? "tenure" : "duration";
+        const k = type + ":" + norm(text);
+        const c = claims.get(k) || { text, type, source_variation_ids: [], review_state: "review" };
+        c.source_variation_ids.push(w.id);
+        claims.set(k, c);
+      }
+    }
+  }
+  return [...claims.values()];
+}
+
+function extractVerbs(wordings) {
+  const verbs = new Map();
+  for (const w of wordings) {
+    const v = leadVerb(w.text);
+    if (!v) continue;
+    const e = verbs.get(v) || { verb: v, tier: tier(v), source_variation_ids: [], review_state: "review" };
+    e.source_variation_ids.push(w.id);
+    verbs.set(v, e);
+  }
+  return [...verbs.values()];
+}
+
+/** Sentences of the fixture set, each as a stem set plus its normalized text. */
+function fixtureSentences(fixtureTexts) {
+  const out = [];
+  // A line (one bullet) is the unit of attribution; its sentences are also offered on
+  // their own so a short wording still matches exactly.
+  for (const t of fixtureTexts || []) {
+    for (const line of String(t).split(/\r?\n/)) {
+      const parts = line.split(/(?<=[.;:])\s+/);
+      for (const s of parts.length > 1 ? [line, ...parts] : parts) {
+        const n = norm(s);
+        if (n.length < 12) continue;
+        out.push({ raw: s, norm: n, stems: new Set(words(s)) });
+      }
+    }
+  }
+  return out;
+}
+
+function containment(needleStems, hay) {
+  if (needleStems.length === 0) return 0;
+  let hit = 0;
+  for (const s of needleStems) if (hay.has(s)) hit++;
+  return hit / needleStems.length;
+}
+
+/** A wording is exercised when a fixture sentence contains most of its stems. */
+function exercisedWordings(wordings, sentences) {
+  const hit = new Set();
+  for (const w of wordings) {
+    const stems = [...new Set(words(w.text))];
+    const n = norm(w.text);
+    for (const s of sentences) {
+      if (stems.length < 4 ? s.norm.includes(n) : containment(stems, s.stems) >= 0.8) { hit.add(w.id); break; }
+    }
+  }
+  return hit;
+}
+
+function applyFixtureRule(row, wordings, sentences) {
+  if (!sentences.length) return row;
+  const hit = exercisedWordings(wordings, sentences);
+  const titleStems = new Set(words(row.title));
+  const shared = (s) => { let c = 0; for (const t of titleStems) if (s.stems.has(t)) c++; return c; };
+  // A distinctive figure (money, percent, four or more digits) needs one title stem in the
+  // sentence; a bare count like "6" or "375" needs two, so a shared small number never
+  // confirms across records.
+  const distinctive = (k) => /[$%]/.test(k) || k.replace(/\D/g, "").length >= 4;
+  for (const m of row.metrics_json) {
+    const byWording = m.source_variation_ids.some((id) => hit.has(id));
+    const keys = [...new Set(m.keys || [m.key])];
+    const byValue = sentences.some((s) => {
+      const n = shared(s);
+      if (n < 1) return false;
+      s.figureKeys || (s.figureKeys = new Set(extractFigures(s.raw).map((f) => f.key)));
+      return keys.some((k) => s.figureKeys.has(k) && (n >= 2 || distinctive(k)));
+    });
+    if (byWording || byValue) m.review_state = "confirmed";
+  }
+  for (const v of row.verbs_json) {
+    if (v.source_variation_ids.some((id) => hit.has(id))) v.review_state = "confirmed";
+  }
+  // A fixture sentence that belongs to this record (most of the title's stems, or one of its
+  // confirmed metrics) confirms the ownership verb it leads with, adding it if the wordings
+  // never used it. The candidate shipped that verb on that record; that is the confirmation.
+  const titleList = [...titleStems];
+  const confirmedValues = row.metrics_json.filter((m) => m.review_state === "confirmed").map((m) => norm(m.value).replace(/\s+/g, ""));
+  for (const s of sentences) {
+    const v = leadVerb(s.norm);
+    if (!v) continue;
+    let shared = 0;
+    for (const t of titleList) if (s.stems.has(t)) shared++;
+    const byTitle = titleList.length >= 2 && shared >= Math.max(2, Math.ceil(titleList.length / 2));
+    const flat = s.norm.replace(/\s+/g, "");
+    const byMetric = confirmedValues.some((val) => val.length >= 3 && flat.includes(val));
+    if (!byTitle && !byMetric) continue;
+    const existing = row.verbs_json.find((x) => x.verb === v);
+    if (existing) existing.review_state = "confirmed";
+    else row.verbs_json.push({ verb: v, tier: tier(v), source_variation_ids: [], source: "fixture", review_state: "confirmed" });
+  }
+  for (const c of row.verbatim_claims_json) {
+    const n = norm(c.text);
+    if (sentences.some((s) => s.norm.includes(n))) c.review_state = "confirmed";
+  }
+  return row;
+}
+
+function toIso(dateDisplay) {
+  // "Sep 2018" -> "2018-09"; "Present" -> null
+  const m = String(dateDisplay || "").match(/([A-Z][a-z]{2})\w*\s+(\d{4})/);
+  if (!m) return null;
+  const month = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"].indexOf(m[1].toLowerCase()) + 1;
+  return month ? `${m[2]}-${String(month).padStart(2, "0")}` : null;
+}
+
+/**
+ * @param {object[]} accomplishments  legacy records
+ * @param {object[]} variations       legacy bullet wordings
+ * @param {string[]} [fixtureTexts]   must-pass fixture texts; empty means all review
+ */
+function buildAccomplishmentRows(accomplishments, variations, fixtureTexts = []) {
+  const byRecord = new Map();
+  for (const v of variations || []) {
+    const list = byRecord.get(v.accomplishmentId) || [];
+    list.push({ id: v.id, text: v.text, recommended: v.isRecommended === true, score: v.variationScore || 0, quality_flags: v.qualityFlags || [] });
+    byRecord.set(v.accomplishmentId, list);
+  }
+  const sentences = fixtureSentences(fixtureTexts);
+  const rows = [];
+  for (const a of accomplishments) {
+    const wordings = (byRecord.get(a.id) || []).sort((x, y) => (y.recommended - x.recommended) || (y.score - x.score));
+    const outcome = { key: slug(a.title), text: a.title };
+    const row = {
+      id: a.id, title: a.title, company: a.company, role: a.role,
+      date_start: toIso(a.dates && a.dates.start), date_end: toIso(a.dates && a.dates.end),
+      summary: a.summary || a.action || null,
+      metrics_json: normalizeMetrics(a.metrics, outcome),
+      verbatim_claims_json: extractClaims(wordings),
+      verbs_json: extractVerbs(wordings),
+      subjects_json: [],
+      wordings_json: wordings.map((w) => ({ id: w.id, text: w.text, recommended: w.recommended, score: w.score })),
+      tags_json: [...new Set([...(a.tags || []), ...(a.skills || [])])],
+      strength_score: a.strengthScore ?? null,
+    };
+    rows.push(applyFixtureRule(row, wordings, sentences));
+  }
+  return rows;
+}
+
+/** Every dimension still in review state, flattened for the review list. */
+function reviewList(rows) {
+  const out = [];
+  for (const r of rows) {
+    for (const m of r.metrics_json) if (m.review_state !== "confirmed") out.push({ id: r.id, dimension: "metric", value: m.value, outcome_key: m.outcome_key });
+    for (const v of r.verbs_json) if (v.review_state !== "confirmed") out.push({ id: r.id, dimension: "verb", value: v.verb });
+    for (const c of r.verbatim_claims_json) if (c.review_state !== "confirmed") out.push({ id: r.id, dimension: c.type, value: c.text });
+  }
+  return out;
+}
+
+module.exports = { buildAccomplishmentRows, normalizeMetrics, extractClaims, extractVerbs, reviewList, isFragment, norm };

package/core/migrations/002-profile.sql

@@ -0,0 +1,3 @@
+-- v2: the candidate profile (employment skeleton, header, framing notes) moves out of
+-- the engine rules and into the store. Candidate data never lives in core/rules.
+ALTER TABLE candidate ADD COLUMN profile_json TEXT NOT NULL DEFAULT '{}';

package/core/migrations/003-discover.sql

@@ -0,0 +1,49 @@
+-- v3: the discover operation (plan section U, "shakedown"): the AI reads the confirmed records and
+-- asks the candidate what is missing; every answer lands pending against the record it extends.
+-- ai_run's operation check gains 'discover', a candidate-level run with no posting, interview, or
+-- source. SQLite cannot alter a CHECK in place, so the table is rebuilt (foreign keys are off for
+-- the migration transaction; migrate.js runs foreign_key_check before it commits).
+CREATE TABLE ai_run_v3 (
+  id TEXT PRIMARY KEY,
+  candidate_id TEXT NOT NULL REFERENCES candidate(id),
+  route TEXT NOT NULL CHECK (route IN ('mcp', 'paste', 'byo_key', 'credits', 'manual')),
+  operation TEXT NOT NULL CHECK (operation IN ('resume', 'cover', 'prep', 'onepager', 'deep_answers', 'followup', 'practice', 'categories', 'extract', 'style', 'dedup', 'discover')),
+  interview_id TEXT REFERENCES interview(id),
+  posting_id TEXT REFERENCES posting(id),
+  source_document_id TEXT REFERENCES source_document(id),
+  onboarding_batch_id TEXT REFERENCES onboarding_batch(id),
+  rules_version TEXT NOT NULL,
+  schema_version TEXT NOT NULL,
+  packet_version TEXT NOT NULL,
+  kb_revision INTEGER NOT NULL,
+  packet_hash TEXT NOT NULL,
+  kb_ids_json TEXT NOT NULL,
+  started_at TEXT NOT NULL,
+  finished_at TEXT,
+  final_result TEXT NOT NULL DEFAULT 'pending' CHECK (final_result IN ('pending', 'passed', 'blocked', 'error', 'abandoned')),
+  CHECK ((operation IN ('resume', 'cover', 'categories') AND posting_id IS NOT NULL)
+      OR (operation IN ('prep', 'onepager', 'deep_answers', 'followup', 'practice') AND interview_id IS NOT NULL)
+      OR (operation IN ('extract', 'style') AND source_document_id IS NOT NULL)
+      OR (operation = 'dedup' AND onboarding_batch_id IS NOT NULL)
+      OR (operation = 'discover'))
+);
+INSERT INTO ai_run_v3 SELECT id, candidate_id, route, operation, interview_id, posting_id, source_document_id, onboarding_batch_id, rules_version, schema_version, packet_version, kb_revision, packet_hash, kb_ids_json, started_at, finished_at, final_result FROM ai_run;
+DROP TABLE ai_run;
+ALTER TABLE ai_run_v3 RENAME TO ai_run;
+
+-- The questions a discovery run asked. Answering one writes a pending row (source 'manual', draft.replaces = the
+-- record) and links it here; confirming that row extends the record. Nothing on the record changes until then.
+CREATE TABLE kb_question (
+  id TEXT PRIMARY KEY,
+  candidate_id TEXT NOT NULL REFERENCES candidate(id),
+  ai_run_id TEXT NOT NULL REFERENCES ai_run(id),
+  accomplishment_id TEXT NOT NULL REFERENCES accomplishment(id),
+  kind TEXT NOT NULL CHECK (kind IN ('metric', 'scope', 'context', 'story', 'tenure', 'skill')),
+  question TEXT NOT NULL,
+  why TEXT,
+  asked_at TEXT NOT NULL,
+  answered_at TEXT,
+  pending_id TEXT REFERENCES pending_accomplishment(id) ON DELETE SET NULL,
+  dismissed_at TEXT
+);
+CREATE INDEX kb_question_open ON kb_question(candidate_id) WHERE answered_at IS NULL AND dismissed_at IS NULL;

package/core/parsers.js

@@ -0,0 +1,79 @@
+"use strict";
+
+/**
+ * Text extraction for uploaded sources (plan section U). Parsers are inputs
+ * from strangers once a second user exists, so every one runs under a cap:
+ * raw size, decompressed docx entries and bytes, PDF pages, and a timeout.
+ * An empty result is returned as a stored failure, never thrown away.
+ */
+
+const crypto = require("crypto");
+
+const LIMITS = { raw_bytes: 10 * 1024 * 1024, docx_entries: 200, docx_inflated_bytes: 50 * 1024 * 1024, pdf_pages: 60, timeout_ms: 30000, text_chars: 1048576 };
+const KINDS = { ".docx": "docx", ".pdf": "pdf", ".md": "md", ".txt": "txt" };
+
+const sha = (b) => crypto.createHash("sha256").update(b).digest("hex");
+
+function kindOf(filename) {
+  const m = String(filename).toLowerCase().match(/\.[a-z0-9]+$/);
+  return (m && KINDS[m[0]]) || null;
+}
+
+function withTimeout(promise, ms, what) {
+  let t;
+  const timer = new Promise((_, reject) => { t = setTimeout(() => reject(new Error(`${what} timed out after ${ms} ms`)), ms); });
+  return Promise.race([promise, timer]).finally(() => clearTimeout(t));
+}
+
+function normalizeText(s) {
+  return String(s || "").replace(/\r\n?/g, "\n").replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+async function parseDocx(buffer, limits) {
+  const JSZip = require("jszip");
+  const zip = await JSZip.loadAsync(buffer);
+  const entries = Object.values(zip.files);
+  if (entries.length > limits.docx_entries) throw new Error(`docx has ${entries.length} entries; the cap is ${limits.docx_entries}`);
+  let inflated = 0;
+  for (const e of entries) {
+    // JSZip exposes the uncompressed size on the internal data object
+    const size = (e._data && e._data.uncompressedSize) || 0;
+    inflated += size;
+    if (inflated > limits.docx_inflated_bytes) throw new Error("docx inflates past the cap");
+  }
+  const mammoth = require("mammoth");
+  const r = await mammoth.extractRawText({ buffer });
+  return { text: normalizeText(r.value), extractor: "mammoth", extractor_version: require("mammoth/package.json").version, pages: null, warnings: (r.messages || []).map((m) => m.message).slice(0, 5) };
+}
+
+async function parsePdf(buffer, limits) {
+  const { getDocumentProxy, extractText } = require("unpdf");
+  const pdf = await getDocumentProxy(new Uint8Array(buffer));
+  if (pdf.numPages > limits.pdf_pages) throw new Error(`pdf has ${pdf.numPages} pages; the cap is ${limits.pdf_pages}`);
+  const r = await extractText(pdf, { mergePages: true });
+  return { text: normalizeText(r.text), extractor: "unpdf", extractor_version: "1.8.1", pages: pdf.numPages, warnings: [] };
+}
+
+/**
+ * @returns {Promise<{ kind, file_hash, text, text_hash, extractor, extractor_version, pages, empty, failure }>}
+ */
+async function extractSource(filename, buffer, limits = LIMITS) {
+  const kind = kindOf(filename);
+  if (!kind) throw Object.assign(new Error("only docx, pdf, md, and txt are accepted"), { status: 415 });
+  if (buffer.length > limits.raw_bytes) throw Object.assign(new Error(`file is ${buffer.length} bytes; the cap is ${limits.raw_bytes}`), { status: 413 });
+  const file_hash = sha(buffer);
+  let out;
+  try {
+    if (kind === "docx") out = await withTimeout(parseDocx(buffer, limits), limits.timeout_ms, "docx extraction");
+    else if (kind === "pdf") out = await withTimeout(parsePdf(buffer, limits), limits.timeout_ms, "pdf extraction");
+    else out = { text: normalizeText(buffer.toString("utf8")), extractor: "plain", extractor_version: "1", pages: null, warnings: [] };
+  } catch (e) {
+    return { kind, file_hash, text: "", text_hash: sha(""), extractor: kind === "docx" ? "mammoth" : kind === "pdf" ? "unpdf" : "plain", extractor_version: "failed", pages: null, empty: true, failure: e.message };
+  }
+  if (out.text.length > limits.text_chars) out.text = out.text.slice(0, limits.text_chars);
+  const empty = out.text.length < 20;
+  return { kind, file_hash, text: out.text, text_hash: sha(out.text), extractor: out.extractor, extractor_version: out.extractor_version, pages: out.pages, empty,
+    failure: empty ? (kind === "pdf" ? "no text layer; OCR is not in v1, export the PDF from the source document or paste the text as .txt" : "no text found in the file") : null };
+}
+
+module.exports = { extractSource, kindOf, LIMITS, normalizeText };

package/core/practice.js

@@ -0,0 +1,75 @@
+"use strict";
+
+/**
+ * The practice workbook (Codification 3.6), built from a passed practice
+ * document: sheets of scenario data with the planted anomalies the manifest
+ * names, a Tasks tab, an AnswerKey tab with formulas as text, and a
+ * Solution tab. Deterministic from the document id so a grader can rebuild
+ * the same workbook. Pure: returns a description exceljs writes.
+ */
+
+function rng(seed) {
+  let s = 0;
+  for (const ch of String(seed)) s = (s * 31 + ch.charCodeAt(0)) >>> 0;
+  return () => { s = (s * 1664525 + 1013904223) >>> 0; return s / 4294967296; };
+}
+
+const NBSP = String.fromCharCode(160);
+
+function cellFor(col, r, row) {
+  const c = col.toLowerCase();
+  if (/id|key|number|no\b|#/.test(c)) return `${col.replace(/[^A-Za-z]/g, "").slice(0, 3).toUpperCase() || "ID"}-${1000 + row}`;
+  if (/date/.test(c)) { const d = new Date(Date.UTC(2026, 0, 1 + Math.floor(r() * 240))); return d.toISOString().slice(0, 10); }
+  if (/qty|count|units|pieces|weight|miles|hours/.test(c)) return Math.round(1 + r() * 400);
+  if (/rate|price|cost|amount|total|bill|charge|freight|fee|invoice/.test(c)) return Math.round((20 + r() * 980) * 100) / 100;
+  if (/tier|class|category|service|type|lane|mode|status/.test(c)) return ["A", "B", "C", "D"][Math.floor(r() * 4)];
+  if (/carrier|vendor|customer|client|name|shipper|consignee/.test(c)) return ["Northwind", "Harbor Goods", "Acme", "Globex", "Initech", "Umbrella"][Math.floor(r() * 6)];
+  if (/state|region/.test(c)) return ["IL", "IN", "MO", "IA", "OH", "MI"][Math.floor(r() * 6)];
+  return `${col} ${row}`;
+}
+
+/** Apply one planted anomaly to a row of cells (by column name), returning what changed. */
+function plant(kind, cells, cols, r) {
+  const money = cols.filter((c) => /rate|price|cost|amount|total|bill|charge|freight|fee|invoice/i.test(c));
+  const numeric = cols.filter((c) => typeof cells[c] === "number");
+  const text = cols.filter((c) => typeof cells[c] === "string" && !/id|key|date/i.test(c));
+  const pick = (list) => list[Math.floor(r() * list.length)];
+  switch (kind) {
+    case "overbill": { const c = pick(money.length ? money : numeric); if (c == null) return null; const was = cells[c]; cells[c] = Math.round(was * (1.15 + r() * 0.4) * 100) / 100; return { column: c, was, now: cells[c] }; }
+    case "underbill": { const c = pick(money.length ? money : numeric); if (c == null) return null; const was = cells[c]; cells[c] = Math.round(was * (0.55 + r() * 0.3) * 100) / 100; return { column: c, was, now: cells[c] }; }
+    case "duplicate": return { column: "*", was: null, now: "row repeated" };
+    case "orphan_key": { const c = cols.find((x) => /id|key/i.test(x)) || cols[0]; const was = cells[c]; cells[c] = "ZZ-9" + Math.floor(r() * 900 + 100); return { column: c, was, now: cells[c] }; }
+    case "whitespace": { const c = pick(text.length ? text : cols); const was = cells[c]; cells[c] = "  " + was + " "; return { column: c, was, now: cells[c] }; }
+    case "nbsp": { const c = pick(text.length ? text : cols); const was = cells[c]; cells[c] = String(was) + NBSP; return { column: c, was, now: cells[c] }; }
+    case "text_number": { const c = pick(numeric.length ? numeric : cols); const was = cells[c]; cells[c] = String(was); return { column: c, was, now: cells[c] }; }
+    case "mislabel": { const c = cols.find((x) => /tier|class|category|service|type|status/i.test(x)) || pick(text.length ? text : cols); const was = cells[c]; cells[c] = "Misc"; return { column: c, was, now: cells[c] }; }
+    case "wrong_tier": { const c = cols.find((x) => /tier|class|category|service|type/i.test(x)); if (!c) return null; const was = cells[c]; cells[c] = was === "A" ? "D" : "A"; return { column: c, was, now: cells[c], note: "the amount is right for the tier shown; the tier is what is wrong" }; }
+    default: return null;
+  }
+}
+
+/** @returns { sheets: [{name, columns, rows: [[...]]}], answerKey: [...], solution: [...], planted: [...] } */
+function buildWorkbook(content, seed) {
+  const r = rng(seed || content.scenario);
+  const sheets = [];
+  const planted = [];
+  for (const spec of content.sheets) {
+    const rows = [];
+    const anomalies = content.anomalies.filter((a) => a.sheet === spec.name);
+    for (let i = 1; i <= spec.rows; i++) {
+      const cells = {};
+      for (const col of spec.columns) cells[col] = cellFor(col, r, i);
+      rows.push(cells);
+    }
+    for (const a of anomalies) {
+      const idx = Math.min(Math.max(1, a.row), rows.length) - 1;
+      const change = plant(a.kind, rows[idx], spec.columns, r);
+      if (a.kind === "duplicate") rows.splice(idx + 1, 0, { ...rows[idx] });
+      planted.push({ sheet: spec.name, row: idx + 2, kind: a.kind, description: a.description, ...(change || {}) });
+    }
+    sheets.push({ name: spec.name, columns: spec.columns, rows: rows.map((c) => spec.columns.map((col) => c[col])) });
+  }
+  return { sheets, tasks: content.tasks, answerKey: content.answer_key, planted, lesson: content.lesson || "" };
+}
+
+module.exports = { buildWorkbook, plant, NBSP };