@remnic/core 10.0.12 → 10.0.14

package/src/compounding/engine.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { isoWeekId } from "./iso-week.js";
+import { cadenceStaleWindowMs, isoWeekId } from "./iso-week.js";
 import { log } from "../logger.js";
 import { composeSalvagedEnvelope } from "../salvage-envelope.js";
 import { sanitizeMemoryContent } from "../sanitize.js";
@@ -11,6 +11,7 @@ import { migrateLegacyFeedbackInbox, resolveFeedbackInboxPath, type SharedFeedba
 import { parseContinuityImprovementLoops } from "../identity-continuity.js";
 import { resolveQmdCapabilities, type QmdConfigProjection, resolveConsolidationCapabilities } from "../capabilities.js";
 import { resolveConversationContextCapabilities } from "../capabilities.js";
+import { writeFileAtomically } from "../maintenance/atomic-file.js";
 import {
   actionEventsVisibleInStore, capWeeklyPatternDetails,
   buildActionFailurePatterns,
@@ -24,6 +25,7 @@ import {
   type WeeklyActionEvent,
   type WeeklyCorrectionEvidence,
 } from "./weekly-evidence.js";
+import { queueWeeklySynthesis } from "./weekly-synthesis-queue.js";
 
 type MistakesFile = {
   version?: number;
@@ -422,20 +424,18 @@ function monthIdFromIsoWeek(weekId: string): string {
   return isoMonthId(monday);
 }
 
-function cadenceStaleWindowMs(cadence: "daily" | "weekly" | "monthly" | "quarterly"): number {
-  switch (cadence) {
-    case "daily":
-      return 2 * 24 * 60 * 60 * 1000;
-    case "weekly":
-      return 10 * 24 * 60 * 60 * 1000;
-    case "monthly":
-      return 45 * 24 * 60 * 60 * 1000;
-    case "quarterly":
-      return 120 * 24 * 60 * 60 * 1000;
-    default:
-      return 45 * 24 * 60 * 60 * 1000;
-  }
-}
+export type WeeklySynthesisOptions = { weekId?: string };
+
+export type WeeklySynthesisResult = {
+  weekId: string;
+  reportPath: string;
+  reportJsonPath: string;
+  mistakesCount: number;
+  rubricsPath: string;
+  rubricsIndexPath: string;
+  promotionCandidateCount: number;
+};
+
 
 export class CompoundingEngine {
   private readonly weeklyDir: string;
@@ -474,17 +474,12 @@ export class CompoundingEngine {
     await mkdir(this.rubricsWorkflowsDir, { recursive: true });
   }
 
-  async synthesizeWeekly(opts?: {
-    weekId?: string;
-  }): Promise<{
-    weekId: string;
-    reportPath: string;
-    reportJsonPath: string;
-    mistakesCount: number;
-    rubricsPath: string;
-    rubricsIndexPath: string;
-    promotionCandidateCount: number;
-  }> {
+  /** Serialized per memory directory — see weekly-synthesis-queue.ts. */
+  async synthesizeWeekly(opts?: WeeklySynthesisOptions): Promise<WeeklySynthesisResult> {
+    return await queueWeeklySynthesis(this.config.memoryDir, () => this.synthesizeWeeklyExclusive(opts));
+  }
+
+  private async synthesizeWeeklyExclusive(opts?: WeeklySynthesisOptions): Promise<WeeklySynthesisResult> {
     await this.ensureDirs();
     const weekId = opts?.weekId ?? isoWeekId(new Date());
 
@@ -559,11 +554,16 @@ export class CompoundingEngine {
         log.warn(`[cmc] causal consolidation in synthesizeWeekly failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);
       }
     }
-    // PEDC: Run calibration consolidation during weekly synthesis
-    if (resolveConsolidationCapabilities(this.config).calibration) {
+    // PEDC: calibration consolidation, keyed by the week id so a retry does
+    // not reinforce the same rules. Only a completed week consolidates: a
+    // manual in-progress-week run must not double-count partial evidence.
+    if (resolveConsolidationCapabilities(this.config).calibration && weekId < isoWeekId(new Date())) {
       try {
         const { calibrationConsolidationInput, runCalibrationConsolidation } = await import("../calibration.js");
-        const calRules = await runCalibrationConsolidation(calibrationConsolidationInput(this.config));
+        const calRules = await runCalibrationConsolidation({
+          ...calibrationConsolidationInput(this.config),
+          idempotencyKey: weekId,
+        });
         log.debug(`[calibration] weekly synthesis produced ${calRules.length} calibration rule(s)`);
       } catch (error) {
         log.warn(`[calibration] weekly consolidation failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);
@@ -573,10 +573,10 @@ export class CompoundingEngine {
       ? await this.readContinuityAuditReferences(weekId)
       : { monthId: monthIdFromIsoWeek(weekId), weeklyPath: null, monthlyPath: null };
 
-    // Write weekly report (always, even if empty: "day-one outcomes").
+    // The markdown report is the completion marker, so it is written after the
+    // JSON, rubrics, and mistakes artifacts. A crash before that write retries.
     const reportPath = path.join(this.weeklyDir, `${weekId}.md`);
     const md = this.formatWeeklyReport(weekId, entries, mistakes.patterns, mistakes.details, continuity, outcomeSummary, promotionCandidates);
-    await writeFile(reportPath, md, "utf-8");
 
     const reportJsonPath = path.join(this.weeklyDir, `${weekId}.json`);
     const weeklyArtifact: WeeklyCompoundingArtifact = {
@@ -633,6 +633,7 @@ export class CompoundingEngine {
       }, null, 2) + "\n",
       "utf-8",
     );
+    await writeFileAtomically(reportPath, md);
 
     log.info(
       `compounding: wrote weekly=${reportPath} weeklyJson=${reportJsonPath} rubrics=${this.rubricsPath} rubricsIndex=${this.rubricsIndexPath} mistakes=${this.mistakesPath}`,

package/src/compounding/iso-week.ts

@@ -58,3 +58,19 @@ export function isIsoWeekId(weekId: string): boolean {
   const weekNum = Number(week);
   return weekNum >= 1 && weekNum <= 53;
 }
+
+/** How long a rubric cadence may go unreviewed before it counts as stale. */
+export function cadenceStaleWindowMs(cadence: "daily" | "weekly" | "monthly" | "quarterly"): number {
+  switch (cadence) {
+    case "daily":
+      return 2 * 24 * 60 * 60 * 1000;
+    case "weekly":
+      return 10 * 24 * 60 * 60 * 1000;
+    case "monthly":
+      return 45 * 24 * 60 * 60 * 1000;
+    case "quarterly":
+      return 120 * 24 * 60 * 60 * 1000;
+    default:
+      return 45 * 24 * 60 * 60 * 1000;
+  }
+}

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"]);
+});