@chatpanel/events 0.33.0 → 0.46.0

package/promotion.js

@@ -0,0 +1,171 @@
+// PROMOTION — the gate between "a model wrote this" and "the brief says this".
+//
+// The single most repeated finding in the community threads was that unreviewed agent
+// writing compounds into confident nonsense (C2), and the convergent answer was to separate
+// CAPTURE from PROMOTION: agents draft freely, promotion needs review. This module is that
+// separation as code. Class-R claims never pass through it — a backlink is not an opinion —
+// and class-C claims never get around it.
+//
+//   proposed  →  promoted   only via accept()
+//   proposed  →  rejected   via reject()
+//
+// A proposal is its own object rather than a mutation of the brief, so the queue survives a
+// rebuild (I-K2 throws briefs away; it must not throw away the user's pending decisions),
+// and so accepting shows a DIFF against what the brief said before rather than a fait
+// accompli.
+//
+// `converge()` is W7's rule written before W7 exists: N independent drafts agree on a claim
+// ⇒ it may be auto-proposed; disagreement ⇒ the human queue. The reviewer is a different
+// appointment from the drafters or convergence measures nothing.
+
+import { contentHash } from './knowledge.js';
+import { normalizeSubject } from './subject-name.js';
+
+export const PROPOSAL_STATES = Object.freeze(['proposed', 'accepted', 'rejected']);
+
+/** A new claim replaces an old one when this much of its vocabulary overlaps. */
+export const SUPERSEDE_OVERLAP = 0.5;
+
+/**
+ * BACKLINKS — the deterministic post-pass that turns cited prose into a linked wiki.
+ *
+ * A synthesised claim cites RECORDS, never another brief, so an accepted "Jordan Blake owns
+ * the Atlas rollback plan" told a reader nothing about where Jordan's page was. This finds
+ * every other subject named in a claim's text — whole-word, by canonical name or alias — and
+ * adds a `brief:` ref beside the record refs. No model: the names are known and the text is
+ * in front of us, which is exactly the kind of work the design says must stay class R.
+ *
+ * `subjects` is the brief index: `[{ id, name, aliases?, kind? }]`. The claim's own brief is
+ * never linked to itself. Refs already present are kept and not duplicated.
+ */
+export function linkClaims(claims = [], subjects = [], { selfId = '' } = {}) {
+  const targets = [];
+  for (const s of subjects) {
+    if (!s?.id || s.id === selfId) continue;
+    const names = [s.name, ...(s.aliases || [])].map(normalizeSubject).filter((n) => n && n.length >= 3);
+    if (names.length) targets.push({ id: s.id, names });
+  }
+  if (!targets.length) return claims;
+  return claims.map((c) => {
+    const hay = ` ${normalizeSubject(c.text)} `;
+    const have = new Set((c.refs || []).map((r) => `${r.kind}:${r.id}`));
+    const added = [];
+    for (const t of targets) {
+      if (have.has(`brief:${t.id}`)) continue;
+      if (t.names.some((n) => hay.includes(` ${n} `))) {
+        added.push({ kind: 'brief', id: t.id, hash: contentHash(t.id) });
+        have.add(`brief:${t.id}`);
+      }
+    }
+    return added.length ? { ...c, refs: [...(c.refs || []), ...added] } : c;
+  });
+}
+
+/** A pending synthesis for one brief. Never carries `promoted`. */
+export function propose({ briefId, claims = [], summary = '', by = 'model', now = 0, newId = null } = {}) {
+  if (!briefId) throw new TypeError('propose: briefId required');
+  const bad = claims.find((c) => c?.cls !== 'C' || !c?.refs?.length);
+  if (bad) throw new TypeError('propose: only class-C claims with refs may be proposed');
+  return {
+    id: newId ? newId() : `p-${briefId}-${now}`,
+    briefId,
+    by: String(by),
+    at: now,
+    state: 'proposed',
+    claims: claims.map((c) => ({ ...c, state: 'proposed' })),
+    summary: String(summary || ''),
+  };
+}
+
+/**
+ * Accept: the proposal's claims join the brief as promoted class-C claims. The ONLY path.
+ * Returns a new brief and the settled proposal; mutates neither input.
+ */
+export function accept(brief, proposal, { now = 0, subjects = [] } = {}) {
+  if (!brief || !proposal || proposal.briefId !== brief.id) throw new TypeError('accept: proposal does not belong to this brief');
+  if (proposal.state !== 'proposed') throw new TypeError(`accept: proposal is ${proposal.state}`);
+  let promoted = proposal.claims.map((c) => ({ ...c, state: 'promoted', lastConfirmed: now }));
+  // Backlinks, at the moment of acceptance — the one point where the claim is final and the
+  // set of other pages is known.
+  promoted = linkClaims(promoted, subjects, { selfId: brief.id });
+
+  // SUPERSESSION. "Cutover is planned for Q3" and "Cutover moved to Q4" must not sit on one
+  // page as two contradicting lines. The old claim is not deleted — that would lose "when did
+  // this change" — it is marked superseded by the new one, and keeps its refs, so the brief
+  // reads as a history rather than an argument with itself. The rule is the same overlap
+  // diffProposal shows the reviewer, so what they accepted is what happens.
+  const diff = diffProposal(brief, proposal);
+  const superseded = new Map(); // old text -> new claim id
+  diff.forEach((d, i) => { if (d.replaces && promoted[i]) superseded.set(d.replaces, promoted[i].id); });
+  const kept = brief.claims.map((c) => (superseded.has(c.text) && !c.supersededBy
+    ? { ...c, supersededBy: superseded.get(c.text), supersededAt: now }
+    : c));
+  promoted = promoted.map((c, i) => (diff[i]?.replaces ? { ...c, supersedes: brief.claims.find((o) => o.text === diff[i].replaces)?.id || null } : c));
+
+  const next = {
+    ...brief,
+    claims: [...kept, ...promoted],
+    summary: proposal.summary || brief.summary || '',
+    updatedAt: now,
+  };
+  return { brief: next, proposal: { ...proposal, state: 'accepted', settledAt: now, claims: promoted } };
+}
+
+export function reject(proposal, { now = 0, why = '' } = {}) {
+  if (!proposal || proposal.state !== 'proposed') throw new TypeError('reject: not a pending proposal');
+  return { ...proposal, state: 'rejected', settledAt: now, why: String(why || '') };
+}
+
+/**
+ * The diff a reviewer sees: what is new against the brief, and what a new claim
+ * contradicts or supersedes. Deterministic and cheap — same-subject, same-`when`-or-later
+ * claims that share enough words are shown as "replaces", which is a suggestion the
+ * reviewer confirms, never an edit.
+ */
+export function diffProposal(brief, proposal) {
+  const existing = (brief?.claims || []).map((c) => c.text);
+  const tokens = (t) => new Set(String(t).toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((w) => w.length > 3));
+  return proposal.claims.map((c) => {
+    const mine = tokens(c.text);
+    let best = null; let bestScore = 0;
+    for (const e of existing) {
+      const theirs = tokens(e);
+      let hit = 0; for (const w of mine) if (theirs.has(w)) hit += 1;
+      const score = mine.size ? hit / mine.size : 0;
+      if (score > bestScore) { bestScore = score; best = e; }
+    }
+    return { claim: c, replaces: bestScore >= SUPERSEDE_OVERLAP ? best : null, overlap: bestScore };
+  });
+}
+
+/**
+ * W7's rule. Given several INDEPENDENT drafts of the same subject, the claims that at least
+ * `minAgree` drafts made (by near-identical text) may be proposed automatically; the rest go
+ * to the human queue. "Agree" is a text-overlap test, not equality — two models never phrase
+ * a thing identically, and requiring it would make convergence measure nothing.
+ */
+export function converge(drafts = [], { minAgree = 2, threshold = 0.6 } = {}) {
+  const tokens = (t) => new Set(String(t).toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((w) => w.length > 3));
+  const all = drafts.flatMap((d, i) => (d?.claims || []).map((c) => ({ c, draft: i, t: tokens(c.text) })));
+  const agreed = [];
+  const disputed = [];
+  const used = new Set();
+  for (let i = 0; i < all.length; i += 1) {
+    if (used.has(i)) continue;
+    const group = [i];
+    for (let j = i + 1; j < all.length; j += 1) {
+      if (used.has(j) || all[j].draft === all[i].draft) continue;
+      let hit = 0; for (const w of all[i].t) if (all[j].t.has(w)) hit += 1;
+      const score = all[i].t.size ? hit / all[i].t.size : 0;
+      if (score >= threshold) group.push(j);
+    }
+    const drafters = new Set(group.map((g) => all[g].draft));
+    for (const g of group) used.add(g);
+    // The union of refs across agreeing drafts: agreement on the claim is evidence, and so
+    // is every record any of them cited for it.
+    const refs = [...new Map(group.flatMap((g) => all[g].c.refs || []).map((r) => [`${r.kind}:${r.id}`, r])).values()];
+    const merged = { ...all[i].c, refs, agreedBy: drafters.size };
+    (drafters.size >= minAgree ? agreed : disputed).push(merged);
+  }
+  return { agreed, disputed };
+}

