@gafj/gafj 0.1.1

package/bridge/byo_key.js

@@ -0,0 +1,50 @@
+"use strict";
+
+/**
+ * byo_key route (phase 6): the local server calls the provider the user
+ * configured through a one-file adapter, then hands the reply to
+ * ingest_document. Keys live in config.json and never in the store or a
+ * log. https unless loopback; no redirects; a fixed hello for the test.
+ */
+
+const { readConfig } = require("../store/config");
+const providers = require("./providers");
+
+function providerById(homeDir, id) {
+  const cfg = readConfig(homeDir);
+  const p = (cfg.providers || []).find((x) => x.id === id);
+  if (!p) throw Object.assign(new Error("unknown provider"), { status: 404 });
+  return p;
+}
+
+function scrub(message, key) {
+  return key ? String(message).split(key).join("[key]") : String(message);
+}
+
+async function testProvider(homeDir, id, fetchImpl) {
+  const p = providerById(homeDir, id);
+  const adapter = providers.adapterFor(p.kind);
+  const started = Date.now();
+  try {
+    const r = await adapter.complete({ provider: p, system: "Reply with the single word: ready", user: "hello", max_tokens: 16, fetch: fetchImpl });
+    return { ok: true, message: `${p.kind} ${p.model || ""}: ${String(r.text).trim().slice(0, 40)} (${Date.now() - started} ms)`, tokens_in: r.tokens_in, tokens_out: r.tokens_out };
+  } catch (e) {
+    return { ok: false, message: scrub(e.message, p.api_key) };
+  }
+}
+
+/** Run one packet through the provider; returns what ingest needs plus attempt metadata. */
+async function runPacket(homeDir, id, { packet, fetchImpl }) {
+  const p = providerById(homeDir, id);
+  const adapter = providers.adapterFor(p.kind);
+  const { renderPasteText } = require("./paste");
+  const started = Date.now();
+  try {
+    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.", user: renderPasteText(packet), max_tokens: 8000, 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 };
+  } catch (e) {
+    throw Object.assign(new Error(scrub(e.message, p.api_key)), { status: 502 });
+  }
+}
+
+module.exports = { testProvider, runPacket, providerById };

package/bridge/credits.js

