heyspex 0.1.0 → 0.2.1

package/spexharness/src/doctrine/sources.mjs

@@ -0,0 +1,252 @@
+// spexharness/src/doctrine/sources.mjs
+//
+// DR1 (epic [[HS-KNHZ-8CMW-EPIC-spexcode-doctrine-v0-the-foundational]], task
+// [[HS-TWTC-8CMW-TASK-dr1-doctrine-corpus-reader-stream-every]]) — enumerates every
+// source the Doctrine corpus reader draws from, verified on this machine 2026-09-11:
+//
+//   - Claude Code sessions:  ~/.claude/projects/<project>/*.jsonl — SCOPED TO THIS REPO'S
+//     project directory by default since 2026-09-20 (see `claudeCodeProjectSlug`); other
+//     projects only on the explicit `allClaudeProjects` / `claudeProjects` opt-in.
+//   - Command Code sessions: ~/.commandcode/projects/<project>/<id>.jsonl — the
+//     sibling `<id>.checkpoints.jsonl` is a DIFFERENT, denser log of the same
+//     session (checkpoint snapshots) and is deliberately excluded: reading it too
+//     would double-count every Command Code session.
+//   - The Command Code taste profile(s): <repo>/.commandcode/taste/taste/taste.md
+//     (this repo, and the sibling spexvr checkout named in the task brief).
+//   - This harness's own session-end export: .heyspex/session-end-events.jsonl
+//     (written by scripts/claude-hooks/session-end.mjs's createLocalEventsExporter,
+//     itself a thin wrapper over session-record.mjs's appendSessionRecord).
+//
+// Pure enumeration: fs.readdirSync + fs.statSync only, never a file read — corpus.mjs
+// does the streaming content read. Every root is injectable so a test never touches
+// the real machine's ~/.claude or ~/.commandcode directories.
+
+import { readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+
+/** Default Claude Code projects root. */
+export function defaultClaudeProjectsDir() {
+  return join(homedir(), '.claude', 'projects');
+}
+
+/**
+ * The Claude Code project-directory name for a working directory. Claude Code names each
+ * subdirectory of `~/.claude/projects/` after the session's cwd with every non-alphanumeric
+ * character replaced by `-` (verified on this machine 2026-09-20: `C:\dev-projects\heyspex-app`
+ * → `C--dev-projects-heyspex-app`).
+ *
+ * This exists because the corpus reader is SCOPED TO THIS REPO by default. Harvesting every
+ * project under `~/.claude/projects/` mixed five other checkouts — and a `C:\Users\...\Temp`
+ * scratch directory used by a sidecar SDK prompt — into a Doctrine document that is COMMITTED
+ * TO GIT, so one machine's unrelated work shipped to every clone. Only 33% of the 5,328-row
+ * corpus measured on 2026-09-20 came from this repo.
+ *
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+export function claudeCodeProjectSlug(repoRoot) {
+  return String(repoRoot ?? '').replace(/[^A-Za-z0-9]/g, '-');
+}
+
+/** Default Command Code projects root. */
+export function defaultCommandCodeProjectsDir() {
+  return join(homedir(), '.commandcode', 'projects');
+}
+
+/**
+ * Default taste.md candidates — this repo's own compiled profile plus the sibling
+ * spexvr checkout named in the task brief. A path that does not exist is silently
+ * skipped by {@link enumerateTasteSources}, so listing a candidate that is absent on
+ * a given machine is harmless.
+ */
+export function defaultTasteFiles(repoRoot) {
+  return [
+    join(repoRoot, '.commandcode', 'taste', 'taste', 'taste.md'),
+    join(repoRoot, '..', 'spexvr', '.commandcode', 'taste', 'taste', 'taste.md'),
+  ];
+}
+
+/**
+ * Default harness session-end export path — see scripts/claude-hooks/session-end.mjs
+ * `sessionEventsExportPath`. This module does not import that script (it lives in
+ * scripts/, this module in spexharness/) so the default is re-derived here; the two
+ * must stay in step (both are `<root>/.heyspex/session-end-events.jsonl`).
+ */
+export function defaultSpexcodeEventsPath(repoRoot) {
+  return join(repoRoot, '.heyspex', 'session-end-events.jsonl');
+}
+
+function safeReaddir(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+function safeStat(path) {
+  try {
+    return statSync(path);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Enumerate every Claude Code session file under `dir` (one subdirectory per project).
+ *
+ * `projects` restricts the walk to the named project directories. Omitted (or `null`) it
+ * walks every subdirectory — the historical behaviour, kept so a caller that has already
+ * decided which roots to read (and every existing test) is unaffected. {@link enumerateSources}
+ * is where the SCOPED-TO-THIS-REPO default lives.
+ *
+ * @param {string} dir
+ * @param {{ projects?: string[]|null }} [opts]
+ * @returns {Array<{ source: 'claude-code', project: string, session: string, path: string, mtime: number }>}
+ */
+export function enumerateClaudeCodeSources(dir, { projects = null } = {}) {
+  const out = [];
+  const allow = Array.isArray(projects) ? new Set(projects) : null;
+  for (const projectEnt of safeReaddir(dir)) {
+    if (!projectEnt.isDirectory()) continue;
+    const project = projectEnt.name;
+    if (allow && !allow.has(project)) continue;
+    const projectDir = join(dir, project);
+    for (const fileEnt of safeReaddir(projectDir)) {
+      if (!fileEnt.isFile() || !fileEnt.name.endsWith('.jsonl')) continue;
+      const filePath = join(projectDir, fileEnt.name);
+      const stat = safeStat(filePath);
+      if (!stat) continue;
+      out.push({
+        source: 'claude-code',
+        project,
+        session: fileEnt.name.replace(/\.jsonl$/, ''),
+        path: filePath,
+        mtime: stat.mtimeMs,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Enumerate every Command Code session file under `dir`, excluding the
+ * `.checkpoints.jsonl` sidecar (see module header).
+ * @param {string} dir
+ * @returns {Array<{ source: 'command-code', project: string, session: string, path: string, mtime: number }>}
+ */
+export function enumerateCommandCodeSources(dir) {
+  const out = [];
+  for (const projectEnt of safeReaddir(dir)) {
+    if (!projectEnt.isDirectory()) continue;
+    const project = projectEnt.name;
+    const projectDir = join(dir, project);
+    for (const fileEnt of safeReaddir(projectDir)) {
+      if (!fileEnt.isFile()) continue;
+      if (!fileEnt.name.endsWith('.jsonl') || fileEnt.name.endsWith('.checkpoints.jsonl')) continue;
+      const filePath = join(projectDir, fileEnt.name);
+      const stat = safeStat(filePath);
+      if (!stat) continue;
+      out.push({
+        source: 'command-code',
+        project,
+        session: fileEnt.name.replace(/\.jsonl$/, ''),
+        path: filePath,
+        mtime: stat.mtimeMs,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Enumerate taste-profile sources — each existing file in `files` yields one source.
+ * `project` is read off the path itself (the directory just above `.commandcode`),
+ * falling back to `'unknown'` for a path shaped unlike the documented layout.
+ * @param {string[]} files
+ * @returns {Array<{ source: 'taste', project: string, session: 'taste', path: string, mtime: number }>}
+ */
+export function enumerateTasteSources(files) {
+  const out = [];
+  for (const filePath of files) {
+    const stat = safeStat(filePath);
+    if (!stat || !stat.isFile()) continue;
+    // .../<repo>/.commandcode/taste/taste/taste.md — the repo name sits one segment
+    // above `.commandcode`.
+    const parts = filePath.split(/[\\/]/);
+    const idx = parts.lastIndexOf('.commandcode');
+    const project = idx > 0 ? parts[idx - 1] : 'unknown';
+    out.push({ source: 'taste', project, session: 'taste', path: filePath, mtime: stat.mtimeMs });
+  }
+  return out;
+}
+
+/**
+ * Enumerate the harness's own session-end export, when present. Zero entries until a
+ * SessionEnd hook has actually appended to it on this machine — that file carries no
+ * `ask` text today (only events + tool-call log; see corpus.mjs's handler for the
+ * documented, forward-compatible handling of that shape).
+ * @param {string} filePath
+ * @param {{ project?: string }} [opts]
+ * @returns {Array<{ source: 'spexcode', project: string, session: string, path: string, mtime: number }>}
+ */
+export function enumerateSpexcodeSources(filePath, { project = 'heyspex-app' } = {}) {
+  const stat = safeStat(filePath);
+  if (!stat || !stat.isFile()) return [];
+  return [
+    {
+      source: 'spexcode',
+      project,
+      session: basename(filePath).replace(/\.jsonl$/, ''),
+      path: filePath,
+      mtime: stat.mtimeMs,
+    },
+  ];
+}
+
+/**
+ * Enumerate every source the Doctrine corpus reader draws from. Every root is
+ * injectable (tests pass fixture dirs); omitted, each defaults to the real machine
+ * path / repo-relative path documented above.
+ *
+ * ── Claude Code scope (2026-09-20) ──────────────────────────────────────────────
+ * Claude Code sessions default to THIS REPO'S project directory only
+ * ({@link claudeCodeProjectSlug}). Other projects are opt-in and never implicit:
+ *   - `allClaudeProjects: true` — every project directory under the root (the old behaviour).
+ *   - `claudeProjects: ['C--dev-projects-spexvr', ...]` — an explicit list.
+ * `allClaudeProjects` wins over `claudeProjects` when both are given.
+ *
+ * @param {{
+ *   claudeProjectsDir?: string,
+ *   claudeProjects?: string[]|null,
+ *   allClaudeProjects?: boolean,
+ *   commandCodeProjectsDir?: string,
+ *   tasteFiles?: string[],
+ *   spexcodeEventsPath?: string,
+ *   repoRoot?: string,
+ * }} [opts]
+ * @returns {Array<{ source: string, project: string, session: string, path: string, mtime: number }>}
+ */
+export function enumerateSources(opts = {}) {
+  const repoRoot = opts.repoRoot ?? process.cwd();
+  const claudeProjectsDir = opts.claudeProjectsDir ?? defaultClaudeProjectsDir();
+  const commandCodeProjectsDir = opts.commandCodeProjectsDir ?? defaultCommandCodeProjectsDir();
+  const tasteFiles = opts.tasteFiles ?? defaultTasteFiles(repoRoot);
+  const spexcodeEventsPath = opts.spexcodeEventsPath ?? defaultSpexcodeEventsPath(repoRoot);
+  const claudeProjects = opts.allClaudeProjects
+    ? null
+    : (opts.claudeProjects ?? [claudeCodeProjectSlug(repoRoot)]);
+
+  return [
+    ...enumerateClaudeCodeSources(claudeProjectsDir, { projects: claudeProjects }),
+    ...enumerateCommandCodeSources(commandCodeProjectsDir),
+    ...enumerateTasteSources(tasteFiles),
+    ...enumerateSpexcodeSources(spexcodeEventsPath, { project: basename(repoRoot) }),
+  ];
+}
+
+/** Stable per-session key used by corpus.mjs's incremental state. */
+export function sourceKey(src) {
+  return `${src.source}:${src.project}:${src.session}`;
+}

package/spexharness/src/doctrine/synthesize.mjs

@@ -0,0 +1,401 @@
+// spexharness/src/doctrine/synthesize.mjs
+//
+// DR2 (epic [[HS-KNHZ-8CMW-EPIC-spexcode-doctrine-v0-the-foundational]], task
+// [[HS-YMPY-8CMW-TASK-dr2-doctrine-synthesis-a-routed]]) — batches the observation
+// stream corpus.mjs produced and asks the `research_synthesis` seat (DeepSeek V4
+// Flash, per dev-factory/routing-table.json `purposes.research_synthesis` /
+// `lockedPrimaries.research_synthesis`) for candidate Doctrine principles.
+//
+// Routing (owner ruling [[owner-ruling-a-routed-model-seat]]): every model call goes
+// through spexharness/src/loop.mjs `runToolLoop` — NEVER a bare `callModel` — even
+// though this seat needs no tools; that keeps the harness's gates, redaction and
+// error-recycling on the call path. No tools are offered (`tools` is omitted), so
+// `runToolLoop`'s `withTools` is false and the loop resolves on the model's own first
+// reply, gated by `hooks.onFinal` for the STRICT-JSON contract:
+//   { "principles": [ { "text", "category", "confidence" (0-1), "evidence": [id,...], "stance" } ] }
+// A reply that is not valid JSON, or that cites an evidence id NOT in the batch it was
+// given, is REJECTED and the seat is asked to retry — once (`maxFinalRetries: 1`,
+// runToolLoop's own Stop-hook-shaped refusal/retry path).
+//
+// Cost is recorded through the existing cost meter (spexharness/src/chat/cost-meter.mjs)
+// when a caller supplies one, one row per model call (one per batch, or two on a retry) —
+// the SAME ledger `dev-factory/cost-tracker.mjs` and the chat margin already read.
+//
+// DR5 ([[HS-7Z9E-8CMW-TASK-dr5-vault-knowledge-as-a-doctrine]]): vault-source.mjs's
+// `source: 'vault'` observations are ALREADY rules (curated by the owner) and are
+// NEVER sent to this seat — {@link batchObservations}/{@link synthesizeDoctrine} drop
+// them before batching, as a hard invariant independent of what a caller passes in.
+// They are instead seeded straight into principles by merge.mjs's
+// `seedVaultRulesAsPrinciples`. This module's only awareness of them is contextual: a
+// caller may pass `vaultContextLines` (see {@link buildVaultRuleContextLines}) — a
+// short "here is what's already established" list folded into the system prompt so a
+// session-derived principle is phrased consistently with the vault and not restated
+// as if it were new.
+
+import { PROVIDERS, callModel } from '../../../dev-factory/cloud-clients.mjs';
+import { DEEPSEEK } from '../../../dev-factory/lib/model-catalog.mjs';
+import { runToolLoop } from '../loop.mjs';
+
+/**
+ * @typedef {{
+ *   text: string,
+ *   category: string,
+ *   confidence: number,
+ *   evidence: string[],
+ *   stance: 'do'|'avoid',
+ *   supersedes?: string[],
+ * }} DoctrinePrincipleCandidate
+ */
+
+/** The `research_synthesis` seat's locked primary (dev-factory/routing-table.json). */
+export const SYNTHESIS_MODEL = DEEPSEEK.FLASH;
+
+/** Categories a candidate principle may be filed under (epic scope). */
+export const CATEGORIES = [
+  'delegation',
+  'verification',
+  'communication',
+  'naming',
+  'safety-permissions',
+  'research-grounding',
+  'session-hygiene',
+  'product-taste',
+];
+
+/**
+ * The ESCAPE VALVE. Without it the seat had to file every observation under one of
+ * {@link CATEGORIES} — there was no way to say "this yields no principle" — so off-topic input
+ * (a bug report, a paste, a machine blob) was laundered into a confident-looking principle
+ * rather than declined. A principle carrying this sentinel category is parsed successfully
+ * and then DROPPED: it never reaches merge.mjs, the writer, or the committed document.
+ *
+ * It is deliberately NOT a member of `CATEGORIES`, so nothing downstream has to learn about
+ * it and `parseSynthesisReply` still rejects a genuinely unknown category.
+ */
+export const NO_PRINCIPLE_CATEGORY = 'none';
+
+// Approximation stated in the task brief: observations ≈ 4 chars/token.
+const CHARS_PER_TOKEN = 4;
+const TARGET_BATCH_TOKENS = 40_000;
+
+/** The row shape a batch sends the seat — the ONLY fields it ever sees per observation. */
+function batchRow(obs) {
+  return { id: obs.id, kind: obs.kind, project: obs.project, date: obs.ts, text: obs.text };
+}
+
+function approxChars(obs) {
+  return JSON.stringify(batchRow(obs)).length;
+}
+
+/**
+ * Estimate the token count of a set of observations (≈ 4 chars/token, per the batch
+ * row shape actually sent to the seat) — call BEFORE synthesizing so the real-run cost
+ * can be printed ahead of any dispatch.
+ * @param {Array<object>} observations
+ * @returns {number}
+ */
+export function estimateTokens(observations) {
+  const eligible = (observations ?? []).filter((o) => o?.source !== 'vault');
+  const chars = eligible.reduce((sum, obs) => sum + approxChars(obs), 0);
+  return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+
+/**
+ * Estimate the $ cost of synthesizing `observations` at `model`'s DeepSeek pricing —
+ * input tokens from the batch content, output tokens estimated generously (principles
+ * are short JSON; ~15% of input is a safe ceiling for a well-bounded batch).
+ * @param {Array<object>} observations
+ * @param {string} [model]
+ * @returns {{ estimatedInputTokens: number, estimatedOutputTokens: number, estimatedCostUSD: number }}
+ */
+export function estimateSynthesisCostUSD(observations, model = SYNTHESIS_MODEL) {
+  const p = PROVIDERS[model];
+  const estimatedInputTokens = estimateTokens(observations);
+  const estimatedOutputTokens = Math.ceil(estimatedInputTokens * 0.15);
+  const estimatedCostUSD = p
+    ? +(((estimatedInputTokens * p.priceIn) + (estimatedOutputTokens * p.priceOut)) / 1e6).toFixed(6)
+    : 0;
+  return { estimatedInputTokens, estimatedOutputTokens, estimatedCostUSD };
+}
+
+/**
+ * Batch observations into ~40k-token groups: grouped by project, oldest-first within
+ * a project ("newest-last" per the task brief), a batch closed once adding the next
+ * observation would exceed `targetTokens`.
+ *
+ * Project order defaults to alphabetical (deterministic). A caller running against a
+ * spend cap that cannot fit the whole corpus may pass `projectOrder` — an explicit
+ * priority list (e.g. `['heyspex-app', ...otherProjectsNewestFirst]`) — so the
+ * highest-priority projects land in the EARLIEST batches, and a `maxBatches` cutoff
+ * then naturally keeps the highest-priority material and drops the rest.
+ *
+ * @param {Array<object>} observations
+ * @param {{ targetTokens?: number, projectOrder?: string[] }} [opts]
+ * @returns {Array<Array<object>>}
+ */
+export function batchObservations(observations, { targetTokens = TARGET_BATCH_TOKENS, projectOrder = null } = {}) {
+  const targetChars = targetTokens * CHARS_PER_TOKEN;
+  const eligible = (observations ?? []).filter((o) => o?.source !== 'vault');
+  const byProject = new Map();
+  for (const obs of eligible) {
+    const list = byProject.get(obs.project) ?? [];
+    list.push(obs);
+    byProject.set(obs.project, list);
+  }
+
+  const priorityIndex = new Map((projectOrder ?? []).map((p, i) => [p, i]));
+  const projects = [...byProject.keys()].sort((a, b) => {
+    const ia = priorityIndex.has(a) ? priorityIndex.get(a) : Number.POSITIVE_INFINITY;
+    const ib = priorityIndex.has(b) ? priorityIndex.get(b) : Number.POSITIVE_INFINITY;
+    if (ia !== ib) return ia - ib;
+    return a.localeCompare(b);
+  });
+
+  const ordered = [];
+  for (const project of projects) {
+    const list = byProject.get(project);
+    list.sort((a, b) => String(a.ts ?? '').localeCompare(String(b.ts ?? '')) || (a.seq ?? 0) - (b.seq ?? 0));
+    ordered.push(...list);
+  }
+
+  const batches = [];
+  let current = [];
+  let currentChars = 0;
+  for (const obs of ordered) {
+    const chars = approxChars(obs);
+    if (current.length && currentChars + chars > targetChars) {
+      batches.push(current);
+      current = [];
+      currentChars = 0;
+    }
+    current.push(obs);
+    currentChars += chars;
+  }
+  if (current.length) batches.push(current);
+  return batches;
+}
+
+/**
+ * The top vault-rule principle texts per category, for prompt context — see the module
+ * header. Accepts merge.mjs's `seedVaultRulesAsPrinciples` output shape
+ * (`{ text, category, confidence }`); sorts each category's candidates by confidence
+ * descending and keeps the top `perCategory`. Pure, deterministic.
+ *
+ * @param {Array<{ text: string, category: string, confidence: number }>} vaultPrinciples
+ * @param {{ perCategory?: number }} [opts]
+ * @returns {string[]} lines shaped `[category] text`
+ */
+export function buildVaultRuleContextLines(vaultPrinciples, { perCategory = 3 } = {}) {
+  const byCategory = new Map();
+  for (const p of vaultPrinciples ?? []) {
+    if (!p || typeof p.text !== 'string' || !p.text.trim()) continue;
+    const list = byCategory.get(p.category) ?? [];
+    list.push(p);
+    byCategory.set(p.category, list);
+  }
+  const lines = [];
+  for (const [category, list] of byCategory) {
+    const top = [...list].sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0)).slice(0, perCategory);
+    for (const p of top) lines.push(`[${category}] ${p.text}`);
+  }
+  return lines;
+}
+
+/** The system prompt every synthesis call sends — states the Doctrine's purpose and the hard rules. */
+export function buildSynthesisSystemPrompt({ vaultContextLines = [] } = {}) {
+  const base = [
+    'You distill SpexCode Doctrine: the base operating principles every developer profile is built on,',
+    'learned from how the owner directs coding agents across many real sessions.',
+    '',
+    'You will receive one batch of observations, each shaped { id, kind, project, date, text }.',
+    'Most observations (kind instruction/correction/ruling/approval/refusal/taste) are the owner\'s own',
+    'words. Some observations have kind "behaviour" — a compact, aggregated summary of how a real',
+    'session actually ran (tools called, guardrail refusals/blocks, claims and specs advanced), built',
+    'from HeySpex\'s own logs, not something the owner said. Treat "behaviour" observations as lower-',
+    'weight supporting evidence for verification/safety-permissions/session-hygiene principles — useful',
+    'to corroborate a pattern, never sufficient on their own to justify a high-confidence principle.',
+    'Reply with STRICT JSON ONLY — no prose, no markdown code fences — matching exactly this shape:',
+    '{ "principles": [ { "text": string, "category": one of ' +
+      JSON.stringify(CATEGORIES) +
+      ', "confidence": number between 0 and 1, "evidence": [observation id, ...], "stance": "do" | "avoid" } ] }',
+    '',
+    'Rules:',
+    '- Prefer a rule that recurs across multiple sessions/observations over a one-off remark.',
+    '- Never quote more than 12 words verbatim from any single observation.',
+    '- Every id in "evidence" MUST be one of the ids given in THIS batch — never invent an id, and never cite one not present here.',
+    '- Never invent a principle or evidence unsupported by this batch.',
+    '- NOT EVERY OBSERVATION YIELDS A PRINCIPLE. An observation that is off-topic, is a one-off',
+    '  bug report, is pasted material, or is not the owner expressing a working preference must',
+    '  NOT be forced into a category. Decline it: either leave it out entirely, or emit an entry',
+    '  with "category": ' + JSON.stringify(NO_PRINCIPLE_CATEGORY) + ' citing it in "evidence". A declined entry is discarded.',
+    '- Returning { "principles": [] } for a batch that yields nothing is a CORRECT answer, not a failure.',
+  ];
+
+  if (vaultContextLines.length) {
+    base.push(
+      '',
+      "These rules are ALREADY established from the owner's own curated vault (decisions, protocols, north star, CLAUDE.md) —",
+      'phrase any new principle consistently with these, and do NOT re-emit one of them as if it were a new principle:',
+      ...vaultContextLines.map((l) => `- ${l}`),
+    );
+  }
+
+  return base.join('\n');
+}
+
+function buildBatchUserMessage(batch) {
+  const rows = batch.map(batchRow);
+  return `Observations batch (${rows.length} items):\n${JSON.stringify(rows)}\n\nReturn ONLY the strict JSON object described in the system prompt — no other text.`;
+}
+
+function stripCodeFence(text) {
+  const trimmed = String(text ?? '').trim();
+  const fence = /^```(?:json)?\s*([\s\S]*?)\s*```$/i.exec(trimmed);
+  return fence ? fence[1].trim() : trimmed;
+}
+
+/**
+ * Validate + parse one seat reply against the strict-JSON contract for `batch`. Never
+ * throws — returns `{ error }` for anything not conforming, so the caller can decide
+ * to reject-and-retry.
+ *
+ * An entry whose category is {@link NO_PRINCIPLE_CATEGORY} is the seat DECLINING the
+ * observations it cites (see the constant's note). It is validated only as far as its
+ * evidence ids — no text, confidence or stance is demanded for something being thrown away —
+ * and is returned separately on `declined`, never on `principles`.
+ *
+ * @param {string} text
+ * @param {string[]} validIds
+ * @returns {{ principles: DoctrinePrincipleCandidate[], declined: string[] } | { error: string }}
+ */
+export function parseSynthesisReply(text, validIds) {
+  let parsed;
+  try {
+    parsed = JSON.parse(stripCodeFence(text));
+  } catch {
+    return { error: 'reply is not valid JSON' };
+  }
+  if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.principles)) {
+    return { error: 'reply is missing a "principles" array' };
+  }
+  const idSet = new Set(validIds);
+  const principles = [];
+  const declined = [];
+  for (const p of parsed.principles) {
+    if (!p || typeof p !== 'object') return { error: 'a principle entry is not an object' };
+    if (p.category === NO_PRINCIPLE_CATEGORY) {
+      for (const id of Array.isArray(p.evidence) ? p.evidence : []) {
+        if (!idSet.has(id)) return { error: `principle cites an evidence id not in this batch: "${id}"` };
+        declined.push(id);
+      }
+      continue;
+    }
+    if (typeof p.text !== 'string' || !p.text.trim()) return { error: 'a principle is missing "text"' };
+    if (!CATEGORIES.includes(p.category)) return { error: `principle has an unknown category "${p.category}"` };
+    if (typeof p.confidence !== 'number' || Number.isNaN(p.confidence) || p.confidence < 0 || p.confidence > 1) {
+      return { error: 'a principle has a "confidence" outside 0..1' };
+    }
+    if (!Array.isArray(p.evidence) || p.evidence.length === 0) return { error: 'a principle is missing "evidence"' };
+    for (const id of p.evidence) {
+      if (!idSet.has(id)) return { error: `principle cites an evidence id not in this batch: "${id}"` };
+    }
+    if (p.stance !== 'do' && p.stance !== 'avoid') return { error: 'a principle has a "stance" other than do/avoid' };
+    principles.push(p);
+  }
+  return { principles, declined };
+}
+
+/**
+ * Synthesize ONE batch through the routed seat. Always goes through `runToolLoop` —
+ * never a bare `callModelFn` — per [[owner-ruling-a-routed-model-seat]]; no tools are
+ * offered. A reply that fails {@link parseSynthesisReply} is rejected via
+ * `hooks.onFinal` and retried once (`maxFinalRetries`).
+ *
+ * @param {Array<object>} batch
+ * @param {{ model?: string, callModelFn?: Function, maxFinalRetries?: number, costMeter?: { recordTurn: Function } | null, vaultContextLines?: string[] }} [opts]
+ * @returns {Promise<{ principles: DoctrinePrincipleCandidate[], costUSD: number, error: string|null }>}
+ */
+export async function synthesizeBatch(batch, { model = SYNTHESIS_MODEL, callModelFn = callModel, maxFinalRetries = 1, costMeter = null, vaultContextLines = [] } = {}) {
+  const validIds = batch.map((o) => o.id);
+  const system = buildSynthesisSystemPrompt({ vaultContextLines });
+  const messages = [{ role: 'user', content: buildBatchUserMessage(batch) }];
+
+  let lastParsed = null;
+  const result = await runToolLoop({
+    callModelFn,
+    model,
+    messages,
+    execute: async () => ({ content: JSON.stringify({ error: 'the doctrine synthesis seat has no tools available' }) }),
+    maxToolTurns: 1,
+    callOpts: { system, maxTokens: 8192, temp: 0 },
+    maxFinalRetries,
+    onTurn: costMeter
+      ? ({ res }) => {
+          if (res && !res.error) costMeter.recordTurn({ model: res.model ?? model, usage: res.usage, costUSD: res.costUSD, seconds: res.seconds });
+        }
+      : null,
+    hooks: {
+      onFinal: async (text) => {
+        const parsed = parseSynthesisReply(text, validIds);
+        lastParsed = parsed;
+        if (parsed.error) {
+          return {
+            accept: false,
+            feedback: `Your reply was rejected: ${parsed.error}. Reply again with ONLY the strict JSON object described in the system prompt, citing only ids present in this batch.`,
+          };
+        }
+        return { accept: true };
+      },
+    },
+  });
+
+  if (!result.ok || !lastParsed || lastParsed.error) {
+    return { principles: [], declined: [], costUSD: result.costUSD ?? 0, error: lastParsed?.error ?? result.error ?? 'synthesis failed with no reply' };
+  }
+  return { principles: lastParsed.principles, declined: lastParsed.declined ?? [], costUSD: result.costUSD ?? 0, error: null };
+}
+
+/**
+ * Synthesize the whole observation set: batch it, run each batch (up to `maxBatches`)
+ * through {@link synthesizeBatch}, and total the cost. Batches beyond `maxBatches` are
+ * left unrun (`batchesSkipped`) rather than silently dropped from the count — a caller
+ * prioritizing which observations to include should slice `observations` BEFORE
+ * calling this, so the skipped batches are the ones that mattered least.
+ *
+ * @param {Array<object>} observations
+ * @param {{ model?: string, callModelFn?: Function, maxBatches?: number, costMeter?: object|null, onBatch?: Function|null, projectOrder?: string[], vaultContextLines?: string[] }} [opts]
+ * @returns {Promise<{ principles: DoctrinePrincipleCandidate[], batchesRun: number, batchesTotal: number, batchesSkipped: number, costUSD: number, results: Array<{ batchIndex: number, size: number, principlesReturned: number, error: string|null, costUSD: number }> }>}
+ */
+export async function synthesizeDoctrine(observations, { model = SYNTHESIS_MODEL, callModelFn = callModel, maxBatches = Infinity, costMeter = null, onBatch = null, projectOrder = null, vaultContextLines = [] } = {}) {
+  // Vault observations are never sent to the seat (see module header) — batchObservations
+  // already drops them, this filter is belt-and-suspenders for anything that inspects
+  // `observations` directly before batching.
+  const batches = batchObservations(observations, { projectOrder });
+  const limit = Number.isFinite(maxBatches) ? Math.max(0, maxBatches) : batches.length;
+  const toRun = batches.slice(0, limit);
+
+  const allPrinciples = [];
+  const allDeclined = [];
+  const results = [];
+  let costUSD = 0;
+
+  for (let i = 0; i < toRun.length; i++) {
+    const batch = toRun[i];
+    const r = await synthesizeBatch(batch, { model, callModelFn, costMeter, vaultContextLines });
+    costUSD += r.costUSD;
+    results.push({ batchIndex: i, size: batch.length, principlesReturned: r.principles.length, declinedCount: (r.declined ?? []).length, error: r.error, costUSD: r.costUSD });
+    allPrinciples.push(...r.principles);
+    allDeclined.push(...(r.declined ?? []));
+    if (onBatch) onBatch({ index: i, of: toRun.length, batch, result: r });
+  }
+
+  return {
+    principles: allPrinciples,
+    declined: allDeclined,
+    batchesRun: toRun.length,
+    batchesTotal: batches.length,
+    batchesSkipped: batches.length - toRun.length,
+    costUSD,
+    results,
+  };
+}