package/redaction-tokens.js

@@ -0,0 +1,61 @@
+// Recognising a redaction placeholder — one predicate, and nothing else in the module.
+//
+// It is its own file for the reason `distance.js` is: three unrelated places need this
+// question answered — the subject resolver, the wikilink parser, and the extension's note
+// index — and the first two live in `entity.js`, which has since grown entity resolution,
+// merge suggestions and a Levenshtein dependency. Importing 25 KB of that into a notes page
+// to ask "is this string a placeholder" is the same 120 KB mistake in a smaller coat.
+
+/**
+ * A REDACTION PLACEHOLDER IS NOT A SUBJECT — and this is the sharpest edge in the module.
+ *
+ * `@chatpanel/pii` writes `[[PERSON_1]]`, `[[EMAIL_2]]`, `[[LOCATION_1]]`, which is
+ * character-for-character the `[[wikilink]]` grammar. So a redacted transcript reads as a
+ * document full of links to pages that do not exist, and every one of them earned a "wanted
+ * page" brief. The name of a person we deliberately did not learn was being filed as a thing
+ * we know about.
+ *
+ * The tempting fix is to treat the token as a pseudonymous identity — it IS stable, and
+ * within one conversation `PERSON_1` really does mean one person. It must not become a
+ * subject anyway, because **the vault is scoped to a conversation**: `PERSON_1` in Monday's
+ * chat and `PERSON_1` in Friday's are different people, and a global subject would merge
+ * strangers under one page and attribute one person's decisions to another. That is the same
+ * reason `aliasMap` refuses a bare token two people could claim — here it is guaranteed
+ * rather than possible.
+ *
+ * So the placeholder is dropped from subject candidacy, and `curate.js` counts what was
+ * dropped so the loss is REPORTED rather than silent. Never resolved against a vault into
+ * anything derived and persisted, either: that would put the PII back on disk in a second
+ * place, which is the one thing redaction exists to prevent.
+ *
+ * The pattern is duplicated from `@chatpanel/pii` rather than imported — this package ships
+ * zero dependencies so the bridge can vendor it file by file, the same constraint that makes
+ * the entitlement JWK live in two clients. `CLAUDE.md` lists `[[TYPE_n]]` as a wire contract
+ * that only changes additively, and the extension (which vendors both) carries the drift
+ * guard that fails when these two stop agreeing.
+ */
+export const REDACTION_TOKEN_TYPES = Object.freeze([
+  'PERSON', 'ORG', 'LOCATION', 'ADDRESS', 'EMAIL', 'PHONE', 'ID', 'SSN', 'IBAN',
+  'CREDITCARD', 'CARD', 'POST', 'FAC', 'GROUP', 'NRP', 'ENTITY', 'KEY', 'SECRET',
+  'TERM', 'PII', 'OTHER',
+]);
+
+const BARE_TOKEN_RE = /^([A-Z][A-Z0-9]*)_\d+$/;
+const unwrap = (v) => String(v ?? '').trim().replace(/^\[{1,2}|\]{1,2}$/g, '');
+
+/**
+ * Is this BARE string one of the redaction placeholders?
+ *
+ * Matched against the type vocabulary rather than the `[A-Z]+_\d+` shape, and everywhere —
+ * inside brackets too. The shape alone eats real subjects: `[[Q3_2026]]` and `[[PHASE_2]]`
+ * are links people genuinely write, and silently dropping them would trade one invisible bug
+ * for another. A custom dictionary type is the accepted gap: it is user-chosen, so filing it
+ * is a name the user picked, not a stranger's identity.
+ *
+ * Bracket-tolerant, because a wikilink parser has already stripped them by the time we ask,
+ * and a model echoing a placeholder into JSON routinely mangles them.
+ */
+export function isRedactionToken(value) {
+  const m = BARE_TOKEN_RE.exec(unwrap(value));
+  return !!m && REDACTION_TOKEN_TYPES.includes(m[1]);
+}

