@remnic/core 10.0.11 → 10.0.13

package/src/compounding/weekly-scheduler.test.ts

@@ -0,0 +1,426 @@
+/**
+ * Daemon weekly compounding run: once per completed ISO week, skip only when
+ * a scheduled run already completed that week, and catch up the missed week
+ * after a restart.
+ */
+
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { parseConfig } from "../config.js";
+import { initLogger, resetLogger } from "../logger.js";
+import type { NamespaceCatalog } from "../namespaces/catalog.js";
+import type { NamespaceSearchRouter } from "../namespaces/search.js";
+import { MaintenanceScheduler } from "../orchestration/maintenance.js";
+import type { SearchBackend } from "../search/port.js";
+import { CompoundingEngine } from "./engine.js";
+import { queueWeeklySynthesis } from "./weekly-synthesis-queue.js";
+import { isIsoWeekId, isoWeekId, msUntilNextIsoWeek, previousIsoWeekId } from "./iso-week.js";
+import {
+  type CompoundingWeeklySchedulerOptions,
+  compoundingWeeklyDoneMarkerPath,
+  compoundingWeeklyReportPath,
+  startCompoundingWeeklyScheduler,
+} from "./weekly-scheduler.js";
+
+const QUIET = { info() {}, warn() {}, debug() {} };
+
+function fixedClock(iso: string): () => Date {
+  const value = new Date(iso);
+  return () => new Date(value.getTime());
+}
+
+function fakeTimers() {
+  const armed: Array<{ fn: () => void; ms: number; unrefd: boolean }> = [];
+  const cleared: unknown[] = [];
+  return {
+    armed,
+    cleared,
+    setTimer: (fn: () => void, ms: number) => {
+      const handle = {
+        fn,
+        ms,
+        unrefd: false,
+        unref() {
+          this.unrefd = true;
+        },
+      };
+      armed.push(handle);
+      return handle;
+    },
+    clearTimer: (handle: unknown) => {
+      cleared.push(handle);
+    },
+  };
+}
+
+function startFor(memoryDir: string, overrides: Partial<CompoundingWeeklySchedulerOptions> & { now: () => Date }) {
+  const timers = fakeTimers();
+  const handle = startCompoundingWeeklyScheduler({
+    memoryDir,
+    synthesizeWeekly: async () => undefined,
+    log: QUIET,
+    setTimer: timers.setTimer,
+    clearTimer: timers.clearTimer,
+    ...overrides,
+  });
+  return { handle, timers };
+}
+
+test("iso week ids follow the Thursday rule across the year boundary", () => {
+  assert.equal(isoWeekId(new Date("2026-01-01T00:00:00.000Z")), "2026-W01");
+  assert.equal(previousIsoWeekId(new Date("2026-01-01T00:00:00.000Z")), "2025-W52");
+  assert.equal(isoWeekId(new Date("2026-01-05T00:00:00.000Z")), "2026-W02");
+  assert.equal(previousIsoWeekId(new Date("2026-01-05T12:00:00.000Z")), "2026-W01");
+  assert.equal(isIsoWeekId("2026-W01"), true);
+  assert.equal(isIsoWeekId("2026-W00"), false);
+  assert.equal(isIsoWeekId("2026-W54"), false);
+  assert.equal(isIsoWeekId("../W01"), false);
+  assert.equal(isIsoWeekId("2026-W1"), false);
+});
+
+test("next Monday delay is one week when already on the Monday boundary", () => {
+  const monday = new Date("2026-03-16T00:00:00.000Z");
+  assert.equal(monday.getUTCDay(), 1);
+  assert.equal(msUntilNextIsoWeek(monday), 7 * 86_400_000);
+  const sundayEvening = new Date("2026-03-15T23:00:00.000Z");
+  assert.equal(msUntilNextIsoWeek(sundayEvening), 60 * 60 * 1000);
+});
+
+test("startup synthesizes the completed ISO week and arms an unref'd boundary timer", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-weekly-cron-"));
+  const now = fixedClock("2026-03-18T12:00:00.000Z");
+  const calls: string[] = [];
+  try {
+    const { handle, timers } = startFor(memoryDir, {
+      now,
+      synthesizeWeekly: async (weekId) => {
+        calls.push(weekId);
+      },
+    });
+    await handle.whenIdle();
+    assert.deepEqual(calls, [previousIsoWeekId(now())]);
+    assert.notEqual(calls[0], isoWeekId(now()));
+    assert.equal(timers.armed.length, 1);
+    assert.equal(timers.armed[0]?.unrefd, true);
+    assert.equal(timers.armed[0]?.ms, msUntilNextIsoWeek(now()));
+    await handle.stop();
+    assert.equal(timers.cleared.length, 1);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a week a scheduled run completed is skipped, including after a restart", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-weekly-cron-"));
+  const now = fixedClock("2026-03-18T12:00:00.000Z");
+  const weekId = previousIsoWeekId(now());
+  const calls: string[] = [];
+  const synthesizeWeekly = async (id: string) => {
+    calls.push(id);
+    const report = compoundingWeeklyReportPath(memoryDir, id);
+    await mkdir(path.dirname(report), { recursive: true });
+    await writeFile(report, `# ${id}\n`, "utf8");
+  };
+  try {
+    const first = startFor(memoryDir, { now, synthesizeWeekly });
+    await first.handle.whenIdle();
+    await first.handle.stop();
+    assert.deepEqual(calls, [weekId]);
+
+    const restarted = startFor(memoryDir, { now, synthesizeWeekly });
+    await restarted.handle.whenIdle();
+    await restarted.handle.stop();
+    assert.deepEqual(calls, [weekId], "restart must not re-run a week the scheduler completed");
+    assert.equal(await readFile(compoundingWeeklyReportPath(memoryDir, weekId), "utf8"), `# ${weekId}\n`);
+    await stat(compoundingWeeklyDoneMarkerPath(memoryDir, weekId));
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a manual access-surface report does not suppress the scheduled run", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-weekly-cron-"));
+  const now = fixedClock("2026-03-18T12:00:00.000Z");
+  const weekId = previousIsoWeekId(now());
+  const calls: string[] = [];
+  try {
+    // A manual compounding_weekly_synthesize call wrote the week's report
+    // while that week was still in progress; no scheduler marker exists.
+    const report = compoundingWeeklyReportPath(memoryDir, weekId);
+    await mkdir(path.dirname(report), { recursive: true });
+    await writeFile(report, `# ${weekId}\n`, "utf8");
+
+    const { handle } = startFor(memoryDir, {
+      now,
+      synthesizeWeekly: async (id) => {
+        calls.push(id);
+      },
+    });
+    await handle.whenIdle();
+    await handle.stop();
+    assert.deepEqual(calls, [weekId], "the report file alone must not satisfy the due check");
+    await stat(compoundingWeeklyDoneMarkerPath(memoryDir, weekId));
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a missed week is caught up once and older gaps are not backfilled", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-weekly-cron-"));
+  let now = new Date("2026-04-08T12:00:00.000Z");
+  const calls: string[] = [];
+  const synthesizeWeekly = async (id: string) => {
+    calls.push(id);
+    const report = compoundingWeeklyReportPath(memoryDir, id);
+    await mkdir(path.dirname(report), { recursive: true });
+    await writeFile(report, `# ${id}\n`, "utf8");
+  };
+  try {
+    const first = startFor(memoryDir, { now: () => now, synthesizeWeekly });
+    await first.handle.whenIdle();
+    await first.handle.stop();
+
+    const completed = previousIsoWeekId(now);
+    now = new Date(now.getTime() + 14 * 86_400_000);
+    const missed = previousIsoWeekId(new Date(now.getTime() - 7 * 86_400_000));
+    const due = previousIsoWeekId(now);
+    assert.notEqual(completed, missed);
+    assert.notEqual(missed, due);
+
+    const restarted = startFor(memoryDir, { now: () => now, synthesizeWeekly });
+    await restarted.handle.whenIdle();
+    await restarted.handle.stop();
+    assert.deepEqual(calls, [completed, due]);
+    assert.equal(calls.includes(missed), false);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a failed tick retries on the next boundary and a stopped timer does not run", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-weekly-cron-"));
+  const now = fixedClock("2026-03-18T12:00:00.000Z");
+  let fail = true;
+  const calls: string[] = [];
+  try {
+    const { handle, timers } = startFor(memoryDir, {
+      now,
+      synthesizeWeekly: async (weekId) => {
+        calls.push(weekId);
+        if (fail) throw new Error("synthesis unavailable");
+      },
+    });
+    await handle.whenIdle();
+    assert.equal(calls.length, 1);
+    fail = false;
+    timers.armed[0]?.fn();
+    await handle.whenIdle();
+    assert.equal(calls.length, 2);
+    await handle.stop();
+    const afterStop = calls.length;
+    timers.armed[0]?.fn();
+    await handle.whenIdle();
+    assert.equal(calls.length, afterStop);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a failed week is retried after the ISO boundary, before the newly due week", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-weekly-cron-"));
+  let now = new Date("2026-03-18T12:00:00.000Z");
+  let fail = true;
+  const calls: string[] = [];
+  try {
+    const { handle, timers } = startFor(memoryDir, {
+      now: () => now,
+      synthesizeWeekly: async (weekId) => {
+        calls.push(weekId);
+        if (fail) throw new Error("synthesis unavailable");
+      },
+    });
+    await handle.whenIdle();
+    const failed = previousIsoWeekId(now);
+    now = new Date(now.getTime() + 7 * 86_400_000);
+    const due = previousIsoWeekId(now);
+    assert.notEqual(failed, due);
+    fail = false;
+    timers.armed.at(-1)?.fn();
+    await handle.whenIdle();
+    assert.deepEqual(calls, [failed, failed, due]);
+    await handle.stop();
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a later artifact failure does not leave the weekly report marker", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-weekly-cron-"));
+  const weekId = previousIsoWeekId(new Date("2026-03-18T12:00:00.000Z"));
+  try {
+    await mkdir(path.join(memoryDir, "compounding", "mistakes.json"), { recursive: true });
+    const engine = new CompoundingEngine(parseConfig({ memoryDir, qmdEnabled: false, compoundingEnabled: true }));
+    await assert.rejects(() => engine.synthesizeWeekly({ weekId }));
+    await assert.rejects(
+      () => stat(compoundingWeeklyReportPath(memoryDir, weekId)),
+      (error: unknown) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT"
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("an overlapping tick coalesces into one follow-up run", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-weekly-cron-"));
+  let release: (() => void) | undefined;
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  let calls = 0;
+  try {
+    const { handle } = startFor(memoryDir, {
+      now: fixedClock("2026-03-18T12:00:00.000Z"),
+      // Every tick reports the week as not yet done, so the follow-up run
+      // the coalescing produces is observable as a second synthesis.
+      weekDone: async () => false,
+      synthesizeWeekly: async () => {
+        calls += 1;
+        if (calls === 1) await gate;
+      },
+    });
+    const extra = handle.tick();
+    release?.();
+    await extra;
+    await handle.whenIdle();
+    assert.equal(calls, 2);
+    await handle.stop();
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+function maintenanceScheduler(
+  memoryDir: string,
+  flags: { compounding: boolean; weekly: boolean }
+): MaintenanceScheduler {
+  const config = parseConfig({
+    memoryDir,
+    qmdEnabled: false,
+    compoundingEnabled: flags.compounding,
+    compoundingWeeklyCronEnabled: flags.weekly,
+    calibrationEnabled: true,
+  });
+  return new MaintenanceScheduler({
+    config,
+    getQmd: () => ({ isAvailable: () => false }) as unknown as SearchBackend,
+    namespaceSearchRouter: {} as unknown as NamespaceSearchRouter,
+    namespaceCatalog: {} as unknown as NamespaceCatalog,
+  });
+}
+
+test("compoundingWeeklyCronEnabled defaults off and the daemon does not arm the run", async () => {
+  assert.equal(parseConfig({}).compoundingWeeklyCronEnabled, false);
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-weekly-cron-"));
+  try {
+    for (const flags of [
+      { compounding: false, weekly: false },
+      { compounding: true, weekly: false },
+      { compounding: false, weekly: true },
+    ]) {
+      const scheduler = maintenanceScheduler(memoryDir, flags);
+      try {
+        assert.equal(scheduler.armCompoundingWeeklyCron(), false);
+      } finally {
+        await scheduler.dispose();
+      }
+    }
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("the daemon arms synthesizeWeekly, including its calibration pass, for the completed week", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-weekly-cron-"));
+  const weekId = previousIsoWeekId(new Date());
+  const original = CompoundingEngine.prototype.synthesizeWeekly;
+  const calls: Array<string | undefined> = [];
+  const logs: string[] = [];
+  CompoundingEngine.prototype.synthesizeWeekly = async function (opts) {
+    calls.push(opts?.weekId);
+    return original.call(this, opts);
+  };
+  initLogger(
+    {
+      info(msg) {
+        logs.push(String(msg));
+      },
+      warn(msg) {
+        logs.push(String(msg));
+      },
+      error(msg) {
+        logs.push(String(msg));
+      },
+      debug(msg) {
+        logs.push(String(msg));
+      },
+    },
+    true,
+    { timestamps: false }
+  );
+  const scheduler = maintenanceScheduler(memoryDir, { compounding: true, weekly: true });
+  try {
+    assert.equal(scheduler.armCompoundingWeeklyCron(), true);
+    assert.equal(scheduler.armCompoundingWeeklyCron(), true, "arming twice must not start a second runner");
+    await scheduler.dispose();
+    assert.deepEqual(calls, [weekId]);
+    const reportPath = compoundingWeeklyReportPath(memoryDir, weekId);
+    const report = await readFile(reportPath, "utf8");
+    assert.equal(report.includes(weekId), true);
+    const weeklyNames = await readdir(path.dirname(reportPath));
+    assert.equal(weeklyNames.includes(`${weekId}.md`), true);
+    assert.equal(
+      weeklyNames.some((name) => name.endsWith(".tmp")),
+      false,
+      "the completion marker is renamed into place, not left as a partial temp file"
+    );
+    assert.equal(
+      logs.some((line) => line.includes("weekly synthesis produced")),
+      true,
+      "synthesizeWeekly must run the calibration pass"
+    );
+  } finally {
+    CompoundingEngine.prototype.synthesizeWeekly = original;
+    resetLogger();
+    await scheduler.dispose();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("weekly synthesis serializes per memory directory across engines", async () => {
+  const order: string[] = [];
+  let releaseFirst: (() => void) | undefined;
+  const firstGate = new Promise<void>((resolve) => {
+    releaseFirst = resolve;
+  });
+  const first = queueWeeklySynthesis("dir-a", async () => {
+    order.push("first-start");
+    await firstGate;
+    order.push("first-end");
+  });
+  const second = queueWeeklySynthesis("dir-a", async () => {
+    order.push("second-start");
+  });
+  const otherDir = queueWeeklySynthesis("dir-b", async () => {
+    order.push("other-dir-start");
+  });
+
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.deepEqual(order, ["first-start", "other-dir-start"], "same-dir run waits; other dir does not");
+  releaseFirst?.();
+  await Promise.all([first, second, otherDir]);
+  assert.deepEqual(order, ["first-start", "other-dir-start", "first-end", "second-start"]);
+});

package/src/compounding/weekly-scheduler.ts

@@ -0,0 +1,231 @@
+/**
+ * In-process weekly compounding run for the standalone daemon.
+ *
+ * OpenClaw delegate mode registers only memory_search and memory_get, so a
+ * gateway cron can no longer call `compounding_weekly_synthesize`. When both
+ * compounding flags are on, the standalone daemon arms this runner after
+ * its HTTP listener is up. Embedded OpenClaw init does not.
+ *
+ * Each tick synthesizes the ISO week that most recently ended (previous week,
+ * not the in-progress one) by calling `synthesizeWeekly`, which includes
+ * calibration when that gate is on. A scheduler-owned completion marker is
+ * the durable skip signal: only a scheduled run writes it, so a manual
+ * access-surface synthesis of the in-progress week cannot suppress the week's
+ * scheduled run, and a restart does not write a completed week twice. A
+ * daemon that was down at the Monday boundary still writes that missed week
+ * on the next start. Older gaps are left alone — one missed week, not a
+ * history backfill.
+ *
+ * The timer is unref'd. Startup fires one tick immediately; later ticks land
+ * on the next Monday 00:00 UTC. A failed tick remembers that week and retries
+ * it before the newly due week, including after the boundary. That memory is
+ * process-local: a restart still keys off the completion marker.
+ */
+
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+
+import { resolveConsolidationCapabilities } from "../capabilities.js";
+import { writeFileAtomically } from "../maintenance/atomic-file.js";
+import { log as defaultLog } from "../logger.js";
+import type { StorageManager } from "../storage.js";
+import type { PluginConfig } from "../types.js";
+import { CompoundingEngine } from "./engine.js";
+import { isIsoWeekId, msUntilNextIsoWeek, previousIsoWeekId } from "./iso-week.js";
+
+export interface CompoundingWeeklyLog {
+  info(message: string): void;
+  warn(message: string): void;
+  debug(message: string): void;
+}
+
+type TimerHandle = { unref?: () => void };
+
+export interface CompoundingWeeklySchedulerOptions {
+  memoryDir: string;
+  /** Full `synthesizeWeekly` path, including its calibration pass. */
+  synthesizeWeekly: (weekId: string) => Promise<unknown>;
+  now?: () => Date;
+  /** Scheduler-owned completion check: has a scheduled run finished this week? */
+  weekDone?: (weekId: string) => Promise<boolean>;
+  /** Record a scheduled run's completion. Manual access-surface runs never do. */
+  markWeekDone?: (weekId: string) => Promise<void>;
+  setTimer?: (fn: () => void, ms: number) => TimerHandle;
+  clearTimer?: (handle: TimerHandle) => void;
+  log?: CompoundingWeeklyLog;
+}
+
+export type CompoundingWeeklyTick =
+  | { status: "synthesized" | "skipped" | "failed"; weekId: string }
+  | { status: "stopped" | "coalesced"; weekId: null };
+
+export interface CompoundingWeeklySchedulerHandle {
+  /** Run one check now (startup catch-up and tests). */
+  tick(): Promise<CompoundingWeeklyTick>;
+  /** Resolve when no tick is in flight, including a coalesced follow-up. */
+  whenIdle(): Promise<void>;
+  /** Prevent later ticks and wait for the one already running. */
+  stop(): Promise<void>;
+}
+
+export function compoundingWeeklyReportPath(memoryDir: string, weekId: string): string {
+  if (!isIsoWeekId(weekId)) {
+    throw new Error("compounding weekly cron: week id must be YYYY-Www");
+  }
+  return path.join(memoryDir, "compounding", "weekly", `${weekId}.md`);
+}
+
+/**
+ * Completion marker for scheduled runs only. A manual access-surface run can
+ * synthesize the in-progress current week early; its report file must not
+ * satisfy the scheduler's due check, or the evidence added after the manual
+ * run would never reach that week's scheduled synthesis.
+ */
+export function compoundingWeeklyDoneMarkerPath(memoryDir: string, weekId: string): string {
+  if (!isIsoWeekId(weekId)) {
+    throw new Error("compounding weekly cron: week id must be YYYY-Www");
+  }
+  return path.join(memoryDir, "compounding", "weekly", ".scheduler", `${weekId}.done`);
+}
+
+async function defaultWeekDone(memoryDir: string, weekId: string): Promise<boolean> {
+  try {
+    await lstat(compoundingWeeklyDoneMarkerPath(memoryDir, weekId));
+    return true;
+  } catch (error) {
+    if (isNotFound(error)) return false;
+    throw error;
+  }
+}
+
+async function defaultMarkWeekDone(memoryDir: string, weekId: string): Promise<void> {
+  // Atomic: a partially written marker must never satisfy the skip check.
+  await writeFileAtomically(compoundingWeeklyDoneMarkerPath(memoryDir, weekId), `${new Date().toISOString()}\n`);
+}
+
+function isNotFound(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+export function startCompoundingWeeklyScheduler(
+  options: CompoundingWeeklySchedulerOptions
+): CompoundingWeeklySchedulerHandle {
+  const now = options.now ?? (() => new Date());
+  const logger = options.log ?? defaultLog;
+  const weekDone = options.weekDone ?? ((weekId) => defaultWeekDone(options.memoryDir, weekId));
+  const markWeekDone = options.markWeekDone ?? ((weekId) => defaultMarkWeekDone(options.memoryDir, weekId));
+  const setTimer =
+    options.setTimer ??
+    ((fn, ms) => {
+      const timer = setTimeout(fn, ms);
+      timer.unref?.();
+      return timer;
+    });
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle as NodeJS.Timeout));
+
+  let stopped = false;
+  let pending = false;
+  let inFlight: Promise<CompoundingWeeklyTick> | null = null;
+  let timer: TimerHandle | null = null;
+  let retryWeekId: string | null = null;
+
+  const runWeek = async (weekId: string): Promise<CompoundingWeeklyTick> => {
+    try {
+      if (await weekDone(weekId)) {
+        if (retryWeekId === weekId) retryWeekId = null;
+        logger.debug(`compounding weekly cron: ${weekId} already synthesized by the scheduler, skipping`);
+        return { status: "skipped", weekId };
+      }
+      await options.synthesizeWeekly(weekId);
+      await markWeekDone(weekId);
+      logger.info(`compounding weekly cron: synthesized ${weekId}`);
+      return { status: "synthesized", weekId };
+    } catch (error) {
+      retryWeekId = weekId;
+      const name = error instanceof Error ? error.name : "Error";
+      logger.warn(`compounding weekly cron: ${weekId} failed (${name}) — retrying on the next tick`);
+      return { status: "failed", weekId };
+    }
+  };
+
+  const arm = (): void => {
+    if (stopped) return;
+    if (timer) clearTimer(timer);
+    const delay = msUntilNextIsoWeek(now());
+    timer = setTimer(() => {
+      timer = null;
+      if (stopped) return;
+      arm();
+      void request();
+    }, delay);
+    timer.unref?.();
+  };
+
+  const doTick = async (): Promise<CompoundingWeeklyTick> => {
+    const due = previousIsoWeekId(now());
+    const weekId = retryWeekId ?? due;
+    const first = await runWeek(weekId);
+    if (first.status === "failed" || weekId === due) return first;
+    return runWeek(due);
+  };
+
+  const request = (): Promise<CompoundingWeeklyTick> => {
+    if (stopped) return Promise.resolve({ status: "stopped", weekId: null });
+    if (inFlight) {
+      pending = true;
+      return inFlight.then(() => ({ status: "coalesced" as const, weekId: null }));
+    }
+    const run = doTick().finally(() => {
+      inFlight = null;
+      if (!stopped && pending) {
+        pending = false;
+        void request();
+      }
+    });
+    inFlight = run;
+    return run;
+  };
+
+  arm();
+  void request();
+
+  return {
+    tick: () => request(),
+    async whenIdle() {
+      while (inFlight) await inFlight;
+    },
+    async stop() {
+      stopped = true;
+      pending = false;
+      if (timer) clearTimer(timer);
+      timer = null;
+      while (inFlight) await inFlight;
+    },
+  };
+}
+
+/**
+ * Arm the daemon weekly run when both compounding flags are on.
+ * Returns null when the run stays off or arming fails. The returned handle's
+ * first tick is already in flight and includes calibration via synthesizeWeekly.
+ */
+export function createCompoundingWeeklyCron(deps: {
+  config: PluginConfig;
+  getStorage?: () => StorageManager | undefined;
+}): CompoundingWeeklySchedulerHandle | null {
+  const caps = resolveConsolidationCapabilities(deps.config);
+  if (!caps.compounding || !caps.compoundingWeeklyCron) return null;
+  try {
+    const engine = new CompoundingEngine(deps.config, deps.getStorage?.());
+    const handle = startCompoundingWeeklyScheduler({
+      memoryDir: deps.config.memoryDir,
+      synthesizeWeekly: (weekId) => engine.synthesizeWeekly({ weekId }),
+    });
+    defaultLog.info("compounding weekly cron armed");
+    return handle;
+  } catch (error) {
+    const name = error instanceof Error ? error.name : "Error";
+    defaultLog.warn(`compounding weekly cron failed to arm (${name}) — non-fatal`);
+    return null;
+  }
+}

package/src/compounding/weekly-synthesis-queue.ts

@@ -0,0 +1,23 @@
+/**
+ * Single-flight boundary for weekly synthesis, keyed by memory directory.
+ * The daemon scheduler and the access surface each drive their own engine
+ * instance against the same files; without serialization, concurrent
+ * read-modify-write of mistakes.json, rubrics, and the calibration index
+ * would let the last finisher discard the other run's updates.
+ */
+
+const weeklySynthesisTails = new Map<string, Promise<void>>();
+
+export function queueWeeklySynthesis<T>(memoryDir: string, run: () => Promise<T>): Promise<T> {
+  const prior = weeklySynthesisTails.get(memoryDir);
+  const next = prior === undefined ? run() : prior.then(run, run);
+  const tail = next.then(
+    () => undefined,
+    () => undefined
+  );
+  weeklySynthesisTails.set(memoryDir, tail);
+  void tail.then(() => {
+    if (weeklySynthesisTails.get(memoryDir) === tail) weeklySynthesisTails.delete(memoryDir);
+  });
+  return next;
+}