@remnic/core 9.19.0 → 9.20.0

package/src/meetings/fuse.test.ts

@@ -0,0 +1,208 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { DEFAULT_MEETINGS_CONFIG } from "./config.js";
+import { fuseMeeting } from "./fuse.js";
+import type {
+  DetectedMeeting,
+  MeetingActivitySnapshot,
+  MeetingsConfig,
+} from "./types.js";
+import type { FusionConversationInput, FusionSegmentInput } from "../wearables/fusion/types.js";
+
+const DATE = "2026-03-10";
+const WINDOW_START = "2026-03-10T14:00:00.000Z";
+const WINDOW_END = "2026-03-10T14:30:00.000Z";
+
+function config(overrides: Partial<MeetingsConfig> = {}): MeetingsConfig {
+  return { ...DEFAULT_MEETINGS_CONFIG, appPatterns: [...DEFAULT_MEETINGS_CONFIG.appPatterns], ...overrides };
+}
+
+function meeting(overrides: Partial<DetectedMeeting> = {}): DetectedMeeting {
+  return {
+    id: "mtg-2026-03-10-abcdef01",
+    date: DATE,
+    startUtc: WINDOW_START,
+    endUtc: WINDOW_END,
+    app: "Zoom",
+    detectionSource: "app+audio",
+    sources: ["desktop"],
+    ...overrides,
+  };
+}
+
+function seg(
+  speaker: string,
+  isSelf: boolean,
+  text: string,
+  startIso: string,
+  endIso?: string,
+): FusionSegmentInput {
+  return { speaker, isSelf, text, startIso, ...(endIso !== undefined ? { endIso } : {}) };
+}
+
+function conv(
+  source: string,
+  id: string,
+  startIso: string,
+  endIso: string,
+  segments: FusionSegmentInput[],
+): FusionConversationInput {
+  return { source, conversationId: id, startIso, endIso, segments };
+}
+
+function snap(overrides: Partial<MeetingActivitySnapshot> & { tsUtc: string; app: string }): MeetingActivitySnapshot {
+  return { ...overrides };
+}
+
+test("fusion prefers the higher-trust source in overlap regions and records corroboratedBy without duplicating text", () => {
+  const fused = fuseMeeting(
+    {
+      meeting: meeting(),
+      conversations: [
+        conv("desktop", "d1", "2026-03-10T14:05:00.000Z", "2026-03-10T14:07:00.000Z", [
+          seg("Jane", false, "hello everyone", "2026-03-10T14:05:00.000Z", "2026-03-10T14:05:04.000Z"),
+          seg("Me (you)", true, "lets begin", "2026-03-10T14:06:00.000Z"),
+        ]),
+        conv("pendant", "p1", "2026-03-10T14:05:00.000Z", "2026-03-10T14:05:10.000Z", [
+          seg("Jane", false, "hello everyone", "2026-03-10T14:05:00.000Z", "2026-03-10T14:05:04.000Z"),
+        ]),
+      ],
+    },
+    config(),
+    { sourceTrust: { desktop: 0.9, pendant: 0.6 } },
+  );
+
+  // Same utterance recorded by two sources → ONE fused segment (no dup).
+  const helloSegments = fused.transcript.filter((s) => s.text === "hello everyone");
+  assert.equal(helloSegments.length, 1);
+  // Higher-trust source won the overlapping region.
+  assert.equal(helloSegments[0]?.provenance.source, "desktop");
+  assert.equal(helloSegments[0]?.provenance.reason, "higher-trust");
+  // The out-voted source is recorded as corroboration.
+  assert.deepEqual(fused.corroboratedBy, ["pendant"]);
+  assert.deepEqual(fused.sources, ["desktop", "pendant"]);
+  // Jane merged + wearer utterance = two segments total; wearer is not an attendee.
+  assert.equal(fused.transcript.length, 2);
+  assert.deepEqual(fused.attendees, ["Jane"]);
+});
+
+test("screen context includes a >=20s dwell and omits a 5s alt-tab; meeting-app text feeds excerpts", () => {
+  const fused = fuseMeeting(
+    {
+      meeting: meeting(),
+      conversations: [
+        conv("desktop", "d1", "2026-03-10T14:05:00.000Z", "2026-03-10T14:12:00.000Z", [
+          seg("Jane", false, "agenda item one", "2026-03-10T14:10:00.000Z"),
+        ]),
+      ],
+      activity: [
+        snap({ tsUtc: "2026-03-10T14:05:00.000Z", app: "Preview", title: "Q3-roadmap.pdf", text: "Q3 roadmap draft" }),
+        snap({ tsUtc: "2026-03-10T14:05:25.000Z", app: "Notes", title: "scratch" }), // Preview dwell 25s → include; Notes starts
+        snap({ tsUtc: "2026-03-10T14:05:30.000Z", app: "Preview", title: "Q3-roadmap.pdf" }), // Notes dwell 5s → exclude
+        snap({ tsUtc: "2026-03-10T14:10:00.000Z", app: "Zoom", text: "Jane: agenda item one" }), // meeting-app → excerpt
+      ],
+    },
+    config(),
+  );
+
+  assert.equal(fused.snapshotCount, 4);
+  const apps = fused.screenContext.map((e) => e.app);
+  assert.ok(apps.includes("Preview"), "Preview dwell should be in the timeline");
+  assert.ok(!apps.includes("Notes"), "5s alt-tab must be excluded");
+  const preview = fused.screenContext.find((e) => e.app === "Preview");
+  assert.equal(preview?.label, "Preview: Q3-roadmap.pdf");
+  assert.ok(preview !== undefined && preview.dwellSeconds >= 20);
+  assert.ok(fused.contextExcerpts.includes("Jane: agenda item one"));
+});
+
+test("context excerpts respect maxContextChars", () => {
+  const fused = fuseMeeting(
+    {
+      meeting: meeting(),
+      conversations: [],
+      activity: [
+        snap({ tsUtc: "2026-03-10T14:01:00.000Z", app: "Zoom", text: "aaaa" }),
+        snap({ tsUtc: "2026-03-10T14:02:00.000Z", app: "Zoom", text: "bbbb" }),
+        snap({ tsUtc: "2026-03-10T14:03:00.000Z", app: "Zoom", text: "cccc" }),
+      ],
+    },
+    config({ maxContextChars: 8 }),
+  );
+  // 4-char excerpts, cap 8 → exactly two fit.
+  assert.deepEqual(fused.contextExcerpts, ["aaaa", "bbbb"]);
+});
+
+test("degradation — no activity yields an empty screen context but a full transcript", () => {
+  const fused = fuseMeeting(
+    {
+      meeting: meeting({ detectionSource: "audio", app: undefined }),
+      conversations: [
+        conv("limitless", "l1", "2026-03-10T14:05:00.000Z", "2026-03-10T14:20:00.000Z", [
+          seg("Jane", false, "quarterly numbers", "2026-03-10T14:05:00.000Z"),
+        ]),
+      ],
+    },
+    config(),
+  );
+  assert.equal(fused.snapshotCount, 0);
+  assert.deepEqual(fused.screenContext, []);
+  assert.deepEqual(fused.contextExcerpts, []);
+  assert.equal(fused.transcript.length, 1);
+  assert.deepEqual(fused.sources, ["limitless"]);
+});
+
+test("degradation — no audio yields an empty transcript without crashing", () => {
+  const fused = fuseMeeting(
+    { meeting: meeting(), conversations: [] },
+    config(),
+  );
+  assert.deepEqual(fused.transcript, []);
+  assert.deepEqual(fused.sources, []);
+  assert.deepEqual(fused.corroboratedBy, []);
+  assert.deepEqual(fused.attendees, []);
+});
+
+test("segments outside the half-open window are clipped out", () => {
+  const fused = fuseMeeting(
+    {
+      meeting: meeting(),
+      conversations: [
+        conv("desktop", "d1", "2026-03-10T13:50:00.000Z", "2026-03-10T14:35:00.000Z", [
+          seg("Jane", false, "before start", "2026-03-10T13:59:59.000Z"),
+          seg("Jane", false, "in window", "2026-03-10T14:05:00.000Z"),
+          seg("Jane", false, "at end boundary", WINDOW_END), // half-open: end excluded
+        ]),
+      ],
+    },
+    config(),
+  );
+  const texts = fused.transcript.map((s) => s.text);
+  assert.deepEqual(texts, ["in window"]);
+});
+
+test("throws on an invalid meeting window", () => {
+  assert.throws(
+    () => fuseMeeting({ meeting: meeting({ endUtc: WINDOW_START }), conversations: [] }, config()),
+    /invalid window/,
+  );
+});
+
+test("a lone trailing other-app snapshot is not inflated to the meeting end", () => {
+  const fused = fuseMeeting(
+    {
+      meeting: meeting(),
+      conversations: [
+        conv("desktop", "d1", "2026-03-10T14:05:00.000Z", "2026-03-10T14:12:00.000Z", [
+          seg("Jane", false, "agenda", "2026-03-10T14:06:00.000Z"),
+        ]),
+      ],
+      // A single Notes snapshot 1 min before the window end. With no later
+      // snapshot, the trailing run must NOT count dwell up to the meeting end.
+      activity: [snap({ tsUtc: "2026-03-10T14:29:00.000Z", app: "Notes", title: "scratch" })],
+    },
+    config(),
+  );
+  assert.equal(fused.snapshotCount, 1);
+  assert.deepEqual(fused.screenContext, [], "a lone trailing snapshot has zero observed dwell");
+});