package/ref.js

@@ -9,7 +9,10 @@
 // version of the note, because that would make replay quietly wrong instead of loudly
 // incomplete.
 
-export const REF_KINDS = Object.freeze(['note', 'meeting', 'chat', 'page', 'result', 'blob']);
+// `memory` and `brief` joined when the derived layer landed: a brief's claim cites the
+// record it came from, and a claim the USER stated cites the memory they stated it in.
+// Additive — no existing ref changes meaning.
+export const REF_KINDS = Object.freeze(['note', 'meeting', 'chat', 'page', 'result', 'blob', 'memory', 'brief']);
 
 export const RESOLUTION = Object.freeze({
   EXACT: 'exact',                              // blob present, hash matches

package/subject-kinds.js

@@ -0,0 +1,5 @@
+// The subject vocabulary, alone in a file so both halves of subject identity can name it
+// without either importing the other.
+
+/** What a subject can be. `title` is a record title someone linked to with [[…]]. */
+export const SUBJECT_KINDS = Object.freeze(['person', 'topic', 'tag', 'title']);

package/subject-name.js

@@ -0,0 +1,96 @@
+// Naming a subject, and when one is big enough to deserve a page.
+//
+// The small, dependency-free half of subject identity: fold a name to its canonical form,
+// strip the decoration a directory hangs off it, and hold the evidence thresholds. Nothing
+// here resolves aliases, proposes merges or reaches for a Levenshtein — that is `entity.js`,
+// which imports this.
+//
+// The split is a load-time one, and it is the third time the lesson has come up here (see
+// `distance.js` and `redaction-tokens.js`). `knowledge.js` needs exactly `normalizeSubject`
+// to build a brief id, and the extension's brief store needs exactly `DEFAULT_THRESHOLD` —
+// and both are on the MV3 service worker's graph. Reaching them through `entity.js` put
+// entity resolution and merge suggestion on a worker that will never run either.
+
+import { SUBJECT_KINDS } from './subject-kinds.js';
+
+/**
+ * A subject earns a brief with EVIDENCE, not on first sight (I-K4).
+ *
+ * PROVISIONAL. These numbers are the W0 measurement's whole point: `surveyCorpus()` reports
+ * how many subjects clear them so they can be set from a real corpus instead of taste. Do
+ * not treat them as decided until that report has been run.
+ */
+export const DEFAULT_THRESHOLD = Object.freeze({ records: 3, mentions: 5 });
+
+/** Ceiling on the set of briefs, for the same reason memory.js caps memories. Provisional. */
+export const MAX_SUBJECTS = 500;
+/** Longest name we will treat as a subject — past this it is a sentence, not a subject. */
+export const MAX_SUBJECT_CHARS = 60;
+/**
+ * Labels a meeting platform uses for the person holding the microphone.
+ *
+ * Zoom, Meet and Teams all write the local participant as "You" — so the user appears in
+ * their own corpus under a name that is not a name, alongside however their colleagues'
+ * clients spelled them. Resolving these needs one fact only the host has: who "you" IS.
+ * `resolveSubjects` takes it rather than guessing, and with no `self` supplied these stay
+ * unresolved instead of collapsing every meeting's local speaker into one fictional person.
+ */
+export const SELF_LABELS = Object.freeze(['you', 'me', 'myself', 'yourself', 'i']);
+
+/**
+ * Is this the platform's label for the local participant?
+ *
+ * Exported because two layers need the SAME exception and getting the order wrong is subtle:
+ * a self-label fails `isSubjectCandidate` (it is a pronoun), so any pass that filters
+ * candidacy BEFORE `resolveSubjects` can fold it has already thrown the user away. `curate.js
+ * mentionsFrom` keeps them for exactly this reason and lets resolution decide.
+ */
+export function isSelfLabel(name) {
+  return SELF_LABELS.includes(normalizeSubject(name));
+}
+
+/**
+ * Strip the decoration a directory or a conference client hangs off a person's name.
+ *
+ * The same human arrives as "Alex Rivera", "Alex Rivera (ACME)", "Alex Rivera - Host" and
+ * "Alex Rivera (he/him)" depending on which client wrote the label. The part in parentheses
+ * or after a dash is an org, a role or a pronoun set — decoration, never identity — so it is
+ * removed before folding.
+ *
+ * NOT removed for non-person subjects: "Migration (Phase 2)" is a different topic from
+ * "Migration", where "Alex Rivera (ACME)" is not a different person from "Alex Rivera".
+ */
+export function stripQualifiers(name) {
+  return String(name ?? '')
+    .replace(/\s*[([{][^)\]}]*[)\]}]\s*/g, ' ')   // (ACME), [external], {guest}
+    .replace(/\s+[-–—|·,]\s+.*$/, '')             // - Host, — Guest, | ACME
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+/**
+ * Fold a name to its canonical form: lowercase, Unicode-aware, separators collapsed.
+ *
+ * Spaces survive as spaces (unlike normalizeTag, which folds them to '-') because a person's
+ * name is read back to the user and "alex rivera" has to be recognisable as one.
+ */
+export function normalizeSubject(name) {
+  const raw = String(name ?? '').normalize('NFKC').trim().replace(/^[#@]+/, '');
+  if (!raw) return '';
+  return raw
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, ' ')
+    .trim()
+    .slice(0, MAX_SUBJECT_CHARS)
+    .trim();
+}
+/** `person:alex rivera` — the identity a brief is filed under. '' when nothing survives. */
+export function subjectKey(kind, name) {
+  const norm = normalizeSubject(name);
+  if (!norm || !SUBJECT_KINDS.includes(kind)) return '';
+  return `${kind}:${norm}`;
+}
+/** Tokens of a canonical name. */
+export function subjectTokens(name) {
+  const norm = normalizeSubject(name);
+  return norm ? norm.split(' ').filter(Boolean) : [];
+}

package/sync-plan.js

@@ -0,0 +1,170 @@
+// RECONCILING TWO COPIES OF THE LIBRARY — the pure half of two-way sync.
+//
+// The extension holds the corpus in chrome.storage; a desktop app holds it in SQLite; the
+// gateway holds a warm copy. Each pair of those needs the same question answered: given what
+// I have and what you have, what do I pull, what do I push, and what genuinely conflicts.
+//
+// It lives here because the answer must not depend on WHO is asking. If the extension
+// decided ties one way and the desktop the other, two clients syncing the same record would
+// flap — each would keep "winning" and re-pushing, forever. One rule, both sides.
+//
+// WHAT MAKES THIS SAFE TO RUN REPEATEDLY: the plan is a pure function of two index lists, so
+// applying it and re-planning yields an empty plan. That is the property to hold on to —
+// every bug in a sync engine eventually shows up as "running it twice does something".
+//
+// TOMBSTONES ARE NOT OPTIONAL, and this is the sharpest edge in the module. A record that is
+// merely ABSENT from one side is indistinguishable from one that side has never seen. So a
+// deletion has to be representable as a value — `deletedAt` — or "delete" and "not synced
+// yet" are the same input with opposite correct answers. The extension's warm sync already
+// hit this and chose, deliberately, not to tombstone (a missing browser record may simply
+// have aged out of IndexedDB while remaining in a backup). That choice is why warm sync is
+// one-way. A two-way sync cannot make it.
+//
+// Pure over arrays of `{ id, updatedAt, deletedAt }`. No storage, no network, no clock —
+// `now` is never consulted, because a plan that depends on when you asked is not a plan.
+
+export class SyncError extends Error {
+  constructor(message) { super(message); this.name = 'SyncError'; }
+}
+
+/**
+ * How far apart two timestamps may be and still count as "the same edit".
+ *
+ * Clocks on two machines are not identical, and a record copied between them can come back
+ * with a millisecond of drift. Without a tolerance every round trip looks like a fresh edit
+ * and the two sides push at each other indefinitely.
+ */
+export const CLOCK_TOLERANCE_MS = 1000;
+
+const num = (v) => (Number.isFinite(Number(v)) ? Number(v) : 0);
+
+/** The comparable stamp of a record: when it last changed, deleted or not. */
+export function stampOf(entry) {
+  if (!entry) return 0;
+  return Math.max(num(entry.updatedAt), num(entry.deletedAt));
+}
+
+function indexById(entries) {
+  const m = new Map();
+  for (const e of entries || []) {
+    if (!e || !e.id) continue;
+    // Later duplicates win: a caller concatenating pages should not be punished for it.
+    m.set(e.id, e);
+  }
+  return m;
+}
+
+/**
+ * Decide one record. Exported because it is the whole rule, and a caller that streams
+ * records one at a time should not have to build two full indexes to use it.
+ *
+ * Returns one of:
+ *   'none'     — the two sides agree
+ *   'pull'     — remote is newer; take theirs
+ *   'push'     — local is newer, or remote has never seen it; send ours
+ *   'conflict' — both changed since the last common state and neither is clearly newer
+ */
+export function decide(local, remote, { tolerance = CLOCK_TOLERANCE_MS, base = null } = {}) {
+  if (!local && !remote) return 'none';
+  if (!remote) return 'push';
+  if (!local) return 'pull';
+
+  const l = stampOf(local);
+  const r = stampOf(remote);
+  const delta = l - r;
+  if (Math.abs(delta) <= tolerance) return 'none';
+
+  // With a recorded base (what both sides last agreed on) we can tell a genuine divergence
+  // from a simple fast-forward: a conflict is when BOTH moved. Without a base the newer
+  // stamp wins, which is last-write-wins and is all a first sync can honestly offer.
+  if (base) {
+    const b = stampOf(base);
+    const localMoved = l - b > tolerance;
+    const remoteMoved = r - b > tolerance;
+    if (localMoved && remoteMoved) return 'conflict';
+  }
+  return delta > 0 ? 'push' : 'pull';
+}
+
+/**
+ * Plan a full two-way reconcile.
+ *
+ * `bases` is optional — a map (or array) of the stamps both sides last agreed on, which is
+ * what upgrades last-write-wins into real conflict detection. Callers that keep a sync
+ * journal pass it; callers that do not get LWW and no false conflicts.
+ *
+ * Returns `{ pull, push, conflicts, unchanged }` as arrays of ids, plus `counts`.
+ */
+export function planSync(localEntries, remoteEntries, {
+  tolerance = CLOCK_TOLERANCE_MS, bases = null,
+} = {}) {
+  const local = indexById(localEntries);
+  const remote = indexById(remoteEntries);
+  const baseMap = bases instanceof Map ? bases : indexById(bases);
+
+  const pull = [];
+  const push = [];
+  const conflicts = [];
+  let unchanged = 0;
+
+  for (const id of new Set([...local.keys(), ...remote.keys()])) {
+    const verdict = decide(local.get(id), remote.get(id), { tolerance, base: baseMap.get(id) || null });
+    if (verdict === 'pull') pull.push(id);
+    else if (verdict === 'push') push.push(id);
+    else if (verdict === 'conflict') conflicts.push(id);
+    else unchanged += 1;
+  }
+
+  // Stable order so two runs over the same input produce byte-identical plans — which is
+  // what makes a plan diffable in a log and testable without sorting at every assertion.
+  pull.sort();
+  push.sort();
+  conflicts.sort();
+
+  return {
+    pull, push, conflicts, unchanged,
+    counts: { pull: pull.length, push: push.length, conflicts: conflicts.length, unchanged },
+  };
+}
+
+/** Nothing to do — the property a correct sync reaches and stays at. */
+export function isSettled(plan) {
+  return !!plan && plan.pull.length === 0 && plan.push.length === 0 && plan.conflicts.length === 0;
+}
+
+/**
+ * Resolve a conflict by keeping both: the loser is preserved under a new id rather than
+ * overwritten.
+ *
+ * Silently discarding one side of a conflict is how a sync engine loses the paragraph
+ * someone wrote on a plane. The caller supplies `newId` because id minting is a host
+ * concern; this only decides WHAT the two resulting records are.
+ */
+export function forkConflict(localRecord, remoteRecord, { newId, label = 'conflicted copy' } = {}) {
+  if (typeof newId !== 'function') throw new SyncError('forkConflict needs a newId() function');
+  const keep = stampOf(localRecord) >= stampOf(remoteRecord) ? localRecord : remoteRecord;
+  const fork = keep === localRecord ? remoteRecord : localRecord;
+  const parsedKind = String(fork.id || '').split(':')[0];
+  return {
+    keep,
+    fork: {
+      ...fork,
+      id: `${parsedKind}:${newId()}`,
+      title: `${fork.title || 'Untitled'} (${label})`,
+      meta: { ...(fork.meta || {}), conflictOf: keep.id },
+    },
+  };
+}
+
+/**
+ * Fold applied ids back into a base map, so the NEXT plan can tell a fast-forward from a
+ * divergence. Returns a new Map; the input is not mutated.
+ */
+export function advanceBases(bases, applied = []) {
+  const next = bases instanceof Map ? new Map(bases) : indexById(bases);
+  for (const entry of applied) {
+    if (!entry || !entry.id) continue;
+    next.set(entry.id, { id: entry.id, updatedAt: num(entry.updatedAt), deletedAt: num(entry.deletedAt) });
+  }
+  return next;
+}

package/synthesis.js

@@ -0,0 +1,123 @@
+// SYNTHESIS — the first class-C claims: prose about a subject, written by a model.
+//
+// Everything a brief said until now was class R: a restatement of something a record
+// already held, with nothing to review. This is the layer the wiki pattern is actually
+// about — "what was decided about Atlas, and when did it change" — and it is exactly the
+// layer the community warned about: agent writing nobody reviewed compounds into confident
+// nonsense that a lint pass cannot tell apart from truth six months on (C2).
+//
+// So two rules do all the defending, and both are enforced here rather than promised:
+//
+//   I-K1  EVERY CLAIM CITES A RECORD IT WAS SHOWN. The model sees excerpts labelled with
+//         their ids and must attach at least one to each claim. A claim citing nothing, or
+//         citing an id that was not in the excerpt set, is REFUSED — not downgraded, not
+//         flagged, refused — because a citation a reader cannot open is worse than no claim.
+//   I-K3  NOTHING HERE PROMOTES. `claimsFromSynthesis` produces claims in state `proposed`
+//         and `promotion.js` is the only path to `promoted`. There is no flag to skip it.
+//
+// The model call itself is not made here (no network, per the package rule). This module
+// owns the SHAPE — one schema, one prompt, one parser — so the extension, the gateway and a
+// desktop client ask the same question and read the answer the same way. It is written as
+// a single appointment on purpose: a team appointment (W7 — drafters that must agree) has
+// the same contract, with `converge()` in promotion.js deciding what to propose.
+
+import { defineSchema, describeSchema } from './structured.js';
+
+export const MAX_SYNTHESIS_CLAIMS = 8;
+export const MAX_CLAIM_CHARS = 240;
+export const MAX_EXCERPT_CHARS = 1200;
+export const MAX_EXCERPTS = 24;
+
+export const SYNTHESIS_SCHEMA = defineSchema({
+  name: 'brief_synthesis',
+  purpose: 'What the records establish about one subject, as separate cited claims.',
+  fields: {
+    claims: {
+      type: 'object[]', maxItems: MAX_SYNTHESIS_CLAIMS,
+      describe: 'the things the records establish about the subject — decisions, roles, status, changes — one per entry, each cited',
+      fields: {
+        text: { type: 'string', required: true, max: MAX_CLAIM_CHARS, describe: 'one specific claim in plain prose, past tense for events, present for standing facts' },
+        refs: { type: 'string[]', required: true, maxItems: 6, describe: 'the record ids (exactly as labelled, e.g. meeting:m_12) that support this claim — at least one, only ones you were shown' },
+        when: { type: 'string', max: 10, describe: 'YYYY-MM-DD of the record that establishes it, if one does' },
+      },
+    },
+    summary: { type: 'string', max: 600, describe: 'two or three sentences of what a colleague should know about this subject right now' },
+  },
+  // "The records do not establish anything beyond what is already listed" is a legitimate
+  // answer and must not be read as a failure — read as one, a caller might fall back to the
+  // model's prose without the schema, which is the exact unstructured path this replaces.
+  nothing: { claims: [], summary: '' },
+});
+
+/**
+ * The prompt. The subject, what the deterministic layer already says (so the model adds to
+ * it rather than restating it), and the excerpts it may cite — each labelled with the id it
+ * must use. Excerpts are capped per record and in count, because this is a bounded call by
+ * design (I-K4): a subject with two hundred records gets its most recent two dozen, and a
+ * later pass can take the rest.
+ */
+export function synthesisPrompt({ subject, existing = [], excerpts = [] } = {}) {
+  const name = String(subject?.name || 'the subject');
+  const kind = String(subject?.kind || 'subject');
+  const shown = excerpts.slice(0, MAX_EXCERPTS);
+  const lines = [
+    `Subject: ${name} (${kind})${subject?.aliases?.length ? ` — also written as ${subject.aliases.join(', ')}` : ''}.`,
+    '',
+    'Already established (do not repeat these):',
+    ...(existing.length ? existing.map((c) => `- ${c}`) : ['- nothing yet']),
+    '',
+    `Records you may cite (${shown.length}). Cite ONLY these ids, exactly as written:`,
+    ...shown.map((e) => `[${e.id}] ${e.title || ''}${e.date ? ` (${e.date})` : ''}\n${String(e.text || '').slice(0, MAX_EXCERPT_CHARS)}`),
+    '',
+    'Write what these records ESTABLISH about the subject: decisions, ownership, status, and',
+    'anything that changed over time (say what it was before and after). Every claim must cite',
+    'at least one of the ids above. If the records establish nothing beyond what is already',
+    'listed, return no claims.',
+    '',
+    describeSchema(SYNTHESIS_SCHEMA),
+  ];
+  return lines.join('\n');
+}
+
+/**
+ * The model's answer → claims a brief could carry, with the refusals listed.
+ *
+ * `knownIds` is the set of ids the model was shown. A claim citing anything outside it is
+ * refused whole — the model invented or misremembered a citation, and a claim we cannot
+ * trace is a claim we cannot keep (I-K1). `hashOf(id)` gives the record's drift hash so the
+ * ref can later say "this record changed since I cited it".
+ *
+ * Returns claims in state `proposed`, class C. There is no argument that produces
+ * `promoted`; that is promotion.js's job and nobody else's (I-K3).
+ */
+export function claimsFromSynthesis(value, { knownIds, hashOf = () => 'unhashed', now = 0, newId = null } = {}) {
+  const known = knownIds instanceof Set ? knownIds : new Set(knownIds || []);
+  const out = [];
+  const refused = [];
+  let n = 0;
+  const id = () => (newId ? newId() : `s${now}-${(n += 1)}`);
+  for (const raw of value?.claims || []) {
+    const text = String(raw?.text || '').trim();
+    const refs = [...new Set((raw?.refs || []).map((r) => String(r || '').trim()).filter(Boolean))];
+    if (!text) { refused.push({ text, why: 'empty' }); continue; }
+    if (!refs.length) { refused.push({ text, why: 'no citation' }); continue; }
+    const unknown = refs.filter((r) => !known.has(r));
+    if (unknown.length) { refused.push({ text, why: `cites a record it was not shown: ${unknown.join(', ')}` }); continue; }
+    out.push({
+      id: id(),
+      kind: 'synthesis',
+      text: text.slice(0, MAX_CLAIM_CHARS),
+      refs: refs.map((r) => {
+        const idx = r.indexOf(':');
+        return { kind: r.slice(0, idx), id: r.slice(idx + 1), hash: hashOf(r) };
+      }),
+      when: /^\d{4}-\d{2}-\d{2}$/.test(String(raw?.when || '')) ? raw.when : '',
+      firstSeen: now,
+      lastConfirmed: now,
+      confidence: 0.6, // a model's read, not a record's word — lower than any class-R claim
+      cls: 'C',
+      state: 'proposed',
+    });
+  }
+  return { claims: out, summary: String(value?.summary || '').trim().slice(0, 600), refused };
+}