@chatpanel/events 0.33.1 → 0.47.0

package/index.js

@@ -38,6 +38,32 @@ export { parseFlowchart, layoutFlowchart, renderFlowchartSvg } from './flowchart
 export { validateView, validateViewInvocation, viewResult } from './view.js';
 export { validateWidget, validateWidgetMessage, effectiveGrants, widgetIcon, WIDGET_SURFACES } from './widget.js';
 export { fuseRRF, planQueries, multiSearch } from './rrf.js';
+
+// The compounding layer — subjects a brief can accumulate about, and the deterministic
+// half of the maintenance pass (W0's read-only survey is `surveyCorpus`).
+export {
+  SUBJECT_KINDS, DEFAULT_THRESHOLD, MAX_SUBJECTS, MAX_SUBJECT_CHARS,
+  normalizeSubject, subjectKey, subjectTokens, isSubjectCandidate,
+  aliasMap, resolveSubjects, earnsBrief, rankSubjects,
+  REDACTION_TOKEN_TYPES, isRedactionToken, SELF_LABELS, isSelfLabel, stripQualifiers,
+  suggestMerges,
+} from './entity.js';
+export {
+  BRIEF_STATES, CLAIM_KINDS, MAX_CLAIMS, MAX_CLAIM_REFS, MAX_BRIEF_RECORDS, MAX_BRIEF_CHARS,
+  contentHash, briefId, briefToText, briefTerms, briefLinks, checkKnowledgeInvariants, parseBriefText,
+} from './knowledge.js';
+export { deriveBrief, deriveBriefs, driftedRefs } from './knowledge-derive.js';
+export {
+  SYNTHESIS_SCHEMA, synthesisPrompt, claimsFromSynthesis,
+  MAX_SYNTHESIS_CLAIMS, MAX_EXCERPTS, MAX_EXCERPT_CHARS,
+} from './synthesis.js';
+export { PROPOSAL_STATES, SUPERSEDE_OVERLAP, propose, accept, reject, diffProposal, converge, linkClaims } from './promotion.js';
+export {
+  normalizeRecord, normalizeRecords, wikilinksIn, redactedTokensIn, redactionCost,
+  wantedPages, orphanRecords,
+  duplicateTitles, vocabularyDrift, mentionsFrom, spanningQuestions,
+  surveyCorpus, thresholdSweep, formatSurvey, NEAR_TITLE_DISTANCE, SPAN_MIN_TERMS,
+} from './curate.js';
 export {
   PDF_MAX_CHARS, linesFromItems, orderLines, paragraphsFromLines,
   pageTextFromItems, looksScanned, buildPdfDocument,
@@ -130,3 +156,55 @@ export {
   titleFromParticipants, titleFromDate, deriveMeetingTitle, shouldAutoTitle, isBetterTitleSource,
   meetingTitlePrompt, parseTitleResponse,
 } from './titles.js';
+
+// The library — one record model (chat / note / meeting / brief) for every client, so
+// "what is the title of this meeting" has one answer rather than one per codebase.
+export {
+  RECORD_KINDS, MAX_TITLE_LEN, LibraryError,
+  parseRecordId, makeRecordId, isRecordId,
+  normalizeStoredRecord, isValidStoredRecord, toSearchRecord, searchTextFor, toIndexEntry,
+  deriveTitle, snippetOf, wordCount,
+} from './library.js';
+
+// Two-way sync, as a pure plan over two index lists. Shared because the tie-break must not
+// depend on which client is asking, or two clients flap forever.
+export {
+  CLOCK_TOLERANCE_MS, SyncError,
+  stampOf, decide, planSync, isSettled, forkConflict, advanceBases,
+} from './sync-plan.js';
+
+// The encrypted backup wire format — the corpus's only lossless channel between clients.
+export {
+  ENCRYPTED_TYPE, COMPRESSIONS, BackupError,
+  // Aliased: `vault.js` also exports KDF_ITERATIONS, and the two are genuinely different
+  // numbers (the vault derives at 310k, a backup at 250k). Shadowing one with the other
+  // would silently re-key every backup this package writes.
+  KDF_ITERATIONS as BACKUP_KDF_ITERATIONS,
+  encryptBackup, decryptBackup, isEncryptedBackup,
+  identityCodec, streamCodec, nodeCodec, bestCodec,
+  // `toB64`/`fromB64` are deliberately NOT re-exported: `vault.js` already owns those names
+  // here. They remain on the module for callers that import the file directly.
+} from './backup-envelope.js';
+
+// The command bar's grammar, so muscle memory transfers between surfaces.
+export {
+  OMNI_MODES, OMNI_GRAMMAR,
+  parseOmni, extractFilters, resolveSince, wantsModel, isActionable,
+} from './omni.js';
+
+// The palette as data, for clients that cannot import a stylesheet.
+export {
+  THEMES, LIGHT, DARK, PALETTES, SHAPE, TOKEN_NAMES, TOKEN_ROLES,
+  paletteFor, cssVarName, toCssVars, themeStylesheet, resolveTheme,
+} from './theme.js';
+
+// Plans, gates and the signed entitlement — one definition, every client. The public
+// verification key lives here so a rotation reaches all of them, instead of being a
+// hand-edit in each (which is what CLAUDE.md currently has to warn about).
+export {
+  PLANS, API_BASE, ENDPOINTS, ENTITLEMENT_PUBLIC_JWK, UPGRADE_URL,
+  FEATURE_TIER, PRO_FEATURES, TEAM_FEATURES, FREE_LIMITS,
+  RECHECK_INTERVAL_MS, EntitlementError,
+  checkoutUrl, planOf, planLabel, isPro, isTeam, can, tierFor, withinFreeLimit,
+  verifyEntitlement, licenseFromPayload, needsRecheck,
+} from './entitlement.js';

package/knowledge-derive.js

@@ -0,0 +1,267 @@
+// DERIVING briefs — the pass that turns a corpus into the derived layer.
+//
+// Separate from `knowledge.js` (the model) because the costs are not alike: reading a brief
+// needs its shape and its renderer; building one walks every record, resolves entities and
+// runs the deterministic maintenance passes. Only pages ever build. The MV3 service worker
+// only ever reads — it syncs stored briefs onward — so keeping this out of `knowledge.js`
+// keeps it off the worker's cold start entirely, rather than relying on nobody importing it.
+//
+// Everything here is class R: no model, no network, and `now` is injected rather than read,
+// so a rebuild is reproducible. That is what makes invariant I-K2 true — deriveBriefs() is
+// the ONLY way a brief is ever created, so throwing them all away can never lose anything.
+
+import { makeRef } from './ref.js';
+import {
+  DEFAULT_THRESHOLD, MAX_SUBJECTS, normalizeSubject, rankSubjects, resolveSubjects,
+} from './entity.js';
+import { mentionsFrom, normalizeRecords, wantedPages } from './curate.js';
+import { MAX_CLAIMS, MAX_CLAIM_REFS, MAX_BRIEF_RECORDS, briefId, contentHash } from './knowledge.js';
+
+/** Records are addressed `chat:x` / `meeting:y` / `note:z` — the ref kind is the prefix. */
+function refForRecord(rec) {
+  const [kind, ...rest] = String(rec.id).split(':');
+  const id = rest.join(':') || rec.id;
+  const known = kind === 'chat' || kind === 'meeting' || kind === 'note' || kind === 'page';
+  return makeRef({ kind: known ? kind : 'result', id: known ? id : rec.id, hash: contentHash(rec.text) });
+}
+
+function claim({ id, kind, text, refs, at = 0, confidence = 1 }) {
+  return {
+    id,
+    kind,
+    text,
+    // I-K1 lives here: a claim is CONSTRUCTED with its refs, and `checkKnowledgeInvariants`
+    // refuses one that arrives without them. There is no path that writes a claim first and
+    // attaches provenance later, because that path is how provenance goes missing.
+    refs: refs.slice(0, MAX_CLAIM_REFS),
+    firstSeen: at,
+    lastConfirmed: at,
+    confidence,
+    cls: 'R', // class R — derived, not written. W3's prose claims carry 'C'.
+  };
+}
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const isoDay = (ms) => (ms ? new Date(ms).toISOString().slice(0, 10) : '');
+
+// How many co-occurring subjects a `together` claim names. Past a handful it stops being a
+// statement and becomes a tag cloud.
+const TOGETHER_LIMIT = 5;
+
+/**
+ * Memories that are ABOUT this subject become its highest-confidence claims.
+ *
+ * This is how the existing memory layer folds in, and the direction matters. `identity` and
+ * `preference` memories are AMBIENT — they ride every turn already, and copying them onto a
+ * brief would say them twice. The other three kinds (`project`, `fact`, `reference`) are
+ * retrieved rather than ambient, and a retrieved durable statement about a subject is
+ * exactly what a claim is — except the user said it themselves, so it outranks anything
+ * derived from co-occurrence.
+ *
+ * The reverse never happens automatically: a brief must not write itself into memory. Memory
+ * is bounded because it is ambient; a corpus flowing into it would unbound the one thing in
+ * the product that is deliberately small.
+ */
+function statedClaims(subject, memories, seq) {
+  const out = [];
+  const names = [subject.canonical, ...subject.aliases].filter(Boolean);
+  for (const mem of memories) {
+    if (!mem?.text || !mem.id) continue;
+    if (mem.kind === 'identity' || mem.kind === 'preference') continue; // already ambient
+    const hay = normalizeSubject(mem.text);
+    // Whole-token containment, so "pricing" does not match "repricing" and a one-word
+    // subject cannot claim every memory that happens to contain it as a substring.
+    const hit = names.some((n) => n && (hay === n || hay.includes(` ${n} `) || hay.startsWith(`${n} `) || hay.endsWith(` ${n}`)));
+    if (!hit) continue;
+    out.push(claim({
+      id: `${seq()}`,
+      kind: 'stated',
+      text: mem.text,
+      refs: [makeRef({ kind: 'memory', id: mem.id, hash: contentHash(mem.text) })],
+      at: Number(mem.updatedAt || mem.createdAt) || 0,
+      confidence: Number(mem.confidence) || 1,
+    }));
+  }
+  return out;
+}
+
+/**
+ * One subject + the records that mention it → a brief.
+ *
+ * Every claim here is a restatement of something the corpus already holds, which is what
+ * makes the phase free and what makes I-K3's auto-promotion defensible: none of it is an
+ * opinion, so there is nothing for a reviewer to review.
+ */
+export function deriveBrief(subject, { records, byId, cooccurring = [], memories = [], wanted = null, now = 0 } = {}) {
+  const recs = [...(subject.records instanceof Set ? subject.records : subject.records || [])]
+    .map((id) => byId.get(id)).filter(Boolean)
+    .sort((a, b) => (a.date || 0) - (b.date || 0));
+  if (!recs.length && !wanted) return null;
+
+  let n = 0;
+  const seq = () => { n += 1; return `c${n}`; };
+  const claims = [];
+
+  if (recs.length) {
+    const byType = {};
+    for (const r of recs) byType[r.type] = (byType[r.type] || 0) + 1;
+    const parts = Object.entries(byType).sort((a, b) => b[1] - a[1]).map(([t, c]) => plural(c, t));
+    claims.push(claim({
+      id: seq(),
+      kind: 'presence',
+      text: `Appears in ${plural(recs.length, 'record')} — ${parts.join(', ')}.`,
+      // The most recent records, because that is what a reader checks first — and the
+      // newest is also the one most likely to still resolve.
+      refs: recs.slice(-MAX_CLAIM_REFS).reverse().map(refForRecord),
+      at: now,
+    }));
+
+    const first = recs.find((r) => r.date);
+    const last = [...recs].reverse().find((r) => r.date);
+    if (first && last && first !== last) {
+      claims.push(claim({
+        id: seq(),
+        kind: 'timeline',
+        text: `Runs from ${isoDay(first.date)} to ${isoDay(last.date)} — ${first.title || 'untitled'} → ${last.title || 'untitled'}.`,
+        refs: [refForRecord(first), refForRecord(last)],
+        at: now,
+      }));
+    }
+  }
+
+  if (cooccurring.length) {
+    claims.push(claim({
+      id: seq(),
+      kind: 'together',
+      text: `Usually alongside ${cooccurring.slice(0, TOGETHER_LIMIT).map((c) => c.name).join(', ')}.`,
+      refs: recs.slice(-MAX_CLAIM_REFS).map(refForRecord),
+      at: now,
+    }));
+  }
+
+  if (wanted) {
+    // A [[link]] that resolves to nothing is the corpus asking for a page: a human already
+    // decided the subject was worth naming. Saying so on the brief is more useful than
+    // hiding it, because it tells the reader the page is thin BECAUSE nobody wrote the
+    // source, not because the derivation failed.
+    claims.push(claim({
+      id: seq(),
+      kind: 'wanted',
+      text: `Linked from ${plural(wanted.recordCount, 'record')} but no record carries this title.`,
+      refs: recs.slice(0, MAX_CLAIM_REFS).map(refForRecord),
+      at: now,
+    }));
+  }
+
+  claims.push(...statedClaims(subject, memories, seq));
+
+  const capped = claims.slice(0, MAX_CLAIMS);
+  const dates = recs.map((r) => r.date || 0).filter(Boolean);
+  return {
+    id: briefId(subject.key),
+    key: subject.key,
+    kind: subject.kind,
+    subject: { name: subject.name, aliases: [...(subject.aliases || [])] },
+    // Class R may auto-promote (I-K3): nothing above is an opinion, so there is nothing a
+    // reviewer could accept or reject. W3's prose arrives as `proposed` beside it.
+    state: 'promoted',
+    cls: 'R',
+    claims: capped,
+    records: recs.slice(-MAX_BRIEF_RECORDS).map((r) => ({ id: r.id, type: r.type, title: r.title, date: r.date })),
+    stats: {
+      records: recs.length,
+      mentions: subject.mentions,
+      claims: capped.length,
+      first: dates.length ? Math.min(...dates) : 0,
+      last: dates.length ? Math.max(...dates) : 0,
+      wanted: !!wanted,
+    },
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+/**
+ * The whole corpus → the briefs it earns. This IS invariant I-K2: it is the only way a
+ * brief is ever created, so throwing them all away can never lose anything.
+ *
+ * `now` is injected rather than read, so a rebuild is reproducible and testable — the same
+ * rule loop.js and schedule.js follow.
+ */
+export function deriveBriefs(records = [], {
+  memories = [], merges = null, self = '', threshold = DEFAULT_THRESHOLD,
+  limit = MAX_SUBJECTS, now = 0,
+} = {}) {
+  const recs = normalizeRecords(records);
+  const byId = new Map(recs.map((r) => [r.id, r]));
+  const mentions = mentionsFrom(recs);
+  // `merges` and `self` are corrections the USER made, and they are applied here — as inputs
+  // to the pass, never as edits to its output. That is what keeps I-K2 true: a rebuild
+  // re-applies them, where a rebuild that erased them would teach the user not to bother.
+  const subjects = resolveSubjects(mentions, { merges, self });
+  const ranked = rankSubjects(subjects, { threshold, limit });
+
+  // Which subjects share records with which — the `together` claim, computed once for the
+  // whole corpus rather than per subject, so this stays linear in mentions rather than
+  // quadratic in subjects.
+  const perRecord = new Map();
+  for (const s of ranked) {
+    for (const id of s.records) {
+      if (!perRecord.has(id)) perRecord.set(id, []);
+      perRecord.get(id).push(s.key);
+    }
+  }
+  const pairs = new Map();
+  for (const keys of perRecord.values()) {
+    for (const a of keys) for (const b of keys) {
+      if (a === b) continue;
+      const m = pairs.get(a) || new Map();
+      m.set(b, (m.get(b) || 0) + 1);
+      pairs.set(a, m);
+    }
+  }
+  const byKey = new Map(ranked.map((s) => [s.key, s]));
+  const wantedByNorm = new Map(wantedPages(recs).map((w) => [w.norm, w]));
+
+  const out = [];
+  for (const s of ranked) {
+    const co = [...(pairs.get(s.key) || new Map()).entries()]
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      .map(([key, count]) => ({ key, count, name: byKey.get(key)?.name || key }))
+      .filter((c) => c.count > 1);
+    const brief = deriveBrief(s, {
+      byId,
+      cooccurring: co,
+      memories,
+      wanted: s.kind === 'title' ? wantedByNorm.get(s.canonical) || null : null,
+      now,
+    });
+    if (brief) out.push(brief);
+  }
+  return out;
+}
+
+/**
+ * Which refs no longer resolve to what they cited.
+ *
+ * This is where `ref.js`'s `drifted` finally earns its existence: a claim saying "cutover
+ * moved to Q4, see meeting m_8812" is worthless if m_8812 has since been edited into
+ * something else, and a maintenance pass that cannot tell is a maintenance pass that lies.
+ */
+export function driftedRefs(brief, records = []) {
+  const hashes = new Map();
+  for (const r of normalizeRecords(records)) {
+    const [kind, ...rest] = r.id.split(':');
+    hashes.set(`${kind}:${rest.join(':') || r.id}`, contentHash(r.text));
+  }
+  const out = [];
+  for (const c of brief?.claims || []) {
+    for (const ref of c.refs || []) {
+      if (ref.kind === 'memory') continue; // memories are not records; they drift by edit, not by hash
+      const now = hashes.get(`${ref.kind}:${ref.id}`);
+      if (now === undefined) out.push({ claim: c.id, ref, resolution: 'verified-but-unavailable' });
+      else if (now !== ref.hash) out.push({ claim: c.id, ref, resolution: 'drifted' });
+    }
+  }
+  return out;
+}

package/knowledge.js

@@ -0,0 +1,221 @@
+// BRIEFS — the derived layer. A statement about a SUBJECT that accumulates across records.
+//
+// Everything else ChatPanel stores is a record of an event: a chat happened, a call
+// happened, a human wrote a note. Nothing is a synthesis, so every answer is re-derived
+// from scratch, every session, forever — and a multi-agent run's findings die with the run.
+// A brief is the thing that compounds.
+//
+// FOUR INVARIANTS, and they are the whole defence (see docs/knowledge-compounding.md §5.1):
+//
+//   I-K1  Every claim cites raw. A claim with no ref is a BUG, not a weak claim — it is
+//         refused on write. Derived text can then always be checked against, or rebuilt
+//         from, the immutable records under it.
+//   I-K2  A brief is REBUILDABLE. Delete every brief and this module reconstructs them from
+//         the record store. That makes a brief a projection — the same guarantee replay()
+//         gives the event log — and it makes "rebuild all" a cache clear, not data loss.
+//   I-K3  Nothing self-promotes. `draft` is free; `promoted` needs a gate. Class-R
+//         derivations may auto-promote (a backlink is not an opinion); model-written prose
+//         may not. Unreviewed agent writing compounding into confident nonsense is the
+//         failure mode that is undetectable six months later.
+//   I-K4  Bounded, or it is a second corpus. A brief has a size ceiling and the SET of
+//         briefs has a count ceiling driven by evidence — memory.js already made this
+//         argument for memory, and the same sentence applies here.
+//
+// This phase (W1) is entirely class R: no model, no network, no clock of its own. Every
+// claim is something the corpus already states — who was present, when, what co-occurs,
+// what the user themselves told us. Prose synthesis arrives in W3, behind the gate, and
+// lands as `proposed` beside these rather than replacing them.
+//
+// WHY THIS FILE IS THE MODEL AND `knowledge-derive.js` IS THE PASS. Reading a brief and
+// BUILDING one have very different costs: reading needs the shape and the renderer, while
+// building walks the whole corpus and needs entity resolution and the maintenance passes.
+// The MV3 service worker only ever reads — it syncs stored briefs to the gateway — so
+// putting both halves in one module would have put 60 KB of derivation on its cold start
+// for code it never runs. The split is what keeps that honest rather than remembered.
+
+// From subject-name.js, not entity.js: this module is on the MV3 service worker's graph and
+// needs exactly one string function, where entity.js also carries alias resolution and merge
+// suggestion. Same argument as the knowledge/knowledge-derive split, one level down.
+import { normalizeSubject } from './subject-name.js';
+
+/** draft → proposed → promoted → archived. `promotion.js` (W3) owns the transitions. */
+export const BRIEF_STATES = Object.freeze(['draft', 'proposed', 'promoted', 'archived']);
+
+/** What a claim is derived FROM. Class R throughout this phase. */
+export const CLAIM_KINDS = Object.freeze(['presence', 'timeline', 'together', 'wanted', 'stated']);
+
+// I-K4, made concrete. A brief that grows without bound is a document, and a document
+// needs its own summary, and then nothing has been gained.
+export const MAX_CLAIMS = 12;
+export const MAX_CLAIM_REFS = 8;
+export const MAX_BRIEF_RECORDS = 200;
+export const MAX_BRIEF_CHARS = 4000;
+
+// How many co-occurring subjects a `together` claim names. Past a handful it stops being a
+// statement and becomes a tag cloud.
+const TOGETHER_LIMIT = 5;
+
+/**
+ * A stable, non-cryptographic content hash, computed SYNCHRONOUSLY.
+ *
+ * Deliberately not SHA-256, which `store.js` uses and which is async: derivation walks
+ * every record in the corpus and runs in an MV3 service worker, so a hash per record has to
+ * be synchronous or the whole pass becomes a promise storm. The job here is DRIFT
+ * DETECTION — "has the record this claim cites changed since the claim was made" — not
+ * tamper resistance, and FNV-1a answers that exactly as well while staying pure.
+ */
+export function contentHash(text) {
+  const s = String(text ?? '');
+  let h1 = 0x811c9dc5, h2 = 0x01000193;
+  for (let i = 0; i < s.length; i += 1) {
+    const c = s.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 0x01000193) >>> 0;
+    h2 = Math.imul(h2 ^ (c + i), 0x85ebca6b) >>> 0;
+  }
+  return `f${h1.toString(16).padStart(8, '0')}${h2.toString(16).padStart(8, '0')}`;
+}
+
+/** `person:alex rivera` → `brief:person-alex-rivera`. Safe as a storage key and a URL hash. */
+export function briefId(subjectKey) {
+  const [kind, ...rest] = String(subjectKey || '').split(':');
+  const slug = normalizeSubject(rest.join(':')).replace(/\s+/g, '-').replace(/-+/g, '-');
+  if (!kind || !slug) return '';
+  // The slug is TRUNCATED, so two long subjects can share one, and it is lossy, so two
+  // kinds can too. A hash of the CANONICAL key rides along to separate them. Canonical, not
+  // raw: "Alex Rivera" and "alex  rivera" are one subject and must land on one id, or a
+  // rebuild would fork the page in two — the exact failure I-K2 exists to make impossible.
+  const canonical = `${kind}:${normalizeSubject(rest.join(':'))}`;
+  return `brief:${kind}-${slug.slice(0, 48)}-${contentHash(canonical).slice(1, 7)}`;
+}
+
+/** Records are addressed `chat:x` / `meeting:y` / `note:z` — the ref kind is the prefix. */
+function refForRecord(rec) {
+  const [kind, ...rest] = String(rec.id).split(':');
+  const id = rest.join(':') || rec.id;
+  const known = kind === 'chat' || kind === 'meeting' || kind === 'note' || kind === 'page';
+  return makeRef({ kind: known ? kind : 'result', id: known ? id : rec.id, hash: contentHash(rec.text) });
+}
+
+function claim({ id, kind, text, refs, at = 0, confidence = 1 }) {
+  return {
+    id,
+    kind,
+    text,
+    // I-K1 lives here: a claim is CONSTRUCTED with its refs, and `checkKnowledgeInvariants`
+    // refuses one that arrives without them. There is no path that writes a claim first and
+    // attaches provenance later, because that path is how provenance goes missing.
+    refs: refs.slice(0, MAX_CLAIM_REFS),
+    firstSeen: at,
+    lastConfirmed: at,
+    confidence,
+    cls: 'R', // class R — derived, not written. W3's prose claims carry 'C'.
+  };
+}
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const isoDay = (ms) => (ms ? new Date(ms).toISOString().slice(0, 10) : '');
+
+/**
+ * The searchable body. A brief is a SOURCE, ranked by the same engine as everything else
+ * (design §7.6 — no second retrieval stack), so it has to render to text like one.
+ */
+export function briefToText(brief) {
+  if (!brief) return '';
+  const L = [`BRIEF: ${brief.subject.name}`];
+  if (brief.subject.aliases?.length) L.push(`Also known as: ${brief.subject.aliases.join(', ')}`);
+  L.push(`Kind: ${brief.kind}`);
+  L.push('');
+  for (const c of brief.claims) {
+    L.push(`- ${c.supersededBy ? '[superseded] ' : ''}${c.text}`);
+    if (c.refs.length) L.push(`  (${c.refs.map((r) => `${r.kind}:${r.id}`).join(', ')})`);
+  }
+  if (brief.records.length) {
+    L.push('', 'RECORDS:');
+    for (const r of brief.records.slice(-40).reverse()) L.push(`- ${r.type}: ${r.title || 'untitled'}`);
+  }
+  return L.join('\n').slice(0, MAX_BRIEF_CHARS);
+}
+
+/**
+ * The inverse of `briefToText` — a brief's claims and refs read back out of the text form.
+ *
+ * Exists because the warm store holds RECORDS: `{ id, title, type, date, text }`, nothing
+ * else. Briefs cross to the gateway as that shape, so an agent asking `get_brief` over MCP
+ * can only be handed structure if the text form is stable enough to parse. It is: this
+ * module writes both ends, and the claim line (`- text`) followed by its refs
+ * (`  (kind:id, kind:id)`) is a grammar, not a rendering. Round-trips in the tests.
+ *
+ * Returns `null` for text that is not a brief, so a caller can tell "not a brief" from
+ * "a brief with no claims".
+ */
+export function parseBriefText(text) {
+  const lines = String(text ?? '').split('\n');
+  if (!/^BRIEF: /.test(lines[0] || '')) return null;
+  const out = { name: lines[0].slice('BRIEF: '.length).trim(), aliases: [], kind: '', claims: [], records: [] };
+  let section = 'head';
+  for (let i = 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (section === 'head') {
+      if (line.startsWith('Also known as: ')) out.aliases = line.slice(15).split(',').map((a) => a.trim()).filter(Boolean);
+      else if (line.startsWith('Kind: ')) out.kind = line.slice(6).trim();
+      else if (line === '') section = 'claims';
+      continue;
+    }
+    if (line === 'RECORDS:') { section = 'records'; continue; }
+    if (section === 'claims' && line.startsWith('- ')) {
+      const claim = { text: line.slice(2), refs: [] };
+      const next = lines[i + 1] || '';
+      const m = /^  \((.*)\)$/.exec(next);
+      if (m) {
+        claim.refs = m[1].split(', ').map((r) => {
+          const idx = r.indexOf(':');
+          return idx > 0 ? { kind: r.slice(0, idx), id: r.slice(idx + 1) } : null;
+        }).filter(Boolean);
+        i += 1;
+      }
+      out.claims.push(claim);
+    } else if (section === 'records' && line.startsWith('- ')) {
+      const idx = line.indexOf(': ');
+      out.records.push(idx > 0 ? { type: line.slice(2, idx), title: line.slice(idx + 2) } : { type: '', title: line.slice(2) });
+    }
+  }
+  return out;
+}
+
+/** The other briefs this brief's accepted claims link to — the backlink graph's edges. */
+export function briefLinks(brief) {
+  const out = new Set();
+  for (const c of brief?.claims || []) for (const r of c.refs || []) if (r.kind === 'brief' && r.id) out.add(r.id);
+  return [...out];
+}
+
+/** Terms the graph and the search index rank a brief by — its subject and its neighbours. */
+export function briefTerms(brief) {
+  if (!brief) return [];
+  const together = brief.claims.find((c) => c.kind === 'together');
+  const names = together ? together.text.replace(/^Usually alongside /, '').replace(/\.$/, '').split(', ') : [];
+  return [...new Set([brief.subject.name, ...(brief.subject.aliases || []), ...names])].filter(Boolean);
+}
+
+/**
+ * The invariants, as a check rather than a promise. Returns the failures; empty means clean.
+ * Same shape as `invariants.js checkInvariants()`, for the same reason: an invariant nobody
+ * can run is a comment.
+ */
+export function checkKnowledgeInvariants(brief) {
+  const fail = [];
+  if (!brief || typeof brief !== 'object') return [{ invariant: 'I-K1', detail: 'not a brief' }];
+  if (!BRIEF_STATES.includes(brief.state)) fail.push({ invariant: 'I-K3', detail: `unknown state ${brief.state}` });
+  if (brief.state === 'promoted' && brief.cls === 'C') {
+    fail.push({ invariant: 'I-K3', detail: 'model-written prose cannot be promoted without the gate' });
+  }
+  for (const c of brief.claims || []) {
+    if (!c.refs?.length) fail.push({ invariant: 'I-K1', detail: `claim ${c.id} cites nothing` });
+    if (!CLAIM_KINDS.includes(c.kind) && c.cls !== 'C') {
+      fail.push({ invariant: 'I-K1', detail: `claim ${c.id} has unknown kind ${c.kind}` });
+    }
+  }
+  if ((brief.claims || []).length > MAX_CLAIMS) fail.push({ invariant: 'I-K4', detail: `${brief.claims.length} claims exceeds ${MAX_CLAIMS}` });
+  if (briefToText(brief).length >= MAX_BRIEF_CHARS) fail.push({ invariant: 'I-K4', detail: 'brief text is at the ceiling' });
+  return fail;
+}