package/src/meetings/fuse.ts

@@ -0,0 +1,297 @@
+/**
+ * Meeting fusion (issue #1900, Phase 4 slice 2).
+ *
+ * For a detected meeting window `[startUtc, endUtc)` (half-open, AGENTS.md §23),
+ * fuse the concurrent signals into a screen-aware `FusedMeeting`:
+ *
+ *   1. Transcript — clip every wearable source's segments to the window and run
+ *      them through the SHARED wearables reconciliation (`fuseCluster`). Higher-
+ *      `sourceTrust` text wins overlapping regions and the out-voted sources are
+ *      recorded per segment; this module never re-implements alignment/dedup —
+ *      the repo rule is "extend the shared fusion module, never fork it".
+ *   2. Screen context — other-app foreground dwell within the window, kept only
+ *      when it lasts `contextDwellSeconds`, plus deduped on-screen text excerpts
+ *      capped at `maxContextChars`.
+ *   3. Attendees — distinct non-wearer speaker labels from the fused transcript
+ *      (already resolved through the wearables speaker registry upstream).
+ *
+ * Pure and deterministic: same inputs ⇒ same `FusedMeeting`.
+ */
+
+import { fuseCluster } from "../wearables/fusion/reconcile.js";
+import type {
+  FusionConversationInput,
+  FusionSegmentInput,
+} from "../wearables/fusion/types.js";
+import type {
+  FusedMeeting,
+  MeetingActivitySnapshot,
+  MeetingBuildInput,
+  MeetingScreenContextEvent,
+  MeetingsConfig,
+} from "./types.js";
+
+/** Per-run tuning that mirrors the wearables fusion knobs. */
+export interface MeetingFusionOptions {
+  /** Per-source trust priors handed to reconciliation. */
+  sourceTrust?: Record<string, number>;
+  /** Max drift (ms) for two segments to align across sources. */
+  windowToleranceMs?: number;
+}
+
+const SORT_STR = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+/** `HH:MM` in UTC for a parseable ISO instant (mirrors the day-store fallback). */
+function formatClockUtc(ms: number): string {
+  return new Date(ms).toISOString().slice(11, 16);
+}
+
+/** Overlap of two half-open [start,end) windows in ms (0 when disjoint). */
+function overlapMs(aStart: number, aEnd: number, bStart: number, bEnd: number): number {
+  return Math.max(0, Math.min(aEnd, bEnd) - Math.max(aStart, bStart));
+}
+
+/** Whether a segment falls in the half-open window; null when it carries no
+ *  parseable start (the caller decides via the conversation-level overlap). */
+function segmentInWindow(
+  seg: FusionSegmentInput,
+  windowStartMs: number,
+  windowEndMs: number,
+): boolean | null {
+  const startMs = seg.startIso === undefined ? NaN : Date.parse(seg.startIso);
+  if (Number.isNaN(startMs)) return null;
+  const endParsed = seg.endIso === undefined ? NaN : Date.parse(seg.endIso);
+  const endMs = Number.isNaN(endParsed) ? startMs : endParsed;
+  if (endMs === startMs) return startMs >= windowStartMs && startMs < windowEndMs;
+  return overlapMs(startMs, endMs, windowStartMs, windowEndMs) > 0;
+}
+
+/** Clip one conversation to the window, keeping only in-window segments. */
+function clipConversation(
+  conv: FusionConversationInput,
+  windowStartMs: number,
+  windowEndMs: number,
+): FusionConversationInput | null {
+  const convStart = Date.parse(conv.startIso);
+  const convEnd = conv.endIso === undefined ? convStart : Date.parse(conv.endIso);
+  const convOverlaps =
+    Number.isFinite(convStart) &&
+    overlapMs(convStart, Number.isFinite(convEnd) ? convEnd : convStart, windowStartMs, windowEndMs) > 0;
+
+  const kept: FusionSegmentInput[] = [];
+  let earliestStart: number | undefined;
+  let earliestIso: string | undefined;
+  let latestEnd: number | undefined;
+  let latestIso: string | undefined;
+  for (const seg of conv.segments) {
+    const decision = segmentInWindow(seg, windowStartMs, windowEndMs);
+    // Untimed segments ride along only when the conversation itself overlaps.
+    if (decision === false || (decision === null && !convOverlaps)) continue;
+    kept.push(seg);
+    if (seg.startIso !== undefined) {
+      const s = Date.parse(seg.startIso);
+      if (Number.isFinite(s) && (earliestStart === undefined || s < earliestStart)) {
+        earliestStart = s;
+        earliestIso = seg.startIso;
+      }
+      const endIso = seg.endIso ?? seg.startIso;
+      const e = Date.parse(endIso);
+      if (Number.isFinite(e) && (latestEnd === undefined || e > latestEnd)) {
+        latestEnd = e;
+        latestIso = endIso;
+      }
+    }
+  }
+  if (kept.length === 0) return null;
+  return {
+    source: conv.source,
+    conversationId: conv.conversationId,
+    ...(conv.title !== undefined ? { title: conv.title } : {}),
+    ...(conv.summary !== undefined ? { summary: conv.summary } : {}),
+    startIso: earliestIso ?? conv.startIso,
+    ...(latestIso !== undefined ? { endIso: latestIso } : conv.endIso !== undefined ? { endIso: conv.endIso } : {}),
+    segments: kept,
+  };
+}
+
+/** Strip the URL scheme for a compact screen-context label. */
+function shortenUrl(url: string): string {
+  return url.replace(/^[a-z]+:\/\//i, "");
+}
+
+function contextLabel(snap: MeetingActivitySnapshot): string {
+  if (snap.url !== undefined && snap.url.length > 0) return `${snap.app}: ${shortenUrl(snap.url)}`;
+  if (snap.title !== undefined && snap.title.length > 0) return `${snap.app}: ${snap.title}`;
+  return snap.app;
+}
+
+/** True when a snapshot is the meeting app itself (captions/chat/participants),
+ *  not other context. Matches the meeting's app or any configured app pattern. */
+function isMeetingAppSnapshot(
+  snap: MeetingActivitySnapshot,
+  meetingApp: string | undefined,
+  appPatterns: readonly string[],
+): boolean {
+  const hay = `${snap.app} ${snap.title ?? ""} ${snap.url ?? ""}`.toLowerCase();
+  if (meetingApp !== undefined && meetingApp.length > 0 && hay.includes(meetingApp.toLowerCase())) {
+    return true;
+  }
+  for (const pattern of appPatterns) {
+    if (pattern.length > 0 && hay.includes(pattern.toLowerCase())) return true;
+  }
+  return false;
+}
+
+const MEETING_APP_KEY = "\u0000meeting-app";
+
+interface ScreenContextResult {
+  events: MeetingScreenContextEvent[];
+  excerpts: string[];
+  snapshotCount: number;
+}
+
+/**
+ * Build the screen-context timeline + excerpts from the day's activity clipped
+ * to the meeting window. Consecutive snapshots sharing a foreground key form a
+ * dwell run whose length is bounded by the NEXT foreground change (or the
+ * window end); other-app runs are emitted only when the dwell clears
+ * `contextDwellSeconds`, so a brief alt-tab is dropped and a lingered doc is
+ * kept. Meeting-app snapshots never enter the timeline but feed excerpts.
+ */
+function buildScreenContext(
+  activity: readonly MeetingActivitySnapshot[],
+  windowStartMs: number,
+  windowEndMs: number,
+  meetingApp: string | undefined,
+  config: MeetingsConfig,
+): ScreenContextResult {
+  const win = activity
+    .map((snap) => ({ snap, ms: Date.parse(snap.tsUtc) }))
+    .filter((entry) => Number.isFinite(entry.ms) && entry.ms >= windowStartMs && entry.ms < windowEndMs)
+    .sort((a, b) => a.ms - b.ms || SORT_STR(a.snap.app, b.snap.app));
+
+  const keyOf = (snap: MeetingActivitySnapshot): string =>
+    isMeetingAppSnapshot(snap, meetingApp, config.appPatterns)
+      ? MEETING_APP_KEY
+      : `${snap.app}\u0000${snap.url ?? snap.title ?? ""}`;
+
+  const events: MeetingScreenContextEvent[] = [];
+  const includedText: string[] = [];
+
+  let runStartIdx = 0;
+  while (runStartIdx < win.length) {
+    const key = keyOf(win[runStartIdx]!.snap);
+    let runEndIdx = runStartIdx + 1;
+    while (runEndIdx < win.length && keyOf(win[runEndIdx]!.snap) === key) runEndIdx++;
+    const runStartMs = win[runStartIdx]!.ms;
+    // A run's dwell ends at the NEXT foreground change (next different-key
+    // snapshot). The trailing run has no observed switch-away, so bound it by the
+    // LAST snapshot in the run — never inflate to the meeting end (a lone trailing
+    // alt-tab would otherwise look like it dwelled until the meeting ended).
+    const runEndMs = runEndIdx < win.length ? win[runEndIdx]!.ms : win[runEndIdx - 1]!.ms;
+    const dwellSeconds = Math.floor((runEndMs - runStartMs) / 1000);
+    const head = win[runStartIdx]!.snap;
+
+    const isMeetingApp = key === MEETING_APP_KEY;
+    if (isMeetingApp) {
+      // Captions / chat / participant text visible on the meeting app itself.
+      for (let i = runStartIdx; i < runEndIdx; i++) {
+        const text = win[i]!.snap.text;
+        if (text !== undefined && text.trim().length > 0) includedText.push(text.trim());
+      }
+    } else if (dwellSeconds >= config.contextDwellSeconds) {
+      events.push({
+        tsUtc: new Date(runStartMs).toISOString(),
+        clock: formatClockUtc(runStartMs),
+        app: head.app,
+        label: contextLabel(head),
+        dwellSeconds,
+      });
+      for (let i = runStartIdx; i < runEndIdx; i++) {
+        const text = win[i]!.snap.text;
+        if (text !== undefined && text.trim().length > 0) includedText.push(text.trim());
+      }
+    }
+    runStartIdx = runEndIdx;
+  }
+
+  // Dedup excerpts (first occurrence wins) and cap total characters.
+  const excerpts: string[] = [];
+  const seen = new Set<string>();
+  let used = 0;
+  for (const text of includedText) {
+    if (seen.has(text)) continue;
+    if (used + text.length > config.maxContextChars) break;
+    seen.add(text);
+    excerpts.push(text);
+    used += text.length;
+  }
+
+  return { events, excerpts, snapshotCount: win.length };
+}
+
+/** Fuse one detected meeting's transcript + screen context into a FusedMeeting. */
+export function fuseMeeting(
+  input: MeetingBuildInput,
+  config: MeetingsConfig,
+  options: MeetingFusionOptions = {},
+): FusedMeeting {
+  const windowStartMs = Date.parse(input.meeting.startUtc);
+  const windowEndMs = Date.parse(input.meeting.endUtc);
+  if (!Number.isFinite(windowStartMs) || !Number.isFinite(windowEndMs) || windowEndMs <= windowStartMs) {
+    throw new RangeError(
+      `meetings: meeting ${input.meeting.id} has an invalid window [${input.meeting.startUtc}, ${input.meeting.endUtc}).`,
+    );
+  }
+
+  const clipped: FusionConversationInput[] = [];
+  for (const conv of input.conversations) {
+    const clip = clipConversation(conv, windowStartMs, windowEndMs);
+    if (clip !== null) clipped.push(clip);
+  }
+
+  const fused =
+    clipped.length > 0
+      ? fuseCluster(clipped, {
+          ...(options.sourceTrust !== undefined ? { sourceTrust: options.sourceTrust } : {}),
+          ...(options.windowToleranceMs !== undefined ? { windowToleranceMs: options.windowToleranceMs } : {}),
+        })
+      : { sources: [], speakers: [], segments: [], disagreements: [], startIso: input.meeting.startUtc };
+
+  const corroborated = new Set<string>();
+  for (const segment of fused.segments) {
+    for (const alt of segment.provenance.alternatives) {
+      // Suppress a source only as corroborator of the SAME segment it won
+      // (a winner is never its own alternative, so this is a guard). A source
+      // that WON one segment but lost another still corroborates the one it
+      // lost — deleting it globally erased legitimate multi-device corroboration
+      // and dropped the summary/fact trust boost.
+      if (alt.source === segment.provenance.source) continue;
+      corroborated.add(alt.source);
+    }
+  }
+
+  const attendees = new Set<string>();
+  for (const speaker of fused.speakers) {
+    if (!speaker.isSelf) attendees.add(speaker.label);
+  }
+
+  const screen = buildScreenContext(
+    input.activity ?? [],
+    windowStartMs,
+    windowEndMs,
+    input.meeting.app,
+    config,
+  );
+
+  return {
+    attendees: [...attendees].sort(SORT_STR),
+    sources: [...fused.sources].sort(SORT_STR),
+    corroboratedBy: [...corroborated].sort(SORT_STR),
+    screenContext: screen.events,
+    contextExcerpts: screen.excerpts,
+    transcript: fused.segments,
+    speakers: fused.speakers,
+    snapshotCount: screen.snapshotCount,
+  };
+}

package/src/meetings/index.ts

@@ -1,8 +1,18 @@
 /**
  * Public entry for the retrospective meeting-detection subsystem (issue #1900):
- * pure detection over a day's already-ingested audio + app-span signals.
+ * the deterministic engine — detection, fusion, record store, day build, and the
+ * CLI over a day's already-ingested audio + app-span signals — plus the
+ * memory-generation SEAM the builder depends on. The concrete memory generator
+ * and the day-source/service/scheduler wiring ship in the surface slice.
  * Re-exported from the package root (`src/index.ts`) so consumers import it from
  * `@remnic/core`, matching the wearables/activity subsystems' surfacing.
  */
 export * from "./types.js";
 export * from "./detect.js";
+export * from "./config.js";
+export * from "./errors.js";
+export * from "./fuse.js";
+export * from "./store.js";
+export * from "./memory-generator.js";
+export * from "./build.js";
+export * from "./cli.js";

package/src/meetings/memory-generator.ts

@@ -0,0 +1,116 @@
+/**
+ * Meeting memory-generation SEAM (issue #1900 — engine/memory decouple).
+ *
+ * Engine-layer boundary between the deterministic meeting builder and the
+ * memory-generation layer. `MeetingsBuilder` (detect/fuse/store/build) depends
+ * ONLY on `MeetingMemoryGenerator` declared here — never on `memory-gen.ts` — so
+ * the deterministic engine carries zero dependency on episode/fact generation
+ * and ships in its own scope-budgeted PR. The concrete generator lives in
+ * `memory-gen.ts` behind `createMeetingMemoryGenerator`, which implements this
+ * interface by driving the existing episode/fact/retract logic.
+ */
+
+import type { MemoryWriteResult } from "../index.js";
+import type { ImportanceScore, MemoryStatus } from "../types.js";
+import type { SealedMemoryEnvelope } from "../write-envelope.js";
+import type { MeetingRecord } from "./types.js";
+
+/**
+ * Narrow writer interface satisfied by `StorageManager` — the same sealed
+ * write entry point the wearables generator uses, so meeting memories inherit
+ * encrypted-at-rest + atomic write + dedup without this module knowing the key.
+ */
+export interface MeetingMemoryWriter {
+  writeSealedMemory(
+    envelope: SealedMemoryEnvelope,
+    extras: {
+      importance?: ImportanceScore;
+      contentHashSource?: string;
+      status?: MemoryStatus;
+      memoryKind?: "episode" | "note" | "box" | "dream" | "procedural";
+    },
+  ): Promise<MemoryWriteResult>;
+  /**
+   * True when an active/pending memory whose frontmatter `source` equals
+   * `source` already carries this exact content. Meeting memories are episodes
+   * (`moment`) and decisions/commitments (`decision`/`commitment`) — categories
+   * the storage fact-hash index does NOT cover — so idempotency is a
+   * source-scoped content scan, mirroring the wearables writer, NOT
+   * `hasFactContentHash` (fact-only; always false here → duplicates on rebuild).
+   */
+  hasMemoryFromSource(source: string, content: string): Promise<boolean>;
+  /**
+   * Retire (invalidate) every memory whose frontmatter `source` equals `source`.
+   * Returns the count retired. Used to reconcile away a removed meeting's
+   * episode/summary memories so recall never surfaces a meeting `show` can't load.
+   */
+  retireMemoriesFromSource(source: string): Promise<number>;
+}
+
+/** Result of generating episode memories for a day's meetings. */
+export interface MeetingEpisodeGenResult {
+  /** Episodes newly written. */
+  written: number;
+  /** Episodes skipped because an identical one already existed. */
+  skipped: number;
+}
+
+/** Day-level aggregate of the trust-gated summary/fact layer across records. */
+export interface MeetingsDayFactGenResult {
+  /** True when the LLM extractor ran for at least one record. */
+  llmInvoked: boolean;
+  /** Facts written active. */
+  active: number;
+  /** Facts queued for review (pending_review). */
+  review: number;
+  /** Candidates/summaries dropped below the trust bar or judge-rejected. */
+  dropped: number;
+  /** Candidates/summaries skipped because an identical memory already existed. */
+  skipped: number;
+  /** Count of records whose summary memory was written. */
+  summariesWritten: number;
+}
+
+/**
+ * Outcome the memory generator returns to the builder after a day's records are
+ * built and persisted. Counts feed the day-build summary; `reindexNeeded` folds
+ * the "reindex when new episodes/facts were written even if no record changed"
+ * rule so the builder never reaches into the memory layer to decide it.
+ */
+export interface MeetingMemoryOutcome {
+  /** Episode-memory counts, present only when records were built. */
+  episodes?: MeetingEpisodeGenResult;
+  /** Trust-gated summary/fact counts, present only when summary deps ran. */
+  facts?: MeetingsDayFactGenResult;
+  /** True when newly written memories require an isolated reindex. */
+  reindexNeeded: boolean;
+  /** Non-fatal warnings raised while generating memories. */
+  warnings: readonly string[];
+}
+
+/**
+ * Seam the deterministic builder depends on. Invoked once per day build after
+ * the record-store writes with, for the day:
+ *   - `built`       — every record composed this build (new, updated, unchanged).
+ *   - `removedIds`  — stale ids the rebuild reconciled away (retract memories).
+ *   - `unchangedIds`— built ids whose stored `contentHash` was IDENTICAL this
+ *                     build (nothing rewritten). The generator SKIPS all
+ *                     episode/summary/fact work for these: an idempotent rebuild
+ *                     must not re-invoke the LLM or duplicate memories.
+ *   - `updatedIds`  — built ids that existed before AND were rewritten this build
+ *                     (same id, changed `contentHash`). The generator REFRESHES
+ *                     them: retract the stale episode/summary memories for that
+ *                     source, then regenerate from the new record.
+ * Ids not in `unchangedIds` or `updatedIds` are newly built — generated fresh
+ * with no retract. The three id sets are disjoint subsets of `built`. The
+ * implementation reports the counts + reindex signal the builder folds into its
+ * day summary.
+ */
+export interface MeetingMemoryGenerator {
+  onRecordsBuilt(input: {
+    built: readonly MeetingRecord[];
+    removedIds: readonly string[];
+    unchangedIds: readonly string[];
+    updatedIds: readonly string[];
+  }): Promise<MeetingMemoryOutcome>;
+}