mlx-bun 0.0.8 → 0.0.10

package/src/memory/resolve.ts

@@ -0,0 +1,307 @@
+// mlx-bun memory — surface-variant RESOLUTION (the dedup fix for P5-T3/T4).
+//
+// canonicalize() in entity.ts is a *pure string normal form*: casefold, collapse
+// whitespace, strip articles/possessives. That is necessary but NOT sufficient —
+// the self-check turned the spacing, brand-only, and possessive surfaces of ONE
+// product name into several different stems:
+//   - "<name>" vs "<na me>"  (internal spacing the normal form keeps)
+//   - "<brand>" / "<brand> <model>"  (brand-only and compositional surfaces that
+//     no purely-lexical normalizer can fold onto one canonical)
+//
+// The resolver adds three layers on top of canonicalize():
+//   1. SQUEEZE — strip ALL non-alphanumerics so "<na me>" / "<name>" / "<nam e>"
+//      collapse to one key deterministically (fixes the spacing split).
+//   2. ALIAS SEED — a known-entity index (entities + entity_aliases in the store,
+//      seeded from goldens/dreaming-entities-gold.json) so brand-only / nickname
+//      surfaces (a "<the brand>", a "<the role>") resolve by exact alias hit.
+//   3. TOKEN-SUBSET FUZZY — a conservative compositional match: a surface folds
+//      onto an entity iff its content tokens are a SUBSET of that entity's tokens
+//      AND the overlap carries at least one DISTINCTIVE token (a token unique to
+//      that entity among all known entities). This merges "<my brand model>" → the
+//      entity via the distinctive model token while REFUSING to merge
+//      "<brand A>" into "<brand B>" (a shared brand token is not distinctive;
+//      the model-number tokens differ) — the over-merge guard.
+//
+// Resolution is conservative by construction: when in doubt it MINTS a new
+// canonical rather than fusing two distinct things. ROUTE (route.ts) escalates
+// the genuine misses to the model for binary disambiguation.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { canonicalize } from "./entity";
+import type { MemoryStore } from "./db";
+
+/** Tokens that carry no disambiguating signal on their own (articles, glue, and
+ *  generic gear nouns shared across many entities). Used only for the fuzzy
+ *  token-subset layer — never for the exact alias index. */
+const STOP = new Set([
+  "the", "a", "an", "and", "or", "of", "to", "for", "in", "on", "with", "is",
+  "as", "my", "your", "his", "her", "its", "our", "their",
+]);
+
+/** Strip ALL non-alphanumerics and casefold: the spacing/punct-insensitive key.
+ *  A name's spacing and punctuation variants all collapse here. */
+export function squeeze(surface: string): string {
+  return surface.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+/** Content tokens of a surface (casefold, split on non-alphanumerics, drop
+ *  stopwords and single characters). Order-insensitive set. */
+export function contentTokens(surface: string): Set<string> {
+  const out = new Set<string>();
+  for (const t of surface.toLowerCase().split(/[^a-z0-9]+/)) {
+    if (t.length > 1 && !STOP.has(t)) out.add(t);
+  }
+  return out;
+}
+
+/** How a surface resolved (for instrumentation + the deterministic gates). */
+export type MatchKind = "stem" | "squeeze" | "alias" | "fuzzy" | "new";
+
+export interface ResolveResult {
+  /** The canonical entity name the surface resolved to (or was minted as). */
+  name: string;
+  /** Which layer produced the resolution. "new" ⇒ a canonical was minted. */
+  matched: MatchKind;
+  /** True iff this call minted a NEW canonical (no existing entity matched). */
+  created: boolean;
+}
+
+interface Seed {
+  canonical: string;
+  aliases: string[];
+}
+
+/**
+ * In-memory variant resolver over a KNOWN-ENTITY set. Indexes each canonical by
+ * its normal-form stem, its squeeze key, and its content tokens, then resolves a
+ * surface through stem → squeeze → alias → token-subset-fuzzy, minting a new
+ * canonical only when every layer misses.
+ *
+ * Construct from a seed list, from a {@link MemoryStore} (entities +
+ * entity_aliases), or from the curated gold — and compose them (store first,
+ * gold to backfill notable brand-only aliases).
+ */
+export class EntityResolver {
+  /** normal-form stem → canonical. */
+  private byStem = new Map<string, string>();
+  /** squeeze key → canonical. */
+  private bySqueeze = new Map<string, string>();
+  /** canonical → union of content tokens across its name + aliases. */
+  private tokensOf = new Map<string, Set<string>>();
+  /** content token → set of canonicals carrying it (distinctiveness check). */
+  private tokenOwners = new Map<string, Set<string>>();
+
+  constructor(seeds: Seed[] = []) {
+    for (const s of seeds) this.register(s.canonical, s.aliases);
+  }
+
+  /** All known canonical names (registration order is not guaranteed). */
+  canonicals(): string[] {
+    return [...this.tokensOf.keys()];
+  }
+
+  /** Is `name` an already-known canonical entity? */
+  has(name: string): boolean {
+    return this.tokensOf.has(name);
+  }
+
+  /** Register a canonical and its aliases into every index. Idempotent; adding
+   *  aliases to an existing canonical merges them. The canonical's own surface is
+   *  always indexed as an alias of itself. */
+  register(canonical: string, aliases: string[] = []): void {
+    if (!this.tokensOf.has(canonical)) this.tokensOf.set(canonical, new Set());
+    const tokset = this.tokensOf.get(canonical)!;
+    for (const surface of [canonical, ...aliases]) {
+      const stem = canonicalize(surface);
+      const sq = squeeze(surface);
+      if (stem && !this.byStem.has(stem)) this.byStem.set(stem, canonical);
+      if (sq && !this.bySqueeze.has(sq)) this.bySqueeze.set(sq, canonical);
+      for (const t of contentTokens(surface)) {
+        tokset.add(t);
+        let owners = this.tokenOwners.get(t);
+        if (!owners) this.tokenOwners.set(t, (owners = new Set()));
+        owners.add(canonical);
+      }
+    }
+  }
+
+  /** A token is DISTINCTIVE iff exactly one known canonical carries it — the
+   *  signal the fuzzy layer requires to merge a compositional surface. */
+  private distinctive(token: string): string | null {
+    const owners = this.tokenOwners.get(token);
+    if (!owners || owners.size !== 1) return null;
+    return [...owners][0]!;
+  }
+
+  /**
+   * Conservative token-subset fuzzy match: the surface's content tokens must be a
+   * non-empty SUBSET of some entity's tokens, and at least one of them must be
+   * distinctive to that same entity. Returns the canonical, or null if no
+   * unambiguous owner (zero or conflicting distinctive owners ⇒ refuse to merge).
+   */
+  private fuzzy(surface: string): string | null {
+    const toks = contentTokens(surface);
+    if (toks.size === 0) return null;
+    // The distinctive tokens present in the surface, and who owns them.
+    const owners = new Set<string>();
+    for (const t of toks) {
+      const owner = this.distinctive(t);
+      if (owner) owners.add(owner);
+    }
+    if (owners.size !== 1) return null; // none, or a tie across entities → no merge
+    const cand = [...owners][0]!;
+    // Subset guard: every surface token must belong to the candidate, else the
+    // surface names something MORE than (a variant of) the candidate.
+    const ets = this.tokensOf.get(cand)!;
+    for (const t of toks) if (!ets.has(t)) return null;
+    return cand;
+  }
+
+  /** Resolve a surface to an EXISTING canonical, or null if every layer misses.
+   *  Pure: never mutates the index. */
+  match(surface: string): { name: string; matched: MatchKind } | null {
+    const stem = canonicalize(surface);
+    if (stem) {
+      const byStem = this.byStem.get(stem);
+      if (byStem) return { name: byStem, matched: "stem" };
+    }
+    const sq = squeeze(surface);
+    if (sq) {
+      const bySq = this.bySqueeze.get(sq);
+      if (bySq) return { name: bySq, matched: "squeeze" };
+    }
+    const fz = this.fuzzy(surface);
+    if (fz) return { name: fz, matched: "fuzzy" };
+    return null;
+  }
+
+  /**
+   * Resolve a surface, MINTING a new canonical when nothing matches. The minted
+   * canonical is the cleaned surface; it is registered so later variants of the
+   * same thing fold onto it. Brand-only nicknames still need a gold/store seed —
+   * fuzzy cannot invent a "<the brand>" ≡ "<brand model>" link from lexis alone.
+   */
+  resolve(surface: string, mintName?: string): ResolveResult {
+    const hit = this.match(surface);
+    if (hit) return { name: hit.name, matched: hit.matched, created: false };
+    const canonical = (mintName ?? surface).trim();
+    this.register(canonical, surface === canonical ? [] : [surface]);
+    return { name: canonical, matched: "new", created: true };
+  }
+
+  /** Register one canonical per stem with its alias surfaces, grouped from a
+   *  normalized `alias → stem` map (the read-index's `aliasToStem`). The stem is
+   *  the canonical; its surfaces become aliases. */
+  static fromAliasMap(aliasToStem: Iterable<readonly [string, string]>): EntityResolver {
+    const byStem = new Map<string, string[]>();
+    for (const [alias, stem] of aliasToStem) {
+      let list = byStem.get(stem);
+      if (!list) byStem.set(stem, (list = []));
+      list.push(alias);
+    }
+    const r = new EntityResolver();
+    for (const [stem, aliases] of byStem) r.register(stem, aliases);
+    return r;
+  }
+
+  /** Load the known-entity index from a store's entities + entity_aliases. */
+  static fromStore(store: MemoryStore): EntityResolver {
+    const r = new EntityResolver();
+    const ents = store.db.query("SELECT name FROM entities").all() as { name: string }[];
+    for (const e of ents) r.register(e.name, []);
+    const aliases = store.db
+      .query("SELECT alias, entity_name FROM entity_aliases")
+      .all() as { alias: string; entity_name: string }[];
+    for (const a of aliases) {
+      if (!r.has(a.entity_name)) r.register(a.entity_name, [a.alias]);
+      else r.register(a.entity_name, [a.alias]);
+    }
+    return r;
+  }
+}
+
+// ---- near-name resolution (sub-concept → its home article) -----------------
+
+/** Generic "kind-of-thing" suffix words a discussed sub-concept drops when it is
+ *  the SAME subject as an existing article (a query that is the article title
+ *  minus a generic tail — "<subject>" for "<subject> Theory"). They carry no
+ *  disambiguating signal alone, so a query made ONLY of these never redirects. */
+const GENERIC_SUFFIX = new Set([
+  "theory", "framework", "system", "model", "method", "methodology", "approach",
+  "principle", "principles", "technique", "concept", "paradigm", "effect", "law",
+  "hypothesis", "problem", "process", "pattern", "practice",
+]);
+
+/**
+ * NEAR-NAME match: resolve a surface to an EXISTING article when it is clearly the
+ * SAME subject — the conservative token-subset fuzzy (a query whose content tokens
+ * are a distinctive subset of an article's, e.g. the title minus a generic suffix).
+ * Reuses {@link EntityResolver.match} (stem → squeeze → token-subset fuzzy) but
+ * REFUSES a query made only of generic suffix words (just "Theory"/"Framework"),
+ * which would over-merge onto an arbitrary article. Returns the canonical (== the
+ * article stem the resolver was seeded with), or null. Pure.
+ */
+export function nearNameMatch(resolver: EntityResolver, surface: string): string | null {
+  const toks = contentTokens(surface);
+  if (toks.size === 0) return null;
+  let hasContentToken = false;
+  for (const t of toks) {
+    if (!GENERIC_SUFFIX.has(t)) {
+      hasContentToken = true;
+      break;
+    }
+  }
+  if (!hasContentToken) return null; // a purely-generic query must not redirect
+  const hit = resolver.match(surface);
+  return hit ? hit.name : null;
+}
+
+// ---- gold seed -------------------------------------------------------------
+
+export interface VariantGroup {
+  canonical: string;
+  kind: string;
+  domain: string;
+  variants: string[];
+}
+export interface NotableEntity {
+  name: string;
+  kind: string;
+  domain: string;
+  aliases: string[];
+  whyNotable: string;
+}
+export interface DreamingGold {
+  variantGroups: VariantGroup[];
+  notableEntities: NotableEntity[];
+}
+
+const GOLD_PATH = join(import.meta.dir, "..", "..", "goldens", "dreaming-entities-gold.json");
+
+/** Read the curated entity gold (variantGroups + notableEntities). */
+export function loadDreamingGold(path: string = GOLD_PATH): DreamingGold {
+  return JSON.parse(readFileSync(path, "utf8")) as DreamingGold;
+}
+
+/** Seeds derived from the gold: every variant group AND every notable entity
+ *  becomes a (canonical, aliases) seed. Notable entries that share a canonical
+ *  with a variant group merge their aliases. */
+export function goldSeeds(gold: DreamingGold = loadDreamingGold()): Seed[] {
+  const byName = new Map<string, Set<string>>();
+  const add = (canonical: string, aliases: string[]): void => {
+    let set = byName.get(canonical);
+    if (!set) byName.set(canonical, (set = new Set()));
+    for (const a of aliases) set.add(a);
+  };
+  for (const g of gold.variantGroups) add(g.canonical, g.variants);
+  for (const n of gold.notableEntities) add(n.name, n.aliases);
+  return [...byName].map(([canonical, aliases]) => ({ canonical, aliases: [...aliases] }));
+}
+
+/** A resolver pre-seeded with the curated gold — the production seed for the
+ *  notable brand-only aliases the model/lexis cannot derive on its own. */
+export function goldResolver(gold?: DreamingGold): EntityResolver {
+  return new EntityResolver(goldSeeds(gold));
+}

package/src/memory/route.ts

@@ -0,0 +1,272 @@
+// mlx-bun memory — ROUTE: chunk-entities → subject articles.
+//
+// Routing is the deterministic-first join from a chunk's extracted entity
+// surfaces to subject articles, with the model used ONLY to break genuine ties.
+// It is the routing thesis under test: read the subjects a chunk is *about* and
+// fan it out to EVERY article it touches (a single chunk routes to many).
+//
+// The policy here is Lucien's `Bucketing.md` / `Editorial_Guidelines.md`, ported
+// faithfully: SURFACE EVERYTHING (nothing is dropped as trivia), STRONGLY PREFER
+// EXISTING articles (existing wins ties), and mint a NEW article only for a
+// substantive subject with no existing home. There is NO ownership/usefulness
+// test — "anything that recurs in your thinking is notable enough."
+//
+// Per surface, in order:
+//   1. RESOLVE — squeeze/alias/token-subset against the known-entity index
+//      (resolve.ts). A hit routes deterministically (folds into that existing
+//      article), no model call.
+//   2. DISAMBIGUATE — a miss gets a trigram shortlist of existing entities; each
+//      candidate is put to the model as a bounded binary "is {surface} the same
+//      thing as {candidate}?" (callLocal("route"), 4 tokens, parseBinary). The
+//      first yes routes (existing wins).
+//   3. CREATE / CAPTURE — a surface that matches nothing runs the CREATE gate: a
+//      subject earns its OWN article when it RECURS (≥ RECURRENCE_THRESHOLD
+//      routed chunks) OR the chunk engages it as a genuine subject (stubs are
+//      encouraged for emerging topics). A thin single fleeting mention with no
+//      existing home is CAPTURED — left in its chunk, retrievable by search,
+//      never dropped and never forced into a junk article. It earns an article
+//      later if it recurs.
+//
+// The deterministic pieces (resolve-to-one, trigram shortlist, fan-out, the
+// CREATE gate arithmetic) are pure and unit-tested; only disambiguate() and
+// engagesAsSubject() touch the GPU.
+
+import type { MemoryStore } from "./db";
+import { callLocal, MAX_OUTPUT_TOKENS } from "./model";
+import { parseBinary } from "./parse";
+import { EntityResolver, type MatchKind } from "./resolve";
+
+/** Reserved bucket for subjects captured (not yet articled) — still retrievable
+ *  by search, NOT a trivia graveyard. The leading underscore keeps it out of the
+ *  emergent bucket namespace. */
+export const CAPTURED_BUCKET = "_captured";
+
+/** A subject RECURS (and so is notable enough for its own article) once it has
+ *  routed this many distinct chunks. Tunable (Bucketing.md: lower = more/smaller
+ *  articles, raise = fewer/larger); ≥2 == "recurs in your thinking." */
+export const RECURRENCE_THRESHOLD = 2;
+
+// ---- trigram shortlist -----------------------------------------------------
+
+/** Character trigrams of a casefolded, space-collapsed surface (padded so short
+ *  names still yield boundary grams). */
+function trigrams(surface: string): Set<string> {
+  const s = ` ${surface.toLowerCase().replace(/[^a-z0-9]+/g, " ").replace(/\s+/g, " ").trim()} `;
+  const out = new Set<string>();
+  for (let i = 0; i + 3 <= s.length; i++) out.add(s.slice(i, i + 3));
+  return out;
+}
+
+/** Overlap coefficient |A∩B| / min(|A|,|B|) — credits a short name CONTAINED in
+ *  a longer one rather than penalizing the length gap a Jaccard would. */
+function overlap(a: Set<string>, b: Set<string>): number {
+  const m = Math.min(a.size, b.size);
+  if (m === 0) return 0;
+  const [small, big] = a.size <= b.size ? [a, b] : [b, a];
+  let inter = 0;
+  for (const x of small) if (big.has(x)) inter++;
+  return inter / m;
+}
+
+/**
+ * Trigram-ranked shortlist of existing canonicals for a surface that the
+ * resolver missed — the candidate set handed to the model for disambiguation.
+ * Returns up to `k` canonicals with nonzero overlap, best first.
+ */
+export function trigramShortlist(
+  resolver: EntityResolver,
+  surface: string,
+  k = 5,
+): string[] {
+  const q = trigrams(surface);
+  const scored: { name: string; score: number }[] = [];
+  for (const name of resolver.canonicals()) {
+    const s = overlap(q, trigrams(name));
+    if (s > 0) scored.push({ name, score: s });
+  }
+  scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+  return scored.slice(0, k).map((c) => c.name);
+}
+
+// ---- model gates -----------------------------------------------------------
+
+/**
+ * Bounded binary disambiguation: is `surface` (in the chunk's `label` context)
+ * the same thing as the candidate `entity` (one-line `lead`)? One short call,
+ * parsed by parseBinary.
+ */
+export async function disambiguate(
+  surface: string,
+  label: string | null,
+  entity: string,
+  lead: string,
+): Promise<boolean> {
+  const prompt =
+    `Is "${surface}" (context: ${label ?? "—"}) the same thing as ` +
+    `"${entity}" — ${lead}? Answer yes or no.`;
+  return parseBinary(await callLocal("route", { user: prompt }, { maxTokens: MAX_OUTPUT_TOKENS }));
+}
+
+/**
+ * Bounded subject-engagement gate: does this chunk engage with `entity` as a
+ * genuine SUBJECT — a topic/idea/person/project/thing the user is actually
+ * thinking about and discussing — rather than mentioning it only in passing?
+ * Feeds the CREATE gate's single-chunk stub path (NOT an ownership test).
+ */
+export async function engagesAsSubject(
+  entity: string,
+  chunkText: string,
+): Promise<boolean> {
+  const prompt =
+    `${chunkText}\n\n---\n` +
+    `Based on the note above, does it engage with "${entity}" as a genuine ` +
+    `SUBJECT — a topic, idea, person, project, or thing the user is actually ` +
+    `thinking about and discussing — rather than mentioning it only in passing? ` +
+    `Answer yes or no.`;
+  return parseBinary(await callLocal("route", { user: prompt }, { maxTokens: MAX_OUTPUT_TOKENS }));
+}
+
+// ---- CREATE gate (pure) ----------------------------------------------------
+
+export interface CreateStats {
+  /** Distinct chunks that routed to this candidate entity. */
+  routedChunks: number;
+  /** At least one routed chunk engages this entity as a genuine subject. */
+  subjectEngagement: boolean;
+}
+
+/**
+ * CREATE gate (Bucketing.md / Editorial_Guidelines.md): a subject earns its own
+ * article when it RECURS (≥ RECURRENCE_THRESHOLD routed chunks — "recurs in your
+ * thinking is notable enough") OR a chunk engages it as a genuine subject (stubs
+ * are encouraged for emerging topics). Otherwise it is CAPTURED — kept in its
+ * chunk, retrievable by search, never dropped. Pure — the model fills
+ * `subjectEngagement` upstream. NO ownership/usefulness test.
+ */
+export function createGate(stats: CreateStats): "create" | "capture" {
+  if (stats.routedChunks >= RECURRENCE_THRESHOLD) return "create";
+  if (stats.subjectEngagement) return "create";
+  return "capture";
+}
+
+// ---- fan-out accumulation --------------------------------------------------
+
+export type RouteAction = "routed" | "create" | "capture";
+
+export interface SurfaceRoute {
+  surface: string;
+  /** Resolved/candidate canonical, or null when no entity could be assigned. */
+  entity: string | null;
+  matched: MatchKind | "disambig" | "none";
+}
+
+/**
+ * Accumulates the chunk→entity fan-out across a run so the CREATE gate can see
+ * each candidate's full chunk count + subject-engagement signal before deciding
+ * create-vs-capture. Deterministic and model-free: callers route surfaces (via
+ * the resolver + optional model disambig) and `enqueue` the resolved canonicals.
+ */
+export class RouteAccumulator {
+  /** canonical → set of chunk ids routed to it (fan-in). */
+  private chunks = new Map<string, Set<string>>();
+  /** canonical → at least one chunk engages it as a genuine subject. */
+  private engaged = new Map<string, boolean>();
+  /** canonicals that already exist as known entities (resolver hits) vs minted. */
+  private known = new Set<string>();
+
+  constructor(knownCanonicals: Iterable<string> = []) {
+    for (const c of knownCanonicals) this.known.add(c);
+  }
+
+  /** Record that `chunkId` routes to `entity` (idempotent per chunk). */
+  enqueue(entity: string, chunkId: string, opts?: { subjectEngagement?: boolean }): void {
+    let set = this.chunks.get(entity);
+    if (!set) this.chunks.set(entity, (set = new Set()));
+    set.add(chunkId);
+    if (opts?.subjectEngagement) this.engaged.set(entity, true);
+    else if (!this.engaged.has(entity)) this.engaged.set(entity, false);
+  }
+
+  /** Stats for an entity (for the CREATE gate). */
+  stats(entity: string): CreateStats {
+    return {
+      routedChunks: this.chunks.get(entity)?.size ?? 0,
+      subjectEngagement: this.engaged.get(entity) ?? false,
+    };
+  }
+
+  /**
+   * Final decision per accumulated entity. Existing known entities are always
+   * `routed` (they already have a home — existing wins); minted candidates run
+   * the CREATE gate (create vs capture). Returns a stable, name-sorted report.
+   */
+  decisions(): { entity: string; action: RouteAction; stats: CreateStats }[] {
+    const out: { entity: string; action: RouteAction; stats: CreateStats }[] = [];
+    for (const entity of [...this.chunks.keys()].sort((a, b) => a.localeCompare(b))) {
+      const stats = this.stats(entity);
+      const action: RouteAction = this.known.has(entity) ? "routed" : createGate(stats);
+      out.push({ entity, action, stats });
+    }
+    return out;
+  }
+}
+
+// ---- chunk routing (deterministic resolve; model only on misses) -----------
+
+export interface RouteChunkOpts {
+  /** Shortlist width for the model disambiguation fallback. */
+  shortlistK?: number;
+  /** One-line lead per canonical, for the disambiguation prompt. */
+  leads?: Map<string, string>;
+  /** Disable the model fallback (deterministic-only routing) — misses become
+   *  `none`. Used by the pure tests + dry runs. */
+  noModel?: boolean;
+}
+
+/**
+ * Route ONE chunk's surfaces to canonicals, fanning out to every entity it
+ * touches. Resolver hits route deterministically; misses get a trigram shortlist
+ * disambiguated by the model (unless `noModel`). Returns one {@link SurfaceRoute}
+ * per surface (entity null when nothing matched — a CREATE candidate upstream).
+ */
+export async function routeChunkSurfaces(
+  resolver: EntityResolver,
+  surfaces: { surface: string }[],
+  label: string | null,
+  opts: RouteChunkOpts = {},
+): Promise<SurfaceRoute[]> {
+  const out: SurfaceRoute[] = [];
+  for (const { surface } of surfaces) {
+    const hit = resolver.match(surface);
+    if (hit) {
+      out.push({ surface, entity: hit.name, matched: hit.matched });
+      continue;
+    }
+    if (opts.noModel) {
+      out.push({ surface, entity: null, matched: "none" });
+      continue;
+    }
+    let routed: string | null = null;
+    for (const cand of trigramShortlist(resolver, surface, opts.shortlistK ?? 5)) {
+      const lead = opts.leads?.get(cand) ?? cand;
+      if (await disambiguate(surface, label, cand, lead)) {
+        routed = cand;
+        break;
+      }
+    }
+    out.push({ surface, entity: routed, matched: routed ? "disambig" : "none" });
+  }
+  return out;
+}
+
+/**
+ * Read a chunk's persisted entity surfaces (chunk_entities.surface_form). The
+ * routing input when extraction has already run; surfaces preserve their raw
+ * form so the resolver/model see what the user actually typed.
+ */
+export function chunkSurfaces(store: MemoryStore, chunkId: string): { surface: string }[] {
+  const rows = store.db
+    .query("SELECT surface_form FROM chunk_entities WHERE chunk_id = ? ORDER BY surface_form")
+    .all(chunkId) as { surface_form: string }[];
+  return rows.map((r) => ({ surface: r.surface_form }));
+}

package/src/memory/schedule.ts

@@ -1,13 +1,15 @@
-// mlx-bun memory — nightly scheduling via launchd.  ✅ REAL (the pipeline it
-// runs is the M1 stub, but install/remove/status here are fully functional).
+// mlx-bun memory — nightly scheduling via launchd.  ✅ REAL — install/remove/
+// status here are fully functional, and the job they run (`mlx-bun memory
+// synthesize`) now drives the real synthesis DAG (create + editorial wikify
+// sweep), not a stub.
 //
 // mlx-bun is macOS/Apple-silicon-only by identity, so launchd is the native
 // choice over crontab: it survives reboot, runs jobs missed while asleep on
 // next wake, and gives clean install/uninstall. `memory schedule` writes
 // ~/Library/LaunchAgents/com.mlx-bun.memory.plist (a StartCalendarInterval that
 // runs `mlx-bun memory synthesize`) and loads it; `unschedule` unloads + removes
-// it. Today that job is a no-op (synthesis is stubbed) — harmless; when M1 lands
-// the same schedule starts producing articles with no reconfiguration.
+// it. That job runs the full synthesis DAG and produces/updates articles on the
+// schedule with no further configuration.
 //
 // See docs/design/memory-system.md → "Scheduling (launchd)".