@@ -0,0 +1,72 @@
+"use strict";
+
+/**
+ * credits route (phase 7, local half): the local server posts the packet
+ * the app built to the relay with the user's Google ID token and hands the
+ * reply to ingest_document like every other route. The relay URL and the
+ * token live in config.json under the user only, never in the store or a
+ * log; the token is masked on read. https only, except loopback for a
+ * local dry run. The relay is not deployed yet; this is the interface
+ * decision 7 reserved, built so the go decision needs no local change.
+ */
+
+const { readConfig } = require("../store/config");
+const { ulid } = require("../core/ulid");
+
+class CreditsError extends Error {
+  constructor(message, status = 502) { super(message); this.status = status; }
+}
+
+function creditsConfig(homeDir) {
+  const cfg = readConfig(homeDir);
+  const c = cfg.credits || {};
+  if (!c.relay_url) throw new CreditsError("no relay url; set it in settings", 409);
+  if (!c.id_token) throw new CreditsError("sign in to credits first; paste the token in settings", 409);
+  if (!/^https:\/\//i.test(c.relay_url) && !/^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?/i.test(c.relay_url)) throw new CreditsError("relay url must be https", 400);
+  return { relay_url: String(c.relay_url).replace(/\/+$/, ""), id_token: String(c.id_token) };
+}
+
+function scrub(message, token) {
+  return token ? String(message).split(token).join("[token]") : String(message);
+}
+
+/**
+ * auth, when given, replaces the config: the hosted server calls the relay with a service key and
+ * the user's uid ({ relay_url, headers }); a user token is never stored on the hosted side.
+ */
+async function relayFetch(homeDir, path, { method = "GET", body, fetchImpl, auth } = {}) {
+  const c = auth ? { relay_url: String(auth.relay_url).replace(/\/+$/, ""), id_token: null, headers: auth.headers } : creditsConfig(homeDir);
+  const f = fetchImpl || fetch;
+  let res;
+  try {
+    res = await f(c.relay_url + path, { method, redirect: "error", headers: { ...(c.id_token ? { authorization: `Bearer ${c.id_token}` } : c.headers || {}), "content-type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  } catch (e) {
+    throw new CreditsError("relay unreachable: " + scrub(e.message, c.id_token), 502);
+  }
+  let data = null;
+  try { data = await res.json(); } catch (_) { data = null; }
+  if (!res.ok) throw new CreditsError(`relay refused (${res.status}): ${scrub((data && data.error) || "no detail", c.id_token)}`, res.status === 401 || res.status === 402 || res.status === 429 ? res.status : 502);
+  return data;
+}
+
+/** Run one packet through the relay; returns what ingest needs plus attempt metadata. */
+async function runPacket(homeDir, { packet, fetchImpl, auth }) {
+  const started = Date.now();
+  const op_id = ulid(started);
+  const r = await relayFetch(homeDir, "/op", { method: "POST", body: { op: packet.op, op_id, packet }, fetchImpl, auth });
+  if (!r || typeof r.content !== "string") throw new CreditsError("relay reply had no content", 502);
+  return { content: r.content, provider: "credits", model: r.model || null, tokens_in: r.tokens_in ?? null, tokens_out: r.tokens_out ?? null, latency_ms: Date.now() - started, charged: r.charged, credits_left: r.credits_left };
+}
+
+async function balance(homeDir, fetchImpl, auth) {
+  return relayFetch(homeDir, "/balance", { fetchImpl, auth });
+}
+
+/** Start a purchase: the relay makes the Stripe Checkout session; the browser goes to its url. */
+async function checkout(homeDir, pack, fetchImpl, auth) {
+  const r = await relayFetch(homeDir, "/checkout", { method: "POST", body: { pack: String(pack || "") }, fetchImpl, auth });
+  if (!r || typeof r.url !== "string" || !/^https:\/\//.test(r.url)) throw new CreditsError("relay returned no checkout url", 502);
+  return { url: r.url };
+}
+
+module.exports = { runPacket, balance, checkout, creditsConfig, CreditsError };

package/bridge/paste.js

@@ -0,0 +1,44 @@
+"use strict";
+
+/**
+ * Paste route serialization. The packet becomes one text file you copy into
+ * any chat window; the reply is one fenced JSON block you save and hand to
+ * gafj ingest with the run handle printed at the top. Serialization is the
+ * adapter's job; the packet itself is route-agnostic.
+ */
+
+function block(title, body) {
+  return `\n\n## ${title}\n\n${body}`;
+}
+
+function json(o) {
+  return "```json\n" + JSON.stringify(o, null, 1) + "\n```";
+}
+
+function renderPasteText(packet, { run_id } = {}) {
+  const c = packet.context;
+  const head = [
+    `# GAF-J packet: ${packet.operation}${run_id ? ` (run ${run_id})` : ""}`,
+    "",
+    "Read everything below, then reply with exactly one fenced ```json block that matches OUTPUT SCHEMA. No prose before or after the block.",
+    "Cite knowledge base records by the id shown beside each record, in the claims array of every claim-bearing field. Never invent an id, a figure, or a date.",
+    run_id ? `The reply is saved to a file and ingested with: gafj ingest --run ${run_id} --file <reply file>` : "",
+  ].filter(Boolean).join("\n");
+  let out = head;
+  out += block(`RULES (engine ${packet.rules_version})`, packet.rules.trim());
+  if (c.source) out += block(`SOURCE (${c.source.filename}, ${c.source.chars} characters; spans index into this text from 0)`, c.source.text);
+  if (c.profile) out += block("PROFILE", json(c.profile));
+  if (c.posting) out += block("POSTING (excerpt)", json(c.posting));
+  if (c.scoring) out += block("SCORING (frozen)", json(c.scoring));
+  if (c.application) out += block("APPLICATION (this application only)", json(c.application));
+  if (c.budget) out += block("CONTENT BUDGET", json(c.budget));
+  if (c.house_rules) out += block("HOUSE RULES", json(c.house_rules));
+  if (packet.kb_slice.length) {
+    out += block(`KNOWLEDGE BASE SLICE (${packet.kb_slice.length} records; cite ids exactly as shown)`,
+      packet.kb_slice.map((r) => JSON.stringify(r)).join("\n"));
+  }
+  out += block(`OUTPUT SCHEMA (schema ${packet.schema_version}, JSON Schema)`, json(packet.output_schema));
+  return out + "\n";
+}
+
+module.exports = { renderPasteText };

package/bridge/providers/anthropic.js

@@ -0,0 +1,16 @@
+"use strict";
+
+const DEFAULT_URL = "https://api.anthropic.com";
+const DEFAULT_MODEL = "claude-fable-5-1";
+
+async function complete({ provider, system, user, max_tokens = 4000, fetch }) {
+  const { post } = require("./index");
+  const base = (provider.base_url || DEFAULT_URL).replace(/\/$/, "");
+  const model = provider.model || DEFAULT_MODEL;
+  const data = await post(fetch, `${base}/v1/messages`, { "x-api-key": provider.api_key || "", "anthropic-version": "2023-06-01" },
+    { model, max_tokens, system, messages: [{ role: "user", content: user }] });
+  const text = (data.content || []).filter((c) => c.type === "text").map((c) => c.text).join("\n");
+  return { text, model: data.model || model, tokens_in: data.usage && data.usage.input_tokens, tokens_out: data.usage && data.usage.output_tokens };
+}
+
+module.exports = { complete, DEFAULT_URL, DEFAULT_MODEL };

package/bridge/providers/gemini.js

@@ -0,0 +1,15 @@
+"use strict";
+
+const DEFAULT_URL = "https://generativelanguage.googleapis.com/v1beta";
+
+async function complete({ provider, system, user, max_tokens = 4000, fetch }) {
+  const { post } = require("./index");
+  const base = (provider.base_url || DEFAULT_URL).replace(/\/$/, "");
+  const model = provider.model || "gemini-2.5-pro";
+  const data = await post(fetch, `${base}/models/${encodeURIComponent(model)}:generateContent`, { "x-goog-api-key": provider.api_key || "" },
+    { systemInstruction: { parts: [{ text: system }] }, contents: [{ role: "user", parts: [{ text: user }] }], generationConfig: { maxOutputTokens: max_tokens } });
+  const text = ((data.candidates && data.candidates[0] && data.candidates[0].content && data.candidates[0].content.parts) || []).map((p) => p.text || "").join("\n");
+  return { text, model, tokens_in: data.usageMetadata && data.usageMetadata.promptTokenCount, tokens_out: data.usageMetadata && data.usageMetadata.candidatesTokenCount };
+}
+
+module.exports = { complete, DEFAULT_URL };

package/bridge/providers/index.js

@@ -0,0 +1,39 @@
+"use strict";
+
+/**
+ * Provider registry: one adapter file per vendor, several stored, one
+ * active per run. Each adapter exposes complete({ provider, system, user,
+ * max_tokens, fetch }) -> { text, model, tokens_in, tokens_out } and uses
+ * fetch only: no vendor SDK, no redirects, https unless loopback.
+ */
+
+const ADAPTERS = { anthropic: require("./anthropic"), openai_compatible: require("./openai_compatible"), gemini: require("./gemini") };
+
+function adapterFor(kind) {
+  const a = ADAPTERS[kind];
+  if (!a) throw Object.assign(new Error(`no adapter for ${kind}`), { status: 400 });
+  return a;
+}
+
+function checkUrl(url) {
+  const u = new URL(url);
+  const loop = u.hostname === "127.0.0.1" || u.hostname === "localhost" || u.hostname === "[::1]";
+  if (u.protocol !== "https:" && !(u.protocol === "http:" && loop)) throw new Error("provider base_url must be https, or http on loopback");
+  return u.toString();
+}
+
+async function post(fetchImpl, url, headers, body, timeoutMs = 120000) {
+  const f = fetchImpl || globalThis.fetch;
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const r = await f(checkUrl(url), { method: "POST", headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(body), redirect: "error", signal: ac.signal });
+    const text = await r.text();
+    let data;
+    try { data = JSON.parse(text); } catch (_) { data = { raw: text.slice(0, 300) }; }
+    if (!r.ok) throw new Error(`${r.status} from provider: ${(data.error && (data.error.message || data.error)) || data.raw || r.statusText}`.slice(0, 300));
+    return data;
+  } finally { clearTimeout(t); }
+}
+
+module.exports = { adapterFor, post, checkUrl, ADAPTERS };

package/bridge/providers/openai_compatible.js

@@ -0,0 +1,17 @@
+"use strict";
+
+/** OpenAI, Groq, Together, OpenRouter, Mistral, DeepSeek, xAI, Ollama, LM Studio: chat completions. */
+
+const DEFAULT_URL = "https://api.openai.com/v1";
+
+async function complete({ provider, system, user, max_tokens = 4000, fetch }) {
+  const { post } = require("./index");
+  const base = (provider.base_url || DEFAULT_URL).replace(/\/$/, "");
+  const model = provider.model || "gpt-5";
+  const headers = provider.api_key ? { authorization: `Bearer ${provider.api_key}` } : {};
+  const data = await post(fetch, `${base}/chat/completions`, headers, { model, max_tokens, messages: [{ role: "system", content: system }, { role: "user", content: user }] });
+  const text = (data.choices && data.choices[0] && data.choices[0].message && data.choices[0].message.content) || "";
+  return { text, model: data.model || model, tokens_in: data.usage && data.usage.prompt_tokens, tokens_out: data.usage && data.usage.completion_tokens };
+}
+
+module.exports = { complete, DEFAULT_URL };

package/core/extract.js

@@ -0,0 +1,55 @@
+"use strict";
+
+/**
+ * Model text to JSON. Strips code fences and prose around the object. A
+ * failure here is a schema block, not a crash: the paste loop is expected
+ * to fail the first time. Two hard limits apply before parsing: one
+ * megabyte of content, nesting no deeper than 64 levels, and no __proto__
+ * key at any depth (JSON.parse makes it an own property, and nothing
+ * downstream should have to think about it).
+ */
+
+const MAX_BYTES = 1024 * 1024;
+
+const MAX_DEPTH = 64;
+
+/** The first problem with a parsed value: a __proto__ key anywhere, or nesting past MAX_DEPTH (JSON.stringify would overflow on it later). */
+function inspect(v, depth = 0) {
+  if (!v || typeof v !== "object") return null;
+  if (depth > MAX_DEPTH) return `nested deeper than ${MAX_DEPTH} levels`;
+  if (Array.isArray(v)) { for (const x of v) { const e = inspect(x, depth + 1); if (e) return e; } return null; }
+  for (const k of Object.keys(v)) { if (k === "__proto__") return "rejected key __proto__"; const e = inspect(v[k], depth + 1); if (e) return e; }
+  return null;
+}
+
+function extractJson(text, { maxBytes = MAX_BYTES } = {}) {
+  if (text && typeof text === "object") {
+    if (Array.isArray(text)) return { error: "expected an object, got an array" };
+    let size;
+    try { size = Buffer.byteLength(JSON.stringify(text)); } catch (e) { return { error: "content is not serializable: " + e.message }; }
+    if (size > maxBytes) return { error: `content larger than ${Math.round(maxBytes / 1024 / 1024)} MB` };
+    const bad = inspect(text);
+    if (bad) return { error: bad };
+    return { value: text };
+  }
+  let s = String(text ?? "");
+  if (Buffer.byteLength(s) > maxBytes) return { error: `content larger than ${Math.round(maxBytes / 1024 / 1024)} MB` };
+  s = s.trim();
+  const fence = s.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fence) s = fence[1].trim();
+  const start = s.indexOf("{");
+  const end = s.lastIndexOf("}");
+  if (start === -1 || end === -1 || end < start) return { error: "no JSON object found" };
+  let value;
+  try {
+    value = JSON.parse(s.slice(start, end + 1));
+  } catch (e) {
+    return { error: "JSON parse failed: " + String(e.message).slice(0, 200) };
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return { error: "expected an object" };
+  const bad = inspect(value);
+  if (bad) return { error: bad };
+  return { value };
+}
+
+module.exports = { extractJson, MAX_BYTES, MAX_DEPTH };

package/core/generators/excerpt.js

@@ -0,0 +1,64 @@
+"use strict";
+
+/**
+ * Posting excerpt, not posting text. The packet carries title, location,
+ * comp, the scan's evidence lines, and a bounded window of body around
+ * them. The full raw_text stays on disk for scoring and validator 7.
+ */
+
+const { scanJobDescription } = require("../scoring");
+const { clip } = require("./serialize");
+
+const DEFAULT_EXCERPT_BYTES = 6000;
+const DEFAULT_WINDOW = 240;
+
+function mergeRanges(ranges) {
+  const sorted = ranges.slice().sort((a, b) => a[0] - b[0]);
+  const out = [];
+  for (const r of sorted) {
+    const last = out[out.length - 1];
+    if (last && r[0] <= last[1]) last[1] = Math.max(last[1], r[1]);
+    else out.push([r[0], r[1]]);
+  }
+  return out;
+}
+
+function postingExcerpt(posting, { categories = [], budget = DEFAULT_EXCERPT_BYTES, window = DEFAULT_WINDOW } = {}) {
+  const text = String(posting.raw_text || "");
+  const scan = scanJobDescription(text);
+  const lines = [];
+  const push = (l) => { const t = String(l || "").trim(); if (t && !lines.includes(t)) lines.push(t); };
+  for (const c of categories) for (const e of c.jd_evidence || []) push(e);
+  for (const l of scan.hardGateLines) push(l);
+  for (const a of scan.aiTriggers) push(a.line);
+
+  let body;
+  let truncated = false;
+  if (!lines.length) {
+    body = clip(text, budget);
+    truncated = body.length < text.length;
+  } else {
+    const ranges = [];
+    for (const l of lines) {
+      const i = text.indexOf(l);
+      if (i >= 0) ranges.push([Math.max(0, i - window), Math.min(text.length, i + l.length + window)]);
+    }
+    const parts = [];
+    let used = 0;
+    for (const [a, b] of mergeRanges(ranges)) {
+      const piece = text.slice(a, b).trim();
+      if (used + piece.length > budget) { truncated = true; break; }
+      parts.push((a > 0 ? "… " : "") + piece + (b < text.length ? " …" : ""));
+      used += piece.length;
+    }
+    body = parts.join("\n\n");
+    if (!body) { body = clip(text, budget); truncated = body.length < text.length; }
+  }
+  return {
+    company: posting.company, title: posting.title, location: posting.location || null, comp_text: posting.comp_text || null,
+    source_url: posting.source_url || null, evidence_lines: lines.slice(0, 40), body, truncated, raw_length: text.length,
+    ai_trigger_fired: scan.aiTriggerFired,
+  };
+}
+
+module.exports = { postingExcerpt, DEFAULT_EXCERPT_BYTES };

package/core/generators/packet.js

@@ -0,0 +1,197 @@
+"use strict";
+
+/**
+ * One semantic packet per operation: rules (engine, versioned), context,
+ * the KB slice with ids, and the output JSON schema. Pure: everything comes
+ * in as plain objects; the store gathers, the bridge serializes per route.
+ *
+ * Rules the builder enforces (plan, packet contract):
+ *  - resume, cover, prep, onepager, deep_answers refuse to build without a frozen scoring row
+ *  - prep-family packets carry this application's facts only
+ *  - the slice follows precedence and a byte budget; a required set that overflows fails closed
+ *  - the posting travels as an excerpt
+ *  - no field of the packet carries the comp floor; the builder never receives it
+ */
+
+const crypto = require("crypto");
+const { rulesFor, rulesVersion } = require("../rules");
+const { SCHEMAS, SCHEMA_VERSION, toJsonSchema } = require("../schemas");
+const { BUDGET } = require("../schemas/onepager");
+const { selectSlice } = require("./slice");
+const { postingExcerpt } = require("./excerpt");
+const { clip, serializeRecord, bytesOf } = require("./serialize");
+
+const PACKET_VERSION = "1";
+const POSTING_OPS = new Set(["resume", "cover", "categories"]);
+const NEEDS_SCORING = new Set(["resume", "cover", "prep", "onepager", "deep_answers"]);
+const NO_SLICE = new Set(["practice", "categories", "extract"]);
+const DISCOVER_SLICE_BYTES = 40000;
+const PRIOR_QUESTIONS_CAP = 60;
+const SOURCE_TEXT_CAP = 60000;
+const DEBRIEF_CAP = 4000;
+const DEBRIEF_TOTAL_CAP = 12000;
+const PREP_CONTENT_CAP = 14000;
+
+const INTERVIEW_PROFILE_KEYS = ["people_leadership", "capability_notes", "framing_notes", "retired_phrasings", "style", "interview_do_nots", "education", "native_industries"];
+
+class PacketError extends Error {
+  constructor(message, detail) { super(message); this.name = "PacketError"; this.detail = detail; }
+}
+
+function profileFor(op, profile) {
+  const p = profile || {};
+  if (POSTING_OPS.has(op)) { const { _note, ...rest } = p; return rest; }
+  const out = {};
+  for (const k of INTERVIEW_PROFILE_KEYS) if (k in p) out[k] = p[k];
+  return out;
+}
+
+function scoringContext(scoring) {
+  if (!scoring) return null;
+  return {
+    fit_score: scoring.fit_score, verdict: scoring.verdict, verdict_reason: scoring.verdict_reason || null,
+    categories: (scoring.categories || []).map((c) => ({ category: c.category, weight: c.weight, is_hard_gate: !!c.is_hard_gate,
+      jd_evidence: c.jd_evidence || [], score: c.score ?? null, evidence_ids: c.evidence_ids || [] })),
+  };
+}
+
+function person(p) {
+  return { person_id: p.id, name: p.name, title: p.title || null, org: p.org || null, role: p.role || null, intel: clip(p.intel_text, 600) || null };
+}
+
+function applicationContext(op, app) {
+  if (!app) return null;
+  const rounds = (app.interviews || []).filter((i) => i.status !== "superseded");
+  const thisRound = rounds.find((i) => i.id === app.interview_id);
+  if (!thisRound) throw new PacketError("interview is not on this application");
+  let debriefBytes = 0;
+  const prior = rounds.filter((i) => i.id !== thisRound.id && (i.status === "completed" || i.scheduled_at < thisRound.scheduled_at))
+    .sort((a, b) => a.scheduled_at.localeCompare(b.scheduled_at))
+    .map((i) => {
+      let debrief = i.debrief_text ? clip(i.debrief_text, DEBRIEF_CAP) : null;
+      if (debrief && debriefBytes + debrief.length > DEBRIEF_TOTAL_CAP) debrief = clip(debrief, Math.max(0, DEBRIEF_TOTAL_CAP - debriefBytes));
+      if (debrief) debriefBytes += debrief.length;
+      return { interview_id: i.id, round_label: i.round_label, format: i.format, status: i.status, outcome: i.outcome, debrief, people: (i.people || []).map(person) };
+    });
+  const documents = (app.documents || []).filter((d) => d.status === "passed").map((d) => ({ document_id: d.id, kind: d.kind, interview_id: d.interview_id || null }));
+  const ctx = {
+    company: app.company, title: app.title, status: app.status,
+    this_round: { interview_id: thisRound.id, round_label: thisRound.round_label, format: thisRound.format, status: thisRound.status,
+      scheduled_at: thisRound.scheduled_at, tz: thisRound.tz, people: (thisRound.people || []).map(person),
+      debrief: op === "followup" && thisRound.debrief_text ? clip(thisRound.debrief_text, DEBRIEF_CAP) : null },
+    prior_rounds: prior,
+    people: (app.people || []).map(person),
+    documents,
+  };
+  // The schema bounds a passed prep, so it travels whole; the cap is a guard against a hand-edited row.
+  if (["onepager", "deep_answers"].includes(op) && app.prep && JSON.stringify(app.prep).length <= PREP_CONTENT_CAP) ctx.prep = app.prep;
+  return ctx;
+}
+
+/**
+ * Discovery is a candidate-level packet: no posting, no interview, no scoring. The slice is the
+ * confirmed records, thinnest first (records the holes name, then fewest confirmed figures), under
+ * its own budget; the context carries the engine's holes and every prior question so the model
+ * digs instead of repeating.
+ */
+function discoverPacket(a) {
+  const records = a.records || [];
+  if (!records.length) throw new PacketError("discovery needs at least one confirmed record; confirm the pending rows first");
+  const holes = a.holes || [];
+  const holeIds = new Set(holes.map((h) => h.accomplishment_id));
+  const confirmedMetrics = (r) => (r.metrics_json || []).filter((m) => m.review_state === "confirmed").length;
+  const ordered = [...records].sort((x, y) => (holeIds.has(y.id) - holeIds.has(x.id)) || (confirmedMetrics(x) - confirmedMetrics(y)) || ((y.strength_score || 0) - (x.strength_score || 0)) || x.id.localeCompare(y.id));
+  const budget = (a.budgets && a.budgets.slice_bytes) || DISCOVER_SLICE_BYTES;
+  const slice = [];
+  let bytes = 0;
+  for (const r of ordered) {
+    const json = serializeRecord(r, a.budgets && a.budgets.record_bytes);
+    const size = bytesOf(json) + 1;
+    if (bytes + size > budget) break;
+    bytes += size;
+    slice.push(json);
+  }
+  const ids = slice.map((r) => r.id);
+  const inSlice = new Set(ids);
+  const packet = {
+    packet_version: PACKET_VERSION, operation: "discover", rules: rulesFor("discover"), rules_version: rulesVersion(), schema_version: SCHEMA_VERSION,
+    output_schema: toJsonSchema(SCHEMAS.discover),
+    context: {
+      candidate: a.candidate.name,
+      records_confirmed: records.length, records_in_slice: ids.length,
+      holes: holes.filter((h) => inSlice.has(h.accomplishment_id)).map((h) => ({ accomplishment_id: h.accomplishment_id, kind: h.kind, hint: clip(h.question, 200) })),
+      prior_questions: (a.prior_questions || []).filter((q) => inSlice.has(q.accomplishment_id)).slice(0, PRIOR_QUESTIONS_CAP).map((q) => ({ accomplishment_id: q.accomplishment_id, kind: q.kind, question: clip(q.question, 200), status: q.status })),
+      note: "Ask about records in the slice only, by id. Answers are written by the candidate and land pending against that record.",
+    },
+    kb_slice: slice, kb_ids: ids, slice_reasons: Object.fromEntries(ids.map((id) => [id, holeIds.has(id) ? "hole" : "thin"])), kb_revision: a.candidate.kb_revision ?? 0,
+  };
+  packet.packet_hash = hashPacket(packet);
+  return packet;
+}
+
+function hashPacket(p) {
+  const h = crypto.createHash("sha256");
+  h.update(JSON.stringify({ operation: p.operation, rules_version: p.rules_version, schema_version: p.schema_version, context: p.context, kb_slice: p.kb_slice }));
+  return h.digest("hex");
+}
+
+/**
+ * @param {object} a { op, candidate:{name, profile, kb_revision}, posting, scoring|null, application|null, records:[parsed], pinned_ids, budgets }
+ */
+function buildPacket(a) {
+  const op = a.op;
+  if (!SCHEMAS[op]) throw new PacketError(`unknown operation ${op}`);
+  if (op === "extract") {
+    if (!a.source) throw new PacketError("extract needs a source document");
+    if (!a.source.text || a.source.text.length < 20) throw new PacketError("this source has no text; extraction failed at upload");
+    const packet = {
+      packet_version: PACKET_VERSION, operation: op, rules: rulesFor(op), rules_version: rulesVersion(), schema_version: SCHEMA_VERSION,
+      output_schema: toJsonSchema(SCHEMAS[op]),
+      context: { candidate: a.candidate.name, source: { source_document_id: a.source.id, filename: a.source.filename, kind: a.source.kind, chars: a.source.text.length,
+        text: a.source.text.slice(0, SOURCE_TEXT_CAP), truncated: a.source.text.length > SOURCE_TEXT_CAP,
+        note: "Spans are character offsets into this text exactly as given, starting at 0." } },
+      kb_slice: [], kb_ids: [], slice_reasons: {}, kb_revision: a.candidate.kb_revision ?? 0,
+    };
+    packet.packet_hash = hashPacket(packet);
+    return packet;
+  }
+  if (op === "discover") return discoverPacket(a);
+  if (POSTING_OPS.has(op) && a.application) throw new PacketError(`${op} is a posting packet; it does not take an interview`);
+  if (!POSTING_OPS.has(op) && !a.application) throw new PacketError(`${op} needs an interview on an application`);
+  if (!a.posting) throw new PacketError("no posting");
+  if (a.posting.status !== "accepted") throw new PacketError("posting is not accepted");
+  if (NEEDS_SCORING.has(op) && (!a.scoring || a.scoring.status !== "frozen")) {
+    throw new PacketError(`${op} needs frozen scoring for ${a.posting.company}: ${a.posting.title}; run gafj score-freeze first`);
+  }
+  const budgets = a.budgets || {};
+  const categories = a.scoring && a.scoring.status === "frozen" ? a.scoring.categories || [] : [];
+  const slice = NO_SLICE.has(op)
+    ? { records: [], ids: [], reasons: {}, bytes: 0 }
+    : selectSlice({ records: a.records || [], categories, pinned_ids: a.pinned_ids || [], posting: a.posting, budget: budgets.slice_bytes, recordBytes: budgets.record_bytes });
+  const context = {
+    candidate: a.candidate.name,
+    profile: profileFor(op, a.candidate.profile),
+    posting: postingExcerpt(a.posting, { categories, budget: budgets.excerpt_bytes }),
+    scoring: NEEDS_SCORING.has(op) ? scoringContext(a.scoring) : null,
+    application: applicationContext(op, a.application),
+  };
+  if (op === "onepager") context.budget = BUDGET;
+  if (a.house) context.house_rules = a.house;
+  const packet = {
+    packet_version: PACKET_VERSION,
+    operation: op,
+    rules: rulesFor(op),
+    rules_version: rulesVersion(),
+    schema_version: SCHEMA_VERSION,
+    output_schema: toJsonSchema(SCHEMAS[op]),
+    context,
+    kb_slice: slice.records,
+    kb_ids: slice.ids,
+    slice_reasons: slice.reasons,
+    kb_revision: a.candidate.kb_revision ?? 0,
+  };
+  packet.packet_hash = hashPacket(packet);
+  return packet;
+}
+
+module.exports = { buildPacket, PacketError, PACKET_VERSION, POSTING_OPS, NEEDS_SCORING, hashPacket };

package/core/generators/serialize.js

@@ -0,0 +1,56 @@
+"use strict";
+
+/**
+ * One knowledge base record as the packet shows it: id beside the text in
+ * the exact form the schema wants back, confirmed dimensions only, bounded
+ * per record so a single record cannot eat the slice budget.
+ */
+
+const DEFAULT_RECORD_BYTES = 1800;
+
+function clip(s, n) {
+  const t = String(s || "");
+  return t.length <= n ? t : t.slice(0, Math.max(0, n - 1)).replace(/\s+\S*$/, "") + "…";
+}
+
+function dates(r) {
+  const a = r.date_start ? String(r.date_start).slice(0, 7) : "";
+  const b = r.date_end ? String(r.date_end).slice(0, 7) : "";
+  return a && b ? `${a} to ${b}` : a || b || "";
+}
+
+function bytesOf(o) {
+  return Buffer.byteLength(JSON.stringify(o), "utf8");
+}
+
+function serializeRecord(r, maxBytes = DEFAULT_RECORD_BYTES) {
+  const confirmed = (xs) => (xs || []).filter((x) => x.review_state === "confirmed");
+  const out = {
+    id: r.id,
+    company: r.company,
+    role: r.role,
+    dates: dates(r),
+    title: r.title,
+    summary: clip(r.summary, 400),
+    metrics: confirmed(r.metrics_json).map((m) => ({ value: m.value, outcome_key: m.outcome_key, outcome: clip(m.outcome, 120) })),
+    verbs: confirmed(r.verbs_json).map((v) => ({ verb: v.verb, tier: v.tier })),
+    claims: confirmed(r.verbatim_claims_json).map((c) => ({ type: c.type, text: c.text })),
+    wordings: (r.wordings_json || []).slice(0, 3).map((w) => ({ id: w.id, text: clip(w.text, 300) })),
+  };
+  // Trim from the least load-bearing end until the record fits: wordings, then summary.
+  while (bytesOf(out) > maxBytes && out.wordings.length) out.wordings.pop();
+  if (bytesOf(out) > maxBytes) out.summary = clip(out.summary, 160);
+  if (bytesOf(out) > maxBytes) out.claims = out.claims.slice(0, 4);
+  return out;
+}
+
+/** The scoring.js shape for rankEvidence. */
+function toScoringShape(r) {
+  return {
+    id: r.id, title: r.title, company: r.company, summary: r.summary || "",
+    wordings: (r.wordings_json || []).map((w) => ({ text: w.text })),
+    tags: r.tags_json || [], skills: [], industries: [], strengthScore: r.strength_score || 0,
+  };
+}
+
+module.exports = { serializeRecord, toScoringShape, bytesOf, clip, DEFAULT_RECORD_BYTES };